earnrate 0.2.13 → 0.2.15

package/dist/engine/recommend.js

@@ -1,7 +1,7 @@
 import { findMerchant, merchantFamily, resolveMerchant, resolveMerchantById, } from "../merchants/resolve.js";
 import { bonusStatus } from "./bonus.js";
 import { evaluateCard, paymentUpgrade, purchaseContext, usableAt, } from "./evaluate.js";
-import { openedOn } from "./intro.js";
+import { introWindows, openedOn, withIntro } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestonePoints, milestonesReached, reachedText, } from "./milestones.js";
 import { daysBetween } from "./periods.js";
@@ -9,12 +9,18 @@ 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, } 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.
 export const FOREIGN_ASSUMPTION = 'Treats this as a purchase outside the U.S.: each card is ranked after its foreign transaction fee.';
 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.
+const ASSUMED_FOREIGN_FEE = 3;
+export const foreignFeeFor = (card, purchase) => isForeign(purchase)
+    ? (card.foreign_transaction_fee ?? ASSUMED_FOREIGN_FEE)
+    : 0;
 // Any purchase outside the U.S., when no country is named: ZZ is a code ISO
 // leaves unassigned, and nothing prints it.
 export const ABROAD = 'ZZ';
@@ -79,8 +85,7 @@ function rankEntries(catalog, wallet, purchase, merchant, category, options = {}
         const bonusPoints = milestonePoints(milestones);
         const perDollar = evaluation.best.rate +
             (bonusPoints > 0 && purchase.amount ? bonusPoints / purchase.amount : 0);
-        // An unknown fee isn't guessed: it's warned about instead.
-        const fee = isForeign(purchase) ? (card.foreign_transaction_fee ?? 0) : 0;
+        const fee = foreignFeeFor(card, purchase);
         const fresh = card.intro_rates.length > 0 && openedOn(held) === null
             ? evaluateCard(card, { ...held, opened: purchase.date }, ctx).best
             : null;
@@ -138,18 +143,19 @@ function reasoningFor(catalog, wallet, entry, amount) {
     const { best } = evaluation;
     const lines = [];
     const currency = valuation.currency;
+    // The standard rate first; a first-year rate on top of it is its own line.
+    // The intro's terms stay in search_cards, not in every answer.
+    const [intro] = best.intro;
+    const standard = earnText(catalog, intro ? best.standardRate : best.nominalRate, currency);
     if (best.rule) {
         const note = best.rule.note ? ` ${best.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}`);
+        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(`${earnText(catalog, best.nominalRate, currency)}, its base rate. No bonus category applies here.`);
-    }
-    const [intro] = best.intro;
-    if (intro) {
-        const note = intro.intro.note ? ` ${intro.intro.note}` : '';
-        lines.push(`${introRateText(earnText(catalog, best.nominalRate, currency), earnText(catalog, best.standardRate, currency), intro.intro.days, intro.until)}${note}`);
+        lines.push(`${standard}, its base rate. No bonus category applies here.`);
     }
+    if (intro)
+        lines.push(introRateText(earnText(catalog, best.nominalRate, currency), standard, intro.intro.days, intro.until));
     const cap = best.cap;
     if (cap && amount !== null && amount > cap.remaining) {
         const over = amount - cap.remaining;
@@ -163,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.`);
@@ -177,10 +181,10 @@ function warningsFor(catalog, entry, purchase) {
     const { card, valuation, evaluation } = entry;
     const { best, nominal } = evaluation;
     const warnings = [];
-    if (entry.fee > 0)
-        warnings.push(`Charges a ${pct(entry.fee)} foreign transaction fee here, so it nets ${pct(entry.rateReturnPct)}.`);
     if (isForeign(purchase) && card.foreign_transaction_fee === null)
-        warnings.push("Its foreign transaction fee isn't on file, so none is subtracted. Check the issuer's terms before using it abroad.");
+        warnings.push(`Its foreign transaction fee isn't on file, so earnrate assumes the usual ${pct(entry.fee)} and it nets ${pct(entry.rateReturnPct)}. Check the issuer's terms before using it abroad.`);
+    else if (entry.fee > 0)
+        warnings.push(`Charges a ${pct(entry.fee)} foreign transaction fee here, so it nets ${pct(entry.rateReturnPct)}.`);
     const capLabel = (e) => e.cap
         ? `${money(e.cap.cap.amount)} ${CAP_ADJECTIVES[e.cap.cap.period]} cap`
         : '';
@@ -190,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}`);
@@ -212,12 +216,14 @@ function warningsFor(catalog, entry, purchase) {
     if (evaluation.staleChoice !== null) {
         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.`);
     }
+    const windows = introWindows(card, entry.held, purchase.date);
     for (const rule of evaluation.needsActivation) {
+        const rate = earnText(catalog, withIntro(rule.rate, rule.id, windows), valuation.currency);
         if (rule.activate_by !== undefined && rule.activate_by < purchase.date) {
-            warnings.push(`The bonus here (${earnText(catalog, rule.rate, valuation.currency)}) needed activating by ${shortDate(rule.activate_by)}.`);
+            warnings.push(`The bonus here (${rate}) needed activating by ${shortDate(rule.activate_by)}.`);
             continue;
         }
-        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)}`}.`);
+        warnings.push(`Activate this bonus with the issuer (it's free)${rule.activate_by === undefined ? '' : ` by ${shortDate(rule.activate_by)}`} to earn ${rate} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
     }
     return warnings;
 }
@@ -267,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'
@@ -277,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)
@@ -330,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
@@ -389,9 +395,12 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
     const winner = entries[0];
     const warnings = [];
     const notes = [];
