earnrate 0.2.16 → 0.2.17

package/dist/engine/rule-text.js

@@ -1,5 +1,5 @@
 import { findMerchant } from "../merchants/resolve.js";
-import { categoryPhrase, categoryReadsOn, choiceName, earnText, introPeriod, listed, num, PAYMENT_PHRASES, PICK_PERIODS, words, } from "./text.js";
+import { categoryPhrase, categoryReadsOn, choiceName, earnText, introPeriod, listed, num, PAYMENT_PHRASES, PICK_PERIODS, wholeDollars, words, } from "./text.js";
 // What a rule or a pick covers, in words, for answers and wallet lists.
 // Travel-site bookings ("Flight through Amex Travel") read mid-sentence in
 // lower case and plural; brand names ("Airbnb through Amex Travel") keep theirs.
@@ -31,11 +31,13 @@ export function ruleParts(catalog, rule, card, { everyStore = false } = {}) {
         return [
             rule.geography === 'foreign_only'
                 ? 'purchases outside the U.S.'
-                : rule.requires?.payment !== undefined
-                    ? 'purchases'
-                    : card?.rules.every((r) => r.match.any)
-                        ? 'every purchase'
-                        : 'everything else',
+                : rule.min_amount !== undefined
+                    ? `purchases of ${wholeDollars(rule.min_amount)} or more`
+                    : rule.requires?.payment !== undefined
+                        ? 'purchases'
+                        : card?.rules.every((r) => r.match.any)
+                            ? 'every purchase'
+                            : 'everything else',
         ];
     if (m.choice !== undefined) {
         const choice = card?.choices.find((c) => c.id === m.choice);
@@ -85,7 +87,10 @@ export function shortenedMerchants(catalog, merchants) {
 }
 export function ruleWhat(catalog, rule, card, options = {}) {
     const payment = rule.requires?.payment;
-    const what = listed(ruleParts(catalog, rule, card, options));
+    const parts = listed(ruleParts(catalog, rule, card, options));
+    const what = rule.min_amount === undefined || rule.match.any
+        ? parts
+        : `${parts}, on purchases of ${wholeDollars(rule.min_amount)} or more`;
     return payment === undefined ? what : `${what} ${PAYMENT_PHRASES[payment]}`;
 }
 // "on dining", "on your picks", "at Costco", "on Walmart+ membership": a
@@ -141,6 +146,14 @@ export function creditName(catalog, credit) {
         ...(credit.match.categories ?? []).map((c) => categoryPhrase(catalog, c)),
     ]);
 }
