@plan-fi/imports 0.6.0

package/src/canonical.ts

@@ -0,0 +1,185 @@
+/**
+ * canonical.ts — the Canonical Financial Profile (CFP): the provider-neutral
+ * contract every import adapter emits and the single Planfi mapper consumes.
+ *
+ * See docs/IMPORT_ADAPTERS.md for the architecture. This file is the contract
+ * (types only, zero dependencies) so it can anchor the open-source SDK.
+ *
+ *   Plaid/MX/OFX raw  ──SourceAdapter.normalize()──►  CanonicalFinancialProfile
+ *   CanonicalFinancialProfile  ──toPlanfiPlan()──►  generate_financial_plan wire
+ */
+
+/**
+ * Broad account family, provider-independent.
+ *
+ * Enum alignment: this maps 1:1 onto the FDX (Financial Data Exchange)
+ * account SHAPES — depositAccount → 'depository', investmentAccount /
+ * annuityAccount → 'investment', loanAccount → 'loan', locAccount /
+ * lineOfCredit → 'credit'. FDX has no property/real-estate shape, so
+ * 'property' has no FDX counterpart (it exists for MX PROPERTY accounts).
+ */
+export type AccountClass = 'depository' | 'investment' | 'loan' | 'credit' | 'property';
+
+/**
+ * Stable machine-readable warning codes (v0.2.0). Codes are append-only: a
+ * released code never changes meaning, so callers can switch on them safely.
+ * Human `message` text may improve between versions; `code` will not.
+ */
+export type WarningCode =
+  | 'CLASSIFICATION_GUESSED'      // account type/subtype ambiguous → treatment guessed
+  | 'NO_COST_BASIS'               // institution reported a holding without cost basis
+  | 'COARSE_INFERENCE'            // contribution inference ran on unlabeled transactions
+  | 'CONTRIBUTION_CLAMPED'        // inferred contribution exceeded the IRS limit → clamped
+  | 'CONTRIBUTION_IMPLAUSIBLE'    // inferred savings rate implausibly high vs known salary
+  | 'HSA_FOLDED_INTO_PORTFOLIO'   // HSA balance folded into stocks total (no wire HSA balance field)
+  | 'HSA_COVERAGE_ASSUMED'        // HSA coverage type unknowable → assumed 'family'
+  | 'IRA_SPLIT_ASSUMED'           // trad+Roth IRA contributions → one 'both' block (engine models 50/50)
+  | 'HOME_VALUE_ESTIMATED'        // no property value in source → estimated at 80% LTV
+  | 'MORTGAGE_SKIPPED'            // mortgage had no balance or home value → dropped
+  | 'NEGATIVE_BALANCE_CLAMPED'    // negative asset balance clamped to $0
+  | 'DEBT_RATE_MISSING'           // debt has no APR in source → modeled at 0%
+  | 'CSV_UNMAPPED_COLUMNS'        // CSV columns not matched by any dialect → best-effort generic mapping
+  | 'CSV_TRANSACTIONS_ONLY'       // transactions-only export (e.g. YNAB) — the tool carries no balances — pair with a balances file
+  | 'IMPORT_EMPTY';               // zero accounts recognized in the payload — likely a format/shape problem — the plan was built from nothing
+
+/** One structured warning. Emitted by adapters (via CFP meta) and the mapper. */
+export interface ImportWarning {
+  code: WarningCode;
+  /** 'info' = lossless modeling note; 'warn' = a value may be wrong — verify. */
+  severity: 'info' | 'warn';
+  /** Human-readable explanation, safe to show to an end user. */
+  message: string;
+  /** Provider account id the warning refers to, when account-scoped. */
+  accountId?: string;
+}
+
+/** Fields an aggregator cannot supply — collect them from the user. */
+export type NeedsInputField =
+  | 'age'
+  | 'retirement_age'
+  | 'annual_salary'
+  | 'desired_annual_spend'
+  | 'home_value'
+  | 'debt_rate';
+
+/**
+ * One structured ask. De-duplicated on (field, accountId, earnerIndex) and
+ * emitted in deterministic order (earner demographics, then per-account asks
+ * in account order, then plan-level goals).
+ */
+export interface NeedsInput {
+  field: NeedsInputField;
+  /** Provider account id, for account-scoped asks (home_value, debt_rate). */
+  accountId?: string;
+  accountName?: string;
+  /** 0-based earner index, for demographic asks in multi-earner households. */
+  earnerIndex?: number;
+  /** Short human label, ready for a form ("Home value for Home mortgage"). */
+  label: string;
+  /** One sentence: why the import couldn't supply this. */
+  why: string;
+}
+
+/**
+ * Tax treatment of an investment/holding bucket. `na` = not applicable (debt, cash).
+ *
+ * Enum alignment: the FDX `accountType` vocabulary partitions cleanly into
+ * these treatments — IRA/401K/403B/457/KEOGH/SEPIRA/SIMPLEIRA → 'traditional',
+ * ROTH/ROTH401K → 'roth', HSA → 'hsa', 529 → '529', BROKERAGE → 'taxable';
+ * TDA/ANNUITY lean 'traditional' at low confidence (warned).
+ */
+export type TaxTreatment = 'taxable' | 'traditional' | 'roth' | 'hsa' | '529' | 'na';
+
+/**
+ * Enum alignment: FDX InvestmentHolding.holdingType overlaps — STOCK →
+ * 'equity', MUTUALFUND → 'mutual_fund', BOND → 'bond', CASH/CD/MONEYMARKET →
+ * 'cash', DIGITALASSET → 'crypto', OPTION/ANNUITY/OTHER → 'other'. 'etf' is
+ * finer-grained than FDX (which files ETFs under STOCK unless the institution
+ * sends an explicit ETF type, which the fdx adapter also accepts).
+ */
+export type AssetType = 'equity' | 'etf' | 'mutual_fund' | 'bond' | 'cash' | 'crypto' | 'other';
+
+/** One security position inside an investment account. */
+export interface CanonicalHolding {
+  ticker?: string;
+  name?: string;
+  quantity?: number;
+  /** Market value of the position at `asOf`. */
+  value?: number;
+  /** Total cost basis (engine-only on import — see docs Gaps). */
+  costBasis?: number;
+  assetType: AssetType;
+}
+
+/** Loan/credit detail attached to a `loan` or `credit` account. */
+export interface LiabilityDetail {
+  /** APR as a fraction, e.g. 0.0625 for 6.25%. */
+  rate?: number;
+  minPayment?: number;
+  monthsRemaining?: number;
+  originationPrincipal?: number;
+  /** The asset securing the debt (property/vehicle), when known. */
+  assetName?: string;
+  assetValue?: number;
+}
+
+export interface CanonicalAccount {
+  /** Stable provider account id — the key for dedup/reconcile across refreshes. */
+  id: string;
+  institution?: string;
+  name?: string;
+  class: AccountClass;
+  /** Provider subtype normalized to lowercase, e.g. '401k', 'roth ira', 'mortgage'. */
+  subtype?: string;
+  taxTreatment?: TaxTreatment;
+  /** Asset value, or outstanding principal for a liability. */
+  balance: number;
+  currency?: string;
+  holdings?: CanonicalHolding[];
+  liability?: LiabilityDetail;
+  /** Which earner (0-based) owns this account, for joint households. */
+  ownerIndex?: number;
+  /** Inferred monthly contribution into this account (from transactions). */
+  estMonthlyContribution?: number;
+}
+
+/**
+ * Planning context aggregators usually CAN'T supply (age, goals, salary).
+ * Populated from onboarding and merged over the imported accounts. Fields left
+ * undefined surface in the mapper's `needsInput` list.
+ */
+export interface OwnerContext {
+  age?: number;
+  retirementAge?: number;
+  annualSalary?: number;
+  desiredAnnualSpend?: number;
+  /** Two-letter US state for tax settings. */
+  filingState?: string;
+  /** Per-earner overrides for joint households. */
+  earners?: Array<Partial<OwnerContext> & { name?: string }>;
+}
+
+export interface CanonicalFinancialProfile {
+  /** Adapter source id: 'plaid' | 'mx' | 'finicity' | 'fdx' | 'csv' | 'ofx' | ... */
+  source: string;
+  /** ISO timestamp of the underlying snapshot. */
+  asOf: string;
+  owner: OwnerContext;
+  accounts: CanonicalAccount[];
+  meta: {
+    /** Structured notes: guessed classifications, dropped/partial data. */
+    warnings: ImportWarning[];
+    /** Raw provider entities that couldn't be mapped — never silently dropped. */
+    unmapped: unknown[];
+  };
+}
+
+/**
+ * The contract implemented once per provider. `normalize` does ONLY that
+ * provider's quirk-mapping into the CFP; all Planfi domain logic lives
+ * downstream in `toPlanfiPlan`, written once and shared across every adapter.
+ */
+export interface SourceAdapter<Raw = unknown> {
+  readonly source: string;
+  normalize(raw: Raw): CanonicalFinancialProfile;
+}

