@soulcraft/sdk 2.1.0 → 2.3.0

package/dist/server/ws-handler.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @module server/ws-handler
+ * @description Namespace-aware WebSocket handler for the Soulcraft SDK.
+ *
+ * Provides `createNamespaceWsHandler()` — a server-side handler that processes
+ * WebSocket messages through the same namespace router used by HTTP RPC, plus
+ * Y.js collaborative editing and real-time change push.
+ *
+ * ## Wire protocol
+ *
+ * All frames are binary MessagePack. The protocol supports four message categories:
+ *
+ * 1. **Namespace RPC** — `{ id, ns, method, args }` dispatched to the namespace router
+ * 2. **Streaming RPC** — `{ id, ns, method, args, stream: true }` returns chunked responses
+ * 3. **Y.js collab** — `{ type: 'y-sync'|'y-update'|'y-awareness', ... }` for CRDT editing
+ * 4. **Change push** — `{ type: 'change', ... }` broadcast from server on data mutations
+ *
+ * ## Auth
+ *
+ * Authentication happens once during `handleUpgrade()`. The resulting `WsSession`
+ * carries the authenticated user context. Subsequent messages are dispatched with
+ * pre-authenticated context — no per-message auth overhead.
+ *
+ * ## Relationship to namespace router
+ *
+ * The WS handler is a thin transport adapter. All RPC dispatch logic lives in
+ * `namespace-router.ts`. This handler adds: token extraction, Y.js routing,
+ * peer tracking, streaming frame serialization, and change broadcasting.
+ *
+ * @example Bun server wiring
+ * ```typescript
+ * import { createNamespaceWsHandler, YDocManager } from '@soulcraft/sdk/server'
+ *
+ * const handler = createNamespaceWsHandler({
+ *   router: routerConfig,
+ *   ydocManager: new YDocManager(),
+ * })
+ *
+ * Bun.serve({
+ *   async fetch(req, server) {
+ *     if (new URL(req.url).pathname === '/api/brainy/ws') {
+ *       const session = await handler.handleUpgrade(req)
+ *       if (!session) return new Response('Unauthorized', { status: 401 })
+ *       server.upgrade(req, { data: session })
+ *       return undefined
+ *     }
+ *   },
+ *   websocket: {
+ *     open(ws) { ws.send(encode({ type: 'ready', scope: ws.data.scope })) },
+ *     async message(ws, data) {
+ *       await handler.handleMessage(ws.data, data, (msg) => ws.send(msg))
+ *     },
+ *     async close(ws) { await handler.handleClose(ws.data) },
+ *   },
+ * })
+ * ```
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { BrainyChangeEvent } from '../modules/brainy/events.js';
+import type { NamespaceRouterConfig, UserContext } from './namespace-router.js';
+import { YDocManager } from '../modules/brainy/ydoc-manager.js';
+/**
+ * Configuration for {@link createNamespaceWsHandler}.
+ *
+ * Reuses the same `NamespaceRouterConfig` shape as `createSoulcraftRouter()`,
+ * so products can share a single config object between HTTP and WebSocket handlers.
+ */
+export interface NamespaceWsHandlerConfig {
+    /**
+     * Shared router config — `authenticate`, `resolveBrain`, `providers`, `authorize`.
+     *
+     * The `authenticate` callback receives a synthetic `RequestContext` built from
+     * the WebSocket upgrade request. The `resolveBrain` callback receives the same
+     * context with the authenticated user populated.
+     */
+    router: NamespaceRouterConfig;
+    /**
+     * Optional Y.js document manager for real-time collaborative editing.
+     *
+     * When provided, the handler routes `y-sync`, `y-update`, and `y-awareness`
+     * messages through the `YDocManager`. Y.js update broadcasts are sent to all
+     * other peers via the `broadcast` callback on the session.
+     */
+    ydocManager?: YDocManager;
+}
+/**
+ * Per-connection session state stored on the WebSocket's data field.
+ *
+ * Created by `handleUpgrade()` and passed to all subsequent message/close handlers.
+ */
+export interface WsSession {
+    /** The authenticated user context. */
+    user: UserContext;
+    /** Workspace ID extracted from the upgrade request. */
+    workspaceId: string;
+    /** The resolved Brainy instance for this session's scope. */
+    brain: Brainy;
+    /** The raw scope string from `?scope=` (preserved for broadcast key). */
+    scope: string;
+    /**
+     * Unique peer ID for this connection. Used by `YDocManager` to track per-file
+     * peer counts so it knows when the last peer has disconnected.
+     */
+    peerId: string;
+    /**
+     * Broadcast callback set by the product server after upgrade.
+     *
+     * Called by the handler to fan out `y-update` and `y-awareness` messages to all
+     * other peers connected to this scope. The product server owns the connection map
+     * and provides this callback so the SDK does not manage WebSocket handles directly.
+     *
+     * @param msg - Encoded MessagePack frame to send to all OTHER peers in this scope.
+     * @param excludePeerId - The peer that sent the message — must be excluded.
+     */
+    broadcast: (msg: Uint8Array, excludePeerId: string) => void;
+}
+/**
+ * The object returned by {@link createNamespaceWsHandler}.
+ */
+export interface NamespaceWsHandler {
+    /**
+     * Handles a WebSocket upgrade request.
+     *
+     * Extracts the token and scope, authenticates via the router's `authenticate`
+     * callback, and resolves the Brainy instance. Returns `null` on auth failure.
+     *
+     * @param request - The HTTP upgrade request.
+     * @returns Session state on success, or `null` on auth failure.
+     */
+    handleUpgrade(request: Request): Promise<WsSession | null>;
+    /**
+     * Processes an incoming WebSocket message.
+     *
+     * Routes to either the namespace RPC dispatcher or the Y.js handler based
+     * on the decoded message shape.
+     *
+     * @param session - Session from `handleUpgrade()`.
+     * @param data - Raw binary MessagePack frame.
+     * @param send - Callback to send a binary response to THIS client only.
+     */
+    handleMessage(session: WsSession, data: ArrayBuffer | Uint8Array, send: (msg: Uint8Array) => void): Promise<void>;
+    /**
+     * Called when a peer's WebSocket connection closes.
+     *
+     * Notifies the `YDocManager` so it can flush and discard Y.Docs with no
+     * active peers.
+     *
+     * @param session - The session of the disconnecting peer.
+     */
+    handleClose(session: WsSession): Promise<void>;
+    /**
+     * Broadcasts a Brainy change event to a connected client.
+     *
+     * @param event - The change event to broadcast.
+     * @param send - Callback to send the encoded event to the target client.
+     */
+    broadcastChange(event: BrainyChangeEvent, send: (msg: Uint8Array) => void): void;
+}
+/**
+ * Creates a namespace-aware WebSocket handler that dispatches RPC through the
+ * same namespace router used by HTTP, plus Y.js collaborative editing.
+ *
+ * @param config - Handler configuration.
+ * @returns A {@link NamespaceWsHandler} instance.
+ */
+export declare function createNamespaceWsHandler(config: NamespaceWsHandlerConfig): NamespaceWsHandler;
+//# sourceMappingURL=ws-handler.d.ts.map

