fleece-cli 0.2.0__tar.gz → 0.3.1__tar.gz

fleece_cli-0.3.1/.agents/skills/fleece/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: fleece
+description: "What credit card should I use for dining, travel, groceries, or gas?" — Fleece answers this with live data. Looks up rewards rates, annual fees, welcome bonuses, statement credits, and transfer partners for Chase, Amex, Citi, Capital One, Bilt, and all major US issuers. Compare cards side-by-side, find gaps in your wallet, estimate first-year ROI, get personalized card recommendations, and generate PointsYeah award flight and hotel search URLs. Install: `pip install fleece-cli`.
+---
+
+# Fleece — Credit Card Research & Redemption
+
+Use this skill when the user asks about:
+- **Specific cards**: "What are the Amex Gold benefits?", "Is the Chase Sapphire Preferred worth it?", "What changed with the Citi Double Cash?"
+- **Earning rates**: "Which card earns the most on dining?", "What's the best card for groceries?"
+- **Transfer partners**: "Where can I transfer Chase Ultimate Rewards?", "What airlines does Amex transfer to?"
+- **Statement credits**: "How do I use the Amex Gold dining credit?", "What credits does the Venture X have?"
+- **Wallet optimization**: "Which card should I use for travel?", "What gaps does my wallet have?"
+- **Card recommendations**: "Best travel credit card for beginners", "No annual fee cash back card"
+- **ROI / value**: "Is the Amex Platinum worth the $695 fee?", "First-year value of the Sapphire Preferred"
+- **Award redemptions**: "Find business class flights JFK to Tokyo", "Search hotels in Paris with points"
+- **Merchant lookup**: "What card should I use at Costco?", "Which card earns the most at gas stations?", "What MCC is a pharmacy?"
+
+Live US credit card data via Brave Search. All commands output JSON for programmatic use.
+
+## MCC-enriched workflow
+
+The bundled MCC dataset (981 codes, offline) enables a precise end-to-end flow:
+
+```
+fleece wallet          → identify category gaps
+fleece mcc 5411        → confirm "Grocery Stores, Supermarkets"
+fleece mcc 5411 --wallet → find best card for that exact merchant type
+fleece recommend "grocery stores, gas, transit"  → suggest a card to fill the gap
+```
+
+**Common MCCs to know:**
+
+| MCC  | Category | Typical card bonus |
+|------|----------|--------------------|
+| 5411 | Grocery Stores | Amex Gold 4x, BofA Cash Rewards 3% |
+| 5812 | Restaurants | Amex Gold 4x, CSP 3x |
+| 5814 | Fast Food | Varies — not always same as 5812 |
+| 5541 | Gas Stations | Citi Custom Cash 5x, BofA 3% |
+| 4511 | Airlines | Amex Platinum 5x, CSR 3x |
+| 7011 | Hotels | Amex Platinum 5x (Amex Travel), CSR 3x |
+| 4111 | Transit / Commuter | CSR 3x, Bilt 3x |
+| 5912 | Drugstores | Chase Freedom Flex 3x |
+
+Use `fleece mcc <code>` (no API key needed) to resolve any MCC before running a rates or wallet query.
+
+## Prerequisites
+
+```bash
+# Install once
+pip install fleece-cli
+
+# Set in environment or .env file
+export BRAVE_API_KEY=<your_key>
+```
+
+## Commands
+
+### Full card report
+```bash
+fleece card "<card name>" --json
+```
+Returns fees, welcome offer, earning rates, credits, benefits, and strategy.
+
+### Earning rates
+```bash
+fleece rates "<card name>" --json
+fleece rates "<card name>" --category "<dining|travel|groceries|gas>" --json
+```
+
+### Transfer partners
+```bash
+fleece partners "<card name>" --json
+```
+Returns airline and hotel partners with ratios and transfer timing.
+
+### Statement credits
+```bash
+fleece credits "<card name>" --json
+```
+Returns all credits with amounts, cadence, and enrollment requirements.
+
+### Recent news (past month)
+```bash
+fleece news "<card name>" --json
+```
+Freshness-filtered to the past month.
+
+### Side-by-side comparison
+```bash
+fleece compare "<card A>" "<card B>" --json
+fleece compare "<card A>" "<card B>" --aspects "fees,rewards,credits" --json
+```
+
+### Portfolio / wallet analysis
+```bash
+fleece wallet "<card 1>" "<card 2>" "<card 3>" --json
+```
+Returns coverage map, overlaps, gaps, and next-card suggestions.
+
+### First-year ROI
+```bash
+fleece roi "<card name>" --travel <monthly $> --dining <monthly $> --other <monthly $> --json
+```
+
+### Profile-based recommendations
+```bash
+fleece recommend "<spending profile>" --json
+fleece recommend "<spending profile>" --preferences "<preferences>" --json
+```
+
+## Output format
+
+Every command with `--json` returns:
+```json
+{
+  "command": "card",
+  "query": "...",
+  "result": "...",
+  "ok": true,
+  "error": null
+}
+```
+
+On error, `ok` is `false` and `error` contains the message. Always check `ok` before using `result`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Search / tool error (Brave API failure) |
+| `2` | `BRAVE_API_KEY` not set |
+
+## Stdin piping
+
+The primary argument on any single-card command accepts `-` to read from stdin:
+```bash
+echo "Chase Sapphire Preferred" | fleece card - --json
+echo "high dining spend" | fleece recommend - --json
+```
+
+The `wallet` command accepts `-` as its sole argument to read newline-delimited card names:
+```bash
+printf "Amex Gold\nChase Freedom Unlimited\nBilt\n" | fleece wallet - --json
+```
+
+## Coverage
+
+Supports all major US issuers: Amex, Bank of America, Barclays, Bilt, Capital One,
+Chase, Citi, Discover, Robinhood, U.S. Bank, Wells Fargo.
+
+## Redemption — PointsYeah URL generation
+
+No API key required. These commands generate best-effort PointsYeah deep-link URLs
+and optionally open them in the browser. Pure stdlib, no external calls.
+
+### Flight search
+```bash
+fleece flights JFK LAX --date 2026-06-01 --json
+fleece flights JFK LHR --date 2026-06-01 --return 2026-06-15 --adults 2 --cabin business --open
+```
+
+Options: `--date` (required), `--return`, `--adults` (default 1), `--cabin` (economy | premium-economy | business | first), `--open`, `--json`
+
+### Hotel search
+```bash
+fleece hotels "Tokyo" --checkin 2026-06-01 --checkout 2026-06-07 --json
+fleece hotels "Jersey City" --checkin 2026-04-10 --checkout 2026-04-12 --guests 2 --rooms 1 --open
+```
+
+Options: `--checkin` (required), `--checkout` (required), `--guests` (default 1), `--rooms` (default 1), `--open`, `--json`
+
+### JSON output format
+```json
+{
+  "command": "flights",
+  "origin": "JFK", "destination": "LAX", "date": "2026-06-01",
+  "return_date": null, "adults": 1, "cabin": "economy",
+  "url": "https://www.pointsyeah.com/?type=flights&...",
+  "ok": true, "error": null
+}
+```
+
+> PointsYeah does not publish a stable deep-link spec. If the URL stops working,
+> the query parameters still serve as a useful manual search reference.

