@roj-ai/transport 0.0.2

package/dist/core/protocol.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Protocol Definition API
+ *
+ * Provides a type-safe way to define RPC-like protocols for WebSocket communication.
+ * Inspired by tRPC but designed for bidirectional WebSocket protocols.
+ */
+import { z } from 'zod';
+import type { Result } from './result.js';
+/**
+ * Definition for a request-response method.
+ */
+export interface MethodDef<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny, TError extends z.ZodTypeAny = z.ZodTypeAny> {
+    _type: 'method';
+    input: TInput;
+    output: TOutput;
+    error: TError;
+}
+/**
+ * Definition for a fire-and-forget notification.
+ */
+export interface NotificationDef<TInput extends z.ZodTypeAny = z.ZodTypeAny> {
+    _type: 'notification';
+    input: TInput;
+}
+/**
+ * A single endpoint definition (method or notification).
+ */
+export type EndpointDef = MethodDef | NotificationDef;
+/**
+ * Protocol definition - a collection of named endpoints.
+ */
+export interface ProtocolDef {
+    [key: string]: EndpointDef;
+}
+/**
+ * Extract input type from an endpoint definition.
+ */
+export type InferInput<T extends EndpointDef> = T extends MethodDef<infer I, infer _O, infer _E> ? z.infer<I> : T extends NotificationDef<infer I> ? z.infer<I> : never;
+/**
+ * Extract output type from a method definition.
+ */
+export type InferOutput<T extends MethodDef> = T extends MethodDef<infer _I, infer O, infer _E> ? z.infer<O> : never;
+/**
+ * Extract error type from a method definition.
+ */
+export type InferError<T extends MethodDef> = T extends MethodDef<infer _I, infer _O, infer E> ? z.infer<E> : never;
+/**
+ * Check if endpoint is a method.
+ */
+export type IsMethod<T extends EndpointDef> = T extends MethodDef ? true : false;
+/**
+ * Check if endpoint is a notification.
+ */
+export type IsNotification<T extends EndpointDef> = T extends NotificationDef ? true : false;
+/**
+ * Handler context passed to method/notification handlers.
+ */
+export interface HandlerContext {
+    /** Connection identifier */
+    connectionId: string;
+    /** Additional context data (platform-specific) */
+    [key: string]: unknown;
+}
+/**
+ * Handler for a method endpoint.
+ */
+export type MethodHandler<T extends MethodDef> = (input: InferInput<T>, ctx: HandlerContext) => Promise<Result<InferOutput<T>, InferError<T>>>;
+/**
+ * Handler for a notification endpoint.
+ */
+export type NotificationHandler<T extends NotificationDef> = (input: InferInput<T>, ctx: HandlerContext) => Promise<void>;
+/**
+ * Handler for an endpoint (method or notification).
+ */
+export type EndpointHandler<T extends EndpointDef> = T extends MethodDef ? MethodHandler<T> : T extends NotificationDef ? NotificationHandler<T> : never;
+/**
+ * Handlers object for a protocol.
+ */
+export type ProtocolHandlers<T extends ProtocolDef> = {
+    [K in keyof T]: EndpointHandler<T[K]>;
+};
+/**
+ * Caller function for a method endpoint.
+ */
+export type MethodCaller<T extends MethodDef> = (input: InferInput<T>) => Promise<Result<InferOutput<T>, InferError<T>>>;
+/**
+ * Notifier function for a notification endpoint.
+ */
+export type NotificationNotifier<T extends NotificationDef> = (input: InferInput<T>) => void;
+/**
+ * Caller object for methods in a protocol.
+ * Only includes method endpoints.
+ */
+export type ProtocolCaller<T extends ProtocolDef> = {
+    [K in keyof T as T[K] extends MethodDef ? K : never]: T[K] extends MethodDef ? MethodCaller<T[K]> : never;
+};
+/**
+ * Notifier object for notifications in a protocol.
+ * Only includes notification endpoints.
+ */
+export type ProtocolNotifier<T extends ProtocolDef> = {
+    [K in keyof T as T[K] extends NotificationDef ? K : never]: T[K] extends NotificationDef ? NotificationNotifier<T[K]> : never;
+};
+/**
+ * Options for method definition.
+ */
+export interface MethodOptions<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, TError extends z.ZodTypeAny> {
+    /** Input schema (what the caller sends) */
+    input: TInput;
+    /** Output schema (what the handler returns on success) */
+    output: TOutput;
+    /** Error schema (what the handler returns on failure) */
+    error: TError;
+}
+/**
+ * Define a request-response method endpoint.
+ */
+export declare function method<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, TError extends z.ZodTypeAny>(options: MethodOptions<TInput, TOutput, TError>): MethodDef<TInput, TOutput, TError>;
+/**
+ * Options for notification definition.
+ */
+export interface NotificationOptions<TInput extends z.ZodTypeAny> {
+    /** Input schema (what is sent) */
+    input: TInput;
+}
+/**
+ * Define a fire-and-forget notification endpoint.
+ */
+export declare function notification<TInput extends z.ZodTypeAny>(options: NotificationOptions<TInput>): NotificationDef<TInput>;
+/**
+ * Safe parse result type (matches Zod's structure).
+ */
+export type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: {
+        message: string;
+    };
+};
+/**
+ * Protocol object with definition and metadata.
+ */
+export interface Protocol<T extends ProtocolDef> {
+    /** The protocol definition */
+    _def: T;
+    /** Get endpoint definition by name */
+    getEndpoint<K extends keyof T>(name: K): T[K];
+    /** Check if endpoint is a method */
+    isMethod(name: keyof T): boolean;
+    /** Check if endpoint is a notification */
+    isNotification(name: keyof T): boolean;
+    /** Get all method names */
+    getMethodNames(): (keyof T)[];
+    /** Get all notification names */
+    getNotificationNames(): (keyof T)[];
+    /** Validate input for an endpoint */
+    validateInput<K extends keyof T>(name: K, input: unknown): SafeParseResult<InferInput<T[K]>>;
+    /** Validate output for a method endpoint */
+    validateOutput<K extends keyof T>(name: K, output: unknown): SafeParseResult<unknown>;
+}
+/**
+ * Define a protocol with typed endpoints.
+ *
+ * @example
+ * ```typescript
+ * const clientProtocol = defineProtocol({
+ *   subscribe: method({
+ *     input: z.object({ sessionId: z.string() }),
+ *     output: z.void(),
+ *     error: z.object({ code: z.literal('SESSION_NOT_FOUND') }),
+ *   }),
+ *
+ *   userMessage: method({
+ *     input: z.object({ sessionId: z.string(), content: z.string() }),
+ *     output: z.object({ messageId: z.string() }),
+ *     error: z.object({ code: z.literal('AGENT_BUSY') }),
+ *   }),
+ * });
+ *
+ * const serverProtocol = defineProtocol({
+ *   agentMessage: notification({
+ *     input: z.object({ sessionId: z.string(), content: z.string() }),
+ *   }),
+ * });
+ * ```
+ */
+export declare function defineProtocol<T extends ProtocolDef>(def: T): Protocol<T>;
+/**
+ * Extract the protocol definition type from a Protocol.
+ */
+export type ExtractProtocolDef<T> = T extends Protocol<infer P> ? P : never;
+/**
+ * Create a typed handlers object type for a protocol.
+ */
+export type HandlersFor<T extends Protocol<ProtocolDef>> = ProtocolHandlers<ExtractProtocolDef<T>>;
+/**
+ * Create a typed caller object type for a protocol.
+ */
+export type CallerFor<T extends Protocol<ProtocolDef>> = ProtocolCaller<ExtractProtocolDef<T>>;
+/**
+ * Create a typed notifier object type for a protocol.
+ */
+export type NotifierFor<T extends Protocol<ProtocolDef>> = ProtocolNotifier<ExtractProtocolDef<T>>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/core/protocol.d.ts.map

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

