@syncular/transport-ws 0.0.1-60

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @syncular/transport-ws - WebSocket transport for sync realtime wake-ups
+ *
+ * Extends the HTTP transport with WebSocket-based realtime notifications.
+ * WebSockets are only used as a "wake up" mechanism; clients must still pull.
+ *
+ * Auth notes:
+ * - Browsers' `WebSocket` cannot attach custom headers.
+ * - Use cookie auth (same-origin) or a query-param token for the realtime URL.
+ */
+import type { SyncPushRequest, SyncPushResponse, SyncTransport } from '@syncular/core';
+import { type ClientOptions } from '@syncular/transport-http';
+/**
+ * WebSocket connection state
+ */
+export type WebSocketConnectionState = 'disconnected' | 'connecting' | 'connected';
+/**
+ * Presence event data
+ */
+export interface PresenceEventData {
+    action: 'join' | 'leave' | 'update' | 'snapshot';
+    scopeKey: string;
+    clientId?: string;
+    actorId?: string;
+    metadata?: Record<string, unknown>;
+    entries?: Array<{
+        clientId: string;
+        actorId: string;
+        joinedAt: number;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Push response data received from the server over WS
+ */
+export interface WsPushResponseData {
+    requestId: string;
+    ok: boolean;
+    status: string;
+    commitSeq?: number;
+    results: Array<{
+        opIndex: number;
+        status: string;
+        [k: string]: unknown;
+    }>;
+    timestamp: number;
+}
+/**
+ * WebSocket event from the server
+ */
+export interface WebSocketEvent {
+    event: 'sync' | 'heartbeat' | 'error' | 'presence' | 'push-response';
+    data: {
+        cursor?: number;
+        /** Inline change data for small payloads (WS data delivery) */
+        changes?: unknown[];
+        error?: string;
+        presence?: PresenceEventData;
+        /** Push response fields (for push-response events) */
+        requestId?: string;
+        ok?: boolean;
+        status?: string;
+        commitSeq?: number;
+        results?: Array<{
+            opIndex: number;
+            status: string;
+            [k: string]: unknown;
+        }>;
+        timestamp: number;
+    };
+}
+/**
+ * Callback for realtime events
+ */
+export type WebSocketEventCallback = (event: WebSocketEvent) => void;
+/**
+ * Callback for connection state changes
+ */
+export type WebSocketStateCallback = (state: WebSocketConnectionState) => void;
+export interface WebSocketTransportOptions extends ClientOptions {
+    /**
+     * WebSocket endpoint URL. If not provided, uses `${baseUrl}/realtime` with
+     * `http(s)` -> `ws(s)` conversion when possible.
+     */
+    wsUrl?: string;
+    /**
+     * Additional query params for the realtime URL (e.g. `{ token }`).
+     *
+     * ⚠️ SECURITY WARNING: Query parameters may be logged by proxies, CDNs, and
+     * browser history. Do NOT pass sensitive tokens here. Use cookie-based auth
+     * or the `authToken` option with a server that supports first-message auth.
+     */
+    getRealtimeParams?: (args: {
+        clientId: string;
+    }) => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * Auth token sent in the first WebSocket message after connection.
+     * More secure than query parameters as it won't appear in URLs.
+     * Requires server support for first-message auth.
+     */
+    authToken?: string | (() => string | Promise<string>);
+    /**
+     * Initial reconnection delay in ms.
+     * Default: 1000 (1 second)
+     */
+    initialReconnectDelay?: number;
+    /**
+     * Maximum reconnection delay in ms.
+     * Default: 30000 (30 seconds)
+     */
+    maxReconnectDelay?: number;
+    /**
+     * Backoff factor for reconnection delay.
+     * Default: 2
+     */
+    reconnectBackoffFactor?: number;
+    /**
+     * Jitter factor for reconnection delay (0-1).
+     * Adds randomness to prevent thundering herd on server restart.
+     * Default: 0.3 (30% randomization)
+     */
+    reconnectJitter?: number;
+    /**
+     * Heartbeat timeout in ms. If no message is received within this time,
+     * the connection is considered dead.
+     * Default: 60000 (60 seconds)
+     */
+    heartbeatTimeout?: number;
+    /**
+     * Optional WebSocket implementation override (useful for non-browser runtimes).
+     */
+    WebSocketImpl?: typeof WebSocket;
+    /**
+     * Transport path telemetry sent to the server for push/pull and realtime.
+     * Defaults to 'relay' for this transport.
+     */
+    transportPath?: 'direct' | 'relay';
+}
+/**
+ * Callback for presence events from the server
+ */
+export type PresenceEventCallback = (event: PresenceEventData) => void;
+/**
+ * Extended sync transport with WebSocket subscription support.
+ */
+export interface WebSocketTransport extends SyncTransport {
+    connect(args: {
+        clientId: string;
+    }, onEvent: WebSocketEventCallback, onStateChange?: WebSocketStateCallback): () => void;
+    getConnectionState(): WebSocketConnectionState;
+    reconnect(): void;
+    sendPresenceJoin(scopeKey: string, metadata?: Record<string, unknown>): void;
+    sendPresenceLeave(scopeKey: string): void;
+    sendPresenceUpdate(scopeKey: string, metadata: Record<string, unknown>): void;
+    onPresenceEvent(callback: PresenceEventCallback): () => void;
+    /**
+     * Push a commit via WebSocket (bypasses HTTP).
+     * Returns `null` if WS is not connected or times out (caller should fall back to HTTP).
+     */
+    pushViaWs(request: SyncPushRequest): Promise<SyncPushResponse | null>;
+}
+export declare function createWebSocketTransport(options: WebSocketTransportOptions): WebSocketTransport;
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,363 @@
+/**
+ * @syncular/transport-ws - WebSocket transport for sync realtime wake-ups
+ *
+ * Extends the HTTP transport with WebSocket-based realtime notifications.
+ * WebSockets are only used as a "wake up" mechanism; clients must still pull.
+ *
+ * Auth notes:
+ * - Browsers' `WebSocket` cannot attach custom headers.
+ * - Use cookie auth (same-origin) or a query-param token for the realtime URL.
+ */
+import { createHttpTransport, } from '@syncular/transport-http';
+function defaultWsUrl(baseUrl) {
+    try {
+        const isAbsolute = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(baseUrl);
+        const resolved = isAbsolute || typeof location === 'undefined'
+            ? new URL(baseUrl)
+            : new URL(baseUrl, location.origin);
+        resolved.protocol = resolved.protocol === 'https:' ? 'wss:' : 'ws:';
+        resolved.pathname = `${resolved.pathname.replace(/\/$/, '')}/realtime`;
+        return resolved.toString();
+    }
+    catch {
+        return null;
+    }
+}
+export function createWebSocketTransport(options) {
+    const telemetryTransportPath = options.transportPath ?? 'relay';
+    const httpTransport = createHttpTransport({
+        baseUrl: options.baseUrl,
+        getHeaders: options.getHeaders,
+        fetch: options.fetch,
+        transportPath: telemetryTransportPath,
+    });
+    const { baseUrl, wsUrl = options.wsUrl ?? defaultWsUrl(baseUrl), getRealtimeParams, authToken, initialReconnectDelay = 1000, maxReconnectDelay = 30_000, reconnectBackoffFactor = 2, heartbeatTimeout = 60_000, WebSocketImpl = typeof WebSocket !== 'undefined' ? WebSocket : undefined, } = options;
+    // Warn about security risk of using getRealtimeParams with sensitive data
+    if (getRealtimeParams && !authToken) {
+        console.warn('[transport-ws] getRealtimeParams sends data in URL query parameters, ' +
+            'which may be logged by proxies and CDNs. Consider using authToken instead.');
+    }
+    if (!wsUrl) {
+        throw new Error('@syncular/transport-ws: wsUrl is required when baseUrl cannot be converted');
+    }
+    if (!WebSocketImpl) {
+        throw new Error('@syncular/transport-ws: WebSocket is not available in this runtime');
+    }
+    let ws = null;
+    let connectionState = 'disconnected';
+    let reconnectAttempts = 0;
+    let reconnectTimer = null;
+    let heartbeatTimer = null;
+    let currentEventCallback = null;
+    let currentStateCallback = null;
+    let isManuallyDisconnected = false;
+    let currentClientId = null;
+    let connectNonce = 0;
+    // Presence state
+    const activePresenceScopes = new Map();
+    const presenceCallbacks = new Set();
+    // Pending WS push requests (requestId -> resolver)
+    const pendingPushRequests = new Map();
+    const WS_PUSH_TIMEOUT_MS = 10_000;
+    function setConnectionState(state) {
+        if (connectionState === state)
+            return;
+        connectionState = state;
+        currentStateCallback?.(state);
+    }
+    function calculateReconnectDelay() {
+        const baseDelay = Math.min(initialReconnectDelay * reconnectBackoffFactor ** reconnectAttempts, maxReconnectDelay);
+        // Add jitter to prevent thundering herd (multiple clients reconnecting simultaneously)
+        const jitterFactor = options.reconnectJitter ?? 0.3;
+        const jitter = baseDelay * jitterFactor * (Math.random() * 2 - 1); // +/- jitterFactor
+        return Math.max(0, Math.round(baseDelay + jitter));
+    }
+    function clearHeartbeatTimer() {
+        if (!heartbeatTimer)
+            return;
+        clearTimeout(heartbeatTimer);
+        heartbeatTimer = null;
+    }
+    function resetHeartbeatTimer() {
+        clearHeartbeatTimer();
+        if (heartbeatTimeout <= 0)
+            return;
+        heartbeatTimer = setTimeout(() => {
+            doDisconnect();
+            scheduleReconnect();
+        }, heartbeatTimeout);
+    }
+    function clearReconnectTimer() {
+        if (!reconnectTimer)
+            return;
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+    }
+    function scheduleReconnect() {
+        if (isManuallyDisconnected)
+            return;
+        clearReconnectTimer();
+        const delay = calculateReconnectDelay();
+        reconnectAttempts += 1;
+        reconnectTimer = setTimeout(() => {
+            void doConnect();
+        }, delay);
+    }
+    function doDisconnect() {
+        clearHeartbeatTimer();
+        clearReconnectTimer();
+        // Resolve all pending WS push requests as null (triggers HTTP fallback)
+        for (const [, pending] of pendingPushRequests) {
+            clearTimeout(pending.timer);
+            pending.resolve(null);
+        }
+        pendingPushRequests.clear();
+        if (ws) {
+            try {
+                ws.onopen = null;
+                ws.onmessage = null;
+                ws.onerror = null;
+                ws.onclose = null;
+                ws.close();
+            }
+            catch {
+                // ignore
+            }
+            ws = null;
+        }
+        setConnectionState('disconnected');
+    }
+    function dispatchEvent(raw) {
+        resetHeartbeatTimer();
+        if (!raw || typeof raw !== 'object')
+            return;
+        if (!('event' in raw) || !('data' in raw))
+            return;
+        const event = raw.event;
+        const data = raw.data;
+        if (!data || typeof data !== 'object')
+            return;
+        // Route push-response events to pending request resolvers
+        if (event === 'push-response') {
+            const d = data;
+            const requestId = typeof d.requestId === 'string' ? d.requestId : '';
+            const pending = pendingPushRequests.get(requestId);
+            if (pending) {
+                pendingPushRequests.delete(requestId);
+                clearTimeout(pending.timer);
+                pending.resolve({
+                    ok: true,
+                    status: d.status ?? 'rejected',
+                    commitSeq: typeof d.commitSeq === 'number' ? d.commitSeq : undefined,
+                    results: Array.isArray(d.results)
+                        ? d.results
+                        : [],
+                });
+            }
+            return;
+        }
+        // Route presence events to dedicated callbacks
+        if (event === 'presence') {
+            const presenceData = data.presence;
+            if (presenceData && typeof presenceData === 'object') {
+                for (const cb of presenceCallbacks) {
+                    cb(presenceData);
+                }
+            }
+            // Also forward to main event callback
+            if (currentEventCallback) {
+                currentEventCallback({ event, data });
+            }
+            return;
+        }
+        if (event !== 'sync' && event !== 'heartbeat' && event !== 'error')
+            return;
+        currentEventCallback?.({ event, data });
+    }
+    function sendPresenceMessage(msg) {
+        if (!ws || ws.readyState !== WebSocketImpl.OPEN)
+            return;
+        ws.send(JSON.stringify({ type: 'presence', ...msg }));
+    }
+    async function buildUrl(clientId) {
+        if (!wsUrl)
+            throw new Error('wsUrl is required');
+        // Handle relative URLs by using location.origin as base
+        const isAbsolute = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(wsUrl);
+        const url = isAbsolute || typeof location === 'undefined'
+            ? new URL(wsUrl)
+            : new URL(wsUrl, location.origin);
+        // Convert http(s) to ws(s) if needed
+        if (url.protocol === 'https:')
+            url.protocol = 'wss:';
+        if (url.protocol === 'http:')
+            url.protocol = 'ws:';
+        url.searchParams.set('clientId', clientId);
+        if (getRealtimeParams) {
+            try {
+                const params = await getRealtimeParams({ clientId });
+                for (const [k, v] of Object.entries(params ?? {})) {
+                    if (typeof v !== 'string')
+                        continue;
+                    if (!v)
+                        continue;
+                    url.searchParams.set(k, v);
+                }
+            }
+            catch {
+                // ignore; realtime is best-effort
+            }
+        }
+        url.searchParams.set('transportPath', telemetryTransportPath);
+        return url.toString();
+    }
+    async function doConnect() {
+        if (!currentClientId)
+            return;
+        if (isManuallyDisconnected)
+            return;
+        const nonce = ++connectNonce;
+        setConnectionState('connecting');
+        const url = await buildUrl(currentClientId);
+        if (nonce !== connectNonce)
+            return;
+        if (!WebSocketImpl)
+            throw new Error('WebSocketImpl is required');
+        try {
+            ws = new WebSocketImpl(url);
+        }
+        catch {
+            doDisconnect();
+            scheduleReconnect();
+            return;
+        }
+        ws.onopen = async () => {
+            if (nonce !== connectNonce)
+                return;
+            // Send auth token if provided (more secure than query params)
+            if (authToken && ws) {
+                try {
+                    const token = typeof authToken === 'function' ? await authToken() : authToken;
+                    if (token && nonce === connectNonce) {
+                        ws.send(JSON.stringify({ type: 'auth', token }));
+                    }
+                }
+                catch {
+                    // Auth token failed, but connection is still open
+                    // Server will handle unauthenticated connection appropriately
+                }
+            }
+            if (nonce !== connectNonce)
+                return;
+            setConnectionState('connected');
+            reconnectAttempts = 0;
+            resetHeartbeatTimer();
+            // Re-join all active presence scopes on reconnect
+            for (const [scopeKey, metadata] of activePresenceScopes) {
+                sendPresenceMessage({ action: 'join', scopeKey, metadata });
+            }
+        };
+        ws.onmessage = (evt) => {
+            if (nonce !== connectNonce)
+                return;
+            resetHeartbeatTimer();
+            if (typeof evt.data === 'string') {
+                try {
+                    dispatchEvent(JSON.parse(evt.data));
+                }
+                catch {
+                    // ignore malformed messages
+                }
+            }
+        };
+        ws.onerror = () => {
+            if (nonce !== connectNonce)
+                return;
+            doDisconnect();
+            scheduleReconnect();
+        };
+        ws.onclose = () => {
+            if (nonce !== connectNonce)
+                return;
+            doDisconnect();
+            scheduleReconnect();
+        };
+    }
+    return {
+        ...httpTransport,
+        connect(args, onEvent, onStateChange) {
+            currentClientId = args.clientId;
+            currentEventCallback = onEvent;
+            currentStateCallback = onStateChange ?? null;
+            isManuallyDisconnected = false;
+            reconnectAttempts = 0;
+            void doConnect();
+            return () => {
+                isManuallyDisconnected = true;
+                currentEventCallback = null;
+                currentStateCallback = null;
+                currentClientId = null;
+                connectNonce += 1;
+                doDisconnect();
+            };
+        },
+        getConnectionState() {
+            return connectionState;
+        },
+        reconnect() {
+            if (!currentClientId)
+                return;
+            if (isManuallyDisconnected)
+                return;
+            connectNonce += 1;
+            doDisconnect();
+            void doConnect();
+        },
+        sendPresenceJoin(scopeKey, metadata) {
+            activePresenceScopes.set(scopeKey, metadata);
+            sendPresenceMessage({ action: 'join', scopeKey, metadata });
+        },
+        sendPresenceLeave(scopeKey) {
+            activePresenceScopes.delete(scopeKey);
+            sendPresenceMessage({ action: 'leave', scopeKey });
+        },
+        sendPresenceUpdate(scopeKey, metadata) {
+            activePresenceScopes.set(scopeKey, metadata);
+            sendPresenceMessage({ action: 'update', scopeKey, metadata });
+        },
+        onPresenceEvent(callback) {
+            presenceCallbacks.add(callback);
+            return () => {
+                presenceCallbacks.delete(callback);
+            };
+        },
+        pushViaWs(request) {
+            if (!ws || ws.readyState !== WebSocketImpl.OPEN) {
+                return Promise.resolve(null);
+            }
+            const requestId = crypto.randomUUID();
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    pendingPushRequests.delete(requestId);
+                    resolve(null);
+                }, WS_PUSH_TIMEOUT_MS);
+                pendingPushRequests.set(requestId, { resolve, timer });
+                try {
+                    ws.send(JSON.stringify({
+                        type: 'push',
+                        requestId,
+                        clientCommitId: request.clientCommitId,
+                        operations: request.operations,
+                        schemaVersion: request.schemaVersion,
+                    }));
+                }
+                catch {
+                    pendingPushRequests.delete(requestId);
+                    clearTimeout(timer);
+                    resolve(null);
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@syncular/transport-ws",
+  "version": "0.0.1-60",
+  "description": "WebSocket transport for Syncular real-time sync",
+  "license": "MIT",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/transport-ws"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript",
+    "websocket",
+    "realtime"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "tsgo": "tsgo --noEmit",
+    "build": "rm -rf dist && tsgo",
+    "release": "bun pm pack --destination . && npm publish ./*.tgz --tag latest && rm -f ./*.tgz"
+  },
+  "dependencies": {
+    "@syncular/core": "0.0.1",
+    "@syncular/transport-http": "0.0.1"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,582 @@
+/**
+ * @syncular/transport-ws - WebSocket transport for sync realtime wake-ups
+ *
+ * Extends the HTTP transport with WebSocket-based realtime notifications.
+ * WebSockets are only used as a "wake up" mechanism; clients must still pull.
+ *
+ * Auth notes:
+ * - Browsers' `WebSocket` cannot attach custom headers.
+ * - Use cookie auth (same-origin) or a query-param token for the realtime URL.
+ */
+
+import type {
+  SyncPushRequest,
+  SyncPushResponse,
+  SyncTransport,
+} from '@syncular/core';
+import {
+  type ClientOptions,
+  createHttpTransport,
+} from '@syncular/transport-http';
+
+/**
+ * WebSocket connection state
+ */
+export type WebSocketConnectionState =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected';
+
+/**
+ * Presence event data
+ */
+export interface PresenceEventData {
+  action: 'join' | 'leave' | 'update' | 'snapshot';
+  scopeKey: string;
+  clientId?: string;
+  actorId?: string;
+  metadata?: Record<string, unknown>;
+  entries?: Array<{
+    clientId: string;
+    actorId: string;
+    joinedAt: number;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
+/**
+ * Push response data received from the server over WS
+ */
+export interface WsPushResponseData {
+  requestId: string;
+  ok: boolean;
+  status: string;
+  commitSeq?: number;
+  results: Array<{ opIndex: number; status: string; [k: string]: unknown }>;
+  timestamp: number;
+}
+
+/**
+ * WebSocket event from the server
+ */
+export interface WebSocketEvent {
+  event: 'sync' | 'heartbeat' | 'error' | 'presence' | 'push-response';
+  data: {
+    cursor?: number;
+    /** Inline change data for small payloads (WS data delivery) */
+    changes?: unknown[];
+    error?: string;
+    presence?: PresenceEventData;
+    /** Push response fields (for push-response events) */
+    requestId?: string;
+    ok?: boolean;
+    status?: string;
+    commitSeq?: number;
+    results?: Array<{ opIndex: number; status: string; [k: string]: unknown }>;
+    timestamp: number;
+  };
+}
+
+/**
+ * Callback for realtime events
+ */
+export type WebSocketEventCallback = (event: WebSocketEvent) => void;
+
+/**
+ * Callback for connection state changes
+ */
+export type WebSocketStateCallback = (state: WebSocketConnectionState) => void;
+
+export interface WebSocketTransportOptions extends ClientOptions {
+  /**
+   * WebSocket endpoint URL. If not provided, uses `${baseUrl}/realtime` with
+   * `http(s)` -> `ws(s)` conversion when possible.
+   */
+  wsUrl?: string;
+  /**
+   * Additional query params for the realtime URL (e.g. `{ token }`).
+   *
+   * ⚠️ SECURITY WARNING: Query parameters may be logged by proxies, CDNs, and
+   * browser history. Do NOT pass sensitive tokens here. Use cookie-based auth
+   * or the `authToken` option with a server that supports first-message auth.
+   */
+  getRealtimeParams?: (args: {
+    clientId: string;
+  }) => Record<string, string> | Promise<Record<string, string>>;
+  /**
+   * Auth token sent in the first WebSocket message after connection.
+   * More secure than query parameters as it won't appear in URLs.
+   * Requires server support for first-message auth.
+   */
+  authToken?: string | (() => string | Promise<string>);
+  /**
+   * Initial reconnection delay in ms.
+   * Default: 1000 (1 second)
+   */
+  initialReconnectDelay?: number;
+  /**
+   * Maximum reconnection delay in ms.
+   * Default: 30000 (30 seconds)
+   */
+  maxReconnectDelay?: number;
+  /**
+   * Backoff factor for reconnection delay.
+   * Default: 2
+   */
+  reconnectBackoffFactor?: number;
+  /**
+   * Jitter factor for reconnection delay (0-1).
+   * Adds randomness to prevent thundering herd on server restart.
+   * Default: 0.3 (30% randomization)
+   */
+  reconnectJitter?: number;
+  /**
+   * Heartbeat timeout in ms. If no message is received within this time,
+   * the connection is considered dead.
+   * Default: 60000 (60 seconds)
+   */
+  heartbeatTimeout?: number;
+  /**
+   * Optional WebSocket implementation override (useful for non-browser runtimes).
+   */
+  WebSocketImpl?: typeof WebSocket;
+  /**
+   * Transport path telemetry sent to the server for push/pull and realtime.
+   * Defaults to 'relay' for this transport.
+   */
+  transportPath?: 'direct' | 'relay';
+}
+
+/**
+ * Callback for presence events from the server
+ */
+export type PresenceEventCallback = (event: PresenceEventData) => void;
+
+/**
+ * Extended sync transport with WebSocket subscription support.
+ */
+export interface WebSocketTransport extends SyncTransport {
+  connect(
+    args: { clientId: string },
+    onEvent: WebSocketEventCallback,
+    onStateChange?: WebSocketStateCallback
+  ): () => void;
+  getConnectionState(): WebSocketConnectionState;
+  reconnect(): void;
+  sendPresenceJoin(scopeKey: string, metadata?: Record<string, unknown>): void;
+  sendPresenceLeave(scopeKey: string): void;
+  sendPresenceUpdate(scopeKey: string, metadata: Record<string, unknown>): void;
+  onPresenceEvent(callback: PresenceEventCallback): () => void;
+  /**
+   * Push a commit via WebSocket (bypasses HTTP).
+   * Returns `null` if WS is not connected or times out (caller should fall back to HTTP).
+   */
+  pushViaWs(request: SyncPushRequest): Promise<SyncPushResponse | null>;
+}
+
+function defaultWsUrl(baseUrl: string): string | null {
+  try {
+    const isAbsolute = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(baseUrl);
+    const resolved =
+      isAbsolute || typeof location === 'undefined'
+        ? new URL(baseUrl)
+        : new URL(baseUrl, location.origin);
+
+    resolved.protocol = resolved.protocol === 'https:' ? 'wss:' : 'ws:';
+    resolved.pathname = `${resolved.pathname.replace(/\/$/, '')}/realtime`;
+    return resolved.toString();
+  } catch {
+    return null;
+  }
+}
+
+export function createWebSocketTransport(
+  options: WebSocketTransportOptions
+): WebSocketTransport {
+  const telemetryTransportPath = options.transportPath ?? 'relay';
+  const httpTransport = createHttpTransport({
+    baseUrl: options.baseUrl,
+    getHeaders: options.getHeaders,
+    fetch: options.fetch,
+    transportPath: telemetryTransportPath,
+  });
+
+  const {
+    baseUrl,
+    wsUrl = options.wsUrl ?? defaultWsUrl(baseUrl),
+    getRealtimeParams,
+    authToken,
+    initialReconnectDelay = 1000,
+    maxReconnectDelay = 30_000,
+    reconnectBackoffFactor = 2,
+    heartbeatTimeout = 60_000,
+    WebSocketImpl = typeof WebSocket !== 'undefined' ? WebSocket : undefined,
+  } = options;
+
+  // Warn about security risk of using getRealtimeParams with sensitive data
+  if (getRealtimeParams && !authToken) {
+    console.warn(
+      '[transport-ws] getRealtimeParams sends data in URL query parameters, ' +
+        'which may be logged by proxies and CDNs. Consider using authToken instead.'
+    );
+  }
+
+  if (!wsUrl) {
+    throw new Error(
+      '@syncular/transport-ws: wsUrl is required when baseUrl cannot be converted'
+    );
+  }
+
+  if (!WebSocketImpl) {
+    throw new Error(
+      '@syncular/transport-ws: WebSocket is not available in this runtime'
+    );
+  }
+
+  let ws: WebSocket | null = null;
+  let connectionState: WebSocketConnectionState = 'disconnected';
+  let reconnectAttempts = 0;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+
+  let currentEventCallback: WebSocketEventCallback | null = null;
+  let currentStateCallback: WebSocketStateCallback | null = null;
+  let isManuallyDisconnected = false;
+  let currentClientId: string | null = null;
+  let connectNonce = 0;
+
+  // Presence state
+  const activePresenceScopes = new Map<
+    string,
+    Record<string, unknown> | undefined
+  >();
+  const presenceCallbacks = new Set<PresenceEventCallback>();
+
+  // Pending WS push requests (requestId -> resolver)
+  const pendingPushRequests = new Map<
+    string,
+    {
+      resolve: (value: SyncPushResponse | null) => void;
+      timer: ReturnType<typeof setTimeout>;
+    }
+  >();
+  const WS_PUSH_TIMEOUT_MS = 10_000;
+
+  function setConnectionState(state: WebSocketConnectionState): void {
+    if (connectionState === state) return;
+    connectionState = state;
+    currentStateCallback?.(state);
+  }
+
+  function calculateReconnectDelay(): number {
+    const baseDelay = Math.min(
+      initialReconnectDelay * reconnectBackoffFactor ** reconnectAttempts,
+      maxReconnectDelay
+    );
+    // Add jitter to prevent thundering herd (multiple clients reconnecting simultaneously)
+    const jitterFactor = options.reconnectJitter ?? 0.3;
+    const jitter = baseDelay * jitterFactor * (Math.random() * 2 - 1); // +/- jitterFactor
+    return Math.max(0, Math.round(baseDelay + jitter));
+  }
+
+  function clearHeartbeatTimer(): void {
+    if (!heartbeatTimer) return;
+    clearTimeout(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+
+  function resetHeartbeatTimer(): void {
+    clearHeartbeatTimer();
+    if (heartbeatTimeout <= 0) return;
+
+    heartbeatTimer = setTimeout(() => {
+      doDisconnect();
+      scheduleReconnect();
+    }, heartbeatTimeout);
+  }
+
+  function clearReconnectTimer(): void {
+    if (!reconnectTimer) return;
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+
+  function scheduleReconnect(): void {
+    if (isManuallyDisconnected) return;
+
+    clearReconnectTimer();
+    const delay = calculateReconnectDelay();
+    reconnectAttempts += 1;
+
+    reconnectTimer = setTimeout(() => {
+      void doConnect();
+    }, delay);
+  }
+
+  function doDisconnect(): void {
+    clearHeartbeatTimer();
+    clearReconnectTimer();
+
+    // Resolve all pending WS push requests as null (triggers HTTP fallback)
+    for (const [, pending] of pendingPushRequests) {
+      clearTimeout(pending.timer);
+      pending.resolve(null);
+    }
+    pendingPushRequests.clear();
+
+    if (ws) {
+      try {
+        ws.onopen = null;
+        ws.onmessage = null;
+        ws.onerror = null;
+        ws.onclose = null;
+        ws.close();
+      } catch {
+        // ignore
+      }
+      ws = null;
+    }
+
+    setConnectionState('disconnected');
+  }
+
+  function dispatchEvent(raw: unknown): void {
+    resetHeartbeatTimer();
+
+    if (!raw || typeof raw !== 'object') return;
+    if (!('event' in raw) || !('data' in raw)) return;
+    const event = (raw as { event: unknown }).event;
+    const data = (raw as { data: unknown }).data;
+    if (!data || typeof data !== 'object') return;
+
+    // Route push-response events to pending request resolvers
+    if (event === 'push-response') {
+      const d = data as Record<string, unknown>;
+      const requestId = typeof d.requestId === 'string' ? d.requestId : '';
+      const pending = pendingPushRequests.get(requestId);
+      if (pending) {
+        pendingPushRequests.delete(requestId);
+        clearTimeout(pending.timer);
+        pending.resolve({
+          ok: true as const,
+          status: (d.status as 'applied' | 'cached' | 'rejected') ?? 'rejected',
+          commitSeq: typeof d.commitSeq === 'number' ? d.commitSeq : undefined,
+          results: Array.isArray(d.results)
+            ? (d.results as SyncPushResponse['results'])
+            : [],
+        });
+      }
+      return;
+    }
+
+    // Route presence events to dedicated callbacks
+    if (event === 'presence') {
+      const presenceData = (data as { presence?: unknown }).presence;
+      if (presenceData && typeof presenceData === 'object') {
+        for (const cb of presenceCallbacks) {
+          cb(presenceData as PresenceEventData);
+        }
+      }
+      // Also forward to main event callback
+      if (currentEventCallback) {
+        currentEventCallback({ event, data } as WebSocketEvent);
+      }
+      return;
+    }
+
+    if (event !== 'sync' && event !== 'heartbeat' && event !== 'error') return;
+    currentEventCallback?.({ event, data } as WebSocketEvent);
+  }
+
+  function sendPresenceMessage(msg: Record<string, unknown>): void {
+    if (!ws || ws.readyState !== WebSocketImpl!.OPEN) return;
+    ws.send(JSON.stringify({ type: 'presence', ...msg }));
+  }
+
+  async function buildUrl(clientId: string): Promise<string> {
+    if (!wsUrl) throw new Error('wsUrl is required');
+    // Handle relative URLs by using location.origin as base
+    const isAbsolute = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(wsUrl);
+    const url =
+      isAbsolute || typeof location === 'undefined'
+        ? new URL(wsUrl)
+        : new URL(wsUrl, location.origin);
+    // Convert http(s) to ws(s) if needed
+    if (url.protocol === 'https:') url.protocol = 'wss:';
+    if (url.protocol === 'http:') url.protocol = 'ws:';
+    url.searchParams.set('clientId', clientId);
+
+    if (getRealtimeParams) {
+      try {
+        const params = await getRealtimeParams({ clientId });
+        for (const [k, v] of Object.entries(params ?? {})) {
+          if (typeof v !== 'string') continue;
+          if (!v) continue;
+          url.searchParams.set(k, v);
+        }
+      } catch {
+        // ignore; realtime is best-effort
+      }
+    }
+
+    url.searchParams.set('transportPath', telemetryTransportPath);
+
+    return url.toString();
+  }
+
+  async function doConnect(): Promise<void> {
+    if (!currentClientId) return;
+    if (isManuallyDisconnected) return;
+
+    const nonce = ++connectNonce;
+
+    setConnectionState('connecting');
+
+    const url = await buildUrl(currentClientId);
+    if (nonce !== connectNonce) return;
+
+    if (!WebSocketImpl) throw new Error('WebSocketImpl is required');
+
+    try {
+      ws = new WebSocketImpl(url);
+    } catch {
+      doDisconnect();
+      scheduleReconnect();
+      return;
+    }
+
+    ws.onopen = async () => {
+      if (nonce !== connectNonce) return;
+
+      // Send auth token if provided (more secure than query params)
+      if (authToken && ws) {
+        try {
+          const token =
+            typeof authToken === 'function' ? await authToken() : authToken;
+          if (token && nonce === connectNonce) {
+            ws.send(JSON.stringify({ type: 'auth', token }));
+          }
+        } catch {
+          // Auth token failed, but connection is still open
+          // Server will handle unauthenticated connection appropriately
+        }
+      }
+
+      if (nonce !== connectNonce) return;
+      setConnectionState('connected');
+      reconnectAttempts = 0;
+      resetHeartbeatTimer();
+
+      // Re-join all active presence scopes on reconnect
+      for (const [scopeKey, metadata] of activePresenceScopes) {
+        sendPresenceMessage({ action: 'join', scopeKey, metadata });
+      }
+    };
+
+    ws.onmessage = (evt) => {
+      if (nonce !== connectNonce) return;
+      resetHeartbeatTimer();
+
+      if (typeof evt.data === 'string') {
+        try {
+          dispatchEvent(JSON.parse(evt.data));
+        } catch {
+          // ignore malformed messages
+        }
+      }
+    };
+
+    ws.onerror = () => {
+      if (nonce !== connectNonce) return;
+      doDisconnect();
+      scheduleReconnect();
+    };
+
+    ws.onclose = () => {
+      if (nonce !== connectNonce) return;
+      doDisconnect();
+      scheduleReconnect();
+    };
+  }
+
+  return {
+    ...httpTransport,
+    connect(args, onEvent, onStateChange) {
+      currentClientId = args.clientId;
+      currentEventCallback = onEvent;
+      currentStateCallback = onStateChange ?? null;
+      isManuallyDisconnected = false;
+      reconnectAttempts = 0;
+      void doConnect();
+
+      return () => {
+        isManuallyDisconnected = true;
+        currentEventCallback = null;
+        currentStateCallback = null;
+        currentClientId = null;
+        connectNonce += 1;
+        doDisconnect();
+      };
+    },
+    getConnectionState() {
+      return connectionState;
+    },
+    reconnect() {
+      if (!currentClientId) return;
+      if (isManuallyDisconnected) return;
+      connectNonce += 1;
+      doDisconnect();
+      void doConnect();
+    },
+    sendPresenceJoin(scopeKey, metadata) {
+      activePresenceScopes.set(scopeKey, metadata);
+      sendPresenceMessage({ action: 'join', scopeKey, metadata });
+    },
+    sendPresenceLeave(scopeKey) {
+      activePresenceScopes.delete(scopeKey);
+      sendPresenceMessage({ action: 'leave', scopeKey });
+    },
+    sendPresenceUpdate(scopeKey, metadata) {
+      activePresenceScopes.set(scopeKey, metadata);
+      sendPresenceMessage({ action: 'update', scopeKey, metadata });
+    },
+    onPresenceEvent(callback) {
+      presenceCallbacks.add(callback);
+      return () => {
+        presenceCallbacks.delete(callback);
+      };
+    },
+    pushViaWs(request: SyncPushRequest): Promise<SyncPushResponse | null> {
+      if (!ws || ws.readyState !== WebSocketImpl!.OPEN) {
+        return Promise.resolve(null);
+      }
+
+      const requestId = crypto.randomUUID();
+
+      return new Promise<SyncPushResponse | null>((resolve) => {
+        const timer = setTimeout(() => {
+          pendingPushRequests.delete(requestId);
+          resolve(null);
+        }, WS_PUSH_TIMEOUT_MS);
+
+        pendingPushRequests.set(requestId, { resolve, timer });
+
+        try {
+          ws!.send(
+            JSON.stringify({
+              type: 'push',
+              requestId,
+              clientCommitId: request.clientCommitId,
+              operations: request.operations,
+              schemaVersion: request.schemaVersion,
+            })
+          );
+        } catch {
+          pendingPushRequests.delete(requestId);
+          clearTimeout(timer);
+          resolve(null);
+        }
+      });
+    },
+  };
+}