earnrate 0.2.3 → 0.2.4

package/dist/engine/wallet-summary.js

@@ -4,49 +4,40 @@ import { daysBetween } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { activationRules } from "./setup.js";
-import { categoryPhrase, earnText } from "./text.js";
+import { categoryPhrase, choiceName, currencyLabel, earnText, listed, words, } from "./text.js";
 import { cardValuation } from "./valuation.js";
-const NUMBERS = {
-    one: '1',
-    two: '2',
-    three: '3',
-    four: '4',
-    five: '5',
-    six: '6',
-};
-// "five-percent" reads "5%"; other ids read as words.
-export function choiceName(id) {
-    return id
-        .replace(/\b(one|two|three|four|five|six)-percent\b/g, (_, n) => `${NUMBERS[n] ?? n}%`)
-        .replace(/[-_.]/g, ' ');
-}
-const listed = (parts) => parts.length <= 2
-    ? parts.join(' and ')
-    : `${parts.slice(0, -1).join(', ')} and ${parts.at(-1) ?? ''}`;
+// Travel-site bookings ("Flight through Amex Travel") read mid-sentence in
+// lower case and plural; brand names keep theirs.
+const BOOKING = /^(Attraction|Car rental|Cruise|Flight|Hotel|Vacation rental)\b/;
 function merchantName(catalog, id) {
     const all = [...catalog.merchants.overrides, ...catalog.merchants.seed];
-    return all.find((m) => m.id === id)?.name ?? id.replace(/[-_.]/g, ' ');
+    const name = all.find((m) => m.id === id)?.name ?? words(id);
+    return name.replace(BOOKING, (kind) => `${kind.toLowerCase()}s`);
 }
 function optionName(catalog, card, choiceId, option) {
     const o = card.choices.find((c) => c.id === choiceId)?.options[option];
     if (!o)
-        return option.replace(/[-_.]/g, ' ');
+        return words(option);
     const parts = [
         ...o.categories.map((c) => categoryPhrase(catalog, c)),
         ...o.merchants.map((m) => merchantName(catalog, m)),
     ];
     if (o.online)
         parts.push('online shopping');
-    return parts.length > 0 ? listed(parts) : option.replace(/[-_.]/g, ' ');
+    return parts.length > 0 ? listed(parts) : words(option);
 }
