pingerchips-js-server 2.1.1 → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # pingerchips-js-server
 
-Server-side SDK for Pingerchips. Trigger events and authenticate users for private/presence channels.
+Server-side SDK for Pingerchips. Trigger events, send push notifications, read
+and write Durable Objects, and issue capability tokens for browser clients.
 
 Requires Node.js 18+ (uses native `fetch`).
 
@@ -20,7 +21,12 @@ import PingerchipsServer from 'pingerchips-js-server';
 const pingerchips = new PingerchipsServer('app_key', 'app_secret');
 ```
 
-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.
+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.
+
+Every server call authenticates with `X-App-Key` / `X-App-Secret` headers. The
+App Secret is sent only to the Pingerchips backend — never to a browser.
 
 ### Trigger events
 
@@ -33,16 +39,30 @@ await pingerchips.trigger('lobby', 'new-message', {
 
 Failed requests are retried on 5xx and network errors (default: 2 retries).
 
-### Authenticate users (private/presence channels)
+## Authentication (ADR-0016 — unified capability tokens)
 
-Implement an auth endpoint on your server:
+Every WebSocket join — a private/presence channel, a Durable Object, or a chat
+thread — carries one `auth` token. Your backend mints it and returns it to the
+client SDK, which forwards it in the join params.
 
-```javascript
-import express from 'express';
+Two token forms:
+
+| Form | Minted by | Network call | Lifetime |
+|---|---|---|---|
+| **fast-path** `{appKey}.{payloadB64}.{sigB64}` | `authenticate`, `authenticateObject`, `authorize` | none (pure function) | no expiry |
+| **JWT** | `authenticateChat`, `issueToken` (`POST /api/auth`) | one round-trip | short-lived, has a `jti` |
+
+Capability grammar: `product:verb:resource`
 
-const app = express();
-app.use(express.json());
+| product | verbs | resource |
+|---|---|---|
+| `channel` | `subscribe`, `publish`, `presence` | channel name, `prefix*`, or `*` |
+| `object` | `read` | `{type}/{key}`, `{type}/*`, or `*` |
+| `chat` | `subscribe`, `publish:user_message`, `cancel_own`, `tool_approval` | thread id, `prefix*`, or `*` |
 
+### Private / presence channels
+
+```javascript
 app.post('/auth', (req, res) => {
   const { socket_id, channel_name, auth_info } = req.body;
 
@@ -50,22 +70,49 @@ app.post('/auth', (req, res) => {
   if (!user) return res.status(403).json({ error: 'Unauthorized' });
 
   const userData = channel_name.startsWith('presence-')
-    ? { user_id: user.id, user_info: { name: user.name } }
+    ? { user_id: user.id, name: user.name }
     : null;
 
-  const authData = pingerchips.authenticate(socket_id, channel_name, userData);
-  res.json(authData);
+  res.json(pingerchips.authenticate(socket_id, channel_name, userData));
 });
 ```
 
-Configure the client to use it:
-
 ```javascript
 const client = new Pingerchips('app_key', {
   authEndpoint: 'https://your-server.com/auth'
 });
 ```
 
+### Many grants on one token
+
+```javascript
+const { auth } = pingerchips.authorize(socketId, {
+  channels: ['orders', 'shipments'],
+  presence: ['lobby'],
+  objects:  [{ type: 'order', key: 'order-42' }],
+  threads:  ['thread-abc'],
+}, clientId);
+```
+
+### Chat threads (server-issued JWT)
+
+```javascript
+// full client capability set for the thread
+const { auth } = await pingerchips.authenticateChat(socketId, threadId, clientId);
+
+// narrowed — read-only
+const { auth } = await pingerchips.authenticateChat(
+  socketId, threadId, clientId, ['subscribe']
+);
+```
+
+### Durable Objects (browser subscription token)
+
+```javascript
+const { auth } = pingerchips.authenticateObject(socketId, 'order', 'order-42');
+// grants object:read:order/order-42 bound to socketId
+```
+
 ## API
 
 ### `new PingerchipsServer(appKey, appSecret, options?)`
