@plan-fi/imports 0.6.0

package/src/adapters/mx.mjs

@@ -0,0 +1,159 @@
+// mx.mjs — MX Platform → Canonical Financial Profile.
+//
+// Consumes MX API entities (already fetched by the caller):
+//   /users/{u}/accounts      → accounts[]
+//   /users/{u}/holdings      → holdings[]
+//   /users/{u}/transactions  → transactions[]  (optional; drives contributions)
+// MX encodes the account family in `type` (CHECKING, INVESTMENT, MORTGAGE,
+// PROPERTY, …) and refines investment tax treatment in `subtype`. We translate
+// MX's vocabulary into the generic (type, subtype) that classify() understands,
+// then reuse the same classifier + the same shared to-planfi mapper.
+//
+// MX advantage over Plaid: a PROPERTY account carries the home's MARKET VALUE,
+// so mortgages can be paired to a real value instead of asking the user.
+//
+// @typedef {import('../canonical').CanonicalFinancialProfile} CFP
+// @typedef {import('../canonical').SourceAdapter} SourceAdapter
+
+import { classify, classifyAsset } from '../classify.mjs';
+import { contributionsByAccount } from '../contributions.mjs';
+import { arr, objs, num, pct, groupBy, monthsBetween, defaultAsOf, warning } from '../util.mjs';
+
+// MX credit-transaction categories/descriptions that are savings INFLOWS
+// (counted) vs investment GROWTH (excluded — already modeled by annual_return).
+const MX_INFLOW = /transfer|deposit|contribution|payroll|direct dep/i;
+const MX_GROWTH = /dividend|interest|capital gain|reinvest/i;
+
+// MX top-level `type` → generic { type, subtype? } that classify() consumes.
+const MX_TYPE = {
+  CHECKING: ['depository', 'checking'],
+  SAVINGS: ['depository', 'savings'],
+  MONEY_MARKET: ['depository', 'money market'],
+  CD: ['depository', 'cd'],
+  CASH: ['depository', 'cash'],
+  PREPAID: ['depository', 'cash'],
+  INVESTMENT: ['investment', undefined],
+  LOAN: ['loan', undefined],
+  MORTGAGE: ['loan', 'mortgage'],
+  CREDIT_CARD: ['credit', 'credit card'],
+  LINE_OF_CREDIT: ['credit', 'line of credit'],
+  PROPERTY: ['property', undefined],
+};
+
+/** @implements {SourceAdapter} */
+export const mxAdapter = {
+  source: 'mx',
+  /**
+   * @param {object} raw - { accounts, holdings, transactions, owner, asOf }
+   * @returns {CFP}
+   */
+  normalize(raw) {
+    // Total function: null/primitive payloads normalize to an empty profile
+    // (a default parameter only covers `undefined` — the contract harness
+    // caught the null case throwing).
+    raw = raw && typeof raw === 'object' ? raw : {};
+    const warnings = [];
+    const unmapped = [];
+    const accountsIn = objs(raw.accounts);
+    const holdingsByAccount = groupBy(objs(raw.holdings), (h) => h.account_guid);
+
+    // Contributions: MX CREDITs into investment accounts are candidate inflows.
+    // Filter by category/description so growth (dividends/interest/reinvest)
+    // isn't double-counted as savings; when a credit carries NO category or
+    // description we count it but warn once that the inference is coarse.
+    const invGuids = new Set(accountsIn.filter((a) => up(a.type) === 'INVESTMENT').map((a) => a.guid));
+    let sawUnlabeledCredit = false;
+    const normTxns = objs(raw.transactions)
+      .filter((t) => {
+        if (!invGuids.has(t.account_guid) || up(t.type) !== 'CREDIT') return false;
+        const label = `${t.category ?? ''} ${t.description ?? ''} ${t.top_level_category ?? ''}`.trim();
+        if (!label) { sawUnlabeledCredit = true; return true; } // no signal → coarse include
+        if (MX_GROWTH.test(label)) return false;                // dividends/interest = growth
+        return MX_INFLOW.test(label);                           // labeled but neither → exclude
+      })
+      .map((t) => ({ account_id: t.account_guid, subtype: 'contribution', amount: -Math.abs(num(t.amount)), date: t.date || t.transacted_at }));
+    if (sawUnlabeledCredit) {
+      warnings.push(warning('COARSE_INFERENCE', 'warn',
+        'MX contribution inference is coarse: some investment-account credits carry no category/description, so ALL such unlabeled credits were counted as contributions (may include dividends or rollovers). Verify inferred contribution rates.'));
+    }
+    const contribByAccount = contributionsByAccount(normTxns);
+
+    const accounts = accountsIn.map((a) => {
+      const [genType, genSub] = MX_TYPE[up(a.type)] ?? ['investment', undefined];
+      // MX investment subtype (401K, ROTH_IRA, HSA, 529…) → words classify() knows.
+      const subtype = genSub ?? mxSubtype(a.subtype) ?? inferLoanSubtype(a.name);
+      const { accountClass, taxTreatment, confidence } = classify(genType === 'property' ? 'investment' : genType, subtype);
+      const cls = genType === 'property' ? 'property' : accountClass;
+      if (confidence === 'low' && cls !== 'property') {
+        warnings.push(warning('CLASSIFICATION_GUESSED', 'warn',
+          `MX account "${a.name ?? a.guid}" (${a.type}/${a.subtype ?? ''}) classification guessed → ${cls}/${taxTreatment}.`, a.guid));
+      }
+
+      const acct = {
+        id: a.guid,
+        institution: a.institution_code,
+        name: a.name,
+        class: cls,
+        subtype: String(subtype ?? '').toLowerCase(),
+        taxTreatment: cls === 'property' ? 'na' : taxTreatment,
+        balance: num(a.balance) || num(a.market_value) || num(a.available_balance) || 0,
+        currency: a.currency_code ?? 'USD',
+        ownerIndex: Number.isInteger(a.owner_index) ? a.owner_index : 0,
+        ...(contribByAccount[a.guid] ? { estMonthlyContribution: contribByAccount[a.guid] } : {}),
+      };
+
+      if (cls === 'investment') {
+        const hs = holdingsByAccount.get(a.guid) ?? [];
+        acct.holdings = hs.map((h) => {
+          if (h.cost_basis == null) {
+            warnings.push(warning('NO_COST_BASIS', 'info',
+              `Holding ${h.symbol ?? h.description ?? h.guid} has no cost basis (MX did not report it).`, a.guid));
+          }
+          return {
+            ticker: h.symbol ?? undefined,
+            name: h.description ?? undefined,
+            quantity: num(h.shares),
+            value: num(h.market_value),
+            costBasis: h.cost_basis == null ? undefined : num(h.cost_basis),
+            assetType: classifyAsset(h.holding_type),
+          };
+        });
+      }
+      if (cls === 'loan' || cls === 'credit') {
+        acct.liability = {
+          rate: pct(a.interest_rate ?? a.apr),
+          minPayment: num(a.minimum_payment) || undefined,
+          originationPrincipal: num(a.original_balance) || undefined,
+          monthsRemaining: monthsBetween(raw.asOf, a.maturity_date),
+          ...(subtype === 'mortgage' ? { assetName: a.name || 'Home' } : {}),
+        };
+      }
+      return acct;
+    });
+
+    return {
+      source: 'mx',
+      // Default snapshot time is NOW (not the 1970 epoch — see util.mjs).
+      asOf: raw.asOf || defaultAsOf(),
+      owner: { ...(raw.owner ?? {}) },
+      accounts,
+      meta: { warnings, unmapped },
+    };
+  },
+};
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+// (arr/num/pct/groupBy/monthsBetween live in ../util.mjs, shared with plaid.mjs.)
+const up = (x) => String(x ?? '').trim().toUpperCase();
+/** MX investment subtype enum → classify()-friendly words. */
+function mxSubtype(sub) {
+  if (!sub) return undefined;
+  return String(sub).toLowerCase().replace(/_/g, ' ');
+}
+function inferLoanSubtype(name) {
+  const n = String(name ?? '').toLowerCase();
+  if (/student/.test(n)) return 'student';
+  if (/auto|car|vehicle/.test(n)) return 'auto';
+  if (/mortgage|home/.test(n)) return 'mortgage';
+  return undefined;
+}

