earnrate 0.1.2 → 0.1.4

package/dist/engine/explore.js

@@ -0,0 +1,292 @@
+import { resolveMerchant } from "../merchants/resolve.js";
+import { evaluateCard, purchaseContext } from "./evaluate.js";
+import { periodKey } from "./periods.js";
+import { categoryPhrase, currencyLabel, dollars, earnText, num, recommend, } from "./recommend.js";
+import { rotationGap } from "./rotation.js";
+import { membershipsUsed } from "./setup.js";
+import { cardValuation } from "./valuation.js";
+const EPSILON = 1e-9;
+export const ALL_PERSONAL_CARDS = {
+    kind: 'any',
+    business: false,
+    noAnnualFee: false,
+    issuer: null,
+    includeClosed: false,
+};
+export function matchesFilters(card, filters) {
+    if (card.business !== filters.business)
+        return false;
+    if (!filters.includeClosed && card.applications_closed !== undefined)
+        return false;
+    if (filters.noAnnualFee && card.annual_fee !== 0)
+        return false;
+    if (filters.issuer !== null && card.issuer !== filters.issuer)
+        return false;
+    const isCash = card.currency === 'cash';
+    if (filters.kind === 'cash' && !isCash)
+        return false;
+    if (filters.kind === 'points' && isCash)
+        return false;
+    return true;
+}
+// The period a card's picks are keyed by in a wallet.
+export function choicePeriod(card) {
+    for (const c of card.choices)
+        if (c.period !== 'until_changed')
+            return c.period;
+    return 'quarter';
+}
+// A card as its holder would set it up for the best result: the given picks,
+// every activation done, and no cap used yet. The anniversary is `date`, so a
+// cardmember-year cap starts fresh.
+export function idealHolding(card, date, picks = {}) {
+    const period = choicePeriod(card);
+    return {
+        id: card.id,
+        anniversary: date.slice(5),
+        cap_usage: {},
+        activated: card.rules
+            .filter((r) => r.requires?.activation === true)
+            .map((r) => r.id),
+        ...(Object.keys(picks).length > 0
+            ? { chosen: { period: periodKey(period, date, null) ?? '', picks } }
+            : {}),
+    };
+}
+const PICK_PERIODS = {
+    month: 'set each month',
+    quarter: 'picked each quarter',
+    calendar_year: 'picked each year',
+    until_changed: 'until you change it',
+};
+const CAP_PERIODS = {
+    month: 'a month',
+    quarter: 'a quarter',
+    calendar_year: 'a calendar year',
+    cardmember_year: 'a cardmember year',
+};
+const plainWords = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+// A category from everyday words: an alias ("groceries") first, then the
+// name, then the id, so "grocery" means supermarkets rather than the parent.
+export function findCategory(catalog, text) {
+    const wanted = plainWords(text);
+    if (wanted === '')
+        return null;
+    const by = (key) => catalog.categories.find((c) => key(c).map(plainWords).includes(wanted))?.id;
+    return (by((c) => c.aliases) ?? by((c) => [c.name]) ?? by((c) => [c.id]) ?? null);
+}
+export function categoryResolution(catalog, category, channel) {
+    const found = catalog.categories.find((c) => c.id === category);
+    if (!found)
+        throw new Error(`unknown category '${category}'`);
+    return {
+        input: found.name,
+        merchantId: null,
+        resolvedName: found.name,
+        category,
+        likelyMcc: null,
+        accepts: null,
+        ambiguity: null,
+        channel,
+        confidence: 'high',
+        source: 'caller',
+        bookedVia: [],
+        inference: null,
+    };
+}
+function walletOf(held, options) {
+    return {
+        valuations: options.valuations,
+        memberships: options.memberships,
+        cards: [held],
+    };
+}
+// One option per choice is enough to cover a single purchase, so each choice
+// is tried option by option, keeping a pick only when it raises the rate.
+function bestPicksForPurchase(catalog, card, merchant, purchase, options) {
+    const picks = {};
+    const rateWith = (p) => {
+        const held = idealHolding(card, purchase.date, p);
+        const ctx = purchaseContext(catalog, walletOf(held, options), merchant, merchant.category, purchase);
+        return evaluateCard(card, held, ctx).best.rate;
+    };
+    for (const choice of card.choices) {
+        let best = rateWith(picks);
+        for (const option of Object.keys(choice.options)) {
+            const trial = { ...picks, [choice.id]: [option] };
+            const rate = rateWith(trial);
+            if (rate > best + EPSILON) {
+                best = rate;
+                picks[choice.id] = [option];
+            }
+        }
+    }
+    return picks;
+}
+function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
+    const ctx = purchaseContext(catalog, wallet, merchant, merchant.category, purchase);
+    const { best } = evaluateCard(card, held, ctx);
+    const rule = best.rule;
+    const none = { pick: null, activation: null, membership: null, cap: null };
+    if (!rule)
+        return none;
+    const choiceId = rule.match.choice;
+    const choice = card.choices.find((c) => c.id === choiceId);
+    const picked = choiceId === undefined ? undefined : held.chosen?.picks[choiceId];
+    const cap = best.cap?.cap;
+    return {
+        pick: choice && picked
+            ? { choice: choice.id, options: picked, period: choice.period }
+            : null,
+        activation: rule.requires?.activation === true ? rule.id : null,
+        membership: rule.requires?.membership ?? null,
+        cap: cap
+            ? {
+                amount: cap.amount,
+                period: cap.period,
+                thenRate: cap.then_rate,
+                currency: cardValuation(catalog, wallet, card).currency,
+            }
+            : null,
+    };
+}
+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]}).`);
+    }
+    if (r.activation !== null)
+        conditions.push(`Needs activating with the issuer ("${r.activation}").`);
+    if (r.membership !== null)
+        conditions.push(`Needs ${r.membership}.`);
+    if (r.cap) {
+        conditions.push(`Up to ${dollars(r.cap.amount)} ${CAP_PERIODS[r.cap.period] ?? ''} at this rate, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}.`);
+    }
+    return conditions;
+}
+function membershipUpgrades(catalog, card, held, merchant, purchase, options, current) {
+    const upgrades = [];
+    for (const membership of membershipsUsed(card)) {
+        if (options.memberships.includes(membership))
+            continue;
+        const wallet = walletOf(held, {
+            ...options,
+            memberships: [...options.memberships, membership],
+        });
+        const ctx = purchaseContext(catalog, wallet, merchant, merchant.category, purchase);
+        const pct = evaluateCard(card, held, ctx).best.rate *
+            cardValuation(catalog, wallet, card).centsPerUnit;
+        if (pct > current + EPSILON)
+            upgrades.push({ membership, effectiveReturnPct: pct });
+    }
+    return upgrades.sort((a, b) => b.effectiveReturnPct - a.effectiveReturnPct);
+}
+function compareExplored(a, b) {
+    const byReturn = b.effectiveReturnPct - a.effectiveReturnPct;
+    if (Math.abs(byReturn) > EPSILON)
+        return byReturn;
+    const byFee = (a.annualFee ?? Infinity) - (b.annualFee ?? Infinity);
+    if (byFee !== 0)
+        return byFee;
+    const byConditions = a.conditions.length - b.conditions.length;
+    if (byConditions !== 0)
+        return byConditions;
+    return a.cardId.localeCompare(b.cardId);
+}
+// Ranks every card in the catalog that passes the filters for one purchase,
+// each set up at its best: the pick that covers it, activated, cap unused.
+export function exploreCards(catalog, query, options) {
+    const merchant = query.merchant !== null
+        ? resolveMerchant(catalog, query.merchant, query.channel)
+        : categoryResolution(catalog, query.category ?? 'other', query.channel);
+    const purchase = {
+        merchant: merchant.input,
+        amount: query.amount,
+        channel: query.channel,
+        date: query.date,
+        country: 'US',
+    };
+    const ranked = [];
+    const excluded = [];
+    for (const card of catalog.cards) {
+        if (!matchesFilters(card, options.filters))
+            continue;
+        const picks = bestPicksForPurchase(catalog, card, merchant, purchase, options);
+        const held = idealHolding(card, query.date, picks);
+        const wallet = walletOf(held, options);
+        const rec = recommend(catalog, wallet, purchase, merchant);
+        const top = rec.ranked[0];
+        if (!top) {
+            excluded.push(...rec.excluded);
+            continue;
+        }
+        const requirements = requirementsFor(catalog, card, held, wallet, merchant, purchase);
+        const gap = rotationGap(card, query.date);
+        const evidenceRule = top.matchedRule ?? 'base_rate';
+        const evidence = card.evidence.find((e) => e.rule === evidenceRule);
+        ranked.push({
+            ...top,
+            warnings: gap === null
+                ? top.warnings
+                : [
+                    ...top.warnings,
+                    `Its rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them.`,
+                ],
+            issuer: card.issuer,
+            network: card.network,
+            annualFee: card.annual_fee ?? null,
+            firstYearFee: card.first_year_fee ?? null,
+            picks,
+            requirements,
+            conditions: conditionsText(catalog, requirements),
+            evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
+            withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
+        });
+    }
+    ranked.sort(compareExplored);
+    return {
+        merchant,
+        ranked,
+        excluded,
+        assumptions: exploreAssumptions(catalog, merchant, ranked, options),
+        warnings: exploreWarnings(catalog, merchant),
+    };
+}
+function exploreAssumptions(catalog, merchant, ranked, options) {
+    const assumptions = [];
+    if (merchant.source === 'caller') {
+        assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
+    }
+    else if (merchant.source !== 'none') {
+        const code = merchant.likelyMcc === null ? '' : ` (MCC ${String(merchant.likelyMcc)})`;
+        assumptions.push(`Assumes ${merchant.resolvedName} codes as ${categoryPhrase(catalog, merchant.category)}${code}.`);
+    }
+    assumptions.push('Assumes each card is set up for this purchase: the right category pick, any activation done, and none of its cap used yet. A card you hold may differ.');
+    assumptions.push(options.memberships.length === 0
+        ? 'Assumes no memberships (like Amazon Prime). Rates that need one are listed separately.'
+        : `Assumes these memberships: ${options.memberships.join(', ')}.`);
+    const values = new Map();
+    for (const e of ranked.slice(0, 10)) {
+        if (e.currency !== 'cash')
+            values.set(e.currency, e.centsPerUnit);
+    }
+    if (values.size > 0) {
+        const list = [...values].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
+        assumptions.push(`Values points at: ${list.join(', ')}.`);
+    }
+    return assumptions;
+}
+function exploreWarnings(catalog, merchant) {
+    const warnings = [];
+    if (merchant.source === 'none') {
+        warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. Try a category instead.`);
+    }
+    if (merchant.ambiguity) {
+        const alternatives = merchant.ambiguity.mayCodeAs.map((c) => categoryPhrase(catalog, c));
+        warnings.push(`${merchant.resolvedName} may code as ${alternatives.join(' or ')} instead: ${merchant.ambiguity.note}`);
+    }
+    return warnings;
+}

