@chainlesschain/personal-data-hub 0.4.6 → 0.4.7

package/__tests__/adapters/travel-12306.test.js

@@ -9,6 +9,11 @@ const crypto = require("node:crypto");
 const {
   Train12306Adapter,
   parseRecords,
+  ticketsFromOrder,
+  extractCompletedOrders,
+  extractPendingOrders,
+  parse12306DateTime,
+  parseYyyymmdd,
   NAME,
   VERSION,
   SNAPSHOT_SCHEMA_VERSION,
@@ -62,7 +67,7 @@ function makeSnapshot(events, extra = {}) {
 describe("constants", () => {
   it("exposes name/version/schema", () => {
     expect(NAME).toBe("travel-12306");
-    expect(VERSION).toBe("0.6.0");
+    expect(VERSION).toBe("0.7.0");
     expect(SNAPSHOT_SCHEMA_VERSION).toBe(1);
     expect([...VALID_SNAPSHOT_KINDS]).toEqual(["ticket"]);
   });
@@ -277,3 +282,231 @@ describe("sync + parseRecords — file-import mode", () => {
     await expect(collect(a.sync({}))).rejects.toThrow(/needs opts\.inputPath/);
   });
 });
+
+// ─── §2.5 v0.3 cookie-api live fetch ────────────────────────────────────────
+
+// One raw 12306 order object (queryMyOrder shape) carrying a single ticket.
+function rawOrder(seq, overrides = {}) {
+  return {
+    sequence_no: seq,
+    order_date: "20240315",
+    ticket_total_price: "553.5",
+    tickets: [
+      {
+        ticket_no: "E123456789",
+        passenger_name: "张三",
+        passenger_id_no: "310101199001011234", // last6 = 011234
+        train_code: "G35",
+        from_station_name: "上海虹桥",
+        to_station_name: "北京南",
+        start_train_date_page: "2024-03-20 09:00",
+        arrive_train_date_page: "2024-03-20 14:00",
+        seat_type_name: "二等座",
+        coach_no: "05",
+        seat_no: "12A",
+        ticket_price: "553.5",
+        ...overrides,
+      },
+    ],
+  };
+}
+
+const COOKIE = "tk=abc; JSESSIONID=xyz; RAIL_DEVICEID=dev";
+
+describe("cookie-api helpers", () => {
+  it("extractCompletedOrders tolerates shape variants + junk", () => {
+    expect(extractCompletedOrders({ data: { OrderDTODataList: [1, 2] } })).toEqual([1, 2]);
+    expect(extractCompletedOrders({ data: { orderDTODataList: [3] } })).toEqual([3]);
+    expect(extractCompletedOrders(null)).toEqual([]);
+    expect(extractCompletedOrders({ data: {} })).toEqual([]);
+    expect(extractCompletedOrders("nope")).toEqual([]);
+  });
+
+  it("extractPendingOrders tolerates shape variants + junk", () => {
+    expect(extractPendingOrders({ data: { orderDBList: [1] } })).toEqual([1]);
+    expect(extractPendingOrders({ data: { orderDbList: [2] } })).toEqual([2]);
+    expect(extractPendingOrders({})).toEqual([]);
+  });
+
+  it("ticketsFromOrder flattens tickets with snake/camel fallbacks", () => {
+    const evs = ticketsFromOrder(rawOrder("SEQ1"), true);
+    expect(evs).toHaveLength(1);
+    expect(evs[0]).toMatchObject({
+      kind: "ticket",
+      id: "ticket-SEQ1:0",
+      orderSequenceNo: "SEQ1",
+      ticketNumber: "E123456789",
+      passengerName: "张三",
+      passengerIdLast6: "011234",
+      trainNumber: "G35",
+      fromStation: "上海虹桥",
+      toStation: "北京南",
+      seatTypeName: "二等座",
+      coachNo: "05",
+      seatNo: "12A",
+      ticketPrice: 553.5,
+      isCompleted: true,
+      capturedVia: "cookie-api",
+    });
+    // camelCase + *_page fallbacks
+    const camel = ticketsFromOrder(
+      {
+        sequenceNo: "SEQ2",
+        tickets: [
+          {
+            stationTrainCode: "D7",
+            passengerName: "李四",
+            from_station_name_page: "杭州东",
+            to_station_name_page: "南京南",
+            ticketPrice: "100",
+          },
+        ],
+      },
+      false,
+    );
+    expect(camel[0]).toMatchObject({
+      trainNumber: "D7",
+      fromStation: "杭州东",
+      toStation: "南京南",
+      ticketPrice: 100,
+      isCompleted: false,
+    });
+  });
+
+  it("ticketsFromOrder drops incomplete tickets + bad orders", () => {
+    expect(ticketsFromOrder(null, true)).toEqual([]);
+    expect(ticketsFromOrder({ tickets: [] }, true)).toEqual([]); // no sequence_no
+    // ticket missing passenger / train / stations → dropped
+    const evs = ticketsFromOrder(
+      { sequence_no: "S", tickets: [{ passenger_name: "x" }] },
+      true,
+    );
+    expect(evs).toEqual([]);
+  });
+
+  it("parse12306DateTime handles date / date-time / Chinese / blank", () => {
+    // 2024-03-20 09:00 Shanghai = 2024-03-20 01:00 UTC
+    expect(parse12306DateTime("2024-03-20 09:00")).toBe(Date.UTC(2024, 2, 20, 1, 0));
+    expect(parse12306DateTime("2024-03-20")).toBe(Date.UTC(2024, 2, 19, 16, 0));
+    expect(parse12306DateTime("")).toBeNull();
+    expect(parse12306DateTime(null)).toBeNull();
+    expect(parse12306DateTime("garbage")).toBeNull();
+  });
+
+  it("parseYyyymmdd parses compact dates", () => {
+    expect(parseYyyymmdd("20240315")).toBe(Date.UTC(2024, 2, 14, 16, 0));
+    expect(parseYyyymmdd("2024-03-15")).toBeNull();
+    expect(parseYyyymmdd(null)).toBeNull();
+  });
+});
+
+describe("authenticate — cookie-api mode", () => {
+  it("ok when account.cookies present (username optional)", async () => {
+    const a = new Train12306Adapter({ account: { cookies: COOKIE } });
+    expect(await a.authenticate({})).toEqual({
+      ok: true,
+      account: null,
+      mode: "cookie",
+    });
+  });
+
+  it("carries username when supplied alongside cookies", async () => {
+    const a = new Train12306Adapter({
+      account: { cookies: COOKIE, username: "alice" },
+    });
+    expect((await a.authenticate({})).account).toBe("alice");
+  });
+
+  it("cookie mode takes precedence over file-import", async () => {
+    const a = new Train12306Adapter({
+      account: { cookies: COOKIE },
+      dataPath: "x.json",
+    });
+    expect((await a.authenticate({})).mode).toBe("cookie");
+  });
+});
+
+describe("sync — cookie-api mode", () => {
+  it("yields flattened ticket events from completed + pending", async () => {
+    const calls = [];
+    const fetchFn = async ({ url, cookies, form }) => {
+      calls.push({ url, cookies, form });
+      if (url.includes("NoComplete")) {
+        return { data: { orderDBList: [rawOrder("PEND1")] } };
+      }
+      // single completed page (< PAGE_SIZE → stops)
+      return { data: { OrderDTODataList: [rawOrder("SEQ1")] } };
+    };
+    const a = new Train12306Adapter({ account: { cookies: COOKIE }, fetchFn });
+    const items = await collect(a.sync({}));
+    expect(items.map((i) => i.originalId)).toEqual([
+      "12306:ticket:ticket-SEQ1:0",
+      "12306:ticket:ticket-PEND1:0",
+    ]);
+    expect(items[0].payload.snapshot).toBe(true);
+    expect(items[0].payload.capturedVia).toBe("cookie-api");
+    expect(items[1].payload.isCompleted).toBe(false);
+    // cookie header forwarded + completed form carries pagination params
+    expect(calls[0].cookies).toBe(COOKIE);
+    expect(calls[0].form).toMatchObject({
+      come_from_flag: "my_order",
+      pageSize: "50",
+      pageIndex: "1",
+    });
+  });
+
+  it("paginates completed orders until a short page", async () => {
+    const fetchFn = async ({ url, form }) => {
+      if (url.includes("NoComplete")) return { data: { orderDBList: [] } };
+      const page = parseInt(form.pageIndex, 10);
+      if (page === 1) {
+        // exactly PAGE_SIZE (50) → triggers page 2
+        const orders = Array.from({ length: 50 }, (_, i) => rawOrder(`P1-${i}`));
+        return { data: { OrderDTODataList: orders } };
+      }
+      if (page === 2) return { data: { OrderDTODataList: [rawOrder("P2-0")] } };
+      return { data: { OrderDTODataList: [] } };
+    };
+    const a = new Train12306Adapter({ account: { cookies: COOKIE }, fetchFn });
+    const items = await collect(a.sync({}));
+    expect(items).toHaveLength(51); // 50 + 1, then short page stops
+  });
+
+  it("honors limit + include gate", async () => {
+    const fetchFn = async ({ url }) =>
+      url.includes("NoComplete")
+        ? { data: { orderDBList: [] } }
+        : { data: { OrderDTODataList: [rawOrder("A"), rawOrder("B")] } };
+    const a = new Train12306Adapter({ account: { cookies: COOKIE }, fetchFn });
+    expect(await collect(a.sync({ limit: 1 }))).toHaveLength(1);
+    expect(await collect(a.sync({ include: { ticket: false } }))).toHaveLength(0);
+  });
+
+  it("empty responses yield nothing (expired cookie / no orders)", async () => {
+    const fetchFn = async () => ({});
+    const a = new Train12306Adapter({ account: { cookies: COOKIE }, fetchFn });
+    expect(await collect(a.sync({}))).toHaveLength(0);
+  });
+
+  it("throws when cookie mode active but no fetchFn injected", async () => {
+    const a = new Train12306Adapter({ account: { cookies: COOKIE } });
+    await expect(collect(a.sync({}))).rejects.toThrow(/no fetchFn configured/);
+  });
+
+  it("normalize maps a cookie ticket event → trip with capturedVia", async () => {
+    const fetchFn = async ({ url }) =>
+      url.includes("NoComplete")
+        ? { data: { orderDBList: [] } }
+        : { data: { OrderDTODataList: [rawOrder("SEQ1")] } };
+    const a = new Train12306Adapter({ account: { cookies: COOKIE }, fetchFn });
+    const [item] = await collect(a.sync({}));
+    const batch = a.normalize(item);
+    const ev = batch.events[0];
+    expect(ev.subtype).toBe("trip");
+    expect(ev.content.title).toBe("train: 上海虹桥 → 北京南");
+    expect(ev.extra.vendorExtras).toMatchObject({
+      capturedVia: "cookie-api",
+      idLast6: "011234",
+    });
+  });
+});

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

@@ -1,5 +1,5 @@
 /**
- * §2.5 v0.2 — 12306 (China Railway) ticket adapter, dual-mode.
+ * §2.5 v0.3 — 12306 (China Railway) ticket adapter, tri-mode.
  *
  *   1. snapshot mode (opts.inputPath): in-APK Android cc reads a snapshot
  *      JSON produced by the phone's Kyfw12306LocalCollector. The collector
@@ -8,7 +8,20 @@
  *      no signing), parses each ticket into a structured event, writes JSON.
  *      Desktop-independent. account is OPTIONAL at construction.
  *
- *   2. file-import mode (opts.dataPath, legacy v0.5): user-uploaded JSON
+ *   2. cookie-api mode (opts.account.cookies, v0.3): fetch the SAME two
+ *      kyfw.12306.cn endpoints directly from the hub, so collection no longer
+ *      requires a phone. 12306's order endpoints are **cookie-only, no signing**
+ *      (no _signature / X-Bogus / anti-content SDK — unlike 抖音/拼多多), so no
+ *      signProvider is needed. The actual HTTP call is delegated to an injected
+ *      `fetchFn` (Android in-APK cc → OkHttp / Kyfw12306ApiClient; desktop hub →
+ *      Electron WebView net request) so this module stays a pure-Node parser +
+ *      orchestrator. Completed orders paginate via `pageIndex` (≤50/page, last
+ *      90 days by default); pending orders are a single call. account OPTIONAL —
+ *      the cookie carries identity. Cookie expires after ~30min idle → the
+ *      endpoint returns an HTML login redirect, surfaced by the fetchFn as a
+ *      non-object / empty response, which yields zero events rather than crashing.
+ *
+ *   3. 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.
  *
@@ -40,14 +53,22 @@
 
 const fs = require("node:fs");
 const { normalizeTravelRecord, parseChineseDateTime } = require("../travel-base");
+const { CookieAuth } = require("../shopping-base");
 
 const NAME = "travel-12306";
-const VERSION = "0.6.0";
+const VERSION = "0.7.0"; // §2.5 v0.3 — cookie-api live fetch path
 const SNAPSHOT_SCHEMA_VERSION = 1;
 
 const KIND_TICKET = "ticket";
 const VALID_SNAPSHOT_KINDS = Object.freeze([KIND_TICKET]);
 
+const KYFW_COMPLETED_URL =
+  "https://kyfw.12306.cn/otn/queryOrder/queryMyOrder";
+const KYFW_PENDING_URL =
+  "https://kyfw.12306.cn/otn/queryOrder/queryMyOrderNoComplete";
+const DAYS_90_MS = 90 * 24 * 3600_000;
+const PAGE_SIZE = 50; // 12306 returns ≤50 completed orders per page
+
 class Train12306Adapter {
   constructor(opts = {}) {
     // §2.5 v0.2: account.username OPTIONAL — snapshot mode is stateless and
@@ -56,10 +77,22 @@ class Train12306Adapter {
     this.account = opts.account || null;
     this._dataPath = opts.dataPath || null;
 
+    // §2.5 v0.3 cookie-api mode — activates when account.cookies is supplied.
+    // 12306 order endpoints are cookie-only (no signing), so no signProvider.
+    this._cookieAuth =
+      opts.account && opts.account.cookies
+        ? new CookieAuth({ platform: "12306", cookies: opts.account.cookies })
+        : null;
+    // The actual HTTP call is delegated to an injected fetchFn so this module
+    // stays a pure-Node parser/orchestrator (same seam as the shopping
+    // adapters). fetchFn({ url, cookies, form }) → parsed JSON response object.
+    this._fetchFn = typeof opts.fetchFn === "function" ? opts.fetchFn : defaultFetch;
+
     this.name = NAME;
     this.version = VERSION;
     this.capabilities = [
       "sync:snapshot",
+      "sync:cookie-api",
       "import:json",
       "parse:12306-orders",
     ];
@@ -95,6 +128,18 @@ class Train12306Adapter {
       }
       return { ok: true, mode: "snapshot-file" };
     }
+    if (this._cookieAuth) {
+      const ok = await this._cookieAuth.validate();
+      if (!ok) {
+        return { ok: false, reason: "INVALID_COOKIE", error: "cookies missing" };
+      }
+      // account is OPTIONAL in cookie mode — the 12306 cookie carries identity.
+      return {
+        ok: true,
+        account: (this.account && this.account.username) || null,
+        mode: "cookie",
+      };
+    }
     if (this._dataPath || (ctx && typeof ctx.dataPath === "string")) {
       if (!this.account || !this.account.username) {
         return {
@@ -109,7 +154,7 @@ class Train12306Adapter {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "travel-12306.authenticate: needs opts.inputPath (snapshot mode) OR opts.dataPath (file-import mode)",
+        "travel-12306.authenticate: needs opts.inputPath (snapshot mode) OR opts.account.cookies (cookie-api mode) OR opts.dataPath (file-import mode)",
     };
   }
 
@@ -122,16 +167,95 @@ class Train12306Adapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (this._cookieAuth) {
+      yield* this._syncViaCookie(opts);
+      return;
+    }
     const dataPath = opts.dataPath || this._dataPath;
     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)",
+      "travel-12306.sync: needs opts.inputPath (snapshot mode, Android in-APK cc) OR opts.account.cookies (cookie-api mode, kyfw.12306.cn live fetch) OR opts.dataPath (file-import mode, user-uploaded JSON)",
     );
   }
 
+  /**
+   * §2.5 v0.3 — cookie-api live fetch. Hits the same two kyfw.12306.cn order
+   * endpoints the on-device collector uses (cookie-only, no signing). The
+   * injected fetchFn performs the HTTP; this method paginates, flattens each
+   * order's tickets into snapshot-shaped ticket events, and yields them so the
+   * existing snapshot normalize path applies unchanged.
+   */
+  async *_syncViaCookie(opts = {}) {
+    if (!(await this._cookieAuth.validate())) return;
+    const cookies = this._cookieAuth.toHeader();
+    const include = opts.include || {};
+    if (include[KIND_TICKET] === false) return;
+
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const maxPages =
+      Number.isInteger(opts.maxPages) && opts.maxPages > 0 ? opts.maxPages : 4;
+    const endDateMs = Number.isFinite(opts.endDateMs) ? opts.endDateMs : Date.now();
+    // queryMyOrder caps the range at 90 days; honour an explicit start /
+    // sinceWatermark but never reach back further than 90d in one query.
+    const requestedStart = Number.isFinite(opts.startDateMs)
+      ? opts.startDateMs
+      : opts.sinceWatermark != null
+        ? parseInt(String(opts.sinceWatermark), 10) || endDateMs - DAYS_90_MS
+        : endDateMs - DAYS_90_MS;
+    const startDateMs = Math.max(requestedStart, endDateMs - DAYS_90_MS);
+    const queryStartDate = fmtDateShanghai(startDateMs);
+    const queryEndDate = fmtDateShanghai(endDateMs);
+
+    let emitted = 0;
+
+    // ── completed orders (paginated) ──────────────────────────────────────
+    let page = 1;
+    while (page <= maxPages) {
+      const form = {
+        come_from_flag: "my_order",
+        queryStartDate,
+        queryEndDate,
+        queryType: "1",
+        sequeue_train_name: "",
+        pageSize: String(PAGE_SIZE),
+        pageIndex: String(page),
+        query_where: "G",
+      };
+      const resp = await this._fetchFn({ url: KYFW_COMPLETED_URL, cookies, form });
+      const orders = extractCompletedOrders(resp);
+      if (!orders.length) break;
+      for (const order of orders) {
+        for (const ev of ticketsFromOrder(order, true)) {
+          if (emitted >= limit) return;
+          yield cookieEventToRecord(ev);
+          emitted += 1;
+        }
+      }
+      if (orders.length < PAGE_SIZE) break; // last page
+      page += 1;
+    }
+
+    // ── pending orders (single call, usually empty) ───────────────────────
+    if (emitted < limit) {
+      const resp = await this._fetchFn({
+        url: KYFW_PENDING_URL,
+        cookies,
+        form: {},
+      });
+      for (const order of extractPendingOrders(resp)) {
+        for (const ev of ticketsFromOrder(order, false)) {
+          if (emitted >= limit) return;
+          yield cookieEventToRecord(ev);
+          emitted += 1;
+        }
+      }
+    }
+  }
+
   async *_syncViaSnapshot(opts) {
     const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
     const snapshot = JSON.parse(raw);
@@ -259,6 +383,7 @@ function snapshotEventToRecord(ev) {
       isCompleted: ev.isCompleted,
       idLast6: ev.passengerIdLast6 || undefined,
       orderTotalPrice: ev.orderTotalPrice || undefined,
+      capturedVia: ev.capturedVia || undefined,
     },
   };
 }
@@ -327,9 +452,158 @@ function numberOrParse(v) {
   return null;
 }
 
+// ─── cookie-api (v0.3) helpers ──────────────────────────────────────────────
+
+/** Wrap a cookie-mode ticket event into the same yield shape the snapshot path
+ *  produces, so normalize() routes it through snapshotEventToRecord unchanged. */
+function cookieEventToRecord(ev) {
+  const capturedAt =
+    (Number.isFinite(ev.departureMs) && ev.departureMs) ||
+    (Number.isFinite(ev.orderDateMs) && ev.orderDateMs) ||
+    Date.now();
+  return {
+    adapter: NAME,
+    kind: KIND_TICKET,
+    originalId: stableOriginalId(ev.id || ev.orderSequenceNo),
+    capturedAt,
+    payload: { ...ev, snapshot: true },
+  };
+}
+
+/** Pull the completed-order array out of a queryMyOrder response. */
+function extractCompletedOrders(resp) {
+  const data = resp && typeof resp === "object" ? resp.data : null;
+  if (!data || typeof data !== "object") return [];
+  const list = data.OrderDTODataList || data.orderDTODataList;
+  return Array.isArray(list) ? list : [];
+}
+
+/** Pull the pending-order array out of a queryMyOrderNoComplete response. */
+function extractPendingOrders(resp) {
+  const data = resp && typeof resp === "object" ? resp.data : null;
+  if (!data || typeof data !== "object") return [];
+  const list = data.orderDBList || data.orderDbList;
+  return Array.isArray(list) ? list : [];
+}
+
+/**
+ * Flatten one 12306 order JSON object into per-ticket snapshot events. Mirrors
+ * Kyfw12306ApiClient.parseOrderTickets — one order carries 1..N tickets, each
+ * flattened so the vault maps 1:1 to "I rode train G123 on date D". Field names
+ * are best-effort across endpoint versions (snake_case + camelCase fallbacks).
+ */
+function ticketsFromOrder(order, isCompleted) {
+  if (!order || typeof order !== "object") return [];
+  const sequenceNo = pickStr(order.sequence_no) || pickStr(order.sequenceNo);
+  if (!sequenceNo) return [];
+  const orderDateMs = parseYyyymmdd(pickStr(order.order_date) || pickStr(order.orderDate));
+  const orderTotalPrice = toNum(order.ticket_total_price || order.ticketTotalPrice);
+  const tickets = Array.isArray(order.tickets) ? order.tickets : [];
+  const out = [];
+  tickets.forEach((t, i) => {
+    if (!t || typeof t !== "object") return;
+    const passengerName = pickStr(t.passenger_name) || pickStr(t.passengerName);
+    if (!passengerName) return;
+    const trainNumber = pickStr(t.train_code) || pickStr(t.stationTrainCode);
+    if (!trainNumber) return;
+    const fromStation =
+      pickStr(t.from_station_name) || pickStr(t.from_station_name_page);
+    const toStation =
+      pickStr(t.to_station_name) || pickStr(t.to_station_name_page);
+    if (!fromStation || !toStation) return;
+    const idNo = pickStr(t.passenger_id_no) || pickStr(t.passengerIdNo);
+    const idLast6 = idNo && idNo.length >= 6 ? idNo.slice(-6) : null;
+    out.push({
+      kind: KIND_TICKET,
+      id: `ticket-${sequenceNo}:${i}`,
+      orderSequenceNo: sequenceNo,
+      ticketNumber: pickStr(t.ticket_no) || pickStr(t.ticketNo) || null,
+      passengerName,
+      passengerIdLast6: idLast6 || undefined,
+      trainNumber,
+      fromStation,
+      toStation,
+      departureMs: parse12306DateTime(
+        pickStr(t.start_train_date_page) || pickStr(t.start_train_date),
+      ),
+      arrivalMs: parse12306DateTime(pickStr(t.arrive_train_date_page)),
+      seatTypeName: pickStr(t.seat_type_name) || pickStr(t.seatTypeName) || null,
+      coachNo: pickStr(t.coach_no) || pickStr(t.coachNo) || null,
+      seatNo: pickStr(t.seat_no) || pickStr(t.seatNo) || null,
+      ticketPrice:
+        toNum(t.ticket_price) || toNum(t.ticketPrice) || 0,
+      orderDateMs,
+      orderTotalPrice,
+      isCompleted,
+      capturedVia: "cookie-api",
+    });
+  });
+  return out;
+}
+
+/** Format epoch-ms as a 12306 `yyyy-MM-dd` query date in Asia/Shanghai. */
+function fmtDateShanghai(ms) {
+  const d = new Date(ms + 8 * 3600_000);
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * Parse the date shapes 12306 returns into epoch-ms (Asia/Shanghai):
+ *   "2024-03-20" / "2024-03-20 09:00" / "2024年03月20日 09:00".
+ * Returns null on blank/unparseable so capturedAt can fall back.
+ */
+function parse12306DateTime(s) {
+  if (!s || typeof s !== "string") return null;
+  const str = s.trim();
+  if (!str) return null;
+  if (str.includes("年")) return parseChineseDateTime(str);
+  const m = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2}))?/.exec(str);
+  if (m) {
+    const [, y, mo, d, hh, mm] = m;
+    // Shanghai is UTC+8 → subtract 8h from the wall-clock to get UTC ms.
+    return Date.UTC(+y, +mo - 1, +d, (hh ? +hh : 0) - 8, mm ? +mm : 0);
+  }
+  const t = Date.parse(str);
+  return Number.isFinite(t) ? t : null;
+}
+
+/** Parse a `yyyyMMdd` order date into epoch-ms (Asia/Shanghai). */
+function parseYyyymmdd(s) {
+  if (!s || !/^\d{8}$/.test(s)) return null;
+  return Date.UTC(+s.slice(0, 4), +s.slice(4, 6) - 1, +s.slice(6, 8), -8, 0);
+}
+
+function pickStr(v) {
+  if (v == null) return null;
+  const s = String(v).trim();
+  return s.length > 0 ? s : null;
+}
+
+function toNum(v) {
+  if (v == null) return 0;
+  const n = typeof v === "number" ? v : parseFloat(String(v));
+  return Number.isFinite(n) ? n : 0;
+}
+
+async function defaultFetch(_opts) {
+  // Pure-Node has no HTTP layer; the host (Android cc → Kyfw12306ApiClient /
+  // desktop hub → Electron WebView net) injects a real fetchFn. Mirrors the
+  // shopping adapters' defaultFetch — a missing fetchFn is a wiring bug, not a
+  // runtime data condition, so it throws loudly rather than silently emitting 0.
+  throw new Error("travel-12306: no fetchFn configured for cookie-api mode");
+}
+
 module.exports = {
   Train12306Adapter,
   parseRecords,
+  ticketsFromOrder,
+  extractCompletedOrders,
+  extractPendingOrders,
+  parse12306DateTime,
+  parseYyyymmdd,
   NAME,
   VERSION,
   SNAPSHOT_SCHEMA_VERSION,

package/package.json

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