earnrate 0.2.15 → 0.2.16

package/README.md

@@ -315,7 +315,7 @@ earnrate needs no account. The local version has no telemetry; the hosted server
 - **What it stores locally:** your wallet, a YAML file on your computer (`~/.earnrate/wallet.yaml` unless you set `EARNRATE_WALLET`). It lists cards by product ID, like `amex-gold`, plus your category picks, activations and how much you've spent toward caps. earnrate never asks for or stores card numbers, expiry dates, security codes or bank logins. When you ask about a store earnrate doesn't recognize, its name goes in `~/.earnrate/missed-merchants.json` (`earnrate missed` lists them; `EARNRATE_MISSED_MERCHANTS=off` keeps no list).
 - **What the local version sends:** nothing, by default. The optional merchant lookup (off unless you turn it on with your own Anthropic API key) sends only the name of a store earnrate doesn't recognize to Anthropic's API, and saves the answer in `~/.earnrate/merchant-cache.json`.
 - **AI assistants:** when you use earnrate through Claude or another assistant, that assistant's provider sees the conversation, including earnrate's answers, under its own privacy policy.
-- **earnrate.dev:** everything you enter on the site stays in your browser, except when you add the cheat sheet to Apple Wallet: then pass.earnrate.dev receives what the pass needs (card IDs, picks, activations, checkout names, memberships and the date) and keeps none of it. The site counts which of its parts get used, by name only, and counts visits with Cloudflare Web Analytics, without cookies.
+- **earnrate.dev:** everything you enter on the site stays in your browser, except when you add the cheat sheet to Apple Wallet: then pass.earnrate.dev receives what the pass needs (card IDs, picks, activations, checkout names, memberships and the date) and keeps none of it. If you turn on syncing with Claude, the wallet (cards, picks, activations, memberships, point values, cap and spending totals, credits used, opening dates) goes to mcp.earnrate.dev and is stored encrypted, like the connector's; a purchase you record is sent so its totals can be updated, and only the totals are kept. Searches, stores and amounts you ask about still never leave the browser. The sign-in stays in a cookie the page's scripts can't read. The site counts which of its parts get used, by name only, and counts visits with Cloudflare Web Analytics, without cookies.
 - **Retention:** locally, your data lives only in files you control, for as long as you keep them. Delete the wallet file, or clear the site's data in your browser, to remove it. A saved wallet on mcp.earnrate.dev lasts until you delete it or leave it unused for 13 months (a week, if it's never used); the record that an app is connected goes after 90 days unused.
 - **Terms:** [earnrate.dev/terms](https://earnrate.dev/terms).
 - **Contact:** [hello@earnrate.dev](mailto:hello@earnrate.dev).

package/dist/cli/args.js

@@ -95,6 +95,8 @@ export function parseCliArgs(argv) {
                 llm: { type: 'boolean' },
                 cards: { type: 'string' },
                 member: { type: 'string', multiple: true },
+                enrolled: { type: 'string', multiple: true },
+                opened: { type: 'string', multiple: true },
                 help: { type: 'boolean', short: 'h' },
             },
         });
