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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.7
+Version: 0.6.9
 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
@@ -21,8 +21,8 @@ Requires-Dist: authlib>=1.3
 Requires-Dist: httpx>=0.27
 Requires-Dist: keyring>=25.0
 Requires-Dist: rich>=13.0
-Requires-Dist: toon-format>=0.9.0b1
-Requires-Dist: typer[all]>=0.12
+Requires-Dist: toon-format==0.9.0b1
+Requires-Dist: typer>=0.16
 Description-Content-Type: text/markdown
 
 # tl cli

{thoughtleaders_cli-0.6.7 → thoughtleaders_cli-0.6.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.6.7"
+version = "0.6.9"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"
@@ -23,12 +23,19 @@ classifiers = [
     "Topic :: Office/Business",
 ]
 dependencies = [
-    "typer[all]>=0.12",
+    # `typer` >= 0.16 made click/rich/shellingham required — the `[all]` extra
+    # was removed and uv warns about it. Drop the extra to silence the warning;
+    # behaviour is identical because the bundled deps are pulled either way.
+    "typer>=0.16",
     "rich>=13.0",
     "httpx>=0.27",
     "keyring>=25.0",
     "authlib>=1.3",
-    "toon-format>=0.9.0b1",
+    # `toon-format` only publishes pre-releases (0.9.0b1 is the only modern
+    # release; 0.1.0 is the lone stable). pip/pipx accept `>=0.9.0b1` and pull
+    # the beta, but uv refuses pre-releases under `>=` when a stable exists.
+    # An exact pin is the one form uv will resolve without `--prerelease=allow`.
+    "toon-format==0.9.0b1",
 ]
 
 [project.scripts]

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

@@ -5,24 +5,17 @@ description: Query and analyze ThoughtLeaders business data using the `tl` CLI.
 
 # ThoughtLeaders Data Analyst
 
-You have access to the `tl` CLI which queries ThoughtLeaders' sponsorship platform data. Run it to answer questions about deals, channels, brands, uploads, metrics, and more.
+Run the `tl` CLI to query ThoughtLeaders' sponsorship platform data. Use it to answer questions about deals, channels, brands, uploads, metrics, etc.
 
 ## Core Principles
 
-**You are the intelligence layer.** Don't use `tl ask` — that's a server-side LLM fallback for users without Claude. Translate the user's question into the right `tl` invocation yourself.
+**Default to raw database queries.** For anything beyond a trivially simple lookup, reach for `tl db pg|fb|es`. Avoid the structured `tl <resource>` commands (`sponsorships list`, `channels show`, `brands history`, etc.).
 
-**Default to raw database queries.** For anything beyond a trivially simple lookup, reach for `tl db pg|fb|es` first. The structured `tl <resource>` commands (`sponsorships list`, `channels show`, `brands history`, etc.) are convenient shorthands for single-record lookups and plain filtered lists — but the moment the question involves joins, aggregations, multi-condition filtering, or anything you'd otherwise post-process client-side, the right tool is a single raw query. One server-side aggregation beats N paginated client-side roll-ups on cost, latency, and the `from+size = 10000` ES cap.
+Always run `tl schema pg|fb|es` before writing a raw query.
 
-Decision rule:
+**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**, to reduce token counts. ES has no per-table form (the index is a single document shape) — `tl schema es` is the only call there.
 
-- **Trivially simple** (use a structured command): "show sponsorship 12345", "list deals for Nike", "show channel 5607", "run report 42".
-- **Anything else** (use `tl db pg|fb|es`): aggregations, joins, conditions the structured filters don't expose, comparing across resources, computing rates / shares / percentiles, anything that would otherwise need a paginated walk + client-side reduce.
-
-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:
+**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`, or `--toon`) into `jq`, `yq`, `rg`, or `duckdb`, as appropriate, and read only the answer back. Pick the tool by shape:
 
 - **`jq`** — filter, project, and transform JSON. The default for `tl … --json` post-processing.
   ```bash
@@ -68,6 +61,13 @@ Other key concepts:
 - **Reports** — saved report configurations that can be re-run
 - **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.
+- **Profiles** — per-organization actors that own sponsorship records on behalf of either side of a deal. A profile is buyer-side or seller-side:
+  - *Buyer-side (brand) profiles* — represent a sponsoring brand. Each brand profile has an M2M link to at most one `Brand` record (which are the actual advertiser identities). On a sponsorship, `creator_profile` is the buyer-side profile.
+  - *Seller-side (publisher) profiles* — attached to a `Publication`, which in turn owns one or more `Channel` records. A channel's adspots therefore inherit ownership through `channel.publication.profile`.
+  - **How to tell them apart** — three signals on the `thoughtleaders_profile` row, used in this order:
+    1. **`persona`** (canonical) — `1=Brand`, `4=Media Agency`, `3=Talent Manager` are buyer-side; `2=Creator`, `5=Creator Service` are seller-side. May be null on legacy rows.
+    2. **`is_advertiser` / `is_publisher`** booleans — feature flags; either or both can be true for staff-style profiles, but on normal user profiles they reliably mark side.
+  - Org scoping for sponsorships is profile-mediated: a sponsorship belongs to your org if **either** `creator_profile.organization` (brand side) **or** `ad_spot.channel.publication.profile.organization` (publisher side) matches yours.
 - **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.
@@ -141,6 +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 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
@@ -152,6 +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 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)
@@ -188,6 +190,30 @@ tl comments add <adlink-id> "msg"      # Add comment (free)
 
 The marginal per-row cost is exactly proportional to `mult` — a 1.4× resource costs 1.4× the row part of a 1.0× resource at any size. Splitting a 500-row pull into ten 50-row calls saves ~30% but burns 10 setup floors instead of 1; "narrow the query" is almost always the better move than "fragment the pagination."
 
+### 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"}'
+tl sponsorships update 98765 '{"publish_status": 3}'
+tl channels update 12345 '{"demographic_male_share": 62}'
+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.
+
 ### Raw queries (`tl db`)
 
 `tl db pg|fb|es` is the default tool. Reach for it whenever the question is anything beyond a trivially simple lookup — and use the structured commands only for those trivial cases (single-record `show`, plain filtered `list`). Don't paginate-and-reduce in your head when one SQL or ES body would do it server-side.
@@ -310,6 +336,8 @@ 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). |