earnrate 0.2.11 → 0.2.13

package/dist/engine/recommend.js

@@ -1,13 +1,15 @@
-import { findMerchant, resolveMerchant, resolveMerchantById, } from "../merchants/resolve.js";
+import { findMerchant, merchantFamily, resolveMerchant, resolveMerchantById, } from "../merchants/resolve.js";
 import { bonusStatus } from "./bonus.js";
-import { evaluateCard, purchaseContext, usableAt, } from "./evaluate.js";
+import { evaluateCard, paymentUpgrade, purchaseContext, usableAt, } from "./evaluate.js";
+import { openedOn } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestonePoints, milestonesReached, reachedText, } from "./milestones.js";
 import { daysBetween } from "./periods.js";
+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, codesAs, currencyLabel, currencyName, earnText, listed, money, NETWORK_NAMES, num, pct, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.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 { cardValuation } from "./valuation.js";
 export const STALE_AFTER_DAYS = 180;
 // The engine only tells the U.S. from everywhere else.
@@ -41,7 +43,7 @@ function compareEntries(a, b) {
         return aCapped ? 1 : -1;
     return a.card.id.localeCompare(b.card.id);
 }
-function rankEntries(catalog, wallet, purchase, merchant, category) {
+function rankEntries(catalog, wallet, purchase, merchant, category, options = {}) {
     const ctx = purchaseContext(catalog, wallet, merchant, category, purchase);
     const entries = [];
     const excluded = [];
@@ -79,6 +81,26 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
             (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 fresh = card.intro_rates.length > 0 && openedOn(held) === null
+            ? evaluateCard(card, { ...held, opened: purchase.date }, ctx).best
+            : null;
+        const ifNew = fresh && fresh.rate > evaluation.best.rate + EPSILON
+            ? {
+                rate: fresh.nominalRate,
+                returnPct: (perDollar - evaluation.best.rate + fresh.rate) *
+                    valuation.centsPerUnit -
+                    fee,
+                days: (fresh.intro[0]?.intro ?? card.intro_rates[0])?.days ?? 365,
+            }
+            : null;
+        const paid = paymentUpgrade(card, held, ctx, evaluation.best.rate);
+        const credit = options.credits === false
+            ? null
+            : creditAt(catalog, card, held, { ...merchant, category }, purchase.date);
+        const back = credit ? creditDollars(credit, purchase.amount) : null;
+        const creditPct = back !== null && back > 0 && purchase.amount
+            ? (back / purchase.amount) * 100
+            : 0;
         entries.push({
             card,
             held,
@@ -87,9 +109,25 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
             milestones,
             perDollar,
             fee,
-            effectiveReturnPct: perDollar * valuation.centsPerUnit - fee,
+            credit,
+            creditDollars: back,
+            creditPct,
+            effectiveReturnPct: perDollar * valuation.centsPerUnit - fee + creditPct,
             rateReturnPct: evaluation.best.rate * valuation.centsPerUnit - fee,
-            upside: perDollar * (valuation.range?.[1] ?? valuation.centsPerUnit) - fee,
+            upside: perDollar * (valuation.range?.[1] ?? valuation.centsPerUnit) -
+                fee +
+                creditPct,
+            ifNew: ifNew && { ...ifNew, returnPct: ifNew.returnPct + creditPct },
+            ifPaid: paid
+                ? {
+                    payment: paid.payment,
+                    rate: paid.nominalRate,
+                    returnPct: (perDollar - evaluation.best.rate + paid.rate) *
+                        valuation.centsPerUnit -
+                        fee +
+                        creditPct,
+                }
+                : null,
         });
     }
     entries.sort(compareEntries);
@@ -105,7 +143,12 @@ function reasoningFor(catalog, wallet, entry, amount) {
         lines.push(`${earnText(catalog, best.nominalRate, currency)} on ${ruleWhat(catalog, best.rule)}${best.rule.requires?.membership === undefined ? '' : `, with ${membershipName(catalog, best.rule.requires.membership)}`}.${note}`);
     }
     else {
-        lines.push(`${earnText(catalog, card.base_rate, currency)}, its base rate. No bonus category applies here.`);
+        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}`);
     }
     const cap = best.cap;
     if (cap && amount !== null && amount > cap.remaining) {
@@ -114,6 +157,8 @@ function reasoningFor(catalog, wallet, entry, amount) {
     }
     for (const hit of entry.milestones)
         lines.push(reachedText(card, hit, valuation.centsPerUnit));
+    if (entry.credit)
+        lines.push(creditAnswerText(entry.credit, entry.creditDollars));
     if (valuation.pooledFrom !== null) {
         const partners = card.pools_into?.when_wallet_has ?? [];
         const heldPartners = wallet.cards
@@ -199,6 +244,16 @@ function toRanked(catalog, wallet, entry, purchase) {
                     entry.valuation.centsPerUnit) /
                     100),
             },
+        credit: entry.credit && {
+            id: entry.credit.credit.id,
+            name: entry.credit.name,
+            amount: entry.credit.amount,
+            period: entry.credit.period,
+            enrolled: entry.credit.enrolled,
+            left: entry.credit.left,
+            until: entry.credit.until,
+            dollars: entry.creditDollars,
+        },
         capped: evaluation.best.cap !== null,
         reasoning: reasoningFor(catalog, wallet, entry, purchase.amount),
         warnings: warningsFor(catalog, entry, purchase),
@@ -243,15 +298,16 @@ function sensitivity(catalog, entries) {
             continue;
         const wRate = winner.perDollar;
         const oRate = other.perDollar;
-        // Net return is rate × value − fee, so each flip point adds the fee back.
+        // Net return is rate × value − fee + credit, so each flip point adds the
+        // fee back and takes the credit off.
         if (w.range && wRate > 0) {
-            const threshold = (other.effectiveReturnPct + winner.fee) / wRate;
+            const threshold = (other.effectiveReturnPct + winner.fee - winner.creditPct) / wRate;
             if (threshold < w.centsPerUnit && threshold >= w.range[0]) {
                 consider((w.centsPerUnit - threshold) / w.centsPerUnit, `${displayName(other)} beats ${displayName(winner)} here if ${pointsName(currencyLabel(catalog, w.currency))} are worth less than ${roundDown(threshold)}¢ (you value them at ${num(w.centsPerUnit)}¢).`);
             }
         }
         if (o.range && oRate > 0) {
-            const threshold = (winner.effectiveReturnPct + other.fee) / oRate;
+            const threshold = (winner.effectiveReturnPct + other.fee - other.creditPct) / oRate;
             if (threshold > o.centsPerUnit && threshold <= o.range[1]) {
                 consider((threshold - o.centsPerUnit) / o.centsPerUnit, `${displayName(other)} beats ${displayName(winner)} here if ${pointsName(currencyLabel(catalog, o.currency))} are worth ${worthAbove(threshold)} (you value them at ${num(o.centsPerUnit)}¢).`);
             }
@@ -273,8 +329,7 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
         const naming = entries.flatMap((e) => {
             const rule = e.evaluation.best.rule;
             return rule &&
-                merchant.merchantId !== null &&
-                (rule.match.merchants ?? []).includes(merchant.merchantId)
+                merchantFamily(catalog, merchant.merchantId).some((id) => (rule.match.merchants ?? []).includes(id))
                 ? [`${displayName(e)} (${ruleWhat(catalog, rule)})`]
                 : [];
         });
@@ -291,6 +346,9 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
     if (purchase.channel === null && merchant.channel === 'in_store') {
         assumptions.push(`Assumes an in-store purchase. ${merchant.resolvedName} takes cards differently online.`);
     }
+    if (merchant.channel === null && purchase.payment === 'paypal') {
+        assumptions.push('Assumes an online purchase, since PayPal checkout is online.');
+    }
     if (purchase.channel === null && merchant.channel === 'online') {
         assumptions.push('Assumes an online purchase, since you gave a web address.');
     }
@@ -299,13 +357,34 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
         assumptions.push(values);
     if (isForeign(purchase))
         assumptions.push(FOREIGN_ASSUMPTION);
+    if (purchase.payment)
+        assumptions.push(paidText(purchase.payment));
+    const winner = entries[0];
+    for (const e of entries) {
+        if (!e.ifPaid || !winner)
+            continue;
+        if (e !== winner &&
+            e.ifPaid.returnPct <= winner.effectiveReturnPct + EPSILON)
+            continue;
+        const currency = e.valuation.currency;
+        assumptions.push(paymentUnknownText(displayName(e), e.ifPaid.payment, earnText(catalog, e.ifPaid.rate, currency), earnText(catalog, e.evaluation.best.nominalRate, currency)));
+    }
+    for (const e of entries) {
+        if (!e.ifNew || !winner)
+            continue;
+        if (e !== winner &&
+            e.ifNew.returnPct <= winner.effectiveReturnPct + EPSILON)
+            continue;
+        const currency = e.valuation.currency;
+        assumptions.push(introUnknownText(displayName(e), earnText(catalog, e.ifNew.rate, currency), earnText(catalog, e.evaluation.best.nominalRate, currency), e.ifNew.days));
+    }
     for (const e of entries)
         for (const hit of e.milestones)
             assumptions.push(`Counts the ${money(hit.before)} tracked on ${displayName(e)} in ${hit.period} toward its ${wholeDollars(hit.spend)} spend bonus; spending earnrate wasn't told about isn't counted.`);
     return assumptions;
 }
-export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(catalog, purchase.merchant, purchase.channel)) {
-    const { entries, excluded } = rankEntries(catalog, wallet, purchase, merchant, merchant.category);
+export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(catalog, purchase.merchant, purchase.channel), options = {}) {
+    const { entries, excluded } = rankEntries(catalog, wallet, purchase, merchant, merchant.category, options);
     const ranked = entries.map((e) => toRanked(catalog, wallet, e, purchase));
     const winner = entries[0];
     const warnings = [];
@@ -329,7 +408,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const alternatives = merchant.ambiguity.mayCodeAs.map((c) => categoryPhrase(catalog, c));
         warnings.push(`${merchant.resolvedName} may code as ${alternatives.join(' or ')} instead: ${merchant.ambiguity.note}`);
         for (const category of merchant.ambiguity.mayCodeAs) {
-            const alts = rankEntries(catalog, wallet, purchase, merchant, category).entries;
+            const alts = rankEntries(catalog, wallet, purchase, merchant, category, options).entries;
             const alt = alts[0];
             if (!alt || !winner)
                 continue;
@@ -356,7 +435,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             ? resolveMerchantById(catalog, merchant.merchantId, 'online')
             : null;
         const alt = online
-            ? rankEntries(catalog, wallet, { ...purchase, channel: 'online' }, online, online.category).entries[0]
+            ? rankEntries(catalog, wallet, { ...purchase, channel: 'online' }, online, online.category, options).entries[0]
             : undefined;
         if (alt)
             warnings.push(`Ordering online instead? ${displayName(alt)} works there (${pct(alt.rateReturnPct)}).`);
@@ -381,8 +460,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const via = resolveMerchantById(catalog, id, purchase.channel);
         if (!via || !winner)
             continue;
-        const alt = rankEntries(catalog, wallet, purchase, via, via.category)
-            .entries[0];
+        const alt = rankEntries(catalog, wallet, purchase, via, via.category, options).entries[0];
         if (alt && alt.effectiveReturnPct > winner.effectiveReturnPct + EPSILON) {
             notes.push(`If you book it as ${via.resolvedName}, ${displayName(alt)} earns ${pct(alt.rateReturnPct)}.`);
         }
@@ -418,8 +496,11 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const costHere = ties || top.earned === null || first.earned === null
             ? null
             : roundCents(first.earned +
-                (first.milestoneBonus?.dollars ?? 0) -
-                (top.earned + (top.milestoneBonus?.dollars ?? 0)));
+                (first.milestoneBonus?.dollars ?? 0) +
+                (first.credit?.dollars ?? 0) -
+                (top.earned +
+                    (top.milestoneBonus?.dollars ?? 0) +
+                    (top.credit?.dollars ?? 0)));
         bonusResult = {
             cardId: top.cardId,
             checkoutLabel: top.checkoutLabel,

package/dist/engine/record.js

@@ -1,6 +1,7 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { bonusStatus, countsTowardBonus } from "./bonus.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
+import { creditAt, creditDollars } from "./credits.js";
 import { milestoneProgress } from "./milestones.js";
 import { roundCents } from "./text.js";
 // Books the spend against the cap of the highest-rate rule that matches, even
@@ -29,6 +30,7 @@ export function capBooking(catalog, wallet, purchase, merchant = resolveMerchant
         capKey: cap.key,
         ruleId: rule.id,
         period: cap.period,
+        periodKind: cap.cap.period,
         capAmount: cap.cap.amount,
         before,
         after: roundCents(before + purchase.amount),
@@ -90,6 +92,7 @@ export function milestoneBookings(catalog, wallet, purchase) {
                 cardId: card.id,
                 milestoneId: p.milestone.id,
                 period: p.period,
+                periodKind: p.milestone.period,
                 spend: p.milestone.spend,
                 before: p.spent,
                 after: roundCents(Math.max(0, p.spent + purchase.amount)),
@@ -110,14 +113,53 @@ export function applyMilestoneBooking(wallet, b) {
             : c),
     };
 }
+// The part of an enrolled merchant credit this purchase uses. None when the
+// card has no credit here, it isn't enrolled, or it's used up.
+export function creditBooking(catalog, wallet, purchase, merchant = resolveMerchant(catalog, purchase.merchant, purchase.channel)) {
+    const held = wallet.cards.find((c) => c.id === purchase.cardId);
+    const card = catalog.cards.find((c) => c.id === purchase.cardId);
+    if (!held || !card)
+        return null;
+    const state = creditAt(catalog, card, held, merchant, purchase.date);
+    const back = state ? creditDollars(state, purchase.amount) : null;
+    if (!state || state.key === null || back === null || back <= 0)
+        return null;
+    return {
+        cardId: card.id,
+        creditId: state.credit.id,
+        name: state.name,
+        period: state.key,
+        periodKind: state.period,
+        amount: state.amount,
+        before: state.used,
+        after: roundCents(state.used + back),
+    };
+}
+export function applyCreditBooking(wallet, b) {
+    return {
+        ...wallet,
+        cards: wallet.cards.map((c) => c.id === b.cardId
+            ? {
+                ...c,
+                credit_usage: {
+                    ...c.credit_usage,
+                    [b.creditId]: { period: b.period, used: b.after },
+                },
+            }
+            : c),
+    };
+}
 export function bookPurchase(catalog, wallet, purchase, merchant) {
     const cap = capBooking(catalog, wallet, purchase, merchant);
     const bonus = bonusBooking(catalog, wallet, purchase);
     const milestones = milestoneBookings(catalog, wallet, purchase);
+    const credit = creditBooking(catalog, wallet, purchase, merchant);
     let next = cap ? applyBooking(wallet, cap) : wallet;
     if (bonus)
         next = applyBonusBooking(next, bonus);
     for (const m of milestones)
         next = applyMilestoneBooking(next, m);
-    return { wallet: next, cap, bonus, milestones };
+    if (credit)
+        next = applyCreditBooking(next, credit);
+    return { wallet: next, cap, bonus, milestones, credit };
 }

package/dist/engine/rotation.js

@@ -14,3 +14,6 @@ export function rotationGap(card, date) {
     }
     return null;
 }
+// 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.`;

package/dist/engine/rule-text.js

@@ -1,5 +1,5 @@
 import { findMerchant } from "../merchants/resolve.js";
-import { categoryPhrase, choiceName, listed, words } from "./text.js";
+import { categoryPhrase, categoryReadsOn, choiceName, earnText, introPeriod, listed, num, PAYMENT_PHRASES, 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.
@@ -29,7 +29,9 @@ export function ruleParts(catalog, rule) {
         return [
             rule.geography === 'foreign_only'
                 ? 'purchases outside the U.S.'
-                : 'everything else',
+                : rule.requires?.payment !== undefined
+                    ? 'purchases'
+                    : 'everything else',
         ];
     if (rule.match.choice !== undefined)
         return [`your ${choiceName(rule.match.choice)} picks`];
@@ -55,5 +57,28 @@ export function ruleParts(catalog, rule) {
     return parts.length > 0 ? parts : [words(rule.id)];
 }
 export function ruleWhat(catalog, rule) {
-    return listed(ruleParts(catalog, rule));
+    const payment = rule.requires?.payment;
+    const what = listed(ruleParts(catalog, rule));
+    return payment === undefined ? what : `${what} ${PAYMENT_PHRASES[payment]}`;
 }
+// "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('; ');
+    const change = intro.multiply === undefined
+        ? `an extra ${earnText(catalog, intro.add ?? 0, card.currency)} on ${on}`
+        : intro.multiply === 2
+            ? `double ${on}`
+            : `${num(intro.multiply)} times ${on}`;
+    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)}`;

package/dist/engine/setup.js

@@ -2,8 +2,9 @@ import { isActivated, pickedCategories } from "./evaluate.js";
 import { membership, membershipName, sameGroup } from "./memberships.js";
 import { milestoneWhat } from "./milestones.js";
 import { daysBetween } from "./periods.js";
-import { rotationGap } from "./rotation.js";
-import { idList, listed } from "./text.js";
+import { rotationGap, rotationGapText } from "./rotation.js";
+import { creditName, creditWhere, introWhat } from "./rule-text.js";
+import { creditBack, ENROLL_FIRST, idList, listed } from "./text.js";
 // Rules that start within this many days are worth activating now.
 const ACTIVATION_LOOKAHEAD_DAYS = 45;
 const searchWords = (s) => s
@@ -105,6 +106,22 @@ export function cardInfo(catalog, card, wallet, today) {
             rewards: m.rewards ?? [],
             text: milestoneWhat(m).replace(/^the /, ''),
         })),
+        introRates: card.intro_rates.map((i) => ({
+            id: i.id,
+            days: i.days,
+            text: introWhat(catalog, card, i),
+        })),
+        credits: card.credits.map((c) => {
+            const name = creditName(catalog, c);
+            return {
+                id: c.id,
+                name,
+                amount: c.amount,
+                period: c.period,
+                enroll: c.enroll === true,
+                text: `${creditBack(c)} ${creditWhere(catalog, c)}${c.enroll ? `, ${ENROLL_FIRST}` : ''}`,
+            };
+        }),
     };
 }
 // Every word of the query has to match a word of the card's id, name or
@@ -180,7 +197,7 @@ export function setupNotes(catalog, wallet, held, today) {
     if (gap !== null) {
         notes.push({
             kind: 'rotation',
-            text: `${name}'s rotating categories for ${gap} aren't in earnrate's data yet. An earnrate update adds them once the issuer announces them.`,
+            text: rotationGapText(name, gap),
         });
     }
     return notes;

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, roundCents, wholeDollars } from "./text.js";
+import { money, paymentNote, roundCents, wholeDollars } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON, HALF_CENT } from "./compare.js";
 const MONTHS = 12;
