earnrate 0.2.16 → 0.2.18

package/dist/engine/text.js

@@ -25,6 +25,8 @@ const dateWords = (date, options) => new Date(`${date}T12:00:00Z`).toLocaleDateS
 export const shortDate = (date) => dateWords(date, { month: 'short', day: 'numeric', year: 'numeric' });
 export const longDate = (date) => dateWords(date, { month: 'long', day: 'numeric', year: 'numeric' });
 export const monthYear = (date) => dateWords(date, { month: 'long', year: 'numeric' });
+// "Q4 2026", from an ISO date.
+export const quarterYear = (date) => `Q${String(Math.floor((Number(date.slice(5, 7)) - 1) / 3) + 1)} ${date.slice(0, 4)}`;
 // Always cents ($4.00), for what one purchase earns. A loss reads −$4.00.
 export const dollarsAndCents = (n) => `${n < 0 ? '−' : ''}$${Math.abs(n).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
 // Rounded to whole dollars ($2,800), for fees, caps and yearly totals.
@@ -87,7 +89,7 @@ export function codesAs(catalog, merchant) {
     const code = mcc === null ? '' : ` (MCC ${String(mcc)})`;
     return `Assumes ${merchant.resolvedName} codes as ${categoryPhrase(catalog, merchant.category)}${code}.`;
 }
-// "Values points at: Membership Rewards (MR) at 1¢." for the currencies an
+// "Point values: Membership Rewards (MR) at 1¢." for the currencies an
 // answer ranks, or null when every card shown earns cash.
 export function pointValuesText(catalog, shown) {
     const values = new Map();
@@ -97,7 +99,7 @@ export function pointValuesText(catalog, shown) {
     if (values.size === 0)
         return null;
     const list = [...values].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
-    return `Values points at: ${list.join(', ')}.`;
+    return `Point values: ${listed(list)}.`;
 }
 export const NETWORK_NAMES = {
     visa: 'Visa',
@@ -115,6 +117,7 @@ export const PAYMENT_PHRASES = {
 };
 export const paidText = (payment) => `Counts this as paid ${PAYMENT_PHRASES[payment]}, as you said.`;
 export const paymentUnknownText = (name, payment, earn, standard) => `${capitalize(PAYMENT_PHRASES[payment])}, ${name} would earn ${earn} here, instead of the ${standard} it's ranked at. Say how you're paying to count it.`;
+export const amountUnknownText = (name, amount, earn, standard) => `On a purchase of ${wholeDollars(amount)} or more, ${name} would earn ${earn} here, instead of the ${standard} it's ranked at. Give the amount to count it.`;
 // For answers that never ask how each purchase is paid (cheat sheets and
 // simulations): which cards' rates that need a way of paying are left out.
 export function paymentNote(cards) {
@@ -146,6 +149,14 @@ export function withArticle(name) {
         : /^[aeiou]/i.test(name) && !/^(u[bnst]|u\.s\.|eu|one\b|once\b)/i.test(name);
     return `${an ? 'an' : 'a'} ${name}`;
 }
+// A card's name as people say it: "Amex Blue Cash Preferred", not "American
+// Express Blue Cash Preferred Card".
+export const shortCardName = (name) => name
+    .replace(/^American Express /, 'Amex ')
+    .replace(/^The (.+) Card from American Express$/, 'Amex $1')
+    // "Card" is part of Apple Card's name, not a suffix.
+    .replace(/ (Visa Signature |Visa Infinite )?(Credit )?(?<!^Apple )Card$/, '')
+    .replace(/ Card by /, ' by ');
 // "Amex Platinum's", "Capital One Savor Rewards'".
 export const possessive = (name) => name.endsWith('s') ? `${name}'` : `${name}'s`;
 export const listed = (parts, joiner = 'and') => {
@@ -196,6 +207,36 @@ export const PICK_PERIODS = {
     calendar_year: 'each year',
     until_changed: 'until you change it',
 };
+// "the 2 categories you pick each quarter", or for a card whose issuer
+// applies the bonus itself, "the category you spend the most in each month".
+// `oneOf` reads as one option of several: "one of the 2 categories …".
+export function choicePhrase(c, oneOf = false) {
+    const which = c.pick === 1
+        ? 'the category'
+        : `${oneOf ? 'one of ' : ''}the ${String(c.pick)} categories`;
+    const when = c.period === 'until_changed' ? '' : ` ${PICK_PERIODS[c.period]}`;
+    return c.automatic
+        ? `${which} you spend the most in${when}`
+        : `${which} you pick${when}`;
+}
+// What earning a picked rate takes, for an answer's conditions: "Needs
+// dining as its top-category pick (picked each month)", or for an automatic
+// choice, "Counts when dining is the category you spend the most in that
+// month".
+export function pickCondition(c, options, name) {
+    if (c.automatic) {
+        const period = {
+            month: ' that month',
+            quarter: ' that quarter',
+            calendar_year: ' that year',
+            until_changed: '',
+        }[c.period];
+        return c.pick === 1
+            ? `Counts when ${options} is the category you spend the most in${period}`
+            : `Counts when ${options} is one of the ${String(c.pick)} categories you spend the most in${period}`;
+    }
+    return `Needs ${options} as its ${name} pick (${c.period === 'until_changed' ? '' : 'picked '}${PICK_PERIODS[c.period]})`;
+}
 // Intro rates (a card's first 365 days): "first year", "first 90 days".
 export const introPeriod = (days) => days === 365 ? 'first year' : `first ${String(days)} days`;
 export const introAdjective = (days) => days === 365 ? 'first-year' : `${String(days)}-day`;
@@ -225,14 +266,21 @@ export const CREDIT_THIS_PERIOD = {
 export const ENROLL_FIRST = 'enroll first';
 // The group of cards with a credit at the store, shown before the ranking.
 export const CREDIT_GROUP = 'With a statement credit';
+// A credit the cardholder said they don't use, in list_wallet.
+export const CREDIT_SKIPPED = "marked as one you don't use, so it isn't counted";
 // "$75 back each quarter"
 export const creditBack = (c) => `${money(c.amount)} back ${CREDIT_PERIODS[c.period]}`;
+const minPurchase = (amount) => `a purchase of ${wholeDollars(amount)} or more`;
+// " on a purchase of $500 or more", " through Sep 30, 2027": the limits a
+// credit's issuer sets beyond its amount and period.
+export const creditTerms = (c) => `${c.min_amount === undefined ? '' : ` with ${minPurchase(c.min_amount)}`}${c.valid_to === undefined ? '' : ` through ${shortDate(c.valid_to)}`}`;
 // "$75 back each quarter, then 1x Amex Membership Rewards"
-export const creditThen = (c, earn) => `${creditBack(c)}, then ${earn}`;
+export const creditThen = (c, earn) => `${creditBack(c)}${creditTerms(c)}, then ${earn}`;
 // "$35 left this quarter"
 export const creditLeft = (left, period) => `${money(left)} left ${CREDIT_THIS_PERIOD[period]}`;
 // A line for an answer that uses the card's credit, or says why it doesn't.
 export function creditAnswerText(c, dollars) {
+    const min = c.minAmount ?? null;
     const credit = `${c.name} credit (${creditBack(c)})`;
     if (!c.enrolled)
         return `Has ${withArticle(credit)} here; ${ENROLL_FIRST} with the issuer, then mark it enrolled in your wallet. It isn't counted until then.`;
@@ -241,7 +289,9 @@ export function creditAnswerText(c, dollars) {
     if (c.left <= 0)
         return `Its ${c.name} credit is used up ${CREDIT_THIS_PERIOD[c.period]}${c.until === null ? '' : `; it renews after ${shortDate(c.until)}`}.`;
     if (dollars === null)
-        return `Its ${credit} has ${creditLeft(c.left, c.period)}; give the amount to count it.`;
+        return `Its ${credit} has ${creditLeft(c.left, c.period)}; give the amount to count it${min === null ? '' : ` (it needs ${minPurchase(min)})`}.`;
+    if (dollars <= 0 && min !== null)
+        return `Its ${credit} needs ${minPurchase(min)}, so it doesn't count here.`;
     return dollars < c.left
         ? `${money(dollars)} back from its ${credit}, on top of what it earns; ${creditLeft(roundCents(c.left - dollars), c.period)} after this.`
         : `${money(dollars)} back from its ${credit}: all that's left ${CREDIT_THIS_PERIOD[c.period]}, on top of what it earns.`;
@@ -265,5 +315,60 @@ export const useCreditText = (card, c, left) => `Use your ${money(c.amount)} ${c
 export const enrollCreditText = (card, names) => names.length === 1
     ? `Enroll in ${possessive(card)} ${names[0] ?? ''} credit with the issuer, then mark it enrolled.`
     : `Enroll in ${possessive(card)} ${listed(names)} credits with the issuer, then mark them enrolled.`;
-// Simulations, the cheat sheet and welcome-offer comparisons.
+// Credits that need no enrolling, before the cardholder says whether they
+// use them: they don't offset the annual fee until then.
+export const askCreditText = (card, names) => names.length === 1
+    ? `Do you use ${possessive(card)} ${names[0] ?? ''} credit? Mark it used and it counts against the annual fee.`
+    : `Do you use ${possessive(card)} ${listed(names)} credits? Mark them used and they count against the annual fee.`;
+// The cheat sheet: its picks are by rate alone.
 export const CREDITS_LEFT_OUT = 'Statement credits (dollars back at a named store) are left out.';
+// "$424 a year: Dunkin', Uber, Grubhub and Resy"
+export const creditsYearText = (c) => `${wholeDollars(c.yearly)} a year: ${listed(c.names)}`;
+// A held card's credits the cardholder uses, counted against its fee:
+// "Amex Gold's credits you use (Dunkin' and Uber) count against its fee: $204 a year."
+export const creditsCountedText = (card, fee, c) => fee > 0
+    ? `${possessive(card)} credits you use (${listed(c.names)}) count against its fee: ${wholeDollars(c.yearly)} a year.`
+    : `${possessive(card)} credits you use (${listed(c.names)}) add ${wholeDollars(c.yearly)} a year.`;
+// Rankings of cards the person doesn't hold: the honest figure leaves
+// credits out, and the one with them is shown beside it.
+export const CREDITS_APART = "Statement credits (dollars back at named stores) aren't in the ranking: they're worth it only if you'd spend at those places anyway. Where a card has them, what it nets if you'd use them all is shown apart.";
+export const HELD_CREDITS_COUNTED = "Statement credits on your own cards count against their fees once you've said you use them: marked enrolled, or marked used (or already used) for ones that need no enrolling.";
+export const CREDITS_ONLY_IF = "They're worth that only if you'd spend at those places anyway.";
+// "If you'd use all the statement credits on Amex Gold and Sapphire Reserve
+// ($724 a year), the pair nets $X a year."
+export const pairCreditsUsedText = (cards, yearly, dollars) => `If you'd use all the statement credits on ${listed(cards)} (${wholeDollars(yearly)} a year), the pair nets ${wholeDollars(dollars)} a year.`;
+// "If you'd use all its statement credits ($424 a year: …), it nets $X a
+// year." `adds` for a card beside the ones already held.
+export const ifCreditsUsedText = (c, dollars, verb = 'nets', owner = 'its') => `If you'd use all ${owner} statement credits (${creditsYearText(c)}), it ${verb} ${wholeDollars(dollars)} a year.`;
+// The renewal check on the to-do list. A card well ahead gets one short
+// line; one that's close or behind gets the parts of the math.
+export function renewalText(name, issuer, r) {
+    const fee = r.firstYearFee === null
+        ? `${money(r.fee)} fee`
+        : `${money(r.fee)} fee, up from ${money(r.firstYearFee)} the first year`;
+    const when = `${name} renews around ${shortDate(r.due)} (${fee})`;
+    if (r.net >= r.fee)
+        return `${when}: it's paying for itself, about ${wholeDollars(r.net)} a year ahead after the fee.`;
+    const basis = r.typical ? 'At typical spending' : 'On your spending';
+    const over = r.against === null ? 'your other cards would' : `${r.against} would`;
+    const earns = Math.round(r.rewardsAdded) > 0
+        ? `it earns about ${wholeDollars(r.rewardsAdded)} a year more than ${over}`
+        : Math.round(r.rewardsAdded) < 0
+            ? `it earns about ${wholeDollars(-r.rewardsAdded)} a year less than ${over}`
+            : `it earns about the same as ${over}`;
+    const credits = r.credits > 0 ? `, plus ${wholeDollars(r.credits)} in credits you use` : '';
+    const result = r.net >= 0
+        ? `about ${wholeDollars(r.net)} a year ahead after the fee.`
+        : `about ${wholeDollars(-r.net)} a year short of the fee. Check with ${issuer} before the fee posts.`;
+    return `${when}. ${basis}, ${earns}${credits}: ${result}`;
+}
+// The next-card planner's figures: "about $1,690 over the first two years
+// ($1,290 the first year, then $394 a year)".
+export const twoYearText = (p) => `about ${wholeDollars(p.twoYears)} over the first two years (${wholeDollars(p.yearOne)} the first year, then ${wholeDollars(p.yearTwo)} a year${p.yearTwo < 0 ? ' after its fee' : ''})`;
+// Whether a welcome offer's minimum spend fits, at the person's spending.
+export function minimumSpendText(spend, months, m, typical) {
+    const whose = typical ? 'typical spending' : 'your spending';
+    return m.reachable
+        ? `The ${money(spend)} minimum takes about ${String(m.weeks)} weeks of all ${whose}.`
+        : `The ${money(spend)} minimum in ${String(months)} months is more than ${whose}, so the bonus isn't counted.`;
+}

package/dist/engine/wallet-change.js

@@ -2,7 +2,7 @@ import { CARD_NUMBER_LABEL, labelHasCardNumber } from "../schema/card-number.js"
 import { WALLET_VERSION, } from "../schema/wallet.js";
 import { addMonths } from "./bonus.js";
 import { capByKey } from "./evaluate.js";
-import { choicePeriod, periodKey } from "./periods.js";
+import { choicePeriod, isAnniversary, periodKey } from "./periods.js";
 import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
 import { CREDIT_PERIODS, idList, money } from "./text.js";
 const failed = (error) => ({ ok: false, error });
@@ -15,13 +15,6 @@ function findCatalogCard(catalog, id, today) {
         ? `No card '${id}' in earnrate. Closest: ${idList(near)}.`
         : `No card '${id}' in earnrate. Search the catalog to find its id.`;
 }
-function isAnniversary(text) {
-    const m = /^(\d{2})-(\d{2})$/.exec(text);
-    if (!m)
-        return false;
-    const date = new Date(`2024-${text}T00:00:00Z`); // a leap year allows 02-29
-    return (!Number.isNaN(date.getTime()) && date.toISOString().slice(5, 10) === text);
-}
 const isDate = (d) => /^\d{4}-\d{2}-\d{2}$/.test(d) &&
     new Date(`${d}T00:00:00Z`).toISOString().startsWith(d);
 function pickKey(card, today) {
@@ -150,17 +143,25 @@ export function cardFields(card, held, input, today) {
         fields.milestone_usage = usage;
     }
     if (input.enrolled !== undefined) {
-        const needing = card.credits
-            .filter((c) => c.enroll === true)
-            .map((c) => c.id);
+        const ids = card.credits.map((c) => c.id);
         for (const id of input.enrolled) {
-            if (!needing.includes(id))
-                problems.push(needing.length > 0
-                    ? `'${id}' isn't a ${card.id} credit that needs enrolling. Those are: ${idList(needing)}.`
-                    : `${card.id} has no credits that need enrolling.`);
+            if (!ids.includes(id))
+                problems.push(ids.length > 0
+                    ? `${card.id} has no credit '${id}'. Its credits are: ${idList(ids)}.`
+                    : `${card.id} has no statement credits.`);
         }
         fields.enrolled = [...new Set(input.enrolled)];
     }
+    if (input.skippedCredits !== undefined) {
+        const ids = card.credits.map((c) => c.id);
+        for (const id of input.skippedCredits) {
+            if (!ids.includes(id))
+                problems.push(ids.length > 0
+                    ? `${card.id} has no credit '${id}'. Its credits are: ${idList(ids)}.`
+                    : `${card.id} has no statement credits.`);
+        }
+        fields.skipped_credits = [...new Set(input.skippedCredits)];
+    }
     if (input.creditUsed !== undefined) {
         const usage = { ...held?.credit_usage };
         const anniversary = fields.anniversary ?? held?.anniversary ?? null;
@@ -251,6 +252,9 @@ const withFields = ({ bonus, checkout_label, opened, ...held }, f) => ({
         : { milestone_usage: f.milestone_usage }),
     ...(f.enrolled === undefined ? {} : { enrolled: f.enrolled }),
     ...(f.credit_usage === undefined ? {} : { credit_usage: f.credit_usage }),
+    ...(f.skipped_credits === undefined
+        ? {}
+        : { skipped_credits: f.skipped_credits }),
     ...(f.bonus ? { bonus: f.bonus } : {}),
 });
 // `wallet` is null when there isn't one yet; adding a card starts it.
@@ -327,6 +331,21 @@ export function withMemberships(catalog, wallet, memberships) {
         notes: [],
     };
 }
+// Issuers to leave out of next-card answers. [] clears the list.
+export function withSkippedIssuers(catalog, wallet, issuers) {
+    const known = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
+    const unknown = issuers.filter((i) => !known.includes(i));
+    if (unknown.length > 0)
+        return failed(`No card earnrate knows is from ${unknown.map((i) => `'${i}'`).join(', ')}. Issuers: ${idList(known)}.`);
+    const { skipped_issuers: _, ...rest } = wallet;
+    const list = [...new Set(issuers)];
+    return {
+        ok: true,
+        wallet: list.length > 0 ? { ...rest, skipped_issuers: list } : rest,
+        fields: {},
+        notes: [],
+    };
+}
 // Point values in cents per point, by currency id; null goes back to
 // earnrate's default for that currency.
 export function withValuations(catalog, wallet, changes) {

package/dist/engine/wallet-summary.js

@@ -1,15 +1,15 @@
 import { bonusStatus } from "./bonus.js";
 import { activationGroup, capUsed, isActivated, pickedCategories, } from "./evaluate.js";
 import { introUntil, introWindows, openedOn } from "./intro.js";
-import { membershipName } from "./memberships.js";
+import { effectiveMemberships, membershipName } from "./memberships.js";
 import { milestoneSummaries } from "./milestones.js";
-import { creditStates } from "./credits.js";
+import { creditStates, usedCreditsYear } from "./credits.js";
 import { creditWhere, optionName, ruleParts, rulePreposition, } from "./rule-text.js";
 import { choicePeriod, daysBetween, inEffect, periodEnd } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { activationRules } from "./setup.js";
-import { CAP_PERIODS, creditBack, creditLeft, ENROLL_FIRST, choiceName, currencyLabel, earnText, listed, PAYMENT_PHRASES, shortDate, wholeDollars, words, } from "./text.js";
+import { CAP_PERIODS, creditBack, creditTerms, creditsCountedText, creditLeft, ENROLL_FIRST, choiceName, currencyLabel, CREDIT_SKIPPED, earnText, listed, PAYMENT_PHRASES, shortCardName, shortDate, wholeDollars, words, } from "./text.js";
 import { cardValuation, currencyValuation } from "./valuation.js";
 const matchKeys = (rule) => rule.match.choice !== undefined
     ? []
@@ -34,11 +34,12 @@ function capLimit(card, shown, rule) {
 // lower tier an uncapped, always-on higher rate fully covers (Prime Visa's 3%
 // without Prime, once Prime is held). Rules at the same rate share a line.
 function headlineRates(catalog, wallet, card, held, currency, today) {
+    const has = effectiveMemberships(catalog, wallet.memberships, wallet.cards.map((c) => c.id));
     const shown = card.rules
         .filter((r) => inEffect(r, today) &&
         r.rate > card.base_rate &&
         (r.requires?.membership === undefined ||
-            wallet.memberships.includes(r.requires.membership)))
+            has.includes(r.requires.membership)))
         .sort((a, b) => b.rate - a.rate);
     const lines = new Map();
     for (const r of shown) {
@@ -214,6 +215,7 @@ export function walletSummary(catalog, wallet, today) {
             caps: capSummaries(catalog, card, held, today),
             milestones: milestoneSummaries(card, held, today),
             credits: creditSummaries(catalog, card, held, today),
+            ...usedCredits(catalog, card, held, today),
             chosen: held.chosen
                 ? {
                     period: held.chosen.period,
@@ -238,18 +240,33 @@ export function walletSummary(catalog, wallet, today) {
     return {
         memberships: wallet.memberships,
         membershipNames: wallet.memberships.map((m) => membershipName(catalog, m)),
+        skippedIssuers: (wallet.skipped_issuers ?? []).map((id) => ({
+            id,
+            name: catalog.issuers.find((i) => i.id === id)?.name ?? id,
+        })),
         pointValues: pointValues(catalog, wallet),
         started: null,
         cards,
     };
 }
+function usedCredits(catalog, card, held, today) {
+    const used = usedCreditsYear(catalog, card, held, today);
+    return {
+        usedCredits: used.yearly,
+        usedCreditsText: used.creditIds.length === 0
+            ? null
+            : creditsCountedText(shortCardName(card.name), card.annual_fee ?? 0, used),
+    };
+}
 function creditSummaries(catalog, card, held, today) {
     return creditStates(catalog, card, held, today).map((s) => {
-        const status = !s.enrolled
-            ? `${ENROLL_FIRST}, then mark it enrolled`
-            : s.left === null
-                ? "give the card's anniversary to track it"
-                : `${creditLeft(s.left, s.period)}${s.until === null ? '' : `, through ${shortDate(s.until)}`}`;
+        const status = s.skipped
+            ? CREDIT_SKIPPED
+            : !s.enrolled
+                ? `${ENROLL_FIRST}, then mark it enrolled`
+                : s.left === null
+                    ? "give the card's anniversary to track it"
+                    : `${creditLeft(s.left, s.period)}${s.until === null ? '' : `, through ${shortDate(s.until)}`}`;
         return {
             id: s.credit.id,
             name: s.name,
@@ -257,12 +274,14 @@ function creditSummaries(catalog, card, held, today) {
             period: s.period,
             enroll: s.credit.enroll === true,
             enrolled: s.enrolled,
+            skipped: s.skipped,
+            confirmed: s.confirmed,
             currentPeriod: s.key,
             until: s.until,
             used: s.used,
             left: s.left,
             tracked: held.credit_usage?.[s.credit.id] !== undefined,
-            text: `${creditBack(s)} ${creditWhere(catalog, s.credit)}: ${status}.`,
+            text: `${creditBack(s)} ${creditWhere(catalog, s.credit)}${creditTerms(s.credit)}: ${status}.`,
         };
     });
 }

package/dist/format/card-text.js

@@ -1,20 +1,12 @@
 // Card names, fees and requirements as earnrate.dev and its static search
 // pages show them. Node-free: the site bundles it.
 import { membershipName, membershipText } from "../engine/memberships.js";
-import { capSentence, earnText, PICK_PERIODS, wholeDollars, words, } from "../engine/text.js";
+import { capSentence, earnText, PICK_PERIODS, pickCondition, shortCardName, wholeDollars, words, } from "../engine/text.js";
 // An issuer's name as people know it, from data/issuers.yaml.
 export const issuerName = (catalog, id) => catalog.issuers.find((i) => i.id === id)?.name ?? id;
 export function cardText(catalog) {
     const cards = new Map(catalog.cards.map((c) => [c.id, c]));
-    function shortName(id) {
-        const name = cards.get(id)?.name ?? id;
-        return (name
-            .replace(/^American Express /, 'Amex ')
-            .replace(/^The Platinum Card from American Express$/, 'Amex Platinum')
-            // "Card" is part of Apple Card's name, not a suffix.
-            .replace(/ (Visa Signature |Visa Infinite )?(Credit )?(?<!^Apple )Card$/, '')
-            .replace(/ Card by /, ' by '));
-    }
+    const shortName = (id) => shortCardName(cards.get(id)?.name ?? id);
     // `membership: false` leaves out a membership the card needs, for lists
     // whose own conditions say it only when it applies.
     function feeLabel(id, { membership = true } = {}) {
@@ -35,7 +27,14 @@ export function cardText(catalog) {
     function requirementLines(cardId, r, until = null) {
         const lines = [];
         if (r.pick)
-            lines.push(`Pick ${r.pick.options.map(words).join(' or ')} as a bonus category (${PICK_PERIODS[r.pick.period]})`);
+            lines.push(r.pick.automatic
+                ? pickCondition({
+                    pick: cards
+                        .get(cardId)
+                        ?.choices.find((c) => c.id === r.pick?.choice)?.pick ?? 1,
+                    ...r.pick,
+                }, r.pick.options.map(words).join(' or '), '')
+                : `Pick ${r.pick.options.map(words).join(' or ')} as a bonus category (${PICK_PERIODS[r.pick.period]})`);
         if (r.activation !== null)
             lines.push(`Activate the bonus with ${issuerName(catalog, cards.get(cardId)?.issuer ?? '')} (free)`);
         if (r.membership !== null)

package/dist/format/explore.js

@@ -1,9 +1,13 @@
 import { membershipName, membershipNote, } from "../engine/memberships.js";
-import { capitalize, choiceName, CREDIT_GROUP, CREDITS_LEFT_OUT, ENROLL_FIRST, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, listed, } from "../engine/text.js";
+import { capitalize, choiceName, CREDIT_GROUP, CREDITS_APART, ENROLL_FIRST, HELD_CREDITS_COUNTED, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, listed, } from "../engine/text.js";
 const membershipFees = (memberships) => memberships
     .map((m) => ` + ${wholeDollars(m.annualFee)} for ${m.name}`)
     .join('');
 const TOP_BEST = 10;
+// " · $X if you'd use all its credits ($424 a year)"
+const ifCredits = (credits, net, sign = '', its = 'its') => credits > 0
+    ? ` · ${sign}${wholeDollars(net)} if you'd use all ${its} credits (${wholeDollars(credits)} a year)`
+    : '';
 export function formatExploration(r, catalog, all) {
     const m = r.merchant;
     const title = m.source === 'category'
@@ -83,15 +87,15 @@ export function formatCatalogSimulation(r, catalog, all) {
         const card = s.cards[0];
         if (!card)
             return;
-        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeDollars(s.net)}  (${wholeDollars(s.rewards)} rewards, ${wholeDollars(s.annualFees)} fee${membershipFees(s.memberships)})${picksText(card.picks)}`);
+        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeDollars(s.net)}  (${wholeDollars(s.rewards)} rewards, ${wholeDollars(s.annualFees)} fee${membershipFees(s.memberships)})${ifCredits(s.otherCredits, s.netIfCreditsUsed)}${picksText(card.picks)}`);
     });
     const pairs = r.pairs.slice(0, top);
     if (pairs.length > 0) {
         lines.push('', 'Best two-card pairs:');
         pairs.forEach((s, i) => {
-            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeDollars(s.net)}`);
+            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeDollars(s.net)}${ifCredits(s.otherCredits, s.netIfCreditsUsed, '', 'their')}`);
             if (s.alternatives.length > 0)
-                lines.push(`    Same result with ${s.alternatives.map(name).join(' or ')} as the second card.`);
+                lines.push(`    Same result with ${listed(s.alternatives.map(name), 'or')} as the second card.`);
             for (const split of splitText(s, name))
                 lines.push(`    ${split}`);
         });
@@ -105,13 +109,13 @@ export function formatCatalogSimulation(r, catalog, all) {
     ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', `Assumes each card's best picks, activations done each quarter, and no welcome bonuses. ${CREDITS_LEFT_OUT}`);
+    lines.push('', `Assumes each card's best picks, activations done each quarter, and no welcome bonuses. ${CREDITS_APART}`);
     return `${lines.join('\n')}\n`;
 }
 export function formatAdditions(r, catalog, all) {
     const name = cardNamer(catalog);
     const lines = [
-        `Your wallet earns about ${wholeDollars(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeDollars(r.current.annualFees)} in annual fees: ${wholeDollars(r.current.net)} after fees` : ''}.`,
+        `Your wallet earns about ${wholeDollars(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeDollars(r.current.annualFees)} in annual fees${r.current.heldCredits > 0 ? ` and ${wholeDollars(r.current.heldCredits)} of credits you use` : ''}: ${wholeDollars(r.current.net)} after fees` : ''}.`,
     ];
     for (const split of splitText(r.current, name))
         lines.push(`  ${split}`);
@@ -122,7 +126,7 @@ export function formatAdditions(r, catalog, all) {
     else {
         lines.push('', 'Cards that would add the most (after their annual fee and any membership they need):');
         gains.slice(0, all ? 20 : TOP_SIMULATED).forEach((a, i) => {
-            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeDollars(a.gain)} a year  (+${wholeDollars(a.extraRewards)} rewards, ${wholeDollars(a.annualFee)} fee${membershipFees(a.simulation.memberships.filter((m) => m.cardIds.includes(a.cardId)))})${picksText(a.picks)}`);
+            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeDollars(a.gain)} a year  (+${wholeDollars(a.extraRewards)} rewards, ${wholeDollars(a.annualFee)} fee${membershipFees(a.simulation.memberships.filter((m) => m.cardIds.includes(a.cardId)))})${ifCredits(a.credits, a.gainIfCreditsUsed, '+')}${picksText(a.picks)}`);
         });
     }
     const notes = new Set([
@@ -133,6 +137,6 @@ export function formatAdditions(r, catalog, all) {
     ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', `Assumes your picks carry over, rotating categories get activated, and caps start fresh. Annual fees are counted in full: statement credits and perks that offset them are left out. ${CREDITS_LEFT_OUT} Each kind of spending lists the card that earns the most on it over the whole year, so a one-quarter bonus may not show.`);
+    lines.push('', `Assumes your picks carry over, rotating categories get activated, and caps start fresh. ${r.current.heldCredits > 0 ? `${HELD_CREDITS_COUNTED} ` : ''}${CREDITS_APART} Perks like lounge access aren't counted. Each kind of spending lists the card that earns the most on it over the whole year, so a one-quarter bonus may not show.`);
     return `${lines.join('\n')}\n`;
 }

package/dist/format/offers.js

@@ -1,5 +1,5 @@
 import { offerTerms } from "../engine/offers.js";
-import { capitalize, feeText, money, shortDate, wholeDollars, } from "../engine/text.js";
+import { capitalize, feeText, minimumSpendText, money, shortDate, twoYearText, wholeDollars, } from "../engine/text.js";
 const TOP = 10;
 export function formatOffers(c, currencyName, all) {
     if (c.offers.length === 0) {
@@ -11,8 +11,10 @@ export function formatOffers(c, currencyName, all) {
     shown.forEach((o, i) => {
         const weeks = (o.months * 52) / 12;
         const pace = o.spend > 0 ? ` (about ${wholeDollars(o.spend / weeks)} a week)` : '';
-        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${wholeDollars(o.firstYearValue)} the first year`, `    ${offerTerms(o, currencyName(o.currency))}${pace}. ${capitalize(feeText(o))}.${o.membershipFee > 0 ? ` Needs a ${money(o.membershipFee)} membership, counted in the first year.` : ''}${o.held ? ' In your wallet.' : ''}`);
-        lines.push(`    ${o.validTo ? `Offer ends ${shortDate(o.validTo)}. ` : ''}Public offer as of ${shortDate(o.lastVerified)}; yours may differ.`);
+        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  ${o.plan ? twoYearText(o.plan) : `about ${wholeDollars(o.firstYearValue)} the first year`}${o.credits > 0 ? `; its credits are ${wholeDollars(o.credits)} a year more if you'd use them all` : ''}`, `    ${offerTerms(o, currencyName(o.currency))}${pace}. ${capitalize(feeText(o))}.${o.membershipFee > 0 ? ` Needs a ${money(o.membershipFee)} membership, counted in the first year.` : ''}${o.held ? ' In your wallet.' : ''}`);
+        lines.push(`    ${o.validTo ? `Offer ends ${shortDate(o.validTo)}. ` : ''}Public offer as of ${shortDate(o.lastVerified)}; yours may differ. The bonus alone is worth about ${wholeDollars(o.firstYearValue)} after the first year's fee.`);
+        if (o.plan?.minimumSpend)
+            lines.push(`    ${minimumSpendText(o.spend, o.months, o.plan.minimumSpend, c.typical)}`);
         if (o.ineligible)
             lines.push(`    ${o.ineligible}`);
         if (o.note)

package/dist/format/wallet-yaml.js

@@ -22,6 +22,9 @@ function compact(wallet) {
         ...(wallet.memberships.length > 0
             ? { memberships: wallet.memberships }
             : {}),
+        ...(wallet.skipped_issuers && wallet.skipped_issuers.length > 0
+            ? { skipped_issuers: wallet.skipped_issuers }
+            : {}),
         cards: wallet.cards.map((c) => Object.fromEntries(CARD_FIELDS.flatMap((k) => (isEmpty(c[k]) ? [] : [[k, c[k]]])))),
     };
 }

package/dist/format/wallet.js

@@ -41,6 +41,8 @@ export function formatWalletSummary(summary) {
             lines.push(`  Spend bonus (${m.id}): ${m.text}`);
         for (const credit of c.credits)
             lines.push(`  Credit (${credit.id}): ${credit.text}`);
+        if (c.usedCreditsText !== null)
+            lines.push(`  ${c.usedCreditsText}`);
         if (c.anniversary !== null)
             lines.push(`  Account anniversary: ${c.anniversary}.`);
         if (c.intro?.state === 'active' && c.intro.until !== null)
@@ -62,7 +64,12 @@ export function formatWalletSummary(summary) {
     const values = summary.pointValues.length > 0
         ? `Point values in the wallet: ${summary.pointValues.map((v) => `${v.name} at ${String(v.centsPerUnit)}¢${v.redemption === null ? '' : ` (redeemed ${v.redemption})`}`).join(', ')}. Others use earnrate's defaults.`
         : "Point values: earnrate's defaults.";
-    return [...cards, memberships, values].join('\n');
+    const skipped = summary.skippedIssuers.length > 0
+        ? [
+            `Next-card answers leave out: ${summary.skippedIssuers.map((i) => `${i.name} (${i.id})`).join(', ')}.`,
+        ]
+        : [];
+    return [...cards, memberships, ...skipped, values].join('\n');
 }
 export function formatBooking(amount, name, // the card's short name
 cap, bonus, milestones = [], credit = null, capLabel = null) {

package/dist/mcp/context.js

@@ -80,6 +80,9 @@ export function makeContext(deps) {
             return {
                 valuations: wallet?.valuations ?? {},
                 memberships: wallet?.memberships ?? [],
+                ...(wallet?.skipped_issuers
+                    ? { skipped_issuers: wallet.skipped_issuers }
+                    : {}),
             };
         }
         catch {
@@ -95,9 +98,14 @@ export function makeContext(deps) {
                 })),
                 memberships: memberships ?? (await saved()).memberships,
             }, deps.today());
-            return typeof named === 'string'
-                ? named
-                : { ...named, valuations: (await saved()).valuations };
+            if (typeof named === 'string')
+                return named;
+            const { valuations, skipped_issuers } = await saved();
+            return {
+                ...named,
+                valuations,
+                ...(skipped_issuers ? { skipped_issuers } : {}),
+            };
         }
         const read = await readableWallet();
         if (typeof read === 'string')

package/dist/mcp/inputs.js

@@ -53,6 +53,10 @@ const NamedCard = z.object({
         .array(z.string())
         .optional()
         .describe("Statement credits the user has enrolled in with the issuer, as credit ids from search_cards. A credit that needs enrolling counts only when it's here. Ask; never assume."),
+    skippedCredits: z
+        .array(z.string())
+        .optional()
+        .describe("Statement credit ids the user says they don't use. They don't count toward a pick or against the card's annual fee."),
     opened: z
         .string()
         .optional()
@@ -73,7 +77,7 @@ const cardFields = {
         .string()
         .regex(/^\d{2}-\d{2}$/)
         .optional()
-        .describe("The account's anniversary as MM-DD, for cards whose cap resets on it."),
+        .describe("The account's anniversary as MM-DD: for cards whose cap resets on it, and for a fee card's renewal check (whether it still pays for itself before the fee comes due). Optional; the opening date stands in. Ask; don't guess."),
     opened: IsoDate.nullable()
         .optional()
         .describe('Optional: the day the account opened, YYYY-MM-DD. Only for cards with a first-year rate (search_cards lists it), which applies only while a purchase falls in the window; without a date the card is ranked at its standard rates. Ask the user; never guess or assume a card is new. null removes it.'),
@@ -92,11 +96,15 @@ const cardFields = {
     enrolled: z
         .array(z.string())
         .optional()
-        .describe('Statement credit ids the user has enrolled in with the issuer (search_cards and list_wallet list each card\'s credits, e.g. "lululemon" on Amex Platinum). A credit that needs enrolling counts in answers only once it\'s here. Replaces the current list. Ask; never assume.'),
+        .describe("Statement credit ids the user has enrolled in with the issuer, or, for a credit that needs no enrolling, says they use (search_cards and list_wallet list each card's credits, e.g. \"lululemon\" on Amex Platinum). A credit that needs enrolling counts in answers only once it's here, and any credit counts against the annual fee only once it's here (or has been used). Replaces the current list. Ask; never assume."),
     creditUsed: z
         .record(z.string(), z.number().nonnegative())
         .optional()
         .describe('Dollars of a statement credit already received this period: credit id → dollars, e.g. {"lululemon": 40}. Ask; recorded purchases add to it from then on.'),
+    skippedCredits: z
+        .array(z.string())
+        .optional()
+        .describe("Statement credit ids the user doesn't use, e.g. [\"dunkin\"] on Amex Gold. They're left out of picks, the to-do list and the annual-fee math; every other credit on the card counts against its fee once it's in enrolled (or, for one that needs no enrolling, has been used). Replaces the current list; [] counts them all again."),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),
@@ -163,6 +171,7 @@ export function makeInputs(catalog) {
             .optional()
             .describe(`Instead of the user's saved point values (or earnrate's defaults): flat, points at their cash-out value, ${profileText('flat')}; or points-heavy, ${profileText('points-heavy')}, for people who transfer points to airlines and hotels.`),
     };
+    const SkippedIssuers = z.array(z.enum(issuers));
     const AllMemberships = Memberships.describe(`Every membership the user has. Known: ${membershipIds.join(', ')}.`);
     return {
         CategoryInput,
@@ -173,6 +182,7 @@ export function makeInputs(catalog) {
         OfferFilters,
         CatalogFilters,
         AllMemberships,
+        SkippedIssuers,
     };
 }
 // The catalog filters as exploreCards and simulate take them. Memberships or

package/dist/mcp/prompts.js

@@ -74,9 +74,9 @@ export function registerPrompts(server, deps, ctx) {
     ]));
     server.registerPrompt('this-quarter', {
         title: 'What should I do with my cards this quarter?',
-        description: 'Bonuses to activate, categories to pick, caps running low and welcome bonuses to finish, from your saved cards.',
+        description: 'Bonuses to activate, categories to pick, caps running low, welcome bonuses to finish and fee cards coming up for renewal, from your saved cards.',
     }, () => ask('What should I do with my cards this quarter?', [
-        "Call earnrate's list_wallet: it starts with a to-do list. Walk through it, soonest first.",
+        "Call earnrate's list_wallet: it starts with a to-do list. Walk through it, soonest first. A renewal check says whether a fee card still pays for itself; give its math as stated, and don't recommend canceling or downgrading on your own.",
         ctx.walletUse,
         'If no cards are saved, say in a sentence or two what saving them adds (reminders to activate bonuses, pick categories, and watch caps and welcome bonuses), without pressing the user to do it, and offer the cheat sheet from every card instead.',
     ]));
@@ -92,7 +92,7 @@ export function registerPrompts(server, deps, ctx) {
             : []),
         'Find each card with search_cards and check the match with the user, then save it with add_card.',
         ctx.walletUse,
-        'When a card needs category picks, a membership like Amazon Prime, activations or its anniversary, ask rather than guessing, and save the answers with update_card or set_memberships.',
+        "When a card needs category picks, a membership like Amazon Prime, activations or its anniversary, ask rather than guessing, and save the answers with update_card or set_memberships. For a card with an annual fee, offer to save its anniversary (or opening date) so earnrate can check before each renewal whether it still pays for itself; it's optional.",
         'When done, call list_wallet and show its to-do list.',
     ]));
 }