@chainlesschain/personal-data-hub 0.4.4 → 0.4.5

package/lib/adapters/finance-alipay/api-client.js

@@ -1,16 +1,83 @@
 /**
- * AlipayApiClient — FAMILY-23 v0.1 cookie-scrape（无签名）。
+ * AlipayApiClient — FAMILY-23 支付宝采集客户端。
  *
- * 支付宝 web cookie uid 不易直取（多走 session token）；v0.1 best-effort 从
- * alipay_uid / userId / loginUserId 抽数字 uid。账单/交易明细 走 v0.2（mobilegw
- * 接口 + 签名）。**高敏感**（涉资金）— 上行受 telemetry level + quiet hours 闸。
+ * 支付宝 web cookie uid 不易直取（多走 session token）；v0.1 仅 cookie-scrape
+ * （extractUid，best-effort 从 alipay_uid / userId / loginUserId 抽数字 uid）。
+ * **v0.2 接通 live 账单 fetcher**：cookie（支付宝会话）经 mobilegw（mgw.htm）
+ * 拉账单/交易明细（商户 / 金额 / 收支方向 / 时间）。
+ *
+ * ⚠️ **best-effort**：mobilegw 接口无公开稳定文档，且生产环境多数 operationType
+ *    需要 app 级签名 — 本客户端留 `signProvider` seam（`buildHeaders({url,
+ *    operationType, body}) → headers`，镜像仓内 SignProvider 模式），未注入时
+ *    发未签名请求（服务端可能拒，错误经 lastError 透出）。端点/operationType/
+ *    字段名按社区逆向常见形态实现 + 多字段名兼容（pick 回退），**未经真实
+ *    支付宝登录态实地验证**，漂移时改常量 / opts 覆盖。
+ * ⚠️ **高敏感**（涉资金）— 上行受 telemetry level + quiet hours 闸（adapter 层
+ *    sensitivity: "high"）。
+ *
+ * profile 不走接口：live 模式 uid 直接由 extractUid 从 cookie 抽（抽不到则只
+ *  出账单不出 profile）— 避免再引入一个未经验证的 user-info operationType。
  */
 "use strict";
 
