@chainlesschain/personal-data-hub 0.3.1 → 0.3.6

package/lib/adapters/social-bilibili-adb/cookies-extension.js

@@ -0,0 +1,250 @@
+"use strict";
+
+/**
+ * Phase 1a (Bilibili C 路径 — 2026-05-25): bilibili.cookies ADB extension
+ * factory.
+ *
+ * Plugs into the `opts.extensions` slot of `createHostAdbBridge` /
+ * `createDesktopAdbBridge` (see Phase B0 plugin API). Pipeline:
+ *
+ *   1. ADB-pull /data/data/tv.danmaku.bili/app_webview/Default/Cookies
+ *      to a host-side temp file via `su -c base64 ...` streaming. Bilibili
+ *      release APKs are NOT debuggable, so `run-as` is not an option;
+ *      base64-over-shell is the cross-vendor-safe path (avoids the
+ *      MIUI/HyperOS FUSE label remap trap [[android-runas-loopback-selinux-split]]
+ *      that hits stage-via-sdcard).
+ *   2. Parse the chromium-shape sqlite via [chromium-cookies-reader].
+ *   3. Filter to BILIBILI_COOKIE_NAMES, assemble a `Cookie:` header.
+ *   4. Also derive `uid` from DedeUserID + `displayName` from
+ *      decode-as-needed (Bilibili stores the UID in DedeUserID as a
+ *      numeric string — no fetch needed).
+ *
+ * Returns:
+ *   {
+ *     cookie: string,            // full Cookie header
+ *     uid: number,               // numeric DedeUserID
+ *     extractedAt: number,       // epoch ms
+ *     diagnostic: {
+ *       cookieCount: number,     // total cookies in DB for bilibili.com
+ *       hadEncrypted: boolean,   // any encrypted_value rows were skipped
+ *     }
+ *   }
+ *
+ * Failure modes (all throw HostAdbBridgeUnavailableError-class errors so
+ * the caller's UI can surface a useful banner):
+ *   - su not available / device not rooted
+ *   - Bilibili App not installed (path doesn't exist)
+ *   - cookies sqlite empty (user never logged into Bilibili App)
+ *   - any required cookie missing (user logged out, or Keystore-wrapped
+ *     value our parser can't decrypt yet)
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+const {
+  readChromiumCookies,
+  assembleBilibiliCookieHeader,
+} = require("./chromium-cookies-reader");
+
+const BILIBILI_COOKIES_REMOTE_PATH =
+  "/data/data/tv.danmaku.bili/app_webview/Default/Cookies";
+
+/**
+ * Pull the Bilibili App's Chromium Cookies sqlite to a host-side temp file
+ * via ADB `su -c base64`.
+ *
+ * Uses base64 streaming rather than stage-via-sdcard because:
+ *  (a) avoids MIUI/HyperOS SELinux label-remap on /sdcard ([[android-runas-loopback-selinux-split]])
+ *  (b) avoids leaving a copy in /sdcard if the host-side write fails
+ *  (c) works identically across vendor ROMs since we never touch the FUSE
+ *      layer
+ *
+ * Tradeoff: base64 has 33% size overhead. Bilibili's Cookies file is
+ * typically 50-200 KB, so this is negligible (<300 KB over the wire vs
+ * raw 200 KB).
+ */
+async function pullCookiesViaSu(adb, serial, opts) {
+  const adbOpts = { serial, timeoutMs: opts?.timeoutMs || 60_000 };
+  // Probe existence first — gives a cleaner error than a base64-of-missing-file
+  // attempt (which would spit "No such file" to stdout).
+  const lsOut = await adb(
+    [
+      "shell",
+      "su",
+      "-c",
+      `ls ${BILIBILI_COOKIES_REMOTE_PATH} 2>/dev/null || echo NOT_FOUND`,
+    ],
+    adbOpts,
+  );
+  const lsLine = lsOut.replace(/\r+$/gm, "").trim();
+  if (lsLine === "NOT_FOUND" || lsLine === "") {
+    throw new Error(
+      "BILIBILI_NOT_INSTALLED_OR_NEVER_LOGGED_IN: " +
+        BILIBILI_COOKIES_REMOTE_PATH +
+        " not found. Install Bilibili App + log in once on the phone, then retry.",
+    );
+  }
+  // su availability — `su -c id -u` returns "0" or "uid=0(root)..." on rooted
+  // phones; non-zero/non-root → throw a clear error.
+  const idOut = await adb(["shell", "su", "-c", "id -u"], adbOpts);
+  const idLine = idOut.replace(/\r+$/gm, "").trim();
+  if (idLine !== "0" && !idLine.includes("uid=0")) {
+    throw new Error(
+      "BILIBILI_NO_ROOT: this phone isn't rooted (su returned `" +
+        idLine.substring(0, 60) +
+        "`). Bilibili release APK isn't debuggable, so root is required to read its Cookies DB.",
+    );
+  }
+  // Base64-stream the file. We pipe through `tr -d '\n'` so the host side
+  // sees a single base64 string with no embedded whitespace artifacts (some
+  // Android `base64` impls wrap at 76 columns).
+  const b64 = await adb(
+    [
+      "shell",
+      "su",
+      "-c",
+      `base64 ${BILIBILI_COOKIES_REMOTE_PATH} | tr -d '\\n\\r'`,
+    ],
+    { ...adbOpts, timeoutMs: opts?.timeoutMs || 60_000 },
+  );
+  const b64Clean = b64.replace(/[\r\n\t ]+/g, "");
+  if (b64Clean.length === 0) {
+    throw new Error(
+      "BILIBILI_COOKIES_EMPTY: base64 stream returned 0 bytes. su exec may have silently failed (MIUI ROM?), retry or check `adb logcat`.",
+    );
+  }
+  let buf;
+  try {
+    buf = Buffer.from(b64Clean, "base64");
+  } catch (e) {
+    throw new Error(
+      "BILIBILI_BASE64_PARSE: stream from device wasn't valid base64 (" +
+        (e.message || String(e)) +
+        "). Possible MIUI ROM corrupting stdout — try plug-in via `adb pull` instead.",
+    );
+  }
+  if (buf.length < 1024) {
+    // Chromium Cookies sqlite is >=4KB even when empty (page size + magic
+    // header). <1KB means truncation.
+    throw new Error(
+      "BILIBILI_COOKIES_TRUNCATED: decoded file is only " +
+        buf.length +
+        " bytes — expected ≥4KB sqlite. Possible su silent fail; check `adb logcat`.",
+    );
+  }
+  // Verify sqlite magic header to catch any kind of corruption early.
+  // Magic: "SQLite format 3\0" (16 bytes).
+  const magic = buf.subarray(0, 16).toString("latin1");
+  if (!magic.startsWith("SQLite format 3")) {
+    throw new Error(
+      "BILIBILI_NOT_SQLITE: decoded file lacks `SQLite format 3` magic header. Got bytes: " +
+        buf.subarray(0, 16).toString("hex"),
+    );
+  }
+  // Write to a unique temp path. Use crypto.randomUUID for collision safety
+  // when two desktop bridges run in parallel.
+  const tmpDir = os.tmpdir();
+  const tmpFile = path.join(
+    tmpDir,
+    `cc-bilibili-cookies-${crypto.randomUUID()}.db`,
+  );
+  fs.writeFileSync(tmpFile, buf);
+  return tmpFile;
+}
+
+/**
+ * Factory: returns an extension handler suitable for the `opts.extensions`
+ * map of `createHostAdbBridge` / `createDesktopAdbBridge`. Wiring:
+ *
+ *   const ext = createBilibiliCookiesExtension();
+ *   const bridge = createHostAdbBridge({
+ *     extensions: { "bilibili.cookies": ext },
+ *   });
+ *   await bridge.invoke("bilibili.cookies");  // → {cookie, uid, ...}
+ *
+ * The handler is stateless — no closure-captured device serial / cache.
+ * Each invocation pulls a fresh Cookies DB (Bilibili cookies rotate
+ * ~weekly; caching across a hub-restart would be brittle).
+ *
+ * @param {object} [factoryOpts]
+ * @param {number} [factoryOpts.timeoutMs=60000]  per-adb-call timeout
+ * @param {(path: string) => void} [factoryOpts.onCleanupFailed]
+ *   callback for non-fatal temp-file cleanup errors (default = swallow)
+ * @returns {(params: object, ctx: object) => Promise<object>}
+ */
+function createBilibiliCookiesExtension(factoryOpts = {}) {
+  const timeoutMs = factoryOpts.timeoutMs || 60_000;
+  const onCleanupFailed = factoryOpts.onCleanupFailed || (() => {});
+
+  return async function bilibiliCookiesHandler(_params, ctx) {
+    if (!ctx || typeof ctx.adb !== "function" || typeof ctx.pickDevice !== "function") {
+      throw new TypeError(
+        "bilibili.cookies extension: ctx must provide {adb, pickDevice} (got " +
+          typeof ctx +
+          ")",
+      );
+    }
+    const serial = await ctx.pickDevice();
+    let tmpFile = null;
+    try {
+      tmpFile = await pullCookiesViaSu(ctx.adb, serial, { timeoutMs });
+      const cookies = readChromiumCookies(tmpFile, "bilibili.com");
+      const cookieCount = cookies.length;
+      const hadEncrypted = (cookies._skippedEncryptedCount || 0) > 0;
+      const { header, missing } = assembleBilibiliCookieHeader(cookies);
+      if (header === null) {
+        throw new Error(
+          "BILIBILI_COOKIES_INCOMPLETE: missing required cookies " +
+            JSON.stringify(missing) +
+            ". User probably logged out, or Bilibili App version uses Keystore-wrapped values (hadEncrypted=" +
+            hadEncrypted +
+            "). Tell user to relog on phone.",
+        );
+      }
+      // Derive uid from DedeUserID (we parse it again here because the
+      // assembled header has it but the caller may not want to split the
+      // header string themselves).
+      const dedeRow = cookies.find((c) => c.name === "DedeUserID");
+      const uid = dedeRow ? parseInt(dedeRow.value, 10) : null;
+      if (!Number.isFinite(uid) || uid <= 0) {
+        throw new Error(
+          "BILIBILI_INVALID_UID: DedeUserID=" +
+            (dedeRow ? dedeRow.value : "<missing>") +
+            " is not a positive integer.",
+        );
+      }
+      return {
+        cookie: header,
+        uid,
+        extractedAt: Date.now(),
+        diagnostic: {
+          cookieCount,
+          hadEncrypted,
+        },
+      };
+    } finally {
+      // Best-effort cleanup. Leaving a stale temp file isn't a security
+      // issue (we wrote it ourselves; nothing else has the path), but it's
+      // unhygienic over time.
+      if (tmpFile) {
+        try {
+          fs.unlinkSync(tmpFile);
+        } catch (e) {
+          onCleanupFailed(tmpFile);
+        }
+      }
+    }
+  };
+}
+
+module.exports = {
+  createBilibiliCookiesExtension,
+  BILIBILI_COOKIES_REMOTE_PATH,
+  // Exposed for tests
+  _internals: {
+    pullCookiesViaSu,
+  },
+};

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

