@chainlesschain/personal-data-hub 0.1.0 → 0.2.0

package/__tests__/shopping-adapters.test.js

@@ -0,0 +1,296 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  normalizeOrderRecord,
+  CookieAuth,
+  TaobaoAdapter,
+  JdAdapter,
+  MeituanAdapter,
+} = require("../lib");
+const { orderToRecord: taobaoOrderToRecord, parseTaobaoTime } = require("../lib/adapters/shopping-taobao");
+const { orderToRecord: jdOrderToRecord } = require("../lib/adapters/shopping-jd");
+const { orderToRecord: meituanOrderToRecord } = require("../lib/adapters/shopping-meituan");
+const { assertAdapter } = require("../lib/adapter-spec");
+const { validateBatch } = require("../lib/batch");
+
+// ─── normalizeOrderRecord ───────────────────────────────────────────────
+
+describe("normalizeOrderRecord", () => {
+  it("produces Event + merchant Person + Item entities", () => {
+    const rec = {
+      vendorId: "taobao",
+      orderId: "ORD-1",
+      placedAt: 1700000000000,
+      paidAt: 1700000010000,
+      status: "delivered",
+      merchantName: "Apple官方旗舰店",
+      totalAmount: { value: 9999, currency: "CNY" },
+      items: [
+        { name: "iPhone 17 Pro 256GB", quantity: 1, unitPrice: 9999 },
+      ],
+      recipient: "张三",
+      shippingAddress: "上海市某区某路",
+      trackingNumber: "SF1234567",
+    };
+    const b = normalizeOrderRecord(rec, { adapterName: "shopping-taobao", adapterVersion: "0.5.0" });
+    expect(b.events).toHaveLength(1);
+    expect(b.events[0].subtype).toBe("order");
+    expect(b.events[0].content.amount.value).toBe(9999);
+    expect(b.events[0].content.amount.direction).toBe("out");
+    expect(b.events[0].extra.merchantOrderNumber).toBe("ORD-1"); // cross-source link
+    expect(b.events[0].extra.orderStatus).toBe("delivered");
+    expect(b.events[0].extra.trackingNumber).toBe("SF1234567");
+    expect(b.persons).toHaveLength(1);
+    expect(b.persons[0].subtype).toBe("merchant");
+    expect(b.items).toHaveLength(1);
+    expect(b.items[0].name).toBe("iPhone 17 Pro 256GB");
+    const v = validateBatch(b);
+    expect(v.valid).toBe(true);
+  });
+
+  it("refund status maps to refund subtype + amount in", () => {
+    const rec = {
+      vendorId: "taobao", orderId: "X", placedAt: Date.now(),
+      status: "refunded", merchantName: "Test",
+      totalAmount: { value: 100, currency: "CNY" },
+    };
+    const b = normalizeOrderRecord(rec, { adapterName: "shopping-taobao" });
+    expect(b.events[0].subtype).toBe("refund");
+    expect(b.events[0].content.amount.direction).toBe("in");
+  });
+
+  it("cancelled status maps to cancelled subtype", () => {
+    const rec = {
+      vendorId: "jd", orderId: "X", placedAt: Date.now(),
+      status: "已取消", merchantName: "Test",
+    };
+    const b = normalizeOrderRecord(rec, { adapterName: "shopping-jd" });
+    expect(b.events[0].subtype).toBe("cancelled");
+  });
+
+  it("requires orderId + merchantName", () => {
+    expect(() => normalizeOrderRecord({})).toThrow();
+    expect(() => normalizeOrderRecord({ orderId: "x" })).toThrow();
+  });
+});
+
+// ─── CookieAuth ──────────────────────────────────────────────────────────
+
+describe("CookieAuth", () => {
+  it("constructor requires platform", () => {
+    expect(() => new CookieAuth({})).toThrow(/platform/);
+  });
+
+  it("toHeader returns null for empty", () => {
+    const ca = new CookieAuth({ platform: "taobao" });
+    expect(ca.toHeader()).toBeNull();
+  });
+
+  it("toHeader returns the cookie string when set", () => {
+    const ca = new CookieAuth({ platform: "taobao", cookies: "k1=v1; k2=v2" });
+    expect(ca.toHeader()).toBe("k1=v1; k2=v2");
+  });
+
+  it("getCookieValue reads single cookie", () => {
+    const ca = new CookieAuth({ platform: "taobao", cookies: "k1=v1; k2=v%20space" });
+    expect(ca.getCookieValue("k1")).toBe("v1");
+    expect(ca.getCookieValue("k2")).toBe("v space"); // decoded
+    expect(ca.getCookieValue("missing")).toBeNull();
+  });
+
+  it("validate returns false for empty", async () => {
+    const ca = new CookieAuth({ platform: "taobao" });
+    expect(await ca.validate()).toBe(false);
+  });
+
+  it("validate uses injected validator", async () => {
+    const ca = new CookieAuth({
+      platform: "taobao",
+      cookies: "k=v",
+      validator: async (c) => c.includes("good"),
+    });
+    expect(await ca.validate()).toBe(false);
+    ca.setCookies("good=ok");
+    expect(await ca.validate()).toBe(true);
+  });
+});
+
+// ─── TaobaoAdapter ──────────────────────────────────────────────────────
+
+describe("TaobaoAdapter", () => {
+  it("contract conformance", () => {
+    const a = new TaobaoAdapter({ account: { userId: "u-1", cookies: "k=v" } });
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.extractMode).toBe("web-api");
+  });
+
+  it("orderToRecord maps Taobao fields", () => {
+    const o = {
+      bizOrderId: "TB-1",
+      sellerNick: "Apple官方旗舰店",
+      createTime: 1700000000,
+      payTime: 1700000010,
+      statusText: "已发货",
+      actualFee: "9999.00",
+      subOrders: [
+        { itemTitle: "iPhone 17", buyCount: 1, itemPrice: "9999" },
+      ],
+      receiverName: "张三",
+      fullAddress: "上海...",
+    };
+    const rec = taobaoOrderToRecord(o);
+    expect(rec.orderId).toBe("TB-1");
+    expect(rec.merchantName).toBe("Apple官方旗舰店");
+    expect(rec.status).toBe("shipped");
+    expect(rec.totalAmount.value).toBe(9999);
+    expect(rec.items).toHaveLength(1);
+    expect(rec.placedAt).toBeGreaterThan(0);
+  });
+
+  it("parseTaobaoTime upgrades seconds → ms", () => {
+    expect(parseTaobaoTime(1700000000)).toBe(1700000000000);
+    expect(parseTaobaoTime(1700000000000)).toBe(1700000000000);
+    expect(parseTaobaoTime("2026-04-15T10:00:00Z")).toBeGreaterThan(0);
+  });
+
+  it("sync yields raw events from fetchFn fixture", async () => {
+    const fetchFn = async () => ({
+      orders: [
+        {
+          bizOrderId: "TB-2", sellerNick: "Test",
+          createTime: 1700000000, payTime: 1700000010,
+          statusText: "已签收", actualFee: "100",
+          subOrders: [{ itemTitle: "Item A", buyCount: 1, itemPrice: "100" }],
+        },
+      ],
+    });
+    const a = new TaobaoAdapter({
+      account: { userId: "u-1", cookies: "valid=cookie" },
+      fetchFn,
+    });
+    const raws = [];
+    for await (const r of a.sync({ pageSize: 20, sinceWatermark: 0 })) raws.push(r);
+    expect(raws).toHaveLength(1);
+    const batch = a.normalize(raws[0]);
+    expect(validateBatch(batch).valid).toBe(true);
+  });
+
+  it("sync no-ops on invalid cookies", async () => {
+    const a = new TaobaoAdapter({ account: { userId: "u-1" } }); // no cookies
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    expect(raws).toHaveLength(0);
+  });
+});
+
+// ─── JdAdapter ───────────────────────────────────────────────────────────
+
+describe("JdAdapter", () => {
+  it("contract conformance", () => {
+    const a = new JdAdapter({ account: { pin: "p1", cookies: "k=v" } });
+    expect(assertAdapter(a).ok).toBe(true);
+  });
+
+  it("orderToRecord maps JD fields", () => {
+    const o = {
+      orderId: "JD-1",
+      orderTotalPrice: "1999.00",
+      orderStartTime: "2026-04-15 10:00:00",
+      orderStatusText: "已收货",
+      venderName: "京东自营",
+      productList: [
+        { productName: "Kindle", productPrice: "999", productQuantity: 2 },
+      ],
+      consigneeName: "张三",
+    };
+    const rec = jdOrderToRecord(o);
+    expect(rec.orderId).toBe("JD-1");
+    expect(rec.merchantName).toBe("京东自营");
+    expect(rec.status).toBe("delivered");
+    expect(rec.totalAmount.value).toBe(1999);
+    expect(rec.items[0].name).toBe("Kindle");
+    expect(rec.items[0].quantity).toBe(2);
+  });
+
+  it("sync + normalize end-to-end", async () => {
+    const fetchFn = async () => ({
+      orders: [
+        {
+          orderId: "JD-2", orderTotalPrice: "299",
+          orderStartTime: "2026-04-15 10:00:00",
+          orderStatusText: "已发货",
+          venderName: "京东",
+          productList: [{ productName: "鼠标", productPrice: "299", productQuantity: 1 }],
+        },
+      ],
+    });
+    const a = new JdAdapter({
+      account: { pin: "p1", cookies: "v=ok" },
+      fetchFn,
+    });
+    const raws = [];
+    for await (const r of a.sync({ sinceWatermark: 0 })) raws.push(r);
+    expect(raws).toHaveLength(1);
+    expect(validateBatch(a.normalize(raws[0])).valid).toBe(true);
+  });
+});
+
+// ─── MeituanAdapter ──────────────────────────────────────────────────────
+
+describe("MeituanAdapter", () => {
+  it("contract conformance", () => {
+    const a = new MeituanAdapter({ account: { userId: "u-1", cookies: "k=v" } });
+    expect(assertAdapter(a).ok).toBe(true);
+  });
+
+  it("orderToRecord maps Meituan 外卖 fields", () => {
+    const o = {
+      orderId: "MT-1",
+      poiName: "麦当劳(中山公园店)",
+      orderTime: 1700000000,
+      payTime: 1700000010,
+      statusDesc: "已送达",
+      totalPrice: "45.50",
+      dishes: [
+        { name: "巨无霸套餐", quantity: 1, price: "45.5" },
+      ],
+      recipientAddress: "上海...",
+    };
+    const rec = meituanOrderToRecord(o, "waimai");
+    expect(rec.orderId).toBe("MT-1");
+    expect(rec.merchantName).toBe("麦当劳(中山公园店)");
+    expect(rec.status).toBe("delivered");
+    expect(rec.totalAmount.value).toBe(45.5);
+    expect(rec.extras.platform).toBe("waimai");
+  });
+
+  it("sync iterates multiple platforms", async () => {
+    const seen = [];
+    const fetchFn = async (opts) => {
+      seen.push(opts.query.platform);
+      return {
+        orders: [
+          {
+            orderId: `MT-${opts.query.platform}`,
+            poiName: "Test",
+            orderTime: 1700000000,
+            statusDesc: "已完成",
+            totalPrice: "10",
+            dishes: [{ name: "x", quantity: 1, price: "10" }],
+          },
+        ],
+      };
+    };
+    const a = new MeituanAdapter({
+      account: { userId: "u-1", cookies: "v=ok" },
+      fetchFn,
+    });
+    const raws = [];
+    for await (const r of a.sync({ sinceWatermark: 0, platforms: ["waimai", "groupbuy"] })) raws.push(r);
+    expect(seen).toContain("waimai");
+    expect(seen).toContain("groupbuy");
+    expect(raws.length).toBeGreaterThan(0);
+  });
+});

