earnrate 0.2.3 → 0.2.5

package/dist/mcp/tools/wallet.js

@@ -1,33 +1,81 @@
 import { z } from 'zod';
+import { membershipsFor, needsAnniversary } from "../../engine/setup.js";
+import { choiceName, currencyLabel, money, shortDate, words, } from "../../engine/text.js";
+import { profileText, VALUATION_PROFILES } from "../../engine/profiles.js";
 import { walletSummary } from "../../engine/wallet-summary.js";
 import { formatBooking, formatWalletSummary } from "../../format/wallet.js";
 import { fail } from "../context.js";
 import { CardChange, CardId, cardInput, ChannelInput, DateInput, Merchant, } from "../inputs.js";
 import { RecordResultSchema, WalletChangeSchema, WalletSummarySchema, } from "../schemas.js";
 const WRITE = { readOnlyHint: false, openWorldHint: false };
+// "Saved wallet started 4 minutes ago": relative, since the server doesn't
+// know the user's time zone, and precise enough to tell apart two wallets
+// started the same day.
+function startedText(started, now) {
+    const minutes = Math.floor((now - Date.parse(started)) / 60_000);
+    const ago = minutes < 1
+        ? 'just now'
+        : minutes < 60
+            ? `${String(minutes)} minute${minutes === 1 ? '' : 's'} ago`
+            : minutes < 48 * 60
+                ? `${String(Math.floor(minutes / 60))} hour${minutes < 120 ? '' : 's'} ago`
+                : `on ${shortDate(started.slice(0, 10))}`;
+    return `Saved wallet started ${ago}.`;
+}
+// What update_card changed, so the reply confirms the values it saved.
+function changes(args) {
+    const out = [];
+    for (const [choice, options] of Object.entries(args.picks ?? {}))
+        out.push(`${choiceName(choice)} picks: ${options.map(words).join(', ')}`);
+    if (args.checkoutLabel === null)
+        out.push('checkout name cleared');
+    else if (args.checkoutLabel !== undefined)
+        out.push(`checkout name "${args.checkoutLabel}"`);
+    if (args.anniversary !== undefined)
+        out.push(`anniversary ${args.anniversary}`);
+    if (args.activated !== undefined)
+        out.push(args.activated.length === 0
+            ? 'nothing activated'
+            : `activated: ${args.activated.join(', ')}`);
+    for (const [key, spent] of Object.entries(args.capSpent ?? {}))
+        out.push(`${money(spent)} already spent on ${key} this period`);
+    if (args.bonus === null)
+        out.push('welcome bonus no longer tracked');
+    else if (args.bonus !== undefined)
+        out.push(`welcome bonus tracked from ${args.bonus.opened}, ${money(args.bonus.spent ?? 0)} spent so far`);
+    return out;
+}
 // The tools that read or change a saved wallet.
 export function registerWalletTools(server, deps, ctx, inputs) {
     const { catalog, store } = deps;
     server.registerTool('list_wallet', {
         title: 'List wallet',
-        description: "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, which stores a store card works at, and when each card's data was last verified.",
+        description: "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, 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.",
         outputSchema: WalletSummarySchema,
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async () => {
         const read = await ctx.readableWallet();
         if (typeof read === 'string')
             return fail(read);
-        const summary = walletSummary(catalog, read.wallet, deps.today());
+        const started = deps.savedWallets === 'account' ? await deps.store.started() : null;
+        const summary = {
+            ...walletSummary(catalog, read.wallet, deps.today()),
+            started,
+        };
+        const when = started === null ? '' : `${startedText(started, Date.now())}\n`;
         return {
             content: [
-                { type: 'text', text: read.start ?? formatWalletSummary(summary) },
+                {
+                    type: 'text',
+                    text: `${when}${read.start ?? formatWalletSummary(summary)}`,
+                },
             ],
             structuredContent: summary,
         };
     });
     server.registerTool('record_purchase', {
         title: 'Record a purchase',
-        description: "Records a purchase the user has already made, so spending caps and welcome-bonus progress 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 and no open welcome bonus are acknowledged and nothing is written.",
+        description: "Records a purchase the user has already made, so spending caps and welcome-bonus progress 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 and no open welcome bonus are acknowledged and nothing is written. For a merchant earnrate doesn't recognize it asks for category first, so caps aren't missed.",
         inputSchema: z.object({
             cardId: z
                 .string()
@@ -37,7 +85,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             amount: z.number().positive().describe('Amount spent in US dollars.'),
             channel: ChannelInput,
             date: DateInput,
-            category: inputs.CategoryInput,
+            category: inputs.RecordCategoryInput,
         }),
         outputSchema: RecordResultSchema,
         annotations: {
@@ -60,6 +108,8 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             date: date ?? deps.today(),
         };
         const resolved = await ctx.resolve(merchant, purchase.channel, category ?? null);
+        if (resolved.merchant.source === 'none')
+            return fail(`earnrate doesn't recognize "${merchant}", so it can't tell which caps this purchase counts toward. Nothing was recorded. Call record_purchase again with category if you can tell what kind of business it is (a restaurant, a grocery store, a gas station), or ask the user. If nobody knows, category "other" records it toward a welcome bonus without touching any cap.`);
         const result = await store.record(purchase, resolved.merchant);
         if (!result.ok)
             return fail(`Couldn't record it: ${result.error}`);
@@ -104,11 +154,18 @@ 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 or activated categories. Picks for the current period are merged with the ones already saved. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+.',
+        description: 'Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, activated categories, cap spending so far (capSpent) 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+.',
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
         annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
-    }, async (args) => ctx.changed(await store.updateCard(cardInput(args), deps.today()), `Updated ${ctx.cardName(args.cardId)} (${args.cardId}).`));
+    }, async (args) => {
+        const what = changes(args);
+        const card = catalog.cards.find((c) => c.id === args.cardId);
+        const unused = args.anniversary !== undefined && card && !needsAnniversary(card)
+            ? " None of its caps reset on the account anniversary, so earnrate doesn't use it."
+            : '';
+        return ctx.changed(await store.updateCard(cardInput(args), deps.today()), `Updated ${ctx.cardName(args.cardId)} (${args.cardId})${what.length > 0 ? `: ${what.join('; ')}` : ''}.${unused}`);
+    });
     server.registerTool('remove_card', {
         title: 'Remove a card',
         description: "Removes a card from the wallet, with its tracked cap usage and bonus progress. Only when the user says they no longer have it or don't want it considered.",
@@ -118,11 +175,49 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     }, async ({ cardId }) => ctx.changed(await store.removeCard(cardId), `Removed ${ctx.cardName(cardId)} (${cardId}).`, { notes: false }));
     server.registerTool('set_memberships', {
         title: 'Set memberships',
-        description: "Sets the memberships that unlock some cards' rates, such as amazon-prime for Prime Visa's 5% or a Bank of America Preferred Rewards tier. Replaces the whole list, so include the ones to keep.",
+        description: "Sets the memberships that unlock some cards' rates, such as amazon-prime for Prime Visa's 5% or a Bank of America Preferred Rewards tier, and costco for a Costco membership (so spending answers don't count its cost against Costco Anywhere). Replaces the whole list, so include the ones to keep.",
         inputSchema: z.object({ memberships: inputs.AllMemberships }),
         outputSchema: WalletChangeSchema,
         annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
-    }, async ({ memberships }) => ctx.changed(await store.setMemberships(memberships), memberships.length > 0
-        ? `Memberships set to ${memberships.join(', ')}.`
-        : 'Memberships cleared.', { notes: false }));
+    }, async ({ memberships }) => {
+        const result = await store.setMemberships(memberships);
+        const used = new Set((result.ok ? result.wallet.cards : []).flatMap((held) => {
+            const card = catalog.cards.find((c) => c.id === held.id);
+            return card ? membershipsFor(card) : [];
+        }));
+        const unused = memberships.filter((m) => !used.has(m));
+        return ctx.changed(result, `${memberships.length > 0
+            ? `Memberships set to ${memberships.join(', ')}.`
+            : 'Memberships cleared.'}${unused.length > 0 ? ` ${unused.join(', ')} ${unused.length === 1 ? "doesn't" : "don't"} change any saved card's rates yet; kept for cards that use ${unused.length === 1 ? 'it' : 'them'}.` : ''}`, { notes: false });
+    });
+    server.registerTool('set_point_values', {
+        title: 'Set point values',
+        description: `Saves what the user's points are worth to them, in cents per point, in their saved wallet; every answer then compares cards at those values unless a valuation profile is asked for. It needs a saved wallet with a card in it. Use it when the user says what their points are worth ("I value Chase points at 1.5¢") or that they transfer points to airlines and hotels (profile points-heavy). Values change only the currencies given; null goes back to earnrate's default. Currencies: ${catalog.currencies.map((c) => c.id).join(', ')}.`,
+        inputSchema: z.object({
+            values: z
+                .record(z.string(), z.number().nullable())
+                .optional()
+                .describe('Cents per point by currency id, e.g. {"UR": 1.5, "MR": 1.6}. null goes back to the default.'),
+            profile: z
+                .enum(['flat', 'points-heavy'])
+                .optional()
+                .describe(`A preset: flat (${profileText('flat')}) or points-heavy (${profileText('points-heavy')}). Values given too win over it.`),
+        }),
+        outputSchema: WalletChangeSchema,
+        annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
+    }, async ({ values, profile }) => {
+        const changes = {
+            ...(profile ? VALUATION_PROFILES[profile] : {}),
+            ...(values ?? {}),
+        };
+        if (Object.keys(changes).length === 0)
+            return fail('Give values (cents per point by currency) or a profile.');
+        const result = await store.setValuations(changes);
+        const set = Object.entries(changes).map(([id, cents]) => cents === null
+            ? `${currencyLabel(catalog, id)} back to the default`
+            : `${currencyLabel(catalog, id)} at ${String(cents)}¢`);
+        return ctx.changed(result, `Point values: ${set.join(', ')}.`, {
+            notes: false,
+        });
+    });
 }

