earnrate 0.1.4 → 0.2.1

package/dist/cli/wallet.js

@@ -1,9 +1,9 @@
 import { parseArgs } from 'node:util';
 import { CLI_NAME } from "../brand.js";
+import { FileWalletStore } from "../data/file-store.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
-import { addCard, removeCard, setMemberships, updateCard, } from "../data/wallet-setup.js";
 import { knownMemberships, searchCards } from "../engine/setup.js";
-import { formatCardInfo, formatNotes } from "./cards.js";
+import { formatCardInfo, formatNotes } from "../format/cards.js";
 import { displayPath, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
 const CARD_OPTIONS = `Options:
   --label <text>             How the card appears at checkout, e.g. "Amex Gold".
@@ -13,6 +13,13 @@ const CARD_OPTIONS = `Options:
   --anniversary <MM-DD>      Account anniversary, for caps that reset on it.
   --activated <rules>        Rules you've activated with the issuer, comma
                              separated. Replaces the current list.
+  --bonus-opened <date>      Track a welcome bonus: the day the account opened
+                             (YYYY-MM-DD). Spending needed and the deadline
+                             default to the card's published offer.
+  --bonus-spent <dollars>    Spending toward it so far. Default 0.
+  --bonus-spend <dollars>    The spending needed, if your offer differs.
+  --bonus-by <date>          The deadline, if your offer differs.
+  --no-bonus                 Stop tracking the welcome bonus.
   -h, --help                 Show this help.`;
 export const WALLET_HELP = {
     cards: `Usage: ${CLI_NAME} cards [search words]
@@ -105,6 +112,11 @@ export async function runWalletCommand(command, argv, io) {
                 pick: { type: 'string', multiple: true },
                 anniversary: { type: 'string' },
                 activated: { type: 'string' },
+                'bonus-opened': { type: 'string' },
+                'bonus-spent': { type: 'string' },
+                'bonus-spend': { type: 'string' },
+                'bonus-by': { type: 'string' },
+                'no-bonus': { type: 'boolean' },
                 none: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
             },
@@ -136,6 +148,7 @@ export async function runWalletCommand(command, argv, io) {
     const catalog = await loadCatalog();
     const file = walletPath(io.env);
     const where = displayPath(file);
+    const store = new FileWalletStore(catalog, file);
     if (command === 'cards') {
         const query = positionals.join(' ');
         const result = searchCards(catalog, query, await heldWallet(io), io.today);
@@ -157,7 +170,7 @@ export async function runWalletCommand(command, argv, io) {
             return usage('Give memberships or --none, not both.');
         }
         const list = values.none ? [] : positionals;
-        return report(await setMemberships(file, catalog, list), list.length > 0
+        return report(await store.setMemberships(list), list.length > 0
             ? `Memberships set to ${list.join(', ')} in ${where}.`
             : `Memberships cleared in ${where}.`, null, io);
     }
@@ -167,7 +180,7 @@ export async function runWalletCommand(command, argv, io) {
     const id = positionals[0] ?? '';
     const name = catalog.cards.find((c) => c.id === id)?.name ?? id;
     if (command === 'remove') {
-        return report(await removeCard(file, catalog, id), `Removed ${name} from ${where}.`, null, io);
+        return report(await store.removeCard(id), `Removed ${name} from ${where}.`, null, io);
     }
     const input = { id };
     if (values.label !== undefined)
@@ -186,9 +199,37 @@ export async function runWalletCommand(command, argv, io) {
             return usage(picks);
         input.picks = picks;
     }
+    const dollarsFlag = (flag, text) => {
+        if (text === undefined)
+            return undefined;
+        const n = Number(text.replace(/[$,]/g, ''));
+        return Number.isFinite(n) ? n : `--${flag} takes dollars, like 1200.`;
+    };
+    if (values['no-bonus']) {
+        input.bonus = null;
+    }
+    else if (values['bonus-opened'] !== undefined) {
+        const spent = dollarsFlag('bonus-spent', values['bonus-spent']);
+        const spend = dollarsFlag('bonus-spend', values['bonus-spend']);
+        if (typeof spent === 'string')
+            return usage(spent);
+        if (typeof spend === 'string')
+            return usage(spend);
+        input.bonus = {
+            opened: values['bonus-opened'],
+            ...(spent === undefined ? {} : { spent }),
+            ...(spend === undefined ? {} : { spend }),
+            ...(values['bonus-by'] === undefined ? {} : { by: values['bonus-by'] }),
+        };
+    }
+    else if (values['bonus-spent'] !== undefined ||
+        values['bonus-spend'] !== undefined ||
+        values['bonus-by'] !== undefined) {
+        return usage('Give --bonus-opened with the other --bonus options.');
+    }
     if (command === 'add') {
-        const result = await addCard(file, catalog, input, io.today);
+        const result = await store.addCard(input, io.today);
         return report(result, `Added ${name} to ${where}${result.ok && result.created ? ' (a new wallet)' : ''}.`, id, io);
     }
-    return report(await updateCard(file, catalog, input, io.today), `Updated ${name} in ${where}.`, id, io);
+    return report(await store.updateCard(input, io.today), `Updated ${name} in ${where}.`, id, io);
 }

package/dist/data/file-store.js

@@ -0,0 +1,95 @@
+import { bookPurchase } from "../engine/record.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
+import { loadWallet } from "./load.js";
+import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, updateCardText, writeProgress, } from "./wallet-edit.js";
+const failed = (error) => ({ ok: false, error });
+const errorText = (e) => (e instanceof Error ? e.message : String(e));
+const queues = new Map();
+// Runs `task` after every earlier task for the same file has settled, so a
+// read-modify-write of the wallet never interleaves with another.
+function withWalletLock(file, task) {
+    const previous = queues.get(file) ?? Promise.resolve();
+    const run = previous.then(task, task);
+    queues.set(file, run.catch(() => undefined));
+    return run;
+}
+// The wallet as a YAML file (the CLI, the local MCP server and the .mcpb).
+// Each change is worked out on the parsed wallet, then spliced into the text,
+// which must re-parse to exactly that wallet before it's written, so the
+// user's comments survive.
+export class FileWalletStore {
+    where;
+    catalog;
+    constructor(catalog, file) {
+        this.catalog = catalog;
+        this.where = file;
+    }
+    async load() {
+        try {
+            return await loadWallet(this.where);
+        }
+        catch (e) {
+            if (e instanceof Error && 'code' in e && e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    }
+    change(plan, edit) {
+        return withWalletLock(this.where, async () => {
+            try {
+                const { text, wallet } = await readWalletText(this.where);
+                const change = plan(wallet);
+                if (typeof change === 'string')
+                    return failed(change);
+                if (!change.ok)
+                    return change;
+                await commitWalletText(this.where, edit(text, change), change.wallet);
+                return {
+                    ok: true,
+                    wallet: change.wallet,
+                    created: text === null,
+                    notes: change.notes,
+                };
+            }
+            catch (e) {
+                return failed(errorText(e));
+            }
+        });
+    }
+    // Changes other than adding a card need a wallet file to change.
+    existing(apply) {
+        return (wallet) => wallet === null
+            ? `No wallet at ${this.where} yet. Add a card first to create it.`
+            : apply(wallet);
+    }
+    addCard(input, today) {
+        return this.change((wallet) => addToWallet(this.catalog, wallet, input, today), (text, change) => addCardText(text, { id: input.id, ...change.fields }));
+    }
+    updateCard(input, today) {
+        return this.change(this.existing((w) => updateInWallet(this.catalog, w, input, today)), (text, change) => updateCardText(text ?? '', input.id, change.fields));
+    }
+    removeCard(cardId) {
+        return this.change(this.existing((w) => removeFromWallet(w, cardId)), (text) => removeCardText(text ?? '', cardId));
+    }
+    setMemberships(memberships) {
+        return this.change(this.existing((w) => withMemberships(this.catalog, w, memberships)), (text, change) => setMembershipsText(text ?? '', change.wallet.memberships));
+    }
+    record(purchase, merchant) {
+        return withWalletLock(this.where, async () => {
+            const wallet = await this.load();
+            if (!wallet)
+                return failed("There's no saved wallet to record it in.");
+            if (!wallet.cards.some((c) => c.id === purchase.cardId))
+                return failed(`${purchase.cardId} isn't in the wallet.`);
+            const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
+            try {
+                if (booked.cap || booked.bonus)
+                    await writeProgress(this.where, booked.cap ? [booked.cap] : [], booked.bonus ? [booked.bonus] : []);
+            }
+            catch (e) {
+                return failed(errorText(e));
+            }
+            return { ok: true, ...booked };
+        });
+    }
+}

package/dist/data/load.js

@@ -11,7 +11,7 @@ import { CurrenciesFileSchema } from "../schema/currency.js";
 import { MerchantsFileSchema } from "../schema/merchant.js";
 import { WalletSchema } from "../schema/wallet.js";
 export const DATA_DIR = fileURLToPath(new URL('../../data/', import.meta.url));
-export async function readYaml(file, schema) {
+async function readYaml(file, schema) {
     const raw = parse(await readFile(file, 'utf8'));
     const result = schema.safeParse(raw);
     if (!result.success) {
@@ -39,8 +39,16 @@ export async function loadCatalog(dir = DATA_DIR) {
     ]);
     return { categories, currencies, cards, merchants: { seed, overrides } };
 }
+// MCP clients pass config values through without a shell, so "~" or
+// "${HOME}" can arrive as literal text; expand them here.
 export function walletPath(env = process.env) {
-    return env[WALLET_ENV_VAR] ?? path.join(homedir(), CONFIG_DIR, 'wallet.yaml');
+    const given = env[WALLET_ENV_VAR]?.trim();
+    if (!given)
+        return path.join(homedir(), CONFIG_DIR, 'wallet.yaml');
+    const expanded = given
+        .replace(/^~(?=$|[/\\])/, homedir())
+        .replace(/\$\{HOME\}|\$HOME\b/g, homedir());
+    return path.resolve(expanded);
 }
 export function loadWallet(file = walletPath()) {
     return readYaml(file, WalletSchema);

package/dist/data/store.js

@@ -0,0 +1,92 @@
+import { bookPurchase } from "../engine/record.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
+import { WalletSchema } from "../schema/wallet.js";
+const failed = (error) => ({ ok: false, error });
+// A wallet stored as JSON text. Writes are serialized within this instance;
+// a backend shared across processes must serialize them itself (one Durable
+// Object per wallet does).
+export class JsonWalletStore {
+    where;
+    catalog;
+    backend;
+    queue = Promise.resolve();
+    constructor(catalog, backend, where) {
+        this.catalog = catalog;
+        this.backend = backend;
+        this.where = where;
+    }
+    async load() {
+        const text = await this.backend.read();
+        return text === null ? null : WalletSchema.parse(JSON.parse(text));
+    }
+    serialized(task) {
+        const run = this.queue.then(task, task);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    change(apply) {
+        return this.serialized(async () => {
+            const before = await this.load();
+            const change = apply(before);
+            if (!change.ok)
+                return failed(change.error);
+            await this.backend.write(JSON.stringify(change.wallet));
+            return {
+                ok: true,
+                wallet: change.wallet,
+                created: before === null,
+                notes: change.notes,
+            };
+        });
+    }
+    needsWallet(apply) {
+        return (wallet) => wallet === null
+            ? failed("There's no saved wallet yet. Add a card first to start one.")
+            : apply(wallet);
+    }
+    addCard(input, today) {
+        return this.change((w) => addToWallet(this.catalog, w, input, today));
+    }
+    updateCard(input, today) {
+        return this.change(this.needsWallet((w) => updateInWallet(this.catalog, w, input, today)));
+    }
+    removeCard(cardId) {
+        return this.change(this.needsWallet((w) => removeFromWallet(w, cardId)));
+    }
+    setMemberships(memberships) {
+        return this.change(this.needsWallet((w) => withMemberships(this.catalog, w, memberships)));
+    }
+    replace(wallet) {
+        return this.change(() => ({ ok: true, wallet, fields: {}, notes: [] }));
+    }
+    erase() {
+        return this.serialized(() => this.backend.remove());
+    }
+    record(purchase, merchant) {
+        return this.serialized(async () => {
+            const wallet = await this.load();
+            if (!wallet)
+                return failed("There's no saved wallet to record it in.");
+            if (!wallet.cards.some((c) => c.id === purchase.cardId))
+                return failed(`${purchase.cardId} isn't in the wallet.`);
+            const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
+            if (booked.cap || booked.bonus)
+                await this.backend.write(JSON.stringify(booked.wallet));
+            return { ok: true, ...booked };
+        });
+    }
+}
+export function memoryBackend(initial = null) {
+    let text = initial;
+    return {
+        read: () => Promise.resolve(text),
+        write: (next) => {
+            text = next;
+            return Promise.resolve();
+        },
+        remove: () => {
+            text = null;
+            return Promise.resolve();
+        },
+    };
+}

package/dist/data/wallet-edit.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { isMap, isSeq, parseDocument, stringify } from 'yaml';
+import { applyBonusBooking, applyBooking, } from "../engine/record.js";
 import { WalletSchema } from "../schema/wallet.js";
 const NEW_WALLET = `# Your earnrate wallet: the cards you hold, by id. Never card numbers.
 # Format: https://github.com/cwasley/earnrate#your-wallet
@@ -38,6 +39,18 @@ function fieldLines(field, f, indent) {
             return f.activated === undefined
                 ? ''
                 : `${indent}activated: ${flowList(f.activated)}\n`;
+        case 'bonus': {
+            if (!f.bonus)
+                return '';
+            const b = f.bonus;
+            return [
+                `${indent}bonus:\n`,
+                `${indent}  opened: ${scalar(b.opened)}\n`,
+                `${indent}  spent: ${String(b.spent)}\n`,
+                b.spend === undefined ? '' : `${indent}  spend: ${String(b.spend)}\n`,
+                b.by === undefined ? '' : `${indent}  by: ${scalar(b.by)}\n`,
+            ].join('');
+        }
         case 'chosen': {
             if (f.chosen === undefined)
                 return '';
@@ -48,7 +61,13 @@ function fieldLines(field, f, indent) {
         }
     }
 }
-const FIELDS = ['checkout_label', 'anniversary', 'chosen', 'activated'];
+const FIELDS = [
+    'checkout_label',
+    'anniversary',
+    'chosen',
+    'activated',
+    'bonus',
+];
 function cardsSeq(text) {
     const doc = parseDocument(text);
     if (doc.errors.length > 0)
@@ -105,7 +124,12 @@ export function updateCardText(text, cardId, fields) {
         const indent = ' '.repeat(column(out, range(card)[0]));
         const lines = fieldLines(field, fields, indent);
         const pair = card.items.find((p) => keyOf(p) === field);
-        if (pair) {
+        if (pair && lines === '') {
+            const start = lineStart(out, range(pair.key)[0]);
+            const end = afterLine(out, range(pair.value)[1] - 1);
+            out = out.slice(0, start) + out.slice(end);
+        }
+        else if (pair) {
             const start = range(pair.key)[0];
             const end = afterLine(out, range(pair.value)[1] - 1);
             out = out.slice(0, start) + lines.trimStart() + out.slice(end);
@@ -131,6 +155,71 @@ export function setMembershipsText(text, memberships) {
     const cards = root.items.find((p) => keyOf(p) === 'cards');
     return insertLines(text, lineStart(text, range(cards?.key)[0]), line);
 }
+function flowUsage(booking) {
+    const period = /^\d+$/.test(booking.period)
+        ? `"${booking.period}"`
+        : booking.period;
+    return `{ period: ${period}, spent: ${String(booking.after)} }`;
+}
+export function capUsageText(text, booking) {
+    const card = findCard(text, booking.cardId);
+    const value = flowUsage(booking);
+    const usage = card.get('cap_usage', true);
+    if (isMap(usage) && !usage.flow && usage.items.length > 0) {
+        const existing = usage.items.find((p) => keyOf(p) === booking.capKey);
+        if (existing) {
+            const [start, end] = range(existing.value);
+            return text.slice(0, start) + value + text.slice(end);
+        }
+        const indent = ' '.repeat(column(text, range(usage.items[0]?.key)[0]));
+        const at = afterLine(text, range(usage)[1] - 1);
+        return insertLines(text, at, `${indent}${booking.capKey}: ${value}\n`);
+    }
+    if (usage !== undefined)
+        throw new Error(`card '${booking.cardId}' has a cap_usage that isn't a block map; ${BY_HAND}`);
+    const indent = ' '.repeat(column(text, range(card.items[0]?.key)[0]));
+    const at = afterLine(text, range(card)[1] - 1);
+    return insertLines(text, at, `${indent}cap_usage:\n${indent}  ${booking.capKey}: ${value}\n`);
+}
+export function bonusSpentText(text, cardId, spent) {
+    const bonus = findCard(text, cardId).get('bonus', true);
+    if (!isMap(bonus))
+        throw new Error(`card '${cardId}' has no bonus`);
+    const value = String(spent);
+    const existing = bonus.items.find((p) => keyOf(p) === 'spent');
+    if (existing) {
+        const [start, end] = range(existing.value);
+        return text.slice(0, start) + value + text.slice(end);
+    }
+    if (bonus.flow) {
+        const close = text.lastIndexOf('}', range(bonus)[1]);
+        return `${text.slice(0, close).trimEnd()}, spent: ${value} ${text.slice(close)}`;
+    }
+    const indent = ' '.repeat(column(text, range(bonus.items[0]?.key)[0]));
+    const at = afterLine(text, range(bonus)[1] - 1);
+    return insertLines(text, at, `${indent}spent: ${value}\n`);
+}
+// Writes spending toward caps and welcome bonuses in one checked write.
+export async function writeProgress(file, caps, bonuses) {
+    const { text, wallet } = await readWalletText(file);
+    if (text === null || wallet === null)
+        throw new Error(`No wallet at ${file}.`);
+    let after = text;
+    let expected = wallet;
+    for (const b of caps) {
+        after = capUsageText(after, b);
+        expected = applyBooking(expected, b);
+    }
+    for (const b of bonuses) {
+        after = bonusSpentText(after, b.cardId, b.after);
+        expected = applyBonusBooking(expected, b);
+    }
+    const byHand = [
+        ...caps.map((b) => `${b.cardId} cap_usage ${b.capKey}: ${flowUsage(b)}`),
+        ...bonuses.map((b) => `${b.cardId} bonus spent: ${String(b.after)}`),
+    ].join('; ');
+    await commitWalletText(file, after, expected, `add it by hand: ${byHand}`);
+}
 async function readText(file) {
     try {
         return await readFile(file, 'utf8');
@@ -150,10 +239,10 @@ export async function readWalletText(file) {
 }
 // Writes `after` only if it parses to exactly `expected`, so a splice that
 // went wrong can never change anything it wasn't meant to.
-export async function commitWalletText(file, after, expected) {
+export async function commitWalletText(file, after, expected, fallback = BY_HAND) {
     const parsed = WalletSchema.safeParse(parseDocument(after).toJS());
     if (!parsed.success || !isDeepStrictEqual(parsed.data, expected)) {
-        throw new Error(`couldn't update ${file} safely; ${BY_HAND}`);
+        throw new Error(`couldn't update ${file} safely; ${fallback}`);
     }
     await mkdir(path.dirname(file), { recursive: true });
     const tmp = `${file}.${String(process.pid)}.tmp`;

package/dist/engine/bonus.js

@@ -1,4 +1,5 @@
 import { daysBetween } from "./periods.js";
+import { roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
 // "Within 3 months of opening": the same day of the month, three months on,
 // or the month's last day when that day doesn't exist (Nov 30 + 3 → Feb 28).
@@ -11,7 +12,17 @@ export function addMonths(date, months) {
     const day = Math.min(d, last);
     return `${String(year)}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
 }
-const round = (n) => Math.round(n * 100) / 100;
+// A welcome bonus in dollars at the given point value; null when it has
+// neither points nor dollars.
+export function bonusDollars(card, centsPerUnit, points, dollars) {
+    if (points !== undefined)
+        return (points * centsPerUnit) / 100;
+    if (dollars === undefined)
+        return null;
+    // A cash back card's bonus is paid like its rewards, so it pools when they
+    // do; a points card's dollar bonus is a statement credit.
+    return card.currency === 'cash' ? dollars * centsPerUnit : dollars;
+}
 export function bonusStatus(catalog, wallet, held, today) {
     const bonus = held.bonus;
     if (!bonus)
@@ -25,22 +36,14 @@ export function bonusStatus(catalog, wallet, held, today) {
     const valuation = cardValuation(catalog, wallet, card);
     const points = bonus.points ?? (bonus.dollars === undefined ? offer?.points : undefined);
     const dollars = bonus.dollars ?? (bonus.points === undefined ? offer?.dollars : undefined);
-    let value = null;
-    if (points !== undefined)
-        value = (points * valuation.centsPerUnit) / 100;
-    else if (dollars !== undefined) {
-        // A cash back card's bonus is paid like its rewards, so it pools when they
-        // do; a points card's dollar bonus is a statement credit.
-        value =
-            card.currency === 'cash' ? dollars * valuation.centsPerUnit : dollars;
-    }
+    const value = bonusDollars(card, valuation.centsPerUnit, points, dollars);
     const base = {
         cardId: held.id,
         opened: bonus.opened,
         spent: bonus.spent,
         spend,
         deadline,
-        value: value === null ? null : round(value),
+        value: value === null ? null : roundCents(value),
     };
     if (spend === null || deadline === null) {
         return {
@@ -50,7 +53,7 @@ export function bonusStatus(catalog, wallet, held, today) {
             state: 'incomplete',
         };
     }
-    const remaining = round(Math.max(0, spend - bonus.spent));
+    const remaining = roundCents(Math.max(0, spend - bonus.spent));
     const daysLeft = daysBetween(today, deadline);
     return {
         ...base,

package/dist/engine/cheat-sheet.js

@@ -1,9 +1,9 @@
 import { resolveMerchantById } from "../merchants/resolve.js";
-import { categoryResolution } from "./explore.js";
+import { categoryResolution, exploreCards, } from "./explore.js";
 import { periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { setupNotes } from "./setup.js";
-export const CHEAT_SHEET_ITEMS = [
+const CHEAT_SHEET_ITEMS = [
     { label: 'Groceries', category: 'grocery.supermarket' },
     { label: 'Dining', category: 'dining' },
     { label: 'Gas', category: 'gas' },
@@ -22,7 +22,7 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
             ? resolveMerchantById(catalog, item.merchant, null)
             : categoryResolution(catalog, item.category, null);
         if (!merchant)
-            throw new Error(`unknown merchant '${item.label}'`);
+            throw new Error(`unknown merchant '${'merchant' in item ? item.merchant : item.category}' for ${item.label}`);
         const rec = recommend(catalog, wallet, {
             merchant: merchant.input,
             amount: null,
@@ -44,5 +44,60 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
         ...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 };
+    return {
+        scope: 'wallet',
+        quarter: `${q ?? ''} ${year ?? ''}`,
+        date,
+        rows,
+        notes,
+    };
+}
+// The best card earnrate knows for each everyday kind of purchase, for
+// someone who hasn't named any cards. Each row's note says what the card
+// costs or needs.
+export function catalogCheatSheet(catalog, date, options, items = CHEAT_SHEET_ITEMS) {
+    const rows = items.map((item) => {
+        const top = exploreCards(catalog, 'merchant' in item
+            ? {
+                merchant: catalog.merchants.seed.find((m) => m.id === item.merchant)
+                    ?.name ??
+                    catalog.merchants.overrides.find((m) => m.id === item.merchant)
+                        ?.name ??
+                    item.label,
+                category: null,
+                amount: null,
+                channel: null,
+                date,
+            }
+            : {
+                merchant: null,
+                category: item.category,
+                amount: null,
+                channel: null,
+                date,
+            }, options).ranked[0];
+        const fee = top?.annualFee === null || top?.annualFee === undefined
+            ? null
+            : top.annualFee === 0
+                ? 'No annual fee.'
+                : `$${String(top.annualFee)} annual fee.`;
+        return {
+            label: item.label,
+            cardId: top?.cardId ?? null,
+            cardName: top?.cardName ?? null,
+            effectiveReturnPct: top?.effectiveReturnPct ?? null,
+            matchedRule: top?.matchedRule ?? null,
+            note: top
+                ? [fee, ...top.conditions].filter((n) => n !== null).join(' ')
+                : null,
+        };
+    });
+    const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
+    return {
+        scope: 'all cards',
+        quarter: `${q ?? ''} ${year ?? ''}`,
+        date,
+        rows,
+        notes: [],
+    };
 }

package/dist/engine/evaluate.js

@@ -15,10 +15,19 @@ export function purchaseContext(catalog, wallet, merchant, category, purchase) {
 }
 // A category with one typical MCC (travel agencies are 4722) implies it, the
 // same assumption explanations state.
-function singleMcc(catalog, category) {
+export function singleMcc(catalog, category) {
     const mccs = catalog.categories.find((c) => c.id === category)?.mccs ?? [];
     return mccs.length === 1 ? (mccs[0] ?? null) : null;
 }
+// A store card works only at its own stores; any other card wherever the
+// merchant takes its network, which counts as yes when unknown.
+export function usableAt(card, merchant) {
+    if (card.only_at)
+        return (merchant.merchantId !== null && card.only_at.includes(merchant.merchantId));
+    return (card.network === 'store' ||
+        merchant.accepts === null ||
+        merchant.accepts.includes(card.network));
+}
 export function categoryMatches(ruleCategory, category) {
     return category === ruleCategory || category.startsWith(`${ruleCategory}.`);
 }
@@ -93,20 +102,35 @@ function applicability(rule, ctx, held, picked) {
         return 'needs-activation';
     return 'applies';
 }
+// A cap's key in the wallet's cap_usage: the shared cap's id, or the rule's
+// id for a cap written on the rule.
+export function capByKey(card, key) {
+    const shared = card.caps.find((c) => c.id === key);
+    if (shared)
+        return shared;
+    const inline = card.rules.find((r) => r.id === key)?.cap;
+    return typeof inline === 'object' ? inline : undefined;
+}
+// How much of a cap has been spent in the period `date` falls in.
+export function capUsed(cap, key, held, date) {
+    const period = periodKey(cap.period, date, held.anniversary ?? null);
+    const usage = held.cap_usage[key];
+    return {
+        period,
+        spent: period !== null && usage?.period === period ? usage.spent : 0,
+    };
+}
 function capState(rule, card, held, date) {
     if (rule.cap === undefined)
         return null;
-    const capId = typeof rule.cap === 'string' ? rule.cap : null;
-    const cap = capId === null ? rule.cap : card.caps.find((c) => c.id === capId);
-    if (cap === undefined || typeof cap === 'string')
+    const key = typeof rule.cap === 'string' ? rule.cap : rule.id;
+    const cap = capByKey(card, key);
+    if (cap === undefined)
         return null;
-    const key = capId ?? rule.id;
-    const period = periodKey(cap.period, date, held.anniversary ?? null);
-    const usage = held.cap_usage[key];
-    const used = period !== null && usage?.period === period ? usage.spent : 0;
-    return { key, cap, period, remaining: Math.max(0, cap.amount - used) };
+    const { period, spent } = capUsed(cap, key, held, date);
+    return { key, cap, period, remaining: Math.max(0, cap.amount - spent) };
 }
-export function rateAfterCap(rate, cap, amount) {
+function rateAfterCap(rate, cap, amount) {
     if (!cap)
         return rate;
     if (amount !== null && amount > 0) {