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

package/README.md

@@ -5,6 +5,7 @@
 - **同时支持 Node.js 与浏览器**：Node.js 18+ 使用内置 `fetch`，浏览器使用原生 `fetch`，无运行时依赖。
 - **三种产物**：CommonJS (`.cjs`) + ESModule (`.js`) + 浏览器 IIFE (`.global.js`)，可通过 npm / `<script>` 直接加载。
 - **完整 TypeScript 类型**：所有请求 / 响应 / 枚举 / 回调全部带类型声明。
+- **全部开放接口**：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理、图片服务（含一键上传到 PushPlus 图床）。
 - **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
 - **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
 - **Builder 链式 API**：与 Java/Python SDK 风格保持一致。
@@ -85,6 +86,16 @@ await client.send({
   content: 'v1.0.0',
   template: Template.MARKDOWN,
 });
+
+// push 表单：template=form 时需传 pushId（表单编码）
+await client.send(
+  sendRequest()
+    .title('表单通知')
+    .content('您有新的表单待填写')
+    .template(Template.FORM)
+    .pushId('表单编码')
+    .build(),
+);
 ```
 
 ### 3. 多渠道发送
@@ -163,8 +174,49 @@ await client.setting.changeOpenMessageType(0);
 
 // 预处理（仅会员）
 const out = await client.pre.test({ content: '...', message: 'hi' });
+
+// 图片服务（一行上传到 PushPlus 图床，30 天有效）
+import { readFile } from 'node:fs/promises';
+const bytes = await readFile('/tmp/logo.png');
+const uploaded = await client.image.uploadBytes(bytes, { fileName: 'logo.png' });
+console.log(uploaded.url);                       // 直接拿到可访问的图片 URL
+const imgs = await client.image.list({ current: 1, pageSize: 10 });
+await client.image.delete(imgs.list[0].id);
+```
+
+### 图片服务
+
+PushPlus 基于七牛云提供图片图床（30 天有效，可主动删除）。SDK 把「获取上传凭证 → multipart 表单上传 → 解析 URL」封装成一步：
+
+```ts
+// Node.js：从文件读取
+import { readFile } from 'node:fs/promises';
+const bytes = await readFile('/tmp/a.png');
+const r = await client.image.uploadBytes(bytes, { fileName: 'a.png' });
+console.log(r.url);
+
+// 浏览器：input[type=file]
+const file = (document.querySelector('input[type=file]') as HTMLInputElement).files![0];
+await client.image.uploadBytes(file, { fileName: file.name, contentType: file.type });
+
+// 已上传图片列表
+const page = await client.image.list({ current: 1, pageSize: 10 });
+
+// 主动删除（未删除的图片默认 30 天后由系统自动清理）
+await client.image.delete(page.list![0].id!);
 ```
 
+需要自己控制凭证的获取与上传过程时（如缓存 token、分布式上传），可拆开调用：
+
+```ts
+const token = await client.image.getUploadToken();
+const r = await client.image.upload(token, bytes, { fileName: 'a.png', contentType: 'image/png' });
+```
+
+> 上传图片的真正请求会按七牛云规范以 `multipart/form-data` 提交到 `uploadUrl`，**不会**携带 PushPlus 的 `access-key`；其余三个接口（获取凭证 / 列表 / 删除）走 PushPlus 开放接口，自动带上 `access-key`。
+>
+> 接受的二进制形态：`Uint8Array`（Node 中 `Buffer` 是其子类，可直接传）、`ArrayBuffer`、`Blob`/`File`（浏览器 + Node 18+）。
+
 ### 5. 回调解析
 
 PushPlus 在消息发送完成、群组新增用户、新增好友时会回调你预置的 URL。SDK 提供类型安全的解析：

package/dist/index.cjs

