earnrate 0.1.4 → 0.2.1

package/dist/engine/explore.js

@@ -1,9 +1,10 @@
 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 { choicePeriod, periodKey } from "./periods.js";
+import { recommend } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
+import { categoryPhrase, codesAs, earnText, money, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 export const ALL_PERSONAL_CARDS = {
@@ -29,18 +30,11 @@ export function matchesFilters(card, filters) {
         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);
+    const period = choicePeriod(card) ?? 'calendar_year';
     return {
         id: card.id,
         anniversary: date.slice(5),
@@ -92,7 +86,7 @@ export function categoryResolution(catalog, category, channel) {
         ambiguity: null,
         channel,
         confidence: 'high',
-        source: 'caller',
+        source: 'category',
         bookedVia: [],
         inference: null,
     };
@@ -163,7 +157,7 @@ function conditionsText(catalog, r) {
     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)}.`);
+        conditions.push(`Up to ${money(r.cap.amount)} ${CAP_PERIODS[r.cap.period] ?? ''} at this rate, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}.`);
     }
     return conditions;
 }
@@ -198,10 +192,11 @@ function compareExplored(a, b) {
 }
 // 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);
+export function exploreCards(catalog, query, options, resolved) {
+    const merchant = resolved ??
+        (query.merchant !== null
+            ? resolveMerchant(catalog, query.merchant, query.channel)
+            : categoryResolution(catalog, query.category ?? 'other', query.channel));
     const purchase = {
         merchant: merchant.input,
         amount: query.amount,
@@ -257,26 +252,19 @@ export function exploreCards(catalog, query, options) {
 }
 function exploreAssumptions(catalog, merchant, ranked, options) {
     const assumptions = [];
-    if (merchant.source === 'caller') {
+    if (merchant.source === 'category') {
         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(codesAs(catalog, merchant));
     }
     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(', ')}.`);
