@chainlesschain/personal-data-hub 0.4.5 → 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/__tests__/shopping-pinduoduo-snapshot.test.js

@@ -10,7 +10,10 @@ const {
   PinduoduoAdapter,
   SNAPSHOT_SCHEMA_VERSION,
   VALID_SNAPSHOT_KINDS,
+  orderToRecord,
+  extractOrders,
 } = require("../lib/adapters/shopping-pinduoduo");
+const { assertAdapter } = require("../lib/adapter-spec");
 const { validateBatch } = require("../lib/batch");
 
 // §2.4c v0.2 — Pinduoduo snapshot-only adapter. Pinduoduo's web API requires
@@ -274,6 +277,13 @@ describe("PinduoduoAdapter snapshot mode", () => {
     expect(raws[0].capturedAt).toBe(ts);
   });
 
+  it("advertises both snapshot and cookie-api capabilities", () => {
+    const a = new PinduoduoAdapter();
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:cookie-api");
+    expect(assertAdapter(a).ok).toBe(true);
+  });
+
   it("snapshotEventToRecord handles snake_case goods_name/goods_price fallback", async () => {
     // Pinduoduo's internal field names use snake_case (goods_name, goods_price,
     // goods_count); the normalizer falls back to those if camelCase is absent.
@@ -300,3 +310,175 @@ describe("PinduoduoAdapter snapshot mode", () => {
     expect(JSON.stringify(batch)).toContain("纸巾");
   });
 });
