earnrate 0.1.4 → 0.2.1

package/dist/engine/wallet-summary.js

@@ -1,8 +1,8 @@
 import { bonusStatus } from "./bonus.js";
-import { pickedCategories } from "./evaluate.js";
-import { daysBetween, periodKey } from "./periods.js";
-import { rotationGap } from "./rotation.js";
+import { capUsed, pickedCategories } from "./evaluate.js";
+import { daysBetween } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
+import { rotationGap } from "./rotation.js";
 import { cardValuation } from "./valuation.js";
 function capSummaries(card, held, today) {
     const caps = new Map();
@@ -19,11 +19,7 @@ function capSummaries(card, held, today) {
         }
     }
     return [...caps].map(([key, { cap, rules }]) => {
-        const currentPeriod = periodKey(cap.period, today, held.anniversary ?? null);
-        const usage = held.cap_usage[key];
-        const spent = currentPeriod !== null && usage?.period === currentPeriod
-            ? usage.spent
-            : 0;
+        const { period: currentPeriod, spent } = capUsed(cap, key, held, today);
         return {
             key,
             rules,

package/dist/format/card-text.js

@@ -0,0 +1,79 @@
+import { earnText } from "../engine/text.js";
+// Card names, fees and requirements as earnrate.dev and its static search
+// pages show them. Node-free: the site bundles it.
+const ISSUERS = {
+    amex: 'American Express',
+    'bank-of-america': 'Bank of America',
+    'capital-one': 'Capital One',
+    chase: 'Chase',
+    citi: 'Citi',
+    column: 'Bilt',
+    sofi: 'SoFi',
+    'td-bank': 'TD Bank',
+    usbank: 'U.S. Bank',
+    'wells-fargo': 'Wells Fargo',
+};
+export const MEMBERSHIPS = {
+    'amazon-prime': 'Amazon Prime',
+    'bank-of-america-account': 'Bank of America checking or savings',
+    'bofa-rewards-member': 'BofA Rewards Member',
+    'bofa-rewards-preferred-plus': 'BofA Rewards Preferred Plus',
+    'bofa-rewards-preferred-honors': 'BofA Rewards Preferred Honors',
+    'bofa-rewards-premier': 'BofA Rewards Premier',
+};
+export const PICK_PERIODS = {
+    month: 'each month',
+    quarter: 'each quarter',
+    calendar_year: 'each year',
+    until_changed: 'until you change it',
+};
+export const CAP_PERIODS = {
+    month: 'a month',
+    quarter: 'a quarter',
+    calendar_year: 'a year',
+    cardmember_year: 'a card year',
+};
+export const words = (id) => id.replace(/[-_.]/g, ' ');
+// Whole dollars, for fees and caps.
+export const usd = (n) => `${n < 0 ? '−' : ''}$${Math.abs(Math.round(n)).toLocaleString('en-US')}`;
+export const issuerName = (id) => ISSUERS[id] ?? id;
+export const membershipName = (id) => MEMBERSHIPS[id] ?? words(id);
+export function cardText(catalog) {
+    const cards = new Map(catalog.cards.map((c) => [c.id, c]));
+    function shortName(id) {
+        const name = cards.get(id)?.name ?? id;
+        return name
+            .replace(/^American Express /, 'Amex ')
+            .replace(/^The Platinum Card from American Express$/, 'Amex Platinum')
+            .replace(/ (Visa Signature |Visa Infinite )?(Credit )?Card$/, '')
+            .replace(/ Card by /, ' by ');
+    }
+    function feeLabel(id) {
+        const card = cards.get(id);
+        const fee = card?.annual_fee;
+        if (fee === undefined)
+            return 'Annual fee not on file';
+        if (fee === 0)
+            return 'No annual fee';
+        const first = card?.first_year_fee;
+        if (first !== undefined && first !== fee)
+            return `${usd(fee)} a year (${first === 0 ? 'waived' : usd(first)} the first year)`;
+        return `${usd(fee)} a year`;
+    }
+    // `until` is the last day a time-limited rate applies, already formatted.
+    function requirementLines(cardId, r, until = null) {
+        const lines = [];
+        if (r.pick)
+            lines.push(`Pick ${r.pick.options.map(words).join(' or ')} as a bonus category (${PICK_PERIODS[r.pick.period]})`);
+        if (r.activation !== null)
+            lines.push(`Activate the bonus with ${issuerName(cards.get(cardId)?.issuer ?? '')} (free)`);
+        if (r.membership !== null)
+            lines.push(`With ${membershipName(r.membership)}`);
+        if (until !== null)
+            lines.push(`This rate runs through ${until}`);
+        if (r.cap)
+            lines.push(`Up to ${usd(r.cap.amount)} of spending ${CAP_PERIODS[r.cap.period] ?? ''}, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}`);
+        return lines;
+    }
+    return { cards, shortName, feeLabel, requirementLines };
+}

package/dist/format/cheat-sheet.js

@@ -0,0 +1,19 @@
+import { pct } from "../engine/text.js";
+export function formatCheatSheet(sheet) {
+    const labelWidth = Math.max(...sheet.rows.map((r) => r.label.length));
+    const cardWidth = Math.max(...sheet.rows.map((r) => (r.cardName ?? 'none of your cards').length));
+    const lines = [
+        sheet.scope === 'wallet'
+            ? `Your cheat sheet for ${sheet.quarter}`
+            : `The best card for each kind of purchase, ${sheet.quarter}`,
+        '',
+    ];
+    for (const row of sheet.rows) {
+        lines.push(`  ${row.label.padEnd(labelWidth)}  ${(row.cardName ?? 'none of your cards').padEnd(cardWidth)}  ${row.effectiveReturnPct === null ? '' : pct(row.effectiveReturnPct).padStart(5)}`.trimEnd());
+        if (row.note)
+            lines.push(`  ${' '.repeat(labelWidth)}  ${sheet.scope === 'wallet' ? '! ' : ''}${row.note}`);
+    }
+    if (sheet.notes.length > 0)
+        lines.push('', ...sheet.notes);
+    return `${lines.join('\n')}\n`;
+}

package/dist/format/explore.js

@@ -0,0 +1,114 @@
+import { feeText, money, pct } from "../engine/text.js";
+const wholeUsd = (n) => money(Math.round(n));
+const TOP_BEST = 10;
+export function formatExploration(r, all) {
+    const m = r.merchant;
+    const title = m.source === 'category'
+        ? m.resolvedName.toLowerCase()
+        : m.source === 'none'
+            ? `"${m.input}" (not recognized)`
+            : m.resolvedName;
+    if (r.ranked.length === 0)
+        return `No cards match at ${title}.\n`;
+    const shown = all ? r.ranked : r.ranked.slice(0, TOP_BEST);
+    const width = Math.max(...shown.map((e) => e.cardName.length));
+    const lines = [`Best cards for ${title}:`, ''];
+    shown.forEach((e, i) => {
+        const earned = e.earned === null ? '' : `  ${money(e.earned)}`;
+        lines.push(`${String(i + 1).padStart(2)}. ${e.cardName.padEnd(width)}  ${pct(e.effectiveReturnPct).padStart(5)}${earned}  ${feeText(e)}`);
+        for (const c of e.conditions)
+            lines.push(`    ${c}`);
+        const upgrade = e.withMembership[0];
+        if (upgrade)
+            lines.push(`    With ${upgrade.membership}: ${pct(upgrade.effectiveReturnPct)}.`);
+        for (const w of e.warnings)
+            lines.push(`    ! ${w}`);
+    });
+    if (r.ranked.length > shown.length)
+        lines.push(`  + ${String(r.ranked.length - shown.length)} more (--all lists them)`);
+    for (const w of r.warnings)
+        lines.push('', `! ${w}`);
+    lines.push('', ...r.assumptions);
+    return `${lines.join('\n')}\n`;
+}
+function picksText(picks) {
+    const parts = Object.entries(picks).map(([choice, options]) => `${choice}: ${options.join(', ')}`);
+    return parts.length === 0 ? '' : ` (picks ${parts.join('; ')})`;
+}
+function cardNamer(catalog) {
+    return (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+}
+function splitText(sim, name) {
+    const byCard = new Map();
+    for (const line of sim.lines) {
+        const first = line.cards[0];
+        if (first === undefined)
+            continue;
+        byCard.set(first, [...(byCard.get(first) ?? []), line.label]);
+    }
+    return [...byCard].map(([id, labels]) => `${labels.join(', ')} → ${name(id)}`);
+}
+const TOP_SIMULATED = 5;
+export function formatCatalogSimulation(r, catalog, all) {
+    const name = cardNamer(catalog);
+    const first = r.singles[0];
+    if (!first)
+        return 'No cards match.\n';
+    const top = all ? 20 : TOP_SIMULATED;
+    const lines = [
+        `A year of this spending: ${wholeUsd(first.spend)}.`,
+        '',
+        'Best single cards (rewards minus annual fee, per year):',
+    ];
+    r.singles.slice(0, top).forEach((s, i) => {
+        const card = s.cards[0];
+        if (!card)
+            return;
+        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeUsd(s.net)}  (${wholeUsd(s.rewards)} rewards, ${wholeUsd(s.annualFees)} fee)${picksText(card.picks)}`);
+    });
+    const pairs = r.pairs.slice(0, top);
+    if (pairs.length > 0) {
+        lines.push('', 'Best two-card pairs:');
+        pairs.forEach((s, i) => {
+            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeUsd(s.net)}`);
+            if (s.alternatives.length > 0)
+                lines.push(`    Same result with ${s.alternatives.map(name).join(' or ')} as the second card.`);
+            for (const split of splitText(s, name))
+                lines.push(`    ${split}`);
+        });
+        const bestPair = r.pairs[0];
+        if (bestPair && bestPair.net <= first.net)
+            lines.push('', `One card is enough here: no pair beats ${name(first.cards[0]?.cardId ?? '')}.`);
+    }
+    const notes = new Set([
+        ...r.singles.slice(0, top).flatMap((s) => s.notes),
+        ...pairs.flatMap((s) => s.notes),
+    ]);
+    if (notes.size > 0)
+        lines.push('', ...notes);
+    lines.push('', "Assumes each card's best picks, activations done each quarter, and no welcome bonuses.");
+    return `${lines.join('\n')}\n`;
+}
+export function formatAdditions(r, catalog, all) {
+    const name = cardNamer(catalog);
+    const lines = [
+        `Your wallet earns about ${wholeUsd(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeUsd(r.current.annualFees)} in annual fees` : ''}.`,
+    ];
+    for (const split of splitText(r.current, name))
+        lines.push(`  ${split}`);
+    const gains = r.additions.filter((a) => a.gain > 0);
+    if (gains.length === 0) {
+        lines.push('', 'No card would add more than its annual fee costs.');
+    }
+    else {
+        lines.push('', 'Cards that would add the most (after their annual fee):');
+        gains.slice(0, all ? 20 : TOP_SIMULATED).forEach((a, i) => {
+            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeUsd(a.gain)} a year  (+${wholeUsd(a.extraRewards)} rewards, ${wholeUsd(a.annualFee)} fee)${picksText(a.picks)}`);
+        });
+    }
+    const notes = new Set(r.current.notes);
+    if (notes.size > 0)
+        lines.push('', ...notes);
+    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh.');
+    return `${lines.join('\n')}\n`;
+}

