@chainlesschain/personal-data-hub 0.3.1 → 0.3.7

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

@@ -0,0 +1,209 @@
+"use strict";
+
+/**
+ * Phase 3c (Xhs C 路径 — 2026-05-25): end-to-end orchestrator.
+ *
+ *   bridge.invoke("xhs.cookies")            ← Phase 3c cookies extension
+ *           │
+ *           ▼  {cookie, a1, diagnostic}
+ *   XhsApiClient.fetchMe                     ← /user/me 拿 user_id (无 X-S)
+ *           │
+ *           ▼  {userId, nickname}
+ *   fetchNotes + fetchLiked + fetchFollows   (parallel, X-S 需 a1)
+ *           │
+ *           ▼  3 arrays (partial-failure OK; ~60% GET hit rate)
+ *   buildSnapshot + writeSnapshotJson        ← schemaVersion=1
+ *           │
+ *           ▼
+ *   registry.syncAdapter("social-xiaohongshu", { inputPath })
+ *
+ * Mirror of social-weibo-adb/collector.js. Key diff: 3 endpoints need
+ * X-S signing (best-effort md5 approximation hits ~60% GET, <30% POST;
+ * collector tolerates partial failures via lastErrorCode propagation).
+ */
+
+const { XhsApiClient } = require("./api-client");
+const {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+} = require("./snapshot-builder");
+
+async function collect(bridge, opts = {}) {
+  if (!bridge || typeof bridge.invoke !== "function") {
+    throw new TypeError(
+      "XhsAdbCollector.collect: bridge must expose invoke(method, params)",
+    );
+  }
+  const now = opts.now || Date.now;
+  // Phase 6b: signProvider opt — desktop wiring injects XhsSignBridge for
+  // ~100% X-S hit rate; cli wiring leaves undefined → client falls back
+  // to in-process best-effort md5 (~60% GET / <30% POST).
+  const signProvider = opts.signProvider || undefined;
+  const client =
+    opts.apiClient || new XhsApiClient({ now, signProvider });
+  const limits = opts.limits || {};
+
+  const cookieResult = await bridge.invoke("xhs.cookies");
+  if (
+    !cookieResult ||
+    typeof cookieResult.cookie !== "string" ||
+    typeof cookieResult.a1 !== "string"
+  ) {
+    throw new Error(
+      "XhsAdbCollector.collect: bridge.invoke('xhs.cookies') returned malformed payload — got cookie=" +
+        typeof cookieResult?.cookie +
+        " a1=" +
+        typeof cookieResult?.a1,
+    );
+  }
+  const { cookie, a1, diagnostic: cookieDiagnostic } = cookieResult;
+
+  // Phase 6b: warm up the sign bridge with the captured cookie BEFORE
+  // calling any X-S endpoint. warmUp is idempotent (no-op when already
+  // warm). NullSignProvider.warmUp doesn't exist (only on the abstract
+  // base + ElectronWebSignBridge), so we feature-detect.
+  if (signProvider && typeof signProvider.warmUp === "function") {
+    try {
+      await signProvider.warmUp(cookie);
+    } catch (e) {
+      // Bridge warm-up failed (timeout / xhs.com 403 / IPC error).
+      // Fall through — api-client will use in-process fallback. Surface
+      // the reason via lastErrorMessage so UI can hint "Electron bridge
+      // unavailable, command-line precision degraded".
+      client._setLastError(
+        -98,
+        `signProvider warm-up failed: ${e && e.message ? e.message : String(e)}`,
+      );
+    }
+  }
+
+  try {
+    // fetchMe — no X-S required
+    const me = await client.fetchMe(cookie);
+    if (!me) {
+      // Cookie expired or web_session missing — write empty snapshot
+      // (build requires userId, use sentinel "0" + emit 0 events).
+      const snapshot = buildSnapshot({
+        userId: "unknown-user",
+        nickname: opts.displayName,
+        snapshottedAt: now(),
+      });
+      const snapshotPath = writeSnapshotJson(snapshot, { dir: opts.stagingDir });
+      return {
+        snapshotPath,
+        userId: null,
+        nickname: null,
+        eventCounts: { note: 0, liked: 0, follow: 0, total: 0 },
+        lastErrorCode: client.lastErrorCode,
+        lastErrorMessage: client.lastErrorMessage,
+        cookieDiagnostic: cookieDiagnostic || null,
+        meFetchFailed: true,
+        signProviderUsed: signProvider
+          ? signProvider.constructor.name
+          : "none",
+        signProviderHits: client._bridgeHits,
+        signProviderFallbacks: client._fallbackHits,
+      };
+    }
+
+    // Parallel 3 endpoints — partial failure tolerated; bridge-signed
+    // requests should hit ~100% while fallback hits ~60% GET / <30% POST.
+    const [notes, liked, follows] = await Promise.all([
+      client.fetchNotes(cookie, a1, me.userId, {
+        limit: Number.isInteger(limits.note) ? limits.note : undefined,
+      }),
+      client.fetchLiked(cookie, a1, {
+        limit: Number.isInteger(limits.liked) ? limits.liked : undefined,
+      }),
+      client.fetchFollows(cookie, a1, me.userId, {
+        limit: Number.isInteger(limits.follow) ? limits.follow : undefined,
+      }),
+    ]);
+
+    const snapshot = buildSnapshot({
+      userId: me.userId,
+      nickname: opts.displayName || me.nickname,
+      notes,
+      liked,
+      follows,
+      snapshottedAt: now(),
+    });
+    const snapshotPath = writeSnapshotJson(snapshot, { dir: opts.stagingDir });
+
+    return {
+      snapshotPath,
+      userId: me.userId,
+      nickname: me.nickname,
+      eventCounts: {
+        note: notes.length,
+        liked: liked.length,
+        follow: follows.length,
+        total: snapshot.events.length,
+      },
+      lastErrorCode: client.lastErrorCode,
+      lastErrorMessage: client.lastErrorMessage,
+      cookieDiagnostic: cookieDiagnostic || null,
+      meFetchFailed: false,
+      signProviderUsed: signProvider ? signProvider.constructor.name : "none",
+      signProviderHits: client._bridgeHits,
+      signProviderFallbacks: client._fallbackHits,
+    };
+  } finally {
+    // Always release the WebContentsView heap (~30-50MB) — even on
+    // throw. shutdown is idempotent so collectAndSync's outer cleanup
+    // calling it again is safe.
+    if (signProvider && typeof signProvider.shutdown === "function") {
+      try {
+        await signProvider.shutdown();
+      } catch (_e) {
+        // Best-effort — shutdown errors don't block sync result.
+      }
+    }
+  }
+}
+
+async function collectAndSync(bridge, registry, opts = {}) {
+  if (!registry || typeof registry.syncAdapter !== "function") {
+    throw new TypeError(
+      "XhsAdbCollector.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-xiaohongshu", {
+      inputPath: collectResult.snapshotPath,
+    });
+  } finally {
+    try {
+      cleanupSnapshotJson(collectResult.snapshotPath);
+    } catch (_e) {
+      cleanupFailed = true;
+    }
+  }
+  return {
+    ...syncReport,
+    xhs: {
+      userId: collectResult.userId,
+      nickname: collectResult.nickname,
+      eventCounts: collectResult.eventCounts,
+      lastErrorCode: collectResult.lastErrorCode,
+      lastErrorMessage: collectResult.lastErrorMessage,
+      cookieDiagnostic: collectResult.cookieDiagnostic,
+      meFetchFailed: collectResult.meFetchFailed,
+      // Phase 6b diagnostic — UI can highlight when bridge upgraded
+      // X-S signing from ~60% best-effort to ~100% bridge.
+      signProviderUsed: collectResult.signProviderUsed,
+      signProviderHits: collectResult.signProviderHits,
+      signProviderFallbacks: collectResult.signProviderFallbacks,
+      cleanupFailed,
+    },
+  };
+}
+
+module.exports = {
+  collect,
+  collectAndSync,
+};

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

