earnrate 0.1.1 → 0.1.3

package/dist/engine/setup.js

@@ -0,0 +1,168 @@
+import { pickedCategories } from "./evaluate.js";
+import { daysBetween } from "./periods.js";
+import { rotationGap } from "./rotation.js";
+// Rules that start within this many days are worth activating now.
+const ACTIVATION_LOOKAHEAD_DAYS = 45;
+const ISSUER_NICKNAMES = {
+    amex: 'american express',
+    'bank-of-america': 'bofa boa bankofamerica',
+    'capital-one': 'capitalone',
+    citi: 'citibank',
+    usbank: 'us bank',
+    'wells-fargo': 'wf wellsfargo',
+    'td-bank': 'td',
+    column: 'bilt',
+};
+const words = (s) => s
+    .toLowerCase()
+    .replace(/\+/g, ' plus ')
+    .replace(/&/g, ' and ')
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length > 0);
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = row[0] ?? 0;
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = row[j] ?? 0;
+            row[j] = Math.min(above + 1, (row[j - 1] ?? 0) + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length] ?? 0;
+}
+function matcher(card) {
+    const haystack = [
+        ...words(card.id),
+        ...words(card.name),
+        ...words(card.issuer),
+        ...words(ISSUER_NICKNAMES[card.issuer] ?? ''),
+    ];
+    const compact = haystack.join('');
+    return (token) => haystack.some((w) => w.startsWith(token)) ||
+        (token.length >= 4 && compact.includes(token)) ||
+        (token.length >= 5 &&
+            haystack.some((w) => editDistance(w, token) <= (token.length >= 8 ? 2 : 1)));
+}
+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) {
+    return card.rules
+        .filter((r) => r.requires?.activation === true &&
+        (r.valid_to === undefined || r.valid_to >= today) &&
+        (r.valid_from === undefined ||
+            daysBetween(today, r.valid_from) <= ACTIVATION_LOOKAHEAD_DAYS))
+        .map((r) => r.id);
+}
+export function membershipsUsed(card) {
+    return [
+        ...new Set(card.rules.flatMap((r) => r.requires?.membership === undefined ? [] : [r.requires.membership])),
+    ];
+}
+export function knownMemberships(catalog) {
+    return [...new Set(catalog.cards.flatMap(membershipsUsed))].sort();
+}
+export function cardInfo(card, wallet, today) {
+    return {
+        id: card.id,
+        name: card.name,
+        issuer: card.issuer,
+        network: card.network,
+        currency: card.currency,
+        annualFee: card.annual_fee ?? null,
+        business: card.business,
+        onlyAt: card.only_at ?? null,
+        held: wallet?.cards.some((c) => c.id === card.id) ?? false,
+        choices: card.choices.map((c) => ({
+            id: c.id,
+            pick: c.pick,
+            period: c.period,
+            options: Object.keys(c.options),
+            default: c.default ?? null,
+        })),
+        memberships: membershipsUsed(card),
+        activation: activationRules(card, today),
+        needsAnniversary: needsAnniversary(card),
+    };
+}
+// Every word of the query has to match a word of the card's id, name or
+// issuer (as a prefix, or with a typo or two in a long word). With no full
+// match, the cards matching the most words come back instead.
+export function searchCards(catalog, query, wallet, today) {
+    const tokens = words(query);
+    const scored = catalog.cards.map((card) => {
+        const matches = matcher(card);
+        return { card, score: tokens.filter((t) => matches(t)).length };
+    });
+    const byShortestId = (a, b) => words(a.card.id).length - words(b.card.id).length ||
+        a.card.id.localeCompare(b.card.id);
+    const full = scored.filter((s) => s.score === tokens.length);
+    const best = Math.max(0, ...scored.map((s) => s.score));
+    const exact = full.length > 0;
+    const chosen = exact
+        ? full.sort(byShortestId)
+        : best === 0
+            ? []
+            : scored
+                .filter((s) => s.score === best)
+                .sort(byShortestId)
+                .slice(0, 5);
+    return {
+        cards: chosen.map((s) => cardInfo(s.card, wallet, today)),
+        exact,
+    };
+}
+const list = (ids) => ids.join(', ');
+// What a card in the wallet still needs before its answers are right.
+export function setupNotes(catalog, wallet, held, today) {
+    const card = catalog.cards.find((c) => c.id === held.id);
+    if (!card)
+        return [];
+    const notes = [];
+    const name = held.checkout_label ?? card.name;
+    const { picked, staleChoice } = pickedCategories(card, held, today);
+    for (const choice of card.choices) {
+        const current = held.chosen?.picks[choice.id] !== undefined &&
+            (staleChoice === null || choice.period === 'until_changed');
+        if (current)
+            continue;
+        const options = list(Object.keys(choice.options));
+        notes.push({
+            kind: 'pick',
+            text: choice.default && picked.has(choice.id)
+                ? `${name}'s ${choice.id} pick is assumed to be ${list(choice.default)}, the default. Set it if a different one was picked (${String(choice.pick)} of: ${options}).`
+                : `${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));
+    if (missing.length > 0) {
+        notes.push({
+            kind: 'membership',
+            text: `Some of ${name}'s rates need a membership: ${list(missing)}. Add any that apply to the wallet's memberships.`,
+        });
+    }
+    const toActivate = activationRules(card, today).filter((id) => !held.activated.includes(id));
+    if (toActivate.length > 0) {
+        notes.push({
+            kind: 'activation',
+            text: `${name} has rates that apply only once activated with the issuer: ${list(toActivate)}. Mark the ones already activated.`,
+        });
+    }
+    if (needsAnniversary(card) && held.anniversary === undefined) {
+        notes.push({
+            kind: 'anniversary',
+            text: `${name} has a cap that resets on the card's anniversary. Add the anniversary (MM-DD) so it can be tracked.`,
+        });
+    }
+    const gap = rotationGap(card, today);
+    if (gap !== null) {
+        notes.push({
+            kind: 'rotation',
+            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 };
+}

package/dist/engine/wallet-change.js

@@ -0,0 +1,179 @@
+import { periodKey } from "./periods.js";
+import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
+const failed = (error) => ({ ok: false, error });
+const list = (ids) => ids.join(', ');
+export function findCatalogCard(catalog, id, today) {
+    const card = catalog.cards.find((c) => c.id === id);
+    if (card)
+        return card;
+    const near = searchCards(catalog, id, null, today).cards.map((c) => c.id);
+    return near.length > 0
+        ? `No card '${id}' in earnrate. Closest: ${list(near)}.`
+        : `No card '${id}' in earnrate. Search the catalog to find its id.`;
+}
+export function isAnniversary(text) {
+    const m = /^(\d{2})-(\d{2})$/.exec(text);
+    if (!m)
+        return false;
+    const date = new Date(`2024-${text}T00:00:00Z`); // a leap year allows 02-29
+    return (!Number.isNaN(date.getTime()) && date.toISOString().slice(5, 10) === text);
+}
+// The period key picks are filed under: the card's choice period, or for
+// picks that carry over, the current year (it's never compared).
+function pickPeriod(card, today) {
+    const periods = [
+        ...new Set(card.choices.map((c) => c.period).filter((p) => p !== 'until_changed')),
+    ];
+    if (periods.length > 1)
+        return null;
+    return periodKey(periods[0] ?? 'calendar_year', today, null);
+}
+export function cardFields(card, held, input, today) {
+    const problems = [];
+    const fields = {};
+    if (input.checkoutLabel !== undefined) {
+        if (input.checkoutLabel.trim() === '')
+            problems.push('The checkout label is empty.');
+        // earnrate never stores card numbers; a last four is fine.
+        if (/\d{8,}/.test(input.checkoutLabel.replace(/[\s-]/g, '')))
+            problems.push('The checkout label looks like it has a card number in it. earnrate never stores card numbers; use a name like "Amex Gold".');
+        fields.checkout_label = input.checkoutLabel.trim();
+    }
+    if (input.anniversary !== undefined) {
+        if (!isAnniversary(input.anniversary)) {
+            problems.push(`"${input.anniversary}" isn't an anniversary. Use MM-DD, like 03-15.`);
+        }
+        fields.anniversary = input.anniversary;
+    }
+    if (input.activated !== undefined) {
+        const needing = card.rules
+            .filter((r) => r.requires?.activation)
+            .map((r) => r.id);
+        for (const id of input.activated) {
+            if (!needing.includes(id)) {
+                problems.push(needing.length > 0
+                    ? `'${id}' isn't a ${card.id} rule that needs activating. Those are: ${list(needing)}.`
+                    : `${card.id} has no rules that need activating.`);
+            }
+        }
+        fields.activated = [...new Set(input.activated)];
+    }
+    if (input.picks !== undefined) {
+        for (const [choiceId, picks] of Object.entries(input.picks)) {
+            const choice = card.choices.find((c) => c.id === choiceId);
+            if (!choice) {
+                problems.push(card.choices.length > 0
+                    ? `${card.id} has no '${choiceId}' pick. Its picks are: ${list(card.choices.map((c) => c.id))}.`
+                    : `${card.id} has no categories to pick.`);
+                continue;
+            }
+            const options = Object.keys(choice.options);
+            for (const p of picks) {
+                if (!options.includes(p)) {
+                    problems.push(`'${p}' isn't a ${choiceId} option for ${card.id}. Options: ${list(options)}.`);
+                }
+            }
+            if (picks.length === 0 || picks.length > choice.pick) {
+                problems.push(`${choiceId} takes ${choice.pick === 1 ? '1 pick' : `1 to ${String(choice.pick)} picks`}, not ${String(picks.length)}.`);
+            }
+        }
+        const period = pickPeriod(card, today);
+        if (period === null) {
+            problems.push(`${card.id} has picks on different schedules; edit the wallet by hand.`);
+        }
+        else {
+            const kept = held?.chosen?.period === period ? held.chosen.picks : {};
+            fields.chosen = {
+                period,
+                picks: { ...kept, ...input.picks },
+            };
+        }
+    }
+    return problems.length > 0 ? problems.join('\n') : fields;
+}
+export const newHolding = (id) => ({
+    id,
+    cap_usage: {},
+    activated: [],
+});
+export const withFields = (held, f) => ({
+    ...held,
+    ...(f.checkout_label === undefined
+        ? {}
+        : { checkout_label: f.checkout_label }),
+    ...(f.anniversary === undefined ? {} : { anniversary: f.anniversary }),
+    ...(f.chosen === undefined ? {} : { chosen: f.chosen }),
+    ...(f.activated === undefined ? {} : { activated: f.activated }),
+});
+// `wallet` is null when there isn't one yet; adding a card starts it.
+export function addToWallet(catalog, wallet, input, today) {
+    const card = findCatalogCard(catalog, input.id, today);
+    if (typeof card === 'string')
+        return failed(card);
+    if (wallet?.cards.some((c) => c.id === card.id)) {
+        return failed(`${card.id} is already in the wallet. Update it instead.`);
+    }
+    const fields = cardFields(card, null, input, today);
+    if (typeof fields === 'string')
+        return failed(fields);
+    const held = withFields(newHolding(card.id), fields);
+    const next = wallet
+        ? { ...wallet, cards: [...wallet.cards, held] }
+        : { valuations: {}, memberships: [], cards: [held] };
+    return {
+        ok: true,
+        wallet: next,
+        fields,
+        notes: setupNotes(catalog, next, held, today),
+    };
+}
+export function updateInWallet(catalog, wallet, input, today) {
+    const held = wallet.cards.find((c) => c.id === input.id);
+    const card = catalog.cards.find((c) => c.id === input.id);
+    if (!held || !card) {
+        return failed(`${input.id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
+    }
+    const fields = cardFields(card, held, input, today);
+    if (typeof fields === 'string')
+        return failed(fields);
+    if (Object.keys(fields).length === 0)
+        return failed('Nothing to change.');
+    const updated = withFields(held, fields);
+    const next = {
+        ...wallet,
+        cards: wallet.cards.map((c) => (c.id === held.id ? updated : c)),
+    };
+    return {
+        ok: true,
+        wallet: next,
+        fields,
+        notes: setupNotes(catalog, next, updated, today),
+    };
+}
+export function removeFromWallet(wallet, id) {
+    if (!wallet.cards.some((c) => c.id === id)) {
+        return failed(`${id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
+    }
+    if (wallet.cards.length === 1) {
+        return failed(`${id} is the last card in the wallet, and a wallet needs one. Add the new card first, then remove this one.`);
+    }
+    return {
+        ok: true,
+        wallet: { ...wallet, cards: wallet.cards.filter((c) => c.id !== id) },
+        fields: {},
+        notes: [],
+    };
+}
+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 {
+        ok: true,
+        wallet: { ...wallet, memberships: [...new Set(memberships)] },
+        fields: {},
+        notes: [],
+    };
+}

package/dist/engine/wallet-summary.js

@@ -1,6 +1,7 @@
 import { bonusStatus } from "./bonus.js";
 import { pickedCategories } from "./evaluate.js";
 import { daysBetween, periodKey } from "./periods.js";
+import { rotationGap } from "./rotation.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { cardValuation } from "./valuation.js";
 function capSummaries(card, held, today) {
@@ -54,6 +55,7 @@ export function walletSummary(catalog, wallet, today) {
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,
             dataIsStale: daysBetween(card.last_verified, today) > STALE_AFTER_DAYS,
+            rotationGap: rotationGap(card, today),
             caps: capSummaries(card, held, today),
             chosen: held.chosen
                 ? {