earnrate 0.2.15 → 0.2.17

package/dist/cli/args.js

@@ -95,6 +95,9 @@ export function parseCliArgs(argv) {
                 llm: { type: 'boolean' },
                 cards: { type: 'string' },
                 member: { type: 'string', multiple: true },
+                enrolled: { type: 'string', multiple: true },
+                'skipped-credits': { type: 'string', multiple: true },
+                opened: { type: 'string', multiple: true },
                 help: { type: 'boolean', short: 'h' },
             },
         });
@@ -129,6 +132,28 @@ export function parseCliArgs(argv) {
     const paying = paymentOf(values.paying);
     if ('problem' in paying)
         return { kind: 'error', message: paying.problem };
+    const cards = cardList(values.cards);
+    const perCard = (flag, example) => {
+        const out = {};
+        for (const pair of values[flag] ?? []) {
+            const [id = '', value = ''] = pair.split('=');
+            if (id.trim() === '' || value.trim() === '')
+                return `--${flag} takes <card>=<${flag === 'opened' ? 'date' : 'credits'}>, like ${example}.`;
+            if (!cards?.includes(id.trim()))
+                return `--${flag} is for a card named with --cards; ${id.trim()} isn't one.`;
+            out[id.trim()] = value.trim();
+        }
+        return out;
+    };
+    const enrolled = perCard('enrolled', 'amex-platinum=lululemon');
+    if (typeof enrolled === 'string')
+        return { kind: 'error', message: enrolled };
+    const skipped = perCard('skipped-credits', 'amex-gold=dunkin');
+    if (typeof skipped === 'string')
+        return { kind: 'error', message: skipped };
+    const opened = perCard('opened', 'discover-it-cash-back=2026-03-04');
+    if (typeof opened === 'string')
+        return { kind: 'error', message: opened };
     return {
         kind: 'run',
         options: {
@@ -143,8 +168,18 @@ export function parseCliArgs(argv) {
             all: values.all ?? false,
             category: values.category ?? null,
             llm: values.llm ?? null,
-            cards: cardList(values.cards),
+            cards,
             members: values.member ?? [],
+            enrolled: creditLists(enrolled),
+            skipped: creditLists(skipped),
+            opened,
         },
     };
 }
+const creditLists = (byCard) => Object.fromEntries(Object.entries(byCard).map(([id, list]) => [
+    id,
+    list
+        .split(',')
+        .map((c) => c.trim())
+        .filter(Boolean),
+]));

package/dist/cli/run.js

@@ -70,6 +70,14 @@ Options:
   ${PAYING_HELP}
   --cards <ids>          Answer for these cards instead of your wallet, comma
                          separated: --cards amex-gold,chase-prime-visa.
+  --enrolled <card>=<credits>
+                         For a named card, statement credits you've enrolled
+                         in: --enrolled amex-platinum=lululemon. Repeat per card.
+  --skipped-credits <card>=<credits>
+                         For a named card, statement credits you don't use:
+                         --skipped-credits amex-gold=dunkin. Repeat per card.
+  --opened <card>=<date> For a named card, the day it opened (YYYY-MM-DD), for
+                         a first-year rate. Repeat per card.
   --member <name>        A membership you have, in place of the saved ones.
   --category <id>        For a merchant earnrate doesn't know: its category,
                          e.g. grocery.supermarket. Ignored for known merchants.
@@ -106,7 +114,12 @@ export async function cardsToUse(catalog, file, io, named) {
     if (named.cards !== null) {
         const saved = await savedSettings(io);
         const wallet = walletFromCards(catalog, {
-            cards: named.cards.map((id) => ({ id })),
+            cards: named.cards.map((id) => ({
+                id,
+                ...(named.enrolled?.[id] ? { enrolled: named.enrolled[id] } : {}),
+                ...(named.skipped?.[id] ? { skippedCredits: named.skipped[id] } : {}),
+                ...(named.opened?.[id] ? { opened: named.opened[id] } : {}),
+            })),
             memberships: named.members.length > 0 ? named.members : saved.memberships,
         }, io.today);
         if (typeof wallet === 'string') {

package/dist/cli/wallet.js

@@ -20,11 +20,17 @@ const CARD_OPTIONS = `Options:
   --activated <rules>        Rules you've activated with the issuer, comma
                              separated. Replaces the current list.
   --enrolled <credits>       Statement credits you've enrolled in with the
-                             issuer, comma separated, e.g. --enrolled lululemon.
-                             Replaces the current list.
+                             issuer, or use if they need no enrolling, comma
+                             separated, e.g. --enrolled lululemon. They count
+                             against the annual fee. Replaces the current list.
   --credit-used <credit>=<dollars>
                              How much of a credit you've received this period,
                              e.g. --credit-used lululemon=40. Repeat for each.
+  --skipped-credits <credits>
+                             Statement credits you don't use, comma separated,
+                             e.g. --skipped-credits dunkin. They're left out of
+                             picks, the to-do list and annual-fee math.
+                             Replaces the current list.
   --cap-spent <cap>=<dollars>
                              Spending toward a cap so far this period, e.g.
                              --cap-spent us-supermarkets=1200. Repeat for each.
@@ -150,6 +156,7 @@ export async function runWalletCommand(command, argv, io) {
                 opened: { type: 'string' },
                 activated: { type: 'string' },
                 enrolled: { type: 'string' },
+                'skipped-credits': { type: 'string' },
                 'credit-used': { type: 'string', multiple: true },
                 'cap-spent': { type: 'string', multiple: true },
                 'milestone-spent': { type: 'string', multiple: true },
@@ -183,6 +190,7 @@ export async function runWalletCommand(command, argv, io) {
         values.opened !== undefined ||
         values.activated !== undefined ||
         values.enrolled !== undefined ||
+        values['skipped-credits'] !== undefined ||
         values['credit-used'] !== undefined ||
         values['cap-spent'] !== undefined ||
         values['milestone-spent'] !== undefined ||
@@ -288,12 +296,14 @@ export async function runWalletCommand(command, argv, io) {
         const n = Number(text.replace(/[$,]/g, ''));
         return Number.isFinite(n) ? n : `--${flag} takes dollars, like 1200.`;
     };
-    if (values.enrolled !== undefined) {
-        input.enrolled = values.enrolled
-            .split(',')
-            .map((r) => r.trim())
-            .filter((r) => r !== '');
-    }
+    const idList = (text) => text
+        .split(',')
+        .map((r) => r.trim())
+        .filter((r) => r !== '');
+    if (values.enrolled !== undefined)
+        input.enrolled = idList(values.enrolled);
+    if (values['skipped-credits'] !== undefined)
+        input.skippedCredits = idList(values['skipped-credits']);
     // --credit-used, --cap-spent and --milestone-spent: <id>=<dollars>, repeated.
     const dollarPairs = (flag, example) => {
         const pairs = values[flag];

package/dist/data/integrity.js

@@ -160,6 +160,19 @@ function cardProblems(card, catalog, merchantIds) {
         ...card.intro_rates.map((i) => i.id),
         ...card.credits.map((c) => c.id),
     ]);
+    // An end or start date has to come from the issuer, so a quote names its
+    // year ("through 12/31/2027", "Starting in 2027").
+    for (const [id, date] of [
+        ...card.credits.map((c) => [c.id, c.valid_to]),
+        ...card.milestones.map((m) => [m.id, m.valid_from]),
+    ]) {
+        if (date === undefined)
+            continue;
+        const year = date.slice(0, 4);
+        const named = new RegExp(`(^|\\D)(${year}|\\d{1,2}/\\d{1,2}/${year.slice(2)})(\\D|$)`);
+        if (!card.evidence.some((e) => e.rule === id && named.test(e.quote)))
+            problems.push(`${where} ${id}: no evidence quote names its date's year`);
+    }
     const sourcePages = new Set(card.source_urls.map((u) => u.split('#')[0]));
     const backed = new Set(card.evidence.map((e) => e.rule));
     for (const e of card.evidence) {

package/dist/data/wallet-edit.js

@@ -44,6 +44,10 @@ function fieldLines(field, f, indent) {
             return f.enrolled === undefined
                 ? ''
                 : `${indent}enrolled: ${flowList(f.enrolled)}\n`;
+        case 'skipped_credits':
+            return f.skipped_credits === undefined
+                ? ''
+                : `${indent}skipped_credits: ${flowList(f.skipped_credits)}\n`;
         case 'credit_usage': {
             if (f.credit_usage === undefined)
                 return '';
@@ -106,6 +110,7 @@ const FIELDS = [
     'milestone_usage',
     'enrolled',
     'credit_usage',
+    'skipped_credits',
     'bonus',
 ];
 function cardsSeq(text) {

package/dist/engine/cheat-sheet.js

@@ -86,7 +86,7 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
         ];
         return [
             `Working on ${possessive(name)} welcome bonus: ${money(status.remaining ?? 0)} more by ${shortDate(status.deadline ?? date)}. ${where.length > 0
-                ? `It ${where.join(' and ')}, so those are the places to use it.`
+                ? `It ${where.join(' and ')}, so ${matches.length + near.length === 1 ? "that's the place" : 'those are the places'} to use it.`
                 : 'It trails the listed cards everywhere, so use it on everyday spending only as needed to reach the bonus.'}`,
         ];
     });

package/dist/engine/checklist.js

@@ -1,8 +1,16 @@
 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, useCreditText, wholeDollars, possessive, } from "./text.js";
 import { milestonePays } from "./milestones.js";
-import { optionName } from "./rule-text.js";
+import { creditLabel, optionName } from "./rule-text.js";
 import { activationsDue, walletSummary, } from "./wallet-summary.js";
+// "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
@@ -24,7 +32,7 @@ shortName) {
             items.push({
                 kind: 'activate',
                 cardId: card.id,
-                text: `Activate ${possessive(name)} bonus ${a.preposition} ${a.what}${a.activateBy === null ? '' : ` by ${shortDate(a.activateBy)}`}${starts}.`,
+                text: `Activate ${possessive(name)} bonus ${a.where}${a.activateBy === null ? '' : ` by ${shortDate(a.activateBy)}`}${starts}.`,
                 due: a.activateBy ?? (a.from !== null && a.from > today ? a.from : a.to),
             });
         }
@@ -41,7 +49,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,
             });
         }
