@gwakko/shared-websocket 0.10.2 → 0.11.0

package/dist/vue.js

@@ -1,6 +1,6 @@
 import {
   SharedWebSocket
-} from "./chunk-PKZXBX5I.js";
+} from "./chunk-VUTUECT2.js";
 
 // src/adapters/vue.ts
 import {
@@ -32,6 +32,19 @@ function useSharedWebSocket() {
   }
   return socket;
 }
+function useAuth() {
+  const socket = useSharedWebSocket();
+  const isAuthenticated = ref(socket.isAuthenticated);
+  const unsub = socket.onAuthChange((authenticated) => {
+    isAuthenticated.value = authenticated;
+  });
+  onUnmounted(unsub);
+  return {
+    isAuthenticated: readonly(isAuthenticated),
+    authenticate: (token) => socket.authenticate(token),
+    deauthenticate: () => socket.deauthenticate()
+  };
+}
 function useSocketEvent(event, callback) {
   const socket = useSharedWebSocket();
   const value = ref(void 0);
@@ -90,14 +103,17 @@ function useSocketStatus() {
   const socket = useSharedWebSocket();
   const connected = ref(socket.connected);
   const tabRole = ref(socket.tabRole);
+  const isAuthenticated = ref(socket.isAuthenticated);
   const timer = setInterval(() => {
     connected.value = socket.connected;
     tabRole.value = socket.tabRole;
+    isAuthenticated.value = socket.isAuthenticated;
   }, 1e3);
   onUnmounted(() => clearInterval(timer));
   return {
     connected: readonly(connected),
-    tabRole: readonly(tabRole)
+    tabRole: readonly(tabRole),
+    isAuthenticated: readonly(isAuthenticated)
   };
 }
 function useSocketLifecycle(handlers) {
@@ -111,17 +127,18 @@ function useSocketLifecycle(handlers) {
   if (handlers.onActive) unsubs.push(socket.onActive(handlers.onActive));
   if (handlers.onInactive) unsubs.push(socket.onInactive(handlers.onInactive));
   if (handlers.onVisibilityChange) unsubs.push(socket.onVisibilityChange(handlers.onVisibilityChange));
+  if (handlers.onAuthChange) unsubs.push(socket.onAuthChange(handlers.onAuthChange));
   onUnmounted(() => unsubs.forEach((u) => u()));
 }
-function useChannel(name) {
+function useChannel(name, options) {
   const socket = useSharedWebSocket();
-  const channel = socket.channel(name);
+  const channel = socket.channel(name, options);
   onUnmounted(() => channel.leave());
   return channel;
 }
-function useTopics(topics) {
+function useTopics(topics, options) {
   const socket = useSharedWebSocket();
-  topics.forEach((t) => socket.subscribe(t));
+  topics.forEach((t) => socket.subscribe(t, options));
   onUnmounted(() => {
     topics.forEach((t) => socket.unsubscribe(t));
   });
@@ -134,6 +151,7 @@ function usePush(event, config) {
 export {
   SharedWebSocketKey,
   createSharedWebSocketPlugin,
+  useAuth,
   useChannel,
   usePush,
   useSharedWebSocket,

package/dist/vue.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/adapters/vue.ts"],"sourcesContent":["import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole, SocketLifecycleHandlers } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {\n *   auth: () => localStorage.getItem('token')!,\n *   useWorker: true,\n * }));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event.\n * - Without callback: returns reactive ref with latest value.\n * - With callback: calls your handler on each event.\n *\n * @example\n * // Reactive state\n * const order = useSocketEvent<Order>('order.created');\n *\n * @example\n * // Custom callback\n * useSocketEvent<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', order);\n * });\n */\nexport function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const handler = (data: unknown) => {\n    const typed = data as T;\n    if (callback) {\n      callback(typed);\n    } else {\n      value.value = typed;\n    }\n  };\n  const unsub = socket.on(event, handler);\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events.\n * - Without callback: returns reactive array.\n * - With callback: calls your handler — manage your own state.\n *\n * @example\n * // Default accumulation\n * const messages = useSocketStream<ChatMessage>('chat.message');\n *\n * @example\n * // Custom — keep last 50\n * const messages = ref<ChatMessage[]>([]);\n * useSocketStream<ChatMessage>('chat.message', (msg) => {\n *   messages.value = [msg, ...messages.value].slice(0, 50);\n * });\n *\n * @example\n * // Custom — filter by type\n * const errors = ref<LogEntry[]>([]);\n * useSocketStream<LogEntry>('log.entry', (entry) => {\n *   if (entry.level === 'error') errors.value = [...errors.value, entry];\n * });\n */\nexport function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const handler = (data: unknown) => {\n    const typed = data as T;\n    if (callback) {\n      callback(typed);\n    } else {\n      items.value = [...items.value, typed];\n    }\n  };\n  const unsub = socket.on(event, handler);\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * - Without callback: reactive ref synced across tabs.\n * - With callback: called when any tab updates this key — side effects.\n *\n * @example\n * // Reactive two-way sync\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n *\n * @example\n * // With side effect callback\n * const cart = useSocketSync<Cart>('cart', { items: [] }, (cart) => {\n *   document.title = `Cart (${cart.items.length})`;\n *   analytics.track('cart_updated');\n * });\n */\nexport function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n    callback?.(v);\n  });\n\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Fire-and-forget event handler — no state, no ref.\n *\n * @example\n * useSocketCallback<Notification>('notification', (n) => {\n *   showToast(n.title);\n * });\n */\nexport function useSocketCallback<T>(event: string, callback: (data: T) => void): void {\n  const socket = useSharedWebSocket();\n\n  const unsub = socket.on(event, (data: unknown) => {\n    callback(data as T);\n  });\n\n  onUnmounted(unsub);\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n\n  const timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n  };\n}\n\n/**\n * Lifecycle hooks — react to connection state changes.\n *\n * @example\n * useSocketLifecycle({\n *   onConnect: () => console.log('Connected!'),\n *   onDisconnect: () => showOfflineBanner(),\n *   onReconnecting: () => showSpinner(),\n *   onLeaderChange: (isLeader) => console.log('Leader:', isLeader),\n *   onError: (err) => reportError(err),\n * });\n */\nexport function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {\n  const socket = useSharedWebSocket();\n  const unsubs: (() => void)[] = [];\n\n  if (handlers.onConnect) unsubs.push(socket.onConnect(handlers.onConnect));\n  if (handlers.onDisconnect) unsubs.push(socket.onDisconnect(handlers.onDisconnect));\n  if (handlers.onReconnecting) unsubs.push(socket.onReconnecting(handlers.onReconnecting));\n  if (handlers.onLeaderChange) unsubs.push(socket.onLeaderChange(handlers.onLeaderChange));\n  if (handlers.onError) unsubs.push(socket.onError(handlers.onError));\n  if (handlers.onActive) unsubs.push(socket.onActive(handlers.onActive));\n  if (handlers.onInactive) unsubs.push(socket.onInactive(handlers.onInactive));\n  if (handlers.onVisibilityChange) unsubs.push(socket.onVisibilityChange(handlers.onVisibilityChange));\n\n  onUnmounted(() => unsubs.forEach((u) => u()));\n}\n\n/**\n * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.\n *\n * @example\n * const chat = useChannel('chat:room_123');\n * // Listen via useSocketEvent('chat:room_123:message')\n * // Send via chat.send('message', { text: 'Hello' })\n */\nexport function useChannel(name: string) {\n  const socket = useSharedWebSocket();\n  const channel = socket.channel(name);\n\n  onUnmounted(() => channel.leave());\n\n  return channel;\n}\n\n/**\n * Subscribe to server-side topics. Auto-unsubscribes on unmount.\n *\n * @example\n * useTopics(['notifications:orders', 'notifications:payments']);\n */\nexport function useTopics(topics: string[]): void {\n  const socket = useSharedWebSocket();\n\n  topics.forEach((t) => socket.subscribe(t));\n\n  onUnmounted(() => {\n    topics.forEach((t) => socket.unsubscribe(t));\n  });\n}\n\n/**\n * Enable browser push notifications for an event. Auto-cleanup on unmount.\n *\n * @example\n * usePush('notification', {\n *   title: (n) => n.title,\n *   body: (n) => n.body,\n *   icon: '/icon.png',\n * });\n */\nexport function usePush<T = unknown>(\n  event: string,\n  config: {\n    title: string | ((data: T) => string);\n    body?: string | ((data: T) => string);\n    icon?: string;\n    tag?: string | ((data: T) => string);\n    leaderOnly?: boolean;\n    onlyWhenHidden?: boolean;\n    onClick?: (data: T) => void;\n  },\n): void {\n  const socket = useSharedWebSocket();\n  const unsub = socket.push<T>(event, config);\n\n  onUnmounted(unsub);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/adapters/vue.ts"],"sourcesContent":["import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole, SocketLifecycleHandlers } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {\n *   auth: () => localStorage.getItem('token')!,\n *   useWorker: true,\n * }));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n/**\n * Reactive auth state with authenticate/deauthenticate actions.\n * Syncs across all tabs.\n *\n * @example\n * const { isAuthenticated, authenticate, deauthenticate } = useAuth();\n *\n * async function login(email: string, password: string) {\n *   const { token } = await api.login(email, password);\n *   authenticate(token);\n * }\n *\n * @example\n * // In template: <button v-if=\"isAuthenticated\" @click=\"deauthenticate\">Logout</button>\n */\nexport function useAuth(): {\n  isAuthenticated: Ref<boolean>;\n  authenticate: (token: string) => void;\n  deauthenticate: () => void;\n} {\n  const socket = useSharedWebSocket();\n  const isAuthenticated = ref(socket.isAuthenticated);\n\n  const unsub = socket.onAuthChange((authenticated: boolean) => {\n    isAuthenticated.value = authenticated;\n  });\n\n  onUnmounted(unsub);\n\n  return {\n    isAuthenticated: readonly(isAuthenticated) as Ref<boolean>,\n    authenticate: (token: string) => socket.authenticate(token),\n    deauthenticate: () => socket.deauthenticate(),\n  };\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event.\n * - Without callback: returns reactive ref with latest value.\n * - With callback: calls your handler on each event.\n *\n * @example\n * // Reactive state\n * const order = useSocketEvent<Order>('order.created');\n *\n * @example\n * // Custom callback\n * useSocketEvent<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', order);\n * });\n */\nexport function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const handler = (data: unknown) => {\n    const typed = data as T;\n    if (callback) {\n      callback(typed);\n    } else {\n      value.value = typed;\n    }\n  };\n  const unsub = socket.on(event, handler);\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events.\n * - Without callback: returns reactive array.\n * - With callback: calls your handler — manage your own state.\n *\n * @example\n * // Default accumulation\n * const messages = useSocketStream<ChatMessage>('chat.message');\n *\n * @example\n * // Custom — keep last 50\n * const messages = ref<ChatMessage[]>([]);\n * useSocketStream<ChatMessage>('chat.message', (msg) => {\n *   messages.value = [msg, ...messages.value].slice(0, 50);\n * });\n *\n * @example\n * // Custom — filter by type\n * const errors = ref<LogEntry[]>([]);\n * useSocketStream<LogEntry>('log.entry', (entry) => {\n *   if (entry.level === 'error') errors.value = [...errors.value, entry];\n * });\n */\nexport function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const handler = (data: unknown) => {\n    const typed = data as T;\n    if (callback) {\n      callback(typed);\n    } else {\n      items.value = [...items.value, typed];\n    }\n  };\n  const unsub = socket.on(event, handler);\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * - Without callback: reactive ref synced across tabs.\n * - With callback: called when any tab updates this key — side effects.\n *\n * @example\n * // Reactive two-way sync\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n *\n * @example\n * // With side effect callback\n * const cart = useSocketSync<Cart>('cart', { items: [] }, (cart) => {\n *   document.title = `Cart (${cart.items.length})`;\n *   analytics.track('cart_updated');\n * });\n */\nexport function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n    callback?.(v);\n  });\n\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Fire-and-forget event handler — no state, no ref.\n *\n * @example\n * useSocketCallback<Notification>('notification', (n) => {\n *   showToast(n.title);\n * });\n */\nexport function useSocketCallback<T>(event: string, callback: (data: T) => void): void {\n  const socket = useSharedWebSocket();\n\n  const unsub = socket.on(event, (data: unknown) => {\n    callback(data as T);\n  });\n\n  onUnmounted(unsub);\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n  isAuthenticated: Ref<boolean>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n  const isAuthenticated = ref(socket.isAuthenticated);\n\n  const timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n    isAuthenticated.value = socket.isAuthenticated;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n    isAuthenticated: readonly(isAuthenticated) as Ref<boolean>,\n  };\n}\n\n/**\n * Lifecycle hooks — react to connection state changes.\n *\n * @example\n * useSocketLifecycle({\n *   onConnect: () => console.log('Connected!'),\n *   onDisconnect: () => showOfflineBanner(),\n *   onReconnecting: () => showSpinner(),\n *   onLeaderChange: (isLeader) => console.log('Leader:', isLeader),\n *   onError: (err) => reportError(err),\n * });\n */\nexport function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {\n  const socket = useSharedWebSocket();\n  const unsubs: (() => void)[] = [];\n\n  if (handlers.onConnect) unsubs.push(socket.onConnect(handlers.onConnect));\n  if (handlers.onDisconnect) unsubs.push(socket.onDisconnect(handlers.onDisconnect));\n  if (handlers.onReconnecting) unsubs.push(socket.onReconnecting(handlers.onReconnecting));\n  if (handlers.onLeaderChange) unsubs.push(socket.onLeaderChange(handlers.onLeaderChange));\n  if (handlers.onError) unsubs.push(socket.onError(handlers.onError));\n  if (handlers.onActive) unsubs.push(socket.onActive(handlers.onActive));\n  if (handlers.onInactive) unsubs.push(socket.onInactive(handlers.onInactive));\n  if (handlers.onVisibilityChange) unsubs.push(socket.onVisibilityChange(handlers.onVisibilityChange));\n  if (handlers.onAuthChange) unsubs.push(socket.onAuthChange(handlers.onAuthChange));\n\n  onUnmounted(() => unsubs.forEach((u) => u()));\n}\n\n/**\n * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.\n *\n * @example\n * const chat = useChannel('chat:room_123');\n * // Listen via useSocketEvent('chat:room_123:message')\n * // Send via chat.send('message', { text: 'Hello' })\n */\nexport function useChannel(name: string, options?: { auth?: boolean }) {\n  const socket = useSharedWebSocket();\n  const channel = socket.channel(name, options);\n\n  onUnmounted(() => channel.leave());\n\n  return channel;\n}\n\n/**\n * Subscribe to server-side topics. Auto-unsubscribes on unmount.\n *\n * @example\n * useTopics(['notifications:orders', 'notifications:payments']);\n */\nexport function useTopics(topics: string[], options?: { auth?: boolean }): void {\n  const socket = useSharedWebSocket();\n\n  topics.forEach((t) => socket.subscribe(t, options));\n\n  onUnmounted(() => {\n    topics.forEach((t) => socket.unsubscribe(t));\n  });\n}\n\n/**\n * Enable browser push notifications for an event. Auto-cleanup on unmount.\n *\n * @example\n * usePush('notification', {\n *   title: (n) => n.title,\n *   body: (n) => n.body,\n *   icon: '/icon.png',\n * });\n */\nexport function usePush<T = unknown>(\n  event: string,\n  config: {\n    title: string | ((data: T) => string);\n    body?: string | ((data: T) => string);\n    icon?: string;\n    tag?: string | ((data: T) => string);\n    leaderOnly?: boolean;\n    onlyWhenHidden?: boolean;\n    onClick?: (data: T) => void;\n  },\n): void {\n  const socket = useSharedWebSocket();\n  const unsub = socket.push<T>(event, config);\n\n  onUnmounted(unsub);\n}\n"],"mappings":";;;;;AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAMA,IAAM,qBAAoD,uBAAO,iBAAiB;AAYlF,SAAS,4BAA4B,KAAa,SAAkC;AACzF,SAAO;AAAA,IACL,QAAQ,KAAU;AAChB,YAAM,SAAS,IAAI,gBAAgB,KAAK,OAAO;AAC/C,aAAO,QAAQ;AACf,UAAI,QAAQ,oBAAoB,MAAM;AAEtC,YAAM,kBAAkB,IAAI,QAAQ,KAAK,GAAG;AAC5C,UAAI,UAAU,MAAM;AAClB,eAAO,OAAO,OAAO,EAAE;AACvB,wBAAgB;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACF;AASO,SAAS,qBAAsC;AACpD,QAAM,SAAS,OAAO,kBAAkB;AACxC,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,+EAA+E;AAAA,EACjG;AACA,SAAO;AACT;AAiBO,SAAS,UAId;AACA,QAAM,SAAS,mBAAmB;AAClC,QAAM,kBAAkB,IAAI,OAAO,eAAe;AAElD,QAAM,QAAQ,OAAO,aAAa,CAAC,kBAA2B;AAC5D,oBAAgB,QAAQ;AAAA,EAC1B,CAAC;AAED,cAAY,KAAK;AAEjB,SAAO;AAAA,IACL,iBAAiB,SAAS,eAAe;AAAA,IACzC,cAAc,CAAC,UAAkB,OAAO,aAAa,KAAK;AAAA,IAC1D,gBAAgB,MAAM,OAAO,eAAe;AAAA,EAC9C;AACF;AAoBO,SAAS,eAAkB,OAAe,UAAkD;AACjG,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAmB,MAAS;AAE1C,QAAM,UAAU,CAAC,SAAkB;AACjC,UAAM,QAAQ;AACd,QAAI,UAAU;AACZ,eAAS,KAAK;AAAA,IAChB,OAAO;AACL,YAAM,QAAQ;AAAA,IAChB;AAAA,EACF;AACA,QAAM,QAAQ,OAAO,GAAG,OAAO,OAAO;AAEtC,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AAyBO,SAAS,gBAAmB,OAAe,UAAwC;AACxF,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAS,CAAC,CAAC;AAEzB,QAAM,UAAU,CAAC,SAAkB;AACjC,UAAM,QAAQ;AACd,QAAI,UAAU;AACZ,eAAS,KAAK;AAAA,IAChB,OAAO;AACL,YAAM,QAAQ,CAAC,GAAG,MAAM,OAAO,KAAK;AAAA,IACtC;AAAA,EACF;AACA,QAAM,QAAQ,OAAO,GAAG,OAAO,OAAO;AAEtC,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AAmBO,SAAS,cAAiB,KAAa,cAAiB,UAAuC;AACpG,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAO,OAAO,QAAW,GAAG,KAAK,YAAY;AAE3D,QAAM,QAAQ,OAAO,OAAU,KAAK,CAAC,MAAM;AACzC,UAAM,QAAQ;AACd,eAAW,CAAC;AAAA,EACd,CAAC;AAED;AAAA,IACE;AAAA,IACA,CAAC,WAAW;AACV,aAAO,KAAK,KAAK,MAAM;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,KAAK;AAAA,EACf;AAEA,cAAY,KAAK;AACjB,SAAO;AACT;AAUO,SAAS,kBAAqB,OAAe,UAAmC;AACrF,QAAM,SAAS,mBAAmB;AAElC,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAkB;AAChD,aAAS,IAAS;AAAA,EACpB,CAAC;AAED,cAAY,KAAK;AACnB;AAQO,SAAS,kBAId;AACA,QAAM,SAAS,mBAAmB;AAClC,QAAM,YAAY,IAAI,OAAO,SAAS;AACtC,QAAM,UAAU,IAAa,OAAO,OAAO;AAC3C,QAAM,kBAAkB,IAAI,OAAO,eAAe;AAElD,QAAM,QAAQ,YAAY,MAAM;AAC9B,cAAU,QAAQ,OAAO;AACzB,YAAQ,QAAQ,OAAO;AACvB,oBAAgB,QAAQ,OAAO;AAAA,EACjC,GAAG,GAAI;AAEP,cAAY,MAAM,cAAc,KAAK,CAAC;AAEtC,SAAO;AAAA,IACL,WAAW,SAAS,SAAS;AAAA,IAC7B,SAAS,SAAS,OAAO;AAAA,IACzB,iBAAiB,SAAS,eAAe;AAAA,EAC3C;AACF;AAcO,SAAS,mBAAmB,UAAyC;AAC1E,QAAM,SAAS,mBAAmB;AAClC,QAAM,SAAyB,CAAC;AAEhC,MAAI,SAAS,UAAW,QAAO,KAAK,OAAO,UAAU,SAAS,SAAS,CAAC;AACxE,MAAI,SAAS,aAAc,QAAO,KAAK,OAAO,aAAa,SAAS,YAAY,CAAC;AACjF,MAAI,SAAS,eAAgB,QAAO,KAAK,OAAO,eAAe,SAAS,cAAc,CAAC;AACvF,MAAI,SAAS,eAAgB,QAAO,KAAK,OAAO,eAAe,SAAS,cAAc,CAAC;AACvF,MAAI,SAAS,QAAS,QAAO,KAAK,OAAO,QAAQ,SAAS,OAAO,CAAC;AAClE,MAAI,SAAS,SAAU,QAAO,KAAK,OAAO,SAAS,SAAS,QAAQ,CAAC;AACrE,MAAI,SAAS,WAAY,QAAO,KAAK,OAAO,WAAW,SAAS,UAAU,CAAC;AAC3E,MAAI,SAAS,mBAAoB,QAAO,KAAK,OAAO,mBAAmB,SAAS,kBAAkB,CAAC;AACnG,MAAI,SAAS,aAAc,QAAO,KAAK,OAAO,aAAa,SAAS,YAAY,CAAC;AAEjF,cAAY,MAAM,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9C;AAUO,SAAS,WAAW,MAAc,SAA8B;AACrE,QAAM,SAAS,mBAAmB;AAClC,QAAM,UAAU,OAAO,QAAQ,MAAM,OAAO;AAE5C,cAAY,MAAM,QAAQ,MAAM,CAAC;AAEjC,SAAO;AACT;AAQO,SAAS,UAAU,QAAkB,SAAoC;AAC9E,QAAM,SAAS,mBAAmB;AAElC,SAAO,QAAQ,CAAC,MAAM,OAAO,UAAU,GAAG,OAAO,CAAC;AAElD,cAAY,MAAM;AAChB,WAAO,QAAQ,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAAA,EAC7C,CAAC;AACH;AAYO,SAAS,QACd,OACA,QASM;AACN,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,OAAO,KAAQ,OAAO,MAAM;AAE1C,cAAY,KAAK;AACnB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gwakko/shared-websocket",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Share ONE WebSocket connection across browser tabs — leader election, BroadcastChannel sync, optional Web Worker",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/SharedWebSocket.ts

@@ -16,6 +16,9 @@ const DEFAULT_PROTOCOL: EventProtocol = {
   defaultEvent: 'message',
   topicSubscribe: '$topic:subscribe',
   topicUnsubscribe: '$topic:unsubscribe',
+  authLogin: '$auth:login',
+  authLogout: '$auth:logout',
+  authRevoked: '$auth:revoked',
 };
 
 const NOOP_LOGGER: Logger = {
@@ -65,6 +68,9 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
   private incomingMiddleware: Middleware[] = [];
   private serializers = new Map<string, (data: unknown) => unknown>();
   private deserializers = new Map<string, (data: unknown) => unknown>();
+  private _isAuthenticated = false;
+  private authChannels = new Map<string, Channel>();
+  private authTopics = new Set<string>();
 
   constructor(
     private readonly url: string,
@@ -117,7 +123,7 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
 
     // Lifecycle events from bus (all tabs receive)
     this.cleanups.push(
-      this.bus.subscribe<{ type: string; isLeader?: boolean; error?: unknown }>('ws:lifecycle', (msg) => {
+      this.bus.subscribe<{ type: string; isLeader?: boolean; error?: unknown; authenticated?: boolean }>('ws:lifecycle', (msg) => {
         switch (msg.type) {
           case 'connect':
             this.subs.emit('$lifecycle:connect', undefined);
@@ -134,6 +140,15 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
           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;
+          }
         }
       }),
     );
@@ -149,6 +164,22 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
       this.cleanups.push(() => document.removeEventListener('visibilitychange', onVisibilityChange));
     }
 
+    // Handle server-initiated auth revocation
+    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');
+      }),
+    );
+
     // Cleanup on tab close
     if (typeof window !== 'undefined') {
       const onBeforeUnload = () => this[Symbol.dispose]();
@@ -165,6 +196,11 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
     return this.coordinator.isLeader ? 'leader' : 'follower';
   }
 
+  /** Whether the user is authenticated via runtime auth. */
+  get isAuthenticated(): boolean {
+    return this._isAuthenticated;
+  }
+
   /** Whether this tab is currently visible/focused. */
   get isActive(): boolean {
     return typeof document !== 'undefined' ? !document.hidden : true;
@@ -221,6 +257,64 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
     return this.subs.on('$lifecycle:active', fn as EventHandler);
   }
 
+  // ─── 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: string): void {
+    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(): void {
+    // Leave auth channels and unsubscribe auth topics
+    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: undefined });
+    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: (authenticated: boolean) => void): Unsubscribe {
+    return this.subs.on('$lifecycle:auth', fn as EventHandler);
+  }
+
   // ─── Middleware ───────────────────────────────────────
 
   /**
@@ -372,14 +466,15 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
    * const notifications = ws.channel(`tenant:${tenantId}:notifications`);
    * notifications.on('alert', (alert) => showToast(alert));
    */
-  channel(name: string): Channel {
+  channel(name: string, options?: { auth?: boolean }): Channel {
     // Notify server about channel subscription
     this.send(this.proto.channelJoin, { channel: name });
 
     const self = this;
     const unsubs: Unsubscribe[] = [];
+    const isAuth = options?.auth ?? false;
 
-    return {
+    const ch: Channel = {
       name,
       on(event: string, handler: EventHandler): Unsubscribe {
         const unsub = self.subs.on(`${name}:${event}`, handler);
@@ -401,8 +496,15 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
         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 ──────────────────────────────────────────
@@ -416,9 +518,12 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
    * ws.subscribe('notifications:payments');
    * ws.subscribe(`user:${userId}:mentions`);
    */
-  subscribe(topic: string): void {
+  subscribe(topic: string, options?: { auth?: boolean }): void {
     this.send(this.proto.topicSubscribe, { topic });
-    this.log.debug('[SharedWS] 📌 subscribe topic', topic);
+    if (options?.auth) {
+      this.authTopics.add(topic);
+    }
+    this.log.debug('[SharedWS] subscribe topic', topic);
   }
 
   /**
@@ -427,7 +532,8 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
    */
   unsubscribe(topic: string): void {
     this.send(this.proto.topicUnsubscribe, { topic });
-    this.log.debug('[SharedWS] 📌 unsubscribe topic', topic);
+    this.authTopics.delete(topic);
+    this.log.debug('[SharedWS] unsubscribe topic', topic);
   }
 
   // ─── Push Notifications ─────────────────────────────
@@ -615,6 +721,7 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
       switch (state) {
         case 'connected':
           this.bus.broadcast('ws:lifecycle', { type: 'connect' });
+          this.reAuthenticateOnReconnect();
           break;
         case 'closed':
           this.bus.broadcast('ws:lifecycle', { type: 'disconnect' });
@@ -643,6 +750,35 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
     this.socket.connect();
   }
 
+  private reAuthenticateOnReconnect(): void {
+    if (!this._isAuthenticated || !this.socket) return;
+
+    const token = this.syncStore.get('$auth:token') as string | undefined;
+    if (token) {
+      this.socket.send({
+        [this.proto.eventField]: this.proto.authLogin,
+        [this.proto.dataField]: { token },
+      });
+      this.log.debug('[SharedWS] re-authenticated after reconnect');
+    }
+
+    // Re-join auth channels
+    for (const name of this.authChannels.keys()) {
+      this.socket.send({
+        [this.proto.eventField]: this.proto.channelJoin,
+        [this.proto.dataField]: { channel: name },
+      });
+    }
+
+    // Re-subscribe auth topics
+    for (const topic of this.authTopics) {
+      this.socket.send({
+        [this.proto.eventField]: this.proto.topicSubscribe,
+        [this.proto.dataField]: { topic },
+      });
+    }
+  }
+
   private handleLoseLeadership(): void {
     if (this.socket) {
       this.socket[Symbol.dispose]();
@@ -666,5 +802,7 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
     this.subs[Symbol.dispose]();
     this.bus[Symbol.dispose]();
     this.syncStore.clear();
+    this.authChannels.clear();
+    this.authTopics.clear();
   }
 }

package/src/adapters/react.ts

@@ -78,6 +78,55 @@ export function useSharedWebSocket(): SharedWebSocket {
   return ctx;
 }
 
+/**
+ * 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 function useAuth(): {
+  isAuthenticated: boolean;
+  authenticate: (token: string) => void;
+  deauthenticate: () => void;
+} {
+  const socket = useSharedWebSocket();
+  const [isAuthenticated, setIsAuthenticated] = useState(socket.isAuthenticated);
+
+  const onAuthChange = useEffectEvent((authenticated: boolean) => {
+    setIsAuthenticated(authenticated);
+  });
+
+  useEffect(() => {
+    return socket.onAuthChange(onAuthChange);
+  }, [socket]);
+
+  const authenticate = useEffectEvent((token: string) => {
+    socket.authenticate(token);
+  });
+
+  const deauthenticate = useEffectEvent(() => {
+    socket.deauthenticate();
+  });
+
+  return { isAuthenticated, authenticate, deauthenticate };
+}
+
 // ─── Hooks ───────────────────────────────────────────────
 
 /**
@@ -253,14 +302,17 @@ export function useSocketCallback<T>(event: string, callback: (data: T) => void)
 export function useSocketStatus(): {
   connected: boolean;
   tabRole: TabRole;
+  isAuthenticated: boolean;
 } {
   const socket = useSharedWebSocket();
   const [connected, setConnected] = useState(socket.connected);
   const [tabRole, setTabRole] = useState<TabRole>(socket.tabRole);
+  const [isAuthenticated, setIsAuthenticated] = useState(socket.isAuthenticated);
 
   const tick = useEffectEvent(() => {
     setConnected(socket.connected);
     setTabRole(socket.tabRole);
+    setIsAuthenticated(socket.isAuthenticated);
   });
 
   useEffect(() => {
@@ -268,7 +320,7 @@ export function useSocketStatus(): {
     return () => clearInterval(interval);
   }, [socket]);
 
-  return { connected, tabRole };
+  return { connected, tabRole, isAuthenticated };
 }
 
 /**
@@ -294,6 +346,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   const onActive = useEffectEvent(() => handlers.onActive?.());
   const onInactive = useEffectEvent(() => handlers.onInactive?.());
   const onVisibilityChange = useEffectEvent((isActive: boolean) => handlers.onVisibilityChange?.(isActive));
+  const onAuthChange = useEffectEvent((authenticated: boolean) => handlers.onAuthChange?.(authenticated));
 
   useEffect(() => {
     const unsubs = [
@@ -305,6 +358,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
       socket.onActive(onActive),
       socket.onInactive(onInactive),
       socket.onVisibilityChange(onVisibilityChange),
+      socket.onAuthChange(onAuthChange),
     ];
     return () => unsubs.forEach((u) => u());
   }, [socket]);
@@ -323,12 +377,12 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
  * const notifications = useChannel(`tenant:${tenantId}:notifications`);
  * useSocketCallback(`tenant:${tenantId}:notifications:alert`, showToast);
  */
-export function useChannel(name: string) {
+export function useChannel(name: string, options?: { auth?: boolean }) {
   const socket = useSharedWebSocket();
-  const channelRef = useRef(socket.channel(name));
+  const channelRef = useRef(socket.channel(name, options));
 
   useEffect(() => {
-    channelRef.current = socket.channel(name);
+    channelRef.current = socket.channel(name, options);
     return () => channelRef.current.leave();
   }, [socket, name]);
 
@@ -342,11 +396,11 @@ export function useChannel(name: string) {
  * useTopics(['notifications:orders', 'notifications:payments']);
  * useTopics([`user:${userId}:mentions`]);
  */
-export function useTopics(topics: string[]): void {
+export function useTopics(topics: string[], options?: { auth?: boolean }): void {
   const socket = useSharedWebSocket();
 
   useEffect(() => {
-    topics.forEach((t) => socket.subscribe(t));
+    topics.forEach((t) => socket.subscribe(t, options));
     return () => topics.forEach((t) => socket.unsubscribe(t));
   }, [socket, topics.join(',')]);
 }

package/src/adapters/vue.ts

@@ -56,6 +56,42 @@ export function useSharedWebSocket(): SharedWebSocket {
   return socket;
 }
 
+/**
+ * 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 function useAuth(): {
+  isAuthenticated: Ref<boolean>;
+  authenticate: (token: string) => void;
+  deauthenticate: () => void;
+} {
+  const socket = useSharedWebSocket();
+  const isAuthenticated = ref(socket.isAuthenticated);
+
+  const unsub = socket.onAuthChange((authenticated: boolean) => {
+    isAuthenticated.value = authenticated;
+  });
+
+  onUnmounted(unsub);
+
+  return {
+    isAuthenticated: readonly(isAuthenticated) as Ref<boolean>,
+    authenticate: (token: string) => socket.authenticate(token),
+    deauthenticate: () => socket.deauthenticate(),
+  };
+}
+
 // ─── Composables ─────────────────────────────────────────
 
 /**
@@ -198,14 +234,17 @@ export function useSocketCallback<T>(event: string, callback: (data: T) => void)
 export function useSocketStatus(): {
   connected: Ref<boolean>;
   tabRole: Ref<TabRole>;
+  isAuthenticated: Ref<boolean>;
 } {
   const socket = useSharedWebSocket();
   const connected = ref(socket.connected);
   const tabRole = ref<TabRole>(socket.tabRole);
+  const isAuthenticated = ref(socket.isAuthenticated);
 
   const timer = setInterval(() => {
     connected.value = socket.connected;
     tabRole.value = socket.tabRole;
+    isAuthenticated.value = socket.isAuthenticated;
   }, 1000);
 
   onUnmounted(() => clearInterval(timer));
@@ -213,6 +252,7 @@ export function useSocketStatus(): {
   return {
     connected: readonly(connected) as Ref<boolean>,
     tabRole: readonly(tabRole) as Ref<TabRole>,
+    isAuthenticated: readonly(isAuthenticated) as Ref<boolean>,
   };
 }
 
@@ -240,6 +280,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   if (handlers.onActive) unsubs.push(socket.onActive(handlers.onActive));
   if (handlers.onInactive) unsubs.push(socket.onInactive(handlers.onInactive));
   if (handlers.onVisibilityChange) unsubs.push(socket.onVisibilityChange(handlers.onVisibilityChange));
+  if (handlers.onAuthChange) unsubs.push(socket.onAuthChange(handlers.onAuthChange));
 
   onUnmounted(() => unsubs.forEach((u) => u()));
 }
@@ -252,9 +293,9 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
  * // Listen via useSocketEvent('chat:room_123:message')
  * // Send via chat.send('message', { text: 'Hello' })
  */
-export function useChannel(name: string) {
+export function useChannel(name: string, options?: { auth?: boolean }) {
   const socket = useSharedWebSocket();
-  const channel = socket.channel(name);
+  const channel = socket.channel(name, options);
 
   onUnmounted(() => channel.leave());
 
@@ -267,10 +308,10 @@ export function useChannel(name: string) {
  * @example
  * useTopics(['notifications:orders', 'notifications:payments']);
  */
-export function useTopics(topics: string[]): void {
+export function useTopics(topics: string[], options?: { auth?: boolean }): void {
   const socket = useSharedWebSocket();
 
-  topics.forEach((t) => socket.subscribe(t));
+  topics.forEach((t) => socket.subscribe(t, options));
 
   onUnmounted(() => {
     topics.forEach((t) => socket.unsubscribe(t));

package/src/types.ts

@@ -109,6 +109,12 @@ export interface EventProtocol {
   topicSubscribe: string;
   /** Event name for topic unsubscribe (default: "$topic:unsubscribe"). */
   topicUnsubscribe: string;
+  /** Event name sent when authenticating at runtime (default: "$auth:login"). */
+  authLogin: string;
+  /** Event name sent when deauthenticating (default: "$auth:logout"). */
+  authLogout: string;
+  /** Event name server sends to revoke auth (default: "$auth:revoked"). */
+  authRevoked: string;
 }
 
 /** Push notification options. */
@@ -136,6 +142,8 @@ export interface SocketLifecycleHandlers {
   onInactive?: () => void;
   /** Called on any visibility change. */
   onVisibilityChange?: (isActive: boolean) => void;
+  /** Called when auth state changes (authenticate/deauthenticate/server revocation). */
+  onAuthChange?: (authenticated: boolean) => void;
 }
 
 /** Scoped channel handle for private/topic-based subscriptions. */