earnrate 0.1.2 → 0.1.3

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/mcp/schemas.js

@@ -218,3 +218,73 @@ export const WalletChangeSchema = z.object({
         text: z.string(),
     })),
 });
+const ExcludedCardSchema = z.object({
+    cardId: z.string(),
+    cardName: z.string(),
+    checkoutLabel: z.string().nullable(),
+    network: Network,
+    reason: z.string(),
+});
+const Picks = z.record(z.string(), z.array(z.string()));
+export const ExplorationSchema = z.object({
+    merchant: MerchantResolutionSchema,
+    ranked: z.array(RankedCardSchema.extend({
+        issuer: z.string(),
+        network: CardNetwork,
+        annualFee: z.number().nullable(),
+        firstYearFee: z.number().nullable(),
+        picks: Picks,
+        requirements: z.object({
+            pick: z
+                .object({
+                choice: z.string(),
+                options: z.array(z.string()),
+                period: z.string(),
+            })
+                .nullable(),
+            activation: z.string().nullable(),
+            membership: z.string().nullable(),
+            cap: z
+                .object({
+                amount: z.number(),
+                period: z.string(),
+                thenRate: z.number(),
+                currency: z.string(),
+            })
+                .nullable(),
+        }),
+        conditions: z.array(z.string()),
+        evidence: z.object({ quote: z.string(), url: z.string() }).nullable(),
+        withMembership: z.array(z.object({ membership: z.string(), effectiveReturnPct: z.number() })),
+    })),
+    excluded: z.array(ExcludedCardSchema),
+    assumptions: z.array(z.string()),
+    warnings: z.array(z.string()),
+});
+const SimulationSchema = z.object({
+    cards: z.array(z.object({ cardId: z.string(), picks: Picks })),
+    spend: z.number(),
+    rewards: z.number(),
+    annualFees: z.number(),
+    net: z.number(),
+    lines: z.array(z.object({
+        label: z.string(),
+        spend: z.number(),
+        earned: z.number(),
+        returnPct: z.number(),
+        cards: z.array(z.string()),
+    })),
+    notes: z.array(z.string()),
+});
+export const SpendingSimulationSchema = z.object({
+    singles: z.array(SimulationSchema),
+    pairs: z.array(SimulationSchema.extend({ alternatives: z.array(z.string()) })),
+    current: SimulationSchema.nullable(),
+    additions: z.array(z.object({
+        cardId: z.string(),
+        picks: Picks,
+        extraRewards: z.number(),
+        annualFee: z.number(),
+        gain: z.number(),
+    })),
+});