thoughtleaders-cli 0.6.6__tar.gz → 0.6.7__tar.gz

{thoughtleaders_cli-0.6.6 → thoughtleaders_cli-0.6.7}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.6 → thoughtleaders_cli-0.6.7}/PKG-INFO

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

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

{thoughtleaders_cli-0.6.6 → thoughtleaders_cli-0.6.7}/skills/tl/SKILL.md

@@ -20,6 +20,8 @@ Decision rule:
 
 Always run `tl describe show <resource>` before using a structured command, and `tl schema pg|fb|es` before writing a raw query.
 
+**When you only need the schema of one table, you MUST call `tl schema pg <table>` (or `tl schema fb <table>`) — never the unscoped form.** The unscoped `tl schema pg` returns *every* table visible to your role, which is dozens of tables and tens of thousands of tokens; the single-table form returns only the section you need, in the same markdown layout. Reaching for the unscoped form when you already know the table name is a tokens/latency tax with zero benefit. ES has no per-table form (the index is a single document shape) — `tl schema es` is the only call there.
+
 **Process data with shell tools, not your context window.** Don't pull large result sets into your reasoning context just to filter, sort, count, or extract a field — that wastes tokens and slows you down. Pipe `tl … --json` (or `--csv`) into `jq`, `yq`, `rg`, or `duckdb` and read only the answer back. Pick the tool by shape:
 
 - **`jq`** — filter, project, and transform JSON. The default for `tl … --json` post-processing.
@@ -67,6 +69,7 @@ Other key concepts:
 - **Comments** — notes attached to sponsorships
 - **Adspots** — types of ads a channel carries (e.g. mention, dedicated video, product placement). Returned by `tl channels show`; each carries price/cost.
 - **MSN** (Media Selling Network) — the ~11k YouTube channels that have opted in to receive sponsorship offers. A channels is in the MSN group if the `channel.media_selling_network_join_date` field is not null.
+- **MBN** (Media Buying Network) — the brand-side counterpart to MSN: brand profiles that have opted in to receive proposed sponsorships. A profile is in the MBN group if the `profile.media_buying_network_join_date` field is not null.
 - **TPP** (ThoughtLeaders Partner Program, a.k.a. "TL channels") — the smaller, exclusive ~169 channels TL manages directly. A channel is in the TPP group if the `channel.is_tl_channel` is True.
 - **`demographics_updated_at`** (on channel detail) — ISO timestamp of when demographic screenshots were last uploaded and processed via OCR. If non-null, the channel has demographics screenshots on file. If null, no screenshots have been uploaded. Use this to check whether a channel has demographics data from screenshots.
 - **`impression`** (on channels) — projected views per video on that channel. Forward-looking estimate. May be null when not yet computed.
@@ -112,6 +115,7 @@ The CLI exposes three different discovery surfaces — pick by what you actually
 | Arguments and flags for a specific leaf command | `tl <group> <subcommand> --help` (e.g. `tl recommender top-channels --help`) |
 | Fields, filters, credit rates for a **data resource** (sponsorships, uploads, snapshots, reports, comments, recommender) | `tl describe show <resource> --json` |
 | The live PG/ES/Firebolt schema for raw `tl db` queries | `tl schema pg` / `tl schema es` / `tl schema fb` |
+| The schema of a **single** PG / Firebolt table | **`tl schema pg <table>`** / **`tl schema fb <table>`** — strongly preferred when you only need one |
 
 Notes:
 - Use `--help` everywhere — there is no separate `tl help` command. `tl help` returns "No such command 'help'".
@@ -153,6 +157,8 @@ tl channels similar <id-or-name>       # Similarity recommender (25 credits flat
 tl brands show <id-or-name>            # Brand detail (1 credit)
 tl brands history <id-or-name>         # Sponsorship history (5 credits/result, linear)
 tl brands history <query> --channel <id>  # Brand mentions on specific channel
