@fias/arche-sdk 2.27.0 → 2.28.0

package/dist/hooks.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FiasContentError = exports.PLUGIN_CONTENT_ENTITY_ID = exports.GRAMMAR_CHECK_ENTITY_ID = exports.NLLB_LANGUAGES = exports.NLLB_TRANSLATION_ENTITY_ID = void 0;
+exports.FiasContentError = exports.FiasLocalStoreError = exports.PLUGIN_LOCAL_STORE_ENTITY_ID = exports.PLUGIN_CONTENT_ENTITY_ID = exports.ArcheAssetError = exports.ARCHE_ASSET_BYTES_ENTITY_ID = exports.GRAMMAR_CHECK_ENTITY_ID = exports.NLLB_LANGUAGES = exports.NLLB_TRANSLATION_ENTITY_ID = void 0;
 exports.useFiasUser = useFiasUser;
 exports.useFiasTheme = useFiasTheme;
 exports.useFiasVendoredAssets = useFiasVendoredAssets;
@@ -21,6 +21,8 @@ exports.useFiasStore = useFiasStore;
 exports.fetchVaultDocumentDownloadUrl = fetchVaultDocumentDownloadUrl;
 exports.useVaultDocuments = useVaultDocuments;
 exports.useArcheAssets = useArcheAssets;
+exports.useArcheAssetBytes = useArcheAssetBytes;
+exports.useLocalStore = useLocalStore;
 exports.useFiasContent = useFiasContent;
 exports.useFiasPreviewState = useFiasPreviewState;
 exports.useDataSubscription = useDataSubscription;
@@ -1457,6 +1459,16 @@ function bytesToBase64(bytes) {
  * state, and refresh `signedUrl` via `getUrl(assetId)` when it's about
  * to expire.
  *
+ * The library holds images and short sound effects (MP3 / WAV). `list` and
+ * `index` return images unless you pass `kinds` (e.g. `{ kinds: ['audio'] }`),
+ * and with `kinds` the entries are typed `ArcheLibraryAsset` — narrow on
+ * `contentType` before using an image's size. Keeping sounds here is
+ * optional; music is not accepted. Sound effects that must play on cue need
+ * decoded Web Audio buffers: load library sounds with
+ * {@link useArcheAssetBytes}`().getMany` once per session, or bundle them in
+ * the plugin's JS (base64) — not in `public/`, which only an `<audio>`
+ * element can play.
+ *
  * Permission: `assets:read`.
  *
  * @example
@@ -1471,12 +1483,14 @@ function useArcheAssets() {
             cursor: options?.cursor,
             limit: options?.limit,
             tags: options?.tags,
+            kinds: options?.kinds,
         });
     }, [bridge]);
     const index = (0, react_1.useCallback)(async (options) => {
         return bridge.request('arche_assets_index', {
             tags: options?.tags,
             groupBy: options?.groupBy,
+            kinds: options?.kinds,
         });
     }, [bridge]);
     const getUrl = (0, react_1.useCallback)(async (assetId) => {
@@ -1484,6 +1498,269 @@ function useArcheAssets() {
     }, [bridge]);
     return (0, react_1.useMemo)(() => ({ list, index, getUrl }), [list, index, getUrl]);
 }
