@ai-matrx/media 0.8.0 → 0.9.0

package/dist/files/engine/hooks/blob-cache.js

@@ -0,0 +1,162 @@
+import {
+  deleteEntriesForFile,
+  clearForUser,
+  putEntry as putIdbEntry
+} from "../cache/idb-store.js";
+import { shouldPersistInIdb } from "../cache/policy.js";
+import {
+  postBlobCacheClearUser,
+  postBlobCacheInvalidate
+} from "../cache/register-service-worker.js";
+let identityUserId = null;
+function setBlobCacheIdentity(userId) {
+  identityUserId = userId;
+}
+const DEFAULT_BUDGET_BYTES = 250 * 1024 * 1024;
+const cache = /* @__PURE__ */ new Map();
+let totalBytes = 0;
+let budgetBytes = DEFAULT_BUDGET_BYTES;
+function getCached(fileId, version) {
+  const entry = cache.get(fileId);
+  if (!entry) return null;
+  if (version != null) {
+    if (entry.version != null && entry.version !== version) return null;
+    entry.version = version;
+  }
+  cache.delete(fileId);
+  entry.lastAccessed = Date.now();
+  cache.set(fileId, entry);
+  return entry;
+}
+async function hydrateFromIdb(fileId, version) {
+  if (!identityUserId) return null;
+  try {
+    const { openBlobCacheDb } = await import("../cache/idb-store.js");
+    const db = await openBlobCacheDb();
+    if (!db) return null;
+    const matches = await db.blobs.where("userId").equals(identityUserId).and(
+      (e) => e.fileId === fileId && (version == null || e.version === version)
+    ).toArray();
+    if (matches.length === 0) return null;
+    const winner = matches.reduce(
+      (best, candidate) => candidate.lastAccessedAt > best.lastAccessedAt ? candidate : best,
+      matches[0]
+    );
+    const objectUrl = URL.createObjectURL(winner.blob);
+    setCachedMemoryOnly(fileId, winner.blob, objectUrl, winner.version ?? null);
+    return cache.get(fileId) ?? null;
+  } catch {
+    return null;
+  }
+}
+function setCached(fileId, blob, url, meta) {
+  setCachedMemoryOnly(fileId, blob, url, meta?.version ?? null);
+  const mime = meta?.mimeType ?? blob.type ?? "application/octet-stream";
+  if (identityUserId && shouldPersistInIdb(mime, blob.size)) {
+    const version = meta?.version ?? null;
+    const checksum = meta?.checksum ?? null;
+    const versionSegment = version != null ? String(version) : "current";
+    const checksumSegment = checksum ?? "unknown";
+    void putIdbEntry({
+      key: `${identityUserId}:${fileId}:${versionSegment}:${checksumSegment}`,
+      userId: identityUserId,
+      fileId,
+      version,
+      checksum,
+      mimeType: mime,
+      bytes: blob.size,
+      blob,
+      etag: checksum,
+      fetchedAt: Date.now(),
+      lastAccessedAt: Date.now(),
+      source: "files-download"
+    });
+  }
+}
+function setCachedMemoryOnly(fileId, blob, url, version) {
+  const existing = cache.get(fileId);
+  if (existing) {
+    URL.revokeObjectURL(existing.url);
+    totalBytes -= existing.bytes;
+    cache.delete(fileId);
+  }
+  const entry = {
+    blob,
+    url,
+    bytes: blob.size,
+    lastAccessed: Date.now(),
+    version
+  };
+  cache.set(fileId, entry);
+  totalBytes += entry.bytes;
+  while (totalBytes > budgetBytes && cache.size > 1) {
+    const oldestKey = cache.keys().next().value;
+    if (!oldestKey || oldestKey === fileId) break;
+    const oldest = cache.get(oldestKey);
+    if (oldest) {
+      URL.revokeObjectURL(oldest.url);
+      totalBytes -= oldest.bytes;
+    }
+    cache.delete(oldestKey);
+  }
+}
+function invalidate(fileId) {
+  const entry = cache.get(fileId);
+  if (entry) {
+    URL.revokeObjectURL(entry.url);
+    totalBytes -= entry.bytes;
+    cache.delete(fileId);
+  }
+  if (identityUserId) {
+    void deleteEntriesForFile(identityUserId, fileId);
+  }
+  void postBlobCacheInvalidate(fileId);
+}
+function cachedVersion(fileId) {
+  return cache.get(fileId)?.version ?? null;
+}
+function replaceWithSavedBytes(fileId, blob, version) {
+  invalidate(fileId);
+  try {
+    setCached(fileId, blob, URL.createObjectURL(blob), {
+      mimeType: blob.type,
+      version
+    });
+  } catch (err) {
+    console.warn("[blob-cache] saved bytes not cached; the next view downloads them", err);
+  }
+}
+function invalidateAll(userId) {
+  for (const entry of cache.values()) {
+    URL.revokeObjectURL(entry.url);
+  }
+  cache.clear();
+  totalBytes = 0;
+  if (userId) {
+    void clearForUser(userId);
+    void postBlobCacheClearUser(userId);
+  }
+}
+function getCacheStats() {
+  return {
+    entryCount: cache.size,
+    totalBytes,
+    budgetBytes
+  };
+}
+function setBudgetBytes(bytes) {
+  budgetBytes = Math.max(0, bytes);
+}
+export {
+  cachedVersion,
+  getCacheStats,
+  getCached,
+  hydrateFromIdb,
+  invalidate,
+  invalidateAll,
+  replaceWithSavedBytes,
+  setBlobCacheIdentity,
+  setBudgetBytes,
+  setCached
+};
+//# sourceMappingURL=blob-cache.js.map