-    }
+    const values = pointValuesText(catalog, ranked.slice(0, 10));
+    if (values !== null)
+        assumptions.push(values);
     return assumptions;
 }
 function exploreWarnings(catalog, merchant) {

package/dist/engine/offers.js

@@ -1,14 +1,7 @@
+import { bonusDollars } from "./bonus.js";
+import { matchesFilters } from "./explore.js";
+import { roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
-const round = (n) => Math.round(n * 100) / 100;
-function bonusValue(card, centsPerUnit, points, dollars) {
-    if (points !== undefined)
-        return (points * centsPerUnit) / 100;
-    if (dollars === undefined)
-        return 0;
-    // A cash back card's bonus is paid like its rewards, so it pools when they
-    // do; a points card's dollar bonus is a statement credit.
-    return card.currency === 'cash' ? dollars * centsPerUnit : dollars;
-}
 export function compareOffers(catalog, wallet, filters, today) {
     const held = new Set(wallet.cards.map((c) => c.id));
     const offers = [];
@@ -16,16 +9,9 @@ export function compareOffers(catalog, wallet, filters, today) {
     for (const card of catalog.cards) {
         if (card.network === 'store')
             continue;
-        if (card.business !== filters.business)
-            continue;
         if (!filters.includeHeld && held.has(card.id))
             continue;
-        const isCash = card.currency === 'cash';
-        if (filters.kind === 'cash' && !isCash)
-            continue;
-        if (filters.kind === 'points' && isCash)
-            continue;
-        if (filters.noAnnualFee && card.annual_fee !== 0)
+        if (!matchesFilters(card, { ...filters, issuer: null, includeClosed: true }))
             continue;
         const offer = card.welcome_offer;
         if (!offer || (offer.valid_to !== undefined && offer.valid_to < today)) {
@@ -33,7 +19,8 @@ export function compareOffers(catalog, wallet, filters, today) {
             continue;
         }
         const valuation = cardValuation(catalog, wallet, card);
-        const value = bonusValue(card, valuation.centsPerUnit, offer.points, offer.dollars);
+        const value = bonusDollars(card, valuation.centsPerUnit, offer.points, offer.dollars) ??
+            0;
         const firstYearFee = card.first_year_fee ?? card.annual_fee ?? null;
         offers.push({
             cardId: card.id,
@@ -50,8 +37,8 @@ export function compareOffers(catalog, wallet, filters, today) {
             note: offer.note ?? null,
             annualFee: card.annual_fee ?? null,
             firstYearFee,
-            bonusValue: round(value),
-            firstYearValue: round(value - (firstYearFee ?? 0)),
+            bonusValue: roundCents(value),
+            firstYearValue: roundCents(value - (firstYearFee ?? 0)),
             held: held.has(card.id),
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,

package/dist/engine/periods.js

@@ -29,3 +29,12 @@ export function localToday(now = new Date()) {
         String(now.getDate()).padStart(2, '0'),
     ].join('-');
 }
+// The period a card's picks are filed under in a wallet. Picks that carry
+// over (until_changed) are never compared, so they file under the calendar
+// year. null when the card's picks reset on different schedules.
+export function choicePeriod(card) {
+    const periods = [
+        ...new Set(card.choices.map((c) => c.period).filter((p) => p !== 'until_changed')),
+    ];
+    return periods.length > 1 ? null : (periods[0] ?? 'calendar_year');
+}

package/dist/engine/recommend.js

@@ -1,8 +1,9 @@
 import { resolveMerchant, resolveMerchantById } from "../merchants/resolve.js";
-import { evaluateCard, purchaseContext, } from "./evaluate.js";
 import { bonusStatus } from "./bonus.js";
+import { evaluateCard, purchaseContext, usableAt, } from "./evaluate.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
+import { categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, num, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 export const STALE_AFTER_DAYS = 180;
@@ -20,36 +21,9 @@ const PERIOD_WORDS = {
     cardmember_year: 'cardmember-year',
 };
 const displayName = (e) => e.held.checkout_label ?? e.card.name;
-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 })}`;
-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;
-}
-export function currencyLabel(catalog, id) {
-    const name = currencyName(catalog, id);
-    return /^[A-Z]{2,4}$/.test(id) ? `${name} (${id})` : name;
-}
 // "Worth X or more" must hold at X itself, so round up; "less than X" rounds down.
 const roundUp = (n) => String(Math.ceil(n * 100 - EPSILON) / 100);
 const roundDown = (n) => String(Math.floor(n * 100 + EPSILON) / 100);
-function categoryName(catalog, id) {
-    return catalog.categories.find((c) => c.id === id)?.name ?? id;
-}
-// Mid-sentence form: "Supermarkets" becomes "supermarkets", but "TV and
-// internet service" and "EV charging" keep their acronyms.
-export function categoryPhrase(catalog, id) {
-    const name = categoryName(catalog, id);
-    return /^[A-Z]{2}/.test(name)
-        ? name
-        : name.charAt(0).toLowerCase() + name.slice(1);
-}
-export function earnText(catalog, rate, currency) {
-    return currency === 'cash'
-        ? `${num(rate)}% cash back`
-        : `${num(rate)}x ${currencyName(catalog, currency)}`;
-}
 function compareEntries(a, b) {
     const byReturn = b.effectiveReturnPct - a.effectiveReturnPct;
     if (Math.abs(byReturn) > EPSILON)
@@ -71,14 +45,11 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
         const card = catalog.cards.find((c) => c.id === held.id);
         if (!card)
             continue;
-        if (card.only_at) {
-            if (merchant.merchantId === null ||
-                !card.only_at.includes(merchant.merchantId))
+        if (!usableAt(card, merchant)) {
+            // A store card elsewhere isn't worth mentioning; a network the merchant
+            // doesn't take is.
+            if (card.only_at || card.network === 'store' || !merchant.accepts)
                 continue;
-        }
-        else if (card.network !== 'store' &&
-            merchant.accepts &&
-            !merchant.accepts.includes(card.network)) {
             const takes = merchant.accepts
                 .map((n) => NETWORK_NAMES[n] ?? n)
                 .join(' or ');
@@ -126,7 +97,7 @@ function reasoningFor(catalog, wallet, entry, amount) {
     const cap = best.cap;
     if (cap && amount !== null && amount > cap.remaining) {
         const over = amount - cap.remaining;
-        lines.push(`${dollars(cap.remaining)} earns ${earnText(catalog, best.nominalRate, currency)} before the cap, then ${dollars(over)} earns ${earnText(catalog, cap.cap.then_rate, currency)}: ${num(best.rate)} per dollar overall.`);
+        lines.push(`${money(cap.remaining)} earns ${earnText(catalog, best.nominalRate, currency)} before the cap, then ${money(over)} earns ${earnText(catalog, cap.cap.then_rate, currency)}: ${num(best.rate)} per dollar overall.`);
     }
     if (valuation.pooledFrom !== null) {
         const partners = card.pools_into?.when_wallet_has ?? [];
@@ -147,7 +118,7 @@ function warningsFor(catalog, entry, purchase) {
     const { best, nominal } = evaluation;
     const warnings = [];
     const capLabel = (e) => e.cap
-        ? `${dollars(e.cap.cap.amount)} ${PERIOD_WORDS[e.cap.cap.period] ?? ''} cap`
+        ? `${money(e.cap.cap.amount)} ${PERIOD_WORDS[e.cap.cap.period] ?? ''} cap`
         : '';
     if (best.cap && best.rule) {
         const { remaining, cap, period } = best.cap;
@@ -155,10 +126,10 @@ function warningsFor(catalog, entry, purchase) {
             warnings.push(`Add this card's anniversary (MM-DD) to your wallet so its ${capLabel(best)} can be tracked.`);
         }
         else if (purchase.amount !== null && purchase.amount > remaining) {
-            warnings.push(`This purchase crosses the ${capLabel(best)} on "${best.rule.id}": only ${dollars(remaining)} is left for ${period}.`);
+            warnings.push(`This purchase crosses the ${capLabel(best)} on "${best.rule.id}": only ${money(remaining)} is left for ${period}.`);
         }
         else if (remaining < cap.amount * NEAR_CAP_SHARE) {
-            warnings.push(`Only ${dollars(remaining)} left of the ${capLabel(best)} on "${best.rule.id}" for ${period}.`);
+            warnings.push(`Only ${money(remaining)} left of the ${capLabel(best)} on "${best.rule.id}" for ${period}.`);
         }
     }
     if (nominal.rule &&
@@ -258,15 +229,14 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
     if (merchant.source === 'none') {
         assumptions.push(`Treats "${merchant.input}" as an everyday purchase with no bonus category.`);
     }
+    else if (merchant.source === 'category') {
+        assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
+    }
     else if (merchant.category === 'other') {
         assumptions.push(`Assumes ${merchant.resolvedName} falls outside the usual bonus categories.`);
     }
     else {
-        const category = catalog.categories.find((c) => c.id === merchant.category);
-        const mcc = merchant.likelyMcc ??
-            (category?.mccs.length === 1 ? category.mccs[0] : undefined);
-        const code = mcc === undefined ? '' : ` (MCC ${String(mcc)})`;
-        assumptions.push(`Assumes ${merchant.resolvedName} codes as ${categoryPhrase(catalog, merchant.category)}${code}.`);
+        assumptions.push(codesAs(catalog, merchant));
     }
     if (merchant.inference) {
         assumptions.push(`Claude's reasoning: ${merchant.inference.rationale}`);
@@ -277,15 +247,9 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
     if (purchase.channel === null && merchant.channel === 'online') {
         assumptions.push('Assumes an online purchase, since you gave a web address.');
     }
-    const pointValues = new Map();
-    for (const e of entries) {
-        if (e.valuation.currency !== 'cash')
-            pointValues.set(e.valuation.currency, e.valuation.centsPerUnit);
-    }
-    if (pointValues.size > 0) {
-        const list = [...pointValues].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
-        assumptions.push(`Values points at: ${list.join(', ')}.`);
-    }
+    const values = pointValuesText(catalog, entries.map((e) => e.valuation));
+    if (values !== null)
+        assumptions.push(values);
     return assumptions;
 }
 export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(catalog, purchase.merchant, purchase.channel)) {

package/dist/engine/record.js

@@ -1,6 +1,7 @@
 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;
+import { roundCents } from "./text.js";
 // Books the spend against the cap of the highest-rate rule that matches, even
 // when that cap is already used up, so usage stays accurate across a reset.
 // Returns null when there's nothing to track: no cap, or a cardmember-year cap
@@ -49,7 +50,36 @@ export function applyBooking(wallet, booking) {
             : c),
     };
 }
-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.
+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),
+    };
+}
+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,15 +1,15 @@
 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 { evaluateCard, purchaseContext, usableAt } from "./evaluate.js";
