earnrate 0.2.0 → 0.2.1

package/dist/import/analyze.js

@@ -1,11 +1,11 @@
 import { bonusStatus, countsTowardBonus } from "../engine/bonus.js";
-import { categoryMatches } from "../engine/evaluate.js";
+import { capByKey, categoryMatches } from "../engine/evaluate.js";
 import { periodKey } from "../engine/periods.js";
-import { applyBooking, capBooking } from "../engine/record.js";
 import { recommend } from "../engine/recommend.js";
+import { applyBooking, capBooking } from "../engine/record.js";
+import { roundCents } from "../engine/text.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { cleanDescriptor } from "./statement.js";
-const round = (n) => Math.round(n * 100) / 100;
 function resolveLine(catalog, line) {
     const cleaned = cleanDescriptor(line.description);
     // "NAME-CHEAP.COM* LV0I6X": the part before the asterisk names the merchant.
@@ -30,12 +30,10 @@ function resolveLine(catalog, line) {
 function capPeriodKey(catalog, wallet, booking, date) {
     const card = catalog.cards.find((c) => c.id === booking.cardId);
     const held = wallet.cards.find((c) => c.id === booking.cardId);
-    const shared = card?.caps.find((c) => c.id === booking.capKey);
-    const inline = card?.rules.find((r) => r.id === booking.capKey)?.cap;
-    const period = shared?.period ?? (typeof inline === 'object' ? inline.period : undefined);
-    if (!period)
+    const cap = card && capByKey(card, booking.capKey);
+    if (!cap)
         return null;
-    return periodKey(period, date, held?.anniversary ?? null);
+    return periodKey(cap.period, date, held?.anniversary ?? null);
 }
 // Replays the statements twice: once on the cards actually used, once on
 // earnrate's picks, each with its own running cap usage, so a cap that fills
@@ -76,7 +74,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
         if (progress &&
             countsTowardBonus(progress, line.date) &&
             !alreadyRecorded(entry, 'bonus')) {
-            progress.after = round(Math.max(0, progress.after + line.amount));
+            progress.after = roundCents(Math.max(0, progress.after + line.amount));
             progress.entries.push(entry);
         }
         const { name, merchant, known } = resolveLine(catalog, line);
@@ -96,7 +94,7 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
                 const signed = line.amount < 0
                     ? {
                         ...booking,
-                        after: round(Math.max(0, booking.before + line.amount)),
+                        after: roundCents(Math.max(0, booking.before + line.amount)),
                     }
                     : booking;
                 bookings.push({ ...entry, booking: signed });
@@ -181,21 +179,21 @@ export function analyzeStatement(catalog, wallet, entries, today, alreadyRecorde
         from: sorted[0]?.line.date ?? '',
         to: sorted.at(-1)?.line.date ?? '',
         purchases,
-        spend: round(spend),
-        refunds: round(refunds),
-        earned: round(earned),
-        best: round(best),
+        spend: roundCents(spend),
+        refunds: roundCents(refunds),
+        earned: roundCents(earned),
+        best: roundCents(best),
         byCard: [...byCard.values()].map((t) => ({
             ...t,
-            spend: round(t.spend),
-            earned: round(t.earned),
+            spend: roundCents(t.spend),
+            earned: roundCents(t.earned),
         })),
         missed: [...missed.values()]
             .map((m) => ({
             ...m,
-            spend: round(m.spend),
-            earned: round(m.earned),
-            best: round(m.best),
+            spend: roundCents(m.spend),
+            earned: roundCents(m.earned),
+            best: roundCents(m.best),
         }))
             .sort((a, b) => b.best - b.earned - (a.best - a.earned)),
         coding: [...coding.values()].sort((a, b) => b.count - a.count),

package/dist/mcp/context.js

@@ -0,0 +1,92 @@
+import { walletProblems } from "../data/integrity.js";
+import { EMPTY_WALLET, walletFromCards } from "../engine/transient.js";
+import { formatNotes } from "../format/cards.js";
+import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
+import { defined } from "./inputs.js";
+export const fail = (text) => ({
+    content: [{ type: 'text', text }],
+    isError: true,
+});
+export const ALL_CARDS_NOTE = "The user hasn't named their cards, so this covers every card earnrate knows. That's a complete answer. If they want the best of their own cards, they can name them (pass them as `cards`); saving a wallet is optional.";
+// What every tool shares: the saved wallet, merchant resolution, and which
+// cards an answer is about.
+export function makeContext(deps) {
+    const { catalog } = deps;
+    const theWallet = deps.savedWallets === 'file'
+        ? `the wallet at ${deps.store.where}`
+        : 'the saved wallet';
+    const noWallet = `There's no saved wallet yet${deps.savedWallets === 'file' ? ` (${deps.store.where})` : ''}. Answers don't need one: they cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.`;
+    // Read on every call, so edits to the wallet apply without a restart.
+    async function wallet() {
+        let loaded;
+        try {
+            const found = await deps.store.load();
+            if (found === null)
+                return noWallet;
+            loaded = found;
+        }
+        catch (e) {
+            return `Couldn't read ${theWallet}: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        const problems = walletProblems(loaded, catalog);
+        return problems.length > 0
+            ? `${theWallet[0]?.toUpperCase() ?? ''}${theWallet.slice(1)} has problems:\n${problems.map((p) => `- ${p}`).join('\n')}`
+            : loaded;
+    }
+    // No saved wallet is the normal state, not a failure: it reads as an
+    // empty one, with a note on how to start one.
+    async function readableWallet() {
+        const w = await wallet();
+        if (typeof w !== 'string')
+            return { wallet: w, start: null };
+        return w === noWallet ? { wallet: EMPTY_WALLET, start: w } : w;
+    }
+    // The caller's category is free and comes before the paid Claude fallback;
+    // neither ever overrides a merchant earnrate already knows.
+    async function resolve(merchant, channel, category) {
+        const known = resolveMerchant(catalog, merchant, channel);
+        if (known.source !== 'none' || category !== null || !deps.llm) {
+            return { merchant: withCallerCategory(known, category), notices: [] };
+        }
+        return deps.llm.resolve(catalog, merchant, channel);
+    }
+    // Cards named in the conversation come first, then the saved wallet; with
+    // neither (null), answers cover every card earnrate knows.
+    async function cardsFor(cards, memberships) {
+        if (cards && cards.length > 0)
+            return walletFromCards(catalog, {
+                cards: cards.map(({ cardId, ...rest }) => ({
+                    id: cardId,
+                    ...defined(rest),
+                })),
+                ...(memberships ? { memberships } : {}),
+            }, deps.today());
+        const read = await readableWallet();
+        if (typeof read === 'string')
+            return read;
+        return read.start === null ? read.wallet : null;
+    }
+    // A card change reports what that card still needs; other changes don't.
+    function changed(result, message, { notes = true } = {}) {
+        if (!result.ok)
+            return fail(result.error);
+        const output = {
+            message,
+            created: result.created,
+            cardIds: result.wallet.cards.map((c) => c.id),
+            memberships: result.wallet.memberships,
+            notes: result.notes,
+        };
+        const text = [
+            message,
+            `Wallet: ${output.cardIds.join(', ')}.`,
+            ...(notes ? [formatNotes(result.notes)] : []),
+        ].join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: output,
+        };
+    }
+    const cardName = (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+    return { wallet, readableWallet, resolve, cardsFor, changed, cardName };
+}

package/dist/mcp/inputs.js

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import { ALL_PERSONAL_CARDS } from "../engine/explore.js";
+import { VALUATION_PROFILES } from "../engine/profiles.js";
+import { knownMemberships } from "../engine/setup.js";
+import { IsoDate } from "../schema/common.js";
+export const Merchant = z
+    .string()
+    .min(1)
+    .describe('Merchant name or web address as the user would say it or see it, e.g. "Whole Foods" or "delta.com".');
+export const ChannelInput = z
+    .enum(['online', 'in_store'])
+    .optional()
+    .describe('How the purchase is made. Omit if unknown; the answer says what it assumed.');
+export const DateInput = IsoDate.optional().describe('Purchase date, YYYY-MM-DD. Defaults to today.');
+export const CardId = z
+    .string()
+    .min(1)
+    .describe('The card id from search_cards, e.g. chase-sapphire-preferred.');
+// The filters every catalog-wide answer takes.
+const OfferFilters = {
+    kind: z
+        .enum(['any', 'cash', 'points'])
+        .optional()
+        .describe('cash: cash back cards only. points: points and miles cards only.'),
+    noAnnualFee: z
+        .boolean()
+        .optional()
+        .describe('Only cards with no annual fee.'),
+    business: z
+        .boolean()
+        .optional()
+        .describe('Business cards instead of personal ones.'),
+};
+const NamedCard = z.object({
+    cardId: z.string().min(1).describe('A card id from search_cards.'),
+    picks: z
+        .record(z.string(), z.array(z.string()).min(1))
+        .optional()
+        .describe("Bonus categories the user picked, for cards that have them: choice id → option ids, from search_cards. Ask; don't guess."),
+    activated: z
+        .array(z.string())
+        .optional()
+        .describe('Bonuses the user has activated with the issuer, as rule ids from search_cards.'),
+});
+const cardFields = {
+    checkoutLabel: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('How the card appears at checkout or in a browser wallet, e.g. "Amex Gold". Optional.'),
+    picks: z
+        .record(z.string(), z.array(z.string()).min(1))
+        .optional()
+        .describe('For cards where the cardholder picks bonus categories: choice id → option ids, from search_cards, e.g. {"five-percent": ["tv-internet-streaming", "fast-food"]}. Saved for the current period. Ask the user; don\'t guess.'),
+    anniversary: z
+        .string()
+        .regex(/^\d{2}-\d{2}$/)
+        .optional()
+        .describe("The account's anniversary as MM-DD, for cards whose cap resets on it."),
+    activated: z
+        .array(z.string())
+        .optional()
+        .describe('Rule ids the user has activated with the issuer, such as rotating categories. Replaces the current list.'),
+    bonus: z
+        .object({
+        opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),
+        spent: z
+            .number()
+            .nonnegative()
+            .optional()
+            .describe('Dollars already spent toward the bonus. Default 0.'),
+        spend: z
+            .number()
+            .positive()
+            .optional()
+            .describe("Dollars of spending the bonus needs, only if the user's offer differs from the published one."),
+        by: IsoDate.optional().describe("The deadline, YYYY-MM-DD, only if the user's offer differs from the published one."),
+    })
+        .nullable()
+        .optional()
+        .describe("A welcome bonus the user is working toward, so purchases recorded on this card count toward it and answers can favor it. Ask when they opened the account; spending needed and the deadline default to the card's published offer. null stops tracking it."),
+};
+export const CardChange = z.object({ cardId: CardId, ...cardFields });
+// Drops keys whose value is undefined, which optional zod fields produce and
+// exactOptionalPropertyTypes won't accept.
+export function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+export function cardInput({ cardId, bonus, ...rest }) {
+    return {
+        id: cardId,
+        ...defined(rest),
+        ...(bonus === undefined ? {} : { bonus: bonus && defined(bonus) }),
+    };
+}
+// Inputs that list the catalog's categories, issuers and memberships.
+export function makeInputs(catalog) {
+    const categoryIds = catalog.categories.map((c) => c.id);
+    const categoryList = catalog.categories
+        .map((c) => `${c.id} (${c.name})`)
+        .join(', ');
+    const membershipIds = knownMemberships(catalog);
+    const issuers = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
+    const CategoryInput = z
+        .enum(categoryIds)
+        .optional()
+        .describe(`Only for a merchant earnrate may not know, and only if you're confident what kind of business it is: its spending category, e.g. grocery.supermarket for a supermarket, dining for a restaurant, gas for a gas station. Ignored when earnrate knows the merchant. Leave it out if unsure. Categories: ${categoryList}.`);
+    const CatalogCategory = z
+        .enum(categoryIds)
+        .describe(`A spending category: ${categoryList}.`);
+    const Memberships = z.array(z.enum(membershipIds));
+    const NamedCards = z
+        .array(NamedCard)
+        .optional()
+        .describe("Cards the user named in this conversation, to answer for just those cards without saving anything. Leave out to use the user's saved wallet if they have one; with neither, the answer covers every card earnrate knows.");
+    const NamedMemberships = Memberships.optional().describe("Memberships the user has, such as amazon-prime, when they're named in the conversation rather than saved.");
+    const CatalogFilters = {
+        ...OfferFilters,
+        issuer: z.enum(issuers).optional().describe("Only this issuer's cards."),
+        memberships: Memberships.optional().describe("Memberships the user has, such as amazon-prime. Rates that need one they don't have are listed separately."),
+        valuation: z
+            .enum(['flat', 'points-heavy'])
+            .optional()
+            .describe('flat (default): points at their cash-out value, about 1¢. points-heavy: Amex MR and Chase UR at 1.7¢, for people who transfer points to airlines and hotels.'),
+    };
+    const AllMemberships = Memberships.describe(`Every membership the user has. Known: ${membershipIds.join(', ')}.`);
+    return {
+        CategoryInput,
+        CatalogCategory,
+        NamedCards,
+        NamedMemberships,
+        OfferFilters,
+        CatalogFilters,
+        AllMemberships,
+    };
+}
+// The catalog filters as exploreCards and simulate take them.
+export const settings = (args) => ({
+    filters: {
+        ...ALL_PERSONAL_CARDS,
+        kind: args.kind ?? 'any',
+        noAnnualFee: args.noAnnualFee ?? false,
+        business: args.business ?? false,
+        issuer: args.issuer ?? null,
+    },
+    memberships: args.memberships ?? [],
+    valuations: args.valuation ? VALUATION_PROFILES[args.valuation] : {},
+});

package/dist/mcp/schemas.js

@@ -42,7 +42,7 @@ const RankedCardSchema = z.object({
     reasoning: z.array(z.string()),
     warnings: z.array(z.string()),
 });
-export const RecommendationSchema = z.object({
+const RecommendationSchema = z.object({
     decision: z
         .object({
         cardId: z.string(),