@graphorin/client 0.5.0

package/dist/transport/ws.js

@@ -0,0 +1,149 @@
+import { AuthFailedError, InvalidServerFrameError, ProtocolViolationError, SubprotocolMismatchError, TransportFailedError } from "../errors.js";
+import { SUBPROTOCOL_NAME, ServerMessageSchema, closeCodeReason, formatTicketSubprotocol, isErrorFrame } from "@graphorin/protocol";
+
+//#region src/transport/ws.ts
+/**
+* WebSocket transport for the {@link GraphorinClient}. Speaks the
+* `graphorin.protocol.v1` subprotocol; honours the browser ticket
+* flow when the auth strategy is `'ticket'`.
+*
+* @packageDocumentation
+*/
+const STATE_CONNECTING = 0;
+const STATE_OPEN = 1;
+/**
+* Open a WebSocket transport. Resolves once the underlying socket
+* fires `open` (i.e. the upgrade succeeded + the subprotocol matches
+* `SUBPROTOCOL_NAME`); rejects with a typed
+* {@link TransportFailedError} / {@link SubprotocolMismatchError} /
+* {@link AuthFailedError} otherwise.
+*
+* @stable
+*/
+async function openWebSocketTransport(options, listeners) {
+	const WebSocketImpl = options.WebSocket ?? globalThis.WebSocket;
+	if (typeof WebSocketImpl !== "function") throw new TransportFailedError("No WebSocket implementation found. Pass `WebSocket` via the transport options or run on a runtime that ships one (Node 22+, modern browsers).");
+	const subprotocols = [SUBPROTOCOL_NAME];
+	if (options.auth.kind === "ticket") {
+		const ticket = await options.auth.ticketProvider();
+		subprotocols.push(formatTicketSubprotocol(ticket));
+	}
+	let socket;
+	if (options.auth.kind === "bearer") {
+		const Ctor = WebSocketImpl;
+		try {
+			socket = new Ctor(options.url, subprotocols, { headers: { Authorization: `Bearer ${options.auth.token}` } });
+		} catch {
+			try {
+				socket = new WebSocketImpl(options.url, subprotocols);
+			} catch (cause) {
+				throw new TransportFailedError(`Failed to construct WebSocket for '${options.url}'.`, cause instanceof Error ? { cause } : {});
+			}
+		}
+	} else try {
+		socket = new WebSocketImpl(options.url, subprotocols);
+	} catch (cause) {
+		throw new TransportFailedError(`Failed to construct WebSocket for '${options.url}'.`, cause instanceof Error ? { cause } : {});
+	}
+	let lastEventId;
+	let closeFired = false;
+	let openFired = false;
+	return await new Promise((resolve, reject) => {
+		const fail = (err) => {
+			if (!openFired) {
+				cleanup();
+				reject(err);
+			} else listeners.onError(err);
+		};
+		const cleanup = () => {
+			socket.removeEventListener("open", onOpen);
+			socket.removeEventListener("message", onMessage);
+			socket.removeEventListener("error", onError);
+			socket.removeEventListener("close", onClose);
+		};
+		const onOpen = () => {
+			const negotiated = socket.protocol;
+			if (negotiated !== SUBPROTOCOL_NAME) {
+				socket.close(4008, "protocol.violation");
+				fail(new SubprotocolMismatchError(SUBPROTOCOL_NAME, negotiated || null));
+				return;
+			}
+			openFired = true;
+			listeners.onOpen();
+			resolve({
+				kind: "ws",
+				url: options.url,
+				send(frame) {
+					if (socket.readyState !== STATE_OPEN) throw new TransportFailedError(`Cannot send: WebSocket is in state ${socket.readyState}.`);
+					socket.send(JSON.stringify(frame));
+				},
+				close(code, reason) {
+					if (socket.readyState !== STATE_CONNECTING && socket.readyState !== STATE_OPEN) return;
+					socket.close(code, reason);
+				},
+				get lastEventId() {
+					return lastEventId;
+				}
+			});
+		};
+		const onMessage = (event) => {
+			const raw = typeof event.data === "string" ? event.data : "";
+			let payload;
+			try {
+				payload = JSON.parse(raw);
+			} catch {
+				fail(new ProtocolViolationError("Server sent a non-JSON frame."));
+				return;
+			}
+			const parsed = ServerMessageSchema.safeParse(payload);
+			if (!parsed.success) {
+				fail(new InvalidServerFrameError("Server frame failed schema validation.", parsed.error.issues.map((i) => ({
+					path: i.path,
+					message: i.message
+				}))));
+				return;
+			}
+			const frame = parsed.data;
+			if ("kind" in frame && frame.kind === "event") lastEventId = frame.eventId;
+			if (isErrorFrame(frame) && frame.fatal === true) {
+				listeners.onFrame(frame);
+				if (frame.code.startsWith("auth.")) fail(new AuthFailedError(frame.message));
+				return;
+			}
+			listeners.onFrame(frame);
+		};
+		const onError = () => {
+			fail(new TransportFailedError("WebSocket error event fired."));
+		};
+		const onClose = (event) => {
+			if (closeFired) return;
+			closeFired = true;
+			cleanup();
+			const graphorinReason = closeCodeReason(event.code);
+			const reasonRecord = {
+				code: event.code,
+				reason: event.reason,
+				wasClean: event.wasClean,
+				...graphorinReason !== void 0 ? { graphorinReason } : {}
+			};
+			if (!openFired) {
+				const codeReason = closeCodeReason(event.code);
+				if (codeReason?.startsWith("auth.") === true) {
+					fail(new AuthFailedError(event.reason || codeReason));
+					return;
+				}
+				fail(new TransportFailedError(event.reason || "WebSocket closed before open."));
+				return;
+			}
+			listeners.onClose(reasonRecord);
+		};
+		socket.addEventListener("open", onOpen);
+		socket.addEventListener("message", onMessage);
+		socket.addEventListener("error", onError);
+		socket.addEventListener("close", onClose);
+	});
+}
+
+//#endregion
+export { openWebSocketTransport };
+//# sourceMappingURL=ws.js.map

