earnrate 0.2.3 → 0.2.5

package/dist/data/integrity.js

@@ -1,3 +1,4 @@
+import { WALLET_VERSION } from "../schema/wallet.js";
 function duplicates(ids) {
     const seen = new Set();
     const dupes = new Set();
@@ -56,6 +57,22 @@ function cardProblems(card, catalog, merchantIds) {
     if (!currencies.has(card.currency)) {
         problems.push(`${where}: unknown currency '${card.currency}'`);
     }
+    for (const id of card.welcome_offer?.not_with ?? [])
+        if (!cardIds.has(id))
+            problems.push(`${where} welcome_offer.not_with: unknown card '${id}'`);
+    const memberships = new Set(catalog.memberships.map((m) => m.id));
+    for (const id of [
+        ...(card.requires_membership === undefined
+            ? []
+            : [card.requires_membership]),
+        ...card.rules.flatMap((r) => r.requires?.membership ?? []),
+    ])
+        if (!memberships.has(id))
+            problems.push(`${where}: unknown membership '${id}' (data/memberships.yaml)`);
+    if (card.requires_membership !== undefined &&
+        catalog.memberships.find((m) => m.id === card.requires_membership)
+            ?.annual_fee === undefined)
+        problems.push(`${where}: requires_membership '${card.requires_membership}' has no annual_fee`);
     if (card.pools_into) {
         if (!currencies.has(card.pools_into.currency)) {
             problems.push(`${where} pools_into: unknown currency '${card.pools_into.currency}'`);
@@ -79,6 +96,8 @@ function cardProblems(card, catalog, merchantIds) {
         ...(card.annual_fee !== undefined ? ['annual_fee'] : []),
         ...(card.first_year_fee !== undefined ? ['first_year_fee'] : []),
         ...(card.welcome_offer ? ['welcome_offer'] : []),
+        ...(card.welcome_offer?.not_with ? ['not_with'] : []),
+        ...(card.requires_membership ? ['requires_membership'] : []),
         ...card.rules.map((r) => r.id),
     ]);
     const sourcePages = new Set(card.source_urls.map((u) => u.split('#')[0]));
@@ -159,6 +178,7 @@ export function catalogProblems(catalog) {
         ['category', catalog.categories.map((c) => c.id)],
         ['currency', catalog.currencies.map((c) => c.id)],
         ['card', catalog.cards.map((c) => c.id)],
+        ['membership', catalog.memberships.map((m) => m.id)],
     ]) {
         for (const id of duplicates(ids))
             problems.push(`duplicate ${kind} id '${id}'`);
@@ -179,6 +199,10 @@ export function catalogProblems(catalog) {
                 problems.push(`merchant ${m.id}: booked_via '${via}' is not a merchant`);
         }
     }
+    for (const m of catalog.memberships)
+        for (const id of m.members_shop_at)
+            if (!merchantIds.has(id))
+                problems.push(`membership ${m.id}: members_shop_at '${id}' is not a merchant`);
     for (const card of catalog.cards) {
         problems.push(...cardProblems(card, catalog, merchantIds));
     }
@@ -188,6 +212,8 @@ export function walletProblems(wallet, catalog) {
     const problems = [];
     const cards = new Map(catalog.cards.map((c) => [c.id, c]));
     const currencies = new Map(catalog.currencies.map((c) => [c.id, c]));
+    if ((wallet.version ?? 1) > WALLET_VERSION)
+        problems.push(`wallet: saved by a newer earnrate (format ${String(wallet.version)}); update earnrate to read it`);
     for (const id of duplicates(wallet.cards.map((c) => c.id))) {
         problems.push(`wallet: card '${id}' is listed twice`);
     }

package/dist/data/load.js

@@ -8,6 +8,7 @@ import { CONFIG_DIR, WALLET_ENV_VAR } from "../brand.js";
 import { CardSchema } from "../schema/card.js";
 import { CategoriesFileSchema } from "../schema/category.js";
 import { CurrenciesFileSchema } from "../schema/currency.js";
+import { MembershipsFileSchema } from "../schema/membership.js";
 import { MerchantsFileSchema } from "../schema/merchant.js";
 import { WalletSchema } from "../schema/wallet.js";
 export const DATA_DIR = fileURLToPath(new URL('../../data/', import.meta.url));
@@ -30,14 +31,21 @@ async function loadCards(dir) {
     }));
 }
 export async function loadCatalog(dir = DATA_DIR) {
-    const [categories, currencies, cards, seed, overrides] = await Promise.all([
+    const [categories, currencies, memberships, cards, seed, overrides] = await Promise.all([
         readYaml(path.join(dir, 'categories.yaml'), CategoriesFileSchema),
         readYaml(path.join(dir, 'currencies.yaml'), CurrenciesFileSchema),
+        readYaml(path.join(dir, 'memberships.yaml'), MembershipsFileSchema),
         loadCards(path.join(dir, 'cards')),
         readYaml(path.join(dir, 'merchants', 'seed.yaml'), MerchantsFileSchema),
         readYaml(path.join(dir, 'merchants', 'overrides.yaml'), MerchantsFileSchema),
     ]);
-    return { categories, currencies, cards, merchants: { seed, overrides } };
+    return {
+        categories,
+        currencies,
+        memberships,
+        cards,
+        merchants: { seed, overrides },
+    };
 }
 // MCP clients pass config values through without a shell, so "~" or
 // "${HOME}" can arrive as literal text; expand them here.

package/dist/data/store.js

@@ -1,5 +1,5 @@
 import { bookPurchase } from "../engine/record.js";
-import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withValuations, } from "../engine/wallet-change.js";
 import { WalletSchema } from "../schema/wallet.js";
 const failed = (error) => ({ ok: false, error });
 // A wallet stored as JSON text. Writes are serialized within this instance;
@@ -60,6 +60,9 @@ export class JsonWalletStore {
     setMemberships(memberships) {
         return this.change(this.needsWallet((w) => withMemberships(this.catalog, w, memberships)));
     }
+    setValuations(changes) {
+        return this.change(this.needsWallet((w) => withValuations(this.catalog, w, changes)));
+    }
     replace(wallet) {
         return this.change(() => ({ ok: true, wallet, fields: {}, notes: [] }));
     }
@@ -70,6 +73,10 @@ export class JsonWalletStore {
     disconnect() {
         return Promise.resolve();
     }
+    // The backend doesn't record when it began.
+    started() {
+        return Promise.resolve(null);
+    }
     record(purchase, merchant) {
         return this.serialized(async () => {
             const wallet = await this.load();

package/dist/data/wallet-edit.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { isMap, isSeq, parseDocument, stringify } from 'yaml';
 import { applyBonusBooking, applyBooking, } from "../engine/record.js";
-import { WalletSchema } from "../schema/wallet.js";
+import { WALLET_VERSION, WalletSchema } from "../schema/wallet.js";
 const NEW_WALLET = `# Your earnrate wallet: the cards you hold, by id. Never card numbers.
 # Format: https://github.com/cwasley/earnrate#your-wallet
 
@@ -57,6 +57,12 @@ function fieldLines(field, f, indent) {
                 `${indent}  spent: ${String(b.spent)}\n`,
                 b.spend === undefined ? '' : `${indent}  spend: ${String(b.spend)}\n`,
                 b.by === undefined ? '' : `${indent}  by: ${scalar(b.by)}\n`,
+                b.points === undefined
+                    ? ''
+                    : `${indent}  points: ${String(b.points)}\n`,
+                b.dollars === undefined
+                    ? ''
+                    : `${indent}  dollars: ${String(b.dollars)}\n`,
             ].join('');
         }
         case 'chosen': {
@@ -100,7 +106,7 @@ const column = (text, at) => at - lineStart(text, at);
 // Appends a card after the last one, matching the list's indentation.
 export function addCardText(text, entry) {
     if (text === null || text.trim() === '') {
-        return `${NEW_WALLET}cards:\n${cardLines(entry, '  ')}`;
+        return `${NEW_WALLET}version: ${String(WALLET_VERSION)}\ncards:\n${cardLines(entry, '  ')}`;
     }
     const { cards } = cardsSeq(text);
     const first = cards.items[0];
@@ -164,6 +170,81 @@ export function setMembershipsText(text, memberships) {
     const cards = root.items.find((p) => keyOf(p) === 'cards');
     return insertLines(text, lineStart(text, range(cards?.key)[0]), line);
 }
+// Point values, one currency at a time so the rest of the file, comments
+// included, stays as it was: a value is replaced in place, a new one goes
+// after the last, a removed one loses its line. An inline map is rewritten.
+export function setValuationsText(text, changes) {
+    let out = text;
+    for (const [id, cents] of Object.entries(changes))
+        out = setValuationText(out, id, cents);
+    return out;
+}
+// The start of the line at `at`, moved up past the comments right above it,
+// so a comment stays with the line it describes.
+function aboveComments(text, at) {
+    let start = lineStart(text, at);
+    while (start > 0) {
+        const previous = lineStart(text, start - 1);
+        if (!text.slice(previous, start).trimStart().startsWith('#'))
+            break;
+        start = previous;
+    }
+    return start;
+}
+function setValuationText(text, id, cents) {
+    const { doc } = cardsSeq(text);
+    const root = doc.contents;
+    if (!isMap(root))
+        throw new Error(`the wallet isn't a map; ${BY_HAND}`);
+    const pair = root.items.find((p) => keyOf(p) === 'valuations');
+    const map = pair?.value;
+    const line = cents === null ? '' : `${id}: ${String(cents)}`;
+    if (!pair || map === null || (isMap(map) && map.items.length === 0)) {
+        if (cents === null)
+            return text;
+        const block = `valuations:\n  ${line}\n`;
+        if (pair) {
+            const start = range(pair.key)[0];
+            const end = afterLine(text, range(map ?? pair.key)[1] - 1);
+            return text.slice(0, start) + block + text.slice(end);
+        }
+        const before = root.items.find((p) => keyOf(p) === 'memberships' || keyOf(p) === 'cards');
+        return insertLines(text, aboveComments(text, range(before?.key)[0]), block);
+    }
+    if (!isMap(map))
+        throw new Error(`"valuations" isn't a map; ${BY_HAND}`);
+    if (map.flow) {
+        const values = Object.entries(map.toJSON()).filter(([k]) => k !== id);
+        if (cents !== null)
+            values.push([id, cents]);
+        const entries = values.map(([k, v]) => `${k}: ${stringify(v, { flow: true }).trimEnd()}`);
+        const start = range(pair.key)[0];
+        const end = afterLine(text, range(map)[1] - 1);
+        return (text.slice(0, start) +
+            (entries.length === 0 ? '' : `valuations: { ${entries.join(', ')} }\n`) +
+            text.slice(end));
+    }
+    const own = map.items.find((p) => keyOf(p) === id);
+    if (own) {
+        if (cents === null) {
+            if (map.items.length === 1) {
+                const start = lineStart(text, range(pair.key)[0]);
+                return (text.slice(0, start) + text.slice(afterLine(text, range(map)[1] - 1)));
+            }
+            const start = lineStart(text, range(own.key)[0]);
+            return (text.slice(0, start) +
+                text.slice(afterLine(text, range(own.value)[1] - 1)));
+        }
+        const [start, end] = range(own.value);
+        return text.slice(0, start) + String(cents) + text.slice(end);
+    }
+    if (cents === null)
+        return text;
+    const first = map.items[0];
+    const last = map.items.at(-1);
+    const indent = ' '.repeat(column(text, range(first?.key)[0]));
+    return insertLines(text, afterLine(text, range(last?.value ?? last?.key)[1] - 1), `${indent}${line}\n`);
+}
 function flowUsage(booking) {
     const period = /^\d+$/.test(booking.period)
         ? `"${booking.period}"`

package/dist/engine/cheat-sheet.js

@@ -1,9 +1,14 @@
 import { resolveMerchantById } from "../merchants/resolve.js";
 import { categoryResolution, exploreCards, } from "./explore.js";
+import { bonusStatus } from "./bonus.js";
+import { EPSILON, isClose } from "./compare.js";
 import { periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { setupNotes } from "./setup.js";
-const CHEAT_SHEET_ITEMS = [
+import { feeText, listed, money, shortDate } from "./text.js";
+// The everyday kinds of purchase: the cheat sheet's rows and the site's
+// quick picks.
+export const EVERYDAY_PURCHASES = [
     { label: 'Groceries', category: 'grocery.supermarket' },
     { label: 'Dining', category: 'dining' },
     { label: 'Gas', category: 'gas' },
@@ -16,7 +21,8 @@ const CHEAT_SHEET_ITEMS = [
 ];
 // The best card in the wallet for each everyday kind of purchase on `date`,
 // with caps, picks and activations as the wallet has them.
-export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
+export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
+    const ranked = [];
     const rows = items.map((item) => {
         const merchant = 'merchant' in item
             ? resolveMerchantById(catalog, item.merchant, null)
@@ -30,7 +36,10 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
             date,
             country: 'US',
         }, merchant);
-        const top = rec.ranked.find((r) => r.cardId === rec.decision?.cardId);
+        // The card that earns the most, even when a welcome bonus would take the
+        // pick for one purchase: the sheet is for the whole quarter.
+        const top = rec.decision ? rec.ranked[0] : undefined;
+        ranked.push({ label: item.label, cards: rec.ranked });
         return {
             label: item.label,
             cardId: top?.cardId ?? null,
@@ -40,8 +49,44 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
             note: top?.warnings[0] ?? null,
         };
     });
+    const bonuses = wallet.cards.flatMap((held) => {
+        const status = bonusStatus(catalog, wallet, held, date);
+        if (status?.state !== 'open')
+            return [];
+        const name = held.checkout_label ??
+            catalog.cards.find((c) => c.id === held.id)?.name ??
+            held.id;
+        // Rows where the bonus card matches the row's card, or is close to it
+        // (as single answers mention it).
+        const matches = [];
+        const near = [];
+        for (const { label, cards } of ranked) {
+            const best = cards[0]?.effectiveReturnPct;
+            const own = cards.find((c) => c.cardId === held.id)?.effectiveReturnPct;
+            if (best === undefined || own === undefined)
+                continue;
+            if (best - own < EPSILON)
+                matches.push(label.toLowerCase());
+            else if (isClose(own, best))
+                near.push(label.toLowerCase());
+        }
+        const where = [
+            ...(matches.length > 0
+                ? [`matches the listed card on ${listed(matches)}`]
+                : []),
+            ...(near.length > 0 ? [`comes within a point on ${listed(near)}`] : []),
+        ];
+        return [
+            `Working on ${name}'s welcome bonus: ${money(status.remaining ?? 0)} more by ${shortDate(status.deadline ?? date)}. ${where.length > 0
+                ? `It ${where.join(' and ')}, so those are the places to use it.`
+                : 'It trails the listed cards everywhere, so use it on everyday spending only as needed to reach the bonus.'}`,
+        ];
+    });
     const notes = [
-        ...new Set(wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text))),
+        ...new Set([
+            ...bonuses,
+            ...wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text)),
+        ]),
     ];
     const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
     return {
@@ -55,14 +100,12 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
 // The best card earnrate knows for each everyday kind of purchase, for
 // someone who hasn't named any cards. Each row's note says what the card
 // costs or needs.
-export function catalogCheatSheet(catalog, date, options, items = CHEAT_SHEET_ITEMS) {
+const capitalized = (t) => t.charAt(0).toUpperCase() + t.slice(1);
+export function catalogCheatSheet(catalog, date, options, items = EVERYDAY_PURCHASES) {
     const rows = items.map((item) => {
         const top = exploreCards(catalog, 'merchant' in item
             ? {
-                merchant: catalog.merchants.seed.find((m) => m.id === item.merchant)
-                    ?.name ??
-                    catalog.merchants.overrides.find((m) => m.id === item.merchant)
-                        ?.name ??
+                merchant: resolveMerchantById(catalog, item.merchant, null)?.resolvedName ??
                     item.label,
                 category: null,
                 amount: null,
@@ -76,11 +119,7 @@ export function catalogCheatSheet(catalog, date, options, items = CHEAT_SHEET_IT
                 channel: null,
                 date,
             }, options).ranked[0];
-        const fee = top?.annualFee === null || top?.annualFee === undefined
-            ? null
-            : top.annualFee === 0
-                ? 'No annual fee.'
-                : `$${String(top.annualFee)} annual fee.`;
+        const fee = top ? `${capitalized(feeText(top))}.` : null;
         return {
             label: item.label,
             cardId: top?.cardId ?? null,

package/dist/engine/compare.js

@@ -0,0 +1,8 @@
+// Returns closer than this are equal: floating-point noise, not a difference.
+export const EPSILON = 1e-9;
+// A card close to the best one: within a percentage point, and at least
+// three quarters of its rate. Answers and cheat sheets mention a welcome
+// bonus card when it's this close.
+export function isClose(own, best) {
+    return best - own <= 1 && own >= best * 0.75;
+}

package/dist/engine/explore.js

@@ -1,12 +1,14 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext } from "./evaluate.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, codesAs, earnText, money, pointValuesText, } from "./text.js";
+import { optionName } from "./wallet-summary.js";
+import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, earnText, 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,
@@ -47,18 +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, ' ')
@@ -147,17 +137,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.join('", "')}" as its ${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 activating with the issuer ("${r.activation}").`);
+        conditions.push('Needs its bonus activated with the issuer (free).');
     if (r.membership !== null)
-        conditions.push(`Needs ${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;
 }
@@ -206,6 +196,11 @@ export function exploreCards(catalog, query, options, resolved) {
     };
     const ranked = [];
     const excluded = [];
+    // A Costco purchase means a Costco member: no membership to point out.
+    const paid = paidMemberships(catalog, {
+        memberships: options.memberships,
+        merchantIds: [merchant.merchantId],
+    });
     for (const card of catalog.cards) {
         if (!matchesFilters(card, options.filters))
             continue;
@@ -236,7 +231,10 @@ export function exploreCards(catalog, query, options, resolved) {
             firstYearFee: card.first_year_fee ?? null,
             picks,
             requirements,
-            conditions: conditionsText(catalog, requirements),
+            conditions: [
+                ...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),
         });

package/dist/engine/memberships.js

@@ -0,0 +1,71 @@
+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.
+export 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 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(catalog, cards, paid) {
+    const costs = new Map();
+    for (const card of cards) {
+        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 ?? 0,
+            cardIds: [],
+        };
+        cost.cardIds.push(card.id);
+        costs.set(m.id, cost);
+    }
+    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(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'} ${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,9 +1,36 @@
 import { bonusDollars } from "./bonus.js";
 import { matchesFilters } from "./explore.js";
-import { roundCents } from "./text.js";
+import { membershipCosts, paidMemberships } from "./memberships.js";
+import { money, roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
+function ineligibleText(catalog, wallet, notWith) {
+    const held = wallet.cards
+        .filter((c) => notWith.includes(c.id))
+        .map((c) => c.checkout_label ??
+        catalog.cards.find((k) => k.id === c.id)?.name ??
+        c.id);
+    return held.length === 0
+        ? 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, {
+        memberships: wallet.memberships,
+        heldCards: [...held],
+    });
     const offers = [];
     const withoutOffer = [];
     for (const card of catalog.cards) {
@@ -22,6 +49,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(catalog, [card], paid)[0]?.annualFee ?? 0;
         offers.push({
             cardId: card.id,
             cardName: card.name,
@@ -39,17 +67,21 @@ export function compareOffers(catalog, wallet, filters, today) {
             annualFee: card.annual_fee ?? null,
             firstYearFee,
             bonusValue: roundCents(value),
-            firstYearValue: roundCents(value - (firstYearFee ?? 0)),
+            membershipFee,
+            ineligible: ineligibleText(catalog, wallet, offer.not_with ?? []),
+            firstYearValue: roundCents(value - (firstYearFee ?? 0) - membershipFee),
             held: held.has(card.id),
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,
         });
     }
-    offers.sort((a, b) => b.firstYearValue - a.firstYearValue || a.cardId.localeCompare(b.cardId));
+    offers.sort((a, b) => Number(a.ineligible !== null) - Number(b.ineligible !== null) ||
+        b.firstYearValue - a.firstYearValue ||
+        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/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);
 }