earnrate 0.2.8 → 0.2.9

package/dist/engine/recommend.js

@@ -2,13 +2,19 @@ import { findMerchant, resolveMerchant, resolveMerchantById, } from "../merchant
 import { bonusStatus } from "./bonus.js";
 import { evaluateCard, purchaseContext, usableAt, } from "./evaluate.js";
 import { membershipName } from "./memberships.js";
+import { milestonePoints, milestonesReached, reachedText, } from "./milestones.js";
 import { daysBetween } from "./periods.js";
 import { ruleWhat } from "./rule-text.js";
 import { rotationGap } from "./rotation.js";
 import { EPSILON, isClose } from "./compare.js";
-import { CAP_ADJECTIVES, categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, NETWORK_NAMES, num, pct, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.js";
+import { CAP_ADJECTIVES, categoryPhrase, codesAs, currencyLabel, currencyName, earnText, listed, money, NETWORK_NAMES, num, pct, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 export const STALE_AFTER_DAYS = 180;
+// The engine only tells the U.S. from everywhere else.
+export const isForeign = (purchase) => purchase.country !== 'US';
+// Any purchase outside the U.S., when no country is named: ZZ is a code ISO
+// leaves unassigned, and nothing prints it.
+export const ABROAD = 'ZZ';
 // The warning when no card works; the CLI shows it as the answer instead.
 export const noCardText = (merchant) => `None of your cards work at ${merchant}.`;
 const NEAR_CAP_SHARE = 0.2;
@@ -66,14 +72,22 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
         }
         const valuation = cardValuation(catalog, wallet, card);
         const evaluation = evaluateCard(card, held, ctx);
-        const rate = evaluation.best.rate;
+        const milestones = milestonesReached(card, held, purchase.date, purchase.amount);
+        const bonusPoints = milestonePoints(milestones);
+        const perDollar = evaluation.best.rate +
+            (bonusPoints > 0 && purchase.amount ? bonusPoints / purchase.amount : 0);
+        // An unknown fee isn't guessed: it's warned about instead.
+        const fee = isForeign(purchase) ? (card.foreign_transaction_fee ?? 0) : 0;
         entries.push({
             card,
             held,
             valuation,
             evaluation,
-            effectiveReturnPct: rate * valuation.centsPerUnit,
-            upside: rate * (valuation.range?.[1] ?? valuation.centsPerUnit),
+            milestones,
+            perDollar,
+            fee,
+            effectiveReturnPct: perDollar * valuation.centsPerUnit - fee,
+            upside: perDollar * (valuation.range?.[1] ?? valuation.centsPerUnit) - fee,
         });
     }
     entries.sort(compareEntries);
@@ -96,6 +110,8 @@ function reasoningFor(catalog, wallet, entry, amount) {
         const over = amount - cap.remaining;
         lines.push(`${money(cap.remaining)} earns ${earnText(catalog, best.nominalRate, currency)} before the cap, then ${money(over)} earns ${earnText(catalog, best.afterCap ?? cap.cap.then_rate, currency)}: ${num(best.rate)} per dollar overall.`);
     }
+    for (const hit of entry.milestones)
+        lines.push(reachedText(card, hit));
     if (valuation.pooledFrom !== null) {
         const partners = card.pools_into?.when_wallet_has ?? [];
         const heldPartners = wallet.cards
@@ -106,7 +122,7 @@ function reasoningFor(catalog, wallet, entry, amount) {
         lines.push(`Pools into ${currencyName(catalog, currency)} because you hold ${heldPartners.join(' and ')}.`);
     }
     if (currency !== 'cash') {
-        lines.push(`Valued at ${num(valuation.centsPerUnit)}¢ per point: ${pct(entry.effectiveReturnPct)} back.`);
+        lines.push(`Valued at ${num(valuation.centsPerUnit)}¢ per point: ${pct(entry.perDollar * valuation.centsPerUnit)} back.`);
     }
     return lines;
 }