package/src/classify.mjs

@@ -0,0 +1,72 @@
+// classify.mjs — map a provider account (type + subtype) to the canonical
+// { class, taxTreatment }. Provider-neutral: adapters pass already-lowercased
+// type/subtype strings. Returns a confidence so ambiguous guesses can warn.
+//
+// @typedef {import('./canonical').AccountClass} AccountClass
+// @typedef {import('./canonical').TaxTreatment} TaxTreatment
+
+/** Roth-flavored investment subtypes. */
+const ROTH = /roth/;
+/** Pre-tax retirement subtypes (traditional treatment). */
+const PRETAX = /401k|403b|457b|401a|\bira\b|sep|simple|keogh|thrift|tsp|retirement/;
+/** Education / 529. */
+const EDU_529 = /529|education\s?savings/;
+/** Explicitly taxable investment subtypes. */
+const TAXABLE_INV = /brokerage|mutual fund|cash management|stock plan|crypto|ugma|utma|other/;
+
+/**
+ * @param {string} type - provider account family (e.g. Plaid 'investment'|'depository'|'loan'|'credit')
+ * @param {string} [subtype]
+ * @returns {{ accountClass: AccountClass, taxTreatment: TaxTreatment, confidence: 'high'|'medium'|'low' }}
+ */
+export function classify(type, subtype = '') {
+  const t = String(type || '').trim().toLowerCase();
+  const s = String(subtype || '').trim().toLowerCase();
+
+  if (t === 'loan') return { accountClass: 'loan', taxTreatment: 'na', confidence: 'high' };
+  if (t === 'credit') return { accountClass: 'credit', taxTreatment: 'na', confidence: 'high' };
+
+  if (t === 'depository') {
+    if (s === 'hsa') return { accountClass: 'investment', taxTreatment: 'hsa', confidence: 'high' };
+    return { accountClass: 'depository', taxTreatment: 'na', confidence: 'high' };
+  }
+
+  if (t === 'investment' || t === 'brokerage') {
+    if (s === 'hsa') return { accountClass: 'investment', taxTreatment: 'hsa', confidence: 'high' };
+    if (EDU_529.test(s)) return { accountClass: 'investment', taxTreatment: '529', confidence: 'high' };
+    // Ambiguous subtypes — treatment is a GUESS, so low confidence (→ warning):
+    //   'non-taxable brokerage' (Plaid): tax-deferred-ish wrapper with unclear
+    //   treatment — do NOT let the 'brokerage' substring claim it as taxable
+    //   at high confidence.
+    //   'pension': a defined-benefit pension is an income STREAM, not an
+    //   investable balance — bucketing its "balance" as a traditional account
+    //   is a coarse approximation that must surface to the caller.
+    if (/non-taxable brokerage/.test(s)) return { accountClass: 'investment', taxTreatment: 'taxable', confidence: 'low' };
+    if (/pension/.test(s)) return { accountClass: 'investment', taxTreatment: 'traditional', confidence: 'low' };
+    //   'tax-deferred' (Finicity investmentTaxDeferred, annuity wrappers): the
+    //   provider says pre-tax but not WHICH wrapper — traditional treatment is
+    //   the right lean, at low confidence so the guess surfaces to the caller.
+    if (/tax[- ]deferred/.test(s)) return { accountClass: 'investment', taxTreatment: 'traditional', confidence: 'low' };
+    if (ROTH.test(s)) return { accountClass: 'investment', taxTreatment: 'roth', confidence: 'high' };
+    if (PRETAX.test(s)) return { accountClass: 'investment', taxTreatment: 'traditional', confidence: 'high' };
+    if (TAXABLE_INV.test(s)) return { accountClass: 'investment', taxTreatment: 'taxable', confidence: 'high' };
+    // Unknown investment subtype → assume taxable but flag it.
+    return { accountClass: 'investment', taxTreatment: 'taxable', confidence: 'low' };
+  }
+
+  // Unknown top-level type — treat as taxable investment, low confidence.
+  return { accountClass: 'investment', taxTreatment: 'taxable', confidence: 'low' };
+}
+
+/** Map a provider security type → canonical assetType. Handles Plaid + MX vocab. */
+export function classifyAsset(securityType = '') {
+  const s = String(securityType || '').trim().toLowerCase();
+  if (s === 'etf') return 'etf';
+  if (s === 'mutual fund') return 'mutual_fund';
+  if (s === 'equity' || s === 'stock' || s === 'common stock') return 'equity';
+  if (s === 'fixed income' || s === 'bond') return 'bond';
+  if (s === 'cash' || s === 'cash equivalent') return 'cash';
+  if (s.startsWith('crypto')) return 'crypto';
+  if (s === 'derivative') return 'other';
+  return 'other';
+}

