@sentinel-it/meowmeow-sdk 0.1.0-rc.7f74b8d

package/dist/index.d.ts

@@ -0,0 +1,612 @@
+export declare type ClientErrorCode = 'WS_ERROR' | 'WS_MESSAGE_ERROR' | 'TOKEN_REFRESH_FAILED' | 'JOIN_ROOM_FAILED';
+
+/** `MeowMeowClient` 可監聽的事件與其 payload 型別對應表 */
+export declare interface ClientEventMap {
+    /** WebSocket 連線建立，伺服器已確認身份 */
+    connected: {
+        user: User;
+    };
+    /** 連線中斷；`willReconnect` 為 true 時 SDK 會自動重連 */
+    disconnected: {
+        reason: DisconnectReason;
+        willReconnect: boolean;
+    };
+    /** 目前所在的聊天室已不可用，已退回 lobby，WS 連線保留 */
+    room_unavailable: {
+        roomId: string;
+    };
+    /** 正在嘗試重新連線，`attempt` 為目前第幾次嘗試 */
+    reconnecting: {
+        attempt: number;
+    };
+    /** 重連成功 */
+    reconnected: void;
+    /** 目前使用者被禁言，`until` 為禁言到期時間（ISO 8601），永久禁言為 null */
+    muted: {
+        until: string | null;
+    };
+    /** 目前使用者的禁言已解除 */
+    unmuted: void;
+    /** 目前使用者被封禁，`until` 為解封時間（ISO 8601），永久封禁為 null */
+    banned: {
+        until: string | null;
+    };
+    /** 目前使用者的封禁已解除 */
+    unbanned: void;
+    /** SDK 內部錯誤，`code` 為錯誤代碼 */
+    error: {
+        code: ClientErrorCode;
+        message: string;
+    };
+}
+
+declare interface ConnectionApi {
+    connect(): Promise<void>;
+    disconnect(reason?: DisconnectReason): void;
+    joinRoom(roomId: string): Promise<WsRequestMap['join_room']['res'] & {
+        seq: number;
+    }>;
+    leaveRoom(roomId: string): Promise<void>;
+    sendMessage(roomId: string, payload: SendMessagePayload): Promise<void>;
+    getMessages(roomId: string, options?: GetMessagesOptions): Promise<MessagesResult>;
+}
+
+/** WebSocket 連線狀態 */
+export declare type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+
+/** 連線斷開原因 */
+export declare type DisconnectReason = 'room_unavailable' | 'connection_replaced' | 'ping_timeout' | 'connected_timeout' | 'room_joined_timeout' | 'token_refresh_failed' | 'fetch_ticket_failed' | 'reconnect_failed' | 'connection_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;
+}
+
+declare type JoinFailReason = 'skipped' | 'timeout' | 'disconnected' | 'disposed' | 'room_unavailable' | WsErrorCode;
+
+declare type JoinResult = {
+    ok: true;
+    room: Room;
+} | {
+    ok: false;
+    reason: JoinFailReason;
+};
+
+declare type LeaveFailReason = 'skipped' | 'disconnected' | 'disposed' | WsErrorCode;
+
+declare type LeaveResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: LeaveFailReason;
+};
+
+/**
+ * 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 vueApp;
+    private hostElement;
+    private meowmeowStore;
+    private uiStore;
+    constructor(options: MeowMeowOptions);
+    /** 顯示 MeowMeow */
+    show(): void;
+    /** 加入聊天室 */
+    join(roomId: string): Promise<void>;
+    /** 隱藏 MeowMeow */
+    hide(): void;
+    /**
+     * 動態設定語系
+     * @param locale en-US 英語 ( 預設 )
+     * @param locale zh-Hant 繁體中文
+     * @param locale zh-Hans 簡體中文
+     * @param locale vi-VN 越南語
+     * @param locale th-TH 泰語
+     * @param locale id-ID 印尼語
+     * @param locale pt-BR 葡萄牙語 ( 巴西 )
+     * @param locale my-MM 緬甸語
+     * @param locale hi-IN 印地語
+     * @param locale ru-RU 俄語
+     * @param locale ko-KR 韓國語
+     * @param locale ms-MY 馬來語
+     * @param locale fil-PH 菲律賓語
+     */
+    setLocale(locale?: string): void;
+    /**
+     * 動態設定主題
+     * @param theme p1 ( 預設 )
+     * @param theme p2
+     */
+    setTheme(theme?: Theme): 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` | — | 重連成功 |
+ * | `banned` | `{ until }` | 被封禁 |
+ * | `unbanned` | — | 封禁解除 |
+ * | `error` | `{ code, message }` | SDK 內部錯誤 |
+ *
+ * @example
+ * ```ts
+ * const client = new MeowMeowClient({ token: '...' })
+ * const result = await client.join('room-1')
+ * if (result.ok) result.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 _currentRoomId;
+    private currentRoom;
+    private _pendingJoinSettle;
+    private _pendingJoinTimer;
+    private _preJoinBuffer;
+    private _pendingLeaveSettle;
+    private _nextOp;
+    private _connectionStatus;
+    private _currentUser;
+    private _isMuted;
+    private _mutedUntil;
+    private _isBanned;
+    private _retryAfterSeconds;
+    private readonly _userStateFilter;
+    /** 目前的連線狀態 */
+    get connectionStatus(): ConnectionStatus;
+    /** 目前登入的使用者，連線前為 null */
+    get currentUser(): User | null;
+    /** 目前使用者是否被禁言 */
+    get isMuted(): boolean;
+    /** 禁言到期時間（ISO 8601），未被禁言時為 null */
+    get mutedUntil(): string | null;
+    /** 目前使用者是否被封禁 */
+    get isBanned(): boolean;
+    /** 發送過於頻繁時需等待的秒數（0 表示無需等待） */
+    get retryAfterSeconds(): number;
+    /** 目前所在的聊天室 ID，未入桌時為 null */
+    get currentRoomId(): string | null;
+    constructor(options: MeowMeowClientOptions);
+    /**
+     * 建立連線並加入聊天室，回傳 {@link JoinResult}，不拋出例外。
+     *
+     * 狀態機行為：
+     * - joining / leaving → 排隊（最後一次生效），被覆蓋的 `{ ok: false, reason: 'skipped' }`
+     * - room 同桌 → 立即 `{ ok: true, room }`
+     * - room 不同桌 / lobby → 直接開始 join（server 支援 switch）
+     */
+    join(roomId: string): Promise<JoinResult>;
+    /**
+     * 離開聊天室（ws 連線保留），回傳 {@link LeaveResult}，不拋出例外。
+     *
+     * 狀態機行為：
+     * - joining / leaving → 排隊（最後一次生效），被覆蓋的 `{ ok: false, reason: 'skipped' }`
+     * - lobby → 立即 `{ ok: true }`
+     * - room → 開始 leave
+     */
+    leaveRoom(): Promise<LeaveResult>;
+    private disconnect;
+    /** 斷開連線並移除所有事件監聽器，釋放資源。頁面卸載時應呼叫此方法。 */
+    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 */
+    private onRoomJoined;
+    /* Excluded from this release type: onRoomUpdated */
+    /* Excluded from this release type: onRoomUnavailable */
+    /* 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 _startJoin;
+    private _startLeave;
+    private _doLeaveRoom;
+    private _queueJoin;
+    private _queueLeave;
+    private _runNextOp;
+    private _doJoinRoom;
+    private _toJoinFailReason;
+    private _toLeaveFailReason;
+    private _settleAll;
+    private _startJoinTimer;
+    private _clearPendingJoin;
+    private _clearPendingLeave;
+}
+
+/** MeowMeowClient 建構所需的設定選項 */
+export declare interface MeowMeowClientOptions {
+    /** 用於驗證身份的 JWT token */
+    token: string;
+    /**
+     * Token 過期時的刷新回調，應回傳新的有效 token。
+     * 若未提供，token 過期後連線將直接斷開。
+     */
+    onTokenRefresh?: () => Promise<string>;
+}
+
+export declare interface MeowMeowOptions {
+    token: string;
+    locale?: string;
+    theme?: Theme;
+    title?: string | Record<string, string>;
+    onTokenRefresh?: () => Promise<string>;
+}
+
+/** 聊天室訊息 */
+export declare type Message = (MessageBase & {
+    type: 'text' | 'system';
+    content: string;
+}) | (MessageBase & {
+    type: 'sticker';
+    content: {
+        packId: string;
+        stickerId: string;
+        url: string;
+    };
+});
+
+declare type MessageBase = {
+    /** 訊息唯一識別碼 */
+    id: string;
+    /** 訊息的序號（用於排序） */
+    seq: number;
+    /** 同一 seq 下的子序號 */
+    subSeq: number;
+    /** 發送者的使用者 ID */
+    userId: string;
+    /** 發送者的顯示名稱 */
+    userName: string;
+    /** 發送者的頭像 URL，無頭像時為 null */
+    avatar: string | null;
+    /** 訊息建立時間（ISO 8601 格式） */
+    createdAt: string;
+    /** 傳送失敗時的錯誤代碼 */
+    errorCode?: WsErrorCode;
+    /** 客戶端本地參考 ID，用於對應樂觀更新 */
+    clientRef?: string | null;
+    /** 是否為尚未確認的樂觀更新訊息 */
+    pending?: boolean;
+};
+
+declare type MessageSender = {
+    id: string;
+    name: string;
+    avatar?: string | null;
+};
+
+/** `getMessages` / `loadMoreMessages` 的回傳結果 */
+declare interface MessagesResult {
+    /** 取得的訊息列表（依序號排序） */
+    messages: Message[];
+    /** 是否還有更早的訊息可以載入 */
+    hasMore: boolean;
+}
+
+/** server push event → handler 收到的完整資料型別對應表（outer envelope 欄位已攤平） */
+declare interface PushEventMap {
+    connected: {
+        seq: number;
+        user: User & {
+            status: 'normal' | 'muted' | 'banned';
+        };
+    };
+    room_updated: {
+        seq: number;
+        roomId: string;
+        cooldownSeconds: number;
+    };
+    presence: {
+        seq: number;
+        roomId: string;
+        type: 'join' | 'leave';
+        user: User;
+        onlineCount: number;
+    };
+    muted: {
+        seq: number;
+        roomId?: string;
+        until: string | null;
+    };
+    unmuted: {
+        seq: number;
+        roomId?: string;
+    };
+    banned: {
+        seq: number;
+        roomId?: string;
+        until: string | null;
+    };
+    unbanned: {
+        seq: number;
+        roomId?: string;
+    };
+    warned: {
+        seq: number;
+        roomId: string;
+        reason?: string;
+    };
+    room_unavailable: {
+        seq: number;
+        roomId: string;
+    };
+    connection_replaced: {
+        seq: number;
+    };
+}
+
+declare type RawMessagePayload = {
+    id: string;
+    type: 'text' | 'system';
+    sender: MessageSender;
+    body: {
+        content: string;
+    };
+    createdAt: string;
+    clientRef?: string | null;
+} | {
+    id: string;
+    type: 'sticker';
+    sender: MessageSender;
+    body: {
+        packId: string;
+        stickerId: string;
+        url: string;
+    };
+    createdAt: string;
+    clientRef?: string | null;
+};
+
+/**
+ * 代表一個已加入的聊天室，提供發送訊息、載入歷史紀錄與監聽即時事件的能力。
+ * 由 {@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 readonly client;
+    private _cooldownSeconds;
+    private _greetingMessage;
+    private _stickerPacks;
+    private _messages;
+    private _hasMore;
+    private _isDisposed;
+    /** 發送訊息冷卻秒數（0 表示無限制） */
+    get cooldownSeconds(): number;
+    /** 加入房間時的歡迎訊息，無則為 null */
+    get greetingMessage(): string | null;
+    /** 此聊天室可用的貼圖包列表 */
+    get stickerPacks(): StickerPack[];
+    /** 目前已載入的訊息列表（依序號排序） */
+    get messages(): Message[];
+    /** 是否還有更早的歷史訊息可以載入 */
+    get hasMore(): boolean;
+    /** 此 Room 是否已失效（換房間或斷線後） */
+    get isDisposed(): boolean;
+    /* Excluded from this release type: __constructor */
+    /**
+     * 發送文字訊息。採樂觀更新，訊息會立即出現在 `messages` 並觸發 `message` 事件；
+     * 若伺服器回傳錯誤，該訊息的 `errorCode` 會被設定且 `pending` 設為 false。
+     * @param content 訊息文字內容
+     * @param sender 發送者資訊
+     */
+    send(content: string): Promise<void>;
+    /**
+     * 發送貼圖訊息，行為同 {@link send}（樂觀更新）。
+     * @param options 貼圖包 ID 與貼圖代碼
+     * @param sender 發送者資訊
+     */
+    sendSticker(options: {
+        packId: string;
+        stickerId: string;
+    }): Promise<void>;
+    /* Excluded from this release type: dispose */
+    /* Excluded from this release type: _setCooldownSeconds */
+    /* Excluded from this release type: _setGreetingMessage */
+    /* Excluded from this release type: _setStickerPacks */
+    /* 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: _handleWarned */
+    /* Excluded from this release type: reload */
+    /* 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;
+    };
+    /** 聊天室設定更新（目前僅有冷卻秒數） */
+    room_updated: {
+        cooldownSeconds: number;
+    };
+    /** 訊息重新載入完成（初次加入或重連後） */
+    messages_reloaded: void;
+}
+
+declare type SendMessagePayload = {
+    type: 'text';
+    body: {
+        content: string;
+    };
+    clientRef: string;
+} | {
+    type: 'sticker';
+    body: {
+        packId: string;
+        stickerId: string;
+    };
+    clientRef: string;
+};
+
+/** 貼圖包資訊 */
+export declare interface StickerPack {
+    /** 貼圖包唯一識別碼 */
+    id: string;
+    /** 貼圖包圖示 URL */
+    iconUrl: string;
+    /** 貼圖包名稱 */
+    name: string;
+    /** 包含的貼圖列表 */
+    stickers: Array<{
+        id: string;
+        url: string;
+    }>;
+}
+
+declare type Theme = typeof THEMES[number];
+
+declare const THEMES: readonly ["p1", "p2"];
+
+/** 使用者資訊 */
+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' | 'STICKER_NOT_AVAILABLE';
+
+/** Client → Server request/response 型別對應表 */
+declare interface WsRequestMap {
+    ping: {
+        req: {
+            type: 'request';
+            action: 'ping';
+        };
+        res: undefined;
+    };
+    join_room: {
+        req: {
+            type: 'request';
+            action: 'join_room';
+            roomId: string;
+        };
+        res: {
+            seq: number;
+            onlineCount: number;
+            latestMessageId: string;
+            greetingMessage?: string;
+            cooldownSeconds: number;
+            retryAfterSeconds: number;
+            stickerPacks: StickerPack[];
+        };
+    };
+    leave_room: {
+        req: {
+            type: 'request';
+            action: 'leave_room';
+            roomId: string;
+        };
+        res: {
+            left: boolean;
+            roomId: string;
+        };
+    };
+    get_messages: {
+        req: {
+            type: 'request';
+            action: 'get_messages';
+            roomId: string;
+            payload: {
+                limit: number;
+                before?: string;
+            };
+        };
+        res: {
+            messages: RawMessagePayload[];
+            hasMore: boolean;
+        };
+    };
+    send_message: {
+        req: {
+            type: 'request';
+            action: 'send_message';
+            roomId: string;
+            payload: SendMessagePayload;
+        };
+        res: undefined;
+    };
+}
+
+export { }