@chainlesschain/personal-data-hub 0.4.4 → 0.4.5

package/__tests__/adapters/social-douyin-adb-watch-history.test.js

@@ -0,0 +1,192 @@
+/**
+ * Douyin watch-history local-DB reader + collector tests (real-device-driven
+ * 2026-06-11, device 5lhyaqu8lbwstc6x: video_record.db record_<uid> = 900 rows).
+ *
+ * Validates the plaintext video_record.db path that sidesteps the encrypted IM
+ * db + X-Bogus signing. adb + sqlite injected (no device / native driver).
+ */
+"use strict";
+
+import { describe, it, expect, vi } from "vitest";
+
+const {
+  createDouyinWatchExtension,
+  VIDEO_RECORD_DB_REMOTE_PATH,
+  _internals,
+} = require("../../lib/adapters/social-douyin-adb/watch-history-reader");
+const {
+  collectWatchHistory,
+} = require("../../lib/adapters/social-douyin-adb/collector");
+const { DouyinAdapter } = require("../../lib/adapters/social-douyin");
+const { partitionBatch } = require("../../lib/batch");
+
+// ── readDouyinWatchHistory (injected Database) ────────────────────────
+function makeFakeDb(tablesToRows) {
+  return class FakeDb {
+    constructor() {}
+    prepare(sql) {
+      return {
+        all: () => {
+          if (/sqlite_master/.test(sql)) {
+            return Object.keys(tablesToRows).map((name) => ({ name }));
+          }
+          const tm = /FROM "([^"]+)"/.exec(sql);
+          if (tm && /table_info/.test(sql) === false && /COUNT/.test(sql) === false) {
+            return tablesToRows[tm[1]] || [];
+          }
+          if (/table_info/.test(sql)) {
+            return [
+              { name: "aid" },
+              { name: "view_time_timestamp" },
+              { name: "enter_from" },
+            ];
+          }
+          return [];
+        },
+        get: () => {
+          const tm = /FROM "([^"]+)"/.exec(sql);
+          if (/COUNT/.test(sql) && tm) return { c: (tablesToRows[tm[1]] || []).length };
+          return undefined;
+        },
+      };
+    }
+    close() {}
+  };
+}
+
+describe("readDouyinWatchHistory", () => {
+  it("picks the largest record_<uid> table (skips record_0), parses rows → ms", () => {
+    const Db = makeFakeDb({
+      record_0: [{ aid: "x", view_time_timestamp: 1, enter_from: "a" }],
+      record_92585448288: [
+        { aid: "7480000000000000001", view_time_timestamp: 1717800000, enter_from: "homepage_hot" },
+        { aid: "7480000000000000002", view_time_timestamp: 1717800600, enter_from: "homepage_follow" },
+      ],
+    });
+    const r = _internals.readDouyinWatchHistory("x.db", { _databaseClass: Db });
+    expect(r.uid).toBe("92585448288");
+    expect(r.records).toHaveLength(2);
+    expect(r.records[0]).toEqual({
+      awemeId: "7480000000000000001",
+      capturedAt: 1717800000 * 1000, // seconds → ms
+      enterFrom: "homepage_hot",
+    });
+  });
+
+  it("returns {uid:null, records:[]} when only the anonymous record_0 exists", () => {
+    const Db = makeFakeDb({ record_0: [{ aid: "x", view_time_timestamp: 1 }] });
+    const r = _internals.readDouyinWatchHistory("x.db", { _databaseClass: Db });
+    expect(r.uid).toBe(null);
+    expect(r.records).toEqual([]);
+  });
+
+  it("toEpochMs treats >1e12 as ms, else seconds; rejects junk", () => {
+    expect(_internals.toEpochMs(1717800000)).toBe(1717800000000);
+    expect(_internals.toEpochMs(1717800000000)).toBe(1717800000000);
+    expect(_internals.toEpochMs(0)).toBe(null);
+    expect(_internals.toEpochMs("nope")).toBe(null);
+  });
+});
+
+// ── pullVideoRecordDbViaSu (injected adb) ─────────────────────────────
+function makeAdb({ ls, pm, id, b64 }) {
+  return async (args) => {
+    const cmd = args.join(" ");
+    if (cmd.includes("pm list packages")) return pm || "";
+    if (cmd.includes("ls ")) return ls;
+    if (cmd.includes("id -u")) return id;
+    if (cmd.includes("base64 ")) return b64;
+    throw new Error("fake adb: unexpected " + cmd);
+  };
+}
+
+describe("pullVideoRecordDbViaSu — diagnosis", () => {
+  it("path constant points at video_record.db", () => {
+    expect(VIDEO_RECORD_DB_REMOTE_PATH).toBe(
+      "/data/data/com.ss.android.ugc.aweme/databases/video_record.db",
+    );
+  });
+
+  it("missing db + installed → DOUYIN_VIDEO_RECORD_MISSING", async () => {
+    const adb = makeAdb({ ls: "NOT_FOUND\r\n", pm: "package:com.ss.android.ugc.aweme\r\n" });
+    await expect(_internals.pullVideoRecordDbViaSu(adb, "s", {})).rejects.toThrow(
+      /DOUYIN_VIDEO_RECORD_MISSING/,
+    );
+  });
+
+  it("missing db + not installed → DOUYIN_NOT_INSTALLED", async () => {
+    const adb = makeAdb({ ls: "NOT_FOUND\r\n", pm: "" });
+    await expect(_internals.pullVideoRecordDbViaSu(adb, "s", {})).rejects.toThrow(
+      /DOUYIN_NOT_INSTALLED/,
+    );
+  });
+
+  it("non-root → DOUYIN_NO_ROOT", async () => {
+    const adb = makeAdb({ ls: VIDEO_RECORD_DB_REMOTE_PATH, id: "2000\r\n" });
+    await expect(_internals.pullVideoRecordDbViaSu(adb, "s", {})).rejects.toThrow(/DOUYIN_NO_ROOT/);
+  });
+
+  it("non-sqlite payload → DOUYIN_VIDEO_RECORD_NOT_SQLITE", async () => {
+    const buf = Buffer.alloc(2048, 0x41);
+    const adb = makeAdb({ ls: VIDEO_RECORD_DB_REMOTE_PATH, id: "uid=0(root)", b64: buf.toString("base64") });
+    await expect(_internals.pullVideoRecordDbViaSu(adb, "s", {})).rejects.toThrow(
+      /DOUYIN_VIDEO_RECORD_NOT_SQLITE/,
+    );
+  });
+});
+
+// ── collectWatchHistory + normalize round-trip ────────────────────────
+describe("collectWatchHistory → social-douyin history events", () => {
+  it("builds a snapshot of history events; normalize → valid BROWSE batch with enterFrom", async () => {
+    const fs = require("node:fs");
+    const os = require("node:os");
+    const bridge = {
+      invoke: vi.fn(async (m) => {
+        if (m === "douyin.watch-history") {
+          return {
+            uid: "92585448288",
+            records: [
+              { awemeId: "7480000000000000001", capturedAt: 1717800000000, enterFrom: "homepage_hot" },
+              { awemeId: "7480000000000000002", capturedAt: 1717800600000, enterFrom: "homepage_follow" },
+            ],
+          };
+        }
+        throw new Error("unknown " + m);
+      }),
+    };
+    const r = await collectWatchHistory(bridge, { stagingDir: os.tmpdir(), now: () => 1717900000000 });
+    expect(r.uid).toBe("92585448288");
+    expect(r.eventCounts.history).toBe(2);
+    // The written snapshot ingests through the real adapter normalize.
+    const snap = JSON.parse(fs.readFileSync(r.snapshotPath, "utf-8"));
+    try {
+      expect(snap.events).toHaveLength(2);
+      expect(snap.events[0].kind).toBe("history");
+      const a = new DouyinAdapter();
+      const batch = a.normalize({
+        adapter: "social-douyin",
+        kind: "history",
+        originalId: "douyin:history:1",
+        capturedAt: 1717800000000,
+        payload: { ...snap.events[0], account: snap.account },
+      });
+      expect(partitionBatch(batch).invalidReasons).toHaveLength(0);
+      expect(batch.events[0].subtype).toBe("browse");
+      expect(batch.events[0].extra.awemeId).toBe("7480000000000000001");
+      expect(batch.events[0].extra.enterFrom).toBe("homepage_hot");
+    } finally {
+      fs.unlinkSync(r.snapshotPath);
+    }
+  });
+
+  it("throws on malformed bridge payload (no records array)", async () => {
+    const bridge = { invoke: vi.fn(async () => ({ uid: "1" })) };
+    await expect(collectWatchHistory(bridge, {})).rejects.toThrow(/malformed payload/);
+  });
+});
+
+describe("createDouyinWatchExtension contract", () => {
+  it("rejects when ctx lacks {adb, pickDevice}", async () => {
+    await expect(createDouyinWatchExtension()({}, {})).rejects.toThrow(/ctx must provide/);
+  });
+});

