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

package/package.json

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

package/src/api/doc-api.ts

@@ -0,0 +1,77 @@
+import { AccessKeyManager } from '../access-key-manager';
+import { ResolvedPushPlusConfig } from '../config';
+import { HttpRequester } from '../http';
+import { DocContent, DocListItem, DocListQuery, DocVo, PageResult } from '../models';
+import { OpenAbstractApi } from './open-base';
+
+/**
+ * 开放接口 - push 文档。
+ *
+ * 文档：https://www.pushplus.plus/doc/ecosystem/doc/
+ * 基础路径：`/push/api/open/doc`
+ */
+export class DocApi extends OpenAbstractApi {
+  constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager) {
+    super(config, http, mgr);
+  }
+
+  /** 我的文档分页。 */
+  list(query?: DocListQuery): Promise<PageResult<DocListItem>> {
+    return this.executeOpen<PageResult<DocListItem>>(
+      'POST',
+      '/push/api/open/doc/list',
+      query ?? {},
+    );
+  }
+
+  /** 创建空白文档。 */
+  create(title: string): Promise<DocVo> {
+    return this.executeOpen<DocVo>('POST', '/push/api/open/doc/create', { title });
+  }
+
+  /** 获取文档元信息与 HTML 草稿正文。 */
+  content(docCode: string): Promise<DocContent> {
+    return this.executeOpen<DocContent>(
+      'GET',
+      this.appendQuery('/push/api/open/doc/content', { docCode }),
+    );
+  }
+
+  /** 保存 HTML 草稿（不影响分享页，需再 publish）。 */
+  saveContent(docCode: string, content: string): Promise<DocVo> {
+    return this.executeOpen<DocVo>('POST', '/push/api/open/doc/saveContent', { docCode, content });
+  }
+
+  /** 将草稿同步为分享页快照。 */
+  publish(docCode: string): Promise<DocVo> {
+    return this.executeOpen<DocVo>(
+      'POST',
+      this.appendQuery('/push/api/open/doc/publish', { docCode }),
+    );
+  }
+
+  /** 重命名。 */
+  async rename(docCode: string, title: string): Promise<void> {
+    await this.executeOpen<unknown>('POST', '/push/api/open/doc/rename', { docCode, title });
+  }
+
+  /** 删除文档。 */
+  async delete(docCode: string): Promise<void> {
+    await this.executeOpen<unknown>(
+      'POST',
+      this.appendQuery('/push/api/open/doc/delete', { docCode }),
+    );
+  }
+
+  /**
+   * 更新分享设置。
+   *
+   * @param sharePerm 0 关闭 / 1 开启（仅可查看）
+   * @param shareLogin 0 免登录 / 1 需登录；不传则沿用原值
+   */
+  updateShare(docCode: string, sharePerm: number, shareLogin?: number): Promise<DocVo> {
+    const body: Record<string, unknown> = { docCode, sharePerm };
+    if (shareLogin != null) body.shareLogin = shareLogin;
+    return this.executeOpen<DocVo>('POST', '/push/api/open/doc/updateShare', body);
+  }
+}

package/src/api/excel-api.ts