{fleece_cli-0.2.0 → fleece_cli-0.3.1}/.claude/skills/fleece-compare.md

@@ -29,3 +29,15 @@ fleece compare "Capital One Venture X" "Chase Sapphire Reserve" --json
 ```
 
 After receiving the result, synthesize a clear recommendation based on the user's stated priorities.
+
+## MCC-precise comparison
+
+When comparing two cards on rewards, use `fleece mcc` to identify the exact merchant category first — then compare on that specific category for a more accurate result:
+
+```bash
+# User wants to know which card earns more at Costco (a grocery/wholesale club)
+fleece mcc 5411   # → Grocery Stores, Supermarkets
+
+# Then compare with that category as the focus
+fleece compare "Amex Gold" "Chase Sapphire Preferred" --aspects "grocery rewards,supermarket earning rate" --json
+```

fleece_cli-0.3.1/.claude/skills/fleece-flights.md

@@ -0,0 +1,51 @@
+---
+name: fleece-flights
+description: Generate a PointsYeah flight search URL. No API key required. Use when the user wants to search for award flights or find redemption options for a route.
+---
+
+# /fleece-flights
+
+Generates a PointsYeah flight search URL from origin, destination, and date. No Brave API key needed — pure URL generation.
+
+## When to use
+- User asks to search for award flights on a route
+- User wants to find redemption options after a `fleece wallet` or `fleece partners` analysis
+- User provides an origin, destination, and date and wants to look up availability
+
+## Usage
+
+```bash
+fleece flights <ORIGIN> <DESTINATION> --date <YYYY-MM-DD> --json
+```
+
+**With return date and cabin:**
+```bash
+fleece flights JFK LHR --date 2026-06-01 --return 2026-06-15 --adults 2 --cabin business --json
+```
+
+**Open in browser:**
+```bash
+fleece flights JFK LAX --date 2026-06-01 --open
+```
+
+Cabin options: `economy` | `premium-economy` | `business` | `first` (default: `economy`)
+
+## Output
+
+```json
+{
+  "command": "flights",
+  "origin": "JFK",
+  "destination": "LAX",
+  "date": "2026-06-01",
+  "return_date": null,
+  "adults": 1,
+  "cabin": "economy",
+  "url": "https://www.pointsyeah.com/?type=flights&origin=JFK&destination=LAX&date=2026-06-01&return=&adults=1&cabin=economy",
+  "ok": true,
+  "error": null
+}
+```
+
+> PointsYeah does not publish a stable deep-link spec. If the URL stops resolving,
+> the query parameters still serve as a useful manual search reference.

fleece_cli-0.3.1/.claude/skills/fleece-hotels.md

@@ -0,0 +1,48 @@
+---
+name: fleece-hotels
+description: Generate a PointsYeah hotel search URL. No API key required. Use when the user wants to search for award hotel stays or find redemption options for a destination.
+---
+
+# /fleece-hotels
+
+Generates a PointsYeah hotel search URL from location and dates. No Brave API key needed — pure URL generation.
+
+## When to use
+- User asks to search for award hotel stays at a destination
+- User wants to redeem hotel points after a `fleece wallet` or `fleece partners` analysis
+- User provides a location and dates and wants to look up availability
+
+## Usage
+
+```bash
+fleece hotels "<location>" --checkin <YYYY-MM-DD> --checkout <YYYY-MM-DD> --json
+```
+
+**With guests and rooms:**
+```bash
+fleece hotels "Tokyo" --checkin 2026-06-01 --checkout 2026-06-07 --guests 2 --rooms 1 --json
+```
+
+**Open in browser:**
+```bash
+fleece hotels "Jersey City" --checkin 2026-04-10 --checkout 2026-04-12 --open
+```
+
+## Output
+
+```json
+{
+  "command": "hotels",
+  "location": "Tokyo",
+  "checkin": "2026-06-01",
+  "checkout": "2026-06-07",
+  "guests": 1,
+  "rooms": 1,
+  "url": "https://www.pointsyeah.com/?type=hotels&location=Tokyo&checkin=2026-06-01&checkout=2026-06-07&guests=1&rooms=1",
+  "ok": true,
+  "error": null
+}
+```
+
+> PointsYeah does not publish a stable deep-link spec. If the URL stops resolving,
+> the query parameters still serve as a useful manual search reference.

fleece_cli-0.3.1/.claude/skills/fleece-mcc.md

@@ -0,0 +1,65 @@
+---
+name: fleece-mcc
+description: Look up a Merchant Category Code (MCC) and find the best card in the user's wallet to use at that merchant. No API key needed for basic lookup; BRAVE_API_KEY needed for wallet cross-reference. Use when the user asks "what card should I use at [merchant]?" or provides an MCC code.
+---
+
+# /fleece-mcc
+
+Looks up an MCC code from the bundled dataset (981 codes, offline) and optionally cross-references with the user's saved wallet to find the highest-earning card.
+
+## When to use
+- User asks "what card should I use at [merchant type]?" and you know or can infer the MCC
+- User provides an MCC code directly and wants to know the category
+- User wants to know which card earns most at a specific merchant category
+- After `fleece wallet` identifies a gap, find which MCC codes fall into that gap
+
+## Usage
+
+**Basic lookup (no API key needed):**
+```bash
+fleece mcc 5812
+# → MCC 5812: Eating Places, Restaurants
+```
+
+**With wallet cross-reference (requires BRAVE_API_KEY):**
+```bash
+fleece mcc 5812 --wallet --json
+fleece mcc 5411 --wallet --json   # Grocery Stores
+fleece mcc 5541 --wallet --json   # Service Stations (gas)
+fleece mcc 4111 --wallet --json   # Transportation / Commuter
+```
+
+## Common MCCs
+
+| MCC  | Category |
+|------|----------|
+| 5411 | Grocery Stores, Supermarkets |
+| 5812 | Eating Places, Restaurants |
+| 5541 | Service Stations (gas) |
+| 5912 | Drug Stores, Pharmacies |
+| 5310 | Discount Stores |
+| 5732 | Electronics Stores |
+| 4111 | Transportation / Commuter |
+| 4411 | Cruise Lines |
+| 7011 | Hotels, Motels, Resorts |
+| 4511 | Airlines, Air Carriers |
+
+## Output (--json)
+
+```json
+{
+  "command": "mcc",
+  "mcc": "5812",
+  "category": "Eating Places, Restaurants",
+  "irs_description": "Restaurants",
+  "ok": true,
+  "error": null
+}
+```
+
+With `--wallet`, returns live research on earning rates per card plus a recommendation for the best card to use.
+
+## Notes
+- Dataset is bundled with `fleece-cli` — works fully offline for basic lookups
+- Source: github.com/greggles/mcc-codes (981 codes)
+- `--wallet` mode requires cards saved via `fleece cards add`

{fleece_cli-0.2.0 → fleece_cli-0.3.1}/.claude/skills/fleece-rates.md

@@ -27,3 +27,13 @@ Categories: `dining`, `travel`, `groceries`, `gas`, `streaming`, `drugstores`, e
 fleece rates "Chase Sapphire Preferred" --json
 fleece rates "Amex Gold" --category dining --json
 ```
