earnrate 0.2.16 → 0.2.18

package/dist/engine/changes.js

@@ -0,0 +1,124 @@
+import { offerTerms } from "./offers.js";
+import { creditName, ruleWhat } from "./rule-text.js";
+import { creditBack, currencyName, earnText, money, pct, possessive, shortCardName, shortDate, } from "./text.js";
+// Newest first.
+export function datedChanges(releases) {
+    return releases
+        .flatMap((r) => r.changes.map((change) => ({
+        version: r.version,
+        date: change.date ?? r.date,
+        change,
+    })))
+        .sort((a, b) => (a.date === b.date ? 0 : a.date < b.date ? 1 : -1));
+}
+export const issuerChanges = (releases) => datedChanges(releases).filter((d) => d.change.cause === 'issuer');
+export function subjectOf(catalog, kind, id) {
+    switch (kind) {
+        case 'cards':
+            return catalog.cards.find((c) => c.id === id);
+        case 'merchants':
+            return [...catalog.merchants.seed, ...catalog.merchants.overrides].find((m) => m.id === id);
+        case 'categories':
+            return catalog.categories.find((c) => c.id === id);
+        case 'currencies':
+            return catalog.currencies.find((c) => c.id === id);
+        case 'memberships':
+            return catalog.memberships.find((m) => m.id === id);
+        case 'issuers':
+            return catalog.issuers.find((i) => i.id === id);
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// `rules.amazon.rate` on a card: list items are found by their id.
+export function fieldValue(subject, field) {
+    if (field === undefined)
+        return subject;
+    let value = subject;
+    for (const step of field.split('.')) {
+        if (Array.isArray(value))
+            value = value.find((item) => isRecord(item) && item.id === step);
+        else if (isRecord(value))
+            value = value[step];
+        else
+            return undefined;
+    }
+    return value;
+}
+const NO_SPEND = ' with no spending required';
+// Mid-sentence: "up to 80,000 points".
+const lower = (text) => text.replace(/^Up to /, 'up to ');
+// Only the part that changed is said twice: "$150 → $200 with no spending
+// required", "80,000 points after $3,000 … → after $2,000 …".
+function offerChange(catalog, card, was, now) {
+    const units = currencyName(catalog, card.currency);
+    const terms = (o) => lower(offerTerms(o, units));
+    const amount = (o) => lower(offerTerms({ ...o, spend: 0, months: 1 }, units)).slice(0, -NO_SPEND.length);
+    const tail = (o) => terms(o).slice(amount(o).length);
+    if (tail(was) === tail(now))
+        return `${amount(was)} → ${terms(now)}`;
+    if (amount(was) === amount(now))
+        return `${terms(was)} → ${tail(now).trim()}`;
+    return `${terms(was)} → ${terms(now)}`;
+}
+const feeWords = (fee) => typeof fee === 'number' ? (fee === 0 ? 'none' : money(fee)) : 'not on file';
+// "Prime Visa's welcome offer: $150 → $200 with no spending required": one
+// plain line for an issuer change, from its old and new values.
+export function changeHeadline(catalog, change) {
+    const id = change.cards?.[0] ?? '';
+    const card = catalog.cards.find((c) => c.id === id);
+    if (!card || change.field === undefined)
+        throw new Error(`no headline for a change to ${id}`);
+    const name = possessive(card.short_name ?? shortCardName(card.name));
+    const [kind, item] = change.field.split('.');
+    const { was, now } = change;
+    switch (kind) {
+        case 'welcome_offer':
+            if (was === null)
+                return `${name} new welcome offer: ${terms(now)}`;
+            if (now === null)
+                return `${name} welcome offer ended: ${terms(was)}`;
+            return `${name} welcome offer: ${offerChange(catalog, card, was, now)}`;
+        case 'annual_fee':
+        case 'first_year_fee':
+            return `${name} ${kind === 'annual_fee' ? 'annual fee' : 'first-year fee'}: ${feeWords(was)} → ${feeWords(now)}`;
+        case 'foreign_transaction_fee': {
+            const fee = (v) => typeof v === 'number' ? (v === 0 ? 'none' : pct(v)) : 'not on file';
+            return `${name} foreign transaction fee: ${fee(was)} → ${fee(now)}`;
+        }
+        case 'applications_closed':
+            return `${name} applications closed ${shortDate(String(now))}`;
+        case 'rules': {
+            const rule = (card.rules.find((r) => r.id === item) ?? now ?? was);
+            const rate = (v) => v === null
+                ? 'none'
+                : earnText(catalog, typeof v === 'number' ? v : v.rate, card.currency);
+            return `${name} rate ${ruleWhat(catalog, rule, card)}: ${rate(was)} → ${rate(now)}`;
+        }
+        case 'credits': {
+            const credit = (card.credits.find((c) => c.id === item) ??
+                now ??
+                was);
+            const back = (v) => v === null ? 'none' : creditBack(v);
+            return `${name} ${creditName(catalog, credit)} credit: ${back(was)} → ${back(now)}`;
+        }
+    }
+    throw new Error(`no headline for an issuer change to ${change.field}`);
+    function terms(o) {
+        return lower(offerTerms(o, currencyName(catalog, card?.currency ?? '')));
+    }
+}
+export function freshness(catalog, releases) {
+    const verified = catalog.cards.map((c) => c.last_verified).sort();
+    const first = releases.at(-1);
+    const latest = releases[0];
+    if (!first || !latest)
+        throw new Error('no data releases');
+    return {
+        issuerChanges: issuerChanges(releases).length,
+        since: first.date,
+        latestRelease: latest.date,
+        latestVersion: latest.version,
+        reviewedFrom: verified[0] ?? '',
+        reviewedTo: verified.at(-1) ?? '',
+    };
+}

package/dist/engine/checklist.js

@@ -1,15 +1,28 @@
 import { addDays, currentPeriodEnd, daysBetween } from "./periods.js";
-import { CAP_PERIODS, choiceName, enrollCreditText, introEndsText, listed, money, shortDate, useCreditText, wholeDollars, possessive, } from "./text.js";
+import { CAP_PERIODS, choiceName, askCreditText, enrollCreditText, introEndsText, listed, money, shortDate, renewalText, useCreditText, wholeDollars, possessive, } from "./text.js";
 import { milestonePays } from "./milestones.js";
-import { optionName } from "./rule-text.js";
+import { renewalCheck, renewalDue } from "./renewal.js";
+import { creditLabel, optionName } from "./rule-text.js";
 import { activationsDue, walletSummary, } from "./wallet-summary.js";
+// Node-free: earnrate.dev builds the same list from its browser wallet.
+const issuerLabel = (catalog, id) => catalog.issuers.find((i) => i.id === id)?.name ?? id;
+// "5% and 2% categories", "top category": a choice already named for its
+// category isn't followed by "categories" again.
+function pickWhat(names) {
+    const [only] = names;
+    if (names.length === 1 && only !== undefined && / category$/.test(only))
+        return only;
+    return `${listed(names)} categories`;
+}
 // What the wallet's cards need this period, soonest first: bonuses to
 // activate, categories to pick, caps running low, welcome bonuses to finish,
 // merchant credits to enroll in or use, and rotating categories the issuer
 // hasn't posted yet.
 export function checklist(catalog, wallet, today, summary = walletSummary(catalog, wallet, today), 
 // A shorter card name than the issuer's full one, where the caller has it.
-shortName) {
+shortName, 
+// For the renewal check; typical amounts when not given.
+spending) {
     const items = [];
     for (const held of wallet.cards) {
         const card = catalog.cards.find((c) => c.id === held.id);
@@ -41,7 +54,7 @@ shortName) {
             items.push({
                 kind: 'pick',
                 cardId: card.id,
-                text: `Pick ${possessive(name)} ${listed(unpicked.map((c) => choiceName(c.id)))} categories for this ${first.period.replace('_', ' ')}; until then they earn the base rate.`,
+                text: `Pick ${possessive(name)} ${pickWhat(unpicked.map((c) => choiceName(c.id)))} for this ${first.period.replace('_', ' ')}; until then they earn the base rate.`,
                 due,
             });
         }
@@ -66,7 +79,7 @@ shortName) {
             items.push({
                 kind: 'pick',
                 cardId: card.id,
-                text: `${possessive(name)} ${listed(assumed.map((c) => choiceName(c.id)))} pick is assumed to be ${listed(assumed.flatMap((c) => (c.default ?? []).map((o) => optionName(catalog, card, c.id, o))))}; set it if you picked something else.`,
+                text: `${possessive(name)} ${listed(assumed.map((c) => choiceName(c.id)))} pick is assumed to be ${listed(assumed.flatMap((c) => (c.default ?? []).map((o) => optionName(catalog, card, c.id, o))))}; set it if ${assumed.every((c) => c.automatic) ? 'you expect another to have the most spending' : 'you picked something else'}.`,
                 due: null,
             });
         for (const cap of s.caps) {
@@ -94,7 +107,19 @@ shortName) {
                 due: m.until,
             });
         }
-        const toEnroll = s.credits.filter((c) => !c.enrolled);
+        const toAsk = s.credits.filter((c) => !c.enroll && !c.confirmed && !c.skipped);
+        if (toAsk.length > 0)
+            items.push({
+                kind: 'enroll',
+                cardId: card.id,
+                ref: toAsk.map((c) => c.id).join(','),
+                text: askCreditText(name, toAsk.map((c) => {
+                    const credit = card.credits.find((x) => x.id === c.id);
+                    return credit ? creditLabel(catalog, credit) : c.name;
+                })),
+                due: null,
+            });
+        const toEnroll = s.credits.filter((c) => !c.enrolled && !c.skipped);
         if (toEnroll.length > 0)
             items.push({
                 kind: 'enroll',
@@ -104,7 +129,7 @@ shortName) {
                 due: null,
             });
         for (const c of s.credits) {
-            if (!c.enrolled)
+            if (!c.enrolled || c.skipped)
                 continue;
             // One that needs no enrolling shows once the cardholder uses it, so a
             // card's every credit isn't a to-do for someone who never shops there.
@@ -138,6 +163,16 @@ shortName) {
                 text: introEndsText(name, s.intro.days, s.intro.until),
                 due: s.intro.until,
             });
