@gwakko/shared-websocket 0.6.2 → 0.7.1

package/README.md

@@ -32,6 +32,9 @@ Share ONE WebSocket connection across multiple browser tabs. Zero dependencies.
   - [Lifecycle Hooks](#lifecycle-hooks)
   - [Private Channels](#private-channels--chat-rooms-tenant-notifications)
   - [Server-side channel handling](#server-side-channel-handling)
+- [Topics](#topics--server-side-filtered-subscriptions)
+- [Push Notifications](#push-notifications)
+- [Server-Side Implementation Guide](#server-side-implementation-guide)
 - [Exported Types](#exported-types)
 - [Browser Support](#browser-support)
 - [License](#license)
@@ -1074,6 +1077,394 @@ wss.on('connection', (ws) => {
 });
 ```
 
+## Topics — Server-Side Filtered Subscriptions
+
+Subscribe to specific topics so the server only sends relevant events:
+
+```typescript
+// Vanilla
+ws.subscribe('notifications:orders');
+ws.subscribe('notifications:payments');
+ws.subscribe(`user:${userId}:mentions`);
+
+// Later — unsubscribe
+ws.unsubscribe('notifications:orders');
+```
+
+```tsx
+// React — auto-subscribe on mount, unsubscribe on unmount
+function OrdersDashboard() {
+  useTopics(['notifications:orders', 'notifications:payments']);
+
+  const order = useSocketEvent('notifications:orders:new');
+  return order ? <div>New order #{order.id}</div> : null;
+}
+
+// Dynamic topics
+function UserMentions({ userId }: { userId: string }) {
+  useTopics([`user:${userId}:mentions`]);
+  useSocketCallback(`user:${userId}:mentions:mention`, showMentionToast);
+  return null;
+}
+```
+
+```vue
+<!-- Vue — same pattern -->
+<script setup>
+const props = defineProps<{ userId: string }>();
+useTopics([`user:${props.userId}:mentions`]);
+useSocketEvent(`user:${props.userId}:mentions:mention`, showToast);
+</script>
+```
+
+Server receives `$topic:subscribe` / `$topic:unsubscribe` events (configurable via `events.topicSubscribe`).
+
+## Push Notifications
+
+Two modes: **custom render** (sonner, react-hot-toast, your UI) and/or **browser Notification API**. Both respect `leaderOnly` + `onlyWhenHidden` to prevent duplicates across tabs.
+
+### Custom Render — you control the display
+
+```typescript
+// Vanilla — sonner toast
+import { toast } from 'sonner';
+
+ws.push('notification', {
+  render: (n) => toast(n.title, { description: n.body }),
+});
+
+ws.push('order.created', {
+  render: (order) => toast.success(`New Order #${order.id}`, {
+    description: `$${order.total} from ${order.customer}`,
+    action: { label: 'View', onClick: () => navigate(`/orders/${order.id}`) },
+  }),
+});
+```
+
+```tsx
+// React — sonner
+import { toast } from 'sonner';
+
+function NotificationSetup() {
+  usePush('notification', {
+    render: (n) => toast(n.title, { description: n.body }),
+  });
+
+  usePush('order.created', {
+    render: (order) => toast.success(`Order #${order.id} — $${order.total}`),
+  });
+
+  return null;
+}
+
+// React — react-hot-toast
+import hotToast from 'react-hot-toast';
+
+function NotificationSetup() {
+  usePush('notification', {
+    render: (n) => hotToast(n.title),
+  });
+  return null;
+}
+```
+
+```vue
+<!-- Vue — sonner-vue -->
+<script setup>
+import { toast } from 'sonner-vue';
+
+usePush('notification', {
+  render: (n) => toast(n.title, { description: n.body }),
+});
+
+usePush('order.created', {
+  render: (order) => toast.success(`Order #${order.id} — $${order.total}`),
+});
+</script>
+```
+
+### Browser Notification API — native OS notifications
+
+```typescript
+// Vanilla — browser native (no render needed)
+ws.push('notification', {
+  title: (n) => n.title,
+  body: (n) => n.body,
+  icon: '/icons/bell.png',
+  tag: (n) => `notif-${n.id}`,  // deduplication
+  onClick: (n) => window.open(n.url),
+  leaderOnly: true,       // default: true
+  onlyWhenHidden: true,   // default: true
+});
+```
+
+```tsx
+// React
+usePush('order.created', {
+  title: (order) => `New Order #${order.id}`,
+  body: (order) => `$${order.total}`,
+  icon: '/icons/order.png',
+  onClick: (order) => navigate(`/orders/${order.id}`),
+});
+```
+
+```vue
+<!-- Vue -->
+<script setup>
+usePush('order.created', {
+  title: (order) => `New Order #${order.id}`,
+  body: (order) => `$${order.total}`,
+});
+</script>
+```
+
+### Both — toast in UI + browser notification
+
+```typescript
+// Show sonner toast AND browser notification
+ws.push('order.created', {
+  render: (order) => toast.success(`Order #${order.id}`),  // in-app toast
+  title: (order) => `New Order #${order.id}`,              // + native notification
+  body: (order) => `$${order.total}`,
+});
+```
+
+## Server-Side Implementation Guide
+
+Complete server reference — what events to listen for and how to respond.
+
+### Message Format
+
+All messages are JSON with two fields (configurable via `events` option):
+
+```
+Client → Server: { "event": "event.name", "data": { ... } }
+Server → Client: { "event": "event.name", "data": { ... } }
+```
+
+### System Events (sent by client automatically)
+
+| Event | When | Payload | Your Server Should |
+|-------|------|---------|-------------------|
+| `ping` | Every 30s (heartbeat) | `{ "type": "ping" }` | Respond with `{ "type": "pong" }` or ignore |
+| `$channel:join` | `ws.channel('name')` | `{ "channel": "chat:room_1" }` | Track which channels this connection belongs to |
+| `$channel:leave` | `channel.leave()` | `{ "channel": "chat:room_1" }` | Remove connection from channel |
+| `$topic:subscribe` | `ws.subscribe('topic')` | `{ "topic": "notifications:orders" }` | Start sending events for this topic to this connection |
+| `$topic:unsubscribe` | `ws.unsubscribe('topic')` | `{ "topic": "notifications:orders" }` | Stop sending events for this topic |
+
+### Node.js (ws) — Complete Server Example
+
+```typescript
+import { WebSocketServer, WebSocket } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+
+// Track per-connection state
+interface ClientState {
+  userId?: string;
+  channels: Set<string>;
+  topics: Set<string>;
+}
+
+const clients = new Map<WebSocket, ClientState>();
+
+wss.on('connection', (ws, req) => {
+  // Extract auth token from URL
+  const url = new URL(req.url!, `http://${req.headers.host}`);
+  const token = url.searchParams.get('token');
+  const userId = verifyToken(token);  // your auth logic
+
+  const state: ClientState = {
+    userId,
+    channels: new Set(),
+    topics: new Set(),
+  };
+  clients.set(ws, state);
+
+  // Send welcome
+  send(ws, 'welcome', { userId, timestamp: Date.now() });
+
+  ws.on('message', (raw) => {
+    const msg = JSON.parse(raw.toString());
+    const { event, data } = msg;
+
+    switch (event) {
+      // ─── System Events ───────────────────────
+
+      case 'ping':
+        // Respond to heartbeat (optional — some servers ignore pings)
+        ws.send(JSON.stringify({ type: 'pong' }));
+        break;
+
+      // ─── Channel Events ──────────────────────
+
+      case '$channel:join':
+        state.channels.add(data.channel);
+        console.log(`${userId} joined ${data.channel}`);
+        // Send channel history, presence, etc.
+        break;
+
+      case '$channel:leave':
+        state.channels.delete(data.channel);
+        console.log(`${userId} left ${data.channel}`);
+        break;
+
+      // ─── Topic Events ────────────────────────
+
+      case '$topic:subscribe':
+        state.topics.add(data.topic);
+        console.log(`${userId} subscribed to ${data.topic}`);
+        break;
+
+      case '$topic:unsubscribe':
+        state.topics.delete(data.topic);
+        break;
+
+      // ─── App Events ──────────────────────────
+
+      case 'chat.send':
+        // Broadcast to all clients in the same channel
+        const channel = data.roomId ? `chat:${data.roomId}` : null;
+        broadcastToChannel(channel, 'chat.message', {
+          id: crypto.randomUUID(),
+          userId: state.userId,
+          text: data.text,
+          timestamp: Date.now(),
+        });
+        break;
+
+      case 'chat.typing':
+        broadcastToChannel(`chat:${data.roomId}`, 'chat.typing', {
+          userId: state.userId,
+        }, ws);  // exclude sender
+        break;
+
+      default:
+        console.log('Unknown event:', event, data);
+    }
+  });
+
+  ws.on('close', () => {
+    clients.delete(ws);
+  });
+});
+
+// ─── Helpers ─────────────────────────────────────
+
+function send(ws: WebSocket, event: string, data: unknown) {
+  if (ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify({ event, data }));
+  }
+}
+
+function broadcastToChannel(
+  channel: string | null,
+  event: string,
+  data: unknown,
+  exclude?: WebSocket,
+) {
+  for (const [ws, state] of clients) {
+    if (ws === exclude) continue;
+    if (channel && !state.channels.has(channel)) continue;
+    send(ws, event, data);
+  }
+}
+
+function broadcastToTopic(topic: string, event: string, data: unknown) {
+  for (const [ws, state] of clients) {
+    if (!state.topics.has(topic)) continue;
+    send(ws, `${topic}:${event}`, data);
+  }
+}
+
+// ─── Example: Send notifications by topic ────────
+
+function notifyNewOrder(order: Order) {
+  broadcastToTopic('notifications:orders', 'new', {
+    id: order.id,
+    total: order.total,
+    customer: order.customerName,
+  });
+  // Only clients who called ws.subscribe('notifications:orders') receive this
+}
+```
+
+### Go — Server Example
+
+```go
+// Message format
+type Message struct {
+    Event string          `json:"event"`
+    Data  json.RawMessage `json:"data"`
+}
+
+// Handle incoming messages
+func handleMessage(conn *websocket.Conn, state *ClientState, msg Message) {
+    switch msg.Event {
+    case "$channel:join":
+        var payload struct{ Channel string `json:"channel"` }
+        json.Unmarshal(msg.Data, &payload)
+        state.Channels[payload.Channel] = true
+
+    case "$channel:leave":
+        var payload struct{ Channel string `json:"channel"` }
+        json.Unmarshal(msg.Data, &payload)
+        delete(state.Channels, payload.Channel)
+
+    case "$topic:subscribe":
+        var payload struct{ Topic string `json:"topic"` }
+        json.Unmarshal(msg.Data, &payload)
+        state.Topics[payload.Topic] = true
+
+    case "$topic:unsubscribe":
+        var payload struct{ Topic string `json:"topic"` }
+        json.Unmarshal(msg.Data, &payload)
+        delete(state.Topics, payload.Topic)
+
+    case "chat.send":
+        // broadcast to channel...
+
+    case "ping":
+        conn.WriteJSON(Message{Event: "pong"})
+    }
+}
+```
+
+### PHP (Laravel + Ratchet/Swoole) — Server Example
+
+```php
+// Handle incoming WebSocket message
+public function onMessage(ConnectionInterface $conn, $msg): void
+{
+    $data = json_decode($msg, true);
+    $event = $data['event'] ?? 'message';
+    $payload = $data['data'] ?? [];
+
+    match ($event) {
+        '$channel:join' => $this->joinChannel($conn, $payload['channel']),
+        '$channel:leave' => $this->leaveChannel($conn, $payload['channel']),
+        '$topic:subscribe' => $this->subscribeTopic($conn, $payload['topic']),
+        '$topic:unsubscribe' => $this->unsubscribeTopic($conn, $payload['topic']),
+        'chat.send' => $this->handleChatMessage($conn, $payload),
+        'ping' => $conn->send(json_encode(['type' => 'pong'])),
+        default => logger()->warning("Unknown event: {$event}"),
+    };
+}
+
+// Send to topic subscribers
+public function notifyTopic(string $topic, string $event, array $data): void
+{
+    foreach ($this->connections as $conn) {
+        if (in_array($topic, $this->topics[$conn->resourceId] ?? [])) {
+            $conn->send(json_encode([
+                'event' => "{$topic}:{$event}",
+                'data' => $data,
+            ]));
+        }
+    }
+}
+```
+
 ## Exported Types
 
 All types are available for import in your projects:
@@ -1116,9 +1507,9 @@ import {
   useSocketStatus,
   useSocketLifecycle,
   useChannel,
+  useTopics,
+  usePush,
 } from '@gwakko/shared-websocket/react';
-
-import type { SharedWebSocketProviderProps } from '@gwakko/shared-websocket/react';
 ```
 
 ```typescript
@@ -1133,7 +1524,9 @@ import {
   useSocketStatus,
   useSocketLifecycle,
   useChannel,
-  SharedWebSocketKey,       // InjectionKey for custom provide/inject
+  useTopics,
+  usePush,
+  SharedWebSocketKey,
 } from '@gwakko/shared-websocket/vue';
 ```
 

package/dist/SharedWebSocket.d.ts

@@ -95,6 +95,78 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
      * notifications.on('alert', (alert) => showToast(alert));
      */
     channel(name: string): Channel;
+    /**
+     * Subscribe to a server-side topic. Server will start sending events for this topic.
+     * Sends topicSubscribe event (default: "$topic:subscribe").
+     *
+     * @example
+     * ws.subscribe('notifications:orders');
+     * ws.subscribe('notifications:payments');
+     * ws.subscribe(`user:${userId}:mentions`);
+     */
+    subscribe(topic: string): void;
+    /**
+     * Unsubscribe from a server-side topic.
+     * Sends topicUnsubscribe event (default: "$topic:unsubscribe").
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Subscribe to an event and show notifications.
+     *
+     * Two modes:
+     * - **render** — you control how to display (sonner, react-hot-toast, custom UI)
+     * - **browser Notification API** — native OS notifications (title/body/icon)
+     *
+     * Both modes respect leaderOnly + onlyWhenHidden to prevent duplicates.
+     *
+     * @example
+     * // Custom render — sonner toast
+     * import { toast } from 'sonner';
+     * ws.push('notification', {
+     *   render: (data) => toast(data.title, { description: data.body }),
+     * });
+     *
+     * @example
+     * // Custom render — react-hot-toast
+     * import toast from 'react-hot-toast';
+     * ws.push('order.created', {
+     *   render: (order) => toast.success(`New Order #${order.id} — $${order.total}`),
+     * });
+     *
+     * @example
+     * // Browser Notification API (no render — uses title/body/icon)
+     * ws.push('notification', {
+     *   title: (data) => data.title,
+     *   body: (data) => data.body,
+     *   icon: '/icons/bell.png',
+     * });
+     *
+     * @example
+     * // Both — toast in UI + browser notification
+     * ws.push('order.created', {
+     *   render: (order) => toast(`Order #${order.id}`),
+     *   title: (order) => `New Order #${order.id}`,
+     *   body: (order) => `$${order.total}`,
+     * });
+     */
+    push<T = unknown>(event: string, config: {
+        /** Custom render function — you decide how to display. Called for every matching event. */
+        render?: (data: T) => void;
+        /** Title for browser Notification API (ignored if only render is used). */
+        title?: string | ((data: T) => string);
+        /** Body for browser Notification API. */
+        body?: string | ((data: T) => string);
+        /** Icon URL for browser Notification. */
+        icon?: string;
+        /** Tag for browser Notification deduplication. */
+        tag?: string | ((data: T) => string);
+        /** Only trigger from leader tab (default: true). Prevents N duplicates for N tabs. */
+        leaderOnly?: boolean;
+        /** Only trigger when tab is hidden/background (default: true). */
+        onlyWhenHidden?: boolean;
+        /** Called when browser Notification is clicked. */
+        onClick?: (data: T) => void;
+    }): Unsubscribe;
     disconnect(): void;
     private createSocket;
     private handleBecomeLeader;

package/dist/adapters/react.d.ts

@@ -164,3 +164,37 @@ export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): v
  * useSocketCallback(`tenant:${tenantId}:notifications:alert`, showToast);
  */
 export declare function useChannel(name: string): import("..").Channel;
+/**
+ * Subscribe to server-side topics. Auto-unsubscribes on unmount.
+ *
+ * @example
+ * useTopics(['notifications:orders', 'notifications:payments']);
+ * useTopics([`user:${userId}:mentions`]);
+ */
+export declare function useTopics(topics: string[]): void;
+/**
+ * Enable browser push notifications for an event. Auto-cleanup on unmount.
+ *
+ * @example
+ * usePush('notification', {
+ *   title: (n) => n.title,
+ *   body: (n) => n.body,
+ *   icon: '/icon.png',
+ * });
+ *
+ * @example
+ * usePush('order.created', {
+ *   title: (order) => `New Order #${order.id}`,
+ *   body: (order) => `$${order.total}`,
+ *   onClick: (order) => navigate(`/orders/${order.id}`),
+ * });
+ */
+export declare function usePush<T = unknown>(event: string, config: {
+    title: string | ((data: T) => string);
+    body?: string | ((data: T) => string);
+    icon?: string;
+    tag?: string | ((data: T) => string);
+    leaderOnly?: boolean;
+    onlyWhenHidden?: boolean;
+    onClick?: (data: T) => void;
+}): void;

package/dist/adapters/vue.d.ts

@@ -123,3 +123,29 @@ export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): v
  * // Send via chat.send('message', { text: 'Hello' })
  */
 export declare function useChannel(name: string): import("..").Channel;
+/**
+ * Subscribe to server-side topics. Auto-unsubscribes on unmount.
+ *
+ * @example
+ * useTopics(['notifications:orders', 'notifications:payments']);
+ */
+export declare function useTopics(topics: string[]): void;
+/**
+ * Enable browser push notifications for an event. Auto-cleanup on unmount.
+ *
+ * @example
+ * usePush('notification', {
+ *   title: (n) => n.title,
+ *   body: (n) => n.body,
+ *   icon: '/icon.png',
+ * });
+ */
+export declare function usePush<T = unknown>(event: string, config: {
+    title: string | ((data: T) => string);
+    body?: string | ((data: T) => string);
+    icon?: string;
+    tag?: string | ((data: T) => string);
+    leaderOnly?: boolean;
+    onlyWhenHidden?: boolean;
+    onClick?: (data: T) => void;
+}): void;

package/dist/{chunk-UEOFAFLV.cjs → chunk-PH7NVGUX.cjs}

@@ -583,7 +583,9 @@ var DEFAULT_PROTOCOL = {
   channelJoin: "$channel:join",
   channelLeave: "$channel:leave",
   ping: { type: "ping" },
-  defaultEvent: "message"
+  defaultEvent: "message",
+  topicSubscribe: "$topic:subscribe",
+  topicUnsubscribe: "$topic:unsubscribe"
 };
 var NOOP_LOGGER = {
   debug() {
@@ -821,6 +823,99 @@ var SharedWebSocket = (_class6 = class {
       }
     };
   }
+  // ─── Topics ──────────────────────────────────────────
+  /**
+   * Subscribe to a server-side topic. Server will start sending events for this topic.
+   * Sends topicSubscribe event (default: "$topic:subscribe").
+   *
+   * @example
+   * ws.subscribe('notifications:orders');
+   * ws.subscribe('notifications:payments');
+   * ws.subscribe(`user:${userId}:mentions`);
+   */
+  subscribe(topic) {
+    this.send(this.proto.topicSubscribe, { topic });
+    this.log.debug("[SharedWS] \u{1F4CC} subscribe topic", topic);
+  }
+  /**
+   * Unsubscribe from a server-side topic.
+   * Sends topicUnsubscribe event (default: "$topic:unsubscribe").
+   */
+  unsubscribe(topic) {
+    this.send(this.proto.topicUnsubscribe, { topic });
+    this.log.debug("[SharedWS] \u{1F4CC} unsubscribe topic", topic);
+  }
+  // ─── Push Notifications ─────────────────────────────
+  /**
+   * Subscribe to an event and show notifications.
+   *
+   * Two modes:
+   * - **render** — you control how to display (sonner, react-hot-toast, custom UI)
+   * - **browser Notification API** — native OS notifications (title/body/icon)
+   *
+   * Both modes respect leaderOnly + onlyWhenHidden to prevent duplicates.
+   *
+   * @example
+   * // Custom render — sonner toast
+   * import { toast } from 'sonner';
+   * ws.push('notification', {
+   *   render: (data) => toast(data.title, { description: data.body }),
+   * });
+   *
+   * @example
+   * // Custom render — react-hot-toast
+   * import toast from 'react-hot-toast';
+   * ws.push('order.created', {
+   *   render: (order) => toast.success(`New Order #${order.id} — $${order.total}`),
+   * });
+   *
+   * @example
+   * // Browser Notification API (no render — uses title/body/icon)
+   * ws.push('notification', {
+   *   title: (data) => data.title,
+   *   body: (data) => data.body,
+   *   icon: '/icons/bell.png',
+   * });
+   *
+   * @example
+   * // Both — toast in UI + browser notification
+   * ws.push('order.created', {
+   *   render: (order) => toast(`Order #${order.id}`),
+   *   title: (order) => `New Order #${order.id}`,
+   *   body: (order) => `$${order.total}`,
+   * });
+   */
+  push(event, config) {
+    const leaderOnly = _nullishCoalesce(config.leaderOnly, () => ( true));
+    const onlyWhenHidden = _nullishCoalesce(config.onlyWhenHidden, () => ( true));
+    const useNativeNotification = !!config.title;
+    if (useNativeNotification && typeof Notification !== "undefined" && Notification.permission === "default") {
+      Notification.requestPermission();
+    }
+    return this.on(event, ((data) => {
+      const typed = data;
+      if (leaderOnly && this.tabRole !== "leader") return;
+      if (onlyWhenHidden && typeof document !== "undefined" && !document.hidden) return;
+      if (config.render) {
+        config.render(typed);
+        this.log.debug("[SharedWS] \u{1F514} push render", event);
+      }
+      if (useNativeNotification && typeof Notification !== "undefined" && Notification.permission === "granted") {
+        const title = typeof config.title === "function" ? config.title(typed) : config.title;
+        const body = typeof config.body === "function" ? config.body(typed) : config.body;
+        const tag = typeof config.tag === "function" ? config.tag(typed) : config.tag;
+        const notif = new Notification(title, { body, icon: config.icon, tag });
+        if (config.onClick) {
+          const handler = config.onClick;
+          notif.onclick = () => {
+            handler(typed);
+            window.focus();
+          };
+        }
+        this.log.debug("[SharedWS] \u{1F514} push native", title);
+      }
+    }));
+  }
   disconnect() {
     this[Symbol.dispose]();
   }
@@ -924,4 +1019,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-UEOFAFLV.cjs.map
+//# sourceMappingURL=chunk-PH7NVGUX.cjs.map