@chainlesschain/personal-data-hub 0.4.4 → 0.4.5

package/__tests__/adapters/game-honor-of-kings-live.test.js

@@ -0,0 +1,230 @@
+/**
+ * FAMILY-23 v0.2 — game-honor-of-kings LIVE 营地 (Camp) fetcher tests.
+ * credential (accessToken+openid+role) → profile + battle-list → snapshot-shaped
+ * events + adapter live sync + defensive field extraction + error mapping.
+ * All network via injected fetch. Endpoint shapes are best-effort (see api-client
+ * header) — these tests pin the REQUEST CONSTRUCTION + PARSING contract, not the
+ * live server, which can't be verified here.
+ */
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { HonorOfKingsAdapter } = require("../../lib");
+const {
+  HonorOfKingsApiClient,
+  pick,
+  toDurationMs,
+  toEpochMs,
+} = require("../../lib/adapters/game-honor-of-kings/api-client");
+const { validateBatch } = require("../../lib/batch");
+
+const CRED = {
+  accessToken: "tok-abc",
+  openid: "OPENID12345678",
+  acctype: "qc",
+  areaId: "1",
+  roleId: "900000001",
+};
+
+function makeFetch(routes, calls) {
+  return async (url, init) => {
+    let parsedBody = null;
+    try {
+      parsedBody = init && init.body ? JSON.parse(init.body) : null;
+    } catch (_e) {
+      parsedBody = init && init.body;
+    }
+    calls.push({ url, body: parsedBody, headers: (init && init.headers) || {} });
+    const route = routes.find((r) => url.includes(r.match));
+    if (!route) return { ok: false, status: 404, text: async () => "not mapped" };
+    return {
+      ok: route.status ? route.status >= 200 && route.status < 300 : true,
+      status: route.status || 200,
+      text: async () =>
+        typeof route.body === "string" ? route.body : JSON.stringify(route.body),
+    };
+  };
+}
+
+async function collect(iter) {
+  const out = [];
+  for await (const r of iter) out.push(r);
+  return out;
+}
+
+describe("honor-of-kings field-extraction helpers", () => {
+  it("pick returns first present non-empty value", () => {
+    expect(pick({ a: "", b: "x" }, ["a", "b"])).toBe("x");
+    expect(pick({ a: 0 }, ["a"])).toBe(0); // 0 is present
+    expect(pick({}, ["a"], "fb")).toBe("fb");
+  });
+
+  it("toDurationMs treats <1e7 as seconds, else ms; coerces numeric strings", () => {
+    expect(toDurationMs(1800)).toBe(1800000); // 30 min in seconds
+    expect(toDurationMs(1800000)).toBe(1800000); // already ms
+    expect(toDurationMs("900")).toBe(900000);
+    expect(toDurationMs(0)).toBe(0);
+    expect(toDurationMs("nope")).toBe(0);
+  });
+
+  it("toEpochMs coerces seconds/ms/date-string", () => {
+    expect(toEpochMs(1700000000)).toBe(1700000000000);
+    expect(toEpochMs(1700000000000)).toBe(1700000000000);
+    expect(toEpochMs("2023-11-14T22:13:20Z")).toBe(1700000000000);
+    expect(toEpochMs("bogus")).toBeNull();
+  });
+});
+
+describe("HonorOfKingsApiClient.fetchSnapshot — live (mocked fetch)", () => {
+  it("merges auth fields into each request + parses profile/battles defensively", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [
+        {
+          match: "/play/profildetail",
+          body: {
+            returnCode: 0,
+            data: { role: { roleId: "900000001", roleName: "小明", level: 30, rankName: "钻石", logo: "u.png" } },
+          },
+        },
+        {
+          match: "/game/getbattlelist",
+          body: {
+            returnCode: 0,
+            data: {
+              list: [
+                { gameSeq: "g1", startTime: 1700000000, gametime: 900, mapName: "排位赛" },
+                { gameSeq: "g2", startTime: "1700003600", usedTime: 1200, modeName: "巅峰赛" },
+              ],
+            },
+          },
+        },
+      ],
+      calls,
+    );
+    const client = new HonorOfKingsApiClient({ fetch });
+    const result = await client.fetchSnapshot(CRED);
+    expect(result.account).toEqual({ uid: "900000001", displayName: "小明" });
+    const profile = result.events.find((e) => e.kind === "profile");
+    expect(profile).toMatchObject({ uid: "900000001", nickname: "小明", level: 30, rank: "钻石", avatarUrl: "u.png" });
+    const plays = result.events.filter((e) => e.kind === "play");
+    expect(plays).toHaveLength(2);
+    expect(plays[0]).toMatchObject({ durationMs: 900000, mode: "排位赛", startAt: 1700000000000 });
+    expect(plays[1]).toMatchObject({ durationMs: 1200000, mode: "巅峰赛", startAt: 1700003600000 });
+    // every request carried the OAuth auth fields.
+    for (const c of calls) {
+      expect(c.body.accessToken).toBe("tok-abc");
+      expect(c.body.openid).toBe("OPENID12345678");
+      expect(c.body.acctype).toBe("qc");
+      expect(c.headers["Content-Type"]).toContain("application/json");
+    }
+  });
+
+  it("handles alternate envelope/field names (result + roleInfo + battleList)", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [
+        {
+          match: "/play/profildetail",
+          body: { result: 0, data: { roleInfo: { uid: "777", nickName: "阿强", roleLevel: 15, gradeName: "黄金" } } },
+        },
+        {
+          match: "/game/getbattlelist",
+          body: { result: 0, data: { battleList: [{ gameId: "b9", battleTime: 1700000000, gameDuration: 600, gameName: "5v5" }] } },
+        },
+      ],
+      calls,
+    );
+    const client = new HonorOfKingsApiClient({ fetch });
+    const result = await client.fetchSnapshot(CRED);
+    expect(result.account.displayName).toBe("阿强");
+    const profile = result.events.find((e) => e.kind === "profile");
+    expect(profile).toMatchObject({ uid: "777", level: 15, rank: "黄金" });
+    const play = result.events.find((e) => e.kind === "play");
+    expect(play).toMatchObject({ durationMs: 600000, mode: "5v5" });
+  });
+
+  it("include.play:false skips the battle-list call", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [{ match: "/play/profildetail", body: { returnCode: 0, data: { role: { roleId: "1", roleName: "x" } } } }],
+      calls,
+    );
+    const client = new HonorOfKingsApiClient({ fetch });
+    const result = await client.fetchSnapshot(CRED, { include: { play: false } });
+    expect(calls.some((c) => c.url.includes("getbattlelist"))).toBe(false);
+    expect(result.events.every((e) => e.kind !== "play")).toBe(true);
+  });
+
+  it("maps non-zero returnCode to null + lastError (e.g. token expired)", async () => {
+    const calls = [];
+    const fetch = makeFetch([{ match: "/play/profildetail", body: { returnCode: 1001, returnMsg: "登录态失效" } }], calls);
+    const client = new HonorOfKingsApiClient({ fetch });
+    expect(await client.fetchSnapshot(CRED)).toBeNull();
+    expect(client.lastError.code).toBe(1001);
+    expect(client.lastError.message).toContain("登录态失效");
+  });
+
+  it("missing accessToken/openid → null + lastError -1 (no network)", async () => {
+    const calls = [];
+    const client = new HonorOfKingsApiClient({ fetch: makeFetch([], calls) });
+    expect(await client.fetchSnapshot({ openid: "x" })).toBeNull();
+    expect(client.lastError.code).toBe(-1);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("HTTP non-2xx → null + lastError with status", async () => {
+    const calls = [];
+    const fetch = makeFetch([{ match: "/play/profildetail", status: 500, body: "err" }], calls);
+    const client = new HonorOfKingsApiClient({ fetch });
+    expect(await client.fetchSnapshot(CRED)).toBeNull();
+    expect(client.lastError.code).toBe(500);
+  });
+});
+
+describe("HonorOfKingsAdapter — credential (live) sync mode", () => {
+  it("authenticate accepts a credential bundle; rejects incomplete", async () => {
+    const a = new HonorOfKingsAdapter();
+    expect((await a.authenticate({ credential: CRED })).mode).toBe("camp-token");
+    expect((await a.authenticate({ credential: { openid: "x" } })).ok).toBe(false);
+  });
+
+  it("version/capabilities reflect v0.2 live mode", () => {
+    const a = new HonorOfKingsAdapter();
+    expect(a.version).toBe("0.2.0");
+    expect(a.capabilities).toContain("sync:camp-token");
+  });
+
+  it("sync via credential yields profile+play raws → valid normalized batch", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [
+        { match: "/play/profildetail", body: { returnCode: 0, data: { role: { roleId: "900000001", roleName: "小明", level: 30, rankName: "钻石" } } } },
+        { match: "/game/getbattlelist", body: { returnCode: 0, data: { list: [{ gameSeq: "g1", startTime: 1700000000, gametime: 1800, mapName: "排位赛" }] } } },
+      ],
+      calls,
+    );
+    const a = new HonorOfKingsAdapter();
+    const raws = await collect(a.sync({ credential: CRED, fetch }));
+    expect(raws.map((r) => r.kind).sort()).toEqual(["play", "profile"]);
+    const profileRaw = raws.find((r) => r.kind === "profile");
+    expect(profileRaw.originalId).toBe("hok:profile:profile-900000001");
+
+    for (const raw of raws) {
+      expect(validateBatch(a.normalize(raw)).valid).toBe(true);
+    }
+    const profileBatch = a.normalize(profileRaw);
+    expect(profileBatch.persons[0].identifiers["hok-uid"]).toEqual(["900000001"]);
+    expect(profileBatch.persons[0].extra.rank).toBe("钻石");
+    const playBatch = a.normalize(raws.find((r) => r.kind === "play"));
+    expect(playBatch.events[0].extra.durationMs).toBe(1800000);
+  });
+
+  it("sync via credential throws (mapped lastError) on API error", async () => {
+    const calls = [];
+    const fetch = makeFetch([{ match: "/play/profildetail", body: { returnCode: 1001, returnMsg: "登录态失效" } }], calls);
+    const a = new HonorOfKingsAdapter();
+    await expect(collect(a.sync({ credential: CRED, fetch }))).rejects.toThrow(/登录态失效|code 1001/);
+  });
+});

