@chainlesschain/personal-data-hub 0.2.2 → 0.2.4

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

@@ -1,44 +1,106 @@
 /**
- * Phase 13.9(+) — Kuaishou 快手 adapter (v0.1 scaffold).
+ * §A8 v0.2 — Kuaishou (快手) adapter, dual-mode (snapshot + sqlite).
  *
- * Source: 快手 Android app stores user history in SQLite under
- * /data/data/com.smile.gifmaker/databases/. Schema is reverse-engineered
- * from sjqz parsers and pinned at scaffold quality only — Phase 13.10 will
- * fixture-pin real field names after Xiaomi 24115RA8EC E2E.
+ * Mirror of social-toutiao v0.2 two-mode pattern:
  *
- * Conjectured tables (待 fixture pin):
- *   - photo_history       watched short-videos (kuaishou calls them "photos")
- *   - user_collect        collected (saved) videos
- *   - search_record       user search queries
+ *   1. snapshot mode (opts.inputPath): in-APK Android cc reads a snapshot
+ *      JSON produced by the phone's KuaishouLocalCollector (root-required
+ *      SQLCipher decrypt of /data/data/com.smile.gifmaker/databases/ on
+ *      Phase 13.10 real-device E2E). Desktop-independent; account.uid
+ *      OPTIONAL at construction — payload carries it.
  *
- * Each row → Event with subtype "browse" (photo_history) /
- * "like" (user_collect) / "post" (search_record reframed as a self-authored
- * search event).
+ *   2. sqlite mode (opts.dbPath, legacy): Phase 13.9 device-pull path —
+ *      desktop reads the pulled DB directly. account.uid REQUIRED in this
+ *      mode (lazy-checked at sync time).
  *
- * Mirrors social-bilibili adapter contract; sensitivity stays "medium"
- * (short-video watch history mainly reveals entertainment preference).
+ * Snapshot schema (mirrors KuaishouLocalCollector.SNAPSHOT_SCHEMA_VERSION):
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "snapshottedAt": <epoch-ms>,
+ *     "account": { "uid": "12345", "displayName": "alice" },
+ *     "events": [
+ *       { "kind": "watch",   "id": "photo-<photoId>",   "capturedAt": <ms>,
+ *         "photoId": "...", "caption": "...", "duration": N,
+ *         "authorId": "...", "authorName": "..." },
+ *       { "kind": "collect", "id": "collect-<photoId>", "capturedAt": <ms>,
+ *         "photoId": "...", "caption": "...",
+ *         "authorId": "...", "authorName": "..." },
+ *       { "kind": "search",  "id": "search-<kw>:<ts>",  "capturedAt": <ms>,
+ *         "keyword": "...", "searchAt": <ms> }
+ *     ]
+ *   }
+ *
+ * Sensitivity: "medium" — short-video watch history mainly reveals
+ * entertainment preference (vs Toutiao's news-reading which goes "high").
  */
 
 "use strict";
 
 const fs = require("node:fs");
 const { newId } = require("../../ids");
+const {
+  ENTITY_TYPES,
+  EVENT_SUBTYPES,
+  CAPTURED_BY,
+} = require("../../constants");
 
 const NAME = "social-kuaishou";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
