/**
 * ============================================================================
 * FILE OPERATION UTILITIES
 * ============================================================================
 *
 * Framework-agnostic utilities for common file operations:
 * - Base64 encoding/decoding
 * - Blob creation and download triggering
 * - File key parsing
 * - Filename generation
 *
 * These utilities work in both browser and Node.js environments.
 */
import { type ParsedFileKey } from '@plyaz/types/core';
/**
 * Convert a File to base64 string (browser only).
 *
 * @param file - The File object to convert
 * @returns Promise resolving to base64 encoded string (without data URL prefix)
 *
 * @example
 * ```typescript
 * const base64 = await fileToBase64(file);
 * // Use for API upload
 * ```
 */
export declare function fileToBase64(file: File): Promise<string>;
/**
 * Convert a base64 string to a Blob (browser only).
 *
 * @param base64 - The base64 encoded string
 * @param mimeType - The MIME type for the blob (default: 'application/octet-stream')
 * @returns A Blob containing the decoded data
 *
 * @example
 * ```typescript
 * const blob = base64ToBlob(downloadResult.buffer, 'application/pdf');
 * downloadBlob(blob, 'document.pdf');
 * ```
 */
export declare function base64ToBlob(base64: string, mimeType?: string): Blob;
/**
 * Convert a base64 string to a Buffer (Node.js only).
 *
 * @param base64 - The base64 encoded string
 * @returns A Buffer containing the decoded data
 *
 * @example
 * ```typescript
 * const buffer = base64ToBuffer(encodedData);
 * fs.writeFileSync('output.pdf', buffer);
 * ```
 */
export declare function base64ToBuffer(base64: string): Buffer;
/**
 * Convert a Buffer or Uint8Array to a base64 string.
 *
 * @param data - The binary data to encode
 * @returns The base64 encoded string
 *
 * @example
 * ```typescript
 * const base64 = bufferToBase64(fileBuffer);
 * ```
 */
export declare function bufferToBase64(data: Buffer | Uint8Array): string;
/**
 * Trigger a browser download of a Blob.
 *
 * Creates a temporary anchor element to trigger the download,
 * then cleans up the object URL.
 *
 * @param blob - The Blob to download
 * @param filename - The filename to save as
 *
 * @example
 * ```typescript
 * const blob = base64ToBlob(data, 'application/pdf');
 * downloadBlob(blob, 'invoice.pdf');
 * ```
 */
export declare function downloadBlob(blob: Blob, filename: string): void;
/**
 * Download a base64-encoded file in the browser.
 * Combines base64ToBlob and downloadBlob for convenience.
 *
 * @param base64 - The base64 encoded data
 * @param filename - The filename to save as
 * @param mimeType - The MIME type (default: 'application/octet-stream')
 *
 * @example
 * ```typescript
 * downloadBase64(response.data, 'report.pdf', 'application/pdf');
 * ```
 */
export declare function downloadBase64(base64: string, filename: string, mimeType?: string): void;
/**
 * Parse a storage file key into its components.
 *
 * Supports various key formats:
 * - `entityType/entityId/category/filename`
 * - `entityType/entityId/filename`
 * - `category/filename`
 * - `filename`
 *
 * @param key - The storage key to parse
 * @returns Parsed components
 *
 * @example
 * ```typescript
 * const parsed = parseFileKey('user/123/documents/invoice.pdf');
 * // { entityType: 'user', entityId: '123', category: 'documents', filename: 'invoice.pdf' }
 * ```
 */
export declare function parseFileKey(key: string): ParsedFileKey;
/**
 * Extract just the filename from a file key or path.
 *
 * @param key - The file key or path
 * @returns The filename portion
 *
 * @example
 * ```typescript
 * getFilenameFromKey('user/123/docs/invoice.pdf'); // 'invoice.pdf'
 * ```
 */
export declare function getFilenameFromKey(key: string): string;
/**
 * Generate a filename from a template ID and output format.
 *
 * @param templateId - The template ID (may include path separators)
 * @param outputFormat - The desired output format (e.g., 'pdf', 'docx')
 * @returns A generated filename
 *
 * @example
 * ```typescript
 * generateFilename('invoices/default', 'pdf');
 * // 'default.pdf'
 * ```
 */
export declare function generateFilename(templateId: string, outputFormat: string): string;
/**
 * Generate a unique filename with timestamp.
 *
 * @param prefix - Filename prefix (default: 'file')
 * @param extension - File extension (default: 'bin')
 * @returns A unique filename
 *
 * @example
 * ```typescript
 * generateUniqueFilename('download', 'pdf');
 * // 'download-1704067200000.pdf'
 * ```
 */
export declare function generateUniqueFilename(prefix?: string, extension?: string): string;
/**
 * Infer file extension from MIME type.
 *
 * @param mimeType - The MIME type
 * @returns The inferred extension (without dot)
 *
 * @example
 * ```typescript
 * inferExtensionFromMimeType('application/pdf'); // 'pdf'
 * inferExtensionFromMimeType('image/png'); // 'png'
 * ```
 */
export declare function inferExtensionFromMimeType(mimeType: string): string;
/**
 * Format file size in human-readable format.
 *
 * @param bytes - Size in bytes
 * @param decimals - Number of decimal places (default: 2)
 * @returns Formatted size string
 *
 * @example
 * ```typescript
 * formatFileSize(1024); // '1 KB'
 * formatFileSize(1536000); // '1.46 MB'
 * ```
 */
export declare function formatFileSize(bytes: number, decimals?: number): string;
/**
 * Parse a human-readable file size to bytes.
 *
 * @param sizeString - Size string (e.g., '1.5 MB', '100KB')
 * @returns Size in bytes
 *
 * @example
 * ```typescript
 * parseFileSize('1.5 MB'); // 1572864
 * parseFileSize('100KB'); // 102400
 * ```
 */
export declare function parseFileSize(sizeString: string): number;
//# sourceMappingURL=files.d.ts.map