uploaderkit 1.0.0 → 2.0.0

package/dist/types-BSlJJwti.d.cts

@@ -0,0 +1,341 @@
+/**
+ * Every user-facing string the package renders, so no copy is hardcoded
+ * inside a component and apps translate or reword without forking.
+ *
+ * English is the default so the kit ships globalized; `ES_LABELS` ships for
+ * Spanish apps, selected once through `UploaderProvider language='es'`. Hooks
+ * take `labels` in their options, components as a prop — always a `Partial`,
+ * merged over the provider's base.
+ */
+type UploaderLabels = {
+    /** Prompt inside the single dropzone of `Uploader` (fine pointers). */
+    dropPrompt: string;
+    /** Same zone on a touch device, where dragging barely exists. */
+    tapPrompt: string;
+    /** Prompt inside the bulk dropzone of `SlottedUploader` (fine pointers). */
+    bulkDropPrompt: string;
+    /** Same bulk zone on a touch device. */
+    bulkTapPrompt: string;
+    /** Button that fires the batch when `uploadOn` is `'manual'`. */
+    uploadAll: string;
+    /** Row action: preview a file. */
+    view: string;
+    /** Row action: forget a file. */
+    remove: string;
+    /** Row action: abort an in-flight upload. */
+    cancel: string;
+    /** Suffix on a row the server confirmed. */
+    ready: string;
+    /**
+     * Suffix on a row holding a picked file that has NOT been sent yet.
+     * Distinct from {@link UploaderLabels.ready}, which means the server
+     * confirmed it — two states, two strings.
+     */
+    staged: string;
+    /** Slot action when the position is empty. */
+    upload: string;
+    /** Slot action when the position is filled. */
+    replace: string;
+    /** Pill shown while a file hovers over a filled slot row. */
+    dropToReplace: string;
+    /** Viewer: aria-label of the previous-image arrow. */
+    previous: string;
+    /** Viewer: aria-label of the next-image arrow. */
+    next: string;
+    /** Fallback when a strategy rejects without a message. */
+    uploadFailed: string;
+    /** The request never reached the server — offline, DNS, CORS preflight. */
+    uploadNetworkFailed: string;
+    /** Message when the DELETE transport refused or failed. */
+    removeFailed: string;
+    /** A stored file could not be fetched for preview or for bytes. */
+    readFailed: string;
+    /** A batch past `maxFiles`. Receives the cap. */
+    maxFilesReached: (max: number) => string;
+    /** A file picked for a slot whose extension the slot rejects. */
+    slotFormatNotAllowed: (slotLabel: string, extensions: string[]) => string;
+    /** A bulk-dropped file no slot matched. */
+    fileWithoutSlot: (fileName: string) => string;
+    /** Viewer: while the URL resolves. */
+    viewerLoading: string;
+    /** Viewer: the URL could not be resolved (expired signature, network). */
+    viewerError: string;
+    /** Second line of the error panel — what the reader can do about it. */
+    viewerErrorHint: string;
+    /** Viewer: button that retries the resolution. */
+    viewerRetry: string;
+    /** Viewer: open the file in a browser tab. */
+    openInTab: string;
+    /** Header action; the long `download` names a file, this labels a button. */
+    downloadShort: string;
+    /** Viewer: close button. */
+    close: string;
+    /** Viewer: formats without an inline preview. */
+    noPreview: string;
+    /** Viewer: download button. Receives the file name. */
+    download: (fileName: string) => string;
+    /** Viewer: fallback title when the file carries no name. */
+    filePreview: string;
+    /** Confirm dialog: affirmative button. */
+    confirm: string;
+    /** Confirm dialog heading before forgetting a file. */
+    confirmRemoveTitle: string;
+    /** Confirm dialog body before forgetting. Receives the file name. */
+    confirmRemoveMessage: (fileName: string) => string;
+    /** Confirm dialog heading before replacing a slot's file. */
+    confirmReplaceTitle: string;
+    /** Confirm dialog body before replacing. Receives current and incoming names. */
+    confirmReplaceMessage: (current: string, incoming: string) => string;
+    /** `DropAnywhereOverlay` heading while a drag is over the window. */
+    dropAnywhereTitle: string;
+    /** `DropAnywhereOverlay` second line. */
+    dropAnywhereHint: string;
+    /** `AvatarUploader`: hover label and aria-label of the picture. */
+    avatarChange: string;
+    /** `AvatarUploader`: overlay while a file hovers the picture. */
+    avatarDropHere: string;
+    /** `AvatarUploader`: the remove link under the picture. */
+    avatarRemove: string;
+    /** `GalleryUploader`: caption of the add tile. */
+    galleryAdd: string;
+    /** A name the extension check cannot read at all. */
+    fileHasNoExtension: string;
+    /** The extension is not on the scope's list. Receives that list. */
+    formatNotAllowed: (extensions: string[]) => string;
+    /** Zero bytes — a failed drag, a cancelled save. */
+    fileIsEmpty: string;
+    /** Over the scope ceiling. Receives both sizes already formatted. */
+    fileTooLarge: (size: string, max: string) => string;
+    /** Fewer bytes than the signature needs: a truncated transfer. */
+    fileIncomplete: string;
+    /** The leading bytes contradict the extension — renamed, or corrupt. */
+    contentDoesNotMatchExtension: string;
+    /** 400: a route parameter or body field the handler needs is missing. */
+    requestIncomplete: string;
+    /** 401: `getUser` answered null. */
+    unauthorized: string;
+    /** 400: an upload arrived with no file part. */
+    fileRequired: string;
+    /** 404: the URL named a scope the registry does not declare. */
+    unknownScope: string;
+    /** 500: the catch-all when a handler throws something unrecognized. */
+    processingFailed: string;
+    /** Download name for a key that ends in nothing usable. */
+    unnamedFile: string;
+};
+/** Spanish copy — select it once: `<UploaderProvider language='es'>`. */
+declare const ES_LABELS: UploaderLabels;
+/** English copy — the package default, so the kit ships globalized. */
+declare const DEFAULT_LABELS: UploaderLabels;
+/** The merge every entry point runs: partial overrides over the default. */
+declare const resolveLabels: (labels?: Partial<UploaderLabels>, base?: UploaderLabels) => UploaderLabels;
+/**
+ * @deprecated English IS {@link DEFAULT_LABELS} now. A shallow copy, kept so
+ * 1.x consumers passing it keep working.
+ */
+declare const EN_LABELS: UploaderLabels;
+
+/**
+ * Every type in this file must be usable from a browser and from a server.
+ * That is what lets one scope definition drive the client's guards and the
+ * server's guards without the two drifting apart.
+ */
+type ImageExtension = 'png' | 'jpg' | 'jpeg' | 'svg' | 'webp' | 'gif' | 'ico' | 'heic';
+type CertificateExtension = 'cer' | 'crt' | 'pem';
+type KeyExtension = 'key';
+type DocumentExtension = 'pdf' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'csv' | 'txt';
+type DataExtension = 'xml' | 'json';
+type VideoExtension = 'mp4' | 'mov' | 'avi' | 'webm';
+type AudioExtension = 'mp3' | 'wav' | 'ogg' | 'aac';
+type FileExtension = ImageExtension | CertificateExtension | KeyExtension | DocumentExtension | DataExtension | VideoExtension | AudioExtension;
+/** Validation preset. Picks extensions, size ceiling and header checking. */
+type FileCategory = 'image' | 'certificate' | 'key' | 'pdf' | 'document' | 'data' | 'video' | 'audio' | 'any';
+type FileCategoryConfig = {
+    extensions: FileExtension[];
+    maxBytes: number;
+    /** Read the leading bytes to catch an .exe renamed to .pdf. */
+    validateMagicNumbers: boolean;
+    /** Lower-case singular noun used in error messages. */
+    label: string;
+    /** Value for an `<input accept="…">`. */
+    accept: string;
+};
+/**
+ * The subset of the DOM `File` this package needs. A browser `File`, a Node 18+
+ * `File` and a multer memory file (via `fromMulterFile`) all satisfy it, so
+ * `validateFile` is the same call on both sides of the wire.
+ */
+type FileLike = {
+    name: string;
+    size: number;
+    /** MIME type as reported by the source. Never trusted on its own. */
+    type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+};
+type UploadStatus = 'idle' | 'validating' | 'uploading' | 'success' | 'error';
+/** Machine-readable reason a file was rejected. Pair with `message` for UI. */
+type ValidationCode = 'extension-not-allowed' | 'too-large' | 'empty-file' | 'magic-number-mismatch' | 'mime-not-allowed' | 'custom';
+type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    code: ValidationCode;
+    message: string;
+};
+type ValidationOptions = {
+    maxBytes?: number;
+    allowedExtensions?: FileExtension[];
+    validateMagicNumbers?: boolean;
+    /**
+     * Copy for the messages these checks produce. Omitted means English — the
+     * same rule the rest of the package follows.
+     */
+    labels?: Partial<UploaderLabels>;
+    /** Runs last, only when every built-in check passed. */
+    customValidation?: (file: FileLike) => Promise<ValidationResult>;
+};
+/**
+ * Public files are served straight from their URL; private files are only ever
+ * reachable through a signed, expiring URL minted by the server.
+ */
+type Visibility = 'public' | 'private';
+/** Client-side image pipeline applied before upload. */
+type CompressOptions = {
+    maxWidth?: number;
+    maxHeight?: number;
+    /** 0–1. Ignored by formats without lossy encoding. */
+    quality?: number;
+    /**
+     * Drop EXIF metadata. Defaults to true: camera photos carry GPS
+     * coordinates, and a public bucket is the wrong place for them.
+     */
+    stripExif?: boolean;
+};
+/**
+ * What an upload does to what the entity already had.
+ *
+ * - `'entity'` — after the put, every other object under the entity's prefix
+ *   is deleted. The scope holds exactly one file and leaves no history.
+ * - `'key'` — only the object at the same key is replaced, siblings stay.
+ * - `false` — nothing is removed; the bucket keeps every version.
+ */
+type ReplaceMode = 'entity' | 'key' | false;
+/**
+ * A named destination. The single source of truth for where a file lands, who
+ * may read it, and what is accepted there.
+ */
+type ScopeConfig = {
+    /**
+     * Storage key for an upload. Receives the owning entity and the incoming
+     * file so the caller controls collisions and folder shape.
+     */
+    path: (entityId: string, file: FileLike) => string;
+    visibility: Visibility;
+    /** Extensions accepted here. Narrower than the category preset, never wider. */
+    accept: FileExtension[];
+    maxBytes: number;
+    category?: FileCategory;
+    /** Hand the bytes to the app's cipher before they leave the server. */
+    encrypt?: boolean;
+    compress?: CompressOptions;
+    /** Replace the object at the same key instead of adding a new one. */
+    overwrite?: boolean;
+    /**
+     * How many files one entity may hold here — on the scope, not on the
+     * uploader, so the server knows the arity too.
+     *
+     * @defaultValue 1
+     * @see AGENTS.md §3 — "Arity lives on the scope"
+     */
+    maxFiles?: number;
+    /**
+     * Overrides the derived replace mode. Rarely needed: the default already
+     * leaves no orphans.
+     */
+    replace?: ReplaceMode;
+    /**
+     * Objects an `'entity'` replace may delete. Defaults to the folder of the
+     * resolved key. Set it when that folder is shared with another scope.
+     */
+    prefix?: (entityId: string) => string;
+    /**
+     * This scope keeps its objects as HISTORY: the server refuses the DELETE
+     * route for it, so no client — buggy or malicious — can destroy the trail.
+     * The default is the opposite: removals are expected to delete from
+     * storage, because a scope with stable keys can never reclaim an orphan.
+     */
+    keepOnRemove?: boolean;
+    /** Documentation-only today; drives lifecycle rules once adapters read it. */
+    retention?: string;
+    /** Free-form tags forwarded to the provider when it supports metadata. */
+    metadata?: Record<string, string>;
+};
+type ScopeRegistry<T extends Record<string, ScopeConfig>> = {
+    scopes: T;
+    names: (keyof T & string)[];
+    get(name: string): ScopeConfig;
+    has(name: string): boolean;
+    /** `<input accept>` string for a scope, derived from its extensions. */
+    accept(name: keyof T & string): string;
+};
+/** What the app persists after a successful upload. */
+type StoredFile = {
+    /** Provider key. The handle for delete, re-sign and download. */
+    key: string;
+    /** Public URL, or a signed expiring URL when the scope is private. */
+    url: string;
+    scope: string;
+    entityId: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+    /** Enables dedupe and integrity checks when the provider reports it. */
+    checksum?: string;
+    uploadedAt: number;
+    uploadedBy?: string;
+};
+type PutInput = {
+    key: string;
+    body: Uint8Array;
+    contentType: string;
+    visibility: Visibility;
+    metadata?: Record<string, string>;
+};
+/**
+ * What a provider can actually do. Declared rather than discovered so a scope
+ * that needs signed URLs fails at boot, not the first time a user opens a file.
+ */
+type ProviderCapabilities = {
+    signedUrl: boolean;
+    resumable: boolean;
+    rangeRead: boolean;
+};
+type SignedUrlOptions = {
+    /** Seconds until the URL stops working. */
+    expiresIn: number;
+    /** Force a download instead of inline rendering. */
+    download?: boolean;
+};
+type StorageProvider = {
+    name: string;
+    capabilities: ProviderCapabilities;
+    put(input: PutInput): Promise<{
+        key: string;
+        url: string;
+        checksum?: string;
+    }>;
+    get(key: string): Promise<Uint8Array>;
+    delete(key: string): Promise<boolean>;
+    signedUrl?(key: string, options: SignedUrlOptions): Promise<string>;
+    list(prefix: string): Promise<{
+        key: string;
+        size: number;
+    }[]>;
+};
+/** Injected cipher for `encrypt: true` scopes. The package never ships one. */
+type CryptoHooks = {
+    encrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+    decrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+};
+
+export { type AudioExtension as A, type CertificateExtension as C, DEFAULT_LABELS as D, EN_LABELS as E, type FileCategory as F, type ImageExtension as I, type KeyExtension as K, type ProviderCapabilities as P, type ReplaceMode as R, type StorageProvider as S, type UploaderLabels as U, type Visibility as V, type FileCategoryConfig as a, type FileExtension as b, type FileLike as c, type ScopeConfig as d, type ScopeRegistry as e, type ValidationResult as f, type ValidationOptions as g, type CompressOptions as h, type CryptoHooks as i, type DataExtension as j, type DocumentExtension as k, ES_LABELS as l, type PutInput as m, type SignedUrlOptions as n, type StoredFile as o, type UploadStatus as p, type ValidationCode as q, type VideoExtension as r, resolveLabels as s };

