@manonero/chat-client-sdk 0.0.1-beta.1 → 0.0.1-beta.10

package/README.md

@@ -13,19 +13,20 @@
 5. [Participant — ParticipantApi](#5-participant--participantapi)
 6. [Conversation — ConversationApi](#6-conversation--conversationapi)
 7. [Message — MessageApi](#7-message--messageapi)
-8. [File — FileApi](#8-file--fileapi)
-9. [Bot — BotApi](#9-bot--botapi)
-10. [Proxy — ProxyApi](#10-proxy--proxyapi)
-11. [Health — HealthApi](#11-health--healthapi)
-12. [Real-time: ChatHubClient](#12-real-time-chathubclient)
-13. [Real-time: NotificationHubClient](#13-real-time-notificationhubclient)
-14. [ReconnectionManager](#14-reconnectionmanager)
-15. [Hệ thống Block (nội dung tin nhắn)](#15-hệ-thống-block-nội-dung-tin-nhắn)
-16. [Toàn bộ kiểu dữ liệu (Types)](#16-toàn-bộ-kiểu-dữ-liệu-types)
-17. [Xử lý lỗi — ChatApiError](#17-xử-lý-lỗi--chatapierror)
-18. [TypedEventEmitter](#18-typedeventemitter)
-19. [Lưu ý quan trọng](#19-lưu-ý-quan-trọng)
-20. [Ví dụ đầy đủ](#20-ví-dụ-đầy-đủ)
+8. [Tìm kiếm — SearchApi](#8-tìm-kiếm--searchapi)
+9. [File — FileApi](#9-file--fileapi)
+10. [Bot — BotApi](#10-bot--botapi)
+11. [Proxy — ProxyApi](#11-proxy--proxyapi)
+12. [Health — HealthApi](#12-health--healthapi)
+13. [Real-time: ChatHubClient](#13-real-time-chathubclient)
+14. [Real-time: NotificationHubClient](#14-real-time-notificationhubclient)
+15. [ReconnectionManager](#15-reconnectionmanager)
+16. [Hệ thống Block (nội dung tin nhắn)](#16-hệ-thống-block-nội-dung-tin-nhắn)
+17. [Toàn bộ kiểu dữ liệu (Types)](#17-toàn-bộ-kiểu-dữ-liệu-types)
+18. [Xử lý lỗi — ChatApiError](#18-xử-lý-lỗi--chatapierror)
+19. [TypedEventEmitter](#19-typedeventemitter)
+20. [Lưu ý quan trọng](#20-lưu-ý-quan-trọng)
+21. [Ví dụ đầy đủ](#21-ví-dụ-đầy-đủ)
 
 ---
 
@@ -37,6 +38,7 @@ ChatClient (facade chính)
 ├── participants  → ParticipantApi   (quản lý người dùng)
 ├── conversations → ConversationApi  (quản lý cuộc hội thoại)
 ├── messages      → MessageApi       (tin nhắn)
+├── search        → SearchApi        (tìm kiếm tổng hợp conversations + messages)
 ├── files         → FileApi          (upload/download file)
 ├── bots          → BotApi           (quản lý bot)
 ├── proxy         → ProxyApi         (proxy đến backend khác)
@@ -92,6 +94,9 @@ import type { HttpClientOptions } from '@manonero/chat-client-sdk';
 // Event map types — dùng khi cần typed wrapper
 import type { ChatHubEventMap, NotificationHubEventMap } from '@manonero/chat-client-sdk';
 
+// Ephemeral broadcast (dùng chung cho cả hai hub) — generic theo kiểu của `data`
+import type { EphemeralBroadcastDto, BroadcastSenderType } from '@manonero/chat-client-sdk';
+
 // Hub options (khi dùng hub client độc lập, không qua ChatClient)
 import type { ChatHubClientOptions, NotificationHubClientOptions } from '@manonero/chat-client-sdk';
 
@@ -187,6 +192,50 @@ const client = new ChatClient({
 });
 ```
 
+### Cấu hình transport SignalR (`connectionOptions`)
+
+SDK mặc định kết nối thẳng qua WebSockets, bỏ qua bước negotiate:
+
+```ts
+{
+  skipNegotiation: true,
+  transport: HttpTransportType.WebSockets,
+}
+```
+
+Mọi giá trị truyền vào `signalrOptions.connectionOptions` sẽ **ghi đè** mặc định trên (đây là toàn bộ `IHttpConnectionOptions` của `@microsoft/signalr`, nên có thể override cả `accessTokenFactory`, `headers`, `withCredentials`, `httpClient`, …):
+
+```ts
+import { HttpTransportType } from '@microsoft/signalr';
+
+// Quay lại luồng negotiate tiêu chuẩn (ví dụ khi đứng sau proxy không hỗ trợ WS)
+const client = new ChatClient({
+  baseUrl: 'https://chat-api.example.com',
+  signalrOptions: {
+    connectionOptions: {
+      skipNegotiation: false,
+      transport: HttpTransportType.WebSockets | HttpTransportType.LongPolling,
+    },
+  },
+});
+```
+
+Có thể cấu hình riêng cho từng hub; giá trị riêng được merge đè lên `connectionOptions` chung:
+
+```ts
+const client = new ChatClient({
+  baseUrl: 'https://chat-api.example.com',
+  signalrOptions: {
+    connectionOptions: { withCredentials: false },              // áp dụng cho cả 2 hub
+    notificationConnectionOptions: { skipNegotiation: false },  // chỉ NotificationHub
+  },
+});
+```
+
+> **Lưu ý:** `skipNegotiation: true` chỉ hợp lệ khi `transport` đúng bằng `HttpTransportType.WebSockets` — kể cả tổ hợp cờ như `WebSockets | LongPolling` cũng bị SignalR từ chối. Nếu bạn đổi `transport` sang giá trị khác mà không nói gì về `skipNegotiation`, SDK sẽ tự bỏ mặc định `skipNegotiation: true`; nếu không, lỗi sẽ xuất hiện dưới dạng `connect()` bị reject (SignalR kiểm tra trong `HttpConnection.startInternal`, không phải lúc `build()`).
+>
+> Một key mang giá trị `undefined` được coi là "không cấu hình" và vẫn giữ mặc định — nên `connectionOptions: { transport: config.transport }` với `config.transport` optional sẽ không vô tình xoá mất transport mặc định.
+
 ---
 
 ## 3. ChatClient — Facade chính
@@ -208,6 +257,9 @@ new ChatClient(options: ChatClientOptions)
 | `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`) |
+| `signalrOptions.connectionOptions` | `IHttpConnectionOptions` | ❌ | Options truyền cho `withUrl()` của cả 2 hub. Ghi đè mặc định `skipNegotiation: true` + `transport: WebSockets` |
+| `signalrOptions.chatConnectionOptions` | `IHttpConnectionOptions` | ❌ | Chỉ áp dụng cho ChatHub, merge đè lên `connectionOptions` |
+| `signalrOptions.notificationConnectionOptions` | `IHttpConnectionOptions` | ❌ | Chỉ áp dụng cho NotificationHub, merge đè lên `connectionOptions` |
 
 ### Thuộc tính
 
@@ -217,6 +269,7 @@ new ChatClient(options: ChatClientOptions)
 | `participants` | `ParticipantApi` | Quản lý participant |
 | `conversations` | `ConversationApi` | Quản lý cuộc hội thoại |
 | `messages` | `MessageApi` | Thao tác với tin nhắn |
+| `search` | `SearchApi` | Tìm kiếm tổng hợp conversations + messages |
 | `files` | `FileApi` | Upload/download file |
 | `bots` | `BotApi` | Quản lý bot |
 | `proxy` | `ProxyApi` | Proxy đến backend khác |
@@ -250,9 +303,9 @@ 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.
+Reconnect lại từng hub đang ở trạng thái `Connected` với token mới nhất. 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`. Sau khi gọi `refreshConnections()`, ứng dụng phải tự `joinConversation` lại — hoặc dùng `ReconnectionManager` để khôi phục trong suốt cho mọi loại disconnect.
+> ℹ️ ChatHub **giữ nguyên** các conversation đã join: SDK snapshot danh sách trước khi reconnect rồi tự `joinConversation` lại sau đó (best-effort), nên event theo hội thoại tiếp tục chảy qua lần xoay token. NotificationHub không có khái niệm join nên tự động nhận lại event sau khi reconnect.
 
 ```ts
 client.setToken(newToken);
@@ -435,20 +488,24 @@ const conv = await client.conversations.create({
 });
 ```
 
-### `search(query, limit?): Promise<ConversationListItemDto[]>`
+> ⚠️ **Đã gỡ bỏ `conversations.search()`** — endpoint backend `GET /api/conversations/search` không còn được proxy qua gateway (trả `404`). Dùng endpoint tìm kiếm tổng hợp `client.search.search()` thay thế — xem [mục 8 — SearchApi](#8-tìm-kiếm--searchapi).
 
-Tìm kiếm theo tên cuộc hội thoại hoặc tên participant.
-
-```ts
-const results = await client.conversations.search('team', 10);
-```
-
-### `getById(id: string): Promise<ConversationDto>`
+### `getById(id, options?): Promise<ConversationDto>`
 
 ```ts
+// Mặc định: bao gồm danh sách thành viên
 const conv = await client.conversations.getById('conv-id-here');
+
+// Bỏ danh sách thành viên để giảm payload — khi đó `participants` trả về []
+const light = await client.conversations.getById('conv-id-here', {
+  includeParticipants: false,
+});
 ```
 
+| Param | Kiểu | Mặc định | Mô tả |
+|-------|------|----------|-------|
+| `options.includeParticipants` | `boolean` | `true` | Đặt `false` để bỏ mảng `participants` khỏi response (spec §6.4). Khi `false`, `participants` là `[]`. |
+
 ### `update(id, request): Promise<ConversationDto>`
 
 ```ts
@@ -536,7 +593,7 @@ if (page1.hasMore) {
 ```ts
 interface ConversationDto {
   id: string;
-  name: string;
+  name?: string | null;
   avatar?: MediaReference | null;
   ownerId: string;
   lastMessageAt?: string | null;  // ISO 8601, null khi chưa có tin nhắn
@@ -661,12 +718,14 @@ const newer = await client.messages.getHistory('conv-id', {
 
 ### `search(conversationId, query, limit?): Promise<MessageDto[]>`
 
-Full-text search trong cuộc hội thoại.
+Full-text search **trong phạm vi một cuộc hội thoại** (`GET /api/conversations/{conversationId}/messages/search`, spec §7.3).
 
 ```ts
 const results = await client.messages.search('conv-id', 'từ khóa tìm kiếm', 20);
 ```
 
+> ℹ️ Để tìm kiếm **xuyên suốt tất cả** cuộc hội thoại và tin nhắn, dùng `client.search.search()` — xem [mục 8 — SearchApi](#8-tìm-kiếm--searchapi).
+
 ### `getById(messageId): Promise<MessageDto>`
 
 ```ts
@@ -773,7 +832,67 @@ interface EditMessageRequest {
 
 ---
 
-## 8. File — FileApi
+## 8. Tìm kiếm — SearchApi
+
+**Truy cập:** `client.search`
+
+Endpoint tìm kiếm tổng hợp do gateway cung cấp (`GET /api/search`, spec §6.3) — tìm **conversations**, **messages**, hoặc **cả hai** trong một request. Yêu cầu JWT.
+
+> Endpoint này **thay thế** cho `GET /api/conversations/search` và `GET /api/messages/search` (global) của backend — hai endpoint đó không còn được proxy qua gateway. Việc tìm kiếm tin nhắn trong phạm vi **một** cuộc hội thoại vẫn dùng `client.messages.search()` (spec §7.3).
+
+### `search(params): Promise<SearchResult>`
+
+| Param | Kiểu | Mặc định | Mô tả |
+|-------|------|----------|-------|
+| `q` | `string` | — (**bắt buộc**) | Từ khóa tìm kiếm. Thiếu/rỗng → `400 Bad Request`. |
+| `type` | `'MESSAGE' \| 'CONVERSATION' \| 'BOTH'` | `'BOTH'` | Phạm vi tìm kiếm. Giá trị khác → `400 Bad Request`. |
+| `limit` | `number` | `20` | Số kết quả mỗi loại. |
+| `cursor` | `string` | — | Phân trang — **chỉ áp dụng cho messages** (opaque `nextCursor` từ response trước). |
+
+**Hành vi theo `type`:**
+
+- `CONVERSATION` — tìm conversations; mỗi item kèm `lastMessage` (full `MessageDto`). `messages` trả về `null`.
+- `MESSAGE` — tìm messages, **gom nhóm theo conversation**; mỗi nhóm kèm thông tin `conversation`. Phân trang (`nextCursor`/`hasMore`) phản ánh messages. `conversations` trả về `null`.
+- `BOTH` — thực hiện cả hai (mặc định).
+
+> Response **luôn có cả hai key** `conversations` và `messages`; phần không được yêu cầu bởi `type` sẽ là `null`.
+
+```ts
+// Tìm cả hai loại (mặc định)
+const result = await client.search.search({ q: 'hello' });
+
+// Conversations: kiểm tra lastMessage.isDeleted trước khi hiển thị
+for (const conv of result.conversations ?? []) {
+  const preview = conv.lastMessage?.isDeleted
+    ? 'Tin nhắn đã xóa'
+    : conv.lastMessage?.plainTextIndex ?? '';
+  console.log(conv.name, preview);
+}
+
+// Messages: gom nhóm theo conversation
+for (const group of result.messages?.groups ?? []) {
+  console.log('Trong:', group.conversation?.name ?? '(không rõ)');
+  for (const msg of group.messages) console.log('  -', msg.plainTextIndex);
+}
+```
+
+```ts
+// Chỉ tìm messages + phân trang
+let page = await client.search.search({ q: 'hello', type: 'MESSAGE', limit: 20 });
+while (page.messages?.hasMore) {
+  page = await client.search.search({
+    q: 'hello',
+    type: 'MESSAGE',
+    cursor: page.messages.nextCursor!, // opaque string — KHÔNG cast sang number
+  });
+}
+```
+
+> ⚠️ Giống `client.conversations.list()`, backend **không** filter `isDeleted` cho `lastMessage` — client **phải** tự kiểm tra `lastMessage.isDeleted` trước khi hiển thị. Nếu batch fetch lỗi, `lastMessage` (của conversation) hoặc `conversation` (của nhóm message) có thể là `null` (degrade graceful).
+
+---
+
+## 9. File — FileApi
 
 **Truy cập:** `client.files`
 
@@ -820,19 +939,9 @@ 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, 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)
+### `getDownloadUrl(storageKey, signed): string`
 
-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:
+Tạo URL tải file tuyệt đối có chữ ký (dùng để hiển thị ảnh, tải xuống, v.v.). Theo spec §8.3, **cả `expires` lẫn `sig` đều bắt buộc** — không có public unsigned access.
 
 ```ts
 const url = client.files.getDownloadUrl('01HXABCDEF/photo.jpg', {
@@ -842,9 +951,9 @@ const url = client.files.getDownloadUrl('01HXABCDEF/photo.jpg', {
 // → ".../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).
+> Server trả `400 Bad Request` (title `Invalid Signature`) nếu URL bị sửa hoặc đã hết hạn. `expires` và `sig` phải lấy từ nguồn server-issued (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.
+> **Trong thực tế:** Server thường trả sẵn `url` trong `MediaReference` (đã gắn `expires` + `sig`) cho mọi media của tin nhắn / participant. Ưu tiên dùng `MediaReference.url` (xem [MediaReference](#mediareference)) — chỉ gọi `getDownloadUrl()` khi bạn có sẵn cặp `expires`/`sig` từ một response server khác (ví dụ: `downloadUrl` từ `POST /api/files/upload`).
 
 > **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.
 
@@ -883,7 +992,7 @@ interface UploadResponse {
 
 ---
 
-## 9. Bot — BotApi
+## 10. Bot — BotApi
 
 **Truy cập:** `client.bots`
 
@@ -916,17 +1025,31 @@ const bot = await client.bots.create({
   uniqueName: 'my-bot',
   fullName: 'My Assistant Bot',
   description: 'Trợ lý AI',
-  kafkaTopic: 'my-bot-topic',     // Không thể thay đổi sau khi tạo
+  kafkaTopic: 'my-bot-topic',          // optional — null/omit = không nhận event qua Kafka
+  webhookUrl: 'https://bot.example.com/events', // optional — HTTP/2 NDJSON webhook
+  deliveryPreference: 'Both',          // optional — 'Both' | 'WebhookOnly' | 'KafkaOnly' (server default 'Both')
   listenAllGroupMessages: false,
 });
 ```
 
+> Bot có thể nhận outgoing event qua `kafkaTopic`, `webhookUrl`, cả hai, hoặc không cấu hình kênh nào. Cả hai field đều **optional** độc lập với nhau.
+>
+> `deliveryPreference` chỉ có hiệu lực khi bot có **cả** `kafkaTopic` lẫn `webhookUrl` được cấu hình. Bot chỉ có một kênh sẽ luôn dùng kênh đó bất kể preference.
+
 ### `update(id, request): Promise<BotDto>`
 
 ```ts
 await client.bots.update('bot-id', {
   fullName: 'Updated Bot Name',
-  // kafkaTopic KHÔNG thể cập nhật
+  kafkaTopic: 'new-topic',             // set/đổi topic
+  webhookUrl: 'https://bot.example.com/events/v2', // set/đổi webhook
+  deliveryPreference: 'WebhookOnly',   // optional — bỏ qua/null = không đổi
+});
+
+// Để clear về null, dùng cờ riêng (mutually exclusive với việc set giá trị mới):
+await client.bots.update('bot-id', {
+  clearKafkaTopic: true,
+  clearWebhookUrl: true,
 });
 ```
 
@@ -948,17 +1071,22 @@ await client.bots.delete('bot-id');
 ### Kiểu dữ liệu Bot
 
 ```ts
+// Kênh nhận outgoing event. Chỉ có hiệu lực khi bot có cả kafkaTopic lẫn webhookUrl.
+type BotDeliveryPreference = 'Both' | 'WebhookOnly' | 'KafkaOnly';
+
 interface BotDto {
   id: string;
-  participantId: string;      // Dùng để lấy name/avatar từ ParticipantApi
+  participantId: string;            // Dùng để lấy name/avatar từ ParticipantApi
   description?: string | null;
   metadata?: Record<string, unknown> | null;
-  kafkaTopic: string;         // KHÔNG thể thay đổi sau khi tạo
+  kafkaTopic?: string | null;       // null khi bot không cấu hình Kafka
+  webhookUrl?: string | null;       // HTTP/2 NDJSON webhook (chỉ MessageCreatedEvent); null khi không cấu hình
+  deliveryPreference: BotDeliveryPreference; // Chỉ áp dụng khi cả kafkaTopic và webhookUrl đều được cấu hình
   isActive: boolean;
   listenAllGroupMessages: boolean;
-  createdBy: string;          // ID của người tạo bot
-  createdAt: string;          // ISO 8601
-  updatedAt: string;          // ISO 8601
+  createdBy: string;                // ID của người tạo bot
+  createdAt: string;                // ISO 8601
+  updatedAt: string;                // ISO 8601
 }
 ```
 
@@ -968,29 +1096,35 @@ interface BotDto {
 
 ```ts
 interface CreateBotRequest {
-  uniqueName: string;
-  fullName: string;
+  uniqueName: string;                // max 50, [a-zA-Z0-9_]
+  fullName: string;                  // max 100
   avatar?: MediaReference;           // optional — avatar của bot
-  description?: string;
+  description?: string;              // max 500
   metadata?: Record<string, unknown>;
-  kafkaTopic: string;                // KHÔNG thể thay đổi sau khi tạo
+  kafkaTopic?: string | null;        // optional — max 200, [a-zA-Z0-9._-]
+  webhookUrl?: string | null;        // optional — absolute http/https URI, max 2000
+  deliveryPreference?: BotDeliveryPreference; // optional — server default 'Both'
   listenAllGroupMessages?: boolean;  // Mặc định false
 }
 
 interface UpdateBotRequest {
-  uniqueName?: string;               // Có thể cập nhật sau khi tạo
+  uniqueName?: string;
   fullName?: string;
   avatar?: MediaReference;
   description?: string;
   metadata?: Record<string, unknown>;
   listenAllGroupMessages?: boolean;
-  // kafkaTopic KHÔNG thể cập nhật
+  kafkaTopic?: string | null;        // set/đổi topic (mutually exclusive với clearKafkaTopic)
+  clearKafkaTopic?: boolean;         // true → clear topic về null
+  webhookUrl?: string | null;        // set/đổi webhook (mutually exclusive với clearWebhookUrl)
+  clearWebhookUrl?: boolean;         // true → clear webhook về null
+  deliveryPreference?: BotDeliveryPreference | null; // bỏ qua/null = không đổi
 }
 ```
 
 ---
 
-## 10. Proxy — ProxyApi
+## 11. Proxy — ProxyApi
 
 **Truy cập:** `client.proxy`
 
@@ -1047,7 +1181,7 @@ const result = await client.proxy.request<unknown>('myservice', 'api/resource/12
 
 ---
 
-## 11. Health — HealthApi
+## 12. Health — HealthApi
 
 **Truy cập:** `client.health`
 
@@ -1067,7 +1201,7 @@ const ready = await client.health.ready(); // "Healthy"
 
 ---
 
-## 12. Real-time: ChatHubClient
+## 13. Real-time: ChatHubClient
 
 **Truy cập:** `client.realtime.chat`
 
@@ -1205,9 +1339,10 @@ client.realtime.chat.off('messageReceived', handler);
 | `streamStarted` | `StreamStartedDto` | Bot stream bắt đầu |
 | `streamStatusUpdated` | `StreamStatusUpdatedDto` | Trạng thái bot stream thay đổi |
 | `streamChunkReceived` | `StreamChunkReceivedDto` | Nhận thêm chunk text từ bot |
-| `streamChunkBatchReceived` | `StreamChunkBatchReceivedDto` | Phiên bản gộp của `streamChunkReceived` — append theo `parts[i].chunkIndex` tăng dần. Cài cả hai handler vì server có thể gửi bất kỳ event nào |
+| `streamBlockReceived` | `StreamBlockReceivedDto` | Nhận inline content block (widget) đan xen giữa các chunk text, theo `sequence` |
 | `streamCompleted` | `StreamCompletedDto` | Bot stream hoàn thành (kèm message đầy đủ) |
 | `streamAborted` | `StreamAbortedDto` | Bot stream bị hủy |
+| `ephemeralBroadcast` | `EphemeralBroadcastDto` | Broadcast tạm thời (không lưu) nhắm `audience="viewers"` của conversation đang mở — `conversationId` luôn có giá trị |
 | `error` | `HubErrorDto` | Lỗi từ server |
 | `reconnecting` | `Error \| undefined` | Đang reconnect |
 | `reconnected` | `string \| undefined` | Đã reconnect (connectionId mới) |
@@ -1222,7 +1357,7 @@ interface MessageUpdatedDto {
   conversationId: string;
   blocks: Block[];
   plainTextContent: string | null;
-  mentions?: Mention[];
+  mentions?: Mention[] | null;
   updatedAt: string;                    // ISO 8601
   replyToMessageId?: string | null;     // null nếu reply reference đã bị xóa
 }
@@ -1298,25 +1433,33 @@ client.realtime.chat.on('messageThumbnailsReady', (dto) => {
 Khi bot streaming, **không có** `messageReceived` — thay vào đó nhận chuỗi sự kiện sau:
 
 ```
-streamStarted → streamStatusUpdated* → streamChunkReceived* → streamCompleted
-                                                             → streamAborted
+streamStarted → streamStatusUpdated* → [streamChunkReceived | streamBlockReceived]* → streamCompleted
+                                                                                     → streamAborted
 ```
 
+`streamChunkReceived` (text) và `streamBlockReceived` (inline block/widget) dùng **chung** dãy số `sequence` (server gán, tăng dần từ 0). Client sắp xếp theo `sequence` để render đúng vị trí text↔block trong cùng một stream.
+
 ```ts
-const chunks: string[] = [];
+// Mỗi phần tử là một text chunk hoặc một block, gắn với sequence để sắp xếp.
+const parts: { sequence: number; text?: string; block?: Block }[] = [];
 
 client.realtime.chat.on('streamStarted', (dto) => {
   console.log('Bot bắt đầu trả lời, streamId:', dto.streamId);
 });
 
 client.realtime.chat.on('streamChunkReceived', (dto) => {
-  chunks.push(dto.text);
-  // Hiển thị progressive: chunks.join('')
+  parts.push({ sequence: dto.sequence, text: dto.text });
+  // Hiển thị progressive: sắp xếp theo sequence rồi nối lại
+});
+
+client.realtime.chat.on('streamBlockReceived', (dto) => {
+  parts.push({ sequence: dto.sequence, block: dto.block });
+  // Render block (card, choice, divider...) đúng vị trí theo sequence
 });
 
 client.realtime.chat.on('streamCompleted', (dto) => {
   console.log('Tin nhắn hoàn chỉnh:', dto.message);
-  chunks.length = 0; // reset
+  parts.length = 0; // reset
 });
 
 client.realtime.chat.on('streamAborted', (dto) => {
@@ -1324,9 +1467,44 @@ client.realtime.chat.on('streamAborted', (dto) => {
 });
 ```
 
+**Giới hạn streaming (server enforce):**
+
+| Giới hạn | Giá trị |
+|----------|---------|
+| Max chunk size | 4096 bytes |
+| Max chunks / stream | 2000 |
+| Max blocks / stream | 50 |
+| Max block size | 65536 bytes (64 KB) |
+| Max accumulated size | 1 MB |
+| Stream timeout | 120 giây |
+| Max stream duration | 300 giây |
+| Max concurrent streams / bot | 10 |
+
+### Ephemeral Broadcast (tin real-time không lưu trữ)
+
+Bot hoặc SYSTEM user có thể phát **broadcast tạm thời** (không lưu vào lịch sử, không có ack, không edit/delete) qua `POST /api/broadcasts`. Trên ChatHub, client nhận event `ephemeralBroadcast` khi broadcast nhắm `audience="viewers"` của conversation đang mở — khi đó `conversationId` luôn có giá trị.
+
+`data` là một envelope JSON tự do; client diễn giải dựa trên `type`. Dùng generic `EphemeralBroadcastDto<TData>` để narrow kiểu của `data` khi cần (mặc định `unknown` để vẫn an toàn khi chưa khai báo).
+
+```ts
+import type { EphemeralBroadcastDto } from '@manonero/chat-client-sdk';
+
+interface PromoBanner { title: string; startsAt: string }
+
+client.realtime.chat.on('ephemeralBroadcast', (b) => {
+  // b.senderType: 'Bot' | 'System' ; b.conversationId luôn có giá trị trên ChatHub
+  if (b.type === 'promo_banner') {
+    const promo = b.data as PromoBanner; // narrow theo `type`
+    showBanner(promo.title, promo.startsAt);
+  }
+});
+```
+
+> Cùng event `ephemeralBroadcast` (và cùng kiểu `EphemeralBroadcastDto`) cũng có trên NotificationHub cho các audience cấp user — xem [mục 14](#14-real-time-notificationhubclient). Định nghĩa kiểu đầy đủ ở [mục 17](#17-toàn-bộ-kiểu-dữ-liệu-types).
+
 ---
 
-## 13. Real-time: NotificationHubClient
+## 14. Real-time: NotificationHubClient
 
 **Truy cập:** `client.realtime.notifications`
 
@@ -1370,6 +1548,7 @@ await client.realtime.notifications.disconnect();
 | `participantLeft` | `ParticipantLeftDto` | Thành viên rời/bị xóa — gửi cho tất cả participant còn lại **và** chính người vừa rời (để sync xóa khỏi các tab khác) |
 | `conversationPinned` | `ConversationPinnedDto` | Conversation được pin |
 | `conversationUnpinned` | `ConversationUnpinnedDto` | Conversation được unpin |
+| `ephemeralBroadcast` | `EphemeralBroadcastDto` | Broadcast tạm thời (không lưu) — audience `members`/`all`/`users`; broadcast toàn cục có `conversationId: null` |
 | `reconnecting` | `Error \| undefined` | Đang reconnect |
 | `reconnected` | `string \| undefined` | Đã reconnect |
 | `disconnected` | `Error \| undefined` | Mất kết nối |
@@ -1440,9 +1619,24 @@ interface ConversationUnpinnedDto {
 }
 ```
 
+### Ephemeral Broadcast trên NotificationHub
+
+Giống ChatHub, NotificationHub cũng phát event `ephemeralBroadcast` (cùng kiểu `EphemeralBroadcastDto`) — nhưng cho các audience **cấp user**: `audience="members"` (mọi thành viên conversation), `audience="all"` (mọi user online), hoặc `audience="users"` (danh sách userId chỉ định). Với broadcast toàn cục, `conversationId` là `null`.
+
+```ts
+client.realtime.notifications.on('ephemeralBroadcast', (b) => {
+  if (b.conversationId === null && b.type === 'system_alert') {
+    // Broadcast toàn cục — vd. cảnh báo bảo trì hệ thống
+    showGlobalAlert(b.data);
+  }
+});
+```
+
+> Định nghĩa đầy đủ `EphemeralBroadcastDto` ở [mục 17](#17-toàn-bộ-kiểu-dữ-liệu-types).
+
 ---
 
-## 14. ReconnectionManager
+## 15. ReconnectionManager
 
 Class quản lý reconnect thủ công khi cả `withAutomaticReconnect` của SignalR đã thất bại và hub bị `disconnected`. Cung cấp exponential backoff và xử lý token hết hạn.
 
@@ -1470,13 +1664,19 @@ manager.stop();
 
 **Chiến lược backoff:** 3 lần thử với delay 2s → 5s → 10s.
 
+> **Không có event kết thúc:** nếu cả 3 lần thử đều thất bại, manager **dừng im lặng** — không phát thêm event nào. Một `connect()` thất bại không mở được kết nối nên `onclose`/`disconnected` **không** fire lại; host chỉ nhận đúng 1 lần `disconnected` (lần kích hoạt reconnect). Muốn biết reconnect đã bỏ cuộc, hãy tự giám sát qua event `disconnected` kết hợp getter `state` của hub.
+
 **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.
 
+> **⚠️ Giới hạn dưới transport mặc định:** SDK mặc định `skipNegotiation: true` + `transport: WebSockets`. Khi token hết hạn, 401 xảy ra ở bước bắt tay WebSocket — mà trình duyệt **không** expose HTTP status ra cho script, nên `err.message` chỉ là chuỗi chung chung ("WebSocket failed to connect…") không chứa keyword nào ở trên, và `onTokenExpired` **có thể không được gọi**. Không danh sách keyword nào khắc phục được (status đơn giản không nằm trong message). Vì vậy:
+> - Muốn xử lý hết hạn **tất định**, hãy **refresh chủ động** dựa trên `AuthResponse.expiresAt` (đã có sẵn từ lúc login) — đừng trông chờ vào drop-detection.
+> - Heuristic chỉ fire đáng tin khi bạn tự override `skipNegotiation: false` (lúc đó bước negotiate trả HTTP 401 đọc được).
+
 **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.
 
 ---
 
-## 15. Hệ thống Block (nội dung tin nhắn)
+## 16. Hệ thống Block (nội dung tin nhắn)
 
 `Block` là **discriminated union** — mỗi block phân biệt bằng field `$type`.
 
@@ -1518,6 +1718,7 @@ interface ImageBlock {
   height: number | null;
   caption: string | null;
   fileSizeBytes: number | null;
+  mimeType: string | null;     // vd. 'image/jpeg', 'image/png', 'image/svg+xml'
 }
 
 interface VideoBlock {
@@ -1635,6 +1836,32 @@ for (const block of message.blocks) {
 
 Danh sách đầy đủ: `isTextBlock`, `isImageBlock`, `isVideoBlock`, `isAudioBlock`, `isFileBlock`, `isLinkPreviewBlock`, `isEmbedBlock`, `isLocationBlock`, `isContactBlock`, `isChoiceBlock`, `isCardBlock`, `isCarouselBlock`, `isDividerBlock`, `isCustomBlock`.
 
+### Serialization helpers — `withTypeFirst` / `normalizeBlocksForSend`
+
+Server dùng polymorphic deserializer yêu cầu **`$type` phải là property đầu tiên** trong mỗi block JSON (spec §13). SDK đã tự gọi `normalizeBlocksForSend()` nội bộ trong `MessageApi.send/edit` và `ChatHubClient.sendMessage/editMessage`, nên **bạn KHÔNG cần gọi thủ công** trong luồng thông thường.
+
+Hai helper này được export public chỉ dành cho power users muốn:
+- Tự xây dựng API module riêng dùng `HttpClient` trực tiếp.
+- Tạo block từ nguồn dữ liệu mà thứ tự property bị xáo trộn (vd. clone qua `structuredClone` rồi spread).
+
+```ts
+import { withTypeFirst, normalizeBlocksForSend } from '@manonero/chat-client-sdk';
+import type { Block, TextBlock } from '@manonero/chat-client-sdk';
+
+// withTypeFirst<T>(block: T): T — chuẩn hoá 1 block đơn lẻ
+const normalized: TextBlock = withTypeFirst({
+  content: 'Xin chào',
+  format: 'Plain',
+  plainText: 'Xin chào',
+  $type: 'text',          // có thể nằm ở cuối khi tạo block — sẽ được đưa lên đầu
+});
+
+// normalizeBlocksForSend<T extends Block>(blocks: T[]): T[] — áp dụng cho mảng
+const blocks: Block[] = normalizeBlocksForSend(rawBlocks);
+```
+
+> `CarouselBlock` là block duy nhất chứa nested blocks (`cards: CardBlock[]`); `withTypeFirst` đệ quy nên rule `$type` đứng đầu giữ vững ở mọi cấp.
+
 ### Ví dụ tạo block
 
 ```ts
@@ -1656,6 +1883,7 @@ const imageBlock: ImageBlock = {
   height: 1080,
   caption: 'Ảnh mô tả',
   fileSizeBytes: 204800,
+  mimeType: 'image/jpeg',
 };
 
 // Gửi tin nhắn kèm file
@@ -1696,7 +1924,7 @@ interface CardField {
 }
 ```
 
-### ChoiceMode / ChoiceOption / ChoiceBlock
+### ChoiceMode / ChoiceOption
 
 ```ts
 type ChoiceMode = 'Single' | 'Multiple';
@@ -1706,16 +1934,10 @@ interface ChoiceOption {
   value: string;
   selected: boolean;
 }
-
-interface ChoiceBlock {
-  $type: 'choice';
-  prompt: string;          // Câu hỏi hiển thị cho user
-  options: ChoiceOption[];
-  mode: ChoiceMode;
-  submitted: boolean;      // true sau khi user đã submit lựa chọn
-}
 ```
 
+> `ChoiceBlock` đã được định nghĩa đầy đủ ở mục [Interfaces tham chiếu đầy đủ](#interfaces-tham-chiếu-đầy-đủ).
+
 ### QuickReply
 
 Nút bấm nhanh hiển thị bên dưới tin nhắn bot:
@@ -1743,7 +1965,7 @@ interface Mention {
 
 ---
 
-## 16. Toàn bộ kiểu dữ liệu (Types)
+## 17. Toàn bộ kiểu dữ liệu (Types)
 
 ### CursorPaginatedResult (cursor-based)
 
@@ -1766,12 +1988,39 @@ interface PagedResult<T> {
 }
 ```
 
+### SearchResult (GET /api/search — §8)
+
+```ts
+type SearchType = 'MESSAGE' | 'CONVERSATION' | 'BOTH';
+
+interface SearchResult {
+  // null khi type=MESSAGE. Mỗi item có `lastMessage` đã hydrate —
+  // kiểm tra lastMessage.isDeleted trước khi hiển thị.
+  conversations: ConversationListItemDto[] | null;
+  // null khi type=CONVERSATION.
+  messages: SearchMessagesResult | null;
+}
+
+interface SearchMessagesResult {
+  groups: SearchMessageGroup[];
+  nextCursor: string | null; // opaque — chỉ phân trang cho messages
+  hasMore: boolean;
+}
+
+interface SearchMessageGroup {
+  // null nếu batch fetch conversation lỗi (degrade graceful).
+  // `participants` luôn là [] (fetch với includeParticipants=false).
+  conversation: ConversationDto | null;
+  messages: MessageDto[];
+}
+```
+
 ### MediaReference
 
 ```ts
 interface MediaReference {
-  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)
+  storageKey?: string | null; // Key lưu trữ nội bộ — dùng FileApi.getDownloadUrl(storageKey, { expires, sig }) để tạo URL tuyệt đối có chữ ký. `null` khi reference là external URL.
+  url?: string | null;        // URL do server cấp sẵn (xem chi tiết bên dưới). `null` ở request body khi chỉ gửi storageKey.
 }
 ```
 
@@ -1782,22 +2031,20 @@ Trường `url` có hai dạng tuỳ cấu hình server:
 | **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).
+> **Quy tắc resolve:** Luôn ưu tiên `url` — nó đã được server gắn signature (`expires` + `sig`). Nếu chỉ có `storageKey` mà không có `url`, bạn cần cặp `expires`/`sig` từ nguồn khác để gọi `getDownloadUrl(storageKey, { expires, sig })` (server bắt buộc signed access — gọi unsigned sẽ bị từ chối với `400 Invalid Signature`).
 
 ```ts
-// Helper chuẩn để resolve MediaReference → URL tuyệt đối
+// Helper chuẩn để resolve MediaReference → URL tuyệt đối.
+// Server gần như luôn trả sẵn `url` cho mọi MediaReference của tin nhắn/participant,
+// nên trường hợp chỉ có storageKey là bất thường và nên log để debug.
 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;
+  if (!ref?.url) return null;
+  // 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;
 }
 ```
 
@@ -1902,23 +2149,15 @@ interface StreamChunkReceivedDto {
   messageId: string;
   conversationId: string;
   text: string;              // Chunk text để append vào placeholder
-  chunkIndex: number;        // Zero-based index
+  sequence: number;          // Số thứ tự server gán (zero-based), chung dãy với StreamBlockReceivedDto
 }
 
-// Phiên bản gộp của StreamChunkReceived — server gom các chunk phát ra trong
-// cùng cửa sổ Streaming:ChunkCoalesceWindowMs (mặc định 50ms) thành 1 batch.
-// Client cài cả hai handler vì server có thể gửi bất kỳ event nào.
-// Append theo thứ tự parts[i].chunkIndex tăng dần.
-interface StreamChunkPart {
-  text: string;
-  chunkIndex: number;
-}
-
-interface StreamChunkBatchReceivedDto {
+interface StreamBlockReceivedDto {
   streamId: string;
   messageId: string;
   conversationId: string;
-  parts: StreamChunkPart[];
+  block: Block;              // Inline content block (card, choice, divider...)
+  sequence: number;          // Số thứ tự server gán, chung dãy với StreamChunkReceivedDto
 }
 
 interface StreamCompletedDto {
@@ -1939,6 +2178,29 @@ interface StreamAbortedDto {
 }
 ```
 
+### EphemeralBroadcastDto (dùng chung — ChatHub & NotificationHub)
+
+Broadcast tạm thời (**KHÔNG lưu trữ**) do bot hoặc SYSTEM user phát qua `POST /api/broadcasts`. Cùng một payload xuất hiện trên **cả hai hub** với event `ephemeralBroadcast`:
+
+- **ChatHub** — `audience="viewers"` của conversation đang mở (`conversationId` có giá trị).
+- **NotificationHub** — `audience="members" | "all" | "users"` (broadcast toàn cục → `conversationId: null`).
+
+```ts
+// Sender của broadcast — luôn là bot hoặc SYSTEM user (không bao giờ là User thường)
+type BroadcastSenderType = 'Bot' | 'System';
+
+interface EphemeralBroadcastDto<TData = unknown> {
+  type: string;                     // Khóa do người gửi đặt — client tự diễn giải `data` theo giá trị này
+  senderId: string;                 // participantId của bot, hoặc literal "SYSTEM"
+  senderType: BroadcastSenderType;  // 'Bot' | 'System'
+  conversationId: string | null;    // null khi broadcast toàn cục
+  data: TData | null;               // Envelope JSON tự do; null khi người gửi bỏ trống
+  sentAt: string;                   // UTC ISO 8601
+}
+```
+
+> `TData` cho phép narrow kiểu của `data` theo `type` (mặc định `unknown` để dùng an toàn khi chưa khai báo). Xem ví dụ ở [mục 13](#13-real-time-chathubclient) (ChatHub) và [mục 14](#14-real-time-notificationhubclient) (NotificationHub).
+
 ### Ack types (return value của Hub methods)
 
 Mỗi Hub method client→server trả về một ack object với `success: boolean` và optional error fields:
@@ -1987,7 +2249,7 @@ interface ReactionAck {
 
 ---
 
-## 17. Xử lý lỗi — ChatApiError
+## 18. Xử lý lỗi — ChatApiError
 
 Tất cả lỗi HTTP đều throw `ChatApiError` (kế thừa `Error`).
 
@@ -2034,7 +2296,7 @@ try {
 |------------|------|-------|
 | `status` | `number` | HTTP status code |
 | `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`) |
+| `detail` | `string \| undefined` | Mô tả chi tiết, human-readable của lỗi (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ộ |
@@ -2110,6 +2372,8 @@ const chatHub = new ChatHubClient({
   hubUrl: 'https://chat-api.example.com/hubs/chat',
   tokenProvider,
   logLevel: LogLevel.Warning, // optional
+  // optional — ghi đè mặc định skipNegotiation: true + transport: WebSockets
+  connectionOptions: { skipNegotiation: false },
 });
 
 // Khởi tạo NotificationHub độc lập
@@ -2139,7 +2403,7 @@ manager.start();
 
 ---
 
-## 18. TypedEventEmitter
+## 19. TypedEventEmitter
 
 SDK dùng `TypedEventEmitter<TEventMap>` nội bộ cho cả hai hub. Giao diện public của nó được expose qua `.on()` và `.off()`.
 
@@ -2169,7 +2433,7 @@ unsubs.forEach(fn => fn());
 
 ---
 
-## 19. Lưu ý quan trọng
+## 20. Lưu ý quan trọng
 
 ### Cursor pagination — KHÔNG cast sang number
 
@@ -2212,34 +2476,25 @@ const block: ImageBlock = {
 };
 ```
 
-**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:
+**Khi hiển thị tin nhắn nhận từ server:** server trả về `MediaReference` có sẵn `url` đã được ký (`expires` + `sig`). 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;
+  if (!ref?.url) return null;
+  // 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;
 }
 
 // Ví dụ dùng với ImageBlock:
-const displayUrl = resolveMediaRef(
-  block.source,
-  'https://chat-api.example.com',
-  client.files.getDownloadUrl.bind(client.files),
-);
+const displayUrl = resolveMediaRef(block.source, 'https://chat-api.example.com');
 ```
 
-> **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 `getDownloadUrl(storageKey, ...)`?** Server bắt buộc signed access (spec §8.3), và `getDownloadUrl()` yêu cầu bạn cung cấp cặp `expires`/`sig`. Trong khi đó, `MediaReference.url` đã được server gắn sẵn signature — không cần thao tác thêm.
 
 > **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.
 
@@ -2255,7 +2510,7 @@ console.log(participant.fullName); // Tên hiển thị của bot
 
 ---
 
-## 20. Ví dụ đầy đủ
+## 21. Ví dụ đầy đủ
 
 ### Ví dụ 1: Chat app cơ bản
 
@@ -2367,7 +2622,9 @@ async function loadMoreMessages(conversationId: string) {
 ### Ví dụ 3: Xử lý bot streaming
 
 ```ts
-const streamBuffers = new Map<string, string[]>();
+// Mỗi part là text hoặc block, gắn sequence (server gán) để sắp xếp đúng vị trí.
+type StreamPart = { sequence: number; text?: string; block?: Block };
+const streamBuffers = new Map<string, StreamPart[]>();
 
 client.realtime.chat.on('streamStarted', (dto) => {
   streamBuffers.set(dto.streamId, []);
@@ -2378,24 +2635,21 @@ client.realtime.chat.on('streamStatusUpdated', (dto) => {
   updateStreamStatus(dto.messageId, dto.status); // e.g. "thinking", "searching"
 });
 
-// Append một chunk vào buffer rồi flush ra UI
-function appendChunk(streamId: string, messageId: string, text: string) {
-  const chunks = streamBuffers.get(streamId) ?? [];
-  chunks.push(text);
-  streamBuffers.set(streamId, chunks);
-  updateStreamingText(messageId, chunks.join(''));
+// Append một part (text hoặc block) vào buffer, sắp theo sequence rồi flush ra UI
+function appendPart(streamId: string, messageId: string, part: StreamPart) {
+  const parts = streamBuffers.get(streamId) ?? [];
+  parts.push(part);
+  parts.sort((a, b) => a.sequence - b.sequence);
+  streamBuffers.set(streamId, parts);
+  renderStreamingParts(messageId, parts); // render text + block đúng thứ tự
 }
 
 client.realtime.chat.on('streamChunkReceived', (dto) => {
-  appendChunk(dto.streamId, dto.messageId, dto.text);
+  appendPart(dto.streamId, dto.messageId, { sequence: dto.sequence, text: dto.text });
 });
 
-// Bắt buộc cài cả handler batch — server có thể gửi chunk gộp khi bật coalescing
-// (default 50ms). Append theo thứ tự parts[i].chunkIndex tăng dần.
-client.realtime.chat.on('streamChunkBatchReceived', (dto) => {
-  for (const part of dto.parts) {
-    appendChunk(dto.streamId, dto.messageId, part.text);
-  }
+client.realtime.chat.on('streamBlockReceived', (dto) => {
+  appendPart(dto.streamId, dto.messageId, { sequence: dto.sequence, block: dto.block });
 });
 
 client.realtime.chat.on('streamCompleted', (dto) => {