earnrate 0.2.4 → 0.2.6

package/dist/mcp/tools/answers.js

@@ -13,6 +13,7 @@ import { formatCheatSheet } from "../../format/cheat-sheet.js";
 import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../../format/explore.js";
 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 { CardSearchSchema, CheatSheetSchema, ExplorationSchema, MerchantResolutionSchema, OfferComparisonSchema, PurchaseAnswerSchema, SpendingSimulationSchema, } from "../schemas.js";
@@ -24,6 +25,7 @@ const SOURCES = {
     category: 'a kind of purchase, not a store',
     none: 'not recognized',
 };
+const EVERY_CARD_NOTE = "Picked from every card earnrate knows, as asked, not just the user's saved cards. The user's saved memberships and point values still apply.";
 const TOP = 10;
 // The tools that answer without a saved wallet: from every card, the cards
 // named in the conversation, or a saved wallet if there is one.
@@ -45,16 +47,21 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             category: CategoryInput,
             cards: NamedCards,
             memberships: NamedMemberships,
+            valuation: CatalogFilters.valuation,
         }),
         outputSchema: PurchaseAnswerSchema,
         annotations: {
+            title: 'Best card for a purchase',
             readOnlyHint: true,
             openWorldHint: deps.llm !== null,
         },
-    }, async ({ merchant, amount, channel, date, category, cards, memberships, }) => {
-        const wallet = await ctx.cardsFor(cards, memberships);
-        if (typeof wallet === 'string')
-            return fail(wallet);
+    }, async ({ merchant, amount, channel, date, category, cards, memberships, valuation, }) => {
+        const held = await ctx.cardsFor(cards, memberships);
+        if (typeof held === 'string')
+            return fail(held);
+        const wallet = held !== null && valuation
+            ? withValuationProfile(held, valuation)
+            : held;
         const purchase = {
             merchant,
             amount: amount ?? null,
@@ -73,14 +80,14 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 amount: purchase.amount,
                 channel: purchase.channel,
                 date: purchase.date,
-            }, settings({ memberships }), resolved.merchant);
+            }, 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);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `${retry}${formatExploration(allCards, true)}\n${ALL_CARDS_NOTE}`,
+                        text: `${retry}${formatExploration(allCards, catalog, true)}\n${ALL_CARDS_NOTE}`,
                     },
                 ],
                 structuredContent: {
@@ -100,7 +107,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             content: [
                 {
                     type: 'text',
-                    text: `${retry}${formatRecommendation(output, purchase, { all: true })}`,
+                    text: `${retry}${ctx.fromCards(cards)}${formatRecommendation(output, purchase, { all: true })}`,
                 },
             ],
             structuredContent: output,
@@ -115,7 +122,11 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             category: CategoryInput,
         }),
         outputSchema: MerchantResolutionSchema,
-        annotations: { readOnlyHint: true, openWorldHint: deps.llm !== null },
+        annotations: {
+            title: 'Resolve a merchant',
+            readOnlyHint: true,
+            openWorldHint: deps.llm !== null,
+        },
     }, async ({ merchant, channel, category }) => {
         const resolved = await ctx.resolve(merchant, channel ?? null, category ?? null);
         const m = resolved.merchant;
@@ -150,12 +161,16 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             cards: NamedCards,
         }),
         outputSchema: OfferComparisonSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Compare welcome offers',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async (args) => {
         const wallet = await ctx.cardsFor(args.cards, undefined);
         if (typeof wallet === 'string')
             return fail(wallet);
-        const base = wallet ?? EMPTY_WALLET;
+        const base = wallet ?? { ...EMPTY_WALLET, ...(await ctx.saved()) };
         const comparison = compareOffers(catalog, args.valuation ? withValuationProfile(base, args.valuation) : base, {
             kind: args.kind ?? 'any',
             noAnnualFee: args.noAnnualFee ?? false,
@@ -164,16 +179,19 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         }, deps.today());
         const trimmed = {
             ...comparison,
-            offers: comparison.offers.slice(0, TOP),
+            // Offers ruled out by a card the user holds sort last; keep them in
+            // view so the reason shows.
+            offers: comparison.offers.filter((o, i) => i < TOP || o.ineligible !== null),
         };
         const more = comparison.offers.length - trimmed.offers.length;
         return {
             content: [
                 {
                     type: 'text',
-                    text: formatOffers(trimmed, (id) => currencyName(catalog, id), true) +
+                    text: (wallet === null ? '' : ctx.fromCards(args.cards)) +
+                        formatOffers(trimmed, (id) => currencyName(catalog, id), true) +
                         (more > 0
-                            ? `\nThe top ${String(TOP)} of ${String(comparison.offers.length)} offers. Narrow them with kind, noAnnualFee or business.\n`
+                            ? `\nThe top ${String(TOP)} of ${String(comparison.offers.length)} offers${trimmed.offers.length > TOP ? `, plus ${String(trimmed.offers.length - TOP)} likely not eligible` : ''}. Narrow them with kind, noAnnualFee or business.\n`
                             : ''),
                 },
             ],
@@ -182,7 +200,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     });
     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.',