@@ -129,6 +131,25 @@ export function parseCliArgs(argv) {
     const paying = paymentOf(values.paying);
     if ('problem' in paying)
         return { kind: 'error', message: paying.problem };
+    const cards = cardList(values.cards);
+    const perCard = (flag, example) => {
+        const out = {};
+        for (const pair of values[flag] ?? []) {
+            const [id = '', value = ''] = pair.split('=');
+            if (id.trim() === '' || value.trim() === '')
+                return `--${flag} takes <card>=<${flag === 'opened' ? 'date' : 'credits'}>, like ${example}.`;
+            if (!cards?.includes(id.trim()))
+                return `--${flag} is for a card named with --cards; ${id.trim()} isn't one.`;
+            out[id.trim()] = value.trim();
+        }
+        return out;
+    };
+    const enrolled = perCard('enrolled', 'amex-platinum=lululemon');
+    if (typeof enrolled === 'string')
+        return { kind: 'error', message: enrolled };
+    const opened = perCard('opened', 'discover-it-cash-back=2026-03-04');
+    if (typeof opened === 'string')
+        return { kind: 'error', message: opened };
     return {
         kind: 'run',
         options: {
@@ -143,8 +164,16 @@ export function parseCliArgs(argv) {
             all: values.all ?? false,
             category: values.category ?? null,
             llm: values.llm ?? null,
-            cards: cardList(values.cards),
+            cards,
             members: values.member ?? [],
+            enrolled: Object.fromEntries(Object.entries(enrolled).map(([id, list]) => [
+                id,
+                list
+                    .split(',')
+                    .map((c) => c.trim())
+                    .filter(Boolean),
+            ])),
+            opened,
         },
     };
 }

package/dist/cli/run.js

@@ -70,6 +70,11 @@ Options:
   ${PAYING_HELP}
   --cards <ids>          Answer for these cards instead of your wallet, comma
                          separated: --cards amex-gold,chase-prime-visa.
+  --enrolled <card>=<credits>
+                         For a named card, statement credits you've enrolled
+                         in: --enrolled amex-platinum=lululemon. Repeat per card.
+  --opened <card>=<date> For a named card, the day it opened (YYYY-MM-DD), for
+                         a first-year rate. Repeat per card.
   --member <name>        A membership you have, in place of the saved ones.
   --category <id>        For a merchant earnrate doesn't know: its category,
                          e.g. grocery.supermarket. Ignored for known merchants.
@@ -106,7 +111,11 @@ export async function cardsToUse(catalog, file, io, named) {
     if (named.cards !== null) {
         const saved = await savedSettings(io);
         const wallet = walletFromCards(catalog, {
-            cards: named.cards.map((id) => ({ id })),
+            cards: named.cards.map((id) => ({
+                id,
+                ...(named.enrolled?.[id] ? { enrolled: named.enrolled[id] } : {}),
+                ...(named.opened?.[id] ? { opened: named.opened[id] } : {}),
+            })),
             memberships: named.members.length > 0 ? named.members : saved.memberships,
         }, io.today);
         if (typeof wallet === 'string') {

package/dist/engine/cheat-sheet.js

@@ -86,7 +86,7 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
         ];
         return [
             `Working on ${possessive(name)} welcome bonus: ${money(status.remaining ?? 0)} more by ${shortDate(status.deadline ?? date)}. ${where.length > 0
-                ? `It ${where.join(' and ')}, so those are the places to use it.`
+                ? `It ${where.join(' and ')}, so ${matches.length + near.length === 1 ? "that's the place" : 'those are the places'} to use it.`
                 : 'It trails the listed cards everywhere, so use it on everyday spending only as needed to reach the bonus.'}`,
         ];
     });

package/dist/engine/checklist.js

@@ -24,7 +24,7 @@ shortName) {
             items.push({
                 kind: 'activate',
                 cardId: card.id,
-                text: `Activate ${possessive(name)} bonus ${a.preposition} ${a.what}${a.activateBy === null ? '' : ` by ${shortDate(a.activateBy)}`}${starts}.`,
+                text: `Activate ${possessive(name)} bonus ${a.where}${a.activateBy === null ? '' : ` by ${shortDate(a.activateBy)}`}${starts}.`,
                 due: a.activateBy ?? (a.from !== null && a.from > today ? a.from : a.to),
             });
         }

package/dist/engine/explore.js

@@ -223,6 +223,10 @@ export function exploreCards(catalog, query, options, resolved) {
                 ...membershipNeeded(catalog, card, members),
             ],
             evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
+            needsMembership: card.requires_membership !== undefined &&
+                !members.has(card.requires_membership)
+                ? card.requires_membership
+                : null,
             withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
         });
     }
