dimsum-chat 0.4.7 → 0.5.1

package/dist/dimsumMessage.d.ts

@@ -1,2 +1,9 @@
 import { Message } from './types';
-export declare function handleMessage(message: Message): Message | undefined;
+/**
+ * Optional context passed to handleMessage for enriching response messages.
+ * Extend this interface when more contextual fields are needed in the future.
+ */
+export interface HandleMessageContext {
+    widgetNickName?: string;
+}
+export declare function handleMessage(message: Message, context?: HandleMessageContext): Message | undefined;

package/dist/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * dimsum-chat — 多平台直播消息解析与 WebSocket 通信工具包。
+ *
+ * 核心能力：
+ * - onMessage：一行代码接入直播间消息
+ * - Parser：跨平台统一消息解析（B站/抖音/快手/AcFun/CHZZK）
+ * - WebSocketManager：WebSocket 连接管理与自动重连
+ *
+ * @module dimsum-chat
+ */
 export { WebSocketManager, getBfaceURL, getWebSocketURL, onMessage } from './websocket';
 export { Parser } from './parser';
 export type { commentParseOptions, abstractLevelOptions } from './parser';

package/dist/parser.d.ts

@@ -1,8 +1,45 @@
 type MessageType = "comment" | "gift" | "follow" | "joinclub" | "like" | "guard" | "superchat" | "enter" | "share" | undefined;
