earnrate 0.1.2 → 0.1.3

package/dist/mcp/server.js

@@ -3,20 +3,24 @@ import { z } from 'zod';
 import { MCP_SERVER_NAME } from "../brand.js";
 import { formatCardInfo, formatNotes } from "../cli/cards.js";
 import { formatRecommendation } from "../cli/format.js";
+import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../cli/explore.js";
 import { formatOffers } from "../cli/offers.js";
 import { walletProblems } from "../data/integrity.js";
 import { loadWallet } from "../data/load.js";
 import { withWalletLock, writeBonusSpent, writeCapBooking, } from "../data/wallet-write.js";
 import { addCard, removeCard, setMemberships, updateCard, } from "../data/wallet-setup.js";
 import { bonusStatus, countsTowardBonus } from "../engine/bonus.js";
+import { ALL_PERSONAL_CARDS, exploreCards } from "../engine/explore.js";
 import { compareOffers } from "../engine/offers.js";
+import { VALUATION_PROFILES } from "../engine/profiles.js";
 import { capBooking } from "../engine/record.js";
 import { recommend } from "../engine/recommend.js";
+import { resolveSpendLines, simulateAdditions, simulateCatalog, } from "../engine/simulate.js";
 import { knownMemberships, searchCards } from "../engine/setup.js";
 import { walletSummary } from "../engine/wallet-summary.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { IsoDate } from "../schema/common.js";
-import { CardSearchSchema, MerchantResolutionSchema, RecommendationSchema, OfferComparisonSchema, RecordResultSchema, WalletChangeSchema, WalletSummarySchema, } from "./schemas.js";
+import { CardSearchSchema, ExplorationSchema, MerchantResolutionSchema, SpendingSimulationSchema, RecommendationSchema, OfferComparisonSchema, RecordResultSchema, WalletChangeSchema, WalletSummarySchema, } from "./schemas.js";
 const Merchant = z
     .string()
     .min(1)
@@ -26,7 +30,7 @@ const ChannelInput = z
     .optional()
     .describe('How the purchase is made. Omit if unknown; the answer says what it assumed.');
 const DateInput = IsoDate.optional().describe('Purchase date, YYYY-MM-DD. Defaults to today.');
-const INSTRUCTIONS = `earnrate picks which of the user's credit cards earns the most for a purchase. Its wallet lists the cards they hold by product id, never card numbers; never ask for card numbers, expiry dates or security codes.
+const INSTRUCTIONS = `earnrate picks which of the user's credit cards earns the most for a purchase. best_cards_for and simulate_spending compare every card earnrate knows and need no wallet, for questions like "what's the best grocery card?" or "which cards fit my spending?". Its wallet lists the cards they hold by product id, never card numbers; never ask for card numbers, expiry dates or security codes.
 
 If a tool says there's no wallet yet, ask the user which cards they have, find each with search_cards, and add it with add_card. add_card and update_card reply with what a card still needs, such as category picks, memberships like Amazon Prime, or activated bonus categories. Ask the user about those and set them with update_card or set_memberships.`;
 const fail = (text) => ({
@@ -211,6 +215,153 @@ export function createEarnrateServer(deps) {
             structuredContent: comparison,
         };
     });
