@usearete/react 0.41.1 → 0.42.0

package/README.md

@@ -315,6 +315,46 @@ await or compose the result.
 
 Program and read hooks are safe to call while the client is still connecting: mutations throw "Arete client is not connected" if submitted early, and reads stay disabled.
 
+## Protocols
+
+Protocol clients come from `@usearete/sdk` (`createProtocolClient(DEFINITION, { auth })` or `session.protocols.<key>`; see its README). Create one per key outside render (or memoize it) and pass it to these hooks:
+
+```tsx
+import { createProtocolClient } from '@usearete/sdk';
+import { useAllowedSteps, useProtocolEvents, useProtocolInstance } from '@usearete/react';
+import TOKEN_RAISE from './generated/typescript/protocols/token-raise/token-raise';
+
+const raise = createProtocolClient(TOKEN_RAISE, { auth: { publishableKey: 'a4_pk_...' } });
+
+function Raise({ id, wallet }: { id: string; wallet?: string }) {
+  const { instance, live, error, isLoading } = useProtocolInstance(raise, id, { wallet });
+  const steps = useAllowedSteps(raise, { instance: id, wallet }, { refreshOnEvents: true });
+  useProtocolEvents(raise, id, {
+    onEvent: (event) => {
+      if (event.type === 'emit' && event.event === 'raise.succeeded') celebrate();
+    },
+  });
+
+  if (isLoading) return <Spinner />;
+  const contribute = steps.data?.find((step) => step.step === 'contribute');
+  return (
+    <button
+      disabled={!contribute?.allowed}
+      onClick={() => raise.steps.contribute.prepare({ instance: id, wallet: wallet!, amount: '1000000' })}
+    >
+      {instance?.state} {contribute?.reason}
+    </button>
+  );
+}
+```
+
+- `useProtocolInstance(client, instanceId, { wallet? })` returns the canonical instance, refreshed on every event of the instance's stream, plus `live` (the protocol stack's row when the client belongs to a session whose protocol ships a stack). The stream opens while mounted.
+- `useAllowedSteps(client, { instance, wallet })` and `useProtocolParticipant(client, { instance, wallet })` are one-shot reads with the same `status`, `refresh()` and argument-keyed behavior as other read hooks; they stay disabled until every argument is set. `refreshOnEvents: true` re-reads on stream events.
+- `useWalletActions(client, { wallet, instance?, cursor?, limit? })` reads `client.actions`: the create steps and one page of instances the wallet relates to, with each step's availability, reason and typed args. It is disabled until `wallet` is set and re-reads when any argument changes (pass `data.nextCursor` as `cursor` to page). With `instance` set, `refreshOnEvents: true` re-reads on that instance's stream events.
+- `useProtocolEvents(client, instanceId, { onEvent, onError?, lastEventId? })` follows the stream with the latest callbacks, reopening only when the client or instance changes.
+
+All of them keep the generated types: instance and participant states, step names, guard codes and event names. A publishable-key client has only the `public` steps, so a secret step does not compile in browser code.
+
 ## Safe amount parsing
 
 `safeToRawAmount(input, decimals)` is re-exported by `@usearete/react` for form validation. Unlike `toRawAmount`, it reports invalid input without throwing:

package/dist/index.cjs

@@ -2186,7 +2186,7 @@ function chainKey(chain) {
     chainIds.set(chain, id);
     return id;
 }
-function abortError() {
+function abortError$1() {
     const error = new Error('Chain read was aborted');
     error.name = 'AbortError';
     return error;
@@ -2199,10 +2199,10 @@ function useNativeBalance(chain, address, options = {}) {
             throw new Error('Chain client and address are required for a native balance read');
         }
         if (signal.aborted)
-            throw abortError();
+            throw abortError$1();
         const result = await chain.nativeBalance(address, { minContextSlot });
         if (signal.aborted)
-            throw abortError();
+            throw abortError$1();
         return result;
     }, { enabled, initialData: options.initialData });
 }
@@ -2221,14 +2221,172 @@ function useTokenBalance(chain, input, options = {}) {
             throw new Error('Chain client and token input are required for a token balance read');
         }
         if (signal.aborted)
