@perk-net/perk-pushplus-sdk 1.0.0

package/src/callback.ts

@@ -0,0 +1,46 @@
+import { PushPlusError } from './exception';
+import { CallbackPayload } from './models';
+
+/**
+ * PushPlus 回调请求体解析工具。
+ *
+ * 用法：在你的回调接口中拿到原始 JSON body，直接传入 `parseCallback(body)` 即可。
+ *
+ * @example
+ * ```ts
+ * import { parseCallback, CallbackEvent } from '@perk-net/perk-pushplus-sdk';
+ *
+ * function onPushPlusCallback(rawBody: string) {
+ *   const payload = parseCallback(rawBody);
+ *   switch (payload.event) {
+ *     case CallbackEvent.MESSAGE_COMPLETE:
+ *       // payload.messageInfo
+ *       break;
+ *     case CallbackEvent.ADD_TOPIC_USER:
+ *       // payload.topicUserInfo
+ *       break;
+ *     case CallbackEvent.ADD_FRIEND:
+ *       // payload.friendInfo, payload.qrCode
+ *       break;
+ *   }
+ *   return 'ok';
+ * }
+ * ```
+ */
+export function parseCallback(json: string | object): CallbackPayload {
+  if (json == null) {
+    throw new PushPlusError('回调请求体不能为空');
+  }
+  if (typeof json === 'string') {
+    try {
+      return JSON.parse(json) as CallbackPayload;
+    } catch (e) {
+      throw new PushPlusError(`解析 PushPlus 回调失败: ${(e as Error).message}`, -1, { cause: e });
+    }
+  }
+  return json as CallbackPayload;
+}
+
+export const CallbackParser = {
+  parse: parseCallback,
+};

package/src/client.ts

