earnrate 0.2.2 → 0.2.4

package/dist/engine/text.js

@@ -2,6 +2,15 @@ import { singleMcc } from "./evaluate.js";
 export const num = (n) => String(Number(n.toFixed(2)));
 export const pct = (n) => `${num(n)}%`;
 export const roundCents = (n) => Math.round(n * 100) / 100;
+// An id in words: "gas-ev-charging" reads "gas ev charging".
+export const words = (id) => id.replace(/[-_.]/g, ' ');
+// "Dec 31, 2026" from YYYY-MM-DD, the same in every time zone.
+export const shortDate = (date) => new Date(`${date}T12:00:00Z`).toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    timeZone: 'UTC',
+});
 // Whole dollars stay whole ($2,800); anything else shows cents ($0.40).
 export const money = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
 export function feeText(fees) {
@@ -51,3 +60,45 @@ export function pointValuesText(catalog, shown) {
     const list = [...values].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
     return `Values points at: ${list.join(', ')}.`;
 }
+export const NETWORK_NAMES = {
+    visa: 'Visa',
+    mastercard: 'Mastercard',
+    amex: 'American Express',
+    discover: 'Discover',
+    store: 'store card',
+};
+// A name with its own "and" ("drugstores and pharmacies") would run into the
+// list's: those lists use commas only, with those names last.
+export const listed = (parts) => {
+    const anded = parts.filter((p) => p.includes(' and '));
+    if (anded.length > 0)
+        return [...parts.filter((p) => !p.includes(' and ')), ...anded].join(', ');
+    return parts.length <= 2
+        ? parts.join(' and ')
+        : `${parts.slice(0, -1).join(', ')} and ${parts.at(-1) ?? ''}`;
+};
+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 words(id.replace(/\b(one|two|three|four|five|six)-percent\b/g, (_, n) => `${NUMBERS[n] ?? n}%`));
+}
+// Display names for membership ids in the card data.
+export const MEMBERSHIPS = {
+    'amazon-prime': 'Amazon Prime',
+    'bank-of-america-account': 'Bank of America checking or savings',
+    'bank-of-america-small-business-account': 'Bank of America small business 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',
+    costco: 'Costco membership',
+    'nordy-club-ambassador': 'Nordy Club Ambassador',
+};
+export const membershipName = (id) => MEMBERSHIPS[id] ?? words(id);

package/dist/engine/wallet-change.js

@@ -1,3 +1,5 @@
+import { WALLET_VERSION, } from "../schema/wallet.js";
+import { addMonths } from "./bonus.js";
 import { capByKey } from "./evaluate.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
@@ -132,11 +134,25 @@ export function cardFields(card, held, input, today) {
             problems.push(`"${b.by}" isn't a deadline after the opening date.`);
         if (!card.welcome_offer && (b.spend === undefined || b.by === undefined))
             problems.push(`earnrate has no published welcome offer for ${card.id}, so give the spending needed and the deadline.`);
+        // The terms are saved with the bonus, so a later change to the published
+        // offer, or a wallet exported and imported again, keeps the user's own.
+        const offer = card.welcome_offer;
+        const before = held?.bonus?.opened === b.opened ? held.bonus : undefined;
+        const spend = b.spend ?? before?.spend ?? offer?.spend;
+        const by = b.by ??
+            before?.by ??
+            (offer && isDate(b.opened)
+                ? addMonths(b.opened, offer.months)
+                : undefined);
+        const points = before?.points ?? (before?.dollars ? undefined : offer?.points);
+        const dollars = before?.dollars ?? (points !== undefined ? undefined : offer?.dollars);
         fields.bonus = {
             opened: b.opened,
             spent: b.spent ?? held?.bonus?.spent ?? 0,
-            ...(b.spend === undefined ? {} : { spend: b.spend }),
-            ...(b.by === undefined ? {} : { by: b.by }),
+            ...(spend === undefined ? {} : { spend }),
+            ...(by === undefined ? {} : { by }),
+            ...(points === undefined ? {} : { points }),
+            ...(dollars === undefined ? {} : { dollars }),
         };
     }
     return problems.length > 0 ? problems.join('\n') : fields;