package/__tests__/adapters/netease-music-live.test.js

@@ -0,0 +1,244 @@
+/**
+ * 网易云音乐 LIVE cookie web-API (weapi) fetcher tests.
+ * weapi crypto determinism (fixed secKey) + account/play/playlist parsing +
+ * adapter cookie-mode sync + error mapping. All network via injected fetch.
+ */
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { NeteaseMusicAdapter } = require("../../lib/adapters/netease-music");
+const {
+  NeteaseMusicApiClient,
+  weapiEncrypt,
+  aesEncrypt,
+  rsaEncrypt,
+  modpow,
+} = require("../../lib/adapters/netease-music/api-client");
+const { partitionBatch } = require("../../lib/batch");
+
+const FIXED_SECKEY = "0123456789abcdef"; // 16 chars → deterministic weapi
+const COOKIE = "MUSIC_U=abcdef0123456789; __csrf=zzz";
+
+/** Map endpoint path substrings → JSON bodies; record posted form bodies. */
+function makeFetch(routes, calls) {
+  return async (url, init) => {
+    calls.push({ url, body: init && init.body, headers: (init && init.headers) || {} });
+    const route = routes.find((r) => url.includes(r.match));
+    if (!route) return { ok: false, status: 404, text: async () => "not mapped" };
+    return {
+      ok: route.status ? route.status >= 200 && route.status < 300 : true,
+      status: route.status || 200,
+      text: async () =>
+        typeof route.body === "string" ? route.body : JSON.stringify(route.body),
+    };
+  };
+}
+
+async function collect(iter) {
+  const out = [];
+  for await (const r of iter) out.push(r);
+  return out;
+}
+
+describe("weapi crypto primitives", () => {
+  it("modpow matches BigInt ** % for small values", () => {
+    expect(modpow(4n, 13n, 497n)).toBe(445n); // textbook RSA example
+    expect(modpow(7n, 0n, 13n)).toBe(1n);
+  });
+
+  it("aesEncrypt is deterministic (fixed key + IV) and base64", () => {
+    const a = aesEncrypt("hello", "0CoJUm6Qyw8W8jud");
+    const b = aesEncrypt("hello", "0CoJUm6Qyw8W8jud");
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[A-Za-z0-9+/=]+$/);
+  });
+
+  it("rsaEncrypt yields zero-padded 256-hex", () => {
+    const enc = rsaEncrypt("test", "010001", "e0b5");
+    expect(enc).toHaveLength(256);
+    expect(enc).toMatch(/^[0-9a-f]{256}$/);
+  });
+
+  it("weapiEncrypt produces stable { params, encSecKey } for a fixed secKey", () => {
+    const a = weapiEncrypt({ uid: 1 }, FIXED_SECKEY);
+    const b = weapiEncrypt({ uid: 1 }, FIXED_SECKEY);
+    expect(a).toEqual(b);
+    expect(a.encSecKey).toHaveLength(256);
+    expect(a.params).toMatch(/^[A-Za-z0-9+/=]+$/);
+  });
+});
+
+describe("NeteaseMusicApiClient.fetchSnapshot — live (mocked fetch)", () => {
+  it("resolves account, play record, playlists into snapshot-shaped events", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [
+        {
+          match: "/weapi/w/nuser/account/get",
+          body: { code: 200, profile: { userId: 42, nickname: "听歌的人" }, account: { id: 42 } },
+        },
+        {
+          match: "/weapi/v1/play/record",
+          body: {
+            code: 200,
+            weekData: [
+              { playCount: 50, song: { id: 186016, name: "晴天", ar: [{ name: "周杰伦" }], al: { name: "叶惠美" } } },
+            ],
+          },
+        },
+        {
+          match: "/weapi/user/playlist",
+          body: {
+            code: 200,
+            playlist: [{ id: 999, name: "我喜欢的音乐", trackCount: 200, creator: { nickname: "听歌的人" } }],
+          },
+        },
+      ],
+      calls,
+    );
+    const client = new NeteaseMusicApiClient({ fetch, secKey: FIXED_SECKEY });
+    const result = await client.fetchSnapshot(COOKIE);
+    expect(result.account).toEqual({ uid: "42", nickname: "听歌的人" });
+    expect(result.events).toHaveLength(2);
+    const play = result.events.find((e) => e.kind === "play");
+    expect(play).toMatchObject({ songId: "186016", song: "晴天", artist: "周杰伦", album: "叶惠美", playCount: 50 });
+    const pl = result.events.find((e) => e.kind === "playlist");
+    expect(pl).toMatchObject({ playlistId: "999", name: "我喜欢的音乐", trackCount: 200, creator: "听歌的人" });
+    // every POST is form-encoded weapi (params + encSecKey) with the cookie.
+    for (const c of calls) {
+      expect(c.body).toMatch(/^params=.+&encSecKey=.+$/);
+      expect(c.headers.Cookie).toBe(COOKIE);
+      expect(c.headers["Content-Type"]).toContain("x-www-form-urlencoded");
+    }
+  });
+
+  it("multi-artist joined with ' / '; falls back to allData when weekData empty", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [
+        { match: "account/get", body: { code: 200, profile: { userId: 7 } } },
+        {
+          match: "play/record",
+          body: {
+            code: 200,
+            weekData: [],
+            allData: [{ playCount: 3, song: { id: 1, name: "S", ar: [{ name: "A" }, { name: "B" }], al: { name: "Al" } } }],
+          },
+        },
+        { match: "user/playlist", body: { code: 200, playlist: [] } },
+      ],
+      calls,
+    );
+    const client = new NeteaseMusicApiClient({ fetch, secKey: FIXED_SECKEY });
+    const result = await client.fetchSnapshot(COOKIE);
+    const play = result.events.find((e) => e.kind === "play");
+    expect(play.artist).toBe("A / B");
+  });
+
+  it("include flags skip endpoints", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [
+        { match: "account/get", body: { code: 200, profile: { userId: 7 } } },
+        { match: "user/playlist", body: { code: 200, playlist: [] } },
+      ],
+      calls,
+    );
+    const client = new NeteaseMusicApiClient({ fetch, secKey: FIXED_SECKEY });
+    const result = await client.fetchSnapshot(COOKIE, { include: { play: false } });
+    expect(calls.some((c) => c.url.includes("play/record"))).toBe(false);
+    expect(result.events.every((e) => e.kind !== "play")).toBe(true);
+  });
+
+  it("maps API code != 200 to null + lastError (e.g. -460 risk-control)", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [{ match: "account/get", body: { code: -460, message: "Cheating" } }],
+      calls,
+    );
+    const client = new NeteaseMusicApiClient({ fetch, secKey: FIXED_SECKEY });
+    expect(await client.fetchSnapshot(COOKIE)).toBeNull();
+    expect(client.lastError.code).toBe(-460);
+    expect(client.lastError.message).toContain("Cheating");
+  });
+
+  it("account with no userId → null + lastError -7", async () => {
+    const calls = [];
+    const fetch = makeFetch([{ match: "account/get", body: { code: 200, profile: null, account: null } }], calls);
+    const client = new NeteaseMusicApiClient({ fetch, secKey: FIXED_SECKEY });
+    expect(await client.fetchSnapshot(COOKIE)).toBeNull();
+    expect(client.lastError.code).toBe(-7);
+  });
+
+  it("empty cookie → null + lastError -1 (no network)", async () => {
+    const calls = [];
+    const client = new NeteaseMusicApiClient({ fetch: makeFetch([], calls), secKey: FIXED_SECKEY });
+    expect(await client.fetchSnapshot("")).toBeNull();
+    expect(client.lastError.code).toBe(-1);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("HTTP non-2xx → null + lastError with status", async () => {
+    const calls = [];
+    const fetch = makeFetch([{ match: "account/get", status: 502, body: "bad gw" }], calls);
+    const client = new NeteaseMusicApiClient({ fetch, secKey: FIXED_SECKEY });
+    expect(await client.fetchSnapshot(COOKIE)).toBeNull();
+    expect(client.lastError.code).toBe(502);
+  });
+});
+
+describe("NeteaseMusicAdapter — cookie (live) sync mode", () => {
+  it("authenticate accepts a cookie with MUSIC_U; rejects without it", async () => {
+    const a = new NeteaseMusicAdapter();
+    expect((await a.authenticate({ cookie: COOKIE })).mode).toBe("cookie");
+    const bad = await a.authenticate({ cookie: "foo=bar" });
+    expect(bad.ok).toBe(false);
+    expect(bad.reason).toBe("INVALID_COOKIE");
+  });
+
+  it("capabilities/version reflect v0.2 live mode", () => {
+    const a = new NeteaseMusicAdapter();
+    expect(a.version).toBe("0.2.0");
+    expect(a.capabilities).toContain("sync:cookie");
+  });
+
+  it("sync via cookie yields play+playlist raws → valid normalized batch", async () => {
+    const calls = [];
+    const fetch = makeFetch(
+      [
+        { match: "account/get", body: { code: 200, profile: { userId: 42, nickname: "me" } } },
+        {
+          match: "play/record",
+          body: { code: 200, weekData: [{ playCount: 9, song: { id: 5, name: "夜曲", ar: [{ name: "周杰伦" }], al: { name: "11月的萧邦" } } }] },
+        },
+        { match: "user/playlist", body: { code: 200, playlist: [{ id: 8, name: "练歌", trackCount: 12, creator: { nickname: "me" } }] } },
+      ],
+      calls,
+    );
+    const a = new NeteaseMusicAdapter();
+    const raws = await collect(a.sync({ cookie: COOKIE, fetch, secKey: FIXED_SECKEY }));
+    expect(raws.map((r) => r.kind).sort()).toEqual(["play", "playlist"]);
+    const playRaw = raws.find((r) => r.kind === "play");
+    expect(playRaw.originalId).toBe("netease-music:play:play-5");
+
+    // normalize → vault-valid batch for both kinds.
+    for (const raw of raws) {
+      const batch = a.normalize(raw);
+      const { invalidReasons } = partitionBatch(batch);
+      expect(invalidReasons).toHaveLength(0);
+    }
+    const playBatch = a.normalize(playRaw);
+    expect(playBatch.items[0].extra.songId).toBe("5");
+    expect(playBatch.events[0].content.title).toContain("夜曲");
+  });
+
+  it("sync via cookie throws (mapped lastError) on risk-control", async () => {
+    const calls = [];
+    const fetch = makeFetch([{ match: "account/get", body: { code: -460, message: "Cheating" } }], calls);
+    const a = new NeteaseMusicAdapter();
+    await expect(collect(a.sync({ cookie: COOKIE, fetch, secKey: FIXED_SECKEY }))).rejects.toThrow(
+      /Cheating|code -460/,
+    );
+  });
+});

