@dloizides/content-upload 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -1,13 +1,38 @@
-# Changelog
-
-## 1.0.0
-
-Initial release (KEFI-PEOPLE-1 "Organizer people editor", task T3).
-
-- `uploadImage(file, options)`: multipart POST to a consumer-supplied endpoint; CSRF header,
-  credentials, client-side validation (empty / `maxBytes` / `allowedTypes`), abort, progress over
-  XMLHttpRequest, typed `UploadError` with `UploadErrorKind`.
-- `buildUploadRequest` for pinning the write shape (no Content-Type on FormData).
-- `blobFromUri(uri)`.
-- `useImageUpload(options)` hook: `UploadStatus` idle / uploading / error / done, progress,
-  supersede-on-new-upload, abort on reset and unmount.
+# Changelog
+
+## 1.2.0
+
+RUPEP-5 "Upload the RuPEP file from the Jobs tab" -- resumable tus upload.
+
+- `uploadResumable({ endpoint, file, metadata?, gzip?, chunkSize?, headers?, withCredentials?, onProgress?, signal?, uploadFactory? })`
+  resolves the tus upload id (last segment of the upload URL). Built on `tus-js-client` 4 (MIT).
+- 16 MiB chunks by default; cookies sent (`withCredentials`) unless `withCredentials: false`; `headers` carry the CSRF header.
+- `gzip: true` compresses with `CompressionStream` as a stream and uses tus deferred length (`encoding=gzip`).
+  Where `CompressionStream` is missing the file is uploaded as-is with `encoding=identity`.
+- Resume: a fingerprint of endpoint + size + lastModified + metadata is stored; the newest stored upload is resumed.
+  A gzip resume re-compresses from the start and skips the bytes already on the server (same engine = same bytes).
+- `signal` abort terminates the server upload (tus termination) and rejects with `UploadErrorKind.Aborted`.
+- Progress for gzip uploads counts source bytes read and holds at 99 until the upload finishes.
+
+## 1.1.0
+
+RUPEP-5 "Upload the RuPEP file from the Jobs tab".
+
+- `uploadFormWithProgress({ url, parts, headers?, onProgress?, signal?, withCredentials?, fetchImpl?, xhrFactory? })`:
+  generic multipart POST with progress; resolves parsed JSON (`null` for an empty 2xx body).
+  Credentials default to `include`; any Content-Type header is dropped; CSRF goes in `headers`.
+- `buildFormRequest(options)` to pin the write shape.
+- `UploadError.body` carries the raw response body of an `Http` failure (both transports).
+- `uploadImage` now shares the transport selection (`sendUploadRequest`); behaviour unchanged.
+
+## 1.0.0
+
+Initial release (KEFI-PEOPLE-1 "Organizer people editor", task T3).
+
+- `uploadImage(file, options)`: multipart POST to a consumer-supplied endpoint; CSRF header,
+  credentials, client-side validation (empty / `maxBytes` / `allowedTypes`), abort, progress over
+  XMLHttpRequest, typed `UploadError` with `UploadErrorKind`.
+- `buildUploadRequest` for pinning the write shape (no Content-Type on FormData).
+- `blobFromUri(uri)`.
+- `useImageUpload(options)` hook: `UploadStatus` idle / uploading / error / done, progress,
+  supersede-on-new-upload, abort on reset and unmount.

package/README.md

