@ai-matrx/media 0.8.0 → 0.9.0

package/dist/files/engine/api/office.d.ts

@@ -0,0 +1,27 @@
+/**
+ * features/files/api/office.ts
+ *
+ * Office (docx / pptx / xlsx) server-side read endpoints on aidream — the
+ * matrx-files Office codec exposed over HTTP. Powers the OfficePreview
+ * previewer (extract → markdown) and the "Convert to PDF" file action.
+ *
+ * Backend: aidream/api/routers/office_generation.py (`/office/*`).
+ */
+import type { components } from "@ai-matrx/agents/generated/api-types";
+/** Markdown view of an existing Office file (whole doc + per-portion). */
+export type OfficeExtraction = components["schemas"]["OfficeExtractionResponse"];
+/** One slide / sheet / section of an extracted document. */
+export type OfficePortion = components["schemas"]["OfficePortionOut"];
+/** FileRef for a generated / converted Office asset. */
+export type OfficeFileRef = components["schemas"]["OfficeGenerationResponse"];
+/**
+ * Extract an Office file the caller can read into markdown + portions.
+ * The server does the parsing (incl. the LibreOffice legacy bridge for
+ * .doc/.ppt) — the bytes never reach the browser.
+ */
+export declare function extractOfficeMarkdown(fileId: string): Promise<OfficeExtraction>;
+/**
+ * Render an Office file to PDF server-side (LibreOffice). Returns the NEW
+ * pdf file's FileRef — callers typically navigate to `/files/f/{file_id}`.
+ */
+export declare function convertOfficeToPdf(fileId: string): Promise<OfficeFileRef>;

package/dist/files/engine/api/office.js

@@ -0,0 +1,19 @@
+import { apiGet, apiPost, buildPath } from "../host/typed-client.js";
+async function extractOfficeMarkdown(fileId) {
+  const { data } = await apiGet(
+    buildPath("/office/{file_id}/markdown", { file_id: fileId })
+  );
+  return data;
+}
+async function convertOfficeToPdf(fileId) {
+  const { data } = await apiPost(
+    buildPath("/office/{file_id}/convert", { file_id: fileId }),
+    { target: "pdf" }
+  );
+  return data;
+}
+export {
+  convertOfficeToPdf,
+  extractOfficeMarkdown
+};
+//# sourceMappingURL=office.js.map

package/dist/files/engine/api/office.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/api/office.ts"],"sourcesContent":["/**\n * features/files/api/office.ts\n *\n * Office (docx / pptx / xlsx) server-side read endpoints on aidream — the\n * matrx-files Office codec exposed over HTTP. Powers the OfficePreview\n * previewer (extract → markdown) and the \"Convert to PDF\" file action.\n *\n * Backend: aidream/api/routers/office_generation.py (`/office/*`).\n */\n\nimport { apiGet, apiPost, buildPath } from \"../host/typed-client\";\nimport type { components } from \"@ai-matrx/agents/generated/api-types\";\n\n/** Markdown view of an existing Office file (whole doc + per-portion). */\nexport type OfficeExtraction =\n  components[\"schemas\"][\"OfficeExtractionResponse\"];\n/** One slide / sheet / section of an extracted document. */\nexport type OfficePortion = components[\"schemas\"][\"OfficePortionOut\"];\n/** FileRef for a generated / converted Office asset. */\nexport type OfficeFileRef = components[\"schemas\"][\"OfficeGenerationResponse\"];\n\n/**\n * Extract an Office file the caller can read into markdown + portions.\n * The server does the parsing (incl. the LibreOffice legacy bridge for\n * .doc/.ppt) — the bytes never reach the browser.\n */\nexport async function extractOfficeMarkdown(\n  fileId: string,\n): Promise<OfficeExtraction> {\n  const { data } = await apiGet(\n    buildPath(\"/office/{file_id}/markdown\", { file_id: fileId }),\n  );\n  return data;\n}\n\n/**\n * Render an Office file to PDF server-side (LibreOffice). Returns the NEW\n * pdf file's FileRef — callers typically navigate to `/files/f/{file_id}`.\n */\nexport async function convertOfficeToPdf(\n  fileId: string,\n): Promise<OfficeFileRef> {\n  const { data } = await apiPost(\n    buildPath(\"/office/{file_id}/convert\", { file_id: fileId }),\n    { target: \"pdf\" },\n  );\n  return data;\n}\n"],"mappings":"AAUA,SAAS,QAAQ,SAAS,iBAAiB;AAgB3C,eAAsB,sBACpB,QAC2B;AAC3B,QAAM,EAAE,KAAK,IAAI,MAAM;AAAA,IACrB,UAAU,8BAA8B,EAAE,SAAS,OAAO,CAAC;AAAA,EAC7D;AACA,SAAO;AACT;AAMA,eAAsB,mBACpB,QACwB;AACxB,QAAM,EAAE,KAAK,IAAI,MAAM;AAAA,IACrB,UAAU,6BAA6B,EAAE,SAAS,OAAO,CAAC;AAAA,IAC1D,EAAE,QAAQ,MAAM;AAAA,EAClB;AACA,SAAO;AACT;","names":[]}

package/dist/files/engine/api/permissions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * features/files/api/permissions.ts
+ *
+ * Grant / revoke permissions on files and folders. Direct-to-Supabase:
+ * `iam.fn_list_resource_permissions` / `fn_grant_resource_permission` /
+ * `fn_revoke_resource_permission` mirror the retired Python
+ * `PermissionsManager` exactly — every call requires 'admin' access on the
+ * resource via `iam.has_access(type, id, 'admin')`, the same auth.uid()-based
+ * resolver RLS itself calls. Identity from auth.uid() only.
+ */
+import type { GrantPermissionRequest, IamResourcePermissionRpcRow } from "../types.js";
+export declare function listFilePermissions(fileId: string, _opts?: unknown): Promise<{
+    data: IamResourcePermissionRpcRow[];
+}>;
+export declare function grantFilePermission(fileId: string, body: GrantPermissionRequest, _opts?: unknown): Promise<{
+    data: IamResourcePermissionRpcRow;
+}>;
+export declare function revokeFilePermission(fileId: string, granteeId: string, params?: {
+    granteeType?: "user" | "group";
+}, _opts?: unknown): Promise<{
+    data: {
+        deleted: boolean;
+    };
+}>;
+export declare function listFolderPermissions(folderId: string, _opts?: unknown): Promise<{
+    data: IamResourcePermissionRpcRow[];
+}>;
+export declare function grantFolderPermission(folderId: string, body: GrantPermissionRequest, _opts?: unknown): Promise<{
+    data: IamResourcePermissionRpcRow;
+}>;
+export declare function revokeFolderPermission(folderId: string, granteeId: string, params?: {
+    granteeType?: "user" | "group";
+}, _opts?: unknown): Promise<{
+    data: {
+        deleted: boolean;
+    };
+}>;