@@ -0,0 +1,211 @@
+"use strict";
+
+/**
+ * Phase 3c (Xhs C 路径 — 2026-05-25): xhs.cookies ADB extension factory.
+ *
+ * Mirror of `social-weibo-adb/cookies-extension.js` (P3a) but for
+ * com.xingin.xhs (Xiaohongshu) — same chromium-cookies-reader reuse,
+ * different package + cookie name requirements.
+ *
+ * Required cookies (without these, X-S signing or auth fails):
+ *  - `a1`           — anti-bot fingerprint, REQUIRED for X-S sig input
+ *  - `web_session`  — login session token
+ *
+ * Either of the two missing → WEIBO_COOKIES_INCOMPLETE-style error code
+ * (XHS_COOKIES_INCOMPLETE) so UI surfaces a "relog on phone" banner.
+ *
+ * Returns:
+ *   {
+ *     cookie: string,             // full Cookie header value
+ *     a1: string,                 // pre-extracted a1 (saves caller parsing)
+ *     extractedAt: number,
+ *     diagnostic: {
+ *       cookieCount: number,
+ *       hadEncrypted: boolean,
+ *       cookieNames: string[],
+ *     }
+ *   }
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+const {
+  readChromiumCookies,
+} = require("../social-bilibili-adb/chromium-cookies-reader");
+
+const XHS_COOKIES_REMOTE_PATH =
+  "/data/data/com.xingin.xhs/app_webview/Default/Cookies";
+
+const XHS_COOKIE_HOST_DOMAIN = "xiaohongshu.com";
+
+const XHS_REQUIRED_COOKIES = Object.freeze(["a1", "web_session"]);
+
+async function pullCookiesViaSu(adb, serial, opts) {
+  const adbOpts = { serial, timeoutMs: opts?.timeoutMs || 60_000 };
+  const lsOut = await adb(
+    [
+      "shell",
+      "su",
+      "-c",
+      `ls ${XHS_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(
+      "XHS_NOT_INSTALLED: " +
+        XHS_COOKIES_REMOTE_PATH +
+        " not found. Install Xiaohongshu App + log in once on the phone, then retry.",
+    );
+  }
+  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(
+      "XHS_NO_ROOT: this phone isn't rooted (su returned `" +
+        idLine.substring(0, 60) +
+        "`). Xiaohongshu release APK isn't debuggable, so root is required.",
+    );
+  }
+  const b64 = await adb(
+    [
+      "shell",
+      "su",
+      "-c",
+      `base64 ${XHS_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(
+      "XHS_COOKIES_EMPTY: base64 stream returned 0 bytes (su exec may have silently failed on MIUI / OEM ROM)",
+    );
+  }
+  let buf;
+  try {
+    buf = Buffer.from(b64Clean, "base64");
+  } catch (e) {
+    throw new Error(
+      "XHS_BASE64_PARSE: stream wasn't valid base64 (" +
+        (e.message || String(e)) +
+        ")",
+    );
+  }
+  if (buf.length < 1024) {
+    throw new Error(
+      "XHS_COOKIES_TRUNCATED: decoded file is only " +
+        buf.length +
+        " bytes — expected ≥4KB sqlite",
+    );
+  }
+  const magic = buf.subarray(0, 16).toString("latin1");
+  if (!magic.startsWith("SQLite format 3")) {
+    throw new Error(
+      "XHS_NOT_SQLITE: decoded file lacks `SQLite format 3` magic header",
+    );
+  }
+  const tmpDir = os.tmpdir();
+  const tmpFile = path.join(tmpDir, `cc-xhs-cookies-${crypto.randomUUID()}.db`);
+  fs.writeFileSync(tmpFile, buf);
+  return tmpFile;
+}
+
+/**
+ * Build a Cookie header + extract a1 from a chromium-cookies array.
+ *
+ * Xhs requires BOTH a1 and web_session — without either, X-S signing
+ * fails (a1) or auth fails (web_session).
+ */
+function assembleXhsCookieHeader(cookies) {
+  if (!Array.isArray(cookies)) {
+    throw new TypeError("assembleXhsCookieHeader: cookies must be an array");
+  }
+  const byName = new Map();
+  for (const c of cookies) {
+    if (
+      !byName.has(c.name) ||
+      c.hostKey.length > (byName.get(c.name).hostKey || "").length
+    ) {
+      byName.set(c.name, c);
+    }
+  }
+  const missing = XHS_REQUIRED_COOKIES.filter((n) => !byName.has(n));
+  const present = new Set(byName.keys());
+  if (missing.length > 0) {
+    return { header: null, a1: null, present, missing };
+  }
+  const header = Array.from(byName.values())
+    .map((c) => `${c.name}=${c.value}`)
+    .join("; ");
+  const a1 = byName.get("a1")?.value || null;
+  return { header, a1, present, missing: [] };
+}
+
+function createXhsCookiesExtension(factoryOpts = {}) {
+  const timeoutMs = factoryOpts.timeoutMs || 60_000;
+  const onCleanupFailed = factoryOpts.onCleanupFailed || (() => {});
+
+  return async function xhsCookiesHandler(_params, ctx) {
+    if (
+      !ctx ||
+      typeof ctx.adb !== "function" ||
+      typeof ctx.pickDevice !== "function"
+    ) {
+      throw new TypeError(
+        "xhs.cookies extension: ctx must provide {adb, pickDevice}",
+      );
+    }
+    const serial = await ctx.pickDevice();
+    let tmpFile = null;
+    try {
+      tmpFile = await pullCookiesViaSu(ctx.adb, serial, { timeoutMs });
+      const cookies = readChromiumCookies(tmpFile, XHS_COOKIE_HOST_DOMAIN);
+      const cookieCount = cookies.length;
+      const hadEncrypted = (cookies._skippedEncryptedCount || 0) > 0;
+      const { header, a1, missing, present } = assembleXhsCookieHeader(cookies);
+      if (header === null) {
+        throw new Error(
+          "XHS_COOKIES_INCOMPLETE: missing required cookies " +
+            JSON.stringify(missing) +
+            ". User probably logged out (relog on phone) or Xhs version uses non-default WebView storage path (hadEncrypted=" +
+            hadEncrypted +
+            ").",
+        );
+      }
+      return {
+        cookie: header,
+        a1,
+        extractedAt: Date.now(),
+        diagnostic: {
+          cookieCount,
+          hadEncrypted,
+          cookieNames: Array.from(present),
+        },
+      };
+    } finally {
+      if (tmpFile) {
+        try {
+          fs.unlinkSync(tmpFile);
+        } catch (_e) {
+          onCleanupFailed(tmpFile);
+        }
+      }
+    }
+  };
+}
+
+module.exports = {
+  createXhsCookiesExtension,
+  XHS_COOKIES_REMOTE_PATH,
+  XHS_COOKIE_HOST_DOMAIN,
+  XHS_REQUIRED_COOKIES,
+  assembleXhsCookieHeader,
+  _internals: {
+    pullCookiesViaSu,
+  },
+};

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

