earnrate 0.2.17 → 0.2.18

package/dist/cli/offers.js

@@ -9,9 +9,11 @@ import { cardList, valuationProblem } from "./args.js";
 import { cardsToUse, RUNTIME_ERROR, savedSettings, USAGE_ERROR, } from "./run.js";
 const OFFERS_HELP = `Usage: ${CLI_NAME} offers [--cash | --points] [--no-fee] [--business] [options]
 
-Ranks the welcome offers on cards you don't have by first-year value: the
-bonus at your point values minus the first year's annual fee and any
-membership the card needs that you don't have.
+Which card to get next: ranks cards you don't have by their first two years
+together. That's what each adds to your cards at typical spending, plus its
+welcome bonus in year one if the minimum spend fits in the window, less each
+year's annual fee and any membership it needs. Each also shows the bonus
+alone. Issuers saved with ${CLI_NAME} skip-issuers are left out.
 
 Options:
   --cash                 Cash back cards only.
@@ -21,6 +23,8 @@ Options:
   --held                 Include cards already in your wallet.
   --cards <ids>          Cards you have, instead of your wallet, comma separated.
   --member <name>        A membership you have, in place of the saved ones.
+  --skip-issuer <id>     Leave out an issuer's cards (chase), in place of the
+                         saved list. Repeat for more.
   --valuation <profile>  flat or points-heavy, instead of your wallet's values.
   --all                  List every offer, not just the top 10.
   --json                 Print the full comparison as JSON.
@@ -39,6 +43,7 @@ export async function runOffers(argv, io) {
                 held: { type: 'boolean' },
                 cards: { type: 'string' },
                 member: { type: 'string', multiple: true },
+                'skip-issuer': { type: 'string', multiple: true },
                 valuation: { type: 'string' },
                 all: { type: 'boolean' },
                 json: { type: 'boolean' },
@@ -75,12 +80,23 @@ export async function runOffers(argv, io) {
         ? await savedSettings(io).then((saved) => ({
             valuations: saved.valuations,
             memberships: values.member ?? saved.memberships,
+            ...(saved.skipped_issuers
+                ? { skipped_issuers: saved.skipped_issuers }
+                : {}),
             cards: [],
         }))
         : found;
+    const skips = values['skip-issuer'];
+    const issuers = new Set(catalog.cards.map((c) => c.issuer));
+    const unknown = (skips ?? []).filter((i) => !issuers.has(i));
+    if (unknown.length > 0) {
+        io.stderr(`No card earnrate knows is from ${unknown.map((i) => `'${i}'`).join(', ')}. Issuers: ${[...issuers].sort().join(', ')}.\n`);
+        return USAGE_ERROR;
+    }
+    const skipped = skips ? { ...loaded, skipped_issuers: skips } : loaded;
     const wallet = values.valuation && isValuationProfile(values.valuation)
-        ? withValuationProfile(loaded, values.valuation)
-        : loaded;
+        ? withValuationProfile(skipped, values.valuation)
+        : skipped;
     const comparison = compareOffers(catalog, wallet, {
         kind: values.cash ? 'cash' : values.points ? 'points' : 'any',
         business: values.business ?? false,

package/dist/cli/run.js

@@ -47,6 +47,7 @@ Save your cards (optional):
   ${CLI_NAME} remove <card-id>                     Remove a card.
   ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime, costco).
   ${CLI_NAME} values [UR=1.5 ...]                  Show or set what your points are worth.
+  ${CLI_NAME} skip-issuers [chase ...]             Issuers to leave out of next-card answers.
 
 Other commands:
   ${CLI_NAME} cheatsheet                           The best card for each category this quarter.
@@ -126,7 +127,13 @@ export async function cardsToUse(catalog, file, io, named) {
             io.stderr(`${wallet}\n`);
             return null;
         }
-        return { ...wallet, valuations: saved.valuations };
+        return {
+            ...wallet,
+            valuations: saved.valuations,
+            ...(saved.skipped_issuers
+                ? { skipped_issuers: saved.skipped_issuers }
+                : {}),
+        };
     }
     try {
         await access(file);
@@ -150,8 +157,12 @@ export const NO_WALLET_HINT = `These are every card earnrate knows. For the best
 // can't be read, has none.
 export async function savedSettings(io) {
     try {
-        const { valuations, memberships } = await loadWallet(walletPath(io.env));
-        return { valuations, memberships };
+        const { valuations, memberships, skipped_issuers } = await loadWallet(walletPath(io.env));
+        return {
+            valuations,
+            memberships,
+            ...(skipped_issuers ? { skipped_issuers } : {}),
+        };
     }
     catch {
         return { valuations: {}, memberships: [] };

package/dist/cli/wallet.js

@@ -4,6 +4,7 @@ import { FileWalletStore } from "../data/file-store.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
 import { isValuationProfile, profileText, VALUATION_PROFILES, } from "../engine/profiles.js";
 import { membershipName } from "../engine/memberships.js";
+import { issuerName } from "../format/card-text.js";
 import { knownMemberships, searchCards } from "../engine/setup.js";
 import { currencyChanges } from "../engine/wallet-change.js";
 import { formatCardInfo, formatNotes } from "../format/cards.js";
@@ -13,7 +14,8 @@ const CARD_OPTIONS = `Options:
   --pick <choice>=<options>  Bonus categories you picked for this period, e.g.
                              --pick five-percent=fast-food,movie-theaters.
                              Repeat for each choice.
-  --anniversary <MM-DD>      Account anniversary, for caps that reset on it.
+  --anniversary <MM-DD>      Account anniversary, for caps that reset on it
+                             and a fee card's renewal check.
   --opened <date>            Optional: the day the account opened (YYYY-MM-DD),
                              for cards with a first-year rate. Without it the
                              card is ranked at its standard rates.
@@ -81,6 +83,13 @@ and point values stay.
 
 With no arguments, shows your memberships and the ones earnrate knows. With
 names, replaces the list. --none clears it. No cards need to be saved first.
+`,
+    'skip-issuers': `Usage: ${CLI_NAME} skip-issuers [<issuer>...] [--none]
+
+Issuers you can't or won't get a new card from (for example chase, if
+you're over its 5/24 rule). ${CLI_NAME} offers and the cards that would add
+the most leave them out. With no arguments, shows the list and the issuers
+earnrate knows. With issuers, replaces the list. --none clears it.
 `,
     values: `Usage: ${CLI_NAME} values [<currency>=<cents>...] [--profile <name>]
 
@@ -202,8 +211,8 @@ export async function runWalletCommand(command, argv, io) {
     if (command !== 'add' && command !== 'update' && cardOptionsGiven) {
         return usage(`${CLI_NAME} ${command} doesn't take card options.`);
     }
-    if (command !== 'memberships' && values.none) {
-        return usage('--none is only for memberships.');
+    if (command !== 'memberships' && command !== 'skip-issuers' && values.none) {
+        return usage('--none is only for memberships and skip-issuers.');
     }
     const catalog = await loadCatalog();
     const file = walletPath(io.env);
@@ -249,6 +258,22 @@ export async function runWalletCommand(command, argv, io) {
             .map(([id, c]) => `${id} ${c === null ? 'back to the default' : `${String(c)}¢`}`)
             .join(', ')}.`, null, io);
     }
+    if (command === 'skip-issuers') {
+        const issuerList = (ids) => ids.map((i) => `${issuerName(catalog, i)} (${i})`).join(', ');
+        if (positionals.length === 0 && !values.none) {
+            const held = await heldWallet(io);
+            const known = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
+            io.stdout(`Left out: ${held?.skipped_issuers?.length ? issuerList(held.skipped_issuers) : 'none'}\nKnown: ${known.join(', ')}\n`);
+            return 0;
+        }
+        if (positionals.length > 0 && values.none) {
+            return usage('Give issuers or --none, not both.');
+        }
+        const list = values.none ? [] : positionals;
+        return report(await store.setSkippedIssuers(list), list.length > 0
+            ? `Next-card answers now leave out ${issuerList(list)} (${where}).`
+            : `Next-card answers include every issuer again (${where}).`, null, io);
+    }
     if (command === 'memberships') {
         if (positionals.length === 0 && !values.none) {
             const held = await heldWallet(io);

package/dist/data/change-integrity.js

@@ -0,0 +1,105 @@
+import { isDeepStrictEqual } from 'node:util';
+import { changeHeadline, fieldValue, subjectOf } from "../engine/changes.js";
+import { WelcomeOfferSchema } from "../schema/card.js";
+import { CHANGE_SUBJECTS, } from "../schema/changes.js";
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// Every key the record gives matches the data; keys it leaves out (a note,
+// a default) don't matter. null means absent.
+export function matches(expected, actual) {
+    if (expected === null)
+        return actual === undefined || actual === null;
+    if (Array.isArray(expected))
+        return (Array.isArray(actual) &&
+            actual.length === expected.length &&
+            expected.every((e, i) => matches(e, actual[i])));
+    if (isRecord(expected))
+        return (isRecord(actual) &&
+            Object.entries(expected).every(([k, v]) => matches(v, actual[k])));
+    return isDeepStrictEqual(expected, actual);
+}
+const subjectKind = (c) => CHANGE_SUBJECTS.find((s) => c[s] !== undefined) ?? 'cards';
+// One path covers another when they're the same or one is inside the other.
+const overlaps = (a, b) => a === undefined ||
+    b === undefined ||
+    a === b ||
+    a.startsWith(`${b}.`) ||
+    b.startsWith(`${a}.`);
+const removes = (later, field) => later.now === null &&
+    (later.field === undefined ||
+        (field !== undefined &&
+            (field === later.field || field.startsWith(`${later.field}.`))));
+export function changeProblems(releases, catalog, changelog, version) {
+    const problems = [];
+    const sections = [...changelog.matchAll(/^## (\S+)$/gm)].map((m) => m[1]);
+    const versions = releases.map((r) => r.version);
+    if (!isDeepStrictEqual(sections, versions))
+        problems.push('data/changes.yaml releases must match data/CHANGELOG.md sections, newest first');
+    if (versions[0] !== version)
+        problems.push(`data/changes.yaml must start with ${version}`);
+    for (let i = 1; i < releases.length; i++)
+        if ((releases[i]?.date ?? '') > (releases[i - 1]?.date ?? ''))
+            problems.push(`${versions[i] ?? ''}: releases must be newest first`);
+    const touches = releases.flatMap((r, at) => r.changes.flatMap((change) => {
+        const kind = subjectKind(change);
+        return (change[kind] ?? []).map((id) => ({ at, kind, id, change }));
+    }));
+    for (const t of touches) {
+        const { change, kind, id, at } = t;
+        const release = releases[at];
+        const where = `${release?.version ?? ''} ${id}${change.field ? ` ${change.field}` : ''}`;
+        if (change.date !== undefined && change.date > (release?.date ?? ''))
+            problems.push(`${where}: date is after its release`);
+        if (change.detected !== undefined &&
+            change.detected > (change.date ?? release?.date ?? ''))
+            problems.push(`${where}: detected after it was released`);
+        const later = touches.filter((o) => o.kind === kind &&
+            o.id === id &&
+            o.change !== change &&
+            o.at <= at &&
+            overlaps(o.change.field, change.field));
+        const removedLater = later.some((o) => o.at < at && removes(o.change, change.field));
+        const subject = subjectOf(catalog, kind, id);
+        const value = fieldValue(subject, change.field);
+        const removal = change.now === null;
+        if (subject === undefined && !removedLater && !(removal && !change.field))
+            problems.push(`${where}: no ${kind} '${id}' in the data`);
+        else if (subject !== undefined &&
+            value === undefined &&
+            !removal &&
+            !removedLater)
+            problems.push(`${where}: no such field`);
+        // The newest change to a path must still describe the data.
+        if (later.length === 0 && change.now !== undefined) {
+            const current = removal && !change.field ? subject : value;
+            if (!matches(change.now, current))
+                problems.push(`${where}: 'now' doesn't match the data`);
+        }
+        if (change.cause === 'issuer') {
+            if (!change.source?.startsWith('https://'))
+                problems.push(`${where}: an issuer change needs an https source`);
+            if (change.field === 'welcome_offer')
+                for (const v of [change.was, change.now])
+                    if (v !== null && !WelcomeOfferSchema.safeParse(v).success)
+                        problems.push(`${where}: not a welcome offer: ${JSON.stringify(v)}`);
+            try {
+                changeHeadline(catalog, change);
+            }
+            catch (e) {
+                problems.push(`${where}: ${e.message}`);
+            }
+        }
+    }
+    // A value recorded as the old one must be what the previous change left.
+    for (const t of touches) {
+        if (t.change.was === undefined || t.change.field === undefined)
+            continue;
+        const before = touches.find((o) => o.kind === t.kind &&
+            o.id === t.id &&
+            o.at > t.at &&
+            o.change.field === t.change.field &&
+            o.change.now !== undefined);
+        if (before && !matches(t.change.was, before.change.now))
+            problems.push(`${releases[t.at]?.version ?? ''} ${t.id} ${t.change.field}: 'was' doesn't match the previous change's 'now'`);
+    }
+    return problems;
+}

