@gwakko/shared-websocket 0.10.2 → 0.11.0

package/README.md

@@ -77,6 +77,11 @@ await withSocket('wss://api.example.com/ws', {
     title: (n) => n.title,                  // + browser Notification
     target: 'active',                       // active | leader | all
   });
+
+  // Runtime auth — authenticate/deauthenticate without reconnecting
+  ws.authenticate(token);                   // → sends $auth:login to server
+  const chat = ws.channel('chat:private', { auth: true }); // auto-leaves on deauth
+  ws.deauthenticate();                      // → auto-leaves auth channels/topics
 });
 ```
 
@@ -86,6 +91,7 @@ await withSocket('wss://api.example.com/ws', {
 import {
   SharedWebSocketProvider,
   useSharedWebSocket,
+  useAuth,
   useSocketEvent,
   useSocketStream,
   useSocketSync,
@@ -110,6 +116,7 @@ function App() {
 
 function Dashboard() {
   const ws = useSharedWebSocket();
+  const { isAuthenticated, authenticate, deauthenticate } = useAuth();
   const order = useSocketEvent<Order>('order.created');
   const [cart, setCart] = useSocketSync('cart', { items: [] });
   const { connected, tabRole } = useSocketStatus();
@@ -123,10 +130,11 @@ function Dashboard() {
   useSocketLifecycle({
     onConnect: () => toast.success('Connected'),
     onActive: () => refreshData(),
+    onAuthChange: (auth) => !auth && navigate('/login'),
   });
 
-  // Channel
-  const chat = useChannel(`chat:${roomId}`);
+  // Auth-aware channel — auto-leaves on deauth
+  const chat = useChannel(`chat:${roomId}`, { auth: true });
 
   // Topics
   useTopics(['notifications:orders']);
@@ -155,6 +163,7 @@ app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {
 <script setup lang="ts">
 import {
   useSharedWebSocket,
+  useAuth,
   useSocketEvent,
   useSocketSync,
   useSocketLifecycle,
@@ -164,15 +173,18 @@ import {
 } from '@gwakko/shared-websocket/vue';
 
 const ws = useSharedWebSocket();
+const { isAuthenticated, authenticate, deauthenticate } = useAuth();
 const order = useSocketEvent<Order>('order.created');
 const cart = useSocketSync('cart', { items: [] });
 
 useSocketLifecycle({
   onConnect: () => toast.success('Connected'),
   onActive: () => refreshData(),
+  onAuthChange: (auth) => { if (!auth) router.push('/login'); },
 });
 
-const chat = useChannel(`chat:${roomId}`);
+// Auth-aware channel — auto-leaves on deauth
+const chat = useChannel(`chat:${roomId}`, { auth: true });
 useTopics(['notifications:orders']);
 
 usePush('notification', {
@@ -196,10 +208,11 @@ usePush('notification', {
 | **Worker Mode** | `useWorker: true` — WebSocket off main thread |
 | **Custom Serialization** | `serialize`/`deserialize` — JSON, MessagePack, Protobuf |
 | **Per-Event Serializers** | `ws.serializer(event, fn)` — binary for specific events |
-| **Lifecycle Hooks** | onConnect, onDisconnect, onActive, onInactive, onLeaderChange |
+| **Runtime Auth** | `authenticate(token)` / `deauthenticate()` on existing connection |
+| **Lifecycle Hooks** | onConnect, onDisconnect, onActive, onInactive, onLeaderChange, onAuthChange |
 | **Debug/Logger** | `debug: true` + injectable logger (pino, Sentry) |
 | **Event Protocol** | Configurable field names (Socket.IO, Phoenix, Laravel Echo) |
-| **Auth** | `auth` callback, `authToken` string, custom `authParam` |
+| **Auth** | URL param (`auth` callback / `authToken`) + runtime `authenticate()`/`deauthenticate()` |
 | **Zero Dependencies** | Pure browser APIs |
 
 ## Processing Pipeline

package/dist/SharedWebSocket.d.ts

@@ -31,9 +31,14 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
     private incomingMiddleware;
     private serializers;
     private deserializers;
+    private _isAuthenticated;
+    private authChannels;
+    private authTopics;
     constructor(url: string, options?: SharedWebSocketOptions<TEvents>);
     get connected(): boolean;
     get tabRole(): TabRole;
+    /** Whether the user is authenticated via runtime auth. */
+    get isAuthenticated(): boolean;
     /** Whether this tab is currently visible/focused. */
     get isActive(): boolean;
     /** Start leader election and connect. */
@@ -54,6 +59,37 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
     onInactive(fn: () => void): Unsubscribe;
     /** Called on any visibility change. */
     onVisibilityChange(fn: (isActive: boolean) => void): Unsubscribe;
+    /**
+     * Authenticate on an existing connection. Sends auth event to server,
+     * syncs auth state across all tabs. Use for login after guest connection.
+     *
+     * @example
+     * const token = await loginApi(email, password);
+     * ws.authenticate(token);
+     *
+     * @example
+     * // React — via useAuth hook
+     * const { authenticate } = useAuth();
+     * authenticate(token);
+     */
+    authenticate(token: string): void;
+    /**
+     * Deauthenticate — notifies server, auto-leaves all auth-required channels
+     * and topics, syncs state across tabs. Connection stays open for public events.
+     *
+     * @example
+     * ws.deauthenticate(); // connection stays open, auth subscriptions cleaned up
+     */
+    deauthenticate(): void;
+    /**
+     * Called when auth state changes (authenticate, deauthenticate, or server revocation).
+     *
+     * @example
+     * ws.onAuthChange((authenticated) => {
+     *   if (!authenticated) router.push('/login');
+     * });
+     */
+    onAuthChange(fn: (authenticated: boolean) => void): Unsubscribe;
     /**
      * Add middleware to transform messages before send or after receive.
      * Return null from middleware to drop the message.
@@ -129,7 +165,9 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
      * const notifications = ws.channel(`tenant:${tenantId}:notifications`);
      * notifications.on('alert', (alert) => showToast(alert));
      */
-    channel(name: string): Channel;
+    channel(name: string, options?: {
+        auth?: boolean;
+    }): Channel;
     /**
      * Subscribe to a server-side topic. Server will start sending events for this topic.
      * Sends topicSubscribe event (default: "$topic:subscribe").
@@ -139,7 +177,9 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
      * ws.subscribe('notifications:payments');
      * ws.subscribe(`user:${userId}:mentions`);
      */
-    subscribe(topic: string): void;
+    subscribe(topic: string, options?: {
+        auth?: boolean;
+    }): void;
     /**
      * Unsubscribe from a server-side topic.
      * Sends topicUnsubscribe event (default: "$topic:unsubscribe").
@@ -205,6 +245,7 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
     disconnect(): void;
     private createSocket;
     private handleBecomeLeader;
+    private reAuthenticateOnReconnect;
     private handleLoseLeadership;
     [Symbol.dispose](): void;
 }

package/dist/adapters/react.d.ts

@@ -41,6 +41,33 @@ export declare function SharedWebSocketProvider({ url, options, children }: Shar
  * ws.send('chat.message', { text: 'Hello' });
  */
 export declare function useSharedWebSocket(): SharedWebSocket;
+/**
+ * Reactive auth state with authenticate/deauthenticate actions.
+ * Syncs across all tabs via BroadcastChannel.
+ *
+ * @example
+ * function LoginPage() {
+ *   const { authenticate } = useAuth();
+ *   const login = async (email: string, password: string) => {
+ *     const { token } = await api.login(email, password);
+ *     authenticate(token);
+ *   };
+ *   return <button onClick={() => login('user@test.com', 'pass')}>Login</button>;
+ * }
+ *
+ * @example
+ * function Header() {
+ *   const { isAuthenticated, deauthenticate } = useAuth();
+ *   return isAuthenticated
+ *     ? <button onClick={deauthenticate}>Logout</button>
+ *     : <Link to="/login">Login</Link>;
+ * }
+ */
+export declare function useAuth(): {
+    isAuthenticated: boolean;
+    authenticate: (token: string) => void;
+    deauthenticate: () => void;
+};
 /**
  * Subscribe to a WebSocket event.
  * - Without callback: returns the latest received value (reactive state).
@@ -136,6 +163,7 @@ export declare function useSocketCallback<T>(event: string, callback: (data: T)
 export declare function useSocketStatus(): {
     connected: boolean;
     tabRole: TabRole;
+    isAuthenticated: boolean;
 };
 /**
  * Lifecycle hooks — react to connection state changes.
@@ -163,7 +191,9 @@ export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): v
  * const notifications = useChannel(`tenant:${tenantId}:notifications`);
  * useSocketCallback(`tenant:${tenantId}:notifications:alert`, showToast);
  */
-export declare function useChannel(name: string): import("..").Channel;
+export declare function useChannel(name: string, options?: {
+    auth?: boolean;
+}): import("..").Channel;
 /**
  * Subscribe to server-side topics. Auto-unsubscribes on unmount.
  *
@@ -171,7 +201,9 @@ export declare function useChannel(name: string): import("..").Channel;
  * useTopics(['notifications:orders', 'notifications:payments']);
  * useTopics([`user:${userId}:mentions`]);
  */
-export declare function useTopics(topics: string[]): void;
+export declare function useTopics(topics: string[], options?: {
+    auth?: boolean;
+}): void;
 /**
  * Enable browser push notifications for an event. Auto-cleanup on unmount.
  *

package/dist/adapters/vue.d.ts

@@ -23,6 +23,26 @@ export declare function createSharedWebSocketPlugin(url: string, options?: Share
  * ws.send('chat.message', { text: 'Hello' });
  */
 export declare function useSharedWebSocket(): SharedWebSocket;
+/**
+ * Reactive auth state with authenticate/deauthenticate actions.
+ * Syncs across all tabs.
+ *
+ * @example
+ * const { isAuthenticated, authenticate, deauthenticate } = useAuth();
+ *
+ * async function login(email: string, password: string) {
+ *   const { token } = await api.login(email, password);
+ *   authenticate(token);
+ * }
+ *
+ * @example
+ * // In template: <button v-if="isAuthenticated" @click="deauthenticate">Logout</button>
+ */
+export declare function useAuth(): {
+    isAuthenticated: Ref<boolean>;
+    authenticate: (token: string) => void;
+    deauthenticate: () => void;
+};
 /**
  * Subscribe to a WebSocket event.
  * - Without callback: returns reactive ref with latest value.
@@ -100,6 +120,7 @@ export declare function useSocketCallback<T>(event: string, callback: (data: T)
 export declare function useSocketStatus(): {
     connected: Ref<boolean>;
     tabRole: Ref<TabRole>;
+    isAuthenticated: Ref<boolean>;
 };
 /**
  * Lifecycle hooks — react to connection state changes.
@@ -122,14 +143,18 @@ export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): v
  * // Listen via useSocketEvent('chat:room_123:message')
  * // Send via chat.send('message', { text: 'Hello' })
  */
-export declare function useChannel(name: string): import("..").Channel;
+export declare function useChannel(name: string, options?: {
+    auth?: boolean;
+}): import("..").Channel;
 /**
  * Subscribe to server-side topics. Auto-unsubscribes on unmount.
  *
  * @example
  * useTopics(['notifications:orders', 'notifications:payments']);
  */
-export declare function useTopics(topics: string[]): void;
+export declare function useTopics(topics: string[], options?: {
+    auth?: boolean;
+}): void;
 /**
  * Enable browser push notifications for an event. Auto-cleanup on unmount.
  *

package/dist/{chunk-MJXKQYRZ.cjs → chunk-LIFZOQPW.cjs}

@@ -590,7 +590,10 @@ var DEFAULT_PROTOCOL = {
   ping: { type: "ping" },
   defaultEvent: "message",
   topicSubscribe: "$topic:subscribe",
-  topicUnsubscribe: "$topic:unsubscribe"
+  topicUnsubscribe: "$topic:unsubscribe",
+  authLogin: "$auth:login",
+  authLogout: "$auth:logout",
+  authRevoked: "$auth:revoked"
 };
 var NOOP_LOGGER = {
   debug() {
@@ -603,7 +606,7 @@ var NOOP_LOGGER = {
   }
 };
 var SharedWebSocket = (_class6 = class {
-  constructor(url, options = {}) {;_class6.prototype.__init25.call(this);_class6.prototype.__init26.call(this);_class6.prototype.__init27.call(this);_class6.prototype.__init28.call(this);_class6.prototype.__init29.call(this);_class6.prototype.__init30.call(this);_class6.prototype.__init31.call(this);_class6.prototype.__init32.call(this);_class6.prototype.__init33.call(this);
+  constructor(url, options = {}) {;_class6.prototype.__init25.call(this);_class6.prototype.__init26.call(this);_class6.prototype.__init27.call(this);_class6.prototype.__init28.call(this);_class6.prototype.__init29.call(this);_class6.prototype.__init30.call(this);_class6.prototype.__init31.call(this);_class6.prototype.__init32.call(this);_class6.prototype.__init33.call(this);_class6.prototype.__init34.call(this);_class6.prototype.__init35.call(this);_class6.prototype.__init36.call(this);
     this.url = url;
     this.options = options;
     this.proto = { ...DEFAULT_PROTOCOL, ...options.events };
@@ -660,6 +663,15 @@ var SharedWebSocket = (_class6 = class {
           case "error":
             this.subs.emit("$lifecycle:error", msg.error);
             break;
+          case "auth": {
+            this._isAuthenticated = !!msg.authenticated;
+            if (!msg.authenticated) {
+              this.authChannels.clear();
+              this.authTopics.clear();
+            }
+            this.subs.emit("$lifecycle:auth", msg.authenticated);
+            break;
+          }
         }
       })
     );
@@ -672,6 +684,20 @@ var SharedWebSocket = (_class6 = class {
       document.addEventListener("visibilitychange", onVisibilityChange);
       this.cleanups.push(() => document.removeEventListener("visibilitychange", onVisibilityChange));
     }
+    this.cleanups.push(
+      this.subs.on(this.proto.authRevoked, () => {
+        if (this.coordinator.isLeader) {
+          for (const [, ch] of this.authChannels) ch.leave();
+          for (const topic of this.authTopics) this.unsubscribe(topic);
+        }
+        this.authChannels.clear();
+        this.authTopics.clear();
+        this._isAuthenticated = false;
+        this.syncStore.delete("$auth:token");
+        this.subs.emit("$lifecycle:auth", false);
+        this.log.warn("[SharedWS] auth revoked by server");
+      })
+    );
     if (typeof window !== "undefined") {
       const onBeforeUnload = () => this[Symbol.dispose]();
       window.addEventListener("beforeunload", onBeforeUnload);
@@ -694,12 +720,19 @@ var SharedWebSocket = (_class6 = class {
   __init31() {this.incomingMiddleware = []}
   __init32() {this.serializers = /* @__PURE__ */ new Map()}
   __init33() {this.deserializers = /* @__PURE__ */ new Map()}
+  __init34() {this._isAuthenticated = false}
+  __init35() {this.authChannels = /* @__PURE__ */ new Map()}
+  __init36() {this.authTopics = /* @__PURE__ */ new Set()}
   get connected() {
     return _optionalChain([this, 'access', _30 => _30.socket, 'optionalAccess', _31 => _31.state]) === "connected" || !this.coordinator.isLeader;
   }
   get tabRole() {
     return this.coordinator.isLeader ? "leader" : "follower";
   }
+  /** Whether the user is authenticated via runtime auth. */
+  get isAuthenticated() {
+    return this._isAuthenticated;
+  }
   /** Whether this tab is currently visible/focused. */
   get isActive() {
     return typeof document !== "undefined" ? !document.hidden : true;
@@ -745,6 +778,58 @@ var SharedWebSocket = (_class6 = class {
   onVisibilityChange(fn) {
     return this.subs.on("$lifecycle:active", fn);
   }
+  // ─── Authentication ──────────────────────────────────
+  /**
+   * Authenticate on an existing connection. Sends auth event to server,
+   * syncs auth state across all tabs. Use for login after guest connection.
+   *
+   * @example
+   * const token = await loginApi(email, password);
+   * ws.authenticate(token);
+   *
+   * @example
+   * // React — via useAuth hook
+   * const { authenticate } = useAuth();
+   * authenticate(token);
+   */
+  authenticate(token) {
+    this._isAuthenticated = true;
+    this.syncStore.set("$auth:token", token);
+    this.bus.broadcast("ws:sync", { key: "$auth:token", value: token });
+    this.send(this.proto.authLogin, { token });
+    this.bus.broadcast("ws:lifecycle", { type: "auth", authenticated: true });
+    this.log.info("[SharedWS] authenticated");
+  }
+  /**
+   * Deauthenticate — notifies server, auto-leaves all auth-required channels
+   * and topics, syncs state across tabs. Connection stays open for public events.
+   *
+   * @example
+   * ws.deauthenticate(); // connection stays open, auth subscriptions cleaned up
+   */
+  deauthenticate() {
+    for (const [, ch] of this.authChannels) ch.leave();
+    this.authChannels.clear();
+    for (const topic of this.authTopics) this.unsubscribe(topic);
+    this.authTopics.clear();
+    this._isAuthenticated = false;
+    this.send(this.proto.authLogout, {});
+    this.syncStore.delete("$auth:token");
+    this.bus.broadcast("ws:sync", { key: "$auth:token", value: void 0 });
+    this.bus.broadcast("ws:lifecycle", { type: "auth", authenticated: false });
+    this.log.info("[SharedWS] deauthenticated");
+  }
+  /**
+   * Called when auth state changes (authenticate, deauthenticate, or server revocation).
+   *
+   * @example
+   * ws.onAuthChange((authenticated) => {
+   *   if (!authenticated) router.push('/login');
+   * });
+   */
+  onAuthChange(fn) {
+    return this.subs.on("$lifecycle:auth", fn);
+  }
   // ─── Middleware ───────────────────────────────────────
   /**
    * Add middleware to transform messages before send or after receive.
@@ -864,11 +949,12 @@ var SharedWebSocket = (_class6 = class {
    * const notifications = ws.channel(`tenant:${tenantId}:notifications`);
    * notifications.on('alert', (alert) => showToast(alert));
    */
-  channel(name) {
+  channel(name, options) {
     this.send(this.proto.channelJoin, { channel: name });
     const self = this;
     const unsubs = [];
-    return {
+    const isAuth = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _32 => _32.auth]), () => ( false));
+    const ch = {
       name,
       on(event, handler) {
         const unsub = self.subs.on(`${name}:${event}`, handler);
@@ -890,8 +976,13 @@ var SharedWebSocket = (_class6 = class {
         self.send(self.proto.channelLeave, { channel: name });
         for (const unsub of unsubs) unsub();
         unsubs.length = 0;
+        if (isAuth) self.authChannels.delete(name);
       }
     };
+    if (isAuth) {
+      this.authChannels.set(name, ch);
+    }
+    return ch;
   }
   // ─── Topics ──────────────────────────────────────────
   /**
@@ -903,9 +994,12 @@ var SharedWebSocket = (_class6 = class {
    * ws.subscribe('notifications:payments');
    * ws.subscribe(`user:${userId}:mentions`);
    */
-  subscribe(topic) {
+  subscribe(topic, options) {
     this.send(this.proto.topicSubscribe, { topic });
-    this.log.debug("[SharedWS] \u{1F4CC} subscribe topic", topic);
+    if (_optionalChain([options, 'optionalAccess', _33 => _33.auth])) {
+      this.authTopics.add(topic);
+    }
+    this.log.debug("[SharedWS] subscribe topic", topic);
   }
   /**
    * Unsubscribe from a server-side topic.
@@ -913,7 +1007,8 @@ var SharedWebSocket = (_class6 = class {
    */
   unsubscribe(topic) {
     this.send(this.proto.topicUnsubscribe, { topic });
-    this.log.debug("[SharedWS] \u{1F4CC} unsubscribe topic", topic);
+    this.authTopics.delete(topic);
+    this.log.debug("[SharedWS] unsubscribe topic", topic);
   }
   // ─── Push Notifications ─────────────────────────────
   /**
@@ -1029,8 +1124,8 @@ var SharedWebSocket = (_class6 = class {
         }
       }
       const msg = data;
-      const event = _nullishCoalesce(_optionalChain([msg, 'optionalAccess', _32 => _32[this.proto.eventField]]), () => ( this.proto.defaultEvent));
-      let payload = _nullishCoalesce(_optionalChain([msg, 'optionalAccess', _33 => _33[this.proto.dataField]]), () => ( data));
+      const event = _nullishCoalesce(_optionalChain([msg, 'optionalAccess', _34 => _34[this.proto.eventField]]), () => ( this.proto.defaultEvent));
+      let payload = _nullishCoalesce(_optionalChain([msg, 'optionalAccess', _35 => _35[this.proto.dataField]]), () => ( data));
       const eventDeserializer = this.deserializers.get(event);
       if (eventDeserializer) {
         payload = eventDeserializer(payload);
@@ -1043,6 +1138,7 @@ var SharedWebSocket = (_class6 = class {
       switch (state) {
         case "connected":
           this.bus.broadcast("ws:lifecycle", { type: "connect" });
+          this.reAuthenticateOnReconnect();
           break;
         case "closed":
           this.bus.broadcast("ws:lifecycle", { type: "disconnect" });
@@ -1057,9 +1153,9 @@ var SharedWebSocket = (_class6 = class {
         return new Promise((resolve) => {
           const unsub = this.socket.onMessage((response) => {
             const res = response;
-            if (_optionalChain([res, 'optionalAccess', _34 => _34[this.proto.eventField]]) === req.event || _optionalChain([res, 'optionalAccess', _35 => _35.requestId])) {
+            if (_optionalChain([res, 'optionalAccess', _36 => _36[this.proto.eventField]]) === req.event || _optionalChain([res, 'optionalAccess', _37 => _37.requestId])) {
               unsub();
-              resolve(_nullishCoalesce(_optionalChain([res, 'optionalAccess', _36 => _36[this.proto.dataField]]), () => ( response)));
+              resolve(_nullishCoalesce(_optionalChain([res, 'optionalAccess', _38 => _38[this.proto.dataField]]), () => ( response)));
             }
           });
           this.socket.send({ event: req.event, data: req.data });
@@ -1068,6 +1164,29 @@ var SharedWebSocket = (_class6 = class {
     );
     this.socket.connect();
   }
+  reAuthenticateOnReconnect() {
+    if (!this._isAuthenticated || !this.socket) return;
+    const token = this.syncStore.get("$auth:token");
+    if (token) {
+      this.socket.send({
+        [this.proto.eventField]: this.proto.authLogin,
+        [this.proto.dataField]: { token }
+      });
+      this.log.debug("[SharedWS] re-authenticated after reconnect");
+    }
+    for (const name of this.authChannels.keys()) {
+      this.socket.send({
+        [this.proto.eventField]: this.proto.channelJoin,
+        [this.proto.dataField]: { channel: name }
+      });
+    }
+    for (const topic of this.authTopics) {
+      this.socket.send({
+        [this.proto.eventField]: this.proto.topicSubscribe,
+        [this.proto.dataField]: { topic }
+      });
+    }
+  }
   handleLoseLeadership() {
     if (this.socket) {
       this.socket[Symbol.dispose]();
@@ -1087,6 +1206,8 @@ var SharedWebSocket = (_class6 = class {
     this.subs[Symbol.dispose]();
     this.bus[Symbol.dispose]();
     this.syncStore.clear();
+    this.authChannels.clear();
+    this.authTopics.clear();
   }
 }, _class6);
 
@@ -1098,4 +1219,4 @@ var SharedWebSocket = (_class6 = class {
 
 
 exports.MessageBus = MessageBus; exports.TabCoordinator = TabCoordinator; exports.SharedSocket = SharedSocket; exports.WorkerSocket = WorkerSocket; exports.SubscriptionManager = SubscriptionManager; exports.SharedWebSocket = SharedWebSocket;
-//# sourceMappingURL=chunk-MJXKQYRZ.cjs.map
+//# sourceMappingURL=chunk-LIFZOQPW.cjs.map