@@ -173,7 +189,12 @@ export function addToWallet(catalog, wallet, input, today) {
     const held = withFields(newHolding(card.id), fields);
     const next = wallet
         ? { ...wallet, cards: [...wallet.cards, held] }
-        : { valuations: {}, memberships: [], cards: [held] };
+        : {
+            version: WALLET_VERSION,
+            valuations: {},
+            memberships: [],
+            cards: [held],
+        };
     return {
         ok: true,
         wallet: next,
@@ -208,9 +229,8 @@ export function removeFromWallet(wallet, id) {
     if (!wallet.cards.some((c) => c.id === id)) {
         return failed(`${id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
     }
-    if (wallet.cards.length === 1) {
-        return failed(`${id} is the last card in the wallet, and a wallet needs one. Add the new card first, then remove this one.`);
-    }
+    // Removing the last card leaves an empty wallet, which each store keeps
+    // in its own way (or refuses, for a wallet file).
     return {
         ok: true,
         wallet: { ...wallet, cards: wallet.cards.filter((c) => c.id !== id) },
@@ -222,7 +242,7 @@ export function withMemberships(catalog, wallet, memberships) {
     const known = knownMemberships(catalog);
     const unknown = memberships.filter((m) => !known.includes(m));
     if (unknown.length > 0) {
-        return failed(`No card rule uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
+        return failed(`No card uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
     }
     return {
         ok: true,

package/dist/engine/wallet-summary.js

@@ -1,10 +1,120 @@
 import { bonusStatus } from "./bonus.js";
-import { capUsed, pickedCategories } from "./evaluate.js";
+import { activationGroup, capUsed, isActivated, pickedCategories, } from "./evaluate.js";
 import { daysBetween } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
+import { activationRules } from "./setup.js";
+import { categoryPhrase, choiceName, currencyLabel, earnText, listed, words, } from "./text.js";
 import { cardValuation } from "./valuation.js";
-function capSummaries(card, held, today) {
+// 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];
+    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 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) : words(option);
+}
+// 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`];
+    const parts = [
+        ...(rule.match.categories ?? []).map((c) => categoryPhrase(catalog, c)),
+        ...(rule.match.merchants ?? []).map((m) => merchantName(catalog, m)),
+    ];
+    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);
+    if (quarter) {
+        const end = ['03-31', '06-30', '09-30', '12-31'][Number(quarter[2]) - 1];
+        return `${quarter[1] ?? ''}-${end ?? ''}`;
+    }
+    const month = /^(\d{4})-(\d{2})$/.exec(period);
+    if (month) {
+        const last = new Date(Date.UTC(Number(month[1]), Number(month[2]), 0));
+        return last.toISOString().slice(0, 10);
+    }
+    return /^\d{4}$/.test(period) ? `${period}-12-31` : null;
+}
+const applies = (rule, today) => (rule.valid_from === undefined || rule.valid_from <= today) &&
+    (rule.valid_to === undefined || rule.valid_to >= today);
+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 [
+        ...[...lines].map(([key, whats]) => `${key.replace('|activate', '')} ${listed(whats)}${key.endsWith('|activate') ? ' (once activated)' : ''}`),
+        `${earnText(catalog, card.base_rate, currency)} on everything else`,
+    ];
+}
+function toActivate(catalog, card, held, today) {
+    const seen = new Set();
+    const out = [];
+    for (const id of activationRules(card, today)) {
+        if (seen.has(id) || isActivated(card, held, id))
+            continue;
+        const group = activationGroup(card, id);
+        for (const g of group)
+            seen.add(g);
+        const rules = card.rules.filter((r) => group.includes(r.id));
+        const first = rules[0];
+        const when = first?.valid_from !== undefined && first.valid_to !== undefined
+            ? ` (${first.valid_from} to ${first.valid_to})`
+            : '';
+        out.push(`${rules.map((r) => ruleWhat(catalog, r)).join(', ')}${when}`);
+    }
+    return out;
+}
+function capSummaries(catalog, card, held, today) {
     const caps = new Map();
     for (const shared of card.caps)
         caps.set(shared.id, { cap: shared, rules: [] });
@@ -20,8 +130,15 @@ function capSummaries(card, held, today) {
     }
     return [...caps].map(([key, { cap, rules }]) => {
         const { period: currentPeriod, spent } = capUsed(cap, key, held, today);
+        const covered = card.rules.filter((r) => rules.includes(r.id));
+        const shared = card.caps.find((c) => c.id === key);
+        const label = shared?.rotating
+            ? 'the rotating bonus categories'
+            : [...new Set(covered.map((r) => ruleWhat(catalog, r)))].join(', ') ||
+                words(key);
         return {
             key,
+            label,
             rules,
             amount: cap.amount,
             period: cap.period,
@@ -47,20 +164,33 @@ 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,
             dataIsStale: daysBetween(card.last_verified, today) > STALE_AFTER_DAYS,
             rotationGap: rotationGap(card, today),
-            caps: capSummaries(card, held, today),
+            caps: capSummaries(catalog, card, held, today),
             chosen: held.chosen
                 ? {
                     period: held.chosen.period,
                     current: pickedCategories(card, held, today).staleChoice === null,
+                    // 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),
+                        options.map((o) => optionName(catalog, card, choice, o)),
+                    ])),
                 }
                 : null,
+            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,34 +1,37 @@
-import { money } from "../engine/text.js";
-const NETWORKS = {
-    visa: 'Visa',
-    mastercard: 'Mastercard',
-    amex: 'American Express',
-    discover: 'Discover',
-    store: 'store card',
-};
-const words = (id) => id.replace(/[-_.]/g, ' ');
+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.checkoutLabel ?? c.cardName} (${c.cardId}): ${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)
             lines.push(`  Works only at ${c.onlyAt.join(', ')}.`);
         if (c.chosen) {
-            const picks = Object.entries(c.chosen.picks)
-                .map(([choice, options]) => `${words(choice)}: ${options.map(words).join(', ')}`)
+            const picks = Object.entries(c.chosen.pickNames)
+                .map(([choice, names]) => `${choice}: ${names.join(', ')}`)
                 .join('; ');
-            lines.push(c.chosen.current
-                ? `  Picks for ${c.chosen.period}: ${picks}. They need choosing again when the period ends.`
-                : `  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.activated.length > 0)
-            lines.push(`  Activated: ${c.activated.join(', ')}.`);
+        if (c.toActivate.length > 0)
+            lines.push(`  Not activated yet: ${c.toActivate.join('; ')}. Activating once with the issuer covers each group.`);
         if (c.rotationGap !== null)
             lines.push(`  Rotating categories for ${c.rotationGap} aren't in earnrate yet.`);
         for (const cap of c.caps)
             if (cap.remaining !== null)
-                lines.push(`  Cap ${cap.key}: ${money(cap.spent)} of ${money(cap.amount)} used for ${cap.currentPeriod ?? ''}.`);
+                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/context.js

@@ -7,7 +7,7 @@ export const fail = (text) => ({
     content: [{ type: 'text', text }],
     isError: true,
 });
-export const ALL_CARDS_NOTE = "The user hasn't named their cards, so this covers every card earnrate knows. That's a complete answer. If they want the best of their own cards, they can name them (pass them as `cards`); saving a wallet is optional.";
+export const ALL_CARDS_NOTE = "No cards are saved or named, so this covers every card earnrate knows. That's a complete answer. If the user wants the best of their own cards, they can name them (pass them as `cards`); saving them is optional.";
 // What every tool shares: the saved wallet, merchant resolution, and which
 // cards an answer is about.
 export function makeContext(deps) {
@@ -15,7 +15,9 @@ export function makeContext(deps) {
     const theWallet = deps.savedWallets === 'file'
         ? `the wallet at ${deps.store.where}`
         : 'the saved wallet';
-    const noWallet = `There's no saved wallet yet${deps.savedWallets === 'file' ? ` (${deps.store.where})` : ''}. Answers don't need one: they cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.`;
+    const noWallet = deps.savedWallets === 'file'
+        ? `There's no saved wallet yet (${deps.store.where}). Answers don't need one: they cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.`
+        : "The user's saved wallet has no cards yet. Answers cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.";
     // Read on every call, so edits to the wallet apply without a restart.
     async function wallet() {
         let loaded;
@@ -79,7 +81,9 @@ export function makeContext(deps) {
         };
         const text = [
             message,
-            `Wallet: ${output.cardIds.join(', ')}.`,
+            output.cardIds.length > 0
+                ? `Wallet: ${output.cardIds.join(', ')}.`
+                : 'The wallet has no cards now; answers cover every card.',
             ...(notes ? [formatNotes(result.notes)] : []),
         ].join('\n');
         return {