@ai-matrx/data 0.19.2 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.21.0 — the one upload transport
+
+- New subpath `@ai-matrx/data/files/tus`: `tusTransfer(file, { endpoint, filePath, metadata,
+  idempotencyKey, headers, onProgress, signal })` — the ONE resumable upload wire (fresh headers on
+  every request, idempotency key on creation only, `mtx-tus-urls` resume store, `X-Cld-File-Id`
+  capture with completed-session recovery), plus `buildUploadMetadataEnvelope`,
+  `createTusUrlStorage`, `listStoredTusUploads`, `TUS_CHUNK_SIZE_BYTES`, `TUS_UPLOAD_PATH`. Moved from
+  `@ai-matrx/media` (architecture step 14, D1); its own subpath so `./files` never loads tus-js-client.
+- `@ai-matrx/data/files` gains the upload dedup guard (`claimUpload`, `uploadDedupKey`), moved from media.
+- `fileUrls(filesBaseUrl, fileId)` is renamed `buildFileUrls(filesBaseUrl, fileId)`. `fileUrls(fileId)`
+  is the one caller-facing signature (media's host-bound builder); the old name stays as a deprecated
+  alias for this release only.
+
+Consumer action: replace `fileUrls(base, id)` from `@ai-matrx/data/files` with `buildFileUrls(base, id)`
+(no consumer app imports it today). A host needing resumable uploads injects `tusTransfer` instead of its own TUS client.
+
+## 0.20.0 — the one file error taxonomy
+
+- `FileErrorCode` gains media's codes (`cors_blocked`, `mime_unknown`, `upload_cancelled`,
+  `quota_exceeded`, `in_flight`), so `@ai-matrx/data/files`' `FileError` family is the one file
+  error taxonomy; media re-exports it (architecture step 14).
+
+Consumer action: none (additive).
+
 ## 0.19.2
 
 - Re-release of 0.19.1 (its publish stopped at the frozen-lockfile install: the tagged commit's

package/dist/files/tus.cjs

@@ -0,0 +1,245 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/files/tus.ts
+var tus_exports = {};
+__export(tus_exports, {
+  TUS_CHUNK_SIZE_BYTES: () => TUS_CHUNK_SIZE_BYTES,
+  TUS_UPLOAD_PATH: () => TUS_UPLOAD_PATH,
+  buildUploadMetadataEnvelope: () => buildUploadMetadataEnvelope,
+  createTusUrlStorage: () => createTusUrlStorage,
+  listStoredTusUploads: () => listStoredTusUploads,
+  tusTransfer: () => tusTransfer
+});
+module.exports = __toCommonJS(tus_exports);
+var tus = __toESM(require("tus-js-client"), 1);
+var TUS_CHUNK_SIZE_BYTES = 16 * 1024 * 1024;
+var TUS_UPLOAD_PATH = "/files/upload/tus";
+function buildUploadMetadataEnvelope(metadata) {
+  const envelope = {
+    // Origin tag aids backend log triage when something goes wrong.
+    origin: "cloudUpload",
+    ...metadata ?? {}
+  };
+  if (process.env.NODE_ENV !== "production" && !hasUploadOrganization(envelope)) {
+    console.warn(
+      "[buildUploadMetadataEnvelope] upload carries no scope.organization_id \u2014 it will be filed in an organization nobody chose. Route this upload through the host's organization gate before the bytes move."
+    );
+  }
+  return envelope;
+}
+function hasUploadOrganization(envelope) {
+  if (typeof envelope.organization_id === "string" && envelope.organization_id) return true;
+  const scope = envelope.scope;
+  return Boolean(
+    scope && typeof scope === "object" && typeof scope.organization_id === "string" && scope.organization_id
+  );
+}
+var URL_DB_NAME = "mtx-tus-urls";
+var URL_STORE = "urls";
+var urlDbPromise = null;
+function openUrlDb() {
+  if (urlDbPromise) return urlDbPromise;
+  urlDbPromise = new Promise((resolve, reject) => {
+    if (typeof indexedDB === "undefined") {
+      reject(new Error("[tusUpload] IndexedDB unavailable"));
+      return;
+    }
+    const req = indexedDB.open(URL_DB_NAME, 1);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(URL_STORE)) {
+        const store = db.createObjectStore(URL_STORE, { keyPath: "urlStorageKey" });
+        store.createIndex("fingerprint", "fingerprint", { unique: false });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("[tusUpload] failed to open mtx-tus-urls"));
+  });
+  urlDbPromise.catch(() => {
+    urlDbPromise = null;
+  });
+  return urlDbPromise;
+}
+function idbRequest(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("IndexedDB failed"));
+  });
+}
+function createTusUrlStorage() {
+  async function write(record, deleteKey) {
+    const db = await openUrlDb();
+    const tx = db.transaction(URL_STORE, "readwrite");
+    if (record) tx.objectStore(URL_STORE).put(record);
+    else if (deleteKey) tx.objectStore(URL_STORE).delete(deleteKey);
+    await new Promise((resolve, reject) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error ?? new Error("IndexedDB tx failed"));
+    });
+  }
+  return {
+    async findAllUploads() {
+      const db = await openUrlDb();
+      const tx = db.transaction(URL_STORE, "readonly");
+      return idbRequest(tx.objectStore(URL_STORE).getAll());
+    },
+    async findUploadsByFingerprint(fingerprint) {
+      const db = await openUrlDb();
+      const tx = db.transaction(URL_STORE, "readonly");
+      return idbRequest(
+        tx.objectStore(URL_STORE).index("fingerprint").getAll(fingerprint)
+      );
+    },
+    async removeUpload(urlStorageKey) {
+      await write(null, urlStorageKey);
+    },
+    async addUpload(fingerprint, upload) {
+      const urlStorageKey = `tus::${fingerprint}::${Date.now().toString(36)}`;
+      await write({
+        urlStorageKey,
+        fingerprint,
+        size: upload.size,
+        metadata: upload.metadata,
+        creationTime: upload.creationTime,
+        uploadUrl: upload.uploadUrl,
+        parallelUploadUrls: upload.parallelUploadUrls
+      });
+      return urlStorageKey;
+    }
+  };
+}
+async function listStoredTusUploads() {
+  try {
+    const db = await openUrlDb();
+    const tx = db.transaction(URL_STORE, "readonly");
+    const all = await idbRequest(tx.objectStore(URL_STORE).getAll());
+    return all.map((r) => ({
+      urlStorageKey: r.urlStorageKey,
+      fingerprint: r.fingerprint,
+      size: r.size,
+      metadata: r.metadata,
+      creationTime: r.creationTime,
+      uploadUrl: r.uploadUrl
+    }));
+  } catch (err) {
+    console.error("[tusUpload] listStoredTusUploads failed:", err);
+    return [];
+  }
+}
+var FORWARDED_HEADERS = ["Authorization", "X-Guest-Fingerprint", "X-Organization-Id"];
+function errorText(err) {
+  if (err instanceof Error) return err.message;
+  return typeof err === "string" ? err : String(err);
+}
+async function tusTransfer(file, opts) {
+  const fileName = typeof File !== "undefined" && file instanceof File ? file.name : opts.filePath.split("/").pop() ?? "upload";
+  const metadataEnvelope = buildUploadMetadataEnvelope(opts.metadata);
+  let cldFileId = null;
+  let aborted = false;
+  try {
+    await new Promise((resolve, reject) => {
+      const upload = new tus.Upload(file, {
+        endpoint: opts.endpoint,
+        chunkSize: TUS_CHUNK_SIZE_BYTES,
+        retryDelays: [0, 1e3, 3e3, 5e3, 1e4],
+        removeFingerprintOnSuccess: true,
+        urlStorage: opts.urlStorage ?? createTusUrlStorage(),
+        ...opts.httpStack ? { httpStack: opts.httpStack } : {},
+        ...opts.fileReader ? { fileReader: opts.fileReader } : {},
+        metadata: {
+          filename: fileName,
+          filepath: opts.filePath,
+          // tus-js-client base64-encodes the value per the Upload-Metadata
+          // spec; the server merges it exactly like the buffered form field.
+          metadata_json: JSON.stringify(metadataEnvelope),
+          ...opts.visibility ? { visibility: opts.visibility } : {}
+        },
+        onBeforeRequest: async (req) => {
+          const headers = await opts.headers();
+          for (const name of FORWARDED_HEADERS) {
+            const value = headers[name];
+            if (value) req.setHeader(name, value);
+          }
+          if (req.getMethod() === "POST") req.setHeader("X-Idempotency-Key", opts.idempotencyKey);
+        },
+        onAfterResponse: (_req, res) => {
+          const id = res.getHeader("X-Cld-File-Id");
+          if (id) cldFileId = id;
+        },
+        onProgress: (bytesSent, bytesTotal) => {
+          opts.onProgress?.(bytesSent, bytesTotal);
+        },
+        onSuccess: () => resolve(),
+        onError: (error) => reject(error)
+      });
+      if (opts.signal) {
+        if (opts.signal.aborted) {
+          aborted = true;
+          reject(new Error("Upload cancelled"));
+          return;
+        }
+        opts.signal.addEventListener(
+          "abort",
+          () => {
+            aborted = true;
+            void upload.abort();
+            reject(new Error("Upload cancelled"));
+          },
+          { once: true }
+        );
+      }
+      void upload.findPreviousUploads().then((previous) => {
+        const first = previous[0];
+        if (first) upload.resumeFromPreviousUpload(first);
+        upload.start();
+      }).catch((err) => {
+        console.warn("[tusUpload] previous-upload lookup failed \u2014 starting fresh:", err);
+        upload.start();
+      });
+    });
+  } catch (err) {
+    if (cldFileId && !aborted) {
+      console.warn(
+        `[tusUpload] transfer reported an error but the server exposed X-Cld-File-Id=${cldFileId} \u2014 recovering the completed session.`
+      );
+    } else {
+      return { ok: false, error: errorText(err), errorCode: aborted ? "upload_cancelled" : "tus_upload_failed" };
+    }
+  }
+  if (!cldFileId) {
+    return {
+      ok: false,
+      error: "TUS upload finished but the server never exposed X-Cld-File-Id \u2014 the file cannot be resolved. Check server CORS expose_headers.",
+      errorCode: "tus_missing_file_id"
+    };
+  }
+  return { ok: true, fileId: cldFileId };
+}
+//# sourceMappingURL=tus.cjs.map

