@ai-matrx/media 0.8.0 → 0.9.1

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

@@ -0,0 +1,249 @@
+/**
+ * features/files/api/files.ts
+ *
+ * REST endpoints under /files/*. Wraps the typed client with endpoint-specific
+ * args/returns so thunks don't hand-craft URLs or bodies.
+ *
+ * Backend contract: features/files/cld_files_frontend.md §6 (Files).
+ */
+import { type DownloadProgressEvent, type RequestOptions, type ResponseMeta, type UploadProgressEvent } from "../host/python-client.js";
+import type { components } from "@ai-matrx/agents/generated/api-types";
+import type { BulkDeleteFilesRequest, BulkMoveFilesRequest, BulkResponse, CopyFileRequest, FilePatchRequest, FileRecordApi, FileUploadResponse, PermissionLevel, RenameFileRequest, SearchFilesParams, SearchFilesResponse, Visibility } from "../types.js";
+export interface UploadFileParams {
+    file: File;
+    filePath: string;
+    visibility?: Visibility;
+    shareWith?: string[];
+    shareLevel?: PermissionLevel;
+    changeSummary?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * Per-upload options the backend reads to alter post-upload behavior —
+     * notably `rag.trigger_now` to run Knowledge immediately instead of waiting for
+     * the scheduled auto-Knowledge sweep. Serialized to the `options_json` form
+     * field alongside `metadata_json`.
+     */
+    options?: UploadOptions;
+    /** Strict dedup intent. Omitted preserves the legacy upload behavior. */
+    intent?: "create" | "alias_existing" | "force_new_copy";
+    /** Required by the backend when `intent` is `force_new_copy`. */
+    reason?: string;
+}
+/** Mirrors the backend `options_json` envelope. Extend as new opts land. */
+export interface UploadOptions {
+    rag?: {
+        /** Run Knowledge ingest immediately on upload (skip the scheduled sweep). */
+        trigger_now?: boolean;
+    };
+}
+export declare function uploadFile(params: UploadFileParams, opts?: RequestOptions): Promise<{
+    data: FileUploadResponse;
+    meta: ResponseMeta;
+}>;
+/**
+ * Write new bytes as the NEXT VERSION of an existing file — same id, version + 1 —
+ * `POST /files/{file_id}/versions`.
+ *
+ * Keyed by the file's ID, so it is the ONE save path for the owner AND for an editor
+ * holding an edit grant on someone else's file: the server authorizes the caller's
+ * `write` right on that file, stores the bytes under the file's own owner/path, records
+ * the caller as the version's author and keeps `changeSummary`. The request carries the
+ * FILE's own organization, never the picker's. Callers go through the `saveFileNewVersion`
+ * thunk (never `uploadFile` with a derived path — that is how a save became a second
+ * file, "name (1).txt", 2026-09-30).
+ *
+ * Raw multipart helper: the route is not in the pinned generated contract yet.
+ */
+export declare function uploadNewVersion(fileId: string, params: {
+    file: File;
+    changeSummary?: string;
+}, opts?: RequestOptions): Promise<{
+    data: FileUploadResponse;
+    meta: ResponseMeta;
+}>;
+export declare function uploadFileWithProgress(params: UploadFileParams, onProgress: (event: UploadProgressEvent) => void, opts?: RequestOptions): Promise<{
+    data: FileUploadResponse;
+    meta: ResponseMeta;
+}>;
+/**
+ * List files. Reading via supabase-js is preferred (RLS-filtered, no roundtrip
+ * through the backend). Exposed here for parity with the REST contract.
+ *
+ * Pagination is supported on the backend side (1–1000, default 100).
+ */
+export declare function listFiles(params?: {
+    folderPath?: string;
+    limit?: number;
+    offset?: number;
+}, opts?: RequestOptions): Promise<{
+    data: FileRecordApi[];
+    meta: ResponseMeta;
+}>;
+export declare function getFile(fileId: string, opts?: RequestOptions): Promise<{
+    data: FileRecordApi;
+    meta: ResponseMeta;
+}>;
+/**
+ * Read the canonical durable file row without asking the server to resolve
+ * render URLs or thumbnail variants.  Exact-id metadata hydration uses this
+ * backend authorization boundary instead of compiling the browser RLS policy
+ * once per file row.
+ */
+export declare function getFileMetadata(fileId: string, opts?: RequestOptions): Promise<{
+    data: FileRecordApi;
+    meta: ResponseMeta;
+}>;
+export declare function getFileByPath(filePath: string, opts?: RequestOptions): Promise<{
+    data: FileRecordApi;
+    meta: ResponseMeta;
+}>;
+/**
+ * Full tree via the RPC. Prefer calling the RPC directly via supabase-js in
+ * thunks (reducer dispatches don't need a round-trip through the backend).
+ * This is provided for backend-mediated contexts only.
+ */
+export declare function getFileTree(opts?: RequestOptions): Promise<{
+    data: unknown[];
+    meta: ResponseMeta;
+}>;
+/**
+ * Patch a file. Union body (A.2 — landed in matrx-utils v1.1.0): can rename,
+ * move (`folder`), change visibility, merge metadata, grant/revoke share,
+ * grant/revoke permissions, request variants, restore a version, restore
+ * from trash, or copy — in any combination, in a single round-trip.
+ *
+ * Sub-operations run sequentially with best-effort atomicity: the upload
+ * piece always lands, but downstream sub-ops can fail individually and
+ * surface in the response envelope's `errors[]` array (FE handles partial
+ * success — see useFileMutation in Phase 1).
+ *
+ * **Metadata is MERGED by default** — only the keys you send are touched
+ * on the server-side jsonb blob. For the rare "rewrite the whole metadata
+ * blob" tool, use `patchFileReplaceMetadata` below.
+ *
+ * `share_revoke` and `restore_from_trash` default to false; callers only
+ * need to set them when intentionally invoking that sub-op.
+ */
+export type FilePatchBody = Partial<FilePatchRequest>;
+export declare function patchFile(fileId: string, body: FilePatchBody, opts?: RequestOptions): Promise<{
+    data: FileRecordApi;
+    meta: ResponseMeta;
+}>;
+/**
+ * Same as `patchFile` but uses the legacy "replace whole metadata jsonb"
+ * semantics. Use ONLY for explicit overwrite-the-whole-blob tools — never
+ * for incremental edits where you'd lose every key the user didn't send.
+ */
+export declare function patchFileReplaceMetadata(fileId: string, body: FilePatchBody, opts?: RequestOptions): Promise<{
+    data: FileRecordApi;
+    meta: ResponseMeta;
+}>;
+/** Move a file to Trash (soft delete — restorable). There is no hard delete. */
+export declare function deleteFile(fileId: string, opts?: RequestOptions): Promise<{
+    data: components["schemas"]["DeleteResponse"];
+    meta: ResponseMeta;
+}>;
+export declare function downloadFile(fileId: string, params?: {
+    version?: number;
+    inline?: boolean;
+}, opts?: RequestOptions): Promise<{
+    blob: Blob;
+    filename: string | null;
+    meta: ResponseMeta;
+}>;
+/**
+ * Same as `downloadFile` but reports byte-level progress via `onProgress`.
+ * Use this when the UI needs a "Downloading 6.2 / 10 MB…" indicator —
+ * notably for `useFileBlob`, which feeds previewers that may pull
+ * multi-megabyte payloads.
+ */
+export declare function downloadFileWithProgress(fileId: string, onProgress: (event: DownloadProgressEvent) => void, params?: {
+    version?: number;
+    inline?: boolean;
+}, opts?: RequestOptions): Promise<{
+    blob: Blob;
+    filename: string | null;
+    meta: ResponseMeta;
+}>;
+/**
+ * Move many files to Trash (soft delete — restorable) in one
+ * call. Returns the standard `BulkResponse` envelope:
+ *
+ *   { results: [{ id, ok, error }], succeeded: N, failed: M }
+ *
+ * Per-request size capped at the user's tier `max_bulk_items` (free=200,
+ * pro=500). Concurrency is capped server-side at 10 in-flight.
+ */
+export declare function bulkDeleteFiles(body: BulkDeleteFilesRequest, opts?: RequestOptions): Promise<{
+    data: BulkResponse | null;
+    meta: ResponseMeta;
+}>;
+/**
+ * Move many files to a new parent folder in one call.
+ *
+ * The backend verifies every target file belongs to the same owner as the
+ * destination folder; cross-owner moves are refused with `403`. Returns
+ * the standard `BulkResponse` envelope.
+ */
+export declare function bulkMoveFiles(body: BulkMoveFilesRequest, opts?: RequestOptions): Promise<{
+    data: BulkResponse;
+    meta: ResponseMeta;
+}>;
+/**
+ * Read the authenticated user's account tier + current storage usage.
+ * Drives the storage indicator + tier badge + feature gating in the UI.
+ */
+export declare function getStorageUsage(opts?: RequestOptions): Promise<{
+    data: components["schemas"]["StorageUsageResponse"];
+    meta: ResponseMeta;
+}>;
+/**
+ * List soft-deleted files + folders for the authenticated user.
+ * Renders the trash view; pair with `restoreFile` to undo.
+ */
+export declare function listTrash(opts?: RequestOptions): Promise<{
+    data: components["schemas"]["TrashListResponse"];
+    meta: ResponseMeta;
+}>;
+/**
+ * Restore a soft-deleted file. Owner or admin grantee only — others
+ * get `403 permission_denied`.
+ */
+export declare function restoreFile(fileId: string, opts?: RequestOptions): Promise<{
+    data: FileRecordApi;
+    meta: ResponseMeta;
+}>;
+/**
+ * Filename / path substring search across the authenticated user's
+ * non-deleted files. `mimePrefix` filters by `mime_type LIKE 'prefix%'`
+ * (e.g. `image/`, `video/mp4`).
+ */
+export declare function searchFiles(params: SearchFilesParams, opts?: RequestOptions): Promise<{
+    data: SearchFilesResponse;
+    meta: ResponseMeta;
+}>;
+/**
+ * Rename / move a file by changing its full logical path. The backend
+ * auto-creates any missing parent folders. Replaces the FE's earlier
+ * "metadata hack" approach.
+ *
+ * The new path is the FULL path including the filename — e.g.
+ * `Reports/2026/Q1/forecast.pdf`. Just changing the leaf renames in
+ * place; changing intermediate segments moves into a different folder.
+ */
+export declare function renameFile(fileId: string, body: RenameFileRequest, opts?: RequestOptions): Promise<{
+    data: FileRecordApi;
+    meta: ResponseMeta;
+}>;
+/**
+ * Copy a file to a new logical path. Backend auto-creates parent folders.
+ * The copy counts against the caller's storage + file-count quota; refused
+ * uploads come back as 413 with the relevant quota code.
+ *
+ * `overwrite: true` replaces an existing file at `target_path`; the
+ * default (false) returns `409 file_already_exists` on conflict.
+ */
+export declare function copyFile(fileId: string, body: CopyFileRequest, opts?: RequestOptions): Promise<{
+    data: FileUploadResponse;
+    meta: ResponseMeta;
+}>;

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

