rightcard-mcp 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# RightCard MCP
+
+The card-selection oracle for agents: **which of your credit cards should pay here?**
+Answers come from RightCard's bank-published, two-source-verified reward data — the same
+data the [RightCard iOS app](https://apps.apple.com/app/id6756834989) uses.
+
+- **No bank login. No account. Nothing stored.** You pass card ids and a store name; you get an answer.
+- Honest by construction: merchant-code caveats (Costco is a warehouse club, so the grocery bonus
+  won't post), rotating quarters with activation flags, ties named, points valued per program.
+- Cash value by default; `valuation: "points"` for conservative travel values.
+
+## Use it
+
+Hosted (stateless Streamable HTTP):
+
+```
+https://mcp.rightcard.ai/mcp
+```
+
+Local (stdio, nothing leaves your machine except a read of the public catalog):
+
+```
+npx rightcard-mcp
+```
+
+Claude Desktop / Claude Code / Cursor config:
+
+```json
+{ "mcpServers": { "rightcard": { "command": "npx", "args": ["-y", "rightcard-mcp"] } } }
+```
+
+## Tools
+
+| tool | what it answers |
+|---|---|
+| `best_card` | which of the given cards earns most at a store or category, today, with caveats |
+| `lookup_merchant` | how a store is coded (category, merchant type, MCC-trap caveat) |
+| `search_cards` | find card ids by name/issuer; verified first, unverified flagged |
+| `card` | one card's verified rates, rotating windows, choose-your-category spec |
+| `rotating_calendar` | live + upcoming rotating windows and permanent merchant benefits |
+
+Try: "I have the Amex Gold, Freedom Flex and Citi Double Cash. Which one at Costco?"
+
+## Parity with the app
+
+`src/engine.ts` is a port of the iOS app's Swift engine. `fixtures/engine_golden.json` holds
+3,100+ answers produced by the Swift code over the real catalog and merchant directory;
+`npm test` fails if the port disagrees on any of them. Offers (a user's personal bank offers)
+are deliberately not part of this server — they live on the phone.
+
+## Privacy
+
+The hosted server logs request counts only. No identifiers, no cookies, no storage.
+Full policy: https://rightcard.ai/privacy

package/dist/configurable.d.ts

@@ -0,0 +1,16 @@
+import type { CreditCard, SpendCategory } from "./model.js";
+export interface ConfigurableCardSpec {
+    key: string;
+    displayName: string;
+    bonusRate: number;
+    slots: number;
+    eligible: SpendCategory[];
+    note: string;
+    matchNeedles: string[];
+    multiCardMax: number;
+}
+export declare const CONFIGURABLE_SPECS: ConfigurableCardSpec[];
+/** ConfigurableCardCatalog.normalize: lowercase, "+" → "plus", strip non-alphanumerics. */
+export declare function normalizeConfigurable(s: string): string;
+export declare function specFor(card: CreditCard): ConfigurableCardSpec | null;
+export declare const isConfigurable: (card: CreditCard) => boolean;

package/dist/configurable.js

@@ -0,0 +1,47 @@
+export const CONFIGURABLE_SPECS = [
+    {
+        key: "amex_business_gold", displayName: "Amex Business Gold", bonusRate: 4, slots: 2,
+        eligible: ["dining", "gas", "travel"],
+        note: "4× on the 2 categories your business spends the most on each billing cycle — from restaurants, gas, airfare, advertising, shipping & select tech — on up to $150,000/year (1× after). Of the categories RightCard tracks, pick the up-to-2 you expect: restaurants, gas, or airfare.",
+        matchNeedles: ["businessgold"], multiCardMax: 1,
+    },
+    {
+        key: "bofa_business_customized", displayName: "BofA Business Advantage Customized Cash", bonusRate: 3, slots: 1,
+        eligible: ["gas", "travel"],
+        note: "3% in your chosen business category (plus an automatic 2% at restaurants), on up to $50,000 in combined choice + dining purchases each year (1% after). Of the categories RightCard tracks, the choice is gas or travel — default gas.",
+        matchNeedles: ["businessadvantagecustomized"], multiCardMax: 1,
+    },
+    {
+        key: "bilt_obsidian", displayName: "Bilt Obsidian Card", bonusRate: 3, slots: 1,
+        eligible: ["dining", "grocery"],
+        note: "3× on your choice of dining OR grocery, set for the calendar year — pick the one you spend more on (grocery counts up to $25,000/year). Everything else earns 1×.",
+        matchNeedles: ["obsidian"], multiCardMax: 1,
+    },
+    {
+        key: "citi_custom_cash", displayName: "Citi Custom Cash", bonusRate: 5, slots: 1,
+        eligible: ["dining", "grocery", "gas", "travel", "drugstore", "transit", "streaming"],
+        note: "5% on your top eligible category, up to $500 each billing cycle (1% after). Citi applies it to your highest-spend category automatically — set the one you expect so RightCard recommends it.",
+        matchNeedles: ["customcash"], multiCardMax: 3,
+    },
+    {
+        key: "bofa_customized_cash", displayName: "Bank of America Customized Cash Rewards", bonusRate: 3, slots: 1,
+        eligible: ["gas", "online", "dining", "travel", "drugstore"],
+        note: "3% in your chosen category (plus 2% at grocery & wholesale clubs), on up to $2,500 in combined choice + grocery purchases each quarter (1% after).",
+        matchNeedles: ["customized"], multiCardMax: 3,
+    },
+    {
+        key: "venmo_credit_card", displayName: "Venmo Credit Card", bonusRate: 3, slots: 1,
+        eligible: ["dining", "grocery", "gas", "travel", "transit"],
+        note: "3% back on the category you spend most in each month (2% on your second, 1% everywhere else). Venmo applies the tiers automatically from your actual spending — set the category you expect to top so RightCard recommends it there. The 2% tier isn't modeled.",
+        matchNeedles: ["venmo"], multiCardMax: 1,
+    },
+];
+/** ConfigurableCardCatalog.normalize: lowercase, "+" → "plus", strip non-alphanumerics. */
+export function normalizeConfigurable(s) {
+    return s.toLowerCase().replace(/\+/g, "plus").replace(/[^\p{L}\p{N}]/gu, "");
+}
+export function specFor(card) {
+    const hay = normalizeConfigurable(card.id) + normalizeConfigurable(card.displayName);
+    return CONFIGURABLE_SPECS.find((spec) => spec.matchNeedles.some((n) => hay.includes(n))) ?? null;
+}
+export const isConfigurable = (card) => specFor(card) !== null;

package/dist/data.d.ts

@@ -0,0 +1,15 @@
+import { type CreditCard, type Merchant, type Override } from "./model.js";
+import { type IndexEntry } from "./search.js";
+export declare const SUPABASE_URL = "https://janvnoyczokisiepefol.supabase.co/rest/v1";
+export declare const SUPABASE_ANON: string;
+export interface Catalog {
+    cards: CreditCard[];
+    cardsById: Map<string, CreditCard>;
+    overrides: Override[];
+    merchants: Merchant[];
+    index: IndexEntry[];
+    loadedAt: number;
+}
+export declare function loadCatalog(fetchImpl?: typeof fetch): Promise<Catalog>;
+/** One-hour edge/process cache; a failed refresh keeps serving the last good catalog. */
+export declare function catalogCache(fetchImpl?: typeof fetch, ttlMs?: number): () => Promise<Catalog>;

package/dist/data.js

@@ -0,0 +1,54 @@
+// Public-tier data access. ANON key only (publishable, RLS-gated, read-only) — the same
+// key the iOS app ships. No private tables, no auth, no user data, ever.
+import { cardFromRow, merchantFromRow, overrideFromRow } from "./model.js";
+import { buildIndex } from "./search.js";
+export const SUPABASE_URL = "https://janvnoyczokisiepefol.supabase.co/rest/v1";
+export const SUPABASE_ANON = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." +
+    "eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImphbnZub3ljem9raXNpZXBlZm9sIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODAxOTc5NDUsImV4cCI6MjA5NTc3Mzk0NX0." +
+    "WdNuhqWft11jh5btv0tvbAA2IUIgpbNTPKaf_YluvwM";
+async function getAll(path, fetchImpl) {
+    const out = [];
+    const page = 1000;
+    for (let off = 0; off < 50000; off += page) {
+        const sep = path.includes("?") ? "&" : "?";
+        const res = await fetchImpl(`${SUPABASE_URL}/${path}${sep}limit=${page}&offset=${off}`, {
+            headers: { apikey: SUPABASE_ANON, Authorization: `Bearer ${SUPABASE_ANON}` },
+        });
+        if (!res.ok)
+            throw new Error(`supabase ${path}: HTTP ${res.status}`);
+        const rows = (await res.json());
+        out.push(...rows);
+        if (rows.length < page)
+            break;
+    }
+    return out;
+}
+export async function loadCatalog(fetchImpl = fetch) {
+    const [cardRows, overrideRows, merchantRows] = await Promise.all([
+        getAll("cards?select=id,name,issuer,reward_currency,base_rate,standard_multipliers,annual_fee,verify_status&country=eq.US&order=id", fetchImpl),
+        getAll("active_overrides?select=*&order=id", fetchImpl),
+        getAll("merchants?select=id,display_name,category,sub_key,merchant_type,is_online,aliases&country=eq.US&order=id", fetchImpl),
+    ]);
+    const cards = cardRows.map(cardFromRow);
+    const merchants = merchantRows.map(merchantFromRow);
+    return {
+        cards, cardsById: new Map(cards.map((c) => [c.id, c])), overrides: overrideRows.map(overrideFromRow),
+        merchants, index: buildIndex(merchants), loadedAt: Date.now(),
+    };
+}
+/** One-hour edge/process cache; a failed refresh keeps serving the last good catalog. */
+export function catalogCache(fetchImpl = fetch, ttlMs = 60 * 60 * 1000) {
+    let current = null;
+    let inflight = null;
+    return async () => {
+        if (current && Date.now() - current.loadedAt < ttlMs)
+            return current;
+        if (!inflight) {
+            inflight = loadCatalog(fetchImpl).then((c) => { current = c; return c; })
+                .catch((e) => { if (current)
+                return current; throw e; })
+                .finally(() => { inflight = null; });
+        }
+        return inflight;
+    };
+}

package/dist/engine.d.ts

@@ -0,0 +1,40 @@
+import { type CreditCard, type Override, type SpendCategory } from "./model.js";
+import { type Valuation } from "./valuation.js";
+export interface SubcategoryBest {
+    label: string;
+    cardName: string;
+    rate: string;
+}
+export interface Recommendation {
+    cardId: string;
+    cardName: string;
+    rateDisplay: string;
+    valueCaption: string;
+    reason: string;
+    breakdownLines: string[];
+    loggableRate: number | null;
+    valueMath: string | null;
+    valueMathShort: string | null;
+    valuationBasis: string | null;
+    valuationMode: Valuation["mode"];
+    tieNote: string | null;
+    portalNote: string | null;
+    subcategoryBreakdown: SubcategoryBest[];
+    /** set by the caller from the directory (exclusionCaveat) */
+    caveat?: string | null;
+}
+export interface RecommendInput {
+    cards: CreditCard[];
+    category: SpendCategory;
+    subKey?: string | null;
+    merchantName?: string | null;
+    overrides: Override[];
+    valuation: Valuation;
+    cardConfigs?: Record<string, Set<SpendCategory>>;
+    now: Date;
+    strictMerchantMatch?: boolean;
+}
+export declare function formatPercent(v: number): string;
+export declare function formatMultiplier(v: number): string;
+/** MerchantYieldEngine.recommend — base-rate mode (offers: []) */
+export declare function recommend(input: RecommendInput): Recommendation | null;

package/dist/engine.js

@@ -0,0 +1,264 @@
+// Mirrors MerchantYieldEngine (BASE-RATE mode only — offers live on the phone, never here).
+import { CATEGORY_DISPLAY, isPermanentMerchantBenefit, multiplier, overrideIsActive, } from "./model.js";
+import { merchantMatchesCoBrandBenefit, offerMatches } from "./matching.js";
+import { specFor } from "./configurable.js";
+import { basisLabel, cashOutCPP, centsPerPoint, earnUnitLabel, effectiveProgram, fmt1, valuesPointsAboveCash, withPooling, } from "./valuation.js";
+// ── formatting (Swift twins) ──
+export function formatPercent(v) {
+    return v === Math.round(v) ? `${Math.round(v)}%` : `${fmt1(v)}%`;
+}
+export function formatMultiplier(v) {
+    return v === Math.round(v) ? `${Math.round(v)}x` : `${fmt1(v)}x`;
+}
+/** shortName: trim issuer/boilerplate so a card name fits a one-line note. */
+function shortName(name) {
+    let s = name;
+    for (const term of ["American Express", "Bank of America", "Wells Fargo", "Capital One", "Credit Card", " Card", "®", "™"]) {
+        s = s.split(term).join(term === "American Express" ? "Amex" : "");
+    }
+    return s.trim();
+}
+const TRANSFERABLE = new Set(["amexMR", "chaseUR", "capOneMiles", "citiTYP", "wellsFargo"]);
+function optionalityRank(card, v) {
+    const program = effectiveProgram(v, card);
+    const isTransferable = TRANSFERABLE.has(program);
+    const isCash = program === "cash";
+    if (v.mode === "smart")
+        return isTransferable ? 2 : (isCash ? 0 : 1);
+    if (!isCash && cashOutCPP(program) >= 1.0)
+        return 3;
+    if (isCash)
+        return 2;
+    return isTransferable ? 1 : 0;
+}
+const PREMIUM_NEEDLES = [
+    "sapphire reserve", "sapphire preferred", "venture x", "platinum card",
+    "gold card", "amex gold", "strata premier", "citi premier", "prestige",
+    "ritz-carlton", "aspire", "altitude reserve", "brilliant",
+];
+function premiumRank(card) {
+    const n = card.displayName.toLowerCase();
+    return PREMIUM_NEEDLES.some((x) => n.includes(x)) ? 1 : 0;
+}
+function tieNote(winner, runnerUp, value, v) {
+    const rate = formatPercent(value);
+    const other = shortName(runnerUp.displayName);
+    const win = shortName(winner.displayName);
+    const wRank = optionalityRank(winner, v), rRank = optionalityRank(runnerUp, v);
+    if (wRank > rRank) {
+        const winProgram = effectiveProgram(v, winner);
+        if (v.mode === "cash" && winProgram !== "cash" && cashOutCPP(winProgram) >= 1.0) {
+            return `${win} ties ${other} at ${rate} — picked ${win}: its points cash out the same, and can be worth more if you ever redeem for travel.`;
+        }
+        const smart = { mode: "smart", pooledPrograms: v.pooledPrograms };
+        if (v.mode === "cash" && centsPerPoint(smart, runnerUp) > 1.0) {
+            return `${win} and ${other} tie at ${rate} for cash. ${other}'s points can be worth more if you redeem for travel — switch to Points & miles to compare.`;
+        }
+        const why = v.mode === "smart" ? "transfer flexibility" : "guaranteed cash back";
+        return `${win} ties ${other} at ${rate} — picked ${win} for ${why}.`;
+    }
+    if (premiumRank(winner) > premiumRank(runnerUp)) {
+        return `${win} ties ${other} at ${rate} — picked ${win}: the premium card's purchase protections come free at the same rate.`;
+    }
+    return `${win} ties ${other} at ${rate} — either works.`;
+}
+const PORTAL_BONUSES = [
+    { needles: ["sapphire reserve"], rate: 10, portal: "Chase Travel", premium: true },
+    { needles: ["sapphire preferred"], rate: 5, portal: "Chase Travel", premium: true },
+    { needles: ["freedom flex", "freedom unlimited"], rate: 5, portal: "Chase Travel", premium: false },
+    { needles: ["venture x"], rate: 10, portal: "Capital One Travel", premium: true },
+    { needles: ["venture"], rate: 5, portal: "Capital One Travel", premium: false },
+    { needles: ["strata premier", "citi premier"], rate: 10, portal: "Citi Travel", premium: true },
+    { needles: ["platinum card", "amex platinum", "american express platinum"], rate: 5, portal: "Amex Travel", premium: true },
+];
+function portalBonus(card) {
+    const hay = (card.id + " " + card.displayName).toLowerCase();
+    return PORTAL_BONUSES.find((pb) => pb.needles.some((n) => hay.includes(n))) ?? null;
+}
+function portalNote(cards, recommended) {
+    let best = null;
+    for (const card of cards) {
+        const pb = portalBonus(card);
+        if (!pb)
+            continue;
+        let better;
+        if (best === null)
+            better = true;
+        else if (pb.rate !== best.pb.rate)
+            better = pb.rate > best.pb.rate;
+        else
+            better = pb.premium && !best.pb.premium;
+        if (better)
+            best = { card, pb };
+    }
+    if (!best)
+        return null;
+    const everyday = multiplier(recommended, "travel", null);
+    if (!(best.pb.rate > everyday))
+        return null;
+    return `Booking through ${best.pb.portal}? ${shortName(best.card.displayName)} earns up to ${formatMultiplier(best.pb.rate)} there.`;
+}
+function appliedRate(card, category, subKey, merchantQuery, overrides, cardConfigs, now, strict) {
+    let rate = multiplier(card, category, subKey);
+    let winningOverride = null;
+    let winningConfig = null;
+    for (const o of overrides) {
+        if (o.cardId !== card.id || !overrideIsActive(o, now))
+            continue;
+        let matches;
+        if (o.merchant && o.merchant !== "") {
+            if (!merchantQuery || merchantQuery === "")
+                continue;
+            matches = isPermanentMerchantBenefit(o, now)
+                ? merchantMatchesCoBrandBenefit(o.merchant, merchantQuery)
+                : offerMatches(o.merchant, merchantQuery, strict);
+        }
+        else {
+            matches = o.category.trim().toLowerCase() === category;
+        }
+        if (matches && o.bonusRate > rate) {
+            rate = o.bonusRate;
+            winningOverride = o;
+            winningConfig = null;
+        }
+    }
+    const spec = specFor(card);
+    if (spec && spec.eligible.includes(category) && cardConfigs[card.id]?.has(category) && spec.bonusRate > rate) {
+        rate = spec.bonusRate;
+        winningConfig = spec;
+        winningOverride = null;
+    }
+    return { rate, override: winningOverride, configured: winningConfig };
+}
+function bestBaseCard(cards, category, subKey, merchantQuery, overrides, cardConfigs, v, now, strict) {
+    const candidates = cards.map((card) => {
+        const a = appliedRate(card, category, subKey, merchantQuery, overrides, cardConfigs, now, strict);
+        return { card, earn: a.rate, value: a.rate * centsPerPoint(v, card), override: a.override, configured: a.configured };
+    });
+    if (candidates.length === 0)
+        return null;
+    const maxValue = Math.max(...candidates.map((c) => c.value));
+    const tied = candidates.filter((c) => Math.abs(c.value - maxValue) < 0.0001).sort((a, b) => {
+        const ra = optionalityRank(a.card, v), rb = optionalityRank(b.card, v);
+        if (ra !== rb)
+            return rb - ra;
+        const pa = premiumRank(a.card), pb = premiumRank(b.card);
+        if (pa !== pb)
+            return pb - pa;
+        return a.card.displayName.localeCompare(b.card.displayName, "en", { sensitivity: "accent" });
+    });
+    const w = tied[0];
+    if (!w)
+        return null;
+    const note = tied.length >= 2 ? tieNote(w.card, tied[1].card, w.value, v) : null;
+    return { card: w.card, earn: w.earn, valueCents: w.value, override: w.override, configured: w.configured, tieNote: note };
+}
+function rateContext(card, earn, valueCents, override, configured, v, category, now, chosenCategoryCount) {
+    const valueStr = formatPercent(valueCents);
+    const cat = CATEGORY_DISPLAY[category].toLowerCase();
+    const disp = CATEGORY_DISPLAY[category];
+    let reason;
+    const lines = [];
+    const pointsAbove = valuesPointsAboveCash(v, card) && card.rewardCurrency !== null;
+    if (configured) {
+        const bonusStr = formatPercent(configured.bonusRate);
+        reason = `${card.displayName} is your choose-your-category card — you set ${disp} for ${bonusStr}, the most in your wallet here.`;
+        if (chosenCategoryCount > configured.slots) {
+            reason += ` You hold more than one — use the copy you set for ${disp}.`;
+            lines.push(`${bonusStr} on ${disp} — your chosen category (the ${disp} copy)`);
+        }
+        else {
+            lines.push(`${bonusStr} on ${disp} — your chosen category`);
+        }
+        lines.push(configured.note);
+    }
+    else if (override) {
+        const scope = override.merchant ? `at ${override.merchant}` : cat;
+        if (isPermanentMerchantBenefit(override, now)) {
+            reason = `${card.displayName} earns ${valueStr} ${scope} — the most in your wallet here.`;
+            lines.push(`${valueStr} ${scope} — card benefit`);
+        }
+        else {
+            const what = override.label ?? `${formatPercent(override.bonusRate)} rotating ${scope} bonus`;
+            reason = `${card.displayName} has a rotating bonus ${scope} active right now — ${valueStr} this quarter, the most in your wallet.`;
+            lines.push(`Rotating bonus: ${what}`);
+        }
+        if (pointsAbove) {
+            lines.push(`${formatMultiplier(override.bonusRate)} ${earnUnitLabel(v, card)} × ${fmt1(centsPerPoint(v, card))}¢ → ${valueStr} per $1`);
+        }
+        if (override.requiresActivation) {
+            const issuer = card.issuer ?? "issuer";
+            reason += ` Activate it in your ${issuer} app to earn the bonus.`;
+            lines.push(`⚠︎ Activate this quarter in your ${issuer} app`);
+        }
+    }
+    else if (pointsAbove) {
+        const earnStr = formatMultiplier(earn);
+        const unit = earnUnitLabel(v, card);
+        const cppStr = fmt1(centsPerPoint(v, card));
+        reason = `${card.displayName} earns ${earnStr} ${unit} on ${cat} — at ${cppStr}¢ each that's ${valueStr} per dollar, the most in your wallet.`;
+        lines.push(`Earns ${earnStr} ${unit}`);
+        lines.push(`Valued at ${cppStr}¢/pt → ${valueStr} per $1`);
+    }
+    else {
+        reason = `${card.displayName} earns the most for ${cat} — ${valueStr} per dollar.`;
+        lines.push(`Base ${cat} earn: ${valueStr}`);
+    }
+    let caption = configured ? "your bonus category · value per $1" : override ? "rotating bonus · value per $1" : "value per $1";
+    let valueMath = null;
+    let valueMathShort = null;
+    if (pointsAbove) {
+        caption = `${formatMultiplier(earn)} ${earnUnitLabel(v, card)} · ${caption}`;
+        const effectiveEarn = configured?.bonusRate ?? override?.bonusRate ?? earn;
+        const cpp = centsPerPoint(v, card);
+        valueMath = `${formatMultiplier(effectiveEarn)} ${earnUnitLabel(v, card)} × ${fmt1(cpp)}¢ = ${fmt1(effectiveEarn * cpp)}¢ per $1`;
+        const cppShort = cpp === Math.round(cpp) ? `${Math.round(cpp)}¢` : `${fmt1(cpp)}¢`;
+        valueMathShort = `${formatMultiplier(effectiveEarn)} pts × ${cppShort}`;
+    }
+    return {
+        cardId: card.id, cardName: card.displayName, rateDisplay: valueStr, valueCaption: caption, reason,
+        breakdownLines: lines, loggableRate: valueCents, valueMath, valueMathShort,
+        valuationBasis: basisLabel(v, card), valuationMode: v.mode, tieNote: null, portalNote: null, subcategoryBreakdown: [],
+    };
+}
+function subcategoryBreakdown(cards, category, overrides, cardConfigs, v, now) {
+    let subs;
+    if (category === "grocery")
+        subs = [["in_store", "In a store"], ["online", "Online / delivery"]];
+    else if (category === "travel")
+        subs = [["flight", "Flights"], ["hotel", "Hotels"]];
+    else
+        return [];
+    const rows = [];
+    for (const [key, label] of subs) {
+        const w = bestBaseCard(cards, category, key, null, overrides, cardConfigs, v, now, false);
+        if (!w)
+            continue;
+        rows.push({ label, cardName: w.card.displayName, rate: formatPercent(w.valueCents) });
+    }
+    const distinct = new Set(rows.map((r) => `${r.cardName}|${r.rate}`));
+    return distinct.size > 1 ? rows : [];
+}
+/** MerchantYieldEngine.recommend — base-rate mode (offers: []) */
+export function recommend(input) {
+    const { cards, category, overrides, now } = input;
+    if (cards.length === 0)
+        return null;
+    const v = withPooling(input.valuation, cards);
+    const cardConfigs = input.cardConfigs ?? {};
+    const strict = input.strictMerchantMatch ?? false;
+    const subKey = input.subKey ?? null;
+    const merchantName = input.merchantName && input.merchantName.trim() !== "" ? input.merchantName : null;
+    const query = merchantName ? merchantName.toLowerCase() : null;
+    const w = bestBaseCard(cards, category, subKey, query, overrides, cardConfigs, v, now, strict);
+    if (!w)
+        return null;
+    const ctx = rateContext(w.card, w.earn, w.valueCents, w.override, w.configured, v, category, now, cardConfigs[w.card.id]?.size ?? 0);
+    ctx.tieNote = w.tieNote;
+    if (category === "travel")
+        ctx.portalNote = portalNote(cards, w.card);
+    if (input.merchantName == null && input.subKey == null) {
+        ctx.subcategoryBreakdown = subcategoryBreakdown(cards, category, overrides, cardConfigs, v, now);
+    }
+    return ctx;
+}

package/dist/matching.d.ts

@@ -0,0 +1,7 @@
+/** MerchantYieldEngine.merchantMatches(offer:query:) */
+export declare function merchantMatches(offerMerchant: string, query: string): boolean;
+/** MerchantYieldEngine.merchantMatchesStrict(offer:place:) */
+export declare function merchantMatchesStrict(offerMerchant: string, place: string): boolean;
+export declare function offerMatches(offer: string, query: string, strict: boolean): boolean;
+/** MerchantYieldEngine.merchantMatchesCoBrandBenefit(benefit:query:) */
+export declare function merchantMatchesCoBrandBenefit(benefit: string, query: string): boolean;

package/dist/matching.js

@@ -0,0 +1,93 @@
+// Mirrors MerchantYieldEngine's brand matchers (merchantMatches, merchantMatchesStrict,
+// merchantMatchesCoBrandBenefit) — brand identity, not token overlap.
+const MERCHANT_STOPWORDS = new Set([
+    "the", "and", "for", "inc", "llc", "ltd", "co", "shop", "store", "stores",
+    "online", "subscription", "subscriptions", "rent", "rental", "rentals",
+    "car", "cars", "hotel", "hotels", "resort", "resorts", "international",
+    "monthly", "annual", "premium", "collection", "rewards", "select",
+    "destinations", "prepaid", "purchases", "amex", "american", "express",
+]);
+const ARTICLE_STOPWORDS = new Set(["the", "a", "an", "of", "and", "at"]);
+const GENERIC_PLACE = new Set([
+    "gas", "station", "fuel", "fueling", "market", "supermarket", "mart",
+    "store", "stores", "pharmacy", "drugstore", "supercenter", "super",
+    "center", "centre", "outlet", "express", "shopping", "inc", "llc", "farmers",
+]);
+const COBRAND_GENERIC = new Set(["incorporated", "corporation", "company"]);
+const TLD_RE = /\.(com|net|org|co|io|tv|shop|store|us)\b/g;
+const isAlnum = (ch) => /[\p{L}\p{N}]/u.test(ch);
+const cache = new Map();
+function forms(s) {
+    const hit = cache.get(s);
+    if (hit)
+        return hit;
+    const lowered = s.toLowerCase()
+        .replace(/&/g, " and ")
+        .replace(/(?<=[\p{L}\p{N}])\+(?=[\p{L}\p{N}])/gu, " and ")
+        .replace(/(?<=\s)\+(?=\s)/g, " and ");
+    const stripped = lowered.replace(TLD_RE, " ");
+    const parts = stripped.split(/[^\p{L}\p{N}]+/u).filter((p) => p.length > 0);
+    const out = {
+        brand: parts.filter((p) => p.length >= 2 && !MERCHANT_STOPWORDS.has(p) && !ARTICLE_STOPWORDS.has(p)),
+        significant: new Set(parts.filter((p) => p.length >= 2 && !ARTICLE_STOPWORDS.has(p))),
+        compact: parts.join(""),
+    };
+    if (cache.size > 4096)
+        cache.clear();
+    cache.set(s, out);
+    return out;
+}
+const eq = (a, b) => a.size === b.size && [...a].every((x) => b.has(x));
+const isSubset = (a, b) => [...a].every((x) => b.has(x));
+const isStrictSubset = (a, b) => a.size < b.size && isSubset(a, b);
+const minus = (a, b) => new Set([...a].filter((x) => !b.has(x)));
+/** MerchantYieldEngine.merchantMatches(offer:query:) */
+export function merchantMatches(offerMerchant, query) {
+    const o = forms(offerMerchant).brand, q = forms(query).brand;
+    if (o.length > 0 && q.length > 0) {
+        const os = new Set(o), qs = new Set(q);
+        if (eq(os, qs))
+            return true;
+        if (isStrictSubset(os, qs) && (isSubset(minus(qs, os), GENERIC_PLACE) || arrEq(q.slice(0, o.length), o)))
+            return true;
+        if (isStrictSubset(qs, os) && isSubset(minus(os, qs), GENERIC_PLACE))
+            return true;
+    }
+    const cm = forms(offerMerchant).compact, cq = forms(query).compact;
+    if (cm.length < 4 || cq.length < 4)
+        return false;
+    if (cm === cq)
+        return true;
+    const [short, long] = cm.length <= cq.length ? [cm, cq] : [cq, cm];
+    if (!long.startsWith(short))
+        return false;
+    const rest = long.slice(short.length);
+    return GENERIC_PLACE.has(rest) || MERCHANT_STOPWORDS.has(rest);
+}
+const arrEq = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+/** MerchantYieldEngine.merchantMatchesStrict(offer:place:) */
+export function merchantMatchesStrict(offerMerchant, place) {
+    const o = forms(offerMerchant).significant, p = forms(place).significant;
+    if (o.size === 0 || p.size === 0)
+        return false;
+    if (eq(o, p))
+        return true;
+    if (isSubset(o, p) && isSubset(minus(p, o), GENERIC_PLACE))
+        return true;
+    return forms(offerMerchant).compact === forms(place).compact;
+}
+export function offerMatches(offer, query, strict) {
+    return strict ? merchantMatchesStrict(offer, query) : merchantMatches(offer, query);
+}
+/** MerchantYieldEngine.merchantMatchesCoBrandBenefit(benefit:query:) */
+export function merchantMatchesCoBrandBenefit(benefit, query) {
+    const distinctive = (s) => new Set(s.toLowerCase().replace(/\.(com|net|org|co|io)\b/g, " ")
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((t) => t.length >= 4 && !COBRAND_GENERIC.has(t)));
+    const b = distinctive(benefit), q = distinctive(query);
+    if (b.size === 0 || q.size === 0)
+        return false;
+    if (![...b].some((x) => q.has(x)))
+        return false;
+    return isSubset(q, b);
+}

package/dist/model.d.ts

@@ -0,0 +1,55 @@
+export type SpendCategory = "dining" | "grocery" | "travel" | "gas" | "online" | "drugstore" | "transit" | "streaming" | "general";
+export declare const ALL_CATEGORIES: SpendCategory[];
+export declare const CATEGORY_DISPLAY: Record<SpendCategory, string>;
+export type RewardCurrency = "points" | "miles" | "cashback";
+export declare const CURRENCY_DISPLAY: Record<RewardCurrency, string>;
+export type MultiplierField = number | {
+    default: number;
+    values: Record<string, number>;
+};
+export interface CreditCard {
+    id: string;
+    displayName: string;
+    issuer: string | null;
+    rewardCurrency: RewardCurrency | null;
+    multipliers: Record<string, MultiplierField>;
+    annualFee?: number | null;
+    verifyStatus?: string | null;
+}
+/** Supabase `cards` row → CreditCard (SupabaseCard.toCreditCard). */
+export declare function cardFromRow(row: any): CreditCard;
+/** CreditCard.multiplier(for:subKey:) — direct key → "other" for general → "general" → 1.0 */
+export declare function multiplier(card: CreditCard, category: SpendCategory, subKey?: string | null): number;
+/** CreditCard.hasAnyReward */
+export declare function hasAnyReward(card: CreditCard): boolean;
+export interface Override {
+    id: string;
+    cardId: string;
+    category: string;
+    bonusRate: number;
+    startDate: string;
+    endDate: string;
+    requiresActivation: boolean;
+    label: string | null;
+    merchant: string | null;
+}
+export declare function overrideFromRow(r: any): Override;
+/** UTC-day canon (SupabaseDateFormat.utcCalendar): compare yyyy-MM-dd strings as UTC days. */
+export declare function utcDay(now: Date): string;
+export declare function overrideIsActive(o: Override, now: Date): boolean;
+/** SupabaseOverride.isPermanentMerchantBenefit: merchant-scoped, no activation, ends > 2 years out. */
+export declare function isPermanentMerchantBenefit(o: Override, now: Date): boolean;
+export interface Merchant {
+    id: string;
+    displayName: string;
+    category: SpendCategory;
+    subKey: string | null;
+    isOnline: boolean;
+    aliases: string[];
+    merchantType: string | null;
+}
+export declare function merchantFromRow(r: any): Merchant;
+/** Merchant.exclusionCaveat */
+export declare function exclusionCaveat(m: Merchant): string | null;
+/** Merchant.isCuratedBrand */
+export declare function isCuratedBrand(m: Merchant): boolean;