@@ -114,6 +130,10 @@ function warningsFor(catalog, entry, purchase) {
     const { card, valuation, evaluation } = entry;
     const { best, nominal } = evaluation;
     const warnings = [];
+    if (entry.fee > 0)
+        warnings.push(`Charges a ${pct(entry.fee)} foreign transaction fee here, so it nets ${pct(entry.effectiveReturnPct)}.`);
+    if (isForeign(purchase) && card.foreign_transaction_fee === null)
+        warnings.push("Its foreign transaction fee isn't on file, so none is subtracted. Check the issuer's terms before using it abroad.");
     const capLabel = (e) => e.cap
         ? `${money(e.cap.cap.amount)} ${CAP_ADJECTIVES[e.cap.cap.period]} cap`
         : '';
@@ -165,6 +185,7 @@ function toRanked(catalog, wallet, entry, purchase) {
         currency: valuation.currency,
         centsPerUnit: valuation.centsPerUnit,
         effectiveReturnPct: entry.effectiveReturnPct,
+        foreignFee: entry.fee > 0 ? entry.fee : null,
         earned: purchase.amount === null
             ? null
             : Math.round(purchase.amount * entry.effectiveReturnPct) / 100,
@@ -208,16 +229,17 @@ function sensitivity(catalog, entries) {
         const o = other.valuation;
         if (w.currency === o.currency)
             continue;
-        const wRate = winner.evaluation.best.rate;
-        const oRate = other.evaluation.best.rate;
+        const wRate = winner.perDollar;
+        const oRate = other.perDollar;
+        // Net return is rate × value − fee, so each flip point adds the fee back.
         if (w.range && wRate > 0) {
-            const threshold = other.effectiveReturnPct / wRate;
+            const threshold = (other.effectiveReturnPct + winner.fee) / wRate;
             if (threshold < w.centsPerUnit && threshold >= w.range[0]) {
                 consider((w.centsPerUnit - threshold) / w.centsPerUnit, `${displayName(other)} beats ${displayName(winner)} here if ${currencyLabel(catalog, w.currency)} points are worth less than ${roundDown(threshold)}¢ (you value them at ${num(w.centsPerUnit)}¢).`);
             }
         }
         if (o.range && oRate > 0) {
-            const threshold = winner.effectiveReturnPct / oRate;
+            const threshold = (winner.effectiveReturnPct + other.fee) / oRate;
             if (threshold > o.centsPerUnit && threshold <= o.range[1]) {
                 consider((threshold - o.centsPerUnit) / o.centsPerUnit, `${displayName(other)} beats ${displayName(winner)} here if ${currencyLabel(catalog, o.currency)} points are worth ${worthAbove(threshold)} (you value them at ${num(o.centsPerUnit)}¢).`);
             }
@@ -251,6 +273,11 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
     const values = pointValuesText(catalog, entries.map((e) => e.valuation));
     if (values !== null)
         assumptions.push(values);
+    if (isForeign(purchase))
+        assumptions.push('Treats this as a purchase outside the U.S.: each card is ranked after its foreign transaction fee.');
+    for (const e of entries)
+        for (const hit of e.milestones)
+            assumptions.push(`Counts the ${money(hit.before)} tracked on ${displayName(e)} in ${hit.period} toward its ${wholeDollars(hit.spend)} spend bonus; spending earnrate wasn't told about isn't counted.`);
     return assumptions;
 }
 export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(catalog, purchase.merchant, purchase.channel)) {
@@ -259,6 +286,9 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
     const winner = entries[0];
     const warnings = [];
     const notes = [];
+    const charging = entries.filter((e) => e.fee > 0);
+    if (charging.length > 0 && entries.length > 1)
+        notes.push(`${listed(charging.map((e) => `${displayName(e)} (${pct(e.fee)})`))} ${charging.length === 1 ? 'charges a foreign transaction fee' : 'charge foreign transaction fees'} here, already subtracted in the ranking.`);
     if (merchant.source === 'none') {
         warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. If you know what kind of business it is, give its category (like dining or grocery) to find bonus rates.`);
     }

package/dist/engine/record.js

@@ -1,6 +1,7 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { bonusStatus, countsTowardBonus } from "./bonus.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
+import { milestoneProgress } from "./milestones.js";
 import { roundCents } from "./text.js";
 // Books the spend against the cap of the highest-rate rule that matches, even
 // when that cap is already used up, so usage stays accurate across a reset.
@@ -75,11 +76,48 @@ export function applyBonusBooking(wallet, b) {
             : c),
     };
 }
+// Every purchase on a card counts toward each of its spend milestones. None
+// for a cardmember-year milestone on a card with no anniversary.
+export function milestoneBookings(catalog, wallet, purchase) {
+    const held = wallet.cards.find((c) => c.id === purchase.cardId);
+    const card = catalog.cards.find((c) => c.id === purchase.cardId);
+    if (!held || !card)
+        return [];
+    return milestoneProgress(card, held, purchase.date).flatMap((p) => p.period === null
+        ? []
+        : [
+            {
+                cardId: card.id,
+                milestoneId: p.milestone.id,
+                period: p.period,
+                spend: p.milestone.spend,
+                before: p.spent,
+                after: roundCents(Math.max(0, p.spent + purchase.amount)),
+            },
+        ]);
+}
+export function applyMilestoneBooking(wallet, b) {
+    return {
+        ...wallet,
+        cards: wallet.cards.map((c) => c.id === b.cardId
+            ? {
+                ...c,
+                milestone_usage: {
+                    ...c.milestone_usage,
+                    [b.milestoneId]: { period: b.period, spent: b.after },
+                },
+            }
+            : c),
+    };
+}
 export function bookPurchase(catalog, wallet, purchase, merchant) {
     const cap = capBooking(catalog, wallet, purchase, merchant);
     const bonus = bonusBooking(catalog, wallet, purchase);
+    const milestones = milestoneBookings(catalog, wallet, purchase);
     let next = cap ? applyBooking(wallet, cap) : wallet;
     if (bonus)
         next = applyBonusBooking(next, bonus);
-    return { wallet: next, cap, bonus };
+    for (const m of milestones)
+        next = applyMilestoneBooking(next, m);
+    return { wallet: next, cap, bonus, milestones };
 }

package/dist/engine/rule-text.js

@@ -26,7 +26,11 @@ export function optionName(catalog, card, choiceId, option) {
 // What a rule covers, as a list of phrases.
 export function ruleParts(catalog, rule) {
     if (rule.match.any)
-        return ['everything else'];
+        return [
+            rule.geography === 'foreign_only'
+                ? 'purchases outside the U.S.'
+                : 'everything else',
+        ];
     if (rule.match.choice !== undefined)
         return [`your ${choiceName(rule.match.choice)} picks`];
     const merchants = rule.match.merchants ?? [];

package/dist/engine/setup.js

@@ -1,5 +1,6 @@
 import { isActivated, pickedCategories } from "./evaluate.js";
 import { membership, membershipName, sameGroup } from "./memberships.js";
+import { milestoneWhat } from "./milestones.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
 import { idList, listed } from "./text.js";
@@ -39,7 +40,8 @@ function matcher(catalog, card) {
 }
 export function needsAnniversary(card) {
     return (card.caps.some((c) => c.period === 'cardmember_year') ||
-        card.rules.some((r) => typeof r.cap === 'object' && r.cap.period === 'cardmember_year'));
+        card.rules.some((r) => typeof r.cap === 'object' && r.cap.period === 'cardmember_year') ||
+        card.milestones.some((m) => m.period === 'cardmember_year'));
 }
 export function activationRules(card, today) {
     return card.rules
@@ -74,6 +76,7 @@ export function cardInfo(catalog, card, wallet, today) {
         network: card.network,
         currency: card.currency,
         annualFee: card.annual_fee ?? null,
+        foreignTransactionFee: card.foreign_transaction_fee,
         business: card.business,
         onlyAt: card.only_at ?? null,
         held: wallet?.cards.some((c) => c.id === card.id) ?? false,
@@ -94,6 +97,14 @@ export function cardInfo(catalog, card, wallet, today) {
             },
         activation: activationRules(card, today),
         needsAnniversary: needsAnniversary(card),
+        milestones: card.milestones.map((m) => ({
+            id: m.id,
+            spend: m.spend,
+            period: m.period,
+            points: m.points ?? null,
+            rewards: m.rewards ?? [],
+            text: milestoneWhat(m).replace(/^the /, ''),
+        })),
     };
 }
 // Every word of the query has to match a word of the card's id, name or
@@ -162,7 +173,7 @@ export function setupNotes(catalog, wallet, held, today) {
     if (needsAnniversary(card) && held.anniversary === undefined) {
         notes.push({
             kind: 'anniversary',
-            text: `${name} has a cap that resets on the card's anniversary. Add the anniversary (MM-DD) so it can be tracked.`,
+            text: `${name} has a ${card.milestones.some((m) => m.period === 'cardmember_year') ? 'spend bonus' : 'cap'} that resets on the card's anniversary. Add the anniversary (MM-DD) so it can be tracked.`,
         });
     }
     const gap = rotationGap(card, today);

package/dist/engine/simulate.js

@@ -4,8 +4,9 @@ import { idealHolding, matchesFilters, } from "./explore.js";
 import { membershipCosts, membershipNote, paidMemberships, } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { applyBooking, capBooking } from "./record.js";
+import { milestoneWhat } from "./milestones.js";
 import { rotationGap } from "./rotation.js";
-import { money, roundCents } from "./text.js";
+import { money, roundCents, wholeDollars } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON, HALF_CENT } from "./compare.js";
 const MONTHS = 12;
