@sentinel-it/meowmeow-sdk 1.0.0-rc.6207efd

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sentinel IT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# MeowMeow SDK
+
+可嵌入式群組聊天室 JavaScript / TypeScript SDK
+
+[API Reference](api-docs/index.md)
+
+---
+
+# 快速開始
+
+## 安裝
+
+**npm / pnpm（ESM）**
+
+```bash
+npm install @sentinel-it/meowmeow-sdk
+# 或
+pnpm add @sentinel-it/meowmeow-sdk
+```
+
+**CDN（IIFE）**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@sentinel-it/meowmeow-sdk@latest/dist/meowmeow-sdk.js"></script>
+<script>
+  const { MeowMeow, MeowMeowClient } = MeowMeowSDK
+</script>
+```
+
+## Token
+
+呼叫 SDK 前，後端須向 MeowMeow 服務端取得使用者 JWT Token 並傳給前端。
+
+若提供 `onTokenRefresh`，SDK 會在 Token 到期前 30 秒自動呼叫以取得新 Token，連線不會中斷。若未提供，Token 過期後連線將會斷開。
+
+---
+
+## MeowMeow — 嵌入聊天室 UI
+
+`MeowMeow` 可直接將聊天室 Widget 嵌入頁面。
+
+```ts
+import { MeowMeow } from '@sentinel-it/meowmeow-sdk'
+
+const chat = new MeowMeow({
+  token: 'YOUR_JWT_TOKEN',
+  locale: 'zh',
+  title: '客服聊天室',
+  onTokenRefresh: async () => {
+    const res = await fetch('/api/chat-token')
+    const { token } = await res.json()
+    return token
+  },
+})
+
+await chat.mount()
+chat.show()
+```
+
+### 初始化選項
+
+| 選項 | 型別 | 必填 | 說明 |
+|------|------|:----:|------|
+| `token` | `string` | ✓ | 使用者 JWT Token |
+| `locale` | `string` | | 介面語言，預設 `'en-US'`，支援 `en-US`、`zh-Hant`、`zh-Hans`、`vi-VN`、`th-TH`、`id-ID`、`pt-BR`、`my-MM`、`hi-IN`、`ru-RU`、`ko-KR`、`ms-MY`、`fil-PH` |
+| `theme` | `'p1' \| 'p2'` | | 介面主題，預設 `'p1'`，傳入無效值自動回退到 `'p1'` |
+| `title` | `string \| Record<string, string>` | | 聊天室標題，可傳入語系對照物件 |
+| `onTokenRefresh` | `() => Promise<string>` | | Token 刷新回呼 |
+
+`title` 可傳入語系對照物件：
+
+```ts
+title: {
+  'en-US': 'Chat Room', // 英語 ( 預設 )
+  'zh-Hant': '聊天室', // 繁體中文
+  'zh-Hans': '聊天室', // 簡體中文
+  'vi-VN': 'Phòng trò chuyện', // 越南語
+  'th-TH': 'ห้องแชท', // 泰語
+  'id-ID': 'Ruang Obrolan', // 印尼語
+  'pt-BR': 'Sala de bate-papo', // 葡萄牙語 ( 巴西 )
+  'my-MM': 'ချတ်ခန်း', // 緬甸語
+  'hi-IN': 'चैट रूम', // 印地語
+  'ru-RU': 'Чат', // 俄語
+  'ko-KR': '채팅방', // 韓國語
+  'ms-MY': 'Bilik Sembang', // 馬來語
+  'fil-PH': 'Silid ng Chat', // 菲律賓語
+}
+```
+
+### 方法
+
+| 方法 | 說明 |
+|------|------|
+| `mount(): Promise<void>` | 掛載 Widget 至 DOM |
+| `unmount(): void` | 卸載並釋放資源 |
+| `show(): void` | 顯示 Widget |
+| `hide(): void` | 隱藏 Widget |
+| `join(roomId: string): Promise<void>` | 加入指定聊天室（需先呼叫 `mount()`） |
+| `setLocale(locale: string): void` | 動態切換介面語言（`en-US`、`zh-Hant`、`zh-Hans`、`vi-VN`、`th-TH`、`id-ID`、`pt-BR`、`my-MM`、`hi-IN`、`ru-RU`、`ko-KR`、`ms-MY`、`fil-PH`） |
+| `setTheme(theme: 'p1' \| 'p2'): void` | 動態切換介面主題，傳入無效值自動回退到 `'p1'` |
+
+### 事件
+
+使用 `chat.on(event, handler)` 監聽。
+
+| 事件 | Payload | 說明 |
+|------|---------|------|
+| `ready` | — | Widget 掛載完成，可開始互動 |
+
+### CSS 自訂參數
+
+Widget 使用 Shadow DOM 掛載，可在宿主元素的 CSS 中覆寫下列 CSS 自訂屬性來調整佈局：
+
+| 參數 | 預設值 | 說明 |
+|------|--------|------|
+| `--meowmeow-z-index` | `auto` | 宿主元素的 `z-index` |
+| `--meowmeow-mobile-preview-bottom` | `56px` | Mobile：預覽訊息條的底部距離 |
+| `--meowmeow-mobile-room-top` | `313px` | Mobile：聊天室面板的頂部距離 |
+| `--meowmeow-desktop-toggle-size` | `70px` | Desktop：開關按鈕的尺寸（寬高） |
+| `--meowmeow-desktop-toggle-right` | `200px` | Desktop：開關按鈕距右側的距離 |
+| `--meowmeow-desktop-toggle-bottom` | `250px` | Desktop：開關按鈕距底部的距離 |
+| `--meowmeow-desktop-room-width` | `375px` | Desktop：聊天室面板的寬度 |
+| `--meowmeow-desktop-room-height` | `586px` | Desktop：聊天室面板的高度 |
+
+```css
+meowmeow-widget {
+  --meowmeow-z-index: 1000;
+  --meowmeow-desktop-toggle-right: 32px;
+  --meowmeow-desktop-toggle-bottom: 32px;
+}
+```
+
+---
+
+## 無頭模式（`MeowMeowClient`）
+
+若不需要內建 UI，可直接使用 `MeowMeowClient`。
+
+```ts
+import { MeowMeowClient } from '@sentinel-it/meowmeow-sdk'
+
+const client = new MeowMeowClient({
+  token: 'YOUR_JWT_TOKEN',
+  onTokenRefresh: async () => fetchNewToken(),
+})
+
+const result = await client.join('YOUR_ROOM_ID')
+if (!result.ok) {
+  console.error('加入失敗：', result.reason)
+  return
+}
+
+const { room } = result
+
+room.on('message', (msg) => {
+  if (msg.pending) return       // 樂觀更新，等待伺服器確認
+  if (msg.errorCode) return     // 傳送失敗
+  console.log(msg.userName, msg.content)
+})
+
+// 頁面卸載時釋放資源
+client.dispose()
+```
+
+### 初始化選項
+
+| 選項 | 型別 | 必填 | 說明 |
+|------|------|:----:|------|
+| `token` | `string` | ✓ | 使用者 JWT Token |
+| `onTokenRefresh` | `() => Promise<string>` | | Token 刷新回呼 |
+
+### 方法
+
+| 方法 | 說明 |
+|------|------|
+| `join(roomId): Promise<JoinResult>` | 建立連線並加入聊天室，不拋出例外，以 `result.ok` 判斷成功 |
+| `leaveRoom(): Promise<LeaveResult>` | 離開聊天室（WebSocket 連線保留），不拋出例外 |
+| `dispose(): void` | 關閉連線並釋放所有資源 |
+
+**`JoinResult`**
+
+```ts
+type JoinResult =
+  | { ok: true; room: Room }
+  | { ok: false; reason: JoinFailReason }
+
+type JoinFailReason =
+  | 'skipped'           // 被後續操作取代
+  | 'timeout'           // 等待回應逾時
+  | 'disconnected'      // 連線中斷且不重連
+  | 'disposed'          // client 已被 dispose
+  | 'room_unavailable'  // 加入期間聊天室變為不可用
+  | WsErrorCode         // 伺服器回傳錯誤（如 ROOM_NOT_FOUND）
+```
+
+**`LeaveResult`**
+
+```ts
+type LeaveResult =
+  | { ok: true }
+  | { ok: false; reason: LeaveFailReason }
+
+type LeaveFailReason =
+  | 'skipped'       // 被後續操作取代
+  | 'disconnected'  // 連線中斷且不重連
+  | 'disposed'      // client 已被 dispose
+  | WsErrorCode     // 伺服器回傳錯誤
+```
+
+### 屬性
+
+| 屬性 | 型別 | 說明 |
+|------|------|------|
+| `connectionStatus` | `ConnectionStatus` | 目前連線狀態 |
+| `currentUser` | `User \| null` | 目前已連線的使用者資訊 |
+| `currentRoomId` | `string \| null` | 目前所在的聊天室 ID |
+| `isMuted` | `boolean` | 是否被禁言 |
+| `mutedUntil` | `string \| null` | 禁言到期時間（ISO 8601） |
+| `isBanned` | `boolean` | 是否被封禁 |
+
+### 事件
+
+使用 `client.on(event, handler)` 監聽。
+
+| 事件 | Payload | 說明 |
+|------|---------|------|
+| `connected` | `{ user }` | WebSocket 連線成功 |
+| `disconnected` | `{ reason, willReconnect }` | 連線斷開 |
+| `reconnecting` | `{ attempt }` | 正在重新連線，`attempt` 為第幾次嘗試 |
+| `reconnected` | — | 重連成功 |
+| `banned` | `{ until }` | 使用者被封禁 |
+| `unbanned` | — | 封禁解除 |
+| `room_unavailable` | `{ roomId }` | 聊天室已不可用，已退回 lobby（WebSocket 連線保留） |
+| `error` | `{ code, message }` | 發生錯誤 |
+
+---
+
+## Room — 聊天室操作
+
+`client.join()` 回傳的 `Room` 實例，用於發送訊息與監聽聊天室事件。
+
+### 屬性
+
+| 屬性 | 型別 | 說明 |
+|------|------|------|
+| `id` | `string` | 聊天室唯一識別碼 |
+| `name` | `string` | 聊天室顯示名稱 |
+| `messages` | `Message[]` | 目前已載入的訊息列表 |
+| `hasMore` | `boolean` | 是否有更早的歷史訊息可載入 |
+| `cooldownSeconds` | `number` | 發送訊息冷卻秒數（0 表示無限制） |
+| `greetingMessage` | `string \| null` | 加入時的歡迎訊息 |
+| `stickerPacks` | `StickerPack[]` | 此聊天室可用的貼圖包列表 |
+| `isDisposed` | `boolean` | 是否已失效（換房間或斷線後舊的 Room 會被標記） |
+
+### 方法
+
+| 方法 | 說明 |
+|------|------|
+| `send(content): Promise<void>` | 發送文字訊息（樂觀更新） |
+| `sendSticker({ packId, stickerId }): Promise<void>` | 發送貼圖（樂觀更新） |
+
+### 事件
+
+使用 `room.on(event, handler)` 監聽。
+
+| 事件 | Payload | 說明 |
+|------|---------|------|
+| `message` | `Message` | 收到新訊息（含樂觀更新與失敗訊息） |
+| `presence` | `{ type, user, onlineCount }` | 使用者加入或離開 |
+| `muted` | `{ until }` | 使用者被禁言 |
+| `unmuted` | — | 禁言解除 |
+| `room_updated` | `{ cooldownSeconds }` | 聊天室設定更新 |
+
+---
+
+## 錯誤碼
+
+| 錯誤碼 | 說明 |
+|--------|------|
+| `TOKEN_INVALID` | Token 無效或已過期 |
+| `FORBIDDEN` | 無操作權限 |
+| `USER_MUTED` | 使用者已被禁言 |
+| `USER_BANNED` | 使用者已被封禁 |
+| `ROOM_NOT_FOUND` | 房間不存在 |
+| `CHAT_MESSAGE_BLOCKED` | 訊息被過濾攔截 |
+| `INTERNAL_SERVER_ERROR` | 伺服器內部錯誤 |
+| `TOKEN_REFRESH_FAILED` | Token 刷新失敗 |