package/dist/core/protocol.js

@@ -0,0 +1,93 @@
+/**
+ * Protocol Definition API
+ *
+ * Provides a type-safe way to define RPC-like protocols for WebSocket communication.
+ * Inspired by tRPC but designed for bidirectional WebSocket protocols.
+ */
+/**
+ * Define a request-response method endpoint.
+ */
+export function method(options) {
+    return {
+        _type: 'method',
+        input: options.input,
+        output: options.output,
+        error: options.error,
+    };
+}
+/**
+ * Define a fire-and-forget notification endpoint.
+ */
+export function notification(options) {
+    return {
+        _type: 'notification',
+        input: options.input,
+    };
+}
+/**
+ * Define a protocol with typed endpoints.
+ *
+ * @example
+ * ```typescript
+ * const clientProtocol = defineProtocol({
+ *   subscribe: method({
+ *     input: z.object({ sessionId: z.string() }),
+ *     output: z.void(),
+ *     error: z.object({ code: z.literal('SESSION_NOT_FOUND') }),
+ *   }),
+ *
+ *   userMessage: method({
+ *     input: z.object({ sessionId: z.string(), content: z.string() }),
+ *     output: z.object({ messageId: z.string() }),
+ *     error: z.object({ code: z.literal('AGENT_BUSY') }),
+ *   }),
+ * });
+ *
+ * const serverProtocol = defineProtocol({
+ *   agentMessage: notification({
+ *     input: z.object({ sessionId: z.string(), content: z.string() }),
+ *   }),
+ * });
+ * ```
+ */
+export function defineProtocol(def) {
+    return {
+        _def: def,
+        getEndpoint(name) {
+            return def[name];
+        },
+        isMethod(name) {
+            const endpoint = def[name];
+            return endpoint?._type === 'method';
+        },
+        isNotification(name) {
+            const endpoint = def[name];
+            return endpoint?._type === 'notification';
+        },
+        getMethodNames() {
+            return Object.keys(def).filter((key) => def[key]._type === 'method');
+        },
+        getNotificationNames() {
+            return Object.keys(def).filter((key) => def[key]._type === 'notification');
+        },
+        validateInput(name, input) {
+            const endpoint = def[name];
+            const result = endpoint.input.safeParse(input);
+            if (result.success) {
+                return { success: true, data: result.data };
+            }
+            return { success: false, error: { message: result.error.message } };
+        },
+        validateOutput(name, output) {
+            const endpoint = def[name];
+            if (endpoint._type !== 'method') {
+                throw new Error(`Endpoint ${String(name)} is not a method`);
+            }
+            const result = endpoint.output.safeParse(output);
+            if (result.success) {
+                return { success: true, data: result.data };
+            }
+            return { success: false, error: { message: result.error.message } };
+        },
+    };
+}

