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

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

@@ -0,0 +1,159 @@
+---
+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"
+
+Live US credit card data via Brave Search. All commands output JSON for programmatic use.
+
+## 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.3.0/.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.0/.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.0/.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.0}/.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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleece-cli
-Version: 0.2.0
+Version: 0.3.0
 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.0}/cli.py

@@ -309,6 +309,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)
 # ---------------------------------------------------------------------------

{fleece_cli-0.2.0 → fleece_cli-0.3.0}/docs/index.html

@@ -464,7 +464,7 @@
   <div class="hero-inner">
     <div>
       <h1>Find the best card for <span>deal saviors</span></h1>
-      <p>AI-powered credit card research. Live data via Brave Search. Every command outputs clean JSON — built for humans and AI agents alike.</p>
+      <p>AI-powered credit card research and award redemption. Live data via Brave Search, PointsYeah flight and hotel search — every command outputs clean JSON, built for humans and AI agents alike.</p>
       <div class="hero-actions">
         <a class="btn-pill-dark" href="https://github.com/chenyuan99/fleece" target="_blank">
           Get Started
@@ -483,7 +483,7 @@
 
 <!-- FEATURE CARDS -->
 <section class="cards-section" id="features">
-  <div class="cards-inner">
+  <div class="cards-inner" style="grid-template-columns: repeat(3, 1fr);">
 
     <div class="card">
       <svg class="card-icon" viewBox="0 0 60 60" fill="none" xmlns="http://www.w3.org/2000/svg">
@@ -513,6 +513,20 @@
       </a>
     </div>
 
+    <div class="card">
+      <svg class="card-icon" viewBox="0 0 60 60" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path d="M8 38l10-16 6 8 8-12 6 8 10-14" stroke="black" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+        <path d="M6 44h48" stroke="black" stroke-width="2.5" stroke-linecap="round"/>
+        <path d="M38 28l8-4-2 8" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+      </svg>
+      <h3>Redemption</h3>
+      <p>Generate PointsYeah search URLs for award flights and hotels — no API key needed. Pure URL generation, open directly in your browser or pipe into an agent workflow.</p>
+      <a class="btn-arrow" href="#commands" >
+        See commands
+        <svg viewBox="0 0 16 16" fill="none"><path d="M3 8h10M9 4l4 4-4 4" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"/></svg>
+      </a>
+    </div>
+
   </div>
 </section>
 
@@ -559,7 +573,7 @@
 
     <div>
       <h2>CLI Commands</h2>
-      <p>All commands support <code style="font-size:0.9em;background:rgba(0,0,0,0.05);padding:1px 5px;border-radius:3px">--json</code> output and stdin piping via <code style="font-size:0.9em;background:rgba(0,0,0,0.05);padding:1px 5px;border-radius:3px">-</code>.</p>
+      <p>All commands support <code style="font-size:0.9em;background:rgba(0,0,0,0.05);padding:1px 5px;border-radius:3px">--json</code> output. <span style="color:var(--yellow);font-weight:600;">Highlighted</span> commands require no API key.</p>
 
       <div class="cmd-list">
         <div class="cmd-row"><span class="cmd-name">fleece card</span><span class="cmd-desc">Full card report — fees, welcome offer, rates, credits, benefits</span></div>
@@ -571,6 +585,8 @@
         <div class="cmd-row"><span class="cmd-name">fleece wallet</span><span class="cmd-desc">Portfolio analysis — coverage, overlaps, gaps</span></div>
         <div class="cmd-row"><span class="cmd-name">fleece roi</span><span class="cmd-desc">First-year ROI estimate by spend profile</span></div>
         <div class="cmd-row"><span class="cmd-name">fleece recommend</span><span class="cmd-desc">Card recommendations for a spending profile</span></div>
+        <div class="cmd-row"><span class="cmd-name" style="color:var(--yellow)">fleece flights</span><span class="cmd-desc">PointsYeah award flight search URL — no API key needed</span></div>
+        <div class="cmd-row"><span class="cmd-name" style="color:var(--yellow)">fleece hotels</span><span class="cmd-desc">PointsYeah award hotel search URL — no API key needed</span></div>
       </div>
     </div>