thoughtleaders-cli 0.5.0__py3-none-any.whl

tl_cli/auth/token_store.py

@@ -0,0 +1,98 @@
+"""Secure token storage using OS keychain (keyring) with file fallback."""
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+import keyring
+from keyring.errors import NoKeyringError
+
+from tl_cli.config import ensure_config_dir
+
+SERVICE_NAME = "tl-cli"
+FALLBACK_FILE = "credentials.json"
+
+
+@dataclass
+class StoredTokens:
+    """Tokens stored in the keychain."""
+
+    access_token: str
+    refresh_token: str | None
+    expires_at: float  # Unix timestamp
+    email: str | None = None
+
+    @property
+    def is_expired(self) -> bool:
+        # 5-minute buffer before actual expiry
+        return time.time() > (self.expires_at - 300)
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "access_token": self.access_token,
+            "refresh_token": self.refresh_token,
+            "expires_at": self.expires_at,
+            "email": self.email,
+        })
+
+    @classmethod
+    def from_json(cls, data: str) -> "StoredTokens":
+        parsed = json.loads(data)
+        return cls(
+            access_token=parsed["access_token"],
+            refresh_token=parsed.get("refresh_token"),
+            expires_at=parsed["expires_at"],
+            email=parsed.get("email"),
+        )
+
+
+def save_tokens(tokens: StoredTokens) -> None:
+    """Save tokens to the OS keychain, falling back to encrypted file."""
+    data = tokens.to_json()
+    try:
+        keyring.set_password(SERVICE_NAME, "tokens", data)
+    except (NoKeyringError, Exception):
+        _save_to_file(data)
+
+
+def load_tokens() -> StoredTokens | None:
+    """Load tokens from the OS keychain or fallback file."""
+    try:
+        data = keyring.get_password(SERVICE_NAME, "tokens")
+        if data:
+            return StoredTokens.from_json(data)
+    except (NoKeyringError, Exception):
+        pass
+
+    return _load_from_file()
+
+
+def clear_tokens() -> None:
+    """Remove stored tokens from keychain and fallback file."""
+    try:
+        keyring.delete_password(SERVICE_NAME, "tokens")
+    except (NoKeyringError, Exception):
+        pass
+
+    fallback = ensure_config_dir() / FALLBACK_FILE
+    if fallback.exists():
+        fallback.unlink()
+
+
+def _save_to_file(data: str) -> None:
+    """Fallback: save to config dir (less secure than keychain)."""
+    path = ensure_config_dir() / FALLBACK_FILE
+    path.write_text(data)
+    path.chmod(0o600)
+
+
+def _load_from_file() -> StoredTokens | None:
+    """Fallback: load from config dir."""
+    path = ensure_config_dir() / FALLBACK_FILE
+    if not path.exists():
+        return None
+    try:
+        return StoredTokens.from_json(path.read_text())
+    except (json.JSONDecodeError, KeyError):
+        return None

tl_cli/client/errors.py

@@ -0,0 +1,72 @@
+"""User-friendly error handling for API responses."""
+
+import json
+import sys
+import traceback
+
+from rich.console import Console
+
+err = Console(stderr=True)
+
+
+class ApiError(Exception):
+    """Raised when the API returns a non-success status."""
+
+    def __init__(self, status_code: int, detail: str, raw: dict | None = None, url: str | None = None, response_text: str | None = None):
+        self.status_code = status_code
+        self.detail = detail
+        self.raw = raw
+        self.url = url
+        self.response_text = response_text
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+def _print_debug(error: ApiError) -> None:
+    """Print detailed debug info for an API error."""
+    from tl_cli.config import debug
+
+    if not debug:
+        return
+    err.print(f"\n[dim]--- debug ---[/dim]")
+    if error.url:
+        err.print(f"[dim]URL: {error.url}[/dim]")
+    err.print(f"[dim]HTTP {error.status_code}: {error.detail}[/dim]")
+    if error.response_text:
+        err.print(f"[dim]Response body:[/dim]")
+        err.print(f"[dim]{error.response_text}[/dim]")
+    err.print(f"[dim]Traceback:[/dim]")
+    err.print(f"[dim]{''.join(traceback.format_exception(error))}[/dim]")
+
+
+def handle_api_error(error: ApiError) -> None:
+    """Print a user-friendly error message and exit with the right code."""
+    if error.status_code == 401:
+        err.print("[red]Authentication required.[/red] Run: tl auth login")
+        _print_debug(error)
+        sys.exit(2)
+    elif error.status_code == 402:
+        err.print("[red]Insufficient credits.[/red]")
+        err.print("Deposit more at: https://app.thoughtleaders.io/settings/billing")
+        _print_debug(error)
+        sys.exit(4)
+    elif error.status_code == 403:
+        err.print(f"[red]Access denied:[/red] {error.detail}")
+        err.print("Your plan may not include access to this resource.")
+        _print_debug(error)
+        sys.exit(1)
+    elif error.status_code == 404:
+        err.print(f"[yellow]Not found:[/yellow] {error.detail}")
+        _print_debug(error)
+        sys.exit(1)
+    elif error.status_code == 429:
+        err.print("[yellow]Rate limited.[/yellow] Please wait and try again.")
+        _print_debug(error)
+        sys.exit(3)
+    elif error.status_code >= 500:
+        err.print(f"[red]Server error ({error.status_code}):[/red] {error.detail}")
+        _print_debug(error)
+        sys.exit(3)
+    else:
+        err.print(f"[red]Error ({error.status_code}):[/red] {error.detail}")
+        _print_debug(error)
+        sys.exit(1)

