earnrate 0.2.12 → 0.2.14

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
@@ -95,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,
             },
         ]);
 }
@@ -112,14 +114,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

@@ -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.
@@ -14,3 +15,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) => `${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, choiceName, earnText, introPeriod, listed, num, 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.
-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];
@@ -29,7 +28,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,7 +56,9 @@ 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".
@@ -71,3 +74,28 @@ export function introWhat(catalog, card, intro) {
             : `${num(intro.multiply)} times ${on}`;
     return `${change} for the ${introPeriod(intro.days)}`;
 }
+// What a merchant credit is named for: "Lululemon", "Disney+, Hulu and ESPN".
+// 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

@@ -2,9 +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 { introWhat } from "./rule-text.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, possessive } from "./text.js";
 // Rules that start within this many days are worth activating now.
 const ACTIVATION_LOOKAHEAD_DAYS = 45;
 const searchWords = (s) => s
@@ -111,6 +111,17 @@ export function cardInfo(catalog, card, wallet, today) {
             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
@@ -157,7 +168,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.`,
         });
     }
@@ -166,7 +177,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));
@@ -186,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, possessive, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON, HALF_CENT } from "./compare.js";
 const MONTHS = 12;
@@ -155,19 +155,22 @@ 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 = [
             ...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) => ({
@@ -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

@@ -101,8 +101,36 @@ 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.
+// "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)
@@ -161,4 +189,64 @@ 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.`;
+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.
+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, 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.';

package/dist/engine/wallet-change.js

@@ -4,7 +4,7 @@ import { addMonths } from "./bonus.js";
 import { capByKey } from "./evaluate.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
-import { idList } from "./text.js";
+import { CREDIT_PERIODS, idList, money } from "./text.js";
 const failed = (error) => ({ ok: false, error });
 function findCatalogCard(catalog, id, today) {
     const card = catalog.cards.find((c) => c.id === id);
@@ -149,6 +149,40 @@ export function cardFields(card, held, input, today) {
         }
         fields.milestone_usage = usage;
     }
+    if (input.enrolled !== undefined) {
+        const needing = card.credits
+            .filter((c) => c.enroll === true)
+            .map((c) => c.id);
+        for (const id of input.enrolled) {
+            if (!needing.includes(id))
+                problems.push(needing.length > 0
+                    ? `'${id}' isn't a ${card.id} credit that needs enrolling. Those are: ${idList(needing)}.`
+                    : `${card.id} has no credits that need enrolling.`);
+        }
+        fields.enrolled = [...new Set(input.enrolled)];
+    }
+    if (input.creditUsed !== undefined) {
+        const usage = { ...held?.credit_usage };
+        const anniversary = fields.anniversary ?? held?.anniversary ?? null;
+        for (const [id, used] of Object.entries(input.creditUsed)) {
+            const credit = card.credits.find((c) => c.id === id);
+            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.`);
+                continue;
+            }
+            if (!(used >= 0 && used <= credit.amount))
+                problems.push(`The '${id}' credit is ${money(credit.amount)} ${CREDIT_PERIODS[credit.period]}, so what's used must be $0 to ${money(credit.amount)}.`);
+            const period = periodKey(credit.period, today, anniversary);
+            if (period === null) {
+                problems.push(`The '${id}' credit resets on the card's anniversary; give the anniversary (MM-DD) too.`);
+                continue;
+            }
+            usage[id] = { period, used };
+        }
+        fields.credit_usage = usage;
+    }
     if (input.bonus === null)
         fields.bonus = null;
     else if (input.bonus !== undefined) {
@@ -215,6 +249,8 @@ const withFields = ({ bonus, checkout_label, opened, ...held }, f) => ({
     ...(f.milestone_usage === undefined
         ? {}
         : { milestone_usage: f.milestone_usage }),
+    ...(f.enrolled === undefined ? {} : { enrolled: f.enrolled }),
+    ...(f.credit_usage === undefined ? {} : { credit_usage: f.credit_usage }),
     ...(f.bonus ? { bonus: f.bonus } : {}),
 });
 // `wallet` is null when there isn't one yet; adding a card starts it.

package/dist/engine/wallet-summary.js

@@ -3,12 +3,13 @@ import { activationGroup, capUsed, isActivated, pickedCategories, } from "./eval
 import { introUntil, introWindows, openedOn } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestoneSummaries } from "./milestones.js";
-import { optionName, ruleParts } from "./rule-text.js";
+import { creditStates } from "./credits.js";
+import { creditWhere, optionName, ruleParts } 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, choiceName, currencyLabel, earnText, listed, shortDate, wholeDollars, words, } from "./text.js";
+import { CAP_PERIODS, categoryReadsOn, 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
     ? []
@@ -62,10 +63,12 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
         if (replaced)
             continue;
         const pending = r.requires?.activation && !isActivated(card, held, r.id);
+        const payment = r.requires?.payment;
         const key = [
             `${earnText(catalog, r.rate, currency)} on`,
             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))
