@chainlesschain/personal-data-hub 0.2.2 → 0.2.3

package/__tests__/adapters/social-toutiao-kuaishou-scaffold.test.js

@@ -1,14 +1,18 @@
 /**
- * Phase 13.8+13.9 — Toutiao 今日头条 + Kuaishou 快手 v0.1 scaffold tests.
+ * §A8 v0.2 — Toutiao 今日头条 + Kuaishou 快手 sqlite-mode tests.
+ *
+ * Originally Phase 13.8+13.9 v0.1 scaffold tests; promoted in §A8 v0.2 to
+ * cover the dual-mode (snapshot + sqlite) adapter. Snapshot-mode coverage
+ * lives in `../social-{toutiao,kuaishou}-snapshot.test.js`; this file
+ * focuses on the legacy sqlite/device-pull path that desktop wiring still
+ * uses for PCs running AndroidExtractor.
  *
- * Tests are intentionally focused on scaffold-quality guarantees:
  *   - Adapter contract conformance (assertAdapter ok)
- *   - Account validation (rejects missing uid)
  *   - sync() yields raw rows per `kind` from mocked SQLite driver
  *   - normalize() produces valid UnifiedSchema events with correct subtype
- *
- * Field-level assertions intentionally avoided — schema is待 fixture pin
- * in Phase 13.10 (real-device E2E).
+ *   - Account validation lazy-checked at sync() time (v0.2 changed:
+ *     account.uid is now OPTIONAL at construction so snapshot-mode-only
+ *     callers can omit it).
  */
 
 "use strict";
