earnrate 0.2.10 → 0.2.12

package/dist/cli/import.js

@@ -13,7 +13,7 @@ import { cardValuation } from "../engine/valuation.js";
 import { analyzeStatement, } from "../import/analyze.js";
 import { parseStatement } from "../import/statement.js";
 import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
-import { currencyName, dollarsAndCents } from "../engine/text.js";
+import { currencyName, dollarsAndCents, periodPhrase } from "../engine/text.js";
 const IMPORT_HELP = `Usage: ${CLI_NAME} import <statement.csv> --card <card-id> [--apply]
        ${CLI_NAME} import <statement.csv>:<card-id> [<statement.csv>:<card-id> ...]
 
@@ -133,7 +133,7 @@ function formatAnalysis(a, labelOf, valuation, categoryName) {
         out.push(`Welcome bonus on ${labelOf(b.cardId)}: ${dollarsAndCents(b.before)} → ${dollarsAndCents(b.after)} of ${dollarsAndCents(b.spend)}${b.deadline ? ` by ${b.deadline}` : ''}.`);
     }
     for (const m of a.milestones) {
-        out.push(`Spend bonus on ${labelOf(m.cardId)}: ${dollarsAndCents(m.before)} → ${dollarsAndCents(m.after)} of ${dollarsAndCents(m.spend)} for ${m.period}${m.before < m.spend && m.after >= m.spend ? ', reached' : ''}.`);
+        out.push(`Spend bonus on ${labelOf(m.cardId)}: ${dollarsAndCents(m.before)} → ${dollarsAndCents(m.after)} of ${dollarsAndCents(m.spend)} ${periodPhrase(m.periodKind, m.period)}${m.before < m.spend && m.after >= m.spend ? ', reached' : ''}.`);
     }
     return `${out.join('\n')}\n`;
 }

package/dist/cli/wallet.js

@@ -14,6 +14,9 @@ const CARD_OPTIONS = `Options:
                              --pick five-percent=fast-food,movie-theaters.
                              Repeat for each choice.
   --anniversary <MM-DD>      Account anniversary, for caps that reset on it.
+  --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.
   --activated <rules>        Rules you've activated with the issuer, comma
                              separated. Replaces the current list.
   --bonus-opened <date>      Track a welcome bonus: the day the account opened
@@ -44,7 +47,7 @@ ${CARD_OPTIONS}
     update: `Usage: ${CLI_NAME} update <card-id> [options]
 
 Changes a card in your wallet: picks for this period, label, anniversary,
-activations or welcome bonus. Picks for the current period are merged with
+opening date, activations or welcome bonus. Picks for the current period are merged with
 ones already set.
 
 ${CARD_OPTIONS}
@@ -130,6 +133,7 @@ export async function runWalletCommand(command, argv, io) {
                 label: { type: 'string' },
                 pick: { type: 'string', multiple: true },
                 anniversary: { type: 'string' },
+                opened: { type: 'string' },
                 activated: { type: 'string' },
                 'bonus-opened': { type: 'string' },
                 'bonus-spent': { type: 'string' },
@@ -158,6 +162,7 @@ export async function runWalletCommand(command, argv, io) {
     const cardOptionsGiven = values.label !== undefined ||
         values.pick !== undefined ||
         values.anniversary !== undefined ||
+        values.opened !== undefined ||
         values.activated !== undefined;
     if (command !== 'add' && command !== 'update' && cardOptionsGiven) {
         return usage(`${CLI_NAME} ${command} doesn't take card options.`);