+        description: 'Ranks every card earnrate knows that takes new applicants, 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(),
@@ -195,20 +213,29 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             ...CatalogFilters,
         }),
         outputSchema: ExplorationSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
-    }, (args) => {
+        annotations: {
+            title: 'Best cards for a purchase',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
         if (args.merchant === undefined && args.category === undefined)
             return fail('Give a merchant or a category.');
+        const channel = args.channel ?? null;
         const result = exploreCards(catalog, {
             merchant: args.merchant ?? null,
-            category: args.merchant === undefined ? (args.category ?? null) : null,
+            category: args.category ?? null,
             amount: args.amount ?? null,
-            channel: args.channel ?? null,
+            channel,
             date: deps.today(),
-        }, settings(args));
+        }, settings(args, await ctx.saved()), args.merchant === undefined
+            ? undefined
+            : withCallerCategory(resolvePlace(catalog, args.merchant, channel), args.category ?? null));
         const trimmed = { ...result, ranked: result.ranked.slice(0, TOP) };
         return {
-            content: [{ type: 'text', text: formatExploration(trimmed, true) }],
+            content: [
+                { type: 'text', text: formatExploration(trimmed, catalog, true) },
+            ],
             structuredContent: trimmed,
         };
     });
@@ -232,7 +259,11 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             ...CatalogFilters,
         }),
         outputSchema: SpendingSimulationSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Simulate a year of spending',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async (args) => {
         const given = args.spending ?? [];
         if (given.some((l) => l.merchant === undefined && l.category === undefined))
@@ -248,7 +279,10 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         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 notes = given.length === 0 ? [TYPICAL_SPEND_NOTE] : [];
-        const options = { ...settings(args), start: deps.today() };
+        const options = {
+            ...settings(args, await ctx.saved()),
+            start: deps.today(),
+        };
         const wantsTheirs = (args.cards !== undefined && args.cards.length > 0) ||
             args.compareToWallet === true;
         const wallet = wantsTheirs
@@ -261,7 +295,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 ? withValuationProfile(wallet, args.valuation)
                 : wallet;
             const result = simulateAdditions(catalog, valued, lines, options);
-            const text = formatAdditions(result, catalog, false);
+            const text = `${ctx.fromCards(args.cards)}${formatAdditions(result, catalog, false)}`;
             return {
                 content: [{ type: 'text', text: [...notes, text].join('\n\n') }],
                 structuredContent: {
@@ -296,6 +330,10 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         inputSchema: z.object({
             date: DateInput,
             cards: NamedCards,
+            everyCard: z
+                .boolean()
+                .optional()
+                .describe('true to pick from every card earnrate knows even when the user has a saved wallet ("which cards should I get?"); the filters then apply.'),
             memberships: NamedMemberships,
             kind: CatalogFilters.kind,
             noAnnualFee: CatalogFilters.noAnnualFee,
@@ -304,22 +342,35 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             valuation: CatalogFilters.valuation,
         }),
         outputSchema: CheatSheetSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Cheat sheet',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async (args) => {
-        const wallet = await ctx.cardsFor(args.cards, args.memberships);
+        const wallet = args.everyCard === true
+            ? null
+            : await ctx.cardsFor(args.cards, args.memberships);
         if (typeof wallet === 'string')
             return fail(wallet);
         const date = args.date ?? deps.today();
         const sheet = wallet === null
             ? {
-                ...catalogCheatSheet(catalog, date, settings(args)),
-                notes: [ALL_CARDS_NOTE],
+                ...catalogCheatSheet(catalog, date, settings(args, await ctx.saved())),
+                notes: [
+                    args.everyCard === true ? EVERY_CARD_NOTE : ALL_CARDS_NOTE,
+                ],
             }
             : cheatSheet(catalog, args.valuation
                 ? withValuationProfile(wallet, args.valuation)
                 : wallet, date);
         return {
-            content: [{ type: 'text', text: formatCheatSheet(sheet) }],
+            content: [
+                {
+                    type: 'text',
+                    text: `${wallet === null ? '' : ctx.fromCards(args.cards)}${formatCheatSheet(sheet)}`,
+                },
+            ],
             structuredContent: sheet,
         };
     });