@@ -122,7 +123,27 @@ held = []) {
             cards: [...r.byCard].sort((a, b) => b[1] - a[1]).map(([id]) => id),
         };
     });
-    const rewards = roundCents(lineResults.reduce((sum, l) => sum + l.earned, 0));
+    // A year of these amounts is taken as every year's: a calendar-year or
+    // cardmember-year total is the same twelve months' spending.
+    const milestones = [];
+    const milestoneNotes = [];
+    for (const { card, cents } of cards) {
+        const spent = results.reduce((sum, r) => sum + (r.byCard.get(card.id) ?? 0), 0);
+        for (const m of card.milestones) {
+            if (spent + EPSILON < m.spend)
+                continue;
+            const value = roundCents(((m.points ?? 0) * cents) / 100);
+            milestones.push({
+                cardId: card.id,
+                milestoneId: m.id,
+                points: m.points ?? null,
+                value,
+            });
+            milestoneNotes.push(`${card.name}: ${wholeDollars(spent)} a year on it reaches ${milestoneWhat(m)}${m.points === undefined ? '' : ` (about ${money(value)}, counted in its rewards)`}, assuming the same spending each year.`);
+        }
+    }
+    const rewards = roundCents(lineResults.reduce((sum, l) => sum + l.earned, 0) +
+        milestones.reduce((sum, m) => sum + m.value, 0));
     const annualFees = cards.reduce((sum, c) => sum + (c.card.annual_fee ?? 0), 0);
     const paid = paidMemberships(catalog, {
         memberships: wallet.memberships,
@@ -131,7 +152,7 @@ held = []) {
     });
     const memberships = membershipCosts(catalog, cards.map((c) => c.card), paid);
     const membershipFees = memberships.reduce((sum, m) => sum + m.annualFee, 0);
