pingerchips-js-server 2.0.0 → 3.0.0

package/index.js

@@ -2,166 +2,939 @@ 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 {
-  constructor(appId, appSecret, options = {}) {
-    this.appId = appId;
+  /**
+   * @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 = {}) {
+    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";
-    this.token = options.token;
+      (process.env.NODE_ENV === "production"
+        ? "https://queue.pingerchips.com"
+        : "http://localhost:4000");
+    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");
+    }
+  }
+
+  /** 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, {
+        ...requestOptions,
+        signal: controller.signal,
+      });
+
+      // 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);
+      }
+
+      return response;
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw new Error(`Request timeout after ${this.requestTimeout}ms`);
+      }
+      // 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;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Trigger an event on a channel. Authenticated with X-App-Key / X-App-Secret
+   * headers (ADR-0016).
+   *
+   * @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 requestOptions = {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        token: this.token,
-      },
-      body: JSON.stringify({
-        app_id: this.appId,
-        app_secret: this.appSecret,
-        channel,
-        event,
-        data,
-      }),
+      headers: this._authHeaders(),
+      body: JSON.stringify(body),
     };
 
-    // Add HTTPS agent if mTLS is enabled
     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.
+   * Send a push notification to a specific user.
    *
-   * @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? }
+   * @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).
    *
-   * @example
-   * // In your Express.js auth endpoint:
-   * app.post('/auth', (req, res) => {
-   *   const { socket_id, channel_name, auth_info } = req.body;
+   * @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.
    *
-   *   // Validate user from session/token
-   *   const user = req.session.user;
-   *   if (!user) return res.status(403).json({ error: 'Unauthorized' });
+   * @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.
    *
-   *   // 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;
+   * 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.
    *
-   *   const authData = pingerchips.authenticate(socket_id, channel_name, userData);
-   *   res.json(authData);
-   * });
+   * @param {string} socketId - Socket ID from the client SDK
+   * @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");
+    }
+
+    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 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) {
+      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);
+
+    if (caps.length === 0) {
+      throw new Error(
+        "authorize: pass at least one of channels / presence / publish / objects / threads / capabilities",
+      );
+    }
+
+    return {
+      auth: mintFastToken(this.appKey, this.appSecret, socketId, caps, clientId),
+    };
+  }
+
+  // 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}`);
+    }
 
-    // Build string to sign based on channel type
-    let stringToSign;
-    let channelData = null;
+    return result;
+  }
 
-    if (userData && channelName.startsWith("presence-")) {
-      // Presence channel: include user data in signature
-      channelData = JSON.stringify(userData);
-      stringToSign = `${socketId}:${fullTopic}:${channelData}`;
-    } else {
-      // Private channel: just socket_id and topic
-      stringToSign = `${socketId}:${fullTopic}`;
+  /**
+   * 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");
     }
 
-    // Generate HMAC-SHA256 signature using app_secret
-    const signature = crypto
-      .createHmac("sha256", this.appSecret)
-      .update(stringToSign)
-      .digest("hex");
+    // 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)}`;
+  }
 
-    const auth = `${this.appKey}:${signature}`;
+  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
+    );
 
-    // Build response
-    const response = { auth };
+    if (res.status === 204) return null;
 
-    if (channelData) {
-      response.channel_data = channelData;
+    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());
+  }
 
-    return response;
+  /** 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", {})));
+  }
+}