@antzsoft/chat-core 1.4.5 → 1.4.7

package/dist/index.d.cts

@@ -339,6 +339,7 @@ declare function getSocket(): Socket;
 declare function tryGetSocket(): Socket | null;
 declare function getSocketStatus(): SocketStatus;
 declare function onSocketStatus(listener: StatusListener): () => void;
+declare function registerTeardownHook(hook: () => void): () => void;
 /** Drop all tracked rooms. Call on a genuine identity change (user/tenant
  *  switch) so the reconnect re-flush can't re-join the previous user's rooms.
  *  NOT called from disconnectSocket() — a token refresh is not an intent change. */
@@ -353,6 +354,9 @@ declare function reconnectSocket(token: string, userId?: string, tenantId?: stri
  */
 declare function refreshSocketAuth(): boolean;
 
+/** Clears the typing throttle state. Call on teardown/identity change so a new
+ *  session cannot inherit the previous one's suppression window. */
+declare function resetTypingThrottle(): void;
 declare const socketEmit: {
     joinRoom(conversationId: string): void;
     leaveRoom(conversationId: string): void;
@@ -395,17 +399,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>;
@@ -535,6 +588,10 @@ interface ChatState {
     } | null) => void;
     addTypingUser: (conversationId: string, user: TypingUser) => void;
     removeTypingUser: (conversationId: string, userId: string) => void;
+    /** Drops every typing indicator and cancels their expiry timers. For teardown
+     *  and identity change — a socket drop no longer needs it, since indicators
+     *  expire on their own. */
+    clearTypingUsers: () => void;
     setUserOnline: (userId: string) => void;
     setUserOffline: (userId: string) => void;
     setOnlineUsers: (userIds: string[]) => void;
@@ -799,4 +856,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, registerTeardownHook, renderMentionParts, resetAuthStore, resetTrackedRooms, resetTypingThrottle, resolveSystemMessageText, setApiClientInstance, setAuthReadyPromise, setTransitSession, socketEmit, syncApi, tryGetSocket, useChatStore, usersApi };

package/dist/index.d.ts

@@ -339,6 +339,7 @@ declare function getSocket(): Socket;
 declare function tryGetSocket(): Socket | null;
 declare function getSocketStatus(): SocketStatus;
 declare function onSocketStatus(listener: StatusListener): () => void;
+declare function registerTeardownHook(hook: () => void): () => void;
 /** Drop all tracked rooms. Call on a genuine identity change (user/tenant
  *  switch) so the reconnect re-flush can't re-join the previous user's rooms.
  *  NOT called from disconnectSocket() — a token refresh is not an intent change. */
@@ -353,6 +354,9 @@ declare function reconnectSocket(token: string, userId?: string, tenantId?: stri
  */
 declare function refreshSocketAuth(): boolean;
 
+/** Clears the typing throttle state. Call on teardown/identity change so a new
+ *  session cannot inherit the previous one's suppression window. */
+declare function resetTypingThrottle(): void;
 declare const socketEmit: {
     joinRoom(conversationId: string): void;
     leaveRoom(conversationId: string): void;
@@ -395,17 +399,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>;
@@ -535,6 +588,10 @@ interface ChatState {
     } | null) => void;
     addTypingUser: (conversationId: string, user: TypingUser) => void;
     removeTypingUser: (conversationId: string, userId: string) => void;
+    /** Drops every typing indicator and cancels their expiry timers. For teardown
+     *  and identity change — a socket drop no longer needs it, since indicators
+     *  expire on their own. */
+    clearTypingUsers: () => void;
     setUserOnline: (userId: string) => void;
     setUserOffline: (userId: string) => void;
     setOnlineUsers: (userIds: string[]) => void;
@@ -799,4 +856,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, registerTeardownHook, renderMentionParts, resetAuthStore, resetTrackedRooms, resetTypingThrottle, 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,16 +31,17 @@ 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";
+} from "./chunk-QHELYVNT.js";
 
 // src/config/types.ts
 function resolveConfig(config) {
@@ -403,6 +405,19 @@ function secureOn(socket, event, handler) {
     handler(raw);
   });
 }