+
+// §2.4c v0.3 — Pinduoduo cookie-api mode. The actual HTTP + anti_token signing
+// is injected (fetchFn / signProvider) so the adapter stays pure-Node.
+describe("PinduoduoAdapter cookie-api mode", () => {
+  it("authenticate(cookie) ok when uid + cookies present", async () => {
+    const a = new PinduoduoAdapter({ account: { uid: "u-1", cookies: "PDDAccessToken=ok" } });
+    const res = await a.authenticate();
+    expect(res.ok).toBe(true);
+    expect(res.mode).toBe("cookie");
+    expect(res.account).toBe("u-1");
+  });
+
+  it("authenticate(cookie) requires account.uid", async () => {
+    const a = new PinduoduoAdapter({ account: { cookies: "PDDAccessToken=ok" } });
+    const res = await a.authenticate();
+    expect(res.ok).toBe(false);
+    expect(res.reason).toBe("NO_ACCOUNT_UID");
+  });
+
+  it("sync yields normalized records from fetchFn fixture (cents → 元)", async () => {
+    const fetchFn = async () => ({
+      orders: [
+        {
+          order_sn: "PDD-COOKIE-1",
+          mall_name: "拼多多旗舰店",
+          order_status_prompt: "已发货",
+          order_amount: 6200, // 分 → 62.00 元
+          order_time: 1700000000, // sec
+          pay_time: 1700000010,
+          receive_name: "李四",
+          address: "广州市天河区...",
+          goods_list: [
+            { goods_name: "纸巾100抽", goods_number: 5, goods_price: 990, sku_id: "sk1" },
+          ],
+        },
+      ],
+    });
+    const a = new PinduoduoAdapter({
+      account: { uid: "u-1", cookies: "PDDAccessToken=ok" },
+      fetchFn,
+    });
+    const raws = [];
+    for await (const r of a.sync({ sinceWatermark: 0 })) raws.push(r);
+    expect(raws.length).toBe(1);
+    expect(raws[0].originalId).toBe("PDD-COOKIE-1");
+    expect(raws[0].payload.record.totalAmount.value).toBe(62);
+    expect(raws[0].payload.record.items[0].unitPrice).toBe(9.9);
+    expect(raws[0].payload.record.status).toBe("shipped");
+
+    const batch = a.normalize(raws[0]);
+    expect(validateBatch(batch).valid).toBe(true);
+    expect(JSON.stringify(batch)).toContain("纸巾100抽");
+    expect(JSON.stringify(batch)).toContain("李四");
+  });
+
+  it("invokes signProvider and passes antiToken to fetchFn", async () => {
+    let seenAntiToken = null;
+    const signProvider = async () => "ANTI-TOKEN-XYZ";
+    const fetchFn = async (opts) => {
+      seenAntiToken = opts.antiToken;
+      return { orders: [] };
+    };
+    const a = new PinduoduoAdapter({
+      account: { uid: "u-1", cookies: "PDDAccessToken=ok" },
+      fetchFn,
+      signProvider,
+    });
+    for await (const _r of a.sync({ sinceWatermark: 0 })) { /* drain */ }
+    expect(seenAntiToken).toBe("ANTI-TOKEN-XYZ");
+  });
+
+  it("passes antiToken: null when no signProvider configured", async () => {
+    let seen = "unset";
+    const fetchFn = async (opts) => {
+      seen = opts.antiToken;
+      return { orders: [] };
+    };
+    const a = new PinduoduoAdapter({
+      account: { uid: "u-1", cookies: "PDDAccessToken=ok" },
+      fetchFn,
+    });
+    for await (const _r of a.sync({ sinceWatermark: 0 })) { /* drain */ }
+    expect(seen).toBe(null);
+  });
+
+  it("paginates and stops at sinceWatermark", async () => {
+    const pages = {
+      1: [
+        { order_sn: "p1-a", mall_name: "m", order_time: 1700000000, order_amount: 100,
+          goods_list: [] },
+        { order_sn: "p1-b", mall_name: "m", order_time: 1699000000, order_amount: 100,
+          goods_list: [] },
+      ],
+      2: [
+        { order_sn: "p2-a", mall_name: "m", order_time: 1698000000, order_amount: 100,
+          goods_list: [] },
+      ],
+    };
+    const seenPages = [];
+    const fetchFn = async (opts) => {
+      seenPages.push(opts.query.pageNumber);
+      return { orders: pages[opts.query.pageNumber] || [] };
+    };
+    const a = new PinduoduoAdapter({
+      account: { uid: "u-1", cookies: "PDDAccessToken=ok" },
+      fetchFn,
+    });
+    const raws = [];
+    // watermark between 1699000000s and 1700000000s → stops on the older order
+    for await (const r of a.sync({ sinceWatermark: 1699500000 * 1000, pageSize: 2 })) {
+      raws.push(r);
+    }
+    expect(raws.map((r) => r.originalId)).toEqual(["p1-a"]);
+    // stopped inside page 1 — never fetched page 2
+    expect(seenPages).toEqual([1]);
+  });
+
+  it("respects per-kind include opt-out in cookie mode", async () => {
+    let called = false;
+    const fetchFn = async () => {
+      called = true;
+      return { orders: [] };
+    };
+    const a = new PinduoduoAdapter({
+      account: { uid: "u-1", cookies: "PDDAccessToken=ok" },
+      fetchFn,
+    });
+    const raws = [];
+    for await (const r of a.sync({ include: { order: false } })) raws.push(r);
+    expect(raws.length).toBe(0);
+    expect(called).toBe(false);
+  });
+
+  it("orderToRecord maps snake_case PDD fields with cents conversion", () => {
+    const rec = orderToRecord({
+      order_sn: "PDD-9",
+      mall_name: "店铺B",
+      order_status: 4, // numeric → 已完成 → delivered
+      order_amount: 1650,
+      order_time: 1700000000,
+      goods_list: [{ goods_name: "牙刷", goods_number: 2, goods_price: 825 }],
+    });
+    expect(rec.orderId).toBe("PDD-9");
+    expect(rec.merchantName).toBe("店铺B");
+    expect(rec.status).toBe("delivered");
+    expect(rec.totalAmount.value).toBe(16.5);
+    expect(rec.items[0].unitPrice).toBe(8.25);
+    expect(rec.extras.capturedBy).toBe("cookie-api");
+  });
+
+  it("extractOrders tolerates nested response shapes", () => {
+    expect(extractOrders({ orders: [1] })).toEqual([1]);
+    expect(extractOrders({ order_list: [2] })).toEqual([2]);
+    expect(extractOrders({ list: [3] })).toEqual([3]);
+    expect(extractOrders({ result: { order_list: [4] } })).toEqual([4]);
+    expect(extractOrders({ result: { list: [5] } })).toEqual([5]);
+    expect(extractOrders({})).toEqual([]);
+    expect(extractOrders(null)).toEqual([]);
+  });
+
+  it("default fetchFn throws a legible error when cookie mode used without injection", async () => {
+    const a = new PinduoduoAdapter({ account: { uid: "u-1", cookies: "PDDAccessToken=ok" } });
+    let threw = null;
+    try {
+      for await (const _r of a.sync({ sinceWatermark: 0 })) { /* drain */ }
+    } catch (err) {
+      threw = err;
+    }
+    expect(threw).toBeTruthy();
+    expect(String(threw.message)).toMatch(/no fetchFn configured/);
+  });
+});

