@richie-rpc/server 1.2.3 → 1.2.5

package/dist/mjs/websocket.mjs

@@ -0,0 +1,212 @@
+// @bun
+// packages/server/websocket.ts
+import { matchPath, parseQuery } from "@richie-rpc/core";
+
+class WebSocketValidationError extends Error {
+  messageType;
+  issues;
+  constructor(messageType, issues) {
+    super(`Validation failed for WebSocket message type: ${messageType}`);
+    this.messageType = messageType;
+    this.issues = issues;
+    this.name = "WebSocketValidationError";
+  }
+}
+function createTypedWebSocket(ws) {
+  return {
+    get raw() {
+      return ws;
+    },
+    send(type, payload) {
+      ws.send(JSON.stringify({ type, payload }));
+    },
+    subscribe(topic) {
+      ws.subscribe(topic);
+    },
+    unsubscribe(topic) {
+      ws.unsubscribe(topic);
+    },
+    publish(topic, type, payload) {
+      ws.publish(topic, JSON.stringify({ type, payload }));
+    },
+    close(code, reason) {
+      ws.close(code, reason);
+    },
+    get data() {
+      return ws.data;
+    }
+  };
+}
+
+class WebSocketRouter {
+  contract;
+  handlers;
+  basePath;
+  contextFactory;
+  constructor(contract, handlers, options) {
+    this.contract = contract;
+    this.handlers = handlers;
+    const bp = options?.basePath || "";
+    if (bp) {
+      this.basePath = bp.startsWith("/") ? bp : `/${bp}`;
+      this.basePath = this.basePath.endsWith("/") ? this.basePath.slice(0, -1) : this.basePath;
+    } else {
+      this.basePath = "";
+    }
+    this.contextFactory = options?.context;
+  }
+  findEndpoint(path) {
+    for (const [name, endpoint] of Object.entries(this.contract)) {
+      const params = matchPath(endpoint.path, path);
+      if (params !== null) {
+        return {
+          name,
+          endpoint,
+          params
+        };
+      }
+    }
+    return null;
+  }
+  parseUpgradeParams(request, endpoint, pathParams) {
+    const url = new URL(request.url);
+    let params = pathParams;
+    if (endpoint.params) {
+      const result = endpoint.params.safeParse(pathParams);
+      if (!result.success) {
+        throw new Error(`Invalid path params: ${result.error.message}`);
+      }
+      params = result.data;
+    }
+    let query = {};
+    if (endpoint.query) {
+      const queryData = parseQuery(url.searchParams);
+      const result = endpoint.query.safeParse(queryData);
+      if (!result.success) {
+        throw new Error(`Invalid query params: ${result.error.message}`);
+      }
+      query = result.data;
+    }
+    let headers = {};
+    if (endpoint.headers) {
+      const headersObj = {};
+      request.headers.forEach((value, key) => {
+        headersObj[key] = value;
+      });
+      const result = endpoint.headers.safeParse(headersObj);
+      if (!result.success) {
+        throw new Error(`Invalid headers: ${result.error.message}`);
+      }
+      headers = result.data;
+    }
+    return { params, query, headers };
+  }
+  async matchAndPrepareUpgrade(request) {
+    const url = new URL(request.url);
+    let path = url.pathname;
+    if (this.basePath && path.startsWith(this.basePath)) {
+      path = path.slice(this.basePath.length) || "/";
+    }
+    const match = this.findEndpoint(path);
+    if (!match) {
+      return null;
+    }
+    const { name, endpoint, params: rawParams } = match;
+    try {
+      const { params, query, headers } = this.parseUpgradeParams(request, endpoint, rawParams);
+      const context = this.contextFactory ? await this.contextFactory(request, String(name), endpoint) : undefined;
+      return {
+        endpointName: String(name),
+        endpoint,
+        params,
+        query,
+        headers,
+        context,
+        state: {}
+      };
+    } catch (err) {
+      console.error("WebSocket upgrade validation failed:", err);
+      return null;
+    }
+  }
+  validateMessage(endpoint, rawMessage) {
+    const messageStr = typeof rawMessage === "string" ? rawMessage : new TextDecoder().decode(rawMessage);
+    const parsed = JSON.parse(messageStr);
+    const { type, payload } = parsed;
+    const messageDef = endpoint.clientMessages[type];
+    if (!messageDef) {
+      throw new WebSocketValidationError(type, [
+        {
+          code: "custom",
+          path: ["type"],
+          message: `Unknown message type: ${type}`
+        }
+      ]);
+    }
+    const result = messageDef.payload.safeParse(payload);
+    if (!result.success) {
+      throw new WebSocketValidationError(type, result.error.issues);
+    }
+    return { type, payload: result.data };
+  }
+  get websocketHandler() {
+    return {
+      open: async (ws) => {
+        const data = ws.data;
+        const endpointHandlers = this.handlers[data.endpointName];
+        if (!endpointHandlers)
+          return;
+        const typedWs = createTypedWebSocket(ws);
+        if (endpointHandlers.open) {
+          await endpointHandlers.open(typedWs, data.context);
+        }
+      },
+      message: async (ws, message) => {
+        const data = ws.data;
+        const endpointHandlers = this.handlers[data.endpointName];
+        if (!endpointHandlers)
+          return;
+        const typedWs = createTypedWebSocket(ws);
+        try {
+          const validatedMessage = this.validateMessage(data.endpoint, typeof message === "string" ? message : message.buffer);
+          await endpointHandlers.message(typedWs, validatedMessage, data.context);
+        } catch (err) {
+          if (err instanceof WebSocketValidationError) {
+            if (endpointHandlers.validationError) {
+              endpointHandlers.validationError(typedWs, err, data.context);
+            } else {
+              typedWs.send("error", {
+                code: "VALIDATION_ERROR",
+                message: err.message,
+                issues: err.issues
+              });
+            }
+          } else {
+            console.error("WebSocket message handler error:", err);
+          }
+        }
+      },
+      close: (ws, _code, _reason) => {
+        const data = ws.data;
+        const endpointHandlers = this.handlers[data.endpointName];
+        if (!endpointHandlers)
+          return;
+        const typedWs = createTypedWebSocket(ws);
+        if (endpointHandlers.close) {
+          endpointHandlers.close(typedWs, data.context);
+        }
+      },
+      drain: () => {}
+    };
+  }
+}
+function createWebSocketRouter(contract, handlers, options) {
+  return new WebSocketRouter(contract, handlers, options);
+}
+export {
+  createWebSocketRouter,
+  WebSocketValidationError,
+  WebSocketRouter
+};
+
+//# debugId=47CE29C068793DD164756E2164756E21

