earnrate 0.2.14 → 0.2.16

package/dist/engine/explore.js

@@ -8,7 +8,7 @@ import { FOREIGN_ASSUMPTION, foreignFeeFor, isForeign, recommend, } from "./reco
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
 import { optionName } from "./rule-text.js";
-import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, creditBack, creditThen, earnText, listed, money, PAYMENT_PHRASES, paidText, paymentUnknownText, PICK_PERIODS, pointValuesText, } from "./text.js";
+import { categoryPhrase, choiceName, codesAs, creditBack, creditThen, earnText, listed, PAYMENT_PHRASES, paidText, paymentUnknownText, PICK_PERIODS, pointValuesText, capSentence, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
@@ -117,7 +117,7 @@ function conditionsText(catalog, card, r) {
     if (r.membership !== null)
         conditions.push(`With your ${membershipName(catalog, r.membership)}.`);
     if (r.cap) {
-        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)}.`);
+        conditions.push(`${capSentence(r.cap, earnText(catalog, r.cap.thenRate, r.cap.currency))}.`);
     }
     return conditions;
 }
@@ -223,6 +223,10 @@ export function exploreCards(catalog, query, options, resolved) {
                 ...membershipNeeded(catalog, card, members),
             ],
             evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
+            needsMembership: card.requires_membership !== undefined &&
+                !members.has(card.requires_membership)
+                ? card.requires_membership
+                : null,
             withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
         });
     }
@@ -303,7 +307,7 @@ function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid
 function exploreWarnings(catalog, merchant) {
     const warnings = [];
     if (merchant.source === 'none') {
-        warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. Try a category instead.`);
+        warnings.push(`earnrate doesn't know "${merchant.input}" yet, so only base rates apply. Try a category, or the name of a larger chain.`);
     }
     if (merchant.ambiguity) {
         const alternatives = merchant.ambiguity.mayCodeAs.map((c) => categoryPhrase(catalog, c));

package/dist/engine/intro.js

@@ -1,8 +1,4 @@
-export function addDays(date, days) {
-    const t = new Date(`${date}T00:00:00Z`);
-    t.setUTCDate(t.getUTCDate() + days);
-    return t.toISOString().slice(0, 10);
-}
+import { addDays } from "./periods.js";
 // Never assumed: a card without a date is ranked at its standard rates.
 export const openedOn = (held) => held.opened ?? held.bonus?.opened ?? null;
 // The opening day is day 1, so 365 days run through the day before the first

package/dist/engine/memberships.js

@@ -1,14 +1,10 @@
-import { money, words } from "./text.js";
+import { listed, money, withArticle, words } from "./text.js";
 export function membership(catalog, id) {
     return catalog.memberships.find((m) => m.id === id);
 }
 export function membershipName(catalog, id) {
     return membership(catalog, id)?.name ?? words(id);
 }
-// "a Costco membership", for a sentence.
-function withArticle(name) {
-    return `${/^[aeiou]/i.test(name) ? 'an' : 'a'} ${name}`;
-}
 // Tiers of one membership: holding one, the others in its group aren't
 // missing (BofA Preferred Rewards).
 export function sameGroup(catalog, a, b) {
@@ -54,7 +50,7 @@ export function membershipCosts(catalog, cards, paid) {
 export function membershipText(catalog, id) {
     const m = membership(catalog, id);
     const name = withArticle(m?.name ?? words(id));
-    return m?.annual_fee === undefined
+    return m?.annual_fee === undefined || m.annual_fee === 0
         ? name
         : `${name} (${money(m.annual_fee)} a year)`;
 }
@@ -67,5 +63,5 @@ export function membershipNeeded(catalog, card, paid) {
 }
 export function membershipNote(catalog, m) {
     const names = m.cardIds.map((id) => catalog.cards.find((c) => c.id === id)?.name ?? id);
-    return `${names.join(' and ')} ${names.length === 1 ? 'needs' : 'need'} ${withArticle(m.name)}, ${money(m.annualFee)} a year, counted here like an annual fee. If you're already a member, add it to your memberships.`;
+    return `${listed(names)} ${names.length === 1 ? 'needs' : 'need'} ${withArticle(m.name)}, ${money(m.annualFee)} a year, counted here like an annual fee. If you're already a member, add it to your memberships.`;
 }

package/dist/engine/offers.js

@@ -2,17 +2,15 @@ import { bonusDollars } from "./bonus.js";
 import { matchesFilters } from "./explore.js";
 import { membershipCosts, paidMemberships } from "./memberships.js";
 import { inEffect } from "./periods.js";
-import { CREDITS_LEFT_OUT, money, roundCents } from "./text.js";
+import { CREDITS_LEFT_OUT, heldName, listed, money, roundCents, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 function ineligibleText(catalog, wallet, notWith) {
     const held = wallet.cards
         .filter((c) => notWith.includes(c.id))
-        .map((c) => c.checkout_label ??
-        catalog.cards.find((k) => k.id === c.id)?.name ??
-        c.id);
+        .map((c) => heldName(catalog, c));
     return held.length === 0
         ? null
-        : `Likely not eligible: you hold ${held.join(' and ')}, and the issuer's terms rule out its cardholders.`;
+        : `Likely not eligible: you hold ${listed(held)}, and the issuer's terms rule out its cardholders.`;
 }
 export const OFFERS_MAY_DIFFER = 'Yours may differ: issuers test and target offers, so use the one shown to you when you apply.';
 // "Up to 60,000 Chase Ultimate Rewards after $4,000 in purchases within 3

package/dist/engine/periods.js

@@ -23,6 +23,11 @@ export function periodKey(period, date, anniversary) {
 export function daysBetween(from, to) {
     return Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000);
 }
+export function addDays(date, days) {
+    const t = new Date(`${date}T00:00:00Z`);
+    t.setUTCDate(t.getUTCDate() + days);
+    return t.toISOString().slice(0, 10);
+}
 // The user's local calendar date, not UTC: a purchase at 9pm in Los Angeles
 // belongs to that day.
 export function localToday(now = new Date()) {

package/dist/engine/profiles.js

@@ -1,3 +1,4 @@
+import { listed } from "./text.js";
 export const VALUATION_PROFILES = {
     flat: { MR: 1.0, UR: 1.0 },
     'points-heavy': { MR: 1.7, UR: 1.7 },
@@ -7,7 +8,7 @@ export function profileText(profile) {
     const values = Object.entries(VALUATION_PROFILES[profile]);
     const cents = [...new Set(values.map(([, v]) => v))];
     return cents.length === 1
-        ? `${values.map(([id]) => id).join(' and ')} at ${String(cents[0])}¢`
+        ? `${listed(values.map(([id]) => id))} at ${String(cents[0])}¢`
         : values.map(([id, v]) => `${id} at ${String(v)}¢`).join(', ');
 }
 export function isValuationProfile(name) {

package/dist/engine/recommend.js

@@ -9,7 +9,7 @@ import { creditAt, creditDollars } from "./credits.js";
 import { ruleWhat } from "./rule-text.js";
 import { rotationGap } from "./rotation.js";
 import { EPSILON, isClose } from "./compare.js";
-import { CAP_ADJECTIVES, categoryPhrase, creditAnswerText, codesAs, currencyLabel, currencyName, earnText, introRateText, introUnknownText, listed, money, NETWORK_NAMES, num, paidText, paymentUnknownText, pct, pointValuesText, roundCents, shortDate, wholeDollars, possessive, } from "./text.js";
+import { CAP_ADJECTIVES, categoryPhrase, creditAnswerText, codesAs, currencyLabel, currencyName, earnText, heldName, introRateText, introUnknownText, listed, money, NETWORK_NAMES, num, paidText, paymentUnknownText, pct, pointValuesText, roundCents, shortDate, wholeDollars, possessive, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 export const STALE_AFTER_DAYS = 180;
 // The engine only tells the U.S. from everywhere else.
@@ -17,7 +17,7 @@ export const FOREIGN_ASSUMPTION = 'Treats this as a purchase outside the U.S.: e
 export const isForeign = (purchase) => purchase.country !== 'US';
 // A fee that isn't on file counts as the usual 3%, so a card can't win
 // abroad on a guess that it charges none.
-export const ASSUMED_FOREIGN_FEE = 3;
+const ASSUMED_FOREIGN_FEE = 3;
 export const foreignFeeFor = (card, purchase) => isForeign(purchase)
     ? (card.foreign_transaction_fee ?? ASSUMED_FOREIGN_FEE)
     : 0;
@@ -149,7 +149,7 @@ function reasoningFor(catalog, wallet, entry, amount) {
     const standard = earnText(catalog, intro ? best.standardRate : best.nominalRate, currency);
     if (best.rule) {
         const note = best.rule.note ? ` ${best.rule.note}` : '';
-        lines.push(`${standard} on ${ruleWhat(catalog, best.rule)}${best.rule.requires?.membership === undefined ? '' : `, with ${membershipName(catalog, best.rule.requires.membership)}`}.${note}`);
+        lines.push(`${standard} on ${ruleWhat(catalog, best.rule, card)}${best.rule.requires?.membership === undefined ? '' : `, with ${membershipName(catalog, best.rule.requires.membership)}`}.${note}`);
     }
     else {
         lines.push(`${standard}, its base rate. No bonus category applies here.`);
@@ -169,10 +169,8 @@ function reasoningFor(catalog, wallet, entry, amount) {
         const partners = card.pools_into?.when_wallet_has ?? [];
         const heldPartners = wallet.cards
             .filter((h) => partners.includes(h.id))
-            .map((h) => h.checkout_label ??
-            catalog.cards.find((c) => c.id === h.id)?.name ??
-            h.id);
-        lines.push(`Pools into ${currencyName(catalog, currency)} because you hold ${heldPartners.join(' and ')}.`);
+            .map((h) => heldName(catalog, h));
+        lines.push(`Pools into ${currencyName(catalog, currency)} because you hold ${listed(heldPartners)}.`);
     }
     if (currency !== 'cash') {
         lines.push(`Valued at ${num(valuation.centsPerUnit)}¢ per point: ${pct(entry.evaluation.best.rate * valuation.centsPerUnit)} back.`);
@@ -196,17 +194,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 ${ruleWhat(catalog, best.rule)}: only ${money(remaining)} is left for ${period}.`);
+            warnings.push(`This purchase crosses the ${capLabel(best)} on ${ruleWhat(catalog, best.rule, card)}: 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 ${ruleWhat(catalog, best.rule)} for ${period}.`);
+            warnings.push(`Only ${money(remaining)} left of the ${capLabel(best)} on ${ruleWhat(catalog, best.rule, card)} for ${period}.`);
         }
     }
     if (nominal.rule &&
         nominal.cap &&
         nominal !== best &&
         nominal.cap.remaining === 0) {
-        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.`);
+        warnings.push(`The ${capLabel(nominal)} on ${ruleWhat(catalog, nominal.rule, card)} 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}`);
@@ -275,7 +273,7 @@ function tieNote(entries) {
     const first = tied[0];
     if (!first)
         return null;
-    const names = tied.map(displayName).join(' and ');
+    const names = listed(tied.map(displayName));
     const verb = tied.length === 1 ? 'earns' : 'earn';
     const why = winner.upside - first.upside > EPSILON
         ? 'because its points can be worth more'
@@ -285,11 +283,11 @@ function tieNote(entries) {
             : 'by a fixed order; either works';
     return `${names} also ${verb} ${pct(winner.rateReturnPct)} here. ${displayName(winner)} wins the tie ${why}.`;
 }
+// "Chase Ultimate Rewards points", but not "IHG One Rewards points points".
+const pointsName = (label) => /\b(points|miles)$/i.test(label) ? label : `${label} points`;
 // 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
 // cents-per-point value, so each pair of cards flips at most once.
-// "Chase Ultimate Rewards points", but not "IHG One Rewards points points".
-const pointsName = (label) => /\b(points|miles)$/i.test(label) ? label : `${label} points`;
 function sensitivity(catalog, entries) {
     const [winner, ...rest] = entries;
     if (!winner)
@@ -338,7 +336,7 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
             const rule = e.evaluation.best.rule;
             return rule &&
                 merchantFamily(catalog, merchant.merchantId).some((id) => (rule.match.merchants ?? []).includes(id))
-                ? [`${displayName(e)} (${ruleWhat(catalog, rule)})`]
+                ? [`${displayName(e)} (${ruleWhat(catalog, rule, e.card)})`]
                 : [];
         });
         assumptions.push(naming.length === 0
@@ -488,9 +486,13 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
     const ties = !isBest && gap <= EPSILON;
     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 ${pct(open.entry.rateReturnPct)} 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 toGo = open
+        ? `${money(open.status.remaining ?? 0)} more by ${open.status.deadline ?? ''}`
+        : '';
+    if (open && isBest && !bonus)
+        notes.push(`${displayName(open.entry)} is the best card here anyway, and this counts toward its welcome bonus (${toGo}).`);
+    else if (open && !bonus && isClose(open.entry.effectiveReturnPct, best))
+        notes.push(`${displayName(open.entry)} earns ${pct(open.entry.rateReturnPct)} here, ${num(gap)} ${gap === 1 ? 'point' : 'points'} less than ${pct(best)}, and would help its welcome bonus (${toGo}). 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.
     const tie = bonus ? null : tieNote(entries);

package/dist/engine/record.js

@@ -80,7 +80,7 @@ export function applyBonusBooking(wallet, b) {
 }
 // Every purchase on a card counts toward each of its spend milestones. None
 // for a cardmember-year milestone on a card with no anniversary.
-export function milestoneBookings(catalog, wallet, purchase) {
+function milestoneBookings(catalog, wallet, purchase) {
     const held = wallet.cards.find((c) => c.id === purchase.cardId);
     const card = catalog.cards.find((c) => c.id === purchase.cardId);
     if (!held || !card)

package/dist/engine/rule-text.js

@@ -1,5 +1,5 @@
 import { findMerchant } from "../merchants/resolve.js";
-import { categoryPhrase, categoryReadsOn, choiceName, earnText, introPeriod, listed, num, PAYMENT_PHRASES, words, } from "./text.js";
+import { categoryPhrase, categoryReadsOn, choiceName, earnText, introPeriod, listed, num, PAYMENT_PHRASES, PICK_PERIODS, 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.
@@ -22,51 +22,99 @@ export function optionName(catalog, card, choiceId, option) {
         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)
+// What a rule covers, as a list of phrases. With the card, a pick reads
+// "the 2 categories you pick each quarter" and a rule for every purchase reads
+// "every purchase" when it's the card's only one.
+export function ruleParts(catalog, rule, card, { everyStore = false } = {}) {
+    const m = rule.match;
+    if (m.any)
         return [
             rule.geography === 'foreign_only'
                 ? 'purchases outside the U.S.'
                 : rule.requires?.payment !== undefined
                     ? 'purchases'
-                    : 'everything else',
+                    : card?.rules.every((r) => r.match.any)
+                        ? 'every purchase'
+                        : 'everything else',
         ];
-    if (rule.match.choice !== undefined)
-        return [`your ${choiceName(rule.match.choice)} picks`];
-    const merchants = rule.match.merchants ?? [];
-    // A long list of mostly one kind of store reads as "select streaming
-    // services": Amex's streaming list also names Audible, which isn't one.
+    if (m.choice !== undefined) {
+        const choice = card?.choices.find((c) => c.id === m.choice);
+        if (!choice)
+            return [`your ${choiceName(m.choice)} picks`];
+        const which = choice.pick === 1
+            ? 'the category'
+            : `the ${String(choice.pick)} categories`;
+        return [
+            `${which} you pick${choice.period === 'until_changed' ? '' : ` ${PICK_PERIODS[choice.period]}`}`,
+        ];
+    }
+    const merchants = m.merchants ?? [];
+    const categories = (m.categories ?? []).map((c) => categoryPhrase(catalog, c));
+    const merchantParts = (everyStore ? null : shortenedMerchants(catalog, merchants)) ??
+        merchants.map((id) => merchantName(catalog, id));
+    // A rule naming both matches a purchase that is both.
+    if (merchants.length > 0 && categories.length > 0)
+        return [`${listed(merchantParts)} when it codes as ${listed(categories)}`];
+    const parts = [...categories, ...(merchants.length > 0 ? merchantParts : [])];
+    if (parts.length > 0)
+        return parts;
+    return m.mccs?.length
+        ? [`purchases coded MCC ${m.mccs.map(String).join(', ')}`]
+        : [words(rule.id)];
+}
+// A long list of mostly one kind of store reads as "select streaming
+// services": Amex's streaming list also names Audible, which isn't one.
+// Null when the list is read out in full.
+function shortenedKind(catalog, merchants) {
     const counts = new Map();
-    for (const m of merchants) {
-        const category = findMerchant(catalog, m)?.category;
+    for (const id of merchants) {
+        const category = findMerchant(catalog, id)?.category;
         if (category)
             counts.set(category, (counts.get(category) ?? 0) + 1);
     }
     const [kind, count = 0] = [...counts].sort((a, b) => b[1] - a[1])[0] ?? [];
-    const merchantParts = merchants.length > 4 &&
+    return merchants.length > 4 &&
         kind !== undefined &&
         count >= merchants.length * 0.75
-        ? [`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)];
+        ? kind
+        : null;
 }
-export function ruleWhat(catalog, rule) {
+export function shortenedMerchants(catalog, merchants) {
+    const kind = shortenedKind(catalog, merchants);
+    return kind === null ? null : [`select ${categoryPhrase(catalog, kind)}`];
+}
+export function ruleWhat(catalog, rule, card, options = {}) {
     const payment = rule.requires?.payment;
-    const what = listed(ruleParts(catalog, rule));
+    const what = listed(ruleParts(catalog, rule, card, options));
     return payment === undefined ? what : `${what} ${PAYMENT_PHRASES[payment]}`;
 }
+// "on dining", "on your picks", "at Costco", "on Walmart+ membership": a
+// category's own preposition, "at" for a store unless its data says "on" or
+// it's a booking through a travel site ("on hotels through Amex Travel"), and
+// a shortened list ("select streaming services") reads like its kind.
+export function rulePreposition(catalog, rules) {
+    const readsOn = (r) => {
+        if (r.match.any === true || r.match.choice !== undefined)
+            return true;
+        const merchants = r.match.merchants ?? [];
+        const kind = shortenedKind(catalog, merchants);
+        return ((r.match.categories ?? []).every((c) => categoryReadsOn(catalog, c)) &&
+            (kind !== null
+                ? categoryReadsOn(catalog, kind)
+                : merchants.every((id) => {
+                    const merchant = findMerchant(catalog, id);
+                    return (merchant?.preposition === 'on' || merchant?.kind === 'booking');
+                })));
+    };
+    return rules.length > 0 && rules.every(readsOn) ? 'on' : 'at';
+}
 // "double every rate for the first year", "an extra 3% cash back on your 3%
 // picks for the first year".
 export function introWhat(catalog, card, intro) {
     const covered = card.rules.filter((r) => intro.rules?.includes(r.id));
     const on = intro.rules === undefined
         ? 'every rate'
-        : [...new Set(covered.map((r) => ruleWhat(catalog, r)))].join('; ');
+        : [...new Set(covered.map((r) => ruleWhat(catalog, r, card)))].join('; ');
     const change = intro.multiply === undefined
         ? `an extra ${earnText(catalog, intro.add ?? 0, card.currency)} on ${on}`
         : intro.multiply === 2

package/dist/engine/setup.js

@@ -77,6 +77,10 @@ export function cardInfo(catalog, card, wallet, today) {
         network: card.network,
         currency: card.currency,
         annualFee: card.annual_fee ?? null,
+        firstYearFee: card.first_year_fee !== undefined &&
+            card.first_year_fee !== card.annual_fee
+            ? card.first_year_fee
+            : null,
         foreignTransactionFee: card.foreign_transaction_fee,
         business: card.business,
         onlyAt: card.only_at ?? null,

package/dist/engine/text.js

@@ -48,6 +48,11 @@ export function feeText(fees) {
         return `${money(annualFee)} annual fee (${firstYearFee === 0 ? 'waived' : money(firstYearFee)} the first year)`;
     return `${money(annualFee)} annual fee`;
 }
+export function heldName(catalog, held) {
+    return (held.checkout_label ??
+        catalog.cards.find((c) => c.id === held.id)?.name ??
+        held.id);
+}
 export function currencyName(catalog, id) {
     return catalog.currencies.find((c) => c.id === id)?.name ?? id;
 }
@@ -129,6 +134,18 @@ export function paymentNote(cards) {
 }
 // A name with its own "and" ("drugstores and pharmacies") would run into the
 // list's: those lists use commas only, with those names last.
+// "Up to $1,500 of spending a quarter, then 1% cash back"
+export const capSentence = (cap, then, of = 'spending', aside = '') => `Up to ${wholeDollars(cap.amount)} of ${of} ${CAP_PERIODS[cap.period]}${aside}, then ${then}`;
+// "a Costco membership", "an Instacart credit", "an IHG card", "a Uber credit":
+// by sound, so a leading "you" or "won" takes "a" and a letter said with a
+// vowel sound ("an REI") takes "an".
+export function withArticle(name) {
+    const initialism = /^[A-Z][A-Z&.-]{1,5}(?![a-z])/.test(name);
+    const an = initialism
+        ? /^[AEFHILMNORSX]/.test(name)
+        : /^[aeiou]/i.test(name) && !/^(u[bnst]|u\.s\.|eu|one\b|once\b)/i.test(name);
+    return `${an ? 'an' : 'a'} ${name}`;
+}
 // "Amex Platinum's", "Capital One Savor Rewards'".
 export const possessive = (name) => name.endsWith('s') ? `${name}'` : `${name}'s`;
 export const listed = (parts, joiner = 'and') => {
@@ -168,7 +185,7 @@ export const CAP_ADJECTIVES = {
     calendar_year: 'calendar-year',
     cardmember_year: 'cardmember-year',
 };
-// "the $15,000 calendar-year spend", for a spend milestone.
+// "the $15,000 calendar-year spend", for a spend bonus.
 export const MILESTONE_PERIODS = {
     calendar_year: 'calendar-year',
     cardmember_year: 'cardmember-year',
@@ -190,7 +207,7 @@ export const introRateText = (earn, standard, days, until) => `${earn} in your $
 // For a card whose opening date isn't known: it's never assumed to be new.
 export const introUnknownText = (name, earn, standard, days) => `A ${introAdjective(days)} rate may apply on ${name}: ${earn} here in an account's ${introPeriod(days)}, instead of the ${standard} it's ranked at. Give the card's opening date if it opened ${introSince(days)}.`;
 export const introEndsText = (name, days, until) => `${possessive(name)} ${introAdjective(days)} rate ends after ${shortDate(until)}; from then on it earns its standard rates.`;
-// Merchant statement credits. Always dollars, never a percentage.
+// Statement credits. Always dollars, never a percentage.
 export const CREDIT_PERIODS = {
     month: 'each month',
     quarter: 'each quarter',
@@ -207,7 +224,7 @@ export const CREDIT_THIS_PERIOD = {
 };
 export const ENROLL_FIRST = 'enroll first';
 // The group of cards with a credit at the store, shown before the ranking.
-export const CREDIT_GROUP = 'With a store credit';
+export const CREDIT_GROUP = 'With a statement credit';
 // "$75 back each quarter"
 export const creditBack = (c) => `${money(c.amount)} back ${CREDIT_PERIODS[c.period]}`;
 // "$75 back each quarter, then 1x Amex Membership Rewards"
@@ -218,9 +235,9 @@ export const creditLeft = (left, period) => `${money(left)} left ${CREDIT_THIS_P
 export function creditAnswerText(c, dollars) {
     const credit = `${c.name} credit (${creditBack(c)})`;
     if (!c.enrolled)
-        return `Has a ${credit} here; ${ENROLL_FIRST} with the issuer, then mark it enrolled in your wallet. It isn't counted until then.`;
+        return `Has ${withArticle(credit)} here; ${ENROLL_FIRST} with the issuer, then mark it enrolled in your wallet. It isn't counted until then.`;
     if (c.left === null)
-        return `Has a ${credit} here; give the card's anniversary to track it.`;
+        return `Has ${withArticle(credit)} here; give the card's anniversary to track it.`;
     if (c.left <= 0)
         return `Its ${c.name} credit is used up ${CREDIT_THIS_PERIOD[c.period]}${c.until === null ? '' : `; it renews after ${shortDate(c.until)}`}.`;
     if (dollars === null)
@@ -249,4 +266,4 @@ export const enrollCreditText = (card, names) => names.length === 1
     ? `Enroll in ${possessive(card)} ${names[0] ?? ''} credit with the issuer, then mark it enrolled.`
     : `Enroll in ${possessive(card)} ${listed(names)} credits with the issuer, then mark them enrolled.`;
 // Simulations, the cheat sheet and welcome-offer comparisons.
-export const CREDITS_LEFT_OUT = 'Merchant statement credits (dollars back at a named store) are left out.';
+export const CREDITS_LEFT_OUT = 'Statement credits (dollars back at a named store) are left out.';

package/dist/engine/wallet-change.js

@@ -134,15 +134,15 @@ export function cardFields(card, held, input, today) {
             const milestone = card.milestones.find((m) => m.id === id);
             if (!milestone) {
                 problems.push(card.milestones.length > 0
-                    ? `${card.id} has no spend milestone '${id}'. Its milestones are: ${idList(card.milestones.map((m) => m.id))}.`
-                    : `${card.id} has no spend milestones.`);
+                    ? `${card.id} has no spend bonus '${id}'. Its milestones are: ${idList(card.milestones.map((m) => m.id))}.`
+                    : `${card.id} has no spend bonuses.`);
                 continue;
             }
             if (!(spent >= 0))
-                problems.push('Spending toward a milestone must be $0 or more.');
+                problems.push('Spending toward a spend bonus must be $0 or more.');
             const period = periodKey(milestone.period, today, anniversary);
             if (period === null) {
-                problems.push(`The '${id}' milestone resets on the card's anniversary; give the anniversary (MM-DD) too.`);
+                problems.push(`The '${id}' spend bonus resets on the card's anniversary; give the anniversary (MM-DD) too.`);
                 continue;
             }
             usage[id] = { period, spent };
@@ -169,7 +169,7 @@ export function cardFields(card, held, input, today) {
             if (!credit) {
                 problems.push(card.credits.length > 0
                     ? `${card.id} has no credit '${id}'. Its credits are: ${idList(card.credits.map((c) => c.id))}.`
-                    : `${card.id} has no merchant credits.`);
+                    : `${card.id} has no statement credits.`);
                 continue;
             }
             if (!(used >= 0 && used <= credit.amount))

package/dist/engine/wallet-summary.js

@@ -4,12 +4,12 @@ import { introUntil, introWindows, openedOn } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestoneSummaries } from "./milestones.js";
 import { creditStates } from "./credits.js";
-import { creditWhere, optionName, ruleParts } from "./rule-text.js";
+import { creditWhere, optionName, ruleParts, rulePreposition, } from "./rule-text.js";
 import { choicePeriod, daysBetween, inEffect, periodEnd } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { activationRules } from "./setup.js";
-import { CAP_PERIODS, categoryReadsOn, creditBack, creditLeft, ENROLL_FIRST, choiceName, currencyLabel, earnText, listed, PAYMENT_PHRASES, shortDate, wholeDollars, words, } from "./text.js";
+import { CAP_PERIODS, creditBack, creditLeft, ENROLL_FIRST, choiceName, currencyLabel, earnText, listed, PAYMENT_PHRASES, shortDate, wholeDollars, words, } from "./text.js";
 import { cardValuation, currencyValuation } from "./valuation.js";
 const matchKeys = (rule) => rule.match.choice !== undefined
     ? []
@@ -30,11 +30,9 @@ function capLimit(card, shown, rule) {
         shown.filter((r) => r.cap === rule.cap).length > 1;
     return `first ${wholeDollars(cap.amount)} ${CAP_PERIODS[cap.period]}${shared ? ', combined' : ''}`;
 }
-// Every bonus rate the cardholder gets now, best first, so none reads as the
-// base rate. Rates behind a membership the wallet lacks are left out, and so
-// is a lower tier that an uncapped, always-on higher rate fully covers (Prime
-// Visa's 3% without Prime, once Prime is held). Rules at the same rate share
-// a line.
+// Best first. Leaves out rates behind a membership the wallet lacks and a
+// lower tier an uncapped, always-on higher rate fully covers (Prime Visa's 3%
+// without Prime, once Prime is held). Rules at the same rate share a line.
 function headlineRates(catalog, wallet, card, held, currency, today) {
     const shown = card.rules
         .filter((r) => inEffect(r, today) &&
@@ -65,22 +63,18 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
         const pending = r.requires?.activation && !isActivated(card, held, r.id);
         const payment = r.requires?.payment;
         const key = [
-            `${earnText(catalog, r.rate, currency)} on`,
+            earnText(catalog, r.rate, currency),
             capLimit(card, shown, r),
             pending ? ', once activated' : '',
             payment === undefined ? '' : ` ${PAYMENT_PHRASES[payment]}`,
         ].join('|');
-        const whats = lines.get(key) ?? [];
-        for (const part of ruleParts(catalog, r))
-            if (!whats.includes(part))
-                whats.push(part);
-        lines.set(key, whats);
+        lines.set(key, [...(lines.get(key) ?? []), r]);
     }
     return [
-        ...[...lines].map(([key, whats]) => {
+        ...[...lines].map(([key, rules]) => {
             const [head = '', limit = '', activate = '', paid = ''] = key.split('|');
             const after = `${limit}${activate}`;
-            return `${head} ${listed(whats)}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
+            return `${head} ${wherePhrase(catalog, card, rules)}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
         }),
         ...(shown.some((r) => r.match.any &&
             r.geography !== 'foreign_only' &&
@@ -92,6 +86,22 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
 }
 // Bonuses current or starting soon that the card hasn't activated, one per
 // activation group (one activation covers a quarter's categories).
+// "at gas stations and restaurants, and on transit": each rule's parts after
+// its own preposition, the "at" ones first.
+export function wherePhrase(catalog, card, rules) {
+    const parts = { at: [], on: [] };
+    for (const r of rules) {
+        const list = parts[rulePreposition(catalog, [r])];
+        for (const part of ruleParts(catalog, r, card))
+            if (!list.includes(part))
+                list.push(part);
+    }
+    const { at, on } = parts;
+    return [
+        ...(at.length > 0 ? [`at ${listed(at)}`] : []),
+        ...(on.length > 0 ? [`on ${listed(on)}`] : []),
+    ].join(at.length > 1 ? ', and ' : ' and ');
+}
 export function activationsDue(catalog, card, held, today) {
     const seen = new Set();
     const out = [];
@@ -103,13 +113,11 @@ export function activationsDue(catalog, card, held, today) {
             seen.add(g);
         const rules = card.rules.filter((r) => group.includes(r.id));
         const first = rules[0];
-        const categories = rules.flatMap((r) => r.match.categories ?? []);
-        const servicesOnly = categories.length > 0 &&
-            rules.every((r) => (r.match.merchants ?? []).length === 0) &&
-            categories.every((c) => categoryReadsOn(catalog, c));
         out.push({
-            what: listed([...new Set(rules.flatMap((r) => ruleParts(catalog, r)))]),
-            preposition: servicesOnly ? 'on' : 'at',
+            what: listed([
+                ...new Set(rules.flatMap((r) => ruleParts(catalog, r, card))),
+            ]),
+            where: wherePhrase(catalog, card, rules),
             from: first?.valid_from ?? null,
             to: first?.valid_to ?? null,
             activateBy: first?.activate_by ?? null,
@@ -154,8 +162,9 @@ function capSummaries(catalog, card, held, today) {
         const shared = card.caps.find((c) => c.id === key);
         const label = shared?.rotating
             ? 'the rotating bonus categories'
-            : listed([...new Set(covered.flatMap((r) => ruleParts(catalog, r)))]) ||
-                words(key);
+            : listed([
+                ...new Set(covered.flatMap((r) => ruleParts(catalog, r, card))),
+            ]) || words(key);
         return {
             key,
             label,