package/__tests__/adapters/social-toutiao-adb-account-reader.test.js

@@ -0,0 +1,135 @@
+/**
+ * Toutiao on-device account_db reader tests (real-device-driven 2026-06-11).
+ *
+ * Validates the path that unblocks Toutiao when the web profile endpoint is
+ * permission-denied (error_code 16) and the cookie jar has no numeric uid:
+ * read uid+nickname+sec_uid from the plaintext local account_db.login_info.
+ * adb + sqlite are injected (no device / no native driver needed).
+ */
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  createToutiaoAccountExtension,
+  ACCOUNT_DB_REMOTE_PATH,
+  _internals,
+} = require("../../lib/adapters/social-toutiao-adb/account-reader");
+
+// ── readToutiaoAccount (injected Database class) ──────────────────────
+function makeFakeDb(rows, { hasTime = true } = {}) {
+  return class FakeDb {
+    constructor() {}
+    prepare(sql) {
+      return {
+        all: () => {
+          if (/table_info\(login_info\)/.test(sql)) {
+            const cols = ["uid", "screen_name", "sec_uid", "platform_screen_name"];
+            if (hasTime) cols.push("time");
+            return cols.map((name) => ({ name }));
+          }
+          if (/FROM login_info/.test(sql)) return rows;
+          return [];
+        },
+        get: () => undefined,
+      };
+    }
+    close() {}
+  };
+}
+
+describe("readToutiaoAccount", () => {
+  it("picks the numeric-uid row → {uid, nickname, secUid}", () => {
+    const Db = makeFakeDb([
+      { uid: "92585279158", screen_name: "小明", sec_uid: "MS4wLjAB", time: 200 },
+    ]);
+    const r = _internals.readToutiaoAccount("x.db", { _databaseClass: Db });
+    expect(r).toEqual({ uid: "92585279158", nickname: "小明", secUid: "MS4wLjAB" });
+  });
+
+  it("skips guest/zero/non-numeric uid rows, takes first valid", () => {
+    const Db = makeFakeDb([
+      { uid: "0", screen_name: "guest", time: 300 },
+      { uid: "abc", screen_name: "bad", time: 250 },
+      { uid: "555", screen_name: "real", sec_uid: null, time: 200 },
+    ]);
+    const r = _internals.readToutiaoAccount("x.db", { _databaseClass: Db });
+    expect(r.uid).toBe("555");
+    expect(r.nickname).toBe("real");
+    expect(r.secUid).toBe(null);
+  });
+
+  it("falls back to platform_screen_name when screen_name empty", () => {
+    const Db = makeFakeDb([
+      { uid: "7", screen_name: "", platform_screen_name: "plat", time: 1 },
+    ]);
+    expect(_internals.readToutiaoAccount("x.db", { _databaseClass: Db }).nickname).toBe("plat");
+  });
+
+  it("returns null when no numeric-uid row exists", () => {
+    const Db = makeFakeDb([{ uid: "0" }, { uid: "" }]);
+    expect(_internals.readToutiaoAccount("x.db", { _databaseClass: Db })).toBe(null);
+  });
+});
+
+// ── pullAccountDbViaSu (injected adb) ─────────────────────────────────
+function makeAdb({ ls, pm, id, b64 }) {
+  return async (args) => {
+    const cmd = args.join(" ");
+    if (cmd.includes("pm list packages")) return pm || "";
+    if (cmd.includes("ls ")) return ls;
+    if (cmd.includes("id -u")) return id;
+    if (cmd.includes("base64 ")) return b64;
+    throw new Error("fake adb: unexpected " + cmd);
+  };
+}
+
+describe("pullAccountDbViaSu — diagnosis", () => {
+  it("constant points at the toutiao account_db", () => {
+    expect(ACCOUNT_DB_REMOTE_PATH).toBe(
+      "/data/data/com.ss.android.article.news/databases/account_db",
+    );
+  });
+
+  it("missing db + package installed → TOUTIAO_ACCOUNT_DB_MISSING", async () => {
+    const adb = makeAdb({ ls: "NOT_FOUND\r\n", pm: "package:com.ss.android.article.news\r\n" });
+    await expect(_internals.pullAccountDbViaSu(adb, "s", {})).rejects.toThrow(
+      /TOUTIAO_ACCOUNT_DB_MISSING/,
+    );
+  });
+
+  it("missing db + package not installed → TOUTIAO_NOT_INSTALLED", async () => {
+    const adb = makeAdb({ ls: "NOT_FOUND\r\n", pm: "" });
+    await expect(_internals.pullAccountDbViaSu(adb, "s", {})).rejects.toThrow(
+      /TOUTIAO_NOT_INSTALLED/,
+    );
+  });
+
+  it("non-root su → TOUTIAO_NO_ROOT", async () => {
+    const adb = makeAdb({ ls: ACCOUNT_DB_REMOTE_PATH, id: "2000\r\n" });
+    await expect(_internals.pullAccountDbViaSu(adb, "s", {})).rejects.toThrow(/TOUTIAO_NO_ROOT/);
+  });
+
+  it("empty base64 stream → TOUTIAO_ACCOUNT_DB_EMPTY", async () => {
+    const adb = makeAdb({ ls: ACCOUNT_DB_REMOTE_PATH, id: "0", b64: "  \r\n" });
+    await expect(_internals.pullAccountDbViaSu(adb, "s", {})).rejects.toThrow(
+      /TOUTIAO_ACCOUNT_DB_EMPTY/,
+    );
+  });
+
+  it("non-sqlite payload → TOUTIAO_ACCOUNT_DB_NOT_SQLITE", async () => {
+    const buf = Buffer.alloc(2048, 0x41); // "AAAA…"
+    const adb = makeAdb({ ls: ACCOUNT_DB_REMOTE_PATH, id: "uid=0(root)", b64: buf.toString("base64") });
+    await expect(_internals.pullAccountDbViaSu(adb, "s", {})).rejects.toThrow(
+      /TOUTIAO_ACCOUNT_DB_NOT_SQLITE/,
+    );
+  });
+});
+
+// ── extension contract ────────────────────────────────────────────────
+describe("createToutiaoAccountExtension", () => {
+  it("rejects when ctx lacks {adb, pickDevice}", async () => {
+    const ext = createToutiaoAccountExtension();
+    await expect(ext({}, {})).rejects.toThrow(/ctx must provide/);
+  });
+});