tl_cli/client/http.py

@@ -0,0 +1,109 @@
+"""Authenticated HTTP client for the TL CLI API."""
+
+import httpx
+
+from tl_cli import __version__
+from tl_cli.auth.login import refresh_access_token
+from tl_cli.auth.token_store import load_tokens
+from tl_cli.client.errors import ApiError
+from tl_cli.config import get_config
+
+
+class TLClient:
+    """HTTP client that handles auth injection, token refresh, and error mapping."""
+
+    def __init__(self) -> None:
+        self._config = get_config()
+        self._client = httpx.Client(
+            base_url=self._config.cli_api_base,
+            timeout=30.0,
+            headers={
+                "User-Agent": f"tl-cli/{__version__}",
+                "X-TL-Client": f"cli/{__version__}",
+            },
+        )
+
+    def get(self, path: str, params: dict | None = None) -> dict:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json_body: dict | None = None) -> dict:
+        return self._request("POST", path, json_body=json_body)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict | None = None,
+        json_body: dict | None = None,
+    ) -> dict:
+        headers = self._auth_headers()
+
+        response = self._client.request(
+            method, path, params=params, json=json_body, headers=headers
+        )
+
+        # On 401, try refreshing the token once
+        if response.status_code == 401:
+            headers = self._refresh_and_get_headers()
+            if headers:
+                response = self._client.request(
+                    method, path, params=params, json=json_body, headers=headers
+                )
+
+        if response.status_code >= 400:
+            detail = self._extract_detail(response)
+            try:
+                raw = response.json() if response.text else None
+            except Exception:
+                raw = None
+            raise ApiError(
+                response.status_code, detail, raw=raw,
+                url=str(response.url), response_text=response.text,
+            )
+
+        return response.json()
+
+    def _auth_headers(self) -> dict[str, str]:
+        """Get authorization headers from API key or stored tokens."""
+        # API key takes priority (for CI/scripts)
+        if self._config.api_key:
+            return {"Authorization": f"Bearer {self._config.api_key}"}
+
+        tokens = load_tokens()
+        if not tokens:
+            raise ApiError(401, "Not authenticated. Run: tl auth login")
+
+        if tokens.is_expired and tokens.refresh_token:
+            tokens = refresh_access_token(tokens.refresh_token)
+
+        return {"Authorization": f"Bearer {tokens.access_token}"}
+
+    def _refresh_and_get_headers(self) -> dict[str, str] | None:
+        """Try to refresh the token. Returns new headers or None."""
+        tokens = load_tokens()
+        if not tokens or not tokens.refresh_token:
+            return None
+        try:
+            new_tokens = refresh_access_token(tokens.refresh_token)
+            return {"Authorization": f"Bearer {new_tokens.access_token}"}
+        except SystemExit:
+            return None
+
+    def _extract_detail(self, response: httpx.Response) -> str:
+        """Extract error detail from response body."""
+        try:
+            data = response.json()
+            return data.get("detail", data.get("error", str(data)))
+        except Exception:
+            text = response.text or ""
+            if text.lstrip().startswith("<!") or text.lstrip().startswith("<html"):
+                return f"HTTP {response.status_code} (non-JSON response from server)"
+            return text or f"HTTP {response.status_code}"
+
+    def close(self) -> None:
+        self._client.close()
+
+
+def get_client() -> TLClient:
+    """Get a configured TL API client."""
+    return TLClient()