-    const charging = entries.filter((e) => e.fee > 0);
+    const charging = entries.filter((e) => e.fee > 0 && e.card.foreign_transaction_fee !== null);
+    const assumed = entries.filter((e) => e.fee > 0 && e.card.foreign_transaction_fee === null);
     if (charging.length > 0 && entries.length > 1)
         notes.push(`${listed(charging.map((e) => `${displayName(e)} (${pct(e.fee)})`))} ${charging.length === 1 ? 'charges a foreign transaction fee' : 'charge foreign transaction fees'} here, already subtracted in the ranking.`);
+    if (assumed.length > 0 && entries.length > 1)
+        notes.push(`${listed(assumed.map(displayName))} ${assumed.length === 1 ? 'has' : 'have'} no foreign transaction fee on file, so the usual ${pct(ASSUMED_FOREIGN_FEE)} is subtracted.`);
     if (merchant.source === 'none') {
         warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. If you know what kind of business it is, give its category (like dining or grocery) to find bonus rates.`);
     }
@@ -453,7 +462,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const gap = card ? rotationGap(card, purchase.date) : null;
         if (card && gap !== null) {
             const name = held.checkout_label ?? card.name;
-            warnings.push(`${name}'s rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them. If this purchase is in that period's categories, ${name} may earn more. An earnrate update adds them once the issuer announces them.`);
+            warnings.push(`${possessive(name)} rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them. If this purchase is in that period's categories, ${name} may earn more. An earnrate update adds them once the issuer announces them.`);
         }
     }
     for (const id of merchant.bookedVia) {
@@ -477,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);
@@ -516,7 +529,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const worth = status.value === null ? '' : `, worth about ${wholeDollars(status.value)}`;
         notes.unshift(ties
             ? `${displayName(bonus.entry)} earns as much here as any of your cards, so it's the pick: it helps its welcome bonus, ${money(remaining)} more to spend by ${deadline}${worth}.`
-            : `You're behind pace on ${displayName(bonus.entry)}'s welcome bonus: ${money(remaining)} more to spend by ${deadline}${pace}${worth}.${isBest
+            : `You're behind pace on ${possessive(displayName(bonus.entry))} welcome bonus: ${money(remaining)} more to spend by ${deadline}${pace}${worth}.${isBest
                 ? ''
                 : costHere === null
                     ? ` It earns ${pct(top.effectiveReturnPct)} here against ${pct(first.effectiveReturnPct)} on ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`

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)
@@ -96,6 +96,7 @@ export function milestoneBookings(catalog, wallet, purchase) {
                 spend: p.milestone.spend,
                 before: p.spent,
                 after: roundCents(Math.max(0, p.spent + purchase.amount)),
+                started: !p.tracked,
             },
         ]);
 }

package/dist/engine/rotation.js

