@jiseer/qiniu 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jiseer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,429 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  JiseerQiniuError: () => JiseerQiniuError,
+  QiniuClient: () => QiniuClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_promises2 = require("fs/promises");
+var import_node_path2 = require("path");
+
+// src/errors.ts
+var JiseerQiniuError = class extends Error {
+  code;
+  status;
+  path;
+  failures;
+  constructor(message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "JiseerQiniuError";
+    this.code = options.code ?? "UNKNOWN";
+    this.status = options.status;
+    this.path = options.path;
+    this.failures = options.failures;
+  }
+};
+
+// src/http.ts
+var MAX_RETRY_WAIT_SECONDS = 5;
+function joinUrl(endpoint, path) {
+  return `${endpoint.replace(/\/+$/, "")}${path}`;
+}
+async function postJson(url, body, headers, context) {
+  let retried = false;
+  for (; ; ) {
+    const response = await send(url, body, headers, context);
+    if (response.status === 429 && !retried) {
+      const wait = retryAfterSeconds(response);
+      if (wait <= MAX_RETRY_WAIT_SECONDS) {
+        retried = true;
+        await sleep(wait * 1e3);
+        continue;
+      }
+      throw new JiseerQiniuError(`\u670D\u52A1\u7AEF\u9650\u6D41\uFF0C\u9700\u8981\u7B49\u5F85 ${wait} \u79D2`, {
+        code: 42901,
+        status: 429,
+        path: url
+      });
+    }
+    const text = await response.text();
+    return parseEnvelope(text, url, response.status);
+  }
+}
+async function send(url, body, headers, context) {
+  try {
+    return await context.fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body ?? {}),
+      signal: withTimeout(context.timeoutMs, context.signal)
+    });
+  } catch (error) {
+    throw new JiseerQiniuError(`\u8BF7\u6C42 ${url} \u5931\u8D25\uFF1A${messageOf(error)}`, {
+      code: "NETWORK",
+      path: url,
+      cause: error
+    });
+  }
+}
+function parseEnvelope(text, url, status) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new JiseerQiniuError(`${url} \u8FD4\u56DE\u975E JSON\uFF08HTTP ${status}\uFF09\uFF1A${snippet(text)}`, {
+      code: "BAD_RESPONSE",
+      status,
+      path: url
+    });
+  }
+  if (typeof payload.code !== "number") {
+    throw new JiseerQiniuError(`${url} \u8FD4\u56DE\u4E86\u975E\u9884\u671F\u7ED3\u6784\uFF08HTTP ${status}\uFF09\uFF1A${snippet(text)}`, {
+      code: "BAD_RESPONSE",
+      status,
+      path: url
+    });
+  }
+  if (payload.code !== 0) {
+    throw new JiseerQiniuError(`${url} \u8C03\u7528\u5931\u8D25 [${payload.code}] ${payload.message}`, {
+      code: payload.code,
+      status,
+      path: url
+    });
+  }
+  if (payload.data === void 0 || payload.data === null) {
+    throw new JiseerQiniuError(`${url} \u54CD\u5E94\u7F3A\u5C11 data`, {
+      code: "MISSING_DATA",
+      status,
+      path: url
+    });
+  }
+  return payload.data;
+}
+function snippet(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return "(\u7A7A\u54CD\u5E94)";
+  return trimmed.length <= 512 ? trimmed : `${trimmed.slice(0, 512)}\u2026`;
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function withTimeout(timeoutMs, signal) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  if (!signal) return timeout;
+  if (typeof AbortSignal.any === "function") return AbortSignal.any([signal, timeout]);
+  const controller = new AbortController();
+  const abort = () => {
+    signal.removeEventListener("abort", abort);
+    timeout.removeEventListener("abort", abort);
+    controller.abort(signal.reason ?? timeout.reason);
+  };
+  if (signal.aborted || timeout.aborted) {
+    abort();
+    return controller.signal;
+  }
+  signal.addEventListener("abort", abort, { once: true });
+  timeout.addEventListener("abort", abort, { once: true });
+  return controller.signal;
+}
+function retryAfterSeconds(response) {
+  const raw = response.headers.get("retry-after");
+  const parsed = raw === null ? Number.NaN : Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : 1;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+
+// src/scan.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var import_fast_glob = __toESM(require("fast-glob"), 1);
+var DEFAULT_IGNORE = [".git/**", "node_modules/**", "target/**", "__pycache__/**"];
+async function scanPaths(inputs, options = {}) {
+  const files = [];
+  for (const input of inputs) {
+    const absolute = (0, import_node_path.resolve)(input);
+    const info = await (0, import_promises.stat)(absolute).catch(() => null);
+    if (!info) {
+      throw new JiseerQiniuError(`\u65E0\u6CD5\u8BFB\u53D6 ${input}`, { code: "NOT_FOUND", path: input });
+    }
+    if (info.isFile()) {
+      files.push({ absolute, relative: (0, import_node_path.basename)(absolute), size: info.size });
+      continue;
+    }
+    if (!info.isDirectory()) continue;
+    const entries = await (0, import_fast_glob.default)("**/*", {
+      cwd: absolute,
+      dot: false,
+      onlyFiles: true,
+      followSymbolicLinks: false,
+      ignore: [...DEFAULT_IGNORE, ...options.exclude ?? []]
+    });
+    for (const entry of entries.sort()) {
+      const child = (0, import_node_path.resolve)(absolute, entry);
+      const childInfo = await (0, import_promises.stat)(child).catch(() => null);
+      if (!childInfo || !childInfo.isFile()) continue;
+      files.push({
+        absolute: child,
+        relative: entry.split("\\").join("/"),
+        size: childInfo.size
+      });
+    }
+  }
+  files.sort((a, b) => a.relative.localeCompare(b.relative));
+  return files;
+}
+
+// src/client.ts
+var DEFAULT_CONCURRENCY = 4;
+var DEFAULT_TIMEOUT_MS = 5 * 6e4;
+var UPLOAD_KEY_HEADER = "x-qiniu-upload-key";
+var STATUS_HINTS = {
+  401: "\u4E0A\u4F20\u5BC6\u94A5\u7F3A\u5931\u6216\u65E0\u6548",
+  403: "\u8DEF\u5F84\u4E0D\u5728\u8BE5\u5BA2\u6237\u7AEF\u7684\u53EF\u5199\u8303\u56F4\u5185",
+  406: "\u5185\u5BB9\u7C7B\u578B\u88AB\u4E0A\u4F20\u7B56\u7565\u7684 mimeLimit \u62D2\u7EDD",
+  413: "\u6587\u4EF6\u8D85\u8FC7\u4E0A\u4F20\u7B56\u7565\u7684 fsizeLimit",
+  579: "\u4E03\u725B\u56DE\u8C03\u4E1A\u52A1\u670D\u52A1\u5668\u5931\u8D25",
+  614: "\u4E0A\u4F20\u7A7A\u95F4\u4E0D\u5B58\u5728",
+  631: "\u4E0A\u4F20\u7A7A\u95F4\u5DF2\u88AB\u7981\u7528",
+  701: "\u5BF9\u8C61\u5DF2\u5B58\u5728\uFF08\u7B56\u7565\u4E3A insertOnly\uFF09\uFF0C\u8BBE\u7F6E overwrite: true \u53EF\u8986\u76D6"
+};
+var QiniuClient = class {
+  options;
+  constructor(options) {
+    if (typeof globalThis === "object" && "window" in globalThis && "document" in globalThis) {
+      throw new JiseerQiniuError("@jiseer/qiniu \u4EC5\u652F\u6301 Node \u73AF\u5883\uFF0C\u8BF7\u52FF\u5728\u6D4F\u89C8\u5668\u4E2D\u4F7F\u7528", {
+        code: "BROWSER_NOT_SUPPORTED"
+      });
+    }
+    if (!options || typeof options.endpoint !== "string" || options.endpoint.length === 0) {
+      throw new JiseerQiniuError("\u7F3A\u5C11 endpoint\uFF08\u51ED\u8BC1\u670D\u52A1\u5730\u5740\uFF09", {
+        code: "INVALID_OPTIONS"
+      });
+    }
+    if (typeof options.uploadKey !== "string" || options.uploadKey.length === 0) {
+      throw new JiseerQiniuError("\u7F3A\u5C11 uploadKey\uFF08\u4E0A\u4F20\u5BC6\u94A5\uFF09", { code: "INVALID_OPTIONS" });
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new JiseerQiniuError("\u5F53\u524D\u73AF\u5883\u6CA1\u6709 fetch\uFF0C\u9700\u8981 Node 18+", { code: "NO_FETCH" });
+    }
+    this.options = {
+      endpoint: options.endpoint.replace(/\/+$/, ""),
+      uploadKey: options.uploadKey,
+      fetch: fetchImpl,
+      concurrency: options.concurrency ?? DEFAULT_CONCURRENCY,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      publicDomain: options.publicDomain
+    };
+  }
+  /** 只取凭证，不实际上传 */
+  token(options = {}) {
+    return this.requestToken(options);
+  }
+  /** 上传单个文件 */
+  async uploadFile(file, options = {}) {
+    const result = await this.uploadPaths([file], options);
+    const uploaded = result.files[0];
+    if (uploaded) return uploaded;
+    const failure = result.failures[0];
+    throw failure ? failure.error : new JiseerQiniuError(`\u4E0A\u4F20\u5931\u8D25\uFF1A${file}`, { code: "UPLOAD_FAILED", path: file });
+  }
+  /** 上传整个目录 */
+  uploadDir(dir, options = {}) {
+    return this.uploadPaths([dir], options);
+  }
+  /** 上传任意文件/目录组成的路径列表 */
+  async uploadPaths(paths, options = {}) {
+    const scanned = await scanPaths(paths, { exclude: options.exclude });
+    if (scanned.length === 0) {
+      throw new JiseerQiniuError("\u6CA1\u6709\u627E\u5230\u53EF\u4E0A\u4F20\u7684\u6587\u4EF6", { code: "NO_FILES" });
+    }
+    if (options.dryRun) {
+      return {
+        files: [],
+        failures: [],
+        planned: scanned.map((file) => ({ file: file.relative, size: file.size }))
+      };
+    }
+    const concurrency = Math.max(1, options.concurrency ?? this.options.concurrency);
+    const publicDomain = options.publicDomain ?? this.options.publicDomain;
+    const total = scanned.length;
+    const files = [];
+    const failures = [];
+    let done = 0;
+    let cursor = 0;
+    let stopped = false;
+    const worker = async () => {
+      for (; ; ) {
+        if (stopped) return;
+        if (options.signal?.aborted) return;
+        const file = scanned[cursor];
+        cursor += 1;
+        if (!file) return;
+        try {
+          const uploaded = await this.uploadOne(file, options, publicDomain);
+          files.push(uploaded);
+          done += 1;
+          options.onProgress?.({ file: uploaded.file, done, total, size: uploaded.size });
+        } catch (error) {
+          const normalized = error instanceof Error ? error : new Error(messageOf(error));
+          failures.push({ file: file.relative, error: normalized });
+          if (!options.continueOnError) stopped = true;
+        }
+      }
+    };
+    const workers = Array.from({ length: Math.min(concurrency, total) }, () => worker());
+    await Promise.all(workers);
+    files.sort((a, b) => a.file.localeCompare(b.file));
+    if (failures.length > 0 && !options.continueOnError) {
+      const first = failures[0];
+      throw new JiseerQiniuError(
+        `${failures.length} \u4E2A\u6587\u4EF6\u4E0A\u4F20\u5931\u8D25${first ? `\uFF0C\u4F8B\u5982 ${first.file}\uFF1A${first.error.message}` : ""}`,
+        { code: "UPLOAD_FAILED", failures }
+      );
+    }
+    return { files, failures };
+  }
+  async uploadOne(file, options, publicDomain) {
+    const fileName = (0, import_node_path2.basename)(file.relative);
+    const token = await this.requestToken({
+      fileName,
+      path: joinBasePath(options.basePath, file.relative),
+      overwrite: options.overwrite ?? true
+    });
+    const content = await (0, import_promises2.readFile)(file.absolute);
+    const form = new FormData();
+    form.append("token", token.token);
+    form.append("key", token.key);
+    form.append("fname", fileName);
+    form.append("file", new Blob([content], { type: "application/octet-stream" }), fileName);
+    const response = await this.options.fetch(token.uploadUrl, {
+      method: "POST",
+      body: form,
+      signal: withTimeout(this.options.timeoutMs, options.signal)
+    }).catch((error) => {
+      throw new JiseerQiniuError(`\u4E0A\u4F20 ${file.relative} \u5931\u8D25\uFF1A${messageOf(error)}`, {
+        code: "NETWORK",
+        path: file.relative,
+        cause: error
+      });
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw uploadError(response.status, text, file.relative);
+    }
+    const parsed = normalizeUploadResponse(text, file.relative);
+    if (parsed.fsize !== void 0 && parsed.fsize !== file.size) {
+      throw new JiseerQiniuError(
+        `\u670D\u52A1\u7AEF\u8FD4\u56DE\u5927\u5C0F ${parsed.fsize} \u4E0E\u672C\u5730 ${file.size} \u4E0D\u4E00\u81F4`,
+        { code: "SIZE_MISMATCH", path: file.relative }
+      );
+    }
+    const url = publicDomain === void 0 ? token.publicUrl ?? void 0 : `${publicDomain.replace(/\/+$/, "")}/${token.key}`;
+    return { file: file.relative, key: parsed.key, size: file.size, hash: parsed.hash, url };
+  }
+  requestToken(options) {
+    return postJson(
+      joinUrl(this.options.endpoint, "/api/upload/token"),
+      {
+        fileName: options.fileName,
+        path: options.path,
+        overwrite: options.overwrite ?? false
+      },
+      { [UPLOAD_KEY_HEADER]: this.options.uploadKey },
+      { fetch: this.options.fetch, timeoutMs: this.options.timeoutMs }
+    );
+  }
+};
+function joinBasePath(basePath, relative) {
+  const base = basePath?.trim().replace(/^\/+|\/+$/g, "");
+  return base ? `${base}/${relative}` : relative;
+}
+function uploadError(status, text, path) {
+  const detail = extractError(text);
+  const hint = STATUS_HINTS[status];
+  const message = hint === void 0 ? `\u4E0A\u4F20\u5931\u8D25\uFF08HTTP ${status}\uFF09\uFF1A${detail}` : `\u4E0A\u4F20\u5931\u8D25\uFF08HTTP ${status}\uFF09\uFF1A${hint}\uFF1B\u4E03\u725B\u8FD4\u56DE\uFF1A${detail}`;
+  return new JiseerQiniuError(message, {
+    code: status === 701 ? 701 : "UPLOAD_FAILED",
+    status,
+    path
+  });
+}
+function extractError(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed.error === "string") return parsed.error;
+  } catch {
+  }
+  return snippet(text);
+}
+function normalizeUploadResponse(text, path) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new JiseerQiniuError(`\u4E0A\u4F20\u54CD\u5E94\u975E JSON\uFF1A${snippet(text)}`, {
+      code: "BAD_RESPONSE",
+      path
+    });
+  }
+  let data = payload;
+  if (typeof data.code === "number") {
+    if (data.code !== 0) {
+      throw new JiseerQiniuError(
+        `\u56DE\u8C03\u8FD4\u56DE\u9519\u8BEF [${data.code}] ${String(data.message ?? "")}`,
+        { code: data.code, path }
+      );
+    }
+    data = data.data ?? {};
+  }
+  const key = data.key;
+  if (typeof key !== "string") {
+    throw new JiseerQiniuError(`\u4E0A\u4F20\u54CD\u5E94\u7F3A\u5C11 key\uFF1A${snippet(text)}`, {
+      code: "BAD_RESPONSE",
+      path
+    });
+  }
+  const hash = typeof data.hash === "string" ? data.hash : void 0;
+  const rawSize = data.fsize ?? data.size;
+  const fsize = typeof rawSize === "number" ? rawSize : void 0;
+  return { key, hash, fsize };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  JiseerQiniuError,
+  QiniuClient
+});

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+/** 创建一个客户端所需的参数 */
+interface ClientOptions {
+    /** 凭证服务地址，例如 https://api.example.com */
+    endpoint: string;
+    /** 上传密钥（只在 Node 侧使用，不要打进浏览器） */
+    uploadKey: string;
+    /** 注入自定义 fetch（测试、代理场景） */
+    fetch?: typeof fetch;
+    /** 覆盖访问域名，用于拼接最终 URL */
+    publicDomain?: string;
+    /** 单次 uploadPaths 的并发数，默认 4 */
+    concurrency?: number;
+    /** 单次 HTTP 请求（取凭证与上传）的总时长上限（毫秒），默认 300000（5 分钟） */
+    timeoutMs?: number;
+}
+/** `/api/upload/token` 的返回 */
+interface TokenInfo {
+    token: string;
+    key: string;
+    uploadUrl: string;
+    expiresIn: number;
+    publicUrl?: string | null;
+    callback: boolean;
+}
+/** 只取凭证时的可选参数 */
+interface TokenOptions {
+    /** 原始文件名，仅用于决定扩展名 */
+    fileName?: string;
+    /** 相对路径，决定对象 key（保留目录结构） */
+    path?: string;
+    /** 允许覆盖同名对象，默认 false */
+    overwrite?: boolean;
+}
+/** 单个上传成功的文件 */
+interface UploadedFile {
+    /** 本地相对路径 */
+    file: string;
+    key: string;
+    size: number;
+    hash?: string;
+    url?: string;
+}
+interface UploadFailure {
+    file: string;
+    error: Error;
+}
+interface PlannedFile {
+    file: string;
+    size: number;
+}
+interface UploadResult {
+    files: UploadedFile[];
+    failures: UploadFailure[];
+    /** 只在 dryRun 时返回 */
+    planned?: PlannedFile[];
+}
+interface ProgressEvent {
+    file: string;
+    done: number;
+    total: number;
+    size: number;
+}
+interface UploadOptions {
+    /** 远程路径前缀（需与服务端 key 的可写前缀一致），会拼在相对路径前面 */
+    basePath?: string;
+    /** 允许覆盖同名对象，默认 true（构建产物同步语义） */
+    overwrite?: boolean;
+    /** 排除规则（glob，相对上传目录） */
+    exclude?: string[];
+    /** 覆盖客户端的并发数 */
+    concurrency?: number;
+    /** 只扫描并返回清单，不发任何请求 */
+    dryRun?: boolean;
+    /** 覆盖访问域名 */
+    publicDomain?: string;
+    /** 单个文件失败后继续上传其余文件 */
+    continueOnError?: boolean;
+    /** 中断信号 */
+    signal?: AbortSignal;
+    /** 每完成一个文件回调一次 */
+    onProgress?: (event: ProgressEvent) => void;
+}
+
+declare class QiniuClient {
+    private readonly options;
+    constructor(options: ClientOptions);
+    /** 只取凭证，不实际上传 */
+    token(options?: TokenOptions): Promise<TokenInfo>;
+    /** 上传单个文件 */
+    uploadFile(file: string, options?: UploadOptions): Promise<UploadedFile>;
+    /** 上传整个目录 */
+    uploadDir(dir: string, options?: UploadOptions): Promise<UploadResult>;
+    /** 上传任意文件/目录组成的路径列表 */
+    uploadPaths(paths: string[], options?: UploadOptions): Promise<UploadResult>;
+    private uploadOne;
+    private requestToken;
+}
+
+interface JiseerQiniuErrorOptions {
+    /** 业务码（服务端返回的 code）或内部错误标识 */
+    code?: string | number;
+    /** HTTP 状态码 */
+    status?: number;
+    /** 出错的接口路径或文件 */
+    path?: string;
+    cause?: unknown;
+    /** `continueOnError: false` 时附带全部失败项 */
+    failures?: UploadFailure[];
+}
+declare class JiseerQiniuError extends Error {
+    readonly code: string | number;
+    readonly status?: number;
+    readonly path?: string;
+    readonly failures?: UploadFailure[];
+    constructor(message: string, options?: JiseerQiniuErrorOptions);
+}
+
+export { type ClientOptions, JiseerQiniuError, type JiseerQiniuErrorOptions, type PlannedFile, type ProgressEvent, QiniuClient, type TokenInfo, type TokenOptions, type UploadFailure, type UploadOptions, type UploadResult, type UploadedFile };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+/** 创建一个客户端所需的参数 */
+interface ClientOptions {
+    /** 凭证服务地址，例如 https://api.example.com */
+    endpoint: string;
+    /** 上传密钥（只在 Node 侧使用，不要打进浏览器） */
+    uploadKey: string;
+    /** 注入自定义 fetch（测试、代理场景） */
+    fetch?: typeof fetch;
+    /** 覆盖访问域名，用于拼接最终 URL */
+    publicDomain?: string;
+    /** 单次 uploadPaths 的并发数，默认 4 */
+    concurrency?: number;
+    /** 单次 HTTP 请求（取凭证与上传）的总时长上限（毫秒），默认 300000（5 分钟） */
+    timeoutMs?: number;
+}
+/** `/api/upload/token` 的返回 */
+interface TokenInfo {
+    token: string;
+    key: string;
+    uploadUrl: string;
+    expiresIn: number;
+    publicUrl?: string | null;
+    callback: boolean;
+}
+/** 只取凭证时的可选参数 */
+interface TokenOptions {
+    /** 原始文件名，仅用于决定扩展名 */
+    fileName?: string;
+    /** 相对路径，决定对象 key（保留目录结构） */
+    path?: string;
+    /** 允许覆盖同名对象，默认 false */
+    overwrite?: boolean;
+}
+/** 单个上传成功的文件 */
+interface UploadedFile {
+    /** 本地相对路径 */
+    file: string;
+    key: string;
+    size: number;
+    hash?: string;
+    url?: string;
+}
+interface UploadFailure {
+    file: string;
+    error: Error;
+}
+interface PlannedFile {
+    file: string;
+    size: number;
+}
+interface UploadResult {
+    files: UploadedFile[];
+    failures: UploadFailure[];
+    /** 只在 dryRun 时返回 */
+    planned?: PlannedFile[];
+}
+interface ProgressEvent {
+    file: string;
+    done: number;
+    total: number;
+    size: number;
+}
+interface UploadOptions {
+    /** 远程路径前缀（需与服务端 key 的可写前缀一致），会拼在相对路径前面 */
+    basePath?: string;
+    /** 允许覆盖同名对象，默认 true（构建产物同步语义） */
+    overwrite?: boolean;
+    /** 排除规则（glob，相对上传目录） */
+    exclude?: string[];
+    /** 覆盖客户端的并发数 */
+    concurrency?: number;
+    /** 只扫描并返回清单，不发任何请求 */
+    dryRun?: boolean;
+    /** 覆盖访问域名 */
+    publicDomain?: string;
+    /** 单个文件失败后继续上传其余文件 */
+    continueOnError?: boolean;
+    /** 中断信号 */
+    signal?: AbortSignal;
+    /** 每完成一个文件回调一次 */
+    onProgress?: (event: ProgressEvent) => void;
+}
+
+declare class QiniuClient {
+    private readonly options;
+    constructor(options: ClientOptions);
+    /** 只取凭证，不实际上传 */
+    token(options?: TokenOptions): Promise<TokenInfo>;
+    /** 上传单个文件 */
+    uploadFile(file: string, options?: UploadOptions): Promise<UploadedFile>;
+    /** 上传整个目录 */
+    uploadDir(dir: string, options?: UploadOptions): Promise<UploadResult>;
+    /** 上传任意文件/目录组成的路径列表 */
+    uploadPaths(paths: string[], options?: UploadOptions): Promise<UploadResult>;
+    private uploadOne;
+    private requestToken;
+}
+
+interface JiseerQiniuErrorOptions {
+    /** 业务码（服务端返回的 code）或内部错误标识 */
+    code?: string | number;
+    /** HTTP 状态码 */
+    status?: number;
+    /** 出错的接口路径或文件 */
+    path?: string;
+    cause?: unknown;
+    /** `continueOnError: false` 时附带全部失败项 */
+    failures?: UploadFailure[];
+}
+declare class JiseerQiniuError extends Error {
+    readonly code: string | number;
+    readonly status?: number;
+    readonly path?: string;
+    readonly failures?: UploadFailure[];
+    constructor(message: string, options?: JiseerQiniuErrorOptions);
+}
+
+export { type ClientOptions, JiseerQiniuError, type JiseerQiniuErrorOptions, type PlannedFile, type ProgressEvent, QiniuClient, type TokenInfo, type TokenOptions, type UploadFailure, type UploadOptions, type UploadResult, type UploadedFile };