+        const due = (card.annual_fee ?? 0) > 0 ? renewalDue(held, today) : null;
+        if (due !== null) {
+            const r = renewalCheck(catalog, wallet, card, due, spending);
+            items.push({
+                kind: 'renewal',
+                cardId: card.id,
+                text: renewalText(name, issuerLabel(catalog, card.issuer), r),
+                due,
+            });
+        }
         if (s.rotationGap !== null) {
             items.push({
                 kind: 'rotation',

package/dist/engine/credits.js

@@ -1,7 +1,7 @@
 import { merchantFamily } from "../merchants/resolve.js";
 import { categoryMatches } from "./evaluate.js";
-import { periodEnd, periodKey } from "./periods.js";
-import { creditName } from "./rule-text.js";
+import { inEffect, periodEnd, periodKey } from "./periods.js";
+import { creditLabel, creditName } from "./rule-text.js";
 import { roundCents } from "./text.js";
 // Only a store itself has a credit: a search for a kind of purchase
 // ("clothing") never does.
@@ -16,6 +16,15 @@ export function creditCovers(catalog, credit, merchant) {
 }
 // A credit that needs enrolling counts only once the wallet says it's done.
 const isEnrolled = (credit, held) => credit.enroll !== true || (held.enrolled ?? []).includes(credit.id);
+// The cardholder said they don't use it: it counts nowhere, enrolled or not.
+export const isSkipped = (credit, held) => (held.skipped_credits ?? []).includes(credit.id);
+// The cardholder said they use it: it's in `enrolled` (for one that needs
+// no enrolling, that means "using it"), or one that needs no enrolling has
+// already paid out. Until then a credit doesn't offset the annual fee.
+export const creditConfirmed = (credit, held) => (held.enrolled ?? []).includes(credit.id) ||
+    (credit.enroll !== true && held.credit_usage?.[credit.id] !== undefined);
+// A credit that counts against the fee: confirmed and not skipped.
+export const creditInUse = (credit, held) => creditConfirmed(credit, held) && !isSkipped(credit, held);
 function creditState(catalog, credit, held, date) {
     const anniversary = held.anniversary ?? null;
     const period = periodKey(credit.period, date, anniversary);
@@ -30,18 +39,23 @@ function creditState(catalog, credit, held, date) {
         amount: credit.amount,
         period: credit.period,
         enrolled: isEnrolled(credit, held),
+        skipped: isSkipped(credit, held),
+        confirmed: creditConfirmed(credit, held),
         used,
+        minAmount: credit.min_amount ?? null,
         left: period === null ? null : roundCents(Math.max(0, credit.amount - used)),
         until: period === null ? null : periodEnd(credit.period, period, anniversary),
     };
 }
-export const creditStates = (catalog, card, held, date) => card.credits.map((c) => creditState(catalog, c, held, date));
-export const counts = (s) => s.enrolled && s.left !== null && s.left > 0;
+// The card's credits the issuer still offers on `date`.
+export const liveCredits = (card, date) => card.credits.filter((c) => inEffect(c, date));
+export const creditStates = (catalog, card, held, date) => liveCredits(card, date).map((c) => creditState(catalog, c, held, date));
+export const counts = (s) => s.enrolled && !s.skipped && s.left !== null && s.left > 0;
 // The card's credit at this merchant, if any: one that counts first, then
-// the one with the most left.
+// the one with the most left. A skipped credit isn't mentioned at all.
 export function creditAt(catalog, card, held, merchant, date) {
-    const here = card.credits
-        .filter((c) => creditCovers(catalog, c, merchant))
+    const here = liveCredits(card, date)
+        .filter((c) => !isSkipped(c, held) && creditCovers(catalog, c, merchant))
         .map((c) => creditState(catalog, c, held, date))
         .sort((a, b) => Number(counts(b)) - Number(counts(a)) || (b.left ?? 0) - (a.left ?? 0));
     return here[0] ?? null;
@@ -53,6 +67,8 @@ export function creditDollars(s, amount) {
         return null;
     if (!counts(s) || amount <= 0)
         return 0;
+    if (s.credit.min_amount !== undefined && amount < s.credit.min_amount)
+        return 0;
     return roundCents(Math.min(amount, s.left ?? 0));
 }
 const PER_YEAR = {
@@ -62,4 +78,37 @@ const PER_YEAR = {
     calendar_year: 1,
     cardmember_year: 1,
 };
+const monthIndex = (date) => Number(date.slice(0, 4)) * 12 + Number(date.slice(5, 7)) - 1;
+// How many times the credit pays in the 12 months from `date`, counting the
+// period `date` is in: every period's, or for a credit that ends, those that
+// start by its last day.
+function payoutsAYear(credit, date) {
+    const all = PER_YEAR[credit.period];
+    if (credit.valid_to === undefined)
+        return all;
+    if (!inEffect(credit, date))
+        return 0;
+    if (all === 1)
+        return 1;
+    const step = 12 / all;
+    const first = monthIndex(date) - (monthIndex(date) % step);
+    const starts = Math.floor((monthIndex(credit.valid_to) - first) / step) + 1;
+    return Math.min(all, starts);
+}
+// Dollars a year at face value, the most first: for ordering cards by credit.
 export const creditPerYear = (c) => c.amount * PER_YEAR[c.period];
+function creditsYear(catalog, card, credits, date) {
+    const live = credits.filter((c) => inEffect(c, date));
+    return {
+        cardId: card.id,
+        yearly: roundCents(live.reduce((sum, c) => sum + c.amount * payoutsAYear(c, date), 0)),
+        creditIds: live.map((c) => c.id),
+        names: live.map((c) => creditLabel(catalog, c)),
+    };
+}
+// Every credit on the card, as if each were used in full: for a card the
+// person doesn't hold.
+export const allCreditsYear = (catalog, card, date) => creditsYear(catalog, card, card.credits, date);
+// The credits a cardholder uses, in full each period: what counts against
+// the fee of a card they hold.
+export const usedCreditsYear = (catalog, card, held, date) => creditsYear(catalog, card, card.credits.filter((c) => creditInUse(c, held)), date);

package/dist/engine/evaluate.js

@@ -1,6 +1,7 @@
 import { merchantFamily } from "../merchants/resolve.js";
 import { EPSILON } from "./compare.js";
 import { introCovers, introWindows, withIntro, } from "./intro.js";
+import { effectiveMemberships } from "./memberships.js";
 import { inEffect, periodKey } from "./periods.js";
 // PayPal checkout happens online, so paying through it says the channel.
 const paymentChannel = (channel, payment) => channel ?? (payment === 'paypal' ? 'online' : null);
@@ -16,7 +17,7 @@ export function purchaseContext(catalog, wallet, merchant, category, purchase) {
         country: purchase.country,
         date: purchase.date,
         amount: purchase.amount,
-        memberships: new Set(wallet.memberships),
+        memberships: new Set(effectiveMemberships(catalog, wallet.memberships, wallet.cards.map((c) => c.id))),
         payment,
     };
 }
@@ -120,6 +121,9 @@ function applicability(card, rule, ctx, held, picked) {
         return 'no';
     if (!inEffect(rule, ctx.date))
         return 'no';
+    if (rule.min_amount !== undefined &&
+        (ctx.amount === null || ctx.amount < rule.min_amount))
+        return 'no';
     const membership = rule.requires?.membership;
     if (membership !== undefined && !ctx.memberships.has(membership))
         return 'no';
@@ -249,3 +253,19 @@ export function paymentUpgrade(card, held, ctx, rate) {
     }
     return best;
 }
+// The smallest purchase amount (one a rule on the card asks for) that would
+// earn more than `rate`, and what it would earn. Only while the purchase has
+// no amount.
+export function amountUpgrade(card, held, ctx, rate) {
+    if (ctx.amount !== null)
+        return null;
+    const amounts = [
+        ...new Set(card.rules.flatMap((r) => r.min_amount ?? [])),
+    ].sort((a, b) => a - b);
+    for (const amount of amounts) {
+        const larger = evaluateCard(card, held, { ...ctx, amount }).best;
+        if (larger.rate > rate + EPSILON)
+            return { amount, rate: larger.rate, nominalRate: larger.nominalRate };
+    }
+    return null;
+}

package/dist/engine/explore.js

@@ -1,6 +1,6 @@
 import { categoryResolution, resolvePlace } from "../merchants/resolve.js";
-import { creditCovers, creditPerYear } from "./credits.js";
-import { evaluateCard, paymentUpgrade, purchaseContext } from "./evaluate.js";
+import { creditCovers, creditPerYear, liveCredits } from "./credits.js";
+import { amountUpgrade, 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";
@@ -8,7 +8,7 @@ import { FOREIGN_ASSUMPTION, foreignFeeFor, isForeign, recommend, } from "./reco
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
 import { optionName } from "./rule-text.js";
-import { categoryPhrase, choiceName, codesAs, creditBack, creditThen, earnText, listed, PAYMENT_PHRASES, paidText, paymentUnknownText, PICK_PERIODS, pointValuesText, capSentence, } from "./text.js";
+import { amountUnknownText, capSentence, categoryPhrase, choiceName, codesAs, creditBack, creditThen, creditTerms, earnText, listed, paidText, PAYMENT_PHRASES, paymentUnknownText, pickCondition, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
@@ -93,7 +93,12 @@ function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
     const cap = best.cap?.cap;
     return {
         pick: choice && picked
-            ? { choice: choice.id, options: picked, period: choice.period }
+            ? {
+                choice: choice.id,
+                options: picked,
+                period: choice.period,
+                automatic: choice.automatic === true,
+            }
             : null,
         activation: rule.requires?.activation === true ? rule.id : null,
         membership: rule.requires?.membership ?? null,
@@ -110,7 +115,7 @@ function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
 function conditionsText(catalog, card, r) {
     const conditions = [];
     if (r.pick) {
-        conditions.push(`Needs ${r.pick.options.map((o) => optionName(catalog, card, r.pick?.choice ?? '', o)).join(' or ')} as its ${choiceName(r.pick.choice)} pick (${r.pick.period === 'until_changed' ? '' : 'picked '}${PICK_PERIODS[r.pick.period]}).`);
+        conditions.push(`${pickCondition({ pick: card.choices.find((c) => c.id === r.pick?.choice)?.pick ?? 1, ...r.pick }, r.pick.options.map((o) => optionName(catalog, card, r.pick?.choice ?? '', o)).join(' or '), choiceName(r.pick.choice))}.`);
     }
     if (r.activation !== null)
         conditions.push('Needs its bonus activated with the issuer (free).');
@@ -169,6 +174,7 @@ export function exploreCards(catalog, query, options, resolved) {
     };
     const ranked = [];
     const ifPaid = new Map();
+    const ifLarger = new Map();
     const excluded = [];
     // A Costco purchase means a Costco member: no membership to point out.
     const members = paidMemberships(catalog, {
@@ -192,6 +198,14 @@ 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);
+        const larger = amountUpgrade(card, held, purchaseContext(catalog, wallet, merchant, merchant.category, purchase), top.rate);
+        if (larger)
+            ifLarger.set(card.id, {
+                amount: larger.amount,
+                earn: earnText(catalog, larger.nominalRate, top.currency),
+                standard: earnText(catalog, top.rate, top.currency),
+                returnPct: larger.rate * top.centsPerUnit - (top.foreignFee ?? 0),
+            });
         if (paid)
             ifPaid.set(card.id, {
                 payment: paid.payment,
@@ -233,17 +247,36 @@ export function exploreCards(catalog, query, options, resolved) {
     ranked.sort(compareExplored);
     return {
         merchant,
-        credits: creditPicks(catalog, merchant, ranked),
+        credits: creditPicks(catalog, merchant, ranked, query.date),
         ranked,
         excluded,
-        assumptions: exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid),
+        assumptions: exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid, ifLarger),
         warnings: exploreWarnings(catalog, merchant),
+        ifPaying: paidAtTop(ranked, ifPaid).map(({ entry, paid }) => ({
+            cardId: entry.cardId,
+            cardName: entry.cardName,
+            payment: paid.payment,
+            earn: paid.earn,
+        })),
     };
 }
-function creditPicks(catalog, merchant, ranked) {
+// Cards a way of paying would lift to the top (or that are already there).
+function paidAtTop(ranked, ifPaid) {
+    const top = ranked[0];
+    if (!top)
+        return [];
+    return ranked.flatMap((entry) => {
+        const paid = ifPaid.get(entry.cardId);
+        return paid &&
+            (entry === top || paid.returnPct > top.effectiveReturnPct + EPSILON)
+            ? [{ entry, paid }]
+            : [];
+    });
+}
+function creditPicks(catalog, merchant, ranked, date) {
     const picks = ranked.flatMap((entry) => {
         const card = catalog.cards.find((c) => c.id === entry.cardId);
-        return ((card?.credits ?? [])
+        return ((card ? liveCredits(card, date) : [])
             // A credit for a whole category (every restaurant) isn't a store's.
             .filter((c) => c.match.merchants !== undefined &&
             creditCovers(catalog, c, merchant))
@@ -263,7 +296,8 @@ function creditPicks(catalog, merchant, ranked) {
                 period: credit.period,
                 enroll: credit.enroll === true,
                 note: credit.note ?? null,
-                back: creditBack(credit),
+                back: `${creditBack(credit)}${creditTerms(credit)}`,
+                terms: creditTerms(credit),
                 earn,
                 text: creditThen(credit, earn),
                 evidence: evidence
@@ -274,7 +308,7 @@ function creditPicks(catalog, merchant, ranked) {
     });
     return picks.sort((a, b) => creditPerYear(b) - creditPerYear(a) || a.cardId.localeCompare(b.cardId));
 }
-function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid) {
+function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid, ifLarger) {
     const assumptions = [];
     if (merchant.source === 'category') {
         assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
@@ -294,13 +328,16 @@ function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid
     if (purchase.payment)
         assumptions.push(paidText(purchase.payment));
     const top = ranked[0];
+    for (const { entry, paid } of paidAtTop(ranked, ifPaid)) {
+        assumptions.push(paymentUnknownText(entry.cardName, paid.payment, paid.earn, paid.standard));
+    }
     for (const entry of ranked) {
-        const paid = ifPaid.get(entry.cardId);
-        if (!paid || !top)
+        const larger = ifLarger.get(entry.cardId);
+        if (!larger || !top)
             continue;
-        if (entry !== top && paid.returnPct <= top.effectiveReturnPct + EPSILON)
+        if (entry !== top && larger.returnPct <= top.effectiveReturnPct + EPSILON)
             continue;
-        assumptions.push(paymentUnknownText(entry.cardName, paid.payment, paid.earn, paid.standard));
+        assumptions.push(amountUnknownText(entry.cardName, larger.amount, larger.earn, larger.standard));
     }
     return assumptions;
 }

package/dist/engine/memberships.js

@@ -1,4 +1,4 @@
-import { listed, money, withArticle, words } from "./text.js";
+import { listed, money, shortCardName, withArticle, words } from "./text.js";
 export function membership(catalog, id) {
     return catalog.memberships.find((m) => m.id === id);
 }
@@ -11,16 +11,24 @@ export function sameGroup(catalog, a, b) {
     const group = membership(catalog, a)?.group;
     return group !== undefined && group === membership(catalog, b)?.group;
 }
+// The memberships a person has: the ones they've said, plus the one each of
+// their cards can't be held without (a Costco membership for Costco
+// Anywhere). Gates a rule's `requires.membership` as well as fees. Only the
+// person's own cards (or those named for an answer) belong in `cardIds`.
+export function effectiveMemberships(catalog, memberships, cardIds) {
+    const out = new Set(memberships);
+    for (const card of catalog.cards) {
+        const id = card.requires_membership;
+        if (id !== undefined && cardIds.includes(card.id))
+            out.add(id);
+    }
+    return [...out];
+}
 // Memberships the person already pays for: the ones they've said, the ones a
 // card they hold needs, and the ones their spending shows (only members shop
 // at Costco).
 export function paidMemberships(catalog, { memberships, heldCards = [], merchantIds = [], }) {
-    const paid = new Set(memberships);
-    for (const card of catalog.cards) {
-        const id = card.requires_membership;
-        if (id !== undefined && heldCards.includes(card.id))
-            paid.add(id);
-    }
+    const paid = new Set(effectiveMemberships(catalog, memberships, heldCards));
     for (const m of catalog.memberships)
         if (m.members_shop_at.some((id) => merchantIds.includes(id)))
             paid.add(m.id);
@@ -62,6 +70,10 @@ export function membershipNeeded(catalog, card, paid) {
         : [];
 }
 export function membershipNote(catalog, m) {
-    const names = m.cardIds.map((id) => catalog.cards.find((c) => c.id === id)?.name ?? id);
-    return `${listed(names)} ${names.length === 1 ? 'needs' : 'need'} ${withArticle(m.name)}, ${money(m.annualFee)} a year, counted here like an annual fee. If you're already a member, add it to your memberships.`;
+    const names = m.cardIds.map((id) => shortCardName(catalog.cards.find((c) => c.id === id)?.name ?? id));
+    const needs = `${listed(names)} ${names.length === 1 ? 'needs' : 'need'} ${withArticle(m.name)}`;
+    const cost = m.annualFee === 0
+        ? ''
+        : `, ${money(m.annualFee)} a year, counted here like an annual fee`;
+    return `${needs}${cost}. If you have one, add it to your memberships.`;
 }

package/dist/engine/milestones.js

@@ -1,7 +1,11 @@
-import { periodEnd, periodKey } from "./periods.js";
-import { listed, MILESTONE_PERIODS, money, roundCents, wholeDollars, } from "./text.js";
+import { inEffect, periodEnd, periodKey } from "./periods.js";
+import { listed, MILESTONE_PERIODS, shortDate, money, roundCents, wholeDollars, } from "./text.js";
+// Spend milestones: a bonus paid once a period after a spending total. Only
+// spending the wallet tracks counts; earnrate never assumes the rest.
+// The card's milestones the issuer runs on `date`.
+export const liveMilestones = (card, date) => card.milestones.filter((m) => inEffect(m, date));
 export function milestoneProgress(card, held, date) {
-    return card.milestones.map((milestone) => {
+    return liveMilestones(card, date).map((milestone) => {
         const period = periodKey(milestone.period, date, held.anniversary ?? null);
         const usage = held.milestone_usage?.[milestone.id];
         return {
@@ -45,6 +49,10 @@ export function milestonePays(m) {
 }
 // "the $15,000 calendar-year spend for 10,000 bonus points"
 export const milestoneWhat = (m) => `the ${wholeDollars(m.spend)} ${MILESTONE_PERIODS[m.period]} spend for ${milestonePays(m)}`;
+// " starting Jan 1, 2027" for a milestone that hasn't started by `today`.
+export const milestoneStarts = (m, today) => m.valid_from === undefined || m.valid_from <= today
+    ? ''
+    : ` starting ${shortDate(m.valid_from)}`;
 export function reachedText(card, hit, centsPerPoint) {
     const m = card.milestones.find((x) => x.id === hit.id);
     if (!m)