earnrate 0.2.16 → 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(),
@@ -179,6 +181,8 @@ export const WalletSummarySchema = z.object({
             period: CreditPeriod,
             enroll: z.boolean(),
             enrolled: z.boolean(),
+            skipped: z.boolean(), // the user doesn't use it: not counted anywhere
+            confirmed: z.boolean(), // said in use: counts against the annual fee
             currentPeriod: z.string().nullable(),
             until: z.string().nullable(),
             used: z.number(),
@@ -186,6 +190,8 @@ export const WalletSummarySchema = z.object({
             tracked: z.boolean(),
             text: z.string(),
         })),
+        usedCredits: z.number(), // a year, counted against the annual fee
+        usedCreditsText: z.string().nullable(),
         chosen: z
             .object({
             period: z.string(),
@@ -282,11 +288,28 @@ export const OfferComparisonSchema = z.object({
         ineligible: z.string().nullable(),
         bonusValue: z.number(),
         firstYearValue: z.number(),
+        // Statement credits, a year at face value, and the first-year value
+        // 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({
@@ -312,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(),
         })),
@@ -381,6 +405,7 @@ export const ExplorationSchema = z.object({
         enroll: z.boolean(),
         note: z.string().nullable(),
         back: z.string(),
+        terms: z.string(),
         earn: z.string(),
         text: z.string(),
         evidence: z.object({ quote: z.string(), url: z.string() }).nullable(),
@@ -397,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(),
@@ -418,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 })),
@@ -431,7 +464,19 @@ const SimulationSchema = z.object({
         cardIds: z.array(z.string()),
     })),
     membershipFees: z.number(),
+    // Credits the user uses on cards they hold, a year: counted in net.
+    heldCredits: z.number(),
     net: z.number(),
