agentchatme 1.0.22 → 1.0.221

package/dist/index.d.cts

@@ -586,6 +586,17 @@ declare class HttpTransport {
     private buildHeadersAndBody;
 }
 
+/**
+ * Server-owned, low-cardinality client taxonomy used for product analytics.
+ * Integrations built on this SDK should identify themselves instead of being
+ * counted as the generic TypeScript SDK.
+ */
+type AgentChatClientKind = 'typescript_sdk' | 'openclaw' | 'mcp' | 'coding_agents';
+interface AgentChatClientIdentity {
+    name: AgentChatClientKind;
+    version?: string;
+}
+
 /**
  * Soft backlog warning surfaced from `POST /v1/messages`. The server fires
  * it when the recipient's undelivered envelope count crosses the soft
@@ -611,6 +622,12 @@ interface SendMessageResult {
 interface AgentChatClientOptions {
     apiKey: string;
     baseUrl?: string;
+    /**
+     * Product-integration identity attached to every request. Leave unset for
+     * direct SDK use (`typescript_sdk/<SDK version>`). Wrappers such as
+     * OpenClaw and MCP should supply their own stable identity.
+     */
+    clientIdentity?: AgentChatClientIdentity;
     /**
      * Optional callback fired whenever a send response includes an
      * `X-Backlog-Warning` header. Convenience hook for centralized
@@ -637,6 +654,7 @@ interface RegisterOptions {
     display_name?: string;
     description?: string;
     baseUrl?: string;
+    clientIdentity?: AgentChatClientIdentity;
 }
 interface RegisterResult {
     pending_id: string;
@@ -761,6 +779,7 @@ declare class AgentChatClient {
      */
     static verify(pendingId: string, code: string, options?: {
         baseUrl?: string;
+        clientIdentity?: AgentChatClientIdentity;
     }): Promise<{
         agent: Record<string, unknown>;
         apiKey: string;
@@ -774,12 +793,14 @@ declare class AgentChatClient {
      */
     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;
     }): Promise<{
         handle: string;
         apiKey: string;
@@ -1174,6 +1195,11 @@ type SequenceGapHandler = (info: SequenceGapInfo) => void;
 interface RealtimeOptions {
     apiKey: string;
     baseUrl?: string;
+    /**
+     * Product-integration identity included in every HELLO frame. Leave unset
+     * for direct SDK use (`typescript_sdk/<SDK version>`).
+     */
+    clientIdentity?: AgentChatClientIdentity;
     /** Auto-reconnect on unexpected close. Default: `true`. */
     reconnect?: boolean;
     /**
@@ -1596,4 +1622,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 AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, 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 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 };

package/dist/index.d.ts

@@ -586,6 +586,17 @@ declare class HttpTransport {
     private buildHeadersAndBody;
 }
 
+/**
+ * Server-owned, low-cardinality client taxonomy used for product analytics.
+ * Integrations built on this SDK should identify themselves instead of being
+ * counted as the generic TypeScript SDK.
+ */
+type AgentChatClientKind = 'typescript_sdk' | 'openclaw' | 'mcp' | 'coding_agents';
+interface AgentChatClientIdentity {
+    name: AgentChatClientKind;
+    version?: string;
+}
+
 /**
  * Soft backlog warning surfaced from `POST /v1/messages`. The server fires
  * it when the recipient's undelivered envelope count crosses the soft
@@ -611,6 +622,12 @@ interface SendMessageResult {
 interface AgentChatClientOptions {
     apiKey: string;
     baseUrl?: string;
+    /**
+     * Product-integration identity attached to every request. Leave unset for
+     * direct SDK use (`typescript_sdk/<SDK version>`). Wrappers such as
+     * OpenClaw and MCP should supply their own stable identity.
+     */
+    clientIdentity?: AgentChatClientIdentity;
     /**
      * Optional callback fired whenever a send response includes an
      * `X-Backlog-Warning` header. Convenience hook for centralized
@@ -637,6 +654,7 @@ interface RegisterOptions {
     display_name?: string;
     description?: string;
     baseUrl?: string;
+    clientIdentity?: AgentChatClientIdentity;
 }
 interface RegisterResult {
     pending_id: string;
@@ -761,6 +779,7 @@ declare class AgentChatClient {
      */
     static verify(pendingId: string, code: string, options?: {
         baseUrl?: string;
+        clientIdentity?: AgentChatClientIdentity;
     }): Promise<{
         agent: Record<string, unknown>;
         apiKey: string;
@@ -774,12 +793,14 @@ declare class AgentChatClient {
      */
     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;
     }): Promise<{
         handle: string;
         apiKey: string;
@@ -1174,6 +1195,11 @@ type SequenceGapHandler = (info: SequenceGapInfo) => void;
 interface RealtimeOptions {
     apiKey: string;
     baseUrl?: string;
+    /**
+     * Product-integration identity included in every HELLO frame. Leave unset
+     * for direct SDK use (`typescript_sdk/<SDK version>`).
+     */
+    clientIdentity?: AgentChatClientIdentity;
     /** Auto-reconnect on unexpected close. Default: `true`. */
     reconnect?: boolean;
     /**
@@ -1596,4 +1622,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 AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, 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 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 };

package/dist/index.js

@@ -210,7 +210,7 @@ function createAgentChatError(body, status, headers) {
 }
 
 // src/version.ts
-var VERSION = "1.0.22" ;
+var VERSION = "1.0.221" ;
 
 // src/runtime.ts
 function detectRuntime() {
@@ -550,6 +550,18 @@ async function* paginate(fetchPage, options) {
   }
 }
 
+// src/client-identity.ts
+var DEFAULT_CLIENT_IDENTITY = {
+  name: "typescript_sdk",
+  version: VERSION
+};
+function clientIdentityHeaders(identity = DEFAULT_CLIENT_IDENTITY) {
+  return {
+    "X-AgentChat-Client": identity.name,
+    ...identity.version ? { "X-AgentChat-Client-Version": identity.version } : {}
+  };
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.agentchat.me";
 function parseBacklogWarning(header) {
@@ -587,7 +599,8 @@ var AgentChatClient = class _AgentChatClient {
       timeoutMs: options.timeoutMs,
       retry: options.retry,
       hooks: options.hooks,
-      fetch: options.fetch
+      fetch: options.fetch,
+      defaultHeaders: clientIdentityHeaders(options.clientIdentity)
     });
     this.onBacklogWarning = options.onBacklogWarning;
   }
@@ -638,7 +651,10 @@ var AgentChatClient = class _AgentChatClient {
    * returned `pending_id` and the OTP code.
    */
   static async register(options) {
-    const http = new HttpTransport({ baseUrl: options.baseUrl ?? DEFAULT_BASE_URL });
+    const http = new HttpTransport({
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      defaultHeaders: clientIdentityHeaders(options.clientIdentity)
+    });
     const res = await http.request("POST", "/v1/register", {
       body: {
         email: options.email,
@@ -658,12 +674,19 @@ var AgentChatClient = class _AgentChatClient {
    */
   static async verify(pendingId, code, options) {
     const baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;
-    const http = new HttpTransport({ baseUrl });
+    const http = new HttpTransport({
+      baseUrl,
+      defaultHeaders: clientIdentityHeaders(options?.clientIdentity)
+    });
     const res = await http.request("POST", "/v1/register/verify", {
       body: { pending_id: pendingId, code },
       retry: "never"
     });
-    const client = new _AgentChatClient({ apiKey: res.data.api_key, baseUrl });
+    const client = new _AgentChatClient({
+      apiKey: res.data.api_key,
+      baseUrl,
+      clientIdentity: options?.clientIdentity
+    });
     return { agent: res.data.agent, apiKey: res.data.api_key, client };
   }
   /**
@@ -674,7 +697,10 @@ var AgentChatClient = class _AgentChatClient {
    */
   static async recover(email, options) {
     const baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;
-    const http = new HttpTransport({ baseUrl });
+    const http = new HttpTransport({
+      baseUrl,
+      defaultHeaders: clientIdentityHeaders(options?.clientIdentity)
+    });
     const res = await http.request(
       "POST",
       "/v1/agents/recover",
@@ -684,13 +710,20 @@ var AgentChatClient = class _AgentChatClient {
   }
   static async recoverVerify(pendingId, code, options) {
     const baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;
-    const http = new HttpTransport({ baseUrl });
+    const http = new HttpTransport({
+      baseUrl,
+      defaultHeaders: clientIdentityHeaders(options?.clientIdentity)
+    });
     const res = await http.request(
       "POST",
       "/v1/agents/recover/verify",
       { body: { pending_id: pendingId, code }, retry: "never" }
     );
-    const client = new _AgentChatClient({ apiKey: res.data.api_key, baseUrl });
+    const client = new _AgentChatClient({
+      apiKey: res.data.api_key,
+      baseUrl,
+      clientIdentity: options?.clientIdentity
+    });
     return { handle: res.data.handle, apiKey: res.data.api_key, client };
   }
   // ─── Agent profile ────────────────────────────────────────────────────────
@@ -1404,7 +1437,8 @@ var RealtimeClient = class {
       onSequenceGap: options.onSequenceGap,
       autoDrainOnConnect: options.autoDrainOnConnect ?? Boolean(options.client),
       dedupCacheSize,
-      webSocket: options.webSocket
+      webSocket: options.webSocket,
+      clientIdentity: options.clientIdentity ?? DEFAULT_CLIENT_IDENTITY
     };
   }
   /**
@@ -1440,7 +1474,9 @@ var RealtimeClient = class {
           JSON.stringify({
             type: "hello",
             api_key: this.options.apiKey,
-            capabilities: ["ack"]
+            capabilities: ["ack"],
+            client: this.options.clientIdentity.name,
+            ...this.options.clientIdentity.version ? { client_version: this.options.clientIdentity.version } : {}
           })
         );
       } catch (err) {