@@ -0,0 +1,114 @@
+import { AccessKeyManager } from '../access-key-manager';
+import { ResolvedPushPlusConfig } from '../config';
+import { PushPlusError } from '../exception';
+import { HttpRequester } from '../http';
+import { DocListItem, DocListQuery, ExcelContent, ExcelVo, PageResult } from '../models';
+import { OpenAbstractApi } from './open-base';
+
+/**
+ * 开放接口 - push 表格。
+ *
+ * 文档：https://www.pushplus.plus/doc/ecosystem/sheet/
+ * 基础路径：`/push/api/open/excel`
+ */
+export class ExcelApi extends OpenAbstractApi {
+  constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager) {
+    super(config, http, mgr);
+  }
+
+  /** 我的表格分页。 */
+  list(query?: DocListQuery): Promise<PageResult<DocListItem>> {
+    return this.executeOpen<PageResult<DocListItem>>(
+      'POST',
+      '/push/api/open/excel/list',
+      query ?? {},
+    );
+  }
+
+  /** 创建空白表格。 */
+  create(title: string): Promise<ExcelVo> {
+    return this.executeOpen<ExcelVo>('POST', '/push/api/open/excel/create', { title });
+  }
+
+  /** 获取表格元信息与整表 JSON 草稿。 */
+  content(docCode: string): Promise<ExcelContent> {
+    return this.executeOpen<ExcelContent>(
+      'GET',
+      this.appendQuery('/push/api/open/excel/content', { docCode }),
+    );
+  }
+
+  /**
+   * 整表覆盖保存草稿。
+   *
+   * `content` 可为 JSON 字符串，或工作簿对象（SDK 会序列化）。
+   */
+  saveContent(docCode: string, content: string | object): Promise<ExcelVo> {
+    return this.executeOpen<ExcelVo>('POST', '/push/api/open/excel/saveContent', {
+      docCode,
+      content: stringifyJsonContent(content),
+    });
+  }
+
+  /**
+   * 从指定起始单元格起，按二维数组向右向下写入（草稿）。
+   *
+   * @param range 起始单元格，如 A1
+   * @param values 外层为行、内层为列
+   * @param sheetName 工作表名称；不传则写入活动表 / 第一张表
+   */
+  writeCells(
+    docCode: string,
+    range: string,
+    values: unknown[][],
+    sheetName?: string,
+  ): Promise<ExcelVo> {
+    const body: Record<string, unknown> = { docCode, range, values };
+    if (sheetName != null) body.sheetName = sheetName;
+    return this.executeOpen<ExcelVo>('POST', '/push/api/open/excel/writeCells', body);
+  }
+
+  /** 将草稿同步为分享页快照。 */
+  publish(docCode: string): Promise<ExcelVo> {
+    return this.executeOpen<ExcelVo>(
+      'POST',
+      this.appendQuery('/push/api/open/excel/publish', { docCode }),
+    );
+  }
+
+  /** 重命名。 */
+  async rename(docCode: string, title: string): Promise<void> {
+    await this.executeOpen<unknown>('POST', '/push/api/open/excel/rename', { docCode, title });
+  }
+
+  /** 删除表格。 */
+  async delete(docCode: string): Promise<void> {
+    await this.executeOpen<unknown>(
+      'POST',
+      this.appendQuery('/push/api/open/excel/delete', { docCode }),
+    );
+  }
+
+  /**
+   * 更新分享设置。
+   *
+   * @param sharePerm 0 关闭 / 1 开启（仅可查看）
+   * @param shareLogin 0 免登录 / 1 需登录；不传则沿用原值
+   */
+  updateShare(docCode: string, sharePerm: number, shareLogin?: number): Promise<ExcelVo> {
+    const body: Record<string, unknown> = { docCode, sharePerm };
+    if (shareLogin != null) body.shareLogin = shareLogin;
+    return this.executeOpen<ExcelVo>('POST', '/push/api/open/excel/updateShare', body);
+  }
+}
+
+function stringifyJsonContent(content: string | object): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+  try {
+    return JSON.stringify(content);
+  } catch (e) {
+    throw new PushPlusError(`序列化表格内容失败: ${(e as Error).message}`, -1, { cause: e });
+  }
+}

package/src/api/form-api.ts

