@perk-net/perk-pushplus-sdk 1.2.0 → 1.2.2

package/dist/index.d.cts

@@ -155,7 +155,9 @@ declare enum Channel {
     /** App 渠道（安卓/鸿蒙/iOS）。 */
     APP = "app",
     /** 微信 ClawBot。 */
-    CLAWBOT = "clawbot"
+    CLAWBOT = "clawbot",
+    /** QQ 机器人；不带 option 发给自己，option 填配置编码则发到对应 QQ 群。 */
+    QQ = "qq"
 }
 /**
  * PushPlus 消息模板枚举。
@@ -511,6 +513,7 @@ interface SendCount {
     cpSendCount?: number;
     webhookSendCount?: number;
     mailSendCount?: number;
+    qqBotSendCount?: number;
 }
 interface UserLimitTime {
     /** 1-无限制，2-短期限制，3-永久限制。 */
@@ -645,6 +648,18 @@ interface TopicUserListQuery {
     /** 例如 { topicId }。 */
     params?: Record<string, unknown>;
 }
+/** 群组订阅人黑名单列表项。 */
+interface TopicUserBlacklistItem {
+    /** 黑名单记录 ID；解除黑名单时使用。 */
+    id?: number;
+    /** 被拉黑用户 ID。 */
+    userId?: number;
+    nickName?: string;
+    openId?: string;
+    headImgUrl?: string;
+    /** 拉黑时间。 */
+    createTime?: string;
+}
 interface WebhookItem {
     id?: number;
     webhookCode?: string;
@@ -685,6 +700,17 @@ interface FriendItem {
 interface FriendQrCode {
     qrCodeImgUrl?: string;
 }
+/** 好友黑名单列表项。 */
+interface FriendBlacklistItem {
+    /** 黑名单记录 ID；解除黑名单时使用。 */
+    id?: number;
+    /** 被拉黑好友 ID。 */
+    friendId?: number;
+    nickName?: string;
+    headImgUrl?: string;
+    /** 拉黑时间。 */
+    createTime?: string;
+}
 interface ClawBotInfo {
     createTime?: string;
     /** 是否有对话令牌（文档为字符串/数字混用，统一用 number 兼容）。 */
@@ -699,6 +725,74 @@ interface ClawBotQrCode {
     url?: string;
     qrcode?: string;
 }
+interface QqBotBindLink {
+    /** 带参分享链接，用于生成扫码二维码；已绑定用户再次获取时可能为空。 */
+    url?: string;
+    /** 绑定码。已是好友时扫码收不到加好友事件，需私聊发送该码；认领 QQ 群也用此码。 */
+    bindCode?: string;
+    /** 有效期秒数，默认 300。 */
+    expireSeconds?: number;
+    /** 为当前用户分配的官方机器人 appId。 */
+    botAppId?: string;
+    botName?: string;
+    botAvatar?: string;
+}
+interface QqBotInfo {
+    botId?: string;
+    username?: string;
+    avatar?: string;
+    appId?: string;
+    /** 官方分享链接，可用于拉机器人进群。 */
+    shareUrl?: string;
+}
+interface QqBotBindInfo {
+    /** 0-未绑定，1-已绑定。 */
+    isBind?: number;
+    /** 1-可接收，0-用户已关闭单聊接收。 */
+    receiveStatus?: number;
+    createTime?: string;
+    botInfo?: QqBotInfo;
+}
+interface QqGroupItem {
+    /** 群编号；新增渠道配置时作为 qqGroupId 使用。 */
+    id?: number;
+    groupOpenId?: string;
+    groupRemark?: string;
+    /** 1-在群，2-群消息接收关闭。 */
+    status?: number;
+    /** 群名称，接口未授权时为空。 */
+    groupName?: string;
+    groupFingerMemo?: string;
+    groupClassText?: string;
+    groupTags?: string[];
+    groupMemberNum?: number;
+    createTime?: string;
+}
+interface QqBotItem {
+    id?: number;
+    qqName?: string;
+    /** 配置编码；发送消息时作为 option 传入。 */
+    qqCode?: string;
+    /** 2-发到 QQ 群。 */
+    sendType?: number;
+    qqGroupId?: number;
+    groupRemark?: string;
+    groupOpenId?: string;
+    groupName?: string;
+    updateTime?: string;
+}
+interface QqBotSaveRequest {
+    /** 修改时必填。 */
+    id?: number;
+    /** 配置名称，必填，最多 64 个字符。 */
+    qqName?: string;
+    /** 配置编码，新增必填；仅支持字母、数字、下划线和中划线，创建后不可修改。 */
+    qqCode?: string;
+    /** 发送类型；留空时 SDK 自动填 2（发到 QQ 群）。 */
+    sendType?: number;
+    /** QQ 群编号，必填，取自 groupList 返回的 id。 */
+    qqGroupId?: number;
+}
 interface MpItem {
     id?: number;
     nickName?: string;
@@ -843,16 +937,19 @@ interface ImageItem {
     /** 创建时间。 */
     createTime?: string;
 }
-/** 我的表单分页查询。 */
+/** 我的表单分页查询。官方结构为 `{current, pageSize, params:{keyword, status}}`。 */
 interface FormListQuery {
-    /** 页码，从 1 开始。 */
-    pageNum?: number;
-    /** 每页条数。 */
+    /** 当前所在分页数，默认 1。 */
+    current?: number;
+    /** 每页大小，默认 20，最大 50。 */
     pageSize?: number;
-    /** 按标题关键词搜索。 */
-    keyword?: string;
-    /** 表单状态：0草稿 / 1收集中 / 2已停止。 */
-    status?: number;
+    params?: {
+        /** 按标题关键词搜索。 */
+        keyword?: string;
+        /** 表单状态：0草稿 / 1收集中 / 2已停止。 */
+        status?: number;
+        [key: string]: unknown;
+    };
 }
 /** 表单封面页配置。 */
 interface FormCover {
@@ -956,13 +1053,18 @@ interface FormPublishResult {
     publishDirty?: boolean;
     publishTime?: string;
 }
-/** 文档 / 表格分页查询。 */
+/** 文档 / 表格分页查询。官方结构为 `{current, pageSize, params:{keyword, shareEnabled}}`。 */
 interface DocListQuery {
-    pageNum?: number;
+    /** 当前所在分页数，默认 1。 */
+    current?: number;
+    /** 每页大小，默认 20，最大 50。 */
     pageSize?: number;
-    keyword?: string;
-    /** true 时仅返回已开启分享的记录。 */
-    shareEnabled?: boolean;
+    params?: {
+        keyword?: string;
+        /** true 时仅返回已开启分享的记录。 */
+        shareEnabled?: boolean;
+        [key: string]: unknown;
+    };
 }
 /** 文档 / 表格列表项。 */
 interface DocListItem {
@@ -1022,6 +1124,11 @@ declare abstract class AbstractApi {
      * 执行请求并返回原始 ApiResponse（不进行 code 校验）。
      */
     protected execute<T>(method: string, path: string, headers: Record<string, string> | undefined | null, body: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 执行带二进制请求体的请求并返回原始 ApiResponse（不进行 code 校验）。
+     * 用于 multipart 上传等场景。
+     */
+    protected executeRaw<T>(method: string, path: string, headers: Record<string, string> | undefined | null, body: Uint8Array): Promise<ApiResponse<T>>;
     /** 执行请求并直接返回 data；非 200 抛出异常。 */
     protected executeForData<T>(method: string, path: string, headers: Record<string, string> | undefined | null, body: unknown): Promise<T>;
 }
@@ -1066,6 +1173,13 @@ declare class AccessKeyManager {
     private isValid;
 }
 
+/** 二进制文件输入。 */
+type FileInput = Uint8Array | ArrayBuffer | Blob;
+interface FileMultipart {
+    contentType: string;
+    body: Uint8Array;
+}
+
 /**
  * 开放接口基类。会自动在 header 中带上 access-key，
  * 并在收到 401 类业务错误时尝试重试一次（刷新 AccessKey 后重试）。
@@ -1081,6 +1195,12 @@ declare abstract class OpenAbstractApi extends AbstractApi {
      * 执行带 access-key 的请求；当返回 code=401 时自动刷新 key 并重试一次。
      */
     protected executeOpen<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** 以 multipart 上传文件（自动携带 access-key；code=401 时刷新后重试一次）。 */
+    protected executeOpenMultipart<T>(path: string, multipart: FileMultipart): Promise<T>;
+    /**
+     * 执行带二进制 body 的开放接口请求；当返回 code=401 时自动刷新 key 并重试一次。
+     */
+    protected executeOpenRaw<T>(method: string, path: string, body: Uint8Array, extraHeaders?: Record<string, string>): Promise<T>;
 }
 
 /**
@@ -1120,6 +1240,9 @@ declare class ClawBotApi extends OpenAbstractApi {
  *
  * 文档：https://www.pushplus.plus/doc/ecosystem/doc/
  * 基础路径：`/push/api/open/doc`
+ *
+ * 文档开放接口不单独提供推送接口。发布后请通过 `client.send` 推送分享页：
+ * `template=doc`，`pushId=docCode`。
  */
 declare class DocApi extends OpenAbstractApi {
     constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
@@ -1127,6 +1250,12 @@ declare class DocApi extends OpenAbstractApi {
     list(query?: DocListQuery): Promise<PageResult<DocListItem>>;
     /** 创建空白文档。 */
     create(title: string): Promise<DocVo>;
+    /**
+     * 导入 Word（.docx）创建文档。
+     *
+     * 标题默认取文件名；创建后默认关闭分享，需再调用 publish 才会同步到分享页。
+     */
+    importWord(file: FileInput, fileName?: string): Promise<DocVo>;
     /** 获取文档元信息与 HTML 草稿正文。 */
     content(docCode: string): Promise<DocContent>;
     /** 保存 HTML 草稿（不影响分享页，需再 publish）。 */
@@ -1151,6 +1280,9 @@ declare class DocApi extends OpenAbstractApi {
  *
  * 文档：https://www.pushplus.plus/doc/ecosystem/sheet/
  * 基础路径：`/push/api/open/excel`
+ *
+ * 表格开放接口不单独提供推送接口。发布后请通过 `client.send` 推送分享页：
+ * `template=excel`，`pushId=docCode`。
  */
 declare class ExcelApi extends OpenAbstractApi {
     constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
@@ -1158,6 +1290,12 @@ declare class ExcelApi extends OpenAbstractApi {
     list(query?: DocListQuery): Promise<PageResult<DocListItem>>;
     /** 创建空白表格。 */
     create(title: string): Promise<ExcelVo>;
+    /**
+     * 导入 Excel（.xlsx / .xls）创建表格。
+     *
+     * 标题默认取文件名；创建后默认关闭分享，需再调用 publish 才会同步到分享页。
+     */
+    importExcel(file: FileInput, fileName?: string): Promise<ExcelVo>;
     /** 获取表格元信息与整表 JSON 草稿。 */
     content(docCode: string): Promise<ExcelContent>;
     /**
@@ -1194,6 +1332,9 @@ declare class ExcelApi extends OpenAbstractApi {
  *
  * 文档：https://www.pushplus.plus/doc/ecosystem/form/
  * 基础路径：`/push/api/open/form`
+ *
+ * 表单开放接口不单独提供推送接口。发布后请通过 `client.send` 推送填写页：
+ * `template=form`，`pushId=formCode`。
  */
 declare class FormApi extends OpenAbstractApi {
     constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
@@ -1235,6 +1376,24 @@ declare class FriendApi extends OpenAbstractApi {
     delete(friendId: number): Promise<void>;
     /** 4. 修改好友备注。 */
     editRemark(id: number, remark: string): Promise<void>;
+    /**
+     * 5. 将好友加入黑名单。
+     *
+     * 加入后将解除双方好友关系，对方无法再添加你。不能将自己加入黑名单，仅可将已有好友加入黑名单。
+     *
+     * @param friendId 好友 id（好友列表中的 friendId 字段）
+     */
+    addBlacklist(friendId: number): Promise<void>;
+    /** 6. 好友黑名单列表。 */
+    blacklistList(query?: PageQuery): Promise<PageResult<FriendBlacklistItem>>;
+    /**
+     * 7. 解除好友黑名单。
+     *
+     * 解除后不会自动恢复好友关系，需重新扫码添加。
+     *
+     * @param id 黑名单记录 ID（黑名单列表中的 id 字段）
+     */
+    removeBlacklist(id: number): Promise<void>;
 }
 
 /**
@@ -1423,6 +1582,29 @@ declare class PreApi extends OpenAbstractApi {
     test(req: PreTestRequest): Promise<string>;
 }
 
+/**
+ * 开放接口 - QQ 机器人（文档「九. QQ机器人接口」）。
+ */
+declare class QqBotApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 1. 获取绑定链接与绑定码；refresh 为 true 时旧绑定码失效并重新生成。 */
+    getBindLink(refresh?: boolean): Promise<QqBotBindLink>;
+    /** 2. 查询绑定状态。 */
+    botInfo(): Promise<QqBotBindInfo>;
+    /** 3. 解绑 QQ 机器人。 */
+    unbind(): Promise<void>;
+    /** 4. 获取机器人已加入的 QQ 群列表。 */
+    groupList(): Promise<QqGroupItem[]>;
+    /** 5. 获取 QQ 机器人渠道配置列表。 */
+    list(q?: PageQuery): Promise<PageResult<QqBotItem>>;
+    /** 6. 新增渠道配置，用于把消息发送到指定 QQ 群；发给自己无需创建配置。 */
+    add(req: QqBotSaveRequest): Promise<void>;
+    /** 7. 修改渠道配置；配置编码不可修改。 */
+    edit(req: QqBotSaveRequest): Promise<void>;
+    /** 8. 删除渠道配置。 */
+    delete(id: number): Promise<void>;
+}
+
 /**
  * 开放接口 - 功能设置（文档「九. 功能设置接口」）。
  */
@@ -1504,6 +1686,28 @@ declare class TopicUserApi extends OpenAbstractApi {
     deleteUser(topicRelationId: number): Promise<string>;
     /** 3. 修改订阅人备注。 */
     editRemark(id: number, remark: string): Promise<void>;
+    /**
+     * 4. 将订阅人加入黑名单。
+     *
+     * 加入后将移出群组，对方无法再加入该群组。积分群组不支持黑名单。不能将自己加入黑名单。
+     *
+     * @param topicRelationId 用户编号（订阅人列表中的 id 字段）
+     */
+    addBlacklist(topicRelationId: number): Promise<void>;
+    /**
+     * 5. 订阅人黑名单列表。
+     *
+     * `query.params.topicId` 必填。
+     */
+    blacklistList(query: TopicUserListQuery): Promise<PageResult<TopicUserBlacklistItem>>;
+    /**
+     * 6. 解除订阅人黑名单。
+     *
+     * 解除后不会自动恢复群组订阅，对方可重新加入该群组。
+     *
+     * @param id 黑名单记录 ID（黑名单列表中的 id 字段）
+     */
+    removeBlacklist(id: number): Promise<void>;
 }
 
 /**
@@ -1575,6 +1779,7 @@ declare class PushPlusClient {
     readonly webhook: WebhookApi;
     readonly channel: ChannelApi;
     readonly clawBot: ClawBotApi;
+    readonly qqBot: QqBotApi;
     readonly setting: SettingApi;
     readonly pre: PreApi;
     readonly image: ImageApi;
@@ -1671,4 +1876,4 @@ 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, DocApi, type DocContent, type DocListItem, type DocListQuery, type DocVo, ErrorCode, ExcelApi, type ExcelContent, type ExcelVo, type ExcelWriteCellsRequest, FetchHttpRequester, FormApi, type FormCover, type FormDetail, type FormItem, type FormListItem, type FormListQuery, type FormPublishDiff, type FormPublishResult, type FormSaveRequest, type FormSettings, FormStatus, FormStatusDescription, type FormTheme, FriendApi, type FriendInfo, type FriendItem, type FriendQrCode, type HttpRawBody, type HttpRawRequestOptions, type HttpRequestOptions, type HttpRequester, type HttpResponse, ImageApi, type ImageFileInput, type ImageItem, type ImageUploadOptions, type ImageUploadResult, type ImageUploadToken, 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, ShareLogin, SharePerm, 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, type VipInfo, WebhookApi, type WebhookItem, type WebhookSaveRequest, WebhookType, WebhookTypeDescription, batchSendRequest, callExecuteRaw, errorCodeFromValue, isRateLimitedCode, isSuccessfulHttpStatus, parseCallback, resolveConfig, sendRequest };
+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, DocApi, type DocContent, type DocListItem, type DocListQuery, type DocVo, ErrorCode, ExcelApi, type ExcelContent, type ExcelVo, type ExcelWriteCellsRequest, FetchHttpRequester, type FileInput, FormApi, type FormCover, type FormDetail, type FormItem, type FormListItem, type FormListQuery, type FormPublishDiff, type FormPublishResult, type FormSaveRequest, type FormSettings, FormStatus, FormStatusDescription, type FormTheme, FriendApi, type FriendBlacklistItem, type FriendInfo, type FriendItem, type FriendQrCode, type HttpRawBody, type HttpRawRequestOptions, type HttpRequestOptions, type HttpRequester, type HttpResponse, ImageApi, type ImageFileInput, type ImageItem, type ImageUploadOptions, type ImageUploadResult, type ImageUploadToken, 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, QqBotApi, type QqBotBindInfo, type QqBotBindLink, type QqBotInfo, type QqBotItem, type QqBotSaveRequest, type QqGroupItem, RateLimitGuard, type ResolvedPushPlusConfig, type SendCount, type SendMessageResult, type SendRequest, SendRequestBuilder, SendStatus, SendStatusDescription, SettingApi, ShareLogin, SharePerm, Template, type TopicAddRequest, TopicApi, type TopicDetail, type TopicEditRequest, type TopicItem, type TopicListQuery, type TopicQrCode, TopicUserApi, type TopicUserBlacklistItem, type TopicUserInfo, type TopicUserItem, type TopicUserListQuery, UserApi, type UserDefaultDetail, type UserDefaultItem, type UserDefaultSaveRequest, type UserInfo, type UserLimitTime, type VipInfo, WebhookApi, type WebhookItem, type WebhookSaveRequest, WebhookType, WebhookTypeDescription, batchSendRequest, callExecuteRaw, errorCodeFromValue, isRateLimitedCode, isSuccessfulHttpStatus, parseCallback, resolveConfig, sendRequest };