-    const notes = [];
+    const notes = [...milestoneNotes];
     for (const m of memberships)
         notes.push(membershipNote(catalog, m));
     const dates = monthDates(start);
@@ -160,6 +181,7 @@ held = []) {
         membershipFees,
         net: roundCents(rewards - annualFees - membershipFees),
         lines: lineResults,
+        milestones,
         notes,
     };
 }

package/dist/engine/text.js

@@ -32,6 +32,12 @@ export const wholeDollars = (n) => money(Math.round(n));
 // Whole dollars stay whole ($2,800); anything else shows cents ($0.40). A
 // loss reads −$618.
 export const money = (n) => `${n < 0 ? '−' : ''}$${Math.abs(n).toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+// "No foreign transaction fee", "3% foreign transaction fee"
+export const foreignFeeText = (fee) => fee === null
+    ? 'Foreign transaction fee not on file'
+    : fee === 0
+        ? 'No foreign transaction fee'
+        : `${pct(fee)} foreign transaction fee`;
 export function feeText(fees) {
     const { annualFee, firstYearFee } = fees;
     if (annualFee === null)
@@ -122,6 +128,11 @@ export const CAP_ADJECTIVES = {
     calendar_year: 'calendar-year',
     cardmember_year: 'cardmember-year',
 };
+// "the $15,000 calendar-year spend", for a spend milestone.
+export const MILESTONE_PERIODS = {
+    calendar_year: 'calendar-year',
+    cardmember_year: 'cardmember-year',
+};
 export const PICK_PERIODS = {
     month: 'each month',
     quarter: 'each quarter',

package/dist/engine/wallet-change.js

@@ -116,6 +116,28 @@ export function cardFields(card, held, input, today) {
         }
         fields.cap_usage = usage;
     }
+    if (input.milestoneSpent !== undefined) {
+        const usage = { ...held?.milestone_usage };
+        const anniversary = fields.anniversary ?? held?.anniversary ?? null;
+        for (const [id, spent] of Object.entries(input.milestoneSpent)) {
+            const milestone = card.milestones.find((m) => m.id === id);
+            if (!milestone) {
+                problems.push(card.milestones.length > 0
+                    ? `${card.id} has no spend milestone '${id}'. Its milestones are: ${idList(card.milestones.map((m) => m.id))}.`
+                    : `${card.id} has no spend milestones.`);
+                continue;
+            }
+            if (!(spent >= 0))
+                problems.push('Spending toward a milestone must be $0 or more.');
+            const period = periodKey(milestone.period, today, anniversary);
+            if (period === null) {
+                problems.push(`The '${id}' milestone resets on the card's anniversary; give the anniversary (MM-DD) too.`);
+                continue;
+            }
+            usage[id] = { period, spent };
+        }
+        fields.milestone_usage = usage;
+    }
     if (input.bonus === null)
         fields.bonus = null;
     else if (input.bonus !== undefined) {
@@ -173,6 +195,9 @@ const withFields = ({ bonus, checkout_label, ...held }, f) => ({
     ...(f.chosen === undefined ? {} : { chosen: f.chosen }),
     ...(f.activated === undefined ? {} : { activated: f.activated }),
     ...(f.cap_usage === undefined ? {} : { cap_usage: f.cap_usage }),
+    ...(f.milestone_usage === undefined
+        ? {}
+        : { milestone_usage: f.milestone_usage }),
     ...(f.bonus ? { bonus: f.bonus } : {}),
 });
 // `wallet` is null when there isn't one yet; adding a card starts it.
@@ -266,3 +291,45 @@ export function withValuations(catalog, wallet, changes) {
 }
 // Higher than any program's points are worth, even transferred.
 const MAX_CENTS = 5;
+// Point values keyed the way people say them ("ur", "Ultimate Rewards",
+// "Chase points"), turned into currency ids. A key that could mean more
+// than one currency is refused rather than guessed.
+export function currencyChanges(catalog, changes) {
+    const out = {};
+    for (const [key, cents] of Object.entries(changes)) {
+        const matches = currenciesFor(catalog, key);
+        const only = matches[0];
+        if (matches.length > 1)
+            return failed(`'${key}' could be ${matches.map((c) => `${c.id} (${c.name})`).join(' or ')}; give the currency id.`);
+        if (only === undefined)
+            return failed(`Unknown currency '${key}'. Currencies: ${catalog.currencies.map((c) => `${c.id} (${c.name})`).join(', ')}.`);
+        if (only.id in out)
+            return failed(`More than one value was given for ${only.name}.`);
+        out[only.id] = cents;
+    }
+    return { ok: true, changes: out };
+}
+const IGNORED_WORDS = new Set(['points', 'point', 'pts', 'miles', 'mile']);
+const words = (text) => text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w !== '' && !IGNORED_WORDS.has(w));
+const sameWords = (a, b) => a.length === b.length && a.every((w, i) => w === b[i]);
+function currenciesFor(catalog, key) {
+    const exact = catalog.currencies.find((c) => c.id === key);
+    if (exact)
+        return [exact];
+    const k = words(key);
+    if (k.length === 0)
+        return [];
+    const byId = catalog.currencies.filter((c) => sameWords(words(c.id), k));
+    if (byId.length > 0)
+        return byId;
+    const byName = catalog.currencies.filter((c) => sameWords(words(c.name), k));
+    if (byName.length > 0)
+        return byName;
+    return catalog.currencies.filter((c) => {
+        const name = words(c.name);
+        return name.some((_, i) => sameWords(name.slice(i, i + k.length), k));
+    });
+}