package/dist/files/engine/api/permissions.js

@@ -0,0 +1,109 @@
+import { createClient } from "../host/supabase.js";
+import { iamDb } from "../host/supabase.js";
+const SHARING_UNAVAILABLE = {
+  file: {
+    list: "We couldn't load who this file is shared with. You may not be allowed to manage its sharing.",
+    grant: "We couldn't share this file. You may not be allowed to manage its sharing.",
+    revoke: "We couldn't remove that person's access to this file. You may not be allowed to manage its sharing."
+  },
+  folder: {
+    list: "We couldn't load who this folder is shared with. You may not be allowed to manage its sharing.",
+    grant: "We couldn't share this folder. You may not be allowed to manage its sharing.",
+    revoke: "We couldn't remove that person's access to this folder. You may not be allowed to manage its sharing."
+  }
+};
+function parsePermissionRpcRows(data) {
+  if (!Array.isArray(data)) return [];
+  return data;
+}
+function parsePermissionRpcRow(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new Error("fn_grant_resource_permission returned an invalid row");
+  }
+  return data;
+}
+async function listPermissions(resourceType, resourceId) {
+  const supabase = createClient();
+  const { data, error } = await iamDb(supabase).rpc(
+    "fn_list_resource_permissions",
+    {
+      p_resource_type: resourceType,
+      p_resource_id: resourceId
+    }
+  );
+  if (error) throw new Error(SHARING_UNAVAILABLE[resourceType].list);
+  return parsePermissionRpcRows(data);
+}
+async function grantPermission(resourceType, resourceId, body) {
+  const supabase = createClient();
+  const { data, error } = await iamDb(supabase).rpc(
+    "fn_grant_resource_permission",
+    {
+      p_resource_type: resourceType,
+      p_resource_id: resourceId,
+      p_grantee_id: body.grantee_id,
+      p_grantee_type: body.grantee_type ?? "user",
+      p_level: body.level ?? "read",
+      p_expires_at: body.expires_at ?? void 0
+    }
+  );
+  if (error) throw new Error(SHARING_UNAVAILABLE[resourceType].grant);
+  return parsePermissionRpcRow(data);
+}
+async function revokePermission(resourceType, resourceId, granteeId, granteeType = "user") {
+  const supabase = createClient();
+  const { data, error } = await iamDb(supabase).rpc(
+    "fn_revoke_resource_permission",
+    {
+      p_resource_type: resourceType,
+      p_resource_id: resourceId,
+      p_grantee_id: granteeId,
+      // The user-group ACL tier is removed DB-side; 'group' has no meaningful
+      // target column, so it's treated the same as the default 'user' grantee.
+      p_grantee_type: granteeType === "group" ? "user" : granteeType
+    }
+  );
+  if (error) throw new Error(SHARING_UNAVAILABLE[resourceType].revoke);
+  return { deleted: Boolean(data) };
+}
+async function listFilePermissions(fileId, _opts) {
+  return { data: await listPermissions("file", fileId) };
+}
+async function grantFilePermission(fileId, body, _opts) {
+  return { data: await grantPermission("file", fileId, body) };
+}
+async function revokeFilePermission(fileId, granteeId, params = {}, _opts) {
+  return {
+    data: await revokePermission(
+      "file",
+      fileId,
+      granteeId,
+      params.granteeType ?? "user"
+    )
+  };
+}
+async function listFolderPermissions(folderId, _opts) {
+  return { data: await listPermissions("folder", folderId) };
+}
+async function grantFolderPermission(folderId, body, _opts) {
+  return { data: await grantPermission("folder", folderId, body) };
+}
+async function revokeFolderPermission(folderId, granteeId, params = {}, _opts) {
+  return {
+    data: await revokePermission(
+      "folder",
+      folderId,
+      granteeId,
+      params.granteeType ?? "user"
+    )
+  };
+}
+export {
+  grantFilePermission,
+  grantFolderPermission,
+  listFilePermissions,
+  listFolderPermissions,
+  revokeFilePermission,
+  revokeFolderPermission
+};
+//# sourceMappingURL=permissions.js.map