+
+## MCC precision tip
+
+Category names like `dining` are broad — a card may earn differently at MCC 5812 (sit-down restaurants) vs 5814 (fast food) vs 5411 (grocery stores with a café). When exact merchant-level precision matters, pair with `fleece mcc`:
+
+```bash
+# Confirm the MCC for the merchant type, then look up the rate
+fleece mcc 5814   # → Fast Food Restaurants
+fleece rates "Amex Gold" --category "fast food restaurants" --json
+```

{fleece_cli-0.2.0 → fleece_cli-0.3.1}/.claude/skills/fleece-recommend.md

@@ -30,3 +30,19 @@ fleece recommend "frequent international traveler" --preferences "priority pass
 ```
 
 After receiving results, present 2–3 top recommendations with a brief rationale for each.
+
+## MCC-informed spending profiles
+
+For more precise recommendations, identify the MCC codes for the user's top merchants first, then describe the profile by category name:
+
+```bash
+# User shops at Whole Foods (5411), commutes by subway (4111), eats out often (5812)
+fleece mcc 5411   # → Grocery Stores, Supermarkets
+fleece mcc 4111   # → Transportation / Commuter
+fleece mcc 5812   # → Eating Places, Restaurants
+
+# Then recommend based on confirmed categories
+fleece recommend "grocery stores, transit, restaurants" --json
+```
+
+This avoids vague profiles like "I spend a lot on food" and maps the user's real spend to known card bonus categories.

{fleece_cli-0.2.0 → fleece_cli-0.3.1}/.claude/skills/fleece-wallet.md

@@ -60,3 +60,20 @@ fleece wallet
 # Explicit cards
 fleece wallet "Amex Gold" "Chase Sapphire Preferred" "Citi Double Cash"
 ```
