@bluevs/ttcli 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluevs/ttcli",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "TikTok CLI - designed for AI Agent and developers",
   "bin": {
     "ttcli": "scripts/run.js"
@@ -9,12 +9,12 @@
     "postinstall": "node -e \"console.log('\\n📦 ttcli installed. To install the openclaw skill, run:\\n  bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh\\n')\""
   },
   "optionalDependencies": {
-    "@bluevs/ttcli-darwin-arm64": "0.0.4",
-    "@bluevs/ttcli-darwin-x64": "0.0.4",
-    "@bluevs/ttcli-linux-arm64": "0.0.4",
-    "@bluevs/ttcli-linux-x64": "0.0.4",
-    "@bluevs/ttcli-win32-arm64": "0.0.4",
-    "@bluevs/ttcli-win32-x64": "0.0.4"
+    "@bluevs/ttcli-darwin-arm64": "0.0.5",
+    "@bluevs/ttcli-darwin-x64": "0.0.5",
+    "@bluevs/ttcli-linux-arm64": "0.0.5",
+    "@bluevs/ttcli-linux-x64": "0.0.5",
+    "@bluevs/ttcli-win32-arm64": "0.0.5",
+    "@bluevs/ttcli-win32-x64": "0.0.5"
   },
   "engines": {
     "node": ">=16"

package/skills/ttcli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: ttcli
-version: 0.0.4
+version: 0.0.5
 description: 直接调用 TikTok Marketing API（access token 鉴权，不经 VH 平台/项目层）。当用户提供原生 TikTok access_token + advertiser_id、要直连 TikTok 创建或查询 Smart+ campaign/adgroup/ad、或查 identity/app/region 等元数据时使用。注意：用户走 VH 项目流程（po_xxxx + account_id）的 TikTok 创编应改走 vhcli tiktok。
 ---
 
 # TikTok CLI (`ttcli`)
 
-> **Skill version**: `0.0.4`
+> **Skill version**: `0.0.5`
 >
 > 当用户问"ttcli skill 版本是多少 / skill 装好了吗 / 升级生效了没" 时，**直接念出上面的版本号**。
 > 用户期望更高版本但没看到 → 让他们：(1) 重跑 `npm install -g @bluevs/ttcli && bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh` (2) 然后**新开一个会话**（skill 在会话启动时加载，老会话不刷新）。
@@ -102,14 +102,21 @@ Before creating a campaign or adgroup, gather the IDs you'll reference:
 
 ```
 ttcli auth show                       # confirm credentials loaded + their source
+ttcli bc list                         # → bc_id (Business Centers; needed for BC_AUTH_TT identities)
 ttcli app list                        # → app_id (Android/iOS apps)
 ttcli minis list                      # → minis_id (TikTok Minis: MINI_GAME / MINI_SERIES)
 ttcli identity list                   # → identity_id (Spark Ads publishing identity)
 ttcli smart-plus campaign list        # → existing campaign_id (or you'll create one)
+ttcli smart-plus adgroup list         # → existing adgroup_id (filter by --campaign-ids / --promotion-type)
+ttcli smart-plus ad list              # → existing smart_plus_ad_id + creative_list (only explicitly-selected creatives)
 ttcli tool region \
   --placements=PLACEMENT_TIKTOK \
   --objective-type=APP_PROMOTION \
   --level-range=TO_COUNTRY            # → location_id for targeting_spec.location_ids
+ttcli tool targeting search \
+  --objective-type=APP_PROMOTION --promotion-type=APP_ANDROID \
+  --placements=PLACEMENT_TIKTOK --search-type=FUZZY_SEARCH \
+  --keywords=Kentucky                  # → geo_id by name (location_ids OR zipcode_ids)
 ```
 
 `tool region` accepts `--language=zh-CN` (or any of 78 supported codes) for localized region names — useful when surfacing options to the user.
@@ -366,6 +373,65 @@ Common codes:
 
 The CLI does NOT validate enum values, type correctness, or conditional-required fields. It only checks that unconditionally required fields are present. TikTok is the source of truth for everything else — surface its error messages directly.
 
+## TikTok user OAuth (Login Kit / Content Posting API) — separate token type
+
+ttcli's main job is Marketing API. But it also wraps OAuth-side endpoints under `tt-user` and `business`:
+
+```
+ttcli tt-user token-info \                           # inspect a user OAuth token
+  --app-id=aw1234abcd5678 \
+  --tt-access-token=act.xxxxx
+
+ttcli business get \                                 # account profile + insights
+  --business-id=open_id_xxx \                        #   (= creator_id from tt-user token-info)
+  --tt-access-token=act.xxxxx \
+  --fields=username,display_name,followers_count,video_views,audience_countries
+```
+
+**These are different token types** from the rest of ttcli. The Marketing API token in `auth show` is for ad management (`/smart_plus/...`, `/report/...`). The token here is a **TikTok user OAuth token** from Login Kit / Content Posting API consumer flow — used for posting videos, reading user profile, etc. They are not interchangeable.
+
+| Endpoint | Auth model | Required scopes (some) |
+|---|---|---|
+| `/tt_user/token_info/get/` | access_token in JSON body, no header | n/a (introspection) |
+| `/business/get/` | Access-Token header (with user OAuth token) | `user.info.basic`, `user.info.username`, `user.info.profile`, `user.info.stats`, `user.account.type`, `user.insights` |
+
+If the user only has a Marketing API token, both will return `code=40105 access_token invalid` — that's the signal to ask for a Login-Kit-flow token instead.
+
+**`business get` defaults**: TikTok defaults `fields=["display_name","profile_image"]` — pass `--fields=...` to get more. Daily metrics have **24-48h delay**; same-day data is unavailable. Audience demographic fields require **≥100 followers**.
+
+## Reporting (async)
+
+`ttcli report task create` posts to `/report/task/create/` and returns a `task_id`. The actual report data is NOT in the response — async reports are three steps:
+
+1. **Create task** — `ttcli report task create ...` → `task_id`
+2. **Poll status** — `ttcli report task check --task-id=...` → `status` (QUEUING / PROCESSING / SUCCESS / FAILED / CANCELED). Poll every ~30s; tasks typically take 30s–a few minutes.
+3. **Download** — `ttcli report task download --task-id=...`. Behavior depends on what `--output-format` you used at create:
+   - **CSV_STRING** (default at create) → returns raw CSV bytes directly to stdout. AI agents: parse CSV from stdout.
+   - **CSV_DOWNLOAD / XLSX_DOWNLOAD** → returns JSON with a 1-hour signed `download_url`. Pass `--out=FILE --fetch` to follow the URL and write the file in one shot.
+
+**Bad task_id gotcha**: TikTok returns `code=51010 internal system error` for unknown task_ids on `task check` (not a clean 4xx). Treat 51010 as "task not found / not yours" when polling.
+
+**Stdout vs JSON**: `task download` is the one ttcli command where `--human`/JSON modes are ignored on the CSV_STRING branch — the body IS the data, so it's written verbatim to stdout. Other commands honor JSON-by-default.
+
+**Async filtering is restricted**: only `campaign_ids` / `adgroup_ids` / `ad_ids` / `country_code` (max 20000 IDs total). For other filters, use sync `/report/integrated/get/` (also not yet wrapped).
+
+**Lifetime metrics**: pass `--query-lifetime` to get all-time metrics; ignores `--start-date`/`--end-date`. No time/audience/country breakdowns allowed in lifetime mode.
+
+**Recommended**: pass `--enable-title-translation=false` for stable header rows (TikTok periodically updates translated headers — raw field names don't change).
+
+```
+ttcli report task create \
+  --report-type=BASIC --data-level=AUCTION_AD \
+  --dimensions=ad_id,stat_time_day \
+  --metrics=spend,impressions,clicks,cpc,ctr \
+  --start-date=2026-05-01 --end-date=2026-06-01 \
+  --filter-ad-ids=1866239337888050,1866239351340034 \
+  --output-format=CSV_DOWNLOAD \
+  --enable-title-translation=false
+```
+
+Limits: 1 QPS per app; 500 async tasks/hour per advertiser; 30-day task validity.
+
 ## Credentials
 
 Priority: `--flag` > env var > config file (`~/.config/ttcli/credentials.json`, mode 0600).