@chainlesschain/personal-data-hub 0.3.1 → 0.3.7

package/__tests__/sign-providers.test.js

@@ -0,0 +1,62 @@
+"use strict";
+
+/**
+ * Phase 6a — SignProvider abstract + NullSignProvider unit cover.
+ */
+
+import { describe, it, expect } from "vitest";
+
+const {
+  SignProvider,
+  NullSignProvider,
+  NULL_SIGN_PROVIDER,
+} = require("../lib/sign-providers");
+
+describe("SignProvider abstract base", () => {
+  it("signUrl returns null by default", async () => {
+    const p = new SignProvider();
+    expect(await p.signUrl("https://example.com", "purpose")).toBe(null);
+  });
+
+  it("signedHeaders returns {} by default", async () => {
+    const p = new SignProvider();
+    const r = await p.signedHeaders("https://example.com", "purpose");
+    expect(r).toEqual({});
+  });
+
+  it("shutdown is no-op (no throw)", async () => {
+    const p = new SignProvider();
+    await expect(p.shutdown()).resolves.toBeUndefined();
+  });
+});
+
+describe("NullSignProvider", () => {
+  it("extends SignProvider", () => {
+    const p = new NullSignProvider();
+    expect(p).toBeInstanceOf(SignProvider);
+  });
+
+  it("inherits stub signUrl / signedHeaders / shutdown", async () => {
+    const p = new NullSignProvider();
+    expect(await p.signUrl("x", "y")).toBe(null);
+    expect(await p.signedHeaders("x", "y")).toEqual({});
+    await expect(p.shutdown()).resolves.toBeUndefined();
+  });
+
+  it("NULL_SIGN_PROVIDER is a frozen singleton", () => {
+    expect(NULL_SIGN_PROVIDER).toBeInstanceOf(NullSignProvider);
+    expect(Object.isFrozen(NULL_SIGN_PROVIDER)).toBe(true);
+  });
+
+  it("api-client pattern: call signUrl + signedHeaders without crash", async () => {
+    // Simulates api-client usage — signProvider.signUrl(url, purpose) ||
+    // fall back to unsigned URL; spread signedHeaders into request headers.
+    const provider = NULL_SIGN_PROVIDER;
+    const url = "https://api.example.com/x";
+    const signedUrl = (await provider.signUrl(url, "test")) || url;
+    expect(signedUrl).toBe(url); // null → fall back to original
+    const extraHeaders = await provider.signedHeaders(url, "test");
+    const finalHeaders = { Cookie: "x=y", ...extraHeaders };
+    expect(finalHeaders).toEqual({ Cookie: "x=y" }); // no extras from null provider
+  });
+});

package/__tests__/travel-adapters.test.js

@@ -299,6 +299,65 @@ describe("CtripAdapter", () => {
     expect(CTRIP_TYPE_MAP.train).toBe("train");
     expect(CTRIP_TYPE_MAP.cruise).toBe("cruise");
   });
