@belysh/socket-bridge-client 1.0.0 → 1.1.0

package/README.md

@@ -1,11 +1,17 @@
 # Socket Bridge client
 
-Optional, framework-neutral helper around Socket.IO. React is not required.
+Optional, framework-neutral helper around Socket.IO. React and Vue are 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`.
+```bash
+npm install @belysh/socket-bridge-client
+```
+
+Use the matching release of the
+[Laravel package](https://github.com/Belysh/laravel-socket-bridge#readme).
+Compiled ESM and TypeScript declarations are included. The tested client tarball
+is also attached to each GitHub release. To develop the client itself, build from
+source with `npm ci && npm run build`.
 
 ```ts
 import { createBridge } from '@belysh/socket-bridge-client';
@@ -17,23 +23,28 @@ const bridge = createBridge({
   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) => {
+const chat = bridge.private('chat.42').listen('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' }),
-});
+// Call from a UI action after connection. Include the socket ID for toOthers().
+async function sendMessage(text: string) {
+  if (!bridge.socket.connected) throw new Error('Realtime connection is not ready.');
+  return fetch('/messages', {
+    method: 'POST',
+    headers: bridge.headers({ 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrf }),
+    body: JSON.stringify({ text }),
+  });
+}
 
 // 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);
+// Keep commandId in your UI state if the outcome is unknown and needs a retry.
+async function sendCommand(text: string, commandId: string) {
+  return bridge.command('chat.message.create', { text }, commandId);
+}
+
+// When this screen is removed: chat.dispose().
 ```
 
 For bearer authentication, provide `getToken`, or `tokenHeaders` returning an
@@ -74,3 +85,25 @@ 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`.
+
+## Channels, React and Vue (1.1)
+
+```ts
+const orders = bridge.private('orders.42')
+  .listen('order.updated', order => updateOrder(order))
+  .error(error => showError(error.message));
+// Remove only this screen's listeners/subscription reference:
+orders.dispose();
+```
+
+Channel-scoped listeners require the matching 1.1+ gateway channel metadata;
+legacy global `on()` and manual `join()` remain available. Multiple handles share
+a room and only the last disposal leaves it. `presence()` exposes authoritative
+`here` snapshots and `joining`/`leaving` changes. `BridgeError.details` preserves
+Laravel field validation errors.
+
+Optional integrations are exported from `@belysh/socket-bridge-client/react`
+(React 18/19) and `/vue` (Vue 3.5+). They provide `useSocketBridge`,
+`useChannelEvent` and `usePresence`, with reference-counted subscriptions and
+lifecycle cleanup. Neither framework is loaded by the base entry point.
+See [the complete client guide](https://github.com/Belysh/laravel-socket-bridge/blob/main/docs/CLIENT.md).

package/dist/channel.d.ts

@@ -0,0 +1,39 @@
+import type { EventMetadata, JsonObject, SocketBridge } from './index.js';
+export interface PresenceMember<T = JsonObject> {
+    id: string;
+    info: T;
+}
+export type ChannelListener<T = JsonObject> = (payload: T, metadata?: EventMetadata) => void;
+/** One subscription owner. Dispose only releases this owner's listeners and room reference. */
+export declare class BridgeChannel {
+    private readonly bridge;
+    readonly name: string;
+    ready: Promise<void>;
+    private disposed;
+    private listeners;
+    private hereListeners;
+    private joiningListeners;
+    private leavingListeners;
+    private errorListeners;
+    private members?;
+    private lastError?;
+    constructor(bridge: SocketBridge, name: string);
+    listen<T = JsonObject>(event: string, listener: ChannelListener<T>): this;
+    stopListening<T = JsonObject>(event: string, listener?: ChannelListener<T>): this;
+    notification<T = JsonObject>(listener: ChannelListener<T>): this;
+    /** Called with each authoritative presence snapshot, including refreshed member information. */
+    here(listener: (members: PresenceMember[]) => void): this;
+    joining(listener: (member: PresenceMember) => void): this;
+    leaving(listener: (member: PresenceMember) => void): this;
+    error(listener: (error: Error) => void): this;
+    /** Release this handle. Other components subscribed to the same channel remain connected. */
+    dispose(): void;
+    leave(): void;
+    /** @internal */
+    receivePresence(members: PresenceMember[]): void;
+    /** @internal */
+    resetPresence(): void;
+    /** @internal */
+    receiveError(error: unknown): void;
+    private assertActive;
+}

package/dist/channel.js

@@ -0,0 +1,116 @@
+const notificationEvent = 'Illuminate\\Notifications\\Events\\BroadcastNotificationCreated';
+/** One subscription owner. Dispose only releases this owner's listeners and room reference. */
+export class BridgeChannel {
+    bridge;
+    name;
+    ready = Promise.resolve();
+    disposed = false;
+    listeners = new Map();
+    hereListeners = new Set();
+    joiningListeners = new Set();
+    leavingListeners = new Set();
+    errorListeners = new Set();
+    members;
+    lastError;
+    constructor(bridge, name) {
+        this.bridge = bridge;
+        this.name = name;
+    }
+    listen(event, listener) {
+        this.assertActive();
+        const listeners = this.listeners.get(event) ?? new Map();
+        if (!listeners.has(listener)) {
+            listeners.set(listener, this.bridge.on(event, (payload, metadata) => {
+                // Old gateways cannot safely support scoped listeners. Never fall back to unfiltered delivery.
+                if (metadata?.channels?.includes(this.name))
+                    listener(payload, metadata);
+            }));
+            this.listeners.set(event, listeners);
+        }
+        return this;
+    }
+    stopListening(event, listener) {
+        const listeners = this.listeners.get(event);
+        if (listener) {
+            listeners?.get(listener)?.();
+            listeners?.delete(listener);
+        }
+        else {
+            for (const stop of listeners?.values() ?? [])
+                stop();
+            this.listeners.delete(event);
+        }
+        return this;
+    }
+    notification(listener) { return this.listen(notificationEvent, listener); }
+    /** Called with each authoritative presence snapshot, including refreshed member information. */
+    here(listener) {
+        this.assertActive();
+        this.hereListeners.add(listener);
+        if (this.members)
+            listener(this.members);
+        return this;
+    }
+    joining(listener) { this.assertActive(); this.joiningListeners.add(listener); return this; }
+    leaving(listener) { this.assertActive(); this.leavingListeners.add(listener); return this; }
+    error(listener) {
+        this.assertActive();
+        this.errorListeners.add(listener);
+        if (this.lastError)
+            listener(this.lastError);
+        return this;
+    }
+    /** Release this handle. Other components subscribed to the same channel remain connected. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const event of this.listeners.keys())
+            this.stopListening(event);
+        this.hereListeners.clear();
+        this.joiningListeners.clear();
+        this.leavingListeners.clear();
+        this.errorListeners.clear();
+        this.members = undefined;
+        this.bridge.releaseChannel(this);
+    }
+    leave() { this.dispose(); }
+    /** @internal */
+    receivePresence(members) {
+        if (this.disposed)
+            return;
+        const previous = this.members;
+        this.members = members;
+        for (const listener of this.hereListeners)
+            listener(members);
+        // A first snapshot establishes a baseline; reconnects must not synthesize everyone joining.
+        if (!previous)
+            return;
+        const old = new Map(previous.map(member => [member.id, member]));
+        const current = new Map(members.map(member => [member.id, member]));
+        for (const [id, member] of current)
+            if (!old.has(id))
+                for (const listener of this.joiningListeners)
+                    listener(member);
+        for (const [id, member] of old)
+            if (!current.has(id))
+                for (const listener of this.leavingListeners)
+                    listener(member);
+    }
+    /** @internal */
+    resetPresence() {
+        this.members = undefined;
+        for (const listener of this.hereListeners)
+            listener([]);
+    }
+    /** @internal */
+    receiveError(error) {
+        if (this.disposed)
+            return;
+        this.lastError = error instanceof Error ? error : new Error(String(error));
+        for (const listener of this.errorListeners)
+            listener(this.lastError);
+    }
+    assertActive() { if (this.disposed)
+        throw new Error('This channel handle has been disposed. Create a new handle.'); }
+}

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 import { io, type Socket } from 'socket.io-client';
+import { BridgeChannel } from './channel.js';
+export { BridgeChannel, type PresenceMember } from './channel.js';
 export type JsonObject = Record<string, unknown>;
 export interface EventMetadata {
     id: string;
     created_at: string;
-    v: 1;
+    v: 1; /** Canonical authorized channel targets; available from gateway 1.1. */
+    channels?: string[];
 }
 export interface BridgeErrorData {
     code: string;
@@ -34,13 +37,22 @@ export interface BridgeOptions {
 export declare class BridgeError extends Error {
     readonly code: string;
     readonly commandId?: string | undefined;
-    constructor(code: string, message: string, commandId?: string | undefined);
+    readonly details?: unknown | undefined;
+    constructor(code: string, message: string, commandId?: string | undefined, details?: unknown | 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 manualChannels;
+    private readonly channels;
+    private readonly channelJoins;
+    private readonly activeChannels;
+    private readonly presenceSnapshots;
+    private connectionGeneration;
+    private connectionReferences;
+    private managedConnection;
     private readonly pending;
     private readonly fetcher;
     private readonly timeout;
@@ -57,10 +69,19 @@ export declare class SocketBridge {
     private readonly channelRetries;
     constructor(options: BridgeOptions);
     connect(): this;
+    private beginConnection;
+    /** Reference-count a framework consumer without closing a manually connected socket. */
+    retainConnection(): () => void;
     disconnect(): void;
     destroy(): void;
     join(channel: string): Promise<void>;
     leave(channel: string): Promise<void>;
+    /** Create an independently disposable subscription to an exact canonical channel. */
+    channel(name: string): BridgeChannel;
+    private(name: string): BridgeChannel;
+    presence(name: string): BridgeChannel;
+    /** Internal lifetime hook used by channel handles. */
+    releaseChannel(handle: BridgeChannel): 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. */
@@ -68,6 +89,7 @@ export declare class SocketBridge {
     /** Merge into HTTP mutations to enable Laravel InteractsWithSockets / toOthers(). */
     headers(initial?: HeadersInit): Headers;
     private obtainToken;
+    private subscribeChannel;
     private restoreSubscriptions;
     private resync;
     private isTerminal;

package/dist/index.js

@@ -1,11 +1,15 @@
 import { io } from 'socket.io-client';
+import { BridgeChannel } from './channel.js';
+export { BridgeChannel } from './channel.js';
 export class BridgeError extends Error {
     code;
     commandId;
-    constructor(code, message, commandId) {
+    details;
+    constructor(code, message, commandId, details) {
         super(message);
         this.code = code;
         this.commandId = commandId;
+        this.details = details;
         this.name = 'BridgeError';
     }
 }
@@ -14,6 +18,14 @@ export class SocketBridge {
     options;
     socket;
     desiredChannels = new Set();
+    manualChannels = new Set();
+    channels = new Map();
+    channelJoins = new Map();
+    activeChannels = new Set();
+    presenceSnapshots = new Map();
+    connectionGeneration = 0;
+    connectionReferences = 0;
+    managedConnection = false;
     pending = new Map();
     fetcher;
     timeout;
@@ -46,6 +58,9 @@ export class SocketBridge {
             },
         });
         this.socket.on('connect', () => {
+            this.connectionGeneration++;
+            this.activeChannels.clear();
+            this.channelJoins.clear();
             this.reconnectAttempts = 0;
             this.retryableDisconnect = false;
             if (this.reconnectTimer)
@@ -54,7 +69,7 @@ export class SocketBridge {
             void this.restoreSubscriptions();
         });
         this.socket.on('connect_error', (error) => {
-            const reason = this.authError ?? new BridgeError(error.data?.code ?? 'transport.unavailable', error.message);
+            const reason = this.authError ?? new BridgeError(error.data?.code ?? 'transport.unavailable', error.data?.message ?? error.message, undefined, error.data?.details);
             this.authError = undefined;
             this.report(reason);
             if (this.isTerminal(reason))
@@ -69,6 +84,13 @@ export class SocketBridge {
             this.report(new BridgeError(packet.code, packet.retryable ? 'Realtime connection will be restored.' : 'Realtime access was revoked.'));
         });
         this.socket.on('disconnect', () => {
+            this.connectionGeneration++;
+            this.activeChannels.clear();
+            this.channelJoins.clear();
+            this.presenceSnapshots.clear();
+            for (const handles of this.channels.values())
+                for (const handle of handles)
+                    handle.resetPresence();
             this.clearRefresh();
             for (const retry of this.channelRetries.values())
                 clearTimeout(retry.timer);
@@ -82,10 +104,33 @@ export class SocketBridge {
                 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.presence', (packet) => {
+            if (!packet || typeof packet.channel !== 'string' || !Array.isArray(packet.members) || !this.desiredChannels.has(packet.channel))
+                return;
+            this.presenceSnapshots.set(packet.channel, packet.members);
+            for (const handle of this.channels.get(packet.channel) ?? [])
+                handle.receivePresence(packet.members);
+        });
+        this.socket.on('bridge.subscription.suspended', (packet) => {
+            this.activeChannels.delete(packet.channel);
+            this.presenceSnapshots.delete(packet.channel);
+            for (const handle of this.channels.get(packet.channel) ?? [])
+                handle.resetPresence();
+        });
+        this.socket.on('bridge.subscription.restored', (packet) => {
+            if (this.desiredChannels.has(packet.channel))
+                this.activeChannels.add(packet.channel);
+            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.presenceSnapshots.delete(packet.channel);
+            for (const handle of this.channels.get(packet.channel) ?? [])
+                handle.resetPresence();
+            const error = new BridgeError('subscription.revoked', `Access to ${packet.channel} was revoked.`);
+            for (const handle of this.channels.get(packet.channel) ?? [])
+                handle.receiveError(error);
+            this.report(error);
         });
         this.socket.on('bridge.command.result', (packet) => {
             const item = this.pending.get(packet.command_id);
@@ -96,18 +141,43 @@ export class SocketBridge {
             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));
+                item.reject(new BridgeError(packet.result.error?.code ?? 'command.failed', packet.result.error?.message ?? 'Command failed', packet.command_id, packet.result.error?.details));
         });
     }
     connect() {
         if (this.destroyed)
             throw new BridgeError('client.destroyed', 'Create a new client after destroy().');
+        this.managedConnection = false;
+        return this.beginConnection();
+    }
+    beginConnection() {
         this.wantConnected = true;
         this.terminal = false;
         this.socket.connect();
         return this;
     }
+    /** Reference-count a framework consumer without closing a manually connected socket. */
+    retainConnection() {
+        if (this.destroyed)
+            throw new BridgeError('client.destroyed', 'Create a new client after destroy().');
+        this.connectionReferences++;
+        if (!this.wantConnected) {
+            this.managedConnection = true;
+            this.beginConnection();
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.connectionReferences--;
+            if (this.connectionReferences === 0 && this.managedConnection)
+                this.disconnect();
+        };
+    }
     disconnect() {
+        this.connectionGeneration++;
+        this.managedConnection = false;
         this.wantConnected = false;
         if (this.reconnectTimer)
             clearTimeout(this.reconnectTimer);
@@ -116,6 +186,8 @@ export class SocketBridge {
         for (const retry of this.channelRetries.values())
             clearTimeout(retry.timer);
         this.channelRetries.clear();
+        this.activeChannels.clear();
+        this.channelJoins.clear();
         this.socket.disconnect();
     }
     destroy() {
@@ -128,24 +200,64 @@ export class SocketBridge {
         }
         this.pending.clear();
         this.desiredChannels.clear();
+        this.manualChannels.clear();
+        this.presenceSnapshots.clear();
+        for (const handles of [...this.channels.values()])
+            for (const handle of [...handles])
+                handle.dispose();
+        this.channels.clear();
     }
     async join(channel) {
+        if (this.destroyed)
+            throw new BridgeError('client.destroyed', 'Create a new client after destroy().');
+        this.manualChannels.add(channel);
         this.desiredChannels.add(channel);
-        if (this.socket.connected) {
-            try {
-                await this.ack('room:join', { channel });
-            }
-            catch (error) {
-                this.failedSubscription(channel, error);
-                throw error;
-            }
-        }
+        if (this.socket.connected)
+            await this.subscribeChannel(channel);
     }
     async leave(channel) {
+        this.manualChannels.delete(channel);
+        if (this.channels.get(channel)?.size)
+            return;
         this.forgetChannel(channel);
         if (this.socket.connected)
             await this.ack('room:leave', { channel });
     }
+    /** Create an independently disposable subscription to an exact canonical channel. */
+    channel(name) {
+        if (this.destroyed)
+            throw new BridgeError('client.destroyed', 'Create a new client after destroy().');
+        if (!/^[a-zA-Z0-9_.:-]{1,200}$/.test(name) || name.startsWith('__'))
+            throw new BridgeError('invalid_channel', 'Invalid or reserved channel.');
+        const handle = new BridgeChannel(this, name);
+        const handles = this.channels.get(name) ?? new Set();
+        handles.add(handle);
+        this.channels.set(name, handles);
+        this.desiredChannels.add(name);
+        const cached = this.presenceSnapshots.get(name);
+        if (cached)
+            handle.receivePresence(cached);
+        handle.ready = this.socket.connected ? this.subscribeChannel(name) : Promise.resolve();
+        // Listeners can use .error(); merely constructing a channel must not create an unhandled rejection.
+        void handle.ready.catch(() => undefined);
+        return handle;
+    }
+    private(name) { return this.channel(name.startsWith('private-') ? name : `private-${name}`); }
+    presence(name) { return this.channel(name.startsWith('presence-') ? name : `presence-${name}`); }
+    /** Internal lifetime hook used by channel handles. */
+    releaseChannel(handle) {
+        const handles = this.channels.get(handle.name);
+        handles?.delete(handle);
+        if (handles?.size)
+            return;
+        this.channels.delete(handle.name);
+        if (this.manualChannels.has(handle.name))
+            return;
+        this.forgetChannel(handle.name);
+        this.presenceSnapshots.delete(handle.name);
+        if (!this.destroyed && this.socket.connected)
+            void this.ack('room:leave', { channel: handle.name }).catch(error => this.report(error));
+    }
     /** Dedupe is bounded and per listener, so multiple consumers all receive a new event. */
     on(event, listener) {
         const seen = new Set();
@@ -180,7 +292,7 @@ export class SocketBridge {
                     return;
                 clearTimeout(item.timer);
                 this.pending.delete(id);
-                reject(error instanceof BridgeError ? new BridgeError(error.code, error.message, id) : error);
+                reject(error instanceof BridgeError ? new BridgeError(error.code, error.message, id, error.details) : error);
             });
         });
     }
@@ -216,17 +328,47 @@ export class SocketBridge {
             throw new BridgeError('auth.invalid_response', 'Ticket response did not include a token.');
         return token;
     }
+    subscribeChannel(channel, attempts = 0) {
+        if (!this.socket.connected || this.destroyed || this.terminal)
+            return Promise.resolve();
+        const pending = this.channelJoins.get(channel);
+        if (pending)
+            return pending;
+        if (this.activeChannels.has(channel))
+            return Promise.resolve();
+        let request;
+        request = this.ack('room:join', { channel }).then(() => {
+            if (this.channelJoins.get(channel) === request && this.desiredChannels.has(channel))
+                this.activeChannels.add(channel);
+        }).catch(error => {
+            // A leave/rejoin or newer connection supersedes the old request and its eventual error.
+            if (this.channelJoins.get(channel) === request) {
+                this.failedSubscription(channel, error, attempts);
+                for (const handle of this.channels.get(channel) ?? [])
+                    handle.receiveError(error);
+                this.report(error);
+            }
+            throw error;
+        }).finally(() => { if (this.channelJoins.get(channel) === request)
+            this.channelJoins.delete(channel); });
+        this.channelJoins.set(channel, request);
+        return request;
+    }
     async restoreSubscriptions() {
-        for (const channel of this.desiredChannels) {
+        const generation = this.connectionGeneration;
+        const current = () => generation === this.connectionGeneration && this.socket.connected && !this.destroyed && !this.terminal;
+        for (const channel of [...this.desiredChannels]) {
+            if (!current())
+                return;
+            if (!this.desiredChannels.has(channel))
+                continue;
             try {
-                await this.ack('room:join', { channel });
-            }
-            catch (error) {
-                this.failedSubscription(channel, error);
-                this.report(error);
+                await this.subscribeChannel(channel);
             }
+            catch { /* subscribeChannel retains transient intent and reports the error. */ }
         }
-        await this.resync();
+        if (current())
+            await this.resync();
     }
     async resync() {
         try {
@@ -240,6 +382,7 @@ export class SocketBridge {
         return error instanceof BridgeError && ['unauthenticated', 'session_revoked', 'auth.revoked', 'forbidden', 'invalid_channel', 'subscription_cancelled'].includes(error.code);
     }
     stopForRevocation() {
+        this.connectionGeneration++;
         this.terminal = true;
         if (this.reconnectTimer)
             clearTimeout(this.reconnectTimer);
@@ -297,6 +440,10 @@ export class SocketBridge {
     }
     forgetChannel(channel) {
         this.desiredChannels.delete(channel);
+        this.manualChannels.delete(channel);
+        this.presenceSnapshots.delete(channel);
+        this.activeChannels.delete(channel);
+        this.channelJoins.delete(channel);
         const retry = this.channelRetries.get(channel);
         if (retry)
             clearTimeout(retry.timer);
@@ -313,10 +460,7 @@ export class SocketBridge {
             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);
-            });
+            void this.subscribeChannel(channel, attempts + 1).then(() => this.resync(), () => undefined);
         }, this.backoff(attempts));
         this.channelRetries.set(channel, { attempts, timer });
     }
@@ -326,7 +470,7 @@ export class SocketBridge {
                 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.'));
+                    return reject(new BridgeError(response?.error?.code ?? 'socket.rejected', response?.error?.message ?? 'Gateway rejected the request.', undefined, response?.error?.details));
                 resolve(response);
             });
         });

package/dist/react.d.ts

@@ -0,0 +1,10 @@
+import type { EventMetadata, JsonObject, PresenceMember, SocketBridge } from './index.js';
+/** Share one application-created bridge across components; the last managed consumer disconnects. */
+export declare function useSocketBridge(bridge: SocketBridge): boolean;
+/** Exact canonical channel name, e.g. private-orders.42. Each mounted hook owns one reference. */
+export declare function useChannelEvent<T = JsonObject>(bridge: SocketBridge, channel: string, event: string, listener: (payload: T, metadata?: EventMetadata) => void, onError?: (error: Error) => void): void;
+/** Name without presence- is accepted. Members are authoritative snapshots, not attendance history. */
+export declare function usePresence(bridge: SocketBridge, channel: string): {
+    members: PresenceMember[];
+    error: Error | null;
+};

package/dist/react.js

@@ -0,0 +1,34 @@
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+/** Share one application-created bridge across components; the last managed consumer disconnects. */
+export function useSocketBridge(bridge) {
+    useEffect(() => bridge.retainConnection(), [bridge]);
+    const subscribe = useCallback((notify) => {
+        bridge.socket.on('connect', notify);
+        bridge.socket.on('disconnect', notify);
+        return () => { bridge.socket.off('connect', notify); bridge.socket.off('disconnect', notify); };
+    }, [bridge]);
+    return useSyncExternalStore(subscribe, () => bridge.socket.connected, () => false);
+}
+/** Exact canonical channel name, e.g. private-orders.42. Each mounted hook owns one reference. */
+export function useChannelEvent(bridge, channel, event, listener, onError) {
+    const latest = useRef({ listener, onError });
+    useEffect(() => { latest.current = { listener, onError }; }, [listener, onError]);
+    useEffect(() => {
+        const handle = bridge.channel(channel).listen(event, (payload, metadata) => latest.current.listener(payload, metadata))
+            .error(error => latest.current.onError?.(error));
+        return () => handle.dispose();
+    }, [bridge, channel, event]);
+}
+/** Name without presence- is accepted. Members are authoritative snapshots, not attendance history. */
+export function usePresence(bridge, channel) {
+    const [state, setState] = useState({ bridge, channel, members: [], error: null });
+    useEffect(() => {
+        const handle = bridge.presence(channel)
+            .here(members => setState({ bridge, channel, members, error: null }))
+            .error(error => setState(current => ({ bridge, channel, members: current.bridge === bridge && current.channel === channel ? current.members : [], error })));
+        const reset = () => setState({ bridge, channel, members: [], error: null });
+        bridge.socket.on('disconnect', reset);
+        return () => { bridge.socket.off('disconnect', reset); handle.dispose(); };
+    }, [bridge, channel]);
+    return state.bridge === bridge && state.channel === channel ? state : { members: [], error: null };
+}

package/dist/vue.d.ts

@@ -0,0 +1,20 @@
+import { type MaybeRefOrGetter } from 'vue';
+import type { EventMetadata, JsonObject, SocketBridge } from './index.js';
+/** No connection is opened during component SSR. Scope cleanup releases only this consumer. */
+export declare function useSocketBridge(bridge: SocketBridge): Readonly<import("vue").Ref<boolean, boolean>>;
+/** Reactive canonical name; old listeners and subscriptions are released when it changes. */
+export declare function useChannelEvent<T = JsonObject>(bridge: SocketBridge, channel: MaybeRefOrGetter<string>, event: MaybeRefOrGetter<string>, listener: (payload: T, metadata?: EventMetadata) => void, onError?: (error: Error) => void): void;
+export declare function usePresence(bridge: SocketBridge, channel: MaybeRefOrGetter<string>): {
+    members: Readonly<import("vue").Ref<readonly {
+        readonly id: string;
+        readonly info: {
+            readonly [x: string]: Readonly<unknown>;
+        };
+    }[], readonly {
+        readonly id: string;
+        readonly info: {
+            readonly [x: string]: Readonly<unknown>;
+        };
+    }[]>>;
+    error: Readonly<import("vue").Ref<Error | null, Error | null>>;
+};

package/dist/vue.js

@@ -0,0 +1,41 @@
+import { getCurrentInstance, getCurrentScope, onMounted, onScopeDispose, readonly, shallowRef, toValue, watch } from 'vue';
+function assertScope() { if (!getCurrentScope())
+    throw new Error('Socket Bridge composables require a component setup() or an active effectScope().'); }
+/** No connection is opened during component SSR. Scope cleanup releases only this consumer. */
+export function useSocketBridge(bridge) {
+    assertScope();
+    const connected = shallowRef(bridge.socket.connected);
+    const update = () => { connected.value = bridge.socket.connected; };
+    bridge.socket.on('connect', update);
+    bridge.socket.on('disconnect', update);
+    let release;
+    const connect = () => { release = bridge.retainConnection(); update(); };
+    if (getCurrentInstance())
+        onMounted(connect);
+    else
+        connect();
+    onScopeDispose(() => { bridge.socket.off('connect', update); bridge.socket.off('disconnect', update); release?.(); });
+    return readonly(connected);
+}
+/** Reactive canonical name; old listeners and subscriptions are released when it changes. */
+export function useChannelEvent(bridge, channel, event, listener, onError) {
+    assertScope();
+    watch(() => [toValue(channel), toValue(event)], ([name, eventName], _previous, onCleanup) => {
+        const handle = bridge.channel(name).listen(eventName, listener).error(error => onError?.(error));
+        onCleanup(() => handle.dispose());
+    }, { immediate: true, flush: 'sync' });
+}
+export function usePresence(bridge, channel) {
+    assertScope();
+    const members = shallowRef([]);
+    const error = shallowRef(null);
+    const reset = () => { members.value = []; error.value = null; };
+    bridge.socket.on('disconnect', reset);
+    watch(() => toValue(channel), (name, _previous, onCleanup) => {
+        reset();
+        const handle = bridge.presence(name).here(value => { members.value = value; error.value = null; }).error(value => { error.value = value; });
+        onCleanup(() => handle.dispose());
+    }, { immediate: true, flush: 'sync' });
+    onScopeDispose(() => bridge.socket.off('disconnect', reset));
+    return { members: readonly(members), error: readonly(error) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belysh/socket-bridge-client",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Framework-neutral Socket.IO client for Laravel Socket Bridge",
   "type": "module",
   "license": "MIT",
@@ -10,6 +10,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js"
     }
   },
   "files": [
@@ -26,7 +34,13 @@
     "socket.io-client": "^4.8.1"
   },
   "devDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^27.0.0",
+    "vue": "^3.5.0"
   },
   "engines": {
     "node": ">=20"
@@ -46,5 +60,17 @@
     "socket.io",
     "redis",
     "realtime"
-  ]
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  }
 }