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

package/README.md

@@ -5,7 +5,7 @@
 - **同时支持 Node.js 与浏览器**：Node.js 18+ 使用内置 `fetch`，浏览器使用原生 `fetch`，无运行时依赖。
 - **三种产物**：CommonJS (`.cjs`) + ESModule (`.js`) + 浏览器 IIFE (`.global.js`)，可通过 npm / `<script>` 直接加载。
 - **完整 TypeScript 类型**：所有请求 / 响应 / 枚举 / 回调全部带类型声明。
-- **全部开放接口**：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理、图片服务（含一键上传到 PushPlus 图床）、push 表单、push 文档、push 表格。
+- **全部开放接口**：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、QQ 机器人、功能设置、预处理、图片服务（含一键上传到 PushPlus 图床）、push 表单、push 文档、push 表格。
 - **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
 - **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
 - **Builder 链式 API**：与 Java/Python SDK 风格保持一致。
@@ -90,7 +90,7 @@ await client.send({
   template: Template.MARKDOWN,
 });
 
-// push 表单：template=form 时需传 pushId（表单编码）
+// push 表单 / 文档 / 表格：template 为 form/doc/excel 时需传 pushId（对应编码）
 await client.send(
   sendRequest()
     .title('表单通知')
@@ -99,6 +99,22 @@ await client.send(
     .pushId('表单编码')
     .build(),
 );
+await client.send(
+  sendRequest()
+    .title('本周工作同步')
+    .content('请查收')
+    .template(Template.DOC)
+    .pushId('文档编码')
+    .build(),
+);
+await client.send(
+  sendRequest()
+    .title('销售日报')
+    .content('请查收')
+    .template(Template.EXCEL)
+    .pushId('表格编码')
+    .build(),
+);
 ```
 
 ### 3. 多渠道发送
@@ -151,10 +167,18 @@ const qr = await client.topic.qrCode(123, 86400, -1);
 
 // 群组用户
 await client.topicUser.editRemark(456, '老张');
+await client.topicUser.addBlacklist(10);
+const topicBlacklist = await client.topicUser.blacklistList({
+  current: 1,
+  pageSize: 20,
+  params: { topicId: 1 },
+});
 
 // 好友
 const myQr = await client.friend.getQrCode({ content: 'welcome' });
 const friends = await client.friend.list({ current: 1, pageSize: 20 });
+await client.friend.addBlacklist(friends.list[0].friendId);
+const friendBlacklist = await client.friend.blacklistList({ current: 1, pageSize: 20 });
 
 // webhook 渠道
 import { WebhookType } from '@perk-net/perk-pushplus-sdk';
@@ -171,6 +195,19 @@ const mps = await client.channel.mpList();
 // ClawBot
 const botQr = await client.clawBot.getBotQrcode();
 
+// QQ 机器人：绑定 -> 认领群 -> 建配置 -> 发到群
+const link = await client.qqBot.getBindLink();   // link.url 生成二维码，或私聊发送 link.bindCode
+const bind = await client.qqBot.botInfo();       // bind.isBind === 1 表示已绑定
+const qqGroups = await client.qqBot.groupList();
+await client.qqBot.add({ qqName: '运维告警群', qqCode: 'ops-group', qqGroupId: qqGroups[0].id });
+await client.send({
+  title: '服务告警',
+  content: '订单服务响应超时',
+  channel: Channel.QQ,
+  option: 'ops-group', // 不传 option 则发给自己
+  template: Template.TXT,
+});
+
 // 设置
 await client.setting.changeIsSend(1); // 启用发送
 await client.setting.changeOpenMessageType(0);
@@ -195,20 +232,38 @@ await client.form.save({
 });
 const published = await client.form.publish(form.id!);
 console.log(published.fillUrl);
+await client.send({
+  title: published.title,
+  content: '请花1分钟完成填写',
+  template: Template.FORM,
+  pushId: published.formCode,
+});
 
 // push 文档
-const doc = await client.doc.create('本周工作同步');
-await client.doc.saveContent(doc.docCode!, '<h1>本周工作同步</h1><p>需求评审。</p>');
+import { readFile } from 'node:fs/promises';
+const doc = await client.doc.importWord(await readFile('本周工作同步.docx'), '本周工作同步.docx');
 await client.doc.updateShare(doc.docCode!, 1, 0);
 await client.doc.publish(doc.docCode!);
+await client.send({
+  title: doc.title,
+  content: '请查收',
+  template: Template.DOC,
+  pushId: doc.docCode,
+});
 
 // push 表格
-const sheet = await client.excel.create('销售日报');
+const sheet = await client.excel.importExcel(await readFile('销售日报.xlsx'), '销售日报.xlsx');
 await client.excel.writeCells(sheet.docCode!, 'A1', [
   ['日期', '销售额'],
   ['2026-08-13', 12800],
 ], 'Sheet1');
 await client.excel.publish(sheet.docCode!);
+await client.send({
+  title: sheet.title,
+  content: '请查收',
+  template: Template.EXCEL,
+  pushId: sheet.docCode,
+});
 ```
 
 ### 图片服务

package/dist/index.cjs

@@ -11,6 +11,7 @@ var Channel = /* @__PURE__ */ ((Channel2) => {
   Channel2["EXTENSION"] = "extension";
   Channel2["APP"] = "app";
   Channel2["CLAWBOT"] = "clawbot";
+  Channel2["QQ"] = "qq";
   return Channel2;
 })(Channel || {});
 var Template = /* @__PURE__ */ ((Template2) => {
@@ -375,6 +376,26 @@ var AbstractApi = class {
     }
     return parseApiResponse(resp);
   }
+  /**
+   * 执行带二进制请求体的请求并返回原始 ApiResponse（不进行 code 校验）。
+   * 用于 multipart 上传等场景。
+   */
+  async executeRaw(method, path, headers, body) {
+    const url = this.resolveUrl(path);
+    const resp = await callExecuteRaw(this.http, {
+      method,
+      url,
+      headers: headers != null ? headers : void 0,
+      body
+    });
+    if (!isSuccessfulHttpStatus(resp.statusCode)) {
+      throw new PushPlusError(
+        `PushPlus \u63A5\u53E3 HTTP \u8C03\u7528\u5931\u8D25: status=${resp.statusCode}, body=${resp.body}`,
+        resp.statusCode
+      );
+    }
+    return parseApiResponse(resp);
+  }
   /** 执行请求并直接返回 data；非 200 抛出异常。 */
   async executeForData(method, path, headers, body) {
     var _a;
@@ -505,6 +526,39 @@ var _OpenAbstractApi = class _OpenAbstractApi extends AbstractApi {
       (_b = resp.code) != null ? _b : -1
     );
   }
+  /** 以 multipart 上传文件（自动携带 access-key；code=401 时刷新后重试一次）。 */
+  executeOpenMultipart(path, multipart) {
+    return this.executeOpenRaw("POST", path, multipart.body, {
+      "Content-Type": multipart.contentType
+    });
+  }
+  /**
+   * 执行带二进制 body 的开放接口请求；当返回 code=401 时自动刷新 key 并重试一次。
+   */
+  async executeOpenRaw(method, path, body, extraHeaders) {
+    var _a, _b;
+    const headers = { ...await this.headersWithAccessKey(), ...extraHeaders != null ? extraHeaders : {} };
+    const resp = await this.executeRaw(method, path, headers, body);
+    if (isApiSuccess(resp)) {
+      return resp.data;
+    }
+    if (resp.code === _OpenAbstractApi.CODE_ACCESS_KEY_INVALID) {
+      this.accessKeyManager.invalidate();
+      const retryHeaders = { ...await this.headersWithAccessKey(), ...extraHeaders != null ? extraHeaders : {} };
+      const retry = await this.executeRaw(method, path, retryHeaders, body);
+      if (isApiSuccess(retry)) {
+        return retry.data;
+      }
+      throw new PushPlusError(
+        `PushPlus \u5F00\u653E\u63A5\u53E3\u4E1A\u52A1\u5931\u8D25(\u91CD\u8BD5\u540E): code=${retry.code}, msg=${retry.msg}`,
+        (_a = retry.code) != null ? _a : -1
+      );
+    }
+    throw new PushPlusError(
+      `PushPlus \u5F00\u653E\u63A5\u53E3\u4E1A\u52A1\u5931\u8D25: code=${resp.code}, msg=${resp.msg}`,
+      (_b = resp.code) != null ? _b : -1
+    );
+  }
 };
 _OpenAbstractApi.HEADER_ACCESS_KEY = "access-key";
 /** PushPlus AccessKey 失效相关的业务码（用于触发自动重试）。 */
@@ -567,6 +621,50 @@ var ClawBotApi = class extends OpenAbstractApi {
   }
 };
 
