earnrate 0.2.8 → 0.2.10

package/dist/engine/periods.js

@@ -42,17 +42,34 @@ export function choicePeriod(card) {
 // limit on that side.
 export const inEffect = (window, date) => (window.valid_from === undefined || window.valid_from <= date) &&
     (window.valid_to === undefined || window.valid_to >= date);
-// The last day of a period key ("2026-Q4", "2026-10", "2026").
-export function periodEnd(period) {
-    const quarter = /^(\d{4})-Q([1-4])$/.exec(period);
-    if (quarter) {
-        const end = ['03-31', '06-30', '09-30', '12-31'][Number(quarter[2]) - 1];
-        return `${quarter[1] ?? ''}-${end ?? ''}`;
-    }
-    const month = /^(\d{4})-(\d{2})$/.exec(period);
-    if (month) {
-        const last = new Date(Date.UTC(Number(month[1]), Number(month[2]), 0));
-        return last.toISOString().slice(0, 10);
+const utcDay = (year, month, day) => new Date(Date.UTC(year, month - 1, day)).toISOString().slice(0, 10);
+// The last day of the period a key from periodKey names. A calendar year and
+// a cardmember year share the key shape ("2026"), so the kind is needed: a
+// cardmember year ends the day before the next anniversary. null for a
+// cardmember year without an anniversary, or a key that doesn't fit the kind.
+export function periodEnd(period, key, anniversary) {
+    switch (period) {
+        case 'month': {
+            const m = /^(\d{4})-(\d{2})$/.exec(key);
+            return m ? utcDay(Number(m[1]), Number(m[2]) + 1, 0) : null;
+        }
+        case 'quarter': {
+            const q = /^(\d{4})-Q([1-4])$/.exec(key);
+            return q ? utcDay(Number(q[1]), Number(q[2]) * 3 + 1, 0) : null;
+        }
+        case 'calendar_year':
+            return /^\d{4}$/.test(key) ? `${key}-12-31` : null;
+        case 'cardmember_year': {
+            const a = anniversary === null ? null : /^(\d{2})-(\d{2})$/.exec(anniversary);
+            if (!a || !/^\d{4}$/.test(key))
+                return null;
+            // Date.UTC rolls over; a parsed "2027-02-29" would be invalid.
+            return utcDay(Number(key) + 1, Number(a[1]), Number(a[2]) - 1);
+        }
     }
-    return /^\d{4}$/.test(period) ? `${period}-12-31` : null;
+}
+// The last day of the period `date` falls in.
+export function currentPeriodEnd(period, date, anniversary) {
+    const key = periodKey(period, date, anniversary);
+    return key === null ? null : periodEnd(period, key, anniversary);
 }

package/dist/engine/recommend.js

@@ -2,13 +2,20 @@ 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 FOREIGN_ASSUMPTION = 'Treats this as a purchase outside the U.S.: each card is ranked after its foreign transaction fee.';
+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 +73,23 @@ 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,
+            rateReturnPct: evaluation.best.rate * valuation.centsPerUnit - fee,
+            upside: perDollar * (valuation.range?.[1] ?? valuation.centsPerUnit) - fee,
         });
     }
     entries.sort(compareEntries);
@@ -96,6 +112,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, valuation.centsPerUnit));
     if (valuation.pooledFrom !== null) {
         const partners = card.pools_into?.when_wallet_has ?? [];
         const heldPartners = wallet.cards
@@ -106,7 +124,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.evaluation.best.rate * valuation.centsPerUnit)} back.`);
     }
     return lines;
 }
@@ -114,6 +132,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`
         : '';