+import { categoryResolution, findCategory, idealHolding, matchesFilters, } from "./explore.js";
+import { choicePeriod, periodKey } from "./periods.js";
 import { applyBooking, capBooking } from "./record.js";
 import { rotationGap } from "./rotation.js";
+import { roundCents } from "./text.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)
@@ -37,17 +37,10 @@ function withCurrentPicks(card, held, date) {
         ...held,
         chosen: {
             ...held.chosen,
-            period: periodKey(choicePeriod(card), date, null) ?? '',
+            period: periodKey(choicePeriod(card) ?? 'calendar_year', 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.
@@ -119,13 +112,13 @@ export function simulateWallet(catalog, wallet, lines, start) {
         };
         return {
             label: line.label,
-            spend: round(r.spend),
-            earned: round(r.earned),
+            spend: roundCents(r.spend),
+            earned: roundCents(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 rewards = roundCents(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);
@@ -146,10 +139,10 @@ export function simulateWallet(catalog, wallet, lines, start) {
             cardId: h.id,
             picks: h.chosen?.picks ?? {},
         })),
-        spend: round(lineResults.reduce((sum, l) => sum + l.spend, 0)),
+        spend: roundCents(lineResults.reduce((sum, l) => sum + l.spend, 0)),
         rewards,
         annualFees,
-        net: round(rewards - annualFees),
+        net: roundCents(rewards - annualFees),
         lines: lineResults,
         notes,
     };
@@ -293,17 +286,38 @@ export function simulateAdditions(catalog, wallet, lines, options) {
             memberships: wallet.memberships,
             valuations: wallet.valuations,
         });
-        const extraRewards = round(simulation.rewards - current.rewards);
+        const extraRewards = roundCents(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),
+            gain: roundCents(extraRewards - annualFee),
             simulation,
         });
     }
     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/text.js

