earnrate 0.2.17 → 0.2.18

package/dist/mcp/schemas.js

@@ -96,6 +96,7 @@ const RecommendationSchema = z.object({
 export const WalletSummarySchema = z.object({
     memberships: z.array(z.string()),
     membershipNames: z.array(z.string()),
+    skippedIssuers: z.array(z.object({ id: z.string(), name: z.string() })),
     pointValues: z.array(z.object({
         currency: z.string(),
         name: z.string(),
@@ -115,6 +116,7 @@ export const WalletSummarySchema = z.object({
             'intro',
             'credit',
             'enroll',
+            'renewal',
         ]),
         cardId: z.string(),
         ref: z.string().optional(),
@@ -290,11 +292,24 @@ export const OfferComparisonSchema = z.object({
         // if all were used. Not ranked on.
         credits: z.number(),
         firstYearValueIfCreditsUsed: z.number(),
+        // On the user's spending beside their cards; null for a card they hold.
+        plan: z
+            .object({
+            extraRewards: z.number(),
+            minimumSpend: z
+                .object({ reachable: z.boolean(), weeks: z.number() })
+                .nullable(),
+            yearOne: z.number(),
+            yearTwo: z.number(),
+            twoYears: z.number(),
+        })
+            .nullable(),
         held: z.boolean(),
         lastVerified: z.string(),
         verifiedBy: z.string(),
     })),
     withoutOffer: z.array(z.string()),
+    typical: z.boolean(),
     notes: z.array(z.string()),
 });
 export const CardSearchSchema = z.object({
@@ -320,6 +335,7 @@ export const CardSearchSchema = z.object({
                 'calendar_year',
                 'until_changed',
             ]),
+            automatic: z.boolean(),
             options: z.array(z.string()),
             default: z.array(z.string()).nullable(),
         })),
@@ -406,6 +422,7 @@ export const ExplorationSchema = z.object({
                 choice: z.string(),
                 options: z.array(z.string()),
                 period: z.string(),
+                automatic: z.boolean(),
             })
                 .nullable(),
             activation: z.string().nullable(),
@@ -427,6 +444,13 @@ export const ExplorationSchema = z.object({
     excluded: z.array(ExcludedCardSchema),
     assumptions: z.array(z.string()),
     warnings: z.array(z.string()),
+    // Ways of paying that would put a card at the top, when payment is unknown.
+    ifPaying: z.array(z.object({
+        cardId: z.string(),
+        cardName: z.string(),
+        payment: z.string(),
+        earn: z.string(),
+    })),
 });
 const SimulationSchema = z.object({
     cards: z.array(z.object({ cardId: z.string(), picks: Picks })),

package/dist/mcp/tools/answers.js

@@ -31,7 +31,7 @@ const TOP = 10;
 // named in the conversation, or a saved wallet if there is one.
 export function registerAnswerTools(server, deps, ctx, inputs) {
     const { catalog } = deps;
-    const { CategoryInput, CatalogCategory, NamedCards, NamedMemberships, OfferFilters, CatalogFilters, } = inputs;
+    const { CategoryInput, CatalogCategory, NamedCards, NamedMemberships, OfferFilters, CatalogFilters, SkippedIssuers, } = inputs;
     server.registerTool('best_card_for_purchase', {
         title: 'Best card for a purchase',
         description: "Which credit 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. When the user is paying outside the U.S. or in another currency, pass `country`: abroad, each card is ranked after its foreign transaction fee. Pass `payment` only when the user says how they're paying, like Apple Pay or PayPal checkout. A statement credit (a card's `credit`, like Amex Platinum's lululemon credit) counts toward the pick only once it's enrolled in the wallet and has dollars left this period, and only when the amount is given; say its dollars apart from the % back. With no cards, `allCards.credits` lists cards with a credit at the store; present those first. Never needs or returns card numbers.",
@@ -155,9 +155,34 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             structuredContent: m,
         };
     });
+    const SpendingLines = z
+        .array(z.object({
+        merchant: Merchant.optional(),
+        category: CatalogCategory.optional(),
+        monthly: z.number().positive().describe('US dollars a month.'),
+    }))
+        .optional()
+        .describe("Monthly spending lines, each a category (grocery.supermarket, dining, gas, other) or a merchant (Amazon, Costco). Optional: leave out to use typical amounts, and don't press the user for numbers they haven't offered.");
+    // Spending lines as given, or typical amounts; a string is why they can't
+    // be used.
+    const spendingFrom = (given) => {
+        if (given.some((l) => l.merchant === undefined && l.category === undefined))
+            return 'Each spending line needs a merchant or a category.';
+        const lines = given.length === 0
+            ? typicalSpendLines(catalog)
+            : resolveSpendLines(catalog, given.map((l) => ({
+                merchant: l.merchant ?? null,
+                category: l.merchant === undefined ? (l.category ?? null) : null,
+                monthly: l.monthly,
+            })));
+        const unknown = lines.filter((l) => l.merchant.source === 'none');
+        if (unknown.length > 0)
+            return `earnrate doesn't know ${unknown.map((l) => `"${l.merchant.input}"`).join(', ')}. Give a category for those lines instead.`;
+        return { lines, typical: given.length === 0 };
+    };
     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 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.",
+        description: "Ranks cards the user doesn't have by what they'd be worth over the first two years: what each adds to the user's cards (or, with none, earns) on their spending, plus the public welcome (sign-up) bonus in year one if its minimum spend fits in the window, less each year's annual fee and any membership it needs. Each offer also shows the bonus alone (first-year value), year one and year two, and how many weeks of spending the minimum takes. Offers the issuer rules out because of a card in the user's wallet are marked likely not eligible and listed last; issuers the user can't get cards from (skippedIssuers, or saved with set_memberships) are left out. Use it when the user asks which card to get next or which has the best sign-up bonus. Spending is optional (typical amounts otherwise). 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. Never suggest applying through a link.",
         inputSchema: z.object({
             ...OfferFilters,
             valuation: CatalogFilters.valuation,
@@ -167,6 +192,8 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 .describe('Include cards already in the wallet.'),
             cards: NamedCards,
             memberships: NamedMemberships,
+            spending: SpendingLines,
+            skippedIssuers: SkippedIssuers.optional().describe("Issuers the user says they can't or won't get a new card from (for example Chase, over its 5/24 rule), for this answer. Replaces the saved list. Never assume it."),
         }),
         outputSchema: OfferComparisonSchema,
         annotations: {
@@ -180,15 +207,21 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         if (typeof wallet === 'string')
             return fail(wallet);
         const found = wallet ?? { ...EMPTY_WALLET, ...(await ctx.saved()) };
-        const base = args.memberships
+        const spending = spendingFrom(args.spending ?? []);
+        if (typeof spending === 'string')
+            return fail(spending);
+        const withMembers = args.memberships
             ? { ...found, memberships: args.memberships }
             : found;
+        const base = args.skippedIssuers
+            ? { ...withMembers, skipped_issuers: args.skippedIssuers }
+            : withMembers;
         const comparison = compareOffers(catalog, args.valuation ? withValuationProfile(base, args.valuation) : base, {
             kind: args.kind ?? 'any',
             noAnnualFee: args.noAnnualFee ?? false,
             business: args.business ?? false,
             includeHeld: args.includeHeld ?? false,
-        }, deps.today());
+        }, deps.today(), spending);
         const trimmed = {
             ...comparison,
             // Offers ruled out by a card the user holds sort last; keep them in
@@ -260,14 +293,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         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, 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({
-                merchant: Merchant.optional(),
-                category: CatalogCategory.optional(),
-                monthly: z.number().positive().describe('US dollars a month.'),
-            }))
-                .optional()
-                .describe("Monthly spending lines, each a category (grocery.supermarket, dining, gas, other) or a merchant (Amazon, Costco). Optional: leave out to use typical amounts, and don't press the user for numbers they haven't offered."),
+            spending: SpendingLines,
             cards: NamedCards,
             compareToWallet: z
                 .boolean()
@@ -284,18 +310,10 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         },
     }, async (args) => {
         const given = args.spending ?? [];
-        if (given.some((l) => l.merchant === undefined && l.category === undefined))
-            return fail('Each spending line needs a merchant or a category.');
-        const lines = given.length === 0
-            ? typicalSpendLines(catalog)
-            : resolveSpendLines(catalog, given.map((l) => ({
-                merchant: l.merchant ?? null,
-                category: l.merchant === undefined ? (l.category ?? null) : null,
-                monthly: l.monthly,
-            })));
-        const unknown = lines.filter((l) => l.merchant.source === 'none');
-        if (unknown.length > 0)
-            return fail(`earnrate doesn't know ${unknown.map((l) => `"${l.merchant.input}"`).join(', ')}. Give a category for those lines instead.`);
+        const spending = spendingFrom(given);
+        if (typeof spending === 'string')
+            return fail(spending);
+        const { lines } = spending;
         const notes = given.length === 0 ? [TYPICAL_SPEND_NOTE] : [];
         const options = {
             ...settings(args, await ctx.saved()),

package/dist/mcp/tools/wallet.js

@@ -7,7 +7,7 @@ import { optionName } from "../../engine/rule-text.js";
 import { currencyChanges } from "../../engine/wallet-change.js";
 import { walletSummary } from "../../engine/wallet-summary.js";
 import { checklist } from "../../engine/checklist.js";
-import { cardText } from "../../format/card-text.js";
+import { cardText, issuerName } from "../../format/card-text.js";
 import { formatBooking, formatChecklist, formatWalletSummary, } from "../../format/wallet.js";
 import { fail } from "../context.js";
 import { CardChange, CardId, cardInput, ChannelInput, DateInput, Merchant, } from "../inputs.js";
@@ -187,8 +187,11 @@ export function walletHandlers(deps, ctx, inputs) {
         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."
+            const unused = args.anniversary !== undefined &&
+                card &&
+                !needsAnniversary(card) &&
+                (card.annual_fee ?? 0) === 0
+                ? " It has no annual fee and 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}`);
         },
@@ -198,10 +201,27 @@ export function walletHandlers(deps, ctx, inputs) {
         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 MembershipsInput = z.object({
+        memberships: inputs.AllMemberships.optional(),
+        skippedIssuers: inputs.SkippedIssuers.optional().describe("Issuers the user says they can't or won't get a new card from (for example Chase, over its 5/24 rule): left out of compare_welcome_offers and of the cards that would add the most. Replaces the saved list; [] clears it. Ask; never assume."),
+    });
     const setMemberships = {
         input: MembershipsInput,
-        run: async ({ memberships }) => {
+        run: async ({ memberships, skippedIssuers }) => {
+            if (memberships === undefined && skippedIssuers === undefined)
+                return fail('Give memberships, skippedIssuers or both.');
+            let skipText = '';
+            if (skippedIssuers !== undefined) {
+                const skipped = await store.setSkippedIssuers(skippedIssuers);
+                skipText =
+                    skippedIssuers.length > 0
+                        ? `Next-card answers now leave out ${listed(skippedIssuers.map((i) => issuerName(catalog, i)))}.`
+                        : 'Next-card answers include every issuer again.';
+                if (memberships === undefined || !skipped.ok)
+                    return ctx.changed(skipped, skipText, { notes: false });
+            }
+            if (memberships === undefined)
+                return fail('Give 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);
@@ -210,7 +230,7 @@ export function walletHandlers(deps, ctx, inputs) {
             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 });
+                : 'Memberships cleared.'}${skipText === '' ? '' : ` ${skipText}`}${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({
@@ -259,7 +279,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     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}`,
+        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, and a fee card's renewal check in the month before its anniversary: whether it still pays for itself at typical spending); 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}`,
         outputSchema: WalletSummarySchema,
         annotations: {
             title: 'List wallet',
@@ -319,7 +339,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     }, (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}`,
+        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. With skippedIssuers, it also saves the issuers the user can't or won't get a new card from (Chase over its 5/24 rule), which next-card answers leave out; either can be given alone. ${ctx.walletUse}`,
         inputSchema: tools.set_memberships.input,
         outputSchema: WalletChangeSchema,
         annotations: {

package/dist/schema/card.js

@@ -129,6 +129,10 @@ export const ChoiceSchema = z.strictObject({
     // `until_changed`: the pick carries over until the cardholder changes it,
     // so a pick made in an earlier period is still current.
     period: z.enum(['month', 'quarter', 'calendar_year', 'until_changed']),
+    // The issuer applies the bonus to the options with the most spending each
+    // period (Citi Custom Cash). A wallet's pick is the one the cardholder
+    // expects, and wording never says the cardholder picks.
+    automatic: z.literal(true).optional(),
     // Option ids that apply when the wallet hasn't picked, e.g. Bilt's dining.
     default: z.array(KebabId).min(1).optional(),
     // Option id → what that option covers: a list of categories; or, when the
@@ -254,6 +258,9 @@ export const CardSchema = z
         rule: z.string().min(1),
         url: z.url(),
         quote: z.string().min(1),
+        // Set only after seeing the quote in a popup the page builds on
+        // click from its embedded data; other quotes must be in its text.
+        in_popup: z.literal(true).optional(),
     }))
         .default([]),
     // Known gaps in this file, surfaced as warnings.

package/dist/schema/changes.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { CategoryId, CurrencyId, IsoDate, KebabId } from "./common.js";
+// Only `issuer` means the issuer changed its terms, and only after earnrate
+// had recorded the old value correctly. A term earnrate starts recording
+// late is an `addition`, so earnrate's own work never reads as a rate cut.
+export const ChangeCause = z.enum([
+    'issuer',
+    'correction',
+    'addition',
+    'wording',
+    'quote',
+    'review',
+]);
+export const CHANGE_SUBJECTS = [
+    'cards',
+    'merchants',
+    'categories',
+    'currencies',
+    'memberships',
+    'issuers',
+];
+export const DATA_VERSION = /^(\d{4})\.(\d{2})\.(\d{2})(\.\d+)?$/;
+const ids = z.array(KebabId).min(1);
+export const ChangeSchema = z
+    .strictObject({
+    cause: ChangeCause,
+    card: KebabId.optional(),
+    cards: ids.optional(),
+    merchants: ids.optional(),
+    categories: z.array(CategoryId).min(1).optional(),
+    currencies: z.array(CurrencyId).min(1).optional(),
+    memberships: ids.optional(),
+    issuers: ids.optional(),
+    // A path in each subject: `welcome_offer`, `rules.amazon`,
+    // `credits.instacart.valid_to`. List items are found by their id.
+    // Without one, the change is to the whole subject (a new card).
+    field: z
+        .string()
+        .regex(/^[a-z_]+(\.[a-z0-9_-]+)*$/)
+        .optional(),
+    // The field's value before and after, as written in the data file.
+    // `was: null` means it didn't exist; `now: null` means it was removed.
+    was: z.unknown().optional(),
+    now: z.unknown().optional(),
+    summary: z.string().min(1).optional(),
+    source: z.url().optional(),
+    // When the change reached the data, if before its release's date.
+    date: IsoDate.optional(),
+    // Issuer changes: when the source check or a person first saw it, and
+    // when the issuer says it took effect. Left out when not known.
+    detected: IsoDate.optional(),
+    effective: IsoDate.optional(),
+})
+    .transform(({ card, ...change }) => card === undefined ? change : { ...change, cards: [card] })
+    .refine((c) => CHANGE_SUBJECTS.filter((s) => c[s] !== undefined).length === 1, 'a change names one kind of subject: card(s), merchants, categories, currencies, memberships or issuers')
+    .refine((c) => c.cause !== 'issuer' ||
+    (c.cards?.length === 1 &&
+        c.field !== undefined &&
+        c.was !== undefined &&
+        c.now !== undefined &&
+        c.source !== undefined), 'an issuer change needs one card, a field, was, now and source')
+    .refine((c) => c.cause === 'issuer' || c.summary !== undefined, "earnrate's own changes need a summary")
+    .refine((c) => c.cause === 'issuer' ||
+    (c.detected === undefined && c.effective === undefined), 'detected and effective are for issuer changes');
+export const ReleaseSchema = z
+    .strictObject({
+    version: z.string().regex(DATA_VERSION),
+    date: IsoDate,
+    changes: z.array(ChangeSchema).min(1),
+})
+    .refine((r) => r.date === r.version.slice(0, 10).replaceAll('.', '-'), "a release's date is its version's date");
+// Newest release first, like data/CHANGELOG.md.
+export const ChangesFileSchema = z.array(ReleaseSchema).min(1);

package/dist/schema/wallet.js

@@ -27,7 +27,8 @@ export const WalletCardSchema = z.strictObject({
         .min(1)
         .refine((t) => !labelHasCardNumber(t), CARD_NUMBER_LABEL)
         .optional(),
-    // MM-DD, needed only for cardmember_year caps.
+    // MM-DD: for cardmember_year caps and a fee card's renewal check. The
+    // opening date stands in for the renewal check when this isn't set.
     anniversary: z
         .string()
         .regex(/^\d{2}-\d{2}$/)
@@ -74,5 +75,8 @@ export const WalletSchema = z.strictObject({
     version: z.number().int().positive().optional(),
     valuations: z.record(CurrencyId, Valuation).default({}),
     memberships: z.array(KebabId).default([]),
+    // Issuers whose new cards the person can't or won't get (Chase over
+    // 5/24): left out of next-card answers. Never assumed.
+    skipped_issuers: z.array(KebabId).optional(),
     cards: z.array(WalletCardSchema).default([]),
 });

package/package.json

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