earnrate 0.2.12 → 0.2.14

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,20 +22,7 @@ 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

package/dist/format/wallet.js

@@ -1,4 +1,4 @@
-import { CAP_PERIODS, introAdjective, introSince, money, NETWORK_NAMES, periodPhrase, 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
@@ -39,6 +39,8 @@ export function formatWalletSummary(summary) {
                 : `  Cap on ${cap.label}: ${money(cap.spent)} of ${money(cap.amount)} used ${periodPhrase(cap.period, cap.currentPeriod ?? '')}${cap.until === null ? '' : `, through ${shortDate(cap.until)}`} (cap key ${cap.key}).`);
         for (const m of c.milestones)
             lines.push(`  Spend bonus (${m.id}): ${m.text}`);
+        for (const credit of c.credits)
+            lines.push(`  Credit (${credit.id}): ${credit.text}`);
         if (c.anniversary !== null)
             lines.push(`  Account anniversary: ${c.anniversary}.`);
         if (c.intro?.state === 'active' && c.intro.until !== null)
@@ -62,27 +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 = []) {
+export function formatBooking(amount, name, // the card's short name
+cap, bonus, milestones = [], credit = null) {
     const messages = [];
+    if (credit)
+        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} against "${cap.capKey}": ${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 ?? 'the 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

@@ -182,8 +182,13 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
             date: line.date,
             country: 'US',
         };
-        const used = recommend(catalog, actual, purchase, merchant).ranked.find((r) => r.cardId === cardId);
-        const top = recommend(catalog, simulated, purchase, merchant).ranked[0];
+        // Past statements don't say which credits were used, so they're left out.
+        const used = recommend(catalog, actual, purchase, merchant, {
+            credits: false,
+        }).ranked.find((r) => r.cardId === cardId);
+        const top = recommend(catalog, simulated, purchase, merchant, {
+            credits: false,
+        }).ranked[0];
         if (!used || !top)
             continue;
         earned += used.earned ?? 0;

package/dist/mcp/inputs.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ALL_PERSONAL_CARDS } from "../engine/explore.js";
 import { profileText, VALUATION_PROFILES } from "../engine/profiles.js";
 import { knownMemberships } from "../engine/setup.js";
+import { PaymentMethod } from "../schema/card.js";
 import { IsoDate } from "../schema/common.js";
 import { COUNTRY_CODE } from "../schema/common.js";
 export const Merchant = z
@@ -18,6 +19,7 @@ export const CountryInput = z
     .regex(COUNTRY_CODE, 'Use a two-letter country code, like US or FR.')
     .optional()
     .describe('Where the purchase is made, as a two-letter country code (FR, GB, JP). Pass it when the user is paying abroad or in another currency: abroad, cards are ranked after their foreign transaction fees. Default US.');
+export const PaymentInput = PaymentMethod.optional().describe("How the purchase is paid, only when the user says: card (the card itself or its number), apple-pay, google-pay or paypal (PayPal checkout). Optional; omit it when unknown, and never assume Apple Pay. Some rates need one (Apple Card's 2% with Apple Pay, PayPal Cashback's 3% through PayPal checkout), and the answer's assumptions say when paying another way would change the pick.");
 export const CardId = z
     .string()
     .min(1)