package/dist/mjs/websocket.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../websocket.ts"],
+  "sourcesContent": [
+    "import type {\n  ExtractClientMessage,\n  ExtractWSHeaders,\n  ExtractWSParams,\n  ExtractWSQuery,\n  WebSocketContract,\n  WebSocketContractDefinition,\n} from '@richie-rpc/core';\nimport { matchPath, parseQuery } from '@richie-rpc/core';\nimport type { z } from 'zod';\n\n/**\n * Validation error for WebSocket messages\n */\nexport class WebSocketValidationError extends Error {\n  constructor(\n    public messageType: string,\n    public issues: z.ZodIssue[],\n  ) {\n    super(`Validation failed for WebSocket message type: ${messageType}`);\n    this.name = 'WebSocketValidationError';\n  }\n}\n\n/**\n * Data attached to WebSocket connections for routing\n */\nexport interface WebSocketData<\n  T extends WebSocketContractDefinition = WebSocketContractDefinition,\n  S = unknown,\n> {\n  endpointName: string;\n  endpoint: T;\n  params: ExtractWSParams<T>;\n  query: ExtractWSQuery<T>;\n  headers: ExtractWSHeaders<T>;\n  context: unknown;\n  state: S;\n}\n\n/**\n * Typed WebSocket wrapper for sending messages\n */\nexport interface TypedServerWebSocket<T extends WebSocketContractDefinition, S = unknown> {\n  /** The underlying Bun WebSocket */\n  readonly raw: WebSocket;\n  /** Send a typed message to the client */\n  send<K extends keyof T['serverMessages']>(\n    type: K,\n    payload: z.infer<T['serverMessages'][K]['payload']>,\n  ): void;\n  /** Subscribe to a topic for pub/sub */\n  subscribe(topic: string): void;\n  /** Unsubscribe from a topic */\n  unsubscribe(topic: string): void;\n  /** Publish a message to a topic */\n  publish<K extends keyof T['serverMessages']>(\n    topic: string,\n    type: K,\n    payload: z.infer<T['serverMessages'][K]['payload']>,\n  ): void;\n  /** Close the connection */\n  close(code?: number, reason?: string): void;\n  /** Connection data */\n  readonly data: WebSocketData<T, S>;\n}\n\n/**\n * Handler functions for a WebSocket endpoint\n */\nexport interface WebSocketEndpointHandlers<\n  T extends WebSocketContractDefinition,\n  C = unknown,\n  S = unknown,\n> {\n  /** Called when connection opens */\n  open?(ws: TypedServerWebSocket<T, S>, ctx: C): void | Promise<void>;\n  /** Called for each validated message */\n  message(\n    ws: TypedServerWebSocket<T, S>,\n    message: ExtractClientMessage<T>,\n    ctx: C,\n  ): void | Promise<void>;\n  /** Called when connection closes */\n  close?(ws: TypedServerWebSocket<T, S>, ctx: C): void;\n  /** Called when message validation fails */\n  validationError?(ws: TypedServerWebSocket<T, S>, error: WebSocketValidationError, ctx: C): void;\n}\n\n/**\n * Contract handlers mapping for WebSocket endpoints\n */\nexport type WebSocketContractHandlers<T extends WebSocketContract, C = unknown, S = unknown> = {\n  [K in keyof T]: WebSocketEndpointHandlers<T[K], C, S>;\n};\n\n/**\n * Upgrade data returned by matchAndPrepareUpgrade\n */\nexport interface UpgradeData<S = unknown> {\n  endpointName: string;\n  endpoint: WebSocketContractDefinition;\n  params: Record<string, string>;\n  query: Record<string, string | string[]>;\n  headers: Record<string, string>;\n  context: unknown;\n  state: S;\n}\n\n/**\n * Options for WebSocket router\n */\nexport interface WebSocketRouterOptions<C = unknown, S = unknown> {\n  basePath?: string;\n  context?: (\n    request: Request,\n    endpointName: string,\n    endpoint: WebSocketContractDefinition,\n  ) => C | Promise<C>;\n  /** Type hint for per-connection state. Use `{} as YourStateType` */\n  state?: S;\n}\n\n/**\n * Bun WebSocket handler type (subset of Bun's types)\n */\nexport interface BunWebSocketHandler<T = unknown> {\n  open(ws: Bun.ServerWebSocket<T>): void | Promise<void>;\n  message(ws: Bun.ServerWebSocket<T>, message: string | Buffer<ArrayBuffer>): void | Promise<void>;\n  close(ws: Bun.ServerWebSocket<T>, code: number, reason: string): void;\n  drain(ws: Bun.ServerWebSocket<T>): void;\n}\n\n/**\n * Create a typed WebSocket wrapper\n */\nfunction createTypedWebSocket<T extends WebSocketContractDefinition, S = unknown>(\n  ws: WebSocket & { data: WebSocketData<T, S> },\n): TypedServerWebSocket<T, S> {\n  return {\n    get raw() {\n      return ws;\n    },\n    send(type, payload) {\n      ws.send(JSON.stringify({ type, payload }));\n    },\n    subscribe(topic) {\n      (ws as any).subscribe(topic);\n    },\n    unsubscribe(topic) {\n      (ws as any).unsubscribe(topic);\n    },\n    publish(topic, type, payload) {\n      (ws as any).publish(topic, JSON.stringify({ type, payload }));\n    },\n    close(code, reason) {\n      ws.close(code, reason);\n    },\n    get data() {\n      return ws.data;\n    },\n  };\n}\n\n/**\n * WebSocket router for managing WebSocket contract endpoints\n */\nexport class WebSocketRouter<T extends WebSocketContract, C = unknown, S = unknown> {\n  private basePath: string;\n  private contextFactory?: (\n    request: Request,\n    endpointName: string,\n    endpoint: WebSocketContractDefinition,\n  ) => C | Promise<C>;\n\n  constructor(\n    private contract: T,\n    private handlers: WebSocketContractHandlers<T, C, S>,\n    options?: WebSocketRouterOptions<C, S>,\n  ) {\n    // Normalize basePath\n    const bp = options?.basePath || '';\n    if (bp) {\n      this.basePath = bp.startsWith('/') ? bp : `/${bp}`;\n      this.basePath = this.basePath.endsWith('/') ? this.basePath.slice(0, -1) : this.basePath;\n    } else {\n      this.basePath = '';\n    }\n    this.contextFactory = options?.context;\n  }\n\n  /**\n   * Find matching endpoint for a path\n   */\n  private findEndpoint(path: string): {\n    name: keyof T;\n    endpoint: WebSocketContractDefinition;\n    params: Record<string, string>;\n  } | null {\n    for (const [name, endpoint] of Object.entries(this.contract)) {\n      const params = matchPath(endpoint.path, path);\n      if (params !== null) {\n        return {\n          name,\n          endpoint: endpoint as WebSocketContractDefinition,\n          params,\n        };\n      }\n    }\n    return null;\n  }\n\n  /**\n   * Parse and validate upgrade request parameters\n   */\n  private parseUpgradeParams(\n    request: Request,\n    endpoint: WebSocketContractDefinition,\n    pathParams: Record<string, string>,\n  ): { params: any; query: any; headers: any } {\n    const url = new URL(request.url);\n\n    // Parse and validate path params\n    let params: any = pathParams;\n    if (endpoint.params) {\n      const result = endpoint.params.safeParse(pathParams);\n      if (!result.success) {\n        throw new Error(`Invalid path params: ${result.error.message}`);\n      }\n      params = result.data;\n    }\n\n    // Parse and validate query params\n    let query: any = {};\n    if (endpoint.query) {\n      const queryData = parseQuery(url.searchParams);\n      const result = endpoint.query.safeParse(queryData);\n      if (!result.success) {\n        throw new Error(`Invalid query params: ${result.error.message}`);\n      }\n      query = result.data;\n    }\n\n    // Parse and validate headers\n    let headers: any = {};\n    if (endpoint.headers) {\n      const headersObj: Record<string, string> = {};\n      request.headers.forEach((value, key) => {\n        headersObj[key] = value;\n      });\n      const result = endpoint.headers.safeParse(headersObj);\n      if (!result.success) {\n        throw new Error(`Invalid headers: ${result.error.message}`);\n      }\n      headers = result.data;\n    }\n\n    return { params, query, headers };\n  }\n\n  /**\n   * Match a request and prepare upgrade data\n   * Returns null if no match, or UpgradeData for server.upgrade()\n   */\n  async matchAndPrepareUpgrade(request: Request): Promise<UpgradeData<S> | null> {\n    const url = new URL(request.url);\n    let path = url.pathname;\n\n    // Strip basePath if configured\n    if (this.basePath && path.startsWith(this.basePath)) {\n      path = path.slice(this.basePath.length) || '/';\n    }\n\n    const match = this.findEndpoint(path);\n    if (!match) {\n      return null;\n    }\n\n    const { name, endpoint, params: rawParams } = match;\n\n    try {\n      const { params, query, headers } = this.parseUpgradeParams(request, endpoint, rawParams);\n\n      // Create context if factory provided\n      const context = this.contextFactory\n        ? await this.contextFactory(request, String(name), endpoint)\n        : (undefined as C);\n\n      return {\n        endpointName: String(name),\n        endpoint,\n        params,\n        query,\n        headers,\n        context,\n        state: {} as S,\n      };\n    } catch (err) {\n      // Validation failed during upgrade\n      console.error('WebSocket upgrade validation failed:', err);\n      return null;\n    }\n  }\n\n  /**\n   * Validate an incoming client message\n   */\n  private validateMessage(\n    endpoint: WebSocketContractDefinition,\n    rawMessage: string | ArrayBuffer,\n  ): ExtractClientMessage<typeof endpoint> {\n    // Parse message\n    const messageStr =\n      typeof rawMessage === 'string' ? rawMessage : new TextDecoder().decode(rawMessage);\n    const parsed = JSON.parse(messageStr) as { type: string; payload: unknown };\n\n    const { type, payload } = parsed;\n\n    // Find the schema for this message type\n    const messageDef = endpoint.clientMessages[type];\n    if (!messageDef) {\n      throw new WebSocketValidationError(type, [\n        {\n          code: 'custom',\n          path: ['type'],\n          message: `Unknown message type: ${type}`,\n        },\n      ]);\n    }\n\n    // Validate payload\n    const result = messageDef.payload.safeParse(payload);\n    if (!result.success) {\n      throw new WebSocketValidationError(type, result.error.issues);\n    }\n\n    return { type, payload: result.data } as ExtractClientMessage<typeof endpoint>;\n  }\n\n  /**\n   * Get Bun-compatible WebSocket handler\n   */\n  get websocketHandler(): BunWebSocketHandler<UpgradeData<S>> {\n    return {\n      open: async (ws) => {\n        const data = ws.data;\n        const endpointHandlers = this.handlers[data.endpointName as keyof T];\n        if (!endpointHandlers) return;\n\n        // Create typed wrapper with properly typed data\n        const typedWs = createTypedWebSocket(\n          ws as unknown as WebSocket & {\n            data: WebSocketData<WebSocketContractDefinition, S>;\n          },\n        );\n\n        if (endpointHandlers.open) {\n          await endpointHandlers.open(typedWs as any, data.context as C);\n        }\n      },\n\n      message: async (ws, message) => {\n        const data = ws.data;\n        const endpointHandlers = this.handlers[data.endpointName as keyof T];\n        if (!endpointHandlers) return;\n\n        const typedWs = createTypedWebSocket(\n          ws as unknown as WebSocket & {\n            data: WebSocketData<WebSocketContractDefinition, S>;\n          },\n        );\n\n        try {\n          // Validate the message\n          const validatedMessage = this.validateMessage(\n            data.endpoint,\n            typeof message === 'string' ? message : message.buffer,\n          );\n\n          // Call handler with validated message\n          await endpointHandlers.message(\n            typedWs as any,\n            validatedMessage as any,\n            data.context as C,\n          );\n        } catch (err) {\n          if (err instanceof WebSocketValidationError) {\n            // Call validation error handler if provided\n            if (endpointHandlers.validationError) {\n              endpointHandlers.validationError(typedWs as any, err, data.context as C);\n            } else {\n              // Default: send error message back\n              typedWs.send(\n                'error' as any,\n                {\n                  code: 'VALIDATION_ERROR',\n                  message: err.message,\n                  issues: err.issues,\n                } as any,\n              );\n            }\n          } else {\n            console.error('WebSocket message handler error:', err);\n          }\n        }\n      },\n\n      close: (ws, _code, _reason) => {\n        const data = ws.data;\n        const endpointHandlers = this.handlers[data.endpointName as keyof T];\n        if (!endpointHandlers) return;\n\n        const typedWs = createTypedWebSocket(\n          ws as unknown as WebSocket & {\n            data: WebSocketData<WebSocketContractDefinition, S>;\n          },\n        );\n\n        if (endpointHandlers.close) {\n          endpointHandlers.close(typedWs as any, data.context as C);\n        }\n      },\n      drain: () => {\n        // not used\n      },\n    };\n  }\n}\n\n/**\n * Create a WebSocket router from a contract and handlers\n */\nexport function createWebSocketRouter<T extends WebSocketContract, C = unknown, S = unknown>(\n  contract: T,\n  handlers: WebSocketContractHandlers<T, C, S>,\n  options?: WebSocketRouterOptions<C, S>,\n): WebSocketRouter<T, C, S> {\n  return new WebSocketRouter(contract, handlers, options);\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "47CE29C068793DD164756E2164756E21",
+  "names": []
+}

