thoughtleaders-cli 0.9.7__tar.gz → 0.9.8__tar.gz

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.8}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: thoughtleaders-cli
-Version: 0.9.7
+Version: 0.9.8
 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.9.7 → thoughtleaders_cli-0.9.8}/hooks/scripts/post-usage.sh

@@ -11,7 +11,7 @@ fi
 
 # Check for 402 (insufficient credits)
 if [[ "$OUTPUT" =~ "402" ]] || [[ "$OUTPUT" =~ "Insufficient credits" ]]; then
-  echo "WARN: Credits exhausted. Deposit more at https://app.thoughtleaders.io/settings/billing" >&2
+  echo "WARN: Credits exhausted. Deposit more at https://app.thoughtleaders.io/billing" >&2
   exit 0
 fi
 

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.8}/pyproject.toml

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

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.8}/skills/tl/SKILL.md

@@ -61,7 +61,7 @@ Retry after 5 seconds if the server returns a "connection denied" or a "server e
 
 Where possible reference sponsorships, brands, channel by numeric IDs.
 
-In raw SQL, match text case-insensitively with `UPPER(x)` on both sides — never `LOWER(x)`, which misses the indexes and times out. See `references/postgres-schema.md`.
+In raw SQL, match text case-insensitively with `UPPER(x)` on both sides — never `LOWER(x)`, which misses the indexes and times out. This includes channel names (`channel_name`, `common_name`), not just handles and URLs. See `references/postgres-schema.md`.
 
 ## Data Model & Terminology
 

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.8}/skills/tl/references/postgres-schema.md

@@ -8,7 +8,7 @@ Accepted SQL:
 - **SELECT only**, single statement. No DDL/DML/transactions/SET/COPY/MERGE.
 - Functions accepted from an explicit list (aggregates, window, string, JSON, math, date-time, array). Catalog-resolving casts (`::regclass`, `::regprocedure`, …) are not accepted.
 - `LIMIT` and `OFFSET` are optional. Omit them and the server fills in `LIMIT 50 OFFSET 0`. Explicit `LIMIT` must be an integer literal ≤ 10,000. Explicit `OFFSET` ≥ 10,000 is rejected with HTTP 403 (`OFFSET_TOO_DEEP`); paginate with the response's `next_offset`/breadcrumbs instead of jumping deep.
-- **Case-insensitive equality: `UPPER(col) = UPPER('…')` / `UPPER(col) IN (UPPER('…'), …)` — never `LOWER(col)`.** The functional indexes on this database are built on `UPPER(…)` (e.g. channel `url`, `common_name`); a `LOWER(col)` predicate can't use them, seq-scans the 1.3M-row channel table, and dies on statement timeout (504). For substring search use `ILIKE '%…%'` on the bare column instead — that's served by trigram indexes where present (`channel_name`, `slug`).
+- **Case-insensitive equality: `UPPER(col) = UPPER('…')` / `UPPER(col) IN (UPPER('…'), …)` — never `LOWER(col)`.** The case-insensitive functional indexes on this database are built on `UPPER(…)` — on channel `channel_name`, `common_name` and `url`, among others. A `LOWER(col)` predicate can't use them: it seq-scans the 1.3M-row channel table (~20s+) and often dies on statement timeout (504). This holds for channel **names** exactly as it does for handles and URLs — see *Finding a single channel or brand ID* below for the bulk-lookup form. For substring search use `ILIKE '%…%'` on the **bare** column instead — that's served by trigram indexes where present (channel `channel_name`, `slug`; brand `name`, `website`). `LOWER(col) ILIKE '%…%'` is both redundant (`ILIKE` is already case-insensitive) and slow (the trigram index is on the bare column).
 
 ## Core Tables
 
@@ -262,16 +262,19 @@ thoughtleaders_adlink
 
 As a special case, the `tl channels find` and `tl brands find` commands accept a name of the channel / brand (be sure to properly quote them for the shell) and will return the respective ID. Use this instead of constructing SQL for this particular case. The commands will return a list of possible choices
 
