@manonero/chat-client-sdk 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -126,7 +126,7 @@ import type { ChatClientSignalrOptions, ChatClientRealtime } from '@manonero/cha
 import type { UploadProgressCallback } from '@manonero/chat-client-sdk';
 
 // RFC 7807 Problem Details — dùng khi cần parse/tạo lỗi thủ công
-import type { ProblemDetails } from '@manonero/chat-client-sdk';
+import type { ProblemDetails, ProblemError } from '@manonero/chat-client-sdk';
 
 // Mark as read request type (REST)
 import type { MarkAsReadRequest } from '@manonero/chat-client-sdk';
@@ -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 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ập nhật JWT token. Có hiệu lực ngay với mọi HTTP request tiếp theo.
+> ⚠️ 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.
 
-> ⚠️ 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.
+> ℹ️ 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();
 ```
@@ -297,8 +335,8 @@ interface AuthUserInfo {
   id: string;
   uniqueName: string;
   fullName: string;
-  avatar?: string;        // URL thuần (KHÔNG phải MediaReference)
-  role?: string | null;  // 'dev' với dev users; null với Google/DsAccount users
+  avatar?: string | null; // URL thuần (KHÔNG phải MediaReference); server có thể trả null
+  role?: string | null;   // 'dev' với dev users; null với Google/DsAccount users
 }
 ```
 
