thoughtleaders-cli 0.7.1__tar.gz → 0.7.2__tar.gz

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/AGENTS.md

@@ -53,7 +53,7 @@ This repo is also a Claude Code plugin, and can directly be installed as one.
 
 - **`tl`** — the main skill for querying ThoughtLeaders data. Default for any sponsorship / channel / brand / upload / report question.
 - **`tl-keyword-research`** — invoke whenever the user wants to find videos or channels by **content keywords** (topics, concepts, niches) that aren't covered by a curated recommender tag, OR to validate that a candidate channel's content actually touches a given topic. Returns `{operator, keywords:[{keyword,count}]}` from a ranked ES probe over `title` / `summary` / `transcript`; the caller then runs the actual content search with the surviving high-count terms. **Do not compose keyword sets by hand for `tl db es` content searches — delegate to this skill first.** See `skills/tl/SKILL.md` → *Channel & video discovery* for the four-path decision tree and when to use this vs the recommender / raw SQL.
-- **`tl-import`**, **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`** — narrower workflows; the skill files document their own triggers.
+- **`tl-import`**, **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`**, **`tl-top-partnerships`** — narrower workflows; the skill files document their own triggers. `tl-top-partnerships` is brand-user-facing: ranks a brand's sold sponsorships by live eCPM vs the sold-date projection and delivers a two-tab Google Sheet via `gws`.
 
 ### Skill content boundaries
 

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.7.1
+Version: 0.7.2
 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