package/dist/engine/wallet-summary.js

@@ -1,8 +1,9 @@
 import { bonusStatus } from "./bonus.js";
 import { activationGroup, capUsed, isActivated, pickedCategories, } from "./evaluate.js";
 import { membershipName } from "./memberships.js";
+import { milestoneSummaries } from "./milestones.js";
 import { optionName, ruleParts, ruleWhat } from "./rule-text.js";
-import { daysBetween, inEffect, periodEnd } from "./periods.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";
@@ -77,7 +78,9 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
             const after = `${limit}${activate}`;
             return `${head} ${listed(whats)}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
         }),
-        ...(shown.some((r) => r.match.any && r.rate > card.base_rate)
+        ...(shown.some((r) => r.match.any &&
+            r.geography !== 'foreign_only' &&
+            r.rate > card.base_rate)
             ? []
             : [`${earnText(catalog, card.base_rate, currency)} on everything else`]),
     ];
@@ -114,6 +117,13 @@ function toActivate(catalog, card, held, today) {
         return `${a.what}${when === '' ? '' : ` (${when})`}`;
     });
 }
+// Picks that carry over have no end date.
+function picksUntil(card, key) {
+    if (card.choices.every((c) => c.period === 'until_changed'))
+        return null;
+    const period = choicePeriod(card);
+    return period === null ? null : periodEnd(period, key, null);
+}
 function capSummaries(catalog, card, held, today) {
     const caps = new Map();
     for (const shared of card.caps)
@@ -143,6 +153,9 @@ function capSummaries(catalog, card, held, today) {
             amount: cap.amount,
             period: cap.period,
             currentPeriod,
+            until: currentPeriod === null
+                ? null
+                : periodEnd(cap.period, currentPeriod, held.anniversary ?? null),
             spent,
             remaining: currentPeriod === null ? null : Math.max(0, cap.amount - spent),
         };
@@ -180,14 +193,13 @@ export function walletSummary(catalog, wallet, today) {
             dataIsStale: daysBetween(card.last_verified, today) > STALE_AFTER_DAYS,
             rotationGap: rotationGap(card, today),
             caps: capSummaries(catalog, card, held, today),
+            milestones: milestoneSummaries(card, held, today),
             chosen: held.chosen
                 ? {
                     period: held.chosen.period,
                     current: pickedCategories(card, held, today).staleChoice === null,
                     // Picks that carry over have no end date.
-                    until: card.choices.every((c) => c.period === 'until_changed')
-                        ? null
-                        : periodEnd(held.chosen.period),
+                    until: picksUntil(card, held.chosen.period),
                     picks: held.chosen.picks,
                     pickNames: Object.fromEntries(Object.entries(held.chosen.picks).map(([choice, options]) => [
                         choiceName(choice),

package/dist/format/cards.js

@@ -1,4 +1,4 @@
-import { money, NETWORK_NAMES } from "../engine/text.js";
+import { foreignFeeText, money, NETWORK_NAMES } from "../engine/text.js";
 export function formatCardInfo(card) {
     const fee = card.annualFee === null
         ? ''
@@ -19,7 +19,9 @@ export function formatCardInfo(card) {
             ? [`activate with the issuer: ${card.activation.join(', ')}`]
             : []),
         ...(card.needsAnniversary ? ['cap resets on the card anniversary'] : []),
+        ...card.milestones.map((m) => `spend bonus: ${m.text} (${m.id})`),
         ...(card.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
+        foreignFeeText(card.foreignTransactionFee).toLowerCase(),
     ];
     return [
         `${card.id}: ${card.name} (${NETWORK_NAMES[card.network] ?? card.network}${fee})${card.held ? ' [in wallet]' : ''}`,

package/dist/format/wallet.js

@@ -1,4 +1,4 @@
-import { money, NETWORK_NAMES, shortDate } from "../engine/text.js";
+import { CAP_PERIODS, money, NETWORK_NAMES, 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
@@ -34,8 +34,11 @@ export function formatWalletSummary(summary) {
         if (c.rotationGap !== null)
             lines.push(`  Rotating categories for ${c.rotationGap} aren't in earnrate yet.`);
         for (const cap of c.caps)
