@fias/arche-sdk 2.19.1 → 2.19.2

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,
@@ -1807,6 +1840,17 @@ function useVaultDocuments() {
     },
     [bridge]
   );
+  const promoteToUserFiles = useCallback(
+    async (documentId) => {
+      const res = await bridge.request("vault_documents_update", {
+        documentId,
+        userVisible: true
+      });
+      downloadUrlCache.delete(documentId);
+      return res;
+    },
+    [bridge]
+  );
   const deleteDocument = useCallback(
     async (documentId) => {
       await bridge.request("vault_documents_delete", { documentId });
@@ -1895,6 +1939,7 @@ function useVaultDocuments() {
       getDownloadUrl,
       write,
       update,
+      promoteToUserFiles,
       delete: deleteDocument,
       search,
       attach,
@@ -1911,6 +1956,7 @@ function useVaultDocuments() {
       getDownloadUrl,
       write,
       update,
+      promoteToUserFiles,
       deleteDocument,
       search,
       attach,
@@ -1921,6 +1967,39 @@ function useVaultDocuments() {
     ]
   );
 }
+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);
@@ -2053,7 +2132,43 @@ function useVaultUserDocuments() {
   const pick = useCallback(
     async (options) => {
       return bridge.request("vault_documents_pick", {
-        maxDocuments: options?.maxDocuments
+        maxDocuments: options?.maxDocuments,
+        access: options?.access
+      });
+    },
+    [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 +2219,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;
@@ -2423,6 +2538,7 @@ var VALID_PLUGIN_PERMISSIONS = [
   "user:profile:read",
   "vault:documents:read",
   "vault:documents:write",
+  "vault:user-documents:edit",
   "vault:user-documents:read",
   "vault:user-documents:write"
 ];
@@ -2451,6 +2567,7 @@ var PLUGIN_PERMISSION_DESCRIPTIONS = {
   "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:edit": "Save changes to files of yours that you let it edit \u2014 you choose each file, earlier versions are kept, and you can remove access any time in Vault \u2192 App 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 App Access.",
   "vault:user-documents:write": "Save its work to your Fias files, where you can find and reuse it. You confirm each save."
 };

package/dist/types.d.ts

@@ -149,7 +149,25 @@ export interface EntityInvocationParams {
      * applies). Bounded per call — keep images small (downscale before sending).
      */
     images?: EntityInvocationImage[];
-    parameters?: Record<string, unknown>;
+    /**
+     * Sampling knobs for the resolved model. Out-of-range values are clamped
+     * rather than rejected.
+     *
+     * - `temperature` — 0–2. **A no-op on models that do not accept sampling
+     *   parameters**, which includes the whole Claude 5 family (Sonnet 5,
+     *   Opus 5, Fable 5) and Opus 4.7/4.8: Anthropic removed the parameter
+     *   there, so the platform drops it rather than letting the provider 400.
+     *   Only the fast tier (Haiku) and the Google models honour it.
+     * - `maxTokens` — may only LOWER the resolved model's output ceiling, never
+     *   raise it. Worth setting when you know the reply is short: it shrinks the
+     *   credit hold taken up front.
+     *
+     * Unknown keys are ignored.
+     */
+    parameters?: {
+        temperature?: number;
+        maxTokens?: number;
+    };
     /** System prompt to send to the AI model. The arche/plugin provides context; the entity provides the capability. */
     systemPrompt?: string;
     /**
@@ -638,13 +656,58 @@ export interface FiasNavigationApi {
      * @param opts.newTab Best-effort open in a new tab (keeps the current arche
      *   open). Browsers may block the popup since user activation does not cross
      *   the iframe→host boundary; the host falls back to same-tab navigation.
+     *   Ignored when `opts.payload` is present — navigation state cannot cross
+     *   into a new tab, so the handoff would arrive empty.
+     * @param opts.payload A typed handoff payload to hand the target arche —
+     *   e.g. `{ kind: 'sign_document', requestId, documentId, recipients }` to
+     *   open Document Sign on a draft seeded from one of the user's Vault
+     *   documents. The host validates it against the target's intake and
+     *   REJECTS a payload that arche would not accept, so a mistargeted handoff
+     *   is an error you can see rather than a silent no-op.
+     *
+     *   A handoff only ever PRE-FILLS a UI — it never causes an effect. The
+     *   user reviews, edits, and acts themself.
+     *
+     *   Mint a fresh `requestId` (uuid) per user intent, not per call: the host
+     *   keys idempotency on it, so re-presenting one resolves to the SAME draft
+     *   instead of creating a duplicate. Reusing a stale one reopens the old
+     *   draft.
      */
     openArche: (archeId: string, opts?: {
         newTab?: boolean;
         path?: string;
+        payload?: ArcheHandoffPayloadInput;
     }) => void;
     currentPath: string;
 }
+/**
+ * Handoff payloads a plugin may hand to another arche via `openArche`.
+ *
+ * Structural rather than a re-export of the platform's Zod-inferred union:
+ * the SDK ships to plugin authors and cannot depend on workspace packages.
+ * The host re-validates against the canonical contract, so a shape that is
+ * wrong here is refused there with a message naming the problem.
+ */
+export type ArcheHandoffPayloadInput = {
+    kind: 'open_document';
+    documentId: string;
+} | {
+    kind: 'sign_document';
+    /** Idempotency key for this signing request. One uuid per user intent. */
+    requestId: string;
+    /** A Vault document the user can open — PDFs only. */
+    documentId: string;
+    title?: string;
+    message?: string;
+    signingOrder?: 'parallel' | 'sequential';
+    recipients?: Array<{
+        email: string;
+        name?: string;
+        role?: 'signer' | 'viewer' | 'approver';
+    }>;
+    /** Opaque metadata echoed back on the result. Never interpreted. */
+    correlationId?: string;
+};
 /**
  * A document owned by the calling arche in the user's Vault.
  *
@@ -671,6 +734,14 @@ export interface VaultDocumentSummary {
      * scoped by `source_arche_id`, not folder).
      */
     folderId: string | null;
+    /**
+     * Opaque token naming the document's current CONTENT — pass it as
+     * `saveContent({ expectedRevision })` so a save is refused
+     * (`VERSION_CONFLICT`) if the content changed since you read it. Never
+     * parse it. Optional: absent on hosts that predate in-place-save
+     * preconditions.
+     */
+    revision?: string;
 }
 export interface VaultDocumentsListOptions {
     search?: string;
@@ -731,12 +802,26 @@ export interface VaultDocumentUpdateParams {
 }
 /** Input to `useVaultDocuments().saveContent`. */
 export interface VaultDocumentSaveContentParams {
-    /** The document to overwrite — one THIS arche created with `write`. */
+    /** The document to overwrite — one THIS arche created with `write` / `upload`. */
     documentId: string;
-    /** New UTF-8 text content (≤ 200 KB encoded). */
-    content: string;
+    /**
+     * The new content, up to 15 MB. A `string` is saved as UTF-8 text (the
+     * document must be — or become, via `contentType` — a text type); bytes
+     * (`Uint8Array` / `ArrayBuffer` / `Blob`) are saved as-is, for any type.
+     * Transport is chosen for you: small text rides the bridge message, and
+     * everything else is uploaded by the host — there is one method either way.
+     */
+    content: string | Uint8Array | ArrayBuffer | Blob;
     /** New MIME type; omitted keeps the document's current one. */
     contentType?: string;
+    /**
+     * The `revision` you last saw for this document (from `list`, `readBytes`,
+     * or a previous `saveContent` result). When supplied, the save is refused
+     * with `VERSION_CONFLICT` if the document has changed since — so a second
+     * tab, or another device, cannot be silently overwritten. Omit for
+     * last-write-wins.
+     */
+    expectedRevision?: string;
 }
 /** Result of `useVaultDocuments().saveContent`. */
 export interface VaultDocumentSaveContentResult {
@@ -745,6 +830,35 @@ export interface VaultDocumentSaveContentResult {
     sizeBytes: number;
     /** ISO timestamp of the save. */
     updatedAt: string;
+    /**
+     * Opaque token naming the content just saved — pass it as
+     * `expectedRevision` on the next save. Optional, like every other
+     * `revision` on this hook: a platform that predates revisions saves the
+     * text lane without returning one (the next save is then last-write-wins).
+     */
+    revision?: string;
+}
+/**
+ * Result of `useVaultUserDocuments().saveContent`. Here `revision` is ALWAYS
+ * present — a platform that can save to the user's files at all returns it —
+ * which matters because that save REQUIRES the next `expectedRevision`.
+ */
+export interface VaultUserDocumentSaveContentResult extends VaultDocumentSaveContentResult {
+    revision: string;
+}
+/** Result of `useVaultDocuments().promoteToUserFiles`. */
+export interface VaultDocumentPromoteResult {
+    documentId: string;
+    visibility: 'user-vault';
+    /**
+     * Whether the user let your app KEEP EDITING the file (a checkbox on the
+     * host's confirmation, offered only when your manifest declares
+     * `vault:user-documents:edit`). `true`: keep saving it with
+     * `useVaultUserDocuments().saveContent`. `false` or absent: it is read-only
+     * to you now — open it read-only and ask with `requestEditAccess` if the
+     * user starts editing.
+     */
+    editAccess?: boolean;
 }
 export interface VaultDocumentSearchOptions {
     /** Number of results to return. 1..50, default 10. */
@@ -788,9 +902,39 @@ export interface OpenDocumentHandoff {
     kind: 'open_document';
     documentId: string;
 }
-/** Every handoff payload a plugin can receive. One kind today; the union is
- *  the extension point, so switch on `kind` rather than assuming. */
-export type ArcheHandoffPayload = OpenDocumentHandoff;
+/**
+ * The REPLY to a `sign_document` handoff your app sent — delivered when the
+ * user leaves Document Sign and comes back to you.
+ *
+ * Contract, and it matters:
+ *
+ *  - It is a POINTER, not a record. It tells you which envelope to look at;
+ *    it is not evidence of what happened to it. Anything you would act on —
+ *    who signed, what is outstanding — comes from reading the envelope, never
+ *    from this payload.
+ *  - `outcome` is the fact, not `envelopeId`. An envelope id exists from the
+ *    moment a DRAFT is created, so its presence proves a draft exists and
+ *    nothing more. A cancellation structurally carries none.
+ *  - Match it to an OUTSTANDING request by `requestId` and consume it once.
+ *    Never re-point an existing association because a `correlationId`
+ *    matched — that is your own metadata, echoed back unverified.
+ */
+export type SignDocumentResultHandoff = {
+    kind: 'sign_document_result';
+    outcome: 'cancelled';
+    requestId: string;
+    correlationId?: string;
+} | {
+    kind: 'sign_document_result';
+    outcome: 'saved_draft' | 'sent';
+    requestId: string;
+    envelopeId: string;
+    correlationId?: string;
+};
+/** Every handoff payload a plugin can receive. Switch on `kind` — the union
+ *  is the extension point, and a kind you do not handle must be ignored
+ *  rather than assumed. */
+export type ArcheHandoffPayload = OpenDocumentHandoff | SignDocumentResultHandoff;
 export interface VaultDocumentUploadParams {
     /** Document display name. */
     name: string;
@@ -842,6 +986,12 @@ export interface VaultDocumentUploadResult {
     /** Status after finalize — `'uploaded'`, then `'available'` once the
      *  extraction worker indexes the document for search. */
     status: string;
+    /**
+     * Only on `upload({ userVisible: true })`: whether the user let your app
+     * keep editing the file it just saved into their files. See
+     * `VaultDocumentPromoteResult.editAccess`.
+     */
+    editAccess?: boolean;
 }
 export interface VaultDocumentReferenceResult {
     referenceId: string;
@@ -875,6 +1025,7 @@ export interface VaultDocumentsApi {
     read: (documentId: string) => Promise<{
         content: string;
         contentType: string;
+        revision?: string;
     }>;
     /**
      * Read the raw bytes of a document THIS ARCHE created (any content
@@ -903,6 +1054,8 @@ export interface VaultDocumentsApi {
             sensitivity: string;
             createdAt: string;
             updatedAt: string;
+            /** See `VaultDocumentSummary.revision`. */
+            revision?: string;
         };
         bytes: Uint8Array;
         contentType: string | null;
@@ -912,9 +1065,17 @@ export interface VaultDocumentsApi {
      * `documentId`, bytes replaced, no version history. The path for an arche
      * that saves continuously as the user works (a spreadsheet's autosave);
      * to publish a distinct new version instead, use
-     * `write({ replacesDocumentId })`, which keeps the chain. UTF-8 text only,
-     * ≤ 200 KB encoded (OWN_DOCUMENT_SAVE_TOO_LARGE names the cap) — larger
-     * documents need `upload`. Only arche-private documents qualify: a
+     * `write({ replacesDocumentId })`, which keeps the chain. Accepts text OR
+     * bytes, up to 15 MB (OWN_DOCUMENT_SAVE_TOO_LARGE names the cap — it is
+     * the same ceiling `readBytes` serves, so anything you save you can
+     * reopen): a `string` is saved as UTF-8 text and the document must be a
+     * text type; a `Uint8Array` / `ArrayBuffer` / `Blob` is saved as-is, for
+     * any type (a PDF editor saving its PDF). Transport is automatic — small
+     * text rides the bridge message, everything else is uploaded by the host —
+     * so there is no second method to choose. Pass `expectedRevision` to
+     * refuse the save (VERSION_CONFLICT) when another tab or device changed
+     * the document first; re-read, merge, and retry with the new revision.
+     * Only arche-private documents qualify: a
      * document the user can see in their own files, even one this arche
      * created, rejects with DOCUMENT_NOT_FOUND. A document whose upload never
      * finished or that is mid-extraction rejects with
@@ -932,13 +1093,45 @@ export interface VaultDocumentsApi {
      * results until re-extraction exists.
      */
     saveContent: (params: VaultDocumentSaveContentParams) => Promise<VaultDocumentSaveContentResult>;
+    /**
+     * Move a document THIS ARCHE created out of its private space and into the
+     * user's own Fias files — the SAME document, not a copy: same `documentId`,
+     * no second upload, nothing double-counted against storage. Use it to hand
+     * over a finished working file instead of `upload({ userVisible: true })`,
+     * which would mint a duplicate.
+     *
+     * The user decides. The host shows them its own confirmation naming the
+     * file and where it will go; this resolves once they agree, and rejects
+     * with `SAVE_DECLINED` if they don't (or if the host cannot ask — the dev
+     * harness and the builder preview can't). Nothing the plugin sends can skip
+     * that step. The file lands in your app's folder under My Fias; you cannot
+     * choose another.
+     *
+     * Requires `vault:user-documents:write` in your manifest (it escalates to
+     * human review) and a registered folder for your arche — the same two
+     * things `upload({ userVisible: true })` needs.
+     *
+     * ONE-WAY, and it changes what you can do: once the file is the user's,
+     * THIS hook's `saveContent`, `update` and `delete` reject — it is theirs
+     * now. To keep saving it, declare `vault:user-documents:edit`: the
+     * confirmation then offers the user "let this app keep editing", the result
+     * carries `editAccess`, and you save through
+     * `useVaultUserDocuments().saveContent` instead. Without that, promote when
+     * the user is DONE. There is no plugin-side demote.
+     *
+     * After a `SAVE_DECLINED`, re-`list()` before assuming nothing moved. The
+     * host performs the move itself, so in the rare case its page is torn down
+     * mid-move (the user navigates away) you are told "declined" for a promote
+     * that completed. The document's `visibility` is the truth.
+     */
+    promoteToUserFiles: (documentId: string) => Promise<VaultDocumentPromoteResult>;
     /**
      * Get a fresh presigned download URL for a documentId. The result is
      * cached client-side and refreshed automatically before expiry.
      */
     getDownloadUrl: (documentId: string) => Promise<VaultDocumentDownloadUrl>;
-    /** Create a small text document inline (UTF-8, ≤1 MB). For binaries
-     *  or larger documents use `upload`. */
+    /** Create a small text document inline (UTF-8, ≤200 KB — the content rides
+     *  the bridge request body). For binaries or larger documents use `upload`. */
     write: (params: VaultDocumentWriteParams) => Promise<{
         documentId: string;
     }>;