@@ -68,7 +68,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [duckdb](https://duckdb.org/)
 - [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
-For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
+For automated installs on MacOS, prefer installing Python and the requirements on Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv`.
 
 ## Install
 
@@ -280,6 +280,7 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
+- **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
 ## Output Formats
 

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/README.md

@@ -40,7 +40,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [duckdb](https://duckdb.org/)
 - [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
-For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
+For automated installs on MacOS, prefer installing Python and the requirements on Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv`.
 
 ## Install
 
@@ -252,6 +252,7 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
+- **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
 ## Output Formats
 

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/pyproject.toml

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

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/skills/tl/SKILL.md

@@ -434,6 +434,8 @@ If unsure about what information to find where, read the [references/postgresql-
 
 If a user asks for one of the **Unavailable** items, say so explicitly and propose the closest `tl`-based approximation rather than silently degrading.
 
+If the user requests a chart, create it as a SVG graphic.
+
 ### Discovery & system
 ```bash
 tl describe                            # List all resources with credit costs (free)

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/skills/tl-keyword-research/SKILL.md

@@ -164,3 +164,4 @@ Each probe is `size:0` + `track_total_hits:true` with no aggregations — no row
 5. `keywords` array is sorted descending by `count`.
 6. Each entry has exactly `keyword` (string) and `count` (integer).
 7. The seed keyword(s) appear in the output.
+8. If the user requests a chart, create it as a SVG graphic

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/skills/tl-save-report/SKILL.md

@@ -503,6 +503,8 @@ Echo the saved URL + ID, plus a follow-up offer for refinement:
 
 The follow-up offer matters because **FilterSet changes (keywords, demographics, M2M lists) can't be patched in place** via `tl reports update` — they require saving a new variant. Surface that limitation only if the user actually asks to change FilterSet fields.
 
+If the user requests a chart, create it as a SVG graphic.
+
 ### On failure
 
 If the command exits non-zero, the CLI prints the error on stderr (shape: `Error (NNN): <detail>` for most codes; specific lines for 401/402/403). **Surface the error verbatim** — do NOT silently report success.

thoughtleaders_cli-0.7.2/skills/tl-top-partnerships/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: tl-top-partnerships
+description: External brand-user performance report. Ranks a brand's sponsorships by effective CPM once the sponsored videos went live, and compares live eCPM against the sold-date projection. Use whenever a brand user asks "which of my sponsorships performed best", "top partnerships this year", "best ROI deals", "effective CPM on my deals", "which sponsorships overperformed", "/top-partnerships", or any variation of "show me my best-performing sponsorships". This is the brand-side equivalent of internal performance reporting — fire it eagerly any time a brand wants to look back at their booked deals through a performance lens, even if they don't say the words "CPM" or "eCPM".
+---
+
+# Top Partnerships (Brand-side)
+
+Helps a brand look back at their sold sponsorships and see which ones delivered the lowest effective CPM (eCPM) once the videos went live, vs the projection at sale.
+
+## Triggers
+
+- `/top-partnerships` — defaults to calendar YTD
+- `/top-partnerships <range>` — e.g. `/top-partnerships 2025`, `/top-partnerships "last 12 months"`, `/top-partnerships "Q1 2026"`
+- Natural language: "top partnerships this year", "best sponsorships", "which deals performed best", "effective CPM on my deals", "show me my best ROI sponsorships"
+
+## What this skill computes
+
+For every sold sponsorship the brand has where the video has actually gone live (has a `publish_date` and a non-null live `views` count):
+
+- **Sold-date eCPM** = `price / projected_views_at_purchase_date * 1000`
+  - The projection captured on the adlink at the moment the deal was sold. This is the eCPM the brand "agreed to."
+- **Live eCPM** = `price / views * 1000`
+  - The actual eCPM now that the video has accumulated views.
+- **View ratio** = `views / projected_views_at_purchase_date`
+  - >1 means the video out-delivered its projection.
+- **Delta** = `live_eCPM - sold_date_eCPM`
+  - Negative delta = the deal got *cheaper* per view than promised (good for the brand). Positive delta = the deal underdelivered.
+
+It also pulls **future bookings** — any sponsorship with status sold / proposal_approved / pending and a send date strictly after today — and tags each deal and each channel with the earliest future send date, or "Re-book - no future spot" if none exists. This turns the report into an actionable list, not just a backward look.
+
+## Output
+
+A Google Sheet with two tabs, owned by the caller's Google account:
+
+- **By Deal** — one row per sponsorship, ranked by live eCPM (best first). Columns: rank, channel, title, video_url, send_date, publish_date, price, promised_views, live_views, view_ratio, sold_date_ecpm, live_ecpm, delta_ecpm, measurable, next_booking.
+- **By Channel** — one row per channel, aggregated across all that channel's deals in range. Combined live eCPM is `sum(price) / sum(live_views) * 1000` (volume-weighted, not an average of CPMs). Sorted by combined live eCPM. Columns: channel, deals, measurable_deals, total_price_usd, total_promised_views, total_live_views, view_ratio, sold_date_ecpm, live_ecpm, delta_ecpm, next_booking.
+
+In chat: a short summary + top-10 channels table + the sheet URL.
+
+## Workflow
+
+### Step 1 — Resolve the brand
+
+Run `tl whoami --json` and read the `brands` array.
+
+- One brand → use it silently.
+- Zero brands → tell the user this skill is for brand-user profiles and stop.
+- Multiple brands → ask which one. Don't guess.
+
+### Step 2 — Resolve the time range
+
+Default = calendar YTD (Jan 1 of the current year through today).
+
+Accept these forms in the user's input:
+
+- `2025` or `"2024"` → that full calendar year
+- `"last 12 months"` → trailing 12 months ending today
+- `"Q1 2026"`, `"Q4 2025"` → that quarter
+- `"YTD"` → explicit current YTD
+- Anything else → ask the user to clarify, don't silently pick
+
+Convert to a `send-date-start` / `send-date-end` pair (YYYY-MM-DD strings). Use `send_date` as the time anchor because that is when the sponsorship actually ran for the brand — purchase_date can be months earlier.
+
+### Step 3 — Run the script
+
+```bash
+python3 <SKILL_DIR>/scripts/top_partnerships.py \
+  --brand "<BRAND_NAME>" \
+  --send-date-start <YYYY-MM-DD> \
+  --send-date-end <YYYY-MM-DD>
+```
+
+`<SKILL_DIR>` resolves to this skill's directory at invocation time (same convention as `tl-views-guarantee`, `tl-keyword-research`).
+
+The script does everything: pulls sold deals in range (paginated), pulls all future bookings, computes per-deal and per-channel metrics, creates a Google Sheet with two tabs, shares it back to the caller, and prints a markdown summary plus the sheet URL.
+
+It uses `tl` for data and `gws` for sheet creation. Both must be on PATH and authed.
+
+### Step 4 — Present the result
+
+Take the script's stdout as-is. It already contains:
+
+1. **Summary line** — total sold deals, measurable count, median live eCPM, count overperforming.
+2. **Top 10 channels by combined live eCPM** — markdown table with the Next booking column bolded when it says "Re-book."
+3. **Sheet URL** — point the user at the two tabs.
+
+If more than half the top-10 channels show "Re-book", call that out in one sentence as the headline action item. If most of the top channels already have follow-ups booked, congratulate briefly and stop.
+
+Keep the writeup tight. No em dashes, no "just wanted to", no hedging. The data does the talking.
+
+## Brand-user mode notes
+
+- This skill assumes a brand-user `tl` auth. It uses only public CLI commands (`tl whoami`, `tl sponsorships list`) — no `tl db pg` and no Elasticsearch.
+- The `tl sponsorships list` endpoint already filters to deals the calling profile is allowed to see, so passing `brand:"<name>"` is a belt-and-braces filter rather than a privacy boundary.
+- View counts come from TL's own tracking on the `views` field returned by the CLI. They're the same numbers the brand sees in the TL dashboard, so the eCPMs are reconcilable with what they see in-app.
+- Don't include creators' contact emails, internal notes, or owner_* fields in the brand-facing output. The script already drops them from the CSV.
+
+## Edge cases worth mentioning to the user (only if they apply)
+
+- A deal that ran very recently (last 14-28 days) may show a misleadingly high Live eCPM because views are still accumulating. Mention this only if more than half the top-10 deals have a send date inside the last 28 days.
+- If the brand has zero measurable deals in the range, say so plainly and suggest broadening the range (e.g., last 12 months).

thoughtleaders_cli-0.7.2/skills/tl-top-partnerships/scripts/top_partnerships.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""
+Pull a brand's sold sponsorships in a date range, compute live vs sold-date eCPM,
+also pull future bookings, build per-deal and per-channel views, upload a
+two-tab Google Sheet, and print a top-10 markdown summary.
+"""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from datetime import date, timedelta
+from pathlib import Path
+
+
+def slugify(s: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-") or "brand"
+
+
+def to_float(x):
+    if x is None or x == "":
+        return None
+    try:
+        return float(x)
+    except (TypeError, ValueError):
+        return None
+
+
+def to_int(x):
+    f = to_float(x)
+    return int(f) if f is not None else None
+
+
+def youtube_url(article_id):
+    if not article_id or ":" not in article_id:
+        return ""
+    vid = article_id.split(":", 1)[1]
+    return f"https://www.youtube.com/watch?v={vid}"
+
+
+def fmt_money(x):
+    return f"${x:,.0f}" if x is not None else "n/a"
+
+
+def fmt_int(x):
+    return f"{x:,}" if x is not None else "n/a"
+
+
+def fmt_ratio(x):
+    return f"{x:.2f}x" if x is not None else "n/a"
+
+
+def fmt_cpm(x):
+    return f"${x:,.2f}" if x is not None else "n/a"
+
+
+def tl_list(*args) -> list[dict]:
+    rows: list[dict] = []
+    limit = 200
+    offset = 0
+    while True:
+        out = subprocess.run(
+            ["tl", "sponsorships", "list", *args,
+             "--limit", str(limit), "--offset", str(offset), "--json"],
+            capture_output=True, text=True, check=True,
+        ).stdout
+        data = json.loads(out)
+        page = data.get("results", data) if isinstance(data, dict) else data
+        if not page:
+            break
+        rows.extend(page)
+        if len(page) < limit:
+            break
+        offset += limit
+    return rows
+
+
+def fetch_future_bookings(brand: str) -> dict[str, dict]:
+    """Return channel -> {send_date, status} for the earliest future booking per channel.
+    Future = send_date strictly after today, status in {sold, proposal_approved, pending}.
+    """
+    today = date.today()
+    cutoff = (today + timedelta(days=1)).isoformat()
+    end = (today + timedelta(days=365 * 2)).isoformat()
+    rows: list[dict] = []
+    for status in ("sold", "proposal_approved", "pending"):
+        rows.extend(tl_list(
+            f"brand:{brand}",
+            f"status:{status}",
+            f"send-date-start:{cutoff}",
+            f"send-date-end:{end}",
+        ))
+    by_channel: dict[str, dict] = {}
+    for r in rows:
+        ch = r.get("channel")
+        sd = r.get("send_date")
+        st = r.get("status")
+        if not ch or not sd:
+            continue
+        if ch not in by_channel or sd < by_channel[ch]["send_date"]:
+            by_channel[ch] = {"send_date": sd, "status": st}
+    return by_channel
+
+
+def build_deal_rows(raw: list[dict], future: dict[str, dict]) -> list[dict]:
+    out = []
+    for r in raw:
+        price = to_float(r.get("price"))
+        promised = to_int(r.get("projected_views_at_purchase_date"))
+        views = to_int(r.get("views"))
+        publish_date = r.get("publish_date")
+        live_cpm = (price / views * 1000) if (price and views) else None
+        sold_cpm = (price / promised * 1000) if (price and promised) else None
+        ratio = (views / promised) if (views and promised) else None
+        delta = (live_cpm - sold_cpm) if (live_cpm is not None and sold_cpm is not None) else None
+        measurable = bool(publish_date and views)
+        ch = r.get("channel")
+        f = future.get(ch)
+        next_booking = f"{f['send_date']} ({f['status']})" if f else "Re-book - no future spot"
+        out.append({
+            "channel": ch,
+            "title": (r.get("title") or "").strip(),
+            "video_url": youtube_url(r.get("article_id")),
+            "send_date": r.get("send_date"),
+            "publish_date": publish_date,
+            "price": price,
+            "price_currency": r.get("price_currency", "USD"),
+            "promised_views": promised,
+            "live_views": views,
+            "view_ratio": ratio,
+            "sold_date_ecpm": sold_cpm,
+            "live_ecpm": live_cpm,
+            "delta_ecpm": delta,
+            "measurable": measurable,
+            "next_booking": next_booking,
+        })
+    return out
+
+
+def build_channel_rows(deals: list[dict], future: dict[str, dict]) -> list[dict]:
+    agg: dict[str, dict] = {}
+    for d in deals:
+        ch = d["channel"] or "(unknown)"
+        a = agg.setdefault(ch, {"deals": 0, "measurable": 0, "price": 0.0, "promised": 0.0, "live": 0.0})
+        a["deals"] += 1
+        a["price"] += d["price"] or 0
+        if d["promised_views"]:
+            a["promised"] += d["promised_views"]
+        if d["live_views"]:
+            a["live"] += d["live_views"]
+            a["measurable"] += 1
+    out = []
+    for ch, a in agg.items():
+        live_cpm = (a["price"] / a["live"] * 1000) if (a["live"] and a["price"]) else None
+        sold_cpm = (a["price"] / a["promised"] * 1000) if (a["promised"] and a["price"]) else None
+        ratio = (a["live"] / a["promised"]) if a["promised"] and a["live"] else None
+        delta = (live_cpm - sold_cpm) if (live_cpm is not None and sold_cpm is not None) else None
+        f = future.get(ch)
+        next_booking = f"{f['send_date']} ({f['status']})" if f else "Re-book - no future spot"
+        out.append({
+            "channel": ch,
+            "deals": a["deals"],
+            "measurable_deals": a["measurable"],
+            "total_price": a["price"],
+            "total_promised": int(a["promised"]),
+            "total_live": int(a["live"]),
+            "view_ratio": ratio,
+            "sold_date_ecpm": sold_cpm,
+            "live_ecpm": live_cpm,
+            "delta_ecpm": delta,
+            "next_booking": next_booking,
+        })
+    out.sort(key=lambda r: (r["live_ecpm"] is None, r["live_ecpm"] if r["live_ecpm"] is not None else 0))
+    return out
+
+
+def whoami_email() -> str | None:
+    try:
+        out = subprocess.run(["tl", "whoami", "--json"], capture_output=True, text=True, check=True).stdout
+        return json.loads(out).get("user", {}).get("email")
+    except Exception:
+        return None
+
+
+def gws(cmd: list[str], params: dict | None = None, body: dict | None = None) -> dict:
+    args = ["gws", *cmd]
+    if params is not None:
+        args += ["--params", json.dumps(params)]
+    if body is not None:
+        args += ["--json", json.dumps(body)]
+    r = subprocess.run(args, capture_output=True, text=True, check=True)
+    # gws may print non-JSON preamble like "Using keyring backend: keyring" — find the JSON block
+    out = r.stdout
+    start = out.find("{")
+    return json.loads(out[start:]) if start >= 0 else {}
+
+
+def upload_sheet(brand: str, deals: list[dict], channels: list[dict], rankable: list[dict]) -> str:
+    title = f"{brand} Top Partnerships ({deals[0]['send_date'][:4] if deals else 'no-data'})"
+
+    # 1) Create empty spreadsheet via Sheets API
+    sheet = gws(["sheets", "spreadsheets", "create"], body={
+        "properties": {"title": title},
+        "sheets": [
+            {"properties": {"title": "By Deal"}},
+            {"properties": {"title": "By Channel"}},
+        ],
+    })
+    sid = sheet["spreadsheetId"]
+
+    # 2) Write By Deal
+    deal_header = ["rank", "channel", "title", "video_url", "send_date", "publish_date",
+                   "price", "promised_views", "live_views", "view_ratio",
+                   "sold_date_ecpm", "live_ecpm", "delta_ecpm", "measurable", "next_booking"]
+    rank_ids = {id(d): i + 1 for i, d in enumerate(rankable)}
+    # Order: ranked first (best live_ecpm), then unranked-measurable, then unmeasurable
+    ranked_set = {id(d) for d in rankable}
+    measurable_unranked = [d for d in deals if d["measurable"] and id(d) not in ranked_set]
+    unmeasurable = [d for d in deals if not d["measurable"]]
+    ordered = rankable + measurable_unranked + unmeasurable
+
+    deal_values = [deal_header]
+    for d in ordered:
+        deal_values.append([
+            rank_ids.get(id(d), ""),
+            d["channel"] or "", d["title"], d["video_url"], d["send_date"] or "",
+            (d["publish_date"] or "")[:10], d["price"] or "",
+            d["promised_views"] or "", d["live_views"] or "",
+            round(d["view_ratio"], 4) if d["view_ratio"] is not None else "",
+            round(d["sold_date_ecpm"], 4) if d["sold_date_ecpm"] is not None else "",
+            round(d["live_ecpm"], 4) if d["live_ecpm"] is not None else "",
+            round(d["delta_ecpm"], 4) if d["delta_ecpm"] is not None else "",
+            "TRUE" if d["measurable"] else "FALSE",
+            d["next_booking"],
+        ])
+    gws(["sheets", "spreadsheets", "values", "update"],
+        params={"spreadsheetId": sid, "range": f"'By Deal'!A1:O{len(deal_values)}",
+                "valueInputOption": "RAW"},
+        body={"values": deal_values})
+
+    # 3) Write By Channel
+    ch_header = ["channel", "deals", "measurable_deals", "total_price_usd",
+                 "total_promised_views", "total_live_views", "view_ratio",
+                 "sold_date_ecpm", "live_ecpm", "delta_ecpm", "next_booking"]
+    ch_values = [ch_header]
+    for c in channels:
+        ch_values.append([
+            c["channel"], c["deals"], c["measurable_deals"],
+            round(c["total_price"], 2), c["total_promised"], c["total_live"],
+            round(c["view_ratio"], 4) if c["view_ratio"] is not None else "",
+            round(c["sold_date_ecpm"], 4) if c["sold_date_ecpm"] is not None else "",
+            round(c["live_ecpm"], 4) if c["live_ecpm"] is not None else "",
+            round(c["delta_ecpm"], 4) if c["delta_ecpm"] is not None else "",
+            c["next_booking"],
+        ])
+    gws(["sheets", "spreadsheets", "values", "update"],
+        params={"spreadsheetId": sid, "range": f"'By Channel'!A1:K{len(ch_values)}",
+                "valueInputOption": "RAW"},
+        body={"values": ch_values})
+
+    # 4) Share with the caller (writer, no email)
+    email = whoami_email()
+    if email:
+        try:
+            gws(["drive", "permissions", "create"],
+                params={"fileId": sid, "sendNotificationEmail": False},
+                body={"role": "writer", "type": "user", "emailAddress": email})
+        except Exception:
+            pass
+
+    return f"https://docs.google.com/spreadsheets/d/{sid}/edit"
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--brand", required=True)
+    ap.add_argument("--send-date-start", required=True)
+    ap.add_argument("--send-date-end", required=True)
+    ap.add_argument("--top", type=int, default=10)
+    args = ap.parse_args()
+
+    raw = tl_list(
+        "status:sold", f"brand:{args.brand}",
+        f"send-date-start:{args.send_date_start}", f"send-date-end:{args.send_date_end}",
+    )
+    future = fetch_future_bookings(args.brand)
+    deals = build_deal_rows(raw, future)
+    channels = build_channel_rows(deals, future)
+
+    rankable = [d for d in deals if d["measurable"] and d["live_ecpm"] is not None and d["sold_date_ecpm"] is not None]
+    rankable.sort(key=lambda d: d["live_ecpm"])
+
+    measurable_count = sum(1 for d in deals if d["measurable"] and d["live_ecpm"] is not None)
+    unmeasurable_count = sum(1 for d in deals if not d["measurable"])
+
+    print("## Summary\n")
+    print(f"- Sold sponsorships in range: **{len(deals)}**")
+    print(f"- Measurable (video live with views): **{measurable_count}**")
+    if rankable:
+        median = sorted(d["live_ecpm"] for d in rankable)[len(rankable) // 2]
+        overperformed = sum(1 for d in rankable if d["delta_ecpm"] is not None and d["delta_ecpm"] < 0)
+        print(f"- Median live eCPM: **{fmt_cpm(median)}**")
+        print(f"- Deals that overperformed: **{overperformed} / {len(rankable)}**")
+    print()
+
+    if channels:
+        ranked_channels = [c for c in channels if c["live_ecpm"] is not None]
+        print(f"## Top {min(args.top, len(ranked_channels))} channels by combined live eCPM\n")
+        print("| # | Channel | Deals | Total spend | Total live views | View ratio | Live eCPM | Delta | Next booking |")
+        print("|---|---------|-------|-------------|------------------|------------|-----------|-------|--------------|")
+        for i, c in enumerate(ranked_channels[: args.top], 1):
+            next_cell = c["next_booking"]
+            if next_cell.startswith("Re-book"):
+                next_cell = f"**{next_cell}**"
+            print(
+                f"| {i} | {c['channel']} | {c['deals']} | {fmt_money(c['total_price'])} | "
+                f"{fmt_int(c['total_live'])} | {fmt_ratio(c['view_ratio'])} | "
+                f"{fmt_cpm(c['live_ecpm'])} | {fmt_cpm(c['delta_ecpm'])} | {next_cell} |"
+            )
+        print()
+
+    if unmeasurable_count:
+        print(f"_{unmeasurable_count} deals in range are not yet measurable (video not live or no view data yet). They appear in the sheet but not in the ranking._\n")
+
+    if deals:
+        url = upload_sheet(args.brand, deals, channels, rankable)
+        print(f"**Google Sheet:** {url}")
+        print("Two tabs — *By Deal* (one row per sponsorship) and *By Channel* (aggregated, one row per channel).")
+    else:
+        print("_No deals found in this range._")
+
+
+if __name__ == "__main__":
+    main()

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/src/tl_cli/__init__.py

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

thoughtleaders_cli-0.7.2/src/tl_cli/_typer_utils.py

@@ -0,0 +1,23 @@
+"""Shared Typer customizations for the tl CLI.
+
+The single export here, ``AlphaSortedTyperGroup``, makes ``--help`` render
+its subcommands alphabetically instead of in registration order. It is
+applied via ``cls=AlphaSortedTyperGroup`` on every ``typer.Typer(...)``
+instantiation in the project so the behavior is consistent at every help
+level (``tl --help``, ``tl brands --help``, ``tl db --help``, etc.).
+"""
+
+import typer
+from typer.core import TyperGroup
+
+
+class AlphaSortedTyperGroup(TyperGroup):
+    """Render subcommands in alphabetical order on ``--help``.
+
+    Typer / Click default ``list_commands`` to insertion order; users
+    looking at long help listings want them sorted so the command they
+    are after is easy to find.
+    """
+
+    def list_commands(self, ctx: typer.Context) -> list[str]:
+        return sorted(super().list_commands(ctx))

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/src/tl_cli/auth/commands.py

@@ -4,6 +4,7 @@ import sys
 import time
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 from rich.prompt import Prompt
 
@@ -11,7 +12,7 @@ from tl_cli.auth.finalize import finalize_signup
 from tl_cli.auth.login import login_browser, login_device_code
 from tl_cli.auth.token_store import KIND_API_KEY, StoredTokens, clear_tokens, load_tokens, save_tokens
 
-app = typer.Typer(help="Authentication commands")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Authentication commands")
 console = Console(stderr=True)
 
 

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/src/tl_cli/commands/balance.py

@@ -3,6 +3,7 @@
 import json
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 from rich.table import Table
 
@@ -10,7 +11,7 @@ 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)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Credit balance and usage (free)")
 console = Console()
 
 

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/src/tl_cli/commands/brands.py

@@ -9,6 +9,7 @@ import json as _json
 import urllib.parse
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 from rich.console import Console
 
@@ -18,7 +19,7 @@ from tl_cli.commands._comments_common import register_comment_commands
 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, find, similar)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Brand intelligence (detail, find, similar)")
 register_comment_commands(app, "brand", "brand")
 
 

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/src/tl_cli/commands/channels.py

@@ -4,6 +4,7 @@ import json as _json
 import urllib.parse
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 
 from tl_cli.client.errors import ApiError, handle_api_error
@@ -13,7 +14,7 @@ from tl_cli.filters import parse_filters
 from tl_cli.hints import detail_hint
 from tl_cli.output.formatter import detect_format, output, output_single
 
-app = typer.Typer(help="YouTube channels (detail and similar-channel recommendations)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="YouTube channels (detail and similar-channel recommendations)")
 register_comment_commands(app, "channel", "channel")
 
 _HISTORY_DEPRECATION = (

{thoughtleaders_cli-0.7.1 → thoughtleaders_cli-0.7.2}/src/tl_cli/commands/credits.py

@@ -18,6 +18,7 @@ import webbrowser
 from decimal import Decimal, InvalidOperation
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.prompt import Prompt
@@ -27,7 +28,7 @@ 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="Buy credits and view top-up history (free)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Buy credits and view top-up history (free)")
 console = Console()
 err = Console(stderr=True)