@graphorin/protocol 0.5.0

package/dist/subprotocol.d.ts

@@ -0,0 +1,70 @@
+//#region src/subprotocol.d.ts
+/**
+ * Subprotocol identifier + negotiation helpers for the Graphorin
+ * WebSocket protocol.
+ *
+ * Clients announce supported subprotocols in the
+ * `Sec-WebSocket-Protocol` upgrade header. The server is expected to
+ * pick exactly one and echo it back; mismatches abort the handshake
+ * per RFC 6455 § 4. Browsers also accept additional comma-separated
+ * tokens — Graphorin uses this slot to attach a single-use ticket
+ * via the `ticket.<value>` form (the WebSocket browser API does not
+ * accept arbitrary headers, so the ticket has to ride the
+ * subprotocol channel).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Canonical subprotocol identifier for the v1 wire format.
+ *
+ * @stable
+ */
+declare const SUBPROTOCOL_NAME = "graphorin.protocol.v1";
+/**
+ * Wire-format major version literal carried on every message body.
+ * The pair `(SUBPROTOCOL_NAME, PROTOCOL_VERSION)` is the binding
+ * contract a client commits to when it receives a successful upgrade.
+ *
+ * @stable
+ */
+declare const PROTOCOL_VERSION = "1";
+/**
+ * Prefix for the single-use ticket that browser clients attach to
+ * the `Sec-WebSocket-Protocol` header. The server's upgrade handler
+ * splits the comma-separated list, finds the first
+ * `ticket.<value>` token, and validates the value against the
+ * in-memory ticket store before granting the connection.
+ *
+ * @stable
+ */
+declare const TICKET_SUBPROTOCOL_PREFIX = "ticket.";
+/**
+ * Format a ticket value as a `Sec-WebSocket-Protocol` token suitable
+ * for browser clients (which cannot attach an `Authorization`
+ * header on the WebSocket upgrade). The companion server helper is
+ * {@link parseTicketSubprotocol}.
+ *
+ * @stable
+ */
+declare function formatTicketSubprotocol(ticket: string): string;
+/**
+ * Extract the ticket value from a single comma-separated client list
+ * (e.g. `'graphorin.protocol.v1, ticket.abc-123'`). Returns
+ * `undefined` if no `ticket.*` token is present. Whitespace around
+ * each comma-separated token is ignored.
+ *
+ * @stable
+ */
+declare function parseTicketSubprotocol(clientList: string | ReadonlyArray<string>): string | undefined;
+/**
+ * Pick the single subprotocol the server should echo back. Returns
+ * `SUBPROTOCOL_NAME` when the client offered it, or `null` when no
+ * compatible variant was advertised. The function ignores `ticket.*`
+ * tokens — those are handled separately via {@link parseTicketSubprotocol}.
+ *
+ * @stable
+ */
+declare function negotiateSubprotocol(clientList: string | ReadonlyArray<string>): string | null;
+//#endregion
+export { PROTOCOL_VERSION, SUBPROTOCOL_NAME, TICKET_SUBPROTOCOL_PREFIX, formatTicketSubprotocol, negotiateSubprotocol, parseTicketSubprotocol };
+//# sourceMappingURL=subprotocol.d.ts.map

package/dist/subprotocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprotocol.d.ts","names":[],"sources":["../src/subprotocol.ts"],"sourcesContent":[],"mappings":";;AAqBA;AASA;AAWA;AAUA;AAeA;AAoBA;;;;;;;;;;;;;;cAjEa,gBAAA;;;;;;;;cASA,gBAAA;;;;;;;;;;cAWA,yBAAA;;;;;;;;;iBAUG,uBAAA;;;;;;;;;iBAeA,sBAAA,sBACO;;;;;;;;;iBAmBP,oBAAA,sBAA0C"}

package/dist/subprotocol.js

