pi-multi-quota 0.1.0

package/src/cookie.ts

@@ -0,0 +1,148 @@
+/**
+ * Ark 控制台 cookie 解析。
+ *
+ * 依据 SPEC §2.3 的实测结论：
+ * - 请求头 `x-csrf-token` 的值与 cookie 中 `csrfToken=` 完全相同
+ *   ⇒ 用户只需维护一个 cookie 字符串，程序自行取 csrf。
+ * - `digest` 是 SSO access token（JWT），其 `exp` 约 24 小时后到期，只能人工更新。
+ *   ⇒ 只做 base64url 解码 payload，**不验签**（无密钥、也无需信任校验）。
+ *
+ * 本模块是纯函数：不发网络请求、不读配置、不写日志。
+ * 错误一律走 result 返回，绝不抛异常；message 只含错误码语义的中文短句，
+ * 严禁回显 cookie 原文。
+ */
+
+export interface ParsedArkCookie {
+  csrfToken: string;
+  /** cookie 中 AccountID 的值；缺失时 undefined。用于账号防呆比对。 */
+  accountId?: string;
+  /** digest 的 exp，epoch 毫秒；缺失或不可解析时 undefined。 */
+  digestExpMs?: number;
+  /** 相对 now 的剩余毫秒；digestExpMs 缺失时 undefined。可为负（已过期）。 */
+  expiresInMs?: number;
+}
+
+export type CookieParseResult =
+  | { ok: true; value: ParsedArkCookie }
+  | { ok: false; code: "missing-csrf" | "missing-digest" | "malformed-digest"; message: string };
+
+const CSRF_KEY = "csrfToken";
+const ACCOUNT_ID_KEY = "AccountID";
+const DIGEST_KEY = "digest";
+
+/** base64url 段的合法字符集；用它先挡掉明显非法的 payload，避免 Buffer 静默丢弃字符。 */
+const BASE64URL_SEGMENT = /^[A-Za-z0-9_-]+$/;
+
+/** cookie 值两端可能被双引号包裹（RFC 6265 允许），解析时剥掉。 */
+function unquote(value: string): string {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/** 拆 cookie 串为键值表；同名键后者覆盖前者（取最后一个）。 */
+function collectPairs(raw: string): Map<string, string> {
+  const pairs = new Map<string, string>();
+  for (const segment of raw.split(";")) {
+    const trimmed = segment.trim();
+    if (trimmed === "") continue;
+    const eq = trimmed.indexOf("=");
+    // 没有键名或没有 "=" 的碎片直接忽略，不能当成有效键值对
+    if (eq <= 0) continue;
+    const name = trimmed.slice(0, eq).trim();
+    const value = unquote(trimmed.slice(eq + 1).trim());
+    pairs.set(name, value);
+  }
+  return pairs;
+}
+
+/** 把 JWT payload 段解成 exp（epoch 秒）；任何畸形返回 undefined。 */
+function decodeJwtExpSeconds(payloadSegment: string | undefined): number | undefined {
+  if (payloadSegment === undefined || payloadSegment === "" || !BASE64URL_SEGMENT.test(payloadSegment)) {
+    return undefined;
+  }
+  const padded = payloadSegment.padEnd(Math.ceil(payloadSegment.length / 4) * 4, "=");
+  let payload: unknown;
+  try {
+    payload = JSON.parse(Buffer.from(padded, "base64url").toString("utf8"));
+  } catch {
+    return undefined;
+  }
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const exp = (payload as Record<string, unknown>)["exp"];
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return undefined;
+  return exp;
+}
+
+/**
+ * 解析 Ark 控制台 cookie。
+ *
+ * @param raw cookie 原文（浏览器复制出来的整串）
+ * @param now 当前时刻，epoch 毫秒；可注入以便测试，默认 `Date.now()`
+ */
+export function parseArkCookie(raw: string, now: number = Date.now()): CookieParseResult {
+  const pairs = collectPairs(raw);
+
+  const csrfToken = pairs.get(CSRF_KEY);
+  if (csrfToken === undefined || csrfToken === "") {
+    return {
+      ok: false,
+      code: "missing-csrf",
+      message: "cookie 中缺少 csrfToken，请复制完整的 cookie",
+    };
+  }
+
+  const digest = pairs.get(DIGEST_KEY);
+  if (digest === undefined || digest === "") {
+    return {
+      ok: false,
+      code: "missing-digest",
+      message: "cookie 中缺少 digest，请重新登录后复制完整的 cookie",
+    };
+  }
+
+  const segments = digest.split(".");
+  const expSeconds = segments.length === 3 ? decodeJwtExpSeconds(segments[1]) : undefined;
+  if (expSeconds === undefined) {
+    return {
+      ok: false,
+      code: "malformed-digest",
+      message: "cookie 的 digest 无法解析出有效期，请重新登录后复制完整的 cookie",
+    };
+  }
+
+  const digestExpMs = expSeconds * 1000;
+  const value: ParsedArkCookie = {
+    csrfToken,
+    digestExpMs,
+    expiresInMs: digestExpMs - now,
+  };
+
+  const accountId = pairs.get(ACCOUNT_ID_KEY);
+  if (accountId !== undefined && accountId !== "") {
+    value.accountId = accountId;
+  }
+
+  return { ok: true, value };
+}
+
+/** 把一段正向时长格式化为「X 天 Y 小时」/「X 小时 Y 分」/「X 分钟」/「<1 分钟」。 */
+function formatDuration(ms: number): string {
+  const totalMinutes = Math.floor(ms / 60_000);
+  if (totalMinutes < 1) return "<1 分钟";
+
+  const days = Math.floor(totalMinutes / 1_440);
+  const hours = Math.floor(totalMinutes / 60) % 24;
+  const minutes = totalMinutes % 60;
+
+  if (days > 0) return hours > 0 ? `${days} 天 ${hours} 小时` : `${days} 天`;
+  if (hours > 0) return minutes > 0 ? `${hours} 小时 ${minutes} 分` : `${hours} 小时`;
+  return `${minutes} 分钟`;
+}
+
+/** 人可读剩余时间，例如 "3 小时 12 分" / "已过期 20 分钟" / "<1 分钟"。 */
+export function describeExpiry(ms: number): string {
+  const text = formatDuration(Math.abs(ms));
+  return ms < 0 ? `已过期 ${text}` : text;
+}

package/src/footer.ts

@@ -0,0 +1,216 @@
+/**
+ * footer 单行渲染 / 详情渲染 + 宽度预算裁剪（纯函数，无 IO）。
+ * 契约见 SPEC.md §3.2（数据模型）；错误短原因映射见本文件下方的 ERROR_TEXTS。
+ * 未登记的 error code 只展示 code 本身，绝不回显 QuotaError.message。
+ */
+
+import type { AccountReport, WindowLevel } from "./types.js";
+
+export interface FooterOptions {
+  /** 可见字符上限（按 Unicode 码点计），默认 60。 */
+  maxWidth?: number;
+  /** 当前活跃账号 id（多账号时用于裁剪优先级）。 */
+  currentAccountId?: string;
+}
+
+/** 默认宽度预算（SPEC §4.1）/ 账号段落分隔符 / 截断收尾标记。 */
+const DEFAULT_MAX_WIDTH = 60;
+const SEGMENT_SEPARATOR = " · ";
+const ELLIPSIS = "…";
+
+/** footer 的窗口标签：session→5h、weekly→wk、monthly→mo。 */
+const WINDOW_LABELS: Record<WindowLevel, string> = {
+  session: "5h",
+  weekly: "wk",
+  monthly: "mo",
+};
+
+/** 窗口渲染顺序固定为 5h / wk / mo，与 SPEC §4.1 的示例一致。 */
+const WINDOW_ORDER: readonly WindowLevel[] = ["session", "weekly", "monthly"];
+
+/** 错误码 → 可展示短句（footer 侧的唯一映射表）。 */
+const ERROR_TEXTS: Record<string, string> = {
+  "missing-credential": "未配置",
+  NotLogin: "cookie 过期",
+  InvalidCSRFToken: "cookie 不完整",
+  "unknown-shape": "接口变更",
+  network: "网络错误",
+  timeout: "超时",
+};
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+
+/** footer 的百分比取整（SPEC 示例：12.5 → 13，100 → 100）。 */
+function formatPercent(percent: number): string {
+  return `${Math.round(percent)}%`;
+}
+
+/** ERROR_TEXTS 映射：已知 code 用展示文本，`http-<status>` 用 `HTTP <status>`，其余原样返回 code。 */
+function errorReason(code: string): string {
+  if (code.startsWith("http-")) {
+    const status = code.slice("http-".length);
+    return status.length > 0 ? `HTTP ${status}` : code;
+  }
+  return ERROR_TEXTS[code] ?? code;
+}
+
+/** 币种前缀：CNY→¥、USD→$、其余用「代码 + 空格」。 */
+function currencyPrefix(currency: string): string {
+  if (currency === "CNY") return "¥";
+  if (currency === "USD") return "$";
+  return `${currency} `;
+}
+
+/** 可见宽度：按 Unicode 码点计，避免 UTF-16 代理对造成偏差。 */
+function visibleWidth(text: string): number {
+  return Array.from(text).length;
+}
+
+function truncateToWidth(text: string, maxWidth: number): string {
+  const chars = Array.from(text);
+  if (chars.length <= maxWidth) return text;
+  return `${chars.slice(0, Math.max(maxWidth - 1, 0)).join("")}${ELLIPSIS}`;
+}
+
+/** 段落主体：windows 类为各窗口百分比，balance 类为各币种金额。 */
+function segmentBody(report: AccountReport): string[] {
+  if (report.kind === "balance") {
+    return (report.balances ?? []).map((entry) => `${currencyPrefix(entry.currency)}${entry.total}`);
+  }
+  const parts: string[] = [];
+  for (const level of WINDOW_ORDER) {
+    const window = (report.windows ?? []).find((candidate) => candidate.level === level);
+    if (window === undefined) continue;
+    parts.push(`${WINDOW_LABELS[level]} ${formatPercent(window.percent)}`);
+  }
+  return parts;
+}
+
+/** 段落名的 stale 前缀。 */
+function segmentName(report: AccountReport): string {
+  return report.stale === true ? `~${report.displayName}` : report.displayName;
+}
+
+/**
+ * 完整形态段落。刻意不含重置时间（resetsAt）—— 倒计时只由 renderDetail 渲染，
+ * 因此宽度裁剪的第一级（先砍倒计时）在 footer 里天然成立，无字段可砍。
+ */
+function renderSegment(report: AccountReport): string {
+  const hasData =
+    (report.windows?.length ?? 0) > 0 || (report.balances?.length ?? 0) > 0;
+  // stale 数据优先于错误展示：SPEC §5 要求网络失败时保留上次成功数据，
+  // 错误原因改由 renderDetail 呈现。否则 SC7（断网后仍显示上次数据）会退化成丢数据。
+  if (report.error !== undefined && !hasData) {
+    return `${report.displayName} ✗ ${errorReason(report.error.code)}`;
+  }
+  const body = segmentBody(report);
+  if (body.length === 0) return segmentName(report);
+  return `${segmentName(report)} ${body.join(" ")}`;
+}
+
+/** 最简形态段落（裁剪第三级）：只有 windows 段还能再退化，错误段与余额段本身已是最短。 */
+function renderCompactSegment(report: AccountReport): string {
+  if (report.error !== undefined || report.kind === "balance") return renderSegment(report);
+  const windows = report.windows ?? [];
+  const window =
+    windows.find((candidate) => candidate.level === "monthly") ?? windows[windows.length - 1];
+  if (window === undefined) return segmentName(report);
+  return `${segmentName(report)} ${WINDOW_LABELS[window.level]} ${formatPercent(window.percent)}`;
+}
+
+/** 单行 footer 文本。空数组 → 返回 ""。 */
+export function renderFooter(reports: AccountReport[], opts: FooterOptions = {}): string {
+  if (reports.length === 0) return "";
+  const maxWidth = opts.maxWidth ?? DEFAULT_MAX_WIDTH;
+  if (maxWidth <= 0) return "";
+
+  const full = reports.map(renderSegment).join(SEGMENT_SEPARATOR);
+  if (visibleWidth(full) <= maxWidth) return full;
+
+  // 裁剪顺序（SPEC §4.1）：
+  //   (a) 砍重置倒计时 —— footer 段落不含该字段，天然满足；
+  //   (b) 全量 compact —— 优先保住**全部账号**（即使每段只剩一个数字）；
+  //   (c) 退到只留当前账号（完整形态）；
+  //   (d) 当前账号 compact；(e) 仍超宽 → 截断。
+  // (b) 优先于 (c) 的理由：知道「两个账号各自还剩多少」
+  // 比「一个账号的三个窗口」对切换决策更有价值（且原逻辑从不尝试 b，会白白丢掉账号）。
+  const currentAccountId = opts.currentAccountId;
+  const currentReports =
+    currentAccountId === undefined
+      ? []
+      : reports.filter((report) => report.accountId === currentAccountId);
+
+  const compactAll = reports.map(renderCompactSegment).join(SEGMENT_SEPARATOR);
+
+  if (currentReports.length > 0) {
+    if (visibleWidth(compactAll) <= maxWidth) return compactAll;
+    const trimmed = currentReports.map(renderSegment).join(SEGMENT_SEPARATOR);
+    if (visibleWidth(trimmed) <= maxWidth) return trimmed;
+    const compact = currentReports.map(renderCompactSegment).join(SEGMENT_SEPARATOR);
+    if (visibleWidth(compact) <= maxWidth) return compact;
+    return truncateToWidth(compact, maxWidth);
+  }
+
+  // 无 currentAccountId 或未命中（OpenCode/DeepSeek 恒定如此，Ark 未绑定账号时也是）：
+  // 先逐段 compact 再截断，避免直接砍成「Ark-A 5h 13% wk 37…」这种半截形态。
+  if (visibleWidth(compactAll) <= maxWidth) return compactAll;
+  return truncateToWidth(compactAll, maxWidth);
+}
+
+/** 重置倒计时：<1 分钟 → "<1m"；<1 天 → "4h 12m"；否则 "2d 3h"。 */
+function formatCountdown(resetsAtSec: number, nowMs: number): string {
+  const remainingMs = resetsAtSec * 1000 - nowMs;
+  if (remainingMs < MINUTE_MS) return "<1m";
+  if (remainingMs >= DAY_MS) {
+    const days = Math.floor(remainingMs / DAY_MS);
+    const hours = Math.floor((remainingMs % DAY_MS) / HOUR_MS);
+    return `${days}d ${hours}h`;
+  }
+  const hours = Math.floor(remainingMs / HOUR_MS);
+  const minutes = Math.floor((remainingMs % HOUR_MS) / MINUTE_MS);
+  return `${hours}h ${minutes}m`;
+}
+
+function detailLines(report: AccountReport, nowMs: number): string[] {
+  const staleSuffix = report.stale === true ? "（上次成功数据）" : "";
+  const lines = [`${report.displayName} (${report.sourceId}) ${staleSuffix}`.trimEnd()];
+
+  if (report.error !== undefined) {
+    lines.push(`  ✗ ${report.error.code} · ${errorReason(report.error.code)}`);
+    return lines;
+  }
+
+  if (report.kind === "balance") {
+    for (const entry of report.balances ?? []) {
+      const parts = [`总额 ${entry.total}`];
+      if (entry.granted !== undefined) parts.push(`赠送 ${entry.granted}`);
+      if (entry.toppedUp !== undefined) parts.push(`充值 ${entry.toppedUp}`);
+      lines.push(`  ${entry.currency}  ${parts.join("  ")}`);
+    }
+    return lines;
+  }
+
+  const windows = report.windows ?? [];
+  for (const level of WINDOW_ORDER) {
+    const window = windows.find((candidate) => candidate.level === level);
+    if (window === undefined) continue;
+    let line = `  ${level}  已用 ${window.percent.toFixed(1)}%`;
+    if (window.resetsAt !== undefined) {
+      line += `  重置于 ${formatCountdown(window.resetsAt, nowMs)} 后`;
+    }
+    lines.push(line);
+  }
+  return lines;
+}
+
+/** /quota 详情视图：逐行文本，含重置倒计时。空数组 → 返回 []。 */
+export function renderDetail(reports: AccountReport[]): string[] {
+  const nowMs = Date.now();
+  const lines: string[] = [];
+  for (const report of reports) {
+    lines.push(...detailLines(report, nowMs));
+  }
+  return lines;
+}