earnrate 0.2.0 → 0.2.1

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/simulate.js

@@ -1,15 +1,15 @@
 import { resolveMerchant } from "../merchants/resolve.js";
-import { evaluateCard, purchaseContext } from "./evaluate.js";
-import { categoryResolution, choicePeriod, findCategory, idealHolding, matchesFilters, } from "./explore.js";
-import { periodKey } from "./periods.js";
+import { evaluateCard, purchaseContext, usableAt } from "./evaluate.js";
+import { categoryResolution, findCategory, idealHolding, matchesFilters, } from "./explore.js";
+import { choicePeriod, periodKey } from "./periods.js";
 import { applyBooking, capBooking } from "./record.js";
 import { rotationGap } from "./rotation.js";
+import { roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 const MONTHS = 12;
 const SHORTLIST = 8; // best single cards considered for pairs
 const PER_LINE = 2; // plus the best cards for each spending line
-const round = (n) => Math.round(n * 100) / 100;
 export function resolveSpendLines(catalog, lines) {
     return lines
         .filter((l) => l.monthly > 0)
@@ -37,17 +37,10 @@ function withCurrentPicks(card, held, date) {
         ...held,
         chosen: {
             ...held.chosen,
-            period: periodKey(choicePeriod(card), date, null) ?? '',
+            period: periodKey(choicePeriod(card) ?? 'calendar_year', date, null) ?? '',
         },
     };
 }
-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));
-}
 // Spends `lines` every month for a year. Each dollar goes to the card that
 // earns the most on it right then, so spend moves to another card once a
 // cap runs out.
@@ -119,13 +112,13 @@ export function simulateWallet(catalog, wallet, lines, start) {
         };
         return {
             label: line.label,
-            spend: round(r.spend),
-            earned: round(r.earned),
+            spend: roundCents(r.spend),
+            earned: roundCents(r.earned),
             returnPct: r.spend > 0 ? (r.earned / r.spend) * 100 : 0,
             cards: [...r.byCard].sort((a, b) => b[1] - a[1]).map(([id]) => id),
         };
     });
-    const rewards = round(lineResults.reduce((sum, l) => sum + l.earned, 0));
+    const rewards = roundCents(lineResults.reduce((sum, l) => sum + l.earned, 0));
     const annualFees = cards.reduce((sum, c) => sum + (c.card.annual_fee ?? 0), 0);
     const notes = [];
     const dates = monthDates(start);
@@ -146,10 +139,10 @@ export function simulateWallet(catalog, wallet, lines, start) {
             cardId: h.id,
             picks: h.chosen?.picks ?? {},
         })),
-        spend: round(lineResults.reduce((sum, l) => sum + l.spend, 0)),
+        spend: roundCents(lineResults.reduce((sum, l) => sum + l.spend, 0)),
         rewards,
         annualFees,
-        net: round(rewards - annualFees),
+        net: roundCents(rewards - annualFees),
         lines: lineResults,
         notes,
     };
@@ -293,14 +286,14 @@ export function simulateAdditions(catalog, wallet, lines, options) {
             memberships: wallet.memberships,
             valuations: wallet.valuations,
         });
-        const extraRewards = round(simulation.rewards - current.rewards);
+        const extraRewards = roundCents(simulation.rewards - current.rewards);
         const annualFee = card.annual_fee ?? 0;
         additions.push({
             cardId: card.id,
             picks: simulation.cards.at(-1)?.picks ?? {},
             extraRewards,
             annualFee,
-            gain: round(extraRewards - annualFee),
+            gain: roundCents(extraRewards - annualFee),
             simulation,
         });
     }

package/dist/engine/text.js