package/dist/core/result.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Result type for explicit error handling without exceptions.
+ * Inspired by Rust/Go approach.
+ */
+export type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export declare const Ok: <T>(value: T) => Result<T, never>;
+export declare const Err: <E>(error: E) => Result<never, E>;
+export declare const isOk: <T, E>(result: Result<T, E>) => result is {
+    ok: true;
+    value: T;
+};
+export declare const isErr: <T, E>(result: Result<T, E>) => result is {
+    ok: false;
+    error: E;
+};
+export declare const mapResult: <T, U, E>(result: Result<T, E>, fn: (value: T) => U) => Result<U, E>;
+export declare const flatMapResult: <T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>) => Result<U, E>;
+export declare const unwrapOr: <T, E>(result: Result<T, E>, defaultValue: T) => T;
+export declare const unwrapOrThrow: <T, E>(result: Result<T, E>) => T;
+//# sourceMappingURL=result.d.ts.map

package/dist/core/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/core/result.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAA;AAG1B,eAAO,MAAM,EAAE,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAA0B,CAAA;AAC1E,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAA2B,CAAA;AAG5E,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAe,CAAA;AAC/F,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAgB,CAAA;AAGlG,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAChC,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACpB,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,KACjB,MAAM,CAAC,CAAC,EAAE,CAAC,CAA8C,CAAA;AAE5D,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACpC,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACpB,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAC5B,MAAM,CAAC,CAAC,EAAE,CAAC,CAA0C,CAAA;AAGxD,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,CAAC,KAAG,CAA4C,CAAA;AAEnH,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAG1D,CAAA"}

package/dist/core/result.js

