# KBChatMQ Hub — Hướng dẫn SDK (phát hành cộng đồng)

SDK là **mã nguồn mẫu** gọi HTTP tới API công khai của Hub. Phù hợp nhúng vào ứng dụng **Node.js, PHP, Python, C#, Android (Kotlin), iOS (Swift)**.

## Vị trí file trên server

| Mục | URL (khi Hub đang chạy) |
|-----|-------------------------|
| Trang SDK | `/sdk/index.html` |
| Manifest JSON | `GET /api/sdk/manifest` |
| Gói zip | `/sdk/dist/kbchatmq-sdk-bundle.zip` (tạo bằng `node scripts/pack-sdk.cjs`) |
| Mã từng ngôn ngữ | `/sdk/nodejs/`, `/sdk/php/`, … |

## Nguyên tắc bảo mật (bắt buộc đọc)

Xem **[SECURITY.md](./SECURITY.md)**. Tóm tắt:

- **Không** commit vào repo ứng dụng: mật khẩu, user token, device token, website token, admin token, `encryptKey`, JWT MQTT.
- Chỉ cấu hình **URL gốc Hub** (ví dụ `https://hub.example.com`); SDK tự thêm `/api`.
- Dữ liệu nhạy cảm chỉ có sau `POST /api/auth/login` (và các biến thể token/device/visitor); lưu **Keychain / Keystore / biến môi trường server**, không log production.

## API được SDK bọc sẵn

Tiền tố: `https://<hub>/api`

| Phương thức | Đường dẫn | Ghi chú |
|-------------|-----------|---------|
| POST | `/auth/login` | `userId` + `password` |
| POST | `/auth/login-token` | `userToken` |
| POST | `/auth/login-visitor` | `websiteToken`, tùy `visitorId` |
| POST | `/auth/login-device` | `deviceToken`, tùy `deviceId` |
| POST | `/auth/refresh` | JWT user (theo tài liệu Hub) |
| POST | `/auth/refresh-device` | JWT thiết bị |
| POST | `/auth/chat-rooms` | Body xác thực giống Chat web |
| GET | `/chat/heartbeat-config` | Chu kỳ heartbeat công khai |
| POST | `/chat/heartbeat` | `userId`, tùy `deviceId`, `clientInstanceId`, … |
| GET | `/chat/presence` | Danh sách online (public) |

MQTT sau khi login: dùng `allocation` (broker, `clientId`, JWT làm password, `topics`, `encryptKey`) — **không** hard-code trong SDK.

### Mã hóa payload chat/pubsub (company room)

- Node SDK có thêm helper:
  - `encryptChatPayload(plainJson, keyB64)`
  - `decryptChatPayload(cipherB64, keyB64)`
  - `companyMqttTopic(companyId)` → `chat/company/{companyId}`
- Python/PHP cũng có helper tương đương trong:
  - `sdk/python/kbchatmq/chat_crypto.py`
  - `sdk/php/ChatCrypto.php`

## Từng ngôn ngữ

- **[NODEJS.md](./NODEJS.md)** — npm / require, Node 18+
- **[PHP.md](./PHP.md)** — include class, curl
- **[PYTHON.md](./PYTHON.md)** — package `kbchatmq`, stdlib
- **[CSHARP.md](./CSHARP.md)** — copy `.cs`, HttpClient
- **[ANDROID.md](./ANDROID.md)** — Kotlin, URLConnection
- **[IOS.md](./IOS.md)** — Swift, URLSession

## Kiểm thử SDK (Node / PHP / Python)

Thư mục `servermqnew/tests/` — cần Hub đang chạy. Xem [tests/README.md](../../tests/README.md).

```bash
npm run test:sdk:node
npm run test:sdk:php
npm run test:sdk:python
# hoặc cả ba: npm run test:sdk

# pub/sub company room (gửi 2-3 tin, đo lag)
npm run test:sdk:node:pubsub
npm run test:sdk:php:pubsub
npm run test:sdk:python:pubsub
# hoặc cả ba: npm run test:sdk:pubsub
```

## Tạo lại file zip phát hành

Trong thư mục `servermqnew`:

```bash
node scripts/pack-sdk.cjs
```

File ra: `sdk/dist/kbchatmq-sdk-bundle.zip`. Nên đính kèm release GitHub / gửi cộng đồng cùng version trong `sdk/manifest.json`.

## Phiên bản

Số phiên bản nằm trong `sdk/manifest.json` (`version`). Khi đổi API Hub breaking, tăng semver SDK và cập nhật tài liệu này.

## Giấy phép

Mã SDK: **MIT** (`sdk/LICENSE`). Hub đầy đủ tuân theo giấy phép dự án của bạn.