@chainlesschain/personal-data-hub 0.1.0 → 0.2.0

package/lib/adapters/email-imap/pdf-extractor.js

@@ -0,0 +1,192 @@
+/**
+ * Phase 5.5 — PDF text extractor with password-trial loop.
+ *
+ * Bank credit-card statements arrive as **encrypted** PDF attachments
+ * (~80% of Chinese issuers). Common password formats:
+ *   - 身份证后 6 位     (last 6 of national ID)
+ *   - 手机后 6 位       (last 6 of registered phone)
+ *   - 卡号尾 6 位       (last 6 of card number)
+ *   - 卡号尾 4 位       (last 4 of card number)
+ *   - 用户生日 YYYYMMDD (date of birth)
+ *
+ * Strategy (per design doc §6.2.1 + T4 in §12):
+ *   1. Try ALL passwords in the supplied list (user-config'd + adapter
+ *      heuristics) plus an empty-password attempt first (PDFs flagged
+ *      as `/Encrypt` but with empty owner-password decrypt successfully).
+ *   2. Return on FIRST success.
+ *   3. If every password fails, return `{ decrypted:false, attempted:N }`
+ *      so the caller can mark the bill as `unparsable` instead of
+ *      silently dropping it. The user can later add a password to
+ *      their list and re-run sync — the cached watermark plus
+ *      reclassification on retry will pick it up.
+ *
+ * Implementation:
+ *   - This module wraps `pdf-parse`. To avoid loading the heavy pdf.js
+ *     bundle at hub require-time (cold start cost for non-email
+ *     consumers), the dep is lazy-loaded on first call. `pdf-parse`
+ *     itself imports pdfjs-dist v1.10 internally.
+ *   - Callers may inject a custom `pdfParseImpl` for testing — this
+ *     keeps the unit tests entirely free of pdf-parse / pdfjs deps
+ *     (the real lib is pulled in only by integration / smoke).
+ *   - Outputs the first 200_000 chars of extracted text (same cap as
+ *     mailparser body output) so downstream LLM prompts stay sane.
+ *
+ * @typedef {object} PdfExtractResult
+ * @property {boolean} decrypted   true if SOME password (or no-password)
+ *                                 successfully opened the PDF.
+ * @property {string}  text        extracted plain text (empty when !decrypted)
+ * @property {string=} password    the password that worked, or undefined
+ *                                 if the PDF was not encrypted to begin
+ *                                 with. (Empty-string password used for
+ *                                 owner-password-only PDFs is reported as "".)
+ * @property {number}  attempted   count of password trials performed
+ * @property {boolean} wasEncrypted whether the PDF was actually encrypted
+ *                                  (vs `isEncrypted` heuristic returning
+ *                                  a false-positive — pdf-parse reports
+ *                                  this via `info.IsEncrypted`).
+ * @property {number}  pageCount   pages, when known.
+ * @property {string=} error       last error message if extraction failed
+ */
+
+"use strict";
+
+/**
+ * Extract text from a PDF buffer. Tries each candidate password until
+ * one works (or the list is exhausted). Never throws on bad passwords —
+ * returns `{decrypted:false}` so callers can mark the bill unparsable
+ * and surface a "missing password" hint to the UI.
+ *
+ * @param {Buffer} buffer        PDF bytes (required)
+ * @param {object} [opts]
+ * @param {string[]} [opts.passwords=[]] candidate passwords to try, in order
+ * @param {number}   [opts.maxTextChars=200000]
+ * @param {Function} [opts.pdfParseImpl] DI seam: `async (buf, {password?}) => {text, numpages, info?}`.
+ *                                       Defaults to lazy-loaded `pdf-parse`.
+ * @returns {Promise<PdfExtractResult>}
+ */
+async function extractPdfText(buffer, opts = {}) {
+  if (!Buffer.isBuffer(buffer)) {
+    return {
+      decrypted: false,
+      text: "",
+      attempted: 0,
+      wasEncrypted: false,
+      pageCount: 0,
+      error: "buffer required",
+    };
+  }
+  const maxTextChars = Number.isFinite(opts.maxTextChars) && opts.maxTextChars > 0
+    ? opts.maxTextChars
+    : 200_000;
+  const userPasswords = Array.isArray(opts.passwords) ? opts.passwords.filter((p) => typeof p === "string") : [];
+  const pdfParse = typeof opts.pdfParseImpl === "function" ? opts.pdfParseImpl : await loadPdfParse();
+
+  // Always attempt empty-password FIRST — pdf-parse treats undefined as
+  // "no password" and many "encrypted" bank PDFs use an empty owner
+  // password (only restricts editing, not decryption).
+  // Deduplicate while preserving order — user lists often include "".
+  const trial = ["", ...userPasswords].filter((v, i, arr) => arr.indexOf(v) === i);
+
+  let lastError = null;
+  let attempted = 0;
+  let wasEncrypted = false;
+
+  for (const pw of trial) {
+    attempted += 1;
+    try {
+      // pdf-parse accepts options.password (a string). Empty string is
+      // a valid argument and means "no password" to pdf.js.
+      const parsed = await pdfParse(buffer, { password: pw });
+      const info = parsed && parsed.info ? parsed.info : {};
+      if (info.IsEncrypted) wasEncrypted = true;
+      const text = trim((parsed && parsed.text) || "", maxTextChars);
+      return {
+        decrypted: true,
+        text,
+        password: pw === "" ? undefined : pw,
+        attempted,
+        wasEncrypted,
+        pageCount: (parsed && parsed.numpages) || 0,
+      };
+    } catch (err) {
+      lastError = err && err.message ? err.message : String(err);
+      // pdf-parse emits "PasswordException" / "InvalidPasswordException" on
+      // wrong password. Anything else (corrupt file, unsupported features)
+      // is also caught — we don't retry on those, but we mark wasEncrypted
+      // if the error string hints at it so the UI shows the right reason.
+      if (/password/i.test(lastError)) {
+        wasEncrypted = true;
+        continue; // try next candidate
+      }
+      // Non-password error → no point trying more passwords
+      return {
+        decrypted: false,
+        text: "",
+        attempted,
+        wasEncrypted,
+        pageCount: 0,
+        error: lastError,
+      };
+    }
+  }
+
+  return {
+    decrypted: false,
+    text: "",
+    attempted,
+    wasEncrypted: wasEncrypted || true, // exhausted all passwords → must be encrypted
+    pageCount: 0,
+    error: lastError || "all passwords failed",
+  };
+}
+
+/**
+ * Generate candidate passwords from per-user hints. Each input is an
+ * optional string from the user's profile (idCardLast6, phoneLast6,
+ * etc.); the function returns the non-empty values in priority order,
+ * deduplicated.
+ *
+ * @param {object} hints
+ * @param {string} [hints.idCardLast6]
+ * @param {string} [hints.phoneLast6]
+ * @param {string} [hints.cardLast6]
+ * @param {string} [hints.cardLast4]
+ * @param {string} [hints.dobYYYYMMDD]
+ * @returns {string[]}
+ */
+function passwordsFromHints(hints = {}) {
+  const order = ["idCardLast6", "phoneLast6", "cardLast6", "cardLast4", "dobYYYYMMDD"];
+  const out = [];
+  for (const k of order) {
+    const v = hints[k];
+    if (typeof v === "string" && v.length > 0 && !out.includes(v)) out.push(v);
+  }
+  return out;
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+function trim(s, max) {
+  if (typeof s !== "string") return "";
+  if (s.length <= max) return s;
+  return s.slice(0, max) + `…[truncated ${s.length - max} chars]`;
+}
+
+let _pdfParseCache = null;
+async function loadPdfParse() {
+  if (_pdfParseCache) return _pdfParseCache;
+  try {
+    // eslint-disable-next-line global-require
+    _pdfParseCache = require("pdf-parse");
+  } catch (err) {
+    throw new Error(
+      `pdf-parse not installed — Phase 5.5 PDF extraction needs it. ${err && err.message ? err.message : err}`
+    );
+  }
+  return _pdfParseCache;
+}
+
+module.exports = {
+  extractPdfText,
+  passwordsFromHints,
+};

package/lib/adapters/email-imap/templates/bill.js

@@ -0,0 +1,232 @@
+/**
+ * bill template extractor — Phase 5.4 of the Personal Data Hub.
+ *
+ * Handles emails classified as bill_bank or bill_credit. Pulls structured
+ * financial fields out of the body + headers so Phase 5.5 (PDF
+ * decryption) and the future spending analyzer have something to grip:
+ *
+ *   amount             { value, currency, direction? }
+ *   dueAmount          same shape — separate from `amount` so total-billed
+ *                      vs total-due aren't conflated
+ *   billingPeriod      { start: Date, end: Date } when both detected
+ *   dueDate            Date (always parsed from explicit "最后还款日" /
+ *                      "due date" keywords, never inferred)
+ *   accountIdentifier  "尾号 1234" / "**** 5678" — last 4 digits only
+ *   institution        sender display name OR domain root
+ *   billingMonth       "YYYY-MM" string (heuristic from subject + dueDate)
+ *
+ * Strategy:
+ *   1. Regex over textBody + subject — single pass, deterministic.
+ *   2. Pick the most-plausible amount via `selectPrimaryAmount`. When
+ *      both 应还/应付 and a generic amount are present, the directional
+ *      one wins.
+ *   3. If `opts.llm` provided AND regex coverage < 60%, ask the LLM to
+ *      fill gaps (Phase 5.4 leaves this as a stub — Phase 5.5 wires it
+ *      after we ground PDF-text against actual bank statements).
+ *
+ * Returns { template:"bill", fields, confidence, warnings }.
+ */
+
+"use strict";
+
+const {
+  extractAmounts,
+  extractDates,
+  extractAccountTails,
+  selectPrimaryAmount,
+  dateToMs,
+} = require("./utils");
+
+const DUE_DATE_KEYWORDS = /(最后还款日|还款日|账单到期日|due\s*date|payment\s*due|应还日期)\s*[:：]?\s*/i;
+const PERIOD_KEYWORDS = /(账单周期|账期|结账周期|billing\s*period|statement\s*period)\s*[:：]?\s*/i;
+const DUE_AMOUNT_KEYWORDS = /(应还金额|本期应还|本期欠款|应还合计|最低还款额|amount\s*due|total\s*due)\s*[:：]?\s*/i;
+
+/**
+ * @param {object} email — must include from/subject/textBody (or htmlBody)
+ * @param {object} [opts]
+ * @param {{chat:Function}} [opts.llm]
+ * @returns {Promise<{template:"bill",fields:object,confidence:number,warnings:string[]}>}
+ */
+async function extractBill(email, _opts = {}) {
+  const warnings = [];
+  const textParts = collectSearchableText(email);
+
+  // ── 1. amount + dueAmount ──────────────────────────────────────────
+  const allAmounts = textParts
+    .flatMap((t) => extractAmounts(t.body).map((a) => ({ ...a, source: t.label })));
+
+  // Find dueAmount via window around DUE_AMOUNT_KEYWORDS
+  let dueAmount = null;
+  for (const t of textParts) {
+    const m = t.body.match(DUE_AMOUNT_KEYWORDS);
+    if (!m) continue;
+    const after = t.body.slice(m.index + m[0].length, m.index + m[0].length + 40);
+    const a = extractAmounts(after)[0];
+    if (a) {
+      dueAmount = { value: a.value, currency: a.currency, raw: a.raw };
+      break;
+    }
+  }
+
+  const primary = selectPrimaryAmount(allAmounts);
+  const amount = primary
+    ? { value: primary.value, currency: primary.currency, direction: primary.direction || "out" }
+    : null;
+  if (!amount) warnings.push("no monetary amount detected");
+
+  // ── 2. dueDate ─────────────────────────────────────────────────────
+  let dueDate = null;
+  for (const t of textParts) {
+    const m = t.body.match(DUE_DATE_KEYWORDS);
+    if (!m) continue;
+    // Search the next 40 chars for a date
+    const after = t.body.slice(m.index + m[0].length, m.index + m[0].length + 40);
+    const dates = extractDates(after);
+    if (dates.length > 0) {
+      dueDate = dates[0].date;
+      break;
+    }
+  }
+
+  // ── 3. billingPeriod ───────────────────────────────────────────────
+  let billingPeriod = null;
+  for (const t of textParts) {
+    const m = t.body.match(PERIOD_KEYWORDS);
+    if (!m) continue;
+    const after = t.body.slice(m.index + m[0].length, m.index + m[0].length + 80);
+    const dates = extractDates(after);
+    if (dates.length >= 2) {
+      billingPeriod = { start: dates[0].date, end: dates[1].date };
+      break;
+    }
+  }
+
+  // ── 4. account identifier (last 4) ────────────────────────────────
+  const tails = textParts.flatMap((t) => extractAccountTails(t.body));
+  const accountIdentifier = tails.length > 0 ? `**** ${tails[0].last4}` : null;
+
+  // ── 5. institution — from sender display name, fall back to domain ─
+  const institution = resolveInstitution(email);
+
+  // ── 6. billingMonth heuristic ──────────────────────────────────────
+  let billingMonth = null;
+  if (billingPeriod && billingPeriod.start instanceof Date) {
+    billingMonth = formatMonthKey(billingPeriod.start);
+  } else if (dueDate instanceof Date) {
+    // "11 月对账单 due 12-25" → bill is for month BEFORE due
+    const prev = new Date(dueDate);
+    prev.setMonth(prev.getMonth() - 1);
+    billingMonth = formatMonthKey(prev);
+  } else {
+    const m = (email.subject || "").match(/(\d{1,2})\s*月.*(?:对账单|月结|账单)/);
+    if (m) {
+      const month = +m[1];
+      const now = new Date();
+      const year = month > now.getMonth() + 1 ? now.getFullYear() - 1 : now.getFullYear();
+      billingMonth = formatMonthKey(new Date(year, month - 1, 1));
+    }
+  }
+
+  const fields = {
+    ...(amount ? { amount } : {}),
+    ...(dueAmount ? { dueAmount } : {}),
+    ...(dueDate ? { dueDate: dateToMs(dueDate) } : {}),
+    ...(billingPeriod
+      ? {
+          billingPeriod: {
+            startMs: dateToMs(billingPeriod.start),
+            endMs: dateToMs(billingPeriod.end),
+          },
+        }
+      : {}),
+    ...(accountIdentifier ? { accountIdentifier } : {}),
+    ...(institution ? { institution } : {}),
+    ...(billingMonth ? { billingMonth } : {}),
+  };
+
+  return {
+    template: "bill",
+    fields,
+    confidence: confidenceFor(fields),
+    warnings,
+  };
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+function collectSearchableText(email) {
+  const parts = [];
+  if (email.subject) parts.push({ label: "subject", body: email.subject });
+  if (email.textBody) parts.push({ label: "textBody", body: email.textBody });
+  if (email.htmlBody && !email.textBody) parts.push({ label: "htmlBody", body: stripHtml(email.htmlBody) });
+  return parts;
+}
+
+function stripHtml(html) {
+  return String(html)
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/\s+/g, " ");
+}
+
+function resolveInstitution(email) {
+  if (Array.isArray(email.from) && email.from[0]) {
+    if (email.from[0].name) return email.from[0].name;
+    const addr = email.from[0].address || "";
+    const at = addr.lastIndexOf("@");
+    if (at >= 0) {
+      const domain = addr.slice(at + 1).toLowerCase();
+      // Map known bank domains to friendly names
+      const known = {
+        "cmbchina.com": "招商银行",
+        "ccb.com.cn": "建设银行",
+        "boc.cn": "中国银行",
+        "bochk.cn": "中国银行",
+        "bochk.com": "中国银行",
+        "icbc.com.cn": "工商银行",
+        "psbc.com": "邮储银行",
+        "abchina.com": "农业银行",
+        "bankcomm.com": "交通银行",
+        "spdb.com.cn": "浦发银行",
+        "cmbc.com.cn": "民生银行",
+        "cebbank.com": "光大银行",
+        "citicbank.com": "中信银行",
+        "hxb.com.cn": "华夏银行",
+      };
+      if (known[domain]) return known[domain];
+      // Try parent domain (e.g. credit.boc.cn → boc.cn)
+      const parts = domain.split(".");
+      if (parts.length > 2) {
+        const parent = parts.slice(-2).join(".");
+        if (known[parent]) return known[parent];
+      }
+      return domain;
+    }
+  }
+  return null;
+}
+
+function formatMonthKey(d) {
+  if (!(d instanceof Date)) return null;
+  const y = d.getFullYear();
+  const m = d.getMonth() + 1;
+  return `${y}-${String(m).padStart(2, "0")}`;
+}
+
+/**
+ * Confidence: count of populated fields / total. Coarse but useful as
+ * a UI badge and as a switch for whether to fire Layer 2 LLM (TODO 5.5).
+ */
+function confidenceFor(fields) {
+  const tracked = [
+    "amount", "dueAmount", "dueDate", "billingPeriod",
+    "accountIdentifier", "institution", "billingMonth",
+  ];
+  const populated = tracked.filter((k) => fields[k] != null).length;
+  return Math.round((populated / tracked.length) * 100) / 100;
+}
+
+module.exports = { extractBill };

package/lib/adapters/email-imap/templates/government.js

@@ -0,0 +1,120 @@
+/**
+ * government template extractor — Phase 5.4.
+ *
+ * Fields:
+ *   agencyName       sender display or known *.gov.cn registrar
+ *   documentType     tax_declaration / social_security / housing_fund /
+ *                    real_estate / immigration / health_insurance / other
+ *   period           "YYYY-MM" when keyword-tagged month found
+ *   amount           { value, currency } if monetary content (e.g.
+ *                    tax declaration confirmations include a paid amount)
+ *   referenceNumber  receipt / 申报编号 / 文号
+ */
+
+"use strict";
+
+const {
+  extractAmounts,
+  selectPrimaryAmount,
+  extractOrderNumbers,
+} = require("./utils");
+
+const DOC_TYPE_KEYWORDS = [
+  { type: "tax_declaration",  patterns: [/(完税|个税|纳税申报|增值税|enterprise\s*income\s*tax)/i] },
+  { type: "social_security",  patterns: [/(社保|社会保险|医疗保险|工伤|生育|失业)/i] },
+  { type: "housing_fund",     patterns: [/(住房公积金|公积金|housing\s*fund)/i] },
+  { type: "real_estate",      patterns: [/(不动产登记|房产证|产权登记|real\s*estate\s*registration)/i] },
+  { type: "immigration",      patterns: [/(出入境|护照|签证|户籍|户口|immigration)/i] },
+  { type: "health_insurance", patterns: [/(医保|医疗保险卡)/i] },
+];
+
+const REF_NUMBER_KEYWORDS = /(申报编号|文号|receipt\s*number|reference\s*number|案卷号|流水号)\s*[:：]?\s*([A-Z0-9][-A-Z0-9]{4,30})/i;
+const PERIOD_KEYWORDS = /(税期|缴费月份|缴款期间|属期|期间)\s*[:：]?\s*(\d{4})(?:[-/.年]|\s)\s*(\d{1,2})/i;
+
+async function extractGovernment(email, _opts = {}) {
+  const warnings = [];
+  const combined = collectSearchableText(email);
+
+  // ── documentType ─────────────────────────────────────────────────
+  let documentType = null;
+  for (const d of DOC_TYPE_KEYWORDS) {
+    if (d.patterns.some((re) => re.test(combined))) {
+      documentType = d.type;
+      break;
+    }
+  }
+  if (!documentType) documentType = "other";
+
+  // ── agency ───────────────────────────────────────────────────────
+  let agencyName = null;
+  if (Array.isArray(email.from) && email.from[0]) {
+    if (email.from[0].name) {
+      agencyName = email.from[0].name;
+    } else {
+      const addr = (email.from[0].address || "").toLowerCase();
+      const at = addr.lastIndexOf("@");
+      if (at >= 0) agencyName = addr.slice(at + 1);
+    }
+  }
+
+  // ── period (YYYY-MM) ─────────────────────────────────────────────
+  let period = null;
+  const periodMatch = combined.match(PERIOD_KEYWORDS);
+  if (periodMatch) {
+    const y = +periodMatch[2];
+    const mo = +periodMatch[3];
+    if (y >= 1970 && y <= 2099 && mo >= 1 && mo <= 12) {
+      period = `${y}-${String(mo).padStart(2, "0")}`;
+    }
+  }
+
+  // ── amount (e.g. tax paid / fee charged) ─────────────────────────
+  const amounts = extractAmounts(combined);
+  const primary = selectPrimaryAmount(amounts);
+  const amount = primary ? { value: primary.value, currency: primary.currency } : null;
+
+  // ── reference number ──────────────────────────────────────────────
+  let referenceNumber = null;
+  const refMatch = combined.match(REF_NUMBER_KEYWORDS);
+  if (refMatch) {
+    referenceNumber = refMatch[2];
+  } else {
+    const orderHits = extractOrderNumbers(combined);
+    if (orderHits.length > 0) referenceNumber = orderHits[0].orderNumber;
+  }
+
+  if (documentType === "other") warnings.push("documentType could not be narrowed");
+
+  const fields = {
+    documentType,
+    ...(agencyName ? { agencyName } : {}),
+    ...(period ? { period } : {}),
+    ...(amount ? { amount } : {}),
+    ...(referenceNumber ? { referenceNumber } : {}),
+  };
+
+  return {
+    template: "government",
+    fields,
+    confidence: confidenceFor(fields),
+    warnings,
+  };
+}
+
+function collectSearchableText(email) {
+  const parts = [];
+  if (email.subject) parts.push(email.subject);
+  if (email.textBody) parts.push(email.textBody);
+  else if (email.htmlBody) {
+    parts.push(String(email.htmlBody).replace(/<[^>]+>/g, " "));
+  }
+  return parts.join("\n");
+}
+
+function confidenceFor(fields) {
+  const tracked = ["documentType", "agencyName", "period", "amount", "referenceNumber"];
+  const populated = tracked.filter((k) => fields[k] != null && fields[k] !== "other").length;
+  return Math.round((populated / tracked.length) * 100) / 100;
+}
+
+module.exports = { extractGovernment };

package/lib/adapters/email-imap/templates/index.js

@@ -0,0 +1,78 @@
+/**
+ * Phase 5.4 — template dispatcher.
+ *
+ * Routes a classified email through the appropriate field extractor:
+ *
+ *   bill_bank / bill_credit  → bill
+ *   order                    → order
+ *   travel                   → travel
+ *   government               → government
+ *   register                 → register
+ *   notify / other / null    → other
+ *
+ * The dispatcher is the SINGLE entry point used by EmailAdapter.sync —
+ * adding a new category later means adding a row to CATEGORY_TO_EXTRACTOR
+ * and a new file, no other change.
+ */
+
+"use strict";
+
+const { extractBill } = require("./bill");
+const { extractOrder } = require("./order");
+const { extractTravel } = require("./travel");
+const { extractGovernment } = require("./government");
+const { extractRegister } = require("./register");
+const { extractOther } = require("./other");
+
+const CATEGORY_TO_EXTRACTOR = Object.freeze({
+  bill_bank: extractBill,
+  bill_credit: extractBill,
+  order: extractOrder,
+  travel: extractTravel,
+  government: extractGovernment,
+  register: extractRegister,
+  notify: extractOther,
+  other: extractOther,
+});
+
+/**
+ * Dispatch by classification.category. Always returns a result —
+ * unknown categories fall through to the `other` extractor.
+ *
+ * @param {object} email — same shape EmailAdapter uses internally:
+ *   { from, subject, textBody, htmlBody, headers, attachments }
+ * @param {object} classification — Phase 5.3 result; `{category}` minimum
+ * @param {object} [opts]
+ * @param {{chat:Function}} [opts.llm]   LLM (currently only used by `other`)
+ * @returns {Promise<{template:string,fields:object,confidence:number,warnings:string[]}>}
+ */
+async function extractFields(email, classification, opts = {}) {
+  if (!email || typeof email !== "object") {
+    return { template: "other", fields: {}, confidence: 0, warnings: ["email missing"] };
+  }
+  const category = classification && classification.category;
+  const extractor = CATEGORY_TO_EXTRACTOR[category] || extractOther;
+  try {
+    return await extractor(email, opts);
+  } catch (err) {
+    return {
+      template: extractor === extractOther ? "other" : (category || "other"),
+      fields: {},
+      confidence: 0,
+      warnings: [`extractor threw: ${err && err.message ? err.message : err}`],
+    };
+  }
+}
+
+module.exports = {
+  extractFields,
+  CATEGORY_TO_EXTRACTOR,
+  // Direct re-exports so callers needing one specific extractor can
+  // bypass the dispatcher (handy in tests).
+  extractBill,
+  extractOrder,
+  extractTravel,
+  extractGovernment,
+  extractRegister,
+  extractOther,
+};