@plan-fi/imports 0.6.0

package/fixtures/ofx-sandbox.mjs

@@ -0,0 +1,196 @@
+// OFX 1.x SGML payload for the keyless adapter — the "Download → Quicken"
+// file a bank actually produces: KEY:VALUE header block, tags whose leaves are
+// NEVER closed, and all four message sets the adapter reads:
+//   BANKMSGSRSV1        — checking + savings ledger balances
+//   CREDITCARDMSGSRSV1  — a card whose BALAMT is NEGATIVE (the OFX convention
+//                         for amount owed; the adapter normalizes to positive)
+//   INVSTMTMSGSRSV1     — one brokerage statement: stock + mutual-fund
+//                         positions (SECID → SECLIST lookup), available cash,
+//                         and an INVTRANLIST with monthly INVBANKTRAN deposits
+//                         (contribution inference) plus an INCOME dividend
+//                         record that must be EXCLUDED as growth
+//   SECLISTMSGSRSV1     — ticker/name lookup for the positions
+// OFX carries no tax-treatment info, so the investment account must come out
+// taxable at LOW confidence with a CLASSIFICATION_GUESSED warning.
+
+const deposits = ['20260115', '20260215', '20260315', '20260415', '20260515', '20260615']
+  .map((d, i) => `
+<INVBANKTRAN>
+<STMTTRN>
+<TRNTYPE>CREDIT
+<DTPOSTED>${d}120000.000[-5:EST]
+<TRNAMT>1500.00
+<FITID>DEP${i + 1}
+<NAME>CONTRIBUTION ACH TRANSFER IN
+</STMTTRN>
+<SUBACCTFUND>CASH
+</INVBANKTRAN>`).join('');
+
+export const ofxRaw = {
+  asOf: '2026-07-02T00:00:00.000Z',
+  owner: {
+    desiredAnnualSpend: 72000,
+    filingState: 'TX',
+    earners: [{ name: 'Sam', age: 45, retirementAge: 63, annualSalary: 140000 }],
+  },
+  content: `OFXHEADER:100
+DATA:OFXSGML
+VERSION:102
+SECURITY:NONE
+ENCODING:USASCII
+CHARSET:1252
+COMPRESSION:NONE
+OLDFILEUID:NONE
+NEWFILEUID:NONE
+
+<OFX>
+<SIGNONMSGSRSV1>
+<SONRS>
+<STATUS>
+<CODE>0
+<SEVERITY>INFO
+</STATUS>
+<DTSERVER>20260702093000.000[-5:EST]
+<LANGUAGE>ENG
+</SONRS>
+</SIGNONMSGSRSV1>
+<BANKMSGSRSV1>
+<STMTTRNRS>
+<TRNUID>1001
+<STMTRS>
+<CURDEF>USD
+<BANKACCTFROM>
+<BANKID>021000021
+<ACCTID>9917341234
+<ACCTTYPE>CHECKING
+</BANKACCTFROM>
+<LEDGERBAL>
+<BALAMT>11250.75
+<DTASOF>20260702
+</LEDGERBAL>
+</STMTRS>
+</STMTTRNRS>
+<STMTTRNRS>
+<TRNUID>1002
+<STMTRS>
+<CURDEF>USD
+<BANKACCTFROM>
+<BANKID>021000021
+<ACCTID>9917349999
+<ACCTTYPE>SAVINGS
+</BANKACCTFROM>
+<LEDGERBAL>
+<BALAMT>27500.00
+<DTASOF>20260702
+</LEDGERBAL>
+</STMTRS>
+</STMTTRNRS>
+</BANKMSGSRSV1>
+<CREDITCARDMSGSRSV1>
+<CCSTMTTRNRS>
+<TRNUID>2001
+<CCSTMTRS>
+<CURDEF>USD
+<CCACCTFROM>
+<ACCTID>5412000012348888
+</CCACCTFROM>
+<LEDGERBAL>
+<BALAMT>-2350.60
+<DTASOF>20260702
+</LEDGERBAL>
+</CCSTMTRS>
+</CCSTMTTRNRS>
+</CREDITCARDMSGSRSV1>
+<INVSTMTMSGSRSV1>
+<INVSTMTTRNRS>
+<TRNUID>3001
+<INVSTMTRS>
+<DTASOF>20260702120000.000[-5:EST]
+<CURDEF>USD
+<INVACCTFROM>
+<BROKERID>fidelity.com
+<ACCTID>X22334455
+</INVACCTFROM>
+<INVTRANLIST>
+<DTSTART>20260101
+<DTEND>20260702${deposits}
+<INCOME>
+<INVTRAN>
+<FITID>DIV1
+<DTTRADE>20260320
+</INVTRAN>
+<SECID>
+<UNIQUEID>922908769
+<UNIQUEIDTYPE>CUSIP
+</SECID>
+<INCOMETYPE>DIV
+<TOTAL>640.00
+<SUBACCTSEC>CASH
+<SUBACCTFUND>CASH
+</INCOME>
+</INVTRANLIST>
+<INVPOSLIST>
+<POSSTOCK>
+<INVPOS>
+<SECID>
+<UNIQUEID>922908769
+<UNIQUEIDTYPE>CUSIP
+</SECID>
+<HELDINACCT>CASH
+<POSTYPE>LONG
+<UNITS>310
+<UNITPRICE>305.12
+<MKTVAL>94587.20
+<DTPRICEASOF>20260702
+</INVPOS>
+</POSSTOCK>
+<POSMF>
+<INVPOS>
+<SECID>
+<UNIQUEID>315911750
+<UNIQUEIDTYPE>CUSIP
+</SECID>
+<HELDINACCT>CASH
+<POSTYPE>LONG
+<UNITS>620
+<UNITPRICE>211.76
+<MKTVAL>131291.20
+<DTPRICEASOF>20260702
+</INVPOS>
+</POSMF>
+</INVPOSLIST>
+<INVBAL>
+<AVAILCASH>4200.55
+<MARGINBALANCE>0
+<SHORTBALANCE>0
+</INVBAL>
+</INVSTMTRS>
+</INVSTMTTRNRS>
+</INVSTMTMSGSRSV1>
+<SECLISTMSGSRSV1>
+<SECLIST>
+<STOCKINFO>
+<SECINFO>
+<SECID>
+<UNIQUEID>922908769
+<UNIQUEIDTYPE>CUSIP
+</SECID>
+<SECNAME>VANGUARD TOTAL STOCK MARKET ETF
+<TICKER>VTI
+</SECINFO>
+</STOCKINFO>
+<MFINFO>
+<SECINFO>
+<SECID>
+<UNIQUEID>315911750
+<UNIQUEIDTYPE>CUSIP
+</SECID>
+<SECNAME>FIDELITY 500 INDEX FUND
+<TICKER>FXAIX
+</SECINFO>
+</MFINFO>
+</SECLIST>
+</SECLISTMSGSRSV1>
+</OFX>
+`,
+};