+
+## MCC-enriched gap analysis
+
+After `fleece wallet` identifies a gap (e.g., "no bonus on grocery stores"), use `fleece mcc` to drill into the precise merchant category and find the best card for it:
+
+```bash
+# Wallet says "gap on groceries" → confirm the MCC and cross-reference wallet
+fleece mcc 5411 --wallet --json   # Grocery Stores, Supermarkets
+
+# Other common gap MCCs to check after a wallet analysis
+fleece mcc 5541 --wallet          # Gas stations
+fleece mcc 5912 --wallet          # Drugstores / pharmacies
+fleece mcc 4111 --wallet          # Transit / commuter
+fleece mcc 5812 --wallet          # Restaurants
+```
+
+This turns a vague "gap on groceries" into a precise card recommendation for a specific merchant category.

{fleece_cli-0.2.0 → fleece_cli-0.3.1}/.github/workflows/publish.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -19,7 +19,7 @@ jobs:
 
       - run: python -m build
 
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v6
         with:
           name: dist
           path: dist/
@@ -31,7 +31,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v6
         with:
           name: dist
           path: dist/

{fleece_cli-0.2.0 → fleece_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleece-cli
-Version: 0.2.0
+Version: 0.3.1
 Summary: Credit card research and redemption CLI — live data via Brave Search, PointsYeah URL generation, designed for humans and AI agents.
 Author-email: Yuan Chen <cysbc1999@gmail.com>
 License: MIT

{fleece_cli-0.2.0 → fleece_cli-0.3.1}/cli.py

@@ -4,10 +4,13 @@ Fleece CLI — agent-friendly companion to the Fleece Streamlit chatbot.
 Exposes credit card research tools as shell commands backed by Brave Search.
 Designed for use by AI agents (Claude Code, Codex) and humans alike.
 
+BRAVE_API_KEY is optional — commands that don't need live search (mcc, flights,
+hotels) work fully offline. Research commands (card, rates, wallet, …) require it.
+
 Exit codes:
   0  success
   1  search / tool error
