@chainlesschain/personal-data-hub 0.4.4 → 0.4.6

package/lib/adapters/shopping-pinduoduo/index.js

@@ -1,29 +1,32 @@
 /**
- * §2.4c 购物三联 v0.2 — Pinduoduo (拼多多) adapter, snapshot-only.
+ * §2.4c 购物三联 — Pinduoduo (拼多多) adapter, dual-mode (snapshot + cookie-api).
  *
- * Mirror of shopping-jd / shopping-meituan snapshot-mode pattern, **but
- * without a cookie-mode fallback** because:
+ * v0.3 brings 拼多多 to parity with shopping-taobao / shopping-jd /
+ * shopping-meituan by adding a cookie-api fetch path alongside the existing
+ * snapshot ingest. As with the other shopping adapters the actual HTTP call is
+ * delegated to an injected `fetchFn` (the Android in-APK cc uses OkHttp; the
+ * desktop hub uses an Electron WebView net request) so this module stays a
+ * pure-Node parser + orchestrator.
  *
- *   1. mobile.yangkeduo.com web endpoint `/proxy/api/galerie/transaction/
- *      transaction_list` requires `anti_token` signing computed by client-side
- *      JS (similar to 抖音 X-Bogus). No pure-Node implementation survives
- *      pinduoduo's monthly anti_token rotation.
- *   2. Pinduoduo Android app has no built-in "export orders" feature, so
- *      there's no SAF source-format to parse directly either.
+ *   1. snapshot mode (opts.inputPath): ingest a snapshot JSON produced by a
+ *      browser extension / hand-roll (stateless — account OPTIONAL).
  *
- * v0.2 deliverable = **scaffold + snapshot-mode JSON ingest**. User-facing
- * paths for producing the snapshot JSON:
+ *   2. cookie-api mode (opts.account.cookies): fetch
+ *      `mobile.yangkeduo.com/proxy/api/galerie/transaction/transaction_list`
+ *      via the injected `fetchFn`, paginating with the `pageNumber` cursor and
+ *      stopping at the `sinceWatermark`. account.uid REQUIRED in this mode.
  *
- *   a) Browser extension (planned v0.3) that scrapes yangkeduo.com order
- *      pages while logged in and exports JSON matching this schema.
- *   b) Manual hand-roll (rare; for testing).
+ * ── anti_token signing seam ──────────────────────────────────────────────
+ *   Pinduoduo's transaction_list requires an `anti_token` (a.k.a.
+ *   `anti-content`) computed by client-side JS — analogous to 抖音 X-Bogus.
+ *   No pure-Node implementation survives pinduoduo's anti_token rotation, so
+ *   the signing itself is injected via `opts.signProvider` (or constructor
+ *   `signProvider`). On Android the in-APK WebView JS VM produces the token;
+ *   in tests a stub returns a fixed value. When no signProvider is configured
+ *   the request is still issued with `antiToken: null` — best-effort, the
+ *   endpoint may 403, which surfaces as zero events rather than a crash.
  *
- * UI surface: pinduoduo card appears alongside alipay/taobao/jd/meituan in
- * 推文 §"支付与购物" 大类, with an explicit "v0.2 待用户导出 — 需 web
- * extension 或手抄" banner so user knows the limitation.
- *
- * Snapshot schema (mirrors PinduoduoLocalCollector.SNAPSHOT_SCHEMA_VERSION
- * once the Kotlin collector lands in v0.3+):
+ * Snapshot schema (mirrors PinduoduoLocalCollector.SNAPSHOT_SCHEMA_VERSION):
  *
  *   {
  *     "schemaVersion": 1,
@@ -45,33 +48,46 @@
  *     ]
  *   }
  *
- * Future v0.3: HTML parsing (`Save As Webpage` from `mobile.yangkeduo.com/
+ * Future v0.4: HTML parsing (`Save As Webpage` from `mobile.yangkeduo.com/
  * users/orders.html` — pinduoduo's order list endpoint).
  */
 
 "use strict";
 
 const fs = require("node:fs");
-const { normalizeOrderRecord } = require("../shopping-base");
+const { normalizeOrderRecord, CookieAuth } = require("../shopping-base");
 
 const NAME = "shopping-pinduoduo";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 
 const KIND_ORDER = "order";
 const VALID_SNAPSHOT_KINDS = Object.freeze([KIND_ORDER]);
 
