@gentleduck/upload 0.2.6 → 0.3.0

package/dist/index-C38Jmizu.d.ts

@@ -1,1005 +0,0 @@
-import { a as AnyCursor, f as IntentMap, i as UploadTransport, l as UploadResultBase, n as StrategyRegistry, o as CursorMap, s as UploadApi, u as AnyIntent } from "./strategy.types-gg9ZStRe.js";
-
-//#region src/core/contracts/errors.types.d.ts
-/**
- * File rejection reasons produced by client-side validation.
- *
- * These should be safe to show in UI.
- */
-type RejectReason = {
-  code: 'empty_file';
-} | {
-  code: 'file_too_large';
-  maxBytes: number;
-  size: number;
-} | {
-  code: 'type_not_allowed';
-  allowed: string[];
-  got: string;
-} | {
-  code: 'too_many_files';
-  max: number;
-};
-/**
- * Base interface for custom errors.
- *
- * If you want to add domain-specific fields, extend this and intersect in {@link UploadError}.
- */
-interface UploadErrorBase {
-  /** Stable error code. */
-  code: string;
-  /** Human-friendly message (safe for UI). */
-  message: string;
-  /** Optional cause (original error, response, etc). */
-  cause?: unknown;
-  /** Whether the error should be retried. */
-  retryable?: boolean;
-}
-/**
- * Built-in engine errors.
- *
- * Keep these narrow and explicit so reducer logic can rely on `code` as a discriminant.
- */
-type BuiltInUploadError = {
-  code: 'validation_failed';
-  message: string;
-  reason: RejectReason;
-  retryable?: false;
-} | {
-  code: 'strategy_missing';
-  message: string;
-  strategy: string;
-  retryable?: false;
-} | {
-  code: 'aborted';
-  message: string;
-  reason: 'pause' | 'cancel' | 'unknown';
-  cause?: unknown;
-  retryable?: false;
-} | {
-  code: 'network';
-  message: string;
-  cause?: unknown;
-  retryable?: boolean;
-} | {
-  code: 'http';
-  message: string;
-  status: number;
-  statusText?: string;
-  cause?: unknown;
-  retryable?: boolean;
-} | {
-  code: 'timeout';
-  message: string;
-  cause?: unknown;
-  retryable?: boolean;
-} | {
-  code: 'auth';
-  message: string;
-  cause?: unknown;
-  retryable?: false;
-} | {
-  code: 'rate_limit';
-  message: string;
-  retryAfterMs?: number;
-  cause?: unknown;
-  retryable?: boolean;
-} | {
-  code: 'server';
-  message: string;
-  serverCode?: string;
-  cause?: unknown;
-  retryable?: boolean;
-} | {
-  code: 'unknown';
-  message: string;
-  cause?: unknown;
-  retryable?: boolean;
-};
-/**
- * The error type used everywhere in the engine.
- *
- * You can extend this by intersecting your own shape with {@link UploadErrorBase}
- * to add fields (example: `{ endpoint: string }`).
- */
-type UploadError = BuiltInUploadError | (UploadErrorBase & Record<string, unknown>);
-/**
- * Validation rules applied on `addFiles` before an item enters the upload pipeline.
- */
-type UploadValidationRules = {
-  /** Maximum number of files allowed. */maxFiles?: number; /** Maximum file size in bytes. */
-  maxSizeBytes?: number; /** Minimum file size in bytes. */
-  minSizeBytes?: number; /** Allowed MIME types. */
-  allowedTypes?: string[]; /** Allowed file extensions. */
-  allowedExtensions?: string[];
-};
-//#endregion
-//#region src/core/contracts/fingerprint.types.d.ts
-/**
- * Deterministic client-side identity for a file.
- *
- * Used to match the same file across refreshes (for rebind) and to deduplicate.
- * If you include `checksum`, it should be stable and computed consistently.
- */
-type FileFingerprint = {
-  /** File name. */name: string; /** File size in bytes. */
-  size: number; /** File MIME type. */
-  type: string; /** File lastModified timestamp (ms). */
-  lastModified: number; /** Optional checksum (example: SHA-256 hex). */
-  checksum?: string;
-};
-//#endregion
-//#region src/core/contracts/transport/transport.d.ts
-type XhrCommonArgs = {
-  url: string;
-  signal?: AbortSignal;
-  headers?: Record<string, string>;
-  onProgress?: (loaded: number, total: number) => void;
-};
-/**
- * Browser-native XHR transport. Uses `XMLHttpRequest` over `fetch` because
- * `fetch` lacks cross-browser upload-progress events.
- */
-declare function createXHRTransport(): UploadTransport & {
-  /** Optional PATCH for tus-style strategies. */patch?: (args: XhrCommonArgs & {
-    body: Blob | ArrayBuffer;
-  }) => Promise<{
-    headers: Record<string, string>;
-  }>;
-};
-//#endregion
-//#region src/core/client/retry.types.d.ts
-/**
- * Output of the retry policy.
- *
- * `delayMs` should be a backoff delay before re-attempting the failed step.
- */
-type RetryDecision = {
-  retryable: false;
-} | {
-  retryable: true;
-  delayMs: number;
-};
-//#endregion
-//#region src/core/client/config.types.d.ts
-/**
- * Global upload engine configuration.
- *
- * @typeParam P - Union of allowed `purpose` strings for your app.
- */
-type UploadConfig<P extends string> = {
-  /** Maximum concurrent uploads. */maxConcurrentUploads: number;
-  /**
-   * Auto-start uploads for specific purposes.
-   * - Array form: only those purposes auto-start
-   * - Function form: dynamic decision per purpose
-   */
-  autoStart?: readonly P[] | ((purpose: P) => boolean); /** Progress event throttle in milliseconds. */
-  progressThrottleMs: number; /** Validation rules keyed by purpose. */
-  validation: Partial<Record<P, UploadValidationRules>>; /** Maximum number of retry attempts (per item / per phase depending on implementation). */
-  maxAttempts: number;
-  /**
-   * Retry policy.
-   * Called whenever a phase fails and the engine needs a decision.
-   */
-  retryPolicy?: (ctx: {
-    phase: 'intent' | 'upload' | 'complete';
-    attempt: number;
-    error: UploadError;
-  }) => RetryDecision;
-  /**
-   * Maximum number of items to keep in state.
-   * When exceeded, oldest completed/canceled items are removed automatically.
-   *
-   * Set to `undefined` for no limit (not recommended for long-running apps).
-   * Default often: `100`.
-   */
-  maxItems: number;
-  /**
-   * Automatically remove completed items after this many milliseconds.
-   * Set to `undefined` to keep completed items indefinitely.
-   */
-  completedItemTTL?: number;
-};
-/**
- * Config input shape accepted by store creation.
- * All fields are optional; defaults are applied by {@link resolveUploadConfig}.
- */
-type UploadConfigInput<P extends string> = Partial<UploadConfig<P>>;
-/**
- * Normalizes user config by applying sensible defaults.
- */
-declare function resolveUploadConfig<P extends string>(input?: UploadConfigInput<P>): UploadConfig<P>;
-//#endregion
-//#region src/core/engine/commands.types.d.ts
-/**
- * Public commands accepted by the upload store.
- *
- * Reducer/effects should treat commands as "user intent".
- */
-type UploadCommand<P extends string> = {
-  type: 'addFiles';
-  files: File[];
-  purpose: P;
-} | {
-  type: 'start';
-  localId: string;
-} | {
-  type: 'startAll';
-  purpose?: P;
-} | {
-  type: 'pause';
-  localId: string;
-} | {
-  type: 'pauseAll';
-  purpose?: P;
-} | {
-  type: 'resume';
-  localId: string;
-} | {
-  type: 'cancel';
-  localId: string;
-} | {
-  type: 'cancelAll';
-  purpose?: P;
-} | {
-  type: 'retry';
-  localId: string;
-} | {
-  type: 'rebind';
-  localId: string;
-  file: File;
-} | {
-  type: 'remove';
-  localId: string;
-};
-//#endregion
-//#region src/core/engine/outcome.types.d.ts
-type UploadCompletionKind = 'upload' | 'dedupe';
-type UploadOutcome<R extends UploadResultBase> = {
-  localId: string;
-  status: 'completed';
-  completedBy: UploadCompletionKind;
-  result: R;
-} | {
-  localId: string;
-  status: 'error';
-  error: UploadError;
-} | {
-  localId: string;
-  status: 'canceled';
-} | {
-  localId: string;
-  status: 'missing';
-};
-//#endregion
-//#region src/core/engine/progress.types.d.ts
-/**
- * Upload progress snapshot.
- *
- * Invariants:
- * - `totalBytes` should be `file.size` when known.
- * - `pct` should be clamped to 0..100.
- */
-type UploadProgress = {
-  /** Bytes uploaded so far. */uploadedBytes: number; /** Total bytes to upload. */
-  totalBytes: number; /** Percent complete (0..100). */
-  pct: number;
-};
-//#endregion
-//#region src/core/engine/internal-events.types.d.ts
-/**
- * Internal events emitted by effects and consumed by the reducer.
- * Distinct from the public event surface — these drive state transitions.
- */
-type InternalEvent<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = {
-  type: 'files.added';
-  items: Array<{
-    localId: string;
-    purpose: P;
-    file: File;
-    fingerprint: FileFingerprint;
-    createdAt: number;
-  }>;
-} | {
-  type: 'fingerprint.updated';
-  localId: string;
-  fingerprint: FileFingerprint;
-} | {
-  type: 'validation.ok';
-  localId: string;
-} | {
-  type: 'validation.failed';
-  localId: string;
-  reason: RejectReason;
-} | {
-  type: 'intent.ok';
-  localId: string;
-  intent: AnyIntent<M>;
-} | {
-  type: 'intent.failed';
-  localId: string;
-  error: UploadError;
-  retryable: boolean;
-} | {
-  type: 'upload.begin';
-  localId: string;
-  startedAt: number;
-} | {
-  type: 'upload.progress';
-  localId: string;
-  uploadedBytes: number;
-  totalBytes: number;
-} | {
-  type: 'cursor.updated';
-  localId: string;
-  cursor: AnyCursor<C>;
-} | {
-  type: 'upload.ok';
-  localId: string;
-} | {
-  type: 'upload.failed';
-  localId: string;
-  error: UploadError;
-  retryable: boolean;
-} | {
-  type: 'dedupe.ok';
-  localId: string;
-  result: R;
-} | {
-  type: 'complete.ok';
-  localId: string;
-  result: R;
-} | {
-  type: 'complete.failed';
-  localId: string;
-  error: UploadError;
-  retryable: boolean;
-} /** Internal completion for pause requests. */ | {
-  type: 'paused';
-  localId: string;
-  cursor: AnyCursor<C>;
-  pausedAt: number;
-} /** Internal completion for cancel requests. */ | {
-  type: 'canceled';
-  localId: string;
-  canceledAt: number;
-};
-/** Every upload phase; the `phase` discriminator of {@link UploadItem}. */
-type UploadPhase = 'validating' | 'creating_intent' | 'ready' | 'queued' | 'uploading' | 'paused' | 'completing' | 'completed' | 'error' | 'canceled';
-/** Discriminated union on `phase` describing a single upload's state. */
-type UploadItem<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = {
-  /** Validating file against rules. */phase: 'validating';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  file: File;
-  createdAt: number;
-} | {
-  /** Requesting upload intent from backend. */phase: 'creating_intent';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  file: File; /** Current attempt number for this phase. */
-  attempt: number;
-  createdAt: number;
-} | {
-  /** Intent received, ready to start upload. */phase: 'ready';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  file: File;
-  intent: AnyIntent<M>;
-  createdAt: number;
-  cursor?: AnyCursor<C>;
-  progress?: UploadProgress;
-  attempt?: number;
-} | {
-  /** Queued for upload (waiting for slot). */phase: 'queued';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  file: File;
-  intent: AnyIntent<M>; /** Timestamp when this item requested a concurrency slot. */
-  requestedAt: number;
-  createdAt: number;
-  cursor?: AnyCursor<C>;
-  progress?: UploadProgress;
-  attempt?: number;
-} | {
-  /** Actively uploading bytes. */phase: 'uploading';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  file: File;
-  intent: AnyIntent<M>;
-  startedAt: number;
-  progress: UploadProgress;
-  createdAt: number;
-  cursor?: AnyCursor<C>;
-  attempt?: number;
-} | {
-  /** Upload paused (resumable). */phase: 'paused';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  intent: AnyIntent<M>;
-  cursor: AnyCursor<C>;
-  progress: UploadProgress;
-  pausedAt: number;
-  createdAt: number;
-  /**
-   * File is optional because a paused item can be restored from persistence without a File.
-   * Use `rebind` to attach the File again before resuming (when required).
-   */
-  file?: File;
-  attempt?: number;
-} | {
-  /** Bytes sent, finalizing with backend. */phase: 'completing';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  file: File;
-  intent: AnyIntent<M>;
-  progress: UploadProgress;
-  completingAt: number;
-  createdAt: number;
-  attempt?: number;
-} | {
-  /** Upload completed successfully. */phase: 'completed';
-  localId: string;
-  file: File;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  intent?: AnyIntent<M>;
-  completedBy: UploadCompletionKind;
-  result: R;
-  completedAt: number;
-  createdAt: number;
-  attempt?: number;
-} | {
-  /** Upload failed (retryable or final). */phase: 'error';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  error: UploadError;
-  retryable: boolean;
-  attempt: number;
-  failedAt: number;
-  createdAt: number;
-  file?: File;
-  intent?: AnyIntent<M>;
-  cursor?: AnyCursor<C>;
-  progress?: UploadProgress;
-} | {
-  /** Upload canceled by user/system. */phase: 'canceled';
-  localId: string;
-  purpose: P;
-  fingerprint: FileFingerprint;
-  canceledAt: number;
-  createdAt: number;
-  file?: File;
-  intent?: AnyIntent<M>;
-  cursor?: AnyCursor<C>;
-  progress?: UploadProgress;
-  attempt?: number;
-};
-//#endregion
-//#region src/core/engine/reducer.d.ts
-type UploadState<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = {
-  /** Map of uploads by localId for O(1) lookups */items: Map<string, UploadItem<M, C, P, R>>;
-};
-declare function createReducer<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase>(): (state: UploadState<M, C, P, R>, event: UploadCommand<P> | InternalEvent<M, C, P, R>) => UploadState<M, C, P, R>;
-//#endregion
-//#region src/core/persistence/persistence.types.d.ts
-/**
- * A minimal, serializable representation of an upload item that is safe to store
- * in persistence (LocalStorage, IndexedDB, etc).
- *
- * This type is intentionally not the full {@link UploadItem} state.
- * It captures only the fields needed to:
- * - restore the UI list after refresh
- * - rebind an upload to its backend intent (if already created)
- * - resume an upload strategy from a known cursor (when supported)
- * - restore last-known progress and phase for UX continuity
- *
- * @typeParam M - Map of upload intent variants keyed by intent kind (e.g. `direct`, `multipart`).
- * @typeParam C - Map of cursor shapes keyed by {@link M}'s intent kinds.
- * @typeParam P - Union of allowed `purpose` strings for your app (e.g. `"avatar" | "document"`).
- */
-type PersistedSnapshot<M, C, P extends string> = {
-  /** Persistence schema version (not app version). */version: number; /** Unix epoch milliseconds when this snapshot was written. */
-  createdAt: number; /** List of persisted upload items. */
-  items: Record<string, PersistedUploadItem<M, C, P>>;
-};
-type PersistedUploadItem<M, C, P extends string> = {
-  /** Stable, client-generated ID for this upload in local state. */id: string; /** File name. */
-  file: {
-    /** File name. */name: string; /** File size in bytes. */
-    size: number; /** File MIME type. */
-    type: string; /** File lastModified timestamp (ms). */
-    lastModified: number; /** Optional checksum (example: SHA-256 hex). */
-    checksum?: string;
-  }; /** Backend-provided "intent" that describes how to upload (strategy, URLs, fields, etc). */
-  intent: M[keyof M]; /** Strategy cursor used to resume uploads that support continuation. */
-  cursor?: AnyCursor<C & Record<string, unknown>>; /** Last-known progress for UX continuity after restoring from persistence. */
-  progress?: {
-    uploadedBytes: number;
-    totalBytes: number;
-    pct?: number;
-  }; /** The last known state-machine phase at the time of persistence. */
-  status: string; /** Logical purpose for the upload (application-defined). */
-  purpose: P;
-};
-/**
- * A persisted snapshot of the upload store.
- *
- * Snapshots are versioned to allow safe migrations when the persistence schema evolves.
- * They are time-stamped for diagnostics and garbage-collection policies.
- */
-interface PersistenceAdapter {
-  /** Loads a snapshot from persistence. */
-  load(key: string): unknown | null | Promise<unknown | null>;
-  /** Saves a snapshot to persistence. */
-  save(key: string, snapshot: unknown): void | Promise<void>;
-  /** Clears a snapshot from persistence. */
-  clear(key: string): void | Promise<void>;
-}
-//#endregion
-//#region src/core/persistence/adapters.indexeddb.d.ts
-declare const IndexedDBAdapter: PersistenceAdapter;
-//#endregion
-//#region src/core/persistence/adapters.local.d.ts
-declare const LocalStorageAdapter: PersistenceAdapter;
-//#endregion
-//#region src/core/persistence/adapters.memory.d.ts
-declare const MemoryAdapter: PersistenceAdapter;
-//#endregion
-//#region src/core/persistence/persistence.d.ts
-/**
- * Serializes the current upload state into a JSON-safe structure.
- * Only serializes items that have a valid 'intent', as these are the only ones
- * that can be resumed cleanly.
- */
-declare function serializeSnapshot<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(state: UploadState<M, C, P, R>, version: number): PersistedSnapshot<M, C, P>;
-/**
- * Deserializes a persisted snapshot back into a store state.
- *
- * Important:
- * - Browser `File` objects cannot be restored from persistence.
- * - We restore resumable items (those with a cursor) into the `paused` phase,
- *   with `file` left undefined. Your UI can ask the user to rebind the file.
- */
-declare function deserializeSnapshot<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(raw: unknown, opts: {
-  isPurpose?: (value: string) => value is P;
-  isIntent?: (value: unknown) => value is M[keyof M];
-  hasStrategy: (value: string) => boolean;
-}): UploadState<M, C, P, R> | null;
-//#endregion
-//#region src/core/utils/emitter/emitter.types.d.ts
-/**
- * Minimal typed event emitter interface.
- *
- * Use this to expose strongly-typed events from your store.
- *
- * @typeParam E - Event map (`eventName -> payload`).
- */
-type TypedEmitter<E extends Record<string, unknown>> = {
-  /**
-   * Subscribe to an event.
-   * @returns Unsubscribe function.
-   */
-  on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void;
-  /**
-   * Unsubscribe from an event.
-   * @returns Unsubscribe function.
-   */
-  off<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void; /** Emit an event to all listeners. */
-  emit<K extends keyof E & string>(type: K, payload: E[K]): void;
-};
-//#endregion
-//#region src/core/utils/emitter/index.d.ts
-declare function createTypedEmitter<E extends Record<string, unknown>>(): TypedEmitter<E>;
-//#endregion
-//#region src/core/engine/event-map.types.d.ts
-/**
- * Public event map emitted to consumers.
- *
- * Consumers subscribe via {@link TypedEmitter.on}.
- */
-type UploadEventMap<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = {
-  'file.added': {
-    localId: string;
-    purpose: P;
-    file: File;
-    fingerprint: FileFingerprint;
-  };
-  'file.rejected': {
-    file: File;
-    reason: RejectReason;
-  };
-  'validation.ok': {
-    localId: string;
-  };
-  'validation.failed': {
-    localId: string;
-    reason: RejectReason;
-  };
-  'intent.creating': {
-    localId: string;
-  };
-  'intent.created': {
-    localId: string;
-    intent: M[keyof M];
-  };
-  'intent.failed': {
-    localId: string;
-    error: UploadError;
-    retryable: boolean;
-  };
-  'upload.queued': {
-    localId: string;
-  };
-  'upload.resumed': {
-    localId: string;
-  };
-  'upload.started': {
-    localId: string;
-  };
-  'upload.progress': {
-    localId: string;
-    pct: number;
-    uploadedBytes: number;
-    totalBytes: number;
-  };
-  'upload.cursor': {
-    localId: string;
-    cursor: AnyCursor<C>;
-  };
-  'upload.paused': {
-    localId: string;
-    cursor: AnyCursor<C>;
-  };
-  'upload.canceled': {
-    localId: string;
-  };
-  'upload.completing': {
-    localId: string;
-  };
-  'upload.completed': {
-    localId: string;
-    result: R;
-    completedBy: UploadCompletionKind;
-  };
-  'upload.error': {
-    localId: string;
-    error: UploadError;
-    retryable: boolean;
-  };
-};
-//#endregion
-//#region src/core/engine/store/store.types.d.ts
-/**
- * Upload store interface used by UI adapters and application code.
- *
- * The store is intentionally minimal:
- * - state is read through {@link UploadStore.getSnapshot}
- * - updates are observed through {@link UploadStore.subscribe} and {@link UploadStore.on}
- * - actions are performed through {@link UploadStore.dispatch}
- *
- * @template M - Intent map type (keyed by strategy id)
- * @template C - Cursor map type (keyed by strategy id)
- * @template P - Purpose string union type
- */
-interface UploadStore<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> {
-  /**
-   * Returns the current immutable state snapshot.
-   * Useful for React loops or debugging.
-   */
-  getSnapshot(): UploadState<M, C, P, R>;
-  /**
-   * Subscribes to ANY state change.
-   * The listener is called after the reducer has run and effects have been scheduled.
-   * @param listener - Listener function to call on state change
-   */
-  subscribe(listener: () => void): () => void;
-  /**
-   * Main entry point for user actions.
-   * Converts external commands into internal state transitions and side effects.
-   *
-   * @param cmd The command to execute (e.g. 'addFiles', 'start', 'pause')
-   */
-  dispatch(cmd: UploadCommand<P>): void;
-  /**
-   * Subscribes to specific events (like 'file.added', 'upload.progress').
-   * Wraps the internal typed emitter.
-   */
-  on: <K extends keyof UploadEventMap<M, C, P, R> & string>(type: K, cb: (payload: UploadEventMap<M, C, P, R>[K]) => void) => () => void;
-  /**
-   * Unsubscribes from specific events (like 'file.added', 'upload.progress').
-   * Wraps the internal typed emitter.
-   */
-  off: <K extends keyof UploadEventMap<M, C, P, R> & string>(type: K, cb: (payload: UploadEventMap<M, C, P, R>[K]) => void) => () => void;
-  /**
-   * Waits for the given localIds to reach a terminal state.
-   */
-  waitFor(localIds: string[]): Promise<Array<UploadOutcome<R>>>;
-}
-/**
- * Options used to construct a store runtime.
- *
- * In practice you provide:
- * - a backend adapter ({@link UploadApi}) that creates intents and finalizes uploads
- * - a transport implementation (XHR, fetch, etc.) used by strategies
- * - a strategy registry describing what upload strategies exist and how to run them
- * - configuration rules for validation, concurrency, retries, and progress throttling
- *
- * Hooks and plugins are optional and let you observe or extend behavior without forking
- * the engine.
- *
- * @template M - Intent map type (keyed by strategy id)
- * @template C - Cursor map type (keyed by strategy id)
- * @template P - Purpose string union type
- */
-interface StoreOptions<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> {
-  /** Initial state to hydrate from (e.g. from localStorage) */
-  initialState?: UploadState<M, C, P, R>;
-  /** Static configuration rules (defaults are applied). */
-  config?: UploadConfigInput<P>;
-  /** Persistence adapter and options */
-  persistence?: PersistenceOptions<M, C, P, R>;
-  /** Backend API adapter for creating intents and finalizing uploads */
-  api: UploadApi<M, P, R>;
-  /** Network transport (XHR/Fetch) for the actual file data transfer */
-  transport?: UploadTransport;
-  /** Registry of available upload strategies (multipart, simple, etc.) */
-  strategies: StrategyRegistry<M, C, P, R>;
-  /** Optional plugins to extend functionality (e.g. debugging, metrics) */
-  plugins?: Array<UploadPlugin<M, C, P, R>>;
-  /** Lifecycle hooks for observing internal events */
-  hooks?: UploadHooks<M, C, P, R>;
-  /**
-   * Optional custom fingerprinting (e.g. include sha256).
-   * Must be synchronous to keep addFiles fast.
-   */
-  fingerprint?: (file: File) => FileFingerprint;
-  /**
-   * If returns non-null, it rejects the file.
-   * Runs after built-in config validation.
-   */
-  validateFile?: (file: File, purpose: P) => RejectReason | null;
-  /**
-   * Optional custom error normalizer.
-   * Convert raw errors (from fetch, XHR, etc.) into your custom UploadError shape.
-   */
-  errorNormalizer?: (err: unknown) => UploadError;
-}
-/**
- * Persistence options.
- *
- * Used to configure the upload store persistence layer.
- */
-type DeserializeContext<M extends IntentMap, _C extends CursorMap<M>, P extends string> = {
-  isPurpose?: (value: string) => value is P;
-  isIntent?: (value: unknown) => value is M[keyof M];
-  hasStrategy: (value: string) => boolean;
-};
-type PersistenceOptions<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase> = {
-  /** Persistence key (e.g. localStorage key) */key: string; /** Persistence schema version (not app version) */
-  version: number; /** Debounce delay in milliseconds (default: 200) */
-  debounceMs?: number; /** Persistence adapter */
-  adapter: PersistenceAdapter;
-  /**
-   * Optional custom snapshot serializer.
-   * Convert the upload state into a JSON-safe snapshot.
-   */
-  serialize?: (state: UploadState<M, C, P, R>, version: number) => PersistedSnapshot<M, C, P>;
-  /**
-   * Optional custom snapshot deserializer.
-   * Convert a JSON-safe snapshot into the upload state.
-   */
-  deserialize?: (raw: unknown, ctx: DeserializeContext<M, C, P>) => UploadState<M, C, P, R> | null;
-  /**
-   * Runtime guard for purpose strings when using the default deserializer.
-   */
-  isPurpose?: (value: string) => value is P;
-  /**
-   * Runtime guard for intent objects when using the default deserializer.
-   */
-  isIntent?: (value: unknown) => value is M[keyof M];
-};
-/**
- * Internal record describing a currently running upload request.
- *
- * The store keeps one inflight entry per `localId` while the strategy's `start()` is running.
- * The {@link AbortController} is used to pause/cancel, while `mode` tracks which user intent
- * caused the abort so the handler can map it back into a correct state transition.
- */
-type InflightUpload = {
-  controller: AbortController;
-  mode: 'normal' | 'pause' | 'cancel';
-  started: boolean;
-};
-/**
- * Internal runtime container shared across dispatch, scheduler, and handlers.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose string union type
- */
-type StoreRuntime<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = {
-  /** Store options */opts: StoreOptions<M, C, P, R> & {
-    config: UploadConfig<P>;
-    transport: UploadTransport;
-  }; /** Current state */
-  state: UploadState<M, C, P, R>; /** Listeners for external events */
-  listeners: Set<() => void>; /** Typed event emitter */
-  emitter: TypedEmitter<UploadEventMap<M, C, P, R>>; /** Reducer */
-  reduce: ReturnType<typeof createReducer<M, C, P, R>>; /** In-flight uploads */
-  inflightUploads: Map<string, InflightUpload>; /** In-flight intents */
-  inflightIntents: Map<string, AbortController>; /** In-flight completes */
-  inflightCompletes: Map<string, AbortController>; /** Effect queue */
-  effectQueue: Array<() => Promise<void>>; /** Effect queue processing */
-  processingEffects: boolean; /** Effect queue scheduling */
-  scheduling: boolean; /** Notifies listeners */
-  notify: () => void; /** Schedules work */
-  scheduleWork: () => void; /** Applies an internal event */
-  applyInternal: (event: InternalEvent<M, C, P, R>) => void; /** Applies a command */
-  applyCommand: (cmd: UploadCommand<P>) => void; /** Enqueues an effect */
-  enqueueEffect: (effect: () => Promise<void>) => void; /** Processes effects */
-  processEffects: () => Promise<void>; /** Set by createUploadStore after construction; used by handlers for retries etc. */
-  dispatch: (cmd: UploadCommand<P>) => void;
-};
-//#endregion
-//#region src/core/engine/store/index.d.ts
-/**
- * Creates an upload store instance.
- *
- * This is the main runtime object you interact with from the outside:
- * - dispatch user commands (add files, start, pause, cancel, resume)
- * - subscribe to state changes (for UI rendering)
- * - subscribe to typed events (for progress, errors, and lifecycle)
- *
- * Plugins are initialized once during construction and receive a minimal store
- * proxy (events, dispatch, snapshot access) to avoid tight coupling.
- *
- * @template M - Intent map type (keyed by strategy id)
- * @template C - Cursor map type (keyed by strategy id)
- * @template P - Purpose string union type
- *
- * @param opts - Store options (config, backend API, strategies, transport, hooks)
- * @returns A configured {@link UploadStore} instance.
- */
-declare function createUploadStore<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase>(opts: StoreOptions<M, C, P, R>): UploadStore<M, C, P, R>;
-//#endregion
-//#region src/core/client/plugins.types.d.ts
-/**
- * Optional hooks for observing internal behavior.
- *
- * Use these for diagnostics, analytics, logging, or devtools.
- */
-type UploadHooks<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = {
-  /**
-   * Called after internal events are processed (depending on your runtime wiring).
-   * Prefer this over subscribing to public events if you need full fidelity.
-   */
-  onInternalEvent?: (event: InternalEvent<M, C, P, R>, state: UploadState<M, C, P, R>) => void;
-};
-/**
- * Store plugins.
- *
- * Plugins can subscribe to store events and dispatch commands.
- * They should not reach into internal state mutably.
- */
-type UploadPlugin<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = {
-  /** Plugin name (for debugging). */name: string;
-  /**
-   * Setup callback called once when the store is created.
-   * The plugin can register event listeners and drive behavior.
-   */
-  setup: (ctx: Pick<UploadStore<M, C, P, R>, 'on' | 'dispatch' | 'getSnapshot'>) => void;
-};
-//#endregion
-//#region src/core/client/uploadClient.d.ts
-type UploadClient<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = UploadStore<M, C, P, R>;
-declare function createUploadClient<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase>(opts: StoreOptions<M, C, P, R>): UploadClient<M, C, P, R>;
-//#endregion
-//#region src/core/engine/validation.d.ts
-/**
- * Validate one file against `config.validation[purpose]` rules.
- *
- * Empty files are always rejected.
- *
- * @param file File to validate.
- * @param purpose Purpose key used to look up rules.
- * @param config Resolved upload config.
- * @template P Purpose discriminator string.
- * @returns `null` when valid, otherwise a {@link Contracts.RejectReason}.
- * @author wildduck2 <https://github.com/wildduck2>
- */
-declare function validateFile<P extends string>(file: File, purpose: P, config: Client.IUploadConfig<P>): Contracts.RejectReason | null;
-/**
- * Validate a batch of files and split into accepted vs rejected.
- *
- * Enforces `maxFiles` against the existing count plus the running additions
- * so a single `addFiles` call cannot overshoot.
- *
- * @param files Files to validate.
- * @param purpose Purpose key used to look up rules.
- * @param config Resolved upload config.
- * @param existingCount Items already in the store for this purpose.
- * @template P Purpose discriminator string.
- * @returns Object with `valid` files and `rejected` files plus reasons.
- * @author wildduck2 <https://github.com/wildduck2>
- */
-declare function validateFileList<P extends string>(files: File[], purpose: P, config: Client.IUploadConfig<P>, existingCount?: number): {
-  valid: File[];
-  rejected: Array<{
-    file: File;
-    reason: Contracts.RejectReason;
-  }>;
-};
-/**
- * Validate an intent payload returned by the backend before the engine
- * commits to it.
- *
- * Rejects malformed shapes, protocol-foreign URLs, and cross-field
- * inconsistencies (e.g. `partCount * partSize` cannot cover the file).
- *
- * @param intent Raw intent value from `createIntent`.
- * @param strategy Expected `strategy` discriminator.
- * @param fileSize File byte length; enables multipart cross-checks.
- * @returns `Error` describing the failure, or `null` if valid.
- * @author wildduck2 <https://github.com/wildduck2>
- */
-declare function validateIntent(intent: unknown, strategy: string, fileSize?: number): Error | null;
-//#endregion
-//#region src/core/utils/async.d.ts
-declare function sleep(ms: number): Promise<void>;
-//#endregion
-//#region src/core/utils/constants.d.ts
-/**
- * Default retry delay base in milliseconds.
- * Used for exponential backoff calculation: base * 2^(attempt - 1)
- */
-declare const DEFAULT_RETRY_DELAY_BASE_MS = 500;
-/**
- * Maximum retry delay in milliseconds.
- * Caps exponential backoff to prevent excessive delays.
- */
-declare const DEFAULT_RETRY_DELAY_MAX_MS = 10000;
-/**
- * Default progress event throttle in milliseconds.
- * Prevents excessive progress updates from overwhelming the UI.
- */
-declare const DEFAULT_PROGRESS_THROTTLE_MS = 100;
-/**
- * Default maximum number of retry attempts.
- */
-declare const DEFAULT_MAX_ATTEMPTS = 3;
-/**
- * Default maximum number of concurrent uploads.
- */
-declare const DEFAULT_MAX_CONCURRENT_UPLOADS = 3;
-/**
- * Default maximum number of items to keep in memory.
- */
-declare const DEFAULT_MAX_ITEMS = 100;
-//#endregion
-//#region src/core/utils/fingerprint.d.ts
-/**
- * Builds a lightweight fingerprint from a {@link File}.
- */
-declare function computeFingerprint(file: File): FileFingerprint;
-/**
- * Compares two file fingerprints.
- */
-declare function fingerprintMatches(a: FileFingerprint, b: FileFingerprint): boolean;
-//#endregion
-//#region src/core/utils/guards.d.ts
-declare function isRecord(value: unknown): value is Record<string, unknown>;
-//#endregion
-//#region src/core/utils/id.d.ts
-declare function generateId(): string;
-//#endregion
-export { RejectReason as $, serializeSnapshot as A, UploadItem as B, StoreOptions as C, createTypedEmitter as D, UploadEventMap as E, PersistedUploadItem as F, UploadCommand as G, UploadProgress as H, PersistenceAdapter as I, resolveUploadConfig as J, UploadConfig as K, UploadState as L, LocalStorageAdapter as M, IndexedDBAdapter as N, TypedEmitter as O, PersistedSnapshot as P, BuiltInUploadError as Q, createReducer as R, PersistenceOptions as S, UploadStore as T, UploadCompletionKind as U, UploadPhase as V, UploadOutcome as W, createXHRTransport as X, RetryDecision as Y, FileFingerprint as Z, UploadHooks as _, DEFAULT_MAX_ATTEMPTS as a, DeserializeContext as b, DEFAULT_PROGRESS_THROTTLE_MS as c, sleep as d, UploadError as et, validateFile as f, createUploadClient as g, UploadClient as h, fingerprintMatches as i, MemoryAdapter as j, deserializeSnapshot as k, DEFAULT_RETRY_DELAY_BASE_MS as l, validateIntent as m, isRecord as n, UploadValidationRules as nt, DEFAULT_MAX_CONCURRENT_UPLOADS as o, validateFileList as p, UploadConfigInput as q, computeFingerprint as r, DEFAULT_MAX_ITEMS as s, generateId as t, UploadErrorBase as tt, DEFAULT_RETRY_DELAY_MAX_MS as u, UploadPlugin as v, StoreRuntime as w, InflightUpload as x, createUploadStore as y, InternalEvent as z };