package/src/adapters/ofx.mjs

@@ -0,0 +1,324 @@
+// ofx.mjs — OFX files → Canonical Financial Profile. The other KEYLESS path:
+// OFX (Open Financial Exchange) is the "Download → Quicken/Money" format that
+// nearly every US bank/broker still exports, in two syntaxes:
+//   - OFX 1.x: SGML — a `KEY:VALUE` header block, then tags whose LEAVES ARE
+//     NEVER CLOSED (`<BALAMT>1234.56` on its own line)
+//   - OFX 2.x: XML — an XML prolog, then the same tag vocabulary fully closed
+//
+// Input contract: { content: string (either syntax), owner, asOf }.
+//
+// The tolerant parser here handles both with one pass (see parseOfx): open
+// tags with trailing text are leaves; close tags pop tolerantly (a close with
+// no matching open is ignored, unclosed aggregates are fine). It never throws.
+//
+// What is extracted (per the OFX 2.2 spec sections noted):
+//   - BANKMSGSRSV1 → STMTRS (11.4): BANKACCTFROM.ACCTTYPE (CHECKING/SAVINGS/
+//     MONEYMRKT/CD/CREDITLINE) + LEDGERBAL.BALAMT → depository accounts
+//     (CREDITLINE → credit class); STMTTRN transactions are bank cash flow,
+//     NOT savings-rate signal, so they are ignored for contribution inference.
+//   - CREDITCARDMSGSRSV1 → CCSTMTRS (11.4.3): card balances. OFX REPORTS CARD
+//     BALANCES NEGATIVE (amount owed as a negative ledger balance) — the
+//     adapter normalizes to POSITIVE amount owed (|BALAMT|), covered by a test.
+//   - INVSTMTMSGSRSV1 → INVSTMTRS (13.9): INVACCTFROM, INVPOSLIST positions
+//     (POSSTOCK/POSMF/POSDEBT/POSOTHER → the INVPOS inside each: SECID lookup
+//     against SECLISTMSGSRSV1 for ticker/name, UNITS, MKTVAL), INVBAL.AVAILCASH,
+//     and INVTRANLIST for contribution inference: INVBANKTRAN deposits are
+//     candidate contributions (same growth-exclusion rules as the siblings —
+//     INCOME/REINVEST records are growth, unlabeled deposits are counted
+//     coarsely + COARSE_INFERENCE); BUY*/SELL* records are internal to the
+//     account and never counted.
+//
+// Honesty rules: OFX CARRIES NO TAX-TREATMENT INFO — an investment statement
+// says "brokerage at broker X", never "this is a Roth IRA". Every investment
+// account is therefore classified taxable at LOW confidence with a
+// CLASSIFICATION_GUESSED warning; nothing is fabricated. OFX also carries no
+// account names — accounts are labeled from type + masked ACCTID.
+//
+// Only OFX quirk-handling lives here; ALL Planfi domain logic stays in
+// to-planfi.mjs, shared with every other adapter.
+//
+// @typedef {import('../canonical').CanonicalFinancialProfile} CFP
+// @typedef {import('../canonical').SourceAdapter} SourceAdapter
+
+import { classify } from '../classify.mjs';
+import { contributionsByAccount } from '../contributions.mjs';
+import { arr, num, defaultAsOf, warning } from '../util.mjs';
+
+// Same inflow/growth split as the CSV/MX/Finicity adapters, plus OFX TRNTYPEs.
+const OFX_INFLOW = /transfer|deposit|contribution|payroll|direct dep|\bdep\b|credit|xfer/i;
+const OFX_GROWTH = /dividend|interest|capital gain|reinvest|\bdiv\b|\bint\b/i;
+
+/** @implements {SourceAdapter} */
+export const ofxAdapter = {
+  source: 'ofx',
+  /**
+   * @param {object} raw - { content: string (OFX 1.x SGML or 2.x XML), owner, asOf }
+   * @returns {CFP}
+   */
+  normalize(raw) {
+    // Total function: null/primitive payloads normalize to an empty profile
+    // (a default parameter only covers `undefined` — the contract harness
+    // caught the null case throwing).
+    raw = raw && typeof raw === 'object' ? raw : {};
+    const warnings = [];
+    const unmapped = [];
+    const accounts = [];
+    const root = parseOfx(raw.content);
+    let statementAsOf; // best DTASOF seen, used when the caller passed no asOf
+
+    // ── security list (SECLISTMSGSRSV1) — UNIQUEID → { ticker, name, type } ──
+    const securities = new Map();
+    for (const wrapTag of ['STOCKINFO', 'MFINFO', 'DEBTINFO', 'OPTINFO', 'OTHERINFO']) {
+      for (const info of findAll(root, wrapTag)) {
+        const uid = val(info, 'UNIQUEID');
+        if (!uid) continue;
+        securities.set(uid, {
+          ticker: val(info, 'TICKER'),
+          name: val(info, 'SECNAME'),
+          assetType: { STOCKINFO: 'equity', MFINFO: 'mutual_fund', DEBTINFO: 'bond', OPTINFO: 'other', OTHERINFO: 'other' }[wrapTag],
+        });
+      }
+    }
+
+    // ── bank statements (STMTRS) ─────────────────────────────────────────────
+    for (const stmt of findAll(root, 'STMTRS')) {
+      const acctFrom = find(stmt, 'BANKACCTFROM') ?? stmt;
+      const acctId = val(acctFrom, 'ACCTID') || `bank:${accounts.length}`;
+      const acctType = (val(acctFrom, 'ACCTTYPE') || 'CHECKING').toUpperCase();
+      const ledger = find(stmt, 'LEDGERBAL');
+      statementAsOf ??= ofxDateIso(val(ledger, 'DTASOF'));
+      const balance = num(val(ledger, 'BALAMT') ?? val(find(stmt, 'AVAILBAL'), 'BALAMT'));
+      if (acctType === 'CREDITLINE') {
+        // A credit line under the bank message set is revolving debt, not cash.
+        accounts.push({
+          id: acctId,
+          name: `Credit line ${mask(acctId)}`,
+          class: 'credit',
+          subtype: 'line of credit',
+          taxTreatment: 'na',
+          balance: Math.abs(balance),
+          currency: val(stmt, 'CURDEF') || 'USD',
+          ownerIndex: 0,
+          liability: { rate: undefined }, // OFX bank statements carry no APR
+        });
+        continue;
+      }
+      const { accountClass, taxTreatment } = classify('depository', acctType.toLowerCase().replace('moneymrkt', 'money market'));
+      accounts.push({
+        id: acctId,
+        name: `${title(acctType)} ${mask(acctId)}`,
+        class: accountClass,
+        subtype: acctType.toLowerCase(),
+        taxTreatment,
+        balance,
+        currency: val(stmt, 'CURDEF') || 'USD',
+        ownerIndex: 0,
+      });
+    }
+
+    // ── credit card statements (CCSTMTRS) ────────────────────────────────────
+    for (const stmt of findAll(root, 'CCSTMTRS')) {
+      const acctId = val(find(stmt, 'CCACCTFROM') ?? stmt, 'ACCTID') || `card:${accounts.length}`;
+      const ledger = find(stmt, 'LEDGERBAL');
+      statementAsOf ??= ofxDateIso(val(ledger, 'DTASOF'));
+      // OFX reports the amount owed as a NEGATIVE ledger balance; the canonical
+      // model (and the shared mapper) wants outstanding principal as a
+      // positive number — normalize with |x| so a debt can't vanish.
+      const owed = Math.abs(num(val(ledger, 'BALAMT')));
+      accounts.push({
+        id: acctId,
+        name: `Credit card ${mask(acctId)}`,
+        class: 'credit',
+        subtype: 'credit card',
+        taxTreatment: 'na',
+        balance: owed,
+        currency: val(stmt, 'CURDEF') || 'USD',
+        ownerIndex: 0,
+        liability: { rate: undefined }, // OFX card statements carry no APR → mapper asks via needsInput
+      });
+    }
+
+    // ── investment statements (INVSTMTRS) ────────────────────────────────────
+    let sawUnlabeledDeposit = false;
+    const normTxns = [];
+    for (const stmt of findAll(root, 'INVSTMTRS')) {
+      const acctFrom = find(stmt, 'INVACCTFROM') ?? stmt;
+      const acctId = val(acctFrom, 'ACCTID') || `inv:${accounts.length}`;
+      const broker = val(acctFrom, 'BROKERID');
+      statementAsOf ??= ofxDateIso(val(stmt, 'DTASOF'));
+
+      const holdings = [];
+      for (const posTag of ['POSSTOCK', 'POSMF', 'POSDEBT', 'POSOPT', 'POSOTHER']) {
+        for (const pos of findAll(stmt, posTag)) {
+          const uid = val(pos, 'UNIQUEID');
+          const sec = (uid && securities.get(uid)) || {};
+          if (uid && !securities.get(uid)) {
+            unmapped.push({ ofx: posTag, uniqueId: uid, reason: 'SECID not found in SECLISTMSGSRSV1' });
+          }
+          holdings.push({
+            ticker: sec.ticker || undefined,
+            name: sec.name || undefined,
+            quantity: num(val(pos, 'UNITS')),
+            value: num(val(pos, 'MKTVAL')),
+            costBasis: undefined, // OFX positions carry no cost basis
+            assetType: sec.assetType
+              ?? { POSSTOCK: 'equity', POSMF: 'mutual_fund', POSDEBT: 'bond', POSOPT: 'other', POSOTHER: 'other' }[posTag],
+          });
+        }
+      }
+      if (holdings.length) {
+        // Structural to the format (not per-institution like the API adapters),
+        // so ONE info note per account instead of one per holding.
+        warnings.push(warning('NO_COST_BASIS', 'info',
+          `${holdings.length} holding(s) in ${mask(acctId)} imported without cost basis — OFX position records don't carry one.`, acctId));
+      }
+
+      const availCash = num(val(find(stmt, 'INVBAL'), 'AVAILCASH'));
+      const balance = holdings.reduce((n, h) => n + (Number.isFinite(h.value) ? h.value : 0), 0) + availCash;
+
+      // OFX has no tax-treatment vocabulary → taxable at LOW confidence, warned.
+      const { accountClass, taxTreatment } = classify('investment', undefined);
+      warnings.push(warning('CLASSIFICATION_GUESSED', 'warn',
+        `OFX investment account ${mask(acctId)}${broker ? ` at ${broker}` : ''}: OFX carries no tax-treatment info (no way to tell a Roth IRA from a brokerage) — classified ${accountClass}/${taxTreatment} at low confidence. Reclassify if it is a retirement account.`, acctId));
+
+      accounts.push({
+        id: acctId,
+        institution: broker || undefined,
+        name: `Investment ${mask(acctId)}`,
+        class: accountClass,
+        subtype: '',
+        taxTreatment,
+        balance,
+        currency: val(stmt, 'CURDEF') || 'USD',
+        ownerIndex: 0,
+        holdings,
+      });
+
+      // Contribution inference: money moving INTO the investment account from
+      // outside = INVBANKTRAN deposits. INCOME/REINVEST are growth (excluded);
+      // BUY*/SELL* are internal (never counted).
+      for (const bankTran of findAll(stmt, 'INVBANKTRAN')) {
+        const trn = find(bankTran, 'STMTTRN') ?? bankTran;
+        const amount = num(val(trn, 'TRNAMT'));
+        if (!(amount > 0)) continue;
+        const label = `${val(trn, 'TRNTYPE') ?? ''} ${val(trn, 'NAME') ?? ''} ${val(trn, 'MEMO') ?? ''}`.trim();
+        if (!label) { sawUnlabeledDeposit = true; }
+        else if (OFX_GROWTH.test(label)) continue;
+        else if (!OFX_INFLOW.test(label)) continue;
+        normTxns.push({
+          account_id: acctId,
+          subtype: 'contribution',
+          amount: -Math.abs(amount),
+          date: ofxDateIso(val(trn, 'DTPOSTED')),
+        });
+      }
+    }
+    if (sawUnlabeledDeposit) {
+      warnings.push(warning('COARSE_INFERENCE', 'warn',
+        'OFX contribution inference is coarse: some investment-account deposits carry no TRNTYPE/NAME/MEMO, so ALL such unlabeled deposits were counted as contributions (may include dividends or rollovers). Verify inferred contribution rates.'));
+    }
+    const contribByAccount = contributionsByAccount(normTxns);
+    for (const a of accounts) {
+      if (contribByAccount[a.id]) a.estMonthlyContribution = contribByAccount[a.id];
+    }
+
+    return {
+      source: 'ofx',
+      // Prefer the caller's asOf, then the statement's own DTASOF, then NOW.
+      asOf: raw.asOf || statementAsOf || defaultAsOf(),
+      owner: { ...(raw.owner ?? {}) },
+      accounts,
+      meta: { warnings, unmapped },
+    };
+  },
+};
+
+// ── tolerant OFX parser ──────────────────────────────────────────────────────
+
+/**
+ * Parse OFX text (1.x SGML or 2.x XML) into a tag tree. One pass, one rule
+ * set for both syntaxes:
+ *   - `<TAG>text` → a LEAF (SGML leaves are never closed; XML's later
+ *     `</TAG>` finds nothing open and is ignored)
+ *   - `<TAG>` with no trailing text → an AGGREGATE (pushed on the stack)
+ *   - `</TAG>` → pops back to the matching open aggregate; ignored when
+ *     nothing matches (hostile/truncated input never throws)
+ * The `OFXHEADER:...` SGML header block / XML prolog before `<OFX>` is
+ * skipped; when no `<OFX>` tag exists the whole text is scanned anyway.
+ * @param {string} text
+ * @returns {{tag: string, value?: string, children: object[]}}
+ */
+export function parseOfx(text) {
+  let s = String(text ?? '');
+  const ofxStart = s.search(/<OFX>/i);
+  if (ofxStart >= 0) s = s.slice(ofxStart);
+  const root = { tag: 'ROOT', children: [] };
+  const stack = [root];
+  const re = /<(\/?)([A-Za-z0-9_.]+)[^>]*>([^<]*)/g;
+  let m;
+  while ((m = re.exec(s))) {
+    const closing = m[1] === '/';
+    const tag = m[2].toUpperCase();
+    const trailing = decodeEntities(m[3]).trim();
+    if (closing) {
+      // Pop back to the matching open aggregate; tolerate mismatches.
+      for (let i = stack.length - 1; i >= 1; i--) {
+        if (stack[i].tag === tag) { stack.length = i; break; }
+      }
+    } else if (trailing) {
+      stack[stack.length - 1].children.push({ tag, value: trailing, children: [] });
+    } else {
+      const node = { tag, children: [] };
+      stack[stack.length - 1].children.push(node);
+      stack.push(node);
+    }
+  }
+  return root;
+}
+
+const decodeEntities = (s) => String(s)
+  .replace(/&lt;/gi, '<').replace(/&gt;/gi, '>').replace(/&amp;/gi, '&').replace(/&nbsp;/gi, ' ');
+
+/** Depth-first search: first descendant with `tag`, or undefined. */
+export function find(node, tag) {
+  if (!node) return undefined;
+  for (const c of node.children ?? []) {
+    if (c.tag === tag) return c;
+    const hit = find(c, tag);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+/** Depth-first search: ALL descendants with `tag` (document order). */
+export function findAll(node, tag) {
+  const out = [];
+  const walk = (n) => {
+    for (const c of n.children ?? []) {
+      if (c.tag === tag) out.push(c);
+      walk(c);
+    }
+  };
+  if (node) walk(node);
+  return out;
+}
+
+/** Leaf value of the first descendant `tag` under `node`, or undefined. */
+const val = (node, tag) => (node ? find(node, tag)?.value : undefined);
+
+/**
+ * OFX dates are `YYYYMMDD[HHMMSS[.XXX]][ [gmt offset:TZ] ]` — take the digits
+ * and build a UTC ISO string. Unparseable → undefined (never a fabricated date).
+ */
+export function ofxDateIso(v) {
+  const m = String(v ?? '').match(/^(\d{4})(\d{2})(\d{2})(?:(\d{2})(\d{2})(\d{2}))?/);
+  if (!m) return undefined;
+  const t = Date.UTC(+m[1], +m[2] - 1, +m[3], +(m[4] ?? 0), +(m[5] ?? 0), +(m[6] ?? 0));
+  return Number.isFinite(t) && +m[2] >= 1 && +m[2] <= 12 && +m[3] >= 1 && +m[3] <= 31
+    ? new Date(t).toISOString()
+    : undefined;
+}
+
+/** "1234567890" → "••7890" — OFX has no account names, only ids. */
+const mask = (id) => `••${String(id ?? '').slice(-4)}`;
+const title = (s) => String(s ?? '').charAt(0) + String(s ?? '').slice(1).toLowerCase();

package/src/adapters/plaid.mjs

@@ -0,0 +1,140 @@
+// plaid.mjs — Plaid → Canonical Financial Profile.
+//
+// Consumes the merged results of the Plaid product endpoints:
+//   /accounts/get              → accounts[] (+ balances)
+//   /investments/holdings/get  → holdings[] + securities[]
+//   /liabilities/get           → liabilities.{mortgage,student,credit}[]
+//   /income (optional)         → owner.annualSalary
+// It maps ONLY Plaid's quirks into the CFP; all Planfi logic lives in
+// to-planfi.mjs. Nothing is fabricated — missing fields become warnings.
+//
+// @typedef {import('../canonical').CanonicalFinancialProfile} CFP
+// @typedef {import('../canonical').SourceAdapter} SourceAdapter
+
+import { classify, classifyAsset } from '../classify.mjs';
+import { contributionsByAccount } from '../contributions.mjs';
+import { arr, objs, num, pct, groupBy, monthsBetween, defaultAsOf, warning } from '../util.mjs';
+
+/** @implements {SourceAdapter} */
+export const plaidAdapter = {
+  source: 'plaid',
+  /**
+   * @param {object} raw - { accounts, holdings, securities, liabilities, income, owner, asOf }
+   * @returns {CFP}
+   */
+  normalize(raw) {
+    // Total function: null/primitive payloads normalize to an empty profile
+    // (a default parameter only covers `undefined` — the contract harness
+    // caught the null case throwing).
+    raw = raw && typeof raw === 'object' ? raw : {};
+    const warnings = [];
+    const unmapped = [];
+    const accountsIn = objs(raw.accounts);
+    const holdingsIn = objs(raw.holdings);
+    const securitiesIn = objs(raw.securities);
+    const liab = raw.liabilities ?? {};
+
+    const secById = new Map(securitiesIn.map((s) => [s.security_id, s]));
+    const holdingsByAccount = groupBy(holdingsIn, (h) => h.account_id);
+    // Inferred monthly contributions from investment transactions (if provided).
+    const contribByAccount = contributionsByAccount(objs(raw.investmentTransactions ?? raw.investment_transactions));
+
+    // liability detail keyed by account_id
+    const liabByAccount = new Map();
+    for (const m of objs(liab.mortgage)) {
+      liabByAccount.set(m.account_id, {
+        rate: pct(m.interest_rate?.percentage),
+        minPayment: num(m.next_monthly_payment) || num(m.last_payment_amount),
+        originationPrincipal: num(m.origination_principal_amount),
+        assetName: m.property_address?.street ? `Home — ${m.property_address.city ?? ''}`.trim() : 'Home',
+        monthsRemaining: monthsBetween(raw.asOf, m.maturity_date),
+      });
+    }
+    for (const st of objs(liab.student)) {
+      liabByAccount.set(st.account_id, {
+        rate: pct(st.interest_rate_percentage),
+        minPayment: num(st.minimum_payment_amount),
+      });
+    }
+    for (const cc of objs(liab.credit)) {
+      liabByAccount.set(cc.account_id, {
+        rate: pct(cc.aprs?.[0]?.apr_percentage),
+        minPayment: num(cc.minimum_payment_amount) || num(cc.last_statement_balance) * 0.02,
+      });
+    }
+
+    const accounts = accountsIn.map((a) => {
+      const { accountClass, taxTreatment, confidence } = classify(a.type, a.subtype);
+      if (confidence === 'low') {
+        warnings.push(warning('CLASSIFICATION_GUESSED', 'warn',
+          `Account "${a.name ?? a.account_id}" (${a.type}/${a.subtype}) classification guessed → ${accountClass}/${taxTreatment}.`, a.account_id));
+      }
+      const bal = a.balances ?? {};
+      // asset accounts use `current`; liabilities also carry `current` = amount owed.
+      const balance = num(bal.current) || num(bal.available) || 0;
+
+      const acct = {
+        id: a.account_id,
+        institution: a.institution_name,
+        name: a.official_name || a.name,
+        class: accountClass,
+        subtype: String(a.subtype ?? '').toLowerCase(),
+        taxTreatment,
+        balance,
+        currency: bal.iso_currency_code ?? 'USD',
+        // Which earner owns it (0/1). Caller may set from Plaid /identity name
+        // matching; defaults to the primary earner.
+        ownerIndex: Number.isInteger(a.owner_index) ? a.owner_index : 0,
+        ...(contribByAccount[a.account_id] ? { estMonthlyContribution: contribByAccount[a.account_id] } : {}),
+      };
+
+      if (accountClass === 'investment') {
+        const hs = holdingsByAccount.get(a.account_id) ?? [];
+        acct.holdings = hs.map((h) => {
+          const sec = secById.get(h.security_id) ?? {};
+          if (h.cost_basis == null) {
+            warnings.push(warning('NO_COST_BASIS', 'info',
+              `Holding ${sec.ticker_symbol ?? sec.name ?? h.security_id} has no cost basis (institution did not report it).`, a.account_id));
+          }
+          return {
+            ticker: sec.ticker_symbol ?? undefined,
+            name: sec.name ?? undefined,
+            quantity: num(h.quantity),
+            value: num(h.institution_value),
+            costBasis: h.cost_basis == null ? undefined : num(h.cost_basis),
+            assetType: classifyAsset(sec.type),
+          };
+        });
+      }
+      if (accountClass === 'loan' || accountClass === 'credit') {
+        acct.liability = liabByAccount.get(a.account_id) ?? { rate: undefined };
+      }
+      return acct;
+    });
+
+    // owner context: Plaid Income can supply salary; everything else onboarding.
+    const owner = { ...(raw.owner ?? {}) };
+    const salary = plaidAnnualIncome(raw.income);
+    if (salary != null && owner.annualSalary == null) owner.annualSalary = salary;
+
+    return {
+      source: 'plaid',
+      // Default snapshot time is NOW (not the 1970 epoch — see util.mjs).
+      asOf: raw.asOf || defaultAsOf(),
+      owner,
+      accounts,
+      meta: { warnings, unmapped },
+    };
+  },
+};
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+// (arr/num/pct/groupBy/monthsBetween live in ../util.mjs, shared with mx.mjs.)
+/** Plaid Income: sum the primary income stream(s) to an annual figure. */
+function plaidAnnualIncome(income) {
+  if (!income) return null;
+  const streams = objs(income.income_streams ?? income.bank_income?.[0]?.income_sources);
+  if (!streams.length) return null;
+  const monthly = streams.reduce((n, s) => n + num(s.monthly_income), 0);
+  return monthly > 0 ? Math.round(monthly * 12) : null;
+}