-For bulk handle/name lookups in SQL (e.g. resolving a list of YouTube handles against `common_name`), compare case-insensitively with `UPPER(…)` on both sides — that's the form the functional indexes serve:
+For bulk handle/name lookups in SQL (e.g. resolving a list of YouTube handles against `common_name`, or a list of channel names against `channel_name`), compare case-insensitively with `UPPER(…)` on both sides — that's the form the functional indexes serve:
 
 ```sql
 SELECT id, channel_name, common_name
 FROM thoughtleaders_channel
 WHERE UPPER(common_name) IN (UPPER('@TheInfographicsShow'), UPPER('@DrewDirksen'))
+   OR UPPER(channel_name) IN (UPPER('The Infographics Show'), UPPER('Drew Dirksen'))
 LIMIT 100 OFFSET 0
 ```
 
-`LOWER(common_name)` (or `LOWER()` on any indexed column) cannot use those indexes — it seq-scans and times out.
+Wrap **both** sides in `UPPER(…)`. `UPPER(col) IN ('lowercase literal', …)` matches nothing, since the indexed side is upper-cased.
+
+`LOWER(channel_name)`, `LOWER(common_name)` — or `LOWER()` on any indexed column — cannot use those indexes. Every such predicate is a full sequential scan of 1.3M channel rows: ~20s when it survives, a 504 statement timeout when it doesn't. One `OR LOWER(col) IN (…)` branch is enough to force the scan even when every other branch in the `WHERE` is indexed, so do not mix the two forms.
 
 ### Common Join Paths
 

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.8}/src/tl_cli/__init__.py

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

thoughtleaders_cli-0.9.8/src/tl_cli/client/errors.py