package/dist/types-BSlJJwti.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Every user-facing string the package renders, so no copy is hardcoded
+ * inside a component and apps translate or reword without forking.
+ *
+ * English is the default so the kit ships globalized; `ES_LABELS` ships for
+ * Spanish apps, selected once through `UploaderProvider language='es'`. Hooks
+ * take `labels` in their options, components as a prop — always a `Partial`,
+ * merged over the provider's base.
+ */
+type UploaderLabels = {
+    /** Prompt inside the single dropzone of `Uploader` (fine pointers). */
+    dropPrompt: string;
+    /** Same zone on a touch device, where dragging barely exists. */
+    tapPrompt: string;
+    /** Prompt inside the bulk dropzone of `SlottedUploader` (fine pointers). */
+    bulkDropPrompt: string;
+    /** Same bulk zone on a touch device. */
+    bulkTapPrompt: string;
+    /** Button that fires the batch when `uploadOn` is `'manual'`. */
+    uploadAll: string;
+    /** Row action: preview a file. */
+    view: string;
+    /** Row action: forget a file. */
+    remove: string;
+    /** Row action: abort an in-flight upload. */
+    cancel: string;
+    /** Suffix on a row the server confirmed. */
+    ready: string;
+    /**
+     * Suffix on a row holding a picked file that has NOT been sent yet.
+     * Distinct from {@link UploaderLabels.ready}, which means the server
+     * confirmed it — two states, two strings.
+     */
+    staged: string;
+    /** Slot action when the position is empty. */
+    upload: string;
+    /** Slot action when the position is filled. */
+    replace: string;
+    /** Pill shown while a file hovers over a filled slot row. */
+    dropToReplace: string;
+    /** Viewer: aria-label of the previous-image arrow. */
+    previous: string;
+    /** Viewer: aria-label of the next-image arrow. */
+    next: string;
+    /** Fallback when a strategy rejects without a message. */
+    uploadFailed: string;
+    /** The request never reached the server — offline, DNS, CORS preflight. */
+    uploadNetworkFailed: string;
+    /** Message when the DELETE transport refused or failed. */
+    removeFailed: string;
+    /** A stored file could not be fetched for preview or for bytes. */
+    readFailed: string;
+    /** A batch past `maxFiles`. Receives the cap. */
+    maxFilesReached: (max: number) => string;
+    /** A file picked for a slot whose extension the slot rejects. */
+    slotFormatNotAllowed: (slotLabel: string, extensions: string[]) => string;
+    /** A bulk-dropped file no slot matched. */
+    fileWithoutSlot: (fileName: string) => string;
+    /** Viewer: while the URL resolves. */
+    viewerLoading: string;
+    /** Viewer: the URL could not be resolved (expired signature, network). */
+    viewerError: string;
+    /** Second line of the error panel — what the reader can do about it. */
+    viewerErrorHint: string;
+    /** Viewer: button that retries the resolution. */
+    viewerRetry: string;
+    /** Viewer: open the file in a browser tab. */
+    openInTab: string;
+    /** Header action; the long `download` names a file, this labels a button. */
+    downloadShort: string;
+    /** Viewer: close button. */
+    close: string;
+    /** Viewer: formats without an inline preview. */
+    noPreview: string;
+    /** Viewer: download button. Receives the file name. */
+    download: (fileName: string) => string;
+    /** Viewer: fallback title when the file carries no name. */
+    filePreview: string;
+    /** Confirm dialog: affirmative button. */
+    confirm: string;
+    /** Confirm dialog heading before forgetting a file. */
+    confirmRemoveTitle: string;
+    /** Confirm dialog body before forgetting. Receives the file name. */
+    confirmRemoveMessage: (fileName: string) => string;
+    /** Confirm dialog heading before replacing a slot's file. */
+    confirmReplaceTitle: string;
+    /** Confirm dialog body before replacing. Receives current and incoming names. */
+    confirmReplaceMessage: (current: string, incoming: string) => string;
+    /** `DropAnywhereOverlay` heading while a drag is over the window. */
+    dropAnywhereTitle: string;
+    /** `DropAnywhereOverlay` second line. */
+    dropAnywhereHint: string;
+    /** `AvatarUploader`: hover label and aria-label of the picture. */
+    avatarChange: string;
+    /** `AvatarUploader`: overlay while a file hovers the picture. */
+    avatarDropHere: string;
+    /** `AvatarUploader`: the remove link under the picture. */
+    avatarRemove: string;
+    /** `GalleryUploader`: caption of the add tile. */
+    galleryAdd: string;
+    /** A name the extension check cannot read at all. */
+    fileHasNoExtension: string;
+    /** The extension is not on the scope's list. Receives that list. */
+    formatNotAllowed: (extensions: string[]) => string;
+    /** Zero bytes — a failed drag, a cancelled save. */
+    fileIsEmpty: string;
+    /** Over the scope ceiling. Receives both sizes already formatted. */
+    fileTooLarge: (size: string, max: string) => string;
+    /** Fewer bytes than the signature needs: a truncated transfer. */
+    fileIncomplete: string;
+    /** The leading bytes contradict the extension — renamed, or corrupt. */
+    contentDoesNotMatchExtension: string;
+    /** 400: a route parameter or body field the handler needs is missing. */
+    requestIncomplete: string;
+    /** 401: `getUser` answered null. */
+    unauthorized: string;
+    /** 400: an upload arrived with no file part. */
+    fileRequired: string;
+    /** 404: the URL named a scope the registry does not declare. */
+    unknownScope: string;
+    /** 500: the catch-all when a handler throws something unrecognized. */
+    processingFailed: string;
+    /** Download name for a key that ends in nothing usable. */
+    unnamedFile: string;
+};
+/** Spanish copy — select it once: `<UploaderProvider language='es'>`. */
+declare const ES_LABELS: UploaderLabels;
+/** English copy — the package default, so the kit ships globalized. */
+declare const DEFAULT_LABELS: UploaderLabels;
+/** The merge every entry point runs: partial overrides over the default. */
+declare const resolveLabels: (labels?: Partial<UploaderLabels>, base?: UploaderLabels) => UploaderLabels;
+/**
+ * @deprecated English IS {@link DEFAULT_LABELS} now. A shallow copy, kept so
+ * 1.x consumers passing it keep working.
+ */
+declare const EN_LABELS: UploaderLabels;
+
+/**
+ * Every type in this file must be usable from a browser and from a server.
+ * That is what lets one scope definition drive the client's guards and the
+ * server's guards without the two drifting apart.
+ */
+type ImageExtension = 'png' | 'jpg' | 'jpeg' | 'svg' | 'webp' | 'gif' | 'ico' | 'heic';
+type CertificateExtension = 'cer' | 'crt' | 'pem';
+type KeyExtension = 'key';
+type DocumentExtension = 'pdf' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'csv' | 'txt';
+type DataExtension = 'xml' | 'json';
+type VideoExtension = 'mp4' | 'mov' | 'avi' | 'webm';
+type AudioExtension = 'mp3' | 'wav' | 'ogg' | 'aac';
+type FileExtension = ImageExtension | CertificateExtension | KeyExtension | DocumentExtension | DataExtension | VideoExtension | AudioExtension;
+/** Validation preset. Picks extensions, size ceiling and header checking. */
+type FileCategory = 'image' | 'certificate' | 'key' | 'pdf' | 'document' | 'data' | 'video' | 'audio' | 'any';
+type FileCategoryConfig = {
+    extensions: FileExtension[];
+    maxBytes: number;
+    /** Read the leading bytes to catch an .exe renamed to .pdf. */
+    validateMagicNumbers: boolean;
+    /** Lower-case singular noun used in error messages. */
+    label: string;
+    /** Value for an `<input accept="…">`. */
+    accept: string;
+};
+/**
+ * The subset of the DOM `File` this package needs. A browser `File`, a Node 18+
+ * `File` and a multer memory file (via `fromMulterFile`) all satisfy it, so
+ * `validateFile` is the same call on both sides of the wire.
+ */
+type FileLike = {
+    name: string;
+    size: number;
+    /** MIME type as reported by the source. Never trusted on its own. */
+    type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+};
+type UploadStatus = 'idle' | 'validating' | 'uploading' | 'success' | 'error';
+/** Machine-readable reason a file was rejected. Pair with `message` for UI. */
+type ValidationCode = 'extension-not-allowed' | 'too-large' | 'empty-file' | 'magic-number-mismatch' | 'mime-not-allowed' | 'custom';
+type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    code: ValidationCode;
+    message: string;
+};
+type ValidationOptions = {
+    maxBytes?: number;
+    allowedExtensions?: FileExtension[];
+    validateMagicNumbers?: boolean;
+    /**
+     * Copy for the messages these checks produce. Omitted means English — the
+     * same rule the rest of the package follows.
+     */
+    labels?: Partial<UploaderLabels>;
+    /** Runs last, only when every built-in check passed. */
+    customValidation?: (file: FileLike) => Promise<ValidationResult>;
+};
+/**
+ * Public files are served straight from their URL; private files are only ever
+ * reachable through a signed, expiring URL minted by the server.
+ */
+type Visibility = 'public' | 'private';
+/** Client-side image pipeline applied before upload. */
+type CompressOptions = {
+    maxWidth?: number;
+    maxHeight?: number;
+    /** 0–1. Ignored by formats without lossy encoding. */
+    quality?: number;
+    /**
+     * Drop EXIF metadata. Defaults to true: camera photos carry GPS
+     * coordinates, and a public bucket is the wrong place for them.
+     */
+    stripExif?: boolean;
+};
+/**
+ * What an upload does to what the entity already had.
+ *
+ * - `'entity'` — after the put, every other object under the entity's prefix
+ *   is deleted. The scope holds exactly one file and leaves no history.
+ * - `'key'` — only the object at the same key is replaced, siblings stay.
+ * - `false` — nothing is removed; the bucket keeps every version.
+ */
+type ReplaceMode = 'entity' | 'key' | false;
+/**
+ * A named destination. The single source of truth for where a file lands, who
+ * may read it, and what is accepted there.
+ */
+type ScopeConfig = {
+    /**
+     * Storage key for an upload. Receives the owning entity and the incoming
+     * file so the caller controls collisions and folder shape.
+     */
+    path: (entityId: string, file: FileLike) => string;
+    visibility: Visibility;
+    /** Extensions accepted here. Narrower than the category preset, never wider. */
+    accept: FileExtension[];
+    maxBytes: number;
+    category?: FileCategory;
+    /** Hand the bytes to the app's cipher before they leave the server. */
+    encrypt?: boolean;
+    compress?: CompressOptions;
+    /** Replace the object at the same key instead of adding a new one. */
+    overwrite?: boolean;
+    /**
+     * How many files one entity may hold here — on the scope, not on the
+     * uploader, so the server knows the arity too.
+     *
+     * @defaultValue 1
+     * @see AGENTS.md §3 — "Arity lives on the scope"
+     */
+    maxFiles?: number;
+    /**
+     * Overrides the derived replace mode. Rarely needed: the default already
+     * leaves no orphans.
+     */
+    replace?: ReplaceMode;
+    /**
+     * Objects an `'entity'` replace may delete. Defaults to the folder of the
+     * resolved key. Set it when that folder is shared with another scope.
+     */
+    prefix?: (entityId: string) => string;
+    /**
+     * This scope keeps its objects as HISTORY: the server refuses the DELETE
+     * route for it, so no client — buggy or malicious — can destroy the trail.
+     * The default is the opposite: removals are expected to delete from
+     * storage, because a scope with stable keys can never reclaim an orphan.
+     */
+    keepOnRemove?: boolean;
+    /** Documentation-only today; drives lifecycle rules once adapters read it. */
+    retention?: string;
+    /** Free-form tags forwarded to the provider when it supports metadata. */
+    metadata?: Record<string, string>;
+};
+type ScopeRegistry<T extends Record<string, ScopeConfig>> = {
+    scopes: T;
+    names: (keyof T & string)[];
+    get(name: string): ScopeConfig;
+    has(name: string): boolean;
+    /** `<input accept>` string for a scope, derived from its extensions. */
+    accept(name: keyof T & string): string;
+};
+/** What the app persists after a successful upload. */
+type StoredFile = {
+    /** Provider key. The handle for delete, re-sign and download. */
+    key: string;
+    /** Public URL, or a signed expiring URL when the scope is private. */
+    url: string;
+    scope: string;
+    entityId: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+    /** Enables dedupe and integrity checks when the provider reports it. */
+    checksum?: string;
+    uploadedAt: number;
+    uploadedBy?: string;
+};
+type PutInput = {
+    key: string;
+    body: Uint8Array;
+    contentType: string;
+    visibility: Visibility;
+    metadata?: Record<string, string>;
+};
+/**
+ * What a provider can actually do. Declared rather than discovered so a scope
+ * that needs signed URLs fails at boot, not the first time a user opens a file.
+ */
+type ProviderCapabilities = {
+    signedUrl: boolean;
+    resumable: boolean;
+    rangeRead: boolean;
+};
+type SignedUrlOptions = {
+    /** Seconds until the URL stops working. */
+    expiresIn: number;
+    /** Force a download instead of inline rendering. */
+    download?: boolean;
+};
+type StorageProvider = {
+    name: string;
+    capabilities: ProviderCapabilities;
+    put(input: PutInput): Promise<{
+        key: string;
+        url: string;
+        checksum?: string;
+    }>;
+    get(key: string): Promise<Uint8Array>;
+    delete(key: string): Promise<boolean>;
+    signedUrl?(key: string, options: SignedUrlOptions): Promise<string>;
+    list(prefix: string): Promise<{
+        key: string;
+        size: number;
+    }[]>;
+};
+/** Injected cipher for `encrypt: true` scopes. The package never ships one. */
+type CryptoHooks = {
+    encrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+    decrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+};
+
+export { type AudioExtension as A, type CertificateExtension as C, DEFAULT_LABELS as D, EN_LABELS as E, type FileCategory as F, type ImageExtension as I, type KeyExtension as K, type ProviderCapabilities as P, type ReplaceMode as R, type StorageProvider as S, type UploaderLabels as U, type Visibility as V, type FileCategoryConfig as a, type FileExtension as b, type FileLike as c, type ScopeConfig as d, type ScopeRegistry as e, type ValidationResult as f, type ValidationOptions as g, type CompressOptions as h, type CryptoHooks as i, type DataExtension as j, type DocumentExtension as k, ES_LABELS as l, type PutInput as m, type SignedUrlOptions as n, type StoredFile as o, type UploadStatus as p, type ValidationCode as q, type VideoExtension as r, resolveLabels as s };