@chainlesschain/personal-data-hub 0.4.4 → 0.4.6

package/lib/adapters/edu-zuoyebang/api-client.js

@@ -1,16 +1,40 @@
 /**
- * ZuoyebangApiClient — FAMILY-23 v0.1 cookie-scrape（无签名）。
+ * ZuoyebangApiClient — FAMILY-23 作业帮采集客户端。
  *
  * 作业帮 session 主键是 ZYBUSS（不透明 token）；数字 uid 走 uid / student_id /
- * passport_uid。v0.1 仅 extractUid（学习/搜题历史 走 v0.2）。仅 ZYBUSS 无数字 uid
- * 时返 null（v0.1 不解 ZYBUSS）。
+ * passport_uid。v0.1 仅 cookie-scrape（extractUid）。**v0.2 接通 live HTTP
+ * fetcher**：cookie（ZYBUSS 会话）直拉 用户信息 + 学习/搜题记录。
+ *
+ * ⚠️ **best-effort**：作业帮 web 接口无公开稳定文档，下方端点/字段按其 web 端
+ *    常见形态实现（envelope `{errNo, errstr, data}`），做了多字段名兼容（pick
+ *    回退），**未经真实登录态实地验证** — 端点/字段漂移时改常量 / opts 覆盖
+ *    （同 SignProvider 轮转思路）。
+ *
+ * Cookie key 优先级 (extractUid): uid > student_id > passport_uid。
+ * live 模式仅需 ZYBUSS 在场即可（uid 由 user-info 接口返回）。
  */
 "use strict";
 
+const { pick, toDurationMs, toEpochMs } = require("../_live-json-helpers");
+
+const DEFAULT_BASE_URL = "https://www.zuoyebang.com";
+// 端点（best-effort，可经 opts 覆盖）。
+const PATH_USER_INFO = "/session/pc/getuserinfo";
+const PATH_STUDY_RECORDS = "/study/pc/record/list";
+
+const BROWSER_UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+
 class ZuoyebangApiClient {
-  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.userInfoPath = opts.userInfoPath || PATH_USER_INFO;
+    this.studyRecordsPath = opts.studyRecordsPath || PATH_STUDY_RECORDS;
   }
   _setLastError(code, msg) {
     this._lastErrorCode = code;
@@ -39,10 +63,161 @@ class ZuoyebangApiClient {
     }
     this._setLastError(
       -7,
-      "cookie 缺 uid / student_id / passport_uid — 作业帮未登录 (仅 ZYBUSS 不透明 token, v0.1 不解)",
+      "cookie 缺 uid / student_id / passport_uid — 作业帮未登录 (仅 ZYBUSS 不透明 token, extractUid 不解)",
     );
     return null;
   }
