earnrate 0.2.0 → 0.2.2

package/dist/data/store.js

@@ -76,8 +76,6 @@ export class JsonWalletStore {
         });
     }
 }
-// A store with nothing behind it, for tests and for a session that starts
-// empty and is thrown away.
 export function memoryBackend(initial = null) {
     let text = initial;
     return {
@@ -92,17 +90,3 @@ export function memoryBackend(initial = null) {
         },
     };
 }
-// No saved wallet, and saving refused: the public remote server before
-// anonymous saved wallets exist. Cards named in the conversation still work.
-export function noSavedWallet(where) {
-    const refused = () => Promise.resolve(failed("Saving a wallet isn't available here yet. Name your cards in the conversation instead; nothing is stored."));
-    return {
-        where,
-        load: () => Promise.resolve(null),
-        addCard: refused,
-        updateCard: refused,
-        removeCard: refused,
-        setMemberships: refused,
-        record: refused,
-    };
-}

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
@@ -32,12 +33,20 @@ function fieldLines(field, f, indent) {
         case 'checkout_label':
         case 'anniversary': {
             const value = f[field];
-            return value === undefined ? '' : `${indent}${field}: ${scalar(value)}\n`;
+            return value == null ? '' : `${indent}${field}: ${scalar(value)}\n`;
         }
         case 'activated':
             return f.activated === undefined
                 ? ''
                 : `${indent}activated: ${flowList(f.activated)}\n`;
+        case 'cap_usage': {
+            if (f.cap_usage === undefined)
+                return '';
+            const caps = Object.entries(f.cap_usage)
+                .map(([key, u]) => `${indent}  ${key}: { period: ${scalar(u.period)}, spent: ${String(u.spent)} }\n`)
+                .join('');
+            return caps === '' ? '' : `${indent}cap_usage:\n${caps}`;
+        }
         case 'bonus': {
             if (!f.bonus)
                 return '';
@@ -65,6 +74,7 @@ const FIELDS = [
     'anniversary',
     'chosen',
     'activated',
+    'cap_usage',
     'bonus',
 ];
 function cardsSeq(text) {
@@ -154,6 +164,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');
@@ -173,10 +248,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

@@ -3,7 +3,7 @@ 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,

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}.`);
 }
@@ -47,7 +56,26 @@ export function pickedCategories(card, held, date) {
     }
     return { picked, staleChoice };
 }
-function applicability(rule, ctx, held, picked) {
+// Activating a rotating quarter (Freedom Flex) turns on all its categories:
+// rules on the same rotating cap with the same dates share one activation.
+export function activationGroup(card, ruleId) {
+    const rule = card.rules.find((r) => r.id === ruleId);
+    const cap = typeof rule?.cap === 'string'
+        ? card.caps.find((c) => c.id === rule.cap)
+        : undefined;
+    if (!rule || !cap?.rotating)
+        return [ruleId];
+    return card.rules
+        .filter((r) => r.requires?.activation === true &&
+        r.cap === rule.cap &&
+        r.valid_from === rule.valid_from &&
+        r.valid_to === rule.valid_to)
+        .map((r) => r.id);
+}
+export function isActivated(card, held, ruleId) {
+    return activationGroup(card, ruleId).some((id) => held.activated.includes(id));
+}
+function applicability(card, rule, ctx, held, picked) {
     const { match, exclude } = rule;
     const inCategory = (cats) => cats.some((c) => categoryMatches(c, ctx.category));
     if (match.categories?.length && !inCategory(match.categories))
@@ -89,24 +117,39 @@ function applicability(rule, ctx, held, picked) {
     const membership = rule.requires?.membership;
     if (membership !== undefined && !ctx.memberships.has(membership))
         return 'no';
-    if (rule.requires?.activation && !held.activated.includes(rule.id))
+    if (rule.requires?.activation && !isActivated(card, held, rule.id))
         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) {
@@ -134,7 +177,7 @@ export function evaluateCard(card, held, ctx) {
     let nominal = base;
     const blocked = [];
     for (const rule of card.rules) {
-        const status = applicability(rule, ctx, held, picked);
+        const status = applicability(card, rule, ctx, held, picked);
         if (status === 'no')
             continue;
         if (status === 'needs-activation') {

package/dist/engine/explore.js

@@ -1,9 +1,10 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
-import { periodKey } from "./periods.js";
-import { categoryPhrase, currencyLabel, dollars, earnText, num, recommend, } from "./recommend.js";
+import { choicePeriod, periodKey } from "./periods.js";
+import { recommend } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
+import { categoryPhrase, codesAs, earnText, money, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 export const ALL_PERSONAL_CARDS = {
@@ -29,18 +30,11 @@ export function matchesFilters(card, filters) {
         return false;
     return true;
 }
-// The period a card's picks are keyed by in a wallet.
-export function choicePeriod(card) {
-    for (const c of card.choices)
-        if (c.period !== 'until_changed')
-            return c.period;
-    return 'quarter';
-}
 // A card as its holder would set it up for the best result: the given picks,
 // every activation done, and no cap used yet. The anniversary is `date`, so a
 // cardmember-year cap starts fresh.
 export function idealHolding(card, date, picks = {}) {
-    const period = choicePeriod(card);
+    const period = choicePeriod(card) ?? 'calendar_year';
     return {
         id: card.id,
         anniversary: date.slice(5),
@@ -163,7 +157,7 @@ function conditionsText(catalog, r) {
     if (r.membership !== null)
         conditions.push(`Needs ${r.membership}.`);
     if (r.cap) {
-        conditions.push(`Up to ${dollars(r.cap.amount)} ${CAP_PERIODS[r.cap.period] ?? ''} at this rate, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}.`);
+        conditions.push(`Up to ${money(r.cap.amount)} ${CAP_PERIODS[r.cap.period] ?? ''} at this rate, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}.`);
     }
     return conditions;
 }
@@ -262,22 +256,15 @@ function exploreAssumptions(catalog, merchant, ranked, options) {
         assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
     }
     else if (merchant.source !== 'none') {
-        const code = merchant.likelyMcc === null ? '' : ` (MCC ${String(merchant.likelyMcc)})`;
-        assumptions.push(`Assumes ${merchant.resolvedName} codes as ${categoryPhrase(catalog, merchant.category)}${code}.`);
+        assumptions.push(codesAs(catalog, merchant));
     }
     assumptions.push('Assumes each card is set up for this purchase: the right category pick, any activation done, and none of its cap used yet. A card you hold may differ.');
     assumptions.push(options.memberships.length === 0
         ? 'Assumes no memberships (like Amazon Prime). Rates that need one are listed separately.'
         : `Assumes these memberships: ${options.memberships.join(', ')}.`);
-    const values = new Map();
-    for (const e of ranked.slice(0, 10)) {
-        if (e.currency !== 'cash')
-            values.set(e.currency, e.centsPerUnit);
-    }
-    if (values.size > 0) {
-        const list = [...values].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
-        assumptions.push(`Values points at: ${list.join(', ')}.`);
-    }
+    const values = pointValuesText(catalog, ranked.slice(0, 10));
+    if (values !== null)
+        assumptions.push(values);
     return assumptions;
 }
 function exploreWarnings(catalog, merchant) {

package/dist/engine/offers.js

@@ -1,14 +1,7 @@
+import { bonusDollars } from "./bonus.js";
+import { matchesFilters } from "./explore.js";
+import { roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
-const round = (n) => Math.round(n * 100) / 100;
-function bonusValue(card, centsPerUnit, points, dollars) {
-    if (points !== undefined)
-        return (points * centsPerUnit) / 100;
-    if (dollars === undefined)
-        return 0;
-    // 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 compareOffers(catalog, wallet, filters, today) {
     const held = new Set(wallet.cards.map((c) => c.id));
     const offers = [];
@@ -16,16 +9,9 @@ export function compareOffers(catalog, wallet, filters, today) {
     for (const card of catalog.cards) {
         if (card.network === 'store')
             continue;
-        if (card.business !== filters.business)
-            continue;
         if (!filters.includeHeld && held.has(card.id))
             continue;
-        const isCash = card.currency === 'cash';
-        if (filters.kind === 'cash' && !isCash)
-            continue;
-        if (filters.kind === 'points' && isCash)
-            continue;
-        if (filters.noAnnualFee && card.annual_fee !== 0)
+        if (!matchesFilters(card, { ...filters, issuer: null, includeClosed: true }))
             continue;
         const offer = card.welcome_offer;
         if (!offer || (offer.valid_to !== undefined && offer.valid_to < today)) {
@@ -33,7 +19,8 @@ export function compareOffers(catalog, wallet, filters, today) {
             continue;
         }
         const valuation = cardValuation(catalog, wallet, card);
-        const value = bonusValue(card, valuation.centsPerUnit, offer.points, offer.dollars);
+        const value = bonusDollars(card, valuation.centsPerUnit, offer.points, offer.dollars) ??
+            0;
         const firstYearFee = card.first_year_fee ?? card.annual_fee ?? null;
         offers.push({
             cardId: card.id,
@@ -47,11 +34,12 @@ export function compareOffers(catalog, wallet, filters, today) {
             spend: offer.spend,
             months: offer.months,
             validTo: offer.valid_to ?? null,
+            varies: offer.varies === true,
             note: offer.note ?? null,
             annualFee: card.annual_fee ?? null,
             firstYearFee,
-            bonusValue: round(value),
-            firstYearValue: round(value - (firstYearFee ?? 0)),
+            bonusValue: roundCents(value),
+            firstYearValue: roundCents(value - (firstYearFee ?? 0)),
             held: held.has(card.id),
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,
@@ -60,7 +48,7 @@ export function compareOffers(catalog, wallet, filters, today) {
     offers.sort((a, b) => b.firstYearValue - a.firstYearValue || a.cardId.localeCompare(b.cardId));
     const notes = [
         `Compares the ${String(catalog.cards.length)} cards earnrate knows, not every card on the market.`,
-        "Each offer is the public one on the issuer's page, checked weekly. Offers can differ by person and by how you apply, and issuers limit who can get a bonus; each card's note says how.",
+        "Each offer is the public one on the issuer's page on the date shown, checked weekly. Yours may differ: issuers test and target offers, so use the one shown to you when you apply. Issuers also limit who can get a bonus; each card's note says how.",
         "First-year value is the bonus at your point values minus the first year's annual fee. It leaves out what the card earns on your spending and any credits or perks.",
     ];
     return { offers, withoutOffer, notes };

package/dist/engine/periods.js

@@ -29,3 +29,12 @@ export function localToday(now = new Date()) {
         String(now.getDate()).padStart(2, '0'),
     ].join('-');
 }
+// The period a card's picks are filed under in a wallet. Picks that carry
+// over (until_changed) are never compared, so they file under the calendar
+// year. null when the card's picks reset on different schedules.
+export function choicePeriod(card) {
+    const periods = [
+        ...new Set(card.choices.map((c) => c.period).filter((p) => p !== 'until_changed')),
+    ];
+    return periods.length > 1 ? null : (periods[0] ?? 'calendar_year');
+}

package/dist/engine/recommend.js

@@ -1,8 +1,9 @@
 import { resolveMerchant, resolveMerchantById } from "../merchants/resolve.js";
-import { evaluateCard, purchaseContext, } from "./evaluate.js";
 import { bonusStatus } from "./bonus.js";
+import { evaluateCard, purchaseContext, usableAt, } from "./evaluate.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
+import { categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, num, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 export const STALE_AFTER_DAYS = 180;
@@ -20,36 +21,9 @@ const PERIOD_WORDS = {
     cardmember_year: 'cardmember-year',
 };
 const displayName = (e) => e.held.checkout_label ?? e.card.name;
-export const num = (n) => String(Number(n.toFixed(2)));
-// Whole dollars stay whole ($2,800); anything else shows cents ($0.40).
-const money = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
-export const dollars = (n) => `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
-export function currencyName(catalog, id) {
-    return catalog.currencies.find((c) => c.id === id)?.name ?? id;
-}
-export function currencyLabel(catalog, id) {
-    const name = currencyName(catalog, id);
-    return /^[A-Z]{2,4}$/.test(id) ? `${name} (${id})` : name;
-}
 // "Worth X or more" must hold at X itself, so round up; "less than X" rounds down.
 const roundUp = (n) => String(Math.ceil(n * 100 - EPSILON) / 100);
 const roundDown = (n) => String(Math.floor(n * 100 + EPSILON) / 100);
