earnrate 0.2.11 → 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/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) {
@@ -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.`);

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 }

package/dist/engine/wallet-summary.js

@@ -1,13 +1,14 @@
 import { bonusStatus } from "./bonus.js";
 import { activationGroup, capUsed, isActivated, pickedCategories, } from "./evaluate.js";
+import { introUntil, introWindows, openedOn } from "./intro.js";
 import { membershipName } from "./memberships.js";
 import { milestoneSummaries } from "./milestones.js";
-import { optionName, ruleParts, ruleWhat } from "./rule-text.js";
+import { optionName, ruleParts } from "./rule-text.js";
 import { choicePeriod, daysBetween, inEffect, periodEnd } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { activationRules } from "./setup.js";
-import { CAP_PERIODS, choiceName, currencyLabel, earnText, listed, shortDate, wholeDollars, words, } from "./text.js";
+import { CAP_PERIODS, categoryReadsOn, choiceName, currencyLabel, earnText, listed, shortDate, wholeDollars, words, } from "./text.js";
 import { cardValuation, currencyValuation } from "./valuation.js";
 const matchKeys = (rule) => rule.match.choice !== undefined
     ? []
@@ -98,8 +99,13 @@ export function activationsDue(catalog, card, held, today) {
             seen.add(g);
         const rules = card.rules.filter((r) => group.includes(r.id));
         const first = rules[0];
+        const categories = rules.flatMap((r) => r.match.categories ?? []);
+        const servicesOnly = categories.length > 0 &&
+            rules.every((r) => (r.match.merchants ?? []).length === 0) &&
+            categories.every((c) => categoryReadsOn(catalog, c));
         out.push({
-            what: rules.map((r) => ruleWhat(catalog, r)).join(', '),
+            what: listed([...new Set(rules.flatMap((r) => ruleParts(catalog, r)))]),
+            preposition: servicesOnly ? 'on' : 'at',
             from: first?.valid_from ?? null,
             to: first?.valid_to ?? null,
             activateBy: first?.activate_by ?? null,
@@ -144,7 +150,7 @@ function capSummaries(catalog, card, held, today) {
         const shared = card.caps.find((c) => c.id === key);
         const label = shared?.rotating
             ? 'the rotating bonus categories'
-            : [...new Set(covered.map((r) => ruleWhat(catalog, r)))].join(', ') ||
+            : listed([...new Set(covered.flatMap((r) => ruleParts(catalog, r)))]) ||
                 words(key);
         return {
             key,
@@ -211,6 +217,8 @@ export function walletSummary(catalog, wallet, today) {
             activated: held.activated,
             toActivate: toActivate(catalog, card, held, today),
             anniversary: held.anniversary ?? null,
+            opened: openedOn(held),
+            intro: introSummary(card, held, today),
         });
     }
     return {
@@ -221,6 +229,18 @@ export function walletSummary(catalog, wallet, today) {
         cards,
     };
 }
+function introSummary(card, held, today) {
+    const [first] = card.intro_rates;
+    if (!first)
+        return null;
+    const opened = openedOn(held);
+    if (opened === null)
+        return { state: 'no-date', until: null, days: first.days };
+    const [active] = introWindows(card, held, today);
+    if (active)
+        return { state: 'active', until: active.until, days: active.intro.days };
+    return { state: 'ended', until: introUntil(first, opened), days: first.days };
+}
 function pointValues(catalog, wallet) {
     return Object.keys(wallet.valuations)
         .filter((id) => catalog.currencies.some((c) => c.id === id))

package/dist/format/card-art.js

@@ -0,0 +1,21 @@
+const FALLBACK = '#5c5650';
+export function cardColor(catalog, cardId) {
+    const card = catalog.cards.find((c) => c.id === cardId);
+    if (card?.color)
+        return card.color;
+    return catalog.issuers.find((i) => i.id === card?.issuer)?.color ?? FALLBACK;
+}
+// Relative luminance, to keep the chip and edge visible on light cards.
+function light(hex) {
+    const [r, g, b] = [1, 3, 5].map((i) => {
+        const c = parseInt(hex.slice(i, i + 2), 16) / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b > 0.35;
+}
+// 86 x 54 is a card's 85.6 x 54 mm; `width` scales it.
+export function cardArtSvg(color, width = 48) {
+    const height = Math.round((width * 54) / 86);
+    const edge = light(color) ? 'rgba(0,0,0,0.18)' : 'rgba(255,255,255,0.14)';
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 86 54" width="${String(width)}" height="${String(height)}" aria-hidden="true" focusable="false"><rect x="0.5" y="0.5" width="85" height="53" rx="5" fill="${color}" stroke="${edge}"/><path d="M0 40 L56 0 H80 Q85.5 0 85.5 5 V8 L20 54 H5 Q0 54 0 49 Z" fill="#fff" opacity="0.07"/><rect x="10" y="17" width="14" height="11" rx="2" fill="#d9c08a" stroke="rgba(0,0,0,0.25)" stroke-width="0.6"/><path d="M10 22.5 H24 M17 17 V28" stroke="rgba(0,0,0,0.25)" stroke-width="0.6"/><rect x="10" y="40" width="30" height="3" rx="1.5" fill="${light(color) ? '#000' : '#fff'}" opacity="0.28"/></svg>`;
+}

package/dist/format/cards.js

@@ -20,6 +20,7 @@ export function formatCardInfo(card) {
             : []),
         ...(card.needsAnniversary ? ['cap resets on the card anniversary'] : []),
         ...card.milestones.map((m) => `spend bonus: ${m.text} (${m.id})`),
+        ...card.introRates.map((i) => `new accounts: ${i.text}; needs the opening date`),
         ...(card.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
         foreignFeeText(card.foreignTransactionFee).toLowerCase(),
     ];

package/dist/format/wallet-yaml.js

@@ -19,6 +19,7 @@ function compact(wallet) {
                 ? {}
                 : { checkout_label: c.checkout_label }),
             ...(c.anniversary === undefined ? {} : { anniversary: c.anniversary }),
+            ...(c.opened === undefined ? {} : { opened: c.opened }),
             ...(Object.keys(c.cap_usage).length > 0
                 ? { cap_usage: c.cap_usage }
                 : {}),