@belysh/socket-bridge-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Socket Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# Socket Bridge client
+
+Optional, framework-neutral helper around Socket.IO. React is not required.
+The gateway also accepts a plain `socket.io-client`.
+
+The client is distributed as a tarball attached to each GitHub release. See the
+[Laravel package README](https://github.com/Belysh/laravel-socket-bridge#readme)
+for the matching installation URL. Build from source with `npm ci && npm run build`.
+
+```ts
+import { createBridge } from '@belysh/socket-bridge-client';
+
+const bridge = createBridge({
+  url: 'http://localhost:6001',
+  tokenEndpoint: '/socket-bridge/token',
+  onResync: () => refreshCurrentScreenFromApi(),
+  onError: (error) => console.error(error.message),
+});
+
+await bridge.join('private-chat.42'); // Exact Laravel PrivateChannel wire name.
+const unsubscribe = bridge.on('chat.message.created', (payload, metadata) => {
+  renderMessage(payload.message);
+});
+bridge.connect();
+
+// HTTP mutations must carry the originating socket ID for Laravel toOthers().
+await fetch('/messages', {
+  method: 'POST',
+  headers: bridge.headers({ 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrf }),
+  body: JSON.stringify({ text: 'Hello' }),
+});
+
+// A result resolves only after Laravel processes the command, not on enqueue.
+// Submit after the socket is connected, for example from a UI event handler.
+const commandId = crypto.randomUUID();
+const message = await bridge.command('chat.message.create', { text: 'Hello' }, commandId);
+```
+
+For bearer authentication, provide `getToken`, or `tokenHeaders` returning an
+Authorization header. Credentials go to Laravel's ticket endpoint, not the
+gateway. A fresh one-use ticket is obtained on every reconnect.
+
+Cookie applications must already establish their Laravel session and CSRF
+cookie/token. The helper forwards a Blade `csrf-token` meta tag or an existing
+`XSRF-TOKEN` cookie; it does not invent a login flow. Responses `{token: ...}`
+and `{data: {token: ...}}` are supported.
+
+Join before or after connecting. Reconnect reauthorizes remembered channels and
+calls `onResync`; the gateway does not persist application history for clients.
+`bridge.on` suppresses duplicate event IDs within a bounded per-listener window.
+Revoked subscriptions invoke `onError` with code `subscription.revoked` and are
+removed from automatic reconnection. Subscribe again explicitly if access changes.
+Use `bridge.socket` for raw Socket.IO access. It remains the same connection.
+
+After an unknown command outcome, retain and retry the same ID and payload
+within the same authenticated session. Do not generate a fresh ID blindly:
+the first attempt may already have committed. `BridgeError.commandId` preserves
+the ID on timeout. `disconnect()` can reconnect; `destroy()` rejects pending
+requests, removes subscriptions/listeners and permanently disposes the helper.
+
+The helper refreshes an expiring socket session with a fresh Laravel ticket.
+The gateway accepts the refresh only for the existing user, session and access
+version. Temporary Redis/network failures retry with bounded backoff; a revoked
+session stops automatic reconnection. Call `connect()` explicitly after the user
+has authenticated again.
+
+Channel authorization renews before its lease expires. During a temporary
+Laravel outage, the gateway retains the last valid grant until its deadline,
+then suspends delivery until reauthorization succeeds. Subscription intent is
+retained and `onResync` runs after recovery. A definite denial removes the
+subscription. Applications should refetch authoritative state in `onResync`.
+
+Raw Socket.IO integrations can implement the same lifecycle by listening for
+`bridge.session` and sending `session:refresh` with `{ token }` before expiry;
+`bridge.disconnect.retryable` distinguishes a recoverable outage/expiry from
+revocation. Only retry a server disconnect when this flag is `true`.

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { io, type Socket } from 'socket.io-client';
+export type JsonObject = Record<string, unknown>;
+export interface EventMetadata {
+    id: string;
+    created_at: string;
+    v: 1;
+}
+export interface BridgeErrorData {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface CommandResult<T = unknown> {
+    command_id: string;
+    result: {
+        ok: boolean;
+        data?: T;
+        error?: BridgeErrorData;
+    };
+}
+export interface BridgeOptions {
+    url: string;
+    tokenEndpoint?: string;
+    /** Override for bearer auth, custom routing, or a different response envelope. */
+    getToken?: () => Promise<string>;
+    fetch?: typeof globalThis.fetch;
+    tokenHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    timeout?: number;
+    onResync?: () => void | Promise<void>;
+    onError?: (error: Error) => void;
+    /** Injectable for tests. Consumers normally use the default Socket.IO factory. */
+    socketFactory?: typeof io;
+}
+export declare class BridgeError extends Error {
+    readonly code: string;
+    readonly commandId?: string | undefined;
+    constructor(code: string, message: string, commandId?: string | undefined);
+}
+/** A thin helper; the underlying ordinary Socket.IO socket remains available. */
+export declare class SocketBridge {
+    private readonly options;
+    readonly socket: Socket;
+    private readonly desiredChannels;
+    private readonly pending;
+    private readonly fetcher;
+    private readonly timeout;
+    private destroyed;
+    private wantConnected;
+    private terminal;
+    private retryableDisconnect;
+    private authError?;
+    private reconnectTimer?;
+    private refreshTimer?;
+    private reconnectAttempts;
+    private refreshAttempts;
+    private refreshGeneration;
+    private readonly channelRetries;
+    constructor(options: BridgeOptions);
+    connect(): this;
+    disconnect(): void;
+    destroy(): void;
+    join(channel: string): Promise<void>;
+    leave(channel: string): Promise<void>;
+    /** Dedupe is bounded and per listener, so multiple consumers all receive a new event. */
+    on<T = JsonObject>(event: string, listener: (payload: T, metadata?: EventMetadata) => void): () => void;
+    /** Keep id when retrying after an unknown outcome. Accepted ACK is not business success. */
+    command<T = unknown>(command: string, payload: JsonObject, id?: string): Promise<T>;
+    /** Merge into HTTP mutations to enable Laravel InteractsWithSockets / toOthers(). */
+    headers(initial?: HeadersInit): Headers;
+    private obtainToken;
+    private restoreSubscriptions;
+    private resync;
+    private isTerminal;
+    private stopForRevocation;
+    private backoff;
+    private scheduleReconnect;
+    private clearRefresh;
+    private scheduleRefresh;
+    private refresh;
+    private forgetChannel;
+    private failedSubscription;
+    private ack;
+    private report;
+}
+export declare function createBridge(options: BridgeOptions): SocketBridge;

package/dist/index.js

@@ -0,0 +1,338 @@
+import { io } from 'socket.io-client';
+export class BridgeError extends Error {
+    code;
+    commandId;
+    constructor(code, message, commandId) {
+        super(message);
+        this.code = code;
+        this.commandId = commandId;
+        this.name = 'BridgeError';
+    }
+}
+/** A thin helper; the underlying ordinary Socket.IO socket remains available. */
+export class SocketBridge {
+    options;
+    socket;
+    desiredChannels = new Set();
+    pending = new Map();
+    fetcher;
+    timeout;
+    destroyed = false;
+    wantConnected = false;
+    terminal = false;
+    retryableDisconnect = false;
+    authError;
+    reconnectTimer;
+    refreshTimer;
+    reconnectAttempts = 0;
+    refreshAttempts = 0;
+    refreshGeneration = 0;
+    channelRetries = new Map();
+    constructor(options) {
+        this.options = options;
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.timeout = options.timeout ?? 15_000;
+        this.socket = (options.socketFactory ?? io)(options.url, {
+            autoConnect: false,
+            transports: ['websocket'],
+            withCredentials: true,
+            auth: (done) => {
+                this.authError = undefined;
+                this.obtainToken().then((token) => done({ token })).catch((error) => {
+                    this.authError = error;
+                    // End the handshake instead of hanging indefinitely; never reuse a consumed ticket.
+                    done({ token: '' });
+                });
+            },
+        });
+        this.socket.on('connect', () => {
+            this.reconnectAttempts = 0;
+            this.retryableDisconnect = false;
+            if (this.reconnectTimer)
+                clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+            void this.restoreSubscriptions();
+        });
+        this.socket.on('connect_error', (error) => {
+            const reason = this.authError ?? new BridgeError(error.data?.code ?? 'transport.unavailable', error.message);
+            this.authError = undefined;
+            this.report(reason);
+            if (this.isTerminal(reason))
+                this.stopForRevocation();
+            else
+                this.scheduleReconnect();
+        });
+        this.socket.on('bridge.disconnect', (packet) => {
+            this.retryableDisconnect = packet.retryable === true;
+            if (!this.retryableDisconnect)
+                this.stopForRevocation();
+            this.report(new BridgeError(packet.code, packet.retryable ? 'Realtime connection will be restored.' : 'Realtime access was revoked.'));
+        });
+        this.socket.on('disconnect', () => {
+            this.clearRefresh();
+            for (const retry of this.channelRetries.values())
+                clearTimeout(retry.timer);
+            this.channelRetries.clear();
+            if (this.retryableDisconnect)
+                this.scheduleReconnect();
+        });
+        this.socket.on('bridge.session', (packet) => {
+            if (Number.isFinite(packet.refresh_after_ms) && packet.refresh_after_ms >= 0) {
+                this.refreshAttempts = 0;
+                this.scheduleRefresh(Math.min(packet.refresh_after_ms, 2_147_483_647));
+            }
+        });
+        this.socket.on('bridge.subscription.restored', () => { void this.resync(); });
+        this.socket.on('bridge.subscription.revoked', (packet) => {
+            this.forgetChannel(packet.channel);
+            this.report(new BridgeError('subscription.revoked', `Access to ${packet.channel} was revoked.`));
+        });
+        this.socket.on('bridge.command.result', (packet) => {
+            const item = this.pending.get(packet.command_id);
+            if (!item)
+                return;
+            clearTimeout(item.timer);
+            this.pending.delete(packet.command_id);
+            if (packet.result.ok)
+                item.resolve(packet.result.data);
+            else
+                item.reject(new BridgeError(packet.result.error?.code ?? 'command.failed', packet.result.error?.message ?? 'Command failed', packet.command_id));
+        });
+    }
+    connect() {
+        if (this.destroyed)
+            throw new BridgeError('client.destroyed', 'Create a new client after destroy().');
+        this.wantConnected = true;
+        this.terminal = false;
+        this.socket.connect();
+        return this;
+    }
+    disconnect() {
+        this.wantConnected = false;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        this.clearRefresh();
+        for (const retry of this.channelRetries.values())
+            clearTimeout(retry.timer);
+        this.channelRetries.clear();
+        this.socket.disconnect();
+    }
+    destroy() {
+        this.destroyed = true;
+        this.disconnect();
+        this.socket.removeAllListeners();
+        for (const [id, item] of this.pending) {
+            clearTimeout(item.timer);
+            item.reject(new BridgeError('client.destroyed', 'Client was destroyed; the command may still be processing.', id));
+        }
+        this.pending.clear();
+        this.desiredChannels.clear();
+    }
+    async join(channel) {
+        this.desiredChannels.add(channel);
+        if (this.socket.connected) {
+            try {
+                await this.ack('room:join', { channel });
+            }
+            catch (error) {
+                this.failedSubscription(channel, error);
+                throw error;
+            }
+        }
+    }
+    async leave(channel) {
+        this.forgetChannel(channel);
+        if (this.socket.connected)
+            await this.ack('room:leave', { channel });
+    }
+    /** Dedupe is bounded and per listener, so multiple consumers all receive a new event. */
+    on(event, listener) {
+        const seen = new Set();
+        const wrapped = (payload, metadata) => {
+            if (metadata?.id) {
+                if (seen.has(metadata.id))
+                    return;
+                seen.add(metadata.id);
+                if (seen.size > 1_000)
+                    seen.delete(seen.values().next().value);
+            }
+            listener(payload, metadata);
+        };
+        this.socket.on(event, wrapped);
+        return () => this.socket.off(event, wrapped);
+    }
+    /** Keep id when retrying after an unknown outcome. Accepted ACK is not business success. */
+    command(command, payload, id = globalThis.crypto.randomUUID()) {
+        if (!this.socket.connected)
+            return Promise.reject(new BridgeError('socket.disconnected', 'Connect before submitting commands.', id));
+        if (this.pending.has(id))
+            return Promise.reject(new BridgeError('command.pending', 'This command already has a pending request.', id));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new BridgeError('command.timeout', 'Command outcome is unknown. Retry with the same command ID.', id));
+            }, this.timeout);
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            void this.ack('command', { id, command, payload }).catch((error) => {
+                const item = this.pending.get(id);
+                if (!item)
+                    return;
+                clearTimeout(item.timer);
+                this.pending.delete(id);
+                reject(error instanceof BridgeError ? new BridgeError(error.code, error.message, id) : error);
+            });
+        });
+    }
+    /** Merge into HTTP mutations to enable Laravel InteractsWithSockets / toOthers(). */
+    headers(initial) {
+        const headers = new Headers(initial);
+        if (this.socket.connected && this.socket.id)
+            headers.set('X-Socket-ID', this.socket.id);
+        return headers;
+    }
+    async obtainToken() {
+        if (this.options.getToken)
+            return this.options.getToken();
+        const initial = typeof this.options.tokenHeaders === 'function' ? await this.options.tokenHeaders() : this.options.tokenHeaders;
+        const headers = new Headers(initial);
+        headers.set('Accept', 'application/json');
+        if (typeof document !== 'undefined') {
+            const csrf = document.querySelector('meta[name="csrf-token"]')?.content;
+            const xsrf = document.cookie.split('; ').find((v) => v.startsWith('XSRF-TOKEN='))?.slice(11);
+            if (csrf && !headers.has('X-CSRF-TOKEN'))
+                headers.set('X-CSRF-TOKEN', csrf);
+            else if (xsrf && !headers.has('X-XSRF-TOKEN'))
+                headers.set('X-XSRF-TOKEN', decodeURIComponent(xsrf));
+        }
+        const response = await this.fetcher(this.options.tokenEndpoint ?? '/socket-bridge/token', {
+            method: 'POST', credentials: 'include', headers, signal: AbortSignal.timeout(this.timeout),
+        });
+        if (!response.ok)
+            throw new BridgeError([401, 403, 419].includes(response.status) ? 'auth.revoked' : 'auth.ticket_failed', `Laravel rejected the connection ticket request (${response.status}).`);
+        const body = await response.json();
+        const token = body.token ?? body.data?.token;
+        if (!token)
+            throw new BridgeError('auth.invalid_response', 'Ticket response did not include a token.');
+        return token;
+    }
+    async restoreSubscriptions() {
+        for (const channel of this.desiredChannels) {
+            try {
+                await this.ack('room:join', { channel });
+            }
+            catch (error) {
+                this.failedSubscription(channel, error);
+                this.report(error);
+            }
+        }
+        await this.resync();
+    }
+    async resync() {
+        try {
+            await this.options.onResync?.();
+        }
+        catch (error) {
+            this.report(error);
+        }
+    }
+    isTerminal(error) {
+        return error instanceof BridgeError && ['unauthenticated', 'session_revoked', 'auth.revoked', 'forbidden', 'invalid_channel', 'subscription_cancelled'].includes(error.code);
+    }
+    stopForRevocation() {
+        this.terminal = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        this.clearRefresh();
+        for (const retry of this.channelRetries.values())
+            clearTimeout(retry.timer);
+        this.channelRetries.clear();
+    }
+    backoff(attempt) { return Math.min(10_000, 250 * 2 ** Math.min(attempt, 6)) * (0.75 + Math.random() * 0.5); }
+    scheduleReconnect() {
+        if (this.destroyed || this.terminal || !this.wantConnected || this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (!this.destroyed && !this.terminal && this.wantConnected && !this.socket.connected)
+                this.socket.connect();
+        }, this.backoff(this.reconnectAttempts++));
+    }
+    clearRefresh() {
+        this.refreshGeneration++;
+        if (this.refreshTimer)
+            clearTimeout(this.refreshTimer);
+        this.refreshTimer = undefined;
+    }
+    scheduleRefresh(ms) {
+        this.clearRefresh();
+        const generation = this.refreshGeneration;
+        this.refreshTimer = setTimeout(() => {
+            this.refreshTimer = undefined;
+            void this.refresh(generation);
+        }, ms);
+    }
+    async refresh(generation) {
+        if (!this.socket.connected || this.terminal || this.destroyed)
+            return;
+        try {
+            const token = await this.obtainToken();
+            if (!this.socket.connected || generation !== this.refreshGeneration)
+                return;
+            await this.ack('session:refresh', { token });
+            // The gateway sends the next expiry/schedule using bridge.session.
+        }
+        catch (error) {
+            if (generation !== this.refreshGeneration)
+                return;
+            this.report(error);
+            if (this.isTerminal(error)) {
+                this.stopForRevocation();
+                this.socket.disconnect();
+            }
+            else if (this.socket.connected)
+                this.scheduleRefresh(this.backoff(this.refreshAttempts++));
+        }
+    }
+    forgetChannel(channel) {
+        this.desiredChannels.delete(channel);
+        const retry = this.channelRetries.get(channel);
+        if (retry)
+            clearTimeout(retry.timer);
+        this.channelRetries.delete(channel);
+    }
+    failedSubscription(channel, error, attempts = 0) {
+        if (this.isTerminal(error)) {
+            this.forgetChannel(channel);
+            return;
+        }
+        if (!this.desiredChannels.has(channel) || this.channelRetries.has(channel) || !this.socket.connected || this.destroyed || this.terminal)
+            return;
+        const timer = setTimeout(() => {
+            this.channelRetries.delete(channel);
+            if (!this.desiredChannels.has(channel) || !this.socket.connected || this.destroyed || this.terminal)
+                return;
+            void this.ack('room:join', { channel }).then(() => this.resync(), next => {
+                this.failedSubscription(channel, next, attempts + 1);
+                this.report(next);
+            });
+        }, this.backoff(attempts));
+        this.channelRetries.set(channel, { attempts, timer });
+    }
+    ack(event, payload) {
+        return new Promise((resolve, reject) => {
+            this.socket.timeout(this.timeout).emit(event, payload, (error, response) => {
+                if (error)
+                    return reject(new BridgeError('socket.ack_timeout', 'Gateway acknowledgement timed out. The outcome may be unknown.'));
+                if (!response?.ok)
+                    return reject(new BridgeError(response?.error?.code ?? 'socket.rejected', response?.error?.message ?? 'Gateway rejected the request.'));
+                resolve(response);
+            });
+        });
+    }
+    report(error) {
+        this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
+    }
+}
+export function createBridge(options) { return new SocketBridge(options); }

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@belysh/socket-bridge-client",
+  "version": "1.0.0",
+  "description": "Framework-neutral Socket.IO client for Laravel Socket Bridge",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Belysh/laravel-socket-bridge.git",
+    "directory": "client"
+  },
+  "homepage": "https://github.com/Belysh/laravel-socket-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/Belysh/laravel-socket-bridge/issues"
+  },
+  "keywords": [
+    "laravel",
+    "websocket",
+    "socket.io",
+    "redis",
+    "realtime"
+  ]
+}