/**
 * Cloud-agnostic storage interfaces.
 *
 * Provides StorageProvider and StorageBucket abstractions
 * that work with Azure Blob, S3, R2, or in-memory storage.
 */

export interface StorageProvider {
  /** Get or create a bucket/container. */
  getBucket(name: string): StorageBucket;

  /** Check if storage is configured and reachable. */
  isHealthy(): Promise<boolean>;
}

export interface StorageBucket {
  /** Upload a blob. */
  upload(
    key: string,
    data: Buffer | Uint8Array | string,
    options?: UploadOptions
  ): Promise<BlobMeta>;

  /** Download a blob as a Buffer. */
  download(key: string): Promise<Buffer>;

  /** Delete a blob. */
  delete(key: string): Promise<void>;

  /** Check if a blob exists. */
  exists(key: string): Promise<boolean>;

  /** List blobs with optional prefix. */
  list(prefix?: string): Promise<BlobMeta[]>;

  /** Get a signed URL for temporary access. */
  getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
}

export interface UploadOptions {
  contentType?: string;
  metadata?: Record<string, string>;
}

export interface SignedUrlOptions {
  /** Expiry in seconds (default 3600). */
  expiresIn?: number;
  permissions?: 'read' | 'write';
}

export interface BlobMeta {
  key: string;
  size?: number;
  contentType?: string;
  lastModified?: Date;
  metadata?: Record<string, string>;
}

export type StorageProviderType = 'azure' | 'memory';