@@ -0,0 +1,92 @@
+import { AccessKeyManager } from '../access-key-manager';
+import { ResolvedPushPlusConfig } from '../config';
+import { HttpRequester } from '../http';
+import {
+  FormDetail,
+  FormListItem,
+  FormListQuery,
+  FormPublishDiff,
+  FormPublishResult,
+  FormSaveRequest,
+  PageResult,
+} from '../models';
+import { OpenAbstractApi } from './open-base';
+
+/**
+ * 开放接口 - push 表单。
+ *
+ * 文档：https://www.pushplus.plus/doc/ecosystem/form/
+ * 基础路径：`/push/api/open/form`
+ */
+export class FormApi extends OpenAbstractApi {
+  constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager) {
+    super(config, http, mgr);
+  }
+
+  /** 我的表单分页。 */
+  list(query?: FormListQuery): Promise<PageResult<FormListItem>> {
+    return this.executeOpen<PageResult<FormListItem>>(
+      'POST',
+      '/push/api/open/form/list',
+      query ?? {},
+    );
+  }
+
+  /** 创建空白表单（草稿）。 */
+  create(title: string): Promise<FormListItem> {
+    return this.executeOpen<FormListItem>('POST', '/push/api/open/form/create', { title });
+  }
+
+  /** 基于已有表单复制一份新草稿。 */
+  copy(id: number): Promise<FormListItem> {
+    return this.executeOpen<FormListItem>(
+      'POST',
+      this.appendQuery('/push/api/open/form/copy', { id }),
+    );
+  }
+
+  /** 保存表单设计（仅更新草稿；已发布需再调用 publish）。 */
+  async save(req: FormSaveRequest): Promise<void> {
+    await this.executeOpen<unknown>('POST', '/push/api/open/form/save', req);
+  }
+
+  /** 表单详情（含草稿题目、主题、设置）。 */
+  detail(id: number): Promise<FormDetail> {
+    return this.executeOpen<FormDetail>(
+      'GET',
+      this.appendQuery('/push/api/open/form/detail', { id }),
+    );
+  }
+
+  /** 草稿与发布快照的题目差异。 */
+  publishDiff(id: number): Promise<FormPublishDiff> {
+    return this.executeOpen<FormPublishDiff>(
+      'GET',
+      this.appendQuery('/push/api/open/form/publishDiff', { id }),
+    );
+  }
+
+  /** 发布表单，开始收集。 */
+  publish(id: number): Promise<FormPublishResult> {
+    return this.executeOpen<FormPublishResult>(
+      'POST',
+      this.appendQuery('/push/api/open/form/publish', { id }),
+    );
+  }
+
+  /** 停止收集。 */
+  async stop(id: number): Promise<void> {
+    await this.executeOpen<unknown>(
+      'POST',
+      this.appendQuery('/push/api/open/form/stop', { id }),
+    );
+  }
+
+  /** 删除表单（不可恢复）。 */
+  async delete(id: number): Promise<void> {
+    await this.executeOpen<unknown>(
+      'POST',
+      this.appendQuery('/push/api/open/form/delete', { id }),
+    );
+  }
+}

package/src/client.ts

@@ -2,6 +2,9 @@ import { AccessKeyManager } from './access-key-manager';
 import { AccessKeyApi } from './api/access-key-api';
 import { ChannelApi } from './api/channel-api';
 import { ClawBotApi } from './api/clawbot-api';
+import { DocApi } from './api/doc-api';
+import { ExcelApi } from './api/excel-api';
+import { FormApi } from './api/form-api';
 import { FriendApi } from './api/friend-api';
 import { ImageApi } from './api/image-api';
 import { MessageApi } from './api/message-api';
