@chainlesschain/personal-data-hub 0.4.3 → 0.4.5

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,
+};

package/lib/adapters/game-genshin/index.js

@@ -1,10 +1,14 @@
 /**
- * FAMILY-23 v0.1 — Genshin Impact (原神 / 米哈游) adapter, snapshot mode.
+ * FAMILY-23 — Genshin Impact (原神 / 米哈游) adapter.
  *
- * 家庭守护 telemetry：家长想看孩子玩什么游戏 / 玩多久。v0.1 cookie-scrape 占位 —
- * [GenshinApiClient.extractUid] 从米游社 cookie 抽 uid；snapshot 模式消费手机端
- * collector 产的快照 JSON（profile + play-session 事件）。HTTP fetcher（takumi/hk4e
- * 战绩 + DS 签名）留 v0.2，故无 inputPath 时 sync 抛 NO_INPUT（同 social-kuaishou）。
+ * 家庭守护 telemetry：家长想看孩子玩什么游戏 / 玩多久。两路互补：
+ *   - snapshot 模式（inputPath）：消费手机端 collector 产的快照 JSON
+ *     （profile + play-session 事件，含精确游戏时长）。
+ *   - **live 模式（cookie，v0.2 接通）**：[GenshinApiClient.fetchProfiles] 经
+ *     米游社 takumi 接口 + DS v1 签名拉取角色档案（nickname / level / region /
+ *     活跃天数）。web game-record API 不暴露单次时长，故 live 仅出 profile；
+ *     "玩多久" 仍依赖 snapshot。
+ * 无 inputPath 且无 cookie 时 sync 抛错。
  *
  * Snapshot schema (v1):
  *   {
@@ -34,7 +38,7 @@ const {
 const { GenshinApiClient } = require("./api-client");
 
 const NAME = "game-genshin";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 
 const KIND_PROFILE = "profile";
@@ -69,6 +73,7 @@ class GenshinAdapter {
     this.version = VERSION;
     this.capabilities = [
       "sync:snapshot",
+      "sync:cookie",
       "parse:genshin-profile",
       "parse:genshin-play-session",
     ];
@@ -83,7 +88,10 @@ class GenshinAdapter {
       legalGate: false,
       defaultInclude: { profile: true, play: true },
     };
-    this.apiClient = new GenshinApiClient();
+    this.apiClient = new GenshinApiClient(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 };
   }
 
@@ -100,11 +108,22 @@ class GenshinAdapter {
       }
       return { ok: true, mode: "snapshot-file" };
     }
+    if (ctx && typeof ctx.cookie === "string" && ctx.cookie.length > 0) {
+      const uid = this.apiClient.extractUid(ctx.cookie);
+      if (!uid) {
+        return {
+          ok: false,
+          reason: "INVALID_COOKIE",
+          message: `game-genshin.authenticate: ${this.apiClient.lastError.message}`,
+        };
+      }
+      return { ok: true, mode: "cookie" };
+    }
     return {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "game-genshin.authenticate: v0.1 needs opts.inputPath (snapshot mode); live HTTP fetcher 待 v0.2",
+        "game-genshin.authenticate: needs opts.inputPath (snapshot mode) or opts.cookie (live HoYoLAB fetch)",
     };
   }
 
@@ -117,11 +136,68 @@ class GenshinAdapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (typeof opts.cookie === "string" && opts.cookie.length > 0) {
+      yield* this._syncViaLive(opts);
+      return;
+    }
     throw new Error(
-      "game-genshin.sync: v0.1 needs opts.inputPath (snapshot mode, Android in-APK cc); live HTTP fetcher (takumi/hk4e + DS 签名) 待 v0.2",
+      "game-genshin.sync: needs opts.inputPath (snapshot mode, Android in-APK cc) or opts.cookie (live HoYoLAB fetch via takumi + DS 签名)",
     );
   }
 
+  async *_syncViaLive(opts) {
+    const client = this._apiClientFactory
+      ? this._apiClientFactory(opts)
+      : new GenshinApiClient({
+          fetch: opts.fetch,
+          now: opts.now,
+          rand: opts.rand,
+          appVersion: opts.appVersion,
+          salt: opts.salt,
+          takumiApi: opts.takumiApi,
+          recordApi: opts.recordApi,
+        });
+    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 profiles = await client.fetchProfiles(opts.cookie, {
+      fetchStats: opts.fetchStats !== false,
+      limit: opts.limit,
+    });
+    if (profiles === null) {
+      const e = client.lastError;
+      throw new Error(
+        `game-genshin.sync (live): ${e.message || "fetch failed"} (code ${e.code})`,
+      );
+    }
+    emit("roles", { count: profiles.length });
+    const capturedAt = Date.now();
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    let emitted = 0;
+    for (const prof of profiles) {
+      if (emitted >= limit) return;
+      yield {
+        adapter: NAME,
+        kind: KIND_PROFILE,
+        originalId: stableOriginalId(KIND_PROFILE, prof.uid),
+        capturedAt,
+        payload: {
+          kind: KIND_PROFILE,
+          ...prof,
+          account: { uid: prof.uid, displayName: prof.nickname },
+        },
+      };
+      emitted += 1;
+    }
+  }
+
   async *_syncViaSnapshot(opts) {
     const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
     const snapshot = JSON.parse(raw);
@@ -220,6 +296,11 @@ function normalizeProfile(p, raw, ingestedAt) {
           platform: "genshin",
           level: p.level != null ? p.level : null,
           avatarUrl: p.avatarUrl || null,
+          region: p.region || null,
+          regionName: p.regionName || null,
+          activeDayNumber: Number.isFinite(p.activeDayNumber)
+            ? p.activeDayNumber
+            : null,
           snapshottedAt: occurredAt,
         },
       },