@@ -73,7 +120,7 @@ const client = new Pingerchips('app_key', {
 | Parameter | Type | Description |
 |---|---|---|
 | `appKey` | string | Your app key |
-| `appSecret` | string | Your app secret — used for HMAC signing, never sent over the wire |
+| `appSecret` | string | Your app secret — sent only to the Pingerchips backend |
 
 **Options:**
 
@@ -82,44 +129,57 @@ const client = new Pingerchips('app_key', {
 | `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)`
 
-Trigger an event on a channel.
-
 - `channel` — max 200 chars
 - `event` — max 200 chars
-- `data` — must be JSON serializable, max 64KB
+- `data` — JSON serializable, max 64KB
 
-```javascript
-await pingerchips.trigger('room-42', 'message', { text: 'hi' });
-```
+### `notify(userId, { title, body }, options?)`
 
-### `authenticate(socketId, channelName, userData?)`
+Send a push notification. `options.trigger` is `"offline"` (default, skipped if
+the user is connected) or `"always"`.
 
-Sign a channel auth request. Call from your auth endpoint.
+### `registerPushToken(userId, device)` / `unregisterPushToken(userId, deviceId)`
 
-- `channelName` must start with `private-` or `presence-`
-- `userData` required for presence channels, must include `user_id`
+Server-side device token management.
 
-```javascript
-// 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\",...}" }
-```
+### `authenticate(socketId, channelName, userData?)` → `{ auth, channel_data? }`
 
-## mTLS
+Fast-path token for one `private-` / `presence-` channel.
+
+### `authorize(socketId, grants, clientId?)` → `{ auth }`
+
+Fast-path token for many grants. `grants`: `{ channels?, presence?, publish?,
+objects?, threads?, capabilities? }`.
+
+### `authenticateChat(socketId, threadId, clientId, verbs?)` → `Promise<{ auth }>`
+
+Server-issued JWT via `POST /api/auth` for a chat thread. `verbs` narrows the
+grant (short verbs or fully-qualified `chat:{verb}:{threadId}` strings).
 
-For secure server-to-server communication:
+### `issueToken(socketId, clientId, grants)` → `Promise<{ auth }>`
+
+Server-issued JWT for an arbitrary grant set (same shape as `authorize`).
+
+### `authenticateObject(socketId, objectType, objectKey)` → `{ auth }`
+
+Fast-path token granting `object:read:{type}/{key}`.
+
+### `object(type, key)` → `DurableObjectHandle`
+
+HTTP client for a Durable Object: `.state()`, `.get(slot)`, `.set(slot, value)`,
+`.setAll(map)`, `.increment(slot, by?)`, `.append(slot, value)`,
+`.delete(slot)`, `.transaction(ops)`, `.log(afterId?)`, `.purge()`.
+
+### `PingerchipsServerChat`
+
+Server-side chat REST API (threads, participants, messages). Authenticates with
+`X-App-Key` / `X-App-Secret`.
+
+## mTLS
 
 ```javascript
 const pingerchips = new PingerchipsServer('app_key', 'app_secret', {
@@ -133,6 +193,18 @@ const pingerchips = new PingerchipsServer('app_key', 'app_secret', {
 });
 ```
 
+## Migrating from 2.x
+
+- App credentials moved from request bodies / HMAC signatures to `X-App-Key` /
+  `X-App-Secret` headers. No code change if you only call `trigger` / `notify`.
+- `authenticate()` now returns a capability token instead of an
+  `{appKey}:{hmac}` string. The client SDK forwards it unchanged — no client
+  change needed.
+- `authenticateChat()` calls `POST /api/auth` (was `/api/chat/auth`) and takes
+  chat *verbs* to narrow, not raw capability strings.
+- `authenticateObject()` returns a capability token, not an HMAC string.
+- New: `authorize()` and `issueToken()` for multi-grant tokens.
+
 ## License
 
 MIT

package/agent-session.js

@@ -0,0 +1,212 @@
+import { Socket } from "phoenix";
+
+// ---------------------------------------------------------------------------
+// AgentSession
+// ---------------------------------------------------------------------------
+
+/**
+ * AgentSession — connects an agent process to a chat thread over WebSocket.
+ *
+ * Usage (in your agent HTTP handler):
+ *
+ *   import { AgentSession } from "pingerchips-js-server/agent-session.js";
+ *
+ *   const agent = new AgentSession(appKey, appSecret);
+ *   const session = await agent.connect(threadId, "agent-1");
+ *   const run = session.createRun(runId);   // runId from HTTP invocation body
+ *
+ *   await run.start();
+ *   const messages = await run.loadConversation();
+ *   // ... call LLM, stream tokens ...
+ *   await run.write(accumulatedContent);
+ *   await run.end("complete");
+ *
+ *   session.close();
+ */
+export class AgentSession {
+  constructor(appKey, appSecret, options = {}) {
+    if (!appKey)    throw new Error("appKey required");
+    if (!appSecret) throw new Error("appSecret required");
+
+    this._appKey    = appKey;
+    this._appSecret = appSecret;
+    this._options   = options;
+  }
+
+  /**
+   * @param {string} threadId
+   * @param {string} agentId
+   * @returns {Promise<AgentThreadSession>}
+   */
+  async connect(threadId, agentId) {
+    if (!agentId) throw new Error("agentId required");
+
+    const endpoint = this._options.endpoint ||
+      process.env.PINGERCHIPS_ENDPOINT ||
+      (process.env.NODE_ENV === "production"
+        ? "wss://queue.pingerchips.com/socket"
+        : "ws://localhost:4000/socket");
+
+    const socket = new Socket(endpoint, { params: { app_key: this._appKey } });
+    socket.connect();
+
+    const topic      = `chat:v1:app:${this._appKey}:thread:${threadId}`;
+    const joinParams = { secret: this._appSecret, agent_id: agentId };
+    const channel    = socket.channel(topic, joinParams);
+
+    return new Promise((resolve, reject) => {
+      channel
+        .join()
+        .receive("ok", (resp) => {
+          resolve(new AgentThreadSession(channel, threadId, socket));
+        })
+        .receive("error", (resp) => {
+          socket.disconnect();
+          reject(new Error(`AgentSession join failed: ${JSON.stringify(resp)}`));
+        });
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AgentThreadSession
+// ---------------------------------------------------------------------------
+
+class AgentThreadSession {
+  constructor(channel, threadId, socket) {
+    this._channel  = channel;
+    this._threadId = threadId;
+    this._socket   = socket;
+    this._runs     = new Set();
+  }
+
+  /**
+   * Create a Run handle for the given runId (from the HTTP invocation body).
+   * @param {string} runId
+   * @returns {Run}
+   */
+  createRun(runId) {
+    if (!runId) throw new Error("runId required");
+    const run = new Run(runId, this._channel, this._threadId, () => {
+      this._runs.delete(run);
+    });
+    this._runs.add(run);
+    return run;
+  }
+
+  close() {
+    for (const run of this._runs) run.close();
+    this._runs.clear();
+    this._channel.leave();
+    this._socket.disconnect();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+class Run {
+  constructor(runId, channel, threadId, onClose) {
+    this.runId      = runId;
+    this._channel   = channel;
+    this._threadId  = threadId;
+    this._abortCtrl = new AbortController();
+    this._onClose   = onClose;
+
+    // Agent listens for cancel pushes from clients on the run-specific PubSub topic.
+    // The channel forwards tool_approval via PubSub — handled separately.
+    this._runEndRef = channel.on("run:end", ({ runId: endedRunId }) => {
+      if (endedRunId !== runId) return;
+      this._abortCtrl.abort();
+      this.close();
+    });
+  }
+
+  /** AbortSignal that fires when this run is cancelled. */
+  get abortSignal() {
+    return this._abortCtrl.signal;
+  }
+
+  /**
+   * Mark the run as active. Transitions pending → active in WAL.
+   * @param {string} ownerClientId — the client who sent the message
+   * @returns {Promise<void>}
+   */
+  start(ownerClientId) {
+    return this._push("run:start", { runId: this.runId, ownerClientId });
+  }
+
+  /**
+   * Load the active branch of the conversation for passing to the LLM.
+   * Returns messages in the current branch (follows parentId from last_message_id).
+   * @returns {Promise<object[]>}
+   */
+  loadConversation() {
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push("load_older", { beforeMessageId: "__all__", limit: 500 })
+        .receive("ok", ({ messages }) => resolve(messages))
+        .receive("error", (e) => reject(new Error(e.reason || "loadConversation failed")));
+    });
+  }
+
+  /**
+   * Write accumulated token content to the stream slot.
+   * Pass the full accumulated string on every call, not just the new token.
+   * @param {string} content — full accumulated content so far
+   * @returns {Promise<void>}
+   */
+  write(content) {
+    return this._push("run:token", { runId: this.runId, content });
+  }
+
+  /**
+   * End the run and trigger GC compaction.
+   * @param {"complete"|"cancelled"|"error"} reason
+   * @returns {Promise<void>}
+   */
+  async end(reason = "complete") {
+    try {
+      return await this._push("run:end", { runId: this.runId, reason });
+    } finally {
+      this.close();
+    }
+  }
+
+  /**
+   * Suspend the run pending human tool approval.
+   * @param {{ toolCallId: string, toolName: string, args: object }} toolInfo
+   * @returns {Promise<void>}
+   */
+  suspend({ toolCallId, toolName, args }) {
+    return this._push("run:suspend", { runId: this.runId, toolCallId, toolName, args });
+  }
+
+  /**
+   * Resume a suspended run after tool approval.
+   * @returns {Promise<void>}
+   */
+  resume() {
+    return this._push("run:resume", { runId: this.runId });
+  }
+
+  _push(event, payload) {
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push(event, payload)
+        .receive("ok", resolve)
+        .receive("error", (e) => reject(new Error(e.reason || `${event} failed`)));
+    });
+  }
+
+  close() {
+    if (this._runEndRef == null) return;
+    this._channel.off("run:end", this._runEndRef);
+    this._runEndRef = null;
+    this._onClose?.();
+    this._onClose = null;
+  }
+}
+
+export { AgentThreadSession, Run };

package/index.js

@@ -2,10 +2,65 @@ import fs from "fs";
 import https from "https";
 import crypto from "crypto";
 
+// ---------------------------------------------------------------------------
+// Unified capability tokens (ADR-0016)
+//
+// Every WebSocket join — PubSub channel, Durable Object, or chat thread —
+// carries one `auth` token. Two forms:
+//
+//   * fast-path token: "{appKey}.{payloadB64}.{sigB64}", a pure function of
+//     (appSecret, socketId, capabilities). No network round-trip, no expiry.
+//     Minted here for private/presence channels and Durable Objects.
+//
+//   * JWT: issued by POST /api/auth. Scoped, short-lived, has a jti. Used for
+//     chat threads (authenticateChat) and any case that wants server-side
+//     issuance / auditing.
+//
+// Capability grammar: "product:verb:resource"
+//   product  channel | object | chat
+//   verb     channel: subscribe | publish | presence
+//            object:  read
+//            chat:    subscribe | publish:user_message | cancel_own | tool_approval
+//   resource an exact string, a "prefix*" wildcard, or "*"
+// ---------------------------------------------------------------------------
+
+const b64url = (buf) => Buffer.from(buf).toString("base64url");
+
+/**
+ * Mint a fast-path capability token bound to one socket.
+ *
+ * @param {string} appKey
+ * @param {string} appSecret
+ * @param {string} socketId
+ * @param {string[]} capabilities - non-empty list of "product:verb:resource"
+ * @param {string} [clientId]     - optional, echoed in the token payload
+ * @returns {string} "{appKey}.{payloadB64}.{sigB64}"
+ */
+function mintFastToken(appKey, appSecret, socketId, capabilities, clientId) {
+  if (!socketId || typeof socketId !== "string") {
+    throw new TypeError("socketId must be a non-empty string");
+  }
+  if (!Array.isArray(capabilities) || capabilities.length === 0) {
+    throw new TypeError("capabilities must be a non-empty array");
+  }
+
+  const payload = { socket_id: socketId, capabilities };
+  if (clientId != null) payload.client_id = clientId;
+
+  const payloadB64 = b64url(JSON.stringify(payload));
+  const signingInput = `${appKey}.${payloadB64}`;
+  const sigB64 = crypto
+    .createHmac("sha256", appSecret)
+    .update(signingInput)
+    .digest("base64url");
+
+  return `${appKey}.${payloadB64}.${sigB64}`;
+}
+
 class PingerchipsServer {
   /**
-   * @param {string} appKey - App key (used for signing and routing)
-   * @param {string} appSecret - App secret (used for HMAC signing)
+   * @param {string} appKey - App key used for authentication and routing
+   * @param {string} appSecret - App secret used for server authentication
    * @param {object} options
    */
   constructor(appKey, appSecret, options = {}) {
@@ -17,7 +72,6 @@ class PingerchipsServer {
       (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
 
@@ -74,22 +128,19 @@ class PingerchipsServer {
     }
   }
 
-  _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 };
+  /** Headers every server-to-server call carries (ADR-0016). */
+  _authHeaders() {
+    return {
+      "Content-Type": "application/json",
+      "X-App-Key": this.appKey,
+      "X-App-Secret": this.appSecret,
+    };
   }
 
   async _fetchWithRetry(url, requestOptions, retriesLeft) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
+    const attempt = this.retries - retriesLeft;
 
     try {
       const response = await fetch(url, {
@@ -99,6 +150,9 @@ class PingerchipsServer {
 
       // Retry on 5xx if retries remain
       if (response.status >= 500 && retriesLeft > 0) {
+        clearTimeout(timeoutId);
+        const delay = Math.min(100 * 2 ** attempt, 5000);
+        await new Promise((r) => setTimeout(r, delay));
         return this._fetchWithRetry(url, requestOptions, retriesLeft - 1);
       }
 
@@ -109,6 +163,8 @@ class PingerchipsServer {
       }
       // Retry on network errors
       if (retriesLeft > 0) {
+        const delay = Math.min(100 * 2 ** attempt, 5000);
+        await new Promise((r) => setTimeout(r, delay));
         return this._fetchWithRetry(url, requestOptions, retriesLeft - 1);
       }
       throw err;
@@ -118,8 +174,8 @@ class PingerchipsServer {
   }
 
   /**
-   * Trigger an event on a channel.
-   * Uses HMAC-SHA256 signature authentication.
+   * Trigger an event on a channel. Authenticated with X-App-Key / X-App-Secret
+   * headers (ADR-0016).
    *
    * @param {string} channel
    * @param {string} event
@@ -132,23 +188,13 @@ class PingerchipsServer {
     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",
-        "X-App-Key": this.appKey,
-        "X-Signature": signature,
-        "X-Timestamp": timestamp.toString(),
-      },
+      headers: this._authHeaders(),
       body: JSON.stringify(body),
     };
 
-    if (this.token) {
-      requestOptions.headers["token"] = this.token;
-    }
-
     if (this.mtls.enabled) {
       requestOptions.agent = this._createHttpsAgent();
     }
@@ -166,8 +212,140 @@ class PingerchipsServer {
   }
 
   /**
-   * Authenticate a user for a private or presence channel.
-   * Call this from your auth endpoint.
+   * Send a push notification to a specific user.
+   *
+   * @param {string} userId
+   * @param {object} notification
+   * @param {string} notification.title
+   * @param {string} notification.body
+   * @param {object} [options]
+   * @param {"always"|"offline"} [options.trigger="offline"] - "offline" skips if user is connected
+   * @param {object} [options.data] - Extra key/value data sent with the notification
+   * @returns {Promise<object>}
+   */
+  async notify(userId, { title, body }, options = {}) {
+    if (!userId) throw new TypeError("userId is required");
+    if (!title || !body) throw new TypeError("notification.title and notification.body are required");
+
+    const path = `/api/apps/${this.appKey}/push/notify`;
+    const url = `${this.endpoint}${path}`;
+    const reqBody = {
+      user_id: userId,
+      title,
+      body,
+      trigger: options.trigger ?? "offline",
+      data: options.data ?? {},
+    };
+    const response = await this._fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this._authHeaders(),
+        body: JSON.stringify(reqBody),
+      },
+      this.retries
+    );
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(`notify failed: ${response.status} ${error.error || ""}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Register a push device token on behalf of a user.
+   * Useful for server-side token registration (e.g. from a mobile backend).
+   *
+   * @param {string} userId
+   * @param {object} device
+   * @param {string} device.deviceId
+   * @param {"fcm"|"web_fcm"|"apns"|"web"} device.platform
+   * @param {string} [device.token]    - FCM or APNs token
+   * @param {string} [device.endpoint] - Web Push endpoint
+   * @param {string} [device.p256dh]   - Web Push p256dh key
+   * @param {string} [device.auth]     - Web Push auth secret
+   */
+  async registerPushToken(userId, { deviceId, platform, token, endpoint, p256dh, auth }) {
+    const path = `/api/apps/${this.appKey}/push/register`;
+    const url = `${this.endpoint}${path}`;
+    const reqBody = {
+      user_id: userId,
+      device_id: deviceId,
+      platform,
+      token,
+      endpoint,
+      p256dh,
+      auth,
+    };
+    const response = await this._fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this._authHeaders(),
+        body: JSON.stringify(reqBody),
+      },
+      this.retries
+    );
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(`registerPushToken failed: ${response.status} ${error.error || ""}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Unregister a push device token.
+   */
+  async unregisterPushToken(userId, deviceId) {
+    const path = `/api/apps/${this.appKey}/push/register`;
+    const url = `${this.endpoint}${path}`;
+    const reqBody = { user_id: userId, device_id: deviceId };
+
+    const response = await this._fetchWithRetry(
+      url,
+      {
+        method: "DELETE",
+        headers: this._authHeaders(),
+        body: JSON.stringify(reqBody),
+      },
+      this.retries
+    );
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(`unregisterPushToken failed: ${response.status} ${error.error || ""}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Trigger the same event on multiple channels in parallel.
+   *
+   * @param {string[]} channels
+   * @param {string} event
+   * @param {any} data
+   * @returns {Promise<object[]>} — one result per channel, in order
+   */
+  async triggerBatch(channels, event, data) {
+    if (!Array.isArray(channels) || channels.length === 0) {
+      throw new TypeError("channels must be a non-empty array");
+    }
+    return Promise.all(channels.map((ch) => this.trigger(ch, event, data)));
+  }
+
+  /**
+   * Authenticate a client for a private or presence channel. Call this from
+   * your auth endpoint and return the result to the client SDK.
+   *
+   * Mints a fast-path capability token (ADR-0016) granting
+   * `channel:subscribe:{channelName}` — and, for presence channels,
+   * `channel:presence:{channelName}` — bound to `socketId`. No network call;
+   * the App Secret never leaves your server.
    *
    * @param {string} socketId - Socket ID from the client SDK
    * @param {string} channelName - Must start with "private-" or "presence-"
@@ -206,32 +384,557 @@ class PingerchipsServer {
       }
     }
 
-    const fullTopic = `app:${this.appKey}:room:${channelName}`;
-    let userDataString = null;
-    let stringToSign;
+    const capabilities = [`channel:subscribe:${channelName}`];
+    if (isPresence) capabilities.push(`channel:presence:${channelName}`);
+
+    const auth = mintFastToken(
+      this.appKey,
+      this.appSecret,
+      socketId,
+      capabilities,
+      userData?.user_id,
+    );
+
+    const result = { auth };
 
     if (userData) {
-      userDataString = JSON.stringify(userData);
-      stringToSign = `${socketId}:${fullTopic}:${userDataString}`;
-    } else {
-      stringToSign = `${socketId}:${fullTopic}`;
+      const userDataString = JSON.stringify(userData);
+      if (isPresence) result.channel_data = userDataString;
+      else result.user_data = userDataString;
+    }
+
+    return result;
+  }
+
+  /**
+   * Mint a fast-path capability token for an arbitrary set of channels /
+   * objects / threads in one call. Use this when a client needs several
+   * subscriptions off one token.
+   *
+   * @param {string} socketId
+   * @param {{
+   *   channels?: string[],   // -> channel:subscribe:{name}
+   *   presence?: string[],   // -> channel:subscribe + channel:presence
+   *   publish?:  string[],   // -> channel:publish:{name}
+   *   objects?:  Array<{type: string, key: string}>, // -> object:read:{type}/{key}
+   *   threads?:  string[],   // -> chat:subscribe + chat:publish:user_message + chat:cancel_own + chat:tool_approval
+   *   capabilities?: string[], // raw "product:verb:resource" strings, appended as-is
+   * }} grants
+   * @param {string} [clientId]
+   * @returns {{ auth: string }}
+   */
+  authorize(socketId, grants = {}, clientId) {
+    const caps = [];
+
+    for (const name of grants.channels ?? []) caps.push(`channel:subscribe:${name}`);
+    for (const name of grants.presence ?? []) {
+      caps.push(`channel:subscribe:${name}`, `channel:presence:${name}`);
+    }
+    for (const name of grants.publish ?? []) caps.push(`channel:publish:${name}`);
+    for (const { type, key } of grants.objects ?? []) {
+      caps.push(`object:read:${type}/${key}`);
     }
+    for (const threadId of grants.threads ?? []) {
+      caps.push(
+        `chat:subscribe:${threadId}`,
+        `chat:publish:user_message:${threadId}`,
+        `chat:cancel_own:${threadId}`,
+        `chat:tool_approval:${threadId}`,
+      );
+    }
+    for (const raw of grants.capabilities ?? []) caps.push(raw);
 
-    const signature = crypto
-      .createHmac("sha256", this.appSecret)
-      .update(stringToSign)
-      .digest("hex");
+    if (caps.length === 0) {
+      throw new Error(
+        "authorize: pass at least one of channels / presence / publish / objects / threads / capabilities",
+      );
+    }
 
-    const result = { auth: `${this.appKey}:${signature}` };
+    return {
+      auth: mintFastToken(this.appKey, this.appSecret, socketId, caps, clientId),
+    };
+  }
 
-    if (isPresence && userDataString) {
-      result.channel_data = userDataString;
-    } else if (userDataString) {
-      result.user_data = userDataString;
+  // Full client capability set for a chat thread (ADR-0016).
+  static chatThreadCapabilities(threadId) {
+    return [
+      `chat:subscribe:${threadId}`,
+      `chat:publish:user_message:${threadId}`,
+      `chat:cancel_own:${threadId}`,
+      `chat:tool_approval:${threadId}`,
+    ];
+  }
+
+  /**
+   * Request a short-lived JWT capability token for a client joining a chat
+   * thread. Calls POST /api/auth with X-App-Key / X-App-Secret; the App Secret
+   * is sent only to the Pingerchips backend.
+   *
+   * @param {string} socketId
+   * @param {string} threadId
+   * @param {string} clientId
+   * @param {string[]} [verbs] - Optional subset of chat verbs to narrow the
+   *   grant. Accepts short verbs ("subscribe", "publish:user_message",
+   *   "cancel_own", "tool_approval") or already-qualified
+   *   "chat:{verb}:{threadId}" strings. Omit for the full client set.
+   * @returns {Promise<{ auth: string }>}
+   */
+  async authenticateChat(socketId, threadId, clientId, verbs) {
+    if (!socketId || !threadId || !clientId) {
+      throw new TypeError("socketId, threadId, and clientId are required");
+    }
+    if (verbs !== undefined && !Array.isArray(verbs)) {
+      throw new TypeError("verbs must be an array when provided");
+    }
+
+    const capabilities =
+      verbs === undefined
+        ? PingerchipsServer.chatThreadCapabilities(threadId)
+        : verbs.map((v) =>
+            v.startsWith("chat:") ? v : `chat:${v}:${threadId}`,
+          );
+
+    const body = {
+      socket_id: socketId,
+      client_id: clientId,
+      capabilities,
+    };
+
+    const response = await this._fetchWithRetry(
+      `${this.endpoint}/api/auth`,
+      {
+        method: "POST",
+        headers: this._authHeaders(),
+        body: JSON.stringify(body),
+      },
+      this.retries,
+    );
+
+    const result = await response.json().catch(() => null);
+
+    if (!response.ok) {
+      const detail =
+        result?.error || result?.errors?.[0]?.detail || response.statusText;
+      throw new Error(`Chat auth failed (${response.status}): ${detail}`);
     }
 
     return result;
   }
+
+  /**
+   * Request a JWT capability token for an arbitrary set of grants via
+   * POST /api/auth. Same grant shape as `authorize()`, but server-issued
+   * (scoped, short-lived, has a jti) instead of a pure fast-path token.
+   *
+   * @param {string} socketId
+   * @param {string} clientId
+   * @param {object} grants - see `authorize()`
+   * @returns {Promise<{ auth: string }>}
+   */
+  async issueToken(socketId, clientId, grants = {}) {
+    if (!socketId || !clientId) {
+      throw new TypeError("socketId and clientId are required");
+    }
+
+    // Reuse authorize()'s grant→capability mapping without minting a token.
+    const { auth: fastToken } = this.authorize(socketId, grants, clientId);
+    const payloadB64 = fastToken.split(".")[1];
+    const { capabilities } = JSON.parse(
+      Buffer.from(payloadB64, "base64url").toString("utf8"),
+    );
+
+    const response = await this._fetchWithRetry(
+      `${this.endpoint}/api/auth`,
+      {
+        method: "POST",
+        headers: this._authHeaders(),
+        body: JSON.stringify({
+          socket_id: socketId,
+          client_id: clientId,
+          capabilities,
+        }),
+      },
+      this.retries,
+    );
+
+    const result = await response.json().catch(() => null);
+
+    if (!response.ok) {
+      const detail =
+        result?.error || result?.errors?.[0]?.detail || response.statusText;
+      throw new Error(`Token issuance failed (${response.status}): ${detail}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Returns a DurableObjectHandle for reading/writing a durable object.
+   *
+   * @param {string} type   - Object type (e.g. "thread")
+   * @param {string} key    - Object key (e.g. thread UUID)
+   * @returns {DurableObjectHandle}
+   */
+  object(type, key) {
+    return new DurableObjectHandle(this, type, key);
+  }
+
+  /**
+   * Mint a fast-path capability token for a browser client to subscribe to a
+   * Durable Object over the socket. Call this from your auth endpoint — the
+   * App Secret never reaches the browser.
+   *
+   * The token grants `object:read:{type}/{key}` bound to one socket. A token
+   * for `order/order-42` cannot be used to subscribe to `order/order-99`.
+   *
+   * @param {string} socketId    - The client's socket id.
+   * @param {string} objectType  - Object type.
+   * @param {string} objectKey   - Object key.
+   * @returns {{ auth: string }}  - `{ auth: "{appKey}.{payloadB64}.{sigB64}" }`
+   */
+  authenticateObject(socketId, objectType, objectKey) {
+    if (!socketId || typeof socketId !== "string") {
+      throw new TypeError("socketId must be a non-empty string");
+    }
+    if (!objectType || typeof objectType !== "string") {
+      throw new TypeError("objectType must be a non-empty string");
+    }
+    if (!objectKey || typeof objectKey !== "string") {
+      throw new TypeError("objectKey must be a non-empty string");
+    }
+
+    return {
+      auth: mintFastToken(this.appKey, this.appSecret, socketId, [
+        `object:read:${objectType}/${objectKey}`,
+      ]),
+    };
+  }
+}
+
+export { mintFastToken };
+
+// ---------------------------------------------------------------------------
+// DurableObjectHandle — HTTP client for /api/v1/objects
+//
+// Auth: X-App-Key + X-App-Secret headers (ADR-0016). The path's app_id
+// segment may be the app key or the app id; the server resolves either.
+// ---------------------------------------------------------------------------
+
+class DurableObjectHandle {
+  constructor(server, type, key) {
+    this._server = server;
+    this._type = type;
+    this._key = key;
+  }
+
+  _basePath() {
+    const s = this._server;
+    return `/api/v1/objects/${encodeURIComponent(s.appKey)}/${encodeURIComponent(this._type)}/${encodeURIComponent(this._key)}`;
+  }
+
+  async _req(method, path, body) {
+    const bodyStr = body !== undefined ? JSON.stringify(body) : undefined;
+
+    const res = await this._server._fetchWithRetry(
+      `${this._server.endpoint}${path}`,
+      {
+        method,
+        headers: this._server._authHeaders(),
+        body: bodyStr,
+      },
+      this._server.retries
+    );
+
+    if (res.status === 204) return null;
+
+    const json = await res.json().catch(() => null);
+    if (!res.ok) {
+      const detail = json?.error || res.statusText;
+      throw new Error(`DurableObject ${method} ${path} failed (${res.status}): ${detail}`);
+    }
+    return json;
+  }
+
+  /** Full state snapshot + log_id */
+  async state() {
+    return this._req("GET", this._basePath());
+  }
+
+  /** Get a single slot value */
+  async get(slot) {
+    const res = await this._req("GET", `${this._basePath()}/${encodeURIComponent(slot)}`);
+    return res?.value;
+  }
+
+  /** Set a single slot */
+  async set(slot, value) {
+    return this._req("PUT", `${this._basePath()}/${encodeURIComponent(slot)}`, { value });
+  }
+
+  /** Set multiple slots atomically */
+  async setAll(map) {
+    return this._req("PATCH", this._basePath(), map);
+  }
+
+  /** POST /api/v1/objects/{appKey}/{type}/{key}/increment with { slot, by } */
+  async increment(slot, by = 1) {
+    return this._req("POST", `${this._basePath()}/increment`, { slot, by });
+  }
+
+  /** POST /api/v1/objects/{appKey}/{type}/{key}/append with { slot, value } */
+  async append(slot, value) {
+    return this._req("POST", `${this._basePath()}/append`, { slot, value });
+  }
+
+  /** Delete a slot */
+  async delete(slot) {
+    return this._req("DELETE", `${this._basePath()}/${encodeURIComponent(slot)}`);
+  }
+
+  /**
+   * Run a transaction.
+   * @param {Array<{op: "set"|"delete"|"increment"|"append", key: string, value?: any, by?: number}>} ops
+   */
+  async transaction(ops) {
+    return this._req("POST", `${this._basePath()}/transaction`, ops);
+  }
+
+  /**
+   * Replay log entries after a given log_id.
+   * @param {number} [afterId=0]
+   */
+  async log(afterId = 0) {
+    const path = `${this._basePath()}/log?after=${afterId}`;
+    return this._req("GET", path);
+  }
+
+  /** Purge the entire durable object (204 No Content) */
+  async purge() {
+    return this._req("DELETE", this._basePath());
+  }
 }
 
 export default PingerchipsServer;
+
+// ---------------------------------------------------------------------------
+// ChannelConfig — typed builder for flow_spec channel feature flags
+//
+// These flags are stored in the flow spec and read by the server on every
+// broadcast. Pass the result as the `flow_spec` when creating/updating a flow.
+//
+// Flags (all optional, server defaults shown):
+//   durable             false  — WAL append + ClickHouse flush after broadcast
+//   replay              true   — buffer last N messages for reconnect recovery
+//   max_replay_messages 200    — ring buffer size (when durable=false)
+//   ordering            strict — "best-effort" skips Horde, broadcasts directly
+//   flow_engine         true   — false = skip Executor, passthrough broadcast
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a channel config / flow_spec with durability and replay settings.
+ *
+ * @param {object} opts
+ * @param {boolean} [opts.durable=false]             — Persist events to WAL + ClickHouse
+ * @param {boolean} [opts.replay=true]               — Buffer messages for reconnect recovery
+ * @param {number}  [opts.maxReplayMessages=200]      — Replay buffer ring size
+ * @param {"strict"|"best-effort"} [opts.ordering="strict"]
+ * @param {boolean} [opts.flowEngine=true]           — Enable flow/transform execution
+ * @returns {object} flow_spec-compatible config object
+ */
+export function channelConfig({
+  durable = false,
+  replay = true,
+  maxReplayMessages = 200,
+  ordering = "strict",
+  flowEngine = true,
+} = {}) {
+  return {
+    durable,
+    replay,
+    max_replay_messages: maxReplayMessages,
+    ordering,
+    flow_engine: flowEngine,
+  };
+}
+
+/**
+ * Preset: durable channel — WAL + ClickHouse, strict ordering, full replay.
+ * Use for financial events, audit logs, or anything that must not be lost.
+ */
+export const durableChannelConfig = () =>
+  channelConfig({ durable: true, replay: true, ordering: "strict" });
+
+/**
+ * Preset: ephemeral channel — no WAL, no replay, best-effort ordering.
+ * Use for high-frequency metrics, cursor positions, typing indicators.
+ */
+export const ephemeralChannelConfig = () =>
+  channelConfig({ durable: false, replay: false, ordering: "best-effort", flowEngine: false });
+
+/**
+ * PingerchipsServerChat — server-side chat REST API.
+ *
+ * Requires app_key + app_secret. Never use in client/browser code.
+ * Calls /api/chat with X-App-Key + X-App-Secret headers.
+ *
+ * Usage:
+ *   const chat = new PingerchipsServerChat(appKey, appSecret);
+ *   const thread = await chat.createThread({ title: "Support", createdBy: "user_1" });
+ *   await chat.joinThread(thread.id, { userId: "user_1", type: "human" });
+ *   await chat.sendMessage(thread.id, { userId: "user_1", sender: { name: "Alice" }, content: { text: "Hello" } });
+ */
+export class PingerchipsServerChat {
+  /**
+   * @param {string} appKey
+   * @param {string} appSecret
+   * @param {Object} [options]
+   * @param {string} [options.endpoint] - base URL, defaults to https://queue.pingerchips.com
+   */
+  constructor(appKey, appSecret, options = {}) {
+    if (!appKey) throw new Error("appKey required");
+    if (!appSecret) throw new Error("appSecret required");
+
+    this.appKey = appKey;
+    this.appSecret = appSecret;
+    this.endpoint = (
+      options.endpoint ||
+      process.env.PINGERCHIPS_API_ENDPOINT ||
+      (process.env.NODE_ENV === "production"
+        ? "https://queue.pingerchips.com"
+        : "http://localhost:4000")
+    ).replace(/\/$/, "");
+  }
+
+  _headers() {
+    return {
+      "Content-Type": "application/vnd.api+json",
+      Accept: "application/vnd.api+json",
+      "X-App-Key": this.appKey,
+      "X-App-Secret": this.appSecret,
+    };
+  }
+
+  async _request(method, path, body) {
+    const res = await fetch(`${this.endpoint}/api/chat${path}`, {
+      method,
+      headers: this._headers(),
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    const json = await res.json().catch(() => null);
+
+    if (!res.ok) {
+      const detail = json?.errors?.[0]?.detail || json?.errors?.[0]?.title || res.statusText;
+      throw new Error(`Chat API ${method} ${path} failed (${res.status}): ${detail}`);
+    }
+
+    return json;
+  }
+
+  _wrap(type, attrs) {
+    return { data: { type, attributes: attrs } };
+  }
+
+  _unwrap(json) {
+    if (!json?.data) return json;
+    const d = json.data;
+    if (Array.isArray(d)) return d.map((r) => ({ id: r.id, ...r.attributes }));
+    return { id: d.id, ...d.attributes };
+  }
+
+  // ─── Threads ─────────────────────────────────────────────────────────────────
+
+  async createThread({ title, type = "group", createdBy, botId, retentionDays, metadata } = {}) {
+    const res = await this._request("POST", "/threads",
+      this._wrap("thread", { title, type, created_by: createdBy, bot_id: botId, retention_days: retentionDays, metadata }));
+    return this._unwrap(res);
+  }
+
+  async getThread(threadId) {
+    return this._unwrap(await this._request("GET", `/threads/${threadId}`));
+  }
+
+  async listThreads({ page } = {}) {
+    const q = page ? `?page=${encodeURIComponent(JSON.stringify(page))}` : "";
+    return this._unwrap(await this._request("GET", `/threads${q}`));
+  }
+
+  async updateThread(threadId, attrs) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}`, this._wrap("thread", attrs)));
+  }
+
+  async resolveThread(threadId) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}/resolve`, this._wrap("thread", {})));
+  }
+
+  async archiveThread(threadId) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}/archive`, this._wrap("thread", {})));
+  }
+
+  async handoffThread(threadId, assignedAgent) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}/handoff`, this._wrap("thread", { assigned_agent: assignedAgent })));
+  }
+
+  async assignBot(threadId, botId) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}/assign-bot`, this._wrap("thread", { bot_id: botId })));
+  }
+
+  async deleteThread(threadId) {
+    return this._request("DELETE", `/threads/${threadId}`);
+  }
+
+  // ─── Participants ────────────────────────────────────────────────────────────
+
+  async joinThread(threadId, { userId, anonId, botId, type, role = "member", metadata } = {}) {
+    const res = await this._request("POST", `/threads/${threadId}/participants`,
+      this._wrap("participant", { thread_id: threadId, user_id: userId, anon_id: anonId, bot_id: botId, type, role, metadata }));
+    return this._unwrap(res);
+  }
+
+  async listParticipants(threadId, { page } = {}) {
+    const q = page ? `?page=${encodeURIComponent(JSON.stringify(page))}` : "";
+    return this._unwrap(await this._request("GET", `/threads/${threadId}/participants${q}`));
+  }
+
+  async markRead(threadId, participantId) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}/participants/${participantId}/mark-read`, this._wrap("participant", {})));
+  }
+
+  async updateParticipantRole(threadId, participantId, role) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}/participants/${participantId}/role`, this._wrap("participant", { role })));
+  }
+
+  async removeParticipant(threadId, participantId) {
+    return this._request("DELETE", `/threads/${threadId}/participants/${participantId}`);
+  }
+
+  // ─── Messages ────────────────────────────────────────────────────────────────
+
+  async sendMessage(threadId, { userId, anonId, botId, sender, type = "text", content, parentId } = {}) {
+    const res = await this._request("POST", `/threads/${threadId}/messages`,
+      this._wrap("message", { thread_id: threadId, user_id: userId, anon_id: anonId, bot_id: botId, sender, type, content, parent_id: parentId }));
+    return this._unwrap(res);
+  }
+
+  async getMessage(threadId, messageId) {
+    return this._unwrap(await this._request("GET", `/threads/${threadId}/messages/${messageId}`));
+  }
+
+  async listMessages(threadId, { page } = {}) {
+    const q = page ? `?page=${encodeURIComponent(JSON.stringify(page))}` : "";
+    return this._unwrap(await this._request("GET", `/threads/${threadId}/messages${q}`));
+  }
+
+  async listReplies(threadId, messageId, { page } = {}) {
+    const q = page ? `?page=${encodeURIComponent(JSON.stringify(page))}` : "";
+    return this._unwrap(await this._request("GET", `/threads/${threadId}/messages/${messageId}/replies${q}`));
+  }
+
+  async editMessage(threadId, messageId, content) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}/messages/${messageId}/edit`, this._wrap("message", { content })));
+  }
+
+  async deleteMessage(threadId, messageId) {
+    return this._unwrap(await this._request("PATCH", `/threads/${threadId}/messages/${messageId}/delete`, this._wrap("message", {})));
+  }
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "pingerchips-js-server",
-  "version": "2.1.1",
-  "description": "Pingerchips server SDK for Node.js - trigger events and authenticate users",
+  "version": "3.0.0",
+  "description": "Pingerchips server SDK for Node.js - trigger events and issue capability tokens",
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "pingerchips",
@@ -17,7 +17,9 @@
   ],
   "author": "Pingerchips",
   "license": "MIT",
-  "dependencies": {},
+  "dependencies": {
+    "phoenix": "^1.7.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/pingerchips/pingerchips-js-server"
@@ -27,6 +29,6 @@
   },
   "homepage": "https://pingerchips.com",
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   }
 }