/**
 * Storage driver contract.
 *
 * The rest of the app only ever sees this interface, so moving from local disk
 * to S3/R2 is a one-line change in `STORAGE_DRIVER` — no call-site edits.
 */
import type { Readable } from 'node:stream';

export interface PutOptions {
  key: string;
  contentType: string;
  size?: number;
}

export interface StorageDriver {
  readonly name: string;

  /** Persist a stream at `key`. Returns the number of bytes written. */
  put(stream: Readable, opts: PutOptions): Promise<{ bytes: number }>;

  /** Open a readable stream for `key`. */
  get(key: string): Promise<{ stream: Readable; size: number; contentType?: string }>;

  delete(key: string): Promise<void>;

  exists(key: string): Promise<boolean>;

  /**
   * A URL the browser can GET directly.
   * Local driver returns an HMAC-signed URL on this server; S3 returns a
   * presigned S3 URL. Either way the caller just uses the string.
   */
  downloadUrl(key: string, ttlSeconds: number, filename?: string): Promise<string>;
}