@@ -0,0 +1,50 @@
+"use strict";
+
+/**
+ * social-xiaohongshu-adb — Phase 3c (Xhs C 路径) entry.
+ *
+ * Phase 3c — desktop ADB Chromium cookies + edith.xiaohongshu.com HTTP
+ * with best-effort X-S signing (md5 approximation, ~60% GET hit rate).
+ *
+ * Pipeline:
+ *   bridge.invoke("xhs.cookies") → {cookie, a1}
+ *     → XhsApiClient.fetchMe (no X-S, cookies-only)
+ *     → fetchNotes + fetchLiked + fetchFollows (X-S signed, parallel)
+ *     → buildSnapshot + writeSnapshotJson
+ *     → registry.syncAdapter("social-xiaohongshu", { inputPath })
+ */
+
+const {
+  createXhsCookiesExtension,
+  XHS_COOKIES_REMOTE_PATH,
+  XHS_COOKIE_HOST_DOMAIN,
+  XHS_REQUIRED_COOKIES,
+  assembleXhsCookieHeader,
+} = require("./cookies-extension");
+const { computeXsXt, extractA1, XS_PREFIX } = require("./sign");
+const { XhsApiClient } = require("./api-client");
+const {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+} = require("./snapshot-builder");
+const { collect, collectAndSync } = require("./collector");
+
+module.exports = {
+  createXhsCookiesExtension,
+  XHS_COOKIES_REMOTE_PATH,
+  XHS_COOKIE_HOST_DOMAIN,
+  XHS_REQUIRED_COOKIES,
+  assembleXhsCookieHeader,
+  computeXsXt,
+  extractA1,
+  XS_PREFIX,
+  XhsApiClient,
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+  collect,
+  collectAndSync,
+};