package/dist/files/engine/hooks/blob-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/hooks/blob-cache.ts"],"sourcesContent":["/**\n * features/files/hooks/blob-cache.ts\n *\n * Layer 1 (in-memory LRU) of the 3-tier byte cache. Survives React mount /\n * unmount cycles within a session. Without it, closing and reopening a\n * 10MB PDF re-fetches the whole blob over the wire — useFileBlob keeps\n * its blob in component state, so unmount = `URL.revokeObjectURL` +\n * lost bytes.\n *\n * 3-tier read path (see features/files/cache/):\n *   1. In-memory LRU (this module)              — synchronous, session\n *   2. IndexedDB (features/files/cache/idb-store) — persistent, async\n *   3. Network                                   — Python /files/{id}/download\n *\n * Writes populate both tiers when the MIME policy permits IDB persistence\n * (PDFs, ≤50 MB video, ≤100 MB audio, images, etc. — see cache/policy.ts).\n *\n * Design:\n *   - Single `Map<fileId, CacheEntry>`. Map iteration order = insertion\n *     order, so re-inserting on a cache hit gives us LRU for free.\n *   - Capped by total bytes (default 250 MB). When inserts push past\n *     the cap, oldest entries are evicted and their object URLs revoked.\n *   - The cache OWNS the object URL. `useFileBlob` reads `entry.url`\n *     directly and does NOT revoke on unmount — only the cache itself\n *     revokes, on eviction or explicit invalidation.\n *\n * Invalidation hooks:\n *   - `invalidate(fileId)` — single file. Used by upload-version /\n *     restore-version / delete thunks + realtime middleware on\n *     cross-device version inserts. Drops from BOTH tiers.\n *   - `invalidateAll()` — for sign-out / identity swap. Drops in-memory\n *     immediately; pass a userId to also wipe IDB for that user.\n *\n * Why not Redux: Blobs are not serialisable; storing them in the slice\n * would trigger RTK serializableCheck warnings on every dispatch and\n * the full blob would be passed through every middleware. A module-\n * level Map is the right primitive for this.\n */\n\nimport {\n  deleteEntriesForFile,\n  clearForUser,\n  getEntry as getIdbEntry,\n  putEntry as putIdbEntry,\n  type BlobCacheEntry as IdbBlobCacheEntry,\n} from \"../cache/idb-store\";\nimport { shouldPersistInIdb } from \"../cache/policy\";\nimport {\n  postBlobCacheClearUser,\n  postBlobCacheInvalidate,\n} from \"../cache/register-service-worker\";\n\nlet identityUserId: string | null = null;\n\n/**\n * Stamp every subsequent put/invalidate with the current user. Called\n * from the sign-in flow (after Supabase session resolves). Without this\n * IDB entries are written under an empty userId — readable but not\n * scoped, which would leak across user swaps. Memory LRU is unaffected.\n */\nexport function setBlobCacheIdentity(userId: string | null): void {\n  identityUserId = userId;\n}\n\nconst DEFAULT_BUDGET_BYTES = 250 * 1024 * 1024; // 250 MB total\n\ninterface CacheEntry {\n  blob: Blob;\n  /** `blob:`-scheme URL — owned by the cache; revoked on eviction. */\n  url: string;\n  /** `blob.size` cached so eviction math doesn't need to re-read. */\n  bytes: number;\n  /**\n   * The file version these bytes belong to; null when it was not known at\n   * fetch time (stamped by the first read that knows it). A read for a\n   * different version is a miss — the bytes are refetched only when the\n   * version changes.\n   */\n  version: number | null;\n  /** Last-access timestamp (ms). Updated on cache hits. */\n  lastAccessed: number;\n}\n\nconst cache = new Map<string, CacheEntry>();\nlet totalBytes = 0;\nlet budgetBytes = DEFAULT_BUDGET_BYTES;\n\n/**\n * Read a cached entry. Touches the LRU position so re-accesses keep\n * the entry alive. Returns `null` on miss — and when `version` is given and\n * the entry holds a different version's bytes.\n */\nexport function getCached(\n  fileId: string,\n  version?: number | null,\n): CacheEntry | null {\n  const entry = cache.get(fileId);\n  if (!entry) return null;\n  if (version != null) {\n    if (entry.version != null && entry.version !== version) return null;\n    entry.version = version;\n  }\n  // Bump LRU position by re-inserting at the end of the iteration order.\n  cache.delete(fileId);\n  entry.lastAccessed = Date.now();\n  cache.set(fileId, entry);\n  return entry;\n}\n\n/**\n * Hydrate the in-memory tier from IndexedDB for a single fileId. Returns\n * the hydrated entry on hit, `null` on miss or when IDB is unavailable.\n *\n * Use this in `useFileBlob`'s effect when the in-memory LRU misses but\n * we want to avoid a network round-trip if the bytes persisted from a\n * previous session.\n */\nexport async function hydrateFromIdb(\n  fileId: string,\n  version?: number | null,\n): Promise<CacheEntry | null> {\n  if (!identityUserId) return null;\n  try {\n    // Read the most recent version's entry. Cache keys embed the version\n    // suffix, so we scan with a prefix match via the deleteEntriesForFile\n    // family. For now we attempt the \"current\" key shape; the SW layer\n    // (Phase 2) will register canonical (url → key) mappings the page can\n    // consult before this read.\n    // FIRST-CUT: try the canonical \"current\" key shape with a wildcard\n    // checksum. The IDB store doesn't support prefix queries directly, so\n    // we fall back to scanning the user's entries for a matching fileId.\n    // This stays O(entries-per-user) which is fine for the realistic upper\n    // bound (~hundreds of cached PDFs).\n    const { openBlobCacheDb } = await import(\"../cache/idb-store\");\n    const db = await openBlobCacheDb();\n    if (!db) return null;\n    const matches = await db.blobs\n      .where(\"userId\")\n      .equals(identityUserId)\n      .and(\n        (e: IdbBlobCacheEntry) =>\n          e.fileId === fileId && (version == null || e.version === version),\n      )\n      .toArray();\n    if (matches.length === 0) return null;\n    // Prefer the entry with the most recent `lastAccessedAt`.\n    const winner = matches.reduce<IdbBlobCacheEntry>(\n      (best, candidate) =>\n        candidate.lastAccessedAt > best.lastAccessedAt ? candidate : best,\n      matches[0],\n    );\n    // Promote into the in-memory tier so the next read is synchronous.\n    const objectUrl = URL.createObjectURL(winner.blob);\n    setCachedMemoryOnly(fileId, winner.blob, objectUrl, winner.version ?? null);\n    return cache.get(fileId) ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Insert (or overwrite) a cached entry. The cache takes ownership of\n * `blob` + `url` — callers should NOT revoke the URL themselves.\n *\n * Writes the entry into the in-memory LRU AND (when the MIME policy\n * permits — see `features/files/cache/policy.ts`) into IndexedDB so the\n * bytes survive page reloads.\n *\n * If a previous entry for the same fileId exists, its URL is revoked\n * and the entry is replaced. After insert, the cache evicts oldest\n * entries until the total byte size is under the budget.\n */\nexport function setCached(\n  fileId: string,\n  blob: Blob,\n  url: string,\n  meta?: { mimeType?: string; version?: number | null; checksum?: string | null },\n): void {\n  setCachedMemoryOnly(fileId, blob, url, meta?.version ?? null);\n  // Best-effort write to IDB. The promise is intentionally not awaited —\n  // the caller's render path is already complete; IDB persistence is a\n  // background side-effect that's safe to fail (the in-memory tier is\n  // already populated).\n  const mime = meta?.mimeType ?? blob.type ?? \"application/octet-stream\";\n  if (identityUserId && shouldPersistInIdb(mime, blob.size)) {\n    const version = meta?.version ?? null;\n    const checksum = meta?.checksum ?? null;\n    const versionSegment = version != null ? String(version) : \"current\";\n    const checksumSegment = checksum ?? \"unknown\";\n    void putIdbEntry({\n      key: `${identityUserId}:${fileId}:${versionSegment}:${checksumSegment}`,\n      userId: identityUserId,\n      fileId,\n      version,\n      checksum,\n      mimeType: mime,\n      bytes: blob.size,\n      blob,\n      etag: checksum,\n      fetchedAt: Date.now(),\n      lastAccessedAt: Date.now(),\n      source: \"files-download\",\n    });\n  }\n}\n\nfunction setCachedMemoryOnly(\n  fileId: string,\n  blob: Blob,\n  url: string,\n  version: number | null,\n): void {\n  // Replace any existing entry — must revoke the old URL.\n  const existing = cache.get(fileId);\n  if (existing) {\n    URL.revokeObjectURL(existing.url);\n    totalBytes -= existing.bytes;\n    cache.delete(fileId);\n  }\n\n  const entry: CacheEntry = {\n    blob,\n    url,\n    bytes: blob.size,\n    lastAccessed: Date.now(),\n    version,\n  };\n  cache.set(fileId, entry);\n  totalBytes += entry.bytes;\n\n  // Evict oldest entries until the cache is under budget. Map iteration\n  // order is insertion order, so the oldest LRU entry is the first key.\n  while (totalBytes > budgetBytes && cache.size > 1) {\n    const oldestKey = cache.keys().next().value as string | undefined;\n    if (!oldestKey || oldestKey === fileId) break;\n    const oldest = cache.get(oldestKey);\n    if (oldest) {\n      URL.revokeObjectURL(oldest.url);\n      totalBytes -= oldest.bytes;\n    }\n    cache.delete(oldestKey);\n  }\n}\n\n/**\n * Drop a single file's cached entry from both tiers. Use this from any\n * code path that makes the cached bytes stale: new-version upload,\n * restore-version, hard-delete, realtime-broadcast cross-device version\n * insert.\n */\nexport function invalidate(fileId: string): void {\n  const entry = cache.get(fileId);\n  if (entry) {\n    URL.revokeObjectURL(entry.url);\n    totalBytes -= entry.bytes;\n    cache.delete(fileId);\n  }\n  // Fire-and-forget: clear every version of this file in IDB AND tell\n  // the Service Worker (if registered) to drop its mirror copy of the\n  // same fileId. Three tiers, one invalidate() call.\n  if (identityUserId) {\n    void deleteEntriesForFile(identityUserId, fileId);\n  }\n  void postBlobCacheInvalidate(fileId);\n}\n\n/** The version the cached bytes belong to (null: unknown or not cached). No LRU touch. */\nexport function cachedVersion(fileId: string): number | null {\n  return cache.get(fileId)?.version ?? null;\n}\n\n/**\n * A save wrote `blob` as version `version` of this file: drop every older\n * copy (all tiers) and cache the saved bytes as that version, so every\n * viewer shows the new version without downloading what this tab just\n * uploaded.\n */\nexport function replaceWithSavedBytes(\n  fileId: string,\n  blob: Blob,\n  version: number,\n): void {\n  invalidate(fileId);\n  try {\n    setCached(fileId, blob, URL.createObjectURL(blob), {\n      mimeType: blob.type,\n      version,\n    });\n  } catch (err) {\n    // The save itself landed; only the local copy could not be kept, so the\n    // next viewer downloads the new version instead. Say so.\n    console.warn(\"[blob-cache] saved bytes not cached; the next view downloads them\", err);\n  }\n}\n\n/**\n * Drop every in-memory entry. Use on sign-out / identity swap so the\n * next user can never see the previous user's blob URLs lingering in\n * memory. When `userId` is provided, also clears IDB for that user.\n */\nexport function invalidateAll(userId?: string): void {\n  for (const entry of cache.values()) {\n    URL.revokeObjectURL(entry.url);\n  }\n  cache.clear();\n  totalBytes = 0;\n  if (userId) {\n    void clearForUser(userId);\n    void postBlobCacheClearUser(userId);\n  }\n}\n\n/**\n * Test/debug helper. Useful for diagnostic pages that want to render\n * \"blob cache: 3 files, 47 MB / 250 MB\".\n */\nexport function getCacheStats(): {\n  entryCount: number;\n  totalBytes: number;\n  budgetBytes: number;\n} {\n  return {\n    entryCount: cache.size,\n    totalBytes,\n    budgetBytes,\n  };\n}\n\n/**\n * Dev/test only — change the size budget at runtime. The default is\n * 250 MB (DEFAULT_BUDGET_BYTES).\n */\nexport function setBudgetBytes(bytes: number): void {\n  budgetBytes = Math.max(0, bytes);\n}\n"],"mappings":"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","names":[]}