@@ -75,12 +78,13 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
     }
     return [
         ...[...lines].map(([key, whats]) => {
-            const [head = '', limit = '', activate = ''] = key.split('|');
+            const [head = '', limit = '', activate = '', paid = ''] = key.split('|');
             const after = `${limit}${activate}`;
-            return `${head} ${listed(whats)}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
+            return `${head} ${listed(whats)}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
         }),
         ...(shown.some((r) => r.match.any &&
             r.geography !== 'foreign_only' &&
+            r.requires?.payment === undefined &&
             r.rate > card.base_rate)
             ? []
             : [`${earnText(catalog, card.base_rate, currency)} on everything else`]),
@@ -200,6 +204,7 @@ export function walletSummary(catalog, wallet, today) {
             rotationGap: rotationGap(card, today),
             caps: capSummaries(catalog, card, held, today),
             milestones: milestoneSummaries(card, held, today),
+            credits: creditSummaries(catalog, card, held, today),
             chosen: held.chosen
                 ? {
                     period: held.chosen.period,
@@ -229,6 +234,29 @@ export function walletSummary(catalog, wallet, today) {
         cards,
     };
 }
+function creditSummaries(catalog, card, held, today) {
+    return creditStates(catalog, card, held, today).map((s) => {
+        const status = !s.enrolled
+            ? `${ENROLL_FIRST}, then mark it enrolled`
+            : s.left === null
+                ? "give the card's anniversary to track it"
+                : `${creditLeft(s.left, s.period)}${s.until === null ? '' : `, through ${shortDate(s.until)}`}`;
+        return {
+            id: s.credit.id,
+            name: s.name,
+            amount: s.amount,
+            period: s.period,
+            enroll: s.credit.enroll === true,
+            enrolled: s.enrolled,
+            currentPeriod: s.key,
+            until: s.until,
+            used: s.used,
+            left: s.left,
+            tracked: held.credit_usage?.[s.credit.id] !== undefined,
+            text: `${creditBack(s)} ${creditWhere(catalog, s.credit)}: ${status}.`,
+        };
+    });
+}
 function introSummary(card, held, today) {
     const [first] = card.intro_rates;
     if (!first)

package/dist/format/card-text.js

@@ -9,11 +9,12 @@ export function cardText(catalog) {
     const cards = new Map(catalog.cards.map((c) => [c.id, c]));
     function shortName(id) {
         const name = cards.get(id)?.name ?? id;
-        return name
+        return (name
             .replace(/^American Express /, 'Amex ')
             .replace(/^The Platinum Card from American Express$/, 'Amex Platinum')
-            .replace(/ (Visa Signature |Visa Infinite )?(Credit )?Card$/, '')
-            .replace(/ Card by /, ' by ');
+            // "Card" is part of Apple Card's name, not a suffix.
+            .replace(/ (Visa Signature |Visa Infinite )?(Credit )?(?<!^Apple )Card$/, '')
+            .replace(/ Card by /, ' by '));
     }
     function feeLabel(id) {
         const card = cards.get(id);

package/dist/format/cards.js

@@ -1,5 +1,6 @@
+import { membershipName } from "../engine/memberships.js";
 import { foreignFeeText, money, NETWORK_NAMES } from "../engine/text.js";
-export function formatCardInfo(card) {
+export function formatCardInfo(catalog, card) {
     const fee = card.annualFee === null
         ? ''
         : card.annualFee === 0
@@ -13,7 +14,9 @@ export function formatCardInfo(card) {
             ]
             : []),
         ...(card.memberships.length > 0
-            ? [`rates that need a membership: ${card.memberships.join(', ')}`]
+            ? [
+                `rates that need a membership: ${card.memberships.map((id) => `${membershipName(catalog, id)} (membership id ${id})`).join(', ')}`,
+            ]
             : []),
         ...(card.activation.length > 0
             ? [`activate with the issuer: ${card.activation.join(', ')}`]
@@ -21,6 +24,7 @@ export function formatCardInfo(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.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
         foreignFeeText(card.foreignTransactionFee).toLowerCase(),
     ];

package/dist/format/cheat-sheet.js

@@ -15,5 +15,7 @@ export function formatCheatSheet(sheet) {
     }
     if (sheet.notes.length > 0)
         lines.push('', ...sheet.notes);
+    if (sheet.assumptions.length > 0)
+        lines.push('', ...sheet.assumptions);
     return `${lines.join('\n')}\n`;
 }

package/dist/format/explore.js

@@ -1,5 +1,5 @@
 import { membershipName, membershipNote, } from "../engine/memberships.js";
-import { choiceName, 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, } from "../engine/text.js";
 const membershipFees = (memberships) => memberships
     .map((m) => ` + ${wholeDollars(m.annualFee)} for ${m.name}`)
     .join('');
@@ -15,7 +15,23 @@ export function formatExploration(r, catalog, all) {
         return `No cards match at ${title}.\n`;
     const shown = all ? r.ranked : r.ranked.slice(0, TOP_BEST);
     const width = Math.max(...shown.map((e) => e.cardName.length));
-    const lines = [`Best cards for ${title}:`, ''];
+    const lines = [
+        ...(r.credits.length === 0
+            ? []
+            : [
+                `${CREDIT_GROUP} at ${title}:`,
+                '',
+                ...r.credits.flatMap((c) => [
+                    `- ${c.cardName}: ${c.text}${c.enroll ? ` (${ENROLL_FIRST})` : ''}. ${capitalize(feeText(c))}.`,
+                    ...(c.evidence
+                        ? [`    "${c.evidence.quote}" (${hostname(c.evidence.url)})`]
+                        : []),
+                ]),
+                '',
+            ]),
+        `Best cards for ${title}${r.credits.length === 0 ? '' : ' by rate'}:`,
+        '',
+    ];
     shown.forEach((e, i) => {
         const earned = e.earned === null ? '' : `  ${dollarsAndCents(e.earned)}`;
         lines.push(`${String(i + 1).padStart(2)}. ${e.cardName.padEnd(width)}  ${pct(e.effectiveReturnPct).padStart(5)}${earned}  ${feeText(e)}`);
@@ -89,7 +105,7 @@ export function formatCatalogSimulation(r, catalog, all) {
     ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', "Assumes each card's best picks, activations done each quarter, and no welcome bonuses.");
+    lines.push('', `Assumes each card's best picks, activations done each quarter, and no welcome bonuses. ${CREDITS_LEFT_OUT}`);
     return `${lines.join('\n')}\n`;
 }
 export function formatAdditions(r, catalog, all) {
@@ -117,6 +133,6 @@ export function formatAdditions(r, catalog, all) {
     ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh. Annual fees are counted in full: statement credits and perks that offset them are left out. Each kind of spending lists the card that earns the most on it over the whole year, so a one-quarter bonus may not show.');
+    lines.push('', `Assumes your picks carry over, rotating categories get activated, and caps start fresh. Annual fees are counted in full: statement credits and perks that offset them are left out. ${CREDITS_LEFT_OUT} Each kind of spending lists the card that earns the most on it over the whole year, so a one-quarter bonus may not show.`);
     return `${lines.join('\n')}\n`;
 }

package/dist/format/recommendation.js

@@ -33,7 +33,8 @@ function cardLines(cards, style, bonusPick) {
         const earned = (c.earned === null ? '' : `  ${dollarsAndCents(c.earned)}`) +
             (c.milestoneBonus === null
                 ? ''
-                : ` + ${money(c.milestoneBonus.dollars)} spend bonus`);
+                : ` + ${money(c.milestoneBonus.dollars)} spend bonus`) +
+            (c.credit?.dollars ? ` + ${money(c.credit.dollars)} credit` : '');
         const pick = c.cardId === bonusPick ? '  ← the pick, for its welcome bonus' : '';
         lines.push(`  ${String(c.rank).padStart(String(rankWidth).length)}. ${label(c).padEnd(nameWidth)}  ${pct(c.effectiveReturnPct).padStart(pctWidth)}${earned}${pick}`);
         for (const r of c.reasoning)
@@ -59,9 +60,12 @@ export function formatRecommendation(rec, purchase, { all = false, style = plain
         const milestone = top.milestoneBonus === null
             ? ''
             : `, plus a spend bonus worth about ${money(top.milestoneBonus.dollars)}`;
+        const credit = top.credit?.dollars
+            ? `, plus ${money(top.credit.dollars)} back from its ${top.credit.name} credit`
+            : '';
         const confidence = rec.decision.confidence;
         const why = rec.bonus ? ' for its welcome bonus' : '';
-        lines.push(`${style('bold', `Use ${label(top)}${why}: ${pct(top.effectiveReturnPct)} back${earned}${milestone}.`)} ${capitalize(confidence)} confidence.`);
+        lines.push(`${style('bold', `Use ${label(top)}${why}: ${pct(top.effectiveReturnPct)} back${earned}${milestone}${credit}.`)} ${capitalize(confidence)} confidence.`);
         if (rec.bonus && rec.notes[0])
             lines.push(rec.notes[0]);
     }