+/**
+ * 多平台直播消息解析器。
+ *
+ * 将各平台（B站/OpenBLive/抖音/快手/AcFun/CHZZK）的原始消息
+ * 统一解析为便于使用的属性访问接口，内置属性值缓存机制。
+ *
+ * @example
+ * ```ts
+ * const parser = new Parser({ type: 'DANMU_MSG', content: '...' })
+ * console.log(parser.platform, parser.userName, parser.comment)
+ * ```
+ *
+ * @see {@link https://dimsum.chat/zh/api/parser.html}
+ */
 declare class Parser {
+    /**
+     * Douyin emoji mappings. Accessible directly without going through CommentBuilder.
+     *
+     * @example
+     * Parser.DouyinEmots.forEach(([emot, url]) => console.log(emot, url));
+     */
+    static readonly DouyinEmots: readonly [string, string][];
+    /**
+     * Bilibili emoji mappings (also used by OpenBLive).
+     *
+     * @example
+     * Parser.BilibiliEmots.forEach(([emot, url]) => console.log(emot, url));
+     */
+    static readonly BilibiliEmots: readonly [string, string][];
+    /**
+     * Kuaishou emoji mappings.
+     *
+     * @example
+     * Parser.KuaishouEmots.forEach(([emot, url]) => console.log(emot, url));
+     */
+    static readonly KuaishouEmots: readonly [string, string][];
     private static douyinGiftGroup;
     private static kuaishouGiftGroup;
+    /** 原始消息类型。 */
     readonly rawType: string;
+    /** 原始消息内容（字符串已自动反序列化为对象）。 */
     readonly rawContent: any;
     private _cachedValues;
     constructor(rawMsg: {
@@ -35,8 +72,11 @@ declare class Parser {
      * @see {@link https://dimsum.chat/zh/api/parser.html#parser-uid}
      */
     get uid(): number | string | undefined;
+    /** 粉丝团/守护团等级。 */
     get clubLevel(): number | undefined;
+    /** 粉丝团/守护团名称。 */
     get clubName(): string | undefined;
+    /** AcFun 守护团所属主播的用户 ID。 */
     get acfunClubUid(): number | undefined;
     /**
      * User subscription status in the current Douyin live room.
@@ -45,7 +85,21 @@ declare class Parser {
      * @see {@link https://dimsum.chat/zh/api/parser.html#parser-douyinsubscribe}
      */
     get douyinSubscribe(): 0 | 1 | 2 | undefined;
+    /**
+     * 用户头像 URL。
+     *
+     * B 站头像存在跨域限制，建议配合 getBfaceURL() 使用。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-avatar}
+     */
     get avatar(): string | undefined;
+    /**
+     * 弹幕聊天内容。
+     *
+     * 当 type 为 comment 或 superchat 时均有值。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-comment}
+     */
     get comment(): string | undefined;
     /**
      * Simple method to construct comments as HTML strings. Useful for rendering comment messages in general.
@@ -64,39 +118,132 @@ declare class Parser {
      */
     CommentBuilder(builder: (comment: string, stickerUrl?: string, emots?: [string, string][]) => string): string | undefined;
     /**
-     * 大航海等级：0-无 3-舰长 2-提督 1-总督
-     * 若type为guard，则为购买的大航海等级
+     * 大航海等级。
+     *
+     * 0=无，3=舰长，2=提督，1=总督。
+     * 当 type 为 guard 时，表示本次购买的大航海等级；
+     * 其他消息类型中表示该用户当前的大航海等级。
+     * Chzzk 平台的 Subscription 事件也支持此属性。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-guardlevel}
      */
     get guardLevel(): 0 | 3 | 2 | 1 | undefined;
+    /**
+     * 大航海购买数量。
+     *
+     * B 站表示购买月数，Chzzk 表示订阅月数。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-guardnum}
+     */
     get guardNum(): number | undefined;
+    /**
+     * 大航海购买价格（CNY）。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-guardprice}
+     */
     get guardPrice(): number | undefined;
+    /** Chzzk 订阅等级（1-3）。 */
     get chzzkTier(): number | undefined;
+    /** Chzzk 订阅月数。 */
     get chzzkTierMonth(): number | undefined;
+    /** 礼物名称。 */
     get giftName(): string | undefined;
+    /**
+     * 礼物数量。
+     *
+     * 抖音和快手已由 SDK 内部处理连击去重，每次返回增量值。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-giftnum}
+     */
     get giftNum(): number | undefined;
+    /**
+     * 单个礼物价格（CNY）。
+     *
+     * 免费礼物（如 B 站银瓜子）返回 0。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-giftunitprice}
+     */
     get giftUnitPrice(): number | undefined;
+    /**
+     * 礼物总价值（CNY）。
+     *
+     * 等价于 giftNum × giftUnitPrice。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-gifttotalprice}
+     */
     get giftTotalPrice(): number | undefined;
+    /** 礼物图片 URL。 */
     get giftImage(): string | undefined;
+    /** 超级聊天评论内容。 */
     get superChatComment(): string | undefined;
+    /**
+     * 超级聊天价格。
+     *
+     * B 站与 OpenBLive 为人民币（元），Chzzk 为韩元（KRW）。
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-superchatprice}
+     */
     get superChatPrice(): number | undefined;
+    /**
+     * 广义价格，根据消息类型自动选择对应价格属性：
+     *
+     * | 消息类型   | 对应属性          |
+     * |-----------|-----------------|
+     * | gift      | giftTotalPrice  |
+     * | superchat | superChatPrice  |
+     * | guard     | guardPrice      |
+     * | 其它      | undefined       |
+     *
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-price}
+     */
     get price(): number | undefined;
+    /**
+     * 获取用户的抽象化分级，用于渲染用户等级标识。
+     *
+     * 不同平台的映射规则见官网文档。
+     *
+     * @param options - 各平台分段阈值配置，见 {@link abstractLevelOptions}
+     * @returns 0-3 等级，undefined 表示不支持
+     * @see {@link https://dimsum.chat/zh/api/parser.html#parser-getabstractlevel}
+     */
     getAbstractLevel(options?: abstractLevelOptions): number | undefined;
 }
+/**
+ * getCommentHTML 渲染选项。
+ *
+ * @see {@link https://dimsum.chat/zh/api/parser.html#parser-getcommenthtml}
+ */
 interface commentParseOptions {
+    /** 贴纸表情的 CSS 样式。 */
     stickerStyle?: string;
+    /** 贴纸表情的 CSS 类名。 */
     stickerClass?: string;
+    /** 小表情的 CSS 样式。 */
     emotStyle?: string;
+    /** 小表情的 CSS 类名。 */
     emotClass?: string;
+    /** 自定义 AcFun 贴纸表情。仅 platform='acfun' 时生效。 */
     acfunCustomStickers?: {
         keyWord: string;
         path: string;
     }[];
     acfunCustomHtmlBuilder?: (stickerPath: string, content: string) => string;
 }
+/**
+ * getAbstractLevel 配置选项。
+ *
+ * 各平台的默认分段均为 [7, 11, 15]，即 clubLevel ≤ 7 → 0, ≤ 11 → 1, ≤ 15 → 2, > 15 → 3。
+ *
+ * @see {@link https://dimsum.chat/zh/api/parser.html#parser-getabstractlevel}
+ */
 interface abstractLevelOptions {
+    /** 抖音 clubLevel 分段阈值，默认 [7, 11, 15]。 */
     douyinSteps?: number[];
+    /** 快手 clubLevel 分段阈值，默认 [7, 11, 15]。 */
     kuaishouSteps?: number[];
+    /** AcFun clubLevel 分段阈值，默认 [7, 11, 15]。 */
     acfunSteps?: number[];
+    /** AcFun 目标主播 UID。设置后仅该主播的守护团成员返回 >0 的值。 */
     acfunClubUid?: number;
 }
 export { Parser };

package/dist/websocket.d.ts

@@ -1,20 +1,140 @@
 import { Parser } from ".";
 import { Message } from "./types";
+/**
+ * WebSocket 连接管理器（单例模式）。
+ *
+ * 管理 WebSocket 的连接生命周期：
+ * - 建立连接（仅调用一次）
+ * - 自动重连（断开后每 3 秒重试）
+ * - 消息分发到多个监听器
+ * - 通过 send() 主动发送消息到主程序
+ * - 内部自动处理 DimSumChatWidgetInfoRequest 等握手消息
+ *
+ * @see {@link https://dimsum.chat/zh/api/websocket-manager.html}
+ */
 declare class WebSocketManager {
     private static instance;
     private webSocket;
     private messageListeners;
+    /**
+     * Nickname for this widget instance.
+     * Set before connection (via onMessageOptions) or dynamically at runtime.
+     * When non-empty, it will be included in DimSumChatWidgetInfoResponse
+     * so other components can identify this widget via DimSumChatCallMessageRequest.
+     */
+    widgetNickName: string;
     private constructor();
+    /**
+     * 获取唯一的 WebSocket 管理器实例。
+     *
+     * @returns WebSocketManager 单例
+     */
     static getInstance(): WebSocketManager;
+    /**
+     * 连接到指定 WebSocket 服务器。
+     *
+     * 仅可调用一次，重复调用将被忽略。
+     * 连接断开后自动每 3 秒尝试重连。
+     *
+     * @param url - WebSocket 服务器 URL
+     * @see {@link https://dimsum.chat/zh/api/websocket-manager.html#websocketmanager-connect}
+     */
     connect(url: string | URL): void;
     private handleMessage;
+    /**
+     * 注册消息监听器。
+     *
+     * 收到 WebSocket 消息后以字符串形式传递给监听器。
+     * 添加监听器时若连接已建立，会自动推送一条欢迎消息。
+     *
+     * @param listener - 消息回调，接收原始 JSON 字符串
+     * @see {@link https://dimsum.chat/zh/api/websocket-manager.html#websocketmanager-addmessagelistener}
+     */
     addMessageListener(listener: (message: string) => void): void;
+    /**
+     * 移除已注册的消息监听器。
+     *
+     * @param listener - 之前通过 addMessageListener 注册的回调
+     */
     removeMessageListener(listener: (message: string) => void): void;
+    /**
+     * 通过 WebSocket 主动发送消息到主程序。
+     *
+     * 连接未就绪时静默失败，不会抛出异常。
+     *
+     * @param message - 要发送的消息对象，会自动 JSON.stringify
+     * @returns 发送成功返回 true，连接未就绪返回 false
+     *
+     * @example
+     * ```ts
+     * import { WebSocketManager } from 'dimsum-chat'
+     *
+     * const ws = WebSocketManager.getInstance()
+     * ws.send({
+     *   type: 'DimSumChatCallMessageRequest',
+     *   content: {
+     *     targetNickName: 'another-widget',
+     *     requestData: { action: 'refresh' }
+     *   }
+     * })
+     * ```
+     */
+    send(message: object): boolean;
 }
+/**
+ * 根据当前页面 URL 自动生成 WebSocket 服务器地址。
+ *
+ * http 页面 → ws://，https 页面 → wss://
+ * 路径固定为 /websocket。
+ *
+ * @returns WebSocket URL，例如 "ws://localhost:13500/websocket"
+ */
 declare function getWebSocketURL(): string;
+/**
+ * 生成 B 站用户头像的代理 URL。
+ *
+ * 走主程序 /bface/ 接口，避免跨域问题。
+ *
+ * @param uid - B 站用户 ID
+ * @returns 头像代理 URL，例如 "http://localhost:13500/bface/123456"
+ */
 declare function getBfaceURL(uid: string | number): string;
+/**
+ * onMessage 配置选项。
+ *
+ * @see {@link https://dimsum.chat/zh/api/websocket-manager.html#onmessage}
+ */
 interface onMessageOptions {
     customWsServer?: string | URL;
+    /**
+     * Nickname for this widget instance.
+     * Set this to identify your widget when communicating between components
+     * (e.g., via DimSumChatCallMessageRequest).
+     *
+     * Can also be set directly on WebSocketManager.getInstance().widgetNickName
+     * at any point before the DimSumChatWidgetInfoRequest is received.
+     */
+    widgetNickName?: string;
 }
+/**
+ * 注册消息回调，一行代码接入直播间消息。
+ *
+ * 内部组合了 WebSocketManager、getWebSocketURL、Parser 和 DimSumAuth，
+ * 自动处理连接、认证和消息解析，开箱即用。
+ *
+ * @param callback - 消息回调，接收原始 Message 和已创建的 Parser 实例
+ * @param options - 配置选项（可选），支持自定义 WebSocket 服务器
+ *
+ * @example
+ * ```ts
+ * import { onMessage } from 'dimsum-chat'
+ *
+ * onMessage((msg, parser) => {
+ *   console.log(parser.userName + ': ' + parser.comment)
+ * })
+ * ```
+ *
+ * @see {@link https://dimsum.chat/zh/api/websocket-manager.html#onmessage}
+ */
 declare function onMessage(callback: (message: Message, parser: Parser) => void, options?: onMessageOptions): void;
 export { WebSocketManager, getBfaceURL, getWebSocketURL, onMessage };

package/package.json

@@ -1,49 +1,49 @@
-{
-  "name": "dimsum-chat",
-  "version": "0.4.7",
-  "description": "This is a simple utility package for DimSum Chat developer.",
-  "author": "Miego Live",
-  "license": "MIT",
-  "homepage": "https://github.com/MiegoLive/dimsum-chat",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/MiegoLive/dimsum-chat.git"
-  },
-  "bugs": {
-    "url": "https://github.com/MiegoLive/dimsum-chat/issues"
-  },
-  "keywords": [
-    "dimsumchat",
-    "utils"
-  ],
-  "type": "module",
-  "main": "./dist/dimsum-chat.umd.cjs",
-  "module": "./dist/dimsum-chat.js",
-  "types": "./dist/index.d.ts",
-  "unpkg": "./dist/dimsum-chat.umd.cjs",
-  "jsdelivr": "./dist/dimsum-chat.umd.cjs",
-  "exports": {
-    ".": {
-      "import": "./dist/dimsum-chat.js",
-      "require": "./dist/dimsum-chat.umd.cjs"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "preview": "vite preview",
-    "pack:dry-run": "npm pack --dry-run",
-    "test": "vitest",
-    "coverage": "vitest run --coverage"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.25",
-    "typescript": "^5.2.2",
-    "vite": "^5.1.4",
-    "vite-plugin-dts": "^3.7.3",
-    "vitest": "^2.1.1"
-  }
-}
+{
+  "name": "dimsum-chat",
+  "version": "0.5.1",
+  "description": "This is a simple utility package for DimSum Chat developer.",
+  "author": "Miego Live",
+  "license": "MIT",
+  "homepage": "https://github.com/MiegoLive/dimsum-chat",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MiegoLive/dimsum-chat.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MiegoLive/dimsum-chat/issues"
+  },
+  "keywords": [
+    "dimsumchat",
+    "utils"
+  ],
+  "type": "module",
+  "main": "./dist/dimsum-chat.umd.cjs",
+  "module": "./dist/dimsum-chat.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/dimsum-chat.umd.cjs",
+  "jsdelivr": "./dist/dimsum-chat.umd.cjs",
+  "exports": {
+    ".": {
+      "import": "./dist/dimsum-chat.js",
+      "require": "./dist/dimsum-chat.umd.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "pack:dry-run": "npm pack --dry-run",
+    "test": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.25",
+    "typescript": "^5.2.2",
+    "vite": "^5.1.4",
+    "vite-plugin-dts": "^3.7.3",
+    "vitest": "^2.1.1"
+  }
+}