earnrate 0.1.1 → 0.1.3

package/dist/data/wallet-edit.js

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

package/dist/data/wallet-setup.js

@@ -0,0 +1,60 @@
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
+import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, updateCardText, } from "./wallet-edit.js";
+const failed = (error) => ({ ok: false, error });
+async function attempt(task) {
+    try {
+        return await task();
+    }
+    catch (e) {
+        return failed(e instanceof Error ? e.message : String(e));
+    }
+}
+const noWallet = (file) => `No wallet at ${file} yet. Add a card first to create it.`;
+// The change is worked out on the parsed wallet, then spliced into the file
+// text, which must re-parse to exactly that wallet before it's written.
+async function commit(file, edited, change, created) {
+    await commitWalletText(file, edited, change.wallet);
+    return { ok: true, wallet: change.wallet, created, notes: change.notes };
+}
+export function addCard(file, catalog, input, today) {
+    return attempt(async () => {
+        const { text, wallet } = await readWalletText(file);
+        const change = addToWallet(catalog, wallet, input, today);
+        if (!change.ok)
+            return change;
+        return commit(file, addCardText(text, { id: input.id, ...change.fields }), change, text === null);
+    });
+}
+export function updateCard(file, catalog, input, today) {
+    return attempt(async () => {
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        const change = updateInWallet(catalog, wallet, input, today);
+        if (!change.ok)
+            return change;
+        return commit(file, updateCardText(text, input.id, change.fields), change, false);
+    });
+}
+export function removeCard(file, _catalog, id) {
+    return attempt(async () => {
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        const change = removeFromWallet(wallet, id);
+        if (!change.ok)
+            return change;
+        return commit(file, removeCardText(text, id), change, false);
+    });
+}
+export function setMemberships(file, catalog, memberships) {
+    return attempt(async () => {
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        const change = withMemberships(catalog, wallet, memberships);
+        if (!change.ok)
+            return change;
+        return commit(file, setMembershipsText(text, change.wallet.memberships), change, false);
+    });
+}

package/dist/engine/explore.js