package/__tests__/adapters/social-toutiao-adb-api-client.test.js

@@ -280,6 +280,56 @@ describe("ToutiaoApiClient — fetchProfile", () => {
     expect(await c.fetchProfile("sessionid=abc")).toBe(null);
     expect(c.lastErrorCode).toBe(-4);
   });
+
+  // ── passport v2 envelope (real-device 2026-06-11, no status_code) ──
+  it("parses passport-v2 success envelope { message:'success', data } (no status_code)", async () => {
+    const { fakeFetch } = makeFakeFetch([
+      [
+        "passport/account/info/v2",
+        {
+          body: JSON.stringify({
+            message: "success",
+            data: { user_id: "555", screen_name: "v2user" },
+          }),
+        },
+      ],
+    ]);
+    const c = new ToutiaoApiClient({ fetch: fakeFetch });
+    const p = await c.fetchProfile("sessionid=abc");
+    expect(p).not.toBe(null);
+    expect(p.uid).toBe("555");
+    expect(p.nickname).toBe("v2user");
+  });
+
+  it("surfaces passport-v2 error envelope error_code + 中文 description (error_code 16 该应用无权限)", async () => {
+    // Verified on device 5lhyaqu8lbwstc6x with a fully logged-in Toutiao:
+    // the endpoint now returns this even with valid sessionid cookies. The
+    // old code mis-reported it as "missing status_code".
+    const { fakeFetch } = makeFakeFetch([
+      [
+        "passport/account/info/v2",
+        {
+          body: JSON.stringify({
+            message: "error",
+            data: { error_code: 16, description: "该应用无权限", captcha: "" },
+          }),
+        },
+      ],
+    ]);
+    const c = new ToutiaoApiClient({ fetch: fakeFetch });
+    expect(await c.fetchProfile("sessionid=abc")).toBe(null);
+    expect(c.lastErrorCode).toBe(16);
+    expect(c.lastErrorMessage).toBe("该应用无权限");
+  });
+
+  it("unrecognized envelope (no status_code, no message) → -5 with key list", async () => {
+    const { fakeFetch } = makeFakeFetch([
+      ["passport/account/info/v2", { body: JSON.stringify({ foo: "bar" }) }],
+    ]);
+    const c = new ToutiaoApiClient({ fetch: fakeFetch });
+    expect(await c.fetchProfile("sessionid=abc")).toBe(null);
+    expect(c.lastErrorCode).toBe(-5);
+  });
 });
 
 describe("ToutiaoApiClient — fetchFeed", () => {
@@ -535,3 +585,42 @@ describe("normalizeMs", () => {
     expect(_internals.normalizeMs(NaN)).toBe(0);
   });
 });
