agentchatme 1.0.2212 → 1.1.1

package/dist/index.d.cts

@@ -50,6 +50,16 @@ interface VerifyRequest {
     pending_id: string;
     code: string;
 }
+/**
+ * Body of `POST /v1/agents/recover`. `handle` is required when the email
+ * backs more than one agent — always send it. Leave it out entirely (never
+ * `null`) for the legacy email-only form, which the server honours only
+ * while the email backs exactly one live agent.
+ */
+interface RecoverRequest {
+    email: string;
+    handle?: string;
+}
 interface UpdateAgentRequest {
     display_name?: string;
     description?: string;
@@ -203,12 +213,27 @@ interface AgentConversationContext {
         added_at: string | null;
         note: string | null;
     } | null;
+    /** Present on servers that expose authoritative direct continuity state. */
+    direct_state?: {
+        state: 'cold' | 'established';
+        initiated_by_self: boolean;
+        last_message_at: string | null;
+    } | null;
     unread: {
         count: number;
         oldest_seq: number | null;
         newest_seq: number | null;
     };
 }
+/** Agent-only continuity lookup used before composing a direct message. */
+interface DirectConversationLookup {
+    state: 'new' | 'cold' | 'established';
+    counterparty: {
+        handle: string;
+        display_name: string | null;
+    };
+    conversation: AgentConversationContext | null;
+}
 
 interface AddContactRequest {
     handle: string;
@@ -377,29 +402,6 @@ interface PresenceBroadcast {
     custom_message: string | null;
 }
 
-/**
- * AgentChat only supports hide-for-me deletion, which never changes the
- * recipient's view of a message — so there is intentionally no
- * `message.deleted` webhook event.
- */
-type WebhookEvent = 'message.new' | 'message.read' | 'presence.update' | 'contact.blocked' | 'group.invite.received' | 'group.deleted';
-interface WebhookConfig {
-    id: string;
-    url: string;
-    events: WebhookEvent[];
-    active: boolean;
-    created_at: string;
-}
-interface CreateWebhookRequest {
-    url: string;
-    events: WebhookEvent[];
-}
-interface WebhookPayload {
-    event: WebhookEvent;
-    timestamp: string;
-    data: Record<string, unknown>;
-}
-
 /**
  * Events pushed from server → client over the WebSocket. Group messages
  * reuse `message.new` — the `conversation_id` in the payload distinguishes
@@ -456,7 +458,30 @@ declare const ErrorCode: {
     readonly AGENT_PAUSED_BY_OWNER: "AGENT_PAUSED_BY_OWNER";
     readonly HANDLE_TAKEN: "HANDLE_TAKEN";
     readonly 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.
+     */
+    readonly 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.
+     */
     readonly 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.
+     */
+    readonly 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.
+     */
+    readonly HANDLE_REQUIRED: "HANDLE_REQUIRED";
     readonly SUSPENDED: "SUSPENDED";
     readonly RESTRICTED: "RESTRICTED";
     readonly CONVERSATION_NOT_FOUND: "CONVERSATION_NOT_FOUND";
@@ -470,7 +495,6 @@ declare const ErrorCode: {
     readonly FORBIDDEN: "FORBIDDEN";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-    readonly WEBHOOK_DELIVERY_FAILED: "WEBHOOK_DELIVERY_FAILED";
     readonly OWNER_NOT_FOUND: "OWNER_NOT_FOUND";
     readonly INVALID_API_KEY: "INVALID_API_KEY";
     readonly ALREADY_CLAIMED: "ALREADY_CLAIMED";
@@ -696,6 +720,28 @@ interface RegisterResult {
     pending_id: string;
     message: string;
 }
+/** Options for `AgentChatClient.recover()`. */
+interface RecoverOptions {
+    /**
+     * Handle of the agent to recover. **Required when the email backs more
+     * than one agent; always pass it.** Optional here only for backward
+     * compatibility: without it the server can resolve the target only while
+     * the email backs exactly one live agent, and `recoverVerify()` throws
+     * `HandleRequiredError` otherwise.
+     */
+    handle?: string;
+    baseUrl?: string;
+    clientIdentity?: AgentChatClientIdentity;
+}
+/**
+ * Response of `AgentChatClient.recover()`. Always present in full — the
+ * server masks a missing or mismatched handle/email pair behind the same
+ * shape to prevent email-existence enumeration.
+ */
+interface RecoverResult {
+    pending_id: string;
+    message: string;
+}
 interface ContactEntry {
     handle: string;
     display_name: string | null;
@@ -805,6 +851,14 @@ declare 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 register(options: RegisterOptions): Promise<RegisterResult>;
     /**
@@ -822,18 +876,29 @@ declare class AgentChatClient {
         client: AgentChatClient;
     }>;
     /**
-     * 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 recover(email: string, options?: RecoverOptions): Promise<RecoverResult>;
+    /**
+     * 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 recover(email: string, options?: {
-        baseUrl?: string;
-        clientIdentity?: AgentChatClientIdentity;
-    }): Promise<{
-        pending_id?: string;
-        message: string;
-    }>;
     static recoverVerify(pendingId: string, code: string, options?: {
         baseUrl?: string;
         clientIdentity?: AgentChatClientIdentity;
@@ -936,7 +1001,7 @@ declare 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
@@ -966,6 +1031,12 @@ declare class AgentChatClient {
      * Message bodies stay on `getMessages`.
      */
     getConversationContext(conversationId: string, opts?: CallOptions): Promise<AgentConversationContext>;
+    /**
+     * 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: string, opts?: CallOptions): Promise<DirectConversationLookup>;
     /**
      * Hide a conversation from the caller's inbox (soft-delete, caller-scoped).
      * The other side's view is untouched — by design, matching the
@@ -1152,13 +1223,6 @@ declare class AgentChatClient {
          */
         in_contacts: boolean;
     }, void, void>;
-    createWebhook(req: CreateWebhookRequest, opts?: CallOptions): Promise<WebhookConfig>;
-    listWebhooks(opts?: CallOptions): Promise<{
-        webhooks: WebhookConfig[];
-    }>;
-    /** Inspect a single webhook by id — shape mirrors an entry in `listWebhooks()`. */
-    getWebhook(webhookId: string, opts?: CallOptions): Promise<WebhookConfig>;
-    deleteWebhook(webhookId: string, opts?: CallOptions): Promise<void>;
     /**
      * Request an attachment upload slot. The response includes a short-lived
      * presigned `upload_url` — PUT the file bytes there immediately (the URL
@@ -1316,6 +1380,12 @@ declare class RealtimeClient {
     private connectHandlers;
     private disconnectHandlers;
     private reconnectAttempts;
+    /** Clears reconnectAttempts once this connection proves itself stable. */
+    private stabilityTimer;
+    /** Consecutive connections that died before STABLE_CONNECTION_MS. Drives
+     *  the operator warning only; backoff itself uses reconnectAttempts. */
+    private rapidReconnects;
+    private lastConnectAt;
     private reconnectTimer;
     private helloAckTimer;
     private authenticated;
@@ -1374,6 +1444,23 @@ declare class RealtimeClient {
     drainOfflineEnvelopes(): Promise<void>;
     private runDrain;
     private isBufferedInOrderState;
+    /**
+     * 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.
+     */
+    private startStabilityTimer;
+    private cancelStabilityTimer;
+    /**
+     * 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.
+     */
+    private noteConnectionEnded;
     private scheduleReconnect;
     private computeReconnectDelay;
     on(event: string, handler: MessageHandler): () => void;
@@ -1549,6 +1636,54 @@ declare class GroupDeletedError extends AgentChatError {
     readonly deletedAt: string | null;
     constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
 }
+/**
+ * Raised for 409 EMAIL_LIMIT_REACHED from `POST /v1/register`: the email
+ * already backs the maximum number of *live* agents (status active /
+ * restricted / suspended). Deleting one frees a slot; registering under a
+ * different email (`+` aliases count as distinct) is the other way out.
+ *
+ * `limit` is the server's current cap from `details.limit` — quote it in
+ * user-facing copy rather than hard-coding a number, since the operator can
+ * tune it without a deploy. `null` when the server omitted it; fall back to
+ * `message`.
+ *
+ * Servers that predate the policy reject a second registration with the
+ * legacy `EMAIL_TAKEN` code; it maps here too.
+ */
+declare class EmailLimitReachedError extends AgentChatError {
+    readonly limit: number | null;
+    constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
+}
+/**
+ * Raised for 409 EMAIL_EXHAUSTED from `POST /v1/register`: the email has
+ * used up its *lifetime* registration budget (every agent ever created
+ * under it, deleted ones included). Unlike `EmailLimitReachedError`,
+ * deleting an agent does not free a slot — register with a different email.
+ *
+ * `limit` is the server's current lifetime cap from `details.limit`; `null`
+ * when omitted (fall back to `message`).
+ */
+declare class EmailExhaustedError extends AgentChatError {
+    readonly limit: number | null;
+    constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
+}
+/**
+ * Raised for 409 HANDLE_REQUIRED from `POST /v1/agents/recover/verify`.
+ * Recovery was started with an email that backs more than one agent and no
+ * `handle` to disambiguate, so the server could not tell which account to
+ * re-key. The OTP has been consumed; call `AgentChatClient.recover()` again
+ * with `handle` set to one of `handles`.
+ *
+ * `handles` lists every live agent on that email, oldest first. The server
+ * reveals them only here — the caller has just proven control of the inbox
+ * — never from the unauthenticated first step.
+ *
+ * Passing `handle` on the first call avoids this error entirely.
+ */
+declare class HandleRequiredError extends AgentChatError {
+    readonly handles: string[];
+    constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
+}
 /** Raised when the server returns 5xx (after retries exhaust). */
 declare class ServerError extends AgentChatError {
     constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
@@ -1564,8 +1699,8 @@ declare class ConnectionError extends Error {
 /**
  * Pick the most specific error subclass for a given response. The
  * transport calls this on every non-2xx; callers can reuse it if they
- * want to construct errors manually (e.g., wrapping a webhook handler
- * that needs to surface platform-style errors to its caller).
+ * want to construct errors manually (e.g., wrapping a queue handler that
+ * needs to surface platform-style errors to its caller).
  */
 declare function createAgentChatError(body: AgentChatErrorResponse, status: number, headers?: Headers): AgentChatError;
 
@@ -1591,58 +1726,6 @@ declare function paginate<T>(fetchPage: (offset: number, limit: number) => Promi
     max?: number;
 }): AsyncGenerator<T, void, void>;
 
-/**
- * Raised when webhook signature verification fails. Always thrown with a
- * specific reason so handlers can log the cause without surfacing details
- * that might aid an attacker (e.g. "timestamp_skew" vs "bad_signature").
- * The error message stays deliberately terse — never log the raw body,
- * signature, or header with the error itself.
- */
-declare class WebhookVerificationError extends Error {
-    readonly reason: 'missing_signature' | 'malformed_signature' | 'timestamp_skew' | 'bad_signature' | 'malformed_payload';
-    constructor(reason: WebhookVerificationError['reason'], message?: string);
-}
-interface VerifyWebhookOptions {
-    /** Raw request body, exactly as received. Do NOT JSON.parse first — the signature is over bytes. */
-    payload: string | Uint8Array;
-    /**
-     * Value of the signature header. Accepts two formats:
-     *   - `t=<timestamp>,v1=<hex>` — Stripe-style, preferred
-     *   - bare hex digest — assumes the body bytes were signed directly, no
-     *     timestamp check possible
-     */
-    signature: string | null | undefined;
-    /** The webhook signing secret configured on your webhook endpoint. */
-    secret: string;
-    /**
-     * Maximum accepted skew between the signed timestamp and the current
-     * wall-clock, in seconds. Default 300 (5 minutes) — the Stripe industry
-     * norm. Pass 0 to disable the check (not recommended in production).
-     */
-    toleranceSeconds?: number;
-    /** Override for testing — defaults to `Date.now()`. */
-    now?: () => number;
-}
-/**
- * Verify an AgentChat webhook signature and return the parsed payload.
- *
- * Security-critical path — read carefully before changing:
- *
- * 1. Signature parsed from the header using a tolerant format
- *    (`t=…,v1=…`) that matches the documented wire shape. The `v1` scheme
- *    prefix lets us rotate to `v2` later without breaking old receivers.
- * 2. HMAC computed over `${timestamp}.${body}` with the caller's secret.
- * 3. Constant-time compare against the provided digest — a length-variance
- *    `===` compare would leak timing info about secret bytes.
- * 4. Timestamp check bounds replay windows. The default 5-minute
- *    tolerance is a deliberate trade between clock skew on the sender
- *    and replay resistance on the receiver.
- *
- * Returns the parsed `WebhookPayload` on success, throws
- * `WebhookVerificationError` on any failure (with `reason` set).
- */
-declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPayload>;
-
 /**
  * Parses `Retry-After` per RFC 9110:
  *   - Non-negative integer → seconds from now
@@ -1669,4 +1752,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
 
 declare const VERSION: string;
 
-export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientIdentity, type AgentChatClientKind, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentConversationContext, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type RenderOptions, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, type SyncEnvelope, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext, verifyWebhook };
+export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientIdentity, type AgentChatClientKind, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentConversationContext, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DirectConversationLookup, type DisconnectHandler, EmailExhaustedError, EmailLimitReachedError, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, HandleRequiredError, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RecoverOptions, type RecoverRequest, type RecoverResult, type RegisterRequest, type RenderOptions, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, type SyncEnvelope, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext };