earnrate 0.2.12 → 0.2.13

package/dist/cli/args.js

@@ -2,6 +2,7 @@ import { parseArgs } from 'node:util';
 import { isValuationProfile, } from "../engine/profiles.js";
 import { knownMemberships } from "../engine/setup.js";
 import { COUNTRY_CODE, countryProblem } from "../schema/common.js";
+import { PaymentMethod } from "../schema/card.js";
 // Shared by every subcommand, so each flag means the same thing everywhere.
 // A string result is the error to show.
 const LOOKS_LIKE_AMOUNT = /^\$?[\d,]*\.?\d+$/;
@@ -50,6 +51,18 @@ export function membershipProblem(catalog, members) {
         ? null
         : `Unknown membership "${unknown.join('", "')}". Use one of: ${known.join(', ')}.`;
 }
+export const PAYING_HELP = `--paying <how>         card, apple-pay, google-pay or paypal. Rates that need
+                         one (Apple Pay on Apple Card) count only when you say.`;
+export function paymentOf(text) {
+    if (text === undefined)
+        return { payment: null };
+    const parsed = PaymentMethod.safeParse(text.toLowerCase());
+    return parsed.success
+        ? { payment: parsed.data }
+        : {
+            problem: `Unknown way of paying "${text}". Use one of: ${PaymentMethod.options.join(', ')}.`,
+        };
+}
 export const BOTH_CHANNELS = 'Pick --online or --in-store, not both.';
 export function channelOf(values) {
     return values.online ? 'online' : values['in-store'] ? 'in_store' : null;
@@ -75,6 +88,7 @@ export function parseCliArgs(argv) {
                 valuation: { type: 'string' },
                 date: { type: 'string' },
                 country: { type: 'string' },
+                paying: { type: 'string' },
                 json: { type: 'boolean' },
                 category: { type: 'string' },
                 all: { type: 'boolean' },
@@ -112,6 +126,9 @@ export function parseCliArgs(argv) {
     const country = values.country ?? 'US';
     if (!COUNTRY_CODE.test(country))
         return { kind: 'error', message: countryProblem(country) };
+    const paying = paymentOf(values.paying);
+    if ('problem' in paying)
+        return { kind: 'error', message: paying.problem };
     return {
         kind: 'run',
         options: {
@@ -121,6 +138,7 @@ export function parseCliArgs(argv) {
             valuation,
             date: values.date ?? null,
             country: country.toUpperCase(),
+            payment: paying.payment,
             json: values.json ?? false,
             all: values.all ?? false,
             category: values.category ?? null,

package/dist/cli/explore.js

@@ -5,7 +5,7 @@ import { ALL_PERSONAL_CARDS, exploreCards, } from "../engine/explore.js";
 import { isValuationProfile, profileText, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
 import { resolveSpendLines, simulateAdditions, simulateCatalog, spendLineFor, typicalSpend, TYPICAL_SPEND_NOTE, } from "../engine/simulate.js";
 import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../format/explore.js";
-import { BOTH_CHANNELS, cardList, channelOf, dateProblem, membershipProblem, splitAmount, valuationProblem, } from "./args.js";
+import { BOTH_CHANNELS, cardList, channelOf, dateProblem, membershipProblem, paymentOf, splitAmount, valuationProblem, } from "./args.js";
 import { COUNTRY_CODE, countryProblem } from "../schema/common.js";
 import { cardsToUse, RUNTIME_ERROR, savedSettings, USAGE_ERROR, } from "./run.js";
 const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or points and miles cards only.
@@ -33,6 +33,8 @@ ${FILTER_OPTIONS}
   --date <YYYY-MM-DD>     Purchase date. Default: today.
   --country <code>        Where you're paying. Abroad, cards rank after their
                           foreign transaction fees. Default: US.
+  --paying <how>          card, apple-pay, google-pay or paypal. Rates that need
+                          one (Apple Pay on Apple Card) count only when you say.
   --all                   List every card, not just the top 10.
   --json                  Print the full result as JSON.
   -h, --help              Show this help.
@@ -108,6 +110,7 @@ export async function runBest(argv, io) {
                 'in-store': { type: 'boolean' },
                 date: { type: 'string' },
                 country: { type: 'string' },
+                paying: { type: 'string' },
             },
         });
     }
@@ -144,6 +147,11 @@ export async function runBest(argv, io) {
         io.stderr(`${countryProblem(country)}\n`);
         return USAGE_ERROR;
     }
+    const paying = paymentOf(values.paying);
+    if ('problem' in paying) {
+        io.stderr(`${paying.problem}\n`);
+        return USAGE_ERROR;
+    }
     const catalog = await loadCatalog();
     const settings = settingsFrom(values, catalog, await savedSettings(io));
     if (typeof settings === 'string') {
@@ -157,6 +165,7 @@ export async function runBest(argv, io) {
         channel: channelOf(values),
         date: values.date ?? io.today,
         country: country.toUpperCase(),
+        payment: paying.payment,
     }, settings);
     io.stdout(values.json
         ? `${JSON.stringify(result, null, 2)}\n`

package/dist/cli/run.js

@@ -17,7 +17,7 @@ import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
 import { missedPath, missLogAt } from "../merchants/missed.js";
 import { resolvePlace, withCallerCategory } from "../merchants/resolve.js";
 import { packageVersion } from "../version.js";
-import { membershipProblem, parseCliArgs } from "./args.js";
+import { membershipProblem, PAYING_HELP, parseCliArgs } from "./args.js";
 import { runCheatSheet } from "./cheatsheet.js";
 import { runMissed } from "./missed.js";
 import { runTodo } from "./todo.js";
@@ -67,6 +67,7 @@ Options:
   --date <YYYY-MM-DD>    Purchase date. Default: today.
   --country <code>       Where you're paying. Abroad, cards rank after their
                          foreign transaction fees. Default: US.
+  ${PAYING_HELP}
   --cards <ids>          Answer for these cards instead of your wallet, comma
                          separated: --cards amex-gold,chase-prime-visa.
   --member <name>        A membership you have, in place of the saved ones.
@@ -201,6 +202,7 @@ export async function run(argv, io) {
         channel: options.channel,
         date: options.date ?? io.today,
         country: options.country,
+        payment: options.payment,
     };
     if (options.category !== null &&
         !catalog.categories.some((c) => c.id === options.category)) {
@@ -239,6 +241,7 @@ export async function run(argv, io) {
             channel: purchase.channel,
             date: purchase.date,
             country: purchase.country,
+            payment: purchase.payment ?? null,
         }, {
             filters: ALL_PERSONAL_CARDS,
             memberships: options.members.length > 0 ? options.members : saved.memberships,

package/dist/cli/wallet.js

@@ -19,6 +19,12 @@ const CARD_OPTIONS = `Options:
                              card is ranked at its standard rates.
   --activated <rules>        Rules you've activated with the issuer, comma
                              separated. Replaces the current list.
+  --enrolled <credits>       Merchant credits you've enrolled in with the
+                             issuer, comma separated, e.g. --enrolled lululemon.
+                             Replaces the current list.
+  --credit-used <credit>=<dollars>
+                             How much of a credit you've received this period,
+                             e.g. --credit-used lululemon=40. Repeat for each.
   --bonus-opened <date>      Track a welcome bonus: the day the account opened
                              (YYYY-MM-DD). Spending needed and the deadline
                              default to the card's published offer.
@@ -47,8 +53,8 @@ ${CARD_OPTIONS}
     update: `Usage: ${CLI_NAME} update <card-id> [options]
 
 Changes a card in your wallet: picks for this period, label, anniversary,
-opening date, activations or welcome bonus. Picks for the current period are merged with
-ones already set.
+opening date, activations, merchant credits or welcome bonus. Picks for the
+current period are merged with ones already set.
 
 ${CARD_OPTIONS}
 `,
@@ -135,6 +141,8 @@ export async function runWalletCommand(command, argv, io) {
                 anniversary: { type: 'string' },
                 opened: { type: 'string' },
                 activated: { type: 'string' },
+                enrolled: { type: 'string' },
+                'credit-used': { type: 'string', multiple: true },
                 'bonus-opened': { type: 'string' },
                 'bonus-spent': { type: 'string' },
                 'bonus-spend': { type: 'string' },
@@ -163,7 +171,9 @@ export async function runWalletCommand(command, argv, io) {
         values.pick !== undefined ||
         values.anniversary !== undefined ||
         values.opened !== undefined ||
-        values.activated !== undefined;
+        values.activated !== undefined ||
+        values.enrolled !== undefined ||
+        values['credit-used'] !== undefined;
     if (command !== 'add' && command !== 'update' && cardOptionsGiven) {
         return usage(`${CLI_NAME} ${command} doesn't take card options.`);
     }
@@ -261,6 +271,23 @@ export async function runWalletCommand(command, argv, io) {
         const n = Number(text.replace(/[$,]/g, ''));
         return Number.isFinite(n) ? n : `--${flag} takes dollars, like 1200.`;
     };
+    if (values.enrolled !== undefined) {
+        input.enrolled = values.enrolled
+            .split(',')
+            .map((r) => r.trim())
+            .filter((r) => r !== '');
+    }
+    if (values['credit-used'] !== undefined) {
+        const used = {};
+        for (const pair of values['credit-used']) {
+            const [credit = '', dollars] = pair.split('=');
+            const n = dollarsFlag('credit-used', dollars);
+            if (credit.trim() === '' || n === undefined || typeof n === 'string')
+                return usage('--credit-used takes <credit>=<dollars>, like lululemon=40.');
+            used[credit.trim()] = n;
+        }
+        input.creditUsed = used;
+    }
     if (values['no-bonus']) {
         input.bonus = null;
     }

package/dist/data/file-store.js

@@ -87,8 +87,11 @@ export class FileWalletStore {
                 return failed(`${purchase.cardId} isn't in the wallet.`);
             const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
             try {
-                if (booked.cap || booked.bonus || booked.milestones.length > 0)
-                    await writeProgress(this.where, booked.cap ? [booked.cap] : [], booked.bonus ? [booked.bonus] : [], booked.milestones);
+                if (booked.cap ||
+                    booked.bonus ||
+                    booked.milestones.length > 0 ||
+                    booked.credit)
+                    await writeProgress(this.where, booked.cap ? [booked.cap] : [], booked.bonus ? [booked.bonus] : [], booked.milestones, booked.credit ? [booked.credit] : []);
             }
             catch (e) {
                 return failed(errorText(e));

package/dist/data/integrity.js

@@ -114,6 +114,7 @@ function cardProblems(card, catalog, merchantIds) {
         ['choice', card.choices.map((c) => c.id)],
         ['milestone', card.milestones.map((m) => m.id)],
         ['intro rate', card.intro_rates.map((i) => i.id)],
+        ['credit', card.credits.map((c) => c.id)],
     ]) {
         for (const id of duplicates(ids))
             problems.push(`${where}: duplicate ${kind} id '${id}'`);
@@ -130,6 +131,16 @@ function cardProblems(card, catalog, merchantIds) {
             if (!card.rules.some((r) => r.id === id))
                 problems.push(`${where} intro rate ${intro.id}: unknown rule '${id}'`);
     }
+    for (const credit of card.credits) {
+        if (card.rules.some((r) => r.id === credit.id) ||
+            card.milestones.some((m) => m.id === credit.id) ||
+            card.intro_rates.some((i) => i.id === credit.id))
+            problems.push(`${where}: credit '${credit.id}' has a rule's id`);
+        for (const c of credit.match.categories ?? [])
+            checkCategory(c, `credit ${credit.id}`);
+        for (const m of credit.match.merchants ?? [])
+            checkMerchant(m, `credit ${credit.id}`);
+    }
     if (card.foreign_transaction_fee === null &&
         !card.todo.some((t) => /foreign transaction fee/i.test(t)))
         problems.push(`${where}: foreign_transaction_fee is null without a todo saying why`);
@@ -147,6 +158,7 @@ function cardProblems(card, catalog, merchantIds) {
         ...card.rules.map((r) => r.id),
         ...card.milestones.map((m) => m.id),
         ...card.intro_rates.map((i) => i.id),
+        ...card.credits.map((c) => c.id),
     ]);
     const sourcePages = new Set(card.source_urls.map((u) => u.split('#')[0]));
     const backed = new Set(card.evidence.map((e) => e.rule));
@@ -249,6 +261,16 @@ export function catalogProblems(catalog) {
                 problems.push(`merchant ${m.id}: booked_via '${via}' is not a merchant`);
         }
     }
+    const all = new Map([...seed, ...overrides].map((m) => [m.id, m]));
+    for (const m of all.values()) {
+        if (m.brand_of === undefined)
+            continue;
+        const parent = all.get(m.brand_of);
+        if (!parent)
+            problems.push(`merchant ${m.id}: brand_of '${m.brand_of}' is not a merchant`);
+        else if (parent.brand_of !== undefined)
+            problems.push(`merchant ${m.id}: brand_of '${m.brand_of}' is itself a brand of '${parent.brand_of}'`);
+    }
     for (const m of catalog.memberships)
         for (const id of m.members_shop_at)
             if (!merchantIds.has(id))

package/dist/data/store.js

@@ -86,7 +86,10 @@ export class JsonWalletStore {
             if (!wallet.cards.some((c) => c.id === purchase.cardId))
                 return failed(`${purchase.cardId} isn't in the wallet.`);
             const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
-            if (booked.cap || booked.bonus || booked.milestones.length > 0)
+            if (booked.cap ||
+                booked.bonus ||
+                booked.milestones.length > 0 ||
+                booked.credit)
                 await this.backend.write(JSON.stringify(booked.wallet));
             return { ok: true, ...booked };
         });

package/dist/data/wallet-edit.js

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { writeFileAtomic } from "./atomic-write.js";
 import { isDeepStrictEqual } from 'node:util';
 import { isMap, isSeq, parseDocument, stringify } from 'yaml';
-import { applyBonusBooking, applyBooking, applyMilestoneBooking, } from "../engine/record.js";
+import { applyBonusBooking, applyBooking, applyCreditBooking, applyMilestoneBooking, } from "../engine/record.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
@@ -40,6 +40,18 @@ function fieldLines(field, f, indent) {
             return f.activated === undefined
                 ? ''
                 : `${indent}activated: ${flowList(f.activated)}\n`;
+        case 'enrolled':
+            return f.enrolled === undefined
+                ? ''
+                : `${indent}enrolled: ${flowList(f.enrolled)}\n`;
+        case 'credit_usage': {
+            if (f.credit_usage === undefined)
+                return '';
+            const entries = Object.entries(f.credit_usage)
+                .map(([key, u]) => `${indent}  ${key}: { period: ${scalar(u.period)}, used: ${String(u.used)} }\n`)
+                .join('');
+            return entries === '' ? '' : `${indent}credit_usage:\n${entries}`;
+        }
         case 'cap_usage': {
             if (f.cap_usage === undefined)
                 return '';
@@ -92,6 +104,8 @@ const FIELDS = [
     'activated',
     'cap_usage',
     'milestone_usage',
+    'enrolled',
+    'credit_usage',
     'bonus',
 ];
 function cardsSeq(text) {
@@ -281,9 +295,9 @@ function setValuationText(text, id, cents) {
     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(period, spent) {
+function flowUsage(period, spent, name = 'spent') {
     const key = /^\d+$/.test(period) ? `"${period}"` : period;
-    return `{ period: ${key}, spent: ${String(spent)} }`;
+    return `{ period: ${key}, ${name}: ${String(spent)} }`;
 }
 // Sets one entry of a card's cap_usage or milestone_usage, adding the map
 // when the card has none.
@@ -324,9 +338,9 @@ function bonusSpentText(text, cardId, spent) {
     const at = afterLine(text, range(bonus)[1] - 1);
     return insertLines(text, at, `${indent}spent: ${value}\n`);
 }
-// Writes spending toward caps, welcome bonuses and spend milestones in one
-// checked write.
-export async function writeProgress(file, caps, bonuses, milestones = []) {
+// Writes spending toward caps, welcome bonuses and spend milestones, and
+// merchant credits used, in one checked write.
+export async function writeProgress(file, caps, bonuses, milestones = [], credits = []) {
     const { text, wallet } = await readWalletText(file);
     if (text === null || wallet === null)
         throw new Error(`No wallet at ${file}.`);
@@ -344,10 +358,15 @@ export async function writeProgress(file, caps, bonuses, milestones = []) {
         after = bonusSpentText(after, b.cardId, b.after);
         expected = applyBonusBooking(expected, b);
     }
+    for (const c of credits) {
+        after = usageText(after, c.cardId, 'credit_usage', c.creditId, flowUsage(c.period, c.after, 'used'));
+        expected = applyCreditBooking(expected, c);
+    }
     const byHand = [
         ...caps.map((b) => `${b.cardId} cap_usage ${b.capKey}: ${flowUsage(b.period, b.after)}`),
         ...bonuses.map((b) => `${b.cardId} bonus spent: ${String(b.after)}`),
         ...milestones.map((m) => `${m.cardId} milestone_usage ${m.milestoneId}: ${flowUsage(m.period, m.after)}`),
+        ...credits.map((c) => `${c.cardId} credit_usage ${c.creditId}: ${flowUsage(c.period, c.after, 'used')}`),
     ].join('; ');
     await commitWalletText(file, after, expected, `add it by hand: ${byHand}`);
 }

package/dist/engine/cheat-sheet.js

@@ -1,12 +1,12 @@
 import { categoryResolution, resolveMerchantById, } from "../merchants/resolve.js";
-import { exploreCards } from "./explore.js";
+import { exploreCards, matchesFilters } from "./explore.js";
 import { bonusStatus } from "./bonus.js";
 import { EPSILON, isClose } from "./compare.js";
 import { periodKey } from "./periods.js";
 import { ABROAD, recommend } from "./recommend.js";
 import { checklist } from "./checklist.js";
 import { setupNotes } from "./setup.js";
-import { capitalize, feeText, listed, money, shortDate } from "./text.js";
+import { capitalize, CREDITS_LEFT_OUT, feeText, listed, money, paymentNote, shortDate, } from "./text.js";
 // The everyday kinds of purchase: the cheat sheet's rows and the site's
 // quick picks.
 export const EVERYDAY_PURCHASES = [
@@ -39,7 +39,7 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
             channel: null,
             date,
             country: 'US',
-        }, merchant);
+        }, merchant, { credits: false });
         // 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;
@@ -101,6 +101,12 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
                 : n.text)),
         ]),
     ];
+    const paying = paymentNote(wallet.cards.flatMap((held) => {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        return card ? [{ name: held.checkout_label ?? card.name, card }] : [];
+    }));
+    if (paying !== null)
+        notes.push(paying);
     const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
     return {
         scope: 'wallet',
@@ -108,6 +114,7 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
         date,
         rows,
         notes,
+        assumptions: [CREDITS_LEFT_OUT],
     };
 }
 const ABROAD_LABEL = 'Abroad';
@@ -121,7 +128,7 @@ function abroadRow(catalog, wallet, date) {
         channel: null,
         date,
         country: ABROAD,
-    }, merchant);
+    }, merchant, { credits: false });
     const top = rec.decision ? rec.ranked[0] : undefined;
     const allCharge = rec.ranked.length > 0 && rec.ranked.every((r) => r.foreignFee !== null);
     return {
@@ -192,6 +199,11 @@ export function catalogCheatSheet(catalog, date, options, items = EVERYDAY_PURCH
         quarter: `${q ?? ''} ${year ?? ''}`,
         date,
         rows,
-        notes: [],
+        notes: [
+            paymentNote(catalog.cards
+                .filter((card) => matchesFilters(card, options.filters))
+                .map((card) => ({ name: card.name, card }))),
+        ].filter((n) => n !== null),
+        assumptions: [CREDITS_LEFT_OUT],
     };
 }

package/dist/engine/checklist.js

@@ -1,11 +1,12 @@
 import { currentPeriodEnd, daysBetween } from "./periods.js";
-import { CAP_PERIODS, choiceName, introEndsText, listed, money, shortDate, wholeDollars, } from "./text.js";
+import { CAP_PERIODS, choiceName, enrollCreditText, introEndsText, listed, money, shortDate, useCreditText, wholeDollars, } from "./text.js";
 import { milestonePays } from "./milestones.js";
 import { optionName } from "./rule-text.js";
 import { activationsDue, walletSummary, } from "./wallet-summary.js";
 // What the wallet's cards need this period, soonest first: bonuses to
 // activate, categories to pick, caps running low, welcome bonuses to finish,
-// and rotating categories the issuer hasn't posted yet.
+// merchant credits to enroll in or use, and rotating categories the issuer
+// 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) {
@@ -93,6 +94,26 @@ shortName) {
                 due: m.until,
             });
         }
+        for (const c of s.credits) {
+            if (!c.enrolled)
+                items.push({
+                    kind: 'enroll',
+                    cardId: card.id,
+                    ref: c.id,
+                    text: enrollCreditText(name, c.name),
+                    due: null,
+                });
+            // One that needs no enrolling shows once the cardholder uses it, so a
+            // card's every credit isn't a to-do for someone who never shops there.
+            else if (c.left !== null && c.left > 0 && (c.enroll || c.tracked))
+                items.push({
+                    kind: 'credit',
+                    cardId: card.id,
+                    ref: c.id,
+                    text: useCreditText(name, c, c.left),
+                    due: c.until,
+                });
+        }
         const b = s.bonus;
         if (b?.state === 'open' && b.remaining !== null && b.deadline !== null) {
             const weeks = Math.max(1, (b.daysLeft ?? 7) / 7);
@@ -127,7 +148,7 @@ shortName) {
         a.cardId.localeCompare(b.cardId));
 }
 // An all-day calendar event for each dated action (activations, picks,
