fablazing-cli 0.1.0__py3-none-any.whl

fablazing_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

fablazing_cli/client.py

@@ -0,0 +1,52 @@
+"""HTTP client for the v1 API. Exits 1 on API errors, 3 on quota."""
+import httpx
+
+from . import __version__
+from .config import api_key, api_url
+from .output import fail
+
+
+def get(path: str, params: dict | None = None) -> dict:
+    key = api_key()
+    if not key:
+        fail(
+            "no API key configured. Run: fablazing auth set-key  "
+            "(or set the FABLAZING_API_KEY environment variable)"
+        )
+
+    clean = {}
+    for name, value in (params or {}).items():
+        if value is None or value == []:
+            continue
+        clean[name] = value
+
+    url = f"{api_url()}{path}"
+    try:
+        response = httpx.get(
+            url,
+            params=clean,
+            headers={
+                "Authorization": f"Bearer {key}",
+                "User-Agent": f"fablazing-cli/{__version__}",
+            },
+            timeout=120,
+        )
+    except httpx.HTTPError as exc:
+        fail(f"cannot reach the API at {api_url()}: {exc}")
+
+    if response.status_code == 401:
+        fail("invalid or revoked API key (401). Run: fablazing auth set-key")
+    if response.status_code == 429:
+        detail = _detail(response) or "rate limited"
+        fail(f"{detail}", 3)
+    if response.status_code >= 400:
+        fail(f"API error {response.status_code}: {_detail(response)}")
+
+    return response.json()
+
+
+def _detail(response: httpx.Response) -> str:
+    try:
+        return response.json().get("detail", "")
+    except ValueError:
+        return response.text[:200]

fablazing_cli/commands/auth.py

@@ -0,0 +1,43 @@
+"""API key management."""
+import typer
+
+from .. import client
+from ..config import api_key, api_url, config_path, load_config, save_config
+from ..output import console, fail
+
+app = typer.Typer(help="API key management")
+
+
+@app.command("set-key")
+def set_key(key: str = typer.Argument(None, help="Your fbl_live_... API key")):
+    """Store your API key (prompted securely if not passed as an argument)."""
+    if not key:
+        key = typer.prompt("API key", hide_input=True)
+    key = key.strip()
+    if not key.startswith("fbl_live_"):
+        fail("that doesn't look like a Fablazing API key (expected fbl_live_...)", 2)
+    cfg = load_config()
+    cfg["api_key"] = key
+    save_config(cfg)
+    console.print(f"Key saved to {config_path()}")
+
+
+@app.command("set-url")
+def set_url(url: str = typer.Argument(..., help="API base URL (for self-hosted/dev)")):
+    """Point the CLI at a different API base URL."""
+    cfg = load_config()
+    cfg["api_url"] = url.rstrip("/")
+    save_config(cfg)
+    console.print(f"API URL set to {cfg['api_url']}")
+
+
+@app.command()
+def status():
+    """Verify the configured key against the API."""
+    key = api_key()
+    if not key:
+        fail("no API key configured. Run: fablazing auth set-key")
+    masked = key[:15] + "..."
+    heroes = client.get("/heroes")
+    count = heroes.get("meta", {}).get("count", "?")
+    console.print(f"[green]OK[/green] key {masked} against {api_url()} ({count} heroes visible)")

fablazing_cli/commands/card.py