@@ -0,0 +1,231 @@
+import {
+  delJson,
+  downloadBlob,
+  downloadBlobWithProgress,
+  getJson,
+  patchJson,
+  postJson,
+  postMultipart,
+  uploadWithProgress
+} from "../host/python-client.js";
+import {
+  apiDelete,
+  apiGet,
+  apiMultipart,
+  apiPost,
+  buildPath
+} from "../host/typed-client.js";
+import {
+  rememberFileOrganizationFrom,
+  withFileOrganization
+} from "./fileOrganization.js";
+function appendUploadIntent(form, params) {
+  if (params.intent) form.append("intent", params.intent);
+  if (params.reason) form.append("reason", params.reason);
+}
+async function uploadFile(params, opts = {}) {
+  const form = new FormData();
+  form.append("file", params.file);
+  form.append("file_path", params.filePath);
+  if (params.visibility) form.append("visibility", params.visibility);
+  if (params.shareWith?.length)
+    form.append("share_with", params.shareWith.join(","));
+  if (params.shareLevel) form.append("share_level", params.shareLevel);
+  if (params.changeSummary) form.append("change_summary", params.changeSummary);
+  if (params.metadata)
+    form.append("metadata_json", JSON.stringify(params.metadata));
+  if (params.options)
+    form.append("options_json", JSON.stringify(params.options));
+  appendUploadIntent(form, params);
+  return apiMultipart("/files/upload", form, opts);
+}
+async function uploadNewVersion(fileId, params, opts = {}) {
+  const form = new FormData();
+  form.append("file", params.file);
+  if (params.changeSummary) form.append("change_summary", params.changeSummary);
+  return postMultipart(
+    `/files/${encodeURIComponent(fileId)}/versions`,
+    form,
+    withFileOrganization(fileId, opts)
+  );
+}
+async function uploadFileWithProgress(params, onProgress, opts = {}) {
+  const form = new FormData();
+  form.append("file", params.file);
+  form.append("file_path", params.filePath);
+  if (params.visibility) form.append("visibility", params.visibility);
+  if (params.shareWith?.length)
+    form.append("share_with", params.shareWith.join(","));
+  if (params.shareLevel) form.append("share_level", params.shareLevel);
+  if (params.changeSummary) form.append("change_summary", params.changeSummary);
+  if (params.metadata)
+    form.append("metadata_json", JSON.stringify(params.metadata));
+  if (params.options)
+    form.append("options_json", JSON.stringify(params.options));
+  appendUploadIntent(form, params);
+  return uploadWithProgress(
+    "/files/upload",
+    form,
+    onProgress,
+    opts
+  );
+}
+async function listFiles(params = {}, opts = {}) {
+  return apiGet("/files", {
+    ...opts,
+    query: {
+      folder_path: params.folderPath,
+      limit: params.limit,
+      offset: params.offset
+    }
+  });
+}
+async function getFile(fileId, opts = {}) {
+  const answered = await apiGet(
+    buildPath("/files/{file_id}", { file_id: fileId }),
+    withFileOrganization(fileId, opts)
+  );
+  rememberFileOrganizationFrom(answered.data);
+  return answered;
+}
+async function getFileMetadata(fileId, opts = {}) {
+  const answered = await apiGet(buildPath("/files/{file_id}", { file_id: fileId }), {
+    ...withFileOrganization(fileId, opts),
+    query: { include_urls: false }
+  });
+  rememberFileOrganizationFrom(answered.data);
+  return answered;
+}
+async function getFileByPath(filePath, opts = {}) {
+  return apiGet(
+    buildPath("/files/by-path/{file_path}", { file_path: filePath }),
+    opts
+  );
+}
+async function getFileTree(opts = {}) {
+  return apiGet("/files/tree", opts);
+}
+async function patchFile(fileId, body, opts = {}) {
+  const fullBody = {
+    share_revoke: false,
+    restore_from_trash: false,
+    ...body
+  };
+  return patchJson(
+    `/files/${fileId}`,
+    fullBody,
+    withFileOrganization(fileId, opts)
+  );
+}
+async function patchFileReplaceMetadata(fileId, body, opts = {}) {
+  const fullBody = {
+    share_revoke: false,
+    restore_from_trash: false,
+    ...body
+  };
+  return patchJson(
+    `/files/${fileId}?metadata_merge=false`,
+    fullBody,
+    withFileOrganization(fileId, opts)
+  );
+}
+async function deleteFile(fileId, opts = {}) {
+  return apiDelete(
+    buildPath("/files/{file_id}", { file_id: fileId }),
+    withFileOrganization(fileId, opts)
+  );
+}
+async function downloadFile(fileId, params = {}, opts = {}) {
+  const qs = [];
+  if (params.version !== void 0) qs.push(`version=${params.version}`);
+  if (params.inline) qs.push("inline=true");
+  const q = qs.length ? `?${qs.join("&")}` : "";
+  return downloadBlob(
+    `/files/${fileId}/download${q}`,
+    withFileOrganization(fileId, opts)
+  );
+}
+async function downloadFileWithProgress(fileId, onProgress, params = {}, opts = {}) {
+  const qs = [];
+  if (params.version !== void 0) qs.push(`version=${params.version}`);
+  if (params.inline) qs.push("inline=true");
+  const q = qs.length ? `?${qs.join("&")}` : "";
+  return downloadBlobWithProgress(
+    `/files/${fileId}/download${q}`,
+    onProgress,
+    withFileOrganization(fileId, opts)
+  );
+}
+async function bulkDeleteFiles(body, opts = {}) {
+  return delJson(
+    "/files/bulk",
+    body,
+    opts
+  );
+}
+async function bulkMoveFiles(body, opts = {}) {
+  return postJson(
+    "/files/bulk/move",
+    body,
+    opts
+  );
+}
+async function getStorageUsage(opts = {}) {
+  return apiGet("/files/usage", opts);
+}
+async function listTrash(opts = {}) {
+  return apiGet("/files/trash", opts);
+}
+async function restoreFile(fileId, opts = {}) {
+  return postJson(
+    `/files/${fileId}/restore`,
+    {},
+    withFileOrganization(fileId, opts)
+  );
+}
+async function searchFiles(params, opts = {}) {
+  const qs = [`q=${encodeURIComponent(params.q)}`];
+  if (params.mimePrefix)
+    qs.push(`mime_prefix=${encodeURIComponent(params.mimePrefix)}`);
+  if (params.limit !== void 0) qs.push(`limit=${params.limit}`);
+  if (params.offset !== void 0) qs.push(`offset=${params.offset}`);
+  return getJson(`/files/search?${qs.join("&")}`, opts);
+}
+async function renameFile(fileId, body, opts = {}) {
+  return apiPost(
+    buildPath("/files/{file_id}/rename", { file_id: fileId }),
+    body,
+    withFileOrganization(fileId, opts)
+  );
+}
+async function copyFile(fileId, body, opts = {}) {
+  return apiPost(
+    buildPath("/files/{file_id}/copy", { file_id: fileId }),
+    body,
+    opts
+  );
+}
+export {
+  bulkDeleteFiles,
+  bulkMoveFiles,
+  copyFile,
+  deleteFile,
+  downloadFile,
+  downloadFileWithProgress,
+  getFile,
+  getFileByPath,
+  getFileMetadata,
+  getFileTree,
+  getStorageUsage,
+  listFiles,
+  listTrash,
+  patchFile,
+  patchFileReplaceMetadata,
+  renameFile,
+  restoreFile,
+  searchFiles,
+  uploadFile,
+  uploadFileWithProgress,
+  uploadNewVersion
+};
+//# sourceMappingURL=files.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/api/files.ts"],"sourcesContent":["/**\n * features/files/api/files.ts\n *\n * REST endpoints under /files/*. Wraps the typed client with endpoint-specific\n * args/returns so thunks don't hand-craft URLs or bodies.\n *\n * Backend contract: features/files/cld_files_frontend.md §6 (Files).\n */\n\nimport {\n  delJson,\n  downloadBlob,\n  downloadBlobWithProgress,\n  getJson,\n  patchJson,\n  postJson,\n  postMultipart,\n  uploadWithProgress,\n  type DownloadProgressEvent,\n  type RequestOptions,\n  type ResponseMeta,\n  type UploadProgressEvent,\n} from \"../host/python-client\";\nimport {\n  apiDelete,\n  apiGet,\n  apiMultipart,\n  apiPost,\n  buildPath,\n} from \"../host/typed-client\";\nimport type { components } from \"@ai-matrx/agents/generated/api-types\";\nimport {\n  rememberFileOrganizationFrom,\n  withFileOrganization,\n} from \"./fileOrganization\";\nimport type {\n  BulkDeleteFilesRequest,\n  BulkMoveFilesRequest,\n  BulkResponse,\n  CopyFileRequest,\n  FilePatchRequest,\n  FileRecordApi,\n  FileUploadResponse,\n  PermissionLevel,\n  RenameFileRequest,\n  SearchFilesParams,\n  SearchFilesResponse,\n  Visibility,\n} from \"../types\";\n\n// ---------------------------------------------------------------------------\n// Upload\n// ---------------------------------------------------------------------------\n\nexport interface UploadFileParams {\n  file: File;\n  filePath: string;\n  visibility?: Visibility;\n  shareWith?: string[];\n  shareLevel?: PermissionLevel;\n  changeSummary?: string;\n  metadata?: Record<string, unknown>;\n  /**\n   * Per-upload options the backend reads to alter post-upload behavior —\n   * notably `rag.trigger_now` to run Knowledge immediately instead of waiting for\n   * the scheduled auto-Knowledge sweep. Serialized to the `options_json` form\n   * field alongside `metadata_json`.\n   */\n  options?: UploadOptions;\n  /** Strict dedup intent. Omitted preserves the legacy upload behavior. */\n  intent?: \"create\" | \"alias_existing\" | \"force_new_copy\";\n  /** Required by the backend when `intent` is `force_new_copy`. */\n  reason?: string;\n}\n\nfunction appendUploadIntent(form: FormData, params: UploadFileParams): void {\n  if (params.intent) form.append(\"intent\", params.intent);\n  if (params.reason) form.append(\"reason\", params.reason);\n}\n\n/** Mirrors the backend `options_json` envelope. Extend as new opts land. */\nexport interface UploadOptions {\n  rag?: {\n    /** Run Knowledge ingest immediately on upload (skip the scheduled sweep). */\n    trigger_now?: boolean;\n  };\n}\n\nexport async function uploadFile(\n  params: UploadFileParams,\n  opts: RequestOptions = {},\n): Promise<{ data: FileUploadResponse; meta: ResponseMeta }> {\n  const form = new FormData();\n  form.append(\"file\", params.file);\n  form.append(\"file_path\", params.filePath);\n  if (params.visibility) form.append(\"visibility\", params.visibility);\n  if (params.shareWith?.length)\n    form.append(\"share_with\", params.shareWith.join(\",\"));\n  if (params.shareLevel) form.append(\"share_level\", params.shareLevel);\n  if (params.changeSummary) form.append(\"change_summary\", params.changeSummary);\n  if (params.metadata)\n    form.append(\"metadata_json\", JSON.stringify(params.metadata));\n  if (params.options)\n    form.append(\"options_json\", JSON.stringify(params.options));\n  appendUploadIntent(form, params);\n\n  // Non-progress multipart POST with a JSON response → typed client. Response\n  // (FileUploadResponse) is DERIVED from the contract, not asserted.\n  return apiMultipart(\"/files/upload\", form, opts);\n}\n\n/**\n * Write new bytes as the NEXT VERSION of an existing file — same id, version + 1 —\n * `POST /files/{file_id}/versions`.\n *\n * Keyed by the file's ID, so it is the ONE save path for the owner AND for an editor\n * holding an edit grant on someone else's file: the server authorizes the caller's\n * `write` right on that file, stores the bytes under the file's own owner/path, records\n * the caller as the version's author and keeps `changeSummary`. The request carries the\n * FILE's own organization, never the picker's. Callers go through the `saveFileNewVersion`\n * thunk (never `uploadFile` with a derived path — that is how a save became a second\n * file, \"name (1).txt\", 2026-09-30).\n *\n * Raw multipart helper: the route is not in the pinned generated contract yet.\n */\nexport async function uploadNewVersion(\n  fileId: string,\n  params: { file: File; changeSummary?: string },\n  opts: RequestOptions = {},\n): Promise<{ data: FileUploadResponse; meta: ResponseMeta }> {\n  const form = new FormData();\n  form.append(\"file\", params.file);\n  if (params.changeSummary) form.append(\"change_summary\", params.changeSummary);\n  return postMultipart<FileUploadResponse>(\n    `/files/${encodeURIComponent(fileId)}/versions`,\n    form,\n    withFileOrganization(fileId, opts),\n  );\n}\n\nexport async function uploadFileWithProgress(\n  params: UploadFileParams,\n  onProgress: (event: UploadProgressEvent) => void,\n  opts: RequestOptions = {},\n): Promise<{ data: FileUploadResponse; meta: ResponseMeta }> {\n  const form = new FormData();\n  form.append(\"file\", params.file);\n  form.append(\"file_path\", params.filePath);\n  if (params.visibility) form.append(\"visibility\", params.visibility);\n  if (params.shareWith?.length)\n    form.append(\"share_with\", params.shareWith.join(\",\"));\n  if (params.shareLevel) form.append(\"share_level\", params.shareLevel);\n  if (params.changeSummary) form.append(\"change_summary\", params.changeSummary);\n  if (params.metadata)\n    form.append(\"metadata_json\", JSON.stringify(params.metadata));\n  if (params.options)\n    form.append(\"options_json\", JSON.stringify(params.options));\n  appendUploadIntent(form, params);\n\n  // Raw client: XHR progress upload — the typed client is JSON-only and has\n  // no progress-capable multipart verb.\n  return uploadWithProgress<FileUploadResponse>(\n    \"/files/upload\",\n    form,\n    onProgress,\n    opts,\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Read\n// ---------------------------------------------------------------------------\n\n/**\n * List files. Reading via supabase-js is preferred (RLS-filtered, no roundtrip\n * through the backend). Exposed here for parity with the REST contract.\n *\n * Pagination is supported on the backend side (1–1000, default 100).\n */\nexport async function listFiles(\n  params: { folderPath?: string; limit?: number; offset?: number } = {},\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi[]; meta: ResponseMeta }> {\n  return apiGet(\"/files\", {\n    ...opts,\n    query: {\n      folder_path: params.folderPath,\n      limit: params.limit,\n      offset: params.offset,\n    },\n  });\n}\n\nexport async function getFile(\n  fileId: string,\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi; meta: ResponseMeta }> {\n  // The file's own organization, never the picker's (GATES-TAIL, VERIFIER-21 #2).\n  const answered = await apiGet(\n    buildPath(\"/files/{file_id}\", { file_id: fileId }),\n    withFileOrganization(fileId, opts),\n  );\n  rememberFileOrganizationFrom(answered.data);\n  return answered;\n}\n\n/**\n * Read the canonical durable file row without asking the server to resolve\n * render URLs or thumbnail variants.  Exact-id metadata hydration uses this\n * backend authorization boundary instead of compiling the browser RLS policy\n * once per file row.\n */\nexport async function getFileMetadata(\n  fileId: string,\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi; meta: ResponseMeta }> {\n  const answered = await apiGet(buildPath(\"/files/{file_id}\", { file_id: fileId }), {\n    ...withFileOrganization(fileId, opts),\n    query: { include_urls: false },\n  });\n  rememberFileOrganizationFrom(answered.data);\n  return answered;\n}\n\nexport async function getFileByPath(\n  filePath: string,\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi; meta: ResponseMeta }> {\n  return apiGet(\n    buildPath(\"/files/by-path/{file_path}\", { file_path: filePath }),\n    opts,\n  );\n}\n\n/**\n * Full tree via the RPC. Prefer calling the RPC directly via supabase-js in\n * thunks (reducer dispatches don't need a round-trip through the backend).\n * This is provided for backend-mediated contexts only.\n */\nexport async function getFileTree(\n  opts: RequestOptions = {},\n): Promise<{ data: unknown[]; meta: ResponseMeta }> {\n  return apiGet(\"/files/tree\", opts);\n}\n\n// ---------------------------------------------------------------------------\n// Mutate\n// ---------------------------------------------------------------------------\n\n/**\n * Patch a file. Union body (A.2 — landed in matrx-utils v1.1.0): can rename,\n * move (`folder`), change visibility, merge metadata, grant/revoke share,\n * grant/revoke permissions, request variants, restore a version, restore\n * from trash, or copy — in any combination, in a single round-trip.\n *\n * Sub-operations run sequentially with best-effort atomicity: the upload\n * piece always lands, but downstream sub-ops can fail individually and\n * surface in the response envelope's `errors[]` array (FE handles partial\n * success — see useFileMutation in Phase 1).\n *\n * **Metadata is MERGED by default** — only the keys you send are touched\n * on the server-side jsonb blob. For the rare \"rewrite the whole metadata\n * blob\" tool, use `patchFileReplaceMetadata` below.\n *\n * `share_revoke` and `restore_from_trash` default to false; callers only\n * need to set them when intentionally invoking that sub-op.\n */\nexport type FilePatchBody = Partial<FilePatchRequest>;\n\nexport async function patchFile(\n  fileId: string,\n  body: FilePatchBody,\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi; meta: ResponseMeta }> {\n  const fullBody: FilePatchRequest = {\n    share_revoke: false,\n    restore_from_trash: false,\n    ...body,\n  };\n  // Raw client: the contract types this 200 as `FileRecord | AssetCombinedOpResponse`\n  // (union-body sub-ops / X-Idempotency-Key path). Consumers here deref plain\n  // `FileRecord`, so routing through the typed client would surface the union\n  // and break them. Kept raw pending a consumer that handles both arms.\n  return patchJson<FileRecordApi, FilePatchRequest>(\n    `/files/${fileId}`,\n    fullBody,\n    withFileOrganization(fileId, opts),\n  );\n}\n\n/**\n * Same as `patchFile` but uses the legacy \"replace whole metadata jsonb\"\n * semantics. Use ONLY for explicit overwrite-the-whole-blob tools — never\n * for incremental edits where you'd lose every key the user didn't send.\n */\nexport async function patchFileReplaceMetadata(\n  fileId: string,\n  body: FilePatchBody,\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi; meta: ResponseMeta }> {\n  const fullBody: FilePatchRequest = {\n    share_revoke: false,\n    restore_from_trash: false,\n    ...body,\n  };\n  // Raw client: same union-response reason as `patchFile`.\n  return patchJson<FileRecordApi, FilePatchRequest>(\n    `/files/${fileId}?metadata_merge=false`,\n    fullBody,\n    withFileOrganization(fileId, opts),\n  );\n}\n\n/** Move a file to Trash (soft delete — restorable). There is no hard delete. */\nexport async function deleteFile(\n  fileId: string,\n  opts: RequestOptions = {},\n): Promise<{\n  data: components[\"schemas\"][\"DeleteResponse\"];\n  meta: ResponseMeta;\n}> {\n  return apiDelete(\n    buildPath(\"/files/{file_id}\", { file_id: fileId }),\n    withFileOrganization(fileId, opts),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Bytes\n// ---------------------------------------------------------------------------\n\n// Raw client: `downloadFile` / `downloadFileWithProgress` stream file BYTES\n// (Blob), not JSON — the typed client only wraps JSON verbs.\nexport async function downloadFile(\n  fileId: string,\n  params: { version?: number; inline?: boolean } = {},\n  opts: RequestOptions = {},\n): Promise<{ blob: Blob; filename: string | null; meta: ResponseMeta }> {\n  const qs: string[] = [];\n  if (params.version !== undefined) qs.push(`version=${params.version}`);\n  // `?inline=true` only honoured for image/video/audio/PDF — other types\n  // are served as `attachment` regardless. Useful for `<a href>` previews\n  // where we want the browser tab to render rather than auto-download.\n  if (params.inline) qs.push(\"inline=true\");\n  const q = qs.length ? `?${qs.join(\"&\")}` : \"\";\n  return downloadBlob(\n    `/files/${fileId}/download${q}`,\n    withFileOrganization(fileId, opts),\n  );\n}\n\n/**\n * Same as `downloadFile` but reports byte-level progress via `onProgress`.\n * Use this when the UI needs a \"Downloading 6.2 / 10 MB…\" indicator —\n * notably for `useFileBlob`, which feeds previewers that may pull\n * multi-megabyte payloads.\n */\nexport async function downloadFileWithProgress(\n  fileId: string,\n  onProgress: (event: DownloadProgressEvent) => void,\n  params: { version?: number; inline?: boolean } = {},\n  opts: RequestOptions = {},\n): Promise<{ blob: Blob; filename: string | null; meta: ResponseMeta }> {\n  const qs: string[] = [];\n  if (params.version !== undefined) qs.push(`version=${params.version}`);\n  if (params.inline) qs.push(\"inline=true\");\n  const q = qs.length ? `?${qs.join(\"&\")}` : \"\";\n  return downloadBlobWithProgress(\n    `/files/${fileId}/download${q}`,\n    onProgress,\n    withFileOrganization(fileId, opts),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Bulk operations\n// ---------------------------------------------------------------------------\n\n/**\n * Move many files to Trash (soft delete — restorable) in one\n * call. Returns the standard `BulkResponse` envelope:\n *\n *   { results: [{ id, ok, error }], succeeded: N, failed: M }\n *\n * Per-request size capped at the user's tier `max_bulk_items` (free=200,\n * pro=500). Concurrency is capped server-side at 10 in-flight.\n */\nexport async function bulkDeleteFiles(\n  body: BulkDeleteFilesRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: BulkResponse | null; meta: ResponseMeta }> {\n  // Raw client: DELETE-with-body. The typed client's `apiDelete` takes no\n  // request body, so a bulk delete can't route through it.\n  return delJson<BulkResponse, BulkDeleteFilesRequest>(\n    \"/files/bulk\",\n    body,\n    opts,\n  );\n}\n\n/**\n * Move many files to a new parent folder in one call.\n *\n * The backend verifies every target file belongs to the same owner as the\n * destination folder; cross-owner moves are refused with `403`. Returns\n * the standard `BulkResponse` envelope.\n */\nexport async function bulkMoveFiles(\n  body: BulkMoveFilesRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: BulkResponse; meta: ResponseMeta }> {\n  // Raw client: the contract's `BulkResultItem.error` is optional, but this\n  // wrapper + its thunk consumers treat `BulkResponse.results[].error` as\n  // required (`string | null`). Binding to the contract type would ripple that\n  // optionality into the thunk payload + `toastBulkPartialFailure` outside\n  // this file, so it's left raw pending a coordinated BulkResponse alignment.\n  return postJson<BulkResponse, BulkMoveFilesRequest>(\n    \"/files/bulk/move\",\n    body,\n    opts,\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Tier / quotas / usage\n// ---------------------------------------------------------------------------\n\n/**\n * Read the authenticated user's account tier + current storage usage.\n * Drives the storage indicator + tier badge + feature gating in the UI.\n */\nexport async function getStorageUsage(opts: RequestOptions = {}): Promise<{\n  data: components[\"schemas\"][\"StorageUsageResponse\"];\n  meta: ResponseMeta;\n}> {\n  return apiGet(\"/files/usage\", opts);\n}\n\n// ---------------------------------------------------------------------------\n// Trash + restore\n// ---------------------------------------------------------------------------\n\n/**\n * List soft-deleted files + folders for the authenticated user.\n * Renders the trash view; pair with `restoreFile` to undo.\n */\nexport async function listTrash(opts: RequestOptions = {}): Promise<{\n  data: components[\"schemas\"][\"TrashListResponse\"];\n  meta: ResponseMeta;\n}> {\n  return apiGet(\"/files/trash\", opts);\n}\n\n/**\n * Restore a soft-deleted file. Owner or admin grantee only — others\n * get `403 permission_denied`.\n */\nexport async function restoreFile(\n  fileId: string,\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi; meta: ResponseMeta }> {\n  // Raw client: this operation declares NO request body in the contract\n  // (`apiPost` would demand `body: never`), and its 200 is `DeleteResponse`,\n  // not `FileRecord` — see the drift note in the module report. Left raw so the\n  // existing FileRecordApi assertion + empty-body POST are preserved verbatim.\n  return postJson<FileRecordApi, Record<string, never>>(\n    `/files/${fileId}/restore`,\n    {},\n    withFileOrganization(fileId, opts),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Search\n// ---------------------------------------------------------------------------\n\n/**\n * Filename / path substring search across the authenticated user's\n * non-deleted files. `mimePrefix` filters by `mime_type LIKE 'prefix%'`\n * (e.g. `image/`, `video/mp4`).\n */\nexport async function searchFiles(\n  params: SearchFilesParams,\n  opts: RequestOptions = {},\n): Promise<{ data: SearchFilesResponse; meta: ResponseMeta }> {\n  // Raw client: this call sends `q=` unconditionally (empty string included),\n  // but the typed client's query serializer DROPS empty-string values — which\n  // would change the wire request for an empty query. Left raw to preserve the\n  // exact `?q=` behavior.\n  const qs: string[] = [`q=${encodeURIComponent(params.q)}`];\n  if (params.mimePrefix)\n    qs.push(`mime_prefix=${encodeURIComponent(params.mimePrefix)}`);\n  if (params.limit !== undefined) qs.push(`limit=${params.limit}`);\n  if (params.offset !== undefined) qs.push(`offset=${params.offset}`);\n  return getJson<SearchFilesResponse>(`/files/search?${qs.join(\"&\")}`, opts);\n}\n\n// ---------------------------------------------------------------------------\n// Rename + copy (path-changing operations)\n// ---------------------------------------------------------------------------\n\n/**\n * Rename / move a file by changing its full logical path. The backend\n * auto-creates any missing parent folders. Replaces the FE's earlier\n * \"metadata hack\" approach.\n *\n * The new path is the FULL path including the filename — e.g.\n * `Reports/2026/Q1/forecast.pdf`. Just changing the leaf renames in\n * place; changing intermediate segments moves into a different folder.\n */\nexport async function renameFile(\n  fileId: string,\n  body: RenameFileRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: FileRecordApi; meta: ResponseMeta }> {\n  return apiPost(\n    buildPath(\"/files/{file_id}/rename\", { file_id: fileId }),\n    body,\n    withFileOrganization(fileId, opts),\n  );\n}\n\n/**\n * Copy a file to a new logical path. Backend auto-creates parent folders.\n * The copy counts against the caller's storage + file-count quota; refused\n * uploads come back as 413 with the relevant quota code.\n *\n * `overwrite: true` replaces an existing file at `target_path`; the\n * default (false) returns `409 file_already_exists` on conflict.\n */\nexport async function copyFile(\n  fileId: string,\n  body: CopyFileRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: FileUploadResponse; meta: ResponseMeta }> {\n  // Contract-bound: the copy 200 is `FileUploadResponse` (NOT `FileRecord` —\n  // the pre-conversion assertion was wrong; see the module report). Deriving it\n  // through the typed client fixes that lie and locks the shape to the contract.\n  return apiPost(\n    buildPath(\"/files/{file_id}/copy\", { file_id: fileId }),\n    body,\n    opts,\n  );\n}\n"],"mappings":"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","names":[]}

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

