@synapse-sdk/client 0.3.6 → 0.3.8

package/dist/types.d.ts

@@ -41,6 +41,18 @@ 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>/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;
@@ -440,6 +488,8 @@ export interface Hardpoint {
 /**
  * An entity of the scene. The fields below are the ones the runtime and the early users read;
  * every other key passes through untouched.
+ * A component is absent (none), `{}` (there, nothing specified yet: every field at its default) or
+ * specified; a null component or sub-key is never stored (a patch deletes the key it names, a spawn drops it).
  */
 export interface SceneEntity {
     /** A ULID; never changes. */
@@ -572,8 +622,8 @@ export interface EntityAuthored {
      * not have: its `not_found`). A view by name whose name no entity holds has no id to send to: `not_found`
      * (`data: { name }`), nothing sent. Detached: `project_inactive`.
      */
-    set<K extends keyof SceneEntity & string>(component: K, value: SceneEntity[K]): Promise<void>;
-    set(components: Partial<SceneEntity>): Promise<void>;
+    set<K extends keyof SceneEntity & string>(component: K, value: PatchSet[K]): Promise<void>;
+    set(components: PatchSet): Promise<void>;
 }
 /** An entity view's live plane (`view.live`). Reads as the view does: nothing once the handle is detached or closed. */
 export interface EntityLive {
@@ -618,6 +668,12 @@ export interface SceneStatus {
     /** Lane rows dropped because their id's claim was refused (rows parked while it was asked, and rows written while refused). */
     unclaimedDrops: number;
 }
+type NullSubKeys<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [S in keyof T]?: T[S] | null;
+} : T;
+type PatchSet = {
+    [K in keyof SceneEntity]?: unknown extends SceneEntity[K] ? unknown : NullSubKeys<NonNullable<SceneEntity[K]>> | null;
+};
 /** An authored change as the runtime applied it (a diff op of the scene's `authored` track). */
 export type SceneDiffOp = {
     op: "spawn";
@@ -631,7 +687,7 @@ export type SceneDiffOp = {
 } | {
     op: "patch";
     id: string;
-    set: Partial<SceneEntity>;
+    set: PatchSet;
     rev: number;
 } | {
     op: "reparent";
@@ -662,7 +718,7 @@ export type SceneOp = {
 } | {
     op: "patch";
     id: string;
-    set: Partial<SceneEntity>;
+    set: PatchSet;
 } | {
     op: "reparent";
     id: string;
@@ -685,20 +741,22 @@ export type SceneSpawnOptions = {
     parent?: string | SceneEntityView | null;
     id?: string;
 } & Partial<Omit<SceneEntity, "id" | "kind" | "name" | "parent" | "order" | "meta">>;
-/** Where `reparent` puts the entity among its new siblings (default: after the last): a sibling by its id or its view. */
-export type ScenePlace = {
-    before: string | SceneEntityView;
-} | {
-    after: string | SceneEntityView;
-};
 /** One authoring batch being built (`txn`): sent as one atomic `apply`. An entity is named by its id or by a view of it (`upsert`'s result). */
 export interface SceneTxn {
     /** Spawns an entity of `kind`; returns its id. */
     spawn(kind: SceneKind, opts: SceneSpawnOptions): string;
-    /** Sets components of the entity (an object merges into an object one level deep). */
-    patch(entity: string | SceneEntityView, set: Partial<SceneEntity>): void;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: string | SceneEntityView, set: PatchSet): void;
     rename(entity: string | SceneEntityView, name: string): void;
-    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): void;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (its local xform is recomputed); `preserveWorld: false` keeps its local xform.
+     */
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, opts?: {
+        before?: string | SceneEntityView;
+        after?: string | SceneEntityView;
+        preserveWorld?: boolean;
+    }): void;
     despawn(entity: string | SceneEntityView, opts?: {
         cascade?: boolean;
     }): void;
@@ -749,7 +807,8 @@ export interface SceneAuthored {
     txn(build: (t: SceneTxn) => void): Promise<void>;
     /** Spawns an entity; its id, once the entities show it. */
     spawn(kind: SceneKind, opts: SceneSpawnOptions): Promise<string>;
-    patch(entity: string | SceneEntityView, set: Partial<SceneEntity>): Promise<void>;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: string | SceneEntityView, set: PatchSet): 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. The id is the runtime's answer, never the copy's: `spawn(kind, { name, parent, ...components })` (a fresh id) is
@@ -765,7 +824,16 @@ export interface SceneAuthored {
         id?: never;
     }): Promise<SceneEntityView>;
     rename(entity: string | SceneEntityView, name: string): Promise<void>;
-    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): Promise<void>;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default the entity keeps its world pose (its local xform is recomputed). With `preserveWorld: false` it keeps its
+     * local xform instead, so a tool moved to another flange snaps to it.
+     */
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, opts?: {
+        before?: string | SceneEntityView;
+        after?: string | SceneEntityView;
+        preserveWorld?: boolean;
+    }): Promise<void>;
     despawn(entity: string | SceneEntityView, opts?: {
         cascade?: boolean;
     }): Promise<void>;
@@ -976,6 +1044,21 @@ export interface Tasks {
     /** Stops every project task (also when none ran). Robot tasks are not touched. */
     stopProjectTasks(): Promise<void>;
 }
+/** The answer of `node.listProjects()` (`synapse/project/list`): every project the runtime has, sorted by id. */
+export interface ProjectListing {
+    projects: ProjectEntry[];
+}
+/** One project of a {@link ProjectListing}: what its document names (`name` when it has one), or why it cannot be read (`error`). */
+export type ProjectEntry = {
+    id: string;
+    name?: string;
+    scene_id: string;
+    store_id: string;
+    active: boolean;
+} | {
+    id: string;
+    error: string;
+};
 export interface Catalog {
     readonly topics: Readonly<Record<string, {
         desc?: TrackDesc;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "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.6",
-    "@moq/net": "0.4.2"
+    "@synapse-sdk/core": "0.3.8",
+    "@moq/net": "0.4.2",
+    "smol-toml": "1.9.0"
   },
   "peerDependencies": {
     "@moq/web-transport": "0.1.5"