@manonero/chat-client-sdk 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -171,7 +171,12 @@ const client = new ChatClient({
 });
 ```
 
-> **Ưu tiên token:** `token` (hoặc `setToken()`) luôn ưu tiên hơn `tokenProvider`. Khi `_token` khác `null`, `tokenProvider` bị bỏ qua.
+> **Ưu tiên token (resolve mỗi request / connect):**
+> 1. Nếu `tokenProvider` được cấu hình **VÀ** trả về string non-empty → dùng giá trị đó.
+> 2. Ngược lại → dùng token nội bộ (`token` constructor / `setToken()` / auto-set sau login).
+> 3. Ngược lại → `null` (không gửi `Authorization`).
+>
+> Provider luôn được hỏi trước nên các hệ thống refresh-token rotation tiếp tục hoạt động kể cả sau khi `setToken()` đã được gọi. Dùng `clearToken()` nếu muốn xoá token nội bộ và trả quyền hoàn toàn về provider.
 
 ### Cấu hình SignalR log level
 
@@ -205,6 +210,7 @@ new ChatClient(options: ChatClientOptions)
 | `baseUrl` | `string` | ✅ | URL gốc của server, ví dụ `"https://chat-api.example.com"` |
 | `token` | `string` | ❌ | JWT token ban đầu (nếu đã đăng nhập) |
 | `tokenProvider` | `() => string \| null` | ❌ | Hàm lấy token từ bên ngoài |
+| `requestTimeoutMs` | `number \| null` | ❌ | Timeout HTTP / upload tính bằng ms. Mặc định `30000`. Truyền `null` để tắt (hữu ích khi upload file lớn). |
 | `signalrOptions.logLevel` | `LogLevel` | ❌ | Mức log cho SignalR (mặc định: `Warning`) |
 
 ### Thuộc tính
@@ -225,20 +231,52 @@ new ChatClient(options: ChatClientOptions)
 
 ### Phương thức
 
-#### `setToken(token: string): void`
+#### `setToken(token: string | null): void`
 
-Cập nhật JWT token. Có hiệu lực ngay với mọi HTTP request tiếp theo.
+Cập nhật JWT token nội bộ. Có hiệu lực **ngay** với mọi HTTP request tiếp theo. Truyền `null` để xoá token nội bộ và `currentUser` (tương đương `clearToken()`).
 
-> ⚠️ Các kết nối SignalR đang hoạt động **không** được cập nhật token mid-session. Cần `disconnect()` rồi `connect()` lại để dùng token mới.
+> ⚠️ Các kết nối SignalR **đang hoạt động** vẫn dùng token cũ cho đến lúc reconnect. Gọi `refreshConnections()` để áp token mới ngay cho hub đang Connected.
+
+> ℹ️ Nếu `tokenProvider` đã được cấu hình và vẫn trả về giá trị, provider tiếp tục được ưu tiên — `setToken()` chỉ ảnh hưởng khi provider trả `null`/empty.
 
 ```ts
 client.setToken('new-jwt-token-here');