package/dist/files/engine/api/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/api/permissions.ts"],"sourcesContent":["/**\n * features/files/api/permissions.ts\n *\n * Grant / revoke permissions on files and folders. Direct-to-Supabase:\n * `iam.fn_list_resource_permissions` / `fn_grant_resource_permission` /\n * `fn_revoke_resource_permission` mirror the retired Python\n * `PermissionsManager` exactly — every call requires 'admin' access on the\n * resource via `iam.has_access(type, id, 'admin')`, the same auth.uid()-based\n * resolver RLS itself calls. Identity from auth.uid() only.\n */\n\nimport { createClient } from \"../host/supabase\";\nimport { iamDb } from \"../host/supabase\";\nimport type {\n  GrantPermissionRequest,\n  IamResourcePermissionRpcRow,\n} from \"../types\";\n\n/**\n * What the user reads when one of the three RPCs fails. The driver's own text\n * (\"permission denied for schema iam\", \"PGRST202 …\") is never shown: the RPC\n * refuses unless the caller has 'admin' on the resource, so the only honest\n * thing to say is that the sharing settings didn't load or the change didn't\n * stick. The raw PostgREST error is still captured in full by the client-wide\n * proxy in `lib/diagnostics/supabaseErrorCapture.ts`, so nothing is lost — it\n * just lands in the Error Inspector instead of in front of a person.\n */\nconst SHARING_UNAVAILABLE = {\n  file: {\n    list: \"We couldn't load who this file is shared with. You may not be allowed to manage its sharing.\",\n    grant: \"We couldn't share this file. You may not be allowed to manage its sharing.\",\n    revoke: \"We couldn't remove that person's access to this file. You may not be allowed to manage its sharing.\",\n  },\n  folder: {\n    list: \"We couldn't load who this folder is shared with. You may not be allowed to manage its sharing.\",\n    grant: \"We couldn't share this folder. You may not be allowed to manage its sharing.\",\n    revoke: \"We couldn't remove that person's access to this folder. You may not be allowed to manage its sharing.\",\n  },\n} as const;\n\nfunction parsePermissionRpcRows(data: unknown): IamResourcePermissionRpcRow[] {\n  if (!Array.isArray(data)) return [];\n  return data as unknown as IamResourcePermissionRpcRow[];\n}\n\nfunction parsePermissionRpcRow(data: unknown): IamResourcePermissionRpcRow {\n  if (!data || typeof data !== \"object\" || Array.isArray(data)) {\n    throw new Error(\"fn_grant_resource_permission returned an invalid row\");\n  }\n  return data as unknown as IamResourcePermissionRpcRow;\n}\n\nasync function listPermissions(\n  resourceType: \"file\" | \"folder\",\n  resourceId: string,\n): Promise<IamResourcePermissionRpcRow[]> {\n  const supabase = createClient();\n  const { data, error } = await iamDb(supabase).rpc(\n    \"fn_list_resource_permissions\",\n    {\n      p_resource_type: resourceType,\n      p_resource_id: resourceId,\n    },\n  );\n  if (error) throw new Error(SHARING_UNAVAILABLE[resourceType].list);\n  return parsePermissionRpcRows(data);\n}\n\nasync function grantPermission(\n  resourceType: \"file\" | \"folder\",\n  resourceId: string,\n  body: GrantPermissionRequest,\n): Promise<IamResourcePermissionRpcRow> {\n  const supabase = createClient();\n  const { data, error } = await iamDb(supabase).rpc(\n    \"fn_grant_resource_permission\",\n    {\n      p_resource_type: resourceType,\n      p_resource_id: resourceId,\n      p_grantee_id: body.grantee_id,\n      p_grantee_type: body.grantee_type ?? \"user\",\n      p_level: body.level ?? \"read\",\n      p_expires_at: body.expires_at ?? undefined,\n    },\n  );\n  if (error) throw new Error(SHARING_UNAVAILABLE[resourceType].grant);\n  return parsePermissionRpcRow(data);\n}\n\nasync function revokePermission(\n  resourceType: \"file\" | \"folder\",\n  resourceId: string,\n  granteeId: string,\n  granteeType: \"user\" | \"group\" = \"user\",\n): Promise<{ deleted: boolean }> {\n  const supabase = createClient();\n  const { data, error } = await iamDb(supabase).rpc(\n    \"fn_revoke_resource_permission\",\n    {\n      p_resource_type: resourceType,\n      p_resource_id: resourceId,\n      p_grantee_id: granteeId,\n      // The user-group ACL tier is removed DB-side; 'group' has no meaningful\n      // target column, so it's treated the same as the default 'user' grantee.\n      p_grantee_type: granteeType === \"group\" ? \"user\" : granteeType,\n    },\n  );\n  if (error) throw new Error(SHARING_UNAVAILABLE[resourceType].revoke);\n  return { deleted: Boolean(data) };\n}\n\n// ---------------------------------------------------------------------------\n// File permissions\n// ---------------------------------------------------------------------------\n\n// `opts` is accepted-and-ignored on every export below — callers still pass\n// the old python-client `{ requestId }` shape (features/files/redux/thunks.ts\n// uses it for its own request ledger, not the network call itself), and\n// dropping the parameter would force every call site to change for no\n// behavioral gain. It plays no role in a direct-Supabase call.\n\nexport async function listFilePermissions(\n  fileId: string,\n  _opts?: unknown,\n): Promise<{ data: IamResourcePermissionRpcRow[] }> {\n  return { data: await listPermissions(\"file\", fileId) };\n}\n\nexport async function grantFilePermission(\n  fileId: string,\n  body: GrantPermissionRequest,\n  _opts?: unknown,\n): Promise<{ data: IamResourcePermissionRpcRow }> {\n  return { data: await grantPermission(\"file\", fileId, body) };\n}\n\nexport async function revokeFilePermission(\n  fileId: string,\n  granteeId: string,\n  params: { granteeType?: \"user\" | \"group\" } = {},\n  _opts?: unknown,\n): Promise<{ data: { deleted: boolean } }> {\n  return {\n    data: await revokePermission(\n      \"file\",\n      fileId,\n      granteeId,\n      params.granteeType ?? \"user\",\n    ),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Folder permissions (cascade to contents)\n// ---------------------------------------------------------------------------\n\nexport async function listFolderPermissions(\n  folderId: string,\n  _opts?: unknown,\n): Promise<{ data: IamResourcePermissionRpcRow[] }> {\n  return { data: await listPermissions(\"folder\", folderId) };\n}\n\nexport async function grantFolderPermission(\n  folderId: string,\n  body: GrantPermissionRequest,\n  _opts?: unknown,\n): Promise<{ data: IamResourcePermissionRpcRow }> {\n  return { data: await grantPermission(\"folder\", folderId, body) };\n}\n\nexport async function revokeFolderPermission(\n  folderId: string,\n  granteeId: string,\n  params: { granteeType?: \"user\" | \"group\" } = {},\n  _opts?: unknown,\n): Promise<{ data: { deleted: boolean } }> {\n  return {\n    data: await revokePermission(\n      \"folder\",\n      folderId,\n      granteeId,\n      params.granteeType ?? \"user\",\n    ),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/files/engine/api/versions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * features/files/api/versions.ts
+ *
+ * File-version endpoints.
+ *
+ * Backend contract: features/files/cld_files_frontend.md §6 (Versions).
+ */
+import { type RequestOptions, type ResponseMeta } from "../host/python-client.js";
+import type { CloudFileVersionRow, FileRecordApi } from "../types.js";
+export declare function listVersions(fileId: string, opts?: RequestOptions): Promise<{
+    data: CloudFileVersionRow[];
+    meta: ResponseMeta;
+}>;
+export declare function getVersion(fileId: string, versionNumber: number, opts?: RequestOptions): Promise<{
+    data: CloudFileVersionRow;
+    meta: ResponseMeta;
+}>;
+export declare function downloadVersion(fileId: string, versionNumber: number, opts?: RequestOptions): Promise<{
+    blob: Blob;
+    filename: string | null;
+    meta: ResponseMeta;
+}>;
+export declare function restoreVersion(fileId: string, versionNumber: number, opts?: RequestOptions): Promise<{
+    data: FileRecordApi;
+    meta: ResponseMeta;
+}>;