package/dist/engine/recommend.js

@@ -20,14 +20,14 @@ const PERIOD_WORDS = {
     cardmember_year: 'cardmember-year',
 };
 const displayName = (e) => e.held.checkout_label ?? e.card.name;
-const num = (n) => String(Number(n.toFixed(2)));
+export const num = (n) => String(Number(n.toFixed(2)));
 // Whole dollars stay whole ($2,800); anything else shows cents ($0.40).
 const money = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
-const dollars = (n) => `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
-function currencyName(catalog, id) {
+export const dollars = (n) => `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
+export function currencyName(catalog, id) {
     return catalog.currencies.find((c) => c.id === id)?.name ?? id;
 }
-function currencyLabel(catalog, id) {
+export function currencyLabel(catalog, id) {
     const name = currencyName(catalog, id);
     return /^[A-Z]{2,4}$/.test(id) ? `${name} (${id})` : name;
 }
@@ -39,13 +39,13 @@ function categoryName(catalog, id) {
 }
 // Mid-sentence form: "Supermarkets" becomes "supermarkets", but "TV and
 // internet service" and "EV charging" keep their acronyms.
-function categoryPhrase(catalog, id) {
+export function categoryPhrase(catalog, id) {
     const name = categoryName(catalog, id);
     return /^[A-Z]{2}/.test(name)
         ? name
         : name.charAt(0).toLowerCase() + name.slice(1);
 }
-function earnText(catalog, rate, currency) {
+export function earnText(catalog, rate, currency) {
     return currency === 'cash'
         ? `${num(rate)}% cash back`
         : `${num(rate)}x ${currencyName(catalog, currency)}`;
@@ -333,7 +333,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const gap = card ? rotationGap(card, purchase.date) : null;
         if (card && gap !== null) {
             const name = held.checkout_label ?? card.name;
-            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.`);
+            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);

package/dist/engine/setup.js

@@ -161,7 +161,7 @@ export function setupNotes(catalog, wallet, held, today) {
     if (gap !== null) {
         notes.push({
             kind: 'rotation',
-            text: `${name}'s rotating categories for ${gap} aren't in earnrate's data yet.`,
+            text: `${name}'s rotating categories for ${gap} aren't in earnrate's data yet. An earnrate update adds them once the issuer announces them.`,
         });
     }
     return notes;

package/dist/engine/simulate.js

@@ -0,0 +1,309 @@
+import { resolveMerchant } from "../merchants/resolve.js";
+import { evaluateCard, purchaseContext } from "./evaluate.js";
+import { categoryResolution, choicePeriod, idealHolding, matchesFilters, } from "./explore.js";
+import { periodKey } from "./periods.js";
+import { applyBooking, capBooking } from "./record.js";
+import { rotationGap } from "./rotation.js";
+import { cardValuation } from "./valuation.js";
+const EPSILON = 1e-9;
+const MONTHS = 12;
+const SHORTLIST = 8; // best single cards considered for pairs
+const PER_LINE = 2; // plus the best cards for each spending line
+const round = (n) => Math.round(n * 100) / 100;
+export function resolveSpendLines(catalog, lines) {
+    return lines
+        .filter((l) => l.monthly > 0)
+        .map((l) => {
+        const merchant = l.merchant !== null
+            ? resolveMerchant(catalog, l.merchant, null)
+            : categoryResolution(catalog, l.category ?? 'other', null);
+        return { label: merchant.resolvedName, monthly: l.monthly, merchant };
+    });
+}
+function monthDates(start) {
+    const year = Number(start.slice(0, 4));
+    const month = Number(start.slice(5, 7)) - 1;
+    return Array.from({ length: MONTHS }, (_, i) => {
+        const y = year + Math.floor((month + i) / 12);
+        const m = ((month + i) % 12) + 1;
+        return `${String(y)}-${String(m).padStart(2, '0')}-15`;
+    });
+}
+// Picks carry over from period to period, so a quarter's picks hold all year.
+function withCurrentPicks(card, held, date) {
+    if (!held.chosen)
+        return held;
+    return {
+        ...held,
+        chosen: {
+            ...held.chosen,
+            period: periodKey(choicePeriod(card), date, null) ?? '',
+        },
+    };
+}
+function usableAt(card, merchant) {
+    if (card.only_at)
+        return (merchant.merchantId !== null && card.only_at.includes(merchant.merchantId));
+    return (card.network === 'store' ||
+        merchant.accepts === null ||
+        merchant.accepts.includes(card.network));
+}
+// 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) {
+    const cards = wallet.cards.map((held) => {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        if (!card)
+            throw new Error(`${held.id} isn't in the card catalog`);
+        return { card, cents: cardValuation(catalog, wallet, card).centsPerUnit };
+    });
+    let state = wallet;
+    const results = lines.map(() => ({
+        spend: 0,
+        earned: 0,
+        byCard: new Map(),
+    }));
+    for (const date of monthDates(start)) {
+        lines.forEach((line, i) => {
+            const result = results[i];
+            if (!result)
+                return;
+            let left = line.monthly;
+            result.spend += left;
+            for (let guard = 0; left > EPSILON && guard < 20; guard++) {
+                let pick = null;
+                for (const { card, cents } of cards) {
+                    if (!usableAt(card, line.merchant))
+                        continue;
+                    const raw = state.cards.find((h) => h.id === card.id);
+                    if (!raw)
+                        continue;
+                    const held = withCurrentPicks(card, raw, date);
+                    const ctx = purchaseContext(catalog, state, line.merchant, line.merchant.category, { amount: null, date, country: 'US' });
+                    const { best } = evaluateCard(card, held, ctx);
+                    const perDollar = (best.rate * cents) / 100;
+                    const room = best.cap && best.cap.remaining > 0 ? best.cap.remaining : Infinity;
+                    if (!pick || perDollar > pick.perDollar + EPSILON)
+                        pick = { card, perDollar, room };
+                }
+                if (!pick)
+                    break;
+                const chosen = pick;
+                const amount = Math.min(left, chosen.room);
+                result.earned += amount * chosen.perDollar;
+                result.byCard.set(chosen.card.id, (result.byCard.get(chosen.card.id) ?? 0) + amount);
+                const booking = capBooking(catalog, {
+                    ...state,
+                    cards: state.cards.map((h) => h.id === chosen.card.id
+                        ? withCurrentPicks(chosen.card, h, date)
+                        : h),
+                }, {
+                    cardId: chosen.card.id,
+                    merchant: line.label,
+                    amount,
+                    date,
+                    channel: line.merchant.channel,
+                }, line.merchant);
+                if (booking)
+                    state = applyBooking(state, booking);
+                left -= amount;
+            }
+        });
+    }
+    const lineResults = lines.map((line, i) => {
+        const r = results[i] ?? {
+            spend: 0,
+            earned: 0,
+            byCard: new Map(),
+        };
+        return {
+            label: line.label,
+            spend: round(r.spend),
+            earned: round(r.earned),
+            returnPct: r.spend > 0 ? (r.earned / r.spend) * 100 : 0,
+            cards: [...r.byCard].sort((a, b) => b[1] - a[1]).map(([id]) => id),
+        };
+    });
+    const rewards = round(lineResults.reduce((sum, l) => sum + l.earned, 0));
+    const annualFees = cards.reduce((sum, c) => sum + (c.card.annual_fee ?? 0), 0);
+    const notes = [];
+    const dates = monthDates(start);
+    for (const { card } of cards) {
+        const gaps = [
+            ...new Set(dates.map((d) => rotationGap(card, d)).filter((g) => g !== null)),
+        ];
+        if (gaps.length > 0)
+            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 &&
+            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.`);
+    }
+    return {
+        cards: wallet.cards.map((h) => ({
+            cardId: h.id,
+            picks: h.chosen?.picks ?? {},
+        })),
+        spend: round(lineResults.reduce((sum, l) => sum + l.spend, 0)),
+        rewards,
+        annualFees,
+        net: round(rewards - annualFees),
+        lines: lineResults,
+        notes,
+    };
+}
+function combinations(items, size) {
+    if (size === 0)
+        return [[]];
+    if (items.length < size)
+        return [items];
+    const [first, ...rest] = items;
+    if (first === undefined)
+        return [[]];
+    return [
+        ...combinations(rest, size - 1).map((c) => [first, ...c]),
+        ...combinations(rest, size),
+    ];
+}
+// Pick sets worth trying: only options that raise the card's rate on one of
+// the lines, combined up to the number of picks the card allows.
+function candidatePicks(catalog, card, lines, memberships, date) {
+    let sets = [{}];
+    for (const choice of card.choices) {
+        const useful = Object.keys(choice.options).filter((option) => {
+            const plain = idealHolding(card, date);
+            const picked = idealHolding(card, date, { [choice.id]: [option] });
+            return lines.some((line) => {
+                const ctx = purchaseContext(catalog, { valuations: {}, memberships, cards: [picked] }, line.merchant, line.merchant.category, { amount: null, date, country: 'US' });
+                return (evaluateCard(card, picked, ctx).best.rate >
+                    evaluateCard(card, plain, ctx).best.rate + EPSILON);
+            });
+        });
+        if (useful.length === 0)
+            continue;
+        const combos = combinations(useful, Math.min(choice.pick, useful.length));
+        sets = sets.flatMap((s) => combos.map((c) => ({ ...s, [choice.id]: c })));
+    }
+    return sets;
+}
+function walletWith(base, card, picks, options) {
+    return {
+        valuations: options.valuations,
+        memberships: options.memberships,
+        cards: [...base, idealHolding(card, options.start, picks)],
+    };
+}
+// The best picks for `card` alongside the cards already in `base`.
+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);
+        if (!best || sim.net > best.net + EPSILON)
+            best = sim;
+    }
+    if (!best)
+        throw new Error(`no simulation for ${card.id}`);
+    return best;
+}
+const byNet = (a, b) => b.net - a.net || a.annualFees - b.annualFees;
+// 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) {
+    const folded = [];
+    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 &&
+            f.cards.some((c) => c.cardId === a?.cardId || c.cardId === b?.cardId));
+        if (!twin) {
+            folded.push({ ...pair, alternatives: [] });
+            continue;
+        }
+        const shared = new Set(twin.cards.map((c) => c.cardId));
+        const other = [a, b].find((c) => c && !shared.has(c.cardId));
+        if (other)
+            twin.alternatives.push(other.cardId);
+    }
+    return folded;
+}
+export function simulateCatalog(catalog, lines, options) {
+    const eligible = catalog.cards.filter((c) => matchesFilters(c, options.filters));
+    const singles = eligible
+        .map((card) => bestSimulation(catalog, [], card, lines, options))
+        .sort(byNet);
+    const shortlist = new Set(singles.slice(0, SHORTLIST).map((s) => s.cards[0]?.cardId));
+    lines.forEach((line) => {
+        const best = [...singles].sort((a, b) => (b.lines.find((l) => l.label === line.label)?.earned ?? 0) -
+            (a.lines.find((l) => l.label === line.label)?.earned ?? 0));
+        for (const s of best.slice(0, PER_LINE))
+            shortlist.add(s.cards[0]?.cardId);
+    });
+    // A card whose points pool into a shortlisted card's is worth more beside it.
+    for (const card of eligible) {
+        if (card.pools_into?.when_wallet_has.some((id) => shortlist.has(id)))
+            shortlist.add(card.id);
+    }
+    const finalists = eligible.filter((c) => shortlist.has(c.id));
+    const singleFor = new Map(singles.map((s) => [s.cards[0]?.cardId, s]));
+    const pairs = [];
+    finalists.forEach((first, i) => {
+        const firstPicks = singleFor.get(first.id)?.cards[0]?.picks ?? {};
+        for (const second of finalists.slice(i + 1)) {
+            const base = [idealHolding(first, options.start, firstPicks)];
+            pairs.push(bestSimulation(catalog, base, second, lines, options));
+        }
+    });
+    pairs.sort(byNet);
+    return { singles, pairs: foldTies(pairs).slice(0, 10) };
+}
+// The person's own wallet, set up as it would run all year: their picks carry
+// over, rotating categories get activated, caps start fresh.
+function projectedWallet(wallet, catalog, start) {
+    return {
+        ...wallet,
+        cards: wallet.cards.map((held) => {
+            const card = catalog.cards.find((c) => c.id === held.id);
+            const ideal = card
+                ? idealHolding(card, start, held.chosen?.picks ?? {})
+                : held;
+            return {
+                ...ideal,
+                ...(held.checkout_label !== undefined
+                    ? { checkout_label: held.checkout_label }
+                    : {}),
+                ...(held.anniversary !== undefined
+                    ? { anniversary: held.anniversary }
+                    : {}),
+            };
+        }),
+    };
+}
+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 additions = [];
+    for (const card of catalog.cards) {
+        if (held.has(card.id) || !matchesFilters(card, options.filters))
+            continue;
+        const simulation = bestSimulation(catalog, projected.cards, card, lines, {
+            ...options,
+            memberships: wallet.memberships,
+            valuations: wallet.valuations,
+        });
+        const extraRewards = round(simulation.rewards - current.rewards);
+        const annualFee = card.annual_fee ?? 0;
+        additions.push({
+            cardId: card.id,
+            picks: simulation.cards.at(-1)?.picks ?? {},
+            extraRewards,
+            annualFee,
+            gain: round(extraRewards - annualFee),
+            simulation,
+        });
+    }
+    additions.sort((a, b) => b.gain - a.gain || a.annualFee - b.annualFee);
+    return { current, additions };
+}