earnrate 0.2.8 → 0.2.9

package/dist/cli/args.js

@@ -1,6 +1,7 @@
 import { parseArgs } from 'node:util';
 import { isValuationProfile, } from "../engine/profiles.js";
 import { knownMemberships } from "../engine/setup.js";
+import { COUNTRY_CODE, countryProblem } from "../schema/common.js";
 // Shared by every subcommand, so each flag means the same thing everywhere.
 // A string result is the error to show.
 const LOOKS_LIKE_AMOUNT = /^\$?[\d,]*\.?\d+$/;
@@ -109,12 +110,8 @@ export function parseCliArgs(argv) {
         ? values.valuation
         : null;
     const country = values.country ?? 'US';
-    if (!/^[A-Za-z]{2}$/.test(country)) {
-        return {
-            kind: 'error',
-            message: `"${country}" isn't a country code. Use two letters, like US or FR.`,
-        };
-    }
+    if (!COUNTRY_CODE.test(country))
+        return { kind: 'error', message: countryProblem(country) };
     return {
         kind: 'run',
         options: {

package/dist/cli/explore.js

@@ -6,6 +6,7 @@ import { isValuationProfile, profileText, VALUATION_PROFILES, withValuationProfi
 import { resolveSpendLines, simulateAdditions, simulateCatalog, spendLineFor, typicalSpend, TYPICAL_SPEND_NOTE, } from "../engine/simulate.js";
 import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../format/explore.js";
 import { BOTH_CHANNELS, cardList, channelOf, dateProblem, membershipProblem, splitAmount, valuationProblem, } from "./args.js";
+import { COUNTRY_CODE, countryProblem } from "../schema/common.js";
 import { cardsToUse, RUNTIME_ERROR, savedSettings, USAGE_ERROR, } from "./run.js";
 const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or points and miles cards only.
   --no-fee                Cards with no annual fee.
@@ -30,6 +31,8 @@ Options:
 ${FILTER_OPTIONS}
   --online, --in-store    How you're paying. Default: inferred from the merchant.
   --date <YYYY-MM-DD>     Purchase date. Default: today.
+  --country <code>        Where you're paying. Abroad, cards rank after their
+                          foreign transaction fees. Default: US.
   --all                   List every card, not just the top 10.
   --json                  Print the full result as JSON.
   -h, --help              Show this help.
@@ -104,6 +107,7 @@ export async function runBest(argv, io) {
                 online: { type: 'boolean' },
                 'in-store': { type: 'boolean' },
                 date: { type: 'string' },
+                country: { type: 'string' },
             },
         });
     }
@@ -135,6 +139,11 @@ export async function runBest(argv, io) {
         io.stderr(`${dated}\n`);
         return USAGE_ERROR;
     }
+    const country = values.country ?? 'US';
+    if (!COUNTRY_CODE.test(country)) {
+        io.stderr(`${countryProblem(country)}\n`);
+        return USAGE_ERROR;
+    }
     const catalog = await loadCatalog();
     const settings = settingsFrom(values, catalog, await savedSettings(io));
     if (typeof settings === 'string') {
@@ -147,6 +156,7 @@ export async function runBest(argv, io) {
         amount,
         channel: channelOf(values),
         date: values.date ?? io.today,
+        country: country.toUpperCase(),
     }, settings);
     io.stdout(values.json
         ? `${JSON.stringify(result, null, 2)}\n`

package/dist/cli/import.js

@@ -41,10 +41,10 @@ const LedgerSchema = z.strictObject({
     // sha256 of card, date, amount and description. Not reversible.
     recorded: z.array(z.string()),
 });
-// Caps and welcome bonuses are recorded separately, so a purchase imported
-// for its cap still counts toward a bonus added to the wallet later.
+// Caps, welcome bonuses and spend milestones are recorded separately, so a
+// purchase imported for its cap still counts toward a bonus added later.
 const fingerprint = ({ cardId, line }, kind = 'cap') => createHash('sha256')
-    .update(`${kind === 'bonus' ? 'bonus|' : ''}${cardId}|${line.date}|${String(line.amount)}|${line.description}`)
+    .update(`${kind === 'cap' ? '' : `${kind}|`}${cardId}|${line.date}|${String(line.amount)}|${line.description}`)
     .digest('hex');
 // "statement.csv:chase-sapphire-preferred" names the card inline.
 function splitTarget(arg) {
@@ -132,6 +132,9 @@ function formatAnalysis(a, labelOf, valuation, categoryName) {
     for (const b of a.bonuses) {
         out.push(`Welcome bonus on ${labelOf(b.cardId)}: ${dollarsAndCents(b.before)} → ${dollarsAndCents(b.after)} of ${dollarsAndCents(b.spend)}${b.deadline ? ` by ${b.deadline}` : ''}.`);
     }
+    for (const m of a.milestones) {
+        out.push(`Spend bonus on ${labelOf(m.cardId)}: ${dollarsAndCents(m.before)} → ${dollarsAndCents(m.after)} of ${dollarsAndCents(m.spend)} for ${m.period}${m.before < m.spend && m.after >= m.spend ? ', reached' : ''}.`);
+    }
     return `${out.join('\n')}\n`;
 }
 export async function runImport(argv, io) {
@@ -229,6 +232,12 @@ export async function runImport(argv, io) {
     ], values.valuation);
     io.stdout(formatAnalysis(analysis, labelOf, valuation, categoryName));
     const bonusEntries = analysis.bonuses.flatMap((b) => b.entries);
+    // A purchase counts toward each of its card's milestones; record it once.
+    const milestoneEntries = [
+        ...new Map(analysis.milestones
+            .flatMap((m) => m.entries)
+            .map((e) => [fingerprint(e, 'milestone'), e])).values(),
+    ];
     const toRecord = [
         ...(analysis.bookings.length > 0
             ? [`${String(analysis.bookings.length)} purchase(s) against your caps`]
@@ -236,6 +245,9 @@ export async function runImport(argv, io) {
         ...(bonusEntries.length > 0
             ? [`${String(bonusEntries.length)} toward welcome bonuses`]
             : []),
+        ...(milestoneEntries.length > 0
+            ? [`${String(milestoneEntries.length)} toward spend bonuses`]
+            : []),
     ];
     if (!values.apply || toRecord.length === 0) {
         io.stdout(values.apply || toRecord.length === 0
@@ -243,11 +255,13 @@ export async function runImport(argv, io) {
             : `Nothing was written. Run again with --apply to record ${toRecord.join(' and ')}.\n`);
         return 0;
     }
-    await writeProgress(walletFile, analysis.bookings.map((e) => e.booking), analysis.bonuses);
+    await writeProgress(walletFile, analysis.bookings.map((e) => e.booking), analysis.bonuses, analysis.milestones);
     for (const entry of analysis.bookings)
         recorded.add(fingerprint(entry));
     for (const entry of bonusEntries)
         recorded.add(fingerprint(entry, 'bonus'));
+    for (const entry of milestoneEntries)
+        recorded.add(fingerprint(entry, 'milestone'));
     await writeFileAtomic(ledgerFile, `${JSON.stringify({ version: 1, recorded: [...recorded] }, null, 2)}\n`);
     io.stdout(`Recorded ${toRecord.join(' and ')} in ${displayPath(walletFile)}.\n`);
     return 0;

package/dist/cli/run.js

@@ -65,7 +65,8 @@ Options:
   --all                  List every card, not just the top three.
   --json                 Print the full recommendation as JSON.
   --date <YYYY-MM-DD>    Purchase date. Default: today.
-  --country <code>       Where you're paying. Default: US.
+  --country <code>       Where you're paying. Abroad, cards rank after their
+                         foreign transaction fees. Default: US.
   --cards <ids>          Answer for these cards instead of your wallet, comma
                          separated: --cards amex-gold,chase-prime-visa.
   --member <name>        A membership you have, in place of the saved ones.
@@ -237,6 +238,7 @@ export async function run(argv, io) {
             amount: purchase.amount,
             channel: purchase.channel,
             date: purchase.date,
+            country: purchase.country,
         }, {
             filters: ALL_PERSONAL_CARDS,
             memberships: options.members.length > 0 ? options.members : saved.memberships,

package/dist/cli/wallet.js

@@ -5,6 +5,7 @@ import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
 import { isValuationProfile, profileText, VALUATION_PROFILES, } from "../engine/profiles.js";
 import { membershipName } from "../engine/memberships.js";
 import { knownMemberships, searchCards } from "../engine/setup.js";
+import { currencyChanges } from "../engine/wallet-change.js";
 import { formatCardInfo, formatNotes } from "../format/cards.js";
 import { displayPath, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
 const CARD_OPTIONS = `Options:
@@ -195,13 +196,16 @@ export async function runWalletCommand(command, argv, io) {
                 return usage(`"${arg}" isn't <currency>=<cents>, like UR=1.5.`);
             changes[id] = cents;
         }
+        const given = currencyChanges(catalog, changes);
+        if (!given.ok)
+            return usage(given.error);
         if (Object.keys(changes).length === 0) {
             const held = await heldWallet(io);
             const set = Object.entries(held?.valuations ?? {});
             io.stdout(`${set.length > 0 ? `Yours: ${set.map(([id, v]) => `${id}=${typeof v === 'number' ? String(v) : JSON.stringify(v)}`).join(' ')}` : "Yours: earnrate's defaults"}\nCurrencies: ${catalog.currencies.map((c) => c.id).join(', ')}\n`);
             return 0;
         }
-        return report(await store.setValuations(changes), `Point values updated in ${where}: ${Object.entries(changes)
+        return report(await store.setValuations(given.changes), `Point values updated in ${where}: ${Object.entries(given.changes)
             .map(([id, c]) => `${id} ${c === null ? 'back to the default' : `${String(c)}¢`}`)
             .join(', ')}.`, null, io);
     }

package/dist/data/file-store.js

@@ -87,8 +87,8 @@ export class FileWalletStore {
                 return failed(`${purchase.cardId} isn't in the wallet.`);
             const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
             try {
-                if (booked.cap || booked.bonus)
-                    await writeProgress(this.where, booked.cap ? [booked.cap] : [], booked.bonus ? [booked.bonus] : []);
+                if (booked.cap || booked.bonus || booked.milestones.length > 0)
+                    await writeProgress(this.where, booked.cap ? [booked.cap] : [], booked.bonus ? [booked.bonus] : [], booked.milestones);
             }
             catch (e) {
                 return failed(errorText(e));

package/dist/data/integrity.js

@@ -86,12 +86,23 @@ function cardProblems(card, catalog, merchantIds) {
         ['rule', card.rules.map((r) => r.id)],
         ['cap', card.caps.map((c) => c.id)],
         ['choice', card.choices.map((c) => c.id)],
+        ['milestone', card.milestones.map((m) => m.id)],
     ]) {
         for (const id of duplicates(ids))
             problems.push(`${where}: duplicate ${kind} id '${id}'`);
     }
+    // Evidence names rules and milestones alike, so their ids can't overlap.
+    for (const m of card.milestones)
+        if (card.rules.some((r) => r.id === m.id))
+            problems.push(`${where}: milestone '${m.id}' has a rule's id`);
+    if (card.foreign_transaction_fee === null &&
+        !card.todo.some((t) => /foreign transaction fee/i.test(t)))
+        problems.push(`${where}: foreign_transaction_fee is null without a todo saying why`);
     const ruleIds = new Set([
         'base_rate',
+        ...(card.foreign_transaction_fee !== null
+            ? ['foreign_transaction_fee']
+            : []),
         ...(card.pools_into ? ['pools_into'] : []),
         ...(card.annual_fee !== undefined ? ['annual_fee'] : []),
         ...(card.first_year_fee !== undefined ? ['first_year_fee'] : []),
@@ -99,6 +110,7 @@ function cardProblems(card, catalog, merchantIds) {
         ...(card.welcome_offer?.not_with ? ['not_with'] : []),
         ...(card.requires_membership ? ['requires_membership'] : []),
         ...card.rules.map((r) => r.id),
+        ...card.milestones.map((m) => m.id),
     ]);
     const sourcePages = new Set(card.source_urls.map((u) => u.split('#')[0]));
     const backed = new Set(card.evidence.map((e) => e.rule));
@@ -248,6 +260,11 @@ export function walletProblems(wallet, catalog) {
             if (!capKeys.has(key))
                 problems.push(`${where} cap_usage: '${key}' is not a cap on this card`);
         }
+        const milestoneIds = new Set(card.milestones.map((m) => m.id));
+        for (const key of Object.keys(held.milestone_usage ?? {})) {
+            if (!milestoneIds.has(key))
+                problems.push(`${where} milestone_usage: '${key}' is not a spend milestone on this card`);
+        }
         if (held.chosen) {
             for (const [choiceId, picks] of Object.entries(held.chosen.picks)) {
                 const choice = card.choices.find((c) => c.id === choiceId);

package/dist/data/store.js

@@ -86,7 +86,7 @@ export class JsonWalletStore {
             if (!wallet.cards.some((c) => c.id === purchase.cardId))
                 return failed(`${purchase.cardId} isn't in the wallet.`);
             const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
-            if (booked.cap || booked.bonus)
+            if (booked.cap || booked.bonus || booked.milestones.length > 0)
                 await this.backend.write(JSON.stringify(booked.wallet));
             return { ok: true, ...booked };
         });

package/dist/data/wallet-edit.js

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { writeFileAtomic } from "./atomic-write.js";
 import { isDeepStrictEqual } from 'node:util';
 import { isMap, isSeq, parseDocument, stringify } from 'yaml';
-import { applyBonusBooking, applyBooking, } from "../engine/record.js";
+import { applyBonusBooking, applyBooking, applyMilestoneBooking, } from "../engine/record.js";
 import { WALLET_VERSION, WalletSchema } from "../schema/wallet.js";
 const NEW_WALLET = `# Your earnrate wallet: the cards you hold, by id. Never card numbers.
 # Format: https://github.com/cwasley/earnrate#your-wallet
@@ -47,6 +47,14 @@ function fieldLines(field, f, indent) {
                 .join('');
             return caps === '' ? '' : `${indent}cap_usage:\n${caps}`;
         }
+        case 'milestone_usage': {
+            if (f.milestone_usage === undefined)
+                return '';
+            const entries = Object.entries(f.milestone_usage)
+                .map(([key, u]) => `${indent}  ${key}: { period: ${scalar(u.period)}, spent: ${String(u.spent)} }\n`)
+                .join('');
+            return entries === '' ? '' : `${indent}milestone_usage:\n${entries}`;
+        }
         case 'bonus': {
             if (!f.bonus)
                 return '';
@@ -81,6 +89,7 @@ const FIELDS = [
     'chosen',
     'activated',
     'cap_usage',
+    'milestone_usage',
     'bonus',
 ];
 function cardsSeq(text) {
@@ -270,31 +279,30 @@ function setValuationText(text, id, cents) {
     const indent = ' '.repeat(column(text, range(first?.key)[0]));
     return insertLines(text, afterLine(text, range(last?.value ?? last?.key)[1] - 1), `${indent}${line}\n`);
 }
-function flowUsage(booking) {
-    const period = /^\d+$/.test(booking.period)
-        ? `"${booking.period}"`
-        : booking.period;
-    return `{ period: ${period}, spent: ${String(booking.after)} }`;
+function flowUsage(period, spent) {
+    const key = /^\d+$/.test(period) ? `"${period}"` : period;
+    return `{ period: ${key}, spent: ${String(spent)} }`;
 }
-function capUsageText(text, booking) {
-    const card = findCard(text, booking.cardId);
-    const value = flowUsage(booking);
-    const usage = card.get('cap_usage', true);
+// Sets one entry of a card's cap_usage or milestone_usage, adding the map
+// when the card has none.
+function usageText(text, cardId, field, key, value) {
+    const card = findCard(text, cardId);
+    const usage = card.get(field, true);
     if (isMap(usage) && !usage.flow && usage.items.length > 0) {
-        const existing = usage.items.find((p) => keyOf(p) === booking.capKey);
+        const existing = usage.items.find((p) => keyOf(p) === key);
         if (existing) {
             const [start, end] = range(existing.value);
             return text.slice(0, start) + value + text.slice(end);
         }
         const indent = ' '.repeat(column(text, range(usage.items[0]?.key)[0]));
         const at = afterLine(text, range(usage)[1] - 1);
-        return insertLines(text, at, `${indent}${booking.capKey}: ${value}\n`);
+        return insertLines(text, at, `${indent}${key}: ${value}\n`);
     }
     if (usage !== undefined)
-        throw new Error(`card '${booking.cardId}' has a cap_usage that isn't a block map; ${BY_HAND}`);
+        throw new Error(`card '${cardId}' has a ${field} that isn't a block map; ${BY_HAND}`);
     const indent = ' '.repeat(column(text, range(card.items[0]?.key)[0]));
     const at = afterLine(text, range(card)[1] - 1);
-    return insertLines(text, at, `${indent}cap_usage:\n${indent}  ${booking.capKey}: ${value}\n`);
+    return insertLines(text, at, `${indent}${field}:\n${indent}  ${key}: ${value}\n`);
 }
 function bonusSpentText(text, cardId, spent) {
     const bonus = findCard(text, cardId).get('bonus', true);
@@ -314,24 +322,30 @@ function bonusSpentText(text, cardId, spent) {
     const at = afterLine(text, range(bonus)[1] - 1);
     return insertLines(text, at, `${indent}spent: ${value}\n`);
 }
-// Writes spending toward caps and welcome bonuses in one checked write.
-export async function writeProgress(file, caps, bonuses) {
+// Writes spending toward caps, welcome bonuses and spend milestones in one
+// checked write.
+export async function writeProgress(file, caps, bonuses, milestones = []) {
     const { text, wallet } = await readWalletText(file);
     if (text === null || wallet === null)
         throw new Error(`No wallet at ${file}.`);
     let after = text;
     let expected = wallet;
     for (const b of caps) {
-        after = capUsageText(after, b);
+        after = usageText(after, b.cardId, 'cap_usage', b.capKey, flowUsage(b.period, b.after));
         expected = applyBooking(expected, b);
     }
+    for (const m of milestones) {
+        after = usageText(after, m.cardId, 'milestone_usage', m.milestoneId, flowUsage(m.period, m.after));
+        expected = applyMilestoneBooking(expected, m);
+    }
     for (const b of bonuses) {
         after = bonusSpentText(after, b.cardId, b.after);
         expected = applyBonusBooking(expected, b);
     }
     const byHand = [
-        ...caps.map((b) => `${b.cardId} cap_usage ${b.capKey}: ${flowUsage(b)}`),
+        ...caps.map((b) => `${b.cardId} cap_usage ${b.capKey}: ${flowUsage(b.period, b.after)}`),
         ...bonuses.map((b) => `${b.cardId} bonus spent: ${String(b.after)}`),
+        ...milestones.map((m) => `${m.cardId} milestone_usage ${m.milestoneId}: ${flowUsage(m.period, m.after)}`),
     ].join('; ');
     await commitWalletText(file, after, expected, `add it by hand: ${byHand}`);
 }

package/dist/engine/cheat-sheet.js

@@ -3,7 +3,7 @@ import { exploreCards } from "./explore.js";
 import { bonusStatus } from "./bonus.js";
 import { EPSILON, isClose } from "./compare.js";
 import { periodKey } from "./periods.js";
-import { recommend } from "./recommend.js";
+import { ABROAD, recommend } from "./recommend.js";
 import { checklist } from "./checklist.js";
 import { setupNotes } from "./setup.js";
 import { capitalize, feeText, listed, money, shortDate } from "./text.js";
@@ -16,7 +16,7 @@ export const EVERYDAY_PURCHASES = [
     { label: 'Amazon', merchant: 'amazon' },
     { label: 'Costco', merchant: 'costco' },
     { label: 'Travel', category: 'travel' },
-    { label: 'Streaming', category: 'streaming' },
+    { label: 'Streaming (Netflix)', merchant: 'netflix' },
     { label: 'Drugstores', category: 'drugstore' },
     { label: 'Everything else', category: 'other' },
 ];
@@ -50,6 +50,7 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
             note: top?.warnings[0] ?? null,
         };
     });
+    rows.push(abroadRow(catalog, wallet, date));
     const bonuses = wallet.cards.flatMap((held) => {
         const status = bonusStatus(catalog, wallet, held, date);
         if (status?.state !== 'open')
@@ -106,6 +107,31 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
         notes,
     };
 }
+const ABROAD_LABEL = 'Abroad';
+// Everyday spending outside the U.S., after each card's foreign transaction
+// fee.
+function abroadRow(catalog, wallet, date) {
+    const merchant = categoryResolution(catalog, 'other', null);
+    const rec = recommend(catalog, wallet, {
+        merchant: merchant.input,
+        amount: null,
+        channel: null,
+        date,
+        country: ABROAD,
+    }, merchant);
+    const top = rec.decision ? rec.ranked[0] : undefined;
+    const allCharge = rec.ranked.length > 0 && rec.ranked.every((r) => r.foreignFee !== null);
+    return {
+        label: ABROAD_LABEL,
+        cardId: top?.cardId ?? null,
+        cardName: top ? (top.checkoutLabel ?? top.cardName) : null,
+        effectiveReturnPct: top?.effectiveReturnPct ?? null,
+        matchedRule: top?.matchedRule ?? null,
+        note: allCharge
+            ? `Every card here charges a foreign transaction fee abroad; this one costs the least. ${top?.warnings[0] ?? ''}`.trim()
+            : (top?.warnings[0] ?? null),
+    };
+}
 // The best card earnrate knows for each everyday kind of purchase, for
 // someone who hasn't named any cards. Each row's note says what the card
 // costs or needs.
@@ -139,6 +165,24 @@ export function catalogCheatSheet(catalog, date, options, items = EVERYDAY_PURCH
                 : null,
         };
     });
+    const abroad = exploreCards(catalog, {
+        merchant: null,
+        category: 'other',
+        amount: null,
+        channel: null,
+        date,
+        country: ABROAD,
+    }, options).ranked[0];
+    rows.push({
+        label: ABROAD_LABEL,
+        cardId: abroad?.cardId ?? null,
+        cardName: abroad?.cardName ?? null,
+        effectiveReturnPct: abroad?.effectiveReturnPct ?? null,
+        matchedRule: abroad?.matchedRule ?? null,
+        note: abroad
+            ? [`${capitalize(feeText(abroad))}.`, ...abroad.conditions].join(' ')
+            : null,
+    });
     const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
     return {
         scope: 'all cards',

package/dist/engine/checklist.js

@@ -1,5 +1,6 @@
-import { daysBetween, periodEnd, periodKey } from "./periods.js";
+import { currentPeriodEnd, daysBetween } from "./periods.js";
 import { CAP_PERIODS, choiceName, listed, money, shortDate, wholeDollars, } from "./text.js";
+import { milestonePays } from "./milestones.js";
 import { optionName } from "./rule-text.js";
 import { activationsDue, walletSummary, } from "./wallet-summary.js";
 // What the wallet's cards need this period, soonest first: bonuses to
@@ -33,24 +34,23 @@ shortName) {
             c.period !== 'until_changed');
         const [first] = unpicked;
         if (first) {
-            const period = first.period === 'until_changed'
+            const due = first.period === 'until_changed'
                 ? null
-                : periodKey(first.period, today, null);
+                : currentPeriodEnd(first.period, today, null);
             items.push({
                 kind: 'pick',
                 cardId: card.id,
                 text: `Pick ${name}'s ${listed(unpicked.map((c) => choiceName(c.id)))} categories for this ${first.period.replace('_', ' ')}; until then they earn the base rate.`,
-                due: period === null ? null : periodEnd(period),
+                due,
             });
         }
         else {
             // Picks made for this period: near its end, a reminder to make the
             // next period's (Cash+ asks each quarter).
             const ending = card.choices.find((c) => c.period !== 'until_changed' && !c.default && current);
-            const period = ending === undefined || ending.period === 'until_changed'
+            const end = ending === undefined || ending.period === 'until_changed'
                 ? null
-                : periodKey(ending.period, today, null);
-            const end = period === null ? null : periodEnd(period);
+                : currentPeriodEnd(ending.period, today, null);
             if (ending && end !== null && daysBetween(today, end) <= 14)
                 items.push({
                     kind: 'pick',
@@ -72,7 +72,7 @@ shortName) {
             // Only caps nearly used up: the rest aren't something to do.
             if (cap.remaining === null || cap.remaining > cap.amount * 0.25)
                 continue;
-            const resets = cap.currentPeriod === null ? null : periodEnd(cap.currentPeriod);
+            const resets = cap.until;
             items.push({
                 kind: 'cap',
                 cardId: card.id,
@@ -82,6 +82,17 @@ shortName) {
                 due: resets,
             });
         }
+        for (const m of s.milestones) {
+            // Like caps: only once at least 75% of the way there.
+            if (!m.tracked || m.spent < m.spend * 0.75 || m.spent >= m.spend)
+                continue;
+            items.push({
+                kind: 'milestone',
+                cardId: card.id,
+                text: `${name}: ${money(m.spent)} of ${wholeDollars(m.spend)} spent toward ${milestonePays(m)}; ${money(m.spend - m.spent)} to go${m.until === null ? '' : ` by ${shortDate(m.until)}`}.`,
+                due: m.until,
+            });
+        }
         const b = s.bonus;
         if (b?.state === 'open' && b.remaining !== null && b.deadline !== null) {
             const weeks = Math.max(1, (b.daysLeft ?? 7) / 7);

package/dist/engine/evaluate.js

@@ -110,6 +110,8 @@ function applicability(card, rule, ctx, held, picked) {
         return 'no';
     if (rule.geography === 'us_only' && ctx.country !== 'US')
         return 'no';
+    if (rule.geography === 'foreign_only' && ctx.country === 'US')
+        return 'no';
     if (!inEffect(rule, ctx.date))
         return 'no';
     const membership = rule.requires?.membership;

package/dist/engine/explore.js

@@ -160,7 +160,7 @@ export function exploreCards(catalog, query, options, resolved) {
         amount: query.amount,
         channel: query.channel,
         date: query.date,
-        country: 'US',
+        country: query.country ?? 'US',
     };
     const ranked = [];
     const excluded = [];

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);
 }