earnrate 0.2.2 → 0.2.4

package/dist/mcp/inputs.js

@@ -120,11 +120,11 @@ export function makeInputs(catalog) {
         .array(NamedCard)
         .optional()
         .describe("Cards the user named in this conversation, to answer for just those cards without saving anything. Leave out to use the user's saved wallet if they have one; with neither, the answer covers every card earnrate knows.");
-    const NamedMemberships = Memberships.optional().describe("Memberships the user has, such as amazon-prime, when they're named in the conversation rather than saved.");
+    const NamedMemberships = Memberships.optional().describe("Memberships the user has, such as amazon-prime or costco, when they're named in the conversation rather than saved.");
     const CatalogFilters = {
         ...OfferFilters,
         issuer: z.enum(issuers).optional().describe("Only this issuer's cards."),
-        memberships: Memberships.optional().describe("Memberships the user has, such as amazon-prime. Rates that need one they don't have are listed separately."),
+        memberships: Memberships.optional().describe("Memberships the user has, such as amazon-prime or costco. Rates that need one they don't have are listed separately; a card that needs one (Costco Anywhere) says so."),
         valuation: z
             .enum(['flat', 'points-heavy'])
             .optional()

package/dist/mcp/schemas.js

@@ -106,6 +106,7 @@ export const WalletSummarySchema = z.object({
         rotationGap: z.string().nullable(),
         caps: z.array(z.object({
             key: z.string(),
+            label: z.string(),
             rules: z.array(z.string()),
             amount: z.number(),
             period: CapPeriod,
@@ -117,10 +118,14 @@ export const WalletSummarySchema = z.object({
             .object({
             period: z.string(),
             current: z.boolean(),
+            until: z.string().nullable(),
             picks: z.record(z.string(), z.array(z.string())),
+            pickNames: z.record(z.string(), z.array(z.string())),
         })
             .nullable(),
+        rates: z.array(z.string()),
         activated: z.array(z.string()),
+        toActivate: z.array(z.string()),
         anniversary: z.string().nullable(),
     })),
 });
@@ -165,6 +170,8 @@ export const OfferComparisonSchema = z.object({
         note: z.string().nullable(),
         annualFee: z.number().nullable(),
         firstYearFee: z.number().nullable(),
+        membershipFee: z.number(),
+        ineligible: z.string().nullable(),
         bonusValue: z.number(),
         firstYearValue: z.number(),
         held: z.boolean(),
@@ -199,6 +206,9 @@ export const CardSearchSchema = z.object({
             default: z.array(z.string()).nullable(),
         })),
         memberships: z.array(z.string()),
+        requiresMembership: z
+            .object({ id: z.string(), name: z.string(), annualFee: z.number() })
+            .nullable(),
         activation: z.array(z.string()),
         needsAnniversary: z.boolean(),
     })),
@@ -267,6 +277,13 @@ const SimulationSchema = z.object({
     spend: z.number(),
     rewards: z.number(),
     annualFees: z.number(),
+    memberships: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        annualFee: z.number(),
+        cardIds: z.array(z.string()),
+    })),
+    membershipFees: z.number(),
     net: z.number(),
     lines: z.array(z.object({
         label: z.string(),
@@ -287,6 +304,7 @@ export const SpendingSimulationSchema = z.object({
         picks: Picks,
         extraRewards: z.number(),
         annualFee: z.number(),
+        membershipFee: z.number(),
         gain: z.number(),
     })),
 });

package/dist/mcp/server.js

@@ -15,8 +15,7 @@ export const ANSWER_TOOLS = [
     'resolve_merchant',
     'search_cards',
 ];
-// The tools that read or change a saved wallet. The hosted server asks for
-// sign-in before running one.
+// The tools that read or change a saved wallet.
 export const SAVED_WALLET_TOOLS = [
     'list_wallet',
     'record_purchase',
@@ -27,10 +26,11 @@ export const SAVED_WALLET_TOOLS = [
     'export_wallet',
     'import_wallet',
     'delete_wallet',
+    'switch_wallet',
 ];
 const SAVING = {
     file: 'Only if they want earnrate to remember their cards, track spending caps or welcome bonuses, or record purchases, save a wallet with add_card and the other wallet tools.',
-    account: "Only if they want earnrate to remember their cards, track spending caps or welcome bonuses, or record purchases, save a wallet with add_card and the other wallet tools. Saved wallets are anonymous: the first wallet tool asks the user to open an earnrate page, where they start a wallet (it shows a recovery code to keep; no email or name) or reconnect one with their code. Never ask for the recovery code in the conversation; it's typed only on that page. To change the code, the user opens https://mcp.earnrate.dev/change-code.",
+    account: "The user signed in to earnrate when they connected it, to an anonymous saved wallet (no email or name). It may have no cards yet; answers then cover every card. Save cards with add_card only when the user agrees. The wallet can change outside this conversation when the user signs in again on earnrate's page, so read it with list_wallet rather than from memory. To use a different wallet or start a new one, call switch_wallet; the user then connects on earnrate's page with that wallet's recovery code. Never ask for the recovery code in the conversation; it's typed only on earnrate's page. To change the code, the user opens https://mcp.earnrate.dev/change-code. earnrate.dev and the earnrate command line keep their own separate wallets; export_wallet and import_wallet move one between them.",
 };
 const instructions = (savedWallets) => `earnrate answers which credit card earns the most for a purchase, from each issuer's own terms. Anyone can use it without entering anything: with no cards given, best_card_for_purchase, best_cards_for, cheat_sheet, simulate_spending and compare_welcome_offers answer from every card earnrate knows, and that's a complete answer. Never require the user's cards, and don't ask what they spend unless the answer depends on it; simulate_spending assumes typical amounts when none are given and says so.
 

package/dist/mcp/tools/account.js

@@ -46,16 +46,36 @@ export function registerAccountTools(server, catalog, store, ctx) {
         const parsed = parseWalletYaml(yaml, catalog);
         if (typeof parsed === 'string')
             return fail(parsed);
-        const current = await store.load().catch(() => null);
+        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;
+        }
         if (current !== null && current.cards.length > 0 && replace !== true)
             return fail(`This would replace the ${String(current.cards.length)} ${current.cards.length === 1 ? 'card' : 'cards'} already saved (${current.cards.map((c) => c.id).join(', ')}). Ask the user, then call again with replace: true.`);
-        const count = parsed.cards.length;
-        return ctx.changed(await store.replace(parsed), `Imported a wallet with ${String(count)} ${count === 1 ? 'card' : 'cards'}.`, { notes: false });
+        const cards = (n) => `${String(n)} ${n === 1 ? 'card' : 'cards'}`;
+        const before = current?.cards.length ?? 0;
+        return ctx.changed(await store.replace(parsed), before > 0
+            ? `Replaced the ${cards(before)} that were saved with the ${cards(parsed.cards.length)} imported.`
+            : `Imported a wallet with ${cards(parsed.cards.length)}.`, { notes: false });
     });
     server.registerTool('delete_wallet', {
         title: 'Delete the wallet',
-        description: 'Deletes the saved wallet now and for good, and signs out every app using it. Only when the user asks to delete it; confirm first, and offer export_wallet to keep a copy.',
-        inputSchema: z.object({}),
+        description: "Deletes the saved wallet and its recovery code now and for good, and signs out every Claude 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 and cards only after the user confirms. It refuses if the wallet no longer holds that many cards, so a retried call can't delete a different wallet.",
+        inputSchema: z.object({
+            confirm: z
+                .literal(true)
+                .describe('true, only after the user confirms the deletion.'),
+            cards: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe('How many cards the wallet held when the user confirmed, from list_wallet: 0 for an empty wallet.'),
+        }),
         outputSchema: z.object({ deleted: z.boolean() }),
         annotations: {
             readOnlyHint: false,
@@ -63,16 +83,44 @@ export function registerAccountTools(server, catalog, store, ctx) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async () => {
+    }, async ({ cards }) => {
+        // An unreadable wallet can still be deleted: the user confirmed it.
+        const current = await store.load().catch(() => undefined);
+        const held = current === undefined ? cards : (current?.cards.length ?? 0);
+        if (held !== cards)
+            return fail(`This saved wallet holds ${String(held)} ${held === 1 ? 'card' : 'cards'}, not ${String(cards)}, so it isn't the wallet the user confirmed (it may have been deleted and a new one connected). Show it with list_wallet and confirm again.`);
         await store.erase();
         return {
             content: [
                 {
                     type: 'text',
-                    text: 'Deleted the saved wallet. Answers now cover every card, or the cards named in the conversation.',
+                    text: "Deleted the saved wallet and its recovery code, and signed out every Claude app connected to it, this one included. To keep using earnrate here, the user connects again on earnrate's page and starts a new wallet.",
                 },
             ],
             structuredContent: { deleted: true },
         };
     });
+    server.registerTool('switch_wallet', {
+        title: 'Switch wallets',
+        description: "Disconnects this app from its saved wallet so the user can connect a different one with its recovery code, or start a new one, on earnrate's page. Nothing is deleted. It also signs out anyone else connected to this wallet through the same app (another Claude account the recovery code was shared with): say so before calling it. Use it when the user wants another wallet. Never ask for the recovery code in the conversation.",
+        inputSchema: z.object({}),
+        outputSchema: z.object({ disconnected: z.boolean() }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        await store.disconnect();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: "Disconnected from this saved wallet; nothing was deleted. earnrate's sign-in page opens on the next earnrate request (or reconnect earnrate in the app's connector settings). There the user chooses \"Already have a wallet?\" and types the other wallet's recovery code, or starts a new wallet. Other Claude accounts connected to this wallet through the same app are signed out too.",
+                },
+            ],
+            structuredContent: { disconnected: true },
+        };
+    });
 }

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.2",
+  "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]