+
+describe("err_no surfacing (HTTP 200 + err_no!=0 must NOT mask as empty)", () => {
+  it("fetchCollection: {err_no:1,'params illegal',data:[]} → [] + lastErrorCode 1", async () => {
+    // Real-device 2026-06-11: tab_comments returned this; the old code saw
+    // data:[] and reported 0 results with errCode 0, hiding the real failure.
+    const { fakeFetch } = makeFakeFetch([
+      [
+        "article/v2/tab_comments",
+        { body: JSON.stringify({ message: "params illegal", err_no: 1, data: [] }) },
+      ],
+    ]);
+    const sign = {
+      signUrl: vi.fn(async (url) => {
+        const u = new URL(String(url));
+        u.searchParams.set("_signature", "X");
+        return u;
+      }),
+    };
+    const c = new ToutiaoApiClient({ fetch: fakeFetch, signProvider: sign });
+    const items = await c.fetchCollection("sessionid=abc");
+    expect(items).toEqual([]);
+    expect(c.lastErrorCode).toBe(1);
+    expect(c.lastErrorMessage).toBe("params illegal");
+  });
+
+  it("err_no:0 is treated as success (not masked)", async () => {
+    const { fakeFetch } = makeFakeFetch([
+      [
+        "article/v2/tab_comments",
+        { body: JSON.stringify({ err_no: 0, data: [{ group_id: "C1", title: "Saved", behot_time: 1700000000 }] }) },
+      ],
+    ]);
+    const sign = { signUrl: vi.fn(async (url) => { const u = new URL(String(url)); u.searchParams.set("_signature", "X"); return u; }) };
+    const c = new ToutiaoApiClient({ fetch: fakeFetch, signProvider: sign });
+    const items = await c.fetchCollection("sessionid=abc");
+    expect(items).toHaveLength(1);
+    expect(items[0].itemId).toBe("C1");
+  });
+});