@@ -236,6 +241,8 @@ export async function runWalletCommand(command, argv, io) {
         input.checkoutLabel = values.label;
     if (values.anniversary !== undefined)
         input.anniversary = values.anniversary;
+    if (values.opened !== undefined)
+        input.opened = values.opened;
     if (values.activated !== undefined) {
         input.activated = values.activated
             .split(',')

package/dist/data/integrity.js

@@ -1,3 +1,4 @@
+import { resolveMerchant } from "../merchants/resolve.js";
 import { WALLET_VERSION } from "../schema/wallet.js";
 function duplicates(ids) {
     const seen = new Set();
@@ -38,6 +39,31 @@ function merchantProblems(file, merchants, categories) {
     }
     return problems;
 }
+// Overrides are searched before seed, and a known name followed by more words
+// still matches it, so a name can be taken by another merchant without ever
+// being listed twice.
+function lookupProblems(catalog) {
+    const problems = [];
+    const { seed, overrides } = catalog.merchants;
+    for (const m of [...overrides, ...seed]) {
+        for (const key of [m.name, ...m.aliases, ...m.domains]) {
+            const found = resolveMerchant(catalog, key, null).merchantId;
+            if (found !== m.id)
+                problems.push(`merchant ${m.id}: '${key}' resolves to ${found ?? 'no merchant'}`);
+        }
+    }
+    for (const c of catalog.categories)
+        for (const word of new Set([
+            c.name,
+            ...c.aliases,
+            c.id.replace(/[._]/g, ' '),
+        ])) {
+            const found = resolveMerchant(catalog, word, null).merchantId;
+            if (found !== null)
+                problems.push(`category ${c.id}: '${word}' resolves to ${found}`);
+        }
+    return problems;
+}
 function cardProblems(card, catalog, merchantIds) {
     const where = `card ${card.id}`;
     const problems = [];
@@ -87,6 +113,7 @@ function cardProblems(card, catalog, merchantIds) {
         ['cap', card.caps.map((c) => c.id)],
         ['choice', card.choices.map((c) => c.id)],
         ['milestone', card.milestones.map((m) => m.id)],
+        ['intro rate', card.intro_rates.map((i) => i.id)],
     ]) {
         for (const id of duplicates(ids))
             problems.push(`${where}: duplicate ${kind} id '${id}'`);
@@ -95,6 +122,14 @@ function cardProblems(card, catalog, merchantIds) {
     for (const m of card.milestones)
         if (card.rules.some((r) => r.id === m.id))
             problems.push(`${where}: milestone '${m.id}' has a rule's id`);
+    for (const intro of card.intro_rates) {
+        if (card.rules.some((r) => r.id === intro.id) ||
+            card.milestones.some((m) => m.id === intro.id))
+            problems.push(`${where}: intro rate '${intro.id}' has a rule's id`);
+        for (const id of intro.rules ?? [])
+            if (!card.rules.some((r) => r.id === id))
+                problems.push(`${where} intro rate ${intro.id}: unknown rule '${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`);
@@ -111,6 +146,7 @@ function cardProblems(card, catalog, merchantIds) {
         ...(card.requires_membership ? ['requires_membership'] : []),
         ...card.rules.map((r) => r.id),
         ...card.milestones.map((m) => m.id),
+        ...card.intro_rates.map((i) => i.id),
     ]);
     const sourcePages = new Set(card.source_urls.map((u) => u.split('#')[0]));
     const backed = new Set(card.evidence.map((e) => e.rule));
@@ -205,6 +241,7 @@ export function catalogProblems(catalog) {
     const { seed, overrides } = catalog.merchants;
     problems.push(...merchantProblems('seed', seed, categories));
     problems.push(...merchantProblems('overrides', overrides, categories));
+    problems.push(...lookupProblems(catalog));
     const merchantIds = new Set([...seed, ...overrides].map((m) => m.id));
     for (const m of [...seed, ...overrides]) {
         for (const via of m.booked_via) {

package/dist/data/wallet-edit.js

@@ -31,7 +31,8 @@ const flowList = (ids) => `[${ids.join(', ')}]`;
 function fieldLines(field, f, indent) {
     switch (field) {
         case 'checkout_label':
-        case 'anniversary': {
+        case 'anniversary':
+        case 'opened': {
             const value = f[field];
             return value == null ? '' : `${indent}${field}: ${scalar(value)}\n`;
         }
@@ -86,6 +87,7 @@ function fieldLines(field, f, indent) {
 const FIELDS = [
     'checkout_label',
     'anniversary',
+    'opened',
     'chosen',
     'activated',
     'cap_usage',

package/dist/engine/cheat-sheet.js

@@ -20,6 +20,9 @@ export const EVERYDAY_PURCHASES = [
     { label: 'Drugstores', category: 'drugstore' },
     { label: 'Everything else', category: 'other' },
 ];
+// What a quick pick searches for: "Streaming (Netflix)" searches "Netflix",
+// since streaming bonuses follow each issuer's list of services.
+export const quickPickText = (item) => /\((.+)\)$/.exec(item.label)?.[1] ?? item.label;
 // The best card in the wallet for each everyday kind of purchase on `date`,
 // with caps, picks and activations as the wallet has them.
 export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {

package/dist/engine/checklist.js

@@ -1,5 +1,5 @@
 import { currentPeriodEnd, daysBetween } from "./periods.js";
-import { CAP_PERIODS, choiceName, listed, money, shortDate, wholeDollars, } from "./text.js";
+import { CAP_PERIODS, choiceName, introEndsText, listed, money, shortDate, wholeDollars, } from "./text.js";
 import { milestonePays } from "./milestones.js";
 import { optionName } from "./rule-text.js";
 import { activationsDue, walletSummary, } from "./wallet-summary.js";
@@ -18,12 +18,12 @@ shortName) {
         const name = s.checkoutLabel ?? shortName?.(card.id) ?? s.cardName;
         for (const a of activationsDue(catalog, card, held, today)) {
             const starts = a.from !== null && a.from > today
-                ? `, starting ${shortDate(a.from)}`
+                ? ` (it starts ${shortDate(a.from)})`
                 : '';
             items.push({
                 kind: 'activate',
                 cardId: card.id,
-                text: `Activate ${name}'s bonus on ${a.what}${starts}${a.activateBy === null ? '' : `, by ${shortDate(a.activateBy)}`}.`,
+                text: `Activate ${name}'s bonus ${a.preposition} ${a.what}${a.activateBy === null ? '' : ` by ${shortDate(a.activateBy)}`}${starts}.`,
                 due: a.activateBy ?? (a.from !== null && a.from > today ? a.from : a.to),
             });
         }
@@ -103,6 +103,17 @@ shortName) {
                 due: b.deadline,
             });
         }
+        const quarterEnd = currentPeriodEnd('quarter', today, null);
+        if (s.intro?.state === 'active' &&
+            s.intro.until !== null &&
+            quarterEnd !== null &&
+            s.intro.until <= quarterEnd)
+            items.push({
+                kind: 'intro',
+                cardId: card.id,
+                text: introEndsText(name, s.intro.days, s.intro.until),
+                due: s.intro.until,
+            });
         if (s.rotationGap !== null) {
             items.push({
                 kind: 'rotation',

package/dist/engine/evaluate.js

@@ -1,3 +1,4 @@
+import { introCovers, introWindows, withIntro, } from "./intro.js";
 import { inEffect, periodKey } from "./periods.js";
 export function purchaseContext(catalog, wallet, merchant, category, purchase) {
     return {
@@ -167,10 +168,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 +194,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 +218,7 @@ 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,
     };
 }

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/recommend.js

@@ -1,13 +1,14 @@
 import { findMerchant, resolveMerchant, resolveMerchantById, } from "../merchants/resolve.js";
 import { bonusStatus } from "./bonus.js";
 import { evaluateCard, purchaseContext, usableAt, } from "./evaluate.js";
+import { openedOn } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestonePoints, milestonesReached, reachedText, } from "./milestones.js";
 import { daysBetween } from "./periods.js";
 import { ruleWhat } from "./rule-text.js";
 import { rotationGap } from "./rotation.js";
 import { EPSILON, isClose } from "./compare.js";
-import { CAP_ADJECTIVES, categoryPhrase, codesAs, currencyLabel, currencyName, earnText, listed, money, NETWORK_NAMES, num, pct, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.js";
+import { CAP_ADJECTIVES, categoryPhrase, codesAs, currencyLabel, currencyName, earnText, introRateText, introUnknownText, listed, money, NETWORK_NAMES, num, pct, pointValuesText, roundCents, shortDate, wholeDollars, } from "./text.js";
 import { cardValuation } from "./valuation.js";
 export const STALE_AFTER_DAYS = 180;
 // The engine only tells the U.S. from everywhere else.
@@ -79,6 +80,18 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
             (bonusPoints > 0 && purchase.amount ? bonusPoints / purchase.amount : 0);
         // An unknown fee isn't guessed: it's warned about instead.
         const fee = isForeign(purchase) ? (card.foreign_transaction_fee ?? 0) : 0;
+        const fresh = card.intro_rates.length > 0 && openedOn(held) === null
+            ? evaluateCard(card, { ...held, opened: purchase.date }, ctx).best
+            : null;
+        const ifNew = fresh && fresh.rate > evaluation.best.rate + EPSILON
+            ? {
+                rate: fresh.nominalRate,
+                returnPct: (perDollar - evaluation.best.rate + fresh.rate) *
+                    valuation.centsPerUnit -
+                    fee,
+                days: (fresh.intro[0]?.intro ?? card.intro_rates[0])?.days ?? 365,
+            }
+            : null;
         entries.push({
             card,
             held,
@@ -90,6 +103,7 @@ function rankEntries(catalog, wallet, purchase, merchant, category) {
             effectiveReturnPct: perDollar * valuation.centsPerUnit - fee,
             rateReturnPct: evaluation.best.rate * valuation.centsPerUnit - fee,
             upside: perDollar * (valuation.range?.[1] ?? valuation.centsPerUnit) - fee,
+            ifNew,
         });
     }
     entries.sort(compareEntries);
@@ -105,7 +119,12 @@ function reasoningFor(catalog, wallet, entry, amount) {
         lines.push(`${earnText(catalog, best.nominalRate, currency)} on ${ruleWhat(catalog, best.rule)}${best.rule.requires?.membership === undefined ? '' : `, with ${membershipName(catalog, best.rule.requires.membership)}`}.${note}`);
     }
     else {
-        lines.push(`${earnText(catalog, card.base_rate, currency)}, its base rate. No bonus category applies here.`);
+        lines.push(`${earnText(catalog, best.nominalRate, currency)}, its base rate. No bonus category applies here.`);
+    }
+    const [intro] = best.intro;
+    if (intro) {
+        const note = intro.intro.note ? ` ${intro.intro.note}` : '';
+        lines.push(`${introRateText(earnText(catalog, best.nominalRate, currency), earnText(catalog, best.standardRate, currency), intro.intro.days, intro.until)}${note}`);
     }
     const cap = best.cap;
     if (cap && amount !== null && amount > cap.remaining) {
@@ -133,7 +152,7 @@ function warningsFor(catalog, entry, purchase) {
     const { best, nominal } = evaluation;
     const warnings = [];
     if (entry.fee > 0)
-        warnings.push(`Charges a ${pct(entry.fee)} foreign transaction fee here, so it nets ${pct(entry.effectiveReturnPct)}.`);
+        warnings.push(`Charges a ${pct(entry.fee)} foreign transaction fee here, so it nets ${pct(entry.rateReturnPct)}.`);
     if (isForeign(purchase) && card.foreign_transaction_fee === null)
         warnings.push("Its foreign transaction fee isn't on file, so none is subtracted. Check the issuer's terms before using it abroad.");
     const capLabel = (e) => e.cap
@@ -220,7 +239,7 @@ function tieNote(entries) {
             tied.some((e) => e.evaluation.best.cap !== null)
             ? 'because its rate has no cap'
             : 'by a fixed order; either works';
-    return `${names} also ${verb} ${pct(winner.effectiveReturnPct)} here. ${displayName(winner)} wins the tie ${why}.`;
+    return `${names} also ${verb} ${pct(winner.rateReturnPct)} here. ${displayName(winner)} wins the tie ${why}.`;
 }
 // Finds the closest point inside a currency's value range where the winner
 // stops winning, varying one currency at a time. Returns are linear in the
@@ -299,6 +318,16 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
         assumptions.push(values);
     if (isForeign(purchase))
         assumptions.push(FOREIGN_ASSUMPTION);
+    const winner = entries[0];
+    for (const e of entries) {
+        if (!e.ifNew || !winner)
+            continue;
+        if (e !== winner &&
+            e.ifNew.returnPct <= winner.effectiveReturnPct + EPSILON)
+            continue;
+        const currency = e.valuation.currency;
+        assumptions.push(introUnknownText(displayName(e), earnText(catalog, e.ifNew.rate, currency), earnText(catalog, e.evaluation.best.nominalRate, currency), e.ifNew.days));
+    }
     for (const e of entries)
         for (const hit of e.milestones)
             assumptions.push(`Counts the ${money(hit.before)} tracked on ${displayName(e)} in ${hit.period} toward its ${wholeDollars(hit.spend)} spend bonus; spending earnrate wasn't told about isn't counted.`);
@@ -338,9 +367,9 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             const twin = alts.find((e) => e.card.id !== winner.card.id &&
                 alt.effectiveReturnPct - e.effectiveReturnPct <= EPSILON);
             if (alt.card.id !== winner.card.id)
-                warnings.push(`${as}, ${displayName(alt)} wins (${pct(alt.effectiveReturnPct)}).`);
+                warnings.push(`${as}, ${displayName(alt)} wins (${pct(alt.rateReturnPct)}).`);
             else if (twin)
-                warnings.push(`${as}, ${displayName(twin)} earns as much (${pct(twin.effectiveReturnPct)}).`);
+                warnings.push(`${as}, ${displayName(twin)} earns as much (${pct(twin.rateReturnPct)}).`);
         }
     }
     if (!winner) {
@@ -359,7 +388,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             ? rankEntries(catalog, wallet, { ...purchase, channel: 'online' }, online, online.category).entries[0]
             : undefined;
         if (alt)
-            warnings.push(`Ordering online instead? ${displayName(alt)} works there (${pct(alt.effectiveReturnPct)}).`);
+            warnings.push(`Ordering online instead? ${displayName(alt)} works there (${pct(alt.rateReturnPct)}).`);
     }
     else if (merchant.accepts === null &&
         (winner.card.network === 'amex' || winner.card.network === 'discover')) {
@@ -384,7 +413,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const alt = rankEntries(catalog, wallet, purchase, via, via.category)
             .entries[0];
         if (alt && alt.effectiveReturnPct > winner.effectiveReturnPct + EPSILON) {
-            notes.push(`If you book it as ${via.resolvedName}, ${displayName(alt)} earns ${pct(alt.effectiveReturnPct)}.`);
+            notes.push(`If you book it as ${via.resolvedName}, ${displayName(alt)} earns ${pct(alt.rateReturnPct)}.`);
         }
     }
     const open = bonusPick(catalog, wallet, entries, purchase.date);
@@ -400,7 +429,7 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
     const bonus = open && (open.behind || ties) ? open : null;
     const best = winner?.effectiveReturnPct ?? 0;
     if (open && !bonus && isClose(open.entry.effectiveReturnPct, best)) {
-        notes.push(`${displayName(open.entry)} earns ${pct(open.entry.effectiveReturnPct)} here, ${num(gap)} ${gap === 1 ? 'point' : 'points'} less than ${pct(best)}, and would help its welcome bonus (${money(open.status.remaining ?? 0)} more by ${open.status.deadline ?? ''}). You're on pace, so this uses the higher rate.`);
+        notes.push(`${displayName(open.entry)} earns ${pct(open.entry.rateReturnPct)} here, ${num(gap)} ${gap === 1 ? 'point' : 'points'} less than ${pct(best)}, and would help its welcome bonus (${money(open.status.remaining ?? 0)} more by ${open.status.deadline ?? ''}). You're on pace, so this uses the higher rate.`);
     }
     const chosen = bonus?.entry ?? winner;
     // A tie among the top cards doesn't matter when a welcome bonus decides.
@@ -417,7 +446,9 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
         const daysLeft = status.daysLeft ?? 0;
         const costHere = ties || top.earned === null || first.earned === null
             ? null
-            : roundCents(first.earned - top.earned);
+            : roundCents(first.earned +
+                (first.milestoneBonus?.dollars ?? 0) -
+                (top.earned + (top.milestoneBonus?.dollars ?? 0)));
         bonusResult = {
             cardId: top.cardId,
             checkoutLabel: top.checkoutLabel,

package/dist/engine/record.js

@@ -29,6 +29,7 @@ export function capBooking(catalog, wallet, purchase, merchant = resolveMerchant
         capKey: cap.key,
         ruleId: rule.id,
         period: cap.period,
+        periodKind: cap.cap.period,
         capAmount: cap.cap.amount,
         before,
         after: roundCents(before + purchase.amount),
@@ -90,6 +91,7 @@ export function milestoneBookings(catalog, wallet, purchase) {
                 cardId: card.id,
                 milestoneId: p.milestone.id,
                 period: p.period,
+                periodKind: p.milestone.period,
                 spend: p.milestone.spend,
                 before: p.spent,
                 after: roundCents(Math.max(0, p.spent + purchase.amount)),

package/dist/engine/rule-text.js

@@ -1,5 +1,5 @@
 import { findMerchant } from "../merchants/resolve.js";
-import { categoryPhrase, choiceName, listed, words } from "./text.js";
+import { categoryPhrase, choiceName, earnText, introPeriod, listed, num, words, } from "./text.js";
 // What a rule or a pick covers, in words, for answers and wallet lists.
 // Travel-site bookings ("Flight through Amex Travel") read mid-sentence in
 // lower case and plural; brand names ("Airbnb through Amex Travel") keep theirs.
@@ -57,3 +57,17 @@ export function ruleParts(catalog, rule) {
 export function ruleWhat(catalog, rule) {
     return listed(ruleParts(catalog, rule));
 }
+// "double every rate for the first year", "an extra 3% cash back on your 3%
+// picks for the first year".
+export function introWhat(catalog, card, intro) {
+    const covered = card.rules.filter((r) => intro.rules?.includes(r.id));
+    const on = intro.rules === undefined
+        ? 'every rate'
+        : [...new Set(covered.map((r) => ruleWhat(catalog, r)))].join('; ');
+    const change = intro.multiply === undefined
+        ? `an extra ${earnText(catalog, intro.add ?? 0, card.currency)} on ${on}`
+        : intro.multiply === 2
+            ? `double ${on}`
+            : `${num(intro.multiply)} times ${on}`;
+    return `${change} for the ${introPeriod(intro.days)}`;
+}

package/dist/engine/setup.js

@@ -3,6 +3,7 @@ import { membership, membershipName, sameGroup } from "./memberships.js";
 import { milestoneWhat } from "./milestones.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
+import { introWhat } from "./rule-text.js";
 import { idList, listed } from "./text.js";
 // Rules that start within this many days are worth activating now.
 const ACTIVATION_LOOKAHEAD_DAYS = 45;
@@ -105,6 +106,11 @@ export function cardInfo(catalog, card, wallet, today) {
             rewards: m.rewards ?? [],
             text: milestoneWhat(m).replace(/^the /, ''),
         })),
+        introRates: card.intro_rates.map((i) => ({
+            id: i.id,
+            days: i.days,
+            text: introWhat(catalog, card, i),
+        })),
     };
 }
 // Every word of the query has to match a word of the card's id, name or

package/dist/engine/text.js

@@ -63,6 +63,15 @@ export function categoryPhrase(catalog, id) {
         ? name
         : name.charAt(0).toLowerCase() + name.slice(1);
 }
+// A category bought as a service reads "on" (streaming services); its own
+// preposition or a parent's says so. Everything else reads "at".
+export function categoryReadsOn(catalog, id) {
+    const category = catalog.categories.find((c) => c.id === id);
+    if (category?.preposition === 'on')
+        return true;
+    const dot = id.lastIndexOf('.');
+    return dot !== -1 && categoryReadsOn(catalog, id.slice(0, dot));
+}
 export function earnText(catalog, rate, currency) {
     return currency === 'cash'
         ? `${pct(rate)} cash back`
@@ -122,6 +131,9 @@ export const CAP_PERIODS = {
     calendar_year: 'a calendar year',
     cardmember_year: 'a cardmember year',
 };
+// "for 2026-Q4", or "this cardmember year": a cardmember year's key is the
+// year it started, which reads as the calendar year.
+export const periodPhrase = (kind, key) => kind === 'cardmember_year' ? 'this cardmember year' : `for ${key}`;
 export const CAP_ADJECTIVES = {
     month: 'monthly',
     quarter: 'quarterly',
@@ -139,3 +151,14 @@ export const PICK_PERIODS = {
     calendar_year: 'each year',
     until_changed: 'until you change it',
 };
+// Intro rates (a card's first 365 days): "first year", "first 90 days".
+export const introPeriod = (days) => days === 365 ? 'first year' : `first ${String(days)} days`;
+export const introAdjective = (days) => days === 365 ? 'first-year' : `${String(days)}-day`;
+// Asking for an opening date: "if it opened in the last year".
+export const introSince = (days) => days === 365 ? 'in the last year' : `in the last ${String(days)} days`;
+// "6% cash back in your first year, through Mar 3, 2027; 3% cash back after
+// that."
+export const introRateText = (earn, standard, days, until) => `${earn} in your ${introPeriod(days)}, through ${shortDate(until)}; ${standard} after that.`;
+// For a card whose opening date isn't known: it's never assumed to be new.
+export const introUnknownText = (name, earn, standard, days) => `A ${introAdjective(days)} rate may apply on ${name}: ${earn} here in an account's ${introPeriod(days)}, instead of the ${standard} it's ranked at. Give the card's opening date if it opened ${introSince(days)}.`;
+export const introEndsText = (name, days, until) => `${name}'s ${introAdjective(days)} rate ends after ${shortDate(until)}; from then on it earns its standard rates.`;

package/dist/engine/wallet-change.js

@@ -22,6 +22,8 @@ function isAnniversary(text) {
     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);
 }
+const isDate = (d) => /^\d{4}-\d{2}-\d{2}$/.test(d) &&
+    new Date(`${d}T00:00:00Z`).toISOString().startsWith(d);
 function pickKey(card, today) {
     const period = choicePeriod(card);
     return period === null ? null : periodKey(period, today, null);
@@ -44,6 +46,15 @@ export function cardFields(card, held, input, today) {
         }
         fields.anniversary = input.anniversary;
     }
+    if (input.opened === null)
+        fields.opened = null;
+    else if (input.opened !== undefined) {
+        if (!isDate(input.opened))
+            problems.push(`"${input.opened}" isn't a date. Use YYYY-MM-DD.`);
+        else if (input.opened > today)
+            problems.push("The account's opening date is in the future.");
+        fields.opened = input.opened;
+    }
     if (input.activated !== undefined) {
         const needing = card.rules
             .filter((r) => r.requires?.activation)
@@ -142,8 +153,6 @@ export function cardFields(card, held, input, today) {
         fields.bonus = null;
     else if (input.bonus !== undefined) {
         const b = input.bonus;
-        const isDate = (d) => /^\d{4}-\d{2}-\d{2}$/.test(d) &&
-            new Date(`${d}T00:00:00Z`).toISOString().startsWith(d);
         if (!isDate(b.opened))
             problems.push(`"${b.opened}" isn't a date. Use YYYY-MM-DD.`);
         else if (b.opened > today)
@@ -177,6 +186,12 @@ export function cardFields(card, held, input, today) {
             ...(dollars === undefined ? {} : { dollars }),
         };
     }
+    const opened = fields.opened === undefined ? (held?.opened ?? null) : fields.opened;
+    const bonusOpened = fields.bonus === undefined
+        ? (held?.bonus?.opened ?? null)
+        : fields.bonus?.opened;
+    if (opened !== null && bonusOpened != null && opened !== bonusOpened)
+        problems.push(`The card's opening date (${opened}) and its welcome bonus's (${bonusOpened}) differ; give the same date for both.`);
     return problems.length > 0 ? problems.join('\n') : fields;
 }
 const newHolding = (id) => ({
@@ -184,8 +199,10 @@ const newHolding = (id) => ({
     cap_usage: {},
     activated: [],
 });
-const withFields = ({ bonus, checkout_label, ...held }, f) => ({
+const withFields = ({ bonus, checkout_label, opened, ...held }, f) => ({
     ...held,
+    ...(opened !== undefined && f.opened === undefined ? { opened } : {}),
+    ...(f.opened ? { opened: f.opened } : {}),
     ...(bonus && f.bonus === undefined ? { bonus } : {}),
     ...(checkout_label !== undefined && f.checkout_label === undefined
         ? { checkout_label }