@@ -303,7 +307,7 @@ function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid
 function exploreWarnings(catalog, merchant) {
     const warnings = [];
     if (merchant.source === 'none') {
-        warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. Try a category instead.`);
+        warnings.push(`earnrate doesn't know "${merchant.input}" yet, so only base rates apply. Try a category, or the name of a larger chain.`);
     }
     if (merchant.ambiguity) {
         const alternatives = merchant.ambiguity.mayCodeAs.map((c) => categoryPhrase(catalog, c));

package/dist/engine/memberships.js

@@ -50,7 +50,7 @@ export function membershipCosts(catalog, cards, paid) {
 export function membershipText(catalog, id) {
     const m = membership(catalog, id);
     const name = withArticle(m?.name ?? words(id));
-    return m?.annual_fee === undefined
+    return m?.annual_fee === undefined || m.annual_fee === 0
         ? name
         : `${name} (${money(m.annual_fee)} a year)`;
 }

package/dist/engine/wallet-summary.js

@@ -68,23 +68,13 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
             pending ? ', once activated' : '',
             payment === undefined ? '' : ` ${PAYMENT_PHRASES[payment]}`,
         ].join('|');
-        const line = lines.get(key) ?? { at: [], on: [] };
-        const whats = line[rulePreposition(catalog, [r])];
-        for (const part of ruleParts(catalog, r, card))
-            if (!whats.includes(part))
-                whats.push(part);
-        lines.set(key, line);
+        lines.set(key, [...(lines.get(key) ?? []), r]);
     }
     return [
-        ...[...lines].map(([key, { at, on }]) => {
+        ...[...lines].map(([key, rules]) => {
             const [head = '', limit = '', activate = '', paid = ''] = key.split('|');
             const after = `${limit}${activate}`;
-            // "at gas stations and on transit" when one line mixes the two.
-            const where = [
-                ...(at.length > 0 ? [`at ${listed(at)}`] : []),
-                ...(on.length > 0 ? [`on ${listed(on)}`] : []),
-            ].join(at.length > 1 ? ', and ' : ' and ');
-            return `${head} ${where}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
+            return `${head} ${wherePhrase(catalog, card, rules)}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
         }),
         ...(shown.some((r) => r.match.any &&
             r.geography !== 'foreign_only' &&
@@ -96,6 +86,22 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
 }
 // Bonuses current or starting soon that the card hasn't activated, one per
 // activation group (one activation covers a quarter's categories).
+// "at gas stations and restaurants, and on transit": each rule's parts after
+// its own preposition, the "at" ones first.
+export function wherePhrase(catalog, card, rules) {
+    const parts = { at: [], on: [] };
+    for (const r of rules) {
+        const list = parts[rulePreposition(catalog, [r])];
+        for (const part of ruleParts(catalog, r, card))
+            if (!list.includes(part))
+                list.push(part);
+    }
+    const { at, on } = parts;
+    return [
+        ...(at.length > 0 ? [`at ${listed(at)}`] : []),
+        ...(on.length > 0 ? [`on ${listed(on)}`] : []),
+    ].join(at.length > 1 ? ', and ' : ' and ');
+}
 export function activationsDue(catalog, card, held, today) {
     const seen = new Set();
     const out = [];
@@ -111,7 +117,7 @@ export function activationsDue(catalog, card, held, today) {
             what: listed([
                 ...new Set(rules.flatMap((r) => ruleParts(catalog, r, card))),
             ]),
-            preposition: rulePreposition(catalog, rules),
+            where: wherePhrase(catalog, card, rules),
             from: first?.valid_from ?? null,
             to: first?.valid_to ?? null,
             activateBy: first?.activate_by ?? null,

package/dist/format/card-text.js

@@ -15,9 +15,11 @@ export function cardText(catalog) {
             .replace(/ (Visa Signature |Visa Infinite )?(Credit )?(?<!^Apple )Card$/, '')
             .replace(/ Card by /, ' by '));
     }
-    function feeLabel(id) {
+    // `membership: false` leaves out a membership the card needs, for lists
+    // whose own conditions say it only when it applies.
+    function feeLabel(id, { membership = true } = {}) {
         const card = cards.get(id);
-        const m = card?.requires_membership;
+        const m = membership ? card?.requires_membership : undefined;
         const needs = m === undefined ? '' : `; needs ${membershipText(catalog, m)}`;
         const fee = card?.annual_fee;
         if (fee === undefined)

package/dist/mcp/inputs.js

@@ -49,6 +49,14 @@ const NamedCard = z.object({
         .array(z.string())
         .optional()
         .describe('Bonuses the user has activated with the issuer, as rule ids from search_cards.'),
+    enrolled: z
+        .array(z.string())
+        .optional()
+        .describe("Statement credits the user has enrolled in with the issuer, as credit ids from search_cards. A credit that needs enrolling counts only when it's here. Ask; never assume."),
+    opened: z
+        .string()
+        .optional()
+        .describe('The day the account opened (YYYY-MM-DD), for a card with a first-year rate. Optional; without it the card is ranked at its standard rates.'),
 });
 const cardFields = {
     checkoutLabel: z

package/dist/mcp/schemas.js

@@ -413,6 +413,7 @@ export const ExplorationSchema = z.object({
         conditions: z.array(z.string()),
         evidence: z.object({ quote: z.string(), url: z.string() }).nullable(),
         withMembership: z.array(z.object({ membership: z.string(), effectiveReturnPct: z.number() })),
+        needsMembership: z.string().nullable(),
     })),
     excluded: z.array(ExcludedCardSchema),
     assumptions: z.array(z.string()),

package/dist/mcp/tools/account.js

@@ -5,19 +5,56 @@ import { listed } from "../../engine/text.js";
 import { savedSettingsText } from "../../engine/wallet-summary.js";
 import { fail } from "../context.js";
 import { WalletChangeSchema } from "../schemas.js";
+const cardsText = (n) => `${String(n)} ${n === 1 ? 'card' : 'cards'}`;
+// Everything a saved wallet holds, in words; empty when there's nothing.
+const contentsOf = (catalog, w) => [
+    ...(w.cards.length > 0
+        ? [`${cardsText(w.cards.length)} (${w.cards.map((c) => c.id).join(', ')})`]
+        : []),
+    ...savedSettingsText(catalog, w),
+];
+const ImportInput = z.object({
+    yaml: z
+        .string()
+        .min(1)
+        .max(100_000)
+        .describe('The wallet.yaml text, as the user gave it.'),
+    replace: z
+        .boolean()
+        .optional()
+        .describe('true to replace what the wallet already holds, after the user confirms.'),
+});
+export function importHandler(catalog, store, ctx) {
+    const contents = (w) => contentsOf(catalog, w);
+    return {
+        input: ImportInput,
+        run: async ({ yaml, replace }) => {
+            const parsed = parseWalletYaml(yaml, catalog);
+            if (typeof parsed === 'string')
+                return fail(parsed);
+            let current;
+            try {
+                current = await store.load();
+            }
+            catch (e) {
+                if (replace !== true)
+                    return fail(`Couldn't read the saved wallet to check what it holds (${e instanceof Error ? e.message : String(e)}). Ask the user, then call again with replace: true to overwrite it.`);
+                current = null;
+            }
+            const before = current === null ? [] : contents(current);
+            if (before.length > 0 && replace !== true)
+                return fail(`This would replace what's saved: ${listed(before)}. Ask the user, then call again with replace: true.`);
+            return ctx.changed(await store.replace(parsed), before.length > 0
+                ? `Replaced what was saved (${listed(before)}) with the imported wallet: ${listed(contents(parsed))}.`
+                : `Imported a wallet with ${listed(contents(parsed)) || 'nothing in it'}.`, { notes: false });
+        },
+    };
+}
 // A saved wallet on the hosted server has no file to copy or delete, so
 // these do it.
 export function registerAccountTools(server, catalog, store, ctx) {
-    const cardsText = (n) => `${String(n)} ${n === 1 ? 'card' : 'cards'}`;
-    // Everything a saved wallet holds, in words; empty when there's nothing.
-    const contents = (w) => [
-        ...(w.cards.length > 0
-            ? [
-                `${cardsText(w.cards.length)} (${w.cards.map((c) => c.id).join(', ')})`,
-            ]
-            : []),
-        ...savedSettingsText(catalog, w),
-    ];
+    const contents = (w) => contentsOf(catalog, w);
+    const importWallet = importHandler(catalog, store, ctx);
     server.registerTool('export_wallet', {
         title: 'Export the wallet',
         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.',
@@ -42,17 +79,7 @@ export function registerAccountTools(server, catalog, store, ctx) {
     server.registerTool('import_wallet', {
         title: 'Import a wallet',
         description: 'Replaces the saved wallet with a wallet.yaml from the earnrate command line or earnrate.dev, when the user pastes or attaches one. Wallet files only: never statements or card numbers. If anything is already saved (cards, memberships or point values), it refuses unless replace is true: confirm with the user first.',
-        inputSchema: z.object({
-            yaml: z
-                .string()
-                .min(1)
-                .max(100_000)
-                .describe('The wallet.yaml text, as the user gave it.'),
-            replace: z
-                .boolean()
-                .optional()
-                .describe('true to replace what the wallet already holds, after the user confirms.'),
-        }),
+        inputSchema: importWallet.input,
         outputSchema: WalletChangeSchema,
         annotations: {
             title: 'Import a wallet',
@@ -61,26 +88,7 @@ export function registerAccountTools(server, catalog, store, ctx) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ yaml, replace }) => {
-        const parsed = parseWalletYaml(yaml, catalog);
-        if (typeof parsed === 'string')
-            return fail(parsed);
-        let current;
-        try {
-            current = await store.load();
-        }
-        catch (e) {
-            if (replace !== true)
-                return fail(`Couldn't read the saved wallet to check what it holds (${e instanceof Error ? e.message : String(e)}). Ask the user, then call again with replace: true to overwrite it.`);
-            current = null;
-        }
-        const before = current === null ? [] : contents(current);
-        if (before.length > 0 && replace !== true)
-            return fail(`This would replace what's saved: ${listed(before)}. Ask the user, then call again with replace: true.`);
-        return ctx.changed(await store.replace(parsed), before.length > 0
-            ? `Replaced what was saved (${listed(before)}) with the imported wallet: ${listed(contents(parsed))}.`
-            : `Imported a wallet with ${listed(contents(parsed)) || 'nothing in it'}.`, { notes: false });
-    });
+    }, (args) => importWallet.run(args));
     server.registerTool('delete_wallet', {
         title: 'Delete the wallet',
         description: "Deletes the saved wallet and its recovery code now and for good, and signs out every app connected to it, this one included. earnrate.dev and the earnrate command line keep their own wallets and aren't affected. Only when the user asks to delete it: show it with list_wallet, offer export_wallet, and pass confirm, cards and saved only after the user confirms. It refuses if the wallet no longer holds what list_wallet showed, so a retried call can't delete a different wallet.",

package/dist/mcp/tools/wallet.js

@@ -63,8 +63,196 @@ function changes(catalog, args) {
         out.push(`welcome bonus tracked from ${args.bonus.opened}, ${money(args.bonus.spent ?? 0)} spent so far`);
     return out;
 }
-export function registerWalletTools(server, deps, ctx, inputs) {
+// The saved wallet with its summary and to-do list, as list_wallet shows it.
+export async function walletListing(deps, ctx) {
+    const read = await ctx.readableWallet();
+    if (typeof read === 'string')
+        return read;
+    const started = deps.savedWallets === 'account' ? await deps.store.started() : null;
+    const base = walletSummary(deps.catalog, read.wallet, deps.today());
+    const summary = {
+        ...base,
+        started,
+        checklist: checklist(deps.catalog, read.wallet, deps.today(), base, cardText(deps.catalog).shortName),
+    };
+    return { ...read, summary };
+}
+export function walletHandlers(deps, ctx, inputs) {
     const { catalog, store } = deps;
+    const listWallet = {
+        input: z.object({}),
+        run: async () => {
+            const found = await walletListing(deps, ctx);
+            if (typeof found === 'string')
+                return fail(found);
+            const { start, summary } = found;
+            const when = summary.started === null
+                ? `This is ${ctx.walletName}.\n`
+                : `This is ${ctx.walletName}. ${startedText(summary.started, Date.now())}\n`;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `${when}${start === null ? '' : `${start}\n`}${formatChecklist(summary.checklist)}${formatWalletSummary(summary)}`,
+                    },
+                ],
+                structuredContent: summary,
+            };
+        },
+    };
+    const RecordInput = z.object({
+        cardId: z
+            .string()
+            .min(1)
+            .describe('The card used, as a cardId from list_wallet or best_card_for_purchase.'),
+        merchant: Merchant,
+        amount: z.number().positive().describe('Amount spent in US dollars.'),
+        channel: ChannelInput,
+        date: DateInput,
+        category: inputs.RecordCategoryInput,
+    });
+    const recordPurchase = {
+        input: RecordInput,
+        run: async ({ cardId, merchant, amount, channel, date, category }) => {
+            const w = await ctx.wallet();
+            if (typeof w === 'string')
+                return fail(w);
+            if (!w.cards.some((c) => c.id === cardId))
+                return fail(`"${cardId}" isn't in the wallet. Cards: ${w.cards.map((c) => c.id).join(', ')}.`);
+            const purchase = {
+                cardId,
+                merchant,
+                amount,
+                channel: channel ?? null,
+                date: date ?? deps.today(),
+            };
+            const resolved = await ctx.resolve(merchant, purchase.channel, category ?? null);
+            if (resolved.merchant.source === 'none')
+                return fail(`earnrate doesn't recognize "${merchant}", so it can't tell which caps this purchase counts toward. Nothing was recorded. Call record_purchase again with category if you can tell what kind of business it is (a restaurant, a grocery store, a gas station), or ask the user. If nobody knows, category "other" records it toward a welcome bonus without touching any cap.`);
+            const result = await store.record(purchase, resolved.merchant);
+            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,
+                    booking,
+                    bonus,
+                    milestones,
+                    credit,
+                    message: `${formatBooking(amount, cardText(catalog).shortName(cardId), booking, bonus, milestones, credit, capLabel)} Saved in ${ctx.walletName}.`,
+                }
+                : {
+                    recorded: false,
+                    booking: null,
+                    bonus: null,
+                    milestones: [],
+                    credit: null,
+                    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: [
+                    {
+                        type: 'text',
+                        text: [output.message, ...resolved.notices].join('\n'),
+                    },
+                ],
+                structuredContent: output,
+            };
+        },
+    };
+    const addCard = {
+        input: CardChange,
+        run: async (args) => {
+            const result = await store.addCard(cardInput(args), deps.today());
+            const started = !result.ok || !result.created
+                ? ''
+                : deps.savedWallets === 'account'
+                    ? ', the first card in your saved wallet'
+                    : `, starting a new wallet at ${store.where}`;
+            return ctx.changed(result, `Added ${ctx.cardName(args.cardId)} (${args.cardId})${started}.`);
+        },
+    };
+    const updateCard = {
+        input: CardChange,
+        run: async (args) => {
+            const what = changes(catalog, args);
+            const card = catalog.cards.find((c) => c.id === args.cardId);
+            const unused = args.anniversary !== undefined && card && !needsAnniversary(card)
+                ? " None of its caps reset on the account anniversary, so earnrate doesn't use it."
+                : '';
+            return ctx.changed(await store.updateCard(cardInput(args), deps.today()), `Updated ${ctx.cardName(args.cardId)} (${args.cardId})${what.length > 0 ? `: ${what.join('; ')}` : ''}.${unused}`);
+        },
+    };
+    const RemoveInput = z.object({ cardId: CardId });
+    const removeCard = {
+        input: RemoveInput,
+        run: async ({ cardId }) => ctx.changed(await store.removeCard(cardId), `Removed ${ctx.cardName(cardId)} (${cardId}).`, { notes: false }),
+    };
+    const MembershipsInput = z.object({ memberships: inputs.AllMemberships });
+    const setMemberships = {
+        input: MembershipsInput,
+        run: async ({ memberships }) => {
+            const result = await store.setMemberships(memberships);
+            const used = new Set((result.ok ? result.wallet.cards : []).flatMap((held) => {
+                const card = catalog.cards.find((c) => c.id === held.id);
+                return card ? membershipsFor(card) : [];
+            }));
+            const unused = memberships.filter((m) => !used.has(m));
+            return ctx.changed(result, `${memberships.length > 0
+                ? `Memberships set to ${memberships.map((m) => `${membershipName(catalog, m)} (${m})`).join(', ')}.`
+                : 'Memberships cleared.'}${unused.length > 0 ? ` ${listed(unused.map((m) => membershipName(catalog, m)))} ${unused.length === 1 ? "doesn't" : "don't"} change any saved card's rates yet; kept for cards that use ${unused.length === 1 ? 'it' : 'them'}.` : ''}`, { notes: false });
+        },
+    };
+    const PointValuesInput = z.object({
+        values: z
+            .record(z.string(), z.number().nullable())
+            .optional()
+            .describe('Cents per point by currency id, e.g. {"UR": 1.5, "MR": 1.6}. null goes back to the default.'),
+        profile: z
+            .enum(['flat', 'points-heavy'])
+            .optional()
+            .describe(`A preset: flat (${profileText('flat')}) or points-heavy (${profileText('points-heavy')}). Values given too win over it.`),
+    });
+    const setPointValues = {
+        input: PointValuesInput,
+        run: async ({ values, profile }) => {
+            const given = currencyChanges(catalog, values ?? {});
+            if (!given.ok)
+                return fail(given.error);
+            const changes = {
+                ...(profile ? VALUATION_PROFILES[profile] : {}),
+                ...given.changes,
+            };
+            if (Object.keys(changes).length === 0)
+                return fail('Give values (cents per point by currency) or a profile.');
+            const result = await store.setValuations(changes);
+            const set = Object.entries(changes).map(([id, cents]) => cents === null
+                ? `${currencyLabel(catalog, id)} back to the default`
+                : `${currencyLabel(catalog, id)} at ${String(cents)}¢`);
+            return ctx.changed(result, `Point values: ${set.join(', ')}.`, {
+                notes: false,
+            });
+        },
+    };
+    return {
+        list_wallet: listWallet,
+        record_purchase: recordPurchase,
+        add_card: addCard,
+        update_card: updateCard,
+        remove_card: removeCard,
+        set_memberships: setMemberships,
+        set_point_values: setPointValues,
+    };
+}
+export function registerWalletTools(server, deps, ctx, inputs) {
+    const { catalog } = deps;
+    const tools = walletHandlers(deps, ctx, inputs);
     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, 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}`,
@@ -75,44 +263,11 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             destructiveHint: false,
             openWorldHint: false,
         },
-    }, async () => {
-        const read = await ctx.readableWallet();
-        if (typeof read === 'string')
-            return fail(read);
-        const started = deps.savedWallets === 'account' ? await deps.store.started() : null;
-        const base = walletSummary(catalog, read.wallet, deps.today());
-        const summary = {
-            ...base,
-            started,
-            checklist: checklist(catalog, read.wallet, deps.today(), base, cardText(catalog).shortName),
-        };
-        const when = started === null
-            ? `This is ${ctx.walletName}.\n`
-            : `This is ${ctx.walletName}. ${startedText(started, Date.now())}\n`;
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `${when}${read.start === null ? '' : `${read.start}\n`}${formatChecklist(summary.checklist)}${formatWalletSummary(summary)}`,
-                },
-            ],
-            structuredContent: summary,
-        };
-    });
+    }, () => tools.list_wallet.run());
     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 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()
-                .min(1)
-                .describe('The card used, as a cardId from list_wallet or best_card_for_purchase.'),
-            merchant: Merchant,
-            amount: z.number().positive().describe('Amount spent in US dollars.'),
-            channel: ChannelInput,
-            date: DateInput,
-            category: inputs.RecordCategoryInput,
-        }),
+        inputSchema: tools.record_purchase.input,
         outputSchema: RecordResultSchema,
         annotations: {
             title: 'Record a purchase',
@@ -121,62 +276,11 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             idempotentHint: false,
             openWorldHint: deps.llm !== null,
         },
-    }, async ({ cardId, merchant, amount, channel, date, category }) => {
-        const w = await ctx.wallet();
-        if (typeof w === 'string')
-            return fail(w);
-        if (!w.cards.some((c) => c.id === cardId))
-            return fail(`"${cardId}" isn't in the wallet. Cards: ${w.cards.map((c) => c.id).join(', ')}.`);
-        const purchase = {
-            cardId,
-            merchant,
-            amount,
-            channel: channel ?? null,
-            date: date ?? deps.today(),
-        };
-        const resolved = await ctx.resolve(merchant, purchase.channel, category ?? null);
-        if (resolved.merchant.source === 'none')
-            return fail(`earnrate doesn't recognize "${merchant}", so it can't tell which caps this purchase counts toward. Nothing was recorded. Call record_purchase again with category if you can tell what kind of business it is (a restaurant, a grocery store, a gas station), or ask the user. If nobody knows, category "other" records it toward a welcome bonus without touching any cap.`);
-        const result = await store.record(purchase, resolved.merchant);
-        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,
-                booking,
-                bonus,
-                milestones,
-                credit,
-                message: `${formatBooking(amount, cardText(catalog).shortName(cardId), booking, bonus, milestones, credit, capLabel)} Saved in ${ctx.walletName}.`,
-            }
-            : {
-                recorded: false,
-                booking: null,
-                bonus: null,
-                milestones: [],
-                credit: null,
-                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: [
-                {
-                    type: 'text',
-                    text: [output.message, ...resolved.notices].join('\n'),
-                },
-            ],
-            structuredContent: output,
-        };
-    });
+    }, (args) => tools.record_purchase.run(args));
     server.registerTool('add_card', {
         title: 'Add a card',
         description: `Adds a card the user holds to their wallet by its id from search_cards, creating the wallet if there isn't one. The reply says what the card still needs (category picks, memberships, activations); ask the user about those. Stores only the card's product id and settings, never card numbers. ${ctx.walletUse}`,
-        inputSchema: CardChange,
+        inputSchema: tools.add_card.input,
         outputSchema: WalletChangeSchema,
         annotations: {
             title: 'Add a card',
@@ -184,19 +288,11 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             destructiveHint: false,
             idempotentHint: false,
         },
-    }, async (args) => {
-        const result = await store.addCard(cardInput(args), deps.today());
-        const started = !result.ok || !result.created
-            ? ''
-            : deps.savedWallets === 'account'
-                ? ', the first card in your saved wallet'
-                : `, starting a new wallet at ${store.where}`;
-        return ctx.changed(result, `Added ${ctx.cardName(args.cardId)} (${args.cardId})${started}.`);
-    });
+    }, (args) => tools.add_card.run(args));
     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 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,
+        inputSchema: tools.update_card.input,
         outputSchema: WalletChangeSchema,
         annotations: {
             title: 'Update a card',
@@ -204,18 +300,11 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             destructiveHint: true,
             idempotentHint: true,
         },
-    }, async (args) => {
-        const what = changes(catalog, args);
-        const card = catalog.cards.find((c) => c.id === args.cardId);
-        const unused = args.anniversary !== undefined && card && !needsAnniversary(card)
-            ? " None of its caps reset on the account anniversary, so earnrate doesn't use it."
-            : '';
-        return ctx.changed(await store.updateCard(cardInput(args), deps.today()), `Updated ${ctx.cardName(args.cardId)} (${args.cardId})${what.length > 0 ? `: ${what.join('; ')}` : ''}.${unused}`);
-    });
+    }, (args) => tools.update_card.run(args));
     server.registerTool('remove_card', {
         title: 'Remove a card',
         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 }),