package/dist/format/offers.js

@@ -0,0 +1,33 @@
+import { feeText, money } from "../engine/text.js";
+const TOP = 10;
+function reward(o, currencyName) {
+    if (o.dollars !== null)
+        return money(o.dollars);
+    return `${(o.points ?? 0).toLocaleString('en-US')} ${currencyName}`;
+}
+export function formatOffers(c, currencyName, all) {
+    if (c.offers.length === 0) {
+        return `No published welcome offers match.${c.withoutOffer.length > 0 ? ` ${String(c.withoutOffer.length)} matching card(s) have none on file.` : ''}\n`;
+    }
+    const shown = all ? c.offers : c.offers.slice(0, TOP);
+    const width = Math.max(...shown.map((o) => o.cardName.length));
+    const lines = [];
+    shown.forEach((o, i) => {
+        const weeks = (o.months * 52) / 12;
+        const pace = o.spend > 0 ? ` (about ${money(Math.round(o.spend / weeks))} a week)` : '';
+        const spend = o.spend > 0
+            ? `after ${money(o.spend)} in ${String(o.months)} month${o.months === 1 ? '' : 's'}${pace}`
+            : 'with no spending required';
+        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${money(Math.round(o.firstYearValue))} the first year`, `    ${reward(o, currencyName(o.currency))} ${spend}. ${feeText(o)[0]?.toUpperCase() ?? ''}${feeText(o).slice(1)}.${o.held ? ' In your wallet.' : ''}`);
+        if (o.validTo)
+            lines.push(`    Offer ends ${o.validTo}.`);
+        if (o.note)
+            lines.push(`    ${o.note}`);
+    });
+    if (c.offers.length > shown.length)
+        lines.push(`  + ${String(c.offers.length - shown.length)} more (--all lists them)`);
+    if (c.withoutOffer.length > 0)
+        lines.push('', `${String(c.withoutOffer.length)} matching card(s) have no published offer on file.`);
+    lines.push('', ...c.notes);
+    return `${lines.join('\n')}\n`;
+}

package/dist/{cli/format.js → format/recommendation.js}

@@ -1,11 +1,7 @@
+import { money, pct } from "../engine/text.js";
 export const plain = (_format, text) => text;
 const TOP = 3;
-const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
 const cents = (n) => `$${n.toFixed(2)}`;
-const amountText = (n) => `$${n.toLocaleString('en-US', {
-    minimumFractionDigits: Number.isInteger(n) ? 0 : 2,
-    maximumFractionDigits: 2,
-})}`;
 const label = (c) => c.checkoutLabel ?? c.cardName;
 function header(rec, purchase) {
     const m = rec.merchant;
@@ -14,14 +10,16 @@ function header(rec, purchase) {
             ? `"${m.resolvedName}" (not recognized)`
             : m.source === 'caller'
                 ? `${m.resolvedName} (category given)`
-                : m.source === 'llm'
-                    ? m.category === 'other'
-                        ? `"${m.resolvedName}" (Claude couldn't place it)`
-                        : `${m.resolvedName} (classified by Claude)`
-                    : m.resolvedName,
+                : m.source === 'category'
+                    ? m.resolvedName
+                    : m.source === 'llm'
+                        ? m.category === 'other'
+                            ? `"${m.resolvedName}" (Claude couldn't place it)`
+                            : `${m.resolvedName} (classified by Claude)`
+                        : m.resolvedName,
     ];
     if (purchase.amount !== null)
-        parts.push(amountText(purchase.amount));
+        parts.push(money(purchase.amount));
     if (m.channel)
         parts.push(m.channel === 'online' ? 'online' : 'in-store');
     return parts.join(' · ');

package/dist/format/wallet-yaml.js

@@ -0,0 +1,45 @@
+import { parse, stringify } from 'yaml';
+import { walletProblems } from "../data/integrity.js";
+import { WalletSchema } from "../schema/wallet.js";
+// A wallet as the YAML file the CLI reads, for moving it between the
+// website, the remote server and the command line. Node-free.
+function compact(wallet) {
+    return {
+        ...(Object.keys(wallet.valuations).length > 0
+            ? { valuations: wallet.valuations }
+            : {}),
+        ...(wallet.memberships.length > 0
+            ? { memberships: wallet.memberships }
+            : {}),
+        cards: wallet.cards.map((c) => ({
+            id: c.id,
+            ...(c.checkout_label === undefined
+                ? {}
+                : { checkout_label: c.checkout_label }),
+            ...(c.anniversary === undefined ? {} : { anniversary: c.anniversary }),
+            ...(Object.keys(c.cap_usage).length > 0
+                ? { cap_usage: c.cap_usage }
+                : {}),
+            ...(c.chosen === undefined ? {} : { chosen: c.chosen }),
+            ...(c.activated.length > 0 ? { activated: c.activated } : {}),
+            ...(c.bonus === undefined ? {} : { bonus: c.bonus }),
+        })),
+    };
+}
+export function walletYaml(wallet) {
+    return `# Your earnrate wallet: the cards you hold, by id. Never card numbers.\n# For the command line, save it as ~/.earnrate/wallet.yaml\n\n${stringify(compact(wallet))}`;
+}
+export function parseWalletYaml(text, catalog) {
+    let raw;
+    try {
+        raw = parse(text);
+    }
+    catch {
+        return "That isn't a wallet: it isn't valid YAML.";
+    }
+    const result = WalletSchema.safeParse(raw);
+    if (!result.success)
+        return "That isn't an earnrate wallet.";
+    const problems = walletProblems(result.data, catalog);
+    return problems.length > 0 ? problems.join(' ') : result.data;
+}

package/dist/format/wallet.js

@@ -0,0 +1,38 @@
+import { money } from "../engine/text.js";
+export function formatWalletSummary(summary) {
+    return summary.cards
+        .map((c) => {
+        const caps = c.caps
+            .filter((cap) => cap.remaining !== null)
+            .map((cap) => `${cap.key} ${money(cap.spent)} of ${money(cap.amount)} used for ${cap.currentPeriod ?? ''}`);
+        const chosen = c.chosen
+            ? `; chosen categories for ${c.chosen.period}${c.chosen.current ? '' : ' (out of date)'}`
+            : '';
+        const onlyAt = c.onlyAt ? `; works only at ${c.onlyAt.join(', ')}` : '';
+        const rotation = c.rotationGap === null
+            ? ''
+            : `; rotating categories for ${c.rotationGap} not in earnrate yet`;
+        const b = c.bonus;
+        const bonus = b?.state === 'open' && b.spend !== null
+            ? `; welcome bonus ${money(b.spent)} of ${money(b.spend)} spent, due ${b.deadline ?? ''}`
+            : b
+                ? `; welcome bonus ${b.state}`
+                : '';
+        return `- ${c.checkoutLabel ?? c.cardName} (${c.cardId}): ${c.currency} at ${String(c.centsPerUnit)}¢${caps.length > 0 ? `; ${caps.join(', ')}` : ''}${chosen}${rotation}${onlyAt}${bonus}`;
+    })
+        .join('\n');
+}
+export function formatBooking(amount, cardId, cap, bonus) {
+    const messages = [];
+    if (cap) {
+        const left = Math.max(0, cap.capAmount - cap.after);
+        messages.push(`Recorded ${money(amount)} on ${cardId} against "${cap.capKey}": ${money(cap.before)} → ${money(cap.after)} of ${money(cap.capAmount)} for ${cap.period}, ${money(left)} left.`);
+    }
+    if (bonus) {
+        const left = Math.max(0, bonus.spend - bonus.after);
+        messages.push(left === 0
+            ? `Welcome bonus spend met on ${cardId}: ${money(bonus.after)} of ${money(bonus.spend)}.`
+            : `Welcome bonus on ${cardId}: ${money(bonus.after)} of ${money(bonus.spend)} spent, ${money(left)} to go by ${bonus.deadline ?? 'the deadline'}.`);
+    }
+    return messages.join(' ');
+}

package/dist/import/analyze.js

@@ -1,11 +1,11 @@
 import { bonusStatus, countsTowardBonus } from "../engine/bonus.js";
-import { categoryMatches } from "../engine/evaluate.js";
+import { capByKey, categoryMatches } from "../engine/evaluate.js";
 import { periodKey } from "../engine/periods.js";
-import { applyBooking, capBooking } from "../engine/record.js";
 import { recommend } from "../engine/recommend.js";
+import { applyBooking, capBooking } from "../engine/record.js";
+import { roundCents } from "../engine/text.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { cleanDescriptor } from "./statement.js";
-const round = (n) => Math.round(n * 100) / 100;
 function resolveLine(catalog, line) {
     const cleaned = cleanDescriptor(line.description);
     // "NAME-CHEAP.COM* LV0I6X": the part before the asterisk names the merchant.
@@ -30,12 +30,10 @@ function resolveLine(catalog, line) {
 function capPeriodKey(catalog, wallet, booking, date) {
     const card = catalog.cards.find((c) => c.id === booking.cardId);
     const held = wallet.cards.find((c) => c.id === booking.cardId);
-    const shared = card?.caps.find((c) => c.id === booking.capKey);
-    const inline = card?.rules.find((r) => r.id === booking.capKey)?.cap;
-    const period = shared?.period ?? (typeof inline === 'object' ? inline.period : undefined);
-    if (!period)
+    const cap = card && capByKey(card, booking.capKey);
+    if (!cap)
         return null;
-    return periodKey(period, date, held?.anniversary ?? null);
+    return periodKey(cap.period, date, held?.anniversary ?? null);
 }
 // Replays the statements twice: once on the cards actually used, once on
 // earnrate's picks, each with its own running cap usage, so a cap that fills
@@ -76,7 +74,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
         if (progress &&
             countsTowardBonus(progress, line.date) &&
             !alreadyRecorded(entry, 'bonus')) {
-            progress.after = round(Math.max(0, progress.after + line.amount));
+            progress.after = roundCents(Math.max(0, progress.after + line.amount));
             progress.entries.push(entry);
         }
         const { name, merchant, known } = resolveLine(catalog, line);
@@ -96,7 +94,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
                 const signed = line.amount < 0
                     ? {
                         ...booking,
-                        after: round(Math.max(0, booking.before + line.amount)),
+                        after: roundCents(Math.max(0, booking.before + line.amount)),
                     }
                     : booking;
                 bookings.push({ ...entry, booking: signed });
@@ -181,21 +179,21 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
         from: sorted[0]?.line.date ?? '',
         to: sorted.at(-1)?.line.date ?? '',
         purchases,
-        spend: round(spend),
-        refunds: round(refunds),
-        earned: round(earned),
-        best: round(best),
+        spend: roundCents(spend),
+        refunds: roundCents(refunds),
+        earned: roundCents(earned),
+        best: roundCents(best),
         byCard: [...byCard.values()].map((t) => ({
             ...t,
-            spend: round(t.spend),
-            earned: round(t.earned),
+            spend: roundCents(t.spend),
+            earned: roundCents(t.earned),
         })),
         missed: [...missed.values()]
             .map((m) => ({
             ...m,
-            spend: round(m.spend),
-            earned: round(m.earned),
-            best: round(m.best),
+            spend: roundCents(m.spend),
+            earned: roundCents(m.earned),
+            best: roundCents(m.best),
         }))
             .sort((a, b) => b.best - b.earned - (a.best - a.earned)),
         coding: [...coding.values()].sort((a, b) => b.count - a.count),

package/dist/mcp/context.js

@@ -0,0 +1,92 @@
+import { walletProblems } from "../data/integrity.js";
+import { EMPTY_WALLET, walletFromCards } from "../engine/transient.js";
+import { formatNotes } from "../format/cards.js";
+import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
+import { defined } from "./inputs.js";
+export const fail = (text) => ({
+    content: [{ type: 'text', text }],
+    isError: true,
+});
+export const ALL_CARDS_NOTE = "The user hasn't named their cards, so this covers every card earnrate knows. That's a complete answer. If they want the best of their own cards, they can name them (pass them as `cards`); saving a wallet is optional.";
+// What every tool shares: the saved wallet, merchant resolution, and which
+// cards an answer is about.
+export function makeContext(deps) {
+    const { catalog } = deps;
+    const theWallet = deps.savedWallets === 'file'
+        ? `the wallet at ${deps.store.where}`
+        : 'the saved wallet';
+    const noWallet = `There's no saved wallet yet${deps.savedWallets === 'file' ? ` (${deps.store.where})` : ''}. Answers don't need one: they cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.`;
+    // Read on every call, so edits to the wallet apply without a restart.
+    async function wallet() {
+        let loaded;
+        try {
+            const found = await deps.store.load();
+            if (found === null)
+                return noWallet;
+            loaded = found;
+        }
+        catch (e) {
+            return `Couldn't read ${theWallet}: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        const problems = walletProblems(loaded, catalog);
+        return problems.length > 0
+            ? `${theWallet[0]?.toUpperCase() ?? ''}${theWallet.slice(1)} has problems:\n${problems.map((p) => `- ${p}`).join('\n')}`
+            : loaded;
+    }
+    // No saved wallet is the normal state, not a failure: it reads as an
+    // empty one, with a note on how to start one.
+    async function readableWallet() {
+        const w = await wallet();
+        if (typeof w !== 'string')
+            return { wallet: w, start: null };
+        return w === noWallet ? { wallet: EMPTY_WALLET, start: w } : w;
+    }
+    // The caller's category is free and comes before the paid Claude fallback;
+    // neither ever overrides a merchant earnrate already knows.
+    async function resolve(merchant, channel, category) {
+        const known = resolveMerchant(catalog, merchant, channel);
+        if (known.source !== 'none' || category !== null || !deps.llm) {
+            return { merchant: withCallerCategory(known, category), notices: [] };
+        }
+        return deps.llm.resolve(catalog, merchant, channel);
+    }
+    // Cards named in the conversation come first, then the saved wallet; with
+    // neither (null), answers cover every card earnrate knows.
+    async function cardsFor(cards, memberships) {
+        if (cards && cards.length > 0)
+            return walletFromCards(catalog, {
+                cards: cards.map(({ cardId, ...rest }) => ({
+                    id: cardId,
+                    ...defined(rest),
+                })),
+                ...(memberships ? { memberships } : {}),
+            }, deps.today());
+        const read = await readableWallet();
+        if (typeof read === 'string')
+            return read;
+        return read.start === null ? read.wallet : null;
+    }
+    // A card change reports what that card still needs; other changes don't.
+    function changed(result, message, { notes = true } = {}) {
+        if (!result.ok)
+            return fail(result.error);
+        const output = {
+            message,
+            created: result.created,
+            cardIds: result.wallet.cards.map((c) => c.id),
+            memberships: result.wallet.memberships,
+            notes: result.notes,
+        };
+        const text = [
+            message,
+            `Wallet: ${output.cardIds.join(', ')}.`,
+            ...(notes ? [formatNotes(result.notes)] : []),
+        ].join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: output,
+        };
+    }
+    const cardName = (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+    return { wallet, readableWallet, resolve, cardsFor, changed, cardName };
+}