earnrate 0.2.12 → 0.2.13

package/dist/mcp/tools/wallet.js

@@ -51,6 +51,12 @@ function changes(catalog, args) {
         out.push(`${money(spent)} already spent on ${key} this period`);
     for (const [id, spent] of Object.entries(args.milestoneSpent ?? {}))
         out.push(`${money(spent)} spent toward ${id} this ${card?.milestones.find((m) => m.id === id)?.period === 'cardmember_year' ? 'cardmember year' : 'year'}`);
+    if (args.enrolled !== undefined)
+        out.push(args.enrolled.length === 0
+            ? 'no credits enrolled'
+            : `enrolled in: ${args.enrolled.join(', ')}`);
+    for (const [id, used] of Object.entries(args.creditUsed ?? {}))
+        out.push(`${money(used)} of the ${id} credit used this period`);
     if (args.bonus === null)
         out.push('welcome bonus no longer tracked');
     else if (args.bonus !== undefined)
@@ -62,7 +68,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     const { catalog, store } = deps;
     server.registerTool('list_wallet', {
         title: 'List wallet',
-        description: `Starts with a to-do list for the user's cards right now (bonuses to activate and their deadlines, categories to pick or confirm, caps nearly used up, welcome bonuses to finish and the weekly pace, yearly spend bonuses at least 75% of the way); use it when the user asks what to do with their cards this quarter or what they're forgetting. Then lists the user's cards: checkout label, network, rewards currency and its value, spending caps with how much is left this period, chosen bonus categories (and whether they're current), welcome-bonus progress, progress toward yearly spend bonuses, which stores a store card works at, when each card's data was last verified, the point values the user saved, and (for the hosted wallet) when it was started. ${ctx.walletUse}`,
+        description: `Starts with a to-do list for the user's cards right now (bonuses to activate and their deadlines, categories to pick or confirm, caps nearly used up, welcome bonuses to finish and the weekly pace, yearly spend bonuses at least 75% of the way, merchant credits to enroll in or use before they reset); use it when the user asks what to do with their cards this quarter or what they're forgetting. Then lists the user's cards: checkout label, network, rewards currency and its value, spending caps with how much is left this period, chosen bonus categories (and whether they're current), welcome-bonus progress, progress toward yearly spend bonuses, merchant statement credits (enrolled or not, and what's left this period), which stores a store card works at, when each card's data was last verified, the point values the user saved, and (for the hosted wallet) when it was started. ${ctx.walletUse}`,
         outputSchema: WalletSummarySchema,
         annotations: {
             title: 'List wallet',
@@ -96,7 +102,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('record_purchase', {
         title: 'Record a purchase',
-        description: `Records a purchase the user has already made, so spending caps, welcome-bonus progress and yearly spend milestones stay accurate for future recommendations. It updates the user's saved wallet. Only call it after the purchase has happened, and only once per purchase: calling it twice counts the spend twice. Purchases with no cap, no open welcome bonus and no spend milestone are acknowledged and nothing is written. For a merchant earnrate doesn't recognize it asks for category first, so caps aren't missed. ${ctx.walletUse}`,
+        description: `Records a purchase the user has already made, so spending caps, welcome-bonus progress, yearly spend milestones and merchant credits used stay accurate for future recommendations. It updates the user's saved wallet. Only call it after the purchase has happened, and only once per purchase: calling it twice counts the spend twice. Purchases with no cap, no open welcome bonus, no spend milestone and no enrolled merchant credit are acknowledged and nothing is written. For a merchant earnrate doesn't recognize it asks for category first, so caps aren't missed. ${ctx.walletUse}`,
         inputSchema: z.object({
             cardId: z
                 .string()
@@ -135,21 +141,23 @@ export function registerWalletTools(server, deps, ctx, inputs) {
         const result = await store.record(purchase, resolved.merchant);
         if (!result.ok)
             return fail(`Couldn't record it: ${result.error}`);
-        const { cap: booking, bonus, milestones } = result;
-        const output = booking || bonus || milestones.length > 0
+        const { cap: booking, bonus, milestones, credit } = result;
+        const output = booking || bonus || milestones.length > 0 || credit
             ? {
                 recorded: true,
                 booking,
                 bonus,
                 milestones,
-                message: `${formatBooking(amount, cardId, booking, bonus, milestones)} Saved in ${ctx.walletName}.`,
+                credit,
+                message: `${formatBooking(amount, cardId, booking, bonus, milestones, credit)} Saved in ${ctx.walletName}.`,
             }
             : {
                 recorded: false,
                 booking: null,
                 bonus: null,
                 milestones: [],
-                message: `Nothing to track: ${cardId} has no spending cap, open welcome bonus or spend milestone for this purchase, so the wallet wasn't changed.`,
+                credit: null,
+                message: `Nothing to track: ${cardId} has no spending cap, open welcome bonus, spend milestone or enrolled merchant credit for this purchase, so the wallet wasn't changed.`,
             };
         return {
             content: [
@@ -183,7 +191,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('update_card', {
         title: 'Update a card',
-        description: `Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, opening date (optional; for first-year rates), activated categories, cap spending so far (capSpent), spending this year toward its spend milestones (milestoneSpent) or a welcome bonus to track. Picks replace the saved ones in each choice group you set (other groups are kept) for the current period. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+. ${ctx.walletUse}`,
+        description: `Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, opening date (optional; for first-year rates), activated categories, cap spending so far (capSpent), spending this year toward its spend milestones (milestoneSpent), merchant credits enrolled in (enrolled) and used this period (creditUsed), or a welcome bonus to track. Picks replace the saved ones in each choice group you set (other groups are kept) for the current period. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+. ${ctx.walletUse}`,
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
         annotations: {

package/dist/merchants/resolve.js

@@ -121,6 +121,14 @@ export function findMerchant(catalog, id) {
     return (catalog.merchants.overrides.find((m) => m.id === id) ??
         catalog.merchants.seed.find((m) => m.id === id));
 }
+// The ids a card rule can name to match this merchant: its own and, for a
+// brand, its parent's.
+export function merchantFamily(catalog, id) {
+    if (id === null)
+        return [];
+    const parent = findMerchant(catalog, id)?.brand_of;
+    return parent === undefined ? [id] : [id, parent];
+}
 export function resolveMerchantById(catalog, id, channel) {
     const override = catalog.merchants.overrides.find((m) => m.id === id);
     const found = findMerchant(catalog, id);

package/dist/schema/card.js

@@ -33,6 +33,16 @@ export const SharedCapSchema = CapSchema.extend({
     // aren't in the data yet, not that there's no bonus.
     rotating: z.literal(true).optional(),
 });
+// How a purchase is paid, for rates that depend on it: Apple Card's 2% with
+// Apple Pay, PayPal Cashback's 3% through PayPal checkout. `card` is the card
+// itself or its number, not a phone wallet or PayPal. Unknown unless the
+// person says, so a rule that requires one never applies by assumption.
+export const PaymentMethod = z.enum([
+    'card',
+    'apple-pay',
+    'google-pay',
+    'paypal',
+]);
 const hasAny = (m) => Object.values(m).some((v) => v === true || (v !== undefined && v.length > 0));
 // Kinds combine with AND, values within a kind with OR: `{ merchants:
 // [lyft], categories: [transit] }` is a Lyft purchase that codes as transit.
@@ -52,8 +62,9 @@ export const ExcludeSchema = z
     categories: z.array(CategoryId).optional(),
     merchants: z.array(KebabId).optional(),
     mccs: z.array(Mcc).optional(),
+    payment: z.array(PaymentMethod).optional(),
 })
-    .refine(hasAny, 'exclude needs categories, merchants or mccs');
+    .refine(hasAny, 'exclude needs categories, merchants, mccs or payment');
 export const RuleSchema = z
     .strictObject({
     id: KebabId,
@@ -71,6 +82,7 @@ export const RuleSchema = z
         .strictObject({
         membership: KebabId.optional(),
         activation: z.boolean().optional(),
+        payment: PaymentMethod.optional(),
     })
         .optional(),
     valid_from: IsoDate.optional(),
@@ -160,6 +172,26 @@ export const IntroRateSchema = z
     note: z.string().optional(),
 })
     .refine((i) => (i.multiply === undefined) !== (i.add === undefined), 'an intro rate needs multiply or add, not both');
+// Merchant statement credits: dollars back for spending at named merchants
+// (or a category) up to `amount` each period, like Amex Platinum's $75 a
+// quarter at lululemon. They're separate from earn rates: the purchase still
+// earns the card's rate on its whole amount, and the credit comes on top.
+// `half_year` runs January to June and July to December.
+export const CreditPeriod = z.enum([...CapPeriod.options, 'half_year']);
+export const CreditSchema = z.strictObject({
+    id: KebabId,
+    match: z
+        .strictObject({
+        merchants: z.array(KebabId).min(1).optional(),
+        categories: z.array(CategoryId).min(1).optional(),
+    })
+        .refine((m) => (m.merchants === undefined) !== (m.categories === undefined), 'a credit matches merchants or categories, not both'),
+    amount: z.number().positive(), // dollars of credit per period
+    period: CreditPeriod,
+    // The cardholder must enroll with the issuer before it pays.
+    enroll: z.literal(true).optional(),
+    note: z.string().optional(),
+});
 const HexColor = z.string().regex(/^#[0-9a-f]{6}$/);
 export const CardSchema = z
     .strictObject({
@@ -206,8 +238,10 @@ export const CardSchema = z
     rules: z.array(RuleSchema).default([]),
     milestones: z.array(MilestoneSchema).default([]),
     intro_rates: z.array(IntroRateSchema).default([]),
-    // A short quote from an issuer page for each rule (or `base_rate`). The
-    // weekly source check fails a rule whose quote disappears from its page.
+    credits: z.array(CreditSchema).default([]),
+    // A short quote from an issuer page for each rule (or `base_rate`, or a
+    // credit's id). The weekly source check fails a rule whose quote
+    // disappears from its page.
     evidence: z
         .array(z.strictObject({
         rule: z.string().min(1),

package/dist/schema/common.js

@@ -19,7 +19,7 @@ export const IsoDate = z.iso.date();
 // YAML reads `period: 2026` as a number, so accept both and normalize.
 export const PeriodKey = z.preprocess((v) => (typeof v === 'number' ? String(v) : v), z
     .string()
-    .regex(/^\d{4}(-Q[1-4]|-(0[1-9]|1[0-2]))?$/, 'expected a period like 2026, 2026-Q4 or 2026-10'));
+    .regex(/^\d{4}(-Q[1-4]|-H[12]|-(0[1-9]|1[0-2]))?$/, 'expected a period like 2026, 2026-Q4, 2026-H2 or 2026-10'));
 export const ValueRange = z
     .tuple([z.number().positive(), z.number().positive()])
     .refine(([low, high]) => low <= high, 'range must be [low, high]');

package/dist/schema/merchant.js

@@ -13,6 +13,9 @@ export const MerchantSchema = z.strictObject({
     aliases: z.array(z.string().min(1)).default([]),
     domains: z.array(z.string().min(1)).default([]),
     category: CategoryId,
+    // A brand of another merchant (Hampton Inn of Hilton): rules that name the
+    // parent's id also match the brand. One level only.
+    brand_of: KebabId.optional(),
     likely_mcc: Mcc.optional(),
     accepts: Accepts.optional(),
     in_store: ChannelOverride.optional(),

package/dist/schema/wallet.js

@@ -16,6 +16,10 @@ const CapUsage = z.strictObject({
     period: PeriodKey,
     spent: z.number().nonnegative(), // dollars
 });
+const CreditUsage = z.strictObject({
+    period: PeriodKey,
+    used: z.number().nonnegative(), // dollars of credit
+});
 export const WalletCardSchema = z.strictObject({
     id: KebabId,
     checkout_label: z
@@ -42,6 +46,10 @@ export const WalletCardSchema = z.strictObject({
     activated: z.array(KebabId).default([]),
     // Keyed by milestone id: every purchase on the card this period.
     milestone_usage: z.record(KebabId, CapUsage).optional(),
+    // Merchant credits (the card's `credits`) the cardholder has enrolled in,
+    // by credit id, and the dollars of each credit already received this period.
+    enrolled: z.array(KebabId).optional(),
+    credit_usage: z.record(KebabId, CreditUsage).optional(),
     // A welcome bonus in progress. Terms default to the card's published
     // offer; set spend, by, points or dollars when yours was different.
     bonus: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Which credit card earns the most at a merchant, from your cards or every card, and why",
   "keywords": [
     "credit cards",