-            if (cap.remaining !== null)
-                lines.push(`  Cap on ${cap.label}: ${money(cap.spent)} of ${money(cap.amount)} used for ${cap.currentPeriod ?? ''} (cap key ${cap.key}).`);
+            lines.push(cap.remaining === null
+                ? `  Cap on ${cap.label}: ${money(cap.amount)} ${CAP_PERIODS[cap.period]}; give the card's anniversary to track it (cap key ${cap.key}).`
+                : `  Cap on ${cap.label}: ${money(cap.spent)} of ${money(cap.amount)} used for ${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}`);
         if (c.anniversary !== null)
             lines.push(`  Account anniversary: ${c.anniversary}.`);
         const b = c.bonus;
@@ -53,7 +56,7 @@ export function formatWalletSummary(summary) {
         : "Point values: earnrate's defaults.";
     return [...cards, memberships, values].join('\n');
 }
-export function formatBooking(amount, cardId, cap, bonus) {
+export function formatBooking(amount, cardId, cap, bonus, milestones = []) {
     const messages = [];
     if (cap) {
         const left = Math.max(0, cap.capAmount - cap.after);
@@ -65,5 +68,16 @@ export function formatBooking(amount, cardId, cap, bonus) {
             ? `Welcome bonus spend met on ${cardId}: ${money(bonus.after)} of ${money(bonus.spend)}.`
             : `Welcome bonus on ${cardId}: ${money(bonus.after)} of ${money(bonus.spend)} spent, ${money(left)} to go by ${bonus.deadline ?? 'the deadline'}.`);
     }
+    // Every milestone counts the same purchases, so one line covers them.
+    const first = milestones[0];
+    if (first) {
+        const reached = milestones.filter((m) => m.before < m.spend && m.after >= m.spend);
+        const next = milestones.find((m) => m.after < m.spend);
+        messages.push([
+            `Spend on ${cardId} this year: ${money(first.after)}.`,
+            ...reached.map((m) => `That reaches its ${money(m.spend)} spend bonus.`),
+            ...(next ? [`${money(next.spend - next.after)} to its next one.`] : []),
+        ].join(' '));
+    }
     return messages.join(' ');
 }

package/dist/import/analyze.js

@@ -1,6 +1,7 @@
 import { bonusStatus, countsTowardBonus } from "../engine/bonus.js";
 import { HALF_CENT } from "../engine/compare.js";
 import { capByKey, categoryMatches } from "../engine/evaluate.js";
+import { milestoneProgress } from "../engine/milestones.js";
 import { periodKey } from "../engine/periods.js";
 import { recommend } from "../engine/recommend.js";
 import { applyBooking, capBooking } from "../engine/record.js";
@@ -41,8 +42,14 @@ function capPeriodKey(catalog, wallet, booking, date) {
 // up partway through the year is accounted for on both sides.
 export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorded = () => false) {
     const sorted = [...entries].sort((a, b) => a.line.date.localeCompare(b.line.date));
-    let actual = wallet;
-    let simulated = wallet;
+    // The earned-versus-best replay leaves spend milestones out: they pay once
+    // on the card's total, whichever card is best for each purchase.
+    const replay = {
+        ...wallet,
+        cards: wallet.cards.map(({ milestone_usage: _usage, ...c }) => c),
+    };
+    let actual = replay;
+    let simulated = replay;
     let current = wallet;
     const byCard = new Map();
     const missed = new Map();
@@ -69,8 +76,40 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
                 entries: [],
             });
     }