package/dist/files/engine/hooks/office-extraction-cache.d.ts

@@ -0,0 +1,28 @@
+/**
+ * features/files/hooks/office-extraction-cache.ts
+ *
+ * Module-level cache of server-side Office extractions (docx/pptx → markdown),
+ * keyed by fileId — the OfficePreview analogue of `blob-cache.ts`. Lives
+ * OUTSIDE the lazy previewer chunk so the Redux thunks and the realtime
+ * middleware can invalidate it (new version upload / restore / delete)
+ * without importing the react-markdown previewer graph.
+ *
+ * Payloads are small (markdown text), so a simple insertion-capped Map is
+ * enough — no LRU, no byte accounting.
+ */
+import { type OfficeExtraction, type OfficeFileRef } from "../api/office.js";
+/** Cached-or-fetched extraction, deduplicated across simultaneous mounts. */
+export declare function getOfficeExtraction(fileId: string): Promise<OfficeExtraction>;
+/** Synchronous cache peek — lets the previewer render instantly on remount. */
+export declare function peekOfficeExtraction(fileId: string): OfficeExtraction | null;
+/**
+ * Cached-or-created PDF derivative of an Office file (server-side LibreOffice
+ * lane, idempotent per source revision) — powers the visual slides/pages
+ * preview. Deduplicated across simultaneous mounts.
+ */
+export declare function getOfficePdf(fileId: string): Promise<OfficeFileRef>;
+/** Synchronous PDF-ref peek — lets the visual previewer render instantly. */
+export declare function peekOfficePdf(fileId: string): OfficeFileRef | null;
+/** Drop the cached extraction AND pdf ref — call wherever the blob cache is
+ *  invalidated (new version upload, restore, delete, realtime update). */
+export declare function invalidateOfficeExtraction(fileId: string): void;