-            throw abortError();
+            throw abortError$1();
         const result = await chain.balance(input, { minContextSlot });
         if (signal.aborted)
-            throw abortError();
+            throw abortError$1();
         return result;
     }, { enabled, initialData: options.initialData });
 }
 
+const clientIds = new WeakMap();
+let nextClientId = 1;
+function clientKey(client) {
+    if (!client)
+        return null;
+    const existing = clientIds.get(client);
+    if (existing !== undefined)
+        return existing;
+    const id = nextClientId++;
+    clientIds.set(client, id);
+    return id;
+}
+function abortError() {
+    const error = new Error('Protocol read was aborted');
+    error.name = 'AbortError';
+    return error;
+}
+const EMPTY_VIEW = { snapshot: undefined, error: undefined };
+/**
+ * Follow one protocol instance: the canonical instance from the hosted API,
+ * refreshed whenever its event stream reports a change, plus the protocol
+ * stack's live row when available. The stream opens while the component is
+ * mounted and closes when it unmounts.
+ */
+function useProtocolInstance(client, instanceId, options = {}) {
+    const enabled = (options.enabled ?? true) && Boolean(client && instanceId);
+    const wallet = options.wallet ?? undefined;
+    const handle = React.useMemo(() => (enabled && client && instanceId
+        ? client.instances.use(instanceId, wallet ? { wallet } : undefined)
+        : undefined), [client, instanceId, wallet, enabled]);
+    React.useEffect(() => () => handle?.close(), [handle]);
+    const cache = React.useRef({ handle: undefined, view: EMPTY_VIEW });
+    const subscribe = React.useCallback((listener) => (handle ? handle.subscribe(listener) : () => undefined), [handle]);
+    const getSnapshot = React.useCallback(() => {
+        if (!handle)
+            return EMPTY_VIEW;
+        const snapshot = handle.get();
+        const error = handle.getError();
+        const cached = cache.current;
+        if (cached.handle === handle && cached.view.snapshot === snapshot && cached.view.error === error) {
+            return cached.view;
+        }
+        const view = { snapshot, error };
+        cache.current = { handle, view };
+        return view;
+    }, [handle]);
+    const view = React.useSyncExternalStore(subscribe, getSnapshot, () => EMPTY_VIEW);
+    const refresh = React.useCallback(async () => {
+        await handle?.refresh();
+    }, [handle]);
+    return {
+        instance: view.snapshot?.instance,
+        live: view.snapshot?.live,
+        error: view.error,
+        isLoading: Boolean(handle) && view.snapshot === undefined && view.error === undefined,
+        refresh,
+    };
+}
+function useRefreshOnEvents(client, instanceId, enabled, refresh) {
+    const refreshRef = React.useRef(refresh);
+    refreshRef.current = refresh;
+    React.useEffect(() => {
+        if (!enabled || !client || !instanceId)
+            return undefined;
+        const subscription = client.events(instanceId, {
+            onEvent: () => {
+                void refreshRef.current().catch(() => undefined);
+            },
+        });
+        return () => subscription.close();
+    }, [client, instanceId, enabled]);
+}
+/**
+ * Which steps `wallet` can call on `instance` now, and why not (a guard code
+ * or an access code).
+ */
+function useAllowedSteps(client, input, options = {}) {
+    const { instance, wallet } = input;
+    const enabled = (options.enabled ?? true) && Boolean(client && instance && wallet);
+    const result = useAsyncRead(['protocol-allowed-steps', clientKey(client), instance, wallet], async ({ signal }) => {
+        if (!client || !instance || !wallet) {
+            throw new Error('A protocol client, instance and wallet are required for allowed steps');
+        }
+        if (signal.aborted)
+            throw abortError();
+        const steps = await client.allowedSteps({ instance, wallet, signal });
+        if (signal.aborted)
+            throw abortError();
+        return steps;
+    }, { enabled, initialData: options.initialData, debounceMs: options.debounceMs });
+    useRefreshOnEvents(client, instance, enabled && (options.refreshOnEvents ?? false), result.refresh);
+    return result;
+}
+/**
+ * Which steps `wallet` can call now across the deployment: create steps and
+ * one page of the instances it relates to, each with its availability,
+ * reason and typed arguments. With `instance` set, `refreshOnEvents: true`
+ * re-reads on that instance's stream events.
+ */
+function useWalletActions(client, input, options = {}) {
+    const { wallet } = input;
+    const instance = input.instance ?? undefined;
+    const cursor = input.cursor ?? undefined;
+    const limit = input.limit;
+    const enabled = (options.enabled ?? true) && Boolean(client && wallet);
+    const result = useAsyncRead(['protocol-wallet-actions', clientKey(client), wallet, instance, cursor, limit], async ({ signal }) => {
+        if (!client || !wallet) {
+            throw new Error('A protocol client and wallet are required for wallet actions');
+        }
+        if (signal.aborted)
+            throw abortError();
+        const actions = await client.actions({ wallet, instance, cursor, limit, signal });
+        if (signal.aborted)
+            throw abortError();
+        return actions;
+    }, { enabled, initialData: options.initialData, debounceMs: options.debounceMs });
+    useRefreshOnEvents(client, instance, enabled && (options.refreshOnEvents ?? false), result.refresh);
+    return result;
+}
+/** One wallet's participant record on an instance. */
+function useProtocolParticipant(client, input, options = {}) {
+    const { instance, wallet } = input;
+    const enabled = (options.enabled ?? true) && Boolean(client && instance && wallet);
+    const result = useAsyncRead(['protocol-participant', clientKey(client), instance, wallet], async ({ signal }) => {
+        if (!client || !instance || !wallet) {
+            throw new Error('A protocol client, instance and wallet are required for a participant read');
+        }
+        if (signal.aborted)
+            throw abortError();
+        const participant = await client.participants.get({ instance, wallet, signal });
+        if (signal.aborted)
+            throw abortError();
+        return participant;
+    }, { enabled, initialData: options.initialData, debounceMs: options.debounceMs });
+    useRefreshOnEvents(client, instance, enabled && (options.refreshOnEvents ?? false), result.refresh);
+    return result;
+}
+/**
+ * Follow an instance's event stream while mounted. The latest callbacks are
+ * always used; the stream reopens only when the client or instance changes.
+ */
+function useProtocolEvents(client, instanceId, options) {
+    const optionsRef = React.useRef(options);
+    optionsRef.current = options;
+    const enabled = (options.enabled ?? true) && Boolean(client && instanceId);
+    React.useEffect(() => {
+        if (!enabled || !client || !instanceId)
+            return undefined;
+        const eventOptions = {
+            lastEventId: optionsRef.current.lastEventId,
+            onEvent: (event) => optionsRef.current.onEvent(event),
+            onError: (error) => optionsRef.current.onError?.(error),
+        };
+        const subscription = client.events(instanceId, eventOptions);
+        return () => subscription.close();
+    }, [client, instanceId, enabled]);
+}
+
 Object.defineProperty(exports, 'Arete', {
     enumerable: true,
     get: function () { return sdk.Arete; }
@@ -2417,12 +2575,17 @@ exports.createProcessedSlotReconciliation = createProcessedSlotReconciliation;
 exports.reconcileProcessedSlot = reconcileProcessedSlot;
 exports.summarizeStatuses = summarizeStatuses;
 exports.summarizeViews = summarizeViews;
+exports.useAllowedSteps = useAllowedSteps;
 exports.useArete = useArete;
 exports.useAreteContext = useAreteContext;
 exports.useAsyncRead = useAsyncRead;
 exports.useConnectionState = useConnectionState;
 exports.useInstructionMutation = useInstructionMutation;
 exports.useNativeBalance = useNativeBalance;
+exports.useProtocolEvents = useProtocolEvents;
+exports.useProtocolInstance = useProtocolInstance;
+exports.useProtocolParticipant = useProtocolParticipant;
 exports.useReconcileProcessedSlot = useReconcileProcessedSlot;
 exports.useTokenBalance = useTokenBalance;
+exports.useWalletActions = useWalletActions;
 //# sourceMappingURL=index.cjs.map