@chainlesschain/personal-data-hub 0.4.3 → 0.4.5

package/lib/adapters/netease-music/api-client.js

@@ -0,0 +1,284 @@
+/**
+ * NeteaseMusicApiClient — 网易云音乐 live cookie web-API fetcher.
+ *
+ * 走标准 weapi 加密（AES-128-CBC 双层 + textbook-RSA encSecKey）。这套加密常量
+ * （presetKey / iv / RSA pubKey+modulus）自 2015 起未变，远比米哈游 DS salt 稳定，
+ * 故可放心钉死。登录态仅需 cookie 里的 `MUSIC_U`。
+ *
+ * 拉取（只读）：
+ *   - /weapi/w/nuser/account/get   → uid + nickname（cookie-only）
+ *   - /weapi/v1/play/record        → 听歌排行（weekData / allData，含 playCount）
+ *   - /weapi/user/playlist         → 用户歌单（id / name / trackCount / creator）
+ * 输出事件形状对齐 snapshot（play / playlist），故 adapter.normalize 不变。
+ * favorite（喜欢的歌）需额外解 likelist+歌曲详情，留 snapshot 模式，live 暂不出。
+ *
+ * 加密的随机 secKey 与网络 fetch 都经 opts 注入，可确定性单测。
+ */
+"use strict";
+
+const crypto = require("node:crypto");
+
+const DEFAULT_BASE_URL = "https://music.163.com";
+
+// ─── weapi crypto constants (stable since 2015) ────────────────────────
+const PRESET_KEY = "0CoJUm6Qyw8W8jud";
+const AES_IV = "0102030405060708";
+const RSA_PUB_KEY = "010001";
+const RSA_MODULUS =
+  "00e0b509f6259df8642dbc35662901477df22677ec152b5ff68ace615bb7b7251" +
+  "52b3ab17a876aea8a5aa76d2e417629ec4ee341f56135fccf695280104e0312ec" +
+  "bda92557c93870114af6c9d05c4f7f0c3685b7a46bee255932575cce10b424d81" +
+  "3cfe4875d3e82047b97ddef52741d546b8e289dc6935b3ece0462db0a22b8e7";
+const SECKEY_ALPHABET =
+  "012345679abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+const BROWSER_UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+
+/** AES-128-CBC encrypt `text` with `key` (utf-8, fixed IV) → base64. */
+function aesEncrypt(text, key) {
+  const cipher = crypto.createCipheriv("aes-128-cbc", Buffer.from(key, "utf8"), Buffer.from(AES_IV, "utf8"));
+  return cipher.update(text, "utf8", "base64") + cipher.final("base64");
+}
+
+/** Modular exponentiation over BigInt: base^exp mod m. */
+function modpow(base, exp, m) {
+  let result = 1n;
+  base %= m;
+  while (exp > 0n) {
+    if (exp & 1n) result = (result * base) % m;
+    exp >>= 1n;
+    base = (base * base) % m;
+  }
+  return result;
+}
+
+/** Textbook RSA (no padding) of a short utf-8 string → 256-hex. */
+function rsaEncrypt(text, pubKeyHex, modulusHex) {
+  const hex = Buffer.from(text, "utf8").toString("hex");
+  const base = BigInt("0x" + (hex || "0"));
+  const exp = BigInt("0x" + pubKeyHex);
+  const mod = BigInt("0x" + modulusHex);
+  return modpow(base, exp, mod).toString(16).padStart(256, "0");
+}
+
+/**
+ * weapi envelope for a payload object. secKey is a 16-char random string
+ * (injectable for tests). Returns { params, encSecKey } form fields.
+ */
+function weapiEncrypt(payloadObj, secKey) {
+  const text = JSON.stringify(payloadObj);
+  const params = aesEncrypt(aesEncrypt(text, PRESET_KEY), secKey);
+  const reversed = secKey.split("").reverse().join("");
+  const encSecKey = rsaEncrypt(reversed, RSA_PUB_KEY, RSA_MODULUS);
+  return { params, encSecKey };
+}
+
+class NeteaseMusicApiClient {
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this._fetch =
+      opts.fetch || (typeof globalThis.fetch === "function" ? globalThis.fetch : null);
+    this._rand = opts.rand || Math.random;
+    // Test seam: force a fixed secKey so weapi output is deterministic.
+    this._secKey = opts.secKey || null;
+    this._lastErrorCode = 0;
+    this._lastErrorMsg = "";
+  }
+
+  _setLastError(code, msg) {
+    this._lastErrorCode = code;
+    this._lastErrorMsg = msg;
+  }
+  _clearLastError() {
+    this._lastErrorCode = 0;
+    this._lastErrorMsg = "";
+  }
+  get lastError() {
+    return { code: this._lastErrorCode, message: this._lastErrorMsg };
+  }
+
+  _genSecKey() {
+    if (this._secKey) return this._secKey;
+    let s = "";
+    for (let i = 0; i < 16; i += 1) {
+      s += SECKEY_ALPHABET[Math.floor(this._rand() * SECKEY_ALPHABET.length)];
+    }
+    return s;
+  }
+
+  /**
+   * POST a weapi endpoint. Returns parsed JSON on success (code 200), null on
+   * transport / API error (sets lastError).
+   * @param {string} path   e.g. "/weapi/user/playlist"
+   * @param {object} payload
+   * @param {string} cookie
+   */
+  async _post(path, payload, cookie) {
+    if (typeof this._fetch !== "function") {
+      this._setLastError(-2, "NeteaseMusicApiClient: fetch not available — pass opts.fetch or run on Node 18+");
+      return null;
+    }
+    const { params, encSecKey } = weapiEncrypt(payload, this._genSecKey());
+    const body = `params=${encodeURIComponent(params)}&encSecKey=${encodeURIComponent(encSecKey)}`;
+    let resp;
+    try {
+      resp = await this._fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "User-Agent": BROWSER_UA,
+          Referer: "https://music.163.com/",
+          Cookie: cookie,
+        },
+        body,
+      });
+    } catch (e) {
+      this._setLastError(-4, "network: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const txt = await resp.text();
+    if (!resp.ok) {
+      this._setLastError(resp.status, `HTTP ${resp.status}`);
+      return null;
+    }
+    let obj;
+    try {
+      obj = JSON.parse(txt);
+    } catch (e) {
+      this._setLastError(-3, "parse: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const code = typeof obj.code === "number" ? obj.code : 200;
+    if (code !== 200) {
+      this._setLastError(code, (obj.message || obj.msg || `code ${code}`).toString());
+      return null;
+    }
+    this._clearLastError();
+    return obj;
+  }
+
+  /** Resolve logged-in account → { uid, nickname } or null. */
+  async getAccount(cookie) {
+    const obj = await this._post("/weapi/w/nuser/account/get", {}, cookie);
+    if (obj === null) return null;
+    const profile = obj.profile && typeof obj.profile === "object" ? obj.profile : null;
+    const account = obj.account && typeof obj.account === "object" ? obj.account : null;
+    const uid =
+      (profile && profile.userId != null && String(profile.userId)) ||
+      (account && account.id != null && String(account.id)) ||
+      null;
+    if (!uid) {
+      this._setLastError(-7, "未登录或 cookie 失效（account.get 无 userId）");
+      return null;
+    }
+    return { uid, nickname: (profile && profile.nickname) || null };
+  }
+
+  /**
+   * 听歌排行。type 1 = 最近一周（含 playCount），0 = 累计。
+   * @returns {Promise<Array<{songId,song,artist,album,playCount}>|null>}
+   */
+  async getPlayRecord(cookie, uid, type = 1) {
+    const obj = await this._post("/weapi/v1/play/record", { uid, type }, cookie);
+    if (obj === null) return null;
+    const rows = Array.isArray(obj.weekData) && obj.weekData.length > 0
+      ? obj.weekData
+      : Array.isArray(obj.allData)
+        ? obj.allData
+        : [];
+    return rows.map((r) => {
+      const song = r && r.song ? r.song : {};
+      const artist = Array.isArray(song.ar)
+        ? song.ar.map((a) => a && a.name).filter(Boolean).join(" / ")
+        : "";
+      return {
+        songId: song.id != null ? String(song.id) : null,
+        song: song.name || "(未知歌曲)",
+        artist,
+        album: song.al && song.al.name ? song.al.name : null,
+        playCount: Number.isFinite(r.playCount) ? r.playCount : null,
+      };
+    });
+  }
+
+  /**
+   * 用户歌单。
+   * @returns {Promise<Array<{playlistId,name,trackCount,creator}>|null>}
+   */
+  async getUserPlaylists(cookie, uid, limit = 100) {
+    const obj = await this._post(
+      "/weapi/user/playlist",
+      { uid, limit, offset: 0, includeVideo: true },
+      cookie,
+    );
+    if (obj === null) return null;
+    const list = Array.isArray(obj.playlist) ? obj.playlist : [];
+    return list.map((p) => ({
+      playlistId: p.id != null ? String(p.id) : null,
+      name: p.name || "(未命名歌单)",
+      trackCount: Number.isFinite(p.trackCount) ? p.trackCount : null,
+      creator: p.creator && p.creator.nickname ? p.creator.nickname : null,
+    }));
+  }
+
+  /**
+   * High-level: build snapshot-shaped events (play + playlist) for a cookie.
+   * Output matches the adapter snapshot schema so normalize is unchanged.
+   * @returns {Promise<{account, events}|null>}
+   */
+  async fetchSnapshot(cookie, opts = {}) {
+    if (typeof cookie !== "string" || cookie.length === 0) {
+      this._setLastError(-1, "cookie 为空");
+      return null;
+    }
+    const account = await this.getAccount(cookie);
+    if (account === null) return null; // lastError set
+    const events = [];
+    const include = opts.include || {};
+
+    if (include.play !== false) {
+      const plays = await this.getPlayRecord(cookie, account.uid, opts.recordType != null ? opts.recordType : 1);
+      if (plays === null) return null;
+      for (const r of plays) {
+        events.push({
+          kind: "play",
+          id: r.songId ? `play-${r.songId}` : null,
+          songId: r.songId,
+          song: r.song,
+          artist: r.artist,
+          album: r.album,
+          playCount: r.playCount,
+        });
+      }
+    }
+
+    if (include.playlist !== false) {
+      const lists = await this.getUserPlaylists(cookie, account.uid, opts.playlistLimit || 100);
+      if (lists === null) return null;
+      for (const p of lists) {
+        events.push({
+          kind: "playlist",
+          id: p.playlistId ? `playlist-${p.playlistId}` : null,
+          playlistId: p.playlistId,
+          name: p.name,
+          trackCount: p.trackCount,
+          creator: p.creator,
+        });
+      }
+    }
+
+    this._clearLastError();
+    return { account: { uid: account.uid, nickname: account.nickname }, events };
+  }
+}
+
+module.exports = {
+  NeteaseMusicApiClient,
+  // Exported for tests.
+  weapiEncrypt,
+  aesEncrypt,
+  rsaEncrypt,
+  modpow,
+};

package/lib/adapters/netease-music/index.js

@@ -1,13 +1,16 @@
 "use strict";
 
 /**
- * 网易云音乐 (NetEase Cloud Music) adapter — snapshot mode.
+ * 网易云音乐 (NetEase Cloud Music) adapter — snapshot + live cookie modes.
  *
- * Mirrors the social snapshot adapters (bilibili/douyin): a device-side
- * collector (Android in-app, or a desktop helper hitting the cookie web API
- * `/user/record` `/user/playlist`) writes a snapshot JSON; this adapter
- * ingests it. Schema is OUR contract, so normalize is fully testable and the
- * vault path is reliable regardless of how the bytes were captured.
+ * 两路互补：
+ *   - snapshot 模式（inputPath）：device-side collector（Android in-app）写
+ *     的快照 JSON；schema 是 OUR contract，normalize 全可测、vault 路径稳定。
+ *   - **live 模式（cookie，v0.2 接通）**：[NeteaseMusicApiClient.fetchSnapshot]
+ *     经标准 weapi 加密拉 `/weapi/v1/play/record`（听歌排行）+ `/weapi/user/playlist`
+ *     （歌单），输出形状对齐 snapshot 故 normalize 不变。favorite（喜欢的歌）
+ *     需额外解 likelist+歌曲详情，留 snapshot 模式，live 暂不出。
+ * Schema 是 OUR contract，无论字节怎么采到 normalize 都一致。
  *
  * Snapshot schema (schemaVersion 1):
  *   {
@@ -35,7 +38,7 @@ const {
 } = require("../../constants");
 
 const NAME = "netease-music";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 
 const KIND_PLAY = "play";
@@ -63,10 +66,15 @@ function stableOriginalId(kind, id) {
 class NeteaseMusicAdapter {
   constructor(opts = {}) {
     this._dataPath = opts.inputPath || null;
+    this._cookie = opts.cookie || null;
+    // Test seam: override how the live client is built per-sync (inject fetch).
+    this._apiClientFactory =
+      typeof opts.apiClientFactory === "function" ? opts.apiClientFactory : null;
     this.name = NAME;
     this.version = VERSION;
     this.capabilities = [
       "sync:snapshot",
+      "sync:cookie",
       "parse:netease-play",
       "parse:netease-favorite",
       "parse:netease-playlist",
@@ -102,7 +110,17 @@ class NeteaseMusicAdapter {
       }
       return { ok: true, mode: "snapshot-file" };
     }
-    return { ok: false, reason: "NO_INPUT", message: "netease-music.authenticate: needs opts.inputPath" };
+    const cookie = (ctx && ctx.cookie) || this._cookie;
+    if (cookie) {
+      return /MUSIC_U=/.test(cookie)
+        ? { ok: true, mode: "cookie" }
+        : { ok: false, reason: "INVALID_COOKIE", message: "netease-music.authenticate: cookie 缺 MUSIC_U（未登录）" };
+    }
+    return {
+      ok: false,
+      reason: "NO_INPUT",
+      message: "netease-music.authenticate: needs opts.inputPath (snapshot) or opts.cookie (live weapi)",
+    };
   }
 
   async healthCheck() {
@@ -111,7 +129,16 @@ class NeteaseMusicAdapter {
 
   async *sync(opts = {}) {
     const inputPath = opts.inputPath || this._dataPath;
-    if (!inputPath) throw new Error("netease-music.sync: needs opts.inputPath (snapshot JSON)");
+    if (!inputPath) {
+      const cookie = opts.cookie || this._cookie;
+      if (cookie) {
+        yield* this._syncViaCookie({ ...opts, cookie });
+        return;
+      }
+      throw new Error(
+        "netease-music.sync: needs opts.inputPath (snapshot JSON) or opts.cookie (live weapi fetch)",
+      );
+    }
     if (!this._deps.fs.existsSync(inputPath)) return;
     const snapshot = JSON.parse(this._deps.fs.readFileSync(inputPath, "utf-8"));
     if (!snapshot || snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
@@ -144,6 +171,55 @@ class NeteaseMusicAdapter {
     }
   }
 
+  async *_syncViaCookie(opts) {
+    const client = this._apiClientFactory
+      ? this._apiClientFactory(opts)
+      : new (require("./api-client").NeteaseMusicApiClient)({
+          fetch: opts.fetch,
+          rand: opts.rand,
+          secKey: opts.secKey,
+          baseUrl: opts.baseUrl,
+        });
+    const emit = (phase, extra) => {
+      if (typeof opts.onProgress === "function") {
+        try {
+          opts.onProgress({ phase, adapter: NAME, ...extra });
+        } catch (_e) {
+          /* progress callback errors are best-effort */
+        }
+      }
+    };
+    const result = await client.fetchSnapshot(opts.cookie, {
+      include: opts.include || {},
+      recordType: opts.recordType,
+      playlistLimit: opts.playlistLimit,
+    });
+    if (result === null) {
+      const e = client.lastError;
+      throw new Error(`netease-music.sync (live): ${e.message || "fetch failed"} (code ${e.code})`);
+    }
+    const account = result.account || null;
+    emit("fetched", { count: result.events.length });
+    const capturedAt = Date.now();
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const include = opts.include || {};
+    let emitted = 0;
+    for (const ev of result.events) {
+      if (emitted >= limit) return;
+      if (!ev || !VALID_KINDS.includes(ev.kind)) continue;
+      if (include[ev.kind] === false) continue;
+      const id = (typeof ev.id === "string" && ev.id) || ev.songId || ev.playlistId || null;
+      yield {
+        adapter: NAME,
+        kind: ev.kind,
+        originalId: stableOriginalId(ev.kind, id),
+        capturedAt,
+        payload: { ...ev, capturedAt, account },
+      };
+      emitted += 1;
+    }
+  }
+
   normalize(raw) {
     if (!raw || !raw.payload) throw new Error("NeteaseMusicAdapter.normalize: payload missing");
     const kind = raw.kind || raw.payload.kind;

package/lib/adapters/social-douyin/index.js

@@ -537,6 +537,8 @@ function normalizeHistory(p, raw, ingestedAt) {
         awemeId,
         author,
         duration,
+        // Source surface from the local video_record.db (homepage_hot / etc.).
+        enterFrom: row.enterFrom || row.enter_from || p.enterFrom || null,
       },
     }],
     persons: [], places: [], items: [], topics: [],

