earnrate 0.1.4 → 0.2.1

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

@@ -17,7 +17,7 @@ export const MerchantResolutionSchema = z.object({
         .nullable(),
     channel: Channel.nullable(),
     confidence: Confidence,
-    source: z.enum(['override', 'seed', 'llm', 'caller', 'none']),
+    source: z.enum(['override', 'seed', 'llm', 'caller', 'category', 'none']),
     bookedVia: z.array(z.string()),
     inference: z
         .object({
@@ -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(),
@@ -277,6 +277,7 @@ const SimulationSchema = z.object({
     notes: z.array(z.string()),
 });
 export const SpendingSimulationSchema = z.object({
+    notes: z.array(z.string()),
     singles: z.array(SimulationSchema),
     pairs: z.array(SimulationSchema.extend({ alternatives: z.array(z.string()) })),
     current: SimulationSchema.nullable(),
@@ -289,6 +290,7 @@ export const SpendingSimulationSchema = z.object({
     })),
 });
 export const CheatSheetSchema = z.object({
+    scope: z.enum(['wallet', 'all cards']),
     quarter: z.string(),
     date: z.string(),
     rows: z.array(z.object({
@@ -301,3 +303,7 @@ export const CheatSheetSchema = z.object({
     })),
     notes: z.array(z.string()),
 });
+export const PurchaseAnswerSchema = RecommendationSchema.extend({
+    // Every card earnrate knows, ranked: set when no cards were given.
+    allCards: ExplorationSchema.nullable(),
+});

package/dist/mcp/serve.js

@@ -1,4 +1,5 @@
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { FileWalletStore } from "../data/file-store.js";
 import { loadCatalog, walletPath } from "../data/load.js";
 import { localToday as today } from "../engine/periods.js";
 import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
@@ -21,7 +22,8 @@ export async function serveMcp(env) {
     }
     serveStdio(() => createEarnrateServer({
         catalog,
-        walletFile: walletPath(env),
+        store: new FileWalletStore(catalog, walletPath(env)),
+        savedWallets: 'file',
         today,
         llm,
         version,