package/src/contributions.mjs

@@ -0,0 +1,65 @@
+// contributions.mjs — infer a monthly contribution rate per account from Plaid
+// investment transactions. Aggregators report balances, not savings rates, so
+// projections need this signal or they understate growth.
+//
+// Heuristic: sum the money flowing INTO the account (deposits / contributions /
+// transfers-in / payroll) over the observed window, then divide by the window
+// length in months. Sign-agnostic (uses magnitude) to survive Plaid's debit/
+// credit convention differences across products. Conservative: unknown → 0.
+//
+// Deliberately EXCLUDED: dividend/interest — that is investment GROWTH, already
+// modeled by the plan's annual_return; counting it as a contribution would
+// double-count it. Transfers ARE counted (a recurring ACH transfer-in is the
+// most common real savings pattern), which means one-off rollovers can inflate
+// the figure — the shared mapper (to-planfi.mjs) sanity-checks the inferred
+// totals (vs known salary / IRS limits) and warns when they look inflated.
+
+const IN_SUBTYPE = /contribution|deposit|transfer|payroll/i;
+const GROWTH_SUBTYPE = /dividend|interest/i;
+
+/**
+ * @param {Array<{account_id?:string, type?:string, subtype?:string, amount?:number, date?:string}>} txns
+ * @param {object} [opts]
+ * @param {number} [opts.windowMonths] - override the inferred window
+ * @returns {number} estimated monthly contribution (>= 0)
+ */
+export function inferMonthlyContribution(txns, opts = {}) {
+  const list = (Array.isArray(txns) ? txns : []).filter(isInflow);
+  if (!list.length) return 0;
+  const total = list.reduce((s, t) => s + Math.abs(Number(t.amount) || 0), 0);
+  const months = opts.windowMonths || spanMonths(txns) || 12;
+  const monthly = total / months;
+  return Number.isFinite(monthly) && monthly > 0 ? Math.round(monthly) : 0;
+}
+
+/** Group investment transactions by account_id → inferred monthly contribution. */
+export function contributionsByAccount(txns, opts = {}) {
+  const byAcct = new Map();
+  for (const t of Array.isArray(txns) ? txns : []) {
+    const k = t.account_id;
+    if (!k) continue;
+    (byAcct.get(k) ?? byAcct.set(k, []).get(k)).push(t);
+  }
+  const out = {};
+  for (const [acct, list] of byAcct) out[acct] = inferMonthlyContribution(list, opts);
+  return out;
+}
+
+/** A transaction that represents NEW money entering the account (not growth). */
+function isInflow(t) {
+  const sub = String(t?.subtype ?? '');
+  if (GROWTH_SUBTYPE.test(sub)) return false; // dividends/interest = growth, not savings
+  if (IN_SUBTYPE.test(sub)) return true;
+  // Plaid credits cash into the account as a negative `amount` on a 'cash' type.
+  return String(t?.type ?? '') === 'cash' && Number(t?.amount) < 0;
+}
+
+/** Months spanned by the transaction dates (min→max), min 1. */
+function spanMonths(txns) {
+  const times = (Array.isArray(txns) ? txns : [])
+    .map((t) => Date.parse(t?.date ?? ''))
+    .filter(Number.isFinite);
+  if (times.length < 2) return 0;
+  const span = (Math.max(...times) - Math.min(...times)) / (1000 * 60 * 60 * 24 * 30.44);
+  return Math.max(1, Math.round(span));
+}

