@chainlesschain/personal-data-hub 0.4.18 → 0.4.24

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/gov-ixiamen.test.js

@@ -0,0 +1,150 @@
+"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 ix = require("../../lib/adapters/gov-ixiamen");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-ix-${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 = "XMGOV_SSO=abc; tgc=xyz";
+
+describe("gov-ixiamen mappers", () => {
+  it("name/version/capabilities", () => {
+    expect(ix.NAME).toBe("gov-ixiamen");
+    expect(ix.VERSION).toBe("0.1.0");
+  });
+  it("inferCategory: explicit wins, else keyword, else fallback", () => {
+    expect(ix.inferCategory("随便", "医保")).toBe("医保");
+    expect(ix.inferCategory("城乡居民医保缴费")).toBe("医保");
+    expect(ix.inferCategory("住房公积金提取")).toBe("公积金");
+    expect(ix.inferCategory("机动车违章处理")).toBe("车驾管");
+    expect(ix.inferCategory("某个没见过的事项")).toBe("其他政务");
+  });
+  it("mapService maps gov-service fields; no id → null", () => {
+    const rec = ix.mapService({
+      service_id: "S1",
+      service_name: "养老保险待遇资格认证",
+      handle_time: 1716383000,
+      status: "已办结",
+      deptName: "厦门市社保中心",
+    });
+    expect(rec).toMatchObject({ serviceId: "S1", category: "社保", status: "已办结", dept: "厦门市社保中心" });
+    expect(rec.handledMs).toBe(1716383000000);
+    expect(ix.mapService({ service_name: "noid" })).toBe(null);
+  });
+  it("extractList tolerant", () => {
+    expect(ix.extractList({ list: [{ id: 1 }] })).toHaveLength(1);
+    expect(ix.extractList({ data: { records: [{ id: 1 }] } })).toHaveLength(1);
+    expect(ix.extractList({})).toEqual([]);
+  });
+});
+
+describe("IXiamenAdapter (snapshot + cookie-api)", () => {
+  const SNAP = JSON.stringify({
+    schemaVersion: 1,
+    snapshottedAt: 1716383000000,
+    account: { userId: "u1", name: "张三" },
+    events: [
+      {
+        kind: "service",
+        id: "svc-S1",
+        serviceId: "S1",
+        serviceName: "住房公积金缴存明细查询",
+        handledTime: 1716383000,
+        status: "已办结",
+        dept: "厦门住房公积金中心",
+      },
+    ],
+  });
+
+  it("snapshot sync + normalize → INTERACTION event + category topic", async () => {
+    const p = writeTmp(SNAP);
+    try {
+      const a = new ix.IXiamenAdapter();
+      expect((await a.authenticate({ inputPath: p })).mode).toBe("snapshot-file");
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(1);
+      expect(items[0].originalId).toBe("ixiamen:service:S1");
+      const batch = a.normalize(items[0]);
+      expect(batch.events[0].subtype).toBe("interaction");
+      expect(batch.events[0].content.title).toBe("办理: 住房公积金缴存明细查询");
+      expect(batch.events[0].extra.category).toBe("公积金");
+      expect(batch.topics[0].name).toBe("公积金");
+      expect(batch.topics[0].id).toBe("topic-ixiamen-cat-公积金");
+      expect(batch.events[0].extra.topicRef).toBe("topic-ixiamen-cat-公积金");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("dataDisclosure: high sensitivity + legalGate (gov real-name)", () => {
+    const a = new ix.IXiamenAdapter();
+    expect(a.dataDisclosure.sensitivity).toBe("high");
+    expect(a.dataDisclosure.legalGate).toBe(true);
+  });
+
+  it("cookie-api: best-effort fetch + paginate + unverified flag", async () => {
+    const pages = [
+      { list: [{ id: 7, name: "门诊报销", category: "医保", handledTime: 1716383000 }] },
+      { list: [] },
+    ];
+    const calls = [];
+    const a = new ix.IXiamenAdapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      fetchFn: async ({ url, cookies, query, sign }) => {
+        calls.push({ url, cookies, page: query.page, sign });
+        return query.page === 1 ? pages[0] : pages[1];
+      },
+    });
+    const auth = await a.authenticate();
+    expect(auth).toMatchObject({ ok: true, mode: "cookie", unverified: true });
+    const items = await collect(a.sync({}));
+    expect(items).toHaveLength(1);
+    expect(items[0].originalId).toBe("ixiamen:service:7");
+    expect(calls[0].cookies).toBe(COOKIES);
+    expect(calls[0].sign).toBe(null);
+    const batch = a.normalize(items[0]);
+    expect(batch.events[0].extra.category).toBe("医保");
+  });
+
+  it("cookie-api: signProvider seam invoked + sinceWatermark stops early", async () => {
+    let seen = null;
+    const a = new ix.IXiamenAdapter({
+      account: { cookies: COOKIES },
+      signProvider: async ({ url, query }) => {
+        seen = { url, page: query.page };
+        return "gov-sig";
+      },
+      fetchFn: async () => ({
+        list: [
+          { id: "new", name: "新事项", handledTime: 1716390000 },
+          { id: "old", name: "旧事项", handledTime: 1700000000 },
+        ],
+      }),
+    });
+    const items = await collect(a.sync({ sinceWatermark: 1716000000000 }));
+    expect(items).toHaveLength(1); // old one below watermark stops iteration
+    expect(items[0].originalId).toBe("ixiamen:service:new");
+    expect(seen.url).toContain("ixm.gov.cn");
+  });
+
+  it("default fetch throws; no input throws", async () => {
+    const a = new ix.IXiamenAdapter({ account: { cookies: COOKIES } });
+    await expect(collect(a.sync({}))).rejects.toThrow(/no fetchFn configured/);
+    const b = new ix.IXiamenAdapter();
+    await expect(collect(b.sync({}))).rejects.toThrow(/needs opts.inputPath/);
+  });
+});

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

@@ -0,0 +1,135 @@
+"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 tx = require("../../lib/adapters/gov-tax");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-tax-${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 = "ETAX_SSO=abc; sid=xyz";
+
+describe("gov-tax mappers", () => {
+  it("name/version", () => {
+    expect(tx.NAME).toBe("gov-tax");
+    expect(tx.VERSION).toBe("0.1.0");
+  });
+  it("periodToMs / toAmount", () => {
+    expect(tx.periodToMs("2025-03")).toBe(Date.parse("2025-03-01T00:00:00Z"));
+    expect(tx.periodToMs("202503")).toBe(Date.parse("2025-03-01T00:00:00Z"));
+    expect(tx.toAmount("¥1,234.56")).toBeCloseTo(1234.56, 2);
+    expect(tx.toAmount(2000)).toBe(2000);
+    expect(tx.toAmount("abc")).toBe(null);
+  });
+  it("mapIncome / mapDeclaration field aliases; no id → null", () => {
+    const inc = tx.mapIncome({ record_id: "I1", tax_period: "2025-03", income_type: "工资薪金", amount: "20,000", withheldTax: 1234.56, company: "某某公司", companyId: "9144" });
+    expect(inc).toMatchObject({ recordId: "I1", incomeType: "工资薪金", payerName: "某某公司", payerId: "9144" });
+    expect(inc.amount).toBe(20000);
+    expect(inc.withheld).toBeCloseTo(1234.56, 2);
+    expect(tx.mapIncome({ amount: 1 })).toBe(null);
+    const dec = tx.mapDeclaration({ id: "D1", tax_year: 2024, type: "综合所得年度汇算", status: "已退税", amount: -800 });
+    expect(dec).toMatchObject({ recordId: "D1", year: 2024, declType: "综合所得年度汇算", status: "已退税", settleAmount: -800 });
+    expect(tx.mapDeclaration({ year: 2024 })).toBe(null);
+  });
+  it("extractList tolerant", () => {
+    expect(tx.extractList({ list: [{ id: 1 }] })).toHaveLength(1);
+    expect(tx.extractList({ data: { records: [{ id: 1 }] } })).toHaveLength(1);
+    expect(tx.extractList({})).toEqual([]);
+  });
+});
+
+describe("TaxAdapter (snapshot + cookie-api)", () => {
+  const SNAP = JSON.stringify({
+    schemaVersion: 1,
+    snapshottedAt: 1716383000000,
+    account: { userId: "u1" },
+    events: [
+      { kind: "income", id: "inc-I1", recordId: "I1", period: "2025-03", incomeType: "工资薪金", amount: 20000, withheld: 1234.56, payerName: "某某科技有限公司", payerId: "9144ABC" },
+      { kind: "declaration", id: "dec-D1", recordId: "D1", year: 2024, declType: "综合所得年度汇算", status: "已退税", settleAmount: -800, declaredAt: 1716383000 },
+    ],
+  });
+
+  it("income → INCOME event + employer Person(MERCHANT)", async () => {
+    const p = writeTmp(SNAP);
+    try {
+      const a = new tx.TaxAdapter();
+      expect((await a.authenticate({ inputPath: p })).mode).toBe("snapshot-file");
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(2);
+      const inc = a.normalize(items[0]);
+      expect(inc.events[0].subtype).toBe("income");
+      expect(inc.events[0].extra.incomeType).toBe("工资薪金");
+      expect(inc.events[0].extra.amount).toBe(20000);
+      expect(inc.persons).toHaveLength(1);
+      expect(inc.persons[0].subtype).toBe("merchant");
+      expect(inc.persons[0].names[0]).toBe("某某科技有限公司");
+      expect(inc.events[0].extra.payerRef).toBe(inc.persons[0].id);
+      expect(items[0].originalId).toBe("tax:income:I1");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("declaration → OTHER event with settleAmount", async () => {
+    const p = writeTmp(SNAP);
+    try {
+      const a = new tx.TaxAdapter();
+      const items = await collect(a.sync({ inputPath: p }));
+      const dec = a.normalize(items[1]);
+      expect(dec.events[0].subtype).toBe("other");
+      expect(dec.events[0].content.title).toContain("个税申报");
+      expect(dec.events[0].extra.settleAmount).toBe(-800);
+      expect(dec.events[0].extra.year).toBe(2024);
+      expect(items[1].originalId).toBe("tax:declaration:D1");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("dataDisclosure: high sensitivity + legalGate (financial/tax)", () => {
+    const a = new tx.TaxAdapter();
+    expect(a.dataDisclosure.sensitivity).toBe("high");
+    expect(a.dataDisclosure.legalGate).toBe(true);
+  });
+
+  it("cookie-api: best-effort both kinds + unverified flag + sign seam", async () => {
+    let signed = 0;
+    const a = new tx.TaxAdapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      signProvider: async () => {
+        signed += 1;
+        return "sig";
+      },
+      fetchFn: async ({ url, query }) => {
+        if (query.page > 1) return { list: [] };
+        if (url.includes("/income")) return { list: [{ recordId: "I9", period: "2025-01", incomeType: "劳务报酬", amount: 5000 }] };
+        return { list: [{ recordId: "D9", year: 2024, declType: "年度汇算", settleAmount: 300 }] };
+      },
+    });
+    const auth = await a.authenticate();
+    expect(auth).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(["tax:declaration:D9", "tax:income:I9"]);
+    expect(signed).toBeGreaterThan(0);
+  });
+
+  it("default fetch throws; no input throws", async () => {
+    const a = new tx.TaxAdapter({ account: { cookies: COOKIES } });
+    await expect(collect(a.sync({}))).rejects.toThrow(/no fetchFn configured/);
+    const b = new tx.TaxAdapter();
+    await expect(collect(b.sync({}))).rejects.toThrow(/needs opts.inputPath/);
+  });
+});

package/__tests__/adapters/health-meiyou.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 my = require("../../lib/adapters/health-meiyou");
+
+function writeTmp(content) {
+  const p = path.join(os.tmpdir(), `cc-my-${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 = "myclient_id=abc; sid=xyz";
+
+describe("health-meiyou mappers", () => {
+  it("name/version", () => {
+    expect(my.NAME).toBe("health-meiyou");
+    expect(my.VERSION).toBe("0.1.0");
+  });
+  it("mapPeriod / mapRecord field aliases; no id → null", () => {
+    const p = my.mapPeriod({ record_id: "P1", start_date: 1716383000, end_date: 1716800000, cycle_length: 28, period_length: 5 });
+    expect(p).toMatchObject({ recordId: "P1", cycleLength: 28, periodLength: 5 });
+    expect(p.startMs).toBe(1716383000000);
+    expect(my.mapPeriod({})).toBe(null);
+    const r = my.mapRecord({ id: "R1", record_type: "mood", date: 1716383000, value: "开心", remark: "今天不错" });
+    expect(r).toMatchObject({ recordId: "R1", recordType: "mood", value: "开心", note: "今天不错" });
+    expect(my.mapRecord({ note: "noid" })).toBe(null);
+  });
+  it("extractList tolerant", () => {
+    expect(my.extractList({ list: [{ id: 1 }] })).toHaveLength(1);
+    expect(my.extractList({ data: { calendar: [{ id: 1 }] } })).toHaveLength(1);
+    expect(my.extractList({})).toEqual([]);
+  });
+});
+
+describe("MeiyouAdapter (snapshot + cookie-api)", () => {
+  const SNAP = JSON.stringify({
+    schemaVersion: 1,
+    snapshottedAt: 1716383000000,
+    account: { userId: "u1" },
+    events: [
+      { kind: "period", id: "p-P1", recordId: "P1", startDate: 1716383000, endDate: 1716800000, cycleLength: 28, periodLength: 5 },
+      { kind: "record", id: "r-R1", recordId: "R1", recordType: "mood", date: 1716383000, value: "开心" },
+    ],
+  });
+
+  it("snapshot sync + normalize → period + record events", async () => {
+    const p = writeTmp(SNAP);
+    try {
+      const a = new my.MeiyouAdapter();
+      expect((await a.authenticate({ inputPath: p })).mode).toBe("snapshot-file");
+      const items = await collect(a.sync({ inputPath: p }));
+      expect(items).toHaveLength(2);
+      const period = a.normalize(items[0]);
+      expect(period.events[0].subtype).toBe("other");
+      expect(period.events[0].content.title).toBe("经期记录");
+      expect(period.events[0].extra.cycleLength).toBe(28);
+      expect(items[0].originalId).toBe("meiyou:period:P1");
+      const record = a.normalize(items[1]);
+      expect(record.events[0].extra.recordType).toBe("mood");
+      expect(record.events[0].extra.value).toBe("开心");
+      expect(items[1].originalId).toBe("meiyou:record:R1");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("dataDisclosure: high sensitivity + legalGate (reproductive health)", () => {
+    const a = new my.MeiyouAdapter();
+    expect(a.dataDisclosure.sensitivity).toBe("high");
+    expect(a.dataDisclosure.legalGate).toBe(true);
+  });
+
+  it("include filter can exclude a kind", async () => {
+    const p = writeTmp(SNAP);
+    try {
+      const a = new my.MeiyouAdapter();
+      const items = await collect(a.sync({ inputPath: p, include: { record: false } }));
+      expect(items).toHaveLength(1);
+      expect(items[0].kind).toBe("period");
+    } finally {
+      fs.unlinkSync(p);
+    }
+  });
+
+  it("cookie-api: best-effort fetch both kinds + unverified flag + sign seam", async () => {
+    const calls = [];
+    let signed = 0;
+    const a = new my.MeiyouAdapter({
+      account: { cookies: COOKIES, userId: "u1" },
+      signProvider: async () => {
+        signed += 1;
+        return "sig";
+      },
+      fetchFn: async ({ url, query }) => {
+        calls.push({ url, page: query.page });
+        if (query.page > 1) return { list: [] };
+        if (url.includes("/period")) return { list: [{ recordId: "P9", startDate: 1716383000, cycleLength: 30 }] };
+        return { list: [{ recordId: "R9", recordType: "weight", date: 1716383000, value: 55 }] };
+      },
+    });
+    const auth = await a.authenticate();
+    expect(auth).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(["meiyou:period:P9", "meiyou:record:R9"]);
+    expect(signed).toBeGreaterThan(0);
+  });
+
+  it("default fetch throws; no input throws", async () => {
+    const a = new my.MeiyouAdapter({ account: { cookies: COOKIES } });
+    await expect(collect(a.sync({}))).rejects.toThrow(/no fetchFn configured/);
+    const b = new my.MeiyouAdapter();
+    await expect(collect(b.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/);
+  });
+});