@graphorin/client 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @graphorin/client
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial Phase 14b release: reference TypeScript client for the
+  Graphorin standalone server. Wraps the `graphorin.protocol.v1`
+  WebSocket subprotocol (with an optional SSE fallback for
+  proxy-restricted environments) behind an ergonomic
+  `GraphorinClient` class: `connect()`, `subscribe({ target, id })`
+  returning an async-iterable subscription, `cancel(runId, opts)`,
+  `resume(runId, directive)`, `ping()`, `disconnect()`. Handles the
+  browser ticket flow, exponential-backoff reconnect with replay
+  buffer resume, and Zod-validated frame parsing on both
+  directions. Browser-friendly: zero Node-only dependencies. Created
+  and maintained by Oleksiy Stepurenko.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @graphorin/client
+
+> Reference TypeScript client for the [Graphorin](https://github.com/o-stepper/graphorin) standalone server.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js: 22+](https://img.shields.io/badge/Node.js-22%2B-43853d.svg)](https://nodejs.org)
+
+- **Version:** v0.5.0
+- **License:** [MIT](./LICENSE) (© 2026 Oleksiy Stepurenko)
+- **Repository:** <https://github.com/o-stepper/graphorin/tree/main/packages/client>
+- **Issues:** <https://github.com/o-stepper/graphorin/issues>
+
+`@graphorin/client` is the reference TypeScript client for the Graphorin standalone server. It wraps the WebSocket subprotocol `graphorin.protocol.v1` (with an optional Server-Sent Events fallback for proxy-restricted environments) behind an ergonomic `GraphorinClient` class.
+
+## What ships in v0.1 (Phase 14b)
+
+| Capability | Detail |
+|---|---|
+| **WebSocket transport** | Honours the `graphorin.protocol.v1` subprotocol; supports both bearer-token (Node SDK) and ticket-flow (browser) authentication. |
+| **SSE fallback** | Read-only `EventSource` transport for environments that block WebSocket upgrades. Control-plane operations (`subscribe`, `cancel`, `resume`) fall back to REST. |
+| **Async-iterable subscriptions** | `for await (const event of sub.events())` — typed `AgentEvent` / `WorkflowEvent` payload via `@graphorin/protocol`. |
+| **Reconnect** | Exponential backoff with full jitter; resubscribes with the recorded `lastEventId` so the server replays buffered events. |
+| **Bundle hygiene** | Browser-friendly. Zero Node-only dependencies; runtime depends only on `@graphorin/protocol` and `zod`. |
+
+## Direct dependencies
+
+- [`@graphorin/protocol`](../protocol/README.md) — single source of truth for the wire format.
+- [`zod`](https://zod.dev) (`^3.25.0`) — schema validation re-exported transitively through `@graphorin/protocol`.
+
+## Install
+
+```bash
+pnpm add @graphorin/client @graphorin/protocol zod
+```
+
+> Other npm-registry-compatible package managers (`npm`, `yarn`, `bun`) work identically.
+
+## Usage
+
+```ts
+import { GraphorinClient } from '@graphorin/client';
+
+const client = new GraphorinClient({
+  baseUrl: 'wss://graphorin.example.com',
+  auth: { kind: 'bearer', token: process.env.GRAPHORIN_TOKEN ?? '' },
+  transport: 'auto', // try WebSocket first, fall back to SSE
+});
+
+await client.connect();
+
+const subscription = await client.subscribe({
+  target: 'agent',
+  id: 'echo',
+  runId: 'run-123',
+});
+
+for await (const event of subscription.events()) {
+  console.log(event.type, event.payload);
+}
+
+await client.cancel('run-123', { drain: false });
+await client.disconnect();
+```
+
+### Browser ticket flow
+
+```ts
+const client = new GraphorinClient({
+  baseUrl: 'https://graphorin.example.com',
+  auth: {
+    kind: 'ticket',
+    ticketProvider: async () => {
+      const res = await fetch('/v1/session/ws-ticket', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${browserToken}` },
+      });
+      const body = (await res.json()) as { ticket: string };
+      return body.ticket;
+    },
+  },
+});
+```
+
+The client attaches the ticket as a second `Sec-WebSocket-Protocol` token (`ticket.<value>`), per the wire contract documented in [`@graphorin/protocol`](../protocol/README.md).
+
+## License
+
+MIT © 2026 Oleksiy Stepurenko. See [`LICENSE`](./LICENSE).
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/errors.d.ts

@@ -0,0 +1,81 @@
+//#region src/errors.d.ts
+/**
+ * Typed error hierarchy surfaced by `@graphorin/client`. Every error
+ * class extends the JavaScript built-in `Error` and exposes a stable
+ * `kind` discriminator so consumers can pattern-match without
+ * relying on `instanceof` (which behaves badly across module-system
+ * boundaries when the package is dual-loaded).
+ *
+ * @packageDocumentation
+ */
+/**
+ * IP-19: map a JSON-RPC error code from a server `RpcFailure` frame to the
+ * client's discriminated {@link GraphorinClientErrorKind}, so a rate-limited
+ * or scope-denied RPC is distinguishable from a genuine protocol violation.
+ */
+declare function kindForRpcCode(code: number): GraphorinClientErrorKind;
+/**
+ * Discriminator union of every error kind raised by the client.
+ *
+ * @stable
+ */
+type GraphorinClientErrorKind = 'client-not-connected' | 'transport-failed' | 'subprotocol-mismatch' | 'auth-failed' | 'protocol-violation' | 'subscription-not-found' | 'rate-limited' | 'scope-denied' | 'run-not-found' | 'server-error' | 'aborted' | 'invalid-server-frame';
+/**
+ * Base class for every error raised by `@graphorin/client`. Carries a
+ * stable {@link GraphorinClientErrorKind} discriminator and an
+ * optional `cause` chain.
+ *
+ * @stable
+ */
+declare class GraphorinClientError extends Error {
+  readonly kind: GraphorinClientErrorKind;
+  constructor(kind: GraphorinClientErrorKind, message: string, options?: ErrorOptions);
+}
+/** @stable */
+declare class ClientNotConnectedError extends GraphorinClientError {
+  constructor(message?: string);
+}
+/** @stable */
+declare class TransportFailedError extends GraphorinClientError {
+  readonly code: number | undefined;
+  constructor(message: string, options?: ErrorOptions & {
+    readonly code?: number;
+  });
+}
+/** @stable */
+declare class SubprotocolMismatchError extends GraphorinClientError {
+  readonly expected: string;
+  readonly actual: string | null;
+  constructor(expected: string, actual: string | null);
+}
+/** @stable */
+declare class AuthFailedError extends GraphorinClientError {
+  constructor(message?: string);
+}
+/** @stable */
+declare class ProtocolViolationError extends GraphorinClientError {
+  constructor(message: string, options?: ErrorOptions);
+}
+/** @stable */
+declare class SubscriptionNotFoundError extends GraphorinClientError {
+  readonly subscriptionId: string;
+  constructor(subscriptionId: string);
+}
+/** @stable */
+declare class ClientAbortedError extends GraphorinClientError {
+  constructor(message?: string);
+}
+/** @stable */
+declare class InvalidServerFrameError extends GraphorinClientError {
+  readonly issues: ReadonlyArray<{
+    path: ReadonlyArray<string | number>;
+    message: string;
+  }>;
+  constructor(message: string, issues: ReadonlyArray<{
+    path: ReadonlyArray<string | number>;
+    message: string;
+  }>);
+}
+//#endregion
+export { AuthFailedError, ClientAbortedError, ClientNotConnectedError, GraphorinClientError, GraphorinClientErrorKind, InvalidServerFrameError, ProtocolViolationError, SubprotocolMismatchError, SubscriptionNotFoundError, TransportFailedError, kindForRpcCode };
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;AAiBA;AA2BA;AAuBA;;;;;;AAWA;AAQA;AAWA;AAgBA;AAQA;AAQa,iBAhHG,cAAA,CAgHuB,IAAQ,EAAA,MAAA,CAAA,EAhHD,wBAgHqB;AAcnE;AAQA;;;;AAKY,KAhHA,wBAAA,GAgHA,sBAAA,GAAA,kBAAA,GAAA,sBAAA,GAAA,aAAA,GAAA,oBAAA,GAAA,wBAAA,GAAA,cAAA,GAAA,cAAA,GAAA,eAAA,GAAA,cAAA,GAAA,SAAA,GAAA,sBAAA;;;;;;;;cAzFC,oBAAA,SAA6B,KAAA;iBACzB;oBAEG,qDAAoD;;;cAQ3D,uBAAA,SAAgC,oBAAA;;;;cAQhC,oBAAA,SAA6B,oBAAA;;yCAGF;;;;;cAQ3B,wBAAA,SAAiC,oBAAA;;;;;;cAgBjC,eAAA,SAAwB,oBAAA;;;;cAQxB,sBAAA,SAA+B,oBAAA;yCACJ;;;cAO3B,yBAAA,SAAkC,oBAAA;;;;;cAclC,kBAAA,SAA2B,oBAAA;;;;cAQ3B,uBAAA,SAAgC,oBAAA;mBAC1B;UAAsB;;;uCAI7B;UAAsB"}

package/dist/errors.js

@@ -0,0 +1,114 @@
+import { RPC_ERROR_CODES } from "@graphorin/protocol";
+
+//#region src/errors.ts
+/**
+* Typed error hierarchy surfaced by `@graphorin/client`. Every error
+* class extends the JavaScript built-in `Error` and exposes a stable
+* `kind` discriminator so consumers can pattern-match without
+* relying on `instanceof` (which behaves badly across module-system
+* boundaries when the package is dual-loaded).
+*
+* @packageDocumentation
+*/
+/**
+* IP-19: map a JSON-RPC error code from a server `RpcFailure` frame to the
+* client's discriminated {@link GraphorinClientErrorKind}, so a rate-limited
+* or scope-denied RPC is distinguishable from a genuine protocol violation.
+*/
+function kindForRpcCode(code) {
+	switch (code) {
+		case RPC_ERROR_CODES.RATE_LIMITED: return "rate-limited";
+		case RPC_ERROR_CODES.SCOPE_DENIED: return "scope-denied";
+		case RPC_ERROR_CODES.AUTH_REQUIRED:
+		case RPC_ERROR_CODES.AUTH_INVALID: return "auth-failed";
+		case RPC_ERROR_CODES.RUN_NOT_FOUND: return "run-not-found";
+		case RPC_ERROR_CODES.SUBSCRIPTION_NOT_FOUND: return "subscription-not-found";
+		case RPC_ERROR_CODES.INTERNAL_ERROR: return "server-error";
+		default: return "protocol-violation";
+	}
+}
+/**
+* Base class for every error raised by `@graphorin/client`. Carries a
+* stable {@link GraphorinClientErrorKind} discriminator and an
+* optional `cause` chain.
+*
+* @stable
+*/
+var GraphorinClientError = class extends Error {
+	kind;
+	constructor(kind, message, options = {}) {
+		super(message, options);
+		this.kind = kind;
+		this.name = "GraphorinClientError";
+	}
+};
+/** @stable */
+var ClientNotConnectedError = class extends GraphorinClientError {
+	constructor(message = "GraphorinClient is not connected. Call connect() first.") {
+		super("client-not-connected", message);
+		this.name = "ClientNotConnectedError";
+	}
+};
+/** @stable */
+var TransportFailedError = class extends GraphorinClientError {
+	code;
+	constructor(message, options = {}) {
+		super("transport-failed", message, options);
+		this.name = "TransportFailedError";
+		this.code = options.code;
+	}
+};
+/** @stable */
+var SubprotocolMismatchError = class extends GraphorinClientError {
+	expected;
+	actual;
+	constructor(expected, actual) {
+		super("subprotocol-mismatch", `Server selected subprotocol '${actual ?? "<none>"}'; expected '${expected}'.`);
+		this.name = "SubprotocolMismatchError";
+		this.expected = expected;
+		this.actual = actual;
+	}
+};
+/** @stable */
+var AuthFailedError = class extends GraphorinClientError {
+	constructor(message = "Authentication failed. Re-mint a token or request a new ticket.") {
+		super("auth-failed", message);
+		this.name = "AuthFailedError";
+	}
+};
+/** @stable */
+var ProtocolViolationError = class extends GraphorinClientError {
+	constructor(message, options = {}) {
+		super("protocol-violation", message, options);
+		this.name = "ProtocolViolationError";
+	}
+};
+/** @stable */
+var SubscriptionNotFoundError = class extends GraphorinClientError {
+	subscriptionId;
+	constructor(subscriptionId) {
+		super("subscription-not-found", `Subscription '${subscriptionId}' is not active on this client.`);
+		this.name = "SubscriptionNotFoundError";
+		this.subscriptionId = subscriptionId;
+	}
+};
+/** @stable */
+var ClientAbortedError = class extends GraphorinClientError {
+	constructor(message = "Operation aborted before completion.") {
+		super("aborted", message);
+		this.name = "ClientAbortedError";
+	}
+};
+/** @stable */
+var InvalidServerFrameError = class extends GraphorinClientError {
+	issues;
+	constructor(message, issues) {
+		super("invalid-server-frame", message);
+		this.name = "InvalidServerFrameError";
+		this.issues = issues;
+	}
+};
+
+//#endregion
+export { AuthFailedError, ClientAbortedError, ClientNotConnectedError, GraphorinClientError, InvalidServerFrameError, ProtocolViolationError, SubprotocolMismatchError, SubscriptionNotFoundError, TransportFailedError, kindForRpcCode };
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Typed error hierarchy surfaced by `@graphorin/client`. Every error\n * class extends the JavaScript built-in `Error` and exposes a stable\n * `kind` discriminator so consumers can pattern-match without\n * relying on `instanceof` (which behaves badly across module-system\n * boundaries when the package is dual-loaded).\n *\n * @packageDocumentation\n */\n\nimport { RPC_ERROR_CODES } from '@graphorin/protocol';\n\n/**\n * IP-19: map a JSON-RPC error code from a server `RpcFailure` frame to the\n * client's discriminated {@link GraphorinClientErrorKind}, so a rate-limited\n * or scope-denied RPC is distinguishable from a genuine protocol violation.\n */\nexport function kindForRpcCode(code: number): GraphorinClientErrorKind {\n  switch (code) {\n    case RPC_ERROR_CODES.RATE_LIMITED:\n      return 'rate-limited';\n    case RPC_ERROR_CODES.SCOPE_DENIED:\n      return 'scope-denied';\n    case RPC_ERROR_CODES.AUTH_REQUIRED:\n    case RPC_ERROR_CODES.AUTH_INVALID:\n      return 'auth-failed';\n    case RPC_ERROR_CODES.RUN_NOT_FOUND:\n      return 'run-not-found';\n    case RPC_ERROR_CODES.SUBSCRIPTION_NOT_FOUND:\n      return 'subscription-not-found';\n    case RPC_ERROR_CODES.INTERNAL_ERROR:\n      return 'server-error';\n    default:\n      // INVALID_REQUEST / INVALID_PARAMS / METHOD_NOT_FOUND / PROTOCOL_VIOLATION\n      // and any unknown code stay a protocol violation.\n      return 'protocol-violation';\n  }\n}\n\n/**\n * Discriminator union of every error kind raised by the client.\n *\n * @stable\n */\nexport type GraphorinClientErrorKind =\n  | 'client-not-connected'\n  | 'transport-failed'\n  | 'subprotocol-mismatch'\n  | 'auth-failed'\n  | 'protocol-violation'\n  | 'subscription-not-found'\n  // IP-19: discriminated RPC-failure kinds so callers can branch on the\n  // server's error class instead of pattern-matching the message string.\n  | 'rate-limited'\n  | 'scope-denied'\n  | 'run-not-found'\n  | 'server-error'\n  | 'aborted'\n  | 'invalid-server-frame';\n\n/**\n * Base class for every error raised by `@graphorin/client`. Carries a\n * stable {@link GraphorinClientErrorKind} discriminator and an\n * optional `cause` chain.\n *\n * @stable\n */\nexport class GraphorinClientError extends Error {\n  readonly kind: GraphorinClientErrorKind;\n\n  constructor(kind: GraphorinClientErrorKind, message: string, options: ErrorOptions = {}) {\n    super(message, options);\n    this.kind = kind;\n    this.name = 'GraphorinClientError';\n  }\n}\n\n/** @stable */\nexport class ClientNotConnectedError extends GraphorinClientError {\n  constructor(message = 'GraphorinClient is not connected. Call connect() first.') {\n    super('client-not-connected', message);\n    this.name = 'ClientNotConnectedError';\n  }\n}\n\n/** @stable */\nexport class TransportFailedError extends GraphorinClientError {\n  readonly code: number | undefined;\n\n  constructor(message: string, options: ErrorOptions & { readonly code?: number } = {}) {\n    super('transport-failed', message, options);\n    this.name = 'TransportFailedError';\n    this.code = options.code;\n  }\n}\n\n/** @stable */\nexport class SubprotocolMismatchError extends GraphorinClientError {\n  readonly expected: string;\n  readonly actual: string | null;\n\n  constructor(expected: string, actual: string | null) {\n    super(\n      'subprotocol-mismatch',\n      `Server selected subprotocol '${actual ?? '<none>'}'; expected '${expected}'.`,\n    );\n    this.name = 'SubprotocolMismatchError';\n    this.expected = expected;\n    this.actual = actual;\n  }\n}\n\n/** @stable */\nexport class AuthFailedError extends GraphorinClientError {\n  constructor(message = 'Authentication failed. Re-mint a token or request a new ticket.') {\n    super('auth-failed', message);\n    this.name = 'AuthFailedError';\n  }\n}\n\n/** @stable */\nexport class ProtocolViolationError extends GraphorinClientError {\n  constructor(message: string, options: ErrorOptions = {}) {\n    super('protocol-violation', message, options);\n    this.name = 'ProtocolViolationError';\n  }\n}\n\n/** @stable */\nexport class SubscriptionNotFoundError extends GraphorinClientError {\n  readonly subscriptionId: string;\n\n  constructor(subscriptionId: string) {\n    super(\n      'subscription-not-found',\n      `Subscription '${subscriptionId}' is not active on this client.`,\n    );\n    this.name = 'SubscriptionNotFoundError';\n    this.subscriptionId = subscriptionId;\n  }\n}\n\n/** @stable */\nexport class ClientAbortedError extends GraphorinClientError {\n  constructor(message = 'Operation aborted before completion.') {\n    super('aborted', message);\n    this.name = 'ClientAbortedError';\n  }\n}\n\n/** @stable */\nexport class InvalidServerFrameError extends GraphorinClientError {\n  readonly issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>;\n\n  constructor(\n    message: string,\n    issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>,\n  ) {\n    super('invalid-server-frame', message);\n    this.name = 'InvalidServerFrameError';\n    this.issues = issues;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,SAAgB,eAAe,MAAwC;AACrE,SAAQ,MAAR;EACE,KAAK,gBAAgB,aACnB,QAAO;EACT,KAAK,gBAAgB,aACnB,QAAO;EACT,KAAK,gBAAgB;EACrB,KAAK,gBAAgB,aACnB,QAAO;EACT,KAAK,gBAAgB,cACnB,QAAO;EACT,KAAK,gBAAgB,uBACnB,QAAO;EACT,KAAK,gBAAgB,eACnB,QAAO;EACT,QAGE,QAAO;;;;;;;;;;AAgCb,IAAa,uBAAb,cAA0C,MAAM;CAC9C,AAAS;CAET,YAAY,MAAgC,SAAiB,UAAwB,EAAE,EAAE;AACvF,QAAM,SAAS,QAAQ;AACvB,OAAK,OAAO;AACZ,OAAK,OAAO;;;;AAKhB,IAAa,0BAAb,cAA6C,qBAAqB;CAChE,YAAY,UAAU,2DAA2D;AAC/E,QAAM,wBAAwB,QAAQ;AACtC,OAAK,OAAO;;;;AAKhB,IAAa,uBAAb,cAA0C,qBAAqB;CAC7D,AAAS;CAET,YAAY,SAAiB,UAAqD,EAAE,EAAE;AACpF,QAAM,oBAAoB,SAAS,QAAQ;AAC3C,OAAK,OAAO;AACZ,OAAK,OAAO,QAAQ;;;;AAKxB,IAAa,2BAAb,cAA8C,qBAAqB;CACjE,AAAS;CACT,AAAS;CAET,YAAY,UAAkB,QAAuB;AACnD,QACE,wBACA,gCAAgC,UAAU,SAAS,eAAe,SAAS,IAC5E;AACD,OAAK,OAAO;AACZ,OAAK,WAAW;AAChB,OAAK,SAAS;;;;AAKlB,IAAa,kBAAb,cAAqC,qBAAqB;CACxD,YAAY,UAAU,mEAAmE;AACvF,QAAM,eAAe,QAAQ;AAC7B,OAAK,OAAO;;;;AAKhB,IAAa,yBAAb,cAA4C,qBAAqB;CAC/D,YAAY,SAAiB,UAAwB,EAAE,EAAE;AACvD,QAAM,sBAAsB,SAAS,QAAQ;AAC7C,OAAK,OAAO;;;;AAKhB,IAAa,4BAAb,cAA+C,qBAAqB;CAClE,AAAS;CAET,YAAY,gBAAwB;AAClC,QACE,0BACA,iBAAiB,eAAe,iCACjC;AACD,OAAK,OAAO;AACZ,OAAK,iBAAiB;;;;AAK1B,IAAa,qBAAb,cAAwC,qBAAqB;CAC3D,YAAY,UAAU,wCAAwC;AAC5D,QAAM,WAAW,QAAQ;AACzB,OAAK,OAAO;;;;AAKhB,IAAa,0BAAb,cAA6C,qBAAqB;CAChE,AAAS;CAET,YACE,SACA,QACA;AACA,QAAM,wBAAwB,QAAQ;AACtC,OAAK,OAAO;AACZ,OAAK,SAAS"}

package/dist/graphorin-client.d.ts

@@ -0,0 +1,180 @@
+import { BackoffPolicy } from "./reconnect.js";
+import { TransportAuth, TransportKind } from "./transport/types.js";
+import "./transport/index.js";
+import { ServerEventFrame } from "@graphorin/protocol";
+
+//#region src/graphorin-client.d.ts
+
+/**
+ * Discriminator for the subscription target. Mirrors the strict
+ * subject grammar enforced by the server:
+ *  - `'session'`/`<id>` ⇒ `'session:<id>/events'`
+ *  - `'agent'`/`<id>` + `runId` ⇒ `'agent:<id>/runs/<runId>/events'`
+ *  - `'run'`/`<runId>` ⇒ `'session:<sessionId>/runs/<runId>/events'`
+ *    (when `sessionId` is provided)
+ *  - `'workflow'`/`<id>` ⇒ `'workflow:<id>/events'`
+ *
+ * @stable
+ */
+type SubscriptionTarget = {
+  readonly target: 'session';
+  readonly id: string;
+} | {
+  readonly target: 'agent';
+  readonly id: string;
+  readonly runId: string;
+} | {
+  readonly target: 'run';
+  readonly runId: string;
+  readonly sessionId?: string;
+} | {
+  readonly target: 'workflow';
+  readonly id: string;
+};
+/**
+ * Transport selector. `'auto'` (default) attempts a WebSocket
+ * handshake first and falls back to SSE on failure.
+ *
+ * @stable
+ */
+type TransportPreference = TransportKind | 'auto';
+/**
+ * Public configuration accepted by {@link GraphorinClient}.
+ *
+ * @stable
+ */
+interface GraphorinClientOptions {
+  /**
+   * Session bound to the SSE fallback (IP-3): substituted into the
+   * `:sessionId` slot of `sseSessionPath`. Required to connect over
+   * SSE — the old client sent the literal template and could never
+   * receive an event.
+   */
+  readonly sessionId?: string;
+  /**
+   * Server base URL. Examples: `'wss://graphorin.example.com'` or
+   * `'http://localhost:8080'`. The path `/v1/ws` is appended for
+   * the WebSocket transport.
+   */
+  readonly baseUrl: string;
+  readonly auth: TransportAuth;
+  readonly transport?: TransportPreference;
+  /** Override the WS path (default `'/v1/ws'`). */
+  readonly wsPath?: string;
+  /**
+   * SSE path template. The placeholder `:sessionId` is replaced at
+   * subscribe time. Default: `'/v1/sessions/:sessionId/events'`.
+   * Required when the transport is `'sse'` or when the WS handshake
+   * fails on `'auto'`.
+   */
+  readonly sseSessionPath?: string;
+  readonly reconnect?: BackoffPolicy;
+  /** Inject a `WebSocket` constructor (Node SDKs / tests). */
+  readonly WebSocket?: typeof WebSocket;
+  /** Inject an `EventSource` constructor (Node SDKs / tests). */
+  readonly EventSource?: typeof EventSource;
+  /** Inject a `fetch` implementation (defaults to `globalThis.fetch`). */
+  readonly fetch?: typeof fetch;
+  /** Optional client identifier surfaced on diagnostics. */
+  readonly clientId?: string;
+  /**
+   * IP-19: per-RPC reply timeout in milliseconds. When set (and > 0), an RPC
+   * that receives no matching reply within this window rejects with a
+   * {@link TransportFailedError} instead of hanging forever on a
+   * non-responsive server. Default: unset — no timeout, so a legitimately
+   * slow server reply is never aborted (opt-in).
+   */
+  readonly rpcTimeoutMs?: number;
+}
+/**
+ * Snapshot returned by {@link Subscription.metadata}.
+ *
+ * @stable
+ */
+interface SubscriptionMetadata {
+  readonly id: string;
+  readonly subject: string;
+  readonly target: SubscriptionTarget;
+  readonly snapshotEventId: string | undefined;
+  readonly lastEventId: string | undefined;
+  readonly closed: boolean;
+}
+/**
+ * Public surface returned by {@link GraphorinClient.subscribe}.
+ *
+ * @stable
+ */
+interface Subscription {
+  readonly subscriptionId: string;
+  readonly subject: string;
+  events(): AsyncIterable<ServerEventFrame>;
+  /**
+   * Close the subscription on the server. Idempotent.
+   */
+  unsubscribe(): Promise<void>;
+  metadata(): SubscriptionMetadata;
+}
+/**
+ * @stable
+ */
+declare class GraphorinClient {
+  #private;
+  constructor(options: GraphorinClientOptions);
+  /**
+   * Open the underlying transport. Resolves once the server has
+   * accepted the handshake (`'open'`); rejects with a typed
+   * {@link GraphorinClientError} otherwise.
+   *
+   * Calling `connect()` while already connected is a no-op; calling
+   * it during another `connect()` returns the same promise.
+   */
+  connect(): Promise<void>;
+  /** Send a `ping` RPC and resolve when the server replies with `pong`. */
+  ping(): Promise<void>;
+  /**
+   * Subscribe to a server-side event stream. Resolves with a
+   * {@link Subscription} once the server confirms with the matching
+   * `subscribed` frame; rejects when the server returns an
+   * `error` instead.
+   */
+  subscribe(target: SubscriptionTarget, opts?: {
+    readonly sinceEventId?: string;
+  }): Promise<Subscription>;
+  /**
+   * Cancel a server-side run. Sends the `run.cancel` RPC and
+   * resolves with the server's `result` payload (typically
+   * `{ cancelled: true, partialStateAvailable: true }`).
+   */
+  cancel(runId: string, opts?: {
+    readonly drain?: boolean;
+    readonly reason?: string;
+    readonly onPendingApprovals?: 'deny' | 'preserve';
+  }): Promise<unknown>;
+  /**
+   * Resume a paused (HITL) run. The WebSocket protocol intentionally
+   * does NOT carry a `resume` control message — resumes are durable
+   * + idempotent + body-carrying, which maps onto the REST endpoint
+   * `POST /v1/runs/:runId/resume`. NOTE (IP-14): the server endpoint
+   * currently answers **501** — server-side durable resume is not
+   * implemented yet. Library-mode callers resume directly:
+   * `agent.run(result.state, { directive })`.
+   */
+  resume(runId: string, directive?: unknown, opts?: {
+    readonly idempotencyKey?: string;
+  }): Promise<unknown>;
+  /**
+   * Send an MCP-compatible cancellation notification. Does not wait
+   * for a server reply (notifications have no `id`).
+   */
+  cancelNotify(requestId: string): void;
+  /**
+   * Disconnect the underlying transport and abort every pending RPC
+   * + subscription. Idempotent.
+   */
+  disconnect(): Promise<void>;
+  /** Return the active transport kind (or `undefined` if not connected). */
+  get transportKind(): TransportKind | undefined;
+}
+//#endregion
+export { GraphorinClient, GraphorinClientOptions, Subscription, SubscriptionMetadata, SubscriptionTarget, TransportPreference };
+//# sourceMappingURL=graphorin-client.d.ts.map

package/dist/graphorin-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphorin-client.d.ts","names":[],"sources":["../src/graphorin-client.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;KAsEY,kBAAA;;;;;;;;;;;;;;;;;;;;;KAoBA,mBAAA,GAAsB;;;;;;UAOjB,sBAAA;;;;;;;;;;;;;;iBAcA;uBACM;;;;;;;;;;uBAUA;;8BAEO;;gCAEE;;0BAEN;;;;;;;;;;;;;;;;;UAkBT,oBAAA;;;mBAGE;;;;;;;;;;UAWF,YAAA;;;YAGL,cAAc;;;;iBAIT;cACH;;;;;cAmBD,eAAA;;uBAYU;;;;;;;;;aAeJ;;UAkCH;;;;;;;oBAWJ;;MAEP,QAAQ;;;;;;;;;;MAoER;;;;;;;;;;;;MA+BA;;;;;;;;;;gBA4DiB;;uBAwBC"}