@@ -1,63 +1,101 @@
-# @dloizides/content-upload
-
-Image upload for the dloizides.com RN-web portals: one multipart POST to the ContentService
-through a same-origin BFF proxy, plus a React hook with `idle / uploading / error / done` states.
-Merged from kefi-web `uploadContent.ts` and katalogos-web `useUploadContent.ts`.
-
-## Install
-
-```bash
-npm install @dloizides/content-upload
-```
-
-Peer dependency: `react >= 18` (only for the hook).
-
-## Client
-
-```ts
-import { uploadImage, UploadError, UploadErrorKind } from '@dloizides/content-upload';
-
-const content = await uploadImage(file, {
-  endpoint: '/bff/api/content/api/v1/content/upload', // consumer-supplied
-  maxBytes: 5 * 1024 * 1024,
-  allowedTypes: ['image/png', 'image/jpeg', 'image/webp'],
-});
-// content = { contentId, status, url }
-```
-
-The request is `multipart/form-data` with fields `File`, `Category` (default `Image`) and
-`IsPublic` (default `true`), `credentials: 'include'` and the `X-BFF-Csrf: 1` anti-forgery header
-(`csrf: null` disables it, `csrf: { name, value }` replaces it). **No Content-Type is ever set**:
-the runtime adds the multipart boundary, and a JSON content type on a FormData body is a 415 (the
-same rule `@dloizides/bff-web-client`'s `writeContentTypeGuard` enforces for axios).
-
-Every failure throws `UploadError` with a `kind`: `Validation`, `Network`, `Http` (`status` set),
-`Aborted`, `InvalidResponse`. Map `kind` to translated copy; `message` is developer-facing.
-
-Transport: with `onProgress` and no `fetchImpl`, the upload uses `XMLHttpRequest` (the only
-transport that reports upload progress, available in browsers and React Native). Otherwise it
-uses `fetch`. `signal` aborts either.
-
-`blobFromUri(uri)` reads a `blob:` / `data:` / RN picker `file:` URI into a `Blob`.
-
-## Hook
-
-```ts
-import { useImageUpload, UploadStatus } from '@dloizides/content-upload';
-
-const { status, progress, error, result, upload, reset } = useImageUpload({
-  endpoint: '/bff/api/content/api/v1/content/upload',
-  onSuccess: (content) => setAvatarUrl(content.url),
-});
-
-await upload(file); // resolves to the content, or null on error / abort
-```
-
-- A new `upload()` or `reset()` aborts the in-flight request; its late result is dropped.
-- Unmount aborts the in-flight request.
-- Options are read at call time, so an inline options object is fine.
-
-## Scripts
-
-`npm run lint` · `npm run typecheck` · `npm run test:coverage` (100% threshold) · `npm run build`.
-Publish only via `./publish.ps1 -Bump <patch|minor|major>`.
+# @dloizides/content-upload
+
+Image upload for the dloizides.com RN-web portals: one multipart POST to the ContentService
+through a same-origin BFF proxy, plus a React hook with `idle / uploading / error / done` states.
+Merged from kefi-web `uploadContent.ts` and katalogos-web `useUploadContent.ts`.
+
+## Install
+
+```bash
+npm install @dloizides/content-upload
+```
+
+Peer dependency: `react >= 18` (only for the hook).
+
+## Client
+
+```ts
+import { uploadImage, UploadError, UploadErrorKind } from '@dloizides/content-upload';
+
+const content = await uploadImage(file, {
+  endpoint: '/bff/api/content/api/v1/content/upload', // consumer-supplied
+  maxBytes: 5 * 1024 * 1024,
+  allowedTypes: ['image/png', 'image/jpeg', 'image/webp'],
+});
+// content = { contentId, status, url }
+```
+
+The request is `multipart/form-data` with fields `File`, `Category` (default `Image`) and
+`IsPublic` (default `true`), `credentials: 'include'` and the `X-BFF-Csrf: 1` anti-forgery header
+(`csrf: null` disables it, `csrf: { name, value }` replaces it). **No Content-Type is ever set**:
+the runtime adds the multipart boundary, and a JSON content type on a FormData body is a 415 (the
+same rule `@dloizides/bff-web-client`'s `writeContentTypeGuard` enforces for axios).
+
+Every failure throws `UploadError` with a `kind`: `Validation`, `Network`, `Http` (`status` set),
+`Aborted`, `InvalidResponse`. Map `kind` to translated copy; `message` is developer-facing.
+
+Transport: with `onProgress` and no `fetchImpl`, the upload uses `XMLHttpRequest` (the only
+transport that reports upload progress, available in browsers and React Native). Otherwise it
+uses `fetch`. `signal` aborts either.
+
+`blobFromUri(uri)` reads a `blob:` / `data:` / RN picker `file:` URI into a `Blob`.
+
+## Generic multipart upload with progress
+
+```ts
+import { uploadFormWithProgress, UploadError, UploadErrorKind } from '@dloizides/content-upload';
+
+const result = await uploadFormWithProgress<{ jobId: string }>({
+  url: '/bff/api/aml/admin/jobs/rupep/upload',
+  parts: { file },
+  headers: { 'X-BFF-Csrf': '1' },
+  onProgress: (pct) => setPct(pct),
+  signal: controller.signal,
+});
+```
+
+Cookies are sent by default (`withCredentials: false` to opt out). A Content-Type header is
+dropped. An `Http` failure carries `error.status` and the raw `error.body`; an empty 2xx body
+resolves `null`.
+
+## Hook
+
+```ts
+import { useImageUpload, UploadStatus } from '@dloizides/content-upload';
+
+const { status, progress, error, result, upload, reset } = useImageUpload({
+  endpoint: '/bff/api/content/api/v1/content/upload',
+  onSuccess: (content) => setAvatarUrl(content.url),
+});
+
+await upload(file); // resolves to the content, or null on error / abort
+```
+
+- A new `upload()` or `reset()` aborts the in-flight request; its late result is dropped.
+- Unmount aborts the in-flight request.
+- Options are read at call time, so an inline options object is fine.
+
+## Scripts
+
+`npm run lint` · `npm run typecheck` · `npm run test:coverage` (100% threshold) · `npm run build`.
+Publish only via `./publish.ps1 -Bump <patch|minor|major>`.
+
+## Resumable upload (tus)
+
+```ts
+const id = await uploadResumable({
+  endpoint: '/bff/api/aml/v1/ingest/uploads',
+  file,
+  metadata: { part: 'persons' },
+  gzip: true,
+  headers: { 'X-BFF-Csrf': '1' },
+  onProgress: setPercent,
+  signal: controller.signal,
+});
+```
+
+- tus 1.0 via `tus-js-client`; 16 MiB chunks; cookies sent by default.
+- `gzip: true` streams through `CompressionStream` with deferred length (`encoding=gzip`); without
+  `CompressionStream` the file goes up uncompressed (`encoding=identity`). The server reads `encoding`.
+- Interrupted uploads resume from a stored fingerprint on the next call with the same file and metadata.
+- Aborting terminates the server-side upload.

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { UploadOptions, PreviousUpload } from 'tus-js-client';
+
 /** A header the BFF anti-forgery middleware requires on mutating requests. */
 interface CsrfHeader {
     name: string;
@@ -15,7 +17,7 @@ interface UploadedContent {
 /** Receives whole-number upload progress, 0-100. */
 type ProgressListener = (percent: number) => void;
 /** Options for `uploadImage`. Only `endpoint` is required. */
-interface UploadImageOptions {
+interface UploadImageOptions extends TransportOptions {
     /** Same-origin URL of the upload endpoint, e.g. `/bff/api/content/api/v1/content/upload`. */
     endpoint: string;
     /** Filename sent with the file part. Defaults to `File.name`, else `"upload"`. */
@@ -36,15 +38,19 @@ interface UploadImageOptions {
     allowedTypes?: readonly string[];
     /** Aborts the request; the promise rejects with `UploadErrorKind.Aborted`. */
     signal?: AbortSignal;
-    /**
-     * Progress listener. When set (and no `fetchImpl` is given) the upload goes over
-     * XMLHttpRequest, the only browser/RN transport that reports upload progress.
-     */
-    onProgress?: ProgressListener;
-    /** Custom fetch (tests, SSR). Forces the fetch transport. */
-    fetchImpl?: typeof fetch;
-    /** Custom XMLHttpRequest factory (tests). */
-    xhrFactory?: () => XMLHttpRequest;
+}
+/** Options for `uploadFormWithProgress`. Only `url` and `parts` are required. */
+interface UploadFormOptions extends TransportOptions {
+    /** Upload endpoint, e.g. a same-origin BFF route. */
+    url: string;
+    /** Multipart fields in insertion order; a Blob/File becomes a file part. */
+    parts: Record<string, Blob | string>;
+    /** Extra headers (e.g. a CSRF header). Any Content-Type is dropped: the runtime sets the boundary. */
+    headers?: Record<string, string>;
+    /** Send cookies (BFF session). Default `true`. */
+    withCredentials?: boolean;
+    /** Aborts the request; the promise rejects with `UploadErrorKind.Aborted`. */
+    signal?: AbortSignal;
 }
 
 /** A fully built multipart upload, independent of the transport that sends it. */
@@ -56,6 +62,15 @@ interface UploadRequest {
     credentials: RequestCredentials;
     signal: AbortSignal | undefined;
 }
+/** Transport selection knobs shared by every upload entry point. */
+interface TransportOptions {
+    /** When set (and no `fetchImpl`), the upload goes over XMLHttpRequest to report progress. */
+    onProgress?: ProgressListener;
+    /** Custom fetch (tests, SSR). Forces the fetch transport. */
+    fetchImpl?: typeof fetch;
+    /** Custom XMLHttpRequest factory (tests). */
+    xhrFactory?: () => XMLHttpRequest;
+}
 
 /** The Bff.AspNetCore anti-forgery convention: header presence, any value. */
 declare const DEFAULT_CSRF_HEADER: CsrfHeader;
@@ -72,6 +87,16 @@ declare function buildUploadRequest(file: Blob, options: UploadImageOptions): Up
  */
 declare function uploadImage(file: Blob, options: UploadImageOptions): Promise<UploadedContent>;
 
+/** Build the transport-independent request. Exported so consumers can pin the write shape. */
+declare function buildFormRequest(options: UploadFormOptions): UploadRequest;
+/**
+ * POST arbitrary multipart parts with optional upload progress; resolves the parsed JSON body
+ * (`null` for an empty 2xx body).
+ *
+ * @throws {UploadError} `Http` carries `status` and the raw `body`; switch on `error.kind`.
+ */
+declare function uploadFormWithProgress<T = unknown>(options: UploadFormOptions): Promise<T | null>;
+
 /**
  * Read a local URI (`blob:`, `data:`, or an RN image-picker `file:` URI) into a Blob so it
  * can be passed to `uploadImage`.
@@ -107,7 +132,9 @@ declare class UploadError extends Error {
     readonly kind: UploadErrorKind;
     /** HTTP status for `UploadErrorKind.Http`; undefined otherwise. */
     readonly status: number | undefined;
-    constructor(kind: UploadErrorKind, message: string, status?: number);
+    /** Raw response body for `UploadErrorKind.Http`; undefined otherwise. */
+    readonly body: string | undefined;
+    constructor(kind: UploadErrorKind, message: string, status?: number, body?: string);
 }
 /** Normalise anything thrown into an `UploadError` (unknown throws become `Network`). */
 declare function toUploadError(cause: unknown): UploadError;
@@ -138,4 +165,66 @@ interface UseImageUploadResult extends ImageUploadState {
  */
 declare function useImageUpload(options: UseImageUploadOptions): UseImageUploadResult;
 
-export { type CsrfHeader, DEFAULT_CSRF_HEADER, type ImageUploadState, type ProgressListener, UploadError, UploadErrorKind, type UploadImageOptions, type UploadRequest, UploadStatus, type UploadedContent, type UseImageUploadOptions, type UseImageUploadResult, blobFromUri, buildUploadRequest, toUploadError, uploadImage, useImageUpload };
+/** Value of the tus `encoding` metadata entry: how the uploaded bytes are encoded. */
+declare const enum UploadEncoding {
+    Gzip = "gzip",
+    Identity = "identity"
+}
+
+/** The read side of a byte stream, as tus-js-client accepts it. */
+type ByteReader = Pick<ReadableStreamDefaultReader<Uint8Array>, 'read'>;
+/** What tus-js-client uploads, and how its progress maps back to the source file. */
+interface ResumableSource {
+    input: Blob | ByteReader;
+    encoding: UploadEncoding;
+    lengthDeferred: boolean;
+    sourceBytesRead: () => number;
+}
+
+/** The part of a tus-js-client `Upload` that `uploadResumable` drives. */
+interface TusUpload {
+    url: string | null;
+    start(): void;
+    abort(shouldTerminate?: boolean): Promise<void>;
+    findPreviousUploads(): Promise<PreviousUpload[]>;
+    resumeFromPreviousUpload(previousUpload: PreviousUpload): void;
+}
+/** Builds the tus upload; injectable for tests. */
+type TusUploadFactory = (input: Blob | ByteReader, options: UploadOptions) => TusUpload;
+/** Options for `uploadResumable`. Only `endpoint` and `file` are required. */
+interface ResumableUploadOptions {
+    /** tus creation endpoint, e.g. `/bff/api/aml/v1/ingest/uploads`. */
+    endpoint: string;
+    file: Blob;
+    /** tus Upload-Metadata; `filename` defaults to `File.name`; `encoding` is always set by the client. */
+    metadata?: Record<string, string>;
+    /** Gzip the file as a stream (deferred length); falls back to identity when `CompressionStream` is missing. */
+    gzip?: boolean;
+    /** PATCH body size in bytes. Default 16 MiB (under the BFF 30 MB body limit). */
+    chunkSize?: number;
+    /** Extra request headers, e.g. the BFF CSRF header. */
+    headers?: Record<string, string>;
+    /** Send cookies (BFF session). Default `true`. */
+    withCredentials?: boolean;
+    onProgress?: ProgressListener;
+    /** Aborts and terminates the upload; the promise rejects with `UploadErrorKind.Aborted`. */
+    signal?: AbortSignal;
+    uploadFactory?: TusUploadFactory;
+}
+
+declare const DEFAULT_RESUMABLE_CHUNK_SIZE: number;
+interface UploadCallbacks {
+    onProgress: (bytesSent: number, bytesTotal: number) => void;
+    onSuccess: () => void;
+    onError: (error: Error) => void;
+}
+/** Upload-Metadata sent on creation: `filename` from the File unless given, `encoding` always from the source. */
+declare function buildResumableMetadata(file: Blob, metadata: Record<string, string> | undefined, encoding: UploadEncoding): Record<string, string>;
+/** Stable resume key: the same endpoint, file identity and metadata resume the same tus upload. */
+declare function resumeFingerprint(endpoint: string, file: Blob, metadata: Record<string, string>): string;
+/** The tus-js-client options for one upload. Exported so consumers can pin the request shape. */
+declare function buildTusOptions(options: ResumableUploadOptions, source: ResumableSource, callbacks: UploadCallbacks): UploadOptions;
+/** tus 1.0 resumable upload (16 MiB chunks, optional streamed gzip, fingerprint resume); resolves the upload id. */
+declare function uploadResumable(options: ResumableUploadOptions): Promise<string>;
+
+export { type ByteReader, type CsrfHeader, DEFAULT_CSRF_HEADER, DEFAULT_RESUMABLE_CHUNK_SIZE, type ImageUploadState, type ProgressListener, type ResumableUploadOptions, type TransportOptions, type TusUpload, type TusUploadFactory, UploadEncoding, UploadError, UploadErrorKind, type UploadFormOptions, type UploadImageOptions, type UploadRequest, UploadStatus, type UploadedContent, type UseImageUploadOptions, type UseImageUploadResult, blobFromUri, buildFormRequest, buildResumableMetadata, buildTusOptions, buildUploadRequest, resumeFingerprint, toUploadError, uploadFormWithProgress, uploadImage, uploadResumable, useImageUpload };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { UploadOptions, PreviousUpload } from 'tus-js-client';
+
 /** A header the BFF anti-forgery middleware requires on mutating requests. */
 interface CsrfHeader {
     name: string;
@@ -15,7 +17,7 @@ interface UploadedContent {
 /** Receives whole-number upload progress, 0-100. */
 type ProgressListener = (percent: number) => void;
 /** Options for `uploadImage`. Only `endpoint` is required. */
-interface UploadImageOptions {
+interface UploadImageOptions extends TransportOptions {
     /** Same-origin URL of the upload endpoint, e.g. `/bff/api/content/api/v1/content/upload`. */
     endpoint: string;
     /** Filename sent with the file part. Defaults to `File.name`, else `"upload"`. */
@@ -36,15 +38,19 @@ interface UploadImageOptions {
     allowedTypes?: readonly string[];
     /** Aborts the request; the promise rejects with `UploadErrorKind.Aborted`. */
     signal?: AbortSignal;
-    /**
-     * Progress listener. When set (and no `fetchImpl` is given) the upload goes over
-     * XMLHttpRequest, the only browser/RN transport that reports upload progress.
-     */
-    onProgress?: ProgressListener;
-    /** Custom fetch (tests, SSR). Forces the fetch transport. */
-    fetchImpl?: typeof fetch;
-    /** Custom XMLHttpRequest factory (tests). */
-    xhrFactory?: () => XMLHttpRequest;
+}
+/** Options for `uploadFormWithProgress`. Only `url` and `parts` are required. */
+interface UploadFormOptions extends TransportOptions {
+    /** Upload endpoint, e.g. a same-origin BFF route. */
+    url: string;
+    /** Multipart fields in insertion order; a Blob/File becomes a file part. */
+    parts: Record<string, Blob | string>;
+    /** Extra headers (e.g. a CSRF header). Any Content-Type is dropped: the runtime sets the boundary. */
+    headers?: Record<string, string>;
+    /** Send cookies (BFF session). Default `true`. */
+    withCredentials?: boolean;
+    /** Aborts the request; the promise rejects with `UploadErrorKind.Aborted`. */
+    signal?: AbortSignal;
 }
 
 /** A fully built multipart upload, independent of the transport that sends it. */
@@ -56,6 +62,15 @@ interface UploadRequest {
     credentials: RequestCredentials;
     signal: AbortSignal | undefined;
 }
+/** Transport selection knobs shared by every upload entry point. */
+interface TransportOptions {
+    /** When set (and no `fetchImpl`), the upload goes over XMLHttpRequest to report progress. */
+    onProgress?: ProgressListener;
+    /** Custom fetch (tests, SSR). Forces the fetch transport. */
+    fetchImpl?: typeof fetch;
+    /** Custom XMLHttpRequest factory (tests). */
+    xhrFactory?: () => XMLHttpRequest;
+}
 
 /** The Bff.AspNetCore anti-forgery convention: header presence, any value. */
 declare const DEFAULT_CSRF_HEADER: CsrfHeader;
@@ -72,6 +87,16 @@ declare function buildUploadRequest(file: Blob, options: UploadImageOptions): Up
  */
 declare function uploadImage(file: Blob, options: UploadImageOptions): Promise<UploadedContent>;
 
+/** Build the transport-independent request. Exported so consumers can pin the write shape. */
+declare function buildFormRequest(options: UploadFormOptions): UploadRequest;
+/**
+ * POST arbitrary multipart parts with optional upload progress; resolves the parsed JSON body
+ * (`null` for an empty 2xx body).
+ *
+ * @throws {UploadError} `Http` carries `status` and the raw `body`; switch on `error.kind`.
+ */
+declare function uploadFormWithProgress<T = unknown>(options: UploadFormOptions): Promise<T | null>;
+
 /**
  * Read a local URI (`blob:`, `data:`, or an RN image-picker `file:` URI) into a Blob so it
  * can be passed to `uploadImage`.
@@ -107,7 +132,9 @@ declare class UploadError extends Error {
     readonly kind: UploadErrorKind;
     /** HTTP status for `UploadErrorKind.Http`; undefined otherwise. */
     readonly status: number | undefined;
-    constructor(kind: UploadErrorKind, message: string, status?: number);
+    /** Raw response body for `UploadErrorKind.Http`; undefined otherwise. */
+    readonly body: string | undefined;
+    constructor(kind: UploadErrorKind, message: string, status?: number, body?: string);
 }
 /** Normalise anything thrown into an `UploadError` (unknown throws become `Network`). */
 declare function toUploadError(cause: unknown): UploadError;
@@ -138,4 +165,66 @@ interface UseImageUploadResult extends ImageUploadState {
  */
 declare function useImageUpload(options: UseImageUploadOptions): UseImageUploadResult;
 
-export { type CsrfHeader, DEFAULT_CSRF_HEADER, type ImageUploadState, type ProgressListener, UploadError, UploadErrorKind, type UploadImageOptions, type UploadRequest, UploadStatus, type UploadedContent, type UseImageUploadOptions, type UseImageUploadResult, blobFromUri, buildUploadRequest, toUploadError, uploadImage, useImageUpload };
+/** Value of the tus `encoding` metadata entry: how the uploaded bytes are encoded. */
+declare const enum UploadEncoding {
+    Gzip = "gzip",
+    Identity = "identity"
+}
+
+/** The read side of a byte stream, as tus-js-client accepts it. */
+type ByteReader = Pick<ReadableStreamDefaultReader<Uint8Array>, 'read'>;
+/** What tus-js-client uploads, and how its progress maps back to the source file. */
+interface ResumableSource {
+    input: Blob | ByteReader;
+    encoding: UploadEncoding;
+    lengthDeferred: boolean;
+    sourceBytesRead: () => number;
+}
+
+/** The part of a tus-js-client `Upload` that `uploadResumable` drives. */
+interface TusUpload {
+    url: string | null;
+    start(): void;
+    abort(shouldTerminate?: boolean): Promise<void>;
+    findPreviousUploads(): Promise<PreviousUpload[]>;
+    resumeFromPreviousUpload(previousUpload: PreviousUpload): void;
+}
+/** Builds the tus upload; injectable for tests. */
+type TusUploadFactory = (input: Blob | ByteReader, options: UploadOptions) => TusUpload;
+/** Options for `uploadResumable`. Only `endpoint` and `file` are required. */
+interface ResumableUploadOptions {
+    /** tus creation endpoint, e.g. `/bff/api/aml/v1/ingest/uploads`. */
+    endpoint: string;
+    file: Blob;
+    /** tus Upload-Metadata; `filename` defaults to `File.name`; `encoding` is always set by the client. */
+    metadata?: Record<string, string>;
+    /** Gzip the file as a stream (deferred length); falls back to identity when `CompressionStream` is missing. */
+    gzip?: boolean;
+    /** PATCH body size in bytes. Default 16 MiB (under the BFF 30 MB body limit). */
+    chunkSize?: number;
+    /** Extra request headers, e.g. the BFF CSRF header. */
+    headers?: Record<string, string>;
+    /** Send cookies (BFF session). Default `true`. */
+    withCredentials?: boolean;
+    onProgress?: ProgressListener;
+    /** Aborts and terminates the upload; the promise rejects with `UploadErrorKind.Aborted`. */
+    signal?: AbortSignal;
+    uploadFactory?: TusUploadFactory;
+}
+
+declare const DEFAULT_RESUMABLE_CHUNK_SIZE: number;
+interface UploadCallbacks {
+    onProgress: (bytesSent: number, bytesTotal: number) => void;
+    onSuccess: () => void;
+    onError: (error: Error) => void;
+}
+/** Upload-Metadata sent on creation: `filename` from the File unless given, `encoding` always from the source. */
+declare function buildResumableMetadata(file: Blob, metadata: Record<string, string> | undefined, encoding: UploadEncoding): Record<string, string>;
+/** Stable resume key: the same endpoint, file identity and metadata resume the same tus upload. */
+declare function resumeFingerprint(endpoint: string, file: Blob, metadata: Record<string, string>): string;
+/** The tus-js-client options for one upload. Exported so consumers can pin the request shape. */
+declare function buildTusOptions(options: ResumableUploadOptions, source: ResumableSource, callbacks: UploadCallbacks): UploadOptions;
+/** tus 1.0 resumable upload (16 MiB chunks, optional streamed gzip, fingerprint resume); resolves the upload id. */
+declare function uploadResumable(options: ResumableUploadOptions): Promise<string>;
+
+export { type ByteReader, type CsrfHeader, DEFAULT_CSRF_HEADER, DEFAULT_RESUMABLE_CHUNK_SIZE, type ImageUploadState, type ProgressListener, type ResumableUploadOptions, type TransportOptions, type TusUpload, type TusUploadFactory, UploadEncoding, UploadError, UploadErrorKind, type UploadFormOptions, type UploadImageOptions, type UploadRequest, UploadStatus, type UploadedContent, type UseImageUploadOptions, type UseImageUploadResult, blobFromUri, buildFormRequest, buildResumableMetadata, buildTusOptions, buildUploadRequest, resumeFingerprint, toUploadError, uploadFormWithProgress, uploadImage, uploadResumable, useImageUpload };