@synapse-sdk/react 0.3.4 → 0.3.7

package/README.md

@@ -3,7 +3,7 @@
 React hooks for a Synapse node: `<SynapseProvider node={node}>` above your components, then `useConnection()`,
 `useProject()`, `useCatalog()` (the node's `status`, `project` and `catalog` cells), `useTopic(t, { select })`, `useCall(svc)`, `useServe(svc, handler)`,
 `usePublisher(t)`, `useStore(name)`, `useScene()`, `useSceneEntity(scene, id | { name }, { select })`, `useSceneTree(scene)`,
-`useSceneStatus(scene)` and `useTasks(select?)`. Every hook reads a value the node keeps current; none keeps its own
+`useSceneStatus(scene)`, `useTasks(select?)` and `useDiscover()` (your clusters, once signed in). Every hook reads a value the node keeps current; none keeps its own
 copy.
 
 ## Two kinds of users
@@ -78,6 +78,52 @@ wins, and a call superseded by a newer `connect()` or `disconnect()` resolves qu
 nothing and settles with it. `connect()` with no target settles with the declared one. `failed` is not the end: the
 node rests there until the next `connect()`; only `close()` ends it (`closed`).
 
+## Signing in: robots by name
+
+A signed-in person can connect to a robot by name, `node.connect("pi4-1@taiga/devel")`, and list their clusters and
+robots, from the browser. The SDK asks the key server for your clusters and for a token to the cluster's relay; it
+needs only a way to get the person's credential. With Clerk, pass Clerk's own `useAuth` to the provider:
+
+```tsx
+import { useAuth } from "@clerk/clerk-react";
+import { SynapseProvider, useDiscover } from "@synapse-sdk/react";
+
+<SynapseProvider node={node} useAuth={useAuth}>…</SynapseProvider>
+
+function Robots() {
+  const { status, data, error, refresh } = useDiscover();
+  if (status === "idle") return <span>sign in to see your robots</span>;
+  if (status === "error") return <button onClick={refresh}>{error!.message}: try again</button>;
+  if (!data) return <span>loading…</span>;
+  return <>{data.clusters.flatMap(c => Object.keys(c.runtimes).map(robot =>
+    <button key={`${c.id}/${robot}`} onClick={() => node.connect(`${robot}@${c.label}`)}>{robot} ({c.label})</button>))}</>;
+}
+```
+
+- The provider follows the sign-in: signed in → `node.setAuth(...)`, signed out → `node.setAuth(undefined)`, another
+  person signed in without a sign-out between (Clerk's `userId` changes) → a new sign-in. Pass `useAuth` on every
+  render (it is a hook).
+- `useDiscover()` is `{ status, data, error, refresh }` over `node.discovery`: `idle` with nobody signed in, then
+  `pending` → `success` with your clusters (`label` is what `connect()` takes after the `@`). It asks once when a person
+  signs in; every component using it shares the one answer. `refresh()` asks again.
+- Signing out never ends a live session. The next time the node has to dial (a dropped connection, or a new
+  `connect()`), it fails `unauthorized` and `useConnection()` shows `failed`; sign in again and `connect()`.
+- The node keeps what the key server said (your clusters, a token per cluster for up to 12 hours) in memory only, until
+  the next sign-in or sign-out: a reconnect costs no request to the key server.
+- Without React, the same on the node: `node.setAuth(fetchToken)` with a function that gives the person's credential
+  when asked (`null` when nobody is signed in), `node.setAuth(undefined)` on sign-out, `await node.discover()`,
+  `node.discovery.get()`. A script that signs in with a known credential: `node.setAuth(async () => token)`. The
+  option `authUrl` names another key server, for example an `http://` one on your own machine while developing; never
+  use an `http://` key server in production, the credential travels in the header.
+
+During development, without Clerk: `fakeAuth(token)` is a stand-in that is always signed in with `token`, for example
+the login `synapse login` keeps on your machine (`~/.synapse/session`), given through an environment variable and never
+committed:
+
+```tsx
+<SynapseProvider node={node} useAuth={fakeAuth(import.meta.env.VITE_SYNAPSE_TOKEN)}>…</SynapseProvider>
+```
+
 ## Calls
 
 `useCall(svc, opts)` is the one call hook, request/reply or streaming: `{ call, cancel, status, data, error, updates,

package/dist/index.d.ts

@@ -1,10 +1,34 @@
 import { type ReactNode } from "react";
-import type { Synapse, Catalog, ConnectionState, ViewOptions, ViewState, Run, CallOptions, Publisher, ServeHandler, ServeOptions, Registration, StoreHandle, StoreOptions, SceneEntity, SceneEntityRef, SceneHandle, SceneStatus, SceneTree, TasksStatus, TaskCatalogEntry, TasksRun } from "@synapse-sdk/client";
+import type { Synapse, Catalog, ConnectionState, Discovery, ViewOptions, ViewState, Run, CallOptions, Publisher, ServeHandler, ServeOptions, Registration, StoreHandle, StoreOptions, SceneEntity, SceneEntityRef, SceneHandle, SceneStatus, SceneTree, TasksStatus, TaskCatalogEntry, TasksRun } from "@synapse-sdk/client";
 import type { ErrorBody, ProjectSnapshot, ServiceRef, TopicRef, SynapseError } from "@synapse-sdk/core";
-export declare function SynapseProvider({ node, children }: {
+/**
+ * What `useAuth` gives (the shape of Clerk's `useAuth()`): whether the sign-in state is known yet, whether a person is
+ * signed in, who (`userId`, when the hook has it: another person signing in without a sign-out between is a new
+ * sign-in to the node), and their credential for the key server, fetched when asked.
+ */
+type AuthState = {
+    isLoaded: boolean;
+    isSignedIn: boolean | undefined;
+    userId?: string | null;
+    getToken(): Promise<string | null>;
+};
+/**
+ * Makes `node` the node of every hook below. With `useAuth` (Clerk's own `useAuth`, or `fakeAuth(token)`), the person
+ * signed in there is the node's (`node.setAuth`): signed in → the node asks the key server with their credential;
+ * signed out → `node.setAuth(undefined)`; not known yet → nothing; a different `userId` while signed in → a new sign-in. `useAuth` is a hook: pass it on every render or never.
+ * Signing out ends no live session.
+ */
+export declare function SynapseProvider({ node, useAuth, children }: {
     node: Synapse;
+    useAuth?: () => AuthState;
     children?: ReactNode;
 }): import("react").FunctionComponentElement<import("react").ProviderProps<Synapse | null>>;
+/**
+ * A stand-in for Clerk's `useAuth` that is always signed in with `token` (a key-server credential such as the one
+ * `synapse login` keeps on your machine), for development and tests: `<SynapseProvider node={node} useAuth={fakeAuth(token)}>`.
+ * An empty `token` is signed out. Keep the token out of your source code (an environment variable).
+ */
+export declare function fakeAuth(token: string): () => AuthState;
 export declare function useSynapse(): Synapse;
 /** The node from the nearest `<SynapseProvider>`, or `null` when there is none. */
 export declare function useSynapseOptional(): Synapse | null;
@@ -14,6 +38,18 @@ export declare function useConnection(): ConnectionState;
 export declare function useProject(): ProjectSnapshot | undefined;
 /** The runtime's catalogs as the current session last read them (`node.catalog`). */
 export declare function useCatalog(): Catalog;
+/**
+ * The signed-in person's clusters and their runtimes (`node.discovery`): `status` (`idle` with nobody signed in, `pending`,
+ * `success`, `error`), `data` (the key server's answer; still the last one on `error`), `error`, and `refresh()` to ask
+ * again. Asks the key server once when it shows `idle` and a person is signed in; every component using it shares one
+ * value and one request.
+ */
+export declare function useDiscover(): {
+    status: "idle" | "pending" | "success" | "error";
+    data: Discovery | undefined;
+    error: SynapseError | undefined;
+    refresh: () => void;
+};
 /** The last `limit` notices (`node.notices`) since the component mounted, newest last. */
 export declare function useNotices(limit?: number): ErrorBody[];
 /** Typed disabled sentinel: `useTopic("skip")` renders `pending` without subscribing. */
@@ -116,3 +152,4 @@ export interface TasksView {
  */
 export declare function useTasks(): TasksView;
 export declare function useTasks<S>(select: (t: TasksView) => S): S;
+export {};

package/dist/index.js

@@ -7,9 +7,36 @@ import { createContext, createElement, useCallback, useContext, useEffect, useMe
 import { replaceEqualDeep, shallowEqual } from "@synapse-sdk/client";
 import { toSynapseError } from "@synapse-sdk/core";
 const SynapseContext = createContext(null);
-export function SynapseProvider({ node, children }) {
+/**
+ * Makes `node` the node of every hook below. With `useAuth` (Clerk's own `useAuth`, or `fakeAuth(token)`), the person
+ * signed in there is the node's (`node.setAuth`): signed in → the node asks the key server with their credential;
+ * signed out → `node.setAuth(undefined)`; not known yet → nothing; a different `userId` while signed in → a new sign-in. `useAuth` is a hook: pass it on every render or never.
+ * Signing out ends no live session.
+ */
+export function SynapseProvider({ node, useAuth, children }) {
+    const auth = useAuth?.();
+    const getToken = useRef(auth?.getToken);
+    getToken.current = auth?.getToken;
+    const loaded = auth?.isLoaded, signedIn = auth?.isSignedIn, userId = auth?.userId ?? undefined;
+    useEffect(() => {
+        if (!loaded)
+            return;
+        if (signedIn)
+            node.setAuth(() => getToken.current ? getToken.current() : Promise.resolve(null));
+        else
+            node.setAuth(undefined);
+    }, [node, loaded, signedIn, userId]);
     return createElement(SynapseContext.Provider, { value: node }, children);
 }
+/**
+ * A stand-in for Clerk's `useAuth` that is always signed in with `token` (a key-server credential such as the one
+ * `synapse login` keeps on your machine), for development and tests: `<SynapseProvider node={node} useAuth={fakeAuth(token)}>`.
+ * An empty `token` is signed out. Keep the token out of your source code (an environment variable).
+ */
+export function fakeAuth(token) {
+    const state = token ? { isLoaded: true, isSignedIn: true, getToken: async () => token } : { isLoaded: true, isSignedIn: false, getToken: async () => null };
+    return () => state;
+}
 export function useSynapse() {
     const node = useContext(SynapseContext);
     if (!node)
@@ -33,6 +60,21 @@ export function useCatalog() {
     const node = useSynapse();
     return useSyncExternalStore(useCallback((cb) => node.catalog.onChange(() => cb()), [node]), () => node.catalog.get(), () => node.catalog.get());
 }
+/**
+ * The signed-in person's clusters and their runtimes (`node.discovery`): `status` (`idle` with nobody signed in, `pending`,
+ * `success`, `error`), `data` (the key server's answer; still the last one on `error`), `error`, and `refresh()` to ask
+ * again. Asks the key server once when it shows `idle` and a person is signed in; every component using it shares one
+ * value and one request.
+ */
+export function useDiscover() {
+    const node = useSynapse();
+    const state = useSyncExternalStore(useCallback((cb) => node.discovery.onChange(() => cb()), [node]), () => node.discovery.get(), () => node.discovery.get());
+    // `idle` again after every `setAuth`: asked then (nobody signed in: refused, and it stays `idle`).
+    useEffect(() => { if (state.status === "idle")
+        node.discover().catch(() => { }); }, [node, state]);
+    const refresh = useCallback(() => { node.discover().catch(() => { }); }, [node]);
+    return { status: state.status, data: state.data, error: state.error, refresh };
+}
 /** The last `limit` notices (`node.notices`) since the component mounted, newest last. */
 export function useNotices(limit = 20) {
     const node = useSynapse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/react",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "description": "Synapse SDK React hooks: connection, topics, calls, services, store.",
   "type": "module",
   "sideEffects": false,
@@ -14,8 +14,8 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.4",
-    "@synapse-sdk/client": "0.3.4"
+    "@synapse-sdk/core": "0.3.7",
+    "@synapse-sdk/client": "0.3.7"
   },
   "peerDependencies": {
     "react": ">=18"