@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

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

@@ -0,0 +1,164 @@
+/**
+ * Phase 9.4 — Amap (高德地图) location history adapter.
+ *
+ * Source: Amap stores recent navigation / search history in app-local
+ * SQLite DBs. Per sjqz/parsers/amap.py, the relevant tables are:
+ *   - history_search  (search queries)
+ *   - history_route   (planned routes)
+ *   - favourites      (saved locations like 公司 / 家)
+ *
+ * Adapter extractMode is "device-pull" — relies on Phase 7.5
+ * AndroidExtractor to pull the .db files from Amap's app-private
+ * directory. For v0.5 we accept a pre-pulled local path (file-import
+ * fallback) so users without root can hand-extract via adb backup.
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const { normalizeTravelRecord, parseChineseDateTime } = require("../travel-base");
+
+const NAME = "travel-amap";
+const VERSION = "0.5.0";
+
+class AmapAdapter {
+  constructor(opts = {}) {
+    if (!opts.account || !opts.account.deviceId) {
+      throw new Error("AmapAdapter: opts.account.deviceId required");
+    }
+    this.account = opts.account;
+    this._dbPath = opts.dbPath || null;
+    this._dbDriverFactory = opts.dbDriverFactory || null;
+
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = ["sync:sqlite", "parse:amap-history"];
+    this.extractMode = "device-pull";
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "amap:search_history (query / time / location)",
+        "amap:route_history (from / to / mode / time)",
+        "amap:favourites (name / address / coords)",
+      ],
+      sensitivity: "medium",
+      legalGate: false,
+    };
+  }
+
+  async authenticate() {
+    return { ok: true, account: this.account.deviceId };
+  }
+
+  async healthCheck() {
+    return { ok: true, lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    const dbPath = opts.dbPath || this._dbPath;
+    if (!dbPath || !fs.existsSync(dbPath)) return;
+    const Database = this._dbDriverFactory || (() => require("better-sqlite3-multiple-ciphers"));
+    const Driver = typeof Database === "function" ? Database() : Database;
+    const db = new Driver(dbPath, { readonly: true });
+
+    try {
+      // History routes (most analytically valuable)
+      const routes = trySelect(db, "SELECT * FROM history_route LIMIT 5000")
+        || trySelect(db, "SELECT * FROM ROUTE_HISTORY LIMIT 5000")
+        || [];
+      for (const r of routes) {
+        const rec = routeRowToRecord(r);
+        if (rec) {
+          yield {
+            adapter: NAME,
+            originalId: rec.recordId,
+            capturedAt: rec.bookedAt || Date.now(),
+            payload: { record: rec, kind: "route" },
+          };
+        }
+      }
+      // History search (queries — produce trip events of type "visit")
+      const searches = trySelect(db, "SELECT * FROM history_search LIMIT 5000") || [];
+      for (const r of searches) {
+        const rec = searchRowToRecord(r);
+        if (rec) {
+          yield {
+            adapter: NAME,
+            originalId: rec.recordId,
+            capturedAt: rec.bookedAt || Date.now(),
+            payload: { record: rec, kind: "search" },
+          };
+        }
+      }
+    } finally {
+      try { db.close(); } catch (_e) {}
+    }
+  }
+
+  normalize(raw) {
+    if (!raw || !raw.payload || !raw.payload.record) {
+      throw new Error("AmapAdapter.normalize: raw.payload.record missing");
+    }
+    return normalizeTravelRecord(raw.payload.record, {
+      adapterName: NAME,
+      adapterVersion: VERSION,
+    });
+  }
+}
+
+function trySelect(db, sql) {
+  try {
+    return db.prepare(sql).all();
+  } catch (_e) {
+    return null;
+  }
+}
+
+function routeRowToRecord(row) {
+  if (!row) return null;
+  const id = row.id || row._id || row.uid || row.guid;
+  if (!id) return null;
+  return {
+    vendorId: "amap",
+    recordId: `route-${id}`,
+    vehicleType: row.mode === "drive" ? "car" : (row.mode || "trip"),
+    from: { name: row.from_name || row.fromName || row.start, lat: row.from_lat || null, lng: row.from_lng || null },
+    to: { name: row.to_name || row.toName || row.dest, lat: row.to_lat || null, lng: row.to_lng || null },
+    departureMs: numberOrParse(row.time || row.create_time || row.start_time),
+    carrier: "高德地图",
+    extras: { mode: row.mode },
+  };
+}
+
+function searchRowToRecord(row) {
+  if (!row) return null;
+  const id = row.id || row._id || row.guid;
+  if (!id) return null;
+  // Search = a "visit" intent
+  return {
+    vendorId: "amap",
+    recordId: `search-${id}`,
+    vehicleType: "visit",
+    to: { name: row.keyword || row.query || row.poiname, lat: row.lat || null, lng: row.lng || null, city: row.city },
+    departureMs: numberOrParse(row.time || row.create_time),
+    carrier: "高德地图",
+    extras: { query: row.keyword || row.query },
+  };
+}
+
+function numberOrParse(v) {
+  if (Number.isFinite(v)) {
+    // Amap timestamps are sometimes seconds — heuristic upgrade to ms
+    return v > 1e12 ? v : (v > 1e10 ? v : v * 1000);
+  }
+  if (typeof v === "string") {
+    if (/^\d+$/.test(v)) {
+      const n = parseInt(v, 10);
+      return n > 1e12 ? n : (n > 1e10 ? n : n * 1000);
+    }
+    return parseChineseDateTime(v);
+  }
+  return null;
+}
+
+module.exports = { AmapAdapter, NAME, VERSION };

package/lib/adapters/travel-baidu-map/index.js

@@ -0,0 +1,162 @@
+/**
+ * Phase 9.4b — Baidu Map (百度地图) location history adapter.
+ *
+ * Parallels travel-amap but uses Baidu's table names. Per
+ * sjqz/parsers/baidumap.py the key tables are:
+ *   - search_history (queries)
+ *   - route_history  (planned routes)
+ *   - my_favourite   (saved places)
+ *   - offline_map    (downloaded offline maps; v2)
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const { normalizeTravelRecord, parseChineseDateTime } = require("../travel-base");
+
+const NAME = "travel-baidu-map";
+const VERSION = "0.5.0";
+
+class BaiduMapAdapter {
+  constructor(opts = {}) {
+    if (!opts.account || !opts.account.deviceId) {
+      throw new Error("BaiduMapAdapter: opts.account.deviceId required");
+    }
+    this.account = opts.account;
+    this._dbPath = opts.dbPath || null;
+    this._dbDriverFactory = opts.dbDriverFactory || null;
+
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = ["sync:sqlite", "parse:baidu-map-history"];
+    this.extractMode = "device-pull";
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "baidu:search_history",
+        "baidu:route_history",
+        "baidu:my_favourite",
+      ],
+      sensitivity: "medium",
+      legalGate: false,
+    };
+  }
+
+  async authenticate() {
+    return { ok: true, account: this.account.deviceId };
+  }
+
+  async healthCheck() {
+    return { ok: true, lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    const dbPath = opts.dbPath || this._dbPath;
+    if (!dbPath || !fs.existsSync(dbPath)) return;
+    const Database = this._dbDriverFactory || (() => require("better-sqlite3-multiple-ciphers"));
+    const Driver = typeof Database === "function" ? Database() : Database;
+    const db = new Driver(dbPath, { readonly: true });
+
+    try {
+      const routes = trySelect(db, "SELECT * FROM route_history LIMIT 5000")
+        || trySelect(db, "SELECT * FROM bd_route_history LIMIT 5000") || [];
+      for (const r of routes) {
+        const rec = routeRowToRecord(r);
+        if (rec) {
+          yield {
+            adapter: NAME,
+            originalId: rec.recordId,
+            capturedAt: rec.bookedAt || Date.now(),
+            payload: { record: rec, kind: "route" },
+          };
+        }
+      }
+      const searches = trySelect(db, "SELECT * FROM search_history LIMIT 5000") || [];
+      for (const r of searches) {
+        const rec = searchRowToRecord(r);
+        if (rec) {
+          yield {
+            adapter: NAME,
+            originalId: rec.recordId,
+            capturedAt: rec.bookedAt || Date.now(),
+            payload: { record: rec, kind: "search" },
+          };
+        }
+      }
+    } finally {
+      try { db.close(); } catch (_e) {}
+    }
+  }
+
+  normalize(raw) {
+    if (!raw || !raw.payload || !raw.payload.record) {
+      throw new Error("BaiduMapAdapter.normalize: raw.payload.record missing");
+    }
+    return normalizeTravelRecord(raw.payload.record, {
+      adapterName: NAME,
+      adapterVersion: VERSION,
+    });
+  }
+}
+
+function trySelect(db, sql) {
+  try {
+    return db.prepare(sql).all();
+  } catch (_e) {
+    return null;
+  }
+}
+
+function routeRowToRecord(row) {
+  if (!row) return null;
+  const id = row._id || row.id || row.uid;
+  if (!id) return null;
+  return {
+    vendorId: "baidumap",
+    recordId: `route-${id}`,
+    vehicleType: detectVehicle(row.type || row.mode),
+    from: { name: row.start_name || row.from_name, lat: row.start_lat || null, lng: row.start_lng || null },
+    to: { name: row.end_name || row.to_name, lat: row.end_lat || null, lng: row.end_lng || null },
+    departureMs: numberOrParse(row.time || row.create_time),
+    carrier: "百度地图",
+    extras: { mode: row.type || row.mode },
+  };
+}
+
+function searchRowToRecord(row) {
+  if (!row) return null;
+  const id = row._id || row.id;
+  if (!id) return null;
+  return {
+    vendorId: "baidumap",
+    recordId: `search-${id}`,
+    vehicleType: "visit",
+    to: { name: row.key || row.query, lat: row.lat || null, lng: row.lng || null, city: row.city },
+    departureMs: numberOrParse(row.time || row.create_time),
+    carrier: "百度地图",
+    extras: { query: row.key || row.query },
+  };
+}
+
+function detectVehicle(v) {
+  const s = String(v || "").toLowerCase();
+  if (s.includes("drive") || s.includes("car")) return "car";
+  if (s.includes("walk")) return "walk";
+  if (s.includes("bike") || s.includes("cycle")) return "bike";
+  if (s.includes("bus") || s.includes("transit")) return "bus";
+  return "trip";
+}
+
+function numberOrParse(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;
+    }
+    return parseChineseDateTime(v);
+  }
+  return null;
+}
+
+module.exports = { BaiduMapAdapter, NAME, VERSION };

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

@@ -0,0 +1,240 @@
+/**
+ * Phase 9 — shared travel adapter base.
+ *
+ * Common normalize logic for the 4 travel sources (12306 / Ctrip /
+ * Amap / Baidu Map). Each per-vendor adapter parses its source format
+ * into a `TravelRecord` then calls `normalizeTravelRecord()` here.
+ *
+ * TravelRecord shape (vendor-neutral):
+ *   {
+ *     vendorId:         "12306" | "ctrip" | "amap" | "baidumap"
+ *     recordId:         string   (vendor's order/trip id, unique)
+ *     vehicleType:      "flight" | "train" | "hotel" | "bus" | "car" | "visit"
+ *     from?:            { city?, station?, lat?, lng? }
+ *     to?:              { city?, station?, lat?, lng? }
+ *     departureMs?:     number   (ms epoch)
+ *     arrivalMs?:       number
+ *     carrier?:         string   ("国航" / "12306" / "携程酒店预订" / ...)
+ *     vehicleNumber?:   string   ("CA1234" / "G35" / "京A88888")
+ *     totalCost?:       { value, currency }
+ *     traveler?:        string   (passenger name)
+ *     confirmationCode?:string
+ *     bookedAt?:        number
+ *     extras?:          { ... vendor-specific }
+ *   }
+ *
+ * normalizeTravelRecord() returns a NormalizedBatch with:
+ *   - 1 Event of subtype `trip`
+ *   - 0-2 Place entities (from / to)
+ *   - 0-2 Person entities (traveler if known + carrier as merchant)
+ */
+
+"use strict";
+
+const { newId } = require("../../ids");
+
+/**
+ * Convert a TravelRecord to a NormalizedBatch.
+ *
+ * @param {TravelRecord} rec
+ * @param {object}        ctx       optional context for cross-source link
+ * @param {string}        ctx.accountKey   typically email or username
+ * @param {string}        ctx.adapterName  the actual adapter.name string
+ * @param {string}        ctx.adapterVersion
+ * @returns {NormalizedBatch}
+ */
+function normalizeTravelRecord(rec, ctx = {}) {
+  if (!rec || typeof rec !== "object") {
+    throw new Error("normalizeTravelRecord: rec required");
+  }
+  if (!rec.recordId) throw new Error("normalizeTravelRecord: rec.recordId required");
+
+  const now = Date.now();
+  const occurredAt = Number.isFinite(rec.departureMs)
+    ? rec.departureMs
+    : Number.isFinite(rec.bookedAt)
+      ? rec.bookedAt
+      : now;
+
+  const adapterName = ctx.adapterName || rec.vendorId || "travel";
+  const adapterVersion = ctx.adapterVersion || "0.1.0";
+  const source = {
+    adapter: adapterName,
+    adapterVersion,
+    originalId: String(rec.recordId),
+    capturedAt: occurredAt,
+    capturedBy: "export",
+  };
+
+  // Places
+  const places = [];
+  const fromPlaceId = rec.from ? placeIdFor(rec.from, adapterName) : null;
+  const toPlaceId = rec.to ? placeIdFor(rec.to, adapterName) : null;
+  if (fromPlaceId) {
+    places.push(makePlace(fromPlaceId, rec.from, now, source));
+  }
+  if (toPlaceId) {
+    places.push(makePlace(toPlaceId, rec.to, now, source));
+  }
+
+  // Carrier as merchant Person (so spending skill can attribute)
+  const persons = [];
+  let carrierPersonId = null;
+  if (rec.carrier) {
+    carrierPersonId = `person-${adapterName}-carrier-${slug(rec.carrier)}`;
+    persons.push({
+      id: carrierPersonId,
+      type: "person",
+      subtype: "merchant",
+      names: [rec.carrier],
+      identifiers: {},
+      ingestedAt: now,
+      source,
+      extra: { fromAdapter: adapterName, carrier: true },
+    });
+  }
+  // Traveler (if not self)
+  let travelerPersonId = null;
+  if (rec.traveler && rec.traveler !== ctx.selfName) {
+    travelerPersonId = `person-${adapterName}-traveler-${slug(rec.traveler)}`;
+    persons.push({
+      id: travelerPersonId,
+      type: "person",
+      subtype: "contact",
+      names: [rec.traveler],
+      identifiers: {},
+      ingestedAt: now,
+      source,
+      extra: { fromAdapter: adapterName, role: "traveler" },
+    });
+  }
+
+  // Event
+  const eventId = newId();
+  const event = {
+    id: eventId,
+    type: "event",
+    subtype: "trip",
+    occurredAt,
+    actor: travelerPersonId || "person-self",
+    participants: dedup(["person-self", travelerPersonId, carrierPersonId].filter(Boolean)),
+    content: {
+      title: buildTitle(rec),
+      ...(rec.extras && rec.extras.note ? { text: rec.extras.note } : {}),
+      ...(rec.totalCost && Number.isFinite(rec.totalCost.value)
+        ? { amount: { value: rec.totalCost.value, currency: rec.totalCost.currency || "CNY", direction: "out" } }
+        : {}),
+    },
+    ingestedAt: now,
+    source,
+    extra: {
+      vehicleType: rec.vehicleType,
+      vendorId: rec.vendorId,
+      ...(rec.from ? { from: rec.from.station || rec.from.city || formatPlace(rec.from) } : {}),
+      ...(rec.to ? { to: rec.to.station || rec.to.city || formatPlace(rec.to) } : {}),
+      ...(rec.from ? { fromPlaceId } : {}),
+      ...(rec.to ? { toPlaceId } : {}),
+      ...(rec.arrivalMs ? { arrivalMs: rec.arrivalMs } : {}),
+      ...(rec.vehicleNumber ? { vehicleNumber: rec.vehicleNumber } : {}),
+      ...(rec.confirmationCode ? { confirmationCode: rec.confirmationCode } : {}),
+      ...(rec.bookedAt ? { bookedAt: rec.bookedAt } : {}),
+      ...(carrierPersonId ? { carrier: rec.carrier, carrierPersonId } : {}),
+      ...(rec.extras ? { vendorExtras: rec.extras } : {}),
+    },
+  };
+
+  return { events: [event], persons, places, items: [], topics: [] };
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+function buildTitle(rec) {
+  const vt = rec.vehicleType || "trip";
+  const from = rec.from ? (rec.from.station || rec.from.city || "?") : "";
+  const to = rec.to ? (rec.to.station || rec.to.city || "?") : "";
+  if (from && to) return `${vt}: ${from} → ${to}`;
+  if (to) return `${vt}: → ${to}`;
+  return `${vt}: ${rec.carrier || rec.recordId}`;
+}
+
+function formatPlace(p) {
+  if (!p) return "";
+  const parts = [p.city, p.station, p.name].filter(Boolean);
+  return parts.join(" ");
+}
+
+function placeIdFor(p, adapterName) {
+  // Stable id keyed by station/city/lat-lng so cross-trip places dedup
+  if (!p) return null;
+  const key = (p.station || p.city || p.name || `${p.lat},${p.lng}` || "").toString().toLowerCase();
+  if (!key) return null;
+  return `place-${adapterName}-${slug(key)}`;
+}
+
+function makePlace(id, p, now, source) {
+  return {
+    id,
+    type: "place",
+    subtype: "venue",
+    name: p.station || p.city || p.name || id,
+    address: p.address || undefined,
+    aliases: [p.station, p.city, p.name].filter(Boolean),
+    coordinates: (Number.isFinite(p.lat) && Number.isFinite(p.lng))
+      ? { lat: p.lat, lng: p.lng }
+      : undefined,
+    ingestedAt: now,
+    source,
+    extra: {},
+  };
+}
+
+function slug(s) {
+  return String(s || "")
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^\w一-鿿-]/g, "")
+    .slice(0, 80);
+}
+
+function dedup(arr) {
+  const seen = new Set();
+  const out = [];
+  for (const x of arr) {
+    if (x == null || seen.has(x)) continue;
+    seen.add(x);
+    out.push(x);
+  }
+  return out;
+}
+
+/**
+ * Parse a Chinese date string ("2026年4月15日 14:30") to ms epoch.
+ * Handles 4 common formats; returns null on failure.
+ */
+function parseChineseDateTime(s) {
+  if (typeof s !== "string" || s.length === 0) return null;
+  // YYYY-MM-DD HH:MM:SS or YYYY-MM-DDTHH:MM
+  let m = /^(\d{4})-(\d{1,2})-(\d{1,2})[T ](\d{1,2}):(\d{2})(?::(\d{2}))?/.exec(s);
+  if (m) {
+    return new Date(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6] || 0).getTime();
+  }
+  // YYYY/MM/DD HH:MM
+  m = /^(\d{4})\/(\d{1,2})\/(\d{1,2})\s+(\d{1,2}):(\d{2})/.exec(s);
+  if (m) return new Date(+m[1], +m[2] - 1, +m[3], +m[4], +m[5]).getTime();
+  // 2026年4月15日 14:30
+  m = /^(\d{4})年(\d{1,2})月(\d{1,2})日\s*(\d{1,2}):(\d{2})/.exec(s);
+  if (m) return new Date(+m[1], +m[2] - 1, +m[3], +m[4], +m[5]).getTime();
+  // 2026年4月15日 (no time)
+  m = /^(\d{4})年(\d{1,2})月(\d{1,2})日/.exec(s);
+  if (m) return new Date(+m[1], +m[2] - 1, +m[3]).getTime();
+  // Fallback: Date.parse
+  const t = Date.parse(s);
+  return Number.isFinite(t) ? t : null;
+}
+
+module.exports = {
+  normalizeTravelRecord,
+  parseChineseDateTime,
+  placeIdFor,
+  slug,
+};