earnrate 0.2.15 → 0.2.17

package/dist/format/explore.js

@@ -1,9 +1,13 @@
 import { membershipName, membershipNote, } from "../engine/memberships.js";
-import { capitalize, choiceName, CREDIT_GROUP, CREDITS_LEFT_OUT, ENROLL_FIRST, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, listed, } from "../engine/text.js";
+import { capitalize, choiceName, CREDIT_GROUP, CREDITS_APART, ENROLL_FIRST, HELD_CREDITS_COUNTED, hostname, feeText, dollarsAndCents, pct, wholeDollars, words, listed, } from "../engine/text.js";
 const membershipFees = (memberships) => memberships
     .map((m) => ` + ${wholeDollars(m.annualFee)} for ${m.name}`)
     .join('');
 const TOP_BEST = 10;
+// " · $X if you'd use all its credits ($424 a year)"
+const ifCredits = (credits, net, sign = '', its = 'its') => credits > 0
+    ? ` · ${sign}${wholeDollars(net)} if you'd use all ${its} credits (${wholeDollars(credits)} a year)`
+    : '';
 export function formatExploration(r, catalog, all) {
     const m = r.merchant;
     const title = m.source === 'category'
@@ -83,15 +87,15 @@ export function formatCatalogSimulation(r, catalog, all) {
         const card = s.cards[0];
         if (!card)
             return;
-        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeDollars(s.net)}  (${wholeDollars(s.rewards)} rewards, ${wholeDollars(s.annualFees)} fee${membershipFees(s.memberships)})${picksText(card.picks)}`);
+        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeDollars(s.net)}  (${wholeDollars(s.rewards)} rewards, ${wholeDollars(s.annualFees)} fee${membershipFees(s.memberships)})${ifCredits(s.otherCredits, s.netIfCreditsUsed)}${picksText(card.picks)}`);
     });
     const pairs = r.pairs.slice(0, top);
     if (pairs.length > 0) {
         lines.push('', 'Best two-card pairs:');
         pairs.forEach((s, i) => {
-            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeDollars(s.net)}`);
+            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeDollars(s.net)}${ifCredits(s.otherCredits, s.netIfCreditsUsed, '', 'their')}`);
             if (s.alternatives.length > 0)
-                lines.push(`    Same result with ${s.alternatives.map(name).join(' or ')} as the second card.`);
+                lines.push(`    Same result with ${listed(s.alternatives.map(name), 'or')} as the second card.`);
             for (const split of splitText(s, name))
                 lines.push(`    ${split}`);
         });
@@ -105,13 +109,13 @@ export function formatCatalogSimulation(r, catalog, all) {
     ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', `Assumes each card's best picks, activations done each quarter, and no welcome bonuses. ${CREDITS_LEFT_OUT}`);
+    lines.push('', `Assumes each card's best picks, activations done each quarter, and no welcome bonuses. ${CREDITS_APART}`);
     return `${lines.join('\n')}\n`;
 }
 export function formatAdditions(r, catalog, all) {
     const name = cardNamer(catalog);
     const lines = [
-        `Your wallet earns about ${wholeDollars(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeDollars(r.current.annualFees)} in annual fees: ${wholeDollars(r.current.net)} after fees` : ''}.`,
+        `Your wallet earns about ${wholeDollars(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeDollars(r.current.annualFees)} in annual fees${r.current.heldCredits > 0 ? ` and ${wholeDollars(r.current.heldCredits)} of credits you use` : ''}: ${wholeDollars(r.current.net)} after fees` : ''}.`,
     ];
     for (const split of splitText(r.current, name))
         lines.push(`  ${split}`);
@@ -122,7 +126,7 @@ export function formatAdditions(r, catalog, all) {
     else {
         lines.push('', 'Cards that would add the most (after their annual fee and any membership they need):');
         gains.slice(0, all ? 20 : TOP_SIMULATED).forEach((a, i) => {
-            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeDollars(a.gain)} a year  (+${wholeDollars(a.extraRewards)} rewards, ${wholeDollars(a.annualFee)} fee${membershipFees(a.simulation.memberships.filter((m) => m.cardIds.includes(a.cardId)))})${picksText(a.picks)}`);
+            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeDollars(a.gain)} a year  (+${wholeDollars(a.extraRewards)} rewards, ${wholeDollars(a.annualFee)} fee${membershipFees(a.simulation.memberships.filter((m) => m.cardIds.includes(a.cardId)))})${ifCredits(a.credits, a.gainIfCreditsUsed, '+')}${picksText(a.picks)}`);
         });
     }
     const notes = new Set([
@@ -133,6 +137,6 @@ export function formatAdditions(r, catalog, all) {
     ]);
     if (notes.size > 0)
         lines.push('', ...notes);
-    lines.push('', `Assumes your picks carry over, rotating categories get activated, and caps start fresh. Annual fees are counted in full: statement credits and perks that offset them are left out. ${CREDITS_LEFT_OUT} Each kind of spending lists the card that earns the most on it over the whole year, so a one-quarter bonus may not show.`);
+    lines.push('', `Assumes your picks carry over, rotating categories get activated, and caps start fresh. ${r.current.heldCredits > 0 ? `${HELD_CREDITS_COUNTED} ` : ''}${CREDITS_APART} Perks like lounge access aren't counted. Each kind of spending lists the card that earns the most on it over the whole year, so a one-quarter bonus may not show.`);
     return `${lines.join('\n')}\n`;
 }

