@beignet/core/dist/uploads/client.d.ts

Core framework primitives for Beignet

import type { CompleteUploadResult, InferUploadMetadata, InferUploadResult, PreparedUploadFile, PrepareUploadResult, UploadDef, UploadFileConstraints, UploadFromRegistry, UploadManifestEntry, UploadRegistry } from "./index.js";
/**
 * Upload registry shape accepted by the typed browser client.
 *
 * Pass the type of a `defineUploads(...)` registry, or an upload definition
 * array, to `createUploadClient<...>()`.
 */
export type UploadClientRegistry = UploadRegistry | readonly UploadDef[];
/**
 * Union of upload route names available in an upload registry.
 */
export type UploadClientName<Registry> = UploadFromRegistry<Registry> extends UploadDef<infer Name> ? Name & string : never;
/**
 * Find one upload definition in a registry by its route name.
 */
export type UploadByName<Registry, Name extends string> = UploadFromRegistry<Registry> extends infer Upload ? Upload extends UploadDef ? Upload extends {
    readonly name: Name;
} ? Upload : never : never : never;
/**
 * Transport strategy used by `upload(...)`.
 */
export type UploadClientStrategy = "auto" | "direct" | "server";
/**
 * Fetch-compatible function used for upload route and direct provider
 * requests.
 */
export type UploadClientFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
/**
 * Static or lazy headers sent to Beignet upload route requests.
 */
export type UploadClientHeaders = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
/**
 * Request options shared by Beignet upload route requests.
 */
export interface UploadClientRequestOptions {
    /**
     * Browser credential policy for upload route requests.
     */
    credentials?: RequestCredentials;
    /**
     * Browser request mode for upload route requests.
     */
    mode?: RequestMode;
    /**
     * Browser cache policy for upload route requests.
     */
    cache?: RequestCache;
}
/**
 * Options for `createUploadClient(...)`.
 */
export interface CreateUploadClientOptions {
    /**
     * Base URL for the upload route.
     *
     * @default "/api/uploads"
     */
    baseUrl?: string;
    /**
     * Fetch implementation used for Beignet upload route requests.
     */
    fetch?: UploadClientFetch;
    /**
     * Headers sent to Beignet upload route requests. These are not sent to
     * provider-owned direct upload URLs.
     */
    headers?: UploadClientHeaders;
    /**
     * Request options shared by Beignet upload route requests.
     */
    request?: UploadClientRequestOptions;
    /**
     * Optional client-safe upload metadata for UI helpers.
     */
    manifest?: readonly UploadManifestEntry[];
}
/**
 * File lifecycle event emitted by direct and server upload helpers.
 */
export interface UploadClientFileEvent {
    /**
     * Browser `File` object being uploaded.
     */
    file: File;
    /**
     * File name supplied by the browser.
     */
    fileName: string;
    /**
     * Zero-based index from the files array passed by the caller.
     */
    index: number;
    /**
     * Prepared upload id when the file has gone through `prepare(...)`.
     */
    uploadId?: string;
    /**
     * Storage key when the file has gone through `prepare(...)`.
     */
    key?: string;
}
/**
 * Upload progress event emitted while a direct upload is in flight.
 */
export interface UploadClientProgressEvent extends UploadClientFileEvent {
    /**
     * Uploaded bytes.
     */
    loaded: number;
    /**
     * Total bytes expected for the file.
     */
    total: number;
    /**
     * Fraction from `0` to `1`.
     */
    progress: number;
}
/**
 * Per-call options shared by upload client route requests.
 */
export interface UploadClientRouteOptions {
    /**
     * Additional headers sent to Beignet upload route requests.
     */
    headers?: UploadClientHeaders;
    /**
     * Additional request options sent to Beignet upload route requests.
     */
    request?: UploadClientRequestOptions;
    /**
     * Abort signal used for route requests and direct uploads.
     */
    signal?: AbortSignal;
}
/**
 * Options for preparing an upload.
 */
export interface UploadClientPrepareOptions<Upload extends UploadDef> extends UploadClientRouteOptions {
    /**
     * Metadata validated by the upload definition.
     */
    metadata: InferUploadMetadata<Upload>;
    /**
     * Browser files to upload.
     */
    files: readonly File[];
}
/**
 * Options for direct, server, or automatic upload execution.
 */
