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

package/package.json

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

package/src/api/image-api.ts

@@ -0,0 +1,241 @@
+import { AccessKeyManager } from '../access-key-manager';
+import { ResolvedPushPlusConfig } from '../config';
+import { PushPlusError } from '../exception';
+import { HttpRequester, callExecuteRaw, isSuccessfulHttpStatus } from '../http';
+import {
+  ImageItem,
+  ImageUploadResult,
+  ImageUploadToken,
+  PageQuery,
+  PageResult,
+} from '../models';
+import { OpenAbstractApi } from './open-base';
+
+/**
+ * 二进制图片输入。
+ *
+ * - `Uint8Array`：Node 与浏览器通用（Buffer 是 Uint8Array 的子类）
+ * - `ArrayBuffer`：原始字节缓冲
+ * - `Blob`/`File`：浏览器与 Node 18+ 都支持
+ */
+export type ImageFileInput = Uint8Array | ArrayBuffer | Blob;
+
+/** 通用上传选项。 */
+export interface ImageUploadOptions {
+  /** 文件名（建议带扩展名，如 `logo.png`）。 */
+  fileName: string;
+  /** 文件 MIME 类型；未指定时按文件名后缀猜测。 */
+  contentType?: string;
+}
+
+/**
+ * 开放接口 - 图片服务（文档「十二. 图片服务接口」）。
+ *
+ * 包含 4 个接口：
+ *
+ * 1. {@link ImageApi.getUploadToken} 获取上传凭证
+ * 2. {@link ImageApi.upload} 上传图片到七牛云（multipart/form-data，**不**带 access-key）
+ * 3. {@link ImageApi.list} 已上传图片列表
+ * 4. {@link ImageApi.delete} 主动删除图片
+ *
+ * 另外提供 {@link ImageApi.uploadBytes} 等便捷方法，
+ * 内部自动「先取凭证 → 再上传」。仅支持图片类型，30 天有效期。
+ */
+export class ImageApi extends OpenAbstractApi {
+  constructor(config: ResolvedPushPlusConfig, http: HttpRequester, mgr: AccessKeyManager) {
+    super(config, http, mgr);
+  }
+
+  /** 1. 获取上传凭证。 */
+  getUploadToken(): Promise<ImageUploadToken> {
+    return this.executeOpen<ImageUploadToken>('GET', '/api/open/userImage/uploadToken');
+  }
+
+  /**
+   * 2. 上传图片到七牛云。
+   *
+   * 使用「获取上传凭证」返回的 `uploadUrl` 与 `uploadToken`，
+   * 按七牛云表单上传规范以 `multipart/form-data` 提交。该请求
+   * **不会** 携带 PushPlus 的 `access-key` 头。
+   */
+  async upload(
+    token: ImageUploadToken,
+    file: ImageFileInput,
+    options: ImageUploadOptions,
+  ): Promise<ImageUploadResult> {
+    if (token == null) {
+      throw new PushPlusError('上传凭证 token 不能为 null');
+    }
+    if (!token.uploadToken) {
+      throw new PushPlusError('上传凭证 uploadToken 不能为空');
+    }
+    const uploadUrl = token.uploadUrl || token.uploadHost;
+    if (!uploadUrl) {
+      throw new PushPlusError('上传凭证未返回 uploadUrl/uploadHost');
+    }
+    return this.uploadToQiniu(uploadUrl, token.uploadToken, file, options);
+  }
+
+  /**
+   * 2. 上传图片到七牛云（低层方法）。直接指定上传地址与 token。
+   */
+  async uploadToQiniu(
+    uploadUrl: string,
+    uploadToken: string,
+    file: ImageFileInput,
+    options: ImageUploadOptions,
+  ): Promise<ImageUploadResult> {
+    if (!uploadUrl) {
+      throw new PushPlusError('uploadUrl 不能为空');
+    }
+    if (!uploadToken) {
+      throw new PushPlusError('uploadToken 不能为空');
+    }
+    const bytes = await toUint8Array(file);
+    if (bytes.byteLength === 0) {
+      throw new PushPlusError('上传文件内容不能为空');
+    }
+
+    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(
+        `上传图片到七牛云失败: status=${resp.statusCode}, body=${resp.body}`,
+        resp.statusCode,
+      );
+    }
+    let result: ImageUploadResult;
+    try {
+      result = JSON.parse(resp.body) as ImageUploadResult;
+    } catch (e) {
+      throw new PushPlusError(
+        `解析七牛云响应失败: ${(e as Error).message}, payload=${resp.body}`,
+        -1,
+        { cause: e },
+      );
+    }
+    if (result == null || typeof result !== 'object') {
+      throw new PushPlusError(`七牛云返回非 JSON 对象: ${resp.body}`);
+    }
+    if (result.errno !== 0) {
+      throw new PushPlusError(
+        `七牛云上传失败: errno=${result.errno}, msg=${result.msg ?? ''}`,
+        result.errno ?? -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: ImageFileInput, options: ImageUploadOptions): Promise<ImageUploadResult> {
+    const token = await this.getUploadToken();
+    return this.upload(token, file, options);
+  }
+
+  /** 3. 图片列表。 */
+  list(query?: PageQuery): Promise<PageResult<ImageItem>> {
+    return this.executeOpen<PageResult<ImageItem>>(
+      'POST',
+      '/api/open/userImage/list',
+      query ?? {},
+    );
+  }
+
+  /**
+   * 4. 主动删除图片；未删除的图片默认 30 天后由系统自动清理。
+   */
+  async delete(id: number): Promise<void> {
+    await this.executeOpen<unknown>(
+      'DELETE',
+      this.appendQuery('/api/open/userImage/delete', { id }),
+    );
+  }
+}
+
+/* ============================== 内部辅助 ============================== */
+
+async function toUint8Array(file: ImageFileInput): Promise<Uint8Array> {
+  if (file == null) {
+    throw new PushPlusError('上传文件不能为 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(`不支持的上传文件类型: ${Object.prototype.toString.call(file)}`);
+}
+
+function buildMultipartBody(
+  boundary: string,
+  uploadToken: string,
+  fileName: string,
+  contentType: string,
+  fileBytes: Uint8Array,
+): Uint8Array {
+  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: string): string {
+  return name.replace(/"/g, '_').replace(/\r/g, ' ').replace(/\n/g, ' ');
+}
+
+function guessContentTypeByName(name: string | undefined): string | null {
+  if (!name) return null;
+  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(): string {
+  // 32 个 hex 字符；不依赖 Node-only 的 crypto，浏览器/Node 都能跑。
+  let s = '';
+  for (let i = 0; i < 32; i++) {
+    s += Math.floor(Math.random() * 16).toString(16);
+  }
+  return s;
+}

package/src/client.ts

@@ -3,6 +3,7 @@ import { AccessKeyApi } from './api/access-key-api';
 import { ChannelApi } from './api/channel-api';
 import { ClawBotApi } from './api/clawbot-api';
 import { FriendApi } from './api/friend-api';
+import { ImageApi } from './api/image-api';
 import { MessageApi } from './api/message-api';
 import { MessageTokenApi } from './api/message-token-api';
 import { OpenMessageApi } from './api/open-message-api';
@@ -65,6 +66,7 @@ export class PushPlusClient {
   readonly clawBot: ClawBotApi;
   readonly setting: SettingApi;
   readonly pre: PreApi;
+  readonly image: ImageApi;
 
   constructor(options: PushPlusClientOptions = {}) {
     this.config = resolveConfig(options);
@@ -86,6 +88,7 @@ export 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 入口。 */

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

package/src/http.ts

@@ -8,6 +8,20 @@ export interface HttpRequestOptions {
   body?: string | null;
 }
 
+/**
+ * 二进制请求体（multipart 上传等场景使用）。
+ *
+ * 接受 fetch `BodyInit` 中的常见二进制形态。
+ */
+export type HttpRawBody = Uint8Array | ArrayBuffer | Blob | null;
+
+export interface HttpRawRequestOptions {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: HttpRawBody;
+}
+
 export interface HttpResponse {
   statusCode: number;
   body: string;
@@ -18,9 +32,45 @@ export interface HttpResponse {
  *
  * SDK 默认提供基于 `fetch` 的实现（Node 18+ 内置 / 浏览器原生）。
  * 调用方也可以自行实现并通过 `PushPlusClient` 注入以使用其它客户端（如 axios/undici/got）。
+ *
+ * `executeRaw` 用于二进制请求体场景（如图片 multipart 上传）。
+ * 自定义实现可选择覆写以正确处理二进制；未覆写时调用方应通过
+ * {@link callExecuteRaw} 适配回退到 `execute`。
  */
 export interface HttpRequester {
   execute(options: HttpRequestOptions): Promise<HttpResponse>;
+  /** 可选：执行带二进制 body 的请求。 */
+  executeRaw?(options: HttpRawRequestOptions): Promise<HttpResponse>;
+}
+
+/**
+ * 调用 {@link HttpRequester} 的二进制通道。
+ *
+ * - 若实现类提供了 `executeRaw`（推荐对二进制场景覆写），则直接使用；
+ * - 否则按 UTF-8 把字节解码成字符串后回退到 {@link HttpRequester.execute}，
+ *   适用于 body 本身是文本的场景。
+ */
+export async function callExecuteRaw(
+  requester: HttpRequester,
+  options: HttpRawRequestOptions,
+): Promise<HttpResponse> {
+  if (typeof requester.executeRaw === 'function') {
+    return requester.executeRaw(options);
+  }
+  const { method, url, headers, body } = options;
+  let text: string | null = 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 });
 }
 
 /**
@@ -52,7 +102,36 @@ export class FetchHttpRequester implements HttpRequester {
   }
 
   async execute(options: HttpRequestOptions): Promise<HttpResponse> {
-    const { method, url, headers, body } = options;
+    return this.doExecute({
+      method: options.method,
+      url: options.url,
+      headers: options.headers,
+      body: options.body ?? null,
+      bodyForLog: options.body ?? null,
+      defaultContentType: 'application/json;charset=UTF-8',
+    });
+  }
+
+  async executeRaw(options: HttpRawRequestOptions): Promise<HttpResponse> {
+    return this.doExecute({
+      method: options.method,
+      url: options.url,
+      headers: options.headers,
+      body: options.body ?? null,
+      bodyForLog: null,
+      defaultContentType: 'application/octet-stream',
+    });
+  }
+
+  private async doExecute(args: {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body: string | HttpRawBody;
+    bodyForLog: string | null;
+    defaultContentType: string;
+  }): Promise<HttpResponse> {
+    const { method, url, headers, body, bodyForLog, defaultContentType } = args;
     const finalHeaders: Record<string, string> = {};
 
     let hasContentType = false;
@@ -63,8 +142,8 @@ export class FetchHttpRequester implements HttpRequester {
         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;
     }
     // 浏览器中不允许设置 User-Agent，仅在非浏览器环境下添加
     if (typeof window === 'undefined' && !finalHeaders['User-Agent'] && !finalHeaders['user-agent']) {
@@ -72,8 +151,14 @@ export class FetchHttpRequester implements HttpRequester {
     }
 
     if (this.logRequest) {
-      // eslint-disable-next-line no-console
-      console.debug('[pushplus] >>>', method, url, 'body=', body);
+      if (bodyForLog != null) {
+        // eslint-disable-next-line no-console
+        console.debug('[pushplus] >>>', method, url, 'body=', bodyForLog);
+      } else {
+        const len = bodyLength(body);
+        // eslint-disable-next-line no-console
+        console.debug('[pushplus] >>>', method, url, 'bodyBytes=', len);
+      }
     }
 
     const controller = new AbortController();
@@ -86,7 +171,8 @@ export class FetchHttpRequester implements HttpRequester {
         signal: controller.signal,
       };
       if (body != null) {
-        init.body = body;
+        // fetch BodyInit 兼容 string / Uint8Array / ArrayBuffer / Blob 等。
+        init.body = body as BodyInit;
       }
       const resp = await this.fetchImpl(url, init);
       const respBody = await resp.text();
@@ -109,6 +195,15 @@ export class FetchHttpRequester implements HttpRequester {
   }
 }
 
+function bodyLength(body: unknown): number {
+  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;
+}
+
 /**
  * 是否处于成功的 HTTP 状态码区间（2xx）。
  */

package/src/index.ts

@@ -33,9 +33,12 @@ export { PushPlusError, PushPlusException } from './exception';
 export {
   type HttpRequester,
   type HttpRequestOptions,
+  type HttpRawBody,
+  type HttpRawRequestOptions,
   type HttpResponse,
   FetchHttpRequester,
   isSuccessfulHttpStatus,
+  callExecuteRaw,
 } from './http';
 export { RateLimitGuard } from './rate-limit';
 export { AccessKeyManager } from './access-key-manager';
@@ -89,6 +92,9 @@ export type {
   PreDetail,
   PreSaveRequest,
   PreTestRequest,
+  ImageUploadToken,
+  ImageUploadResult,
+  ImageItem,
 } from './models';
 
 export {
@@ -114,3 +120,8 @@ export { ChannelApi } from './api/channel-api';
 export { ClawBotApi } from './api/clawbot-api';
 export { SettingApi } from './api/setting-api';
 export { PreApi } from './api/pre-api';
+export {
+  ImageApi,
+  type ImageFileInput,
+  type ImageUploadOptions,
+} from './api/image-api';

package/src/models.ts

@@ -578,3 +578,65 @@ export interface PreTestRequest {
   contentType?: number;
   message?: string;
 }
+
+/* ============================== 开放接口 - image ============================== */
+
+/**
+ * 图片服务 - 获取上传凭证响应。
+ *
+ * 对应文档「十二. 图片服务接口 / 1. 获取上传凭证」。
+ * 返回七牛云表单上传所需的 token 及上传域名、存储桶等信息。
+ */
+export interface ImageUploadToken {
+  /** 七牛云上传凭证。 */
+  uploadToken?: string;
+  /** 七牛云上传域名，例如 `https://upload.qiniup.com`。 */
+  uploadHost?: string;
+  /** 七牛云上传地址，一般等同于 `uploadHost + "/"`。 */
+  uploadUrl?: string;
+  /** 七牛云存储桶名称。 */
+  bucket?: string;
+  /** 凭证有效时间（秒）。 */
+  expiresIn?: number;
+}
+
+/**
+ * 图片服务 - 上传图片响应（由七牛云直接返回）。
+ *
+ * 注意：该响应不是 PushPlus 统一的 `{code, msg, data}` 结构，
+ * 判断成功使用 `errno === 0`。
+ */
+export interface ImageUploadResult {
+  /** 错误码；0 表示成功。 */
+  errno?: number;
+  /** 文件扩展名，例如 `.png`。 */
+  ext?: string;
+  /** 文件名。 */
+  fname?: string;
+  /** 文件大小（字节）。 */
+  fsize?: number;
+  /** 七牛云文件 hash。 */
+  hash?: string;
+  /** 对象存储中的路径 key。 */
+  key?: string;
+  /** MIME 类型，例如 `image/png`。 */
+  mimeType?: string;
+  /** 响应说明。 */
+  msg?: string;
+  /** 缩略图地址。 */
+  thumbnail?: string;
+  /** 图片访问地址。 */
+  url?: string;
+}
+
+/** 图片服务 - 图片列表项。 */
+export interface ImageItem {
+  /** 图片 id。 */
+  id?: number;
+  /** 图片地址。 */
+  imgUrl?: string;
+  /** 缩略图地址。 */
+  thumbnail?: string;
+  /** 创建时间。 */
+  createTime?: string;
+}