package/lib/adapters/shopping-pinduoduo/index.js

@@ -1,29 +1,32 @@
 /**
- * §2.4c 购物三联 v0.2 — Pinduoduo (拼多多) adapter, snapshot-only.
+ * §2.4c 购物三联 — Pinduoduo (拼多多) adapter, dual-mode (snapshot + cookie-api).
  *
- * Mirror of shopping-jd / shopping-meituan snapshot-mode pattern, **but
- * without a cookie-mode fallback** because:
+ * v0.3 brings 拼多多 to parity with shopping-taobao / shopping-jd /
+ * shopping-meituan by adding a cookie-api fetch path alongside the existing
+ * snapshot ingest. As with the other shopping adapters the actual HTTP call is
+ * delegated to an injected `fetchFn` (the Android in-APK cc uses OkHttp; the
+ * desktop hub uses an Electron WebView net request) so this module stays a
+ * pure-Node parser + orchestrator.
  *
- *   1. mobile.yangkeduo.com web endpoint `/proxy/api/galerie/transaction/
- *      transaction_list` requires `anti_token` signing computed by client-side
- *      JS (similar to 抖音 X-Bogus). No pure-Node implementation survives
- *      pinduoduo's monthly anti_token rotation.
- *   2. Pinduoduo Android app has no built-in "export orders" feature, so
- *      there's no SAF source-format to parse directly either.
+ *   1. snapshot mode (opts.inputPath): ingest a snapshot JSON produced by a
+ *      browser extension / hand-roll (stateless — account OPTIONAL).
  *
- * v0.2 deliverable = **scaffold + snapshot-mode JSON ingest**. User-facing
- * paths for producing the snapshot JSON:
+ *   2. cookie-api mode (opts.account.cookies): fetch
+ *      `mobile.yangkeduo.com/proxy/api/galerie/transaction/transaction_list`
+ *      via the injected `fetchFn`, paginating with the `pageNumber` cursor and
+ *      stopping at the `sinceWatermark`. account.uid REQUIRED in this mode.
  *
- *   a) Browser extension (planned v0.3) that scrapes yangkeduo.com order
- *      pages while logged in and exports JSON matching this schema.
- *   b) Manual hand-roll (rare; for testing).
+ * ── anti_token signing seam ──────────────────────────────────────────────
+ *   Pinduoduo's transaction_list requires an `anti_token` (a.k.a.
+ *   `anti-content`) computed by client-side JS — analogous to 抖音 X-Bogus.
+ *   No pure-Node implementation survives pinduoduo's anti_token rotation, so
+ *   the signing itself is injected via `opts.signProvider` (or constructor
+ *   `signProvider`). On Android the in-APK WebView JS VM produces the token;
+ *   in tests a stub returns a fixed value. When no signProvider is configured
+ *   the request is still issued with `antiToken: null` — best-effort, the
+ *   endpoint may 403, which surfaces as zero events rather than a crash.
  *
- * UI surface: pinduoduo card appears alongside alipay/taobao/jd/meituan in
- * 推文 §"支付与购物" 大类, with an explicit "v0.2 待用户导出 — 需 web
- * extension 或手抄" banner so user knows the limitation.
- *
- * Snapshot schema (mirrors PinduoduoLocalCollector.SNAPSHOT_SCHEMA_VERSION
- * once the Kotlin collector lands in v0.3+):
+ * Snapshot schema (mirrors PinduoduoLocalCollector.SNAPSHOT_SCHEMA_VERSION):
  *
  *   {
  *     "schemaVersion": 1,
@@ -45,33 +48,46 @@
  *     ]
  *   }
  *
- * Future v0.3: HTML parsing (`Save As Webpage` from `mobile.yangkeduo.com/
+ * Future v0.4: HTML parsing (`Save As Webpage` from `mobile.yangkeduo.com/
  * users/orders.html` — pinduoduo's order list endpoint).
  */
 
 "use strict";
 
 const fs = require("node:fs");
