@antzsoft/chat-core 1.4.5 → 1.4.6

package/dist/index.d.cts

@@ -395,17 +395,66 @@ declare function encryptPayload(data: unknown, sessionKey: AnySessionKey): Promi
 declare function decryptPayload(envelope: TransitEnvelope, sessionKey: AnySessionKey): Promise<unknown>;
 declare function isTransitEnvelope(v: unknown): v is TransitEnvelope;
 
+/**
+ * Caller identity attached to the pre-auth transit handshake requests.
+ *
+ * GET /crypto/pubkey and POST /crypto/session run BEFORE a transit session (and
+ * therefore before the authenticated axios client) exists, so they bypass the
+ * request interceptor that normally adds these headers. Without them the server
+ * can only rate-limit these two routes by client IP — which means every user
+ * behind one NAT, office proxy or ALB shares a single bucket, and one client's
+ * reload loop 429s everyone else.
+ *
+ * These values are NOT used for authentication: the endpoints are unauthenticated
+ * by design and the server treats the headers as a fairness hint only, with a
+ * per-IP ceiling underneath as the real abuse limit. Sending them is therefore
+ * safe, optional, and backward compatible — an older SDK that omits them simply
+ * falls back to the shared per-IP bucket.
+ */
+interface TransitIdentity {
+    /** External user id — same value sent as x-user-id on authenticated requests. */
+    userId?: string;
+    /** Tenant id — same value sent as X-Tenant-ID on authenticated requests. */
+    tenantId?: string;
+}
+/**
+ * How long the server asked us to wait, in ms, from a 429's Retry-After.
+ *
+ * The chat server runs TWO named rate-limit layers, and @nestjs/throttler
+ * suffixes its headers with the throttler name unless that name is literally
+ * "default". So a 429 carries `Retry-After-identity` or `Retry-After-ip`, not a
+ * bare `Retry-After`. Older servers and intermediary proxies may still send the
+ * bare name, so all three are read; when more than one is present the LONGER
+ * wait wins, since retrying before the slower bucket drains just earns another
+ * 429.
+ *
+ * Returns undefined when no variant is readable — in a browser that also
+ * happens when the server omits these from Access-Control-Expose-Headers, in
+ * which case callers must fall back to their own backoff.
+ */
+declare function readRetryAfterMs(headers: Headers): number | undefined;
+/**
+ * Thrown when the transit handshake is rate-limited (HTTP 429).
+ *
+ * Distinct from a generic failure because the correct response differs: a 429
+ * means "wait", not "this is broken", so callers must not burn their retry
+ * budget on it and should honour `retryAfterMs` when the server supplied it.
+ */
+declare class TransitRateLimitedError extends Error {
+    readonly retryAfterMs?: number;
+    constructor(retryAfterMs?: number);
+}
 interface ServerPublicKeys {
     x25519: string;
     p256: string;
     enabled: boolean;
 }
-declare function fetchServerKeys(apiUrl: string): Promise<ServerPublicKeys>;
+declare function fetchServerKeys(apiUrl: string, identity?: TransitIdentity): Promise<ServerPublicKeys>;
 declare function generateEphemeralKey(algo: TransitAlgo, serverKeys: ServerPublicKeys): Promise<{
     ephemeralPubB64: string;
     deriveSessionKey: (sessionId: string) => Promise<unknown>;
 }>;