@@ -0,0 +1,63 @@
+/**
+ * features/files/api/folders.ts
+ *
+ * Folder CRUD against the Python REST backend. Listing also goes through
+ * REST here for parity with the contract; supabase-js reads remain the
+ * preferred path for the live tree (`get_user_file_tree`).
+ *
+ * Backend contract: features/files/cloud_files_frontend.md §6 (Folders)
+ * plus the Python team's P-6 (folder CRUD) deliverables.
+ */
+import { type RequestOptions, type ResponseMeta } from "../host/python-client.js";
+import type { components } from "@ai-matrx/agents/generated/api-types";
+import type { BulkMoveFoldersRequest, BulkResponse, CloudFolderRow, CreateFolderRequest, FolderPatchRequest } from "../types.js";
+export declare function listFolders(params?: {
+    parentPath?: string;
+}, opts?: RequestOptions): Promise<{
+    data: CloudFolderRow[];
+    meta: ResponseMeta;
+}>;
+/**
+ * Create a folder. Prefer path-style (`folder_path: "Images/Chat"`) — the
+ * backend will create any missing intermediate folders atomically and
+ * idempotently, matching upload semantics.
+ */
+export declare function createFolder(body: CreateFolderRequest, opts?: RequestOptions): Promise<{
+    data: CloudFolderRow;
+    meta: ResponseMeta;
+}>;
+/**
+ * Ensure a complete logical folder path in one idempotent backend operation.
+ * The server creates missing intermediate segments atomically; callers must
+ * never reproduce that traversal with one PostgREST lookup per segment.
+ */
+export declare function ensureFolderPath(folderPath: string, visibility?: CreateFolderRequest["visibility"], opts?: RequestOptions): Promise<{
+    data: CloudFolderRow;
+    meta: ResponseMeta;
+}>;
+/**
+ * Update a folder — rename, move (via `parent_id`), or change visibility.
+ * The backend cascades `folder_path` updates to descendants on the server
+ * side; we don't replay that on the client.
+ */
+export declare function patchFolder(folderId: string, body: FolderPatchRequest, opts?: RequestOptions): Promise<{
+    data: CloudFolderRow;
+    meta: ResponseMeta;
+}>;
+/**
+ * Move a folder to Trash (soft delete — restorable). The backend cascades to
+ * all descendants. There is no hard delete.
+ */
+export declare function deleteFolder(folderId: string, opts?: RequestOptions): Promise<{
+    data: components["schemas"]["DeleteResponse"];
+    meta: ResponseMeta;
+}>;
+/**
+ * Move many folders to a new parent in one call. Returns a per-item
+ * succeeded/failed envelope so the caller can show per-row error chips
+ * without aborting the whole batch.
+ */
+export declare function bulkMoveFolders(body: BulkMoveFoldersRequest, opts?: RequestOptions): Promise<{
+    data: BulkResponse;
+    meta: ResponseMeta;
+}>;

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

