earnrate 0.2.14 → 0.2.15

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,28 @@ 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))
+        const line = lines.get(key) ?? { at: [], on: [] };
+        const whats = line[rulePreposition(catalog, [r])];
+        for (const part of ruleParts(catalog, r, card))
             if (!whats.includes(part))
                 whats.push(part);
-        lines.set(key, whats);
+        lines.set(key, line);
     }
     return [
-        ...[...lines].map(([key, whats]) => {
+        ...[...lines].map(([key, { at, on }]) => {
             const [head = '', limit = '', activate = '', paid = ''] = key.split('|');
             const after = `${limit}${activate}`;
-            return `${head} ${listed(whats)}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
+            // "at gas stations and on transit" when one line mixes the two.
+            const where = [
+                ...(at.length > 0 ? [`at ${listed(at)}`] : []),
+                ...(on.length > 0 ? [`on ${listed(on)}`] : []),
+            ].join(at.length > 1 ? ', and ' : ' and ');
+            return `${head} ${where}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
         }),
         ...(shown.some((r) => r.match.any &&
             r.geography !== 'foreign_only' &&
@@ -103,13 +107,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))),
+            ]),
+            preposition: rulePreposition(catalog, rules),
             from: first?.valid_from ?? null,
             to: first?.valid_to ?? null,
             activateBy: first?.activate_by ?? null,
@@ -154,8 +156,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,

package/dist/format/card-text.js

@@ -1,8 +1,7 @@
-import { earnText } from "../engine/text.js";
 // Card names, fees and requirements as earnrate.dev and its static search
 // pages show them. Node-free: the site bundles it.
 import { membershipName, membershipText } from "../engine/memberships.js";