+const SNAPSHOT_SCHEMA_VERSION = 1;
+
+const KIND_WATCH = "watch";
+const KIND_COLLECT = "collect";
+const KIND_SEARCH = "search";
+const VALID_SNAPSHOT_KINDS = Object.freeze([
+  KIND_WATCH,
+  KIND_COLLECT,
+  KIND_SEARCH,
+]);
+
+function stableOriginalId(kind, id) {
+  const stringified =
+    (typeof id === "string" && id.length > 0 && id) ||
+    (typeof id === "number" && Number.isFinite(id) && String(id)) ||
+    null;
+  const safe =
+    stringified ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `kuaishou:${kind}:${safe}`;
+}
+
+function parseTime(v) {
+  if (Number.isFinite(v)) return v > 1e12 ? v : v * 1000;
+  if (typeof v === "string") {
+    if (/^\d+$/.test(v)) {
+      const n = parseInt(v, 10);
+      return n > 1e12 ? n : n * 1000;
+    }
+    const t = Date.parse(v);
+    return Number.isFinite(t) ? t : null;
+  }
+  return null;
+}
+
+function trySelect(db, sql) {
+  try {
+    return db.prepare(sql).all();
+  } catch (_e) {
+    return null;
+  }
+}
 
 class KuaishouAdapter {
   constructor(opts = {}) {
-    if (!opts.account || !opts.account.uid) {
-      throw new Error("KuaishouAdapter: opts.account.uid required");
-    }
-    this.account = opts.account;
+    // §A8 v0.2: account.uid OPTIONAL at construction — snapshot mode is
+    // stateless. Sqlite mode lazy-checks at sync time.
+    this.account = opts.account || null;
     this._dbPath = opts.dbPath || null;
-    this._dbDriverFactory = opts.dbDriverFactory || null;
 
     this.name = NAME;
     this.version = VERSION;
     this.capabilities = [
+      "sync:snapshot",
       "sync:sqlite",
       "parse:kuaishou-photo-history",
       "parse:kuaishou-user-collect",
@@ -54,11 +116,49 @@ class KuaishouAdapter {
       ],
       sensitivity: "medium",
       legalGate: false,
+      defaultInclude: {
+        watch: true,
+        collect: true,
+        search: true,
+      },
+    };
+
+    this._deps = {
+      fs,
+      dbDriverFactory: opts.dbDriverFactory || null,
     };
   }
 
-  async authenticate() {
-    return { ok: true, account: this.account.uid };
+  async authenticate(ctx = {}) {
+    if (ctx && typeof ctx.inputPath === "string" && ctx.inputPath.length > 0) {
+      try {
+        this._deps.fs.accessSync(ctx.inputPath, this._deps.fs.constants.R_OK);
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "INPUT_PATH_UNREADABLE",
+          message: `snapshot not readable at ${ctx.inputPath}: ${err.message}`,
+        };
+      }
+      return { ok: true, mode: "snapshot-file" };
+    }
+    if (this._dbPath || (ctx && typeof ctx.dbPath === "string")) {
+      if (!this.account || !this.account.uid) {
+        return {
+          ok: false,
+          reason: "NO_ACCOUNT_UID",
+          message:
+            "social-kuaishou.authenticate: sqlite mode requires account.uid",
+        };
+      }
+      return { ok: true, account: this.account.uid, mode: "sqlite" };
+    }
+    return {
+      ok: false,
+      reason: "NO_INPUT",
+      message:
+        "social-kuaishou.authenticate: needs opts.inputPath (snapshot mode) OR opts.dbPath (sqlite mode)",
+    };
   }
 
   async healthCheck() {
@@ -66,10 +166,85 @@ class KuaishouAdapter {
   }
 
   async *sync(opts = {}) {
+    if (typeof opts.inputPath === "string" && opts.inputPath.length > 0) {
+      yield* this._syncViaSnapshot(opts);
+      return;
+    }
     const dbPath = opts.dbPath || this._dbPath;
-    if (!dbPath || !fs.existsSync(dbPath)) return;
-    const Driver = this._dbDriverFactory
-      ? this._dbDriverFactory()
+    if (dbPath) {
+      yield* this._syncViaSqlite({ ...opts, dbPath });
+      return;
+    }
+    throw new Error(
+      "social-kuaishou.sync: needs opts.inputPath (snapshot mode, Android in-APK cc) OR opts.dbPath (sqlite mode, legacy device-pull)",
+    );
+  }
+
+  async *_syncViaSnapshot(opts) {
+    const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
+    const snapshot = JSON.parse(raw);
+    if (
+      !snapshot ||
+      typeof snapshot !== "object" ||
+      snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION
+    ) {
+      throw new Error(
+        `social-kuaishou.sync: snapshot schemaVersion mismatch (got ${snapshot && snapshot.schemaVersion}, expected ${SNAPSHOT_SCHEMA_VERSION})`,
+      );
+    }
+    const fallbackCapturedAt =
+      Number.isFinite(snapshot.snapshottedAt) && snapshot.snapshottedAt > 0
+        ? Math.floor(snapshot.snapshottedAt)
+        : Date.now();
+
+    const account =
+      snapshot.account && typeof snapshot.account === "object"
+        ? snapshot.account
+        : null;
+    const include = opts.include || {};
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+
+    const events = Array.isArray(snapshot.events) ? snapshot.events : [];
+    let emitted = 0;
+    for (const ev of events) {
+      if (emitted >= limit) return;
+      if (!ev || typeof ev !== "object") continue;
+      const kind = ev.kind;
+      if (!VALID_SNAPSHOT_KINDS.includes(kind)) continue;
+      if (include[kind] === false) continue;
+
+      const capturedAt =
+        parseTime(ev.capturedAt) ||
+        parseTime(ev.time) ||
+        fallbackCapturedAt;
+      const id =
+        (typeof ev.id === "string" && ev.id.length > 0 && ev.id) ||
+        ev.photoId ||
+        ev.keyword ||
+        null;
+
+      yield {
+        adapter: NAME,
+        kind,
+        originalId: stableOriginalId(kind, id),
+        capturedAt,
+        payload: { ...ev, account },
+      };
+      emitted += 1;
+    }
+  }
+
+  async *_syncViaSqlite(opts) {
+    if (!this.account || !this.account.uid) {
+      throw new Error(
+        "social-kuaishou._syncViaSqlite: account.uid required (set via new KuaishouAdapter({ account: { uid } }) in cli wiring)",
+      );
+    }
+    const dbPath = opts.dbPath;
+    if (!dbPath || !this._deps.fs.existsSync(dbPath)) return;
+    const Driver = this._deps.dbDriverFactory
+      ? this._deps.dbDriverFactory()
       : require("better-sqlite3-multiple-ciphers");
     const db = new Driver(dbPath, { readonly: true });
 
@@ -84,7 +259,7 @@ class KuaishouAdapter {
           adapter: NAME,
           originalId: `photo-${row.id || row._id || row.photo_id}`,
           capturedAt: parseTime(row.view_time || row.time || row.create_time),
-          payload: { row, kind: "watch" },
+          payload: { row, kind: KIND_WATCH },
         };
       }
 
@@ -98,7 +273,7 @@ class KuaishouAdapter {
           adapter: NAME,
           originalId: `collect-${row.id || row.photo_id}`,
           capturedAt: parseTime(row.collect_time || row.time),
-          payload: { row, kind: "collect" },
+          payload: { row, kind: KIND_COLLECT },
         };
       }
 
@@ -112,126 +287,203 @@ class KuaishouAdapter {
           adapter: NAME,
           originalId: `search-${row.id || row.keyword + ":" + row.search_time}`,
           capturedAt: parseTime(row.search_time || row.time),
-          payload: { row, kind: "search" },
+          payload: { row, kind: KIND_SEARCH },
         };
       }
     } finally {
       try {
         db.close();
-      } catch (_e) {}
+      } catch (_e) {
+        /* ignore */
+      }
     }
   }
 
   normalize(raw) {
-    if (!raw || !raw.payload || !raw.payload.row) {
-      throw new Error("KuaishouAdapter.normalize: row missing");
+    if (!raw || !raw.payload) {
+      throw new Error("KuaishouAdapter.normalize: payload missing");
     }
-    const { kind, row } = raw.payload;
-    const now = Date.now();
-    const occurredAt =
-      parseTime(row.view_time || row.collect_time || row.search_time || row.time) ||
-      now;
-    const source = {
-      adapter: NAME,
-      adapterVersion: VERSION,
-      originalId: raw.originalId,
-      capturedAt: occurredAt,
-      capturedBy: "sqlite",
-    };
+    const ingestedAt = Date.now();
+    const kind = raw.kind || raw.payload.kind;
+    const p = raw.payload;
 
-    if (kind === "collect") {
-      return {
-        events: [
-          {
-            id: newId(),
-            type: "event",
-            subtype: "like",
-            occurredAt,
-            actor: "person-self",
-            content: { title: row.caption || row.title || "(no caption)" },
-            ingestedAt: now,
-            source,
-            extra: {
-              photoId: row.photo_id || null,
-              authorId: row.author_id || null,
-              authorName: row.author_name || null,
-            },
-          },
-        ],
-        persons: [],
-        places: [],
-        items: [],
-        topics: [],
-      };
+    if (kind === KIND_COLLECT) {
+      return normalizeCollect(p, raw, ingestedAt);
     }
-    if (kind === "search") {
-      return {
-        events: [
-          {
-            id: newId(),
-            type: "event",
-            subtype: "post",
-            occurredAt,
-            actor: "person-self",
-            content: { title: row.keyword || row.query || "(empty query)" },
-            ingestedAt: now,
-            source,
-            extra: { kind: "search", keyword: row.keyword || row.query || null },
-          },
-        ],
-        persons: [],
-        places: [],
-        items: [],
-        topics: [],
-      };
+    if (kind === KIND_SEARCH) {
+      return normalizeSearch(p, raw, ingestedAt);
     }
-    // watch → browse event
-    return {
-      events: [
-        {
-          id: newId(),
-          type: "event",
-          subtype: "browse",
-          occurredAt,
-          actor: "person-self",
-          content: { title: row.caption || row.title || "(no caption)" },
-          ingestedAt: now,
-          source,
-          extra: {
-            photoId: row.photo_id || null,
-            duration: row.duration || row.play_duration || null,
-            authorId: row.author_id || null,
-            authorName: row.author_name || null,
-          },
-        },
-      ],
-      persons: [],
-      places: [],
-      items: [],
-      topics: [],
-    };
+    if (kind === KIND_WATCH) {
+      return normalizeWatch(p, raw, ingestedAt);
+    }
+    throw new Error(`KuaishouAdapter.normalize: unknown kind ${kind}`);
   }
 }
 
-function trySelect(db, sql) {
-  try {
-    return db.prepare(sql).all();
-  } catch (_e) {
-    return null;
+function buildSource(raw, occurredAt, capturedBy) {
+  return {
+    adapter: NAME,
+    adapterVersion: VERSION,
+    originalId: raw.originalId,
+    capturedAt: raw.capturedAt || occurredAt,
+    capturedBy,
+  };
+}
+
+function pickField(p, snapshotKey, ...sqlKeys) {
+  if (p[snapshotKey] != null) return p[snapshotKey];
+  const row = p.row || {};
+  for (const k of sqlKeys) {
+    if (row[k] != null) return row[k];
+  }
+  return null;
+}
+
+function normalizeWatch(p, raw, ingestedAt) {
+  if (!p.row && !p.photoId && !p.caption) {
+    if (!p.row) {
+      throw new Error("KuaishouAdapter.normalize: row missing");
+    }
   }
+  const isSnapshot = !p.row;
+  const row = p.row || {};
+  const caption =
+    pickField(p, "caption", "caption", "title") || "(no caption)";
+  const occurredAt =
+    parseTime(p.capturedAt) ||
+    parseTime(row.view_time || row.time || row.create_time) ||
+    raw.capturedAt ||
+    ingestedAt;
+  const source = buildSource(
+    raw,
+    occurredAt,
+    isSnapshot ? CAPTURED_BY.API : CAPTURED_BY.SQLITE,
+  );
+  return {
+    events: [
+      {
+        id: newId(),
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.BROWSE,
+        occurredAt,
+        actor: "person-self",
+        content: { title: caption },
+        ingestedAt,
+        source,
+        extra: {
+          platform: "kuaishou",
+          photoId: pickField(p, "photoId", "photo_id"),
+          duration: pickField(p, "duration", "duration", "play_duration"),
+          authorId: pickField(p, "authorId", "author_id"),
+          authorName: pickField(p, "authorName", "author_name"),
+        },
+      },
+    ],
+    persons: [],
+    places: [],
+    items: [],
+    topics: [],
+  };
 }
 
-function parseTime(v) {
-  if (Number.isFinite(v)) return v > 1e12 ? v : v * 1000;
-  if (typeof v === "string") {
-    if (/^\d+$/.test(v)) {
-      const n = parseInt(v, 10);
-      return n > 1e12 ? n : n * 1000;
+function normalizeCollect(p, raw, ingestedAt) {
+  if (!p.row && !p.photoId && !p.caption) {
+    if (!p.row) {
+      throw new Error("KuaishouAdapter.normalize: row missing");
     }
-    const t = Date.parse(v);
-    return Number.isFinite(t) ? t : null;
   }
-  return null;
+  const isSnapshot = !p.row;
+  const row = p.row || {};
+  const caption =
+    pickField(p, "caption", "caption", "title") || "(no caption)";
+  const occurredAt =
+    parseTime(p.capturedAt) ||
+    parseTime(row.collect_time || row.time) ||
+    raw.capturedAt ||
+    ingestedAt;
+  const source = buildSource(
+    raw,
+    occurredAt,
+    isSnapshot ? CAPTURED_BY.API : CAPTURED_BY.SQLITE,
+  );
+  return {
+    events: [
+      {
+        id: newId(),
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.LIKE,
+        occurredAt,
+        actor: "person-self",
+        content: { title: caption },
+        ingestedAt,
+        source,
+        extra: {
+          platform: "kuaishou",
+          photoId: pickField(p, "photoId", "photo_id"),
+          authorId: pickField(p, "authorId", "author_id"),
+          authorName: pickField(p, "authorName", "author_name"),
+        },
+      },
+    ],
+    persons: [],
+    places: [],
+    items: [],
+    topics: [],
+  };
+}
+
+function normalizeSearch(p, raw, ingestedAt) {
+  if (!p.row && !p.keyword && !p.query) {
+    if (!p.row) {
+      throw new Error("KuaishouAdapter.normalize: row missing");
+    }
+  }
+  const isSnapshot = !p.row;
+  const row = p.row || {};
+  const keyword =
+    pickField(p, "keyword", "keyword", "query") ||
+    pickField(p, "query") ||
+    "(empty query)";
+  const occurredAt =
+    parseTime(p.capturedAt) ||
+    parseTime(p.searchAt) ||
+    parseTime(row.search_time || row.time) ||
+    raw.capturedAt ||
+    ingestedAt;
+  const source = buildSource(
+    raw,
+    occurredAt,
+    isSnapshot ? CAPTURED_BY.API : CAPTURED_BY.SQLITE,
+  );
+  return {
+    events: [
+      {
+        id: newId(),
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.POST,
+        occurredAt,
+        actor: "person-self",
+        content: { title: keyword },
+        ingestedAt,
+        source,
+        extra: {
+          platform: "kuaishou",
+          kind: "search",
+          keyword,
+        },
+      },
+    ],
+    persons: [],
+    places: [],
+    items: [],
+    topics: [],
+  };
 }
 
-module.exports = { KuaishouAdapter, NAME, VERSION };
+module.exports = {
+  KuaishouAdapter,
+  NAME,
+  VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+  VALID_SNAPSHOT_KINDS,
+};