package/dist/files/engine/hooks/office-extraction-cache.js

@@ -0,0 +1,67 @@
+import {
+  convertOfficeToPdf,
+  extractOfficeMarkdown
+} from "../api/office.js";
+const extractionCache = /* @__PURE__ */ new Map();
+const CACHE_MAX_ENTRIES = 40;
+const inflight = /* @__PURE__ */ new Map();
+const pdfRefCache = /* @__PURE__ */ new Map();
+const pdfInflight = /* @__PURE__ */ new Map();
+function getOfficeExtraction(fileId) {
+  const cached = extractionCache.get(fileId);
+  if (cached) return Promise.resolve(cached);
+  let p = inflight.get(fileId);
+  if (!p) {
+    p = extractOfficeMarkdown(fileId).then((result) => {
+      if (extractionCache.size >= CACHE_MAX_ENTRIES) {
+        const oldest = extractionCache.keys().next().value;
+        if (oldest !== void 0) extractionCache.delete(oldest);
+      }
+      extractionCache.set(fileId, result);
+      return result;
+    });
+    inflight.set(fileId, p);
+    void p.catch(() => void 0).finally(() => {
+      if (inflight.get(fileId) === p) inflight.delete(fileId);
+    });
+  }
+  return p;
+}
+function peekOfficeExtraction(fileId) {
+  return extractionCache.get(fileId) ?? null;
+}
+function getOfficePdf(fileId) {
+  const cached = pdfRefCache.get(fileId);
+  if (cached) return Promise.resolve(cached);
+  let p = pdfInflight.get(fileId);
+  if (!p) {
+    p = convertOfficeToPdf(fileId).then((result) => {
+      if (pdfRefCache.size >= CACHE_MAX_ENTRIES) {
+        const oldest = pdfRefCache.keys().next().value;
+        if (oldest !== void 0) pdfRefCache.delete(oldest);
+      }
+      pdfRefCache.set(fileId, result);
+      return result;
+    });
+    pdfInflight.set(fileId, p);
+    void p.catch(() => void 0).finally(() => {
+      if (pdfInflight.get(fileId) === p) pdfInflight.delete(fileId);
+    });
+  }
+  return p;
+}
+function peekOfficePdf(fileId) {
+  return pdfRefCache.get(fileId) ?? null;
+}
+function invalidateOfficeExtraction(fileId) {
+  extractionCache.delete(fileId);
+  pdfRefCache.delete(fileId);
+}
+export {
+  getOfficeExtraction,
+  getOfficePdf,
+  invalidateOfficeExtraction,
+  peekOfficeExtraction,
+  peekOfficePdf
+};
+//# sourceMappingURL=office-extraction-cache.js.map

