@chainlesschain/personal-data-hub 0.4.23 → 0.4.24

package/__tests__/adapters/bank-family.test.js

@@ -0,0 +1,125 @@
+"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 base = require("../../lib/adapters/_bank-base");
+const cmbc = require("../../lib/adapters/bank-cmbc");
+const boc = require("../../lib/adapters/bank-boc");
+const bankcomm = require("../../lib/adapters/bank-bankcomm");
+const icbc = require("../../lib/adapters/bank-icbc");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-bank-${crypto.randomUUID()}.json`);
+  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;
+}
+const COOKIES = "MBANK_SSO=abc; sid=xyz";
+
+describe("_bank-base helpers", () => {
+  it("normDirection: keyword + amount-sign fallback", () => {
+    expect(base.normDirection({ direction: "收入" })).toBe("credit");
+    expect(base.normDirection({ flag: "支出" })).toBe("debit");
+    expect(base.normDirection({ amount: -50 })).toBe("debit");
+    expect(base.normDirection({ amount: 50 })).toBe("credit");
+  });
+  it("mapTransaction / mapCard aliases; no id → null", () => {
+    const tx = base.mapTransaction({ serialNo: "T1", tranTime: 1716383000, tranAmount: "-1,234.56", oppName: "星巴克", abstract: "消费", bal: 9999 });
+    expect(tx).toMatchObject({ txId: "T1", direction: "debit", counterparty: "星巴克", summary: "消费" });
+    expect(tx.amount).toBeCloseTo(1234.56, 2);
+    expect(tx.balance).toBe(9999);
+    expect(base.mapTransaction({ amount: 1 })).toBe(null);
+    const card = base.mapCard({ billId: "B1", billMonth: "2025-03", statementAmount: 3210, minPayment: 321, status: "已出账" });
+    expect(card).toMatchObject({ billId: "B1", billMonth: "2025-03", statementAmount: 3210, status: "已出账" });
+    expect(base.mapCard({ status: "x" })).toBe(null);
+  });
+  it("billMonthToMs", () => {
+    expect(base.billMonthToMs("2025-03")).toBe(Date.parse("2025-03-01T00:00:00Z"));
+  });
+});
+
+describe("bank wrappers identity", () => {
+  it("each wrapper has its own name + adapter class", () => {
+    expect(cmbc.NAME).toBe("bank-cmbc");
+    expect(boc.NAME).toBe("bank-boc");
+    expect(bankcomm.NAME).toBe("bank-bankcomm");
+    expect(icbc.NAME).toBe("bank-icbc");
+    expect(new cmbc.CmbcBankAdapter().name).toBe("bank-cmbc");
+    expect(new boc.BocBankAdapter().name).toBe("bank-boc");
+    expect(new bankcomm.BankcommBankAdapter().name).toBe("bank-bankcomm");
+    expect(new icbc.IcbcBankAdapter().name).toBe("bank-icbc");
+  });
+  it("all gated high sensitivity + legalGate", () => {
+    for (const A of [new cmbc.CmbcBankAdapter(), new boc.BocBankAdapter(), new bankcomm.BankcommBankAdapter(), new icbc.IcbcBankAdapter()]) {
+      expect(A.dataDisclosure.sensitivity).toBe("high");
+      expect(A.dataDisclosure.legalGate).toBe(true);
+    }
+  });
+});
+
+describe("CmbcBankAdapter (via _bank-base)", () => {
+  const SNAP = JSON.stringify({
+    schemaVersion: 1,
+    snapshottedAt: 1716383000000,
+    account: { userId: "u1" },
+    events: [
+      { kind: "transaction", id: "tx-T1", txId: "T1", time: 1716383000, amount: -88.5, direction: "支出", counterparty: "全家", summary: "消费", balance: 1200 },
+      { kind: "card", id: "card-C1", billId: "C1", billMonth: "2025-03", statementAmount: 3210, minPayment: 321, status: "已出账" },
+    ],
+  });
+
+  it("transaction → PAYMENT event; card → OTHER event", async () => {
+    const p = writeTmp(SNAP);
+    try {
+      const a = new cmbc.CmbcBankAdapter();
+      expect((await a.authenticate({ inputPath: p })).mode).toBe("snapshot-file");
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(2);
+      const tx = a.normalize(items[0]);
+      expect(tx.events[0].subtype).toBe("payment");
+      expect(tx.events[0].content.title).toContain("支出");
+      expect(tx.events[0].extra.amount).toBe(88.5);
+      expect(tx.events[0].extra.direction).toBe("debit");
+      expect(items[0].originalId).toBe("cmbc:transaction:T1");
+      const card = a.normalize(items[1]);
+      expect(card.events[0].subtype).toBe("other");
+      expect(card.events[0].extra.billMonth).toBe("2025-03");
+      expect(items[1].originalId).toBe("cmbc:card:C1");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("cookie-api: best-effort fetch + unverified + sign seam", async () => {
+    let signed = 0;
+    const a = new cmbc.CmbcBankAdapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      signProvider: async () => { signed += 1; return "sig"; },
+      fetchFn: async ({ url, query }) => {
+        if (query.page > 1) return { list: [] };
+        if (url.includes("transactions")) return { list: [{ txId: "T9", time: 1716383000, amount: 500, direction: "收入", summary: "工资" }] };
+        return { list: [{ billId: "C9", billMonth: "2025-02", statementAmount: 1000 }] };
+      },
+    });
+    expect(await a.authenticate()).toMatchObject({ ok: true, mode: "cookie", unverified: true });
+    const items = await collect(a.sync({}));
+    expect(items).toHaveLength(2);
+    expect(items.map((i) => i.originalId).sort()).toEqual(["cmbc:card:C9", "cmbc:transaction:T9"]);
+    expect(signed).toBeGreaterThan(0);
+  });
+
+  it("default fetch throws; no input throws", async () => {
+    const a = new cmbc.CmbcBankAdapter({ account: { cookies: COOKIES } });
+    await expect(collect(a.sync({}))).rejects.toThrow(/no fetchFn configured/);
+    const b = new cmbc.CmbcBankAdapter();
+    await expect(collect(b.sync({}))).rejects.toThrow(/needs opts.inputPath/);
+  });
+});

package/__tests__/adapters/car-mercedesme.test.js

@@ -0,0 +1,74 @@
+"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 mb = require("../../lib/adapters/car-mercedesme");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-mb-${crypto.randomUUID()}.json`);
+  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;
+}
+const COOKIES = "mb_token=abc";
+
+describe("car-mercedesme", () => {
+  it("name + tripToRecord (km direct + meters fallback; no id → null)", () => {
+    expect(mb.NAME).toBe("car-mercedesme");
+    const r = mb.tripToRecord({ tripId: "T1", startTime: 1716383000, endTime: 1716385000, startAddress: "家", endAddress: "公司", distanceKm: 12.4, plate: "京A12345" });
+    expect(r).toMatchObject({ vendorId: "mercedesme", recordId: "T1", vehicleType: "car", carrier: "Mercedes me", vehicleNumber: "京A12345" });
+    expect(r.from.name).toBe("家");
+    expect(r.to.name).toBe("公司");
+    expect(r.extras.distanceKm).toBeCloseTo(12.4, 2);
+    // meters fallback
+    expect(mb.tripToRecord({ tripId: "T2", distanceMeters: 5230 }).extras.distanceKm).toBeCloseTo(5.23, 2);
+    expect(mb.tripToRecord({ startAddress: "x" })).toBe(null);
+  });
+  it("extractTrips tolerant", () => {
+    expect(mb.extractTrips({ trips: [{ tripId: 1 }] })).toHaveLength(1);
+    expect(mb.extractTrips({ data: { list: [{ tripId: 1 }] } })).toHaveLength(1);
+    expect(mb.extractTrips({})).toEqual([]);
+  });
+
+  it("snapshot trip → car travel event", async () => {
+    const SNAP = JSON.stringify({ trips: [{ tripId: "T1", startTime: 1716383000, endTime: 1716385000, startAddress: "家", endAddress: "公司", distanceKm: 12.4 }] });
+    const p = writeTmp(SNAP);
+    try {
+      const a = new mb.MercedesMeAdapter();
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(1);
+      expect(items[0].originalId).toBe("T1");
+      const b = a.normalize(items[0]);
+      expect(b.events[0].source.adapter).toBe("car-mercedesme");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("cookie-api: unverified + sign seam", async () => {
+    let signed = 0;
+    const a = new mb.MercedesMeAdapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      signProvider: async () => { signed += 1; return "sig"; },
+      fetchFn: async ({ query }) => (query.page > 1 ? { trips: [] } : { trips: [{ tripId: "T9", startTime: 1716383000, distanceMeters: 8000 }] }),
+    });
+    expect(await a.authenticate()).toMatchObject({ ok: true, mode: "cookie", unverified: true });
+    const items = await collect(a.sync({}));
+    expect(items).toHaveLength(1);
+    expect(items[0].originalId).toBe("T9");
+    expect(signed).toBeGreaterThan(0);
+  });
+
+  it("medium sensitivity; default fetch throws", async () => {
+    expect(new mb.MercedesMeAdapter().dataDisclosure.sensitivity).toBe("medium");
+    await expect(collect(new mb.MercedesMeAdapter({ account: { cookies: COOKIES } }).sync({}))).rejects.toThrow(/no fetchFn/);
+  });
+});

package/__tests__/adapters/finance-dcep.test.js

@@ -0,0 +1,74 @@
+"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 dc = require("../../lib/adapters/finance-dcep");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-dcep-${crypto.randomUUID()}.json`);
+  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;
+}
+const COOKIES = "DCEP_SSO=abc";
+
+describe("finance-dcep", () => {
+  it("name/version + mappers", () => {
+    expect(dc.NAME).toBe("finance-dcep");
+    expect(dc.normDirection({ direction: "收款" })).toBe("receive");
+    expect(dc.normDirection({ amount: -5 })).toBe("pay");
+    const t = dc.mapTx({ txId: "X1", time: 1716383000, amount: -12.5, merchant: "便利店", subWallet: "中行子钱包" });
+    expect(t).toMatchObject({ txId: "X1", direction: "pay", counterparty: "便利店", walletType: "中行子钱包" });
+    expect(t.amount).toBe(12.5);
+    expect(dc.mapTx({ amount: 1 })).toBe(null);
+  });
+
+  it("snapshot → PAYMENT event; cookie-api unverified + sign", async () => {
+    const SNAP = JSON.stringify({
+      schemaVersion: 1,
+      snapshottedAt: 1716383000000,
+      account: { userId: "u1" },
+      events: [{ kind: "transaction", id: "tx-X1", txId: "X1", time: 1716383000, amount: 12.5, direction: "pay", counterparty: "便利店" }],
+    });
+    const p = writeTmp(SNAP);
+    try {
+      const a = new dc.DcepAdapter();
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(1);
+      const b = a.normalize(items[0]);
+      expect(b.events[0].subtype).toBe("payment");
+      expect(b.events[0].content.title).toContain("付款");
+      expect(b.events[0].extra.amount).toBe(12.5);
+      expect(items[0].originalId).toBe("dcep:transaction:X1");
+    } finally {
+      fs.unlinkSync(p);
+    }
+
+    let signed = 0;
+    const a = new dc.DcepAdapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      signProvider: async () => { signed += 1; return "sig"; },
+      fetchFn: async ({ query }) => (query.page > 1 ? { list: [] } : { list: [{ txId: "X9", time: 1716383000, amount: 9.9, direction: "receive" }] }),
+    });
+    expect(await a.authenticate()).toMatchObject({ ok: true, mode: "cookie", unverified: true });
+    const items = await collect(a.sync({}));
+    expect(items).toHaveLength(1);
+    expect(items[0].originalId).toBe("dcep:transaction:X9");
+    expect(signed).toBeGreaterThan(0);
+  });
+
+  it("high sensitivity + legalGate; default fetch / no input throw", async () => {
+    expect(new dc.DcepAdapter().dataDisclosure.sensitivity).toBe("high");
+    expect(new dc.DcepAdapter().dataDisclosure.legalGate).toBe(true);
+    await expect(collect(new dc.DcepAdapter({ account: { cookies: COOKIES } }).sync({}))).rejects.toThrow(/no fetchFn/);
+    await expect(collect(new dc.DcepAdapter().sync({}))).rejects.toThrow(/needs opts.inputPath/);
+  });
+});

