@synapse-sdk/client 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @synapse-sdk/client
+
+Isomorphic TypeScript SDK for the **Synapse** robotics bus (Phoenix Channels). Browser,
+Bun, Node, Deno, edge. The companion to `python_client` — same model (call / stream /
+subscribe / publish / provide, realm-prefixed addresses), idiomatic TypeScript.
+
+```sh
+# internal (git) for now:
+bun add github:<org>/<repo>        # or: pnpm add github:<org>/<repo>
+```
+
+Imports: `@synapse-sdk/client` (core) and `@synapse-sdk/client/react` (hooks; React is an
+optional peer dependency).
+
+> Built for robot control and HMIs, where a stale or still-open socket is a safety hazard.
+> So we **own the connection lifecycle** (a single, verified socket) and reuse the installed
+> `phoenix` package only for the wire serializer.
+
+## The safety invariant
+
+> **At most one socket is ever acted upon.** A new socket is never created until the previous
+> one's `close` is confirmed (healthy switch) or it's been fenced and abandoned (dead socket).
+
+Three mechanics enforce it (`src/connection.ts`):
+
+1. **Serialized reconcile** — `connect`/`disconnect` set a *desired target*; one queue
+   converges to it, latest wins. Mashing the connect button coalesces.
+2. **Generation + live-identity guards** — every socket event checks it belongs to the
+   current desired-epoch *and* the current socket, so a late message/close from a superseded
+   or replaced socket is inert.
+3. **Verified teardown** — switching awaits the real `close` (with a force-fence timeout)
+   before any new socket opens. Dead sockets (heartbeat timeout) are fenced and abandoned —
+   never awaited, never read from or written to again.
+
+No `window` coupling, so discarding a socket is clean. The fuzz test runs 100 random
+connect/disconnect/retarget ops and asserts simultaneously-open sockets never exceeds **1**.
+
+## Quick start
+
+```ts
+import { Synapse } from "@synapse-sdk/client"
+
+const synapse = new Synapse() // browser/Bun: uses the built-in WebSocket
+
+// declarative, idempotent target — the "connect button" calls this
+await synapse.connect({
+  url: "wss://robot-7.tail.ts.net/runtime/api/v1/socket",
+  params: { type: "web" },
+  token: () => auth.getToken(), // → Phoenix auth subprotocol, fresh on every (re)connect
+})
+await synapse.connect({ url: "wss://robot-9/…", token }) // retarget: same verb, safe switch
+await synapse.disconnect()
+
+synapse.subscribeState((s) => render(s.status)) // idle|connecting|connected|reconnecting|closing|error
+
+// consume — mirrors the Python node
+const sum = await synapse.call("rosbridge:/add_two_ints", { a: 2, b: 3 }, { onUpdate: show, signal })
+for await (const ev of synapse.callStream("planner/plan", req)) { /* ev.type: update|result */ }
+synapse.subscribe("telemetry/pose", (m) => render(m))
+await synapse.publish("teleop/cmd_vel", axes)
+
+// provide — from any node, including the browser (the robot calls in)
+synapse.service("teleop/joystick", (input, ctx) => drive(input))
+```
+
+### three.js / react-three-fiber (no React re-renders)
+
+High-frequency data bypasses React entirely via `latest()` — read `.get()` in the render loop:
+
+```ts
+const joints = synapse.latest("rosbridge:/joint_states", { opts: { type: "sensor_msgs/JointState" } })
+useFrame(() => {
+  const s = joints.get()              // non-reactive, latest-wins (no queue growth)
+  if (s) robotRef.current?.setJointValues(toMap(s.name, s.position))
+})
+```
+
+Connection *status* (low-frequency) drives UI through a selector hook; robot *data*
+(high-frequency) drives the scene imperatively. React stays quiet at 60 Hz.
+
+## Layout (single package)
+
+```
+src/
+  connection.ts   single-socket state machine — the safety core
+  channel.ts      one topic on the connection (join/push/request/on, auto-rejoin)
+  serializer.ts   wraps the installed `phoenix` Serializer (v2 text + binary frames)
+  node.ts         Synapse — the bus verbs (call/callStream/subscribe/publish/service/latest)
+  address.ts      realm-prefix parsing (`rosbridge:/x` → { realm, name })
+  errors.ts       ConnectionError / SupersededError / ChannelError / BusError
+  types.ts        public types
+  index.ts        barrel
+test/             bun:test — connection (fuzz/invariant), channel, node
+```
+
+## Develop
+
+```bash
+bun install
+bun test                     # invariant fuzz, channel, call/subscribe/publish/provider
+bun examples/live_demo.ts    # end-to-end against a running runtime on :9001
+bunx tsc --noEmit            # type-check
+```
+
+## Status & roadmap
+
+- [x] Single-socket connection core — fuzz-proven invariant
+- [x] Bus verbs: `call` / `callStream` / `subscribe` / `publish` / `service` / `latest`
+- [x] Wire frames reconciled against the live Elixir `ServiceChannel` / `PubSubChannel`
+- [ ] React adapter — `useConnectionStatus` / `useSubscription` / `useService` + zustand
+- [ ] System-channel handshake as the default `verify` (server role → verified `connected`)
+- [ ] State mirrors (`synapse:state:*`) + discovery (`synapse:catalog`)
+```

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { A as SynapseOptions, C as ServiceCard, D as StreamEvent, E as StateDiff, F as VerifyFn, I as VerifyHandle, L as WebSocketCtor, M as SystemState, N as Target, O as SubscribeOptions, P as TokenInput, R as WebSocketLike, S as Serializer, T as ServiceRegistration, _ as Message, a as Channel, b as Reply, c as CallOptions, d as ConnectTarget, f as ConnectionOptions, g as Logger, h as Frame, i as Connection, j as SystemRole, k as Subscription, l as CatalogChange, m as ConnectionStatus, n as StateHandle, o as ChannelHandler, p as ConnectionState, r as Synapse, s as CallContext, t as LatestValue, u as ChannelHost, v as Params, w as ServiceHandler, x as ResourceInfo, y as ParamsInput } from "./node-DbD7G0Nx.js";
+
+//#region src/serializer.d.ts
+/**
+ * The wire serializer — the **installed** Phoenix `Serializer` (v2 text + binary frames),
+ * wrapped to our `Serializer` interface so wire-compat tracks the `phoenix` package. Its
+ * `encode`/`decode` are callback-style but synchronous, so we capture the result inline.
+ */
+declare const serializer: Serializer;
+//#endregion
+//#region src/address.d.ts
+interface Address {
+  realm: string;
+  name: string;
+}
+/**
+ * Split a `[realm:]name` address into `{ realm, name }`; default realm `synapse`.
+ * Only a bare-identifier prefix counts as a realm, so a synapse name with `/` and no realm
+ * passes through unchanged. Mirrors the Python client.
+ *
+ *   "camera/capture"          -> { realm: "synapse",   name: "camera/capture" }
+ *   "rosbridge:/add_two_ints" -> { realm: "rosbridge", name: "/add_two_ints" }
+ */
+declare function address(addr: string): Address;
+//#endregion
+//#region src/errors.d.ts
+declare class ConnectionError extends Error {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+declare class TimeoutError extends ConnectionError {
+  constructor(message: string);
+}
+/** A newer `connect(...)` (or `disconnect()`) replaced the target this promise was awaiting. */
+declare class SupersededError extends ConnectionError {
+  constructor();
+}
+declare class ChannelError extends Error {
+  topic: string;
+  response: unknown;
+  constructor(topic: string, message: string, response?: unknown);
+}
+interface BusErrorPayload {
+  code?: string;
+  message?: string;
+}
+/**
+ * Known bus error codes — server-emitted (`unauthorized`, `service_unavailable`,
+ * `provider_error`, `invalid_input`, `unknown_event`, `ros_error`) plus client-side
+ * (`bad_ack`, `not_connected`, `timeout`, `cancelled`). Match on these to avoid magic
+ * strings; treat the set as **non-exhaustive** (the server may add codes).
+ */
+declare const BusErrorCode: {
+  readonly Unauthorized: "unauthorized";
+  readonly ServiceUnavailable: "service_unavailable";
+  readonly ProviderError: "provider_error";
+  readonly InvalidInput: "invalid_input";
+  readonly UnknownEvent: "unknown_event";
+  readonly RosError: "ros_error";
+  readonly BadAck: "bad_ack";
+  readonly NotConnected: "not_connected";
+  readonly Timeout: "timeout";
+  readonly Cancelled: "cancelled";
+};
+type BusErrorCode = (typeof BusErrorCode)[keyof typeof BusErrorCode];
+/** Raised when a service call fails — at accept time or mid-flight (see the bus error model). */
+declare class BusError extends Error {
+  code: string;
+  detail: unknown;
+  constructor(error: BusErrorPayload | unknown);
+}
+//#endregion
+export { type Address, BusError, BusErrorCode, type BusErrorPayload, type CallContext, type CallOptions, type CatalogChange, Channel, ChannelError, type ChannelHandler, type ChannelHost, type ConnectTarget, Connection, ConnectionError, type ConnectionOptions, type ConnectionState, type ConnectionStatus, type Frame, LatestValue, type Logger, type Message, type Params, type ParamsInput, type Reply, type ResourceInfo, type Serializer, type ServiceCard, type ServiceHandler, type ServiceRegistration, type StateDiff, StateHandle, type StreamEvent, type SubscribeOptions, type Subscription, SupersededError, Synapse, type SynapseOptions, SystemRole, type SystemState, type Target, TimeoutError, type TokenInput, type VerifyFn, type VerifyHandle, type WebSocketCtor, type WebSocketLike, address, serializer };

package/dist/index.js

@@ -0,0 +1,15 @@
+import { a as Connection, c as BusError, d as ConnectionError, f as SupersededError, i as address, l as BusErrorCode, n as StateHandle, o as serializer, p as TimeoutError, r as Synapse, s as Channel, t as LatestValue, u as ChannelError } from "./node-CSSIXG4k.js";
+//#region src/types.ts
+/**
+* Server-assigned session role from the `synapse:system` handshake. **Open-ended** — the
+* server may assign roles beyond these (the Python node already has `agent`), so the type is
+* any string; the constants are just for ergonomic, typo-safe comparison
+* (`role === SystemRole.Controller`). Add entries here as the server grows.
+*/
+const SystemRole = {
+	Viewer: "viewer",
+	Controller: "controller",
+	Agent: "agent"
+};
+//#endregion
+export { BusError, BusErrorCode, Channel, ChannelError, Connection, ConnectionError, LatestValue, StateHandle, SupersededError, Synapse, SystemRole, TimeoutError, address, serializer };