earnrate 0.2.12 → 0.2.13

package/dist/engine/text.js

@@ -101,6 +101,32 @@ export const NETWORK_NAMES = {
     discover: 'Discover',
     store: 'store card',
 };
+// How a purchase is paid, mid-sentence: "2% cash back with Apple Pay".
+export const PAYMENT_PHRASES = {
+    card: 'with the card itself',
+    'apple-pay': 'with Apple Pay',
+    'google-pay': 'with Google Pay',
+    paypal: 'through PayPal checkout',
+};
+export const paidText = (payment) => `Counts this as paid ${PAYMENT_PHRASES[payment]}, as you said.`;
+export const paymentUnknownText = (name, payment, earn, standard) => `${capitalize(PAYMENT_PHRASES[payment])}, ${name} would earn ${earn} here, instead of the ${standard} it's ranked at. Say how you're paying to count it.`;
+// For answers that never ask how each purchase is paid (cheat sheets and
+// simulations): which cards' rates that need a way of paying are left out.
+export function paymentNote(cards) {
+    const payments = new Set();
+    const names = [];
+    for (const { name, card } of cards) {
+        const needs = card.rules.flatMap((r) => r.requires?.payment === undefined ? [] : [r.requires.payment]);
+        if (needs.length === 0)
+            continue;
+        names.push(name);
+        for (const p of needs)
+            payments.add(p);
+    }
+    if (names.length === 0)
+        return null;
+    return `Rates ${listed([...payments].map((p) => PAYMENT_PHRASES[p]), 'or')} (${listed(names)}) aren't counted: this ranks each card by what it earns however you pay.`;
+}
 // A name with its own "and" ("drugstores and pharmacies") would run into the
 // list's: those lists use commas only, with those names last.
 export const listed = (parts, joiner = 'and') => {
@@ -162,3 +188,61 @@ export const introRateText = (earn, standard, days, until) => `${earn} in your $
 // For a card whose opening date isn't known: it's never assumed to be new.
 export const introUnknownText = (name, earn, standard, days) => `A ${introAdjective(days)} rate may apply on ${name}: ${earn} here in an account's ${introPeriod(days)}, instead of the ${standard} it's ranked at. Give the card's opening date if it opened ${introSince(days)}.`;
 export const introEndsText = (name, days, until) => `${name}'s ${introAdjective(days)} rate ends after ${shortDate(until)}; from then on it earns its standard rates.`;
+// Merchant statement credits. Always dollars, never a percentage.
+export const CREDIT_PERIODS = {
+    month: 'each month',
+    quarter: 'each quarter',
+    half_year: 'each half year',
+    calendar_year: 'each calendar year',
+    cardmember_year: 'each cardmember year',
+};
+export const CREDIT_THIS_PERIOD = {
+    month: 'this month',
+    quarter: 'this quarter',
+    half_year: 'this half year',
+    calendar_year: 'this year',
+    cardmember_year: 'this cardmember year',
+};
+export const ENROLL_FIRST = 'enroll first';
+// The group of cards with a credit at the store, shown before the ranking.
+export const CREDIT_GROUP = 'With a store credit';
+// "$75 back each quarter"
+export const creditBack = (c) => `${money(c.amount)} back ${CREDIT_PERIODS[c.period]}`;
+// "$75 back each quarter, then 1x Amex Membership Rewards"
+export const creditThen = (c, earn) => `${creditBack(c)}, then ${earn}`;
+// "$35 left this quarter"
+export const creditLeft = (left, period) => `${money(left)} left ${CREDIT_THIS_PERIOD[period]}`;
+// A line for an answer that uses the card's credit, or says why it doesn't.
+export function creditAnswerText(c, dollars) {
+    const credit = `${c.name} credit (${creditBack(c)})`;
+    if (!c.enrolled)
+        return `Has a ${credit} here; ${ENROLL_FIRST} with the issuer, then mark it enrolled in your wallet. It isn't counted until then.`;
+    if (c.left === null)
+        return `Has a ${credit} here; give the card's anniversary to track it.`;
+    if (c.left <= 0)
+        return `Its ${c.name} credit is used up ${CREDIT_THIS_PERIOD[c.period]}${c.until === null ? '' : `; it renews after ${shortDate(c.until)}`}.`;
+    if (dollars === null)
+        return `Its ${credit} has ${creditLeft(c.left, c.period)}; give the amount to count it.`;
+    return dollars < c.left
+        ? `${money(dollars)} back from its ${credit}, on top of what it earns; ${creditLeft(roundCents(c.left - dollars), c.period)} after this.`
+        : `${money(dollars)} back from its ${credit}: all that's left ${CREDIT_THIS_PERIOD[c.period]}, on top of what it earns.`;
+}
+// One short line beside a ranked card: "+ $35 back from its Lululemon
+// credit", "Lululemon credit: $35 left this quarter".
+export function creditShort(c, dollars) {
+    if (!c.enrolled)
+        return `${c.name} credit: ${creditBack(c)}, ${ENROLL_FIRST}`;
+    if (c.left === null)
+        return `${c.name} credit: ${creditBack(c)}`;
+    if (c.left <= 0)
+        return `${c.name} credit used up ${CREDIT_THIS_PERIOD[c.period]}`;
+    if (dollars === null || dollars <= 0)
+        return `${c.name} credit: ${creditLeft(c.left, c.period)}`;
+    return `+ ${money(dollars)} back from its ${c.name} credit`;
+}
+// For the to-do list: "Use your $75 lululemon credit on Amex Platinum by Dec
+// 31, 2026: $35 left."
+export const useCreditText = (card, c, left) => `Use your ${money(c.amount)} ${c.name} credit on ${card}${c.until === null ? '' : ` by ${shortDate(c.until)}`}: ${money(left)} left.`;
+export const enrollCreditText = (card, name) => `Enroll in ${card}'s ${name} credit with the issuer, then mark it enrolled.`;
+// Simulations, the cheat sheet and welcome-offer comparisons.
+export const CREDITS_LEFT_OUT = 'Merchant statement credits (dollars back at a named store) are left out.';

package/dist/engine/wallet-change.js

@@ -4,7 +4,7 @@ import { addMonths } from "./bonus.js";
 import { capByKey } from "./evaluate.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
-import { idList } from "./text.js";
+import { CREDIT_PERIODS, idList, money } from "./text.js";
 const failed = (error) => ({ ok: false, error });
 function findCatalogCard(catalog, id, today) {
     const card = catalog.cards.find((c) => c.id === id);
@@ -149,6 +149,40 @@ export function cardFields(card, held, input, today) {
         }
         fields.milestone_usage = usage;
     }
+    if (input.enrolled !== undefined) {
+        const needing = card.credits
+            .filter((c) => c.enroll === true)
+            .map((c) => c.id);
+        for (const id of input.enrolled) {
+            if (!needing.includes(id))
+                problems.push(needing.length > 0
+                    ? `'${id}' isn't a ${card.id} credit that needs enrolling. Those are: ${idList(needing)}.`
+                    : `${card.id} has no credits that need enrolling.`);
+        }
+        fields.enrolled = [...new Set(input.enrolled)];
+    }
+    if (input.creditUsed !== undefined) {
+        const usage = { ...held?.credit_usage };
+        const anniversary = fields.anniversary ?? held?.anniversary ?? null;
+        for (const [id, used] of Object.entries(input.creditUsed)) {
+            const credit = card.credits.find((c) => c.id === id);
+            if (!credit) {
+                problems.push(card.credits.length > 0
+                    ? `${card.id} has no credit '${id}'. Its credits are: ${idList(card.credits.map((c) => c.id))}.`
+                    : `${card.id} has no merchant credits.`);
+                continue;
+            }
+            if (!(used >= 0 && used <= credit.amount))
+                problems.push(`The '${id}' credit is ${money(credit.amount)} ${CREDIT_PERIODS[credit.period]}, so what's used must be $0 to ${money(credit.amount)}.`);
+            const period = periodKey(credit.period, today, anniversary);
+            if (period === null) {
+                problems.push(`The '${id}' credit resets on the card's anniversary; give the anniversary (MM-DD) too.`);
+                continue;
+            }
+            usage[id] = { period, used };
+        }
+        fields.credit_usage = usage;
+    }
     if (input.bonus === null)
         fields.bonus = null;
     else if (input.bonus !== undefined) {
@@ -215,6 +249,8 @@ const withFields = ({ bonus, checkout_label, opened, ...held }, f) => ({
     ...(f.milestone_usage === undefined
         ? {}
         : { milestone_usage: f.milestone_usage }),
+    ...(f.enrolled === undefined ? {} : { enrolled: f.enrolled }),
+    ...(f.credit_usage === undefined ? {} : { credit_usage: f.credit_usage }),
     ...(f.bonus ? { bonus: f.bonus } : {}),
 });
 // `wallet` is null when there isn't one yet; adding a card starts it.

package/dist/engine/wallet-summary.js

@@ -3,12 +3,13 @@ import { activationGroup, capUsed, isActivated, pickedCategories, } from "./eval
 import { introUntil, introWindows, openedOn } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestoneSummaries } from "./milestones.js";
-import { optionName, ruleParts } from "./rule-text.js";
+import { creditStates } from "./credits.js";
+import { creditWhere, optionName, ruleParts } from "./rule-text.js";
 import { choicePeriod, daysBetween, inEffect, periodEnd } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { activationRules } from "./setup.js";
-import { CAP_PERIODS, categoryReadsOn, choiceName, currencyLabel, earnText, listed, shortDate, wholeDollars, words, } from "./text.js";
+import { CAP_PERIODS, categoryReadsOn, creditBack, creditLeft, ENROLL_FIRST, choiceName, currencyLabel, earnText, listed, PAYMENT_PHRASES, shortDate, wholeDollars, words, } from "./text.js";
 import { cardValuation, currencyValuation } from "./valuation.js";
 const matchKeys = (rule) => rule.match.choice !== undefined
     ? []
@@ -62,10 +63,12 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
         if (replaced)
             continue;
         const pending = r.requires?.activation && !isActivated(card, held, r.id);
+        const payment = r.requires?.payment;
         const key = [
             `${earnText(catalog, r.rate, currency)} on`,
             capLimit(card, shown, r),
             pending ? ', once activated' : '',
+            payment === undefined ? '' : ` ${PAYMENT_PHRASES[payment]}`,
         ].join('|');
         const whats = lines.get(key) ?? [];
         for (const part of ruleParts(catalog, r))
@@ -75,12 +78,13 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
     }
     return [
         ...[...lines].map(([key, whats]) => {
-            const [head = '', limit = '', activate = ''] = key.split('|');
+            const [head = '', limit = '', activate = '', paid = ''] = key.split('|');
             const after = `${limit}${activate}`;
-            return `${head} ${listed(whats)}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
+            return `${head} ${listed(whats)}${paid}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
         }),
         ...(shown.some((r) => r.match.any &&
             r.geography !== 'foreign_only' &&
+            r.requires?.payment === undefined &&
             r.rate > card.base_rate)
             ? []
             : [`${earnText(catalog, card.base_rate, currency)} on everything else`]),
@@ -200,6 +204,7 @@ export function walletSummary(catalog, wallet, today) {
             rotationGap: rotationGap(card, today),
             caps: capSummaries(catalog, card, held, today),
             milestones: milestoneSummaries(card, held, today),
+            credits: creditSummaries(catalog, card, held, today),
             chosen: held.chosen
                 ? {
                     period: held.chosen.period,
@@ -229,6 +234,29 @@ export function walletSummary(catalog, wallet, today) {
         cards,
     };
 }
+function creditSummaries(catalog, card, held, today) {
+    return creditStates(catalog, card, held, today).map((s) => {
+        const status = !s.enrolled
+            ? `${ENROLL_FIRST}, then mark it enrolled`
+            : s.left === null
+                ? "give the card's anniversary to track it"
+                : `${creditLeft(s.left, s.period)}${s.until === null ? '' : `, through ${shortDate(s.until)}`}`;
+        return {
+            id: s.credit.id,
+            name: s.name,
+            amount: s.amount,
+            period: s.period,
+            enroll: s.credit.enroll === true,
+            enrolled: s.enrolled,
+            currentPeriod: s.key,
+            until: s.until,
+            used: s.used,
+            left: s.left,
+            tracked: held.credit_usage?.[s.credit.id] !== undefined,
+            text: `${creditBack(s)} ${creditWhere(catalog, s.credit)}: ${status}.`,
+        };
+    });
+}
 function introSummary(card, held, today) {
     const [first] = card.intro_rates;
     if (!first)

package/dist/format/card-text.js

@@ -9,11 +9,12 @@ export function cardText(catalog) {
     const cards = new Map(catalog.cards.map((c) => [c.id, c]));
     function shortName(id) {
         const name = cards.get(id)?.name ?? id;
-        return name
+        return (name
             .replace(/^American Express /, 'Amex ')
             .replace(/^The Platinum Card from American Express$/, 'Amex Platinum')
-            .replace(/ (Visa Signature |Visa Infinite )?(Credit )?Card$/, '')
-            .replace(/ Card by /, ' by ');
+            // "Card" is part of Apple Card's name, not a suffix.
+            .replace(/ (Visa Signature |Visa Infinite )?(Credit )?(?<!^Apple )Card$/, '')
+            .replace(/ Card by /, ' by '));
     }
     function feeLabel(id) {
         const card = cards.get(id);

package/dist/format/cheat-sheet.js

@@ -15,5 +15,7 @@ export function formatCheatSheet(sheet) {
     }
     if (sheet.notes.length > 0)
         lines.push('', ...sheet.notes);
+    if (sheet.assumptions.length > 0)
+        lines.push('', ...sheet.assumptions);
     return `${lines.join('\n')}\n`;
 }

package/dist/format/explore.js

@@ -1,5 +1,5 @@
 import { membershipName, membershipNote, } from "../engine/memberships.js";
-import { choiceName, feeText, dollarsAndCents, pct, wholeDollars, words, } from "../engine/text.js";
+import { capitalize, choiceName, CREDIT_GROUP, CREDITS_LEFT_OUT, ENROLL_FIRST, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, } from "../engine/text.js";
 const membershipFees = (memberships) => memberships
     .map((m) => ` + ${wholeDollars(m.annualFee)} for ${m.name}`)
     .join('');
@@ -15,7 +15,23 @@ export function formatExploration(r, catalog, all) {
         return `No cards match at ${title}.\n`;
     const shown = all ? r.ranked : r.ranked.slice(0, TOP_BEST);
     const width = Math.max(...shown.map((e) => e.cardName.length));
-    const lines = [`Best cards for ${title}:`, ''];
+    const lines = [
+        ...(r.credits.length === 0
+            ? []
+            : [
+                `${CREDIT_GROUP} at ${title}:`,
+                '',
+                ...r.credits.flatMap((c) => [
+                    `- ${c.cardName}: ${c.text}${c.enroll ? ` (${ENROLL_FIRST})` : ''}. ${capitalize(feeText(c))}.`,
+                    ...(c.evidence
+                        ? [`    "${c.evidence.quote}" (${hostname(c.evidence.url)})`]
+                        : []),
+                ]),
+                '',
+            ]),
+        `Best cards for ${title}${r.credits.length === 0 ? '' : ' by rate'}:`,
+        '',
+    ];
     shown.forEach((e, i) => {
         const earned = e.earned === null ? '' : `  ${dollarsAndCents(e.earned)}`;
         lines.push(`${String(i + 1).padStart(2)}. ${e.cardName.padEnd(width)}  ${pct(e.effectiveReturnPct).padStart(5)}${earned}  ${feeText(e)}`);
@@ -89,7 +105,7 @@ export function formatCatalogSimulation(r, catalog, all) {
     ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', "Assumes each card's best picks, activations done each quarter, and no welcome bonuses.");
+    lines.push('', `Assumes each card's best picks, activations done each quarter, and no welcome bonuses. ${CREDITS_LEFT_OUT}`);
     return `${lines.join('\n')}\n`;
 }
 export function formatAdditions(r, catalog, all) {
@@ -117,6 +133,6 @@ export function formatAdditions(r, catalog, all) {
     ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh. Annual fees are counted in full: statement credits and perks that offset them are left out. Each kind of spending lists the card that earns the most on it over the whole year, so a one-quarter bonus may not show.');
+    lines.push('', `Assumes your picks carry over, rotating categories get activated, and caps start fresh. Annual fees are counted in full: statement credits and perks that offset them are left out. ${CREDITS_LEFT_OUT} Each kind of spending lists the card that earns the most on it over the whole year, so a one-quarter bonus may not show.`);
     return `${lines.join('\n')}\n`;
 }

package/dist/format/recommendation.js

@@ -33,7 +33,8 @@ function cardLines(cards, style, bonusPick) {
         const earned = (c.earned === null ? '' : `  ${dollarsAndCents(c.earned)}`) +
             (c.milestoneBonus === null
                 ? ''
-                : ` + ${money(c.milestoneBonus.dollars)} spend bonus`);
+                : ` + ${money(c.milestoneBonus.dollars)} spend bonus`) +
+            (c.credit?.dollars ? ` + ${money(c.credit.dollars)} credit` : '');
         const pick = c.cardId === bonusPick ? '  ← the pick, for its welcome bonus' : '';
         lines.push(`  ${String(c.rank).padStart(String(rankWidth).length)}. ${label(c).padEnd(nameWidth)}  ${pct(c.effectiveReturnPct).padStart(pctWidth)}${earned}${pick}`);
         for (const r of c.reasoning)
@@ -59,9 +60,12 @@ export function formatRecommendation(rec, purchase, { all = false, style = plain
         const milestone = top.milestoneBonus === null
             ? ''
             : `, plus a spend bonus worth about ${money(top.milestoneBonus.dollars)}`;
+        const credit = top.credit?.dollars
+            ? `, plus ${money(top.credit.dollars)} back from its ${top.credit.name} credit`
+            : '';
         const confidence = rec.decision.confidence;
         const why = rec.bonus ? ' for its welcome bonus' : '';
-        lines.push(`${style('bold', `Use ${label(top)}${why}: ${pct(top.effectiveReturnPct)} back${earned}${milestone}.`)} ${capitalize(confidence)} confidence.`);
+        lines.push(`${style('bold', `Use ${label(top)}${why}: ${pct(top.effectiveReturnPct)} back${earned}${milestone}${credit}.`)} ${capitalize(confidence)} confidence.`);
         if (rec.bonus && rec.notes[0])
             lines.push(rec.notes[0]);
     }

package/dist/format/wallet.js

@@ -1,4 +1,4 @@
-import { CAP_PERIODS, introAdjective, introSince, money, NETWORK_NAMES, periodPhrase, shortDate, } from "../engine/text.js";
+import { CAP_PERIODS, introAdjective, introSince, money, NETWORK_NAMES, periodPhrase, roundCents, shortDate, } from "../engine/text.js";
 // "To do now", above the card details; nothing when all's done.
 export function formatChecklist(items) {
     return items.length === 0
@@ -39,6 +39,8 @@ export function formatWalletSummary(summary) {
                 : `  Cap on ${cap.label}: ${money(cap.spent)} of ${money(cap.amount)} used ${periodPhrase(cap.period, cap.currentPeriod ?? '')}${cap.until === null ? '' : `, through ${shortDate(cap.until)}`} (cap key ${cap.key}).`);
         for (const m of c.milestones)
             lines.push(`  Spend bonus (${m.id}): ${m.text}`);
+        for (const credit of c.credits)
+            lines.push(`  Credit (${credit.id}): ${credit.text}`);
         if (c.anniversary !== null)
             lines.push(`  Account anniversary: ${c.anniversary}.`);
         if (c.intro?.state === 'active' && c.intro.until !== null)
@@ -62,8 +64,10 @@ export function formatWalletSummary(summary) {
         : "Point values: earnrate's defaults.";
     return [...cards, memberships, values].join('\n');
 }
-export function formatBooking(amount, cardId, cap, bonus, milestones = []) {
+export function formatBooking(amount, cardId, cap, bonus, milestones = [], credit = null) {
     const messages = [];
+    if (credit)
+        messages.push(`Used ${money(roundCents(credit.after - credit.before))} of ${cardId}'s ${credit.name} credit: ${money(credit.after)} of ${money(credit.amount)} ${periodPhrase(credit.periodKind, credit.period)}, ${money(roundCents(Math.max(0, credit.amount - credit.after)))} left.`);
     if (cap) {
         const left = Math.max(0, cap.capAmount - cap.after);
         messages.push(`Recorded ${money(amount)} on ${cardId} against "${cap.capKey}": ${money(cap.before)} → ${money(cap.after)} of ${money(cap.capAmount)} ${periodPhrase(cap.periodKind, cap.period)}, ${money(left)} left.`);

package/dist/import/analyze.js

@@ -182,8 +182,13 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
             date: line.date,
             country: 'US',
         };
-        const used = recommend(catalog, actual, purchase, merchant).ranked.find((r) => r.cardId === cardId);
-        const top = recommend(catalog, simulated, purchase, merchant).ranked[0];
+        // Past statements don't say which credits were used, so they're left out.
+        const used = recommend(catalog, actual, purchase, merchant, {
+            credits: false,
+        }).ranked.find((r) => r.cardId === cardId);
+        const top = recommend(catalog, simulated, purchase, merchant, {
+            credits: false,
+        }).ranked[0];
         if (!used || !top)
             continue;
         earned += used.earned ?? 0;

package/dist/mcp/inputs.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ALL_PERSONAL_CARDS } from "../engine/explore.js";
 import { profileText, VALUATION_PROFILES } from "../engine/profiles.js";
 import { knownMemberships } from "../engine/setup.js";
+import { PaymentMethod } from "../schema/card.js";
 import { IsoDate } from "../schema/common.js";
 import { COUNTRY_CODE } from "../schema/common.js";
 export const Merchant = z
@@ -18,6 +19,7 @@ export const CountryInput = z
     .regex(COUNTRY_CODE, 'Use a two-letter country code, like US or FR.')
     .optional()
     .describe('Where the purchase is made, as a two-letter country code (FR, GB, JP). Pass it when the user is paying abroad or in another currency: abroad, cards are ranked after their foreign transaction fees. Default US.');
+export const PaymentInput = PaymentMethod.optional().describe("How the purchase is paid, only when the user says: card (the card itself or its number), apple-pay, google-pay or paypal (PayPal checkout). Optional; omit it when unknown, and never assume Apple Pay. Some rates need one (Apple Card's 2% with Apple Pay, PayPal Cashback's 3% through PayPal checkout), and the answer's assumptions say when paying another way would change the pick.");
 export const CardId = z
     .string()
     .min(1)
@@ -79,6 +81,14 @@ const cardFields = {
         .record(z.string(), z.number().nonnegative())
         .optional()
         .describe('Dollars already spent on the card this year, for its spend milestones (bonuses after a yearly spending total, as search_cards lists them): milestone id → dollars, e.g. {"spend-15k": 9000}. Every purchase on the card counts, so give each milestone the same total. Ask; recorded purchases add to it from then on.'),
+    enrolled: z
+        .array(z.string())
+        .optional()
+        .describe('Merchant credit ids the user has enrolled in with the issuer (search_cards and list_wallet list each card\'s credits, e.g. "lululemon" on Amex Platinum). A credit that needs enrolling counts in answers only once it\'s here. Replaces the current list. Ask; never assume.'),
+    creditUsed: z
+        .record(z.string(), z.number().nonnegative())
+        .optional()
+        .describe('Dollars of a merchant credit already received this period: credit id → dollars, e.g. {"lululemon": 40}. Ask; recorded purchases add to it from then on.'),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),

package/dist/mcp/prompts.js

@@ -33,10 +33,15 @@ export function registerPrompts(server, deps, ctx) {
                 .string()
                 .optional()
                 .describe('Where you are paying, if not the U.S.: FR, Japan'),
+            paying: z
+                .string()
+                .optional()
+                .describe('How you are paying, if you know: Apple Pay, PayPal'),
         }),
     }, (args) => {
         const amount = args.amount?.trim() || null;
         const country = args.country?.trim() || null;
+        const paying = args.paying?.trim() || null;
         const call = [
             `merchant ${JSON.stringify(args.store)}`,
             ...(amount === null
@@ -45,8 +50,11 @@ export function registerPrompts(server, deps, ctx) {
             ...(country === null
                 ? []
                 : [`country as the two-letter code for ${JSON.stringify(country)}`]),
+            ...(paying === null
+                ? []
+                : [`payment for paying with ${JSON.stringify(paying)}`]),
         ];
-        return ask(`Which credit card should I use at ${args.store}${amount === null ? '' : ` for ${dollars(amount)}`}${country === null ? '' : ` in ${country}`}?`, [
+        return ask(`Which credit card should I use at ${args.store}${amount === null ? '' : ` for ${dollars(amount)}`}${country === null ? '' : ` in ${country}`}${paying === null ? '' : ` with ${paying}`}?`, [
             `Call earnrate's best_card_for_purchase with ${call.join(', ')}.`,
             `It answers from ${FROM_SAVED_OR_ALL}, so don't ask for their cards first.`,
             'Say which card to use and why, with the assumptions and warnings it gives.',

package/dist/mcp/schemas.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { CapPeriod, MilestoneSchema } from "../schema/card.js";
+import { CapPeriod, CreditPeriod, MilestoneSchema } from "../schema/card.js";
 const MilestonePeriod = MilestoneSchema.shape.period;
 import { CardNetwork, Network } from "../schema/common.js";
 // Mirrors the engine's result types. The SDK validates every structured
@@ -43,6 +43,18 @@ const RankedCardSchema = z.object({
     milestoneBonus: z
         .object({ points: z.number(), dollars: z.number() })
         .nullable(),
+    credit: z
+        .object({
+        id: z.string(),
+        name: z.string(),
+        amount: z.number(),
+        period: CreditPeriod,
+        enrolled: z.boolean(),
+        left: z.number().nullable(),
+        until: z.string().nullable(),
+        dollars: z.number().nullable(),
+    })
+        .nullable(),
     capped: z.boolean(),
     reasoning: z.array(z.string()),
     warnings: z.array(z.string()),
@@ -101,8 +113,11 @@ export const WalletSummarySchema = z.object({
             'milestone',
             'rotation',
             'intro',
+            'credit',
+            'enroll',
         ]),
         cardId: z.string(),
+        ref: z.string().optional(),
         text: z.string(),
         due: z.string().nullable(),
     }))
@@ -157,6 +172,20 @@ export const WalletSummarySchema = z.object({
             rewards: z.array(z.string()),
             text: z.string(),
         })),
+        credits: z.array(z.object({
+            id: z.string(),
+            name: z.string(),
+            amount: z.number(),
+            period: CreditPeriod,
+            enroll: z.boolean(),
+            enrolled: z.boolean(),
+            currentPeriod: z.string().nullable(),
+            until: z.string().nullable(),
+            used: z.number(),
+            left: z.number().nullable(),
+            tracked: z.boolean(),
+            text: z.string(),
+        })),
         chosen: z
             .object({
             period: z.string(),
@@ -217,6 +246,18 @@ export const RecordResultSchema = z.object({
         before: z.number(),
         after: z.number(),
     })),
+    credit: z
+        .object({
+        cardId: z.string(),
+        creditId: z.string(),
+        name: z.string(),
+        period: z.string(),
+        periodKind: CreditPeriod,
+        amount: z.number(),
+        before: z.number(),
+        after: z.number(),
+    })
+        .nullable(),
     message: z.string(),
 });
 export const OfferComparisonSchema = z.object({
@@ -287,6 +328,14 @@ export const CardSearchSchema = z.object({
             text: z.string(),
         })),
         introRates: z.array(z.object({ id: z.string(), days: z.number(), text: z.string() })),
+        credits: z.array(z.object({
+            id: z.string(),
+            name: z.string(),
+            amount: z.number(),
+            period: CreditPeriod,
+            enroll: z.boolean(),
+            text: z.string(),
+        })),
     })),
 });
 export const WalletChangeSchema = z.object({
@@ -315,6 +364,25 @@ const ExcludedCardSchema = z.object({
 const Picks = z.record(z.string(), z.array(z.string()));
 export const ExplorationSchema = z.object({
     merchant: MerchantResolutionSchema,
+    // Cards with a statement credit at this store, shown before the ranking.
+    credits: z.array(z.object({
+        cardId: z.string(),
+        cardName: z.string(),
+        issuer: z.string(),
+        network: CardNetwork,
+        annualFee: z.number().nullable(),
+        firstYearFee: z.number().nullable(),
+        creditId: z.string(),
+        name: z.string(),
+        amount: z.number(),
+        period: CreditPeriod,
+        enroll: z.boolean(),
+        note: z.string().nullable(),
+        back: z.string(),
+        earn: z.string(),
+        text: z.string(),
+        evidence: z.object({ quote: z.string(), url: z.string() }).nullable(),
+    })),
     ranked: z.array(RankedCardSchema.extend({
         issuer: z.string(),
         network: CardNetwork,
@@ -403,6 +471,7 @@ export const CheatSheetSchema = z.object({
         note: z.string().nullable(),
     })),
     notes: z.array(z.string()),
+    assumptions: z.array(z.string()),
 });
 export const PurchaseAnswerSchema = RecommendationSchema.extend({
     // Every card earnrate knows, ranked: set when no cards were given.

package/dist/mcp/tools/answers.js

@@ -15,7 +15,7 @@ import { formatOffers } from "../../format/offers.js";
 import { formatRecommendation } from "../../format/recommendation.js";
 import { resolvePlace, withCallerCategory } from "../../merchants/resolve.js";
 import { ALL_CARDS_NOTE, fail } from "../context.js";
-import { ChannelInput, CountryInput, DateInput, Merchant, settings, } from "../inputs.js";
+import { ChannelInput, CountryInput, PaymentInput, 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",
@@ -34,7 +34,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 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. Never needs or returns card numbers.",
+        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 merchant 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.",
         inputSchema: z.object({
             merchant: Merchant,
             amount: z
@@ -45,6 +45,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             channel: ChannelInput,
             date: DateInput,
             country: CountryInput,
+            payment: PaymentInput,
             category: CategoryInput,
             cards: NamedCards,
             memberships: NamedMemberships,
@@ -57,7 +58,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             destructiveHint: false,
             openWorldHint: deps.llm !== null,
         },
-    }, async ({ merchant, amount, channel, date, country, category, cards, memberships, valuation, }) => {
+    }, async ({ merchant, amount, channel, date, country, payment, category, cards, memberships, valuation, }) => {
         const held = await ctx.cardsFor(cards, memberships);
         if (typeof held === 'string')
             return fail(held);
@@ -70,6 +71,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             channel: channel ?? null,
             date: date ?? deps.today(),
             country: (country ?? 'US').toUpperCase(),
+            payment: payment ?? null,
         };
         const resolved = await ctx.resolve(merchant, purchase.channel, category ?? null);
         const retry = resolved.merchant.source === 'none'
@@ -83,6 +85,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 channel: purchase.channel,
                 date: purchase.date,
                 country: purchase.country,
+                payment: purchase.payment,
             }, settings({ memberships, valuation }, await ctx.saved()), resolved.merchant);
             const allCards = { ...explored, ranked: explored.ranked.slice(0, TOP) };
             const empty = recommend(catalog, EMPTY_WALLET, purchase, resolved.merchant);
@@ -205,7 +208,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     });
     server.registerTool('best_cards_for', {
         title: 'Best cards for a purchase',
-        description: 'Ranks every card earnrate knows that takes new applicants, not only the user\'s, for one purchase or category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Use it for questions like "what\'s the best card for groceries?" or "which card should I get for Amazon?". It needs no wallet. For which of the user\'s own cards to use, call best_card_for_purchase instead. Mention the annual fee and any conditions alongside each card.',
+        description: 'Ranks every card earnrate knows that takes new applicants, not only the user\'s, for one purchase or category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Use it for questions like "what\'s the best card for groceries?" or "which card should I get for Amazon?". It needs no wallet. For which of the user\'s own cards to use, call best_card_for_purchase instead. Mention the annual fee and any conditions alongside each card. For a store, cards with a statement credit there come first in `credits` ("$75 back each quarter, then 1x Amex Membership Rewards"): present them first, in dollars and never as a percentage, saying when the cardholder must enroll, then the ranking by rate.',
         inputSchema: z.object({
             merchant: Merchant.optional(),
             category: CatalogCategory.optional(),
@@ -216,6 +219,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 .describe('Purchase amount in US dollars, if known.'),
             channel: ChannelInput,
             country: CountryInput,
+            payment: PaymentInput,
             ...CatalogFilters,
         }),
         outputSchema: ExplorationSchema,
@@ -236,6 +240,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             channel,
             date: deps.today(),
             country: (args.country ?? 'US').toUpperCase(),
+            payment: args.payment ?? null,
         }, settings(args, await ctx.saved()), args.merchant === undefined
             ? undefined
             : withCallerCategory(resolvePlace(catalog, args.merchant, channel), args.category ?? null));