@damiangilgonzalez/harness 1.3.7

package/skills/testing-web/scripts/verify.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — testing-web skill gate. Lints frontend test files for the load-bearing rules.
+#
+# Usage:  scripts/verify.sh [PATH]      (PATH = a test file or a directory; default: current dir)
+#
+# Read-only. Never executes the tests, never edits anything. It checks artifact SHAPE, not whether the
+# assertions are true.
+#
+# Discovers test files matching *.test.* / *.spec.* (.ts/.tsx/.js/.jsx), skipping node_modules/.git/dist.
+# Per file:
+#   HARD fail (exit 1):
+#     - zero `expect(`                                  -> a test that asserts nothing
+#     - a userEvent/`user.<verb>(` interaction not preceded by `await` on the same line
+#   WARN (advisory, never changes exit code):
+#     - getByTestId used while no getByRole/getByLabelText/getByText query is present
+#     - raw fireEvent( where userEvent would do
+#     - act( inside a component (non-hook) test file
+#     - setTimeout(-based waiting instead of waitFor/findBy
+#
+# An empty or clean target exits 0 (no false failure). Stock macOS bash 3.2 compatible.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+TARGET="${1:-.}"
+if [ ! -e "$TARGET" ]; then
+  err "path not found: $TARGET"
+  exit 1
+fi
+
+FILES=()
+if [ -f "$TARGET" ]; then
+  FILES+=("$TARGET")
+else
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(
+    find "$TARGET" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' -o -path '*/build/*' -o -path '*/coverage/*' \) -prune -o \
+      -type f \( -name '*.test.ts' -o -name '*.test.tsx' -o -name '*.test.js' -o -name '*.test.jsx' \
+                 -o -name '*.spec.ts' -o -name '*.spec.tsx' -o -name '*.spec.js' -o -name '*.spec.jsx' \) -print0 2>/dev/null
+  )
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  warn "no *.test.* / *.spec.* files found under $TARGET — nothing to lint"
+  ok "verify.sh passed (empty target)"
+  exit 0
+fi
+
+for f in "${FILES[@]}"; do
+  problems=0
+
+  # --- HARD: must contain at least one assertion ---
+  if ! grep -Eq 'expect[[:space:]]*\(' "$f"; then
+    err "$f: no expect(...) — a test must assert something observable"
+    problems=$((problems + 1))
+  fi
+
+  # --- HARD: every userEvent/user.<verb>( interaction must be awaited on its line ---
+  # Match interaction calls (user.click(, userEvent.type(, etc.) whose line lacks `await`.
+  unawaited="$(grep -nE '(^|[^a-zA-Z0-9_.])(user|userEvent)\.[a-zA-Z]+[[:space:]]*\(' "$f" 2>/dev/null \
+                | grep -vE '\bawait\b' \
+                | grep -vE '\.setup[[:space:]]*\(' || true)"
+  if [ -n "$unawaited" ]; then
+    err "$f: user-event interaction not awaited (await user.click/type/...):"
+    printf '%s\n' "$unawaited" | sed 's/^/      /'
+    problems=$((problems + 1))
+  fi
+
+  # --- WARN: testid as the only query (no role/label/text query present) ---
+  if grep -Eq 'getByTestId|findByTestId|queryByTestId' "$f"; then
+    if ! grep -Eq 'ByRole|ByLabelText|ByText|ByPlaceholderText|ByDisplayValue' "$f"; then
+      warn "$f: uses *ByTestId with no role/label/text query — climb the query ladder first"
+    fi
+  fi
+
+  # --- WARN: raw fireEvent ---
+  if grep -Eq '\bfireEvent\.' "$f"; then
+    warn "$f: uses fireEvent — prefer userEvent.setup() + await user.* for realistic events"
+  fi
+
+  # --- WARN: act( in a component (non-hook) test file ---
+  if grep -Eq '(^|[^a-zA-Z0-9_])act[[:space:]]*\(' "$f"; then
+    if ! grep -Eq 'renderHook' "$f"; then
+      warn "$f: bare act() in a component test — await findBy/waitFor instead"
+    fi
+  fi
+
+  # --- WARN: setTimeout-based waiting ---
+  if grep -Eq '\bsetTimeout[[:space:]]*\(' "$f" && ! grep -Eq 'waitFor|findBy' "$f"; then
+    warn "$f: waits with setTimeout and no waitFor/findBy — use waitFor/findBy to retry until ready"
+  fi
+
+  if [ "$problems" -eq 0 ]; then
+    ok "$f"
+  fi
+done
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then
+  ok "verify.sh passed"
+else
+  err "verify.sh found hard violations"
+fi
+exit "$EXIT"

package/skills/tiktok-api/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: tiktok-api
+description: "Use when connecting a real TikTok account to code via the Content Posting, Display and Business Account APIs — OAuth, chunked video publish with status polling, and pulling views, watch time and impression sources, then logging that performance into the wiki as a dated feedback record. Covers short-lived tokens breaking a cron, unverified pull-from-URL ownership, and rate limits. NOT what to post or how to package it (that is `shortform-strategy` and `shortform-packaging`)."
+tags: [tiktok, content-posting-api, tiktok-display-api, tiktok-business-api, oauth2, chunked-upload, video-publish, watch-time, completion-rate, shortform-feedback-log]
+recommends: [shortform-strategy, shortform-packaging, shortform-ideation, shortform-editing, social-publisher, instagram-api, youtube-api, api-connector-builder, automation-flows, knowledge-ops]
+origin: risco
+---
+
+# TikTok API — Transport + Ingestion for a Real Account
+
+*You own the wire: authenticate to a TikTok account, publish video, pull the numbers, and write those numbers into the wiki as a durable feedback log. You do not decide what to make, when to post it, or how to caption it — that is the shortform strategy/packaging family. Deliver clean transport and a queryable log; let the siblings interpret.*
+
+TikTok splits across **three** separate APIs, and a real account touches all three:
+
+- **Content Posting API** — `https://open.tiktokapis.com/v2/post/publish/...` — the *write* side: init a publish, transfer the file, poll status. Audit-gated.
+- **Display API** — `https://open.tiktokapis.com/v2/video/...` — the *cheap read* side: your own profile and basic per-video counters (`view_count, like_count, comment_count, share_count`).
+- **TikTok API for Business** — the *rich read* side: watch time, completion, impression sources. Enabled through a **separate business portal**, not the standard developer app.
+
+Auth is **user OAuth v2 via Login Kit**, never a service token. A human owns the account; you act on their behalf with a refresh token. There is **no official TikTok SDK** — you call the REST endpoints directly with any HTTP client. Treat the access token as a short-lived, refreshable credential object, never a hardcoded literal.
+
+## When to use / When NOT
+
+Use when:
+
+- Wiring a script or agent to publish to an account: Direct Post or upload-to-draft via `/v2/post/publish/video/init/` (or `/inbox/` for a draft), then `FILE_UPLOAD` chunked PUT or `PULL_FROM_URL`, then poll `/v2/post/publish/status/fetch/`.
+- Pulling an account's own video stats: counters via Display `POST /v2/video/query/` (or `/v2/video/list/`); watch-time / completion / impression-source via the Business Account API.
+- Building the recurring "fetch performance → write to `docs/wiki/shortform/`" loop that turns API responses into an account feedback log siblings can read.
+- Debugging TikTok-specific failures: `scope_not_authorized`, `url_ownership_unverified`, `rate_limit_exceeded` (6 req/min), 24-hour access-token expiry, audit/`video.publish` not approved, unaudited-app private-only posting.
+
+Do NOT use when (route to the sibling that owns it):
+
+| You actually want | Go to |
+| --- | --- |
+| What to post / cadence / niche / hook strategy | `shortform-strategy` *(catalog id)* |
+| Clip ideas, hooks, a topic backlog | `shortform-ideation` *(catalog id)* |
+| Caption / cover / title packaging, A/B framing | `shortform-packaging` *(catalog id)* |
+| Cut/caption/render the actual clip file | `shortform-editing` *(catalog id)* |
+| Render a video file programmatically | `../remotion-video/SKILL.md` |
+| Post one asset to TikTok + IG + YouTube at once | `../social-publisher/SKILL.md` |
+| Instagram's Graph / Content Publishing API | `../instagram-api/SKILL.md` |
+| YouTube's two APIs (same family, other platform) | `../youtube-api/SKILL.md` |
+| Wrap an arbitrary REST provider with OAuth + retries | `api-connector-builder` *(catalog id)* |
+| Chain publish → Notion row → Slack across tools | `automation-flows` *(catalog id)* |
+
+One line: **this skill authenticates, calls, and ingests TikTok's Content Posting + Display + Business APIs into the wiki. What to post and how to package it belong to the shortform-strategy / shortform-ideation / shortform-packaging siblings; multi-network posting belongs to social-publisher.**
+
+## 1. One-time setup (do this before any code)
+
+A checklist, because each missing step produces a distinct, confusing failure later:
+
+1. Register a **TikTok developer app** in the developer portal.
+2. **Add the products you need**: Login Kit (OAuth), Content Posting API (publish), Display API (read counts). Insights live in the **separate TikTok for Business portal** — enable that account access too if you need watch time/completion.
+3. Set an exact **redirect URI** for the OAuth flow.
+4. **Submit the app for audit before posting public content.** An unaudited app can only post **privately** (`SELF_ONLY`) and only to a limited set of test users. This is the #1 "works on my machine, breaks in prod" surprise — see rule below.
+5. If you publish by URL (`PULL_FROM_URL`), **verify the domain / URL-prefix** in the portal (DNS TXT or URL-prefix), or every init returns `url_ownership_unverified`.
+
+The three gates are independent. Do not assume one approval covers everything:
+
+```text
+Bad:  "My app is approved, so publish + insights both work."
+Good: Content Posting *audit* gates public publish;
+      Display *scope* (video.list) gates own-video counts;
+      Business *portal* access gates watch time / completion / impression sources.
+      Three separate gates — check each.
+```
+
+Scope table — request only what the job needs:
+
+| Scope | Grants | Use for |
+| --- | --- | --- |
+| `video.publish` | Direct Post to the public feed | `/post/publish/video/init/` (audit-gated) |
+| `video.upload` | Upload to drafts/inbox for the user to finish | `/post/publish/inbox/video/init/` |
+| `video.list` | Read your own videos + basic counters | Display `POST /v2/video/query/` |
+| `user.info.basic` | Read profile (open_id, display name, avatar) | `POST /v2/user/info/` |
+
+Full app-registration + product-enable walkthrough, the audit gate, and `scope_not_authorized` troubleshooting live in `references/oauth-setup.md`.
+
+## 2. Get an authed client and keep the token alive
+
+OAuth v2: send the user to `https://www.tiktok.com/v2/auth/authorize/`, receive a `code` at your redirect URI, exchange it at `https://open.tiktokapis.com/v2/oauth/token/`, and **store the refresh token**.
+
+The lifecycle is the load-bearing fact: **access token expires in 24 hours** (`expires_in: 86400`); **refresh token lasts 365 days** (`refresh_expires_in: 31536000`) and renews without user re-consent. So a daily-pull cron **MUST refresh the access token every run**, and a long-idle account silently dies at the 365-day refresh boundary.
+
+```python
+# python: raw REST, no official TikTok SDK. requests/httpx both fine.
+import time, json, os, requests
+
+TOKEN_URL = "https://open.tiktokapis.com/v2/oauth/token/"
+STORE = "tiktok_token.json"   # gitignored — holds the rotating refresh_token
+
+def load(): return json.load(open(STORE)) if os.path.exists(STORE) else {}
+def save(t): t["obtained_at"] = int(time.time()); json.dump(t, open(STORE, "w"))
+
+def access_token():
+    t = load()
+    fresh = t.get("access_token") and time.time() < t.get("obtained_at", 0) + t["expires_in"] - 60
+    if fresh:
+        return t["access_token"]
+    r = requests.post(TOKEN_URL, data={                 # refresh every run, 24h expiry
+        "client_key": os.environ["TIKTOK_CLIENT_KEY"],
+        "client_secret": os.environ["TIKTOK_CLIENT_SECRET"],
+        "grant_type": "refresh_token",
+        "refresh_token": t["refresh_token"],            # 365-day lifetime; rotates
+    }, headers={"Content-Type": "application/x-www-form-urlencoded"})
+    r.raise_for_status()
+    new = r.json()
+    save(new)                                           # persist the NEW refresh_token
+    return new["access_token"]
+```
+
+```javascript
+// node: built-in fetch, no SDK.
+import fs from "node:fs";
+const STORE = "tiktok_token.json";
+
+async function accessToken() {
+  const t = JSON.parse(fs.readFileSync(STORE, "utf8"));
+  if (t.access_token && Date.now() / 1000 < t.obtained_at + t.expires_in - 60) return t.access_token;
+  const r = await fetch("https://open.tiktokapis.com/v2/oauth/token/", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_key: process.env.TIKTOK_CLIENT_KEY,
+      client_secret: process.env.TIKTOK_CLIENT_SECRET,
+      grant_type: "refresh_token",
+      refresh_token: t.refresh_token,
+    }),
+  });
+  const n = await r.json();
+  n.obtained_at = Math.floor(Date.now() / 1000);
+  fs.writeFileSync(STORE, JSON.stringify(n));          // persist rotated refresh_token
+  return n.access_token;
+}
+```
+
+Rule: persist the **refresh token** and re-read it each run, never a bare `access_token`. A hardcoded `access_token=...` literal is a guaranteed failure within 24 hours — and is exactly what `verify.sh` flags.
+
+Full token-exchange flow (authorize URL params, PKCE, code exchange) is in `references/oauth-setup.md`.
+
+## 3. Publish a video (init → transfer → poll)
+
+Publishing is always **three steps**: init the publish, transfer the bytes, poll until processing finishes (it is async). Pick the transfer mode first:
+
+| Situation | Source | Endpoint |
+| --- | --- | --- |
+| File is local / in your control | `FILE_UPLOAD` | `/post/publish/video/init/` |
+| File is at a **verified** HTTPS URL | `PULL_FROM_URL` | `/post/publish/video/init/` |
+| Should land as a draft the user finalizes | `FILE_UPLOAD` | `/post/publish/inbox/video/init/` |
+
+**Init** (FILE_UPLOAD) — returns `publish_id` and an `upload_url`:
+
+```python
+import math, requests
+
+CHUNK = 10 * 1024 * 1024                      # 10 MB, inside the 5–64 MB window
+size = os.path.getsize("clip.mp4")
+chunk_count = 1 if size < 5 * 1024 * 1024 else math.ceil(size / CHUNK)
+
+init = requests.post(
+    "https://open.tiktokapis.com/v2/post/publish/video/init/",
+    headers={"Authorization": f"Bearer {access_token()}",
+             "Content-Type": "application/json; charset=UTF-8"},
+    json={
+        "post_info": {"title": "caption #fyp", "privacy_level": "SELF_ONLY"},  # public needs audit
+        "source_info": {
+            "source": "FILE_UPLOAD",
+            "video_size": size,
+            "chunk_size": CHUNK if size >= 5 * 1024 * 1024 else size,
+            "total_chunk_count": chunk_count,
+        },
+    }).json()
+publish_id = init["data"]["publish_id"]
+upload_url = init["data"]["upload_url"]
+```
+
+**Transfer** — PUT chunks **sequentially** to `upload_url` with a `Content-Range` header. Chunk **min 5 MB, max 64 MB** (final chunk up to 128 MB), **1–1000 chunks**; a file under 5 MB is one chunk equal to the file size. Each PUT returns **206** (more to send) or **201** (last chunk accepted):
+
+```python
+with open("clip.mp4", "rb") as f:
+    for i in range(chunk_count):
+        first = i * CHUNK
+        data = f.read(CHUNK)
+        last = first + len(data) - 1
+        r = requests.put(upload_url, data=data, headers={
+            "Content-Type": "video/mp4",
+            "Content-Range": f"bytes {first}-{last}/{size}",  # exact byte span
+        })
+        assert r.status_code in (206, 201), r.text     # 206 = continue, 201 = done
+```
+
+**Poll** — TikTok processes asynchronously; check status until `PUBLISH_COMPLETE`. Respect the cap below — do not tight-loop:
+
+```python
+import time
+while True:
+    s = requests.post(
+        "https://open.tiktokapis.com/v2/post/publish/status/fetch/",
+        headers={"Authorization": f"Bearer {access_token()}",
+                 "Content-Type": "application/json; charset=UTF-8"},
+        json={"publish_id": publish_id}).json()
+    status = s["data"]["status"]
+    if status in ("PUBLISH_COMPLETE", "FAILED"):
+        break
+    time.sleep(10)                                      # 6/min cap — sleep, never spin
+```
+
+**Rate limit: 6 requests/minute per user access token** → `rate_limit_exceeded`. Throttle init/status calls and back off; a tight status-poll loop blows the budget in seconds.
+
+`PULL_FROM_URL` requires the domain/URL-prefix to be verified in the portal (HTTPS only, no redirects, 1-hour download timeout) or init returns `url_ownership_unverified`. Full PULL_FROM_URL init body and verification steps are in `references/metrics-and-publish.md`.
+
+## 4. Pull performance (two APIs, one rule)
+
+The load-bearing distinction: **Display gives you counters; only the Business API gives you watch time, completion, and traffic.**
+
+```python
+# (a) Display API — basic counters only. scope video.list, up to 20 ids/request.
+counts = requests.post(
+    "https://open.tiktokapis.com/v2/video/query/",
+    params={"fields": "id,title,view_count,like_count,comment_count,share_count,duration,create_time"},
+    headers={"Authorization": f"Bearer {access_token()}",
+             "Content-Type": "application/json"},
+    json={"filters": {"video_ids": ["<id1>", "<id2>"]}}).json()
+# returns: view_count, like_count, comment_count, share_count, duration, title, create_time
+```
+
+```python
+# (b) Business Account API — the real engagement signal.
+# Returns the metrics Display CANNOT: average_time_watched, total_time_watched,
+# full_video_watched_rate (completion), impression_sources (FYP / Following / profile /
+# search), audience_countries. (Endpoint shape in references/metrics-and-publish.md.)
+```
+
+```text
+Bad:  expect average_time_watched / full_video_watched_rate from /v2/video/query/
+Good: counters from Display /v2/video/query/;
+      watch time + completion + impression_sources from the Business Account API.
+```
+
+Caveat: **Business insight metrics lag 24–48h** and can differ from the in-app numbers. Treat a fresh pull as provisional — the wiki log (next section) is where you watch them settle. Full metric catalog split by API is in `references/metrics-and-publish.md`.
+
+## 5. Ingest into the wiki — the actual deliverable
+
+A pull that prints to stdout and vanishes is wasted. **Every pull appends a dated entry under `docs/wiki/shortform/`**, platform-namespaced, so the account's numbers become queryable history the strategy/packaging siblings can read.
+
+```text
+docs/wiki/shortform/
+  index.md                       # rolling pointer to latest snapshot + open questions
+  tiktok-account-2026-06-02.md   # dated account snapshot (one per pull)
+  videos/tiktok-<video_id>.md    # per-video running log, newest entry on top
+```
+
+Filenames carry the `tiktok-` prefix because the same `shortform/` wiki may also hold Instagram and YouTube pulls — namespacing keeps platforms from colliding.
+
+Per-pull entry template. The frontmatter is **OKF v0.1 conformant** — a non-empty `type` is the only hard requirement; `title`/`tags`/`timestamp` are the recommended OKF surface; the domain `date`/`range`/`account`/`platform`/`source` keys the siblings parse are preserved additively (OKF tolerates extra keys). `date` is the reporting day; `timestamp` is the ISO 8601 write moment:
+
+```markdown
+---
+type: shortform-metrics
+title: TikTok account snapshot — 2026-06-02
+tags: [tiktok, metrics, snapshot]
+timestamp: 2026-06-02T09:00:00Z
+date: 2026-06-02
+range: 2026-05-26..2026-06-01
+account: <open_id>
+platform: tiktok
+source: display-api + business-account-api
+---
+## KPIs
+views: 52,140 | likes: 3,902 | comments: 211 | shares: 488
+
+## Watch
+full_video_watched_rate: 28.4% | avg_time_watched: 6.1s | total_time_watched: 88h
+
+## Impression sources (top 3)
+For You 71% · Personal profile 14% · Search 7%
+
+## What changed since last pull
+completion +3.1pts after the tighter cold-open; FYP share up 5pts.
+```
+
+Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need, and erases the 24–48h settling you only see across pulls. The per-video log (`videos/tiktok-<id>.md`) is an OKF append-log: write its frontmatter header once, prepend each new dated block newest-first, never edit a past block. `index.md` is the OKF reserved file — no frontmatter, standard markdown links only. Exact file tree, frontmatter, naming, and how siblings read the log: `references/wiki-schema.md`.
+
+## 6. Rate & failure math
+
+The publish token is capped at **6 requests/minute**. Wrap publish/status calls in a token-bucket or backoff-with-jitter helper, and refresh the access token (24h expiry) before each cron run.
+
+Error → cause map:
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `scope_not_authorized` | Scope missing or not approved for the app | Add the scope; re-consent; check app approval |
+| Only `SELF_ONLY` posts work | App not audited | Submit for audit; use test users until approved |
+| `url_ownership_unverified` on init | PULL_FROM_URL domain not verified | Verify domain/URL-prefix (DNS TXT) in the portal |
+| `rate_limit_exceeded` | >6 req/min on the user token | Throttle + backoff; stop tight-looping the poll |
+| 401 / `access_token_invalid` mid-cron | 24h access token expired | Refresh before each run; persist refresh_token |
+| Empty watch time / completion | Wrong API **or** <24–48h since post | Use the Business API, not Display; wait for lag |
+| Refresh fails after long idle | 365-day refresh token expired | Re-run the OAuth consent flow |
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Commit `client_secret` / a token file holding `refresh_token` | Leaks full account control to anyone with repo read | Gitignore it; load from env/secret store |
+| Hardcode a 24h `access_token` literal | Dead within a day; breaks every cron | Persist the refresh token; refresh each run |
+| Tight-loop the status poll | Blows the 6/min cap → `rate_limit_exceeded` | Sleep ~10s between polls; back off on 429 |
+| Expect watch time from Display `video/query` | That field does not exist there | Counts from Display, watch time from Business |
+| Treat an unaudited app as production | Only `SELF_ONLY` posts work for real users | Submit for audit before public posting |
+| `PULL_FROM_URL` without domain verification | Every init returns `url_ownership_unverified` | Verify domain/URL-prefix first, HTTPS, no redirects |
+| Assume one approval covers publish + insights | Three independent gates | Posting audit + Display scope + Business portal |
+| Overwrite yesterday's wiki snapshot | Destroys the trend + the 24–48h settling | Append a new dated entry every pull |
+
+## Cross-references
+
+- `../social-publisher/SKILL.md` — when the asset goes to many networks, not just TikTok.
+- `../instagram-api/SKILL.md` — same family pattern, Instagram's Graph/Content Publishing API.
+- `../youtube-api/SKILL.md` — same transport+ingestion shape, YouTube's two APIs.
+- `../remotion-video/SKILL.md` — produce the clip file this skill only uploads.
+- `shortform-strategy`, `shortform-ideation`, `shortform-packaging`, `shortform-editing` *(catalog ids)* — what the numbers *mean*, what to make, and how to package/edit it.
+- `api-connector-builder`, `automation-flows`, `knowledge-ops` *(catalog ids)* — generic connector wrapping, cross-tool chaining, and wiki conventions.

package/skills/tiktok-api/evals/README.md

@@ -0,0 +1,17 @@
+# Evals — tiktok-api
+
+These are routing and coverage checks run by the skill harness, not live API tests. No
+TikTok or OAuth network calls are made. `should_trigger` asserts this skill fires on
+TikTok transport/ingestion prompts — including the non-obvious ones (24h access-token
+death, `url_ownership_unverified` on PULL_FROM_URL, `rate_limit_exceeded` at 6/min, and
+the Display-can't-give-watch-time distinction) and the Spanish/Catalan phrasings.
+`should_not_trigger` asserts the right sibling wins on intent (`shortform-strategy` /
+`shortform-packaging` / `shortform-editing`), on multi-network posting
+(`social-publisher`), on other platforms (`instagram-api`), and on generic connector
+work (`api-connector-builder`). `capability` is a rubric for a generated answer to the
+daily-cron scenario — graded on whether it covers token refresh, the chunked
+init→PUT→poll publish flow, the correct Display-vs-Business API split, the 6/min
+throttle, least-privilege scopes + the audit caveat, append-not-overwrite wiki
+ingestion, secret hygiene, and the 24–48h metric-lag caveat. Run them through the
+repo's standard skill-eval runner against `cases.yaml`. The companion `scripts/verify.sh`
+is a separate static, no-network linter you can point at integration code.

package/skills/tiktok-api/evals/cases.yaml

@@ -0,0 +1,51 @@
+skill: tiktok-api
+
+should_trigger:
+  - prompt: "Publish a video to my TikTok account via the Content Posting API and poll until it's live."
+    why: "Core write path — init → chunked transfer → status/fetch poll. The transport job this skill owns."
+  - prompt: "My TikTok access token stops working after 24 hours and the cron breaks — how do I keep it alive?"
+    why: "Non-obvious: 24h access token / 365d refresh lifecycle. This skill maps the symptom to refresh-every-run + persist refresh_token."
+  - prompt: "Pull watch time and full_video_watched_rate for my last TikTok videos and explain why the Display API returns nothing."
+    why: "The load-bearing Display-vs-Business split — those metrics only exist on the Business API, not /v2/video/query/."
+  - prompt: "publish init returns url_ownership_unverified for my PULL_FROM_URL — how do I fix it?"
+    why: "TikTok-specific failure mapped to domain/URL-prefix verification in the portal. Squarely this skill's debugging surface."
+  - prompt: "I keep hitting rate_limit_exceeded at 6 requests per minute while polling publish status."
+    why: "Non-obvious 6/min per-user-token cap; this skill prescribes sleep/backoff instead of a tight status loop."
+  - prompt: "Fetch this week's TikTok impression sources (FYP vs profile) and append them to docs/wiki/shortform/."
+    why: "The ingestion deliverable — Business API insight pull appended to the platform-namespaced feedback log."
+  - prompt: "subir vídeos a TikTok por API y guardar las métricas del canal en el wiki."
+    why: "Spanish; upload + ingest metrics — the full transport + ingestion loop this skill owns."
+  - prompt: "treure la retenció i el watch time de TikTok cap al wiki."
+    why: "Catalan; pull retention/watch time and log it — Business-API read + ingestion, this skill's core."
+
+should_not_trigger:
+  - prompt: "What kind of TikToks should I post to grow this account this quarter?"
+    route_to: shortform-strategy
+    why: "Strategy/cadence/niche, not transport. This skill delivers numbers; it does not set the plan."
+  - prompt: "Write 5 hook and caption options for this clip."
+    route_to: shortform-packaging
+    why: "Caption/cover/title packaging and A/B framing — packaging, not the API call."
+  - prompt: "Cut this long video into vertical 9:16 clips with burned-in captions."
+    route_to: shortform-editing
+    why: "Production of the file. This skill uploads the file; it does not produce it."
+  - prompt: "Post this same clip to TikTok, Instagram Reels, and YouTube Shorts at once."
+    route_to: social-publisher
+    why: "Multi-network fan-out. This skill is TikTok-only and deep on TikTok's three APIs."
+  - prompt: "Connect Instagram's Graph API to publish a Reel."
+    route_to: instagram-api
+    why: "Different platform; same family pattern, different transport."
+  - prompt: "Wrap a generic REST API I picked with OAuth and retries."
+    route_to: api-connector-builder
+    why: "Generic connector for an arbitrary provider, not TikTok's specific three-API split."
+
+capability:
+  - scenario: "Build a daily cron that authenticates to a TikTok account, publishes a local MP4 via the Content Posting API, then fetches that video's views + full_video_watched_rate + impression sources and appends a dated entry to docs/wiki/shortform/."
+    must_include:
+      - "OAuth v2 token refresh each run (24h access token / 365d refresh token, with the rotating refresh_token persisted)"
+      - "publish init (FILE_UPLOAD) → sequential Content-Range chunked PUT (5–64 MB chunks, final ≤128 MB, 1–1000 chunks; <5 MB = single chunk) expecting 206 then 201 → poll status/fetch on publish_id until PUBLISH_COMPLETE"
+      - "correct API split: counters via Display POST /v2/video/query/, but watch time + full_video_watched_rate + impression_sources via the Business Account API, NOT Display"
+      - "6 requests/minute throttle with sleep/backoff (no tight status-poll loop)"
+      - "least-privilege scopes (video.publish, video.list) and the unaudited-app SELF_ONLY-until-audited caveat"
+      - "append-not-overwrite, platform-namespaced wiki entry (tiktok-account-YYYY-MM-DD.md) with dated frontmatter"
+      - "never-commit-secret note (client_secret / refresh_token loaded from env/secret store)"
+      - "24–48h metric-lag caveat: fresh pulls are provisional"

package/skills/tiktok-api/references/metrics-and-publish.md

@@ -0,0 +1,127 @@
+# Publish call bodies + the metric catalog split by API
+
+Copy-paste request shapes for the full publish flow and the exact field split between
+Display (counters) and Business (rich insights).
+
+## Publish — FILE_UPLOAD init
+
+```json
+POST https://open.tiktokapis.com/v2/post/publish/video/init/
+Authorization: Bearer <access_token>
+Content-Type: application/json; charset=UTF-8
+
+{
+  "post_info": {
+    "title": "caption text #fyp",
+    "privacy_level": "SELF_ONLY",
+    "disable_comment": false,
+    "disable_duet": false,
+    "disable_stitch": false
+  },
+  "source_info": {
+    "source": "FILE_UPLOAD",
+    "video_size": 10485760,
+    "chunk_size": 10485760,
+    "total_chunk_count": 1
+  }
+}
+```
+
+Response `data` carries `publish_id` and `upload_url`.
+
+### Chunk math (the part people get wrong)
+
+- Chunk size **min 5 MB, max 64 MB**; the **final** chunk may run up to **128 MB**.
+- **1–1000 chunks** total, uploaded **sequentially**.
+- A file **under 5 MB is a single chunk** whose `chunk_size` equals the file size and
+  `total_chunk_count` is 1.
+- Each `PUT` to `upload_url` carries `Content-Range: bytes {first}-{last}/{total}` and
+  returns **206** (more to send) or **201** (final chunk accepted).
+
+```python
+# the PUT loop, expanded
+with open(path, "rb") as f:
+    for i in range(total_chunk_count):
+        first = i * chunk_size
+        blob = f.read(chunk_size)
+        last = first + len(blob) - 1
+        r = requests.put(upload_url, data=blob, headers={
+            "Content-Type": "video/mp4",
+            "Content-Range": f"bytes {first}-{last}/{video_size}",
+        })
+        assert r.status_code in (206, 201), (r.status_code, r.text)
+```
+
+## Publish — PULL_FROM_URL init
+
+Requires a **verified** domain/URL-prefix (see oauth-setup.md §6), HTTPS, no redirects.
+
+```json
+POST https://open.tiktokapis.com/v2/post/publish/video/init/
+
+{
+  "post_info": { "title": "caption #fyp", "privacy_level": "SELF_ONLY" },
+  "source_info": {
+    "source": "PULL_FROM_URL",
+    "video_url": "https://verified.example.com/clips/clip.mp4"
+  }
+}
+```
+
+No chunk PUT needed — TikTok fetches the file itself. Then poll status as usual.
+
+## Upload to draft (inbox)
+
+For "let the user finish/post it in-app," swap the endpoint to
+`https://open.tiktokapis.com/v2/post/publish/inbox/video/init/` with scope
+`video.upload`. Same `source_info`/chunk rules; the video lands in the user's drafts.
+
+## Status poll
+
+```json
+POST https://open.tiktokapis.com/v2/post/publish/status/fetch/
+{ "publish_id": "<publish_id>" }
+```
+
+`data.status` walks through `PROCESSING_UPLOAD` / `SEND_TO_USER_INBOX` →
+`PUBLISH_COMPLETE` or `FAILED`. Poll on a sleep, never a tight loop —
+**6 requests/minute per user token** or you hit `rate_limit_exceeded`.
+
+## Metric catalog — which API returns what
+
+### Display API — `POST /v2/video/query/` (counters only)
+
+Pass `fields` as a query param; filter by `video_ids` (**≤20 per request**). Scope
+`video.list`. Returns ONLY:
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Video id |
+| `title` | Caption/title |
+| `view_count` | Total views |
+| `like_count` | Likes |
+| `comment_count` | Comments |
+| `share_count` | Shares |
+| `duration` | Video length (s) |
+| `create_time` | Post timestamp |
+
+There is **no watch-time, completion, or impression-source field here.** Asking for one
+returns nothing — that is the wrong-API assumption `verify.sh` flags.
+
+### Business Account API — video list + insights (the rich metrics)
+
+The engagement signal lives only here:
+
+| Field | Meaning |
+| --- | --- |
+| `average_time_watched` | Mean seconds watched per view |
+| `total_time_watched` | Aggregate watch time |
+| `full_video_watched_rate` | Completion rate (watched to the end) |
+| `impression_sources` | Traffic breakdown: For You / Following / personal profile / search / sound |
+| `audience_countries` | Top viewer geographies |
+
+### Lag caveat
+
+Business insight metrics **lag 24–48h** and can differ from the in-app numbers. A pull
+within ~2 days of posting is **provisional** — log it, then watch it settle across
+later pulls (this is exactly why the wiki log appends instead of overwriting).