@@ -333,7 +384,11 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 .describe('Card name or issuer, as the user said it.'),
         }),
         outputSchema: CardSearchSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Search cards',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async ({ query }) => {
         const held = await deps.store.load().catch(() => null);
         const result = searchCards(catalog, query ?? '', held, deps.today());

package/dist/mcp/tools/wallet.js

@@ -1,17 +1,34 @@
 import { z } from 'zod';
 import { membershipsFor, needsAnniversary } from "../../engine/setup.js";
-import { choiceName, money, words } from "../../engine/text.js";
-import { walletSummary } from "../../engine/wallet-summary.js";
+import { choiceName, currencyLabel, listed, money, shortDate, words, } from "../../engine/text.js";
+import { membershipName } from "../../engine/memberships.js";
+import { profileText, VALUATION_PROFILES } from "../../engine/profiles.js";
+import { optionName, walletSummary } from "../../engine/wallet-summary.js";
 import { formatBooking, formatWalletSummary } from "../../format/wallet.js";
 import { fail } from "../context.js";
 import { CardChange, CardId, cardInput, ChannelInput, DateInput, Merchant, } from "../inputs.js";
 import { RecordResultSchema, WalletChangeSchema, WalletSummarySchema, } from "../schemas.js";
 const WRITE = { readOnlyHint: false, openWorldHint: false };
+// "Saved wallet started 4 minutes ago": relative, since the server doesn't
+// know the user's time zone, and precise enough to tell apart two wallets
+// started the same day.
+function startedText(started, now) {
+    const minutes = Math.floor((now - Date.parse(started)) / 60_000);
+    const ago = minutes < 1
+        ? 'just now'
+        : minutes < 60
+            ? `${String(minutes)} minute${minutes === 1 ? '' : 's'} ago`
+            : minutes < 48 * 60
+                ? `${String(Math.floor(minutes / 60))} hour${minutes < 120 ? '' : 's'} ago`
+                : `on ${shortDate(started.slice(0, 10))}`;
+    return `It was started ${ago}.`;
+}
 // What update_card changed, so the reply confirms the values it saved.
-function changes(args) {
+function changes(catalog, args) {
+    const card = catalog.cards.find((c) => c.id === args.cardId);
     const out = [];
     for (const [choice, options] of Object.entries(args.picks ?? {}))
-        out.push(`${choiceName(choice)} picks: ${options.map(words).join(', ')}`);
+        out.push(`${choiceName(choice)} picks: ${options.map((o) => (card ? optionName(catalog, card, choice, o) : words(o))).join('; ')}`);
     if (args.checkoutLabel === null)
         out.push('checkout name cleared');
     else if (args.checkoutLabel !== undefined)
@@ -35,24 +52,38 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     const { catalog, store } = deps;
     server.registerTool('list_wallet', {
         title: 'List wallet',
-        description: "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, and when each card's data was last verified.",
+        description: `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}`,
         outputSchema: WalletSummarySchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'List wallet',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async () => {
         const read = await ctx.readableWallet();
         if (typeof read === 'string')
             return fail(read);
-        const summary = walletSummary(catalog, read.wallet, deps.today());
+        const started = deps.savedWallets === 'account' ? await deps.store.started() : null;
+        const summary = {
+            ...walletSummary(catalog, read.wallet, deps.today()),
+            started,
+        };
+        const when = started === null
+            ? `This is ${ctx.walletName}.\n`
+            : `This is ${ctx.walletName}. ${startedText(started, Date.now())}\n`;
         return {
             content: [
-                { type: 'text', text: read.start ?? formatWalletSummary(summary) },
+                {
+                    type: 'text',
+                    text: `${when}${read.start === null ? '' : `${read.start}\n`}${formatWalletSummary(summary)}`,
+                },
             ],
             structuredContent: summary,
         };
     });
     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.",
+        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}`,
         inputSchema: z.object({
             cardId: z
                 .string()
@@ -62,10 +93,11 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             amount: z.number().positive().describe('Amount spent in US dollars.'),
             channel: ChannelInput,
             date: DateInput,
-            category: inputs.CategoryInput,
+            category: inputs.RecordCategoryInput,
         }),
         outputSchema: RecordResultSchema,
         annotations: {
+            title: 'Record a purchase',
             ...WRITE,
             destructiveHint: false,
             idempotentHint: false,
@@ -96,7 +128,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
                 recorded: true,
                 booking,
                 bonus,
-                message: formatBooking(amount, cardId, booking, bonus),
+                message: `${formatBooking(amount, cardId, booking, bonus)} Saved in ${ctx.walletName}.`,
             }
             : {
                 recorded: false,
@@ -116,10 +148,15 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     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.",
+        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,
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: false, idempotentHint: false },
+        annotations: {
+            title: 'Add a card',
+            ...WRITE,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
     }, async (args) => {
         const result = await store.addCard(cardInput(args), deps.today());
         const started = !result.ok || !result.created
@@ -131,12 +168,17 @@ 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+.',
+        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}`,
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
+        annotations: {
+            title: 'Update a card',
+            ...WRITE,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
     }, async (args) => {
-        const what = changes(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."
@@ -145,17 +187,27 @@ 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. Only when the user says they no longer have it or don't want it considered.",
+        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}`,
         inputSchema: z.object({ cardId: CardId }),
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
+        annotations: {
+            title: 'Remove a card',
+            ...WRITE,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
     }, async ({ cardId }) => ctx.changed(await store.removeCard(cardId), `Removed ${ctx.cardName(cardId)} (${cardId}).`, { notes: false }));
     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.",
+        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 }),
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
+        annotations: {
+            title: 'Set memberships',
+            ...WRITE,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
     }, async ({ memberships }) => {
         const result = await store.setMemberships(memberships);
         const used = new Set((result.ok ? result.wallet.cards : []).flatMap((held) => {
@@ -164,7 +216,42 @@ export function registerWalletTools(server, deps, ctx, inputs) {
         }));
         const unused = memberships.filter((m) => !used.has(m));
         return ctx.changed(result, `${memberships.length > 0
-            ? `Memberships set to ${memberships.join(', ')}.`
-            : 'Memberships cleared.'}${unused.length > 0 ? ` ${unused.join(', ')} ${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 });
+            ? `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 });
+    });
+    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}`,
+        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.`),
+        }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            title: 'Set point values',
+            ...WRITE,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ values, profile }) => {
+        const changes = {
+            ...(profile ? VALUATION_PROFILES[profile] : {}),
+            ...(values ?? {}),
+        };
+        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,
+        });
     });
 }