package/lib/adapters/social-douyin-adb/aweme-detail-client.js

@@ -0,0 +1,119 @@
+/**
+ * AwemeDetailClient — resolves Douyin aweme (video) ids to human-readable
+ * metadata (desc / author / duration) so watch-history events show WHAT was
+ * watched, not just an id.
+ *
+ * Real-device finding 2026-06-11: the web detail endpoint
+ *   https://www.douyin.com/aweme/v1/web/aweme/detail/?aweme_id=<id>
+ *     &device_platform=webapp&aid=6383&channel=channel_pc_web
+ * returns HTTP 200 + full `aweme_detail` JSON (desc, author.nickname, duration,
+ * create_time) with **just a browser UA + Referer — no X-Bogus / cookie / msToken**
+ * for this guest request shape. So title resolution is a plain HTTP client, not a
+ * sign-bridge. (If Douyin later enforces signing here, this becomes the seam to
+ * route through a DouyinSignBridge — same pattern as toutiao/xhs.)
+ *
+ * Rate-friendly: dedups ids, caps per run, sleeps between calls, fails soft per
+ * id (an unresolved id just keeps "(no title)" — never aborts the sync).
+ */
+"use strict";
+
+const DEFAULT_BASE_URL = "https://www.douyin.com";
+const BROWSER_HEADERS = Object.freeze({
+  "User-Agent":
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
+    "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+  Referer: "https://www.douyin.com/",
+  "Accept-Language": "zh-CN,zh;q=0.9",
+});
+
+class AwemeDetailClient {
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this._fetch =
+      opts.fetch || (typeof globalThis.fetch === "function" ? globalThis.fetch : null);
+    this._sleep =
+      opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    this.delayMs = Number.isFinite(opts.delayMs) ? opts.delayMs : 200;
+    this.lastErrorCode = 0;
+    this.lastErrorMessage = null;
+  }
+
+  _setErr(code, msg) {
+    this.lastErrorCode = code;
+    this.lastErrorMessage = msg;
+  }
+
+  /**
+   * Resolve one aweme id → {awemeId, desc, author, durationMs, createTime} or
+   * null on any error (sets lastError).
+   */
+  async fetchDetail(aid) {
+    if (typeof this._fetch !== "function") {
+      this._setErr(-2, "AwemeDetailClient: fetch not available — pass opts.fetch or run on Node 18+");
+      return null;
+    }
+    const url =
+      `${this.baseUrl}/aweme/v1/web/aweme/detail/?aweme_id=${encodeURIComponent(String(aid))}` +
+      `&device_platform=webapp&aid=6383&channel=channel_pc_web`;
+    let resp;
+    try {
+      resp = await this._fetch(url, { method: "GET", headers: { ...BROWSER_HEADERS } });
+    } catch (e) {
+      this._setErr(-4, "network: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const body = await resp.text();
+    if (!resp.ok) {
+      this._setErr(resp.status, `HTTP ${resp.status}`);
+      return null;
+    }
+    let obj;
+    try {
+      obj = JSON.parse(body);
+    } catch (e) {
+      this._setErr(-3, "parse: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const code = typeof obj.status_code === "number" ? obj.status_code : 0;
+    if (code !== 0) {
+      this._setErr(code, (obj.status_msg || `status_code=${code}`).toString());
+      return null;
+    }
+    const d = obj.aweme_detail;
+    if (!d || typeof d !== "object") {
+      this._setErr(-5, "no aweme_detail (deleted/private video?)");
+      return null;
+    }
+    this._setErr(0, null);
+    return {
+      awemeId: String(aid),
+      desc: d.desc || null,
+      author: (d.author && d.author.nickname) || null,
+      durationMs: Number.isFinite(d.duration) ? d.duration : null,
+      createTime: Number.isFinite(d.create_time) ? d.create_time : null,
+    };
+  }
+
+  /**
+   * Resolve many ids → Map<aid, detail>. Dedups, caps at `limit`, sleeps
+   * `delayMs` between calls. Per-id failures are skipped (not in the map).
+   * @param {string[]} aids
+   * @param {{limit?: number}} [opts]
+   */
+  async resolveMany(aids, opts = {}) {
+    const uniq = [...new Set((aids || []).map(String))];
+    const cap = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : uniq.length;
+    const out = new Map();
+    let n = 0;
+    for (const aid of uniq) {
+      if (n >= cap) break;
+      const d = await this.fetchDetail(aid);
+      n += 1;
+      if (d) out.set(aid, d);
+      if (this.delayMs > 0 && n < cap) await this._sleep(this.delayMs);
+    }
+    return out;
+  }
+}
+
+module.exports = { AwemeDetailClient, BROWSER_HEADERS };

package/lib/adapters/social-douyin-adb/collector.js

@@ -159,7 +159,121 @@ async function collectAndSync(bridge, registry, opts = {}) {
   };
 }
 
+// ── Watch-history (video_record.db) path ─────────────────────────────────
+// Distinct from the IM-db path above: pulls the plaintext video_record.db and
+// emits `history` events (KIND_HISTORY → BROWSE) the social-douyin adapter
+// already normalizes. No X-Bogus, no SQLCipher — the durable "what/when the
+// user watched" signal. See watch-history-reader.js.
+const DOUYIN_SNAPSHOT_SCHEMA_VERSION = 1;
+
+async function collectWatchHistory(bridge, opts = {}) {
+  if (!bridge || typeof bridge.invoke !== "function") {
+    throw new TypeError(
+      "DouyinAdbCollector.collectWatchHistory: bridge must expose invoke(method, params)",
+    );
+  }
+  const now = opts.now || Date.now;
+  const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 2000;
+  const res = await bridge.invoke("douyin.watch-history", { limit });
+  if (!res || !Array.isArray(res.records)) {
+    throw new Error(
+      "DouyinAdbCollector.collectWatchHistory: bridge.invoke('douyin.watch-history') returned malformed payload",
+    );
+  }
+  const uid = res.uid || opts.uid || null;
+  const events = [];
+  for (const r of res.records) {
+    if (!r || !r.awemeId) continue;
+    events.push({
+      kind: "history",
+      id: `history-${r.awemeId}-${r.capturedAt || ""}`,
+      capturedAt: r.capturedAt || now(),
+      awemeId: r.awemeId,
+      enterFrom: r.enterFrom || null,
+    });
+  }
+
+  // Optional title enrichment: resolve aweme ids → desc/author/duration via the
+  // web detail endpoint (plain HTTP, no signing) so events show WHAT was watched.
+  // Capped + dedup'd + fail-soft; an unresolved id just keeps "(no title)".
+  let titlesResolved = 0;
+  if (opts.resolveTitles && events.length > 0) {
+    const client =
+      opts._detailClient ||
+      new (require("./aweme-detail-client").AwemeDetailClient)({
+        fetch: opts.fetch,
+        delayMs: opts.titleDelayMs,
+      });
+    // Resolve most-recent first (events come back DESC by view time).
+    const titles = await client.resolveMany(
+      events.map((e) => e.awemeId),
+      { limit: Number.isInteger(opts.titleLimit) && opts.titleLimit > 0 ? opts.titleLimit : 60 },
+    );
+    for (const e of events) {
+      const t = titles.get(e.awemeId);
+      if (t) {
+        // normalizeHistory reads title/author/duration off the snapshot event.
+        e.title = t.desc;
+        e.author = t.author;
+        e.duration = t.durationMs;
+        titlesResolved += 1;
+      }
+    }
+  }
+
+  const snapshot = {
+    schemaVersion: DOUYIN_SNAPSHOT_SCHEMA_VERSION,
+    snapshottedAt: now(),
+    account: {
+      ...(uid ? { shortId: String(uid) } : {}),
+      displayName: opts.displayName,
+    },
+    events,
+  };
+  const snapshotPath = writeSnapshotJson(snapshot, { dir: opts.stagingDir });
+  return {
+    snapshotPath,
+    uid,
+    eventCounts: { history: events.length, total: events.length },
+    titlesResolved,
+  };
+}
+
+async function collectWatchHistoryAndSync(bridge, registry, opts = {}) {
+  if (!registry || typeof registry.syncAdapter !== "function") {
+    throw new TypeError(
+      "DouyinAdbCollector.collectWatchHistoryAndSync: registry must expose syncAdapter(name, options)",
+    );
+  }
+  const collectResult = await collectWatchHistory(bridge, opts);
+  let syncReport = null;
+  let cleanupFailed = false;
+  try {
+    syncReport = await registry.syncAdapter("social-douyin", {
+      inputPath: collectResult.snapshotPath,
+    });
+  } finally {
+    try {
+      cleanupSnapshotJson(collectResult.snapshotPath);
+    } catch (_e) {
+      cleanupFailed = true;
+    }
+  }
+  return {
+    ...syncReport,
+    douyin: {
+      uid: collectResult.uid,
+      eventCounts: collectResult.eventCounts,
+      titlesResolved: collectResult.titlesResolved || 0,
+      mode: "watch-history",
+      cleanupFailed,
+    },
+  };
+}
+
 module.exports = {
   collect,
   collectAndSync,
+  collectWatchHistory,
+  collectWatchHistoryAndSync,
 };