earnrate 0.2.11 → 0.2.13

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,16 +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
@@ -78,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 &&
@@ -99,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')
@@ -117,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';
@@ -167,10 +176,16 @@ function beats(a, aRate, b, bRate) {
 }
 export function evaluateCard(card, held, ctx) {
     const { picked, staleChoice } = pickedCategories(card, held, ctx.date);
+    const windows = introWindows(card, held, ctx.date);
+    const introFor = (ruleId) => windows.filter((w) => introCovers(w.intro, ruleId));
+    const rateOf = (rule) => withIntro(rule.rate, rule.id, windows);
+    const baseRate = withIntro(card.base_rate, null, windows);
     const base = {
         rule: null,
-        nominalRate: card.base_rate,
-        rate: card.base_rate,
+        nominalRate: baseRate,
+        standardRate: card.base_rate,
+        intro: introFor(null),
+        rate: baseRate,
         cap: null,
         afterCap: null,
     };
@@ -187,14 +202,19 @@ export function evaluateCard(card, held, ctx) {
         else
             applying.push(rule);
     }
-    const uncapped = Math.max(card.base_rate, ...applying.filter((r) => r.cap === undefined).map((r) => r.rate));
+    const uncapped = Math.max(baseRate, ...applying.filter((r) => r.cap === undefined).map(rateOf));
     for (const rule of applying) {
         const cap = capState(rule, card, held, ctx.date);
-        const afterCap = cap ? Math.max(cap.cap.then_rate, uncapped) : null;
+        const rate = rateOf(rule);
+        const afterCap = cap
+            ? Math.max(withIntro(cap.cap.then_rate, rule.id, windows, true), uncapped)
+            : null;
         const earning = {
             rule,
-            nominalRate: rule.rate,
-            rate: rateAfterCap(rule.rate, cap, afterCap ?? rule.rate, ctx.amount),
+            nominalRate: rate,
+            standardRate: rule.rate,
+            intro: introFor(rule.id),
+            rate: rateAfterCap(rate, cap, afterCap ?? rate, ctx.amount),
             cap,
             afterCap,
         };
@@ -206,7 +226,26 @@ export function evaluateCard(card, held, ctx) {
     return {
         best,
         nominal,
-        needsActivation: blocked.filter((r) => r.rate > best.rate),
+        needsActivation: blocked.filter((r) => rateOf(r) > best.rate),
         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;
+}

package/dist/engine/explore.js

@@ -1,12 +1,14 @@
 import { categoryResolution, resolvePlace } from "../merchants/resolve.js";
-import { evaluateCard, purchaseContext } from "./evaluate.js";
+import { creditCovers, creditPerYear } from "./credits.js";
+import { evaluateCard, paymentUpgrade, purchaseContext } from "./evaluate.js";
+import { creditName } from "./rule-text.js";
 import { membershipName, membershipNeeded, paidMemberships, } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { FOREIGN_ASSUMPTION, isForeign, recommend } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
 import { optionName } from "./rule-text.js";
-import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, earnText, listed, money, PICK_PERIODS, pointValuesText, } from "./text.js";
+import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, creditBack, creditThen, earnText, listed, money, PAYMENT_PHRASES, paidText, paymentUnknownText, PICK_PERIODS, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
@@ -163,11 +165,13 @@ export function exploreCards(catalog, query, options, resolved) {
         channel: query.channel,
         date: query.date,
         country: query.country ?? 'US',
+        payment: query.payment ?? null,
     };
     const ranked = [];
+    const ifPaid = new Map();
     const excluded = [];
     // A Costco purchase means a Costco member: no membership to point out.
-    const paid = paidMemberships(catalog, {
+    const members = paidMemberships(catalog, {
         memberships: options.memberships,
         merchantIds: [merchant.merchantId],
     });
@@ -177,7 +181,9 @@ export function exploreCards(catalog, query, options, resolved) {
         const picks = bestPicksForPurchase(catalog, card, merchant, purchase, options);
         const held = idealHolding(card, query.date, picks);
         const wallet = walletOf(held, options);
-        const rec = recommend(catalog, wallet, purchase, merchant);
+        const rec = recommend(catalog, wallet, purchase, merchant, {
+            credits: false,
+        });
         const top = rec.ranked[0];
         if (!top) {
             excluded.push(...rec.excluded);
@@ -185,6 +191,16 @@ export function exploreCards(catalog, query, options, resolved) {
         }
         const requirements = requirementsFor(catalog, card, held, wallet, merchant, purchase);
         const gap = rotationGap(card, query.date);
+        const paid = paymentUpgrade(card, held, purchaseContext(catalog, wallet, merchant, merchant.category, purchase), top.rate);
+        if (paid)
+            ifPaid.set(card.id, {
+                payment: paid.payment,
+                earn: earnText(catalog, paid.nominalRate, top.currency),
+                standard: earnText(catalog, top.rate, top.currency),
+                returnPct: paid.rate * top.centsPerUnit - (top.foreignFee ?? 0),
+            });
+        const payment = card.rules.find((r) => r.id === top.matchedRule)?.requires
+            ?.payment;
         const evidenceRule = top.matchedRule ?? 'base_rate';
         const evidence = card.evidence.find((e) => e.rule === evidenceRule);
         ranked.push({
@@ -203,7 +219,8 @@ export function exploreCards(catalog, query, options, resolved) {
             requirements,
             conditions: [
                 ...conditionsText(catalog, card, requirements),
-                ...membershipNeeded(catalog, card, paid),
+                ...(payment === undefined ? [] : [`Paid ${PAYMENT_PHRASES[payment]}.`]),
+                ...membershipNeeded(catalog, card, members),
             ],
             evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
             withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
@@ -212,13 +229,48 @@ export function exploreCards(catalog, query, options, resolved) {
     ranked.sort(compareExplored);
     return {
         merchant,
+        credits: creditPicks(catalog, merchant, ranked),
         ranked,
         excluded,
-        assumptions: exploreAssumptions(catalog, merchant, ranked, options, purchase),
+        assumptions: exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid),
         warnings: exploreWarnings(catalog, merchant),
     };
 }
-function exploreAssumptions(catalog, merchant, ranked, options, purchase) {
+function creditPicks(catalog, merchant, ranked) {
+    const picks = ranked.flatMap((entry) => {
+        const card = catalog.cards.find((c) => c.id === entry.cardId);
+        return ((card?.credits ?? [])
+            // A credit for a whole category (every restaurant) isn't a store's.
+            .filter((c) => c.match.merchants !== undefined &&
+            creditCovers(catalog, c, merchant))
+            .map((credit) => {
+            const earn = earnText(catalog, entry.rate, entry.currency);
+            const evidence = card?.evidence.find((e) => e.rule === credit.id);
+            return {
+                cardId: entry.cardId,
+                cardName: entry.cardName,
+                issuer: entry.issuer,
+                network: entry.network,
+                annualFee: entry.annualFee,
+                firstYearFee: entry.firstYearFee,
+                creditId: credit.id,
+                name: creditName(catalog, credit),
+                amount: credit.amount,
+                period: credit.period,
+                enroll: credit.enroll === true,
+                note: credit.note ?? null,
+                back: creditBack(credit),
+                earn,
+                text: creditThen(credit, earn),
+                evidence: evidence
+                    ? { quote: evidence.quote, url: evidence.url }
+                    : null,
+            };
+        }));
+    });
+    return picks.sort((a, b) => creditPerYear(b) - creditPerYear(a) || a.cardId.localeCompare(b.cardId));
+}
+function exploreAssumptions(catalog, merchant, ranked, options, purchase, ifPaid) {
     const assumptions = [];
     if (merchant.source === 'category') {
         assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
@@ -235,6 +287,17 @@ function exploreAssumptions(catalog, merchant, ranked, options, purchase) {
         assumptions.push(values);
     if (isForeign(purchase))
         assumptions.push(FOREIGN_ASSUMPTION);
+    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;
+        assumptions.push(paymentUnknownText(entry.cardName, paid.payment, paid.earn, paid.standard));
+    }
     return assumptions;
 }
 function exploreWarnings(catalog, merchant) {

package/dist/engine/intro.js

@@ -0,0 +1,36 @@
+export function addDays(date, days) {
+    const t = new Date(`${date}T00:00:00Z`);
+    t.setUTCDate(t.getUTCDate() + days);
+    return t.toISOString().slice(0, 10);
+}
+// Never assumed: a card without a date is ranked at its standard rates.
+export const openedOn = (held) => held.opened ?? held.bonus?.opened ?? null;
+// The opening day is day 1, so 365 days run through the day before the first
+// anniversary.
+export const introUntil = (intro, opened) => addDays(opened, intro.days - 1);
+// The card's intro rates in effect on `date`.
+export function introWindows(card, held, date) {
+    const opened = openedOn(held);
+    if (opened === null || date < opened)
+        return [];
+    return card.intro_rates.flatMap((intro) => {
+        const until = introUntil(intro, opened);
+        return date <= until ? [{ intro, until }] : [];
+    });
+}
+// Whether an intro rate changes this rule's rate (null: the base rate). Past
+// a cap only a whole-card intro applies.
+export const introCovers = (intro, ruleId, pastCap = false) => intro.rules === undefined ||
+    (!pastCap && ruleId !== null && intro.rules.includes(ruleId));
+export function withIntro(rate, ruleId, windows, pastCap = false) {
+    let out = rate;
+    for (const { intro } of windows) {
+        if (!introCovers(intro, ruleId, pastCap))
+            continue;
+        out =
+            intro.multiply !== undefined
+                ? out * intro.multiply
+                : out + (intro.add ?? 0);
+    }
+    return out;
+}

package/dist/engine/offers.js

@@ -2,7 +2,7 @@ import { bonusDollars } from "./bonus.js";
 import { matchesFilters } from "./explore.js";
 import { membershipCosts, paidMemberships } from "./memberships.js";
 import { inEffect } from "./periods.js";
-import { money, roundCents } from "./text.js";
+import { CREDITS_LEFT_OUT, money, roundCents } from "./text.js";
 import { cardValuation } from "./valuation.js";
 function ineligibleText(catalog, wallet, notWith) {
     const held = wallet.cards
@@ -83,6 +83,7 @@ export function compareOffers(catalog, wallet, filters, today) {
         `Compares the ${String(catalog.cards.length)} cards earnrate knows, not every card on the market.`,
         `Each offer is the public one on the issuer's page on the date shown, checked weekly. ${OFFERS_MAY_DIFFER} Issuers also limit who can get a bonus; each card's note says how.`,
         "First-year value is the bonus at your point values minus the first year's annual fee and any membership the card needs that you don't have. It leaves out what the card earns on your spending and any credits or perks.",
+        CREDITS_LEFT_OUT,
     ];
     return { offers, withoutOffer, notes };
 }

package/dist/engine/periods.js

@@ -1,6 +1,7 @@
-// Keys match the wallet's PeriodKey format: "2026" or "2026-Q4". A cardmember
-// year is keyed by the calendar year it started in. Returns null when a
-// cardmember year is asked for without an anniversary (MM-DD).
+// Keys match the wallet's PeriodKey format: "2026", "2026-Q4" or "2026-H2"
+// (July to December). A cardmember year is keyed by the calendar year it
+// started in. Returns null when a cardmember year is asked for without an
+// anniversary (MM-DD).
 export function periodKey(period, date, anniversary) {
     const year = Number(date.slice(0, 4));
     const month = Number(date.slice(5, 7));
@@ -11,6 +12,8 @@ export function periodKey(period, date, anniversary) {
             return String(year);
         case 'quarter':
             return `${String(year)}-Q${String(Math.floor((month - 1) / 3) + 1)}`;
+        case 'half_year':
+            return `${String(year)}-H${month <= 6 ? '1' : '2'}`;
         case 'cardmember_year':
             if (anniversary === null)
                 return null;
@@ -57,6 +60,10 @@ export function periodEnd(period, key, anniversary) {
             const q = /^(\d{4})-Q([1-4])$/.exec(key);
             return q ? utcDay(Number(q[1]), Number(q[2]) * 3 + 1, 0) : null;
         }
+        case 'half_year': {
+            const h = /^(\d{4})-H([12])$/.exec(key);
+            return h ? utcDay(Number(h[1]), Number(h[2]) * 6 + 1, 0) : null;
+        }
         case 'calendar_year':
             return /^\d{4}$/.test(key) ? `${key}-12-31` : null;
         case 'cardmember_year': {