-function categoryName(catalog, id) {
-    return catalog.categories.find((c) => c.id === id)?.name ?? id;
-}
-// Mid-sentence form: "Supermarkets" becomes "supermarkets", but "TV and
-// internet service" and "EV charging" keep their acronyms.
-export function categoryPhrase(catalog, id) {
-    const name = categoryName(catalog, id);
-    return /^[A-Z]{2}/.test(name)
-        ? name
-        : name.charAt(0).toLowerCase() + name.slice(1);
-}
-export function earnText(catalog, rate, currency) {
-    return currency === 'cash'
-        ? `${num(rate)}% cash back`
-        : `${num(rate)}x ${currencyName(catalog, currency)}`;
-}
 function compareEntries(a, b) {
     const byReturn = b.effectiveReturnPct - a.effectiveReturnPct;
     if (Math.abs(byReturn) > EPSILON)
@@ -71,14 +45,11 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
         const card = catalog.cards.find((c) => c.id === held.id);
         if (!card)
             continue;
-        if (card.only_at) {
-            if (merchant.merchantId === null ||
-                !card.only_at.includes(merchant.merchantId))
+        if (!usableAt(card, merchant)) {
+            // A store card elsewhere isn't worth mentioning; a network the merchant
+            // doesn't take is.
+            if (card.only_at || card.network === 'store' || !merchant.accepts)
                 continue;
-        }
-        else if (card.network !== 'store' &&
-            merchant.accepts &&
-            !merchant.accepts.includes(card.network)) {
             const takes = merchant.accepts
                 .map((n) => NETWORK_NAMES[n] ?? n)
                 .join(' or ');
@@ -126,7 +97,7 @@ function reasoningFor(catalog, wallet, entry, amount) {
     const cap = best.cap;
     if (cap && amount !== null && amount > cap.remaining) {
         const over = amount - cap.remaining;
-        lines.push(`${dollars(cap.remaining)} earns ${earnText(catalog, best.nominalRate, currency)} before the cap, then ${dollars(over)} earns ${earnText(catalog, cap.cap.then_rate, currency)}: ${num(best.rate)} per dollar overall.`);
+        lines.push(`${money(cap.remaining)} earns ${earnText(catalog, best.nominalRate, currency)} before the cap, then ${money(over)} earns ${earnText(catalog, cap.cap.then_rate, currency)}: ${num(best.rate)} per dollar overall.`);
     }
     if (valuation.pooledFrom !== null) {
         const partners = card.pools_into?.when_wallet_has ?? [];
@@ -147,7 +118,7 @@ function warningsFor(catalog, entry, purchase) {
     const { best, nominal } = evaluation;
     const warnings = [];
     const capLabel = (e) => e.cap
-        ? `${dollars(e.cap.cap.amount)} ${PERIOD_WORDS[e.cap.cap.period] ?? ''} cap`
+        ? `${money(e.cap.cap.amount)} ${PERIOD_WORDS[e.cap.cap.period] ?? ''} cap`
         : '';
     if (best.cap && best.rule) {
         const { remaining, cap, period } = best.cap;
@@ -155,10 +126,10 @@ function warningsFor(catalog, entry, purchase) {
             warnings.push(`Add this card's anniversary (MM-DD) to your wallet so its ${capLabel(best)} can be tracked.`);
         }
         else if (purchase.amount !== null && purchase.amount > remaining) {
-            warnings.push(`This purchase crosses the ${capLabel(best)} on "${best.rule.id}": only ${dollars(remaining)} is left for ${period}.`);
+            warnings.push(`This purchase crosses the ${capLabel(best)} on "${best.rule.id}": only ${money(remaining)} is left for ${period}.`);
         }
         else if (remaining < cap.amount * NEAR_CAP_SHARE) {
-            warnings.push(`Only ${dollars(remaining)} left of the ${capLabel(best)} on "${best.rule.id}" for ${period}.`);
+            warnings.push(`Only ${money(remaining)} left of the ${capLabel(best)} on "${best.rule.id}" for ${period}.`);
         }
     }
     if (nominal.rule &&
@@ -265,11 +236,7 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
         assumptions.push(`Assumes ${merchant.resolvedName} falls outside the usual bonus categories.`);
     }
     else {
-        const category = catalog.categories.find((c) => c.id === merchant.category);
-        const mcc = merchant.likelyMcc ??
-            (category?.mccs.length === 1 ? category.mccs[0] : undefined);
-        const code = mcc === undefined ? '' : ` (MCC ${String(mcc)})`;
-        assumptions.push(`Assumes ${merchant.resolvedName} codes as ${categoryPhrase(catalog, merchant.category)}${code}.`);
+        assumptions.push(codesAs(catalog, merchant));
     }
     if (merchant.inference) {
         assumptions.push(`Claude's reasoning: ${merchant.inference.rationale}`);
@@ -280,15 +247,9 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
     if (purchase.channel === null && merchant.channel === 'online') {
         assumptions.push('Assumes an online purchase, since you gave a web address.');
     }
-    const pointValues = new Map();
-    for (const e of entries) {
-        if (e.valuation.currency !== 'cash')
-            pointValues.set(e.valuation.currency, e.valuation.centsPerUnit);
-    }
-    if (pointValues.size > 0) {
-        const list = [...pointValues].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
-        assumptions.push(`Values points at: ${list.join(', ')}.`);
-    }
+    const values = pointValuesText(catalog, entries.map((e) => e.valuation));
+    if (values !== null)
+        assumptions.push(values);
     return assumptions;
 }
 export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(catalog, purchase.merchant, purchase.channel)) {

package/dist/engine/record.js

@@ -1,7 +1,7 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { bonusStatus, countsTowardBonus } from "./bonus.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
-const roundCents = (n) => Math.round(n * 100) / 100;
+import { roundCents } from "./text.js";
 // Books the spend against the cap of the highest-rate rule that matches, even
 // when that cap is already used up, so usage stays accurate across a reset.
 // Returns null when there's nothing to track: no cap, or a cardmember-year cap
@@ -50,12 +50,8 @@ export function applyBooking(wallet, booking) {
             : c),
     };
 }
-export function recordPurchase(catalog, wallet, purchase) {
-    const booking = capBooking(catalog, wallet, purchase);
-    return booking ? applyBooking(wallet, booking) : wallet;
-}
 // The purchase's progress toward the card's open welcome bonus, if it counts.
-export function bonusBooking(catalog, wallet, purchase) {
+function bonusBooking(catalog, wallet, purchase) {
     const held = wallet.cards.find((c) => c.id === purchase.cardId);
     const status = held ? bonusStatus(catalog, wallet, held, purchase.date) : null;
     if (!status ||
@@ -79,7 +75,6 @@ export function applyBonusBooking(wallet, b) {
             : c),
     };
 }
-// Everything recording a purchase changes: its cap and its welcome bonus.
 export function bookPurchase(catalog, wallet, purchase, merchant) {
     const cap = capBooking(catalog, wallet, purchase, merchant);
     const bonus = bonusBooking(catalog, wallet, purchase);

package/dist/engine/setup.js

@@ -1,4 +1,4 @@
-import { pickedCategories } from "./evaluate.js";
+import { isActivated, pickedCategories } from "./evaluate.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
 // Rules that start within this many days are worth activating now.
@@ -144,7 +144,7 @@ export function setupNotes(catalog, wallet, held, today) {
             text: `Some of ${name}'s rates need a membership: ${list(missing)}. Add any that apply to the wallet's memberships.`,
         });
     }
-    const toActivate = activationRules(card, today).filter((id) => !held.activated.includes(id));
+    const toActivate = activationRules(card, today).filter((id) => !isActivated(card, held, id));
     if (toActivate.length > 0) {
         notes.push({
             kind: 'activation',