npm - openkbs-pulse - Versions diffs - 1.0.2 - Mend

openkbs-pulse 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,182 @@
+# OpenKBS Pulse SDK
+Real-time WebSocket SDK for browser applications. Similar to Ably/Pusher.
+## Installation
+### CDN
+```html
+<script src="https://cdn.openkbs.com/pulse/pulse.min.js"></script>
+```
+### NPM (coming soon)
+```bash
+npm install @openkbs/pulse
+```
+## Quick Start
+```javascript
+// Initialize
+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
+    debug: true                  // Optional: enable console logging
+});
+// Subscribe to a channel
+const channel = pulse.channel('posts');
+// Listen for specific events
+channel.subscribe('new_post', (data) => {
+    console.log('New post:', data);
+});
+// Listen for all events
+channel.subscribe((data, message) => {
+    console.log('Any event:', message.event, data);
+});
+// Publish event
+channel.publish('new_post', {
+    title: 'Hello World',
+    content: 'My first post'
+});
+```
+## Presence (Online Users)
+```javascript
+const channel = pulse.channel('chat-room');
+// Track who's online
+channel.presence.subscribe((members) => {
+    console.log('Online users:', members.length);
+});
+// Enter presence with user data
+channel.presence.enter({
+    name: 'John',
+    avatar: 'https://...'
+});
+// Listen for members joining/leaving
+channel.presence.onEnter((member) => {
+    console.log('User joined:', member.data.name);
+});
+channel.presence.onLeave((member) => {
+    console.log('User left:', member.data.name);
+});
+// Update your presence data
+channel.presence.update({ status: 'away' });
+// Leave presence
+channel.presence.leave();
+```
+## Connection State
+```javascript
+// Check connection state
+console.log(pulse.state);       // 'connected', 'disconnected', 'connecting', 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');
+    }
+});
+// Manual connect/disconnect
+pulse.disconnect();
+pulse.connect();
+```
+## API Reference
+### Pulse Constructor 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 |
+### Connection States
+- `disconnected` - Not connected
+- `connecting` - Establishing connection
+- `connected` - Connected and ready
+- `reconnecting` - Lost connection, attempting to reconnect
+- `failed` - Connection failed
+- `disconnecting` - Closing connection
+## Full Example
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Pulse Example</title>
+    <script src="https://cdn.openkbs.com/pulse/pulse.min.js"></script>
+</head>
+<body>
+    <div id="status">Connecting...</div>
+    <div id="online">Online: 0</div>
+    <div id="messages"></div>
+    <input type="text" id="input" placeholder="Type message...">
+    <button onclick="send()">Send</button>
+    <script>
+        const pulse = new Pulse({
+            kbId: 'YOUR_KB_ID',
+            token: 'USER_TOKEN',
+            debug: true
+        });
+        const channel = pulse.channel('chat');
+        // Connection status
+        pulse.onStateChange((state) => {
+            document.getElementById('status').textContent = state;
+        });
+        // Presence
+        channel.presence.subscribe((members) => {
+            document.getElementById('online').textContent = 'Online: ' + members.length;
+        });
+        channel.presence.enter({ name: 'User' });
+        // Messages
+        channel.subscribe('message', (data) => {
+            const div = document.createElement('div');
+            div.textContent = data.name + ': ' + data.text;
+            document.getElementById('messages').appendChild(div);
+        });
+        function send() {
+            const input = document.getElementById('input');
+            channel.publish('message', {
+                name: 'User',
+                text: input.value
+            });
+            input.value = '';
+        }
+    </script>
+</body>
+</html>
+```
+## License
+MIT

package/package.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "name": "openkbs-pulse",
+  "version": "1.0.2",
+  "description": "Real-time WebSocket SDK for OpenKBS",
+  "main": "pulse.js",
+  "types": "pulse.d.ts",
+  "files": [
+    "pulse.js",
+    "pulse.d.ts"
+  ],
+  "scripts": {
+    "deploy:cdn": "./deploy.sh",
+    "publish:patch": "npm version patch && npm publish --access public",
+    "publish:minor": "npm version minor && npm publish --access public",
+    "publish:major": "npm version major && npm publish --access public"
+  },
+  "keywords": ["websocket", "realtime", "pubsub", "openkbs"],
+  "author": "OpenKBS",
+  "license": "MIT"
+}

package/pulse.d.ts ADDED Viewed

@@ -0,0 +1,50 @@
+declare class Pulse {
+  constructor(options: PulseOptions);
+  connect(): void;
+  disconnect(): void;
+  channel(name: string): PulseChannel;
+  onStateChange(callback: (state: ConnectionState) => void): () => void;
+  readonly state: ConnectionState;
+  readonly isConnected: boolean;
+}
+interface PulseOptions {
+  kbId: string;
+  token: string;
+  channel?: string;
+  region?: 'us-east-1' | 'eu-central-1';
+  endpoint?: string;
+  debug?: boolean;
+  autoConnect?: boolean;
+}
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'disconnecting' | 'failed';
+declare class PulseChannel {
+  readonly name: string;
+  readonly presence: PulsePresence;
+  subscribe(callback: (data: any, msg: any) => void): () => void;
+  subscribe(event: string, callback: (data: any, msg: any) => void): () => void;
+  publish(event: string, data: any): boolean;
+  unsubscribe(): void;
+}
+declare class PulsePresence {
+  readonly members: PresenceMember[];
+  readonly count: number;
+  subscribe(callback: (members: PresenceMember[]) => void): () => void;
+  onEnter(callback: (member: PresenceMember) => void): () => void;
+  onLeave(callback: (member: PresenceMember) => void): () => void;
+  enter(data?: Record<string, any>): void;
+  leave(): void;
+  update(data: Record<string, any>): void;
+}
+interface PresenceMember {
+  connectionId: string;
+  userId?: string;
+  data?: Record<string, any>;
+}
+export = Pulse;
+export as namespace Pulse;

package/pulse.js ADDED Viewed

@@ -0,0 +1,477 @@
+/**
+ * OpenKBS Pulse v1.0.2 - Real-time WebSocket SDK
+ *
+ * Usage:
+ *   const pulse = new Pulse({ kbId: 'your-kb-id', token: 'user-token' });
+ *
+ *   const channel = pulse.channel('posts');
+ *   channel.subscribe('new_post', (data) => console.log('New post:', data));
+ *   channel.publish('new_post', { title: 'Hello' });
+ *
+ *   channel.presence.subscribe((members) => console.log('Online:', members.length));
+ *   channel.presence.enter({ name: 'John' });
+ */
+(function(global) {
+    'use strict';
+    const PULSE_ENDPOINTS = {
+        'us-east-1': 'wss://pulse.vpc1.us',
+        'eu-central-1': 'wss://pulse.vpc1.eu'
+    };
+    const DEFAULT_REGION = 'us-east-1';
+    const RECONNECT_DELAYS = [1000, 2000, 5000, 10000, 30000];
+    /**
+     * Main Pulse client
+     */
+    class Pulse {
+        constructor(options = {}) {
+            if (!options.kbId) {
+                throw new Error('Pulse: kbId is required');
+            }
+            if (!options.token) {
+                throw new Error('Pulse: token is required');
+            }
+            this.kbId = options.kbId;
+            this.token = options.token;
+            this._defaultChannel = options.channel || 'default';
+            this.region = options.region || DEFAULT_REGION;
+            this.endpoint = options.endpoint || PULSE_ENDPOINTS[this.region] || PULSE_ENDPOINTS[DEFAULT_REGION];
+            this.debug = options.debug || false;
+            this._channels = {};
+            this._ws = null;
+            this._reconnectAttempt = 0;
+            this._intentionalClose = false;
+            this._connectionState = 'disconnected';
+            this._stateListeners = [];
+            this._messageQueue = [];
+            // Auto-connect unless disabled
+            if (options.autoConnect !== false) {
+                this.connect();
+            }
+        }
+        /**
+         * Connect to Pulse WebSocket server
+         */
+        connect() {
+            if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+                this._log('Already connected');
+                return;
+            }
+            this._intentionalClose = false;
+            this._setConnectionState('connecting');
+            const url = `${this.endpoint}?kbId=${this.kbId}&token=${this.token}&channel=${this._defaultChannel}`;
+            this._log('Connecting to:', url);
+            try {
+                this._ws = new WebSocket(url);
+                this._setupWebSocket();
+            } catch (err) {
+                this._log('Connection error:', err);
+                this._setConnectionState('failed');
+                this._scheduleReconnect();
+            }
+        }
+        /**
+         * Disconnect from server
+         */
+        disconnect() {
+            this._intentionalClose = true;
+            this._setConnectionState('disconnecting');
+            if (this._ws) {
+                this._ws.close(1000, 'Client disconnect');
+                this._ws = null;
+            }
+            this._setConnectionState('disconnected');
+        }
+        /**
+         * Get or create a channel
+         */
+        channel(name) {
+            if (!this._channels[name]) {
+                this._channels[name] = new PulseChannel(this, name);
+            }
+            return this._channels[name];
+        }
+        /**
+         * Subscribe to connection state changes
+         */
+        onStateChange(callback) {
+            this._stateListeners.push(callback);
+            // Immediately call with current state
+            callback(this._connectionState);
+            return () => {
+                this._stateListeners = this._stateListeners.filter(cb => cb !== callback);
+            };
+        }
+        /**
+         * Get current connection state
+         */
+        get state() {
+            return this._connectionState;
+        }
+        /**
+         * Check if connected
+         */
+        get isConnected() {
+            return this._connectionState === 'connected';
+        }
+        // Internal methods
+        _setupWebSocket() {
+            this._ws.onopen = () => {
+                this._log('Connected');
+                this._reconnectAttempt = 0;
+                this._setConnectionState('connected');
+                // Resubscribe to all channels
+                Object.values(this._channels).forEach(channel => {
+                    channel._resubscribe();
+                });
+                // Flush message queue
+                this._flushMessageQueue();
+            };
+            this._ws.onclose = (e) => {
+                this._log('Disconnected:', e.code, e.reason);
+                this._setConnectionState('disconnected');
+                if (!this._intentionalClose) {
+                    this._scheduleReconnect();
+                }
+            };
+            this._ws.onerror = (err) => {
+                this._log('WebSocket error:', err);
+                this._setConnectionState('failed');
+            };
+            this._ws.onmessage = (e) => {
+                this._handleMessage(e.data);
+            };
+        }
+        _handleMessage(data) {
+            this._log('Received:', data);
+            try {
+                const msg = JSON.parse(data);
+                // Handle server message format: {type: 'message', data: {...}}
+                if (msg.type === 'message' && msg.data) {
+                    // Route to the connected channel
+                    const channel = this._channels[this._defaultChannel];
+                    if (channel) {
+                        channel._handleMessage(msg.data);
+                    }
+                }
+                // Handle system messages
+                if (msg.type === 'error') {
+                    this._log('Server error:', msg.error);
+                }
+            } catch (err) {
+                this._log('Parse error:', err);
+            }
+        }
+        _send(data) {
+            if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+                this._ws.send(JSON.stringify(data));
+                return true;
+            } else {
+                // Queue message for when connected
+                this._messageQueue.push(data);
+                return false;
+            }
+        }
+        _flushMessageQueue() {
+            while (this._messageQueue.length > 0) {
+                const msg = this._messageQueue.shift();
+                this._send(msg);
+            }
+        }
+        _scheduleReconnect() {
+            const delay = RECONNECT_DELAYS[Math.min(this._reconnectAttempt, RECONNECT_DELAYS.length - 1)];
+            this._reconnectAttempt++;
+            this._log(`Reconnecting in ${delay}ms (attempt ${this._reconnectAttempt})`);
+            this._setConnectionState('reconnecting');
+            setTimeout(() => {
+                if (!this._intentionalClose) {
+                    this.connect();
+                }
+            }, delay);
+        }
+        _setConnectionState(state) {
+            if (this._connectionState !== state) {
+                this._connectionState = state;
+                this._stateListeners.forEach(cb => cb(state));
+            }
+        }
+        _log(...args) {
+            if (this.debug) {
+                console.log('[Pulse]', ...args);
+            }
+        }
+    }
+    /**
+     * Channel for pub/sub messaging
+     */
+    class PulseChannel {
+        constructor(pulse, name) {
+            this._pulse = pulse;
+            this.name = name;
+            this._subscribers = {};
+            this._allSubscribers = [];
+            this._subscribed = false;
+            // Presence sub-object
+            this.presence = new PulsePresence(this);
+        }
+        /**
+         * Subscribe to a specific event type
+         */
+        subscribe(event, callback) {
+            if (typeof event === 'function') {
+                // Subscribe to all events
+                callback = event;
+                this._allSubscribers.push(callback);
+            } else {
+                // Subscribe to specific event
+                if (!this._subscribers[event]) {
+                    this._subscribers[event] = [];
+                }
+                this._subscribers[event].push(callback);
+            }
+            // Send subscribe message to server
+            if (!this._subscribed) {
+                this._pulse._send({
+                    action: 'subscribe',
+                    channel: this.name
+                });
+                this._subscribed = true;
+            }
+            // Return unsubscribe function
+            return () => {
+                if (typeof event === 'function') {
+                    this._allSubscribers = this._allSubscribers.filter(cb => cb !== callback);
+                } else {
+                    this._subscribers[event] = (this._subscribers[event] || []).filter(cb => cb !== callback);
+                }
+            };
+        }
+        /**
+         * Publish a message to the channel
+         */
+        publish(event, data) {
+            return this._pulse._send({
+                action: 'publish',
+                channel: this.name,
+                event: event,
+                data: data
+            });
+        }
+        /**
+         * Unsubscribe from channel
+         */
+        unsubscribe() {
+            this._subscribers = {};
+            this._allSubscribers = [];
+            this._subscribed = false;
+            this._pulse._send({
+                action: 'unsubscribe',
+                channel: this.name
+            });
+        }
+        // Internal methods
+        _handleMessage(msg) {
+            const event = msg.event || msg.type;
+            // Use msg itself as data if no data field (server sends {type: 'new_post', post: {...}})
+            const data = msg.data !== undefined ? msg.data : msg;
+            // Call specific event subscribers
+            if (event && this._subscribers[event]) {
+                this._subscribers[event].forEach(cb => cb(data, msg));
+            }
+            // Call all-event subscribers
+            this._allSubscribers.forEach(cb => cb(data, msg));
+            // Handle presence events
+            if (msg.type === 'presence') {
+                this.presence._handleMessage(msg);
+            }
+        }
+        _resubscribe() {
+            if (this._subscribed) {
+                this._pulse._send({
+                    action: 'subscribe',
+                    channel: this.name
+                });
+            }
+        }
+    }
+    /**
+     * Presence tracking for a channel
+     */
+    class PulsePresence {
+        constructor(channel) {
+            this._channel = channel;
+            this._members = [];
+            this._subscribers = [];
+            this._enterSubscribers = [];
+            this._leaveSubscribers = [];
+            this._myData = null;
+        }
+        /**
+         * Subscribe to presence changes
+         */
+        subscribe(callback) {
+            this._subscribers.push(callback);
+            // Return current members immediately
+            if (this._members.length > 0) {
+                callback(this._members);
+            }
+            return () => {
+                this._subscribers = this._subscribers.filter(cb => cb !== callback);
+            };
+        }
+        /**
+         * Subscribe to member enter events
+         */
+        onEnter(callback) {
+            this._enterSubscribers.push(callback);
+            return () => {
+                this._enterSubscribers = this._enterSubscribers.filter(cb => cb !== callback);
+            };
+        }
+        /**
+         * Subscribe to member leave events
+         */
+        onLeave(callback) {
+            this._leaveSubscribers.push(callback);
+            return () => {
+                this._leaveSubscribers = this._leaveSubscribers.filter(cb => cb !== callback);
+            };
+        }
+        /**
+         * Enter presence with optional data
+         */
+        enter(data = {}) {
+            this._myData = data;
+            this._channel._pulse._send({
+                action: 'presence_enter',
+                channel: this._channel.name,
+                data: data
+            });
+        }
+        /**
+         * Leave presence
+         */
+        leave() {
+            this._myData = null;
+            this._channel._pulse._send({
+                action: 'presence_leave',
+                channel: this._channel.name
+            });
+        }
+        /**
+         * Update presence data
+         */
+        update(data) {
+            this._myData = data;
+            this._channel._pulse._send({
+                action: 'presence_update',
+                channel: this._channel.name,
+                data: data
+            });
+        }
+        /**
+         * Get current members
+         */
+        get members() {
+            return this._members;
+        }
+        /**
+         * Get member count
+         */
+        get count() {
+            return this._members.length;
+        }
+        // Internal methods
+        _handleMessage(msg) {
+            if (msg.action === 'sync') {
+                this._members = msg.members || [];
+                this._notifySubscribers();
+            } else if (msg.action === 'enter') {
+                this._members.push(msg.member);
+                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._notifySubscribers();
+                this._leaveSubscribers.forEach(cb => cb(msg.member));
+            }
+        }
+        _notifySubscribers() {
+            this._subscribers.forEach(cb => cb(this._members));
+        }
+    }
+    // Export for different module systems
+    if (typeof module !== 'undefined' && module.exports) {
+        module.exports = Pulse;
+    } else if (typeof define === 'function' && define.amd) {
+        define([], function() { return Pulse; });
+    } else {
+        global.Pulse = Pulse;
+    }
+})(typeof window !== 'undefined' ? window : this);