package/dist/index.js

@@ -0,0 +1,391 @@
+// src/client.ts
+import { readFile } from "fs/promises";
+import { basename as basename2 } from "path";
+
+// src/errors.ts
+var JiseerQiniuError = class extends Error {
+  code;
+  status;
+  path;
+  failures;
+  constructor(message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "JiseerQiniuError";
+    this.code = options.code ?? "UNKNOWN";
+    this.status = options.status;
+    this.path = options.path;
+    this.failures = options.failures;
+  }
+};
+
+// src/http.ts
+var MAX_RETRY_WAIT_SECONDS = 5;
+function joinUrl(endpoint, path) {
+  return `${endpoint.replace(/\/+$/, "")}${path}`;
+}
+async function postJson(url, body, headers, context) {
+  let retried = false;
+  for (; ; ) {
+    const response = await send(url, body, headers, context);
+    if (response.status === 429 && !retried) {
+      const wait = retryAfterSeconds(response);
+      if (wait <= MAX_RETRY_WAIT_SECONDS) {
+        retried = true;
+        await sleep(wait * 1e3);
+        continue;
+      }
+      throw new JiseerQiniuError(`\u670D\u52A1\u7AEF\u9650\u6D41\uFF0C\u9700\u8981\u7B49\u5F85 ${wait} \u79D2`, {
+        code: 42901,
+        status: 429,
+        path: url
+      });
+    }
+    const text = await response.text();
+    return parseEnvelope(text, url, response.status);
+  }
+}
+async function send(url, body, headers, context) {
+  try {
+    return await context.fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body ?? {}),
+      signal: withTimeout(context.timeoutMs, context.signal)
+    });
+  } catch (error) {
+    throw new JiseerQiniuError(`\u8BF7\u6C42 ${url} \u5931\u8D25\uFF1A${messageOf(error)}`, {
+      code: "NETWORK",
+      path: url,
+      cause: error
+    });
+  }
+}
+function parseEnvelope(text, url, status) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new JiseerQiniuError(`${url} \u8FD4\u56DE\u975E JSON\uFF08HTTP ${status}\uFF09\uFF1A${snippet(text)}`, {
+      code: "BAD_RESPONSE",
+      status,
+      path: url
+    });
+  }
+  if (typeof payload.code !== "number") {
+    throw new JiseerQiniuError(`${url} \u8FD4\u56DE\u4E86\u975E\u9884\u671F\u7ED3\u6784\uFF08HTTP ${status}\uFF09\uFF1A${snippet(text)}`, {
+      code: "BAD_RESPONSE",
+      status,
+      path: url
+    });
+  }
+  if (payload.code !== 0) {
+    throw new JiseerQiniuError(`${url} \u8C03\u7528\u5931\u8D25 [${payload.code}] ${payload.message}`, {
+      code: payload.code,
+      status,
+      path: url
+    });
+  }
+  if (payload.data === void 0 || payload.data === null) {
+    throw new JiseerQiniuError(`${url} \u54CD\u5E94\u7F3A\u5C11 data`, {
+      code: "MISSING_DATA",
+      status,
+      path: url
+    });
+  }
+  return payload.data;
+}
+function snippet(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return "(\u7A7A\u54CD\u5E94)";
+  return trimmed.length <= 512 ? trimmed : `${trimmed.slice(0, 512)}\u2026`;
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function withTimeout(timeoutMs, signal) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  if (!signal) return timeout;
+  if (typeof AbortSignal.any === "function") return AbortSignal.any([signal, timeout]);
+  const controller = new AbortController();
+  const abort = () => {
+    signal.removeEventListener("abort", abort);
+    timeout.removeEventListener("abort", abort);
+    controller.abort(signal.reason ?? timeout.reason);
+  };
+  if (signal.aborted || timeout.aborted) {
+    abort();
+    return controller.signal;
+  }
+  signal.addEventListener("abort", abort, { once: true });
+  timeout.addEventListener("abort", abort, { once: true });
+  return controller.signal;
+}
+function retryAfterSeconds(response) {
+  const raw = response.headers.get("retry-after");
+  const parsed = raw === null ? Number.NaN : Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : 1;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+
+// src/scan.ts
+import { stat } from "fs/promises";
+import { basename, resolve } from "path";
+import fg from "fast-glob";
+var DEFAULT_IGNORE = [".git/**", "node_modules/**", "target/**", "__pycache__/**"];
+async function scanPaths(inputs, options = {}) {
+  const files = [];
+  for (const input of inputs) {
+    const absolute = resolve(input);
+    const info = await stat(absolute).catch(() => null);
+    if (!info) {
+      throw new JiseerQiniuError(`\u65E0\u6CD5\u8BFB\u53D6 ${input}`, { code: "NOT_FOUND", path: input });
+    }
+    if (info.isFile()) {
+      files.push({ absolute, relative: basename(absolute), size: info.size });
+      continue;
+    }
+    if (!info.isDirectory()) continue;
+    const entries = await fg("**/*", {
+      cwd: absolute,
+      dot: false,
+      onlyFiles: true,
+      followSymbolicLinks: false,
+      ignore: [...DEFAULT_IGNORE, ...options.exclude ?? []]
+    });
+    for (const entry of entries.sort()) {
+      const child = resolve(absolute, entry);
+      const childInfo = await stat(child).catch(() => null);
+      if (!childInfo || !childInfo.isFile()) continue;
+      files.push({
+        absolute: child,
+        relative: entry.split("\\").join("/"),
+        size: childInfo.size
+      });
+    }
+  }
+  files.sort((a, b) => a.relative.localeCompare(b.relative));
+  return files;
+}
+
+// src/client.ts
+var DEFAULT_CONCURRENCY = 4;
+var DEFAULT_TIMEOUT_MS = 5 * 6e4;
+var UPLOAD_KEY_HEADER = "x-qiniu-upload-key";
+var STATUS_HINTS = {
+  401: "\u4E0A\u4F20\u5BC6\u94A5\u7F3A\u5931\u6216\u65E0\u6548",
+  403: "\u8DEF\u5F84\u4E0D\u5728\u8BE5\u5BA2\u6237\u7AEF\u7684\u53EF\u5199\u8303\u56F4\u5185",
+  406: "\u5185\u5BB9\u7C7B\u578B\u88AB\u4E0A\u4F20\u7B56\u7565\u7684 mimeLimit \u62D2\u7EDD",
+  413: "\u6587\u4EF6\u8D85\u8FC7\u4E0A\u4F20\u7B56\u7565\u7684 fsizeLimit",
+  579: "\u4E03\u725B\u56DE\u8C03\u4E1A\u52A1\u670D\u52A1\u5668\u5931\u8D25",
+  614: "\u4E0A\u4F20\u7A7A\u95F4\u4E0D\u5B58\u5728",
+  631: "\u4E0A\u4F20\u7A7A\u95F4\u5DF2\u88AB\u7981\u7528",
+  701: "\u5BF9\u8C61\u5DF2\u5B58\u5728\uFF08\u7B56\u7565\u4E3A insertOnly\uFF09\uFF0C\u8BBE\u7F6E overwrite: true \u53EF\u8986\u76D6"
+};
+var QiniuClient = class {
+  options;
+  constructor(options) {
+    if (typeof globalThis === "object" && "window" in globalThis && "document" in globalThis) {
+      throw new JiseerQiniuError("@jiseer/qiniu \u4EC5\u652F\u6301 Node \u73AF\u5883\uFF0C\u8BF7\u52FF\u5728\u6D4F\u89C8\u5668\u4E2D\u4F7F\u7528", {
+        code: "BROWSER_NOT_SUPPORTED"
+      });
+    }
+    if (!options || typeof options.endpoint !== "string" || options.endpoint.length === 0) {
+      throw new JiseerQiniuError("\u7F3A\u5C11 endpoint\uFF08\u51ED\u8BC1\u670D\u52A1\u5730\u5740\uFF09", {
+        code: "INVALID_OPTIONS"
+      });
+    }
+    if (typeof options.uploadKey !== "string" || options.uploadKey.length === 0) {
+      throw new JiseerQiniuError("\u7F3A\u5C11 uploadKey\uFF08\u4E0A\u4F20\u5BC6\u94A5\uFF09", { code: "INVALID_OPTIONS" });
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new JiseerQiniuError("\u5F53\u524D\u73AF\u5883\u6CA1\u6709 fetch\uFF0C\u9700\u8981 Node 18+", { code: "NO_FETCH" });
+    }
+    this.options = {
+      endpoint: options.endpoint.replace(/\/+$/, ""),
+      uploadKey: options.uploadKey,
+      fetch: fetchImpl,
+      concurrency: options.concurrency ?? DEFAULT_CONCURRENCY,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      publicDomain: options.publicDomain
+    };
+  }
+  /** 只取凭证，不实际上传 */
+  token(options = {}) {
+    return this.requestToken(options);
+  }
+  /** 上传单个文件 */
+  async uploadFile(file, options = {}) {
+    const result = await this.uploadPaths([file], options);
+    const uploaded = result.files[0];
+    if (uploaded) return uploaded;
+    const failure = result.failures[0];
+    throw failure ? failure.error : new JiseerQiniuError(`\u4E0A\u4F20\u5931\u8D25\uFF1A${file}`, { code: "UPLOAD_FAILED", path: file });
+  }
+  /** 上传整个目录 */
+  uploadDir(dir, options = {}) {
+    return this.uploadPaths([dir], options);
+  }
+  /** 上传任意文件/目录组成的路径列表 */
+  async uploadPaths(paths, options = {}) {
+    const scanned = await scanPaths(paths, { exclude: options.exclude });
+    if (scanned.length === 0) {
+      throw new JiseerQiniuError("\u6CA1\u6709\u627E\u5230\u53EF\u4E0A\u4F20\u7684\u6587\u4EF6", { code: "NO_FILES" });
+    }
+    if (options.dryRun) {
+      return {
+        files: [],
+        failures: [],
+        planned: scanned.map((file) => ({ file: file.relative, size: file.size }))
+      };
+    }
+    const concurrency = Math.max(1, options.concurrency ?? this.options.concurrency);
+    const publicDomain = options.publicDomain ?? this.options.publicDomain;
+    const total = scanned.length;
+    const files = [];
+    const failures = [];
+    let done = 0;
+    let cursor = 0;
+    let stopped = false;
+    const worker = async () => {
+      for (; ; ) {
+        if (stopped) return;
+        if (options.signal?.aborted) return;
+        const file = scanned[cursor];
+        cursor += 1;
+        if (!file) return;
+        try {
+          const uploaded = await this.uploadOne(file, options, publicDomain);
+          files.push(uploaded);
+          done += 1;
+          options.onProgress?.({ file: uploaded.file, done, total, size: uploaded.size });
+        } catch (error) {
+          const normalized = error instanceof Error ? error : new Error(messageOf(error));
+          failures.push({ file: file.relative, error: normalized });
+          if (!options.continueOnError) stopped = true;
+        }
+      }
+    };
+    const workers = Array.from({ length: Math.min(concurrency, total) }, () => worker());
+    await Promise.all(workers);
+    files.sort((a, b) => a.file.localeCompare(b.file));
+    if (failures.length > 0 && !options.continueOnError) {
+      const first = failures[0];
+      throw new JiseerQiniuError(
+        `${failures.length} \u4E2A\u6587\u4EF6\u4E0A\u4F20\u5931\u8D25${first ? `\uFF0C\u4F8B\u5982 ${first.file}\uFF1A${first.error.message}` : ""}`,
+        { code: "UPLOAD_FAILED", failures }
+      );
+    }
+    return { files, failures };
+  }
+  async uploadOne(file, options, publicDomain) {
+    const fileName = basename2(file.relative);
+    const token = await this.requestToken({
+      fileName,
+      path: joinBasePath(options.basePath, file.relative),
+      overwrite: options.overwrite ?? true
+    });
+    const content = await readFile(file.absolute);
+    const form = new FormData();
+    form.append("token", token.token);
+    form.append("key", token.key);
+    form.append("fname", fileName);
+    form.append("file", new Blob([content], { type: "application/octet-stream" }), fileName);
+    const response = await this.options.fetch(token.uploadUrl, {
+      method: "POST",
+      body: form,
+      signal: withTimeout(this.options.timeoutMs, options.signal)
+    }).catch((error) => {
+      throw new JiseerQiniuError(`\u4E0A\u4F20 ${file.relative} \u5931\u8D25\uFF1A${messageOf(error)}`, {
+        code: "NETWORK",
+        path: file.relative,
+        cause: error
+      });
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw uploadError(response.status, text, file.relative);
+    }
+    const parsed = normalizeUploadResponse(text, file.relative);
+    if (parsed.fsize !== void 0 && parsed.fsize !== file.size) {
+      throw new JiseerQiniuError(
+        `\u670D\u52A1\u7AEF\u8FD4\u56DE\u5927\u5C0F ${parsed.fsize} \u4E0E\u672C\u5730 ${file.size} \u4E0D\u4E00\u81F4`,
+        { code: "SIZE_MISMATCH", path: file.relative }
+      );
+    }
+    const url = publicDomain === void 0 ? token.publicUrl ?? void 0 : `${publicDomain.replace(/\/+$/, "")}/${token.key}`;
+    return { file: file.relative, key: parsed.key, size: file.size, hash: parsed.hash, url };
+  }
+  requestToken(options) {
+    return postJson(
+      joinUrl(this.options.endpoint, "/api/upload/token"),
+      {
+        fileName: options.fileName,
+        path: options.path,
+        overwrite: options.overwrite ?? false
+      },
+      { [UPLOAD_KEY_HEADER]: this.options.uploadKey },
+      { fetch: this.options.fetch, timeoutMs: this.options.timeoutMs }
+    );
+  }
+};
+function joinBasePath(basePath, relative) {
+  const base = basePath?.trim().replace(/^\/+|\/+$/g, "");
+  return base ? `${base}/${relative}` : relative;
+}
+function uploadError(status, text, path) {
+  const detail = extractError(text);
+  const hint = STATUS_HINTS[status];
+  const message = hint === void 0 ? `\u4E0A\u4F20\u5931\u8D25\uFF08HTTP ${status}\uFF09\uFF1A${detail}` : `\u4E0A\u4F20\u5931\u8D25\uFF08HTTP ${status}\uFF09\uFF1A${hint}\uFF1B\u4E03\u725B\u8FD4\u56DE\uFF1A${detail}`;
+  return new JiseerQiniuError(message, {
+    code: status === 701 ? 701 : "UPLOAD_FAILED",
+    status,
+    path
+  });
+}
+function extractError(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed.error === "string") return parsed.error;
+  } catch {
+  }
+  return snippet(text);
+}
+function normalizeUploadResponse(text, path) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new JiseerQiniuError(`\u4E0A\u4F20\u54CD\u5E94\u975E JSON\uFF1A${snippet(text)}`, {
+      code: "BAD_RESPONSE",
+      path
+    });
+  }
+  let data = payload;
+  if (typeof data.code === "number") {
+    if (data.code !== 0) {
+      throw new JiseerQiniuError(
+        `\u56DE\u8C03\u8FD4\u56DE\u9519\u8BEF [${data.code}] ${String(data.message ?? "")}`,
+        { code: data.code, path }
+      );
+    }
+    data = data.data ?? {};
+  }
+  const key = data.key;
+  if (typeof key !== "string") {
+    throw new JiseerQiniuError(`\u4E0A\u4F20\u54CD\u5E94\u7F3A\u5C11 key\uFF1A${snippet(text)}`, {
+      code: "BAD_RESPONSE",
+      path
+    });
+  }
+  const hash = typeof data.hash === "string" ? data.hash : void 0;
+  const rawSize = data.fsize ?? data.size;
+  const fsize = typeof rawSize === "number" ? rawSize : void 0;
+  return { key, hash, fsize };
+}
+export {
+  JiseerQiniuError,
+  QiniuClient
+};