+// A short name for a list of credits: the first store a credit names
+// ("Grubhub" for the dining credit at five chains); creditName has them all.
+export function creditLabel(catalog, credit) {
+    const [first, ...more] = credit.match.merchants ?? [];
+    return first === undefined || more.length === 0
+        ? creditName(catalog, credit)
+        : merchantName(catalog, first);
+}
 // "at Lululemon", "at restaurants", "on travel", "on Walmart+ membership":
 // the category's or merchant's own preposition.
 export const creditWhere = (catalog, credit) => `${(credit.match.categories ?? []).some((c) => categoryReadsOn(catalog, c)) ||

package/dist/engine/setup.js

@@ -1,10 +1,10 @@
 import { isActivated, pickedCategories } from "./evaluate.js";
-import { membership, membershipName, sameGroup } from "./memberships.js";
-import { milestoneWhat } from "./milestones.js";
+import { effectiveMemberships, membership, membershipName, sameGroup, } from "./memberships.js";
+import { milestoneStarts, milestoneWhat } from "./milestones.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap, rotationGapText } from "./rotation.js";
 import { creditName, creditWhere, introWhat } from "./rule-text.js";
-import { creditBack, ENROLL_FIRST, idList, listed, possessive } from "./text.js";
+import { creditBack, creditTerms, ENROLL_FIRST, idList, listed, possessive, } from "./text.js";
 // Rules that start within this many days are worth activating now.
 const ACTIVATION_LOOKAHEAD_DAYS = 45;
 const searchWords = (s) => s
@@ -108,7 +108,7 @@ export function cardInfo(catalog, card, wallet, today) {
             period: m.period,
             points: m.points ?? null,
             rewards: m.rewards ?? [],
-            text: milestoneWhat(m).replace(/^the /, ''),
+            text: `${milestoneWhat(m).replace(/^the /, '')}${milestoneStarts(m, today)}`,
         })),
         introRates: card.intro_rates.map((i) => ({
             id: i.id,
@@ -123,7 +123,7 @@ export function cardInfo(catalog, card, wallet, today) {
                 amount: c.amount,
                 period: c.period,
                 enroll: c.enroll === true,
-                text: `${creditBack(c)} ${creditWhere(catalog, c)}${c.enroll ? `, ${ENROLL_FIRST}` : ''}`,
+                text: `${creditBack(c)} ${creditWhere(catalog, c)}${creditTerms(c)}${c.enroll ? `, ${ENROLL_FIRST}` : ''}`,
             };
         }),
     };
@@ -177,7 +177,8 @@ export function setupNotes(catalog, wallet, held, today) {
         });
     }
     // With one tier of a group saved, the others aren't missing.
-    const missing = membershipsUsed(card).filter((m) => !wallet.memberships.some((held) => held === m || sameGroup(catalog, held, m)));
+    const has = effectiveMemberships(catalog, wallet.memberships, wallet.cards.map((c) => c.id));
+    const missing = membershipsUsed(card).filter((m) => !has.some((held) => held === m || sameGroup(catalog, held, m)));
     if (missing.length > 0) {
         notes.push({
             kind: 'membership',

package/dist/engine/simulate.js

@@ -1,12 +1,13 @@
 import { categoryResolution, findCategory, resolvePlace, } from "../merchants/resolve.js";
+import { allCreditsYear, usedCreditsYear } from "./credits.js";
 import { evaluateCard, purchaseContext, usableAt } from "./evaluate.js";
 import { idealHolding, matchesFilters, } from "./explore.js";
 import { membershipCosts, membershipNote, paidMemberships, } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { applyBooking, capBooking } from "./record.js";
-import { milestoneWhat } from "./milestones.js";
+import { liveMilestones, milestoneStarts, milestoneWhat } from "./milestones.js";
 import { rotationGap } from "./rotation.js";
-import { money, paymentNote, roundCents, wholeDollars, possessive, } from "./text.js";
+import { creditsCountedText, money, paymentNote, roundCents, shortCardName, wholeDollars, possessive, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON, HALF_CENT } from "./compare.js";
 const MONTHS = 12;
@@ -127,9 +128,11 @@ held = []) {
     // cardmember-year total is the same twelve months' spending.
     const milestones = [];
     const milestoneNotes = [];
+    const lastMonth = monthDates(start).at(-1) ?? start;
     for (const { card, cents } of cards) {
         const spent = results.reduce((sum, r) => sum + (r.byCard.get(card.id) ?? 0), 0);
-        for (const m of card.milestones) {
+        // One that starts during the year counts, as it will the year after.
+        for (const m of liveMilestones(card, lastMonth)) {
             if (spent + EPSILON < m.spend)
                 continue;
             const value = roundCents(((m.points ?? 0) * cents) / 100);
@@ -139,12 +142,25 @@ held = []) {
                 points: m.points ?? null,
                 value,
             });
-            milestoneNotes.push(`${card.name}: ${wholeDollars(spent)} a year on it reaches ${milestoneWhat(m)}${m.points === undefined ? '' : ` (about ${money(value)}, counted in its rewards)`}, assuming the same spending each year.`);
+            milestoneNotes.push(`${shortCardName(card.name)}: ${wholeDollars(spent)} a year on it reaches ${milestoneWhat(m)}${milestoneStarts(m, start)}${m.points === undefined ? '' : ` (about ${money(value)}, counted in its rewards)`}, assuming the same spending each year.`);
         }
     }
     const rewards = roundCents(lineResults.reduce((sum, l) => sum + l.earned, 0) +
         milestones.reduce((sum, m) => sum + m.value, 0));
     const annualFees = cards.reduce((sum, c) => sum + (c.card.annual_fee ?? 0), 0);
+    const credits = cards.flatMap(({ card }) => {
+        const holding = held.includes(card.id);
+        const raw = wallet.cards.find((h) => h.id === card.id);
+        const year = holding && raw
+            ? usedCreditsYear(catalog, card, raw, start)
+            : allCreditsYear(catalog, card, start);
+        return year.creditIds.length === 0 ? [] : [{ ...year, held: holding }];
+    });
+    const creditSum = (heldOnes) => roundCents(credits
+        .filter((c) => c.held === heldOnes)
+        .reduce((sum, c) => sum + c.yearly, 0));
+    const heldCredits = creditSum(true);
+    const otherCredits = creditSum(false);
     const paid = paidMemberships(catalog, {
         memberships: wallet.memberships,
         heldCards: held,
@@ -155,7 +171,12 @@ held = []) {
     const notes = [...milestoneNotes];
     for (const m of memberships)
         notes.push(membershipNote(catalog, m));
-    const paying = paymentNote(cards.map(({ card }) => ({ name: card.name, card })));
+    for (const c of credits.filter((c) => c.held)) {
+        const card = cards.find((x) => x.card.id === c.cardId)?.card;
+        if (card)
+            notes.push(creditsCountedText(shortCardName(card.name), card.annual_fee ?? 0, c));
+    }
+    const paying = paymentNote(cards.map(({ card }) => ({ name: shortCardName(card.name), card })));
     if (paying !== null)
         notes.push(paying);
     const dates = monthDates(start);
@@ -164,13 +185,13 @@ held = []) {
             ...new Set(dates.map((d) => rotationGap(card, d)).filter((g) => g !== null)),
         ];
         if (gaps.length > 0)
-            notes.push(`${possessive(card.name)} rotating categories for ${gaps.join(', ')} aren't in earnrate's data yet, so those quarters count at its everyday rates.`);
+            notes.push(`${possessive(shortCardName(card.name))} rotating categories for ${gaps.join(', ')} aren't in earnrate's data yet, so those quarters count at its everyday rates.`);
         if (card.annual_fee === undefined)
-            notes.push(`${possessive(card.name)} annual fee isn't on file, so none is subtracted.`);
+            notes.push(`${possessive(shortCardName(card.name))} annual fee isn't on file, so none is subtracted.`);
         else if (!held.includes(card.id) &&
             card.first_year_fee !== undefined &&
             card.first_year_fee !== card.annual_fee)