@@ -0,0 +1,292 @@
+import { resolveMerchant } from "../merchants/resolve.js";
+import { evaluateCard, purchaseContext } from "./evaluate.js";
+import { periodKey } from "./periods.js";
+import { categoryPhrase, currencyLabel, dollars, earnText, num, recommend, } from "./recommend.js";
+import { rotationGap } from "./rotation.js";
+import { membershipsUsed } from "./setup.js";
+import { cardValuation } from "./valuation.js";
+const EPSILON = 1e-9;
+export const ALL_PERSONAL_CARDS = {
+    kind: 'any',
+    business: false,
+    noAnnualFee: false,
+    issuer: null,
+    includeClosed: false,
+};
+export function matchesFilters(card, filters) {
+    if (card.business !== filters.business)
+        return false;
+    if (!filters.includeClosed && card.applications_closed !== undefined)
+        return false;
+    if (filters.noAnnualFee && card.annual_fee !== 0)
+        return false;
+    if (filters.issuer !== null && card.issuer !== filters.issuer)
+        return false;
+    const isCash = card.currency === 'cash';
+    if (filters.kind === 'cash' && !isCash)
+        return false;
+    if (filters.kind === 'points' && isCash)
+        return false;
+    return true;
+}
+// The period a card's picks are keyed by in a wallet.
+export function choicePeriod(card) {
+    for (const c of card.choices)
+        if (c.period !== 'until_changed')
+            return c.period;
+    return 'quarter';
+}
+// A card as its holder would set it up for the best result: the given picks,
+// every activation done, and no cap used yet. The anniversary is `date`, so a
+// cardmember-year cap starts fresh.
+export function idealHolding(card, date, picks = {}) {
+    const period = choicePeriod(card);
+    return {
+        id: card.id,
+        anniversary: date.slice(5),
+        cap_usage: {},
+        activated: card.rules
+            .filter((r) => r.requires?.activation === true)
+            .map((r) => r.id),
+        ...(Object.keys(picks).length > 0
+            ? { chosen: { period: periodKey(period, date, null) ?? '', picks } }
+            : {}),
+    };
+}
+const PICK_PERIODS = {
+    month: 'set each month',
+    quarter: 'picked each quarter',
+    calendar_year: 'picked each year',
+    until_changed: 'until you change it',
+};
+const CAP_PERIODS = {
+    month: 'a month',
+    quarter: 'a quarter',
+    calendar_year: 'a calendar year',
+    cardmember_year: 'a cardmember year',
+};
+const plainWords = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+// A category from everyday words: an alias ("groceries") first, then the
+// name, then the id, so "grocery" means supermarkets rather than the parent.
+export function findCategory(catalog, text) {
+    const wanted = plainWords(text);
+    if (wanted === '')
+        return null;
+    const by = (key) => catalog.categories.find((c) => key(c).map(plainWords).includes(wanted))?.id;
+    return (by((c) => c.aliases) ?? by((c) => [c.name]) ?? by((c) => [c.id]) ?? null);
+}
+export function categoryResolution(catalog, category, channel) {
+    const found = catalog.categories.find((c) => c.id === category);
+    if (!found)
+        throw new Error(`unknown category '${category}'`);
+    return {
+        input: found.name,
+        merchantId: null,
+        resolvedName: found.name,
+        category,
+        likelyMcc: null,
+        accepts: null,
+        ambiguity: null,
+        channel,
+        confidence: 'high',
+        source: 'caller',
+        bookedVia: [],
+        inference: null,
+    };
+}
+function walletOf(held, options) {
+    return {
+        valuations: options.valuations,
+        memberships: options.memberships,
+        cards: [held],
+    };
+}
+// One option per choice is enough to cover a single purchase, so each choice
+// is tried option by option, keeping a pick only when it raises the rate.
+function bestPicksForPurchase(catalog, card, merchant, purchase, options) {
+    const picks = {};
+    const rateWith = (p) => {
+        const held = idealHolding(card, purchase.date, p);
+        const ctx = purchaseContext(catalog, walletOf(held, options), merchant, merchant.category, purchase);
+        return evaluateCard(card, held, ctx).best.rate;
+    };
+    for (const choice of card.choices) {
+        let best = rateWith(picks);
+        for (const option of Object.keys(choice.options)) {
+            const trial = { ...picks, [choice.id]: [option] };
+            const rate = rateWith(trial);
+            if (rate > best + EPSILON) {
+                best = rate;
+                picks[choice.id] = [option];
+            }
+        }
+    }
+    return picks;
+}
+function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
+    const ctx = purchaseContext(catalog, wallet, merchant, merchant.category, purchase);
+    const { best } = evaluateCard(card, held, ctx);
+    const rule = best.rule;
+    const none = { pick: null, activation: null, membership: null, cap: null };
+    if (!rule)
+        return none;
+    const choiceId = rule.match.choice;
+    const choice = card.choices.find((c) => c.id === choiceId);
+    const picked = choiceId === undefined ? undefined : held.chosen?.picks[choiceId];
+    const cap = best.cap?.cap;
+    return {
+        pick: choice && picked
+            ? { choice: choice.id, options: picked, period: choice.period }
+            : null,
+        activation: rule.requires?.activation === true ? rule.id : null,
+        membership: rule.requires?.membership ?? null,
+        cap: cap
+            ? {
+                amount: cap.amount,
+                period: cap.period,
+                thenRate: cap.then_rate,
+                currency: cardValuation(catalog, wallet, card).currency,
+            }
+            : null,
+    };
+}
+function conditionsText(catalog, r) {
+    const conditions = [];
+    if (r.pick) {
+        conditions.push(`Needs "${r.pick.options.join('", "')}" as its ${r.pick.choice} pick (${PICK_PERIODS[r.pick.period]}).`);
+    }
+    if (r.activation !== null)
+        conditions.push(`Needs activating with the issuer ("${r.activation}").`);
+    if (r.membership !== null)
+        conditions.push(`Needs ${r.membership}.`);
+    if (r.cap) {
+        conditions.push(`Up to ${dollars(r.cap.amount)} ${CAP_PERIODS[r.cap.period] ?? ''} at this rate, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}.`);
+    }
+    return conditions;
+}
+function membershipUpgrades(catalog, card, held, merchant, purchase, options, current) {
+    const upgrades = [];
+    for (const membership of membershipsUsed(card)) {
+        if (options.memberships.includes(membership))
+            continue;
+        const wallet = walletOf(held, {
+            ...options,
+            memberships: [...options.memberships, membership],
+        });
+        const ctx = purchaseContext(catalog, wallet, merchant, merchant.category, purchase);
+        const pct = evaluateCard(card, held, ctx).best.rate *
+            cardValuation(catalog, wallet, card).centsPerUnit;
+        if (pct > current + EPSILON)
+            upgrades.push({ membership, effectiveReturnPct: pct });
+    }
+    return upgrades.sort((a, b) => b.effectiveReturnPct - a.effectiveReturnPct);
+}
+function compareExplored(a, b) {
+    const byReturn = b.effectiveReturnPct - a.effectiveReturnPct;
+    if (Math.abs(byReturn) > EPSILON)
+        return byReturn;
+    const byFee = (a.annualFee ?? Infinity) - (b.annualFee ?? Infinity);
+    if (byFee !== 0)
+        return byFee;
+    const byConditions = a.conditions.length - b.conditions.length;
+    if (byConditions !== 0)
+        return byConditions;
+    return a.cardId.localeCompare(b.cardId);
+}
+// Ranks every card in the catalog that passes the filters for one purchase,
+// each set up at its best: the pick that covers it, activated, cap unused.
+export function exploreCards(catalog, query, options) {
+    const merchant = query.merchant !== null
+        ? resolveMerchant(catalog, query.merchant, query.channel)
+        : categoryResolution(catalog, query.category ?? 'other', query.channel);
+    const purchase = {
+        merchant: merchant.input,
+        amount: query.amount,
+        channel: query.channel,
+        date: query.date,
+        country: 'US',
+    };
+    const ranked = [];
+    const excluded = [];
+    for (const card of catalog.cards) {
+        if (!matchesFilters(card, options.filters))
+            continue;
+        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 top = rec.ranked[0];
+        if (!top) {
+            excluded.push(...rec.excluded);
+            continue;
+        }
+        const requirements = requirementsFor(catalog, card, held, wallet, merchant, purchase);
+        const gap = rotationGap(card, query.date);
+        const evidenceRule = top.matchedRule ?? 'base_rate';
+        const evidence = card.evidence.find((e) => e.rule === evidenceRule);
+        ranked.push({
+            ...top,
+            warnings: gap === null
+                ? top.warnings
+                : [
+                    ...top.warnings,
+                    `Its rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them.`,
+                ],
+            issuer: card.issuer,
+            network: card.network,
+            annualFee: card.annual_fee ?? null,
+            firstYearFee: card.first_year_fee ?? null,
+            picks,
+            requirements,
+            conditions: conditionsText(catalog, requirements),
+            evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
+            withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),
+        });
+    }
+    ranked.sort(compareExplored);
+    return {
+        merchant,
+        ranked,
+        excluded,
+        assumptions: exploreAssumptions(catalog, merchant, ranked, options),
+        warnings: exploreWarnings(catalog, merchant),
+    };
+}
+function exploreAssumptions(catalog, merchant, ranked, options) {
+    const assumptions = [];
+    if (merchant.source === 'caller') {
+        assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
+    }
+    else if (merchant.source !== 'none') {
+        const code = merchant.likelyMcc === null ? '' : ` (MCC ${String(merchant.likelyMcc)})`;
+        assumptions.push(`Assumes ${merchant.resolvedName} codes as ${categoryPhrase(catalog, merchant.category)}${code}.`);
+    }
+    assumptions.push('Assumes each card is set up for this purchase: the right category pick, any activation done, and none of its cap used yet. A card you hold may differ.');
+    assumptions.push(options.memberships.length === 0
+        ? 'Assumes no memberships (like Amazon Prime). Rates that need one are listed separately.'
+        : `Assumes these memberships: ${options.memberships.join(', ')}.`);
+    const values = new Map();
+    for (const e of ranked.slice(0, 10)) {
+        if (e.currency !== 'cash')
+            values.set(e.currency, e.centsPerUnit);
+    }
+    if (values.size > 0) {
+        const list = [...values].map(([id, cents]) => `${currencyLabel(catalog, id)} at ${num(cents)}¢`);
+        assumptions.push(`Values points at: ${list.join(', ')}.`);
+    }
+    return assumptions;
+}
+function exploreWarnings(catalog, merchant) {
+    const warnings = [];
+    if (merchant.source === 'none') {
+        warnings.push(`Couldn't identify "${merchant.input}", so only base rates apply. Try a category instead.`);
+    }
+    if (merchant.ambiguity) {
+        const alternatives = merchant.ambiguity.mayCodeAs.map((c) => categoryPhrase(catalog, c));
+        warnings.push(`${merchant.resolvedName} may code as ${alternatives.join(' or ')} instead: ${merchant.ambiguity.note}`);
+    }
+    return warnings;
+}

