@fias/arche-sdk 2.30.0 → 2.32.0

package/dist/hooks.js

@@ -16,6 +16,7 @@ exports.useSurface = useSurface;
 exports.useFiasNavigation = useFiasNavigation;
 exports.usePersistentState = usePersistentState;
 exports.useFiasChrome = useFiasChrome;
+exports.useOpener = useOpener;
 exports.useStepNavigation = useStepNavigation;
 exports.useFiasDataStore = useFiasDataStore;
 exports.useFiasWorkspaces = useFiasWorkspaces;
@@ -34,6 +35,7 @@ exports.useDataSubscription = useDataSubscription;
 exports.useVaultUserDocuments = useVaultUserDocuments;
 exports.useCreativeLibrary = useCreativeLibrary;
 exports.useFiasConnections = useFiasConnections;
+exports.useFiasWebSources = useFiasWebSources;
 exports.useFiasX = useFiasX;
 exports.useFiasSchedules = useFiasSchedules;
 exports.useFiasLinkedIn = useFiasLinkedIn;
@@ -107,6 +109,8 @@ function createDebouncedWriter(bridge) {
     }
     return { schedule, flush };
 }
+/** The platform's `resolve_people` limit per call; `resolvePeople` pages above it. */
+const RESOLVE_PEOPLE_PAGE = 100;
 /**
  * Access the current user's profile information.
  * Requires the `user:profile:read` permission in fias-plugin.json.
@@ -438,6 +442,20 @@ function useImageEntities(filter) {
  * run, so we use the same 2-minute ceiling as the image/audio surfaces.
  */
 const CLIENT_ENTITY_INVOKE_TIMEOUT_MS = 120000;