package/dist/files/tus.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/files/tus.ts"],"sourcesContent":["/**\n * @ai-matrx/data/files/tus — the ONE resumable (TUS) upload transport.\n *\n * Origin: `@ai-matrx/media/files/engine/upload/tusUpload.ts` (architecture\n * step 14, D1: only byte transport moves to data). Media keeps the Redux\n * side and the record hydration; every host — the app, the extension, the\n * desktop — rides this one wire:\n *\n *   - creation POST carries `X-Idempotency-Key` (one intended upload, one key);\n *   - FRESH headers on EVERY request (long uploads outlive a JWT; the\n *     organization header must reach every chunk — aidream 8e5ee0b93 400s an\n *     unscoped upload);\n *   - one validated `metadata_json` envelope, byte-identical to the buffered\n *     form field ({@link buildUploadMetadataEnvelope});\n *   - automatic resume from the dedicated `mtx-tus-urls` IndexedDB store;\n *   - the created file id comes back in `X-Cld-File-Id`, including the\n *     completed-session recovery when the final response was lost.\n *\n * Its own subpath so `@ai-matrx/data/files` never loads tus-js-client.\n */\n\nimport * as tus from \"tus-js-client\";\n\n/** Server-bounded chunk size (8–32 MiB allowed): 16 MiB. */\nexport const TUS_CHUNK_SIZE_BYTES = 16 * 1024 * 1024;\n\n/** The TUS creation route on the files service. */\nexport const TUS_UPLOAD_PATH = \"/files/upload/tus\";\n\n// ─── Shared metadata envelope (buffered ↔ TUS parity) ────────────────────────\n\n/**\n * The ONE builder for the upload metadata JSON object. The buffered path\n * serializes it into the `metadata_json` form field; the TUS path serializes\n * the SAME object into the `metadata_json` Upload-Metadata key. One builder ⇒\n * the two transports can never drift.\n *\n * `scope.organization_id` is the OWNING WORKSPACE of the uploaded file. The\n * server stamps `files.files.organization_id` from it (membership-checked);\n * omitted, the server falls back to the uploader's own organization — a silent\n * mis-filing (2026-08-30). Loud in development, never a hard failure.\n */\nexport function buildUploadMetadataEnvelope(\n  metadata: Record<string, unknown> | undefined,\n): Record<string, unknown> {\n  const envelope: Record<string, unknown> = {\n    // Origin tag aids backend log triage when something goes wrong.\n    origin: \"cloudUpload\",\n    ...(metadata ?? {}),\n  };\n  if (process.env.NODE_ENV !== \"production\" && !hasUploadOrganization(envelope)) {\n    console.warn(\n      \"[buildUploadMetadataEnvelope] upload carries no scope.organization_id — \" +\n        \"it will be filed in an organization nobody chose. Route this \" +\n        \"upload through the host's organization gate before the bytes move.\",\n    );\n  }\n  return envelope;\n}\n\nfunction hasUploadOrganization(envelope: Record<string, unknown>): boolean {\n  if (typeof envelope.organization_id === \"string\" && envelope.organization_id) return true;\n  const scope = envelope.scope;\n  return Boolean(\n    scope &&\n      typeof scope === \"object\" &&\n      typeof (scope as Record<string, unknown>).organization_id === \"string\" &&\n      (scope as Record<string, unknown>).organization_id,\n  );\n}\n\n// ─── Dedicated resume-URL storage (mtx-tus-urls) ─────────────────────────────\n\nconst URL_DB_NAME = \"mtx-tus-urls\";\nconst URL_STORE = \"urls\";\n\ninterface StoredTusUpload {\n  urlStorageKey: string;\n  fingerprint: string;\n  size: number | null;\n  metadata: Record<string, string>;\n  creationTime: string;\n  uploadUrl: string | null;\n  parallelUploadUrls: string[] | null;\n}\n\nlet urlDbPromise: Promise<IDBDatabase> | null = null;\n\nfunction openUrlDb(): Promise<IDBDatabase> {\n  if (urlDbPromise) return urlDbPromise;\n  urlDbPromise = new Promise<IDBDatabase>((resolve, reject) => {\n    if (typeof indexedDB === \"undefined\") {\n      reject(new Error(\"[tusUpload] IndexedDB unavailable\"));\n      return;\n    }\n    const req = indexedDB.open(URL_DB_NAME, 1);\n    req.onupgradeneeded = () => {\n      const db = req.result;\n      if (!db.objectStoreNames.contains(URL_STORE)) {\n        const store = db.createObjectStore(URL_STORE, { keyPath: \"urlStorageKey\" });\n        store.createIndex(\"fingerprint\", \"fingerprint\", { unique: false });\n      }\n    };\n    req.onsuccess = () => resolve(req.result);\n    req.onerror = () => reject(req.error ?? new Error(\"[tusUpload] failed to open mtx-tus-urls\"));\n  });\n  urlDbPromise.catch(() => {\n    urlDbPromise = null;\n  });\n  return urlDbPromise;\n}\n\nfunction idbRequest<T>(req: IDBRequest<T>): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    req.onsuccess = () => resolve(req.result);\n    req.onerror = () => reject(req.error ?? new Error(\"IndexedDB failed\"));\n  });\n}\n\ntype PreviousUpload = Awaited<ReturnType<tus.Upload[\"findPreviousUploads\"]>>[number];\n\n/** tus-js-client HttpStack port (tests inject a mock wire). */\nexport type TusHttpStack = tus.HttpStack;\n/** tus-js-client file reader port (tests: Node builds cannot slice browser Files). */\nexport type TusFileReader = ConstructorParameters<typeof tus.Upload>[1][\"fileReader\"];\n\n/** tus-js-client UrlStorage port. */\nexport type TusUrlStorage = NonNullable<ConstructorParameters<typeof tus.Upload>[1][\"urlStorage\"]>;\n\n/** tus-js-client UrlStorage backed by the dedicated `mtx-tus-urls` DB —\n *  deliberately SEPARATE from any recorder chunk journal. */\nexport function createTusUrlStorage(): TusUrlStorage {\n  async function write(record: StoredTusUpload | null, deleteKey?: string): Promise<void> {\n    const db = await openUrlDb();\n    const tx = db.transaction(URL_STORE, \"readwrite\");\n    if (record) tx.objectStore(URL_STORE).put(record);\n    else if (deleteKey) tx.objectStore(URL_STORE).delete(deleteKey);\n    await new Promise<void>((resolve, reject) => {\n      tx.oncomplete = () => resolve();\n      tx.onerror = () => reject(tx.error ?? new Error(\"IndexedDB tx failed\"));\n    });\n  }\n  return {\n    async findAllUploads(): Promise<PreviousUpload[]> {\n      const db = await openUrlDb();\n      const tx = db.transaction(URL_STORE, \"readonly\");\n      return idbRequest(tx.objectStore(URL_STORE).getAll() as IDBRequest<StoredTusUpload[]>);\n    },\n    async findUploadsByFingerprint(fingerprint: string): Promise<PreviousUpload[]> {\n      const db = await openUrlDb();\n      const tx = db.transaction(URL_STORE, \"readonly\");\n      return idbRequest(\n        tx.objectStore(URL_STORE).index(\"fingerprint\").getAll(fingerprint) as IDBRequest<StoredTusUpload[]>,\n      );\n    },\n    async removeUpload(urlStorageKey: string): Promise<void> {\n      await write(null, urlStorageKey);\n    },\n    async addUpload(fingerprint: string, upload: PreviousUpload): Promise<string> {\n      const urlStorageKey = `tus::${fingerprint}::${Date.now().toString(36)}`;\n      await write({\n        urlStorageKey,\n        fingerprint,\n        size: upload.size,\n        metadata: upload.metadata,\n        creationTime: upload.creationTime,\n        uploadUrl: upload.uploadUrl,\n        parallelUploadUrls: upload.parallelUploadUrls,\n      });\n      return urlStorageKey;\n    },\n  };\n}\n\n/** Read-only summary of a stored TUS resume session (diagnostics surfaces). */\nexport interface StoredTusUploadSummary {\n  urlStorageKey: string;\n  fingerprint: string;\n  size: number | null;\n  metadata: Record<string, string>;\n  creationTime: string;\n  uploadUrl: string | null;\n}\n\n/**\n * List every stored TUS resume-URL entry. Read-only — resuming happens inside\n * {@link tusTransfer}; this only lets management surfaces SHOW a pending\n * session. Returns [] where IndexedDB is unavailable (never throws).\n */\nexport async function listStoredTusUploads(): Promise<StoredTusUploadSummary[]> {\n  try {\n    const db = await openUrlDb();\n    const tx = db.transaction(URL_STORE, \"readonly\");\n    const all = await idbRequest(tx.objectStore(URL_STORE).getAll() as IDBRequest<StoredTusUpload[]>);\n    return all.map((r) => ({\n      urlStorageKey: r.urlStorageKey,\n      fingerprint: r.fingerprint,\n      size: r.size,\n      metadata: r.metadata,\n      creationTime: r.creationTime,\n      uploadUrl: r.uploadUrl,\n    }));\n  } catch (err) {\n    console.error(\"[tusUpload] listStoredTusUploads failed:\", err);\n    return [];\n  }\n}\n\n// ─── The transport ───────────────────────────────────────────────────────────\n\nexport interface TusTransferOptions {\n  /** Full creation URL (`{filesBase}${TUS_UPLOAD_PATH}`). */\n  endpoint: string;\n  /** Destination path including the file name. */\n  filePath: string;\n  /** Caller metadata; wrapped by {@link buildUploadMetadataEnvelope}. */\n  metadata?: Record<string, unknown> | undefined;\n  /** Optional Upload-Metadata `visibility` (transitional wire input). */\n  visibility?: string | undefined;\n  /** One intended upload, one key — sent on the creation POST only. */\n  idempotencyKey: string;\n  /**\n   * FRESH request headers, read before EVERY request. Only `Authorization`,\n   * `X-Guest-Fingerprint` and `X-Organization-Id` are forwarded.\n   */\n  headers: () => Promise<Record<string, string | undefined>>;\n  onProgress?: ((loaded: number, total: number) => void) | undefined;\n  signal?: AbortSignal | undefined;\n  /** Injected HttpStack (tests: mock wire, no XHR). */\n  httpStack?: TusHttpStack | undefined;\n  /** Injected file reader (tests: Node builds cannot slice browser Files). */\n  fileReader?: TusFileReader | undefined;\n  /** Override URL storage (tests). Default: {@link createTusUrlStorage}. */\n  urlStorage?: TusUrlStorage | undefined;\n}\n\nexport type TusTransferErrorCode = \"upload_cancelled\" | \"tus_upload_failed\" | \"tus_missing_file_id\";\n\nexport type TusTransferResult =\n  | { ok: true; fileId: string }\n  | { ok: false; error: string; errorCode: TusTransferErrorCode };\n\nconst FORWARDED_HEADERS = [\"Authorization\", \"X-Guest-Fingerprint\", \"X-Organization-Id\"] as const;\n\nfunction errorText(err: unknown): string {\n  if (err instanceof Error) return err.message;\n  return typeof err === \"string\" ? err : String(err);\n}\n\n/**\n * Resumable upload of one file. Never throws — `{ ok: false, errorCode }` on\n * failure. Resumes a previous session for the same file automatically; when the\n * transfer errors but the server already exposed `X-Cld-File-Id`, the completed\n * session is recovered (loudly) instead of failing or re-uploading.\n */\nexport async function tusTransfer(file: File | Blob, opts: TusTransferOptions): Promise<TusTransferResult> {\n  const fileName = typeof File !== \"undefined\" && file instanceof File ? file.name : opts.filePath.split(\"/\").pop() ?? \"upload\";\n  const metadataEnvelope = buildUploadMetadataEnvelope(opts.metadata);\n  let cldFileId: string | null = null;\n  let aborted = false;\n\n  try {\n    await new Promise<void>((resolve, reject) => {\n      const upload: tus.Upload = new tus.Upload(file, {\n        endpoint: opts.endpoint,\n        chunkSize: TUS_CHUNK_SIZE_BYTES,\n        retryDelays: [0, 1000, 3000, 5000, 10000],\n        removeFingerprintOnSuccess: true,\n        urlStorage: opts.urlStorage ?? createTusUrlStorage(),\n        ...(opts.httpStack ? { httpStack: opts.httpStack } : {}),\n        ...(opts.fileReader ? { fileReader: opts.fileReader } : {}),\n        metadata: {\n          filename: fileName,\n          filepath: opts.filePath,\n          // tus-js-client base64-encodes the value per the Upload-Metadata\n          // spec; the server merges it exactly like the buffered form field.\n          metadata_json: JSON.stringify(metadataEnvelope),\n          ...(opts.visibility ? { visibility: opts.visibility } : {}),\n        },\n        onBeforeRequest: async (req) => {\n          const headers = await opts.headers();\n          for (const name of FORWARDED_HEADERS) {\n            const value = headers[name];\n            if (value) req.setHeader(name, value);\n          }\n          if (req.getMethod() === \"POST\") req.setHeader(\"X-Idempotency-Key\", opts.idempotencyKey);\n        },\n        onAfterResponse: (_req, res) => {\n          const id = res.getHeader(\"X-Cld-File-Id\");\n          if (id) cldFileId = id;\n        },\n        onProgress: (bytesSent, bytesTotal) => {\n          opts.onProgress?.(bytesSent, bytesTotal);\n        },\n        onSuccess: () => resolve(),\n        onError: (error) => reject(error),\n      });\n\n      if (opts.signal) {\n        if (opts.signal.aborted) {\n          aborted = true;\n          reject(new Error(\"Upload cancelled\"));\n          return;\n        }\n        opts.signal.addEventListener(\n          \"abort\",\n          () => {\n            aborted = true;\n            void upload.abort();\n            reject(new Error(\"Upload cancelled\"));\n          },\n          { once: true },\n        );\n      }\n\n      void upload\n        .findPreviousUploads()\n        .then((previous) => {\n          const first = previous[0];\n          if (first) upload.resumeFromPreviousUpload(first);\n          upload.start();\n        })\n        .catch((err) => {\n          console.warn(\"[tusUpload] previous-upload lookup failed — starting fresh:\", err);\n          upload.start();\n        });\n    });\n  } catch (err) {\n    if (cldFileId && !aborted) {\n      console.warn(\n        `[tusUpload] transfer reported an error but the server exposed ` +\n          `X-Cld-File-Id=${cldFileId} — recovering the completed session.`,\n      );\n    } else {\n      return { ok: false, error: errorText(err), errorCode: aborted ? \"upload_cancelled\" : \"tus_upload_failed\" };\n    }\n  }\n\n  if (!cldFileId) {\n    return {\n      ok: false,\n      error:\n        \"TUS upload finished but the server never exposed X-Cld-File-Id — \" +\n        \"the file cannot be resolved. Check server CORS expose_headers.\",\n      errorCode: \"tus_missing_file_id\",\n    };\n  }\n  return { ok: true, fileId: cldFileId };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,UAAqB;AAGd,IAAM,uBAAuB,KAAK,OAAO;AAGzC,IAAM,kBAAkB;AAexB,SAAS,4BACd,UACyB;AACzB,QAAM,WAAoC;AAAA;AAAA,IAExC,QAAQ;AAAA,IACR,GAAI,YAAY,CAAC;AAAA,EACnB;AACA,MAAI,yBAAyB,gBAAgB,CAAC,sBAAsB,QAAQ,GAAG;AAC7E,YAAQ;AAAA,MACN;AAAA,IAGF;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,sBAAsB,UAA4C;AACzE,MAAI,OAAO,SAAS,oBAAoB,YAAY,SAAS,gBAAiB,QAAO;AACrF,QAAM,QAAQ,SAAS;AACvB,SAAO;AAAA,IACL,SACE,OAAO,UAAU,YACjB,OAAQ,MAAkC,oBAAoB,YAC7D,MAAkC;AAAA,EACvC;AACF;AAIA,IAAM,cAAc;AACpB,IAAM,YAAY;AAYlB,IAAI,eAA4C;AAEhD,SAAS,YAAkC;AACzC,MAAI,aAAc,QAAO;AACzB,iBAAe,IAAI,QAAqB,CAAC,SAAS,WAAW;AAC3D,QAAI,OAAO,cAAc,aAAa;AACpC,aAAO,IAAI,MAAM,mCAAmC,CAAC;AACrD;AAAA,IACF;AACA,UAAM,MAAM,UAAU,KAAK,aAAa,CAAC;AACzC,QAAI,kBAAkB,MAAM;AAC1B,YAAM,KAAK,IAAI;AACf,UAAI,CAAC,GAAG,iBAAiB,SAAS,SAAS,GAAG;AAC5C,cAAM,QAAQ,GAAG,kBAAkB,WAAW,EAAE,SAAS,gBAAgB,CAAC;AAC1E,cAAM,YAAY,eAAe,eAAe,EAAE,QAAQ,MAAM,CAAC;AAAA,MACnE;AAAA,IACF;AACA,QAAI,YAAY,MAAM,QAAQ,IAAI,MAAM;AACxC,QAAI,UAAU,MAAM,OAAO,IAAI,SAAS,IAAI,MAAM,yCAAyC,CAAC;AAAA,EAC9F,CAAC;AACD,eAAa,MAAM,MAAM;AACvB,mBAAe;AAAA,EACjB,CAAC;AACD,SAAO;AACT;AAEA,SAAS,WAAc,KAAgC;AACrD,SAAO,IAAI,QAAW,CAAC,SAAS,WAAW;AACzC,QAAI,YAAY,MAAM,QAAQ,IAAI,MAAM;AACxC,QAAI,UAAU,MAAM,OAAO,IAAI,SAAS,IAAI,MAAM,kBAAkB,CAAC;AAAA,EACvE,CAAC;AACH;AAcO,SAAS,sBAAqC;AACnD,iBAAe,MAAM,QAAgC,WAAmC;AACtF,UAAM,KAAK,MAAM,UAAU;AAC3B,UAAM,KAAK,GAAG,YAAY,WAAW,WAAW;AAChD,QAAI,OAAQ,IAAG,YAAY,SAAS,EAAE,IAAI,MAAM;AAAA,aACvC,UAAW,IAAG,YAAY,SAAS,EAAE,OAAO,SAAS;AAC9D,UAAM,IAAI,QAAc,CAAC,SAAS,WAAW;AAC3C,SAAG,aAAa,MAAM,QAAQ;AAC9B,SAAG,UAAU,MAAM,OAAO,GAAG,SAAS,IAAI,MAAM,qBAAqB,CAAC;AAAA,IACxE,CAAC;AAAA,EACH;AACA,SAAO;AAAA,IACL,MAAM,iBAA4C;AAChD,YAAM,KAAK,MAAM,UAAU;AAC3B,YAAM,KAAK,GAAG,YAAY,WAAW,UAAU;AAC/C,aAAO,WAAW,GAAG,YAAY,SAAS,EAAE,OAAO,CAAkC;AAAA,IACvF;AAAA,IACA,MAAM,yBAAyB,aAAgD;AAC7E,YAAM,KAAK,MAAM,UAAU;AAC3B,YAAM,KAAK,GAAG,YAAY,WAAW,UAAU;AAC/C,aAAO;AAAA,QACL,GAAG,YAAY,SAAS,EAAE,MAAM,aAAa,EAAE,OAAO,WAAW;AAAA,MACnE;AAAA,IACF;AAAA,IACA,MAAM,aAAa,eAAsC;AACvD,YAAM,MAAM,MAAM,aAAa;AAAA,IACjC;AAAA,IACA,MAAM,UAAU,aAAqB,QAAyC;AAC5E,YAAM,gBAAgB,QAAQ,WAAW,KAAK,KAAK,IAAI,EAAE,SAAS,EAAE,CAAC;AACrE,YAAM,MAAM;AAAA,QACV;AAAA,QACA;AAAA,QACA,MAAM,OAAO;AAAA,QACb,UAAU,OAAO;AAAA,QACjB,cAAc,OAAO;AAAA,QACrB,WAAW,OAAO;AAAA,QAClB,oBAAoB,OAAO;AAAA,MAC7B,CAAC;AACD,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAiBA,eAAsB,uBAA0D;AAC9E,MAAI;AACF,UAAM,KAAK,MAAM,UAAU;AAC3B,UAAM,KAAK,GAAG,YAAY,WAAW,UAAU;AAC/C,UAAM,MAAM,MAAM,WAAW,GAAG,YAAY,SAAS,EAAE,OAAO,CAAkC;AAChG,WAAO,IAAI,IAAI,CAAC,OAAO;AAAA,MACrB,eAAe,EAAE;AAAA,MACjB,aAAa,EAAE;AAAA,MACf,MAAM,EAAE;AAAA,MACR,UAAU,EAAE;AAAA,MACZ,cAAc,EAAE;AAAA,MAChB,WAAW,EAAE;AAAA,IACf,EAAE;AAAA,EACJ,SAAS,KAAK;AACZ,YAAQ,MAAM,4CAA4C,GAAG;AAC7D,WAAO,CAAC;AAAA,EACV;AACF;AAoCA,IAAM,oBAAoB,CAAC,iBAAiB,uBAAuB,mBAAmB;AAEtF,SAAS,UAAU,KAAsB;AACvC,MAAI,eAAe,MAAO,QAAO,IAAI;AACrC,SAAO,OAAO,QAAQ,WAAW,MAAM,OAAO,GAAG;AACnD;AAQA,eAAsB,YAAY,MAAmB,MAAsD;AACzG,QAAM,WAAW,OAAO,SAAS,eAAe,gBAAgB,OAAO,KAAK,OAAO,KAAK,SAAS,MAAM,GAAG,EAAE,IAAI,KAAK;AACrH,QAAM,mBAAmB,4BAA4B,KAAK,QAAQ;AAClE,MAAI,YAA2B;AAC/B,MAAI,UAAU;AAEd,MAAI;AACF,UAAM,IAAI,QAAc,CAAC,SAAS,WAAW;AAC3C,YAAM,SAAqB,IAAQ,WAAO,MAAM;AAAA,QAC9C,UAAU,KAAK;AAAA,QACf,WAAW;AAAA,QACX,aAAa,CAAC,GAAG,KAAM,KAAM,KAAM,GAAK;AAAA,QACxC,4BAA4B;AAAA,QAC5B,YAAY,KAAK,cAAc,oBAAoB;AAAA,QACnD,GAAI,KAAK,YAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;AAAA,QACtD,GAAI,KAAK,aAAa,EAAE,YAAY,KAAK,WAAW,IAAI,CAAC;AAAA,QACzD,UAAU;AAAA,UACR,UAAU;AAAA,UACV,UAAU,KAAK;AAAA;AAAA;AAAA,UAGf,eAAe,KAAK,UAAU,gBAAgB;AAAA,UAC9C,GAAI,KAAK,aAAa,EAAE,YAAY,KAAK,WAAW,IAAI,CAAC;AAAA,QAC3D;AAAA,QACA,iBAAiB,OAAO,QAAQ;AAC9B,gBAAM,UAAU,MAAM,KAAK,QAAQ;AACnC,qBAAW,QAAQ,mBAAmB;AACpC,kBAAM,QAAQ,QAAQ,IAAI;AAC1B,gBAAI,MAAO,KAAI,UAAU,MAAM,KAAK;AAAA,UACtC;AACA,cAAI,IAAI,UAAU,MAAM,OAAQ,KAAI,UAAU,qBAAqB,KAAK,cAAc;AAAA,QACxF;AAAA,QACA,iBAAiB,CAAC,MAAM,QAAQ;AAC9B,gBAAM,KAAK,IAAI,UAAU,eAAe;AACxC,cAAI,GAAI,aAAY;AAAA,QACtB;AAAA,QACA,YAAY,CAAC,WAAW,eAAe;AACrC,eAAK,aAAa,WAAW,UAAU;AAAA,QACzC;AAAA,QACA,WAAW,MAAM,QAAQ;AAAA,QACzB,SAAS,CAAC,UAAU,OAAO,KAAK;AAAA,MAClC,CAAC;AAED,UAAI,KAAK,QAAQ;AACf,YAAI,KAAK,OAAO,SAAS;AACvB,oBAAU;AACV,iBAAO,IAAI,MAAM,kBAAkB,CAAC;AACpC;AAAA,QACF;AACA,aAAK,OAAO;AAAA,UACV;AAAA,UACA,MAAM;AACJ,sBAAU;AACV,iBAAK,OAAO,MAAM;AAClB,mBAAO,IAAI,MAAM,kBAAkB,CAAC;AAAA,UACtC;AAAA,UACA,EAAE,MAAM,KAAK;AAAA,QACf;AAAA,MACF;AAEA,WAAK,OACF,oBAAoB,EACpB,KAAK,CAAC,aAAa;AAClB,cAAM,QAAQ,SAAS,CAAC;AACxB,YAAI,MAAO,QAAO,yBAAyB,KAAK;AAChD,eAAO,MAAM;AAAA,MACf,CAAC,EACA,MAAM,CAAC,QAAQ;AACd,gBAAQ,KAAK,oEAA+D,GAAG;AAC/E,eAAO,MAAM;AAAA,MACf,CAAC;AAAA,IACL,CAAC;AAAA,EACH,SAAS,KAAK;AACZ,QAAI,aAAa,CAAC,SAAS;AACzB,cAAQ;AAAA,QACN,+EACmB,SAAS;AAAA,MAC9B;AAAA,IACF,OAAO;AACL,aAAO,EAAE,IAAI,OAAO,OAAO,UAAU,GAAG,GAAG,WAAW,UAAU,qBAAqB,oBAAoB;AAAA,IAC3G;AAAA,EACF;AAEA,MAAI,CAAC,WAAW;AACd,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,OACE;AAAA,MAEF,WAAW;AAAA,IACb;AAAA,EACF;AACA,SAAO,EAAE,IAAI,MAAM,QAAQ,UAAU;AACvC;","names":[]}

