earnrate 0.2.2 → 0.2.4

package/dist/engine/cheat-sheet.js

@@ -1,8 +1,10 @@
 import { resolveMerchantById } from "../merchants/resolve.js";
 import { categoryResolution, exploreCards, } from "./explore.js";
+import { bonusStatus } from "./bonus.js";
 import { periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { setupNotes } from "./setup.js";
+import { listed, money, shortDate } from "./text.js";
 const CHEAT_SHEET_ITEMS = [
     { label: 'Groceries', category: 'grocery.supermarket' },
     { label: 'Dining', category: 'dining' },
@@ -17,6 +19,7 @@ const CHEAT_SHEET_ITEMS = [
 // The best card in the wallet for each everyday kind of purchase on `date`,
 // with caps, picks and activations as the wallet has them.
 export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
+    const ranked = [];
     const rows = items.map((item) => {
         const merchant = 'merchant' in item
             ? resolveMerchantById(catalog, item.merchant, null)
@@ -30,7 +33,10 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
             date,
             country: 'US',
         }, merchant);
-        const top = rec.ranked.find((r) => r.cardId === rec.decision?.cardId);
+        // The card that earns the most, even when a welcome bonus would take the
+        // pick for one purchase: the sheet is for the whole quarter.
+        const top = rec.decision ? rec.ranked[0] : undefined;
+        ranked.push({ label: item.label, cards: rec.ranked });
         return {
             label: item.label,
             cardId: top?.cardId ?? null,
@@ -40,8 +46,44 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
             note: top?.warnings[0] ?? null,
         };
     });
+    const bonuses = wallet.cards.flatMap((held) => {
+        const status = bonusStatus(catalog, wallet, held, date);
+        if (status?.state !== 'open')
+            return [];
+        const name = held.checkout_label ??
+            catalog.cards.find((c) => c.id === held.id)?.name ??
+            held.id;
+        // Rows where the bonus card matches the row's card, or comes within a
+        // point and three quarters of its rate (as single answers mention it).
+        const matches = [];
+        const near = [];
+        for (const { label, cards } of ranked) {
+            const best = cards[0]?.effectiveReturnPct;
+            const own = cards.find((c) => c.cardId === held.id)?.effectiveReturnPct;
+            if (best === undefined || own === undefined)
+                continue;
+            if (best - own < 1e-9)
+                matches.push(label.toLowerCase());
+            else if (best - own <= 1 && own >= best * 0.75)
+                near.push(label.toLowerCase());
+        }
+        const where = [
+            ...(matches.length > 0
+                ? [`matches the listed card on ${listed(matches)}`]
+                : []),
+            ...(near.length > 0 ? [`comes within a point on ${listed(near)}`] : []),
+        ];
+        return [
+            `Working on ${name}'s welcome bonus: ${money(status.remaining ?? 0)} more by ${shortDate(status.deadline ?? date)}. ${where.length > 0
+                ? `It ${where.join(' and ')}, so those are the places to use it.`
+                : 'It trails the listed cards everywhere, so use it on everyday spending only as needed to reach the bonus.'}`,
+        ];
+    });
     const notes = [
-        ...new Set(wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text))),
+        ...new Set([
+            ...bonuses,
+            ...wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text)),
+        ]),
     ];
     const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
     return {

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',
@@ -23,6 +21,11 @@ const PERIOD_WORDS = {
 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);
+// At exactly the break-even value the two cards tie, so only an exact
+// threshold reads "more than".
+const worthAbove = (n) => Math.abs(n * 100 - Math.round(n * 100)) < EPSILON
+    ? `more than ${num(n)}¢`
+    : `${roundUp(n)}¢ or more`;
 const roundDown = (n) => String(Math.floor(n * 100 + EPSILON) / 100);
 function compareEntries(a, b) {
     const byReturn = b.effectiveReturnPct - a.effectiveReturnPct;
@@ -149,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;
 }
@@ -218,7 +221,7 @@ function sensitivity(catalog, entries) {
         if (o.range && oRate > 0) {
             const threshold = winner.effectiveReturnPct / oRate;
             if (threshold > o.centsPerUnit && threshold <= o.range[1]) {
-                consider((threshold - o.centsPerUnit) / o.centsPerUnit, `${displayName(other)} beats ${displayName(winner)} here if ${currencyLabel(catalog, o.currency)} points are worth ${roundUp(threshold)}¢ or more (you value them at ${num(o.centsPerUnit)}¢).`);
+                consider((threshold - o.centsPerUnit) / o.centsPerUnit, `${displayName(other)} beats ${displayName(winner)} here if ${currencyLabel(catalog, o.currency)} points are worth ${worthAbove(threshold)} (you value them at ${num(o.centsPerUnit)}¢).`);
             }
         }
     }
@@ -259,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.`);
@@ -274,15 +277,38 @@ 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}.`);
+        // 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
+            ? rankEntries(catalog, wallet, { ...purchase, channel: 'online' }, online, online.category).entries[0]
+            : undefined;
+        if (alt)
+            warnings.push(`Ordering online instead? ${displayName(alt)} works there (${num(alt.effectiveReturnPct)}%).`);
     }
     else if (merchant.accepts === null &&
         (winner.card.network === 'amex' || winner.card.network === 'discover')) {
@@ -300,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)
@@ -313,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,
@@ -341,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) {
@@ -373,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,11 +45,11 @@ 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'));
 }
-function activationRules(card, today) {
+export function activationRules(card, today) {
     return card.rules
         .filter((r) => r.requires?.activation === true &&
         (r.valid_to === undefined || r.valid_to >= today) &&
@@ -57,13 +57,24 @@ 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