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

package/dist/index.d.cts

@@ -227,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 接口业务返回码语义。
  *
@@ -616,6 +645,18 @@ interface TopicUserListQuery {
     /** 例如 { topicId }。 */
     params?: Record<string, unknown>;
 }
+/** 群组订阅人黑名单列表项。 */
+interface TopicUserBlacklistItem {
+    /** 黑名单记录 ID；解除黑名单时使用。 */
+    id?: number;
+    /** 被拉黑用户 ID。 */
+    userId?: number;
+    nickName?: string;
+    openId?: string;
+    headImgUrl?: string;
+    /** 拉黑时间。 */
+    createTime?: string;
+}
 interface WebhookItem {
     id?: number;
     webhookCode?: string;
@@ -656,6 +697,17 @@ interface FriendItem {
 interface FriendQrCode {
     qrCodeImgUrl?: string;
 }
+/** 好友黑名单列表项。 */
+interface FriendBlacklistItem {
+    /** 黑名单记录 ID；解除黑名单时使用。 */
+    id?: number;
+    /** 被拉黑好友 ID。 */
+    friendId?: number;
+    nickName?: string;
+    headImgUrl?: string;
+    /** 拉黑时间。 */
+    createTime?: string;
+}
 interface ClawBotInfo {
     createTime?: string;
     /** 是否有对话令牌（文档为字符串/数字混用，统一用 number 兼容）。 */
@@ -814,6 +866,175 @@ interface ImageItem {
     /** 创建时间。 */
     createTime?: string;
 }
+/** 我的表单分页查询。官方结构为 `{current, pageSize, params:{keyword, status}}`。 */
+interface FormListQuery {
+    /** 当前所在分页数，默认 1。 */
+    current?: number;
+    /** 每页大小，默认 20，最大 50。 */
+    pageSize?: number;
+    params?: {
+        /** 按标题关键词搜索。 */
+        keyword?: string;
+        /** 表单状态：0草稿 / 1收集中 / 2已停止。 */
+        status?: number;
+        [key: string]: unknown;
+    };
+}
+/** 表单封面页配置。 */
+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;
+}
+/** 文档 / 表格分页查询。官方结构为 `{current, pageSize, params:{keyword, shareEnabled}}`。 */
+interface DocListQuery {
+    /** 当前所在分页数，默认 1。 */
+    current?: number;
+    /** 每页大小，默认 20，最大 50。 */
+    pageSize?: number;
+    params?: {
+        keyword?: string;
+        /** true 时仅返回已开启分享的记录。 */
+        shareEnabled?: boolean;
+        [key: string]: unknown;
+    };
+}
+/** 文档 / 表格列表项。 */
+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 基类，提供请求执行与统一错误处理。
@@ -832,6 +1053,11 @@ declare abstract class AbstractApi {
      * 执行请求并返回原始 ApiResponse（不进行 code 校验）。
      */
     protected execute<T>(method: string, path: string, headers: Record<string, string> | undefined | null, body: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 执行带二进制请求体的请求并返回原始 ApiResponse（不进行 code 校验）。
+     * 用于 multipart 上传等场景。
+     */
+    protected executeRaw<T>(method: string, path: string, headers: Record<string, string> | undefined | null, body: Uint8Array): Promise<ApiResponse<T>>;
     /** 执行请求并直接返回 data；非 200 抛出异常。 */
     protected executeForData<T>(method: string, path: string, headers: Record<string, string> | undefined | null, body: unknown): Promise<T>;
 }
@@ -876,6 +1102,13 @@ declare class AccessKeyManager {
     private isValid;
 }
 
+/** 二进制文件输入。 */
+type FileInput = Uint8Array | ArrayBuffer | Blob;
+interface FileMultipart {
+    contentType: string;
+    body: Uint8Array;
+}
+
 /**
  * 开放接口基类。会自动在 header 中带上 access-key，
  * 并在收到 401 类业务错误时尝试重试一次（刷新 AccessKey 后重试）。
@@ -891,6 +1124,12 @@ declare abstract class OpenAbstractApi extends AbstractApi {
      * 执行带 access-key 的请求；当返回 code=401 时自动刷新 key 并重试一次。
      */
     protected executeOpen<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** 以 multipart 上传文件（自动携带 access-key；code=401 时刷新后重试一次）。 */
+    protected executeOpenMultipart<T>(path: string, multipart: FileMultipart): Promise<T>;
+    /**
+     * 执行带二进制 body 的开放接口请求；当返回 code=401 时自动刷新 key 并重试一次。
+     */
+    protected executeOpenRaw<T>(method: string, path: string, body: Uint8Array, extraHeaders?: Record<string, string>): Promise<T>;
 }
 
 /**
@@ -925,6 +1164,129 @@ declare class ClawBotApi extends OpenAbstractApi {
     getMsg(): Promise<ClawBotMessage[]>;
 }
 
+/**
+ * 开放接口 - push 文档。
+ *
+ * 文档：https://www.pushplus.plus/doc/ecosystem/doc/
+ * 基础路径：`/push/api/open/doc`
+ *
+ * 文档开放接口不单独提供推送接口。发布后请通过 `client.send` 推送分享页：
+ * `template=doc`，`pushId=docCode`。
+ */
+declare class DocApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 我的文档分页。 */
+    list(query?: DocListQuery): Promise<PageResult<DocListItem>>;
+    /** 创建空白文档。 */
+    create(title: string): Promise<DocVo>;
+    /**
+     * 导入 Word（.docx）创建文档。
+     *
+     * 标题默认取文件名；创建后默认关闭分享，需再调用 publish 才会同步到分享页。
+     */
+    importWord(file: FileInput, fileName?: 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`
+ *
+ * 表格开放接口不单独提供推送接口。发布后请通过 `client.send` 推送分享页：
+ * `template=excel`，`pushId=docCode`。
+ */
+declare class ExcelApi extends OpenAbstractApi {
+    constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager);
+    /** 我的表格分页。 */
+    list(query?: DocListQuery): Promise<PageResult<DocListItem>>;
+    /** 创建空白表格。 */
+    create(title: string): Promise<ExcelVo>;
+    /**
+     * 导入 Excel（.xlsx / .xls）创建表格。
+     *
+     * 标题默认取文件名；创建后默认关闭分享，需再调用 publish 才会同步到分享页。
+     */
+    importExcel(file: FileInput, fileName?: 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`
+ *
+ * 表单开放接口不单独提供推送接口。发布后请通过 `client.send` 推送填写页：
+ * `template=form`，`pushId=formCode`。
+ */
+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>;
+}
+
 /**
  * 开放接口 - 好友功能（文档「十. 好友功能接口」）。
  */
@@ -943,6 +1305,24 @@ declare class FriendApi extends OpenAbstractApi {
     delete(friendId: number): Promise<void>;
     /** 4. 修改好友备注。 */
     editRemark(id: number, remark: string): Promise<void>;
+    /**
+     * 5. 将好友加入黑名单。
+     *
+     * 加入后将解除双方好友关系，对方无法再添加你。不能将自己加入黑名单，仅可将已有好友加入黑名单。
+     *
+     * @param friendId 好友 id（好友列表中的 friendId 字段）
+     */
+    addBlacklist(friendId: number): Promise<void>;
+    /** 6. 好友黑名单列表。 */
+    blacklistList(query?: PageQuery): Promise<PageResult<FriendBlacklistItem>>;
+    /**
+     * 7. 解除好友黑名单。
+     *
+     * 解除后不会自动恢复好友关系，需重新扫码添加。
+     *
+     * @param id 黑名单记录 ID（黑名单列表中的 id 字段）
+     */
+    removeBlacklist(id: number): Promise<void>;
 }
 
 /**
@@ -1212,6 +1592,28 @@ declare class TopicUserApi extends OpenAbstractApi {
     deleteUser(topicRelationId: number): Promise<string>;
     /** 3. 修改订阅人备注。 */
     editRemark(id: number, remark: string): Promise<void>;
+    /**
+     * 4. 将订阅人加入黑名单。
+     *
+     * 加入后将移出群组，对方无法再加入该群组。积分群组不支持黑名单。不能将自己加入黑名单。
+     *
+     * @param topicRelationId 用户编号（订阅人列表中的 id 字段）
+     */
+    addBlacklist(topicRelationId: number): Promise<void>;
+    /**
+     * 5. 订阅人黑名单列表。
+     *
+     * `query.params.topicId` 必填。
+     */
+    blacklistList(query: TopicUserListQuery): Promise<PageResult<TopicUserBlacklistItem>>;
+    /**
+     * 6. 解除订阅人黑名单。
+     *
+     * 解除后不会自动恢复群组订阅，对方可重新加入该群组。
+     *
+     * @param id 黑名单记录 ID（黑名单列表中的 id 字段）
+     */
+    removeBlacklist(id: number): Promise<void>;
 }
 
 /**
@@ -1286,6 +1688,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;
@@ -1376,4 +1781,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, type VipInfo, 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, type FileInput, 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 FriendBlacklistItem, 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 TopicUserBlacklistItem, 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 };