earnrate 0.2.8 → 0.2.10

package/dist/format/wallet.js

@@ -1,4 +1,4 @@
-import { money, NETWORK_NAMES, shortDate } from "../engine/text.js";
+import { CAP_PERIODS, money, NETWORK_NAMES, shortDate } from "../engine/text.js";
 // "To do now", above the card details; nothing when all's done.
 export function formatChecklist(items) {
     return items.length === 0
@@ -34,8 +34,11 @@ export function formatWalletSummary(summary) {
         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 on ${cap.label}: ${money(cap.spent)} of ${money(cap.amount)} used for ${cap.currentPeriod ?? ''} (cap key ${cap.key}).`);
+            lines.push(cap.remaining === null
+                ? `  Cap on ${cap.label}: ${money(cap.amount)} ${CAP_PERIODS[cap.period]}; give the card's anniversary to track it (cap key ${cap.key}).`
+                : `  Cap on ${cap.label}: ${money(cap.spent)} of ${money(cap.amount)} used ${cap.period === 'cardmember_year' ? 'this cardmember year' : `for ${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}`);
         if (c.anniversary !== null)
             lines.push(`  Account anniversary: ${c.anniversary}.`);
         const b = c.bonus;
@@ -53,7 +56,7 @@ export function formatWalletSummary(summary) {
         : "Point values: earnrate's defaults.";
     return [...cards, memberships, values].join('\n');
 }
-export function formatBooking(amount, cardId, cap, bonus) {
+export function formatBooking(amount, cardId, cap, bonus, milestones = []) {
     const messages = [];
     if (cap) {
         const left = Math.max(0, cap.capAmount - cap.after);
@@ -65,5 +68,20 @@ export function formatBooking(amount, cardId, cap, bonus) {
             ? `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'}.`);
     }
+    // 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);
+        messages.push([
+            `Spend on ${cardId} this year: ${money(first.after)}.`,
+            ...reached.map((m) => `That reaches its ${money(m.spend)} spend bonus.`),
+            ...(next
+                ? [
+                    `${money(next.spend - next.after)} to go for the ${money(next.spend)} spend bonus.`,
+                ]
+                : []),
+        ].join(' '));
+    }
     return messages.join(' ');
 }

package/dist/import/analyze.js

@@ -1,6 +1,7 @@
 import { bonusStatus, countsTowardBonus } from "../engine/bonus.js";
 import { HALF_CENT } from "../engine/compare.js";
 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";
@@ -41,8 +42,14 @@ function capPeriodKey(catalog, wallet, booking, date) {
 // up partway through the year is accounted for on both sides.
 export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorded = () => false) {
     const sorted = [...entries].sort((a, b) => a.line.date.localeCompare(b.line.date));
-    let actual = wallet;
-    let simulated = wallet;
+    // The earned-versus-best replay leaves spend milestones out: they pay once
+    // on the card's total, whichever card is best for each purchase.
+    const replay = {
+        ...wallet,
+        cards: wallet.cards.map(({ milestone_usage: _usage, ...c }) => c),
+    };
+    let actual = replay;
+    let simulated = replay;
     let current = wallet;
     const byCard = new Map();
     const missed = new Map();
@@ -69,8 +76,40 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
                 entries: [],
             });
     }
+    const milestones = [];
+    for (const held of wallet.cards) {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        if (!card)
+            continue;
+        for (const p of milestoneProgress(card, held, today))
+            if (p.period !== null)
+                milestones.push({
+                    cardId: held.id,
+                    milestoneId: p.milestone.id,
+                    period: p.period,
+                    spend: p.milestone.spend,
+                    before: p.spent,
+                    after: p.spent,
+                    entries: [],
+                });
+    }
     for (const entry of sorted) {
         const { cardId, line } = entry;
+        if (!alreadyRecorded(entry, 'milestone')) {
+            const held = wallet.cards.find((c) => c.id === cardId);
+            for (const m of milestones) {
+                if (m.cardId !== cardId)
+                    continue;
+                const card = catalog.cards.find((c) => c.id === cardId);
+                const milestone = card?.milestones.find((x) => x.id === m.milestoneId);
+                if (!milestone ||
+                    periodKey(milestone.period, line.date, held?.anniversary ?? null) !==
+                        m.period)
+                    continue;
+                m.after = roundCents(Math.max(0, m.after + line.amount));
+                m.entries.push(entry);
+            }
+        }
         const progress = bonuses.get(cardId);
         if (progress &&
             countsTowardBonus(progress, line.date) &&
@@ -202,5 +241,6 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
         outsideCurrentPeriod,
         alreadyImported,
         bonuses: [...bonuses.values()].filter((b) => b.entries.length > 0),
+        milestones: milestones.filter((m) => m.entries.length > 0),
     };
 }

