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

package/dist/index.d.cts

@@ -178,7 +178,11 @@ declare enum Template {
     /** 支付成功通知模板。 */
     PAY = "pay",
     /** 表单格式模板；发送时需传 pushId（表单编码）。 */
-    FORM = "form"
+    FORM = "form",
+    /** 文档格式模板（push 文档）；发送时需传 pushId。 */
+    DOC = "doc",
+    /** 表格格式模板（push 表格）；发送时需传 pushId。 */
+    EXCEL = "excel"
 }
 /**
  * 消息投递状态。
@@ -223,6 +227,35 @@ declare enum WebhookType {
     CUSTOM = 12
 }
 declare const WebhookTypeDescription: Record<number, string>;
+/**
+ * push 表单状态。
+ *
+ * 0-草稿，1-收集中，2-已停止。
+ */
+declare enum FormStatus {
+    DRAFT = 0,
+    COLLECTING = 1,
+    STOPPED = 2
+}
+declare const FormStatusDescription: Record<FormStatus, string>;
+/**
+ * push 文档 / 表格分享权限。
+ *
+ * 0-关闭分享，1-开启分享（仅可查看）。
+ */
+declare enum SharePerm {
+    CLOSED = 0,
+    VIEW = 1
+}
+/**
+ * push 文档 / 表格打开分享页是否需要登录。
+ *
+ * 0-免登录，1-需登录。
+ */
+declare enum ShareLogin {
+    ANONYMOUS = 0,
+    REQUIRED = 1
+}
 /**
  * PushPlus 接口业务返回码语义。
  *
@@ -310,7 +343,7 @@ interface SendRequest {
     to?: string;
     /** 预处理编码（仅会员）。 */
     pre?: string;
-    /** push 表单编码；template 为 form 时必传。 */
+    /** push 编码；template 为 form/doc/excel 时必传。 */
     pushId?: string;
 }
 declare class SendRequestBuilder {
@@ -350,7 +383,7 @@ interface BatchSendRequest {
     timestamp?: number;
     to?: string;
     pre?: string;
-    /** push 表单编码；template 为 form 时必传。 */
+    /** push 编码；template 为 form/doc/excel 时必传。 */
     pushId?: string;
 }
 /**
@@ -449,6 +482,13 @@ interface AccessKeyResult {
     /** 过期时间（单位秒）。 */
     expiresIn?: number;
 }