+
+  // §9.3b v0.2 — no-arg ctor (auto-register at boot) + inputPath alias for
+  // Android in-APK cc syncAdapter("travel-ctrip", path). Earlier strict ctor
+  // (opts.account.email required) blocked the auto-register loop.
+
+  it("no-arg ctor passes contract (snapshot mode)", () => {
+    const a = new CtripAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("import:json"); // both kept
+  });
+
+  it("sync(inputPath) alias yields records same as dataPath", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ctrip-snap-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, JSON.stringify([
+      {
+        orderId: "C-SNAP-1", type: "flight",
+        depCity: "上海", arrCity: "北京",
+        flightNumber: "MU100", airline: "东航",
+        departureTime: "2026-05-01 08:00:00",
+        arrivalTime: "2026-05-01 10:30:00",
+        passengerName: "张三", price: 800, pnr: "XYZ",
+      },
+    ]), "utf-8");
+    try {
+      const a = new CtripAdapter();
+      const raws = [];
+      for await (const r of a.sync({ inputPath })) raws.push(r);
+      expect(raws).toHaveLength(1);
+      expect(raws[0].adapter).toBe("travel-ctrip");
+      expect(raws[0].originalId).toBe("C-SNAP-1");
+      const batch = a.normalize(raws[0]);
+      expect(validateBatch(batch).valid).toBe(true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("authenticate(ctx.inputPath) returns ok when file readable", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ctrip-auth-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, "[]", "utf-8");
+    try {
+      const a = new CtripAdapter();
+      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("authenticate(no path) ok with mode=ready (no account required)", async () => {
+    const a = new CtripAdapter();
+    const auth = await a.authenticate({});
+    expect(auth.ok).toBe(true);
+    expect(auth.mode).toBe("ready");
+  });
 });
 
 // ─── Amap adapter (mocked SQLite) ───────────────────────────────────────
@@ -310,6 +369,13 @@ describe("AmapAdapter", () => {
     expect(a.extractMode).toBe("device-pull");
   });
 
+  it("no-arg ctor passes contract (2026-05-25 v0.6 — account.deviceId OPTIONAL for snapshot mode)", () => {
+    const a = new AmapAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
+  });
+
   it("sync yields route + search records via mocked driver", async () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "amap-"));
     const dbPath = path.join(dir, "amap.db");

package/__tests__/whatsapp-adapter.test.js

@@ -43,8 +43,11 @@ describe("WhatsAppAdapter", () => {
     expect(a.dataDisclosure.legalGate).toBe(true);
   });
 
-  it("rejects missing account.phone", () => {
-    expect(() => new WhatsAppAdapter({ account: {} })).toThrow(/phone/);
+  it("no-arg ctor passes contract (2026-05-25 v0.6 — account.phone OPTIONAL for snapshot mode)", () => {
+    const a = new WhatsAppAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
   });
 
   it("authenticate fails without DB", async () => {

package/lib/adapters/browser-history-chrome/chrome-db-reader.js

@@ -12,7 +12,16 @@ const os = require("node:os");
 // better-sqlite3 tracks Node's ABI 127 (test path). Whichever loads
 // without NODE_MODULE_VERSION mismatch wins. Both expose the same
 // Database class for unencrypted DBs.
+//
+// CRITICAL: must be lazy. Calling at module-load time means any require()
+// of this file (e.g. via PDH wiring's eager `require("@chainlesschain/
+// personal-data-hub/adapters/browser-history-chrome")`) throws synchronously
+// when both modules are absent/ABI-mismatched, killing the entire main
+// process before the BrowserHistoryChromeAdapter try/catch in wiring.js
+// can swallow it. See v5.0.3.87 crash + handbook trap #23.
+let _cachedDatabaseClass = null;
 function loadDatabase() {
+  if (_cachedDatabaseClass) return _cachedDatabaseClass;
   for (const mod of ["better-sqlite3-multiple-ciphers", "better-sqlite3"]) {
     let cls;
     try {
@@ -27,6 +36,7 @@ function loadDatabase() {
     try {
       const probe = new cls(":memory:");
       probe.close();
+      _cachedDatabaseClass = cls;
       return cls;
     } catch (_e) {
       // ABI mismatch — try next candidate
@@ -36,7 +46,6 @@ function loadDatabase() {
     "chrome-db-reader: neither better-sqlite3-multiple-ciphers nor better-sqlite3 loaded — both ABI-mismatched",
   );
 }
-const Database = loadDatabase();
 
 // WebKit timestamps are microseconds since 1601-01-01 UTC. Convert to
 // epoch-ms by shifting the epoch (11644473600 seconds × 1e6 µs/s).
@@ -168,6 +177,7 @@ function* readVisits(tmpPath, opts = {}) {
     : 0n;
   const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 200_000;
   const includeHidden = opts.includeHidden === true;
+  const Database = loadDatabase();
   const db = new Database(tmpPath, { readonly: true });
   try {
     // Bind sinceWk as a string — better-sqlite3 accepts BigInt only when

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()