earnrate 0.2.3 → 0.2.4

package/dist/engine/explore.js

@@ -1,10 +1,11 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
+import { membershipNeeded, paidMemberships } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
-import { categoryPhrase, codesAs, earnText, money, pointValuesText, } from "./text.js";
+import { categoryPhrase, choiceName, codesAs, earnText, membershipName, money, pointValuesText, words, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 export const ALL_PERSONAL_CARDS = {
@@ -150,12 +151,12 @@ function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
 function conditionsText(catalog, r) {
     const conditions = [];
     if (r.pick) {
-        conditions.push(`Needs "${r.pick.options.join('", "')}" as its ${r.pick.choice} pick (${PICK_PERIODS[r.pick.period]}).`);
+        conditions.push(`Needs ${r.pick.options.map(words).join(' or ')} as its ${choiceName(r.pick.choice)} pick (${PICK_PERIODS[r.pick.period]}).`);
     }
     if (r.activation !== null)
-        conditions.push(`Needs activating with the issuer ("${r.activation}").`);
+        conditions.push('Needs its bonus activated with the issuer (free).');
     if (r.membership !== null)
-        conditions.push(`Needs ${r.membership}.`);
+        conditions.push(`Needs ${membershipName(r.membership)}.`);
     if (r.cap) {
         conditions.push(`Up to ${money(r.cap.amount)} ${CAP_PERIODS[r.cap.period] ?? ''} at this rate, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}.`);
     }
@@ -206,6 +207,11 @@ export function exploreCards(catalog, query, options, resolved) {
     };
     const ranked = [];
     const excluded = [];
+    // A Costco purchase means a Costco member: no membership to point out.
+    const paid = paidMemberships(catalog, {
+        memberships: options.memberships,
+        merchantIds: [merchant.merchantId],
+    });
     for (const card of catalog.cards) {
         if (!matchesFilters(card, options.filters))
             continue;
@@ -236,7 +242,10 @@ export function exploreCards(catalog, query, options, resolved) {
             firstYearFee: card.first_year_fee ?? null,
             picks,
             requirements,
-            conditions: conditionsText(catalog, requirements),
+            conditions: [
+                ...conditionsText(catalog, requirements),
+                ...membershipNeeded(card, paid),
+            ],
             evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
             withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
         });

package/dist/engine/memberships.js

@@ -0,0 +1,45 @@
+import { money } from "./text.js";
+// Memberships the person already pays for: the ones they've said, the ones a
+// card they hold needs, and the ones their spending shows (only members shop
+// at Costco).
+export function paidMemberships(catalog, { memberships, heldCards = [], merchantIds = [], }) {
+    const paid = new Set(memberships);
+    for (const card of catalog.cards) {
+        const m = card.requires_membership;
+        if (!m)
+            continue;
+        if (heldCards.includes(card.id) ||
+            m.members_shop_at.some((id) => merchantIds.includes(id)))
+            paid.add(m.id);
+    }
+    return paid;
+}
+// What these cards' memberships add, once each, leaving out the paid ones.
+export function membershipCosts(cards, paid) {
+    const costs = new Map();
+    for (const card of cards) {
+        const m = card.requires_membership;
+        if (!m || paid.has(m.id))
+            continue;
+        const cost = costs.get(m.id) ?? {
+            id: m.id,
+            name: m.name,
+            annualFee: m.annual_fee,
+            cardIds: [],
+        };
+        cost.cardIds.push(card.id);
+        costs.set(m.id, cost);
+    }
+    return [...costs.values()];
+}
+// The card's membership as a condition, unless it's paid for.
+export function membershipNeeded(card, paid) {
+    const m = card.requires_membership;
+    return m && !paid.has(m.id)
+        ? [`Needs ${m.name} (${money(m.annual_fee)} a year).`]
+        : [];
+}
+export function membershipNote(catalog, m) {
+    const names = m.cardIds.map((id) => catalog.cards.find((c) => c.id === id)?.name ?? id);
+    return `${names.join(' and ')} ${names.length === 1 ? 'needs' : 'need'} ${m.name}, ${money(m.annualFee)} a year, counted here like an annual fee. If you're already a member, add it to your memberships.`;
+}

package/dist/engine/offers.js

@@ -1,9 +1,24 @@
 import { bonusDollars } from "./bonus.js";
 import { matchesFilters } from "./explore.js";
+import { membershipCosts, paidMemberships } from "./memberships.js";
 import { roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
+function ineligibleText(catalog, wallet, notWith) {
+    const held = wallet.cards
+        .filter((c) => notWith.includes(c.id))
+        .map((c) => c.checkout_label ??
+        catalog.cards.find((k) => k.id === c.id)?.name ??
+        c.id);
+    return held.length === 0
+        ? null
+        : `Likely not eligible: you hold ${held.join(' and ')}, and the issuer's terms rule out its cardholders.`;
+}
 export function compareOffers(catalog, wallet, filters, today) {
     const held = new Set(wallet.cards.map((c) => c.id));
+    const paid = paidMemberships(catalog, {
+        memberships: wallet.memberships,
+        heldCards: [...held],
+    });
     const offers = [];
     const withoutOffer = [];
     for (const card of catalog.cards) {
@@ -22,6 +37,7 @@ export function compareOffers(catalog, wallet, filters, today) {
         const value = bonusDollars(card, valuation.centsPerUnit, offer.points, offer.dollars) ??
             0;
         const firstYearFee = card.first_year_fee ?? card.annual_fee ?? null;
+        const membershipFee = membershipCosts([card], paid)[0]?.annualFee ?? 0;
         offers.push({
             cardId: card.id,
             cardName: card.name,
@@ -39,13 +55,17 @@ export function compareOffers(catalog, wallet, filters, today) {
             annualFee: card.annual_fee ?? null,
             firstYearFee,
             bonusValue: roundCents(value),
-            firstYearValue: roundCents(value - (firstYearFee ?? 0)),
+            membershipFee,
+            ineligible: ineligibleText(catalog, wallet, offer.not_with ?? []),
+            firstYearValue: roundCents(value - (firstYearFee ?? 0) - membershipFee),
             held: held.has(card.id),
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,
         });
     }
-    offers.sort((a, b) => b.firstYearValue - a.firstYearValue || a.cardId.localeCompare(b.cardId));
+    offers.sort((a, b) => Number(a.ineligible !== null) - Number(b.ineligible !== null) ||
+        b.firstYearValue - a.firstYearValue ||
+        a.cardId.localeCompare(b.cardId));
     const notes = [
         `Compares the ${String(catalog.cards.length)} cards earnrate knows, not every card on the market.`,
         "Each offer is the public one on the issuer's page on the date shown, checked weekly. Yours may differ: issuers test and target offers, so use the one shown to you when you apply. Issuers also limit who can get a bonus; each card's note says how.",

package/dist/engine/recommend.js

@@ -3,17 +3,15 @@ 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 { categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, NETWORK_NAMES, num, pointValuesText, shortDate, } from "./text.js";
 import { cardValuation } from "./valuation.js";
+// An on-pace welcome bonus card is mentioned when it's this close to the
+// best card: within a point, and at least three quarters of its rate.
+const CLOSE_PCT = 1;
+const CLOSE_SHARE = 0.75;
 const EPSILON = 1e-9;
 export const STALE_AFTER_DAYS = 180;
 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',
@@ -154,7 +152,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 +262,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 +277,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
+        // 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 +326,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 +336,40 @@ 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 &&
+        gap <= CLOSE_PCT &&
+        open.entry.effectiveReturnPct >= best * CLOSE_SHARE) {
+        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;
+            : Math.round((first.earned - top.earned) * 100) / 100;
         bonusResult = {
             cardId: top.cardId,
             checkoutLabel: top.checkoutLabel,
@@ -354,11 +385,13 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         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.`}`);
+        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 +419,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

@@ -45,7 +45,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'));
 }
@@ -57,13 +57,24 @@ export function activationRules(card, today) {
             daysBetween(today, r.valid_from) <= ACTIVATION_LOOKAHEAD_DAYS))
         .map((r) => r.id);
 }
+// Bank of America Preferred Rewards tiers: a person holds one at a time, so
+// with one saved the others aren't missing.
+const TIER = /^bofa-rewards-/;
 export function membershipsUsed(card) {
     return [
         ...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.id] : []),
+    ];
+}
 export function knownMemberships(catalog) {
-    return [...new Set(catalog.cards.flatMap(membershipsUsed))].sort();
+    return [...new Set(catalog.cards.flatMap(membershipsFor))].sort();
 }
 export function cardInfo(card, wallet, today) {
     return {
@@ -84,6 +95,13 @@ export function cardInfo(card, wallet, today) {
             default: c.default ?? null,
         })),
         memberships: membershipsUsed(card),
+        requiresMembership: card.requires_membership
+            ? {
+                id: card.requires_membership.id,
+                name: card.requires_membership.name,
+                annualFee: card.requires_membership.annual_fee,
+            }
+            : null,
         activation: activationRules(card, today),
         needsAnniversary: needsAnniversary(card),
     };
@@ -137,7 +155,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));
+    const hasTier = wallet.memberships.some((m) => TIER.test(m));
+    const missing = membershipsUsed(card).filter((m) => !wallet.memberships.includes(m) && !(hasTier && TIER.test(m)));
     if (missing.length > 0) {
         notes.push({
             kind: 'membership',

package/dist/engine/simulate.js

@@ -1,6 +1,7 @@
 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";
@@ -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(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,7 +143,8 @@ 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.`);
     }
@@ -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

package/dist/engine/text.js

@@ -2,6 +2,15 @@ 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;
+// An id in words: "gas-ev-charging" reads "gas ev charging".
+export const words = (id) => id.replace(/[-_.]/g, ' ');
+// "Dec 31, 2026" from YYYY-MM-DD, the same in every time zone.
+export const shortDate = (date) => new Date(`${date}T12:00:00Z`).toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    timeZone: 'UTC',
+});
 // 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 })}`;
 export function feeText(fees) {
@@ -51,3 +60,45 @@ 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) => {
+    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(' and ')
+        : `${parts.slice(0, -1).join(', ')} and ${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}%`));
+}
+// Display names for membership ids in the card data.
+export const MEMBERSHIPS = {
+    'amazon-prime': 'Amazon Prime',
+    'bank-of-america-account': 'Bank of America checking or savings',
+    'bank-of-america-small-business-account': 'Bank of America small business checking or savings',
+    'bofa-rewards-member': 'BofA Rewards Member',
+    'bofa-rewards-preferred-plus': 'BofA Rewards Preferred Plus',
+    'bofa-rewards-preferred-honors': 'BofA Rewards Preferred Honors',
+    'bofa-rewards-premier': 'BofA Rewards Premier',
+    costco: 'Costco membership',
+    'nordy-club-ambassador': 'Nordy Club Ambassador',
+};
+export const membershipName = (id) => MEMBERSHIPS[id] ?? words(id);

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,