@chainlesschain/personal-data-hub 0.4.3 → 0.4.5

package/__tests__/adapters/travel-tencent-map.test.js

@@ -0,0 +1,207 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+const {
+  TencentMapAdapter,
+  NAME,
+  VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+} = require("../../lib/adapters/travel-tencent-map");
+
+function writeTmp(content, ext = "json") {
+  const p = path.join(
+    os.tmpdir(),
+    `cc-tencentmap-test-${crypto.randomUUID()}.${ext}`,
+  );
+  fs.writeFileSync(p, content, "utf-8");
+  return p;
+}
+
+async function collect(gen) {
+  const out = [];
+  for await (const x of gen) out.push(x);
+  return out;
+}
+
+function makeFakeDriverFactory(tables, log = {}) {
+  return () =>
+    class FakeDb {
+      constructor(dbPath, opts) {
+        log.opened = { dbPath, opts };
+      }
+      prepare(sql) {
+        for (const [needle, rows] of Object.entries(tables)) {
+          if (sql.includes(needle)) return { all: () => rows };
+        }
+        throw new Error(`no such table in: ${sql}`);
+      }
+      close() {
+        log.closed = true;
+      }
+    };
+}
+
+const SNAPSHOT = {
+  schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+  snapshottedAt: 1716383021000,
+  vendor: "tencent-map",
+  account: { uid: "U1" },
+  events: [
+    {
+      kind: "favourite",
+      id: "fav-1",
+      capturedAt: 1716383021000,
+      name: "公司",
+      lat: 31.2,
+      lng: 121.44,
+      category: "company",
+    },
+    {
+      kind: "route",
+      id: "route-2",
+      capturedAt: 1716383021000,
+      from: { name: "公司" },
+      to: { name: "体育馆" },
+      mode: "bike",
+    },
+  ],
+};
+
+describe("constants", () => {
+  it("exposes name/version/schema", () => {
+    expect(NAME).toBe("travel-tencent-map");
+    expect(VERSION).toBe("0.2.0");
+    expect(SNAPSHOT_SCHEMA_VERSION).toBe(1);
+  });
+});
+
+describe("authenticate", () => {
+  it("mirrors baidu: snapshot / sqlite-needs-deviceId / NO_INPUT", async () => {
+    const p = writeTmp("{}");
+    try {
+      const a = new TencentMapAdapter();
+      expect((await a.authenticate({ inputPath: p })).mode).toBe(
+        "snapshot-file",
+      );
+      expect(
+        (
+          await new TencentMapAdapter({ dbPath: "x.db" }).authenticate({})
+        ).reason,
+      ).toBe("NO_ACCOUNT_DEVICE_ID");
+      expect((await a.authenticate({})).reason).toBe("NO_INPUT");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+});
+
+describe("sync — snapshot mode", () => {
+  it("yields events with tencent-map: prefixed originalId", async () => {
+    const p = writeTmp(JSON.stringify(SNAPSHOT));
+    try {
+      const a = new TencentMapAdapter();
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items.map((i) => i.originalId)).toEqual([
+        "tencent-map:favourite:fav-1",
+        "tencent-map:route:route-2",
+      ]);
+      expect(items[0].payload.account).toEqual({ uid: "U1" });
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("throws on schemaVersion mismatch", async () => {
+    const p = writeTmp(JSON.stringify({ schemaVersion: 2, events: [] }));
+    try {
+      await expect(
+        collect(new TencentMapAdapter().sync({ inputPath: p })),
+      ).rejects.toThrow(/schemaVersion mismatch/);
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+});
+
+describe("sync — sqlite mode (fake driver)", () => {
+  it("yields rows + falls back to tencent_* legacy tables (keyword alias)", async () => {
+    const p = writeTmp("fake", "db");
+    const log = {};
+    try {
+      const a = new TencentMapAdapter({
+        dbPath: p,
+        account: { deviceId: "DEV1" },
+        dbDriverFactory: makeFakeDriverFactory(
+          {
+            tencent_route_history: [
+              {
+                _id: 5,
+                mode: "walk",
+                start_name: "家",
+                end_name: "菜场",
+                time: 1716383021,
+              },
+            ],
+            tencent_search_history: [
+              { _id: 6, keyword: "奶茶", city: "深圳", time: 1716383021000 },
+            ],
+          },
+          log,
+        ),
+      });
+      const items = await collect(a.sync({}));
+      expect(items).toHaveLength(2);
+      expect(items[0].payload.record).toMatchObject({
+        vendorId: "tencentmap",
+        recordId: "route-5",
+        vehicleType: "walk",
+        carrier: "腾讯地图",
+        departureMs: 1716383021 * 1000,
+      });
+      // searchRowToRecord accepts the tencent `keyword` alias
+      expect(items[1].payload.record.to).toMatchObject({
+        name: "奶茶",
+        city: "深圳",
+      });
+      expect(log.closed).toBe(true);
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("requires account.deviceId at sync time", async () => {
+    const a = new TencentMapAdapter({ dbPath: "x.db" });
+    await expect(collect(a.sync({}))).rejects.toThrow(
+      /account\.deviceId required/,
+    );
+  });
+});
+
+describe("normalize", () => {
+  it("snapshot route → bike trip titled by place names", async () => {
+    const p = writeTmp(JSON.stringify(SNAPSHOT));
+    try {
+      const a = new TencentMapAdapter();
+      const [fav, route] = await collect(a.sync({ inputPath: p }));
+      expect(a.normalize(fav).events[0].content.title).toBe("visit: → 公司");
+      const batch = a.normalize(route);
+      expect(batch.events[0].content.title).toBe("bike: 公司 → 体育馆");
+      expect(
+        batch.persons.find((x) => x.subtype === "merchant").names,
+      ).toEqual(["腾讯地图"]);
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("throws on missing payload", () => {
+    expect(() => new TencentMapAdapter().normalize(null)).toThrow(
+      /payload missing/,
+    );
+  });
+});

package/lib/adapters/_live-json-helpers.js

@@ -0,0 +1,50 @@
+/**
+ * Shared field-extraction helpers for FAMILY-23 live JSON fetchers
+ * (edu-zuoyebang / edu-huawei-learning / finance-alipay).
+ *
+ * Same semantics as the locals in game-honor-of-kings/api-client.js — kept
+ * separate so existing clients (KOH / genshin) stay untouched; new live
+ * clients require from here instead of re-duplicating.
+ */
+"use strict";
+
+/** First present, non-empty value among `keys` on `obj`. */
+function pick(obj, keys, fallback = null) {
+  if (!obj || typeof obj !== "object") return fallback;
+  for (const k of keys) {
+    const v = obj[k];
+    if (v !== undefined && v !== null && v !== "") return v;
+  }
+  return fallback;
+}
+
+/**
+ * Coerce a seconds-or-ms duration to ms. Session lengths separate cleanly:
+ * seconds form is ≤ ~7200 (2h), ms form is ≥ ~300000 (5min) — a 1e5 threshold
+ * disambiguates without overlap.
+ */
+function toDurationMs(v) {
+  if (!Number.isFinite(v)) {
+    const n = typeof v === "string" && /^\d+$/.test(v) ? parseInt(v, 10) : NaN;
+    if (!Number.isFinite(n)) return 0;
+    v = n;
+  }
+  if (v <= 0) return 0;
+  return v < 1e5 ? v * 1000 : v;
+}
+
+/** Coerce epoch seconds-or-ms (or date string) to ms, else null. */
+function toEpochMs(v) {
+  if (Number.isFinite(v)) return v > 1e12 ? v : v * 1000;
+  if (typeof v === "string") {
+    if (/^\d+$/.test(v)) {
+      const n = parseInt(v, 10);
+      return n > 1e12 ? n : n * 1000;
+    }
+    const t = Date.parse(v);
+    return Number.isFinite(t) ? t : null;
+  }
+  return null;
+}
+
+module.exports = { pick, toDurationMs, toEpochMs };

package/lib/adapters/edu-huawei-learning/api-client.js

@@ -1,15 +1,37 @@
 /**
- * HuaweiLearningApiClient — FAMILY-23 v0.1 cookie-scrape（无签名）。
+ * HuaweiLearningApiClient — FAMILY-23 华为学习中心采集客户端。
  *
- * 华为学习中心走华为账号登录；v0.1 从 accountId / userId / huaweiUid 抽数字 uid。
- * 课程/学习时长 走 v0.2（华为教育接口 + 账号签名）。
+ * 华为学习中心走华为账号登录；v0.1 仅 cookie-scrape（extractUid，从 accountId /
+ * userId / huaweiUid 抽数字 uid）。**v0.2 接通 live HTTP fetcher**：cookie（华为
+ * 账号 web 会话）直拉 用户信息 + 课程学习记录（课程名 / 学习时长）。
+ *
+ * ⚠️ **best-effort**：学习中心接口无公开稳定文档，下方端点/字段按 hicloud 教育
+ *    服务常见形态实现（envelope `{code|resultCode, message, data}`，0 = ok），
+ *    做了多字段名兼容（pick 回退），**未经真实华为账号登录态实地验证** —
+ *    端点/字段漂移时改常量 / opts 覆盖（同 SignProvider 轮转思路）。
  */
 "use strict";
 
+const { pick, toDurationMs, toEpochMs } = require("../_live-json-helpers");
+
+const DEFAULT_BASE_URL = "https://educenter.hicloud.com";
+// 端点（best-effort，可经 opts 覆盖）。
+const PATH_USER_INFO = "/edu/api/user/v1/info";
+const PATH_STUDY_RECORDS = "/edu/api/study/v1/records";
+
+const BROWSER_UA =
+  "Mozilla/5.0 (Linux; Android 12; HarmonyOS) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/114.0.0.0 Mobile Safari/537.36";
+
 class HuaweiLearningApiClient {
-  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;
@@ -42,6 +64,157 @@ class HuaweiLearningApiClient {
     );
     return null;
   }
+
+  /**
+   * live 模式会话探测：华为账号 web 会话 key 形态不稳定（CAS / OAuth 多变体），
+   * 宽松判定 — 有任意 `k=v` 形态的非空 cookie 即放行，真伪交给服务端校验。
+   * @param {string} cookie @returns {boolean}
+   */
+  hasSession(cookie) {
+    if (typeof cookie !== "string" || !/[^=;\s]+=[^;\s]+/.test(cookie)) {
+      this._setLastError(-7, "cookie 为空或非法 — 华为账号未登录");
+      return false;
+    }
+    this._clearLastError();
+    return true;
+  }
+
+  _headers(cookie) {
+    return {
+      Cookie: cookie,
+      "User-Agent": BROWSER_UA,
+      Referer: `${this.baseUrl}/`,
+      Accept: "application/json",
+    };
+  }
+
+  /**
+   * GET <url> with cookie. Parses `{ code|resultCode, message, data }`
+   * (0 = ok). Returns `data` on success, null on error (sets lastError).
+   */
+  async _doGetJson(url, cookie) {
+    if (typeof this._fetch !== "function") {
+      this._setLastError(
+        -2,
+        "HuaweiLearningApiClient: 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, ["code", "resultCode", "errorCode"], 0);
+    if (Number(code) !== 0) {
+      this._setLastError(
+        Number(code),
+        pick(obj, ["message", "msg", "desc", "errorMsg"], `code ${code}`).toString(),
+      );
+      return null;
+    }
+    this._clearLastError();
+    const data = pick(obj, ["data", "result", "value"]);
+    return data !== null ? data : obj;
+  }
+
+  /** 用户信息 → { uid, nickname } or null. */
+  async getUserInfo(cookie) {
+    const data = await this._doGetJson(`${this.baseUrl}${this.userInfoPath}`, cookie);
+    if (data === null) return null;
+    const u = pick(data, ["user", "userInfo", "account"], data);
+    const uid = pick(u, ["uid", "userId", "accountId"]);
+    return {
+      uid: uid != null ? String(uid) : null,
+      nickname: pick(u, ["nickName", "nickname", "displayName", "userName", "name"]),
+    };
+  }
+
+  /**
+   * 课程学习记录 → [{ recordId, course, durationMs, startAt }]. null on error.
+   * @param {string} cookie
+   * @param {object} [opts] { limit, offset }
+   */
+  async getStudyRecords(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 url = `${this.baseUrl}${this.studyRecordsPath}?offset=${offset}&limit=${limit}`;
+    const data = await this._doGetJson(url, cookie);
+    if (data === null) return null;
+    const list = pick(data, ["records", "list", "items"], Array.isArray(data) ? data : []);
+    if (!Array.isArray(list)) return [];
+    return list.map((r) => ({
+      recordId: pick(r, ["recordId", "id", "logId"]),
+      course: pick(r, ["courseName", "course", "title", "name"]),
+      durationMs: toDurationMs(
+        pick(r, ["studyDuration", "duration", "learnTime", "durationMs"], 0),
+      ),
+      startAt: toEpochMs(pick(r, ["startTime", "studyTime", "createTime", "beginTime"])),
+    }));
+  }
+
+  /**
+   * 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,
+      });
+    }
+
+    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,
+          course: r.course,
+          durationMs: r.durationMs,
+          startAt: r.startAt,
+        });
+      }
+    }
+
+    this._clearLastError();
+    return { account, events };
+  }
 }
 
-module.exports = { HuaweiLearningApiClient };
+module.exports = {
+  HuaweiLearningApiClient,
+  // Exported for tests / endpoint introspection.
+  PATH_USER_INFO,
+  PATH_STUDY_RECORDS,
+};

package/lib/adapters/edu-huawei-learning/index.js

@@ -1,10 +1,13 @@
 /**
- * FAMILY-23 v0.1 — 华为学习中心 (Huawei Learning Center) adapter, snapshot mode.
+ * FAMILY-23 — 华为学习中心 (Huawei Learning Center) adapter.
  *
- * 家庭守护 telemetry：家长看孩子的课程/学习时长。v0.1 cookie-scrape 占位 —
- * [HuaweiLearningApiClient.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 接通）**：[HuaweiLearningApiClient.fetchSnapshot]
+ *     经学习中心接口（华为账号 web 会话 cookie）拉 用户信息 + 课程学习记录。
+ *     端点/字段无公开稳定文档，按 hicloud 教育服务常见形态实现 + 多字段名兼容，
+ *     **未实地验证**，漂移时按 api-client 常量/pick 列表调整。
+ * 无 inputPath 且无 cookie 时 sync 抛错。
  *
  * Snapshot schema (v1):
  *   { schemaVersion:1, snapshottedAt, account:{uid,displayName}, events:[
@@ -26,7 +29,7 @@ const {
 const { HuaweiLearningApiClient } = require("./api-client");
 
 const NAME = "edu-huawei-learning";
-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 HuaweiLearningAdapter {
     this.version = VERSION;
     this.capabilities = [
       "sync:snapshot",
+      "sync:cookie",
       "parse:huawei-learning-profile",
       "parse:huawei-learning-study-session",
     ];
@@ -74,7 +78,10 @@ class HuaweiLearningAdapter {
       legalGate: false,
       defaultInclude: { profile: true, study: true },
     };
-    this.apiClient = new HuaweiLearningApiClient();
+    this.apiClient = new HuaweiLearningApiClient(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 HuaweiLearningAdapter {
       }
       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-huawei-learning.authenticate: ${this.apiClient.lastError.message}`,
+        };
+      }
+      return { ok: true, mode: "cookie" };
+    }
     return {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "edu-huawei-learning.authenticate: v0.1 needs opts.inputPath (snapshot mode); live HTTP fetcher 待 v0.2",
+        "edu-huawei-learning.authenticate: needs opts.inputPath (snapshot mode) or opts.cookie (华为账号会话, live fetch)",
     };
   }
 
@@ -108,11 +125,68 @@ class HuaweiLearningAdapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (typeof opts.cookie === "string" && opts.cookie.length > 0) {
+      yield* this._syncViaLive(opts);
+      return;
+    }
     throw new Error(
-      "edu-huawei-learning.sync: v0.1 needs opts.inputPath (snapshot mode); 课程历史 HTTP fetcher 待 v0.2",
+      "edu-huawei-learning.sync: needs opts.inputPath (snapshot mode) or opts.cookie (华为账号会话, 课程学习记录 live fetch)",
     );
   }
 
+  async *_syncViaLive(opts) {
+    const client = this._apiClientFactory
+      ? this._apiClientFactory(opts)
+      : new HuaweiLearningApiClient({
+          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-huawei-learning.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);