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

package/README.md

@@ -0,0 +1,2453 @@
+# ChatClientSdk — Tài liệu hướng dẫn sử dụng
+
+> SDK TypeScript để tích hợp với Chat Gateway API. Bao gồm toàn bộ HTTP REST API và kết nối real-time qua SignalR.
+
+---
+
+## Mục lục
+
+1. [Tổng quan kiến trúc](#1-tổng-quan-kiến-trúc)
+2. [Cài đặt và khởi tạo](#2-cài-đặt-và-khởi-tạo)
+3. [ChatClient — Facade chính](#3-chatclient--facade-chính)
+4. [Xác thực — AuthApi](#4-xác-thực--authapi)
+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-đủ)
+
+---
+
+## 1. Tổng quan kiến trúc
+
+```
+ChatClient (facade chính)
+├── auth          → AuthApi          (xác thực)
+├── 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)
+├── files         → FileApi          (upload/download file)
+├── bots          → BotApi           (quản lý bot)
+├── proxy         → ProxyApi         (proxy đến backend khác)
+├── health        → HealthApi        (kiểm tra sức khỏe server)
+└── realtime
+    ├── chat          → ChatHubClient          (sự kiện tin nhắn real-time)
+    └── notifications → NotificationHubClient  (thông báo real-time)
+```
+
+**Luồng hoạt động cơ bản:**
+
+1. Khởi tạo `ChatClient` với `baseUrl`.
+2. Đăng nhập qua `client.auth.loginWith*()` — token được tự động lưu và truyền vào mọi request sau.
+3. Kết nối các hub SignalR qua `client.realtime.notifications.connect()` và `client.realtime.chat.connect()`.
+4. Lắng nghe sự kiện real-time bằng `.on(eventName, handler)`.
+5. Gọi các phương thức REST hoặc Hub để thực hiện thao tác.
+
+---
+
+## 2. Cài đặt và khởi tạo
+
+### Installation
+
+```bash
+npm install @manonero/chat-client-sdk
+npm install @microsoft/signalr   # peer dependency
+```
+
+### Import
+
+```ts
+import { ChatClient } from '@manonero/chat-client-sdk';
+```
+
+Tất cả các kiểu dữ liệu đều được export từ package root:
+
+```ts
+import type { MessageDto, ConversationDto, Block } from '@manonero/chat-client-sdk';
+import { ChatApiError } from '@manonero/chat-client-sdk'; // class — dùng import (không phải import type) để hỗ trợ instanceof
+```
+
+**Export nâng cao** — SDK cũng export một số class và type nội bộ cho power users:
+
+```ts
+// TypedEventEmitter — dùng độc lập hoặc extend
+import { TypedEventEmitter } from '@manonero/chat-client-sdk';
+import type { Unsubscribe } from '@manonero/chat-client-sdk';
+
+// HttpClient — tự xây dựng API module bổ sung theo cùng pattern
+import { HttpClient } from '@manonero/chat-client-sdk';
+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';
+
+// Hub options (khi dùng hub client độc lập, không qua ChatClient)
+import type { ChatHubClientOptions, NotificationHubClientOptions } from '@manonero/chat-client-sdk';
+
+// Hub request types (Client → Server) — dùng khi gọi SignalR methods
+import type {
+  ChatSendMessageRequest,
+  ChatEditMessageRequest,
+  ChatDeleteMessageRequest,
+  ChatRecoverMessageRequest,
+  ChatAddReactionRequest,
+  ChatRemoveReactionRequest,
+} from '@manonero/chat-client-sdk';
+
+// Ack types (Server → Client return) — dùng khi cần type return value của Hub methods
+import type {
+  SendMessageAck,
+  EditMessageAck,
+  DeleteMessageAck,
+  RecoverMessageAck,
+  ReactionAck,
+  HubErrorDto,
+} from '@manonero/chat-client-sdk';
+
+// ReconnectionManager options
+import type { ReconnectionManagerOptions } from '@manonero/chat-client-sdk';
+
+// ChatClient facade types
+import type { ChatClientSignalrOptions, ChatClientRealtime } from '@manonero/chat-client-sdk';
+
+// Upload progress callback type — dùng khi cần type hàm onProgress
+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, ProblemError } from '@manonero/chat-client-sdk';
+
+// Login request types riêng lẻ (khi cần type-check từng provider)
+import type {
+  GoogleLoginRequest,
+  DsAccountLoginRequest,
+  DevLoginRequest,
+  LoginRequest,
+} from '@manonero/chat-client-sdk';
+
+// Standalone hub clients — dùng khi không cần ChatClient facade
+import { ChatHubClient, NotificationHubClient, ReconnectionManager } from '@manonero/chat-client-sdk';
+```
+
+### Khởi tạo cơ bản
+
+```ts
+const client = new ChatClient({
+  baseUrl: 'https://chat-api.example.com',
+});
+```
+
+### Khởi tạo với token có sẵn (đã đăng nhập từ trước)
+
+```ts
+const client = new ChatClient({
+  baseUrl: 'https://chat-api.example.com',
+  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+});
+```
+
+### Khởi tạo với external token provider
+
+Dùng khi token được quản lý bên ngoài SDK (ví dụ: Redux store):
+
+```ts
+const client = new ChatClient({
+  baseUrl: 'https://chat-api.example.com',
+  tokenProvider: () => store.getState().auth.token,
+});
+```
+
+> **Ư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
+
+```ts
+import { LogLevel } from '@microsoft/signalr';
+
+const client = new ChatClient({
+  baseUrl: 'https://chat-api.example.com',
+  signalrOptions: {
+    logLevel: LogLevel.Debug, // Mặc định: LogLevel.Warning
+  },
+});
+```
+
+---
+
+## 3. ChatClient — Facade chính
+
+**Class:** `ChatClient`
+
+Đây là điểm vào duy nhất của SDK. Quản lý token JWT dùng chung cho tất cả HTTP request và kết nối SignalR.
+
+### Constructor
+
+```ts
+new ChatClient(options: ChatClientOptions)
+```
+
+| Option | Kiểu | Bắt buộc | Mô tả |
+|--------|------|----------|-------|
+| `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
+
+| Thuộc tính | Kiểu | Mô tả |
+|------------|------|-------|
+| `auth` | `AuthApi` | Các endpoint xác thực |
+| `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 |
+| `files` | `FileApi` | Upload/download file |
+| `bots` | `BotApi` | Quản lý bot |
+| `proxy` | `ProxyApi` | Proxy đến backend khác |
+| `health` | `HealthApi` | Kiểm tra sức khỏe server |
+| `realtime.chat` | `ChatHubClient` | SignalR ChatHub |
+| `realtime.notifications` | `NotificationHubClient` | SignalR NotificationHub |
+| `currentUser` | `AuthUserInfo \| null` | User hiện tại sau khi đăng nhập |
+
+### Phương thức
+
+#### `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á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`. 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.
+
+```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();
+```
+
+---
+
+## 4. Xác thực — AuthApi
+
+**Truy cập:** `client.auth`
+
+Các endpoint xác thực **không yêu cầu JWT**. Sau khi đăng nhập thành công, SDK tự động lưu token và cập nhật `client.currentUser`.
+
+### `loginWithGoogle(idToken: string): Promise<AuthResponse>`
+
+Đăng nhập bằng Google ID Token.
+
+```ts
+const { token, user } = await client.auth.loginWithGoogle(googleIdToken);
+console.log(client.currentUser); // AuthUserInfo đã được set tự động
+```
+
+### `loginWithDsAccount(token: string): Promise<AuthResponse>`
+
+Đăng nhập bằng DS Account token.
+
+```ts
+const auth = await client.auth.loginWithDsAccount(dsToken);
+```
+
+### `loginWithDev(username: string, password: string): Promise<AuthResponse>`
+
+Đăng nhập tài khoản dev. Chỉ dùng trong môi trường phát triển. JWT được cấp có claim `role=dev`, cho phép truy cập các endpoint quản lý bot.
+
+```ts
+const auth = await client.auth.loginWithDev('devuser', 'devpass');
+```
+
+### `login(provider: string, body: LoginRequest): Promise<AuthResponse>`
+
+Đăng nhập với provider tùy chỉnh (khi provider được xác định lúc runtime).
+
+```ts
+const auth = await client.auth.login('custom-provider', { token: '...' });
+```
+
+### `AuthResponse`
+
+```ts
+interface AuthResponse {
+  token: string;    // JWT token
+  expiresAt: string; // ISO 8601 — thời điểm hết hạn
+  user: AuthUserInfo;
+}
+
+interface AuthUserInfo {
+  id: string;
+  uniqueName: string;
+  fullName: string;
+  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
+}
+```
+
+---
+
+## 5. Participant — ParticipantApi
+
+**Truy cập:** `client.participants`
+
+Tất cả endpoint đều **yêu cầu JWT**. Server cache GET trong 5 phút.
+
+### `createOrUpdate(request): Promise<ParticipantDto>`
+
+Tạo mới hoặc cập nhật participant (upsert theo ID).
+
+```ts
+const participant = await client.participants.createOrUpdate({
+  id: 'user-123',
+  uniqueName: 'john_doe',
+  fullName: 'John Doe',
+  avatar: { url: 'https://example.com/avatar.jpg' },
+  gender: 'Male',
+});
+```
+
+### `getById(id: string): Promise<ParticipantDto>`
+
+```ts
+const participant = await client.participants.getById('user-123');
+```
+
+### `getByUniqueName(uniqueName: string): Promise<ParticipantDto>`
+
+```ts
+const participant = await client.participants.getByUniqueName('john_doe');
+```
+
+### `getBatch(ids: string[]): Promise<ParticipantDto[]>`
+
+Lấy nhiều participant trong một request. ID không tìm thấy sẽ bị bỏ qua (không báo lỗi).
+
+```ts
+const participants = await client.participants.getBatch(['id-1', 'id-2', 'id-3']);
+```
+
+### `ParticipantDto`
+
+```ts
+interface ParticipantDto {
+  id: string;
+  uniqueName: string;
+  fullName: string;
+  avatar?: MediaReference | null; // hỗ trợ cả internal storageKey lẫn external URL; server có thể trả null
+  gender?: string | null;
+  isBot: boolean;
+  createdAt: string;           // ISO 8601
+  updatedAt: string;           // ISO 8601
+}
+```
+
+---
+
+## 6. Conversation — ConversationApi
+
+**Truy cập:** `client.conversations`
+
+Tất cả endpoint đều **yêu cầu JWT**.
+
+### `list(params?): Promise<CursorPaginatedResult<ConversationListItemDto>>`
+
+Lấy danh sách cuộc hội thoại với cursor-based pagination. Sắp xếp: pinned trước, sau đó theo `lastMessageAt` giảm dần.
+
+```ts
+// Trang đầu
+const result = await client.conversations.list({ limit: 20 });
+console.log(result.items);      // ConversationListItemDto[]
+console.log(result.hasMore);    // boolean
+console.log(result.nextCursor); // string | null
+
+// Trang tiếp theo
+if (result.hasMore) {
+  const nextPage = await client.conversations.list({
+    limit: 20,
+    cursor: result.nextCursor!, // Đây là string — KHÔNG cast sang number
+  });
+}
+```
+
+> ⚠️ `cursor` là chuỗi opaque dạng `"<UnixMs>_<ULID>"` (ví dụ: `"1743004200000_01JRZABC1234567890ABCDEF"`). Luôn truyền nguyên dạng string — **KHÔNG được ép kiểu sang number**.
+
+### `create(request): Promise<ConversationDto>`
+
+> Hệ thống chỉ hỗ trợ duy nhất loại **Group** (spec §6.2) — không có direct 1-1 hay self chat. Một cuộc trò chuyện với 1 user + 1 bot vẫn là Group 2 thành viên.
+
+```ts
+const conv = await client.conversations.create({
+  name: 'Team Chat',
+  avatar: { storageKey: '01HXABCDEF/group-avatar.jpg' }, // optional
+  participantIds: ['user-1', 'user-2', 'user-3'],
+});
+```
+
+### `search(query, limit?): Promise<ConversationListItemDto[]>`
+
+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>`
+
+```ts
+const conv = await client.conversations.getById('conv-id-here');
+```
+
+### `update(id, request): Promise<ConversationDto>`
+
+```ts
+const updated = await client.conversations.update('conv-id', {
+  name: 'New Group Name',
+  avatar: { url: 'https://example.com/group-avatar.jpg' },
+});
+```
+
+### `delete(id: string): Promise<void>` / `leave(id: string): Promise<void>`
+
+Hai method là alias hoàn toàn của nhau (spec §6.6 và §6.7 — `DELETE /api/conversations/{id}` ≡ `POST /api/conversations/{id}/leave`). Caller rời cuộc hội thoại; các thành viên khác vẫn còn lại.
+
+```ts
+await client.conversations.delete('conv-id');
+// hoặc
+await client.conversations.leave('conv-id');
+```
+
+### `addParticipant(conversationId, request): Promise<void>`
+
+```ts
+await client.conversations.addParticipant('conv-id', {
+  participantId: 'new-user-id',
+});
+```
+
+### `removeParticipant(conversationId, participantId): Promise<void>`
+
+```ts
+await client.conversations.removeParticipant('conv-id', 'user-to-remove-id');
+```
+
+### `getParticipants(conversationId): Promise<ConversationParticipantDto[]>`
+
+Trả về tất cả participant kể cả người đã rời nhóm.
+
+```ts
+const members = await client.conversations.getParticipants('conv-id');
+const active = members.filter(m => m.isActive);
+```
+
+### `pin(id) / unpin(id): Promise<void>`
+
+```ts
+await client.conversations.pin('conv-id');
+await client.conversations.unpin('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
+interface ConversationDto {
+  id: string;
+  name: string;
+  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
+  createdAt: string;              // ISO 8601
+  updatedAt: string;              // ISO 8601
+  participants: ConversationParticipantDto[];
+}
+
+interface ConversationParticipantDto {
+  participantId: string;
+  joinedAt: string;          // ISO 8601
+  leftAt?: string | null;    // ISO 8601, null nếu vẫn trong nhóm
+  isActive: boolean;
+  isPinned: boolean;
+  pinnedAt?: string | null;  // ISO 8601
+}
+
+interface ConversationListItemDto {
+  id: string;
+  name?: string | null;
+  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
+  isPinned: boolean;
+  pinnedAt?: string | null;        // ISO 8601, null khi chưa pin
+  participantCount: number;
+}
+```
+
+```ts
+// 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;
+}
+```
+
+---
+
+## 7. Message — MessageApi
+
+**Truy cập:** `client.messages`
+
+Tất cả endpoint đều **yêu cầu JWT**.
+
+### `send(conversationId, request): Promise<MessageDto>`
+
+Gửi tin nhắn qua REST API. Trả về 201 Created với `MessageDto` đầy đủ.
+
+```ts
+const msg = await client.messages.send('conv-id', {
+  blocks: [
+    { $type: 'text', format: 'Plain', content: 'Xin chào!', plainText: 'Xin chào!' }
+  ],
+  replyToMessageId: 'msg-id-to-reply', // optional
+  clientMessageId: 'local-uuid-1234',  // optional, dùng cho optimistic rendering
+});
+```
+
+> 💡 **REST vs SignalR:** Có thể gửi tin nhắn qua cả REST (`client.messages.send`) lẫn SignalR (`client.realtime.chat.sendMessage`). SignalR trả về ack ngay lập tức và nhanh hơn trong môi trường real-time.
+
+### `getHistory(conversationId, params?): Promise<CursorPaginatedResult<MessageDto>>`
+
+Lấy lịch sử tin nhắn với cursor-based pagination.
+
+```ts
+// Lấy 30 tin nhắn mới nhất
+const result = await client.messages.getHistory('conv-id', { limit: 30 });
+
+// Load thêm tin nhắn cũ hơn (scroll lên)
+const older = await client.messages.getHistory('conv-id', {
+  limit: 30,
+  cursor: result.nextCursor!,
+  direction: 'older', // mặc định
+});
+
+// Load tin nhắn mới hơn cursor (scroll xuống)
+const newer = await client.messages.getHistory('conv-id', {
+  cursor: someCursor,
+  direction: 'newer',
+});
+```
+
+### `search(conversationId, query, limit?): Promise<MessageDto[]>`
+
+Full-text search trong cuộc hội thoại.
+
+```ts
+const results = await client.messages.search('conv-id', 'từ khóa tìm kiếm', 20);
+```
+
+### `getById(messageId): Promise<MessageDto>`
+
+```ts
+const msg = await client.messages.getById('msg-id');
+```
+
+### `edit(messageId, request): Promise<MessageDto>`
+
+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
+  replyToMessageId: null,   // optional — null để xóa reply reference
+});
+```
+
+> ⚠️ **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 }>`
+
+Xóa mềm (soft delete). Trả về object (không phải 204).
+
+```ts
+const { messageId, deletedAt } = await client.messages.delete('msg-id');
+```
+
+### `recover(messageId): Promise<void>`
+
+Khôi phục tin nhắn đã xóa. Chỉ khả dụng trong vòng **10 phút** sau khi xóa.
+
+```ts
+await client.messages.recover('msg-id');
+```
+
+### `addReaction(messageId, emoji) / removeReaction(messageId, emoji): Promise<void>`
+
+```ts
+await client.messages.addReaction('msg-id', '👍');
+await client.messages.removeReaction('msg-id', '👍');
+```
+
+> Server trả về 409 Conflict nếu đã react với emoji đó. Emoji được tự động URL-encode.
+
+### Kiểu dữ liệu Message
+
+```ts
+type SenderType = 'User' | 'Bot' | 'System';
+
+interface MessageDto {
+  id: string;               // ULID do server tạo
+  conversationId: string;
+  senderId: string;
+  senderType: SenderType;
+  blocks: Block[];          // Nội dung tin nhắn
+  plainTextIndex: string | null;
+  replyToMessageId: string | null;
+  quickReplies: QuickReply[] | null;
+  isEdited: boolean;
+  editedAt: string | null;  // ISO 8601
+  isDeleted: boolean;
+  deletedAt: string | null; // ISO 8601
+  reactionSummary: ReactionSummary | null;
+  mentions: Mention[] | null;
+  createdAt: string;        // ISO 8601
+  updatedAt: string;        // ISO 8601
+  clientMessageId: string | null;
+  systemEvent: SystemEventInfo | null;
+}
+```
+
+### Kiểu dữ liệu bổ sung
+
+```ts
+// Reaction summary (REST API)
+interface ReactionSummary {
+  groups: ReactionGroup[];
+  totalCount: number;
+}
+
+interface ReactionGroup {
+  emoji: string;
+  count: number;
+  participantIds: string[]; // Danh sách participant đã react
+}
+
+// Request để gửi tin nhắn mới
+interface SendMessageRequest {
+  blocks: Block[];
+  replyToMessageId?: string;
+  quickReplies?: QuickReply[];  // Nút bấm nhanh đính kèm tin nhắn
+  mentions?: Mention[];
+  clientMessageId?: string;     // Tối đa 128 ký tự
+}
+
+// Request để chỉnh sửa tin nhắn qua REST
+interface EditMessageRequest {
+  blocks: Block[];
+  mentions?: Mention[];
+  replyToMessageId?: string | null; // null để xóa reply reference
+}
+```
+
+---
+
+## 8. File — FileApi
+
+**Truy cập:** `client.files`
+
+Upload yêu cầu JWT. Download là **public** (không cần JWT).
+
+### `uploadFile(file, onProgress?): Promise<UploadResponse>`
+
+Phương thức tiện lợi — gộp `createUploadUrl` + `upload` thành một bước.
+
+```ts
+const fileInput = document.getElementById('file') as HTMLInputElement;
+const file = fileInput.files![0];
+
+const result = await client.files.uploadFile(file, (loaded, total) => {
+  const percent = Math.round((loaded / total) * 100);
+  console.log(`Upload: ${percent}%`);
+});
+
+console.log(result.storageKey);   // Dùng làm MediaReference.storageKey
+console.log(result.downloadUrl);  // Relative URL
+```
+
+### `createUploadUrl(request): Promise<CreateUploadUrlResponse>`
+
+Bước 1 của 2 bước upload thủ công — xin URL upload.
+
+```ts
+const { uploadUrl, storageKey, expiresAt } = await client.files.createUploadUrl({
+  fileName: 'photo.jpg',
+  contentType: 'image/jpeg',
+  fileSize: file.size, // bytes, tối đa 50MB
+});
+```
+
+### `upload(uploadUrl, file, onProgress?): Promise<UploadResponse>`
+
+Bước 2 — upload file vào URL đã xin.
+
+```ts
+const result = await client.files.upload(uploadUrl, file, (loaded, total) => {
+  console.log(`${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)
+
+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. 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');
+```
+
+### Kiểu dữ liệu File
+
+```ts
+interface CreateUploadUrlRequest {
+  fileName: string;
+  contentType: string;
+  fileSize: number; // bytes
+}
+
+interface CreateUploadUrlResponse {
+  uploadUrl: string;   // Relative path — HttpClient tự prepend baseUrl
+  storageKey: string;
+  expiresAt: string;   // ISO 8601
+}
+
+interface UploadResponse {
+  downloadUrl: string; // Relative path
+  storageKey: string;
+  fileName: string;
+  contentType: string;
+  fileSize: number;
+  uploadedAt: string;  // ISO 8601
+}
+```
+
+---
+
+## 9. Bot — BotApi
+
+**Truy cập:** `client.bots`
+
+GET (`list`, `getById`) là **public**. Các thao tác quản lý yêu cầu JWT với `role=dev` (đăng nhập qua `loginWithDev`). User không có quyền nhận `404 Not Found`.
+
+### `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.
+
+```ts
+const result = await client.bots.list({ page: 1, pageSize: 20 });
+console.log(result.items);      // BotDto[]
+console.log(result.totalCount); // Tổng số bot
+```
+
+### `getById(id): Promise<BotDto>`
+
+```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>`
+
+Đăng ký bot mới.
+
+```ts
+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
+  listenAllGroupMessages: false,
+});
+```
+
+### `update(id, request): Promise<BotDto>`
+
+```ts
+await client.bots.update('bot-id', {
+  fullName: 'Updated Bot Name',
+  // kafkaTopic KHÔNG thể cập nhật
+});
+```
+
+### `activate(id) / deactivate(id): Promise<void>`
+
+```ts
+await client.bots.activate('bot-id');
+await client.bots.deactivate('bot-id');
+```
+
+### `delete(id): Promise<void>`
+
+Soft delete.
+
+```ts
+await client.bots.delete('bot-id');
+```
+
+### Kiểu dữ liệu Bot
+
+```ts
+interface BotDto {
+  id: string;
+  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
+  isActive: boolean;
+  listenAllGroupMessages: boolean;
+  createdBy: string;          // ID của người tạo bot
+  createdAt: string;          // ISO 8601
+  updatedAt: string;          // ISO 8601
+}
+```
+
+> ⚠️ `BotDto` **không** chứa `uniqueName` hay `fullName`. Dùng `client.participants.getById(bot.participantId)` để lấy tên và avatar của bot.
+
+### Kiểu dữ liệu Request (Bot)
+
+```ts
+interface CreateBotRequest {
+  uniqueName: string;
+  fullName: string;
+  avatar?: MediaReference;           // optional — avatar của bot
+  description?: string;
+  metadata?: Record<string, unknown>;
+  kafkaTopic: string;                // KHÔNG thể thay đổi sau khi tạo
+  listenAllGroupMessages?: boolean;  // Mặc định false
+}
+
+interface UpdateBotRequest {
+  uniqueName?: string;               // Có thể cập nhật sau khi tạo
+  fullName?: string;
+  avatar?: MediaReference;
+  description?: string;
+  metadata?: Record<string, unknown>;
+  listenAllGroupMessages?: boolean;
+  // kafkaTopic KHÔNG thể cập nhật
+}
+```
+
+---
+
+## 10. Proxy — ProxyApi
+
+**Truy cập:** `client.proxy`
+
+Chuyển tiếp request đến các backend service đã đăng ký qua gateway.
+
+```ts
+// GET /api/proxy/trading/api/stocks/VN30
+const data = await client.proxy.get<StockData>('trading', 'api/stocks/VN30');
+
+// POST /api/proxy/trading/api/orders
+const order = await client.proxy.post<Order>('trading', 'api/orders', {
+  symbol: 'VNM',
+  quantity: 100,
+});
+
+// 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');
+
+// DELETE với body (gateway forward nguyên vẹn — spec §10.1)
+await client.proxy.delete('trading', 'api/orders/bulk', {
+  ids: ['order-1', 'order-2'],
+});
+
+// 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' },
+});
+```
+
+---
+
+## 11. Health — HealthApi
+
+**Truy cập:** `client.health`
+
+Các endpoint **public** (không cần JWT). Cả hai trả về **plain text** (`"Healthy"` / `"Degraded"` / `"Unhealthy"`), KHÔNG phải JSON — server dùng ResponseWriter mặc định của ASP.NET Health Checks (spec §11).
+
+```ts
+// Liveness probe — kiểm tra process có chạy không
+const live = await client.health.live();   // "Healthy"
+
+// Readiness probe — gateway stateless, không đăng ký check nào với tag `ready`,
+// nên hiện luôn trả "Healthy". Gọi /health/ready của backend nếu cần check
+// infrastructure (MongoDB / Redis / Kafka).
+const ready = await client.health.ready(); // "Healthy"
+```
+
+> HTTP status: `200` khi `Healthy`/`Degraded`, `503` khi `Unhealthy`.
+
+---
+
+## 12. Real-time: ChatHubClient
+
+**Truy cập:** `client.realtime.chat`
+
+Kết nối đến SignalR ChatHub (`/hubs/chat`). Xử lý tất cả sự kiện liên quan đến tin nhắn trong cuộc hội thoại.
+
+### Kết nối
+
+```ts
+await client.realtime.chat.connect();
+```
+
+> Nếu đã connected, gọi `connect()` lần nữa sẽ không làm gì. SDK tự động reconnect (dùng SignalR `withAutomaticReconnect`).
+
+### Ngắt kết nối
+
+```ts
+await client.realtime.chat.disconnect();
+// Xóa toàn bộ joinedConversations
+```
+
+> `joinedConversations` là `Set<string>` chứa các conversationId đã join. SDK dùng set này để tự động re-join sau reconnect. Có thể đọc trực tiếp: `client.realtime.chat.joinedConversations`.
+
+### `rejoinConversations(): Promise<void>`
+
+Re-join tất cả conversation đang track. SDK tự gọi sau reconnect; cũng có thể gọi thủ công nếu cần.
+
+```ts
+await client.realtime.chat.rejoinConversations();
+```
+
+### Trạng thái kết nối
+
+```ts
+import { HubConnectionState } from '@microsoft/signalr';
+
+const state = client.realtime.chat.state;
+// HubConnectionState.Connected | Disconnected | Connecting | Reconnecting
+```
+
+### Tham gia / Rời cuộc hội thoại
+
+```ts
+// Tham gia — bắt đầu nhận sự kiện của cuộc hội thoại
+await client.realtime.chat.joinConversation('conv-id');
+
+// Rời
+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
+
+```ts
+const ack = await client.realtime.chat.sendMessage({
+  conversationId: 'conv-id',
+  blocks: [{ $type: 'text', format: 'Plain', content: 'Hello!', plainText: 'Hello!' }],
+  clientMessageId: 'local-uuid', // optional, optimistic rendering
+});
+
+if (ack.success) {
+  console.log('Đã gửi, messageId:', ack.messageId);
+} else {
+  console.error('Lỗi:', ack.errorCode, ack.errorMessage);
+}
+```
+
+### Chỉnh sửa / Xóa / Khôi phục tin nhắn qua SignalR
+
+```ts
+// 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
+const deleteAck = await client.realtime.chat.deleteMessage({ messageId: 'msg-id' });
+
+// Khôi phục
+const recoverAck = await client.realtime.chat.recoverMessage({ messageId: 'msg-id' });
+```
+
+### Typing indicator
+
+```ts
+await client.realtime.chat.startTyping('conv-id');
+await client.realtime.chat.stopTyping('conv-id');
+```
+
+### Reaction qua SignalR
+
+```ts
+await client.realtime.chat.addReaction({ messageId: 'msg-id', conversationId: 'conv-id', emoji: '❤️' });
+await client.realtime.chat.removeReaction({ messageId: 'msg-id', emoji: '❤️' });
+```
+
+### Lắng nghe sự kiện
+
+```ts
+// Đăng ký — trả về hàm unsubscribe
+const unsub = client.realtime.chat.on('messageReceived', (msg) => {
+  console.log('Tin nhắn mới:', msg.plainTextContent);
+});
+
+// Hủy đăng ký
+unsub();
+
+// Hoặc dùng .off()
+const handler = (msg: ChatMessageDto) => { /* ... */ };
+client.realtime.chat.on('messageReceived', handler);
+client.realtime.chat.off('messageReceived', handler);
+```
+
+### Toàn bộ sự kiện ChatHub
+
+| Sự kiện | Payload | Mô tả |
+|---------|---------|-------|
+| `messageReceived` | `ChatMessageDto` | Tin nhắn mới trong cuộc hội thoại |
+| `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õ |
+| `typingStopped` | `TypingDto` | Người dùng dừng gõ |
+| `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 |
+| `streamCompleted` | `StreamCompletedDto` | Bot stream hoàn thành (kèm message đầy đủ) |
+| `streamAborted` | `StreamAbortedDto` | Bot stream bị hủy |
+| `error` | `HubErrorDto` | Lỗi từ server |
+| `reconnecting` | `Error \| undefined` | Đang reconnect |
+| `reconnected` | `string \| undefined` | Đã reconnect (connectionId mới) |
+| `disconnected` | `Error \| undefined` | Mất kết nối hẳn |
+
+### Kiểu dữ liệu sự kiện (ChatHub)
+
+```ts
+// Tin nhắn được chỉnh sửa
+interface MessageUpdatedDto {
+  messageId: string;
+  conversationId: string;
+  blocks: Block[];
+  plainTextContent: string | null;
+  mentions?: Mention[];
+  updatedAt: string;                    // ISO 8601
+  replyToMessageId?: string | null;     // null nếu reply reference đã bị xóa
+}
+
+// Tin nhắn bị xóa
+interface MessageDeletedDto {
+  messageId: string;
+  conversationId: string;
+  deletedBy: string;          // participantId
+  deletedAt: string;          // ISO 8601
+}
+
+// Reaction được thêm
+interface ReactionAddedDto {
+  messageId: string;
+  conversationId: string;
+  participantId: string;
+  participantName: string;
+  emoji: string;
+  createdAt: string;          // ISO 8601
+}
+
+// Reaction được xóa — chú ý field là removedAt, KHÔNG phải createdAt
+interface ReactionRemovedDto {
+  messageId: string;
+  conversationId: string;
+  participantId: string;
+  participantName: string;
+  emoji: string;
+  removedAt: string;          // ISO 8601 — khác với ReactionAddedDto.createdAt
+}
+
+// Typing indicator
+interface TypingDto {
+  conversationId: string;
+  participantId: string;
+  participantName: string;
+}
+
+// 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
+
+Khi bot streaming, **không có** `messageReceived` — thay vào đó nhận chuỗi sự kiện sau:
+
+```
+streamStarted → streamStatusUpdated* → streamChunkReceived* → streamCompleted
+                                                             → streamAborted
+```
+
+```ts
+const chunks: string[] = [];
+
+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('')
+});
+
+client.realtime.chat.on('streamCompleted', (dto) => {
+  console.log('Tin nhắn hoàn chỉnh:', dto.message);
+  chunks.length = 0; // reset
+});
+
+client.realtime.chat.on('streamAborted', (dto) => {
+  console.error('Stream bị hủy:', dto.reason);
+});
+```
+
+---
+
+## 13. Real-time: NotificationHubClient
+
+**Truy cập:** `client.realtime.notifications`
+
+Kết nối đến SignalR NotificationHub (`/hubs/notifications`). Nhận thông báo cấp user (không cần tham gia conversation).
+
+### Trạng thái kết nối
+
+```ts
+import { HubConnectionState } from '@microsoft/signalr';
+
+const state = client.realtime.notifications.state;
+// HubConnectionState.Connected | Disconnected | Connecting | Reconnecting
+```
+
+### Kết nối
+
+```ts
+await client.realtime.notifications.connect();
+// Sau khi kết nối, server tự động thêm user vào group `participant:{userId}`
+// để nhận các thông báo cá nhân — KHÔNG cần gọi hub method nào.
+```
+
+### Ngắt kết nối
+
+```ts
+await client.realtime.notifications.disconnect();
+// Server tự động dọn dẹp group cá nhân.
+```
+
+> NotificationHub **không expose hub method** nào do client gọi và **không phát event `Error`** — toàn bộ event được server đẩy tự động sau khi connect. JWT thiếu/sai/hết hạn bị gateway từ chối ở mức HTTP 401 (silent), không có signal qua hub. Listener `error` chỉ cần đăng ký trên ChatHub.
+
+### Toàn bộ sự kiện NotificationHub
+
+| Sự kiện | Payload | Mô tả |
+|---------|---------|-------|
+| `newMessageNotification` | `NewMessageNotificationDto` | Có tin nhắn mới (gửi cho tất cả participants trừ người gửi). **Không gửi cho system message**; vẫn gửi bình thường cho streaming message của bot |
+| `mentionedNotification` | `MentionedNotificationDto` | User được mention. Chỉ phát sinh với mention `type: "User"` có `targetId` hợp lệ; mention `All`/`Here`/`Role` không sinh event này |
+| `conversationCreated` | `ConversationCreatedDto` | Conversation mới xuất hiện trong danh sách của user — do vừa được tạo (gửi cho tất cả participant ban đầu) hoặc user vừa được thêm vào (chỉ gửi cho người mới) |
+| `conversationUpdated` | `ConversationUpdatedDto` | Metadata cuộc hội thoại thay đổi (tên, avatar...) |
+| `participantJoined` | `ParticipantJoinedDto` | Có thành viên mới — chỉ gửi cho các participant đã có sẵn (người mới nhận `conversationCreated`) |
+| `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 |
+| `reconnecting` | `Error \| undefined` | Đang reconnect |
+| `reconnected` | `string \| undefined` | Đã reconnect |
+| `disconnected` | `Error \| undefined` | Mất kết nối |
+
+### Kiểu dữ liệu sự kiện (NotificationHub)
+
+```ts
+interface NewMessageNotificationDto {
+  conversationId: string;
+  conversationName?: string | null;
+  messageId: string;
+  senderId: string;
+  senderName: string;
+  senderAvatar?: MediaReference | null; // Có thể null khi server chưa sẵn signed URL
+  contentPreview: string;     // Plain text, server cắt tối đa 100 ký tự
+  sentAt: string;             // ISO 8601
+}
+
+// Chú ý: KHÔNG có senderAvatar (khác NewMessageNotificationDto)
+interface MentionedNotificationDto {
+  conversationId: string;
+  messageId: string;
+  senderId: string;
+  senderName: string;
+  contentPreview: string;     // Plain text, server cắt tối đa 100 ký tự
+  sentAt: string;             // ISO 8601
+}
+
+interface ConversationCreatedDto {
+  conversationId: string;
+  name?: string | null;
+  avatar?: MediaReference | null;
+  participantCount: number;
+}
+
+interface ConversationUpdatedDto {
+  conversationId: string;
+  name?: string | null;
+  avatar?: MediaReference | null; // null = avatar đã bị xóa
+  participantCount: number;
+}
+
+interface ParticipantJoinedDto {
+  conversationId: string;
+  participantId: string;
+  participantName: string;
+  participantAvatar?: MediaReference | null; // Có thể null khi server chưa sẵn signed URL
+  changedAt: string;          // ISO 8601
+}
+
+// Cùng shape với ParticipantJoinedDto
+interface ParticipantLeftDto {
+  conversationId: string;
+  participantId: string;
+  participantName: string;
+  participantAvatar?: MediaReference | null; // Có thể null khi server chưa sẵn signed URL
+  changedAt: string;          // ISO 8601
+}
+
+interface ConversationPinnedDto {
+  conversationId: string;
+  pinnedAt: string;           // ISO 8601
+}
+
+// Chú ý: KHÔNG có pinnedAt (khác ConversationPinnedDto)
+interface ConversationUnpinnedDto {
+  conversationId: string;
+}
+```
+
+---
+
+## 14. 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.
+
+```ts
+import { ReconnectionManager } from '@manonero/chat-client-sdk';
+
+const manager = new ReconnectionManager({
+  chatHub: client.realtime.chat,
+  notificationHub: client.realtime.notifications,
+  onTokenExpired: async () => {
+    // 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; lần connect() kế tiếp sẽ dùng giá trị mới
+    }
+    return newToken; // Trả về null để hủy reconnect
+  },
+});
+
+manager.start(); // Bắt đầu quản lý — idempotent, gọi nhiều lần an toàn
+
+// Khi không còn cần
+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:** 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.
+
+---
+
+## 15. 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`.
+
+### Các loại Block
+
+| `$type` | Interface | Mô tả |
+|---------|-----------|-------|
+| `"text"` | `TextBlock` | Văn bản (Plain, Markdown, Html, ProseMirrorJson) |
+| `"image"` | `ImageBlock` | Hình ảnh |
+| `"video"` | `VideoBlock` | Video |
+| `"audio"` | `AudioBlock` | Âm thanh |
+| `"file"` | `FileBlock` | Tệp tin |
+| `"linkPreview"` | `LinkPreviewBlock` | Preview URL |
+| `"embed"` | `EmbedBlock` | Nhúng nội dung (iframe) |
+| `"location"` | `LocationBlock` | Vị trí địa lý |
+| `"contact"` | `ContactBlock` | Thông tin liên hệ |
+| `"choice"` | `ChoiceBlock` | Câu hỏi / lựa chọn (bot) |
+| `"card"` | `CardBlock` | Thẻ thông tin có button |
+| `"carousel"` | `CarouselBlock` | Nhiều card liên tiếp |
+| `"divider"` | `DividerBlock` | Đường phân cách |
+| `"custom"` | `CustomBlock` | Block tùy chỉnh |
+
+### Interfaces tham chiếu đầy đủ
+
+```ts
+interface TextBlock {
+  $type: 'text';
+  format: TextFormat; // 'Plain' | 'Markdown' | 'Html' | 'ProseMirrorJson'
+  content: string;
+  plainText: string | null;
+}
+
+interface ImageBlock {
+  $type: 'image';
+  source: MediaReference;
+  thumbnail: MediaReference | null;
+  altText: string | null;
+  width: number | null;
+  height: number | null;
+  caption: string | null;
+  fileSizeBytes: number | null;
+}
+
+interface VideoBlock {
+  $type: 'video';
+  source: MediaReference;
+  thumbnail: MediaReference | null;
+  caption: string | null;
+  durationSeconds: number | null;
+  mimeType: string | null;
+  fileSizeBytes: number | null;
+}
+
+interface AudioBlock {
+  $type: 'audio';
+  source: MediaReference;
+  durationSeconds: number | null;
+  mimeType: string | null;
+  transcript: string | null;    // Bản ghi âm thanh (nếu có)
+  fileSizeBytes: number | null;
+}
+
+interface FileBlock {
+  $type: 'file';
+  source: MediaReference;
+  fileName: string;
+  mimeType: string | null;
+  fileSizeBytes: number | null;
+}
+
+interface LinkPreviewBlock {
+  $type: 'linkPreview';
+  url: string;
+  title: string | null;
+  description: string | null;
+  image: MediaReference | null;
+  siteName: string | null;
+}
+
+interface EmbedBlock {
+  $type: 'embed';
+  url: string;
+  html: string | null;          // HTML nhúng (iframe snippet)
+  width: number | null;
+  height: number | null;
+}
+
+interface LocationBlock {
+  $type: 'location';
+  latitude: number;
+  longitude: number;
+  name: string | null;
+  address: string | null;
+}
+
+interface ContactBlock {
+  $type: 'contact';
+  displayName: string;
+  phone: string | null;
+  email: string | null;
+  organization: string | null;
+}
+
+interface ChoiceBlock {
+  $type: 'choice';
+  prompt: string;               // Câu hỏi hiển thị cho user
+  options: ChoiceOption[];
+  mode: ChoiceMode;             // 'Single' | 'Multiple'
+  submitted: boolean;           // true sau khi user đã submit lựa chọn
+}
+
+interface CardBlock {
+  $type: 'card';
+  title: string | null;
+  subtitle: string | null;
+  image: MediaReference | null;
+  fields: CardField[] | null;
+  buttons: ActionButton[] | null;
+}
+
+interface CarouselBlock {
+  $type: 'carousel';
+  cards: CardBlock[];           // Danh sách card trình chiếu ngang
+}
+
+interface DividerBlock {
+  $type: 'divider';             // Đường phân cách — không có field nào khác
+}
+
+interface CustomBlock {
+  $type: 'custom';
+  type: string;                 // Discriminator tùy chỉnh của ứng dụng
+  data: Record<string, unknown> | null;
+}
+```
+
+### Type Guards
+
+SDK xuất sẵn các hàm kiểm tra kiểu (type guard), giúp TypeScript thu hẹp kiểu tự động:
+
+```ts
+import { isTextBlock, isImageBlock, isFileBlock, isCardBlock } from '@manonero/chat-client-sdk';
+
+for (const block of message.blocks) {
+  if (isTextBlock(block)) {
+    console.log(block.content); // TypeScript biết đây là TextBlock
+  } else if (isImageBlock(block)) {
+    console.log(block.source.url); // ImageBlock
+  } else if (isFileBlock(block)) {
+    console.log(block.fileName, block.fileSizeBytes);
+  } else if (isCardBlock(block)) {
+    block.buttons?.forEach(btn => console.log(btn.label, btn.action));
+  }
+}
+```
+
+Danh sách đầy đủ: `isTextBlock`, `isImageBlock`, `isVideoBlock`, `isAudioBlock`, `isFileBlock`, `isLinkPreviewBlock`, `isEmbedBlock`, `isLocationBlock`, `isContactBlock`, `isChoiceBlock`, `isCardBlock`, `isCarouselBlock`, `isDividerBlock`, `isCustomBlock`.
+
+### Ví dụ tạo block
+
+```ts
+// Văn bản Markdown
+const textBlock: TextBlock = {
+  $type: 'text',
+  format: 'Markdown',
+  content: '**Hello** _world_!',
+  plainText: 'Hello world!',
+};
+
+// Hình ảnh đã upload
+const imageBlock: ImageBlock = {
+  $type: 'image',
+  source: { storageKey: '01HXABCDEF/photo.jpg' },
+  thumbnail: null,
+  altText: 'Ảnh chụp',
+  width: 1920,
+  height: 1080,
+  caption: 'Ảnh mô tả',
+  fileSizeBytes: 204800,
+};
+
+// Gửi tin nhắn kèm file
+const fileBlock: FileBlock = {
+  $type: 'file',
+  source: { storageKey: '01HXABCDEF/report.pdf' },
+  fileName: 'report.pdf',
+  mimeType: 'application/pdf',
+  fileSizeBytes: 1048576,
+};
+```
+
+### TextFormat
+
+| Giá trị | Mô tả |
+|---------|-------|
+| `'Plain'` | Văn bản thuần |
+| `'Markdown'` | Markdown |
+| `'Html'` | HTML (render trong WebView) |
+| `'ProseMirrorJson'` | Rich text dạng JSON (ProseMirror) |
+
+### ButtonAction / ButtonStyle (dùng trong CardBlock)
+
+```ts
+type ButtonAction = 'Postback' | 'Url' | 'Call' | 'Copy';
+type ButtonStyle = 'Default' | 'Primary' | 'Danger';
+
+interface ActionButton {
+  label: string;
+  action: ButtonAction;
+  value?: string | null;
+  style: ButtonStyle;
+}
+
+interface CardField {
+  label: string;
+  value: string;
+}
+```
+
+### ChoiceMode / ChoiceOption / ChoiceBlock
+
+```ts
+type ChoiceMode = 'Single' | 'Multiple';
+
+interface ChoiceOption {
+  label: string;
+  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
+}
+```
+
+### QuickReply
+
+Nút bấm nhanh hiển thị bên dưới tin nhắn bot:
+
+```ts
+interface QuickReply {
+  label: string;       // Text hiển thị
+  action: QuickReplyAction; // 'SendText' | 'Postback' | 'Url'
+  value: string | null;
+  icon: string | null;
+}
+```
+
+### Mention
+
+```ts
+interface Mention {
+  type: MentionType;   // 'User' | 'All' | 'Here' | 'Role'
+  targetId: string | null; // User ID (null cho All/Here)
+  displayName: string;
+  offset: number | null;   // Vị trí trong plainText
+  length: number | null;
+}
+```
+
+---
+
+## 16. Toàn bộ kiểu dữ liệu (Types)
+
+### CursorPaginatedResult (cursor-based)
+
+```ts
+interface CursorPaginatedResult<T> {
+  items: T[];
+  nextCursor: string | null; // PHẢI là string opaque — KHÔNG cast sang number
+  hasMore: boolean;
+}
+```
+
+### PagedResult (page-based)
+
+```ts
+interface PagedResult<T> {
+  items: T[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+```
+
+### 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)
+}
+```
+
+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;
+}
+```
+
+### ChatMessageDto (SignalR version)
+
+Khác với `MessageDto` (REST):
+
+```ts
+interface ChatMessageDto {
+  id: string;
+  conversationId: string;
+  senderId: string;
+  senderName: string;        // 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)
+  replyToMessageId: string | null;
+  quickReplies: QuickReply[] | null;
+  isEdited: boolean;
+  reactions: ReactionGroupDto[] | null; // Flat array, khác REST
+  mentions: Mention[] | null;
+  createdAt: string;
+  updatedAt: string | null;
+  clientMessageId: string | null;
+  systemEvent: SystemEventDto | null;
+}
+
+// Reaction group (SignalR version — flat array, KHÔNG gói trong ReactionSummary)
+// So sánh với REST: ReactionSummary { groups: ReactionGroup[], totalCount }
+interface ReactionGroupDto {
+  emoji: string;
+  count: number;
+  participantIds: string[];   // Danh sách participant đã react
+}
+```
+
+### SystemEvent
+
+```ts
+type SystemEventType =
+  | 'ConversationRenamed'  // Đổi tên nhóm
+  | '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';              // Sự kiện tùy chỉnh do server định nghĩa
+
+interface SystemEventInfo {
+  type: SystemEventType;
+  actorId?: string | null;  // null/undefined khi không có actor (vd. MemberLeft tự rời)
+  targetIds?: string[];
+  // 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
+interface SystemEventDto extends SystemEventInfo {
+  actorName?: string;       // Tên hiển thị của actor
+  targetNames?: string[];   // Tên hiển thị của các target participants
+}
+```
+
+### HubErrorDto
+
+```ts
+interface HubErrorDto {
+  code: string;
+  message: string;
+  // Server có thể gửi `null` rõ ràng, hoặc bỏ field hoàn toàn
+  details?: Record<string, unknown> | null;
+}
+```
+
+### Streaming DTOs (ChatHub)
+
+```ts
+interface StreamStartedDto {
+  streamId: string;
+  messageId: string;
+  conversationId: string;
+  senderId: string;
+  senderName: 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 {
+  streamId: string;
+  messageId: string;
+  conversationId: string;
+  status: string;            // e.g. "thinking", "searching"
+  detail?: string;
+  updatedAt: string;         // ISO 8601
+}
+
+interface StreamChunkReceivedDto {
+  streamId: string;
+  messageId: string;
+  conversationId: string;
+  text: string;              // Chunk text để append vào placeholder
+  chunkIndex: number;        // Zero-based index
+}
+
+// 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 {
+  streamId: string;
+  messageId: string;
+  conversationId: string;
+  parts: StreamChunkPart[];
+}
+
+interface StreamCompletedDto {
+  streamId: string;
+  messageId: string;
+  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 {
+  streamId: string;
+  messageId: string;
+  conversationId: string;
+  reason: string;
+  abortedAt: string;         // ISO 8601
+}
+```
+
+### 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:
+
+```ts
+interface SendMessageAck {
+  success: boolean;
+  messageId?: string;
+  clientMessageId?: string;
+  createdAt?: string;        // ISO 8601 — thời điểm server tạo tin nhắn
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+interface EditMessageAck {
+  success: boolean;
+  messageId?: string;
+  editedAt?: string;         // ISO 8601
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+interface DeleteMessageAck {
+  success: boolean;
+  messageId?: string;
+  deletedAt?: string;        // ISO 8601
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+interface RecoverMessageAck {
+  success: boolean;
+  messageId?: string;
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+interface ReactionAck {
+  success: boolean;
+  messageId?: string;
+  emoji?: string;
+  errorCode?: string;
+  errorMessage?: string;
+}
+```
+
+---
+
+## 17. Xử lý lỗi — ChatApiError
+
+Tất cả lỗi HTTP đều throw `ChatApiError` (kế thừa `Error`).
+
+```ts
+import { ChatApiError } from '@manonero/chat-client-sdk';
+
+try {
+  await client.messages.send('conv-id', { blocks: [...] });
+} catch (err) {
+  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();
+        break;
+      case 403: // Forbidden — không có quyền
+        break;
+      case 404: // Not Found
+        break;
+      case 409: // Conflict — ví dụ: đã react emoji đó rồi
+        break;
+      case 429: // Rate Limited
+        break;
+    }
+  }
+}
+```
+
+### Thuộc tính ChatApiError
+
+| Thuộc tính | Kiểu | Mô tả |
+|------------|------|-------|
+| `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`) |
+| `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: `{ type, status, title, detail?, errors?, traceId? }`. Endpoint proxy trả `{ detail }` đơn giản hơn, và `/health/*` trả plain text (`"Unhealthy"`) — SDK xử lý cả ba.
+
+> **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
+
+#### `ChatApiError.fromResponse(response: Response): Promise<ChatApiError>`
+
+Parse lỗi từ HTTP `Response`. SDK gọi nội bộ — bạn không cần gọi trực tiếp. Hỗ trợ ba loại body: RFC 7807 JSON (REST chuẩn), `{ detail }` JSON (proxy), và plain text (`/health/*` trả `"Unhealthy"` → set vào `error.detail`).
+
+#### `ChatApiError.fromProblemDetails(pd: ProblemDetails): ChatApiError`
+
+Tạo `ChatApiError` từ object `ProblemDetails` (RFC 7807). Hữu ích khi bạn nhận `ProblemDetails` từ nguồn khác (ví dụ: WebSocket, tự parse).
+
+```ts
+import { ChatApiError } from '@manonero/chat-client-sdk';
+import type { ProblemDetails } from '@manonero/chat-client-sdk';
+
+const pd: ProblemDetails = {
+  type: 'https://tools.ietf.org/html/rfc9110#section-15.5.5',
+  status: 404,
+  title: 'Not Found',
+  detail: 'Conversation not found',
+};
+const error = ChatApiError.fromProblemDetails(pd);
+console.log(error.status);  // 404
+console.log(error.message); // "Conversation not found"
+```
+
+### ProblemDetails
+
+Kiểu dữ liệu RFC 7807 mà server trả về khi có lỗi:
+
+```ts
+interface ProblemDetails {
+  type: string;            // URI tham chiếu (RFC 7807) — luôn được framework inject
+  status: number;
+  title: string;
+  detail?: string;
+  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"
+}
+```
+
+---
+
+### Sử dụng hub client độc lập (không qua ChatClient)
+
+Power users có thể khởi tạo `ChatHubClient` hoặc `NotificationHubClient` trực tiếp, không qua `ChatClient` facade:
+
+```ts
+import { ChatHubClient, NotificationHubClient } from '@manonero/chat-client-sdk';
+import { LogLevel } from '@microsoft/signalr';
+
+// Tự quản lý token
+const tokenProvider = () => localStorage.getItem('jwt');
+
+// Khởi tạo ChatHub độc lập
+const chatHub = new ChatHubClient({
+  hubUrl: 'https://chat-api.example.com/hubs/chat',
+  tokenProvider,
+  logLevel: LogLevel.Warning, // optional
+});
+
+// Khởi tạo NotificationHub độc lập
+const notificationHub = new NotificationHubClient({
+  hubUrl: 'https://chat-api.example.com/hubs/notifications',
+  tokenProvider,
+});
+
+await chatHub.connect();
+await notificationHub.connect();
+
+// Kết hợp với ReconnectionManager
+import { ReconnectionManager } from '@manonero/chat-client-sdk';
+
+const manager = new ReconnectionManager({
+  chatHub,
+  notificationHub,
+  onTokenExpired: async () => {
+    const newToken = await refreshMyToken();
+    return newToken;
+  },
+});
+manager.start();
+```
+
+> ⚠️ Khi dùng standalone, bạn phải tự quản lý token và truyền đúng `hubUrl` (bao gồm full URL kèm `/hubs/chat` hoặc `/hubs/notifications`).
+
+---
+
+## 18. 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()`.
+
+```ts
+// Đăng ký handler — trả về hàm unsubscribe
+const unsub = hub.on('eventName', (payload) => { /* ... */ });
+
+// Hủy bằng hàm unsubscribe
+unsub();
+
+// Hoặc hủy bằng .off()
+hub.off('eventName', handler);
+```
+
+**Lưu ý:** Khi dùng `.off()`, phải truyền chính xác **cùng một reference hàm** đã đăng ký. Dùng cách unsubscribe function từ `.on()` để tránh lỗi này.
+
+> ⚠️ **`removeAllListeners()` không được expose** trên `ChatHubClient` hay `NotificationHubClient`. Method này chỉ tồn tại trên class `TypedEventEmitter` khi dùng trực tiếp — không qua hub. Hai hub client chỉ expose `.on()` và `.off()`. Để dọn dẹp nhiều listener khi unmount component, lưu lại từng unsubscribe function và gọi từng cái:
+
+```ts
+const unsubs: Array<() => void> = [];
+unsubs.push(hub.on('messageReceived', handler1));
+unsubs.push(hub.on('typingStarted', handler2));
+
+// Khi cleanup:
+unsubs.forEach(fn => fn());
+```
+
+---
+
+## 19. Lưu ý quan trọng
+
+### Cursor pagination — KHÔNG cast sang number
+
+```ts
+// ✅ Đúng
+const cursor: string = result.nextCursor!;
+await client.conversations.list({ cursor });
+
+// ❌ Sai — mất độ chính xác vì vượt Number.MAX_SAFE_INTEGER
+const cursor = Number(result.nextCursor); // BUG!
+```
+
+### Token và SignalR
+
+- `setToken()` hoạt động ngay cho **HTTP requests**.
+- SignalR đọc token khi **connect()**, không phải mid-session.
+- Để áp token mới ngay cho hub đang Connected: `setToken(newToken)` → `await refreshConnections()`.
+- Sau `refreshConnections()` cần tự `joinConversation()` 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, 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
+const { storageKey } = await client.files.uploadFile(file);
+
+const block: ImageBlock = {
+  $type: 'image',
+  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;
+}
+
+// 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:
+
+```ts
+const bot = await client.bots.getById('bot-id');
+const participant = await client.participants.getById(bot.participantId);
+console.log(participant.fullName); // Tên hiển thị của bot
+```
+
+---
+
+## 20. Ví dụ đầy đủ
+
+### Ví dụ 1: Chat app cơ bản
+
+```ts
+import { ChatClient, ChatApiError } from '@manonero/chat-client-sdk';
+import type { ChatMessageDto } from '@manonero/chat-client-sdk';
+
+// 1. Khởi tạo
+const client = new ChatClient({ baseUrl: 'https://chat-api.example.com' });
+
+// 2. Đăng nhập
+await client.auth.loginWithGoogle(googleIdToken);
+console.log('Xin chào,', client.currentUser?.fullName);
+
+// 3. Kết nối hub (thứ tự: notifications trước, chat sau)
+await client.realtime.notifications.connect();
+await client.realtime.chat.connect();
+
+// 4. Lắng nghe thông báo
+client.realtime.notifications.on('newMessageNotification', (notification) => {
+  console.log(`[${notification.conversationId}] ${notification.senderName}: ${notification.contentPreview}`);
+});
+
+// 5. Mở cuộc hội thoại và chat
+const convId = 'conv-id-here';
+await client.realtime.chat.joinConversation(convId);
+
+// Lắng nghe tin nhắn
+const unsubMsg = client.realtime.chat.on('messageReceived', (msg: ChatMessageDto) => {
+  appendMessageToUI(msg);
+});
+
+// Lắng nghe typing
+client.realtime.chat.on('typingStarted', (dto) => {
+  showTypingIndicator(dto.participantName);
+});
+
+// 6. Gửi tin nhắn
+async function sendMessage(text: string) {
+  const ack = await client.realtime.chat.sendMessage({
+    conversationId: convId,
+    blocks: [{ $type: 'text', format: 'Plain', content: text, plainText: text }],
+  });
+  if (!ack.success) throw new Error(ack.errorMessage);
+}
+
+// 7. Upload và gửi file
+async function sendFile(file: File) {
+  const { storageKey } = await client.files.uploadFile(file, (loaded, total) => {
+    setProgress(Math.round((loaded / total) * 100));
+  });
+
+  await client.realtime.chat.sendMessage({
+    conversationId: convId,
+    blocks: [{
+      $type: 'file',
+      source: { storageKey },
+      fileName: file.name,
+      mimeType: file.type,
+      fileSizeBytes: file.size,
+    }],
+  });
+}
+
+// 8. Đánh máy indicator
+let typingTimer: ReturnType<typeof setTimeout>;
+function onUserType() {
+  client.realtime.chat.startTyping(convId);
+  clearTimeout(typingTimer);
+  typingTimer = setTimeout(() => client.realtime.chat.stopTyping(convId), 2000);
+}
+
+// 9. Dọn dẹp khi thoát
+async function cleanup() {
+  unsubMsg(); // Hủy event listener
+  await client.disconnect();
+}
+```
+
+### Ví dụ 2: Load lịch sử tin nhắn với infinite scroll
+
+```ts
+let cursor: string | null = null;
+let loading = false;
+
+async function loadMoreMessages(conversationId: string) {
+  if (loading) return;
+  loading = true;
+
+  try {
+    const result = await client.messages.getHistory(conversationId, {
+      limit: 30,
+      cursor: cursor ?? undefined,
+      direction: 'older',
+    });
+
+    result.items.forEach(msg => prependMessageToUI(msg));
+    cursor = result.nextCursor;
+
+    if (!result.hasMore) {
+      hideLoadMoreButton();
+    }
+  } finally {
+    loading = false;
+  }
+}
+```
+
+### Ví dụ 3: Xử lý bot streaming
+
+```ts
+const streamBuffers = new Map<string, string[]>();
+
+client.realtime.chat.on('streamStarted', (dto) => {
+  streamBuffers.set(dto.streamId, []);
+  addStreamingPlaceholder(dto.messageId, dto.senderName);
+});
+
+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(''));
+}
+
+client.realtime.chat.on('streamChunkReceived', (dto) => {
+  appendChunk(dto.streamId, dto.messageId, 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('streamCompleted', (dto) => {
+  streamBuffers.delete(dto.streamId);
+  replaceWithFinalMessage(dto.message); // ChatMessageDto đầy đủ
+});
+
+client.realtime.chat.on('streamAborted', (dto) => {
+  streamBuffers.delete(dto.streamId);
+  showStreamError(dto.messageId, dto.reason);
+});
+```
+
+### Ví dụ 4: Xử lý lỗi và token refresh
+
+```ts
+import { ReconnectionManager } from '@manonero/chat-client-sdk';
+
+let isRefreshing = false;
+
+const manager = new ReconnectionManager({
+  chatHub: client.realtime.chat,
+  notificationHub: client.realtime.notifications,
+  onTokenExpired: async () => {
+    if (isRefreshing) return null;
+    isRefreshing = true;
+    try {
+      const newToken = await myAuthService.refreshToken();
+      if (newToken) {
+        client.setToken(newToken);
+        localStorage.setItem('token', newToken);
+      }
+      return newToken;
+    } finally {
+      isRefreshing = false;
+    }
+  },
+});
+
+manager.start();
+
+// Lắng nghe lỗi hub
+client.realtime.chat.on('error', (err) => {
+  console.error(`Hub error [${err.code}]: ${err.message}`);
+});
+
+client.realtime.chat.on('disconnected', (err) => {
+  if (err) console.warn('ChatHub disconnected:', err.message);
+  showReconnectingUI();
+});
+
+client.realtime.chat.on('reconnected', () => {
+  hideReconnectingUI();
+});
+```