thoughtleaders-cli 0.7.4__tar.gz → 0.7.6__tar.gz

{thoughtleaders_cli-0.7.4 → thoughtleaders_cli-0.7.6}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

{thoughtleaders_cli-0.7.4 → thoughtleaders_cli-0.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.7.4
+Version: 0.7.6
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli

{thoughtleaders_cli-0.7.4 → thoughtleaders_cli-0.7.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.7.4"
+version = "0.7.6"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

{thoughtleaders_cli-0.7.4 → thoughtleaders_cli-0.7.6}/skills/tl/SKILL.md

@@ -50,6 +50,13 @@ The pattern is always: server-side narrowing first (usually by filters in the `t
 
 Always assume there will be more than 1 page of results. You MUST always pass `LIMIT` and `OFFSET` to every `tl db pg|fb|es` query (and use the response envelope's `next_offset` / breadcrumbs to walk forward) so the entire data set is retrieved. The maximum number of rows per page is present in the output of `whoami`.
 
+**Counts, totals, and breakdowns: aggregate in the query engine — never page through records to count them.** A "how many / total / average / per-X" question is ONE aggregation query, not N pages of rows summed in your head:
+- `tl db pg` — `SELECT COUNT(*) …`, or `SELECT col, COUNT(*) AS n … GROUP BY col ORDER BY n DESC`. Also `SUM`/`AVG`/`MIN`/`MAX`/`date_trunc`. Returns one/few rows regardless of table size. (`LIMIT`/`OFFSET` still required — an aggregate is one row, so `LIMIT 1 OFFSET 0` is fine.)
+- `tl db es` — aggregation body with `"size": 0` (returns zero hits, only the agg result): `value_count`/`cardinality` for counts, `terms` for per-group, `sum`/`avg` for metrics, `date_histogram` for time series. Add `"track_total_hits": true` to get an exact match count. One aggregation block per body (see ES reference) — run multiple calls for a multi-metric dashboard.
+- Structured list commands and list endpoints already return the full match count as `total` in the response envelope — request `--limit 1` and read `total` instead of fetching every row.
+
+Fetching all rows to count/sum/group them is wrong: it is slow, costs credits per row returned, and silently undercounts once you hit the page cap.
+
 Retry after 5 seconds if the server returns a "connection denied" or a "server error" on any request.
 
 Where possible reference sponsorships, brands, channel by numeric IDs.
@@ -360,6 +367,13 @@ cat query.json | tl db es -
 
 See [references/elasticsearch-schema.md](references/elasticsearch-schema.md) for accepted top-level keys, query types, size/depth limits, scripting/aggregation rules, and the field catalogue.
 
+**Article docs in ES carry only `channel.id` — not a usable channel name. Resolve names from PG, in a two-step script.** Whenever you query article/upload docs and the output needs channel names, do NOT hand-map ids in context and do NOT `ILIKE` on names — write a script that:
+1. runs `tl db es … --json` with `channel.id` in `_source`, then collects the **distinct** channel ids;
+2. runs `tl db pg "SELECT id, channel_name FROM thoughtleaders_channel WHERE id IN (<ids>)" --json` to build an `{id: channel_name}` map;
+3. merges the map onto the ES rows by `channel.id` and emits the enriched result.
+
+Prefer Python for the script (write it to `/tmp`); a `jq`+`xargs` one-liner is fine for a single page (worked example under *Brand sponsorship history*). Always go ES→PG in this order (PG `IN (...)` on the ids ES returned) — one PG round-trip for the whole page, never one query per article.
+
 #### `tl db fb` — Firebolt
 
 ```bash

{thoughtleaders_cli-0.7.4 → thoughtleaders_cli-0.7.6}/src/tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.7.4"
+__version__ = "0.7.6"

{thoughtleaders_cli-0.7.4 → thoughtleaders_cli-0.7.6}/src/tl_cli/auth/commands.py

@@ -8,9 +8,9 @@ from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 from rich.prompt import Prompt
 
-from tl_cli.auth.finalize import finalize_signup
-from tl_cli.auth.login import login_browser, login_device_code
+from tl_cli.auth.login import login_browser, login_device_code, revoke_refresh_token
 from tl_cli.auth.token_store import KIND_API_KEY, StoredTokens, clear_tokens, load_tokens, save_tokens
+from tl_cli.config import get_config
 
 app = typer.Typer(cls=AlphaSortedTyperGroup, help="Authentication commands")
 console = Console(stderr=True)
@@ -106,8 +106,6 @@ def login_cmd() -> None:
     else:
         login_browser()
 
-    finalize_signup()
-
 
 def _login_api_key() -> None:
     """Store a user-supplied API key as the active credential.
@@ -171,7 +169,27 @@ def _login_api_key() -> None:
 
 @app.command("logout")
 def logout_cmd() -> None:
-    """Clear stored authentication tokens."""
+    """Log out: revoke the refresh token at Auth0, then clear stored tokens."""
+    tokens = load_tokens()
+    # Revoke the long-lived credential server-side so a leaked/synced copy of
+    # the local token store can't keep minting access tokens. Best-effort —
+    # API-key auth has no refresh token, and an offline revoke must not block
+    # clearing local credentials.
+    if tokens and not tokens.is_api_key and tokens.refresh_token:
+        if revoke_refresh_token(tokens.refresh_token):
+            console.print("[dim]Refresh token revoked at Auth0.[/dim]")
+        else:
+            console.print(
+                "[yellow]Could not reach Auth0 to revoke the refresh token; "
+                "clearing local credentials anyway.[/yellow]"
+            )
+        # Revoking the refresh token doesn't end the browser SSO session that
+        # the interactive login established. Point the user at Auth0's logout
+        # URL so the next `tl auth login` doesn't silently SSO straight back in.
+        logout_url = f"https://{get_config().auth0_domain}/logout"
+        console.print(
+            f"To end your Auth0 browser session, visit: [cyan]{logout_url}[/cyan]"
+        )
     clear_tokens()
     console.print("[green]Logged out successfully.[/green]")
 

{thoughtleaders_cli-0.7.4 → thoughtleaders_cli-0.7.6}/src/tl_cli/auth/login.py

@@ -212,6 +212,29 @@ def refresh_access_token(refresh_token: str) -> StoredTokens:
     return tokens
 
 
+def revoke_refresh_token(refresh_token: str) -> bool:
+    """Best-effort revocation of a refresh token at Auth0 (RFC 7009).
+
+    Invalidates the long-lived credential server-side so it can no longer mint
+    new access tokens. Public-client call — `client_id` only, no secret. Returns
+    True on success; never raises — network / Auth0 errors are swallowed so
+    `tl auth logout` can still clear the local credentials when offline.
+    """
+    config = get_config()
+    try:
+        response = httpx.post(
+            f"https://{config.auth0_domain}/oauth/revoke",
+            json={
+                "client_id": config.auth0_client_id,
+                "token": refresh_token,
+            },
+            timeout=10,
+        )
+    except httpx.HTTPError:
+        return False
+    return response.status_code == 200
+
+
 def _exchange_code(
     code: str,
     code_verifier: str,

thoughtleaders_cli-0.7.6/tests/test_auth.py

@@ -0,0 +1,145 @@
+"""Tests for PKCE and token storage."""
+
+import httpx
+from typer.testing import CliRunner
+
+from tl_cli.auth import commands as auth_commands
+from tl_cli.auth import login as auth_login
+from tl_cli.auth.commands import app as auth_app
+from tl_cli.auth.login import revoke_refresh_token
+from tl_cli.auth.pkce import generate_pkce_pair
+from tl_cli.auth.token_store import KIND_API_KEY, KIND_BEARER, StoredTokens
+
+runner = CliRunner()
+
+
+class TestPKCE:
+    def test_generates_pair(self):
+        verifier, challenge = generate_pkce_pair()
+        assert len(verifier) > 40
+        assert len(challenge) > 20
+        assert verifier != challenge
+
+    def test_different_each_time(self):
+        v1, c1 = generate_pkce_pair()
+        v2, c2 = generate_pkce_pair()
+        assert v1 != v2
+        assert c1 != c2
+
+
+class TestStoredTokens:
+    def test_roundtrip_json(self):
+        tokens = StoredTokens(
+            access_token="abc",
+            refresh_token="def",
+            expires_at=9999999999.0,
+            email="test@example.com",
+        )
+        json_str = tokens.to_json()
+        restored = StoredTokens.from_json(json_str)
+        assert restored.access_token == "abc"
+        assert restored.refresh_token == "def"
+        assert restored.email == "test@example.com"
+
+    def test_is_expired(self):
+        tokens = StoredTokens(
+            access_token="abc", refresh_token=None, expires_at=0.0
+        )
+        assert tokens.is_expired
+
+    def test_not_expired(self):
+        tokens = StoredTokens(
+            access_token="abc", refresh_token=None, expires_at=9999999999.0
+        )
+        assert not tokens.is_expired
+
+
+class TestStoredTokensKind:
+    def test_default_kind_is_bearer(self):
+        tokens = StoredTokens(access_token="x", refresh_token=None, expires_at=9e9)
+        assert tokens.kind == KIND_BEARER
+        assert not tokens.is_api_key
+
+    def test_api_key_never_expires(self):
+        tokens = StoredTokens(
+            access_token="k", refresh_token=None, expires_at=0.0, kind=KIND_API_KEY,
+        )
+        assert tokens.is_api_key
+        # 0.0 would mark a bearer token as expired; API keys ignore expiry.
+        assert not tokens.is_expired
+
+    def test_kind_roundtrips_through_json(self):
+        tokens = StoredTokens(
+            access_token="k", refresh_token=None, expires_at=0.0,
+            email="user@example.com", kind=KIND_API_KEY,
+        )
+        restored = StoredTokens.from_json(tokens.to_json())
+        assert restored.kind == KIND_API_KEY
+        assert restored.is_api_key
+        assert restored.email == "user@example.com"
+
+    def test_legacy_payload_without_kind_defaults_to_bearer(self):
+        # Pre-API-key clients wrote payloads with no `kind` field. Loading
+        # those must still produce a working bearer token.
+        legacy = '{"access_token": "x", "refresh_token": "y", "expires_at": 1.0, "email": "e"}'
+        restored = StoredTokens.from_json(legacy)
+        assert restored.kind == KIND_BEARER
+        assert not restored.is_api_key
+
+
+class _FakeResponse:
+    def __init__(self, status_code: int) -> None:
+        self.status_code = status_code
+
+
+class TestRevokeRefreshToken:
+    def test_returns_true_on_200(self, monkeypatch) -> None:
+        monkeypatch.setattr(auth_login.httpx, "post", lambda *a, **k: _FakeResponse(200))
+        assert revoke_refresh_token("rt") is True
+
+    def test_returns_false_on_non_200(self, monkeypatch) -> None:
+        monkeypatch.setattr(auth_login.httpx, "post", lambda *a, **k: _FakeResponse(400))
+        assert revoke_refresh_token("rt") is False
+
+    def test_swallows_network_error(self, monkeypatch) -> None:
+        def boom(*a, **k):
+            raise httpx.ConnectError("offline")
+        monkeypatch.setattr(auth_login.httpx, "post", boom)
+        # Must not raise — logout has to proceed offline.
+        assert revoke_refresh_token("rt") is False
+
+
+class TestLogoutCommand:
+    def _patch(self, monkeypatch, tokens):
+        calls = {"revoked": None, "cleared": False}
+        monkeypatch.setattr(auth_commands, "load_tokens", lambda: tokens)
+        monkeypatch.setattr(auth_commands, "clear_tokens", lambda: calls.__setitem__("cleared", True))
+        monkeypatch.setattr(auth_commands, "revoke_refresh_token", lambda rt: calls.__setitem__("revoked", rt) or True)
+        return calls
+
+    def test_bearer_logout_revokes_then_clears(self, monkeypatch) -> None:
+        tokens = StoredTokens(access_token="a", refresh_token="rt", expires_at=None, email="e@x.com")
+        calls = self._patch(monkeypatch, tokens)
+        result = runner.invoke(auth_app, ["logout"])
+        assert result.exit_code == 0
+        assert calls["revoked"] == "rt"   # revoked with the stored refresh token
+        assert calls["cleared"] is True   # local tokens still cleared
+        # Points the user at Auth0's session-logout URL built from auth0_domain.
+        assert "/logout" in result.output
+        assert auth_commands.get_config().auth0_domain in result.output
+
+    def test_api_key_logout_skips_revoke(self, monkeypatch) -> None:
+        tokens = StoredTokens(access_token="k", refresh_token=None, expires_at=None, email=None, kind=KIND_API_KEY)
+        calls = self._patch(monkeypatch, tokens)
+        result = runner.invoke(auth_app, ["logout"])
+        assert result.exit_code == 0
+        assert calls["revoked"] is None   # no refresh token → no Auth0 call
+        assert calls["cleared"] is True
+        assert "/logout" not in result.output  # no browser session for API-key auth
+
+    def test_logged_out_already_just_clears(self, monkeypatch) -> None:
+        calls = self._patch(monkeypatch, None)
+        result = runner.invoke(auth_app, ["logout"])
+        assert result.exit_code == 0
+        assert calls["revoked"] is None
+        assert calls["cleared"] is True

thoughtleaders_cli-0.7.4/src/tl_cli/auth/finalize.py

@@ -1,88 +0,0 @@
-"""Server-side signup finalize, called once per login.
-
-After Auth0 returns a valid token the CLI asks the server whether an
-account exists for the email. If yes, this is a no-op. If no, the CLI
-prompts for a persona (Media Buyer or Creator) and POSTs it back; the
-server creates the User, Organization, Profile and CreditAccount.
-
-Errors here never abort login — the user can always retry the prompt
-on the next call. We do print a clear message so it's obvious whether
-the account is fully set up.
-"""
-
-from __future__ import annotations
-
-import typer
-from rich.console import Console
-from rich.prompt import Prompt
-
-from tl_cli.client.errors import ApiError
-from tl_cli.client.http import get_client
-
-console = Console(stderr=True)
-
-PERSONA_LABEL_TO_KEY = {
-    "Media Buyer": "media_buyer",
-    "Creator": "creator",
-}
-
-
-def finalize_signup() -> None:
-    """POST /auth/finalize, prompting for persona if the server asks for one."""
-    client = get_client()
-    try:
-        # First call: no body. Server tells us whether persona is required.
-        try:
-            result = client.post("/auth/finalize", {})
-        except ApiError as exc:
-            if exc.status_code == 400 and isinstance(exc.raw, dict) and exc.raw.get("code") == "persona_required":
-                result = _prompt_and_finalize(client, exc.raw.get("allowed_personas") or [])
-            elif exc.status_code == 404:
-                # Server predates this endpoint — silently skip; legacy
-                # accounts already exist and don't need provisioning.
-                return
-            else:
-                console.print(f"[yellow]Could not finalize signup: {exc.detail}[/yellow]")
-                return
-
-        if result.get("created"):
-            org = result.get("organization", {})
-            console.print(
-                f"[green]Account created for {org.get('name', 'your organization')}.[/green] "
-                "Run [bold]tl balance[/bold] to see your starter credits."
-            )
-    finally:
-        client.close()
-
-
-def _prompt_and_finalize(client, allowed: list[str]) -> dict:
-    """Prompt the user for a persona, then retry /auth/finalize."""
-    console.print()
-    console.print("[bold]Welcome to ThoughtLeaders![/bold] We need one more detail to set up your account.")
-    console.print("  [cyan]1[/cyan] — Media Buyer (brands and agencies buying sponsorships)")
-    console.print("  [cyan]2[/cyan] — Creator (channels selling sponsorships)")
-
-    persona_key: str | None = None
-    while persona_key is None:
-        choice = Prompt.ask("I am a", choices=["1", "2"], default="1", console=console)
-        candidate = "media_buyer" if choice == "1" else "creator"
-        if allowed and candidate not in allowed:
-            console.print(f"[yellow]Server rejects persona '{candidate}'. Allowed: {', '.join(allowed)}.[/yellow]")
-            continue
-        persona_key = candidate
-
-    org_name = Prompt.ask(
-        "Organization name (optional, leave blank to use your email)",
-        default="",
-        console=console,
-    ).strip()
-
-    body = {"persona": persona_key}
-    if org_name:
-        body["organization_name"] = org_name
-
-    try:
-        return client.post("/auth/finalize", body)
-    except ApiError as exc:
-        console.print(f"[red]Signup failed:[/red] {exc.detail}")
-        raise typer.Exit(1)

thoughtleaders_cli-0.7.4/tests/test_auth.py

@@ -1,78 +0,0 @@
-"""Tests for PKCE and token storage."""
-
-from tl_cli.auth.pkce import generate_pkce_pair
-from tl_cli.auth.token_store import KIND_API_KEY, KIND_BEARER, StoredTokens
-
-
-class TestPKCE:
-    def test_generates_pair(self):
-        verifier, challenge = generate_pkce_pair()
-        assert len(verifier) > 40
-        assert len(challenge) > 20
-        assert verifier != challenge
-
-    def test_different_each_time(self):
-        v1, c1 = generate_pkce_pair()
-        v2, c2 = generate_pkce_pair()
-        assert v1 != v2
-        assert c1 != c2
-
-
-class TestStoredTokens:
-    def test_roundtrip_json(self):
-        tokens = StoredTokens(
-            access_token="abc",
-            refresh_token="def",
-            expires_at=9999999999.0,
-            email="test@example.com",
-        )
-        json_str = tokens.to_json()
-        restored = StoredTokens.from_json(json_str)
-        assert restored.access_token == "abc"
-        assert restored.refresh_token == "def"
-        assert restored.email == "test@example.com"
-
-    def test_is_expired(self):
-        tokens = StoredTokens(
-            access_token="abc", refresh_token=None, expires_at=0.0
-        )
-        assert tokens.is_expired
-
-    def test_not_expired(self):
-        tokens = StoredTokens(
-            access_token="abc", refresh_token=None, expires_at=9999999999.0
-        )
-        assert not tokens.is_expired
-
-
-class TestStoredTokensKind:
-    def test_default_kind_is_bearer(self):
-        tokens = StoredTokens(access_token="x", refresh_token=None, expires_at=9e9)
-        assert tokens.kind == KIND_BEARER
-        assert not tokens.is_api_key
-
-    def test_api_key_never_expires(self):
-        tokens = StoredTokens(
-            access_token="k", refresh_token=None, expires_at=0.0, kind=KIND_API_KEY,
-        )
-        assert tokens.is_api_key
-        # 0.0 would mark a bearer token as expired; API keys ignore expiry.
-        assert not tokens.is_expired
-
-    def test_kind_roundtrips_through_json(self):
-        tokens = StoredTokens(
-            access_token="k", refresh_token=None, expires_at=0.0,
-            email="user@example.com", kind=KIND_API_KEY,
-        )
-        restored = StoredTokens.from_json(tokens.to_json())
-        assert restored.kind == KIND_API_KEY
-        assert restored.is_api_key
-        assert restored.email == "user@example.com"
-
-    def test_legacy_payload_without_kind_defaults_to_bearer(self):
-        # Pre-API-key clients wrote payloads with no `kind` field. Loading
-        # those must still produce a working bearer token.
-        legacy = '{"access_token": "x", "refresh_token": "y", "expires_at": 1.0, "email": "e"}'
-        restored = StoredTokens.from_json(legacy)
-        assert restored.kind == KIND_BEARER
-        assert not restored.is_api_key