package/dist/files/tus.d.cts

@@ -0,0 +1,106 @@
+import * as tus from 'tus-js-client';
+
+/**
+ * @ai-matrx/data/files/tus — the ONE resumable (TUS) upload transport.
+ *
+ * Origin: `@ai-matrx/media/files/engine/upload/tusUpload.ts` (architecture
+ * step 14, D1: only byte transport moves to data). Media keeps the Redux
+ * side and the record hydration; every host — the app, the extension, the
+ * desktop — rides this one wire:
+ *
+ *   - creation POST carries `X-Idempotency-Key` (one intended upload, one key);
+ *   - FRESH headers on EVERY request (long uploads outlive a JWT; the
+ *     organization header must reach every chunk — aidream 8e5ee0b93 400s an
+ *     unscoped upload);
+ *   - one validated `metadata_json` envelope, byte-identical to the buffered
+ *     form field ({@link buildUploadMetadataEnvelope});
+ *   - automatic resume from the dedicated `mtx-tus-urls` IndexedDB store;
+ *   - the created file id comes back in `X-Cld-File-Id`, including the
+ *     completed-session recovery when the final response was lost.
+ *
+ * Its own subpath so `@ai-matrx/data/files` never loads tus-js-client.
+ */
+
+/** Server-bounded chunk size (8–32 MiB allowed): 16 MiB. */
+declare const TUS_CHUNK_SIZE_BYTES: number;
+/** The TUS creation route on the files service. */
+declare const TUS_UPLOAD_PATH = "/files/upload/tus";
+/**
+ * The ONE builder for the upload metadata JSON object. The buffered path
+ * serializes it into the `metadata_json` form field; the TUS path serializes
+ * the SAME object into the `metadata_json` Upload-Metadata key. One builder ⇒
+ * the two transports can never drift.
+ *
+ * `scope.organization_id` is the OWNING WORKSPACE of the uploaded file. The
+ * server stamps `files.files.organization_id` from it (membership-checked);
+ * omitted, the server falls back to the uploader's own organization — a silent
+ * mis-filing (2026-08-30). Loud in development, never a hard failure.
+ */
+declare function buildUploadMetadataEnvelope(metadata: Record<string, unknown> | undefined): Record<string, unknown>;
+/** tus-js-client HttpStack port (tests inject a mock wire). */
+type TusHttpStack = tus.HttpStack;
+/** tus-js-client file reader port (tests: Node builds cannot slice browser Files). */
+type TusFileReader = ConstructorParameters<typeof tus.Upload>[1]["fileReader"];
+/** tus-js-client UrlStorage port. */
+type TusUrlStorage = NonNullable<ConstructorParameters<typeof tus.Upload>[1]["urlStorage"]>;
+/** tus-js-client UrlStorage backed by the dedicated `mtx-tus-urls` DB —
+ *  deliberately SEPARATE from any recorder chunk journal. */
+declare function createTusUrlStorage(): TusUrlStorage;
+/** Read-only summary of a stored TUS resume session (diagnostics surfaces). */
+interface StoredTusUploadSummary {
+    urlStorageKey: string;
+    fingerprint: string;
+    size: number | null;
+    metadata: Record<string, string>;
+    creationTime: string;
+    uploadUrl: string | null;
+}
+/**
+ * List every stored TUS resume-URL entry. Read-only — resuming happens inside
+ * {@link tusTransfer}; this only lets management surfaces SHOW a pending
+ * session. Returns [] where IndexedDB is unavailable (never throws).
+ */
+declare function listStoredTusUploads(): Promise<StoredTusUploadSummary[]>;
+interface TusTransferOptions {
+    /** Full creation URL (`{filesBase}${TUS_UPLOAD_PATH}`). */
+    endpoint: string;
+    /** Destination path including the file name. */
+    filePath: string;
+    /** Caller metadata; wrapped by {@link buildUploadMetadataEnvelope}. */
+    metadata?: Record<string, unknown> | undefined;
+    /** Optional Upload-Metadata `visibility` (transitional wire input). */
+    visibility?: string | undefined;
+    /** One intended upload, one key — sent on the creation POST only. */
+    idempotencyKey: string;
+    /**
+     * FRESH request headers, read before EVERY request. Only `Authorization`,
+     * `X-Guest-Fingerprint` and `X-Organization-Id` are forwarded.
+     */
+    headers: () => Promise<Record<string, string | undefined>>;
+    onProgress?: ((loaded: number, total: number) => void) | undefined;
+    signal?: AbortSignal | undefined;
+    /** Injected HttpStack (tests: mock wire, no XHR). */
+    httpStack?: TusHttpStack | undefined;
+    /** Injected file reader (tests: Node builds cannot slice browser Files). */
+    fileReader?: TusFileReader | undefined;
+    /** Override URL storage (tests). Default: {@link createTusUrlStorage}. */
+    urlStorage?: TusUrlStorage | undefined;
+}
+type TusTransferErrorCode = "upload_cancelled" | "tus_upload_failed" | "tus_missing_file_id";
+type TusTransferResult = {
+    ok: true;
+    fileId: string;
+} | {
+    ok: false;
+    error: string;
+    errorCode: TusTransferErrorCode;
+};
+/**
+ * Resumable upload of one file. Never throws — `{ ok: false, errorCode }` on
+ * failure. Resumes a previous session for the same file automatically; when the
+ * transfer errors but the server already exposed `X-Cld-File-Id`, the completed
+ * session is recovered (loudly) instead of failing or re-uploading.
+ */
+declare function tusTransfer(file: File | Blob, opts: TusTransferOptions): Promise<TusTransferResult>;
+
+export { type StoredTusUploadSummary, TUS_CHUNK_SIZE_BYTES, TUS_UPLOAD_PATH, type TusFileReader, type TusHttpStack, type TusTransferErrorCode, type TusTransferOptions, type TusTransferResult, type TusUrlStorage, buildUploadMetadataEnvelope, createTusUrlStorage, listStoredTusUploads, tusTransfer };