@@ -22,6 +22,7 @@ var Template = /* @__PURE__ */ ((Template2) => {
   Template2["JENKINS"] = "jenkins";
   Template2["ROUTE"] = "route";
   Template2["PAY"] = "pay";
+  Template2["FORM"] = "form";
   return Template2;
 })(Template || {});
 var SendStatus = /* @__PURE__ */ ((SendStatus2) => {
@@ -185,6 +186,25 @@ var AccessKeyManager = class {
 };
 
 // src/http.ts
+async function callExecuteRaw(requester, options) {
+  if (typeof requester.executeRaw === "function") {
+    return requester.executeRaw(options);
+  }
+  const { method, url, headers, body } = options;
+  let text = null;
+  if (body != null) {
+    if (typeof Blob !== "undefined" && body instanceof Blob) {
+      text = await body.text();
+    } else if (body instanceof Uint8Array) {
+      text = new TextDecoder("utf-8").decode(body);
+    } else if (body instanceof ArrayBuffer) {
+      text = new TextDecoder("utf-8").decode(new Uint8Array(body));
+    } else {
+      text = String(body);
+    }
+  }
+  return requester.execute({ method, url, headers, body: text });
+}
 var FetchHttpRequester = class {
   constructor(config, fetchImpl) {
     this.readTimeoutMs = config.readTimeoutMs;
@@ -200,7 +220,29 @@ var FetchHttpRequester = class {
   }
   async execute(options) {
     var _a, _b;
-    const { method, url, headers, body } = options;
+    return this.doExecute({
+      method: options.method,
+      url: options.url,
+      headers: options.headers,
+      body: (_a = options.body) != null ? _a : null,
+      bodyForLog: (_b = options.body) != null ? _b : null,
+      defaultContentType: "application/json;charset=UTF-8"
+    });
+  }
+  async executeRaw(options) {
+    var _a;
+    return this.doExecute({
+      method: options.method,
+      url: options.url,
+      headers: options.headers,
+      body: (_a = options.body) != null ? _a : null,
+      bodyForLog: null,
+      defaultContentType: "application/octet-stream"
+    });
+  }
+  async doExecute(args) {
+    var _a, _b;
+    const { method, url, headers, body, bodyForLog, defaultContentType } = args;
     const finalHeaders = {};
     let hasContentType = false;
     if (headers) {
@@ -210,14 +252,19 @@ var FetchHttpRequester = class {
         if (k.toLowerCase() === "content-type") hasContentType = true;
       }
     }
-    if (body != null && !hasContentType) {
-      finalHeaders["Content-Type"] = "application/json;charset=UTF-8";
+    if (body != null && !hasContentType && defaultContentType) {
+      finalHeaders["Content-Type"] = defaultContentType;
     }
     if (typeof window === "undefined" && !finalHeaders["User-Agent"] && !finalHeaders["user-agent"]) {
       finalHeaders["User-Agent"] = this.userAgent;
     }
     if (this.logRequest) {
-      console.debug("[pushplus] >>>", method, url, "body=", body);
+      if (bodyForLog != null) {
+        console.debug("[pushplus] >>>", method, url, "body=", bodyForLog);
+      } else {
+        const len = bodyLength(body);
+        console.debug("[pushplus] >>>", method, url, "bodyBytes=", len);
+      }
     }
     const controller = new AbortController();
     const timer = this.readTimeoutMs > 0 ? setTimeout(() => controller.abort(), this.readTimeoutMs) : null;
@@ -249,6 +296,14 @@ var FetchHttpRequester = class {
     }
   }
 };
+function bodyLength(body) {
+  if (body == null) return 0;
+  if (typeof body === "string") return body.length;
+  if (body instanceof Uint8Array) return body.byteLength;
+  if (body instanceof ArrayBuffer) return body.byteLength;
+  if (typeof Blob !== "undefined" && body instanceof Blob) return body.size;
+  return -1;
+}
 function isSuccessfulHttpStatus(status) {
   return status >= 200 && status < 300;
 }
@@ -520,6 +575,168 @@ var FriendApi = class extends OpenAbstractApi {
   }
 };
 
+// src/api/image-api.ts
+var ImageApi = class extends OpenAbstractApi {
+  constructor(config, http, mgr) {
+    super(config, http, mgr);
+  }
+  /** 1. 获取上传凭证。 */
+  getUploadToken() {
+    return this.executeOpen("GET", "/api/open/userImage/uploadToken");
+  }
+  /**
+   * 2. 上传图片到七牛云。
+   *
+   * 使用「获取上传凭证」返回的 `uploadUrl` 与 `uploadToken`，
+   * 按七牛云表单上传规范以 `multipart/form-data` 提交。该请求
+   * **不会** 携带 PushPlus 的 `access-key` 头。
+   */
+  async upload(token, file, options) {
+    if (token == null) {
+      throw new PushPlusError("\u4E0A\u4F20\u51ED\u8BC1 token \u4E0D\u80FD\u4E3A null");
+    }
+    if (!token.uploadToken) {
+      throw new PushPlusError("\u4E0A\u4F20\u51ED\u8BC1 uploadToken \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    const uploadUrl = token.uploadUrl || token.uploadHost;
+    if (!uploadUrl) {
+      throw new PushPlusError("\u4E0A\u4F20\u51ED\u8BC1\u672A\u8FD4\u56DE uploadUrl/uploadHost");
+    }
+    return this.uploadToQiniu(uploadUrl, token.uploadToken, file, options);
+  }
+  /**
+   * 2. 上传图片到七牛云（低层方法）。直接指定上传地址与 token。
+   */
+  async uploadToQiniu(uploadUrl, uploadToken, file, options) {
+    var _a, _b;
+    if (!uploadUrl) {
+      throw new PushPlusError("uploadUrl \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!uploadToken) {
+      throw new PushPlusError("uploadToken \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    const bytes = await toUint8Array(file);
+    if (bytes.byteLength === 0) {
+      throw new PushPlusError("\u4E0A\u4F20\u6587\u4EF6\u5185\u5BB9\u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    const fileName = options.fileName || "file";
+    const contentType = options.contentType || guessContentTypeByName(fileName) || "application/octet-stream";
+    const boundary = "----PushPlusBoundary" + randomBoundarySuffix();
+    const body = buildMultipartBody(boundary, uploadToken, fileName, contentType, bytes);
+    const resp = await callExecuteRaw(this.http, {
+      method: "POST",
+      url: uploadUrl,
+      headers: { "Content-Type": `multipart/form-data; boundary=${boundary}` },
+      body
+    });
+    if (!isSuccessfulHttpStatus(resp.statusCode)) {
+      throw new PushPlusError(
+        `\u4E0A\u4F20\u56FE\u7247\u5230\u4E03\u725B\u4E91\u5931\u8D25: status=${resp.statusCode}, body=${resp.body}`,
+        resp.statusCode
+      );
+    }
+    let result;
+    try {
+      result = JSON.parse(resp.body);
+    } catch (e) {
+      throw new PushPlusError(
+        `\u89E3\u6790\u4E03\u725B\u4E91\u54CD\u5E94\u5931\u8D25: ${e.message}, payload=${resp.body}`,
+        -1,
+        { cause: e }
+      );
+    }
+    if (result == null || typeof result !== "object") {
+      throw new PushPlusError(`\u4E03\u725B\u4E91\u8FD4\u56DE\u975E JSON \u5BF9\u8C61: ${resp.body}`);
+    }
+    if (result.errno !== 0) {
+      throw new PushPlusError(
+        `\u4E03\u725B\u4E91\u4E0A\u4F20\u5931\u8D25: errno=${result.errno}, msg=${(_a = result.msg) != null ? _a : ""}`,
+        (_b = result.errno) != null ? _b : -1
+      );
+    }
+    return result;
+  }
+  /**
+   * 便捷方法：自动获取上传凭证后上传字节数组 / Blob / ArrayBuffer。
+   *
+   * @example
+   * ```ts
+   * await client.image.uploadBytes(buffer, { fileName: 'a.png' });
+   * await client.image.uploadBytes(blob, { fileName: 'b.jpg', contentType: 'image/jpeg' });
+   * ```
+   */
+  async uploadBytes(file, options) {
+    const token = await this.getUploadToken();
+    return this.upload(token, file, options);
+  }
+  /** 3. 图片列表。 */
+  list(query) {
+    return this.executeOpen(
+      "POST",
+      "/api/open/userImage/list",
+      query != null ? query : {}
+    );
+  }
+  /**
+   * 4. 主动删除图片；未删除的图片默认 30 天后由系统自动清理。
+   */
+  async delete(id) {
+    await this.executeOpen(
+      "DELETE",
+      this.appendQuery("/api/open/userImage/delete", { id })
+    );
+  }
+};
+async function toUint8Array(file) {
+  if (file == null) {
+    throw new PushPlusError("\u4E0A\u4F20\u6587\u4EF6\u4E0D\u80FD\u4E3A null");
+  }
+  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 buildMultipartBody(boundary, uploadToken, fileName, contentType, fileBytes) {
+  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}`
+  );
+  const tail = enc.encode(`${crlf}--${boundary}--${crlf}`);
+  const out = new Uint8Array(head.byteLength + fileBytes.byteLength + tail.byteLength);
+  out.set(head, 0);
+  out.set(fileBytes, head.byteLength);
+  out.set(tail, head.byteLength + fileBytes.byteLength);
+  return out;
+}
+function escapeFileName(name) {
+  return name.replace(/"/g, "_").replace(/\r/g, " ").replace(/\n/g, " ");
+}
+function guessContentTypeByName(name) {
+  const lower = name.toLowerCase();
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  if (lower.endsWith(".gif")) return "image/gif";
+  if (lower.endsWith(".webp")) return "image/webp";
+  if (lower.endsWith(".bmp")) return "image/bmp";
+  if (lower.endsWith(".svg")) return "image/svg+xml";
+  return null;
+}
+function randomBoundarySuffix() {
+  let s = "";
+  for (let i = 0; i < 32; i++) {
+    s += Math.floor(Math.random() * 16).toString(16);
+  }
+  return s;
+}
+
 // src/api/message-api.ts
 var MessageApi = class extends AbstractApi {
   constructor(config, http, rateLimitGuard) {
@@ -919,7 +1136,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.0.0`
+    userAgent: (_j = cfg.userAgent) != null ? _j : `@perk-net/perk-pushplus-sdk/1.1.0`
   };
 }
 
@@ -1013,6 +1230,7 @@ var PushPlusClient = class _PushPlusClient {
     this.clawBot = new ClawBotApi(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);
   }
   /** 与 Java SDK 风格一致的 Builder 入口。 */
   static builder() {
@@ -1159,6 +1377,10 @@ var SendRequestBuilder = class {
     this.req.pre = v;
     return this;
   }
+  pushId(v) {
+    this.req.pushId = v;
+    return this;
+  }
   build() {
     return { ...this.req };
   }
@@ -1208,6 +1430,10 @@ var BatchSendRequestBuilder = class {
     this.req.pre = v;
     return this;
   }
+  pushId(v) {
+    this.req.pushId = v;
+    return this;
+  }
   /** 追加一个 channel。 */
   channel(ch) {
     this.channelList.push(typeof ch === "string" ? ch : ch);
@@ -1251,6 +1477,7 @@ exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
 exports.ErrorCode = ErrorCode;
 exports.FetchHttpRequester = FetchHttpRequester;
 exports.FriendApi = FriendApi;
+exports.ImageApi = ImageApi;
 exports.MessageApi = MessageApi;
 exports.MessageTokenApi = MessageTokenApi;
 exports.OpenAbstractApi = OpenAbstractApi;
@@ -1273,6 +1500,7 @@ exports.WebhookApi = WebhookApi;
 exports.WebhookType = WebhookType;
 exports.WebhookTypeDescription = WebhookTypeDescription;
 exports.batchSendRequest = batchSendRequest;
+exports.callExecuteRaw = callExecuteRaw;
 exports.errorCodeFromValue = errorCodeFromValue;
 exports.isRateLimitedCode = isRateLimitedCode;
 exports.isSuccessfulHttpStatus = isSuccessfulHttpStatus;