@kyneta/websocket-transport 1.3.0 → 1.4.0

package/dist/client.d.ts

@@ -1,207 +0,0 @@
-import { Program, TransitionListener } from '@kyneta/machine';
-import { ReconnectOptions, PeerId, Transport, GeneratedChannel, TransportFactory } from '@kyneta/transport';
-import { W as WebsocketClientState, b as WebsocketClientStateTransition, D as DisconnectReason } from './types-DdNb8cAz.js';
-export { S as Socket, a as SocketReadyState, T as TransitionListener, w as wrapStandardWebsocket } from './types-DdNb8cAz.js';
-
-type WsClientMsg = {
-    type: "start";
-} | {
-    type: "socket-opened";
-} | {
-    type: "server-ready";
-} | {
-    type: "socket-closed";
-    code: number;
-    reason: string;
-} | {
-    type: "socket-error";
-    error: Error;
-} | {
-    type: "reconnect-timer-fired";
-} | {
-    type: "stop";
-};
-type WsClientEffect = {
-    type: "create-websocket";
-    attempt: number;
-} | {
-    type: "close-websocket";
-} | {
-    type: "add-channel-and-establish";
-} | {
-    type: "remove-channel";
-} | {
-    type: "start-reconnect-timer";
-    delayMs: number;
-} | {
-    type: "cancel-reconnect-timer";
-} | {
-    type: "start-keepalive";
-} | {
-    type: "stop-keepalive";
-};
-interface WsClientProgramOptions {
-    reconnect?: Partial<ReconnectOptions>;
-    /** Inject jitter source for deterministic testing. Default: () => Math.random() * 1000 */
-    jitterFn?: () => number;
-}
-/**
- * Create the websocket client connection lifecycle program — a pure Mealy machine.
- *
- * The returned `Program<WsClientMsg, WebsocketClientState, WsClientEffect>`
- * encodes every state transition and effect as inspectable data. The imperative
- * shell interprets `WsClientEffect` as actual I/O.
- */
-declare function createWsClientProgram(options?: WsClientProgramOptions): Program<WsClientMsg, WebsocketClientState, WsClientEffect>;
-
-/**
- * Default fragment threshold in bytes.
- * AWS API Gateway has a 128KB limit, so 100KB provides a safe margin.
- */
-declare const DEFAULT_FRAGMENT_THRESHOLD: number;
-/**
- * Options for the Websocket client transport (browser connections).
- */
-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;
-    /** Reconnection options. */
-    reconnect?: {
-        enabled?: boolean;
-        maxAttempts?: number;
-        baseDelay?: number;
-        maxDelay?: number;
-    };
-    /** Keepalive interval in ms (default: 30000). */
-    keepaliveInterval?: number;
-    /**
-     * Fragment threshold in bytes. Messages larger than this are fragmented.
-     * Set to 0 to disable fragmentation (not recommended for cloud deployments).
-     * Default: 100KB
-     */
-    fragmentThreshold?: number;
-    /** Lifecycle event callbacks. */
-    lifecycle?: WebsocketClientLifecycleEvents;
-}
-/**
- * Lifecycle event callbacks for the Websocket client.
- */
-interface WebsocketClientLifecycleEvents {
-    /** Called on every state transition (delivered async via microtask). */
-    onStateChange?: (transition: WebsocketClientStateTransition) => void;
-    /** Called when the connection is lost. */
-    onDisconnect?: (reason: DisconnectReason) => void;
-    /** Called when a reconnection attempt is scheduled. */
-    onReconnecting?: (attempt: number, nextAttemptMs: number) => void;
-    /** Called when reconnection succeeds after a previous connection. */
-    onReconnected?: () => void;
-    /** Called when the server sends the "ready" signal. */
-    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.
- */
-interface ServiceWebsocketClientOptions extends WebsocketClientOptions {
-    /**
-     * Headers to send during Websocket upgrade.
-     * Used for authentication in service-to-service communication.
-     */
-    headers?: Record<string, string>;
-}
-/**
- * Websocket client network transport for @kyneta/exchange.
- *
- * Connects to a Websocket server, sends and receives ChannelMsg via
- * the kyneta wire format (CBOR codec + framing + fragmentation).
- *
- * Internally, the connection lifecycle is a `Program<Msg, Model, Fx>` —
- * a pure Mealy machine whose transitions are deterministically testable.
- * 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)
- */
-declare class WebsocketClientTransport extends Transport<void> {
-    #private;
-    constructor(options: ServiceWebsocketClientOptions);
-    /**
-     * Get the current connection state.
-     */
-    getState(): WebsocketClientState;
-    /**
-     * Subscribe to state transitions.
-     */
-    subscribeToTransitions(listener: TransitionListener<WebsocketClientState>): () => void;
-    /**
-     * Wait for a specific state.
-     */
-    waitForState(predicate: (state: WebsocketClientState) => boolean, options?: {
-        timeoutMs?: number;
-    }): Promise<WebsocketClientState>;
-    /**
-     * Wait for a specific status.
-     */
-    waitForStatus(status: WebsocketClientState["status"], options?: {
-        timeoutMs?: number;
-    }): Promise<WebsocketClientState>;
-    /**
-     * Whether the client is ready (server ready signal received).
-     */
-    get isReady(): boolean;
-    protected generate(): GeneratedChannel;
-    onStart(): Promise<void>;
-    onStop(): Promise<void>;
-}
-/**
- * Create a Websocket client transport factory for browser-to-server
- * connections.
- *
- * Returns an `TransportFactory` — a closure that creates a fresh transport
- * instance when called. Pass directly to `Exchange({ transports: [...] })`.
- *
- * @example
- * ```typescript
- * import { createWebsocketClient } from "@kyneta/websocket-transport/client"
- *
- * const exchange = new Exchange({
- *   transports: [createWebsocketClient({
- *     url: "ws://localhost:3000/ws",
- *     reconnect: { enabled: true },
- *   })],
- * })
- * ```
- */
-declare function createWebsocketClient(options: WebsocketClientOptions): TransportFactory;
-/**
- * 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 },
- *   })],
- * })
- * ```
- */
-declare function createServiceWebsocketClient(options: ServiceWebsocketClientOptions): TransportFactory;
-
-export { DEFAULT_FRAGMENT_THRESHOLD, DisconnectReason, type ServiceWebsocketClientOptions, type WebsocketClientLifecycleEvents, type WebsocketClientOptions, WebsocketClientState, WebsocketClientStateTransition, WebsocketClientTransport, type WsClientEffect, type WsClientMsg, type WsClientProgramOptions, createServiceWebsocketClient, createWebsocketClient, createWsClientProgram };