@@ -0,0 +1,20 @@
+/**
+ * Result type for explicit error handling without exceptions.
+ * Inspired by Rust/Go approach.
+ */
+// Constructors
+export const Ok = (value) => ({ ok: true, value });
+export const Err = (error) => ({ ok: false, error });
+// Type guards
+export const isOk = (result) => result.ok;
+export const isErr = (result) => !result.ok;
+// Helper functions
+export const mapResult = (result, fn) => result.ok ? Ok(fn(result.value)) : result;
+export const flatMapResult = (result, fn) => result.ok ? fn(result.value) : result;
+// Unwrap functions
+export const unwrapOr = (result, defaultValue) => result.ok ? result.value : defaultValue;
+export const unwrapOrThrow = (result) => {
+    if (result.ok)
+        return result.value;
+    throw result.error;
+};

package/dist/core/router.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Message Router
+ *
+ * Handles notification dispatching - no request-response, no correlation.
+ * Simplified for notification-only protocols.
+ */
+import type { HandlerContext, InferInput, Protocol, ProtocolDef, ProtocolHandlers } from './protocol.js';
+/**
+ * Message send function type.
+ */
+export type MessageSender = (message: string) => boolean;
+/**
+ * Router error types for debugging protocol issues.
+ */
+export type RouterErrorType = 'parse' | 'unknown_type' | 'validation' | 'handler';
+/**
+ * Router error handler callback.
+ */
+export type RouterErrorHandler = (error: {
+    type: RouterErrorType;
+    message: string;
+    raw?: string;
+    details?: unknown;
+}) => void;
+/**
+ * Message router for handling incoming notifications and sending outbound notifications.
+ *
+ * Simplified notification-only router:
+ * - No request-response correlation
+ * - No pending requests tracking
+ * - Fire-and-forget notifications only
+ */
+/**
+ * Raw message listener — receives every parsed message before handler dispatch.
+ */
+export type RawMessageListener = (type: string, payload: unknown) => void;
+export declare class MessageRouter<TReceive extends ProtocolDef, TSend extends ProtocolDef> {
+    private readonly receiveProtocol;
+    private readonly sendProtocol;
+    private handlers;
+    private sender;
+    private errorHandler;
+    private rawMessageListener;
+    constructor(receiveProtocol: Protocol<TReceive> | null, sendProtocol: Protocol<TSend> | null);
+    /**
+     * Set the message sender function.
+     */
+    setSender(sender: MessageSender): void;
+    /**
+     * Set handlers for incoming notifications.
+     */
+    setHandlers(handlers: Partial<ProtocolHandlers<TReceive>>): void;
+    /**
+     * Set error handler for debugging protocol issues.
+     */
+    setErrorHandler(handler: RouterErrorHandler): void;
+    /**
+     * Set a raw message listener that receives every incoming message.
+     * When set, bypasses per-type handler dispatch — the listener receives (type, payload) directly.
+     */
+    setRawMessageListener(listener: RawMessageListener): void;
+    /**
+     * Handle an incoming raw message (notification).
+     */
+    handleMessage(raw: string, ctx: HandlerContext): Promise<void>;
+    /**
+     * Send a notification (fire-and-forget).
+     */
+    notify<K extends keyof TSend>(name: K, input: TSend[K] extends {
+        input: infer I;
+    } ? (I extends {
+        _type: string;
+    } ? never : InferInput<TSend[K]>) : never): boolean;
+}
+/**
+ * Create a message router for the given protocols.
+ */
+export declare function createRouter<TReceive extends ProtocolDef, TSend extends ProtocolDef>(receiveProtocol: Protocol<TReceive> | null, sendProtocol: Protocol<TSend> | null): MessageRouter<TReceive, TSend>;
+//# sourceMappingURL=router.d.ts.map

package/dist/core/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/core/router.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAOxG;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;AAExD;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,cAAc,GAAG,YAAY,GAAG,SAAS,CAAA;AAEjF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE;IACxC,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB,KAAK,IAAI,CAAA;AAMV;;;;;;;GAOG;AACH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;AAEzE,qBAAa,aAAa,CAAC,QAAQ,SAAS,WAAW,EAAE,KAAK,SAAS,WAAW;IACjF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwB;IAErD,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,kBAAkB,CAAkC;gBAG3D,eAAe,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,EAC1C,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,IAAI;IAMrC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAItC;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI;IAIhE;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAIlD;;;OAGG;IACH,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAIzD;;OAEG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDpE;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,KAAK,EAC3B,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,CAAC,CAAC,SAAS;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAC/G,OAAO;CAaV;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,SAAS,WAAW,EAAE,KAAK,SAAS,WAAW,EACnF,eAAe,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,EAC1C,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,IAAI,GAClC,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,CAEhC"}

