earnrate 0.1.1 → 0.1.3

package/README.md

@@ -9,23 +9,26 @@ I wanted a ghost card: one card that always charges the best of my cards. The ca
 
 **earnrate is the best-card decision layer for people and AI agents.** Give it a merchant, and it tells you which card in your wallet earns the most there, and why. It's stateful (it knows your caps and chosen categories), valuation-aware, and transparent about its assumptions. It never sees a card number.
 
-- Runs on your machine. No account, no telemetry, no affiliate links.
+- Runs on your machine, or in your browser at [earnrate.dev](https://earnrate.dev) with nothing to install. No account, no telemetry, no affiliate links. See the [privacy page](https://earnrate.dev/privacy).
 - US cards and US merchants, for now.
 
 > **Status:** early, and it works: the engine, CLI, optional Claude merchant lookup and MCP server. See [the benchmark](docs/benchmark.md) for how it compares to an existing card-picking MCP server.
 
 ## Try it
 
-Needs Node 24 or later.
+Needs Node 22 or later.
 
 ```sh
 npm install -g earnrate
-mkdir -p ~/.earnrate
-curl -o ~/.earnrate/wallet.yaml https://raw.githubusercontent.com/cwasley/earnrate/main/wallet.example.yaml
+earnrate cards sapphire            # find your cards' ids
+earnrate add chase-sapphire-preferred
+earnrate add amex-gold
 earnrate whole foods 80
 ```
 
-Then edit `~/.earnrate/wallet.yaml` to list your own cards (see [Your wallet](#your-wallet)).
+Adding a card tells you anything else it needs to earn correctly, such as the categories you picked on Cash+, Amazon Prime for Prime Visa's 5%, or which rotating categories you've activated. `earnrate update` sets those. Using an AI assistant instead? [Add the MCP server](#use-it-from-an-ai-agent-mcp) and tell it which cards you have.
+
+With the [example wallet](wallet.example.yaml), it prints:
 
 ```
 Whole Foods Market · $80
@@ -50,7 +53,7 @@ Options: `--online` or `--in-store`, `--valuation flat|points-heavy`, `--all`, `
 
 ### Your wallet
 
-The wallet is a YAML file listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). Only the cards are required:
+The wallet is a YAML file (`~/.earnrate/wallet.yaml`) listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). `earnrate add`, `update`, `remove` and `memberships` write it for you and keep your comments, or you can edit it by hand. Only the cards are required:
 
 ```yaml
 valuations:
@@ -95,6 +98,16 @@ While the bonus is open, that card wins wherever it's accepted, and the answer s
 
 ### Which new card?
 
+No wallet needed for these:
+
+```sh
+earnrate best groceries                               # every card, ranked for one purchase
+earnrate simulate groceries=600 dining=300 other=1000 # best cards and pairs for a year
+earnrate simulate groceries=600 other=1000 --wallet   # what a new card would add to yours
+```
+
+`best` ranks every card earnrate knows for a merchant or a category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Rates that need a membership like Amazon Prime are listed separately unless you pass `--member amazon-prime`. `simulate` spends your monthly amounts for a year, applying caps as they fill and reset, and ranks single cards and two-card pairs by rewards minus annual fees. Both take `--no-fee`, `--cash` or `--points`, `--issuer`, `--business` and `--valuation`. Welcome bonuses are left out of both; for those:
+
 ```sh
 earnrate offers --cash
 ```
@@ -139,13 +152,17 @@ Spotted a wrong rate, or want a card added? [Open an issue](https://github.com/c
 
 ## Use it from an AI agent (MCP)
 
-`earnrate mcp` runs earnrate as a local MCP server over stdio, with five tools:
+`earnrate mcp` runs earnrate as a local MCP server over stdio, with twelve tools:
 
 - `best_card_for_purchase`: which card to use, with reasons
+- `best_cards_for` and `simulate_spending`: compare every card earnrate knows, for one purchase or a year of spending, with no wallet needed
 - `resolve_merchant`: how a merchant was identified
 - `list_wallet`: your cards, caps left this period, chosen categories and welcome-bonus progress
 - `compare_welcome_offers`: the best public sign-up offers on cards you don't have
 - `record_purchase`: books a purchase against its cap and any open welcome bonus in your wallet file, keeping your comments
+- `search_cards`, `add_card`, `update_card`, `remove_card` and `set_memberships`: set up the wallet in conversation
+
+There's no wallet to write first: tell the assistant which cards you have, and it finds them, adds them, and asks about anything a card needs, like this quarter's Cash+ picks.
 
 For a merchant earnrate doesn't know, the calling model can pass a `category` (e.g. `grocery.supermarket`). It's used only for unknown merchants and is labeled in the answer. The command line takes the same thing as `--category`.
 
@@ -179,8 +196,8 @@ merchant text
 
 - **Card terms are data, not code.** Each card is a YAML file of rules (category, rate, cap, channel, dates, activation, required membership), validated with Zod. Every rule carries a short quote from the issuer's own page, and a test fails if one is missing. The engine has no card-specific branches.
 - **Merchants resolve to a category plus the assumption behind it.** "Whole Foods codes as a supermarket (MCC 5411)" is stated in the answer, and venues that can code more than one way (a restaurant inside a stadium or hotel) come back at medium confidence with the alternative spelled out. Unknown merchants fall back to base rates, or to an opt-in, cached and labeled Claude guess.
-- **The engine is pure and deterministic.** Given a purchase, a date and a wallet, it checks every rule against network acceptance, the date window, caps already used (split when a purchase straddles one), quarterly picks and activations, then values points at your cents-per-point, including pooling (Freedom Unlimited points are worth Sapphire points when you hold both). Ties, the valuation at which the runner-up would win, and stale data all show up in the answer.
-- **Wallet edits keep your file intact.** Recording a purchase rewrites only the numbers that changed, so comments and formatting in your YAML survive.
+- **The engine is pure and deterministic.** Given a purchase, a date and a wallet, it checks every rule against network acceptance, the date window, caps already used (split when a purchase straddles one), quarterly picks and activations, then values points at your cents-per-point, including pooling (Freedom Unlimited points are worth Sapphire points when you hold both). Ties, the valuation at which the runner-up would win, stale data, and a rotating card whose new quarter isn't in the data yet all show up in the answer.
+- **Wallet edits keep your file intact.** Adding or changing a card, or recording a purchase, splices in only the lines that changed and checks the result before saving, so comments and formatting in your YAML survive.
 - **Drift detection.** A weekly GitHub Action opens each issuer page in a headless browser, checks every quote is still there, and opens an issue when terms move. It stores only hashes of issuer text.
 - **Tested end to end.** Golden cases written from issuer terms, CLI snapshot tests, an MCP round trip over real stdio, an install test that packs and installs the npm package, and a check that no committed file contains a card number. CI runs all of it on every push.
 
@@ -195,6 +212,8 @@ Every rule in `data/cards/` carries a short quote from the issuer's own page. In
 
 A GitHub Action runs it every Monday and opens a "Card source changes" issue when something moved. After updating a card file, run `yarn check-sources --update` to record the new baseline. Some issuers block headless browsers on shared servers; those pages are listed as "couldn't check", and running the command locally covers them. The first run needs `yarn playwright install chromium`.
 
+Rotating categories (Freedom Flex) are added each quarter once the issuer posts them. Until then, answers say that quarter's categories are missing rather than guessing.
+
 ## Working on earnrate
 
 ```sh

package/data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Every change to card rules, merchants, categories or currencies under `data/`. Bump `data/VERSION` (`YYYY.MM.DD`, plus `.N` for a second release on the same day) and add a section here in the same commit. Each row cites the issuer page the new value came from.
 
+## 2026.10.30.2
+
+Cards record when the issuer stopped taking applications, so "best card for" lists can leave out cards nobody can get. Categories gain `aliases`, the everyday words people search by ("groceries" finds supermarkets). No rates changed.
+
+| Card             | Field               | Old → new  | Source                                                                      |
+| ---------------- | ------------------- | ---------- | --------------------------------------------------------------------------- |
+| citi-custom-cash | applications_closed | 2026-05-28 | [card page](https://www.citi.com/credit-cards/citi-custom-cash-credit-card) |
+
+## 2026.10.30.1
+
+Freedom Flex's quarterly cap is marked `rotating`, so a quarter whose categories aren't in the data yet gets a warning instead of quietly ranking Flex at its everyday rates. Capital One's issuer id is now spelled the same on every card. No rates changed.
+
+| Card                                                          | Field                       | Old → new                | Source |
+| ------------------------------------------------------------- | --------------------------- | ------------------------ | ------ |
+| chase-freedom-flex                                            | caps.five-percent-quarterly | adds `rotating`          | n/a    |
+| capital-one-venture-x, capital-one-venture, capital-one-savor | issuer                      | capitalone → capital-one | n/a    |
+
 ## 2026.10.28.2
 
 Bank of America Customized Cash Rewards, reviewed by Collin (`verified_by: collin`). Choice options can now be "any online purchase except these categories", and a choice period can be `until_changed` for picks that carry over.

package/data/VERSION

@@ -1 +1 @@
-2026.10.28.2
+2026.10.30.2

package/data/cards/capital-one-savor.yaml

@@ -1,6 +1,6 @@
 id: capital-one-savor
 name: Capital One Savor Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 # The card page never names the network in visible text; its embedded
 # product data says MasterCard.
 network: mastercard

package/data/cards/capital-one-venture-x.yaml

@@ -1,6 +1,6 @@
 id: capital-one-venture-x
 name: Capital One Venture X Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 network: visa # Visa Infinite, per the card page's footnotes
 currency: C1
 last_verified: 2026-10-26

package/data/cards/capital-one-venture.yaml

@@ -1,6 +1,6 @@
 id: capital-one-venture
 name: Capital One Venture Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 # The card page never names the network in visible text. Its embedded product
 # data says MasterCard; older Venture accounts may be on Visa.
 network: mastercard

package/data/cards/chase-freedom-flex.yaml

@@ -31,6 +31,7 @@ caps:
     amount: 1500
     period: quarter
     then_rate: 1
+    rotating: true
 rules:
   - id: chase-travel
     match: { merchants: [chase-travel] }

package/data/cards/citi-custom-cash.yaml

@@ -5,9 +5,10 @@ network: mastercard
 currency: cash
 last_verified: 2026-10-26
 verified_by: collin
-# Citi stopped taking applications on May 28, 2026; existing cardmembers keep
-# the card and its rewards. The card page no longer lists the categories, so
-# the definitions come from the card's current ThankYou terms (Sept 2026).
+applications_closed: 2026-05-28
+# Existing cardmembers keep the card and its rewards. The card page no longer
+# lists the categories, so the definitions come from the card's current
+# ThankYou terms (Sept 2026).
 source_urls:
   - https://www.citi.com/credit-cards/citi-custom-cash-credit-card
   - https://www.thankyou.com/ccterms

package/data/categories.yaml

@@ -5,24 +5,30 @@
 
 - id: dining
   name: Restaurants
+  aliases: [dining, restaurant, food, eating out, takeout]
   mccs: [5812, 5813, 5814]
 - id: dining.fast_food
   name: Fast food
+  aliases: [fast food restaurants]
   mccs: [5814]
 
 - id: grocery
   name: Grocery
 - id: grocery.supermarket
   name: Supermarkets
+  aliases: [groceries, grocery, grocery stores, supermarket]
   mccs: [5411]
 - id: grocery.online
   name: Online grocery and delivery
+  aliases: [grocery delivery]
 
 - id: superstore
   name: Superstores
+  aliases: [superstore, big box stores]
   mccs: [5310]
 - id: warehouse_club
   name: Warehouse clubs
+  aliases: [warehouse club, wholesale clubs]
   mccs: [5300]
 
 - id: convenience_store
@@ -31,6 +37,7 @@
 
 - id: gas
   name: Gas stations
+  aliases: [gas, fuel, gas station]
   mccs: [5541, 5542]
 - id: gas.grocery_store
   name: Gas at grocery stores
@@ -38,6 +45,7 @@
   name: Gas at superstores and warehouse clubs
 - id: ev_charging
   name: EV charging
+  aliases: [ev, charging]
   mccs: [5552]
 
 - id: transit
@@ -45,6 +53,7 @@
   mccs: [4111, 4112, 4131, 4784, 7523]
 - id: transit.rideshare
   name: Rideshare and taxis
+  aliases: [rideshare, taxi, taxis]
   mccs: [4121]
 
 - id: travel
@@ -52,41 +61,53 @@
   mccs: [4722]
 - id: travel.flights
   name: Flights
+  aliases: [flights, airfare, airlines]
   mccs: [4511]
 - id: travel.hotels
   name: Hotels
+  aliases: [hotel]
   mccs: [7011]
 - id: travel.car_rental
   name: Car rental
+  aliases: [car rentals, rental cars]
   mccs: [7512]
 - id: travel.cruise
   name: Cruises
+  aliases: [cruise]
   mccs: [4411]
 
 - id: streaming
   name: Streaming services
+  aliases: [streaming, subscriptions]
   mccs: [4899, 5815]
 - id: tv_internet
   name: TV and internet service
+  aliases: [internet, cable]
   mccs: [4899]
 - id: phone
   name: Cell phone service
+  aliases: [phone, cell phone, wireless]
   mccs: [4814]
 - id: utilities
   name: Home utilities
+  aliases: [utilities, electric, electricity]
   mccs: [4900]
 
 - id: drugstore
   name: Drugstores and pharmacies
+  aliases: [drugstores, pharmacy, pharmacies]
   mccs: [5912]
 - id: movie_theaters
   name: Movie theaters
+  aliases: [movies, movie theater]
   mccs: [7832]
 - id: entertainment
   name: Live entertainment and events
+  aliases: [concerts, events, tickets]
   mccs: [7922, 7941]
 - id: fitness
   name: Gyms and fitness
+  aliases: [gym, gyms, fitness]
   mccs: [7997]
 
 - id: department_store
@@ -103,6 +124,7 @@
   mccs: [5941]
 - id: home_improvement
   name: Home improvement
+  aliases: [hardware stores]
   mccs: [5200, 5211]
 - id: furniture
   name: Furniture stores
@@ -110,6 +132,7 @@
 
 - id: online_retail
   name: Online retail
+  aliases: [online shopping, shopping online]
 - id: office_supply
   name: Office supply stores
 - id: shipping
@@ -119,3 +142,4 @@
 
 - id: other
   name: Everything else
+  aliases: [everything, everything else, other]

package/dist/cli/cards.js

@@ -0,0 +1,34 @@
+const NETWORKS = {
+    visa: 'Visa',
+    mastercard: 'Mastercard',
+    amex: 'Amex',
+    discover: 'Discover',
+    store: 'store card',
+};
+export function formatCardInfo(card) {
+    const fee = card.annualFee === null
+        ? ''
+        : card.annualFee === 0
+            ? ', no annual fee'
+            : `, $${String(card.annualFee)} a year`;
+    const needs = [
+        ...card.choices.map((c) => `${c.id}: pick ${String(c.pick)} of ${c.options.join(', ')}${c.default ? ` (default ${c.default.join(', ')})` : ''}`),
+        ...(card.memberships.length > 0
+            ? [`rates that need a membership: ${card.memberships.join(', ')}`]
+            : []),
+        ...(card.activation.length > 0
+            ? [`activate with the issuer: ${card.activation.join(', ')}`]
+            : []),
+        ...(card.needsAnniversary ? ['cap resets on the card anniversary'] : []),
+        ...(card.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
+    ];
+    return [
+        `${card.id}: ${card.name} (${NETWORKS[card.network]}${fee})${card.held ? ' [in wallet]' : ''}`,
+        ...needs.map((n) => `    ${n}`),
+    ].join('\n');
+}
+export function formatNotes(notes) {
+    return notes.length === 0
+        ? 'Nothing else to set up for it.'
+        : `Still to set:\n${notes.map((n) => `- ${n.text}`).join('\n')}`;
+}