@@ -0,0 +1,141 @@
+"""Card search, metadata, trends, synergies, popularity."""
+import typer
+
+from .. import client, resolve
+from ..output import console, emit, pct, set_mode
+
+app = typer.Typer(help="Card catalog and analytics")
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Part of a card name"),
+    limit: int = typer.Option(25, "--limit", min=1, max=100),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Search cards and equipment by name."""
+    set_mode(json_, csv_)
+    payload = client.get("/cards/search", {"q": query, "limit": limit})
+    rows = [
+        [
+            c.get("card_id", ""),
+            c.get("card_name", ""),
+            c.get("pitch_value", ""),
+            "equipment" if c.get("is_equipment") else "card",
+            c.get("class", ""),
+            f"${c['tcg_market_price']:.2f}" if c.get("tcg_market_price") else "-",
+        ]
+        for c in payload["data"]
+    ]
+    emit(payload, tables=[("Results", ["ID", "Name", "Pitch", "Kind", "Class", "Price"], rows)])
+
+
+@app.command()
+def show(
+    card: str = typer.Argument(..., help="Card id or name"),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Show one card's metadata."""
+    set_mode(json_, csv_)
+    card_id = resolve.card_id(card)
+    payload = client.get(f"/cards/{card_id}")
+    data = payload["data"]
+    rows = [
+        [field, str(data.get(field, ""))]
+        for field in (
+            "card_id", "card_name", "kind", "pitch_value", "cost", "power",
+            "defense", "class", "rarity", "tcg_market_price", "default_set_name",
+        )
+        if data.get(field) not in (None, "")
+    ]
+    emit(payload, tables=[(data.get("card_name", card_id), ["Field", "Value"], rows)])
+    if data.get("text"):
+        console.print(f"[dim]{data['text']}[/dim]")
+
+
+@app.command()
+def trends(
+    card: str = typer.Argument(..., help="Card id or name"),
+    format_type: str = typer.Option("cc", "--format"),
+    days: int = typer.Option(30, "--days", min=1, max=365),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Daily play-rate time series."""
+    set_mode(json_, csv_)
+    card_id = resolve.card_id(card)
+    payload = client.get(f"/cards/{card_id}/trends", {"format": format_type, "days": days})
+    data = payload["data"]
+    points = data.get("data_points") or data.get("trends") or []
+    rows = [
+        [
+            p.get("date", ""),
+            pct(p.get("deck_frequency")),
+            p.get("deck_count", ""),
+            p.get("match_count", ""),
+        ]
+        for p in points
+    ]
+    summary = []
+    if data.get("trend_direction"):
+        summary.append(
+            f"[bold]{card_id}[/bold] ({format_type}, {days}d): trend {data['trend_direction']}"
+            + (f", change {data.get('percent_change'):+.1f}%" if data.get("percent_change") is not None else "")
+        )
+    emit(payload, tables=[("Daily", ["Date", "Deck freq", "Decks", "Matches"], rows)], summary=summary)
+
+
+@app.command()
+def synergies(
+    card: str = typer.Argument(..., help="Card id or name"),
+    format_type: str = typer.Option("cc", "--format"),
+    limit: int = typer.Option(20, "--limit", min=1, max=50),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Co-occurrence synergy partners, with scores."""
+    set_mode(json_, csv_)
+    card_id = resolve.card_id(card)
+    payload = client.get(f"/cards/{card_id}/synergies", {"format": format_type, "limit": limit})
+    rows = [
+        [
+            s.get("card_id", ""),
+            s.get("card_name", ""),
+            f"{s.get('synergy_score', 0):.3f}",
+            s.get("co_occurrence_count", ""),
+            f"${s['tcg_market_price']:.2f}" if s.get("tcg_market_price") else "-",
+        ]
+        for s in payload["data"].get("synergies", [])
+    ]
+    emit(payload, tables=[(f"Synergies for {card_id}", ["ID", "Name", "Score", "Co-occur", "Price"], rows)])
+
+
+@app.command()
+def popular(
+    format_type: str = typer.Option("cc", "--format"),
+    days: int = typer.Option(7, "--days", min=1, max=365),
+    limit: int = typer.Option(25, "--limit", min=1, max=100),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Most-played cards over the window."""
+    set_mode(json_, csv_)
+    payload = client.get("/cards/popular", {"format": format_type, "days": days, "limit": limit})
+    rows = [
+        [
+            c.get("rank", ""),
+            c.get("card_id", ""),
+            c.get("card_name", ""),
+            pct(c.get("avg_deck_frequency")),
+            c.get("total_deck_count", ""),
+            c.get("total_matches", ""),
+        ]
+        for c in payload["data"].get("cards", [])
+    ]
+    emit(
+        payload,
+        tables=[("Popular cards", ["#", "ID", "Name", "Deck freq", "Decks", "Matches"], rows)],
+        summary=[f"[bold]Most played[/bold] - {format_type}, last {days}d"],
+    )

fablazing_cli/commands/hero.py

@@ -0,0 +1,91 @@
+"""Hero catalog + pre-computed matchup aggregates."""
+import typer
+
+from .. import client, resolve
+from ..output import emit, pct, set_mode
+
+app = typer.Typer(help="Heroes and their matchup tables")
+
+
+@app.command("list")
+def list_heroes(
+    hero_class: str = typer.Option(None, "--class", help="Filter by class, e.g. Mechanologist"),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """List all heroes."""
+    set_mode(json_, csv_)
+    payload = client.get("/heroes", {"class": hero_class})
+    rows = [
+        [h["hero_id"], h.get("hero_name", ""), ", ".join(h.get("class", []) if isinstance(h.get("class"), list) else [str(h.get("class", ""))]), h.get("life", ""), h.get("intellect", "")]
+        for h in payload["data"]
+    ]
+    emit(payload, tables=[("Heroes", ["ID", "Name", "Class", "Life", "Int"], rows)])
+
+
+@app.command()
+def show(
+    hero: str = typer.Argument(..., help="Hero id or name"),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Show one hero's details."""
+    set_mode(json_, csv_)
+    hero_id = resolve.hero_id(hero)
+    payload = client.get(f"/heroes/{hero_id}")
+    data = payload["data"]
+    rows = [
+        [field, str(data.get(field, ""))]
+        for field in ("hero_id", "hero_name", "class", "life", "intellect", "rarity", "tcg_market_price")
+        if data.get(field) is not None
+    ]
+    emit(payload, tables=[(data.get("hero_name", hero_id), ["Field", "Value"], rows)])
+
+
+@app.command()
+def aggregate(
+    hero: str = typer.Argument(..., help="Hero id or name"),
+    format_type: str = typer.Option("cc", "--format"),
+    source: str = typer.Option("online", "--source", help="online | paper"),
+    period: str = typer.Option("14d", "--period", help="7d | 14d | 30d"),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Pre-computed matchup table: per-opponent record + play/draw splits."""
+    set_mode(json_, csv_)
+    hero_id = resolve.hero_id(hero)
+    payload = client.get(
+        f"/heroes/{hero_id}/aggregate",
+        {"format": format_type, "source": source, "period": period},
+    )
+    data = payload["data"]
+    names = resolve.hero_names()
+
+    matchups = sorted(
+        data.get("matchups", {}).items(),
+        key=lambda kv: kv[1].get("total_matches", 0),
+        reverse=True,
+    )
+    rows = [
+        [
+            names.get(opp_id, opp_id),
+            opp_id,
+            m.get("total_matches", 0),
+            pct(m.get("win_rate")),
+            pct(m.get("going_first_win_rate")),
+            pct(m.get("going_second_win_rate")),
+        ]
+        for opp_id, m in matchups
+    ]
+    summary = [
+        f"[bold]{names.get(hero_id, hero_id)}[/bold] - {format_type}/{source}/{period}: "
+        f"{data.get('total_matches', 0)} matches, "
+        f"overall WR {pct(data.get('overall_win_rate'))} "
+        f"(first {pct(data.get('going_first_win_rate'))}, "
+        f"second {pct(data.get('going_second_win_rate'))})"
+    ]
+    emit(
+        payload,
+        tables=[("Matchups", ["Opponent", "ID", "Matches", "WR", "First WR", "Second WR"], rows)],
+        summary=summary,
+    )

fablazing_cli/commands/matchup.py

@@ -0,0 +1,121 @@
+"""The matchup command."""
+from typing import List
+
+import typer
+
+from .. import client, resolve
+from ..output import emit, pct, set_mode
+
+
+def matchup(
+    hero1: str = typer.Argument(..., help="Deck 1 hero (id or name)"),
+    hero2: str = typer.Argument(..., help="Deck 2 hero (id or name)"),
+    format_type: str = typer.Option("cc", "--format"),
+    days: int = typer.Option(30, "--days", min=1, max=365),
+    start_date: str = typer.Option(None, "--start", help="YYYY-MM-DD (overrides --days)"),
+    end_date: str = typer.Option(None, "--end", help="YYYY-MM-DD"),
+    winner: int = typer.Option(None, "--winner", min=1, max=2, help="Only games won by deck 1 or 2"),
+    include1: List[str] = typer.Option([], "--include1", help="Deck 1 must run this card (repeatable; supports card:gte2)"),
+    include2: List[str] = typer.Option([], "--include2", help="Deck 2 must run this card"),
+    exclude1: List[str] = typer.Option([], "--exclude1", help="Deck 1 must NOT run this card"),
+    exclude2: List[str] = typer.Option([], "--exclude2", help="Deck 2 must NOT run this card"),
+    dynamics: bool = typer.Option(True, "--dynamics/--no-dynamics", help="Game length / fatigue stats"),
+    top: int = typer.Option(10, "--top", min=1, max=50, help="Cards per table"),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Head-to-head analysis: win rates, play/draw splits, card tables, tech
+    cards, and game dynamics."""
+    set_mode(json_, csv_)
+    h1 = resolve.hero_id(hero1)
+    h2 = resolve.hero_id(hero2)
+    params = {
+        "format": format_type,
+        "days": days,
+        "start_date": start_date,
+        "end_date": end_date,
+        "winner": winner,
+        "included_deck1": [resolve.card_id(c, allow_spec=True) for c in include1],
+        "included_deck2": [resolve.card_id(c, allow_spec=True) for c in include2],
+        "excluded_deck1": [resolve.card_id(c) for c in exclude1],
+        "excluded_deck2": [resolve.card_id(c) for c in exclude2],
+        "include_dynamics": dynamics,
+    }
+    payload = client.get(f"/matchups/{h1}/{h2}", params)
+    data = payload["data"]
+    names = resolve.hero_names()
+    name1, name2 = names.get(h1, h1), names.get(h2, h2)
+
+    total = data.get("total_matches", 0)
+    summary = [
+        f"[bold]{name1}[/bold] vs [bold]{name2}[/bold] - {format_type}, {total} matches"
+    ]
+    if total == 0:
+        emit(payload, summary=summary + ["No matches found for these filters."])
+        return
+
+    overview_rows = []
+    for deck_key, name in (("deck1", name1), ("deck2", name2)):
+        overview_rows.append([
+            name,
+            data.get(f"{deck_key}_wins", 0),
+            pct(data.get(f"{deck_key}_win_rate")),
+            f"{pct(data.get(f'{deck_key}_going_first_win_rate'))} ({data.get(f'{deck_key}_going_first_matches', 0)})",
+            f"{pct(data.get(f'{deck_key}_going_second_win_rate'))} ({data.get(f'{deck_key}_going_second_matches', 0)})",
+        ])
+
+    tables = [("Overview", ["Deck", "Wins", "WR", "First WR (n)", "Second WR (n)"], overview_rows)]
+
+    def card_rows(cards):
+        return [
+            [
+                c.get("card_id", ""),
+                pct(c.get("frequency")),
+                pct(c.get("win_rate")),
+                pct(c.get("play_frequency")),
+                pct(c.get("block_frequency")),
+                pct(c.get("pitch_frequency")),
+                f"{c.get('copies_avg', 0):.1f}",
+            ]
+            for c in (cards or [])[:top]
+        ]
+
+    card_columns = ["Card", "Freq", "WR", "Play", "Block", "Pitch", "Copies"]
+    for deck_key, name in (("deck1", name1), ("deck2", name2)):
+        frequent = data.get(f"{deck_key}_frequent_cards")
+        if frequent:
+            tables.append((f"{name} - top cards", card_columns, card_rows(frequent)))
+        tech = data.get(f"{deck_key}_tech_cards")
+        if tech:
+            tech_rows = [
+                [
+                    c.get("card_id", ""),
+                    pct(c.get("frequency")),
+                    pct(c.get("win_rate")),
+                    f"+{c.get('wilson_improvement', 0) * 100:.1f}%",
+                    c.get("match_count", ""),
+                ]
+                for c in tech[:top]
+            ]
+            tables.append((f"{name} - tech cards (Wilson outperformers)", ["Card", "Freq", "WR", "Wilson delta", "Matches"], tech_rows))
+
+    game_length = data.get("game_length") or {}
+    turns = game_length.get("turns") or {}
+    if turns:
+        percentiles = turns.get("percentiles") or {}
+        spread = ""
+        if percentiles.get("p10") is not None and percentiles.get("p90") is not None:
+            spread = f", p10-p90 {percentiles['p10']}-{percentiles['p90']}"
+        summary.append(
+            f"Game length: avg {turns.get('avg', '?')} turns, "
+            f"median {turns.get('median', '?')}{spread}"
+        )
+    for deck_key, name in (("deck1", name1), ("deck2", name2)):
+        transform = data.get(f"{deck_key}_transform")
+        if transform and transform.get("can_transform"):
+            summary.append(
+                f"{name} transform rate: {pct(transform.get('transform_rate'))} "
+                f"({transform.get('transformed_matches', 0)}/{transform.get('assessed_matches', 0)} games)"
+            )
+
+    emit(payload, tables=tables, summary=summary)

fablazing_cli/commands/meta.py

@@ -0,0 +1,76 @@
+"""Meta snapshot + movers."""
+import typer
+
+from .. import client
+from ..output import emit, pct, set_mode
+
+app = typer.Typer(help="Meta breakdown and trending heroes")
+
+
+@app.command()
+def snapshot(
+    days: int = typer.Option(14, "--days", min=1, max=90),
+    format_type: str = typer.Option("cc", "--format"),
+    source: str = typer.Option("online", "--source", help="online | paper"),
+    tournament_type: str = typer.Option(None, "--type", help="Paper only, e.g. Calling"),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Hero popularity, win rate, and top matchups over the window."""
+    set_mode(json_, csv_)
+    payload = client.get(
+        "/meta/snapshot",
+        {"days": days, "format": format_type, "source": source, "tournament_type": tournament_type},
+    )
+    data = payload["data"]
+    rows = [
+        [
+            rank,
+            h.get("hero_name", h.get("hero_id", "")),
+            h.get("hero_id", ""),
+            f"{h.get('percentage', 0):.1f}%",
+            pct(h.get("win_rate")),
+            h.get("count", 0),
+        ]
+        for rank, h in enumerate(data.get("heroes", []), start=1)
+    ]
+    summary = [
+        f"[bold]Meta snapshot[/bold] - {format_type}/{source}, last {days}d, "
+        f"{data.get('total_matches', 0)} matches"
+    ]
+    emit(payload, tables=[("Heroes", ["#", "Hero", "ID", "Play %", "WR", "Games"], rows)], summary=summary)
+
+
+@app.command()
+def movers(
+    days: int = typer.Option(14, "--days", min=1, max=90),
+    format_type: str = typer.Option("cc", "--format"),
+    source: str = typer.Option("online", "--source"),
+    limit: int = typer.Option(10, "--limit", min=1, max=50),
+    sort_by: str = typer.Option("popularity", "--sort-by", help="popularity | winrate"),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Rising and falling heroes over the window."""
+    set_mode(json_, csv_)
+    payload = client.get(
+        "/meta/movers",
+        {"days": days, "format": format_type, "source": source, "limit": limit, "sort_by": sort_by},
+    )
+    arrows = {"up": "↑", "down": "↓", "stable": "→"}
+    rows = [
+        [
+            h.get("hero_name", h.get("hero_id", "")),
+            h.get("hero_id", ""),
+            arrows.get(h.get("trend_direction", ""), h.get("trend_direction", "")),
+            f"{h.get('percent_change', 0):+.1f}%",
+            f"{h.get('current_popularity', 0):.1f}%",
+            f"{h.get('avg_popularity', 0):.1f}%",
+        ]
+        for h in payload["data"].get("heroes", [])
+    ]
+    emit(
+        payload,
+        tables=[("Movers", ["Hero", "ID", "Trend", "Change", "Now", "Avg"], rows)],
+        summary=[f"[bold]Meta movers[/bold] - {format_type}/{source}, last {days}d, by {sort_by}"],
+    )

fablazing_cli/commands/tournaments.py

@@ -0,0 +1,120 @@
+"""Tournament events, final standings, decklists."""
+import typer
+
+from .. import client
+from ..output import emit, set_mode
+
+app = typer.Typer(help="Paper tournaments: events, standings, decklists")
+
+
+@app.command("list")
+def list_tournaments(
+    format_type: str = typer.Option(None, "--format"),
+    tournament_type: str = typer.Option(None, "--type", help="Battle Hardened, National, Pro Tour, Calling..."),
+    status: str = typer.Option(None, "--status"),
+    has_decklists: bool = typer.Option(None, "--has-decklists/--no-decklists"),
+    limit: int = typer.Option(25, "--limit", min=1, max=100),
+    offset: int = typer.Option(0, "--offset", min=0),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """List tournaments, newest first."""
+    set_mode(json_, csv_)
+    payload = client.get(
+        "/tournaments",
+        {
+            "format": format_type,
+            "type": tournament_type,
+            "status": status,
+            "has_decklists": has_decklists,
+            "limit": limit,
+            "offset": offset,
+        },
+    )
+    rows = [
+        [
+            e.get("id", ""),
+            e.get("tournament_name", ""),
+            (e.get("event_date") or "")[:10],
+            e.get("format", ""),
+            e.get("type", ""),
+            e.get("total_players", ""),
+            (e.get("winner") or {}).get("player_name", "-") if isinstance(e.get("winner"), dict) else "-",
+        ]
+        for e in payload["data"]
+    ]
+    emit(
+        payload,
+        tables=[("Tournaments", ["ID", "Name", "Date", "Format", "Type", "Players", "Winner"], rows)],
+        summary=[f"{payload['meta'].get('total', len(rows))} tournaments (showing {len(rows)})"],
+    )
+
+
+@app.command()
+def show(
+    event_id: str = typer.Argument(..., help="Tournament id (from `tournaments list`)"),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Show one tournament's details."""
+    set_mode(json_, csv_)
+    payload = client.get(f"/tournaments/{event_id}")
+    data = payload["data"]
+    rows = [
+        [field, str(data.get(field, ""))]
+        for field in (
+            "tournament_name", "event_date", "format", "type", "status",
+            "total_players", "total_rounds", "has_decklists", "has_matches", "event_url",
+        )
+        if data.get(field) is not None
+    ]
+    emit(payload, tables=[(data.get("tournament_name", event_id), ["Field", "Value"], rows)])
+
+
+@app.command()
+def standings(
+    event_id: str = typer.Argument(...),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Winner + top 8 from official final standings."""
+    set_mode(json_, csv_)
+    payload = client.get(f"/tournaments/{event_id}/standings")
+    data = payload["data"]
+    rows = [
+        [p.get("rank", ""), p.get("player_name", ""), p.get("hero_name", ""), p.get("hero_id", "")]
+        for p in data.get("top_8", [])
+    ]
+    winner = data.get("winner") or {}
+    summary = [f"[bold]{data.get('tournament_name', '')}[/bold]"]
+    if winner:
+        summary.append(
+            f"Winner: [green]{winner.get('player_name', '?')}[/green] "
+            f"({winner.get('hero_name', '?')})"
+        )
+    emit(payload, tables=[("Top 8", ["Rank", "Player", "Hero", "Hero ID"], rows)], summary=summary)
+
+
+@app.command()
+def decklists(
+    event_id: str = typer.Argument(...),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Submitted decklists for a tournament."""
+    set_mode(json_, csv_)
+    payload = client.get(f"/tournaments/{event_id}/decklists")
+    rows = [
+        [
+            d.get("player_id", ""),
+            len(d.get("card_ids") or []),
+            len(d.get("equipment_ids") or []),
+            d.get("decklist_url", ""),
+        ]
+        for d in payload["data"]
+    ]
+    emit(
+        payload,
+        tables=[("Decklists", ["Player", "Cards", "Equipment", "URL"], rows)],
+        summary=[f"{payload['meta'].get('count', len(rows))} decklists (full card lists in --json)"],
+    )

fablazing_cli/config.py

@@ -0,0 +1,39 @@
+"""Config + cache paths. Key/URL resolution order: env var, then config file."""
+import json
+import os
+from pathlib import Path
+
+from platformdirs import user_cache_dir, user_config_dir
+
+APP_NAME = "fablazing"
+DEFAULT_API_URL = "https://fablazing.com/api/v1"
+
+
+def config_path() -> Path:
+    return Path(user_config_dir(APP_NAME)) / "config.json"
+
+
+def load_config() -> dict:
+    try:
+        return json.loads(config_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def save_config(cfg: dict) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+
+
+def api_key():
+    return os.environ.get("FABLAZING_API_KEY") or load_config().get("api_key")
+
+
+def api_url() -> str:
+    url = os.environ.get("FABLAZING_API_URL") or load_config().get("api_url") or DEFAULT_API_URL
+    return url.rstrip("/")
+
+
+def cache_path(name: str) -> Path:
+    return Path(user_cache_dir(APP_NAME)) / name

fablazing_cli/main.py

@@ -0,0 +1,41 @@
+"""Fablazing CLI entry point. `fablazing` and `fabz` both land here."""
+import typer
+
+from . import __version__
+from .commands import auth, card, hero, meta, tournaments
+from .commands.matchup import matchup
+from .output import console
+from .reference import REFERENCE
+
+app = typer.Typer(
+    name="fablazing",
+    help=(
+        "Flesh and Blood analytics from your terminal: matchups, meta, cards, "
+        "and tournaments. Run `fablazing reference` for the full primer."
+    ),
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+app.add_typer(auth.app, name="auth")
+app.add_typer(hero.app, name="hero")
+app.add_typer(meta.app, name="meta")
+app.add_typer(card.app, name="card")
+app.add_typer(tournaments.app, name="tournaments")
+app.command()(matchup)
+
+
+@app.command()
+def reference():
+    """Print the full CLI + data-semantics primer (markdown)."""
+    print(REFERENCE)
+
+
+@app.command()
+def version():
+    """Print the CLI version."""
+    console.print(f"fablazing-cli {__version__}")
+
+
+if __name__ == "__main__":
+    app()

fablazing_cli/output.py

@@ -0,0 +1,97 @@
+"""Rendering: rich tables on a tty, JSON when piped or with --json, CSV of
+the primary table with --csv. JSON mode always gets the full API payload."""
+import csv
+import io
+import json
+import os
+import sys
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+# Windows pipes default to cp1252, which crashes on non-ASCII card/hero
+# names (e.g. "Jarl Vetreiði"). Force UTF-8 on both streams.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        try:
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+        except (OSError, ValueError):
+            pass
+
+console = Console()
+err_console = Console(stderr=True)
+
+_forced_mode = None  # None = auto (table on TTY, json otherwise)
+
+
+def set_mode(json_flag: bool, csv_flag: bool) -> None:
+    global _forced_mode
+    if json_flag and csv_flag:
+        fail("--json and --csv are mutually exclusive", 2)
+    if json_flag:
+        _forced_mode = "json"
+    elif csv_flag:
+        _forced_mode = "csv"
+
+
+def mode() -> str:
+    if _forced_mode:
+        return _forced_mode
+    env_mode = os.environ.get("FABLAZING_OUTPUT")
+    if env_mode in ("table", "json", "csv"):
+        return env_mode
+    return "table" if sys.stdout.isatty() else "json"
+
+
+def fail(message: str, code: int = 1):
+    err_console.print(f"[red]error:[/red] {message}")
+    raise typer.Exit(code)
+
+
+def pct(value, digits: int = 1) -> str:
+    """Format a 0-1 rate as a percentage string."""
+    if value is None:
+        return "-"
+    return f"{value * 100:.{digits}f}%"
+
+
+def num(value) -> str:
+    return "-" if value is None else str(value)
+
+
+def emit(payload, tables=None, summary=None) -> None:
+    """payload: full API response (JSON mode). tables: [(title, columns,
+    rows)]. summary: list of rich-markup lines printed above tables."""
+    current = mode()
+
+    if current == "json":
+        buffer = io.StringIO()
+        json.dump(payload, buffer, indent=2, default=str, ensure_ascii=False)
+        print(buffer.getvalue())
+        return
+
+    if current == "csv":
+        if not tables:
+            fail("this command has no tabular form; use --json", 2)
+        title, columns, rows = tables[0]
+        if len(tables) > 1:
+            err_console.print(
+                f"[yellow]note:[/yellow] --csv only emits the first table ({title}), use --json for everything"
+            )
+        writer = csv.writer(sys.stdout, lineterminator="\n")
+        writer.writerow(columns)
+        writer.writerows(rows)
+        return
+
+    for line in summary or []:
+        console.print(line)
+    for title, columns, rows in tables or []:
+        table = Table(title=title, title_justify="left")
+        for column in columns:
+            table.add_column(str(column))
+        for row in rows:
+            table.add_row(*[str(cell) for cell in row])
+        console.print(table)
+    if not tables and not summary:
+        console.print_json(json.dumps(payload, default=str))

fablazing_cli/reference.py

@@ -0,0 +1,61 @@
+"""Text for the `reference` command."""
+
+REFERENCE = """\
+# Fablazing CLI reference
+
+Terminal client for the Fablazing API: matchup stats, meta breakdowns, card
+analytics and paper tournament results for competitive Flesh and Blood.
+`fablazing` and `fabz` are the same binary.
+
+## Auth
+- `fablazing auth set-key fbl_live_...` stores your key, or set the
+  FABLAZING_API_KEY env var.
+- `fablazing auth status` checks it.
+- Keys have a daily quota and a per-minute limit. Hitting either exits
+  with code 3.
+
+## IDs and formats
+- Hero ids look like `EVO001` (set code + number).
+- Card ids are snake_case with a pitch color suffix: `sink_below_red`.
+  The same card name can exist as red, yellow and blue. Those are
+  different cards and are counted separately everywhere.
+- Names are accepted anywhere an id is. Ambiguous names error out and
+  list the matching ids (exit code 2).
+- Formats: `cc` (default), `blitz`, `ll`, `sage`, `gage`.
+
+## Data notes
+- win_rate fields are fractions between 0 and 1.
+- In `matchup HERO1 HERO2`, deck1 is HERO1, so deck1_win_rate is HERO1's.
+- going_first means that player took the first turn.
+- Matches are deduplicated. Transforming heroes (Levia, Marionette, Maxx,
+  Teklovossen) are stored under their base hero id, with transform stats
+  in deck1_transform / deck2_transform.
+- Tech cards are Wilson-scored against the matchup baseline, so a lucky
+  streak on a small sample doesn't make the list.
+- Tournament standings and decklists come from official paper events.
+
+## Commands
+- `fablazing matchup EVO001 "Jarl" --days 30`
+  Card filters: `--include1/--include2/--exclude1/--exclude2`, repeatable.
+  Copy counts on includes: `--include1 "sink_below_red:gte2"` (eq/gte/lte,
+  cards only, not equipment). `--no-dynamics` skips game length stats.
+- `fablazing meta snapshot --format cc --days 14`
+- `fablazing meta movers --days 14`
+- `fablazing hero list` / `hero show EVO001`
+- `fablazing hero aggregate EVO001 --period 14d --source online`
+- `fablazing card search "sink"` / `card show sink_below_red`
+- `fablazing card trends sink_below_red --days 30`
+- `fablazing card synergies sink_below_red`
+- `fablazing card popular --days 7`
+- `fablazing tournaments list --type Calling`
+- `fablazing tournaments show <id>` / `standings <id>` / `decklists <id>`
+- `fablazing reference` prints this text.
+
+## Output
+- Tables on a terminal, JSON when piped or with --json (the JSON is the
+  full API payload, a superset of the tables), CSV of the primary table
+  with --csv. Data goes to stdout, errors to stderr.
+
+## Exit codes
+0 ok, 1 api error, 2 usage error, 3 quota exceeded
+"""

fablazing_cli/resolve.py

@@ -0,0 +1,87 @@
+"""Resolve hero/card names to ids so commands accept either form.
+
+Heroes come from a 24h disk cache of /heroes. Cards go through
+/cards/search, but only when the input isn't already a card_id.
+"""
+import json
+import re
+import time
+
+from . import client
+from .config import cache_path
+from .output import fail
+
+HERO_ID_RE = re.compile(r"^[A-Z]{2,4}\d{3}$")
+CARD_ID_RE = re.compile(r"^[a-z0-9_]+$")
+CARD_SPEC_RE = re.compile(r"^(?P<card>.+?):(?P<spec>(eq|gte|lte)\d+)$")
+HERO_CACHE_TTL = 24 * 3600
+_HEROES_CACHE_FILE = "heroes.json"
+
+
+def hero_list() -> list:
+    path = cache_path(_HEROES_CACHE_FILE)
+    try:
+        cached = json.loads(path.read_text(encoding="utf-8"))
+        if time.time() - cached["at"] < HERO_CACHE_TTL:
+            return cached["heroes"]
+    except (OSError, ValueError, KeyError):
+        pass
+    heroes = client.get("/heroes")["data"]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({"at": time.time(), "heroes": heroes}), encoding="utf-8"
+    )
+    return heroes
+
+
+def hero_names() -> dict:
+    """hero_id -> hero_name map from the cached hero list."""
+    return {h["hero_id"]: h.get("hero_name", h["hero_id"]) for h in hero_list()}
+
+
+def hero_id(text: str) -> str:
+    candidate = text.strip()
+    if HERO_ID_RE.match(candidate.upper()):
+        return candidate.upper()
+
+    query = candidate.lower()
+    heroes = hero_list()
+    exact = [
+        h for h in heroes
+        if h.get("hero_name", "").lower() == query or h.get("snake_case") == query
+    ]
+    if len(exact) == 1:
+        return exact[0]["hero_id"]
+    partial = [h for h in heroes if query in h.get("hero_name", "").lower()]
+    if len(partial) == 1:
+        return partial[0]["hero_id"]
+    if not partial:
+        fail(f"no hero matches '{text}'", 2)
+    options = ", ".join(f"{h['hero_name']} ({h['hero_id']})" for h in partial[:8])
+    fail(f"ambiguous hero '{text}' - did you mean: {options}", 2)
+
+
+def card_id(text: str, allow_spec: bool = False) -> str:
+    """Resolve a card name or id; optionally preserve a :gte2-style suffix."""
+    candidate = text.strip()
+    spec = ""
+    match = CARD_SPEC_RE.match(candidate)
+    if match and allow_spec:
+        candidate, spec = match.group("card"), ":" + match.group("spec")
+
+    if CARD_ID_RE.match(candidate):
+        return candidate + spec
+
+    results = client.get("/cards/search", {"q": candidate, "limit": 10})["data"]
+    exact = [c for c in results if c.get("card_name", "").lower() == candidate.lower()]
+    pool = exact or results
+    if len(pool) == 1:
+        return pool[0]["card_id"] + spec
+    if not pool:
+        fail(f"no card matches '{candidate}'", 2)
+    options = ", ".join(c["card_id"] for c in pool[:9])
+    fail(
+        f"ambiguous card '{candidate}' (pitch variants share names) - "
+        f"use a card_id: {options}",
+        2,
+    )

fablazing_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: fablazing-cli
+Version: 0.1.0
+Summary: Fablazing analytics from your terminal - Flesh and Blood matchups, meta, cards, and tournaments.
+Project-URL: Homepage, https://fablazing.com
+Author: Fablazing
+License: MIT
+Keywords: analytics,cli,fab,flesh-and-blood,tcg
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# fablazing-cli
+
+Terminal client for [Fablazing](https://fablazing.com): matchup stats, meta
+breakdowns, card trends and paper tournament results for Flesh and Blood.
+
+You need an API key (Builder plan).
+
+## Install
+
+    pipx install fablazing-cli
+
+or plain `pip install fablazing-cli`. On Windows without pipx:
+
+    py -m pip install --user pipx
+    py -m pipx ensurepath
+
+This installs `fablazing` and `fabz`, same thing.
+
+## Setup
+
+    fabz auth set-key fbl_live_xxx
+    fabz auth status
+
+The key can also come from the `FABLAZING_API_KEY` env var.
+
+## Usage
+
+    fabz matchup "Dash I/O" Jarl --days 30
+    fabz meta snapshot
+    fabz meta movers
+    fabz hero aggregate EVO001 --period 14d
+    fabz card trends "Sink Below" --json
+    fabz card popular --days 7 --csv > popular.csv
+    fabz tournaments list --type Calling
+
+Heroes and cards can be given by name or id. A name that matches several
+cards (pitch variants share names) errors and lists the ids so you can pick
+one. Copy count filters work on matchup includes:
+`--include1 "sink_below_red:gte2"`.
+
+## Output
+
+Tables on a terminal. JSON when piped or with `--json`, CSV with `--csv`.
+Exit codes: 0 ok, 1 api error, 2 usage error, 3 quota exceeded.
+
+## Tab completion
+
+    fablazing --install-completion
+
+## Reference
+
+`fablazing reference` prints the full command and data reference.

fablazing_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+fablazing_cli/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+fablazing_cli/client.py,sha256=QcX7KPVMVJTY9-eIebv_SPPaoEnZLTwNUWXAiGXZzD8,1500
+fablazing_cli/config.py,sha256=fWMBakRegMF2VxCOdp56Zb7fJUHZzVsMEoaxgFYAs8s,1015
+fablazing_cli/main.py,sha256=c2YVSmsHrVsHfSQb88l3FhGJs9j8gDlqvMAjf_7m5w8,1070
+fablazing_cli/output.py,sha256=pclbVso68F-JJAtImDC8ed-M8qqAlO1KYMLtoQRt0-E,2968
+fablazing_cli/reference.py,sha256=8Gm7UEJpJreeHVgCiFyWDy6wvTQ0Pz4zWShnOhnF2tg,2617
+fablazing_cli/resolve.py,sha256=dwlbGOADRNakW4tYTbxQ6o6QTvYQ5chBkadOUPpmJBs,2859
+fablazing_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fablazing_cli/commands/auth.py,sha256=KgDNwnqxgtxU1zgKAsvY4PgkRvU8xS4zg9LVqgVfuS4,1451
+fablazing_cli/commands/card.py,sha256=4FIqeOqDu-OYKiKab2vhFW8hw_gNze0F1xgXC_m-TqU,5052
+fablazing_cli/commands/hero.py,sha256=SgZ0JZeZFphPGSYg4VTpnTikN4dSgk8VjaLJ74RCB40,3214
+fablazing_cli/commands/matchup.py,sha256=5i5iapR0QRcQ54fBEwQYfvP5cg0EBBKmAQi0UGl66O8,5346
+fablazing_cli/commands/meta.py,sha256=Po-m64OSMKUpo2i0st4N_TyCiAu9pmpzA-mAZ8U_JuM,2821
+fablazing_cli/commands/tournaments.py,sha256=UqYtWrYdFZK3hfVln8PBLvMLNit3rosyGA8Q-McZtOw,4127
+fablazing_cli-0.1.0.dist-info/METADATA,sha256=WEx4AM92FYdYaH1YO0SAGsAkl66UYUus8km-jRvTfKA,1814
+fablazing_cli-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+fablazing_cli-0.1.0.dist-info/entry_points.txt,sha256=w6VNYUimCKbqnOw-aT8JA2q0DxE-dQTZBfh40UL2vyc,83
+fablazing_cli-0.1.0.dist-info/RECORD,,

fablazing_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fablazing_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+fablazing = fablazing_cli.main:app
+fabz = fablazing_cli.main:app