@@ -0,0 +1,87 @@
+//#region src/subprotocol.ts
+/**
+* Subprotocol identifier + negotiation helpers for the Graphorin
+* WebSocket protocol.
+*
+* Clients announce supported subprotocols in the
+* `Sec-WebSocket-Protocol` upgrade header. The server is expected to
+* pick exactly one and echo it back; mismatches abort the handshake
+* per RFC 6455 § 4. Browsers also accept additional comma-separated
+* tokens — Graphorin uses this slot to attach a single-use ticket
+* via the `ticket.<value>` form (the WebSocket browser API does not
+* accept arbitrary headers, so the ticket has to ride the
+* subprotocol channel).
+*
+* @packageDocumentation
+*/
+/**
+* Canonical subprotocol identifier for the v1 wire format.
+*
+* @stable
+*/
+const SUBPROTOCOL_NAME = "graphorin.protocol.v1";
+/**
+* Wire-format major version literal carried on every message body.
+* The pair `(SUBPROTOCOL_NAME, PROTOCOL_VERSION)` is the binding
+* contract a client commits to when it receives a successful upgrade.
+*
+* @stable
+*/
+const PROTOCOL_VERSION = "1";
+/**
+* Prefix for the single-use ticket that browser clients attach to
+* the `Sec-WebSocket-Protocol` header. The server's upgrade handler
+* splits the comma-separated list, finds the first
+* `ticket.<value>` token, and validates the value against the
+* in-memory ticket store before granting the connection.
+*
+* @stable
+*/
+const TICKET_SUBPROTOCOL_PREFIX = "ticket.";
+/**
+* Format a ticket value as a `Sec-WebSocket-Protocol` token suitable
+* for browser clients (which cannot attach an `Authorization`
+* header on the WebSocket upgrade). The companion server helper is
+* {@link parseTicketSubprotocol}.
+*
+* @stable
+*/
+function formatTicketSubprotocol(ticket) {
+	if (typeof ticket !== "string" || ticket.length === 0) throw new TypeError("formatTicketSubprotocol: ticket must be a non-empty string.");
+	return `${TICKET_SUBPROTOCOL_PREFIX}${ticket}`;
+}
+/**
+* Extract the ticket value from a single comma-separated client list
+* (e.g. `'graphorin.protocol.v1, ticket.abc-123'`). Returns
+* `undefined` if no `ticket.*` token is present. Whitespace around
+* each comma-separated token is ignored.
+*
+* @stable
+*/
+function parseTicketSubprotocol(clientList) {
+	for (const token of normalizeTokens(clientList)) if (token.startsWith(TICKET_SUBPROTOCOL_PREFIX)) {
+		const value = token.slice(7);
+		if (value.length > 0) return value;
+	}
+}
+/**
+* Pick the single subprotocol the server should echo back. Returns
+* `SUBPROTOCOL_NAME` when the client offered it, or `null` when no
+* compatible variant was advertised. The function ignores `ticket.*`
+* tokens — those are handled separately via {@link parseTicketSubprotocol}.
+*
+* @stable
+*/
+function negotiateSubprotocol(clientList) {
+	for (const token of normalizeTokens(clientList)) if (token === SUBPROTOCOL_NAME) return SUBPROTOCOL_NAME;
+	return null;
+}
+function normalizeTokens(input) {
+	if (Array.isArray(input)) return input.flatMap((entry) => entry.split(",")).map((token) => token.trim()).filter((token) => token.length > 0);
+	if (typeof input !== "string") return [];
+	return input.split(",").map((token) => token.trim()).filter((token) => token.length > 0);
+}
+
+//#endregion
+export { PROTOCOL_VERSION, SUBPROTOCOL_NAME, TICKET_SUBPROTOCOL_PREFIX, formatTicketSubprotocol, negotiateSubprotocol, parseTicketSubprotocol };
+//# sourceMappingURL=subprotocol.js.map