+tl brands history-stats <id-or-name>   # Aggregate roll-up: counts, total/avg/median views, first/last seen, by-year, top channels (5 credits flat)
+tl brands history-stats <q> --channel <id>  # Same roll-up, narrowed to one channel
 tl brands similar <id-or-name>         # Find similar brands via similarity search (25 credits flat)
 tl recommender tags [query]            # List similarity tag names — categories, demographics, formats (free)
 tl recommender top-channels "<tag>"    # Top channels loaded on a similarity tag (25 credits; Intelligence)
@@ -317,8 +323,10 @@ If a user asks for one of the **Unavailable** items, say so explicitly and propo
 ```bash
 tl describe                            # List all resources with credit costs (free)
 tl describe show <resource> --json     # Fields, filters, credit rates (free)
-tl schema pg                           # PostgreSQL schema reference for `tl db pg` (free)
-tl schema fb                           # Live Firebolt tables and column types for `tl db fb` (free)
+tl schema pg                           # PostgreSQL schema reference for `tl db pg` (free) — every visible table
+tl schema pg <table>                   # PostgreSQL schema for a SINGLE table (free) — same markdown shape
+tl schema fb                           # Live Firebolt tables and column types for `tl db fb` (free) — both tables
+tl schema fb <table>                   # Firebolt schema for a SINGLE table (free) — `article_metrics` or `channel_metrics`
 tl schema es                           # Elasticsearch document shape for `tl db es` (free)
 tl balance --json                      # Credit balance (free)
 tl whoami                              # Current user, org, brands (free)

{thoughtleaders_cli-0.6.6 → thoughtleaders_cli-0.6.7}/skills/tl/references/postgres-schema.md

@@ -27,6 +27,8 @@ The main deals table. Each row = one sponsorship deal between a brand and a YouT
 > - ❌ `organization_id` — there is NO direct org FK. Org is reached via `creator_profile_id → profile.organization_id → organization`.
 > - ❌ `channel_id` — channel is reached via `ad_spot_id → adspot.channel_id → channel`.
 > - ❌ `youtube_id` (on channel) — use `external_channel_id`.
+> - ❌ `msn_join_date` (on channel) — use `media_selling_network_join_date`.
+> - ❌ `mbn_join_date` (on profile) — use `media_buying_network_join_date`.
 
 #### Key Columns
 

{thoughtleaders_cli-0.6.6 → thoughtleaders_cli-0.6.7}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.6 → thoughtleaders_cli-0.6.7}/src/tl_cli/commands/brands.py

@@ -118,6 +118,50 @@ def history_cmd(
         client.close()
 
 
+@app.command("history-stats")
+def history_stats_cmd(
+    query: str = typer.Argument(..., help="Brand name or numeric ID"),
+    channel: int | None = typer.Option(None, "--channel", "-c", help="Restrict the roll-up to a specific channel"),
+    top_channels: int = typer.Option(10, "--top-channels", help="How many top-by-count channels to include in the roll-up (1-50)"),
+    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)"),
+) -> None:
+    """Aggregate roll-up of a brand's sponsorship history (no per-row output).
+
+    Same scope as `tl brands history` (videos where the brand is in
+    `sponsored_brand_mentions`), but returned as a single summary
+    record: total sponsored videos, view sums/avg/median, first/last
+    seen dates, per-year buckets, top channels by count, and
+    TL-brokered adlink counts. Computed via one ES aggregation +
+    one PG count — cost is flat regardless of how prolific the
+    brand is.
+
+    Requires an Intelligence plan. Costs 5 credits flat.
+
+    Examples:
+        tl brands history-stats Nike
+        tl brands history-stats 21416 --top-channels 25
+        tl brands history-stats Nike --channel 12345 --json
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+
+    params: dict[str, str] = {"top-channels": str(top_channels)}
+    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-stats", params=params)
+        output_single(data, fmt)
+    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"},

thoughtleaders_cli-0.6.7/src/tl_cli/commands/schema.py

@@ -0,0 +1,83 @@
+"""tl schema — Show raw-db schema documentation for `tl db pg|fb|es`."""
+
+import json
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+
+app = typer.Typer(help="Show schema documentation for raw db queries (`tl db pg|fb|es`)")
+console = Console()
+
+
+def _show(db: str, json_output: bool, table: str | None = None) -> None:
+    client = get_client()
+    try:
+        params = {"table": table} if table else {}
+        data = client.get(f"/raw/{db}/schema", params=params)
+        if json_output:
+            print(json.dumps(data, indent=2, default=str))
+            return
+        content = data.get("content", "")
+        if console.is_terminal:
+            console.print(Markdown(content))
+        else:
+            print(content)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("pg")
+def pg_cmd(
+    table: str = typer.Argument(None, help="Optional table name. When given, prints only that table's section in the same markdown format."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Show PostgreSQL schema reference (for `tl db pg`).
+
+    With no argument: lists every table visible to your role.
+    With a table name: prints only that table's column listing.
+
+    **Strongly preferred for single-table lookups.** Listing every
+    table just to read one is wasteful — pass the table name and the
+    server returns only that section.
+
+    Examples:
+        tl schema pg
+        tl schema pg thoughtleaders_channel
+        tl schema pg thoughtleaders_adlink --json
+    """
+    _show("pg", json_output, table=table)
+
+
+@app.command("fb")
+def fb_cmd(
+    table: str = typer.Argument(None, help="Optional table name (`article_metrics` or `channel_metrics`). When given, prints only that table's section."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Show Firebolt schema (live: tables and column types) for `tl db fb`.
+
+    With no argument: lists both accepted tables.
+    With a table name: prints only that table's columns + primary index.
+
+    **Strongly preferred for single-table lookups.** Pass the table
+    name to skip the other one.
+
+    Examples:
+        tl schema fb
+        tl schema fb article_metrics
+        tl schema fb channel_metrics --json
+    """
+    _show("fb", json_output, table=table)
+
+
+@app.command("es")
+def es_cmd(
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Show Elasticsearch document shape for `tl db es`."""
+    _show("es", json_output)

{thoughtleaders_cli-0.6.6 → thoughtleaders_cli-0.6.7}/uv.lock

@@ -388,7 +388,7 @@ wheels = [
 
 [[package]]
 name = "thoughtleaders-cli"
-version = "0.6.6"
+version = "0.6.7"
 source = { editable = "." }
 dependencies = [
     { name = "authlib" },

thoughtleaders_cli-0.6.6/src/tl_cli/commands/schema.py

@@ -1,55 +0,0 @@
-"""tl schema — Show raw-db schema documentation for `tl db pg|fb|es`."""
-
-import json
-
-import typer
-from rich.console import Console
-from rich.markdown import Markdown
-
-from tl_cli.client.errors import ApiError, handle_api_error
-from tl_cli.client.http import get_client
-
-app = typer.Typer(help="Show schema documentation for raw db queries (`tl db pg|fb|es`)")
-console = Console()
-
-
-def _show(db: str, json_output: bool) -> None:
-    client = get_client()
-    try:
-        data = client.get(f"/raw/{db}/schema")
-        if json_output:
-            print(json.dumps(data, indent=2, default=str))
-            return
-        content = data.get("content", "")
-        if console.is_terminal:
-            console.print(Markdown(content))
-        else:
-            print(content)
-    except ApiError as e:
-        handle_api_error(e)
-    finally:
-        client.close()
-
-
-@app.command("pg")
-def pg_cmd(
-    json_output: bool = typer.Option(False, "--json", help="JSON output"),
-) -> None:
-    """Show PostgreSQL schema reference (for `tl db pg`)."""
-    _show("pg", json_output)
-
-
-@app.command("fb")
-def fb_cmd(
-    json_output: bool = typer.Option(False, "--json", help="JSON output"),
-) -> None:
-    """Show Firebolt schema (live: tables and column types) for `tl db fb`."""
-    _show("fb", json_output)
-
-
-@app.command("es")
-def es_cmd(
-    json_output: bool = typer.Option(False, "--json", help="JSON output"),
-) -> None:
-    """Show Elasticsearch document shape for `tl db es`."""
-    _show("es", json_output)