@@ -164,10 +186,19 @@ function toRanked(catalog, wallet, entry, purchase) {
         rate: evaluation.best.rate,
         currency: valuation.currency,
         centsPerUnit: valuation.centsPerUnit,
-        effectiveReturnPct: entry.effectiveReturnPct,
+        effectiveReturnPct: entry.rateReturnPct,
+        foreignFee: entry.fee > 0 ? entry.fee : null,
         earned: purchase.amount === null
             ? null
-            : Math.round(purchase.amount * entry.effectiveReturnPct) / 100,
+            : Math.round(purchase.amount * entry.rateReturnPct) / 100,
+        milestoneBonus: entry.milestones.length === 0
+            ? null
+            : {
+                points: milestonePoints(entry.milestones),
+                dollars: roundCents((milestonePoints(entry.milestones) *
+                    entry.valuation.centsPerUnit) /
+                    100),
+            },
         capped: evaluation.best.cap !== null,
         reasoning: reasoningFor(catalog, wallet, entry, purchase.amount),
         warnings: warningsFor(catalog, entry, purchase),
@@ -194,6 +225,8 @@ function tieNote(entries) {
 // Finds the closest point inside a currency's value range where the winner
 // stops winning, varying one currency at a time. Returns are linear in the
 // cents-per-point value, so each pair of cards flips at most once.
+// "Chase Ultimate Rewards points", but not "IHG One Rewards points points".
+const pointsName = (label) => /\b(points|miles)$/i.test(label) ? label : `${label} points`;
 function sensitivity(catalog, entries) {
     const [winner, ...rest] = entries;
     if (!winner)
@@ -208,18 +241,19 @@ 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)}¢).`);
+                consider((w.centsPerUnit - threshold) / w.centsPerUnit, `${displayName(other)} beats ${displayName(winner)} here if ${pointsName(currencyLabel(catalog, w.currency))} 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)}¢).`);
+                consider((threshold - o.centsPerUnit) / o.centsPerUnit, `${displayName(other)} beats ${displayName(winner)} here if ${pointsName(currencyLabel(catalog, o.currency))} are worth ${worthAbove(threshold)} (you value them at ${num(o.centsPerUnit)}¢).`);
             }
         }
     }
@@ -234,7 +268,19 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
         assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
     }
     else if (merchant.category === 'other') {
-        assumptions.push(`Assumes ${merchant.resolvedName} falls outside the usual bonus categories.`);
+        // A card whose rule names this store by name (Audible on Amex's
+        // streaming list) earns its bonus there anyway.
+        const naming = entries.flatMap((e) => {
+            const rule = e.evaluation.best.rule;
+            return rule &&
+                merchant.merchantId !== null &&
+                (rule.match.merchants ?? []).includes(merchant.merchantId)
+                ? [`${displayName(e)} (${ruleWhat(catalog, rule)})`]
+                : [];
+        });
+        assumptions.push(naming.length === 0
+            ? `Assumes ${merchant.resolvedName} falls outside the usual bonus categories.`
+            : `Assumes ${merchant.resolvedName} falls outside the usual bonus categories, except on cards that name it: ${listed(naming)}.`);
     }
     else {
         assumptions.push(codesAs(catalog, merchant));
@@ -251,6 +297,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(FOREIGN_ASSUMPTION);
+    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 +310,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,14 +26,26 @@ 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 ?? [];
-    // A long list of one kind of store reads as "select streaming services".
-    const kinds = new Set(merchants.map((m) => findMerchant(catalog, m)?.category));
-    const [kind] = kinds;
-    const merchantParts = merchants.length > 4 && kinds.size === 1 && kind !== undefined
+    // A long list of mostly one kind of store reads as "select streaming
+    // services": Amex's streaming list also names Audible, which isn't one.
+    const counts = new Map();
+    for (const m of merchants) {
+        const category = findMerchant(catalog, m)?.category;
+        if (category)
+            counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+    const [kind, count = 0] = [...counts].sort((a, b) => b[1] - a[1])[0] ?? [];
+    const merchantParts = merchants.length > 4 &&
+        kind !== undefined &&
+        count >= merchants.length * 0.75
         ? [`select ${categoryPhrase(catalog, kind)}`]
         : merchants.map((m) => merchantName(catalog, m));
     const parts = [

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/recommendation.js

@@ -30,7 +30,10 @@ function cardLines(cards, style, bonusPick) {
     const pctWidth = Math.max(...cards.map((c) => pct(c.effectiveReturnPct).length));
     const lines = [];
     cards.forEach((c) => {
-        const earned = c.earned === null ? '' : `  ${dollarsAndCents(c.earned)}`;
+        const earned = (c.earned === null ? '' : `  ${dollarsAndCents(c.earned)}`) +
+            (c.milestoneBonus === null
+                ? ''
+                : ` + ${money(c.milestoneBonus.dollars)} spend bonus`);
         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)
@@ -53,9 +56,12 @@ export function formatRecommendation(rec, purchase, { all = false, style = plain
     const noCard = noCardText(rec.merchant.resolvedName);
     if (rec.decision && top) {
         const earned = top.earned === null ? '' : `, about ${dollarsAndCents(top.earned)}`;
+        const milestone = top.milestoneBonus === null
+            ? ''
+            : `, plus a spend bonus worth about ${money(top.milestoneBonus.dollars)}`;
         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}.`)} ${capitalize(confidence)} confidence.`);
+        lines.push(`${style('bold', `Use ${label(top)}${why}: ${pct(top.effectiveReturnPct)} back${earned}${milestone}.`)} ${capitalize(confidence)} confidence.`);
         if (rec.bonus && rec.notes[0])
             lines.push(rec.notes[0]);
     }