-function ruleWhat(catalog, rule) {
+// What a rule covers, as a list of phrases.
+function ruleParts(catalog, rule) {
     if (rule.match.choice !== undefined)
-        return `your ${choiceName(rule.match.choice)} picks`;
+        return [`your ${choiceName(rule.match.choice)} picks`];
     const parts = [
         ...(rule.match.categories ?? []).map((c) => categoryPhrase(catalog, c)),
         ...(rule.match.merchants ?? []).map((m) => merchantName(catalog, m)),
     ];
-    return parts.length > 0 ? listed(parts) : rule.id.replace(/[-_.]/g, ' ');
+    return parts.length > 0 ? parts : [words(rule.id)];
+}
+function ruleWhat(catalog, rule) {
+    return listed(ruleParts(catalog, rule));
 }
 function periodEnd(period) {
     const quarter = /^(\d{4})-Q([1-4])$/.exec(period);
@@ -63,14 +54,45 @@ function periodEnd(period) {
 }
 const applies = (rule, today) => (rule.valid_from === undefined || rule.valid_from <= today) &&
     (rule.valid_to === undefined || rule.valid_to >= today);
-function headlineRates(catalog, card, currency, today) {
-    const best = card.rules
-        .filter((r) => applies(r, today) && r.rate > card.base_rate)
-        .sort((a, b) => b.rate - a.rate)
-        .slice(0, 4)
-        .map((r) => `${earnText(catalog, r.rate, currency)} on ${ruleWhat(catalog, r)}${r.requires?.activation ? ' (once activated)' : ''}`);
+const matchKeys = (rule) => rule.match.choice !== undefined
+    ? []
+    : [
+        ...(rule.match.categories ?? []).map((c) => `category:${c}`),
+        ...(rule.match.merchants ?? []).map((m) => `merchant:${m}`),
+    ];
+// Every bonus rate the cardholder gets now, best first, so none reads as the
+// base rate. Rates behind a membership the wallet lacks are left out, and so
+// is a lower tier that 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 shown = card.rules
+        .filter((r) => applies(r, today) &&
+        r.rate > card.base_rate &&
+        (r.requires?.membership === undefined ||
+            wallet.memberships.includes(r.requires.membership)))
+        .sort((a, b) => b.rate - a.rate);
+    const lines = new Map();
+    for (const r of shown) {
+        const keys = matchKeys(r);
+        const higher = shown
+            .filter((h) => h.rate > r.rate &&
+            h.cap === undefined &&
+            (!h.requires?.activation || isActivated(card, held, h.id)))
+            .flatMap(matchKeys);
+        if (keys.length > 0 && keys.every((k) => higher.includes(k)))
+            continue;
+        const pending = r.requires?.activation && !isActivated(card, held, r.id);
+        const head = `${earnText(catalog, r.rate, currency)} on`;
+        const key = pending ? `${head}|activate` : head;
+        const whats = lines.get(key) ?? [];
+        for (const part of ruleParts(catalog, r))
+            if (!whats.includes(part))
+                whats.push(part);
+        lines.set(key, whats);
+    }
     return [
-        ...best,
+        ...[...lines].map(([key, whats]) => `${key.replace('|activate', '')} ${listed(whats)}${key.endsWith('|activate') ? ' (once activated)' : ''}`),
         `${earnText(catalog, card.base_rate, currency)} on everything else`,
     ];
 }
@@ -113,7 +135,7 @@ function capSummaries(catalog, card, held, today) {
         const label = shared?.rotating
             ? 'the rotating bonus categories'
             : [...new Set(covered.map((r) => ruleWhat(catalog, r)))].join(', ') ||
-                key.replace(/[-_.]/g, ' ');
+                words(key);
         return {
             key,
             label,
@@ -142,6 +164,9 @@ export function walletSummary(catalog, wallet, today) {
             onlyAt: card.only_at ?? null,
             bonus: bonusStatus(catalog, wallet, held, today),
             currency: valuation.currency,
+            currencyName: valuation.currency === 'cash'
+                ? 'cash back'
+                : currencyLabel(catalog, valuation.currency),
             centsPerUnit: valuation.centsPerUnit,
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,
@@ -152,7 +177,10 @@ export function walletSummary(catalog, wallet, today) {
                 ? {
                     period: held.chosen.period,
                     current: pickedCategories(card, held, today).staleChoice === null,
-                    until: periodEnd(held.chosen.period),
+                    // Picks that carry over have no end date.
+                    until: card.choices.every((c) => c.period === 'until_changed')
+                        ? null
+                        : periodEnd(held.chosen.period),
                     picks: held.chosen.picks,
                     pickNames: Object.fromEntries(Object.entries(held.chosen.picks).map(([choice, options]) => [
                         choiceName(choice),
@@ -160,7 +188,7 @@ export function walletSummary(catalog, wallet, today) {
                     ])),
                 }
                 : null,
-            rates: headlineRates(catalog, card, valuation.currency, today),
+            rates: headlineRates(catalog, wallet, card, held, valuation.currency, today),
             activated: held.activated,
             toActivate: toActivate(catalog, card, held, today),
             anniversary: held.anniversary ?? null,

package/dist/format/card-text.js

@@ -13,14 +13,6 @@ const ISSUERS = {
     usbank: 'U.S. Bank',
     'wells-fargo': 'Wells Fargo',
 };
-export const MEMBERSHIPS = {
-    'amazon-prime': 'Amazon Prime',
-    'bank-of-america-account': 'Bank of America checking or savings',
-    'bofa-rewards-member': 'BofA Rewards Member',
-    'bofa-rewards-preferred-plus': 'BofA Rewards Preferred Plus',
-    'bofa-rewards-preferred-honors': 'BofA Rewards Preferred Honors',
-    'bofa-rewards-premier': 'BofA Rewards Premier',
-};
 export const PICK_PERIODS = {
     month: 'each month',
     quarter: 'each quarter',
@@ -33,11 +25,11 @@ export const CAP_PERIODS = {
     calendar_year: 'a year',
     cardmember_year: 'a card year',
 };
-export const words = (id) => id.replace(/[-_.]/g, ' ');
+export { MEMBERSHIPS, membershipName, words } from "../engine/text.js";
+import { membershipName, words } from "../engine/text.js";
 // Whole dollars, for fees and caps.
 export const usd = (n) => `${n < 0 ? '−' : ''}$${Math.abs(Math.round(n)).toLocaleString('en-US')}`;
 export const issuerName = (id) => ISSUERS[id] ?? id;
-export const membershipName = (id) => MEMBERSHIPS[id] ?? words(id);
 export function cardText(catalog) {
     const cards = new Map(catalog.cards.map((c) => [c.id, c]));
     function shortName(id) {
@@ -50,15 +42,17 @@ export function cardText(catalog) {
     }
     function feeLabel(id) {
         const card = cards.get(id);
+        const m = card?.requires_membership;
+        const needs = m ? `; needs ${m.name} (${usd(m.annual_fee)} a year)` : '';
         const fee = card?.annual_fee;
         if (fee === undefined)
             return 'Annual fee not on file';
         if (fee === 0)
-            return 'No annual fee';
+            return `No annual fee${needs}`;
         const first = card?.first_year_fee;
         if (first !== undefined && first !== fee)
-            return `${usd(fee)} a year (${first === 0 ? 'waived' : usd(first)} the first year)`;
-        return `${usd(fee)} a year`;
+            return `${usd(fee)} a year (${first === 0 ? 'waived' : usd(first)} the first year)${needs}`;
+        return `${usd(fee)} a year${needs}`;
     }
     // `until` is the last day a time-limited rate applies, already formatted.
     function requirementLines(cardId, r, until = null) {

package/dist/format/cards.js

@@ -1,10 +1,4 @@
-const NETWORKS = {
-    visa: 'Visa',
-    mastercard: 'Mastercard',
-    amex: 'Amex',
-    discover: 'Discover',
-    store: 'store card',
-};
+import { NETWORK_NAMES } from "../engine/text.js";
 export function formatCardInfo(card) {
     const fee = card.annualFee === null
         ? ''
@@ -13,6 +7,11 @@ export function formatCardInfo(card) {
             : `, $${String(card.annualFee)} a year`;
     const needs = [
         ...card.choices.map((c) => `${c.id}: pick ${String(c.pick)} of ${c.options.join(', ')}${c.default ? ` (default ${c.default.join(', ')})` : ''}`),
+        ...(card.requiresMembership
+            ? [
+                `needs ${card.requiresMembership.name} ($${String(card.requiresMembership.annualFee)} a year; membership id ${card.requiresMembership.id})`,
+            ]
+            : []),
         ...(card.memberships.length > 0
             ? [`rates that need a membership: ${card.memberships.join(', ')}`]
             : []),
@@ -23,7 +22,7 @@ export function formatCardInfo(card) {
         ...(card.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
     ];
     return [
-        `${card.id}: ${card.name} (${NETWORKS[card.network]}${fee})${card.held ? ' [in wallet]' : ''}`,
+        `${card.id}: ${card.name} (${NETWORK_NAMES[card.network] ?? card.network}${fee})${card.held ? ' [in wallet]' : ''}`,
         ...needs.map((n) => `    ${n}`),
     ].join('\n');
 }

package/dist/format/explore.js

@@ -1,5 +1,9 @@
-import { feeText, money, pct } from "../engine/text.js";
+import { membershipNote } from "../engine/memberships.js";
+import { feeText, membershipName, money, pct } from "../engine/text.js";
 const wholeUsd = (n) => money(Math.round(n));
+const membershipText = (memberships) => memberships
+    .map((m) => ` + ${wholeUsd(m.annualFee)} for ${m.name.replace(/^an? /, '')}`)
+    .join('');
 const TOP_BEST = 10;
 export function formatExploration(r, all) {
     const m = r.merchant;
@@ -20,7 +24,7 @@ export function formatExploration(r, all) {
             lines.push(`    ${c}`);
         const upgrade = e.withMembership[0];
         if (upgrade)
-            lines.push(`    With ${upgrade.membership}: ${pct(upgrade.effectiveReturnPct)}.`);
+            lines.push(`    With ${membershipName(upgrade.membership)}: ${pct(upgrade.effectiveReturnPct)}.`);
         for (const w of e.warnings)
             lines.push(`    ! ${w}`);
     });
@@ -64,7 +68,7 @@ export function formatCatalogSimulation(r, catalog, all) {
         const card = s.cards[0];
         if (!card)
             return;
-        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeUsd(s.net)}  (${wholeUsd(s.rewards)} rewards, ${wholeUsd(s.annualFees)} fee)${picksText(card.picks)}`);
+        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeUsd(s.net)}  (${wholeUsd(s.rewards)} rewards, ${wholeUsd(s.annualFees)} fee${membershipText(s.memberships)})${picksText(card.picks)}`);
     });
     const pairs = r.pairs.slice(0, top);
     if (pairs.length > 0) {
@@ -92,7 +96,7 @@ export function formatCatalogSimulation(r, catalog, all) {
 export function formatAdditions(r, catalog, all) {
     const name = cardNamer(catalog);
     const lines = [
-        `Your wallet earns about ${wholeUsd(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeUsd(r.current.annualFees)} in annual fees` : ''}.`,
+        `Your wallet earns about ${wholeUsd(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeUsd(r.current.annualFees)} in annual fees: ${wholeUsd(r.current.net)} after fees` : ''}.`,
     ];
     for (const split of splitText(r.current, name))
         lines.push(`  ${split}`);
@@ -101,14 +105,19 @@ export function formatAdditions(r, catalog, all) {
         lines.push('', 'No card would add more than its annual fee costs.');
     }
     else {
-        lines.push('', 'Cards that would add the most (after their annual fee):');
+        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)}  +${wholeUsd(a.gain)} a year  (+${wholeUsd(a.extraRewards)} rewards, ${wholeUsd(a.annualFee)} fee)${picksText(a.picks)}`);
+            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeUsd(a.gain)} a year  (+${wholeUsd(a.extraRewards)} rewards, ${wholeUsd(a.annualFee)} fee${membershipText(a.simulation.memberships.filter((m) => m.cardIds.includes(a.cardId)))})${picksText(a.picks)}`);
         });
     }
-    const notes = new Set(r.current.notes);
+    const notes = new Set([
+        ...r.current.notes,
+        ...gains
+            .slice(0, all ? 20 : TOP_SIMULATED)
+            .flatMap((a) => a.simulation.memberships.map((m) => membershipNote(catalog, m))),
+    ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh.');
+    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh. 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,4 +1,4 @@
-import { feeText, money } from "../engine/text.js";
+import { feeText, money, shortDate } from "../engine/text.js";
 const TOP = 10;
 function reward(o, currencyName) {
     const amount = o.dollars !== null
@@ -6,12 +6,6 @@ function reward(o, currencyName) {
         : `${(o.points ?? 0).toLocaleString('en-US')} ${currencyName}`;
     return o.varies ? `Up to ${amount}` : amount;
 }
-const asOf = (date) => new Date(`${date}T12:00:00Z`).toLocaleDateString('en-US', {
-    month: 'short',
-    day: 'numeric',
-    year: 'numeric',
-    timeZone: 'UTC',
-});
 export function formatOffers(c, currencyName, all) {
     if (c.offers.length === 0) {
         return `No published welcome offers match.${c.withoutOffer.length > 0 ? ` ${String(c.withoutOffer.length)} matching card(s) have none on file.` : ''}\n`;
@@ -25,8 +19,10 @@ export function formatOffers(c, currencyName, all) {
         const spend = o.spend > 0
             ? `after ${money(o.spend)} in ${String(o.months)} month${o.months === 1 ? '' : 's'}${pace}`
             : 'with no spending required';
-        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${money(Math.round(o.firstYearValue))} the first year`, `    ${reward(o, currencyName(o.currency))} ${spend}. ${feeText(o)[0]?.toUpperCase() ?? ''}${feeText(o).slice(1)}.${o.held ? ' In your wallet.' : ''}`);
-        lines.push(`    ${o.validTo ? `Offer ends ${o.validTo}. ` : ''}Public offer as of ${asOf(o.lastVerified)}; yours may differ.`);
+        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${money(Math.round(o.firstYearValue))} the first year`, `    ${reward(o, currencyName(o.currency))} ${spend}. ${feeText(o)[0]?.toUpperCase() ?? ''}${feeText(o).slice(1)}.${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 ${o.validTo}. ` : ''}Public offer as of ${shortDate(o.lastVerified)}; yours may differ.`);
+        if (o.ineligible)
+            lines.push(`    ${o.ineligible}`);
         if (o.note)
             lines.push(`    ${o.note}`);
     });

package/dist/format/recommendation.js

@@ -24,13 +24,15 @@ function header(rec, purchase) {
         parts.push(m.channel === 'online' ? 'online' : 'in-store');
     return parts.join(' · ');
 }
-function cardLines(cards, style) {
+function cardLines(cards, style, bonusPick) {
+    const rankWidth = Math.max(...cards.map((c) => c.rank));
     const nameWidth = Math.max(...cards.map((c) => label(c).length));
     const pctWidth = Math.max(...cards.map((c) => pct(c.effectiveReturnPct).length));
     const lines = [];
-    cards.forEach((c, i) => {
+    cards.forEach((c) => {
         const earned = c.earned === null ? '' : `  ${cents(c.earned)}`;
-        lines.push(`  ${String(i + 1)}. ${label(c).padEnd(nameWidth)}  ${pct(c.effectiveReturnPct).padStart(pctWidth)}${earned}`);
+        const pick = c.cardId === bonusPick ? '  ← the pick, for its welcome bonus' : '';
+        lines.push(`  ${String(c.rank).padStart(String(rankWidth).length)}. ${label(c).padEnd(nameWidth)}  ${pct(c.effectiveReturnPct).padStart(pctWidth)}${earned}${pick}`);
         for (const r of c.reasoning)
             lines.push(style('dim', `     ${r}`));
         for (const w of c.warnings)
@@ -60,9 +62,13 @@ export function formatRecommendation(rec, purchase, { all = false, style = plain
     else {
         lines.push(style('bold', noCard));
     }
-    const shown = all ? rec.ranked : rec.ranked.slice(0, TOP);
+    const bonusPick = rec.bonus?.cardId ?? null;
+    const ranked = rec.ranked.map((c, i) => ({ ...c, rank: i + 1 }));
+    const shown = all
+        ? ranked
+        : ranked.filter((c, i) => i < TOP || c.cardId === bonusPick);
     if (shown.length > 0)
-        lines.push('', ...cardLines(shown, style));
+        lines.push('', ...cardLines(shown, style, bonusPick));
     const hidden = rec.ranked.length - shown.length;
     if (hidden > 0) {
         lines.push(style('dim', `  + ${String(hidden)} more ${hidden === 1 ? 'card' : 'cards'} (--all lists them)`));

package/dist/format/wallet-yaml.js

@@ -1,10 +1,11 @@
-import { parse, stringify } from 'yaml';
+import { Document, parse, visit } from 'yaml';
 import { walletProblems } from "../data/integrity.js";
-import { WalletSchema } from "../schema/wallet.js";
+import { WALLET_VERSION, WalletSchema } from "../schema/wallet.js";
 // A wallet as the YAML file the CLI reads, for moving it between the
 // website, the remote server and the command line. Node-free.
 function compact(wallet) {
     return {
+        version: wallet.version ?? WALLET_VERSION,
         ...(Object.keys(wallet.valuations).length > 0
             ? { valuations: wallet.valuations }
             : {}),
@@ -26,8 +27,22 @@ function compact(wallet) {
         })),
     };
 }
+// Dates, periods and anniversaries are quoted: YAML 1.1 parsers read a bare 2026-10-15 as a
+// date, not a string.
+function quotedYaml(value) {
+    const doc = new Document(value);
+    visit(doc, {
+        Scalar(key, node) {
+            if (key === 'value' &&
+                typeof node.value === 'string' &&
+                /^(\d{4}(-|$)|\d{2}-\d{2}$)/.test(node.value))
+                node.type = 'QUOTE_DOUBLE';
+        },
+    });
+    return doc.toString();
+}
 export function walletYaml(wallet) {
-    return `# Your earnrate wallet: the cards you hold, by id. Never card numbers.\n# For the command line, save it as ~/.earnrate/wallet.yaml\n\n${stringify(compact(wallet))}`;
+    return `# Your earnrate wallet: the cards you hold, by id. Never card numbers.\n# For the command line, save it as ~/.earnrate/wallet.yaml\n\n${quotedYaml(compact(wallet))}`;
 }
 export function parseWalletYaml(text, catalog) {
     let raw;

package/dist/format/wallet.js

@@ -1,24 +1,11 @@
-import { money } from "../engine/text.js";
-const NETWORKS = {
-    visa: 'Visa',
-    mastercard: 'Mastercard',
-    amex: 'American Express',
-    discover: 'Discover',
-    store: 'store card',
-};
-const day = (date) => new Date(`${date}T12:00:00Z`).toLocaleDateString('en-US', {
-    month: 'short',
-    day: 'numeric',
-    year: 'numeric',
-    timeZone: 'UTC',
-});
+import { money, NETWORK_NAMES, shortDate } from "../engine/text.js";
 export function formatWalletSummary(summary) {
     const cards = summary.cards.map((c) => {
         const label = c.checkoutLabel
             ? `, shown at checkout as "${c.checkoutLabel}"`
             : '';
         const lines = [
-            `- ${c.cardName} (${c.cardId})${label}: ${NETWORKS[c.network] ?? c.network}, ${c.currency} at ${String(c.centsPerUnit)}¢. Data checked ${c.lastVerified}${c.dataIsStale ? ' (old; check the issuer)' : ''}.`,
+            `- ${c.cardName} (${c.cardId})${label}: ${NETWORK_NAMES[c.network] ?? c.network}, ${c.currencyName} at ${String(c.centsPerUnit)}¢. Data checked ${c.lastVerified}${c.dataIsStale ? ' (old; check the issuer)' : ''}.`,
             `  Earns: ${c.rates.join('; ')}.`,
         ];
         if (c.onlyAt)
@@ -27,10 +14,14 @@ export function formatWalletSummary(summary) {
             const picks = Object.entries(c.chosen.pickNames)
                 .map(([choice, names]) => `${choice}: ${names.join(', ')}`)
                 .join('; ');
-            const until = c.chosen.until ? `, through ${day(c.chosen.until)}` : '';
-            lines.push(c.chosen.current
-                ? `  Picks for ${c.chosen.period}${until}: ${picks}. Pick again after that.`
-                : `  Picks are for ${c.chosen.period}, which is over: ask for this period's picks.`);
+            const until = c.chosen.until
+                ? `, through ${shortDate(c.chosen.until)}`
+                : '';
+            lines.push(!c.chosen.current
+                ? `  Picks are for ${c.chosen.period}, which is over: ask for this period's picks.`
+                : c.chosen.until === null
+                    ? `  Picks: ${picks}. They stay until the user changes them.`
+                    : `  Picks for ${c.chosen.period}${until}: ${picks}. Pick again after that.`);
         }
         if (c.toActivate.length > 0)
             lines.push(`  Not activated yet: ${c.toActivate.join('; ')}. Activating once with the issuer covers each group.`);
@@ -39,6 +30,8 @@ export function formatWalletSummary(summary) {
         for (const cap of c.caps)
             if (cap.remaining !== null)
                 lines.push(`  Cap on ${cap.label}: ${money(cap.spent)} of ${money(cap.amount)} used for ${cap.currentPeriod ?? ''} (cap key ${cap.key}).`);
+        if (c.anniversary !== null)
+            lines.push(`  Account anniversary: ${c.anniversary}.`);
         const b = c.bonus;
         if (b?.state === 'open' && b.spend !== null)
             lines.push(`  Welcome bonus: ${money(b.spent)} of ${money(b.spend)} spent, due ${b.deadline ?? ''}.`);

package/dist/mcp/inputs.js

@@ -120,11 +120,11 @@ export function makeInputs(catalog) {
         .array(NamedCard)
         .optional()
         .describe("Cards the user named in this conversation, to answer for just those cards without saving anything. Leave out to use the user's saved wallet if they have one; with neither, the answer covers every card earnrate knows.");
-    const NamedMemberships = Memberships.optional().describe("Memberships the user has, such as amazon-prime, when they're named in the conversation rather than saved.");
+    const NamedMemberships = Memberships.optional().describe("Memberships the user has, such as amazon-prime or costco, when they're named in the conversation rather than saved.");
     const CatalogFilters = {
         ...OfferFilters,
         issuer: z.enum(issuers).optional().describe("Only this issuer's cards."),
-        memberships: Memberships.optional().describe("Memberships the user has, such as amazon-prime. Rates that need one they don't have are listed separately."),
+        memberships: Memberships.optional().describe("Memberships the user has, such as amazon-prime or costco. Rates that need one they don't have are listed separately; a card that needs one (Costco Anywhere) says so."),
         valuation: z
             .enum(['flat', 'points-heavy'])
             .optional()

package/dist/mcp/schemas.js

@@ -170,6 +170,8 @@ export const OfferComparisonSchema = z.object({
         note: z.string().nullable(),
         annualFee: z.number().nullable(),
         firstYearFee: z.number().nullable(),
+        membershipFee: z.number(),
+        ineligible: z.string().nullable(),
         bonusValue: z.number(),
         firstYearValue: z.number(),
         held: z.boolean(),
@@ -204,6 +206,9 @@ export const CardSearchSchema = z.object({
             default: z.array(z.string()).nullable(),
         })),
         memberships: z.array(z.string()),
+        requiresMembership: z
+            .object({ id: z.string(), name: z.string(), annualFee: z.number() })
+            .nullable(),
         activation: z.array(z.string()),
         needsAnniversary: z.boolean(),
     })),
@@ -272,6 +277,13 @@ const SimulationSchema = z.object({
     spend: z.number(),
     rewards: z.number(),
     annualFees: z.number(),
+    memberships: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        annualFee: z.number(),
+        cardIds: z.array(z.string()),
+    })),
+    membershipFees: z.number(),
     net: z.number(),
     lines: z.array(z.object({
         label: z.string(),
@@ -292,6 +304,7 @@ export const SpendingSimulationSchema = z.object({
         picks: Picks,
         extraRewards: z.number(),
         annualFee: z.number(),
+        membershipFee: z.number(),
         gain: z.number(),
     })),
 });

package/dist/mcp/tools/account.js

@@ -46,19 +46,35 @@ export function registerAccountTools(server, catalog, store, ctx) {
         const parsed = parseWalletYaml(yaml, catalog);
         if (typeof parsed === 'string')
             return fail(parsed);
-        const current = await store.load().catch(() => null);
+        let current;
+        try {
+            current = await store.load();
+        }
+        catch (e) {
+            if (replace !== true)
+                return fail(`Couldn't read the saved wallet to check what it holds (${e instanceof Error ? e.message : String(e)}). Ask the user, then call again with replace: true to overwrite it.`);
+            current = null;
+        }
         if (current !== null && current.cards.length > 0 && replace !== true)
             return fail(`This would replace the ${String(current.cards.length)} ${current.cards.length === 1 ? 'card' : 'cards'} already saved (${current.cards.map((c) => c.id).join(', ')}). Ask the user, then call again with replace: true.`);
-        const count = parsed.cards.length;
-        return ctx.changed(await store.replace(parsed), `Imported a wallet with ${String(count)} ${count === 1 ? 'card' : 'cards'}.`, { notes: false });
+        const cards = (n) => `${String(n)} ${n === 1 ? 'card' : 'cards'}`;
+        const before = current?.cards.length ?? 0;
+        return ctx.changed(await store.replace(parsed), before > 0
+            ? `Replaced the ${cards(before)} that were saved with the ${cards(parsed.cards.length)} imported.`
+            : `Imported a wallet with ${cards(parsed.cards.length)}.`, { notes: false });
     });
     server.registerTool('delete_wallet', {
         title: 'Delete the wallet',
-        description: "Deletes the saved wallet and its recovery code now and for good, and signs out every Claude app connected to it, this one included. earnrate.dev and the earnrate command line keep their own wallets and aren't affected. Only when the user asks to delete it: offer export_wallet first, and pass confirm only after the user confirms. It refuses when the wallet has no cards, since there's nothing to delete.",
+        description: "Deletes the saved wallet and its recovery code now and for good, and signs out every Claude app connected to it, this one included. earnrate.dev and the earnrate command line keep their own wallets and aren't affected. Only when the user asks to delete it: show it with list_wallet, offer export_wallet, and pass confirm and cards only after the user confirms. It refuses if the wallet no longer holds that many cards, so a retried call can't delete a different wallet.",
         inputSchema: z.object({
             confirm: z
                 .literal(true)
                 .describe('true, only after the user confirms the deletion.'),
+            cards: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe('How many cards the wallet held when the user confirmed, from list_wallet: 0 for an empty wallet.'),
         }),
         outputSchema: z.object({ deleted: z.boolean() }),
         annotations: {
@@ -67,10 +83,12 @@ export function registerAccountTools(server, catalog, store, ctx) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async () => {
-        const current = await store.load().catch(() => null);
-        if (current === null || current.cards.length === 0)
-            return fail("This saved wallet has no cards, so there's nothing to delete. If the user meant a different wallet, it may already be deleted.");
+    }, async ({ cards }) => {
+        // An unreadable wallet can still be deleted: the user confirmed it.
+        const current = await store.load().catch(() => undefined);
+        const held = current === undefined ? cards : (current?.cards.length ?? 0);
+        if (held !== cards)
+            return fail(`This saved wallet holds ${String(held)} ${held === 1 ? 'card' : 'cards'}, not ${String(cards)}, so it isn't the wallet the user confirmed (it may have been deleted and a new one connected). Show it with list_wallet and confirm again.`);
         await store.erase();
         return {
             content: [
@@ -84,7 +102,7 @@ export function registerAccountTools(server, catalog, store, ctx) {
     });
     server.registerTool('switch_wallet', {
         title: 'Switch wallets',
-        description: "Disconnects this app from its saved wallet so the user can connect a different one with its recovery code, or start a new one, on earnrate's page. Nothing is deleted. Use it when the user wants another wallet. Never ask for the recovery code in the conversation.",
+        description: "Disconnects this app from its saved wallet so the user can connect a different one with its recovery code, or start a new one, on earnrate's page. Nothing is deleted. It also signs out anyone else connected to this wallet through the same app (another Claude account the recovery code was shared with): say so before calling it. Use it when the user wants another wallet. Never ask for the recovery code in the conversation.",
         inputSchema: z.object({}),
         outputSchema: z.object({ disconnected: z.boolean() }),
         annotations: {