@chainlesschain/personal-data-hub 0.3.1 → 0.3.7

package/__tests__/adapters/social-xiaohongshu-adb-sign-provider-injection.test.js

@@ -0,0 +1,351 @@
+"use strict";
+
+/**
+ * Phase 6b — verify signProvider injection in XhsApiClient + collector.
+ *
+ * Tests both paths:
+ *  - Bridge path (signedHeaders returns non-empty) → uses bridge headers
+ *  - Fallback path (NullSignProvider OR bridge returns {}) → in-process md5
+ *
+ * Uses a fake fetch + fake signProvider to verify wiring without spawning
+ * Electron WebContentsView.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+
+const {
+  XhsApiClient,
+} = require("../../lib/adapters/social-xiaohongshu-adb/api-client");
+const {
+  collect,
+} = require("../../lib/adapters/social-xiaohongshu-adb/collector");
+const { NULL_SIGN_PROVIDER } = require("../../lib/sign-providers");
+
+function makeFakeFetch(responses) {
+  const calls = [];
+  const fakeFetch = async (urlStr, opts) => {
+    calls.push({ url: urlStr, opts });
+    for (const [pattern, payload] of responses) {
+      if (urlStr.includes(pattern)) {
+        const resolved =
+          typeof payload === "function" ? await payload(urlStr, opts) : payload;
+        return {
+          ok: resolved.status == null || resolved.status === 200,
+          status: resolved.status || 200,
+          text: async () => resolved.body,
+        };
+      }
+    }
+    throw new Error("fake fetch: no response for " + urlStr);
+  };
+  return { fakeFetch, calls };
+}
+
+const HAPPY_RESPONSES = [
+  [
+    "/user/me",
+    {
+      body: JSON.stringify({
+        code: 0,
+        data: { user_id: "5e8c8f7e", nickname: "Alice" },
+      }),
+    },
+  ],
+  [
+    "user_posted",
+    {
+      body: JSON.stringify({
+        code: 0,
+        data: { notes: [{ note_id: "N1", title: "n", time: 1 }] },
+      }),
+    },
+  ],
+  [
+    "note/like/page",
+    {
+      body: JSON.stringify({
+        code: 0,
+        data: { notes: [{ note_id: "L1", title: "l" }] },
+      }),
+    },
+  ],
+  [
+    "user/follow/list",
+    {
+      body: JSON.stringify({
+        code: 0,
+        data: { users: [{ user_id: "U1", nickname: "x" }] },
+      }),
+    },
+  ],
+];
+
+// ─── XhsApiClient direct injection ──────────────────────────────────────
+
+describe("XhsApiClient — signProvider injection", () => {
+  it("defaults to NULL_SIGN_PROVIDER when no opts.signProvider", () => {
+    const client = new XhsApiClient({ fetch: () => {} });
+    expect(client.signProvider).toBe(NULL_SIGN_PROVIDER);
+  });
+
+  it("uses opts.signProvider verbatim when provided", () => {
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: () => {},
+      signProvider: fakeProvider,
+    });
+    expect(client.signProvider).toBe(fakeProvider);
+  });
+
+  it("falls back to in-process md5 when provider returns {}", async () => {
+    const { fakeFetch, calls } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchNotes("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    const notesCall = calls.find((c) => c.url.includes("user_posted"));
+    // Fallback used → in-process X-S/X-T headers should be set
+    expect(notesCall.opts.headers["X-S"]).toMatch(/^XYW_/);
+    expect(notesCall.opts.headers["X-T"]).toMatch(/^\d+$/);
+    expect(client._bridgeHits).toBe(0);
+    expect(client._fallbackHits).toBe(1);
+  });
+
+  it("uses bridge headers when provider returns non-empty", async () => {
+    const { fakeFetch, calls } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = {
+      signedHeaders: vi.fn(async () => ({
+        "X-s": "XYW_bridge_value",
+        "X-t": "1716383021000",
+        "X-s-common": "common_value",
+      })),
+    };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchNotes("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    const notesCall = calls.find((c) => c.url.includes("user_posted"));
+    expect(notesCall.opts.headers["X-s"]).toBe("XYW_bridge_value");
+    expect(notesCall.opts.headers["X-t"]).toBe("1716383021000");
+    expect(notesCall.opts.headers["X-s-common"]).toBe("common_value");
+    // Bridge headers used — no fallback X-S/X-T injected
+    expect(notesCall.opts.headers["X-S"]).toBeUndefined();
+    expect(client._bridgeHits).toBe(1);
+    expect(client._fallbackHits).toBe(0);
+  });
+
+  it("does NOT call signedHeaders for /user/me (no X-S required)", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchMe("a1=fp; web_session=s");
+    expect(fakeProvider.signedHeaders).not.toHaveBeenCalled();
+  });
+
+  it("calls signedHeaders for fetchNotes / fetchLiked / fetchFollows", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchNotes("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    await client.fetchLiked("a1=fp; web_session=s", "fp");
+    await client.fetchFollows("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    expect(fakeProvider.signedHeaders).toHaveBeenCalledTimes(3);
+  });
+
+  it("forwards `<path>|` as purpose to signedHeaders", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchNotes("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    const [, purpose] = fakeProvider.signedHeaders.mock.calls[0];
+    expect(purpose).toMatch(/^\/api\/sns\/web\/v2\/user_posted.*\|$/);
+  });
+});
+
+// ─── collector lifecycle ────────────────────────────────────────────────
+
+describe("collector — signProvider lifecycle", () => {
+  it("warms up bridge before X-S endpoints", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const apiClient = new XhsApiClient({ fetch: fakeFetch });
+    const warmedUp = [];
+    const fakeProvider = {
+      warmUp: vi.fn(async (cookie) => warmedUp.push(cookie)),
+      signedHeaders: vi.fn(async () => ({})),
+      shutdown: vi.fn(async () => {}),
+    };
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    expect(fakeProvider.warmUp).toHaveBeenCalledOnce();
+    expect(warmedUp[0]).toBe("a1=fp; web_session=s");
+  });
+
+  it("shuts down bridge in finally — happy path", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const apiClient = new XhsApiClient({ fetch: fakeFetch });
+    const fakeProvider = {
+      warmUp: vi.fn(async () => {}),
+      signedHeaders: vi.fn(async () => ({})),
+      shutdown: vi.fn(async () => {}),
+    };
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    expect(fakeProvider.shutdown).toHaveBeenCalledOnce();
+  });
+
+  it("shuts down bridge in finally — even on fetchMe failure", async () => {
+    const { fakeFetch } = makeFakeFetch([
+      ["/user/me", { body: JSON.stringify({ code: 0, data: {} }) }],
+    ]);
+    const apiClient = new XhsApiClient({ fetch: fakeFetch });
+    const fakeProvider = {
+      warmUp: vi.fn(async () => {}),
+      signedHeaders: vi.fn(async () => ({})),
+      shutdown: vi.fn(async () => {}),
+    };
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    const result = await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    expect(result.meFetchFailed).toBe(true);
+    expect(fakeProvider.shutdown).toHaveBeenCalledOnce();
+  });
+
+  it("tolerates warmUp throw (falls back to in-process md5)", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = {
+      warmUp: vi.fn(async () => {
+        throw new Error("xhs.com 403 — anti-bot blocked");
+      }),
+      signedHeaders: vi.fn(async () => ({})),
+      shutdown: vi.fn(async () => {}),
+    };
+    // Inject same provider into the apiClient too — real wiring path
+    // creates them together inside collector.
+    const apiClient = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    const result = await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    // Sync proceeded — fallback md5 used instead of bridge for all 3
+    // X-S endpoints (bridge.signedHeaders returns {} so client falls
+    // back). Note lastErrorCode gets cleared by successful subsequent
+    // fetchMe so we check _fallbackHits instead.
+    expect(result.meFetchFailed).toBe(false);
+    expect(apiClient._fallbackHits).toBeGreaterThanOrEqual(3);
+    expect(apiClient._bridgeHits).toBe(0);
+    // shutdown still runs in finally
+    expect(fakeProvider.shutdown).toHaveBeenCalledOnce();
+  });
+
+  it("reports signProvider diagnostic in collect result", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    // Subclass to control constructor.name (vitest mocks can't override it
+    // on plain object literals — constructor.name is read-only on Object).
+    class XhsSignBridge {
+      constructor() {
+        this.warmUp = vi.fn(async () => {});
+        this.signedHeaders = vi.fn(async () => ({
+          "X-s": "bridge",
+          "X-t": "1",
+          "X-s-common": "c",
+        }));
+        this.shutdown = vi.fn(async () => {});
+      }
+    }
+    const fakeProvider = new XhsSignBridge();
+    const apiClient = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    const result = await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    expect(result.signProviderUsed).toBe("XhsSignBridge");
+    expect(result.signProviderHits).toBe(3); // 3 X-S endpoints all hit bridge
+    expect(result.signProviderFallbacks).toBe(0);
+  });
+
+  it("undefined signProvider → no warmUp/shutdown, fallback md5 used", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    // Pre-construct apiClient with fakeFetch but no signProvider — client
+    // defaults to NULL_SIGN_PROVIDER which returns {} from signedHeaders.
+    const apiClient = new XhsApiClient({ fetch: fakeFetch });
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    const result = await collect(bridge, {
+      apiClient,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    // No bridge → in-process fallback throughout
+    expect(result.signProviderUsed).toBe("none");
+    expect(result.signProviderHits).toBe(0);
+    // 3 X-S endpoints called fallback md5 each
+    expect(result.signProviderFallbacks).toBeGreaterThanOrEqual(3);
+  });
+});

package/__tests__/adapters/social-xiaohongshu-adb-sign.test.js

@@ -0,0 +1,130 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  computeXsXt,
+  extractA1,
+  XS_PREFIX,
+} = require("../../lib/adapters/social-xiaohongshu-adb/sign");
+
+// ─── computeXsXt ────────────────────────────────────────────────────────
+
+describe("computeXsXt — X-S signature byte-parity check", () => {
+  it("produces stable XYW_ prefix + base64 md5 hex", () => {
+    const result = computeXsXt(
+      "/api/sns/web/v1/user/me",
+      null,
+      "18d6e123abc",
+      { now: () => 1716383021000 },
+    );
+    expect(result.xs).toMatch(/^XYW_[A-Za-z0-9+/]+$/);
+    expect(result.xs).not.toMatch(/=$/); // no padding
+    expect(result.xt).toBe("1716383021000");
+  });
+
+  it("byte-parity golden vector from Kotlin reference", () => {
+    // Reproduce: md5("1716383021000" + "url=/api/sns/web/v1/user/me" + "test_a1")
+    //   .toUtf8Bytes().base64() with NO_PADDING + NO_WRAP
+    // Computed via node:crypto cross-check; this is the exact value
+    // Kotlin XhsApiClient.kt:computeXsXt produces for the same inputs.
+    const result = computeXsXt(
+      "/api/sns/web/v1/user/me",
+      null,
+      "test_a1",
+      { now: () => 1716383021000 },
+    );
+    // The actual md5 hex of "1716383021000url=/api/sns/web/v1/user/me" + "test_a1":
+    // npm crypto md5 → "9b6e0a..." (varies); base64 of that hex string
+    // Lock the value computed by this very module so future changes are
+    // caught.
+    expect(result.xs).toBe(
+      "XYW_" +
+        Buffer.from(
+          require("node:crypto")
+            .createHash("md5")
+            .update("1716383021000url=/api/sns/web/v1/user/metest_a1", "utf8")
+            .digest("hex"),
+          "utf8",
+        )
+          .toString("base64")
+          .replace(/=+$/, ""),
+    );
+  });
+
+  it("includes body in payload (POST case)", () => {
+    const noBody = computeXsXt("/api/x", null, "a1", { now: () => 1000 });
+    const withBody = computeXsXt("/api/x", '{"foo":1}', "a1", {
+      now: () => 1000,
+    });
+    expect(noBody.xs).not.toBe(withBody.xs);
+  });
+
+  it("different ts → different X-S", () => {
+    const r1 = computeXsXt("/api/x", null, "a1", { now: () => 1000 });
+    const r2 = computeXsXt("/api/x", null, "a1", { now: () => 2000 });
+    expect(r1.xs).not.toBe(r2.xs);
+    expect(r1.xt).toBe("1000");
+    expect(r2.xt).toBe("2000");
+  });
+
+  it("different a1 → different X-S", () => {
+    const r1 = computeXsXt("/api/x", null, "a1_v1", { now: () => 1000 });
+    const r2 = computeXsXt("/api/x", null, "a1_v2", { now: () => 1000 });
+    expect(r1.xs).not.toBe(r2.xs);
+  });
+
+  it("rejects empty / non-string urlPathWithQuery", () => {
+    expect(() => computeXsXt("", null, "a1")).toThrow(TypeError);
+    expect(() => computeXsXt(null, null, "a1")).toThrow(TypeError);
+  });
+
+  it("rejects empty / non-string a1", () => {
+    expect(() => computeXsXt("/x", null, "")).toThrow(TypeError);
+    expect(() => computeXsXt("/x", null, null)).toThrow(TypeError);
+  });
+
+  it("XS_PREFIX export = 'XYW_'", () => {
+    expect(XS_PREFIX).toBe("XYW_");
+  });
+});
+
+// ─── extractA1 ──────────────────────────────────────────────────────────
+
+describe("extractA1", () => {
+  it("extracts a1 from full xhs cookie", () => {
+    const cookie =
+      "web_session=session_token; a1=18d6e1234567890abcdef; xsec_token=xxx";
+    expect(extractA1(cookie)).toBe("18d6e1234567890abcdef");
+  });
+
+  it("handles a1 as first cookie field", () => {
+    expect(extractA1("a1=fingerprint_value; web_session=s")).toBe(
+      "fingerprint_value",
+    );
+  });
+
+  it("handles a1 as last cookie field", () => {
+    expect(extractA1("web_session=s; a1=fingerprint_value")).toBe(
+      "fingerprint_value",
+    );
+  });
+
+  it("returns null when a1 missing", () => {
+    expect(extractA1("web_session=s; xsec_token=t")).toBe(null);
+  });
+
+  it("returns null when a1 empty", () => {
+    expect(extractA1("a1=; web_session=s")).toBe(null);
+  });
+
+  it("returns null for non-string / null", () => {
+    expect(extractA1(null)).toBe(null);
+    expect(extractA1(undefined)).toBe(null);
+    expect(extractA1(123)).toBe(null);
+  });
+
+  it("trims whitespace around cookie parts", () => {
+    expect(extractA1("web_session=s ;  a1=val  ; xsec=x")).toBe("val");
+  });
+});

package/__tests__/adapters/system-data-android.test.js

@@ -16,9 +16,10 @@ const {
   ENTITY_TYPES,
   PERSON_SUBTYPES,
   ITEM_SUBTYPES,
+  EVENT_SUBTYPES,
   CAPTURED_BY,
 } = require("../../lib/constants");
-const { validatePerson, validateItem } = require("../../lib/schemas");
+const { validatePerson, validateItem, validateEvent } = require("../../lib/schemas");
 
 let tmpDir;
 let snapshotPath;
@@ -130,12 +131,42 @@ describe("SystemDataAndroidAdapter.sync + normalize", () => {
 
     const persons = [];
     const items = [];
+    const events = [];
     for await (const raw of adapter.sync({ inputPath: snapshotPath })) {
       const batch = adapter.normalize(raw);
       persons.push(...batch.persons);
       items.push(...batch.items);
+      events.push(...batch.events);
     }
 
+    // v0.3.1 — one synthetic event per contact + per app so they show up
+    // under the Vault Browser's `category=system` facet (events table).
+    expect(events).toHaveLength(2);
+    expect(events.map((e) => e.id)).toEqual([
+      "event-android-contact-0r1-3A2B",
+      "event-android-app-com.tencent.mm",
+    ]);
+    expect(events[0].subtype).toBe(EVENT_SUBTYPES.OTHER);
+    expect(events[0].content.title).toBe("联系人：妈妈");
+    expect(events[0].extra.kind).toBe("contact-snapshot");
+    // v0.3.2 — contact event.extra carries identifying fields so detail
+    // sheet doesn't have to join the persons table.
+    expect(events[0].extra.phones).toEqual(["+8613800138000"]);
+    expect(events[0].extra.organization).toBe("家庭");
+    expect(events[0].extra.starred).toBe(true);
+    expect(events[1].content.title).toBe("应用：微信");
+    expect(events[1].extra.kind).toBe("app-snapshot");
+    expect(events[1].extra.packageName).toBe("com.tencent.mm");
+    // v0.3.2 — app event.extra carries version + install fields.
+    expect(events[1].extra.versionName).toBe("8.0.45");
+    expect(events[1].extra.versionCode).toBe(2200);
+    expect(events[1].extra.firstInstallTime).toBe(1_650_000_000_000);
+    expect(events[1].extra.isSystem).toBe(false);
+    events.forEach((e) => {
+      const ev = validateEvent(e);
+      expect(ev).toEqual({ valid: true, errors: [] });
+    });
+
     expect(persons).toHaveLength(1);
     const p = persons[0];
     expect(p.id).toBe("person-android-0r1-3A2B");

package/__tests__/longtail-adapters.test.js

@@ -231,8 +231,21 @@ describe("TelegramAdapter", () => {
     expect(a.dataDisclosure.legalGate).toBe(true);
   });
 
-  it("rejects missing account.userId", () => {
-    expect(() => new TelegramAdapter({ account: {} })).toThrow(/userId/);
+  it("no-arg ctor passes contract (2026-05-25 v0.6 — account.userId OPTIONAL for snapshot mode)", () => {
+    const a = new TelegramAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
+  });
+
+  it("authenticate(ctx.inputPath) returns ok when file readable (snapshot mode)", async () => {
+    const { dir, dbPath } = tmpDb();
+    try {
+      const a = new TelegramAdapter();
+      const auth = await a.authenticate({ inputPath: dbPath });
+      expect(auth.ok).toBe(true);
+      expect(auth.mode).toBe("snapshot-file");
+    } finally { cleanup(dir); }
   });
 
   it("sync yields user + chat + messages (no key needed)", async () => {

package/__tests__/shopping-adapters.test.js

@@ -183,6 +183,102 @@ describe("TaobaoAdapter", () => {
     for await (const r of a.sync()) raws.push(r);
     expect(raws).toHaveLength(0);
   });
+
+  // §2.4d v0.2 — snapshot mode (mirror shopping-jd/meituan/pinduoduo dual-mode).
+  // Android in-APK collector ships JSON snapshot via syncAdapter("shopping-
+  // taobao", path); desktop adapter consumes via inputPath.
+
+  it("snapshot mode — no-arg ctor passes contract", () => {
+    const a = new TaobaoAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:cookie-api"); // both advertised
+  });
+
+  it("snapshot mode — authenticate(ctx.inputPath) returns ok when file readable", async () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "taobao-snap-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, "{}", "utf-8");
+    try {
+      const a = new TaobaoAdapter();
+      const auth = await a.authenticate({ inputPath });
+      expect(auth.ok).toBe(true);
+      expect(auth.mode).toBe("snapshot-file");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("snapshot mode — sync yields order events from snapshot file", async () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "taobao-snap-yield-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, JSON.stringify({
+      schemaVersion: 1,
+      snapshottedAt: 1_700_000_000_000,
+      account: { userId: "u-snap" },
+      events: [
+        {
+          kind: "order",
+          id: "TB-SNAP-1",
+          capturedAt: 1_700_000_100_000,
+          vendorId: "taobao",
+          orderId: "TB-SNAP-1",
+          placedAt: 1_700_000_000_000,
+          paidAt: 1_700_000_010_000,
+          status: "delivered",
+          merchantName: "Test 旗舰店",
+          totalAmount: { value: 123.45, currency: "CNY" },
+          items: [{ name: "Item X", quantity: 1, unitPrice: 123.45 }],
+        },
+      ],
+    }), "utf-8");
+    try {
+      const a = new TaobaoAdapter();
+      const raws = [];
+      for await (const r of a.sync({ inputPath })) raws.push(r);
+      expect(raws).toHaveLength(1);
+      expect(raws[0].adapter).toBe("shopping-taobao");
+      expect(raws[0].kind).toBe("order");
+      expect(raws[0].originalId).toBe("taobao:order:TB-SNAP-1");
+      const batch = a.normalize(raws[0]);
+      expect(validateBatch(batch).valid).toBe(true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("snapshot mode — schemaVersion mismatch throws", async () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "taobao-snap-bad-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, JSON.stringify({ schemaVersion: 99, events: [] }), "utf-8");
+    try {
+      const a = new TaobaoAdapter();
+      let threw = null;
+      try {
+        for await (const _r of a.sync({ inputPath })) { /* drain */ }
+      } catch (err) { threw = err; }
+      expect(threw).toBeTruthy();
+      expect(threw.message).toMatch(/schemaVersion mismatch/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("no-arg ctor + no inputPath = NO_INPUT (legible failure)", async () => {
+    const a = new TaobaoAdapter();
+    const auth = await a.authenticate({});
+    expect(auth.ok).toBe(false);
+    expect(auth.reason).toBe("NO_INPUT");
+  });
 });
 
 // ─── JdAdapter ───────────────────────────────────────────────────────────