package/dist/files/engine/hooks/office-extraction-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/hooks/office-extraction-cache.ts"],"sourcesContent":["/**\n * features/files/hooks/office-extraction-cache.ts\n *\n * Module-level cache of server-side Office extractions (docx/pptx → markdown),\n * keyed by fileId — the OfficePreview analogue of `blob-cache.ts`. Lives\n * OUTSIDE the lazy previewer chunk so the Redux thunks and the realtime\n * middleware can invalidate it (new version upload / restore / delete)\n * without importing the react-markdown previewer graph.\n *\n * Payloads are small (markdown text), so a simple insertion-capped Map is\n * enough — no LRU, no byte accounting.\n */\n\nimport {\n  convertOfficeToPdf,\n  extractOfficeMarkdown,\n  type OfficeExtraction,\n  type OfficeFileRef,\n} from \"../api/office\";\n\nconst extractionCache = new Map<string, OfficeExtraction>();\nconst CACHE_MAX_ENTRIES = 40;\nconst inflight = new Map<string, Promise<OfficeExtraction>>();\n\n// PDF-derivative refs for the visual (slides/pages) preview. The server lane\n// is idempotent per source revision, so caching the FileRef here only saves\n// the round-trip — a stale entry can't produce a wrong document, and it is\n// dropped through the same invalidation choke points as extractions.\nconst pdfRefCache = new Map<string, OfficeFileRef>();\nconst pdfInflight = new Map<string, Promise<OfficeFileRef>>();\n\n/** Cached-or-fetched extraction, deduplicated across simultaneous mounts. */\nexport function getOfficeExtraction(fileId: string): Promise<OfficeExtraction> {\n  const cached = extractionCache.get(fileId);\n  if (cached) return Promise.resolve(cached);\n  let p = inflight.get(fileId);\n  if (!p) {\n    p = extractOfficeMarkdown(fileId).then((result) => {\n      if (extractionCache.size >= CACHE_MAX_ENTRIES) {\n        const oldest = extractionCache.keys().next().value;\n        if (oldest !== undefined) extractionCache.delete(oldest);\n      }\n      extractionCache.set(fileId, result);\n      return result;\n    });\n    inflight.set(fileId, p);\n    // Cleanup must not create an unhandled rejection when the fetch fails —\n    // subscribers handle `p`'s rejection themselves; this chain swallows it.\n    void p\n      .catch(() => undefined)\n      .finally(() => {\n        if (inflight.get(fileId) === p) inflight.delete(fileId);\n      });\n  }\n  return p;\n}\n\n/** Synchronous cache peek — lets the previewer render instantly on remount. */\nexport function peekOfficeExtraction(fileId: string): OfficeExtraction | null {\n  return extractionCache.get(fileId) ?? null;\n}\n\n/**\n * Cached-or-created PDF derivative of an Office file (server-side LibreOffice\n * lane, idempotent per source revision) — powers the visual slides/pages\n * preview. Deduplicated across simultaneous mounts.\n */\nexport function getOfficePdf(fileId: string): Promise<OfficeFileRef> {\n  const cached = pdfRefCache.get(fileId);\n  if (cached) return Promise.resolve(cached);\n  let p = pdfInflight.get(fileId);\n  if (!p) {\n    p = convertOfficeToPdf(fileId).then((result) => {\n      if (pdfRefCache.size >= CACHE_MAX_ENTRIES) {\n        const oldest = pdfRefCache.keys().next().value;\n        if (oldest !== undefined) pdfRefCache.delete(oldest);\n      }\n      pdfRefCache.set(fileId, result);\n      return result;\n    });\n    pdfInflight.set(fileId, p);\n    void p\n      .catch(() => undefined)\n      .finally(() => {\n        if (pdfInflight.get(fileId) === p) pdfInflight.delete(fileId);\n      });\n  }\n  return p;\n}\n\n/** Synchronous PDF-ref peek — lets the visual previewer render instantly. */\nexport function peekOfficePdf(fileId: string): OfficeFileRef | null {\n  return pdfRefCache.get(fileId) ?? null;\n}\n\n/** Drop the cached extraction AND pdf ref — call wherever the blob cache is\n *  invalidated (new version upload, restore, delete, realtime update). */\nexport function invalidateOfficeExtraction(fileId: string): void {\n  extractionCache.delete(fileId);\n  pdfRefCache.delete(fileId);\n}\n"],"mappings":"AAaA;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AAEP,MAAM,kBAAkB,oBAAI,IAA8B;AAC1D,MAAM,oBAAoB;AAC1B,MAAM,WAAW,oBAAI,IAAuC;AAM5D,MAAM,cAAc,oBAAI,IAA2B;AACnD,MAAM,cAAc,oBAAI,IAAoC;AAGrD,SAAS,oBAAoB,QAA2C;AAC7E,QAAM,SAAS,gBAAgB,IAAI,MAAM;AACzC,MAAI,OAAQ,QAAO,QAAQ,QAAQ,MAAM;AACzC,MAAI,IAAI,SAAS,IAAI,MAAM;AAC3B,MAAI,CAAC,GAAG;AACN,QAAI,sBAAsB,MAAM,EAAE,KAAK,CAAC,WAAW;AACjD,UAAI,gBAAgB,QAAQ,mBAAmB;AAC7C,cAAM,SAAS,gBAAgB,KAAK,EAAE,KAAK,EAAE;AAC7C,YAAI,WAAW,OAAW,iBAAgB,OAAO,MAAM;AAAA,MACzD;AACA,sBAAgB,IAAI,QAAQ,MAAM;AAClC,aAAO;AAAA,IACT,CAAC;AACD,aAAS,IAAI,QAAQ,CAAC;AAGtB,SAAK,EACF,MAAM,MAAM,MAAS,EACrB,QAAQ,MAAM;AACb,UAAI,SAAS,IAAI,MAAM,MAAM,EAAG,UAAS,OAAO,MAAM;AAAA,IACxD,CAAC;AAAA,EACL;AACA,SAAO;AACT;AAGO,SAAS,qBAAqB,QAAyC;AAC5E,SAAO,gBAAgB,IAAI,MAAM,KAAK;AACxC;AAOO,SAAS,aAAa,QAAwC;AACnE,QAAM,SAAS,YAAY,IAAI,MAAM;AACrC,MAAI,OAAQ,QAAO,QAAQ,QAAQ,MAAM;AACzC,MAAI,IAAI,YAAY,IAAI,MAAM;AAC9B,MAAI,CAAC,GAAG;AACN,QAAI,mBAAmB,MAAM,EAAE,KAAK,CAAC,WAAW;AAC9C,UAAI,YAAY,QAAQ,mBAAmB;AACzC,cAAM,SAAS,YAAY,KAAK,EAAE,KAAK,EAAE;AACzC,YAAI,WAAW,OAAW,aAAY,OAAO,MAAM;AAAA,MACrD;AACA,kBAAY,IAAI,QAAQ,MAAM;AAC9B,aAAO;AAAA,IACT,CAAC;AACD,gBAAY,IAAI,QAAQ,CAAC;AACzB,SAAK,EACF,MAAM,MAAM,MAAS,EACrB,QAAQ,MAAM;AACb,UAAI,YAAY,IAAI,MAAM,MAAM,EAAG,aAAY,OAAO,MAAM;AAAA,IAC9D,CAAC;AAAA,EACL;AACA,SAAO;AACT;AAGO,SAAS,cAAc,QAAsC;AAClE,SAAO,YAAY,IAAI,MAAM,KAAK;AACpC;AAIO,SAAS,2BAA2B,QAAsB;AAC/D,kBAAgB,OAAO,MAAM;AAC7B,cAAY,OAAO,MAAM;AAC3B;","names":[]}