@@ -351,8 +389,8 @@ interface ParticipantDto {
   id: string;
   uniqueName: string;
   fullName: string;
-  avatar?: MediaReference;
-  gender?: string;
+  avatar?: MediaReference | null; // hỗ trợ cả internal storageKey lẫn external URL; server có thể trả null
+  gender?: string | null;
   isBot: boolean;
   isOnline: boolean;
   lastSeenAt?: string | null;  // ISO 8601, null khi đang online
@@ -440,17 +478,29 @@ const updated = await client.conversations.update('conv-id', {
 });
 ```
 
-### `leave(id: string): Promise<void>`
+### `delete(id: string): Promise<void>`
+
+Hành vi phụ thuộc vào loại cuộc hội thoại:
+- **Group** → rời nhóm (tương đương `leaveGroup()`). Các participant khác vẫn còn đó.
+- **OneToOne / Self** → ẩn cuộc hội thoại khỏi danh sách (soft-delete). Conversation vẫn tồn tại và sẽ tự khôi phục khi có tin nhắn mới.
+
+```ts
+await client.conversations.delete('conv-id');
+```
+
+### `leaveGroup(id: string): Promise<void>`
 
-Rời khỏi cuộc hội thoại. Các participant khác vẫn còn đó.
+Rời cuộc hội thoại **Group** một cách tường minh. Trả về `403 Forbidden` nếu conversation không phải Group.
+
+> Dùng `leaveGroup()` khi cần ngữ nghĩa Group-only với phản hồi lỗi rõ ràng cho non-Group. Dùng `delete()` khi muốn xử lý cả Group lẫn OneToOne/Self trong cùng một flow.
 
 ```ts
-await client.conversations.leave('conv-id');
+await client.conversations.leaveGroup('conv-id');
 ```
 
 ### `findOneToOne(otherParticipantId): Promise<ConversationDto | null>`
 
-Tìm cuộc hội thoại 1-1 với user khác. Trả về `null` (HTTP 204) nếu chưa có.
+Tìm cuộc hội thoại 1-1 với user khác. Trả về `null` nếu chưa có (server trả 404, SDK chuyển thành `null` để gọi không cần try/catch).
 
 ```ts
 const existing = await client.conversations.findOneToOne('other-user-id');
@@ -490,16 +540,49 @@ await client.conversations.pin('conv-id');
 await client.conversations.unpin('conv-id');
 ```
 
-### `markAsRead(id, messageId) / markAsUnread(id): Promise<void>`
+### `markAsRead(id, request) / markAsUnread(id): Promise<void>`
 
 ```ts
 // Đánh dấu đã đọc đến messageId
-await client.conversations.markAsRead('conv-id', 'last-message-id');
+await client.conversations.markAsRead('conv-id', { messageId: 'last-message-id' });
 
 // Đánh dấu chưa đọc
 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
@@ -508,8 +591,8 @@ type ConversationType = 'Group' | 'OneToOne' | 'Self';
 interface ConversationDto {
   id: string;
   type: ConversationType;
-  name?: string;                  // Tên nhóm (chỉ Group)
-  avatar?: MediaReference;
+  name?: string | null;           // Tên nhóm (chỉ Group); null cho OneToOne/Self
+  avatar?: MediaReference | null;
   ownerId: string;
   lastMessageAt?: string | null;  // ISO 8601, null khi chưa có tin nhắn
   lastMessageId?: string | null;  // null khi chưa có tin nhắn
@@ -533,8 +616,8 @@ interface ConversationParticipantDto {
 interface ConversationListItemDto {
   id: string;
   type: ConversationType;
-  name?: string;
-  avatar?: MediaReference;
+  name?: string | null;            // null cho OneToOne/Self
+  avatar?: MediaReference | null;
   lastMessageAt?: string | null;   // ISO 8601
   lastMessageId?: string | null;
   lastMessage?: MessageDto | null; // Preview tin nhắn cuối, null khi chưa có tin nhắn
@@ -543,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;
+}
 ```
 
 ---
@@ -612,11 +738,12 @@ Chỉ người gửi mới có thể chỉnh sửa.
 ```ts
 const edited = await client.messages.edit('msg-id', {
   blocks: [{ $type: 'text', format: 'Plain', content: 'Nội dung đã sửa', plainText: 'Nội dung đã sửa' }],
-  mentions: [], // optional
+  mentions: [],              // optional
+  replyToMessageId: null,   // optional — null để xóa reply reference
 });
 ```
 
-> ⚠️ **Khác biệt REST vs SignalR:** REST dùng `{ blocks, mentions }`, SignalR dùng `{ messageId, newBlocks, newMentions }`.
+> ⚠️ **Khác biệt REST vs SignalR:** REST dùng `{ blocks, mentions, replyToMessageId }`, SignalR dùng `{ messageId, newBlocks, newMentions, newReplyToMessageId }`.
 
 ### `delete(messageId): Promise<{ messageId, deletedAt }>`
 
@@ -653,7 +780,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;
@@ -699,6 +825,7 @@ interface SendMessageRequest {
 interface EditMessageRequest {
   blocks: Block[];
   mentions?: Mention[];
+  replyToMessageId?: string | null; // null để xóa reply reference
 }
 
 // Request đánh dấu đã đọc (REST)
@@ -756,18 +883,37 @@ const result = await client.files.upload(uploadUrl, file, (loaded, total) => {
 
 > Khi có `onProgress`, SDK dùng XHR thay vì fetch (vì fetch không hỗ trợ upload progress events).
 
-### `getDownloadUrl(storageKey: string): string`
+### `getDownloadUrl(storageKey, signed?): string`
 
 Tạo URL tải file tuyệt đối (dùng để hiển thị ảnh, tải xuống, v.v.).
 
 ```ts
+// URL public (mặc định)
 const url = client.files.getDownloadUrl('01HXABCDEF/photo.jpg');
 // → "https://chat-api.example.com/api/files/01HXABCDEF/photo.jpg"
 ```
 
+#### Signed URL (kiểm soát truy cập)
+
+Khi server bật signed download (kiểm soát truy cập có thời hạn), truyền `expires` + `sig` ở tham số thứ hai:
+
+```ts
+const url = client.files.getDownloadUrl('01HXABCDEF/photo.jpg', {
+  expires: '2026-03-26T13:00:00.0000000Z',
+  sig: 'abc123...',
+});
+// → ".../api/files/01HXABCDEF/photo.jpg?expires=...&sig=abc123..."
+```
+
+> Server trả `400 Bad Request` (title `Invalid Signature`) nếu URL bị sửa hoặc đã hết hạn. `expires` và `sig` thường lấy từ nguồn server-issued tương ứng (không tự ghép).
+
+> **Khi server bật signed download:** Server thường trả sẵn `url` trong `MediaReference` (đã gắn `expires` + `sig`) thay vì yêu cầu client tự gọi `getDownloadUrl(storageKey, { expires, sig })`. Trong trường hợp đó, ưu tiên dùng `MediaReference.url` (sau khi resolve relative — xem [MediaReference](#mediareference)), **không** dùng `getDownloadUrl(storageKey)` vì sẽ tạo ra unsigned URL và bị server từ chối.
+
+> **Encoding:** `storageKey` có thể chứa `/` — SDK giữ `/` làm phân cách path; các ký tự đặc biệt khác (space, `?`, `#`, `%`...) tự động được percent-encode theo từng segment.
+
 ### `delete(storageKey: string): Promise<void>`
 
-Xóa file. Chỉ người upload mới có thể xóa. `storageKey` có thể chứa `/`, không cần encode.
+Xóa file. Chỉ người upload mới có thể xóa. Cùng quy tắc encoding như `getDownloadUrl()`: `/` được giữ, ký tự đặc biệt khác tự động percent-encoded.
 
 ```ts
 await client.files.delete('01HXABCDEF/photo.jpg');
@@ -808,7 +954,7 @@ GET (`list`, `getById`) là **public**. Các thao tác quản lý yêu cầu JWT
 
 ### `list(params?): Promise<PagedResult<BotDto>>`
 
-> Lưu ý: BotApi dùng **page-based** pagination (không phải cursor-based). `page` bắt đầu từ 1. Server cache kết quả **5 phút**.
+> Lưu ý: BotApi dùng **page-based** pagination (không phải cursor-based). `page` bắt đầu từ 1.
 
 ```ts
 const result = await client.bots.list({ page: 1, pageSize: 20 });
@@ -818,17 +964,15 @@ console.log(result.totalCount); // Tổng số bot
 
 ### `getById(id): Promise<BotDto>`
 
-> Server cache kết quả **5 phút**.
-
 ```ts
 const bot = await client.bots.getById('bot-id');
 // Lấy thêm thông tin display: name, avatar
 const participant = await client.participants.getById(bot.participantId);
 ```
 
-### `create(request): Promise<BotDto & { apiKey: string }>`
+### `create(request): Promise<BotDto>`
 
-Tạo bot và nhận `apiKey` một lần — **lưu ngay**, server không lưu key này.
+Đăng ký bot mới.
 
 ```ts
 const bot = await client.bots.create({
@@ -836,10 +980,8 @@ const bot = await client.bots.create({
   fullName: 'My Assistant Bot',
   description: 'Trợ lý AI',
   kafkaTopic: 'my-bot-topic',     // Không thể thay đổi sau khi tạo
-  rateLimitPerSecond: 5,
   listenAllGroupMessages: false,
 });
-const apiKey = bot.apiKey; // Lưu ngay!
 ```
 
 ### `update(id, request): Promise<BotDto>`
@@ -847,7 +989,6 @@ const apiKey = bot.apiKey; // Lưu ngay!
 ```ts
 await client.bots.update('bot-id', {
   fullName: 'Updated Bot Name',
-  rateLimitPerSecond: 10,
   // kafkaTopic KHÔNG thể cập nhật
 });
 ```
@@ -859,14 +1000,6 @@ await client.bots.activate('bot-id');
 await client.bots.deactivate('bot-id');
 ```
 
-### `regenerateKey(id): Promise<RegenerateKeyResponse>`
-
-Xoay API key — key cũ bị vô hiệu hóa ngay lập tức.
-
-```ts
-const { apiKey } = await client.bots.regenerateKey('bot-id');
-```
-
 ### `delete(id): Promise<void>`
 
 Soft delete.
@@ -881,11 +1014,10 @@ await client.bots.delete('bot-id');
 interface BotDto {
   id: string;
   participantId: string;      // Dùng để lấy name/avatar từ ParticipantApi
-  description?: string;
-  metadata?: Record<string, unknown>;
+  description?: string | null;
+  metadata?: Record<string, unknown> | null;
   kafkaTopic: string;         // KHÔNG thể thay đổi sau khi tạo
   isActive: boolean;
-  rateLimitPerSecond: number;
   listenAllGroupMessages: boolean;
   createdBy: string;          // ID của người tạo bot
   createdAt: string;          // ISO 8601
@@ -905,7 +1037,6 @@ interface CreateBotRequest {
   description?: string;
   metadata?: Record<string, unknown>;
   kafkaTopic: string;                // KHÔNG thể thay đổi sau khi tạo
-  rateLimitPerSecond?: number;
   listenAllGroupMessages?: boolean;  // Mặc định false
 }
 
@@ -915,7 +1046,6 @@ interface UpdateBotRequest {
   avatar?: MediaReference;
   description?: string;
   metadata?: Record<string, unknown>;
-  rateLimitPerSecond?: number;
   listenAllGroupMessages?: boolean;
   // kafkaTopic KHÔNG thể cập nhật
 }
@@ -939,7 +1069,34 @@ const order = await client.proxy.post<Order>('trading', 'api/orders', {
   quantity: 100,
 });
 
-// Request tùy chỉnh method
+// PUT /api/proxy/trading/api/orders/123
+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',
   headers: { 'X-Custom-Header': 'value' },
@@ -1035,6 +1192,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
 
@@ -1055,10 +1218,11 @@ if (ack.success) {
 ### Chỉnh sửa / Xóa / Khôi phục tin nhắn qua SignalR
 
 ```ts
-// Chỉnh sửa — dùng newBlocks/newMentions (khác REST!)
+// Chỉnh sửa — dùng newBlocks/newMentions/newReplyToMessageId (khác REST!)
 const editAck = await client.realtime.chat.editMessage({
   messageId: 'msg-id',
   newBlocks: [{ $type: 'text', format: 'Plain', content: 'Đã sửa', plainText: 'Đã sửa' }],
+  newReplyToMessageId: null, // optional — null để xóa reply reference
 });
 
 // Xóa — truyền object, KHÔNG phải string
@@ -1113,6 +1277,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õ |
@@ -1138,7 +1303,8 @@ interface MessageUpdatedDto {
   blocks: Block[];
   plainTextContent: string | null;
   mentions?: Mention[];
-  updatedAt: string;          // ISO 8601
+  updatedAt: string;                    // ISO 8601
+  replyToMessageId?: string | null;     // null nếu reply reference đã bị xóa
 }
 
 // Tin nhắn bị xóa
@@ -1186,6 +1352,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
@@ -1263,7 +1459,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
@@ -1278,7 +1474,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']);
 ```
 
@@ -1300,6 +1496,8 @@ await client.realtime.notifications.unsubscribeFromPresence(['user-1']);
 | `conversationPinned` | `ConversationPinnedDto` | Cuộc hội thoại được pin |
 | `conversationUnpinned` | `ConversationUnpinnedDto` | Cuộc hội thoại được unpin |
 | `readStatusChanged` | `ReadStatusChangedDto` | Trạng thái đọc thay đổi |
+| `conversationDeleted` | `ConversationDeletedDto` | Conversation bị ẩn/xóa khỏi danh sách (chỉ OneToOne & Self, chỉ user thực hiện) |
+| `conversationRestored` | `ConversationRestoredDto` | Conversation bị ẩn được khôi phục tự động do có tin nhắn mới (chỉ OneToOne & Self) |
 | `error` | `HubErrorDto` | Lỗi từ server |
 | `reconnecting` | `Error \| undefined` | Đang reconnect |
 | `reconnected` | `string \| undefined` | Đã reconnect |
@@ -1325,11 +1523,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
 }
@@ -1354,15 +1552,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;
 }
@@ -1371,7 +1569,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
 }
 
@@ -1380,7 +1578,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
 }
 
@@ -1400,6 +1598,26 @@ interface ReadStatusChangedDto {
   unreadCount: number;
   markedAsUnread: boolean;    // true khi user chủ động đánh dấu chưa đọc
 }
+
+// Conversation bị ẩn/xóa khỏi danh sách của user.
+// Chỉ áp dụng cho OneToOne và Self — không broadcast tới người còn lại.
+// Conversation vẫn tồn tại và sẽ tự khôi phục khi có tin nhắn mới.
+interface ConversationDeletedDto {
+  conversationId: string;
+  deletedAt: string;          // ISO 8601
+}
+
+// Conversation đã bị ẩn được khôi phục tự động vì có tin nhắn mới.
+// Client nên thêm lại conversation vào sidebar với metadata đầy đủ từ payload.
+// Chú ý: Ngay sau event này, client cũng sẽ nhận newMessageNotification cho tin nhắn kích hoạt khôi phục.
+interface ConversationRestoredDto {
+  conversationId: string;
+  type: ConversationType;
+  name?: string | null;
+  avatar?: MediaReference | null;
+  participantCount: number;
+  restoredAt: string;         // ISO 8601
+}
 ```
 
 ---
@@ -1418,7 +1636,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
   },
@@ -1432,7 +1650,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.
 
 ---
 
@@ -1646,7 +1866,7 @@ type ButtonStyle = 'Default' | 'Primary' | 'Danger';
 interface ActionButton {
   label: string;
   action: ButtonAction;
-  value: string | null;
+  value?: string | null;
   style: ButtonStyle;
 }
 
@@ -1730,8 +1950,34 @@ interface PagedResult<T> {
 
 ```ts
 interface MediaReference {
-  storageKey?: string; // Key nội bộ — dùng FileApi.getDownloadUrl() để tạo URL
-  url?: string;        // URL bên ngoài (không qua storage)
+  storageKey?: string; // Key lưu trữ nội bộ — dùng FileApi.getDownloadUrl(storageKey) để tạo URL tuyệt đối
+  url?: string;        // URL do server cấp sẵn (xem chi tiết bên dưới)
+}
+```
+
+Trường `url` có hai dạng tuỳ cấu hình server:
+
+| Dạng | Ví dụ | Cách dùng |
+|------|-------|-----------|
+| **Relative signed URL** | `/api/files/abc/photo.jpg?expires=...&sig=...` | Phải prepend `baseUrl` trước khi dùng |
+| **Absolute external URL** | `https://cdn.example.com/photo.jpg` | Dùng trực tiếp |
+
+> **Quy tắc resolve:** Kiểm tra `url` trước, `storageKey` sau. Nếu `url` bắt đầu bằng `/`, đây là relative signed URL — cần ghép `baseUrl`. Tuyệt đối **không** bỏ qua `url` để dùng `storageKey` vì signed URL có thể bắt buộc (server trả `400 Invalid Signature` nếu gọi bằng unsigned URL).
+
+```ts
+// Helper chuẩn để resolve MediaReference → URL tuyệt đối
+function resolveMediaRef(
+  ref: MediaReference | null | undefined,
+  baseUrl: string,
+  getDownloadUrl: (key: string) => string,
+): string | null {
+  if (!ref) return null;
+  if (ref.url) {
+    // Relative signed URL → prepend baseUrl
+    return ref.url.startsWith('/') ? baseUrl.replace(/\/$/, '') + ref.url : ref.url;
+  }
+  if (ref.storageKey) return getDownloadUrl(ref.storageKey);
+  return null;
 }
 ```
 
@@ -1745,7 +1991,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)
@@ -1778,13 +2024,15 @@ type SystemEventType =
   | 'MemberAdded'          // Thêm thành viên
   | 'MemberRemoved'        // Xóa thành viên
   | 'MemberLeft'           // Thành viên tự rời
-  | 'Custom';
+  | 'Custom';              // Sự kiện tùy chỉnh do server định nghĩa
 
 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" }).
+  // Server có thể trả null cho event không kèm metadata (vd. MemberAdded thuần).
+  metadata?: Record<string, string> | null;
 }
 
 // SignalR (ChatHub) version — kế thừa SystemEventInfo, thêm display names
@@ -1800,7 +2048,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;
 }
 ```
 
@@ -1813,9 +2062,10 @@ 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
+  clientMessageId?: string | null; // ID tạm của client (echo). null nếu bot không truyền
 }
 
 interface StreamStatusUpdatedDto {
@@ -1841,6 +2091,7 @@ interface StreamCompletedDto {
   conversationId: string;
   message: ChatMessageDto;   // Tin nhắn hoàn chỉnh (SignalR, không phải REST MessageDto)
   completedAt: string;       // ISO 8601
+  finishReason?: string | null; // Lý do kết thúc stream. null nếu bot không truyền
 }
 
 interface StreamAbortedDto {
@@ -1920,7 +2171,17 @@ try {
   if (err instanceof ChatApiError) {
     console.error(`HTTP ${err.status}: ${err.title}`);
     console.error('Chi tiết:', err.detail);
-    
+
+    // Xem tất cả lỗi validation chi tiết
+    if (err.errors) {
+      err.errors.forEach(e => console.error(`[${e.code}] ${e.description}`));
+    }
+
+    // Dùng traceId để correlate log
+    if (err.traceId) {
+      console.error('TraceId:', err.traceId);
+    }
+
     switch (err.status) {
       case 401: // Unauthorized — token hết hạn/không hợp lệ
         await refreshAndRetry();
@@ -1943,12 +2204,17 @@ try {
 | Thuộc tính | Kiểu | Mô tả |
 |------------|------|-------|
 | `status` | `number` | HTTP status code |
-| `title` | `string` | Tiêu đề lỗi (từ RFC 7807 `title`) |
-| `detail` | `string \| undefined` | Chi tiết lỗi (từ RFC 7807 `detail`) |
+| `title` | `string` | Tiêu đề lỗi — giá trị `ErrorType` enum: `Validation`, `NotFound`, `Conflict`, `Forbidden`, `Unauthorized`, `Unexpected`. Auth endpoints trả `Bad Request`, v.v. |
+| `detail` | `string \| undefined` | Mô tả của lỗi đầu tiên (từ RFC 7807 `detail`) |
+| `type` | `string \| undefined` | URI tham chiếu RFC 7807 `type` (nếu server gửi). `undefined` cho proxy errors và lỗi sinh nội bộ (timeout/network/parse) |
+| `errors` | `ProblemError[] \| undefined` | Mảng tất cả lỗi chi tiết — có khi lỗi đi qua handler (ErrorOr path). `undefined` cho lỗi middleware/filter, proxy errors, và lỗi sinh nội bộ |
+| `traceId` | `string \| undefined` | W3C trace ID để correlate log. Tự động thêm bởi framework. `undefined` cho proxy errors và lỗi sinh nội bộ |
 | `message` | `string` | `detail ?? title` (kế thừa từ `Error`) |
 | `name` | `string` | Luôn là `"ChatApiError"` |
 
-Server trả lỗi dạng RFC 7807: `{ status, title, detail }`. Endpoint proxy trả `{ detail }` đơn giản hơn — SDK xử lý cả hai.
+Server trả lỗi dạng RFC 7807: `{ type?, status, title, detail?, errors?, traceId? }`. Endpoint proxy trả `{ detail }` đơn giản hơn — SDK xử lý cả hai.
+
+> **Lưu ý:** `errors` chỉ có mặt khi lỗi đi qua handler (ErrorOr path → `ToProblemResult`). Lỗi từ middleware/filter (401 thiếu token, lỗi routing) trả ProblemDetails **không có** trường `errors`.
 
 ### Static methods
 
@@ -1979,7 +2245,16 @@ interface ProblemDetails {
   status: number;
   title: string;
   detail?: string;
-  type?: string;     // URI reference — thường không dùng trực tiếp
+  type?: string;          // URI tham chiếu (RFC 7807) — `ChatApiError.fromProblemDetails` sẽ forward sang `error.type`
+  errors?: ProblemError[]; // Có khi lỗi đi qua handler; vắng mặt cho lỗi middleware/filter
+  traceId?: string;        // W3C trace ID — tự động thêm bởi framework
+}
+
+// Một phần tử trong mảng `errors`
+interface ProblemError {
+  code: string;        // Mã định danh lỗi, ví dụ: "Bot.NotFound", "UniqueName"
+  description: string; // Mô tả chi tiết lỗi
+  type: string;        // ErrorType: "Validation", "NotFound", "Conflict", "Forbidden", "Unauthorized", "Unexpected"
 }
 ```
 
