pingerchips-js-server 2.0.0 → 2.1.1

package/README.md

@@ -1,6 +1,8 @@
-# Pingerchips Server SDK
+# pingerchips-js-server
 
-Server-side SDK for triggering events and authenticating users with Pingerchips.
+Server-side SDK for Pingerchips. Trigger events and authenticate users for private/presence channels.
+
+Requires Node.js 18+ (uses native `fetch`).
 
 ## Installation
 
@@ -15,24 +17,23 @@ npm install pingerchips-js-server
 ```javascript
 import PingerchipsServer from 'pingerchips-js-server';
 
-const pingerchips = new PingerchipsServer('app_id', 'app_secret', {
-  appKey: 'app_key',
-  endpoint: 'https://pinger-processor.pingerchips.com/api'
-});
+const pingerchips = new PingerchipsServer('app_key', 'app_secret');
 ```
 
-### Trigger Events
+Defaults to `https://queue.pingerchips.com` in production (`NODE_ENV=production`) and `http://localhost:4000` otherwise. Override with `options.endpoint` or the `PINGERCHIPS_API_ENDPOINT` env var.
 
-Send events to channels from your server:
+### Trigger events
 
 ```javascript
-await pingerchips.trigger('lobby', 'message', {
+await pingerchips.trigger('lobby', 'new-message', {
   text: 'Hello from server!',
   timestamp: Date.now()
 });
 ```
 
-### Authenticate Users (Private/Presence Channels)
+Failed requests are retried on 5xx and network errors (default: 2 retries).
+
+### Authenticate users (private/presence channels)
 
 Implement an auth endpoint on your server:
 
@@ -45,76 +46,89 @@ app.use(express.json());
 app.post('/auth', (req, res) => {
   const { socket_id, channel_name, auth_info } = req.body;
 
-  // Validate user from session/token
   const user = validateUser(auth_info);
-  if (!user) {
-    return res.status(403).json({ error: 'Unauthorized' });
-  }
+  if (!user) return res.status(403).json({ error: 'Unauthorized' });
 
-  // For presence channels, provide user data
-  const userData = channel_name.startsWith('presence-') ? {
-    user_id: user.id,
-    user_info: {
-      name: user.name,
-      avatar: user.avatar
-    }
-  } : null;
+  const userData = channel_name.startsWith('presence-')
+    ? { user_id: user.id, user_info: { name: user.name } }
+    : null;
 
-  // Sign authentication with Pingerchips
   const authData = pingerchips.authenticate(socket_id, channel_name, userData);
   res.json(authData);
 });
 ```
 
-## API Reference
+Configure the client to use it:
+
+```javascript
+const client = new Pingerchips('app_key', {
+  authEndpoint: 'https://your-server.com/auth'
+});
+```
+
+## API
 
-### `new PingerchipsServer(appId, appSecret, options)`
+### `new PingerchipsServer(appKey, appSecret, options?)`
 
-Create a new server instance.
+| Parameter | Type | Description |
+|---|---|---|
+| `appKey` | string | Your app key |
+| `appSecret` | string | Your app secret — used for HMAC signing, never sent over the wire |
 
 **Options:**
-- `appKey` - Your app key (required for authentication)
-- `endpoint` - API endpoint URL
-- `token` - API token for internal endpoints
-- `mtls` - mTLS configuration for secure connections
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `endpoint` | string | auto | API base URL |
+| `requestTimeout` | number | `10000` | Request timeout in ms |
+| `retries` | number | `2` | Retries on 5xx / network error |
+| `token` | string | — | Internal API token (legacy) |
+| `mtls` | object | — | mTLS config (see below) |
 
 ### `trigger(channel, event, data)`
 
-Send an event to a channel.
+Trigger an event on a channel.
+
+- `channel` — max 200 chars
+- `event` — max 200 chars
+- `data` — must be JSON serializable, max 64KB
 
 ```javascript
-await pingerchips.trigger('my-channel', 'my-event', { message: 'Hello' });
+await pingerchips.trigger('room-42', 'message', { text: 'hi' });
 ```
 
 ### `authenticate(socketId, channelName, userData?)`
 
-Generate signed authentication for private/presence channels.
+Sign a channel auth request. Call from your auth endpoint.
 
-**Parameters:**
-- `socketId` - Socket ID from client
-- `channelName` - Channel name (e.g., "private-chat" or "presence-lobby")
-- `userData` - User data for presence channels (must include `user_id`)
+- `channelName` must start with `private-` or `presence-`
+- `userData` required for presence channels, must include `user_id`
 
-**Returns:**
 ```javascript
-{
-  auth: "app_key:hmac_signature",
-  channel_data: "{\"user_id\":\"123\",...}" // presence channels only
-}
+// Private channel
+const auth = pingerchips.authenticate(socketId, 'private-chat');
+// → { auth: "app_key:hmac_signature" }
+
+// Presence channel
+const auth = pingerchips.authenticate(socketId, 'presence-lobby', {
+  user_id: '123',
+  user_info: { name: 'Alice' }
+});
+// → { auth: "app_key:hmac_signature", channel_data: "{\"user_id\":\"123\",...}" }
 ```
 
-## mTLS Support
+## mTLS
 
 For secure server-to-server communication:
 
 ```javascript
-const pingerchips = new PingerchipsServer('app_id', 'app_secret', {
-  endpoint: 'https://pinger-processor.pingerchips.com/api',
+const pingerchips = new PingerchipsServer('app_key', 'app_secret', {
   mtls: {
     enabled: true,
-    cert: '/path/to/client-cert.pem',
+    cert: '/path/to/client-cert.pem',  // or PEM string directly
     key: '/path/to/client-key.pem',
-    ca: '/path/to/ca-cert.pem'
+    ca: '/path/to/ca-cert.pem',
+    rejectUnauthorized: true           // default — do not disable
   }
 });
 ```

package/index.js

@@ -3,164 +3,234 @@ import https from "https";
 import crypto from "crypto";
 
 class PingerchipsServer {
-  constructor(appId, appSecret, options = {}) {
-    this.appId = appId;
+  /**
+   * @param {string} appKey - App key (used for signing and routing)
+   * @param {string} appSecret - App secret (used for HMAC signing)
+   * @param {object} options
+   */
+  constructor(appKey, appSecret, options = {}) {
+    this.appKey = appKey;
     this.appSecret = appSecret;
-    this.appKey = options.appKey || appId; // App key for signing
     this.endpoint =
       options.endpoint ||
       process.env.PINGERCHIPS_API_ENDPOINT ||
-      process.env.NODE_ENV === "production"
-        ? "https://pinger-processor.pingerchips.com"
-        : "http://localhost:4000";
+      (process.env.NODE_ENV === "production"
+        ? "https://queue.pingerchips.com"
+        : "http://localhost:4000");
     this.token = options.token;
+    this.requestTimeout = options.requestTimeout || 10000;
+    this.retries = options.retries ?? 2; // retry 5xx up to N times
 
-    // mTLS configuration
     this.mtls = {
       enabled: options.mtls?.enabled || false,
       cert: options.mtls?.cert,
       key: options.mtls?.key,
       ca: options.mtls?.ca,
-      rejectUnauthorized: options.mtls?.rejectUnauthorized !== false,
+      rejectUnauthorized: options.mtls?.rejectUnauthorized ?? true,
     };
-
-    this.fetchPromise = import("node-fetch").then((mod) => mod.default);
   }
 
   _createHttpsAgent() {
-    if (!this.mtls.enabled) {
-      return undefined;
-    }
+    if (!this.mtls.enabled) return undefined;
 
     const agentOptions = {
       rejectUnauthorized: this.mtls.rejectUnauthorized,
     };
 
-    // Load cert, key, and ca - support both file paths and direct content
-    if (this.mtls.cert) {
-      agentOptions.cert = this._loadCertificate(this.mtls.cert);
-    }
-    if (this.mtls.key) {
-      agentOptions.key = this._loadCertificate(this.mtls.key);
-    }
-    if (this.mtls.ca) {
-      agentOptions.ca = this._loadCertificate(this.mtls.ca);
-    }
+    if (this.mtls.cert) agentOptions.cert = this._loadCertificate(this.mtls.cert);
+    if (this.mtls.key) agentOptions.key = this._loadCertificate(this.mtls.key);
+    if (this.mtls.ca) agentOptions.ca = this._loadCertificate(this.mtls.ca);
 
     return new https.Agent(agentOptions);
   }
 
   _loadCertificate(certOrPath) {
-    // If it looks like a certificate/key content (starts with -----), return as-is
-    if (
-      typeof certOrPath === "string" &&
-      certOrPath.trim().startsWith("-----")
-    ) {
+    if (typeof certOrPath === "string" && certOrPath.trim().startsWith("-----")) {
       return certOrPath;
     }
-    // Otherwise, treat as file path
     return fs.readFileSync(certOrPath, "utf8");
   }
 
+  _validateTriggerInput(channel, event, data) {
+    if (!channel || typeof channel !== "string") {
+      throw new TypeError("channel must be a non-empty string");
+    }
+    if (!event || typeof event !== "string") {
+      throw new TypeError("event must be a non-empty string");
+    }
+    if (channel.length > 200) {
+      throw new Error("channel name must be 200 characters or less");
+    }
+    if (event.length > 200) {
+      throw new Error("event name must be 200 characters or less");
+    }
+    try {
+      const serialized = JSON.stringify(data);
+      if (serialized.length > 65536) {
+        throw new Error("data payload must be 64KB or less");
+      }
+    } catch {
+      throw new TypeError("data must be JSON serializable");
+    }
+  }
+
+  _generateSignature(method, path, body) {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const bodyString = JSON.stringify(body);
+    const stringToSign = `${method}\n${path}\n${timestamp}\n${bodyString}`;
+
+    const signature = crypto
+      .createHmac("sha256", this.appSecret)
+      .update(stringToSign)
+      .digest("hex");
+
+    return { signature, timestamp };
+  }
+
+  async _fetchWithRetry(url, requestOptions, retriesLeft) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
+
+    try {
+      const response = await fetch(url, {
+        ...requestOptions,
+        signal: controller.signal,
+      });
+
+      // Retry on 5xx if retries remain
+      if (response.status >= 500 && retriesLeft > 0) {
+        return this._fetchWithRetry(url, requestOptions, retriesLeft - 1);
+      }
+
+      return response;
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw new Error(`Request timeout after ${this.requestTimeout}ms`);
+      }
+      // Retry on network errors
+      if (retriesLeft > 0) {
+        return this._fetchWithRetry(url, requestOptions, retriesLeft - 1);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Trigger an event on a channel.
+   * Uses HMAC-SHA256 signature authentication.
+   *
+   * @param {string} channel
+   * @param {string} event
+   * @param {any} data - Must be JSON serializable, max 64KB
+   * @returns {Promise<object>}
+   */
   async trigger(channel, event, data) {
-    const fetch = await this.fetchPromise;
-    const url = `${this.endpoint}/apps/${this.appId}/trigger`;
+    this._validateTriggerInput(channel, event, data);
+
+    const path = `/api/apps/${this.appKey}/trigger`;
+    const url = `${this.endpoint}${path}`;
+    const body = { channel, event, data };
+    const { signature, timestamp } = this._generateSignature("POST", path, body);
 
     const requestOptions = {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        token: this.token,
+        "X-App-Key": this.appKey,
+        "X-Signature": signature,
+        "X-Timestamp": timestamp.toString(),
       },
-      body: JSON.stringify({
-        app_id: this.appId,
-        app_secret: this.appSecret,
-        channel,
-        event,
-        data,
-      }),
+      body: JSON.stringify(body),
     };
 
-    // Add HTTPS agent if mTLS is enabled
+    if (this.token) {
+      requestOptions.headers["token"] = this.token;
+    }
+
     if (this.mtls.enabled) {
       requestOptions.agent = this._createHttpsAgent();
     }
 
-    const response = await fetch(url, requestOptions);
+    const response = await this._fetchWithRetry(url, requestOptions, this.retries);
 
     if (!response.ok) {
       const error = await response.json().catch(() => ({}));
       throw new Error(
-        `Failed to trigger event: ${response.statusText} - ${error.error || ""}`
+        `Failed to trigger event: ${response.status} ${response.statusText} - ${error.error || ""}`,
       );
     }
 
-    return await response.json();
+    return response.json();
   }
 
   /**
-   * Authenticate a user for a private or presence channel
-   *
-   * This method is called by your auth endpoint to sign user data.
-   * The signature proves that your server authorized the user to join the channel.
+   * Authenticate a user for a private or presence channel.
+   * Call this from your auth endpoint.
    *
    * @param {string} socketId - Socket ID from the client SDK
-   * @param {string} channelName - Channel name (e.g., "private-chat" or "presence-lobby")
-   * @param {object} userData - User data for presence channels (must include user_id)
-   * @returns {object} - Signed authentication data: { auth, channel_data? }
-   *
-   * @example
-   * // In your Express.js auth endpoint:
-   * app.post('/auth', (req, res) => {
-   *   const { socket_id, channel_name, auth_info } = req.body;
-   *
-   *   // Validate user from session/token
-   *   const user = req.session.user;
-   *   if (!user) return res.status(403).json({ error: 'Unauthorized' });
-   *
-   *   // For presence channels, provide user data
-   *   const userData = channel_name.startsWith('presence-') ? {
-   *     user_id: user.id,
-   *     user_info: { name: user.name, avatar: user.avatar }
-   *   } : null;
-   *
-   *   const authData = pingerchips.authenticate(socket_id, channel_name, userData);
-   *   res.json(authData);
-   * });
+   * @param {string} channelName - Must start with "private-" or "presence-"
+   * @param {object|null} userData - Required for presence channels, must include user_id
+   * @returns {{ auth: string, channel_data?: string, user_data?: string }}
    */
   authenticate(socketId, channelName, userData = null) {
-    // Build the full topic name
-    const fullTopic = `app:${this.appKey}:room:${channelName}`;
+    if (!socketId || typeof socketId !== "string") {
+      throw new TypeError("socketId must be a non-empty string");
+    }
+    if (!channelName || typeof channelName !== "string") {
+      throw new TypeError("channelName must be a non-empty string");
+    }
 
-    // Build string to sign based on channel type
+    const isPrivate = channelName.startsWith("private-");
+    const isPresence = channelName.startsWith("presence-");
+
+    if (!isPrivate && !isPresence) {
+      throw new Error(
+        "Public channels do not require authentication. Only private-* and presence-* channels need auth.",
+      );
+    }
+
+    if (isPresence && !userData) {
+      throw new Error(
+        "Presence channels require userData with at least user_id field",
+      );
+    }
+
+    if (userData) {
+      if (typeof userData !== "object" || userData === null) {
+        throw new TypeError("userData must be an object");
+      }
+      if (isPresence && !userData.user_id) {
+        throw new Error("userData must include user_id for presence channels");
+      }
+    }
+
+    const fullTopic = `app:${this.appKey}:room:${channelName}`;
+    let userDataString = null;
     let stringToSign;
-    let channelData = null;
 
-    if (userData && channelName.startsWith("presence-")) {
-      // Presence channel: include user data in signature
-      channelData = JSON.stringify(userData);
-      stringToSign = `${socketId}:${fullTopic}:${channelData}`;
+    if (userData) {
+      userDataString = JSON.stringify(userData);
+      stringToSign = `${socketId}:${fullTopic}:${userDataString}`;
     } else {
-      // Private channel: just socket_id and topic
       stringToSign = `${socketId}:${fullTopic}`;
     }
 
-    // Generate HMAC-SHA256 signature using app_secret
     const signature = crypto
       .createHmac("sha256", this.appSecret)
       .update(stringToSign)
       .digest("hex");
 
-    const auth = `${this.appKey}:${signature}`;
-
-    // Build response
-    const response = { auth };
+    const result = { auth: `${this.appKey}:${signature}` };
 
-    if (channelData) {
-      response.channel_data = channelData;
+    if (isPresence && userDataString) {
+      result.channel_data = userDataString;
+    } else if (userDataString) {
+      result.user_data = userDataString;
     }
 
-    return response;
+    return result;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pingerchips-js-server",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Pingerchips server SDK for Node.js - trigger events and authenticate users",
   "main": "index.js",
   "type": "module",
@@ -17,9 +17,7 @@
   ],
   "author": "Pingerchips",
   "license": "MIT",
-  "dependencies": {
-    "node-fetch": "^3.3.0"
-  },
+  "dependencies": {},
   "repository": {
     "type": "git",
     "url": "https://github.com/pingerchips/pingerchips-js-server"