package/__tests__/adapters/social-toutiao-adb-collector.test.js

@@ -71,9 +71,19 @@ const HAPPY_RESPONSES = [
   ],
 ];
 
-function makeBridge(invokeResult) {
+function makeBridge(invokeResult, accountResult) {
   return {
-    invoke: vi.fn(async (method, params) => invokeResult),
+    invoke: vi.fn(async (method) => {
+      if (method === "toutiao.account") {
+        // Mirror real wiring: a separate extension. Tests that don't wire it
+        // get a throw (collector falls through gracefully).
+        if (accountResult === undefined) {
+          throw new Error("toutiao.account not wired in this test");
+        }
+        return accountResult;
+      }
+      return invokeResult;
+    }),
   };
 }
 
@@ -182,6 +192,89 @@ describe("collect — profile fetch fails", () => {
     expect(r.uid).toBe(null);
     expect(r.profileFetchFailed).toBe(true);
   });
+
+  it("profile permission-denied (error_code 16) BUT cookie uid + signer → feed/collection/search still collect", async () => {
+    // Real-device 2026-06-11: logged-in Toutiao returns passport error_code 16
+    // 该应用无权限. We must NOT abort — feed is cookie-identified, so with a
+    // SignBridge the signed endpoints still flow. Profile event is skipped, but
+    // the headline error (16) is surfaced and feed/collection/search collect.
+    const { fakeFetch } = makeFakeFetch([
+      [
+        "passport/account/info/v2",
+        {
+          body: JSON.stringify({
+            message: "error",
+            data: { error_code: 16, description: "该应用无权限" },
+          }),
+        },
+      ],
+      ...HAPPY_RESPONSES.slice(1), // feed / comments / search responses
+    ]);
+    const sign = {
+      warmUp: vi.fn(async () => {}),
+      signUrl: vi.fn(async (url) => {
+        const u = new URL(String(url));
+        u.searchParams.set("_signature", "BRIDGE_SIG");
+        return u;
+      }),
+      shutdown: vi.fn(async () => {}),
+    };
+    const client = new ToutiaoApiClient({ fetch: fakeFetch, signProvider: sign });
+    const r = await collect(makeBridge(COOKIE_PAYLOAD), {
+      apiClient: client,
+      signProvider: sign,
+      stagingDir: os.tmpdir(),
+    });
+    expect(r.profileFetchFailed).toBe(true);
+    expect(r.uid).toBe("12345"); // cookie-derived
+    expect(r.lastErrorCode).toBe(16); // headline profile error preserved
+    expect(r.lastErrorMessage).toBe("该应用无权限");
+    expect(r.eventCounts.profile).toBe(0); // no profile event
+    expect(r.eventCounts.feed).toBe(1); // ← previously 0 (aborted before signing)
+    expect(r.eventCounts.collection).toBe(1);
+    expect(r.eventCounts.search).toBe(1);
+    expect(r.eventCounts.total).toBe(3);
+  });
+
+  it("profile error_code 16 + NO cookie uid → recovers uid from local account_db, collects signed endpoints", async () => {
+    // Real-device 2026-06-11: web profile permission-denied AND the WebView
+    // cookie jar has no numeric uid. The collector asks the bridge for
+    // 'toutiao.account' (local account_db) and proceeds with that uid.
+    const { fakeFetch } = makeFakeFetch([
+      [
+        "passport/account/info/v2",
+        { body: JSON.stringify({ message: "error", data: { error_code: 16, description: "该应用无权限" } }) },
+      ],
+      ...HAPPY_RESPONSES.slice(1),
+    ]);
+    const sign = {
+      warmUp: vi.fn(async () => {}),
+      signUrl: vi.fn(async (url) => {
+        const u = new URL(String(url));
+        u.searchParams.set("_signature", "BRIDGE_SIG");
+        return u;
+      }),
+      shutdown: vi.fn(async () => {}),
+    };
+    const bridge = {
+      invoke: vi.fn(async (m) => {
+        if (m === "toutiao.cookies") return { cookie: "sessionid=abc", uid: null, diagnostic: {} };
+        if (m === "toutiao.account") return { uid: "92585279158", nickname: "小明", secUid: "MS4w" };
+        throw new Error("unknown " + m);
+      }),
+    };
+    const client = new ToutiaoApiClient({ fetch: fakeFetch, signProvider: sign });
+    const r = await collect(bridge, { apiClient: client, signProvider: sign, stagingDir: os.tmpdir() });
+    expect(r.profileFetchFailed).toBe(true);
+    expect(r.profileSource).toBe("local-account-db");
+    expect(r.uid).toBe("92585279158");
+    expect(r.nickname).toBe("小明");
+    expect(r.lastErrorCode).toBe(16); // headline web error preserved
+    expect(r.eventCounts.profile).toBe(1); // profile event from local account
+    expect(r.eventCounts.feed).toBe(1);
+    expect(r.eventCounts.collection).toBe(1);
+    expect(r.eventCounts.search).toBe(1);
+  });
 });
 
 describe("collect — bridge warmUp failure", () => {

package/__tests__/adapters/social-toutiao-adb-cookies-extension.test.js

@@ -161,3 +161,33 @@ describe("createToutiaoCookiesExtension", () => {
     ).rejects.toThrow(/ctx must provide/);
   });
 });
