@fias/arche-sdk 2.27.0 → 2.28.0

package/dist/index.mjs

@@ -2240,7 +2240,8 @@ function useArcheAssets() {
       return bridge.request("arche_assets_list", {
         cursor: options?.cursor,
         limit: options?.limit,
-        tags: options?.tags
+        tags: options?.tags,
+        kinds: options?.kinds
       });
     },
     [bridge]
@@ -2249,7 +2250,8 @@ function useArcheAssets() {
     async (options) => {
       return bridge.request("arche_assets_index", {
         tags: options?.tags,
-        groupBy: options?.groupBy
+        groupBy: options?.groupBy,
+        kinds: options?.kinds
       });
     },
     [bridge]
@@ -2262,7 +2264,327 @@ function useArcheAssets() {
   );
   return useMemo2(() => ({ list, index, getUrl }), [list, index, getUrl]);
 }
+function useArcheAssetBytes() {
+  const bridge = useBridge();
+  const getBytes = useCallback(
+    async (asset) => {
+      let ref;
+      if (typeof asset === "string") {
+        try {
+          ref = await bridge.request("arche_assets_get_url", { assetId: asset });
+        } catch (err) {
+          throw toArcheAssetError(err);
+        }
+      } else {
+        ref = asset;
+      }
+      return enqueueAssetByteRead(bridge, ref);
+    },
+    [bridge]
+  );
+  const getMany = useCallback(
+    async (assets) => {
+      const read = await readAssetBytesBatch(bridge, assets);
+      const out = {};
+      for (const [assetId, result] of read) out[assetId] = result;
+      return out;
+    },
+    [bridge]
+  );
+  return useMemo2(() => ({ getBytes, getMany }), [getBytes, getMany]);
+}
+var ARCHE_ASSET_BYTES_ENTITY_ID = "ent_intg_arche_asset_bytes_00000";
+var ArcheAssetError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "ArcheAssetError";
+  }
+};
+var ASSET_URL_MIN_REMAINING_SECONDS = 30;
+var ASSET_BYTES_MAX_URLS_PER_CALL = 100;
+var ASSET_URL_MAX_REFRESHES_PER_BATCH = 10;
+async function readSignedUrls(bridge, signedUrls) {
+  let response;
+  try {
+    response = await bridge.request(
+      "client_entity_invoke",
+      { entityId: ARCHE_ASSET_BYTES_ENTITY_ID, input: { verb: "read", signedUrls } },
+      CLIENT_ENTITY_INVOKE_TIMEOUT_MS
+    );
+  } catch (err) {
+    throw toArcheAssetError(err);
+  }
+  if ("error" in response) {
+    throw new ArcheAssetError(response.error.message, response.error.code);
+  }
+  return response.results;
+}
+function fileError(result) {
+  return result && "error" in result ? new ArcheAssetError(result.error.message, result.error.code) : new ArcheAssetError("the asset could not be read", "ASSET_UNAVAILABLE");
+}
+async function readInBatches(bridge, items, out) {
+  const lapsed = [];
+  let queue = items;
+  while (queue.length > 0) {
+    const overBudget = [];
+    let readCount = 0;
+    for (let at = 0; at < queue.length; at += ASSET_BYTES_MAX_URLS_PER_CALL) {
+      const chunk = queue.slice(at, at + ASSET_BYTES_MAX_URLS_PER_CALL);
+      const results = await readSignedUrls(
+        bridge,
+        chunk.map((item) => item.signedUrl)
+      );
+      chunk.forEach((item, i) => {
+        const result = results[i];
+        if (result && !("error" in result)) {
+          out.set(item.assetId, result);
+          readCount += 1;
+        } else if (result?.error.code === "ASSET_URL_EXPIRED" && !item.refreshed) {
+          lapsed.push(item);
+        } else if (result?.error.code === "ASSET_TOO_LARGE" && chunk.length > 1) {
+          overBudget.push(item);
+        } else {
+          out.set(item.assetId, fileError(result));
+        }
+      });
+    }
+    if (readCount === 0) {
+      for (const item of overBudget) {
+        out.set(
+          item.assetId,
+          new ArcheAssetError("the asset is too large to read", "ASSET_TOO_LARGE")
+        );
+      }
+      break;
+    }
+    queue = overBudget;
+  }
+  return lapsed;
+}
+async function readAssetBytesBatch(bridge, refs) {
+  const out = /* @__PURE__ */ new Map();
+  let refreshesLeft = ASSET_URL_MAX_REFRESHES_PER_BATCH;
+  const refresh = async (assetIds) => {
+    const fresh = [];
+    for (const assetId of assetIds) {
+      if (refreshesLeft <= 0) {
+        out.set(
+          assetId,
+          new ArcheAssetError(
+            "the asset URL has expired; list the assets again for fresh URLs",
+            "ASSET_URL_EXPIRED"
+          )
+        );
+        continue;
+      }
+      refreshesLeft -= 1;
+      try {
+        const asset = await bridge.request("arche_assets_get_url", { assetId });
+        fresh.push({ assetId, signedUrl: asset.signedUrl, refreshed: true });
+      } catch (err) {
+        out.set(assetId, toArcheAssetError(err));
+      }
+    }
+    return fresh;
+  };
+  const unique = /* @__PURE__ */ new Map();
+  for (const ref of refs) if (!unique.has(ref.assetId)) unique.set(ref.assetId, ref);
+  const nowSeconds = Date.now() / 1e3;
+  const reusable = [];
+  const stale = [];
+  for (const ref of unique.values()) {
+    if (ref.expiresAt - nowSeconds > ASSET_URL_MIN_REMAINING_SECONDS) {
+      reusable.push({ assetId: ref.assetId, signedUrl: ref.signedUrl, refreshed: false });
+    } else {
+      stale.push(ref.assetId);
+    }
+  }
+  const pending = [...reusable, ...await refresh(stale)];
+  const lapsed = await readInBatches(bridge, pending, out);
+  if (lapsed.length > 0) {
+    await readInBatches(bridge, await refresh(lapsed.map((item) => item.assetId)), out);
+  }
+  return out;
+}
+var pendingAssetByteReads = /* @__PURE__ */ new WeakMap();
+function enqueueAssetByteRead(bridge, ref) {
+  let batch = pendingAssetByteReads.get(bridge);
+  if (!batch) {
+    const created = { refs: [], waiters: [] };
+    pendingAssetByteReads.set(bridge, created);
+    batch = created;
+    void Promise.resolve().then(() => flushAssetByteReads(bridge, created));
+  }
+  batch.refs.push(ref);
+  const queued = batch;
+  return new Promise((resolve, reject) => {
+    queued.waiters.push({ assetId: ref.assetId, resolve, reject });
+  });
+}
+async function flushAssetByteReads(bridge, batch) {
+  pendingAssetByteReads.delete(bridge);
+  let results;
+  try {
+    results = await readAssetBytesBatch(bridge, batch.refs);
+  } catch (err) {
+    const failure = toArcheAssetError(err);
+    for (const waiter of batch.waiters) waiter.reject(failure);
+    return;
+  }
+  const handedOut = /* @__PURE__ */ new Set();
+  for (const waiter of batch.waiters) {
+    const result = results.get(waiter.assetId) ?? new ArcheAssetError("the asset could not be read", "ASSET_UNAVAILABLE");
+    if (result instanceof ArcheAssetError) {
+      waiter.reject(result);
+    } else if (handedOut.has(waiter.assetId)) {
+      waiter.resolve({ ...result, bytes: result.bytes.slice(0) });
+    } else {
+      handedOut.add(waiter.assetId);
+      waiter.resolve(result);
+    }
+  }
+}
+function toArcheAssetError(err) {
+  if (err instanceof ArcheAssetError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  const code = err?.code;
+  if (/permission denied/i.test(message)) {
+    return new ArcheAssetError(
+      `${message} \u2014 useArcheAssetBytes needs both "assets:read" and "entities:client_invoke" in fias-plugin.json`,
+      "PERMISSION_DENIED"
+    );
+  }
+  if (code === "RATE_LIMITED" || code === "RATE_LIMIT" || /rate limit/i.test(message)) {
+    return new ArcheAssetError(message, "RATE_LIMIT");
+  }
+  if (/rapid-fire loop|runaway loop/i.test(message)) {
+    return new ArcheAssetError(
+      `${message} Load many assets with useArcheAssetBytes().getMany(entries) \u2014 one call per 100.`,
+      "RATE_LIMIT"
+    );
+  }
+  return new ArcheAssetError(message, "ASSET_UNAVAILABLE");
+}
 var PLUGIN_CONTENT_ENTITY_ID = "ent_intg_plugin_content_00000000";
+var PLUGIN_LOCAL_STORE_ENTITY_ID = "ent_intg_plugin_local_store_0000";
+var FiasLocalStoreError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "FiasLocalStoreError";
+  }
+};
+function toLocalStoreError(err) {
+  if (err instanceof FiasLocalStoreError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  const raw = err?.code;
+  const code = raw === "PERMISSION_DENIED" || /permission denied/i.test(message) ? "PERMISSION_DENIED" : raw === "RATE_LIMIT" || raw === "RATE_LIMITED" || /rate limit/i.test(message) ? "RATE_LIMIT" : "LOCAL_STORE_UNAVAILABLE";
+  return new FiasLocalStoreError(message, code);
+}
+function useLocalStore() {
+  const bridge = useBridge();
+  const call = useCallback(
+    async (input) => {
+      let response;
+      try {
+        response = await bridge.request(
+          "client_entity_invoke",
+          { entityId: PLUGIN_LOCAL_STORE_ENTITY_ID, input },
+          CLIENT_ENTITY_INVOKE_TIMEOUT_MS
+        );
+      } catch (err) {
+        throw toLocalStoreError(err);
+      }
+      if (response?.error) {
+        throw new FiasLocalStoreError(response.error.message, response.error.code);
+      }
+      return response ?? {};
+    },
+    [bridge]
+  );
+  const get = useCallback(
+    async (key) => (await call({ verb: "get", key })).entry ?? null,
+    [call]
+  );
+  const getText = useCallback(
+    async (key) => {
+      const entry = await get(key);
+      if (!entry) return null;
+      if (typeof entry.value !== "string") {
+        throw new FiasLocalStoreError(`"${key}" does not hold text`, "LOCAL_STORE_WRONG_KIND");
+      }
+      return entry.value;
+    },
+    [get]
+  );
+  const getBytes = useCallback(
+    async (key) => {
+      const entry = await get(key);
+      if (!entry) return null;
+      if (!(entry.value instanceof ArrayBuffer)) {
+        throw new FiasLocalStoreError(`"${key}" does not hold bytes`, "LOCAL_STORE_WRONG_KIND");
+      }
+      return entry.value;
+    },
+    [get]
+  );
+  const getJson = useCallback(
+    async (key) => {
+      const entry = await get(key);
+      if (!entry) return null;
+      if (entry.value instanceof ArrayBuffer) {
+        throw new FiasLocalStoreError(`"${key}" holds bytes, not JSON`, "LOCAL_STORE_WRONG_KIND");
+      }
+      if (typeof entry.value === "string") {
+        try {
+          return JSON.parse(entry.value);
+        } catch {
+          throw new FiasLocalStoreError(
+            `"${key}" holds text that is not JSON`,
+            "LOCAL_STORE_WRONG_KIND"
+          );
+        }
+      }
+      return entry.value;
+    },
+    [get]
+  );
+  const getMany = useCallback(
+    async (keys) => (await call({ verb: "get_many", keys })).entries ?? [],
+    [call]
+  );
+  const put = useCallback(
+    async (key, value) => ({
+      sizeBytes: (await call({ verb: "put", key, value })).sizeBytes ?? 0
+    }),
+    [call]
+  );
+  const del = useCallback(
+    async (key) => {
+      await call({ verb: "delete", key });
+    },
+    [call]
+  );
+  const list = useCallback(
+    async (prefix) => (await call({ verb: "list", ...prefix !== void 0 ? { prefix } : {} })).entries ?? [],
+    [call]
+  );
+  const clear = useCallback(
+    async () => ({
+      deleted: (await call({ verb: "clear" })).deleted ?? 0
+    }),
+    [call]
+  );
+  const estimate = useCallback(async () => {
+    const res = await call({ verb: "estimate" });
+    return { usedBytes: res.usedBytes ?? 0, budgetBytes: res.budgetBytes ?? 0 };
+  }, [call]);
+  return useMemo2(
+    () => ({ get, getMany, getText, getBytes, getJson, put, delete: del, list, clear, estimate }),
+    [get, getMany, getText, getBytes, getJson, put, del, list, clear, estimate]
+  );
+}
 var FiasContentError = class extends Error {
   constructor(message, code, path) {
     super(message);
@@ -2962,6 +3284,7 @@ var VALID_PLUGIN_PERMISSIONS = [
   "entities:web_search",
   "navigation:open_arche",
   "sandbox:vendored-libraries",
+  "storage:local",
   "storage:sandbox",
   "store:purchase",
   "theme:read",
@@ -2981,7 +3304,7 @@ var PLUGIN_PERMISSION_DESCRIPTIONS = {
   "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.",
+  "assets:read": "Show images and play sounds from this arche's published asset library.",
   "data:agents": "Let Fias AI, and assistants you connect with an API key and allow here, read this arche's data \u2014 and change it where it says so \u2014 even while it is closed.",
   "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.",
@@ -2996,6 +3319,7 @@ 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:local": "Keep its working files on this device, so a refresh or crash does not lose your work. Nothing leaves your device; cleared when you sign out or when someone else signs in here.",
   "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.",
@@ -5485,6 +5809,7 @@ function validatePanelCatalog(value) {
   return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
 }
 export {
+  ARCHE_ASSET_BYTES_ENTITY_ID,
   AUDIO_AUDIO_ISOLATION_SURFACE_KEY,
   AUDIO_FORCED_ALIGNMENT_SURFACE_KEY,
   AUDIO_GEMINI_TRANSCRIBE_SURFACE_KEY,
@@ -5496,6 +5821,7 @@ export {
   AUDIO_TTS_SURFACE_KEY,
   AUDIO_VOICE_CHANGER_SURFACE_KEY,
   AUDIO_VOICE_DESIGN_SURFACE_KEY,
+  ArcheAssetError,
   DARK_THEME,
   ENTITY_INVOCATION_HISTORY_LIMITS,
   ENTITY_INVOCATION_REQUEST_LIMITS,
@@ -5504,6 +5830,7 @@ export {
   FiasBridge,
   FiasBridgeError,
   FiasContentError,
+  FiasLocalStoreError,
   FiasProvider,
   GRAMMAR_CHECK_ENTITY_ID,
   IMAGE_SMART_CONTROL_SURFACE_KEY,
@@ -5537,6 +5864,7 @@ export {
   PANEL_THEME_Z_MAX,
   PANEL_TITLE_MAX_LENGTH,
   PLUGIN_CONTENT_ENTITY_ID,
+  PLUGIN_LOCAL_STORE_ENTITY_ID,
   PLUGIN_PERMISSION_DESCRIPTIONS,
   REASONING_EFFORTS,
   SDK_BRIDGE_PROTOCOL_VERSION,
@@ -5557,6 +5885,7 @@ export {
   invocationPayloadByteLimit,
   isValidPluginPermission,
   resetBridge,
+  useArcheAssetBytes,
   useArcheAssets,
   useArcheHandoff,
   useAudioGeneration,
@@ -5591,6 +5920,7 @@ export {
   useImageEntities,
   useImageGeneration,
   useIntegrationWebSearch,
+  useLocalStore,
   useLyriaMusic,
   usePersistentState,
   useSmartControl,