@kumix/storage 0.1.0

package/dist/helpers.d.ts

@@ -0,0 +1,764 @@
+//#region src/helpers.d.ts
+/**
+ * Storage helper utilities
+ * Provides utility functions for file operations, MIME type detection, and path manipulation
+ */
+/**
+ * Generate a unique file key with timestamp and random string
+ * @param originalName Original file name
+ * @param prefix Optional prefix for the key
+ * @returns Unique file key
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { generateFileKey } from '@kumix/storage/helpers';
+ *
+ * const key1 = generateFileKey('document.pdf');
+ * // Returns: "document-1703123456789-abc123.pdf"
+ *
+ * const key2 = generateFileKey('photo.jpg', 'uploads/images');
+ * // Returns: "uploads/images/photo-1703123456789-def456.jpg"
+ * ```
+ */
+declare function generateFileKey(originalName: string, prefix?: string): string;
+/**
+ * Get MIME type from file name or extension
+ * @param fileName File name or path
+ * @returns MIME type string
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getMimeType } from '@kumix/storage/helpers';
+ *
+ * const type1 = getMimeType('document.pdf');
+ * // Returns: "application/pdf"
+ *
+ * const type2 = getMimeType('photo.jpg');
+ * // Returns: "image/jpeg"
+ *
+ * const type3 = getMimeType('unknown.xyz');
+ * // Returns: "application/octet-stream"
+ * ```
+ */
+declare function getMimeType(fileName: string): string;
+/**
+ * Validate file size against maximum allowed size
+ * @param fileSize File size in bytes
+ * @param maxSize Maximum allowed size in bytes
+ * @returns Validation result with error message if invalid
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { validateFileSize } from '@kumix/storage/helpers';
+ *
+ * const result1 = validateFileSize(1024 * 1024, 5 * 1024 * 1024); // 1MB vs 5MB limit
+ * // Returns: { valid: true }
+ *
+ * const result2 = validateFileSize(10 * 1024 * 1024, 5 * 1024 * 1024); // 10MB vs 5MB limit
+ * // Returns: { valid: false, error: "File size 10 MB exceeds maximum allowed size 5 MB" }
+ * ```
+ */
+declare function validateFileSize(fileSize: number, maxSize: number): {
+  valid: boolean;
+  error?: string;
+};
+/**
+ * Validate file type against allowed types (MIME types or extensions)
+ * @param fileName File name or path
+ * @param allowedTypes Array of allowed MIME types or file extensions
+ * @returns Validation result with error message if invalid
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { validateFileType } from '@kumix/storage/helpers';
+ *
+ * // Using MIME types
+ * const result1 = validateFileType('photo.jpg', ['image/*', 'application/pdf']);
+ * // Returns: { valid: true }
+ *
+ * // Using file extensions
+ * const result2 = validateFileType('document.txt', ['.pdf', '.doc', '.docx']);
+ * // Returns: { valid: false, error: "File type not allowed. Allowed types: .pdf, .doc, .docx" }
+ *
+ * // Mixed MIME types and extensions
+ * const result3 = validateFileType('video.mp4', ['image/*', '.pdf', 'video/mp4']);
+ * // Returns: { valid: true }
+ * ```
+ */
+declare function validateFileType(fileName: string, allowedTypes: string[]): {
+  valid: boolean;
+  error?: string;
+};
+/**
+ * Format file size in human readable format
+ * @param bytes File size in bytes
+ * @returns Formatted file size string
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { formatFileSize } from '@kumix/storage/helpers';
+ *
+ * const size1 = formatFileSize(1024);
+ * // Returns: "1 KB"
+ *
+ * const size2 = formatFileSize(1048576);
+ * // Returns: "1 MB"
+ *
+ * const size3 = formatFileSize(1073741824);
+ * // Returns: "1 GB"
+ * ```
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * Sanitize file name for S3 key by removing special characters
+ * @param fileName Original file name
+ * @returns Sanitized file name safe for S3 keys
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { sanitizeFileName } from '@kumix/storage/helpers';
+ *
+ * const safe1 = sanitizeFileName('My Document (2023).pdf');
+ * // Returns: "my_document_2023.pdf"
+ *
+ * const safe2 = sanitizeFileName('file@#$%name.txt');
+ * // Returns: "file_name.txt"
+ * ```
+ */
+declare function sanitizeFileName(fileName: string): string;
+/**
+ * Extract file extension from file name
+ * @param fileName File name or path
+ * @returns File extension with dot (e.g., '.pdf')
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getFileExtension } from '@kumix/storage/helpers';
+ *
+ * const ext1 = getFileExtension('document.pdf');
+ * // Returns: ".pdf"
+ *
+ * const ext2 = getFileExtension('photo.JPEG');
+ * // Returns: ".jpeg"
+ *
+ * const ext3 = getFileExtension('noextension');
+ * // Returns: ""
+ * ```
+ */
+declare function getFileExtension(fileName: string): string;
+/**
+ * Generate cache control header for HTTP responses
+ * @param maxAge Cache max age in seconds (default: 1 year)
+ * @param isPublic Whether cache should be public or private
+ * @returns Cache control header string
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { generateCacheControl } from '@kumix/storage/helpers';
+ *
+ * const cache1 = generateCacheControl();
+ * // Returns: "public, max-age=31536000"
+ *
+ * const cache2 = generateCacheControl(3600, false);
+ * // Returns: "private, max-age=3600"
+ *
+ * const cache3 = generateCacheControl(86400); // 1 day
+ * // Returns: "public, max-age=86400"
+ * ```
+ */
+declare function generateCacheControl(maxAge?: number, // 1 year default
+isPublic?: boolean): string;
+/**
+ * Parse S3 URL to extract bucket and key
+ * @param url S3 URL to parse
+ * @returns Object containing bucket and key
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { parseS3Url } from '@kumix/storage/helpers';
+ *
+ * // Virtual hosted-style URL
+ * const result1 = parseS3Url('https://my-bucket.s3.us-east-1.amazonaws.com/folder/file.pdf');
+ * // Returns: { bucket: "my-bucket", key: "folder/file.pdf" }
+ *
+ * // Path-style URL
+ * const result2 = parseS3Url('https://s3.us-east-1.amazonaws.com/my-bucket/folder/file.pdf');
+ * // Returns: { bucket: "my-bucket", key: "folder/file.pdf" }
+ *
+ * // Custom endpoint (R2, MinIO)
+ * const result3 = parseS3Url('https://my-endpoint.com/my-bucket/folder/file.pdf');
+ * // Returns: { bucket: "my-bucket", key: "folder/file.pdf" }
+ * ```
+ */
+declare function parseS3Url(url: string): {
+  bucket?: string;
+  key?: string;
+};
+/**
+ * Build public URL for a file
+ * @param baseUrl Base URL of the storage service
+ * @param bucket Bucket name
+ * @param key File key/path
+ * @returns Complete public URL
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { buildPublicUrl } from '@kumix/storage/helpers';
+ *
+ * const url1 = buildPublicUrl('https://cdn.example.com', 'my-bucket', 'folder/file.pdf');
+ * // Returns: "https://cdn.example.com/my-bucket/folder/file.pdf"
+ *
+ * const url2 = buildPublicUrl('https://storage.example.com/', 'assets', 'images/logo.png');
+ * // Returns: "https://storage.example.com/assets/images/logo.png"
+ * ```
+ */
+declare function buildPublicUrl(baseUrl: string, bucket: string, key: string, supabase?: boolean): string;
+/**
+ * Validate S3 key format according to AWS S3 naming rules
+ * @param key S3 object key to validate
+ * @returns Validation result with error message if invalid
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { validateS3Key } from '@kumix/storage/helpers';
+ *
+ * const result1 = validateS3Key('documents/report.pdf');
+ * // Returns: { valid: true }
+ *
+ * const result2 = validateS3Key('/invalid/key/');
+ * // Returns: { valid: false, error: "Key cannot start or end with forward slash" }
+ * ```
+ */
+declare function validateS3Key(key: string): {
+  valid: boolean;
+  error?: string;
+};
+/**
+ * Convert File object to Buffer for upload
+ * @param file File object from browser input
+ * @returns Promise that resolves to Buffer
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { fileToBuffer } from '@kumix/storage/helpers';
+ *
+ * // In browser with file input
+ * const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+ * const file = fileInput.files?.[0];
+ *
+ * if (file) {
+ *   const buffer = await fileToBuffer(file);
+ *   // Use buffer for upload
+ *   await storage.uploadFile('uploads/file.pdf', buffer);
+ * }
+ * ```
+ */
+declare function fileToBuffer(file: File): Promise<Uint8Array>;
+/**
+ * Get file information from File object
+ * @param file File object from browser input
+ * @returns Object containing file metadata
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getFileInfo } from '@kumix/storage/helpers';
+ *
+ * // In browser with file input
+ * const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+ * const file = fileInput.files?.[0];
+ *
+ * if (file) {
+ *   const info = getFileInfo(file);
+ *   console.log(info);
+ *   // Returns: {
+ *   //   name: "document.pdf",
+ *   //   size: 1048576,
+ *   //   type: "application/pdf",
+ *   //   lastModified: Date
+ *   // }
+ * }
+ * ```
+ */
+declare function getFileInfo(file: File): {
+  name: string;
+  size: number;
+  type: string;
+  lastModified: Date;
+};
+/**
+ * Generate unique key with prefix and timestamp
+ * @param fileName Original file name
+ * @param prefix Optional prefix for the key
+ * @param includeTimestamp Whether to include timestamp for uniqueness
+ * @returns Unique file key
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { generateUniqueKey } from '@kumix/storage/helpers';
+ *
+ * const key1 = generateUniqueKey('report.pdf', 'documents');
+ * // Returns: "documents/report-1703123456789-abc123.pdf"
+ *
+ * const key2 = generateUniqueKey('photo.jpg', 'images', false);
+ * // Returns: "images/photo.jpg"
+ * ```
+ */
+declare function generateUniqueKey(fileName: string, prefix?: string, includeTimestamp?: boolean): string;
+/**
+ * Extract bucket, key, and region from S3 URL
+ * @param url S3 URL to parse
+ * @returns Object containing bucket, key, and region information
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { extractS3Info } from '@kumix/storage/helpers';
+ *
+ * // AWS S3 virtual hosted-style
+ * const result1 = extractS3Info('https://my-bucket.s3.us-west-2.amazonaws.com/folder/file.pdf');
+ * // Returns: { bucket: "my-bucket", key: "folder/file.pdf", region: "us-west-2" }
+ *
+ * // AWS S3 path-style
+ * const result2 = extractS3Info('https://s3.eu-central-1.amazonaws.com/my-bucket/file.pdf');
+ * // Returns: { bucket: "my-bucket", key: "file.pdf", region: "eu-central-1" }
+ *
+ * // Custom endpoint
+ * const result3 = extractS3Info('https://minio.example.com/my-bucket/folder/file.pdf');
+ * // Returns: { bucket: "my-bucket", key: "folder/file.pdf" }
+ * ```
+ */
+declare function extractS3Info(url: string): {
+  bucket?: string;
+  key?: string;
+  region?: string;
+};
+/**
+ * Validate S3 configuration object
+ * @param config S3 configuration object to validate
+ * @returns Validation result with list of errors
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { validateS3Config } from '@kumix/storage/helpers';
+ *
+ * const config = {
+ *   provider: 'aws',
+ *   region: 'us-east-1',
+ *   bucket: 'my-bucket',
+ *   accessKeyId: 'AKIA...',
+ *   secretAccessKey: 'secret...'
+ * };
+ *
+ * const result = validateS3Config(config);
+ * // Returns: { valid: true, errors: [] }
+ *
+ * const invalidConfig = { provider: 'aws' }; // Missing required fields
+ * const result2 = validateS3Config(invalidConfig);
+ * // Returns: { valid: false, errors: ["Region is required", "Bucket is required", ...] }
+ * ```
+ */
+declare function validateS3Config(config: Record<string, unknown>): {
+  valid: boolean;
+  errors: string[];
+};
+/**
+ * Validate S3 bucket name according to AWS naming rules
+ * @param bucketName Bucket name to validate
+ * @returns Validation result with error message if invalid
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { validateBucketName } from '@kumix/storage/helpers';
+ *
+ * const result1 = validateBucketName('my-valid-bucket');
+ * // Returns: { valid: true }
+ *
+ * const result2 = validateBucketName('My-Invalid-Bucket');
+ * // Returns: { valid: false, error: "Bucket name can only contain lowercase letters, numbers, dots, and hyphens" }
+ *
+ * const result3 = validateBucketName('ab');
+ * // Returns: { valid: false, error: "Bucket name must be between 3 and 63 characters" }
+ * ```
+ */
+declare function validateBucketName(bucketName: string): {
+  valid: boolean;
+  error?: string;
+};
+/**
+ * Generate content disposition header for file downloads
+ * @param fileName File name for the download
+ * @param disposition Whether to display inline or as attachment
+ * @returns Content disposition header string
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getContentDisposition } from '@kumix/storage/helpers';
+ *
+ * const header1 = getContentDisposition('document.pdf');
+ * // Returns: 'attachment; filename="document.pdf"'
+ *
+ * const header2 = getContentDisposition('image.jpg', 'inline');
+ * // Returns: 'inline; filename="image.jpg"'
+ *
+ * const header3 = getContentDisposition('file@#$name.txt');
+ * // Returns: 'attachment; filename="filename.txt"'
+ * ```
+ */
+declare function getContentDisposition(fileName: string, disposition?: "inline" | "attachment"): string;
+/**
+ * Check if file is an image based on MIME type
+ * @param fileName File name or path
+ * @returns True if file is an image
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { isImageFile } from '@kumix/storage/helpers';
+ *
+ * const result1 = isImageFile('photo.jpg');
+ * // Returns: true
+ *
+ * const result2 = isImageFile('document.pdf');
+ * // Returns: false
+ * ```
+ */
+declare function isImageFile(fileName: string): boolean;
+/**
+ * Check if file is a video based on MIME type
+ * @param fileName File name or path
+ * @returns True if file is a video
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { isVideoFile } from '@kumix/storage/helpers';
+ *
+ * const result1 = isVideoFile('movie.mp4');
+ * // Returns: true
+ *
+ * const result2 = isVideoFile('document.pdf');
+ * // Returns: false
+ * ```
+ */
+declare function isVideoFile(fileName: string): boolean;
+/**
+ * Check if file is an audio file based on MIME type
+ * @param fileName File name or path
+ * @returns True if file is an audio file
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { isAudioFile } from '@kumix/storage/helpers';
+ *
+ * const result1 = isAudioFile('song.mp3');
+ * // Returns: true
+ *
+ * const result2 = isAudioFile('document.pdf');
+ * // Returns: false
+ * ```
+ */
+declare function isAudioFile(fileName: string): boolean;
+/**
+ * Check if file is a document based on MIME type
+ * @param fileName File name or path
+ * @returns True if file is a document
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { isDocumentFile } from '@kumix/storage/helpers';
+ *
+ * const result1 = isDocumentFile('report.pdf');
+ * // Returns: true
+ *
+ * const result2 = isDocumentFile('spreadsheet.xlsx');
+ * // Returns: true
+ *
+ * const result3 = isDocumentFile('photo.jpg');
+ * // Returns: false
+ * ```
+ */
+declare function isDocumentFile(fileName: string): boolean;
+/**
+ * Normalize path separators and remove redundant slashes
+ * @param path Path to normalize
+ * @returns Normalized path
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { normalizePath } from '@kumix/storage/helpers';
+ *
+ * const path1 = normalizePath('folder//subfolder///file.txt');
+ * // Returns: "folder/subfolder/file.txt"
+ *
+ * const path2 = normalizePath('\\folder\\file.txt');
+ * // Returns: "folder/file.txt"
+ *
+ * const path3 = normalizePath('/folder/file.txt/');
+ * // Returns: "folder/file.txt"
+ * ```
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Join path segments safely with proper separators
+ * @param segments Path segments to join
+ * @returns Joined path
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { joinPath } from '@kumix/storage/helpers';
+ *
+ * const path1 = joinPath('folder', 'subfolder', 'file.txt');
+ * // Returns: "folder/subfolder/file.txt"
+ *
+ * const path2 = joinPath('/folder/', '/subfolder/', '/file.txt/');
+ * // Returns: "folder/subfolder/file.txt"
+ *
+ * const path3 = joinPath('', 'folder', '', 'file.txt');
+ * // Returns: "folder/file.txt"
+ * ```
+ */
+declare function joinPath(...segments: string[]): string;
+/**
+ * Get parent directory path from a file key
+ * @param key File key or path
+ * @returns Parent directory path
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getParentPath } from '@kumix/storage/helpers';
+ *
+ * const parent1 = getParentPath('folder/subfolder/file.txt');
+ * // Returns: "folder/subfolder"
+ *
+ * const parent2 = getParentPath('file.txt');
+ * // Returns: ""
+ *
+ * const parent3 = getParentPath('folder/file.txt');
+ * // Returns: "folder"
+ * ```
+ */
+declare function getParentPath(key: string): string;
+/**
+ * Get filename from a file key or path
+ * @param key File key or path
+ * @returns Filename without path
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getFileName } from '@kumix/storage/helpers';
+ *
+ * const name1 = getFileName('folder/subfolder/document.pdf');
+ * // Returns: "document.pdf"
+ *
+ * const name2 = getFileName('file.txt');
+ * // Returns: "file.txt"
+ *
+ * const name3 = getFileName('folder/subfolder/');
+ * // Returns: ""
+ * ```
+ */
+declare function getFileName(key: string): string;
+/**
+ * Convert base64 string to Buffer
+ * @param base64 Base64 encoded string
+ * @returns Buffer containing the decoded data
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { base64ToBuffer } from '@kumix/storage/helpers';
+ *
+ * const base64 = 'SGVsbG8gV29ybGQ='; // "Hello World" in base64
+ * const buffer = base64ToBuffer(base64);
+ * console.log(buffer.toString()); // "Hello World"
+ *
+ * // For file uploads from base64 data
+ * const imageBase64 = 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...';
+ * const cleanBase64 = imageBase64.split(',')[1]; // Remove data URL prefix
+ * const imageBuffer = base64ToBuffer(cleanBase64);
+ * await storage.uploadFile('images/photo.jpg', imageBuffer);
+ * ```
+ */
+declare function base64ToBuffer(base64: string): Uint8Array;
+/**
+ * Convert Buffer to base64 string
+ * @param buffer Buffer to encode
+ * @param includeDataUrl Whether to include data URL prefix
+ * @param mimeType MIME type for data URL (required if includeDataUrl is true)
+ * @returns Base64 encoded string
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { bufferToBase64 } from '@kumix/storage/helpers';
+ *
+ * const buffer = Buffer.from('Hello World');
+ * const base64 = bufferToBase64(buffer);
+ * // Returns: "SGVsbG8gV29ybGQ="
+ *
+ * // With data URL for images
+ * const imageBuffer = await storage.downloadFile('images/photo.jpg');
+ * const dataUrl = bufferToBase64(imageBuffer.content!, true, 'image/jpeg');
+ * // Returns: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
+ *
+ * // Use in HTML img tag
+ * document.querySelector('img').src = dataUrl;
+ * ```
+ */
+declare function bufferToBase64(buffer: Uint8Array, includeDataUrl?: boolean, mimeType?: string): string;
+/**
+ * Generate file hash/checksum for integrity verification
+ * @param content File content as Buffer or string
+ * @param algorithm Hash algorithm to use
+ * @returns Hash string
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { generateFileHash } from '@kumix/storage/helpers';
+ *
+ * const content = Buffer.from('Hello World');
+ *
+ * const md5Hash = generateFileHash(content, 'md5');
+ * // Returns: "b10a8db164e0754105b7a99be72e3fe5"
+ *
+ * const sha256Hash = generateFileHash(content, 'sha256');
+ * // Returns: "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e"
+ *
+ * // For file integrity checking
+ * const fileBuffer = await storage.downloadFile('document.pdf');
+ * const currentHash = generateFileHash(fileBuffer.content!, 'sha256');
+ * const expectedHash = 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e';
+ *
+ * if (currentHash === expectedHash) {
+ *   console.log('File integrity verified');
+ * } else {
+ *   console.log('File may be corrupted');
+ * }
+ * ```
+ */
+declare function generateFileHash(content: Uint8Array | string, algorithm?: "md5" | "sha1" | "sha256"): Promise<string>;
+/**
+ * Generate multiple unique keys at once for batch operations
+ * @param fileNames Array of file names
+ * @param prefix Optional prefix for all keys
+ * @returns Array of unique keys
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { generateBatchKeys } from '@kumix/storage/helpers';
+ *
+ * const fileNames = ['document1.pdf', 'document2.pdf', 'image.jpg'];
+ * const keys = generateBatchKeys(fileNames, 'uploads');
+ * // Returns: [
+ * //   "uploads/document1-1703123456789-abc123.pdf",
+ * //   "uploads/document2-1703123456790-def456.pdf",
+ * //   "uploads/image-1703123456791-ghi789.jpg"
+ * // ]
+ *
+ * // Use for batch uploads
+ * const files = [file1, file2, file3];
+ * const keys = generateBatchKeys(files.map(f => f.name), 'batch-upload');
+ *
+ * for (let i = 0; i < files.length; i++) {
+ *   await storage.uploadFile(keys[i], files[i]);
+ * }
+ * ```
+ */
+declare function generateBatchKeys(fileNames: string[], prefix?: string): string[];
+/**
+ * Validate multiple files at once with consistent options
+ * @param files Array of File objects to validate
+ * @param options Validation options
+ * @returns Array of validation results
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { validateBatchFiles } from '@kumix/storage/helpers';
+ *
+ * const files = [file1, file2, file3]; // File objects from input
+ * const options = {
+ *   maxSize: 5 * 1024 * 1024, // 5MB
+ *   allowedTypes: ['image/*', 'application/pdf'],
+ *   maxFiles: 10
+ * };
+ *
+ * const results = validateBatchFiles(files, options);
+ * // Returns: [
+ * //   { valid: true, fileName: "image.jpg" },
+ * //   { valid: false, fileName: "large.pdf", errors: ["File size exceeds limit"] },
+ * //   { valid: true, fileName: "document.pdf" }
+ * // ]
+ *
+ * const validFiles = files.filter((_, index) => results[index].valid);
+ * const invalidFiles = files.filter((_, index) => !results[index].valid);
+ * ```
+ */
+declare function validateBatchFiles(files: File[], options: {
+  maxSize?: number;
+  allowedTypes?: string[];
+  maxFiles?: number;
+}): Array<{
+  valid: boolean;
+  fileName: string;
+  errors?: string[];
+}>;
+/**
+ * Detect file type from content using magic numbers/file signatures
+ * @param buffer File content buffer
+ * @returns Detected MIME type or 'application/octet-stream' if unknown
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { detectFileTypeFromContent } from '@kumix/storage/helpers';
+ *
+ * // Read file content
+ * const fileBuffer = await storage.downloadFile('unknown-file');
+ * const detectedType = detectFileTypeFromContent(fileBuffer.content!);
+ *
+ * console.log(detectedType);
+ * // Returns: "image/jpeg" for JPEG files
+ * // Returns: "application/pdf" for PDF files
+ * // Returns: "image/png" for PNG files
+ * // Returns: "application/octet-stream" for unknown types
+ *
+ * // Verify file type matches extension
+ * const fileName = 'document.pdf';
+ * const expectedType = getMimeType(fileName);
+ * const actualType = detectFileTypeFromContent(fileBuffer.content!);
+ *
+ * if (expectedType !== actualType) {
+ *   console.warn('File extension does not match content type');
+ * }
+ * ```
+ */
+declare function detectFileTypeFromContent(buffer: Uint8Array): string;
+//#endregion
+export { base64ToBuffer, bufferToBase64, buildPublicUrl, detectFileTypeFromContent, extractS3Info, fileToBuffer, formatFileSize, generateBatchKeys, generateCacheControl, generateFileHash, generateFileKey, generateUniqueKey, getContentDisposition, getFileExtension, getFileInfo, getFileName, getMimeType, getParentPath, isAudioFile, isDocumentFile, isImageFile, isVideoFile, joinPath, normalizePath, parseS3Url, sanitizeFileName, validateBatchFiles, validateBucketName, validateFileSize, validateFileType, validateS3Config, validateS3Key };
+//# sourceMappingURL=helpers.d.ts.map