+/** 会员信息。 */
+interface VipInfo {
+    /** 是否会员；0-否，1-是。 */
+    isVip?: number;
+    /** 会员到期日。 */
+    lastDay?: string;
+}
 interface UserInfo {
     openId?: string;
     unionId?: string;
@@ -461,6 +501,10 @@ interface UserInfo {
     emailStatus?: number;
     birthday?: string;
     points?: number;
+    /** 会员信息。 */
+    vipInfo?: VipInfo;
+    /** 实名认证状态；0-未实名，1-已实名。 */
+    verifyStatus?: number;
 }
 interface SendCount {
     wechatSendCount?: number;
@@ -799,6 +843,167 @@ interface ImageItem {
     /** 创建时间。 */
     createTime?: string;
 }
+/** 我的表单分页查询。 */
+interface FormListQuery {
+    /** 页码，从 1 开始。 */
+    pageNum?: number;
+    /** 每页条数。 */
+    pageSize?: number;
+    /** 按标题关键词搜索。 */
+    keyword?: string;
+    /** 表单状态：0草稿 / 1收集中 / 2已停止。 */
+    status?: number;
+}
+/** 表单封面页配置。 */
+interface FormCover {
+    enabled?: boolean;
+    image?: string;
+    buttonText?: string;
+}
+/** 表单主题外观。 */
+interface FormTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    headerImage?: string;
+    backgroundImage?: string;
+    cover?: FormCover;
+}
+/** 表单收集 / 展示设置。 */
+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 等。
+ */
+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;
+}
+/** 表单列表项 / 创建、复制结果（不含题目明细）。 */
+interface FormListItem {
+    id?: number;
+    formCode?: string;
+    fillUrl?: string;
+    title?: string;
+    description?: string;
+    status?: number;
+    responseCount?: number;
+    publishTime?: string;
+    createTime?: string;
+    updateTime?: string;
+}
+/** 保存表单设计请求。 */
+interface FormSaveRequest {
+    id: number;
+    title: string;
+    description?: string;
+    items?: FormItem[];
+    theme?: FormTheme;
+    settings?: FormSettings;
+}
+/** 表单详情（含草稿题目、主题、设置）。 */
+interface FormDetail extends FormListItem {
+    items?: FormItem[];
+    theme?: FormTheme;
+    settings?: FormSettings;
+    publishDirty?: boolean;
+}
+/** 草稿题目与发布快照差异。 */
+interface FormPublishDiff {
+    dirty?: boolean;
+    breaking?: boolean;
+    responseCount?: number;
+    added?: string[];
+    removed?: string[];
+    typeChanged?: string[];
+    optionChanged?: string[];
+}
+/** 发布表单结果。 */
+interface FormPublishResult {
+    id?: number;
+    formCode?: string;
+    fillUrl?: string;
+    title?: string;
+    status?: number;
+    previousStatus?: number;
+    publishDirty?: boolean;
+    publishTime?: string;
+}
+/** 文档 / 表格分页查询。 */
+interface DocListQuery {
+    pageNum?: number;
+    pageSize?: number;
+    keyword?: string;
+    /** true 时仅返回已开启分享的记录。 */
+    shareEnabled?: boolean;
+}
+/** 文档 / 表格列表项。 */
+interface DocListItem {
+    docCode?: string;
+    shareUrl?: string;
+    title?: string;
+    sharePerm?: number;
+    shareLogin?: number;
+    perm?: number;
+    published?: boolean;
+    publishTime?: string;
+    createTime?: string;
+    updateTime?: string;
+}
+/** 文档信息（不含正文）。 */
+interface DocVo extends DocListItem {
+    publishDirty?: boolean;
+}
+/** 文档内容（HTML 草稿）。 */
+interface DocContent extends DocVo {
+    content?: string;
+}
+/** 表格信息（不含正文）。与文档结构相同，独立类型便于区分。 */
+interface ExcelVo extends DocListItem {
+    publishDirty?: boolean;
+}
+/** 表格内容（整表 JSON 字符串草稿）。 */
+interface ExcelContent extends ExcelVo {
+    /** 整表草稿 JSON 字符串。 */
+    content?: string;
+}
+/** 按区域写入单元格请求。 */
+interface ExcelWriteCellsRequest {
+    docCode: string;
+    /** 工作表名称；不传则写入活动表 / 第一张表。 */
+    sheetName?: string;
+    /** 起始单元格，如 A1。 */
+    range: string;
+    /** 二维数组，外层为行、内层为列。 */
+    values: unknown[][];
+}
 
 /**
  * API 基类，提供请求执行与统一错误处理。
@@ -910,6 +1115,108 @@ declare class ClawBotApi extends OpenAbstractApi {
     getMsg(): Promise<ClawBotMessage[]>;
 }
 
+/**
+ * 开放接口 - push 文档。
+ *
+ * 文档：https://www.pushplus.plus/doc/ecosystem/doc/
+ * 基础路径：`/push/api/open/doc`
+ */
+declare class DocApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 我的文档分页。 */
+    list(query?: DocListQuery): Promise<PageResult<DocListItem>>;
+    /** 创建空白文档。 */
+    create(title: string): Promise<DocVo>;
+    /** 获取文档元信息与 HTML 草稿正文。 */
+    content(docCode: string): Promise<DocContent>;
+    /** 保存 HTML 草稿（不影响分享页，需再 publish）。 */
+    saveContent(docCode: string, content: string): Promise<DocVo>;
+    /** 将草稿同步为分享页快照。 */
+    publish(docCode: string): Promise<DocVo>;
+    /** 重命名。 */
+    rename(docCode: string, title: string): Promise<void>;
+    /** 删除文档。 */
+    delete(docCode: string): Promise<void>;
+    /**
+     * 更新分享设置。
+     *
+     * @param sharePerm 0 关闭 / 1 开启（仅可查看）
+     * @param shareLogin 0 免登录 / 1 需登录；不传则沿用原值
+     */
+    updateShare(docCode: string, sharePerm: number, shareLogin?: number): Promise<DocVo>;
+}
+
+/**
+ * 开放接口 - push 表格。
+ *
+ * 文档：https://www.pushplus.plus/doc/ecosystem/sheet/
+ * 基础路径：`/push/api/open/excel`
+ */
+declare class ExcelApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 我的表格分页。 */
+    list(query?: DocListQuery): Promise<PageResult<DocListItem>>;
+    /** 创建空白表格。 */
+    create(title: string): Promise<ExcelVo>;
+    /** 获取表格元信息与整表 JSON 草稿。 */
+    content(docCode: string): Promise<ExcelContent>;
+    /**
+     * 整表覆盖保存草稿。
+     *
+     * `content` 可为 JSON 字符串，或工作簿对象（SDK 会序列化）。
+     */
+    saveContent(docCode: string, content: string | object): Promise<ExcelVo>;
+    /**
+     * 从指定起始单元格起，按二维数组向右向下写入（草稿）。
+     *
+     * @param range 起始单元格，如 A1
+     * @param values 外层为行、内层为列
+     * @param sheetName 工作表名称；不传则写入活动表 / 第一张表
+     */
+    writeCells(docCode: string, range: string, values: unknown[][], sheetName?: string): Promise<ExcelVo>;
+    /** 将草稿同步为分享页快照。 */
+    publish(docCode: string): Promise<ExcelVo>;
+    /** 重命名。 */
+    rename(docCode: string, title: string): Promise<void>;
+    /** 删除表格。 */
+    delete(docCode: string): Promise<void>;
+    /**
+     * 更新分享设置。
+     *
+     * @param sharePerm 0 关闭 / 1 开启（仅可查看）
+     * @param shareLogin 0 免登录 / 1 需登录；不传则沿用原值
+     */
+    updateShare(docCode: string, sharePerm: number, shareLogin?: number): Promise<ExcelVo>;
+}
+
+/**
+ * 开放接口 - push 表单。
+ *
+ * 文档：https://www.pushplus.plus/doc/ecosystem/form/
+ * 基础路径：`/push/api/open/form`
+ */
+declare class FormApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 我的表单分页。 */
+    list(query?: FormListQuery): Promise<PageResult<FormListItem>>;
+    /** 创建空白表单（草稿）。 */
+    create(title: string): Promise<FormListItem>;
+    /** 基于已有表单复制一份新草稿。 */
+    copy(id: number): Promise<FormListItem>;
+    /** 保存表单设计（仅更新草稿；已发布需再调用 publish）。 */
+    save(req: FormSaveRequest): Promise<void>;
+    /** 表单详情（含草稿题目、主题、设置）。 */
+    detail(id: number): Promise<FormDetail>;
+    /** 草稿与发布快照的题目差异。 */
+    publishDiff(id: number): Promise<FormPublishDiff>;
+    /** 发布表单，开始收集。 */
+    publish(id: number): Promise<FormPublishResult>;
+    /** 停止收集。 */
+    stop(id: number): Promise<void>;
+    /** 删除表单（不可恢复）。 */
+    delete(id: number): Promise<void>;
+}
+
 /**
  * 开放接口 - 好友功能（文档「十. 好友功能接口」）。
  */
@@ -1271,6 +1578,9 @@ declare class PushPlusClient {
     readonly setting: SettingApi;
     readonly pre: PreApi;
     readonly image: ImageApi;
+    readonly form: FormApi;
+    readonly doc: DocApi;
+    readonly excel: ExcelApi;
     constructor(options?: PushPlusClientOptions);
     /** 与 Java SDK 风格一致的 Builder 入口。 */
     static builder(): PushPlusClientBuilder;
@@ -1361,4 +1671,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, ErrorCode, FetchHttpRequester, 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, 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, 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, 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 };