pingerchips-js 2.1.0 → 3.0.0

package/README.md

@@ -1,4 +1,4 @@
-# Pingerchips JavaScript SDK
+# pingerchips-js
 
 Real-time WebSocket client for Pingerchips.
 
@@ -10,17 +10,29 @@ npm install pingerchips-js
 
 ## Usage
 
-### Basic Connection
+### Basic connection
 
 ```javascript
 import Pingerchips from 'pingerchips-js';
 
+// Connects to queue.pingerchips.com in production by default
+const client = new Pingerchips('your_app_key');
+```
+
+Pass `debug: "false"` to force the production endpoint, or override with `endpoint`:
+
+```javascript
+const client = new Pingerchips('your_app_key', {
+  debug: "false"  // uses wss://queue.pingerchips.com/socket
+});
+
+// or explicit:
 const client = new Pingerchips('your_app_key', {
-  endpoint: 'wss://pinger-processor.pingerchips.com/socket'
+  endpoint: 'wss://your-own-deployment.com/socket'
 });
 ```
 
-### Subscribe to Public Channels
+### Public channels
 
 ```javascript
 const channel = await client.subscribe('lobby');
@@ -29,77 +41,76 @@ channel.bind('message', (data) => {
   console.log('Received:', data);
 });
 
+// Send client event
 channel.trigger('message', { text: 'Hello!' });
 ```
 
-### Subscribe to Private Channels
+### Private channels
 
-For private channels, you need to configure an auth endpoint:
+Requires an `authEndpoint` on your server (see `pingerchips-js-server`):
 
 ```javascript
 const client = new Pingerchips('your_app_key', {
-  endpoint: 'wss://pinger-processor.pingerchips.com/socket',
   authEndpoint: 'https://your-server.com/auth',
-  authInfo: {
-    userId: '123',
-    token: 'user-session-token'
-  }
+  authInfo: { token: 'user-session-token' }  // forwarded to your auth endpoint
 });
 
-const privateChannel = await client.subscribe('private-chat');
+const channel = await client.subscribe('private-chat');
 ```
 
-### Subscribe to Presence Channels
+### Presence channels
 
 ```javascript
-const presenceChannel = await client.subscribe('presence-lobby');
-
-presenceChannel.bind('user-joined', (data) => {
-  console.log('User joined:', data.user_info);
+const client = new Pingerchips('your_app_key', {
+  authEndpoint: 'https://your-server.com/auth',
+  authInfo: { token: 'user-session-token' }
 });
-```
-
-## Configuration Options
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `endpoint` | string | WebSocket endpoint URL |
-| `authEndpoint` | string | Your server's auth endpoint for private/presence channels |
-| `authInfo` | object | User authentication info passed to your auth endpoint |
-| `authHeaders` | object | Additional headers for auth requests |
+const channel = await client.subscribe('presence-lobby');
 
-## Authentication
-
-For private and presence channels, you must implement an auth endpoint on your server. See [pingerchips-js-server](https://www.npmjs.com/package/pingerchips-js-server) for server-side implementation.
-
-## Channel Methods
-
-### `bind(event, callback)`
-
-Listen for events on a channel.
-
-```javascript
-channel.bind('message', (data) => {
-  console.log(data);
+channel.bind('presence_diff', ({ joins, leaves }) => {
+  console.log('Joined:', joins);
+  console.log('Left:', leaves);
 });
 ```
 
-### `trigger(event, data)`
+### Reconnection
+
+The client automatically reconnects on disconnect. All previously subscribed channels are re-joined transparently — no extra handling needed.
 
-Send an event to a channel.
+### Socket ID
 
 ```javascript
-channel.trigger('message', { text: 'Hello!' });
+// Available after first channel join
+const socketId = client.getSocketId();
 ```
 
-### `unbind(event)`
-
-Stop listening for an event.
+### Unsubscribe
 
 ```javascript
-channel.unbind('message');
+client.unsubscribe('lobby');
 ```
 
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `endpoint` | string | auto | WebSocket endpoint. Defaults to `wss://queue.pingerchips.com/socket` (prod) or `ws://localhost:4000/socket` (dev) |
+| `debug` | string | — | Set to `"false"` to use production endpoint without providing `endpoint` explicitly |
+| `authEndpoint` | string | — | Your server's auth URL for private/presence channels |
+| `authInfo` | object | `{}` | Forwarded to your auth endpoint in the request body |
+| `authHeaders` | object | — | Extra headers added to auth requests |
+| `params` | object | — | Extra params sent with the WebSocket connection |
+
+## Channel API
+
+| Method | Description |
+|---|---|
+| `bind(event, callback)` | Listen for an event |
+| `unbind(event)` | Stop listening for an event |
+| `trigger(event, data)` | Send a client event |
+| `leave()` | Leave the channel |
+
 ## License
 
 MIT