+await client.refreshConnections(); // tuỳ chọn — chỉ khi muốn áp ngay cho SignalR
+```
+
+#### `clearToken(): void`
+
+Xoá token nội bộ và `currentUser`. Không động tới `tokenProvider` (provider tiếp tục hoạt động bình thường) và không ngắt SignalR. Dùng `logout()` nếu muốn ngắt cả hub.
+
+```ts
+client.clearToken();
+```
+
+#### `refreshConnections(): Promise<void>`
+
+`disconnect()` + `connect()` lại từng hub đang ở trạng thái `Connected`. Hub đang Disconnected/Reconnecting được giữ nguyên. Dùng để áp token mới (sau `setToken()`) cho phiên SignalR đang chạy.
+
+> ⚠️ `disconnect()` xoá local tracking (`joinedConversations`, `subscribedPresenceIds`). Sau khi gọi `refreshConnections()`, ứng dụng phải tự `joinConversation` / `subscribeToPresence` lại — hoặc dùng `ReconnectionManager` để khôi phục trong suốt cho mọi loại disconnect.
+
+```ts
+client.setToken(newToken);
+await client.refreshConnections();
+```
+
+#### `logout(): Promise<void>`
+
+Xoá token + `currentUser` rồi `disconnect()` cả hai hub. Chỉ clear local state — không gọi server (server không có endpoint logout). Nếu `tokenProvider` được cấu hình và vẫn trả token, request kế tiếp vẫn có thể auth lại.
+
+```ts
+await client.logout();
 ```
 
 #### `disconnect(): Promise<void>`
 
 Ngắt kết nối tất cả các SignalR hub (ChatHub + NotificationHub) đồng thời.
 
+> Cả hai hub set cờ `intentionallyClosed` trước khi tear down nên `ReconnectionManager` (nếu được attach) sẽ **bỏ qua** lần `disconnected` này thay vì auto-reconnect ngược ý người dùng.
+
 ```ts
 await client.disconnect();
 ```
@@ -512,6 +550,39 @@ await client.conversations.markAsRead('conv-id', 'last-message-id');
 await client.conversations.markAsUnread('conv-id');
 ```
 
+### `getMedia(conversationId, params?): Promise<CursorPaginatedResult<ConversationMediaItemDto>>`
+
+Liệt kê toàn bộ media (image/video/audio/file) và link (LinkPreview hoặc external URL) đã từng xuất hiện trong cuộc hội thoại — sắp xếp **newest-first**, cursor pagination.
+
+```ts
+// Mặc định: kind = 'all', limit = 50
+const page1 = await client.conversations.getMedia('conv-id');
+
+// Chỉ file/ảnh nội bộ
+const attachments = await client.conversations.getMedia('conv-id', {
+  kind: 'attachment',
+  limit: 100,
+});
+
+// Chỉ link / LinkPreview
+const links = await client.conversations.getMedia('conv-id', { kind: 'link' });
+
+// Trang tiếp theo
+if (page1.hasMore) {
+  const page2 = await client.conversations.getMedia('conv-id', {
+    cursor: page1.nextCursor!,
+  });
+}
+```
+
+| Param | Type | Default | Mô tả |
+|-------|------|---------|-------|
+| `kind` | `'all' \| 'attachment' \| 'link'` | `'all'` | Lọc theo loại item |
+| `limit` | number | 50 | 1..100 |
+| `cursor` | string | — | `nextCursor` từ trang trước (opaque) |
+
+> **Lưu ý:** Người dùng chỉ thấy media của các message từ thời điểm họ join cuộc hội thoại trở đi. Server trả `403` nếu caller không phải participant.
+
 ### Kiểu dữ liệu Conversation
 
 ```ts
@@ -555,6 +626,49 @@ interface ConversationListItemDto {
   unreadCount: number;
   participantCount: number;
 }
+
+// Media listing (getMedia)
+type ConversationMediaKindFilter = 'all' | 'attachment' | 'link';
+type ConversationMediaKind = 'Attachment' | 'Link';
+type ConversationMediaBlockType = 'Image' | 'Video' | 'Audio' | 'File' | 'LinkPreview';
+
+interface ConversationMediaItemDto {
+  id: string;                // Composite "{messageId}#{blockIndex:D2}"
+  conversationId: string;
+  messageId: string;
+  blockIndex: number;        // 0-based vị trí block trong message
+  senderId: string;
+  senderType: string;        // 'User' | 'Bot' | 'System'
+  kind: ConversationMediaKind;
+  blockType: ConversationMediaBlockType;
+  createdAt: string;         // ISO 8601 — thời điểm message được tạo
+
+  storageKey?: string | null; // set khi kind === 'Attachment'
+  url?: string | null;        // set khi kind === 'Link'
+
+  // File / audio / video
+  fileName?: string | null;
+  mimeType?: string | null;
+  fileSizeBytes?: number | null;
+
+  // Image / video / audio
+  width?: number | null;
+  height?: number | null;
+  durationSeconds?: number | null;
+  caption?: string | null;
+  altText?: string | null;
+
+  // Image / video thumbnail
+  thumbnailStorageKey?: string | null;
+  thumbnailUrl?: string | null;
+
+  // LinkPreview metadata
+  linkTitle?: string | null;
+  linkDescription?: string | null;
+  linkSiteName?: string | null;
+  linkImageStorageKey?: string | null;
+  linkImageUrl?: string | null;
+}
 ```
 
 ---
