@chainlesschain/personal-data-hub 0.3.1 → 0.3.6

package/lib/adapters/email-imap/email-adapter.js

@@ -15,6 +15,7 @@
 
 "use strict";
 
+const fs = require("node:fs");
 const {
   EVENT_SUBTYPES,
   PERSON_SUBTYPES,
@@ -34,26 +35,45 @@ const { extractPdfText, passwordsFromHints } = require("./pdf-extractor");
 const { extractTransactions } = require("./transactions");
 
 const NAME = "email-imap";
-const VERSION = "0.6.0"; // Phase 5.7 — retry-with-backoff + progress streaming
+const VERSION = "0.7.0"; // Phase 5.8 — snapshot mode for Android in-APK IMAP fetch
+const SNAPSHOT_SCHEMA_VERSION = 1;
 
 class EmailAdapter {
   constructor(opts) {
     if (!opts || typeof opts !== "object") {
       throw new Error("EmailAdapter: opts required");
     }
-    const account = opts.account;
-    if (!account || typeof account !== "object") {
-      throw new Error("EmailAdapter: opts.account required");
-    }
-    if (typeof account.email !== "string" || !account.email.includes("@")) {
-      throw new Error("EmailAdapter: account.email must be a full address");
-    }
-    if (typeof account.authCode !== "string" || account.authCode.length === 0) {
-      throw new Error("EmailAdapter: account.authCode required (provider authorization code)");
+
+    // Phase 5.8 — snapshot mode: Android EmailLocalCollector ships pre-fetched
+    // {records:[]} JSON via ccRunner.syncAdapter("email-imap", path). When
+    // snapshotMode=true: skip IMAP-account validation (no IMAP login needed)
+    // and switch authenticate/sync to the snapshot path. The single registered
+    // instance handles every Android vendor; each snapshot file carries its
+    // own vendor + user, no per-account constructor needed (mirror of
+    // travel-12306 / travel-baidu-map / social-bilibili snapshot mode).
+    this._snapshotMode = !!opts.snapshotMode;
+
+    if (!this._snapshotMode) {
+      const account = opts.account;
+      if (!account || typeof account !== "object") {
+        throw new Error("EmailAdapter: opts.account required");
+      }
+      if (typeof account.email !== "string" || !account.email.includes("@")) {
+        throw new Error("EmailAdapter: account.email must be a full address");
+      }
+      if (typeof account.authCode !== "string" || account.authCode.length === 0) {
+        throw new Error("EmailAdapter: account.authCode required (provider authorization code)");
+      }
+      this.account = account;
+      this._provider = resolveProvider(account);
+    } else {
+      // Snapshot-mode stub: account fields used by _envelopeToRawEvent/
+      // normalize fall back to "(snapshot)" placeholders. Real per-record
+      // vendor + user surface in the snapshot envelope payload instead.
+      this.account = opts.account || { email: "(snapshot)", authCode: "(snapshot)" };
+      this._provider = null;
     }
 
-    this.account = account;
-    this._provider = resolveProvider(account);
     this._sessionFactory = typeof opts.sessionFactory === "function"
       ? opts.sessionFactory
       : (cfg) => new ImapSession(cfg);
@@ -129,16 +149,15 @@ class EmailAdapter {
     this.name = NAME;
     this.version = VERSION;
     this.capabilities = [
-      "sync:imap",
-      "auth:authcode",
+      ...(this._snapshotMode ? ["sync:snapshot"] : ["sync:imap"]),
+      ...(this._snapshotMode ? [] : ["auth:authcode"]),
       "parse:mime-body",
       "parse:attachment-metadata",
       "classify:layer1-rules",
       ...(this._llm ? ["classify:layer2-llm"] : []),
       "extract:6-templates",
       ...(this._disablePdfExtraction ? [] : ["decrypt:pdf-bills"]),
-      "sync:retry-backoff",
-      "sync:progress-stream",
+      ...(this._snapshotMode ? [] : ["sync:retry-backoff", "sync:progress-stream"]),
     ];
     this.rateLimits = { perMinute: 60 };
     this.dataDisclosure = {
@@ -159,7 +178,30 @@ class EmailAdapter {
     };
   }
 
-  async authenticate(_ctx = {}) {
+  async authenticate(ctx = {}) {
+    // Phase 5.8 — snapshot mode authenticate: validate ctx.inputPath is
+    // readable; no IMAP login. Snapshot mode WITHOUT inputPath in ctx
+    // returns NO_INPUT (parallel to travel-12306 / travel-baidu-map shape).
+    if (this._snapshotMode || (ctx && typeof ctx.inputPath === "string" && ctx.inputPath.length > 0)) {
+      if (!ctx || typeof ctx.inputPath !== "string" || ctx.inputPath.length === 0) {
+        return {
+          ok: false,
+          reason: "NO_INPUT",
+          message: "email-imap (snapshot mode): ctx.inputPath required",
+        };
+      }
+      try {
+        fs.accessSync(ctx.inputPath, fs.constants.R_OK);
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "INPUT_PATH_UNREADABLE",
+          message: `snapshot not readable at ${ctx.inputPath}: ${err.message}`,
+        };
+      }
+      return { ok: true, mode: "snapshot-file" };
+    }
+
     const session = this._sessionFactory(this._sessionConfig());
     try {
       await session.connect();
@@ -184,6 +226,15 @@ class EmailAdapter {
   }
 
   async *sync(opts = {}) {
+    // Phase 5.8 — snapshot mode: bypass IMAP session entirely, read Android
+    // EmailLocalCollector's staging JSON, yield one raw event per record.
+    // Classification + extraction reused on envelope-only data (bodyPreview
+    // is the only text we get; PDF decryption skipped since attachment
+    // buffers never crossed the Android → desktop boundary).
+    if (this._snapshotMode || (typeof opts.inputPath === "string" && opts.inputPath.length > 0)) {
+      yield* this._syncViaSnapshot(opts);
+      return;
+    }
     const folders = Array.isArray(opts.folders) && opts.folders.length > 0
       ? opts.folders
       : this._provider.folders;
@@ -329,6 +380,143 @@ class EmailAdapter {
     }
   }
 
+  /**
+   * Phase 5.8 — snapshot path: read Android EmailLocalCollector's staging
+   * JSON, convert each record to an IMAP-shaped envelope, run classifier +
+   * extractor (no PDF — Android only ships bodyPreview), yield raw events.
+   *
+   * Expected snapshot shape (matches EmailLocalCollector.kt:135-156):
+   *   {vendor, user, fetchedAt, records: [{
+   *     messageNumber, subject, from, to, sentDateMs, bodyPreview,
+   *     hasAttachments
+   *   }]}
+   *
+   * Lossy compared to IMAP path:
+   *   - No HTML body (Android Jakarta Mail only ships text/plain or
+   *     stripped-html as bodyPreview, capped 8KB).
+   *   - No attachment buffers → no PDF decryption / transaction extraction
+   *     even for bill-template matches. `hasAttachments` boolean only.
+   *   - No real Message-ID → originalId synthesized from
+   *     `android-snapshot:<vendor>:<user>:<messageNumber>` (stable per device).
+   *   - No flags / cc / size; UID = Android messageNumber (per-folder).
+   */
+  async *_syncViaSnapshot(opts) {
+    const raw = fs.readFileSync(opts.inputPath, "utf-8");
+    let snapshot;
+    try {
+      snapshot = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(
+        `email-imap.sync (snapshot): bad JSON at ${opts.inputPath}: ${err.message}`,
+      );
+    }
+    if (!snapshot || typeof snapshot !== "object") {
+      throw new Error(
+        `email-imap.sync (snapshot): expected object, got ${typeof snapshot}`,
+      );
+    }
+    if (!Array.isArray(snapshot.records)) {
+      throw new Error(
+        "email-imap.sync (snapshot): expected {records: [...]} shape (Android EmailLocalCollector writes this)",
+      );
+    }
+    const vendor = typeof snapshot.vendor === "string" ? snapshot.vendor : "unknown";
+    const user = typeof snapshot.user === "string" ? snapshot.user : "unknown@snapshot";
+    const fallbackCapturedAt =
+      Number.isFinite(snapshot.fetchedAt) && snapshot.fetchedAt > 0
+        ? Math.floor(snapshot.fetchedAt)
+        : Date.now();
+
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    let emitted = 0;
+
+    for (const r of snapshot.records) {
+      if (emitted >= limit) return;
+      if (!r || typeof r !== "object") continue;
+      const env = this._androidRecordToEnvelope(r, vendor, user, fallbackCapturedAt);
+      // bodyPreview is the only text we have — wrap as a thin parsedBody so
+      // the classifier sees the same shape it does for IMAP-fetched mail.
+      const parsedBody = {
+        textBody: typeof r.bodyPreview === "string" ? r.bodyPreview : "",
+        htmlBody: "",
+        attachments: r.hasAttachments
+          ? [{ filename: "(unknown)", contentType: "application/octet-stream", size: 0 }]
+          : [],
+        headers: {},
+      };
+
+      let classification = null;
+      if (!this._disableClassification) {
+        try {
+          classification = await this._classifier(
+            this._classifierInput(env, parsedBody),
+            { llm: this._llm, minLayer1Confidence: this._minLayer1Confidence },
+          );
+        } catch (err) {
+          classification = {
+            category: CATEGORIES.OTHER,
+            confidence: 0,
+            layer: "error",
+            error: err && err.message ? err.message : String(err),
+          };
+        }
+      }
+
+      let extraction = null;
+      if (!this._disableExtraction) {
+        try {
+          extraction = await this._extractor(
+            this._classifierInput(env, parsedBody),
+            classification || { category: CATEGORIES.OTHER },
+            { llm: this._llm },
+          );
+        } catch (err) {
+          extraction = {
+            template: null,
+            fields: null,
+            warnings: [`extractor threw: ${err && err.message ? err.message : err}`],
+          };
+        }
+      }
+
+      // PDF extraction intentionally skipped — attachment buffers never crossed
+      // the Android → desktop boundary. Bill-template extractions on snapshot
+      // records get extraction.fields but no transactions list.
+      yield this._envelopeToRawEvent(env, "INBOX", parsedBody, classification, extraction);
+      emitted += 1;
+    }
+  }
+
+  /**
+   * Convert Android EmailLocalCollector record → IMAP-shaped envelope.
+   * Address strings ("Name <addr@x>" / "addr@x" / "addr@x, addr2@y") parse
+   * into {address, name} objects matching mailparser's output. Multi-recipient
+   * `to` strings split on comma.
+   */
+  _androidRecordToEnvelope(r, vendor, user, fallbackCapturedAt) {
+    const messageNumber = Number.isInteger(r.messageNumber) ? r.messageNumber : 0;
+    const sentDate = Number.isFinite(r.sentDateMs) && r.sentDateMs > 0
+      ? new Date(r.sentDateMs)
+      : new Date(fallbackCapturedAt);
+    return {
+      uid: messageNumber,
+      messageId: `android-snapshot:${vendor}:${user}:${messageNumber}`,
+      folder: "INBOX",
+      subject: typeof r.subject === "string" ? r.subject : "(no subject)",
+      from: typeof r.from === "string" && r.from.length > 0
+        ? [parseSnapshotAddress(r.from)]
+        : [],
+      to: typeof r.to === "string" && r.to.length > 0
+        ? r.to.split(",").map((s) => parseSnapshotAddress(s.trim())).filter(Boolean)
+        : [],
+      cc: [],
+      flags: [],
+      size: 0,
+      internalDate: sentDate,
+      date: sentDate,
+    };
+  }
+
   /**
    * Phase 5.7: connect with retry on transient errors. Auth failures
    * (AUTH_FAILED) and mailbox-not-found (MAILBOX_NOT_FOUND) bypass retry —
@@ -673,6 +861,25 @@ function formatAddr(a) {
   return a.name ? `${a.name} <${a.address}>` : a.address;
 }
 
+/**
+ * Phase 5.8 — snapshot mode address parser. Android records ship address
+ * fields as strings like "Name <addr@x.com>" or "addr@x.com". Convert to
+ * mailparser-compatible {address, name} shape. Returns null for blank input.
+ */
+function parseSnapshotAddress(s) {
+  if (typeof s !== "string") return null;
+  const t = s.trim();
+  if (t.length === 0) return null;
+  // "Name <addr@x>" form
+  const m = t.match(/^(.*?)\s*<([^>]+)>\s*$/);
+  if (m) {
+    const name = m[1].trim().replace(/^["']|["']$/g, "");
+    return { address: m[2].trim(), name: name.length > 0 ? name : undefined };
+  }
+  // Bare address form
+  return { address: t, name: undefined };
+}
+
 function formatRecipients(list) {
   if (!Array.isArray(list) || list.length === 0) return "?";
   const head = list.slice(0, 3).map(formatAddr).join(", ");

package/lib/adapters/messaging-telegram/index.js

@@ -18,20 +18,22 @@ const fs = require("node:fs");
 const { newId } = require("../../ids");
 
 const NAME = "messaging-telegram";
-const VERSION = "0.5.0";
+const VERSION = "0.6.0"; // 2026-05-25 — account.userId OPTIONAL + inputPath alias
 
 class TelegramAdapter {
   constructor(opts = {}) {
-    if (!opts.account || !opts.account.userId) {
-      throw new Error("TelegramAdapter: opts.account.userId required");
-    }
-    this.account = opts.account;
-    this._dbPath = opts.dbPath || null;
+    // 2026-05-25 — account.userId OPTIONAL (mirror Taobao/Ctrip dual-mode).
+    // sqlite-mode adapter still requires user to provide a decrypted
+    // cache4.db (Telegram cache db is unencrypted — easier than WeChat).
+    // Earlier strict ctor blocked auto-register at boot → silent "no adapter
+    // messaging-telegram" when Android collector ships extracted db.
+    this.account = opts.account || null;
+    this._dbPath = opts.dbPath || opts.inputPath || null;
     this._dbDriverFactory = opts.dbDriverFactory || null;
 
     this.name = NAME;
     this.version = VERSION;
-    this.capabilities = ["sync:sqlite", "parse:telegram-messages"];
+    this.capabilities = ["sync:sqlite", "sync:snapshot", "parse:telegram-messages"];
     this.extractMode = "device-pull";
     this.rateLimits = {};
     this.dataDisclosure = {
@@ -43,11 +45,12 @@ class TelegramAdapter {
     };
   }
 
-  async authenticate() {
-    if (!this._dbPath || !fs.existsSync(this._dbPath)) {
-      return { ok: false, reason: "DB_NOT_PULLED" };
+  async authenticate(ctx = {}) {
+    const dbPath = (ctx && (ctx.inputPath || ctx.dbPath)) || this._dbPath;
+    if (!dbPath || !fs.existsSync(dbPath)) {
+      return { ok: false, reason: "DB_NOT_PULLED", message: "needs ctx.inputPath / opts.dbPath pointing to extracted cache4.db" };
     }
-    return { ok: true, account: this.account.userId };
+    return { ok: true, account: this.account ? this.account.userId : null, mode: "snapshot-file" };
   }
 
   async healthCheck() {
@@ -56,7 +59,7 @@ class TelegramAdapter {
   }
 
   async *sync(opts = {}) {
-    const dbPath = opts.dbPath || this._dbPath;
+    const dbPath = opts.inputPath || opts.dbPath || this._dbPath;
     if (!dbPath || !fs.existsSync(dbPath)) return;
     const Driver = this._dbDriverFactory
       ? this._dbDriverFactory()

package/lib/adapters/messaging-whatsapp/index.js

@@ -22,21 +22,23 @@ const fs = require("node:fs");
 const { newId } = require("../../ids");
 
 const NAME = "messaging-whatsapp";
-const VERSION = "0.5.0";
+const VERSION = "0.6.0"; // 2026-05-25 — account.phone OPTIONAL + inputPath alias
 
 class WhatsAppAdapter {
   constructor(opts = {}) {
-    if (!opts.account || !opts.account.phone) {
-      throw new Error("WhatsAppAdapter: opts.account.phone required");
-    }
-    this.account = opts.account;
-    this._dbPath = opts.dbPath || null;
+    // 2026-05-25 — account.phone OPTIONAL (mirror Taobao/Ctrip/Telegram).
+    // sqlite-mode adapter still requires user to provide a decrypted
+    // msgstore.db (user pre-decrypts with WhatsApp Crypt key — out of band).
+    // Earlier strict ctor blocked auto-register at boot → silent "no adapter
+    // messaging-whatsapp" when Android collector ships extracted db.
+    this.account = opts.account || null;
+    this._dbPath = opts.dbPath || opts.inputPath || null;
     this._keyProvider = opts.keyProvider || null;
     this._dbDriverFactory = opts.dbDriverFactory || null;
 
     this.name = NAME;
     this.version = VERSION;
-    this.capabilities = ["sync:sqlite", "parse:whatsapp-messages"];
+    this.capabilities = ["sync:sqlite", "sync:snapshot", "parse:whatsapp-messages"];
     this.extractMode = "device-pull";
     this.rateLimits = {};
     this.dataDisclosure = {
@@ -50,11 +52,12 @@ class WhatsAppAdapter {
     };
   }
 
-  async authenticate() {
-    if (!this._dbPath || !fs.existsSync(this._dbPath)) {
-      return { ok: false, reason: "DB_NOT_PULLED" };
+  async authenticate(ctx = {}) {
+    const dbPath = (ctx && (ctx.inputPath || ctx.dbPath)) || this._dbPath;
+    if (!dbPath || !fs.existsSync(dbPath)) {
+      return { ok: false, reason: "DB_NOT_PULLED", message: "needs ctx.inputPath / opts.dbPath pointing to decrypted msgstore.db" };
     }
-    return { ok: true, account: this.account.phone };
+    return { ok: true, account: this.account ? this.account.phone : null, mode: "snapshot-file" };
   }
 
   async healthCheck() {
@@ -63,7 +66,7 @@ class WhatsAppAdapter {
   }
 
   async *sync(opts = {}) {
-    const dbPath = opts.dbPath || this._dbPath;
+    const dbPath = opts.inputPath || opts.dbPath || this._dbPath;
     if (!dbPath || !fs.existsSync(dbPath)) return;
     const Driver = this._dbDriverFactory
       ? this._dbDriverFactory()

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

@@ -18,28 +18,36 @@
 
 "use strict";
 
+const fs = require("node:fs");
 const { normalizeOrderRecord, CookieAuth } = require("../shopping-base");
 
 const NAME = "shopping-taobao";
-const VERSION = "0.5.0";
+const VERSION = "0.6.0"; // §2.4d snapshot mode for Android in-APK cc
+const SNAPSHOT_SCHEMA_VERSION = 1;
+
+const KIND_ORDER = "order";
+const VALID_SNAPSHOT_KINDS = Object.freeze([KIND_ORDER]);
 
 const TAOBAO_ORDERS_URL = "https://h5.m.taobao.com/mlapp/olist.html";
 
 class TaobaoAdapter {
   constructor(opts = {}) {
-    if (!opts.account || !opts.account.userId) {
-      throw new Error("TaobaoAdapter: opts.account.userId required");
-    }
-    this.account = opts.account;
-    this._cookieAuth = new CookieAuth({
-      platform: "taobao",
-      cookies: opts.account.cookies || "",
-    });
+    // §2.4d v0.2 — account.userId OPTIONAL (mirror shopping-jd/meituan/pinduoduo
+    // dual-mode). Snapshot mode is stateless; cookie mode requires it; checked
+    // at sync time, not construction. Earlier strict ctor blocked auto-register
+    // at boot → user-driven HTML import worked but JSON snapshot path didn't.
+    this.account = opts.account || null;
+    this._cookieAuth = opts.account
+      ? new CookieAuth({
+          platform: "taobao",
+          cookies: opts.account.cookies || "",
+        })
+      : null;
     this._fetchFn = typeof opts.fetchFn === "function" ? opts.fetchFn : defaultFetch;
 
     this.name = NAME;
     this.version = VERSION;
-    this.capabilities = ["sync:cookie-api", "parse:taobao-orders"];
+    this.capabilities = ["sync:snapshot", "sync:cookie-api", "parse:taobao-orders"];
     this.extractMode = "web-api";
     this.rateLimits = { perMinute: 6, perDay: 200 }; // respect Taobao风控
     this.dataDisclosure = {
@@ -48,23 +56,132 @@ class TaobaoAdapter {
       ],
       sensitivity: "high",
       legalGate: false,
+      defaultInclude: { order: true },
     };
+
+    // _deps injection seam — vi.mock fs doesn't intercept inlined CJS require.
+    this._deps = { fs };
   }
 
-  async authenticate() {
-    const ok = await this._cookieAuth.validate();
-    if (!ok) return { ok: false, reason: "INVALID_COOKIE", error: "cookies missing or empty" };
-    return { ok: true, account: this.account.userId };
+  async authenticate(ctx = {}) {
+    if (ctx && typeof ctx.inputPath === "string" && ctx.inputPath.length > 0) {
+      try {
+        this._deps.fs.accessSync(ctx.inputPath, this._deps.fs.constants.R_OK);
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "INPUT_PATH_UNREADABLE",
+          message: `snapshot not readable at ${ctx.inputPath}: ${err.message}`,
+        };
+      }
+      return { ok: true, mode: "snapshot-file" };
+    }
+    if (this._cookieAuth) {
+      const ok = await this._cookieAuth.validate();
+      if (!ok) return { ok: false, reason: "INVALID_COOKIE", error: "cookies missing or empty" };
+      if (!this.account || !this.account.userId) {
+        return { ok: false, reason: "NO_ACCOUNT_USERID", message: "cookie mode requires account.userId" };
+      }
+      return { ok: true, account: this.account.userId, mode: "cookie" };
+    }
+    return {
+      ok: false,
+      reason: "NO_INPUT",
+      message: "TaobaoAdapter.authenticate: needs opts.inputPath (snapshot mode) OR opts.account.cookies (cookie mode)",
+    };
   }
 
   async healthCheck() {
-    const r = await this.authenticate();
-    return r.ok
-      ? { ok: true, lastChecked: Date.now() }
-      : { ok: false, reason: r.reason, error: r.error };
+    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() };
   }
 
   async *sync(opts = {}) {
+    if (typeof opts.inputPath === "string" && opts.inputPath.length > 0) {
+      yield* this._syncViaSnapshot(opts);
+      return;
+    }
+    if (this._cookieAuth) {
+      yield* this._syncViaCookie(opts);
+      return;
+    }
+    throw new Error(
+      "TaobaoAdapter.sync: needs opts.inputPath (snapshot mode, Android in-APK cc) OR opts.account.cookies (cookie mode)",
+    );
+  }
+
+  async *_syncViaSnapshot(opts) {
+    const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
+    let snapshot;
+    try {
+      snapshot = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(
+        `shopping-taobao.sync: snapshot must be JSON (v0.3 will add HTML parsing for SAF-exported pages). Got parse error: ${err.message}`,
+      );
+    }
+    if (
+      !snapshot ||
+      typeof snapshot !== "object" ||
+      snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION
+    ) {
+      throw new Error(
+        `shopping-taobao.sync: snapshot schemaVersion mismatch (got ${snapshot && snapshot.schemaVersion}, expected ${SNAPSHOT_SCHEMA_VERSION})`,
+      );
+    }
+    const fallbackCapturedAt =
+      Number.isFinite(snapshot.snapshottedAt) && snapshot.snapshottedAt > 0
+        ? Math.floor(snapshot.snapshottedAt)
+        : Date.now();
+    const account =
+      snapshot.account && typeof snapshot.account === "object"
+        ? snapshot.account
+        : null;
+    const include = opts.include || {};
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+
+    const events = Array.isArray(snapshot.events) ? snapshot.events : [];
+    let emitted = 0;
+    for (const ev of events) {
+      if (emitted >= limit) return;
+      if (!ev || typeof ev !== "object") continue;
+      const kind = ev.kind;
+      if (!VALID_SNAPSHOT_KINDS.includes(kind)) continue;
+      if (include[kind] === false) continue;
+
+      const capturedAt =
+        parseTime(ev.capturedAt) ||
+        parseTime(ev.placedAt) ||
+        parseTime(ev.paidAt) ||
+        fallbackCapturedAt;
+      const id =
+        (typeof ev.id === "string" && ev.id.length > 0 && ev.id) ||
+        ev.orderId ||
+        null;
+
+      yield {
+        adapter: NAME,
+        kind,
+        originalId: stableOriginalId(kind, id),
+        capturedAt,
+        payload: { ...ev, account },
+      };
+      emitted += 1;
+    }
+  }
+
+  async *_syncViaCookie(opts = {}) {
+    if (!this.account || !this.account.userId) {
+      throw new Error(
+        "TaobaoAdapter._syncViaCookie: account.userId required (set via new TaobaoAdapter({ account: { userId } }))",
+      );
+    }
     if (!(await this._cookieAuth.validate())) return;
     const sinceMs = opts.sinceWatermark != null
       ? parseWatermarkMs(opts.sinceWatermark)
@@ -97,16 +214,39 @@ class TaobaoAdapter {
   }
 
   normalize(raw) {
-    if (!raw || !raw.payload || !raw.payload.record) {
-      throw new Error("TaobaoAdapter.normalize: raw.payload.record missing");
+    if (!raw || !raw.payload) {
+      throw new Error("TaobaoAdapter.normalize: raw.payload missing");
+    }
+    // Snapshot mode payload is the raw event spread + account; cookie mode
+    // wraps a normalized record under payload.record. Dispatch on shape.
+    if (raw.payload.record) {
+      return normalizeOrderRecord(raw.payload.record, {
+        adapterName: NAME,
+        adapterVersion: VERSION,
+      });
     }
-    return normalizeOrderRecord(raw.payload.record, {
+    // Snapshot path: the Android collector ships records that already match
+    // the OrderRecord shape (vendorId/orderId/placedAt/...). Pass through.
+    return normalizeOrderRecord(raw.payload, {
       adapterName: NAME,
       adapterVersion: VERSION,
     });
   }
 }
 
+function parseTime(v) {
+  if (Number.isFinite(v) && v > 0) return v < 1e12 ? v * 1000 : v;
+  if (typeof v === "string") {
+    const t = Date.parse(v);
+    if (Number.isFinite(t)) return t;
+  }
+  return null;
+}
+
+function stableOriginalId(kind, id) {
+  return id ? `taobao:${kind}:${id}` : `taobao:${kind}:unknown-${Date.now()}`;
+}
+
 function orderToRecord(o) {
   if (!o || typeof o !== "object") return null;
   const orderId = o.bizOrderId || o.orderId || o.id;