@perk-net/perk-pushplus-sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1208 @@
+/**
+ * PushPlus SDK 全局配置。
+ *
+ * 通过 `PushPlusClient.builder()` 或直接 `new PushPlusClient(config)` 构建实例。
+ * 所有字段都有合理默认值，仅 `token` 是发送消息接口必填、`secretKey` 是开放接口必填。
+ */
+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 默认服务地址。 */
+declare const DEFAULT_BASE_URL = "https://www.pushplus.plus";
+interface ResolvedPushPlusConfig {
+    token: string;
+    secretKey: string;
+    baseUrl: string;
+    connectTimeoutMs: number;
+    readTimeoutMs: number;
+    accessKeyRefreshAheadSeconds: number;
+    logRequest: boolean;
+    rateLimitGuardEnabled: boolean;
+    rateLimitCooldownMs: number;
+    userAgent: string;
+}
+declare function resolveConfig(input: PushPlusConfig | undefined | null): ResolvedPushPlusConfig;
+
+interface HttpRequestOptions {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string | null;
+}
+interface HttpResponse {
+    statusCode: number;
+    body: string;
+}
+/**
+ * HTTP 请求执行器抽象。
+ *
+ * SDK 默认提供基于 `fetch` 的实现（Node 18+ 内置 / 浏览器原生）。
+ * 调用方也可以自行实现并通过 `PushPlusClient` 注入以使用其它客户端（如 axios/undici/got）。
+ */
+interface HttpRequester {
+    execute(options: HttpRequestOptions): Promise<HttpResponse>;
+}
+/**
+ * 基于 fetch 的请求执行器。
+ *
+ * - Node.js：18+ 自带全局 fetch；< 18 需要使用 polyfill 或自定义 HttpRequester。
+ * - 浏览器：所有现代浏览器原生支持。
+ *
+ * 实现是无状态的，可作为 SDK 单例长期复用。
+ */
+declare class FetchHttpRequester implements HttpRequester {
+    private readonly readTimeoutMs;
+    private readonly logRequest;
+    private readonly userAgent;
+    private readonly fetchImpl;
+    constructor(config: ResolvedPushPlusConfig, fetchImpl?: typeof fetch);
+    execute(options: HttpRequestOptions): Promise<HttpResponse>;
+}
+/**
+ * 是否处于成功的 HTTP 状态码区间（2xx）。
+ */
+declare function isSuccessfulHttpStatus(status: number): boolean;
+
+/**
+ * PushPlus 发送渠道枚举。
+ *
+ * 对应官方文档「发送渠道（channel）枚举」。
+ */
+declare 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 消息模板枚举。
+ */
+declare 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-发送失败。
+ */
+declare enum SendStatus {
+    NOT_SENT = 0,
+    SENDING = 1,
+    SUCCESS = 2,
+    FAILED = 3
+}
+declare const SendStatusDescription: Record<SendStatus, string>;
+/**
+ * 回调事件类型。
+ */
+declare enum CallbackEvent {
+    /** 消息发送完成。 */
+    MESSAGE_COMPLETE = "message_complate",
+    /** 群组新增用户。 */
+    ADD_TOPIC_USER = "add_topic_user",
+    /** 新增好友。 */
+    ADD_FRIEND = "add_friend"
+}
+/**
+ * Webhook 渠道类型。
+ *
+ * 对应开放接口文档「webhook 列表」中的 webhookType 枚举值。
+ */
+declare 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
+}
+declare const WebhookTypeDescription: Record<number, string>;
+/**
+ * PushPlus 接口业务返回码语义。
+ *
+ * 对应官方文档「接口返回码说明」：https://www.pushplus.plus/doc/guide/code.html
+ */
+declare 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
+}
+declare function errorCodeFromValue(code: number | null | undefined): ErrorCode;
+declare function isRateLimitedCode(code: number | null | undefined): boolean;
+
+/**
+ * PushPlus 接口统一响应。所有接口都遵循 `{code, msg, data}` 结构。
+ */
+interface ApiResponse<T = unknown> {
+    code?: number;
+    msg?: string;
+    data?: T;
+}
+/** 通用分页请求参数。 */
+interface PageQuery {
+    /** 当前所在分页数，默认 1。 */
+    current?: number;
+    /** 每页大小，默认 20，最大 50。 */
+    pageSize?: number;
+}
+/** 分页响应结构。 */
+interface PageResult<T> {
+    pageNum?: number;
+    pageSize?: number;
+    total?: number;
+    pages?: number;
+    list?: T[];
+}
+/**
+ * 发送消息请求。对应 `/send` 接口。
+ *
+ * 推荐使用 `SendRequestBuilder`（`SendRequest.builder()`）链式构建。
+ */
+interface SendRequest {
+    /** 用户 token 或消息 token。可不填，由 SDK 从 PushPlusConfig 自动注入。 */
+    token?: string;
+    /** 消息标题。 */
+    title?: string;
+    /** 消息内容；必填。 */
+    content?: string;
+    /** 群组编码。不填仅发送给自己；channel 为 webhook 时无效。 */
+    topic?: string;
+    /** 发送模板，默认 html。 */
+    template?: Template | string;
+    /** 发送渠道，默认 wechat。 */
+    channel?: Channel | string;
+    /** 渠道配置参数（cp/webhook/mail 渠道使用渠道编码）。 */
+    option?: string;
+    /** 异步回调地址。 */
+    callbackUrl?: string;
+    /** 毫秒时间戳；服务器时间大于此时间戳消息不会发送。 */
+    timestamp?: number;
+    /** 好友令牌；多个用逗号分隔。 */
+    to?: string;
+    /** 预处理编码（仅会员）。 */
+    pre?: string;
+}
+declare class SendRequestBuilder {
+    private req;
+    token(v?: string): this;
+    title(v?: string): this;
+    content(v?: string): this;
+    topic(v?: string): this;
+    template(v?: Template | string): this;
+    channel(v?: Channel | string): this;
+    option(v?: string): this;
+    callbackUrl(v?: string): this;
+    timestamp(v?: number): this;
+    to(v?: string): this;
+    pre(v?: string): this;
+    build(): SendRequest;
+}
+/**
+ * 创建 SendRequest 链式构造器。
+ */
+declare function sendRequest(): SendRequestBuilder;
+/**
+ * 多渠道发送消息请求。对应 `/batchSend` 接口。
+ */
+interface BatchSendRequest {
+    token?: string;
+    title?: string;
+    content?: string;
+    topic?: string;
+    template?: Template | string;
+    /** 多渠道，逗号分隔。 */
+    channel?: string;
+    /** 多渠道 option，逗号分隔；与 channel 一一对应。 */
+    option?: string;
+    callbackUrl?: string;
+    timestamp?: number;
+    to?: string;
+    pre?: string;
+}
+/**
+ * 链式 Builder：支持以 `channel(Channel)` / `option(string)` 形式累积调用，
+ * 内部自动用逗号拼接并按顺序一一对应。
+ *
+ * 也可以通过 `channelString`/`optionString` 直接指定 CSV 字符串。
+ * 累积式优先级高于 CSV 字符串。
+ */
+declare class BatchSendRequestBuilder {
+    private req;
+    private readonly channelList;
+    private readonly optionList;
+    token(v?: string): this;
+    title(v?: string): this;
+    content(v?: string): this;
+    topic(v?: string): this;
+    template(v?: Template | string): this;
+    callbackUrl(v?: string): this;
+    timestamp(v?: number): this;
+    to(v?: string): this;
+    pre(v?: string): this;
+    /** 追加一个 channel。 */
+    channel(ch: Channel | string): this;
+    /** 追加一个 option，与最近一次 channel() 配对；可传空串。 */
+    option(opt?: string): this;
+    /** 直接以 CSV 形式指定多渠道字符串（与累积式 channel(Channel) 互斥）。 */
+    channelString(csv?: string): this;
+    /** 直接以 CSV 形式指定 option 字符串。 */
+    optionString(csv?: string): this;
+    build(): BatchSendRequest;
+}
+/**
+ * 创建 BatchSendRequest 链式构造器。
+ */
+declare function batchSendRequest(): BatchSendRequestBuilder;
+/** 批量发送的单条渠道结果。 */
+interface BatchSendResult {
+    /** 消息流水号；可用于查询发送结果。 */
+    shortCode?: string;
+    /** 业务消息。 */
+    message?: string;
+    /** 业务 code。 */
+    code?: number;
+    /** 渠道。 */
+    channel?: Channel | string;
+}
+interface MessageCompleteInfo {
+    /** 推送错误内容（如有）。 */
+    message?: string;
+    /** 消息流水号。 */
+    shortCode?: string;
+    /** 发送状态：0-未发送，1-发送中，2-发送成功，3-发送失败。 */
+    sendStatus?: SendStatus | number;
+}
+interface TopicUserInfo {
+    id?: number;
+    openId?: string;
+    topicId?: number;
+    userSex?: number;
+    isFollow?: number;
+    nickName?: string;
+    havePhone?: number;
+    topicCode?: string;
+    topicName?: string;
+    headImgUrl?: string;
+    emailStatus?: number;
+}
+interface FriendInfo {
+    token?: string;
+    friendId?: number;
+    isFollow?: number;
+    nickName?: string;
+    havePhone?: number;
+    createTime?: string;
+    emailStatus?: number;
+}
+/**
+ * PushPlus 回调统一载体。
+ *
+ * 使用 `parseCallback(json)` 解析回调请求体后，
+ * 根据 `event` 判断事件类型并取对应的字段。
+ */
+interface CallbackPayload {
+    event?: CallbackEvent | string;
+    messageInfo?: MessageCompleteInfo;
+    topicUserInfo?: TopicUserInfo;
+    friendInfo?: FriendInfo;
+    /** 自定义二维码参数（仅 add_friend 事件有值）。 */
+    qrCode?: string;
+}
+interface AccessKeyResult {
+    /** 访问令牌，后续请求需加到 header 中。 */
+    accessKey?: string;
+    /** 过期时间（单位秒）。 */
+    expiresIn?: number;
+}
+interface UserInfo {
+    openId?: string;
+    unionId?: string;
+    nickName?: string;
+    headImgUrl?: string;
+    userSex?: number;
+    token?: string;
+    phoneNumber?: string;
+    email?: string;
+    emailStatus?: number;
+    birthday?: string;
+    points?: number;
+}
+interface SendCount {
+    wechatSendCount?: number;
+    cpSendCount?: number;
+    webhookSendCount?: number;
+    mailSendCount?: number;
+}
+interface UserLimitTime {
+    /** 1-无限制，2-短期限制，3-永久限制。 */
+    sendLimit?: number;
+    userLimitTime?: string;
+}
+interface MessageItem {
+    topicName?: string;
+    /** 消息类型：1-一对一消息，2-一对多消息。 */
+    messageType?: number;
+    title?: string;
+    shortCode?: string;
+    channel?: Channel | string;
+    updateTime?: string;
+}
+interface SendMessageResult {
+    /** 0-未投递，1-发送中，2-已发送，3-发送失败。 */
+    status?: SendStatus | number;
+    errorMessage?: string;
+    updateTime?: string;
+}
+interface MessageTokenAddRequest {
+    /** 令牌名称；必填。 */
+    name: string;
+    /** 过期时间，格式 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss；不填默认 2999-12-31。 */
+    expireTime?: string;
+}
+interface MessageTokenEditRequest {
+    id: number;
+    name?: string;
+    expireTime?: string;
+}
+interface MessageTokenItem {
+    id?: number;
+    name?: string;
+    expireTime?: string;
+    token?: string;
+}
+interface MessageTokenOption {
+    id?: number;
+    name?: string;
+}
+interface TopicListQuery {
+    current?: number;
+    pageSize?: number;
+    /** 例如 { topicType: 0 }；0-我创建的，1-我加入的。 */
+    params?: Record<string, unknown>;
+}
+interface TopicQrCode {
+    qrCodeImgUrl?: string;
+    /** 0-临时二维码，1-永久二维码。 */
+    forever?: number;
+}
+interface TopicAddRequest {
+    topicCode?: string;
+    topicName?: string;
+    contact?: string;
+    introduction?: string;
+    receiptMessage?: string;
+    appId?: string;
+    icon?: string;
+    /** 0普通；1积分；2公开。默认 0。 */
+    topicType?: number;
+    price?: number | string;
+    topicDescribe?: string;
+}
+interface TopicEditRequest {
+    /** 群组编号，必填。 */
+    topic: number;
+    topicCode?: string;
+    topicName?: string;
+    contact?: string;
+    introduction?: string;
+    receiptMessage?: string;
+    icon?: string;
+    price?: number | string;
+    topicDescribe?: string;
+}
+interface TopicDetail {
+    topicId?: number;
+    topicName?: string;
+    topicCode?: string;
+    qrCodeImgUrl?: string;
+    contact?: string;
+    introduction?: string;
+    receiptMessage?: string;
+    nickName?: string;
+    createTime?: string;
+    topicUserCount?: number;
+    icon?: string;
+    appId?: string;
+    topicType?: number;
+    price?: number | string;
+    topicDescribe?: string;
+    userNickName?: string;
+    isApproved?: number;
+    firstIsApproved?: number;
+    approveReason?: string;
+    isOpen?: number;
+}
+interface TopicItem {
+    icon?: string;
+    topicId?: number;
+    topicCode?: string;
+    topicName?: string;
+    nickName?: string;
+    createTime?: string;
+    topicUserCount?: number;
+    /** 0普通群组；1积分群组；2公开群组。 */
+    topicType?: number;
+    isApproved?: number;
+    firstIsApproved?: number;
+    approveReason?: string;
+    /** 0否，1是。 */
+    isOpen?: number;
+}
+interface TopicUserItem {
+    id?: number;
+    nickName?: string;
+    openId?: string;
+    headImgUrl?: string;
+    userSex?: number;
+    havePhone?: number;
+    isFollow?: number;
+    emailStatus?: number;
+    followTime?: string;
+    remark?: string;
+}
+interface TopicUserListQuery {
+    current?: number;
+    pageSize?: number;
+    /** 例如 { topicId }。 */
+    params?: Record<string, unknown>;
+}
+interface WebhookItem {
+    id?: number;
+    webhookCode?: string;
+    webhookName?: string;
+    webhookType?: WebhookType | number;
+    webhookTypeName?: string;
+    webhookUrl?: string;
+    createTime?: string;
+    /** 自定义类型才返回。 */
+    httpMethod?: string;
+    headers?: string;
+    body?: string;
+}
+interface WebhookSaveRequest {
+    /** 仅修改时使用。 */
+    id?: number;
+    webhookCode?: string;
+    webhookName?: string;
+    webhookType?: WebhookType | number;
+    webhookUrl?: string;
+    /** 自定义类型时使用。 */
+    httpMethod?: string;
+    headers?: string;
+    body?: string;
+}
+interface FriendItem {
+    id?: number;
+    friendId?: number;
+    token?: string;
+    headImgUrl?: string;
+    nickName?: string;
+    emailStatus?: number;
+    havePhone?: number;
+    isFollow?: number;
+    remark?: string;
+    createTime?: string;
+}
+interface FriendQrCode {
+    qrCodeImgUrl?: string;
+}
+interface ClawBotInfo {
+    createTime?: string;
+    /** 是否有对话令牌（文档为字符串/数字混用，统一用 number 兼容）。 */
+    haveContextToken?: number;
+}
+interface ClawBotMessage {
+    /** 1-文字，3-语音。 */
+    type?: number;
+    text?: string;
+}
+interface ClawBotQrCode {
+    url?: string;
+    qrcode?: string;
+}
+interface MpItem {
+    id?: number;
+    nickName?: string;
+    headImg?: string;
+    principalName?: string;
+    authorizationAppid?: string;
+    funcInfo?: string;
+    serviceType?: number;
+    verifyType?: number;
+    alias?: string;
+    updateTime?: string;
+}
+interface CpItem {
+    id?: number;
+    cpName?: string;
+    cpCode?: string;
+}
+interface MailItem {
+    id?: number;
+    mailName?: string;
+    mailCode?: string;
+}
+interface MailDetail {
+    id?: number;
+    mailName?: string;
+    mailCode?: string;
+    account?: string;
+    password?: string;
+    smtpServer?: string;
+    smtpSsl?: number;
+    smtpPort?: number;
+    createTime?: string;
+}
+interface UserDefaultDetail {
+    id?: number;
+    channel?: Channel | string;
+    option?: string;
+    pre?: string;
+    updateTime?: string;
+    name?: string;
+    tokenId?: number;
+}
+interface UserDefaultItem {
+    id?: number;
+    channel?: Channel | string;
+    channelTxt?: string;
+    updateTime?: string;
+    name?: string;
+}
+interface UserDefaultSaveRequest {
+    /** 默认配置编号（修改时必填）。 */
+    id?: number;
+    channel?: Channel | string;
+    option?: string;
+    pre?: string;
+    /** 消息令牌 id；用户令牌为 0。 */
+    tokenId?: number;
+}
+interface PreItem {
+    id?: number;
+    preName?: string;
+    preCode?: string;
+    /** 1-JavaScript。 */
+    contentType?: number;
+    createTime?: string;
+}
+interface PreDetail {
+    id?: number;
+    preName?: string;
+    preCode?: string;
+    contentType?: number;
+    content?: string;
+}
+interface PreSaveRequest {
+    /** 修改时必填。 */
+    id?: number;
+    content?: string;
+    preName?: string;
+    preCode?: string;
+    /** 1-JavaScript。 */
+    contentType?: number;
+}
+interface PreTestRequest {
+    content?: string;
+    contentType?: number;
+    message?: string;
+}
+
+/**
+ * API 基类，提供请求执行与统一错误处理。
+ */
+declare abstract class AbstractApi {
+    protected readonly config: ResolvedPushPlusConfig;
+    protected readonly http: HttpRequester;
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester);
+    /** 拼接绝对 URL。 */
+    protected resolveUrl(path: string): string;
+    /** 把对象拼成 query string。 */
+    protected buildQuery(params: Record<string, unknown> | undefined | null): string;
+    /** 在 path 上追加 query string。 */
+    protected appendQuery(path: string, params: Record<string, unknown> | undefined | null): string;
+    /**
+     * 执行请求并返回原始 ApiResponse（不进行 code 校验）。
+     */
+    protected execute<T>(method: string, path: string, headers: Record<string, string> | undefined | null, body: unknown): Promise<ApiResponse<T>>;
+    /** 执行请求并直接返回 data；非 200 抛出异常。 */
+    protected executeForData<T>(method: string, path: string, headers: Record<string, string> | undefined | null, body: unknown): Promise<T>;
+}
+
+/**
+ * AccessKey 接口。对应文档「一. 获取 AccessKey」。
+ */
+declare class AccessKeyApi extends AbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester);
+    /** 使用配置中的 token + secretKey 获取 AccessKey。 */
+    getAccessKey(): Promise<AccessKeyResult>;
+    /** 使用指定 token + secretKey 获取 AccessKey。 */
+    getAccessKey(token: string, secretKey: string): Promise<AccessKeyResult>;
+}
+
+/**
+ * AccessKey 管理器。
+ *
+ * 提供线程/异步并发安全的 AccessKey 缓存 + 过期前自动刷新能力。
+ *
+ * 在调用任意需要 access-key 的开放接口前，OpenAbstractApi 会自动通过本类拿到一个有效的 AccessKey。
+ *
+ * 刷新策略：在 expiresIn 到期前 `accessKeyRefreshAheadSeconds` 秒视为过期。
+ * 文档说明老 key 在新 key 生成后 5 分钟内仍可用，因此默认 300 秒提前量足够安全。
+ */
+declare class AccessKeyManager {
+    private readonly config;
+    private readonly api;
+    private cachedKey;
+    /** 最早过期时间戳（毫秒，含提前量）；到达此刻必须刷新。 */
+    private expireAtMs;
+    /** 并发刷新去重。 */
+    private inflight;
+    constructor(config: ResolvedPushPlusConfig, api: AccessKeyApi);
+    /** 获取有效的 AccessKey。如已缓存且未过期则直接返回；否则触发刷新。 */
+    getAccessKey(): Promise<string>;
+    /** 强制刷新。多次并发调用时仅会真正发起一次刷新请求。 */
+    refresh(): Promise<string>;
+    /** 失效缓存。下次调用 getAccessKey() 时会重新拉取。 */
+    invalidate(): void;
+    private doRefresh;
+    private isValid;
+}
+
+/**
+ * 开放接口基类。会自动在 header 中带上 access-key，
+ * 并在收到 401 类业务错误时尝试重试一次（刷新 AccessKey 后重试）。
+ */
+declare abstract class OpenAbstractApi extends AbstractApi {
+    static readonly HEADER_ACCESS_KEY = "access-key";
+    /** PushPlus AccessKey 失效相关的业务码（用于触发自动重试）。 */
+    private static readonly CODE_ACCESS_KEY_INVALID;
+    protected readonly accessKeyManager: AccessKeyManager;
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, accessKeyManager: AccessKeyManager);
+    private headersWithAccessKey;
+    /**
+     * 执行带 access-key 的请求；当返回 code=401 时自动刷新 key 并重试一次。
+     */
+    protected executeOpen<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+
+/**
+ * 开放接口 - 微信公众号/企业微信/邮箱渠道列表（文档「七. 渠道配置接口」 5-8）。
+ */
+declare class ChannelApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 5. 微信公众号渠道列表。 */
+    mpList(q?: PageQuery): Promise<PageResult<MpItem>>;
+    /** 6. 企业微信应用渠道列表。 */
+    cpList(q?: PageQuery): Promise<PageResult<CpItem>>;
+    /** 7. 邮箱渠道列表。 */
+    mailList(q?: PageQuery): Promise<PageResult<MailItem>>;
+    /** 8. 邮箱渠道详情。 */
+    mailDetail(mailId: number): Promise<MailDetail>;
+}
+
+/**
+ * 开放接口 - 微信 ClawBot（文档「八. 微信ClawBot接口」）。
+ */
+declare class ClawBotApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 1. 获取二维码。 */
+    getBotQrcode(): Promise<ClawBotQrCode>;
+    /** 2. 扫码结果查询。 */
+    getQrcodeStatus(qrcode: string): Promise<void>;
+    /** 3. 绑定详情。 */
+    botInfo(): Promise<ClawBotInfo>;
+    /** 4. 解绑。 */
+    unbind(): Promise<void>;
+    /** 5. 获取发送消息。 */
+    getMsg(): Promise<ClawBotMessage[]>;
+}
+
+/**
+ * 开放接口 - 好友功能（文档「十. 好友功能接口」）。
+ */
+declare class FriendApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 1. 获取个人二维码。 */
+    getQrCode(options: {
+        appId?: string;
+        content?: string;
+        second?: number;
+        scanCount?: number;
+    }): Promise<FriendQrCode>;
+    /** 2. 获取好友列表。 */
+    list(query?: PageQuery): Promise<PageResult<FriendItem>>;
+    /** 3. 删除好友。 */
+    delete(friendId: number): Promise<void>;
+    /** 4. 修改好友备注。 */
+    editRemark(id: number, remark: string): Promise<void>;
+}
+
+/**
+ * 本地限流守卫：当 PushPlus 服务端返回 ErrorCode.RATE_LIMITED（code=900）时，
+ * 在内存里按 token 维度记录"解禁时间"，期间任何发送类调用都会直接抛 PushPlusError，
+ * 不再发起 HTTP，避免继续打到上游浪费请求并加重账号限制。
+ *
+ * 对应官方文档建议：https://www.pushplus.plus/doc/guide/code.html
+ *
+ * 默认禁推到「次日 0 点」自动解禁；也可以通过 rateLimitCooldownMs 配置一个固定时长。
+ *
+ * 仅本地视角：服务端实际禁推时长可能与本地估算不同（文档示例为 2 天）。
+ */
+declare class RateLimitGuard {
+    private readonly enabled;
+    private readonly cooldownMs;
+    private readonly blockedUntil;
+    constructor(config: ResolvedPushPlusConfig);
+    /**
+     * 在发起发送类请求前调用：若当前 token 处于限流期，直接抛 PushPlusError
+     * （code = ErrorCode.RATE_LIMITED），不会发起 HTTP。
+     */
+    check(token: string | undefined | null): void;
+    /**
+     * 在收到服务端 code=900 后调用：登记限流状态，直到 cooldownUntil 到期。
+     */
+    markBlocked(token: string | undefined | null): void;
+    /** 仅供测试或运维手动清除（例如已确认服务端解禁）。 */
+    clear(token: string | undefined | null): void;
+    /** 返回该 token 的解禁时间（毫秒时间戳）；未被限流则为 null。 */
+    blockedUntilAt(token: string | undefined | null): number | null;
+    /**
+     * 计算解禁时间：
+     * - cooldownMs > 0 时使用 now + cooldownMs；
+     * - 否则使用「系统默认时区的次日 0 点」。
+     */
+    private cooldownUntil;
+    private normalize;
+}
+
+/**
+ * 发送消息接口。
+ *
+ * 对应 PushPlus 文档「二. 发送消息接口」与「三. 多渠道发送消息接口」。
+ *
+ * 内置本地限流守卫：当上游返回 ErrorCode.RATE_LIMITED（code=900）时，
+ * 后续对同一 token 的发送调用会在 SDK 内被直接短路抛 PushPlusError，
+ * 不再发起 HTTP，直到守卫到期自动解除。
+ */
+declare class MessageApi extends AbstractApi {
+    private readonly rateLimitGuard;
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, rateLimitGuard: RateLimitGuard);
+    /** 暴露限流守卫，便于运维场景手动 clear 或观察解禁时间。 */
+    getRateLimitGuard(): RateLimitGuard;
+    /**
+     * 发送单条消息。
+     *
+     * @returns 消息流水号
+     */
+    send(request: SendRequest): Promise<string>;
+    /**
+     * 多渠道发送消息。
+     */
+    batchSend(request: BatchSendRequest): Promise<BatchSendResult[]>;
+    /** 便捷方法：以默认渠道、默认模板发送一条简单消息。 */
+    sendSimple(title: string | undefined, content: string): Promise<string>;
+    private executeWithGuard;
+    private withDefaultToken;
+    private withDefaultBatchToken;
+    private requireToken;
+}
+
+/**
+ * 开放接口 - 消息 token（文档「四. 消息token接口」）。
+ */
+declare class MessageTokenApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 获取消息 token 列表。 */
+    list(query?: PageQuery): Promise<PageResult<MessageTokenItem>>;
+    /** 新增消息 token，返回新建的 token 字符串。 */
+    add(req: MessageTokenAddRequest): Promise<string>;
+    /** 修改消息 token。 */
+    edit(req: MessageTokenEditRequest): Promise<string>;
+    /** 删除消息 token。 */
+    delete(id: number): Promise<string>;
+    /**
+     * 消息 token 下拉选择列表。
+     *
+     * @param type 0-返回所有；1-返回未配置默认推送渠道的消息 token
+     */
+    selectList(type?: number): Promise<MessageTokenOption[]>;
+}
+
+/**
+ * 开放接口 - 消息接口（文档「二. 消息接口」）。
+ */
+declare class OpenMessageApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 1. 消息列表。 */
+    list(query?: PageQuery): Promise<PageResult<MessageItem>>;
+    /** 2. 查询消息发送结果。 */
+    queryResult(shortCode: string): Promise<SendMessageResult>;
+    /** 3. 删除消息。 */
+    delete(shortCode: string): Promise<string>;
+    /**
+     * 4. 消息详情（HTML 页面 URL）。
+     *
+     * 该接口直接返回 HTML 内容，SDK 仅返回访问 URL，调用方自行决定是否拉取页面内容。
+     */
+    detailUrl(shortCode: string): string;
+}
+
+/**
+ * 开放接口 - 预处理信息（文档「十一. 预处理信息接口」）。注：需开通会员。
+ */
+declare class PreApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    list(q?: PageQuery): Promise<PageResult<PreItem>>;
+    detail(preId: number): Promise<PreDetail>;
+    add(req: PreSaveRequest): Promise<number>;
+    edit(req: PreSaveRequest): Promise<string>;
+    delete(preId: number): Promise<string>;
+    /** 测试预处理代码，返回处理后的消息。 */
+    test(req: PreTestRequest): Promise<string>;
+}
+
+/**
+ * 开放接口 - 功能设置（文档「九. 功能设置接口」）。
+ */
+declare class SettingApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 1. 获取默认配置列表。 */
+    listUserDefault(q?: PageQuery): Promise<PageResult<UserDefaultItem>>;
+    /** 2. 默认配置详情。 */
+    detailUserDefault(id: number): Promise<UserDefaultDetail>;
+    /** 3. 新增默认配置。 */
+    addUserDefault(req: UserDefaultSaveRequest): Promise<void>;
+    /** 4. 修改默认配置。 */
+    editUserDefault(req: UserDefaultSaveRequest): Promise<void>;
+    /** 5. 删除默认配置。 */
+    deleteUserDefault(id: number): Promise<void>;
+    /**
+     * 6. 修改接收消息限制。
+     *
+     * @param recevieLimit 0-接收全部，1-不接收消息
+     */
+    changeReceiveLimit(recevieLimit: number): Promise<void>;
+    /**
+     * 7. 开启/关闭发送消息功能。
+     *
+     * @param isSend 0-禁用，1-启用
+     */
+    changeIsSend(isSend: number): Promise<void>;
+    /**
+     * 8. 修改打开消息方式。
+     *
+     * @param openMessageType 0:H5，1:小程序
+     */
+    changeOpenMessageType(openMessageType: number): Promise<void>;
+    /**
+     * 9. 修改插件渠道转发。
+     *
+     * @param forward 0:否，1:是
+     */
+    changeExtensionForward(forward: number): Promise<void>;
+}
+
+/**
+ * 开放接口 - 群组接口（文档「五. 群组接口」）。
+ */
+declare class TopicApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 1. 群组列表。 */
+    list(query?: TopicListQuery): Promise<PageResult<TopicItem>>;
+    /** 2. 获取我创建的群组详情。 */
+    detail(topicId: number): Promise<TopicDetail>;
+    /** 3. 获取我加入的群详情。 */
+    joinDetail(topicId: number): Promise<TopicDetail>;
+    /** 4. 新增群组，返回新建群组编号。 */
+    add(req: TopicAddRequest): Promise<number>;
+    /** 5. 修改群组。 */
+    edit(req: TopicEditRequest): Promise<string>;
+    /** 6. 获取群组二维码。 */
+    qrCode(topicId: number, second?: number, scanCount?: number): Promise<TopicQrCode>;
+    /** 7. 退出群组。 */
+    exit(topicId: number): Promise<string>;
+    /** 8. 删除群组。 */
+    delete(topicId: number): Promise<string>;
+    /**
+     * 9. 上下架积分群组。
+     *
+     * @param isOpen 1-上架，0-下架
+     */
+    setOpen(topicId: number, isOpen: number): Promise<string>;
+}
+
+/**
+ * 开放接口 - 群组用户（文档「六. 群组用户接口」）。
+ */
+declare class TopicUserApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 1. 获取群组内用户。 */
+    subscriberList(query: TopicUserListQuery): Promise<PageResult<TopicUserItem>>;
+    /** 2. 删除群组内用户。 */
+    deleteUser(topicRelationId: number): Promise<string>;
+    /** 3. 修改订阅人备注。 */
+    editRemark(id: number, remark: string): Promise<void>;
+}
+
+/**
+ * 开放接口 - 用户接口（文档「三. 用户接口」）。
+ */
+declare class UserApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 获取用户 token。 */
+    getToken(): Promise<string>;
+    /** 个人资料详情。 */
+    myInfo(): Promise<UserInfo>;
+    /** 获取解封剩余时间。 */
+    getLimitTime(): Promise<UserLimitTime>;
+    /** 查询当日消息接口请求次数。 */
+    getSendCount(): Promise<SendCount>;
+}
+
+/**
+ * 开放接口 - webhook 渠道配置（文档「七. 渠道配置接口」 1-4）。
+ */
+declare class WebhookApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    list(q?: PageQuery): Promise<PageResult<WebhookItem>>;
+    detail(webhookId: number): Promise<WebhookItem>;
+    /** 新增 webhook，返回新 id。 */
+    add(req: WebhookSaveRequest): Promise<number>;
+    edit(req: WebhookSaveRequest): Promise<string>;
+}
+
+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();
+ * ```
+ */
+declare class PushPlusClient {
+    /** 已解析的不可变配置。 */
+    readonly config: ResolvedPushPlusConfig;
+    readonly httpRequester: HttpRequester;
+    readonly accessKeyManager: AccessKeyManager;
+    readonly rateLimitGuard: RateLimitGuard;
+    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);
+    /** 与 Java SDK 风格一致的 Builder 入口。 */
+    static builder(): PushPlusClientBuilder;
+    /** 工厂方法。 */
+    static of(options: PushPlusClientOptions): PushPlusClient;
+    /** 发送一条简单消息（默认 wechat / html）。 */
+    sendSimple(title: string | undefined, content: string): Promise<string>;
+    /** 发送消息。 */
+    send(req: SendRequest): Promise<string>;
+    /** 多渠道发送消息。 */
+    batchSend(req: BatchSendRequest): Promise<BatchSendResult[]>;
+}
+/**
+ * 链式 Builder，与 Java/Python SDK 风格保持一致。
+ */
+declare class PushPlusClientBuilder {
+    private readonly opt;
+    token(v?: string): this;
+    secretKey(v?: string): this;
+    baseUrl(v?: string): this;
+    connectTimeoutMs(v: number): this;
+    readTimeoutMs(v: number): this;
+    accessKeyRefreshAheadSeconds(v: number): this;
+    logRequest(v: boolean): this;
+    rateLimitGuardEnabled(v: boolean): this;
+    rateLimitCooldownMs(v: number): this;
+    userAgent(v: string): this;
+    httpRequester(req: HttpRequester): this;
+    build(): PushPlusClient;
+}
+
+/**
+ * PushPlus SDK 统一运行时异常。
+ *
+ * 该异常会在以下场景抛出：
+ * - HTTP 请求失败（网络异常、非 2xx 状态码）
+ * - PushPlus 业务接口返回 code != 200
+ * - JSON 序列化/反序列化异常
+ * - SDK 参数校验失败
+ * - 本地限流守卫命中（code=900 后被短路），不会真正发起 HTTP 请求
+ */
+declare class PushPlusError extends Error {
+    /** PushPlus 接口返回的业务 code。HTTP 错误时为对应的 HTTP 状态码；其他为 -1。 */
+    readonly code: number;
+    /** 同 message。便于和其它语言 SDK 风格一致。 */
+    get businessMessage(): string;
+    constructor(message: string, code?: number, options?: {
+        cause?: unknown;
+    });
+    /** 把数值 code 映射为 ErrorCode 枚举（未知为 UNKNOWN）。 */
+    get errorCode(): ErrorCode;
+    /** 是否为 PushPlus 限流（code=900）。命中后建议当天停止继续调用发送消息接口。 */
+    isRateLimited(): boolean;
+}
+/**
+ * 兼容 Java SDK 命名（PushPlusException）的别名导出。
+ */
+declare const PushPlusException: typeof PushPlusError;
+
+/**
+ * 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';
+ * }
+ * ```
+ */
+declare function parseCallback(json: string | object): CallbackPayload;
+declare const CallbackParser: {
+    parse: typeof parseCallback;
+};
+
+export { AbstractApi, AccessKeyApi, AccessKeyManager, type AccessKeyResult, type ApiResponse, type BatchSendRequest, BatchSendRequestBuilder, type BatchSendResult, CallbackEvent, CallbackParser, type CallbackPayload, Channel, ChannelApi, ClawBotApi, type ClawBotInfo, type ClawBotMessage, type ClawBotQrCode, type CpItem, DEFAULT_BASE_URL, ErrorCode, FetchHttpRequester, FriendApi, type FriendInfo, type FriendItem, type FriendQrCode, type HttpRequestOptions, type HttpRequester, type HttpResponse, type MailDetail, type MailItem, MessageApi, type MessageCompleteInfo, type MessageItem, type MessageTokenAddRequest, MessageTokenApi, type MessageTokenEditRequest, type MessageTokenItem, type MessageTokenOption, type MpItem, OpenAbstractApi, OpenMessageApi, type PageQuery, type PageResult, PreApi, type PreDetail, type PreItem, type PreSaveRequest, type PreTestRequest, PushPlusClient, PushPlusClientBuilder, type PushPlusClientOptions, type PushPlusConfig, PushPlusError, PushPlusException, RateLimitGuard, type ResolvedPushPlusConfig, type SendCount, type SendMessageResult, type SendRequest, SendRequestBuilder, SendStatus, SendStatusDescription, SettingApi, Template, type TopicAddRequest, TopicApi, type TopicDetail, type TopicEditRequest, type TopicItem, type TopicListQuery, type TopicQrCode, TopicUserApi, type TopicUserInfo, type TopicUserItem, type TopicUserListQuery, UserApi, type UserDefaultDetail, type UserDefaultItem, type UserDefaultSaveRequest, type UserInfo, type UserLimitTime, WebhookApi, type WebhookItem, type WebhookSaveRequest, WebhookType, WebhookTypeDescription, batchSendRequest, errorCodeFromValue, isRateLimitedCode, isSuccessfulHttpStatus, parseCallback, resolveConfig, sendRequest };