@@ -665,7 +779,6 @@ interface MessageDto {
   conversationId: string;
   senderId: string;
   senderType: SenderType;
-  timestamp: string;        // ISO 8601 — thời điểm gửi
   blocks: Block[];          // Nội dung tin nhắn
   plainTextIndex: string | null;
   replyToMessageId: string | null;
@@ -956,6 +1069,28 @@ const updated = await client.proxy.put<Order>('trading', 'api/orders/123', {
   quantity: 200,
 });
 
+// PATCH /api/proxy/trading/api/orders/123
+const patched = await client.proxy.patch<Order>('trading', 'api/orders/123', {
+  status: 'cancelled',
+});
+
+// DELETE /api/proxy/trading/api/orders/123
+await client.proxy.delete('trading', 'api/orders/123');
+
+// Truyền custom headers — mỗi shortcut đều nhận `headers?` ở tham số cuối
+const dataWithHeader = await client.proxy.get<StockData>(
+  'trading',
+  'api/stocks/VN30',
+  { 'X-Trace-Id': 'abc-123' },
+);
+
+const orderWithHeader = await client.proxy.post<Order>(
+  'trading',
+  'api/orders',
+  { symbol: 'VNM', quantity: 100 },
+  { 'Idempotency-Key': 'order-uuid' },
+);
+
 // Request tùy chỉnh method (hỗ trợ GET, POST, PUT, PATCH, DELETE)
 const result = await client.proxy.request<unknown>('myservice', 'api/resource/123', {
   method: 'DELETE',
@@ -1052,6 +1187,12 @@ await client.realtime.chat.leaveConversation('conv-id');
 ```
 
 > SDK theo dõi `joinedConversations` và tự động re-join sau khi reconnect.
+>
+> **Lưu ý về FORBIDDEN/UNAUTHORIZED:** Theo spec, server có thể chấp nhận lời gọi `joinConversation` nhưng từ chối quyền truy cập sau đó qua event `Error` (vd. `FORBIDDEN — You are not a participant`). SDK sẽ tự động loại conversationId đó khỏi `joinedConversations` để tránh re-join sai sau reconnect, dựa trên:
+> 1. `error.details.conversationId` nếu server cung cấp (chính xác nhất), hoặc
+> 2. Fallback: message khớp `/not a participant/i` **và** chỉ có đúng 1 lời gọi `joinConversation` đang trong cửa sổ ~2s.
+>
+> Vẫn nên đăng ký listener `error` để hiển thị thông báo cho user.
 
 ### Gửi tin nhắn qua SignalR
 
@@ -1130,6 +1271,7 @@ client.realtime.chat.off('messageReceived', handler);
 | `messageUpdated` | `MessageUpdatedDto` | Tin nhắn được chỉnh sửa |
 | `messageDeleted` | `MessageDeletedDto` | Tin nhắn bị xóa |
 | `messageRecovered` | `ChatMessageDto` | Tin nhắn được khôi phục |
+| `messageThumbnailsReady` | `MessageThumbnailsReadyDto` | Server đã sinh xong thumbnail cho ảnh/video — patch theo `blockIndex` |
 | `reactionAdded` | `ReactionAddedDto` | Thêm reaction |
 | `reactionRemoved` | `ReactionRemovedDto` | Xóa reaction |
 | `typingStarted` | `TypingDto` | Người dùng đang gõ |
@@ -1203,6 +1345,36 @@ interface ReadReceiptUpdatedDto {
   lastReadMessageId: string;
   readAt: string;             // ISO 8601
 }
+
+// Thumbnail ready cho một block media trong message
+interface MessageThumbnailDto {
+  blockIndex: number;          // Vị trí block trong mảng blocks của message
+  thumbnail: MediaReference;
+}
+
+// Server đã sinh xong thumbnail cho ảnh/video (xử lý bất đồng bộ).
+// Event này gửi SAU messageReceived/streamCompleted.
+interface MessageThumbnailsReadyDto {
+  messageId: string;
+  conversationId: string;
+  thumbnails: MessageThumbnailDto[];
+}
+```
+
+### Cập nhật thumbnail bất đồng bộ
+
+Khi gửi tin nhắn có ảnh/video, server xử lý thumbnail trong nền và phát event `messageThumbnailsReady` sau khi hoàn tất. Client nên patch block theo `blockIndex` thay vì re-fetch toàn bộ message.
+
+```ts
+client.realtime.chat.on('messageThumbnailsReady', (dto) => {
+  // dto.thumbnails: [{ blockIndex: 0, thumbnail: { storageKey, url } }, ...]
+  for (const item of dto.thumbnails) {
+    const block = messageStore.get(dto.messageId)?.blocks[item.blockIndex];
+    if (block && (block.$type === 'image' || block.$type === 'video')) {
+      block.thumbnail = item.thumbnail;
+    }
+  }
+});
 ```
 
 ### Bot streaming
@@ -1280,7 +1452,7 @@ await client.realtime.notifications.resubscribePresence();
 ### Theo dõi trạng thái online (Presence)
 
 ```ts
-// Đăng ký theo dõi tối đa 200 participant mỗi lần
+// Đăng ký theo dõi presence — SDK tự chia nhỏ thành các batch 200 nếu danh sách dài hơn
 await client.realtime.notifications.subscribeToPresence(['user-1', 'user-2', 'user-3']);
 
 // Server gửi PresenceState ngay lập tức sau khi subscribe
@@ -1295,7 +1467,7 @@ client.realtime.notifications.on('presenceChanged', (dto) => {
   console.log(dto.participantId, 'is now', dto.isOnline ? 'online' : 'offline');
 });
 
-// Hủy theo dõi — cũng giới hạn tối đa 200 participant mỗi lần
+// Hủy theo dõi — cũng tự chia nhỏ thành các batch 200
 await client.realtime.notifications.unsubscribeFromPresence(['user-1']);
 ```
 
@@ -1344,11 +1516,11 @@ interface PresenceChangedDto {
 interface NewMessageNotificationDto {
   conversationId: string;
   conversationType: ConversationType;
-  conversationName?: string;
+  conversationName?: string | null;
   messageId: string;
   senderId: string;
   senderName: string;
-  senderAvatar?: MediaReference;
+  senderAvatar?: MediaReference | null; // Có thể null khi server chưa sẵn signed URL
   contentPreview: string;
   sentAt: string;             // ISO 8601
 }
@@ -1373,15 +1545,15 @@ interface UnreadCountChangedDto {
 interface ConversationCreatedDto {
   conversationId: string;
   type: ConversationType;
-  name?: string;
-  avatar?: MediaReference;
+  name?: string | null;
+  avatar?: MediaReference | null;
   participantCount: number;
 }
 
 interface ConversationUpdatedDto {
   conversationId: string;
   type: ConversationType;
-  name?: string;
+  name?: string | null;
   avatar?: MediaReference | null; // null = avatar đã bị xóa
   participantCount: number;
 }
@@ -1390,7 +1562,7 @@ interface ParticipantJoinedDto {
   conversationId: string;
   participantId: string;
   participantName: string;
-  participantAvatar?: MediaReference;
+  participantAvatar?: MediaReference | null; // Có thể null khi server chưa sẵn signed URL
   changedAt: string;          // ISO 8601
 }
 
@@ -1399,7 +1571,7 @@ interface ParticipantLeftDto {
   conversationId: string;
   participantId: string;
   participantName: string;
-  participantAvatar?: MediaReference;
+  participantAvatar?: MediaReference | null; // Có thể null khi server chưa sẵn signed URL
   changedAt: string;          // ISO 8601
 }
 
@@ -1457,7 +1629,7 @@ const manager = new ReconnectionManager({
     // Gọi API refresh token của ứng dụng
     const newToken = await refreshToken();
     if (newToken) {
-      client.setToken(newToken); // Cập nhật token vào SDK
+      client.setToken(newToken); // Cập nhật token vào SDK; lần connect() kế tiếp sẽ dùng giá trị mới
     }
     return newToken; // Trả về null để hủy reconnect
   },
@@ -1471,7 +1643,9 @@ manager.stop();
 
 **Chiến lược backoff:** 3 lần thử với delay 2s → 5s → 10s.
 
-**Phát hiện token hết hạn:** Kiểm tra error message có chứa `"401"` hoặc `"unauthorized"`.
+**Phát hiện token hết hạn:** heuristic — match (case-insensitive) các keyword `401`, `unauthorized`, `expired`, `invalid_token`, `invalid token` trong message của error.
+
+**Bỏ qua close chủ động:** Cả `ChatHubClient` và `NotificationHubClient` expose getter `intentionallyClosed`. Trước khi tear down trong `disconnect()` (kể cả khi gọi qua `client.disconnect()` / `client.logout()`), cờ này được set `true`. Manager kiểm tra cờ ngay đầu handler và **bỏ qua** lần `disconnected` đó — không tự reconnect ngược ý người dùng. Cờ được reset về `false` ở đầu lần `connect()` kế tiếp.
 
 ---
 
@@ -1685,7 +1859,7 @@ type ButtonStyle = 'Default' | 'Primary' | 'Danger';
 interface ActionButton {
   label: string;
   action: ButtonAction;
-  value: string | null;
+  value?: string | null;
   style: ButtonStyle;
 }
 
@@ -1703,7 +1877,7 @@ type ChoiceMode = 'Single' | 'Multiple';
 interface ChoiceOption {
   label: string;
   value: string;
-  selected: boolean;
+  selected?: boolean;
 }
 
 interface ChoiceBlock {
@@ -1784,7 +1958,7 @@ interface ChatMessageDto {
   conversationId: string;
   senderId: string;
   senderName: string;        // Có ở SignalR, không có ở REST
-  senderAvatar?: MediaReference; // Có ở SignalR, không có ở REST
+  senderAvatar?: MediaReference | null; // Có ở SignalR, không có ở REST. Có thể null khi server chưa sẵn signed URL
   senderType: SenderType;    // Có ở cả REST và SignalR
   blocks: Block[];
   plainTextContent: string | null; // Tên khác với REST (plainTextIndex)
@@ -1816,14 +1990,14 @@ type SystemEventType =
   | 'AvatarChanged'        // Đổi avatar
   | 'MemberAdded'          // Thêm thành viên
   | 'MemberRemoved'        // Xóa thành viên
-  | 'MemberLeft'           // Thành viên tự rời
-  | 'Custom';
+  | 'MemberLeft';          // Thành viên tự rời
 
 interface SystemEventInfo {
   type: SystemEventType;
-  actorId: string | null;   // null khi MemberLeft (tự rời)
+  actorId?: string | null;  // null/undefined khi không có actor (vd. MemberLeft tự rời)
   targetIds?: string[];
-  metadata?: Record<string, unknown>;
+  // Tất cả giá trị đều là string (vd. ConversationRenamed → { newName: "Team Beta" })
+  metadata?: Record<string, string>;
 }
 
 // SignalR (ChatHub) version — kế thừa SystemEventInfo, thêm display names
@@ -1839,7 +2013,8 @@ interface SystemEventDto extends SystemEventInfo {
 interface HubErrorDto {
   code: string;
   message: string;
-  details?: Record<string, unknown>;
+  // Server có thể gửi `null` rõ ràng, hoặc bỏ field hoàn toàn
+  details?: Record<string, unknown> | null;
 }
 ```
 
@@ -1852,8 +2027,8 @@ interface StreamStartedDto {
   conversationId: string;
   senderId: string;
   senderName: string;
-  senderAvatar?: MediaReference;
-  replyToMessageId?: string;
+  senderAvatar?: MediaReference | null; // Có thể null khi server chưa sẵn signed URL
+  replyToMessageId?: string | null;
   startedAt: string;         // ISO 8601
 }
 
@@ -2116,7 +2291,9 @@ const cursor = Number(result.nextCursor); // BUG!
 
 - `setToken()` hoạt động ngay cho **HTTP requests**.
 - SignalR đọc token khi **connect()**, không phải mid-session.
-- Để cập nhật token cho SignalR: `disconnect()` → `setToken()` → `connect()`.
+- Để áp token mới ngay cho hub đang Connected: `setToken(newToken)` → `await refreshConnections()`.
+- Sau `refreshConnections()` cần tự `joinConversation()` / `subscribeToPresence()` lại (tracking bị clear khi disconnect). Hoặc dùng `ReconnectionManager` để tự động khôi phục.
+- Khi `tokenProvider` được cấu hình, provider luôn được hỏi trước. `setToken()` chỉ là fallback cho trường hợp provider trả `null`/empty.
 
 ### REST vs SignalR — field name khác nhau
 

package/dist/ChatClient.d.ts

@@ -24,10 +24,25 @@ export interface ChatClientOptions {
     token?: string;
     /**
      * Optional external token provider function.
-     * When both `token` and `tokenProvider` are provided, the internal `_token`
-     * (set via constructor or setToken()) takes priority over the external provider.
+     *
+     * Resolution order on every request / connect:
+     *   1. If `tokenProvider` is set AND returns a non-empty string, that value
+     *      is used (so external rotation systems are honored on each call).
+     *   2. Otherwise the internal token (constructor `token`, `setToken()`, or
+     *      auto-set after a successful login) is used.
+     *   3. Otherwise null (no Authorization header sent).
+     *
+     * Note: this is reversed from the previous beta — previously a one-time
+     * setToken() would shadow the provider permanently. Now the provider always
+     * wins when it returns a value. Use `clearToken()` if you want to make sure
+     * the provider takes over after using setToken().
      */
     tokenProvider?: () => string | null;
+    /**
+     * Per-request HTTP timeout in milliseconds. Default 30000 (30s).
+     * Pass `null` to disable the timeout — useful when uploading large files.
+     */
+    requestTimeoutMs?: number | null;
     /** Options for SignalR hub connections */
     signalrOptions?: ChatClientSignalrOptions;
 }
@@ -67,8 +82,13 @@ export interface ChatClientRealtime {
  */
 export declare class ChatClient {
     /**
-     * The current JWT token held by the SDK.
-     * Overrides any external tokenProvider when non-null.
+     * Internally held JWT token (set via constructor `token`, `setToken()`, or
+     * after a successful login).
+     *
+     * Acts as the fallback when no `tokenProvider` is configured, or when the
+     * configured `tokenProvider` returns null. The external `tokenProvider`
+     * always wins when it returns a non-empty value — see
+     * {@link ChatClientOptions.tokenProvider}.
      */
     private _token;
     /**
@@ -101,16 +121,55 @@ export declare class ChatClient {
     /**
      * Update the JWT token.
      *
-     * The new token takes effect immediately for all subsequent HTTP requests.
-     * Active SignalR connections are NOT updated — they must be reconnected
-     * (disconnect() then connect()) for the new token to be used.
+     * Effect on requests:
+     *   - HTTP: takes effect on the very next request.
+     *   - SignalR: existing active connections keep using the token they were
+     *     opened with. To apply the new token immediately to active hubs, call
+     *     `refreshConnections()` after `setToken()`.
+     *
+     * Pass `null` to clear the internally held token (same as `clearToken()`):
+     * both `_token` and `currentUser` are cleared so the SDK no longer reports
+     * stale identity. If a `tokenProvider` is configured and still returns a
+     * value, it will continue to be used regardless of this call.
+     */
+    setToken(token: string | null): void;
+    /**
+     * Clear the internally held JWT token and authenticated user.
+     *
+     * After this, the configured `tokenProvider` (if any) becomes the only
+     * source of tokens. Use `logout()` instead when you also want to disconnect
+     * SignalR hubs.
      */
-    setToken(token: string): void;
+    clearToken(): void;
+    /**
+     * Disconnect any active SignalR hub and reconnect it with the latest token.
+     *
+     * Useful right after `setToken()` to propagate the new token to live hubs.
+     * Hubs that are not currently connected are left untouched.
+     *
+     * Re-joins of conversations / re-subscriptions of presence are NOT performed
+     * automatically here — `disconnect()` clears that local tracking by design.
+     * The application is responsible for re-issuing those after a manual refresh
+     * (or for using `ReconnectionManager` for transparent recovery).
+     */
+    refreshConnections(): Promise<void>;
+    /**
+     * Log the current user out: clear the internal token + currentUser and
+     * disconnect both SignalR hubs.
+     *
+     * Note: there is no server-side logout endpoint — this only clears local
+     * SDK state. If a `tokenProvider` is configured and still returns a token,
+     * subsequent requests can authenticate again with that token.
+     */
+    logout(): Promise<void>;
     /**
      * Disconnect all SignalR hubs (ChatHub + NotificationHub).
      *
      * Resolves after both hubs have finished disconnecting. Individual hub
      * disconnect failures do not prevent the other hub from disconnecting.
+     *
+     * Both hubs set their `intentionallyClosed` flag, so a `ReconnectionManager`
+     * attached to them will skip auto-reconnect for the resulting close.
      */
     disconnect(): Promise<void>;
     /**

package/dist/ChatClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatClient.d.ts","sourceRoot":"","sources":["../src/ChatClient.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAgB,YAAY,EAAgB,MAAM,iBAAiB,CAAC;AAoDhF,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACpC,0CAA0C;IAC1C,cAAc,CAAC,EAAE,wBAAwB,CAAC;CAC3C;AAMD,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;CAC/C;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,UAAU;IAKrB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAgB;IAE9B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAsB;IAM7D,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IAEtC,8BAA8B;IAC9B,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IAExC,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAE9B,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAEzB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAM3B,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAMtC,OAAO,CAAC,YAAY,CAA6B;IAEjD,+EAA+E;IAC/E,IAAI,WAAW,IAAI,YAAY,GAAG,IAAI,CAErC;gBAMW,OAAO,EAAE,iBAAiB;IAuDtC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAWjC;;;OAGG;IACH,OAAO,CAAC,eAAe;CAIxB"}
+{"version":3,"file":"ChatClient.d.ts","sourceRoot":"","sources":["../src/ChatClient.ts"],"names":[],"mappings":"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"}

package/dist/ChatClient.js

@@ -1,5 +1,5 @@
 // ChatClient.ts — Main SDK facade
-import { LogLevel } from '@microsoft/signalr';
+import { HubConnectionState, LogLevel } from '@microsoft/signalr';
 import { HttpClient } from './http/HttpClient.js';
 import { AuthApi } from './http/AuthApi.js';
 import { ParticipantApi } from './http/ParticipantApi.js';
@@ -94,16 +94,26 @@ export class ChatClient {
         // ---------------------------------------------------------------------------
         this._currentUser = null;
         this._token = options.token ?? null;
-        // Build the combined token provider:
-        // 1. Return _token if it has been set (via constructor or setToken()).
-        // 2. Fall back to the external tokenProvider if provided.
-        // 3. Return null otherwise.
+        // Build the combined token provider — see ChatClientOptions.tokenProvider
+        // for the rationale. The external provider takes priority when it returns
+        // a non-empty value so refresh-token rotation systems keep working even
+        // after setToken() has been called.
         const externalProvider = options.tokenProvider;
-        this._internalTokenProvider = () => this._token ?? (externalProvider ? externalProvider() : null);
+        this._internalTokenProvider = () => {
+            if (externalProvider) {
+                const fromProvider = externalProvider();
+                if (fromProvider)
+                    return fromProvider;
+            }
+            return this._token;
+        };
         // Shared HTTP client used by all REST API modules
         const http = new HttpClient({
             baseUrl: options.baseUrl,
             tokenProvider: this._internalTokenProvider,
+            ...(options.requestTimeoutMs !== undefined
+                ? { requestTimeoutMs: options.requestTimeoutMs }
+                : {}),
         });
         // Instantiate REST API modules
         this.participants = new ParticipantApi(http);
@@ -139,18 +149,81 @@ export class ChatClient {
     /**
      * Update the JWT token.
      *
-     * The new token takes effect immediately for all subsequent HTTP requests.
-     * Active SignalR connections are NOT updated — they must be reconnected
-     * (disconnect() then connect()) for the new token to be used.
+     * Effect on requests:
+     *   - HTTP: takes effect on the very next request.
+     *   - SignalR: existing active connections keep using the token they were
+     *     opened with. To apply the new token immediately to active hubs, call
+     *     `refreshConnections()` after `setToken()`.
+     *
+     * Pass `null` to clear the internally held token (same as `clearToken()`):
+     * both `_token` and `currentUser` are cleared so the SDK no longer reports
+     * stale identity. If a `tokenProvider` is configured and still returns a
+     * value, it will continue to be used regardless of this call.
      */
     setToken(token) {
         this._token = token;
+        if (token === null) {
+            this._currentUser = null;
+        }
+    }
+    /**
+     * Clear the internally held JWT token and authenticated user.
+     *
+     * After this, the configured `tokenProvider` (if any) becomes the only
+     * source of tokens. Use `logout()` instead when you also want to disconnect
+     * SignalR hubs.
+     */
+    clearToken() {
+        this._token = null;
+        this._currentUser = null;
+    }
+    /**
+     * Disconnect any active SignalR hub and reconnect it with the latest token.
+     *
+     * Useful right after `setToken()` to propagate the new token to live hubs.
+     * Hubs that are not currently connected are left untouched.
+     *
+     * Re-joins of conversations / re-subscriptions of presence are NOT performed
+     * automatically here — `disconnect()` clears that local tracking by design.
+     * The application is responsible for re-issuing those after a manual refresh
+     * (or for using `ReconnectionManager` for transparent recovery).
+     */
+    async refreshConnections() {
+        const tasks = [];
+        if (this.realtime.chat.state === HubConnectionState.Connected) {
+            tasks.push((async () => {
+                await this.realtime.chat.disconnect();
+                await this.realtime.chat.connect();
+            })());
+        }
+        if (this.realtime.notifications.state === HubConnectionState.Connected) {
+            tasks.push((async () => {
+                await this.realtime.notifications.disconnect();
+                await this.realtime.notifications.connect();
+            })());
+        }
+        await Promise.all(tasks);
+    }
+    /**
+     * Log the current user out: clear the internal token + currentUser and
+     * disconnect both SignalR hubs.
+     *
+     * Note: there is no server-side logout endpoint — this only clears local
+     * SDK state. If a `tokenProvider` is configured and still returns a token,
+     * subsequent requests can authenticate again with that token.
+     */
+    async logout() {
+        this.clearToken();
+        await this.disconnect();
     }
     /**
      * Disconnect all SignalR hubs (ChatHub + NotificationHub).
      *
      * Resolves after both hubs have finished disconnecting. Individual hub
      * disconnect failures do not prevent the other hub from disconnecting.
+     *
+     * Both hubs set their `intentionallyClosed` flag, so a `ReconnectionManager`
+     * attached to them will skip auto-reconnect for the resulting close.
      */
     async disconnect() {
         await Promise.allSettled([