package/dist/files/engine/api/versions.js

@@ -0,0 +1,37 @@
+import {
+  downloadBlob,
+  getJson,
+  postJson
+} from "../host/python-client.js";
+async function listVersions(fileId, opts = {}) {
+  return getJson(
+    `/files/${fileId}/versions`,
+    opts
+  );
+}
+async function getVersion(fileId, versionNumber, opts = {}) {
+  return getJson(
+    `/files/${fileId}/versions/${versionNumber}`,
+    opts
+  );
+}
+async function downloadVersion(fileId, versionNumber, opts = {}) {
+  return downloadBlob(
+    `/files/${fileId}/versions/${versionNumber}/download`,
+    opts
+  );
+}
+async function restoreVersion(fileId, versionNumber, opts = {}) {
+  return postJson(
+    `/files/${fileId}/versions/${versionNumber}/restore`,
+    {},
+    opts
+  );
+}
+export {
+  downloadVersion,
+  getVersion,
+  listVersions,
+  restoreVersion
+};
+//# sourceMappingURL=versions.js.map

package/dist/files/engine/api/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/api/versions.ts"],"sourcesContent":["/**\n * features/files/api/versions.ts\n *\n * File-version endpoints.\n *\n * Backend contract: features/files/cld_files_frontend.md §6 (Versions).\n */\n\nimport {\n  downloadBlob,\n  getJson,\n  postJson,\n  type RequestOptions,\n  type ResponseMeta,\n} from \"../host/python-client\";\nimport type { CloudFileVersionRow, FileRecordApi } from \"../types\";\n\n// list/get stay on the raw client: the contract response is `FileVersionRecord`\n// (all-optional + index-signature), whereas consumers read the concrete DB-row\n// `CloudFileVersionRow`. Binding would erase the row's concrete fields.\nexport async function listVersions(\n  fileId: string,\n  opts: RequestOptions = {},\n): Promise<{ data: CloudFileVersionRow[]; meta: ResponseMeta }> {\n  return getJson<CloudFileVersionRow[]>(\n    `/files/${fileId}/versions`,\n    opts,\n  );\n}\n\nexport async function getVersion(\n  fileId: string,\n  versionNumber: number,\n  opts: RequestOptions = {},\n): Promise<{ data: CloudFileVersionRow; meta: ResponseMeta }> {\n  return getJson<CloudFileVersionRow>(\n    `/files/${fileId}/versions/${versionNumber}`,\n    opts,\n  );\n}\n\n// Binary download (blob bytes, not JSON) — stays on the raw `downloadBlob` helper;\n// the typed client only covers JSON responses.\nexport async function downloadVersion(\n  fileId: string,\n  versionNumber: number,\n  opts: RequestOptions = {},\n): Promise<{ blob: Blob; filename: string | null; meta: ResponseMeta }> {\n  return downloadBlob(\n    `/files/${fileId}/versions/${versionNumber}/download`,\n    opts,\n  );\n}\n\nexport async function restoreVersion(\n  fileId: string,\n  versionNumber: number,\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi; meta: ResponseMeta }> {\n  // Stays on the raw client: the contract declares NO request body for this\n  // operation, but the server accepts (and this call sends) an empty `{}` — routing\n  // through `apiPost` would type the body as `undefined` and could change the wire.\n  // The response type is already contract-bound: `FileRecordApi` is an alias of\n  // `components[\"schemas\"][\"FileRecord\"]`, exactly what the operation returns.\n  return postJson<FileRecordApi, Record<string, never>>(\n    `/files/${fileId}/versions/${versionNumber}/restore`,\n    {},\n    opts,\n  );\n}\n"],"mappings":"AAQA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AAMP,eAAsB,aACpB,QACA,OAAuB,CAAC,GACsC;AAC9D,SAAO;AAAA,IACL,UAAU,MAAM;AAAA,IAChB;AAAA,EACF;AACF;AAEA,eAAsB,WACpB,QACA,eACA,OAAuB,CAAC,GACoC;AAC5D,SAAO;AAAA,IACL,UAAU,MAAM,aAAa,aAAa;AAAA,IAC1C;AAAA,EACF;AACF;AAIA,eAAsB,gBACpB,QACA,eACA,OAAuB,CAAC,GAC8C;AACtE,SAAO;AAAA,IACL,UAAU,MAAM,aAAa,aAAa;AAAA,IAC1C;AAAA,EACF;AACF;AAEA,eAAsB,eACpB,QACA,eACA,OAAuB,CAAC,GAC8B;AAMtD,SAAO;AAAA,IACL,UAAU,MAAM,aAAa,aAAa;AAAA,IAC1C,CAAC;AAAA,IACD;AAAA,EACF;AACF;","names":[]}

package/dist/files/engine/cache/idb-store.d.ts