+    // Credits on cards not held, a year at face value: not in net.
+    otherCredits: z.number(),
+    netIfCreditsUsed: z.number(),
+    credits: z.array(z.object({
+        cardId: z.string(),
+        yearly: z.number(),
+        creditIds: z.array(z.string()),
+        names: z.array(z.string()),
+        held: z.boolean(),
+    })),
     lines: z.array(z.object({
         label: z.string(),
         spend: z.number(),
@@ -459,6 +504,8 @@ export const SpendingSimulationSchema = z.object({
         annualFee: z.number(),
         membershipFee: z.number(),
         gain: z.number(),
+        credits: z.number(), // its statement credits, a year: not in gain
+        gainIfCreditsUsed: z.number(),
     })),
 });
 export const CheatSheetSchema = z.object({

package/dist/mcp/tools/account.js

@@ -57,7 +57,7 @@ export function registerAccountTools(server, catalog, store, ctx) {
     const importWallet = importHandler(catalog, store, ctx);
     server.registerTool('export_wallet', {
         title: 'Export the wallet',
-        description: 'The saved wallet as a wallet.yaml file: card ids, checkout labels, picks, activations, opening dates and anniversaries, memberships, point values, cap usage, welcome-bonus progress, yearly spending toward spend bonuses, and statement credits enrolled in and used. earnrate.dev imports it, and the earnrate command line reads it saved as ~/.earnrate/wallet.yaml. Never card numbers.',
+        description: 'The saved wallet as a wallet.yaml file: card ids, checkout labels, picks, activations, opening dates and anniversaries, memberships, point values, cap usage, welcome-bonus progress, yearly spending toward spend bonuses, and statement credits enrolled in, used and not used. earnrate.dev imports it, and the earnrate command line reads it saved as ~/.earnrate/wallet.yaml. Never card numbers.',
         inputSchema: z.object({}),
         outputSchema: z.object({ yaml: z.string() }),
         annotations: {

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";
@@ -57,6 +57,10 @@ function changes(catalog, args) {
             : `enrolled in: ${args.enrolled.join(', ')}`);
     for (const [id, used] of Object.entries(args.creditUsed ?? {}))
         out.push(`${money(used)} of the ${id} credit used this period`);
+    if (args.skippedCredits !== undefined)
+        out.push(args.skippedCredits.length === 0
+            ? 'every credit counted'
+            : `credits not used: ${args.skippedCredits.join(', ')}`);
     if (args.bonus === null)
         out.push('welcome bonus no longer tracked');
     else if (args.bonus !== undefined)
@@ -183,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}`);
         },
@@ -194,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);
@@ -206,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({
@@ -255,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',
@@ -291,7 +315,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     }, (args) => tools.add_card.run(args));
     server.registerTool('update_card', {
         title: 'Update a card',
-        description: `Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, opening date (optional; for first-year rates), activated categories, cap spending so far (capSpent), spending this year toward its spend bonuses (milestoneSpent), statement credits enrolled in (enrolled) and used this period (creditUsed), or a welcome bonus to track. Picks replace the saved ones in each choice group you set (other groups are kept) for the current period. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+. ${ctx.walletUse}`,
+        description: `Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, opening date (optional; for first-year rates), activated categories, cap spending so far (capSpent), spending this year toward its spend bonuses (milestoneSpent), statement credits enrolled in (enrolled), used this period (creditUsed) or not used at all (skippedCredits), 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: tools.update_card.input,
         outputSchema: WalletChangeSchema,
         annotations: {
@@ -315,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

@@ -23,6 +23,9 @@ export const MilestoneSchema = z
     period: z.enum(['calendar_year', 'cardmember_year']),
     points: z.number().positive().optional(), // in the card's currency
     rewards: z.array(z.string().min(1)).min(1).optional(),
+    // The day the issuer starts it, for one announced ahead: spending counts
+    // from then.
+    valid_from: IsoDate.optional(),
     note: z.string().optional(),
 })
     .refine((m) => m.points !== undefined || m.rewards !== undefined, 'a milestone needs points, rewards or both');
@@ -76,6 +79,9 @@ export const RuleSchema = z
     geography: z
         .enum(['us_only', 'foreign_only', 'worldwide'])
         .default('worldwide'),
+    // Only a purchase of at least this many dollars. Unknown without an
+    // amount, so then it never applies by assumption.
+    min_amount: z.number().positive().optional(),
     // Inline cap, or the id of a shared cap in the card's `caps`.
     cap: z.union([CapSchema, KebabId]).optional(),
     requires: z
@@ -123,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
@@ -186,6 +196,11 @@ export const CreditSchema = z.strictObject({
     period: CreditPeriod,
     // The cardholder must enroll with the issuer before it pays.
     enroll: z.literal(true).optional(),
+    // It pays only on a purchase of at least this many dollars.
+    min_amount: z.number().positive().optional(),
+    // The issuer's last day for it. Past it the credit counts nowhere, and a
+    // year's worth counts only the periods that start by then.
+    valid_to: IsoDate.optional(),
     note: z.string().optional(),
 });
 const HexColor = z.string().regex(/^#[0-9a-f]{6}$/);
@@ -243,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}$/)
@@ -46,10 +47,14 @@ export const WalletCardSchema = z.strictObject({
     activated: z.array(KebabId).default([]),
     // Keyed by milestone id: every purchase on the card this period.
     milestone_usage: z.record(KebabId, CapUsage).optional(),
-    // Merchant credits (the card's `credits`) the cardholder has enrolled in,
-    // by credit id, and the dollars of each credit already received this period.
+    // Merchant credits (the card's `credits`) the cardholder has enrolled in
+    // or, for ones that need no enrolling, says they use, by credit id; and
+    // the dollars of each credit already received this period.
     enrolled: z.array(KebabId).optional(),
     credit_usage: z.record(KebabId, CreditUsage).optional(),
+    // Credits the cardholder doesn't use: left out of the pick, the to-do
+    // list and the fee math, even if enrolled.
+    skipped_credits: z.array(KebabId).optional(),
     // A welcome bonus in progress. Terms default to the card's published
     // offer; set spend, by, points or dollars when yours was different.
     bonus: z
@@ -70,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.16",
+  "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",