@@ -0,0 +1,143 @@
+import { AccessKeyManager } from './access-key-manager';
+import { AccessKeyApi } from './api/access-key-api';
+import { ChannelApi } from './api/channel-api';
+import { ClawBotApi } from './api/clawbot-api';
+import { FriendApi } from './api/friend-api';
+import { MessageApi } from './api/message-api';
+import { MessageTokenApi } from './api/message-token-api';
+import { OpenMessageApi } from './api/open-message-api';
+import { PreApi } from './api/pre-api';
+import { SettingApi } from './api/setting-api';
+import { TopicApi } from './api/topic-api';
+import { TopicUserApi } from './api/topic-user-api';
+import { UserApi } from './api/user-api';
+import { WebhookApi } from './api/webhook-api';
+import { PushPlusConfig, ResolvedPushPlusConfig, resolveConfig } from './config';
+import { PushPlusError } from './exception';
+import { FetchHttpRequester, HttpRequester } from './http';
+import { BatchSendRequest, BatchSendResult, SendRequest } from './models';
+import { RateLimitGuard } from './rate-limit';
+
+export interface PushPlusClientOptions extends PushPlusConfig {
+  /** 自定义 HTTP 客户端实现。 */
+  httpRequester?: HttpRequester;
+}
+
+/**
+ * PushPlus SDK 统一入口。
+ *
+ * 兼容 Node.js（>=18 内置 fetch）与浏览器环境。
+ *
+ * @example 快速开始
+ * ```ts
+ * import { PushPlusClient } from '@perk-net/perk-pushplus-sdk';
+ *
+ * const client = new PushPlusClient({
+ *   token: 'your_user_token',
+ *   secretKey: 'your_secret_key',  // 调用开放接口才需要
+ * });
+ *
+ * // 发送消息
+ * const shortCode = await client.sendSimple('标题', 'Hello PushPlus');
+ *
+ * // 调用开放接口（无需手动管理 AccessKey）
+ * const info = await client.user.myInfo();
+ * ```
+ */
+export class PushPlusClient {
+  /** 已解析的不可变配置。 */
+  readonly config: ResolvedPushPlusConfig;
+  readonly httpRequester: HttpRequester;
+  readonly accessKeyManager: AccessKeyManager;
+  readonly rateLimitGuard: RateLimitGuard;
+
+  /* ---------------- 各 API ---------------- */
+  readonly message: MessageApi;
+  readonly accessKey: AccessKeyApi;
+  readonly openMessage: OpenMessageApi;
+  readonly user: UserApi;
+  readonly messageToken: MessageTokenApi;
+  readonly topic: TopicApi;
+  readonly topicUser: TopicUserApi;
+  readonly friend: FriendApi;
+  readonly webhook: WebhookApi;
+  readonly channel: ChannelApi;
+  readonly clawBot: ClawBotApi;
+  readonly setting: SettingApi;
+  readonly pre: PreApi;
+
+  constructor(options: PushPlusClientOptions = {}) {
+    this.config = resolveConfig(options);
+    this.httpRequester = options.httpRequester ?? new FetchHttpRequester(this.config);
+    this.rateLimitGuard = new RateLimitGuard(this.config);
+
+    this.message = new MessageApi(this.config, this.httpRequester, this.rateLimitGuard);
+    this.accessKey = new AccessKeyApi(this.config, this.httpRequester);
+    this.accessKeyManager = new AccessKeyManager(this.config, this.accessKey);
+
+    this.openMessage = new OpenMessageApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.user = new UserApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.messageToken = new MessageTokenApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.topic = new TopicApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.topicUser = new TopicUserApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.friend = new FriendApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.webhook = new WebhookApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.channel = new ChannelApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.clawBot = new ClawBotApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.setting = new SettingApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.pre = new PreApi(this.config, this.httpRequester, this.accessKeyManager);
+  }
+
+  /** 与 Java SDK 风格一致的 Builder 入口。 */
+  static builder(): PushPlusClientBuilder {
+    return new PushPlusClientBuilder();
+  }
+
+  /** 工厂方法。 */
+  static of(options: PushPlusClientOptions): PushPlusClient {
+    return new PushPlusClient(options);
+  }
+
+  /* ============================== 便捷转发方法 ============================== */
+
+  /** 发送一条简单消息（默认 wechat / html）。 */
+  sendSimple(title: string | undefined, content: string): Promise<string> {
+    return this.message.sendSimple(title, content);
+  }
+
+  /** 发送消息。 */
+  send(req: SendRequest): Promise<string> {
+    return this.message.send(req);
+  }
+
+  /** 多渠道发送消息。 */
+  batchSend(req: BatchSendRequest): Promise<BatchSendResult[]> {
+    return this.message.batchSend(req);
+  }
+}
+
+/**
+ * 链式 Builder，与 Java/Python SDK 风格保持一致。
+ */
+export class PushPlusClientBuilder {
+  private readonly opt: PushPlusClientOptions = {};
+
+  token(v?: string): this { this.opt.token = v; return this; }
+  secretKey(v?: string): this { this.opt.secretKey = v; return this; }
+  baseUrl(v?: string): this { this.opt.baseUrl = v; return this; }
+  connectTimeoutMs(v: number): this { this.opt.connectTimeoutMs = v; return this; }
+  readTimeoutMs(v: number): this { this.opt.readTimeoutMs = v; return this; }
+  accessKeyRefreshAheadSeconds(v: number): this { this.opt.accessKeyRefreshAheadSeconds = v; return this; }
+  logRequest(v: boolean): this { this.opt.logRequest = v; return this; }
+  rateLimitGuardEnabled(v: boolean): this { this.opt.rateLimitGuardEnabled = v; return this; }
+  rateLimitCooldownMs(v: number): this { this.opt.rateLimitCooldownMs = v; return this; }
+  userAgent(v: string): this { this.opt.userAgent = v; return this; }
+  httpRequester(req: HttpRequester): this { this.opt.httpRequester = req; return this; }
+
+  build(): PushPlusClient {
+    if (this.opt.token != null && this.opt.token.trim().length === 0) {
+      throw new PushPlusError('token 不能为空字符串');
+    }
+    return new PushPlusClient(this.opt);
+  }
+}

package/src/config.ts

