pingerchips-js-server 2.0.0 → 3.0.0

package/README.md

@@ -1,6 +1,9 @@
-# Pingerchips Server SDK
+# pingerchips-js-server
 
-Server-side SDK for triggering events and authenticating users with Pingerchips.
+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`).
 
 ## Installation
 
@@ -15,110 +18,193 @@ 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.
+
+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.
 
-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).
 
-Implement an auth endpoint on your server:
+## Authentication (ADR-0016 — unified capability tokens)
 
-```javascript
-import express from 'express';
+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.
+
+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` |
 
-const app = express();
-app.use(express.json());
+Capability grammar: `product:verb:resource`
 
+| 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;
 
-  // 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' });
+
+  const userData = channel_name.startsWith('presence-')
+    ? { user_id: user.id, name: user.name }
+    : null;
 
-  // 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;
-
-  // Sign authentication with Pingerchips
-  const authData = pingerchips.authenticate(socket_id, channel_name, userData);
-  res.json(authData);
+  res.json(pingerchips.authenticate(socket_id, channel_name, userData));
 });
 ```
 
-## API Reference
+```javascript
+const client = new Pingerchips('app_key', {
+  authEndpoint: 'https://your-server.com/auth'
+});
+```
 
-### `new PingerchipsServer(appId, appSecret, options)`
+### Many grants on one token
 
-Create a new server instance.
+```javascript
+const { auth } = pingerchips.authorize(socketId, {
+  channels: ['orders', 'shipments'],
+  presence: ['lobby'],
+  objects:  [{ type: 'order', key: 'order-42' }],
+  threads:  ['thread-abc'],
+}, clientId);
+```
 
-**Options:**
-- `appKey` - Your app key (required for authentication)
-- `endpoint` - API endpoint URL
-- `token` - API token for internal endpoints
-- `mtls` - mTLS configuration for secure connections
+### Chat threads (server-issued JWT)
 
-### `trigger(channel, event, data)`
+```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']
+);
+```
 
-Send an event to a channel.
+### Durable Objects (browser subscription token)
 
 ```javascript
-await pingerchips.trigger('my-channel', 'my-event', { message: 'Hello' });
+const { auth } = pingerchips.authenticateObject(socketId, 'order', 'order-42');
+// grants object:read:order/order-42 bound to socketId
 ```
 
-### `authenticate(socketId, channelName, userData?)`
+## API
 
-Generate signed authentication for private/presence channels.
+### `new PingerchipsServer(appKey, appSecret, options?)`
 
-**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`)
+| Parameter | Type | Description |
+|---|---|---|
+| `appKey` | string | Your app key |
+| `appSecret` | string | Your app secret — sent only to the Pingerchips backend |
 
-**Returns:**
-```javascript
-{
-  auth: "app_key:hmac_signature",
-  channel_data: "{\"user_id\":\"123\",...}" // presence channels only
-}
-```
+**Options:**
+
+| 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 |
+| `mtls` | object | — | mTLS config (see below) |
+
+### `trigger(channel, event, data)`
+
+- `channel` — max 200 chars
+- `event` — max 200 chars
+- `data` — JSON serializable, max 64KB
+
+### `notify(userId, { title, body }, options?)`
+
+Send a push notification. `options.trigger` is `"offline"` (default, skipped if
+the user is connected) or `"always"`.
+
+### `registerPushToken(userId, device)` / `unregisterPushToken(userId, deviceId)`
+
+Server-side device token management.
+
+### `authenticate(socketId, channelName, userData?)` → `{ auth, channel_data? }`
+
+Fast-path token for one `private-` / `presence-` channel.
+
+### `authorize(socketId, grants, clientId?)` → `{ auth }`
 
-## mTLS Support
+Fast-path token for many grants. `grants`: `{ channels?, presence?, publish?,
+objects?, threads?, capabilities? }`.
 
-For secure server-to-server communication:
+### `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).
+
+### `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_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
   }
 });
 ```
 
+## 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 };