@fias/arche-sdk 2.27.0 → 2.29.0

package/dist/hooks.js

@@ -1,12 +1,13 @@
 "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;
 exports.useFiasStorage = useFiasStorage;
 exports.useEntityInvocation = useEntityInvocation;
 exports.useTextModels = useTextModels;
+exports.useFiasHolder = useFiasHolder;
 exports.useImageGeneration = useImageGeneration;
 exports.useImageEntities = useImageEntities;
 exports.useClientEntity = useClientEntity;
@@ -21,10 +22,16 @@ 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;
 exports.useVaultUserDocuments = useVaultUserDocuments;
+exports.useFiasConnections = useFiasConnections;
+exports.useFiasX = useFiasX;
+exports.useFiasSchedules = useFiasSchedules;
+exports.useFiasLinkedIn = useFiasLinkedIn;
 exports.useCompanyEmail = useCompanyEmail;
 exports.useCommunityAssets = useCommunityAssets;
 exports.useArcheHandoff = useArcheHandoff;
@@ -290,6 +297,26 @@ function useTextModels() {
     }, [bridge]);
     return models;
 }
+/**
+ * The Fias workspace the plugin was opened in: the user's own (`personal`) or
+ * an organization's (`org`), and the user's role there.
+ *
+ * Requires `user:profile:read` or `data:workspace`. Returns `null` until the
+ * host has delivered it (usually immediately), and when the host could not
+ * resolve it. The value never changes while the plugin is open — switching
+ * workspace reopens the plugin. It carries no id and no name, and the
+ * platform applies the workspace to every call itself.
+ */
+function useFiasHolder() {
+    const bridge = useBridge();
+    const [holder, setHolder] = (0, react_1.useState)(bridge.getHolder());
+    (0, react_1.useEffect)(() => {
+        // Init may have arrived between the initial render and this effect.
+        setHolder(bridge.getHolder());
+        return bridge.onHolderReady(setHolder);
+    }, [bridge]);
+    return holder;
+}
 /**
  * How long `generate` waits for an image. High-quality renders at large sizes
  * run past two minutes, and the platform keeps working on them for up to
@@ -947,6 +974,8 @@ function useFiasDataStore() {
  * const workspaces = useFiasWorkspaces();
  * const ws = await workspaces.create('Acme Corp');
  * await workspaces.addMember(ws.workspaceId, otherUserId, 'member');
+ * // or, inside a Fias org workspace, its members' shared space:
+ * const shared = await workspaces.openForWorkspace();
  * // then, with useFiasDataStore():
  * await dataStore.put('ledger', 'tx-1', { amount: 100 }, { workspaceId: ws.workspaceId });
  *
@@ -958,6 +987,12 @@ function useFiasWorkspaces() {
         const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'create', { displayName });
         return res.workspace;
     }, [bridge]);
+    const openForWorkspace = (0, react_1.useCallback)(async () => {
+        // The workspace is the host's acting one, stamped on the call by the host;
+        // the plugin never names it.
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'create', { forActingHolder: true });
+        return res.workspace;
+    }, [bridge]);
     const list = (0, react_1.useCallback)(async () => {
         const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'list');
         return res.workspaces;
@@ -992,7 +1027,27 @@ function useFiasWorkspaces() {
             username,
         });
     }, [bridge]);
-    return (0, react_1.useMemo)(() => ({ create, list, get, archive, listMembers, addMember, updateMember, removeMember }), [create, list, get, archive, listMembers, addMember, updateMember, removeMember]);
+    return (0, react_1.useMemo)(() => ({
+        create,
+        openForWorkspace,
+        list,
+        get,
+        archive,
+        listMembers,
+        addMember,
+        updateMember,
+        removeMember,
+    }), [
+        create,
+        openForWorkspace,
+        list,
+        get,
+        archive,
+        listMembers,
+        addMember,
+        updateMember,
+        removeMember,
+    ]);
 }
 /**
  * Access the in-arche purchase (IAP) store.
@@ -1457,6 +1512,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 +1536,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 +1551,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 +1824,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) {
@@ -1975,6 +2442,133 @@ async function fetchCommunityAssetUrls(bridge, assetIds) {
     }
     return hits;
 }
+/** Connecting waits on a person (and maybe a provider sign-in in a popup). */
+const CONNECT_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Outside accounts (X, LinkedIn, …) the workspace the app is open in lets it
+ * use (ADR-029 §2). Requires `connections:use`.
+ *
+ * The app never sees a credential. `connect(provider)` asks the host to show
+ * its connect screen, where the person connects an account or lets this app
+ * use one already connected; the host makes every grant. Acting as an account
+ * (posting, reading its audience) is a verb on the provider's own entity.
+ *
+ * @example
+ *   const connections = useFiasConnections();
+ *   const accounts = await connections.list();
+ *   const x = accounts.find((a) => a.provider === 'x') ?? (await connections.connect('x'));
+ */
+function useFiasConnections() {
+    const bridge = useBridge();
+    const list = (0, react_1.useCallback)(async () => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.CONNECTIONS_ENTITY_ID, 'list');
+        return res.connections;
+    }, [bridge]);
+    const connect = (0, react_1.useCallback)(async (provider) => {
+        const result = await bridge.request('client_entity_invoke', { entityId: entity_ops_1.CONNECTIONS_CONNECT_ENTITY_ID, input: { provider } }, CONNECT_TIMEOUT_MS);
+        if (result && 'error' in result) {
+            throw new bridge_1.FiasBridgeError(result.error.message, result.error.code);
+        }
+        return result;
+    }, [bridge]);
+    const release = (0, react_1.useCallback)(async (connectionId) => {
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.CONNECTIONS_ENTITY_ID, 'release', { connectionId });
+    }, [bridge]);
+    return (0, react_1.useMemo)(() => ({ list, connect, release }), [list, connect, release]);
+}
+/**
+ * X, as an account the workspace this app is open in let it use (ADR-029 §3).
+ *
+ * Requires `connections:use` in `fias-plugin.json`. Get a `connectionId` from
+ * `useFiasConnections()` (`list`, or `connect('x')`). Each call is charged to
+ * the user as X prices it: a read by what it returns, a post per post — and a
+ * post with a link (any URL or web address) costs more than a plain one. `publishPost` puts a confirm sheet in front of the
+ * person — the platform's own words: the account, the workspace, the post —
+ * and resolves only after they approve. A decline rejects with
+ * `FiasBridgeError` code `USER_DECLINED`. Never available in the dev harness:
+ * a post needs a person in the Fias app.
+ *
+ * @example
+ * ```tsx
+ * const x = useFiasX();
+ * const { posts } = await x.publishPost({ connectionId, posts: [{ text: 'Hello' }] });
+ * ```
+ */
+function useFiasX() {
+    const bridge = useBridge();
+    return (0, react_1.useMemo)(() => ({
+        publishPost: (params) => (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.X_ENTITY_ID, 'publish_post', { ...params }),
+        searchUsers: async (connectionId, query, options) => (await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.X_ENTITY_ID, 'search_users', {
+            connectionId,
+            query,
+            ...options,
+        })).users,
+        getUserPosts: async (connectionId, options) => (await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.X_ENTITY_ID, 'get_user_posts', {
+            connectionId,
+            ...options,
+        })).posts,
+        getPostMetrics: async (connectionId, postIds) => (await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.X_ENTITY_ID, 'get_post_metrics', { connectionId, postIds })).metrics,
+        getAccountStats: (connectionId) => (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.X_ENTITY_ID, 'get_account_stats', {
+            connectionId,
+        }),
+    }), [bridge]);
+}
+/**
+ * Schedule one call for later (ADR-029 §5) — e.g. a post at 9 AM tomorrow.
+ *
+ * Requires `schedule:invoke` in `fias-plugin.json`, plus whatever the call
+ * itself needs (`connections:use` to post). For an action outside Fias the
+ * person approves the exact call AND its time in a confirm sheet first; a
+ * decline rejects with `USER_DECLINED`. When it is due every check runs again
+ * — if the account was disconnected or the app lost access, nothing is sent
+ * and `list()` shows it as `refused`. There is no edit: cancel and schedule
+ * again (a new approval).
+ *
+ * @example
+ * ```tsx
+ * const schedules = useFiasSchedules();
+ * await schedules.schedule({
+ *   entityId: X_ENTITY_ID,
+ *   verb: 'publish_post',
+ *   payload: { connectionId, posts: [{ text: 'Launch day' }] },
+ *   fireAt: tomorrowAtNine,
+ * });
+ * ```
+ */
+function useFiasSchedules() {
+    const bridge = useBridge();
+    return (0, react_1.useMemo)(() => ({
+        schedule: (params) => (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'schedule', {
+            entityId: params.entityId,
+            verb: params.verb,
+            payload: params.payload,
+            fireAt: params.fireAt instanceof Date ? params.fireAt.toISOString() : params.fireAt,
+        }),
+        list: async (options) => (await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'list', {
+            ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options?.scheduleIds ? { scheduleIds: options.scheduleIds } : {}),
+        })).schedules,
+        cancel: async (scheduleId) => {
+            await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'cancel', { scheduleId });
+        },
+    }), [bridge]);
+}
+/**
+ * LinkedIn, as a member account the workspace this app is open in let it use
+ * (ADR-029 §3). Requires `connections:use`; get a `connectionId` from
+ * `useFiasConnections()`. Each call is charged to the user. No post-metrics or
+ * audience calls yet: LinkedIn serves them only with analytics scopes the
+ * connection does not ask for. `publishPost` puts
+ * a confirm sheet in front of the person and resolves only after they approve;
+ * a decline rejects with code `USER_DECLINED`.
+ */
+function useFiasLinkedIn() {
+    const bridge = useBridge();
+    return (0, react_1.useMemo)(() => ({
+        publishPost: (params) => (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.LINKEDIN_ENTITY_ID, 'publish_post', { ...params }),
+        searchOrganizations: async (connectionId, vanityName) => (await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.LINKEDIN_ENTITY_ID, 'search_organizations', { connectionId, query: vanityName })).organizations,
+    }), [bridge]);
+}
 /**
  * Send email AS the Company this app is being used in (ADR-023), from the
  * Company's own verified domain — not from Fias.
@@ -2130,9 +2724,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();