thoughtleaders-cli 0.6.10__tar.gz → 0.6.12__tar.gz

{thoughtleaders_cli-0.6.10 → thoughtleaders_cli-0.6.12}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.10 → thoughtleaders_cli-0.6.12}/AGENTS.md

@@ -95,6 +95,7 @@ The version string is defined in three files and all three must be updated toget
 ## Coding
 
 * Do not reference internal architecture of the ThoughtLeaders app in comments or skills. Specifially: do not reference internal table names, field names, API endpoints, Python modules or functions (including the sanitizer).
+* Do not let server implementation details into skill files (anything under `skills/`). Skills describe *what the CLI does* from the user's seat — observable command surface, inputs, outputs, examples. Do not say "the server enforces X", "the API validates Y on its side", "the backend rejects Z" — those are mechanism notes that drift the moment the server changes. State the user-visible behaviour ("unknown keys come back as 400") without naming where it's enforced.
 * Place all imports at the start of the Python module file
 
 # Git commit rules

{thoughtleaders_cli-0.6.10 → thoughtleaders_cli-0.6.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.10
+Version: 0.6.12
 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.6.10 → thoughtleaders_cli-0.6.12}/pyproject.toml

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

{thoughtleaders_cli-0.6.10 → thoughtleaders_cli-0.6.12}/skills/tl/SKILL.md

@@ -141,7 +141,7 @@ Prefer writing Python code, shell code, or `jq` commands that fetche or analysis
 tl sponsorships list [filters...]      # Sponsorships — list curve, mult 1.0
 tl sponsorships show <id>              # Sponsorship detail (2 credits)
 tl sponsorships create --channel <id> --brand <id>  # Create proposal (free)
-tl sponsorships update <id> '<json>'   # Update whitelisted fields (2 credits) — only `publish_status` editable; non-full-access users can only edit sponsorships in their own org
+tl sponsorships update <id> '<json>'   # Update a sponsorship (2 credits)
 tl deals list [filters...]             # Shortcut: agreed-upon sponsorships (status:deal); same curve as sponsorships list
 tl deals show <id>                     # Deal detail (2 credits)
 tl matches list [filters...]           # Shortcut: possible brand-channel pairings (status:match); same curve
@@ -153,7 +153,7 @@ tl proposals create --channel <id> --brand <id>  # Create proposal (free)
 tl uploads list [filters...]           # Video uploads from ES — list curve, mult 1.0
 tl uploads show <id>                   # Upload detail (2 credits)
 tl channels show <id-or-name>          # Channel detail (2 credits; accepts numeric ID or name) — for channel search use raw SQL on thoughtleaders_channel
-tl channels update <id> '<json>'       # Update whitelisted demographic fields (2 credits; full-access only)
+tl channels update <id> '<json>'       # Update a channel (2 credits)
 tl channels history <id-or-name>       # Sponsorship history (5 credits/result, linear)
 tl channels similar <id-or-name>       # Similarity recommender (25 credits flat; Intelligence plan)
 tl brands show <id-or-name>            # Brand detail (1 credit)
@@ -182,17 +182,11 @@ tl <entity> comment-edit <comment-id> "msg"  # Edit own comment (author or super
 
 ### Updating records
 
-A narrow write surface is exposed for two resources. Each command takes the record id and a single JSON object with the fields to change; the server enforces a hard-coded field whitelist and rejects anything else with a 400. Each call costs 2 credits.
-
 ```bash
 tl sponsorships update <id> '<json>'   # Edit a sponsorship (adlink)
 tl channels update <id> '<json>'       # Edit a channel
 ```
 
