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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perk-net/perk-pushplus-sdk",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "pushplus(推送加) 官方接口 JavaScript/TypeScript SDK，可在 Node.js 与浏览器中使用",
   "keywords": [
     "pushplus",

package/src/api/base.ts

@@ -1,6 +1,6 @@
 import { ResolvedPushPlusConfig } from '../config';
 import { PushPlusError } from '../exception';
-import { HttpRequester, HttpResponse, isSuccessfulHttpStatus } from '../http';
+import { HttpRequester, HttpResponse, callExecuteRaw, isSuccessfulHttpStatus } from '../http';
 import { ApiResponse } from '../models';
 
 /**
@@ -62,6 +62,32 @@ export abstract class AbstractApi {
     return parseApiResponse<T>(resp);
   }
 
+  /**
+   * 执行带二进制请求体的请求并返回原始 ApiResponse（不进行 code 校验）。
+   * 用于 multipart 上传等场景。
+   */
+  protected async executeRaw<T>(
+    method: string,
+    path: string,
+    headers: Record<string, string> | undefined | null,
+    body: Uint8Array,
+  ): Promise<ApiResponse<T>> {
+    const url = this.resolveUrl(path);
+    const resp = await callExecuteRaw(this.http, {
+      method,
+      url,
+      headers: headers ?? undefined,
+      body,
+    });
+    if (!isSuccessfulHttpStatus(resp.statusCode)) {
+      throw new PushPlusError(
+        `PushPlus 接口 HTTP 调用失败: status=${resp.statusCode}, body=${resp.body}`,
+        resp.statusCode,
+      );
+    }
+    return parseApiResponse<T>(resp);
+  }
+
   /** 执行请求并直接返回 data；非 200 抛出异常。 */
   protected async executeForData<T>(
     method: string,

package/src/api/doc-api.ts

@@ -1,6 +1,7 @@
 import { AccessKeyManager } from '../access-key-manager';
 import { ResolvedPushPlusConfig } from '../config';
 import { HttpRequester } from '../http';
+import { FileInput, buildFileMultipart, toFileBytes } from '../multipart';
 import { DocContent, DocListItem, DocListQuery, DocVo, PageResult } from '../models';
 import { OpenAbstractApi } from './open-base';
 
@@ -9,6 +10,9 @@ import { OpenAbstractApi } from './open-base';
  *
  * 文档：https://www.pushplus.plus/doc/ecosystem/doc/
  * 基础路径：`/push/api/open/doc`
+ *
+ * 文档开放接口不单独提供推送接口。发布后请通过 `client.send` 推送分享页：
+ * `template=doc`，`pushId=docCode`。
  */
 export class DocApi extends OpenAbstractApi {
   constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager) {
@@ -29,6 +33,20 @@ export class DocApi extends OpenAbstractApi {
     return this.executeOpen<DocVo>('POST', '/push/api/open/doc/create', { title });
   }
 
+  /**
+   * 导入 Word（.docx）创建文档。
+   *
+   * 标题默认取文件名；创建后默认关闭分享，需再调用 publish 才会同步到分享页。
+   */
+  async importWord(file: FileInput, fileName = 'document.docx'): Promise<DocVo> {
+    const bytes = await toFileBytes(file);
+    const name = fileName && fileName.trim() ? fileName : 'document.docx';
+    return this.executeOpenMultipart<DocVo>(
+      '/push/api/open/doc/import',
+      buildFileMultipart(name, guessDocxContentType(name), bytes),
+    );
+  }
+
   /** 获取文档元信息与 HTML 草稿正文。 */
   content(docCode: string): Promise<DocContent> {
     return this.executeOpen<DocContent>(
@@ -75,3 +93,9 @@ export class DocApi extends OpenAbstractApi {
     return this.executeOpen<DocVo>('POST', '/push/api/open/doc/updateShare', body);
   }
 }
+
+function guessDocxContentType(name: string): string {
+  return name.toLowerCase().endsWith('.docx')
+    ? 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+    : 'application/octet-stream';
+}

package/src/api/excel-api.ts

@@ -2,6 +2,7 @@ import { AccessKeyManager } from '../access-key-manager';
 import { ResolvedPushPlusConfig } from '../config';
 import { PushPlusError } from '../exception';
 import { HttpRequester } from '../http';
+import { FileInput, buildFileMultipart, toFileBytes } from '../multipart';
 import { DocListItem, DocListQuery, ExcelContent, ExcelVo, PageResult } from '../models';
 import { OpenAbstractApi } from './open-base';
 
@@ -10,6 +11,9 @@ import { OpenAbstractApi } from './open-base';
  *
  * 文档：https://www.pushplus.plus/doc/ecosystem/sheet/
  * 基础路径：`/push/api/open/excel`
+ *
+ * 表格开放接口不单独提供推送接口。发布后请通过 `client.send` 推送分享页：
+ * `template=excel`，`pushId=docCode`。
  */
 export class ExcelApi extends OpenAbstractApi {
   constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager) {
@@ -30,6 +34,20 @@ export class ExcelApi extends OpenAbstractApi {
     return this.executeOpen<ExcelVo>('POST', '/push/api/open/excel/create', { title });
   }
 
+  /**
+   * 导入 Excel（.xlsx / .xls）创建表格。
+   *
+   * 标题默认取文件名；创建后默认关闭分享，需再调用 publish 才会同步到分享页。
+   */
+  async importExcel(file: FileInput, fileName = 'workbook.xlsx'): Promise<ExcelVo> {
+    const bytes = await toFileBytes(file);
+    const name = fileName && fileName.trim() ? fileName : 'workbook.xlsx';
+    return this.executeOpenMultipart<ExcelVo>(
+      '/push/api/open/excel/import',
+      buildFileMultipart(name, guessExcelContentType(name), bytes),
+    );
+  }
+
   /** 获取表格元信息与整表 JSON 草稿。 */
   content(docCode: string): Promise<ExcelContent> {
     return this.executeOpen<ExcelContent>(
@@ -112,3 +130,14 @@ function stringifyJsonContent(content: string | object): string {
     throw new PushPlusError(`序列化表格内容失败: ${(e as Error).message}`, -1, { cause: e });
   }
 }
+
+function guessExcelContentType(name: string): string {
+  const lower = name.toLowerCase();
+  if (lower.endsWith('.xlsx')) {
+    return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+  }
+  if (lower.endsWith('.xls')) {
+    return 'application/vnd.ms-excel';
+  }
+  return 'application/octet-stream';
+}

package/src/api/form-api.ts

@@ -17,6 +17,9 @@ import { OpenAbstractApi } from './open-base';
  *
  * 文档：https://www.pushplus.plus/doc/ecosystem/form/
  * 基础路径：`/push/api/open/form`
+ *
+ * 表单开放接口不单独提供推送接口。发布后请通过 `client.send` 推送填写页：
+ * `template=form`，`pushId=formCode`。
  */
 export class FormApi extends OpenAbstractApi {
   constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager) {

package/src/api/friend-api.ts

@@ -1,7 +1,7 @@
 import { AccessKeyManager } from '../access-key-manager';
 import { ResolvedPushPlusConfig } from '../config';
 import { HttpRequester } from '../http';
-import { FriendItem, FriendQrCode, PageQuery, PageResult } from '../models';
+import { FriendBlacklistItem, FriendItem, FriendQrCode, PageQuery, PageResult } from '../models';
 import { OpenAbstractApi } from './open-base';
 
 /**
@@ -44,4 +44,41 @@ export class FriendApi extends OpenAbstractApi {
   async editRemark(id: number, remark: string): Promise<void> {
     await this.executeOpen<unknown>('POST', '/api/open/friend/editRemark', { id, remark });
   }
+
+  /**
+   * 5. 将好友加入黑名单。
+   *
+   * 加入后将解除双方好友关系，对方无法再添加你。不能将自己加入黑名单，仅可将已有好友加入黑名单。
+   *
+   * @param friendId 好友 id（好友列表中的 friendId 字段）
+   */
+  async addBlacklist(friendId: number): Promise<void> {
+    await this.executeOpen<unknown>(
+      'POST',
+      this.appendQuery('/api/open/friend/addBlacklist', { friendId }),
+    );
+  }
+
+  /** 6. 好友黑名单列表。 */
+  blacklistList(query?: PageQuery): Promise<PageResult<FriendBlacklistItem>> {
+    return this.executeOpen<PageResult<FriendBlacklistItem>>(
+      'POST',
+      '/api/open/friend/blacklistList',
+      query ?? {},
+    );
+  }
+
+  /**
+   * 7. 解除好友黑名单。
+   *
+   * 解除后不会自动恢复好友关系，需重新扫码添加。
+   *
+   * @param id 黑名单记录 ID（黑名单列表中的 id 字段）
+   */
+  async removeBlacklist(id: number): Promise<void> {
+    await this.executeOpen<unknown>(
+      'POST',
+      this.appendQuery('/api/open/friend/removeBlacklist', { id }),
+    );
+  }
 }

package/src/api/open-base.ts

@@ -2,6 +2,7 @@ import { AccessKeyManager } from '../access-key-manager';
 import { ResolvedPushPlusConfig } from '../config';
 import { PushPlusError } from '../exception';
 import { HttpRequester } from '../http';
+import { FileMultipart } from '../multipart';
 import { AbstractApi, isApiSuccess } from './base';
 
 /**
@@ -51,4 +52,43 @@ export abstract class OpenAbstractApi extends AbstractApi {
       resp.code ?? -1,
     );
   }
+
+  /** 以 multipart 上传文件（自动携带 access-key；code=401 时刷新后重试一次）。 */
+  protected executeOpenMultipart<T>(path: string, multipart: FileMultipart): Promise<T> {
+    return this.executeOpenRaw<T>('POST', path, multipart.body, {
+      'Content-Type': multipart.contentType,
+    });
+  }
+
+  /**
+   * 执行带二进制 body 的开放接口请求；当返回 code=401 时自动刷新 key 并重试一次。
+   */
+  protected async executeOpenRaw<T>(
+    method: string,
+    path: string,
+    body: Uint8Array,
+    extraHeaders?: Record<string, string>,
+  ): Promise<T> {
+    const headers = { ...(await this.headersWithAccessKey()), ...(extraHeaders ?? {}) };
+    const resp = await this.executeRaw<T>(method, path, headers, body);
+    if (isApiSuccess(resp)) {
+      return resp.data as T;
+    }
+    if (resp.code === OpenAbstractApi.CODE_ACCESS_KEY_INVALID) {
+      this.accessKeyManager.invalidate();
+      const retryHeaders = { ...(await this.headersWithAccessKey()), ...(extraHeaders ?? {}) };
+      const retry = await this.executeRaw<T>(method, path, retryHeaders, body);
+      if (isApiSuccess(retry)) {
+        return retry.data as T;
+      }
+      throw new PushPlusError(
+        `PushPlus 开放接口业务失败(重试后): code=${retry.code}, msg=${retry.msg}`,
+        retry.code ?? -1,
+      );
+    }
+    throw new PushPlusError(
+      `PushPlus 开放接口业务失败: code=${resp.code}, msg=${resp.msg}`,
+      resp.code ?? -1,
+    );
+  }
 }

package/src/api/qqbot-api.ts

@@ -0,0 +1,75 @@
+import { AccessKeyManager } from '../access-key-manager';
+import { ResolvedPushPlusConfig } from '../config';
+import { HttpRequester } from '../http';
+import {
+  PageQuery,
+  PageResult,
+  QqBotBindInfo,
+  QqBotBindLink,
+  QqBotItem,
+  QqBotSaveRequest,
+  QqGroupItem,
+} from '../models';
+import { OpenAbstractApi } from './open-base';
+
+/** 发送到 QQ 群，目前渠道配置仅支持该类型。 */
+const SEND_TYPE_QQ_GROUP = 2;
+
+/**
+ * 开放接口 - QQ 机器人（文档「九. QQ机器人接口」）。
+ */
+export class QqBotApi extends OpenAbstractApi {
+  constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager) {
+    super(config, http, mgr);
+  }
+
+  /** 1. 获取绑定链接与绑定码；refresh 为 true 时旧绑定码失效并重新生成。 */
+  getBindLink(refresh = false): Promise<QqBotBindLink> {
+    const path = refresh
+      ? this.appendQuery('/api/open/qqBot/getBindLink', { refresh: true })
+      : '/api/open/qqBot/getBindLink';
+    return this.executeOpen<QqBotBindLink>('GET', path);
+  }
+
+  /** 2. 查询绑定状态。 */
+  botInfo(): Promise<QqBotBindInfo> {
+    return this.executeOpen<QqBotBindInfo>('GET', '/api/open/qqBot/botInfo');
+  }
+
+  /** 3. 解绑 QQ 机器人。 */
+  async unbind(): Promise<void> {
+    await this.executeOpen<unknown>('GET', '/api/open/qqBot/unbind');
+  }
+
+  /** 4. 获取机器人已加入的 QQ 群列表。 */
+  async groupList(): Promise<QqGroupItem[]> {
+    return (await this.executeOpen<QqGroupItem[]>('GET', '/api/open/qqBot/groupList')) ?? [];
+  }
+
+  /** 5. 获取 QQ 机器人渠道配置列表。 */
+  list(q?: PageQuery): Promise<PageResult<QqBotItem>> {
+    return this.executeOpen<PageResult<QqBotItem>>('POST', '/api/open/qqBot/list', q ?? {});
+  }
+
+  /** 6. 新增渠道配置，用于把消息发送到指定 QQ 群；发给自己无需创建配置。 */
+  async add(req: QqBotSaveRequest): Promise<void> {
+    await this.executeOpen<unknown>('POST', '/api/open/qqBot/add', withDefaultSendType(req));
+  }
+
+  /** 7. 修改渠道配置；配置编码不可修改。 */
+  async edit(req: QqBotSaveRequest): Promise<void> {
+    await this.executeOpen<unknown>('POST', '/api/open/qqBot/edit', withDefaultSendType(req));
+  }
+
+  /** 8. 删除渠道配置。 */
+  async delete(id: number): Promise<void> {
+    await this.executeOpen<unknown>(
+      'DELETE',
+      this.appendQuery('/api/open/qqBot/delete', { id }),
+    );
+  }
+}
+
+function withDefaultSendType(req: QqBotSaveRequest): QqBotSaveRequest {
+  return { ...req, sendType: req.sendType ?? SEND_TYPE_QQ_GROUP };
+}

package/src/api/topic-user-api.ts

@@ -1,7 +1,7 @@
 import { AccessKeyManager } from '../access-key-manager';
 import { ResolvedPushPlusConfig } from '../config';
 import { HttpRequester } from '../http';
-import { PageResult, TopicUserItem, TopicUserListQuery } from '../models';
+import { PageResult, TopicUserBlacklistItem, TopicUserItem, TopicUserListQuery } from '../models';
 import { OpenAbstractApi } from './open-base';
 
 /**
@@ -27,4 +27,43 @@ export class TopicUserApi extends OpenAbstractApi {
   async editRemark(id: number, remark: string): Promise<void> {
     await this.executeOpen<unknown>('POST', '/api/open/topicUser/editRemark', { id, remark });
   }
+
+  /**
+   * 4. 将订阅人加入黑名单。
+   *
+   * 加入后将移出群组，对方无法再加入该群组。积分群组不支持黑名单。不能将自己加入黑名单。
+   *
+   * @param topicRelationId 用户编号（订阅人列表中的 id 字段）
+   */
+  async addBlacklist(topicRelationId: number): Promise<void> {
+    const path = this.appendQuery('/api/open/topicUser/addBlacklist', { topicRelationId });
+    await this.executeOpen<unknown>('POST', path);
+  }
+
+  /**
+   * 5. 订阅人黑名单列表。
+   *
+   * `query.params.topicId` 必填。
+   */
+  blacklistList(query: TopicUserListQuery): Promise<PageResult<TopicUserBlacklistItem>> {
+    return this.executeOpen<PageResult<TopicUserBlacklistItem>>(
+      'POST',
+      '/api/open/topicUser/blacklistList',
+      query,
+    );
+  }
+
+  /**
+   * 6. 解除订阅人黑名单。
+   *
+   * 解除后不会自动恢复群组订阅，对方可重新加入该群组。
+   *
+   * @param id 黑名单记录 ID（黑名单列表中的 id 字段）
+   */
+  async removeBlacklist(id: number): Promise<void> {
+    await this.executeOpen<unknown>(
+      'POST',
+      this.appendQuery('/api/open/topicUser/removeBlacklist', { id }),
+    );
+  }
 }

package/src/client.ts

@@ -11,6 +11,7 @@ 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 { QqBotApi } from './api/qqbot-api';
 import { SettingApi } from './api/setting-api';
 import { TopicApi } from './api/topic-api';
 import { TopicUserApi } from './api/topic-user-api';
@@ -67,6 +68,7 @@ export class PushPlusClient {
   readonly webhook: WebhookApi;
   readonly channel: ChannelApi;
   readonly clawBot: ClawBotApi;
+  readonly qqBot: QqBotApi;
   readonly setting: SettingApi;
   readonly pre: PreApi;
   readonly image: ImageApi;
@@ -92,6 +94,7 @@ export class PushPlusClient {
     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.qqBot = new QqBotApi(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);
     this.image = new ImageApi(this.config, this.httpRequester, this.accessKeyManager);

package/src/config.ts

@@ -87,6 +87,6 @@ export function resolveConfig(input: PushPlusConfig | undefined | null): Resolve
     logRequest: cfg.logRequest ?? false,
     rateLimitGuardEnabled: cfg.rateLimitGuardEnabled ?? true,
     rateLimitCooldownMs: cfg.rateLimitCooldownMs ?? 0,
-    userAgent: cfg.userAgent ?? `@perk-net/perk-pushplus-sdk/1.2.0`,
+    userAgent: cfg.userAgent ?? `@perk-net/perk-pushplus-sdk/1.2.1`,
   };
 }

package/src/enums.ts

@@ -22,6 +22,8 @@ export enum Channel {
   APP = 'app',
   /** 微信 ClawBot。 */
   CLAWBOT = 'clawbot',
+  /** QQ 机器人；不带 option 发给自己，option 填配置编码则发到对应 QQ 群。 */
+  QQ = 'qq',
 }
 
 /**

package/src/index.ts

@@ -79,13 +79,21 @@ export type {
   TopicItem,
   TopicUserItem,
   TopicUserListQuery,
+  TopicUserBlacklistItem,
   WebhookItem,
   WebhookSaveRequest,
   FriendItem,
   FriendQrCode,
+  FriendBlacklistItem,
   ClawBotInfo,
   ClawBotMessage,
   ClawBotQrCode,
+  QqBotBindLink,
+  QqBotBindInfo,
+  QqBotInfo,
+  QqBotItem,
+  QqBotSaveRequest,
+  QqGroupItem,
   MpItem,
   CpItem,
   MailItem,
@@ -140,6 +148,7 @@ export { FriendApi } from './api/friend-api';
 export { WebhookApi } from './api/webhook-api';
 export { ChannelApi } from './api/channel-api';
 export { ClawBotApi } from './api/clawbot-api';
+export { QqBotApi } from './api/qqbot-api';
 export { SettingApi } from './api/setting-api';
 export { PreApi } from './api/pre-api';
 export {
@@ -150,3 +159,4 @@ export {
 export { FormApi } from './api/form-api';
 export { DocApi } from './api/doc-api';
 export { ExcelApi } from './api/excel-api';
+export { type FileInput } from './multipart';

package/src/models.ts

@@ -270,6 +270,7 @@ export interface SendCount {
   cpSendCount?: number;
   webhookSendCount?: number;
   mailSendCount?: number;
+  qqBotSendCount?: number;
 }
 
 export interface UserLimitTime {
@@ -426,6 +427,19 @@ export interface TopicUserListQuery {
   params?: Record<string, unknown>;
 }
 
+/** 群组订阅人黑名单列表项。 */
+export interface TopicUserBlacklistItem {
+  /** 黑名单记录 ID；解除黑名单时使用。 */
+  id?: number;
+  /** 被拉黑用户 ID。 */
+  userId?: number;
+  nickName?: string;
+  openId?: string;
+  headImgUrl?: string;
+  /** 拉黑时间。 */
+  createTime?: string;
+}
+
 /* ============================== 开放接口 - webhook ============================== */
 
 export interface WebhookItem {
@@ -474,6 +488,18 @@ export interface FriendQrCode {
   qrCodeImgUrl?: string;
 }
 
+/** 好友黑名单列表项。 */
+export interface FriendBlacklistItem {
+  /** 黑名单记录 ID；解除黑名单时使用。 */
+  id?: number;
+  /** 被拉黑好友 ID。 */
+  friendId?: number;
+  nickName?: string;
+  headImgUrl?: string;
+  /** 拉黑时间。 */
+  createTime?: string;
+}
+
 /* ============================== 开放接口 - clawbot ============================== */
 
 export interface ClawBotInfo {
@@ -493,6 +519,82 @@ export interface ClawBotQrCode {
   qrcode?: string;
 }
 
+/* ============================== 开放接口 - QQ 机器人 ============================== */
+
+export interface QqBotBindLink {
+  /** 带参分享链接，用于生成扫码二维码；已绑定用户再次获取时可能为空。 */
+  url?: string;
+  /** 绑定码。已是好友时扫码收不到加好友事件，需私聊发送该码；认领 QQ 群也用此码。 */
+  bindCode?: string;
+  /** 有效期秒数，默认 300。 */
+  expireSeconds?: number;
+  /** 为当前用户分配的官方机器人 appId。 */
+  botAppId?: string;
+  botName?: string;
+  botAvatar?: string;
+}
+
+export interface QqBotInfo {
+  botId?: string;
+  username?: string;
+  avatar?: string;
+  appId?: string;
+  /** 官方分享链接，可用于拉机器人进群。 */
+  shareUrl?: string;
+}
+
+export interface QqBotBindInfo {
+  /** 0-未绑定，1-已绑定。 */
+  isBind?: number;
+  /** 1-可接收，0-用户已关闭单聊接收。 */
+  receiveStatus?: number;
+  createTime?: string;
+  botInfo?: QqBotInfo;
+}
+
+export 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;
+}
+
+export interface QqBotItem {
+  id?: number;
+  qqName?: string;
+  /** 配置编码；发送消息时作为 option 传入。 */
+  qqCode?: string;
+  /** 2-发到 QQ 群。 */
+  sendType?: number;
+  qqGroupId?: number;
+  groupRemark?: string;
+  groupOpenId?: string;
+  groupName?: string;
+  updateTime?: string;
+}
+
+export interface QqBotSaveRequest {
+  /** 修改时必填。 */
+  id?: number;
+  /** 配置名称，必填，最多 64 个字符。 */
+  qqName?: string;
+  /** 配置编码，新增必填；仅支持字母、数字、下划线和中划线，创建后不可修改。 */
+  qqCode?: string;
+  /** 发送类型；留空时 SDK 自动填 2（发到 QQ 群）。 */
+  sendType?: number;
+  /** QQ 群编号，必填，取自 groupList 返回的 id。 */
+  qqGroupId?: number;
+}
+
 /* ============================== 开放接口 - channel ============================== */
 
 export interface MpItem {
@@ -661,16 +763,19 @@ export interface ImageItem {
 
 /* ============================== 开放接口 - form（push 表单） ============================== */
 
-/** 我的表单分页查询。 */
+/** 我的表单分页查询。官方结构为 `{current, pageSize, params:{keyword, status}}`。 */
 export 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;
+  };
 }
 
 /** 表单封面页配置。 */
@@ -786,13 +891,18 @@ export interface FormPublishResult {
 
 /* ============================== 开放接口 - doc / excel 共用查询 ============================== */
 
-/** 文档 / 表格分页查询。 */
+/** 文档 / 表格分页查询。官方结构为 `{current, pageSize, params:{keyword, shareEnabled}}`。 */
 export 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;
+  };
 }
 
 /** 文档 / 表格列表项。 */