@chainlesschain/personal-data-hub 0.2.4 → 0.3.1

package/lib/adapters/system-data-android/adapter.js

@@ -23,11 +23,18 @@ const {
   ENTITY_TYPES,
   PERSON_SUBTYPES,
   ITEM_SUBTYPES,
+  EVENT_SUBTYPES,
   CAPTURED_BY,
 } = require("../../constants");
 
 const NAME = "system-data-android";
-const VERSION = "0.1.0";
+// v0.3.0 (2026-05-24): added kind="media-file" via bridge mode
+//   (host-adb-bridge media.list across 5 /sdcard categories). Metadata
+//   only — path/size/mtime/ext, no file content.
+// v0.2.0 (2026-05-24): added kind="sms" + kind="call" via bridge mode.
+//   Snapshot mode still v1 schema — sms/calls/media only land via
+//   bridge path until Android snapshot writer is updated to include them.
+const VERSION = "0.3.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 
 // Stable per-source originalId — registry.putRawEvent rejects null originalId
@@ -48,6 +55,25 @@ function appOriginalId(a) {
     `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   return `android-app:${k}`;
 }
+function smsOriginalId(s) {
+  // Stable across re-syncs: use SMS _id from the system content provider.
+  const k = (s && s.id != null && String(s.id)) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `android-sms:${k}`;
+}
+function callOriginalId(c) {
+  // Stable across re-syncs: use call_log _id from the system content provider.
+  const k = (c && c.id != null && String(c.id)) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `android-call:${k}`;
+}
+function mediaOriginalId(m) {
+  // Full filesystem path is stable as long as the file isn't moved/renamed.
+  // Path is unique within the device.
+  const k = (m && typeof m.path === "string" && m.path) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `android-media:${k}`;
+}
 
 class SystemDataAndroidAdapter {
   constructor(opts = {}) {
@@ -56,6 +82,9 @@ class SystemDataAndroidAdapter {
     this.capabilities = [
       "sync:android-content-provider",
       "sync:android-package-manager",
+      "sync:android-sms",
+      "sync:android-call-log",
+      "sync:android-media-files",
     ];
     this.extractMode = "device-pull";
     this.rateLimits = { perDay: 24 };
@@ -63,10 +92,20 @@ class SystemDataAndroidAdapter {
       fields: [
         "contacts:displayName,phones,emails,starred,organization,photoUri",
         "installed_apps:packageName,label,versionName,versionCode,firstInstallTime,lastUpdateTime,isSystem",
+        "sms:id,address,body,date,dateSent,type,threadId,read,subject",
+        "callLog:id,number,name,duration,date,type,geocoded",
+        // Media is metadata-only — file content never leaves the device.
+        "media:path,size,mtimeMs,ext,category(photos|pictures|videos|downloads|documents)",
       ],
-      sensitivity: "medium",
+      sensitivity: "high",
       legalGate: false,
-      defaultInclude: { contacts: true, apps: true },
+      defaultInclude: {
+        contacts: true,
+        apps: true,
+        sms: true,
+        calls: true,
+        media: { photos: true, pictures: true, videos: true, downloads: true, documents: true },
+      },
     };
 
     // _deps for test injection — mirrors the pattern in cli-dev.md so test
@@ -191,6 +230,68 @@ class SystemDataAndroidAdapter {
         emitted += 1;
       }
     }
+
+    const includeSms = opts.include?.sms !== false;
+    if (includeSms) {
+      const res = await bridge.invoke("sms.query", {
+        since: Number.isInteger(opts.since) ? opts.since : undefined,
+      });
+      const arr = Array.isArray(res) ? res : Array.isArray(res?.sms) ? res.sms : [];
+      for (const s of arr) {
+        if (emitted >= limit) return;
+        yield {
+          kind: "sms",
+          originalId: smsOriginalId(s),
+          capturedAt,
+          payload: s,
+        };
+        emitted += 1;
+      }
+    }
+
+    const includeCalls = opts.include?.calls !== false;
+    if (includeCalls) {
+      const res = await bridge.invoke("call.query", {
+        since: Number.isInteger(opts.since) ? opts.since : undefined,
+      });
+      const arr = Array.isArray(res) ? res : Array.isArray(res?.calls) ? res.calls : [];
+      for (const c of arr) {
+        if (emitted >= limit) return;
+        yield {
+          kind: "call",
+          originalId: callOriginalId(c),
+          capturedAt,
+          payload: c,
+        };
+        emitted += 1;
+      }
+    }
+
+    // Media files — metadata only (path, size, mtime, ext). Never reads
+    // file content off the device. UI uses per-category include keys so
+    // a privacy-conscious user can keep photos but skip downloads, etc.
+    const MEDIA_CATEGORIES = ["photos", "pictures", "videos", "downloads", "documents"];
+    for (const cat of MEDIA_CATEGORIES) {
+      // Per-category include key: include.media.photos, include.media.videos, ...
+      // Top-level `include.media === false` disables ALL media in one switch.
+      if (opts.include?.media === false) break;
+      if (opts.include?.media?.[cat] === false) continue;
+      const res = await bridge.invoke("media.list", {
+        category: cat,
+        since: Number.isInteger(opts.since) ? opts.since : undefined,
+      });
+      const arr = Array.isArray(res) ? res : Array.isArray(res?.files) ? res.files : [];
+      for (const f of arr) {
+        if (emitted >= limit) return;
+        yield {
+          kind: "media-file",
+          originalId: mediaOriginalId(f),
+          capturedAt,
+          payload: f,
+        };
+        emitted += 1;
+      }
+    }
   }
 
   async *_syncViaSnapshot(opts) {
@@ -336,6 +437,122 @@ class SystemDataAndroidAdapter {
       };
     }
 
+    if (raw.kind === "sms") {
+      const p = raw.payload || {};
+      // SMS type from Android SDK Telephony.Sms (Inbox.MESSAGE_TYPE_*):
+      //   1 INBOX, 2 SENT, 3 DRAFT, 4 OUTBOX, 5 FAILED, 6 QUEUED
+      const direction = p.type === 2 || p.type === 4 ? "out" : "in";
+      const eventId = `event-android-sms-${p.id || raw.capturedAt}`;
+      const occurredAt = Number.isInteger(p.date) ? p.date : raw.capturedAt;
+      const bodyText = typeof p.body === "string" ? p.body : "";
+      const event = {
+        id: eventId,
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.MESSAGE,
+        occurredAt,
+        ingestedAt,
+        source: source(`android-sms:${p.id || raw.capturedAt}`),
+        actor: direction === "in" ? p.address : "self",
+        // Participants on the OTHER side of the message.
+        participants: p.address ? [p.address] : [],
+        // Validator (lib/schemas.js validateEvent) requires `content` to be
+        // a plain object — title/text/etc go INSIDE this object, not on the
+        // event root.
+        content: {
+          title: bodyText.length > 0
+            ? (bodyText.length > 80 ? bodyText.substring(0, 80) + "…" : bodyText)
+            : "(空短信)",
+          text: bodyText,
+        },
+      };
+      const extra = { direction, threadId: p.threadId };
+      if (typeof p.dateSent === "number") extra.dateSent = p.dateSent;
+      if (typeof p.read === "boolean") extra.read = p.read;
+      if (typeof p.subject === "string" && p.subject.length > 0) extra.subject = p.subject;
+      if (Number.isInteger(p.type)) extra.smsType = p.type;
+      event.extra = extra;
+
+      return { events: [event], persons: [], places: [], items: [], topics: [] };
+    }
+
+    if (raw.kind === "call") {
+      const p = raw.payload || {};
+      // Call type from Android SDK CallLog.Calls.TYPE:
+      //   1 INCOMING, 2 OUTGOING, 3 MISSED, 4 VOICEMAIL, 5 REJECTED, 6 BLOCKED
+      const direction = p.type === 2 ? "out" : "in";
+      const eventId = `event-android-call-${p.id || raw.capturedAt}`;
+      const occurredAt = Number.isInteger(p.date) ? p.date : raw.capturedAt;
+      const callTypeName =
+        p.type === 1 ? "incoming" :
+        p.type === 2 ? "outgoing" :
+        p.type === 3 ? "missed" :
+        p.type === 4 ? "voicemail" :
+        p.type === 5 ? "rejected" :
+        p.type === 6 ? "blocked" : "unknown";
+      const titleName =
+        (typeof p.name === "string" && p.name.trim().length > 0) ? p.name.trim() : (p.number || "未知号码");
+      const title =
+        `${callTypeName === "missed" ? "未接 " : ""}${callTypeName === "outgoing" ? "拨打 " : ""}${callTypeName === "incoming" ? "来电 " : ""}${titleName}`;
+      const event = {
+        id: eventId,
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.CALL,
+        occurredAt,
+        ingestedAt,
+        source: source(`android-call:${p.id || raw.capturedAt}`),
+        actor: direction === "in" ? p.number : "self",
+        participants: p.number ? [p.number] : [],
+        // Schema-required `content` object — title goes here, not on root.
+        content: { title },
+      };
+      if (Number.isInteger(p.duration) && p.duration > 0) {
+        event.durationMs = p.duration * 1000;
+      }
+      const extra = { direction, callType: callTypeName };
+      if (Number.isInteger(p.type)) extra.androidCallType = p.type;
+      if (typeof p.geocoded === "string" && p.geocoded.length > 0) extra.geocoded = p.geocoded;
+      if (typeof p.name === "string" && p.name.length > 0) extra.name = p.name;
+      event.extra = extra;
+
+      return { events: [event], persons: [], places: [], items: [], topics: [] };
+    }
+
+    if (raw.kind === "media-file") {
+      const p = raw.payload || {};
+      const path = typeof p.path === "string" ? p.path : "";
+      const fileName = path.includes("/") ? path.substring(path.lastIndexOf("/") + 1) : path;
+      // Category → item subtype + category string
+      let subtype = ITEM_SUBTYPES.OTHER;
+      let category = "media";
+      if (p.category === "photos" || p.category === "pictures" || p.category === "videos") {
+        subtype = ITEM_SUBTYPES.MEDIA;
+        category = p.category;
+      } else if (p.category === "documents") {
+        subtype = ITEM_SUBTYPES.DOCUMENT;
+        category = "documents";
+      } else if (p.category === "downloads") {
+        subtype = ITEM_SUBTYPES.OTHER;
+        category = "downloads";
+      }
+      const item = {
+        id: `item-android-media-${path}`,
+        type: ENTITY_TYPES.ITEM,
+        subtype,
+        name: fileName || "(无名)",
+        category,
+        ingestedAt,
+        source: source(`android-media:${path}`),
+        extra: {
+          path,
+          size: Number.isInteger(p.size) ? p.size : null,
+          mtimeMs: Number.isInteger(p.mtimeMs) ? p.mtimeMs : null,
+          ext: typeof p.ext === "string" ? p.ext : null,
+          androidCategory: p.category,
+        },
+      };
+      return { events: [], persons: [], places: [], items: [item], topics: [] };
+    }
+
     throw new Error(`system-data-android.normalize: unknown raw.kind=${raw.kind}`);
   }
 }

package/lib/adapters/travel-12306/index.js

@@ -1,18 +1,39 @@
 /**
- * Phase 9.2 — 12306 (China Railway) ticket adapter.
+ * §2.5 v0.2 — 12306 (China Railway) ticket adapter, dual-mode.
  *
- * Source format: 12306 doesn't have an official user export. We accept
- * two file formats:
- *   1. order-confirmation emails (already adapter-parsed by Phase 5 +
- *      Phase 5.4 travel template). Phase 9.2 reads those events back
- *      out of the vault and **re-normalizes** them into the
- *      adapter-neutral travel schema. This is the "rich vault →
- *      enrich" pattern.
- *   2. user-uploaded JSON dump (e.g. exported from a 3rd-party 12306
- *      scraper, or hand-curated). Optional.
+ *   1. snapshot mode (opts.inputPath): in-APK Android cc reads a snapshot
+ *      JSON produced by the phone's Kyfw12306LocalCollector. The collector
+ *      uses captured login cookie to hit kyfw.12306.cn `/otn/queryOrder/
+ *      queryMyOrder` + `/otn/queryOrder/queryMyOrderNoComplete` (cookie-only,
+ *      no signing), parses each ticket into a structured event, writes JSON.
+ *      Desktop-independent. account is OPTIONAL at construction.
  *
- * For v0.5 we focus on (2) since (1) is purely vault-side derivation
- * the AnalysisEngine can do at query time.
+ *   2. file-import mode (opts.dataPath, legacy v0.5): user-uploaded JSON
+ *      dump from a 3rd-party 12306 scraper or hand-curated. Preserved for
+ *      backward compat. account.username REQUIRED.
+ *
+ * Snapshot schema (mirrors Kyfw12306LocalCollector.SNAPSHOT_SCHEMA_VERSION):
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "snapshottedAt": <epoch-ms>,
+ *     "vendor": "12306",
+ *     "events": [
+ *       { "kind": "ticket", "id": "ticket-<seqNo>:<n>",  "capturedAt": <ms>,
+ *         "orderSequenceNo": "...", "ticketNumber": "...",
+ *         "passengerName": "张三", "passengerIdLast6": "123456",
+ *         "trainNumber": "G123",
+ *         "fromStation": "上海虹桥", "toStation": "北京南",
+ *         "departureMs": <ms>, "arrivalMs": <ms>,
+ *         "seatTypeName": "二等座", "coachNo": "05", "seatNo": "12A",
+ *         "ticketPrice": 553.5, "orderDateMs": <ms>, "orderTotalPrice": 553.5,
+ *         "isCompleted": true }
+ *     ]
+ *   }
+ *
+ * Sensitivity: medium — ticket history reveals travel patterns + 6 trailing
+ * digits of national ID (used for cross-source EntityResolver linking, never
+ * exposed in vault search). Snapshot file is purged after sync.
  */
 
 "use strict";
@@ -21,32 +42,75 @@ const fs = require("node:fs");
 const { normalizeTravelRecord, parseChineseDateTime } = require("../travel-base");
 
 const NAME = "travel-12306";
-const VERSION = "0.5.0";
+const VERSION = "0.6.0";
+const SNAPSHOT_SCHEMA_VERSION = 1;
+
+const KIND_TICKET = "ticket";
+const VALID_SNAPSHOT_KINDS = Object.freeze([KIND_TICKET]);
 
 class Train12306Adapter {
   constructor(opts = {}) {
-    if (!opts.account || !opts.account.username) {
-      throw new Error("Train12306Adapter: opts.account.username required (12306 user id)");
-    }
-    this.account = opts.account;
+    // §2.5 v0.2: account.username OPTIONAL — snapshot mode is stateless and
+    // doesn't need a pre-known username. file-import mode still requires it,
+    // checked at sync time, not construction.
+    this.account = opts.account || null;
     this._dataPath = opts.dataPath || null;
 
     this.name = NAME;
     this.version = VERSION;
-    this.capabilities = ["import:json", "parse:12306-orders"];
-    this.extractMode = "file-import";
+    this.capabilities = [
+      "sync:snapshot",
+      "import:json",
+      "parse:12306-orders",
+    ];
+    this.extractMode = "device-pull";
     this.rateLimits = {};
     this.dataDisclosure = {
       fields: [
-        "12306:orderId / passengerName / trainNumber / fromStation / toStation / departureTime / arrivalTime / seat / price",
+        "12306:orderSequenceNo / ticketNumber / passengerName / trainNumber / fromStation / toStation / departureMs / arrivalMs / seat / price",
       ],
       sensitivity: "medium",
       legalGate: false,
+      defaultInclude: {
+        ticket: true,
+      },
+    };
+
+    // _deps injection seam — vi.mock fs doesn't intercept inlined CJS require.
+    this._deps = {
+      fs,
     };
   }
 
-  async authenticate() {
-    return { ok: true, account: this.account.username };
+  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._dataPath || (ctx && typeof ctx.dataPath === "string")) {
+      if (!this.account || !this.account.username) {
+        return {
+          ok: false,
+          reason: "NO_ACCOUNT_USERNAME",
+          message: "travel-12306.authenticate: file-import mode requires account.username",
+        };
+      }
+      return { ok: true, account: this.account.username, mode: "file-import" };
+    }
+    return {
+      ok: false,
+      reason: "NO_INPUT",
+      message:
+        "travel-12306.authenticate: needs opts.inputPath (snapshot mode) OR opts.dataPath (file-import mode)",
+    };
   }
 
   async healthCheck() {
@@ -54,14 +118,83 @@ class Train12306Adapter {
   }
 
   async *sync(opts = {}) {
+    if (typeof opts.inputPath === "string" && opts.inputPath.length > 0) {
+      yield* this._syncViaSnapshot(opts);
+      return;
+    }
     const dataPath = opts.dataPath || this._dataPath;
-    if (!dataPath || !fs.existsSync(dataPath)) return;
-    const buf = fs.readFileSync(dataPath, "utf-8");
+    if (dataPath) {
+      yield* this._syncViaFileImport({ ...opts, dataPath });
+      return;
+    }
+    throw new Error(
+      "travel-12306.sync: needs opts.inputPath (snapshot mode, Android in-APK cc) OR opts.dataPath (file-import mode, user-uploaded JSON)",
+    );
+  }
+
+  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(
+        `travel-12306.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 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 =
+        (Number.isFinite(ev.capturedAt) && ev.capturedAt) ||
+        (Number.isFinite(ev.departureMs) && ev.departureMs) ||
+        fallbackCapturedAt;
+      const id =
+        (typeof ev.id === "string" && ev.id.length > 0 && ev.id) ||
+        ev.orderSequenceNo ||
+        null;
+
+      yield {
+        adapter: NAME,
+        kind,
+        originalId: stableOriginalId(id || `unknown-${emitted}`),
+        capturedAt,
+        payload: { ...ev, snapshot: true },
+      };
+      emitted += 1;
+    }
+  }
+
+  async *_syncViaFileImport(opts) {
+    if (!this.account || !this.account.username) {
+      throw new Error(
+        "travel-12306._syncViaFileImport: account.username required (set via new Train12306Adapter({ account: { username } }))",
+      );
+    }
+    const dataPath = opts.dataPath;
+    if (!dataPath || !this._deps.fs.existsSync(dataPath)) return;
+    const buf = this._deps.fs.readFileSync(dataPath, "utf-8");
     let records;
     try {
       records = parseRecords(buf);
     } catch (err) {
-      throw new Error(`Train12306Adapter: parse failed: ${err.message}`);
+      throw new Error(`travel-12306._syncViaFileImport: parse failed: ${err.message}`);
     }
     for (const r of records) {
       yield {
@@ -74,7 +207,18 @@ class Train12306Adapter {
   }
 
   normalize(raw) {
-    if (!raw || !raw.payload || !raw.payload.record) {
+    if (!raw || !raw.payload) {
+      throw new Error("Train12306Adapter.normalize: payload missing");
+    }
+    // Snapshot-mode payload is the parsed event directly; legacy file-import
+    // payload has `.record` (already normalized shape).
+    if (raw.payload.snapshot) {
+      return normalizeTravelRecord(snapshotEventToRecord(raw.payload), {
+        adapterName: NAME,
+        adapterVersion: VERSION,
+      });
+    }
+    if (!raw.payload.record) {
       throw new Error("Train12306Adapter.normalize: raw.payload.record missing");
     }
     return normalizeTravelRecord(raw.payload.record, {
@@ -84,8 +228,43 @@ class Train12306Adapter {
   }
 }
 
+function stableOriginalId(id) {
+  return `12306:ticket:${id}`;
+}
+
+/** Convert a v0.2 snapshot event into the adapter-neutral travel record
+ *  shape that [normalizeTravelRecord] expects. */
+function snapshotEventToRecord(ev) {
+  return {
+    vendorId: "12306",
+    recordId: String(ev.id || ev.orderSequenceNo || ev.ticketNumber),
+    vehicleType: "train",
+    from: { station: ev.fromStation },
+    to: { station: ev.toStation },
+    departureMs: ev.departureMs || null,
+    arrivalMs: ev.arrivalMs || null,
+    carrier: "12306",
+    vehicleNumber: ev.trainNumber,
+    totalCost:
+      Number.isFinite(ev.ticketPrice) && ev.ticketPrice > 0
+        ? { value: ev.ticketPrice, currency: "CNY" }
+        : null,
+    traveler: ev.passengerName,
+    confirmationCode: ev.ticketNumber || ev.orderSequenceNo,
+    bookedAt: ev.orderDateMs || null,
+    extras: {
+      seat: ev.seatTypeName,
+      coachNo: ev.coachNo,
+      seatNumber: ev.seatNo,
+      isCompleted: ev.isCompleted,
+      idLast6: ev.passengerIdLast6 || undefined,
+      orderTotalPrice: ev.orderTotalPrice || undefined,
+    },
+  };
+}
+
 /**
- * Parse a 12306 dump file. Accepts either:
+ * Parse a 12306 dump file (legacy v0.5 file-import mode). Accepts either:
  *   - JSON array of order objects
  *   - JSON object { orders: [...] }
  *   - JSONL (one order per line)
@@ -134,7 +313,7 @@ function orderToRecord(o) {
     extras: {
       seat: o.seat || o.seatType,
       seatNumber: o.seatNumber || o.seat_number,
-      idCardLast6: o.idLast6 || undefined, // for cross-source EntityResolver linking
+      idCardLast6: o.idLast6 || undefined,
     },
   };
 }
@@ -148,4 +327,11 @@ function numberOrParse(v) {
   return null;
 }
 
-module.exports = { Train12306Adapter, parseRecords, NAME, VERSION };
+module.exports = {
+  Train12306Adapter,
+  parseRecords,
+  NAME,
+  VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+  VALID_SNAPSHOT_KINDS,
+};