@@ -1,4 +1,5 @@
 import { periodKey } from "./periods.js";
+import { possessive } from "./text.js";
 // The period of the card's rotating categories that `date` falls in, when no
 // rule in the data covers it yet; null when it's covered or the card doesn't
 // rotate.
@@ -16,4 +17,4 @@ export function rotationGap(card, date) {
 }
 // What answers say about a gap: "Freedom Flex's rotating categories for
 // 2027-Q2 aren't in earnrate's data yet. ..."
-export const rotationGapText = (name, gap) => `${name}'s rotating categories for ${gap} aren't in earnrate's data yet. An earnrate update adds them once the issuer announces them.`;
+export const rotationGapText = (name, gap) => `${possessive(name)} rotating categories for ${gap} aren't in earnrate's data yet. An earnrate update adds them once the issuer announces them.`;

package/dist/engine/rule-text.js

@@ -1,15 +1,14 @@
 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.
-const BOOKING = /^(Attraction|Car rental|Cruise|Flight|Hotel|Vacation rental)\b/;
+const BOOKING = /^(Activity|Attraction|Car rental|Cruise|Flight|Hotel|Vacation rental)\b/;
+const plural = (kind) => kind === 'Activity' ? 'activities' : `${kind.toLowerCase()}s`;
 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;