-  2  configuration error (missing API key)
+  2  BRAVE_API_KEY required but not set
 """
 import json
 import sys
@@ -18,7 +21,11 @@ from dotenv import load_dotenv
 
 app = typer.Typer(
     name="fleece",
-    help="Fleece credit card research CLI — live data via Brave Search.",
+    help=(
+        "Fleece credit card research CLI — live data via Brave Search.\n\n"
+        "BRAVE_API_KEY is optional: mcc, flights, and hotels work offline.\n"
+        "Research commands (card, rates, wallet, …) require it."
+    ),
     no_args_is_help=True,
 )
 
@@ -27,20 +34,21 @@ app = typer.Typer(
 # ---------------------------------------------------------------------------
 
 def _resolve_key(api_key: Optional[str], no_dotenv: bool) -> str:
-    """Load env and return the Brave API key, or exit with code 2."""
+    """Load env and return the Brave API key (may be empty — checked at use time)."""
     import os
     if not no_dotenv:
         load_dotenv()
-    key = api_key or os.getenv("BRAVE_API_KEY", "")
+    return api_key or os.getenv("BRAVE_API_KEY", "")
+
+
+def _get_wrapper(key: str, freshness: Optional[str] = None):
     if not key:
         _error_exit(
-            "BRAVE_API_KEY not set. Pass --api-key or add it to .env.",
+            "BRAVE_API_KEY is required for live research. "
+            "Set it in your environment, add it to .env, or pass --api-key. "
+            "Commands mcc, flights, and hotels work without it.",
             code=2,
         )
-    return key
-
-
-def _get_wrapper(key: str, freshness: Optional[str] = None):
     from tools.brave_client import build_brave_wrapper
     return build_brave_wrapper(key, freshness=freshness)
 
@@ -309,6 +317,87 @@ def recommend(
     _run_search(_get_wrapper(key), query, "recommend", as_json)
 
 
+# ---------------------------------------------------------------------------
+# MCC lookup — offline, no API key required
+# ---------------------------------------------------------------------------
+
+def _load_mcc_db() -> dict[str, dict]:
+    """Load mcc_codes.jsonl bundled with the package. Returns {mcc: record}."""
+    import importlib.resources, pathlib
+    # Try installed package data first, fall back to local file
+    for candidate in [
+        pathlib.Path(__file__).parent / "mcc_codes.jsonl",
+    ]:
+        if candidate.exists():
+            data = {}
+            for line in candidate.read_text().splitlines():
+                line = line.strip()
+                if line:
+                    rec = json.loads(line)
+                    data[str(rec["mcc"]).zfill(4)] = rec
+            return data
+    _error_exit("mcc_codes.jsonl not found. Re-install fleece-cli.", code=1)
+
+
+@app.command()
+def mcc(
+    code:     Annotated[str, typer.Argument(help="4-digit MCC code, e.g. 5812.")],
+    wallet:   Annotated[bool, typer.Option("--wallet", "-w", help="Cross-reference with your saved cards.")] = False,
+    api_key:  ApiKeyOpt  = None,
+    as_json:  JsonOpt    = False,
+    no_dotenv: NoDotenv  = False,
+):
+    """Look up a Merchant Category Code and find the best card in your wallet to use."""
+    code = code.strip().zfill(4)
+    db = _load_mcc_db()
+
+    if code not in db:
+        _error_exit(f"MCC {code} not found in dataset.", code=1)
+
+    rec = db[code]
+    category = rec.get("edited_description") or rec.get("combined_description", "Unknown")
+    irs_desc = rec.get("irs_description", "")
+
+    if not wallet:
+        if as_json:
+            typer.echo(json.dumps({"command": "mcc", "mcc": code, "category": category,
+                                   "irs_description": irs_desc, "ok": True, "error": None}))
+        else:
+            typer.echo(f"MCC {code}: {category}")
+            if irs_desc and irs_desc != category:
+                typer.echo(f"IRS description: {irs_desc}")
+        return
+
+    # Wallet mode — look up earning rates for each card in the profile
+    card_names = _profile_card_names()
+    if not card_names:
+        _error_exit("No cards in profile. Add cards with: fleece cards add \"<name>\"", code=1)
+
+    key = _resolve_key(api_key, no_dotenv)
+    from tools.brave_client import search_and_format
+    wrapper = _get_wrapper(key)
+
+    parts = []
+    try:
+        for name in card_names:
+            result = search_and_format(
+                wrapper,
+                f'"{name}" credit card earning rate "{category}" OR "{irs_desc}" category multiplier 2025',
+                max_results=2,
+            )
+            parts.append(f"### {name}\n{result}")
+    except Exception as e:
+        _error_exit(str(e), code=1)
+
+    combined = (
+        f"MCC {code}: {category}\n\n"
+        + "\n\n".join(parts)
+        + f"\n\nBased on the above, which card earns the most at merchants coded as MCC {code} ({category})? "
+        "Show the multiplier for each card and pick the winner."
+    )
+    _emit(combined, as_json, "mcc", code)
+
+
 # ---------------------------------------------------------------------------
 # Redemption — PointsYeah URL generation (no API key required)
 # ---------------------------------------------------------------------------