@@ -0,0 +1,51 @@
+"use strict";
+
+/**
+ * social-bilibili-adb — Phase 1 (Bilibili C 路径) entry.
+ *
+ * Phase 1a (commit `7c12fd253`) — cookies extraction layer
+ * Phase 1b (this commit)        — Node API client + snapshot builder + collector
+ * Phase 1c (next)               — wiring injection + UI + real-device E2E
+ *
+ * Pipeline (see collector.js):
+ *   bridge.invoke("bilibili.cookies")
+ *     → BilibiliApiClient (4 endpoints, WBI-signed)
+ *     → buildSnapshot → writeSnapshotJson
+ *     → registry.syncAdapter("social-bilibili", { inputPath })
+ */
+
+const {
+  createBilibiliCookiesExtension,
+  BILIBILI_COOKIES_REMOTE_PATH,
+} = require("./cookies-extension");
+const {
+  readChromiumCookies,
+  assembleBilibiliCookieHeader,
+  BILIBILI_COOKIE_NAMES,
+} = require("./chromium-cookies-reader");
+const { BilibiliApiClient, extractUid } = require("./api-client");
+const {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+} = require("./snapshot-builder");
+const { collect, collectAndSync } = require("./collector");
+
+module.exports = {
+  // Phase 1a
+  createBilibiliCookiesExtension,
+  BILIBILI_COOKIES_REMOTE_PATH,
+  readChromiumCookies,
+  assembleBilibiliCookieHeader,
+  BILIBILI_COOKIE_NAMES,
+  // Phase 1b
+  BilibiliApiClient,
+  extractUid,
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+  collect,
+  collectAndSync,
+};