package/dist/transport/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","names":["subprotocols: string[]","socket: WebSocket","lastEventId: string | undefined","payload: unknown","reasonRecord: TransportCloseReason"],"sources":["../../src/transport/ws.ts"],"sourcesContent":["/**\n * WebSocket transport for the {@link GraphorinClient}. Speaks the\n * `graphorin.protocol.v1` subprotocol; honours the browser ticket\n * flow when the auth strategy is `'ticket'`.\n *\n * @packageDocumentation\n */\n\nimport {\n  type ClientMessage,\n  closeCodeReason,\n  formatTicketSubprotocol,\n  isErrorFrame,\n  ServerMessageSchema,\n  SUBPROTOCOL_NAME,\n} from '@graphorin/protocol';\n\nimport {\n  AuthFailedError,\n  InvalidServerFrameError,\n  ProtocolViolationError,\n  SubprotocolMismatchError,\n  TransportFailedError,\n} from '../errors.js';\nimport type {\n  Transport,\n  TransportCloseReason,\n  TransportListeners,\n  TransportOptions,\n} from './types.js';\n\nconst STATE_CONNECTING = 0;\nconst STATE_OPEN = 1;\n\n/**\n * Open a WebSocket transport. Resolves once the underlying socket\n * fires `open` (i.e. the upgrade succeeded + the subprotocol matches\n * `SUBPROTOCOL_NAME`); rejects with a typed\n * {@link TransportFailedError} / {@link SubprotocolMismatchError} /\n * {@link AuthFailedError} otherwise.\n *\n * @stable\n */\nexport async function openWebSocketTransport(\n  options: TransportOptions,\n  listeners: TransportListeners,\n): Promise<Transport> {\n  const WebSocketImpl = options.WebSocket ?? globalThis.WebSocket;\n  if (typeof WebSocketImpl !== 'function') {\n    throw new TransportFailedError(\n      'No WebSocket implementation found. Pass `WebSocket` via the transport options or run on a runtime that ships one (Node 22+, modern browsers).',\n    );\n  }\n\n  const subprotocols: string[] = [SUBPROTOCOL_NAME];\n  if (options.auth.kind === 'ticket') {\n    const ticket = await options.auth.ticketProvider();\n    subprotocols.push(formatTicketSubprotocol(ticket));\n  }\n\n  // Bearer-token auth on Node SDKs is encoded as a custom header on\n  // the upgrade. The browser WebSocket API does not expose headers,\n  // so the SDK fallback path uses the ticket strategy instead. We\n  // try the 3-arg `new WebSocket(url, protocols, opts)` overload\n  // first (supported by `ws` on Node + most polyfills); if the\n  // implementation rejects it, we fall back to the 2-arg signature\n  // and rely on the server to surface auth failures via the close\n  // code (the only viable path on plain browser WebSocket).\n  let socket: WebSocket;\n  if (options.auth.kind === 'bearer') {\n    type WsCtorWithOptions = new (\n      url: string,\n      protocols: ReadonlyArray<string>,\n      options: { readonly headers: Readonly<Record<string, string>> },\n    ) => WebSocket;\n    const Ctor = WebSocketImpl as unknown as WsCtorWithOptions;\n    try {\n      socket = new Ctor(options.url, subprotocols, {\n        headers: { Authorization: `Bearer ${options.auth.token}` },\n      });\n    } catch {\n      try {\n        socket = new WebSocketImpl(options.url, subprotocols);\n      } catch (cause) {\n        throw new TransportFailedError(\n          `Failed to construct WebSocket for '${options.url}'.`,\n          cause instanceof Error ? { cause } : {},\n        );\n      }\n    }\n  } else {\n    try {\n      socket = new WebSocketImpl(options.url, subprotocols);\n    } catch (cause) {\n      throw new TransportFailedError(\n        `Failed to construct WebSocket for '${options.url}'.`,\n        cause instanceof Error ? { cause } : {},\n      );\n    }\n  }\n\n  let lastEventId: string | undefined;\n  let closeFired = false;\n  let openFired = false;\n  return await new Promise<Transport>((resolve, reject) => {\n    const fail = (err: Error): void => {\n      if (!openFired) {\n        cleanup();\n        reject(err);\n      } else {\n        listeners.onError(err);\n      }\n    };\n    const cleanup = (): void => {\n      socket.removeEventListener('open', onOpen);\n      socket.removeEventListener('message', onMessage);\n      socket.removeEventListener('error', onError);\n      socket.removeEventListener('close', onClose);\n    };\n    const onOpen = (): void => {\n      const negotiated = socket.protocol;\n      if (negotiated !== SUBPROTOCOL_NAME) {\n        socket.close(4008, 'protocol.violation');\n        fail(new SubprotocolMismatchError(SUBPROTOCOL_NAME, negotiated || null));\n        return;\n      }\n      openFired = true;\n      listeners.onOpen();\n      resolve({\n        kind: 'ws',\n        url: options.url,\n        send(frame: ClientMessage): void {\n          if (socket.readyState !== STATE_OPEN) {\n            throw new TransportFailedError(\n              `Cannot send: WebSocket is in state ${socket.readyState}.`,\n            );\n          }\n          socket.send(JSON.stringify(frame));\n        },\n        close(code?: number, reason?: string): void {\n          if (socket.readyState !== STATE_CONNECTING && socket.readyState !== STATE_OPEN) {\n            return;\n          }\n          socket.close(code, reason);\n        },\n        get lastEventId(): string | undefined {\n          return lastEventId;\n        },\n      });\n    };\n    const onMessage = (event: MessageEvent): void => {\n      const raw = typeof event.data === 'string' ? event.data : '';\n      let payload: unknown;\n      try {\n        payload = JSON.parse(raw);\n      } catch {\n        fail(new ProtocolViolationError('Server sent a non-JSON frame.'));\n        return;\n      }\n      const parsed = ServerMessageSchema.safeParse(payload);\n      if (!parsed.success) {\n        fail(\n          new InvalidServerFrameError(\n            'Server frame failed schema validation.',\n            parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),\n          ),\n        );\n        return;\n      }\n      const frame = parsed.data;\n      if ('kind' in frame && frame.kind === 'event') {\n        lastEventId = frame.eventId;\n      }\n      if (isErrorFrame(frame) && frame.fatal === true) {\n        listeners.onFrame(frame);\n        if (frame.code.startsWith('auth.')) fail(new AuthFailedError(frame.message));\n        return;\n      }\n      listeners.onFrame(frame);\n    };\n    const onError = (): void => {\n      fail(new TransportFailedError('WebSocket error event fired.'));\n    };\n    const onClose = (event: CloseEvent): void => {\n      if (closeFired) return;\n      closeFired = true;\n      cleanup();\n      const graphorinReason = closeCodeReason(event.code);\n      const reasonRecord: TransportCloseReason = {\n        code: event.code,\n        reason: event.reason,\n        wasClean: event.wasClean,\n        ...(graphorinReason !== undefined ? { graphorinReason } : {}),\n      };\n      if (!openFired) {\n        const codeReason = closeCodeReason(event.code);\n        if (codeReason?.startsWith('auth.') === true) {\n          fail(new AuthFailedError(event.reason || codeReason));\n          return;\n        }\n        fail(new TransportFailedError(event.reason || 'WebSocket closed before open.'));\n        return;\n      }\n      listeners.onClose(reasonRecord);\n    };\n    socket.addEventListener('open', onOpen);\n    socket.addEventListener('message', onMessage);\n    socket.addEventListener('error', onError);\n    socket.addEventListener('close', onClose);\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@graphorin/client",
+  "version": "0.5.0",
+  "description": "Reference TypeScript client for the Graphorin standalone server. Wraps the WebSocket subprotocol `graphorin.protocol.v1` (with the optional Server-Sent Events 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 (single-use ticket attached as a `ticket.<value>` `Sec-WebSocket-Protocol` token), exponential-backoff reconnect with `lastEventId` resume against the server replay buffer, and Zod-validated frame parsing on both directions. Browser-friendly: zero Node-only dependencies; the only runtime dependencies are `@graphorin/protocol` and `zod`. Created and maintained by Oleksiy Stepurenko.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "client",
+    "websocket",
+    "sse",
+    "browser-friendly",
+    "ticket-flow",
+    "reconnect"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/graphorin-client.d.ts",
+      "import": "./dist/graphorin-client.js"
+    },
+    "./transport": {
+      "types": "./dist/transport/index.d.ts",
+      "import": "./dist/transport/index.js"
+    },
+    "./reconnect": {
+      "types": "./dist/reconnect.d.ts",
+      "import": "./dist/reconnect.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "zod": "^3.25.0",
+    "@graphorin/protocol": "0.5.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "ws": "^8.20.1",
+    "@graphorin/security": "0.5.0",
+    "@graphorin/server": "0.5.0",
+    "@graphorin/store-sqlite": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}