package/docs/api.md

@@ -0,0 +1,96 @@
+# API
+
+## `new QiniuClient(options)`
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| `endpoint` | `string` | 是 | — | 凭证服务地址，末尾斜杠会被忽略 |
+| `uploadKey` | `string` | 是 | — | 上传密钥（只用于调 `/api/upload/token`） |
+| `fetch` | `typeof fetch` | 否 | 全局 `fetch` | 注入自定义实现（测试/代理） |
+| `publicDomain` | `string` | 否 | — | 访问域名，用于拼返回的 URL |
+| `concurrency` | `number` | 否 | `4` | 单次上传的并发数 |
+| `timeoutMs` | `number` | 否 | `300000` | 单次 HTTP 请求（取凭证与上传）的总时长上限；大文件按需调大 |
+
+构造时会检查运行环境：检测到 `window` 与 `document`（浏览器）直接抛 `BROWSER_NOT_SUPPORTED`，避免上传密钥被打进前端包。
+
+## `uploadDir(dir, options?)` / `uploadPaths(paths, options?)`
+
+返回 `Promise<UploadResult>`：
+
+```ts
+interface UploadResult {
+  files: UploadedFile[];            // 按相对路径排序
+  failures: UploadFailure[];
+  planned?: PlannedFile[];          // 仅 dryRun
+}
+```
+
+| 选项 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `basePath` | `string` | — | 远程路径前缀，需与服务端该 key 的可写前缀一致，会拼在相对路径前 |
+| `overwrite` | `boolean` | `true` | 允许覆盖同名对象 |
+| `exclude` | `string[]` | `[]` | 排除规则（glob，相对上传根） |
+| `concurrency` | `number` | 客户端配置 | 覆盖并发数 |
+| `dryRun` | `boolean` | `false` | 只扫描，不发请求 |
+| `publicDomain` | `string` | 客户端配置 | 覆盖访问域名 |
+| `continueOnError` | `boolean` | `false` | 单文件失败后继续 |
+| `signal` | `AbortSignal` | — | 中断上传 |
+| `onProgress` | `(event) => void` | — | 每完成一个文件回调一次 |
+
+`ProgressEvent`：
+
+```ts
+interface ProgressEvent { file: string; done: number; total: number; size: number }
+```
+
+## `uploadFile(file, options?)`
+
+返回 `Promise<UploadedFile>`：
+
+```ts
+interface UploadedFile { file: string; key: string; size: number; hash?: string; url?: string }
+```
+
+传入的单个文件不会被 `exclude` 过滤。
+
+## `token(options?)`
+
+只取凭证，不上传：
+
+```ts
+interface TokenOptions { fileName?: string; path?: string; overwrite?: boolean }
+
+interface TokenInfo {
+  token: string;      // 七牛上传凭证
+  key: string;        // 服务端锁定的对象 key
+  uploadUrl: string;  // 七牛上传入口
+  expiresIn: number;
+  publicUrl?: string | null;
+  callback: boolean;
+}
+```
+
+- `path` 决定对象 key（保留目录结构），指定后 `fileName` 被忽略；
+- `fileName` 只用于决定扩展名（uuid key 场景）。
+
+## 目录扫描规则
+
+- 显式传入的文件原样上传（不过滤）；
+- 目录递归遍历，`dot: false`，跳过 `.git`、`node_modules`、`target`、`__pycache__` 与符号链接；
+- 结果按相对路径排序，保证输出稳定。
+
+## 错误码
+
+| code | 场景 |
+| --- | --- |
+| `BROWSER_NOT_SUPPORTED` | 在浏览器环境构造客户端 |
+| `INVALID_OPTIONS` | 构造参数缺失 |
+| `NO_FETCH` | 环境没有 `fetch`（Node < 18） |
+| `NOT_FOUND` | 路径不存在 |
+| `NO_FILES` | 没找到可上传的文件 |
+| `NETWORK` | 网络错误 / 超时 |
+| `BAD_RESPONSE` | 响应不是预期 JSON |
+| `MISSING_DATA` | 统一信封缺少 `data` |
+| `SIZE_MISMATCH` | 服务端 `fsize` 与本地不一致 |
+| `UPLOAD_FAILED` | 一个或多个文件上传失败 |
+| `40001` / `40101` / `40301` / `413` / `42901` / `701` | 服务端与七牛的业务码 |