package/lib/adapters/social-bilibili-adb/snapshot-builder.js

@@ -0,0 +1,197 @@
+"use strict";
+
+/**
+ * Phase 1b (Bilibili C 路径 — 2026-05-25): convert 4 API response arrays
+ * into a snapshot JSON file that the existing `social-bilibili` adapter
+ * consumes in snapshot mode.
+ *
+ * Schema (mirrors `adapter.js`:SNAPSHOT_SCHEMA_VERSION = 1):
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "snapshottedAt": <epoch-ms>,
+ *     "account": { "uid": "<numeric uid as string>", "displayName": "" },
+ *     "events": [
+ *       { "kind": "history",   "id": "BV1...",      "capturedAt": <ms>, ...fields },
+ *       { "kind": "favourite", "id": "fav-BV1...",  "capturedAt": <ms>, ...fields },
+ *       { "kind": "dynamic",   "id": "dyn-<rid>",   "capturedAt": <ms>, ...fields },
+ *       { "kind": "follow",    "id": "follow-<mid>", "capturedAt": <ms>, ...fields }
+ *     ]
+ *   }
+ *
+ * Field mapping (BilibiliApiClient.js return shapes → event fields):
+ *   HistoryItem.viewAt        → capturedAt
+ *   FavouriteItem.savedAt     → capturedAt
+ *   DynamicItem.publishedAt   → capturedAt
+ *   FollowItem.followedAt     → capturedAt
+ *
+ * All other fields pass through verbatim (the adapter stores the whole
+ * event object as the payload via `{...ev, account}`).
+ *
+ * Stable `id` derivation matches the Android side
+ * (BilibiliLocalCollector.kt does the same prefix-namespacing):
+ *   history:   bvid  (fallback "history-<index>")
+ *   favourite: "fav-" + bvid  (fallback "fav-<index>")
+ *   dynamic:   "dyn-" + rid   (fallback "dyn-<index>")
+ *   follow:    "follow-" + mid (fallback "follow-<index>")
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+const SNAPSHOT_SCHEMA_VERSION = 1;
+
+/**
+ * Build the in-memory snapshot object. Pure function — no disk I/O.
+ *
+ * @param {{
+ *   uid: number,
+ *   displayName?: string,
+ *   history?: Array,
+ *   favourites?: Array,
+ *   dynamics?: Array,
+ *   follows?: Array,
+ *   snapshottedAt?: number,
+ * }} input
+ * @returns {{schemaVersion: number, snapshottedAt: number, account: object, events: Array}}
+ */
+function buildSnapshot(input) {
+  if (!input || typeof input !== "object") {
+    throw new TypeError("buildSnapshot: input must be an object");
+  }
+  const uid = input.uid;
+  if (!Number.isFinite(uid) || uid <= 0) {
+    throw new TypeError(
+      "buildSnapshot: input.uid must be a positive integer (was " + uid + ")",
+    );
+  }
+  const snapshottedAt =
+    Number.isFinite(input.snapshottedAt) && input.snapshottedAt > 0
+      ? input.snapshottedAt
+      : Date.now();
+  const account = {
+    uid: String(uid),
+    displayName:
+      typeof input.displayName === "string" ? input.displayName : "",
+  };
+  const events = [];
+
+  // history
+  const history = Array.isArray(input.history) ? input.history : [];
+  history.forEach((h, idx) => {
+    if (!h || typeof h !== "object") return;
+    events.push({
+      kind: "history",
+      id: h.bvid || `history-${idx}`,
+      capturedAt: typeof h.viewAt === "number" ? h.viewAt : snapshottedAt,
+      title: h.title || null,
+      bvid: h.bvid || null,
+      avid: typeof h.avid === "number" ? h.avid : null,
+      duration: typeof h.duration === "number" ? h.duration : null,
+      uploader: h.uploader || null,
+      uploaderMid: typeof h.uploaderMid === "number" ? h.uploaderMid : null,
+      part: h.part || null,
+    });
+  });
+
+  // favourites
+  const favs = Array.isArray(input.favourites) ? input.favourites : [];
+  favs.forEach((f, idx) => {
+    if (!f || typeof f !== "object") return;
+    events.push({
+      kind: "favourite",
+      id: f.bvid ? `fav-${f.bvid}` : `fav-${idx}`,
+      capturedAt: typeof f.savedAt === "number" ? f.savedAt : snapshottedAt,
+      title: f.title || null,
+      bvid: f.bvid || null,
+      folderName: f.folderName || null,
+      uploader: f.uploader || null,
+    });
+  });
+
+  // dynamics
+  const dyns = Array.isArray(input.dynamics) ? input.dynamics : [];
+  dyns.forEach((d, idx) => {
+    if (!d || typeof d !== "object") return;
+    events.push({
+      kind: "dynamic",
+      id: d.rid ? `dyn-${d.rid}` : `dyn-${idx}`,
+      capturedAt:
+        typeof d.publishedAt === "number" ? d.publishedAt : snapshottedAt,
+      summary: d.summary || null,
+      dynamicType: d.dynamicType || "unknown",
+      authorMid: typeof d.authorMid === "number" ? d.authorMid : null,
+      authorName: d.authorName || null,
+    });
+  });
+
+  // follows
+  const fols = Array.isArray(input.follows) ? input.follows : [];
+  fols.forEach((f, idx) => {
+    if (!f || typeof f !== "object") return;
+    const mid = typeof f.mid === "number" ? f.mid : null;
+    events.push({
+      kind: "follow",
+      id: mid ? `follow-${mid}` : `follow-${idx}`,
+      capturedAt:
+        typeof f.followedAt === "number" ? f.followedAt : snapshottedAt,
+      mid: mid != null ? String(mid) : null,
+      uname: f.uname || null,
+      face: f.face || null,
+      sign: f.sign || null,
+    });
+  });
+
+  return {
+    schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+    snapshottedAt,
+    account,
+    events,
+  };
+}
+
+/**
+ * Write a snapshot object to disk as JSON. Default destination is
+ * `<os.tmpdir()>/cc-bilibili-snapshot-<uuid>.json`. Returns the absolute
+ * path written. Caller is responsible for cleanup (BilibiliAdbCollector
+ * does this in a try/finally).
+ *
+ * @param {object} snapshot  output of buildSnapshot
+ * @param {{dir?: string, fileName?: string}} [opts]
+ * @returns {string}  absolute path
+ */
+function writeSnapshotJson(snapshot, opts = {}) {
+  const dir = opts.dir || os.tmpdir();
+  const fileName =
+    opts.fileName || `cc-bilibili-snapshot-${crypto.randomUUID()}.json`;
+  if (fileName.includes("/") || fileName.includes("\\")) {
+    throw new Error(
+      "writeSnapshotJson: opts.fileName must be a basename, not a path",
+    );
+  }
+  const full = path.join(dir, fileName);
+  fs.writeFileSync(full, JSON.stringify(snapshot), "utf-8");
+  return full;
+}
+
+/**
+ * Best-effort delete of a snapshot file. Used in finally blocks; never
+ * throws.
+ */
+function cleanupSnapshotJson(filePath) {
+  if (!filePath) return;
+  try {
+    fs.unlinkSync(filePath);
+  } catch (_e) {
+    // ignore — temp file cleanup is best-effort
+  }
+}
+
+module.exports = {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+};

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