+/**
+ * Whether a `client_entity_invoke` failed because the host has no executor
+ * for the entity (an older Fias, or the dev harness): the capability is simply
+ * not available there. Hosts answer `CLIENT_ENTITY_UNAVAILABLE`; older ones
+ * only said so in the message ("no client-side executor …"), which is still
+ * recognised. Any other bridge error is the app's to fix.
+ */
+function isClientEntityUnavailable(err) {
+    if (!(err instanceof bridge_1.FiasBridgeError))
+        return false;
+    if (err.code === 'CLIENT_ENTITY_UNAVAILABLE')
+        return true;
+    return err.code === 'BRIDGE_ERROR' && err.message.includes('no client-side executor');
+}
 /**
  * Invoke a client-side ("on-device") entity through the bridge's generic
  * `client_entity_invoke` op. Client-side entities execute entirely in the
@@ -757,6 +775,7 @@ const INERT_CHROME = {
     sidebarCollapsed: false,
     hostExpandedBar: true,
     hostExpandButton: true,
+    opener: null,
 };
 /**
  * The host chrome around your arche — Fias's standard expand/contract (the
@@ -819,6 +838,7 @@ function useFiasChrome() {
     const openAssistant = (0, react_1.useCallback)(() => bridge.openAssistant(), [bridge]);
     return (0, react_1.useMemo)(() => ({
         ...(chrome ?? INERT_CHROME),
+        opener: chrome?.opener ?? null,
         supported: supported && chrome !== null,
         setFocusMode,
         setSidebarCollapsed,
@@ -837,6 +857,72 @@ function useFiasChrome() {
         openAssistant,
     ]);
 }
+/** The person answers the send sheet; it waits on them, like the picker. */
+const SEND_TO_OPENER_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * Where the person came from, when a Fias tool opened your arche — the forge
+ * page's "Open FiasWorks Studio", the Arche Builder's (ADR-037 D8) — and the
+ * two things you can do about it:
+ *
+ * - `returnTo()` takes the person back there.
+ * - `send(file)` offers a Vault file YOUR arche created ("Use in {name}"):
+ *   Fias shows the person a sheet naming the file and the destination, and
+ *   their Send moves it — into a forge's `public/`, or an Arche Builder
+ *   arche's asset library. Requires `opener:send`.
+ *
+ * `opener` is null when nothing opened your arche; show neither then. Reading
+ * it does not take the host chrome over (unlike `useFiasChrome`).
+ *
+ * @example
+ *   const { opener, send, returnTo } = useOpener();
+ *   {opener && <button onClick={returnTo}>Return to {opener.name}</button>}
+ *   {opener && <button onClick={() => send({ fileId, name: 'pumpkin.png' })}>
+ *     Use in {opener.name}</button>}
+ */
+function useOpener() {
+    const bridge = useBridge();
+    const [opener, setOpener] = (0, react_1.useState)(bridge.getChrome()?.opener ?? null);
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        bridge.waitForInit().then(() => {
+            if (!cancelled)
+                setOpener(bridge.getChrome()?.opener ?? null);
+        });
+        const unsubscribe = bridge.onChromeUpdate((next) => setOpener(next?.opener ?? null));
+        return () => {
+            cancelled = true;
+            unsubscribe();
+        };
+    }, [bridge]);
+    const returnTo = (0, react_1.useCallback)(() => {
+        if (bridge.getChrome()?.opener)
+            bridge.navigateHost('opener');
+    }, [bridge]);
+    const send = (0, react_1.useCallback)(async (file) => {
+        if (!bridge.getChrome()?.opener) {
+            throw new bridge_1.FiasBridgeError('Nothing opened this arche, so there is nowhere to send', 'NO_OPENER');
+        }
+        let answer;
+        try {
+            answer = await bridge.request('client_entity_invoke', {
+                entityId: entity_ops_1.SEND_TO_OPENER_ENTITY_ID,
+                input: { fileId: file.fileId, ...(file.name ? { name: file.name } : {}) },
+            }, SEND_TO_OPENER_TIMEOUT_MS);
+        }
+        catch (err) {
+            // A host without it (an older Fias, the dev harness).
+            if (isClientEntityUnavailable(err)) {
+                throw new bridge_1.FiasBridgeError('Sending to another arche is not available here', 'SEND_UNAVAILABLE');
+            }
+            throw err;
+        }
+        if (answer && 'error' in answer) {
+            throw new bridge_1.FiasBridgeError(answer.error.message, answer.error.code);
+        }
+        return answer;
+    }, [bridge]);
+    return (0, react_1.useMemo)(() => ({ opener, returnTo, send }), [opener, returnTo, send]);
+}
 /**
  * Manage step navigation for multi-node plugins.
  * Listens for step_navigate messages from the host to support
@@ -1074,6 +1160,17 @@ function useFiasDataStore() {
         batch,
     ]);
 }
+/** A member target on the wire: a typed username, or the app's ref (ADR-040 §4). */
+function memberTargetPayload(member) {
+    if (typeof member === 'string')
+        return { username: member };
+    if (member && typeof member === 'object' && typeof member.ref === 'string') {
+        return { ref: member.ref };
+    }
+    // Most often `m.username` from a roster: apps created after app user refs
+    // get `ref` there instead (ADR-040 §4).
+    throw new Error('useFiasWorkspaces: name the member by { ref } from listMembers() (or a username a person typed)');
+}
 /**
  * Access workspace tenancy — team/org workspaces with role-gated membership
  * (owner/admin/member/viewer) over `workspace`-scoped Data Store collections
@@ -1087,7 +1184,8 @@ function useFiasDataStore() {
  * @example
  * const workspaces = useFiasWorkspaces();
  * const ws = await workspaces.create('Acme Corp');
- * await workspaces.addMember(ws.workspaceId, otherUserId, 'member');
+ * // a person picks who to add, in a sheet Fias draws (ADR-040):
+ * const { added } = await workspaces.addPeople(ws.workspaceId);
  * // or, inside a Fias org workspace, its members' shared space:
  * const shared = await workspaces.openForWorkspace();
  * // then, with useFiasDataStore():
@@ -1118,10 +1216,41 @@ function useFiasWorkspaces() {
     const archive = (0, react_1.useCallback)(async (workspaceId) => {
         await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'archive', { workspaceId });
     }, [bridge]);
+    const resolvePeople = (0, react_1.useCallback)(async (refs, workspaceId) => {
+        // Any length, in order: nothing to ask for an empty list, and the
+        // platform's 100-per-call limit is the SDK's to page, not the app's.
+        const people = [];
+        for (let i = 0; i < refs.length; i += RESOLVE_PEOPLE_PAGE) {
+            const page = refs.slice(i, i + RESOLVE_PEOPLE_PAGE);
+            const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'resolve_people', workspaceId === undefined ? { refs: page } : { refs: page, workspaceId });
+            people.push(...res.people);
+        }
+        return people;
+    }, [bridge]);
     const listMembers = (0, react_1.useCallback)(async (workspaceId) => {
         const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'list_members', { workspaceId });
         return res.members;
     }, [bridge]);
+    const addPeople = (0, react_1.useCallback)(async (workspaceId, options) => {
+        let answer;
+        try {
+            answer = await bridge.request('client_entity_invoke', {
+                entityId: entity_ops_1.WORKSPACE_ADD_PEOPLE_ENTITY_ID,
+                input: options?.role ? { workspaceId, role: options.role } : { workspaceId },
+            }, ADD_PEOPLE_SHEET_TIMEOUT_MS);
+        }
+        catch (err) {
+            // A host without the sheet (an older Fias or dev harness) has no
+            // executor for it: the sheet is simply not available there.
+            if (isClientEntityUnavailable(err)) {
+                throw new bridge_1.FiasBridgeError('Adding people is not available here', 'ADD_PEOPLE_UNAVAILABLE');
+            }
+            throw err;
+        }
+        if ('error' in answer)
+            throw new bridge_1.FiasBridgeError(answer.error.message, answer.error.code);
+        return { added: answer.added };
+    }, [bridge]);
     const addMember = (0, react_1.useCallback)(async (workspaceId, username, role, expiresAt) => {
         const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'add_member', {
             workspaceId,
@@ -1131,14 +1260,14 @@ function useFiasWorkspaces() {
         });
         return res.member;
     }, [bridge]);
-    const updateMember = (0, react_1.useCallback)(async (workspaceId, username, role) => {
-        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'update_member', { workspaceId, username, role });
+    const updateMember = (0, react_1.useCallback)(async (workspaceId, member, role) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'update_member', { workspaceId, ...memberTargetPayload(member), role });
         return res.member;
     }, [bridge]);
-    const removeMember = (0, react_1.useCallback)(async (workspaceId, username) => {
+    const removeMember = (0, react_1.useCallback)(async (workspaceId, member) => {
         await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'remove_member', {
             workspaceId,
-            username,
+            ...memberTargetPayload(member),
         });
     }, [bridge]);
     return (0, react_1.useMemo)(() => ({
@@ -1148,9 +1277,11 @@ function useFiasWorkspaces() {
         get,
         archive,
         listMembers,
+        addPeople,
         addMember,
         updateMember,
         removeMember,
+        resolvePeople,
     }), [
         create,
         openForWorkspace,
@@ -1158,9 +1289,11 @@ function useFiasWorkspaces() {
         get,
         archive,
         listMembers,
+        addPeople,
         addMember,
         updateMember,
         removeMember,
+        resolvePeople,
     ]);
 }
 /** The refusals that mean "no access here" — the workspaces `get` verb's two answers. */