@@ -94,7 +102,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 +124,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.

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, PICK_PERIODS, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
@@ -169,6 +169,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 +193,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,
@@ -223,23 +232,27 @@ export function exploreCards(catalog, query, options, resolved) {
                 ...membershipNeeded(catalog, card, members),
             ],
             evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
+            needsMembership: card.requires_membership !== undefined &&
+                !members.has(card.requires_membership)
+                ? card.requires_membership
+                : null,
             withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
         });
     }
     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),
     };
 }
-function creditPicks(catalog, merchant, ranked) {
+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))
@@ -259,7 +272,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
@@ -270,7 +284,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)}.`);
@@ -298,12 +312,20 @@ function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid
             continue;
         assumptions.push(paymentUnknownText(entry.cardName, paid.payment, paid.earn, paid.standard));
     }
+    for (const entry of ranked) {
+        const larger = ifLarger.get(entry.cardId);
+        if (!larger || !top)
+            continue;
+        if (entry !== top && larger.returnPct <= top.effectiveReturnPct + EPSILON)
+            continue;
+        assumptions.push(amountUnknownText(entry.cardName, larger.amount, larger.earn, larger.standard));
+    }
     return assumptions;
 }
 function exploreWarnings(catalog, merchant) {
     const warnings = [];
     if (merchant.source === 'none') {
-        warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. Try a category instead.`);
+        warnings.push(`earnrate doesn't know "${merchant.input}" yet, so only base rates apply. Try a category, or the name of a larger chain.`);
     }
     if (merchant.ambiguity) {
         const alternatives = merchant.ambiguity.mayCodeAs.map((c) => categoryPhrase(catalog, c));

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);
@@ -50,7 +58,7 @@ export function membershipCosts(catalog, cards, paid) {
 export function membershipText(catalog, id) {
     const m = membership(catalog, id);
     const name = withArticle(m?.name ?? words(id));
-    return m?.annual_fee === undefined
+    return m?.annual_fee === undefined || m.annual_fee === 0
         ? name
         : `${name} (${money(m.annual_fee)} a year)`;
 }
@@ -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)

