earnrate 0.2.5 → 0.2.7

package/dist/engine/simulate.js

@@ -1,13 +1,13 @@
-import { resolveMerchant } from "../merchants/resolve.js";
+import { categoryResolution, findCategory, resolvePlace, } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext, usableAt } from "./evaluate.js";
-import { categoryResolution, findCategory, idealHolding, matchesFilters, } from "./explore.js";
+import { idealHolding, matchesFilters, } from "./explore.js";
 import { membershipCosts, membershipNote, paidMemberships, } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { applyBooking, capBooking } from "./record.js";
 import { rotationGap } from "./rotation.js";
 import { money, roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
-import { EPSILON } from "./compare.js";
+import { EPSILON, HALF_CENT } from "./compare.js";
 const MONTHS = 12;
 const SHORTLIST = 8; // best single cards considered for pairs
 const PER_LINE = 2; // plus the best cards for each spending line
@@ -16,7 +16,7 @@ export function resolveSpendLines(catalog, lines) {
         .filter((l) => l.monthly > 0)
         .map((l) => {
         const merchant = l.merchant !== null
-            ? resolveMerchant(catalog, l.merchant, null)
+            ? resolvePlace(catalog, l.merchant, null)
             : categoryResolution(catalog, l.category ?? 'other', null);
         return { label: merchant.resolvedName, monthly: l.monthly, merchant };
     });
@@ -224,7 +224,7 @@ 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 &&
+        const twin = folded.find((f) => Math.abs(f.net - pair.net) < HALF_CENT &&
             costs(f) === costs(pair) &&
             f.cards.some((c) => c.cardId === a?.cardId || c.cardId === b?.cardId));
         if (!twin) {
@@ -339,7 +339,8 @@ export function spendLineFor(catalog, what, monthly) {
     const category = findCategory(catalog, what);
     return { merchant: category === null ? what : null, category, monthly };
 }
+export const typicalSpend = (catalog) => TYPICAL_MONTHLY_SPEND.map((t) => spendLineFor(catalog, t.what, t.monthly));
 export function typicalSpendLines(catalog) {
-    return resolveSpendLines(catalog, TYPICAL_MONTHLY_SPEND.map((t) => spendLineFor(catalog, t.what, t.monthly)));
+    return resolveSpendLines(catalog, typicalSpend(catalog));
 }
 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} ${money(t.monthly)}`).join(', ')}. Give your own amounts for a closer answer.`;

package/dist/engine/text.js

@@ -2,6 +2,18 @@ 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;
+// Ids for a message: "amex-gold, citi-double-cash".
+export const idList = (ids) => ids.join(', ');
+export const capitalize = (t) => t.charAt(0).toUpperCase() + t.slice(1);
+// "usbank.com" from "https://www.usbank.com/credit-cards/...".
+export function hostname(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, '');
+    }
+    catch {
+        return url;
+    }
+}
 // An id in words: "gas-ev-charging" reads "gas ev charging".
 export const words = (id) => id.replace(/[-_.]/g, ' ');
 const dateWords = (date, options) => new Date(`${date}T12:00:00Z`).toLocaleDateString('en-US', {
@@ -47,7 +59,7 @@ export function categoryPhrase(catalog, id) {
 }
 export function earnText(catalog, rate, currency) {
     return currency === 'cash'
-        ? `${num(rate)}% cash back`
+        ? `${pct(rate)} cash back`
         : `${num(rate)}x ${currencyName(catalog, currency)}`;
 }
 export function codesAs(catalog, merchant) {

package/dist/engine/wallet-change.js

@@ -3,15 +3,15 @@ import { addMonths } from "./bonus.js";
 import { capByKey } from "./evaluate.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
+import { idList } from "./text.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. Closest: ${idList(near)}.`
         : `No card '${id}' in earnrate. Search the catalog to find its id.`;
 }
 function isAnniversary(text) {
@@ -51,7 +51,7 @@ export function cardFields(card, held, input, today) {
         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)}.`
+                    ? `'${id}' isn't a ${card.id} rule that needs activating. Those are: ${idList(needing)}.`
                     : `${card.id} has no rules that need activating.`);
             }
         }