@@ -50,18 +54,37 @@ function withFakeDb(fn) {
 
 // ─── ToutiaoAdapter ─────────────────────────────────────────────────────
 
-describe("ToutiaoAdapter — Phase 13.8(+) v0.1 scaffold", () => {
+describe("ToutiaoAdapter — §A8 v0.2 sqlite mode", () => {
   it("contract conformance + sensitivity high (news reading reveals political/medical interest)", () => {
     const a = new ToutiaoAdapter({ account: { uid: "u-1" } });
     expect(assertAdapter(a).ok).toBe(true);
     expect(a.name).toBe("social-toutiao");
     expect(a.extractMode).toBe("device-pull");
     expect(a.dataDisclosure.sensitivity).toBe("high");
+    // v0.2 dual-mode capabilities — adapter accepts both snapshot and sqlite.
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
+  });
+
+  it("v0.2: account OPTIONAL at construction (snapshot mode is stateless)", () => {
+    // Used to throw in v0.1 — now legal. Sqlite-mode sync() will lazy-throw.
+    expect(() => new ToutiaoAdapter()).not.toThrow();
+    expect(() => new ToutiaoAdapter({})).not.toThrow();
+    expect(() => new ToutiaoAdapter({ account: {} })).not.toThrow();
   });
 
-  it("rejects missing account.uid", () => {
-    expect(() => new ToutiaoAdapter({})).toThrow();
-    expect(() => new ToutiaoAdapter({ account: {} })).toThrow(/uid/);
+  it("sqlite mode lazy-throws when account.uid missing at sync time", async () => {
+    const a = new ToutiaoAdapter({ dbPath: "/no/such/path.db" });
+    let threw = null;
+    try {
+      for await (const _r of a.sync()) {
+        /* drain */
+      }
+    } catch (err) {
+      threw = err;
+    }
+    expect(threw).toBeTruthy();
+    expect(String(threw.message)).toMatch(/account\.uid required/);
   });
 
   it("sync yields read + collection + search raws via mocked driver", async () => {
@@ -130,9 +153,11 @@ describe("ToutiaoAdapter — Phase 13.8(+) v0.1 scaffold", () => {
     }
   });
 
-  it("normalize throws on missing payload.row (validator-friendly)", () => {
+  it("normalize throws on missing payload row + no snapshot fields (validator-friendly)", () => {
     const a = new ToutiaoAdapter({ account: { uid: "u-1" } });
-    expect(() => a.normalize({ payload: {} })).toThrow(/row missing/);
+    // v0.2: row-missing check moved into per-kind normalizers (snapshot
+    // payloads have no `row` but carry fields directly).
+    expect(() => a.normalize({ payload: { kind: "read" } })).toThrow(/row missing/);
   });
 
   it("search keyword preserved verbatim in content.title + extra.keyword", () => {
@@ -158,18 +183,35 @@ describe("ToutiaoAdapter — Phase 13.8(+) v0.1 scaffold", () => {
 
 // ─── KuaishouAdapter ────────────────────────────────────────────────────
 
-describe("KuaishouAdapter — Phase 13.9(+) v0.1 scaffold", () => {
+describe("KuaishouAdapter — §A8 v0.2 sqlite mode", () => {
   it("contract conformance + sensitivity medium (entertainment preference)", () => {
     const a = new KuaishouAdapter({ account: { uid: "u-2" } });
     expect(assertAdapter(a).ok).toBe(true);
     expect(a.name).toBe("social-kuaishou");
     expect(a.extractMode).toBe("device-pull");
     expect(a.dataDisclosure.sensitivity).toBe("medium");
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
+  });
+
+  it("v0.2: account OPTIONAL at construction (snapshot mode is stateless)", () => {
+    expect(() => new KuaishouAdapter()).not.toThrow();
+    expect(() => new KuaishouAdapter({})).not.toThrow();
+    expect(() => new KuaishouAdapter({ account: {} })).not.toThrow();
   });
 
-  it("rejects missing account.uid", () => {
-    expect(() => new KuaishouAdapter({})).toThrow();
-    expect(() => new KuaishouAdapter({ account: {} })).toThrow(/uid/);
+  it("sqlite mode lazy-throws when account.uid missing at sync time", async () => {
+    const a = new KuaishouAdapter({ dbPath: "/no/such/path.db" });
+    let threw = null;
+    try {
+      for await (const _r of a.sync()) {
+        /* drain */
+      }
+    } catch (err) {
+      threw = err;
+    }
+    expect(threw).toBeTruthy();
+    expect(String(threw.message)).toMatch(/account\.uid required/);
   });
 
   it("sync yields watch + collect + search raws via mocked driver", async () => {

package/__tests__/longtail-adapters.test.js

@@ -84,10 +84,17 @@ describe("XiaohongshuAdapter", () => {
   it("contract conformance", () => {
     const a = new XiaohongshuAdapter({ account: { uid: "u-1" } });
     expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
   });
 
-  it("rejects missing account.uid", () => {
-    expect(() => new XiaohongshuAdapter({ account: {} })).toThrow(/uid/);
+  it("snapshot mode constructs without account.uid (stateless)", () => {
+    // §A8 v0.2: constructor loosened — snapshot mode pulls account from the
+    // snapshot file. Sqlite mode still requires account.uid, checked at sync
+    // time not construction.
+    const a = new XiaohongshuAdapter({});
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.account).toBeNull();
   });
 
   it("sync yields history + likes + favourites", async () => {
@@ -118,17 +125,39 @@ describe("QQAdapter", () => {
     const a = new QQAdapter({ account: { qq: "12345" } });
     expect(assertAdapter(a).ok).toBe(true);
     expect(a.dataDisclosure.legalGate).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
+  });
+
+  it("snapshot mode constructs without account.qq (stateless)", () => {
+    // §Phase 13.5 v0.2: constructor loosened — snapshot mode pulls account
+    // from the snapshot file. Sqlite mode still requires account.qq, checked
+    // at sync time not construction. Mirror of weibo / bilibili A8 pattern.
+    const a = new QQAdapter({});
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.account).toBeNull();
   });
 
-  it("rejects missing account.qq", () => {
-    expect(() => new QQAdapter({ account: {} })).toThrow(/qq/);
+  it("sqlite mode throws at sync time when account.qq missing", async () => {
+    const { dir, dbPath } = tmpDb();
+    try {
+      const a = new QQAdapter({ dbPath, keyProvider: { getKey: async () => "k" } });
+      let threw = null;
+      try {
+        for await (const _r of a.sync()) { /* drain */ }
+      } catch (err) {
+        threw = err;
+      }
+      expect(threw).toBeTruthy();
+      expect(String(threw.message)).toMatch(/account\.qq/);
+    } finally { cleanup(dir); }
   });
 
-  it("authenticate fails without DB", async () => {
+  it("authenticate({}) without inputPath nor dbPath returns NO_INPUT", async () => {
     const a = new QQAdapter({ account: { qq: "12345" }, keyProvider: { getKey: async () => "k" } });
     const r = await a.authenticate();
     expect(r.ok).toBe(false);
-    expect(r.reason).toBe("DB_NOT_PULLED");
+    expect(r.reason).toBe("NO_INPUT");
   });
 
   it("authenticate fails without keyProvider", async () => {
@@ -143,27 +172,44 @@ describe("QQAdapter", () => {
   it("sync yields contact + group + message types", async () => {
     const { dir, dbPath } = tmpDb();
     try {
+      // §Phase 13.5 v0.2 mock — new SQL targets:
+      //   - Friends / friends / tb_recent_contact (probe order)
+      //   - TroopInfoV2
+      //   - sqlite_master LIKE 'mr_friend_%_New'
+      //   - mr_friend_<MD5(peer).upper()>_New
       const mockDriver = makeMockDriver([
-        ["FROM mr_friend", [{ uin: "999", nickname: "好友A", remark: "" }]],
-        ["FROM mr_troop", [{ troop_uin: "888", troop_name: "测试群" }]],
-        ["FROM sqlite_master", [{ name: "msgcsr_friend_999" }]],
-        ["FROM msgcsr_friend_999", [{ msgid: "m1", msg: "你好", time: 1700000000, frienduin: "999", msgtype: 1 }]],
+        ["FROM Friends", [{ uin: "999", nickname: "好友A", remark: "" }]],
+        ["FROM TroopInfoV2", [{ troop_uin: "888", troop_name: "测试群", member_count: 5, owner_uin: "777" }]],
+        ["FROM sqlite_master", [{ name: "mr_friend_ABCDEF1234_New" }]],
+        [
+          "FROM mr_friend_ABCDEF1234_New",
+          [{
+            msgId: "m1", msgtype: -1000, senderuin: "999", time: 1700000000,
+            // msgData is XOR-encrypted bytes; with imei="123456789012345" key,
+            // "hi" encrypts to bytes [0x51, 0x5d] (0x68^0x31=0x59 — actually
+            // depends on imei[0] = '1' = 0x31). Use Buffer for cross-platform.
+            msgData: Buffer.from([0x68 ^ 0x31, 0x69 ^ 0x32]),
+            issend: 0, frienduin: "999", troopuin: null,
+          }],
+        ],
       ]);
       const a = new QQAdapter({
         account: { qq: "12345" },
         dbPath,
-        keyProvider: { getKey: async () => "fakekey" },
+        keyProvider: { getKey: async () => "123456789012345" },
         dbDriverFactory: () => mockDriver,
       });
       const raws = [];
       for await (const r of a.sync()) raws.push(r);
       expect(raws.length).toBe(3); // contact + group + message
-      const contact = raws.find((r) => r.payload.kind === "contact");
-      const group = raws.find((r) => r.payload.kind === "group");
-      const message = raws.find((r) => r.payload.kind === "message");
+      const contact = raws.find((r) => r.kind === "contact");
+      const group = raws.find((r) => r.kind === "group");
+      const message = raws.find((r) => r.kind === "message");
       expect(contact).toBeDefined();
       expect(group).toBeDefined();
       expect(message).toBeDefined();
+      // XOR-decrypt round-trip: bytes(0x68^0x31, 0x69^0x32) XOR "12" = "hi"
+      expect(message.payload.text).toBe("hi");
       for (const r of raws) {
         expect(validateBatch(a.normalize(r)).valid).toBe(true);
       }

package/__tests__/messaging-qq-snapshot.test.js

@@ -0,0 +1,294 @@
+"use strict";
+
+import { describe, it, expect, beforeEach } from "vitest";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const {
+  QQAdapter,
+  SNAPSHOT_SCHEMA_VERSION,
+  VALID_SNAPSHOT_KINDS,
+  xorDecrypt,
+} = require("../lib/adapters/messaging-qq");
+const { validateBatch } = require("../lib/batch");
+
+// §Phase 13.5 v0.2 (2026-05-22) — snapshot-mode tests, mirror of
+// social-weibo-snapshot.test.js.
+//
+// Snapshot mode is in-APK Android cc reading JSON written by QQLocalCollector
+// (su cp /data/data/com.tencent.mobileqq/databases/<uin>.db + plain SQLite
+// open + per-row XOR-with-IMEI decrypt of msgData). Sqlite/device-pull tests
+// stay in longtail-adapters.test.js. Both paths share normalize().
+
+function writeSnapshot(dir, snapshot) {
+  const p = path.join(dir, "messaging-qq.json");
+  fs.writeFileSync(p, JSON.stringify(snapshot), "utf-8");
+  return p;
+}
+
+describe("QQAdapter snapshot mode", () => {
+  let tmpDir;
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "qq-snap-"));
+  });
+
+  it("exports SNAPSHOT_SCHEMA_VERSION = 1 + 3 VALID_SNAPSHOT_KINDS", () => {
+    expect(SNAPSHOT_SCHEMA_VERSION).toBe(1);
+    expect(VALID_SNAPSHOT_KINDS).toEqual(["contact", "group", "message"]);
+  });
+
+  it("authenticate(inputPath) ok when readable", async () => {
+    const p = writeSnapshot(tmpDir, {
+      schemaVersion: 1,
+      snapshottedAt: Date.now(),
+      events: [],
+    });
+    const a = new QQAdapter();
+    const res = await a.authenticate({ inputPath: p });
+    expect(res.ok).toBe(true);
+    expect(res.mode).toBe("snapshot-file");
+  });
+
+  it("authenticate(inputPath) fails when path unreadable", async () => {
+    const a = new QQAdapter();
+    const res = await a.authenticate({ inputPath: path.join(tmpDir, "missing.json") });
+    expect(res.ok).toBe(false);
+    expect(res.reason).toBe("INPUT_PATH_UNREADABLE");
+  });
+
+  it("authenticate() with neither inputPath nor dbPath returns NO_INPUT", async () => {
+    const a = new QQAdapter();
+    const res = await a.authenticate({});
+    expect(res.ok).toBe(false);
+    expect(res.reason).toBe("NO_INPUT");
+  });
+
+  it("rejects schemaVersion mismatch", async () => {
+    const p = writeSnapshot(tmpDir, {
+      schemaVersion: 99,
+      snapshottedAt: Date.now(),
+      events: [],
+    });
+    const a = new QQAdapter();
+    let threw = null;
+    try {
+      for await (const _r of a.sync({ inputPath: p })) { /* drain */ }
+    } catch (err) {
+      threw = err;
+    }
+    expect(threw).toBeTruthy();
+    expect(String(threw.message)).toMatch(/schemaVersion mismatch/);
+  });
+
+  it("empty events array yields nothing (no crash)", async () => {
+    const p = writeSnapshot(tmpDir, {
+      schemaVersion: 1,
+      snapshottedAt: Date.now(),
+      events: [],
+    });
+    const a = new QQAdapter();
+    const raws = [];
+    for await (const r of a.sync({ inputPath: p })) raws.push(r);
+    expect(raws.length).toBe(0);
+  });
+
+  it("contact + group + message round-trip normalize cleanly", async () => {
+    const now = Date.now();
+    const p = writeSnapshot(tmpDir, {
+      schemaVersion: 1,
+      snapshottedAt: now,
+      account: { qq: "12345", displayName: "alice" },
+      events: [
+        {
+          kind: "contact",
+          id: "contact-99999",
+          capturedAt: now - 1000,
+          uin: "99999",
+          nickname: "好友A",
+          remark: "工作组",
+        },
+        {
+          kind: "group",
+          id: "group-88888",
+          capturedAt: now - 2000,
+          troopUin: "88888",
+          troopName: "测试群",
+          memberCount: 30,
+          ownerUin: "77777",
+        },
+        {
+          kind: "message",
+          id: "msg-m1",
+          capturedAt: now - 3000,
+          msgId: "m1",
+          msgType: -1000,
+          senderUin: "99999",
+          peerUin: "12345",
+          isGroup: false,
+          isSend: false,
+          text: "你好",
+        },
+      ],
+    });
+    const a = new QQAdapter();
+    const raws = [];
+    for await (const r of a.sync({ inputPath: p })) raws.push(r);
+    expect(raws.length).toBe(3);
+
+    const kinds = raws.map((r) => r.kind);
+    expect(kinds).toEqual(["contact", "group", "message"]);
+
+    // Each originalId namespaced under qq:<kind>:<id>
+    expect(raws[0].originalId).toMatch(/^qq:contact:/);
+    expect(raws[1].originalId).toMatch(/^qq:group:/);
+    expect(raws[2].originalId).toMatch(/^qq:message:/);
+
+    // Normalize each + validate
+    for (const raw of raws) {
+      const batch = a.normalize(raw);
+      expect(validateBatch(batch).valid).toBe(true);
+    }
+
+    const contactBatch = a.normalize(raws[0]);
+    expect(contactBatch.events.length).toBe(0);
+    expect(contactBatch.persons.length).toBe(1);
+    // remark + nickname + uin all surface as names (priority order)
+    expect(contactBatch.persons[0].names).toEqual(["工作组", "好友A", "99999"]);
+    expect(contactBatch.persons[0].identifiers["qq-uin"]).toEqual(["99999"]);
+
+    const groupBatch = a.normalize(raws[1]);
+    expect(groupBatch.events.length).toBe(0);
+    expect(groupBatch.topics.length).toBe(1);
+    expect(groupBatch.topics[0].name).toBe("测试群");
+    expect(groupBatch.topics[0].extra.troopUin).toBe("88888");
+    expect(groupBatch.topics[0].extra.memberCount).toBe(30);
+
+    const msgBatch = a.normalize(raws[2]);
+    expect(msgBatch.events.length).toBe(1);
+    expect(msgBatch.events[0].subtype).toBe("message");
+    expect(msgBatch.events[0].extra.peerUin).toBe("12345");
+    expect(msgBatch.events[0].extra.senderUin).toBe("99999");
+    expect(msgBatch.events[0].extra.isGroup).toBe(false);
+    expect(msgBatch.events[0].extra.isSend).toBe(false);
+    expect(msgBatch.events[0].content.text).toBe("你好");
+  });
+
+  it("respects per-kind include opt-out", async () => {
+    const now = Date.now();
+    const p = writeSnapshot(tmpDir, {
+      schemaVersion: 1,
+      snapshottedAt: now,
+      events: [
+        { kind: "contact", id: "c1", capturedAt: now, uin: "100", nickname: "A" },
+        { kind: "group", id: "g1", capturedAt: now, troopUin: "200", troopName: "G" },
+        { kind: "message", id: "m1", capturedAt: now, msgId: "m1", text: "hi" },
+      ],
+    });
+    const a = new QQAdapter();
+    const raws = [];
+    for await (const r of a.sync({ inputPath: p, include: { message: false } })) {
+      raws.push(r);
+    }
+    const kinds = raws.map((r) => r.kind);
+    expect(kinds).toEqual(["contact", "group"]);
+  });
+
+  it("respects opts.limit", async () => {
+    const now = Date.now();
+    const events = Array.from({ length: 5 }, (_, i) => ({
+      kind: "message",
+      id: `m${i}`,
+      capturedAt: now - i * 100,
+      msgId: `m${i}`,
+      text: `t${i}`,
+    }));
+    const p = writeSnapshot(tmpDir, { schemaVersion: 1, snapshottedAt: now, events });
+    const a = new QQAdapter();
+    const raws = [];
+    for await (const r of a.sync({ inputPath: p, limit: 2 })) raws.push(r);
+    expect(raws.length).toBe(2);
+  });
+
+  it("filters out unknown kinds (forward compat)", async () => {
+    const now = Date.now();
+    const p = writeSnapshot(tmpDir, {
+      schemaVersion: 1,
+      snapshottedAt: now,
+      events: [
+        { kind: "contact", id: "c1", capturedAt: now, uin: "100", nickname: "A" },
+        { kind: "future-kind", id: "x", capturedAt: now },
+        { kind: "search", id: "s", capturedAt: now }, // not a QQ snapshot kind
+      ],
+    });
+    const a = new QQAdapter();
+    const raws = [];
+    for await (const r of a.sync({ inputPath: p })) raws.push(r);
+    expect(raws.length).toBe(1);
+    expect(raws[0].kind).toBe("contact");
+  });
+
+  it("snapshottedAt fallback when event capturedAt missing", async () => {
+    const ts = 1700000000000;
+    const p = writeSnapshot(tmpDir, {
+      schemaVersion: 1,
+      snapshottedAt: ts,
+      events: [
+        { kind: "contact", id: "c1", uin: "100", nickname: "A" },
+      ],
+    });
+    const a = new QQAdapter();
+    const raws = [];
+    for await (const r of a.sync({ inputPath: p })) raws.push(r);
+    expect(raws[0].capturedAt).toBe(ts);
+  });
+
+  it("normalize handles missing identifiers gracefully (forward compat)", () => {
+    const a = new QQAdapter();
+    // Contact with empty payload — uin/nickname/remark all absent
+    const raw = {
+      adapter: "messaging-qq",
+      kind: "contact",
+      originalId: "qq:contact:unknown",
+      capturedAt: Date.now(),
+      payload: { kind: "contact" },
+    };
+    const batch = a.normalize(raw);
+    expect(batch.persons.length).toBe(1);
+    expect(batch.persons[0].names).toEqual(["(unnamed)"]);
+    expect(validateBatch(batch).valid).toBe(true);
+  });
+
+  it("xorDecrypt: empty input or empty key returns empty string", () => {
+    expect(xorDecrypt(null, Buffer.from("123"))).toBe("");
+    expect(xorDecrypt(Buffer.from(""), Buffer.from("123"))).toBe("");
+    expect(xorDecrypt(Buffer.from("hi"), Buffer.from(""))).toBe("");
+  });
+
+  it("xorDecrypt: ASCII round-trip via IMEI XOR (sjqz qq.py parity)", () => {
+    // Algorithm: out[i] = data[i] XOR imeiBytes[i % imeiLen]. Encryption is
+    // its own inverse: XOR-decrypt the encrypted form ⇒ original plaintext.
+    const imei = "123456789012345";
+    const plaintext = "hello";
+    const imeiBytes = Buffer.from(imei, "utf-8");
+    const ptBytes = Buffer.from(plaintext, "utf-8");
+    const encrypted = Buffer.alloc(ptBytes.length);
+    for (let i = 0; i < ptBytes.length; i++) {
+      encrypted[i] = ptBytes[i] ^ imeiBytes[i % imeiBytes.length];
+    }
+    expect(xorDecrypt(encrypted, imeiBytes)).toBe(plaintext);
+  });
+
+  it("xorDecrypt: UTF-8 multibyte (Chinese) round-trip", () => {
+    const imei = "999000111222333";
+    const plaintext = "你好世界";
+    const imeiBytes = Buffer.from(imei, "utf-8");
+    const ptBytes = Buffer.from(plaintext, "utf-8");
+    const encrypted = Buffer.alloc(ptBytes.length);
+    for (let i = 0; i < ptBytes.length; i++) {
+      encrypted[i] = ptBytes[i] ^ imeiBytes[i % imeiBytes.length];
+    }
+    expect(xorDecrypt(encrypted, imeiBytes)).toBe(plaintext);
+  });
+});