+
+describe("pullCookiesViaSu — installed-vs-not-installed diagnosis", () => {
+  function makeAdb({ ls, pm }) {
+    return async (args) => {
+      const cmd = args.join(" ");
+      if (cmd.includes("pm list packages")) return pm || "";
+      if (cmd.includes("ls ")) return ls;
+      throw new Error("fake adb: unexpected command " + cmd);
+    };
+  }
+
+  it("throws TOUTIAO_NOT_INSTALLED when cookies absent AND package not installed", async () => {
+    const adb = makeAdb({ ls: "NOT_FOUND\r\n", pm: "" });
+    await expect(
+      _internals.pullCookiesViaSu(adb, "serial", {}),
+    ).rejects.toThrow(/TOUTIAO_NOT_INSTALLED/);
+  });
+
+  it("throws TOUTIAO_NO_WEBVIEW_COOKIES when cookies absent but package installed (real-device 2026-06-11)", async () => {
+    // Verified on device 5lhyaqu8lbwstc6x: com.ss.android.article.news
+    // installed but no webview cookie store → must NOT say NOT_INSTALLED.
+    const adb = makeAdb({
+      ls: "NOT_FOUND\r\n",
+      pm: "package:com.ss.android.article.news\r\n",
+    });
+    await expect(
+      _internals.pullCookiesViaSu(adb, "serial", {}),
+    ).rejects.toThrow(/TOUTIAO_NO_WEBVIEW_COOKIES/);
+  });
+});

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