package/fixtures/plaid-sandbox.mjs

@@ -0,0 +1,56 @@
+// Plaid-sandbox-shaped payload (merged /accounts + /investments/holdings +
+// /liabilities), trimmed to the fields the adapter reads. Mirrors real Plaid
+// response shapes. Intentionally includes a holding with NO cost basis and a
+// low-confidence subtype to exercise the warning paths.
+
+export const plaidRaw = {
+  asOf: '2026-07-02T00:00:00.000Z',
+  // Two earners → joint household. Accounts carry owner_index (0/1).
+  owner: {
+    desiredAnnualSpend: 90000, filingState: 'CA',
+    earners: [
+      { name: 'Alex', age: 41, retirementAge: 62, annualSalary: 185000 },
+      { name: 'Sam', age: 39, retirementAge: 62, annualSalary: 120000 },
+    ],
+  },
+  accounts: [
+    { account_id: 'chk1', name: 'Checking', type: 'depository', subtype: 'checking', balances: { current: 18400, iso_currency_code: 'USD' } },
+    { account_id: 'sav1', name: 'Savings', type: 'depository', subtype: 'savings', balances: { current: 52000 } },
+    { account_id: 'brk1', name: 'Brokerage', type: 'investment', subtype: 'brokerage', balances: { current: 240000 }, owner_index: 0 },
+    { account_id: 'k401', name: 'Fidelity 401(k)', type: 'investment', subtype: '401k', balances: { current: 315000 }, owner_index: 0 },
+    { account_id: 'roth1', name: 'Roth IRA', type: 'investment', subtype: 'roth', balances: { current: 88000 }, owner_index: 1 },
+    { account_id: 'hsa1', name: 'HSA', type: 'investment', subtype: 'hsa', balances: { current: 22000 } },
+    { account_id: 'edu1', name: "Kid's 529", type: 'investment', subtype: '529', balances: { current: 41000 } },
+    { account_id: 'mtg1', name: 'Home mortgage', type: 'loan', subtype: 'mortgage', balances: { current: 512000 } },
+    { account_id: 'std1', name: 'Student loan', type: 'loan', subtype: 'student', balances: { current: 28000 } },
+    { account_id: 'cc1', name: 'Sapphire card', type: 'credit', subtype: 'credit card', balances: { current: 4200 } },
+    { account_id: 'weird1', name: 'Mystery acct', type: 'investment', subtype: 'annuity', balances: { current: 15000 } },
+  ],
+  securities: [
+    { security_id: 's_vti', ticker_symbol: 'VTI', name: 'Vanguard Total Market ETF', type: 'etf' },
+    { security_id: 's_aapl', ticker_symbol: 'AAPL', name: 'Apple Inc', type: 'equity' },
+    { security_id: 's_btc', ticker_symbol: 'BTC', name: 'Bitcoin', type: 'cryptocurrency' },
+    { security_id: 's_tgt', ticker_symbol: null, name: 'Target Retirement 2045', type: 'mutual fund' },
+  ],
+  holdings: [
+    { account_id: 'brk1', security_id: 's_vti', quantity: 800, institution_value: 200000, cost_basis: 150000 },
+    { account_id: 'brk1', security_id: 's_btc', quantity: 0.5, institution_value: 40000, cost_basis: null },
+    { account_id: 'k401', security_id: 's_tgt', quantity: 3200, institution_value: 315000, cost_basis: 260000 },
+    { account_id: 'roth1', security_id: 's_aapl', quantity: 400, institution_value: 88000, cost_basis: 41000 },
+  ],
+  liabilities: {
+    mortgage: [{ account_id: 'mtg1', interest_rate: { percentage: 6.25 }, next_monthly_payment: 3150, origination_principal_amount: 560000, maturity_date: '2052-06-01', property_address: { city: 'Palo Alto', street: '1 Main St' } }],
+    student: [{ account_id: 'std1', interest_rate_percentage: 5.5, minimum_payment_amount: 310 }],
+    credit: [{ account_id: 'cc1', aprs: [{ apr_percentage: 21.9 }], minimum_payment_amount: 95 }],
+  },
+  // /investments/transactions — monthly contributions Jan–Jun 2026 (drives the
+  // inferred savings rate). brk1 $2k/mo, k401 $1.5k/mo (Alex), roth1 $500/mo (Sam).
+  investmentTransactions: [
+    ...monthly('brk1', 2000), ...monthly('k401', 1500), ...monthly('roth1', 500),
+  ],
+};
+
+function monthly(account_id, amount) {
+  return ['2026-01-15', '2026-02-15', '2026-03-15', '2026-04-15', '2026-05-15', '2026-06-15']
+    .map((date) => ({ account_id, type: 'cash', subtype: 'contribution', amount: -amount, date }));
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@plan-fi/imports",
+  "version": "0.6.0",
+  "description": "Import customer financial data from aggregators (Plaid, MX, Finicity, FDX) or CSV/OFX files into Planfi plans via a canonical model.",
+  "type": "module",
+  "license": "MIT",
+  "types": "./planfi-import.d.ts",
+  "bin": {
+    "planfi-import": "./bin/planfi-import.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./planfi-import.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./canonical": "./src/canonical.ts",
+    "./fixtures/*": "./fixtures/*"
+  },
+  "files": [
+    "src",
+    "bin",
+    "fixtures",
+    "docs",
+    "planfi-import.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "demo": "node -e \"import('./src/index.mjs').then(async({importToPlan})=>{const{plaidRaw}=await import('./fixtures/plaid-sandbox.mjs');console.log(JSON.stringify(importToPlan('plaid',plaidRaw),null,2))})\""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "zod": "^4.3.5"
+  },
+  "keywords": [
+    "planfi",
+    "plaid",
+    "mx",
+    "finicity",
+    "fdx",
+    "financial-data-exchange",
+    "open-banking",
+    "mastercard-open-banking",
+    "akoya",
+    "csv",
+    "ofx",
+    "aggregator",
+    "financial-data",
+    "import",
+    "adapter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holdequity/planfi-import.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/holdequity/planfi-import#readme",
+  "bugs": {
+    "url": "https://github.com/holdequity/planfi-import/issues"
+  }
+}

package/planfi-import.d.ts

@@ -0,0 +1,270 @@
+/**
+ * planfi-import.d.ts — hand-written type declarations for the package entry
+ * point (src/index.mjs). Self-contained on purpose: the runtime is zero-dep
+ * ESM JavaScript, and consumers should get full types without TypeScript
+ * having to compile the shipped `src/canonical.ts` (which remains the
+ * annotated source of truth these declarations mirror — keep them in sync).
+ */
+
+// ── Canonical Financial Profile (mirrors src/canonical.ts) ──────────────────
+
+/** Broad account family, provider-independent. */
+export type AccountClass = 'depository' | 'investment' | 'loan' | 'credit' | 'property';
+
+/** Tax treatment of an investment/holding bucket. `na` = not applicable (debt, cash). */
+export type TaxTreatment = 'taxable' | 'traditional' | 'roth' | 'hsa' | '529' | 'na';
+
+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, when the institution reported it. */
+  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). */
+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 }>;
+}
+
+// ── Structured results (v0.2.0) ─────────────────────────────────────────────
+
+/**
+ * Stable machine-readable warning codes. Append-only: a released code never
+ * changes meaning. Message text may improve between versions; codes will not.
+ */
+export type WarningCode =
+  | 'CLASSIFICATION_GUESSED'
+  | 'NO_COST_BASIS'
+  | 'COARSE_INFERENCE'
+  | 'CONTRIBUTION_CLAMPED'
+  | 'CONTRIBUTION_IMPLAUSIBLE'
+  | 'HSA_FOLDED_INTO_PORTFOLIO'
+  | 'HSA_COVERAGE_ASSUMED'
+  | 'IRA_SPLIT_ASSUMED'
+  | 'HOME_VALUE_ESTIMATED'
+  | 'MORTGAGE_SKIPPED'
+  | 'NEGATIVE_BALANCE_CLAMPED'
+  | 'DEBT_RATE_MISSING'
+  | 'CSV_UNMAPPED_COLUMNS'
+  | 'CSV_TRANSACTIONS_ONLY'
+  | 'IMPORT_EMPTY';
+
+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.
+ */
+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. */
+  label: string;
+  /** One sentence: why the import couldn't supply this. */
+  why: string;
+}
+
+export interface CanonicalFinancialProfile {
+  /** Adapter source id: 'plaid' | 'mx' | 'finicity' | 'fdx' | ... */
+  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. */
+export interface SourceAdapter<Raw = unknown> {
+  readonly source: string;
+  normalize(raw: Raw): CanonicalFinancialProfile;
+}
+
+// ── Emitted plan (generate_financial_plan wire body) ────────────────────────
+// The body is validated server-side by the engine's Zod schema; typing it
+// loosely here keeps this package decoupled from engine releases.
+export interface PlanfiPlan {
+  name: string;
+  earners: Array<{
+    name: string;
+    age?: number;
+    retirement_age?: number;
+    annual_salary?: number;
+    retirement_accounts?: {
+      k401?: { employee_annual: number };
+      ira?: { type: 'traditional' | 'roth' | 'both'; annual: number };
+      hsa?: { coverage: 'self' | 'family'; annual: number };
+    };
+  }>;
+  stocks: { current_value: number; monthly_contribution: number; annual_return: number };
+  cash: { current_value: number; monthly_contribution: number; annual_return: number };
+  account_balances: { taxable: number; traditional: number; roth: number };
+  real_estate?: Array<{
+    name: string;
+    current_value: number;
+    annual_appreciation: number;
+    mortgage?: { balance: number; rate: number; years_remaining: number };
+  }>;
+  debts?: Array<{ name: string; balance: number; rate: number; min_payment: number; asset_name?: string; asset_value?: number }>;
+  speculative?: Array<{ name: string; current_value: number; annual_growth_rate: number }>;
+  education_account?: { enabled: boolean; initialBalance: number; monthlyContribution: number };
+  tax_settings: { state: string };
+  desired_annual_spend?: number;
+  [key: string]: unknown;
+}
+
+export interface ImportResult {
+  /** POST this to /v1/tools/generate_financial_plan. */
+  plan: PlanfiPlan;
+  warnings: ImportWarning[];
+  needsInput: NeedsInput[];
+  /** The full canonical profile (ticker/shares/cost-basis preserved). */
+  cfp: CanonicalFinancialProfile;
+}
+
+export interface ToPlanfiOptions {
+  /** Two-letter US state used when the owner context has none. Default 'CA'. */
+  defaultState?: string;
+}
+
+// ── Functions + adapters (mirrors src/index.mjs exports) ────────────────────
+
+/**
+ * One-call import: raw provider payload → { plan, warnings, needsInput, cfp }.
+ * @throws if `source` is not a registered adapter id.
+ */
+export function importToPlan(
+  source: 'plaid' | 'mx' | 'finicity' | 'fdx' | 'csv' | 'ofx' | (string & {}),
+  raw: object,
+  opts?: ToPlanfiOptions,
+): ImportResult;
+
+/** The shared mapper: Canonical Financial Profile → wire body + diagnostics. */
+export function toPlanfiPlan(
+  cfp: CanonicalFinancialProfile,
+  opts?: ToPlanfiOptions,
+): { plan: PlanfiPlan; warnings: ImportWarning[]; needsInput: NeedsInput[] };
+
+/** Map a provider (type, subtype) to the canonical class + tax treatment. */
+export function classify(
+  type: string,
+  subtype?: string,
+): { accountClass: AccountClass; taxTreatment: TaxTreatment; confidence: 'high' | 'medium' | 'low' };
+
+/** Map a provider security type ('etf', 'Mutual Fund', …) → canonical AssetType. */
+export function classifyAsset(securityType?: string): AssetType;
+
+/** Infer a monthly contribution rate from investment transactions. */
+export function inferMonthlyContribution(
+  txns: Array<{ account_id?: string; type?: string; subtype?: string; amount?: number; date?: string }>,
+  opts?: { windowMonths?: number },
+): number;
+
+/** Group transactions by account_id → inferred monthly contribution each. */
+export function contributionsByAccount(
+  txns: Array<{ account_id?: string; type?: string; subtype?: string; amount?: number; date?: string }>,
+  opts?: { windowMonths?: number },
+): Record<string, number>;
+
+export declare const plaidAdapter: SourceAdapter<object>;
+export declare const mxAdapter: SourceAdapter<object>;
+export declare const finicityAdapter: SourceAdapter<object>;
+
+/**
+ * FDX (Financial Data Exchange — the US open-banking standard; Akoya speaks
+ * it natively) → CFP. Raw shape: { accounts, holdings?, transactions?, owner?,
+ * asOf? } where accounts are FDX Account entities, wrapped
+ * ({ depositAccount: {…} } / { investmentAccount: {…} } / { loanAccount: {…} }
+ * / { locAccount: {…} }) or already flattened.
+ */
+export declare const fdxAdapter: SourceAdapter<object>;
+
+/** One CSV file handed to the csv adapter (the keyless path). */
+export interface CsvFile {
+  /** Used in warnings and as the fallback account name (Schwab positions). */
+  name?: string;
+  /** Force the mapping; omitted → the header fingerprint decides. */
+  kind?: 'accounts' | 'holdings' | 'transactions';
+  content: string;
+}
+
+/** CSV exports → CFP. Raw shape: { files: CsvFile[], owner?, asOf? }. */
+export declare const csvAdapter: SourceAdapter<{ files: CsvFile[]; owner?: OwnerContext; asOf?: string }>;
+
+/** OFX 1.x (SGML) / 2.x (XML) → CFP. Raw shape: { content: string, owner?, asOf? }. */
+export declare const ofxAdapter: SourceAdapter<{ content: string; owner?: OwnerContext; asOf?: string }>;
+
+/** Registry of source adapters by id. */
+export declare const ADAPTERS: Record<string, SourceAdapter<object>>;