package/__tests__/adapters/social-douyin-adb-aweme-detail.test.js

@@ -0,0 +1,165 @@
+/**
+ * Douyin aweme-detail title resolver tests (real-device-driven 2026-06-11:
+ * web detail endpoint returns aweme_detail{desc,author,duration} with no signing).
+ * fetch injected — no network.
+ */
+"use strict";
+
+import { describe, it, expect, vi } from "vitest";
+
+const {
+  AwemeDetailClient,
+} = require("../../lib/adapters/social-douyin-adb/aweme-detail-client");
+const {
+  collectWatchHistory,
+} = require("../../lib/adapters/social-douyin-adb/collector");
+const { DouyinAdapter } = require("../../lib/adapters/social-douyin");
+const { partitionBatch } = require("../../lib/batch");
+
+function makeFetch(byAid) {
+  return async (url) => {
+    const m = /aweme_id=(\d+)/.exec(url);
+    const aid = m && m[1];
+    const payload = byAid[aid];
+    if (payload === undefined) return { ok: false, status: 404, text: async () => "nf" };
+    return {
+      ok: payload.status ? payload.status >= 200 && payload.status < 300 : true,
+      status: payload.status || 200,
+      text: async () => (typeof payload.body === "string" ? payload.body : JSON.stringify(payload.body)),
+    };
+  };
+}
+const noSleep = () => Promise.resolve();
+
+describe("AwemeDetailClient.fetchDetail", () => {
+  it("parses aweme_detail → {desc, author, durationMs, createTime}; sends aweme_id + webapp params", async () => {
+    let seenUrl;
+    const fetch = async (url) => {
+      seenUrl = url;
+      return { ok: true, status: 200, text: async () => JSON.stringify({
+        status_code: 0,
+        aweme_detail: { desc: "洋气婆婆和她的土狗儿媳", author: { nickname: "任集" }, duration: 9200, create_time: 1780112750 },
+      }) };
+    };
+    const c = new AwemeDetailClient({ fetch, sleep: noSleep });
+    const d = await c.fetchDetail("7645526043227334246");
+    expect(d).toEqual({ awemeId: "7645526043227334246", desc: "洋气婆婆和她的土狗儿媳", author: "任集", durationMs: 9200, createTime: 1780112750 });
+    expect(seenUrl).toContain("aweme_id=7645526043227334246");
+    expect(seenUrl).toContain("device_platform=webapp");
+    expect(seenUrl).toContain("aid=6383");
+  });
+
+  it("status_code != 0 → null + lastError", async () => {
+    const fetch = makeFetch({ 1: { body: { status_code: 8, status_msg: "risk" } } });
+    const c = new AwemeDetailClient({ fetch, sleep: noSleep });
+    expect(await c.fetchDetail("1")).toBe(null);
+    expect(c.lastErrorCode).toBe(8);
+  });
+
+  it("missing aweme_detail (deleted/private) → null -5", async () => {
+    const fetch = makeFetch({ 1: { body: { status_code: 0 } } });
+    const c = new AwemeDetailClient({ fetch, sleep: noSleep });
+    expect(await c.fetchDetail("1")).toBe(null);
+    expect(c.lastErrorCode).toBe(-5);
+  });
+
+  it("HTTP non-2xx → null with status", async () => {
+    const fetch = makeFetch({ 1: { status: 444, body: "blocked" } });
+    const c = new AwemeDetailClient({ fetch, sleep: noSleep });
+    expect(await c.fetchDetail("1")).toBe(null);
+    expect(c.lastErrorCode).toBe(444);
+  });
+});
+
+describe("AwemeDetailClient.resolveMany", () => {
+  it("dedups ids, caps at limit, skips per-id failures", async () => {
+    const calls = [];
+    const fetch = async (url) => {
+      const aid = /aweme_id=(\d+)/.exec(url)[1];
+      calls.push(aid);
+      const ok = { 11: true, 22: true }[aid];
+      return { ok: true, status: 200, text: async () => JSON.stringify(
+        ok ? { status_code: 0, aweme_detail: { desc: "d" + aid, author: { nickname: "a" } } }
+           : { status_code: 0 }, // 33 → no aweme_detail → skipped
+      ) };
+    };
+    const c = new AwemeDetailClient({ fetch, sleep: noSleep });
+    const map = await c.resolveMany(["11", "11", "22", "33"], { limit: 10 });
+    expect(calls).toEqual(["11", "22", "33"]); // deduped (one 11)
+    expect([...map.keys()].sort()).toEqual(["11", "22"]); // 33 skipped
+    expect(map.get("11").desc).toBe("d11");
+  });
+
+  it("respects limit (stops early)", async () => {
+    const calls = [];
+    const fetch = async (url) => {
+      calls.push(/aweme_id=(\d+)/.exec(url)[1]);
+      return { ok: true, status: 200, text: async () => JSON.stringify({ status_code: 0, aweme_detail: { desc: "x" } }) };
+    };
+    const c = new AwemeDetailClient({ fetch, sleep: noSleep });
+    await c.resolveMany(["1", "2", "3", "4", "5"], { limit: 2 });
+    expect(calls).toEqual(["1", "2"]);
+  });
+});
+
+describe("collectWatchHistory --resolve-titles integration", () => {
+  it("attaches title/author/duration → normalizeHistory shows real content", async () => {
+    const fs = require("node:fs");
+    const os = require("node:os");
+    const bridge = {
+      invoke: vi.fn(async (m) =>
+        m === "douyin.watch-history"
+          ? {
+              uid: "92585448288",
+              records: [
+                { awemeId: "7645526043227334246", capturedAt: 1780112750000, enterFrom: "homepage_hot" },
+              ],
+            }
+          : (() => { throw new Error("unknown " + m); })(),
+      ),
+    };
+    const detailClient = new AwemeDetailClient({
+      sleep: () => Promise.resolve(),
+      fetch: makeFetch({
+        "7645526043227334246": { body: { status_code: 0, aweme_detail: { desc: "洋气婆婆和她的土狗儿媳", author: { nickname: "任集" }, duration: 9200 } } },
+      }),
+    });
+    const r = await collectWatchHistory(bridge, {
+      stagingDir: os.tmpdir(),
+      now: () => 1781000000000,
+      resolveTitles: true,
+      _detailClient: detailClient,
+    });
+    expect(r.titlesResolved).toBe(1);
+    const snap = JSON.parse(fs.readFileSync(r.snapshotPath, "utf-8"));
+    try {
+      expect(snap.events[0].title).toBe("洋气婆婆和她的土狗儿媳");
+      const a = new DouyinAdapter();
+      const batch = a.normalize({
+        adapter: "social-douyin",
+        kind: "history",
+        originalId: "douyin:history:1",
+        capturedAt: 1780112750000,
+        payload: { ...snap.events[0], account: snap.account },
+      });
+      expect(partitionBatch(batch).invalidReasons).toHaveLength(0);
+      expect(batch.events[0].content.title).toBe("洋气婆婆和她的土狗儿媳");
+      expect(batch.events[0].extra.author).toBe("任集");
+      expect(batch.events[0].extra.duration).toBe(9200);
+      expect(batch.events[0].extra.enterFrom).toBe("homepage_hot");
+    } finally {
+      fs.unlinkSync(r.snapshotPath);
+    }
+  });
+
+  it("without resolveTitles, no network + title stays unresolved", async () => {
+    const os = require("node:os");
+    const fs = require("node:fs");
+    const bridge = { invoke: vi.fn(async () => ({ uid: "1", records: [{ awemeId: "999", capturedAt: 1, enterFrom: "x" }] })) };
+    const r = await collectWatchHistory(bridge, { stagingDir: os.tmpdir(), now: () => 1, resolveTitles: false });
+    expect(r.titlesResolved).toBe(0);
+    const snap = JSON.parse(fs.readFileSync(r.snapshotPath, "utf-8"));
+    fs.unlinkSync(r.snapshotPath);
+    expect(snap.events[0].title).toBeUndefined();
+  });
+});