@@ -0,0 +1,122 @@
+"""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 _split_hint(error: ApiError) -> tuple[str, str | None]:
+    """Separate the server's `hint` from `detail`.
+
+    The server sends the remediation both concatenated into `detail` (for
+    older clients) and as a separate `hint` key — render it on its own line
+    so it can't get lost in the error. Used by every branch: a hint on a
+    billing refusal (402/403/429) is just as actionable as one on a 400.
+    """
+    detail = error.detail or ""
+    hint = (error.raw or {}).get("hint") if isinstance(error.raw, dict) else None
+    if isinstance(hint, str) and hint:
+        if detail.endswith(hint):
+            detail = detail[: -len(hint)].rstrip()
+        return detail, hint
+    return detail, None
+
+
+def _print_hint(hint: str | None) -> None:
+    if hint:
+        err.print(f"[bold yellow]Hint:[/bold yellow] [yellow]{hint}[/yellow]")
+
+
+def handle_api_error(error: ApiError) -> None:
+    """Print a user-friendly error message and exit with the right code."""
+    detail, hint = _split_hint(error)
+    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:
+        # The server composes the whole story into `detail` — a prepaid org is
+        # told to deposit, a subscription org that it can also just wait for
+        # the next top-up — and only the server knows which org this is. The
+        # old fixed copy overwrote that with the same top-up pitch for
+        # everyone. The `tl credits buy` line stays: it is the CLI-native way
+        # to act on the refusal, which the server's sentence can't know about.
+        if detail:
+            err.print(f"[red]{detail}[/red]")
+        else:
+            err.print("[red]Insufficient credits.[/red]")
+            err.print("Or visit: https://app.thoughtleaders.io/billing")
+        _print_hint(hint)
+        err.print("Top up with: [bold]tl credits buy --amount-usd 10[/bold]")
+        _print_debug(error)
+        sys.exit(4)
+    elif error.status_code == 403:
+        # Verbatim, with no upsell line of our own: a billing 403's detail
+        # already names the paid plan (UPGRADE_MESSAGE and friends), and the
+        # rest of the 403s — "Superuser only", permission errors — are not
+        # plan problems, so "your plan may not include this" was misdirection
+        # exactly where the user needed the real reason.
+        err.print(f"[red]Access denied:[/red] {detail}")
+        _print_hint(hint)
+        _print_debug(error)
+        sys.exit(1)
+    elif error.status_code == 404:
+        err.print(f"[yellow]Not found:[/yellow] {detail}")
+        _print_hint(hint)
+        _print_debug(error)
+        sys.exit(1)
+    elif error.status_code == 429:
+        # Both quota gates refuse with 429 and compose the whole explanation
+        # into `detail` — which cap was hit, how much of it is used, and when it
+        # frees up. Collapsing that to a flat "rate limited" line drops the only
+        # thing that tells the user whether to wait, buy credits, or ask for a
+        # seat. An edge/WAF 429 carries no detail and keeps the generic wording.
+        if detail:
+            err.print(f"[yellow]{detail}[/yellow]")
+        else:
+            err.print("[yellow]Rate limited.[/yellow] Please wait and try again.")
+        _print_hint(hint)
+        _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] {detail}")
+        _print_hint(hint)
+        _print_debug(error)
+        sys.exit(1)

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.8}/src/tl_cli/commands/balance.py

@@ -53,6 +53,17 @@ def balance(
         if allow_overage:
             console.print("[dim]Overage: enabled[/dim]")
 
+        # The server's own read on the caller's allowance — the session-quota
+        # percentage, or the seatless explanation. This is the same sentence
+        # the refusal path uses, so a seatless member learns why from
+        # `tl balance` instead of only from their first refused call (it used
+        # to be visible solely under --json).
+        usage = data.get("credit_usage") or {}
+        usage_message = usage.get("message")
+        if isinstance(usage_message, str) and usage_message:
+            style = "yellow" if usage.get("warn") else "dim"
+            console.print(f"[{style}]{usage_message}[/{style}]")
+
         # Top-up hint when running low. Threshold matches the hook warning
         # that nudges the user before they hit 0.
         try:
@@ -63,7 +74,7 @@ def balance(
             console.print(
                 "[yellow]Running low.[/yellow] Top up with: "
                 "[bold]tl credits buy --amount-usd 10[/bold] "
-                "(or https://app.thoughtleaders.io/billing/cli)"
+                "(or https://app.thoughtleaders.io/billing)"
             )
 
         recent = data.get("recent_usage", [])

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.8}/src/tl_cli/output/formatter.py

@@ -95,12 +95,14 @@ def output(
         # Banner still goes to stderr so it surfaces even when stdout is
         # piped through `jq` or redirected to a file.
         _print_quota_notice(data)
+        _print_upgrade_notice(data)
         _print_server_warnings(data)
         return
 
     if not results:
         err_console.print("[dim]No results found.[/dim]")
         _print_quota_notice(data)
+        _print_upgrade_notice(data)
         _print_server_warnings(data)
         _print_usage(usage)
         return
@@ -121,6 +123,7 @@ def output(
 
     _print_pagination_notice(data)
     _print_quota_notice(data)
+    _print_upgrade_notice(data)
     _print_server_warnings(data)
     _print_usage(usage)
     _print_breadcrumbs(breadcrumbs)
@@ -523,17 +526,17 @@ def _print_server_warnings(data: dict) -> None:
 
 
 def _print_quota_notice(data: dict) -> None:
-    """Print a banner when the server signals a billing-quota refusal or
-    truncation on a raw-DB call.
-
-    The server emits `_billing_quota_exhausted` on the response envelope
-    in two cases: (a) the query was refused outright before execution
-    because the org has already used its expensive-query allowance for
-    the window; (b) the query ran but the result list was truncated
-    because the remaining expensive-row allowance was smaller than the
-    natural row count. Either way the response carries an empty or
-    short ``results`` array and the caller needs to know *why* and
-    *when they can retry*.
+    """Print a banner when the server signals a billing-quota truncation
+    on a raw-DB call.
+
+    The query ran, but the result list was cut to the org's remaining
+    premium-row allowance for the window — so ``results`` is short of what
+    the query would naturally return, and the caller needs to know *why*
+    and *when the rest becomes reachable*.
+
+    An outright refusal never lands here: it is a 429 carrying the server's
+    detail, rendered by `client.errors.handle_api_error`. A short result set
+    and a refused query must not look alike.
     """
     if not data.get("_billing_quota_exhausted"):
         return
@@ -555,6 +558,28 @@ def _print_quota_notice(data: dict) -> None:
         )
 
 