package/lib/adapters/social-xiaohongshu-adb/sign.js

@@ -0,0 +1,90 @@
+"use strict";
+
+/**
+ * Phase 3c (Xhs C 路径 — 2026-05-25): X-S signature generator (Node port).
+ *
+ * Byte-parity port of
+ * `android-app/.../pdh/social/xiaohongshu/XhsApiClient.kt`:computeXsXt.
+ *
+ * **Real xhs.js algorithm (open-source reverse-engineered, best-effort)**:
+ *   1. payload = "url=" + url_path_with_query + ("" or body_json)
+ *   2. raw = ts_ms + payload + a1_cookie
+ *   3. md5_hex = MD5(raw).hex()                — hex STRING (not bytes)
+ *   4. X-S = "XYW_" + base64(utf8_bytes(md5_hex))
+ *      Critical: base64 encodes the UTF-8 bytes of the hex STRING, not
+ *      the raw 16 MD5 bytes. This is what xhs.js does — it stringifies
+ *      the digest before base64-ing it.
+ *   5. X-T = ts_ms (as decimal string)
+ *
+ * **Real xhs.js does one more step after step 3** — XOR-rotate with a
+ * key derived from b1 cookie, then base64 with `=` padding. v0.2 we
+ * skip that step → ~60% GET hit rate, <30% POST hit rate. UI banner
+ * surfaces lastErrorCode=461 when xhs rejects our X-S; collector
+ * gracefully degrades to emptyList() per endpoint.
+ *
+ * Future Phase 3c-v0.3: a WebView-based bridge (see Android-side
+ * XhsSignBridge.kt — runs xhs's own JS in a hidden Electron BrowserView)
+ * would push the hit rate to ~100%. Out of scope for v0.2 Node port.
+ */
+
+const crypto = require("node:crypto");
+
+/** "XYW_" prefix — matches xhs.js output. */
+const XS_PREFIX = "XYW_";
+
+/**
+ * Compute X-S + X-T headers for a GET request.
+ *
+ * @param {string} urlPathWithQuery   url.pathname + url.search (path + "?" + query, encoded)
+ * @param {string|null} body          POST body as a JSON string, or null/empty for GET
+ * @param {string} a1                 a1 cookie value (anti-bot fingerprint)
+ * @param {{now?: () => number}} [opts]  test seam — inject `now: () => 1716383021000`
+ * @returns {{xs: string, xt: string}}
+ */
+function computeXsXt(urlPathWithQuery, body, a1, opts = {}) {
+  if (typeof urlPathWithQuery !== "string" || urlPathWithQuery.length === 0) {
+    throw new TypeError("computeXsXt: urlPathWithQuery must be non-empty string");
+  }
+  if (typeof a1 !== "string" || a1.length === 0) {
+    throw new TypeError("computeXsXt: a1 must be non-empty string");
+  }
+  const ts = (opts.now || Date.now)();
+  const bodyStr = typeof body === "string" ? body : "";
+  const payload = "url=" + urlPathWithQuery + bodyStr;
+  const raw = `${ts}${payload}${a1}`;
+  const md5Hex = crypto.createHash("md5").update(raw, "utf8").digest("hex");
+  // base64 encode the UTF-8 bytes of the hex STRING (32 chars → 32 bytes
+  // → 44-char base64 with padding). xhs.js NO_WRAP NO_PADDING flags
+  // mirror: replace = padding with "", remove newlines (default in
+  // Buffer.toString("base64") already no-newlines, only padding to strip).
+  const b64NoPad = Buffer.from(md5Hex, "utf8").toString("base64").replace(/=+$/, "");
+  return {
+    xs: XS_PREFIX + b64NoPad,
+    xt: String(ts),
+  };
+}
+
+/**
+ * Extract a1 cookie value from a Cookie header string.
+ *
+ *   "web_session=abc; a1=18d6e123abc; xsec_token=xxx" → "18d6e123abc"
+ *
+ * Returns null when a1 not present.
+ */
+function extractA1(cookie) {
+  if (typeof cookie !== "string") return null;
+  for (const part of cookie.split(";")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith("a1=")) {
+      const v = trimmed.substring(3);
+      return v.length > 0 ? v : null;
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  computeXsXt,
+  extractA1,
+  XS_PREFIX,
+};

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

@@ -0,0 +1,126 @@
+"use strict";
+
+/**
+ * Phase 3c (Xhs C 路径 — 2026-05-25): API responses → snapshot JSON.
+ *
+ * Matches the existing `social-xiaohongshu` adapter's snapshot mode
+ * schema (schemaVersion=1). Kinds: note / liked / follow.
+ *
+ * Note: xhs userId is a Base64-ish string (e.g. "5e8c8f7e..."), not a
+ * numeric Long. The account.uid in the snapshot is set to userId
+ * verbatim (string passthrough); consumers shouldn't expect numeric uid.
+ */
+
+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;
+
+function buildSnapshot(input) {
+  if (!input || typeof input !== "object") {
+    throw new TypeError("buildSnapshot: input must be an object");
+  }
+  const userId = input.userId;
+  if (typeof userId !== "string" || userId.length === 0) {
+    throw new TypeError("buildSnapshot: input.userId must be a non-empty string");
+  }
+  const snapshottedAt =
+    Number.isFinite(input.snapshottedAt) && input.snapshottedAt > 0
+      ? input.snapshottedAt
+      : Date.now();
+  const account = {
+    userId, // xhs userId is a string, not numeric
+    nickname: typeof input.nickname === "string" ? input.nickname : "",
+  };
+  const events = [];
+
+  // notes
+  const notes = Array.isArray(input.notes) ? input.notes : [];
+  notes.forEach((n, idx) => {
+    if (!n || typeof n !== "object") return;
+    events.push({
+      kind: "note",
+      id: n.noteId ? `note-${n.noteId}` : `note-${idx}`,
+      capturedAt:
+        typeof n.createdAt === "number" && n.createdAt > 0
+          ? n.createdAt
+          : snapshottedAt,
+      noteId: n.noteId || null,
+      title: n.title || null,
+      desc: n.desc || null,
+      type: n.type || "normal",
+      likedCount: typeof n.likedCount === "number" ? n.likedCount : 0,
+      collectedCount:
+        typeof n.collectedCount === "number" ? n.collectedCount : 0,
+      commentCount: typeof n.commentCount === "number" ? n.commentCount : 0,
+    });
+  });
+
+  // liked
+  const liked = Array.isArray(input.liked) ? input.liked : [];
+  liked.forEach((l, idx) => {
+    if (!l || typeof l !== "object") return;
+    events.push({
+      kind: "liked",
+      id: l.noteId ? `liked-${l.noteId}` : `liked-${idx}`,
+      // xhs doesn't return liked_at — use snapshottedAt
+      capturedAt: snapshottedAt,
+      noteId: l.noteId || null,
+      title: l.title || null,
+      authorNickname: l.authorNickname || null,
+    });
+  });
+
+  // follows
+  const follows = Array.isArray(input.follows) ? input.follows : [];
+  follows.forEach((f, idx) => {
+    if (!f || typeof f !== "object") return;
+    events.push({
+      kind: "follow",
+      id: f.userId ? `follow-${f.userId}` : `follow-${idx}`,
+      capturedAt: snapshottedAt,
+      userId: f.userId || null,
+      nickname: f.nickname || null,
+      image: f.image || null,
+    });
+  });
+
+  return {
+    schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+    snapshottedAt,
+    account,
+    events,
+  };
+}
+
+function writeSnapshotJson(snapshot, opts = {}) {
+  const dir = opts.dir || os.tmpdir();
+  const fileName =
+    opts.fileName || `cc-xhs-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;
+}
+
+function cleanupSnapshotJson(filePath) {
+  if (!filePath) return;
+  try {
+    fs.unlinkSync(filePath);
+  } catch (_e) {
+    // ignore
+  }
+}
+
+module.exports = {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+};