package/dist/server/ws-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-handler.d.ts","sourceRoot":"","sources":["../../src/server/ws-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,KAAK,EACV,qBAAqB,EAErB,WAAW,EAEZ,MAAM,uBAAuB,CAAA;AAI9B,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAA;AAM/D;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,MAAM,EAAE,qBAAqB,CAAA;IAE7B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAMD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,IAAI,EAAE,WAAW,CAAA;IACjB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAA;IACnB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;;OASG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5D;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAA;IAE1D;;;;;;;;;OASG;IACH,aAAa,CACX,OAAO,EAAE,SAAS,EAClB,IAAI,EAAE,WAAW,GAAG,UAAU,EAC9B,IAAI,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,GAC9B,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhB;;;;;;;OAOG;IACH,WAAW,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9C;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAA;CACjF;AAiCD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,GAAG,kBAAkB,CA0I7F"}

package/dist/server/ws-handler.js

@@ -0,0 +1,243 @@
+/**
+ * @module server/ws-handler
+ * @description Namespace-aware WebSocket handler for the Soulcraft SDK.
+ *
+ * Provides `createNamespaceWsHandler()` — a server-side handler that processes
+ * WebSocket messages through the same namespace router used by HTTP RPC, plus
+ * Y.js collaborative editing and real-time change push.
+ *
+ * ## Wire protocol
+ *
+ * All frames are binary MessagePack. The protocol supports four message categories:
+ *
+ * 1. **Namespace RPC** — `{ id, ns, method, args }` dispatched to the namespace router
+ * 2. **Streaming RPC** — `{ id, ns, method, args, stream: true }` returns chunked responses
+ * 3. **Y.js collab** — `{ type: 'y-sync'|'y-update'|'y-awareness', ... }` for CRDT editing
+ * 4. **Change push** — `{ type: 'change', ... }` broadcast from server on data mutations
+ *
+ * ## Auth
+ *
+ * Authentication happens once during `handleUpgrade()`. The resulting `WsSession`
+ * carries the authenticated user context. Subsequent messages are dispatched with
+ * pre-authenticated context — no per-message auth overhead.
+ *
+ * ## Relationship to namespace router
+ *
+ * The WS handler is a thin transport adapter. All RPC dispatch logic lives in
+ * `namespace-router.ts`. This handler adds: token extraction, Y.js routing,
+ * peer tracking, streaming frame serialization, and change broadcasting.
+ *
+ * @example Bun server wiring
+ * ```typescript
+ * import { createNamespaceWsHandler, YDocManager } from '@soulcraft/sdk/server'
+ *
+ * const handler = createNamespaceWsHandler({
+ *   router: routerConfig,
+ *   ydocManager: new YDocManager(),
+ * })
+ *
+ * Bun.serve({
+ *   async fetch(req, server) {
+ *     if (new URL(req.url).pathname === '/api/brainy/ws') {
+ *       const session = await handler.handleUpgrade(req)
+ *       if (!session) return new Response('Unauthorized', { status: 401 })
+ *       server.upgrade(req, { data: session })
+ *       return undefined
+ *     }
+ *   },
+ *   websocket: {
+ *     open(ws) { ws.send(encode({ type: 'ready', scope: ws.data.scope })) },
+ *     async message(ws, data) {
+ *       await handler.handleMessage(ws.data, data, (msg) => ws.send(msg))
+ *     },
+ *     async close(ws) { await handler.handleClose(ws.data) },
+ *   },
+ * })
+ * ```
+ */
+import { encode, decode } from '@msgpack/msgpack';
+import { createNamespaceRouter } from './namespace-router.js';
+import { YDocManager } from '../modules/brainy/ydoc-manager.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates a namespace-aware WebSocket handler that dispatches RPC through the
+ * same namespace router used by HTTP, plus Y.js collaborative editing.
+ *
+ * @param config - Handler configuration.
+ * @returns A {@link NamespaceWsHandler} instance.
+ */
+export function createNamespaceWsHandler(config) {
+    const { router: routerConfig, ydocManager } = config;
+    const router = createNamespaceRouter(routerConfig);
+    return {
+        async handleUpgrade(request) {
+            const url = new URL(request.url);
+            const scope = url.searchParams.get('scope') ?? '';
+            // Extract auth token — Bun/Node uses Authorization header; browsers use ?token= query.
+            const authHeader = request.headers.get('authorization') ?? '';
+            const token = authHeader.startsWith('Bearer ')
+                ? authHeader.slice(7)
+                : (url.searchParams.get('token') ?? '');
+            // Extract workspace ID from scope or header.
+            const workspaceId = request.headers.get('x-workspace-id') ??
+                url.searchParams.get('workspaceId') ??
+                scope;
+            // Build a synthetic RequestContext for the router's authenticate callback.
+            const ctx = {
+                request,
+                user: null,
+                workspaceId,
+            };
+            // Authenticate using the router's callback.
+            let user;
+            try {
+                user = await routerConfig.authenticate(ctx);
+            }
+            catch (err) {
+                console.error('[SDK/ws] authenticate threw during upgrade:', err);
+                return null;
+            }
+            if (!user)
+                return null;
+            // Resolve brain with the authenticated context.
+            ctx.user = user;
+            let brain;
+            try {
+                brain = await routerConfig.resolveBrain(ctx);
+            }
+            catch (err) {
+                console.error('[SDK/ws] resolveBrain threw during upgrade:', err);
+                return null;
+            }
+            const peerId = crypto.randomUUID();
+            return {
+                user,
+                workspaceId,
+                brain,
+                scope,
+                peerId,
+                broadcast: () => { }, // No-op until product server sets it in websocket.open()
+            };
+        },
+        async handleMessage(session, data, send) {
+            let decoded;
+            try {
+                decoded = decode(data instanceof ArrayBuffer ? new Uint8Array(data) : data);
+            }
+            catch {
+                return; // Malformed frame — silently ignore
+            }
+            if (!decoded || typeof decoded !== 'object')
+                return;
+            const msg = decoded;
+            // ── Y.js messages ──────────────────────────────────────────────────
+            if (typeof msg['type'] === 'string' && msg['type'].startsWith('y-')) {
+                await _handleYjsMessage(msg, session, send, ydocManager);
+                return;
+            }
+            // ── Namespace RPC ──────────────────────────────────────────────────
+            const id = msg['id'];
+            const ns = msg['ns'];
+            const method = msg['method'];
+            const args = msg['args'];
+            if (typeof id !== 'string' || typeof method !== 'string' || !Array.isArray(args)) {
+                return; // Not a valid RPC frame
+            }
+            // Default namespace to 'brainy' for backward compat with SDK 1.x clients
+            // that send { id, method, args } without an ns field.
+            const resolvedNs = typeof ns === 'string' ? ns : 'brainy';
+            const stream = msg['stream'] === true;
+            const rpc = { id, ns: resolvedNs, method, args, stream };
+            // Dispatch with pre-authenticated context — skips re-authentication.
+            // The user was already verified in handleUpgrade().
+            const preAuthCtx = {
+                user: session.user,
+                workspaceId: session.workspaceId,
+                request: new Request('http://localhost/api/rpc'),
+            };
+            const result = await router.dispatch(rpc, preAuthCtx);
+            if (result.type === 'response') {
+                send(encode(result.response));
+                return;
+            }
+            // Streaming response — iterate the async iterable and send frames.
+            if (result.type === 'stream') {
+                try {
+                    for await (const chunk of result.iterable) {
+                        const frame = { id, chunk };
+                        send(encode(frame));
+                    }
+                    send(encode({ id, done: true }));
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    send(encode({ id, error: message }));
+                }
+            }
+        },
+        async handleClose(session) {
+            if (!ydocManager)
+                return;
+            await ydocManager.onPeerDisconnectAll(session.scope, session.peerId);
+        },
+        broadcastChange(event, send) {
+            send(encode(event));
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Y.js message handler
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Routes a Y.js protocol message to the appropriate `YDocManager` method.
+ *
+ * ## Sync protocol (standard two-phase handshake):
+ * 1. Client sends `y-sync` with its state vector.
+ * 2. Server replies with `y-sync` diff (updates client is missing).
+ * 3. Client applies diff → sends `y-update` for pending local ops.
+ * 4. Steady state: all ops are `y-update` frames, broadcast to all other peers.
+ *
+ * ## Awareness:
+ * `y-awareness` frames carry cursor positions, user name/color. NOT persisted —
+ * forwarded to all other peers then discarded.
+ *
+ * @param msg - Decoded Y.js message frame.
+ * @param session - The WebSocket session for the sending peer.
+ * @param send - Sends a response to THIS peer only.
+ * @param ydocManager - The server-side Y.Doc pool (may be undefined if collab disabled).
+ */
+async function _handleYjsMessage(msg, session, send, ydocManager) {
+    if (!ydocManager)
+        return;
+    switch (msg.type) {
+        case 'y-sync': {
+            const clientSv = msg.stateVector instanceof Uint8Array
+                ? msg.stateVector
+                : new Uint8Array(Object.values(msg.stateVector));
+            const diff = await ydocManager.getDiff(session.scope, msg.filePath, session.brain, clientSv);
+            send(encode({ type: 'y-sync', filePath: msg.filePath, diff }));
+            break;
+        }
+        case 'y-update': {
+            const update = msg.update instanceof Uint8Array
+                ? msg.update
+                : new Uint8Array(Object.values(msg.update));
+            await ydocManager.getOrCreate(session.scope, msg.filePath, session.brain, session.peerId);
+            await ydocManager.applyUpdate(session.scope, msg.filePath, update);
+            const frame = encode({ type: 'y-update', filePath: msg.filePath, update });
+            session.broadcast(frame, session.peerId);
+            break;
+        }
+        case 'y-awareness': {
+            const update = msg.update instanceof Uint8Array
+                ? msg.update
+                : new Uint8Array(Object.values(msg.update));
+            const frame = encode({ type: 'y-awareness', update });
+            session.broadcast(frame, session.peerId);
+            break;
+        }
+    }
+}
+//# sourceMappingURL=ws-handler.js.map

package/dist/server/ws-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-handler.js","sourceRoot":"","sources":["../../src/server/ws-handler.ts"],"names":[],"mappings":"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"}

package/dist/transports/ws.d.ts

@@ -52,6 +52,7 @@
  * ```
  */
 import type { SDKTransport } from './transport.js';
+import type { NamespaceTransport } from '../client/namespace-proxy.js';
 import type { BrainyChangeEvent } from '../modules/brainy/events.js';
 /**
  * Transport that communicates via MessagePack-encoded WebSocket RPC.
@@ -63,7 +64,7 @@ import type { BrainyChangeEvent } from '../modules/brainy/events.js';
  * `createSDK` client factory calls this automatically when `sdk.connect()` is
  * invoked.
  */
-export declare class WsTransport implements SDKTransport {
+export declare class WsTransport implements SDKTransport, NamespaceTransport {
     private ws;
     private readonly wsUrl;
     private readonly authToken;
@@ -71,6 +72,7 @@ export declare class WsTransport implements SDKTransport {
     private readonly timeoutMs;
     private readonly maxReconnectAttempts;
     private readonly pending;
+    private readonly pendingStreams;
     private nextId;
     private connectionState;
     private readonly changeListeners;
@@ -99,6 +101,9 @@ export declare class WsTransport implements SDKTransport {
     /**
      * Sends a MessagePack-encoded RPC request and awaits the response.
      *
+     * Delegates to `callNs('brainy', method, args)` for backward compatibility
+     * with SDK 1.x callers that use the flat Brainy method namespace.
+     *
      * @param method - Dot-separated Brainy method name (e.g. `'vfs.readdir'`).
      * @param args - Positional arguments to forward.
      * @returns Whatever the server's Brainy method returns.
@@ -107,6 +112,29 @@ export declare class WsTransport implements SDKTransport {
      * @throws {@link SDKRpcError} if the server reports an error.
      */
     call(method: string, args: unknown[]): Promise<unknown>;
+    /**
+     * Sends a namespace-aware RPC request and awaits the response.
+     *
+     * @param ns - Target namespace (e.g. `'chat'`, `'graph'`, `'brainy.vfs'`).
+     * @param method - Method within the namespace (e.g. `'send'`, `'getData'`).
+     * @param args - Positional arguments.
+     * @returns The handler's return value.
+     * @throws {@link SDKDisconnectedError} if not connected.
+     * @throws {@link SDKTimeoutError} after `timeoutMs` ms.
+     * @throws {@link SDKRpcError} if the server reports an error.
+     */
+    callNs(ns: string, method: string, args: unknown[]): Promise<unknown>;
+    /**
+     * Sends a streaming namespace-aware RPC request and returns an async iterable
+     * that yields chunks as they arrive from the server.
+     *
+     * @param ns - Target namespace.
+     * @param method - Method within the namespace.
+     * @param args - Positional arguments.
+     * @returns An async iterable of response chunks.
+     * @throws {@link SDKDisconnectedError} if not connected.
+     */
+    callNsStream(ns: string, method: string, args: unknown[]): AsyncIterable<unknown>;
     /**
      * Registers a listener for real-time change push events from the server.
      *

package/dist/transports/ws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/transports/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAkDpE;;;;;;;;;GASG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAE7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,MAAM,CAAI;IAElB,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgD;IAEhF,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,aAAa,CAAoC;IAEzD,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,cAAc,CAA6C;IAEnE;;;;;;OAMG;gBAED,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,SAAS,EAClB,oBAAoB,SAAK;IAW3B;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAO/B;;;;;;;;;OASG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB7D;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI1D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAK3D;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;;;;;;;OASG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B9B,OAAO,CAAC,WAAW;IAuCnB,OAAO,CAAC,cAAc;IAsDtB,OAAO,CAAC,YAAY;IA2DpB,OAAO,CAAC,iBAAiB;CAO1B"}
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/transports/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AA2EpE;;;;;;;;;GASG;AACH,qBAAa,WAAY,YAAW,YAAY,EAAE,kBAAkB;IAClE,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAE7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmC;IAClE,OAAO,CAAC,MAAM,CAAI;IAElB,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgD;IAEhF,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,aAAa,CAAoC;IAEzD,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,cAAc,CAA6C;IAEnE;;;;;;OAMG;gBAED,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,SAAS,EAClB,oBAAoB,SAAK;IAW3B;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAO/B;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAM7D;;;;;;;;;;OAUG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB3E;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC;IA+EjF;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI1D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAK3D;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;;;;;;;OASG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B9B,OAAO,CAAC,WAAW;IAuCnB,OAAO,CAAC,cAAc;IAyEtB,OAAO,CAAC,YAAY;IA2DpB,OAAO,CAAC,iBAAiB;CAa1B"}