// financial/src/documents.jsx — the Documents tab: the drop-zone portal.
//
// Drop any financial document. It is uploaded to Cloud Storage (kept — a
// later, better extractor can re-read it), a record is written, a cheap
// classify call names its KIND, and the kind routes it: payslips and tax
// returns go to the parsers that already exist on their tabs, statements
// and policies are extracted here (lib/documentKinds shapes, nulls over
// guesses, a source for every figure). Every extraction is shown next to
// its warnings and applied only when a human clicks:
//
// 401(k) statement → the money-source SPLIT into retirementConfig
// (the balance stays live from Monarch); the newest-
// DATED statement is the one in force, never the
// last uploaded
// any account → its fund positions (401(k)/403(b)/401(a), UK
// statement pension, 529, brokerage) become holdings for an
// account Monarch does not itemize — no click, since
// they are data rather than a config choice
// (lib/statementPositions → derived/statementHoldings)
// tax return → the Tax tab's own save, after review
// insurance policy → a row on the Estate tab's policies, after review
// everything else → history only
//
// The cadence panel says which kinds are overdue; the same audit feeds the
// plan-completeness card and the insight rule, so the prompt appears on the
// pages already being opened.
const { useState, useEffect, useContext, useMemo, useRef, useCallback } = React;
const { DataContext, useToast, callFn, fmtCur, fmtDate, timeAgo } = window.FinanceShared;
// The upload itself is the DataProvider's uploadDocumentFile — the ONE path
// every surface (this drop zone, the payslip buttons) puts a file through.
// The contract behind it (limits, path, error table, pending/reconcile) is
// lib/documentUpload, mirrored and tested. Read defensively: the HTML and
// the slices are cached independently, and a slice must stay harmless
// against HTML that has not loaded the lib yet.
const DU = window.DocumentUpload || null;
const MAX_FILE_MB = DU ? Math.round(DU.MAX_FILE_BYTES / 1024 / 1024) : 7;
const readBase64 = (file) => new Promise((resolve, reject) => {
const r = new FileReader();
r.onload = () => resolve(String(r.result).split(',')[1]);
r.onerror = reject;
r.readAsDataURL(file);
});
const KIND_COLOR = { payslip: '#3b82f6', taxReturn: '#f59e0b', k401Statement: '#8b5cf6', ukPensionStatement: '#6366f1', brokerageStatement: '#06b6d4', plan529Statement: '#64748b', insurancePolicy: '#10b981', other: '#475569' };
function Tag({ color, children }) {
return {children};
}
// ── One document's review panel ────────────────────────────────────────────
function money(v) { return v == null ? '—' : fmtCur(v); }
function ExtractionView({ doc }) {
const x = doc.extracted;
if (!x) return null;
const rows = [];
const push = (k, v) => { if (v !== undefined && v !== null && typeof v !== 'object') rows.push([k, typeof v === 'number' ? (Math.abs(v) >= 100 ? fmtCur(v) : String(v)) : String(v)]); };
Object.entries(x).forEach(([k, v]) => { if (k !== 'sources' && k !== 'notes' && k !== 'moneySources' && k !== 'holdings' && k !== 'beneficiaries' && typeof v !== 'object') push(k, v); });
['contributionsThisPeriod', 'contributionsYtd'].forEach((g) => { if (x[g] && typeof x[g] === 'object') Object.entries(x[g]).forEach(([k, v]) => push(`${g}.${k}`, v)); });
return (
Upload not finished — the record is settled on the next load once it is an hour old (promoted if the file landed, removed if not).
}
{doc.error &&
{doc.error}
}
{doc.warnings && doc.warnings.length > 0 &&
{doc.warnings.map((w, i) =>
⚠ {w}
)}
}
{open && doc.extracted &&
}
);
}
// ── The tab ────────────────────────────────────────────────────────────────
function Documents({ setTab }) {
const { uid, documents, documentUsage, saveDocument, deleteDocument, uploadDocumentFile, saveRetirementConfig, saveTaxReturn, updateEstatePolicies, estatePlan, kidsPlan, retirementConfig, monarchAuth, reload, accounts, netWorthSnapshots, accountBalanceHistory, monarchHoldings, statementHoldings } = useContext(DataContext);
const { show, Toast } = useToast();
const DK = window.DocumentKinds;
const [dragOver, setDragOver] = useState(false);
const [busyIds, setBusyIds] = useState({});
const [queue, setQueue] = useState([]); // { name, status, error }
const fileRef = useRef(null);
const setBusy = (id, v) => setBusyIds(b => ({ ...b, [id]: v }));
const cadence = useMemo(() => DK ? DK.cadenceAudit(documents || []) : null, [DK, documents]);
// Which statement each applied field came from, and whether a newer-DATED
// one is waiting (lib/documentKinds.appliedFieldStatus).
const appliedFields = useMemo(() => DK && DK.appliedFieldStatus ? DK.appliedFieldStatus(retirementConfig, documents || []) : [], [DK, retirementConfig, documents]);
// The latest statement of each account extracted before fund positions
// were read — one re-extract each turns it into positions.
const SP = window.StatementPositions;
const positionRereads = useMemo(() => SP ? SP.rereadCandidates({ documents: documents || [], accounts, monarchHoldings: monarchHoldings || [], accountMap: retirementConfig && retirementConfig.accountMap }) : [], [SP, documents, accounts, monarchHoldings, retirementConfig]);
const statementCoverage = useMemo(() => statementHoldings && statementHoldings.accounts ? Object.values(statementHoldings.accounts) : [], [statementHoldings]);
const month = DK ? DK.monthKey() : '';
// The month's cap: the standing MONTHLY_CALL_CAP plus any dated one-time
// allowance (a bulk backfill month) — one number, from the lib.
const monthCap = DK ? (DK.capForMonth ? DK.capForMonth(month) : DK.MONTHLY_CALL_CAP) : '—';
// `months` counts extractions (the capped budget) only from usage schema 2
// on; before that it was classifications and extractions mixed, and the
// callable retires it to `legacyMonths` on the next drop.
const usageCurrent = documentUsage && DK && documentUsage.schema === DK.USAGE_SCHEMA;
const used = usageCurrent && documentUsage.months ? Number(documentUsage.months[month] || 0) : 0;
const classified = usageCurrent && documentUsage.classifyMonths ? Number(documentUsage.classifyMonths[month] || 0) : 0;
// ── The pipeline for one file ──────────────────────────────────────────
const classifyAndRoute = useCallback(async (doc, base64, mimeType) => {
setBusy(doc.id, true);
try {
const res = await callFn('processDocument', { action: 'classify', fileBase64: base64, mimeType, fileName: doc.fileName });
if (res.paused) { await saveDocument({ id: doc.id, status: 'uploaded', error: res.reason }); show(res.reason, 'error'); return; }
const c = res.classification;
const next = { id: doc.id, status: 'classified', kind: c.kind, classification: c, statementDate: c.statementDate, institution: c.institution, who: c.who, accountHint: c.accountHint, error: null };
await saveDocument(next);
const k = DK.kindOf(c.kind);
if (k.route === 'extract') await extract({ ...doc, ...next }, base64, mimeType);
else if (k.route === 'parsePayslip') {
// The existing parser saves the payslip itself under compensation/{year}/payslips.
const r = await callFn('parsePayslip', { imageBase64: base64, mimeType, fallbackYear: c.statementDate ? Number(c.statementDate.slice(0, 4)) : new Date().getFullYear() });
await saveDocument({ id: doc.id, status: 'routed', routedTo: 'parsePayslip', extracted: r && r.parsed ? r.parsed : r || null, appliedAt: new Date().toISOString() });
reload();
} else if (k.route === 'parseTaxReturn') {
const r = await callFn('parseTaxReturn', { fileBase64: base64, mimeType, fallbackYear: c.statementDate ? Number(c.statementDate.slice(0, 4)) - 1 : new Date().getFullYear() - 1 });
await saveDocument({ id: doc.id, status: 'extracted', routedTo: 'parseTaxReturn', extracted: { taxYear: r.year, ...r.parsed }, warnings: r.warnings || [], statementDate: doc.statementDate || `${r.year}-12-31` });
}
} catch (e) {
await saveDocument({ id: doc.id, status: 'error', error: e.message });
show(e.message, 'error');
}
setBusy(doc.id, false);
}, [saveDocument, show, reload]);
// Returns { ok } or { ok:false, exhausted } — `exhausted` is the callable's
// resource-exhausted (the month's cap genuinely reached), which the bulk
// retry below treats as "stop", not "next".
const budgetExhausted = (e) => /resource-exhausted/.test(String((e && e.code) || '')) || /budget for .* is used up/i.test(String((e && e.message) || ''));
const extract = useCallback(async (doc, base64, mimeType, opts) => {
const quiet = !!(opts && opts.quiet);
setBusy(doc.id, true);
let out = { ok: false };
try {
// A re-read names the kept file by its object path and the callable
// reads it server-side: fetching the download URL back from here is a
// cross-origin request the bucket does not grant ("Failed to fetch").
const req = { action: 'extract', kind: doc.kind, fileName: doc.fileName, mimeType: mimeType || doc.mimeType };
if (base64) req.fileBase64 = base64;
else {
const sp = DU ? DU.storagePathOf(doc) : doc.storagePath;
if (!sp) throw new Error('This record has no kept file to re-read — upload the statement again.');
req.storagePath = sp;
}
const res = await callFn('processDocument', req);
if (res.paused) { await saveDocument({ id: doc.id, error: res.reason }); if (!quiet) show(res.reason, 'error'); out = { ok: false, paused: true }; }
else {
const x = res.extracted || {};
await saveDocument({ id: doc.id, status: 'extracted', extracted: x, warnings: res.warnings || [], error: null,
statementDate: x.statementDate || x.effectiveDate || doc.statementDate || null, institution: x.provider || x.institution || x.insurer || doc.institution || null, extractedAt: new Date().toISOString() });
if (!quiet) show(`Read the ${DK.kindOf(doc.kind).label.toLowerCase()} — review before applying`);
out = { ok: true };
}
} catch (e) {
await saveDocument({ id: doc.id, status: 'error', error: e.message });
if (!quiet) show(e.message, 'error');
out = { ok: false, exhausted: budgetExhausted(e), message: e.message };
}
setBusy(doc.id, false);
return out;
}, [saveDocument, show]);
// ── Bulk retry of failed extractions ───────────────────────────────────
// The extraction counter once charged classifications too and kept
// counting past the cap ("96 of 60"), so every extraction in a busy month
// failed and its row stayed in error. The counter is fixed (usage schema
// 2 restarts it) but the rows do not repair themselves: this re-runs each
// failed extractable row from its kept file, in order, and stops at the
// first genuine cap so a real budget is not spent rewriting error rows.
const failedExtractions = useMemo(() => (documents || []).filter(d => d.status === 'error' && (d.storagePath || d.downloadUrl) && DK && DK.kindOf(d.kind) && DK.kindOf(d.kind).route === 'extract'), [documents, DK]);
const [retrying, setRetrying] = useState(null); // { done, total }
const retryFailed = async () => {
const list = failedExtractions;
if (!list.length || retrying) return;
setRetrying({ done: 0, total: list.length });
let ok = 0, exhausted = false;
for (const d of list) {
const r = await extract(d, null, null, { quiet: true });
if (r && r.ok) ok++;
if (r && r.exhausted) { exhausted = true; break; }
setRetrying(st => st ? { ...st, done: st.done + 1 } : st);
}
setRetrying(null);
if (exhausted) show(`${ok} re-read; the month's extraction budget is now genuinely used up — ${list.length - ok} still failed. Add a dated ONE_TIME_ALLOWANCE month in lib/documentKinds (a bulk upload) or wait for next month.`, 'error');
else show(`${ok} of ${list.length} failed extraction${list.length === 1 ? '' : 's'} re-read — review each before applying`);
};
// ── Re-reading statements for their fund positions ─────────────────────
// Statements extracted before the fund table was part of the shape have
// no positions. Only the newest-dated statement of each account Monarch
// does not itemize is re-read (older ones would never be used), in order,
// stopping at a genuine cap like the failed-row retry.
const [rereading, setRereading] = useState(null);
const rereadPositions = async () => {
const list = positionRereads;
if (!list.length || rereading) return;
setRereading({ done: 0, total: list.length });
let ok = 0, exhausted = false;
for (const d of list) {
const r = await extract(d, null, null, { quiet: true });
if (r && r.ok) ok++;
if (r && r.exhausted) { exhausted = true; break; }
setRereading(st => st ? { ...st, done: st.done + 1 } : st);
}
setRereading(null);
show(exhausted ? `${ok} re-read for positions; the month's extraction budget is used up — the rest wait for next month` : `${ok} of ${list.length} statement${list.length === 1 ? '' : 's'} re-read — their fund positions are on the Investments tab now`, exhausted ? 'error' : undefined);
};
// One file: through the repository (uploadDocumentFile: auth, preflight,
// pending → put → uploaded), then classify and route. A failed upload is
// reported by its title, Firebase code and the attempted path; nothing is
// left behind for it (the provider discards its pending record).
const processFiles = async (fileList) => {
const files = Array.from(fileList || []);
if (!files.length) return;
setQueue(files.map(f => ({ name: f.name, status: 'queued' })));
for (let i = 0; i < files.length; i++) {
const file = files[i];
const mark = (status, error) => setQueue(q => q.map((x, j) => j === i ? { ...x, status, error } : x));
mark('uploading');
let doc = null;
try {
doc = await uploadDocumentFile(file, { source: 'documents' });
} catch (e) {
mark('error', `${e.title || 'Upload failed'} — ${e.message}`);
show(`${e.title || 'Upload failed'}: ${e.message}`, 'error');
continue;
}
try {
mark('classifying');
const base64 = await readBase64(file);
await classifyAndRoute(doc, base64, doc.mimeType);
mark('done');
} catch (e) { mark('error', e.message); }
}
show(`${files.length} file${files.length === 1 ? '' : 's'} processed`);
setTimeout(() => setQueue([]), 6000);
};
// ── Applying an extraction ─────────────────────────────────────────────
const APPLY_LABEL = { k401Statement: 'Apply split to the plan', insurancePolicy: 'Add to Estate policies', taxReturn: 'Save to Tax tab' };
const apply = async (doc) => {
setBusy(doc.id, true);
try {
const x = doc.extracted;
if (doc.kind === 'k401Statement') {
// History uploads are welcome, but an older statement must never
// replace the split from a newer one — the date compared is the one
// the statement PRINTS, never when it was uploaded.
const asOf = DK.statementDateOf(doc);
const status = (DK.appliedFieldStatus(retirementConfig, documents || []) || []).find(f => f.key === 'k401Sources');
const inForce = status && status.inForce && status.inForce.date;
if (!asOf) throw new Error('This statement has no statement date — set it (Re-extract) before applying');
if (inForce && asOf < inForce && !(status.inForce && status.inForce.seeded)) throw new Error(`This statement (${asOf}) is older than the split already in force (${inForce}) — kept as history, nothing applied`);
if (String(doc.who || '').toLowerCase() === 'spouse') throw new Error('This is the spouse\'s plan statement — its fund positions are used on the Investments tab; the money-source split is for your 401(k) only');
// The SPLIT only (rows + the stored k401Split, together). The 401(k)
// balance itself stays live from Monarch.
const patch = window.TaxBuckets.applyStatementSplit(retirementConfig, { rows: x.moneySources, asOf, documentId: doc.id, fileName: doc.fileName || null });
if (!patch) throw new Error('No money-source balances on this statement — nothing to apply');
await saveRetirementConfig(patch);
const r = patch.k401Split, tot = r.pretax + r.roth;
show(`401(k) split applied from the ${asOf} statement: Roth ${fmtCur(r.roth)} of ${fmtCur(tot)} (${tot ? (r.roth / tot * 100).toFixed(1) : 0}%) — the Retirement tab reads it now`);
} else if (doc.kind === 'insurancePolicy') {
const KIND = { term: 'term', whole: 'whole', universal: 'whole', group: 'group', accidentalDeath: 'adnd' };
const row = { insurer: x.insurer || '', kind: KIND[x.policyKind] || x.policyKind || 'other', insured: doc.who || (x.insured || 'you'), owner: 'insured', deathBenefit: x.deathBenefit || 0, annualPremium: x.annualPremium || null, beneficiaries: x.beneficiaries || [], expires: x.expires || '', documentId: doc.id };
// Re-applying a document, or applying a second copy of a policy
// already on file, updates that row instead of adding a twin — a
// twin doubles the household's cover on paper. Matched against the
// list as stored now, not this page's copy, which may predate a
// removal made in another tab.
let at = -1;
await updateEstatePolicies(stored => {
const policies = [...stored];
at = policies.findIndex((p) => p && ((p.documentId && p.documentId === doc.id) || EstatePlan.duplicatePolicies([p, row])[1] === 0));
if (at >= 0) {
const prev = policies[at];
policies[at] = { ...row, ...Object.fromEntries(Object.entries(prev).filter(([, v]) => v !== '' && v != null && !(Array.isArray(v) && !v.length))), documentId: prev.documentId || doc.id };
} else policies.push(row);
return policies;
});
show(at >= 0 ? `Already on the Estate tab as policy ${at + 1} — updated it rather than adding a duplicate` : 'Policy added to the Estate tab — review the insured and beneficiaries there');
} else if (doc.kind === 'taxReturn') {
const { taxYear, ...parsed } = x;
await saveTaxReturn(taxYear, parsed);
show(`${taxYear} return saved to the Tax tab`);
}
await saveDocument({ id: doc.id, status: 'applied', appliedAt: new Date().toISOString() });
} catch (e) { show(e.message, 'error'); }
setBusy(doc.id, false);
};
// Tie statements to the one account they are of (lib/documentReconcile
// .identify reads doc.accountId first). Empty clears back to auto.
const linkAccount = async (ids, accountId) => {
try {
for (const id of ids) await saveDocument({ id, accountId: accountId || null });
const a = (accounts || []).find(x => x.id === accountId);
show(accountId ? `${ids.length} statement${ids.length === 1 ? '' : 's'} linked to ${a ? (a.displayName || a.name) : 'the account'}` : 'Link cleared — matched automatically');
} catch (e) { show(e.message, 'error'); }
};
const setKind = async (doc, kind) => {
await saveDocument({ id: doc.id, kind, status: doc.extracted ? 'classified' : doc.status, extracted: null, warnings: [], appliedAt: null });
};
const openPdf = (doc) => window.open(doc.downloadUrl, '_blank', 'noopener');
const lastSync = monarchAuth && monarchAuth.lastSync;
return (
{Toast}
Documents
{used} of {monthCap} extractions used in {month}{classified ? ` (${classified} classified, not capped)` : ''} · PDFs are kept in Storage · figures are applied only when you click
{/* C5: every extracted figure against the stored one (lib/documentReconcile). */}
{window.DocumentReconcile && window.FinanceProducts && window.FinanceProducts.DocumentReconcileCard && (
)}
{window.DocumentReconcile && window.DocumentReconcile.history && window.FinanceProducts && window.FinanceProducts.StatementHistoryCard && (
k && k.name).filter(Boolean) })}
accounts={accounts} onLink={linkAccount} />
)}
{/* Where each applied field came from (statement date, file), and the
newer statement that is waiting — applied by statement date, never
by upload order. */}
{appliedFields.length > 0 && (
Each account uses its newest-dated statement, and only while Monarch does not itemize it — a synced position is never overwritten. Funds are valued at their statement weight × the live balance.{positionRereads.length > 0 ? ` ${positionRereads.length} latest statement${positionRereads.length === 1 ? ' was' : 's were'} read before fund positions were extracted; each re-read costs one of the month's ${monthCap} extractions.` : ''}