@@ -62,6 +62,8 @@ const KIND_HISTORY = "history";   // v0.3 (X-Bogus required)
 const KIND_FAVOURITE = "favourite"; // v0.3 (X-Bogus required)
 const KIND_LIKE = "like";         // v0.3 (X-Bogus required)
 const KIND_SEARCH = "search";     // legacy sqlite-mode only
+const KIND_MESSAGE = "message";   // Phase 2a — IM private messages from <uid>_im.db (abrignoni DFIR)
+const KIND_CONTACT = "contact";   // Phase 2a — SIMPLE_USER table contacts/follows from <uid>_im.db
 
 // Forward-compat: list every kind v0.3+ may emit so cc adapter accepts
 // snapshots from a newer Android even if this JS hasn't been bumped yet.
@@ -70,6 +72,8 @@ const VALID_SNAPSHOT_KINDS = Object.freeze([
   KIND_HISTORY,
   KIND_FAVOURITE,
   KIND_LIKE,
+  KIND_MESSAGE,
+  KIND_CONTACT,
 ]);
 
 function stableOriginalId(kind, id) {

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

@@ -0,0 +1,165 @@
+"use strict";
+
+/**
+ * Phase 2a (Douyin C 路径 — 2026-05-25): end-to-end orchestrator.
+ *
+ *   bridge.invoke("douyin.pull-im-db")  ← Phase 2a db-extension
+ *           │
+ *           ▼  {tempPath, uid, walPath?, shmPath?, cleanup}
+ *   parseImDb(tempPath)                  ← Phase 2a im-db-parser
+ *           │
+ *           ▼  {messages, contacts, diagnostic}
+ *   buildSnapshot + writeSnapshotJson    ← Phase 2a snapshot-builder
+ *           │
+ *           ▼  staging JSON path
+ *   registry.syncAdapter("social-douyin", { inputPath })  ← existing
+ *                                                            snapshot mode
+ *
+ * Pattern mirrors social-bilibili-adb/collector.js — same try/finally
+ * cleanup, same `{ok, report?, reason?, message?}` return shape.
+ */
+
+const { parseImDb } = require("./im-db-parser");
+const {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+} = require("./snapshot-builder");
+
+/**
+ * Pull IM db → parse → write snapshot. Returns the staging path + counts
+ * + diagnostic. Caller decides what to do with the snapshot (typically
+ * passes to registry.syncAdapter then cleanup).
+ *
+ * @param {object} bridge  host-adb-bridge instance — must have
+ *   "douyin.pull-im-db" extension registered
+ * @param {{
+ *   uid?: string,                 // 19-digit uid to disambiguate multi-account
+ *   limits?: {messages?: number, contacts?: number},
+ *   stagingDir?: string,
+ *   displayName?: string,
+ *   now?: () => number,
+ * }} [opts]
+ */
+async function collect(bridge, opts = {}) {
+  if (!bridge || typeof bridge.invoke !== "function") {
+    throw new TypeError(
+      "DouyinAdbCollector.collect: bridge must expose invoke(method, params)",
+    );
+  }
+  const now = opts.now || Date.now;
+
+  // 1. Pull the IM db cohort.
+  const pullResult = await bridge.invoke("douyin.pull-im-db", {
+    uid: opts.uid,
+  });
+  if (
+    !pullResult ||
+    typeof pullResult.tempPath !== "string" ||
+    typeof pullResult.uid !== "string"
+  ) {
+    throw new Error(
+      "DouyinAdbCollector.collect: bridge.invoke('douyin.pull-im-db') returned malformed payload",
+    );
+  }
+  const { tempPath, uid, cleanup: cleanupDbCohort } = pullResult;
+
+  try {
+    // 2. Parse the IM db locally.
+    const parsed = parseImDb(tempPath, {
+      limitMessages: opts.limits && opts.limits.messages,
+      limitContacts: opts.limits && opts.limits.contacts,
+    });
+
+    // 3. Build snapshot + write to staging.
+    const snapshot = buildSnapshot({
+      uid,
+      displayName: opts.displayName,
+      messages: parsed.messages,
+      contacts: parsed.contacts,
+      snapshottedAt: now(),
+    });
+    const snapshotPath = writeSnapshotJson(snapshot, {
+      dir: opts.stagingDir,
+    });
+
+    return {
+      snapshotPath,
+      uid,
+      eventCounts: {
+        message: parsed.messages.length,
+        contact: parsed.contacts.length,
+        total: parsed.messages.length + parsed.contacts.length,
+      },
+      parserDiagnostic: parsed.diagnostic,
+      // Cleanup the pulled db cohort right after parsing — we have the
+      // events in memory, no reason to keep the .db lying around.
+      _dbCohortCleanup: cleanupDbCohort,
+    };
+  } catch (err) {
+    // On any parse / build / write failure, cleanup the pulled db cohort
+    // before re-throwing so we don't leak the temp file.
+    if (typeof cleanupDbCohort === "function") {
+      try {
+        cleanupDbCohort();
+      } catch (_e) {
+        // best-effort
+      }
+    }
+    throw err;
+  }
+}
+
+/**
+ * One-shot convenience: collect + syncAdapter("social-douyin") + cleanup
+ * everything (both the db cohort AND the snapshot JSON, even if
+ * syncAdapter throws).
+ *
+ * @param {object} bridge      host-adb-bridge
+ * @param {object} registry    AdapterRegistry
+ * @param {object} [opts]      forwarded to `collect()`
+ * @returns {Promise<object>}  SyncReport + collector diagnostic
+ */
+async function collectAndSync(bridge, registry, opts = {}) {
+  if (!registry || typeof registry.syncAdapter !== "function") {
+    throw new TypeError(
+      "DouyinAdbCollector.collectAndSync: registry must expose syncAdapter(name, options)",
+    );
+  }
+  const collectResult = await collect(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;
+    }
+    // Always cleanup the pulled db cohort.
+    if (typeof collectResult._dbCohortCleanup === "function") {
+      try {
+        collectResult._dbCohortCleanup();
+      } catch (_e) {
+        cleanupFailed = true;
+      }
+    }
+  }
+  return {
+    ...syncReport,
+    douyin: {
+      uid: collectResult.uid,
+      eventCounts: collectResult.eventCounts,
+      parserDiagnostic: collectResult.parserDiagnostic,
+      cleanupFailed,
+    },
+  };
+}
+
+module.exports = {
+  collect,
+  collectAndSync,
+};