@fias/arche-sdk 2.19.2 → 2.20.0

package/dist/index.mjs

@@ -1840,17 +1840,6 @@ 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 });
@@ -1921,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,
@@ -1939,12 +1938,12 @@ function useVaultDocuments() {
       getDownloadUrl,
       write,
       update,
-      promoteToUserFiles,
       delete: deleteDocument,
       search,
       attach,
       detach,
       upload,
+      saveCopy,
       uploadInit,
       uploadFinalize
     }),
@@ -1956,12 +1955,12 @@ function useVaultDocuments() {
       getDownloadUrl,
       write,
       update,
-      promoteToUserFiles,
       deleteDocument,
       search,
       attach,
       detach,
       upload,
+      saveCopy,
       uploadInit,
       uploadFinalize
     ]
@@ -2043,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);
@@ -2133,7 +2249,8 @@ function useVaultUserDocuments() {
     async (options) => {
       return bridge.request("vault_documents_pick", {
         maxDocuments: options?.maxDocuments,
-        access: options?.access
+        access: options?.access,
+        ...options?.accept ? { accept: [...options.accept] } : {}
       });
     },
     [bridge]
@@ -2536,6 +2653,7 @@ 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",
@@ -2546,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.",
@@ -2561,15 +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: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."
+  "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
@@ -5056,6 +5175,7 @@ export {
   FONT_PAIRINGS,
   FiasBridge,
   FiasBridgeError,
+  FiasContentError,
   FiasProvider,
   GRAMMAR_CHECK_ENTITY_ID,
   IMAGE_SMART_CONTROL_SURFACE_KEY,
@@ -5088,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,
@@ -5118,6 +5239,7 @@ export {
   useElevenLabsVoiceDesign,
   useEntityInvocation,
   useFiasAIActions,
+  useFiasContent,
   useFiasDataStore,
   useFiasFonts,
   useFiasNavigation,

package/dist/types.d.ts

@@ -678,6 +678,21 @@ export interface FiasNavigationApi {
         path?: string;
         payload?: ArcheHandoffPayloadInput;
     }) => void;
+    /**
+     * The host's current path, expressed in THIS plugin's own route space — the
+     * same space `navigateTo` accepts. A plugin mounted at
+     * `/a/<arche>/my-books` reads `/my-books`, and its home page reads `/`.
+     * Parse it with your own router; it never carries the `/a/<arche>` prefix.
+     *
+     * Tracks the host: it updates after your own `navigateTo`, and when the
+     * user moves the host themselves with browser back/forward. A router driven
+     * off this value stays in step with the address bar.
+     *
+     * `''` before the host's `init` message lands (the bridge handshake is
+     * async, so the first render usually happens first). Treat the empty string
+     * as "not known yet" rather than as the home page — that distinction is what
+     * lets a direct entry such as a share link survive the pre-init race.
+     */
     currentPath: string;
 }
 /**
@@ -846,20 +861,6 @@ export interface VaultDocumentSaveContentResult {
 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. */
     topK?: number;
@@ -949,28 +950,49 @@ export interface VaultDocumentUploadParams {
     /** Optional predecessor for replace-mode uploads. */
     replacesDocumentId?: string;
     /**
-     * Save this as a document the USER owns and can see — it appears in their
-     * Fias files under your arche's folder, other arches can pick it, and it
-     * outlives your app. Without this the document is arche-private: yours to
+     * Where the file goes. Omitted: your arche's own private space — yours to
      * read and write, invisible everywhere else.
      *
+     * `'documents'` — into the USER's Documents, through the host **Save
+     * dialog**: the user picks the folder, can change the name, settles a name
+     * clash (keep both, or replace a file of the same type), and decides what
+     * your arche keeps afterwards. `name` is the name you SUGGEST. The result
+     * tells you the document id, the final `name` and your `access` — never the
+     * folder.
+     *
      * Use it for the artifact the user made and asked you to keep (an edited
      * image, an exported document). Do NOT use it for your app's own state —
      * caches, session snapshots, working files — which belong in the default
      * private space.
      *
-     * Requires the `vault:user-documents:write` permission, and the HOST asks
-     * the user to confirm each save by name. If they decline, this rejects with
-     * `SAVE_DECLINED`; treat that as a normal outcome, not an error to retry.
-     * Cannot be combined with `folderPath` (the destination is your arche's
-     * registered folder), and is unavailable in preview and in the dev harness.
+     * Requires `vault:user-documents:write`. If the user cancels, this rejects
+     * with `SAVE_DECLINED`; treat that as a normal outcome, not an error to
+     * retry. Cannot be combined with `folderPath`, `replacesDocumentId`, `tags`
+     * or `sensitivity` (the user decides those — `INVALID_PARAMS`). Unavailable
+     * in preview and in the dev harness.
      *
-     * `upload` only — the lower-level `uploadInit` cannot do this. The host has
-     * to run the confirmation, and it can only do that when it is orchestrating
-     * the whole upload.
+     * `upload` only — the lower-level `uploadInit` cannot do this: the host has
+     * to show the dialog, and it can only do that when it orchestrates the
+     * whole upload.
+     *
+     * `'arche-saves'` — AUTOMATICALLY into the user's `Arche Saves/<your
+     * label>/`, with no dialog. Only for an arche a Fias admin has designated
+     * (which issues its label) AND that declares `vault:arche-saves:write`;
+     * otherwise it rejects with `ARCHE_NOT_DESIGNATED` or `PERMISSION_DENIED`.
+     * The file is user-visible, and your arche keeps reaching it through
+     * `useVaultDocuments()` while it stays in Arche Saves. Cannot be combined
+     * with `folderPath` or `userVisible`. Use it for outputs the user expects to
+     * find without being asked each time; otherwise prefer `'documents'`.
      */
+    destination?: 'documents' | 'arche-saves';
+    /** Alias for `destination: 'documents'` (the original spelling). */
     userVisible?: boolean;
 }
+/** Options for {@link VaultDocumentsApi.saveCopy}. */
+export interface VaultDocumentSaveCopyOptions {
+    /** The name to suggest in the Save dialog. Default: the document's name. */
+    suggestedName?: string;
+}
 export interface VaultDocumentUploadInitResult {
     documentId: string;
     /** Presigned PUT URL — the plugin must PUT the bytes to this URL. */
@@ -987,10 +1009,25 @@ export interface VaultDocumentUploadResult {
      *  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`.
+     * Only on a save into the user's Documents (`destination: 'documents'`,
+     * `saveCopy`): the name the user kept — it may differ from the one you
+     * suggested ("Report (2).pdf" after "keep both").
+     */
+    name?: string;
+    /**
+     * Only on a save into the user's Documents: what your arche can do with the
+     * file afterwards.
+     *   - `'read'` — open it again, through `useVaultUserDocuments()` (declare
+     *     `vault:user-documents:read`).
+     *   - `'write'` — the user ticked "keep editing": keep saving it with
+     *     `useVaultUserDocuments().saveContent` (needs `vault:user-documents:edit`).
+     *   - `'none'` — nothing: your arche cannot hold access to it (no `:read`
+     *     permission, or the file is proprietary).
+     * The user can change it at any time in Arche Access. The file is theirs:
+     * `useVaultDocuments()` does not list it.
      */
+    access?: 'none' | 'read' | 'write';
+    /** Published alias: `access === 'write'`. */
     editAccess?: boolean;
 }
 export interface VaultDocumentReferenceResult {
@@ -1093,38 +1130,6 @@ 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.
@@ -1168,11 +1173,23 @@ export interface VaultDocumentsApi {
      * `'uploaded'` → `'available'`).
      */
     upload: (bytes: ArrayBuffer | Uint8Array, params: VaultDocumentUploadParams) => Promise<VaultDocumentUploadResult>;
+    /**
+     * Hand the user a COPY of one of your own documents: the host Save dialog
+     * opens with its content, the user chooses where it goes in their
+     * Documents, and your working file is left exactly as it was (delete it
+     * afterwards if you no longer need it). Same outcome and result as
+     * `upload(bytes, { destination: 'documents' })`, without re-sending the
+     * bytes.
+     *
+     * Requires `vault:documents:read` (the host reads your file) and
+     * `vault:user-documents:write`. Cancelling rejects with `SAVE_DECLINED`.
+     */
+    saveCopy: (documentId: string, options?: VaultDocumentSaveCopyOptions) => Promise<VaultDocumentUploadResult>;
     /**
      * Lower-level — start an upload, returning a presigned PUT URL.
      * Prefer `upload` unless you need to drive the PUT yourself.
      */
-    uploadInit: (params: Omit<VaultDocumentUploadParams, 'userVisible'> & {
+    uploadInit: (params: Omit<VaultDocumentUploadParams, 'userVisible' | 'destination'> & {
         sizeBytes: number;
         checksumSha256: string;
     }) => Promise<VaultDocumentUploadInitResult>;
@@ -1275,6 +1292,51 @@ export interface ArcheAssetsApi {
     /** Refresh the signed URL for a single asset. */
     getUrl: (assetId: string) => Promise<ArcheAsset>;
 }
+/**
+ * Why a content read failed. The first seven come from the host's content
+ * reader; `PERMISSION_DENIED` (the manifest lacks `entities:client_invoke`)
+ * and `RATE_LIMIT` come from the bridge.
+ */
+export type FiasContentErrorCode = 'CONTENT_NOT_FOUND' | 'CONTENT_NOT_TEXT' | 'CONTENT_TOO_LARGE' | 'CONTENT_UNAVAILABLE' | 'CONTENT_THROTTLED' | 'CONTENT_UNAVAILABLE_IN_PREVIEW' | 'INVALID_INPUT' | 'PERMISSION_DENIED' | 'RATE_LIMIT';
+/** One file of the published content pack. `path` is relative to `content/`. */
+export interface FiasContentFile {
+    path: string;
+    sizeBytes: number;
+    mimeType: string;
+}
+/** A signed, arche-scoped URL for streaming media. Request a new one after `expiresAt`. */
+export interface FiasContentUrl {
+    url: string;
+    expiresAt: string;
+}
+export interface FiasContentApi {
+    /** Files in the pack, optionally under a path prefix (e.g. `'lessons/'`). */
+    list(prefix?: string): Promise<FiasContentFile[]>;
+    /** A text file (`.md`, `.txt`, `.json`) as a string. */
+    getText(path: string): Promise<string>;
+    /** A `.json` file, parsed. */
+    getJson<T = unknown>(path: string): Promise<T>;
+    /** Any file as bytes. */
+    getBytes(path: string): Promise<ArrayBuffer>;
+    /**
+     * Up to 100 files in one call (≤ 25 MB together). Each value is the file's
+     * content or the `FiasContentError` for that path — one missing file does
+     * not fail the rest.
+     */
+    getMany(paths: string[], as: 'text'): Promise<Record<string, string | Error>>;
+    getMany(paths: string[], as: 'bytes'): Promise<Record<string, ArrayBuffer | Error>>;
+    /**
+     * A `blob:` URL for `<img>`, `<audio>`, `@font-face` — built in the plugin
+     * from host-cached bytes, so repeat views cost the contributor nothing. The
+     * recommended way to show content images.
+     */
+    getObjectUrl(path: string): Promise<string>;
+    /**
+     * A signed CDN URL, for long media that must stream or seek. Bypasses the
+     * host cache; prefer `getObjectUrl` for anything else.
+     */
+    getUrl(path: string): Promise<FiasContentUrl>;
+}
 /** Where an asset sits in the moderation lifecycle, from the author's view. */
 export type CommunityAssetStatus = 
 /** Awaiting a verdict. Nobody else can see it yet. */
@@ -1551,6 +1613,7 @@ export interface BridgeInitMessage {
         archId: string;
         permissions: PluginPermission[];
         theme: FiasTheme;
+        /** Plugin-relative path — see `FiasNavigationApi.currentPath`. */
         currentPath: string;
         /**
          * Self-hosted vendored-library asset URLs (keyed by import specifier) —