earnrate 0.1.2 → 0.1.4

package/dist/cli/explore.js

@@ -0,0 +1,364 @@
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { walletProblems } from "../data/integrity.js";
+import { loadCatalog, walletPath } from "../data/load.js";
+import { ALL_PERSONAL_CARDS, exploreCards, findCategory, } from "../engine/explore.js";
+import { isValuationProfile, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
+import { resolveSpendLines, simulateAdditions, simulateCatalog, } from "../engine/simulate.js";
+import { knownMemberships } from "../engine/setup.js";
+import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or points and miles cards only.
+  --no-fee                Cards with no annual fee.
+  --issuer <id>           One issuer's cards, e.g. chase or amex.
+  --business              Business cards instead of personal ones.
+  --closed                Include cards the issuer no longer takes applications for.
+  --member <name>         A membership you have, e.g. amazon-prime. Repeatable.
+  --valuation <profile>   flat (points at 1¢, the default) or points-heavy
+                          (MR and UR at 1.7¢).`;
+export const BEST_HELP = `Usage: ${CLI_NAME} best <merchant or category> [amount] [options]
+
+Ranks every card in earnrate's catalog for one purchase, not just yours. Each
+card is set up at its best: the right category pick, activated, cap unused.
+
+Examples:
+  ${CLI_NAME} best groceries
+  ${CLI_NAME} best amazon 120 --member amazon-prime
+  ${CLI_NAME} best dining --no-fee
+
+Options:
+${FILTER_OPTIONS}
+  --online, --in-store    How you're paying. Default: inferred from the merchant.
+  --date <YYYY-MM-DD>     Purchase date. Default: today.
+  --all                   List every card, not just the top 10.
+  --json                  Print the full result as JSON.
+  -h, --help              Show this help.
+`;
+export const SIMULATE_HELP = `Usage: ${CLI_NAME} simulate <what>=<dollars a month>... [options]
+
+Spends this much every month for a year and ranks the cards, and the
+two-card pairs, that earn the most after annual fees. Each <what> is a
+category (groceries, dining, gas, travel, streaming, other) or a merchant
+(amazon, costco).
+
+Examples:
+  ${CLI_NAME} simulate groceries=600 dining=300 gas=150 other=1000
+  ${CLI_NAME} simulate groceries=600 amazon=150 other=800 --wallet
+
+Options:
+  --wallet                Start from your wallet and rank the cards that would
+                          add the most to it, after their fee.
+${FILTER_OPTIONS}
+  --start <YYYY-MM-DD>    First month of the year simulated. Default: today.
+  --all                   List more results.
+  --json                  Print the full result as JSON.
+  -h, --help              Show this help.
+`;
+const FILTER_FLAGS = {
+    cash: { type: 'boolean' },
+    points: { type: 'boolean' },
+    'no-fee': { type: 'boolean' },
+    issuer: { type: 'string' },
+    business: { type: 'boolean' },
+    closed: { type: 'boolean' },
+    member: { type: 'string', multiple: true },
+    valuation: { type: 'string' },
+    all: { type: 'boolean' },
+    json: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+};
+function settingsFrom(values, catalog) {
+    if (values.cash && values.points)
+        return 'Pick --cash or --points, not both.';
+    if (values.valuation !== undefined && !isValuationProfile(values.valuation))
+        return `Unknown valuation "${values.valuation}". Use flat or points-heavy.`;
+    const issuers = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
+    if (values.issuer !== undefined && !issuers.includes(values.issuer))
+        return `Unknown issuer "${values.issuer}". Use one of: ${issuers.join(', ')}.`;
+    const known = knownMemberships(catalog);
+    const unknown = (values.member ?? []).filter((m) => !known.includes(m));
+    if (unknown.length > 0)
+        return `Unknown membership "${unknown.join('", "')}". Use one of: ${known.join(', ')}.`;
+    return {
+        filters: {
+            ...ALL_PERSONAL_CARDS,
+            kind: values.cash ? 'cash' : values.points ? 'points' : 'any',
+            business: values.business ?? false,
+            noAnnualFee: values['no-fee'] ?? false,
+            issuer: values.issuer ?? null,
+            includeClosed: values.closed ?? false,
+        },
+        memberships: values.member ?? [],
+        valuations: values.valuation !== undefined && isValuationProfile(values.valuation)
+            ? VALUATION_PROFILES[values.valuation]
+            : {},
+    };
+}
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+const wholeUsd = (n) => usd(Math.round(n));
+const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
+function feeText(e) {
+    if (e.annualFee === null)
+        return 'annual fee not on file';
+    if (e.annualFee === 0)
+        return 'no annual fee';
+    if (e.firstYearFee !== null && e.firstYearFee !== e.annualFee)
+        return `${usd(e.annualFee)} annual fee (${e.firstYearFee === 0 ? 'waived' : usd(e.firstYearFee)} the first year)`;
+    return `${usd(e.annualFee)} annual fee`;
+}
+const TOP_BEST = 10;
+export function formatExploration(r, all) {
+    const m = r.merchant;
+    const title = m.source === 'caller'
+        ? 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 ? '' : `  ${usd(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`;
+}
+export async function runBest(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                ...FILTER_FLAGS,
+                online: { type: 'boolean' },
+                'in-store': { type: 'boolean' },
+                date: { type: 'string' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${BEST_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(BEST_HELP);
+        return 0;
+    }
+    const words = [...positionals];
+    const last = words.at(-1);
+    const amount = words.length > 1 && last !== undefined && /^\$?\d+(\.\d+)?$/.test(last)
+        ? Number(last.replace('$', ''))
+        : null;
+    if (amount !== null)
+        words.pop();
+    const text = words.join(' ').trim();
+    if (text === '') {
+        io.stderr(`Say what you're buying, e.g. ${CLI_NAME} best groceries.\n`);
+        return USAGE_ERROR;
+    }
+    if (values.online && values['in-store']) {
+        io.stderr('Pick --online or --in-store, not both.\n');
+        return USAGE_ERROR;
+    }
+    const catalog = await loadCatalog();
+    const settings = settingsFrom(values, catalog);
+    if (typeof settings === 'string') {
+        io.stderr(`${settings}\n`);
+        return USAGE_ERROR;
+    }
+    const category = findCategory(catalog, text);
+    const result = exploreCards(catalog, {
+        merchant: category === null ? text : null,
+        category,
+        amount,
+        channel: values.online
+            ? 'online'
+            : values['in-store']
+                ? 'in_store'
+                : null,
+        date: values.date ?? io.today,
+    }, settings);
+    io.stdout(values.json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : formatExploration(result, values.all ?? false));
+    return 0;
+}
+export function parseSpend(catalog, args) {
+    const lines = [];
+    for (const arg of args) {
+        const match = /^(.+)=\$?(\d+(?:\.\d+)?)$/.exec(arg);
+        if (!match?.[1] || match[2] === undefined)
+            return `"${arg}" isn't <what>=<dollars a month>, e.g. groceries=600.`;
+        const what = match[1].replace(/[-_]/g, ' ');
+        const category = findCategory(catalog, what);
+        lines.push({
+            merchant: category === null ? what : null,
+            category,
+            monthly: Number(match[2]),
+        });
+    }
+    if (lines.length === 0)
+        return `Give your monthly spending, e.g. ${CLI_NAME} simulate groceries=600 dining=300 other=1000.`;
+    return lines;
+}
+export async function runSimulate(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                ...FILTER_FLAGS,
+                wallet: { type: 'boolean' },
+                start: { type: 'string' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${SIMULATE_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(SIMULATE_HELP);
+        return 0;
+    }
+    const catalog = await loadCatalog();
+    const settings = settingsFrom(values, catalog);
+    if (typeof settings === 'string') {
+        io.stderr(`${settings}\n`);
+        return USAGE_ERROR;
+    }
+    const spend = parseSpend(catalog, positionals);
+    if (typeof spend === 'string') {
+        io.stderr(`${spend}\n`);
+        return USAGE_ERROR;
+    }
+    const lines = resolveSpendLines(catalog, spend);
+    const unknown = lines.filter((l) => l.merchant.source === 'none');
+    if (unknown.length > 0) {
+        io.stderr(`Not a category or a merchant earnrate knows: ${unknown.map((l) => `"${l.merchant.input}"`).join(', ')}. Categories include groceries, dining, gas, travel, streaming and other.\n`);
+        return USAGE_ERROR;
+    }
+    const options = { ...settings, start: values.start ?? io.today };
+    if (values.wallet) {
+        const file = walletPath(io.env);
+        const wallet = await readWallet(file, io);
+        if (!wallet)
+            return RUNTIME_ERROR;
+        const problems = walletProblems(wallet, catalog);
+        if (problems.length > 0) {
+            io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+            return RUNTIME_ERROR;
+        }
+        const valued = values.valuation !== undefined && isValuationProfile(values.valuation)
+            ? withValuationProfile(wallet, values.valuation)
+            : wallet;
+        const result = simulateAdditions(catalog, valued, lines, options);
+        io.stdout(values.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : formatAdditions(result, catalog, values.all ?? false));
+        return 0;
+    }
+    const result = simulateCatalog(catalog, lines, options);
+    io.stdout(values.json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : formatCatalogSimulation(result, catalog, values.all ?? false));
+    return 0;
+}

package/dist/cli/run.js

@@ -12,6 +12,8 @@ import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { packageVersion } from "../version.js";
 import { parseCliArgs } from "./args.js";
+import { runCheatSheet } from "./cheatsheet.js";
+import { runBest, runSimulate } from "./explore.js";
 import { runImport } from "./import.js";
 import { runOffers } from "./offers.js";
 import { runWalletCommand, WALLET_HELP } from "./wallet.js";
@@ -25,6 +27,10 @@ Examples:
   ${CLI_NAME} costco --in-store
   ${CLI_NAME} delta.com 450 --valuation points-heavy
 
+Compare every card, no wallet needed:
+  ${CLI_NAME} best <merchant or category>          Rank all cards for one purchase.
+  ${CLI_NAME} simulate groceries=600 dining=300    Best cards and pairs for a year of spending.
+
 Set up your wallet:
   ${CLI_NAME} cards [search words]                 Find cards and their ids.
   ${CLI_NAME} add <card-id> [--pick ...]           Add a card you hold.
@@ -33,6 +39,7 @@ Set up your wallet:
   ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime).
 
 Other commands:
+  ${CLI_NAME} cheatsheet                           Your best card for each category this quarter.
   ${CLI_NAME} import <statement.csv> --card <id>   Replay a statement against your wallet.
   ${CLI_NAME} offers [--cash | --points]           Rank welcome offers on cards you don't have.
   ${CLI_NAME} mcp                                  Run the MCP server over stdio, for AI agents.
@@ -87,6 +94,12 @@ export async function run(argv, io) {
         return runImport(argv.slice(1), io);
     if (argv[0] === 'offers')
         return runOffers(argv.slice(1), io);
+    if (argv[0] === 'best')
+        return runBest(argv.slice(1), io);
+    if (argv[0] === 'cheatsheet')
+        return runCheatSheet(argv.slice(1), io);
+    if (argv[0] === 'simulate')
+        return runSimulate(argv.slice(1), io);
     const command = argv[0];
     if (command !== undefined && Object.hasOwn(WALLET_HELP, command)) {
         return runWalletCommand(command, argv.slice(1), io);

package/dist/data/wallet-setup.js

@@ -1,107 +1,6 @@
-import { periodKey } from "../engine/periods.js";
-import { knownMemberships, searchCards, setupNotes, } from "../engine/setup.js";
-import { WalletCardSchema, WalletSchema, } from "../schema/wallet.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
 import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, updateCardText, } from "./wallet-edit.js";
 const failed = (error) => ({ ok: false, error });
-const list = (ids) => ids.join(', ');
-function findCatalogCard(catalog, id, today) {
-    const card = catalog.cards.find((c) => c.id === id);
-    if (card)
-        return card;
-    const near = searchCards(catalog, id, null, today).cards.map((c) => c.id);
-    return near.length > 0
-        ? `No card '${id}' in earnrate. Closest: ${list(near)}.`
-        : `No card '${id}' in earnrate. Search the catalog to find its id.`;
-}
-function isAnniversary(text) {
-    const m = /^(\d{2})-(\d{2})$/.exec(text);
-    if (!m)
-        return false;
-    const date = new Date(`2024-${text}T00:00:00Z`); // a leap year allows 02-29
-    return (!Number.isNaN(date.getTime()) && date.toISOString().slice(5, 10) === text);
-}
-// The period key picks are filed under: the card's choice period, or for
-// picks that carry over, the current year (it's never compared).
-function choicePeriod(card, today) {
-    const periods = [
-        ...new Set(card.choices.map((c) => c.period).filter((p) => p !== 'until_changed')),
-    ];
-    if (periods.length > 1)
-        return null;
-    return periodKey(periods[0] ?? 'calendar_year', today, null);
-}
-function fieldsFor(card, held, input, today) {
-    const problems = [];
-    const fields = {};
-    if (input.checkoutLabel !== undefined) {
-        if (input.checkoutLabel.trim() === '')
-            problems.push('The checkout label is empty.');
-        // earnrate never stores card numbers; a last four is fine.
-        if (/\d{8,}/.test(input.checkoutLabel.replace(/[\s-]/g, '')))
-            problems.push('The checkout label looks like it has a card number in it. earnrate never stores card numbers; use a name like "Amex Gold".');
-        fields.checkout_label = input.checkoutLabel.trim();
-    }
-    if (input.anniversary !== undefined) {
-        if (!isAnniversary(input.anniversary)) {
-            problems.push(`"${input.anniversary}" isn't an anniversary. Use MM-DD, like 03-15.`);
-        }
-        fields.anniversary = input.anniversary;
-    }
-    if (input.activated !== undefined) {
-        const needing = card.rules
-            .filter((r) => r.requires?.activation)
-            .map((r) => r.id);
-        for (const id of input.activated) {
-            if (!needing.includes(id)) {
-                problems.push(needing.length > 0
-                    ? `'${id}' isn't a ${card.id} rule that needs activating. Those are: ${list(needing)}.`
-                    : `${card.id} has no rules that need activating.`);
-            }
-        }
-        fields.activated = [...new Set(input.activated)];
-    }
-    if (input.picks !== undefined) {
-        for (const [choiceId, picks] of Object.entries(input.picks)) {
-            const choice = card.choices.find((c) => c.id === choiceId);
-            if (!choice) {
-                problems.push(card.choices.length > 0
-                    ? `${card.id} has no '${choiceId}' pick. Its picks are: ${list(card.choices.map((c) => c.id))}.`
-                    : `${card.id} has no categories to pick.`);
-                continue;
-            }
-            const options = Object.keys(choice.options);
-            for (const p of picks) {
-                if (!options.includes(p)) {
-                    problems.push(`'${p}' isn't a ${choiceId} option for ${card.id}. Options: ${list(options)}.`);
-                }
-            }
-            if (picks.length === 0 || picks.length > choice.pick) {
-                problems.push(`${choiceId} takes ${choice.pick === 1 ? '1 pick' : `1 to ${String(choice.pick)} picks`}, not ${String(picks.length)}.`);
-            }
-        }
-        const period = choicePeriod(card, today);
-        if (period === null) {
-            problems.push(`${card.id} has picks on different schedules; edit the wallet by hand.`);
-        }
-        else {
-            const kept = held?.chosen?.period === period ? held.chosen.picks : {};
-            fields.chosen = {
-                period,
-                picks: { ...kept, ...input.picks },
-            };
-        }
-    }
-    return problems.length > 0 ? problems.join('\n') : fields;
-}
-const applyFields = (held, f) => WalletCardSchema.parse({
-    ...held,
-    ...(f.checkout_label === undefined
-        ? {}
-        : { checkout_label: f.checkout_label }),
-    ...(f.anniversary === undefined ? {} : { anniversary: f.anniversary }),
-    ...(f.chosen === undefined ? {} : { chosen: f.chosen }),
-    ...(f.activated === undefined ? {} : { activated: f.activated }),
-});
 async function attempt(task) {
     try {
         return await task();
@@ -111,29 +10,19 @@ async function attempt(task) {
     }
 }
 const noWallet = (file) => `No wallet at ${file} yet. Add a card first to create it.`;
+// The change is worked out on the parsed wallet, then spliced into the file
+// text, which must re-parse to exactly that wallet before it's written.
+async function commit(file, edited, change, created) {
+    await commitWalletText(file, edited, change.wallet);
+    return { ok: true, wallet: change.wallet, created, notes: change.notes };
+}
 export function addCard(file, catalog, input, today) {
     return attempt(async () => {
-        const card = findCatalogCard(catalog, input.id, today);
-        if (typeof card === 'string')
-            return failed(card);
         const { text, wallet } = await readWalletText(file);
-        if (wallet?.cards.some((c) => c.id === card.id)) {
-            return failed(`${card.id} is already in the wallet. Update it instead.`);
-        }
-        const fields = fieldsFor(card, null, input, today);
-        if (typeof fields === 'string')
-            return failed(fields);
-        const held = applyFields(WalletCardSchema.parse({ id: card.id }), fields);
-        const expected = wallet
-            ? { ...wallet, cards: [...wallet.cards, held] }
-            : WalletSchema.parse({ cards: [held] });
-        await commitWalletText(file, addCardText(text, { id: card.id, ...fields }), expected);
-        return {
-            ok: true,
-            wallet: expected,
-            created: text === null,
-            notes: setupNotes(catalog, expected, held, today),
-        };
+        const change = addToWallet(catalog, wallet, input, today);
+        if (!change.ok)
+            return change;
+        return commit(file, addCardText(text, { id: input.id, ...change.fields }), change, text === null);
     });
 }
 export function updateCard(file, catalog, input, today) {
@@ -141,28 +30,10 @@ export function updateCard(file, catalog, input, today) {
         const { text, wallet } = await readWalletText(file);
         if (text === null || wallet === null)
             return failed(noWallet(file));
-        const held = wallet.cards.find((c) => c.id === input.id);
-        const card = catalog.cards.find((c) => c.id === input.id);
-        if (!held || !card) {
-            return failed(`${input.id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
-        }
-        const fields = fieldsFor(card, held, input, today);
-        if (typeof fields === 'string')
-            return failed(fields);
-        if (Object.keys(fields).length === 0)
-            return failed('Nothing to change.');
-        const updated = applyFields(held, fields);
-        const expected = {
-            ...wallet,
-            cards: wallet.cards.map((c) => (c.id === held.id ? updated : c)),
-        };
-        await commitWalletText(file, updateCardText(text, held.id, fields), expected);
-        return {
-            ok: true,
-            wallet: expected,
-            created: false,
-            notes: setupNotes(catalog, expected, updated, today),
-        };
+        const change = updateInWallet(catalog, wallet, input, today);
+        if (!change.ok)
+            return change;
+        return commit(file, updateCardText(text, input.id, change.fields), change, false);
     });
 }
 export function removeCard(file, _catalog, id) {
@@ -170,33 +41,20 @@ export function removeCard(file, _catalog, id) {
         const { text, wallet } = await readWalletText(file);
         if (text === null || wallet === null)
             return failed(noWallet(file));
-        if (!wallet.cards.some((c) => c.id === id)) {
-            return failed(`${id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
-        }
-        if (wallet.cards.length === 1) {
-            return failed(`${id} is the last card in the wallet, and a wallet needs one. Add the new card first, then remove this one.`);
-        }
-        const expected = {
-            ...wallet,
-            cards: wallet.cards.filter((c) => c.id !== id),
-        };
-        await commitWalletText(file, removeCardText(text, id), expected);
-        return { ok: true, wallet: expected, created: false, notes: [] };
+        const change = removeFromWallet(wallet, id);
+        if (!change.ok)
+            return change;
+        return commit(file, removeCardText(text, id), change, false);
     });
 }
 export function setMemberships(file, catalog, memberships) {
     return attempt(async () => {
-        const known = knownMemberships(catalog);
-        const unknown = memberships.filter((m) => !known.includes(m));
-        if (unknown.length > 0) {
-            return failed(`No card rule uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
-        }
         const { text, wallet } = await readWalletText(file);
         if (text === null || wallet === null)
             return failed(noWallet(file));
-        const unique = [...new Set(memberships)];
-        const expected = { ...wallet, memberships: unique };
-        await commitWalletText(file, setMembershipsText(text, unique), expected);
-        return { ok: true, wallet: expected, created: false, notes: [] };
+        const change = withMemberships(catalog, wallet, memberships);
+        if (!change.ok)
+            return change;
+        return commit(file, setMembershipsText(text, change.wallet.memberships), change, false);
     });
 }

package/dist/engine/cheat-sheet.js

@@ -0,0 +1,48 @@
+import { resolveMerchantById } from "../merchants/resolve.js";
+import { categoryResolution } from "./explore.js";
+import { periodKey } from "./periods.js";
+import { recommend } from "./recommend.js";
+import { setupNotes } from "./setup.js";
+export const CHEAT_SHEET_ITEMS = [
+    { label: 'Groceries', category: 'grocery.supermarket' },
+    { label: 'Dining', category: 'dining' },
+    { label: 'Gas', category: 'gas' },
+    { label: 'Amazon', merchant: 'amazon' },
+    { label: 'Costco', merchant: 'costco' },
+    { label: 'Travel', category: 'travel' },
+    { label: 'Streaming', category: 'streaming' },
+    { label: 'Drugstores', category: 'drugstore' },
+    { label: 'Everything else', category: 'other' },
+];
+// The best card in the wallet for each everyday kind of purchase on `date`,
+// with caps, picks and activations as the wallet has them.
+export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
+    const rows = items.map((item) => {
+        const merchant = 'merchant' in item
+            ? resolveMerchantById(catalog, item.merchant, null)
+            : categoryResolution(catalog, item.category, null);
+        if (!merchant)
+            throw new Error(`unknown merchant '${item.label}'`);
+        const rec = recommend(catalog, wallet, {
+            merchant: merchant.input,
+            amount: null,
+            channel: null,
+            date,
+            country: 'US',
+        }, merchant);
+        const top = rec.ranked.find((r) => r.cardId === rec.decision?.cardId);
+        return {
+            label: item.label,
+            cardId: top?.cardId ?? null,
+            cardName: top ? (top.checkoutLabel ?? top.cardName) : null,
+            effectiveReturnPct: top?.effectiveReturnPct ?? null,
+            matchedRule: top?.matchedRule ?? null,
+            note: top?.warnings[0] ?? null,
+        };
+    });
+    const notes = [
+        ...new Set(wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text))),
+    ];
+    const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
+    return { quarter: `${q ?? ''} ${year ?? ''}`, date, rows, notes };
+}