+
+  /**
+   * live 模式会话探测：ZYBUSS 在场（uid 可由接口拿）或数字 uid 可抽即视为有会话。
+   * @param {string} cookie @returns {boolean}
+   */
+  hasSession(cookie) {
+    if (typeof cookie !== "string" || cookie.length === 0) return false;
+    if (/(?:^|; ?)ZYBUSS=[^;\s]+/.test(cookie)) return true;
+    const uid = this.extractUid(cookie);
+    if (uid) return true;
+    this._setLastError(-7, "cookie 缺 ZYBUSS 且无数字 uid — 作业帮未登录");
+    return false;
+  }
+
+  _headers(cookie) {
+    return {
+      Cookie: cookie,
+      "User-Agent": BROWSER_UA,
+      Referer: `${this.baseUrl}/`,
+      Accept: "application/json",
+    };
+  }
+
+  /**
+   * GET <url> with cookie. Parses the zuoyebang web envelope
+   * `{ errNo, errstr, data }` (errNo 0 = ok). Returns `data` on success,
+   * null on transport / API error (sets lastError).
+   */
+  async _doGetJson(url, cookie) {
+    if (typeof this._fetch !== "function") {
+      this._setLastError(
+        -2,
+        "ZuoyebangApiClient: fetch not available — pass opts.fetch or run on Node 18+",
+      );
+      return null;
+    }
+    let resp;
+    try {
+      resp = await this._fetch(url, { method: "GET", headers: this._headers(cookie) });
+    } 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;
+    }
+    const code = pick(obj, ["errNo", "errno", "code"], 0);
+    if (Number(code) !== 0) {
+      this._setLastError(
+        Number(code),
+        pick(obj, ["errstr", "errStr", "errmsg", "errMsg", "msg"], `errNo ${code}`).toString(),
+      );
+      return null;
+    }
+    this._clearLastError();
+    return obj.data !== undefined && obj.data !== null ? obj.data : obj;
+  }
+
+  /** 用户信息 → { uid, nickname, grade } or null. */
+  async getUserInfo(cookie) {
+    const data = await this._doGetJson(`${this.baseUrl}${this.userInfoPath}`, cookie);
+    if (data === null) return null;
+    // web 端常把用户体包在 data.user / data.userInfo 下，或直接平铺。
+    const u = pick(data, ["user", "userInfo", "loginUser"], data);
+    const uid = pick(u, ["uid", "userId", "studentUid", "cuid"]);
+    return {
+      uid: uid != null ? String(uid) : null,
+      nickname: pick(u, ["uname", "nickName", "nickname", "userName", "name"]),
+      grade: pick(u, ["gradeName", "grade", "gradeId"]),
+    };
+  }
+
+  /**
+   * 学习/搜题记录 → [{ recordId, subject, durationMs, startAt }]. null on error.
+   * @param {string} cookie
+   * @param {object} [opts] { limit, offset }
+   */
+  async getStudyRecords(cookie, opts = {}) {
+    const rn = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 20;
+    const pn = Number.isInteger(opts.offset) && opts.offset > 0 ? opts.offset : 0;
+    const url = `${this.baseUrl}${this.studyRecordsPath}?pn=${pn}&rn=${rn}`;
+    const data = await this._doGetJson(url, cookie);
+    if (data === null) return null;
+    const list = pick(data, ["list", "records", "items"], Array.isArray(data) ? data : []);
+    if (!Array.isArray(list)) return [];
+    return list.map((r) => ({
+      recordId: pick(r, ["recordId", "logId", "id"]),
+      subject: pick(r, ["subjectName", "subject", "courseName", "course"]),
+      durationMs: toDurationMs(pick(r, ["studyTime", "duration", "learnTime", "durationMs"], 0)),
+      startAt: toEpochMs(pick(r, ["startTime", "beginTime", "createTime", "time"])),
+    }));
+  }
+
+  /**
+   * High-level: user info + study records → snapshot-shaped { account, events }
+   * so the adapter normalize path is unchanged.
+   * @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 user = await this.getUserInfo(cookie);
+      if (user === null) return null;
+      account = { uid: user.uid, displayName: user.nickname };
+      events.push({
+        kind: "profile",
+        id: user.uid ? `profile-${user.uid}` : null,
+        uid: user.uid,
+        nickname: user.nickname,
+        grade: user.grade,
+      });
+    }
+
+    if (include.study !== false) {
+      const records = await this.getStudyRecords(cookie, {
+        limit: opts.limit,
+        offset: opts.offset,
+      });
+      if (records === null) return null;
+      for (const r of records) {
+        events.push({
+          kind: "study",
+          id: r.recordId ? `study-${r.recordId}` : null,
+          subject: r.subject,
+          durationMs: r.durationMs,
+          startAt: r.startAt,
+        });
+      }
+    }
+
+    this._clearLastError();
+    return { account, events };
+  }
 }
 
-module.exports = { ZuoyebangApiClient };
+module.exports = {
+  ZuoyebangApiClient,
+  // Exported for tests / endpoint introspection.
+  PATH_USER_INFO,
+  PATH_STUDY_RECORDS,
+};

package/lib/adapters/edu-zuoyebang/index.js

@@ -1,10 +1,13 @@
 /**
- * FAMILY-23 v0.1 — 作业帮 (Zuoyebang) adapter, snapshot mode.
+ * FAMILY-23 — 作业帮 (Zuoyebang) adapter.
  *
- * 家庭守护 telemetry：家长看孩子的学习/搜题情况。v0.1 cookie-scrape 占位 —
- * [ZuoyebangApiClient.extractUid] 抽 uid；snapshot 模式消费手机端 collector 快照
- * (profile + study-session)。搜题/作业历史 HTTP fetcher 留 v0.2，故无 inputPath 时
- * sync 抛 NO_INPUT。
+ * 家庭守护 telemetry：家长看孩子的学习/搜题情况。两路互补：
+ *   - snapshot 模式（inputPath）：手机端 collector 快照 (profile + study-session)。
+ *   - **live 模式（cookie，v0.2 接通）**：[ZuoyebangApiClient.fetchSnapshot] 经
+ *     作业帮 web 接口（ZYBUSS 会话 cookie）拉 用户信息 + 学习/搜题记录。端点/
+ *     字段无公开稳定文档，按 web 端常见形态实现 + 多字段名兼容，**未实地验证**，
+ *     漂移时按 api-client 常量/pick 列表调整。
+ * 无 inputPath 且无 cookie 时 sync 抛错。
  *
  * Snapshot schema (v1):
  *   { schemaVersion:1, snapshottedAt, account:{uid,displayName}, events:[
@@ -26,7 +29,7 @@ const {
 const { ZuoyebangApiClient } = require("./api-client");
 
 const NAME = "edu-zuoyebang";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 const KIND_PROFILE = "profile";
 const KIND_STUDY = "study";
@@ -60,6 +63,7 @@ class ZuoyebangAdapter {
     this.version = VERSION;
     this.capabilities = [
       "sync:snapshot",
+      "sync:cookie",
       "parse:zuoyebang-profile",
       "parse:zuoyebang-study-session",
     ];
@@ -74,7 +78,10 @@ class ZuoyebangAdapter {
       legalGate: false,
       defaultInclude: { profile: true, study: true },
     };
-    this.apiClient = new ZuoyebangApiClient();
+    this.apiClient = new ZuoyebangApiClient(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 };
   }
 
@@ -91,11 +98,21 @@ class ZuoyebangAdapter {
       }
       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: `edu-zuoyebang.authenticate: ${this.apiClient.lastError.message}`,
+        };
+      }
+      return { ok: true, mode: "cookie" };
+    }
     return {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "edu-zuoyebang.authenticate: v0.1 needs opts.inputPath (snapshot mode); live HTTP fetcher 待 v0.2",
+        "edu-zuoyebang.authenticate: needs opts.inputPath (snapshot mode) or opts.cookie (ZYBUSS 会话, live fetch)",
     };
   }
 
@@ -108,11 +125,68 @@ class ZuoyebangAdapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (typeof opts.cookie === "string" && opts.cookie.length > 0) {
+      yield* this._syncViaLive(opts);
+      return;
+    }
     throw new Error(
-      "edu-zuoyebang.sync: v0.1 needs opts.inputPath (snapshot mode); 搜题/作业历史 HTTP fetcher 待 v0.2",
+      "edu-zuoyebang.sync: needs opts.inputPath (snapshot mode) or opts.cookie (ZYBUSS 会话, 学习/搜题记录 live fetch)",
     );
   }
 
+  async *_syncViaLive(opts) {
+    const client = this._apiClientFactory
+      ? this._apiClientFactory(opts)
+      : new ZuoyebangApiClient({
+          fetch: opts.fetch,
+          baseUrl: opts.baseUrl,
+          userInfoPath: opts.userInfoPath,
+          studyRecordsPath: opts.studyRecordsPath,
+        });
+    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(
+        `edu-zuoyebang.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/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,
+};