earnrate 0.2.14 → 0.2.15

package/dist/mcp/inputs.js

@@ -80,15 +80,15 @@ const cardFields = {
     milestoneSpent: z
         .record(z.string(), z.number().nonnegative())
         .optional()
-        .describe('Dollars already spent on the card this year, for its spend milestones (bonuses after a yearly spending total, as search_cards lists them): milestone id → dollars, e.g. {"spend-15k": 9000}. Every purchase on the card counts, so give each milestone the same total. Ask; recorded purchases add to it from then on.'),
+        .describe('Dollars already spent on the card this year, for its spend bonuses (bonuses after a yearly spending total, as search_cards lists them): milestone id → dollars, e.g. {"spend-15k": 9000}. Every purchase on the card counts, so give each milestone the same total. Ask; recorded purchases add to it from then on.'),
     enrolled: z
         .array(z.string())
         .optional()
-        .describe('Merchant credit ids the user has enrolled in with the issuer (search_cards and list_wallet list each card\'s credits, e.g. "lululemon" on Amex Platinum). A credit that needs enrolling counts in answers only once it\'s here. Replaces the current list. Ask; never assume.'),
+        .describe('Statement credit ids the user has enrolled in with the issuer (search_cards and list_wallet list each card\'s credits, e.g. "lululemon" on Amex Platinum). A credit that needs enrolling counts in answers only once it\'s here. Replaces the current list. Ask; never assume.'),
     creditUsed: z
         .record(z.string(), z.number().nonnegative())
         .optional()
-        .describe('Dollars of a merchant credit already received this period: credit id → dollars, e.g. {"lululemon": 40}. Ask; recorded purchases add to it from then on.'),
+        .describe('Dollars of a statement credit already received this period: credit id → dollars, e.g. {"lululemon": 40}. Ask; recorded purchases add to it from then on.'),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),

package/dist/mcp/schemas.js

@@ -298,6 +298,7 @@ export const CardSearchSchema = z.object({
         network: CardNetwork,
         currency: z.string(),
         annualFee: z.number().nullable(),
+        firstYearFee: z.number().nullable(),
         foreignTransactionFee: z.number().nullable(),
         business: z.boolean(),
         onlyAt: z.array(z.string()).nullable(),

package/dist/mcp/server.js

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

package/dist/mcp/tools/account.js

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

package/dist/mcp/tools/answers.js

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

package/dist/mcp/tools/wallet.js

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

package/dist/schema/card.js

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

package/package.json

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