package/dist/core/router.js

@@ -0,0 +1,119 @@
+/**
+ * Message Router
+ *
+ * Handles notification dispatching - no request-response, no correlation.
+ * Simplified for notification-only protocols.
+ */
+export class MessageRouter {
+    receiveProtocol;
+    sendProtocol;
+    handlers = {};
+    sender = null;
+    errorHandler = null;
+    rawMessageListener = null;
+    constructor(receiveProtocol, sendProtocol) {
+        this.receiveProtocol = receiveProtocol;
+        this.sendProtocol = sendProtocol;
+    }
+    /**
+     * Set the message sender function.
+     */
+    setSender(sender) {
+        this.sender = sender;
+    }
+    /**
+     * Set handlers for incoming notifications.
+     */
+    setHandlers(handlers) {
+        this.handlers = handlers;
+    }
+    /**
+     * Set error handler for debugging protocol issues.
+     */
+    setErrorHandler(handler) {
+        this.errorHandler = handler;
+    }
+    /**
+     * Set a raw message listener that receives every incoming message.
+     * When set, bypasses per-type handler dispatch — the listener receives (type, payload) directly.
+     */
+    setRawMessageListener(listener) {
+        this.rawMessageListener = listener;
+    }
+    /**
+     * Handle an incoming raw message (notification).
+     */
+    async handleMessage(raw, ctx) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            this.errorHandler?.({ type: 'parse', message: 'Invalid JSON', raw, details: e });
+            return;
+        }
+        const { type, payload } = parsed;
+        // Raw listener mode — forward everything without dispatch or validation
+        if (this.rawMessageListener) {
+            this.rawMessageListener(type, payload);
+            return;
+        }
+        if (this.receiveProtocol) {
+            // Validated path — protocol provided, validate input before dispatching
+            const endpoint = this.receiveProtocol._def[type];
+            if (!endpoint) {
+                this.errorHandler?.({ type: 'unknown_type', message: `Unknown message type: ${type}`, raw });
+                return;
+            }
+            const inputResult = this.receiveProtocol.validateInput(type, payload);
+            if (!inputResult.success) {
+                this.errorHandler?.({ type: 'validation', message: `Validation failed for ${type}`, raw, details: inputResult.error });
+                return;
+            }
+            const handler = this.handlers[type];
+            if (!handler)
+                return;
+            try {
+                await handler(inputResult.data, ctx);
+            }
+            catch (e) {
+                this.errorHandler?.({ type: 'handler', message: `Handler error for ${type}`, raw, details: e });
+            }
+        }
+        else {
+            // Unvalidated path — no protocol, dispatch directly (trusted source)
+            const handler = this.handlers[type];
+            if (!handler)
+                return;
+            try {
+                await handler(payload, ctx);
+            }
+            catch (e) {
+                this.errorHandler?.({ type: 'handler', message: `Handler error for ${type}`, raw, details: e });
+            }
+        }
+    }
+    /**
+     * Send a notification (fire-and-forget).
+     */
+    notify(name, input) {
+        if (!this.sender) {
+            return false;
+        }
+        const message = {
+            type: String(name),
+            payload: input,
+            ts: Date.now(),
+        };
+        return this.sender(JSON.stringify(message));
+    }
+}
+// ============================================================================
+// Router Builder
+// ============================================================================
+/**
+ * Create a message router for the given protocols.
+ */
+export function createRouter(receiveProtocol, sendProtocol) {
+    return new MessageRouter(receiveProtocol, sendProtocol);
+}