package/docs/examples.md

@@ -0,0 +1,106 @@
+# 示例
+
+> 更新日期：2026-10-30
+
+## 1. 多环境
+
+staging 与 production 用不同的 `endpoint` / `uploadKey`（或同一服务不同空间）：
+
+```js
+import { QiniuClient } from '@jiseer/qiniu';
+
+const env = process.env.DEPLOY_ENV ?? 'staging';
+const config = {
+  staging: { endpoint: process.env.STAGING_ENDPOINT, uploadKey: process.env.STAGING_UPLOAD_KEY },
+  production: { endpoint: process.env.PROD_ENDPOINT, uploadKey: process.env.PROD_UPLOAD_KEY },
+}[env];
+
+if (!config?.endpoint || !config?.uploadKey) {
+  throw new Error(`缺少 ${env} 环境的 endpoint / uploadKey`);
+}
+
+const client = new QiniuClient({ ...config, publicDomain: process.env.PUBLIC_DOMAIN });
+const result = await client.uploadDir('dist', { overwrite: true });
+```
+
+服务端前缀是按空间配置的，同一套服务无法把 staging 与 production 写到不同前缀——需要指向不同的凭证服务实例（或不同空间）。
+
+## 2. 路径前缀
+
+如果服务端给这把 key 配了可写前缀（例如 `ci/`），上传时要把 `basePath` 设成同样的值：
+
+```js
+await client.uploadDir('dist', { basePath: 'ci', overwrite: true });
+// path = ci/index.html → key = uploads/ci/index.html
+```
+
+不设置的话，相对路径（`index.html`）不在 `ci/` 下，服务端会返回 `403 40301`。
+
+## 3. 只看不传
+
+```js
+const preview = await client.uploadDir('dist', { dryRun: true });
+console.table(preview.planned);
+// [{ file: 'index.html', size: 812 }, ...]
+```
+
+`dryRun` 不发任何 HTTP 请求，适合在 CI 里先做一次「将要上传什么」的检查。
+
+## 4. 失败重试
+
+```js
+const result = await client.uploadDir('dist', {
+  overwrite: true,
+  continueOnError: true,
+});
+
+if (result.failures.length > 0) {
+  console.error('失败文件：', result.failures.map((failure) => failure.file));
+  // 幂等：直接重跑整次上传即可，overwrite 会覆盖已成功的部分
+  process.exitCode = 1;
+}
+```
+
+上传是幂等的（`overwrite: true` 时），重跑整批比精确重试单个文件更简单。
+
+## 5. 上传后刷新 CDN（示意）
+
+包本身不提供 CDN 刷新能力，下面只是把上传结果交给刷新任务的位置示意：
+
+```js
+const result = await client.uploadDir('dist', { overwrite: true });
+
+// 只刷入口页这类文件名固定的资源，带 hash 的不用刷
+const refreshList = result.files
+  .filter((file) => file.file.endsWith('.html'))
+  .map((file) => file.url ?? file.key);
+
+await fetch(`${process.env.CDN_REFRESH_ENDPOINT}`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ urls: refreshList }),
+});
+```
+
+## 6. 回滚
+
+包只做上传，没有删除/版本切换能力。回滚 = 把上一版产物重新传一次（`overwrite: true`）：
+
+```bash
+# 从 CI artifact 或 git tag 取出旧版 dist
+git checkout v1.2.0 -- dist
+node scripts/deploy.mjs
+```
+
+前提是旧版产物还能拿到：建议在 CI 里把 `dist/` 作为 artifact 保存（见 [github-actions.md](../../../docs/guides/github-actions.md)）。
+
+## 7. 只取凭证给别的工具用
+
+```js
+const { token, key, uploadUrl } = await client.token({ path: 'dist/app.js', overwrite: true });
+
+// 交给七牛官方 SDK 或自己的上传实现
+console.log(uploadUrl, key, token);
+```
+
+注意：凭证里已经锁定了 key，上传时必须原样使用，不能改写。

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@jiseer/qiniu",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "把前端构建产物上传到七牛云存储（由服务端签发上传凭证）",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "qiniu",
+    "upload",
+    "kodo",
+    "deploy",
+    "cdn"
+  ],
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.