-declare function createRestTransitSession(apiUrl: string): Promise<{
+declare function createRestTransitSession(apiUrl: string, identity?: TransitIdentity): Promise<{
     sessionId: string;
     sessionKey: CryptoKey | Uint8Array;
 } | null>;
@@ -799,4 +848,4 @@ declare class AntzChatClient {
     uploadIcon(conversationId: string, file: UploadableFile): Promise<Conversation>;
 }
 
-export { AntzChatAuthError, AntzChatClient, AntzChatConfig, AntzChatError, AntzChatNetworkError, AntzChatPermissionError, AntzChatServerError, AntzChatValidationError, AppConfig, AuthResponse, AuthTokens, BatchUploadResult, CompletedPart, Conversation, ConversationListParams, ConversationSyncResponse, ConversationUnreadCount, type CreateDirectData, type CreateGroupData, CrossConversationSyncResponse, CursorPaginatedResponse, FileResponse, FileType, ForwardAckPayload, ForwardMessagePayload, type ForwardResult, HIGHLY_FORWARDED_DEPTH_THRESHOLD, type LastReadEntry, type ListMessagesParams, LoginCredentials, MAX_FORWARD_TARGETS, type MentionPart, type MentionSegment, Message, MessageReactionsResponse, MessageReceiptsResponse, type MobileDeviceToken, PaginatedResponse, type ParsedMention, Participant, PersistStorage, PresignedUrlRequest, PresignedUrlResponse, RegisterData, type RegisterDeviceTokenPayload, ResolvedCompressionConfig, ResolvedConfig, type SearchParams, type SendData, SendMessagePayload, type SocketStatus, type StatusListener, type TokenStore, UnreadSummary, type UpdateConversationData, type UpdateProfilePayload, UploadableFile, User, UserPreferences, type WebPushDeviceToken, appConfigApi, authApi, buildMentionText, connectSocket, conversationsApi, createAuthStore, createRestTransitSession, decryptPayload, devicesApi, disconnectSocket, encryptPayload, extractMentionIds, fetchServerKeys, generateEphemeralKey, getApiClient, getAuthStore, getCompressionStrategy, getSessionId, getSessionKey, getSocket, getSocketStatus, initApiClient, initAuthStore, isApiClientConfigured, isMentionAll, isTransitEnvelope, messagesApi, normalizeAxiosError, normalizeConversation, onSocketStatus, parseMentions, performHandshake, reconnectSocket, refreshSocketAuth, renderMentionParts, resetAuthStore, resetTrackedRooms, resolveSystemMessageText, setApiClientInstance, setAuthReadyPromise, setTransitSession, socketEmit, syncApi, tryGetSocket, useChatStore, usersApi };
+export { AntzChatAuthError, AntzChatClient, AntzChatConfig, AntzChatError, AntzChatNetworkError, AntzChatPermissionError, AntzChatServerError, AntzChatValidationError, AppConfig, AuthResponse, AuthTokens, BatchUploadResult, CompletedPart, Conversation, ConversationListParams, ConversationSyncResponse, ConversationUnreadCount, type CreateDirectData, type CreateGroupData, CrossConversationSyncResponse, CursorPaginatedResponse, FileResponse, FileType, ForwardAckPayload, ForwardMessagePayload, type ForwardResult, HIGHLY_FORWARDED_DEPTH_THRESHOLD, type LastReadEntry, type ListMessagesParams, LoginCredentials, MAX_FORWARD_TARGETS, type MentionPart, type MentionSegment, Message, MessageReactionsResponse, MessageReceiptsResponse, type MobileDeviceToken, PaginatedResponse, type ParsedMention, Participant, PersistStorage, PresignedUrlRequest, PresignedUrlResponse, RegisterData, type RegisterDeviceTokenPayload, ResolvedCompressionConfig, ResolvedConfig, type SearchParams, type SendData, SendMessagePayload, type SocketStatus, type StatusListener, type TokenStore, type TransitIdentity, TransitRateLimitedError, UnreadSummary, type UpdateConversationData, type UpdateProfilePayload, UploadableFile, User, UserPreferences, type WebPushDeviceToken, appConfigApi, authApi, buildMentionText, connectSocket, conversationsApi, createAuthStore, createRestTransitSession, decryptPayload, devicesApi, disconnectSocket, encryptPayload, extractMentionIds, fetchServerKeys, generateEphemeralKey, getApiClient, getAuthStore, getCompressionStrategy, getSessionId, getSessionKey, getSocket, getSocketStatus, initApiClient, initAuthStore, isApiClientConfigured, isMentionAll, isTransitEnvelope, messagesApi, normalizeAxiosError, normalizeConversation, onSocketStatus, parseMentions, performHandshake, readRetryAfterMs, reconnectSocket, refreshSocketAuth, renderMentionParts, resetAuthStore, resetTrackedRooms, resolveSystemMessageText, setApiClientInstance, setAuthReadyPromise, setTransitSession, socketEmit, syncApi, tryGetSocket, useChatStore, usersApi };

package/dist/index.d.ts

@@ -395,17 +395,66 @@ declare function encryptPayload(data: unknown, sessionKey: AnySessionKey): Promi
 declare function decryptPayload(envelope: TransitEnvelope, sessionKey: AnySessionKey): Promise<unknown>;
 declare function isTransitEnvelope(v: unknown): v is TransitEnvelope;
 
+/**
+ * Caller identity attached to the pre-auth transit handshake requests.
+ *
+ * GET /crypto/pubkey and POST /crypto/session run BEFORE a transit session (and
+ * therefore before the authenticated axios client) exists, so they bypass the
+ * request interceptor that normally adds these headers. Without them the server
+ * can only rate-limit these two routes by client IP — which means every user
+ * behind one NAT, office proxy or ALB shares a single bucket, and one client's
+ * reload loop 429s everyone else.
+ *
+ * These values are NOT used for authentication: the endpoints are unauthenticated
+ * by design and the server treats the headers as a fairness hint only, with a
+ * per-IP ceiling underneath as the real abuse limit. Sending them is therefore
+ * safe, optional, and backward compatible — an older SDK that omits them simply
+ * falls back to the shared per-IP bucket.
+ */
+interface TransitIdentity {
+    /** External user id — same value sent as x-user-id on authenticated requests. */
+    userId?: string;
+    /** Tenant id — same value sent as X-Tenant-ID on authenticated requests. */
+    tenantId?: string;
+}
+/**
+ * How long the server asked us to wait, in ms, from a 429's Retry-After.
+ *
+ * The chat server runs TWO named rate-limit layers, and @nestjs/throttler
+ * suffixes its headers with the throttler name unless that name is literally
+ * "default". So a 429 carries `Retry-After-identity` or `Retry-After-ip`, not a
+ * bare `Retry-After`. Older servers and intermediary proxies may still send the
+ * bare name, so all three are read; when more than one is present the LONGER
+ * wait wins, since retrying before the slower bucket drains just earns another
+ * 429.
+ *
+ * Returns undefined when no variant is readable — in a browser that also
+ * happens when the server omits these from Access-Control-Expose-Headers, in
+ * which case callers must fall back to their own backoff.
+ */
+declare function readRetryAfterMs(headers: Headers): number | undefined;
+/**
+ * Thrown when the transit handshake is rate-limited (HTTP 429).
+ *
+ * Distinct from a generic failure because the correct response differs: a 429
+ * means "wait", not "this is broken", so callers must not burn their retry
+ * budget on it and should honour `retryAfterMs` when the server supplied it.
+ */
+declare class TransitRateLimitedError extends Error {
+    readonly retryAfterMs?: number;
+    constructor(retryAfterMs?: number);
+}
 interface ServerPublicKeys {
     x25519: string;
     p256: string;
     enabled: boolean;
 }
-declare function fetchServerKeys(apiUrl: string): Promise<ServerPublicKeys>;
+declare function fetchServerKeys(apiUrl: string, identity?: TransitIdentity): Promise<ServerPublicKeys>;
 declare function generateEphemeralKey(algo: TransitAlgo, serverKeys: ServerPublicKeys): Promise<{
     ephemeralPubB64: string;
     deriveSessionKey: (sessionId: string) => Promise<unknown>;
 }>;
-declare function createRestTransitSession(apiUrl: string): Promise<{
+declare function createRestTransitSession(apiUrl: string, identity?: TransitIdentity): Promise<{
     sessionId: string;
     sessionKey: CryptoKey | Uint8Array;
 } | null>;
@@ -799,4 +848,4 @@ declare class AntzChatClient {
     uploadIcon(conversationId: string, file: UploadableFile): Promise<Conversation>;
 }
 
-export { AntzChatAuthError, AntzChatClient, AntzChatConfig, AntzChatError, AntzChatNetworkError, AntzChatPermissionError, AntzChatServerError, AntzChatValidationError, AppConfig, AuthResponse, AuthTokens, BatchUploadResult, CompletedPart, Conversation, ConversationListParams, ConversationSyncResponse, ConversationUnreadCount, type CreateDirectData, type CreateGroupData, CrossConversationSyncResponse, CursorPaginatedResponse, FileResponse, FileType, ForwardAckPayload, ForwardMessagePayload, type ForwardResult, HIGHLY_FORWARDED_DEPTH_THRESHOLD, type LastReadEntry, type ListMessagesParams, LoginCredentials, MAX_FORWARD_TARGETS, type MentionPart, type MentionSegment, Message, MessageReactionsResponse, MessageReceiptsResponse, type MobileDeviceToken, PaginatedResponse, type ParsedMention, Participant, PersistStorage, PresignedUrlRequest, PresignedUrlResponse, RegisterData, type RegisterDeviceTokenPayload, ResolvedCompressionConfig, ResolvedConfig, type SearchParams, type SendData, SendMessagePayload, type SocketStatus, type StatusListener, type TokenStore, UnreadSummary, type UpdateConversationData, type UpdateProfilePayload, UploadableFile, User, UserPreferences, type WebPushDeviceToken, appConfigApi, authApi, buildMentionText, connectSocket, conversationsApi, createAuthStore, createRestTransitSession, decryptPayload, devicesApi, disconnectSocket, encryptPayload, extractMentionIds, fetchServerKeys, generateEphemeralKey, getApiClient, getAuthStore, getCompressionStrategy, getSessionId, getSessionKey, getSocket, getSocketStatus, initApiClient, initAuthStore, isApiClientConfigured, isMentionAll, isTransitEnvelope, messagesApi, normalizeAxiosError, normalizeConversation, onSocketStatus, parseMentions, performHandshake, reconnectSocket, refreshSocketAuth, renderMentionParts, resetAuthStore, resetTrackedRooms, resolveSystemMessageText, setApiClientInstance, setAuthReadyPromise, setTransitSession, socketEmit, syncApi, tryGetSocket, useChatStore, usersApi };
+export { AntzChatAuthError, AntzChatClient, AntzChatConfig, AntzChatError, AntzChatNetworkError, AntzChatPermissionError, AntzChatServerError, AntzChatValidationError, AppConfig, AuthResponse, AuthTokens, BatchUploadResult, CompletedPart, Conversation, ConversationListParams, ConversationSyncResponse, ConversationUnreadCount, type CreateDirectData, type CreateGroupData, CrossConversationSyncResponse, CursorPaginatedResponse, FileResponse, FileType, ForwardAckPayload, ForwardMessagePayload, type ForwardResult, HIGHLY_FORWARDED_DEPTH_THRESHOLD, type LastReadEntry, type ListMessagesParams, LoginCredentials, MAX_FORWARD_TARGETS, type MentionPart, type MentionSegment, Message, MessageReactionsResponse, MessageReceiptsResponse, type MobileDeviceToken, PaginatedResponse, type ParsedMention, Participant, PersistStorage, PresignedUrlRequest, PresignedUrlResponse, RegisterData, type RegisterDeviceTokenPayload, ResolvedCompressionConfig, ResolvedConfig, type SearchParams, type SendData, SendMessagePayload, type SocketStatus, type StatusListener, type TokenStore, type TransitIdentity, TransitRateLimitedError, UnreadSummary, type UpdateConversationData, type UpdateProfilePayload, UploadableFile, User, UserPreferences, type WebPushDeviceToken, appConfigApi, authApi, buildMentionText, connectSocket, conversationsApi, createAuthStore, createRestTransitSession, decryptPayload, devicesApi, disconnectSocket, encryptPayload, extractMentionIds, fetchServerKeys, generateEphemeralKey, getApiClient, getAuthStore, getCompressionStrategy, getSessionId, getSessionKey, getSocket, getSocketStatus, initApiClient, initAuthStore, isApiClientConfigured, isMentionAll, isTransitEnvelope, messagesApi, normalizeAxiosError, normalizeConversation, onSocketStatus, parseMentions, performHandshake, readRetryAfterMs, reconnectSocket, refreshSocketAuth, renderMentionParts, resetAuthStore, resetTrackedRooms, resolveSystemMessageText, setApiClientInstance, setAuthReadyPromise, setTransitSession, socketEmit, syncApi, tryGetSocket, useChatStore, usersApi };

package/dist/index.js

@@ -5,6 +5,7 @@ import {
   AntzChatPermissionError,
   AntzChatServerError,
   AntzChatValidationError,
+  TransitRateLimitedError,
   awaitTransitReadyOr,
   clearTransitSession,
   configureTransitIfUnset,
@@ -30,13 +31,14 @@ import {
   normalizeAxiosError,
   onTransitReady,
   performHandshake,
+  readRetryAfterMs,
   resetAlgoCache,
   setApiClientInstance,
   setAuthReadyPromise,
   setTransitSession,
   storageApi,
   uploadBatch
-} from "./chunk-WUNH3UTE.js";
+} from "./chunk-U637W5MD.js";
 import {
   useChatStore
 } from "./chunk-UIYJAOGL.js";
@@ -456,7 +458,7 @@ async function _doConnect(config, getToken) {
     if (existingSession?.enabled && existingSession.sessionId) {
       httpsSession = { sessionId: existingSession.sessionId, sessionKey: existingSession.sessionKey };
     } else {
-      httpsSession = await createRestTransitSession(config.apiUrl);
+      httpsSession = await createRestTransitSession(config.apiUrl, { userId: config.userId, tenantId: config.tenantId });
       if (httpsSession) {
         const algo = globalThis.crypto?.subtle ? await detectTransitAlgo() : "x25519";
         setTransitSession({ sessionKey: httpsSession.sessionKey, algo, sessionId: httpsSession.sessionId, enabled: true });
@@ -467,7 +469,7 @@ async function _doConnect(config, getToken) {
       boundDeriveSessionKey = null;
     } else {
       try {
-        const serverKeys = await fetchServerKeys(config.apiUrl);
+        const serverKeys = await fetchServerKeys(config.apiUrl, { userId: config.userId, tenantId: config.tenantId });
         if (!serverKeys.enabled) {
           throw new AntzChatError(
             "TRANSIT_MISMATCH",
@@ -484,7 +486,7 @@ async function _doConnect(config, getToken) {
     }
   } else {
     try {
-      const serverKeys = await fetchServerKeys(config.apiUrl);
+      const serverKeys = await fetchServerKeys(config.apiUrl, { userId: config.userId, tenantId: config.tenantId });
       if (serverKeys.enabled) {
         throw new AntzChatError(
           "TRANSIT_MISMATCH",
@@ -1331,6 +1333,7 @@ export {
   HIGHLY_FORWARDED_DEPTH_THRESHOLD,
   MAX_FORWARD_TARGETS,
   MENTION_ALL_ID,
+  TransitRateLimitedError,
   appConfigApi,
   authApi,
   buildMentionText,
@@ -1363,6 +1366,7 @@ export {
   onSocketStatus,
   parseMentions,
   performHandshake,
+  readRetryAfterMs,
   reconnectSocket,
   refreshSocketAuth,
   renderMentionParts,