@@ -0,0 +1,95 @@
+/**
+ * features/files/cache/idb-store.ts
+ *
+ * IndexedDB tier of the 3-tier byte cache (memory LRU → IDB → network).
+ *
+ * Dexie wrapper for the `matrx-blob-cache` database — a SEPARATE DB from
+ * `matrx-sync` so cache eviction can never threaten sync persistence.
+ * Schema is intentionally simple: one `blobs` table keyed by a string
+ * cache key, indexed by `userId` (for sign-out purge) and
+ * `lastAccessedAt` (for LRU eviction).
+ *
+ * Cache key strategy (see plan §4A):
+ *   - Owned files (current version): `${userId}:${fileId}:current:${checksum}`
+ *   - Owned files (pinned version):  `${userId}:${fileId}:${N}:${checksum}`
+ *   - URL-keyed entries (share-link bytes, etc.): `${userId}:url:${sha256(url)}`
+ *
+ * Signed S3 URLs (either AWS dialect — SigV4 `X-Amz-*` or SigV2
+ * `AWSAccessKeyId`/`Signature`/`Expires`) are NEVER cached because they
+ * expire — caching them would create stale-URL bugs.
+ *
+ * Failure modes:
+ *   - Private browsing / IDB disabled / quota exceeded: `openBlobCacheDb()`
+ *     rejects → all reads return null, all writes resolve as no-ops. The
+ *     in-memory LRU + network stay functional.
+ *
+ * Identity scoping:
+ *   - Every entry is stamped with `userId`. Sign-out calls `clearForUser`
+ *     so cross-user contamination is structurally impossible.
+ *
+ * Budget:
+ *   - Default 2 GB total. Eviction is size-aware-LRU: oldest entries above
+ *     a 2 MB floor are evicted first; tiny entries (<2 MB) only evict when
+ *     the cache is otherwise full of small entries.
+ *   - QuotaExceededError triggers an immediate eviction down to 70% of
+ *     budget and a single retry. Subsequent failures fall back to network.
+ */
+import Dexie, { type Table } from "dexie";
+export declare const BLOB_CACHE_DB_NAME = "matrx-blob-cache";
+export declare const BLOB_CACHE_SCHEMA_VERSION = 1;
+export declare const DEFAULT_BUDGET_BYTES: number;
+export type BlobCacheSource = "files-download" | "share" | "cdn" | "url";
+export interface BlobCacheEntry {
+    /** Composite cache key — see header comment for the key shape. */
+    key: string;
+    userId: string;
+    /** Null for url-keyed entries (share links / arbitrary URLs). */
+    fileId: string | null;
+    version: number | null;
+    checksum: string | null;
+    mimeType: string;
+    bytes: number;
+    blob: Blob;
+    etag: string | null;
+    fetchedAt: number;
+    lastAccessedAt: number;
+    source: BlobCacheSource;
+}
+interface BlobCacheDb extends Dexie {
+    blobs: Table<BlobCacheEntry, string>;
+}
+/**
+ * Open the Dexie blob-cache DB. Lazy + memoized — the server-render pass
+ * never touches IDB. Returns `null` when IDB is unavailable (private
+ * browsing, server-side, quota exhausted at open time); callers should
+ * treat that as "no persistent tier" and fall through to network.
+ */
+export declare function openBlobCacheDb(): Promise<BlobCacheDb | null>;
+export declare function getEntry(key: string): Promise<BlobCacheEntry | null>;
+export declare function putEntry(entry: BlobCacheEntry): Promise<void>;
+export declare function deleteEntry(key: string): Promise<void>;
+/**
+ * Drop every entry whose key starts with `${userId}:${fileId}:`. Use on
+ * realtime version-bump / hard-delete so every cached version of a file
+ * gets evicted regardless of the version segment in the key.
+ */
+export declare function deleteEntriesForFile(userId: string, fileId: string): Promise<void>;
+/**
+ * Drop every entry for the signed-out user. Called from the sign-out
+ * code path so the next user can never read the previous user's blobs.
+ */
+export declare function clearForUser(userId: string): Promise<void>;
+/**
+ * Test/debug helper. Returns `{ entryCount, totalBytes }`. The admin
+ * observability panel reads this.
+ */
+export declare function getStats(): Promise<{
+    entryCount: number;
+    totalBytes: number;
+}>;
+/**
+ * Public LRU evict for a given user — exposed so the admin observability
+ * panel can offer an "Evict now" button.
+ */
+export declare function evictForUser(userId: string, targetBytes: number): Promise<void>;
+export {};

package/dist/files/engine/cache/idb-store.js

