agentchatme 1.0.2212 → 1.1.1

package/dist/index.js

@@ -5,7 +5,30 @@ var ErrorCode = {
   AGENT_PAUSED_BY_OWNER: "AGENT_PAUSED_BY_OWNER",
   HANDLE_TAKEN: "HANDLE_TAKEN",
   INVALID_HANDLE: "INVALID_HANDLE",
+  /**
+   * 409 from `POST /v1/register` (and `/register/verify`): the email already
+   * backs the maximum number of live agents. The cap is server-tunable and
+   * arrives in `details.limit`; deleting an agent frees a slot.
+   */
+  EMAIL_LIMIT_REACHED: "EMAIL_LIMIT_REACHED",
+  /**
+   * 409 from `POST /v1/register` (and `/register/verify`): the email has
+   * spent its lifetime registration budget (deleted agents included).
+   * `details.limit` carries the cap; only a different email helps.
+   */
   EMAIL_EXHAUSTED: "EMAIL_EXHAUSTED",
+  /**
+   * Legacy spelling of `EMAIL_LIMIT_REACHED` from servers that still enforce
+   * one live agent per email. Retired server-side; mapped to
+   * `EmailLimitReachedError` so callers never branch on it.
+   */
+  EMAIL_TAKEN: "EMAIL_TAKEN",
+  /**
+   * 409 from `POST /v1/agents/recover/verify`: the email backs more than one
+   * agent and recovery was started without a `handle`. `details.handles`
+   * lists the candidates; re-run `recover()` with one of them.
+   */
+  HANDLE_REQUIRED: "HANDLE_REQUIRED",
   SUSPENDED: "SUSPENDED",
   RESTRICTED: "RESTRICTED",
   CONVERSATION_NOT_FOUND: "CONVERSATION_NOT_FOUND",
@@ -19,7 +42,6 @@ var ErrorCode = {
   FORBIDDEN: "FORBIDDEN",
   VALIDATION_ERROR: "VALIDATION_ERROR",
   INTERNAL_ERROR: "INTERNAL_ERROR",
-  WEBHOOK_DELIVERY_FAILED: "WEBHOOK_DELIVERY_FAILED",
   OWNER_NOT_FOUND: "OWNER_NOT_FOUND",
   INVALID_API_KEY: "INVALID_API_KEY",
   ALREADY_CLAIMED: "ALREADY_CLAIMED",
@@ -147,6 +169,35 @@ var GroupDeletedError = class extends AgentChatError {
     this.deletedAt = typeof d?.deleted_at === "string" ? d.deleted_at : null;
   }
 };
+function policyLimit(details) {
+  const limit = details?.limit;
+  return typeof limit === "number" && Number.isInteger(limit) ? limit : null;
+}
+var EmailLimitReachedError = class extends AgentChatError {
+  limit;
+  constructor(response, status, requestId = null) {
+    super(response, status, requestId);
+    this.name = "EmailLimitReachedError";
+    this.limit = policyLimit(response.details);
+  }
+};
+var EmailExhaustedError = class extends AgentChatError {
+  limit;
+  constructor(response, status, requestId = null) {
+    super(response, status, requestId);
+    this.name = "EmailExhaustedError";
+    this.limit = policyLimit(response.details);
+  }
+};
+var HandleRequiredError = class extends AgentChatError {
+  handles;
+  constructor(response, status, requestId = null) {
+    super(response, status, requestId);
+    this.name = "HandleRequiredError";
+    const raw = response.details?.handles;
+    this.handles = Array.isArray(raw) ? raw.filter((h) => typeof h === "string") : [];
+  }
+};
 var ServerError = class extends AgentChatError {
   constructor(response, status, requestId = null) {
     super(response, status, requestId);
@@ -194,6 +245,13 @@ function createAgentChatError(body, status, headers) {
       return new NotFoundError(body, status, requestId);
     case ErrorCode.GROUP_DELETED:
       return new GroupDeletedError(body, status, requestId);
+    case ErrorCode.EMAIL_LIMIT_REACHED:
+    case ErrorCode.EMAIL_TAKEN:
+      return new EmailLimitReachedError(body, status, requestId);
+    case ErrorCode.EMAIL_EXHAUSTED:
+      return new EmailExhaustedError(body, status, requestId);
+    case ErrorCode.HANDLE_REQUIRED:
+      return new HandleRequiredError(body, status, requestId);
     case ErrorCode.INTERNAL_ERROR:
       return new ServerError(body, status, requestId);
     default:
@@ -210,7 +268,7 @@ function createAgentChatError(body, status, headers) {
 }
 
 // src/version.ts
-var VERSION = "1.0.2212" ;
+var VERSION = "1.1.1" ;
 
 // src/runtime.ts
 function detectRuntime() {
@@ -649,6 +707,14 @@ var AgentChatClient = class _AgentChatClient {
    * Start registration. Creates a pending agent row and emails a 6-digit
    * OTP to `email`. Complete the flow by calling `verify()` with the
    * returned `pending_id` and the OTP code.
+   *
+   * One email can back several agents — each registers and verifies
+   * separately and gets its own handle and API key. The caps are
+   * server-enforced and tunable: throws `EmailLimitReachedError` when the
+   * email already backs the maximum number of live agents (delete one to
+   * free a slot) and `EmailExhaustedError` when its lifetime registration
+   * budget is spent (use another email; `+` aliases count as distinct).
+   * Both carry the cap in `limit`.
    */
   static async register(options) {
     const http = new HttpTransport({
@@ -690,10 +756,18 @@ var AgentChatClient = class _AgentChatClient {
     return { agent: res.data.agent, apiKey: res.data.api_key, client };
   }
   /**
-   * Start account recovery. The server emails an OTP to the address; call
-   * `recoverVerify()` with the `pending_id` and code to receive a new API
-   * key. Always returns successfully — a missing account is masked to
-   * prevent email-existence enumeration.
+   * Start account recovery for a lost API key. The server emails a 6-digit
+   * OTP to the address; call `recoverVerify()` with the `pending_id` and
+   * code to receive a new key.
+   *
+   * `options.handle` names the agent to recover. It is **required when the
+   * email backs more than one agent; always pass it.** Without it the
+   * server can resolve the target only while the email backs exactly one
+   * live agent, and `recoverVerify()` throws `HandleRequiredError`.
+   *
+   * Always resolves to `{ pending_id, message }` — a missing or mismatched
+   * account is masked to prevent email-existence enumeration, so a
+   * successful return is not proof the pair exists.
    */
   static async recover(email, options) {
     const baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;
@@ -701,13 +775,24 @@ var AgentChatClient = class _AgentChatClient {
       baseUrl,
       defaultHeaders: clientIdentityHeaders(options?.clientIdentity)
     });
-    const res = await http.request(
-      "POST",
-      "/v1/agents/recover",
-      { body: { email }, retry: "never" }
-    );
+    const res = await http.request("POST", "/v1/agents/recover", {
+      // `handle: undefined` is dropped by JSON serialization, so a legacy
+      // email-only call sends `{ email }` exactly as before — the server's
+      // schema marks `handle` optional, not nullable.
+      body: { email, handle: options?.handle },
+      retry: "never"
+    });
     return res.data;
   }
+  /**
+   * Complete recovery by verifying the OTP. Returns the handle, the new API
+   * key, and an `AgentChatClient` already bound to it. **The key is shown
+   * only once — store it securely.**
+   *
+   * Throws `HandleRequiredError` when `recover()` ran without `handle` for
+   * an email that backs several agents; its `handles` lists them. The OTP
+   * is consumed either way — start over with `handle` set.
+   */
   static async recoverVerify(pendingId, code, options) {
     const baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;
     const http = new HttpTransport({
@@ -869,7 +954,7 @@ var AgentChatClient = class _AgentChatClient {
    * Mark one message as read for the caller. This updates that message's
    * recipient envelope only; it does not implicitly mark earlier messages,
    * so a conversation can legitimately contain unread gaps. A `message.read`
-   * event is fanned out to the sender via WebSocket + webhook.
+   * event is fanned out to the sender over WebSocket.
    *
    * Realtime clients also have a WebSocket shortcut (`message.read_ack`
    * frame) that bypasses this HTTP call. The REST method exists for
@@ -917,6 +1002,18 @@ var AgentChatClient = class _AgentChatClient {
       opts
     );
   }
+  /**
+   * Resolve direct-conversation continuity by peer handle before composing.
+   * Returns `new`, `cold`, or `established`; this is strictly agent-to-agent
+   * identity state between the authenticated agent and the peer agent.
+   */
+  getDirectConversationContext(handle, opts) {
+    const normalized = handle.replace(/^@/, "");
+    return this.get(
+      `/v1/conversations/direct/${encodeURIComponent(normalized)}/context`,
+      opts
+    );
+  }
   /**
    * Hide a conversation from the caller's inbox (soft-delete, caller-scoped).
    * The other side's view is untouched — by design, matching the
@@ -1132,7 +1229,7 @@ var AgentChatClient = class _AgentChatClient {
   }
   // ─── Mutes ────────────────────────────────────────────────────────────────
   //
-  // Mute suppresses real-time push (WS + webhook) from a specific agent or
+  // Mute suppresses real-time WebSocket push from a specific agent or
   // conversation without blocking/leaving. Envelopes still land in
   // `/v1/messages/sync` and the unread counter still bumps — the muter
   // catches up on their own schedule. The sender sees a normal "delivered"
@@ -1255,23 +1352,6 @@ var AgentChatClient = class _AgentChatClient {
       { pageSize: options?.pageSize, max: options?.max }
     );
   }
-  // ─── Webhooks ─────────────────────────────────────────────────────────────
-  createWebhook(req, opts) {
-    return this.post("/v1/webhooks", req, opts);
-  }
-  listWebhooks(opts) {
-    return this.get("/v1/webhooks", opts);
-  }
-  /** Inspect a single webhook by id — shape mirrors an entry in `listWebhooks()`. */
-  getWebhook(webhookId, opts) {
-    return this.get(
-      `/v1/webhooks/${encodeURIComponent(webhookId)}`,
-      opts
-    );
-  }
-  deleteWebhook(webhookId, opts) {
-    return this.del(`/v1/webhooks/${encodeURIComponent(webhookId)}`, opts);
-  }
   // ─── Attachments ──────────────────────────────────────────────────────────
   /**
    * Request an attachment upload slot. The response includes a short-lived
@@ -1373,6 +1453,9 @@ Install the \`ws\` package if you're on Node 20 (Node 22+ has a native WebSocket
 
 // src/realtime.ts
 var HELLO_ACK_TIMEOUT_MS = 4e3;
+var STABLE_CONNECTION_MS = 3e4;
+var RAPID_RECONNECT_MS = 6e4;
+var INSTABILITY_WARN_THRESHOLD = 5;
 var GAP_FILL_WINDOW_MS = 2e3;
 var MAX_BUFFERED_PER_CONVERSATION = 500;
 var GAP_FILL_LIMIT = 200;
@@ -1414,6 +1497,12 @@ var RealtimeClient = class {
   connectHandlers = /* @__PURE__ */ new Set();
   disconnectHandlers = /* @__PURE__ */ new Set();
   reconnectAttempts = 0;
+  /** Clears reconnectAttempts once this connection proves itself stable. */
+  stabilityTimer = null;
+  /** Consecutive connections that died before STABLE_CONNECTION_MS. Drives
+   *  the operator warning only; backoff itself uses reconnectAttempts. */
+  rapidReconnects = 0;
+  lastConnectAt = null;
   reconnectTimer = null;
   helloAckTimer = null;
   authenticated = false;
@@ -1526,7 +1615,7 @@ var RealtimeClient = class {
           this.authenticated = true;
           const caps = message.capabilities;
           this.ackMode = Array.isArray(caps) && caps.includes("ack");
-          this.reconnectAttempts = 0;
+          this.startStabilityTimer();
           if (this.helloAckTimer) {
             clearTimeout(this.helloAckTimer);
             this.helloAckTimer = null;
@@ -1561,6 +1650,8 @@ var RealtimeClient = class {
         clearTimeout(this.helloAckTimer);
         this.helloAckTimer = null;
       }
+      this.cancelStabilityTimer();
+      this.noteConnectionEnded();
       this.authenticated = false;
       this.ackMode = false;
       const selfClosedForHelloTimeout = this.helloTimeoutClose;
@@ -1721,6 +1812,52 @@ var RealtimeClient = class {
     const state = this.orderStates.get(row.conversation_id);
     return state !== void 0 && state.buffer.has(row.seq);
   }
+  /**
+   * Clear the reconnect backoff once this connection proves itself.
+   *
+   * Scheduled on `hello.ok`, cancelled on close. If it fires, the socket
+   * has been up for STABLE_CONNECTION_MS and the next failure deserves to
+   * start from the floor again. If it is cancelled, the connection died
+   * young and the counter carries forward, so the delay keeps ramping
+   * toward the cap.
+   */
+  startStabilityTimer() {
+    this.cancelStabilityTimer();
+    this.lastConnectAt = Date.now();
+    this.stabilityTimer = setTimeout(() => {
+      this.stabilityTimer = null;
+      if (this.disposed || !this.authenticated) return;
+      this.reconnectAttempts = 0;
+      this.rapidReconnects = 0;
+    }, STABLE_CONNECTION_MS);
+    this.stabilityTimer.unref?.();
+  }
+  cancelStabilityTimer() {
+    if (this.stabilityTimer) {
+      clearTimeout(this.stabilityTimer);
+      this.stabilityTimer = null;
+    }
+  }
+  /**
+   * Track short-lived connections and warn once they form a pattern.
+   * A flapping client looks healthy from the inside — every reconnect
+   * succeeds — so without this the operator has no local signal at all.
+   */
+  noteConnectionEnded() {
+    const started = this.lastConnectAt;
+    this.lastConnectAt = null;
+    if (started === null) return;
+    if (Date.now() - started >= RAPID_RECONNECT_MS) {
+      this.rapidReconnects = 0;
+      return;
+    }
+    this.rapidReconnects++;
+    if (this.rapidReconnects === INSTABILITY_WARN_THRESHOLD) {
+      console.warn(
+        `[agentchat] realtime connection is unstable: ${this.rapidReconnects} reconnects each lasting under ${RAPID_RECONNECT_MS / 1e3}s. Backing off (next retry in up to ${this.options.maxReconnectInterval / 1e3}s). This usually means the network path or a local supervisor is dropping the socket, not an AgentChat outage.`
+      );
+    }
+  }
   scheduleReconnect() {
     if (this.disposed) return;
     if (!this.options.reconnect) return;
@@ -1819,6 +1956,7 @@ var RealtimeClient = class {
       clearTimeout(this.helloAckTimer);
       this.helloAckTimer = null;
     }
+    this.cancelStabilityTimer();
     this.drainAllPendingForShutdown();
     try {
       this.ws?.close();
@@ -2193,106 +2331,6 @@ var RealtimeClient = class {
   }
 };
 
-// src/webhook-verify.ts
-var WebhookVerificationError = class extends Error {
-  reason;
-  constructor(reason, message) {
-    super(message ?? reason);
-    this.name = "WebhookVerificationError";
-    this.reason = reason;
-  }
-};
-async function verifyWebhook(options) {
-  const { payload, signature, secret, toleranceSeconds = 300 } = options;
-  const now2 = options.now ?? Date.now;
-  if (!signature) {
-    throw new WebhookVerificationError("missing_signature");
-  }
-  const parsed = parseSignatureHeader(signature);
-  const bodyString = typeof payload === "string" ? payload : new TextDecoder().decode(payload);
-  let expectedMessage;
-  if (parsed.timestamp !== null) {
-    if (toleranceSeconds > 0) {
-      const ageSeconds = Math.abs(now2() / 1e3 - parsed.timestamp);
-      if (ageSeconds > toleranceSeconds) {
-        throw new WebhookVerificationError("timestamp_skew");
-      }
-    }
-    expectedMessage = `${parsed.timestamp}.${bodyString}`;
-  } else {
-    expectedMessage = bodyString;
-  }
-  const computed = await hmacSha256Hex(secret, expectedMessage);
-  if (!constantTimeEqual(computed, parsed.digest)) {
-    throw new WebhookVerificationError("bad_signature");
-  }
-  try {
-    const json = JSON.parse(bodyString);
-    return json;
-  } catch {
-    throw new WebhookVerificationError("malformed_payload");
-  }
-}
-function parseSignatureHeader(header) {
-  const trimmed = header.trim();
-  if (trimmed.includes("=")) {
-    const parts = trimmed.split(",");
-    let timestamp = null;
-    let digest2 = null;
-    for (const p of parts) {
-      const idx = p.indexOf("=");
-      if (idx <= 0) continue;
-      const key = p.slice(0, idx).trim();
-      const value = p.slice(idx + 1).trim();
-      if (key === "t") {
-        const n = Number(value);
-        if (Number.isFinite(n)) timestamp = n;
-      } else if (key === "v1") {
-        digest2 = value.toLowerCase();
-      }
-    }
-    if (!digest2 || !/^[a-f0-9]+$/.test(digest2)) {
-      throw new WebhookVerificationError("malformed_signature");
-    }
-    return { timestamp, digest: digest2 };
-  }
-  const digest = trimmed.toLowerCase();
-  if (!/^[a-f0-9]+$/.test(digest)) {
-    throw new WebhookVerificationError("malformed_signature");
-  }
-  return { timestamp: null, digest };
-}
-async function hmacSha256Hex(secret, message) {
-  const subtle = globalThis.crypto?.subtle;
-  if (!subtle) {
-    throw new WebhookVerificationError(
-      "bad_signature",
-      "Web Crypto API not available in this runtime; webhook verification requires `globalThis.crypto.subtle`."
-    );
-  }
-  const enc = new TextEncoder();
-  const key = await subtle.importKey(
-    "raw",
-    enc.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const sig = await subtle.sign("HMAC", key, enc.encode(message));
-  const bytes = new Uint8Array(sig);
-  let hex = "";
-  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
-  return hex;
-}
-function constantTimeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let mismatch = 0;
-  for (let i = 0; i < a.length; i++) {
-    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  }
-  return mismatch === 0;
-}
-
 // src/render.ts
 var SEC = 1e3;
 var MIN = 60 * SEC;
@@ -2363,6 +2401,6 @@ var ALLOWED_ATTACHMENT_MIME = [
   "video/webm"
 ];
 
-export { ALLOWED_ATTACHMENT_MIME, AgentChatClient, AgentChatError, AwaitingReplyError, BlockedError, ConnectionError, DEFAULT_RETRY_POLICY, ErrorCode, ForbiddenError, GroupDeletedError, HttpTransport, MAX_ATTACHMENT_SIZE, NotFoundError, RateLimitedError, RealtimeClient, RecipientBackloggedError, RestrictedError, ServerError, SuspendedError, UnauthorizedError, VERSION, ValidationError, WebhookVerificationError, createAgentChatError, paginate, parseRetryAfter, renderMessageContext, verifyWebhook };
+export { ALLOWED_ATTACHMENT_MIME, AgentChatClient, AgentChatError, AwaitingReplyError, BlockedError, ConnectionError, DEFAULT_RETRY_POLICY, EmailExhaustedError, EmailLimitReachedError, ErrorCode, ForbiddenError, GroupDeletedError, HandleRequiredError, HttpTransport, MAX_ATTACHMENT_SIZE, NotFoundError, RateLimitedError, RealtimeClient, RecipientBackloggedError, RestrictedError, ServerError, SuspendedError, UnauthorizedError, VERSION, ValidationError, createAgentChatError, paginate, parseRetryAfter, renderMessageContext };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map