@@ -155,6 +155,9 @@ held = []) {
     const notes = [...milestoneNotes];
     for (const m of memberships)
         notes.push(membershipNote(catalog, m));
+    const paying = paymentNote(cards.map(({ card }) => ({ name: card.name, card })));
+    if (paying !== null)
+        notes.push(paying);
     const dates = monthDates(start);
     for (const { card } of cards) {
         const gaps = [
@@ -240,6 +243,12 @@ function bestSimulation(catalog, base, card, lines, options) {
 }
 const costs = (s) => s.annualFees + s.membershipFees;
 const byNet = (a, b) => b.net - a.net || costs(a) - costs(b);
+// Each card on its own with its best picks, best net first.
+export function simulateSingles(catalog, cards, lines, options) {
+    return cards
+        .map((card) => bestSimulation(catalog, [], card, lines, options))
+        .sort(byNet);
+}
 // Pairs that tie and share their first card differ only in an
 // interchangeable second card (several flat 2% cards), so they fold into one.
 function foldTies(pairs) {

package/dist/engine/text.js

@@ -63,6 +63,15 @@ export function categoryPhrase(catalog, id) {
         ? name
         : name.charAt(0).toLowerCase() + name.slice(1);
 }
+// A category bought as a service reads "on" (streaming services); its own
+// preposition or a parent's says so. Everything else reads "at".
+export function categoryReadsOn(catalog, id) {
+    const category = catalog.categories.find((c) => c.id === id);
+    if (category?.preposition === 'on')
+        return true;
+    const dot = id.lastIndexOf('.');
+    return dot !== -1 && categoryReadsOn(catalog, id.slice(0, dot));
+}
 export function earnText(catalog, rate, currency) {
     return currency === 'cash'
         ? `${pct(rate)} cash back`
@@ -92,6 +101,32 @@ export const NETWORK_NAMES = {
     discover: 'Discover',
     store: 'store card',
 };
+// How a purchase is paid, mid-sentence: "2% cash back with Apple Pay".
+export const PAYMENT_PHRASES = {
+    card: 'with the card itself',
+    'apple-pay': 'with Apple Pay',
+    'google-pay': 'with Google Pay',
+    paypal: 'through PayPal checkout',
+};
+export const paidText = (payment) => `Counts this as paid ${PAYMENT_PHRASES[payment]}, as you said.`;
+export const paymentUnknownText = (name, payment, earn, standard) => `${capitalize(PAYMENT_PHRASES[payment])}, ${name} would earn ${earn} here, instead of the ${standard} it's ranked at. Say how you're paying to count it.`;
+// For answers that never ask how each purchase is paid (cheat sheets and
+// simulations): which cards' rates that need a way of paying are left out.
+export function paymentNote(cards) {
+    const payments = new Set();
+    const names = [];
+    for (const { name, card } of cards) {
+        const needs = card.rules.flatMap((r) => r.requires?.payment === undefined ? [] : [r.requires.payment]);
+        if (needs.length === 0)
+            continue;
+        names.push(name);
+        for (const p of needs)
+            payments.add(p);
+    }
+    if (names.length === 0)
+        return null;
+    return `Rates ${listed([...payments].map((p) => PAYMENT_PHRASES[p]), 'or')} (${listed(names)}) aren't counted: this ranks each card by what it earns however you pay.`;
+}
 // A name with its own "and" ("drugstores and pharmacies") would run into the
 // list's: those lists use commas only, with those names last.
 export const listed = (parts, joiner = 'and') => {
@@ -122,6 +157,9 @@ export const CAP_PERIODS = {
     calendar_year: 'a calendar year',
     cardmember_year: 'a cardmember year',
 };
+// "for 2026-Q4", or "this cardmember year": a cardmember year's key is the
+// year it started, which reads as the calendar year.
+export const periodPhrase = (kind, key) => kind === 'cardmember_year' ? 'this cardmember year' : `for ${key}`;
 export const CAP_ADJECTIVES = {
     month: 'monthly',
     quarter: 'quarterly',
@@ -139,3 +177,72 @@ export const PICK_PERIODS = {
     calendar_year: 'each year',
     until_changed: 'until you change it',
 };
+// Intro rates (a card's first 365 days): "first year", "first 90 days".
+export const introPeriod = (days) => days === 365 ? 'first year' : `first ${String(days)} days`;
+export const introAdjective = (days) => days === 365 ? 'first-year' : `${String(days)}-day`;
+// Asking for an opening date: "if it opened in the last year".
+export const introSince = (days) => days === 365 ? 'in the last year' : `in the last ${String(days)} days`;
+// "6% cash back in your first year, through Mar 3, 2027; 3% cash back after
+// that."
+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 CREDIT_PERIODS = {
+    month: 'each month',
+    quarter: 'each quarter',
+    half_year: 'each half year',
+    calendar_year: 'each calendar year',
+    cardmember_year: 'each cardmember year',
+};
+export const CREDIT_THIS_PERIOD = {
+    month: 'this month',
+    quarter: 'this quarter',
+    half_year: 'this half year',
+    calendar_year: 'this year',
+    cardmember_year: 'this cardmember year',
+};
+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';
+// "$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"
+export const creditThen = (c, earn) => `${creditBack(c)}, then ${earn}`;
+// "$35 left this quarter"
+export const creditLeft = (left, period) => `${money(left)} left ${CREDIT_THIS_PERIOD[period]}`;
+// A line for an answer that uses the card's credit, or says why it doesn't.
+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.`;
+    if (c.left === null)
+        return `Has a ${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)
+        return `Its ${credit} has ${creditLeft(c.left, c.period)}; give the amount to count it.`;
+    return dollars < c.left
+        ? `${money(dollars)} back from its ${credit}, on top of what it earns; ${creditLeft(roundCents(c.left - dollars), c.period)} after this.`
+        : `${money(dollars)} back from its ${credit}: all that's left ${CREDIT_THIS_PERIOD[c.period]}, on top of what it earns.`;
+}
+// One short line beside a ranked card: "+ $35 back from its Lululemon
+// credit", "Lululemon credit: $35 left this quarter".
+export function creditShort(c, dollars) {
+    if (!c.enrolled)
+        return `${c.name} credit: ${creditBack(c)}, ${ENROLL_FIRST}`;
+    if (c.left === null)
+        return `${c.name} credit: ${creditBack(c)}`;
+    if (c.left <= 0)
+        return `${c.name} credit used up ${CREDIT_THIS_PERIOD[c.period]}`;
+    if (dollars === null || dollars <= 0)
+        return `${c.name} credit: ${creditLeft(c.left, c.period)}`;
+    return `+ ${money(dollars)} back from its ${c.name} credit`;
+}
+// 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.`;
+// 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.';