earnrate 0.1.4 → 0.2.0

package/dist/engine/record.js

@@ -1,4 +1,5 @@
 import { resolveMerchant } from "../merchants/resolve.js";
+import { bonusStatus, countsTowardBonus } from "./bonus.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
 const roundCents = (n) => Math.round(n * 100) / 100;
 // Books the spend against the cap of the highest-rate rule that matches, even
@@ -53,3 +54,37 @@ export function recordPurchase(catalog, wallet, purchase) {
     const booking = capBooking(catalog, wallet, purchase);
     return booking ? applyBooking(wallet, booking) : wallet;
 }
+// The purchase's progress toward the card's open welcome bonus, if it counts.
+export function bonusBooking(catalog, wallet, purchase) {
+    const held = wallet.cards.find((c) => c.id === purchase.cardId);
+    const status = held ? bonusStatus(catalog, wallet, held, purchase.date) : null;
+    if (!status ||
+        status.spend === null ||
+        (status.remaining ?? 0) <= 0 ||
+        !countsTowardBonus(status, purchase.date))
+        return null;
+    return {
+        cardId: purchase.cardId,
+        before: status.spent,
+        after: roundCents(status.spent + purchase.amount),
+        spend: status.spend,
+        deadline: status.deadline,
+    };
+}
+export function applyBonusBooking(wallet, b) {
+    return {
+        ...wallet,
+        cards: wallet.cards.map((c) => c.id === b.cardId && c.bonus
+            ? { ...c, bonus: { ...c.bonus, spent: b.after } }
+            : c),
+    };
+}
+// Everything recording a purchase changes: its cap and its welcome bonus.
+export function bookPurchase(catalog, wallet, purchase, merchant) {
+    const cap = capBooking(catalog, wallet, purchase, merchant);
+    const bonus = bonusBooking(catalog, wallet, purchase);
+    let next = cap ? applyBooking(wallet, cap) : wallet;
+    if (bonus)
+        next = applyBonusBooking(next, bonus);
+    return { wallet: next, cap, bonus };
+}

package/dist/engine/simulate.js

@@ -1,6 +1,6 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
-import { categoryResolution, choicePeriod, idealHolding, matchesFilters, } from "./explore.js";
+import { categoryResolution, choicePeriod, findCategory, idealHolding, matchesFilters, } from "./explore.js";
 import { periodKey } from "./periods.js";
 import { applyBooking, capBooking } from "./record.js";
 import { rotationGap } from "./rotation.js";
@@ -307,3 +307,24 @@ export function simulateAdditions(catalog, wallet, lines, options) {
     additions.sort((a, b) => b.gain - a.gain || a.annualFee - b.annualFee);
     return { current, additions };
 }
+// Rough monthly amounts for a U.S. household: the starting point when someone
+// hasn't said what they spend. Answers built on them say so.
+export const TYPICAL_MONTHLY_SPEND = [
+    { what: 'Groceries', monthly: 500 },
+    { what: 'Dining', monthly: 250 },
+    { what: 'Gas', monthly: 150 },
+    { what: 'Amazon', monthly: 100 },
+    { what: 'Streaming', monthly: 40 },
+    { what: 'Travel', monthly: 150 },
+    { what: 'Everything else', monthly: 800 },
+];
+// A spending line from everyday words: a category when one matches
+// ("groceries"), otherwise a merchant ("Amazon").
+export function spendLineFor(catalog, what, monthly) {
+    const category = findCategory(catalog, what);
+    return { merchant: category === null ? what : null, category, monthly };
+}
+export function typicalSpendLines(catalog) {
+    return resolveSpendLines(catalog, TYPICAL_MONTHLY_SPEND.map((t) => spendLineFor(catalog, t.what, t.monthly)));
+}
+export const TYPICAL_SPEND_NOTE = `No spending was given, so this uses rough typical monthly amounts for a U.S. household: ${TYPICAL_MONTHLY_SPEND.map((t) => `${t.what} $${String(t.monthly)}`).join(', ')}. Give your own amounts for a closer answer.`;

package/dist/engine/transient.js

