@kyneta/websocket-transport 1.3.0 → 1.4.0

package/src/client-transport.ts

@@ -36,6 +36,13 @@ import type {
   WebsocketClientState,
   WebsocketClientStateTransition,
 } from "./types.js"
+import {
+  READY_STATE,
+  type WebSocketCloseEvent,
+  type WebSocketConstructor,
+  type WebSocketLike,
+  type WebSocketMessageEvent,
+} from "./types.js"
 
 // Re-export state types for convenience
 export type {
@@ -61,8 +68,23 @@ export interface WebsocketClientOptions {
   /** Websocket URL to connect to. Can be a string or a function of peerId. */
   url: string | ((peerId: PeerId) => string)
 
-  /** Optional custom WebSocket implementation (for Node.js or testing). */
-  WebSocket?: typeof globalThis.WebSocket
+  /**
+   * WebSocket constructor — caller must provide explicitly.
+   *
+   * In browsers, pass the global `WebSocket`. In Node.js, pass `ws`'s
+   * `WebSocket`. In Bun, pass `globalThis.WebSocket`. The transport
+   * never probes `globalThis` on its own.
+   */
+  WebSocket: WebSocketConstructor
+
+  /**
+   * Headers to send during Websocket upgrade.
+   * Used for authentication in service-to-service communication.
+   *
+   * Note: Headers are a Bun/Node-specific extension. The browser WebSocket
+   * API does not support custom headers per the WHATWG spec.
+   */
+  headers?: Record<string, string>
 
   /** Reconnection options. */
   reconnect?: {
@@ -106,21 +128,6 @@ export interface WebsocketClientLifecycleEvents {
   onReady?: () => void
 }
 
-/**
- * Options for service-to-service Websocket connections.
- * Extends WebsocketClientOptions with header support for authentication.
- *
- * Note: Headers are a Bun/Node-specific extension. The browser WebSocket API
- * does not support custom headers per the WHATWG spec.
- */
-export interface ServiceWebsocketClientOptions extends WebsocketClientOptions {
-  /**
-   * Headers to send during Websocket upgrade.
-   * Used for authentication in service-to-service communication.
-   */
-  headers?: Record<string, string>
-}
-
 // ---------------------------------------------------------------------------
 // WebsocketClientTransport
 // ---------------------------------------------------------------------------
@@ -136,19 +143,19 @@ export interface ServiceWebsocketClientOptions extends WebsocketClientOptions {
  * This class is the imperative shell that interprets data effects as I/O.
  *
  * Prefer the factory functions for construction:
- * - `createWebsocketClient()` — browser-to-server
- * - `createServiceWebsocketClient()` — service-to-service (with headers)
+ * - `createWebsocketClient()` — browser-to-server (from `./browser`)
+ * - `createServiceWebsocketClient()` — service-to-service with headers (from `./server`)
  */
 export class WebsocketClientTransport extends Transport<void> {
   #peerId?: PeerId
-  #options: ServiceWebsocketClientOptions
-  #WebSocketImpl: typeof globalThis.WebSocket
+  #options: WebsocketClientOptions
+  #WebSocketImpl: WebSocketConstructor
 
   // Observable program handle — created in constructor, drives all state
   #handle: ObservableHandle<WsClientMsg, WebsocketClientState>
 
   // Executor-local I/O state — not in the program model
-  #socket?: WebSocket
+  #socket?: WebSocketLike
   #serverChannel?: Channel
   #keepaliveTimer?: ReturnType<typeof setInterval>
   #reconnectTimer?: ReturnType<typeof setTimeout>
@@ -157,10 +164,10 @@ export class WebsocketClientTransport extends Transport<void> {
   readonly #fragmentThreshold: number
   readonly #reassembler: FragmentReassembler
 
-  constructor(options: ServiceWebsocketClientOptions) {
+  constructor(options: WebsocketClientOptions) {
     super({ transportType: "websocket-client" })
     this.#options = options
-    this.#WebSocketImpl = options.WebSocket ?? globalThis.WebSocket
+    this.#WebSocketImpl = options.WebSocket
     this.#fragmentThreshold =
       options.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD
     this.#reassembler = new FragmentReassembler({
@@ -279,18 +286,14 @@ export class WebsocketClientTransport extends Transport<void> {
         : this.#options.url
 
     try {
-      // Create WebSocket with optional headers (Bun-specific extension)
+      // Create WebSocket — pass headers as second arg when present.
+      // The structural WebSocketConstructor's `...rest: any[]` absorbs
+      // both the browser's protocols arg and backend's { headers } arg.
       if (
         this.#options.headers &&
         Object.keys(this.#options.headers).length > 0
       ) {
-        type BunWebSocketConstructor = new (
-          url: string,
-          options: { headers: Record<string, string> },
-        ) => WebSocket
-        const BunWebSocket = this
-          .#WebSocketImpl as unknown as BunWebSocketConstructor
-        this.#socket = new BunWebSocket(url, {
+        this.#socket = new this.#WebSocketImpl(url, {
           headers: this.#options.headers,
         })
       } else {
@@ -302,7 +305,7 @@ export class WebsocketClientTransport extends Transport<void> {
 
       // Set up message handler IMMEDIATELY to handle the "ready" race condition.
       // The server may send "ready" before the open event fires.
-      socket.addEventListener("message", (event: MessageEvent) => {
+      socket.addEventListener("message", (event: WebSocketMessageEvent) => {
         this.#handleMessage(event, dispatch)
       })
 
@@ -315,7 +318,7 @@ export class WebsocketClientTransport extends Transport<void> {
         dispatch({ type: "socket-opened" })
 
         // After open, set up permanent close handler for post-connection closes
-        socket.addEventListener("close", (event: CloseEvent) => {
+        socket.addEventListener("close", (event: WebSocketCloseEvent) => {
           dispatch({
             type: "socket-closed",
             code: event.code,
@@ -372,7 +375,7 @@ export class WebsocketClientTransport extends Transport<void> {
    * Binary frames carry CBOR-encoded ChannelMsg.
    */
   #handleMessage(
-    event: MessageEvent,
+    event: WebSocketMessageEvent,
     dispatch: (msg: WsClientMsg) => void,
   ): void {
     const data = event.data
@@ -426,7 +429,7 @@ export class WebsocketClientTransport extends Transport<void> {
     const interval = this.#options.keepaliveInterval ?? 30_000
 
     this.#keepaliveTimer = setInterval(() => {
-      if (this.#socket?.readyState === WebSocket.OPEN) {
+      if (this.#socket?.readyState === READY_STATE.OPEN) {
         this.#socket.send("ping")
       }
     }, interval)
@@ -536,7 +539,7 @@ export class WebsocketClientTransport extends Transport<void> {
       transportType: this.transportType,
       send: (msg: ChannelMsg) => {
         const socket = this.#socket
-        if (!socket || socket.readyState !== WebSocket.OPEN) {
+        if (!socket || socket.readyState !== READY_STATE.OPEN) {
           return
         }
 
@@ -581,11 +584,12 @@ export class WebsocketClientTransport extends Transport<void> {
  *
  * @example
  * ```typescript
- * import { createWebsocketClient } from "@kyneta/websocket-transport/client"
+ * import { createWebsocketClient } from "@kyneta/websocket-transport/browser"
  *
  * const exchange = new Exchange({
  *   transports: [createWebsocketClient({
  *     url: "ws://localhost:3000/ws",
+ *     WebSocket,
  *     reconnect: { enabled: true },
  *   })],
  * })
@@ -596,32 +600,3 @@ export function createWebsocketClient(
 ): TransportFactory {
   return () => new WebsocketClientTransport(options)
 }
-
-/**
- * Create a Websocket client transport for service-to-service connections.
- *
- * This factory is for backend environments (Bun, Node.js) where you need
- * to pass authentication headers during the Websocket upgrade.
- *
- * Note: Headers are a Bun/Node-specific extension. The browser WebSocket API
- * does not support custom headers. For browser clients, use
- * `createWebsocketClient()` and authenticate via URL query parameters.
- *
- * @example
- * ```typescript
- * import { createServiceWebsocketClient } from "@kyneta/websocket-transport/client"
- *
- * const exchange = new Exchange({
- *   transports: [createServiceWebsocketClient({
- *     url: "ws://primary-server:3000/ws",
- *     headers: { Authorization: "Bearer token" },
- *     reconnect: { enabled: true },
- *   })],
- * })
- * ```
- */
-export function createServiceWebsocketClient(
-  options: ServiceWebsocketClientOptions,
-): TransportFactory {
-  return () => new WebsocketClientTransport(options)
-}

package/src/connection.ts

@@ -133,7 +133,7 @@ export class WebsocketConnection {
    *
    * This is a transport-level text message that tells the client the
    * server is ready to receive protocol messages. The client creates
-   * its channel and sends establish-request after receiving this.
+   * its channel and sends establish after receiving this.
    */
   sendReady(): void {
     if (this.#socket.readyState !== "open") {

package/src/server-transport.ts

@@ -5,8 +5,8 @@
 // library through the Socket interface.
 //
 // Usage with Bun:
-//   import { WebsocketServerTransport } from "@kyneta/websocket-network-adapter/server"
-//   import { createBunWebsocketHandlers } from "@kyneta/websocket-network-adapter/bun"
+//   import { WebsocketServerTransport } from "@kyneta/websocket-transport/server"
+//   import { createBunWebsocketHandlers } from "@kyneta/websocket-transport/bun"
 //
 //   const serverAdapter = new WebsocketServerTransport()
 //   Bun.serve({
@@ -15,7 +15,7 @@
 //   })
 //
 // Usage with Node.js `ws`:
-//   import { WebsocketServerTransport, wrapNodeWebsocket } from "@kyneta/websocket-network-adapter/server"
+//   import { WebsocketServerTransport, wrapNodeWebsocket } from "@kyneta/websocket-transport/server"
 //   import { WebSocketServer } from "ws"
 //
 //   const serverAdapter = new WebsocketServerTransport()
@@ -88,12 +88,12 @@ function generatePeerId(): PeerId {
  *
  * The connection handshake follows a two-phase protocol:
  * 1. Server sends text `"ready"` signal (transport-level)
- * 2. Client sends `establish-request` (protocol-level)
- * 3. Server responds with `establish-response` (handled by Synchronizer)
+ * 2. Client sends `establish` (protocol-level)
+ * 3. Server upgrades channel and sends present (handled by Synchronizer)
  *
  * The server does NOT call `establishChannel()` — it waits for the
- * client's establish-request to avoid a race condition where the binary
- * establish-request could arrive before the client has processed "ready".
+ * client's establish to avoid a race condition where the binary
+ * establish could arrive before the client has processed "ready".
  */
 export class WebsocketServerTransport extends Transport<PeerId> {
   #connections = new Map<PeerId, WebsocketConnection>()
@@ -219,11 +219,11 @@ export class WebsocketServerTransport extends Transport<PeerId> {
         connection.sendReady()
 
         // NOTE: We do NOT call establishChannel() here.
-        // The client will send establish-request after receiving "ready".
+        // The client will send establish after receiving "ready".
         // Our channel gets established when the Synchronizer receives
-        // and processes that establish-request.
+        // and processes that establish message.
         //
-        // This prevents a race condition where our binary establish-request
+        // This prevents a race condition where our binary establish
         // could arrive before the client has processed "ready" and created
         // its channel.
       },

package/src/server.ts

@@ -1,10 +1,11 @@
-// server — barrel export for @kyneta/websocket-network-adapter/server.
+// server — barrel export for @kyneta/websocket-transport/server.
 //
 // This is the server-side entry point. It exports everything needed
-// to create a Websocket server adapter with any framework.
+// to create a Websocket server transport with any framework, plus
+// the service-to-service client factory for backend connections.
 
 // ---------------------------------------------------------------------------
-// Server adapter
+// Server transport
 // ---------------------------------------------------------------------------
 
 export {
@@ -22,6 +23,15 @@ export {
   type WebsocketConnectionConfig,
 } from "./connection.js"
 
+// ---------------------------------------------------------------------------
+// Service-to-service client (backend connections with headers)
+// ---------------------------------------------------------------------------
+
+export {
+  createServiceWebsocketClient,
+  type ServiceWebsocketClientOptions,
+} from "./service-client.js"
+
 // ---------------------------------------------------------------------------
 // Shared types + wrappers
 // ---------------------------------------------------------------------------
@@ -31,9 +41,17 @@ export type {
   NodeWebsocketLike,
   Socket,
   SocketReadyState,
+  WebSocketCloseEvent,
+  WebSocketConstructor,
+  WebSocketLike,
+  WebSocketMessageEvent,
   WebsocketConnectionHandle,
   WebsocketConnectionOptions,
   WebsocketConnectionResult,
 } from "./types.js"
 
-export { wrapNodeWebsocket, wrapStandardWebsocket } from "./types.js"
+export {
+  READY_STATE,
+  wrapNodeWebsocket,
+  wrapStandardWebsocket,
+} from "./types.js"

package/src/service-client.ts

@@ -0,0 +1,52 @@
+// service-client — service-to-service WebSocket client factory.
+//
+// Extracted from client-transport.ts so that the service client factory
+// lives in the `./server` entry point (where it belongs) rather than
+// the `./browser` entry point. Backend code imports from `./server`;
+// browser code imports from `./browser`.
+
+import type { TransportFactory } from "@kyneta/transport"
+import {
+  type WebsocketClientOptions,
+  WebsocketClientTransport,
+} from "./client-transport.js"
+
+/**
+ * Options for service-to-service Websocket connections.
+ *
+ * Identical to `WebsocketClientOptions` — the `headers` field is always
+ * available on the base options. This alias exists for API clarity:
+ * importing `ServiceWebsocketClientOptions` from `./server` signals
+ * intent and pairs with `createServiceWebsocketClient`.
+ */
+export type ServiceWebsocketClientOptions = WebsocketClientOptions
+
+/**
+ * Create a Websocket client transport for service-to-service connections.
+ *
+ * This factory is for backend environments (Bun, Node.js) where you need
+ * to pass authentication headers during the Websocket upgrade.
+ *
+ * Note: Headers are a Bun/Node-specific extension. The browser WebSocket API
+ * does not support custom headers. For browser clients, use
+ * `createWebsocketClient()` and authenticate via URL query parameters.
+ *
+ * @example
+ * ```typescript
+ * import { createServiceWebsocketClient } from "@kyneta/websocket-transport/server"
+ *
+ * const exchange = new Exchange({
+ *   transports: [createServiceWebsocketClient({
+ *     url: "ws://primary-server:3000/ws",
+ *     WebSocket,
+ *     headers: { Authorization: "Bearer token" },
+ *     reconnect: { enabled: true },
+ *   })],
+ * })
+ * ```
+ */
+export function createServiceWebsocketClient(
+  options: ServiceWebsocketClientOptions,
+): TransportFactory {
+  return () => new WebsocketClientTransport(options)
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-// types — framework-agnostic Websocket abstractions for @kyneta/websocket-network-adapter.
+// types — framework-agnostic Websocket abstractions for @kyneta/websocket-transport.
 //
 // The `Socket` interface decouples the adapter from any specific Websocket
 // library (browser WebSocket, Node `ws`, Bun ServerWebSocket). Platform-
@@ -15,7 +15,75 @@ import type {
 } from "@kyneta/transport"
 
 // ---------------------------------------------------------------------------
-// Socket ready states
+// WebSocket readyState constants (spec values, no global dependency)
+// ---------------------------------------------------------------------------
+
+/**
+ * WebSocket readyState constants per the WHATWG WebSocket spec.
+ * Replaces references to `WebSocket.CONNECTING`, `WebSocket.OPEN`, etc.
+ * so that shared code never depends on the browser global.
+ */
+export const READY_STATE = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const
+
+// ---------------------------------------------------------------------------
+// Structural event types (replace DOM MessageEvent / CloseEvent)
+// ---------------------------------------------------------------------------
+
+/** Minimal message event — only the fields the transport accesses. */
+export interface WebSocketMessageEvent {
+  readonly data: string | ArrayBuffer
+}
+
+/** Minimal close event — only the fields the transport accesses. */
+export interface WebSocketCloseEvent {
+  readonly code: number
+  readonly reason: string
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket instance and constructor structural types
+// ---------------------------------------------------------------------------
+
+/**
+ * Structural type for a constructed WebSocket instance.
+ *
+ * Covers the browser's `WebSocket`, the `ws` library's `WebSocket`,
+ * and Bun's client `WebSocket` — all satisfy this interface without casting.
+ *
+ * The client transport uses `addEventListener`/`removeEventListener` for
+ * one-shot connection handlers with explicit cleanup during the connect
+ * phase. This is why `WebSocketLike` exists alongside the server-side
+ * `Socket` interface (which uses single-callback registration).
+ */
+export interface WebSocketLike {
+  readonly readyState: number
+  binaryType: string
+  send(data: string | ArrayBuffer): void
+  close(code?: number, reason?: string): void
+  addEventListener(type: string, listener: (event: any) => void): void
+  removeEventListener(type: string, listener: (event: any) => void): void
+}
+
+/**
+ * Structural type for a WebSocket constructor.
+ *
+ * Type safety for constructor arguments is intentionally at the options
+ * layer (`WebsocketClientOptions.headers`), not here. The `...rest: any[]`
+ * absorbs both the browser's `protocols` arg and backend's `{ headers }`
+ * arg without requiring the transport to know which runtime it's in.
+ */
+export type WebSocketConstructor = new (
+  url: string,
+  ...rest: any[]
+) => WebSocketLike
+
+// ---------------------------------------------------------------------------
+// Socket ready states (string enum for server-side Socket interface)
 // ---------------------------------------------------------------------------
 
 /**
@@ -205,13 +273,13 @@ export function wrapStandardWebsocket(ws: WebSocket): Socket {
 
     get readyState(): SocketReadyState {
       switch (ws.readyState) {
-        case WebSocket.CONNECTING:
+        case READY_STATE.CONNECTING:
           return "connecting"
-        case WebSocket.OPEN:
+        case READY_STATE.OPEN:
           return "open"
-        case WebSocket.CLOSING:
+        case READY_STATE.CLOSING:
           return "closing"
-        case WebSocket.CLOSED:
+        case READY_STATE.CLOSED:
           return "closed"
         default:
           return "closed"

package/dist/chunk-PSG3LLT5.js

@@ -1,111 +0,0 @@
-// src/types.ts
-function wrapStandardWebsocket(ws) {
-  return {
-    send(data) {
-      ws.send(
-        typeof data === "string" ? data : data
-      );
-    },
-    close(code, reason) {
-      ws.close(code, reason);
-    },
-    onMessage(handler) {
-      ws.addEventListener("message", (event) => {
-        if (event.data instanceof ArrayBuffer) {
-          handler(new Uint8Array(event.data));
-        } else if (typeof Blob !== "undefined" && event.data instanceof Blob) {
-          event.data.arrayBuffer().then((buffer) => {
-            handler(new Uint8Array(buffer));
-          });
-        } else {
-          handler(event.data);
-        }
-      });
-    },
-    onClose(handler) {
-      ws.addEventListener("close", (event) => {
-        handler(event.code, event.reason);
-      });
-    },
-    onError(handler) {
-      ws.addEventListener("error", (_event) => {
-        handler(new Error("WebSocket error"));
-      });
-    },
-    get readyState() {
-      switch (ws.readyState) {
-        case WebSocket.CONNECTING:
-          return "connecting";
-        case WebSocket.OPEN:
-          return "open";
-        case WebSocket.CLOSING:
-          return "closing";
-        case WebSocket.CLOSED:
-          return "closed";
-        default:
-          return "closed";
-      }
-    }
-  };
-}
-function wrapNodeWebsocket(ws) {
-  const CONNECTING = 0;
-  const OPEN = 1;
-  const CLOSING = 2;
-  return {
-    send(data) {
-      ws.send(data);
-    },
-    close(code, reason) {
-      ws.close(code, reason);
-    },
-    onMessage(handler) {
-      ws.on(
-        "message",
-        (data, isBinary) => {
-          if (isBinary) {
-            if (data instanceof ArrayBuffer) {
-              handler(new Uint8Array(data));
-            } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
-              handler(new Uint8Array(data));
-            } else {
-              handler(new Uint8Array(data));
-            }
-          } else {
-            if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
-              handler(data.toString("utf-8"));
-            } else {
-              handler(data);
-            }
-          }
-        }
-      );
-    },
-    onClose(handler) {
-      ws.on("close", (code, reason) => {
-        handler(code, reason.toString());
-      });
-    },
-    onError(handler) {
-      ws.on("error", handler);
-    },
-    get readyState() {
-      switch (ws.readyState) {
-        case CONNECTING:
-          return "connecting";
-        case OPEN:
-          return "open";
-        case CLOSING:
-          return "closing";
-        default:
-          return "closed";
-      }
-    }
-  };
-}
-
-export {
-  wrapStandardWebsocket,
-  wrapNodeWebsocket
-};
-//# sourceMappingURL=chunk-PSG3LLT5.js.map

package/dist/chunk-PSG3LLT5.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["// types — framework-agnostic Websocket abstractions for @kyneta/websocket-network-adapter.\n//\n// The `Socket` interface decouples the adapter from any specific Websocket\n// library (browser WebSocket, Node `ws`, Bun ServerWebSocket). Platform-\n// specific wrappers (`wrapStandardWebsocket`, `wrapNodeWebsocket`,\n// `wrapBunWebsocket`) adapt concrete implementations to this interface.\n//\n// Ported from @loro-extended/adapter-websocket's WsSocket with kyneta\n// naming conventions applied.\n\nimport type {\n  TransitionListener as GenericTransitionListener,\n  PeerId,\n  StateTransition,\n} from \"@kyneta/transport\"\n\n// ---------------------------------------------------------------------------\n// Socket ready states\n// ---------------------------------------------------------------------------\n\n/**\n * Websocket ready states — mirrors the standard WebSocket readyState\n * values as human-readable strings.\n */\nexport type SocketReadyState = \"connecting\" | \"open\" | \"closing\" | \"closed\"\n\n// ---------------------------------------------------------------------------\n// Socket interface\n// ---------------------------------------------------------------------------\n\n/**\n * Framework-agnostic Websocket interface.\n *\n * This allows the adapter to work with any Websocket library:\n * - Browser `WebSocket` via `wrapStandardWebsocket()`\n * - Node.js `ws` library via `wrapNodeWebsocket()`\n * - Bun `ServerWebSocket` via `wrapBunWebsocket()`\n *\n * The interface is intentionally minimal — only the operations the\n * adapter needs are exposed.\n */\nexport interface Socket {\n  /** Send binary or text data through the Websocket. */\n  send(data: Uint8Array | string): void\n\n  /** Close the Websocket connection. */\n  close(code?: number, reason?: string): void\n\n  /** Register a handler for incoming messages (binary or text). */\n  onMessage(handler: (data: Uint8Array | string) => void): void\n\n  /** Register a handler for connection close. */\n  onClose(handler: (code: number, reason: string) => void): void\n\n  /** Register a handler for errors. */\n  onError(handler: (error: Error) => void): void\n\n  /** The current ready state of the Websocket. */\n  readonly readyState: SocketReadyState\n}\n\n// ---------------------------------------------------------------------------\n// Connection types — used by server adapter\n// ---------------------------------------------------------------------------\n\n/**\n * Options for handling a new Websocket connection on the server.\n */\nexport interface WebsocketConnectionOptions {\n  /** The Websocket instance, wrapped in the Socket interface. */\n  socket: Socket\n\n  /** Optional peer ID extracted from the upgrade request. */\n  peerId?: PeerId\n\n  /** Optional authentication token from the upgrade request. */\n  authToken?: string\n}\n\n/**\n * Handle for an active Websocket connection.\n */\nexport interface WebsocketConnectionHandle {\n  /** The peer ID for this connection. */\n  readonly peerId: PeerId\n\n  /** The channel ID for this connection. */\n  readonly channelId: number\n\n  /** Close the connection. */\n  close(code?: number, reason?: string): void\n}\n\n/**\n * Result of handling a Websocket connection on the server.\n */\nexport interface WebsocketConnectionResult {\n  /** The connection handle for managing this peer. */\n  connection: WebsocketConnectionHandle\n\n  /** Call this to start processing messages. */\n  start(): void\n}\n\n// ---------------------------------------------------------------------------\n// Disconnect reason\n// ---------------------------------------------------------------------------\n\n/**\n * Discriminated union describing why a Websocket connection was lost.\n */\nexport type DisconnectReason =\n  | { type: \"intentional\" }\n  | { type: \"error\"; error: Error }\n  | { type: \"closed\"; code: number; reason: string }\n  | { type: \"max-retries-exceeded\"; attempts: number }\n  | { type: \"not-started\" }\n\n// ---------------------------------------------------------------------------\n// Connection state (for client adapter observability)\n// ---------------------------------------------------------------------------\n\n/**\n * All possible states of the Websocket client.\n *\n * State machine transitions:\n * ```\n * disconnected → connecting → connected → ready\n *                    ↓            ↓         ↓\n *               reconnecting ← ─ ┴ ─ ─ ─ ─ ┘\n *                    ↓\n *               connecting (retry)\n *                    ↓\n *               disconnected (max retries)\n * ```\n */\nexport type WebsocketClientState =\n  | { status: \"disconnected\"; reason?: DisconnectReason }\n  | { status: \"connecting\"; attempt: number }\n  | { status: \"connected\" }\n  | { status: \"ready\" }\n  | { status: \"reconnecting\"; attempt: number; nextAttemptMs: number }\n\n/**\n * A state transition event for websocket client states.\n * Specialized from the generic `StateTransition<S>`.\n */\nexport type WebsocketClientStateTransition =\n  StateTransition<WebsocketClientState>\n\n/**\n * Listener for websocket client state transitions.\n * Specialized from the generic `TransitionListener<S>`.\n */\nexport type TransitionListener = GenericTransitionListener<WebsocketClientState>\n\n// ---------------------------------------------------------------------------\n// Socket wrapper — standard WebSocket API (browser + Node ws)\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a standard `WebSocket` (browser or Node.js `ws` via `ws` package\n * in `WebSocket`-compatible mode) into the `Socket` interface.\n *\n * Handles `ArrayBuffer`, `Blob`, and string messages.\n */\nexport function wrapStandardWebsocket(ws: WebSocket): Socket {\n  return {\n    send(data: Uint8Array | string): void {\n      ws.send(\n        typeof data === \"string\" ? data : (data as Uint8Array<ArrayBuffer>),\n      )\n    },\n\n    close(code?: number, reason?: string): void {\n      ws.close(code, reason)\n    },\n\n    onMessage(handler: (data: Uint8Array | string) => void): void {\n      ws.addEventListener(\"message\", event => {\n        if (event.data instanceof ArrayBuffer) {\n          handler(new Uint8Array(event.data))\n        } else if (typeof Blob !== \"undefined\" && event.data instanceof Blob) {\n          // Handle Blob data (browser)\n          event.data.arrayBuffer().then(buffer => {\n            handler(new Uint8Array(buffer))\n          })\n        } else {\n          handler(event.data as string)\n        }\n      })\n    },\n\n    onClose(handler: (code: number, reason: string) => void): void {\n      ws.addEventListener(\"close\", event => {\n        handler(event.code, event.reason)\n      })\n    },\n\n    onError(handler: (error: Error) => void): void {\n      ws.addEventListener(\"error\", _event => {\n        handler(new Error(\"WebSocket error\"))\n      })\n    },\n\n    get readyState(): SocketReadyState {\n      switch (ws.readyState) {\n        case WebSocket.CONNECTING:\n          return \"connecting\"\n        case WebSocket.OPEN:\n          return \"open\"\n        case WebSocket.CLOSING:\n          return \"closing\"\n        case WebSocket.CLOSED:\n          return \"closed\"\n        default:\n          return \"closed\"\n      }\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Socket wrapper — Node.js `ws` library (raw API, not WebSocket-compat)\n// ---------------------------------------------------------------------------\n\n/**\n * The minimal interface we need from the Node.js `ws` library's `WebSocket`.\n *\n * Using a structural type rather than importing `ws` — consumers provide\n * the actual `ws` instance, we just need these methods.\n */\nexport interface NodeWebsocketLike {\n  send(data: Uint8Array | string): void\n  close(code?: number, reason?: string): void\n  on(\n    event: \"message\",\n    handler: (data: Buffer | ArrayBuffer | string, isBinary: boolean) => void,\n  ): void\n  on(event: \"close\", handler: (code: number, reason: Buffer) => void): void\n  on(event: \"error\", handler: (error: Error) => void): void\n  readyState: number\n}\n\n/**\n * Wrap a Node.js `ws` library WebSocket into the `Socket` interface.\n *\n * Handles `Buffer` → `Uint8Array` conversion for binary messages.\n */\nexport function wrapNodeWebsocket(ws: NodeWebsocketLike): Socket {\n  const CONNECTING = 0\n  const OPEN = 1\n  const CLOSING = 2\n\n  return {\n    send(data: Uint8Array | string): void {\n      ws.send(data)\n    },\n\n    close(code?: number, reason?: string): void {\n      ws.close(code, reason)\n    },\n\n    onMessage(handler: (data: Uint8Array | string) => void): void {\n      ws.on(\n        \"message\",\n        (data: Buffer | ArrayBuffer | string, isBinary: boolean) => {\n          if (isBinary) {\n            if (data instanceof ArrayBuffer) {\n              handler(new Uint8Array(data))\n            } else if (typeof Buffer !== \"undefined\" && Buffer.isBuffer(data)) {\n              handler(new Uint8Array(data))\n            } else {\n              handler(new Uint8Array(data as unknown as ArrayBuffer))\n            }\n          } else {\n            if (typeof Buffer !== \"undefined\" && Buffer.isBuffer(data)) {\n              handler(data.toString(\"utf-8\"))\n            } else {\n              handler(data as string)\n            }\n          }\n        },\n      )\n    },\n\n    onClose(handler: (code: number, reason: string) => void): void {\n      ws.on(\"close\", (code: number, reason: Buffer) => {\n        handler(code, reason.toString())\n      })\n    },\n\n    onError(handler: (error: Error) => void): void {\n      ws.on(\"error\", handler)\n    },\n\n    get readyState(): SocketReadyState {\n      switch (ws.readyState) {\n        case CONNECTING:\n          return \"connecting\"\n        case OPEN:\n          return \"open\"\n        case CLOSING:\n          return \"closing\"\n        default:\n          return \"closed\"\n      }\n    },\n  }\n}\n"],"mappings":";AAsKO,SAAS,sBAAsB,IAAuB;AAC3D,SAAO;AAAA,IACL,KAAK,MAAiC;AACpC,SAAG;AAAA,QACD,OAAO,SAAS,WAAW,OAAQ;AAAA,MACrC;AAAA,IACF;AAAA,IAEA,MAAM,MAAe,QAAuB;AAC1C,SAAG,MAAM,MAAM,MAAM;AAAA,IACvB;AAAA,IAEA,UAAU,SAAoD;AAC5D,SAAG,iBAAiB,WAAW,WAAS;AACtC,YAAI,MAAM,gBAAgB,aAAa;AACrC,kBAAQ,IAAI,WAAW,MAAM,IAAI,CAAC;AAAA,QACpC,WAAW,OAAO,SAAS,eAAe,MAAM,gBAAgB,MAAM;AAEpE,gBAAM,KAAK,YAAY,EAAE,KAAK,YAAU;AACtC,oBAAQ,IAAI,WAAW,MAAM,CAAC;AAAA,UAChC,CAAC;AAAA,QACH,OAAO;AACL,kBAAQ,MAAM,IAAc;AAAA,QAC9B;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuD;AAC7D,SAAG,iBAAiB,SAAS,WAAS;AACpC,gBAAQ,MAAM,MAAM,MAAM,MAAM;AAAA,MAClC,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuC;AAC7C,SAAG,iBAAiB,SAAS,YAAU;AACrC,gBAAQ,IAAI,MAAM,iBAAiB,CAAC;AAAA,MACtC,CAAC;AAAA,IACH;AAAA,IAEA,IAAI,aAA+B;AACjC,cAAQ,GAAG,YAAY;AAAA,QACrB,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT;AACE,iBAAO;AAAA,MACX;AAAA,IACF;AAAA,EACF;AACF;AA6BO,SAAS,kBAAkB,IAA+B;AAC/D,QAAM,aAAa;AACnB,QAAM,OAAO;AACb,QAAM,UAAU;AAEhB,SAAO;AAAA,IACL,KAAK,MAAiC;AACpC,SAAG,KAAK,IAAI;AAAA,IACd;AAAA,IAEA,MAAM,MAAe,QAAuB;AAC1C,SAAG,MAAM,MAAM,MAAM;AAAA,IACvB;AAAA,IAEA,UAAU,SAAoD;AAC5D,SAAG;AAAA,QACD;AAAA,QACA,CAAC,MAAqC,aAAsB;AAC1D,cAAI,UAAU;AACZ,gBAAI,gBAAgB,aAAa;AAC/B,sBAAQ,IAAI,WAAW,IAAI,CAAC;AAAA,YAC9B,WAAW,OAAO,WAAW,eAAe,OAAO,SAAS,IAAI,GAAG;AACjE,sBAAQ,IAAI,WAAW,IAAI,CAAC;AAAA,YAC9B,OAAO;AACL,sBAAQ,IAAI,WAAW,IAA8B,CAAC;AAAA,YACxD;AAAA,UACF,OAAO;AACL,gBAAI,OAAO,WAAW,eAAe,OAAO,SAAS,IAAI,GAAG;AAC1D,sBAAQ,KAAK,SAAS,OAAO,CAAC;AAAA,YAChC,OAAO;AACL,sBAAQ,IAAc;AAAA,YACxB;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,IAEA,QAAQ,SAAuD;AAC7D,SAAG,GAAG,SAAS,CAAC,MAAc,WAAmB;AAC/C,gBAAQ,MAAM,OAAO,SAAS,CAAC;AAAA,MACjC,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuC;AAC7C,SAAG,GAAG,SAAS,OAAO;AAAA,IACxB;AAAA,IAEA,IAAI,aAA+B;AACjC,cAAQ,GAAG,YAAY;AAAA,QACrB,KAAK;AACH,iBAAO;AAAA,QACT,KAAK;AACH,iBAAO;AAAA,QACT,KAAK;AACH,iBAAO;AAAA,QACT;AACE,iBAAO;AAAA,MACX;AAAA,IACF;AAAA,EACF;AACF;","names":[]}