package/dist/core/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Core Transport Types
+ *
+ * Platform-agnostic types for WebSocket transport infrastructure.
+ */
+/**
+ * Connection state machine states.
+ */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * Wire message envelope for all protocol messages.
+ * Simplified: notification-only, no correlation ID.
+ */
+export interface WireMessage<T = unknown> {
+    /** Notification type name */
+    type: string;
+    /** Message payload */
+    payload: T;
+    /** Timestamp */
+    ts: number;
+}
+/**
+ * Transport event types.
+ */
+export type TransportEvent = 'connected' | 'disconnected' | 'error' | 'reconnecting' | 'reconnected' | 'state_change' | 'router_error';
+/**
+ * Transport event listener.
+ */
+export type TransportEventListener = (event: TransportEvent, data?: unknown) => void;
+/**
+ * Reconnection strategy options.
+ */
+export interface ReconnectOptions {
+    /** Base delay in ms (default: 1000) */
+    baseDelayMs: number;
+    /** Maximum delay in ms (default: 30000) */
+    maxDelayMs: number;
+    /** Maximum number of attempts before giving up (default: Infinity) */
+    maxAttempts: number;
+    /** Jitter factor (0-1, default: 0.3) */
+    jitterFactor: number;
+}
+export declare const DEFAULT_RECONNECT_OPTIONS: ReconnectOptions;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,MAAM,eAAe,GACxB,cAAc,GACd,YAAY,GACZ,WAAW,GACX,cAAc,CAAA;AAMjB;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACvC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,sBAAsB;IACtB,OAAO,EAAE,CAAC,CAAA;IACV,gBAAgB;IAChB,EAAE,EAAE,MAAM,CAAA;CACV;AAMD;;GAEG;AACH,MAAM,MAAM,cAAc,GACvB,WAAW,GACX,cAAc,GACd,OAAO,GACP,cAAc,GACd,aAAa,GACb,cAAc,GACd,cAAc,CAAA;AAEjB;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;AAMpF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAA;IACnB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;CACpB;AAMD,eAAO,MAAM,yBAAyB,EAAE,gBAKvC,CAAA"}

package/dist/core/types.js

@@ -0,0 +1,14 @@
+/**
+ * Core Transport Types
+ *
+ * Platform-agnostic types for WebSocket transport infrastructure.
+ */
+// ============================================================================
+// Default Values
+// ============================================================================
+export const DEFAULT_RECONNECT_OPTIONS = {
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    maxAttempts: Infinity,
+    jitterFactor: 0.3,
+};

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @roj-ai/transport
+ *
+ * Platform-agnostic WebSocket transport infrastructure with RPC-like protocol API.
+ */
+export { defineProtocol, method, notification } from './core/protocol.js';
+export type { CallerFor, EndpointDef, EndpointHandler, ExtractProtocolDef, HandlerContext, HandlersFor, InferError, InferInput, InferOutput, IsMethod, IsNotification, MethodCaller, MethodDef, MethodHandler, MethodOptions, NotificationDef, NotificationHandler, NotificationNotifier, NotificationOptions, NotifierFor, Protocol, ProtocolCaller, ProtocolDef, ProtocolHandlers, ProtocolNotifier, } from './core/protocol.js';
+export { Err, flatMapResult, isErr, isOk, mapResult, Ok, unwrapOr, unwrapOrThrow } from './core/result.js';
+export type { Result } from './core/result.js';
+export type { ConnectionState, ReconnectOptions, TransportEvent, TransportEventListener, WireMessage } from './core/types.js';
+export { DEFAULT_RECONNECT_OPTIONS } from './core/types.js';
+export { createRouter, MessageRouter } from './core/router.js';
+export type { MessageSender, RawMessageListener, RouterErrorHandler, RouterErrorType } from './core/router.js';
+export { Connection } from './core/connection.js';
+export type { ConnectionConfig } from './core/connection.js';
+export type { ICloseEvent, IServerWebSocket, IWebSocket, IWebSocketFactory } from './platform/types.js';
+export { WebSocketReadyState } from './platform/types.js';
+export { ClientConnection, createClientConnection } from './client/client-connection.js';
+export type { ClientConnectionConfig } from './client/client-connection.js';
+export { createServerConnection, ServerConnection } from './server/server-connection.js';
+export type { ServerConnectionConfig, ServerHandlerContext } from './server/server-connection.js';
+export { ConnectionManager } from './server/connection-manager.js';
+export type { ConnectionStats } from './server/connection-manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACzE,YAAY,EACX,SAAS,EACT,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,SAAS,EACT,aAAa,EACb,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,gBAAgB,GAChB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAC1G,YAAY,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAG9C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAE7H,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA;AAG3D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAC9D,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAE9G,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAM5D,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAEvG,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAMzD,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AACxF,YAAY,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AAM3E,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AACxF,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAEjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA"}