+/**
+ * Read the bytes of assets in this arche's asset library — for Web Audio
+ * (`AudioContext.decodeAudioData`), canvas pixel work, or anything else a
+ * signed URL cannot do (the plugin sandbox has no network). Read each sound
+ * once per session and keep the decoded buffer.
+ *
+ * To load a set of sounds, pass the listed entries to `getMany`: up to 100
+ * are read per call, so a whole sound set takes one or two calls. One call
+ * per sound would trip the bridge's runaway-loop guard (more than 50 calls in
+ * 5 seconds), which blocks every read for 10 seconds — `getBytes` calls made
+ * together are batched for the same reason. The host page fetches each asset,
+ * so each read costs one asset load like an `<img>` does. Unavailable in the
+ * builder preview.
+ *
+ * Sounds are ready to trigger only once their buffers are decoded: wait for
+ * the load before the first cue, and resume the `AudioContext` on the first
+ * user gesture.
+ *
+ * Permissions: `entities:client_invoke` AND `assets:read`.
+ *
+ * @example
+ *   const { list } = useArcheAssets();
+ *   const { getMany } = useArcheAssetBytes();
+ *   const { entries } = await list({ kinds: ['audio'], tags: ['sfx:ui'] });
+ *   const ctx = new AudioContext();
+ *   const loaded = await getMany(entries);
+ *   const buffers = new Map<string, AudioBuffer>();
+ *   for (const entry of entries) {
+ *     const result = loaded[entry.assetId];
+ *     if (result instanceof Error) continue; // result.code says why
+ *     buffers.set(entry.name ?? entry.assetId, await ctx.decodeAudioData(result.bytes));
+ *   }
+ */
+function useArcheAssetBytes() {
+    const bridge = useBridge();
+    const getBytes = (0, react_1.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 = (0, react_1.useCallback)(async (assets) => {
+        const read = await readAssetBytesBatch(bridge, assets);
+        const out = {};
+        for (const [assetId, result] of read)
+            out[assetId] = result;
+        return out;
+    }, [bridge]);
+    return (0, react_1.useMemo)(() => ({ getBytes, getMany }), [getBytes, getMany]);
+}
+/**
+ * Entity ID of the arche asset bytes client-side entity — the host-side
+ * reader behind {@link useArcheAssetBytes}. Literal here so the SDK
+ * stays bundle-clean (no `@fias/entities` runtime dep).
+ *
+ * SYNC NOTE: must match `ARCHE_ASSET_BYTES_ENTITY_ID` in
+ * `packages/entities/src/integrations/arche-asset-bytes/config.ts`. The
+ * architecture test `sdk-entity-id-constants-match.test.ts` pins this.
+ */
+exports.ARCHE_ASSET_BYTES_ENTITY_ID = 'ent_intg_arche_asset_bytes_00000';
+/** A failed asset byte read (`useArcheAssetBytes`): `code` says why. */
+class ArcheAssetError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'ArcheAssetError';
+    }
+}
+exports.ArcheAssetError = ArcheAssetError;
+/** A listed URL with less than this many seconds left is replaced, not reused. */
+const ASSET_URL_MIN_REMAINING_SECONDS = 30;
+/** Most URLs the host reads in one call (`ARCHE_ASSET_BYTES_MAX_URLS` in the executor). */
+const ASSET_BYTES_MAX_URLS_PER_CALL = 100;
+/**
+ * Most lapsed URLs one batch replaces with `arche_assets_get_url`, one call
+ * each. Covers URLs that lapse in flight while staying far below the bridge's
+ * 50-calls-in-5-seconds guard; a batch of older entries is answered
+ * `ASSET_URL_EXPIRED` past this, so the plugin lists again (one call).
+ */
+const ASSET_URL_MAX_REFRESHES_PER_BATCH = 10;
+/** One `read` call: the outcome of each URL, in order. Throws when the call itself is refused. */
+async function readSignedUrls(bridge, signedUrls) {
+    let response;
+    try {
+        response = await bridge.request('client_entity_invoke', { entityId: exports.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');
+}
+/**
+ * Read `items` in calls of up to 100 URLs, recording each outcome in `out`.
+ * Assets that did not fit a call's byte budget beside the others go again
+ * together until a pass reads nothing more (then each is too large on its
+ * own). Returns the reused URLs that lapsed in flight, for a fresh URL.
+ */
+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) {
+                    // A reused URL can lapse before the host's fetch lands (or the
+                    // device clock runs fast); a fresh one recovers it.
+                    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;
+}
+/**
+ * Read `refs` in as few host calls as possible: reuse each listed URL while it
+ * has time left, replace a bounded number of lapsed ones, and send up to 100
+ * URLs per call. Throws only when a call is refused as a whole.
+ */
+async function readAssetBytesBatch(bridge, refs) {
+    const out = new Map();
+    let refreshesLeft = ASSET_URL_MAX_REFRESHES_PER_BATCH;
+    // A fresh URL for each lapsed item, within the batch's refresh allowance.
+    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;
+    };
+    // One read per asset, whatever the caller passed twice.
+    const unique = new Map();
+    for (const ref of refs)
+        if (!unique.has(ref.assetId))
+            unique.set(ref.assetId, ref);
+    const nowSeconds = Date.now() / 1000;
+    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;
+}
+const pendingAssetByteReads = 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 = 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)) {
+            // Two callers asked for one asset: each gets its own buffer, because
+            // `decodeAudioData` detaches the one it is given.
+            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} — 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) — one call per 100.`, 'RATE_LIMIT');
+    }
+    return new ArcheAssetError(message, 'ASSET_UNAVAILABLE');
+}
 /**
  * Entity ID of the plugin content pack client-side entity (ADR-021) — the
  * host-side reader behind {@link useFiasContent}. Literal here so the SDK
@@ -1494,6 +1771,143 @@ function useArcheAssets() {
  * architecture test `sdk-entity-id-constants-match.test.ts` pins this.
  */
 exports.PLUGIN_CONTENT_ENTITY_ID = 'ent_intg_plugin_content_00000000';
+/**
+ * Entity ID of the plugin local store client-side entity (ADR-031) — the
+ * host-side store behind {@link useLocalStore}. Literal here so the SDK stays
+ * bundle-clean (no `@fias/entities` runtime dep).
+ *
+ * SYNC NOTE: must match `PLUGIN_LOCAL_STORE_ENTITY_ID` in
+ * `packages/entities/src/integrations/plugin-local-store/config.ts`. The
+ * architecture test `sdk-entity-id-constants-match.test.ts` pins this.
+ */
+exports.PLUGIN_LOCAL_STORE_ENTITY_ID = 'ent_intg_plugin_local_store_0000';
+/** A failed local-store call: `code` says why. */
+class FiasLocalStoreError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'FiasLocalStoreError';
+    }
+}
+exports.FiasLocalStoreError = FiasLocalStoreError;
+function toLocalStoreError(err) {
+    if (err instanceof FiasLocalStoreError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    // The bridge's centralized gates carry a code; the registry's own refusals
+    // (per-entity permission, per-entity rate bucket) are plain Errors, so the
+    // message is the fallback, never the first look.
+    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);
+}
+/**
+ * Keep working data on the user's device — a recovery journal, drafts, a
+ * cache — so a refresh, a crash or a closed tab loses nothing. Writes take
+ * milliseconds and never touch the network: the host page keeps the data in
+ * its own browser storage, in a space only this plugin can read, for the
+ * signed-in user in the workspace they are working in (Personal and each org
+ * workspace keep separate data; switching workspace switches the store).
+ * Signing out clears it.
+ *
+ * This is NOT where a user's work is kept. It is best-effort device storage —
+ * a browser may clear site data, and nothing here reaches another device —
+ * so write the journal here and save the user's files through the Vault
+ * (`useVaultUserDocuments().saveContent`, `upload`, or the Save dialog).
+ *
+ * Values: a string, bytes (`ArrayBuffer` / `Uint8Array`), or any JSON value;
+ * `get` returns the same kind. One value ≤ 64 MB; the whole store for this
+ * user ≤ 256 MB. Over budget, `put` throws `LOCAL_STORE_QUOTA_EXCEEDED`
+ * rather than evicting — decide what to keep with `estimate()` and `list()`.
+ * For a large snapshot (an image, a big document), put BYTES: a JSON value is
+ * validated and serialized on the host page, which costs time proportional
+ * to its size on every write, while bytes are only copied. Restore a journal
+ * with `getMany(keys)` — one call for up to 100 entries, instead of one call
+ * per key.
+ *
+ * Permission: `storage:local`.
+ *
+ * @example
+ *   const store = useLocalStore();
+ *   await store.put(`session/${docId}`, snapshotJson);        // on every change
+ *   const saved = await store.getJson<Snapshot>(`session/${docId}`); // on load
+ *   await store.delete(`session/${docId}`);                    // on close
+ */
+function useLocalStore() {
+    const bridge = useBridge();
+    const call = (0, react_1.useCallback)(async (input) => {
+        let response;
+        try {
+            response = await bridge.request('client_entity_invoke', { entityId: exports.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 = (0, react_1.useCallback)(async (key) => (await call({ verb: 'get', key })).entry ?? null, [call]);
+    const getText = (0, react_1.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 = (0, react_1.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 = (0, react_1.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');
+        }
+        // A top-level string is always stored as text, so `put(key,
+        // JSON.stringify(x))` reads back here the same as `put(key, x)`.
+        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 = (0, react_1.useCallback)(async (keys) => (await call({ verb: 'get_many', keys }))
+        .entries ?? [], [call]);
+    const put = (0, react_1.useCallback)(async (key, value) => ({
+        sizeBytes: (await call({ verb: 'put', key, value })).sizeBytes ?? 0,
+    }), [call]);
+    const del = (0, react_1.useCallback)(async (key) => {
+        await call({ verb: 'delete', key });
+    }, [call]);
+    const list = (0, react_1.useCallback)(async (prefix) => (await call({ verb: 'list', ...(prefix !== undefined ? { prefix } : {}) })).entries ?? [], [call]);
+    const clear = (0, react_1.useCallback)(async () => ({
+        deleted: (await call({ verb: 'clear' })).deleted ?? 0,
+    }), [call]);
+    const estimate = (0, react_1.useCallback)(async () => {
+        const res = await call({ verb: 'estimate' });
+        return { usedBytes: res.usedBytes ?? 0, budgetBytes: res.budgetBytes ?? 0 };
+    }, [call]);
+    return (0, react_1.useMemo)(() => ({ get, getMany, getText, getBytes, getJson, put, delete: del, list, clear, estimate }), [get, getMany, getText, getBytes, getJson, put, del, list, clear, estimate]);
+}
 /** A failed content read: `code` says why, `path` names the file when there is one. */
 class FiasContentError extends Error {
     constructor(message, code, path) {
@@ -2130,9 +2544,11 @@ function useCommunityAssets() {
  * mutate the source. And you are the authoritative type gate — if you cannot
  * open this file, tell the user plainly rather than opening something broken.
  *
- * To be offered as a destination at all, your arche must be registered for
- * document intake on the platform side; declaring this hook alone does not
- * enrol you.
+ * To be offered as a destination at all, declare what you open in
+ * `fias-plugin.json` (`"fileIntake": { "kinds": ["document"], "types": [".docx"] }`;
+ * `types` narrows a kind to the files you really open) and have Fias approve
+ * it; declaring this hook alone does not enrol you. A kind or type added later
+ * stays off until it is approved too.
  */
 function useArcheHandoff(onHandoff) {
     const bridge = useBridge();