@@ -0,0 +1,56 @@
+import {
+  getJson,
+  patchJson,
+  postJson
+} from "../host/python-client.js";
+import { apiDelete, buildPath } from "../host/typed-client.js";
+async function listFolders(params = {}, opts = {}) {
+  const q = params.parentPath ? `?parent_path=${encodeURIComponent(params.parentPath)}` : "";
+  return getJson(`/files/folders${q}`, opts);
+}
+async function createFolder(body, opts = {}) {
+  return postJson(
+    "/folders",
+    body,
+    opts
+  );
+}
+async function ensureFolderPath(folderPath, visibility = "personal", opts = {}) {
+  const normalizedPath = folderPath.split("/").map((segment) => segment.trim()).filter(Boolean).join("/");
+  if (!normalizedPath) {
+    throw new Error("folderPath cannot be empty.");
+  }
+  return createFolder(
+    { folder_path: normalizedPath, visibility, metadata: null },
+    opts
+  );
+}
+async function patchFolder(folderId, body, opts = {}) {
+  return patchJson(
+    `/folders/${folderId}`,
+    body,
+    opts
+  );
+}
+async function deleteFolder(folderId, opts = {}) {
+  return apiDelete(
+    buildPath("/folders/{folder_id}", { folder_id: folderId }),
+    opts
+  );
+}
+async function bulkMoveFolders(body, opts = {}) {
+  return postJson(
+    "/folders/bulk/move",
+    body,
+    opts
+  );
+}
+export {
+  bulkMoveFolders,
+  createFolder,
+  deleteFolder,
+  ensureFolderPath,
+  listFolders,
+  patchFolder
+};
+//# sourceMappingURL=folders.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/api/folders.ts"],"sourcesContent":["/**\n * features/files/api/folders.ts\n *\n * Folder CRUD against the Python REST backend. Listing also goes through\n * REST here for parity with the contract; supabase-js reads remain the\n * preferred path for the live tree (`get_user_file_tree`).\n *\n * Backend contract: features/files/cloud_files_frontend.md §6 (Folders)\n * plus the Python team's P-6 (folder CRUD) deliverables.\n */\n\nimport {\n  getJson,\n  patchJson,\n  postJson,\n  type RequestOptions,\n  type ResponseMeta,\n} from \"../host/python-client\";\nimport { apiDelete, buildPath } from \"../host/typed-client\";\nimport type { components } from \"@ai-matrx/agents/generated/api-types\";\nimport type {\n  BulkMoveFoldersRequest,\n  BulkResponse,\n  CloudFolderRow,\n  CreateFolderRequest,\n  FolderPatchRequest,\n} from \"../types\";\n\n// ---------------------------------------------------------------------------\n// Read\n// ---------------------------------------------------------------------------\n\n// Left on the raw client: the contract types this response as an untyped\n// `{ [key: string]: unknown }[]` (operation `list_folders_files_folders_get`),\n// while consumers deref concrete `CloudFolderRow` (DB-row) fields. Binding to\n// the contract would replace the row shape with `unknown` and break them.\nexport async function listFolders(\n  params: { parentPath?: string } = {},\n  opts: RequestOptions = {},\n): Promise<{ data: CloudFolderRow[]; meta: ResponseMeta }> {\n  const q = params.parentPath\n    ? `?parent_path=${encodeURIComponent(params.parentPath)}`\n    : \"\";\n  return getJson<CloudFolderRow[]>(`/files/folders${q}`, opts);\n}\n\n// ---------------------------------------------------------------------------\n// Create / update / delete (Python P-6)\n// ---------------------------------------------------------------------------\n\n/**\n * Create a folder. Prefer path-style (`folder_path: \"Images/Chat\"`) — the\n * backend will create any missing intermediate folders atomically and\n * idempotently, matching upload semantics.\n */\n// Left on the raw client: two contract disagreements make binding unsafe here.\n// (1) The contract's `CreateFolderRequest` schema has ONLY `folder_path` (required),\n//     `visibility`, `metadata` — it does NOT declare `folder_name` / `parent_id`,\n//     which this FE type sends. (2) The contract response is `FolderRecord`\n//     (owner_id / all-optional), not the DB-row `CloudFolderRow` (created_by /\n//     organization_id / is_system) that consumers read. See report — latent bug.\nexport async function createFolder(\n  body: CreateFolderRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: CloudFolderRow; meta: ResponseMeta }> {\n  return postJson<CloudFolderRow, CreateFolderRequest>(\n    \"/folders\",\n    body,\n    opts,\n  );\n}\n\n/**\n * Ensure a complete logical folder path in one idempotent backend operation.\n * The server creates missing intermediate segments atomically; callers must\n * never reproduce that traversal with one PostgREST lookup per segment.\n */\nexport async function ensureFolderPath(\n  folderPath: string,\n  visibility: CreateFolderRequest[\"visibility\"] = \"personal\",\n  opts: RequestOptions = {},\n): Promise<{ data: CloudFolderRow; meta: ResponseMeta }> {\n  const normalizedPath = folderPath\n    .split(\"/\")\n    .map((segment) => segment.trim())\n    .filter(Boolean)\n    .join(\"/\");\n  if (!normalizedPath) {\n    throw new Error(\"folderPath cannot be empty.\");\n  }\n\n  return createFolder(\n    { folder_path: normalizedPath, visibility, metadata: null },\n    opts,\n  );\n}\n\n/**\n * Update a folder — rename, move (via `parent_id`), or change visibility.\n * The backend cascades `folder_path` updates to descendants on the server\n * side; we don't replay that on the client.\n */\n// Left on the raw client: same disagreements as `createFolder`. The contract's\n// `PatchFolderRequest` has `folder_path` / `visibility` / `metadata`, while this\n// FE type sends `folder_name` / `parent_id`; and the contract response is\n// `FolderRecord`, not the DB-row `CloudFolderRow` consumers read.\nexport async function patchFolder(\n  folderId: string,\n  body: FolderPatchRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: CloudFolderRow; meta: ResponseMeta }> {\n  return patchJson<CloudFolderRow, FolderPatchRequest>(\n    `/folders/${folderId}`,\n    body,\n    opts,\n  );\n}\n\n/**\n * Move a folder to Trash (soft delete — restorable). The backend cascades to\n * all descendants. There is no hard delete.\n */\nexport async function deleteFolder(\n  folderId: string,\n  opts: RequestOptions = {},\n): Promise<{ data: components[\"schemas\"][\"DeleteResponse\"]; meta: ResponseMeta }> {\n  // Contract-bound: response derived from `delete_folder_folders__folder_id__delete`.\n  return apiDelete(\n    buildPath(\"/folders/{folder_id}\", { folder_id: folderId }),\n    opts,\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Bulk (Python P-7)\n// ---------------------------------------------------------------------------\n\n/**\n * Move many folders to a new parent in one call. Returns a per-item\n * succeeded/failed envelope so the caller can show per-row error chips\n * without aborting the whole batch.\n */\n// Left on the raw client: the request is contract-compatible, but the contract's\n// `BulkResponse.results[].error` is OPTIONAL while this FE `BulkResponse` (and its\n// thunk consumer) treats `error` as REQUIRED (`string | null`). Routing would force\n// the looser optional type onto the consumer and break it. See report — latent bug.\nexport async function bulkMoveFolders(\n  body: BulkMoveFoldersRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: BulkResponse; meta: ResponseMeta }> {\n  return postJson<BulkResponse, BulkMoveFoldersRequest>(\n    \"/folders/bulk/move\",\n    body,\n    opts,\n  );\n}\n"],"mappings":"AAWA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP,SAAS,WAAW,iBAAiB;AAkBrC,eAAsB,YACpB,SAAkC,CAAC,GACnC,OAAuB,CAAC,GACiC;AACzD,QAAM,IAAI,OAAO,aACb,gBAAgB,mBAAmB,OAAO,UAAU,CAAC,KACrD;AACJ,SAAO,QAA0B,iBAAiB,CAAC,IAAI,IAAI;AAC7D;AAiBA,eAAsB,aACpB,MACA,OAAuB,CAAC,GAC+B;AACvD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAOA,eAAsB,iBACpB,YACA,aAAgD,YAChD,OAAuB,CAAC,GAC+B;AACvD,QAAM,iBAAiB,WACpB,MAAM,GAAG,EACT,IAAI,CAAC,YAAY,QAAQ,KAAK,CAAC,EAC/B,OAAO,OAAO,EACd,KAAK,GAAG;AACX,MAAI,CAAC,gBAAgB;AACnB,UAAM,IAAI,MAAM,6BAA6B;AAAA,EAC/C;AAEA,SAAO;AAAA,IACL,EAAE,aAAa,gBAAgB,YAAY,UAAU,KAAK;AAAA,IAC1D;AAAA,EACF;AACF;AAWA,eAAsB,YACpB,UACA,MACA,OAAuB,CAAC,GAC+B;AACvD,SAAO;AAAA,IACL,YAAY,QAAQ;AAAA,IACpB;AAAA,IACA;AAAA,EACF;AACF;AAMA,eAAsB,aACpB,UACA,OAAuB,CAAC,GACwD;AAEhF,SAAO;AAAA,IACL,UAAU,wBAAwB,EAAE,WAAW,SAAS,CAAC;AAAA,IACzD;AAAA,EACF;AACF;AAeA,eAAsB,gBACpB,MACA,OAAuB,CAAC,GAC6B;AACrD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}