@naplink/naplink 0.0.7 → 0.0.10

package/README.md

@@ -15,7 +15,7 @@
 - ⏱️ **超时控制** - API 调用和连接超时保护
 - 🎯 **事件驱动** - 完整的 OneBot 11 事件支持
 - 📊 **完善日志** - 分级日志系统，支持自定义 logger
-- 💪 **稳定可靠** - 自动心跳检测，零运行时依赖
+- 💪 **稳定可靠** - 自动心跳检测，轻量运行时依赖
 
 ## 📚 文档
 
@@ -32,7 +32,9 @@
 ## 📦 安装
 
 ```bash
-pnpm add naplink
+pnpm add @naplink/naplink
+npm install @naplink/naplink
+yarn add @naplink/naplink
 ```
 
 ## 🔧 配置示例

package/dist/index.d.ts

@@ -18,7 +18,7 @@ interface NapLinkConfig {
         /** 自定义心跳动作（默认 get_status） */
         heartbeatAction?: {
             action: string;
-            params?: Record<string, any>;
+            params?: Record<string, unknown>;
         };
     };
     /** 重连配置 */
@@ -57,10 +57,10 @@ interface NapLinkConfig {
  * 允许用户提供自定义logger实现
  */
 interface Logger {
-    debug(message: string, ...meta: any[]): void;
-    info(message: string, ...meta: any[]): void;
-    warn(message: string, ...meta: any[]): void;
-    error(message: string, error?: Error, ...meta: any[]): void;
+    debug(message: string, ...meta: unknown[]): void;
+    info(message: string, ...meta: unknown[]): void;
+    warn(message: string, ...meta: unknown[]): void;
+    error(message: string, error?: Error, ...meta: unknown[]): void;
 }
 /**
  * 部分配置类型（用于构造函数）
@@ -74,7 +74,7 @@ type PartialNapLinkConfig = {
         pingInterval?: number;
         heartbeatAction?: {
             action: string;
-            params?: Record<string, any>;
+            params?: Record<string, unknown>;
         };
     };
     reconnect?: Partial<NapLinkConfig['reconnect']>;
@@ -109,7 +109,7 @@ declare class ConnectionManager {
     private connectPromise?;
     private connectTimeout?;
     private wasReconnecting;
-    constructor(config: NapLinkConfig, logger: Logger, onMessage: (data: string) => void, onStateChange: (state: ConnectionState, wasReconnecting?: boolean) => void, emitter?: any | undefined);
+    constructor(config: NapLinkConfig, logger: Logger, onMessage: (data: string) => void, onStateChange: (state: ConnectionState, wasReconnecting?: boolean) => void, emitter?: Pick<EventEmitter, "emit"> | undefined);
     /**
      * 连接到WebSocket服务器
      */
@@ -154,6 +154,14 @@ declare class ConnectionManager {
     private clearConnectTimeout;
 }
 
+type ApiResponseEnvelope = {
+    stream?: string;
+    status?: string;
+    retcode?: number;
+    message?: string;
+    wording?: string;
+    data?: Record<string, unknown>;
+};
 /**
  * API客户端
  * 负责发送API请求并处理响应
@@ -173,7 +181,7 @@ declare class ApiClient {
      * @param params API参数
      * @param options 调用选项
      */
-    call<T = any>(method: string, params?: any, options?: {
+    call<T = unknown>(method: string, params?: Record<string, unknown>, options?: {
         timeout?: number;
         retries?: number;
     }): Promise<T>;
@@ -181,7 +189,7 @@ declare class ApiClient {
      * 调用流式 API（NapCat stream-action）
      * 会持续产出 data.type=stream 的分片包，并在 data.type=response 时结束。
      */
-    callStream<TPacket = any, TFinal = any>(method: string, params?: any, options?: {
+    callStream<TPacket = unknown, TFinal = unknown>(method: string, params?: Record<string, unknown>, options?: {
         timeout?: number;
     }): {
         packets: AsyncIterable<TPacket>;
@@ -191,11 +199,16 @@ declare class ApiClient {
      * 处理API响应
      * 由连接管理器调用
      */
-    handleResponse(echo: string, response: any): void;
+    handleResponse(echo: string, response: ApiResponseEnvelope): void;
     /**
      * 销毁API客户端
      */
     destroy(): void;
+    /**
+     * 清理所有待处理请求，但保留客户端可继续使用。
+     * 适用于临时断线、主动 disconnect 后再次 connect 的场景。
+     */
+    clearPendingRequests(reason: string): void;
     /**
      * 发送API请求
      */
@@ -215,6 +228,93 @@ declare class ApiClient {
     private startCleanupTimer;
 }
 
+type TextSegment = {
+    type: 'text';
+    data: {
+        text: string;
+    };
+};
+type AtSegment = {
+    type: 'at';
+    data: {
+        qq: string | 'all';
+    };
+};
+type FaceSegment = {
+    type: 'face';
+    data: {
+        id: string;
+    };
+};
+type ReplySegment = {
+    type: 'reply';
+    data: {
+        id: string;
+    };
+};
+type ImageSegment = {
+    type: 'image';
+    data: {
+        file: string;
+        file_id?: string;
+        url?: string;
+        summary?: string;
+        sub_type?: string;
+    };
+};
+type RecordSegment = {
+    type: 'record';
+    data: {
+        file: string;
+        file_id?: string;
+        url?: string;
+    };
+};
+type AudioSegment = {
+    type: 'audio';
+    data: {
+        file: string;
+        file_id?: string;
+        url?: string;
+    };
+};
+type VideoSegment = {
+    type: 'video';
+    data: {
+        file: string;
+        file_id?: string;
+        url?: string;
+    };
+};
+type FileSegment = {
+    type: 'file';
+    data: {
+        file: string;
+        file_id?: string;
+        url?: string;
+        name?: string;
+    };
+};
+type JsonSegment = {
+    type: 'json';
+    data: {
+        data: string;
+    };
+};
+type XmlSegment = {
+    type: 'xml';
+    data: {
+        data: string;
+    };
+};
+type MarkdownSegment = {
+    type: 'markdown';
+    data: {
+        content: string;
+    };
+};
+type OneBotMessageSegment = TextSegment | AtSegment | FaceSegment | ReplySegment | ImageSegment | RecordSegment | AudioSegment | VideoSegment | FileSegment | JsonSegment | XmlSegment | MarkdownSegment;
+
 /**
  * OneBot 11 Protocol Base Types
  */
@@ -224,7 +324,7 @@ interface BaseEvent {
     self_id: number;
     post_type: PostType;
 }
-type MessageSegment = any;
+type MessageSegment = OneBotMessageSegment;
 
 interface MessageEvent extends BaseEvent {
     post_type: 'message';
@@ -344,7 +444,7 @@ interface FriendAddNotice extends NoticeEvent {
 interface NotifyNotice extends NoticeEvent {
     notice_type: 'notify';
     sub_type: string;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 interface PokeNotice extends NotifyNotice {
     sub_type: 'poke';
@@ -391,7 +491,7 @@ interface LifecycleMetaEvent extends MetaEvent {
 }
 interface HeartbeatMetaEvent extends MetaEvent {
     meta_event_type: 'heartbeat';
-    status: any;
+    status: Record<string, unknown>;
     interval: number;
 }
 
@@ -405,6 +505,8 @@ interface GroupHonorInfo {
     emotion_list?: any[];
 }
 
+type OneBotEvent = MessageEvent | PrivateMessageEvent | GroupMessageEvent | NoticeEvent | GroupRecallNotice | FriendRecallNotice | GroupUploadNotice | GroupAdminNotice | GroupDecreaseNotice | GroupIncreaseNotice | FriendAddNotice | PokeNotice | GroupGrayTipNotice | RequestEvent | FriendRequest | GroupRequest | MetaEvent | LifecycleMetaEvent | HeartbeatMetaEvent;
+
 type MessageApi = {
     sendMessage(params: {
         message_type?: 'private' | 'group';
@@ -457,11 +559,15 @@ type MessageApi = {
     sendPoke(targetId: number | string, groupId?: number | string): Promise<any>;
 };
 
+type MediaFileResponse = {
+    file?: string;
+    url?: string;
+};
 type MediaApi = {
-    getImage(file: string): Promise<any>;
-    getRecord(file: string, outFormat?: string): Promise<any>;
-    getFile(file: string): Promise<any>;
-    hydrateMedia(message: any[]): Promise<void>;
+    getImage(file: string): Promise<MediaFileResponse>;
+    getRecord(file: string, outFormat?: string): Promise<MediaFileResponse>;
+    getFile(file: string): Promise<MediaFileResponse>;
+    hydrateMedia(message: OneBotMessageSegment[]): Promise<void>;
 };
 
 type AccountApi = {
@@ -979,15 +1085,20 @@ declare class NapLink extends EventEmitter {
      * 补充消息中的媒体直链
      * 自动通过 get_file / get_image / get_record 获取真实下载链接
      */
-    hydrateMessage(message: any[]): Promise<void>;
+    hydrateMessage(message: OneBotMessageSegment[]): Promise<void>;
     /**
      * 调用自定义API
      */
-    callApi<T = any>(method: string, params?: any): Promise<T>;
+    callApi<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
     /**
      * 暴露 OneBot API 便于直接使用
      */
     get api(): OneBotApi;
+    /**
+     * 销毁客户端实例
+     * 调用后不应再复用当前实例。
+     */
+    dispose(): void;
     /**
      * 设置事件转发
      */
@@ -1002,8 +1113,8 @@ interface NapLink extends OneBotApiMethods {
  */
 declare class NapLinkError extends Error {
     code: string;
-    details?: any | undefined;
-    constructor(message: string, code: string, details?: any | undefined);
+    details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
     /**
      * 转换为JSON格式
      */
@@ -1011,7 +1122,7 @@ declare class NapLinkError extends Error {
         name: string;
         message: string;
         code: string;
-        details: any;
+        details: unknown;
     };
 }
 /**
@@ -1019,7 +1130,7 @@ declare class NapLinkError extends Error {
  * 当WebSocket连接失败时抛出
  */
 declare class ConnectionError extends NapLinkError {
-    constructor(message: string, cause?: any);
+    constructor(message: string, cause?: unknown);
 }
 /**
  * API超时错误
@@ -1054,75 +1165,4 @@ declare class InvalidConfigError extends NapLinkError {
     constructor(field: string, reason: string);
 }
 
-type TextSegment = {
-    type: 'text';
-    data: {
-        text: string;
-    };
-};
-type AtSegment = {
-    type: 'at';
-    data: {
-        qq: string | 'all';
-    };
-};
-type FaceSegment = {
-    type: 'face';
-    data: {
-        id: string;
-    };
-};
-type ReplySegment = {
-    type: 'reply';
-    data: {
-        id: string;
-    };
-};
-type ImageSegment = {
-    type: 'image';
-    data: {
-        file: string;
-        summary?: string;
-        sub_type?: string;
-    };
-};
-type RecordSegment = {
-    type: 'record';
-    data: {
-        file: string;
-    };
-};
-type VideoSegment = {
-    type: 'video';
-    data: {
-        file: string;
-    };
-};
-type FileSegment = {
-    type: 'file';
-    data: {
-        file: string;
-        name?: string;
-    };
-};
-type JsonSegment = {
-    type: 'json';
-    data: {
-        data: string;
-    };
-};
-type XmlSegment = {
-    type: 'xml';
-    data: {
-        data: string;
-    };
-};
-type MarkdownSegment = {
-    type: 'markdown';
-    data: {
-        content: string;
-    };
-};
-type OneBotMessageSegment = TextSegment | AtSegment | FaceSegment | ReplySegment | ImageSegment | RecordSegment | VideoSegment | FileSegment | JsonSegment | XmlSegment | MarkdownSegment;
-
-export { type Anonymous, ApiError, ApiTimeoutError, type AtSegment, type BaseEvent, ConnectionClosedError, ConnectionError, ConnectionState, type FaceSegment, type FileInfo, type FileSegment, type FriendAddNotice, type FriendRecallNotice, type FriendRequest, type GroupAdminNotice, type GroupDecreaseNotice, type GroupGrayTipNotice, type GroupHonorInfo, type GroupIncreaseNotice, type GroupInviteRequest, type GroupJoinRequest, type GroupMessageEvent, type GroupRecallNotice, type GroupRequest, type GroupSystemMessages, type GroupUploadNotice, type HeartbeatMetaEvent, type ImageSegment, InvalidConfigError, type JsonSegment, type LifecycleMetaEvent, type Logger, type MarkdownSegment, MaxReconnectAttemptsError, type MessageEvent, type MessageSegment, type MetaEvent, NapLink, type NapLinkConfig, NapLinkError, type NoticeEvent, type NotifyNotice, OneBotApi, type OneBotMessageSegment, type PartialNapLinkConfig, type PokeNotice, type PostType, type PrivateMessageEvent, type RecordSegment, type ReplySegment, type RequestEvent, type Sender, type TextSegment, type VideoSegment, type XmlSegment, NapLink as default };
+export { type Anonymous, ApiError, ApiTimeoutError, type AtSegment, type AudioSegment, type BaseEvent, ConnectionClosedError, ConnectionError, ConnectionState, type FaceSegment, type FileInfo, type FileSegment, type FriendAddNotice, type FriendRecallNotice, type FriendRequest, type GroupAdminNotice, type GroupDecreaseNotice, type GroupGrayTipNotice, type GroupHonorInfo, type GroupIncreaseNotice, type GroupInviteRequest, type GroupJoinRequest, type GroupMessageEvent, type GroupRecallNotice, type GroupRequest, type GroupSystemMessages, type GroupUploadNotice, type HeartbeatMetaEvent, type ImageSegment, InvalidConfigError, type JsonSegment, type LifecycleMetaEvent, type Logger, type MarkdownSegment, MaxReconnectAttemptsError, type MessageEvent, type MessageSegment, type MetaEvent, NapLink, type NapLinkConfig, NapLinkError, type NoticeEvent, type NotifyNotice, OneBotApi, type OneBotEvent, type OneBotMessageSegment, type PartialNapLinkConfig, type PokeNotice, type PostType, type PrivateMessageEvent, type RecordSegment, type ReplySegment, type RequestEvent, type Sender, type TextSegment, type VideoSegment, type XmlSegment, NapLink as default };

package/dist/index.js

@@ -293,8 +293,14 @@ var ConnectionState = /* @__PURE__ */ ((ConnectionState3) => {
 function buildWebSocketUrl(config) {
   const { url, token } = config.connection;
   if (token) {
-    const separator = url.includes("?") ? "&" : "?";
-    return `${url}${separator}access_token=${token}`;
+    try {
+      const parsed = new URL(url);
+      parsed.searchParams.set("access_token", token);
+      return parsed.toString();
+    } catch {
+      const separator = url.includes("?") ? "&" : "?";
+      return `${url}${separator}access_token=${encodeURIComponent(token)}`;
+    }
   }
   return url;
 }
@@ -532,6 +538,7 @@ var ConnectionManager = class {
     this.logger.info(`\u65AD\u5F00\u8FDE\u63A5: ${reason}`);
     this.reconnectService.cancel();
     this.stopHeartbeat();
+    this.clearConnectTimeout();
     if (this.ws) {
       try {
         this.ws.onopen = null;
@@ -851,8 +858,8 @@ var ApiClient = class {
       });
       const error = new ApiError(
         request.method,
-        response.retcode,
-        response.message,
+        typeof response.retcode === "number" ? response.retcode : -1,
+        typeof response.message === "string" ? response.message : "Unknown API error",
         response.wording
       );
       request.onError?.(error);
@@ -863,12 +870,19 @@ var ApiClient = class {
    * 销毁API客户端
    */
   destroy() {
-    this.registry.clearAll("API\u5BA2\u6237\u7AEF\u5DF2\u9500\u6BC1");
+    this.clearPendingRequests("API\u5BA2\u6237\u7AEF\u5DF2\u9500\u6BC1");
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = void 0;
     }
   }
+  /**
+   * 清理所有待处理请求，但保留客户端可继续使用。
+   * 适用于临时断线、主动 disconnect 后再次 connect 的场景。
+   */
+  clearPendingRequests(reason) {
+    this.registry.clearAll(reason);
+  }
   /**
    * 发送API请求
    */
@@ -949,7 +963,7 @@ var EventRouter = class extends EventEmitter {
   emit(event, ...args) {
     this.anyListeners.forEach((listener) => {
       try {
-        listener(event, ...args);
+        listener(event, args[0]);
       } catch (error) {
         this.logger.error("onAny listener error", error);
       }
@@ -963,13 +977,15 @@ var EventRouter = class extends EventEmitter {
   route(data) {
     try {
       const postType = data.post_type;
+      const messageType = "message_type" in data ? data.message_type : void 0;
+      const noticeType = "notice_type" in data ? data.notice_type : void 0;
       if (!postType) {
         this.logger.warn("\u6536\u5230\u65E0\u6548\u6D88\u606F: \u7F3A\u5C11 post_type", data);
         return;
       }
       this.logger.debug(`\u8DEF\u7531\u4E8B\u4EF6: ${postType}`, {
-        messageType: data.message_type,
-        noticeType: data.notice_type
+        messageType,
+        noticeType
       });
       switch (postType) {
         case "meta_event":
@@ -1000,10 +1016,13 @@ var EventRouter = class extends EventEmitter {
    * 路由元事件
    */
   routeMetaEvent(data) {
+    if (!isMetaEventPayload(data))
+      return;
     const type = data.meta_event_type;
     const events = [`meta_event`, `meta_event.${type}`];
-    if (type === "lifecycle") {
-      events.push(`meta_event.lifecycle.${data.sub_type}`);
+    const subType = "sub_type" in data ? data.sub_type : void 0;
+    if (type === "lifecycle" && subType) {
+      events.push(`meta_event.lifecycle.${subType}`);
     }
     this.emitEvents(events, data);
   }
@@ -1011,6 +1030,8 @@ var EventRouter = class extends EventEmitter {
    * 路由消息事件
    */
   routeMessage(data) {
+    if (!isMessageEventPayload(data))
+      return;
     const messageType = data.message_type;
     const subType = data.sub_type;
     const events = [
@@ -1024,6 +1045,8 @@ var EventRouter = class extends EventEmitter {
    * 路由发送消息事件
    */
   routeMessageSent(data) {
+    if (!isMessageEventPayload(data))
+      return;
     const messageType = data.message_type;
     const subType = data.sub_type;
     const events = [
@@ -1037,8 +1060,10 @@ var EventRouter = class extends EventEmitter {
    * 路由通知事件
    */
   routeNotice(data) {
+    if (!isNoticeEventPayload(data))
+      return;
     const noticeType = data.notice_type;
-    const subType = data.sub_type;
+    const subType = "sub_type" in data ? data.sub_type : void 0;
     const events = ["notice", `notice.${noticeType}`];
     if (subType) {
       events.push(`notice.${noticeType}.${subType}`);
@@ -1049,8 +1074,10 @@ var EventRouter = class extends EventEmitter {
    * 路由请求事件
    */
   routeRequest(data) {
+    if (!isRequestEventPayload(data))
+      return;
     const requestType = data.request_type;
-    const subType = data.sub_type;
+    const subType = "sub_type" in data ? data.sub_type : void 0;
     const events = ["request", `request.${requestType}`];
     if (subType) {
       events.push(`request.${requestType}.${subType}`);
@@ -1067,6 +1094,18 @@ var EventRouter = class extends EventEmitter {
     }
   }
 };
+function isMessageEventPayload(data) {
+  return data.post_type === "message" || data.post_type === "message_sent";
+}
+function isNoticeEventPayload(data) {
+  return data.post_type === "notice";
+}
+function isRequestEventPayload(data) {
+  return data.post_type === "request";
+}
+function isMetaEventPayload(data) {
+  return data.post_type === "meta_event";
+}
 
 // src/core/dispatcher.ts
 var MessageDispatcher = class {
@@ -1082,7 +1121,8 @@ var MessageDispatcher = class {
   dispatch(message) {
     try {
       const data = JSON.parse(message);
-      if (data.echo) {
+      const isApiResponse = data && typeof data === "object" && ("echo" in data || "status" in data || "retcode" in data);
+      if (isApiResponse) {
         if (typeof data.echo === "string" && data.echo.startsWith("heartbeat_")) {
           return;
         }
@@ -1211,38 +1251,37 @@ function createMediaApi(client, logger) {
     async hydrateMedia(message) {
       if (!Array.isArray(message)) return;
       await Promise.all(message.map(async (segment) => {
+        if (!isHydratableSegment(segment)) return;
         const type = segment?.type;
         const data = segment?.data;
         if (!type || !data) return;
-        if (["image", "video", "record", "audio", "file"].includes(type)) {
-          const fileId = data.file ?? data.file_id;
-          if (typeof fileId === "string" && !/^https?:\/\//.test(fileId) && !fileId.startsWith("file://")) {
-            try {
-              const res = await api.getFile(fileId);
-              const hydratedUrl = res?.file ?? res?.url;
-              if (hydratedUrl) {
-                data.url = hydratedUrl;
-                data.file = hydratedUrl;
-                return;
+        const fileId = data.file ?? data.file_id;
+        if (typeof fileId === "string" && !/^https?:\/\//.test(fileId) && !fileId.startsWith("file://")) {
+          try {
+            const res = await api.getFile(fileId);
+            const hydratedUrl = res?.file ?? res?.url;
+            if (hydratedUrl) {
+              data.url = hydratedUrl;
+              data.file = hydratedUrl;
+              return;
+            }
+            if (type === "record" || type === "audio") {
+              const rec = await api.getRecord(fileId, "mp3");
+              const recUrl = rec?.file ?? rec?.url;
+              if (recUrl) {
+                data.url = recUrl;
+                data.file = recUrl;
               }
-              if (type === "record" || type === "audio") {
-                const rec = await api.getRecord(fileId, "mp3");
-                const recUrl = rec?.file ?? rec?.url;
-                if (recUrl) {
-                  data.url = recUrl;
-                  data.file = recUrl;
-                }
-              } else if (type === "image") {
-                const img = await api.getImage(fileId);
-                const imgUrl = img?.file ?? img?.url;
-                if (imgUrl) {
-                  data.url = imgUrl;
-                  data.file = imgUrl;
-                }
+            } else if (type === "image") {
+              const img = await api.getImage(fileId);
+              const imgUrl = img?.file ?? img?.url;
+              if (imgUrl) {
+                data.url = imgUrl;
+                data.file = imgUrl;
               }
-            } catch (e) {
-              logger.debug(`Failed to hydrate media for ${type}: ${fileId}`, e);
             }
+          } catch (e) {
+            logger.debug(`Failed to hydrate media for ${type}: ${fileId}`, e);
           }
         }
       }));
@@ -1250,6 +1289,9 @@ function createMediaApi(client, logger) {
   };
   return api;
 }
+function isHydratableSegment(segment) {
+  return ["image", "video", "record", "audio", "file"].includes(segment.type);
+}
 
 // src/api/onebot/account.ts
 function createAccountApi(client) {
@@ -2174,7 +2216,7 @@ var NapLink = class extends EventEmitter2 {
   disconnect() {
     this.logger.info("\u65AD\u5F00\u8FDE\u63A5...");
     this.connection.disconnect();
-    this.apiClient.destroy();
+    this.apiClient.clearPendingRequests("\u8FDE\u63A5\u5DF2\u65AD\u5F00");
   }
   /**
    * 获取连接状态
@@ -2207,6 +2249,15 @@ var NapLink = class extends EventEmitter2 {
   get api() {
     return this.oneBotApi;
   }
+  /**
+   * 销毁客户端实例
+   * 调用后不应再复用当前实例。
+   */
+  dispose() {
+    this.logger.info("\u9500\u6BC1\u5BA2\u6237\u7AEF...");
+    this.connection.disconnect();
+    this.apiClient.destroy();
+  }
   // ============ 内部方法 ============
   /**
    * 设置事件转发