+    const CatalogCategory = z
+        .enum(ids)
+        .describe(`A spending category: ${catalog.categories.map((c) => `${c.id} (${c.name})`).join(', ')}.`);
+    const issuers = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
+    const membershipIds = knownMemberships(catalog);
+    const CatalogFilters = {
+        kind: z
+            .enum(['any', 'cash', 'points'])
+            .optional()
+            .describe('cash: cash back cards only. points: points and miles cards only.'),
+        noAnnualFee: z
+            .boolean()
+            .optional()
+            .describe('Only cards with no annual fee.'),
+        business: z
+            .boolean()
+            .optional()
+            .describe('Business cards instead of personal ones.'),
+        issuer: z.enum(issuers).optional().describe("Only this issuer's cards."),
+        memberships: z
+            .array(z.enum(membershipIds))
+            .optional()
+            .describe("Memberships the user has, such as amazon-prime. Rates that need one they don't have are listed separately."),
+        valuation: z
+            .enum(['flat', 'points-heavy'])
+            .optional()
+            .describe('flat (default): points at their cash-out value, about 1¢. points-heavy: Amex MR and Chase UR at 1.7¢, for people who transfer points to airlines and hotels.'),
+    };
+    const settings = (args) => ({
+        filters: {
+            ...ALL_PERSONAL_CARDS,
+            kind: args.kind ?? 'any',
+            noAnnualFee: args.noAnnualFee ?? false,
+            business: args.business ?? false,
+            issuer: args.issuer ?? null,
+        },
+        memberships: args.memberships ?? [],
+        valuations: args.valuation ? VALUATION_PROFILES[args.valuation] : {},
+    });
+    server.registerTool('best_cards_for', {
+        title: 'Best cards for a purchase',
+        description: 'Ranks every card earnrate knows, 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.',
+        inputSchema: z.object({
+            merchant: Merchant.optional(),
+            category: CatalogCategory.optional(),
+            amount: z
+                .number()
+                .positive()
+                .optional()
+                .describe('Purchase amount in US dollars, if known.'),
+            channel: ChannelInput,
+            ...CatalogFilters,
+        }),
+        outputSchema: ExplorationSchema,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, (args) => {
+        if (args.merchant === undefined && args.category === undefined)
+            return fail('Give a merchant or a category.');
+        const result = exploreCards(catalog, {
+            merchant: args.merchant ?? null,
+            category: args.merchant === undefined ? (args.category ?? null) : null,
+            amount: args.amount ?? null,
+            channel: args.channel ?? null,
+            date: deps.today(),
+        }, settings(args));
+        const trimmed = { ...result, ranked: result.ranked.slice(0, 10) };
+        return {
+            content: [{ type: 'text', text: formatExploration(trimmed, true) }],
+            structuredContent: trimmed,
+        };
+    });
+    server.registerTool('simulate_spending', {
+        title: 'Simulate a year of spending',
+        description: 'Spends the user\'s monthly amounts for a year across every card earnrate knows, and ranks single cards and two-card pairs by rewards minus annual fees. With compareToWallet, it starts from the user\'s wallet and ranks the cards that would add the most to it. Use it for "which card fits my spending?" or "is it worth adding a card?". Ask for rough monthly amounts if the user hasn\'t given them. It leaves out welcome bonuses.',
+        inputSchema: z.object({
+            spending: z
+                .array(z.object({
+                merchant: Merchant.optional(),
+                category: CatalogCategory.optional(),
+                monthly: z.number().positive().describe('US dollars a month.'),
+            }))
+                .min(1)
+                .describe('Monthly spending lines, each a category (grocery.supermarket, dining, gas, other) or a merchant (Amazon, Costco).'),
+            compareToWallet: z
+                .boolean()
+                .optional()
+                .describe("Rank the cards that would add the most to the user's wallet."),
+            ...CatalogFilters,
+        }),
+        outputSchema: SpendingSimulationSchema,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => {
+        if (args.spending.some((l) => l.merchant === undefined && l.category === undefined))
+            return fail('Each spending line needs a merchant or a category.');
+        const lines = resolveSpendLines(catalog, args.spending.map((l) => ({
+            merchant: l.merchant ?? null,
+            category: l.merchant === undefined ? (l.category ?? null) : null,
+            monthly: l.monthly,
+        })));
+        const unknown = lines.filter((l) => l.merchant.source === 'none');
+        if (unknown.length > 0)
+            return fail(`earnrate doesn't know ${unknown.map((l) => `"${l.merchant.input}"`).join(', ')}. Give a category for those lines instead.`);
+        const options = { ...settings(args), start: deps.today() };
+        if (args.compareToWallet) {
+            const w = await wallet();
+            if (typeof w === 'string')
+                return fail(w);
+            const valued = args.valuation
+                ? {
+                    ...w,
+                    valuations: {
+                        ...w.valuations,
+                        ...VALUATION_PROFILES[args.valuation],
+                    },
+                }
+                : w;
+            const result = simulateAdditions(catalog, valued, lines, options);
+            return {
+                content: [
+                    { type: 'text', text: formatAdditions(result, catalog, false) },
+                ],
+                structuredContent: {
+                    singles: [],
+                    pairs: [],
+                    current: result.current,
+                    additions: result.additions
+                        .slice(0, 10)
+                        .map(({ simulation: _, ...a }) => a),
+                },
+            };
+        }
+        const result = simulateCatalog(catalog, lines, options);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: formatCatalogSimulation(result, catalog, false),
+                },
+            ],
+            structuredContent: {
+                singles: result.singles.slice(0, 10),
+                pairs: result.pairs.slice(0, 5),
+                current: null,
+                additions: [],
+            },
+        };
+    });
     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 wallet file. 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.",