package/dist/types/index.d.ts

@@ -1,8 +1,8 @@
-import type { Contract, EndpointDefinition, ExtractBody, ExtractHeaders, ExtractParams, ExtractQuery } from '@richie-rpc/core';
+import type { Contract, DownloadEndpointDefinition, EndpointDefinition, ExtractBody, ExtractChunk, ExtractFinalResponse, ExtractHeaders, ExtractParams, ExtractQuery, ExtractSSEEventData, SSEEndpointDefinition, StandardEndpointDefinition, StreamingEndpointDefinition } from '@richie-rpc/core';
 import { Status } from '@richie-rpc/core';
 import type { z } from 'zod';
 export { Status };
-export type HandlerInput<T extends EndpointDefinition, C = unknown> = {
+export type HandlerInput<T extends StandardEndpointDefinition, C = unknown> = {
     params: ExtractParams<T>;
     query: ExtractQuery<T>;
     headers: ExtractHeaders<T>;
@@ -10,16 +10,106 @@ export type HandlerInput<T extends EndpointDefinition, C = unknown> = {
     request: Request;
     context: C;
 };
-export type HandlerResponse<T extends EndpointDefinition> = {
+export type HandlerResponse<T extends StandardEndpointDefinition> = {
     [Status in keyof T['responses']]: {
         status: Status;
         body: T['responses'][Status] extends z.ZodTypeAny ? z.infer<T['responses'][Status]> : never;
         headers?: Record<string, string>;
     };
 }[keyof T['responses']];
-export type Handler<T extends EndpointDefinition, C = unknown> = (input: HandlerInput<T, C>) => Promise<HandlerResponse<T>> | HandlerResponse<T>;
+export type Handler<T extends StandardEndpointDefinition, C = unknown> = (input: HandlerInput<T, C>) => Promise<HandlerResponse<T>> | HandlerResponse<T>;
+/**
+ * Emitter for streaming responses - push-based API
+ */
+export interface StreamEmitter<T extends StreamingEndpointDefinition> {
+    /** Send a chunk to the client */
+    send(chunk: ExtractChunk<T>): void;
+    /** Close the stream with optional final response */
+    close(final?: ExtractFinalResponse<T>): void;
+    /** Check if stream is still open */
+    readonly isOpen: boolean;
+}
+/**
+ * Handler input for streaming endpoints
+ */
+export type StreamingHandlerInput<T extends StreamingEndpointDefinition, C = unknown> = {
+    params: ExtractParams<T>;
+    query: ExtractQuery<T>;
+    headers: ExtractHeaders<T>;
+    body: ExtractBody<T>;
+    request: Request;
+    context: C;
+    stream: StreamEmitter<T>;
+};
+/**
+ * Handler function type for streaming endpoints
+ */
+export type StreamingHandler<T extends StreamingEndpointDefinition, C = unknown> = (input: StreamingHandlerInput<T, C>) => void | Promise<void>;
+/**
+ * Emitter for SSE responses
+ */
+export interface SSEEmitter<T extends SSEEndpointDefinition> {
+    /** Send an event to the client */
+    send<K extends keyof T['events']>(event: K, data: ExtractSSEEventData<T, K>, options?: {
+        id?: string;
+    }): void;
+    /** Close the connection */
+    close(): void;
+    /** Check if connection is still open */
+    readonly isOpen: boolean;
+}
+/**
+ * Handler input for SSE endpoints
+ */
+export type SSEHandlerInput<T extends SSEEndpointDefinition, C = unknown> = {
+    params: ExtractParams<T>;
+    query: ExtractQuery<T>;
+    headers: ExtractHeaders<T>;
+    request: Request;
+    context: C;
+    emitter: SSEEmitter<T>;
+    /** AbortSignal for detecting client disconnect */
+    signal: AbortSignal;
+};
+/**
+ * Handler function type for SSE endpoints
+ * Returns an optional cleanup function
+ */
+export type SSEHandler<T extends SSEEndpointDefinition, C = unknown> = (input: SSEHandlerInput<T, C>) => void | (() => void) | Promise<void | (() => void)>;
+/**
+ * Handler input for download endpoints
+ */
+export type DownloadHandlerInput<T extends DownloadEndpointDefinition, C = unknown> = {
+    params: ExtractParams<T>;
+    query: ExtractQuery<T>;
+    headers: ExtractHeaders<T>;
+    request: Request;
+    context: C;
+};
+/**
+ * Handler response for download endpoints
+ * Success (200) returns File, errors return typed response
+ */
+export type DownloadHandlerResponse<T extends DownloadEndpointDefinition> = {
+    status: 200;
+    body: File;
+    headers?: Record<string, string>;
+} | (T['errorResponses'] extends Record<number, z.ZodTypeAny> ? {
+    [S in keyof T['errorResponses']]: {
+        status: S;
+        body: T['errorResponses'][S] extends z.ZodTypeAny ? z.infer<T['errorResponses'][S]> : never;
+        headers?: Record<string, string>;
+    };
+}[keyof T['errorResponses']] : never);
+/**
+ * Handler function type for download endpoints
+ */
+export type DownloadHandler<T extends DownloadEndpointDefinition, C = unknown> = (input: DownloadHandlerInput<T, C>) => Promise<DownloadHandlerResponse<T>> | DownloadHandlerResponse<T>;
+/**
+ * Contract handlers mapping - conditionally applies handler type based on endpoint type
+ */
 export type ContractHandlers<T extends Contract, C = unknown> = {
-    [K in keyof T]: Handler<T[K], C>;
+    [K in keyof T]: T[K] extends StandardEndpointDefinition ? Handler<T[K], C> : T[K] extends StreamingEndpointDefinition ? StreamingHandler<T[K], C> : T[K] extends SSEEndpointDefinition ? SSEHandler<T[K], C> : T[K] extends DownloadEndpointDefinition ? DownloadHandler<T[K], C> : never;
 };
 export declare class ValidationError extends Error {
     field: string;
@@ -64,3 +154,4 @@ export declare class Router<T extends Contract, C = unknown> {
  * Create a router from a contract and handlers
  */
 export declare function createRouter<T extends Contract, C = unknown>(contract: T, handlers: ContractHandlers<T, C>, options?: RouterOptions<C>): Router<T, C>;
+export { createWebSocketRouter } from './websocket';

package/dist/types/websocket.d.ts

@@ -0,0 +1,125 @@
+import type { ExtractClientMessage, ExtractWSHeaders, ExtractWSParams, ExtractWSQuery, WebSocketContract, WebSocketContractDefinition } from '@richie-rpc/core';
+import type { z } from 'zod';
+/**
+ * Validation error for WebSocket messages
+ */
+export declare class WebSocketValidationError extends Error {
+    messageType: string;
+    issues: z.ZodIssue[];
+    constructor(messageType: string, issues: z.ZodIssue[]);
+}
+/**
+ * Data attached to WebSocket connections for routing
+ */
+export interface WebSocketData<T extends WebSocketContractDefinition = WebSocketContractDefinition, S = unknown> {
+    endpointName: string;
+    endpoint: T;
+    params: ExtractWSParams<T>;
+    query: ExtractWSQuery<T>;
+    headers: ExtractWSHeaders<T>;
+    context: unknown;
+    state: S;
+}
+/**
+ * Typed WebSocket wrapper for sending messages
+ */
+export interface TypedServerWebSocket<T extends WebSocketContractDefinition, S = unknown> {
+    /** The underlying Bun WebSocket */
+    readonly raw: WebSocket;
+    /** Send a typed message to the client */
+    send<K extends keyof T['serverMessages']>(type: K, payload: z.infer<T['serverMessages'][K]['payload']>): void;
+    /** Subscribe to a topic for pub/sub */
+    subscribe(topic: string): void;
+    /** Unsubscribe from a topic */
+    unsubscribe(topic: string): void;
+    /** Publish a message to a topic */
+    publish<K extends keyof T['serverMessages']>(topic: string, type: K, payload: z.infer<T['serverMessages'][K]['payload']>): void;
+    /** Close the connection */
+    close(code?: number, reason?: string): void;
+    /** Connection data */
+    readonly data: WebSocketData<T, S>;
+}
+/**
+ * Handler functions for a WebSocket endpoint
+ */
+export interface WebSocketEndpointHandlers<T extends WebSocketContractDefinition, C = unknown, S = unknown> {
+    /** Called when connection opens */
+    open?(ws: TypedServerWebSocket<T, S>, ctx: C): void | Promise<void>;
+    /** Called for each validated message */
+    message(ws: TypedServerWebSocket<T, S>, message: ExtractClientMessage<T>, ctx: C): void | Promise<void>;
+    /** Called when connection closes */
+    close?(ws: TypedServerWebSocket<T, S>, ctx: C): void;
+    /** Called when message validation fails */
+    validationError?(ws: TypedServerWebSocket<T, S>, error: WebSocketValidationError, ctx: C): void;
+}
+/**
+ * Contract handlers mapping for WebSocket endpoints
+ */
+export type WebSocketContractHandlers<T extends WebSocketContract, C = unknown, S = unknown> = {
+    [K in keyof T]: WebSocketEndpointHandlers<T[K], C, S>;
+};
+/**
+ * Upgrade data returned by matchAndPrepareUpgrade
+ */
+export interface UpgradeData<S = unknown> {
+    endpointName: string;
+    endpoint: WebSocketContractDefinition;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    headers: Record<string, string>;
+    context: unknown;
+    state: S;
+}
+/**
+ * Options for WebSocket router
+ */
+export interface WebSocketRouterOptions<C = unknown, S = unknown> {
+    basePath?: string;
+    context?: (request: Request, endpointName: string, endpoint: WebSocketContractDefinition) => C | Promise<C>;
+    /** Type hint for per-connection state. Use `{} as YourStateType` */
+    state?: S;
+}
+/**
+ * Bun WebSocket handler type (subset of Bun's types)
+ */
+export interface BunWebSocketHandler<T = unknown> {
+    open(ws: Bun.ServerWebSocket<T>): void | Promise<void>;
+    message(ws: Bun.ServerWebSocket<T>, message: string | Buffer<ArrayBuffer>): void | Promise<void>;
+    close(ws: Bun.ServerWebSocket<T>, code: number, reason: string): void;
+    drain(ws: Bun.ServerWebSocket<T>): void;
+}
+/**
+ * WebSocket router for managing WebSocket contract endpoints
+ */
+export declare class WebSocketRouter<T extends WebSocketContract, C = unknown, S = unknown> {
+    private contract;
+    private handlers;
+    private basePath;
+    private contextFactory?;
+    constructor(contract: T, handlers: WebSocketContractHandlers<T, C, S>, options?: WebSocketRouterOptions<C, S>);
+    /**
+     * Find matching endpoint for a path
+     */
+    private findEndpoint;
+    /**
+     * Parse and validate upgrade request parameters
+     */
+    private parseUpgradeParams;
+    /**
+     * Match a request and prepare upgrade data
+     * Returns null if no match, or UpgradeData for server.upgrade()
+     */
+    matchAndPrepareUpgrade(request: Request): Promise<UpgradeData<S> | null>;
+    /**
+     * Validate an incoming client message
+     */
+    private validateMessage;
+    /**
+     * Get Bun-compatible WebSocket handler
+     */
+    get websocketHandler(): BunWebSocketHandler<UpgradeData<S>>;
+}
+/**
+ * Create a WebSocket router from a contract and handlers
+ */
+export declare function createWebSocketRouter<T extends WebSocketContract, C = unknown, S = unknown>(contract: T, handlers: WebSocketContractHandlers<T, C, S>, options?: WebSocketRouterOptions<C, S>): WebSocketRouter<T, C, S>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@richie-rpc/server",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "main": "./dist/cjs/index.cjs",
   "exports": {
     ".": {
@@ -10,7 +10,7 @@
     }
   },
   "peerDependencies": {
-    "@richie-rpc/core": "^1.2.2",
+    "@richie-rpc/core": "^1.2.4",
     "typescript": "^5",
     "zod": "^4.1.12"
   },