/**
 * Upload Handler for Momentum CMS
 * Framework-agnostic file upload handling
 */
import type { StorageAdapter, UploadedFile, MomentumConfig, MediaDocument, UploadCollectionConfig } from '@momentumcms/core';
import { type MomentumAPIContext } from './momentum-api';
/**
 * Upload request from the client.
 */
export interface UploadRequest {
    /** Uploaded file data */
    file: UploadedFile;
    /** User context for access control */
    user?: MomentumAPIContext['user'];
    /** Alt text for the file (for images) */
    alt?: string;
    /** Target collection (defaults to 'media') */
    collection?: string;
}
/**
 * Upload response returned to the client.
 */
export interface UploadResponse {
    /** Created media document */
    doc?: MediaDocument;
    /** Error message if upload failed */
    error?: string;
    /** HTTP status code */
    status: number;
}
/**
 * Upload configuration from MomentumConfig.
 */
export interface UploadConfig {
    /** Storage adapter for file storage */
    adapter: StorageAdapter;
    /** Maximum file size in bytes */
    maxFileSize?: number;
    /** Allowed MIME types */
    allowedMimeTypes?: string[];
}
/**
 * Get upload configuration from MomentumConfig.
 */
export declare function getUploadConfig(config: MomentumConfig): UploadConfig | null;
/**
 * Validate claimed MIME type against an allow-list.
 * Returns an error message if the type is not allowed, or null if OK.
 */
export declare function validateMimeType(mimeType: string, allowedTypes: string[]): string | null;
/**
 * Handle file upload.
 *
 * @param config - Upload configuration
 * @param request - Upload request with file and user context
 * @returns Upload response with created media document or error
 */
export declare function handleUpload(config: UploadConfig, request: UploadRequest): Promise<UploadResponse>;
/**
 * Upload request for a collection-level upload.
 * Used when POST /api/{slug} with multipart/form-data hits an upload collection.
 */
export interface CollectionUploadRequest {
    /** The uploaded file */
    file: UploadedFile;
    /** User context for access control */
    user?: MomentumAPIContext['user'];
    /** Non-file form fields from multipart body (e.g., alt, title) */
    fields: Record<string, unknown>;
    /** Target collection slug */
    collectionSlug: string;
    /** Collection-level upload config */
    collectionUpload: UploadCollectionConfig;
}
/**
 * Response from a collection-level upload.
 */
export interface CollectionUploadResponse {
    /** Created document (with auto-populated file metadata) */
    doc?: Record<string, unknown>;
    /** Error message if upload failed */
    error?: string;
    /** HTTP status code */
    status: number;
}
/**
 * Handle file upload for an upload collection.
 * Stores the file, auto-populates metadata fields, merges with user-provided fields,
 * and creates the document in the target collection.
 *
 * Collection-level config overrides global config for mimeTypes and maxFileSize.
 *
 * @param globalConfig - Global upload configuration (storage adapter, defaults)
 * @param request - Collection upload request with file, user fields, and collection config
 * @returns Response with created document or error
 */
export declare function handleCollectionUpload(globalConfig: UploadConfig, request: CollectionUploadRequest): Promise<CollectionUploadResponse>;
/**
 * Handle file deletion.
 *
 * @param adapter - Storage adapter
 * @param path - Storage path of the file to delete
 * @returns True if deleted, false if not found
 */
export declare function handleFileDelete(adapter: StorageAdapter, path: string): Promise<boolean>;
/**
 * Handle file retrieval for serving.
 *
 * @param adapter - Storage adapter
 * @param path - Storage path of the file
 * @returns File buffer and metadata, or null if not found
 */
export declare function handleFileGet(adapter: StorageAdapter, path: string): Promise<{
    buffer: Uint8Array;
    mimeType?: string;
} | null>;