-const { normalizeOrderRecord } = require("../shopping-base");
+const { normalizeOrderRecord, CookieAuth } = require("../shopping-base");
 
 const NAME = "shopping-pinduoduo";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 
 const KIND_ORDER = "order";
 const VALID_SNAPSHOT_KINDS = Object.freeze([KIND_ORDER]);
 
+const PINDUODUO_ORDERS_URL =
+  "https://mobile.yangkeduo.com/proxy/api/galerie/transaction/transaction_list";
+
 class PinduoduoAdapter {
   constructor(opts = {}) {
-    // §2.4c v0.2: account is OPTIONAL — snapshot mode is stateless. There's
-    // no cookie mode at all (anti_token signing path deferred to v0.3+).
+    // §2.4c: account is OPTIONAL — snapshot mode is stateless. Cookie-api mode
+    // activates only when account.cookies is supplied; account.uid is then
+    // required (checked at sync time).
     this.account = opts.account || null;
+    this._cookieAuth =
+      opts.account && opts.account.cookies
+        ? new CookieAuth({ platform: "pinduoduo", cookies: opts.account.cookies })
+        : null;
+    this._fetchFn = typeof opts.fetchFn === "function" ? opts.fetchFn : defaultFetch;
+    // anti_token signing seam — see file header. Async fn({ url, query,
+    // cookies }) → string|null. When absent, requests carry antiToken: null.
+    this._signProvider =
+      typeof opts.signProvider === "function" ? opts.signProvider : null;
 
     this.name = NAME;
     this.version = VERSION;
-    this.capabilities = ["sync:snapshot", "parse:pinduoduo-orders"];
-    this.extractMode = "user-export";
-    this.rateLimits = {};
+    this.capabilities = ["sync:snapshot", "sync:cookie-api", "parse:pinduoduo-orders"];
+    this.extractMode = "web-api";
+    this.rateLimits = { perMinute: 8, perDay: 200 };
     this.dataDisclosure = {
       fields: [
         "pinduoduo:order_sn / mall_name / goods_list / order_amount / address",
@@ -99,15 +115,33 @@ class PinduoduoAdapter {
       }
       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" };
+      if (!this.account || !this.account.uid) {
+        return {
+          ok: false,
+          reason: "NO_ACCOUNT_UID",
+          message: "cookie-api mode requires account.uid",
+        };
+      }
+      return { ok: true, account: this.account.uid, mode: "cookie" };
+    }
     return {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "PinduoduoAdapter.authenticate: needs opts.inputPath (snapshot mode — no cookie mode in v0.2)",
+        "PinduoduoAdapter.authenticate: needs opts.inputPath (snapshot mode) OR opts.account.cookies (cookie-api mode — anti_token signing via signProvider)",
     };
   }
 
   async healthCheck() {
+    if (this._cookieAuth) {
+      const r = await this.authenticate();
+      return r.ok
+        ? { ok: true, lastChecked: Date.now() }
+        : { ok: false, reason: r.reason, error: r.error };
+    }
     return { ok: true, lastChecked: Date.now() };
   }
 
@@ -116,21 +150,25 @@ class PinduoduoAdapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (this._cookieAuth) {
+      yield* this._syncViaCookie(opts);
+      return;
+    }
     throw new Error(
-      "PinduoduoAdapter.sync: needs opts.inputPath (snapshot mode; no cookie/api mode in v0.2 because pinduoduo's web API requires anti_token JS-VM signing)",
+      "PinduoduoAdapter.sync: needs opts.inputPath (snapshot mode) OR opts.account.cookies (cookie-api mode; pinduoduo's web API requires anti_token signing supplied via opts.signProvider)",
     );
   }
 
   async *_syncViaSnapshot(opts) {
     const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
     // v0.2 explicit JSON-only. HTML parsing (SAF-exported webpage from
-    // yangkeduo.com order list) is future v0.3 work.
+    // yangkeduo.com order list) is future v0.4 work.
     let snapshot;
     try {
       snapshot = JSON.parse(raw);
     } catch (err) {
       throw new Error(
-        `shopping-pinduoduo.sync: snapshot must be JSON (v0.3 will add HTML parsing). Got parse error: ${err.message}`,
+        `shopping-pinduoduo.sync: snapshot must be JSON (v0.4 will add HTML parsing). Got parse error: ${err.message}`,
       );
     }
     if (
@@ -184,11 +222,77 @@ class PinduoduoAdapter {
     }
   }
 
+  async *_syncViaCookie(opts = {}) {
+    if (!this.account || !this.account.uid) {
+      throw new Error(
+        "PinduoduoAdapter._syncViaCookie: account.uid required (set via new PinduoduoAdapter({ account: { uid, cookies } }))",
+      );
+    }
+    if (!(await this._cookieAuth.validate())) return;
+    const sinceMs =
+      opts.sinceWatermark != null
+        ? parseInt(String(opts.sinceWatermark), 10) || 0
+        : Date.now() - 365 * 24 * 3600_000; // default last year
+    const pageSize = Number.isFinite(opts.pageSize) ? opts.pageSize : 10;
+    const include = opts.include || {};
+    if (include[KIND_ORDER] === false) return;
+
+    let pageNumber = 1;
+    while (true) {
+      const query = { pageNumber, pageSize, ts: Date.now() };
+      // anti_token signing seam — best-effort. null when no signProvider.
+      let antiToken = null;
+      if (this._signProvider) {
+        antiToken = await this._signProvider({
+          url: PINDUODUO_ORDERS_URL,
+          query,
+          cookies: this._cookieAuth.toHeader(),
+        });
+      }
+      const resp = await this._fetchFn({
+        url: PINDUODUO_ORDERS_URL,
+        cookies: this._cookieAuth.toHeader(),
+        antiToken,
+        query,
+      });
+      const orders = extractOrders(resp);
+      if (!orders.length) break;
+      let pageHasNew = false;
+      let reachedWatermark = false;
+      for (const raw of orders) {
+        const rec = orderToRecord(raw);
+        if (!rec) continue;
+        if (rec.placedAt && rec.placedAt < sinceMs) {
+          reachedWatermark = true; // everything from here on is older
+          break;
+        }
+        pageHasNew = true;
+        yield {
+          adapter: NAME,
+          originalId: rec.orderId,
+          capturedAt: rec.paidAt || rec.placedAt || Date.now(),
+          payload: { record: rec },
+        };
+      }
+      // Stop once we've crossed the watermark, drained the page, or the page
+      // came back short (last page).
+      if (reachedWatermark || !pageHasNew || orders.length < pageSize) break;
+      pageNumber += 1;
+    }
+  }
+
   normalize(raw) {
     if (!raw || !raw.payload) {
       throw new Error("PinduoduoAdapter.normalize: payload missing");
     }
-    // Snapshot-mode only — payload carries fields directly on the event.
+    // Cookie-api mode wraps a normalized record under payload.record; snapshot
+    // mode carries the raw event fields directly on the payload.
+    if (raw.payload.record) {
+      return normalizeOrderRecord(raw.payload.record, {
+        adapterName: NAME,
+        adapterVersion: VERSION,
+      });
+    }
     const rec = snapshotEventToRecord(raw.payload);
     return normalizeOrderRecord(rec, {
       adapterName: NAME,
@@ -208,6 +312,104 @@ function stableOriginalId(kind, id) {
   return `pinduoduo:${kind}:${safe}`;
 }
 
+/**
+ * Pull the order array out of a transaction_list response. Pinduoduo nests it
+ * under different keys across endpoint versions; the injected fetchFn may also
+ * pre-flatten to `{ orders }`. Tolerant of all common shapes.
+ */
+function extractOrders(resp) {
+  if (!resp || typeof resp !== "object") return [];
+  if (Array.isArray(resp.orders)) return resp.orders;
+  if (Array.isArray(resp.order_list)) return resp.order_list;
+  if (Array.isArray(resp.list)) return resp.list;
+  if (resp.result && Array.isArray(resp.result.order_list)) return resp.result.order_list;
+  if (resp.result && Array.isArray(resp.result.list)) return resp.result.list;
+  return [];
+}
+
+/**
+ * Map one pinduoduo transaction_list order object → vendor-neutral OrderRecord.
+ * Pinduoduo amounts are in 分 (cents); converted to 元 here. Field names are
+ * best-effort across endpoint versions (camelCase + snake_case fallbacks).
+ */
+function orderToRecord(o) {
+  if (!o || typeof o !== "object") return null;
+  const orderId = o.order_sn || o.orderSn || o.orderId || o.id;
+  if (!orderId) return null;
+  const merchant = o.mall_name || o.mallName || o.merchantName || o.shop_name || "拼多多";
+
+  const items = [];
+  const rawItems = o.goods_list || o.order_goods || o.goodsList || o.items || [];
+  for (const it of Array.isArray(rawItems) ? rawItems : []) {
+    if (!it) continue;
+    items.push({
+      name: it.goods_name || it.goodsName || it.name || it.skuName,
+      quantity: parseInt(it.goods_number || it.goods_count || it.quantity || 1, 10),
+      unitPrice: centsToYuan(it.goods_price || it.goodsPrice || it.unitPrice || 0),
+      sku: it.sku_id || it.skuId || it.goods_id || it.sku || null,
+    });
+  }
+
+  return {
+    vendorId: "pinduoduo",
+    orderId: String(orderId),
+    placedAt: parseTime(o.order_time || o.create_at || o.createAt || o.order_create_at),
+    paidAt: parseTime(o.pay_time || o.payTime || o.group_order_pay_time),
+    status: mapStatus(pickStatusText(o)),
+    merchantName: merchant,
+    totalAmount: {
+      value: centsToYuan(o.order_amount || o.orderAmount || o.pay_amount || o.total_amount || 0),
+      currency: "CNY",
+    },
+    items,
+    recipient: o.receive_name || o.receiver || o.recipient || null,
+    shippingAddress: o.address || o.receive_address || o.shippingAddress || null,
+    trackingNumber: o.tracking_number || o.waybill_no || o.trackingNumber || null,
+    extras: { capturedBy: "cookie-api", platform: "pinduoduo" },
+  };
+}
+
+/**
+ * Pinduoduo carries a human-readable status under several keys; prefer text
+ * over the numeric `order_status` code so mapStatus's keyword match works.
+ */
+function pickStatusText(o) {
+  const text =
+    o.order_status_prompt ||
+    o.orderStatusPrompt ||
+    o.status_prompt ||
+    o.statusPrompt ||
+    o.status_desc ||
+    null;
+  if (text) return text;
+  // Fall back to the numeric order_status code (best-effort PDD mapping).
+  const code = o.order_status != null ? o.order_status : o.orderStatus;
+  switch (Number(code)) {
+    case 1:
+      return "待付款";
+    case 2:
+      return "待发货";
+    case 3:
+      return "已发货";
+    case 4:
+      return "已完成";
+    case 5:
+    case 6:
+      return "已关闭";
+    default:
+      return o.status != null ? String(o.status) : "";
+  }
+}
+
+function centsToYuan(v) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return 0;
+  // Snapshot/test inputs may already be 元 with a decimal point; treat any
+  // non-integer as 元, integers as 分.
+  if (!Number.isInteger(n)) return n;
+  return Math.round(n) / 100;
+}
+
 function snapshotEventToRecord(ev) {
   const items = [];
   const rawItems = Array.isArray(ev.items) ? ev.items : [];
@@ -266,8 +468,14 @@ function mapStatus(s) {
   return "placed";
 }
 
+async function defaultFetch(_opts) {
+  throw new Error("PinduoduoAdapter: no fetchFn configured");
+}
+
 module.exports = {
   PinduoduoAdapter,
+  orderToRecord,
+  extractOrders,
   NAME,
   VERSION,
   SNAPSHOT_SCHEMA_VERSION,

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.5",
+  "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",