@@ -441,14 +592,13 @@ export function createEarnrateServer(deps) {
             openWorldHint: false,
         },
     }, ({ cardId }) => withWalletLock(deps.walletFile, async () => changed(await removeCard(deps.walletFile, catalog, cardId), `Removed ${cardName(cardId)} (${cardId}).`, false)));
-    const memberships = knownMemberships(catalog);
     server.registerTool('set_memberships', {
         title: 'Set memberships',
         description: "Sets the memberships that unlock some cards' rates, such as amazon-prime for Prime Visa's 5% or a Bank of America Preferred Rewards tier. Replaces the whole list, so include the ones to keep.",
         inputSchema: z.object({
             memberships: z
-                .array(z.enum(memberships))
-                .describe(`Every membership the user has. Known: ${memberships.join(', ')}.`),
+                .array(z.enum(membershipIds))
+                .describe(`Every membership the user has. Known: ${membershipIds.join(', ')}.`),
         }),
         outputSchema: WalletChangeSchema,
         annotations: {

package/dist/schema/card.js

@@ -133,6 +133,8 @@ export const CardSchema = z
     source_urls: z.array(z.url()).min(1),
     base_rate: z.number().nonnegative(),
     business: z.boolean().default(false),
+    // When the issuer stopped taking applications; cardholders keep earning.
+    applications_closed: IsoDate.optional(),
     annual_fee: z.number().nonnegative().optional(), // dollars
     // When the first year differs, usually a waived fee.
     first_year_fee: z.number().nonnegative().optional(),

package/dist/schema/category.js

@@ -6,6 +6,8 @@ export const CategorySchema = z.strictObject({
     // Typical MCCs, as hints for explanations and the LLM fallback. Matching is
     // by category, not by these.
     mccs: z.array(Mcc).default([]),
+    // Everyday words people search by ("groceries"), besides the name.
+    aliases: z.array(z.string().min(1)).default([]),
     note: z.string().optional(),
 });
 export const CategoriesFileSchema = z.array(CategorySchema).min(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Picks the best credit card from your wallet for a merchant, and explains why",
   "keywords": [
     "credit cards",
@@ -40,11 +40,13 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepack": "yarn build",
     "smoke:pack": "node scripts/smoke-pack.ts",
-    "site:deploy": "WRANGLER_SEND_METRICS=false wrangler deploy",
+    "site:build": "vite build site",
+    "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",
+    "typecheck": "tsc && tsc -p site",
     "lint": "eslint",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -64,6 +66,7 @@
     "eslint": "^10.13.0",
     "eslint-config-prettier": "^10.1.8",
     "playwright": "1.64.1",
+    "preact": "^10.29.8",
     "prettier": "^3.9.10",
     "typescript": "~6.0.3",
     "typescript-eslint": "^8.72.0",