earnrate 0.2.12 → 0.2.13

package/dist/engine/explore.js

@@ -1,12 +1,14 @@
 import { categoryResolution, resolvePlace } from "../merchants/resolve.js";
-import { evaluateCard, purchaseContext } from "./evaluate.js";
+import { creditCovers, creditPerYear } from "./credits.js";
+import { evaluateCard, paymentUpgrade, purchaseContext } from "./evaluate.js";
+import { creditName } from "./rule-text.js";
 import { membershipName, membershipNeeded, paidMemberships, } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { FOREIGN_ASSUMPTION, isForeign, recommend } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
 import { optionName } from "./rule-text.js";
-import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, earnText, listed, money, PICK_PERIODS, pointValuesText, } from "./text.js";
+import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, creditBack, creditThen, earnText, listed, money, PAYMENT_PHRASES, paidText, paymentUnknownText, PICK_PERIODS, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
@@ -163,11 +165,13 @@ export function exploreCards(catalog, query, options, resolved) {
         channel: query.channel,
         date: query.date,
         country: query.country ?? 'US',
+        payment: query.payment ?? null,
     };
     const ranked = [];
+    const ifPaid = new Map();
     const excluded = [];
     // A Costco purchase means a Costco member: no membership to point out.
-    const paid = paidMemberships(catalog, {
+    const members = paidMemberships(catalog, {
         memberships: options.memberships,
         merchantIds: [merchant.merchantId],
     });
@@ -177,7 +181,9 @@ export function exploreCards(catalog, query, options, resolved) {
         const picks = bestPicksForPurchase(catalog, card, merchant, purchase, options);
         const held = idealHolding(card, query.date, picks);
         const wallet = walletOf(held, options);
-        const rec = recommend(catalog, wallet, purchase, merchant);
+        const rec = recommend(catalog, wallet, purchase, merchant, {
+            credits: false,
+        });
         const top = rec.ranked[0];
         if (!top) {
             excluded.push(...rec.excluded);
@@ -185,6 +191,16 @@ export function exploreCards(catalog, query, options, resolved) {
         }
         const requirements = requirementsFor(catalog, card, held, wallet, merchant, purchase);
         const gap = rotationGap(card, query.date);
+        const paid = paymentUpgrade(card, held, purchaseContext(catalog, wallet, merchant, merchant.category, purchase), top.rate);
+        if (paid)
+            ifPaid.set(card.id, {
+                payment: paid.payment,
+                earn: earnText(catalog, paid.nominalRate, top.currency),
+                standard: earnText(catalog, top.rate, top.currency),
+                returnPct: paid.rate * top.centsPerUnit - (top.foreignFee ?? 0),
+            });
+        const payment = card.rules.find((r) => r.id === top.matchedRule)?.requires
+            ?.payment;
         const evidenceRule = top.matchedRule ?? 'base_rate';
         const evidence = card.evidence.find((e) => e.rule === evidenceRule);
         ranked.push({
@@ -203,7 +219,8 @@ export function exploreCards(catalog, query, options, resolved) {
             requirements,
             conditions: [
                 ...conditionsText(catalog, card, requirements),
-                ...membershipNeeded(catalog, card, paid),
+                ...(payment === undefined ? [] : [`Paid ${PAYMENT_PHRASES[payment]}.`]),
+                ...membershipNeeded(catalog, card, members),
             ],
             evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
             withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
@@ -212,13 +229,48 @@ export function exploreCards(catalog, query, options, resolved) {
     ranked.sort(compareExplored);
     return {
         merchant,
+        credits: creditPicks(catalog, merchant, ranked),
         ranked,
         excluded,
-        assumptions: exploreAssumptions(catalog, merchant, ranked, options, purchase),
+        assumptions: exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid),
         warnings: exploreWarnings(catalog, merchant),
     };
 }
-function exploreAssumptions(catalog, merchant, ranked, options, purchase) {
+function creditPicks(catalog, merchant, ranked) {
+    const picks = ranked.flatMap((entry) => {
+        const card = catalog.cards.find((c) => c.id === entry.cardId);
+        return ((card?.credits ?? [])
+            // A credit for a whole category (every restaurant) isn't a store's.
+            .filter((c) => c.match.merchants !== undefined &&
+            creditCovers(catalog, c, merchant))
+            .map((credit) => {
+            const earn = earnText(catalog, entry.rate, entry.currency);
+            const evidence = card?.evidence.find((e) => e.rule === credit.id);
+            return {
+                cardId: entry.cardId,
+                cardName: entry.cardName,
+                issuer: entry.issuer,
+                network: entry.network,
+                annualFee: entry.annualFee,
+                firstYearFee: entry.firstYearFee,
+                creditId: credit.id,
+                name: creditName(catalog, credit),
+                amount: credit.amount,
+                period: credit.period,
+                enroll: credit.enroll === true,
+                note: credit.note ?? null,
+                back: creditBack(credit),
+                earn,
+                text: creditThen(credit, earn),
+                evidence: evidence
+                    ? { quote: evidence.quote, url: evidence.url }
+                    : null,
+            };
+        }));
+    });
+    return picks.sort((a, b) => creditPerYear(b) - creditPerYear(a) || a.cardId.localeCompare(b.cardId));
+}
+function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid) {
     const assumptions = [];
     if (merchant.source === 'category') {
         assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
@@ -235,6 +287,17 @@ function exploreAssumptions(catalog, merchant, ranked, options, purchase) {
         assumptions.push(values);
     if (isForeign(purchase))
         assumptions.push(FOREIGN_ASSUMPTION);
+    if (purchase.payment)
+        assumptions.push(paidText(purchase.payment));
+    const top = ranked[0];
+    for (const entry of ranked) {
+        const paid = ifPaid.get(entry.cardId);
+        if (!paid || !top)
+            continue;
+        if (entry !== top && paid.returnPct <= top.effectiveReturnPct + EPSILON)
+            continue;
+        assumptions.push(paymentUnknownText(entry.cardName, paid.payment, paid.earn, paid.standard));
+    }
     return assumptions;
 }
 function exploreWarnings(catalog, merchant) {

package/dist/engine/offers.js

@@ -2,7 +2,7 @@ import { bonusDollars } from "./bonus.js";
 import { matchesFilters } from "./explore.js";
 import { membershipCosts, paidMemberships } from "./memberships.js";
 import { inEffect } from "./periods.js";
-import { money, roundCents } from "./text.js";
+import { CREDITS_LEFT_OUT, money, roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
 function ineligibleText(catalog, wallet, notWith) {
     const held = wallet.cards
@@ -83,6 +83,7 @@ export function compareOffers(catalog, wallet, filters, today) {
         `Compares the ${String(catalog.cards.length)} cards earnrate knows, not every card on the market.`,
         `Each offer is the public one on the issuer's page on the date shown, checked weekly. ${OFFERS_MAY_DIFFER} Issuers also limit who can get a bonus; each card's note says how.`,
         "First-year value is the bonus at your point values minus the first year's annual fee and any membership the card needs that you don't have. It leaves out what the card earns on your spending and any credits or perks.",
+        CREDITS_LEFT_OUT,
     ];
     return { offers, withoutOffer, notes };
 }

package/dist/engine/periods.js

@@ -1,6 +1,7 @@
-// Keys match the wallet's PeriodKey format: "2026" or "2026-Q4". A cardmember
-// year is keyed by the calendar year it started in. Returns null when a
-// cardmember year is asked for without an anniversary (MM-DD).
+// Keys match the wallet's PeriodKey format: "2026", "2026-Q4" or "2026-H2"
+// (July to December). A cardmember year is keyed by the calendar year it
+// started in. Returns null when a cardmember year is asked for without an
+// anniversary (MM-DD).
 export function periodKey(period, date, anniversary) {
     const year = Number(date.slice(0, 4));
     const month = Number(date.slice(5, 7));
@@ -11,6 +12,8 @@ export function periodKey(period, date, anniversary) {
             return String(year);
         case 'quarter':
             return `${String(year)}-Q${String(Math.floor((month - 1) / 3) + 1)}`;
+        case 'half_year':
+            return `${String(year)}-H${month <= 6 ? '1' : '2'}`;
         case 'cardmember_year':
             if (anniversary === null)
                 return null;
@@ -57,6 +60,10 @@ export function periodEnd(period, key, anniversary) {
             const q = /^(\d{4})-Q([1-4])$/.exec(key);
             return q ? utcDay(Number(q[1]), Number(q[2]) * 3 + 1, 0) : null;
         }
+        case 'half_year': {
+            const h = /^(\d{4})-H([12])$/.exec(key);
+            return h ? utcDay(Number(h[1]), Number(h[2]) * 6 + 1, 0) : null;
+        }
         case 'calendar_year':
             return /^\d{4}$/.test(key) ? `${key}-12-31` : null;
         case 'cardmember_year': {

package/dist/engine/recommend.js

@@ -1,14 +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, introRateText, introUnknownText, 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.
@@ -42,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 = [];
@@ -92,6 +93,14 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
                 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,
@@ -100,10 +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,
-            ifNew,
+            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);
@@ -133,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
@@ -218,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),
@@ -262,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)}¢).`);
             }
@@ -292,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)})`]
                 : [];
         });
@@ -310,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.');
     }
@@ -318,7 +357,18 @@ 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;
@@ -333,8 +383,8 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
             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 = [];
@@ -358,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;
@@ -385,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)}).`);
@@ -410,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)}.`);
         }
@@ -447,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
@@ -112,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, 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.
@@ -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,7 +57,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 +75,10 @@ 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".
+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,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 } 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
@@ -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 } 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) {