earnrate 0.2.4 → 0.2.6

package/dist/engine/explore.js

@@ -1,13 +1,14 @@
-import { resolveMerchant } from "../merchants/resolve.js";
+import { categoryResolution, resolvePlace } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
-import { membershipNeeded, paidMemberships } from "./memberships.js";
+import { membershipName, membershipNeeded, paidMemberships, } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
-import { categoryPhrase, choiceName, codesAs, earnText, membershipName, money, pointValuesText, words, } from "./text.js";
+import { optionName } from "./wallet-summary.js";
+import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, earnText, listed, money, PICK_PERIODS, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
-const EPSILON = 1e-9;
+import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
     kind: 'any',
     business: false,
@@ -48,50 +49,6 @@ export function idealHolding(card, date, 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: 'category',
-        bookedVia: [],
-        inference: null,
-    };
-}
 function walletOf(held, options) {
     return {
         valuations: options.valuations,
@@ -148,17 +105,17 @@ function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
             : null,
     };
 }
-function conditionsText(catalog, r) {
+function conditionsText(catalog, card, r) {
     const conditions = [];
     if (r.pick) {
-        conditions.push(`Needs ${r.pick.options.map(words).join(' or ')} as its ${choiceName(r.pick.choice)} pick (${PICK_PERIODS[r.pick.period]}).`);
+        conditions.push(`Needs ${r.pick.options.map((o) => optionName(catalog, card, r.pick?.choice ?? '', o)).join(' or ')} as its ${choiceName(r.pick.choice)} pick (${r.pick.period === 'until_changed' ? '' : 'picked '}${PICK_PERIODS[r.pick.period]}).`);
     }
     if (r.activation !== null)
         conditions.push('Needs its bonus activated with the issuer (free).');
     if (r.membership !== null)
-        conditions.push(`Needs ${membershipName(r.membership)}.`);
+        conditions.push(`With your ${membershipName(catalog, r.membership)}.`);
     if (r.cap) {
-        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)}.`);
+        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;
 }
@@ -196,7 +153,7 @@ function compareExplored(a, b) {
 export function exploreCards(catalog, query, options, resolved) {
     const merchant = resolved ??
         (query.merchant !== null
-            ? resolveMerchant(catalog, query.merchant, query.channel)
+            ? resolvePlace(catalog, query.merchant, query.channel)
             : categoryResolution(catalog, query.category ?? 'other', query.channel));
     const purchase = {
         merchant: merchant.input,
@@ -243,8 +200,8 @@ export function exploreCards(catalog, query, options, resolved) {
             picks,
             requirements,
             conditions: [
-                ...conditionsText(catalog, requirements),
-                ...membershipNeeded(card, paid),
+                ...conditionsText(catalog, card, requirements),
+                ...membershipNeeded(catalog, card, paid),
             ],
             evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
             withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
@@ -270,7 +227,7 @@ function exploreAssumptions(catalog, merchant, ranked, options) {
     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(', ')}.`);
+        : `Assumes these memberships: ${listed(options.memberships.map((m) => membershipName(catalog, m)))}.`);
     const values = pointValuesText(catalog, ranked.slice(0, 10));
     if (values !== null)
         assumptions.push(values);

package/dist/engine/memberships.js

@@ -1,30 +1,48 @@
-import { money } from "./text.js";
+import { money, words } from "./text.js";
+export function membership(catalog, id) {
+    return catalog.memberships.find((m) => m.id === id);
+}
+export function membershipName(catalog, id) {
+    return membership(catalog, id)?.name ?? words(id);
+}
+// "a Costco membership", for a sentence.
+function withArticle(name) {
+    return `${/^[aeiou]/i.test(name) ? 'an' : 'a'} ${name}`;
+}
+// Tiers of one membership: holding one, the others in its group aren't
+// missing (BofA Preferred Rewards).
+export function sameGroup(catalog, a, b) {
+    const group = membership(catalog, a)?.group;
+    return group !== undefined && group === membership(catalog, b)?.group;
+}
 // Memberships the person already pays for: the ones they've said, the ones a
 // card they hold needs, and the ones their spending shows (only members shop
 // at Costco).
 export function paidMemberships(catalog, { memberships, heldCards = [], merchantIds = [], }) {
     const paid = new Set(memberships);
     for (const card of catalog.cards) {
-        const m = card.requires_membership;
-        if (!m)
-            continue;
-        if (heldCards.includes(card.id) ||
-            m.members_shop_at.some((id) => merchantIds.includes(id)))
-            paid.add(m.id);
+        const id = card.requires_membership;
+        if (id !== undefined && heldCards.includes(card.id))
+            paid.add(id);
     }
+    for (const m of catalog.memberships)
+        if (m.members_shop_at.some((id) => merchantIds.includes(id)))
+            paid.add(m.id);
     return paid;
 }
 // What these cards' memberships add, once each, leaving out the paid ones.