package/dist/schema/card.js

@@ -79,6 +79,9 @@ export const WelcomeOfferSchema = z
     // the page showed different offers on different visits. The amount
     // above is then the most it shows.
     varies: z.literal(true).optional(),
+    // Other cards whose holders the issuer says can't get this offer
+    // (Southwest's personal cards, Blue Cash Everyday with Preferred).
+    not_with: z.array(KebabId).min(1).optional(),
     note: z.string().optional(),
 })
     .refine((o) => (o.points === undefined) !== (o.dollars === undefined), 'a welcome offer needs points or dollars, not both');
@@ -143,6 +146,10 @@ export const CardSchema = z
     // When the first year differs, usually a waived fee.
     first_year_fee: z.number().nonnegative().optional(),
     welcome_offer: WelcomeOfferSchema.optional(),
+    // A paid membership (data/memberships.yaml) the card can't be had
+    // without, Costco's for Costco Anywhere. Its fee counts like an annual
+    // fee for anyone not already paying it.
+    requires_membership: KebabId.optional(),
     pools_into: z
         .strictObject({
         currency: CurrencyId,

package/dist/schema/category.js

@@ -9,5 +9,9 @@ export const CategorySchema = z.strictObject({
     // Everyday words people search by ("groceries"), besides the name.
     aliases: z.array(z.string().min(1)).default([]),
     note: z.string().optional(),
+    // Bought as a service, a category reads "on" (3x on flights); places read
+    // "at". Subcategories inherit it.
+    preposition: z.literal('on').optional(),
+    slug: z.string().optional(), // its search page, when not from its name
 });
 export const CategoriesFileSchema = z.array(CategorySchema).min(1);

package/dist/schema/currency.js

@@ -9,6 +9,8 @@ export const CurrencySchema = z.strictObject({
     // Value per redemption option, for currencies whose worth depends on how
     // they're redeemed. A wallet picks one by key.
     redemptions: z.record(z.string(), z.number().positive()).optional(),
+    // How each redemption reads after "redeemed": "into a SoFi account".
+    redemption_names: z.record(z.string(), z.string()).optional(),
     sources: z.array(z.url()).default([]),
     note: z.string().optional(),
 });

package/dist/schema/membership.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { KebabId } from "./common.js";
+export const MembershipSchema = z.strictObject({
+    id: KebabId,
+    name: z.string().min(1), // "Costco membership"
+    // The site's checkbox for it, when it's one most people would know.
+    ask: z.string().min(1).optional(),
+    // Memberships in one group are tiers: a person holds one at a time.
+    group: KebabId.optional(),
+    // Dollars a year, for a membership a card needs (`requires_membership`).
+    annual_fee: z.number().nonnegative().optional(),
+    // Merchants only members can buy from: spending there means a member.
+    members_shop_at: z.array(KebabId).default([]),
+});
+export const MembershipsFileSchema = z.array(MembershipSchema).min(1);

package/dist/schema/merchant.js

@@ -27,6 +27,10 @@ export const MerchantSchema = z.strictObject({
     // Other ways to buy the same thing, e.g. through a card's travel site, that
     // can earn more. Answers mention them when they would.
     booked_via: z.array(KebabId).default([]),
+    // A card issuer's or store's travel or ticketing site (portal: Amex Travel,
+    // Costco Travel), or a booking made through one (booking: "Hotel through
+    // Amex Travel").
+    kind: z.enum(['portal', 'booking']).optional(),
     note: z.string().optional(),
 });
 export const MerchantsFileSchema = z.array(MerchantSchema);

package/dist/schema/wallet.js

@@ -42,7 +42,11 @@ export const WalletCardSchema = z.strictObject({
     })
         .optional(),
 });
+// The wallet file's format. A file without `version` is version 1; bump it
+// when a change would make older earnrate misread newer files.
+export const WALLET_VERSION = 1;
 export const WalletSchema = z.strictObject({
+    version: z.number().int().positive().optional(),
     valuations: z.record(CurrencyId, Valuation).default({}),
     memberships: z.array(KebabId).default([]),
     cards: z.array(WalletCardSchema).min(1),

package/package.json

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

package/wallet.example.yaml

@@ -1,6 +1,7 @@
 # Copy to ~/.earnrate/wallet.yaml (or point $EARNRATE_WALLET at a copy).
 # Valuations default to data/currencies.yaml; set one here only to override it.
 
+version: 1
 valuations:
   sofi-rewards: { redemption: sofi-account }
 memberships: [amazon-prime]