+        inputSchema: tools.remove_card.input,
         outputSchema: WalletChangeSchema,
         annotations: {
             title: 'Remove a card',
@@ -223,11 +312,11 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             destructiveHint: true,
             idempotentHint: true,
         },
-    }, async ({ cardId }) => ctx.changed(await store.removeCard(cardId), `Removed ${ctx.cardName(cardId)} (${cardId}).`, { notes: false }));
+    }, (args) => tools.remove_card.run(args));
     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, and costco for a Costco membership (so spending answers don't count its cost against Costco Anywhere). Replaces the whole list, so include the ones to keep. It saves them even with no cards saved, and every answer then uses them. ${ctx.walletUse}`,
-        inputSchema: z.object({ memberships: inputs.AllMemberships }),
+        inputSchema: tools.set_memberships.input,
         outputSchema: WalletChangeSchema,
         annotations: {
             title: 'Set memberships',
@@ -235,30 +324,11 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             destructiveHint: true,
             idempotentHint: true,
         },
-    }, async ({ memberships }) => {
-        const result = await store.setMemberships(memberships);
-        const used = new Set((result.ok ? result.wallet.cards : []).flatMap((held) => {
-            const card = catalog.cards.find((c) => c.id === held.id);
-            return card ? membershipsFor(card) : [];
-        }));
-        const unused = memberships.filter((m) => !used.has(m));
-        return ctx.changed(result, `${memberships.length > 0
-            ? `Memberships set to ${memberships.map((m) => `${membershipName(catalog, m)} (${m})`).join(', ')}.`
-            : 'Memberships cleared.'}${unused.length > 0 ? ` ${listed(unused.map((m) => membershipName(catalog, m)))} ${unused.length === 1 ? "doesn't" : "don't"} change any saved card's rates yet; kept for cards that use ${unused.length === 1 ? 'it' : 'them'}.` : ''}`, { notes: false });
-    });
+    }, (args) => tools.set_memberships.run(args));
     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 by id: ${catalog.currencies.map((c) => `${c.id} (${c.name})`).join(', ')}. ${ctx.walletUse}`,
-        inputSchema: z.object({
-            values: z
-                .record(z.string(), z.number().nullable())
-                .optional()
-                .describe('Cents per point by currency id, e.g. {"UR": 1.5, "MR": 1.6}. null goes back to the default.'),
-            profile: z
-                .enum(['flat', 'points-heavy'])
-                .optional()
-                .describe(`A preset: flat (${profileText('flat')}) or points-heavy (${profileText('points-heavy')}). Values given too win over it.`),
-        }),
+        inputSchema: tools.set_point_values.input,
         outputSchema: WalletChangeSchema,
         annotations: {
             title: 'Set point values',
@@ -266,22 +336,5 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             destructiveHint: true,
             idempotentHint: true,
         },
-    }, async ({ values, profile }) => {
-        const given = currencyChanges(catalog, values ?? {});
-        if (!given.ok)
-            return fail(given.error);
-        const changes = {
-            ...(profile ? VALUATION_PROFILES[profile] : {}),
-            ...given.changes,
-        };
-        if (Object.keys(changes).length === 0)
-            return fail('Give values (cents per point by currency) or a profile.');
-        const result = await store.setValuations(changes);
-        const set = Object.entries(changes).map(([id, cents]) => cents === null
-            ? `${currencyLabel(catalog, id)} back to the default`
-            : `${currencyLabel(catalog, id)} at ${String(cents)}¢`);
-        return ctx.changed(result, `Point values: ${set.join(', ')}.`, {
-            notes: false,
-        });
-    });
+    }, (args) => tools.set_point_values.run(args));
 }

package/dist/mcp/wallet-api.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { makeContext } from "./context.js";
+import { makeInputs } from "./inputs.js";
+import { importHandler } from "./tools/account.js";
+import { walletHandlers, walletListing } from "./tools/wallet.js";
+// The changes earnrate.dev can make to a synced wallet, by MCP tool name.
+// import_wallet replaces it all, with the tool's own confirmation.
+export const WALLET_CHANGES = [
+    'add_card',
+    'update_card',
+    'remove_card',
+    'set_memberships',
+    'set_point_values',
+    'record_purchase',
+    'import_wallet',
+];
+const ChangeRequest = z.object({
+    tool: z.enum(WALLET_CHANGES),
+    input: z.record(z.string(), z.unknown()).optional(),
+});
+// The hosted wallet over plain HTTP: reads give what list_wallet gives, and
+// each change runs the MCP tool's own handler, so the rules and refusals
+// can't drift between earnrate.dev and Claude.
+export function walletApi(deps) {
+    const server = {
+        ...deps,
+        savedWallets: 'account',
+        llm: null,
+        version: '',
+    };
+    const ctx = makeContext(server);
+    const handlers = {
+        ...walletHandlers(server, ctx, makeInputs(deps.catalog)),
+        import_wallet: importHandler(deps.catalog, deps.store, ctx),
+    };
+    async function read() {
+        const found = await walletListing(server, ctx);
+        if (typeof found === 'string')
+            return { status: 422, body: { error: found } };
+        return {
+            status: 200,
+            body: { wallet: found.wallet, summary: found.summary },
+        };
+    }
+    // `body` is the request's parsed JSON: {"tool": "add_card", "input": {...}}.
+    async function change(body) {
+        const request = ChangeRequest.safeParse(body);
+        if (!request.success)
+            return {
+                status: 400,
+                body: {
+                    error: `Send one change as {"tool": ..., "input": {...}}, where tool is one of ${WALLET_CHANGES.join(', ')}.`,
+                },
+            };
+        const { tool, input } = request.data;
+        const handler = handlers[tool];
+        const args = handler.input.safeParse(input ?? {});
+        if (!args.success)
+            return {
+                status: 400,
+                tool,
+                body: {
+                    error: `Invalid input for ${tool}: ${z.prettifyError(args.error)}`,
+                },
+            };
+        const result = await handler.run(args.data);
+        const text = result.content.map((c) => c.text).join('\n');
+        if (result.isError)
+            return { status: 422, tool, body: { error: text } };
+        const after = await read();
+        return {
+            status: after.status,
+            tool,
+            body: after.status === 200 ? { message: text, ...after.body } : after.body,
+        };
+    }
+    return { read, change };
+}

package/package.json

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