+    const milestones = [];
+    for (const held of wallet.cards) {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        if (!card)
+            continue;
+        for (const p of milestoneProgress(card, held, today))
+            if (p.period !== null)
+                milestones.push({
+                    cardId: held.id,
+                    milestoneId: p.milestone.id,
+                    period: p.period,
+                    spend: p.milestone.spend,
+                    before: p.spent,
+                    after: p.spent,
+                    entries: [],
+                });
+    }
     for (const entry of sorted) {
         const { cardId, line } = entry;
+        if (!alreadyRecorded(entry, 'milestone')) {
+            const held = wallet.cards.find((c) => c.id === cardId);
+            for (const m of milestones) {
+                if (m.cardId !== cardId)
+                    continue;
+                const card = catalog.cards.find((c) => c.id === cardId);
+                const milestone = card?.milestones.find((x) => x.id === m.milestoneId);
+                if (!milestone ||
+                    periodKey(milestone.period, line.date, held?.anniversary ?? null) !==
+                        m.period)
+                    continue;
+                m.after = roundCents(Math.max(0, m.after + line.amount));
+                m.entries.push(entry);
+            }
+        }
         const progress = bonuses.get(cardId);
         if (progress &&
             countsTowardBonus(progress, line.date) &&
@@ -202,5 +241,6 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
         outsideCurrentPeriod,
         alreadyImported,
         bonuses: [...bonuses.values()].filter((b) => b.entries.length > 0),
+        milestones: milestones.filter((m) => m.entries.length > 0),
     };
 }

package/dist/mcp/inputs.js

@@ -3,6 +3,7 @@ import { ALL_PERSONAL_CARDS } from "../engine/explore.js";
 import { profileText, VALUATION_PROFILES } from "../engine/profiles.js";
 import { knownMemberships } from "../engine/setup.js";
 import { IsoDate } from "../schema/common.js";
+import { COUNTRY_CODE } from "../schema/common.js";
 export const Merchant = z
     .string()
     .min(1)
@@ -12,6 +13,11 @@ export const ChannelInput = z
     .optional()
     .describe('How the purchase is made. Omit if unknown; the answer says what it assumed.');
 export const DateInput = IsoDate.optional().describe('Purchase date, YYYY-MM-DD. Defaults to today.');
+export const CountryInput = z
+    .string()
+    .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 CardId = z
     .string()
     .min(1)
@@ -66,6 +72,10 @@ const cardFields = {
         .record(z.string(), z.number().nonnegative())
         .optional()
         .describe('Dollars already spent this period on a capped bonus, for a card the user starts tracking partway through: cap key (as list_wallet shows it) → dollars, e.g. {"five-percent-quarterly": 400}. Ask; recorded purchases add to it from then on.'),
+    milestoneSpent: z
+        .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.'),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),