@@ -67,6 +70,9 @@ export class PushPlusClient {
   readonly setting: SettingApi;
   readonly pre: PreApi;
   readonly image: ImageApi;
+  readonly form: FormApi;
+  readonly doc: DocApi;
+  readonly excel: ExcelApi;
 
   constructor(options: PushPlusClientOptions = {}) {
     this.config = resolveConfig(options);
@@ -89,6 +95,9 @@ export class PushPlusClient {
     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);
+    this.form = new FormApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.doc = new DocApi(this.config, this.httpRequester, this.accessKeyManager);
+    this.excel = new ExcelApi(this.config, this.httpRequester, this.accessKeyManager);
   }
 
   /** 与 Java SDK 风格一致的 Builder 入口。 */

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.1.0`,
+    userAgent: cfg.userAgent ?? `@perk-net/perk-pushplus-sdk/1.2.0`,
   };
 }

package/src/enums.ts

@@ -46,6 +46,10 @@ export enum Template {
   PAY = 'pay',
   /** 表单格式模板；发送时需传 pushId（表单编码）。 */
   FORM = 'form',
+  /** 文档格式模板（push 文档）；发送时需传 pushId。 */
+  DOC = 'doc',
+  /** 表格格式模板（push 表格）；发送时需传 pushId。 */
+  EXCEL = 'excel',
 }
 
 /**
@@ -114,6 +118,43 @@ export const WebhookTypeDescription: Record<number, string> = {
   [WebhookType.CUSTOM]: '自定义',
 };
 
+/**
+ * push 表单状态。
+ *
+ * 0-草稿，1-收集中，2-已停止。
+ */
+export enum FormStatus {
+  DRAFT = 0,
+  COLLECTING = 1,
+  STOPPED = 2,
+}
+
+export const FormStatusDescription: Record<FormStatus, string> = {
+  [FormStatus.DRAFT]: '草稿',
+  [FormStatus.COLLECTING]: '收集中',
+  [FormStatus.STOPPED]: '已停止',
+};
+
+/**
+ * push 文档 / 表格分享权限。
+ *
+ * 0-关闭分享，1-开启分享（仅可查看）。
+ */
+export enum SharePerm {
+  CLOSED = 0,
+  VIEW = 1,
+}
+
+/**
+ * push 文档 / 表格打开分享页是否需要登录。
+ *
+ * 0-免登录，1-需登录。
+ */
+export enum ShareLogin {
+  ANONYMOUS = 0,
+  REQUIRED = 1,
+};
+
 /**
  * PushPlus 接口业务返回码语义。
  *

package/src/index.ts

@@ -25,6 +25,10 @@ export {
   CallbackEvent,
   WebhookType,
   WebhookTypeDescription,
+  FormStatus,
+  FormStatusDescription,
+  SharePerm,
+  ShareLogin,
   ErrorCode,
   errorCodeFromValue,
   isRateLimitedCode,
@@ -58,6 +62,7 @@ export type {
   FriendInfo,
   AccessKeyResult,
   UserInfo,
+  VipInfo,
   SendCount,
   UserLimitTime,
   MessageItem,
@@ -95,6 +100,23 @@ export type {
   ImageUploadToken,
   ImageUploadResult,
   ImageItem,
+  FormListQuery,
+  FormCover,
+  FormTheme,
+  FormSettings,
+  FormItem,
+  FormListItem,
+  FormSaveRequest,
+  FormDetail,
+  FormPublishDiff,
+  FormPublishResult,
+  DocListQuery,
+  DocListItem,
+  DocVo,
+  DocContent,
+  ExcelVo,
+  ExcelContent,
+  ExcelWriteCellsRequest,
 } from './models';
 
 export {
@@ -125,3 +147,6 @@ export {
   type ImageFileInput,
   type ImageUploadOptions,
 } from './api/image-api';
+export { FormApi } from './api/form-api';
+export { DocApi } from './api/doc-api';
+export { ExcelApi } from './api/excel-api';

package/src/models.ts

@@ -56,7 +56,7 @@ export interface SendRequest {
   to?: string;
   /** 预处理编码（仅会员）。 */
   pre?: string;
-  /** push 表单编码；template 为 form 时必传。 */
+  /** push 编码；template 为 form/doc/excel 时必传。 */
   pushId?: string;
 }
 
@@ -107,7 +107,7 @@ export interface BatchSendRequest {
   timestamp?: number;
   to?: string;
   pre?: string;
-  /** push 表单编码；template 为 form 时必传。 */
+  /** push 编码；template 为 form/doc/excel 时必传。 */
   pushId?: string;
 }
 
@@ -239,6 +239,14 @@ export interface AccessKeyResult {
 
 /* ============================== 开放接口 - user ============================== */
 
+/** 会员信息。 */
+export interface VipInfo {
+  /** 是否会员；0-否，1-是。 */
+  isVip?: number;
+  /** 会员到期日。 */
+  lastDay?: string;
+}
+
 export interface UserInfo {
   openId?: string;
   unionId?: string;
@@ -251,6 +259,10 @@ export interface UserInfo {
   emailStatus?: number;
   birthday?: string;
   points?: number;
+  /** 会员信息。 */
+  vipInfo?: VipInfo;
+  /** 实名认证状态；0-未实名，1-已实名。 */
+  verifyStatus?: number;
 }
 
 export interface SendCount {
@@ -646,3 +658,185 @@ export interface ImageItem {
   /** 创建时间。 */
   createTime?: string;
 }
+
+/* ============================== 开放接口 - form（push 表单） ============================== */
+
+/** 我的表单分页查询。 */
+export interface FormListQuery {
+  /** 页码，从 1 开始。 */
+  pageNum?: number;
+  /** 每页条数。 */
+  pageSize?: number;
+  /** 按标题关键词搜索。 */
+  keyword?: string;
+  /** 表单状态：0草稿 / 1收集中 / 2已停止。 */
+  status?: number;
+}
+
+/** 表单封面页配置。 */
+export interface FormCover {
+  enabled?: boolean;
+  image?: string;
+  buttonText?: string;
+}
+
+/** 表单主题外观。 */
+export interface FormTheme {
+  primaryColor?: string;
+  backgroundColor?: string;
+  headerImage?: string;
+  backgroundImage?: string;
+  cover?: FormCover;
+}
+
+/** 表单收集 / 展示设置。 */
+export interface FormSettings {
+  endTime?: string | null;
+  maxResponses?: number | null;
+  oncePerUser?: boolean;
+  allowAnonymous?: boolean;
+  password?: string;
+  showQuestionNumber?: boolean;
+  onePerPage?: boolean;
+  showPrevButton?: boolean;
+  hideTitle?: boolean;
+  hideCopyright?: boolean;
+  hideAd?: boolean;
+  showOutline?: boolean;
+  thankText?: string;
+  redirectEnabled?: boolean;
+  redirectUrl?: string;
+  allowEdit?: boolean;
+}
+
+/**
+ * 表单题目。不同题型字段不同，除常用字段外可携带任意扩展属性。
+ *
+ * type 常用取值：input / textarea / radio / checkbox / select / number / date / rate 等。
+ */
+export interface FormItem {
+  id?: string;
+  type?: string;
+  alias?: string;
+  label?: string;
+  description?: string;
+  required?: boolean;
+  placeholder?: string;
+  options?: unknown[];
+  rows?: unknown[];
+  columns?: unknown[];
+  allowOther?: boolean;
+  [key: string]: unknown;
+}
+
+/** 表单列表项 / 创建、复制结果（不含题目明细）。 */
+export interface FormListItem {
+  id?: number;
+  formCode?: string;
+  fillUrl?: string;
+  title?: string;
+  description?: string;
+  status?: number;
+  responseCount?: number;
+  publishTime?: string;
+  createTime?: string;
+  updateTime?: string;
+}
+
+/** 保存表单设计请求。 */
+export interface FormSaveRequest {
+  id: number;
+  title: string;
+  description?: string;
+  items?: FormItem[];
+  theme?: FormTheme;
+  settings?: FormSettings;
+}
+
+/** 表单详情（含草稿题目、主题、设置）。 */
+export interface FormDetail extends FormListItem {
+  items?: FormItem[];
+  theme?: FormTheme;
+  settings?: FormSettings;
+  publishDirty?: boolean;
+}
+
+/** 草稿题目与发布快照差异。 */
+export interface FormPublishDiff {
+  dirty?: boolean;
+  breaking?: boolean;
+  responseCount?: number;
+  added?: string[];
+  removed?: string[];
+  typeChanged?: string[];
+  optionChanged?: string[];
+}
+
+/** 发布表单结果。 */
+export interface FormPublishResult {
+  id?: number;
+  formCode?: string;
+  fillUrl?: string;
+  title?: string;
+  status?: number;
+  previousStatus?: number;
+  publishDirty?: boolean;
+  publishTime?: string;
+}
+
+/* ============================== 开放接口 - doc / excel 共用查询 ============================== */
+
+/** 文档 / 表格分页查询。 */
+export interface DocListQuery {
+  pageNum?: number;
+  pageSize?: number;
+  keyword?: string;
+  /** true 时仅返回已开启分享的记录。 */
+  shareEnabled?: boolean;
+}
+
+/** 文档 / 表格列表项。 */
+export interface DocListItem {
+  docCode?: string;
+  shareUrl?: string;
+  title?: string;
+  sharePerm?: number;
+  shareLogin?: number;
+  perm?: number;
+  published?: boolean;
+  publishTime?: string;
+  createTime?: string;
+  updateTime?: string;
+}
+
+/** 文档信息（不含正文）。 */
+export interface DocVo extends DocListItem {
+  publishDirty?: boolean;
+}
+
+/** 文档内容（HTML 草稿）。 */
+export interface DocContent extends DocVo {
+  content?: string;
+}
+
+/** 表格信息（不含正文）。与文档结构相同，独立类型便于区分。 */
+export interface ExcelVo extends DocListItem {
+  publishDirty?: boolean;
+}
+
+/** 表格内容（整表 JSON 字符串草稿）。 */
+export interface ExcelContent extends ExcelVo {
+  /** 整表草稿 JSON 字符串。 */
+  content?: string;
+}
+
+/** 按区域写入单元格请求。 */
+export interface ExcelWriteCellsRequest {
+  docCode: string;
+  /** 工作表名称；不传则写入活动表 / 第一张表。 */
+  sheetName?: string;
+  /** 起始单元格，如 A1。 */
+  range: string;
+  /** 二维数组，外层为行、内层为列。 */
+  values: unknown[][];
+}