package/dist/data/file-store.js

@@ -1,8 +1,8 @@
 import { bookPurchase } from "../engine/record.js";
-import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withValuations, } from "../engine/wallet-change.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withSkippedIssuers, withValuations, } from "../engine/wallet-change.js";
 import { loadWallet } from "./load.js";
 import { emptyWallet, } from "./store.js";
-import { addCardText, commitWalletText, EMPTY_WALLET_TEXT, readWalletText, removeCardText, setMembershipsText, setValuationsText, updateCardText, writeProgress, } from "./wallet-edit.js";
+import { addCardText, commitWalletText, EMPTY_WALLET_TEXT, readWalletText, removeCardText, setMembershipsText, setTopListText, setValuationsText, updateCardText, writeProgress, } from "./wallet-edit.js";
 const failed = (error) => ({ ok: false, error });
 const errorText = (e) => (e instanceof Error ? e.message : String(e));
 const queues = new Map();
@@ -75,6 +75,9 @@ export class FileWalletStore {
     setMemberships(memberships) {
         return this.change((w) => withMemberships(this.catalog, w ?? emptyWallet(), memberships), (text, change) => setMembershipsText(text ?? EMPTY_WALLET_TEXT, change.wallet.memberships));
     }
+    setSkippedIssuers(issuers) {
+        return this.change((w) => withSkippedIssuers(this.catalog, w ?? emptyWallet(), issuers), (text, change) => setTopListText(text ?? EMPTY_WALLET_TEXT, 'skipped_issuers', change.wallet.skipped_issuers ?? []));
+    }
     setValuations(changes) {
         return this.change((w) => withValuations(this.catalog, w ?? emptyWallet(), changes), (text) => setValuationsText(text ?? EMPTY_WALLET_TEXT, changes));
     }

package/dist/data/integrity.js

@@ -1,4 +1,5 @@
 import { resolveMerchant } from "../merchants/resolve.js";
+import { isAnniversary } from "../engine/periods.js";
 import { WALLET_VERSION } from "../schema/wallet.js";
 function duplicates(ids) {
     const seen = new Set();
@@ -305,6 +306,10 @@ export function walletProblems(wallet, catalog) {
     for (const id of duplicates(wallet.cards.map((c) => c.id))) {
         problems.push(`wallet: card '${id}' is listed twice`);
     }
+    const issuers = new Set(catalog.cards.map((c) => c.issuer));
+    for (const id of wallet.skipped_issuers ?? [])
+        if (!issuers.has(id))
+            problems.push(`wallet skipped_issuers: no card is from '${id}'`);
     for (const [id, valuation] of Object.entries(wallet.valuations)) {
         const currency = currencies.get(id);
         if (!currency) {
@@ -319,6 +324,8 @@ export function walletProblems(wallet, catalog) {
     }
     for (const held of wallet.cards) {
         const where = `wallet card ${held.id}`;
+        if (held.anniversary !== undefined && !isAnniversary(held.anniversary))
+            problems.push(`${where}: anniversary '${held.anniversary}' isn't a date`);
         const card = cards.get(held.id);
         if (!card) {
             problems.push(`${where}: not in the card catalog`);

package/dist/data/load.js

@@ -7,6 +7,7 @@ import { z } from 'zod';
 import { CONFIG_DIR, WALLET_ENV_VAR } from "../brand.js";
 import { CardSchema } from "../schema/card.js";
 import { CategoriesFileSchema } from "../schema/category.js";
+import { ChangesFileSchema } from "../schema/changes.js";
 import { CurrenciesFileSchema } from "../schema/currency.js";
 import { IssuersFileSchema } from "../schema/issuer.js";
 import { MembershipsFileSchema } from "../schema/membership.js";
@@ -50,6 +51,10 @@ export async function loadCatalog(dir = DATA_DIR) {
         merchants: { seed, overrides },
     };
 }
+// The structured change record, newest release first.
+export function loadChanges(dir = DATA_DIR) {
+    return readYaml(path.join(dir, 'changes.yaml'), ChangesFileSchema);
+}
 // MCP clients pass config values through without a shell, so "~" or
 // "${HOME}" can arrive as literal text; expand them here.
 export function walletPath(env = process.env) {

package/dist/data/store.js

@@ -1,5 +1,5 @@
 import { bookPurchase } from "../engine/record.js";
-import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withValuations, } from "../engine/wallet-change.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withSkippedIssuers, withValuations, } from "../engine/wallet-change.js";
 import { withoutCardNumbers } from "../schema/card-number.js";
 import { WALLET_VERSION, WalletSchema } from "../schema/wallet.js";
 const failed = (error) => ({ ok: false, error });
@@ -61,6 +61,9 @@ export class JsonWalletStore {
     setMemberships(memberships) {
         return this.change((w) => withMemberships(this.catalog, w ?? emptyWallet(), memberships));
     }
+    setSkippedIssuers(issuers) {
+        return this.change((w) => withSkippedIssuers(this.catalog, w ?? emptyWallet(), issuers));
+    }
     setValuations(changes) {
         return this.change((w) => withValuations(this.catalog, w ?? emptyWallet(), changes));
     }

package/dist/data/wallet-edit.js

@@ -212,18 +212,29 @@ export function updateCardText(text, cardId, fields) {
     }
     return out;
 }
-export function setMembershipsText(text, memberships) {
+export const setMembershipsText = (text, memberships) => setTopListText(text, 'memberships', memberships);
+// A top-level list, written as one flow line before `cards:`. An empty list
+// other than memberships loses its line.
+export function setTopListText(text, key, list) {
     const root = rootMap(text);
-    const line = `memberships: ${flowList(memberships)}\n`;
-    const pair = root.items.find((p) => keyOf(p) === 'memberships');
+    const line = list.length === 0 && key !== 'memberships'
+        ? ''
+        : `${key}: ${flowList(list)}\n`;
+    const pair = root.items.find((p) => keyOf(p) === key);
     if (pair) {
         const start = range(pair.key)[0];
         const end = afterLine(text, (pair.value === null ? range(pair.key) : range(pair.value))[1] - 1);
-        return text.slice(0, start) + line + text.slice(end);
+        // A comment at the end of the key's line stays with the new value.
+        const first = text
+            .slice(start, afterLine(text, start))
+            .replace(/\r?\n$/, '');
+        const comment = / #.*$/.exec(first)?.[0] ?? '';
+        const kept = line === '' ? '' : line.replace(/\n$/, `${comment}\n`);
+        return text.slice(0, start) + kept + text.slice(end);
     }
     const cards = root.items.find((p) => keyOf(p) === 'cards');
     return cards
-        ? insertLines(text, lineStart(text, range(cards.key)[0]), line)
+        ? insertLines(text, aboveComments(text, range(cards.key)[0]), line)
         : insertLines(text, text.length, line);
 }
 // Point values, one currency at a time so the rest of the file, comments

package/dist/engine/changes.js

@@ -0,0 +1,124 @@
+import { offerTerms } from "./offers.js";
+import { creditName, ruleWhat } from "./rule-text.js";
+import { creditBack, currencyName, earnText, money, pct, possessive, shortCardName, shortDate, } from "./text.js";
+// Newest first.
+export function datedChanges(releases) {
+    return releases
+        .flatMap((r) => r.changes.map((change) => ({
+        version: r.version,
+        date: change.date ?? r.date,
+        change,
+    })))
+        .sort((a, b) => (a.date === b.date ? 0 : a.date < b.date ? 1 : -1));
+}
+export const issuerChanges = (releases) => datedChanges(releases).filter((d) => d.change.cause === 'issuer');
+export function subjectOf(catalog, kind, id) {
+    switch (kind) {
+        case 'cards':
+            return catalog.cards.find((c) => c.id === id);
+        case 'merchants':
+            return [...catalog.merchants.seed, ...catalog.merchants.overrides].find((m) => m.id === id);
+        case 'categories':
+            return catalog.categories.find((c) => c.id === id);
+        case 'currencies':
+            return catalog.currencies.find((c) => c.id === id);
+        case 'memberships':
+            return catalog.memberships.find((m) => m.id === id);
+        case 'issuers':
+            return catalog.issuers.find((i) => i.id === id);
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// `rules.amazon.rate` on a card: list items are found by their id.
+export function fieldValue(subject, field) {
+    if (field === undefined)
+        return subject;
+    let value = subject;
+    for (const step of field.split('.')) {
+        if (Array.isArray(value))
+            value = value.find((item) => isRecord(item) && item.id === step);
+        else if (isRecord(value))
+            value = value[step];
+        else
+            return undefined;
+    }
+    return value;
+}
+const NO_SPEND = ' with no spending required';
+// Mid-sentence: "up to 80,000 points".
+const lower = (text) => text.replace(/^Up to /, 'up to ');
+// Only the part that changed is said twice: "$150 → $200 with no spending
+// required", "80,000 points after $3,000 … → after $2,000 …".
+function offerChange(catalog, card, was, now) {
+    const units = currencyName(catalog, card.currency);
+    const terms = (o) => lower(offerTerms(o, units));
+    const amount = (o) => lower(offerTerms({ ...o, spend: 0, months: 1 }, units)).slice(0, -NO_SPEND.length);
+    const tail = (o) => terms(o).slice(amount(o).length);
+    if (tail(was) === tail(now))
+        return `${amount(was)} → ${terms(now)}`;
+    if (amount(was) === amount(now))
+        return `${terms(was)} → ${tail(now).trim()}`;
+    return `${terms(was)} → ${terms(now)}`;
+}
+const feeWords = (fee) => typeof fee === 'number' ? (fee === 0 ? 'none' : money(fee)) : 'not on file';
+// "Prime Visa's welcome offer: $150 → $200 with no spending required": one
+// plain line for an issuer change, from its old and new values.
+export function changeHeadline(catalog, change) {
+    const id = change.cards?.[0] ?? '';
+    const card = catalog.cards.find((c) => c.id === id);
+    if (!card || change.field === undefined)
+        throw new Error(`no headline for a change to ${id}`);
+    const name = possessive(card.short_name ?? shortCardName(card.name));
+    const [kind, item] = change.field.split('.');
+    const { was, now } = change;
+    switch (kind) {
+        case 'welcome_offer':
+            if (was === null)
+                return `${name} new welcome offer: ${terms(now)}`;
+            if (now === null)
+                return `${name} welcome offer ended: ${terms(was)}`;
+            return `${name} welcome offer: ${offerChange(catalog, card, was, now)}`;
+        case 'annual_fee':
+        case 'first_year_fee':
+            return `${name} ${kind === 'annual_fee' ? 'annual fee' : 'first-year fee'}: ${feeWords(was)} → ${feeWords(now)}`;
+        case 'foreign_transaction_fee': {
+            const fee = (v) => typeof v === 'number' ? (v === 0 ? 'none' : pct(v)) : 'not on file';
+            return `${name} foreign transaction fee: ${fee(was)} → ${fee(now)}`;
+        }
+        case 'applications_closed':
+            return `${name} applications closed ${shortDate(String(now))}`;
+        case 'rules': {
+            const rule = (card.rules.find((r) => r.id === item) ?? now ?? was);
+            const rate = (v) => v === null
+                ? 'none'
+                : earnText(catalog, typeof v === 'number' ? v : v.rate, card.currency);
+            return `${name} rate ${ruleWhat(catalog, rule, card)}: ${rate(was)} → ${rate(now)}`;
+        }
+        case 'credits': {
+            const credit = (card.credits.find((c) => c.id === item) ??
+                now ??
+                was);
+            const back = (v) => v === null ? 'none' : creditBack(v);
+            return `${name} ${creditName(catalog, credit)} credit: ${back(was)} → ${back(now)}`;
+        }
+    }
+    throw new Error(`no headline for an issuer change to ${change.field}`);
+    function terms(o) {
+        return lower(offerTerms(o, currencyName(catalog, card?.currency ?? '')));
+    }
+}
+export function freshness(catalog, releases) {
+    const verified = catalog.cards.map((c) => c.last_verified).sort();
+    const first = releases.at(-1);
+    const latest = releases[0];
+    if (!first || !latest)
+        throw new Error('no data releases');
+    return {
+        issuerChanges: issuerChanges(releases).length,
+        since: first.date,
+        latestRelease: latest.date,
+        latestVersion: latest.version,
+        reviewedFrom: verified[0] ?? '',
+        reviewedTo: verified.at(-1) ?? '',
+    };
+}

package/dist/engine/checklist.js

@@ -1,8 +1,11 @@
 import { addDays, currentPeriodEnd, daysBetween } from "./periods.js";
-import { CAP_PERIODS, choiceName, askCreditText, enrollCreditText, introEndsText, listed, money, shortDate, useCreditText, wholeDollars, possessive, } from "./text.js";
+import { CAP_PERIODS, choiceName, askCreditText, enrollCreditText, introEndsText, listed, money, shortDate, renewalText, useCreditText, wholeDollars, possessive, } from "./text.js";
 import { milestonePays } from "./milestones.js";
+import { renewalCheck, renewalDue } from "./renewal.js";
 import { creditLabel, optionName } from "./rule-text.js";
 import { activationsDue, walletSummary, } from "./wallet-summary.js";
+// Node-free: earnrate.dev builds the same list from its browser wallet.
+const issuerLabel = (catalog, id) => catalog.issuers.find((i) => i.id === id)?.name ?? id;
 // "5% and 2% categories", "top category": a choice already named for its
 // category isn't followed by "categories" again.
 function pickWhat(names) {
@@ -17,7 +20,9 @@ function pickWhat(names) {
 // hasn't posted yet.
 export function checklist(catalog, wallet, today, summary = walletSummary(catalog, wallet, today), 
 // A shorter card name than the issuer's full one, where the caller has it.
-shortName) {
+shortName, 
+// For the renewal check; typical amounts when not given.
+spending) {
     const items = [];
     for (const held of wallet.cards) {
         const card = catalog.cards.find((c) => c.id === held.id);
@@ -74,7 +79,7 @@ shortName) {
             items.push({
                 kind: 'pick',
                 cardId: card.id,
-                text: `${possessive(name)} ${listed(assumed.map((c) => choiceName(c.id)))} pick is assumed to be ${listed(assumed.flatMap((c) => (c.default ?? []).map((o) => optionName(catalog, card, c.id, o))))}; set it if you picked something else.`,
+                text: `${possessive(name)} ${listed(assumed.map((c) => choiceName(c.id)))} pick is assumed to be ${listed(assumed.flatMap((c) => (c.default ?? []).map((o) => optionName(catalog, card, c.id, o))))}; set it if ${assumed.every((c) => c.automatic) ? 'you expect another to have the most spending' : 'you picked something else'}.`,
                 due: null,
             });
         for (const cap of s.caps) {
@@ -158,6 +163,16 @@ shortName) {
                 text: introEndsText(name, s.intro.days, s.intro.until),
                 due: s.intro.until,
             });
+        const due = (card.annual_fee ?? 0) > 0 ? renewalDue(held, today) : null;
+        if (due !== null) {
+            const r = renewalCheck(catalog, wallet, card, due, spending);
+            items.push({
+                kind: 'renewal',
+                cardId: card.id,
+                text: renewalText(name, issuerLabel(catalog, card.issuer), r),
+                due,
+            });
+        }
         if (s.rotationGap !== null) {
             items.push({
                 kind: 'rotation',

package/dist/engine/explore.js

@@ -8,7 +8,7 @@ import { FOREIGN_ASSUMPTION, foreignFeeFor, isForeign, recommend, } from "./reco
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
 import { optionName } from "./rule-text.js";
-import { amountUnknownText, capSentence, categoryPhrase, choiceName, codesAs, creditBack, creditThen, creditTerms, earnText, listed, paidText, PAYMENT_PHRASES, paymentUnknownText, PICK_PERIODS, pointValuesText, } from "./text.js";
+import { amountUnknownText, capSentence, categoryPhrase, choiceName, codesAs, creditBack, creditThen, creditTerms, earnText, listed, paidText, PAYMENT_PHRASES, paymentUnknownText, pickCondition, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
@@ -93,7 +93,12 @@ function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
     const cap = best.cap?.cap;
     return {
         pick: choice && picked
-            ? { choice: choice.id, options: picked, period: choice.period }
+            ? {
+                choice: choice.id,
+                options: picked,
+                period: choice.period,
+                automatic: choice.automatic === true,
+            }
             : null,
         activation: rule.requires?.activation === true ? rule.id : null,
         membership: rule.requires?.membership ?? null,
@@ -110,7 +115,7 @@ function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
 function conditionsText(catalog, card, r) {
     const conditions = [];
     if (r.pick) {
-        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]}).`);
+        conditions.push(`${pickCondition({ pick: card.choices.find((c) => c.id === r.pick?.choice)?.pick ?? 1, ...r.pick }, r.pick.options.map((o) => optionName(catalog, card, r.pick?.choice ?? '', o)).join(' or '), choiceName(r.pick.choice))}.`);
     }
     if (r.activation !== null)
         conditions.push('Needs its bonus activated with the issuer (free).');
@@ -247,8 +252,27 @@ export function exploreCards(catalog, query, options, resolved) {
         excluded,
         assumptions: exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid, ifLarger),
         warnings: exploreWarnings(catalog, merchant),
+        ifPaying: paidAtTop(ranked, ifPaid).map(({ entry, paid }) => ({
+            cardId: entry.cardId,
+            cardName: entry.cardName,
+            payment: paid.payment,
+            earn: paid.earn,
+        })),
     };
 }
+// Cards a way of paying would lift to the top (or that are already there).
+function paidAtTop(ranked, ifPaid) {
+    const top = ranked[0];
+    if (!top)
+        return [];
+    return ranked.flatMap((entry) => {
+        const paid = ifPaid.get(entry.cardId);
+        return paid &&
+            (entry === top || paid.returnPct > top.effectiveReturnPct + EPSILON)
+            ? [{ entry, paid }]
+            : [];
+    });
+}
 function creditPicks(catalog, merchant, ranked, date) {
     const picks = ranked.flatMap((entry) => {
         const card = catalog.cards.find((c) => c.id === entry.cardId);
@@ -304,12 +328,7 @@ function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid
     if (purchase.payment)
         assumptions.push(paidText(purchase.payment));
     const top = ranked[0];
-    for (const entry of ranked) {
-        const paid = ifPaid.get(entry.cardId);
-        if (!paid || !top)
-            continue;
-        if (entry !== top && paid.returnPct <= top.effectiveReturnPct + EPSILON)
-            continue;
+    for (const { entry, paid } of paidAtTop(ranked, ifPaid)) {
         assumptions.push(paymentUnknownText(entry.cardName, paid.payment, paid.earn, paid.standard));
     }
     for (const entry of ranked) {