package/__tests__/adapters/fitness-joyrun.test.js

@@ -0,0 +1,82 @@
+"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 jr = require("../../lib/adapters/fitness-joyrun");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-jr-${crypto.randomUUID()}.json`);
+  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;
+}
+const COOKIES = "joyrun_sid=abc";
+
+describe("fitness-joyrun", () => {
+  it("name + mapRun (meter wins; km*1000 fallback; no id → null)", () => {
+    expect(jr.NAME).toBe("fitness-joyrun");
+    const r = jr.mapRun({ fid: "R1", starttime: 1716383000, meter: 5230, second: 1800, pace: 344, dohas: 320, stepcount: 6400 });
+    expect(r).toMatchObject({ runId: "R1", distanceMeters: 5230, durationSec: 1800, paceSecPerKm: 344, calories: 320, steps: 6400 });
+    expect(r.timeMs).toBe(1716383000000);
+    // distance given as km (5.23) with no meter field → *1000
+    expect(jr.mapRun({ id: "R2", distance: 5.23 }).distanceMeters).toBeCloseTo(5230, 0);
+    expect(jr.mapRun({ meter: 100 })).toBe(null);
+  });
+  it("extractList tolerant", () => {
+    expect(jr.extractList({ data: { runs: [{ fid: 1 }] } })).toHaveLength(1);
+    expect(jr.extractList({ list: [{ fid: 1 }] })).toHaveLength(1);
+    expect(jr.extractList({})).toEqual([]);
+  });
+
+  it("snapshot → OTHER event with km title + run extras", async () => {
+    const SNAP = JSON.stringify({
+      schemaVersion: 1,
+      snapshottedAt: 1716383000000,
+      account: { userId: "u1" },
+      events: [{ kind: "run", id: "r-R1", runId: "R1", time: 1716383000, distanceMeters: 5230, durationSec: 1800, paceSecPerKm: 344, calories: 320 }],
+    });
+    const p = writeTmp(SNAP);
+    try {
+      const a = new jr.JoyrunAdapter();
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(1);
+      const b = a.normalize(items[0]);
+      expect(b.events[0].subtype).toBe("other");
+      expect(b.events[0].content.title).toBe("跑步 5.23 km");
+      expect(b.events[0].extra.distanceMeters).toBe(5230);
+      expect(b.events[0].extra.calories).toBe(320);
+      expect(items[0].originalId).toBe("joyrun:run:R1");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("cookie-api: unverified flag + sign seam + paginate", async () => {
+    let signed = 0;
+    const a = new jr.JoyrunAdapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      signProvider: async () => { signed += 1; return "sig"; },
+      fetchFn: async ({ query }) => (query.page > 1 ? { list: [] } : { data: { runs: [{ fid: "R9", starttime: 1716383000, meter: 10000, second: 3600 }] } }),
+    });
+    expect(await a.authenticate()).toMatchObject({ ok: true, mode: "cookie", unverified: true });
+    const items = await collect(a.sync({}));
+    expect(items).toHaveLength(1);
+    expect(items[0].originalId).toBe("joyrun:run:R9");
+    expect(signed).toBeGreaterThan(0);
+  });
+
+  it("medium sensitivity (GPS route); default fetch / no input throw", async () => {
+    expect(new jr.JoyrunAdapter().dataDisclosure.sensitivity).toBe("medium");
+    expect(new jr.JoyrunAdapter().dataDisclosure.legalGate).toBe(false);
+    await expect(collect(new jr.JoyrunAdapter({ account: { cookies: COOKIES } }).sync({}))).rejects.toThrow(/no fetchFn/);
+    await expect(collect(new jr.JoyrunAdapter().sync({}))).rejects.toThrow(/needs opts.inputPath/);
+  });
+});

package/__tests__/adapters/gov-12123.test.js

@@ -0,0 +1,103 @@
+"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 g = require("../../lib/adapters/gov-12123");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-12123-${crypto.randomUUID()}.json`);
+  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;
+}
+const COOKIES = "GAB_SSO=abc";
+
+describe("gov-12123", () => {
+  it("name + mappers (chinese-field aliases)", () => {
+    expect(g.NAME).toBe("gov-12123");
+    const v = g.mapViolation({ wzbh: "V1", wfsj: 1716383000, wfdz: "环岛路", wfxw: "超速50%以下", fkje: "200", wfjfs: "3" });
+    expect(v).toMatchObject({ violationId: "V1", location: "环岛路", reason: "超速50%以下" });
+    expect(v.fine).toBe(200);
+    expect(v.points).toBe(3);
+    expect(g.mapViolation({ wfxw: "x" })).toBe(null);
+    const l = g.mapLicense({ dabh: "L1", zt: "正常", ljjf: 3, yxqz: 1900000000 });
+    expect(l).toMatchObject({ licenseId: "L1", status: "正常", cumulativePoints: 3 });
+    expect(g.mapLicense({ zt: "x" })).toBe(null);
+  });
+  it("extractLicense wraps single object", () => {
+    expect(g.extractLicense({ data: { dabh: "L1" } })).toHaveLength(1);
+    expect(g.extractLicense({ licenseId: "L2" })).toHaveLength(1);
+    expect(g.extractLicense({ list: [{ dabh: "L3" }] })).toHaveLength(1);
+  });
+
+  it("snapshot → violation + license OTHER events", async () => {
+    const SNAP = JSON.stringify({
+      schemaVersion: 1,
+      snapshottedAt: 1716383000000,
+      account: { userId: "u1" },
+      events: [
+        { kind: "violation", id: "v-V1", violationId: "V1", time: 1716383000, location: "环岛路", reason: "超速", fine: 200, points: 3 },
+        { kind: "license", id: "l-L1", licenseId: "L1", status: "正常", cumulativePoints: 3, validUntil: 1900000000 },
+      ],
+    });
+    const p = writeTmp(SNAP);
+    try {
+      const a = new g.Tmri12123Adapter();
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(2);
+      const v = a.normalize(items[0]);
+      expect(v.events[0].subtype).toBe("other");
+      expect(v.events[0].content.title).toContain("交通违章");
+      expect(v.events[0].extra.fine).toBe(200);
+      expect(v.events[0].extra.points).toBe(3);
+      expect(items[0].originalId).toBe("12123:violation:V1");
+      const l = a.normalize(items[1]);
+      expect(l.events[0].content.title).toContain("驾驶证状态");
+      expect(l.events[0].extra.cumulativePoints).toBe(3);
+      expect(items[1].originalId).toBe("12123:license:L1");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("cookie-api: paginated violations + single license + unverified", async () => {
+    const a = new g.Tmri12123Adapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      fetchFn: async ({ url, query }) => {
+        if (url.includes("/violation")) return query.page > 1 ? { list: [] } : { list: [{ wzbh: "V9", wfsj: 1716383000, wfxw: "闯红灯", fkje: 200, wfjfs: 6 }] };
+        return { data: { dabh: "L9", zt: "正常", ljjf: 6 } };
+      },
+    });
+    expect(await a.authenticate()).toMatchObject({ ok: true, mode: "cookie", unverified: true });
+    const items = await collect(a.sync({}));
+    expect(items).toHaveLength(2);
+    expect(items.map((i) => i.originalId).sort()).toEqual(["12123:license:L9", "12123:violation:V9"]);
+  });
+
+  it("province base host (verified .122.gov.cn/app); override + default", () => {
+    // default province bj
+    const a = new g.Tmri12123Adapter({ province: "fj" });
+    expect(a.province).toBe("fj");
+    expect(a._urls.violation).toBe("https://fj.122.gov.cn/app/violation/list");
+    expect(a._urls.license).toBe("https://fj.122.gov.cn/app/license/info");
+    // bad province → default bj
+    expect(new g.Tmri12123Adapter({ province: "XX" })._urls.violation).toBe("https://bj.122.gov.cn/app/violation/list");
+    // explicit url override still wins
+    expect(new g.Tmri12123Adapter({ violationUrl: "https://x/y" })._urls.violation).toBe("https://x/y");
+  });
+
+  it("high sensitivity + legalGate; default fetch / no input throw", async () => {
+    expect(new g.Tmri12123Adapter().dataDisclosure.sensitivity).toBe("high");
+    expect(new g.Tmri12123Adapter().dataDisclosure.legalGate).toBe(true);
+    await expect(collect(new g.Tmri12123Adapter({ account: { cookies: COOKIES } }).sync({}))).rejects.toThrow(/no fetchFn/);
+    await expect(collect(new g.Tmri12123Adapter().sync({}))).rejects.toThrow(/needs opts.inputPath/);
+  });
+});

package/__tests__/adapters/music-qq.test.js

@@ -0,0 +1,112 @@
+"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 qm = require("../../lib/adapters/music-qq");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-qqm-${crypto.randomUUID()}.json`);
+  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;
+}
+const COOKIES = "qqmusic_key=abc; uin=123";
+
+describe("music-qq mappers", () => {
+  it("name/version", () => {
+    expect(qm.NAME).toBe("music-qq");
+    expect(qm.VERSION).toBe("0.1.0");
+  });
+  it("flattenSinger handles array / string / object", () => {
+    expect(qm.flattenSinger([{ name: "周杰伦" }, { name: "费玉清" }])).toBe("周杰伦/费玉清");
+    expect(qm.flattenSinger("林俊杰")).toBe("林俊杰");
+    expect(qm.flattenSinger({ name: "邓紫棋" })).toBe("邓紫棋");
+    expect(qm.flattenSinger(null)).toBe("");
+  });
+  it("songItemToRecord (QQ fields: songmid, singer array, album.name)", () => {
+    const r = qm.songItemToRecord({ songmid: "S1", songname: "晴天", singer: [{ name: "周杰伦" }], album: { name: "叶惠美" }, time: 1716383000 });
+    expect(r).toMatchObject({ songId: "S1", song: "晴天", artist: "周杰伦", album: "叶惠美" });
+    expect(r.occurredAt).toBe(1716383000000);
+    expect(qm.songItemToRecord({ songname: "x" })).toBe(null);
+  });
+  it("playlistItemToRecord (dissid/dissname/songnum)", () => {
+    const r = qm.playlistItemToRecord({ dissid: "P1", dissname: "我喜欢", songnum: 42, creator: { name: "我" } });
+    expect(r).toMatchObject({ playlistId: "P1", name: "我喜欢", trackCount: 42, creator: "我" });
+    expect(qm.playlistItemToRecord({ dissname: "x" })).toBe(null);
+  });
+  it("extractList tolerant (list / data.songlist)", () => {
+    expect(qm.extractList({ list: [{ songmid: 1 }] })).toHaveLength(1);
+    expect(qm.extractList({ data: { songlist: [{ songmid: 1 }] } })).toHaveLength(1);
+    expect(qm.extractList({})).toEqual([]);
+  });
+});
+
+describe("QQMusicAdapter (snapshot + cookie-api)", () => {
+  const SNAP = JSON.stringify({
+    schemaVersion: 1,
+    snapshottedAt: 1716383000000,
+    account: { userId: "u1" },
+    events: [
+      { kind: "play", id: "play-S1", songId: "S1", song: "晴天", artist: "周杰伦", album: "叶惠美" },
+      { kind: "favorite", id: "fav-S2", songId: "S2", song: "稻香", artist: "周杰伦" },
+      { kind: "playlist", id: "pl-P1", playlistId: "P1", name: "我喜欢", trackCount: 42 },
+    ],
+  });
+
+  it("snapshot → play(MEDIA)/favorite(LIKE) events + playlist topic", async () => {
+    const p = writeTmp(SNAP);
+    try {
+      const a = new qm.QQMusicAdapter();
+      expect((await a.authenticate({ inputPath: p })).mode).toBe("snapshot-file");
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(3);
+      const play = a.normalize(items[0]);
+      expect(play.events[0].subtype).toBe("media");
+      expect(play.events[0].content.title).toContain("听了: 晴天");
+      expect(play.items[0].subtype).toBe("media");
+      expect(play.items[0].extra.platform).toBe("qqmusic");
+      expect(items[0].originalId).toBe("qqmusic:play:play-S1"); // snapshot uses ev.id (mirrors kugou)
+      const fav = a.normalize(items[1]);
+      expect(fav.events[0].subtype).toBe("like");
+      const pl = a.normalize(items[2]);
+      expect(pl.topics[0].name).toBe("我喜欢");
+      expect(pl.topics[0].id).toBe("topic-qqmusic-playlist-P1");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("cookie-api: fetch 3 kinds + sign seam", async () => {
+    let signed = 0;
+    const a = new qm.QQMusicAdapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      signProvider: async () => { signed += 1; return "sig"; },
+      fetchFn: async ({ url, query }) => {
+        if (query.page > 1) return { list: [] };
+        if (url.includes("/listen")) return { list: [{ songmid: "A", songname: "歌1", singer: [{ name: "歌手" }], time: 1716383000 }] };
+        if (url.includes("/favorite")) return { data: { songlist: [{ songmid: "B", songname: "歌2", singer: "歌手2" }] } };
+        return { data: { list: [{ dissid: "C", dissname: "歌单", songnum: 5 }] } };
+      },
+    });
+    expect(await a.authenticate()).toEqual({ ok: true, account: "u1", mode: "cookie" });
+    const items = await collect(a.sync({}));
+    expect(items).toHaveLength(3);
+    expect(items.map((i) => i.originalId).sort()).toEqual(["qqmusic:favorite:B", "qqmusic:play:A", "qqmusic:playlist:C"]);
+    expect(signed).toBeGreaterThan(0);
+  });
+
+  it("low sensitivity (consumer music); default fetch / no input throw", async () => {
+    expect(new qm.QQMusicAdapter().dataDisclosure.sensitivity).toBe("low");
+    expect(new qm.QQMusicAdapter().dataDisclosure.legalGate).toBe(false);
+    await expect(collect(new qm.QQMusicAdapter({ account: { cookies: COOKIES } }).sync({}))).rejects.toThrow(/no fetchFn/);
+    await expect(collect(new qm.QQMusicAdapter().sync({}))).rejects.toThrow(/needs opts.inputPath/);
+  });
+});