@@ -0,0 +1,172 @@
+import Dexie from "dexie";
+import { logger } from "../support/logger.js";
+import { extractErrorMessage } from "@ai-matrx/data/net";
+const BLOB_CACHE_DB_NAME = "matrx-blob-cache";
+const BLOB_CACHE_SCHEMA_VERSION = 1;
+const DEFAULT_BUDGET_BYTES = 2 * 1024 * 1024 * 1024;
+const SIZE_FLOOR_BYTES = 2 * 1024 * 1024;
+function hasIndexedDb() {
+  if (typeof globalThis === "undefined") return false;
+  return typeof globalThis.indexedDB !== "undefined";
+}
+let dbPromise = null;
+function openBlobCacheDb() {
+  if (dbPromise) return dbPromise;
+  dbPromise = (async () => {
+    if (!hasIndexedDb()) {
+      logger.info("blob-cache.unavailable", {
+        meta: { reason: "no-indexedDB" }
+      });
+      return null;
+    }
+    try {
+      const db = new Dexie(BLOB_CACHE_DB_NAME);
+      db.version(BLOB_CACHE_SCHEMA_VERSION).stores({
+        // Primary key `key`; secondary indexes for purge + eviction.
+        blobs: "key, userId, lastAccessedAt, bytes"
+      });
+      await db.open();
+      logger.info("blob-cache.open.success", {
+        meta: { schemaVersion: BLOB_CACHE_SCHEMA_VERSION }
+      });
+      return db;
+    } catch (err) {
+      logger.warn("blob-cache.open.error", {
+        meta: { error: extractErrorMessage(err) }
+      });
+      return null;
+    }
+  })();
+  return dbPromise;
+}
+async function getEntry(key) {
+  const db = await openBlobCacheDb();
+  if (!db) return null;
+  try {
+    const entry = await db.blobs.get(key);
+    if (!entry) return null;
+    void db.blobs.update(key, { lastAccessedAt: Date.now() });
+    return entry;
+  } catch (err) {
+    logger.warn("blob-cache.read.error", {
+      meta: { key, error: extractErrorMessage(err) }
+    });
+    return null;
+  }
+}
+async function putEntry(entry) {
+  const db = await openBlobCacheDb();
+  if (!db) return;
+  try {
+    await db.blobs.put(entry);
+  } catch (err) {
+    if (isQuotaExceeded(err)) {
+      try {
+        await evictToBudget(db, entry.userId, DEFAULT_BUDGET_BYTES * 0.7);
+        await db.blobs.put(entry);
+      } catch (retryErr) {
+        logger.warn("blob-cache.write.quota-exceeded", {
+          meta: { key: entry.key, error: extractErrorMessage(retryErr) }
+        });
+      }
+      return;
+    }
+    logger.warn("blob-cache.write.error", {
+      meta: { key: entry.key, error: extractErrorMessage(err) }
+    });
+  }
+}
+async function deleteEntry(key) {
+  const db = await openBlobCacheDb();
+  if (!db) return;
+  try {
+    await db.blobs.delete(key);
+  } catch (err) {
+    logger.warn("blob-cache.delete.error", {
+      meta: { key, error: extractErrorMessage(err) }
+    });
+  }
+}
+async function deleteEntriesForFile(userId, fileId) {
+  const db = await openBlobCacheDb();
+  if (!db) return;
+  try {
+    await db.blobs.where("userId").equals(userId).and((entry) => entry.fileId === fileId).delete();
+  } catch (err) {
+    logger.warn("blob-cache.delete-for-file.error", {
+      meta: { userId, fileId, error: extractErrorMessage(err) }
+    });
+  }
+}
+async function clearForUser(userId) {
+  const db = await openBlobCacheDb();
+  if (!db) return;
+  try {
+    await db.blobs.where("userId").equals(userId).delete();
+  } catch (err) {
+    logger.warn("blob-cache.clear-for-user.error", {
+      meta: { userId, error: extractErrorMessage(err) }
+    });
+  }
+}
+async function getStats() {
+  const db = await openBlobCacheDb();
+  if (!db) return { entryCount: 0, totalBytes: 0 };
+  try {
+    let count = 0;
+    let total = 0;
+    await db.blobs.each((entry) => {
+      count += 1;
+      total += entry.bytes;
+    });
+    return { entryCount: count, totalBytes: total };
+  } catch {
+    return { entryCount: 0, totalBytes: 0 };
+  }
+}
+function isQuotaExceeded(err) {
+  if (!err || typeof err !== "object") return false;
+  const e = err;
+  return e.name === "QuotaExceededError" || e.code === 22;
+}
+async function evictToBudget(db, userId, targetBytes) {
+  const entries = await db.blobs.where("userId").equals(userId).toArray();
+  const ordered = entries.sort((a, b) => {
+    const aBig = a.bytes >= SIZE_FLOOR_BYTES ? 0 : 1;
+    const bBig = b.bytes >= SIZE_FLOOR_BYTES ? 0 : 1;
+    if (aBig !== bBig) return aBig - bBig;
+    return a.lastAccessedAt - b.lastAccessedAt;
+  });
+  let total = ordered.reduce((sum, e) => sum + e.bytes, 0);
+  const toDelete = [];
+  for (const entry of ordered) {
+    if (total <= targetBytes) break;
+    toDelete.push(entry.key);
+    total -= entry.bytes;
+  }
+  if (toDelete.length > 0) {
+    await db.blobs.bulkDelete(toDelete);
+    logger.info("blob-cache.evicted", {
+      meta: { userId, evicted: toDelete.length, totalAfter: total }
+    });
+  }
+}
+async function evictForUser(userId, targetBytes) {
+  const db = await openBlobCacheDb();
+  if (!db) return;
+  await evictToBudget(db, userId, targetBytes);
+}
+export {
+  BLOB_CACHE_DB_NAME,
+  BLOB_CACHE_SCHEMA_VERSION,
+  DEFAULT_BUDGET_BYTES,
+  clearForUser,
+  deleteEntriesForFile,
+  deleteEntry,
+  evictForUser,
+  getEntry,
+  getStats,
+  openBlobCacheDb,
+  putEntry
+};
+//# sourceMappingURL=idb-store.js.map