package/dist/files/engine/host/configure.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The files engine's host port — the ONE place a client hands the engine what
+ * only it can own: its database client, its AI Matrx server client, its Redux
+ * store, its share-link calls, its organization chooser and its notifications.
+ *
+ * Everything else the engine needs (the slice, thunks, middlewares, uploads,
+ * the resolver, the typed REST verbs, session retry, claims) is package code.
+ *
+ * Configure once, before the store is created:
+ *
+ *   configureFilesHost({ db, server, store: () => store, ... });
+ *
+ * Every seam module reads the host at CALL time, never at import time, so the
+ * order of module loading never matters. Used before configuration, a call
+ * throws `FilesHostNotConfiguredError`, which names the remedy.
+ */
+import type { SupabaseClient } from "@supabase/supabase-js";
+export interface FilesRequestOptions {
+    requestId?: string;
+    signal?: AbortSignal;
+    baseUrlOverride?: string;
+    timeoutMs?: number;
+    captureErrors?: boolean;
+    guestFingerprint?: string;
+    idempotencyKey?: string;
+    organizationId?: string;
+    bodyCarriedRead?: boolean;
+    cloudFilesBypass?: string;
+}
+export interface FilesResponseMeta {
+    requestId: string;
+    status: number;
+    serverRequestId: string | null;
+}
+export interface FilesUploadProgressEvent {
+    loaded: number;
+    total: number;
+}
+export interface FilesDownloadProgressEvent {
+    loaded: number;
+    total: number | null;
+}
+type Envelope<T> = Promise<{
+    data: T;
+    meta: FilesResponseMeta;
+}>;
+type BlobEnvelope = Promise<{
+    blob: Blob;
+    meta: FilesResponseMeta;
+    filename: string | null;
+}>;
+/** The host's AI Matrx server client (matrx-frontend: `lib/python-client`). */
+export interface FilesServerClient {
+    resolveFilesBaseUrl(override?: string): string;
+    resolveBaseUrlForPath(path: string, override?: string, method?: string): string;
+    buildHeaders(opts: FilesRequestOptions, includeContentType: boolean, method?: string): Promise<{
+        headers: Record<string, string>;
+        requestId: string;
+    }>;
+    getJson<T>(path: string, opts?: FilesRequestOptions): Envelope<T>;
+    postJson<T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions): Envelope<T>;
+    patchJson<T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions): Envelope<T>;
+    putJson<T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions): Envelope<T>;
+    del<T = null>(path: string, opts?: FilesRequestOptions): Promise<{
+        data: T | null;
+        meta: FilesResponseMeta;
+    }>;
+    delJson<T = null, B = unknown>(path: string, body: B, opts?: FilesRequestOptions): Promise<{
+        data: T | null;
+        meta: FilesResponseMeta;
+    }>;
+    postMultipart<T>(path: string, form: FormData, opts?: FilesRequestOptions): Envelope<T>;
+    uploadWithProgress<T>(path: string, form: FormData, onProgress: (event: FilesUploadProgressEvent) => void, opts?: FilesRequestOptions): Envelope<T>;
+    downloadBlob(path: string, opts?: FilesRequestOptions): BlobEnvelope;
+    downloadBlobWithProgress(path: string, onProgress: (event: FilesDownloadProgressEvent) => void, opts?: FilesRequestOptions): BlobEnvelope;
+}
+export interface FilesShareLink {
+    id: string;
+    token: string;
+    shortToken: string | null;
+    permissionLevel: string;
+    label: string | null;
+    expiresAt: string | null;
+    maxUses: number | null;
+    useCount: number;
+    isActive: boolean;
+    createdAt: string | null;
+    lastUsedAt: string | null;
+}
+export interface FilesCreateShareLinkOptions {
+    resourceType: string;
+    resourceId: string;
+    permissionLevel?: string;
+    expiresAt?: string | null;
+    maxUses?: number | null;
+    label?: string | null;
+}
+/** The host's share-link store (matrx-frontend: `utils/permissions/shareLinks`). */
+export interface FilesShareLinks {
+    shareLinkUrl(token: string): string;
+    createShareLink(options: FilesCreateShareLinkOptions): Promise<{
+        success: boolean;
+        token?: string;
+        shortToken?: string | null;
+        url?: string;
+        error?: string;
+    }>;
+    listShareLinks(resourceType: string, resourceId: string): Promise<FilesShareLink[]>;
+    revokeShareLink(linkId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/** The store the engine's slice is mounted in (under `cloudFiles`). */
+export interface FilesStore {
+    getState(): unknown;
+    dispatch(action: unknown): unknown;
+}
+/** Where new uploads land by default: the person's current organization / project / task. */
+export interface FilesScope {
+    /** The signed-in person (ownership checks). */
+    userId?: string | null;
+    organizationId: string | null;
+    projectId: string | null;
+    taskId: string | null;
+}
+export interface FilesNotifyPort {
+    success(message: string, options?: {
+        description?: string;
+        id?: string | number;
+        duration?: number;
+    }): void;
+    error(message: string, options?: {
+        description?: string;
+        id?: string | number;
+        duration?: number;
+    }): void;
+}
+export interface FilesHost {
+    /** A supabase-js client for the signed-in person (the engine reads the `files` and `iam` schemas). */
+    db: SupabaseClient<any, any, any>;
+    server: FilesServerClient;
+    /** The store the `cloudFiles` reducer is mounted in; null until it exists. */
+    store(): FilesStore | null;
+    /** The person's current organization / project / task, read from `state`. Default: none. */
+    scope?(state: unknown): FilesScope;
+    /**
+     * Resolve the organization a write lands in. Given a declared id, return it;
+     * otherwise ask the person (the host's chooser). Default: the declared id,
+     * else the scope's organization, else a named error.
+     */
+    ensureOrganizationContext?(options: {
+        organizationId?: string | null;
+    }): Promise<string>;
+    shareLinks?: FilesShareLinks;
+    notify?: FilesNotifyPort;
+}
+export declare class FilesHostNotConfiguredError extends Error {
+    constructor(member: string);
+}
+export declare function configureFilesHost(next: FilesHost): void;
+export declare function isFilesHostConfigured(): boolean;
+export declare function getFilesHost(member: string): FilesHost;
+/** For tests: drop the configured host. */
+export declare function __resetFilesHostForTests(): void;
+export {};

package/dist/files/engine/host/configure.js

@@ -0,0 +1,30 @@
+class FilesHostNotConfiguredError extends Error {
+  constructor(member) {
+    super(
+      `@ai-matrx/media/files-engine: "${member}" was used before configureFilesHost(...) ran. Call configureFilesHost({ db, server, store }) once at startup, before the store is created.`
+    );
+    this.name = "FilesHostNotConfiguredError";
+  }
+}
+let host = null;
+function configureFilesHost(next) {
+  host = next;
+}
+function isFilesHostConfigured() {
+  return host !== null;
+}
+function getFilesHost(member) {
+  if (!host) throw new FilesHostNotConfiguredError(member);
+  return host;
+}
+function __resetFilesHostForTests() {
+  host = null;
+}
+export {
+  FilesHostNotConfiguredError,
+  __resetFilesHostForTests,
+  configureFilesHost,
+  getFilesHost,
+  isFilesHostConfigured
+};
+//# sourceMappingURL=configure.js.map

package/dist/files/engine/host/configure.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/host/configure.ts"],"sourcesContent":["/**\n * The files engine's host port — the ONE place a client hands the engine what\n * only it can own: its database client, its AI Matrx server client, its Redux\n * store, its share-link calls, its organization chooser and its notifications.\n *\n * Everything else the engine needs (the slice, thunks, middlewares, uploads,\n * the resolver, the typed REST verbs, session retry, claims) is package code.\n *\n * Configure once, before the store is created:\n *\n *   configureFilesHost({ db, server, store: () => store, ... });\n *\n * Every seam module reads the host at CALL time, never at import time, so the\n * order of module loading never matters. Used before configuration, a call\n * throws `FilesHostNotConfiguredError`, which names the remedy.\n */\n\nimport type { SupabaseClient } from \"@supabase/supabase-js\";\n\nexport interface FilesRequestOptions {\n  requestId?: string;\n  signal?: AbortSignal;\n  baseUrlOverride?: string;\n  timeoutMs?: number;\n  captureErrors?: boolean;\n  guestFingerprint?: string;\n  idempotencyKey?: string;\n  organizationId?: string;\n  bodyCarriedRead?: boolean;\n  cloudFilesBypass?: string;\n}\n\nexport interface FilesResponseMeta {\n  requestId: string;\n  status: number;\n  serverRequestId: string | null;\n}\n\nexport interface FilesUploadProgressEvent {\n  loaded: number;\n  total: number;\n}\n\nexport interface FilesDownloadProgressEvent {\n  loaded: number;\n  total: number | null;\n}\n\ntype Envelope<T> = Promise<{ data: T; meta: FilesResponseMeta }>;\ntype BlobEnvelope = Promise<{ blob: Blob; meta: FilesResponseMeta; filename: string | null }>;\n\n/** The host's AI Matrx server client (matrx-frontend: `lib/python-client`). */\nexport interface FilesServerClient {\n  resolveFilesBaseUrl(override?: string): string;\n  resolveBaseUrlForPath(path: string, override?: string, method?: string): string;\n  buildHeaders(\n    opts: FilesRequestOptions,\n    includeContentType: boolean,\n    method?: string,\n  ): Promise<{ headers: Record<string, string>; requestId: string }>;\n  getJson<T>(path: string, opts?: FilesRequestOptions): Envelope<T>;\n  postJson<T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions): Envelope<T>;\n  patchJson<T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions): Envelope<T>;\n  putJson<T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions): Envelope<T>;\n  del<T = null>(path: string, opts?: FilesRequestOptions): Promise<{ data: T | null; meta: FilesResponseMeta }>;\n  delJson<T = null, B = unknown>(\n    path: string,\n    body: B,\n    opts?: FilesRequestOptions,\n  ): Promise<{ data: T | null; meta: FilesResponseMeta }>;\n  postMultipart<T>(path: string, form: FormData, opts?: FilesRequestOptions): Envelope<T>;\n  uploadWithProgress<T>(\n    path: string,\n    form: FormData,\n    onProgress: (event: FilesUploadProgressEvent) => void,\n    opts?: FilesRequestOptions,\n  ): Envelope<T>;\n  downloadBlob(path: string, opts?: FilesRequestOptions): BlobEnvelope;\n  downloadBlobWithProgress(\n    path: string,\n    onProgress: (event: FilesDownloadProgressEvent) => void,\n    opts?: FilesRequestOptions,\n  ): BlobEnvelope;\n}\n\nexport interface FilesShareLink {\n  id: string;\n  token: string;\n  shortToken: string | null;\n  permissionLevel: string;\n  label: string | null;\n  expiresAt: string | null;\n  maxUses: number | null;\n  useCount: number;\n  isActive: boolean;\n  createdAt: string | null;\n  lastUsedAt: string | null;\n}\n\nexport interface FilesCreateShareLinkOptions {\n  resourceType: string;\n  resourceId: string;\n  permissionLevel?: string;\n  expiresAt?: string | null;\n  maxUses?: number | null;\n  label?: string | null;\n}\n\n/** The host's share-link store (matrx-frontend: `utils/permissions/shareLinks`). */\nexport interface FilesShareLinks {\n  shareLinkUrl(token: string): string;\n  createShareLink(options: FilesCreateShareLinkOptions): Promise<{\n    success: boolean;\n    token?: string;\n    shortToken?: string | null;\n    url?: string;\n    error?: string;\n  }>;\n  listShareLinks(resourceType: string, resourceId: string): Promise<FilesShareLink[]>;\n  revokeShareLink(linkId: string): Promise<{ success: boolean; error?: string }>;\n}\n\n/** The store the engine's slice is mounted in (under `cloudFiles`). */\nexport interface FilesStore {\n  getState(): unknown;\n  dispatch(action: unknown): unknown;\n}\n\n/** Where new uploads land by default: the person's current organization / project / task. */\nexport interface FilesScope {\n  /** The signed-in person (ownership checks). */\n  userId?: string | null;\n  organizationId: string | null;\n  projectId: string | null;\n  taskId: string | null;\n}\n\nexport interface FilesNotifyPort {\n  success(message: string, options?: { description?: string; id?: string | number; duration?: number }): void;\n  error(message: string, options?: { description?: string; id?: string | number; duration?: number }): void;\n}\n\nexport interface FilesHost {\n  /** A supabase-js client for the signed-in person (the engine reads the `files` and `iam` schemas). */\n  db: SupabaseClient<any, any, any>;\n  server: FilesServerClient;\n  /** The store the `cloudFiles` reducer is mounted in; null until it exists. */\n  store(): FilesStore | null;\n  /** The person's current organization / project / task, read from `state`. Default: none. */\n  scope?(state: unknown): FilesScope;\n  /**\n   * Resolve the organization a write lands in. Given a declared id, return it;\n   * otherwise ask the person (the host's chooser). Default: the declared id,\n   * else the scope's organization, else a named error.\n   */\n  ensureOrganizationContext?(options: { organizationId?: string | null }): Promise<string>;\n  shareLinks?: FilesShareLinks;\n  notify?: FilesNotifyPort;\n}\n\nexport class FilesHostNotConfiguredError extends Error {\n  constructor(member: string) {\n    super(\n      `@ai-matrx/media/files-engine: \"${member}\" was used before configureFilesHost(...) ran. ` +\n        \"Call configureFilesHost({ db, server, store }) once at startup, before the store is created.\",\n    );\n    this.name = \"FilesHostNotConfiguredError\";\n  }\n}\n\nlet host: FilesHost | null = null;\n\nexport function configureFilesHost(next: FilesHost): void {\n  host = next;\n}\n\nexport function isFilesHostConfigured(): boolean {\n  return host !== null;\n}\n\nexport function getFilesHost(member: string): FilesHost {\n  if (!host) throw new FilesHostNotConfiguredError(member);\n  return host;\n}\n\n/** For tests: drop the configured host. */\nexport function __resetFilesHostForTests(): void {\n  host = null;\n}\n"],"mappings":"AAgKO,MAAM,oCAAoC,MAAM;AAAA,EACrD,YAAY,QAAgB;AAC1B;AAAA,MACE,kCAAkC,MAAM;AAAA,IAE1C;AACA,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAI,OAAyB;AAEtB,SAAS,mBAAmB,MAAuB;AACxD,SAAO;AACT;AAEO,SAAS,wBAAiC;AAC/C,SAAO,SAAS;AAClB;AAEO,SAAS,aAAa,QAA2B;AACtD,MAAI,CAAC,KAAM,OAAM,IAAI,4BAA4B,MAAM;AACvD,SAAO;AACT;AAGO,SAAS,2BAAiC;AAC/C,SAAO;AACT;","names":[]}

