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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perk-net/perk-pushplus-sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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/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/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/index.ts

@@ -79,10 +79,12 @@ export type {
   TopicItem,
   TopicUserItem,
   TopicUserListQuery,
+  TopicUserBlacklistItem,
   WebhookItem,
   WebhookSaveRequest,
   FriendItem,
   FriendQrCode,
+  FriendBlacklistItem,
   ClawBotInfo,
   ClawBotMessage,
   ClawBotQrCode,
@@ -150,3 +152,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

@@ -426,6 +426,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 +487,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 {
@@ -661,16 +686,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 +814,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;
+  };
 }
 
 /** 文档 / 表格列表项。 */

package/src/multipart.ts

@@ -0,0 +1,62 @@
+import { PushPlusError } from './exception';
+
+/** 二进制文件输入。 */
+export type FileInput = Uint8Array | ArrayBuffer | Blob;
+
+export interface FileMultipart {
+  contentType: string;
+  body: Uint8Array;
+}
+
+/** 构造仅含一个 file 字段的 multipart/form-data 请求体。 */
+export function buildFileMultipart(
+  fileName: string,
+  contentType: string | undefined,
+  fileBytes: Uint8Array,
+): FileMultipart {
+  if (fileBytes == null || fileBytes.byteLength === 0) {
+    throw new PushPlusError('上传文件内容不能为空');
+  }
+  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 };
+}
+
+export async function toFileBytes(file: FileInput): Promise<Uint8Array> {
+  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(`不支持的上传文件类型: ${Object.prototype.toString.call(file)}`);
+}
+
+function escapeFileName(name: string): string {
+  return name.replace(/"/g, '_').replace(/\r/g, ' ').replace(/\n/g, ' ');
+}
+
+function randomBoundarySuffix(): string {
+  let s = '';
+  for (let i = 0; i < 32; i++) {
+    s += Math.floor(Math.random() * 16).toString(16);
+  }
+  return s;
+}