-import { CAP_PERIODS, PICK_PERIODS, wholeDollars, words, } from "../engine/text.js";
+import { capSentence, earnText, PICK_PERIODS, wholeDollars, words, } from "../engine/text.js";
 // An issuer's name as people know it, from data/issuers.yaml.
 export const issuerName = (catalog, id) => catalog.issuers.find((i) => i.id === id)?.name ?? id;
 export function cardText(catalog) {
@@ -42,7 +41,7 @@ export function cardText(catalog) {
         if (until !== null)
             lines.push(`This rate runs through ${until}`);
         if (r.cap)
-            lines.push(`Up to ${wholeDollars(r.cap.amount)} of spending ${CAP_PERIODS[r.cap.period]}, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}`);
+            lines.push(capSentence(r.cap, earnText(catalog, r.cap.thenRate, r.cap.currency)));
         return lines;
     }
     const memberName = (id) => membershipName(catalog, id);

package/dist/format/cards.js

@@ -5,7 +5,7 @@ export function formatCardInfo(catalog, card) {
         ? ''
         : card.annualFee === 0
             ? ', no annual fee'
-            : `, ${money(card.annualFee)} a year`;
+            : `, ${money(card.annualFee)} a year${card.firstYearFee === null ? '' : `, ${card.firstYearFee === 0 ? 'waived' : money(card.firstYearFee)} the first year`}`;
     const needs = [
         ...card.choices.map((c) => `${c.id}: pick ${String(c.pick)} of ${c.options.join(', ')}${c.default ? ` (default ${c.default.join(', ')})` : ''}`),
         ...(card.requiresMembership
@@ -24,7 +24,7 @@ export function formatCardInfo(catalog, card) {
         ...(card.needsAnniversary ? ['cap resets on the card anniversary'] : []),
         ...card.milestones.map((m) => `spend bonus: ${m.text} (${m.id})`),
         ...card.introRates.map((i) => `new accounts: ${i.text}; needs the opening date`),
-        ...card.credits.map((c) => `merchant credit ${c.id}: ${c.text}`),
+        ...card.credits.map((c) => `statement credit ${c.id}: ${c.text}`),
         ...(card.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
         foreignFeeText(card.foreignTransactionFee).toLowerCase(),
     ];

package/dist/format/explore.js

@@ -1,5 +1,5 @@
 import { membershipName, membershipNote, } from "../engine/memberships.js";
-import { capitalize, choiceName, CREDIT_GROUP, CREDITS_LEFT_OUT, ENROLL_FIRST, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, } from "../engine/text.js";
+import { capitalize, choiceName, CREDIT_GROUP, CREDITS_LEFT_OUT, ENROLL_FIRST, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, listed, } from "../engine/text.js";
 const membershipFees = (memberships) => memberships
     .map((m) => ` + ${wholeDollars(m.annualFee)} for ${m.name}`)
     .join('');
@@ -51,7 +51,7 @@ export function formatExploration(r, catalog, all) {
     return `${lines.join('\n')}\n`;
 }
 function picksText(picks) {
-    const parts = Object.entries(picks).map(([choice, options]) => `${options.map(words).join(' and ')} as its ${choiceName(choice)} ${options.length === 1 ? 'pick' : 'picks'}`);
+    const parts = Object.entries(picks).map(([choice, options]) => `${listed(options.map(words))} as its ${choiceName(choice)} ${options.length === 1 ? 'pick' : 'picks'}`);
     return parts.length === 0 ? '' : ` (with ${parts.join('; ')})`;
 }
 function cardNamer(catalog) {

package/dist/format/wallet-yaml.js

@@ -25,8 +25,8 @@ function compact(wallet) {
         cards: wallet.cards.map((c) => Object.fromEntries(CARD_FIELDS.flatMap((k) => (isEmpty(c[k]) ? [] : [[k, c[k]]])))),
     };
 }
-// Dates, periods and anniversaries are quoted: YAML 1.1 parsers read a bare 2026-10-15 as a
-// date, not a string.
+// Dates, periods and anniversaries are quoted: YAML 1.1 parsers read a bare
+// 2026-10-15 as a date, not a string.
 function quotedYaml(value) {
     const doc = new Document(value);
     visit(doc, {

package/dist/format/wallet.js

@@ -48,10 +48,10 @@ export function formatWalletSummary(summary) {
         else if (c.intro?.state === 'no-date')
             lines.push(`  Has ${introAdjective(c.intro.days)} rates for new accounts; give its opening date if it opened ${introSince(c.intro.days)}.`);
         else if (c.opened !== null)
-            lines.push(`  Opened ${c.opened}.`);
+            lines.push(`  Opened ${shortDate(c.opened)}.`);
         const b = c.bonus;
         if (b?.state === 'open' && b.spend !== null)
-            lines.push(`  Welcome bonus: ${money(b.spent)} of ${money(b.spend)} spent, due ${b.deadline ?? ''}.`);
+            lines.push(`  Welcome bonus: ${money(b.spent)} of ${money(b.spend)} spent, due ${b.deadline === null ? 'by its deadline' : shortDate(b.deadline)}.`);
         else if (b)
             lines.push(`  Welcome bonus: ${b.state}.`);
         return lines.join('\n');
@@ -65,19 +65,19 @@ export function formatWalletSummary(summary) {
     return [...cards, memberships, values].join('\n');
 }
 export function formatBooking(amount, name, // the card's short name
-cap, bonus, milestones = [], credit = null) {
+cap, bonus, milestones = [], credit = null, capLabel = null) {
     const messages = [];
     if (credit)
         messages.push(`Used ${money(roundCents(credit.after - credit.before))} of ${possessive(name)} ${credit.name} credit: ${money(credit.after)} of ${money(credit.amount)} ${periodPhrase(credit.periodKind, credit.period)}, ${money(roundCents(Math.max(0, credit.amount - credit.after)))} left.`);
     if (cap) {
         const left = Math.max(0, cap.capAmount - cap.after);
-        messages.push(`Recorded ${money(amount)} on ${name} against "${cap.capKey}": ${money(cap.before)} → ${money(cap.after)} of ${money(cap.capAmount)} ${periodPhrase(cap.periodKind, cap.period)}, ${money(left)} left.`);
+        messages.push(`Recorded ${money(amount)} on ${name} toward its ${capLabel ?? cap.capKey} cap: ${money(cap.before)} → ${money(cap.after)} of ${money(cap.capAmount)} ${periodPhrase(cap.periodKind, cap.period)}, ${money(left)} left.`);
     }
     if (bonus) {
         const left = Math.max(0, bonus.spend - bonus.after);
         messages.push(left === 0
             ? `Welcome bonus spend met on ${name}: ${money(bonus.after)} of ${money(bonus.spend)}.`
-            : `Welcome bonus on ${name}: ${money(bonus.after)} of ${money(bonus.spend)} spent, ${money(left)} to go by ${bonus.deadline ?? 'the deadline'}.`);
+            : `Welcome bonus on ${name}: ${money(bonus.after)} of ${money(bonus.spend)} spent, ${money(left)} to go by ${bonus.deadline === null ? 'the deadline' : shortDate(bonus.deadline)}.`);
     }
     // Every milestone counts the same purchases, so one line covers them.
     const first = milestones[0];

package/dist/import/analyze.js

@@ -4,7 +4,7 @@ import { capByKey, categoryMatches } from "../engine/evaluate.js";
 import { milestoneProgress } from "../engine/milestones.js";
 import { periodKey } from "../engine/periods.js";
 import { recommend } from "../engine/recommend.js";
-import { applyBooking, capBooking } from "../engine/record.js";
+import { applyBooking, applyCreditBooking, capBooking, creditBooking, } from "../engine/record.js";
 import { roundCents } from "../engine/text.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { cleanDescriptor } from "./statement.js";
@@ -55,6 +55,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
     const missed = new Map();
     const coding = new Map();
     const bookings = [];
+    const credits = [];
     let outsideCurrentPeriod = 0;
     let alreadyImported = 0;
     let purchases = 0;
@@ -145,6 +146,16 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
                 outsideCurrentPeriod++;
             }
         }
+        if (line.amount > 0 && !alreadyRecorded(entry, 'credit')) {
+            const credit = creditBooking(catalog, current, recorded, merchant);
+            const held = current.cards.find((c) => c.id === cardId);
+            if (credit &&
+                periodKey(credit.periodKind, today, held?.anniversary ?? null) ===
+                    credit.period) {
+                credits.push({ ...entry, booking: credit });
+                current = applyCreditBooking(current, credit);
+            }
+        }
         if (line.amount < 0) {
             refunds += -line.amount;
             continue;
@@ -244,6 +255,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
             .sort((a, b) => b.best - b.earned - (a.best - a.earned)),
         coding: [...coding.values()].sort((a, b) => b.count - a.count),
         bookings,
+        credits,
         outsideCurrentPeriod,
         alreadyImported,
         bonuses: [...bonuses.values()].filter((b) => b.entries.length > 0),

package/dist/mcp/context.js

@@ -72,9 +72,8 @@ export function makeContext(deps) {
     }
     // Cards named in the conversation come first, then the saved wallet; with
     // neither (null), answers cover every card earnrate knows.
-    // The point values and memberships the user saved apply to every answer,
-    // not just ones from their saved cards. A wallet that can't be read has
-    // none.
+    // Saved point values and memberships apply to every answer, not just ones
+    // from saved cards. A wallet that can't be read has none.
     async function saved() {
         try {
             const wallet = await deps.store.load();