earnrate 0.2.8 → 0.2.9

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,7 @@ const RankedCardSchema = z.object({
     centsPerUnit: z.number(),
     effectiveReturnPct: z.number(),
     earned: z.number().nullable(),
+    foreignFee: z.number().nullable(),
     capped: z.boolean(),
     reasoning: z.array(z.string()),
     warnings: z.array(z.string()),
@@ -88,7 +90,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 +137,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 +190,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 +237,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 +259,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 +348,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/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.9",
   "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"
   }
 }