package/dist/merchants/cache.js

@@ -38,16 +38,6 @@ export function merchantCachePath(env = process.env) {
     return (env[MERCHANT_CACHE_ENV_VAR] ??
         path.join(homedir(), CONFIG_DIR, 'merchant-cache.json'));
 }
-export function memoryCache() {
-    const entries = new Map();
-    return {
-        get: (key) => entries.get(key),
-        set: (key, value) => {
-            entries.set(key, value);
-            return Promise.resolve();
-        },
-    };
-}
 // A cache file that can't be read is left alone rather than overwritten, so a
 // hand edit gone wrong doesn't lose every saved classification.
 export async function openMerchantCache(file) {

package/dist/merchants/resolve.js

@@ -116,17 +116,94 @@ function fromMerchant(found, source, input, channel, typedDomain) {
         inference: null,
     };
 }
+// A merchant's record by id; an override replaces the seed entry.
+export function findMerchant(catalog, id) {
+    return (catalog.merchants.overrides.find((m) => m.id === id) ??
+        catalog.merchants.seed.find((m) => m.id === id));
+}
 export function resolveMerchantById(catalog, id, channel) {
     const override = catalog.merchants.overrides.find((m) => m.id === id);
-    const found = override ?? catalog.merchants.seed.find((m) => m.id === id);
+    const found = findMerchant(catalog, id);
     if (!found)
         return null;
     return fromMerchant(found, override ? 'override' : 'seed', found.name, channel, false);
 }
-// Used only when the merchant is unknown: curated data always wins over a
-// category supplied with the request.
+// Curated merchant data always wins over a category supplied with the
+// request; the caller's category wins over an unknown name or a different
+// category word.
 export function withCallerCategory(merchant, category) {
-    if (merchant.source !== 'none' || category === null)
+    if (category === null)
+        return merchant;
+    const otherWord = merchant.source === 'category' && merchant.category !== category;
+    if (merchant.source !== 'none' && !otherWord)
         return merchant;
     return { ...merchant, category, confidence: 'medium', source: 'caller' };
 }
