earnrate 0.2.3 → 0.2.4

package/dist/mcp/tools/answers.js

@@ -6,7 +6,7 @@ import { withValuationProfile } from "../../engine/profiles.js";
 import { recommend } from "../../engine/recommend.js";
 import { searchCards } from "../../engine/setup.js";
 import { resolveSpendLines, simulateAdditions, simulateCatalog, TYPICAL_SPEND_NOTE, typicalSpendLines, } from "../../engine/simulate.js";
-import { currencyName } from "../../engine/text.js";
+import { categoryPhrase, currencyName, NETWORK_NAMES, } from "../../engine/text.js";
 import { EMPTY_WALLET } from "../../engine/transient.js";
 import { formatCardInfo } from "../../format/cards.js";
 import { formatCheatSheet } from "../../format/cheat-sheet.js";
@@ -16,6 +16,14 @@ import { formatRecommendation } from "../../format/recommendation.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";
+const SOURCES = {
+    override: "from earnrate's merchant list",
+    seed: "from earnrate's merchant list",
+    llm: 'classified by Claude',
+    caller: 'from the category given with the request',
+    category: 'a kind of purchase, not a store',
+    none: 'not recognized',
+};
 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.
@@ -24,7 +32,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     const { CategoryInput, CatalogCategory, NamedCards, NamedMemberships, OfferFilters, CatalogFilters, } = inputs;
     server.registerTool('best_card_for_purchase', {
         title: 'Best card for a purchase',
-        description: "Which card earns the most rewards for a purchase, and why. With no cards given and no saved wallet, it ranks every card earnrate knows (in `allCards`): a complete answer for anyone. With cards named in the conversation (`cards`) or a saved wallet, it picks the best of the user's own: `decision.cardId` is the pick and `decision.checkoutLabel` is how the card appears at checkout, with every usable card ranked with reasons, cards the merchant won't take, assumptions, warnings, and when a different point valuation would change the pick. Never needs or returns card numbers.",
+        description: "Which card earns the most rewards for a purchase, and why. With no cards given and no saved wallet, it ranks every card earnrate knows (in `allCards`): a complete answer for anyone. With cards named in the conversation (`cards`) or a saved wallet, it picks the best of the user's own: `decision.cardId` is the pick and `decision.checkoutLabel` is how the card appears at checkout, with every usable card ranked with reasons, cards the merchant won't take, assumptions, warnings, and when a different point valuation would change the pick. For a business earnrate may not know, like a local restaurant, pass `category` when you can tell what kind of business it is. Never needs or returns card numbers.",
         inputSchema: z.object({
             merchant: Merchant,
             amount: z
@@ -55,6 +63,9 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             country: 'US',
         };
         const resolved = await ctx.resolve(merchant, purchase.channel, category ?? null);
+        const retry = resolved.merchant.source === 'none'
+            ? `earnrate doesn't recognize "${merchant}", so this answer uses only base rates and may miss the best card. If you can tell what kind of business it is (a restaurant, a grocery store, a gas station), call best_card_for_purchase again with category; otherwise ask the user.\n\n`
+            : '';
         if (wallet === null) {
             const explored = exploreCards(catalog, {
                 merchant,
@@ -69,7 +80,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 content: [
                     {
                         type: 'text',
-                        text: `${formatExploration(allCards, true)}\n${ALL_CARDS_NOTE}`,
+                        text: `${retry}${formatExploration(allCards, true)}\n${ALL_CARDS_NOTE}`,
                     },
                 ],
                 structuredContent: {
@@ -89,7 +100,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             content: [
                 {
                     type: 'text',
-                    text: formatRecommendation(output, purchase, { all: true }),
+                    text: `${retry}${formatRecommendation(output, purchase, { all: true })}`,
                 },
             ],
             structuredContent: output,
@@ -109,7 +120,13 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         const resolved = await ctx.resolve(merchant, channel ?? null, category ?? null);
         const m = resolved.merchant;
         const text = [
-            `${m.resolvedName}: ${m.category}${m.likelyMcc === null ? '' : ` (MCC ${String(m.likelyMcc)})`}, ${m.confidence} confidence, from ${m.source}.`,
+            `${m.resolvedName}: ${categoryPhrase(catalog, m.category)}${m.likelyMcc === null ? '' : ` (MCC ${String(m.likelyMcc)})`}, ${m.confidence} confidence, ${SOURCES[m.source]}.`,
+            m.accepts === null
+                ? m.source === 'none'
+                    ? 'Which card networks it takes is unknown.'
+                    : 'Takes all major card networks.'
+                : `Takes ${m.accepts.map((n) => NETWORK_NAMES[n] ?? n).join(', ')} only.`,
+            ...(m.ambiguity ? [m.ambiguity.note] : []),
             ...(m.inference
                 ? [`Claude's reasoning: ${m.inference.rationale}`]
                 : []),
@@ -122,7 +139,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     });
     server.registerTool('compare_welcome_offers', {
         title: 'Compare welcome offers',
-        description: "Ranks the public welcome (sign-up) offers on cards the user doesn't have by first-year value: the bonus at the user's point values minus the first year's annual fee. Use it when the user asks which new card to get or which has the best sign-up bonus. It covers only the cards earnrate knows, offers vary by person, and each offer's note gives the issuer's eligibility rules; pass those caveats on. It doesn't account for what a card would earn on the user's spending.",
+        description: "Ranks the public welcome (sign-up) offers on cards the user doesn't have by first-year value: the bonus at the user's point values minus the first year's annual fee and any membership the card needs that the user doesn't have. Offers the issuer rules out because of a card in the user's wallet are marked likely not eligible and listed last. Use it when the user asks which new card to get or which has the best sign-up bonus. It covers only the cards earnrate knows, offers vary by person, and each offer's note gives the issuer's eligibility rules; pass those caveats on. It doesn't account for what a card would earn on the user's spending.",
         inputSchema: z.object({
             ...OfferFilters,
             valuation: CatalogFilters.valuation,
@@ -197,7 +214,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     });
     server.registerTool('simulate_spending', {
         title: 'Simulate a year of spending',
-        description: 'Spends monthly amounts for a year across every card earnrate knows, and ranks single cards and two-card pairs by rewards minus annual fees. Spending is optional: without it, typical U.S. household amounts are used and the answer says so. With `cards` (named in the conversation) or compareToWallet (the saved wallet), it ranks the cards that would add the most to those cards instead. Use it for "which card fits my spending?" or "is it worth adding a card?". It leaves out welcome bonuses.',
+        description: 'Spends monthly amounts for a year across every card earnrate knows, and ranks single cards and two-card pairs by rewards minus annual fees, and minus a membership a card needs (a Costco membership) unless the user has it or spends at Costco. Spending is optional: without it, typical U.S. household amounts are used and the answer says so. With `cards` (named in the conversation) or compareToWallet (the saved wallet), it ranks the cards that would add the most to those cards instead. Use it for "which card fits my spending?" or "is it worth adding a card?". It leaves out welcome bonuses.',
         inputSchema: z.object({
             spending: z
                 .array(z.object({

package/dist/mcp/tools/wallet.js

@@ -1,10 +1,35 @@
 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 { 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 };
+// What update_card changed, so the reply confirms the values it saved.
+function changes(args) {
+    const out = [];
+    for (const [choice, options] of Object.entries(args.picks ?? {}))
+        out.push(`${choiceName(choice)} picks: ${options.map(words).join(', ')}`);
+    if (args.checkoutLabel === null)
+        out.push('checkout name cleared');
+    else if (args.checkoutLabel !== undefined)
+        out.push(`checkout name "${args.checkoutLabel}"`);
+    if (args.anniversary !== undefined)
+        out.push(`anniversary ${args.anniversary}`);
+    if (args.activated !== undefined)
+        out.push(args.activated.length === 0
+            ? 'nothing activated'
+            : `activated: ${args.activated.join(', ')}`);
+    for (const [key, spent] of Object.entries(args.capSpent ?? {}))
+        out.push(`${money(spent)} already spent on ${key} this period`);
+    if (args.bonus === null)
+        out.push('welcome bonus no longer tracked');
+    else if (args.bonus !== undefined)
+        out.push(`welcome bonus tracked from ${args.bonus.opened}, ${money(args.bonus.spent ?? 0)} spent so far`);
+    return out;
+}
 // The tools that read or change a saved wallet.
 export function registerWalletTools(server, deps, ctx, inputs) {
     const { catalog, store } = deps;
@@ -27,7 +52,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('record_purchase', {
         title: 'Record a purchase',
-        description: "Records a purchase the user has already made, so spending caps and welcome-bonus progress stay accurate for future recommendations. It updates the user's saved wallet. Only call it after the purchase has happened, and only once per purchase: calling it twice counts the spend twice. Purchases with no cap and no open welcome bonus are acknowledged and nothing is written.",
+        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.",
         inputSchema: z.object({
             cardId: z
                 .string()
@@ -60,6 +85,8 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             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}`);
@@ -104,11 +131,18 @@ 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 or activated categories. Picks for the current period are merged with the ones already saved. 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+.',
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
         annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
-    }, async (args) => ctx.changed(await store.updateCard(cardInput(args), deps.today()), `Updated ${ctx.cardName(args.cardId)} (${args.cardId}).`));
+    }, async (args) => {
+        const what = changes(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}`);
+    });
     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.",
@@ -118,11 +152,19 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     }, 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. 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.",
         inputSchema: z.object({ memberships: inputs.AllMemberships }),
         outputSchema: WalletChangeSchema,
         annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
-    }, async ({ memberships }) => ctx.changed(await store.setMemberships(memberships), memberships.length > 0
-        ? `Memberships set to ${memberships.join(', ')}.`
-        : 'Memberships cleared.', { notes: false }));
+    }, 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.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 });
+    });
 }

package/dist/schema/card.js

@@ -79,6 +79,9 @@ export const WelcomeOfferSchema = z
     // the page showed different offers on different visits. The amount
     // above is then the most it shows.
     varies: z.literal(true).optional(),
+    // Other cards whose holders the issuer says can't get this offer
+    // (Southwest's personal cards, Blue Cash Everyday with Preferred).
+    not_with: z.array(KebabId).min(1).optional(),
     note: z.string().optional(),
 })
     .refine((o) => (o.points === undefined) !== (o.dollars === undefined), 'a welcome offer needs points or dollars, not both');
@@ -143,6 +146,17 @@ 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(),
     pools_into: z
         .strictObject({
         currency: CurrencyId,

package/dist/schema/wallet.js

@@ -42,7 +42,11 @@ export const WalletCardSchema = z.strictObject({
     })
         .optional(),
 });
+// The wallet file's format. A file without `version` is version 1; bump it
+// when a change would make older earnrate misread newer files.
+export const WALLET_VERSION = 1;
 export const WalletSchema = z.strictObject({
+    version: z.number().int().positive().optional(),
     valuations: z.record(CurrencyId, Valuation).default({}),
     memberships: z.array(KebabId).default([]),
     cards: z.array(WalletCardSchema).min(1),

package/package.json

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

package/wallet.example.yaml

@@ -1,6 +1,7 @@
 # Copy to ~/.earnrate/wallet.yaml (or point $EARNRATE_WALLET at a copy).
 # Valuations default to data/currencies.yaml; set one here only to override it.
 
+version: 1
 valuations:
   sofi-rewards: { redemption: sofi-account }
 memberships: [amazon-prime]