-// welcome-bonus deadlines), with a reminder two days before. Built on the
+// welcome-bonus deadlines, credits to use), with a reminder two days before. Built on the
 // device: nothing is sent anywhere.
 export function checklistCalendar(items, stamp) {
     const escape = (t) => t.replace(/\\/g, '\\\\').replace(/[,;]/g, (c) => `\\${c}`);
@@ -149,7 +170,7 @@ export function checklistCalendar(items, stamp) {
         const due = i.due ?? '';
         return [
             'BEGIN:VEVENT',
-            `UID:${i.kind}-${i.cardId}-${due}@earnrate.dev`,
+            `UID:${i.kind}-${i.cardId}${i.ref === undefined ? '' : `-${i.ref}`}-${due}@earnrate.dev`,
             `DTSTAMP:${stamp}`,
             `DTSTART;VALUE=DATE:${day(due)}`,
             `DTEND;VALUE=DATE:${day(next(due))}`,

package/dist/engine/credits.js

@@ -0,0 +1,65 @@
+import { merchantFamily } from "../merchants/resolve.js";
+import { categoryMatches } from "./evaluate.js";
+import { periodEnd, periodKey } from "./periods.js";
+import { creditName } from "./rule-text.js";
+import { roundCents } from "./text.js";
+// Only a store itself has a credit: a search for a kind of purchase
+// ("clothing") never does.
+// A credit naming a merchant also covers its brands (Hilton's covers Hampton).
+export function creditCovers(catalog, credit, merchant) {
+    if (merchant.source === 'category' || merchant.source === 'none')
+        return false;
+    const named = credit.match.merchants;
+    if (named)
+        return merchantFamily(catalog, merchant.merchantId).some((id) => named.includes(id));
+    return (credit.match.categories ?? []).some((c) => categoryMatches(c, merchant.category));
+}
+// A credit that needs enrolling counts only once the wallet says it's done.
+export const isEnrolled = (credit, held) => credit.enroll !== true || (held.enrolled ?? []).includes(credit.id);
+export function creditState(catalog, credit, held, date) {
+    const anniversary = held.anniversary ?? null;
+    const period = periodKey(credit.period, date, anniversary);
+    const usage = held.credit_usage?.[credit.id];
+    const used = period !== null && usage !== undefined && usage.period === period
+        ? usage.used
+        : 0;
+    return {
+        credit,
+        key: period,
+        name: creditName(catalog, credit),
+        amount: credit.amount,
+        period: credit.period,
+        enrolled: isEnrolled(credit, held),
+        used,
+        left: period === null ? null : roundCents(Math.max(0, credit.amount - used)),
+        until: period === null ? null : periodEnd(credit.period, period, anniversary),
+    };
+}
+export const creditStates = (catalog, card, held, date) => card.credits.map((c) => creditState(catalog, c, held, date));
+export const counts = (s) => s.enrolled && s.left !== null && s.left > 0;
+// The card's credit at this merchant, if any: one that counts first, then
+// the one with the most left.
+export function creditAt(catalog, card, held, merchant, date) {
+    const here = card.credits
+        .filter((c) => creditCovers(catalog, c, merchant))
+        .map((c) => creditState(catalog, c, held, date))
+        .sort((a, b) => Number(counts(b)) - Number(counts(a)) || (b.left ?? 0) - (a.left ?? 0));
+    return here[0] ?? null;
+}
+// Dollars back on a purchase: null without an amount, 0 when the credit
+// doesn't count (not enrolled, or used up).
+export function creditDollars(s, amount) {
+    if (amount === null)
+        return null;
+    if (!counts(s) || amount <= 0)
+        return 0;
+    return roundCents(Math.min(amount, s.left ?? 0));
+}
+const PER_YEAR = {
+    month: 12,
+    quarter: 4,
+    half_year: 2,
+    calendar_year: 1,
+    cardmember_year: 1,
+};
+export const creditPerYear = (c) => c.amount * PER_YEAR[c.period];

package/dist/engine/evaluate.js

@@ -1,17 +1,23 @@
+import { merchantFamily } from "../merchants/resolve.js";
+import { EPSILON } from "./compare.js";
 import { introCovers, introWindows, withIntro, } from "./intro.js";
 import { inEffect, periodKey } from "./periods.js";
+// PayPal checkout happens online, so paying through it says the channel.
+export const paymentChannel = (channel, payment) => channel ?? (payment === 'paypal' ? 'online' : null);
 export function purchaseContext(catalog, wallet, merchant, category, purchase) {
+    const payment = purchase.payment ?? null;
     return {
         category,
-        merchantId: merchant.merchantId,
+        merchantIds: merchantFamily(catalog, merchant.merchantId),
         mcc: category === merchant.category && merchant.likelyMcc !== null
             ? merchant.likelyMcc
             : singleMcc(catalog, category),
-        channel: merchant.channel,
+        channel: paymentChannel(merchant.channel, payment),
         country: purchase.country,
         date: purchase.date,
         amount: purchase.amount,
         memberships: new Set(wallet.memberships),
+        payment,
     };
 }
 // A category with one typical MCC (travel agencies are 4722) implies it, the
@@ -79,18 +85,16 @@ export function isActivated(card, held, ruleId) {
 function applicability(card, rule, ctx, held, picked) {
     const { match, exclude } = rule;
     const inCategory = (cats) => cats.some((c) => categoryMatches(c, ctx.category));
+    const named = (ids) => ids?.some((id) => ctx.merchantIds.includes(id)) ?? false;
     if (match.categories?.length && !inCategory(match.categories))
         return 'no';
-    if (match.merchants?.length &&
-        !(ctx.merchantId !== null && match.merchants.includes(ctx.merchantId))) {
+    if (match.merchants?.length && !named(match.merchants))
         return 'no';
-    }
     if (match.mccs?.length && !(ctx.mcc !== null && match.mccs.includes(ctx.mcc)))
         return 'no';
     if (match.choice !== undefined) {
         const covered = picked.get(match.choice);
-        const merchantPicked = ctx.merchantId !== null &&
-            (covered?.merchants.includes(ctx.merchantId) ?? false);
+        const merchantPicked = named(covered?.merchants);
         const onlinePicked = ctx.channel === 'online' &&
             (covered?.online.some((o) => !inCategory(o.exclude)) ?? false);
         if (!merchantPicked &&
@@ -100,13 +104,14 @@ function applicability(card, rule, ctx, held, picked) {
     }
     if (exclude?.categories && inCategory(exclude.categories))
         return 'no';
-    if (exclude?.merchants &&
-        ctx.merchantId !== null &&
-        exclude.merchants.includes(ctx.merchantId)) {
+    if (named(exclude?.merchants))
         return 'no';
-    }
     if (exclude?.mccs && ctx.mcc !== null && exclude.mccs.includes(ctx.mcc))
         return 'no';
+    if (exclude?.payment &&
+        ctx.payment !== null &&
+        exclude.payment.includes(ctx.payment))
+        return 'no';
     if (rule.channel !== 'any' && rule.channel !== ctx.channel)
         return 'no';
     if (rule.geography === 'us_only' && ctx.country !== 'US')
@@ -118,6 +123,9 @@ function applicability(card, rule, ctx, held, picked) {
     const membership = rule.requires?.membership;
     if (membership !== undefined && !ctx.memberships.has(membership))
         return 'no';
+    const payment = rule.requires?.payment;
+    if (payment !== undefined && ctx.payment !== payment)
+        return 'no';
     if (rule.requires?.activation && !isActivated(card, held, rule.id))
         return 'needs-activation';
     return 'applies';
@@ -222,3 +230,22 @@ export function evaluateCard(card, held, ctx) {
         staleChoice,
     };
 }
+// The way of paying (one a rule on the card requires) that would earn the
+// most on this purchase, when that beats `rate`. Only while the purchase
+// doesn't say how it's paid.
+export function paymentUpgrade(card, held, ctx, rate) {
+    if (ctx.payment !== null)
+        return null;
+    let best = null;
+    const methods = new Set(card.rules.flatMap((r) => r.requires?.payment === undefined ? [] : [r.requires.payment]));
+    for (const payment of methods) {
+        const paid = evaluateCard(card, held, {
+            ...ctx,
+            payment,
+            channel: paymentChannel(ctx.channel, payment),
+        }).best;
+        if (paid.rate > (best?.rate ?? rate) + EPSILON)
+            best = { payment, rate: paid.rate, nominalRate: paid.nominalRate };
+    }
+    return best;
+}