export interface UploadClientUploadOptions<Upload extends UploadDef> extends UploadClientPrepareOptions<Upload> {
    /**
     * Upload transport strategy. Auto probes for direct-upload instructions and
     * falls back to server-handled multipart upload.
     *
     * @default "auto"
     */
    strategy?: UploadClientStrategy;
    /**
     * Called when a file is about to be uploaded.
     */
    onFileBegin?(event: UploadClientFileEvent): void;
    /**
     * Called with upload progress. Direct uploads use XHR when this callback is
     * provided so browsers can report progress events.
     */
    onProgress?(event: UploadClientProgressEvent): void;
}
/**
 * Browser upload client typed by an upload registry.
 */
export interface UploadClient<Registry extends UploadClientRegistry> {
    /**
     * Validate metadata and file intent, authorize the upload, and receive
     * storage keys plus direct upload instructions when a signer is configured.
     */
    prepare<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientPrepareOptions<UploadByName<Registry, Name>>): Promise<PrepareUploadResult>;
    /**
     * Complete a prepared direct upload after objects have been written to
     * storage.
     */
    complete<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientRouteOptions & {
        metadata: InferUploadMetadata<UploadByName<Registry, Name>>;
        files: readonly PreparedUploadFile[];
    }): Promise<CompleteUploadResult<InferUploadResult<UploadByName<Registry, Name>>>>;
    /**
     * Upload files through the Beignet application server using multipart form
     * data.
     */
    server<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientUploadOptions<UploadByName<Registry, Name>>): Promise<CompleteUploadResult<InferUploadResult<UploadByName<Registry, Name>>>>;
    /**
     * Require a direct provider upload flow: prepare, PUT each file to its
     * provider URL, then complete.
     */
    direct<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientUploadOptions<UploadByName<Registry, Name>>): Promise<CompleteUploadResult<InferUploadResult<UploadByName<Registry, Name>>>>;
    /**
     * Upload using the selected strategy. The default `"auto"` strategy uses a
     * direct provider flow when available and falls back to server multipart.
     */
    upload<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientUploadOptions<UploadByName<Registry, Name>>): Promise<CompleteUploadResult<InferUploadResult<UploadByName<Registry, Name>>>>;
    /**
     * Return manifest-backed file constraints for UI controls.
     */
    constraints<Name extends UploadClientName<Registry>>(uploadName: Name): UploadFileConstraints | undefined;
    /**
     * Return a comma-delimited file input `accept` value from manifest content
     * types.
     */
    accept<Name extends UploadClientName<Registry>>(uploadName: Name): string | undefined;
}
/**
 * Constructor options for `UploadClientError`.
 */
export interface UploadClientErrorOptions {
    /**
     * Client operation that failed.
     */
    operation: string;
    /**
     * Upload route name involved in the failure.
     */
    uploadName: string;
    /**
     * Human-readable error message.
     */
    message: string;
    /**
     * HTTP status when a route or provider response was received.
     */
    status?: number;
    /**
     * Machine-readable error code.
     */
    code?: string;
    /**
     * Structured error details from the upload route, when available.
     */
    details?: unknown;
    /**
     * Original error that caused the client failure.
     */
    cause?: unknown;
}
/**
 * Error thrown by upload client route requests or direct provider uploads.
 */
export declare class UploadClientError extends Error {
    /**
     * Client operation that failed.
     */
    readonly operation: string;
    /**
     * Upload route name involved in the failure.
     */
    readonly uploadName: string;
    /**
     * HTTP status when a route or provider response was received.
     */
    readonly status?: number;
    /**
     * Machine-readable error code.
     */
    readonly code?: string;
    /**
     * Structured error details from the upload route, when available.
     */
    readonly details?: unknown;
    /**
     * Create an upload client error.
     */
    constructor(options: UploadClientErrorOptions);
}
/**
 * Create a typed browser upload client for a Beignet upload route.
 */
export declare function createUploadClient<Registry extends UploadClientRegistry = UploadRegistry>(options?: CreateUploadClientOptions): UploadClient<Registry>;
//# sourceMappingURL=client.d.ts.map