package/src/index.mjs

@@ -0,0 +1,42 @@
+// planfi-import — aggregator data → Planfi plans, via a canonical model.
+// See docs/IMPORT_ADAPTERS.md. To ADD an adapter, follow docs/ADAPTER_GUIDE.md
+// (and AGENTS.md for the invariants) — every adapter must be registered here
+// in ADAPTERS + the named exports, typed in planfi-import.d.ts, and covered by
+// a fixture in test/helpers/fixture-registry.mjs; test/adapter-contract.test.mjs
+// enforces all of that.
+
+export { classify, classifyAsset } from './classify.mjs';
+export { inferMonthlyContribution, contributionsByAccount } from './contributions.mjs';
+export { toPlanfiPlan } from './to-planfi.mjs';
+export { plaidAdapter } from './adapters/plaid.mjs';
+export { mxAdapter } from './adapters/mx.mjs';
+export { finicityAdapter } from './adapters/finicity.mjs';
+export { fdxAdapter } from './adapters/fdx.mjs';
+export { csvAdapter } from './adapters/csv.mjs';
+export { ofxAdapter } from './adapters/ofx.mjs';
+
+import { plaidAdapter } from './adapters/plaid.mjs';
+import { mxAdapter } from './adapters/mx.mjs';
+import { finicityAdapter } from './adapters/finicity.mjs';
+import { fdxAdapter } from './adapters/fdx.mjs';
+import { csvAdapter } from './adapters/csv.mjs';
+import { ofxAdapter } from './adapters/ofx.mjs';
+import { toPlanfiPlan } from './to-planfi.mjs';
+
+/** Registry of source adapters by id. */
+export const ADAPTERS = { plaid: plaidAdapter, mx: mxAdapter, finicity: finicityAdapter, fdx: fdxAdapter, csv: csvAdapter, ofx: ofxAdapter };
+
+/**
+ * One-call import: raw provider payload → { plan, warnings, needsInput, cfp }.
+ * @param {string} source - adapter id ('plaid' | 'mx' | 'finicity' | 'fdx' | 'csv' | 'ofx')
+ * @param {object} raw - provider-native payload
+ * @param {object} [opts] - forwarded to toPlanfiPlan (e.g. defaultState)
+ * @returns {{ plan: object, warnings: import('./canonical').ImportWarning[], needsInput: import('./canonical').NeedsInput[], cfp: import('./canonical').CanonicalFinancialProfile }}
+ */
+export function importToPlan(source, raw, opts) {
+  const adapter = ADAPTERS[source];
+  if (!adapter) throw new Error(`No import adapter for source "${source}". Known: ${Object.keys(ADAPTERS).join(', ')}`);
+  const cfp = adapter.normalize(raw);
+  const { plan, warnings, needsInput } = toPlanfiPlan(cfp, opts);
+  return { plan, warnings, needsInput, cfp };
+}