package/__tests__/sidecar-contacts-cross-validate.test.js

@@ -0,0 +1,163 @@
+"use strict";
+
+/**
+ * Cross-validate that Persons produced by the Python sidecar's
+ * `system.parse_contacts` method pass the hub-side UnifiedSchema validator.
+ *
+ * Without this test, sidecar and hub can drift silently: sidecar emits
+ * fields the schema rejects, or skips required ones. Run against a real
+ * sidecar subprocess + synthesized contacts2.db.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+
+const { SidecarSupervisor } = require("../lib/sidecar");
+const { validatePerson } = require("../lib/schemas");
+const Database = require("better-sqlite3-multiple-ciphers");
+
+const SIDECAR_ROOT = path.resolve(
+  __dirname,
+  "..",
+  "..",
+  "personal-data-hub-bridge",
+);
+
+let pythonAvailable = true;
+try {
+  const probe = spawnSync(
+    process.env.FORENSICS_BRIDGE_PYTHON || "python",
+    ["--version"],
+    { stdio: "ignore" },
+  );
+  if (probe.status !== 0) pythonAvailable = false;
+} catch (_err) {
+  pythonAvailable = false;
+}
+
+const describePy = pythonAvailable ? describe : describe.skip;
+
+function seedFixtureContactsDb(dbPath) {
+  const db = new Database(dbPath);
+  try {
+    db.exec(`
+      CREATE TABLE raw_contacts (
+        _id INTEGER PRIMARY KEY,
+        display_name TEXT,
+        starred INTEGER DEFAULT 0,
+        deleted INTEGER DEFAULT 0
+      );
+      CREATE TABLE mimetypes (
+        _id INTEGER PRIMARY KEY,
+        mimetype TEXT NOT NULL UNIQUE
+      );
+      CREATE TABLE data (
+        _id INTEGER PRIMARY KEY,
+        raw_contact_id INTEGER NOT NULL,
+        mimetype_id INTEGER NOT NULL,
+        data1 TEXT
+      );
+    `);
+    const mimetypes = {
+      "vnd.android.cursor.item/phone_v2": 5,
+      "vnd.android.cursor.item/email_v2": 1,
+      "vnd.android.cursor.item/organization": 4,
+      "vnd.android.cursor.item/note": 10,
+    };
+    const insertMime = db.prepare(
+      "INSERT INTO mimetypes (_id, mimetype) VALUES (?, ?)",
+    );
+    for (const [mt, mid] of Object.entries(mimetypes)) insertMime.run(mid, mt);
+
+    const insertContact = db.prepare(
+      "INSERT INTO raw_contacts (_id, display_name, starred, deleted) VALUES (?, ?, ?, 0)",
+    );
+    insertContact.run(1, "妈妈", 1);
+    insertContact.run(2, "张三", 0);
+
+    const insertData = db.prepare(
+      "INSERT INTO data (raw_contact_id, mimetype_id, data1) VALUES (?, ?, ?)",
+    );
+    insertData.run(1, mimetypes["vnd.android.cursor.item/phone_v2"], "13800001111");
+    insertData.run(1, mimetypes["vnd.android.cursor.item/phone_v2"], "13900002222");
+    insertData.run(1, mimetypes["vnd.android.cursor.item/email_v2"], "mom@example.com");
+    insertData.run(2, mimetypes["vnd.android.cursor.item/phone_v2"], "13711112222");
+  } finally {
+    db.close();
+  }
+}
+
+describePy("sidecar.system.parse_contacts × hub.validatePerson", () => {
+  let supervisor;
+  let tmpDir;
+  let dbPath;
+
+  beforeAll(async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "phdb-sidecar-contacts-"));
+    dbPath = path.join(tmpDir, "contacts2.db");
+    seedFixtureContactsDb(dbPath);
+
+    supervisor = new SidecarSupervisor({
+      command: process.env.FORENSICS_BRIDGE_PYTHON || "python",
+      args: ["-u", "-m", "forensics_bridge.ipc_server"],
+      cwd: SIDECAR_ROOT,
+      healthCheckIntervalMs: 0,
+      env: { PYTHONPATH: SIDECAR_ROOT },
+    });
+    await supervisor.start({ readyTimeoutMs: 8_000 });
+  }, 15_000);
+
+  afterAll(async () => {
+    if (supervisor) await supervisor.stop({ graceMs: 1500 });
+    if (tmpDir) {
+      try {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      } catch (_err) {
+        /* best effort */
+      }
+    }
+  });
+
+  it("emits Persons that pass hub UnifiedSchema validation", async () => {
+    const persons = [];
+    const result = await supervisor.invoke(
+      "system.parse_contacts",
+      { data_path: dbPath, device_serial: "24115RA8EC-test" },
+      {
+        timeoutMs: 10_000,
+        onChunk: (batch) => {
+          for (const p of batch.persons || []) persons.push(p);
+        },
+      },
+    );
+
+    expect(result.status).toBe("ok");
+    expect(result.totalPersons).toBe(2);
+    expect(persons).toHaveLength(2);
+
+    for (const person of persons) {
+      const validation = validatePerson(person);
+      if (!validation.valid) {
+        // Dump the offender so CI failures are debuggable without re-running.
+        console.error(
+          "validatePerson failed for",
+          JSON.stringify(person, null, 2),
+          "errors:",
+          validation.errors,
+        );
+      }
+      expect(validation.valid).toBe(true);
+      expect(validation.errors).toEqual([]);
+    }
+
+    // Spot-check shape — mom has phones+email+starred+notes? (notes none in this fixture)
+    const mom = persons.find((p) => p.names[0] === "妈妈");
+    expect(mom.identifiers.phone).toEqual(["13800001111", "13900002222"]);
+    expect(mom.identifiers.email).toEqual(["mom@example.com"]);
+    expect(mom.extra.starred).toBe(true);
+    expect(mom.extra.deviceSerial).toBe("24115RA8EC-test");
+  });
+});

