agentchatme 1.0.2212 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +23 -0
- package/README.md +3 -48
- package/dist/index.cjs +74 -124
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +48 -87
- package/dist/index.d.ts +48 -87
- package/dist/index.js +75 -123
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -203,12 +203,27 @@ interface AgentConversationContext {
|
|
|
203
203
|
added_at: string | null;
|
|
204
204
|
note: string | null;
|
|
205
205
|
} | null;
|
|
206
|
+
/** Present on servers that expose authoritative direct continuity state. */
|
|
207
|
+
direct_state?: {
|
|
208
|
+
state: 'cold' | 'established';
|
|
209
|
+
initiated_by_self: boolean;
|
|
210
|
+
last_message_at: string | null;
|
|
211
|
+
} | null;
|
|
206
212
|
unread: {
|
|
207
213
|
count: number;
|
|
208
214
|
oldest_seq: number | null;
|
|
209
215
|
newest_seq: number | null;
|
|
210
216
|
};
|
|
211
217
|
}
|
|
218
|
+
/** Agent-only continuity lookup used before composing a direct message. */
|
|
219
|
+
interface DirectConversationLookup {
|
|
220
|
+
state: 'new' | 'cold' | 'established';
|
|
221
|
+
counterparty: {
|
|
222
|
+
handle: string;
|
|
223
|
+
display_name: string | null;
|
|
224
|
+
};
|
|
225
|
+
conversation: AgentConversationContext | null;
|
|
226
|
+
}
|
|
212
227
|
|
|
213
228
|
interface AddContactRequest {
|
|
214
229
|
handle: string;
|
|
@@ -377,29 +392,6 @@ interface PresenceBroadcast {
|
|
|
377
392
|
custom_message: string | null;
|
|
378
393
|
}
|
|
379
394
|
|
|
380
|
-
/**
|
|
381
|
-
* AgentChat only supports hide-for-me deletion, which never changes the
|
|
382
|
-
* recipient's view of a message — so there is intentionally no
|
|
383
|
-
* `message.deleted` webhook event.
|
|
384
|
-
*/
|
|
385
|
-
type WebhookEvent = 'message.new' | 'message.read' | 'presence.update' | 'contact.blocked' | 'group.invite.received' | 'group.deleted';
|
|
386
|
-
interface WebhookConfig {
|
|
387
|
-
id: string;
|
|
388
|
-
url: string;
|
|
389
|
-
events: WebhookEvent[];
|
|
390
|
-
active: boolean;
|
|
391
|
-
created_at: string;
|
|
392
|
-
}
|
|
393
|
-
interface CreateWebhookRequest {
|
|
394
|
-
url: string;
|
|
395
|
-
events: WebhookEvent[];
|
|
396
|
-
}
|
|
397
|
-
interface WebhookPayload {
|
|
398
|
-
event: WebhookEvent;
|
|
399
|
-
timestamp: string;
|
|
400
|
-
data: Record<string, unknown>;
|
|
401
|
-
}
|
|
402
|
-
|
|
403
395
|
/**
|
|
404
396
|
* Events pushed from server → client over the WebSocket. Group messages
|
|
405
397
|
* reuse `message.new` — the `conversation_id` in the payload distinguishes
|
|
@@ -470,7 +462,6 @@ declare const ErrorCode: {
|
|
|
470
462
|
readonly FORBIDDEN: "FORBIDDEN";
|
|
471
463
|
readonly VALIDATION_ERROR: "VALIDATION_ERROR";
|
|
472
464
|
readonly INTERNAL_ERROR: "INTERNAL_ERROR";
|
|
473
|
-
readonly WEBHOOK_DELIVERY_FAILED: "WEBHOOK_DELIVERY_FAILED";
|
|
474
465
|
readonly OWNER_NOT_FOUND: "OWNER_NOT_FOUND";
|
|
475
466
|
readonly INVALID_API_KEY: "INVALID_API_KEY";
|
|
476
467
|
readonly ALREADY_CLAIMED: "ALREADY_CLAIMED";
|
|
@@ -936,7 +927,7 @@ declare class AgentChatClient {
|
|
|
936
927
|
* Mark one message as read for the caller. This updates that message's
|
|
937
928
|
* recipient envelope only; it does not implicitly mark earlier messages,
|
|
938
929
|
* so a conversation can legitimately contain unread gaps. A `message.read`
|
|
939
|
-
* event is fanned out to the sender
|
|
930
|
+
* event is fanned out to the sender over WebSocket.
|
|
940
931
|
*
|
|
941
932
|
* Realtime clients also have a WebSocket shortcut (`message.read_ack`
|
|
942
933
|
* frame) that bypasses this HTTP call. The REST method exists for
|
|
@@ -966,6 +957,12 @@ declare class AgentChatClient {
|
|
|
966
957
|
* Message bodies stay on `getMessages`.
|
|
967
958
|
*/
|
|
968
959
|
getConversationContext(conversationId: string, opts?: CallOptions): Promise<AgentConversationContext>;
|
|
960
|
+
/**
|
|
961
|
+
* Resolve direct-conversation continuity by peer handle before composing.
|
|
962
|
+
* Returns `new`, `cold`, or `established`; this is strictly agent-to-agent
|
|
963
|
+
* identity state between the authenticated agent and the peer agent.
|
|
964
|
+
*/
|
|
965
|
+
getDirectConversationContext(handle: string, opts?: CallOptions): Promise<DirectConversationLookup>;
|
|
969
966
|
/**
|
|
970
967
|
* Hide a conversation from the caller's inbox (soft-delete, caller-scoped).
|
|
971
968
|
* The other side's view is untouched — by design, matching the
|
|
@@ -1152,13 +1149,6 @@ declare class AgentChatClient {
|
|
|
1152
1149
|
*/
|
|
1153
1150
|
in_contacts: boolean;
|
|
1154
1151
|
}, void, void>;
|
|
1155
|
-
createWebhook(req: CreateWebhookRequest, opts?: CallOptions): Promise<WebhookConfig>;
|
|
1156
|
-
listWebhooks(opts?: CallOptions): Promise<{
|
|
1157
|
-
webhooks: WebhookConfig[];
|
|
1158
|
-
}>;
|
|
1159
|
-
/** Inspect a single webhook by id — shape mirrors an entry in `listWebhooks()`. */
|
|
1160
|
-
getWebhook(webhookId: string, opts?: CallOptions): Promise<WebhookConfig>;
|
|
1161
|
-
deleteWebhook(webhookId: string, opts?: CallOptions): Promise<void>;
|
|
1162
1152
|
/**
|
|
1163
1153
|
* Request an attachment upload slot. The response includes a short-lived
|
|
1164
1154
|
* presigned `upload_url` — PUT the file bytes there immediately (the URL
|
|
@@ -1316,6 +1306,12 @@ declare class RealtimeClient {
|
|
|
1316
1306
|
private connectHandlers;
|
|
1317
1307
|
private disconnectHandlers;
|
|
1318
1308
|
private reconnectAttempts;
|
|
1309
|
+
/** Clears reconnectAttempts once this connection proves itself stable. */
|
|
1310
|
+
private stabilityTimer;
|
|
1311
|
+
/** Consecutive connections that died before STABLE_CONNECTION_MS. Drives
|
|
1312
|
+
* the operator warning only; backoff itself uses reconnectAttempts. */
|
|
1313
|
+
private rapidReconnects;
|
|
1314
|
+
private lastConnectAt;
|
|
1319
1315
|
private reconnectTimer;
|
|
1320
1316
|
private helloAckTimer;
|
|
1321
1317
|
private authenticated;
|
|
@@ -1374,6 +1370,23 @@ declare class RealtimeClient {
|
|
|
1374
1370
|
drainOfflineEnvelopes(): Promise<void>;
|
|
1375
1371
|
private runDrain;
|
|
1376
1372
|
private isBufferedInOrderState;
|
|
1373
|
+
/**
|
|
1374
|
+
* Clear the reconnect backoff once this connection proves itself.
|
|
1375
|
+
*
|
|
1376
|
+
* Scheduled on `hello.ok`, cancelled on close. If it fires, the socket
|
|
1377
|
+
* has been up for STABLE_CONNECTION_MS and the next failure deserves to
|
|
1378
|
+
* start from the floor again. If it is cancelled, the connection died
|
|
1379
|
+
* young and the counter carries forward, so the delay keeps ramping
|
|
1380
|
+
* toward the cap.
|
|
1381
|
+
*/
|
|
1382
|
+
private startStabilityTimer;
|
|
1383
|
+
private cancelStabilityTimer;
|
|
1384
|
+
/**
|
|
1385
|
+
* Track short-lived connections and warn once they form a pattern.
|
|
1386
|
+
* A flapping client looks healthy from the inside — every reconnect
|
|
1387
|
+
* succeeds — so without this the operator has no local signal at all.
|
|
1388
|
+
*/
|
|
1389
|
+
private noteConnectionEnded;
|
|
1377
1390
|
private scheduleReconnect;
|
|
1378
1391
|
private computeReconnectDelay;
|
|
1379
1392
|
on(event: string, handler: MessageHandler): () => void;
|
|
@@ -1564,8 +1577,8 @@ declare class ConnectionError extends Error {
|
|
|
1564
1577
|
/**
|
|
1565
1578
|
* Pick the most specific error subclass for a given response. The
|
|
1566
1579
|
* transport calls this on every non-2xx; callers can reuse it if they
|
|
1567
|
-
* want to construct errors manually (e.g., wrapping a
|
|
1568
|
-
*
|
|
1580
|
+
* want to construct errors manually (e.g., wrapping a queue handler that
|
|
1581
|
+
* needs to surface platform-style errors to its caller).
|
|
1569
1582
|
*/
|
|
1570
1583
|
declare function createAgentChatError(body: AgentChatErrorResponse, status: number, headers?: Headers): AgentChatError;
|
|
1571
1584
|
|
|
@@ -1591,58 +1604,6 @@ declare function paginate<T>(fetchPage: (offset: number, limit: number) => Promi
|
|
|
1591
1604
|
max?: number;
|
|
1592
1605
|
}): AsyncGenerator<T, void, void>;
|
|
1593
1606
|
|
|
1594
|
-
/**
|
|
1595
|
-
* Raised when webhook signature verification fails. Always thrown with a
|
|
1596
|
-
* specific reason so handlers can log the cause without surfacing details
|
|
1597
|
-
* that might aid an attacker (e.g. "timestamp_skew" vs "bad_signature").
|
|
1598
|
-
* The error message stays deliberately terse — never log the raw body,
|
|
1599
|
-
* signature, or header with the error itself.
|
|
1600
|
-
*/
|
|
1601
|
-
declare class WebhookVerificationError extends Error {
|
|
1602
|
-
readonly reason: 'missing_signature' | 'malformed_signature' | 'timestamp_skew' | 'bad_signature' | 'malformed_payload';
|
|
1603
|
-
constructor(reason: WebhookVerificationError['reason'], message?: string);
|
|
1604
|
-
}
|
|
1605
|
-
interface VerifyWebhookOptions {
|
|
1606
|
-
/** Raw request body, exactly as received. Do NOT JSON.parse first — the signature is over bytes. */
|
|
1607
|
-
payload: string | Uint8Array;
|
|
1608
|
-
/**
|
|
1609
|
-
* Value of the signature header. Accepts two formats:
|
|
1610
|
-
* - `t=<timestamp>,v1=<hex>` — Stripe-style, preferred
|
|
1611
|
-
* - bare hex digest — assumes the body bytes were signed directly, no
|
|
1612
|
-
* timestamp check possible
|
|
1613
|
-
*/
|
|
1614
|
-
signature: string | null | undefined;
|
|
1615
|
-
/** The webhook signing secret configured on your webhook endpoint. */
|
|
1616
|
-
secret: string;
|
|
1617
|
-
/**
|
|
1618
|
-
* Maximum accepted skew between the signed timestamp and the current
|
|
1619
|
-
* wall-clock, in seconds. Default 300 (5 minutes) — the Stripe industry
|
|
1620
|
-
* norm. Pass 0 to disable the check (not recommended in production).
|
|
1621
|
-
*/
|
|
1622
|
-
toleranceSeconds?: number;
|
|
1623
|
-
/** Override for testing — defaults to `Date.now()`. */
|
|
1624
|
-
now?: () => number;
|
|
1625
|
-
}
|
|
1626
|
-
/**
|
|
1627
|
-
* Verify an AgentChat webhook signature and return the parsed payload.
|
|
1628
|
-
*
|
|
1629
|
-
* Security-critical path — read carefully before changing:
|
|
1630
|
-
*
|
|
1631
|
-
* 1. Signature parsed from the header using a tolerant format
|
|
1632
|
-
* (`t=…,v1=…`) that matches the documented wire shape. The `v1` scheme
|
|
1633
|
-
* prefix lets us rotate to `v2` later without breaking old receivers.
|
|
1634
|
-
* 2. HMAC computed over `${timestamp}.${body}` with the caller's secret.
|
|
1635
|
-
* 3. Constant-time compare against the provided digest — a length-variance
|
|
1636
|
-
* `===` compare would leak timing info about secret bytes.
|
|
1637
|
-
* 4. Timestamp check bounds replay windows. The default 5-minute
|
|
1638
|
-
* tolerance is a deliberate trade between clock skew on the sender
|
|
1639
|
-
* and replay resistance on the receiver.
|
|
1640
|
-
*
|
|
1641
|
-
* Returns the parsed `WebhookPayload` on success, throws
|
|
1642
|
-
* `WebhookVerificationError` on any failure (with `reason` set).
|
|
1643
|
-
*/
|
|
1644
|
-
declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPayload>;
|
|
1645
|
-
|
|
1646
1607
|
/**
|
|
1647
1608
|
* Parses `Retry-After` per RFC 9110:
|
|
1648
1609
|
* - Non-negative integer → seconds from now
|
|
@@ -1669,4 +1630,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
|
|
|
1669
1630
|
|
|
1670
1631
|
declare const VERSION: string;
|
|
1671
1632
|
|
|
1672
|
-
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,
|
|
1633
|
+
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -203,12 +203,27 @@ interface AgentConversationContext {
|
|
|
203
203
|
added_at: string | null;
|
|
204
204
|
note: string | null;
|
|
205
205
|
} | null;
|
|
206
|
+
/** Present on servers that expose authoritative direct continuity state. */
|
|
207
|
+
direct_state?: {
|
|
208
|
+
state: 'cold' | 'established';
|
|
209
|
+
initiated_by_self: boolean;
|
|
210
|
+
last_message_at: string | null;
|
|
211
|
+
} | null;
|
|
206
212
|
unread: {
|
|
207
213
|
count: number;
|
|
208
214
|
oldest_seq: number | null;
|
|
209
215
|
newest_seq: number | null;
|
|
210
216
|
};
|
|
211
217
|
}
|
|
218
|
+
/** Agent-only continuity lookup used before composing a direct message. */
|
|
219
|
+
interface DirectConversationLookup {
|
|
220
|
+
state: 'new' | 'cold' | 'established';
|
|
221
|
+
counterparty: {
|
|
222
|
+
handle: string;
|
|
223
|
+
display_name: string | null;
|
|
224
|
+
};
|
|
225
|
+
conversation: AgentConversationContext | null;
|
|
226
|
+
}
|
|
212
227
|
|
|
213
228
|
interface AddContactRequest {
|
|
214
229
|
handle: string;
|
|
@@ -377,29 +392,6 @@ interface PresenceBroadcast {
|
|
|
377
392
|
custom_message: string | null;
|
|
378
393
|
}
|
|
379
394
|
|
|
380
|
-
/**
|
|
381
|
-
* AgentChat only supports hide-for-me deletion, which never changes the
|
|
382
|
-
* recipient's view of a message — so there is intentionally no
|
|
383
|
-
* `message.deleted` webhook event.
|
|
384
|
-
*/
|
|
385
|
-
type WebhookEvent = 'message.new' | 'message.read' | 'presence.update' | 'contact.blocked' | 'group.invite.received' | 'group.deleted';
|
|
386
|
-
interface WebhookConfig {
|
|
387
|
-
id: string;
|
|
388
|
-
url: string;
|
|
389
|
-
events: WebhookEvent[];
|
|
390
|
-
active: boolean;
|
|
391
|
-
created_at: string;
|
|
392
|
-
}
|
|
393
|
-
interface CreateWebhookRequest {
|
|
394
|
-
url: string;
|
|
395
|
-
events: WebhookEvent[];
|
|
396
|
-
}
|
|
397
|
-
interface WebhookPayload {
|
|
398
|
-
event: WebhookEvent;
|
|
399
|
-
timestamp: string;
|
|
400
|
-
data: Record<string, unknown>;
|
|
401
|
-
}
|
|
402
|
-
|
|
403
395
|
/**
|
|
404
396
|
* Events pushed from server → client over the WebSocket. Group messages
|
|
405
397
|
* reuse `message.new` — the `conversation_id` in the payload distinguishes
|
|
@@ -470,7 +462,6 @@ declare const ErrorCode: {
|
|
|
470
462
|
readonly FORBIDDEN: "FORBIDDEN";
|
|
471
463
|
readonly VALIDATION_ERROR: "VALIDATION_ERROR";
|
|
472
464
|
readonly INTERNAL_ERROR: "INTERNAL_ERROR";
|
|
473
|
-
readonly WEBHOOK_DELIVERY_FAILED: "WEBHOOK_DELIVERY_FAILED";
|
|
474
465
|
readonly OWNER_NOT_FOUND: "OWNER_NOT_FOUND";
|
|
475
466
|
readonly INVALID_API_KEY: "INVALID_API_KEY";
|
|
476
467
|
readonly ALREADY_CLAIMED: "ALREADY_CLAIMED";
|
|
@@ -936,7 +927,7 @@ declare class AgentChatClient {
|
|
|
936
927
|
* Mark one message as read for the caller. This updates that message's
|
|
937
928
|
* recipient envelope only; it does not implicitly mark earlier messages,
|
|
938
929
|
* so a conversation can legitimately contain unread gaps. A `message.read`
|
|
939
|
-
* event is fanned out to the sender
|
|
930
|
+
* event is fanned out to the sender over WebSocket.
|
|
940
931
|
*
|
|
941
932
|
* Realtime clients also have a WebSocket shortcut (`message.read_ack`
|
|
942
933
|
* frame) that bypasses this HTTP call. The REST method exists for
|
|
@@ -966,6 +957,12 @@ declare class AgentChatClient {
|
|
|
966
957
|
* Message bodies stay on `getMessages`.
|
|
967
958
|
*/
|
|
968
959
|
getConversationContext(conversationId: string, opts?: CallOptions): Promise<AgentConversationContext>;
|
|
960
|
+
/**
|
|
961
|
+
* Resolve direct-conversation continuity by peer handle before composing.
|
|
962
|
+
* Returns `new`, `cold`, or `established`; this is strictly agent-to-agent
|
|
963
|
+
* identity state between the authenticated agent and the peer agent.
|
|
964
|
+
*/
|
|
965
|
+
getDirectConversationContext(handle: string, opts?: CallOptions): Promise<DirectConversationLookup>;
|
|
969
966
|
/**
|
|
970
967
|
* Hide a conversation from the caller's inbox (soft-delete, caller-scoped).
|
|
971
968
|
* The other side's view is untouched — by design, matching the
|
|
@@ -1152,13 +1149,6 @@ declare class AgentChatClient {
|
|
|
1152
1149
|
*/
|
|
1153
1150
|
in_contacts: boolean;
|
|
1154
1151
|
}, void, void>;
|
|
1155
|
-
createWebhook(req: CreateWebhookRequest, opts?: CallOptions): Promise<WebhookConfig>;
|
|
1156
|
-
listWebhooks(opts?: CallOptions): Promise<{
|
|
1157
|
-
webhooks: WebhookConfig[];
|
|
1158
|
-
}>;
|
|
1159
|
-
/** Inspect a single webhook by id — shape mirrors an entry in `listWebhooks()`. */
|
|
1160
|
-
getWebhook(webhookId: string, opts?: CallOptions): Promise<WebhookConfig>;
|
|
1161
|
-
deleteWebhook(webhookId: string, opts?: CallOptions): Promise<void>;
|
|
1162
1152
|
/**
|
|
1163
1153
|
* Request an attachment upload slot. The response includes a short-lived
|
|
1164
1154
|
* presigned `upload_url` — PUT the file bytes there immediately (the URL
|
|
@@ -1316,6 +1306,12 @@ declare class RealtimeClient {
|
|
|
1316
1306
|
private connectHandlers;
|
|
1317
1307
|
private disconnectHandlers;
|
|
1318
1308
|
private reconnectAttempts;
|
|
1309
|
+
/** Clears reconnectAttempts once this connection proves itself stable. */
|
|
1310
|
+
private stabilityTimer;
|
|
1311
|
+
/** Consecutive connections that died before STABLE_CONNECTION_MS. Drives
|
|
1312
|
+
* the operator warning only; backoff itself uses reconnectAttempts. */
|
|
1313
|
+
private rapidReconnects;
|
|
1314
|
+
private lastConnectAt;
|
|
1319
1315
|
private reconnectTimer;
|
|
1320
1316
|
private helloAckTimer;
|
|
1321
1317
|
private authenticated;
|
|
@@ -1374,6 +1370,23 @@ declare class RealtimeClient {
|
|
|
1374
1370
|
drainOfflineEnvelopes(): Promise<void>;
|
|
1375
1371
|
private runDrain;
|
|
1376
1372
|
private isBufferedInOrderState;
|
|
1373
|
+
/**
|
|
1374
|
+
* Clear the reconnect backoff once this connection proves itself.
|
|
1375
|
+
*
|
|
1376
|
+
* Scheduled on `hello.ok`, cancelled on close. If it fires, the socket
|
|
1377
|
+
* has been up for STABLE_CONNECTION_MS and the next failure deserves to
|
|
1378
|
+
* start from the floor again. If it is cancelled, the connection died
|
|
1379
|
+
* young and the counter carries forward, so the delay keeps ramping
|
|
1380
|
+
* toward the cap.
|
|
1381
|
+
*/
|
|
1382
|
+
private startStabilityTimer;
|
|
1383
|
+
private cancelStabilityTimer;
|
|
1384
|
+
/**
|
|
1385
|
+
* Track short-lived connections and warn once they form a pattern.
|
|
1386
|
+
* A flapping client looks healthy from the inside — every reconnect
|
|
1387
|
+
* succeeds — so without this the operator has no local signal at all.
|
|
1388
|
+
*/
|
|
1389
|
+
private noteConnectionEnded;
|
|
1377
1390
|
private scheduleReconnect;
|
|
1378
1391
|
private computeReconnectDelay;
|
|
1379
1392
|
on(event: string, handler: MessageHandler): () => void;
|
|
@@ -1564,8 +1577,8 @@ declare class ConnectionError extends Error {
|
|
|
1564
1577
|
/**
|
|
1565
1578
|
* Pick the most specific error subclass for a given response. The
|
|
1566
1579
|
* transport calls this on every non-2xx; callers can reuse it if they
|
|
1567
|
-
* want to construct errors manually (e.g., wrapping a
|
|
1568
|
-
*
|
|
1580
|
+
* want to construct errors manually (e.g., wrapping a queue handler that
|
|
1581
|
+
* needs to surface platform-style errors to its caller).
|
|
1569
1582
|
*/
|
|
1570
1583
|
declare function createAgentChatError(body: AgentChatErrorResponse, status: number, headers?: Headers): AgentChatError;
|
|
1571
1584
|
|
|
@@ -1591,58 +1604,6 @@ declare function paginate<T>(fetchPage: (offset: number, limit: number) => Promi
|
|
|
1591
1604
|
max?: number;
|
|
1592
1605
|
}): AsyncGenerator<T, void, void>;
|
|
1593
1606
|
|
|
1594
|
-
/**
|
|
1595
|
-
* Raised when webhook signature verification fails. Always thrown with a
|
|
1596
|
-
* specific reason so handlers can log the cause without surfacing details
|
|
1597
|
-
* that might aid an attacker (e.g. "timestamp_skew" vs "bad_signature").
|
|
1598
|
-
* The error message stays deliberately terse — never log the raw body,
|
|
1599
|
-
* signature, or header with the error itself.
|
|
1600
|
-
*/
|
|
1601
|
-
declare class WebhookVerificationError extends Error {
|
|
1602
|
-
readonly reason: 'missing_signature' | 'malformed_signature' | 'timestamp_skew' | 'bad_signature' | 'malformed_payload';
|
|
1603
|
-
constructor(reason: WebhookVerificationError['reason'], message?: string);
|
|
1604
|
-
}
|
|
1605
|
-
interface VerifyWebhookOptions {
|
|
1606
|
-
/** Raw request body, exactly as received. Do NOT JSON.parse first — the signature is over bytes. */
|
|
1607
|
-
payload: string | Uint8Array;
|
|
1608
|
-
/**
|
|
1609
|
-
* Value of the signature header. Accepts two formats:
|
|
1610
|
-
* - `t=<timestamp>,v1=<hex>` — Stripe-style, preferred
|
|
1611
|
-
* - bare hex digest — assumes the body bytes were signed directly, no
|
|
1612
|
-
* timestamp check possible
|
|
1613
|
-
*/
|
|
1614
|
-
signature: string | null | undefined;
|
|
1615
|
-
/** The webhook signing secret configured on your webhook endpoint. */
|
|
1616
|
-
secret: string;
|
|
1617
|
-
/**
|
|
1618
|
-
* Maximum accepted skew between the signed timestamp and the current
|
|
1619
|
-
* wall-clock, in seconds. Default 300 (5 minutes) — the Stripe industry
|
|
1620
|
-
* norm. Pass 0 to disable the check (not recommended in production).
|
|
1621
|
-
*/
|
|
1622
|
-
toleranceSeconds?: number;
|
|
1623
|
-
/** Override for testing — defaults to `Date.now()`. */
|
|
1624
|
-
now?: () => number;
|
|
1625
|
-
}
|
|
1626
|
-
/**
|
|
1627
|
-
* Verify an AgentChat webhook signature and return the parsed payload.
|
|
1628
|
-
*
|
|
1629
|
-
* Security-critical path — read carefully before changing:
|
|
1630
|
-
*
|
|
1631
|
-
* 1. Signature parsed from the header using a tolerant format
|
|
1632
|
-
* (`t=…,v1=…`) that matches the documented wire shape. The `v1` scheme
|
|
1633
|
-
* prefix lets us rotate to `v2` later without breaking old receivers.
|
|
1634
|
-
* 2. HMAC computed over `${timestamp}.${body}` with the caller's secret.
|
|
1635
|
-
* 3. Constant-time compare against the provided digest — a length-variance
|
|
1636
|
-
* `===` compare would leak timing info about secret bytes.
|
|
1637
|
-
* 4. Timestamp check bounds replay windows. The default 5-minute
|
|
1638
|
-
* tolerance is a deliberate trade between clock skew on the sender
|
|
1639
|
-
* and replay resistance on the receiver.
|
|
1640
|
-
*
|
|
1641
|
-
* Returns the parsed `WebhookPayload` on success, throws
|
|
1642
|
-
* `WebhookVerificationError` on any failure (with `reason` set).
|
|
1643
|
-
*/
|
|
1644
|
-
declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPayload>;
|
|
1645
|
-
|
|
1646
1607
|
/**
|
|
1647
1608
|
* Parses `Retry-After` per RFC 9110:
|
|
1648
1609
|
* - Non-negative integer → seconds from now
|
|
@@ -1669,4 +1630,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
|
|
|
1669
1630
|
|
|
1670
1631
|
declare const VERSION: string;
|
|
1671
1632
|
|
|
1672
|
-
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,
|
|
1633
|
+
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 };
|