@@ -0,0 +1,21 @@
+import { addToWallet, withMemberships, } from "./wallet-change.js";
+// A wallet for one answer, from cards the user named in the conversation.
+// Nothing is saved; the same rules as adding cards to a saved wallet apply.
+export function walletFromCards(catalog, named, today) {
+    let wallet = null;
+    for (const input of named.cards) {
+        const change = addToWallet(catalog, wallet, input, today);
+        if (!change.ok)
+            return change.error;
+        wallet = change.wallet;
+    }
+    if (!wallet)
+        return 'Name at least one card.';
+    if (named.memberships && named.memberships.length > 0) {
+        const change = withMemberships(catalog, wallet, named.memberships);
+        if (!change.ok)
+            return change.error;
+        wallet = change.wallet;
+    }
+    return wallet;
+}

package/dist/engine/wallet-change.js

@@ -89,6 +89,31 @@ export function cardFields(card, held, input, today) {
             };
         }
     }
+    if (input.bonus === null)
+        fields.bonus = null;
+    else if (input.bonus !== undefined) {
+        const b = input.bonus;
+        const isDate = (d) => /^\d{4}-\d{2}-\d{2}$/.test(d) &&
+            new Date(`${d}T00:00:00Z`).toISOString().startsWith(d);
+        if (!isDate(b.opened))
+            problems.push(`"${b.opened}" isn't a date. Use YYYY-MM-DD.`);
+        else if (b.opened > today)
+            problems.push("The account's opening date is in the future.");
+        if (b.spent !== undefined && !(b.spent >= 0))
+            problems.push('Spending toward the bonus must be $0 or more.');
+        if (b.spend !== undefined && !(b.spend > 0))
+            problems.push('The spending needed must be more than $0.');
+        if (b.by !== undefined && (!isDate(b.by) || b.by < b.opened))
+            problems.push(`"${b.by}" isn't a deadline after the opening date.`);
+        if (!card.welcome_offer && (b.spend === undefined || b.by === undefined))
+            problems.push(`earnrate has no published welcome offer for ${card.id}, so give the spending needed and the deadline.`);
+        fields.bonus = {
+            opened: b.opened,
+            spent: b.spent ?? held?.bonus?.spent ?? 0,
+            ...(b.spend === undefined ? {} : { spend: b.spend }),
+            ...(b.by === undefined ? {} : { by: b.by }),
+        };
+    }
     return problems.length > 0 ? problems.join('\n') : fields;
 }
 export const newHolding = (id) => ({
@@ -96,14 +121,16 @@ export const newHolding = (id) => ({
     cap_usage: {},
     activated: [],
 });
-export const withFields = (held, f) => ({
+export const withFields = ({ bonus, ...held }, f) => ({
     ...held,
+    ...(bonus && f.bonus === undefined ? { bonus } : {}),
     ...(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 }),
+    ...(f.bonus ? { bonus: f.bonus } : {}),
 });
 // `wallet` is null when there isn't one yet; adding a card starts it.
 export function addToWallet(catalog, wallet, input, today) {

package/dist/format/cheat-sheet.js

@@ -0,0 +1,19 @@
+const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
+export function formatCheatSheet(sheet) {
+    const labelWidth = Math.max(...sheet.rows.map((r) => r.label.length));
+    const cardWidth = Math.max(...sheet.rows.map((r) => (r.cardName ?? 'none of your cards').length));
+    const lines = [
+        sheet.scope === 'wallet'
+            ? `Your cheat sheet for ${sheet.quarter}`
+            : `The best card for each kind of purchase, ${sheet.quarter}`,
+        '',
+    ];
+    for (const row of sheet.rows) {
+        lines.push(`  ${row.label.padEnd(labelWidth)}  ${(row.cardName ?? 'none of your cards').padEnd(cardWidth)}  ${row.effectiveReturnPct === null ? '' : pct(row.effectiveReturnPct).padStart(5)}`.trimEnd());
+        if (row.note)
+            lines.push(`  ${' '.repeat(labelWidth)}  ${sheet.scope === 'wallet' ? '! ' : ''}${row.note}`);
+    }
+    if (sheet.notes.length > 0)
+        lines.push('', ...sheet.notes);
+    return `${lines.join('\n')}\n`;
+}

package/dist/format/explore.js

@@ -0,0 +1,124 @@
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+const wholeUsd = (n) => usd(Math.round(n));
+const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
+function feeText(e) {
+    if (e.annualFee === null)
+        return 'annual fee not on file';
+    if (e.annualFee === 0)
+        return 'no annual fee';
+    if (e.firstYearFee !== null && e.firstYearFee !== e.annualFee)
+        return `${usd(e.annualFee)} annual fee (${e.firstYearFee === 0 ? 'waived' : usd(e.firstYearFee)} the first year)`;
+    return `${usd(e.annualFee)} annual fee`;
+}
+const TOP_BEST = 10;
+export function formatExploration(r, all) {
+    const m = r.merchant;
+    const title = m.source === 'category'
+        ? m.resolvedName.toLowerCase()
+        : m.source === 'none'
+            ? `"${m.input}" (not recognized)`
+            : m.resolvedName;
+    if (r.ranked.length === 0)
+        return `No cards match at ${title}.\n`;
+    const shown = all ? r.ranked : r.ranked.slice(0, TOP_BEST);
+    const width = Math.max(...shown.map((e) => e.cardName.length));
+    const lines = [`Best cards for ${title}:`, ''];
+    shown.forEach((e, i) => {
+        const earned = e.earned === null ? '' : `  ${usd(e.earned)}`;
+        lines.push(`${String(i + 1).padStart(2)}. ${e.cardName.padEnd(width)}  ${pct(e.effectiveReturnPct).padStart(5)}${earned}  ${feeText(e)}`);
+        for (const c of e.conditions)
+            lines.push(`    ${c}`);
+        const upgrade = e.withMembership[0];
+        if (upgrade)
+            lines.push(`    With ${upgrade.membership}: ${pct(upgrade.effectiveReturnPct)}.`);
+        for (const w of e.warnings)
+            lines.push(`    ! ${w}`);
+    });
+    if (r.ranked.length > shown.length)
+        lines.push(`  + ${String(r.ranked.length - shown.length)} more (--all lists them)`);
+    for (const w of r.warnings)
+        lines.push('', `! ${w}`);
+    lines.push('', ...r.assumptions);
+    return `${lines.join('\n')}\n`;
+}
+function picksText(picks) {
+    const parts = Object.entries(picks).map(([choice, options]) => `${choice}: ${options.join(', ')}`);
+    return parts.length === 0 ? '' : ` (picks ${parts.join('; ')})`;
+}
+function cardNamer(catalog) {
+    return (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+}
+function splitText(sim, name) {
+    const byCard = new Map();
+    for (const line of sim.lines) {
+        const first = line.cards[0];
+        if (first === undefined)
+            continue;
+        byCard.set(first, [...(byCard.get(first) ?? []), line.label]);
+    }
+    return [...byCard].map(([id, labels]) => `${labels.join(', ')} → ${name(id)}`);
+}
+const TOP_SIMULATED = 5;
+export function formatCatalogSimulation(r, catalog, all) {
+    const name = cardNamer(catalog);
+    const first = r.singles[0];
+    if (!first)
+        return 'No cards match.\n';
+    const top = all ? 20 : TOP_SIMULATED;
+    const lines = [
+        `A year of this spending: ${wholeUsd(first.spend)}.`,
+        '',
+        'Best single cards (rewards minus annual fee, per year):',
+    ];
+    r.singles.slice(0, top).forEach((s, i) => {
+        const card = s.cards[0];
+        if (!card)
+            return;
+        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeUsd(s.net)}  (${wholeUsd(s.rewards)} rewards, ${wholeUsd(s.annualFees)} fee)${picksText(card.picks)}`);
+    });
+    const pairs = r.pairs.slice(0, top);
+    if (pairs.length > 0) {
+        lines.push('', 'Best two-card pairs:');
+        pairs.forEach((s, i) => {
+            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeUsd(s.net)}`);
+            if (s.alternatives.length > 0)
+                lines.push(`    Same result with ${s.alternatives.map(name).join(' or ')} as the second card.`);
+            for (const split of splitText(s, name))
+                lines.push(`    ${split}`);
+        });
+        const bestPair = r.pairs[0];
+        if (bestPair && bestPair.net <= first.net)
+            lines.push('', `One card is enough here: no pair beats ${name(first.cards[0]?.cardId ?? '')}.`);
+    }
+    const notes = new Set([
+        ...r.singles.slice(0, top).flatMap((s) => s.notes),
+        ...pairs.flatMap((s) => s.notes),
+    ]);
+    if (notes.size > 0)
+        lines.push('', ...notes);
+    lines.push('', "Assumes each card's best picks, activations done each quarter, and no welcome bonuses.");
+    return `${lines.join('\n')}\n`;
+}
+export function formatAdditions(r, catalog, all) {
+    const name = cardNamer(catalog);
+    const lines = [
+        `Your wallet earns about ${wholeUsd(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeUsd(r.current.annualFees)} in annual fees` : ''}.`,
+    ];
+    for (const split of splitText(r.current, name))
+        lines.push(`  ${split}`);
+    const gains = r.additions.filter((a) => a.gain > 0);
+    if (gains.length === 0) {
+        lines.push('', 'No card would add more than its annual fee costs.');
+    }
+    else {
+        lines.push('', 'Cards that would add the most (after their annual fee):');
+        gains.slice(0, all ? 20 : TOP_SIMULATED).forEach((a, i) => {
+            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeUsd(a.gain)} a year  (+${wholeUsd(a.extraRewards)} rewards, ${wholeUsd(a.annualFee)} fee)${picksText(a.picks)}`);
+        });
+    }
+    const notes = new Set(r.current.notes);
+    if (notes.size > 0)
+        lines.push('', ...notes);
+    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh.');
+    return `${lines.join('\n')}\n`;
+}

package/dist/format/offers.js

@@ -0,0 +1,42 @@
+const TOP = 10;
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+function reward(o, currencyName) {
+    if (o.dollars !== null)
+        return usd(o.dollars);
+    return `${(o.points ?? 0).toLocaleString('en-US')} ${currencyName}`;
+}
+function feeText(o) {
+    if (o.annualFee === null)
+        return 'annual fee not on file';
+    if (o.annualFee === 0)
+        return 'no annual fee';
+    if (o.firstYearFee !== null && o.firstYearFee !== o.annualFee)
+        return `${usd(o.annualFee)} annual fee (${o.firstYearFee === 0 ? 'waived' : usd(o.firstYearFee)} the first year)`;
+    return `${usd(o.annualFee)} annual fee`;
+}
+export function formatOffers(c, currencyName, all) {
+    if (c.offers.length === 0) {
+        return `No published welcome offers match.${c.withoutOffer.length > 0 ? ` ${String(c.withoutOffer.length)} matching card(s) have none on file.` : ''}\n`;
+    }
+    const shown = all ? c.offers : c.offers.slice(0, TOP);
+    const width = Math.max(...shown.map((o) => o.cardName.length));
+    const lines = [];
+    shown.forEach((o, i) => {
+        const weeks = (o.months * 52) / 12;
+        const pace = o.spend > 0 ? ` (about ${usd(Math.round(o.spend / weeks))} a week)` : '';
+        const spend = o.spend > 0
+            ? `after ${usd(o.spend)} in ${String(o.months)} month${o.months === 1 ? '' : 's'}${pace}`
+            : 'with no spending required';
+        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${usd(Math.round(o.firstYearValue))} the first year`, `    ${reward(o, currencyName(o.currency))} ${spend}. ${feeText(o)[0]?.toUpperCase() ?? ''}${feeText(o).slice(1)}.${o.held ? ' In your wallet.' : ''}`);
+        if (o.validTo)
+            lines.push(`    Offer ends ${o.validTo}.`);
+        if (o.note)
+            lines.push(`    ${o.note}`);
+    });
+    if (c.offers.length > shown.length)
+        lines.push(`  + ${String(c.offers.length - shown.length)} more (--all lists them)`);
+    if (c.withoutOffer.length > 0)
+        lines.push('', `${String(c.withoutOffer.length)} matching card(s) have no published offer on file.`);
+    lines.push('', ...c.notes);
+    return `${lines.join('\n')}\n`;
+}

package/dist/format/wallet-yaml.js

@@ -0,0 +1,45 @@
+import { parse, stringify } from 'yaml';
+import { walletProblems } from "../data/integrity.js";
+import { WalletSchema } from "../schema/wallet.js";
+// A wallet as the YAML file the CLI reads, for moving it between the
+// website, the remote server and the command line. Node-free.
+function compact(wallet) {
+    return {
+        ...(Object.keys(wallet.valuations).length > 0
+            ? { valuations: wallet.valuations }
+            : {}),
+        ...(wallet.memberships.length > 0
+            ? { memberships: wallet.memberships }
+            : {}),
+        cards: wallet.cards.map((c) => ({
+            id: c.id,
+            ...(c.checkout_label === undefined
+                ? {}
+                : { checkout_label: c.checkout_label }),
+            ...(c.anniversary === undefined ? {} : { anniversary: c.anniversary }),
+            ...(Object.keys(c.cap_usage).length > 0
+                ? { cap_usage: c.cap_usage }
+                : {}),
+            ...(c.chosen === undefined ? {} : { chosen: c.chosen }),
+            ...(c.activated.length > 0 ? { activated: c.activated } : {}),
+            ...(c.bonus === undefined ? {} : { bonus: c.bonus }),
+        })),
+    };
+}
+export function walletYaml(wallet) {
+    return `# Your earnrate wallet: the cards you hold, by id. Never card numbers.\n# For the command line, save it as ~/.earnrate/wallet.yaml\n\n${stringify(compact(wallet))}`;
+}
+export function parseWalletYaml(text, catalog) {
+    let raw;
+    try {
+        raw = parse(text);
+    }
+    catch {
+        return "That isn't a wallet: it isn't valid YAML.";
+    }
+    const result = WalletSchema.safeParse(raw);
+    if (!result.success)
+        return "That isn't an earnrate wallet.";
+    const problems = walletProblems(result.data, catalog);
+    return problems.length > 0 ? problems.join(' ') : result.data;
+}

package/dist/mcp/schemas.js

@@ -17,7 +17,7 @@ export const MerchantResolutionSchema = z.object({
         .nullable(),
     channel: Channel.nullable(),
     confidence: Confidence,
-    source: z.enum(['override', 'seed', 'llm', 'caller', 'none']),
+    source: z.enum(['override', 'seed', 'llm', 'caller', 'category', 'none']),
     bookedVia: z.array(z.string()),
     inference: z
         .object({
@@ -277,6 +277,7 @@ const SimulationSchema = z.object({
     notes: z.array(z.string()),
 });
 export const SpendingSimulationSchema = z.object({
+    notes: z.array(z.string()),
     singles: z.array(SimulationSchema),
     pairs: z.array(SimulationSchema.extend({ alternatives: z.array(z.string()) })),
     current: SimulationSchema.nullable(),
@@ -289,6 +290,7 @@ export const SpendingSimulationSchema = z.object({
     })),
 });
 export const CheatSheetSchema = z.object({
+    scope: z.enum(['wallet', 'all cards']),
     quarter: z.string(),
     date: z.string(),
     rows: z.array(z.object({
@@ -301,3 +303,7 @@ export const CheatSheetSchema = z.object({
     })),
     notes: z.array(z.string()),
 });
+export const PurchaseAnswerSchema = RecommendationSchema.extend({
+    // Every card earnrate knows, ranked: set when no cards were given.
+    allCards: ExplorationSchema.nullable(),
+});

package/dist/mcp/serve.js

@@ -1,4 +1,5 @@
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { FileWalletStore } from "../data/file-store.js";
 import { loadCatalog, walletPath } from "../data/load.js";
 import { localToday as today } from "../engine/periods.js";
 import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
@@ -21,7 +22,8 @@ export async function serveMcp(env) {
     }
     serveStdio(() => createEarnrateServer({
         catalog,
-        walletFile: walletPath(env),
+        store: new FileWalletStore(catalog, walletPath(env)),
+        savedWallets: 'file',
         today,
         llm,
         version,