-            notes.push(`${possessive(card.name)} fee is ${money(card.first_year_fee)} the first year; the yearly figure uses the ${money(card.annual_fee)} that follows.`);
+            notes.push(`${possessive(shortCardName(card.name))} fee is ${money(card.first_year_fee)} the first year; the yearly figure uses the ${money(card.annual_fee)} that follows.`);
     }
     return {
         cards: wallet.cards.map((h) => ({
@@ -182,7 +203,11 @@ held = []) {
         annualFees,
         memberships,
         membershipFees,
-        net: roundCents(rewards - annualFees - membershipFees),
+        heldCredits,
+        net: roundCents(rewards + heldCredits - annualFees - membershipFees),
+        otherCredits,
+        netIfCreditsUsed: roundCents(rewards + heldCredits + otherCredits - annualFees - membershipFees),
+        credits,
         lines: lineResults,
         milestones,
         notes,
@@ -317,6 +342,10 @@ function projectedWallet(wallet, catalog, start) {
                 ...(held.anniversary !== undefined
                     ? { anniversary: held.anniversary }
                     : {}),
+                ...(held.enrolled !== undefined ? { enrolled: held.enrolled } : {}),
+                ...(held.skipped_credits !== undefined
+                    ? { skipped_credits: held.skipped_credits }
+                    : {}),
             };
         }),
     };
@@ -339,13 +368,17 @@ export function simulateAdditions(catalog, wallet, lines, options) {
         const extraRewards = roundCents(simulation.rewards - current.rewards);
         const annualFee = card.annual_fee ?? 0;
         const membershipFee = roundCents(simulation.membershipFees - current.membershipFees);
+        const gain = roundCents(extraRewards - annualFee - membershipFee);
+        const credits = allCreditsYear(catalog, card, options.start).yearly;
         additions.push({
             cardId: card.id,
             picks: simulation.cards.at(-1)?.picks ?? {},
             extraRewards,
             annualFee,
             membershipFee,
-            gain: roundCents(extraRewards - annualFee - membershipFee),
+            gain,
+            credits,
+            gainIfCreditsUsed: roundCents(gain + credits),
             simulation,
         });
     }

package/dist/engine/text.js

@@ -87,7 +87,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 +97,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 +115,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 +147,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') => {
@@ -225,14 +234,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 +257,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 +283,28 @@ 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.`;

package/dist/engine/wallet-change.js

@@ -150,17 +150,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 +259,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.

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,
@@ -243,13 +245,24 @@ export function walletSummary(catalog, wallet, today) {
         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 +270,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, 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 } = {}) {

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

@@ -11,7 +11,7 @@ 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(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${wholeDollars(o.firstYearValue)} the first year${o.credits > 0 ? `, ${wholeDollars(o.firstYearValueIfCreditsUsed)} if you'd use all its credits (${wholeDollars(o.credits)} a 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.`);
         if (o.ineligible)
             lines.push(`    ${o.ineligible}`);

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)

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()
@@ -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.'),