package/dist/files/engine/cache/idb-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/cache/idb-store.ts"],"sourcesContent":["/**\n * features/files/cache/idb-store.ts\n *\n * IndexedDB tier of the 3-tier byte cache (memory LRU → IDB → network).\n *\n * Dexie wrapper for the `matrx-blob-cache` database — a SEPARATE DB from\n * `matrx-sync` so cache eviction can never threaten sync persistence.\n * Schema is intentionally simple: one `blobs` table keyed by a string\n * cache key, indexed by `userId` (for sign-out purge) and\n * `lastAccessedAt` (for LRU eviction).\n *\n * Cache key strategy (see plan §4A):\n *   - Owned files (current version): `${userId}:${fileId}:current:${checksum}`\n *   - Owned files (pinned version):  `${userId}:${fileId}:${N}:${checksum}`\n *   - URL-keyed entries (share-link bytes, etc.): `${userId}:url:${sha256(url)}`\n *\n * Signed S3 URLs (either AWS dialect — SigV4 `X-Amz-*` or SigV2\n * `AWSAccessKeyId`/`Signature`/`Expires`) are NEVER cached because they\n * expire — caching them would create stale-URL bugs.\n *\n * Failure modes:\n *   - Private browsing / IDB disabled / quota exceeded: `openBlobCacheDb()`\n *     rejects → all reads return null, all writes resolve as no-ops. The\n *     in-memory LRU + network stay functional.\n *\n * Identity scoping:\n *   - Every entry is stamped with `userId`. Sign-out calls `clearForUser`\n *     so cross-user contamination is structurally impossible.\n *\n * Budget:\n *   - Default 2 GB total. Eviction is size-aware-LRU: oldest entries above\n *     a 2 MB floor are evicted first; tiny entries (<2 MB) only evict when\n *     the cache is otherwise full of small entries.\n *   - QuotaExceededError triggers an immediate eviction down to 70% of\n *     budget and a single retry. Subsequent failures fall back to network.\n */\n\nimport Dexie, { type Table } from \"dexie\";\nimport { logger } from \"../support/logger\";\nimport { extractErrorMessage } from \"@ai-matrx/data/net\";\n\nexport const BLOB_CACHE_DB_NAME = \"matrx-blob-cache\";\nexport const BLOB_CACHE_SCHEMA_VERSION = 1;\nexport const DEFAULT_BUDGET_BYTES = 2 * 1024 * 1024 * 1024; // 2 GB\nconst SIZE_FLOOR_BYTES = 2 * 1024 * 1024; // 2 MB — evict bigger entries first\n\nexport type BlobCacheSource =\n  | \"files-download\"\n  | \"share\"\n  | \"cdn\"\n  | \"url\";\n\nexport interface BlobCacheEntry {\n  /** Composite cache key — see header comment for the key shape. */\n  key: string;\n  userId: string;\n  /** Null for url-keyed entries (share links / arbitrary URLs). */\n  fileId: string | null;\n  version: number | null;\n  checksum: string | null;\n  mimeType: string;\n  bytes: number;\n  blob: Blob;\n  etag: string | null;\n  fetchedAt: number;\n  lastAccessedAt: number;\n  source: BlobCacheSource;\n}\n\ninterface BlobCacheDb extends Dexie {\n  blobs: Table<BlobCacheEntry, string>;\n}\n\nfunction hasIndexedDb(): boolean {\n  if (typeof globalThis === \"undefined\") return false;\n  return typeof (globalThis as { indexedDB?: unknown }).indexedDB !== \"undefined\";\n}\n\nlet dbPromise: Promise<BlobCacheDb | null> | null = null;\n\n/**\n * Open the Dexie blob-cache DB. Lazy + memoized — the server-render pass\n * never touches IDB. Returns `null` when IDB is unavailable (private\n * browsing, server-side, quota exhausted at open time); callers should\n * treat that as \"no persistent tier\" and fall through to network.\n */\nexport function openBlobCacheDb(): Promise<BlobCacheDb | null> {\n  if (dbPromise) return dbPromise;\n  dbPromise = (async () => {\n    if (!hasIndexedDb()) {\n      logger.info(\"blob-cache.unavailable\", {\n        meta: { reason: \"no-indexedDB\" },\n      });\n      return null;\n    }\n    try {\n      const db = new Dexie(BLOB_CACHE_DB_NAME) as BlobCacheDb;\n      db.version(BLOB_CACHE_SCHEMA_VERSION).stores({\n        // Primary key `key`; secondary indexes for purge + eviction.\n        blobs: \"key, userId, lastAccessedAt, bytes\",\n      });\n      await db.open();\n      logger.info(\"blob-cache.open.success\", {\n        meta: { schemaVersion: BLOB_CACHE_SCHEMA_VERSION },\n      });\n      return db;\n    } catch (err) {\n      logger.warn(\"blob-cache.open.error\", {\n        meta: { error: extractErrorMessage(err) },\n      });\n      return null;\n    }\n  })();\n  return dbPromise;\n}\n\n// ---------------------------------------------------------------------------\n// Read / write\n// ---------------------------------------------------------------------------\n\nexport async function getEntry(key: string): Promise<BlobCacheEntry | null> {\n  const db = await openBlobCacheDb();\n  if (!db) return null;\n  try {\n    const entry = await db.blobs.get(key);\n    if (!entry) return null;\n    // Bump LRU position. Fire-and-forget — the read result is already\n    // returned, and a missed lastAccessedAt bump just shortens this entry's\n    // lifetime in the next eviction pass (acceptable).\n    void db.blobs.update(key, { lastAccessedAt: Date.now() });\n    return entry;\n  } catch (err) {\n    logger.warn(\"blob-cache.read.error\", {\n      meta: { key, error: extractErrorMessage(err) },\n    });\n    return null;\n  }\n}\n\nexport async function putEntry(entry: BlobCacheEntry): Promise<void> {\n  const db = await openBlobCacheDb();\n  if (!db) return;\n  try {\n    await db.blobs.put(entry);\n    // Best-effort eviction pass. If quota is exhausted we'll catch and\n    // retry the put once after an emergency eviction.\n  } catch (err) {\n    // Quota-exceeded: try to free space, retry once, then give up.\n    if (isQuotaExceeded(err)) {\n      try {\n        await evictToBudget(db, entry.userId, DEFAULT_BUDGET_BYTES * 0.7);\n        await db.blobs.put(entry);\n      } catch (retryErr) {\n        logger.warn(\"blob-cache.write.quota-exceeded\", {\n          meta: { key: entry.key, error: extractErrorMessage(retryErr) },\n        });\n      }\n      return;\n    }\n    logger.warn(\"blob-cache.write.error\", {\n      meta: { key: entry.key, error: extractErrorMessage(err) },\n    });\n  }\n}\n\nexport async function deleteEntry(key: string): Promise<void> {\n  const db = await openBlobCacheDb();\n  if (!db) return;\n  try {\n    await db.blobs.delete(key);\n  } catch (err) {\n    logger.warn(\"blob-cache.delete.error\", {\n      meta: { key, error: extractErrorMessage(err) },\n    });\n  }\n}\n\n/**\n * Drop every entry whose key starts with `${userId}:${fileId}:`. Use on\n * realtime version-bump / hard-delete so every cached version of a file\n * gets evicted regardless of the version segment in the key.\n */\nexport async function deleteEntriesForFile(\n  userId: string,\n  fileId: string,\n): Promise<void> {\n  const db = await openBlobCacheDb();\n  if (!db) return;\n  try {\n    await db.blobs.where(\"userId\").equals(userId).and((entry) => entry.fileId === fileId).delete();\n  } catch (err) {\n    logger.warn(\"blob-cache.delete-for-file.error\", {\n      meta: { userId, fileId, error: extractErrorMessage(err) },\n    });\n  }\n}\n\n/**\n * Drop every entry for the signed-out user. Called from the sign-out\n * code path so the next user can never read the previous user's blobs.\n */\nexport async function clearForUser(userId: string): Promise<void> {\n  const db = await openBlobCacheDb();\n  if (!db) return;\n  try {\n    await db.blobs.where(\"userId\").equals(userId).delete();\n  } catch (err) {\n    logger.warn(\"blob-cache.clear-for-user.error\", {\n      meta: { userId, error: extractErrorMessage(err) },\n    });\n  }\n}\n\n/**\n * Test/debug helper. Returns `{ entryCount, totalBytes }`. The admin\n * observability panel reads this.\n */\nexport async function getStats(): Promise<{ entryCount: number; totalBytes: number }> {\n  const db = await openBlobCacheDb();\n  if (!db) return { entryCount: 0, totalBytes: 0 };\n  try {\n    let count = 0;\n    let total = 0;\n    await db.blobs.each((entry) => {\n      count += 1;\n      total += entry.bytes;\n    });\n    return { entryCount: count, totalBytes: total };\n  } catch {\n    return { entryCount: 0, totalBytes: 0 };\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Eviction\n// ---------------------------------------------------------------------------\n\nfunction isQuotaExceeded(err: unknown): boolean {\n  if (!err || typeof err !== \"object\") return false;\n  const e = err as { name?: string; code?: number };\n  return e.name === \"QuotaExceededError\" || e.code === 22;\n}\n\n/**\n * Evict entries (size-aware-LRU) for `userId` until total bytes ≤ target.\n *\n * Strategy: entries are sorted by `(bytes >= SIZE_FLOOR_BYTES, lastAccessedAt)`\n * so large stale entries go first; small entries only get evicted once the\n * large pile is gone. Stops when the per-user total drops below `targetBytes`.\n */\nasync function evictToBudget(\n  db: BlobCacheDb,\n  userId: string,\n  targetBytes: number,\n): Promise<void> {\n  const entries = await db.blobs\n    .where(\"userId\")\n    .equals(userId)\n    .toArray();\n  const ordered = entries.sort((a, b) => {\n    const aBig = a.bytes >= SIZE_FLOOR_BYTES ? 0 : 1;\n    const bBig = b.bytes >= SIZE_FLOOR_BYTES ? 0 : 1;\n    if (aBig !== bBig) return aBig - bBig;\n    return a.lastAccessedAt - b.lastAccessedAt;\n  });\n  let total = ordered.reduce((sum, e) => sum + e.bytes, 0);\n  const toDelete: string[] = [];\n  for (const entry of ordered) {\n    if (total <= targetBytes) break;\n    toDelete.push(entry.key);\n    total -= entry.bytes;\n  }\n  if (toDelete.length > 0) {\n    await db.blobs.bulkDelete(toDelete);\n    logger.info(\"blob-cache.evicted\", {\n      meta: { userId, evicted: toDelete.length, totalAfter: total },\n    });\n  }\n}\n\n/**\n * Public LRU evict for a given user — exposed so the admin observability\n * panel can offer an \"Evict now\" button.\n */\nexport async function evictForUser(userId: string, targetBytes: number): Promise<void> {\n  const db = await openBlobCacheDb();\n  if (!db) return;\n  await evictToBudget(db, userId, targetBytes);\n}\n"],"mappings":"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","names":[]}