tl_cli/commands/ask.py

@@ -0,0 +1,54 @@
+"""tl ask — Natural language query (AI fallback for users without an agent)."""
+
+import typer
+
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.output.formatter import detect_format, output
+
+app = typer.Typer(help="Natural language data queries (AI-powered fallback)")
+
+
+@app.callback(invoke_without_command=True)
+def ask(
+    ctx: typer.Context,
+    question: str = typer.Argument(..., help="Your question in plain English"),
+    llm_key: str | None = typer.Option(
+        None, "--llm-key", envvar="TL_LLM_KEY",
+        help="Your own LLM API key (waives surcharge)",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results"),
+) -> None:
+    """Ask a question about your data in plain English.
+
+    This is an optional fallback for users who don't have an AI agent (like Claude Code).
+    If you have Claude Code installed, use the /tl slash command instead — it's free and
+    uses your own Claude to translate questions into structured tl commands.
+
+    Credits: result credits + 2/result surcharge (waived with --llm-key).
+
+    Examples:
+        tl ask "show me all sold sponsorships for Nike in Q1"
+        tl ask "which channels had the most views last month" --llm-key sk-...
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+
+    body: dict = {"query": question, "limit": limit}
+    if llm_key:
+        body["llm_key"] = llm_key
+
+    client = get_client()
+    try:
+        data = client.post("/ask", json_body=body)
+        output(data, fmt, title="Results")
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

tl_cli/commands/balance.py

@@ -0,0 +1,68 @@
+"""tl balance — Show credit balance and recent usage."""
+
+import json
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.output.formatter import detect_format
+
+app = typer.Typer(help="Credit balance and usage (free)")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def balance(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Show your credit balance and recent usage (free, no credits).
+
+    Examples:
+        tl balance
+        tl balance --json
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    fmt = detect_format(json_output, False, False, toon_output)
+
+    client = get_client()
+    try:
+        data = client.get("/balance")
+
+        if fmt == "json":
+            print(json.dumps(data, indent=2, default=str))
+            return
+
+        balance_val = data.get("balance", 0)
+        allow_overage = data.get("allow_overage", False)
+
+        console.print(f"\n[bold]Credit Balance:[/bold] [cyan]{balance_val}[/cyan] credits")
+        if allow_overage:
+            console.print("[dim]Overage: enabled[/dim]")
+
+        recent = data.get("recent_usage", [])
+        if recent:
+            table = Table(title="Recent Usage")
+            table.add_column("Date")
+            table.add_column("Resource")
+            table.add_column("Results", justify="right")
+            table.add_column("Credits", justify="right")
+            for entry in recent[:10]:
+                table.add_row(
+                    entry.get("date", ""),
+                    entry.get("resource", ""),
+                    str(entry.get("results_count", "")),
+                    str(entry.get("credits_charged", "")),
+                )
+            console.print(table)
+
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

tl_cli/commands/brands.py

@@ -0,0 +1,174 @@
+"""tl brands — Brand detail and sponsorship history."""
+
+import urllib.parse
+
+import typer
+
+from rich.console import Console
+
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.hints import detail_hint
+from tl_cli.output.formatter import detect_format, output, output_single
+
+app = typer.Typer(help="Brand intelligence (detail, sponsorship history, channel mentions)")
+
+
+@app.callback(invoke_without_command=True)
+def brands(ctx: typer.Context) -> None:
+    """Brands — detail and sponsorship history."""
+    if ctx.invoked_subcommand is None:
+        ctx.get_help()
+        raise typer.Exit()
+
+
+def _handle_brand_api_error(e: ApiError) -> None:
+    """Print a candidates list for ambiguous brand name matches."""
+    if e.status_code == 400 and isinstance(e.raw, dict) and e.raw.get("candidates"):
+        err = Console(stderr=True)
+        err.print(f"[yellow]{e.detail}[/yellow]")
+        err.print()
+        err.print("[bold]Candidates:[/bold]")
+        err.print(f"  {'brand_id':>10}  {'website':<30}  name")
+        err.print(f"  {'-' * 10}  {'-' * 30}  {'-' * 40}")
+        for c in e.raw["candidates"]:
+            err.print(f"  {c['brand_id']:>10}  {c.get('website', ''):<30}  {c['name']}")
+        raise typer.Exit(1)
+    handle_api_error(e)
+
+
+@app.command("show")
+def show_cmd(
+    query: str = typer.Argument(..., help="Brand name or numeric ID"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output (flattens nested fields)"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Show brand detail by name or ID.
+
+    Accepts either a numeric brand ID or a partial name. Names that
+    match more than one brand return an error with candidate IDs.
+
+    Examples:
+        tl brands show Nike
+        tl brands show 21416
+    """
+    fmt = detect_format(json_output, csv_output, False, toon_output)
+    encoded_query = urllib.parse.quote(query, safe="")
+    client = get_client()
+    try:
+        data = client.get(f"/brands/{encoded_query}")
+        for r in (data.get("results", []) if isinstance(data.get("results"), list) else []):
+            r["brand_id"] = r.pop("id", None)
+        output_single(data, fmt)
+        if fmt == "table" and data.get("show_cta"):
+            record = data.get("results", data)
+            if isinstance(record, list) and record:
+                record = record[0]
+            if isinstance(record, dict):
+                hint = detail_hint(client, brand=record.get("name"))
+                if hint:
+                    Console(stderr=True).print(f"\n[yellow]{hint}[/yellow]")
+    except ApiError as e:
+        _handle_brand_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("history")
+def history_cmd(
+    query: str = typer.Argument(..., help="Brand name or numeric ID"),
+    channel: int | None = typer.Option(None, "--channel", "-c", help="Filter to a specific channel"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results"),
+    offset: int = typer.Option(0, "--offset", help="Pagination offset"),
+) -> None:
+    """Show a brand's sponsorship history (videos where the brand was detected).
+
+    Requires an Intelligence plan.
+
+    Examples:
+        tl brands history Nike                          # Nike's sponsorship history
+        tl brands history 21416                         # By brand ID
+        tl brands history Nike --channel 12345          # Nike mentions on a specific channel
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+
+    params: dict[str, str] = {"limit": str(limit), "offset": str(offset)}
+    if channel is not None:
+        params["channel_id"] = str(channel)
+
+    encoded_query = urllib.parse.quote(query, safe="")
+    client = get_client()
+    try:
+        data = client.get(f"/brands/{encoded_query}/history", params=params)
+        brand_name = data.get("brand", {}).get("name", query)
+        output(
+            data,
+            fmt,
+            columns=["video_id", "title", "channel_id", "channel", "views", "publication_date", "is_tl"],
+            title=f"Brand History: {brand_name}",
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+SIMILAR_COLUMNS = ["score", "brand_id", "brand_name", "website", "mbn"]
+SIMILAR_COLUMN_CONFIG = {
+    "score": {"justify": "right"},
+}
+
+
+def _format_score(results: list[dict]) -> list[dict]:
+    """Convert raw cosine score (0.0-1.0) to percentage string."""
+    for row in results:
+        score = row.get("score")
+        if isinstance(score, (int, float)):
+            row["score"] = f"{score * 100:.1f}%"
+    return results
+
+
+@app.command("similar")
+def similar_cmd(
+    query: str = typer.Argument(..., help="Brand name or numeric ID"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(20, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Find brands similar to a given one (by ID or name).
+
+    Costs 50 credits per call. Intelligence plan required.
+
+    Examples:
+        tl brands similar Nike
+        tl brands similar 6037
+        tl brands similar 6037 mbn:yes --limit 10
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    encoded_query = urllib.parse.quote(query, safe="")
+    params: dict[str, str] = {"limit": str(limit)}
+
+    client = get_client()
+    try:
+        data = client.get(f"/brands/{encoded_query}/similar", params=params)
+        brand_name = data.get("brand", {}).get("name", query)
+        if fmt in ("table", "md"):
+            _format_score(data.get("results", []))
+        output(
+            data,
+            fmt,
+            columns=SIMILAR_COLUMNS,
+            title=f"Brands similar to {brand_name}",
+            column_config=SIMILAR_COLUMN_CONFIG,
+        )
+    except ApiError as e:
+        _handle_brand_api_error(e)
+    finally:
+        client.close()