@sentinel-it/meowmeow-sdk 1.0.0-rc.b28bb80

package/README.md

@@ -0,0 +1,202 @@
+# 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',
+  room: 'YOUR_ROOM_ID',
+  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 |
+| `room` | `string` | ✓ | 房間 ID |
+| `locale` | `string` | | 介面語言，預設 `'en'`，支援 `en`、`id`、`vi`、`tl` |
+| `title` | `string \| Record<string, string>` | | 聊天室標題，可傳入語系對照物件 |
+| `zIndex` | `number \| 'auto'` | | Widget 層級，預設 `'auto'` |
+| `onTokenRefresh` | `() => Promise<string>` | | Token 刷新回呼 |
+
+`title` 可傳入語系對照物件：
+
+```ts
+title: {
+  en: 'Support Chat',
+  id: 'Obrolan Dukungan',
+  vi: 'Hỗ trợ trực tuyến',
+}
+```
+
+### 方法
+
+| 方法 | 說明 |
+|------|------|
+| `mount(): Promise<void>` | 掛載 Widget 至 DOM |
+| `unmount(): void` | 卸載並釋放資源 |
+| `show(): void` | 顯示 Widget |
+| `hide(): void` | 隱藏 Widget |
+| `setLocale(locale: string): void` | 動態切換介面語言（`en`、`id`、`vi`、`tl`） |
+
+### 事件
+
+使用 `chat.on(event, handler)` 監聽。
+
+| 事件 | Payload | 說明 |
+|------|---------|------|
+| `ready` | — | Widget 掛載完成，可開始互動 |
+
+---
+
+## 無頭模式（`MeowMeowClient`）
+
+若不需要內建 UI，可直接使用 `MeowMeowClient`。
+
+```ts
+import { MeowMeowClient } from '@sentinel-it/meowmeow-sdk'
+
+const client = new MeowMeowClient({
+  token: 'YOUR_JWT_TOKEN',
+  roomId: 'YOUR_ROOM_ID',
+  onTokenRefresh: async () => fetchNewToken(),
+})
+
+const room = await client.join()
+
+room.on('message', (msg) => {
+  if (msg.pending) return       // 樂觀更新，等待伺服器確認
+  if (msg.errorCode) return     // 傳送失敗
+  console.log(msg.userName, msg.content)
+})
+
+// 頁面卸載時釋放資源
+client.dispose()
+```
+
+### 初始化選項
+
+| 選項 | 型別 | 必填 | 說明 |
+|------|------|:----:|------|
+| `token` | `string` | ✓ | 使用者 JWT Token |
+| `roomId` | `string` | ✓ | 要加入的聊天室 ID |
+| `onTokenRefresh` | `() => Promise<string>` | | Token 刷新回呼 |
+
+### 方法
+
+| 方法 | 說明 |
+|------|------|
+| `join(): Promise<Room>` | 建立連線並加入聊天室，回傳 `Room` 實例 |
+| `dispose(): void` | 關閉連線並釋放所有資源 |
+
+### 屬性
+
+| 屬性 | 型別 | 說明 |
+|------|------|------|
+| `currentUser` | `User \| null` | 目前已連線的使用者資訊 |
+
+### 事件
+
+使用 `client.on(event, handler)` 監聽。
+
+| 事件 | Payload | 說明 |
+|------|---------|------|
+| `connected` | `{ user }` | WebSocket 連線成功 |
+| `disconnected` | `{ reason, willReconnect }` | 連線斷開 |
+| `reconnecting` | `{ attempt }` | 正在重新連線，`attempt` 為第幾次嘗試 |
+| `reconnected` | — | 重連成功 |
+| `room_joined` | `{ onlineUsers, cooldownSeconds, greetingMessage? }` | 成功加入聊天室 |
+| `banned` | `{ until }` | 使用者被封禁 |
+| `unbanned` | — | 封禁解除 |
+| `error` | `{ code, message }` | 發生錯誤 |
+
+---
+
+## Room — 聊天室操作
+
+`client.join()` 回傳的 `Room` 實例，用於發送訊息與監聽聊天室事件。
+
+### 方法
+
+| 方法 | 說明 |
+|------|------|
+| `send(content, sender): Promise<void>` | 發送文字訊息（樂觀更新） |
+| `sendSticker({ packId, code }, sender): 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 刷新失敗 |
+

package/dist/index.d.ts

@@ -0,0 +1,431 @@
+export declare type ClientErrorCode = 'WS_ERROR' | 'WS_MESSAGE_ERROR' | 'TOKEN_REFRESH_FAILED';
+
+/** `MeowMeowClient` 可監聽的事件與其 payload 型別對應表 */
+export declare interface ClientEventMap {
+    /** WebSocket 連線建立，伺服器已確認身份 */
+    connected: {
+        user: User;
+    };
+    /** 連線中斷；`willReconnect` 為 true 時 SDK 會自動重連 */
+    disconnected: {
+        reason: DisconnectReason;
+        willReconnect: boolean;
+    };
+    /** 正在嘗試重新連線，`attempt` 為目前第幾次嘗試 */
+    reconnecting: {
+        attempt: number;
+    };
+    /** 重連成功 */
+    reconnected: void;
+    /** 成功加入聊天室，`join()` 回傳的 Room 即可使用 */
+    room_joined: {
+        onlineUsers: User[];
+        cooldownSeconds: number;
+        greetingMessage?: string;
+    };
+    /** 目前使用者被封禁，`until` 為解封時間（ISO 8601），永久封禁為 null */
+    banned: {
+        until: string | null;
+    };
+    /** 目前使用者的封禁已解除 */
+    unbanned: void;
+    /** SDK 內部錯誤，`code` 為錯誤代碼 */
+    error: {
+        code: ClientErrorCode;
+        message: string;
+    };
+}
+
+declare interface ConnectionApi {
+    connect(roomId: string): Promise<void>;
+    disconnect(reason?: DisconnectReason): void;
+    sendMessage(roomId: string, payload: SendMessagePayload): Promise<void>;
+    getMessages(roomId: string, options?: GetMessagesOptions): Promise<MessagesResult>;
+}
+
+/** WebSocket 連線狀態 */
+export declare type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'joined' | 'reconnecting';
+
+/** 連線斷開原因 */
+export declare type DisconnectReason = 'room_unavailable' | 'connection_replaced' | 'ping_timeout' | 'connected_timeout' | 'room_joined_timeout' | 'token_refresh_failed' | 'fetch_ticket_failed' | 'reconnect_failed' | 'user_banned' | (string & {});
+
+/** 型別安全的事件發送器，`MeowMeowClient` 與 `Room` 皆繼承此類別。 */
+declare class EventEmitter<TEventMap extends object = Record<string, unknown>> {
+    private _listeners;
+    /**
+     * 註冊事件監聽器。
+     * @param event 事件名稱
+     * @param handler 事件處理函式
+     */
+    on<E extends keyof TEventMap>(event: E, handler: (payload: TEventMap[E]) => void): void;
+    /**
+     * 移除已註冊的事件監聽器。
+     * @param event 事件名稱
+     * @param handler 要移除的處理函式（需與 `on` 傳入的參考相同）
+     */
+    off<E extends keyof TEventMap>(event: E, handler: (payload: TEventMap[E]) => void): void;
+    protected emit<E extends keyof TEventMap>(event: E, ...args: TEventMap[E] extends void ? [] : [payload: TEventMap[E]]): void;
+    /** 移除所有事件的所有監聽器。 */
+    removeAllListeners(): void;
+}
+
+/** 取得歷史訊息的查詢選項 */
+declare interface GetMessagesOptions {
+    /** 單次最多取幾筆 */
+    limit: number;
+    /** 取在此訊息 ID 之前的訊息（用於分頁） */
+    before?: string;
+}
+
+/**
+ * MeowMeow 聊天室 UI Widget。
+ * 掛載後在頁面上顯示完整的聊天室介面（預覽泡泡 + 聊天室視窗）。
+ *
+ * @example
+ * ```ts
+ * const chat = new MeowMeow({ token: '...', room: 'room-1', locale: 'zh' })
+ * await chat.mount()
+ * chat.show()
+ * ```
+ */
+export declare class MeowMeow extends EventEmitter {
+    private readonly options;
+    private readonly client;
+    private vueApp;
+    private hostElement;
+    private meowmeowStore;
+    private uiStore;
+    private localeSet;
+    constructor(options: MeowMeowOptions);
+    /** 顯示 MeowMeow */
+    show(): void;
+    /** 隱藏 MeowMeow */
+    hide(): void;
+    /**
+     * 動態設定語系
+     * @param locale 目前僅支援 en / id / vi / tl
+     */
+    setLocale(locale: string): void;
+    /**
+     * 建立 Shadow DOM、初始化 Vue 應用並掛載到 `document.body`。
+     * 掛載後聊天室預設為隱藏，需呼叫 {@link show} 顯示。
+     */
+    mount(): Promise<void>;
+    /** 卸載 Vue 應用、移除 DOM 元素並釋放所有資源。 */
+    unmount(): void;
+}
+
+/**
+ * MeowMeow SDK 的核心 Client，負責管理 WebSocket 連線與聊天室生命週期。
+ *
+ * @remarks
+ * 可透過 `on(event, handler)` 監聽以下事件：
+ *
+ * | 事件 | Payload | 說明 |
+ * |------|---------|------|
+ * | `connected` | `{ user }` | 連線建立並通過身份驗證 |
+ * | `disconnected` | `{ reason, willReconnect }` | 連線中斷 |
+ * | `reconnecting` | `{ attempt }` | 正在嘗試重連 |
+ * | `reconnected` | — | 重連成功 |
+ * | `room_joined` | `{ onlineUsers, cooldownSeconds, greetingMessage? }` | 成功加入聊天室 |
+ * | `banned` | `{ until }` | 被封禁 |
+ * | `unbanned` | — | 封禁解除 |
+ * | `error` | `{ code, message }` | SDK 內部錯誤 |
+ *
+ * @example
+ * ```ts
+ * const client = new MeowMeowClient({ token: '...', roomId: 'room-1' })
+ * const room = await client.join()
+ * room.on('message', msg => console.log(msg))
+ * client.on('disconnected', ({ reason }) => console.warn('disconnected:', reason))
+ * ```
+ */
+export declare class MeowMeowClient extends EventEmitter<ClientEventMap> {
+    private readonly connectionApi;
+    private readonly roomId;
+    private currentRoom;
+    private _pendingJoinPromise;
+    private _pendingJoinResolve;
+    private _pendingJoinReject;
+    private _pendingJoinTimer;
+    private _connectionStatus;
+    private _currentUser;
+    private _isMuted;
+    private _mutedUntil;
+    private _isBanned;
+    private readonly _userStateFilter;
+    private readonly _onlineUsersFilter;
+    /** 目前的連線狀態 */
+    get connectionStatus(): ConnectionStatus;
+    /** 目前登入的使用者，連線前為 null */
+    get currentUser(): User | null;
+    /** 目前使用者是否被禁言 */
+    get isMuted(): boolean;
+    /** 禁言到期時間（ISO 8601），未被禁言時為 null */
+    get mutedUntil(): string | null;
+    /** 目前使用者是否被封禁 */
+    get isBanned(): boolean;
+    constructor(options: MeowMeowClientOptions);
+    /**
+     * 建立連線並加入聊天室，回傳 {@link Room} 實例。
+     *
+     * 若連線或加入超過 10 秒未完成，Promise 將 reject。
+     * 重複呼叫時回傳同一個 pending Promise，不會建立多條連線。
+     */
+    join(): Promise<Room>;
+    /**
+     * 主動斷開 WebSocket 連線。
+     * @param reason 斷線原因，預設為 `'manual disconnect'`
+     */
+    disconnect(reason?: DisconnectReason): void;
+    /** 斷開連線並移除所有事件監聽器，釋放資源。頁面卸載時應呼叫此方法。 */
+    dispose(): void;
+    /* Excluded from this release type: onConnected */
+    /* Excluded from this release type: onDisconnected */
+    /* Excluded from this release type: onReconnecting */
+    /* Excluded from this release type: onReconnected */
+    /* Excluded from this release type: onRoomJoined */
+    /* Excluded from this release type: onRoomUpdated */
+    /* Excluded from this release type: onMessage */
+    /* Excluded from this release type: onPresence */
+    /* Excluded from this release type: onMuted */
+    /* Excluded from this release type: onUnmuted */
+    /* Excluded from this release type: onBanned */
+    /* Excluded from this release type: onUnbanned */
+    /* Excluded from this release type: onWarned */
+    /* Excluded from this release type: onError */
+    private _startJoinTimer;
+    private _clearPendingJoin;
+}
+
+/** MeowMeowClient 建構所需的設定選項 */
+export declare interface MeowMeowClientOptions {
+    /** 用於驗證身份的 JWT token */
+    token: string;
+    /** 要加入的聊天室 ID */
+    roomId: string;
+    /**
+     * Token 過期時的刷新回調，應回傳新的有效 token。
+     * 若未提供，token 過期後連線將直接斷開。
+     */
+    onTokenRefresh?: () => Promise<string>;
+}
+
+export declare interface MeowMeowOptions {
+    token: string;
+    room: string;
+    locale?: string;
+    title?: string | Record<string, string> | 'CHAT ROOM';
+    zIndex?: number | 'auto';
+    onTokenRefresh?: () => Promise<string>;
+}
+
+/** 聊天室訊息 */
+export declare interface Message {
+    /** 訊息唯一識別碼 */
+    id: string;
+    /** 訊息的序號（用於排序） */
+    seq: number;
+    /** 同一 seq 下的子序號 */
+    subSeq: number;
+    /** 訊息類型：文字、貼圖或系統訊息 */
+    type: 'text' | 'sticker' | 'system';
+    /** 訊息內容文字 */
+    content: string;
+    /** 發送者的使用者 ID */
+    userId: string;
+    /** 發送者的顯示名稱 */
+    userName: string;
+    /** 發送者的頭像 URL，無頭像時為 null */
+    avatar: string | null;
+    /** 訊息建立時間（ISO 8601 格式） */
+    createdAt: string;
+    /** 訊息附帶的額外資料（例如貼圖資訊） */
+    metadata: {
+        sticker?: {
+            packId: string;
+            code: string;
+            url: string;
+        };
+    } | null;
+    /** 傳送失敗時的錯誤代碼 */
+    errorCode?: WsErrorCode;
+    /** 客戶端本地參考 ID，用於對應樂觀更新 */
+    clientRef?: string | null;
+    /** 是否為尚未確認的樂觀更新訊息 */
+    pending?: boolean;
+}
+
+/** `getMessages` / `loadMoreMessages` 的回傳結果 */
+declare interface MessagesResult {
+    /** 取得的訊息列表（依序號排序） */
+    messages: Message[];
+    /** 是否還有更早的訊息可以載入 */
+    hasMore: boolean;
+}
+
+/** push event → payload 型別對應表（payload 為 undefined 表示該事件無附帶資料） */
+declare interface PushEventPayloadMap {
+    connected: {
+        roomId?: string;
+        user: User & {
+            status: 'normal' | 'muted' | 'banned';
+        };
+    };
+    room_joined: {
+        onlineUsers: User[];
+        onlineCount: number;
+        latestMessageId: string;
+        greetingMessage?: string;
+        cooldownSeconds: number;
+    };
+    room_updated: {
+        cooldownSeconds: number;
+    };
+    presence: {
+        type: 'join' | 'leave';
+        user: User;
+        onlineCount: number;
+    };
+    muted: {
+        until: string | null;
+    };
+    unmuted: undefined;
+    banned: {
+        until: string | null;
+    };
+    unbanned: undefined;
+    warned: {
+        reason?: string;
+    };
+    room_unavailable: undefined;
+    connection_replaced: undefined;
+}
+
+/**
+ * 代表一個已加入的聊天室，提供發送訊息、載入歷史紀錄與監聽即時事件的能力。
+ * 由 {@link MeowMeowClient.join} 回傳，不應自行建構。
+ *
+ * @remarks
+ * 可透過 `on(event, handler)` 監聽以下事件：
+ *
+ * | 事件 | Payload | 說明 |
+ * |------|---------|------|
+ * | `message` | {@link Message} | 收到新訊息（含 pending 樂觀更新） |
+ * | `presence` | `{ type, user, onlineCount }` | 使用者加入或離開 |
+ * | `muted` | `{ until }` | 被禁言 |
+ * | `unmuted` | — | 禁言解除 |
+ * | `room_updated` | `{ cooldownSeconds }` | 聊天室設定更新 |
+ */
+export declare class Room extends EventEmitter<RoomEventMap> {
+    /** 聊天室唯一識別碼 */
+    readonly id: string;
+    /** 聊天室顯示名稱 */
+    readonly name: string;
+    private readonly connectionApi;
+    private _onlineUsers;
+    private _cooldownSeconds;
+    private _messages;
+    private _hasMore;
+    /** 發送訊息冷卻秒數（0 表示無限制） */
+    get cooldownSeconds(): number;
+    /** 目前在線的使用者列表 */
+    get onlineUsers(): User[];
+    /** 目前已載入的訊息列表（依序號排序） */
+    get messages(): Message[];
+    /** 是否還有更早的歷史訊息可以載入 */
+    get hasMore(): boolean;
+    /* Excluded from this release type: __constructor */
+    /**
+     * 發送文字訊息。採樂觀更新，訊息會立即出現在 `messages` 並觸發 `message` 事件；
+     * 若伺服器回傳錯誤，該訊息的 `errorCode` 會被設定且 `pending` 設為 false。
+     * @param content 訊息文字內容
+     * @param sender 發送者資訊
+     */
+    send(content: string, sender: User): Promise<void>;
+    /**
+     * 發送貼圖訊息，行為同 {@link send}（樂觀更新）。
+     * @param options 貼圖包 ID 與貼圖代碼
+     * @param sender 發送者資訊
+     */
+    sendSticker(options: {
+        packId: string;
+        code: string;
+    }, sender: User): Promise<void>;
+    /* Excluded from this release type: getMessages */
+    /* Excluded from this release type: loadMoreMessages */
+    /* Excluded from this release type: _setOnlineUsers */
+    /* Excluded from this release type: _setCooldownSeconds */
+    /* Excluded from this release type: _initMessages */
+    /* Excluded from this release type: _handleMessage */
+    /* Excluded from this release type: _handleRoomUpdated */
+    /* Excluded from this release type: _handlePresence */
+    /* Excluded from this release type: _handleMuted */
+    /* Excluded from this release type: _handleUnmuted */
+    /* Excluded from this release type: _handleWarned */
+    /* Excluded from this release type: reset */
+    private _createPendingMessage;
+    private _markFailed;
+    private _insertMessage;
+    private _mergeSorted;
+}
+
+/** `Room` 可監聽的事件與其 payload 型別對應表 */
+export declare interface RoomEventMap {
+    /** 收到新訊息（含樂觀更新的 pending 訊息與伺服器確認後的最終訊息） */
+    message: Message;
+    /** 使用者加入或離開聊天室 */
+    presence: {
+        type: 'join' | 'leave';
+        user: User;
+        onlineCount: number;
+    };
+    /** 目前使用者被禁言，`until` 為禁言到期時間（ISO 8601），永久禁言為 null */
+    muted: {
+        until: string | null;
+    };
+    /** 目前使用者的禁言已解除 */
+    unmuted: void;
+    /** 聊天室設定更新（目前僅有冷卻秒數） */
+    room_updated: {
+        cooldownSeconds: number;
+    };
+}
+
+declare type SendMessagePayload = {
+    type: 'text';
+    content: string;
+    clientRef: string;
+} | {
+    type: 'sticker';
+    packId: string;
+    code: string;
+    clientRef: string;
+};
+
+/** 貼圖包資訊 */
+export declare interface StickerPack {
+    /** 貼圖包唯一識別碼 */
+    id: string;
+    /** 貼圖包名稱 */
+    name: string;
+    /** 包含的貼圖列表 */
+    stickers: Array<{
+        code: string;
+        url: string;
+    }>;
+}
+
+/** 使用者資訊 */
+export declare interface User {
+    /** 使用者唯一識別碼 */
+    id: string;
+    /** 使用者顯示名稱 */
+    name: string;
+    /** 頭像 URL，無頭像時為 null */
+    avatar: string | null;
+}
+
+export declare type WsErrorCode = 'BAD_REQUEST' | 'TOKEN_INVALID' | 'FORBIDDEN' | 'USER_MUTED' | 'USER_BANNED' | 'ROOM_NOT_FOUND' | 'CHAT_MESSAGE_STORE_UNAVAILABLE' | 'CHAT_MESSAGE_BLOCKED' | 'INTERNAL_SERVER_ERROR' | 'INVALID_TYPE' | 'INVALID_MESSAGE_TYPE' | 'MISSING_REF';
+
+export { }