package/dist/files/engine/host/org.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Organization seam — where a write lands. The host's chooser asks the person
+ * when nothing declared one; a host without a chooser uses the declared id,
+ * then the person's current organization, and otherwise refuses by name.
+ */
+export declare function ensureOrganizationContext(options?: {
+    organizationId?: string | null;
+}): Promise<string>;

package/dist/files/engine/host/org.js

@@ -0,0 +1,16 @@
+import { getFilesHost } from "./configure.js";
+import { selectOrganizationId, getStoreSingleton } from "./store.js";
+async function ensureOrganizationContext(options = {}) {
+  const host = getFilesHost("ensureOrganizationContext");
+  if (host.ensureOrganizationContext) return host.ensureOrganizationContext(options);
+  if (options.organizationId) return options.organizationId;
+  const current = selectOrganizationId(getStoreSingleton()?.getState());
+  if (current) return current;
+  throw new Error(
+    "@ai-matrx/media/files-engine: this write needs an organization and none is selected \u2014 choose one, then retry."
+  );
+}
+export {
+  ensureOrganizationContext
+};
+//# sourceMappingURL=org.js.map

package/dist/files/engine/host/org.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/host/org.ts"],"sourcesContent":["/**\n * Organization seam — where a write lands. The host's chooser asks the person\n * when nothing declared one; a host without a chooser uses the declared id,\n * then the person's current organization, and otherwise refuses by name.\n */\n\nimport { getFilesHost } from \"./configure\";\nimport { selectOrganizationId, getStoreSingleton } from \"./store\";\n\nexport async function ensureOrganizationContext(\n  options: { organizationId?: string | null } = {},\n): Promise<string> {\n  const host = getFilesHost(\"ensureOrganizationContext\");\n  if (host.ensureOrganizationContext) return host.ensureOrganizationContext(options);\n  if (options.organizationId) return options.organizationId;\n  const current = selectOrganizationId(getStoreSingleton()?.getState());\n  if (current) return current;\n  throw new Error(\n    \"@ai-matrx/media/files-engine: this write needs an organization and none is selected — choose one, then retry.\",\n  );\n}\n"],"mappings":"AAMA,SAAS,oBAAoB;AAC7B,SAAS,sBAAsB,yBAAyB;AAExD,eAAsB,0BACpB,UAA8C,CAAC,GAC9B;AACjB,QAAM,OAAO,aAAa,2BAA2B;AACrD,MAAI,KAAK,0BAA2B,QAAO,KAAK,0BAA0B,OAAO;AACjF,MAAI,QAAQ,eAAgB,QAAO,QAAQ;AAC3C,QAAM,UAAU,qBAAqB,kBAAkB,GAAG,SAAS,CAAC;AACpE,MAAI,QAAS,QAAO;AACpB,QAAM,IAAI;AAAA,IACR;AAAA,EACF;AACF;","names":[]}