+const plainWords = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+// A category from everyday words: an alias ("groceries") first, then the
+// name, then the id, so "grocery" means supermarkets rather than the parent.
+export function findCategory(catalog, text) {
+    const wanted = plainWords(text);
+    if (wanted === '')
+        return null;
+    // "grocery store" finds "grocery stores", and "drugstore" "drugstores".
+    const forms = [
+        wanted,
+        wanted.endsWith('s') ? wanted.slice(0, -1) : `${wanted}s`,
+    ];
+    for (const form of forms) {
+        const by = (key) => catalog.categories.find((c) => key(c).map(plainWords).includes(form))?.id;
+        const found = by((c) => c.aliases) ?? by((c) => [c.name]) ?? by((c) => [c.id]);
+        if (found !== undefined)
+            return found;
+    }
+    return null;
+}
+export function categoryResolution(catalog, category, channel) {
+    const found = catalog.categories.find((c) => c.id === category);
+    if (!found)
+        throw new Error(`unknown category '${category}'`);
+    return {
+        input: found.name,
+        merchantId: null,
+        resolvedName: found.name,
+        category,
+        likelyMcc: null,
+        accepts: null,
+        ambiguity: null,
+        channel,
+        confidence: 'high',
+        source: 'category',
+        bookedVia: [],
+        inference: null,
+    };
+}
+// Words around a place that don't name it: "a restaurant", "the grocery
+// store", "a gas station near me".
+const LEADING = /^(?:(?:a|an|the|my|any|some|our|your|this|that|local|nearby|nearest)\s+)+/i;
+const TRAILING = /\s+(?:near me|nearby|around here|close by)$/i;
+// What someone typed: a store earnrate knows, else a category word
+// ("restaurants", "gas"), else unrecognized. Names are tried as given first,
+// so a store like The Home Depot keeps its "The".
+export function resolvePlace(catalog, text, channel) {
+    const attempt = (t) => {
+        const known = resolveMerchant(catalog, t, channel);
+        if (known.source !== 'none')
+            return known;
+        const category = findCategory(catalog, t);
+        return category === null
+            ? known
+            : categoryResolution(catalog, category, channel);
+    };
+    const asGiven = attempt(text);
+    if (asGiven.source !== 'none')
+        return asGiven;
+    const bare = text.trim().replace(TRAILING, '').replace(LEADING, '');
+    if (bare === '' || bare === text.trim())
+        return asGiven;
+    const found = attempt(bare);
+    return found.source === 'none' ? asGiven : found;
+}

package/dist/schema/card.js

@@ -58,12 +58,15 @@ export const RuleSchema = z
         .optional(),
     valid_from: IsoDate.optional(),
     valid_to: IsoDate.optional(),
+    // The issuer's last day to activate a bonus that needs it.
+    activate_by: IsoDate.optional(),
     // Set when a rule isn't confirmed against the issuer's terms. The engine
     // warns when an unverified rule decides the winner.
     unverified: z.string().optional(),
     note: z.string().optional(),
 })
-    .refine((r) => !r.valid_from || !r.valid_to || r.valid_from <= r.valid_to, 'valid_from must not be after valid_to');
+    .refine((r) => !r.valid_from || !r.valid_to || r.valid_from <= r.valid_to, 'valid_from must not be after valid_to')
+    .refine((r) => r.activate_by === undefined || r.requires?.activation === true, 'activate_by needs requires.activation');
 // The public sign-up bonus on the issuer's page. Offers vary by person and
 // channel, so a wallet can override it.
 export const WelcomeOfferSchema = z
@@ -146,17 +149,10 @@ export const CardSchema = z
     // When the first year differs, usually a waived fee.
     first_year_fee: z.number().nonnegative().optional(),
     welcome_offer: WelcomeOfferSchema.optional(),
-    // A paid membership the card can't be had without (Costco Anywhere). Its
-    // cost counts like an annual fee for anyone not already paying for it.
-    requires_membership: z
-        .strictObject({
-        id: KebabId,
-        name: z.string().min(1), // "a Costco membership"
-        annual_fee: z.number().nonnegative(), // the basic tier, dollars
-        // Only members can buy here, so spending here means a member.
-        members_shop_at: z.array(KebabId).default([]),
-    })
-        .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
+    // fee for anyone not already paying it.
+    requires_membership: KebabId.optional(),
     pools_into: z
         .strictObject({
         currency: CurrencyId,

package/dist/schema/category.js

@@ -9,5 +9,9 @@ export const CategorySchema = z.strictObject({
     // Everyday words people search by ("groceries"), besides the name.
     aliases: z.array(z.string().min(1)).default([]),
     note: z.string().optional(),
+    // Bought as a service, a category reads "on" (3x on flights); places read
+    // "at". Subcategories inherit it.
+    preposition: z.literal('on').optional(),
+    slug: z.string().optional(), // its search page, when not from its name
 });
 export const CategoriesFileSchema = z.array(CategorySchema).min(1);