earnrate 0.1.0 → 0.1.2

package/dist/data/integrity.js

@@ -106,7 +106,10 @@ function cardProblems(card, catalog, merchantIds) {
                 problems.push(`${where} choice ${choice.id}: default '${d}' is not an option`);
         }
         for (const [option, covered] of options) {
-            for (const c of covered.categories)
+            for (const c of [
+                ...covered.categories,
+                ...(covered.online?.exclude ?? []),
+            ])
                 checkCategory(c, `choice ${choice.id}.${option}`);
             for (const m of covered.merchants)
                 checkMerchant(m, `choice ${choice.id}.${option}`);
@@ -133,6 +136,20 @@ function cardProblems(card, catalog, merchantIds) {
             problems.push(`${where} ${context}: unknown cap '${rule.cap}'`);
         }
     }
+    for (const cap of card.caps.filter((c) => c.rotating)) {
+        const rules = card.rules.filter((r) => r.cap === cap.id);
+        if (rules.length === 0) {
+            problems.push(`${where} cap ${cap.id}: rotating, but no rule uses it`);
+        }
+        for (const r of rules) {
+            if (r.valid_from === undefined || r.valid_to === undefined) {
+                problems.push(`${where} rule ${r.id}: rules on rotating cap '${cap.id}' need valid_from and valid_to`);
+            }
+        }
+        if (cap.period === 'cardmember_year') {
+            problems.push(`${where} cap ${cap.id}: a rotating cap can't use cardmember years`);
+        }
+    }
     return problems;
 }
 export function catalogProblems(catalog) {

package/dist/data/wallet-edit.js

@@ -0,0 +1,162 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { isMap, isSeq, parseDocument, stringify } from 'yaml';
+import { 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
+
+`;
+const BY_HAND = 'edit the wallet by hand';
+const lineStart = (text, at) => text.lastIndexOf('\n', at - 1) + 1;
+function afterLine(text, at) {
+    const end = text.indexOf('\n', at);
+    return end === -1 ? text.length : end + 1;
+}
+function insertLines(text, at, lines) {
+    const head = text.slice(0, at);
+    const gap = head.length > 0 && !head.endsWith('\n') ? '\n' : '';
+    return `${head}${gap}${lines}${text.slice(at)}`;
+}
+function range(node) {
+    const r = node?.range;
+    if (!r)
+        throw new Error(`a wallet value has no source position; ${BY_HAND}`);
+    return r;
+}
+const keyOf = (pair) => pair.key?.value;
+const scalar = (value) => stringify(value).trimEnd();
+const flowList = (ids) => `[${ids.join(', ')}]`;
+function fieldLines(field, f, indent) {
+    switch (field) {
+        case 'checkout_label':
+        case 'anniversary': {
+            const value = f[field];
+            return value === undefined ? '' : `${indent}${field}: ${scalar(value)}\n`;
+        }
+        case 'activated':
+            return f.activated === undefined
+                ? ''
+                : `${indent}activated: ${flowList(f.activated)}\n`;
+        case 'chosen': {
+            if (f.chosen === undefined)
+                return '';
+            const picks = Object.entries(f.chosen.picks)
+                .map(([choice, ids]) => `${indent}    ${choice}: ${flowList(ids)}\n`)
+                .join('');
+            return `${indent}chosen:\n${indent}  period: ${scalar(f.chosen.period)}\n${indent}  picks:\n${picks}`;
+        }
+    }
+}
+const FIELDS = ['checkout_label', 'anniversary', 'chosen', 'activated'];
+function cardsSeq(text) {
+    const doc = parseDocument(text);
+    if (doc.errors.length > 0)
+        throw new Error(doc.errors[0]?.message);
+    const cards = doc.get('cards', true);
+    if (!isSeq(cards) || cards.flow) {
+        throw new Error(`"cards" isn't a block list; ${BY_HAND}`);
+    }
+    return { doc, cards };
+}
+function findCard(text, cardId) {
+    const { cards } = cardsSeq(text);
+    const card = cards.items.find((item) => isMap(item) && item.get('id') === cardId);
+    if (!isMap(card))
+        throw new Error(`no card '${cardId}' in the wallet`);
+    if (card.flow)
+        throw new Error(`card '${cardId}' is written inline; ${BY_HAND}`);
+    return card;
+}
+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, '  ')}`;
+    }
+    const { cards } = cardsSeq(text);
+    const first = cards.items[0];
+    if (!isMap(first))
+        throw new Error(`"cards" is empty; ${BY_HAND}`);
+    const keyColumn = column(text, range(first)[0]);
+    if (keyColumn < 2 || text[range(first)[0] - 2] !== '-') {
+        throw new Error(`can't tell how the cards are indented; ${BY_HAND}`);
+    }
+    const at = afterLine(text, range(cards)[1] - 1);
+    return insertLines(text, at, cardLines(entry, ' '.repeat(keyColumn - 2)));
+}
+function cardLines(entry, dashIndent) {
+    const indent = `${dashIndent}  `;
+    return `${dashIndent}- id: ${entry.id}\n${FIELDS.map((f) => fieldLines(f, entry, indent)).join('')}`;
+}
+export function removeCardText(text, cardId) {
+    const card = findCard(text, cardId);
+    const start = lineStart(text, range(card)[0]);
+    const end = afterLine(text, range(card)[1] - 1);
+    return text.slice(0, start) + text.slice(end);
+}
+// Replaces each given field in place, or adds it after the card's last line.
+export function updateCardText(text, cardId, fields) {
+    let out = text;
+    for (const field of FIELDS) {
+        if (fields[field] === undefined)
+            continue;
+        const card = findCard(out, cardId);
+        const indent = ' '.repeat(column(out, range(card)[0]));
+        const lines = fieldLines(field, fields, indent);
+        const pair = card.items.find((p) => keyOf(p) === field);
+        if (pair) {
+            const start = range(pair.key)[0];
+            const end = afterLine(out, range(pair.value)[1] - 1);
+            out = out.slice(0, start) + lines.trimStart() + out.slice(end);
+        }
+        else {
+            out = insertLines(out, afterLine(out, range(card)[1] - 1), lines);
+        }
+    }
+    return out;
+}
+export function setMembershipsText(text, memberships) {
+    const { doc } = cardsSeq(text);
+    const root = doc.contents;
+    if (!isMap(root))
+        throw new Error(`the wallet isn't a map; ${BY_HAND}`);
+    const line = `memberships: ${flowList(memberships)}\n`;
+    const pair = root.items.find((p) => keyOf(p) === 'memberships');
+    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);
+    }
+    const cards = root.items.find((p) => keyOf(p) === 'cards');
+    return insertLines(text, lineStart(text, range(cards?.key)[0]), line);
+}
+async function readText(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (e) {
+        if (e instanceof Error && 'code' in e && e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+}
+export async function readWalletText(file) {
+    const text = await readText(file);
+    return {
+        text,
+        wallet: text === null ? null : WalletSchema.parse(parseDocument(text).toJS()),
+    };
+}
+// Writes `after` only if it parses to exactly `expected`, so a splice that
+// went wrong can never change anything it wasn't meant to.
+export async function commitWalletText(file, after, expected) {
+    const parsed = WalletSchema.safeParse(parseDocument(after).toJS());
+    if (!parsed.success || !isDeepStrictEqual(parsed.data, expected)) {
+        throw new Error(`couldn't update ${file} safely; ${BY_HAND}`);
+    }
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${String(process.pid)}.tmp`;
+    await writeFile(tmp, after);
+    await rename(tmp, file);
+}

package/dist/data/wallet-setup.js

@@ -0,0 +1,202 @@
+import { periodKey } from "../engine/periods.js";
+import { knownMemberships, searchCards, setupNotes, } from "../engine/setup.js";
+import { WalletCardSchema, WalletSchema, } from "../schema/wallet.js";
+import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, updateCardText, } from "./wallet-edit.js";
+const failed = (error) => ({ ok: false, error });
+const list = (ids) => ids.join(', ');
+function findCatalogCard(catalog, id, today) {
+    const card = catalog.cards.find((c) => c.id === id);
+    if (card)
+        return card;
+    const near = searchCards(catalog, id, null, today).cards.map((c) => c.id);
+    return near.length > 0
+        ? `No card '${id}' in earnrate. Closest: ${list(near)}.`
+        : `No card '${id}' in earnrate. Search the catalog to find its id.`;
+}
+function isAnniversary(text) {
+    const m = /^(\d{2})-(\d{2})$/.exec(text);
+    if (!m)
+        return false;
+    const date = new Date(`2024-${text}T00:00:00Z`); // a leap year allows 02-29
+    return (!Number.isNaN(date.getTime()) && date.toISOString().slice(5, 10) === text);
+}
+// The period key picks are filed under: the card's choice period, or for
+// picks that carry over, the current year (it's never compared).
+function choicePeriod(card, today) {
+    const periods = [
+        ...new Set(card.choices.map((c) => c.period).filter((p) => p !== 'until_changed')),
+    ];
+    if (periods.length > 1)
+        return null;
+    return periodKey(periods[0] ?? 'calendar_year', today, null);
+}
+function fieldsFor(card, held, input, today) {
+    const problems = [];
+    const fields = {};
+    if (input.checkoutLabel !== undefined) {
+        if (input.checkoutLabel.trim() === '')
+            problems.push('The checkout label is empty.');
+        // earnrate never stores card numbers; a last four is fine.
+        if (/\d{8,}/.test(input.checkoutLabel.replace(/[\s-]/g, '')))
+            problems.push('The checkout label looks like it has a card number in it. earnrate never stores card numbers; use a name like "Amex Gold".');
+        fields.checkout_label = input.checkoutLabel.trim();
+    }
+    if (input.anniversary !== undefined) {
+        if (!isAnniversary(input.anniversary)) {
+            problems.push(`"${input.anniversary}" isn't an anniversary. Use MM-DD, like 03-15.`);
+        }
+        fields.anniversary = input.anniversary;
+    }
+    if (input.activated !== undefined) {
+        const needing = card.rules
+            .filter((r) => r.requires?.activation)
+            .map((r) => r.id);
+        for (const id of input.activated) {
+            if (!needing.includes(id)) {
+                problems.push(needing.length > 0
+                    ? `'${id}' isn't a ${card.id} rule that needs activating. Those are: ${list(needing)}.`
+                    : `${card.id} has no rules that need activating.`);
+            }
+        }
+        fields.activated = [...new Set(input.activated)];
+    }
+    if (input.picks !== undefined) {
+        for (const [choiceId, picks] of Object.entries(input.picks)) {
+            const choice = card.choices.find((c) => c.id === choiceId);
+            if (!choice) {
+                problems.push(card.choices.length > 0
+                    ? `${card.id} has no '${choiceId}' pick. Its picks are: ${list(card.choices.map((c) => c.id))}.`
+                    : `${card.id} has no categories to pick.`);
+                continue;
+            }
+            const options = Object.keys(choice.options);
+            for (const p of picks) {
+                if (!options.includes(p)) {
+                    problems.push(`'${p}' isn't a ${choiceId} option for ${card.id}. Options: ${list(options)}.`);
+                }
+            }
+            if (picks.length === 0 || picks.length > choice.pick) {
+                problems.push(`${choiceId} takes ${choice.pick === 1 ? '1 pick' : `1 to ${String(choice.pick)} picks`}, not ${String(picks.length)}.`);
+            }
+        }
+        const period = choicePeriod(card, today);
+        if (period === null) {
+            problems.push(`${card.id} has picks on different schedules; edit the wallet by hand.`);
+        }
+        else {
+            const kept = held?.chosen?.period === period ? held.chosen.picks : {};
+            fields.chosen = {
+                period,
+                picks: { ...kept, ...input.picks },
+            };
+        }
+    }
+    return problems.length > 0 ? problems.join('\n') : fields;
+}
+const applyFields = (held, f) => WalletCardSchema.parse({
+    ...held,
+    ...(f.checkout_label === undefined
+        ? {}
+        : { checkout_label: f.checkout_label }),
+    ...(f.anniversary === undefined ? {} : { anniversary: f.anniversary }),
+    ...(f.chosen === undefined ? {} : { chosen: f.chosen }),
+    ...(f.activated === undefined ? {} : { activated: f.activated }),
+});
+async function attempt(task) {
+    try {
+        return await task();
+    }
+    catch (e) {
+        return failed(e instanceof Error ? e.message : String(e));
+    }
+}
+const noWallet = (file) => `No wallet at ${file} yet. Add a card first to create it.`;
+export function addCard(file, catalog, input, today) {
+    return attempt(async () => {
+        const card = findCatalogCard(catalog, input.id, today);
+        if (typeof card === 'string')
+            return failed(card);
+        const { text, wallet } = await readWalletText(file);
+        if (wallet?.cards.some((c) => c.id === card.id)) {
+            return failed(`${card.id} is already in the wallet. Update it instead.`);
+        }
+        const fields = fieldsFor(card, null, input, today);
+        if (typeof fields === 'string')
+            return failed(fields);
+        const held = applyFields(WalletCardSchema.parse({ id: card.id }), fields);
+        const expected = wallet
+            ? { ...wallet, cards: [...wallet.cards, held] }
+            : WalletSchema.parse({ cards: [held] });
+        await commitWalletText(file, addCardText(text, { id: card.id, ...fields }), expected);
+        return {
+            ok: true,
+            wallet: expected,
+            created: text === null,
+            notes: setupNotes(catalog, expected, held, today),
+        };
+    });
+}
+export function updateCard(file, catalog, input, today) {
+    return attempt(async () => {
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        const held = wallet.cards.find((c) => c.id === input.id);
+        const card = catalog.cards.find((c) => c.id === input.id);
+        if (!held || !card) {
+            return failed(`${input.id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
+        }
+        const fields = fieldsFor(card, held, input, today);
+        if (typeof fields === 'string')
+            return failed(fields);
+        if (Object.keys(fields).length === 0)
+            return failed('Nothing to change.');
+        const updated = applyFields(held, fields);
+        const expected = {
+            ...wallet,
+            cards: wallet.cards.map((c) => (c.id === held.id ? updated : c)),
+        };
+        await commitWalletText(file, updateCardText(text, held.id, fields), expected);
+        return {
+            ok: true,
+            wallet: expected,
+            created: false,
+            notes: setupNotes(catalog, expected, updated, today),
+        };
+    });
+}
+export function removeCard(file, _catalog, id) {
+    return attempt(async () => {
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        if (!wallet.cards.some((c) => c.id === id)) {
+            return failed(`${id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
+        }
+        if (wallet.cards.length === 1) {
+            return failed(`${id} is the last card in the wallet, and a wallet needs one. Add the new card first, then remove this one.`);
+        }
+        const expected = {
+            ...wallet,
+            cards: wallet.cards.filter((c) => c.id !== id),
+        };
+        await commitWalletText(file, removeCardText(text, id), expected);
+        return { ok: true, wallet: expected, created: false, notes: [] };
+    });
+}
+export function setMemberships(file, catalog, memberships) {
+    return attempt(async () => {
+        const known = knownMemberships(catalog);
+        const unknown = memberships.filter((m) => !known.includes(m));
+        if (unknown.length > 0) {
+            return failed(`No card rule uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
+        }
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        const unique = [...new Set(memberships)];
+        const expected = { ...wallet, memberships: unique };
+        await commitWalletText(file, setMembershipsText(text, unique), expected);
+        return { ok: true, wallet: expected, created: false, notes: [] };
+    });
+}

package/dist/engine/evaluate.js

@@ -30,6 +30,7 @@ export function pickedCategories(card, held, date) {
         let picks = chosen?.picks[choice.id];
         if (picks &&
             chosen &&
+            choice.period !== 'until_changed' &&
             chosen.period !== periodKey(choice.period, date, null)) {
             staleChoice = chosen.period;
             picks = undefined;
@@ -41,6 +42,7 @@ export function pickedCategories(card, held, date) {
         picked.set(choice.id, {
             categories: options.flatMap((o) => o.categories),
             merchants: options.flatMap((o) => o.merchants),
+            online: options.flatMap((o) => (o.online ? [o.online] : [])),
         });
     }
     return { picked, staleChoice };
@@ -60,7 +62,11 @@ function applicability(rule, ctx, held, picked) {
         const covered = picked.get(match.choice);
         const merchantPicked = ctx.merchantId !== null &&
             (covered?.merchants.includes(ctx.merchantId) ?? false);
-        if (!merchantPicked && !inCategory(covered?.categories ?? []))
+        const onlinePicked = ctx.channel === 'online' &&
+            (covered?.online.some((o) => !inCategory(o.exclude)) ?? false);
+        if (!merchantPicked &&
+            !onlinePicked &&
+            !inCategory(covered?.categories ?? []))
             return 'no';
     }
     if (exclude?.categories && inCategory(exclude.categories))

package/dist/engine/recommend.js

@@ -2,6 +2,7 @@ import { resolveMerchant, resolveMerchantById } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext, } from "./evaluate.js";
 import { bonusStatus } from "./bonus.js";
 import { daysBetween } from "./periods.js";
+import { rotationGap } from "./rotation.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 export const STALE_AFTER_DAYS = 180;
@@ -327,6 +328,14 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             : '';
         warnings.push(`Not every business takes ${NETWORK_NAMES[winner.card.network] ?? winner.card.network}.${fallback}`);
     }
+    for (const held of wallet.cards) {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        const gap = card ? rotationGap(card, purchase.date) : null;
+        if (card && gap !== null) {
+            const name = held.checkout_label ?? card.name;
+            warnings.push(`${name}'s rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them. If this purchase is in that period's categories, ${name} may earn more.`);
+        }
+    }
     const tie = tieNote(entries);
     if (tie)
         notes.push(tie);

package/dist/engine/rotation.js

@@ -0,0 +1,16 @@
+import { periodKey } from "./periods.js";
+// The period of the card's rotating categories that `date` falls in, when no
+// rule in the data covers it yet; null when it's covered or the card doesn't
+// rotate.
+export function rotationGap(card, date) {
+    for (const cap of card.caps) {
+        if (!cap.rotating || cap.period === 'cardmember_year')
+            continue;
+        const covered = card.rules.some((r) => r.cap === cap.id &&
+            (r.valid_from ?? '') <= date &&
+            date <= (r.valid_to ?? ''));
+        if (!covered)
+            return periodKey(cap.period, date, null);
+    }
+    return null;
+}

package/dist/engine/setup.js

@@ -0,0 +1,168 @@
+import { pickedCategories } from "./evaluate.js";
+import { daysBetween } from "./periods.js";
+import { rotationGap } from "./rotation.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
+    .toLowerCase()
+    .replace(/\+/g, ' plus ')
+    .replace(/&/g, ' and ')
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length > 0);
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = row[0] ?? 0;
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = row[j] ?? 0;
+            row[j] = Math.min(above + 1, (row[j - 1] ?? 0) + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length] ?? 0;
+}
+function matcher(card) {
+    const haystack = [
+        ...words(card.id),
+        ...words(card.name),
+        ...words(card.issuer),
+        ...words(ISSUER_NICKNAMES[card.issuer] ?? ''),
+    ];
+    const compact = haystack.join('');
+    return (token) => haystack.some((w) => w.startsWith(token)) ||
+        (token.length >= 4 && compact.includes(token)) ||
+        (token.length >= 5 &&
+            haystack.some((w) => editDistance(w, token) <= (token.length >= 8 ? 2 : 1)));
+}
+function needsAnniversary(card) {
+    return (card.caps.some((c) => c.period === 'cardmember_year') ||
+        card.rules.some((r) => typeof r.cap === 'object' && r.cap.period === 'cardmember_year'));
+}
+function activationRules(card, today) {
+    return card.rules
+        .filter((r) => r.requires?.activation === true &&
+        (r.valid_to === undefined || r.valid_to >= today) &&
+        (r.valid_from === undefined ||
+            daysBetween(today, r.valid_from) <= ACTIVATION_LOOKAHEAD_DAYS))
+        .map((r) => r.id);
+}
+export function membershipsUsed(card) {
+    return [
+        ...new Set(card.rules.flatMap((r) => r.requires?.membership === undefined ? [] : [r.requires.membership])),
+    ];
+}
+export function knownMemberships(catalog) {
+    return [...new Set(catalog.cards.flatMap(membershipsUsed))].sort();
+}
+export function cardInfo(card, wallet, today) {
+    return {
+        id: card.id,
+        name: card.name,
+        issuer: card.issuer,
+        network: card.network,
+        currency: card.currency,
+        annualFee: card.annual_fee ?? null,
+        business: card.business,
+        onlyAt: card.only_at ?? null,
+        held: wallet?.cards.some((c) => c.id === card.id) ?? false,
+        choices: card.choices.map((c) => ({
+            id: c.id,
+            pick: c.pick,
+            period: c.period,
+            options: Object.keys(c.options),
+            default: c.default ?? null,
+        })),
+        memberships: membershipsUsed(card),
+        activation: activationRules(card, today),
+        needsAnniversary: needsAnniversary(card),
+    };
+}
+// Every word of the query has to match a word of the card's id, name or
+// 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 scored = catalog.cards.map((card) => {
+        const matches = matcher(card);
+        return { card, score: tokens.filter((t) => matches(t)).length };
+    });
+    const byShortestId = (a, b) => words(a.card.id).length - words(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));
+    const exact = full.length > 0;
+    const chosen = exact
+        ? full.sort(byShortestId)
+        : best === 0
+            ? []
+            : scored
+                .filter((s) => s.score === best)
+                .sort(byShortestId)
+                .slice(0, 5);
+    return {
+        cards: chosen.map((s) => cardInfo(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);
+    if (!card)
+        return [];
+    const notes = [];
+    const name = held.checkout_label ?? card.name;
+    const { picked, staleChoice } = pickedCategories(card, held, today);
+    for (const choice of card.choices) {
+        const current = held.chosen?.picks[choice.id] !== undefined &&
+            (staleChoice === null || choice.period === 'until_changed');
+        if (current)
+            continue;
+        const options = list(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} needs its ${choice.id} pick for this period (${String(choice.pick)} of: ${options}). Until then those categories earn the base rate.`,
+        });
+    }
+    const missing = membershipsUsed(card).filter((m) => !wallet.memberships.includes(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.`,
+        });
+    }
+    const toActivate = activationRules(card, today).filter((id) => !held.activated.includes(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.`,
+        });
+    }
+    if (needsAnniversary(card) && held.anniversary === undefined) {
+        notes.push({
+            kind: 'anniversary',
+            text: `${name} has a cap that resets on the card's anniversary. Add the anniversary (MM-DD) so it can be tracked.`,
+        });
+    }
+    const gap = rotationGap(card, today);
+    if (gap !== null) {
+        notes.push({
+            kind: 'rotation',
+            text: `${name}'s rotating categories for ${gap} aren't in earnrate's data yet.`,
+        });
+    }
+    return notes;
+}

package/dist/engine/wallet-summary.js

@@ -1,6 +1,7 @@
 import { bonusStatus } from "./bonus.js";
 import { pickedCategories } from "./evaluate.js";
 import { daysBetween, periodKey } from "./periods.js";
+import { rotationGap } from "./rotation.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { cardValuation } from "./valuation.js";
 function capSummaries(card, held, today) {
@@ -54,6 +55,7 @@ export function walletSummary(catalog, wallet, today) {
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,
             dataIsStale: daysBetween(card.last_verified, today) > STALE_AFTER_DAYS,
+            rotationGap: rotationGap(card, today),
             caps: capSummaries(card, held, today),
             chosen: held.chosen
                 ? {