earnrate 0.2.7 → 0.2.9

package/dist/engine/milestones.js

@@ -0,0 +1,83 @@
+import { periodEnd, periodKey } from "./periods.js";
+import { listed, MILESTONE_PERIODS, money, roundCents, wholeDollars, } from "./text.js";
+export function milestoneProgress(card, held, date) {
+    return card.milestones.map((milestone) => {
+        const period = periodKey(milestone.period, date, held.anniversary ?? null);
+        const usage = held.milestone_usage?.[milestone.id];
+        return {
+            milestone,
+            period,
+            spent: usage !== undefined && usage.period === period ? usage.spent : 0,
+            tracked: usage !== undefined,
+        };
+    });
+}
+// The milestones this purchase reaches: tracked spending before it is under
+// the total, and with it the total is met.
+export function milestonesReached(card, held, date, amount) {
+    if (amount === null || amount <= 0)
+        return [];
+    return milestoneProgress(card, held, date).flatMap(({ milestone: m, period, spent, tracked }) => tracked &&
+        period !== null &&
+        spent < m.spend &&
+        m.spend <= roundCents(spent + amount)
+        ? [
+            {
+                id: m.id,
+                spend: m.spend,
+                period,
+                before: spent,
+                points: m.points ?? null,
+                rewards: m.rewards ?? [],
+            },
+        ]
+        : []);
+}
+export const milestonePoints = (hits) => hits.reduce((sum, h) => sum + (h.points ?? 0), 0);
+// "10,000 bonus points and Gold Elite status"
+export function milestonePays(m) {
+    return listed([
+        ...(m.points === undefined || m.points === null
+            ? []
+            : [`${m.points.toLocaleString('en-US')} bonus points`]),
+        ...(m.rewards ?? []),
+    ]);
+}
+// "the $15,000 calendar-year spend for 10,000 bonus points"
+export const milestoneWhat = (m) => `the ${wholeDollars(m.spend)} ${MILESTONE_PERIODS[m.period]} spend for ${milestonePays(m)}`;
+export function reachedText(card, hit) {
+    const m = card.milestones.find((x) => x.id === hit.id);
+    if (!m)
+        return '';
+    return `This purchase reaches ${milestoneWhat(m)} (${money(hit.before)} tracked on this card in ${hit.period} before it).`;
+}
+const THIS_PERIOD = {
+    calendar_year: 'this year',
+    cardmember_year: 'this cardmember year',
+};
+export function milestoneSummaries(card, held, today) {
+    return milestoneProgress(card, held, today).map(({ milestone: m, period, spent, tracked }) => {
+        const pays = milestonePays(m);
+        const text = period === null
+            ? `${wholeDollars(m.spend)} a cardmember year for ${pays}: give the card's anniversary to track it.`
+            : !tracked
+                ? `${wholeDollars(m.spend)} ${THIS_PERIOD[m.period]} for ${pays}; spending toward it isn't tracked yet.`
+                : spent >= m.spend
+                    ? `${wholeDollars(m.spend)} reached ${THIS_PERIOD[m.period]}: ${pays}.`
+                    : `${money(spent)} of ${wholeDollars(m.spend)} ${THIS_PERIOD[m.period]} for ${pays}.`;
+        return {
+            id: m.id,
+            spend: m.spend,
+            period: m.period,
+            currentPeriod: period,
+            until: period === null
+                ? null
+                : periodEnd(m.period, period, held.anniversary ?? null),
+            spent,
+            tracked,
+            points: m.points ?? null,
+            rewards: m.rewards ?? [],
+            text,
+        };
+    });
+}

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,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`
         : '';
@@ -146,6 +166,10 @@ function warningsFor(catalog, entry, purchase) {
         warnings.push(`Your chosen categories are set for ${evaluation.staleChoice}, not the current period, so chosen-category bonuses don't apply until you update them.`);
     }
     for (const rule of evaluation.needsActivation) {
+        if (rule.activate_by !== undefined && rule.activate_by < purchase.date) {
+            warnings.push(`The bonus here (${earnText(catalog, rule.rate, valuation.currency)}) needed activating by ${shortDate(rule.activate_by)}.`);
+            continue;
+        }
         warnings.push(`Activate this bonus with the issuer (it's free)${rule.activate_by === undefined ? '' : ` by ${shortDate(rule.activate_by)}`} to earn ${earnText(catalog, rule.rate, valuation.currency)} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
     }
     return warnings;
@@ -161,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,
@@ -204,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)}¢).`);
             }
@@ -247,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)) {
@@ -255,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,12 +40,14 @@ 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
         .filter((r) => r.requires?.activation === true &&
         (r.valid_to === undefined || r.valid_to >= today) &&
+        (r.activate_by === undefined || r.activate_by >= today) &&
         (r.valid_from === undefined ||
             daysBetween(today, r.valid_from) <= ACTIVATION_LOOKAHEAD_DAYS))
         .map((r) => r.id);
@@ -73,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,
@@ -93,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
@@ -161,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

@@ -1,3 +1,4 @@
+import { CARD_NUMBER_LABEL, labelHasCardNumber } from "../schema/card-number.js";
 import { WALLET_VERSION, } from "../schema/wallet.js";
 import { addMonths } from "./bonus.js";
 import { capByKey } from "./evaluate.js";
@@ -33,9 +34,8 @@ export function cardFields(card, held, input, today) {
     else if (input.checkoutLabel !== undefined) {
         if (input.checkoutLabel.trim() === '')
             problems.push('The checkout label is empty.');
-        // earnrate never stores card numbers; a last four is fine.
-        if (/\d{8,}/.test(input.checkoutLabel.replace(/[\s-]/g, '')))
-            problems.push('The checkout label looks like it has a card number in it. earnrate never stores card numbers; use a name like "Amex Gold".');
+        if (labelHasCardNumber(input.checkoutLabel))
+            problems.push(CARD_NUMBER_LABEL);
         fields.checkout_label = input.checkoutLabel.trim();
     }
     if (input.anniversary !== undefined) {
@@ -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]' : ''}`,