@@ -0,0 +1,92 @@
+/**
+ * PushPlus SDK 全局配置。
+ *
+ * 通过 `PushPlusClient.builder()` 或直接 `new PushPlusClient(config)` 构建实例。
+ * 所有字段都有合理默认值，仅 `token` 是发送消息接口必填、`secretKey` 是开放接口必填。
+ */
+export interface PushPlusConfig {
+  /**
+   * 用户 token 或消息 token，发送消息接口默认使用。
+   * 注意：获取 AccessKey 必须使用用户 token。
+   */
+  token?: string;
+
+  /**
+   * 用户 secretKey，调用开放接口（获取 AccessKey）必填。
+   * 在 pushplus 个人中心 -> 开发设置 中配置。
+   */
+  secretKey?: string;
+
+  /**
+   * 服务器基础地址。默认：https://www.pushplus.plus
+   */
+  baseUrl?: string;
+
+  /** 连接超时（毫秒）。默认 10000。 */
+  connectTimeoutMs?: number;
+
+  /** 请求/读超时（毫秒）。默认 30000。 */
+  readTimeoutMs?: number;
+
+  /**
+   * 在 AccessKey 过期前提前多少秒刷新。默认提前 5 分钟（300 秒），
+   * 文档中提到老 AccessKey 在新 AccessKey 生成后 5 分钟内仍可用。
+   */
+  accessKeyRefreshAheadSeconds?: number;
+
+  /** 是否启用请求/响应详细日志。默认关闭。 */
+  logRequest?: boolean;
+
+  /**
+   * 是否启用本地限流守卫。默认开启。
+   *
+   * 开启后，当任意一次发送消息接口返回 code=900（请求次数过多）时，
+   * 后续对同一 token 的发送调用会被 SDK 直接短路，不再发起 HTTP，
+   * 直到 `rateLimitCooldownMs`（默认次日 0 点）到期。
+   */
+  rateLimitGuardEnabled?: boolean;
+
+  /**
+   * 命中 code=900 后的本地禁推时长（毫秒）。
+   * 不传或 <=0 表示使用默认策略：到「次日 0 点」。
+   *
+   * 注意：服务端实际禁推时长可能更长（文档示例为 2 天）。
+   */
+  rateLimitCooldownMs?: number;
+
+  /** 自定义 User-Agent。 */
+  userAgent?: string;
+}
+
+/** PushPlus 默认服务地址。 */
+export const DEFAULT_BASE_URL = 'https://www.pushplus.plus';
+
+export interface ResolvedPushPlusConfig {
+  token: string;
+  secretKey: string;
+  baseUrl: string;
+  connectTimeoutMs: number;
+  readTimeoutMs: number;
+  accessKeyRefreshAheadSeconds: number;
+  logRequest: boolean;
+  rateLimitGuardEnabled: boolean;
+  rateLimitCooldownMs: number;
+  userAgent: string;
+}
+
+export function resolveConfig(input: PushPlusConfig | undefined | null): ResolvedPushPlusConfig {
+  const cfg = input ?? {};
+  const baseUrl = (cfg.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+  return {
+    token: cfg.token ?? '',
+    secretKey: cfg.secretKey ?? '',
+    baseUrl: baseUrl || DEFAULT_BASE_URL,
+    connectTimeoutMs: cfg.connectTimeoutMs ?? 10000,
+    readTimeoutMs: cfg.readTimeoutMs ?? 30000,
+    accessKeyRefreshAheadSeconds: cfg.accessKeyRefreshAheadSeconds ?? 300,
+    logRequest: cfg.logRequest ?? false,
+    rateLimitGuardEnabled: cfg.rateLimitGuardEnabled ?? true,
+    rateLimitCooldownMs: cfg.rateLimitCooldownMs ?? 0,
+    userAgent: cfg.userAgent ?? `@perk-net/perk-pushplus-sdk/1.0.0`,
+  };
+}

package/src/enums.ts

@@ -0,0 +1,170 @@
+/**
+ * PushPlus 发送渠道枚举。
+ *
+ * 对应官方文档「发送渠道（channel）枚举」。
+ */
+export enum Channel {
+  /** 微信公众号（默认）。 */
+  WECHAT = 'wechat',
+  /** 第三方 webhook（企业微信/钉钉/飞书/bark/Gotify/Server酱/IFTTT/WxPusher 等）。 */
+  WEBHOOK = 'webhook',
+  /** 企业微信应用。 */
+  CP = 'cp',
+  /** 邮箱。 */
+  MAIL = 'mail',
+  /** 短信（收费）。 */
+  SMS = 'sms',
+  /** 语音（收费）。 */
+  VOICE = 'voice',
+  /** 浏览器扩展插件 / 桌面应用程序。 */
+  EXTENSION = 'extension',
+  /** App 渠道（安卓/鸿蒙/iOS）。 */
+  APP = 'app',
+  /** 微信 ClawBot。 */
+  CLAWBOT = 'clawbot',
+}
+
+/**
+ * PushPlus 消息模板枚举。
+ */
+export enum Template {
+  /** 默认模板，支持 HTML 文本。 */
+  HTML = 'html',
+  /** 纯文本，不转义 HTML。 */
+  TXT = 'txt',
+  /** 基于 JSON 格式展示。 */
+  JSON = 'json',
+  /** Markdown 格式。 */
+  MARKDOWN = 'markdown',
+  /** 阿里云监控报警定制模板。 */
+  CLOUD_MONITOR = 'cloudMonitor',
+  /** Jenkins 插件定制模板。 */
+  JENKINS = 'jenkins',
+  /** 路由器插件定制模板。 */
+  ROUTE = 'route',
+  /** 支付成功通知模板。 */
+  PAY = 'pay',
+}
+
+/**
+ * 消息投递状态。
+ *
+ * 0-未发送/未投递，1-发送中，2-发送成功，3-发送失败。
+ */
+export enum SendStatus {
+  NOT_SENT = 0,
+  SENDING = 1,
+  SUCCESS = 2,
+  FAILED = 3,
+}
+
+export const SendStatusDescription: Record<SendStatus, string> = {
+  [SendStatus.NOT_SENT]: '未发送',
+  [SendStatus.SENDING]: '发送中',
+  [SendStatus.SUCCESS]: '发送成功',
+  [SendStatus.FAILED]: '发送失败',
+};
+
+/**
+ * 回调事件类型。
+ */
+export enum CallbackEvent {
+  /** 消息发送完成。 */
+  MESSAGE_COMPLETE = 'message_complate',
+  /** 群组新增用户。 */
+  ADD_TOPIC_USER = 'add_topic_user',
+  /** 新增好友。 */
+  ADD_FRIEND = 'add_friend',
+}
+
+/**
+ * Webhook 渠道类型。
+ *
+ * 对应开放接口文档「webhook 列表」中的 webhookType 枚举值。
+ */
+export enum WebhookType {
+  WORK_WECHAT_BOT = 1,
+  DING_TALK_BOT = 2,
+  FEISHU_BOT = 3,
+  SERVER_CHAN = 4,
+  BARK = 50,
+  WORK_WECHAT_APP = 6,
+  TENCENT_LIGHT_LINK = 7,
+  IFTTT = 8,
+  JI_JIAN_YUN = 9,
+  GOTIFY = 10,
+  WX_PUSHER = 11,
+  CUSTOM = 12,
+}
+
+export const WebhookTypeDescription: Record<number, string> = {
+  [WebhookType.WORK_WECHAT_BOT]: '企业微信机器人',
+  [WebhookType.DING_TALK_BOT]: '钉钉机器人',
+  [WebhookType.FEISHU_BOT]: '飞书机器人',
+  [WebhookType.SERVER_CHAN]: 'Server酱',
+  [WebhookType.BARK]: 'bark',
+  [WebhookType.WORK_WECHAT_APP]: '企业微信应用',
+  [WebhookType.TENCENT_LIGHT_LINK]: '腾讯轻联',
+  [WebhookType.IFTTT]: 'IFTTT',
+  [WebhookType.JI_JIAN_YUN]: '集简云',
+  [WebhookType.GOTIFY]: 'Gotify',
+  [WebhookType.WX_PUSHER]: 'WxPusher',
+  [WebhookType.CUSTOM]: '自定义',
+};
+
+/**
+ * PushPlus 接口业务返回码语义。
+ *
+ * 对应官方文档「接口返回码说明」：https://www.pushplus.plus/doc/guide/code.html
+ */
+export enum ErrorCode {
+  /** 200 执行成功。 */
+  OK = 200,
+  /** 302 未登录。 */
+  NOT_LOGIN = 302,
+  /** 401 请求未授权（开放接口未启用）。 */
+  UNAUTHORIZED = 401,
+  /** 403 请求 IP 未授权（白名单未配置）。 */
+  IP_FORBIDDEN = 403,
+  /** 500 系统异常，请稍后再试。 */
+  SERVER_ERROR = 500,
+  /** 600 数据异常，操作失败。 */
+  DATA_ERROR = 600,
+  /** 805 无权查看。 */
+  FORBIDDEN_VIEW = 805,
+  /** 888 积分不足，需要充值。 */
+  INSUFFICIENT_POINTS = 888,
+  /** 900 用户账号使用受限（请求次数过多）。 */
+  RATE_LIMITED = 900,
+  /** 905 账户未进行实名认证。 */
+  NOT_VERIFIED = 905,
+  /** 903 无效的用户令牌。 */
+  INVALID_TOKEN = 903,
+  /** 999 服务端验证错误。 */
+  VALIDATION_ERROR = 999,
+  /** 其它未在文档中列出的 code。 */
+  UNKNOWN = -1,
+}
+
+export function errorCodeFromValue(code: number | null | undefined): ErrorCode {
+  if (code == null) return ErrorCode.UNKNOWN;
+  const known = [
+    ErrorCode.OK,
+    ErrorCode.NOT_LOGIN,
+    ErrorCode.UNAUTHORIZED,
+    ErrorCode.IP_FORBIDDEN,
+    ErrorCode.SERVER_ERROR,
+    ErrorCode.DATA_ERROR,
+    ErrorCode.FORBIDDEN_VIEW,
+    ErrorCode.INSUFFICIENT_POINTS,
+    ErrorCode.RATE_LIMITED,
+    ErrorCode.NOT_VERIFIED,
+    ErrorCode.INVALID_TOKEN,
+    ErrorCode.VALIDATION_ERROR,
+  ];
+  return known.includes(code as ErrorCode) ? (code as ErrorCode) : ErrorCode.UNKNOWN;
+}
+
+export function isRateLimitedCode(code: number | null | undefined): boolean {
+  return code != null && code === ErrorCode.RATE_LIMITED;
+}

package/src/exception.ts

@@ -0,0 +1,48 @@
+import { ErrorCode, errorCodeFromValue, isRateLimitedCode } from './enums';
+
+/**
+ * PushPlus SDK 统一运行时异常。
+ *
+ * 该异常会在以下场景抛出：
+ * - HTTP 请求失败（网络异常、非 2xx 状态码）
+ * - PushPlus 业务接口返回 code != 200
+ * - JSON 序列化/反序列化异常
+ * - SDK 参数校验失败
+ * - 本地限流守卫命中（code=900 后被短路），不会真正发起 HTTP 请求
+ */
+export class PushPlusError extends Error {
+  /** PushPlus 接口返回的业务 code。HTTP 错误时为对应的 HTTP 状态码；其他为 -1。 */
+  public readonly code: number;
+
+  /** 同 message。便于和其它语言 SDK 风格一致。 */
+  public get businessMessage(): string {
+    return this.message;
+  }
+
+  constructor(message: string, code: number = -1, options?: { cause?: unknown }) {
+    super(message);
+    this.name = 'PushPlusError';
+    this.code = code;
+    if (options?.cause !== undefined) {
+      // Node 16+ 支持 Error cause
+      (this as any).cause = options.cause;
+    }
+    // 修复部分环境下 instanceof 失效问题
+    Object.setPrototypeOf(this, PushPlusError.prototype);
+  }
+
+  /** 把数值 code 映射为 ErrorCode 枚举（未知为 UNKNOWN）。 */
+  get errorCode(): ErrorCode {
+    return errorCodeFromValue(this.code);
+  }
+
+  /** 是否为 PushPlus 限流（code=900）。命中后建议当天停止继续调用发送消息接口。 */
+  isRateLimited(): boolean {
+    return isRateLimitedCode(this.code);
+  }
+}
+
+/**
+ * 兼容 Java SDK 命名（PushPlusException）的别名导出。
+ */
+export const PushPlusException = PushPlusError;

package/src/http.ts

@@ -0,0 +1,117 @@
+import { ResolvedPushPlusConfig } from './config';
+import { PushPlusError } from './exception';
+
+export interface HttpRequestOptions {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: string | null;
+}
+
+export interface HttpResponse {
+  statusCode: number;
+  body: string;
+}
+
+/**
+ * HTTP 请求执行器抽象。
+ *
+ * SDK 默认提供基于 `fetch` 的实现（Node 18+ 内置 / 浏览器原生）。
+ * 调用方也可以自行实现并通过 `PushPlusClient` 注入以使用其它客户端（如 axios/undici/got）。
+ */
+export interface HttpRequester {
+  execute(options: HttpRequestOptions): Promise<HttpResponse>;
+}
+
+/**
+ * 基于 fetch 的请求执行器。
+ *
+ * - Node.js：18+ 自带全局 fetch；< 18 需要使用 polyfill 或自定义 HttpRequester。
+ * - 浏览器：所有现代浏览器原生支持。
+ *
+ * 实现是无状态的，可作为 SDK 单例长期复用。
+ */
+export class FetchHttpRequester implements HttpRequester {
+  private readonly readTimeoutMs: number;
+  private readonly logRequest: boolean;
+  private readonly userAgent: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(config: ResolvedPushPlusConfig, fetchImpl?: typeof fetch) {
+    this.readTimeoutMs = config.readTimeoutMs;
+    this.logRequest = config.logRequest;
+    this.userAgent = config.userAgent;
+    const resolved = fetchImpl ?? (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : undefined);
+    if (!resolved) {
+      throw new PushPlusError(
+        '当前运行环境没有可用的 fetch 实现。请在 Node.js 18+ 中运行，' +
+          '或自行注入 HttpRequester 实例。',
+      );
+    }
+    this.fetchImpl = resolved;
+  }
+
+  async execute(options: HttpRequestOptions): Promise<HttpResponse> {
+    const { method, url, headers, body } = options;
+    const finalHeaders: Record<string, string> = {};
+
+    let hasContentType = false;
+    if (headers) {
+      for (const [k, v] of Object.entries(headers)) {
+        if (k == null || v == null) continue;
+        finalHeaders[k] = v;
+        if (k.toLowerCase() === 'content-type') hasContentType = true;
+      }
+    }
+    if (body != null && !hasContentType) {
+      finalHeaders['Content-Type'] = 'application/json;charset=UTF-8';
+    }
+    // 浏览器中不允许设置 User-Agent，仅在非浏览器环境下添加
+    if (typeof window === 'undefined' && !finalHeaders['User-Agent'] && !finalHeaders['user-agent']) {
+      finalHeaders['User-Agent'] = this.userAgent;
+    }
+
+    if (this.logRequest) {
+      // eslint-disable-next-line no-console
+      console.debug('[pushplus] >>>', method, url, 'body=', body);
+    }
+
+    const controller = new AbortController();
+    const timer = this.readTimeoutMs > 0 ? setTimeout(() => controller.abort(), this.readTimeoutMs) : null;
+
+    try {
+      const init: RequestInit = {
+        method: method.toUpperCase(),
+        headers: finalHeaders,
+        signal: controller.signal,
+      };
+      if (body != null) {
+        init.body = body;
+      }
+      const resp = await this.fetchImpl(url, init);
+      const respBody = await resp.text();
+      if (this.logRequest) {
+        // eslint-disable-next-line no-console
+        console.debug('[pushplus] <<< status=', resp.status, 'body=', respBody);
+      }
+      return { statusCode: resp.status, body: respBody };
+    } catch (e: unknown) {
+      const err = e as { name?: string; message?: string };
+      if (err && err.name === 'AbortError') {
+        throw new PushPlusError(`调用 PushPlus 接口超时(${this.readTimeoutMs}ms): ${err.message ?? ''}`, -1, {
+          cause: e,
+        });
+      }
+      throw new PushPlusError(`调用 PushPlus 接口失败: ${err?.message ?? String(e)}`, -1, { cause: e });
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+}
+
+/**
+ * 是否处于成功的 HTTP 状态码区间（2xx）。
+ */
+export function isSuccessfulHttpStatus(status: number): boolean {
+  return status >= 200 && status < 300;
+}