@chainlesschain/personal-data-hub 0.3.0 → 0.3.1

package/__tests__/travel-adapters.test.js

@@ -103,7 +103,84 @@ describe("Train12306Adapter", () => {
     const r = assertAdapter(a);
     expect(r.ok).toBe(true);
     if (!r.ok) console.log(r.errors);
-    expect(a.extractMode).toBe("file-import");
+    // v0.2: snapshot mode is the primary path (in-APK collector); legacy
+    // file-import preserved for backward compat. extractMode reports
+    // "device-pull" to match the snapshot-based social adapters family.
+    expect(a.extractMode).toBe("device-pull");
+  });
+
+  it("v0.2 snapshot mode — sync yields ticket events from snapshot file", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "12306-snap-"));
+    const inputPath = path.join(dir, "travel-12306.json");
+    fs.writeFileSync(inputPath, JSON.stringify({
+      schemaVersion: 1,
+      snapshottedAt: 1_700_000_000_000,
+      vendor: "12306",
+      events: [
+        {
+          kind: "ticket",
+          id: "ticket-EE123:0",
+          capturedAt: 1_700_001_000_000,
+          orderSequenceNo: "EE123",
+          ticketNumber: "T-1",
+          passengerName: "张三",
+          passengerIdLast6: "123456",
+          trainNumber: "G123",
+          fromStation: "上海虹桥",
+          toStation: "北京南",
+          departureMs: 1_700_001_000_000,
+          arrivalMs: 1_700_018_000_000,
+          seatTypeName: "二等座",
+          coachNo: "05",
+          seatNo: "12A",
+          ticketPrice: 553.5,
+          orderDateMs: 1_699_950_000_000,
+          orderTotalPrice: 553.5,
+          isCompleted: true,
+        },
+      ],
+    }));
+    try {
+      const a = new Train12306Adapter(); // snapshot mode — no account needed
+      const auth = await a.authenticate({ inputPath });
+      expect(auth.ok).toBe(true);
+      expect(auth.mode).toBe("snapshot-file");
+      const raws = [];
+      for await (const r of a.sync({ inputPath })) raws.push(r);
+      expect(raws).toHaveLength(1);
+      expect(raws[0].adapter).toBe("travel-12306");
+      expect(raws[0].kind).toBe("ticket");
+      expect(raws[0].originalId).toMatch(/^12306:ticket:/);
+      expect(raws[0].payload.snapshot).toBe(true);
+      const batch = a.normalize(raws[0]);
+      const v = validateBatch(batch);
+      expect(v.valid).toBe(true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("v0.2 snapshot mode — rejects schemaVersion mismatch", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "12306-snap-bad-"));
+    const inputPath = path.join(dir, "travel-12306.json");
+    fs.writeFileSync(inputPath, JSON.stringify({
+      schemaVersion: 99,
+      snapshottedAt: Date.now(),
+      events: [],
+    }));
+    try {
+      const a = new Train12306Adapter();
+      let threw = null;
+      try {
+        for await (const _r of a.sync({ inputPath })) { /* drain */ }
+      } catch (err) {
+        threw = err;
+      }
+      expect(threw).toBeTruthy();
+      expect(String(threw.message)).toMatch(/schemaVersion mismatch/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
   });
 
   it("parseRecords parses JSON array", () => {
@@ -131,7 +208,7 @@ describe("Train12306Adapter", () => {
     expect(recs).toHaveLength(2);
   });
 
-  it("sync yields raw events from a file", async () => {
+  it("legacy file-import mode — yields raw events from JSON file", async () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "12306-"));
     const dataPath = path.join(dir, "12306.json");
     fs.writeFileSync(dataPath, JSON.stringify([
@@ -151,9 +228,24 @@ describe("Train12306Adapter", () => {
     }
   });
 
-  it("rejects missing account.username", () => {
-    expect(() => new Train12306Adapter({})).toThrow();
-    expect(() => new Train12306Adapter({ account: {} })).toThrow(/username/);
+  it("v0.2: account.username optional at construction (snapshot mode is stateless)", () => {
+    // Previously threw — v0.2 lifts this since snapshot mode doesn't need it.
+    expect(() => new Train12306Adapter({})).not.toThrow();
+    expect(() => new Train12306Adapter()).not.toThrow();
+  });
+
+  it("authenticate without inputPath OR dataPath returns NO_INPUT", async () => {
+    const a = new Train12306Adapter();
+    const r = await a.authenticate({});
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe("NO_INPUT");
+  });
+
+  it("authenticate file-import mode without account.username returns NO_ACCOUNT_USERNAME", async () => {
+    const a = new Train12306Adapter({ dataPath: "/no/such/file.json" });
+    const r = await a.authenticate({});
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe("NO_ACCOUNT_USERNAME");
   });
 });
 

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,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainlesschain/personal-data-hub",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Personal Data Hub — UnifiedSchema + validators + KG ingest helpers for the data-back-to-the-individual middleware",
   "type": "commonjs",
   "main": "lib/index.js",