+const { pick, toEpochMs } = require("../_live-json-helpers");
+
+const DEFAULT_BASE_URL = "https://mobilegw.alipay.com";
+// 端点 / operationType（best-effort，可经 opts 覆盖）。
+const PATH_MGW = "/mgw.htm";
+const OP_BILL_LIST = "alipay.mobile.bill.list";
+
+const BROWSER_UA =
+  "Mozilla/5.0 (Linux; Android 12) AppleWebKit/537.36 (KHTML, like Gecko) " +
+  "Chrome/114.0.0.0 Mobile Safari/537.36 AlipayClient/10.5.0";
+
+/**
+ * 金额（元，number 或 "12.50"/"-12.50"/"+12.50" 字符串）→ { amountFen, sign }。
+ * amountFen 取绝对值整数分；sign -1/0/1（账单负数=支出）。解析失败返 null。
+ */
+function parseAmountYuan(v) {
+  let n;
+  if (Number.isFinite(v)) {
+    n = v;
+  } else if (typeof v === "string") {
+    const cleaned = v.replace(/[¥￥,\s]/g, "");
+    if (!/^[+-]?\d+(\.\d+)?$/.test(cleaned)) return null;
+    n = parseFloat(cleaned);
+  } else {
+    return null;
+  }
+  if (!Number.isFinite(n)) return null;
+  return {
+    amountFen: Math.round(Math.abs(n) * 100),
+    sign: n > 0 ? 1 : n < 0 ? -1 : 0,
+  };
+}
+
+/**
+ * 收支方向：显式字段（"收入"/"in"/"INCOME" → in；"支出"/"out"/"EXPENSE" → out）
+ * 优先，否则按金额符号（负=out 正=in），都没有默认 "out"（家长关心消费）。
+ */
+function deriveDirection(explicit, sign) {
+  if (typeof explicit === "string" && explicit.length > 0) {
+    const s = explicit.toLowerCase();
+    if (s === "in" || s === "income" || explicit.includes("收入")) return "in";
+    if (s === "out" || s === "expense" || explicit.includes("支出")) return "out";
+  }
+  if (sign === 1) return "in";
+  return "out";
+}
+
 class AlipayApiClient {
-  constructor() {
+  constructor(opts = {}) {
     this._lastErrorCode = 0;
     this._lastErrorMsg = "";
+    this._fetch =
+      opts.fetch || (typeof globalThis.fetch === "function" ? globalThis.fetch : null);
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.mgwPath = opts.mgwPath || PATH_MGW;
+    this.billListOp = opts.billListOp || OP_BILL_LIST;
+    // 签名 seam：{ buildHeaders({url, operationType, body}) → object }。
+    this.signProvider = opts.signProvider || null;
   }
   _setLastError(code, msg) {
     this._lastErrorCode = code;
@@ -43,6 +110,201 @@ class AlipayApiClient {
     );
     return null;
   }
+
+  /**
+   * live 模式会话探测：数字 uid 可抽，或常见会话 token key（ALIPAYJSESSIONID /
+   * JSESSIONID / ctoken / zone）在场即放行，真伪交给服务端校验。
+   * @param {string} cookie @returns {boolean}
+   */
+  hasSession(cookie) {
+    if (typeof cookie !== "string" || cookie.length === 0) {
+      this._setLastError(-7, "cookie 为空 — 支付宝未登录");
+      return false;
+    }
+    if (/(?:^|; ?)(ALIPAYJSESSIONID|JSESSIONID|ctoken|zone)=[^;\s]+/.test(cookie)) {
+      this._clearLastError();
+      return true;
+    }
+    if (this.extractUid(cookie)) return true;
+    this._setLastError(
+      -7,
+      "cookie 缺会话 token（ALIPAYJSESSIONID / JSESSIONID / ctoken）且无数字 uid — 支付宝未登录",
+    );
+    return false;
+  }
+
+  /**
+   * POST mgw.htm：form 体 `operationType=<op>&requestData=<json-array>`，带
+   * cookie + 可选 signProvider 头。mgw envelope：`{ resultStatus, memo, result }`
+   * （resultStatus 1000 = ok，result 可能是 JSON 字符串），或直接平铺业务体
+   * （`{ success, ... }`）。成功返业务体，失败返 null（设 lastError）。
+   */
+  async _postMgw(operationType, requestData, cookie) {
+    if (typeof this._fetch !== "function") {
+      this._setLastError(
+        -2,
+        "AlipayApiClient: fetch not available — pass opts.fetch or run on Node 18+",
+      );
+      return null;
+    }
+    const url = `${this.baseUrl}${this.mgwPath}`;
+    const body =
+      `operationType=${encodeURIComponent(operationType)}` +
+      `&requestData=${encodeURIComponent(JSON.stringify([requestData]))}`;
+    let headers = {
+      Cookie: cookie,
+      "Content-Type": "application/x-www-form-urlencoded",
+      "User-Agent": BROWSER_UA,
+    };
+    if (this.signProvider && typeof this.signProvider.buildHeaders === "function") {
+      try {
+        const extra = await this.signProvider.buildHeaders({ url, operationType, body });
+        if (extra && typeof extra === "object") headers = { ...headers, ...extra };
+      } catch (e) {
+        this._setLastError(-5, "sign: " + (e && e.message ? e.message : String(e)));
+        return null;
+      }
+    }
+    let resp;
+    try {
+      resp = await this._fetch(url, { method: "POST", headers, body });
+    } catch (e) {
+      this._setLastError(-4, "network: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const txt = await resp.text();
+    if (!resp.ok) {
+      this._setLastError(resp.status, `HTTP ${resp.status}`);
+      return null;
+    }
+    let obj;
+    try {
+      obj = JSON.parse(txt);
+    } catch (e) {
+      this._setLastError(-3, "parse: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    // mgw 网关层错误（resultStatus != 1000）。
+    if (obj.resultStatus !== undefined && Number(obj.resultStatus) !== 1000) {
+      this._setLastError(
+        Number(obj.resultStatus),
+        pick(obj, ["memo", "tips", "message"], `resultStatus ${obj.resultStatus}`).toString(),
+      );
+      return null;
+    }
+    let result = obj.result !== undefined ? obj.result : obj;
+    if (typeof result === "string") {
+      try {
+        result = JSON.parse(result);
+      } catch (e) {
+        this._setLastError(-3, "parse(result): " + (e && e.message ? e.message : String(e)));
+        return null;
+      }
+    }
+    // 业务层错误（success === false）。
+    if (result && result.success === false) {
+      this._setLastError(
+        -6,
+        pick(result, ["resultMessage", "memo", "message", "msg"], "业务失败").toString(),
+      );
+      return null;
+    }
+    this._clearLastError();
+    return result;
+  }
+
+  /**
+   * 账单列表 → [{ orderId, merchant, amountFen, direction, startAt }].
+   * null on error.
+   * @param {string} cookie
+   * @param {object} [opts] { limit, offset }
+   */
+  async getBillList(cookie, opts = {}) {
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 20;
+    const offset = Number.isInteger(opts.offset) && opts.offset > 0 ? opts.offset : 0;
+    const result = await this._postMgw(
+      this.billListOp,
+      { pageSize: limit, pageNum: Math.floor(offset / limit) + 1, offset },
+      cookie,
+    );
+    if (result === null) return null;
+    const list = pick(
+      result,
+      ["billList", "list", "records", "items"],
+      Array.isArray(result) ? result : [],
+    );
+    if (!Array.isArray(list)) return [];
+    return list.map((b) => {
+      const amount = parseAmountYuan(pick(b, ["amount", "tradeAmount", "money"]));
+      return {
+        orderId: pick(b, ["billId", "tradeNo", "bizInNo", "alipayOrderNo", "id"]),
+        merchant: pick(b, [
+          "displayName",
+          "merchantName",
+          "shopName",
+          "goodsTitle",
+          "title",
+        ]),
+        amountFen: amount ? amount.amountFen : null,
+        direction: deriveDirection(
+          pick(b, ["direction", "inOut", "incomeOrExpense"]),
+          amount ? amount.sign : 0,
+        ),
+        startAt: toEpochMs(pick(b, ["gmtCreate", "createTime", "tradeTime", "payTime"])),
+      };
+    });
+  }
+
+  /**
+   * High-level: cookie-scraped uid (profile) + bill list (orders) →
+   * snapshot-shaped { account, events } so the adapter normalize path is
+   * unchanged. uid 抽不到时仅出账单（account null、无 profile 事件）。
+   * @returns {Promise<{account, events}|null>}
+   */
+  async fetchSnapshot(cookie, opts = {}) {
+    if (!this.hasSession(cookie)) return null; // lastError already set
+    const include = opts.include || {};
+    const events = [];
+    let account = null;
+
+    if (include.profile !== false) {
+      const uid = this.extractUid(cookie);
+      if (uid) {
+        account = { uid, displayName: null };
+        events.push({ kind: "profile", id: `profile-${uid}`, uid, nickname: null });
+      }
+      // uid 抽不到不是硬错 — 账单仍可拉。
+      this._clearLastError();
+    }
+
+    if (include.order !== false) {
+      const bills = await this.getBillList(cookie, {
+        limit: opts.limit,
+        offset: opts.offset,
+      });
+      if (bills === null) return null;
+      for (const b of bills) {
+        events.push({
+          kind: "order",
+          id: b.orderId ? `order-${b.orderId}` : null,
+          merchant: b.merchant,
+          amountFen: b.amountFen,
+          direction: b.direction,
+          startAt: b.startAt,
+        });
+      }
+    }
+
+    this._clearLastError();
+    return { account, events };
+  }
 }
 
-module.exports = { AlipayApiClient };
+module.exports = {
+  AlipayApiClient,
+  // Exported for tests / endpoint introspection.
+  parseAmountYuan,
+  deriveDirection,
+  PATH_MGW,
+  OP_BILL_LIST,
+};

package/lib/adapters/finance-alipay/index.js

@@ -1,11 +1,15 @@
 /**
- * FAMILY-23 v0.1 — 支付宝 (Alipay) adapter, snapshot mode.
+ * FAMILY-23 — 支付宝 (Alipay) adapter.
  *
  * 家庭守护 telemetry：家长看孩子的消费情况。**高敏感**（涉资金）— 上行受
- * telemetry level + quiet hours 闸（FAMILY-24/25）。v0.1 cookie-scrape 占位 —
- * [AlipayApiClient.extractUid] 抽 uid；snapshot 模式消费手机端 collector 快照
- * (profile + order)。账单 HTTP fetcher（mobilegw + 签名）留 v0.2，故无 inputPath
- * 时 sync 抛 NO_INPUT。
+ * telemetry level + quiet hours 闸（FAMILY-24/25）。两路互补：
+ *   - snapshot 模式（inputPath）：手机端 collector 快照 (profile + order)。
+ *   - **live 模式（cookie，v0.2 接通）**：[AlipayApiClient.fetchSnapshot] 经
+ *     mobilegw（mgw.htm）拉账单/交易明细；多数 operationType 需 app 级签名 —
+ *     opts.signProvider seam 注入，未注入发未签名请求（服务端可能拒）。端点/
+ *     字段无公开稳定文档，按社区逆向常见形态实现 + 多字段名兼容，**未实地
+ *     验证**，漂移时按 api-client 常量/pick 列表调整。
+ * 无 inputPath 且无 cookie 时 sync 抛错。
  *
  * Snapshot schema (v1):
  *   { schemaVersion:1, snapshottedAt, account:{uid,displayName}, events:[
@@ -28,7 +32,7 @@ const {
 const { AlipayApiClient } = require("./api-client");
 
 const NAME = "finance-alipay";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 const KIND_PROFILE = "profile";
 const KIND_ORDER = "order";
@@ -62,6 +66,7 @@ class AlipayAdapter {
     this.version = VERSION;
     this.capabilities = [
       "sync:snapshot",
+      "sync:cookie",
       "parse:alipay-profile",
       "parse:alipay-order",
     ];
@@ -76,7 +81,10 @@ class AlipayAdapter {
       legalGate: false,
       defaultInclude: { profile: true, order: true },
     };
-    this.apiClient = new AlipayApiClient();
+    this.apiClient = new AlipayApiClient(opts);
+    // Test seam: override how the live client is built per-sync (inject fetch).
+    this._apiClientFactory =
+      typeof opts.apiClientFactory === "function" ? opts.apiClientFactory : null;
     this._deps = { fs };
   }
 
@@ -93,11 +101,21 @@ class AlipayAdapter {
       }
       return { ok: true, mode: "snapshot-file" };
     }
+    if (ctx && typeof ctx.cookie === "string" && ctx.cookie.length > 0) {
+      if (!this.apiClient.hasSession(ctx.cookie)) {
+        return {
+          ok: false,
+          reason: "INVALID_COOKIE",
+          message: `finance-alipay.authenticate: ${this.apiClient.lastError.message}`,
+        };
+      }
+      return { ok: true, mode: "cookie" };
+    }
     return {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "finance-alipay.authenticate: v0.1 needs opts.inputPath (snapshot mode); live HTTP fetcher 待 v0.2",
+        "finance-alipay.authenticate: needs opts.inputPath (snapshot mode) or opts.cookie (支付宝会话, mobilegw live fetch)",
     };
   }
 
@@ -110,11 +128,69 @@ class AlipayAdapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (typeof opts.cookie === "string" && opts.cookie.length > 0) {
+      yield* this._syncViaLive(opts);
+      return;
+    }
     throw new Error(
-      "finance-alipay.sync: v0.1 needs opts.inputPath (snapshot mode); 账单 HTTP fetcher (mobilegw + 签名) 待 v0.2",
+      "finance-alipay.sync: needs opts.inputPath (snapshot mode) or opts.cookie (支付宝会话, 账单 mobilegw live fetch)",
     );
   }
 
+  async *_syncViaLive(opts) {
+    const client = this._apiClientFactory
+      ? this._apiClientFactory(opts)
+      : new AlipayApiClient({
+          fetch: opts.fetch,
+          baseUrl: opts.baseUrl,
+          mgwPath: opts.mgwPath,
+          billListOp: opts.billListOp,
+          signProvider: opts.signProvider,
+        });
+    const emit = (phase, extra) => {
+      if (typeof opts.onProgress === "function") {
+        try {
+          opts.onProgress({ phase, adapter: NAME, ...extra });
+        } catch (_e) {
+          /* progress callback errors are best-effort */
+        }
+      }
+    };
+    const result = await client.fetchSnapshot(opts.cookie, {
+      include: opts.include || {},
+      limit: opts.limit,
+      offset: opts.offset,
+    });
+    if (result === null) {
+      const e = client.lastError;
+      throw new Error(
+        `finance-alipay.sync (live): ${e.message || "fetch failed"} (code ${e.code})`,
+      );
+    }
+    const account = result.account || null;
+    emit("fetched", { count: result.events.length });
+    const capturedAt = Date.now();
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const include = opts.include || {};
+    let emitted = 0;
+    for (const ev of result.events) {
+      if (emitted >= limit) return;
+      if (!ev || !VALID_SNAPSHOT_KINDS.includes(ev.kind)) continue;
+      if (include[ev.kind] === false) continue;
+      const id =
+        (typeof ev.id === "string" && ev.id.length > 0 && ev.id) || ev.uid || null;
+      yield {
+        adapter: NAME,
+        kind: ev.kind,
+        originalId: stableOriginalId(ev.kind, id),
+        capturedAt,
+        payload: { ...ev, capturedAt, account },
+      };
+      emitted += 1;
+    }
+  }
+
   async *_syncViaSnapshot(opts) {
     const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
     const snapshot = JSON.parse(raw);

package/lib/adapters/game-genshin/api-client.js

@@ -1,19 +1,78 @@
 /**
- * GenshinApiClient — FAMILY-23 v0.1 cookie-scrape（无签名）。
+ * GenshinApiClient — FAMILY-23 米哈游通行证 (HoYoLAB / 米游社) 采集客户端。
  *
- * 原神 / 米哈游通行证 (HoYoLAB / 米游社) 走 cookie 鉴权；v0.1 仅从 cookie 抽 uid
- * (extractUid)，不做 HTTP fetcher（历史战绩 / 游戏时长 走 v0.2 通过 takumi/hk4e
- * 接口 + DS 签名）。镜像 social-toutiao-adb/api-client.js 的 extractUid 形态。
+ * v0.1 仅 cookie-scrape（extractUid）。**v0.2 接通 live HTTP fetcher**：
+ * 通过米游社 takumi 接口 + DS（dynamic secret）v1 签名拉取角色档案
+ * （nickname / level / region / 活跃天数）。原神 web game-record API 不暴露
+ * 单次游戏时长（"玩多久" 仍走手机端 collector 快照），但 "玩什么 / 等级 /
+ * 活跃天数" 可经合法 cookie 获取——两路互补。
+ *
+ * DS v1 算法是固定的；轮转的只有 `x-rpc-app_version` ↔ salt 配对（约每隔
+ * 几个客户端版本变一次）。配对作为**可覆盖常量**钉在这里（镜像仓内
+ * SignProvider 轮转模式）——轮转时改 DEFAULT_APP_VERSION / DEFAULT_DS_SALT，
+ * 或在 opts 里传 appVersion / salt。每次轮转后必须用真实已登录 cookie 验证。
  *
  * Cookie key 优先级 (米游社 2023+ → 旧版):
  *   account_id_v2 > ltuid_v2 > account_id > ltuid
  */
 "use strict";
 
+const crypto = require("node:crypto");
+
+// ─── Endpoints (CN / 国服) ─────────────────────────────────────────────
+const DEFAULT_TAKUMI_API = "https://api-takumi.mihoyo.com";
+const DEFAULT_RECORD_API = "https://api-takumi-record.mihoyo.com";
+// 原神国服 game_biz。海外 (hk4e_global) 走不同 host，本采集器仅国服。
+const GAME_BIZ_GENSHIN_CN = "hk4e_cn";
+
+// ─── DS v1 (rotatable) ─────────────────────────────────────────────────
+// 与下方 salt 配对的客户端版本号；DS 校验时 server 比对该版本与 salt。
+// 轮转点：客户端大版本更新后 salt 失效 → 同步改这两个常量。
+const DEFAULT_APP_VERSION = "2.71.1";
+// LK2 / game-record salt（与 DEFAULT_APP_VERSION 配对）。已知会随版本轮转。
+const DEFAULT_DS_SALT = "dWCcEenpFEKWPk7FQzfztReDfGdvR9D9";
+
+const BROWSER_UA =
+  "Mozilla/5.0 (Linux; Android 12) AppleWebKit/537.36 (KHTML, like Gecko) " +
+  "Version/4.0 Chrome/103.0.5060.129 Mobile Safari/537.36 miHoYoBBS/2.71.1";
+
+/** md5 hex digest of a utf-8 string. */
+function md5Hex(input) {
+  return crypto.createHash("md5").update(String(input), "utf8").digest("hex");
+}
+
+/**
+ * Generate a DS v1 dynamic-secret header value: `${t},${r},${c}` where
+ *   t = floor(epoch_ms / 1000)
+ *   r = random integer in [100001, 200000)  (6-digit)
+ *   c = md5(`salt=${salt}&t=${t}&r=${r}`)
+ *
+ * @param {string} salt
+ * @param {() => number} nowFn   epoch-ms clock (test seam)
+ * @param {() => number} randFn  [0,1) source (test seam)
+ */
+function genDs(salt, nowFn, randFn) {
+  const t = Math.floor(nowFn() / 1000);
+  const span = 200000 - 100001;
+  const r = 100001 + Math.floor(randFn() * span);
+  const c = md5Hex(`salt=${salt}&t=${t}&r=${r}`);
+  return `${t},${r},${c}`;
+}
+
 class GenshinApiClient {
-  constructor() {
+  constructor(opts = {}) {
     this._lastErrorCode = 0;
     this._lastErrorMsg = "";
+    // Network deps — resolved lazily so offline callers (extractUid) and
+    // tests can construct without a fetch impl. Network methods check.
+    this._fetch =
+      opts.fetch || (typeof globalThis.fetch === "function" ? globalThis.fetch : null);
+    this._now = opts.now || Date.now;
+    this._rand = opts.rand || Math.random;
+    this.takumiApi = (opts.takumiApi || DEFAULT_TAKUMI_API).replace(/\/+$/, "");
+    this.recordApi = (opts.recordApi || DEFAULT_RECORD_API).replace(/\/+$/, "");
+    this.appVersion = opts.appVersion || DEFAULT_APP_VERSION;
+    this.salt = opts.salt || DEFAULT_DS_SALT;
   }
 
   _setLastError(code, msg) {
@@ -54,6 +113,148 @@ class GenshinApiClient {
     );
     return null;
   }
+
+  _headers(cookie, ds) {
+    return {
+      Cookie: cookie,
+      DS: ds,
+      "x-rpc-app_version": this.appVersion,
+      "x-rpc-client_type": "5",
+      "User-Agent": BROWSER_UA,
+      Referer: "https://webstatic.mihoyo.com/",
+      Origin: "https://webstatic.mihoyo.com",
+    };
+  }
+
+  /**
+   * GET <url> with DS-signed mihoyo headers. Returns parsed `data` field on
+   * success (retcode 0), null on transport / API error (sets lastError).
+   * @param {string} url
+   * @param {string} cookie
+   */
+  async _doGetJson(url, cookie) {
+    if (typeof this._fetch !== "function") {
+      this._setLastError(
+        -2,
+        "GenshinApiClient: fetch not available — pass opts.fetch or run on Node 18+",
+      );
+      return null;
+    }
+    let resp;
+    try {
+      const ds = genDs(this.salt, this._now, this._rand);
+      resp = await this._fetch(url, { method: "GET", headers: this._headers(cookie, ds) });
+    } catch (e) {
+      this._setLastError(-4, "network: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const body = await resp.text();
+    if (!resp.ok) {
+      this._setLastError(resp.status, `HTTP ${resp.status}`);
+      return null;
+    }
+    let obj;
+    try {
+      obj = JSON.parse(body);
+    } catch (e) {
+      this._setLastError(-3, "parse: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    // mihoyo envelope: { retcode, message, data }
+    const retcode = typeof obj.retcode === "number" ? obj.retcode : 0;
+    if (retcode !== 0) {
+      this._setLastError(retcode, (obj.message || "").toString() || `retcode ${retcode}`);
+      return null;
+    }
+    this._clearLastError();
+    return obj.data;
+  }
+
+  /**
+   * Fetch the user's bound Genshin (国服) game roles via cookie.
+   * @param {string} cookie
+   * @returns {Promise<Array<{game_uid,nickname,level,region,region_name}>|null>}
+   */
+  async getGameRoles(cookie) {
+    const url = `${this.takumiApi}/binding/api/getUserGameRolesByCookie?game_biz=${GAME_BIZ_GENSHIN_CN}`;
+    const data = await this._doGetJson(url, cookie);
+    if (data === null) return null;
+    const list = Array.isArray(data.list) ? data.list : [];
+    return list;
+  }
+
+  /**
+   * Fetch game-record index stats for one role (active_day_number etc.).
+   * @param {string} cookie
+   * @param {string} roleId  in-game uid (game_uid)
+   * @param {string} server  region code (cn_gf01 / cn_qd01)
+   * @returns {Promise<object|null>}  the `stats` object or null
+   */
+  async getRecordStats(cookie, roleId, server) {
+    const url = `${this.recordApi}/game_record/app/genshin/api/index?role_id=${encodeURIComponent(
+      roleId,
+    )}&server=${encodeURIComponent(server)}`;
+    const data = await this._doGetJson(url, cookie);
+    if (data === null) return null;
+    return data.stats && typeof data.stats === "object" ? data.stats : {};
+  }
+
+  /**
+   * High-level: resolve all bound Genshin roles into profile records shaped
+   * to match the snapshot `profile` event (so adapter.normalize is unchanged).
+   * When `fetchStats` is true also folds in active_day_number per role.
+   *
+   * @param {string} cookie
+   * @param {object} [opts]
+   * @param {boolean} [opts.fetchStats=true]
+   * @param {number}  [opts.limit]
+   * @returns {Promise<Array<object>|null>}  profile records, or null on hard error
+   */
+  async fetchProfiles(cookie, opts = {}) {
+    if (typeof cookie !== "string" || cookie.length === 0) {
+      this._setLastError(-1, "cookie 为空");
+      return null;
+    }
+    const roles = await this.getGameRoles(cookie);
+    if (roles === null) return null; // lastError already set
+    const fetchStats = opts.fetchStats !== false;
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const profiles = [];
+    for (const role of roles) {
+      if (profiles.length >= limit) break;
+      if (!role || typeof role !== "object") continue;
+      const uid = role.game_uid != null ? String(role.game_uid) : null;
+      if (!uid) continue;
+      const region = role.region || null;
+      let activeDayNumber = null;
+      if (fetchStats && region) {
+        const stats = await this.getRecordStats(cookie, uid, region);
+        // A per-role stats failure is non-fatal — still emit the profile.
+        if (stats && Number.isFinite(stats.active_day_number)) {
+          activeDayNumber = stats.active_day_number;
+        }
+      }
+      profiles.push({
+        uid,
+        nickname: role.nickname || null,
+        level: Number.isFinite(role.level) ? role.level : null,
+        region,
+        regionName: role.region_name || null,
+        activeDayNumber,
+      });
+    }
+    this._clearLastError();
+    return profiles;
+  }
 }
 
-module.exports = { GenshinApiClient };
+module.exports = {
+  GenshinApiClient,
+  // Exported for tests / live-pair rotation introspection.
+  genDs,
+  md5Hex,
+  DEFAULT_APP_VERSION,
+  DEFAULT_DS_SALT,
+  GAME_BIZ_GENSHIN_CN,
+};