@naplink/naplink 0.0.1 → 0.0.3

package/README.md

@@ -27,15 +27,12 @@
 - [事件处理](https://naplink.github.io/guide/events) - 事件系统详解
 - [最佳实践](https://naplink.github.io/guide/best-practices) - 生产环境建议
 - [架构设计](https://naplink.github.io/guide/architecture) - 内部实现
+- 最佳实践项目：[NapGram](https://github.com/NapLink/NapGram) - 基于 NapLink 的 QQ ↔ Telegram 消息桥接
 
 ## 📦 安装
 
 ```bash
-npm install naplink
-# 或
 pnpm add naplink
-# 或
-yarn add naplink
 ```
 
 ## 🔧 配置示例
@@ -67,19 +64,19 @@ const client = new NapLink({
 
 ```bash
 # 安装依赖
-npm install
+pnpm install
 
 # 开发模式
-npm run dev
+pnpm dev
 
 # 构建
-npm run build
+pnpm build
 
 # 测试
-npm test
+pnpm test
 
 # 类型检查
-npm run typecheck
+pnpm typecheck
 ```
 
 ## 📄 许可证

package/dist/index.d.ts

@@ -101,13 +101,15 @@ declare class ConnectionManager {
     private logger;
     private onMessage;
     private onStateChange;
+    private emitter?;
     private ws?;
     private state;
     private reconnectService;
     private heartbeatService?;
     private connectPromise?;
     private connectTimeout?;
-    constructor(config: NapLinkConfig, logger: Logger, onMessage: (data: string) => void, onStateChange: (state: ConnectionState) => void);
+    private wasReconnecting;
+    constructor(config: NapLinkConfig, logger: Logger, onMessage: (data: string) => void, onStateChange: (state: ConnectionState, wasReconnecting?: boolean) => void, emitter?: any | undefined);
     /**
      * 连接到WebSocket服务器
      */
@@ -175,6 +177,16 @@ declare class ApiClient {
         timeout?: number;
         retries?: number;
     }): Promise<T>;
+    /**
+     * 调用流式 API（NapCat stream-action）
+     * 会持续产出 data.type=stream 的分片包，并在 data.type=response 时结束。
+     */
+    callStream<TPacket = any, TFinal = any>(method: string, params?: any, options?: {
+        timeout?: number;
+    }): {
+        packets: AsyncIterable<TPacket>;
+        result: Promise<TFinal>;
+    };
     /**
      * 处理API响应
      * 由连接管理器调用
@@ -402,9 +414,37 @@ type MessageApi = {
     deleteEssenceMessage(messageId: number | string): Promise<any>;
     getEssenceMessageList(groupId: number | string): Promise<any>;
     markMessageAsRead(messageId: number | string): Promise<any>;
+    markGroupMsgAsRead(groupId: number | string): Promise<any>;
+    markPrivateMsgAsRead(userId: number | string): Promise<any>;
+    markAllMsgAsRead(): Promise<any>;
     getGroupAtAllRemain(groupId: number | string): Promise<number>;
     getGroupSystemMsg(): Promise<GroupSystemMessages>;
     getGroupHonorInfo(groupId: number | string, type: 'all' | 'talkative' | 'performer' | 'legend' | 'strong_newbie' | 'emotion'): Promise<GroupHonorInfo>;
+    getGroupMsgHistory(params: {
+        group_id: number | string;
+        message_seq: number | string;
+        count: number;
+        reverse_order?: boolean;
+    }): Promise<any>;
+    getFriendMsgHistory(params: {
+        user_id: number | string;
+        message_seq: number | string;
+        count: number;
+        reverse_order?: boolean;
+    }): Promise<any>;
+    getRecentContact(count: number): Promise<any>;
+    setMsgEmojiLike(messageId: number | string, emojiId: number, set: boolean): Promise<any>;
+    fetchEmojiLike(params: {
+        message_id: number | string;
+        emojiId: string;
+        emojiType: string;
+        group_id?: number | string;
+        user_id?: number | string;
+        count?: number;
+    }): Promise<any>;
+    sendGroupPoke(groupId: number | string, userId: number | string): Promise<any>;
+    sendFriendPoke(userId: number | string): Promise<any>;
+    sendPoke(targetId: number | string, groupId?: number | string): Promise<any>;
 };
 
 type MediaApi = {
@@ -465,6 +505,70 @@ type StreamApi = {
         verifyOnly?: boolean;
     }): Promise<any>;
     getUploadStreamStatus(streamId: string): Promise<any>;
+    /**
+     * 流式下载文件（原始分片包）
+     * - data_type=file_info / file_chunk / file_complete
+     * - type=stream / response
+     */
+    downloadFileStream(fileId: string, options?: {
+        chunkSize?: number;
+    }): {
+        packets: AsyncIterable<DownloadStreamPacket>;
+        result: Promise<DownloadStreamPacket>;
+    };
+    downloadFileStreamToFile(fileId: string, options?: {
+        chunkSize?: number;
+        filename?: string;
+    }): Promise<{
+        path: string;
+        info?: DownloadStreamPacket;
+    }>;
+    downloadFileImageStream(fileId: string, options?: {
+        chunkSize?: number;
+    }): {
+        packets: AsyncIterable<DownloadStreamPacket>;
+        result: Promise<DownloadStreamPacket>;
+    };
+    downloadFileImageStreamToFile(fileId: string, options?: {
+        chunkSize?: number;
+        filename?: string;
+    }): Promise<{
+        path: string;
+        info?: DownloadStreamPacket;
+    }>;
+    downloadFileRecordStream(fileId: string, outFormat?: string, options?: {
+        chunkSize?: number;
+        filename?: string;
+    }): {
+        packets: AsyncIterable<DownloadStreamPacket>;
+        result: Promise<DownloadStreamPacket>;
+    };
+    downloadFileRecordStreamToFile(fileId: string, outFormat?: string, options?: {
+        chunkSize?: number;
+        filename?: string;
+    }): Promise<{
+        path: string;
+        info?: DownloadStreamPacket;
+    }>;
+    cleanStreamTempFile(): Promise<any>;
+};
+type DownloadStreamPacket = {
+    type: 'stream' | 'response' | 'reset' | 'error';
+    data_type?: 'file_info' | 'file_chunk' | 'file_complete' | string;
+    file_name?: string;
+    file_size?: number;
+    chunk_size?: number;
+    index?: number;
+    data?: string;
+    size?: number;
+    progress?: number;
+    base64_size?: number;
+    total_chunks?: number;
+    total_bytes?: number;
+    message?: string;
+    width?: number;
+    height?: number;
+    out_format?: string;
 };
 
 type RequestApi = {
@@ -472,6 +576,103 @@ type RequestApi = {
     handleGroupRequest(flag: string, subType: 'add' | 'invite', approve?: boolean, reason?: string): Promise<any>;
 };
 
+type SystemApi = {
+    getOnlineClients(noCache?: boolean): Promise<any>;
+    getRobotUinRange(): Promise<any>;
+    canSendImage(): Promise<any>;
+    canSendRecord(): Promise<any>;
+    getCookies(domain: string): Promise<any>;
+    getCsrfToken(): Promise<any>;
+    getCredentials(domain: string): Promise<any>;
+    setInputStatus(userId: number | string, eventType: number): Promise<any>;
+    ocrImage(image: string, dot?: boolean): Promise<any>;
+    translateEn2zh(words: string[]): Promise<any>;
+    checkUrlSafely(url: string): Promise<any>;
+    handleQuickOperation(context: any, operation: any): Promise<any>;
+    getModelShow(model: string): Promise<any>;
+    setModelShow(model: string, modelShow: string): Promise<any>;
+    getPacketStatus(): Promise<any>;
+};
+
+type NapCatApi = {
+    getRkeyEx(): Promise<any>;
+    getRkeyServer(): Promise<any>;
+    getRkey(): Promise<any>;
+    setFriendRemark(userId: number | string, remark: string): Promise<any>;
+    deleteFriend(userId: number | string): Promise<any>;
+    getUnidirectionalFriendList(): Promise<any>;
+    setGroupRemark(groupId: number | string, remark: string): Promise<any>;
+    getGroupInfoEx(groupId: number | string): Promise<any>;
+    getGroupDetailInfo(groupId: number | string): Promise<any>;
+    getGroupIgnoredNotifies(): Promise<any>;
+    getGroupShutList(groupId: number | string): Promise<any>;
+    sendPrivateForwardMessage(params: {
+        user_id: number | string;
+        messages: any[];
+        news?: any[];
+        prompt?: string;
+        summary?: string;
+        source?: string;
+    }): Promise<any>;
+    forwardFriendSingleMsg(userId: number | string, messageId: number | string): Promise<any>;
+    forwardGroupSingleMsg(groupId: number | string, messageId: number | string): Promise<any>;
+    sendForwardMsg(params: {
+        group_id?: number | string;
+        user_id?: number | string;
+        messages: any[];
+        news?: any[];
+        prompt?: string;
+        summary?: string;
+        source?: string;
+    }): Promise<any>;
+    sendGroupNotice(params: {
+        group_id: number | string;
+        content: string;
+        image?: string;
+        pinned?: number | string;
+        type?: number | string;
+        confirm_required?: number | string;
+        is_show_edit_card?: number | string;
+        tip_window_type?: number | string;
+    }): Promise<any>;
+    getGroupNotice(groupId: number | string): Promise<any>;
+    delGroupNotice(groupId: number | string, noticeId: string): Promise<any>;
+    setOnlineStatus(status: number | string, extStatus: number | string, batteryStatus: number | string): Promise<any>;
+    setDiyOnlineStatus(faceId: number | string, wording?: string, faceType?: number | string): Promise<any>;
+    sendArkShare(params: {
+        user_id?: number | string;
+        group_id?: number | string;
+        phone_number?: string;
+    }): Promise<any>;
+    sendGroupArkShare(groupId: number | string): Promise<any>;
+    getMiniAppArk(payload: any): Promise<any>;
+    getAiCharacters(groupId: number | string, chatType?: number | string): Promise<any>;
+    getAiRecord(groupId: number | string, character: string, text: string): Promise<any>;
+    sendGroupAiRecord(groupId: number | string, character: string, text: string): Promise<any>;
+    setGroupSign(groupId: number | string): Promise<any>;
+    sendGroupSign(groupId: number | string): Promise<any>;
+    fetchCustomFace(params?: any): Promise<any>;
+    getClientkey(): Promise<any>;
+    clickInlineKeyboardButton(params: {
+        group_id: number | string;
+        bot_appid: string;
+        button_id?: string;
+        callback_data?: string;
+        msg_seq?: string;
+    }): Promise<any>;
+};
+
+/**
+ * NapCatQQ ActionName 全量列表（服务端路由表）
+ * - 可用于“完全覆盖”服务端 action，而不必在 SDK 里为每个 action 单独写一层包装。
+ * - 对于包含 '.'/'_' 等前缀的 action，建议使用 bracket 访问：api.raw['.ocr_image'](...)
+ */
+declare const NAPCAT_ACTIONS: readonly [".get_word_slices", ".handle_quick_operation", ".ocr_image", "ArkShareGroup", "ArkSharePeer", "_del_group_notice", "_get_group_notice", "_get_model_show", "_mark_all_as_read", "_send_group_notice", "_set_model_show", "bot_exit", "can_send_image", "can_send_record", "check_url_safely", "clean_cache", "clean_stream_temp_file", "click_inline_keyboard_button", "create_collection", "create_group_file_folder", "del_group_album_media", "delete_essence_msg", "delete_friend", "delete_group_file", "delete_group_folder", "delete_msg", "delete_unidirectional_friend", "do_group_album_comment", "download_file", "download_file_image_stream", "download_file_record_stream", "download_file_stream", "fetch_custom_face", "fetch_emoji_like", "forward_friend_single_msg", "forward_group_single_msg", "friend_poke", "get_ai_characters", "get_ai_record", "get_clientkey", "get_collection_list", "get_cookies", "get_credentials", "get_csrf_token", "get_doubt_friends_add_request", "get_essence_msg_list", "get_file", "get_forward_msg", "get_friend_list", "get_friend_msg_history", "get_friends_with_category", "get_group_album_media_list", "get_group_at_all_remain", "get_group_detail_info", "get_group_file_system_info", "get_group_file_url", "get_group_files_by_folder", "get_group_honor_info", "get_group_ignore_add_request", "get_group_ignored_notifies", "get_group_info", "get_group_info_ex", "get_group_list", "get_group_member_info", "get_group_member_list", "get_group_msg_history", "get_group_root_files", "get_group_shut_list", "get_group_system_msg", "get_guild_list", "get_guild_service_profile", "get_image", "get_login_info", "get_mini_app_ark", "get_msg", "get_online_clients", "get_private_file_url", "get_profile_like", "get_qun_album_list", "get_recent_contact", "get_record", "get_rkey", "get_rkey_server", "get_robot_uin_range", "get_status", "get_stranger_info", "get_unidirectional_friend_list", "get_version_info", "group_poke", "mark_group_msg_as_read", "mark_msg_as_read", "mark_private_msg_as_read", "move_group_file", "nc_get_packet_status", "nc_get_rkey", "nc_get_user_status", "ocr_image", "qidian_get_account_info", "reboot_normal", "reload_event_filter", "rename_group_file", "send_ark_share", "send_forward_msg", "send_group_ai_record", "send_group_ark_share", "send_group_forward_msg", "send_group_msg", "send_group_sign", "send_like", "send_msg", "send_packet", "send_poke", "send_private_forward_msg", "send_private_msg", "set_diy_online_status", "set_doubt_friends_add_request", "set_essence_msg", "set_friend_add_request", "set_friend_remark", "set_group_add_option", "set_group_add_request", "set_group_admin", "set_group_album_media_like", "set_group_anonymous", "set_group_anonymous_ban", "set_group_ban", "set_group_card", "set_group_kick", "set_group_kick_members", "set_group_leave", "set_group_name", "set_group_portrait", "set_group_remark", "set_group_robot_add_option", "set_group_search", "set_group_sign", "set_group_special_title", "set_group_todo", "set_group_whole_ban", "set_input_status", "set_msg_emoji_like", "set_online_status", "set_qq_avatar", "set_qq_profile", "set_restart", "set_self_longnick", "test_auto_register_01", "test_auto_register_02", "test_download_stream", "trans_group_file", "translate_en2zh", "unknown", "upload_file_stream", "upload_group_file", "upload_image_to_qun_album", "upload_private_file"];
+type NapCatAction = typeof NAPCAT_ACTIONS[number];
+type RawActionApi = {
+    [K in NapCatAction]: (params?: any) => Promise<any>;
+};
+
 /**
  * OneBot 11 API 封装
  * 将 ApiClient 的底层 call 转为清晰的业务方法
@@ -485,9 +686,12 @@ declare class OneBotApi {
     private fileApi;
     private streamApi;
     private requestApi;
+    private systemApi;
+    private napcatApi;
+    readonly raw: RawActionApi;
     constructor(client: ApiClient, logger: Logger);
 }
-interface OneBotApi extends MessageApi, MediaApi, AccountApi, GroupApi, FileApi, StreamApi, RequestApi {
+interface OneBotApi extends MessageApi, MediaApi, AccountApi, GroupApi, FileApi, StreamApi, RequestApi, SystemApi, NapCatApi {
 }
 
 /**
@@ -511,6 +715,9 @@ type OneBotApiMethods = {
     getForwardMessage(id: string): Promise<any>;
     getEssenceMessageList(groupId: number | string): Promise<any>;
     markMessageAsRead(messageId: number | string): Promise<any>;
+    markGroupMsgAsRead(groupId: number | string): Promise<any>;
+    markPrivateMsgAsRead(userId: number | string): Promise<any>;
+    markAllMsgAsRead(): Promise<any>;
     getGroupAtAllRemain(groupId: number | string): Promise<any>;
     getGroupSystemMsg(): Promise<any>;
     getGroupHonorInfo(groupId: number | string, type: 'all' | 'talkative' | 'performer' | 'legend' | 'strong_newbie' | 'emotion'): Promise<any>;
@@ -532,7 +739,74 @@ type OneBotApiMethods = {
         verifyOnly?: boolean;
     }): Promise<any>;
     getUploadStreamStatus(streamId: string): Promise<any>;
+    downloadFileStream(fileId: string, options?: {
+        chunkSize?: number;
+    }): {
+        packets: AsyncIterable<any>;
+        result: Promise<any>;
+    };
+    downloadFileStreamToFile(fileId: string, options?: {
+        chunkSize?: number;
+        filename?: string;
+    }): Promise<{
+        path: string;
+        info?: any;
+    }>;
+    downloadFileImageStream(fileId: string, options?: {
+        chunkSize?: number;
+    }): {
+        packets: AsyncIterable<any>;
+        result: Promise<any>;
+    };
+    downloadFileImageStreamToFile(fileId: string, options?: {
+        chunkSize?: number;
+        filename?: string;
+    }): Promise<{
+        path: string;
+        info?: any;
+    }>;
+    downloadFileRecordStream(fileId: string, outFormat?: string, options?: {
+        chunkSize?: number;
+        filename?: string;
+    }): {
+        packets: AsyncIterable<any>;
+        result: Promise<any>;
+    };
+    downloadFileRecordStreamToFile(fileId: string, outFormat?: string, options?: {
+        chunkSize?: number;
+        filename?: string;
+    }): Promise<{
+        path: string;
+        info?: any;
+    }>;
+    cleanStreamTempFile(): Promise<any>;
     sendGroupForwardMessage(groupId: number | string, messages: any[]): Promise<any>;
+    getGroupMsgHistory(params: {
+        group_id: number | string;
+        message_seq: number | string;
+        count: number;
+        reverse_order?: boolean;
+    }): Promise<any>;
+    getFriendMsgHistory(params: {
+        user_id: number | string;
+        message_seq: number | string;
+        count: number;
+        reverse_order?: boolean;
+    }): Promise<any>;
+    getRecentContact(count: number): Promise<any>;
+    setMsgEmojiLike(messageId: number | string, emojiId: number, set: boolean): Promise<any>;
+    fetchEmojiLike(params: {
+        message_id: number | string;
+        emojiId: string;
+        emojiType: string;
+        group_id?: number | string;
+        user_id?: number | string;
+        count?: number;
+    }): Promise<any>;
+    fetchCustomFace(params?: any): Promise<any>;
+    sendGroupPoke(groupId: number | string, userId: number | string): Promise<any>;
+    sendFriendPoke(userId: number | string): Promise<any>;
+    sendPoke(targetId: number | string, groupId?: number | string): Promise<any>;
     getImage(file: string): Promise<any>;
     getRecord(file: string, outFormat?: string): Promise<any>;
     getFile(file: string): Promise<any>;
@@ -561,6 +835,90 @@ type OneBotApiMethods = {
     getVersionInfo(): Promise<any>;
     handleFriendRequest(flag: string, approve?: boolean, remark?: string): Promise<any>;
     handleGroupRequest(flag: string, subType: 'add' | 'invite', approve?: boolean, reason?: string): Promise<any>;
+    getOnlineClients(noCache?: boolean): Promise<any>;
+    getRobotUinRange(): Promise<any>;
+    canSendImage(): Promise<any>;
+    canSendRecord(): Promise<any>;
+    getCookies(domain: string): Promise<any>;
+    getCsrfToken(): Promise<any>;
+    getCredentials(domain: string): Promise<any>;
+    setInputStatus(userId: number | string, eventType: number): Promise<any>;
+    ocrImage(image: string, dot?: boolean): Promise<any>;
+    translateEn2zh(words: string[]): Promise<any>;
+    checkUrlSafely(url: string): Promise<any>;
+    handleQuickOperation(context: any, operation: any): Promise<any>;
+    getModelShow(model: string): Promise<any>;
+    setModelShow(model: string, modelShow: string): Promise<any>;
+    getPacketStatus(): Promise<any>;
+    getRkeyEx(): Promise<any>;
+    getRkeyServer(): Promise<any>;
+    getRkey(): Promise<any>;
+    setFriendRemark(userId: number | string, remark: string): Promise<any>;
+    deleteFriend(userId: number | string): Promise<any>;
+    getUnidirectionalFriendList(): Promise<any>;
+    setGroupRemark(groupId: number | string, remark: string): Promise<any>;
+    getGroupInfoEx(groupId: number | string): Promise<any>;
+    getGroupDetailInfo(groupId: number | string): Promise<any>;
+    getGroupIgnoredNotifies(): Promise<any>;
+    getGroupShutList(groupId: number | string): Promise<any>;
+    sendPrivateForwardMessage(params: {
+        user_id: number | string;
+        messages: any[];
+        news?: any[];
+        prompt?: string;
+        summary?: string;
+        source?: string;
+    }): Promise<any>;
+    forwardFriendSingleMsg(userId: number | string, messageId: number | string): Promise<any>;
+    forwardGroupSingleMsg(groupId: number | string, messageId: number | string): Promise<any>;
+    sendForwardMsg(params: {
+        group_id?: number | string;
+        user_id?: number | string;
+        messages: any[];
+        news?: any[];
+        prompt?: string;
+        summary?: string;
+        source?: string;
+    }): Promise<any>;
+    sendGroupNotice(params: {
+        group_id: number | string;
+        content: string;
+        image?: string;
+        pinned?: number | string;
+        type?: number | string;
+        confirm_required?: number | string;
+        is_show_edit_card?: number | string;
+        tip_window_type?: number | string;
+    }): Promise<any>;
+    getGroupNotice(groupId: number | string): Promise<any>;
+    delGroupNotice(groupId: number | string, noticeId: string): Promise<any>;
+    setOnlineStatus(status: number | string, extStatus: number | string, batteryStatus: number | string): Promise<any>;
+    setDiyOnlineStatus(faceId: number | string, wording?: string, faceType?: number | string): Promise<any>;
+    sendArkShare(params: {
+        user_id?: number | string;
+        group_id?: number | string;
+        phone_number?: string;
+    }): Promise<any>;
+    sendGroupArkShare(groupId: number | string): Promise<any>;
+    getMiniAppArk(payload: any): Promise<any>;
+    getAiCharacters(groupId: number | string, chatType?: number | string): Promise<any>;
+    getAiRecord(groupId: number | string, character: string, text: string): Promise<any>;
+    sendGroupAiRecord(groupId: number | string, character: string, text: string): Promise<any>;
+    setGroupSign(groupId: number | string): Promise<any>;
+    sendGroupSign(groupId: number | string): Promise<any>;
+    getClientkey(): Promise<any>;
+    clickInlineKeyboardButton(params: {
+        group_id: number | string;
+        bot_appid: string;
+        button_id?: string;
+        callback_data?: string;
+        msg_seq?: string;
+    }): Promise<any>;
+    /**
+     * Raw action table (ActionName 全覆盖)
+     * 访问方式：client.raw['get_group_shut_list']({ group_id: 123 })
+     */
+    raw: any;
 };
 
 /**