+const PINDUODUO_ORDERS_URL =
+  "https://mobile.yangkeduo.com/proxy/api/galerie/transaction/transaction_list";
+
 class PinduoduoAdapter {
   constructor(opts = {}) {
-    // §2.4c v0.2: account is OPTIONAL — snapshot mode is stateless. There's
-    // no cookie mode at all (anti_token signing path deferred to v0.3+).
+    // §2.4c: account is OPTIONAL — snapshot mode is stateless. Cookie-api mode
+    // activates only when account.cookies is supplied; account.uid is then
+    // required (checked at sync time).
     this.account = opts.account || null;
+    this._cookieAuth =
+      opts.account && opts.account.cookies
+        ? new CookieAuth({ platform: "pinduoduo", cookies: opts.account.cookies })
+        : null;
+    this._fetchFn = typeof opts.fetchFn === "function" ? opts.fetchFn : defaultFetch;
+    // anti_token signing seam — see file header. Async fn({ url, query,
+    // cookies }) → string|null. When absent, requests carry antiToken: null.
+    this._signProvider =
+      typeof opts.signProvider === "function" ? opts.signProvider : null;
 
     this.name = NAME;
     this.version = VERSION;
-    this.capabilities = ["sync:snapshot", "parse:pinduoduo-orders"];
-    this.extractMode = "user-export";
-    this.rateLimits = {};
+    this.capabilities = ["sync:snapshot", "sync:cookie-api", "parse:pinduoduo-orders"];
+    this.extractMode = "web-api";
+    this.rateLimits = { perMinute: 8, perDay: 200 };
     this.dataDisclosure = {
       fields: [
         "pinduoduo:order_sn / mall_name / goods_list / order_amount / address",
@@ -99,15 +115,33 @@ class PinduoduoAdapter {
       }
       return { ok: true, mode: "snapshot-file" };
     }
+    if (this._cookieAuth) {
+      const ok = await this._cookieAuth.validate();
+      if (!ok) return { ok: false, reason: "INVALID_COOKIE", error: "cookies missing" };
+      if (!this.account || !this.account.uid) {
+        return {
+          ok: false,
+          reason: "NO_ACCOUNT_UID",
+          message: "cookie-api mode requires account.uid",
+        };
+      }
+      return { ok: true, account: this.account.uid, mode: "cookie" };
+    }
     return {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "PinduoduoAdapter.authenticate: needs opts.inputPath (snapshot mode — no cookie mode in v0.2)",
+        "PinduoduoAdapter.authenticate: needs opts.inputPath (snapshot mode) OR opts.account.cookies (cookie-api mode — anti_token signing via signProvider)",
     };
   }
 
   async healthCheck() {
+    if (this._cookieAuth) {
+      const r = await this.authenticate();
+      return r.ok
+        ? { ok: true, lastChecked: Date.now() }
+        : { ok: false, reason: r.reason, error: r.error };
+    }
     return { ok: true, lastChecked: Date.now() };
   }
 
@@ -116,21 +150,25 @@ class PinduoduoAdapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (this._cookieAuth) {
+      yield* this._syncViaCookie(opts);
+      return;
+    }
     throw new Error(
-      "PinduoduoAdapter.sync: needs opts.inputPath (snapshot mode; no cookie/api mode in v0.2 because pinduoduo's web API requires anti_token JS-VM signing)",
+      "PinduoduoAdapter.sync: needs opts.inputPath (snapshot mode) OR opts.account.cookies (cookie-api mode; pinduoduo's web API requires anti_token signing supplied via opts.signProvider)",
     );
   }
 
   async *_syncViaSnapshot(opts) {
     const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
     // v0.2 explicit JSON-only. HTML parsing (SAF-exported webpage from
-    // yangkeduo.com order list) is future v0.3 work.
+    // yangkeduo.com order list) is future v0.4 work.
     let snapshot;
     try {
       snapshot = JSON.parse(raw);
     } catch (err) {
       throw new Error(
-        `shopping-pinduoduo.sync: snapshot must be JSON (v0.3 will add HTML parsing). Got parse error: ${err.message}`,
+        `shopping-pinduoduo.sync: snapshot must be JSON (v0.4 will add HTML parsing). Got parse error: ${err.message}`,
       );
     }
     if (
@@ -184,11 +222,77 @@ class PinduoduoAdapter {
     }
   }
 
+  async *_syncViaCookie(opts = {}) {
+    if (!this.account || !this.account.uid) {
+      throw new Error(
+        "PinduoduoAdapter._syncViaCookie: account.uid required (set via new PinduoduoAdapter({ account: { uid, cookies } }))",
+      );
+    }
+    if (!(await this._cookieAuth.validate())) return;
+    const sinceMs =
+      opts.sinceWatermark != null
+        ? parseInt(String(opts.sinceWatermark), 10) || 0
+        : Date.now() - 365 * 24 * 3600_000; // default last year
+    const pageSize = Number.isFinite(opts.pageSize) ? opts.pageSize : 10;
+    const include = opts.include || {};
+    if (include[KIND_ORDER] === false) return;
+
+    let pageNumber = 1;
+    while (true) {
+      const query = { pageNumber, pageSize, ts: Date.now() };
+      // anti_token signing seam — best-effort. null when no signProvider.
+      let antiToken = null;
+      if (this._signProvider) {
+        antiToken = await this._signProvider({
+          url: PINDUODUO_ORDERS_URL,
+          query,
+          cookies: this._cookieAuth.toHeader(),
+        });
+      }
+      const resp = await this._fetchFn({
+        url: PINDUODUO_ORDERS_URL,
+        cookies: this._cookieAuth.toHeader(),
+        antiToken,
+        query,
+      });
+      const orders = extractOrders(resp);
+      if (!orders.length) break;
+      let pageHasNew = false;
+      let reachedWatermark = false;
+      for (const raw of orders) {
+        const rec = orderToRecord(raw);
+        if (!rec) continue;
+        if (rec.placedAt && rec.placedAt < sinceMs) {
+          reachedWatermark = true; // everything from here on is older
+          break;
+        }
+        pageHasNew = true;
+        yield {
+          adapter: NAME,
+          originalId: rec.orderId,
+          capturedAt: rec.paidAt || rec.placedAt || Date.now(),
+          payload: { record: rec },
+        };
+      }
+      // Stop once we've crossed the watermark, drained the page, or the page
+      // came back short (last page).
+      if (reachedWatermark || !pageHasNew || orders.length < pageSize) break;
+      pageNumber += 1;
+    }
+  }
+
   normalize(raw) {
     if (!raw || !raw.payload) {
       throw new Error("PinduoduoAdapter.normalize: payload missing");
     }
-    // Snapshot-mode only — payload carries fields directly on the event.
+    // Cookie-api mode wraps a normalized record under payload.record; snapshot
+    // mode carries the raw event fields directly on the payload.
+    if (raw.payload.record) {
+      return normalizeOrderRecord(raw.payload.record, {
+        adapterName: NAME,
+        adapterVersion: VERSION,
+      });
+    }
     const rec = snapshotEventToRecord(raw.payload);
     return normalizeOrderRecord(rec, {
       adapterName: NAME,
@@ -208,6 +312,104 @@ function stableOriginalId(kind, id) {
   return `pinduoduo:${kind}:${safe}`;
 }
 
+/**
+ * Pull the order array out of a transaction_list response. Pinduoduo nests it
+ * under different keys across endpoint versions; the injected fetchFn may also
+ * pre-flatten to `{ orders }`. Tolerant of all common shapes.
+ */
+function extractOrders(resp) {
+  if (!resp || typeof resp !== "object") return [];
+  if (Array.isArray(resp.orders)) return resp.orders;
+  if (Array.isArray(resp.order_list)) return resp.order_list;
+  if (Array.isArray(resp.list)) return resp.list;
+  if (resp.result && Array.isArray(resp.result.order_list)) return resp.result.order_list;
+  if (resp.result && Array.isArray(resp.result.list)) return resp.result.list;
+  return [];
+}
+
+/**
+ * Map one pinduoduo transaction_list order object → vendor-neutral OrderRecord.
+ * Pinduoduo amounts are in 分 (cents); converted to 元 here. Field names are
+ * best-effort across endpoint versions (camelCase + snake_case fallbacks).
+ */
+function orderToRecord(o) {
+  if (!o || typeof o !== "object") return null;
+  const orderId = o.order_sn || o.orderSn || o.orderId || o.id;
+  if (!orderId) return null;
+  const merchant = o.mall_name || o.mallName || o.merchantName || o.shop_name || "拼多多";
+
+  const items = [];
+  const rawItems = o.goods_list || o.order_goods || o.goodsList || o.items || [];
+  for (const it of Array.isArray(rawItems) ? rawItems : []) {
+    if (!it) continue;
+    items.push({
+      name: it.goods_name || it.goodsName || it.name || it.skuName,
+      quantity: parseInt(it.goods_number || it.goods_count || it.quantity || 1, 10),
+      unitPrice: centsToYuan(it.goods_price || it.goodsPrice || it.unitPrice || 0),
+      sku: it.sku_id || it.skuId || it.goods_id || it.sku || null,
+    });
+  }
+
+  return {
+    vendorId: "pinduoduo",
+    orderId: String(orderId),
+    placedAt: parseTime(o.order_time || o.create_at || o.createAt || o.order_create_at),
+    paidAt: parseTime(o.pay_time || o.payTime || o.group_order_pay_time),
+    status: mapStatus(pickStatusText(o)),
+    merchantName: merchant,
+    totalAmount: {
+      value: centsToYuan(o.order_amount || o.orderAmount || o.pay_amount || o.total_amount || 0),
+      currency: "CNY",
+    },
+    items,
+    recipient: o.receive_name || o.receiver || o.recipient || null,
+    shippingAddress: o.address || o.receive_address || o.shippingAddress || null,
+    trackingNumber: o.tracking_number || o.waybill_no || o.trackingNumber || null,
+    extras: { capturedBy: "cookie-api", platform: "pinduoduo" },
+  };
+}
+
+/**
+ * Pinduoduo carries a human-readable status under several keys; prefer text
+ * over the numeric `order_status` code so mapStatus's keyword match works.
+ */
+function pickStatusText(o) {
+  const text =
+    o.order_status_prompt ||
+    o.orderStatusPrompt ||
+    o.status_prompt ||
+    o.statusPrompt ||
+    o.status_desc ||
+    null;
+  if (text) return text;
+  // Fall back to the numeric order_status code (best-effort PDD mapping).
+  const code = o.order_status != null ? o.order_status : o.orderStatus;
+  switch (Number(code)) {
+    case 1:
+      return "待付款";
+    case 2:
+      return "待发货";
+    case 3:
+      return "已发货";
+    case 4:
+      return "已完成";
+    case 5:
+    case 6:
+      return "已关闭";
+    default:
+      return o.status != null ? String(o.status) : "";
+  }
+}
+
+function centsToYuan(v) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return 0;
+  // Snapshot/test inputs may already be 元 with a decimal point; treat any
+  // non-integer as 元, integers as 分.
+  if (!Number.isInteger(n)) return n;
+  return Math.round(n) / 100;
+}
+
 function snapshotEventToRecord(ev) {
   const items = [];
   const rawItems = Array.isArray(ev.items) ? ev.items : [];
@@ -266,8 +468,14 @@ function mapStatus(s) {
   return "placed";
 }
 
+async function defaultFetch(_opts) {
+  throw new Error("PinduoduoAdapter: no fetchFn configured");
+}
+
 module.exports = {
   PinduoduoAdapter,
+  orderToRecord,
+  extractOrders,
   NAME,
   VERSION,
   SNAPSHOT_SCHEMA_VERSION,

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,
 };

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

@@ -38,13 +38,30 @@ const {
   cleanupSnapshotJson,
   SNAPSHOT_SCHEMA_VERSION,
 } = require("./snapshot-builder");
-const { collect, collectAndSync } = require("./collector");
+const {
+  collect,
+  collectAndSync,
+  collectWatchHistory,
+  collectWatchHistoryAndSync,
+} = require("./collector");
+const {
+  createDouyinWatchExtension,
+  VIDEO_RECORD_DB_REMOTE_PATH,
+} = require("./watch-history-reader");
+const { AwemeDetailClient } = require("./aweme-detail-client");
 
 module.exports = {
   // Extension factory (wiring registers this on the bridge)
   createDouyinDbExtension,
   DOUYIN_DB_REMOTE_DIR,
   IM_DB_PATTERN,
+  // Watch-history (video_record.db) extension + path
+  createDouyinWatchExtension,
+  VIDEO_RECORD_DB_REMOTE_PATH,
+  collectWatchHistory,
+  collectWatchHistoryAndSync,
+  // Aweme title resolver (web detail endpoint, no signing)
+  AwemeDetailClient,
   // Parser + builder (also exposed for advanced callers / tests)
   parseImDb,
   buildSnapshot,