+var _teardownHooks = /* @__PURE__ */ new Set();
+function registerTeardownHook(hook) {
+  _teardownHooks.add(hook);
+  return () => _teardownHooks.delete(hook);
+}
+function runTeardownHooks() {
+  _teardownHooks.forEach((hook) => {
+    try {
+      hook();
+    } catch {
+    }
+  });
+}
 var _joinedRooms = /* @__PURE__ */ new Set();
 function trackRoomJoin(conversationId) {
   _joinedRooms.add(conversationId);
@@ -456,7 +471,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 +482,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 +499,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",
@@ -546,13 +561,13 @@ async function _doConnect(config, getToken) {
     });
   }
   secureOn(_socket, "read_receipt", (event) => {
-    import("./chat.store-UVTDBPEC.js").then(({ useChatStore: useChatStore2 }) => {
+    import("./chat.store-TA6G7PD6.js").then(({ useChatStore: useChatStore2 }) => {
       const e = event;
       useChatStore2.getState().setLastRead(e.conversationId, e.messageId, e.readAt);
     });
   });
   secureOn(_socket, "user_online", (event) => {
-    import("./chat.store-UVTDBPEC.js").then(({ useChatStore: useChatStore2 }) => {
+    import("./chat.store-TA6G7PD6.js").then(({ useChatStore: useChatStore2 }) => {
       const store = useChatStore2.getState();
       const e = event;
       store.setUserOnline(e.userId);
@@ -560,7 +575,7 @@ async function _doConnect(config, getToken) {
     });
   });
   secureOn(_socket, "user_offline", (event) => {
-    import("./chat.store-UVTDBPEC.js").then(({ useChatStore: useChatStore2 }) => {
+    import("./chat.store-TA6G7PD6.js").then(({ useChatStore: useChatStore2 }) => {
       const e = event;
       const store = useChatStore2.getState();
       store.setUserOffline(e.userId);
@@ -598,6 +613,10 @@ function disconnectSocket() {
   }
   clearTransitSession();
   resetAlgoCache();
+  runTeardownHooks();
+  import("./chat.store-TA6G7PD6.js").then(({ useChatStore: useChatStore2 }) => {
+    useChatStore2.getState().clearTypingUsers();
+  });
   _getToken = null;
   _userId = void 0;
   _tenantId = void 0;
@@ -649,6 +668,12 @@ var RECONNECT_WAIT_TIMEOUT = 15e3;
 var QUEUE_MAX_SIZE = 100;
 var QUEUE_ENTRY_TTL = 3e4;
 var sendQueues = /* @__PURE__ */ new Map();
+var TYPING_THROTTLE_MS = 3e3;
+var _lastTypingSentAt = /* @__PURE__ */ new Map();
+function resetTypingThrottle() {
+  _lastTypingSentAt.clear();
+}
+registerTeardownHook(resetTypingThrottle);
 var sendQueueRunning = /* @__PURE__ */ new Map();
 async function drainSendQueue(conversationId) {
   if (sendQueueRunning.get(conversationId)) return;
@@ -779,8 +804,40 @@ var socketEmit = {
     return withAck("unpin_message", { messageId });
   },
   // markRead and typing are best-effort — silently dropped if socket not ready
+  //
+  // Typing is additionally LEADING-THROTTLED here rather than in the UI layer,
+  // so every consumer (both UI SDKs and any host calling socketEmit directly)
+  // gets the same emit budget and none can bypass it.
+  //
+  // The composer calls this on EVERY keystroke. A 40-word message is ~200 calls
+  // of which exactly one carries information: "this person started typing".
+  // Each one previously cost a round trip plus real server work, making typing
+  // the single most expensive event in the system per unit of user value.
+  //
+  // Shape of the throttle:
+  //   isTyping:true  — passed through at most once per TYPING_THROTTLE_MS per
+  //                    conversation. A continuous typist emits ~20/min instead
+  //                    of ~200/min.
+  //   isTyping:false — ALWAYS passed through, and resets the window. It is the
+  //                    edge that clears the indicator on every peer, it is
+  //                    already debounced by the composer, and dropping it is
+  //                    exactly the failure that leaves "is typing…" stuck.
+  //
+  // The server refreshes its typing key on each true edge (10s TTL) and
+  // receivers expire their own indicators after TYPING_EXPIRY_MS, both of which
+  // are comfortably longer than TYPING_THROTTLE_MS — so a throttled-away event
+  // never lets an indicator lapse mid-typing.
   typing(conversationId, isTyping) {
-    fireAndForget("typing", { conversationId, isTyping });
+    if (!isTyping) {
+      _lastTypingSentAt.delete(conversationId);
+      fireAndForget("typing", { conversationId, isTyping: false });
+      return;
+    }
+    const now = Date.now();
+    const last = _lastTypingSentAt.get(conversationId) ?? 0;
+    if (now - last < TYPING_THROTTLE_MS) return;
+    _lastTypingSentAt.set(conversationId, now);
+    fireAndForget("typing", { conversationId, isTyping: true });
   },
   markRead(conversationId, messageId) {
     fireAndForget("mark_read", { conversationId, ...messageId ? { messageId } : {} });
@@ -1331,6 +1388,7 @@ export {
   HIGHLY_FORWARDED_DEPTH_THRESHOLD,
   MAX_FORWARD_TARGETS,
   MENTION_ALL_ID,
+  TransitRateLimitedError,
   appConfigApi,
   authApi,
   buildMentionText,
@@ -1363,11 +1421,14 @@ export {
   onSocketStatus,
   parseMentions,
   performHandshake,
+  readRetryAfterMs,
   reconnectSocket,
   refreshSocketAuth,
+  registerTeardownHook,
   renderMentionParts,
   resetAuthStore,
   resetTrackedRooms,
+  resetTypingThrottle,
   resolveConfig,
   resolveSystemMessageText,
   setApiClientInstance,