package/dist/subprotocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprotocol.js","names":[],"sources":["../src/subprotocol.ts"],"sourcesContent":["/**\n * Subprotocol identifier + negotiation helpers for the Graphorin\n * WebSocket protocol.\n *\n * Clients announce supported subprotocols in the\n * `Sec-WebSocket-Protocol` upgrade header. The server is expected to\n * pick exactly one and echo it back; mismatches abort the handshake\n * per RFC 6455 § 4. Browsers also accept additional comma-separated\n * tokens — Graphorin uses this slot to attach a single-use ticket\n * via the `ticket.<value>` form (the WebSocket browser API does not\n * accept arbitrary headers, so the ticket has to ride the\n * subprotocol channel).\n *\n * @packageDocumentation\n */\n\n/**\n * Canonical subprotocol identifier for the v1 wire format.\n *\n * @stable\n */\nexport const SUBPROTOCOL_NAME = 'graphorin.protocol.v1';\n\n/**\n * Wire-format major version literal carried on every message body.\n * The pair `(SUBPROTOCOL_NAME, PROTOCOL_VERSION)` is the binding\n * contract a client commits to when it receives a successful upgrade.\n *\n * @stable\n */\nexport const PROTOCOL_VERSION = '1';\n\n/**\n * Prefix for the single-use ticket that browser clients attach to\n * the `Sec-WebSocket-Protocol` header. The server's upgrade handler\n * splits the comma-separated list, finds the first\n * `ticket.<value>` token, and validates the value against the\n * in-memory ticket store before granting the connection.\n *\n * @stable\n */\nexport const TICKET_SUBPROTOCOL_PREFIX = 'ticket.';\n\n/**\n * Format a ticket value as a `Sec-WebSocket-Protocol` token suitable\n * for browser clients (which cannot attach an `Authorization`\n * header on the WebSocket upgrade). The companion server helper is\n * {@link parseTicketSubprotocol}.\n *\n * @stable\n */\nexport function formatTicketSubprotocol(ticket: string): string {\n  if (typeof ticket !== 'string' || ticket.length === 0) {\n    throw new TypeError('formatTicketSubprotocol: ticket must be a non-empty string.');\n  }\n  return `${TICKET_SUBPROTOCOL_PREFIX}${ticket}`;\n}\n\n/**\n * Extract the ticket value from a single comma-separated client list\n * (e.g. `'graphorin.protocol.v1, ticket.abc-123'`). Returns\n * `undefined` if no `ticket.*` token is present. Whitespace around\n * each comma-separated token is ignored.\n *\n * @stable\n */\nexport function parseTicketSubprotocol(\n  clientList: string | ReadonlyArray<string>,\n): string | undefined {\n  for (const token of normalizeTokens(clientList)) {\n    if (token.startsWith(TICKET_SUBPROTOCOL_PREFIX)) {\n      const value = token.slice(TICKET_SUBPROTOCOL_PREFIX.length);\n      if (value.length > 0) return value;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Pick the single subprotocol the server should echo back. Returns\n * `SUBPROTOCOL_NAME` when the client offered it, or `null` when no\n * compatible variant was advertised. The function ignores `ticket.*`\n * tokens — those are handled separately via {@link parseTicketSubprotocol}.\n *\n * @stable\n */\nexport function negotiateSubprotocol(clientList: string | ReadonlyArray<string>): string | null {\n  for (const token of normalizeTokens(clientList)) {\n    if (token === SUBPROTOCOL_NAME) return SUBPROTOCOL_NAME;\n  }\n  return null;\n}\n\nfunction normalizeTokens(input: string | ReadonlyArray<string>): ReadonlyArray<string> {\n  if (Array.isArray(input)) {\n    return input\n      .flatMap((entry) => entry.split(','))\n      .map((token) => token.trim())\n      .filter((token) => token.length > 0);\n  }\n  if (typeof input !== 'string') return [];\n  return input\n    .split(',')\n    .map((token) => token.trim())\n    .filter((token) => token.length > 0);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,MAAa,mBAAmB;;;;;;;;AAShC,MAAa,mBAAmB;;;;;;;;;;AAWhC,MAAa,4BAA4B;;;;;;;;;AAUzC,SAAgB,wBAAwB,QAAwB;AAC9D,KAAI,OAAO,WAAW,YAAY,OAAO,WAAW,EAClD,OAAM,IAAI,UAAU,8DAA8D;AAEpF,QAAO,GAAG,4BAA4B;;;;;;;;;;AAWxC,SAAgB,uBACd,YACoB;AACpB,MAAK,MAAM,SAAS,gBAAgB,WAAW,CAC7C,KAAI,MAAM,WAAW,0BAA0B,EAAE;EAC/C,MAAM,QAAQ,MAAM,MAAM,EAAiC;AAC3D,MAAI,MAAM,SAAS,EAAG,QAAO;;;;;;;;;;;AAcnC,SAAgB,qBAAqB,YAA2D;AAC9F,MAAK,MAAM,SAAS,gBAAgB,WAAW,CAC7C,KAAI,UAAU,iBAAkB,QAAO;AAEzC,QAAO;;AAGT,SAAS,gBAAgB,OAA8D;AACrF,KAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MACJ,SAAS,UAAU,MAAM,MAAM,IAAI,CAAC,CACpC,KAAK,UAAU,MAAM,MAAM,CAAC,CAC5B,QAAQ,UAAU,MAAM,SAAS,EAAE;AAExC,KAAI,OAAO,UAAU,SAAU,QAAO,EAAE;AACxC,QAAO,MACJ,MAAM,IAAI,CACV,KAAK,UAAU,MAAM,MAAM,CAAC,CAC5B,QAAQ,UAAU,MAAM,SAAS,EAAE"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@graphorin/protocol",
+  "version": "0.5.0",
+  "description": "Wire protocol contract for the Graphorin framework: Zod schemas + TypeScript types for the WebSocket subprotocol `graphorin.protocol.v1`. Defines the `ClientMessage` and `ServerMessage` discriminated unions, the JSON-RPC-shaped control channel (`initialize` / `subscription.subscribe` / `subscription.unsubscribe` / `run.cancel` / `ping`), the typed event push frames (`{ kind: 'event', subject, type, payload, eventId }`), the asynchronous server-initiated error frames (`{ kind: 'error', code, message }`), the subprotocol negotiation helpers, and the close-code taxonomy (4001 auth.required, 4002 auth.invalid, 4003 auth.revoked, 4004 auth.scope_denied, 4005 rate.limited, 4006 flow.throttled, 4007 server.shutdown, 4008 protocol.violation). Browser-friendly: zero Node-only dependencies; the only runtime dependency is `zod`. Created and maintained by Oleksiy Stepurenko.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/protocol",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "protocol",
+    "websocket",
+    "subprotocol",
+    "zod",
+    "wire-format",
+    "browser-friendly"
+  ],
+  "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-message": {
+      "types": "./dist/client-message.d.ts",
+      "import": "./dist/client-message.js"
+    },
+    "./server-message": {
+      "types": "./dist/server-message.d.ts",
+      "import": "./dist/server-message.js"
+    },
+    "./subprotocol": {
+      "types": "./dist/subprotocol.d.ts",
+      "import": "./dist/subprotocol.js"
+    },
+    "./close-codes": {
+      "types": "./dist/close-codes.d.ts",
+      "import": "./dist/close-codes.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "zod": "^3.25.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}