+    return merchant?.kind === 'booking' ? name.replace(BOOKING, plural) : name;
 }
 export function optionName(catalog, card, choiceId, option) {
     const o = card.choices.find((c) => c.id === choiceId)?.options[option];
@@ -23,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 shortenedMerchants(catalog, merchants) {
+    const kind = shortenedKind(catalog, merchants);
+    return kind === null ? null : [`select ${categoryPhrase(catalog, kind)}`];
 }
-export function ruleWhat(catalog, rule) {
+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
@@ -76,9 +123,27 @@ export function introWhat(catalog, card, intro) {
     return `${change} for the ${introPeriod(intro.days)}`;
 }
 // What a merchant credit is named for: "Lululemon", "Disney+, Hulu and ESPN".
-export const creditName = (catalog, credit) => listed([
-    ...(credit.match.merchants ?? []).map((m) => merchantName(catalog, m)),
-    ...(credit.match.categories ?? []).map((c) => categoryPhrase(catalog, c)),
-]);
-// "at Lululemon", "at restaurants", "on travel": a category's own preposition.
-export const creditWhere = (catalog, credit) => `${(credit.match.categories ?? []).some((c) => categoryReadsOn(catalog, c)) ? 'on' : 'at'} ${creditName(catalog, credit)}`;
+// Bookings through a travel site the credit also names go without saying:
+// "Capital One Travel", not each kind of booking through it.
+export function creditName(catalog, credit) {
+    const ids = credit.match.merchants ?? [];
+    const portals = ids
+        .map((m) => findMerchant(catalog, m))
+        .filter((m) => m?.kind === 'portal')
+        .map((m) => ` through ${m?.name ?? ''}`);
+    const merchants = ids.filter((m) => {
+        const merchant = findMerchant(catalog, m);
+        return !(merchant?.kind === 'booking' &&
+            portals.some((p) => merchant.name.endsWith(p)));
+    });
+    return listed([
+        ...merchants.map((m) => merchantName(catalog, m)),
+        ...(credit.match.categories ?? []).map((c) => categoryPhrase(catalog, c)),
+    ]);
+}
+// "at Lululemon", "at restaurants", "on travel", "on Walmart+ membership":
+// the category's or merchant's own preposition.
+export const creditWhere = (catalog, credit) => `${(credit.match.categories ?? []).some((c) => categoryReadsOn(catalog, c)) ||
+    (credit.match.merchants ?? []).some((m) => findMerchant(catalog, m)?.preposition === 'on')
+    ? 'on'
+    : 'at'} ${creditName(catalog, credit)}`;

package/dist/engine/setup.js

@@ -4,7 +4,7 @@ import { milestoneWhat } from "./milestones.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap, rotationGapText } from "./rotation.js";
 import { creditName, creditWhere, introWhat } from "./rule-text.js";
-import { creditBack, ENROLL_FIRST, idList, listed } from "./text.js";
+import { creditBack, ENROLL_FIRST, idList, listed, possessive } from "./text.js";
 // Rules that start within this many days are worth activating now.
 const ACTIVATION_LOOKAHEAD_DAYS = 45;
 const searchWords = (s) => s
@@ -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,
@@ -168,7 +172,7 @@ export function setupNotes(catalog, wallet, held, today) {
         notes.push({
             kind: 'pick',
             text: choice.default && picked.has(choice.id)
-                ? `${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}).`
+                ? `${possessive(name)} ${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.`,
         });
     }
@@ -177,7 +181,7 @@ export function setupNotes(catalog, wallet, held, today) {
     if (missing.length > 0) {
         notes.push({
             kind: 'membership',
-            text: `Some of ${name}'s rates need ${listed(missing.map((m) => `${membershipName(catalog, m)} (${m})`), 'or')}; they're counted without it.`,
+            text: `Some of ${possessive(name)} 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));

package/dist/engine/simulate.js

@@ -6,7 +6,7 @@ import { choicePeriod, periodKey } from "./periods.js";
 import { applyBooking, capBooking } from "./record.js";
 import { milestoneWhat } from "./milestones.js";
 import { rotationGap } from "./rotation.js";
-import { money, paymentNote, roundCents, wholeDollars } from "./text.js";
+import { money, paymentNote, roundCents, wholeDollars, possessive, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON, HALF_CENT } from "./compare.js";
 const MONTHS = 12;
@@ -164,13 +164,13 @@ held = []) {
             ...new Set(dates.map((d) => rotationGap(card, d)).filter((g) => g !== null)),
         ];
         if (gaps.length > 0)
-            notes.push(`${card.name}'s rotating categories for ${gaps.join(', ')} aren't in earnrate's data yet, so those quarters count at its everyday rates.`);
+            notes.push(`${possessive(card.name)} rotating categories for ${gaps.join(', ')} aren't in earnrate's data yet, so those quarters count at its everyday rates.`);
         if (card.annual_fee === undefined)
-            notes.push(`${card.name}'s annual fee isn't on file, so none is subtracted.`);
+            notes.push(`${possessive(card.name)} annual fee isn't on file, so none is subtracted.`);
         else if (!held.includes(card.id) &&
             card.first_year_fee !== undefined &&
             card.first_year_fee !== card.annual_fee)
-            notes.push(`${card.name}'s fee is ${money(card.first_year_fee)} the first year; the yearly figure uses the ${money(card.annual_fee)} that follows.`);
+            notes.push(`${possessive(card.name)} fee is ${money(card.first_year_fee)} the first year; the yearly figure uses the ${money(card.annual_fee)} that follows.`);
     }
     return {
         cards: wallet.cards.map((h) => ({

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,20 @@ 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') => {
     const anded = parts.filter((p) => p.includes(' and '));
     if (anded.length > 0)
@@ -166,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',
@@ -187,8 +206,8 @@ export const introSince = (days) => days === 365 ? 'in the last year' : `in the
 export const introRateText = (earn, standard, days, until) => `${earn} in your ${introPeriod(days)}, through ${shortDate(until)}; ${standard} after that.`;
 // 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) => `${name}'s ${introAdjective(days)} rate ends after ${shortDate(until)}; from then on it earns its standard rates.`;
-// Merchant statement credits. Always dollars, never a percentage.
+export const introEndsText = (name, days, until) => `${possessive(name)} ${introAdjective(days)} rate ends after ${shortDate(until)}; from then on it earns its standard rates.`;
+// Statement credits. Always dollars, never a percentage.
 export const CREDIT_PERIODS = {
     month: 'each month',
     quarter: 'each quarter',
@@ -205,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"
@@ -216,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)
@@ -243,6 +262,8 @@ export function creditShort(c, dollars) {
 // For the to-do list: "Use your $75 lululemon credit on Amex Platinum by Dec
 // 31, 2026: $35 left."
 export const useCreditText = (card, c, left) => `Use your ${money(c.amount)} ${c.name} credit on ${card}${c.until === null ? '' : ` by ${shortDate(c.until)}`}: ${money(left)} left.`;
-export const enrollCreditText = (card, name) => `Enroll in ${card}'s ${name} credit with the issuer, then mark it enrolled.`;
+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))