/**
 * Storage Port
 *
 * Defines the interface for object storage operations (S3, MinIO, etc.).
 * This is a secondary port (output port) in hexagonal architecture.
 */

export const STORAGE_PORT = 'StoragePort';

export interface UploadOptions {
  bucket: string;
  key: string;
  body: Buffer | string;
  contentType?: string;
  metadata?: Record<string, string>;
  acl?: string;
}

export interface DownloadOptions {
  bucket: string;
  key: string;
}

export interface DeleteOptions {
  bucket: string;
  key: string;
}

export interface StorageObject {
  key: string;
  url: string;
  size: number;
  contentType?: string;
  lastModified?: Date;
}

export interface StoragePort {
  /**
   * Upload a file to storage
   */
  upload(options: UploadOptions): Promise<StorageObject>;

  /**
   * Download a file from storage
   */
  download(options: DownloadOptions): Promise<Buffer>;

  /**
   * Delete a file from storage
   */
  delete(options: DeleteOptions): Promise<void>;

  /**
   * Get a signed URL for temporary access
   * @param options - Download options
   * @param expiresIn - URL expiration in seconds (default: 3600)
   */
  getSignedUrl(options: DownloadOptions, expiresIn?: number): Promise<string>;

  /**
   * Check if a file exists in storage
   */
  exists(options: DownloadOptions): Promise<boolean>;

  /**
   * List objects in a bucket
   */
  list(bucket: string, prefix?: string): Promise<StorageObject[]>;

  /**
   * Ensure a bucket exists, creating it if it does not
   */
  ensureBucket(bucket: string): Promise<void>;
}