package/dist/format/offers.js

@@ -11,7 +11,7 @@ export function formatOffers(c, currencyName, all) {
     shown.forEach((o, i) => {
         const weeks = (o.months * 52) / 12;
         const pace = o.spend > 0 ? ` (about ${wholeDollars(o.spend / weeks)} a week)` : '';
-        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${wholeDollars(o.firstYearValue)} the first year`, `    ${offerTerms(o, currencyName(o.currency))}${pace}. ${capitalize(feeText(o))}.${o.membershipFee > 0 ? ` Needs a ${money(o.membershipFee)} membership, counted in the first year.` : ''}${o.held ? ' In your wallet.' : ''}`);
+        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${wholeDollars(o.firstYearValue)} the first year${o.credits > 0 ? `, ${wholeDollars(o.firstYearValueIfCreditsUsed)} if you'd use all its credits (${wholeDollars(o.credits)} a year)` : ''}`, `    ${offerTerms(o, currencyName(o.currency))}${pace}. ${capitalize(feeText(o))}.${o.membershipFee > 0 ? ` Needs a ${money(o.membershipFee)} membership, counted in the first year.` : ''}${o.held ? ' In your wallet.' : ''}`);
         lines.push(`    ${o.validTo ? `Offer ends ${shortDate(o.validTo)}. ` : ''}Public offer as of ${shortDate(o.lastVerified)}; yours may differ.`);
         if (o.ineligible)
             lines.push(`    ${o.ineligible}`);

package/dist/format/wallet.js

@@ -41,6 +41,8 @@ export function formatWalletSummary(summary) {
             lines.push(`  Spend bonus (${m.id}): ${m.text}`);
         for (const credit of c.credits)
             lines.push(`  Credit (${credit.id}): ${credit.text}`);
+        if (c.usedCreditsText !== null)
+            lines.push(`  ${c.usedCreditsText}`);
         if (c.anniversary !== null)
             lines.push(`  Account anniversary: ${c.anniversary}.`);
         if (c.intro?.state === 'active' && c.intro.until !== null)

package/dist/mcp/inputs.js

@@ -49,6 +49,18 @@ const NamedCard = z.object({
         .array(z.string())
         .optional()
         .describe('Bonuses the user has activated with the issuer, as rule ids from search_cards.'),
+    enrolled: z
+        .array(z.string())
+        .optional()
+        .describe("Statement credits the user has enrolled in with the issuer, as credit ids from search_cards. A credit that needs enrolling counts only when it's here. Ask; never assume."),
+    skippedCredits: z
+        .array(z.string())
+        .optional()
+        .describe("Statement credit ids the user says they don't use. They don't count toward a pick or against the card's annual fee."),
+    opened: z
+        .string()
+        .optional()
+        .describe('The day the account opened (YYYY-MM-DD), for a card with a first-year rate. Optional; without it the card is ranked at its standard rates.'),
 });
 const cardFields = {
     checkoutLabel: z
@@ -84,11 +96,15 @@ const cardFields = {
     enrolled: z
         .array(z.string())
         .optional()
-        .describe('Statement credit ids the user has enrolled in with the issuer (search_cards and list_wallet list each card\'s credits, e.g. "lululemon" on Amex Platinum). A credit that needs enrolling counts in answers only once it\'s here. Replaces the current list. Ask; never assume.'),
+        .describe("Statement credit ids the user has enrolled in with the issuer, or, for a credit that needs no enrolling, says they use (search_cards and list_wallet list each card's credits, e.g. \"lululemon\" on Amex Platinum). A credit that needs enrolling counts in answers only once it's here, and any credit counts against the annual fee only once it's here (or has been used). Replaces the current list. Ask; never assume."),
     creditUsed: z
         .record(z.string(), z.number().nonnegative())
         .optional()
         .describe('Dollars of a statement credit already received this period: credit id → dollars, e.g. {"lululemon": 40}. Ask; recorded purchases add to it from then on.'),
+    skippedCredits: z
+        .array(z.string())
+        .optional()
+        .describe("Statement credit ids the user doesn't use, e.g. [\"dunkin\"] on Amex Gold. They're left out of picks, the to-do list and the annual-fee math; every other credit on the card counts against its fee once it's in enrolled (or, for one that needs no enrolling, has been used). Replaces the current list; [] counts them all again."),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),

package/dist/mcp/schemas.js

@@ -179,6 +179,8 @@ export const WalletSummarySchema = z.object({
             period: CreditPeriod,
             enroll: z.boolean(),
             enrolled: z.boolean(),
+            skipped: z.boolean(), // the user doesn't use it: not counted anywhere
+            confirmed: z.boolean(), // said in use: counts against the annual fee
             currentPeriod: z.string().nullable(),
             until: z.string().nullable(),
             used: z.number(),
@@ -186,6 +188,8 @@ export const WalletSummarySchema = z.object({
             tracked: z.boolean(),
             text: z.string(),
         })),
+        usedCredits: z.number(), // a year, counted against the annual fee
+        usedCreditsText: z.string().nullable(),
         chosen: z
             .object({
             period: z.string(),
@@ -282,6 +286,10 @@ export const OfferComparisonSchema = z.object({
         ineligible: z.string().nullable(),
         bonusValue: z.number(),
         firstYearValue: z.number(),
+        // Statement credits, a year at face value, and the first-year value
+        // if all were used. Not ranked on.
+        credits: z.number(),
+        firstYearValueIfCreditsUsed: z.number(),
         held: z.boolean(),
         lastVerified: z.string(),
         verifiedBy: z.string(),
@@ -381,6 +389,7 @@ export const ExplorationSchema = z.object({
         enroll: z.boolean(),
         note: z.string().nullable(),
         back: z.string(),
+        terms: z.string(),
         earn: z.string(),
         text: z.string(),
         evidence: z.object({ quote: z.string(), url: z.string() }).nullable(),
@@ -413,6 +422,7 @@ export const ExplorationSchema = z.object({
         conditions: z.array(z.string()),
         evidence: z.object({ quote: z.string(), url: z.string() }).nullable(),
         withMembership: z.array(z.object({ membership: z.string(), effectiveReturnPct: z.number() })),
+        needsMembership: z.string().nullable(),
     })),
     excluded: z.array(ExcludedCardSchema),
     assumptions: z.array(z.string()),
@@ -430,7 +440,19 @@ const SimulationSchema = z.object({
         cardIds: z.array(z.string()),
     })),
     membershipFees: z.number(),
+    // Credits the user uses on cards they hold, a year: counted in net.
+    heldCredits: z.number(),
     net: z.number(),
+    // Credits on cards not held, a year at face value: not in net.
+    otherCredits: z.number(),
+    netIfCreditsUsed: z.number(),
+    credits: z.array(z.object({
+        cardId: z.string(),
+        yearly: z.number(),
+        creditIds: z.array(z.string()),
+        names: z.array(z.string()),
+        held: z.boolean(),
+    })),
     lines: z.array(z.object({
         label: z.string(),
         spend: z.number(),
@@ -458,6 +480,8 @@ export const SpendingSimulationSchema = z.object({
         annualFee: z.number(),
         membershipFee: z.number(),
         gain: z.number(),
+        credits: z.number(), // its statement credits, a year: not in gain
+        gainIfCreditsUsed: z.number(),
     })),
 });
 export const CheatSheetSchema = z.object({

package/dist/mcp/tools/account.js

@@ -5,22 +5,59 @@ import { listed } from "../../engine/text.js";
 import { savedSettingsText } from "../../engine/wallet-summary.js";
 import { fail } from "../context.js";
 import { WalletChangeSchema } from "../schemas.js";
+const cardsText = (n) => `${String(n)} ${n === 1 ? 'card' : 'cards'}`;
+// Everything a saved wallet holds, in words; empty when there's nothing.
+const contentsOf = (catalog, w) => [
+    ...(w.cards.length > 0
+        ? [`${cardsText(w.cards.length)} (${w.cards.map((c) => c.id).join(', ')})`]
+        : []),
+    ...savedSettingsText(catalog, w),
+];
+const ImportInput = z.object({
+    yaml: z
+        .string()
+        .min(1)
+        .max(100_000)
+        .describe('The wallet.yaml text, as the user gave it.'),
+    replace: z
+        .boolean()
+        .optional()
+        .describe('true to replace what the wallet already holds, after the user confirms.'),
+});
+export function importHandler(catalog, store, ctx) {
+    const contents = (w) => contentsOf(catalog, w);
+    return {
+        input: ImportInput,
+        run: async ({ yaml, replace }) => {
+            const parsed = parseWalletYaml(yaml, catalog);
+            if (typeof parsed === 'string')
+                return fail(parsed);
+            let current;
+            try {
+                current = await store.load();
+            }
+            catch (e) {
+                if (replace !== true)
+                    return fail(`Couldn't read the saved wallet to check what it holds (${e instanceof Error ? e.message : String(e)}). Ask the user, then call again with replace: true to overwrite it.`);
+                current = null;
+            }
+            const before = current === null ? [] : contents(current);
+            if (before.length > 0 && replace !== true)
+                return fail(`This would replace what's saved: ${listed(before)}. Ask the user, then call again with replace: true.`);
+            return ctx.changed(await store.replace(parsed), before.length > 0
+                ? `Replaced what was saved (${listed(before)}) with the imported wallet: ${listed(contents(parsed))}.`
+                : `Imported a wallet with ${listed(contents(parsed)) || 'nothing in it'}.`, { notes: false });
+        },
+    };
+}
 // A saved wallet on the hosted server has no file to copy or delete, so
 // these do it.
 export function registerAccountTools(server, catalog, store, ctx) {
-    const cardsText = (n) => `${String(n)} ${n === 1 ? 'card' : 'cards'}`;
-    // Everything a saved wallet holds, in words; empty when there's nothing.
-    const contents = (w) => [
-        ...(w.cards.length > 0
-            ? [
-                `${cardsText(w.cards.length)} (${w.cards.map((c) => c.id).join(', ')})`,
-            ]
-            : []),
-        ...savedSettingsText(catalog, w),
-    ];
+    const contents = (w) => contentsOf(catalog, w);
+    const importWallet = importHandler(catalog, store, ctx);
     server.registerTool('export_wallet', {
         title: 'Export the wallet',
-        description: 'The saved wallet as a wallet.yaml file: card ids, checkout labels, picks, activations, opening dates and anniversaries, memberships, point values, cap usage, welcome-bonus progress, yearly spending toward spend bonuses, and statement credits enrolled in and used. earnrate.dev imports it, and the earnrate command line reads it saved as ~/.earnrate/wallet.yaml. Never card numbers.',
+        description: 'The saved wallet as a wallet.yaml file: card ids, checkout labels, picks, activations, opening dates and anniversaries, memberships, point values, cap usage, welcome-bonus progress, yearly spending toward spend bonuses, and statement credits enrolled in, used and not used. earnrate.dev imports it, and the earnrate command line reads it saved as ~/.earnrate/wallet.yaml. Never card numbers.',
         inputSchema: z.object({}),
         outputSchema: z.object({ yaml: z.string() }),
         annotations: {
@@ -42,17 +79,7 @@ export function registerAccountTools(server, catalog, store, ctx) {
     server.registerTool('import_wallet', {
         title: 'Import a wallet',
         description: 'Replaces the saved wallet with a wallet.yaml from the earnrate command line or earnrate.dev, when the user pastes or attaches one. Wallet files only: never statements or card numbers. If anything is already saved (cards, memberships or point values), it refuses unless replace is true: confirm with the user first.',
-        inputSchema: z.object({
-            yaml: z
-                .string()
-                .min(1)
-                .max(100_000)
-                .describe('The wallet.yaml text, as the user gave it.'),
-            replace: z
-                .boolean()
-                .optional()
-                .describe('true to replace what the wallet already holds, after the user confirms.'),
-        }),
+        inputSchema: importWallet.input,
         outputSchema: WalletChangeSchema,
         annotations: {
             title: 'Import a wallet',
@@ -61,26 +88,7 @@ export function registerAccountTools(server, catalog, store, ctx) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ yaml, replace }) => {
-        const parsed = parseWalletYaml(yaml, catalog);
-        if (typeof parsed === 'string')
-            return fail(parsed);
-        let current;
-        try {
-            current = await store.load();
-        }
-        catch (e) {
-            if (replace !== true)
-                return fail(`Couldn't read the saved wallet to check what it holds (${e instanceof Error ? e.message : String(e)}). Ask the user, then call again with replace: true to overwrite it.`);
-            current = null;
-        }
-        const before = current === null ? [] : contents(current);
-        if (before.length > 0 && replace !== true)
-            return fail(`This would replace what's saved: ${listed(before)}. Ask the user, then call again with replace: true.`);
-        return ctx.changed(await store.replace(parsed), before.length > 0
-            ? `Replaced what was saved (${listed(before)}) with the imported wallet: ${listed(contents(parsed))}.`
-            : `Imported a wallet with ${listed(contents(parsed)) || 'nothing in it'}.`, { notes: false });
-    });
+    }, (args) => importWallet.run(args));
     server.registerTool('delete_wallet', {
         title: 'Delete the wallet',
         description: "Deletes the saved wallet and its recovery code now and for good, and signs out every app connected to it, this one included. earnrate.dev and the earnrate command line keep their own wallets and aren't affected. Only when the user asks to delete it: show it with list_wallet, offer export_wallet, and pass confirm, cards and saved only after the user confirms. It refuses if the wallet no longer holds what list_wallet showed, so a retried call can't delete a different wallet.",