package/dist/files/engine/host/python-client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Server seam — the AI Matrx server client the engine calls (same names the
+ * call sites imported from matrx-frontend's `lib/python-client`). Each export
+ * forwards at CALL time to the configured host's `server` (`./configure.ts`).
+ */
+import { type FilesDownloadProgressEvent, type FilesRequestOptions, type FilesResponseMeta, type FilesUploadProgressEvent } from "./configure.js";
+export type RequestOptions = FilesRequestOptions;
+export type ResponseMeta = FilesResponseMeta;
+export type UploadProgressEvent = FilesUploadProgressEvent;
+export type DownloadProgressEvent = FilesDownloadProgressEvent;
+export declare const resolveFilesBaseUrl: (override?: string) => string;
+export declare const resolveBaseUrlForPath: (path: string, override?: string, method?: string) => string;
+export declare const buildHeaders: (opts: FilesRequestOptions, includeContentType: boolean, method?: string) => Promise<{
+    headers: Record<string, string>;
+    requestId: string;
+}>;
+export declare const getJson: <T>(path: string, opts?: FilesRequestOptions) => Promise<{
+    data: T;
+    meta: FilesResponseMeta;
+}>;
+export declare const postJson: <T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions) => Promise<{
+    data: T;
+    meta: FilesResponseMeta;
+}>;
+export declare const patchJson: <T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions) => Promise<{
+    data: T;
+    meta: FilesResponseMeta;
+}>;
+export declare const putJson: <T, B = unknown>(path: string, body: B, opts?: FilesRequestOptions) => Promise<{
+    data: T;
+    meta: FilesResponseMeta;
+}>;
+export declare const del: <T = null>(path: string, opts?: FilesRequestOptions) => Promise<{
+    data: T | null;
+    meta: FilesResponseMeta;
+}>;
+export declare const delJson: <T = null, B = unknown>(path: string, body: B, opts?: FilesRequestOptions) => Promise<{
+    data: T | null;
+    meta: FilesResponseMeta;
+}>;
+export declare const postMultipart: <T>(path: string, form: FormData, opts?: FilesRequestOptions) => Promise<{
+    data: T;
+    meta: FilesResponseMeta;
+}>;
+export declare const uploadWithProgress: <T>(path: string, form: FormData, onProgress: (event: FilesUploadProgressEvent) => void, opts?: FilesRequestOptions) => Promise<{
+    data: T;
+    meta: FilesResponseMeta;
+}>;
+export declare const downloadBlob: (path: string, opts?: FilesRequestOptions) => Promise<{
+    blob: Blob;
+    meta: FilesResponseMeta;
+    filename: string | null;
+}>;
+export declare const downloadBlobWithProgress: (path: string, onProgress: (event: FilesDownloadProgressEvent) => void, opts?: FilesRequestOptions) => Promise<{
+    blob: Blob;
+    meta: FilesResponseMeta;
+    filename: string | null;
+}>;
+/** Client-generated request id (sent as `X-Request-Id`). */
+export declare function newRequestId(): string;

package/dist/files/engine/host/python-client.js

@@ -0,0 +1,46 @@
+import {
+  getFilesHost
+} from "./configure.js";
+function forward(member) {
+  const forwarded = (...args) => {
+    const target = getFilesHost(`server.${member}`).server[member];
+    return target(...args);
+  };
+  return forwarded;
+}
+const resolveFilesBaseUrl = forward("resolveFilesBaseUrl");
+const resolveBaseUrlForPath = forward("resolveBaseUrlForPath");
+const buildHeaders = forward("buildHeaders");
+const getJson = forward("getJson");
+const postJson = forward("postJson");
+const patchJson = forward("patchJson");
+const putJson = forward("putJson");
+const del = forward("del");
+const delJson = forward("delJson");
+const postMultipart = forward("postMultipart");
+const uploadWithProgress = forward("uploadWithProgress");
+const downloadBlob = forward("downloadBlob");
+const downloadBlobWithProgress = forward("downloadBlobWithProgress");
+function newRequestId() {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID();
+  }
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+export {
+  buildHeaders,
+  del,
+  delJson,
+  downloadBlob,
+  downloadBlobWithProgress,
+  getJson,
+  newRequestId,
+  patchJson,
+  postJson,
+  postMultipart,
+  putJson,
+  resolveBaseUrlForPath,
+  resolveFilesBaseUrl,
+  uploadWithProgress
+};
+//# sourceMappingURL=python-client.js.map