@@ -0,0 +1,53 @@
+import { singleMcc } from "./evaluate.js";
+export const num = (n) => String(Number(n.toFixed(2)));
+export const pct = (n) => `${num(n)}%`;
+export const roundCents = (n) => Math.round(n * 100) / 100;
+// Whole dollars stay whole ($2,800); anything else shows cents ($0.40).
+export const money = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+export function feeText(fees) {
+    const { annualFee, firstYearFee } = fees;
+    if (annualFee === null)
+        return 'annual fee not on file';
+    if (annualFee === 0)
+        return 'no annual fee';
+    if (firstYearFee !== null && firstYearFee !== annualFee)
+        return `${money(annualFee)} annual fee (${firstYearFee === 0 ? 'waived' : money(firstYearFee)} the first year)`;
+    return `${money(annualFee)} annual fee`;
+}
+export function currencyName(catalog, id) {
+    return catalog.currencies.find((c) => c.id === id)?.name ?? id;
+}
+export function currencyLabel(catalog, id) {
+    const name = currencyName(catalog, id);
+    return /^[A-Z]{2,4}$/.test(id) ? `${name} (${id})` : name;
+}
+// Mid-sentence form: "Supermarkets" becomes "supermarkets", but "TV and
+// internet service" and "EV charging" keep their acronyms.
+export function categoryPhrase(catalog, id) {
+    const name = catalog.categories.find((c) => c.id === id)?.name ?? id;
+    return /^[A-Z]{2}/.test(name)
+        ? name
+        : name.charAt(0).toLowerCase() + name.slice(1);
+}
+export function earnText(catalog, rate, currency) {
+    return currency === 'cash'
+        ? `${num(rate)}% cash back`
+        : `${num(rate)}x ${currencyName(catalog, currency)}`;
+}
+export function codesAs(catalog, merchant) {
+    const mcc = merchant.likelyMcc ?? singleMcc(catalog, merchant.category);
+    const code = mcc === null ? '' : ` (MCC ${String(mcc)})`;
+    return `Assumes ${merchant.resolvedName} codes as ${categoryPhrase(catalog, merchant.category)}${code}.`;
+}
+// "Values points at: Membership Rewards (MR) at 1¢." for the currencies an
+// answer ranks, or null when every card shown earns cash.
+export function pointValuesText(catalog, shown) {
+    const values = new Map();
+    for (const e of shown)
+        if (e.currency !== 'cash')
+            values.set(e.currency, e.centsPerUnit);
+    if (values.size === 0)
+        return null;
+    const list = [...values].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
+    return `Values points at: ${list.join(', ')}.`;
+}