package/dist/mcp/inputs.js

@@ -3,6 +3,7 @@ import { ALL_PERSONAL_CARDS } from "../engine/explore.js";
 import { profileText, VALUATION_PROFILES } from "../engine/profiles.js";
 import { knownMemberships } from "../engine/setup.js";
 import { IsoDate } from "../schema/common.js";
+import { COUNTRY_CODE } from "../schema/common.js";
 export const Merchant = z
     .string()
     .min(1)
@@ -12,6 +13,11 @@ export const ChannelInput = z
     .optional()
     .describe('How the purchase is made. Omit if unknown; the answer says what it assumed.');
 export const DateInput = IsoDate.optional().describe('Purchase date, YYYY-MM-DD. Defaults to today.');
+export const CountryInput = z
+    .string()
+    .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 CardId = z
     .string()
     .min(1)
@@ -66,6 +72,10 @@ const cardFields = {
         .record(z.string(), z.number().nonnegative())
         .optional()
         .describe('Dollars already spent this period on a capped bonus, for a card the user starts tracking partway through: cap key (as list_wallet shows it) → dollars, e.g. {"five-percent-quarterly": 400}. Ask; recorded purchases add to it from then on.'),
+    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.'),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),

package/dist/mcp/schemas.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { CapPeriod } from "../schema/card.js";
+import { CapPeriod, 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
 // result against these, so a drift between the two fails loudly in tests.
@@ -38,6 +39,10 @@ const RankedCardSchema = z.object({
     centsPerUnit: z.number(),
     effectiveReturnPct: z.number(),
     earned: z.number().nullable(),
+    foreignFee: z.number().nullable(),
+    milestoneBonus: z
+        .object({ points: z.number(), dollars: z.number() })
+        .nullable(),
     capped: z.boolean(),
     reasoning: z.array(z.string()),
     warnings: z.array(z.string()),
@@ -88,7 +93,14 @@ export const WalletSummarySchema = z.object({
     started: z.string().nullable(),
     checklist: z
         .array(z.object({
-        kind: z.enum(['activate', 'pick', 'cap', 'bonus', 'rotation']),
+        kind: z.enum([
+            'activate',
+            'pick',
+            'cap',
+            'bonus',
+            'milestone',
+            'rotation',
+        ]),
         cardId: z.string(),
         text: z.string(),
         due: z.string().nullable(),
@@ -128,9 +140,22 @@ export const WalletSummarySchema = z.object({
             amount: z.number(),
             period: CapPeriod,
             currentPeriod: z.string().nullable(),
+            until: z.string().nullable(),
             spent: z.number(),
             remaining: z.number().nullable(),
         })),
+        milestones: z.array(z.object({
+            id: z.string(),
+            spend: z.number(),
+            period: MilestonePeriod,
+            currentPeriod: z.string().nullable(),
+            until: z.string().nullable(),
+            spent: z.number(),
+            tracked: z.boolean(),
+            points: z.number().nullable(),
+            rewards: z.array(z.string()),
+            text: z.string(),
+        })),
         chosen: z
             .object({
             period: z.string(),
@@ -168,6 +193,14 @@ export const RecordResultSchema = z.object({
         deadline: z.string().nullable(),
     })
         .nullable(),
+    milestones: z.array(z.object({
+        cardId: z.string(),
+        milestoneId: z.string(),
+        period: z.string(),
+        spend: z.number(),
+        before: z.number(),
+        after: z.number(),
+    })),
     message: z.string(),
 });
 export const OfferComparisonSchema = z.object({
@@ -207,6 +240,7 @@ export const CardSearchSchema = z.object({
         network: CardNetwork,
         currency: z.string(),
         annualFee: z.number().nullable(),
+        foreignTransactionFee: z.number().nullable(),
         business: z.boolean(),
         onlyAt: z.array(z.string()).nullable(),
         held: z.boolean(),
@@ -228,6 +262,14 @@ export const CardSearchSchema = z.object({
             .nullable(),
         activation: z.array(z.string()),
         needsAnniversary: z.boolean(),
+        milestones: z.array(z.object({
+            id: z.string(),
+            spend: z.number(),
+            period: MilestonePeriod,
+            points: z.number().nullable(),
+            rewards: z.array(z.string()),
+            text: z.string(),
+        })),
     })),
 });
 export const WalletChangeSchema = z.object({
@@ -309,6 +351,12 @@ const SimulationSchema = z.object({
         returnPct: z.number(),
         cards: z.array(z.string()),
     })),
+    milestones: z.array(z.object({
+        cardId: z.string(),
+        milestoneId: z.string(),
+        points: z.number().nullable(),
+        value: z.number(),
+    })),
     notes: z.array(z.string()),
 });
 export const SpendingSimulationSchema = z.object({

package/dist/mcp/server.js

@@ -45,7 +45,23 @@ The wallet lists cards by product id, never card numbers; never ask for card num
 
 ${WHICH_WALLET[savedWallets]} The earnrate extension on the user's computer and the hosted earnrate connector keep separate wallets with the same tools. If both are connected, say which wallet an answer comes from, and ask the user which one to use before saving or recording anything.`;
 export function createEarnrateServer(deps) {
-    const server = new McpServer({ name: MCP_SERVER_NAME, version: deps.version }, { instructions: instructions(deps.savedWallets) });
+    const server = new McpServer({
+        name: MCP_SERVER_NAME,
+        version: deps.version,
+        websiteUrl: 'https://earnrate.dev',
+        icons: [
+            {
+                src: 'https://earnrate.dev/icon-192.png',
+                mimeType: 'image/png',
+                sizes: ['192x192'],
+            },
+            {
+                src: 'https://earnrate.dev/favicon.svg',
+                mimeType: 'image/svg+xml',
+                sizes: ['any'],
+            },
+        ],
+    }, { instructions: instructions(deps.savedWallets) });
     const ctx = makeContext(deps);
     const inputs = makeInputs(deps.catalog);
     registerAnswerTools(server, deps, ctx, inputs);

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 and bonus progress. Never card numbers.',
+        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.',
         inputSchema: z.object({}),
         outputSchema: z.object({ yaml: z.string() }),
         annotations: {

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, DateInput, Merchant, settings, } from "../inputs.js";
+import { ChannelInput, CountryInput, 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 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. 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. Never needs or returns card numbers.",
         inputSchema: z.object({
             merchant: Merchant,
             amount: z
@@ -44,6 +44,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 .describe('Purchase amount in US dollars. Improves cap math.'),
             channel: ChannelInput,
             date: DateInput,
+            country: CountryInput,
             category: CategoryInput,
             cards: NamedCards,
             memberships: NamedMemberships,
@@ -55,7 +56,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             readOnlyHint: true,
             openWorldHint: deps.llm !== null,
         },
-    }, async ({ merchant, amount, channel, date, category, cards, memberships, valuation, }) => {
+    }, async ({ merchant, amount, channel, date, country, category, cards, memberships, valuation, }) => {
         const held = await ctx.cardsFor(cards, memberships);
         if (typeof held === 'string')
             return fail(held);
@@ -67,7 +68,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             amount: amount ?? null,
             channel: channel ?? null,
             date: date ?? deps.today(),
-            country: 'US',
+            country: (country ?? 'US').toUpperCase(),
         };
         const resolved = await ctx.resolve(merchant, purchase.channel, category ?? null);
         const retry = resolved.merchant.source === 'none'
@@ -80,6 +81,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 amount: purchase.amount,
                 channel: purchase.channel,
                 date: purchase.date,
+                country: purchase.country,
             }, 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);
@@ -210,6 +212,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 .optional()
                 .describe('Purchase amount in US dollars, if known.'),
             channel: ChannelInput,
+            country: CountryInput,
             ...CatalogFilters,
         }),
         outputSchema: ExplorationSchema,
@@ -228,6 +231,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             amount: args.amount ?? null,
             channel,
             date: deps.today(),
+            country: (args.country ?? 'US').toUpperCase(),
         }, settings(args, await ctx.saved()), args.merchant === undefined
             ? undefined
             : withCallerCategory(resolvePlace(catalog, args.merchant, channel), args.category ?? null));

package/dist/mcp/tools/wallet.js

@@ -4,6 +4,7 @@ import { choiceName, currencyLabel, listed, money, shortDate, words, } from "../
 import { membershipName } from "../../engine/memberships.js";
 import { profileText, VALUATION_PROFILES } from "../../engine/profiles.js";
 import { optionName } from "../../engine/rule-text.js";
+import { currencyChanges } from "../../engine/wallet-change.js";
 import { walletSummary } from "../../engine/wallet-summary.js";
 import { checklist } from "../../engine/checklist.js";
 import { cardText } from "../../format/card-text.js";
@@ -44,6 +45,8 @@ function changes(catalog, args) {
             : `activated: ${args.activated.join(', ')}`);
     for (const [key, spent] of Object.entries(args.capSpent ?? {}))
         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 year`);
     if (args.bonus === null)
         out.push('welcome bonus no longer tracked');
     else if (args.bonus !== undefined)
@@ -55,7 +58,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); 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, 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); 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}`,
         outputSchema: WalletSummarySchema,
         annotations: {
             title: 'List wallet',
@@ -88,7 +91,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 and welcome-bonus progress 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 and no open welcome bonus 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 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}`,
         inputSchema: z.object({
             cardId: z
                 .string()
@@ -127,19 +130,21 @@ 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 } = result;
-        const output = booking || bonus
+        const { cap: booking, bonus, milestones } = result;
+        const output = booking || bonus || milestones.length > 0
             ? {
                 recorded: true,
                 booking,
                 bonus,
-                message: `${formatBooking(amount, cardId, booking, bonus)} Saved in ${ctx.walletName}.`,
+                milestones,
+                message: `${formatBooking(amount, cardId, booking, bonus, milestones)} Saved in ${ctx.walletName}.`,
             }
             : {
                 recorded: false,
                 booking: null,
                 bonus: null,
-                message: `Nothing to track: ${cardId} has no spending cap or open welcome bonus for this purchase, so the wallet wasn't changed.`,
+                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.`,
             };
         return {
             content: [
@@ -173,7 +178,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, activated categories, cap spending so far (capSpent) 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, 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}`,
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
         annotations: {
@@ -192,7 +197,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('remove_card', {
         title: 'Remove a card',
-        description: `Removes a card from the wallet, with its tracked cap usage and bonus progress. Memberships and point values stay, even when the last card goes. Only when the user says they no longer have it or don't want it considered. ${ctx.walletUse}`,
+        description: `Removes a card from the wallet, with its tracked cap usage, bonus progress and yearly spending. Memberships and point values stay, even when the last card goes. Only when the user says they no longer have it or don't want it considered. ${ctx.walletUse}`,
         inputSchema: z.object({ cardId: CardId }),
         outputSchema: WalletChangeSchema,
         annotations: {
@@ -226,7 +231,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('set_point_values', {
         title: 'Set point values',
-        description: `Saves what the user's points are worth to them, in cents per point, in their saved wallet; every answer then compares cards at those values unless a valuation profile is asked for. No saved cards are needed. Use it when the user says what their points are worth ("I value Chase points at 1.5¢") or that they transfer points to airlines and hotels (profile points-heavy). Values change only the currencies given; null goes back to earnrate's default. Currencies: ${catalog.currencies.map((c) => c.id).join(', ')}. ${ctx.walletUse}`,
+        description: `Saves what the user's points are worth to them, in cents per point, in their saved wallet; every answer then compares cards at those values unless a valuation profile is asked for. No saved cards are needed. Use it when the user says what their points are worth ("I value Chase points at 1.5¢") or that they transfer points to airlines and hotels (profile points-heavy). Values change only the currencies given; null goes back to earnrate's default. Currencies by id: ${catalog.currencies.map((c) => `${c.id} (${c.name})`).join(', ')}. ${ctx.walletUse}`,
         inputSchema: z.object({
             values: z
                 .record(z.string(), z.number().nullable())
@@ -245,9 +250,12 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             idempotentHint: true,
         },
     }, async ({ values, profile }) => {
+        const given = currencyChanges(catalog, values ?? {});
+        if (!given.ok)
+            return fail(given.error);
         const changes = {
             ...(profile ? VALUATION_PROFILES[profile] : {}),
-            ...(values ?? {}),
+            ...given.changes,
         };
         if (Object.keys(changes).length === 0)
             return fail('Give values (cents per point by currency) or a profile.');

package/dist/schema/card.js

@@ -12,6 +12,20 @@ export const CapSchema = z.strictObject({
     period: CapPeriod,
     then_rate: z.number().nonnegative(),
 });
+// A bonus paid once a period after a spending total, rather than per dollar
+// ("10,000 bonus points after you spend $15,000 on purchases each calendar
+// year"). Every purchase on the card counts. Only `points` is valued;
+// `rewards` (status, night credits, free nights) is shown, never valued.
+export const MilestoneSchema = z
+    .strictObject({
+    id: KebabId,
+    spend: z.number().positive(), // dollars of purchases in the period
+    period: z.enum(['calendar_year', 'cardmember_year']),
+    points: z.number().positive().optional(), // in the card's currency
+    rewards: z.array(z.string().min(1)).min(1).optional(),
+    note: z.string().optional(),
+})
+    .refine((m) => m.points !== undefined || m.rewards !== undefined, 'a milestone needs points, rewards or both');
 export const SharedCapSchema = CapSchema.extend({
     id: KebabId,
     // Rotating categories (Freedom Flex): every rule on this cap covers one
@@ -47,7 +61,10 @@ export const RuleSchema = z
     exclude: ExcludeSchema.optional(),
     rate: z.number().nonnegative(), // currency units per dollar
     channel: z.enum(['any', 'online', 'in_store']).default('any'),
-    geography: z.enum(['us_only', 'worldwide']).default('worldwide'),
+    // A purchase is foreign when its country isn't the U.S.
+    geography: z
+        .enum(['us_only', 'foreign_only', 'worldwide'])
+        .default('worldwide'),
     // Inline cap, or the id of a shared cap in the card's `caps`.
     cap: z.union([CapSchema, KebabId]).optional(),
     requires: z
@@ -148,6 +165,9 @@ export const CardSchema = z
     annual_fee: z.number().nonnegative().optional(), // dollars
     // When the first year differs, usually a waived fee.
     first_year_fee: z.number().nonnegative().optional(),
+    // Percent of each purchase outside the U.S.; 0 when there's none. null
+    // only when no issuer page states it, with a todo saying so.
+    foreign_transaction_fee: z.number().nonnegative().nullable(),
     welcome_offer: WelcomeOfferSchema.optional(),
     // A paid membership (data/memberships.yaml) the card can't be had
     // without, Costco's for Costco Anywhere. Its fee counts like an annual
@@ -162,6 +182,7 @@ export const CardSchema = z
     caps: z.array(SharedCapSchema).default([]),
     choices: z.array(ChoiceSchema).default([]),
     rules: z.array(RuleSchema).default([]),
+    milestones: z.array(MilestoneSchema).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.
     evidence: z

package/dist/schema/common.js

@@ -23,3 +23,7 @@ export const PeriodKey = z.preprocess((v) => (typeof v === 'number' ? String(v)
 export const ValueRange = z
     .tuple([z.number().positive(), z.number().positive()])
     .refine(([low, high]) => low <= high, 'range must be [low, high]');
+// A two-letter country code, like US or FR. Only the U.S. versus everywhere
+// else matters to the engine.
+export const COUNTRY_CODE = /^[A-Za-z]{2}$/;
+export const countryProblem = (code) => `"${code}" isn't a country code. Use two letters, like US or FR.`;

package/dist/schema/wallet.js

@@ -37,6 +37,8 @@ export const WalletCardSchema = z.strictObject({
     })
         .optional(),
     activated: z.array(KebabId).default([]),
+    // Keyed by milestone id: every purchase on the card this period.
+    milestone_usage: z.record(KebabId, CapUsage).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.8",
+  "version": "0.2.10",
   "description": "Which credit card earns the most at a merchant, from your cards or every card, and why",
   "keywords": [
     "credit cards",
@@ -46,13 +46,15 @@
     "remote:build": "node scripts/build-remote.ts",
     "remote:check": "yarn remote:build && WRANGLER_SEND_METRICS=false wrangler deploy --config remote/wrangler.jsonc --dry-run --outdir dist",
     "remote:deploy": "yarn remote:build && WRANGLER_SEND_METRICS=false wrangler deploy --config remote/wrangler.jsonc",
+    "monitor:check": "WRANGLER_SEND_METRICS=false wrangler deploy --config monitor/wrangler.jsonc --dry-run --outdir dist",
+    "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:deploy": "yarn site:build && WRANGLER_SEND_METRICS=false wrangler deploy",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage --coverage.include=src/**",
-    "typecheck": "tsc && tsc -p site && tsc -p remote",
+    "typecheck": "tsc && tsc -p site && tsc -p remote && tsc -p monitor",
     "lint": "eslint",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -81,6 +83,6 @@
     "typescript-eslint": "^8.72.0",
     "vite": "^8.3.5",
     "vitest": "^5.0.5",
-    "wrangler": "4.149.0"
+    "wrangler": "4.156.2"
   }
 }