package/__tests__/sidecar-supervisor.test.js

@@ -0,0 +1,120 @@
+"use strict";
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import path from "node:path";
+
+const {
+  SidecarSupervisor,
+  SidecarTimeoutError,
+  SidecarMethodError,
+  SidecarNotRunningError,
+} = require("../lib/sidecar");
+
+const SIDECAR_ROOT = path.resolve(
+  __dirname,
+  "..",
+  "..",
+  "personal-data-hub-bridge",
+);
+
+/**
+ * Spawn the forensics-bridge sidecar from this repo's sibling package.
+ * Tests are skipped if Python is unavailable on PATH (CI matrix coverage
+ * is the source of truth; local dev without Python should not be blocked).
+ */
+function makeSupervisor() {
+  return new SidecarSupervisor({
+    command: process.env.FORENSICS_BRIDGE_PYTHON || "python",
+    args: ["-u", "-m", "forensics_bridge.ipc_server"],
+    cwd: SIDECAR_ROOT,
+    healthCheckIntervalMs: 0, // disable for tests — manual control only
+    env: { PYTHONPATH: SIDECAR_ROOT },
+  });
+}
+
+let pythonAvailable = true;
+try {
+  // Cheap synchronous probe — spawn fails if python is not on PATH.
+  const { spawnSync } = require("node:child_process");
+  const probe = spawnSync(
+    process.env.FORENSICS_BRIDGE_PYTHON || "python",
+    ["--version"],
+    { stdio: "ignore" },
+  );
+  if (probe.status !== 0) pythonAvailable = false;
+} catch (_err) {
+  pythonAvailable = false;
+}
+
+const itPy = pythonAvailable ? it : it.skip;
+
+describe("SidecarSupervisor (forensics-bridge integration)", () => {
+  let supervisor;
+
+  beforeEach(() => {
+    supervisor = makeSupervisor();
+  });
+
+  afterEach(async () => {
+    if (supervisor) await supervisor.stop({ graceMs: 1500 });
+  });
+
+  itPy("starts the sidecar and round-trips sidecar.ping", async () => {
+    await supervisor.start({ readyTimeoutMs: 8_000 });
+    expect(supervisor.isRunning()).toBe(true);
+
+    const ping = await supervisor.invoke("sidecar.ping", {}, { timeoutMs: 3_000 });
+    expect(ping.version).toMatch(/^\d+\.\d+\.\d+/);
+    expect(ping.pythonVersion).toMatch(/^3\./);
+  });
+
+  itPy("sidecar.capabilities exposes registered methods", async () => {
+    await supervisor.start({ readyTimeoutMs: 8_000 });
+
+    const caps = await supervisor.invoke("sidecar.capabilities");
+    expect(caps.methods).toContain("sidecar.ping");
+    expect(caps.methods).toContain("sidecar.capabilities");
+    // Namespace registry grows as parsers/extractors land; Phase 4.5.2 brings
+    // the system parser online.
+    expect(caps.parsers).toContain("system");
+    expect(caps.extractors).toContain("android");
+  });
+
+  itPy("METHOD_NOT_FOUND surfaces as a typed SidecarMethodError", async () => {
+    await supervisor.start({ readyTimeoutMs: 8_000 });
+
+    await expect(
+      supervisor.invoke("definitely.not.a.real.method"),
+    ).rejects.toMatchObject({
+      name: "SidecarMethodError",
+      code: "METHOD_NOT_FOUND",
+      retryable: false,
+    });
+  });
+
+  itPy("invoke rejects with SidecarNotRunningError when sidecar is stopped", async () => {
+    await supervisor.start({ readyTimeoutMs: 8_000 });
+    await supervisor.stop({ graceMs: 1500 });
+    expect(supervisor.isRunning()).toBe(false);
+
+    await expect(supervisor.invoke("sidecar.ping")).rejects.toMatchObject({
+      name: "SidecarNotRunningError",
+      code: "SIDECAR_NOT_RUNNING",
+    });
+  });
+
+  itPy("two sequential invokes share one sidecar process", async () => {
+    await supervisor.start({ readyTimeoutMs: 8_000 });
+    const first = await supervisor.invoke("sidecar.ping");
+    const second = await supervisor.invoke("sidecar.capabilities");
+    expect(first.version).toBeDefined();
+    expect(second.methods).toContain("sidecar.ping");
+  });
+
+  itPy("error class hierarchy is exported", () => {
+    expect(typeof SidecarSupervisor).toBe("function");
+    expect(typeof SidecarTimeoutError).toBe("function");
+    expect(typeof SidecarMethodError).toBe("function");
+    expect(typeof SidecarNotRunningError).toBe("function");
+  });
+});