+// src/multipart.ts
+function buildFileMultipart(fileName, contentType, fileBytes) {
+  if (fileBytes == null || fileBytes.byteLength === 0) {
+    throw new PushPlusError("\u4E0A\u4F20\u6587\u4EF6\u5185\u5BB9\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  const safeName = fileName && fileName.trim() ? fileName : "file";
+  const mime = contentType && contentType.trim() ? contentType : "application/octet-stream";
+  const boundary = "----PushPlusBoundary" + randomBoundarySuffix();
+  const crlf = "\r\n";
+  const enc = new TextEncoder();
+  const head = enc.encode(
+    `--${boundary}${crlf}Content-Disposition: form-data; name="file"; filename="${escapeFileName(safeName)}"${crlf}Content-Type: ${mime}${crlf}${crlf}`
+  );
+  const tail = enc.encode(`${crlf}--${boundary}--${crlf}`);
+  const body = new Uint8Array(head.byteLength + fileBytes.byteLength + tail.byteLength);
+  body.set(head, 0);
+  body.set(fileBytes, head.byteLength);
+  body.set(tail, head.byteLength + fileBytes.byteLength);
+  return { contentType: `multipart/form-data; boundary=${boundary}`, body };
+}
+async function toFileBytes(file) {
+  if (file instanceof Uint8Array) {
+    return file;
+  }
+  if (file instanceof ArrayBuffer) {
+    return new Uint8Array(file);
+  }
+  if (typeof Blob !== "undefined" && file instanceof Blob) {
+    const ab = await file.arrayBuffer();
+    return new Uint8Array(ab);
+  }
+  throw new PushPlusError(`\u4E0D\u652F\u6301\u7684\u4E0A\u4F20\u6587\u4EF6\u7C7B\u578B: ${Object.prototype.toString.call(file)}`);
+}
+function escapeFileName(name) {
+  return name.replace(/"/g, "_").replace(/\r/g, " ").replace(/\n/g, " ");
+}
+function randomBoundarySuffix() {
+  let s = "";
+  for (let i = 0; i < 32; i++) {
+    s += Math.floor(Math.random() * 16).toString(16);
+  }
+  return s;
+}
+
 // src/api/doc-api.ts
 var DocApi = class extends OpenAbstractApi {
   constructor(config, http, mgr) {
@@ -584,6 +682,19 @@ var DocApi = class extends OpenAbstractApi {
   create(title) {
     return this.executeOpen("POST", "/push/api/open/doc/create", { title });
   }
+  /**
+   * 导入 Word（.docx）创建文档。
+   *
+   * 标题默认取文件名；创建后默认关闭分享，需再调用 publish 才会同步到分享页。
+   */
+  async importWord(file, fileName = "document.docx") {
+    const bytes = await toFileBytes(file);
+    const name = fileName && fileName.trim() ? fileName : "document.docx";
+    return this.executeOpenMultipart(
+      "/push/api/open/doc/import",
+      buildFileMultipart(name, guessDocxContentType(name), bytes)
+    );
+  }
   /** 获取文档元信息与 HTML 草稿正文。 */
   content(docCode) {
     return this.executeOpen(
@@ -625,6 +736,9 @@ var DocApi = class extends OpenAbstractApi {
     return this.executeOpen("POST", "/push/api/open/doc/updateShare", body);
   }
 };
+function guessDocxContentType(name) {
+  return name.toLowerCase().endsWith(".docx") ? "application/vnd.openxmlformats-officedocument.wordprocessingml.document" : "application/octet-stream";
+}
 
 // src/api/excel-api.ts
 var ExcelApi = class extends OpenAbstractApi {
@@ -643,6 +757,19 @@ var ExcelApi = class extends OpenAbstractApi {
   create(title) {
     return this.executeOpen("POST", "/push/api/open/excel/create", { title });
   }
+  /**
+   * 导入 Excel（.xlsx / .xls）创建表格。
+   *
+   * 标题默认取文件名；创建后默认关闭分享，需再调用 publish 才会同步到分享页。
+   */
+  async importExcel(file, fileName = "workbook.xlsx") {
+    const bytes = await toFileBytes(file);
+    const name = fileName && fileName.trim() ? fileName : "workbook.xlsx";
+    return this.executeOpenMultipart(
+      "/push/api/open/excel/import",
+      buildFileMultipart(name, guessExcelContentType(name), bytes)
+    );
+  }
   /** 获取表格元信息与整表 JSON 草稿。 */
   content(docCode) {
     return this.executeOpen(
@@ -713,6 +840,16 @@ function stringifyJsonContent(content) {
     throw new PushPlusError(`\u5E8F\u5217\u5316\u8868\u683C\u5185\u5BB9\u5931\u8D25: ${e.message}`, -1, { cause: e });
   }
 }
+function guessExcelContentType(name) {
+  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";
+}
 
 // src/api/form-api.ts
 var FormApi = class extends OpenAbstractApi {
@@ -808,6 +945,40 @@ var FriendApi = class extends OpenAbstractApi {
   async editRemark(id, remark) {
     await this.executeOpen("POST", "/api/open/friend/editRemark", { id, remark });
   }
+  /**
+   * 5. 将好友加入黑名单。
+   *
+   * 加入后将解除双方好友关系，对方无法再添加你。不能将自己加入黑名单，仅可将已有好友加入黑名单。
+   *
+   * @param friendId 好友 id（好友列表中的 friendId 字段）
+   */
+  async addBlacklist(friendId) {
+    await this.executeOpen(
+      "POST",
+      this.appendQuery("/api/open/friend/addBlacklist", { friendId })
+    );
+  }
+  /** 6. 好友黑名单列表。 */
+  blacklistList(query) {
+    return this.executeOpen(
+      "POST",
+      "/api/open/friend/blacklistList",
+      query != null ? query : {}
+    );
+  }
+  /**
+   * 7. 解除好友黑名单。
+   *
+   * 解除后不会自动恢复好友关系，需重新扫码添加。
+   *
+   * @param id 黑名单记录 ID（黑名单列表中的 id 字段）
+   */
+  async removeBlacklist(id) {
+    await this.executeOpen(
+      "POST",
+      this.appendQuery("/api/open/friend/removeBlacklist", { id })
+    );
+  }
 };
 
 // src/api/image-api.ts
@@ -856,7 +1027,7 @@ var ImageApi = class extends OpenAbstractApi {
     }
     const fileName = options.fileName || "file";
     const contentType = options.contentType || guessContentTypeByName(fileName) || "application/octet-stream";
-    const boundary = "----PushPlusBoundary" + randomBoundarySuffix();
+    const boundary = "----PushPlusBoundary" + randomBoundarySuffix2();
     const body = buildMultipartBody(boundary, uploadToken, fileName, contentType, bytes);
     const resp = await callExecuteRaw(this.http, {
       method: "POST",
@@ -942,7 +1113,7 @@ function buildMultipartBody(boundary, uploadToken, fileName, contentType, fileBy
   const crlf = "\r\n";
   const enc = new TextEncoder();
   const head = enc.encode(
-    `--${boundary}${crlf}Content-Disposition: form-data; name="token"${crlf}${crlf}${uploadToken}${crlf}--${boundary}${crlf}Content-Disposition: form-data; name="file"; filename="${escapeFileName(fileName)}"${crlf}Content-Type: ${contentType}${crlf}${crlf}`
+    `--${boundary}${crlf}Content-Disposition: form-data; name="token"${crlf}${crlf}${uploadToken}${crlf}--${boundary}${crlf}Content-Disposition: form-data; name="file"; filename="${escapeFileName2(fileName)}"${crlf}Content-Type: ${contentType}${crlf}${crlf}`
   );
   const tail = enc.encode(`${crlf}--${boundary}--${crlf}`);
   const out = new Uint8Array(head.byteLength + fileBytes.byteLength + tail.byteLength);
@@ -951,7 +1122,7 @@ function buildMultipartBody(boundary, uploadToken, fileName, contentType, fileBy
   out.set(tail, head.byteLength + fileBytes.byteLength);
   return out;
 }
-function escapeFileName(name) {
+function escapeFileName2(name) {
   return name.replace(/"/g, "_").replace(/\r/g, " ").replace(/\n/g, " ");
 }
 function guessContentTypeByName(name) {
@@ -964,7 +1135,7 @@ function guessContentTypeByName(name) {
   if (lower.endsWith(".svg")) return "image/svg+xml";
   return null;
 }
-function randomBoundarySuffix() {
+function randomBoundarySuffix2() {
   let s = "";
   for (let i = 0; i < 32; i++) {
     s += Math.floor(Math.random() * 16).toString(16);
@@ -1156,6 +1327,55 @@ var PreApi = class extends OpenAbstractApi {
   }
 };
 
+// src/api/qqbot-api.ts
+var SEND_TYPE_QQ_GROUP = 2;
+var QqBotApi = class extends OpenAbstractApi {
+  constructor(config, http, mgr) {
+    super(config, http, mgr);
+  }
+  /** 1. 获取绑定链接与绑定码；refresh 为 true 时旧绑定码失效并重新生成。 */
+  getBindLink(refresh = false) {
+    const path = refresh ? this.appendQuery("/api/open/qqBot/getBindLink", { refresh: true }) : "/api/open/qqBot/getBindLink";
+    return this.executeOpen("GET", path);
+  }
+  /** 2. 查询绑定状态。 */
+  botInfo() {
+    return this.executeOpen("GET", "/api/open/qqBot/botInfo");
+  }
+  /** 3. 解绑 QQ 机器人。 */
+  async unbind() {
+    await this.executeOpen("GET", "/api/open/qqBot/unbind");
+  }
+  /** 4. 获取机器人已加入的 QQ 群列表。 */
+  async groupList() {
+    var _a;
+    return (_a = await this.executeOpen("GET", "/api/open/qqBot/groupList")) != null ? _a : [];
+  }
+  /** 5. 获取 QQ 机器人渠道配置列表。 */
+  list(q) {
+    return this.executeOpen("POST", "/api/open/qqBot/list", q != null ? q : {});
+  }
+  /** 6. 新增渠道配置，用于把消息发送到指定 QQ 群；发给自己无需创建配置。 */
+  async add(req) {
+    await this.executeOpen("POST", "/api/open/qqBot/add", withDefaultSendType(req));
+  }
+  /** 7. 修改渠道配置；配置编码不可修改。 */
+  async edit(req) {
+    await this.executeOpen("POST", "/api/open/qqBot/edit", withDefaultSendType(req));
+  }
+  /** 8. 删除渠道配置。 */
+  async delete(id) {
+    await this.executeOpen(
+      "DELETE",
+      this.appendQuery("/api/open/qqBot/delete", { id })
+    );
+  }
+};
+function withDefaultSendType(req) {
+  var _a;
+  return { ...req, sendType: (_a = req.sendType) != null ? _a : SEND_TYPE_QQ_GROUP };
+}
+
 // src/api/setting-api.ts
 var SettingApi = class extends OpenAbstractApi {
   constructor(config, http, mgr) {
@@ -1307,6 +1527,42 @@ var TopicUserApi = class extends OpenAbstractApi {
   async editRemark(id, remark) {
     await this.executeOpen("POST", "/api/open/topicUser/editRemark", { id, remark });
   }
+  /**
+   * 4. 将订阅人加入黑名单。
+   *
+   * 加入后将移出群组，对方无法再加入该群组。积分群组不支持黑名单。不能将自己加入黑名单。
+   *
+   * @param topicRelationId 用户编号（订阅人列表中的 id 字段）
+   */
+  async addBlacklist(topicRelationId) {
+    const path = this.appendQuery("/api/open/topicUser/addBlacklist", { topicRelationId });
+    await this.executeOpen("POST", path);
+  }
+  /**
+   * 5. 订阅人黑名单列表。
+   *
+   * `query.params.topicId` 必填。
+   */
+  blacklistList(query) {
+    return this.executeOpen(
+      "POST",
+      "/api/open/topicUser/blacklistList",
+      query
+    );
+  }
+  /**
+   * 6. 解除订阅人黑名单。
+   *
+   * 解除后不会自动恢复群组订阅，对方可重新加入该群组。
+   *
+   * @param id 黑名单记录 ID（黑名单列表中的 id 字段）
+   */
+  async removeBlacklist(id) {
+    await this.executeOpen(
+      "POST",
+      this.appendQuery("/api/open/topicUser/removeBlacklist", { id })
+    );
+  }
 };
 
 // src/api/user-api.ts
@@ -1371,7 +1627,7 @@ function resolveConfig(input) {
     logRequest: (_g = cfg.logRequest) != null ? _g : false,
     rateLimitGuardEnabled: (_h = cfg.rateLimitGuardEnabled) != null ? _h : true,
     rateLimitCooldownMs: (_i = cfg.rateLimitCooldownMs) != null ? _i : 0,
-    userAgent: (_j = cfg.userAgent) != null ? _j : `@perk-net/perk-pushplus-sdk/1.2.0`
+    userAgent: (_j = cfg.userAgent) != null ? _j : `@perk-net/perk-pushplus-sdk/1.2.1`
   };
 }
 
@@ -1463,6 +1719,7 @@ var PushPlusClient = 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);
@@ -1730,6 +1987,7 @@ exports.PushPlusClient = PushPlusClient;
 exports.PushPlusClientBuilder = PushPlusClientBuilder;
 exports.PushPlusError = PushPlusError;
 exports.PushPlusException = PushPlusException;
+exports.QqBotApi = QqBotApi;
 exports.RateLimitGuard = RateLimitGuard;
 exports.SendRequestBuilder = SendRequestBuilder;
 exports.SendStatus = SendStatus;