package/dist/engine/recommend.js

@@ -2,6 +2,7 @@ import { resolveMerchant, resolveMerchantById } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext, } from "./evaluate.js";
 import { bonusStatus } from "./bonus.js";
 import { daysBetween } from "./periods.js";
+import { rotationGap } from "./rotation.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 export const STALE_AFTER_DAYS = 180;
@@ -19,14 +20,14 @@ const PERIOD_WORDS = {
     cardmember_year: 'cardmember-year',
 };
 const displayName = (e) => e.held.checkout_label ?? e.card.name;
-const num = (n) => String(Number(n.toFixed(2)));
+export const num = (n) => String(Number(n.toFixed(2)));
 // Whole dollars stay whole ($2,800); anything else shows cents ($0.40).
 const money = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
-const dollars = (n) => `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
-function currencyName(catalog, id) {
+export const dollars = (n) => `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
+export function currencyName(catalog, id) {
     return catalog.currencies.find((c) => c.id === id)?.name ?? id;
 }
-function currencyLabel(catalog, id) {
+export function currencyLabel(catalog, id) {
     const name = currencyName(catalog, id);
     return /^[A-Z]{2,4}$/.test(id) ? `${name} (${id})` : name;
 }
@@ -38,13 +39,13 @@ function categoryName(catalog, id) {
 }
 // Mid-sentence form: "Supermarkets" becomes "supermarkets", but "TV and
 // internet service" and "EV charging" keep their acronyms.
-function categoryPhrase(catalog, id) {
+export function categoryPhrase(catalog, id) {
     const name = categoryName(catalog, id);
     return /^[A-Z]{2}/.test(name)
         ? name
         : name.charAt(0).toLowerCase() + name.slice(1);
 }
-function earnText(catalog, rate, currency) {
+export function earnText(catalog, rate, currency) {
     return currency === 'cash'
         ? `${num(rate)}% cash back`
         : `${num(rate)}x ${currencyName(catalog, currency)}`;
@@ -327,6 +328,14 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             : '';
         warnings.push(`Not every business takes ${NETWORK_NAMES[winner.card.network] ?? winner.card.network}.${fallback}`);
     }
+    for (const held of wallet.cards) {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        const gap = card ? rotationGap(card, purchase.date) : null;
+        if (card && gap !== null) {
+            const name = held.checkout_label ?? card.name;
+            warnings.push(`${name}'s rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them. If this purchase is in that period's categories, ${name} may earn more. An earnrate update adds them once the issuer announces them.`);
+        }
+    }
     const tie = tieNote(entries);
     if (tie)
         notes.push(tie);

package/dist/engine/rotation.js

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