package/dist/engine/transient.js

@@ -0,0 +1,26 @@
+import { addToWallet, withMemberships, } from "./wallet-change.js";
+export const EMPTY_WALLET = {
+    valuations: {},
+    memberships: [],
+    cards: [],
+};
+// 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/valuation.js

@@ -1,4 +1,4 @@
-export function currencyValuation(catalog, wallet, currencyId) {
+function currencyValuation(catalog, wallet, currencyId) {
     const currency = catalog.currencies.find((c) => c.id === currencyId);
     if (!currency)
         throw new Error(`unknown currency '${currencyId}'`);

package/dist/engine/wallet-change.js

@@ -1,8 +1,8 @@
-import { periodKey } from "./periods.js";
+import { choicePeriod, 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) {
+function findCatalogCard(catalog, id, today) {
     const card = catalog.cards.find((c) => c.id === id);
     if (card)
         return card;
@@ -11,22 +11,16 @@ export function findCatalogCard(catalog, id, today) {
         ? `No card '${id}' in earnrate. Closest: ${list(near)}.`
         : `No card '${id}' in earnrate. Search the catalog to find its id.`;
 }
-export function isAnniversary(text) {
+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);
+function pickKey(card, today) {
+    const period = choicePeriod(card);
+    return period === null ? null : periodKey(period, today, null);
 }
 export function cardFields(card, held, input, today) {
     const problems = [];
@@ -77,7 +71,7 @@ export function cardFields(card, held, input, today) {
                 problems.push(`${choiceId} takes ${choice.pick === 1 ? '1 pick' : `1 to ${String(choice.pick)} picks`}, not ${String(picks.length)}.`);
             }
         }
-        const period = pickPeriod(card, today);
+        const period = pickKey(card, today);
         if (period === null) {
             problems.push(`${card.id} has picks on different schedules; edit the wallet by hand.`);
         }
@@ -89,21 +83,48 @@ 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) => ({
+const newHolding = (id) => ({
     id,
     cap_usage: {},
     activated: [],
 });
-export const withFields = (held, f) => ({
+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) {