@@ -2077,33 +2352,63 @@ 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
 
 | Thao tác | REST | SignalR |
 |----------|------|---------|
-| Edit message | `{ blocks, mentions }` | `{ messageId, newBlocks, newMentions }` |
+| Edit message | `{ blocks, mentions, replyToMessageId? }` | `{ messageId, newBlocks, newMentions, newReplyToMessageId? }` |
 | Delete message | `messages.delete(messageId)` | `deleteMessage({ messageId })` — object, không phải string |
 | Stream completion | Không có event | `streamCompleted` thay `messageReceived` |
 
 ### File upload — storageKey vs URL
 
+**Khi gửi tin nhắn (client → server):** dùng `storageKey` trong block, không dùng `url`.
+
 ```ts
-// Sau khi upload, dùng storageKey làm MediaReference
 const { storageKey } = await client.files.uploadFile(file);
 
-// Trong block:
 const block: ImageBlock = {
   $type: 'image',
-  source: { storageKey }, // KHÔNG phải url
+  source: { storageKey }, // ĐÚNG — KHÔNG đặt url ở đây
   // ...
 };
+```
+
+**Khi hiển thị tin nhắn nhận từ server:** server trả về `MediaReference` có thể chứa cả `storageKey` lẫn `url`. Dùng helper resolve sau:
+
+```ts
+// resolve MediaReference → URL tuyệt đối để dùng trong <img src>, <a href>, v.v.
+function resolveMediaRef(
+  ref: MediaReference | null | undefined,
+  baseUrl: string,
+  getDownloadUrl: (key: string) => string,
+): string | null {
+  if (!ref) return null;
+  if (ref.url) {
+    // url có thể là relative signed URL ("/api/files/...?sig=...")
+    // hoặc absolute external URL ("https://...")
+    return ref.url.startsWith('/') ? baseUrl.replace(/\/$/, '') + ref.url : ref.url;
+  }
+  if (ref.storageKey) return getDownloadUrl(ref.storageKey);
+  return null;
+}
 
-// Để hiển thị ảnh:
-const displayUrl = client.files.getDownloadUrl(storageKey);
+// Ví dụ dùng với ImageBlock:
+const displayUrl = resolveMediaRef(
+  block.source,
+  'https://chat-api.example.com',
+  client.files.getDownloadUrl.bind(client.files),
+);
 ```
 
+> **Tại sao không chỉ dùng `getDownloadUrl(storageKey)`?** Khi server bật signed download, `getDownloadUrl(storageKey)` tạo unsigned URL → server từ chối (`400 Invalid Signature`). `url` trong `MediaReference` đã được server gắn sẵn signature và phải được ưu tiên dùng.
+
+> **Tại sao không dùng `url` trực tiếp?** Server trả `url` dạng relative (`/api/files/...`), không phải absolute. Dùng trực tiếp trong `<img src>` sẽ resolve về origin của frontend thay vì API server nếu hai service chạy trên host/port khác nhau.
+
 ### BotDto — không có tên/avatar
 
 `BotDto` **không** chứa `uniqueName` hay `fullName`. Phải gọi thêm: