earnrate 0.1.2 → 0.1.3

package/dist/data/wallet-setup.js

@@ -1,107 +1,6 @@
-import { periodKey } from "../engine/periods.js";
-import { knownMemberships, searchCards, setupNotes, } from "../engine/setup.js";
-import { WalletCardSchema, WalletSchema, } from "../schema/wallet.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
 import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, updateCardText, } from "./wallet-edit.js";
 const failed = (error) => ({ ok: false, error });
-const list = (ids) => ids.join(', ');
-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.`;
-}
-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 choicePeriod(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);
-}
-function fieldsFor(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 = choicePeriod(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;
-}
-const applyFields = (held, f) => WalletCardSchema.parse({
-    ...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 }),
-});
 async function attempt(task) {
     try {
         return await task();
@@ -111,29 +10,19 @@ async function attempt(task) {
     }
 }
 const noWallet = (file) => `No wallet at ${file} yet. Add a card first to create it.`;
+// The change is worked out on the parsed wallet, then spliced into the file
+// text, which must re-parse to exactly that wallet before it's written.
+async function commit(file, edited, change, created) {
+    await commitWalletText(file, edited, change.wallet);
+    return { ok: true, wallet: change.wallet, created, notes: change.notes };
+}
 export function addCard(file, catalog, input, today) {
     return attempt(async () => {
-        const card = findCatalogCard(catalog, input.id, today);
-        if (typeof card === 'string')
-            return failed(card);
         const { text, wallet } = await readWalletText(file);
-        if (wallet?.cards.some((c) => c.id === card.id)) {
-            return failed(`${card.id} is already in the wallet. Update it instead.`);
-        }
-        const fields = fieldsFor(card, null, input, today);
-        if (typeof fields === 'string')
-            return failed(fields);
-        const held = applyFields(WalletCardSchema.parse({ id: card.id }), fields);
-        const expected = wallet
-            ? { ...wallet, cards: [...wallet.cards, held] }
-            : WalletSchema.parse({ cards: [held] });
-        await commitWalletText(file, addCardText(text, { id: card.id, ...fields }), expected);
-        return {
-            ok: true,
-            wallet: expected,
-            created: text === null,
-            notes: setupNotes(catalog, expected, held, today),
-        };
+        const change = addToWallet(catalog, wallet, input, today);
+        if (!change.ok)
+            return change;
+        return commit(file, addCardText(text, { id: input.id, ...change.fields }), change, text === null);
     });
 }
 export function updateCard(file, catalog, input, today) {
@@ -141,28 +30,10 @@ export function updateCard(file, catalog, input, today) {
         const { text, wallet } = await readWalletText(file);
         if (text === null || wallet === null)
             return failed(noWallet(file));
-        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 = fieldsFor(card, held, input, today);
-        if (typeof fields === 'string')
-            return failed(fields);
-        if (Object.keys(fields).length === 0)
-            return failed('Nothing to change.');
-        const updated = applyFields(held, fields);
-        const expected = {
-            ...wallet,
-            cards: wallet.cards.map((c) => (c.id === held.id ? updated : c)),
-        };
-        await commitWalletText(file, updateCardText(text, held.id, fields), expected);
-        return {
-            ok: true,
-            wallet: expected,
-            created: false,
-            notes: setupNotes(catalog, expected, updated, today),
-        };
+        const change = updateInWallet(catalog, wallet, input, today);
+        if (!change.ok)
+            return change;
+        return commit(file, updateCardText(text, input.id, change.fields), change, false);
     });
 }
 export function removeCard(file, _catalog, id) {
@@ -170,33 +41,20 @@ export function removeCard(file, _catalog, id) {
         const { text, wallet } = await readWalletText(file);
         if (text === null || wallet === null)
             return failed(noWallet(file));
-        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.`);
-        }
-        const expected = {
-            ...wallet,
-            cards: wallet.cards.filter((c) => c.id !== id),
-        };
-        await commitWalletText(file, removeCardText(text, id), expected);
-        return { ok: true, wallet: expected, created: false, notes: [] };
+        const change = removeFromWallet(wallet, id);
+        if (!change.ok)
+            return change;
+        return commit(file, removeCardText(text, id), change, false);
     });
 }
 export function setMemberships(file, catalog, memberships) {
     return attempt(async () => {
-        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)}.`);
-        }
         const { text, wallet } = await readWalletText(file);
         if (text === null || wallet === null)
             return failed(noWallet(file));
-        const unique = [...new Set(memberships)];
-        const expected = { ...wallet, memberships: unique };
-        await commitWalletText(file, setMembershipsText(text, unique), expected);
-        return { ok: true, wallet: expected, created: false, notes: [] };
+        const change = withMemberships(catalog, wallet, memberships);
+        if (!change.ok)
+            return change;
+        return commit(file, setMembershipsText(text, change.wallet.memberships), change, false);
     });
 }

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;