earnrate 0.2.12 → 0.2.14

package/dist/engine/evaluate.js

@@ -1,17 +1,23 @@
+import { merchantFamily } from "../merchants/resolve.js";
+import { EPSILON } from "./compare.js";
 import { introCovers, introWindows, withIntro, } from "./intro.js";
 import { inEffect, periodKey } from "./periods.js";
+// PayPal checkout happens online, so paying through it says the channel.
+export const paymentChannel = (channel, payment) => channel ?? (payment === 'paypal' ? 'online' : null);
 export function purchaseContext(catalog, wallet, merchant, category, purchase) {
+    const payment = purchase.payment ?? null;
     return {
         category,
-        merchantId: merchant.merchantId,
+        merchantIds: merchantFamily(catalog, merchant.merchantId),
         mcc: category === merchant.category && merchant.likelyMcc !== null
             ? merchant.likelyMcc
             : singleMcc(catalog, category),
-        channel: merchant.channel,
+        channel: paymentChannel(merchant.channel, payment),
         country: purchase.country,
         date: purchase.date,
         amount: purchase.amount,
         memberships: new Set(wallet.memberships),
+        payment,
     };
 }
 // A category with one typical MCC (travel agencies are 4722) implies it, the
@@ -79,18 +85,16 @@ export function isActivated(card, held, ruleId) {
 function applicability(card, rule, ctx, held, picked) {
     const { match, exclude } = rule;
     const inCategory = (cats) => cats.some((c) => categoryMatches(c, ctx.category));
+    const named = (ids) => ids?.some((id) => ctx.merchantIds.includes(id)) ?? false;
     if (match.categories?.length && !inCategory(match.categories))
         return 'no';
-    if (match.merchants?.length &&
-        !(ctx.merchantId !== null && match.merchants.includes(ctx.merchantId))) {
+    if (match.merchants?.length && !named(match.merchants))
         return 'no';
-    }
     if (match.mccs?.length && !(ctx.mcc !== null && match.mccs.includes(ctx.mcc)))
         return 'no';
     if (match.choice !== undefined) {
         const covered = picked.get(match.choice);
-        const merchantPicked = ctx.merchantId !== null &&
-            (covered?.merchants.includes(ctx.merchantId) ?? false);
+        const merchantPicked = named(covered?.merchants);
         const onlinePicked = ctx.channel === 'online' &&
             (covered?.online.some((o) => !inCategory(o.exclude)) ?? false);
         if (!merchantPicked &&
@@ -100,13 +104,14 @@ function applicability(card, rule, ctx, held, picked) {
     }
     if (exclude?.categories && inCategory(exclude.categories))
         return 'no';
-    if (exclude?.merchants &&
-        ctx.merchantId !== null &&
-        exclude.merchants.includes(ctx.merchantId)) {
+    if (named(exclude?.merchants))
         return 'no';
-    }
     if (exclude?.mccs && ctx.mcc !== null && exclude.mccs.includes(ctx.mcc))
         return 'no';
+    if (exclude?.payment &&
+        ctx.payment !== null &&
+        exclude.payment.includes(ctx.payment))
+        return 'no';
     if (rule.channel !== 'any' && rule.channel !== ctx.channel)
         return 'no';
     if (rule.geography === 'us_only' && ctx.country !== 'US')
@@ -118,6 +123,9 @@ function applicability(card, rule, ctx, held, picked) {
     const membership = rule.requires?.membership;
     if (membership !== undefined && !ctx.memberships.has(membership))
         return 'no';
+    const payment = rule.requires?.payment;
+    if (payment !== undefined && ctx.payment !== payment)
+        return 'no';
     if (rule.requires?.activation && !isActivated(card, held, rule.id))
         return 'needs-activation';
     return 'applies';
@@ -222,3 +230,22 @@ export function evaluateCard(card, held, ctx) {
         staleChoice,
     };
 }
+// The way of paying (one a rule on the card requires) that would earn the
+// most on this purchase, when that beats `rate`. Only while the purchase
+// doesn't say how it's paid.
+export function paymentUpgrade(card, held, ctx, rate) {
+    if (ctx.payment !== null)
+        return null;
+    let best = null;
+    const methods = new Set(card.rules.flatMap((r) => r.requires?.payment === undefined ? [] : [r.requires.payment]));
+    for (const payment of methods) {
+        const paid = evaluateCard(card, held, {
+            ...ctx,
+            payment,
+            channel: paymentChannel(ctx.channel, payment),
+        }).best;
+        if (paid.rate > (best?.rate ?? rate) + EPSILON)
+            best = { payment, rate: paid.rate, nominalRate: paid.nominalRate };
+    }
+    return best;
+}

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 { FOREIGN_ASSUMPTION, foreignFeeFor, 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 = {
@@ -129,7 +131,7 @@ function membershipUpgrades(catalog, card, held, merchant, purchase, options, cu
             memberships: [...options.memberships, membership],
         });
         const ctx = purchaseContext(catalog, wallet, merchant, merchant.category, purchase);
-        const fee = isForeign(purchase) ? (card.foreign_transaction_fee ?? 0) : 0;
+        const fee = foreignFeeFor(card, purchase);
         const pct = evaluateCard(card, held, ctx).best.rate *
             cardValuation(catalog, wallet, card).centsPerUnit -
             fee;
@@ -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,19 +1,26 @@
-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 { openedOn } from "./intro.js";
+import { evaluateCard, paymentUpgrade, purchaseContext, usableAt, } from "./evaluate.js";
+import { introWindows, openedOn, withIntro } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestonePoints, milestonesReached, reachedText, } from "./milestones.js";
 import { daysBetween } from "./periods.js";
+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, possessive, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 export const STALE_AFTER_DAYS = 180;
 // The engine only tells the U.S. from everywhere else.
 export const FOREIGN_ASSUMPTION = 'Treats this as a purchase outside the U.S.: each card is ranked after its foreign transaction fee.';
 export const isForeign = (purchase) => purchase.country !== 'US';
+// A fee that isn't on file counts as the usual 3%, so a card can't win
+// abroad on a guess that it charges none.
+export const ASSUMED_FOREIGN_FEE = 3;
+export const foreignFeeFor = (card, purchase) => isForeign(purchase)
+    ? (card.foreign_transaction_fee ?? ASSUMED_FOREIGN_FEE)
+    : 0;
 // Any purchase outside the U.S., when no country is named: ZZ is a code ISO
 // leaves unassigned, and nothing prints it.
 export const ABROAD = 'ZZ';
@@ -42,7 +49,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 = [];
@@ -78,8 +85,7 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
         const bonusPoints = milestonePoints(milestones);
         const perDollar = evaluation.best.rate +
             (bonusPoints > 0 && purchase.amount ? bonusPoints / purchase.amount : 0);
-        // An unknown fee isn't guessed: it's warned about instead.
-        const fee = isForeign(purchase) ? (card.foreign_transaction_fee ?? 0) : 0;
+        const fee = foreignFeeFor(card, purchase);
         const fresh = card.intro_rates.length > 0 && openedOn(held) === null
             ? evaluateCard(card, { ...held, opened: purchase.date }, ctx).best
             : null;
@@ -92,6 +98,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 +114,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);
@@ -114,18 +143,19 @@ function reasoningFor(catalog, wallet, entry, amount) {
     const { best } = evaluation;
     const lines = [];
     const currency = valuation.currency;
+    // The standard rate first; a first-year rate on top of it is its own line.
+    // The intro's terms stay in search_cards, not in every answer.
+    const [intro] = best.intro;
+    const standard = earnText(catalog, intro ? best.standardRate : best.nominalRate, currency);
     if (best.rule) {
         const note = best.rule.note ? ` ${best.rule.note}` : '';
-        lines.push(`${earnText(catalog, best.nominalRate, currency)} on ${ruleWhat(catalog, best.rule)}${best.rule.requires?.membership === undefined ? '' : `, with ${membershipName(catalog, best.rule.requires.membership)}`}.${note}`);
+        lines.push(`${standard} on ${ruleWhat(catalog, best.rule)}${best.rule.requires?.membership === undefined ? '' : `, with ${membershipName(catalog, best.rule.requires.membership)}`}.${note}`);
     }
     else {
-        lines.push(`${earnText(catalog, best.nominalRate, currency)}, its base rate. No bonus category applies here.`);
-    }
-    const [intro] = best.intro;
-    if (intro) {
-        const note = intro.intro.note ? ` ${intro.intro.note}` : '';
-        lines.push(`${introRateText(earnText(catalog, best.nominalRate, currency), earnText(catalog, best.standardRate, currency), intro.intro.days, intro.until)}${note}`);
+        lines.push(`${standard}, its base rate. No bonus category applies here.`);
     }
+    if (intro)
+        lines.push(introRateText(earnText(catalog, best.nominalRate, currency), standard, intro.intro.days, intro.until));
     const cap = best.cap;
     if (cap && amount !== null && amount > cap.remaining) {
         const over = amount - cap.remaining;
@@ -133,6 +163,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
@@ -151,10 +183,10 @@ function warningsFor(catalog, entry, purchase) {
     const { card, valuation, evaluation } = entry;
     const { best, nominal } = evaluation;
     const warnings = [];
-    if (entry.fee > 0)
-        warnings.push(`Charges a ${pct(entry.fee)} foreign transaction fee here, so it nets ${pct(entry.rateReturnPct)}.`);
     if (isForeign(purchase) && card.foreign_transaction_fee === null)
-        warnings.push("Its foreign transaction fee isn't on file, so none is subtracted. Check the issuer's terms before using it abroad.");
+        warnings.push(`Its foreign transaction fee isn't on file, so earnrate assumes the usual ${pct(entry.fee)} and it nets ${pct(entry.rateReturnPct)}. Check the issuer's terms before using it abroad.`);
+    else if (entry.fee > 0)
+        warnings.push(`Charges a ${pct(entry.fee)} foreign transaction fee here, so it nets ${pct(entry.rateReturnPct)}.`);
     const capLabel = (e) => e.cap
         ? `${money(e.cap.cap.amount)} ${CAP_ADJECTIVES[e.cap.cap.period]} cap`
         : '';
@@ -186,12 +218,14 @@ function warningsFor(catalog, entry, purchase) {
     if (evaluation.staleChoice !== null) {
         warnings.push(`Your chosen categories are set for ${evaluation.staleChoice}, not the current period, so chosen-category bonuses don't apply until you update them.`);
     }
+    const windows = introWindows(card, entry.held, purchase.date);
     for (const rule of evaluation.needsActivation) {
+        const rate = earnText(catalog, withIntro(rule.rate, rule.id, windows), valuation.currency);
         if (rule.activate_by !== undefined && rule.activate_by < purchase.date) {
-            warnings.push(`The bonus here (${earnText(catalog, rule.rate, valuation.currency)}) needed activating by ${shortDate(rule.activate_by)}.`);
+            warnings.push(`The bonus here (${rate}) needed activating by ${shortDate(rule.activate_by)}.`);
             continue;
         }
-        warnings.push(`Activate this bonus with the issuer (it's free)${rule.activate_by === undefined ? '' : ` by ${shortDate(rule.activate_by)}`} to earn ${earnText(catalog, rule.rate, valuation.currency)} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
+        warnings.push(`Activate this bonus with the issuer (it's free)${rule.activate_by === undefined ? '' : ` by ${shortDate(rule.activate_by)}`} to earn ${rate} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
     }
     return warnings;
 }
@@ -218,6 +252,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 +306,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 +337,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 +354,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 +365,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,15 +391,18 @@ 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 = [];
     const notes = [];
-    const charging = entries.filter((e) => e.fee > 0);
+    const charging = entries.filter((e) => e.fee > 0 && e.card.foreign_transaction_fee !== null);
+    const assumed = entries.filter((e) => e.fee > 0 && e.card.foreign_transaction_fee === null);
     if (charging.length > 0 && entries.length > 1)
         notes.push(`${listed(charging.map((e) => `${displayName(e)} (${pct(e.fee)})`))} ${charging.length === 1 ? 'charges a foreign transaction fee' : 'charge foreign transaction fees'} here, already subtracted in the ranking.`);
+    if (assumed.length > 0 && entries.length > 1)
+        notes.push(`${listed(assumed.map(displayName))} ${assumed.length === 1 ? 'has' : 'have'} no foreign transaction fee on file, so the usual ${pct(ASSUMED_FOREIGN_FEE)} is subtracted.`);
     if (merchant.source === 'none') {
         warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. If you know what kind of business it is, give its category (like dining or grocery) to find bonus rates.`);
     }
@@ -358,7 +419,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 +446,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)}).`);
@@ -403,15 +464,14 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const gap = card ? rotationGap(card, purchase.date) : null;
         if (card && gap !== null) {
             const name = held.checkout_label ?? card.name;
-            warnings.push(`${name}'s rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them. If this purchase is in that period's categories, ${name} may earn more. An earnrate update adds them once the issuer announces them.`);
+            warnings.push(`${possessive(name)} rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them. If this purchase is in that period's categories, ${name} may earn more. An earnrate update adds them once the issuer announces them.`);
         }
     }
     for (const id of merchant.bookedVia) {
         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 +507,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,
@@ -464,7 +527,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const worth = status.value === null ? '' : `, worth about ${wholeDollars(status.value)}`;
         notes.unshift(ties
             ? `${displayName(bonus.entry)} earns as much here as any of your cards, so it's the pick: it helps its welcome bonus, ${money(remaining)} more to spend by ${deadline}${worth}.`
-            : `You're behind pace on ${displayName(bonus.entry)}'s welcome bonus: ${money(remaining)} more to spend by ${deadline}${pace}${worth}.${isBest
+            : `You're behind pace on ${possessive(displayName(bonus.entry))} welcome bonus: ${money(remaining)} more to spend by ${deadline}${pace}${worth}.${isBest
                 ? ''
                 : costHere === null
                     ? ` It earns ${pct(top.effectiveReturnPct)} here against ${pct(first.effectiveReturnPct)} on ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`