@@ -0,0 +1,53 @@
+import { singleMcc } from "./evaluate.js";
+export const num = (n) => String(Number(n.toFixed(2)));
+export const pct = (n) => `${num(n)}%`;
+export const roundCents = (n) => Math.round(n * 100) / 100;
+// Whole dollars stay whole ($2,800); anything else shows cents ($0.40).
+export const money = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+export function feeText(fees) {
+    const { annualFee, firstYearFee } = fees;
+    if (annualFee === null)
+        return 'annual fee not on file';
+    if (annualFee === 0)
+        return 'no annual fee';
+    if (firstYearFee !== null && firstYearFee !== annualFee)
+        return `${money(annualFee)} annual fee (${firstYearFee === 0 ? 'waived' : money(firstYearFee)} the first year)`;
+    return `${money(annualFee)} annual fee`;
+}
+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;
+}
+// Mid-sentence form: "Supermarkets" becomes "supermarkets", but "TV and
+// internet service" and "EV charging" keep their acronyms.
+export function categoryPhrase(catalog, id) {
+    const name = catalog.categories.find((c) => c.id === id)?.name ?? 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)}`;
+}
+export function codesAs(catalog, merchant) {
+    const mcc = merchant.likelyMcc ?? singleMcc(catalog, merchant.category);
+    const code = mcc === null ? '' : ` (MCC ${String(mcc)})`;
+    return `Assumes ${merchant.resolvedName} codes as ${categoryPhrase(catalog, merchant.category)}${code}.`;
+}
+// "Values points at: Membership Rewards (MR) at 1¢." for the currencies an
+// answer ranks, or null when every card shown earns cash.
+export function pointValuesText(catalog, shown) {
+    const values = new Map();
+    for (const e of shown)
+        if (e.currency !== 'cash')
+            values.set(e.currency, e.centsPerUnit);
+    if (values.size === 0)
+        return null;
+    const list = [...values].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
+    return `Values points at: ${list.join(', ')}.`;
+}

package/dist/engine/transient.js

@@ -1,4 +1,9 @@
 import { addToWallet, withMemberships, } from "./wallet-change.js";
+export const EMPTY_WALLET = {
+    valuations: {},
+    memberships: [],
+    cards: [],
+};
 // A wallet for one answer, from cards the user named in the conversation.
 // Nothing is saved; the same rules as adding cards to a saved wallet apply.
 export function walletFromCards(catalog, named, today) {

package/dist/engine/valuation.js

@@ -1,4 +1,4 @@
-export function currencyValuation(catalog, wallet, currencyId) {
+function currencyValuation(catalog, wallet, currencyId) {
     const currency = catalog.currencies.find((c) => c.id === currencyId);
     if (!currency)
         throw new Error(`unknown currency '${currencyId}'`);

package/dist/engine/wallet-change.js

@@ -1,8 +1,8 @@
-import { periodKey } from "./periods.js";
+import { choicePeriod, periodKey } from "./periods.js";
 import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
 const failed = (error) => ({ ok: false, error });
 const list = (ids) => ids.join(', ');
-export function findCatalogCard(catalog, id, today) {
+function findCatalogCard(catalog, id, today) {
     const card = catalog.cards.find((c) => c.id === id);
     if (card)
         return card;
@@ -11,22 +11,16 @@ export function findCatalogCard(catalog, id, today) {
         ? `No card '${id}' in earnrate. Closest: ${list(near)}.`
         : `No card '${id}' in earnrate. Search the catalog to find its id.`;
 }
-export function isAnniversary(text) {
+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 pickPeriod(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 pickKey(card, today) {
+    const period = choicePeriod(card);
+    return period === null ? null : periodKey(period, today, null);
 }
 export function cardFields(card, held, input, today) {
     const problems = [];
@@ -77,7 +71,7 @@ export function cardFields(card, held, input, today) {
                 problems.push(`${choiceId} takes ${choice.pick === 1 ? '1 pick' : `1 to ${String(choice.pick)} picks`}, not ${String(picks.length)}.`);
             }
         }
-        const period = pickPeriod(card, today);
+        const period = pickKey(card, today);
         if (period === null) {
             problems.push(`${card.id} has picks on different schedules; edit the wallet by hand.`);
         }
@@ -116,12 +110,12 @@ export function cardFields(card, held, input, today) {
     }
     return problems.length > 0 ? problems.join('\n') : fields;
 }
-export const newHolding = (id) => ({
+const newHolding = (id) => ({
     id,
     cap_usage: {},
     activated: [],
 });
-export const withFields = ({ bonus, ...held }, f) => ({
+const withFields = ({ bonus, ...held }, f) => ({
     ...held,
     ...(bonus && f.bonus === undefined ? { bonus } : {}),
     ...(f.checkout_label === undefined

package/dist/engine/wallet-summary.js

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

package/dist/format/card-text.js

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

package/dist/format/cheat-sheet.js

@@ -1,4 +1,4 @@
-const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
+import { pct } from "../engine/text.js";
 export function formatCheatSheet(sheet) {
     const labelWidth = Math.max(...sheet.rows.map((r) => r.label.length));
     const cardWidth = Math.max(...sheet.rows.map((r) => (r.cardName ?? 'none of your cards').length));

package/dist/format/explore.js

@@ -1,15 +1,5 @@
-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`;
-}
+import { feeText, money, pct } from "../engine/text.js";
+const wholeUsd = (n) => money(Math.round(n));
 const TOP_BEST = 10;
 export function formatExploration(r, all) {
     const m = r.merchant;
@@ -24,7 +14,7 @@ export function formatExploration(r, all) {
     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)}`;
+        const earned = e.earned === null ? '' : `  ${money(e.earned)}`;
         lines.push(`${String(i + 1).padStart(2)}. ${e.cardName.padEnd(width)}  ${pct(e.effectiveReturnPct).padStart(5)}${earned}  ${feeText(e)}`);
         for (const c of e.conditions)
             lines.push(`    ${c}`);

package/dist/format/offers.js

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

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

@@ -1,11 +1,7 @@
+import { money, pct } from "../engine/text.js";
 export const plain = (_format, text) => text;
 const TOP = 3;
-const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
 const cents = (n) => `$${n.toFixed(2)}`;
-const amountText = (n) => `$${n.toLocaleString('en-US', {
-    minimumFractionDigits: Number.isInteger(n) ? 0 : 2,
-    maximumFractionDigits: 2,
-})}`;
 const label = (c) => c.checkoutLabel ?? c.cardName;
 function header(rec, purchase) {
     const m = rec.merchant;
@@ -23,7 +19,7 @@ function header(rec, purchase) {
                         : m.resolvedName,
     ];
     if (purchase.amount !== null)
-        parts.push(amountText(purchase.amount));
+        parts.push(money(purchase.amount));
     if (m.channel)
         parts.push(m.channel === 'online' ? 'online' : 'in-store');
     return parts.join(' · ');

package/dist/format/wallet.js

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