package/dist/engine/offers.js

@@ -1,8 +1,9 @@
 import { bonusDollars } from "./bonus.js";
+import { allCreditsYear } from "./credits.js";
 import { matchesFilters } from "./explore.js";
 import { membershipCosts, paidMemberships } from "./memberships.js";
 import { inEffect } from "./periods.js";
-import { CREDITS_LEFT_OUT, heldName, listed, money, roundCents, } from "./text.js";
+import { CREDITS_APART, heldName, listed, money, roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
 function ineligibleText(catalog, wallet, notWith) {
     const held = wallet.cards
@@ -49,6 +50,8 @@ export function compareOffers(catalog, wallet, filters, today) {
             0;
         const firstYearFee = card.first_year_fee ?? card.annual_fee ?? null;
         const membershipFee = membershipCosts(catalog, [card], paid)[0]?.annualFee ?? 0;
+        const firstYearValue = roundCents(value - (firstYearFee ?? 0) - membershipFee);
+        const credits = allCreditsYear(catalog, card, today).yearly;
         offers.push({
             cardId: card.id,
             cardName: card.name,
@@ -68,7 +71,9 @@ export function compareOffers(catalog, wallet, filters, today) {
             bonusValue: roundCents(value),
             membershipFee,
             ineligible: ineligibleText(catalog, wallet, offer.not_with ?? []),
-            firstYearValue: roundCents(value - (firstYearFee ?? 0) - membershipFee),
+            firstYearValue,
+            credits,
+            firstYearValueIfCreditsUsed: roundCents(firstYearValue + credits),
             held: held.has(card.id),
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,
@@ -80,8 +85,8 @@ export function compareOffers(catalog, wallet, filters, today) {
     const notes = [
         `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,
+        "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 its perks.",
+        CREDITS_APART,
     ];
     return { offers, withoutOffer, notes };
 }