-**Sponsorships** — only `publish_status` is editable. Accepts either an int code or a status label (`proposed`, `pending`, `sold`, `matched`, `outreach`, `proposal_approved`, `advertiser_reject`, `publisher_reject`, `agency_reject`, `unavailable`). Non-full-access users may only update sponsorships tied to their own organization (either through `creator_profile` or through the channel's `publication`). Trying to edit a sponsorship outside the user's org returns 403.
-
-**Channels** — only the demographic fields are editable: `demographic_usa_share` and `demographic_male_share` (integers 0–100), `demographic_age` / `demographic_device` / `demographic_geo` (JSON objects with numeric values). Requires full-access permission; non-full-access users get a 403. The `demographics_updated_at` timestamp is refreshed automatically when any whitelisted demographic field changes.
-
 Examples:
 ```bash
 tl sponsorships update 98765 '{"publish_status": "sold"}'
@@ -202,7 +196,7 @@ tl channels update 12345 '{"demographic_geo": {"US": 60, "UK": 12, "CA": 8}}'
 tl channels update 12345 '{"demographic_male_share": 55, "demographic_usa_share": 70}'
 ```
 
-Anything outside these whitelists — price, cost, owner, channel name, etc. — is not editable through the CLI and must be done in the app or by a human with DB access.
+Each call costs 2 credits. If a request is rejected with a 400, the response body names the offending key — read it and retry with a smaller body. If the user wants to edit something the API rejects, the change has to be made in the app or by a human with DB access.
 
 ### Raw queries (`tl db`)
 
@@ -326,8 +320,6 @@ See [references/business-glossary.md](references/business-glossary.md) for reven
 | Arbitrary read-only `SELECT` on Postgres | **Available** via `tl db pg`. | SELECT-only, mandatory `LIMIT ≤ 500` + `OFFSET`, only certain SQL forms are allowed. See `references/postgres-schema.md`. |
 | Cross-reference helpers ("channels proposed to brand X", "channels sponsored by MBN brands in last N days") | **Available** via `tl db pg`. | Write the join: `thoughtleaders_adlink` ↔ `adspot` ↔ `channel` ↔ `profile` ↔ `profile_brands` ↔ `brand`. Filter by `publish_status` for proposed/sold and by date range as needed. See `references/postgres-schema.md` for the exact column names. |
 | **AdLink INSERT** with custom price/cost/owner/`weighted_price`/`created_where` | **Unavailable** — `tl sponsorships create` exists but only creates a free *proposal* between a channel and a brand. The `tl db pg` sanitizer accepts SELECT only — no INSERT/UPDATE. | Done in the app or by a human with DB access. |
-| **AdLink UPDATE** of any field other than `publish_status` (price, cost, owner, send_date, …) | **Unavailable** — `tl sponsorships update` only accepts `publish_status` and only for sponsorships in the user's org (full-access bypasses the org check). | Done in the app or by a human with DB access. |
-| **Channel UPDATE** of any field other than the demographic fields (`demographic_usa_share`, `demographic_male_share`, `demographic_age`, `demographic_device`, `demographic_geo`) | **Unavailable** — `tl channels update` only accepts those fields, and only for full-access users. | Done in the app or by a human with DB access. |
 | Pre-insert validation queries (joining `adspot ↔ channel ↔ profile ↔ org` to confirm MSN, integration=1, persona, plan) | **Available** via `tl db pg`. | One SELECT joining the four tables. Use `thoughtleaders_channel.media_selling_network_join_date IS NOT NULL` for MSN, `thoughtleaders_adspot.integration = 1` for mention adspots, `thoughtleaders_profile.persona` for the persona code (see persona constants in `references/postgres-schema.md`). |
 | Firebolt cross-table or join queries; filtering on non-indexed columns in WHERE | **Unavailable** — not accepted. | Fetch a wider slice keyed on `channel_id` (and optionally `id`), filter the rest in `jq`/Python. |
 | ES `query_string`, `regexp`, `wildcard`, `fuzzy`, `more_like_this`, parent/child joins; any `script_*`; multiple aggregations in one body | **Unavailable** — not accepted. | Rewrite using `term`/`terms`/`match`/`bool`/`nested`. For multi-agg dashboards, run multiple `tl db es` calls and combine client-side. For "similar"-style queries, try `tl channels similar` / `tl brands similar` (server-implemented similarity search). |

{thoughtleaders_cli-0.6.10 → thoughtleaders_cli-0.6.12}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.10 → thoughtleaders_cli-0.6.12}/src/tl_cli/commands/channels.py

