earnrate 0.2.5 → 0.2.7

package/dist/engine/checklist.js

@@ -0,0 +1,152 @@
+import { daysBetween, periodEnd, periodKey } from "./periods.js";
+import { CAP_PERIODS, choiceName, listed, money, shortDate, wholeDollars, } from "./text.js";
+import { optionName } from "./rule-text.js";
+import { activationsDue, walletSummary, } from "./wallet-summary.js";
+// What the wallet's cards need this period, soonest first: bonuses to
+// activate, categories to pick, caps running low, welcome bonuses to finish,
+// and rotating categories the issuer hasn't posted yet.
+export function checklist(catalog, wallet, today, summary = walletSummary(catalog, wallet, today), 
+// A shorter card name than the issuer's full one, where the caller has it.
+shortName) {
+    const items = [];
+    for (const held of wallet.cards) {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        const s = summary.cards.find((c) => c.cardId === held.id);
+        if (!card || !s)
+            continue;
+        const name = s.checkoutLabel ?? shortName?.(card.id) ?? s.cardName;
+        for (const a of activationsDue(catalog, card, held, today)) {
+            const starts = a.from !== null && a.from > today
+                ? `, starting ${shortDate(a.from)}`
+                : '';
+            items.push({
+                kind: 'activate',
+                cardId: card.id,
+                text: `Activate ${name}'s bonus on ${a.what}${starts}${a.activateBy === null ? '' : `, by ${shortDate(a.activateBy)}`}.`,
+                due: a.activateBy ?? (a.from !== null && a.from > today ? a.from : a.to),
+            });
+        }
+        const picked = (id) => s.chosen?.picks[id] !== undefined;
+        const current = s.chosen?.current === true;
+        const unpicked = card.choices.filter((c) => !c.default &&
+            !(current && picked(c.id)) &&
+            c.period !== 'until_changed');
+        const [first] = unpicked;
+        if (first) {
+            const period = first.period === 'until_changed'
+                ? null
+                : periodKey(first.period, today, null);
+            items.push({
+                kind: 'pick',
+                cardId: card.id,
+                text: `Pick ${name}'s ${listed(unpicked.map((c) => choiceName(c.id)))} categories for this ${first.period.replace('_', ' ')}; until then they earn the base rate.`,
+                due: period === null ? null : periodEnd(period),
+            });
+        }
+        else {
+            // Picks made for this period: near its end, a reminder to make the
+            // next period's (Cash+ asks each quarter).
+            const ending = card.choices.find((c) => c.period !== 'until_changed' && !c.default && current);
+            const period = ending === undefined || ending.period === 'until_changed'
+                ? null
+                : periodKey(ending.period, today, null);
+            const end = period === null ? null : periodEnd(period);
+            if (ending && end !== null && daysBetween(today, end) <= 14)
+                items.push({
+                    kind: 'pick',
+                    cardId: card.id,
+                    text: `Pick ${name}'s categories for next ${ending.period.replace('_', ' ')}; this one ends ${shortDate(end)}.`,
+                    due: end,
+                });
+        }
+        // A pick earnrate assumes because none was saved: worth confirming.
+        const assumed = card.choices.filter((c) => c.default && !picked(c.id));
+        if (assumed.length > 0)
+            items.push({
+                kind: 'pick',
+                cardId: card.id,
+                text: `${name}'s ${listed(assumed.map((c) => choiceName(c.id)))} pick is assumed to be ${listed(assumed.flatMap((c) => (c.default ?? []).map((o) => optionName(catalog, card, c.id, o))))}; set it if you picked something else.`,
+                due: null,
+            });
+        for (const cap of s.caps) {
+            // Only caps nearly used up: the rest aren't something to do.
+            if (cap.remaining === null || cap.remaining > cap.amount * 0.25)
+                continue;
+            const resets = cap.currentPeriod === null ? null : periodEnd(cap.currentPeriod);
+            items.push({
+                kind: 'cap',
+                cardId: card.id,
+                text: cap.remaining === 0
+                    ? `${name}'s ${cap.label} cap is used up${resets === null ? '' : ` until ${shortDate(resets)}`}; another card may earn more there.`
+                    : `${name}: ${money(cap.remaining)} left of ${money(cap.amount)} ${CAP_PERIODS[cap.period]} at the bonus rate on ${cap.label}.`,
+                due: resets,
+            });
+        }
+        const b = s.bonus;
+        if (b?.state === 'open' && b.remaining !== null && b.deadline !== null) {
+            const weeks = Math.max(1, (b.daysLeft ?? 7) / 7);
+            items.push({
+                kind: 'bonus',
+                cardId: card.id,
+                text: `${name}'s welcome bonus: ${money(b.remaining)} to go by ${shortDate(b.deadline)}, about ${wholeDollars(b.remaining / weeks)} a week.`,
+                due: b.deadline,
+            });
+        }
+        if (s.rotationGap !== null) {
+            items.push({
+                kind: 'rotation',
+                cardId: card.id,
+                text: `${name}'s ${s.rotationGap} categories aren't out yet; earnrate adds them once the issuer posts them.`,
+                due: null,
+            });
+        }
+    }
+    return items.sort((a, b) => (a.due ?? '9999').localeCompare(b.due ?? '9999') ||
+        a.cardId.localeCompare(b.cardId));
+}
+// An all-day calendar event for each dated action (activations, picks,
+// welcome-bonus deadlines), with a reminder two days before. Built on the
+// device: nothing is sent anywhere.
+export function checklistCalendar(items, stamp) {
+    const escape = (t) => t.replace(/\\/g, '\\\\').replace(/[,;]/g, (c) => `\\${c}`);
+    const fold = (line) => {
+        const parts = [];
+        for (let i = 0; i < line.length; i += 73)
+            parts.push(line.slice(i, i + 73));
+        return parts.join('\r\n ');
+    };
+    const day = (d) => d.replace(/-/g, '');
+    const next = (d) => {
+        const t = new Date(`${d}T00:00:00Z`);
+        t.setUTCDate(t.getUTCDate() + 1);
+        return t.toISOString().slice(0, 10);
+    };
+    const events = items
+        .filter((i) => i.due !== null && i.kind !== 'cap' && i.kind !== 'rotation')
+        .flatMap((i) => {
+        const due = i.due ?? '';
+        return [
+            'BEGIN:VEVENT',
+            `UID:${i.kind}-${i.cardId}-${due}@earnrate.dev`,
+            `DTSTAMP:${stamp}`,
+            `DTSTART;VALUE=DATE:${day(due)}`,
+            `DTEND;VALUE=DATE:${day(next(due))}`,
+            fold(`SUMMARY:${escape(i.text)}`),
+            'BEGIN:VALARM',
+            'TRIGGER:-P2D',
+            'ACTION:DISPLAY',
+            fold(`DESCRIPTION:${escape(i.text)}`),
+            'END:VALARM',
+            'END:VEVENT',
+        ];
+    });
+    return [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'PRODID:-//earnrate//checklist//EN',
+        'CALSCALE:GREGORIAN',
+        ...events,
+        'END:VCALENDAR',
+        '',
+    ].join('\r\n');
+}

