earnrate 0.2.3 → 0.2.5

package/dist/engine/recommend.js

@@ -3,23 +3,13 @@ import { bonusStatus } from "./bonus.js";
 import { evaluateCard, purchaseContext, usableAt, } from "./evaluate.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
-import { categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, num, pointValuesText, } from "./text.js";
+import { EPSILON, isClose } from "./compare.js";
+import { CAP_ADJECTIVES, categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, NETWORK_NAMES, num, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.js";
 import { cardValuation } from "./valuation.js";
-const EPSILON = 1e-9;
 export const STALE_AFTER_DAYS = 180;
+// 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;
-const NETWORK_NAMES = {
-    visa: 'Visa',
-    mastercard: 'Mastercard',
-    amex: 'American Express',
-    discover: 'Discover',
-};
-const PERIOD_WORDS = {
-    month: 'monthly',
-    quarter: 'quarterly',
-    calendar_year: 'calendar-year',
-    cardmember_year: 'cardmember-year',
-};
 const displayName = (e) => e.held.checkout_label ?? e.card.name;
 // "Worth X or more" must hold at X itself, so round up; "less than X" rounds down.
 const roundUp = (n) => String(Math.ceil(n * 100 - EPSILON) / 100);
@@ -123,7 +113,7 @@ function warningsFor(catalog, entry, purchase) {
     const { best, nominal } = evaluation;
     const warnings = [];
     const capLabel = (e) => e.cap
-        ? `${money(e.cap.cap.amount)} ${PERIOD_WORDS[e.cap.cap.period] ?? ''} cap`
+        ? `${money(e.cap.cap.amount)} ${CAP_ADJECTIVES[e.cap.cap.period]} cap`
         : '';
     if (best.cap && best.rule) {
         const { remaining, cap, period } = best.cap;
@@ -154,7 +144,7 @@ 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) {
-        warnings.push(`Activate "${rule.id}" with the issuer to earn ${earnText(catalog, rule.rate, valuation.currency)} here.`);
+        warnings.push(`Activate this bonus with the issuer (it's free) to earn ${earnText(catalog, rule.rate, valuation.currency)} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
     }
     return warnings;
 }
@@ -264,7 +254,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
     const warnings = [];
     const notes = [];
     if (merchant.source === 'none') {
-        warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. A more specific name may find a bonus category.`);
+        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.`);
     }
     if (merchant.source === 'caller') {
         warnings.push(`"${merchant.input}" isn't in earnrate's merchant list, so it uses the category given with the request. Check how it codes on your statement.`);
@@ -279,16 +269,31 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const alternatives = merchant.ambiguity.mayCodeAs.map((c) => categoryPhrase(catalog, c));
         warnings.push(`${merchant.resolvedName} may code as ${alternatives.join(' or ')} instead: ${merchant.ambiguity.note}`);
         for (const category of merchant.ambiguity.mayCodeAs) {
-            const alt = rankEntries(catalog, wallet, purchase, merchant, category)
-                .entries[0];
-            if (alt && winner && alt.card.id !== winner.card.id) {
-                warnings.push(`If it codes as ${categoryPhrase(catalog, category)}, ${displayName(alt)} wins (${num(alt.effectiveReturnPct)}%).`);
-            }
+            const alts = rankEntries(catalog, wallet, purchase, merchant, category).entries;
+            const alt = alts[0];
+            if (!alt || !winner)
+                continue;
+            const as = `If it codes as ${categoryPhrase(catalog, category)}`;
+            // The same pick there may share the top with another card.
+            const twin = alts.find((e) => e.card.id !== winner.card.id &&
+                alt.effectiveReturnPct - e.effectiveReturnPct <= EPSILON);
+            if (alt.card.id !== winner.card.id)
+                warnings.push(`${as}, ${displayName(alt)} wins (${num(alt.effectiveReturnPct)}%).`);
+            else if (twin)
+                warnings.push(`${as}, ${displayName(twin)} earns as much (${num(twin.effectiveReturnPct)}%).`);
         }
     }
     if (!winner) {
-        warnings.push(`None of your cards work at ${merchant.resolvedName}.`);
-        const online = merchant.channel === 'in_store' && merchant.merchantId !== null
+        warnings.push(noCardText(merchant.resolvedName));
+        // Only where the merchant's data says what its website takes: without
+        // that, every network is assumed, and a gas pump has no website.
+        const record = [
+            ...catalog.merchants.overrides,
+            ...catalog.merchants.seed,
+        ].find((m) => m.id === merchant.merchantId);
+        const online = merchant.channel === 'in_store' &&
+            merchant.merchantId !== null &&
+            record?.online?.accepts !== undefined
             ? resolveMerchantById(catalog, merchant.merchantId, 'online')
             : null;
         const alt = online
@@ -313,9 +318,6 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             warnings.push(`${name}'s rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them. If this purchase is in that period's categories, ${name} may earn more. An earnrate update adds them once the issuer announces them.`);
         }
     }
-    const tie = tieNote(entries);
-    if (tie)
-        notes.push(tie);
     for (const id of merchant.bookedVia) {
         const via = resolveMerchantById(catalog, id, purchase.channel);
         if (!via || !winner)
@@ -326,19 +328,37 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             notes.push(`If you book it as ${via.resolvedName}, ${displayName(alt)} earns ${num(alt.effectiveReturnPct)}%.`);
         }
     }
-    const bonus = bonusPick(catalog, wallet, entries, purchase.date);
+    const open = bonusPick(catalog, wallet, entries, purchase.date);
+    // Behind pace, the bonus card takes the pick; on pace, only where it earns
+    // as much as the best card (it costs nothing there). Within a point, it's
+    // mentioned; otherwise the bonus isn't this purchase's business.
+    const gap = open && winner
+        ? winner.effectiveReturnPct - open.entry.effectiveReturnPct
+        : Infinity;
+    // Already the best card, it's the pick anyway: a tie needs no note.
+    const isBest = open !== null && open.entry === winner;
+    const ties = !isBest && gap <= EPSILON;
+    const bonus = open && (open.behind || ties) ? open : null;
+    const best = winner?.effectiveReturnPct ?? 0;
+    if (open && !bonus && isClose(open.entry.effectiveReturnPct, best)) {
+        notes.push(`${displayName(open.entry)} earns ${num(open.entry.effectiveReturnPct)}% here, ${num(gap)} ${gap === 1 ? 'point' : 'points'} less than ${num(best)}%, and would help its welcome bonus (${money(open.status.remaining ?? 0)} more by ${open.status.deadline ?? ''}). You're on pace, so this uses the higher rate.`);
+    }
     const chosen = bonus?.entry ?? winner;
+    // A tie among the top cards doesn't matter when a welcome bonus decides.
+    const tie = bonus ? null : tieNote(entries);
+    if (tie)
+        notes.push(tie);
     const top = ranked.find((r) => r.cardId === chosen?.card.id);
-    const best = ranked[0];
+    const first = ranked[0];
     let bonusResult = null;
-    if (bonus && top && best) {
+    if (bonus && top && first) {
         const { status } = bonus;
         const remaining = status.remaining ?? 0;
         const deadline = status.deadline ?? purchase.date;
         const daysLeft = status.daysLeft ?? 0;
-        const costHere = top.cardId === best.cardId || top.earned === null || best.earned === null
+        const costHere = ties || top.earned === null || first.earned === null
             ? null
-            : Math.round((best.earned - top.earned) * 100) / 100;
+            : roundCents(first.earned - top.earned);
         bonusResult = {
             cardId: top.cardId,
             checkoutLabel: top.checkoutLabel,
@@ -349,16 +369,16 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             costHere,
         };
         const pace = daysLeft >= 7
-            ? ` (about ${money(Math.round(remaining / (daysLeft / 7)))} a week)`
+            ? ` (about ${wholeDollars(remaining / (daysLeft / 7))} a week)`
             : '';
-        const worth = status.value === null
-            ? ''
-            : `, worth about ${money(Math.round(status.value))}`;
-        notes.unshift(`You're working on ${displayName(bonus.entry)}'s welcome bonus: ${money(remaining)} more to spend by ${deadline}${pace}${worth}.${top.cardId === best.cardId
-            ? ''
-            : costHere === null
-                ? ` It earns ${num(top.effectiveReturnPct)}% here against ${num(best.effectiveReturnPct)}% on ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`
-                : ` Using it here earns ${money(costHere)} less than ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`}`);
+        const worth = status.value === null ? '' : `, worth about ${wholeDollars(status.value)}`;
+        notes.unshift(ties
+            ? `${displayName(bonus.entry)} earns as much here as any of your cards, so it's the pick: it helps its welcome bonus, ${money(remaining)} more to spend by ${deadline}${worth}.`
+            : `You're behind pace on ${displayName(bonus.entry)}'s welcome bonus: ${money(remaining)} more to spend by ${deadline}${pace}${worth}.${isBest
+                ? ''
+                : costHere === null
+                    ? ` It earns ${num(top.effectiveReturnPct)}% here against ${num(first.effectiveReturnPct)}% on ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`
+                    : ` Using it here earns ${money(costHere)} less than ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`}`);
     }
     let confidence = merchant.confidence;
     if (confidence === 'high' && chosen && top) {
@@ -386,17 +406,31 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         bonus: bonusResult,
     };
 }
+// Behind a steady pace: less spent than an even share of the spending needed
+// for the days gone by. Ahead of it, the bonus will likely be met anyway, so
+// it doesn't justify a card that earns less.
+function behindPace(status, date) {
+    if (status.spend === null || status.deadline === null)
+        return false;
+    const window = Math.max(1, daysBetween(status.opened, status.deadline));
+    const elapsed = Math.min(window, daysBetween(status.opened, date));
+    return status.spent < (status.spend * elapsed) / window;
+}
 // The open welcome bonus that most needs this purchase: the one with the most
-// spend still needed per day left.
+// spend still needed per day left. Only a bonus behind pace takes the pick
+// (`behind`); one on pace is only mentioned.
 function bonusPick(catalog, wallet, entries, date) {
     let pick = null;
     for (const entry of entries) {
         const status = bonusStatus(catalog, wallet, entry.held, date);
         if (status?.state !== 'open' || date < status.opened)
             continue;
+        const behind = behindPace(status, date);
         const pace = (status.remaining ?? 0) / Math.max(1, status.daysLeft ?? 1);
-        if (!pick || pace > pick.pace)
-            pick = { entry, status, pace };
+        if (!pick ||
+            (behind && !pick.behind) ||
+            (behind === pick.behind && pace > pick.pace))
+            pick = { entry, status, behind, pace };
     }
     return pick;
 }

package/dist/engine/setup.js

@@ -1,4 +1,5 @@
 import { isActivated, pickedCategories } from "./evaluate.js";
+import { membership, membershipName, sameGroup } from "./memberships.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
 // Rules that start within this many days are worth activating now.
@@ -45,7 +46,7 @@ function matcher(card) {
         (token.length >= 5 &&
             haystack.some((w) => editDistance(w, token) <= (token.length >= 8 ? 2 : 1)));
 }
-function needsAnniversary(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'));
 }
@@ -62,10 +63,18 @@ export function membershipsUsed(card) {
         ...new Set(card.rules.flatMap((r) => r.requires?.membership === undefined ? [] : [r.requires.membership])),
     ];
 }
+// Memberships that matter to a card: ones its rates need, and one the card
+// itself needs (a Costco membership for Costco Anywhere).
+export function membershipsFor(card) {
+    return [
+        ...membershipsUsed(card),
+        ...(card.requires_membership ? [card.requires_membership] : []),
+    ];
+}
 export function knownMemberships(catalog) {
-    return [...new Set(catalog.cards.flatMap(membershipsUsed))].sort();
+    return catalog.memberships.map((m) => m.id).sort();
 }
-export function cardInfo(card, wallet, today) {
+export function cardInfo(catalog, card, wallet, today) {
     return {
         id: card.id,
         name: card.name,
@@ -84,6 +93,13 @@ export function cardInfo(card, wallet, today) {
             default: c.default ?? null,
         })),
         memberships: membershipsUsed(card),
+        requiresMembership: card.requires_membership === undefined
+            ? null
+            : {
+                id: card.requires_membership,
+                name: membershipName(catalog, card.requires_membership),
+                annualFee: membership(catalog, card.requires_membership)?.annual_fee ?? 0,
+            },
         activation: activationRules(card, today),
         needsAnniversary: needsAnniversary(card),
     };
@@ -111,7 +127,7 @@ export function searchCards(catalog, query, wallet, today) {
                 .sort(byShortestId)
                 .slice(0, 5);
     return {
-        cards: chosen.map((s) => cardInfo(s.card, wallet, today)),
+        cards: chosen.map((s) => cardInfo(catalog, s.card, wallet, today)),
         exact,
     };
 }
@@ -137,7 +153,8 @@ export function setupNotes(catalog, wallet, held, today) {
                 : `${name} needs its ${choice.id} pick for this period (${String(choice.pick)} of: ${options}). Until then those categories earn the base rate.`,
         });
     }
