Types

interface UploadOptions {
  filename: string;
  mimeType?: string;
  path?: string;
  metadata?: Record<string, string>;
  size?: number;
  signal?: AbortSignal;
  onProgress?: (progress: UploadProgress) => void;
  streamFactory?: () => ReadableStream<Uint8Array>; // sync today; async return is a planned future feature
}

interface UploadProgress {
  bytes: number;
  total?: number;
  progress?: number; // 0..1, present only when total is known
}

interface UploadResult<TMeta extends Record<string, unknown>> {
  id: string;
  url: string;
  path: string;
  size: number;
  meta: TMeta;
}

interface PresignedUrlOptions {
  expiresIn?: number; // seconds; default 3600, bounds driver-specific
}

interface RetryConfig {
  maxRetries?: number;           // attempts after the first; default 3, 0 disables
  baseDelayMs?: number;          // first delay; default 300
  maxDelayMs?: number;           // cap on any single delay; default 10000
  multiplier?: number;           // exponential backoff factor; default 2
  jitter?: boolean;              // full jitter over [0, delay]; default true
  retryHttpStatuses?: number[];  // extra HTTP statuses to treat as retryable
  retryGenericErrors?: boolean;  // retry non-StorageError failures; default true
}

interface BaseDriver<TMeta extends Record<string, unknown> = Record<string, unknown>> {
  name: string;
  upload(
    stream: ReadableStream<Uint8Array>,
    options: UploadOptions,
  ): Promise<UploadResult<TMeta>>;
  delete(path: string): Promise<boolean>;
  getUrl(path: string): Promise<string>;
  get(path: string): Promise<ReadableStream<Uint8Array>>;
  getPresignedUrl?(path: string, options?: PresignedUrlOptions): Promise<string>;
}

interface MiddlewareHook {
  beforeUpload?: (
    stream: ReadableStream<Uint8Array>,
    options: UploadOptions,
  ) => Promise<
    | { stream?: ReadableStream<Uint8Array>; options?: UploadOptions }
    | void
  >;
  afterUpload?: (result: UploadResult<Record<string, unknown>>) => Promise<void>;
}

interface FilewayConfig<TDriver extends BaseDriver> {
  driver: TDriver;
  middlewares?: MiddlewareHook[];
  logger?: Logger;
  onError?: (error: unknown, context: ErrorContext) => void | Promise<void>;
  retry?: RetryConfig;
}

interface Logger {
  debug?(message: string, meta?: Record<string, unknown>): void;
  info?(message: string, meta?: Record<string, unknown>): void;
  warn?(message: string, meta?: Record<string, unknown>): void;
  error?(message: string, meta?: Record<string, unknown>): void;
}

interface ErrorContext {
  operation: "upload" | "delete" | "get" | "getUrl" | "getPresignedUrl" | "retry";
  durationMs: number;
  filename?: string;
  path?: string;
  mimeType?: string;
  size?: number;
}

type StorageErrorCode =
  | "validation"
  | "config"
  | "not-found"
  | "bucket-not-found"
  | "auth-failed"
  | "size-exceeded"
  | "network"
  | "provider-error";

class StorageError extends Error {
  readonly code: StorageErrorCode;
  readonly statusCode?: number;
  readonly provider?: string;
  readonly cause?: unknown;
  toJSON(): { name: string; code: StorageErrorCode; message: string; statusCode?: number; provider?: string };
}