openkbs-pulse 1.0.7 → 1.0.10

package/README.md

@@ -1,124 +1,581 @@
 # OpenKBS Pulse SDK
 
-Real-time WebSocket SDK for browser applications. Similar to Ably/Pusher.
+Real-time WebSocket SDK for browser applications. Similar to Ably/Pusher but built for OpenKBS Elastic Services.
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [How It Works](#how-it-works)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Channels](#channels)
+- [Presence (Online Users)](#presence-online-users)
+- [Connection Management](#connection-management)
+- [Server-Side Publishing](#server-side-publishing)
+- [API Reference](#api-reference)
+- [Message Format](#message-format)
+- [Security](#security)
+- [Scalability](#scalability)
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              Client (Browser)                                │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  Pulse SDK                                                           │    │
+│  │  - Manages WebSocket connection                                      │    │
+│  │  - Handles reconnection with exponential backoff                     │    │
+│  │  - Routes messages to channels                                       │    │
+│  │  - Tracks presence state                                             │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      │ WebSocket (wss://)
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         AWS API Gateway (WebSocket)                          │
+│  Endpoints:                                                                  │
+│  - us-east-1: wss://pulse.vpc1.us                                           │
+│  - eu-central-1: wss://pulse.vpc1.eu                                        │
+│                                                                              │
+│  Routes:                                                                     │
+│  - $connect    → Lambda (validate token, store connection)                  │
+│  - $disconnect → Lambda (remove connection)                                 │
+│  - $default    → Lambda (handle publish/subscribe/presence)                 │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Lambda: openkbs-elastic-pulse                        │
+│                                                                              │
+│  Handles:                                                                    │
+│  - Token validation (RS256 kbToken or ES256 pulseToken)                     │
+│  - Connection storage in DynamoDB                                           │
+│  - Message broadcasting to channel subscribers                              │
+│  - Presence queries                                                         │
+│  - Stale connection cleanup                                                 │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    DynamoDB: openkbs-elastic-pulse-connections               │
+│                                                                              │
+│  Schema:                                                                     │
+│  - Primary Key: kbId (partition) + connectionId (sort)                      │
+│  - GSI: channel-index (kbId + channel) - for broadcasting                   │
+│  - GSI: connectionId-index (connectionId) - for O(1) lookups                │
+│  - TTL: 24 hours auto-cleanup                                               │
+│                                                                              │
+│  Fields:                                                                     │
+│  - kbId, connectionId, channel, userId, region, connectedAt, ttl            │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## How It Works
+
+### Connection Flow
+
+1. **Client connects** with `kbId` and `token` via WebSocket
+2. **Lambda validates token** (JWT with RS256 or ES256)
+3. **Checks KB has Pulse enabled** (`elasticPulseEnabled` flag)
+4. **Stores connection** in DynamoDB with channel and user info
+5. **Client subscribes to channels** by sending `{action: 'subscribe', channel: 'name'}`
+6. **Messages are broadcast** to all connections in the same kbId + channel
+
+### Message Flow
+
+```
+Client A                    Lambda                    Client B
+   │                          │                          │
+   │ publish('chat', 'msg',   │                          │
+   │         {text: 'Hi'})    │                          │
+   │ ─────────────────────────>                          │
+   │                          │                          │
+   │                          │ Query DynamoDB for       │
+   │                          │ all connections in       │
+   │                          │ kbId + channel           │
+   │                          │                          │
+   │                          │ postToConnection()       │
+   │                          │ ─────────────────────────>
+   │                          │                          │
+   │                          │         {type: 'message',│
+   │                          │          channel: 'chat',│
+   │                          │          data: {text:'Hi'}}
+```
+
+### Presence Flow
+
+```
+Client A                    Lambda                    Client B
+   │                          │                          │
+   │ {action: 'presence',     │                          │
+   │  channel: 'chat'}        │                          │
+   │ ─────────────────────────>                          │
+   │                          │                          │
+   │                          │ Query all connections    │
+   │                          │ in kbId + channel        │
+   │                          │                          │
+   │        {type: 'presence',│                          │
+   │         action: 'sync',  │                          │
+   │         count: 5,        │                          │
+   │         members: [...]}  │                          │
+   │ <─────────────────────────                          │
+```
+
+---
 
 ## Installation
 
-### CDN
+### CDN (Browser)
+
 ```html
 <script src="https://cdn.openkbs.com/pulse/pulse.min.js"></script>
 ```
 
-### NPM (coming soon)
+### NPM
+
 ```bash
 npm install @openkbs/pulse
 ```
 
+```javascript
+import Pulse from '@openkbs/pulse';
+```
+
+---
+
 ## Quick Start
 
 ```javascript
-// Initialize
+// Initialize with your KB credentials
 const pulse = new Pulse({
     kbId: 'your-kb-id',
-    token: 'user-pulse-token',   // From auth response
-    region: 'eu-central-1',      // Optional: us-east-1 (default), eu-central-1, ap-southeast-1
+    token: 'user-pulse-token',   // From auth response or Elastic Function
+    region: 'us-east-1',         // Optional: us-east-1 (default), eu-central-1
     debug: true                  // Optional: enable console logging
 });
 
 // Subscribe to a channel
-const channel = pulse.channel('posts');
+const channel = pulse.channel('notifications');
 
 // Listen for specific events
-channel.subscribe('new_post', (data) => {
-    console.log('New post:', data);
+channel.subscribe('new_order', (data) => {
+    console.log('New order:', data);
 });
 
-// Listen for all events
-channel.subscribe((data, message) => {
-    console.log('Any event:', message.event, data);
+// Publish an event (broadcasts to all subscribers)
+channel.publish('new_order', {
+    orderId: '12345',
+    amount: 99.99
 });
+```
+
+---
+
+## Channels
+
+Channels are logical groupings for messages. Each KB can have unlimited channels.
+
+### Creating/Getting a Channel
+
+```javascript
+const channel = pulse.channel('channel-name');
+```
+
+Channels are created on-demand. The same channel instance is returned for the same name.
 
-// Publish event
-channel.publish('new_post', {
-    title: 'Hello World',
-    content: 'My first post'
+### Subscribing to Events
+
+```javascript
+// Subscribe to a specific event type
+const unsubscribe = channel.subscribe('event_name', (data, rawMessage) => {
+    console.log('Event data:', data);
+    console.log('Full message:', rawMessage);
+});
+
+// Subscribe to ALL events on the channel
+channel.subscribe((data, rawMessage) => {
+    console.log('Any event:', rawMessage.event, data);
 });
+
+// Unsubscribe
+unsubscribe();
 ```
 
+### Publishing Events
+
+```javascript
+// Publish to channel (broadcasts to all OTHER subscribers)
+channel.publish('event_name', {
+    any: 'data',
+    you: 'want'
+});
+```
+
+Note: The sender does NOT receive their own published messages.
+
+### Unsubscribing from Channel
+
+```javascript
+channel.unsubscribe(); // Removes all event listeners
+```
+
+---
+
 ## Presence (Online Users)
 
+Track who's currently online in a channel.
+
+### Subscribe to Presence Changes
+
 ```javascript
 const channel = pulse.channel('chat-room');
 
-// Track who's online
+// Get notified when member list changes
 channel.presence.subscribe((members) => {
-    console.log('Online users:', members.length);
+    console.log('Online count:', members.length);
+    members.forEach(m => {
+        console.log(`- ${m.userId} (connected at ${m.connectedAt})`);
+    });
 });
 
-// Enter presence with user data
+// Get current member count (may be higher than members.length if > 100)
+console.log('Total online:', channel.presence.count);
+```
+
+### Enter Presence
+
+```javascript
+// Enter with custom data
 channel.presence.enter({
-    name: 'John',
-    avatar: 'https://...'
+    name: 'John Doe',
+    avatar: 'https://example.com/avatar.jpg',
+    status: 'online'
 });
+```
 
-// Listen for members joining/leaving
+### Listen for Join/Leave Events
+
+```javascript
 channel.presence.onEnter((member) => {
-    console.log('User joined:', member.data.name);
+    console.log('User joined:', member.userId, member.data);
 });
 
 channel.presence.onLeave((member) => {
-    console.log('User left:', member.data.name);
+    console.log('User left:', member.userId);
 });
+```
 
-// Update your presence data
-channel.presence.update({ status: 'away' });
+### Update Presence Data
 
-// Leave presence
+```javascript
+channel.presence.update({
+    status: 'away',
+    lastSeen: Date.now()
+});
+```
+
+### Leave Presence
+
+```javascript
 channel.presence.leave();
 ```
 
-## Connection State
+### Presence Member Object
 
 ```javascript
-// Check connection state
-console.log(pulse.state);       // 'connected', 'disconnected', 'connecting', etc.
+{
+    connectionId: 'abc123',      // Unique connection ID
+    userId: 'user@example.com',  // From token
+    connectedAt: 1703952000000,  // Connection timestamp
+    data: { ... }                // Custom data from enter()
+}
+```
+
+---
+
+## Connection Management
+
+### Connection States
+
+| State | Description |
+|-------|-------------|
+| `disconnected` | Not connected to server |
+| `connecting` | Establishing WebSocket connection |
+| `connected` | Connected and ready |
+| `reconnecting` | Lost connection, attempting to reconnect |
+| `failed` | Connection attempt failed |
+| `disconnecting` | Closing connection |
+
+### Monitoring Connection State
+
+```javascript
+// Get current state
+console.log(pulse.state);       // 'connected', 'disconnected', etc.
 console.log(pulse.isConnected); // true/false
 
 // Listen for state changes
-pulse.onStateChange((state) => {
-    if (state === 'connected') {
-        console.log('Online!');
-    } else if (state === 'disconnected') {
-        console.log('Offline');
+const unsubscribe = pulse.onStateChange((state) => {
+    switch (state) {
+        case 'connected':
+            console.log('Online!');
+            break;
+        case 'disconnected':
+            console.log('Offline');
+            break;
+        case 'reconnecting':
+            console.log('Reconnecting...');
+            break;
     }
 });
 
-// Manual connect/disconnect
+// Stop listening
+unsubscribe();
+```
+
+### Manual Connect/Disconnect
+
+```javascript
+// Disconnect (stops reconnection attempts)
 pulse.disconnect();
+
+// Reconnect
 pulse.connect();
 ```
 
+### Automatic Reconnection
+
+The SDK automatically reconnects with exponential backoff:
+- 1s → 2s → 5s → 10s → 30s (max)
+
+On reconnection, all channel subscriptions are automatically restored.
+
+---
+
+## Server-Side Publishing
+
+Publish messages from Elastic Functions or Node.js servers.
+
+### Using Elastic Functions
+
+```javascript
+// In your Elastic Function
+export default async function handler(event, context) {
+    // Publish to all connected clients
+    await context.pulse.publish('notifications', 'new_alert', {
+        message: 'Server update available',
+        severity: 'info'
+    });
+
+    // Get presence info
+    const { count, members } = await context.pulse.presence('chat-room');
+    console.log(`${count} users online`);
+
+    return { success: true };
+}
+```
+
+### Using Server SDK
+
+```javascript
+import pulse from '@openkbs/pulse/server';
+
+// Generate token for client authentication
+const { token, endpoint, region } = await pulse.getToken(kbId, apiKey, userId);
+
+// Publish from server
+await pulse.publish('channel', 'event', { data: 'value' });
+
+// Get presence
+const { count, members } = await pulse.presence('channel');
+```
+
+---
+
 ## API Reference
 
-### Pulse Constructor Options
+### Pulse Constructor
+
+```javascript
+new Pulse(options)
+```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| kbId | string | required | Your KB ID |
-| token | string | required | User's pulse token (from auth) |
-| region | string | 'us-east-1' | Server region |
-| endpoint | string | auto | Custom WebSocket endpoint |
-| debug | boolean | false | Enable debug logging |
-| autoConnect | boolean | true | Connect automatically |
+| `kbId` | string | **required** | Your Knowledge Base ID |
+| `token` | string | **required** | JWT token for authentication |
+| `region` | string | `'us-east-1'` | Server region (`us-east-1`, `eu-central-1`) |
+| `endpoint` | string | auto | Custom WebSocket endpoint URL |
+| `channel` | string | `'default'` | Default channel to connect to |
+| `debug` | boolean | `false` | Enable console debug logging |
+| `autoConnect` | boolean | `true` | Connect automatically on instantiation |
 
-### Connection States
+### Pulse Instance Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `channel(name)` | `PulseChannel` | Get or create a channel |
+| `connect()` | void | Connect to WebSocket server |
+| `disconnect()` | void | Disconnect from server |
+| `onStateChange(callback)` | unsubscribe fn | Listen for connection state changes |
+
+### Pulse Instance Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `state` | string | Current connection state |
+| `isConnected` | boolean | Whether currently connected |
+
+### PulseChannel Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `subscribe(event, callback)` | unsubscribe fn | Subscribe to specific event |
+| `subscribe(callback)` | unsubscribe fn | Subscribe to all events |
+| `publish(event, data)` | boolean | Publish event to channel |
+| `unsubscribe()` | void | Unsubscribe from channel |
+
+### PulsePresence Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `subscribe(callback)` | unsubscribe fn | Subscribe to member list changes |
+| `onEnter(callback)` | unsubscribe fn | Subscribe to member join events |
+| `onLeave(callback)` | unsubscribe fn | Subscribe to member leave events |
+| `enter(data)` | void | Enter presence with optional data |
+| `leave()` | void | Leave presence |
+| `update(data)` | void | Update presence data |
+
+### PulsePresence Properties
 
-- `disconnected` - Not connected
-- `connecting` - Establishing connection
-- `connected` - Connected and ready
-- `reconnecting` - Lost connection, attempting to reconnect
-- `failed` - Connection failed
-- `disconnecting` - Closing connection
+| Property | Type | Description |
+|----------|------|-------------|
+| `members` | array | Current member list (max 100) |
+| `count` | number | Total member count |
+
+---
+
+## Message Format
+
+### Client → Server
+
+```javascript
+// Subscribe to channel
+{ action: 'subscribe', channel: 'channel-name' }
+
+// Unsubscribe from channel
+{ action: 'unsubscribe', channel: 'channel-name' }
+
+// Publish message
+{ action: 'publish', channel: 'channel-name', event: 'event-name', data: {...} }
+
+// Request presence
+{ action: 'presence', channel: 'channel-name' }
+
+// Enter presence
+{ action: 'presence_enter', channel: 'channel-name', data: {...} }
+
+// Leave presence
+{ action: 'presence_leave', channel: 'channel-name' }
+
+// Update presence
+{ action: 'presence_update', channel: 'channel-name', data: {...} }
+
+// Ping (heartbeat)
+{ action: 'ping' }
+```
+
+### Server → Client
+
+```javascript
+// Message broadcast
+{ type: 'message', channel: 'channel-name', data: {...}, timestamp: 1703952000000 }
+
+// Presence sync (full member list)
+{ type: 'presence', action: 'sync', channel: 'channel-name', count: 5, members: [...] }
+
+// Presence enter
+{ type: 'presence', action: 'enter', channel: 'channel-name', member: {...} }
+
+// Presence leave
+{ type: 'presence', action: 'leave', channel: 'channel-name', member: {...} }
+
+// Pong response
+{ type: 'pong', timestamp: 1703952000000 }
+
+// Error
+{ type: 'error', error: 'Error message' }
+```
+
+---
+
+## Security
+
+### Authentication
+
+Pulse uses JWT tokens for authentication:
+
+1. **KB Token (RS256)**: Standard OpenKBS user token
+2. **Pulse Token (ES256)**: Generated by Elastic Functions for specific users
+3. **Public Chat Token (ES256)**: For anonymous/public access
+
+Token must contain:
+- `kbId`: Must match the connection's kbId
+- `userId` or `email` or `chatId`: User identifier
+
+### Authorization
+
+- Connections are validated against the KB's `elasticPulseEnabled` flag
+- Each connection is scoped to a single KB (cross-KB messaging not allowed)
+- Channels within a KB are not authenticated (any valid token can access any channel)
+
+### Connection Security
+
+- All connections use WSS (WebSocket Secure)
+- Connections expire after 24 hours (TTL)
+- Stale connections are automatically cleaned up
+
+---
+
+## Scalability
+
+### Design for Scale
+
+The Pulse backend is designed to handle:
+- **Many KBs (applications)**: Each KB is isolated
+- **Hundreds of concurrent users per KB**: Efficient per-channel queries
+- **Large channels**: Paginated broadcasting (100 connections per batch)
+
+### DynamoDB Indexes
+
+| Index | Keys | Purpose |
+|-------|------|---------|
+| Primary | `kbId` + `connectionId` | Unique connection lookup |
+| `channel-index` | `kbId` + `channel` | Broadcast to channel subscribers |
+| `connectionId-index` | `connectionId` | O(1) connection lookup for messages |
+
+### Limits
+
+| Resource | Limit |
+|----------|-------|
+| Presence member list | 100 members (count is accurate) |
+| Connection TTL | 24 hours |
+| Message size | 32 KB (API Gateway limit) |
+| Broadcast batch | 100 concurrent sends |
+
+### Best Practices
+
+1. **Use specific channels**: Don't put all users in one channel
+2. **Clean up presence**: Call `leave()` when user navigates away
+3. **Handle reconnection**: Subscribe handlers survive reconnection automatically
+4. **Monitor state**: Show connection status to users
+
+---
 
 ## Full Example
 
@@ -126,14 +583,25 @@ pulse.connect();
 <!DOCTYPE html>
 <html>
 <head>
-    <title>Pulse Example</title>
+    <title>Pulse Chat Example</title>
     <script src="https://cdn.openkbs.com/pulse/pulse.min.js"></script>
+    <style>
+        .status { padding: 5px 10px; border-radius: 10px; }
+        .connected { background: #4CAF50; color: white; }
+        .disconnected { background: #f44336; color: white; }
+        #messages { height: 300px; overflow-y: auto; border: 1px solid #ccc; padding: 10px; }
+    </style>
 </head>
 <body>
-    <div id="status">Connecting...</div>
-    <div id="online">Online: 0</div>
+    <h1>Pulse Chat</h1>
+    <div>
+        <span id="status" class="status disconnected">Connecting...</span>
+        <span id="online">👥 0 online</span>
+    </div>
+
     <div id="messages"></div>
 
+    <input type="text" id="name" placeholder="Your name" value="Anonymous">
     <input type="text" id="input" placeholder="Type message...">
     <button onclick="send()">Send</button>
 
@@ -145,62 +613,107 @@ pulse.connect();
         });
 
         const channel = pulse.channel('chat');
+        const statusEl = document.getElementById('status');
+        const onlineEl = document.getElementById('online');
+        const messagesEl = document.getElementById('messages');
 
         // Connection status
         pulse.onStateChange((state) => {
-            document.getElementById('status').textContent = state;
+            statusEl.textContent = state;
+            statusEl.className = 'status ' + (state === 'connected' ? 'connected' : 'disconnected');
         });
 
-        // Presence
+        // Presence tracking
         channel.presence.subscribe((members) => {
-            document.getElementById('online').textContent = 'Online: ' + members.length;
+            onlineEl.textContent = '👥 ' + members.length + ' online';
         });
-        channel.presence.enter({ name: 'User' });
 
-        // Messages
+        channel.presence.onEnter((member) => {
+            addMessage('system', `${member.userId} joined`);
+        });
+
+        channel.presence.onLeave((member) => {
+            addMessage('system', `${member.userId} left`);
+        });
+
+        // Enter presence when connected
+        pulse.onStateChange((state) => {
+            if (state === 'connected') {
+                channel.presence.enter({ name: document.getElementById('name').value });
+            }
+        });
+
+        // Message handling
         channel.subscribe('message', (data) => {
-            const div = document.createElement('div');
-            div.textContent = data.name + ': ' + data.text;
-            document.getElementById('messages').appendChild(div);
+            addMessage(data.name, data.text);
         });
 
+        function addMessage(name, text) {
+            const div = document.createElement('div');
+            div.innerHTML = '<strong>' + name + ':</strong> ' + text;
+            messagesEl.appendChild(div);
+            messagesEl.scrollTop = messagesEl.scrollHeight;
+        }
+
         function send() {
             const input = document.getElementById('input');
-            channel.publish('message', {
-                name: 'User',
-                text: input.value
-            });
-            input.value = '';
+            const name = document.getElementById('name').value || 'Anonymous';
+
+            if (input.value.trim()) {
+                channel.publish('message', { name, text: input.value });
+                addMessage(name, input.value); // Show own message
+                input.value = '';
+            }
         }
+
+        // Send on Enter key
+        document.getElementById('input').addEventListener('keypress', (e) => {
+            if (e.key === 'Enter') send();
+        });
+
+        // Leave presence on page unload
+        window.addEventListener('beforeunload', () => {
+            channel.presence.leave();
+        });
     </script>
 </body>
 </html>
 ```
 
-## Server SDK
+---
 
-For server-side usage (Elastic Functions, Node.js):
+## Troubleshooting
 
-```javascript
-import pulse from 'openkbs-pulse/server';
+### Connection Issues
 
-// Get a token for client WebSocket auth
-const { token, endpoint, region } = await pulse.getToken(kbId, apiKey, userId);
+**Problem**: `Invalid token` error on connect
+- Ensure token is valid JWT with correct `kbId`
+- Check token hasn't expired
+- Verify KB has `elasticPulseEnabled: true`
 
-// Publish to channel
-await pulse.publish('channel', 'event', { data });
+**Problem**: Connection keeps reconnecting
+- Check network connectivity
+- Verify WebSocket endpoint is correct for your region
+- Enable `debug: true` to see detailed logs
 
-// Get presence info
-const { count, members } = await pulse.presence('channel');
-```
+### Presence Issues
+
+**Problem**: Presence count shows 0
+- Request presence after subscribing: `{action: 'presence', channel: 'name'}`
+- Ensure channel name matches exactly (case-sensitive)
+
+**Problem**: Members list is truncated
+- By design, only 100 members are returned
+- Use `channel.presence.count` for accurate total
+
+### Message Issues
 
-### Server SDK Functions
+**Problem**: Not receiving published messages
+- Verify you're subscribed to the correct channel and event
+- Publishers don't receive their own messages
+- Check `debug: true` logs for incoming messages
 
-| Function | Parameters | Description |
-|----------|------------|-------------|
-| `getToken(kbId, apiKey, userId)` | kbId, apiKey (required), userId (default: 'anonymous') | Get WebSocket auth token |
-| `publish(channel, event, data)` | All required | Publish message to channel |
-| `presence(channel)` | channel name | Get online count and members |
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openkbs-pulse",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "description": "Real-time WebSocket SDK for OpenKBS",
   "main": "pulse.js",
   "types": "pulse.d.ts",

package/pulse.js

@@ -174,15 +174,25 @@
             try {
                 const msg = JSON.parse(data);
 
-                // Handle server message format: {type: 'message', data: {...}}
+                // Handle server message format: {type: 'message', channel: 'x', data: {...}}
                 if (msg.type === 'message' && msg.data) {
-                    // Route to the connected channel
-                    const channel = this._channels[this._defaultChannel];
+                    // Route to the correct channel based on msg.channel
+                    const channelName = msg.channel || this._defaultChannel;
+                    const channel = this._channels[channelName];
                     if (channel) {
                         channel._handleMessage(msg.data);
                     }
                 }
 
+                // Handle presence response: {type: 'presence', channel: 'x', action: 'sync', members: [...]}
+                if (msg.type === 'presence') {
+                    const channelName = msg.channel || this._defaultChannel;
+                    const channel = this._channels[channelName];
+                    if (channel && channel.presence) {
+                        channel.presence._handleMessage(msg);
+                    }
+                }
+
                 // Handle system messages
                 if (msg.type === 'error') {
                     this._log('Server error:', msg.error);
@@ -352,6 +362,7 @@
         constructor(channel) {
             this._channel = channel;
             this._members = [];
+            this._count = 0;
             this._subscribers = [];
             this._enterSubscribers = [];
             this._leaveSubscribers = [];
@@ -437,24 +448,28 @@
         }
 
         /**
-         * Get member count
+         * Get member count (may be higher than members.length if list is limited)
          */
         get count() {
-            return this._members.length;
+            return this._count || this._members.length;
         }
 
         // Internal methods
 
         _handleMessage(msg) {
-            if (msg.action === 'sync') {
+            // Handle sync (full member list) - can come from action='sync' or just type='presence'
+            if (msg.action === 'sync' || (msg.type === 'presence' && msg.members)) {
                 this._members = msg.members || [];
+                this._count = msg.count !== undefined ? msg.count : this._members.length;
                 this._notifySubscribers();
             } else if (msg.action === 'enter') {
                 this._members.push(msg.member);
+                this._count = (this._count || 0) + 1;
                 this._notifySubscribers();
                 this._enterSubscribers.forEach(cb => cb(msg.member));
             } else if (msg.action === 'leave') {
                 this._members = this._members.filter(m => m.connectionId !== msg.member.connectionId);
+                this._count = Math.max(0, (this._count || 1) - 1);
                 this._notifySubscribers();
                 this._leaveSubscribers.forEach(cb => cb(msg.member));
             }