package/dist/engine/compare.js

@@ -1,5 +1,7 @@
 // Returns closer than this are equal: floating-point noise, not a difference.
 export const EPSILON = 1e-9;
+// Dollar amounts closer than half a cent print the same.
+export const HALF_CENT = 0.005;
 // A card close to the best one: within a percentage point, and at least
 // three quarters of its rate. Answers and cheat sheets mention a welcome
 // bonus card when it's this close.

package/dist/engine/evaluate.js

@@ -1,4 +1,4 @@
-import { periodKey } from "./periods.js";
+import { inEffect, periodKey } from "./periods.js";
 export function purchaseContext(catalog, wallet, merchant, category, purchase) {
     return {
         category,
@@ -110,9 +110,7 @@ function applicability(card, rule, ctx, held, picked) {
         return 'no';
     if (rule.geography === 'us_only' && ctx.country !== 'US')
         return 'no';
-    if (rule.valid_from !== undefined && ctx.date < rule.valid_from)
-        return 'no';
-    if (rule.valid_to !== undefined && ctx.date > rule.valid_to)
+    if (!inEffect(rule, ctx.date))
         return 'no';
     const membership = rule.requires?.membership;
     if (membership !== undefined && !ctx.memberships.has(membership))
@@ -149,14 +147,14 @@ function capState(rule, card, held, date) {
     const { period, spent } = capUsed(cap, key, held, date);
     return { key, cap, period, remaining: Math.max(0, cap.amount - spent) };
 }
-function rateAfterCap(rate, cap, amount) {
+function rateAfterCap(rate, cap, afterCap, amount) {
     if (!cap)
         return rate;
     if (amount !== null && amount > 0) {
         const inCap = Math.min(amount, cap.remaining);
-        return (inCap * rate + (amount - inCap) * cap.cap.then_rate) / amount;
+        return (inCap * rate + (amount - inCap) * afterCap) / amount;
     }
-    return cap.remaining > 0 ? rate : cap.cap.then_rate;
+    return cap.remaining > 0 ? rate : afterCap;
 }
 // On equal rates an uncapped rule wins, so spend that can earn the same
 // without a cap doesn't use one up. Otherwise the earlier rule stays.
@@ -172,24 +170,31 @@ export function evaluateCard(card, held, ctx) {
         nominalRate: card.base_rate,
         rate: card.base_rate,
         cap: null,
+        afterCap: null,
     };
     let best = base;
     let nominal = base;
     const blocked = [];
+    const applying = [];
     for (const rule of card.rules) {
         const status = applicability(card, rule, ctx, held, picked);
         if (status === 'no')
             continue;
-        if (status === 'needs-activation') {
+        if (status === 'needs-activation')
             blocked.push(rule);
-            continue;
-        }
+        else
+            applying.push(rule);
+    }
+    const uncapped = Math.max(card.base_rate, ...applying.filter((r) => r.cap === undefined).map((r) => r.rate));
+    for (const rule of applying) {
         const cap = capState(rule, card, held, ctx.date);
+        const afterCap = cap ? Math.max(cap.cap.then_rate, uncapped) : null;
         const earning = {
             rule,
             nominalRate: rule.rate,
-            rate: rateAfterCap(rule.rate, cap, ctx.amount),
+            rate: rateAfterCap(rule.rate, cap, afterCap ?? rule.rate, ctx.amount),
             cap,
+            afterCap,
         };
         if (beats(earning, earning.rate, best, best.rate))
             best = earning;

package/dist/engine/explore.js

@@ -1,12 +1,12 @@
-import { resolveMerchant } from "../merchants/resolve.js";
+import { categoryResolution, resolvePlace } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
 import { membershipName, membershipNeeded, paidMemberships, } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
-import { optionName } from "./wallet-summary.js";
-import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, earnText, money, PICK_PERIODS, pointValuesText, } from "./text.js";
+import { optionName } from "./rule-text.js";
+import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, earnText, listed, money, PICK_PERIODS, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
@@ -49,38 +49,6 @@ export function idealHolding(card, date, picks = {}) {
             : {}),
     };
 }
-const plainWords = (s) => s
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, ' ')
-    .trim();
-// A category from everyday words: an alias ("groceries") first, then the
-// name, then the id, so "grocery" means supermarkets rather than the parent.
-export function findCategory(catalog, text) {
-    const wanted = plainWords(text);
-    if (wanted === '')
-        return null;
-    const by = (key) => catalog.categories.find((c) => key(c).map(plainWords).includes(wanted))?.id;
-    return (by((c) => c.aliases) ?? by((c) => [c.name]) ?? by((c) => [c.id]) ?? null);
-}
-export function categoryResolution(catalog, category, channel) {
-    const found = catalog.categories.find((c) => c.id === category);
-    if (!found)
-        throw new Error(`unknown category '${category}'`);
-    return {
-        input: found.name,
-        merchantId: null,
-        resolvedName: found.name,
-        category,
-        likelyMcc: null,
-        accepts: null,
-        ambiguity: null,
-        channel,
-        confidence: 'high',
-        source: 'category',
-        bookedVia: [],
-        inference: null,
-    };
-}
 function walletOf(held, options) {
     return {
         valuations: options.valuations,
@@ -131,7 +99,7 @@ function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
             ? {
                 amount: cap.amount,
                 period: cap.period,
-                thenRate: cap.then_rate,
+                thenRate: best.afterCap ?? cap.then_rate,
                 currency: cardValuation(catalog, wallet, card).currency,
             }
             : null,
@@ -185,7 +153,7 @@ function compareExplored(a, b) {
 export function exploreCards(catalog, query, options, resolved) {
     const merchant = resolved ??
         (query.merchant !== null
-            ? resolveMerchant(catalog, query.merchant, query.channel)
+            ? resolvePlace(catalog, query.merchant, query.channel)
             : categoryResolution(catalog, query.category ?? 'other', query.channel));
     const purchase = {
         merchant: merchant.input,
@@ -259,7 +227,7 @@ function exploreAssumptions(catalog, merchant, ranked, options) {
     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(', ')}.`);
+        : `Assumes these memberships: ${listed(options.memberships.map((m) => membershipName(catalog, m)))}.`);
     const values = pointValuesText(catalog, ranked.slice(0, 10));
     if (values !== null)
         assumptions.push(values);

package/dist/engine/memberships.js

@@ -6,7 +6,7 @@ export function membershipName(catalog, id) {
     return membership(catalog, id)?.name ?? words(id);
 }
 // "a Costco membership", for a sentence.
-export function withArticle(name) {
+function withArticle(name) {
     return `${/^[aeiou]/i.test(name) ? 'an' : 'a'} ${name}`;
 }
 // Tiers of one membership: holding one, the others in its group aren't

package/dist/engine/offers.js

@@ -1,6 +1,7 @@
 import { bonusDollars } from "./bonus.js";
 import { matchesFilters } from "./explore.js";
 import { membershipCosts, paidMemberships } from "./memberships.js";
+import { inEffect } from "./periods.js";
 import { money, roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
 function ineligibleText(catalog, wallet, notWith) {
@@ -41,7 +42,7 @@ export function compareOffers(catalog, wallet, filters, today) {
         if (!matchesFilters(card, { ...filters, issuer: null, includeClosed: true }))
             continue;
         const offer = card.welcome_offer;
-        if (!offer || (offer.valid_to !== undefined && offer.valid_to < today)) {
+        if (!offer || !inEffect(offer, today)) {
             withoutOffer.push(card.id);
             continue;
         }

package/dist/engine/periods.js

@@ -38,3 +38,21 @@ export function choicePeriod(card) {
     ];
     return periods.length > 1 ? null : (periods[0] ?? 'calendar_year');
 }
+// Whether a dated rule or offer is in effect on `date`; an open end has no
+// limit on that side.
+export const inEffect = (window, date) => (window.valid_from === undefined || window.valid_from <= date) &&
+    (window.valid_to === undefined || window.valid_to >= date);
+// The last day of a period key ("2026-Q4", "2026-10", "2026").
+export function periodEnd(period) {
+    const quarter = /^(\d{4})-Q([1-4])$/.exec(period);
+    if (quarter) {
+        const end = ['03-31', '06-30', '09-30', '12-31'][Number(quarter[2]) - 1];
+        return `${quarter[1] ?? ''}-${end ?? ''}`;
+    }
+    const month = /^(\d{4})-(\d{2})$/.exec(period);
+    if (month) {
+        const last = new Date(Date.UTC(Number(month[1]), Number(month[2]), 0));
+        return last.toISOString().slice(0, 10);
+    }
+    return /^\d{4}$/.test(period) ? `${period}-12-31` : null;
+}

package/dist/engine/recommend.js

@@ -1,10 +1,12 @@
-import { resolveMerchant, resolveMerchantById } from "../merchants/resolve.js";
+import { findMerchant, resolveMerchant, resolveMerchantById, } from "../merchants/resolve.js";
 import { bonusStatus } from "./bonus.js";
 import { evaluateCard, purchaseContext, usableAt, } from "./evaluate.js";
+import { membershipName } from "./memberships.js";
 import { daysBetween } from "./periods.js";
+import { ruleWhat } from "./rule-text.js";
 import { rotationGap } from "./rotation.js";
 import { EPSILON, isClose } from "./compare.js";
-import { CAP_ADJECTIVES, categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, NETWORK_NAMES, num, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.js";
+import { CAP_ADJECTIVES, categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, NETWORK_NAMES, num, pct, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 export const STALE_AFTER_DAYS = 180;
 // The warning when no card works; the CLI shows it as the answer instead.
@@ -84,7 +86,7 @@ function reasoningFor(catalog, wallet, entry, amount) {
     const currency = valuation.currency;
     if (best.rule) {
         const note = best.rule.note ? ` ${best.rule.note}` : '';
-        lines.push(`${earnText(catalog, best.nominalRate, currency)} from its "${best.rule.id}" rule.${note}`);
+        lines.push(`${earnText(catalog, best.nominalRate, currency)} on ${ruleWhat(catalog, best.rule)}${best.rule.requires?.membership === undefined ? '' : `, with ${membershipName(catalog, best.rule.requires.membership)}`}.${note}`);
     }
     else {
         lines.push(`${earnText(catalog, card.base_rate, currency)}, its base rate. No bonus category applies here.`);
@@ -92,7 +94,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(`${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.`);
+        lines.push(`${money(cap.remaining)} earns ${earnText(catalog, best.nominalRate, currency)} before the cap, then ${money(over)} earns ${earnText(catalog, best.afterCap ?? cap.cap.then_rate, currency)}: ${num(best.rate)} per dollar overall.`);
     }
     if (valuation.pooledFrom !== null) {
         const partners = card.pools_into?.when_wallet_has ?? [];
@@ -104,7 +106,7 @@ function reasoningFor(catalog, wallet, entry, amount) {
         lines.push(`Pools into ${currencyName(catalog, currency)} because you hold ${heldPartners.join(' and ')}.`);
     }
     if (currency !== 'cash') {
-        lines.push(`Valued at ${num(valuation.centsPerUnit)}¢ per point: ${num(entry.effectiveReturnPct)}% back.`);
+        lines.push(`Valued at ${num(valuation.centsPerUnit)}¢ per point: ${pct(entry.effectiveReturnPct)} back.`);
     }
     return lines;
 }
@@ -121,17 +123,17 @@ 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 ${money(remaining)} is left for ${period}.`);
+            warnings.push(`This purchase crosses the ${capLabel(best)} on ${ruleWhat(catalog, best.rule)}: only ${money(remaining)} is left for ${period}.`);
         }
         else if (remaining < cap.amount * NEAR_CAP_SHARE) {
-            warnings.push(`Only ${money(remaining)} left of the ${capLabel(best)} on "${best.rule.id}" for ${period}.`);
+            warnings.push(`Only ${money(remaining)} left of the ${capLabel(best)} on ${ruleWhat(catalog, best.rule)} for ${period}.`);
         }
     }
     if (nominal.rule &&
         nominal.cap &&
         nominal !== best &&
         nominal.cap.remaining === 0) {
-        warnings.push(`The ${capLabel(nominal)} on "${nominal.rule.id}" is used up for ${nominal.cap.period ?? 'this period'}, so it earns ${earnText(catalog, nominal.cap.cap.then_rate, valuation.currency)} until it resets.`);
+        warnings.push(`The ${capLabel(nominal)} on ${ruleWhat(catalog, nominal.rule)} is used up for ${nominal.cap.period ?? 'this period'}, so it earns ${earnText(catalog, nominal.afterCap ?? nominal.cap.cap.then_rate, valuation.currency)} until it resets.`);
     }
     if (best.rule?.unverified !== undefined) {
         warnings.push(`This rate isn't confirmed against the issuer's terms yet: ${best.rule.unverified}`);
@@ -144,7 +146,7 @@ function warningsFor(catalog, entry, purchase) {
         warnings.push(`Your chosen categories are set for ${evaluation.staleChoice}, not the current period, so chosen-category bonuses don't apply until you update them.`);
     }
     for (const rule of evaluation.needsActivation) {
-        warnings.push(`Activate this bonus with the issuer (it's free) to earn ${earnText(catalog, rule.rate, valuation.currency)} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
+        warnings.push(`Activate this bonus with the issuer (it's free)${rule.activate_by === undefined ? '' : ` by ${shortDate(rule.activate_by)}`} to earn ${earnText(catalog, rule.rate, valuation.currency)} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
     }
     return warnings;
 }
@@ -183,7 +185,7 @@ function tieNote(entries) {
             tied.some((e) => e.evaluation.best.cap !== null)
             ? 'because its rate has no cap'
             : 'by a fixed order; either works';
-    return `${names} also ${verb} ${num(winner.effectiveReturnPct)}% here. ${displayName(winner)} wins the tie ${why}.`;
+    return `${names} also ${verb} ${pct(winner.effectiveReturnPct)} here. ${displayName(winner)} wins the tie ${why}.`;
 }
 // Finds the closest point inside a currency's value range where the winner
 // stops winning, varying one currency at a time. Returns are linear in the
@@ -278,19 +280,18 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             const twin = alts.find((e) => e.card.id !== winner.card.id &&
                 alt.effectiveReturnPct - e.effectiveReturnPct <= EPSILON);
             if (alt.card.id !== winner.card.id)
-                warnings.push(`${as}, ${displayName(alt)} wins (${num(alt.effectiveReturnPct)}%).`);
+                warnings.push(`${as}, ${displayName(alt)} wins (${pct(alt.effectiveReturnPct)}).`);
             else if (twin)
-                warnings.push(`${as}, ${displayName(twin)} earns as much (${num(twin.effectiveReturnPct)}%).`);
+                warnings.push(`${as}, ${displayName(twin)} earns as much (${pct(twin.effectiveReturnPct)}).`);
         }
     }
     if (!winner) {
         warnings.push(noCardText(merchant.resolvedName));
         // Only where the merchant's data says what its website takes: without
         // that, every network is assumed, and a gas pump has no website.
-        const record = [
-            ...catalog.merchants.overrides,
-            ...catalog.merchants.seed,
-        ].find((m) => m.id === merchant.merchantId);
+        const record = merchant.merchantId === null
+            ? undefined
+            : findMerchant(catalog, merchant.merchantId);
         const online = merchant.channel === 'in_store' &&
             merchant.merchantId !== null &&
             record?.online?.accepts !== undefined
@@ -300,7 +301,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             ? rankEntries(catalog, wallet, { ...purchase, channel: 'online' }, online, online.category).entries[0]
             : undefined;
         if (alt)
-            warnings.push(`Ordering online instead? ${displayName(alt)} works there (${num(alt.effectiveReturnPct)}%).`);
+            warnings.push(`Ordering online instead? ${displayName(alt)} works there (${pct(alt.effectiveReturnPct)}).`);
     }
     else if (merchant.accepts === null &&
         (winner.card.network === 'amex' || winner.card.network === 'discover')) {
@@ -325,7 +326,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const alt = rankEntries(catalog, wallet, purchase, via, via.category)
             .entries[0];
         if (alt && alt.effectiveReturnPct > winner.effectiveReturnPct + EPSILON) {
-            notes.push(`If you book it as ${via.resolvedName}, ${displayName(alt)} earns ${num(alt.effectiveReturnPct)}%.`);
+            notes.push(`If you book it as ${via.resolvedName}, ${displayName(alt)} earns ${pct(alt.effectiveReturnPct)}.`);
         }
     }
     const open = bonusPick(catalog, wallet, entries, purchase.date);
@@ -341,7 +342,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
     const bonus = open && (open.behind || ties) ? open : null;
     const best = winner?.effectiveReturnPct ?? 0;
     if (open && !bonus && isClose(open.entry.effectiveReturnPct, best)) {
-        notes.push(`${displayName(open.entry)} earns ${num(open.entry.effectiveReturnPct)}% here, ${num(gap)} ${gap === 1 ? 'point' : 'points'} less than ${num(best)}%, and would help its welcome bonus (${money(open.status.remaining ?? 0)} more by ${open.status.deadline ?? ''}). You're on pace, so this uses the higher rate.`);
+        notes.push(`${displayName(open.entry)} earns ${pct(open.entry.effectiveReturnPct)} here, ${num(gap)} ${gap === 1 ? 'point' : 'points'} less than ${pct(best)}, and would help its welcome bonus (${money(open.status.remaining ?? 0)} more by ${open.status.deadline ?? ''}). You're on pace, so this uses the higher rate.`);
     }
     const chosen = bonus?.entry ?? winner;
     // A tie among the top cards doesn't matter when a welcome bonus decides.
@@ -377,7 +378,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             : `You're behind pace on ${displayName(bonus.entry)}'s welcome bonus: ${money(remaining)} more to spend by ${deadline}${pace}${worth}.${isBest
                 ? ''
                 : costHere === null
-                    ? ` It earns ${num(top.effectiveReturnPct)}% here against ${num(first.effectiveReturnPct)}% on ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`
+                    ? ` It earns ${pct(top.effectiveReturnPct)} here against ${pct(first.effectiveReturnPct)} on ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`
                     : ` Using it here earns ${money(costHere)} less than ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`}`);
     }
     let confidence = merchant.confidence;

package/dist/engine/rule-text.js

@@ -0,0 +1,47 @@
+import { findMerchant } from "../merchants/resolve.js";
+import { categoryPhrase, choiceName, listed, words } from "./text.js";
+// What a rule or a pick covers, in words, for answers and wallet lists.
+// Travel-site bookings ("Flight through Amex Travel") read mid-sentence in
+// lower case and plural; brand names ("Airbnb through Amex Travel") keep theirs.
+const BOOKING = /^(Attraction|Car rental|Cruise|Flight|Hotel|Vacation rental)\b/;
+function merchantName(catalog, id) {
+    const merchant = findMerchant(catalog, id);
+    const name = merchant?.name ?? words(id);
+    return merchant?.kind === 'booking'
+        ? name.replace(BOOKING, (kind) => `${kind.toLowerCase()}s`)
+        : name;
+}
+export function optionName(catalog, card, choiceId, option) {
+    const o = card.choices.find((c) => c.id === choiceId)?.options[option];
+    if (!o)
+        return words(option);
+    const parts = [
+        ...o.categories.map((c) => categoryPhrase(catalog, c)),
+        ...o.merchants.map((m) => merchantName(catalog, m)),
+    ];
+    if (o.online)
+        parts.push('online shopping');
+    return parts.length > 0 ? listed(parts) : words(option);
+}
+// What a rule covers, as a list of phrases.
+export function ruleParts(catalog, rule) {
+    if (rule.match.any)
+        return ['everything else'];
+    if (rule.match.choice !== undefined)
+        return [`your ${choiceName(rule.match.choice)} picks`];
+    const merchants = rule.match.merchants ?? [];
+    // A long list of one kind of store reads as "select streaming services".
+    const kinds = new Set(merchants.map((m) => findMerchant(catalog, m)?.category));
+    const [kind] = kinds;
+    const merchantParts = merchants.length > 4 && kinds.size === 1 && kind !== undefined
+        ? [`select ${categoryPhrase(catalog, kind)}`]
+        : merchants.map((m) => merchantName(catalog, m));
+    const parts = [
+        ...(rule.match.categories ?? []).map((c) => categoryPhrase(catalog, c)),
+        ...merchantParts,
+    ];
+    return parts.length > 0 ? parts : [words(rule.id)];
+}
+export function ruleWhat(catalog, rule) {
+    return listed(ruleParts(catalog, rule));
+}

package/dist/engine/setup.js

@@ -2,19 +2,10 @@ import { isActivated, pickedCategories } from "./evaluate.js";
 import { membership, membershipName, sameGroup } from "./memberships.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
+import { idList, listed } from "./text.js";
 // Rules that start within this many days are worth activating now.
 const ACTIVATION_LOOKAHEAD_DAYS = 45;
-const ISSUER_NICKNAMES = {
-    amex: 'american express',
-    'bank-of-america': 'bofa boa bankofamerica',
-    'capital-one': 'capitalone',
-    citi: 'citibank',
-    usbank: 'us bank',
-    'wells-fargo': 'wf wellsfargo',
-    'td-bank': 'td',
-    column: 'bilt',
-};
-const words = (s) => s
+const searchWords = (s) => s
     .toLowerCase()
     .replace(/\+/g, ' plus ')
     .replace(/&/g, ' and ')
@@ -33,12 +24,12 @@ function editDistance(a, b) {
     }
     return row[b.length] ?? 0;
 }
-function matcher(card) {
+function matcher(catalog, card) {
     const haystack = [
-        ...words(card.id),
-        ...words(card.name),
-        ...words(card.issuer),
-        ...words(ISSUER_NICKNAMES[card.issuer] ?? ''),
+        ...searchWords(card.id),
+        ...searchWords(card.name),
+        ...searchWords(card.issuer),
+        ...(catalog.issuers.find((i) => i.id === card.issuer)?.search ?? []).flatMap(searchWords),
     ];
     const compact = haystack.join('');
     return (token) => haystack.some((w) => w.startsWith(token)) ||
@@ -108,12 +99,12 @@ export function cardInfo(catalog, card, wallet, today) {
 // issuer (as a prefix, or with a typo or two in a long word). With no full
 // match, the cards matching the most words come back instead.
 export function searchCards(catalog, query, wallet, today) {
-    const tokens = words(query);
+    const tokens = searchWords(query);
     const scored = catalog.cards.map((card) => {
-        const matches = matcher(card);
+        const matches = matcher(catalog, card);
         return { card, score: tokens.filter((t) => matches(t)).length };
     });
-    const byShortestId = (a, b) => words(a.card.id).length - words(b.card.id).length ||
+    const byShortestId = (a, b) => searchWords(a.card.id).length - searchWords(b.card.id).length ||
         a.card.id.localeCompare(b.card.id);
     const full = scored.filter((s) => s.score === tokens.length);
     const best = Math.max(0, ...scored.map((s) => s.score));
@@ -131,7 +122,6 @@ export function searchCards(catalog, query, wallet, today) {
         exact,
     };
 }
-const list = (ids) => ids.join(', ');
 // What a card in the wallet still needs before its answers are right.
 export function setupNotes(catalog, wallet, held, today) {
     const card = catalog.cards.find((c) => c.id === held.id);
@@ -145,11 +135,11 @@ export function setupNotes(catalog, wallet, held, today) {
             (staleChoice === null || choice.period === 'until_changed');
         if (current)
             continue;
-        const options = list(Object.keys(choice.options));
+        const options = idList(Object.keys(choice.options));
         notes.push({
             kind: 'pick',
             text: choice.default && picked.has(choice.id)
-                ? `${name}'s ${choice.id} pick is assumed to be ${list(choice.default)}, the default. Set it if a different one was picked (${String(choice.pick)} of: ${options}).`
+                ? `${name}'s ${choice.id} pick is assumed to be ${idList(choice.default)}, the default. Set it if a different one was picked (${String(choice.pick)} of: ${options}).`
                 : `${name} needs its ${choice.id} pick for this period (${String(choice.pick)} of: ${options}). Until then those categories earn the base rate.`,
         });
     }
@@ -158,14 +148,14 @@ export function setupNotes(catalog, wallet, held, today) {
     if (missing.length > 0) {
         notes.push({
             kind: 'membership',
-            text: `Some of ${name}'s rates need a membership: ${list(missing)}. Add any that apply to the wallet's memberships.`,
+            text: `Some of ${name}'s rates need ${listed(missing.map((m) => `${membershipName(catalog, m)} (${m})`), 'or')}; they're counted without it.`,
         });
     }
     const toActivate = activationRules(card, today).filter((id) => !isActivated(card, held, id));
     if (toActivate.length > 0) {
         notes.push({
             kind: 'activation',
-            text: `${name} has rates that apply only once activated with the issuer: ${list(toActivate)}. Mark the ones already activated.`,
+            text: `${name} has rates that apply only once activated with the issuer: ${idList(toActivate)}. Mark the ones already activated.`,
         });
     }
     if (needsAnniversary(card) && held.anniversary === undefined) {