@@ -1245,13 +1378,10 @@ function useFiasAccess(workspaceId) {
         }
         catch (err) {
             // A host without the sheet (an older Fias, or an older dev harness) has
-            // no executor for it and answers a generic bridge error naming that —
-            // "no client-side executor registered" / "no client-side executor for …
-            // in the dev harness": the sheet is simply not available. Any other bridge error (a missing permission, a call loop)
-            // is the app's to fix, so it passes through unchanged.
-            if (err instanceof bridge_1.FiasBridgeError &&
-                err.code === 'BRIDGE_ERROR' &&
-                err.message.includes('no client-side executor')) {
+            // no executor for it: the sheet is simply not available. Any other
+            // bridge error (a missing permission, a call loop) is the app's to fix,
+            // so it passes through unchanged.
+            if (isClientEntityUnavailable(err)) {
                 throw new bridge_1.FiasBridgeError('Managing access is not available here', 'ACCESS_UNAVAILABLE');
             }
             throw err;
@@ -1295,6 +1425,8 @@ const lastAccessAnswers = new Map();
 const FOCUS_REFETCH_MIN_MS = 30000;
 /** How long a person may keep the access sheet open before the call gives up. */
 const ACCESS_SHEET_TIMEOUT_MS = 30 * 60 * 1000;
+/** The Add people sheet waits on a person, like the access sheet. */
+const ADD_PEOPLE_SHEET_TIMEOUT_MS = ACCESS_SHEET_TIMEOUT_MS;
 const sharedAccessByBridge = new WeakMap();
 function peekSharedAccess(bridge, workspaceId) {
     return sharedAccessByBridge.get(bridge)?.get(workspaceId);
@@ -2958,7 +3090,7 @@ async function fetchCommunityAssetUrls(bridge, assetIds) {
     return hits;
 }
 /**
- * The user's Creative Library (ADR-035): their styles and characters, made in
+ * The user's Creative Library (ADR-037): their styles and characters, made in
  * FiasWorks Studio or any arche they allow, owned by them — or, in a team
  * workspace that approved this arche, the workspace's. Requires
  * `vault:creative:read`; `create` / `update` / `remove` / `restore` also need
@@ -2998,9 +3130,7 @@ function useCreativeLibrary() {
                 catch (err) {
                     // A host without the picker (an older Fias, the dev harness) has no
                     // executor for it: the picker is simply not available there.
-                    if (err instanceof bridge_1.FiasBridgeError &&
-                        err.code === 'BRIDGE_ERROR' &&
-                        err.message.includes('no client-side executor')) {
+                    if (isClientEntityUnavailable(err)) {
                         throw new bridge_1.FiasBridgeError('The Creative Library picker is not available here', 'PICKER_UNAVAILABLE');
                     }
                     throw err;
@@ -3047,6 +3177,54 @@ function useFiasConnections() {
     }, [bridge]);
     return (0, react_1.useMemo)(() => ({ list, connect, release }), [list, connect, release]);
 }
+/**
+ * Pages on websites Fias approved, read as DATA (ADR-038). Requires
+ * `web:sources:read`.
+ *
+ * The app names a page on an approved site and a form — the fields it wants —
+ * and gets back values of those kinds (numbers, dates, yes/no, the app's own
+ * choices, lists of them), each `null` when the page does not say. It never
+ * receives the page's text, not even a short label. One copy of each page serves every app, fetched at most
+ * once an hour; a fresh fetch and its reading are charged to the user (well
+ * under a cent for a typical page), and a cached result is free.
+ *
+ * @example
+ *   const web = useFiasWebSources();
+ *   const result = await web.extract<{
+ *     rates: Array<{ termMonths: number | null; ira: boolean | null; apy: number | null }>;
+ *   }>({
+ *     url: 'https://www.becu.org/everyday-banking/certificates',
+ *     form: {
+ *       description: 'Share certificate rates',
+ *       fields: {
+ *         rates: {
+ *           kind: 'list',
+ *           item: {
+ *             termMonths: { kind: 'integer', min: 1, max: 120, description: 'Term in months' },
+ *             ira: { kind: 'boolean', description: 'An IRA certificate' },
+ *             apy: { kind: 'number', min: 0, max: 25, description: 'APY in percent' },
+ *           },
+ *         },
+ *       },
+ *     },
+ *   });
+ *   // Show result.site.name and result.fetchedAt beside the figures.
+ */
+function useFiasWebSources() {
+    const bridge = useBridge();
+    const listSites = (0, react_1.useCallback)(async (options) => (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.WEB_SOURCES_ENTITY_ID, 'list_sites', {
+        ...(options?.category !== undefined ? { category: options.category } : {}),
+        ...(options?.search !== undefined ? { search: options.search } : {}),
+        ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+        ...(options?.offset !== undefined ? { offset: options.offset } : {}),
+    }), [bridge]);
+    const extract = (0, react_1.useCallback)(async (request) => (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.WEB_SOURCES_ENTITY_ID, 'extract', {
+        url: request.url,
+        form: request.form,
+        ...(request.maxAgeSeconds !== undefined ? { maxAgeSeconds: request.maxAgeSeconds } : {}),
+    }), [bridge]);
+    return (0, react_1.useMemo)(() => ({ listSites, extract }), [listSites, extract]);
+}
 /**
  * X, as an account the workspace this app is open in let it use (ADR-029 §3).
  *
@@ -3151,7 +3329,8 @@ function useFiasLinkedIn() {
  * The From address is always the Company's — you only choose recipients and
  * content.
  *
- * Name members by `userId`; you never see their addresses. Every email carries
+ * Name members by their ref (`useFiasUser().ref`, or refs you stored); you
+ * never see their addresses. Every email carries
  * a one-click unsubscribe, and people who used it are skipped (`muted`).
  *
  * @example
@@ -3159,7 +3338,7 @@ function useFiasLinkedIn() {
  * const email = useCompanyEmail();
  * const result = await email.send({
  *   requestKey: `digest-${weekId}`,
- *   to: members.map((m) => ({ userId: m.userId })),
+ *   to: assigneeRefs.map((ref) => ({ ref })),
  *   subject: 'Your weekly digest',
  *   text: digestText,
  *   html: digestHtml,