+def _print_upgrade_notice(data: dict) -> None:
+    """Print a banner when the server withheld premium fields from a
+    successful response (``_upgrade_required``).
+
+    The rows are real, but transcript / brand-mention / demographic fields
+    were omitted for the caller's plan — without this line a free-tier user
+    reads the gaps as "no data exists". The sentence is the server's own
+    (UPGRADE_MESSAGE), the same one the web app's field locks show, so the
+    wording stays composed in exactly one place.
+    """
+    notice = data.get("_upgrade_required")
+    if not isinstance(notice, dict):
+        return
+    message = notice.get("message") or "Some fields are available on paid plans."
+    err_console.print(f"[bold yellow]⚠ {message}[/bold yellow]")
+    fields = notice.get("fields") or []
+    if fields:
+        err_console.print(
+            f"[yellow]  withheld field(s): {', '.join(str(f) for f in fields)}[/yellow]"
+        )
+
+
 def output_pricing_estimate(data: dict, fmt: str) -> None:
     """Render the `--pricing` dry-run estimate for `tl db pg|fb|es`.
 

thoughtleaders_cli-0.9.8/tests/test_quota_refusal_message.py

@@ -0,0 +1,68 @@
+"""Tests for what a 429 quota refusal actually tells the user.
+
+Both server-side quota gates refuse with 429 and put the entire remedy into
+`detail`: which cap was hit, how much of it is spent, and when it frees up. The
+user's next action differs per gate — wait out a rolling window, buy credits,
+or ask an org admin for a seat — so a generic "rate limited" line is not a
+smaller version of the message, it is the wrong message.
+"""
+
+import pytest
+
+from tl_cli.client.errors import ApiError, handle_api_error
+
+
+def _render(error: ApiError, capsys) -> str:
+    with pytest.raises(SystemExit) as exc:
+        handle_api_error(error)
+    assert exc.value.code == 3
+    return " ".join(capsys.readouterr().err.split())  # undo console wrapping
+
+
+class TestQuotaRefusalMessage:
+    def test_premium_data_quota_detail_reaches_the_user(self, capsys):
+        detail = (
+            "Premium data quota reached: your organization has used 100 of 100 "
+            "premium-data rows in the last 24h. Wait ~3.2h until the oldest call "
+            "rolls off the window (2026-08-17T14:02:11+00:00)."
+        )
+        out = _render(
+            ApiError(429, detail, raw={"detail": detail, "code": "quota_exhausted"}),
+            capsys,
+        )
+        assert "100 of 100 premium-data rows" in out
+        assert "Wait ~3.2h" in out
+
+    def test_per_user_credit_quota_detail_reaches_the_user(self, capsys):
+        detail = (
+            "Per-user CLI credit quota reached: 1236.32 of 1200.00 credits used this "
+            "session (5h window). Wait ~5.0h until your session resets "
+            "(2026-08-17T16:21:13+00:00); you can then spend up to 1200.00 credits "
+            "again. Or buy credits to continue without waiting: "
+            "https://app.thoughtleaders.io/billing"
+        )
+        out = _render(
+            ApiError(429, detail, raw={"detail": detail, "code": "quota_exhausted"}),
+            capsys,
+        )
+        assert "1236.32 of 1200.00 credits" in out
+        # The remedy is the point: without it the user cannot tell that buying
+        # credits skips the wait.
+        assert "buy credits" in out
+
+    def test_seatless_refusal_names_the_remedy(self, capsys):
+        detail = (
+            "No CLI seat is assigned to your user in this organization. Ask an "
+            "organization owner or admin to assign you a seat: "
+            "https://app.thoughtleaders.io/billing"
+        )
+        out = _render(
+            ApiError(429, detail, raw={"detail": detail, "code": "quota_exhausted"}),
+            capsys,
+        )
+        assert "assign you a seat" in out
+
+    def test_bare_429_keeps_the_generic_wording(self, capsys):
+        # An edge/WAF rate limit carries no detail; there is nothing to explain.
+        out = _render(ApiError(429, "", raw=None), capsys)
+        assert "Rate limited." in out

thoughtleaders_cli-0.9.8/tests/test_refusal_rendering.py

@@ -0,0 +1,109 @@
+"""Tests for how billing refusals and withheld fields reach the user.
+
+The server composes every refusal's story into `detail` (and names the code
+in `code`); the CLI's job is to deliver it verbatim, add the CLI-native way
+to act on it, and never bolt on a diagnosis of its own. These tests pin the
+three places that used to do otherwise: the 402 branch (fixed copy that
+overwrote the server's prepaid/subscription distinction), the 403 branch
+(a blanket "your plan may not include this" on every 403, superuser gates
+included), and successful envelopes whose premium fields were silently
+withheld (`_upgrade_required`).
+"""
+
+import pytest
+
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.output.formatter import output
+
+
+def _render(error: ApiError, capsys, code: int) -> str:
+    with pytest.raises(SystemExit) as exc:
+        handle_api_error(error)
+    assert exc.value.code == code
+    return " ".join(capsys.readouterr().err.split())  # undo console wrapping
+
+
+class TestInsufficientCredits402:
+    def test_server_detail_reaches_the_user_verbatim(self, capsys):
+        # The subscription org's alternative — wait for the next top-up —
+        # exists only in the server's sentence. Fixed client copy erased it.
+        detail = (
+            "Your organization is out of CLI credits for this top-up period. "
+            "Buy credits at https://app.thoughtleaders.io/billing or wait for "
+            "the next top-up."
+        )
+        out = _render(
+            ApiError(402, detail, raw={"detail": detail, "code": "insufficient_credits"}),
+            capsys,
+            code=4,
+        )
+        assert "wait for the next top-up" in out
+        # The CLI-native affordance stays alongside the server's sentence.
+        assert "tl credits buy" in out
+
+    def test_empty_detail_falls_back_to_the_generic_copy(self, capsys):
+        out = _render(ApiError(402, "", raw=None), capsys, code=4)
+        assert "Insufficient credits." in out
+        assert "tl credits buy" in out
+
+
+class TestAccessDenied403:
+    def test_plan_gate_detail_is_verbatim_without_a_second_diagnosis(self, capsys):
+        detail = "Snapshots require a paid plan"
+        out = _render(
+            ApiError(403, detail, raw={"detail": detail, "code": "plan_required"}),
+            capsys,
+            code=1,
+        )
+        assert "Access denied: Snapshots require a paid plan" in out
+        # The detail already names the plan; a bolted-on suggestion would be
+        # redundant here and wrong on every non-billing 403.
+        assert "Your plan may not include" not in out
+
+    def test_superuser_gate_gets_no_plan_upsell(self, capsys):
+        out = _render(ApiError(403, "Superuser only", raw={"detail": "Superuser only"}), capsys, code=1)
+        assert "Access denied: Superuser only" in out
+        assert "plan" not in out.lower()
+
+
+class TestHintsOnBillingStatuses:
+    # A hint on a refusal is just as actionable as one on a 400 — the old
+    # handler only rendered hints on the generic branch.
+    def test_hint_renders_on_403(self, capsys):
+        error = ApiError(403, "Query rejected: premium column(s)", raw={"hint": "Name the columns you want."})
+        out = _render(error, capsys, code=1)
+        assert "Hint: Name the columns you want." in out
+
+    def test_hint_renders_on_429(self, capsys):
+        error = ApiError(429, "Premium data quota reached", raw={"hint": "Assign another seat."})
+        out = _render(error, capsys, code=3)
+        assert "Hint: Assign another seat." in out
+
+
+class TestUpgradeNoticeOnSuccess:
+    def test_withheld_fields_are_announced_on_stderr(self, capsys):
+        # ES attaches `_upgrade_required` to a 200 whose premium fields were
+        # stripped; silently missing fields read as "no data exists".
+        output(
+            {
+                "results": [{"id": 1, "title": "video"}],
+                "_upgrade_required": {
+                    "fields": ["transcript", "sponsored_brand_mentions"],
+                    "message": (
+                        "Audience demographics, channel outreach emails, video "
+                        "transcripts and brand mentions are available on paid plans."
+                    ),
+                },
+            },
+            fmt="json",
+        )
+        captured = capsys.readouterr()
+        err_out = " ".join(captured.err.split())
+        assert "available on paid plans" in err_out
+        assert "transcript, sponsored_brand_mentions" in err_out
+        # The notice is a banner, not data: stdout stays valid JSON.
+        assert "_upgrade_required" in captured.out
+
+    def test_absent_key_prints_nothing(self, capsys):
+        output({"results": [{"id": 1}]}, fmt="json")
+        assert "paid plans" not in capsys.readouterr().err

thoughtleaders_cli-0.9.7/src/tl_cli/client/errors.py

@@ -1,84 +0,0 @@
-"""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("Top up with: [bold]tl credits buy --amount-usd 10[/bold]")
-        err.print("Or visit: https://app.thoughtleaders.io/billing/cli")
-        _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:
-        detail = error.detail or ""
-        hint = (error.raw or {}).get("hint") if isinstance(error.raw, dict) else None
-        if isinstance(hint, str) and hint:
-            # The server sends the remediation both concatenated into
-            # `detail` (for older clients) and as a separate `hint` key —
-            # render it on its own line so it can't get lost in the error.
-            if detail.endswith(hint):
-                detail = detail[: -len(hint)].rstrip()
-            err.print(f"[red]Error ({error.status_code}):[/red] {detail}")
-            err.print(f"[bold yellow]Hint:[/bold yellow] [yellow]{hint}[/yellow]")
-        else:
-            err.print(f"[red]Error ({error.status_code}):[/red] {detail}")
-        _print_debug(error)
-        sys.exit(1)