@@ -79,6 +81,14 @@ const cardFields = {
         .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.'),
+    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.'),
+    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.'),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),

package/dist/mcp/prompts.js

@@ -33,10 +33,15 @@ export function registerPrompts(server, deps, ctx) {
                 .string()
                 .optional()
                 .describe('Where you are paying, if not the U.S.: FR, Japan'),
+            paying: z
+                .string()
+                .optional()
+                .describe('How you are paying, if you know: Apple Pay, PayPal'),
         }),
     }, (args) => {
         const amount = args.amount?.trim() || null;
         const country = args.country?.trim() || null;
+        const paying = args.paying?.trim() || null;
         const call = [
             `merchant ${JSON.stringify(args.store)}`,
             ...(amount === null
@@ -45,8 +50,11 @@ export function registerPrompts(server, deps, ctx) {
             ...(country === null
                 ? []
                 : [`country as the two-letter code for ${JSON.stringify(country)}`]),
+            ...(paying === null
+                ? []
+                : [`payment for paying with ${JSON.stringify(paying)}`]),
         ];
-        return ask(`Which credit card should I use at ${args.store}${amount === null ? '' : ` for ${dollars(amount)}`}${country === null ? '' : ` in ${country}`}?`, [
+        return ask(`Which credit card should I use at ${args.store}${amount === null ? '' : ` for ${dollars(amount)}`}${country === null ? '' : ` in ${country}`}${paying === null ? '' : ` with ${paying}`}?`, [
             `Call earnrate's best_card_for_purchase with ${call.join(', ')}.`,
             `It answers from ${FROM_SAVED_OR_ALL}, so don't ask for their cards first.`,
             'Say which card to use and why, with the assumptions and warnings it gives.',

package/dist/mcp/schemas.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { CapPeriod, MilestoneSchema } from "../schema/card.js";
+import { CapPeriod, CreditPeriod, MilestoneSchema } from "../schema/card.js";
 const MilestonePeriod = MilestoneSchema.shape.period;
 import { CardNetwork, Network } from "../schema/common.js";
 // Mirrors the engine's result types. The SDK validates every structured
@@ -43,6 +43,18 @@ const RankedCardSchema = z.object({
     milestoneBonus: z
         .object({ points: z.number(), dollars: z.number() })
         .nullable(),
+    credit: z
+        .object({
+        id: z.string(),
+        name: z.string(),
+        amount: z.number(),
+        period: CreditPeriod,
+        enrolled: z.boolean(),
+        left: z.number().nullable(),
+        until: z.string().nullable(),
+        dollars: z.number().nullable(),
+    })
+        .nullable(),
     capped: z.boolean(),
     reasoning: z.array(z.string()),
     warnings: z.array(z.string()),
@@ -101,8 +113,11 @@ export const WalletSummarySchema = z.object({
             'milestone',
             'rotation',
             'intro',
+            'credit',
+            'enroll',
         ]),
         cardId: z.string(),
+        ref: z.string().optional(),
         text: z.string(),
         due: z.string().nullable(),
     }))
@@ -157,6 +172,20 @@ export const WalletSummarySchema = z.object({
             rewards: z.array(z.string()),
             text: z.string(),
         })),
+        credits: z.array(z.object({
+            id: z.string(),
+            name: z.string(),
+            amount: z.number(),
+            period: CreditPeriod,
+            enroll: z.boolean(),
+            enrolled: z.boolean(),
+            currentPeriod: z.string().nullable(),
+            until: z.string().nullable(),
+            used: z.number(),
+            left: z.number().nullable(),
+            tracked: z.boolean(),
+            text: z.string(),
+        })),
         chosen: z
             .object({
             period: z.string(),
@@ -216,7 +245,20 @@ export const RecordResultSchema = z.object({
         spend: z.number(),
         before: z.number(),
         after: z.number(),
+        started: z.boolean(),
     })),
+    credit: z
+        .object({
+        cardId: z.string(),
+        creditId: z.string(),
+        name: z.string(),
+        period: z.string(),
+        periodKind: CreditPeriod,
+        amount: z.number(),
+        before: z.number(),
+        after: z.number(),
+    })
+        .nullable(),
     message: z.string(),
 });
 export const OfferComparisonSchema = z.object({
@@ -287,6 +329,14 @@ export const CardSearchSchema = z.object({
             text: z.string(),
         })),
         introRates: z.array(z.object({ id: z.string(), days: z.number(), text: z.string() })),
+        credits: z.array(z.object({
+            id: z.string(),
+            name: z.string(),
+            amount: z.number(),
+            period: CreditPeriod,
+            enroll: z.boolean(),
+            text: z.string(),
+        })),
     })),
 });
 export const WalletChangeSchema = z.object({
@@ -315,6 +365,25 @@ const ExcludedCardSchema = z.object({
 const Picks = z.record(z.string(), z.array(z.string()));
 export const ExplorationSchema = z.object({
     merchant: MerchantResolutionSchema,
+    // Cards with a statement credit at this store, shown before the ranking.
+    credits: z.array(z.object({
+        cardId: z.string(),
+        cardName: z.string(),
+        issuer: z.string(),
+        network: CardNetwork,
+        annualFee: z.number().nullable(),
+        firstYearFee: z.number().nullable(),
+        creditId: z.string(),
+        name: z.string(),
+        amount: z.number(),
+        period: CreditPeriod,
+        enroll: z.boolean(),
+        note: z.string().nullable(),
+        back: z.string(),
+        earn: z.string(),
+        text: z.string(),
+        evidence: z.object({ quote: z.string(), url: z.string() }).nullable(),
+    })),
     ranked: z.array(RankedCardSchema.extend({
         issuer: z.string(),
         network: CardNetwork,
@@ -403,6 +472,7 @@ export const CheatSheetSchema = z.object({
         note: z.string().nullable(),
     })),
     notes: z.array(z.string()),
+    assumptions: z.array(z.string()),
 });
 export const PurchaseAnswerSchema = RecommendationSchema.extend({
     // Every card earnrate knows, ranked: set when no cards were given.

package/dist/mcp/tools/answers.js

@@ -15,7 +15,7 @@ import { formatOffers } from "../../format/offers.js";
 import { formatRecommendation } from "../../format/recommendation.js";
 import { resolvePlace, withCallerCategory } from "../../merchants/resolve.js";
 import { ALL_CARDS_NOTE, fail } from "../context.js";
-import { ChannelInput, CountryInput, DateInput, Merchant, settings, } from "../inputs.js";
+import { ChannelInput, CountryInput, PaymentInput, DateInput, Merchant, settings, } from "../inputs.js";
 import { CardSearchSchema, CheatSheetSchema, ExplorationSchema, MerchantResolutionSchema, OfferComparisonSchema, PurchaseAnswerSchema, SpendingSimulationSchema, } from "../schemas.js";
 const SOURCES = {
     override: "from earnrate's merchant list",
@@ -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. 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 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.",
         inputSchema: z.object({
             merchant: Merchant,
             amount: z
@@ -45,6 +45,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             channel: ChannelInput,
             date: DateInput,
             country: CountryInput,
+            payment: PaymentInput,
             category: CategoryInput,
             cards: NamedCards,
             memberships: NamedMemberships,
@@ -57,7 +58,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             destructiveHint: false,
             openWorldHint: deps.llm !== null,
         },
-    }, async ({ merchant, amount, channel, date, country, category, cards, memberships, valuation, }) => {
+    }, async ({ merchant, amount, channel, date, country, payment, category, cards, memberships, valuation, }) => {
         const held = await ctx.cardsFor(cards, memberships);
         if (typeof held === 'string')
             return fail(held);
@@ -70,6 +71,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             channel: channel ?? null,
             date: date ?? deps.today(),
             country: (country ?? 'US').toUpperCase(),
+            payment: payment ?? null,
         };
         const resolved = await ctx.resolve(merchant, purchase.channel, category ?? null);
         const retry = resolved.merchant.source === 'none'
@@ -83,6 +85,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 channel: purchase.channel,
                 date: purchase.date,
                 country: purchase.country,
+                payment: purchase.payment,
             }, settings({ memberships, valuation }, await ctx.saved()), resolved.merchant);
             const allCards = { ...explored, ranked: explored.ranked.slice(0, TOP) };
             const empty = recommend(catalog, EMPTY_WALLET, purchase, resolved.merchant);
@@ -205,7 +208,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     });
     server.registerTool('best_cards_for', {
         title: 'Best cards for a purchase',
-        description: 'Ranks every card earnrate knows that takes new applicants, not only the user\'s, for one purchase or category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Use it for questions like "what\'s the best card for groceries?" or "which card should I get for Amazon?". It needs no wallet. For which of the user\'s own cards to use, call best_card_for_purchase instead. Mention the annual fee and any conditions alongside each card.',
+        description: 'Ranks every card earnrate knows that takes new applicants, not only the user\'s, for one purchase or category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Use it for questions like "what\'s the best card for groceries?" or "which card should I get for Amazon?". It needs no wallet. For which of the user\'s own cards to use, call best_card_for_purchase instead. Mention the annual fee and any conditions alongside each card. For a store, cards with a statement credit there come first in `credits` ("$75 back each quarter, then 1x Amex Membership Rewards"): present them first, in dollars and never as a percentage, saying when the cardholder must enroll, then the ranking by rate.',
         inputSchema: z.object({
             merchant: Merchant.optional(),
             category: CatalogCategory.optional(),
@@ -216,6 +219,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 .describe('Purchase amount in US dollars, if known.'),
             channel: ChannelInput,
             country: CountryInput,
+            payment: PaymentInput,
             ...CatalogFilters,
         }),
         outputSchema: ExplorationSchema,
@@ -236,6 +240,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             channel,
             date: deps.today(),
             country: (args.country ?? 'US').toUpperCase(),
+            payment: args.payment ?? null,
         }, settings(args, await ctx.saved()), args.merchant === undefined
             ? undefined
             : withCallerCategory(resolvePlace(catalog, args.merchant, channel), args.category ?? null));
@@ -412,7 +417,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

@@ -51,6 +51,12 @@ function changes(catalog, args) {
         out.push(`${money(spent)} already spent on ${key} this period`);
     for (const [id, spent] of Object.entries(args.milestoneSpent ?? {}))
         out.push(`${money(spent)} spent toward ${id} this ${card?.milestones.find((m) => m.id === id)?.period === 'cardmember_year' ? 'cardmember year' : 'year'}`);
+    if (args.enrolled !== undefined)
+        out.push(args.enrolled.length === 0
+            ? 'no credits enrolled'
+            : `enrolled in: ${args.enrolled.join(', ')}`);
+    for (const [id, used] of Object.entries(args.creditUsed ?? {}))
+        out.push(`${money(used)} of the ${id} credit used this period`);
     if (args.bonus === null)
         out.push('welcome bonus no longer tracked');
     else if (args.bonus !== undefined)
@@ -62,7 +68,7 @@ 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); 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, 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, 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}`,
         outputSchema: WalletSummarySchema,
         annotations: {
             title: 'List wallet',
@@ -96,7 +102,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 and yearly spend milestones 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 and no spend milestone 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 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}`,
         inputSchema: z.object({
             cardId: z
                 .string()
@@ -135,21 +141,23 @@ export function registerWalletTools(server, deps, ctx, inputs) {
         const result = await store.record(purchase, resolved.merchant);
         if (!result.ok)
             return fail(`Couldn't record it: ${result.error}`);
-        const { cap: booking, bonus, milestones } = result;
-        const output = booking || bonus || milestones.length > 0
+        const { cap: booking, bonus, milestones, credit } = result;
+        const output = booking || bonus || milestones.length > 0 || credit
             ? {
                 recorded: true,
                 booking,
                 bonus,
                 milestones,
-                message: `${formatBooking(amount, cardId, booking, bonus, milestones)} Saved in ${ctx.walletName}.`,
+                credit,
+                message: `${formatBooking(amount, cardText(catalog).shortName(cardId), booking, bonus, milestones, credit)} Saved in ${ctx.walletName}.`,
             }
             : {
                 recorded: false,
                 booking: null,
                 bonus: null,
                 milestones: [],
-                message: `Nothing to track: ${cardId} has no spending cap, open welcome bonus or spend milestone for this purchase, so the wallet wasn't changed.`,
+                credit: null,
+                message: `Nothing to track: ${cardText(catalog).shortName(cardId)} has no spending cap, open welcome bonus, spend milestone or enrolled merchant credit for this purchase, so the wallet wasn't changed.`,
             };
         return {
             content: [
@@ -183,7 +191,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) 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 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}`,
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
         annotations: {

package/dist/merchants/resolve.js

@@ -121,6 +121,14 @@ export function findMerchant(catalog, id) {
     return (catalog.merchants.overrides.find((m) => m.id === id) ??
         catalog.merchants.seed.find((m) => m.id === id));
 }
+// The ids a card rule can name to match this merchant: its own and, for a
+// brand, its parent's.
+export function merchantFamily(catalog, id) {
+    if (id === null)
+        return [];
+    const parent = findMerchant(catalog, id)?.brand_of;
+    return parent === undefined ? [id] : [id, parent];
+}
 export function resolveMerchantById(catalog, id, channel) {
     const override = catalog.merchants.overrides.find((m) => m.id === id);
     const found = findMerchant(catalog, id);

package/dist/schema/card.js

@@ -33,6 +33,16 @@ export const SharedCapSchema = CapSchema.extend({
     // aren't in the data yet, not that there's no bonus.
     rotating: z.literal(true).optional(),
 });
+// How a purchase is paid, for rates that depend on it: Apple Card's 2% with
+// Apple Pay, PayPal Cashback's 3% through PayPal checkout. `card` is the card
+// itself or its number, not a phone wallet or PayPal. Unknown unless the
+// person says, so a rule that requires one never applies by assumption.
+export const PaymentMethod = z.enum([
+    'card',
+    'apple-pay',
+    'google-pay',
+    'paypal',
+]);
 const hasAny = (m) => Object.values(m).some((v) => v === true || (v !== undefined && v.length > 0));
 // Kinds combine with AND, values within a kind with OR: `{ merchants:
 // [lyft], categories: [transit] }` is a Lyft purchase that codes as transit.
@@ -52,8 +62,9 @@ export const ExcludeSchema = z
     categories: z.array(CategoryId).optional(),
     merchants: z.array(KebabId).optional(),
     mccs: z.array(Mcc).optional(),
+    payment: z.array(PaymentMethod).optional(),
 })
-    .refine(hasAny, 'exclude needs categories, merchants or mccs');
+    .refine(hasAny, 'exclude needs categories, merchants, mccs or payment');
 export const RuleSchema = z
     .strictObject({
     id: KebabId,
@@ -71,6 +82,7 @@ export const RuleSchema = z
         .strictObject({
         membership: KebabId.optional(),
         activation: z.boolean().optional(),
+        payment: PaymentMethod.optional(),
     })
         .optional(),
     valid_from: IsoDate.optional(),
@@ -160,6 +172,26 @@ 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.
+export const CreditPeriod = z.enum([...CapPeriod.options, 'half_year']);
+export const CreditSchema = z.strictObject({
+    id: KebabId,
+    match: z
+        .strictObject({
+        merchants: z.array(KebabId).min(1).optional(),
+        categories: z.array(CategoryId).min(1).optional(),
+    })
+        .refine((m) => (m.merchants === undefined) !== (m.categories === undefined), 'a credit matches merchants or categories, not both'),
+    amount: z.number().positive(), // dollars of credit per period
+    period: CreditPeriod,
+    // The cardholder must enroll with the issuer before it pays.
+    enroll: z.literal(true).optional(),
+    note: z.string().optional(),
+});
 const HexColor = z.string().regex(/^#[0-9a-f]{6}$/);
 export const CardSchema = z
     .strictObject({
@@ -206,8 +238,10 @@ export const CardSchema = z
     rules: z.array(RuleSchema).default([]),
     milestones: z.array(MilestoneSchema).default([]),
     intro_rates: z.array(IntroRateSchema).default([]),
-    // A short quote from an issuer page for each rule (or `base_rate`). The
-    // weekly source check fails a rule whose quote disappears from its page.
+    credits: z.array(CreditSchema).default([]),
+    // A short quote from an issuer page for each rule (or `base_rate`, or a
+    // credit's id). The weekly source check fails a rule whose quote
+    // disappears from its page.
     evidence: z
         .array(z.strictObject({
         rule: z.string().min(1),

package/dist/schema/common.js

@@ -19,7 +19,7 @@ export const IsoDate = z.iso.date();
 // YAML reads `period: 2026` as a number, so accept both and normalize.
 export const PeriodKey = z.preprocess((v) => (typeof v === 'number' ? String(v) : v), z
     .string()
-    .regex(/^\d{4}(-Q[1-4]|-(0[1-9]|1[0-2]))?$/, 'expected a period like 2026, 2026-Q4 or 2026-10'));
+    .regex(/^\d{4}(-Q[1-4]|-H[12]|-(0[1-9]|1[0-2]))?$/, 'expected a period like 2026, 2026-Q4, 2026-H2 or 2026-10'));
 export const ValueRange = z
     .tuple([z.number().positive(), z.number().positive()])
     .refine(([low, high]) => low <= high, 'range must be [low, high]');

package/dist/schema/merchant.js

@@ -13,6 +13,9 @@ export const MerchantSchema = z.strictObject({
     aliases: z.array(z.string().min(1)).default([]),
     domains: z.array(z.string().min(1)).default([]),
     category: CategoryId,
+    // A brand of another merchant (Hampton Inn of Hilton): rules that name the
+    // parent's id also match the brand. One level only.
+    brand_of: KebabId.optional(),
     likely_mcc: Mcc.optional(),
     accepts: Accepts.optional(),
     in_store: ChannelOverride.optional(),
@@ -31,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/dist/schema/wallet.js

@@ -16,6 +16,10 @@ const CapUsage = z.strictObject({
     period: PeriodKey,
     spent: z.number().nonnegative(), // dollars
 });
+const CreditUsage = z.strictObject({
+    period: PeriodKey,
+    used: z.number().nonnegative(), // dollars of credit
+});
 export const WalletCardSchema = z.strictObject({
     id: KebabId,
     checkout_label: z
@@ -42,6 +46,10 @@ export const WalletCardSchema = z.strictObject({
     activated: z.array(KebabId).default([]),
     // Keyed by milestone id: every purchase on the card this period.
     milestone_usage: z.record(KebabId, CapUsage).optional(),
+    // Merchant credits (the card's `credits`) the cardholder has enrolled in,
+    // by credit id, and the dollars of each credit already received this period.
+    enrolled: z.array(KebabId).optional(),
+    credit_usage: z.record(KebabId, CreditUsage).optional(),
     // A welcome bonus in progress. Terms default to the card's published
     // offer; set spend, by, points or dollars when yours was different.
     bonus: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Which credit card earns the most at a merchant, from your cards or every card, and why",
   "keywords": [
     "credit cards",