agentchatme 1.1.0 → 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;
@@ -448,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";
@@ -687,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;
@@ -796,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>;
     /**
@@ -813,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;
@@ -1562,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);
@@ -1630,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, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DirectConversationLookup, 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 WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext };
+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 };

package/dist/index.d.ts

@@ -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;
@@ -448,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";
@@ -687,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;
@@ -796,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>;
     /**
@@ -813,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;
@@ -1562,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);
@@ -1630,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, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DirectConversationLookup, 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 WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext };
+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 };

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",
@@ -146,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);
@@ -193,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:
@@ -209,7 +268,7 @@ function createAgentChatError(body, status, headers) {
 }
 
 // src/version.ts
-var VERSION = "1.1.0" ;
+var VERSION = "1.1.1" ;
 
 // src/runtime.ts
 function detectRuntime() {
@@ -648,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({
@@ -689,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;
@@ -700,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({
@@ -2315,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, createAgentChatError, paginate, parseRetryAfter, renderMessageContext };
+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