-export function membershipCosts(cards, paid) {
+export function membershipCosts(catalog, cards, paid) {
     const costs = new Map();
     for (const card of cards) {
-        const m = card.requires_membership;
+        const m = card.requires_membership === undefined
+            ? undefined
+            : membership(catalog, card.requires_membership);
         if (!m || paid.has(m.id))
             continue;
         const cost = costs.get(m.id) ?? {
             id: m.id,
             name: m.name,
-            annualFee: m.annual_fee,
+            annualFee: m.annual_fee ?? 0,
             cardIds: [],
         };
         cost.cardIds.push(card.id);
@@ -32,14 +50,22 @@ export function membershipCosts(cards, paid) {
     }
     return [...costs.values()];
 }
+// "a Costco membership ($65 a year)"
+export function membershipText(catalog, id) {
+    const m = membership(catalog, id);
+    const name = withArticle(m?.name ?? words(id));
+    return m?.annual_fee === undefined
+        ? name
+        : `${name} (${money(m.annual_fee)} a year)`;
+}
 // The card's membership as a condition, unless it's paid for.
-export function membershipNeeded(card, paid) {
-    const m = card.requires_membership;
-    return m && !paid.has(m.id)
-        ? [`Needs ${m.name} (${money(m.annual_fee)} a year).`]
+export function membershipNeeded(catalog, card, paid) {
+    const id = card.requires_membership;
+    return id !== undefined && !paid.has(id)
+        ? [`Needs ${membershipText(catalog, id)}.`]
         : [];
 }
 export function membershipNote(catalog, m) {
     const names = m.cardIds.map((id) => catalog.cards.find((c) => c.id === id)?.name ?? id);
-    return `${names.join(' and ')} ${names.length === 1 ? 'needs' : 'need'} ${m.name}, ${money(m.annualFee)} a year, counted here like an annual fee. If you're already a member, add it to your memberships.`;
+    return `${names.join(' and ')} ${names.length === 1 ? 'needs' : 'need'} ${withArticle(m.name)}, ${money(m.annualFee)} a year, counted here like an annual fee. If you're already a member, add it to your memberships.`;
 }

package/dist/engine/offers.js

@@ -1,7 +1,8 @@
 import { bonusDollars } from "./bonus.js";
 import { matchesFilters } from "./explore.js";
 import { membershipCosts, paidMemberships } from "./memberships.js";
-import { roundCents } from "./text.js";
+import { inEffect } from "./periods.js";
+import { money, roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
 function ineligibleText(catalog, wallet, notWith) {
     const held = wallet.cards
@@ -13,6 +14,18 @@ function ineligibleText(catalog, wallet, notWith) {
         ? null
         : `Likely not eligible: you hold ${held.join(' and ')}, and the issuer's terms rule out its cardholders.`;
 }
+export const OFFERS_MAY_DIFFER = 'Yours may differ: issuers test and target offers, so use the one shown to you when you apply.';
+// "Up to 60,000 Chase Ultimate Rewards after $4,000 in purchases within 3
+// months": one wording for the site, the search pages and the CLI.
+export function offerTerms(o, currencyName) {
+    const amount = o.points !== null && o.points !== undefined
+        ? `${o.points.toLocaleString('en-US')} ${currencyName}`
+        : money(o.dollars ?? 0);
+    const spend = o.spend > 0
+        ? `after ${money(o.spend)} in purchases within ${String(o.months)} month${o.months === 1 ? '' : 's'}`
+        : 'with no spending required';
+    return `${o.varies ? 'Up to ' : ''}${amount} ${spend}`;
+}
 export function compareOffers(catalog, wallet, filters, today) {
     const held = new Set(wallet.cards.map((c) => c.id));
     const paid = paidMemberships(catalog, {
@@ -29,7 +42,7 @@ export function compareOffers(catalog, wallet, filters, today) {
         if (!matchesFilters(card, { ...filters, issuer: null, includeClosed: true }))
             continue;
         const offer = card.welcome_offer;
-        if (!offer || (offer.valid_to !== undefined && offer.valid_to < today)) {
+        if (!offer || !inEffect(offer, today)) {
             withoutOffer.push(card.id);
             continue;
         }
@@ -37,7 +50,7 @@ export function compareOffers(catalog, wallet, filters, today) {
         const value = bonusDollars(card, valuation.centsPerUnit, offer.points, offer.dollars) ??
             0;
         const firstYearFee = card.first_year_fee ?? card.annual_fee ?? null;
-        const membershipFee = membershipCosts([card], paid)[0]?.annualFee ?? 0;
+        const membershipFee = membershipCosts(catalog, [card], paid)[0]?.annualFee ?? 0;
         offers.push({
             cardId: card.id,
             cardName: card.name,
@@ -68,8 +81,8 @@ export function compareOffers(catalog, wallet, filters, today) {
         a.cardId.localeCompare(b.cardId));
     const notes = [
         `Compares the ${String(catalog.cards.length)} cards earnrate knows, not every card on the market.`,
-        "Each offer is the public one on the issuer's page on the date shown, checked weekly. Yours may differ: issuers test and target offers, so use the one shown to you when you apply. Issuers also limit who can get a bonus; each card's note says how.",
-        "First-year value is the bonus at your point values minus the first year's annual fee. It leaves out what the card earns on your spending and any credits or perks.",
+        `Each offer is the public one on the issuer's page on the date shown, checked weekly. ${OFFERS_MAY_DIFFER} Issuers also limit who can get a bonus; each card's note says how.`,
+        "First-year value is the bonus at your point values minus the first year's annual fee and any membership the card needs that you don't have. It leaves out what the card earns on your spending and any credits or perks.",
     ];
     return { offers, withoutOffer, notes };
 }

package/dist/engine/periods.js

@@ -38,3 +38,21 @@ export function choicePeriod(card) {
     ];
     return periods.length > 1 ? null : (periods[0] ?? 'calendar_year');
 }
+// Whether a dated rule or offer is in effect on `date`; an open end has no
+// limit on that side.
+export const inEffect = (window, date) => (window.valid_from === undefined || window.valid_from <= date) &&
+    (window.valid_to === undefined || window.valid_to >= date);
+// The last day of a period key ("2026-Q4", "2026-10", "2026").
+export 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;
+}

package/dist/engine/profiles.js

@@ -2,6 +2,14 @@ export const VALUATION_PROFILES = {
     flat: { MR: 1.0, UR: 1.0 },
     'points-heavy': { MR: 1.7, UR: 1.7 },
 };
+// "MR and UR at 1.7¢": what a profile sets, for help text.
+export function profileText(profile) {
+    const values = Object.entries(VALUATION_PROFILES[profile]);
+    const cents = [...new Set(values.map(([, v]) => v))];
+    return cents.length === 1
+        ? `${values.map(([id]) => id).join(' and ')} at ${String(cents[0])}¢`
+        : values.map(([id, v]) => `${id} at ${String(v)}¢`).join(', ');
+}
 export function isValuationProfile(name) {
     return Object.hasOwn(VALUATION_PROFILES, name);
 }

package/dist/engine/recommend.js

@@ -1,23 +1,15 @@
-import { resolveMerchant, resolveMerchantById } from "../merchants/resolve.js";
+import { findMerchant, resolveMerchant, resolveMerchantById, } from "../merchants/resolve.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, NETWORK_NAMES, num, pointValuesText, shortDate, } from "./text.js";
+import { EPSILON, isClose } from "./compare.js";
+import { CAP_ADJECTIVES, categoryPhrase, codesAs, currencyLabel, currencyName, earnText, money, NETWORK_NAMES, num, pct, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.js";
 import { cardValuation } from "./valuation.js";
-// An on-pace welcome bonus card is mentioned when it's this close to the
-// best card: within a point, and at least three quarters of its rate.
-const CLOSE_PCT = 1;
-const CLOSE_SHARE = 0.75;
-const EPSILON = 1e-9;
 export const STALE_AFTER_DAYS = 180;
+// The warning when no card works; the CLI shows it as the answer instead.
+export const noCardText = (merchant) => `None of your cards work at ${merchant}.`;
 const NEAR_CAP_SHARE = 0.2;
-const PERIOD_WORDS = {
-    month: 'monthly',
-    quarter: 'quarterly',
-    calendar_year: 'calendar-year',
-    cardmember_year: 'cardmember-year',
-};
 const displayName = (e) => e.held.checkout_label ?? e.card.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);
@@ -112,7 +104,7 @@ function reasoningFor(catalog, wallet, entry, amount) {
         lines.push(`Pools into ${currencyName(catalog, currency)} because you hold ${heldPartners.join(' and ')}.`);
     }
     if (currency !== 'cash') {
-        lines.push(`Valued at ${num(valuation.centsPerUnit)}¢ per point: ${num(entry.effectiveReturnPct)}% back.`);
+        lines.push(`Valued at ${num(valuation.centsPerUnit)}¢ per point: ${pct(entry.effectiveReturnPct)} back.`);
     }
     return lines;
 }
@@ -121,7 +113,7 @@ function warningsFor(catalog, entry, purchase) {
     const { best, nominal } = evaluation;
     const warnings = [];
     const capLabel = (e) => e.cap
-        ? `${money(e.cap.cap.amount)} ${PERIOD_WORDS[e.cap.cap.period] ?? ''} cap`
+        ? `${money(e.cap.cap.amount)} ${CAP_ADJECTIVES[e.cap.cap.period]} cap`
         : '';
     if (best.cap && best.rule) {
         const { remaining, cap, period } = best.cap;
@@ -152,7 +144,7 @@ function warningsFor(catalog, entry, purchase) {
         warnings.push(`Your chosen categories are set for ${evaluation.staleChoice}, not the current period, so chosen-category bonuses don't apply until you update them.`);
     }
     for (const rule of evaluation.needsActivation) {
-        warnings.push(`Activate this bonus with the issuer (it's free) to earn ${earnText(catalog, rule.rate, valuation.currency)} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
+        warnings.push(`Activate this bonus with the issuer (it's free)${rule.activate_by === undefined ? '' : ` by ${shortDate(rule.activate_by)}`} to earn ${earnText(catalog, rule.rate, valuation.currency)} here${rule.valid_to === undefined ? '' : ` through ${shortDate(rule.valid_to)}`}.`);
     }
     return warnings;
 }
@@ -191,7 +183,7 @@ function tieNote(entries) {
             tied.some((e) => e.evaluation.best.cap !== null)
             ? 'because its rate has no cap'
             : 'by a fixed order; either works';
-    return `${names} also ${verb} ${num(winner.effectiveReturnPct)}% here. ${displayName(winner)} wins the tie ${why}.`;
+    return `${names} also ${verb} ${pct(winner.effectiveReturnPct)} here. ${displayName(winner)} wins the tie ${why}.`;
 }
 // Finds the closest point inside a currency's value range where the winner
 // stops winning, varying one currency at a time. Returns are linear in the
@@ -286,19 +278,18 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             const twin = alts.find((e) => e.card.id !== winner.card.id &&
                 alt.effectiveReturnPct - e.effectiveReturnPct <= EPSILON);
             if (alt.card.id !== winner.card.id)
-                warnings.push(`${as}, ${displayName(alt)} wins (${num(alt.effectiveReturnPct)}%).`);
+                warnings.push(`${as}, ${displayName(alt)} wins (${pct(alt.effectiveReturnPct)}).`);
             else if (twin)
-                warnings.push(`${as}, ${displayName(twin)} earns as much (${num(twin.effectiveReturnPct)}%).`);
+                warnings.push(`${as}, ${displayName(twin)} earns as much (${pct(twin.effectiveReturnPct)}).`);
         }
     }
     if (!winner) {
-        warnings.push(`None of your cards work at ${merchant.resolvedName}.`);
+        warnings.push(noCardText(merchant.resolvedName));
         // Only where the merchant's data says what its website takes: without
         // that, every network is assumed, and a gas pump has no website.
-        const record = [
-            ...catalog.merchants.overrides,
-            ...catalog.merchants.seed,
-        ].find((m) => m.id === merchant.merchantId);
+        const record = merchant.merchantId === null
+            ? undefined
+            : findMerchant(catalog, merchant.merchantId);
         const online = merchant.channel === 'in_store' &&
             merchant.merchantId !== null &&
             record?.online?.accepts !== undefined
@@ -308,7 +299,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             ? rankEntries(catalog, wallet, { ...purchase, channel: 'online' }, online, online.category).entries[0]
             : undefined;
         if (alt)
-            warnings.push(`Ordering online instead? ${displayName(alt)} works there (${num(alt.effectiveReturnPct)}%).`);
+            warnings.push(`Ordering online instead? ${displayName(alt)} works there (${pct(alt.effectiveReturnPct)}).`);
     }
     else if (merchant.accepts === null &&
         (winner.card.network === 'amex' || winner.card.network === 'discover')) {
@@ -333,7 +324,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const alt = rankEntries(catalog, wallet, purchase, via, via.category)
             .entries[0];
         if (alt && alt.effectiveReturnPct > winner.effectiveReturnPct + EPSILON) {
-            notes.push(`If you book it as ${via.resolvedName}, ${displayName(alt)} earns ${num(alt.effectiveReturnPct)}%.`);
+            notes.push(`If you book it as ${via.resolvedName}, ${displayName(alt)} earns ${pct(alt.effectiveReturnPct)}.`);
         }
     }
     const open = bonusPick(catalog, wallet, entries, purchase.date);
@@ -348,11 +339,8 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
     const ties = !isBest && gap <= EPSILON;
     const bonus = open && (open.behind || ties) ? open : null;
     const best = winner?.effectiveReturnPct ?? 0;
-    if (open &&
-        !bonus &&
-        gap <= CLOSE_PCT &&
-        open.entry.effectiveReturnPct >= best * CLOSE_SHARE) {
-        notes.push(`${displayName(open.entry)} earns ${num(open.entry.effectiveReturnPct)}% here, ${num(gap)} ${gap === 1 ? 'point' : 'points'} less than ${num(best)}%, and would help its welcome bonus (${money(open.status.remaining ?? 0)} more by ${open.status.deadline ?? ''}). You're on pace, so this uses the higher rate.`);
+    if (open && !bonus && isClose(open.entry.effectiveReturnPct, best)) {
+        notes.push(`${displayName(open.entry)} earns ${pct(open.entry.effectiveReturnPct)} here, ${num(gap)} ${gap === 1 ? 'point' : 'points'} less than ${pct(best)}, and would help its welcome bonus (${money(open.status.remaining ?? 0)} more by ${open.status.deadline ?? ''}). You're on pace, so this uses the higher rate.`);
     }
     const chosen = bonus?.entry ?? winner;
     // A tie among the top cards doesn't matter when a welcome bonus decides.
@@ -369,7 +357,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const daysLeft = status.daysLeft ?? 0;
         const costHere = ties || top.earned === null || first.earned === null
             ? null
-            : Math.round((first.earned - top.earned) * 100) / 100;
+            : roundCents(first.earned - top.earned);
         bonusResult = {
             cardId: top.cardId,
             checkoutLabel: top.checkoutLabel,
@@ -380,17 +368,15 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             costHere,
         };
         const pace = daysLeft >= 7
-            ? ` (about ${money(Math.round(remaining / (daysLeft / 7)))} a week)`
+            ? ` (about ${wholeDollars(remaining / (daysLeft / 7))} a week)`
             : '';
-        const worth = status.value === null
-            ? ''
-            : `, worth about ${money(Math.round(status.value))}`;
+        const worth = status.value === null ? '' : `, worth about ${wholeDollars(status.value)}`;
         notes.unshift(ties
             ? `${displayName(bonus.entry)} earns as much here as any of your cards, so it's the pick: it helps its welcome bonus, ${money(remaining)} more to spend by ${deadline}${worth}.`
             : `You're behind pace on ${displayName(bonus.entry)}'s welcome bonus: ${money(remaining)} more to spend by ${deadline}${pace}${worth}.${isBest
                 ? ''
                 : costHere === null
-                    ? ` It earns ${num(top.effectiveReturnPct)}% here against ${num(first.effectiveReturnPct)}% on ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`
+                    ? ` It earns ${pct(top.effectiveReturnPct)} here against ${pct(first.effectiveReturnPct)} on ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`
                     : ` Using it here earns ${money(costHere)} less than ${displayName(entries[0] ?? bonus.entry)}, which the bonus outweighs.`}`);
     }
     let confidence = merchant.confidence;

package/dist/engine/setup.js

@@ -1,19 +1,11 @@
 import { isActivated, pickedCategories } from "./evaluate.js";
+import { membership, membershipName, sameGroup } from "./memberships.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
+import { idList, listed } from "./text.js";
 // Rules that start within this many days are worth activating now.
 const ACTIVATION_LOOKAHEAD_DAYS = 45;
-const ISSUER_NICKNAMES = {
-    amex: 'american express',
-    'bank-of-america': 'bofa boa bankofamerica',
-    'capital-one': 'capitalone',
-    citi: 'citibank',
-    usbank: 'us bank',
-    'wells-fargo': 'wf wellsfargo',
-    'td-bank': 'td',
-    column: 'bilt',
-};
-const words = (s) => s
+const searchWords = (s) => s
     .toLowerCase()
     .replace(/\+/g, ' plus ')
     .replace(/&/g, ' and ')
@@ -32,12 +24,12 @@ function editDistance(a, b) {
     }
     return row[b.length] ?? 0;
 }
-function matcher(card) {
+function matcher(catalog, card) {
     const haystack = [
-        ...words(card.id),
-        ...words(card.name),
-        ...words(card.issuer),
-        ...words(ISSUER_NICKNAMES[card.issuer] ?? ''),
+        ...searchWords(card.id),
+        ...searchWords(card.name),
+        ...searchWords(card.issuer),
+        ...(catalog.issuers.find((i) => i.id === card.issuer)?.search ?? []).flatMap(searchWords),
     ];
     const compact = haystack.join('');
     return (token) => haystack.some((w) => w.startsWith(token)) ||
@@ -57,9 +49,6 @@ export function activationRules(card, today) {
             daysBetween(today, r.valid_from) <= ACTIVATION_LOOKAHEAD_DAYS))
         .map((r) => r.id);
 }
-// Bank of America Preferred Rewards tiers: a person holds one at a time, so
-// with one saved the others aren't missing.
-const TIER = /^bofa-rewards-/;
 export function membershipsUsed(card) {
     return [
         ...new Set(card.rules.flatMap((r) => r.requires?.membership === undefined ? [] : [r.requires.membership])),
@@ -70,13 +59,13 @@ export function membershipsUsed(card) {
 export function membershipsFor(card) {
     return [
         ...membershipsUsed(card),
-        ...(card.requires_membership ? [card.requires_membership.id] : []),
+        ...(card.requires_membership ? [card.requires_membership] : []),
     ];
 }
 export function knownMemberships(catalog) {
-    return [...new Set(catalog.cards.flatMap(membershipsFor))].sort();
+    return catalog.memberships.map((m) => m.id).sort();
 }
-export function cardInfo(card, wallet, today) {
+export function cardInfo(catalog, card, wallet, today) {
     return {
         id: card.id,
         name: card.name,
@@ -95,13 +84,13 @@ export function cardInfo(card, wallet, today) {
             default: c.default ?? null,
         })),
         memberships: membershipsUsed(card),
-        requiresMembership: card.requires_membership
-            ? {
-                id: card.requires_membership.id,
-                name: card.requires_membership.name,
-                annualFee: card.requires_membership.annual_fee,
-            }
-            : null,
+        requiresMembership: card.requires_membership === undefined
+            ? null
+            : {
+                id: card.requires_membership,
+                name: membershipName(catalog, card.requires_membership),
+                annualFee: membership(catalog, card.requires_membership)?.annual_fee ?? 0,
+            },
         activation: activationRules(card, today),
         needsAnniversary: needsAnniversary(card),
     };
@@ -110,12 +99,12 @@ export function cardInfo(card, wallet, today) {
 // issuer (as a prefix, or with a typo or two in a long word). With no full
 // match, the cards matching the most words come back instead.
 export function searchCards(catalog, query, wallet, today) {
-    const tokens = words(query);
+    const tokens = searchWords(query);
     const scored = catalog.cards.map((card) => {
-        const matches = matcher(card);
+        const matches = matcher(catalog, card);
         return { card, score: tokens.filter((t) => matches(t)).length };
     });
-    const byShortestId = (a, b) => words(a.card.id).length - words(b.card.id).length ||
+    const byShortestId = (a, b) => searchWords(a.card.id).length - searchWords(b.card.id).length ||
         a.card.id.localeCompare(b.card.id);
     const full = scored.filter((s) => s.score === tokens.length);
     const best = Math.max(0, ...scored.map((s) => s.score));
@@ -129,11 +118,10 @@ export function searchCards(catalog, query, wallet, today) {
                 .sort(byShortestId)
                 .slice(0, 5);
     return {
-        cards: chosen.map((s) => cardInfo(s.card, wallet, today)),
+        cards: chosen.map((s) => cardInfo(catalog, s.card, wallet, today)),
         exact,
     };
 }
-const list = (ids) => ids.join(', ');
 // What a card in the wallet still needs before its answers are right.
 export function setupNotes(catalog, wallet, held, today) {
     const card = catalog.cards.find((c) => c.id === held.id);
@@ -147,27 +135,27 @@ export function setupNotes(catalog, wallet, held, today) {
             (staleChoice === null || choice.period === 'until_changed');
         if (current)
             continue;
-        const options = list(Object.keys(choice.options));
+        const options = idList(Object.keys(choice.options));
         notes.push({
             kind: 'pick',
             text: choice.default && picked.has(choice.id)
-                ? `${name}'s ${choice.id} pick is assumed to be ${list(choice.default)}, the default. Set it if a different one was picked (${String(choice.pick)} of: ${options}).`
+                ? `${name}'s ${choice.id} pick is assumed to be ${idList(choice.default)}, the default. Set it if a different one was picked (${String(choice.pick)} of: ${options}).`
                 : `${name} needs its ${choice.id} pick for this period (${String(choice.pick)} of: ${options}). Until then those categories earn the base rate.`,
         });
     }
-    const hasTier = wallet.memberships.some((m) => TIER.test(m));
-    const missing = membershipsUsed(card).filter((m) => !wallet.memberships.includes(m) && !(hasTier && TIER.test(m)));
+    // With one tier of a group saved, the others aren't missing.
+    const missing = membershipsUsed(card).filter((m) => !wallet.memberships.some((held) => held === m || sameGroup(catalog, held, m)));
     if (missing.length > 0) {
         notes.push({
             kind: 'membership',
-            text: `Some of ${name}'s rates need a membership: ${list(missing)}. Add any that apply to the wallet's memberships.`,
+            text: `Some of ${name}'s rates need ${listed(missing.map((m) => `${membershipName(catalog, m)} (${m})`), 'or')}; they're counted without it.`,
         });
     }
     const toActivate = activationRules(card, today).filter((id) => !isActivated(card, held, id));
     if (toActivate.length > 0) {
         notes.push({
             kind: 'activation',
-            text: `${name} has rates that apply only once activated with the issuer: ${list(toActivate)}. Mark the ones already activated.`,
+            text: `${name} has rates that apply only once activated with the issuer: ${idList(toActivate)}. Mark the ones already activated.`,
         });
     }
     if (needsAnniversary(card) && held.anniversary === undefined) {