package/dist/files/tus.d.ts

@@ -0,0 +1,106 @@
+import * as tus from 'tus-js-client';
+
+/**
+ * @ai-matrx/data/files/tus — the ONE resumable (TUS) upload transport.
+ *
+ * Origin: `@ai-matrx/media/files/engine/upload/tusUpload.ts` (architecture
+ * step 14, D1: only byte transport moves to data). Media keeps the Redux
+ * side and the record hydration; every host — the app, the extension, the
+ * desktop — rides this one wire:
+ *
+ *   - creation POST carries `X-Idempotency-Key` (one intended upload, one key);
+ *   - FRESH headers on EVERY request (long uploads outlive a JWT; the
+ *     organization header must reach every chunk — aidream 8e5ee0b93 400s an
+ *     unscoped upload);
+ *   - one validated `metadata_json` envelope, byte-identical to the buffered
+ *     form field ({@link buildUploadMetadataEnvelope});
+ *   - automatic resume from the dedicated `mtx-tus-urls` IndexedDB store;
+ *   - the created file id comes back in `X-Cld-File-Id`, including the
+ *     completed-session recovery when the final response was lost.
+ *
+ * Its own subpath so `@ai-matrx/data/files` never loads tus-js-client.
+ */
+
+/** Server-bounded chunk size (8–32 MiB allowed): 16 MiB. */
+declare const TUS_CHUNK_SIZE_BYTES: number;
+/** The TUS creation route on the files service. */
+declare const TUS_UPLOAD_PATH = "/files/upload/tus";
+/**
+ * The ONE builder for the upload metadata JSON object. The buffered path
+ * serializes it into the `metadata_json` form field; the TUS path serializes
+ * the SAME object into the `metadata_json` Upload-Metadata key. One builder ⇒
+ * the two transports can never drift.
+ *
+ * `scope.organization_id` is the OWNING WORKSPACE of the uploaded file. The
+ * server stamps `files.files.organization_id` from it (membership-checked);
+ * omitted, the server falls back to the uploader's own organization — a silent
+ * mis-filing (2026-08-30). Loud in development, never a hard failure.
+ */
+declare function buildUploadMetadataEnvelope(metadata: Record<string, unknown> | undefined): Record<string, unknown>;
+/** tus-js-client HttpStack port (tests inject a mock wire). */
+type TusHttpStack = tus.HttpStack;
+/** tus-js-client file reader port (tests: Node builds cannot slice browser Files). */
+type TusFileReader = ConstructorParameters<typeof tus.Upload>[1]["fileReader"];
+/** tus-js-client UrlStorage port. */
+type TusUrlStorage = NonNullable<ConstructorParameters<typeof tus.Upload>[1]["urlStorage"]>;
+/** tus-js-client UrlStorage backed by the dedicated `mtx-tus-urls` DB —
+ *  deliberately SEPARATE from any recorder chunk journal. */
+declare function createTusUrlStorage(): TusUrlStorage;
+/** Read-only summary of a stored TUS resume session (diagnostics surfaces). */
+interface StoredTusUploadSummary {
+    urlStorageKey: string;
+    fingerprint: string;
+    size: number | null;
+    metadata: Record<string, string>;
+    creationTime: string;
+    uploadUrl: string | null;
+}
+/**
+ * List every stored TUS resume-URL entry. Read-only — resuming happens inside
+ * {@link tusTransfer}; this only lets management surfaces SHOW a pending
+ * session. Returns [] where IndexedDB is unavailable (never throws).
+ */
+declare function listStoredTusUploads(): Promise<StoredTusUploadSummary[]>;
+interface TusTransferOptions {
+    /** Full creation URL (`{filesBase}${TUS_UPLOAD_PATH}`). */
+    endpoint: string;
+    /** Destination path including the file name. */
+    filePath: string;
+    /** Caller metadata; wrapped by {@link buildUploadMetadataEnvelope}. */
+    metadata?: Record<string, unknown> | undefined;
+    /** Optional Upload-Metadata `visibility` (transitional wire input). */
+    visibility?: string | undefined;
+    /** One intended upload, one key — sent on the creation POST only. */
+    idempotencyKey: string;
+    /**
+     * FRESH request headers, read before EVERY request. Only `Authorization`,
+     * `X-Guest-Fingerprint` and `X-Organization-Id` are forwarded.
+     */
+    headers: () => Promise<Record<string, string | undefined>>;
+    onProgress?: ((loaded: number, total: number) => void) | undefined;
+    signal?: AbortSignal | undefined;
+    /** Injected HttpStack (tests: mock wire, no XHR). */
+    httpStack?: TusHttpStack | undefined;
+    /** Injected file reader (tests: Node builds cannot slice browser Files). */
+    fileReader?: TusFileReader | undefined;
+    /** Override URL storage (tests). Default: {@link createTusUrlStorage}. */
+    urlStorage?: TusUrlStorage | undefined;
+}
+type TusTransferErrorCode = "upload_cancelled" | "tus_upload_failed" | "tus_missing_file_id";
+type TusTransferResult = {
+    ok: true;
+    fileId: string;
+} | {
+    ok: false;
+    error: string;
+    errorCode: TusTransferErrorCode;
+};
+/**
+ * Resumable upload of one file. Never throws — `{ ok: false, errorCode }` on
+ * failure. Resumes a previous session for the same file automatically; when the
+ * transfer errors but the server already exposed `X-Cld-File-Id`, the completed
+ * session is recovered (loudly) instead of failing or re-uploading.
+ */
+declare function tusTransfer(file: File | Blob, opts: TusTransferOptions): Promise<TusTransferResult>;
+
+export { type StoredTusUploadSummary, TUS_CHUNK_SIZE_BYTES, TUS_UPLOAD_PATH, type TusFileReader, type TusHttpStack, type TusTransferErrorCode, type TusTransferOptions, type TusTransferResult, type TusUrlStorage, buildUploadMetadataEnvelope, createTusUrlStorage, listStoredTusUploads, tusTransfer };