@synapse-sdk/client 0.3.4 → 0.3.7

package/dist/types.d.ts

@@ -40,7 +40,19 @@ export interface ConnectOptions {
 export interface ConnectTarget {
     /**
      * The runtime, `https://host:4470` (the path to dial is learned from the runtime at every attempt). Through a relay: the relay with
-     * the runtime's path, `https://relay:4443/runtimes/<runtime_id>`, and `token`. A `jwt=` in the URL is taken as the token.
+     * the runtime's path, `https://<relay>/cluster/<cluster>/runtimes/<runtime_id>`, and `token`. A `jwt=` in the URL is taken as the token.
+     *
+     * Or, in Bun/Node, a target as the CLI's `-t` names it (anything without `<scheme>://`): `"infra-1@devel"` (runtime `infra-1`
+     * of cluster `devel`), `"infra-1"` (in the default cluster), `"arm@medatech/devel"` (an org's cluster, by its slug). The relay
+     * URL and the token come from the CLI's files on this machine (`~/.synapse/cluster.toml` and the tokens beside it), read again
+     * at every attempt, so a token the CLI refreshed is used on the next reconnect (`token` given here wins). The SDK only reads
+     * those files: `synapse login` and `synapse cluster login <cluster>` first. A name this machine does not know is
+     * `invalid_input`, a missing or expired token `unauthorized`, each naming the CLI command that fixes it.
+     *
+     * With a person signed in (`node.setAuth`), in a browser or in Bun/Node, the same names are resolved through the key
+     * server instead, from your clusters: `"infra-1@devel"`, `"arm@medatech/devel"` (the cluster is always named). A name
+     * not in your clusters is `invalid_input`; nobody signed in, or a sign-in the key server does not take, `unauthorized`.
+     * In a browser with nobody signed in, a name is refused at once (`invalid_input`): sign in, or pass the relay URL and a token.
      */
     url: string;
     /** The type to declare there; left out keeps the node's current one. */
@@ -51,7 +63,7 @@ export interface ConnectTarget {
     userId?: string;
     /** The credential to present there; left out keeps the node's current one. Never printed. */
     credential?: string;
-    /** Pin of *this* broker's self-signed certificate (SHA-256 hex). Absent: `SYNAPSE_BROKER_CERT_SHA256`, then the broker's helper, then unpinned (per attempt). */
+    /** Pin of *this* runtime's self-signed certificate (SHA-256 hex). Absent: `SYNAPSE_BROKER_CERT_SHA256`, then, for a runtime URL (no path), its helper; a URL naming a root (a relay) connects unpinned against the system's roots (per attempt). */
     brokerCertSha256?: string;
     /** The relay token for *this* target; left out = no token (a token for another runtime would be refused). Never printed. */
     token?: string;
@@ -85,6 +97,42 @@ export type ConnectionState = {
     status: "failed";
     error: SynapseError;
 };
+/**
+ * Gives the signed-in person's credential for the key server, fetched each time the node asks it (`setAuth`);
+ * `null` or `undefined` means nobody is signed in.
+ */
+export type FetchToken = () => Promise<string | null | undefined>;
+/** The key server's answer about the signed-in person (`node.discover()`): the relay to dial and your clusters with their runtimes. */
+export interface Discovery {
+    /** The relay a runtime of these clusters is dialed through. */
+    relay: string;
+    /** The signed-in person. */
+    userId: string;
+    /** Your clusters: your own, and those of the organizations you belong to. */
+    clusters: {
+        id: string;
+        name: string;
+        /** Who owns it: `kind` `user` (yours) or `org`, its `id`, and the organization's `slug` when it has one. */
+        owner: {
+            kind: string;
+            id: string;
+            slug?: string;
+        };
+        /** How `connect()` names it: `name` for yours, `<slug>/<name>` (or `<org id>/<name>`) for an organization's: `"infra-1@" + label`. */
+        label: string;
+        /** Its runtimes, name → runtime id. */
+        runtimes: Record<string, string>;
+    }[];
+}
+/**
+ * `node.discovery`: `idle` with nobody signed in (or just after `setAuth`), `pending` while the key server is asked,
+ * `success` with the answer, `error` with why it failed (`data` still holds the last answer, if there was one).
+ */
+export interface DiscoveryState {
+    status: "idle" | "pending" | "success" | "error";
+    data?: Discovery;
+    error?: SynapseError;
+}
 /** This node's identity and the current session's hello facts; empty strings between sessions. */
 export interface Info {
     name: string;
@@ -230,27 +278,32 @@ export interface CallOptions<U = unknown> {
     /** Local: fail `idle_timeout` (and cancel) when no frame arrives for this long. */
     idleTimeoutMs?: number;
     signal?: AbortSignal;
+    /** The callback form: the SDK reads the updates and calls `onUpdate(u)` for each (the run's loop then has none); a throwing `onUpdate` is rethrown later and the reading goes on. */
     onUpdate?: (u: U) => void;
 }
-/** A started call (WP §8.3): its updates, its result, and cancel. */
-/** `await run` is `await run.result`. */
-export interface Run<U, R> extends AsyncDisposable, PromiseLike<R> {
+/**
+ * A started call (WP §8.3). Its progress is a stream, the run itself a promise:
+ * `for await (const u of run)` the updates until the run ended, `await run.next()` one update
+ * (`undefined` once the run ended), or `onUpdate` in the call options (the SDK reads them);
+ * `await run` (or `.then`/`.catch`) the result, rejecting with the `SynapseError` of a
+ * `failed` or `canceled` run; `cancel()`.
+ */
+export interface Run<U, R> extends AsyncDisposable, PromiseLike<R>, AsyncIterable<U> {
     readonly id: string;
     readonly status: RunStatus;
-    /** The next progress update; `undefined` once the terminal frame arrived (then `result`). */
-    nextUpdate(): Promise<U | undefined>;
-    updates(): AsyncIterable<U>;
+    /** The next progress update; `undefined` once the run ended (then `await run` settles at once). */
+    next(): Promise<U | undefined>;
+    /** `await run` / `.then` as on a promise (returns a `Promise`, so `.then(...).catch(...)` chains). */
+    then<A = R, B = never>(onfulfilled?: ((value: R) => A | PromiseLike<A>) | null, onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    /** The result as a plain promise (what `await run` waits for). */
     readonly result: Promise<R>;
+    /** `.catch` as on a promise: `onRejected` gets the run's `SynapseError` when it failed or was canceled. */
+    catch<B = never>(onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<R | B>;
+    /** `.finally` as on a promise: `onFinally` runs once the run ended, whichever way. */
+    finally(onFinally?: (() => void) | null): Promise<R>;
     /** Cooperative cancel: tells the broker, resolves on its `canceled` frame. */
     cancel(reason?: string): Promise<void>;
 }
-export type CallEvent<U, R> = {
-    type: "update";
-    data: U;
-} | {
-    type: "result";
-    data: R;
-};
 export interface ServeContext<U> {
     readonly call: string;
     readonly caller: string;
@@ -332,7 +385,7 @@ export interface StoreHandle extends AsyncDisposable {
     readonly synced: boolean;
     /** The handle's own state, a state value: `get()` now (the same object while unchanged), `onChange` for each change, `changed()` for the next. */
     readonly status: StateValue<StoreStatus>;
-    /** Resolves once the first value is in (the first snapshot applied, or the namespace absent). */
+    /** Resolves once the value is in: current as of the open (the version the runtime answered then applied), or the namespace absent. */
     ready(): Promise<void>;
     /** `set(key, value)`, or `set({ ... })` for several keys as one atomic write; resolves once `get()` shows it. */
     set(key: string, value: unknown): Promise<void>;
@@ -343,8 +396,9 @@ export interface StoreHandle extends AsyncDisposable {
     destroy(): Promise<void>;
     /** The whole value after each change; with `key`, that key's value each time it changes (`undefined` after a delete). */
     watch(key?: string): AsyncIterable<unknown>;
-    /** The whole value after its next change; `store_gone` once this handle is closed. */
+    /** The whole value after its next change; with `key`, that key's value after its next change (`undefined` after a delete). `store_gone` once this handle is closed. */
     changed(): Promise<Record<string, unknown>>;
+    changed(key: string): Promise<unknown>;
     /** `cb` with the whole value on every change of the value or the status (the framework bridge); returns the remover. */
     onChange(cb: (value: Record<string, unknown>) => void): () => void;
     close(): void;
@@ -441,7 +495,7 @@ export interface SceneEntity {
     kind: SceneKind;
     /**
      * Unique across every plane (authored, calibration, live): a write that would give an entity a name another entity
-     * holds is refused `name_taken`, its `data.holder` the id holding the name.
+     * holds is refused `name_taken`, its `data.holder` the id holding the name (`data.kind`, `data.layer`: the holder's).
      */
     name?: string;
     /** The parent's id; `null` is the world root. */
@@ -550,6 +604,9 @@ export interface SceneEntityView extends SceneView<SceneEntity | undefined> {
      */
     watch(): AsyncIterable<SceneEntity | undefined>;
     watch<K extends keyof SceneEntity & string>(component: K): AsyncIterable<SceneEntity[K] | undefined>;
+    /** The entity after its next change; with `component`, that component after its next change (`undefined` once gone). The value now once the handle ends. */
+    changed(): Promise<SceneEntity | undefined>;
+    changed<K extends keyof SceneEntity & string>(component: K): Promise<SceneEntity[K] | undefined>;
 }
 /** An entity view's authored plane (`view.authored`). Reads as the view does: nothing once the handle is detached or closed. */
 export interface EntityAuthored {
@@ -743,12 +800,14 @@ export interface SceneAuthored {
     patch(entity: string | SceneEntityView, set: Partial<SceneEntity>): Promise<void>;
     /**
      * A builder's one verb, keyed by `name`; resolves with the entity's view (by id: that entity) once the entities show
-     * it. No authored entity of that name: `spawn(kind, { name, parent, ...components })`. One of `kind`: its authored
-     * value is compared with what `patch(id, components)` would make of it (one-level merge; live overrides never
-     * count): equal, nothing is sent; else a patch of the components that differ. `parent` is used by the spawn only: an
-     * existing entity is not reparented. One of another kind, or a name a live entity holds: the spawn is sent and the
-     * runtime answers (`name_taken`, `data.holder`, while the name is held; the copy here may be stale). An `id`
-     * component: `invalid_input` (`data: { component: "id" }`), nothing sent.
+     * it. The id is the runtime's answer, never the copy's: `spawn(kind, { name, parent, ...components })` (a fresh id) is
+     * sent first; the runtime refusing it `name_taken` names the holder and its kind (`data.holder`, `data.kind`,
+     * `data.layer`). A holder of this kind in the authored or calibration layer is patched with the components that differ
+     * from what the copy shows of it (one-level merge; live overrides never count; all of them when the copy does not show
+     * it yet; equal, nothing more is sent): the copy only trims the patch, it never decides. A holder of another kind, a
+     * live one, or an answer without them: the `name_taken` as it came. `parent` is used by the spawn only: an existing
+     * entity is not reparented. Any other refusal as it came (`not_found` on the patch: the entity went meanwhile; upsert
+     * again). An `id` component: `invalid_input` (`data: { component: "id" }`), nothing sent.
      */
     upsert(kind: SceneKind, opts: SceneSpawnOptions & {
         id?: never;
@@ -817,7 +876,7 @@ export interface SceneHandle extends AsyncDisposable {
     readonly status: StateValue<SceneStatus>;
     /** The one boolean a node author checks: `status.get().synced`. */
     readonly synced: boolean;
-    /** Resolves once the handle is attached (at once if it is); `not_connected` once the handle is closed. No timeout: pass an `AbortSignal` to what awaits it, or race it. */
+    /** Resolves once the handle is attached (at once if it is): the copy current as of the attach, at the version the runtime answered when the scene was opened, or past it; `not_connected` once the handle is closed. No timeout: pass an `AbortSignal` to what awaits it, or race it. */
     ready(): Promise<void>;
     /** The entities after their next change (state, not history); `not_connected` once the handle is closed. */
     changed(): Promise<Readonly<Record<string, SceneEntity>>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "description": "Synapse SDK client: connect a node to the runtime; topics, services, calls, store, video.",
   "type": "module",
   "sideEffects": false,
@@ -14,8 +14,9 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.4",
-    "@moq/net": "0.4.2"
+    "@synapse-sdk/core": "0.3.7",
+    "@moq/net": "0.4.2",
+    "smol-toml": "1.9.0"
   },
   "peerDependencies": {
     "@moq/web-transport": "0.1.5"