@@ -62,14 +62,14 @@ export function cardFields(card, held, input, today) {
             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 '${choiceId}' pick. Its picks are: ${idList(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)}.`);
+                    problems.push(`'${p}' isn't a ${choiceId} option for ${card.id}. Options: ${idList(options)}.`);
                 }
             }
             if (picks.length === 0 || picks.length > choice.pick) {
@@ -101,7 +101,7 @@ export function cardFields(card, held, input, today) {
                         .map((r) => r.id),
                 ];
                 problems.push(keys.length > 0
-                    ? `${card.id} has no cap '${key}'. Its caps are: ${list(keys)}.`
+                    ? `${card.id} has no cap '${key}'. Its caps are: ${idList(keys)}.`
                     : `${card.id} has no spending caps.`);
                 continue;
             }
@@ -206,7 +206,7 @@ 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))}.`);
+        return failed(`${input.id} isn't in the wallet. Cards: ${idList(wallet.cards.map((c) => c.id))}.`);
     }
     const fields = cardFields(card, held, input, today);
     if (typeof fields === 'string')
@@ -227,10 +227,8 @@ export function updateInWallet(catalog, wallet, input, 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))}.`);
+        return failed(`${id} isn't in the wallet. Cards: ${idList(wallet.cards.map((c) => c.id))}.`);
     }
-    // Removing the last card leaves an empty wallet, which each store keeps
-    // in its own way (or refuses, for a wallet file).
     return {
         ok: true,
         wallet: { ...wallet, cards: wallet.cards.filter((c) => c.id !== id) },
@@ -242,7 +240,7 @@ 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 uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
+        return failed(`No card uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${idList(known)}.`);
     }
     return {
         ok: true,
@@ -256,7 +254,7 @@ export function withMemberships(catalog, wallet, memberships) {
 export function withValuations(catalog, wallet, changes) {
     const unknown = Object.keys(changes).filter((id) => !catalog.currencies.some((c) => c.id === id));
     if (unknown.length > 0)
-        return failed(`Unknown currency ${unknown.map((id) => `'${id}'`).join(', ')}. Currencies: ${list(catalog.currencies.map((c) => c.id))}.`);
+        return failed(`Unknown currency ${unknown.map((id) => `'${id}'`).join(', ')}. Currencies: ${idList(catalog.currencies.map((c) => c.id))}.`);
     const odd = Object.entries(changes).filter(([, cents]) => cents !== null && !(cents > 0 && cents <= MAX_CENTS));
     if (odd.length > 0)
         return failed(`A point is worth more than 0¢ and at most ${String(MAX_CENTS)}¢; check ${odd.map(([id]) => id).join(', ')}.`);

package/dist/engine/wallet-summary.js

@@ -1,68 +1,32 @@
 import { bonusStatus } from "./bonus.js";
 import { activationGroup, capUsed, isActivated, pickedCategories, } from "./evaluate.js";
-import { daysBetween } from "./periods.js";
+import { membershipName } from "./memberships.js";
+import { optionName, ruleParts, ruleWhat } from "./rule-text.js";
+import { daysBetween, inEffect, periodEnd } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { activationRules } from "./setup.js";
-import { categoryPhrase, choiceName, currencyLabel, earnText, listed, words, } from "./text.js";
+import { CAP_PERIODS, choiceName, currencyLabel, earnText, listed, shortDate, wholeDollars, words, } from "./text.js";
 import { cardValuation, currencyValuation } from "./valuation.js";
-// Travel-site bookings ("Flight through Amex Travel") read mid-sentence in
-// lower case and plural; brand names ("Airbnb through Amex Travel") keep theirs.
-const BOOKING = /^(Attraction|Car rental|Cruise|Flight|Hotel|Vacation rental)\b/;
-function merchantName(catalog, id) {
-    const all = [...catalog.merchants.overrides, ...catalog.merchants.seed];
-    const merchant = all.find((m) => m.id === id);
-    const name = merchant?.name ?? words(id);
-    return merchant?.kind === 'booking'
-        ? name.replace(BOOKING, (kind) => `${kind.toLowerCase()}s`)
-        : name;
-}
-export function optionName(catalog, card, choiceId, option) {
-    const o = card.choices.find((c) => c.id === choiceId)?.options[option];
-    if (!o)
-        return words(option);
-    const parts = [
-        ...o.categories.map((c) => categoryPhrase(catalog, c)),
-        ...o.merchants.map((m) => merchantName(catalog, m)),
-    ];
-    if (o.online)
-        parts.push('online shopping');
-    return parts.length > 0 ? listed(parts) : words(option);
-}
-// What a rule covers, as a list of phrases.
-function ruleParts(catalog, rule) {
-    if (rule.match.choice !== undefined)
-        return [`your ${choiceName(rule.match.choice)} picks`];
-    const parts = [
-        ...(rule.match.categories ?? []).map((c) => categoryPhrase(catalog, c)),
-        ...(rule.match.merchants ?? []).map((m) => merchantName(catalog, m)),
-    ];
-    return parts.length > 0 ? parts : [words(rule.id)];
-}
-function ruleWhat(catalog, rule) {
-    return listed(ruleParts(catalog, rule));
-}
-function periodEnd(period) {
-    const quarter = /^(\d{4})-Q([1-4])$/.exec(period);
-    if (quarter) {
-        const end = ['03-31', '06-30', '09-30', '12-31'][Number(quarter[2]) - 1];
-        return `${quarter[1] ?? ''}-${end ?? ''}`;
-    }
-    const month = /^(\d{4})-(\d{2})$/.exec(period);
-    if (month) {
-        const last = new Date(Date.UTC(Number(month[1]), Number(month[2]), 0));
-        return last.toISOString().slice(0, 10);
-    }
-    return /^\d{4}$/.test(period) ? `${period}-12-31` : null;
-}
-const applies = (rule, today) => (rule.valid_from === undefined || rule.valid_from <= today) &&
-    (rule.valid_to === undefined || rule.valid_to >= today);
 const matchKeys = (rule) => rule.match.choice !== undefined
     ? []
     : [
         ...(rule.match.categories ?? []).map((c) => `category:${c}`),
         ...(rule.match.merchants ?? []).map((m) => `merchant:${m}`),
     ];
+// "first $1,500 a quarter, combined": how much of a rate's spending earns it.
+function capLimit(card, shown, rule) {
+    if (rule.cap === undefined)
+        return '';
+    const cap = typeof rule.cap === 'string'
+        ? card.caps.find((c) => c.id === rule.cap)
+        : rule.cap;
+    if (!cap)
+        return '';
+    const shared = typeof rule.cap === 'string' &&
+        shown.filter((r) => r.cap === rule.cap).length > 1;
+    return `first ${wholeDollars(cap.amount)} ${CAP_PERIODS[cap.period]}${shared ? ', combined' : ''}`;
+}
 // Every bonus rate the cardholder gets now, best first, so none reads as the
 // base rate. Rates behind a membership the wallet lacks are left out, and so
 // is a lower tier that an uncapped, always-on higher rate fully covers (Prime
@@ -70,7 +34,7 @@ const matchKeys = (rule) => rule.match.choice !== undefined
 // a line.
 function headlineRates(catalog, wallet, card, held, currency, today) {
     const shown = card.rules
-        .filter((r) => applies(r, today) &&
+        .filter((r) => inEffect(r, today) &&
         r.rate > card.base_rate &&
         (r.requires?.membership === undefined ||
             wallet.memberships.includes(r.requires.membership)))
@@ -85,9 +49,22 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
             .flatMap(matchKeys);
         if (keys.length > 0 && keys.every((k) => higher.includes(k)))
             continue;
+        // A membership tier's higher rate on the same purchases replaces the
+        // card's own (BofA Rewards tiers), cap or not.
+        const replaced = shown.some((h) => h !== r &&
+            h.rate > r.rate &&
+            h.requires?.membership !== undefined &&
+            r.requires?.membership === undefined &&
+            JSON.stringify(h.match) === JSON.stringify(r.match) &&
+            JSON.stringify(h.exclude) === JSON.stringify(r.exclude));
+        if (replaced)
+            continue;
         const pending = r.requires?.activation && !isActivated(card, held, r.id);
-        const head = `${earnText(catalog, r.rate, currency)} on`;
-        const key = pending ? `${head}|activate` : head;
+        const key = [
+            `${earnText(catalog, r.rate, currency)} on`,
+            capLimit(card, shown, r),
+            pending ? ', once activated' : '',
+        ].join('|');
         const whats = lines.get(key) ?? [];
         for (const part of ruleParts(catalog, r))
             if (!whats.includes(part))
@@ -95,11 +72,19 @@ function headlineRates(catalog, wallet, card, held, currency, today) {
         lines.set(key, whats);
     }
     return [
-        ...[...lines].map(([key, whats]) => `${key.replace('|activate', '')} ${listed(whats)}${key.endsWith('|activate') ? ' (once activated)' : ''}`),
-        `${earnText(catalog, card.base_rate, currency)} on everything else`,
+        ...[...lines].map(([key, whats]) => {
+            const [head = '', limit = '', activate = ''] = key.split('|');
+            const after = `${limit}${activate}`;
+            return `${head} ${listed(whats)}${after === '' ? '' : ` (${after.replace(/^, /, '')})`}`;
+        }),
+        ...(shown.some((r) => r.match.any && r.rate > card.base_rate)
+            ? []
+            : [`${earnText(catalog, card.base_rate, currency)} on everything else`]),
     ];
 }
-function toActivate(catalog, card, held, today) {
+// Bonuses current or starting soon that the card hasn't activated, one per
+// activation group (one activation covers a quarter's categories).
+export function activationsDue(catalog, card, held, today) {
     const seen = new Set();
     const out = [];
     for (const id of activationRules(card, today)) {
@@ -110,13 +95,25 @@ function toActivate(catalog, card, held, today) {
             seen.add(g);
         const rules = card.rules.filter((r) => group.includes(r.id));
         const first = rules[0];
-        const when = first?.valid_from !== undefined && first.valid_to !== undefined
-            ? ` (${first.valid_from} to ${first.valid_to})`
-            : '';
-        out.push(`${rules.map((r) => ruleWhat(catalog, r)).join(', ')}${when}`);
+        out.push({
+            what: rules.map((r) => ruleWhat(catalog, r)).join(', '),
+            from: first?.valid_from ?? null,
+            to: first?.valid_to ?? null,
+            activateBy: first?.activate_by ?? null,
+        });
     }
     return out;
 }
+function toActivate(catalog, card, held, today) {
+    return activationsDue(catalog, card, held, today).map((a) => {
+        const deadline = a.activateBy === null ? '' : `activate by ${shortDate(a.activateBy)}`;
+        const dates = a.from !== null && a.to !== null
+            ? `${shortDate(a.from)} to ${shortDate(a.to)}`
+            : '';
+        const when = [dates, deadline].filter((x) => x !== '').join(', ');
+        return `${a.what}${when === '' ? '' : ` (${when})`}`;
+    });
+}
 function capSummaries(catalog, card, held, today) {
     const caps = new Map();
     for (const shared of card.caps)
@@ -204,7 +201,16 @@ export function walletSummary(catalog, wallet, today) {
             anniversary: held.anniversary ?? null,
         });
     }
-    const pointValues = Object.keys(wallet.valuations)
+    return {
+        memberships: wallet.memberships,
+        membershipNames: wallet.memberships.map((m) => membershipName(catalog, m)),
+        pointValues: pointValues(catalog, wallet),
+        started: null,
+        cards,
+    };
+}
+function pointValues(catalog, wallet) {
+    return Object.keys(wallet.valuations)
         .filter((id) => catalog.currencies.some((c) => c.id === id))
         .map((id) => ({
         currency: id,
@@ -212,5 +218,14 @@ export function walletSummary(catalog, wallet, today) {
         centsPerUnit: currencyValuation(catalog, wallet, id).centsPerUnit,
         redemption: redemptionOf(catalog, id, wallet.valuations[id]),
     }));
-    return { memberships: wallet.memberships, pointValues, started: null, cards };
+}
+// The memberships and point values a wallet holds besides its cards, in
+// words: what replacing or deleting it would lose.
+export function savedSettingsText(catalog, wallet) {
+    return [
+        ...wallet.memberships.map((m) => membershipName(catalog, m)),
+        ...pointValues(catalog, wallet).map((v) => v.redemption === null
+            ? `${v.name} at ${String(v.centsPerUnit)}¢`
+            : `${v.name} redeemed ${v.redemption}`),
+    ];
 }

package/dist/format/card-text.js

@@ -1,24 +1,10 @@
 import { earnText } from "../engine/text.js";
 // Card names, fees and requirements as earnrate.dev and its static search
 // pages show them. Node-free: the site bundles it.
-const ISSUERS = {
-    amex: 'American Express',
-    'bank-of-america': 'Bank of America',
-    'capital-one': 'Capital One',
-    chase: 'Chase',
-    citi: 'Citi',
-    column: 'Bilt',
-    sofi: 'SoFi',
-    'td-bank': 'TD Bank',
-    usbank: 'U.S. Bank',
-    'wells-fargo': 'Wells Fargo',
-};
-export { CAP_PERIODS, PICK_PERIODS, words } from "../engine/text.js";
 import { membershipName, membershipText } from "../engine/memberships.js";
 import { CAP_PERIODS, PICK_PERIODS, wholeDollars, words, } from "../engine/text.js";
-// Whole dollars, for fees and caps.
-export const usd = wholeDollars;
-export const issuerName = (id) => ISSUERS[id] ?? id;
+// An issuer's name as people know it, from data/issuers.yaml.
+export const issuerName = (catalog, id) => catalog.issuers.find((i) => i.id === id)?.name ?? id;
 export function cardText(catalog) {
     const cards = new Map(catalog.cards.map((c) => [c.id, c]));
     function shortName(id) {
@@ -40,8 +26,8 @@ export function cardText(catalog) {
             return `No annual fee${needs}`;
         const first = card?.first_year_fee;
         if (first !== undefined && first !== fee)
-            return `${usd(fee)} a year (${first === 0 ? 'waived' : usd(first)} the first year)${needs}`;
-        return `${usd(fee)} a year${needs}`;
+            return `${wholeDollars(fee)} a year (${first === 0 ? 'waived' : wholeDollars(first)} the first year)${needs}`;
+        return `${wholeDollars(fee)} a year${needs}`;
     }
     // `until` is the last day a time-limited rate applies, already formatted.
     function requirementLines(cardId, r, until = null) {
@@ -49,13 +35,13 @@ export function cardText(catalog) {
         if (r.pick)
             lines.push(`Pick ${r.pick.options.map(words).join(' or ')} as a bonus category (${PICK_PERIODS[r.pick.period]})`);
         if (r.activation !== null)
-            lines.push(`Activate the bonus with ${issuerName(cards.get(cardId)?.issuer ?? '')} (free)`);
+            lines.push(`Activate the bonus with ${issuerName(catalog, cards.get(cardId)?.issuer ?? '')} (free)`);
         if (r.membership !== null)
             lines.push(`With ${membershipName(catalog, r.membership)}`);
         if (until !== null)
             lines.push(`This rate runs through ${until}`);
         if (r.cap)
-            lines.push(`Up to ${usd(r.cap.amount)} of spending ${CAP_PERIODS[r.cap.period]}, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}`);
+            lines.push(`Up to ${wholeDollars(r.cap.amount)} of spending ${CAP_PERIODS[r.cap.period]}, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}`);
         return lines;
     }
     const memberName = (id) => membershipName(catalog, id);
@@ -65,5 +51,6 @@ export function cardText(catalog) {
         feeLabel,
         requirementLines,
         membershipName: memberName,
+        issuerName: (id) => issuerName(catalog, id),
     };
 }

package/dist/format/explore.js

@@ -1,5 +1,5 @@
 import { membershipName, membershipNote, } from "../engine/memberships.js";
-import { choiceName, feeText, money, pct, wholeDollars, words, } from "../engine/text.js";
+import { choiceName, feeText, dollarsAndCents, pct, wholeDollars, words, } from "../engine/text.js";
 const membershipFees = (memberships) => memberships
     .map((m) => ` + ${wholeDollars(m.annualFee)} for ${m.name}`)
     .join('');
@@ -17,7 +17,7 @@ export function formatExploration(r, catalog, all) {
     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 ? '' : `  ${money(e.earned)}`;
+        const earned = e.earned === null ? '' : `  ${dollarsAndCents(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}`);

package/dist/format/offers.js

@@ -1,5 +1,5 @@
 import { offerTerms } from "../engine/offers.js";
-import { feeText, money, shortDate, wholeDollars } from "../engine/text.js";
+import { capitalize, feeText, money, shortDate, wholeDollars, } from "../engine/text.js";
 const TOP = 10;
 export function formatOffers(c, currencyName, all) {
     if (c.offers.length === 0) {
@@ -11,7 +11,7 @@ export function formatOffers(c, currencyName, all) {
     shown.forEach((o, i) => {
         const weeks = (o.months * 52) / 12;
         const pace = o.spend > 0 ? ` (about ${wholeDollars(o.spend / weeks)} a week)` : '';
-        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${wholeDollars(o.firstYearValue)} the first year`, `    ${offerTerms(o, currencyName(o.currency))}${pace}. ${feeText(o)[0]?.toUpperCase() ?? ''}${feeText(o).slice(1)}.${o.membershipFee > 0 ? ` Needs a ${money(o.membershipFee)} membership, counted in the first year.` : ''}${o.held ? ' In your wallet.' : ''}`);
+        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${wholeDollars(o.firstYearValue)} the first year`, `    ${offerTerms(o, currencyName(o.currency))}${pace}. ${capitalize(feeText(o))}.${o.membershipFee > 0 ? ` Needs a ${money(o.membershipFee)} membership, counted in the first year.` : ''}${o.held ? ' In your wallet.' : ''}`);
         lines.push(`    ${o.validTo ? `Offer ends ${shortDate(o.validTo)}. ` : ''}Public offer as of ${shortDate(o.lastVerified)}; yours may differ.`);
         if (o.ineligible)
             lines.push(`    ${o.ineligible}`);

package/dist/format/recommendation.js

@@ -1,4 +1,4 @@
-import { dollarsAndCents, money, pct } from "../engine/text.js";
+import { capitalize, dollarsAndCents, money, pct } from "../engine/text.js";
 import { noCardText } from "../engine/recommend.js";
 export const plain = (_format, text) => text;
 const TOP = 3;
@@ -55,7 +55,7 @@ export function formatRecommendation(rec, purchase, { all = false, style = plain
         const earned = top.earned === null ? '' : `, about ${dollarsAndCents(top.earned)}`;
         const confidence = rec.decision.confidence;
         const why = rec.bonus ? ' for its welcome bonus' : '';
-        lines.push(`${style('bold', `Use ${label(top)}${why}: ${pct(top.effectiveReturnPct)} back${earned}.`)} ${confidence[0]?.toUpperCase() ?? ''}${confidence.slice(1)} confidence.`);
+        lines.push(`${style('bold', `Use ${label(top)}${why}: ${pct(top.effectiveReturnPct)} back${earned}.`)} ${capitalize(confidence)} confidence.`);
         if (rec.bonus && rec.notes[0])
             lines.push(rec.notes[0]);
     }

package/dist/format/wallet.js

@@ -1,4 +1,10 @@
 import { money, NETWORK_NAMES, shortDate } from "../engine/text.js";
+// "To do now", above the card details; nothing when all's done.
+export function formatChecklist(items) {
+    return items.length === 0
+        ? ''
+        : `To do now:\n${items.map((i) => `- ${i.text}`).join('\n')}\n\n`;
+}
 export function formatWalletSummary(summary) {
     const cards = summary.cards.map((c) => {
         const label = c.checkoutLabel
@@ -40,7 +46,7 @@ export function formatWalletSummary(summary) {
         return lines.join('\n');
     });
     const memberships = summary.memberships.length > 0
-        ? `Memberships: ${summary.memberships.join(', ')}.`
+        ? `Memberships: ${summary.memberships.map((id, i) => `${summary.membershipNames[i] ?? id} (${id})`).join(', ')}.`
         : 'Memberships: none saved.';
     const values = summary.pointValues.length > 0
         ? `Point values in the wallet: ${summary.pointValues.map((v) => `${v.name} at ${String(v.centsPerUnit)}¢${v.redemption === null ? '' : ` (redeemed ${v.redemption})`}`).join(', ')}. Others use earnrate's defaults.`

package/dist/import/analyze.js

@@ -1,4 +1,5 @@
 import { bonusStatus, countsTowardBonus } from "../engine/bonus.js";
+import { HALF_CENT } from "../engine/compare.js";
 import { capByKey, categoryMatches } from "../engine/evaluate.js";
 import { periodKey } from "../engine/periods.js";
 import { recommend } from "../engine/recommend.js";
@@ -155,7 +156,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
         if (topBooking)
             simulated = applyBooking(simulated, topBooking);
         const gain = (top.earned ?? 0) - (used.earned ?? 0);
-        if (top.cardId !== cardId && gain > 0.005) {
+        if (top.cardId !== cardId && gain > HALF_CENT) {
             const key = `${name}|${cardId}|${top.cardId}`;
             const miss = missed.get(key) ?? {
                 merchant: name,

package/dist/mcp/context.js

@@ -1,7 +1,8 @@
 import { walletProblems } from "../data/integrity.js";
 import { EMPTY_WALLET, walletFromCards } from "../engine/transient.js";
+import { capitalize } from "../engine/text.js";
 import { formatNotes } from "../format/cards.js";
-import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
+import { resolvePlace, withCallerCategory } from "../merchants/resolve.js";
 import { defined } from "./inputs.js";
 export const fail = (text) => ({
     content: [{ type: 'text', text }],
@@ -15,9 +16,22 @@ export function makeContext(deps) {
     const theWallet = deps.savedWallets === 'file'
         ? `the wallet at ${deps.store.where}`
         : 'the saved wallet';
+    // Which wallet this server keeps, for replies and tool descriptions. The
+    // local extension and the hosted connector can both be connected at once,
+    // each with its own wallet, and their tools are otherwise identical.
+    const walletName = deps.savedWallets === 'file'
+        ? `the wallet file on this computer (${deps.store.where})`
+        : 'your hosted earnrate wallet';
+    const walletUse = deps.savedWallets === 'file'
+        ? "It uses the wallet file on this computer, not the hosted earnrate connector's wallet."
+        : "It uses the user's hosted earnrate wallet, not a wallet file on their computer.";
+    const startHint = 'Answers cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.';
+    const noCards = deps.savedWallets === 'file'
+        ? `The wallet at ${deps.store.where} has no cards yet. ${startHint}`
+        : `The user's saved wallet has no cards yet. ${startHint}`;
     const noWallet = deps.savedWallets === 'file'
         ? `There's no saved wallet yet (${deps.store.where}). Answers don't need one: they cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.`
-        : "The user's saved wallet has no cards yet. Answers cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.";
+        : noCards;
     // Read on every call, so edits to the wallet apply without a restart.
     async function wallet() {
         let loaded;
@@ -32,25 +46,29 @@ export function makeContext(deps) {
         }
         const problems = walletProblems(loaded, catalog);
         return problems.length > 0
-            ? `${theWallet[0]?.toUpperCase() ?? ''}${theWallet.slice(1)} has problems:\n${problems.map((p) => `- ${p}`).join('\n')}`
+            ? `${capitalize(theWallet)} has problems:\n${problems.map((p) => `- ${p}`).join('\n')}`
             : loaded;
     }
-    // No saved wallet is the normal state, not a failure: it reads as an
-    // empty one, with a note on how to start one.
+    // No saved wallet, or one with no cards, is the normal state, not a
+    // failure: it reads as an empty one, with a note on how to add cards.
     async function readableWallet() {
         const w = await wallet();
         if (typeof w !== 'string')
-            return { wallet: w, start: null };
+            return { wallet: w, start: w.cards.length === 0 ? noCards : null };
         return w === noWallet ? { wallet: EMPTY_WALLET, start: w } : w;
     }
     // The caller's category is free and comes before the paid Claude fallback;
     // neither ever overrides a merchant earnrate already knows.
     async function resolve(merchant, channel, category) {
-        const known = resolveMerchant(catalog, merchant, channel);
-        if (known.source !== 'none' || category !== null || !deps.llm) {
-            return { merchant: withCallerCategory(known, category), notices: [] };
-        }
-        return deps.llm.resolve(catalog, merchant, channel);
+        const known = resolvePlace(catalog, merchant, channel);
+        const resolved = known.source !== 'none' || category !== null || !deps.llm
+            ? { merchant: withCallerCategory(known, category), notices: [] }
+            : await deps.llm.resolve(catalog, merchant, channel);
+        const source = resolved.merchant.source;
+        if (deps.missed &&
+            (source === 'none' || source === 'caller' || source === 'llm'))
+            await deps.missed.note(merchant, source === 'none' ? null : resolved.merchant.category, deps.today());
+        return resolved;
     }
     // Cards named in the conversation come first, then the saved wallet; with
     // neither (null), answers cover every card earnrate knows.
@@ -101,8 +119,8 @@ export function makeContext(deps) {
         const text = [
             message,
             output.cardIds.length > 0
-                ? `Wallet: ${output.cardIds.join(', ')}.`
-                : 'The wallet has no cards now; answers cover every card.',
+                ? `Saved in ${walletName}, which has ${String(output.cardIds.length)} ${output.cardIds.length === 1 ? 'card' : 'cards'}.`
+                : `Saved in ${walletName}, which has no cards now; answers cover every card.`,
             ...(notes ? [formatNotes(result.notes)] : []),
         ].join('\n');
         return {
@@ -111,7 +129,14 @@ export function makeContext(deps) {
         };
     }
     const cardName = (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+    // The first line of an answer from the user's own cards: which ones.
+    const fromCards = (named) => named !== undefined && named.length > 0
+        ? 'For the cards named in this conversation.\n'
+        : `From ${walletName}.\n`;
     return {
+        walletName,
+        fromCards,
+        walletUse,
         wallet,
         readableWallet,
         resolve,

package/dist/mcp/inputs.js

@@ -6,7 +6,7 @@ import { IsoDate } from "../schema/common.js";
 export const Merchant = z
     .string()
     .min(1)
-    .describe('Merchant name or web address as the user would say it or see it, e.g. "Whole Foods" or "delta.com".');
+    .describe('Merchant name or web address as the user would say it or see it, e.g. "Whole Foods" or "delta.com", or a kind of place, e.g. "restaurants" or "gas station".');
 export const ChannelInput = z
     .enum(['online', 'in_store'])
     .optional()

package/dist/mcp/schemas.js

@@ -78,6 +78,7 @@ const RecommendationSchema = z.object({
 });
 export const WalletSummarySchema = z.object({
     memberships: z.array(z.string()),
+    membershipNames: z.array(z.string()),
     pointValues: z.array(z.object({
         currency: z.string(),
         name: z.string(),
@@ -85,6 +86,14 @@ export const WalletSummarySchema = z.object({
         redemption: z.string().nullable(),
     })),
     started: z.string().nullable(),
+    checklist: z
+        .array(z.object({
+        kind: z.enum(['activate', 'pick', 'cap', 'bonus', 'rotation']),
+        cardId: z.string(),
+        text: z.string(),
+        due: z.string().nullable(),
+    }))
+        .optional(),
     cards: z.array(z.object({
         cardId: z.string(),
         cardName: z.string(),