@@ -238,19 +238,13 @@ def history_cmd(
 @app.command("update")
 def update_cmd(
     channel_id: int = typer.Argument(..., help="Channel ID (numeric)"),
-    fields: str = typer.Argument(..., help='JSON object of fields to update, e.g. \'{"demographic_male_share": 62}\''),
+    fields: str = typer.Argument(..., help='JSON object of fields to update'),
     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:
-    """Update whitelisted channel fields (demographics; full-access only).
+    """Update a channel.
 
-    Editable fields: demographic_usa_share, demographic_male_share,
-    demographic_age, demographic_device, demographic_geo. The
-    demographics_updated_at timestamp is refreshed automatically.
-
-    Examples:
-        tl channels update 12345 '{"demographic_male_share": 62}'
-        tl channels update 12345 '{"demographic_geo": {"US": 60, "UK": 12}}'
+    Unknown fields are rejected with a 400 listing the offending key.
     """
     fmt = detect_format(json_output, False, False, toon_output)
     try:

{thoughtleaders_cli-0.6.10 → thoughtleaders_cli-0.6.12}/src/tl_cli/commands/reports.py

@@ -10,9 +10,9 @@ from rich.text import Text
 
 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
+from tl_cli.output.formatter import detect_format, output, output_single
 
-app = typer.Typer(help="Saved reports (list, run, create)")
+app = typer.Typer(help="Saved reports (list, run, create, update)")
 err = Console(stderr=True)
 
 # Report type labels matching Django's ReportType enum
@@ -226,75 +226,120 @@ def _handle_follow_up(result: dict) -> str:
     return answer
 
 
+def _parse_config_arg(config_json: str) -> dict:
+    """Parse the --config argument string into a dict, exiting cleanly on bad input."""
+    try:
+        config = json.loads(config_json)
+    except json.JSONDecodeError as exc:
+        err.print(f"[red]--config is not valid JSON: {exc}[/red]")
+        raise typer.Exit(1)
+    if not isinstance(config, dict):
+        err.print("[red]--config must be a JSON object.[/red]")
+        raise typer.Exit(1)
+    return config
+
+
+def _orchestrate_via_server(
+    client,
+    prompt: str,
+    timeout: int,
+) -> dict:
+    """Run the server-side AI Report Builder loop and return the resulting config."""
+    conversation: list[dict[str, str]] = []
+    current_prompt = prompt
+
+    while True:
+        # Send prompt to server, poll for result
+        try:
+            create_data = client.post("/reports/create", json_body={
+                "prompt": current_prompt,
+                "conversation": conversation,
+            })
+        except ApiError as e:
+            if e.status_code == 503:
+                err.print("[red]AI Report Builder is temporarily unavailable. Please try again later.[/red]")
+                raise typer.Exit(1)
+            handle_api_error(e)
+            raise typer.Exit(1)
+
+        task_id = create_data.get("task_id")
+        if not task_id:
+            err.print("[red]Server did not return a task ID.[/red]")
+            raise typer.Exit(1)
+
+        result = _poll_for_result(client, task_id, timeout)
+        action = result.get("action", "")
+
+        if action == "follow_up":
+            answer = _handle_follow_up(result)
+            conversation.append({"role": "user", "content": current_prompt})
+            conversation.append({"role": "assistant", "content": result.get("question", "")})
+            current_prompt = answer
+            continue
+
+        if action in ("error", "unsupported"):
+            message = result.get("message", "Request could not be processed.")
+            err.print(f"\n[red]{message}[/red]")
+            raise typer.Exit(1)
+
+        if action == "preview":
+            return result.get("config", {})
+        if action == "create_report":
+            return result
+
+        err.print(f"[yellow]Unexpected action: {action}[/yellow]")
+        err.print(json.dumps(result, indent=2, default=str))
+        raise typer.Exit(1)
+
+
 @app.command("create")
 def create_report(
-    prompt: str = typer.Argument(..., help="Natural language description of the report you want"),
+    prompt: str | None = typer.Argument(
+        None,
+        help="Natural language description of the report you want. Omit when using --config.",
+    ),
+    config_json: str | None = typer.Option(
+        None,
+        "--config",
+        help=(
+            "Pre-built report config as JSON. Skips the AI Report Builder "
+            "pipeline and saves the config directly. Mutually exclusive with "
+            "the prompt argument."
+        ),
+    ),
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
     json_output: bool = typer.Option(False, "--json", help="Output raw JSON config"),
     timeout: int = typer.Option(300, "--timeout", help="Max orchestration time in seconds"),
 ) -> None:
-    """Create a report from a natural language description.
+    """Create a report from a natural-language prompt or a pre-built config.
 
-    Sends your prompt to the ThoughtLeaders server, which runs the AI Report
-    Builder pipeline (keyword research, config generation, review). Then
-    confirms with the server to create the campaign.
+    With a prompt, runs the AI Report Builder pipeline (keyword research, config
+    generation, review) and saves the resulting campaign.
+
+    With --config '<json>', skips the orchestration pipeline and saves the
+    provided config directly. Useful when an external agent (e.g. the
+    tl-report-builder Claude Code skill) has already produced a validated
+    config and you just want to persist it.
 
     Examples:
         tl reports create "gaming channels sponsoring energy drinks"
         tl reports create "tech review channels with 100K+ subscribers" --yes
-        tl reports create "beauty brands on YouTube" --json
+        tl reports create --config "$(cat config.json)" --yes
     """
+    if (prompt is None) == (config_json is None):
+        err.print(
+            "[red]Provide either a natural-language prompt OR --config '<json>', not both.[/red]"
+        )
+        raise typer.Exit(1)
+
     client = get_client()
     try:
-        conversation: list[dict[str, str]] = []
-        current_prompt = prompt
-
-        while True:
-            # Send prompt to server, poll for result
-            try:
-                create_data = client.post("/reports/create", json_body={
-                    "prompt": current_prompt,
-                    "conversation": conversation,
-                })
-            except ApiError as e:
-                if e.status_code == 503:
-                    err.print("[red]AI Report Builder is temporarily unavailable. Please try again later.[/red]")
-                    raise typer.Exit(1)
-                handle_api_error(e)
-                raise typer.Exit(1)
-
-            task_id = create_data.get("task_id")
-            if not task_id:
-                err.print("[red]Server did not return a task ID.[/red]")
-                raise typer.Exit(1)
-
-            result = _poll_for_result(client, task_id, timeout)
-            action = result.get("action", "")
-
-            # Server wraps response: "preview" → config in result["config"]
-            if action == "follow_up":
-                answer = _handle_follow_up(result)
-                conversation.append({"role": "user", "content": current_prompt})
-                conversation.append({"role": "assistant", "content": result.get("question", "")})
-                current_prompt = answer
-                continue
-
-            if action in ("error", "unsupported"):
-                message = result.get("message", "Request could not be processed.")
-                err.print(f"\n[red]{message}[/red]")
-                raise typer.Exit(1)
-
-            if action == "preview":
-                config = result.get("config", {})
-            elif action == "create_report":
-                config = result
-            else:
-                err.print(f"[yellow]Unexpected action: {action}[/yellow]")
-                if json_output:
-                    print(json.dumps(result, indent=2, default=str))
-                raise typer.Exit(1)
-
-            break
+        if config_json is not None:
+            config = _parse_config_arg(config_json)
+            saved_prompts: list[str] = []
+        else:
+            config = _orchestrate_via_server(client, prompt, timeout)
+            saved_prompts = [prompt]
 
         # --- Show preview ---
         if json_output:
@@ -315,7 +360,7 @@ def create_report(
         # --- Save to server ---
         data = client.post("/reports/confirm", json_body={
             "config": config,
-            "prompts": [prompt],
+            "prompts": saved_prompts,
             "reasoning": "",
         })
 
@@ -344,3 +389,34 @@ def create_report(
         handle_api_error(e)
     finally:
         client.close()
+
+
+@app.command("update")
+def update_report(
+    report_id: int = typer.Argument(..., help="Report ID"),
+    fields: str = typer.Argument(..., help='JSON object of fields to update'),
+    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:
+    """Update a saved report.
+
+    Unknown fields are rejected with a 400 listing the offending key.
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    try:
+        body = json.loads(fields)
+    except json.JSONDecodeError as exc:
+        err.print(f"[red]Error:[/red] fields argument must be a JSON object: {exc}")
+        raise typer.Exit(1)
+    if not isinstance(body, dict):
+        err.print("[red]Error:[/red] fields argument must be a JSON object.")
+        raise typer.Exit(1)
+
+    client = get_client()
+    try:
+        data = client.post(f"/reports/{report_id}/edit", json_body=body)
+        output_single(data, fmt)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

{thoughtleaders_cli-0.6.10 → thoughtleaders_cli-0.6.12}/src/tl_cli/commands/sponsorships.py

@@ -198,19 +198,13 @@ def create_cmd(
 @app.command("update")
 def update_cmd(
     sponsorship_id: int = typer.Argument(..., help="Sponsorship (adlink) ID"),
-    fields: str = typer.Argument(..., help='JSON object of fields to update, e.g. \'{"publish_status": "sold"}\''),
+    fields: str = typer.Argument(..., help='JSON object of fields to update'),
     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:
-    """Update whitelisted sponsorship fields.
+    """Update a sponsorship.
 
-    Editable fields: publish_status (int code or status label, e.g. 'sold',
-    'pending', 'matched'). Non-full-access users may only update sponsorships
-    tied to their own organization.
-
-    Examples:
-        tl sponsorships update 98765 '{"publish_status": "sold"}'
-        tl sponsorships update 98765 '{"publish_status": 3}'
+    Unknown fields are rejected with a 400 listing the offending key.
     """
     fmt = detect_format(json_output, False, False, toon_output)
     try:

thoughtleaders_cli-0.6.12/tests/test_reports.py

@@ -0,0 +1,79 @@
+"""Tests for `tl reports create --config` and `tl reports update`."""
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from tl_cli.commands.reports import _parse_config_arg, app
+
+runner = CliRunner()
+
+
+# ---------------------------------------------------------------------------
+# _parse_config_arg
+# ---------------------------------------------------------------------------
+
+
+class TestParseConfigArg:
+    def test_valid_object_returns_dict(self) -> None:
+        result = _parse_config_arg('{"report_title": "Test", "report_type": 3}')
+        assert result == {"report_title": "Test", "report_type": 3}
+
+    def test_invalid_json_exits(self) -> None:
+        with pytest.raises(typer.Exit) as excinfo:
+            _parse_config_arg('{not json')
+        assert excinfo.value.exit_code == 1
+
+    def test_non_object_exits(self) -> None:
+        # JSON arrays / strings / numbers are valid JSON but not the object the
+        # endpoint accepts.
+        with pytest.raises(typer.Exit) as excinfo:
+            _parse_config_arg('[1, 2, 3]')
+        assert excinfo.value.exit_code == 1
+
+
+# ---------------------------------------------------------------------------
+# tl reports create — argument validation
+# ---------------------------------------------------------------------------
+
+
+class TestCreateArgValidation:
+    def test_no_prompt_and_no_config_rejected(self) -> None:
+        result = runner.invoke(app, ["create"])
+        assert result.exit_code == 1
+        assert "either" in (result.stderr or result.output).lower() and "config" in (result.stderr or result.output).lower()
+
+    def test_both_prompt_and_config_rejected(self) -> None:
+        result = runner.invoke(
+            app,
+            ["create", "gaming channels", "--config", '{"report_title": "x", "report_type": 3}'],
+        )
+        assert result.exit_code == 1
+        assert "either" in (result.stderr or result.output).lower()
+
+    def test_config_invalid_json_rejected(self) -> None:
+        result = runner.invoke(app, ["create", "--config", "{not json", "--yes"])
+        assert result.exit_code == 1
+        assert "valid json" in (result.stderr or result.output).lower()
+
+    def test_config_non_object_rejected(self) -> None:
+        result = runner.invoke(app, ["create", "--config", "[1,2,3]", "--yes"])
+        assert result.exit_code == 1
+        assert "json object" in (result.stderr or result.output).lower()
+
+
+# ---------------------------------------------------------------------------
+# tl reports update — argument validation
+# ---------------------------------------------------------------------------
+
+
+class TestUpdateArgValidation:
+    def test_invalid_json_rejected(self) -> None:
+        result = runner.invoke(app, ["update", "12345", "{not json"])
+        assert result.exit_code == 1
+        assert "json object" in (result.stderr or result.output).lower()
+
+    def test_non_object_rejected(self) -> None:
+        result = runner.invoke(app, ["update", "12345", '"just a string"'])
+        assert result.exit_code == 1
+        assert "json object" in (result.stderr or result.output).lower()