@fias/arche-sdk 2.19.1 → 2.20.0

package/dist/index.mjs

@@ -1008,7 +1008,10 @@ function useFiasStorage() {
     },
     [bridge]
   );
-  return { readFile, writeFile, listFiles, deleteFile };
+  return useMemo2(
+    () => ({ readFile, writeFile, listFiles, deleteFile }),
+    [readFile, writeFile, listFiles, deleteFile]
+  );
 }
 function useEntityInvocation() {
   const bridge = useBridge();
@@ -1243,21 +1246,30 @@ function useFiasNavigation() {
       bridge.request("open_arche", {
         archeId,
         newTab: opts?.newTab === true,
-        ...opts?.path ? { path: opts.path } : {}
+        ...opts?.path ? { path: opts.path } : {},
+        ...opts?.payload ? { payload: opts.payload } : {}
       });
     },
     [bridge]
   );
-  return { navigateTo, openArche, currentPath };
+  return useMemo2(
+    () => ({ navigateTo, openArche, currentPath }),
+    [navigateTo, openArche, currentPath]
+  );
 }
 function usePersistentState(key, initialValue) {
   const bridge = useBridge();
   const [value, setValueInternal] = useState2(initialValue);
   const initializedRef = useRef(false);
   const valueRef = useRef(initialValue);
+  const setByPluginRef = useRef(false);
   const writer = useMemo2(() => createDebouncedWriter(bridge), [bridge]);
   useEffect2(() => {
     invokeEntityOp(bridge, PLUGIN_STORAGE_ENTITY_ID, "read", { path: `__state/${key}` }).then((result) => {
+      if (setByPluginRef.current) {
+        initializedRef.current = true;
+        return;
+      }
       if (result.exists && result.content !== null) {
         try {
           const parsed = JSON.parse(result.content);
@@ -1277,6 +1289,7 @@ function usePersistentState(key, initialValue) {
   const setValue = useCallback(
     (next) => {
       const resolved = typeof next === "function" ? next(valueRef.current) : next;
+      setByPluginRef.current = true;
       valueRef.current = resolved;
       setValueInternal(resolved);
       writer.schedule(`__state/${key}`, JSON.stringify(resolved));
@@ -1740,9 +1753,10 @@ function useVaultDocuments() {
   );
   const read = useCallback(
     async (documentId) => {
-      return bridge.request("vault_documents_read", {
-        documentId
-      });
+      return bridge.request(
+        "vault_documents_read",
+        { documentId }
+      );
     },
     [bridge]
   );
@@ -1767,16 +1781,29 @@ function useVaultDocuments() {
   );
   const saveContent = useCallback(
     async (params) => {
-      const res = await invokeEntityOp(
-        bridge,
-        VAULT_ARCHE_DOCUMENTS_ENTITY_ID,
-        "save_own_document_content",
-        {
-          documentId: params.documentId,
-          content: params.content,
-          contentType: params.contentType
-        }
-      );
+      const routed = await routeSaveContent(params.content);
+      let res;
+      if (routed.lane === "body") {
+        res = await invokeEntityOp(
+          bridge,
+          VAULT_ARCHE_DOCUMENTS_ENTITY_ID,
+          "save_own_document_content",
+          {
+            documentId: params.documentId,
+            content: routed.text,
+            contentType: params.contentType,
+            expectedRevision: params.expectedRevision
+          }
+        );
+      } else {
+        res = await bridge.request("vault_documents_upload", {
+          saveToDocumentId: params.documentId,
+          bytes: bytesToBase64(routed.bytes),
+          mimeType: params.contentType,
+          contentKind: routed.contentKind,
+          expectedRevision: params.expectedRevision
+        });
+      }
       downloadUrlCache.delete(params.documentId);
       return res;
     },
@@ -1784,6 +1811,12 @@ function useVaultDocuments() {
   );
   const write = useCallback(
     async (params) => {
+      if (params.content.length > SAVE_CONTENT_BODY_LANE_MAX_BYTES || !fitsBridgeBodyAsJsonText(params.content)) {
+        throw new FiasBridgeError(
+          "write() takes small text only: at most 200,000 characters, and small enough to travel in one bridge request once JSON-escaped (quotes, backslashes and newlines double). Use upload() for larger documents.",
+          "INVALID_PARAMS"
+        );
+      }
       return bridge.request("vault_documents_write", {
         name: params.name,
         content: params.content,
@@ -1877,15 +1910,25 @@ function useVaultDocuments() {
         sensitivity: params.sensitivity,
         folderPath: params.folderPath,
         replacesDocumentId: params.replacesDocumentId,
-        // Opt-in user-visible save. The host turns this into a confirmation
-        // the user sees and the iframe cannot script; the server independently
-        // requires `vault:user-documents:write` plus a registered folder for
-        // this arche. Omitted (the common case) keeps the arche-private default.
+        // A save into the user's Documents. The host turns this into its Save
+        // dialog, which the iframe cannot see or script, and performs the
+        // write itself from the user's session. Omitted (the common case)
+        // keeps the arche-private default.
+        destination: params.destination,
         userVisible: params.userVisible
       });
     },
     [bridge]
   );
+  const saveCopy = useCallback(
+    async (documentId, options) => {
+      return bridge.request("vault_documents_update", {
+        documentId,
+        saveCopy: { ...options?.suggestedName ? { suggestedName: options.suggestedName } : {} }
+      });
+    },
+    [bridge]
+  );
   return useMemo2(
     () => ({
       list,
@@ -1900,6 +1943,7 @@ function useVaultDocuments() {
       attach,
       detach,
       upload,
+      saveCopy,
       uploadInit,
       uploadFinalize
     }),
@@ -1916,11 +1960,45 @@ function useVaultDocuments() {
       attach,
       detach,
       upload,
+      saveCopy,
       uploadInit,
       uploadFinalize
     ]
   );
 }
+var SAVE_CONTENT_BODY_LANE_MAX_BYTES = 2e5;
+var BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES = 256 * 1024 - 16 * 1024;
+function fitsBridgeBodyAsJsonText(text, utf8Bytes) {
+  if (text.length * 6 <= BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES) return true;
+  const escapeOverhead = JSON.stringify(text).length - text.length;
+  const bytes = utf8Bytes ?? new TextEncoder().encode(text).length;
+  return bytes + escapeOverhead <= BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES;
+}
+var SAVE_CONTENT_MAX_BYTES = 15 * 1024 * 1024;
+async function routeSaveContent(content) {
+  let routed;
+  if (typeof content === "string") {
+    if (content.length * 6 <= SAVE_CONTENT_BODY_LANE_MAX_BYTES) {
+      return { lane: "body", text: content };
+    }
+    const bytes = new TextEncoder().encode(content);
+    routed = bytes.length <= SAVE_CONTENT_BODY_LANE_MAX_BYTES && fitsBridgeBodyAsJsonText(content, bytes.length) ? { lane: "body", text: content } : { lane: "host", bytes, contentKind: "text" };
+  } else {
+    routed = { lane: "host", bytes: await toUint8Array(content), contentKind: "binary" };
+  }
+  if (routed.lane === "host" && routed.bytes.length > SAVE_CONTENT_MAX_BYTES) {
+    throw new FiasBridgeError(
+      `Content is ${routed.bytes.length} bytes; saveContent accepts at most ${SAVE_CONTENT_MAX_BYTES} bytes (15 MB).`,
+      "OWN_DOCUMENT_SAVE_TOO_LARGE"
+    );
+  }
+  return routed;
+}
+async function toUint8Array(content) {
+  if (content instanceof Uint8Array) return content;
+  if (content instanceof ArrayBuffer) return new Uint8Array(content);
+  return new Uint8Array(await content.arrayBuffer());
+}
 function base64ToBytes(base64) {
   const binary = atob(base64);
   const bytes = new Uint8Array(binary.length);
@@ -1964,6 +2042,123 @@ function useArcheAssets() {
   );
   return useMemo2(() => ({ list, index, getUrl }), [list, index, getUrl]);
 }
+var PLUGIN_CONTENT_ENTITY_ID = "ent_intg_plugin_content_00000000";
+var FiasContentError = class extends Error {
+  constructor(message, code, path) {
+    super(message);
+    this.code = code;
+    this.path = path;
+    this.name = "FiasContentError";
+  }
+};
+function toContentError(err) {
+  if (err instanceof FiasContentError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  const code = err?.code;
+  if (/permission denied/i.test(message)) return new FiasContentError(message, "PERMISSION_DENIED");
+  if (code === "RATE_LIMITED" || /rate limit/i.test(message)) {
+    return new FiasContentError(message, "RATE_LIMIT");
+  }
+  return new FiasContentError(message, "CONTENT_UNAVAILABLE");
+}
+function fileResult(results, path) {
+  const result = results?.[path];
+  if (!result) {
+    throw new FiasContentError(`No result for content/${path}`, "CONTENT_UNAVAILABLE", path);
+  }
+  if ("error" in result) throw new FiasContentError(result.error.message, result.error.code, path);
+  return result;
+}
+var contentObjectUrls = /* @__PURE__ */ new Map();
+function useFiasContent() {
+  const bridge = useBridge();
+  const call = useCallback(
+    async (input) => {
+      let response;
+      try {
+        response = await bridge.request(
+          "client_entity_invoke",
+          { entityId: PLUGIN_CONTENT_ENTITY_ID, input },
+          CLIENT_ENTITY_INVOKE_TIMEOUT_MS
+        );
+      } catch (err) {
+        throw toContentError(err);
+      }
+      if (response?.error) {
+        throw new FiasContentError(response.error.message, response.error.code);
+      }
+      return response ?? {};
+    },
+    [bridge]
+  );
+  const list = useCallback(
+    async (prefix) => (await call({ verb: "list", ...prefix !== void 0 ? { prefix } : {} })).files ?? [],
+    [call]
+  );
+  const getText = useCallback(
+    async (path) => {
+      const { results } = await call({ verb: "read", paths: [path], as: "text" });
+      return fileResult(results, path).text;
+    },
+    [call]
+  );
+  const getJson = useCallback(
+    async (path) => JSON.parse(await getText(path)),
+    [getText]
+  );
+  const readBytes = useCallback(
+    async (path) => {
+      const { results } = await call({ verb: "read", paths: [path], as: "bytes" });
+      return fileResult(results, path);
+    },
+    [call]
+  );
+  const getBytes = useCallback(
+    async (path) => (await readBytes(path)).bytes,
+    [readBytes]
+  );
+  const getMany = useCallback(
+    async (paths, as) => {
+      const { results } = await call({ verb: "read", paths, as });
+      const out = {};
+      for (const path of paths) {
+        try {
+          const result = fileResult(results, path);
+          out[path] = as === "text" ? result.text : result.bytes;
+        } catch (err) {
+          out[path] = toContentError(err);
+        }
+      }
+      return out;
+    },
+    [call]
+  );
+  const getObjectUrl = useCallback(
+    async (path) => {
+      const cached = contentObjectUrls.get(path);
+      if (cached) return cached;
+      const pending = readBytes(path).then(
+        ({ bytes, mimeType }) => URL.createObjectURL(new Blob([bytes], { type: mimeType }))
+      );
+      contentObjectUrls.set(path, pending);
+      pending.catch(() => contentObjectUrls.delete(path));
+      return pending;
+    },
+    [readBytes]
+  );
+  const getUrl = useCallback(
+    async (path) => {
+      const { results } = await call({ verb: "url", paths: [path] });
+      const { url, expiresAt } = fileResult(results, path);
+      return { url, expiresAt };
+    },
+    [call]
+  );
+  return useMemo2(
+    () => ({ list, getText, getJson, getBytes, getMany, getObjectUrl, getUrl }),
+    [list, getText, getJson, getBytes, getMany, getObjectUrl, getUrl]
+  );
+}
 function useFiasPreviewState(key, getState, onRestore) {
   const bridge = useBridge();
   const getStateRef = useRef(getState);
@@ -2053,7 +2248,44 @@ function useVaultUserDocuments() {
   const pick = useCallback(
     async (options) => {
       return bridge.request("vault_documents_pick", {
-        maxDocuments: options?.maxDocuments
+        maxDocuments: options?.maxDocuments,
+        access: options?.access,
+        ...options?.accept ? { accept: [...options.accept] } : {}
+      });
+    },
+    [bridge]
+  );
+  const requestEditAccess = useCallback(
+    async (documentId) => {
+      return bridge.request("vault_documents_pick", {
+        maxDocuments: 1,
+        access: "write",
+        documentId
+      });
+    },
+    [bridge]
+  );
+  const saveContent = useCallback(
+    async (params) => {
+      const routed = await routeSaveContent(params.content);
+      if (routed.lane === "body") {
+        return invokeEntityOp(
+          bridge,
+          VAULT_USER_DOCUMENTS_ENTITY_ID,
+          "save_consented_document_content",
+          {
+            documentId: params.documentId,
+            content: routed.text,
+            expectedRevision: params.expectedRevision
+          }
+        );
+      }
+      return bridge.request("vault_documents_upload", {
+        saveToDocumentId: params.documentId,
+        saveTarget: "user",
+        bytes: bytesToBase64(routed.bytes),
+        contentKind: routed.contentKind,
+        expectedRevision: params.expectedRevision
       });
     },
     [bridge]
@@ -2104,8 +2336,8 @@ function useVaultUserDocuments() {
     [bridge]
   );
   return useMemo2(
-    () => ({ pick, list, get, getDownloadUrl, getBytes }),
-    [pick, list, get, getDownloadUrl, getBytes]
+    () => ({ pick, requestEditAccess, saveContent, list, get, getDownloadUrl, getBytes }),
+    [pick, requestEditAccess, saveContent, list, get, getDownloadUrl, getBytes]
   );
 }
 var COMMUNITY_ASSET_URL_REFRESH_BUFFER_MS = 3e4;
@@ -2421,8 +2653,10 @@ var VALID_PLUGIN_PERMISSIONS = [
   "store:purchase",
   "theme:read",
   "user:profile:read",
+  "vault:arche-saves:write",
   "vault:documents:read",
   "vault:documents:write",
+  "vault:user-documents:edit",
   "vault:user-documents:read",
   "vault:user-documents:write"
 ];
@@ -2430,12 +2664,12 @@ function isValidPluginPermission(perm) {
   return VALID_PLUGIN_PERMISSIONS.includes(perm);
 }
 var PLUGIN_PERMISSION_DESCRIPTIONS = {
-  "ai:actions": "Let Fias AI operate this app for you \u2014 only actions you could do yourself in its interface, and risky ones ask you first.",
-  "assets:community:publish": "Share images you made here so other people using this app can see them, and manage what you have shared.",
-  "assets:community:read": "Show you images that other people using this app have shared. Everything shared is checked before anyone can see it.",
-  "assets:read": "Show images from this app's published asset library.",
-  "data:search": "Search this app's own data semantically \u2014 costs credits per search.",
-  "data:store": "Save structured data in this app's own private database.",
+  "ai:actions": "Let Fias AI operate this arche for you \u2014 only actions you could do yourself in its interface, and risky ones ask you first.",
+  "assets:community:publish": "Share images you made here so other people using this arche can see them, and manage what you have shared.",
+  "assets:community:read": "Show you images that other people using this arche have shared. Everything shared is checked before anyone can see it.",
+  "assets:read": "Show images from this arche's published asset library.",
+  "data:search": "Search this arche's own data semantically \u2014 costs credits per search.",
+  "data:store": "Save structured data in this arche's own private database.",
   "data:workspace": "Create team workspaces and manage their members.",
   "entities:audio_generate": "Generate audio with platform AI \u2014 costs credits.",
   "entities:client_invoke": "Use free on-device tools (grammar check, translation) in your browser.",
@@ -2445,14 +2679,16 @@ var PLUGIN_PERMISSION_DESCRIPTIONS = {
   "entities:web_search": "Search the live web on your behalf \u2014 costs credits.",
   "navigation:open_arche": "Open other arches for you (navigation only).",
   "sandbox:vendored-libraries": "Load platform-hosted libraries (like the PDF renderer) from the trusted CDN.",
-  "storage:sandbox": "Save files in this app's own private storage.",
-  "store:purchase": "Offer in-app purchases (you approve each purchase).",
+  "storage:sandbox": "Save files in this arche's own private storage.",
+  "store:purchase": "Offer purchases inside the arche (you approve each purchase).",
   "theme:read": "Match your platform theme.",
   "user:profile:read": "See your display name and avatar.",
-  "vault:documents:read": "Read documents this app itself created in your Vault.",
-  "vault:documents:write": "Create and manage its own documents in your Vault.",
-  "vault:user-documents:read": "Read documents YOU choose to share with it from your Vault \u2014 you pick each document, and you can remove access any time in Vault \u2192 App Access.",
-  "vault:user-documents:write": "Save its work to your Fias files, where you can find and reuse it. You confirm each save."
+  "vault:arche-saves:write": "Saves files to your Arche Saves automatically.",
+  "vault:documents:read": "Read files this arche itself created, in its own folders of your Vault.",
+  "vault:documents:write": "Create and manage its own files, in its own folder of your Vault.",
+  "vault:user-documents:edit": "Save changes to files of yours that you let it edit \u2014 you choose each file, earlier versions are kept unless you turned version history off, and you can remove access any time in Vault \u2192 Arche Access.",
+  "vault:user-documents:read": "Read documents YOU choose to share with it from your Vault \u2014 you pick each document, and you can remove access any time in Vault \u2192 Arche Access.",
+  "vault:user-documents:write": "Save its work to your Documents \u2014 you choose the folder and the name each time."
 };
 
 // src/fias.ts
@@ -4939,6 +5175,7 @@ export {
   FONT_PAIRINGS,
   FiasBridge,
   FiasBridgeError,
+  FiasContentError,
   FiasProvider,
   GRAMMAR_CHECK_ENTITY_ID,
   IMAGE_SMART_CONTROL_SURFACE_KEY,
@@ -4971,6 +5208,7 @@ export {
   PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS,
   PANEL_THEME_Z_MAX,
   PANEL_TITLE_MAX_LENGTH,
+  PLUGIN_CONTENT_ENTITY_ID,
   PLUGIN_PERMISSION_DESCRIPTIONS,
   SDK_BRIDGE_PROTOCOL_VERSION,
   SDK_REQUIRES_HOST_PROTOCOL_VERSION,
@@ -5001,6 +5239,7 @@ export {
   useElevenLabsVoiceDesign,
   useEntityInvocation,
   useFiasAIActions,
+  useFiasContent,
   useFiasDataStore,
   useFiasFonts,
   useFiasNavigation,