-    const missing = membershipsUsed(card).filter((m) => !wallet.memberships.includes(m));
+    // With one tier of a group saved, the others aren't missing.
+    const missing = membershipsUsed(card).filter((m) => !wallet.memberships.some((held) => held === m || sameGroup(catalog, held, m)));
     if (missing.length > 0) {
         notes.push({
             kind: 'membership',

package/dist/engine/simulate.js

@@ -1,12 +1,13 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext, usableAt } from "./evaluate.js";
 import { categoryResolution, findCategory, 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 { rotationGap } from "./rotation.js";
-import { roundCents } from "./text.js";
+import { money, roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
-const EPSILON = 1e-9;
+import { EPSILON } from "./compare.js";
 const MONTHS = 12;
 const SHORTLIST = 8; // best single cards considered for pairs
 const PER_LINE = 2; // plus the best cards for each spending line
@@ -44,7 +45,10 @@ function withCurrentPicks(card, held, date) {
 // Spends `lines` every month for a year. Each dollar goes to the card that
 // earns the most on it right then, so spend moves to another card once a
 // cap runs out.
-export function simulateWallet(catalog, wallet, lines, start) {
+export function simulateWallet(catalog, wallet, lines, start, 
+// Cards the person already has: their first year is behind them and any
+// membership they need is paid for.
+held = []) {
     const cards = wallet.cards.map((held) => {
         const card = catalog.cards.find((c) => c.id === held.id);
         if (!card)
@@ -120,7 +124,16 @@ export function simulateWallet(catalog, wallet, lines, start) {
     });
     const rewards = roundCents(lineResults.reduce((sum, l) => sum + l.earned, 0));
     const annualFees = cards.reduce((sum, c) => sum + (c.card.annual_fee ?? 0), 0);
+    const paid = paidMemberships(catalog, {
+        memberships: wallet.memberships,
+        heldCards: held,
+        merchantIds: lines.map((l) => l.merchant.merchantId),
+    });
+    const memberships = membershipCosts(catalog, cards.map((c) => c.card), paid);
+    const membershipFees = memberships.reduce((sum, m) => sum + m.annualFee, 0);
     const notes = [];
+    for (const m of memberships)
+        notes.push(membershipNote(catalog, m));
     const dates = monthDates(start);
     for (const { card } of cards) {
         const gaps = [
@@ -130,9 +143,10 @@ export function simulateWallet(catalog, wallet, lines, start) {
             notes.push(`${card.name}'s rotating categories for ${gaps.join(', ')} aren't in earnrate's data yet, so those quarters count at its everyday rates.`);
         if (card.annual_fee === undefined)
             notes.push(`${card.name}'s annual fee isn't on file, so none is subtracted.`);
-        else if (card.first_year_fee !== undefined &&
+        else if (!held.includes(card.id) &&
+            card.first_year_fee !== undefined &&
             card.first_year_fee !== card.annual_fee)
-            notes.push(`${card.name}'s fee is $${String(card.first_year_fee)} the first year; the yearly figure uses the $${String(card.annual_fee)} that follows.`);
+            notes.push(`${card.name}'s fee is ${money(card.first_year_fee)} the first year; the yearly figure uses the ${money(card.annual_fee)} that follows.`);
     }
     return {
         cards: wallet.cards.map((h) => ({
@@ -142,7 +156,9 @@ export function simulateWallet(catalog, wallet, lines, start) {
         spend: roundCents(lineResults.reduce((sum, l) => sum + l.spend, 0)),
         rewards,
         annualFees,
-        net: roundCents(rewards - annualFees),
+        memberships,
+        membershipFees,
+        net: roundCents(rewards - annualFees - membershipFees),
         lines: lineResults,
         notes,
     };
@@ -192,7 +208,7 @@ function walletWith(base, card, picks, options) {
 function bestSimulation(catalog, base, card, lines, options) {
     let best = null;
     for (const picks of candidatePicks(catalog, card, lines, options.memberships, options.start)) {
-        const sim = simulateWallet(catalog, walletWith(base, card, picks, options), lines, options.start);
+        const sim = simulateWallet(catalog, walletWith(base, card, picks, options), lines, options.start, options.held);
         if (!best || sim.net > best.net + EPSILON)
             best = sim;
     }
@@ -200,7 +216,8 @@ function bestSimulation(catalog, base, card, lines, options) {
         throw new Error(`no simulation for ${card.id}`);
     return best;
 }
-const byNet = (a, b) => b.net - a.net || a.annualFees - b.annualFees;
+const costs = (s) => s.annualFees + s.membershipFees;
+const byNet = (a, b) => b.net - a.net || costs(a) - costs(b);
 // Pairs that tie and share their first card differ only in an
 // interchangeable second card (several flat 2% cards), so they fold into one.
 function foldTies(pairs) {
@@ -208,7 +225,7 @@ function foldTies(pairs) {
     for (const pair of pairs) {
         const [a, b] = pair.cards;
         const twin = folded.find((f) => Math.abs(f.net - pair.net) < 0.005 &&
-            f.annualFees === pair.annualFees &&
+            costs(f) === costs(pair) &&
             f.cards.some((c) => c.cardId === a?.cardId || c.cardId === b?.cardId));
         if (!twin) {
             folded.push({ ...pair, alternatives: [] });
@@ -275,8 +292,9 @@ function projectedWallet(wallet, catalog, start) {
 }
 export function simulateAdditions(catalog, wallet, lines, options) {
     const projected = projectedWallet(wallet, catalog, options.start);
-    const current = simulateWallet(catalog, projected, lines, options.start);
-    const held = new Set(wallet.cards.map((c) => c.id));
+    const heldIds = wallet.cards.map((c) => c.id);
+    const current = simulateWallet(catalog, projected, lines, options.start, heldIds);
+    const held = new Set(heldIds);
     const additions = [];
     for (const card of catalog.cards) {
         if (held.has(card.id) || !matchesFilters(card, options.filters))
@@ -285,19 +303,23 @@ export function simulateAdditions(catalog, wallet, lines, options) {
             ...options,
             memberships: wallet.memberships,
             valuations: wallet.valuations,
+            held: heldIds,
         });
         const extraRewards = roundCents(simulation.rewards - current.rewards);
         const annualFee = card.annual_fee ?? 0;
+        const membershipFee = roundCents(simulation.membershipFees - current.membershipFees);
         additions.push({
             cardId: card.id,
             picks: simulation.cards.at(-1)?.picks ?? {},
             extraRewards,
             annualFee,
-            gain: roundCents(extraRewards - annualFee),
+            membershipFee,
+            gain: roundCents(extraRewards - annualFee - membershipFee),
             simulation,
         });
     }
-    additions.sort((a, b) => b.gain - a.gain || a.annualFee - b.annualFee);
+    additions.sort((a, b) => b.gain - a.gain ||
+        a.annualFee + a.membershipFee - (b.annualFee + b.membershipFee));
     return { current, additions };
 }
 // Rough monthly amounts for a U.S. household: the starting point when someone
@@ -320,4 +342,4 @@ export function spendLineFor(catalog, what, monthly) {
 export function typicalSpendLines(catalog) {
     return resolveSpendLines(catalog, TYPICAL_MONTHLY_SPEND.map((t) => spendLineFor(catalog, t.what, t.monthly)));
 }
-export const TYPICAL_SPEND_NOTE = `No spending was given, so this uses rough typical monthly amounts for a U.S. household: ${TYPICAL_MONTHLY_SPEND.map((t) => `${t.what} $${String(t.monthly)}`).join(', ')}. Give your own amounts for a closer answer.`;
+export const TYPICAL_SPEND_NOTE = `No spending was given, so this uses rough typical monthly amounts for a U.S. household: ${TYPICAL_MONTHLY_SPEND.map((t) => `${t.what} ${money(t.monthly)}`).join(', ')}. Give your own amounts for a closer answer.`;

package/dist/engine/text.js

@@ -2,8 +2,24 @@ import { singleMcc } from "./evaluate.js";
 export const num = (n) => String(Number(n.toFixed(2)));
 export const pct = (n) => `${num(n)}%`;
 export const roundCents = (n) => Math.round(n * 100) / 100;
-// Whole dollars stay whole ($2,800); anything else shows cents ($0.40).
-export const money = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+// An id in words: "gas-ev-charging" reads "gas ev charging".
+export const words = (id) => id.replace(/[-_.]/g, ' ');
+const dateWords = (date, options) => new Date(`${date}T12:00:00Z`).toLocaleDateString('en-US', {
+    ...options,
+    timeZone: 'UTC',
+});
+// From YYYY-MM-DD, the same in every time zone: "Dec 31, 2026",
+// "December 31, 2026", "December 2026".
+export const shortDate = (date) => dateWords(date, { month: 'short', day: 'numeric', year: 'numeric' });
+export const longDate = (date) => dateWords(date, { month: 'long', day: 'numeric', year: 'numeric' });
+export const monthYear = (date) => dateWords(date, { month: 'long', year: 'numeric' });
+// Always cents ($4.00), for what one purchase earns. A loss reads −$4.00.
+export const dollarsAndCents = (n) => `${n < 0 ? '−' : ''}$${Math.abs(n).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+// Rounded to whole dollars ($2,800), for fees, caps and yearly totals.
+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 })}`;
 export function feeText(fees) {
     const { annualFee, firstYearFee } = fees;
     if (annualFee === null)
@@ -51,3 +67,52 @@ export function pointValuesText(catalog, shown) {
     const list = [...values].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
     return `Values points at: ${list.join(', ')}.`;
 }
+export const NETWORK_NAMES = {
+    visa: 'Visa',
+    mastercard: 'Mastercard',
+    amex: 'American Express',
+    discover: 'Discover',
+    store: 'store card',
+};
+// A name with its own "and" ("drugstores and pharmacies") would run into the
+// list's: those lists use commas only, with those names last.
+export const listed = (parts, joiner = 'and') => {
+    const anded = parts.filter((p) => p.includes(' and '));
+    if (anded.length > 0)
+        return [...parts.filter((p) => !p.includes(' and ')), ...anded].join(', ');
+    return parts.length <= 2
+        ? parts.join(` ${joiner} `)
+        : `${parts.slice(0, -1).join(', ')} ${joiner} ${parts.at(-1) ?? ''}`;
+};
+const NUMBERS = {
+    one: '1',
+    two: '2',
+    three: '3',
+    four: '4',
+    five: '5',
+    six: '6',
+};
+// "five-percent" reads "5%"; other ids read as words.
+export function choiceName(id) {
+    return words(id.replace(/\b(one|two|three|four|five|six)-percent\b/g, (_, n) => `${NUMBERS[n] ?? n}%`));
+}
+// Period words in one place: a cap of $1,500 "a quarter", a "quarterly" cap,
+// a category picked "each quarter".
+export const CAP_PERIODS = {
+    month: 'a month',
+    quarter: 'a quarter',
+    calendar_year: 'a calendar year',
+    cardmember_year: 'a cardmember year',
+};
+export const CAP_ADJECTIVES = {
+    month: 'monthly',
+    quarter: 'quarterly',
+    calendar_year: 'calendar-year',
+    cardmember_year: 'cardmember-year',
+};
+export const PICK_PERIODS = {
+    month: 'each month',
+    quarter: 'each quarter',
+    calendar_year: 'each year',
+    until_changed: 'until you change it',
+};

package/dist/engine/valuation.js

@@ -1,4 +1,4 @@
-function currencyValuation(catalog, wallet, currencyId) {
+export function currencyValuation(catalog, wallet, currencyId) {
     const currency = catalog.currencies.find((c) => c.id === currencyId);
     if (!currency)
         throw new Error(`unknown currency '${currencyId}'`);

package/dist/engine/wallet-change.js

@@ -1,3 +1,5 @@
+import { WALLET_VERSION, } from "../schema/wallet.js";
+import { addMonths } from "./bonus.js";
 import { capByKey } from "./evaluate.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
@@ -132,11 +134,25 @@ export function cardFields(card, held, input, today) {
             problems.push(`"${b.by}" isn't a deadline after the opening date.`);
         if (!card.welcome_offer && (b.spend === undefined || b.by === undefined))
             problems.push(`earnrate has no published welcome offer for ${card.id}, so give the spending needed and the deadline.`);
+        // The terms are saved with the bonus, so a later change to the published
+        // offer, or a wallet exported and imported again, keeps the user's own.
+        const offer = card.welcome_offer;
+        const before = held?.bonus?.opened === b.opened ? held.bonus : undefined;
+        const spend = b.spend ?? before?.spend ?? offer?.spend;
+        const by = b.by ??
+            before?.by ??
+            (offer && isDate(b.opened)
+                ? addMonths(b.opened, offer.months)
+                : undefined);
+        const points = before?.points ?? (before?.dollars ? undefined : offer?.points);
+        const dollars = before?.dollars ?? (points !== undefined ? undefined : offer?.dollars);
         fields.bonus = {
             opened: b.opened,
             spent: b.spent ?? held?.bonus?.spent ?? 0,
-            ...(b.spend === undefined ? {} : { spend: b.spend }),
-            ...(b.by === undefined ? {} : { by: b.by }),
+            ...(spend === undefined ? {} : { spend }),
+            ...(by === undefined ? {} : { by }),
+            ...(points === undefined ? {} : { points }),
+            ...(dollars === undefined ? {} : { dollars }),
         };
     }
     return problems.length > 0 ? problems.join('\n') : fields;
@@ -173,7 +189,12 @@ export function addToWallet(catalog, wallet, input, today) {
     const held = withFields(newHolding(card.id), fields);
     const next = wallet
         ? { ...wallet, cards: [...wallet.cards, held] }
-        : { valuations: {}, memberships: [], cards: [held] };
+        : {
+            version: WALLET_VERSION,
+            valuations: {},
+            memberships: [],
+            cards: [held],
+        };
     return {
         ok: true,
         wallet: next,
@@ -221,7 +242,7 @@ export function withMemberships(catalog, wallet, memberships) {
     const known = knownMemberships(catalog);
     const unknown = memberships.filter((m) => !known.includes(m));
     if (unknown.length > 0) {
-        return failed(`No card rule uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
+        return failed(`No card uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
     }
     return {
         ok: true,
@@ -230,3 +251,20 @@ export function withMemberships(catalog, wallet, memberships) {
         notes: [],
     };
 }
+// Point values in cents per point, by currency id; null goes back to
+// earnrate's default for that currency.
+export function withValuations(catalog, wallet, changes) {
+    const unknown = Object.keys(changes).filter((id) => !catalog.currencies.some((c) => c.id === id));
+    if (unknown.length > 0)
+        return failed(`Unknown currency ${unknown.map((id) => `'${id}'`).join(', ')}. Currencies: ${list(catalog.currencies.map((c) => c.id))}.`);
+    const odd = Object.entries(changes).filter(([, cents]) => cents !== null && !(cents > 0 && cents <= MAX_CENTS));
+    if (odd.length > 0)
+        return failed(`A point is worth more than 0¢ and at most ${String(MAX_CENTS)}¢; check ${odd.map(([id]) => id).join(', ')}.`);
+    const valuations = Object.fromEntries([
+        ...Object.entries(wallet.valuations).filter(([id]) => !(id in changes)),
+        ...Object.entries(changes).filter(([, cents]) => cents !== null),
+    ]);
+    return { ok: true, wallet: { ...wallet, valuations }, fields: {}, notes: [] };
+}
+// Higher than any program's points are worth, even transferred.
+const MAX_CENTS = 5;