earnrate 0.2.13 → 0.2.15

package/dist/engine/wallet-summary.js

@@ -4,12 +4,12 @@ import { introUntil, introWindows, openedOn } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestoneSummaries } from "./milestones.js";
 import { creditStates } from "./credits.js";
-import { creditWhere, optionName, ruleParts } from "./rule-text.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, categoryReadsOn, creditBack, creditLeft, ENROLL_FIRST, choiceName, currencyLabel, earnText, listed, PAYMENT_PHRASES, shortDate, wholeDollars, words, } from "./text.js";
+import { CAP_PERIODS, creditBack, creditLeft, ENROLL_FIRST, choiceName, currencyLabel, earnText, listed, PAYMENT_PHRASES, shortDate, wholeDollars, words, } from "./text.js";
 import { cardValuation, currencyValuation } from "./valuation.js";
 const matchKeys = (rule) => rule.match.choice !== undefined
     ? []
@@ -30,11 +30,9 @@ function capLimit(card, shown, rule) {
         shown.filter((r) => r.cap === rule.cap).length > 1;
     return `first ${wholeDollars(cap.amount)} ${CAP_PERIODS[cap.period]}${shared ? ', combined' : ''}`;
 }
-// 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.
+// Best first. Leaves out rates behind a membership the wallet lacks and a
+// 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 shown = card.rules
         .filter((r) => inEffect(r, today) &&
@@ -65,22 +63,28 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
         const pending = r.requires?.activation && !isActivated(card, held, r.id);
         const payment = r.requires?.payment;
         const key = [
-            `${earnText(catalog, r.rate, currency)} on`,
+            earnText(catalog, r.rate, currency),
             capLimit(card, shown, r),
             pending ? ', once activated' : '',
             payment === undefined ? '' : ` ${PAYMENT_PHRASES[payment]}`,
         ].join('|');
-        const whats = lines.get(key) ?? [];
-        for (const part of ruleParts(catalog, r))
+        const line = lines.get(key) ?? { at: [], on: [] };
+        const whats = line[rulePreposition(catalog, [r])];
+        for (const part of ruleParts(catalog, r, card))
             if (!whats.includes(part))
                 whats.push(part);
-        lines.set(key, whats);
+        lines.set(key, line);
     }
     return [
-        ...[...lines].map(([key, whats]) => {
+        ...[...lines].map(([key, { at, on }]) => {
             const [head = '', limit = '', activate = '', paid = ''] = key.split('|');
             const after = `${limit}${activate}`;
-            return `${head} ${listed(whats)}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
+            // "at gas stations and on transit" when one line mixes the two.
+            const where = [
+                ...(at.length > 0 ? [`at ${listed(at)}`] : []),
+                ...(on.length > 0 ? [`on ${listed(on)}`] : []),
+            ].join(at.length > 1 ? ', and ' : ' and ');
+            return `${head} ${where}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
         }),
         ...(shown.some((r) => r.match.any &&
             r.geography !== 'foreign_only' &&
@@ -103,13 +107,11 @@ export function activationsDue(catalog, card, held, today) {
             seen.add(g);
         const rules = card.rules.filter((r) => group.includes(r.id));
         const first = rules[0];
-        const categories = rules.flatMap((r) => r.match.categories ?? []);
-        const servicesOnly = categories.length > 0 &&
-            rules.every((r) => (r.match.merchants ?? []).length === 0) &&
-            categories.every((c) => categoryReadsOn(catalog, c));
         out.push({
-            what: listed([...new Set(rules.flatMap((r) => ruleParts(catalog, r)))]),
-            preposition: servicesOnly ? 'on' : 'at',
+            what: listed([
+                ...new Set(rules.flatMap((r) => ruleParts(catalog, r, card))),
+            ]),
+            preposition: rulePreposition(catalog, rules),
             from: first?.valid_from ?? null,
             to: first?.valid_to ?? null,
             activateBy: first?.activate_by ?? null,
@@ -154,8 +156,9 @@ function capSummaries(catalog, card, held, today) {
         const shared = card.caps.find((c) => c.id === key);
         const label = shared?.rotating
             ? 'the rotating bonus categories'
-            : listed([...new Set(covered.flatMap((r) => ruleParts(catalog, r)))]) ||
-                words(key);
+            : listed([
+                ...new Set(covered.flatMap((r) => ruleParts(catalog, r, card))),
+            ]) || words(key);
         return {
             key,
             label,

package/dist/format/card-text.js

@@ -1,8 +1,7 @@
-import { earnText } from "../engine/text.js";
 // 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 { CAP_PERIODS, PICK_PERIODS, wholeDollars, words, } from "../engine/text.js";
+import { capSentence, earnText, PICK_PERIODS, 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) {
@@ -42,7 +41,7 @@ export function cardText(catalog) {
         if (until !== null)
             lines.push(`This rate runs through ${until}`);
         if (r.cap)
-            lines.push(`Up to ${wholeDollars(r.cap.amount)} of spending ${CAP_PERIODS[r.cap.period]}, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}`);
+            lines.push(capSentence(r.cap, earnText(catalog, r.cap.thenRate, r.cap.currency)));
         return lines;
     }
     const memberName = (id) => membershipName(catalog, id);

package/dist/format/cards.js

@@ -1,10 +1,11 @@
+import { membershipName } from "../engine/memberships.js";
 import { foreignFeeText, money, NETWORK_NAMES } from "../engine/text.js";
-export function formatCardInfo(card) {
+export function formatCardInfo(catalog, card) {
     const fee = card.annualFee === null
         ? ''
         : card.annualFee === 0
             ? ', no annual fee'
-            : `, ${money(card.annualFee)} a year`;
+            : `, ${money(card.annualFee)} a year${card.firstYearFee === null ? '' : `, ${card.firstYearFee === 0 ? 'waived' : money(card.firstYearFee)} the first 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
@@ -13,7 +14,9 @@ export function formatCardInfo(card) {
             ]
             : []),
         ...(card.memberships.length > 0
-            ? [`rates that need a membership: ${card.memberships.join(', ')}`]
+            ? [
+                `rates that need a membership: ${card.memberships.map((id) => `${membershipName(catalog, id)} (membership id ${id})`).join(', ')}`,
+            ]
             : []),
         ...(card.activation.length > 0
             ? [`activate with the issuer: ${card.activation.join(', ')}`]
@@ -21,6 +24,7 @@ export function formatCardInfo(card) {
         ...(card.needsAnniversary ? ['cap resets on the card anniversary'] : []),
         ...card.milestones.map((m) => `spend bonus: ${m.text} (${m.id})`),
         ...card.introRates.map((i) => `new accounts: ${i.text}; needs the opening date`),
+        ...card.credits.map((c) => `statement credit ${c.id}: ${c.text}`),
         ...(card.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
         foreignFeeText(card.foreignTransactionFee).toLowerCase(),
     ];

package/dist/format/explore.js

@@ -1,5 +1,5 @@
 import { membershipName, membershipNote, } from "../engine/memberships.js";
-import { capitalize, choiceName, CREDIT_GROUP, CREDITS_LEFT_OUT, ENROLL_FIRST, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, } from "../engine/text.js";
+import { capitalize, choiceName, CREDIT_GROUP, CREDITS_LEFT_OUT, ENROLL_FIRST, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, listed, } from "../engine/text.js";
 const membershipFees = (memberships) => memberships
     .map((m) => ` + ${wholeDollars(m.annualFee)} for ${m.name}`)
     .join('');
@@ -51,7 +51,7 @@ export function formatExploration(r, catalog, all) {
     return `${lines.join('\n')}\n`;
 }
 function picksText(picks) {
-    const parts = Object.entries(picks).map(([choice, options]) => `${options.map(words).join(' and ')} as its ${choiceName(choice)} ${options.length === 1 ? 'pick' : 'picks'}`);
+    const parts = Object.entries(picks).map(([choice, options]) => `${listed(options.map(words))} as its ${choiceName(choice)} ${options.length === 1 ? 'pick' : 'picks'}`);
     return parts.length === 0 ? '' : ` (with ${parts.join('; ')})`;
 }
 function cardNamer(catalog) {

package/dist/format/wallet-yaml.js

@@ -1,9 +1,18 @@
 import { Document, parse, visit } from 'yaml';
 import { walletProblems } from "../data/integrity.js";
 import { CARD_NUMBER_LABEL, CARD_NUMBER_REDEMPTION, } from "../schema/card-number.js";
-import { WALLET_VERSION, WalletSchema } from "../schema/wallet.js";
+import { WALLET_VERSION, WalletCardSchema, 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.
+// Every field the schema defines, in its order, so a new wallet field is
+// exported without anyone remembering to add it here.
+const CARD_FIELDS = Object.keys(WalletCardSchema.shape);
+const isEmpty = (value) => value === undefined ||
+    (Array.isArray(value)
+        ? value.length === 0
+        : typeof value === 'object' &&
+            value !== null &&
+            Object.keys(value).length === 0);
 function compact(wallet) {
     return {
         version: wallet.version ?? WALLET_VERSION,
@@ -13,24 +22,11 @@ function compact(wallet) {
         ...(wallet.memberships.length > 0
             ? { memberships: wallet.memberships }
             : {}),
-        cards: wallet.cards.map((c) => ({
-            id: c.id,
-            ...(c.checkout_label === undefined
-                ? {}
-                : { checkout_label: c.checkout_label }),
-            ...(c.anniversary === undefined ? {} : { anniversary: c.anniversary }),
-            ...(c.opened === undefined ? {} : { opened: c.opened }),
-            ...(Object.keys(c.cap_usage).length > 0
-                ? { cap_usage: c.cap_usage }
-                : {}),
-            ...(c.chosen === undefined ? {} : { chosen: c.chosen }),
-            ...(c.activated.length > 0 ? { activated: c.activated } : {}),
-            ...(c.bonus === undefined ? {} : { bonus: c.bonus }),
-        })),
+        cards: wallet.cards.map((c) => Object.fromEntries(CARD_FIELDS.flatMap((k) => (isEmpty(c[k]) ? [] : [[k, c[k]]])))),
     };
 }
-// Dates, periods and anniversaries are quoted: YAML 1.1 parsers read a bare 2026-10-15 as a
-// date, not a string.
+// 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, {

package/dist/format/wallet.js

@@ -1,4 +1,4 @@
-import { CAP_PERIODS, introAdjective, introSince, money, NETWORK_NAMES, periodPhrase, roundCents, shortDate, } from "../engine/text.js";
+import { CAP_PERIODS, introAdjective, introSince, money, NETWORK_NAMES, periodPhrase, roundCents, shortDate, possessive, } from "../engine/text.js";
 // "To do now", above the card details; nothing when all's done.
 export function formatChecklist(items) {
     return items.length === 0
@@ -48,10 +48,10 @@ export function formatWalletSummary(summary) {
         else if (c.intro?.state === 'no-date')
             lines.push(`  Has ${introAdjective(c.intro.days)} rates for new accounts; give its opening date if it opened ${introSince(c.intro.days)}.`);
         else if (c.opened !== null)
-            lines.push(`  Opened ${c.opened}.`);
+            lines.push(`  Opened ${shortDate(c.opened)}.`);
         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 ?? ''}.`);
+            lines.push(`  Welcome bonus: ${money(b.spent)} of ${money(b.spend)} spent, due ${b.deadline === null ? 'by its deadline' : shortDate(b.deadline)}.`);
         else if (b)
             lines.push(`  Welcome bonus: ${b.state}.`);
         return lines.join('\n');
@@ -64,29 +64,33 @@ export function formatWalletSummary(summary) {
         : "Point values: earnrate's defaults.";
     return [...cards, memberships, values].join('\n');
 }
-export function formatBooking(amount, cardId, cap, bonus, milestones = [], credit = null) {
+export function formatBooking(amount, name, // the card's short name
+cap, bonus, milestones = [], credit = null, capLabel = null) {
     const messages = [];
     if (credit)
-        messages.push(`Used ${money(roundCents(credit.after - credit.before))} of ${cardId}'s ${credit.name} credit: ${money(credit.after)} of ${money(credit.amount)} ${periodPhrase(credit.periodKind, credit.period)}, ${money(roundCents(Math.max(0, credit.amount - credit.after)))} left.`);
+        messages.push(`Used ${money(roundCents(credit.after - credit.before))} of ${possessive(name)} ${credit.name} credit: ${money(credit.after)} of ${money(credit.amount)} ${periodPhrase(credit.periodKind, credit.period)}, ${money(roundCents(Math.max(0, credit.amount - credit.after)))} left.`);
     if (cap) {
         const left = Math.max(0, cap.capAmount - cap.after);
-        messages.push(`Recorded ${money(amount)} on ${cardId} against "${cap.capKey}": ${money(cap.before)} → ${money(cap.after)} of ${money(cap.capAmount)} ${periodPhrase(cap.periodKind, cap.period)}, ${money(left)} left.`);
+        messages.push(`Recorded ${money(amount)} on ${name} toward its ${capLabel ?? cap.capKey} cap: ${money(cap.before)} → ${money(cap.after)} of ${money(cap.capAmount)} ${periodPhrase(cap.periodKind, cap.period)}, ${money(left)} left.`);
     }
     if (bonus) {
         const left = Math.max(0, bonus.spend - bonus.after);
         messages.push(left === 0
-            ? `Welcome bonus spend met on ${cardId}: ${money(bonus.after)} of ${money(bonus.spend)}.`
-            : `Welcome bonus on ${cardId}: ${money(bonus.after)} of ${money(bonus.spend)} spent, ${money(left)} to go by ${bonus.deadline ?? 'the deadline'}.`);
+            ? `Welcome bonus spend met on ${name}: ${money(bonus.after)} of ${money(bonus.spend)}.`
+            : `Welcome bonus on ${name}: ${money(bonus.after)} of ${money(bonus.spend)} spent, ${money(left)} to go by ${bonus.deadline === null ? 'the deadline' : shortDate(bonus.deadline)}.`);
     }
     // Every milestone counts the same purchases, so one line covers them.
     const first = milestones[0];
     if (first) {
         const reached = milestones.filter((m) => m.before < m.spend && m.after >= m.spend);
         const next = milestones.find((m) => m.after < m.spend);
+        const period = first.periodKind === 'cardmember_year' ? 'cardmember year' : 'year';
         messages.push([
-            `Spend on ${cardId} this ${first.periodKind === 'cardmember_year' ? 'cardmember year' : 'year'}: ${money(first.after)}.`,
+            first.started
+                ? `Started tracking spend on ${name} this ${period} with this purchase: ${money(first.after)}. Spending on it earlier this ${period} isn't counted; give the total so far (milestoneSpent) to include it.`
+                : `Spend on ${name} this ${period}: ${money(first.after)}.`,
             ...reached.map((m) => `That reaches its ${money(m.spend)} spend bonus.`),
-            ...(next
+            ...(next && !first.started
                 ? [
                     `${money(next.spend - next.after)} to go for the ${money(next.spend)} spend bonus.`,
                 ]

package/dist/import/analyze.js

@@ -4,7 +4,7 @@ import { capByKey, categoryMatches } from "../engine/evaluate.js";
 import { milestoneProgress } from "../engine/milestones.js";
 import { periodKey } from "../engine/periods.js";
 import { recommend } from "../engine/recommend.js";
-import { applyBooking, capBooking } from "../engine/record.js";
+import { applyBooking, applyCreditBooking, capBooking, creditBooking, } from "../engine/record.js";
 import { roundCents } from "../engine/text.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { cleanDescriptor } from "./statement.js";
@@ -55,6 +55,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
     const missed = new Map();
     const coding = new Map();
     const bookings = [];
+    const credits = [];
     let outsideCurrentPeriod = 0;
     let alreadyImported = 0;
     let purchases = 0;
@@ -145,6 +146,16 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
                 outsideCurrentPeriod++;
             }
         }
+        if (line.amount > 0 && !alreadyRecorded(entry, 'credit')) {
+            const credit = creditBooking(catalog, current, recorded, merchant);
+            const held = current.cards.find((c) => c.id === cardId);
+            if (credit &&
+                periodKey(credit.periodKind, today, held?.anniversary ?? null) ===
+                    credit.period) {
+                credits.push({ ...entry, booking: credit });
+                current = applyCreditBooking(current, credit);
+            }
+        }
         if (line.amount < 0) {
             refunds += -line.amount;
             continue;
@@ -244,6 +255,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
             .sort((a, b) => b.best - b.earned - (a.best - a.earned)),
         coding: [...coding.values()].sort((a, b) => b.count - a.count),
         bookings,
+        credits,
         outsideCurrentPeriod,
         alreadyImported,
         bonuses: [...bonuses.values()].filter((b) => b.entries.length > 0),

package/dist/mcp/context.js

@@ -72,9 +72,8 @@ export function makeContext(deps) {
     }
     // Cards named in the conversation come first, then the saved wallet; with
     // neither (null), answers cover every card earnrate knows.
-    // The point values and memberships the user saved apply to every answer,
-    // not just ones from their saved cards. A wallet that can't be read has
-    // none.
+    // Saved point values and memberships apply to every answer, not just ones
+    // from saved cards. A wallet that can't be read has none.
     async function saved() {
         try {
             const wallet = await deps.store.load();

package/dist/mcp/inputs.js

@@ -80,15 +80,15 @@ const cardFields = {
     milestoneSpent: z
         .record(z.string(), z.number().nonnegative())
         .optional()
-        .describe('Dollars already spent on the card this year, for its spend milestones (bonuses after a yearly spending total, as search_cards lists them): milestone id → dollars, e.g. {"spend-15k": 9000}. Every purchase on the card counts, so give each milestone the same total. Ask; recorded purchases add to it from then on.'),
+        .describe('Dollars already spent on the card this year, for its spend bonuses (bonuses after a yearly spending total, as search_cards lists them): milestone id → dollars, e.g. {"spend-15k": 9000}. Every purchase on the card counts, so give each milestone the same total. Ask; recorded purchases add to it from then on.'),
     enrolled: z
         .array(z.string())
         .optional()
-        .describe('Merchant 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 (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.'),
     creditUsed: z
         .record(z.string(), z.number().nonnegative())
         .optional()
-        .describe('Dollars of a merchant credit already received this period: credit id → dollars, e.g. {"lululemon": 40}. Ask; recorded purchases add to it from then on.'),
+        .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.'),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),

package/dist/mcp/schemas.js

@@ -245,6 +245,7 @@ export const RecordResultSchema = z.object({
         spend: z.number(),
         before: z.number(),
         after: z.number(),
+        started: z.boolean(),
     })),
     credit: z
         .object({
@@ -297,6 +298,7 @@ export const CardSearchSchema = z.object({
         network: CardNetwork,
         currency: z.string(),
         annualFee: z.number().nullable(),
+        firstYearFee: z.number().nullable(),
         foreignTransactionFee: z.number().nullable(),
         business: z.boolean(),
         onlyAt: z.array(z.string()).nullable(),

package/dist/mcp/server.js

@@ -6,7 +6,6 @@ import { registerPrompts } from "./prompts.js";
 import { registerAccountTools } from "./tools/account.js";
 import { registerAnswerTools } from "./tools/answers.js";
 import { registerWalletTools } from "./tools/wallet.js";
-// The tools that answer without a saved wallet.
 export const ANSWER_TOOLS = [
     'best_card_for_purchase',
     'best_cards_for',
@@ -16,7 +15,6 @@ export const ANSWER_TOOLS = [
     'resolve_merchant',
     'search_cards',
 ];
-// The tools that read or change a saved wallet.
 export const SAVED_WALLET_TOOLS = [
     'list_wallet',
     'record_purchase',

package/dist/mcp/tools/account.js

@@ -20,7 +20,7 @@ export function registerAccountTools(server, catalog, store, ctx) {
     ];
     server.registerTool('export_wallet', {
         title: 'Export the wallet',
-        description: 'The saved wallet as a wallet.yaml file the earnrate command line and earnrate.dev can import: card ids, picks, activations, memberships, point values, cap usage, bonus progress and yearly spending toward spend bonuses. Never card numbers.',
+        description: 'The saved wallet as a wallet.yaml file: card ids, checkout labels, picks, activations, opening dates and anniversaries, memberships, point values, cap usage, welcome-bonus progress, yearly spending toward spend bonuses, and statement credits enrolled in and used. earnrate.dev imports it, and the earnrate command line reads it saved as ~/.earnrate/wallet.yaml. Never card numbers.',
         inputSchema: z.object({}),
         outputSchema: z.object({ yaml: z.string() }),
         annotations: {

package/dist/mcp/tools/answers.js

@@ -34,7 +34,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     const { CategoryInput, CatalogCategory, NamedCards, NamedMemberships, OfferFilters, CatalogFilters, } = inputs;
     server.registerTool('best_card_for_purchase', {
         title: 'Best card for a purchase',
-        description: "Which credit card earns the most rewards for a purchase, and why. With no cards given and no saved wallet, it ranks every card earnrate knows (in `allCards`): a complete answer for anyone. With cards named in the conversation (`cards`) or a saved wallet, it picks the best of the user's own: `decision.cardId` is the pick and `decision.checkoutLabel` is how the card appears at checkout, with every usable card ranked with reasons, cards the merchant won't take, assumptions, warnings, and when a different point valuation would change the pick. For a business earnrate may not know, like a local restaurant, pass `category` when you can tell what kind of business it is. When the user is paying outside the U.S. or in another currency, pass `country`: abroad, each card is ranked after its foreign transaction fee. Pass `payment` only when the user says how they're paying, like Apple Pay or PayPal checkout. A merchant statement credit (a card's `credit`, like Amex Platinum's lululemon credit) counts toward the pick only once it's enrolled in the wallet and has dollars left this period, and only when the amount is given; say its dollars apart from the % back. With no cards, `allCards.credits` lists cards with a credit at the store; present those first. Never needs or returns card numbers.",
+        description: "Which credit card earns the most rewards for a purchase, and why. With no cards given and no saved wallet, it ranks every card earnrate knows (in `allCards`): a complete answer for anyone. With cards named in the conversation (`cards`) or a saved wallet, it picks the best of the user's own: `decision.cardId` is the pick and `decision.checkoutLabel` is how the card appears at checkout, with every usable card ranked with reasons, cards the merchant won't take, assumptions, warnings, and when a different point valuation would change the pick. For a business earnrate may not know, like a local restaurant, pass `category` when you can tell what kind of business it is. When the user is paying outside the U.S. or in another currency, pass `country`: abroad, each card is ranked after its foreign transaction fee. Pass `payment` only when the user says how they're paying, like Apple Pay or PayPal checkout. A statement credit (a card's `credit`, like Amex Platinum's lululemon credit) counts toward the pick only once it's enrolled in the wallet and has dollars left this period, and only when the amount is given; say its dollars apart from the % back. With no cards, `allCards.credits` lists cards with a credit at the store; present those first. Never needs or returns card numbers.",
         inputSchema: z.object({
             merchant: Merchant,
             amount: z
@@ -166,6 +166,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 .optional()
                 .describe('Include cards already in the wallet.'),
             cards: NamedCards,
+            memberships: NamedMemberships,
         }),
         outputSchema: OfferComparisonSchema,
         annotations: {
@@ -175,10 +176,13 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             openWorldHint: false,
         },
     }, async (args) => {
-        const wallet = await ctx.cardsFor(args.cards, undefined);
+        const wallet = await ctx.cardsFor(args.cards, args.memberships);
         if (typeof wallet === 'string')
             return fail(wallet);
-        const base = wallet ?? { ...EMPTY_WALLET, ...(await ctx.saved()) };
+        const found = wallet ?? { ...EMPTY_WALLET, ...(await ctx.saved()) };
+        const base = args.memberships
+            ? { ...found, memberships: args.memberships }
+            : found;
         const comparison = compareOffers(catalog, args.valuation ? withValuationProfile(base, args.valuation) : base, {
             kind: args.kind ?? 'any',
             noAnnualFee: args.noAnnualFee ?? false,
@@ -391,7 +395,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     });
     server.registerTool('search_cards', {
         title: 'Search cards',
-        description: 'Finds credit cards in earnrate\'s catalog by name or issuer, e.g. "sapphire", "amex gold" or "bofa". Returns each card\'s id (for add_card), network, annual fee, whether it\'s already in the wallet, and what it needs set up: category picks and their options, memberships, activations. Leave the query out to list every card. US cards only.',
+        description: 'Finds credit cards in earnrate\'s catalog by name or issuer, e.g. "sapphire", "amex gold" or "bofa". Returns each card\'s id (for add_card), network, annual fee (and any first-year waiver), foreign transaction fee, whether it\'s already in the wallet, what it needs set up (category picks and their options, memberships, activations), its yearly spend bonuses, first-year rates and statement credits, each with the id update_card takes. Leave the query out to list every card. US cards only.',
         inputSchema: z.object({
             query: z
                 .string()
@@ -417,7 +421,8 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             content: [
                 {
                     type: 'text',
-                    text: header + result.cards.map(formatCardInfo).join('\n'),
+                    text: header +
+                        result.cards.map((c) => formatCardInfo(catalog, c)).join('\n'),
                 },
             ],
             structuredContent: result,

package/dist/mcp/tools/wallet.js

@@ -63,12 +63,11 @@ function changes(catalog, args) {
         out.push(`welcome bonus tracked from ${args.bonus.opened}, ${money(args.bonus.spent ?? 0)} spent so far`);
     return out;
 }
-// The tools that read or change a saved wallet.
 export function registerWalletTools(server, deps, ctx, inputs) {
     const { catalog, store } = deps;
     server.registerTool('list_wallet', {
         title: 'List wallet',
-        description: `Starts with a to-do list for the user's cards right now (bonuses to activate and their deadlines, categories to pick or confirm, caps nearly used up, welcome bonuses to finish and the weekly pace, yearly spend bonuses at least 75% of the way, merchant credits to enroll in or use before they reset); use it when the user asks what to do with their cards this quarter or what they're forgetting. Then lists the user's cards: checkout label, network, rewards currency and its value, spending caps with how much is left this period, chosen bonus categories (and whether they're current), welcome-bonus progress, progress toward yearly spend bonuses, merchant statement credits (enrolled or not, and what's left this period), which stores a store card works at, when each card's data was last verified, the point values the user saved, and (for the hosted wallet) when it was started. ${ctx.walletUse}`,
+        description: `Starts with a to-do list for the user's cards right now (bonuses to activate and their deadlines, categories to pick or confirm, caps nearly used up, welcome bonuses to finish and the weekly pace, yearly spend bonuses at least 75% of the way, statement credits to enroll in or use before they reset); use it when the user asks what to do with their cards this quarter or what they're forgetting. Then lists the user's cards: checkout label, network, rewards currency and its value, spending caps with how much is left this period, chosen bonus categories (and whether they're current), welcome-bonus progress, progress toward yearly spend bonuses, statement credits (enrolled or not, and what's left this period), which stores a store card works at, when each card's data was last verified, the point values the user saved, and (for the hosted wallet) when it was started. ${ctx.walletUse}`,
         outputSchema: WalletSummarySchema,
         annotations: {
             title: 'List wallet',
@@ -102,7 +101,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('record_purchase', {
         title: 'Record a purchase',
-        description: `Records a purchase the user has already made, so spending caps, welcome-bonus progress, yearly spend milestones and merchant credits used stay accurate for future recommendations. It updates the user's saved wallet. Only call it after the purchase has happened, and only once per purchase: calling it twice counts the spend twice. Purchases with no cap, no open welcome bonus, no spend milestone and no enrolled merchant credit are acknowledged and nothing is written. For a merchant earnrate doesn't recognize it asks for category first, so caps aren't missed. ${ctx.walletUse}`,
+        description: `Records a purchase the user has already made, so spending caps, welcome-bonus progress, yearly spend bonuses and statement credits used stay accurate for future recommendations. It updates the user's saved wallet. Only call it after the purchase has happened, and only once per purchase: calling it twice counts the spend twice. Purchases with no cap, no open welcome bonus, no spend bonus and no enrolled statement credit are acknowledged and nothing is written. For a merchant earnrate doesn't recognize it asks for category first, so caps aren't missed. ${ctx.walletUse}`,
         inputSchema: z.object({
             cardId: z
                 .string()
@@ -142,6 +141,11 @@ export function registerWalletTools(server, deps, ctx, inputs) {
         if (!result.ok)
             return fail(`Couldn't record it: ${result.error}`);
         const { cap: booking, bonus, milestones, credit } = result;
+        const capLabel = booking
+            ? (walletSummary(catalog, w, purchase.date)
+                .cards.find((c) => c.cardId === cardId)
+                ?.caps.find((c) => c.key === booking.capKey)?.label ?? null)
+            : null;
         const output = booking || bonus || milestones.length > 0 || credit
             ? {
                 recorded: true,
@@ -149,7 +153,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
                 bonus,
                 milestones,
                 credit,
-                message: `${formatBooking(amount, cardId, booking, bonus, milestones, credit)} Saved in ${ctx.walletName}.`,
+                message: `${formatBooking(amount, cardText(catalog).shortName(cardId), booking, bonus, milestones, credit, capLabel)} Saved in ${ctx.walletName}.`,
             }
             : {
                 recorded: false,
@@ -157,7 +161,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
                 bonus: null,
                 milestones: [],
                 credit: null,
-                message: `Nothing to track: ${cardId} has no spending cap, open welcome bonus, spend milestone or enrolled merchant credit for this purchase, so the wallet wasn't changed.`,
+                message: `Nothing to track: ${cardText(catalog).shortName(cardId)} has no spending cap, open welcome bonus, spend bonus or enrolled statement credit for this purchase, so the wallet wasn't changed.`,
             };
         return {
             content: [
@@ -191,7 +195,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('update_card', {
         title: 'Update a card',
-        description: `Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, opening date (optional; for first-year rates), activated categories, cap spending so far (capSpent), spending this year toward its spend milestones (milestoneSpent), merchant credits enrolled in (enrolled) and used this period (creditUsed), or a welcome bonus to track. Picks replace the saved ones in each choice group you set (other groups are kept) for the current period. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+. ${ctx.walletUse}`,
+        description: `Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, opening date (optional; for first-year rates), activated categories, cap spending so far (capSpent), spending this year toward its spend bonuses (milestoneSpent), statement credits enrolled in (enrolled) and used this period (creditUsed), or a welcome bonus to track. Picks replace the saved ones in each choice group you set (other groups are kept) for the current period. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+. ${ctx.walletUse}`,
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
         annotations: {

package/dist/schema/card.js

@@ -157,11 +157,9 @@ export const ChoiceSchema = z.strictObject({
         })),
     ])),
 });
-// A rate for a stretch after the account opens, counted from the opening
-// day: Discover's Cashback Match doubles every rate for the first 365 days,
-// Customized Cash adds 3% to its choice category. With `rules`, it changes
-// only those rules' rates, inside their caps; past a cap they earn what they
-// always do. Without, it changes every rate on the card, past caps included.
+// Counted from the opening day. With `rules`, it changes only those rules'
+// rates, inside their caps; past a cap they earn what they always do.
+// Without, it changes every rate on the card, past caps included.
 export const IntroRateSchema = z
     .strictObject({
     id: KebabId,
@@ -172,11 +170,9 @@ export const IntroRateSchema = z
     note: z.string().optional(),
 })
     .refine((i) => (i.multiply === undefined) !== (i.add === undefined), 'an intro rate needs multiply or add, not both');
-// Merchant statement credits: dollars back for spending at named merchants
-// (or a category) up to `amount` each period, like Amex Platinum's $75 a
-// quarter at lululemon. They're separate from earn rates: the purchase still
-// earns the card's rate on its whole amount, and the credit comes on top.
-// `half_year` runs January to June and July to December.
+// Separate from earn rates: the purchase still earns the card's rate on its
+// whole amount, and the credit comes on top. `half_year` runs January to June
+// and July to December.
 export const CreditPeriod = z.enum([...CapPeriod.options, 'half_year']);
 export const CreditSchema = z.strictObject({
     id: KebabId,

package/dist/schema/merchant.js

@@ -34,6 +34,9 @@ export const MerchantSchema = z.strictObject({
     // Costco Travel), or a booking made through one (booking: "Hotel through
     // Amex Travel").
     kind: z.enum(['portal', 'booking']).optional(),
+    // "on Walmart+ membership" rather than "at": a membership or subscription,
+    // not a store.
+    preposition: z.literal('on').optional(),
     note: z.string().optional(),
 });
 export const MerchantsFileSchema = z.array(MerchantSchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Which credit card earns the most at a merchant, from your cards or every card, and why",
   "keywords": [
     "credit cards",
@@ -54,6 +54,7 @@
     "monitor:deploy": "WRANGLER_SEND_METRICS=false wrangler deploy --config monitor/wrangler.jsonc",
     "site:build": "vite build site && node scripts/build-pages.ts",
     "site:dev": "vite site",
+    "site:preview": "yarn site:build && WRANGLER_SEND_METRICS=false wrangler deploy --config wrangler.preview.jsonc",
     "site:deploy": "yarn site:build && WRANGLER_SEND_METRICS=false wrangler deploy && node scripts/indexnow.ts",
     "test": "vitest run",
     "test:watch": "vitest",