/**
 * Storage Provider Abstraction Layer
 *
 * Allows swapping between local disk, MinIO/S3, and future providers
 * without changing business logic.
 */

export interface UploadResult {
	/** Provider-internal path used for retrieval/deletion */
	storagePath: string;
	/** Publicly accessible URL (may be null for private providers) */
	publicUrl: string | null;
	/** The provider identifier */
	storageProvider: 'local' | 'minio' | 's3';
}

export interface IStorageProvider {
	/**
	 * Upload a file from a local temp path and return storage metadata.
	 * @param sourcePath  Absolute path to the temp file on disk
	 * @param destKey     Desired storage key / path within the bucket or folder
	 * @param mime        MIME type of the file
	 */
	upload(sourcePath: string, destKey: string, mime: string): Promise<UploadResult>;

	/**
	 * Delete a file from storage by its storage path / key.
	 */
	delete(storagePath: string): Promise<void>;

	/**
	 * Generate a signed/pre-signed URL for temporary access.
	 * Returns null if the provider does not support signed URLs.
	 * @param storagePath        Storage path / key
	 * @param expiresInSeconds   URL TTL in seconds (default 3600)
	 * @param contentDisposition SEC-05: override Content-Disposition header on the returned resource
	 * @param filename           Optional filename to include in Content-Disposition header
	 */
	getSignedUrl(
		storagePath: string,
		expiresInSeconds?: number,
		contentDisposition?: 'inline' | 'attachment',
		filename?: string,
	): Promise<string | null>;
}
