pi-multi-quota 0.1.0

package/src/sources/ark.ts

@@ -0,0 +1,257 @@
+/**
+ * Ark（火山引擎 Coding Plan）额度适配器。
+ *
+ * 端点、响应结构（实测所得，数值已合成）与失败码见 SPEC.md §2.3。
+ * Ark 特例：**鉴权失败时 HTTP 仍是 200**，失败信息在 body 的 `ResponseMetadata.Error.Code` 里，
+ * 只看状态码会把失败误判成成功。
+ * 零运行时依赖；网络调用经 `fetchImpl` 注入；不写日志，error.message 只含中文短句、不回显凭据与响应体。
+ */
+import { parseArkCookie } from "../cookie.js";
+import { redact } from "../config.js";
+import type { ArkAccountConfig } from "../config.js";
+import type { FetchOptions } from "./opencode.js";
+import type { AccountReport, QuotaWindow, WindowLevel } from "../types.js";
+
+/** Ark Coding Plan 用量端点。 */
+export const ARK_USAGE_URL =
+  "https://console.volcengine.com/api/top/ark/cn-beijing/2024-01-01/GetCodingPlanUsage?";
+
+/** 唯一允许携带凭据的 host（SPEC §6）。 */
+export const ARK_ALLOWED_HOST = "console.volcengine.com";
+
+/** 默认超时，与 src/sources/opencode.ts 一致。 */
+const DEFAULT_TIMEOUT_MS = 20000;
+
+/** 响应 Level → 内部窗口粒度；表外的 Level 视为接口变更：跳过并记 note。 */
+const LEVELS: ReadonlyMap<string, WindowLevel> = new Map<string, WindowLevel>([
+  ["session", "session"],
+  ["weekly", "weekly"],
+  ["monthly", "monthly"],
+]);
+
+/** 已知失败码 → 可安全展示的中文短句；其余码原样透传，message 走通用短句。 */
+const KNOWN_ERROR_MESSAGES: ReadonlyMap<string, string> = new Map([
+  ["NotLogin", "cookie 已过期或无效"],
+  ["InvalidCSRFToken", "cookie 不完整"],
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
+/** 构造失败报告：error 只含错误码与人可读短句。 */
+function failure(
+  accountId: string,
+  displayName: string,
+  fetchedAt: number,
+  code: string,
+  message: string,
+): AccountReport {
+  return {
+    accountId,
+    displayName,
+    sourceId: "ark",
+    kind: "windows",
+    fetchedAt,
+    error: { code, message },
+  };
+}
+
+/**
+ * URL host 白名单校验（SPEC §6）：发送任何凭据**之前**必须先过这一关。
+ * URL 不可解析、或 host（含端口）与 `ARK_ALLOWED_HOST` 不完全相等，都返回 false。
+ */
+export function isArkAllowedUrl(url: string): boolean {
+  try {
+    return new URL(url).host === ARK_ALLOWED_HOST;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `account.id` → 展示名："ark-a" → "Ark-A"。
+ * 契约类型 `ArkAccountConfig`（见 ../config.ts）只有 id/provider/cookie，没有 displayName，
+ * 故由 id 派生；若需其他写法，调用方可在展示层覆盖 report.displayName。
+ */
+function displayNameFor(accountId: string): string {
+  const parts = accountId.split(/[-_]+/).filter((part) => part !== "");
+  if (parts.length === 0) return accountId;
+  return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("-");
+}
+
+/**
+ * 纯解析：GetCodingPlanUsage payload → AccountReport。
+ *
+ * `ResponseMetadata.Error` 存在即失败（HTTP 200 也可能是失败）；`QuotaUsage` 里
+ * Level 未知 / Percent 非法 / Level 重复的条目跳过并记 note；`ResetTimestamp` 已是 epoch 秒，直接使用。
+ */
+export function parseArkUsage(
+  payload: unknown,
+  fetchedAt: number,
+  accountId: string,
+  displayName: string,
+): AccountReport {
+  const fail = (code: string, message: string): AccountReport =>
+    failure(accountId, displayName, fetchedAt, code, message);
+  const changed = (): AccountReport => fail("unknown-shape", "接口变更");
+
+  const root = asRecord(payload);
+  if (root === undefined) return changed();
+
+  const metadata = asRecord(root["ResponseMetadata"]);
+  const error = metadata === undefined ? undefined : asRecord(metadata["Error"]);
+  if (error !== undefined) {
+    const code = error["Code"];
+    if (typeof code !== "string" || code === "") return changed();
+    const known = KNOWN_ERROR_MESSAGES.get(code);
+    if (known !== undefined) return fail(code, known);
+    // 未知 code 归入 unknown-shape，而不是把原始 code 塞进 QuotaError.code ——
+    // 否则 footer 会展示出 ERROR_TEXTS 表之外的英文错误码。
+    // 原始 code 经脱敏后记入 notes，保留排查线索。
+    const report = fail("unknown-shape", "接口变更");
+    return { ...report, notes: [`Ark 返回未知错误码 ${redact(code)}`] };
+  }
+
+  const result = asRecord(root["Result"]);
+  const rawUsage = result === undefined ? undefined : result["QuotaUsage"];
+  if (!Array.isArray(rawUsage)) return changed();
+
+  const windows: QuotaWindow[] = [];
+  const notes: string[] = [];
+
+  for (const item of rawUsage) {
+    const entry = asRecord(item);
+    if (entry === undefined) {
+      notes.push("存在结构异常的窗口条目，已跳过");
+      continue;
+    }
+    const rawLevel = entry["Level"];
+    const level = typeof rawLevel === "string" ? LEVELS.get(rawLevel) : undefined;
+    if (level === undefined) {
+      notes.push(`未知窗口 Level "${redact(String(rawLevel))}"，已跳过`);
+      continue;
+    }
+    if (windows.some((existing) => existing.level === level)) {
+      notes.push(`窗口 ${level} 重复出现，已跳过`);
+      continue;
+    }
+    const percent = entry["Percent"];
+    if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0) {
+      notes.push(`窗口 ${level} 的 Percent 不是非负有限数字，已跳过`);
+      continue;
+    }
+    const window: QuotaWindow = { level, percent };
+    const resetTimestamp = entry["ResetTimestamp"];
+    // epoch 秒，不做毫秒换算
+    if (typeof resetTimestamp === "number" && Number.isFinite(resetTimestamp)) {
+      window.resetsAt = resetTimestamp;
+    }
+    windows.push(window);
+  }
+
+  if (windows.length === 0) return changed();
+
+  const report: AccountReport = {
+    accountId,
+    displayName,
+    sourceId: "ark",
+    kind: "windows",
+    windows,
+    fetchedAt,
+  };
+  if (notes.length > 0) report.notes = notes;
+  return report;
+}
+
+/**
+ * 查询某个 Ark 账号的额度。
+ * cookie 缺失 / 白名单不通过 / 网络异常 / 超时 / 非 2xx / 响应畸形，一律返回带 error 的报告，不抛异常。
+ */
+export async function fetchArkUsage(
+  account: ArkAccountConfig,
+  opts: FetchOptions = {},
+): Promise<AccountReport> {
+  const fetchedAt = Date.now();
+  const displayName = displayNameFor(account.id);
+  const fail = (code: string, message: string): AccountReport =>
+    failure(account.id, displayName, fetchedAt, code, message);
+
+  if (typeof account.cookie !== "string" || account.cookie.trim() === "") {
+    return fail("missing-credential", "未配置 Ark cookie");
+  }
+
+  // host 白名单在解析 cookie 与发请求之前：不匹配绝不发送凭据
+  if (!isArkAllowedUrl(ARK_USAGE_URL)) {
+    return fail("blocked-host", "请求目标不在白名单内，已阻止");
+  }
+
+  // x-csrf-token 由 cookie 内联解析得到（SPEC §2.3）：用户只维护一个 cookie 字符串
+  const parsed = parseArkCookie(account.cookie);
+  if (!parsed.ok) return fail("InvalidCSRFToken", parsed.message);
+
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs =
+    typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+      ? opts.timeoutMs
+      : DEFAULT_TIMEOUT_MS;
+
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  const externalSignal = opts.signal;
+  const onExternalAbort = (): void => controller.abort();
+  if (externalSignal !== undefined) {
+    if (externalSignal.aborted) controller.abort();
+    else externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+  }
+
+  try {
+    let response: Response;
+    try {
+      response = await fetchImpl(ARK_USAGE_URL, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-csrf-token": parsed.value.csrfToken,
+          cookie: account.cookie,
+          Accept: "application/json",
+        },
+        body: "{}",
+        redirect: "error", // 拒绝重定向，防止凭据被转发到白名单外的 host（SPEC §6）
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (timedOut) return fail("timeout", `Ark 接口请求超时（${timeoutMs}ms）`);
+      if (isAbortError(err)) return fail("network", "Ark 请求已取消");
+      return fail("network", "Ark 网络请求失败");
+    }
+
+    if (!response.ok) return fail(`http-${response.status}`, `Ark 接口返回 HTTP ${response.status}`);
+
+    let payload: unknown;
+    try {
+      payload = await response.json();
+    } catch {
+      // 超时可能落在 body 读取阶段（fetch 已 resolve、body 未读完），
+      // 此时应报 timeout，而非误报「接口变更」
+      if (timedOut || controller.signal.aborted) {
+        return fail("timeout", `Ark 响应读取超时（${timeoutMs}ms）`);
+      }
+      return fail("unknown-shape", "响应不是合法 JSON");
+    }
+
+    return parseArkUsage(payload, fetchedAt, account.id, displayName);
+  } finally {
+    clearTimeout(timer);
+    externalSignal?.removeEventListener("abort", onExternalAbort);
+  }
+}

package/src/sources/deepseek.ts

@@ -0,0 +1,189 @@
+/**
+ * DeepSeek 余额适配器。
+ *
+ * 数据模型见 SPEC.md §3.2；响应结构为实测所得，数值已合成（SPEC.md §2.2）。
+ * 硬约束：金额（total / granted / toppedUp）全程保持接口返回的**字符串**，
+ * 不得转 Number —— 转 float 会丢精度（SPEC §2.2 / §3.2）。
+ */
+
+import type { FetchOptions } from "./opencode.js";
+import type { AccountReport, BalanceEntry } from "../types.js";
+
+/** DeepSeek 余额查询端点。 */
+export const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
+
+/** DeepSeek 在 AccountReport 中的账号 id。 */
+export const DEEPSEEK_ACCOUNT_ID = "deepseek";
+
+const DISPLAY_NAME = "DeepSeek";
+
+/** 默认超时，与 src/sources/opencode.ts 保持一致。 */
+const DEFAULT_TIMEOUT_MS = 20000;
+
+/** 构造失败报告：error 只含错误码与人可读短句，不含凭据与响应体。 */
+function failure(fetchedAt: number, code: string, message: string): AccountReport {
+  return {
+    accountId: DEEPSEEK_ACCOUNT_ID,
+    displayName: DISPLAY_NAME,
+    sourceId: "deepseek",
+    kind: "balance",
+    fetchedAt,
+    error: { code, message },
+  };
+}
+
+/** 类型守卫：非对象（含 null 与数组）返回 undefined。 */
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+/** 字段守卫：只接受非空字符串，数字形态一律不认（避免隐式精度损失）。 */
+function asNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.trim() === "") return undefined;
+  return value;
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
+/**
+ * 纯解析：DeepSeek `/user/balance` payload → AccountReport。
+ *
+ * - `is_available === false`：账户不可用，返回带 error 且**不带 balances** 的报告。
+ * - `balance_infos` 为空或全部结构异常：返回 error（绝不显示 ¥0.00）。
+ * - 多币种各自一条 BalanceEntry，不相加、不换算。
+ *
+ * 畸形 payload 不抛异常，统一走 error 报告，便于 registry 直接展示。
+ */
+export function parseDeepSeekBalance(payload: unknown, fetchedAt: number): AccountReport {
+  const root = asRecord(payload);
+  if (root === undefined) {
+    return failure(fetchedAt, "unknown-shape", "DeepSeek 余额响应不是对象");
+  }
+
+  if (root["is_available"] === false) {
+    return failure(fetchedAt, "http-402", "DeepSeek 账户当前不可用（余额不足或账户已停用）");
+  }
+
+  const rawInfos = root["balance_infos"];
+  if (!Array.isArray(rawInfos)) {
+    return failure(fetchedAt, "unknown-shape", "DeepSeek 余额响应缺少 balance_infos 数组");
+  }
+
+  const balances: BalanceEntry[] = [];
+  let skipped = 0;
+
+  for (const rawInfo of rawInfos) {
+    const info = asRecord(rawInfo);
+    if (info === undefined) {
+      skipped += 1;
+      continue;
+    }
+    const currency = asNonEmptyString(info["currency"]);
+    const total = asNonEmptyString(info["total_balance"]);
+    if (currency === undefined || total === undefined) {
+      skipped += 1;
+      continue;
+    }
+
+    const entry: BalanceEntry = { currency, total };
+    const granted = asNonEmptyString(info["granted_balance"]);
+    if (granted !== undefined) entry.granted = granted;
+    const toppedUp = asNonEmptyString(info["topped_up_balance"]);
+    if (toppedUp !== undefined) entry.toppedUp = toppedUp;
+    balances.push(entry);
+  }
+
+  if (balances.length === 0) {
+    return failure(fetchedAt, "unknown-shape", "DeepSeek 余额响应没有可用的余额记录");
+  }
+
+  const report: AccountReport = {
+    accountId: DEEPSEEK_ACCOUNT_ID,
+    displayName: DISPLAY_NAME,
+    sourceId: "deepseek",
+    kind: "balance",
+    fetchedAt,
+    balances,
+  };
+  if (skipped > 0) {
+    report.notes = [`${skipped} 条余额记录结构异常，已跳过`];
+  }
+  return report;
+}
+
+/**
+ * 拉取 DeepSeek 余额。
+ * 网络异常 / 超时 / 非 2xx / 响应畸形一律返回带 error 的 AccountReport，不抛异常。
+ */
+export async function fetchDeepSeekBalance(
+  apiKey: string,
+  opts: FetchOptions = {},
+): Promise<AccountReport> {
+  const fetchedAt = Date.now();
+
+  if (typeof apiKey !== "string" || apiKey.trim() === "") {
+    return failure(fetchedAt, "missing-credential", "未配置 DeepSeek API key");
+  }
+
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+
+  const externalSignal = opts.signal;
+  const onExternalAbort = () => controller.abort();
+  if (externalSignal !== undefined) {
+    if (externalSignal.aborted) controller.abort();
+    else externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+  }
+
+  try {
+    let response: Response;
+    try {
+      response = await fetchImpl(DEEPSEEK_BALANCE_URL, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          Accept: "application/json",
+        },
+        redirect: "error",
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (timedOut) {
+        return failure(fetchedAt, "timeout", `DeepSeek 接口请求超时（${timeoutMs}ms）`);
+      }
+      if (isAbortError(err)) {
+        return failure(fetchedAt, "network", "DeepSeek 请求已取消");
+      }
+      return failure(fetchedAt, "network", "DeepSeek 网络请求失败");
+    }
+
+    if (!response.ok) {
+      return failure(fetchedAt, `http-${response.status}`, `DeepSeek 接口返回 HTTP ${response.status}`);
+    }
+
+    let payload: unknown;
+    try {
+      payload = await response.json();
+    } catch {
+      if (timedOut || controller.signal.aborted) {
+        return failure(fetchedAt, "timeout", `DeepSeek 响应读取超时（${timeoutMs}ms）`);
+      }
+      return failure(fetchedAt, "unknown-shape", "DeepSeek 响应不是合法 JSON");
+    }
+
+    return parseDeepSeekBalance(payload, fetchedAt);
+  } finally {
+    clearTimeout(timer);
+    externalSignal?.removeEventListener("abort", onExternalAbort);
+  }
+}

package/src/sources/opencode.ts

@@ -0,0 +1,186 @@
+/**
+ * OpenCode Go（Zen）额度适配器。
+ *
+ * 端点与响应结构见 SPEC §2.1，错误码语义与展示约束见 SPEC §5 / §6。
+ * 零运行时依赖；网络调用通过 `fetchImpl` 注入，测试不触网。
+ */
+import { redact } from "../config.js";
+import type { AccountReport, QuotaWindow, WindowLevel } from "../types.js";
+
+export const OPENCODE_USAGE_URL = "https://opencode.ai/zen/go/v1/usage";
+export const OPENCODE_ACCOUNT_ID = "opencode";
+
+/** fetch 未传 timeoutMs 时的默认超时。 */
+const DEFAULT_TIMEOUT_MS = 20000;
+
+/** 响应中的窗口字段 → 内部窗口粒度。顺序即 windows 数组的输出顺序。 */
+const WINDOW_FIELDS: ReadonlyArray<readonly [string, WindowLevel]> = [
+  ["rolling", "session"],
+  ["weekly", "weekly"],
+  ["monthly", "monthly"],
+];
+
+/** 视为可用的窗口状态，其余状态一律降级为 note。 */
+const USABLE_STATUSES: ReadonlySet<string> = new Set(["ok", "rate-limited"]);
+
+export interface FetchOptions {
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** ISO 时间字符串 → epoch 秒；不可解析时返回 undefined（该窗口不带重置时间）。 */
+function toEpochSeconds(value: unknown): number | undefined {
+  if (typeof value !== "string") return undefined;
+  const ms = Date.parse(value);
+  if (!Number.isFinite(ms)) return undefined;
+  return Math.floor(ms / 1000);
+}
+
+/** 从错误对象取可安全展示的短句；绝不回显原始响应体。 */
+function messageOf(err: unknown): string {
+  return err instanceof Error && err.message !== "" ? err.message : "用量数据结构无法识别";
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+}
+
+/** 构造失败报告（不含凭据、不含响应体）。 */
+function errorReport(code: string, message: string, fetchedAt: number): AccountReport {
+  return {
+    accountId: OPENCODE_ACCOUNT_ID,
+    displayName: "Zen",
+    sourceId: "opencode",
+    kind: "windows",
+    fetchedAt,
+    error: { code, message },
+  };
+}
+
+/**
+ * 纯解析：OpenCode `/v1/usage` 响应 → AccountReport。
+ *
+ * 窗口映射：rolling → session，weekly → weekly，monthly → monthly。
+ * 状态非 ok / rate-limited 的窗口跳过并记入 notes；percent 非非负有限数字的窗口同样跳过。
+ * 响应结构不可识别或三个窗口全部不可用时抛 Error（message 不含凭据）。
+ */
+export function parseOpenCodeUsage(payload: unknown, fetchedAt: number): AccountReport {
+  const usage = isRecord(payload) ? payload.usage : undefined;
+  if (!isRecord(usage)) {
+    throw new Error("响应缺少 usage 对象");
+  }
+
+  const windows: QuotaWindow[] = [];
+  const notes: string[] = [];
+
+  for (const [field, level] of WINDOW_FIELDS) {
+    const raw = usage[field];
+    if (!isRecord(raw)) {
+      notes.push(`窗口 ${field} 缺失或结构异常，已跳过`);
+      continue;
+    }
+    const status = raw.status;
+    if (typeof status !== "string" || !USABLE_STATUSES.has(status)) {
+      notes.push(`窗口 ${field} 状态为 ${typeof status === "string" ? redact(status) : "缺失"}，已跳过`);
+      continue;
+    }
+    const percent = raw.percent;
+    if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0) {
+      notes.push(`窗口 ${field} 的 percent 不是非负有限数字，已跳过`);
+      continue;
+    }
+    const window: QuotaWindow = { level, percent };
+    const resetsAt = toEpochSeconds(raw.resetsAt);
+    if (resetsAt !== undefined) window.resetsAt = resetsAt;
+    windows.push(window);
+  }
+
+  if (windows.length === 0) {
+    throw new Error("响应中没有任何可用窗口");
+  }
+
+  const report: AccountReport = {
+    accountId: OPENCODE_ACCOUNT_ID,
+    displayName: "Zen",
+    sourceId: "opencode",
+    kind: "windows",
+    windows,
+    fetchedAt,
+  };
+  if (notes.length > 0) report.notes = notes;
+  return report;
+}
+
+/**
+ * 查询 OpenCode Go 额度。
+ *
+ * 网络异常 / 超时 / 非 2xx / 响应结构不可识别一律返回带 error 的 AccountReport，不抛异常。
+ */
+export async function fetchOpenCodeUsage(apiKey: string, opts: FetchOptions = {}): Promise<AccountReport> {
+  const fetchedAt = Date.now();
+  if (typeof apiKey !== "string" || apiKey === "") {
+    return errorReport("missing-credential", "未配置 OpenCode API key", fetchedAt);
+  }
+
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs =
+    typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+      ? opts.timeoutMs
+      : DEFAULT_TIMEOUT_MS;
+
+  // 外部 signal 与超时合并到同一个 AbortController：任一触发都中止请求。
+  const controller = new AbortController();
+  const external = opts.signal;
+  const onExternalAbort = (): void => controller.abort();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  if (external !== undefined) {
+    if (external.aborted) controller.abort();
+    else external.addEventListener("abort", onExternalAbort, { once: true });
+  }
+  const cleanup = (): void => {
+    clearTimeout(timer);
+    external?.removeEventListener("abort", onExternalAbort);
+  };
+
+  try {
+    const response = await fetchImpl(OPENCODE_USAGE_URL, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+      // 拒绝跟随重定向，防止凭据被转发到白名单外的 host（SPEC §6）。
+      redirect: "error",
+      signal: controller.signal,
+    });
+
+    if (controller.signal.aborted) {
+      return errorReport("timeout", "请求超时", fetchedAt);
+    }
+    if (!response.ok) {
+      return errorReport(`http-${response.status}`, `HTTP ${response.status}`, fetchedAt);
+    }
+
+    let payload: unknown;
+    try {
+      payload = await response.json();
+    } catch {
+      return errorReport("unknown-shape", "响应不是合法 JSON", fetchedAt);
+    }
+
+    try {
+      return parseOpenCodeUsage(payload, fetchedAt);
+    } catch (err) {
+      return errorReport("unknown-shape", messageOf(err), fetchedAt);
+    }
+  } catch (err) {
+    if (controller.signal.aborted || isAbortError(err)) {
+      return errorReport("timeout", "请求超时", fetchedAt);
+    }
+    return errorReport("network", "网络请求失败", fetchedAt);
+  } finally {
+    cleanup();
+  }
+}

package/src/types.ts

@@ -0,0 +1,64 @@
+/**
+ * pi-multi-quota 核心类型定义。
+ *
+ * 这些类型是跨模块的接口契约，与 SPEC.md §3.2 的数据模型一一对应。
+ * 任何修改必须先更新 SPEC.md §3.2，再改本文件。
+ */
+
+/** 额度窗口的粒度。三个数据源统一映射到这三档。 */
+export type WindowLevel = "session" | "weekly" | "monthly";
+
+/** 数据源标识。 */
+export type SourceId = "ark" | "opencode" | "deepseek";
+
+/** 单个额度窗口。 */
+export interface QuotaWindow {
+  level: WindowLevel;
+  /** 已用百分比，0-100。 */
+  percent: number;
+  /** 重置时间，epoch 秒。缺失表示该窗口不含重置信息。 */
+  resetsAt?: number;
+}
+
+/**
+ * 余额条目（pay-as-you-go 类数据源）。
+ * 金额全程保持字符串，禁止转 float —— 转换会丢精度。
+ */
+export interface BalanceEntry {
+  /** 币种，例如 "CNY" / "USD"。 */
+  currency: string;
+  /** 总余额，精确保留原始字符串。 */
+  total: string;
+  /** 赠送余额。 */
+  granted?: string;
+  /** 充值余额。 */
+  toppedUp?: string;
+}
+
+/**
+ * 归一化错误。message 必须是可安全展示的文本：
+ * 只允许包含错误码，严禁包含 cookie、API key 或原始响应体。
+ */
+export interface QuotaError {
+  code: string;
+  message: string;
+}
+
+/** 单个账号的一次查询结果。 */
+export interface AccountReport {
+  /** 账号唯一标识，例如 "ark-a" / "ark-b" / "opencode" / "deepseek"。 */
+  accountId: string;
+  /** 展示名，例如 "Ark-A"。 */
+  displayName: string;
+  sourceId: SourceId;
+  kind: "windows" | "balance";
+  windows?: QuotaWindow[];
+  balances?: BalanceEntry[];
+  /** 抓到数据的时刻，epoch 毫秒。 */
+  fetchedAt: number;
+  error?: QuotaError;
+  /** true 表示展示的是上次成功的数据（本次查询失败）。 */
+  stale?: boolean;
+  /** 非致命提示，例如某个窗口 status 未知。 */
+  notes?: string[];
+}