package/dist/files/engine/cache/policy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * features/files/cache/policy.ts
+ *
+ * Per-MIME size policy for the IndexedDB tier. The in-memory LRU caches
+ * everything (it's session-scoped and bounded by total bytes); IDB only
+ * persists what's worth re-loading across page reloads.
+ *
+ * The defaults are conservative: cache the large, expensive-to-re-fetch
+ * artifacts (PDFs, video posters, audio) and the small text-y assets
+ * (markdown, JSON, code) that previewers consult repeatedly.
+ *
+ * Returned `false` means "do not write to IDB". Memory LRU still caches.
+ */
+export declare function shouldPersistInIdb(mimeType: string | null | undefined, byteSize: number): boolean;

package/dist/files/engine/cache/policy.js

@@ -0,0 +1,40 @@
+const POLICIES = [
+  { prefix: "image/", maxBytes: 50 * 1024 * 1024 },
+  { prefix: "audio/", maxBytes: 100 * 1024 * 1024 },
+  // Videos cache only up to 50 MB by default. Larger videos rely on
+  // native HTML5 streaming + server-side Range responses.
+  { prefix: "video/", maxBytes: 50 * 1024 * 1024 },
+  { exact: ["application/pdf"], maxBytes: 250 * 1024 * 1024 },
+  {
+    exact: [
+      "application/zip",
+      "application/x-zip-compressed",
+      "application/x-tar",
+      "application/gzip"
+    ],
+    maxBytes: 500 * 1024 * 1024
+  },
+  {
+    prefix: "text/",
+    maxBytes: 10 * 1024 * 1024
+  },
+  { exact: ["application/json", "application/xml"], maxBytes: 10 * 1024 * 1024 }
+];
+const FALLBACK_MAX_BYTES = 25 * 1024 * 1024;
+function shouldPersistInIdb(mimeType, byteSize) {
+  if (!mimeType || byteSize <= 0) return false;
+  const normalized = mimeType.toLowerCase();
+  for (const policy of POLICIES) {
+    if (policy.exact?.includes(normalized)) {
+      return byteSize <= policy.maxBytes;
+    }
+    if (policy.prefix && normalized.startsWith(policy.prefix)) {
+      return byteSize <= policy.maxBytes;
+    }
+  }
+  return byteSize <= FALLBACK_MAX_BYTES;
+}
+export {
+  shouldPersistInIdb
+};
+//# sourceMappingURL=policy.js.map