@agentapps/app.tiktok-ads 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,128 @@
1
+ # TikTok Ads
2
+
3
+ Lets an agent work with TikTok ad accounts through the TikTok API for Business (Marketing API
4
+ v1.3, `https://business-api.tiktok.com/open_api/v1.3`). It can list the ad accounts a token can
5
+ reach, list campaigns, ad groups and ads, and run performance and audience reports. It can also
6
+ pause or enable delivery and change a campaign or ad group budget. It does not create or delete
7
+ anything. Enabling delivery and budget changes affect spend: they are marked destructive and ask
8
+ for approval.
9
+
10
+ ## Tools
11
+
12
+ | Tool | What it does | Writes? |
13
+ |---|---|---|
14
+ | `list-advertisers` | The ad accounts (advertisers) the access token is authorized for. Needs the app credentials (system secrets). | no |
15
+ | `get-advertiser-info` | Account details: status, currency, time zone, balance, company, country (up to 100 accounts). | no |
16
+ | `list-campaigns` | Campaigns of one account with status, budget and budget mode; filters by id, name and status; paged. | no |
17
+ | `list-ad-groups` | Ad groups, optionally of some campaigns, with status, budget, bidding and schedule; paged. | no |
18
+ | `list-ads` | Ads, optionally of some campaigns or ad groups, with status, format, text and landing page; paged. | no |
19
+ | `get-report` | Synchronous report (`report/integrated/get`): BASIC or AUDIENCE, any level, dimensions, metrics, date range or lifetime, filters, totals. Returns columns and rows. | no |
20
+ | `pause-delivery` | Pauses up to 20 campaigns, ad groups or ads (reversible). | yes, sensitive |
21
+ | `enable-delivery` | Enables up to 20 campaigns, ad groups or ads. **Affects spend.** | yes, sensitive, destructive |
22
+ | `update-budget` | Sets one campaign or ad group budget; returns the previous budget so it can be reverted. **Affects spend.** | yes, sensitive, destructive |
23
+
24
+ Limits:
25
+
26
+ - Lists return at most 100 items per page, reports at most 500 rows per page, and every result
27
+ stays under 50,000 characters (`limitApplied` on lists, a `[RESULT_TOO_LARGE]` error naming
28
+ what to shrink on reports).
29
+ - Report date ranges are at most 365 days. TikTok applies stricter limits of its own (for
30
+ example on hourly data) and says so in a `[BAD_REQUEST]` error.
31
+ - Report dates and `stat_time_*` values are in the ad account's time zone; money is in the
32
+ account currency (see `get-advertiser-info`).
33
+
34
+ ### TikTok ids and the CLI
35
+
36
+ TikTok ids (advertiser, campaign, ad group, ad) are 16-19 digit numbers, above JavaScript's
37
+ safe integer range. The `agentapps` CLI turns `key:value` arguments that look like numbers into
38
+ numbers, which would round such an id to a different one. The tools refuse a rounded id, so pass
39
+ ids inside a single JSON object (or as JSON on stdin):
40
+
41
+ ```bash
42
+ agentapps tiktok-ads tool list-campaigns '{"advertiserId":"7012345678901234567"}'
43
+ ```
44
+
45
+ MCP clients send JSON, so this only matters on the command line.
46
+
47
+ ## Setup
48
+
49
+ The app needs three values: the TikTok developer app's id and secret (system secrets, shared by
50
+ every installation) and an advertiser access token (a user secret, per installation).
51
+
52
+ 1. **Developer account and app.** Sign in at the
53
+ [TikTok API for Business portal](https://business-api.tiktok.com/portal) with a TikTok for
54
+ Business account, register as a developer and create an app (My Apps, Create). Give it an
55
+ advertiser redirect URL you control and request the Marketing API permission scopes this app
56
+ uses: **Ad Account Management** (account list and info), **Ads Management** (campaigns, ad
57
+ groups, ads, status and budget changes) and **Reporting**. TikTok reviews new apps; once it is
58
+ approved, the app page shows the **App ID**, the **Secret** and an **advertiser authorization
59
+ URL**.
60
+ 2. **Authorize the ad accounts.** Open the advertiser authorization URL while signed in as a
61
+ user with access to the ad accounts (or the Business Center that owns them), pick the
62
+ accounts and confirm. TikTok redirects to your redirect URL with an `auth_code` query
63
+ parameter, valid for a short time.
64
+ 3. **Exchange the code for a long-lived access token** (once, by hand):
65
+
66
+ ```bash
67
+ curl -s -X POST https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/ \
68
+ -H 'Content-Type: application/json' \
69
+ -d '{"app_id":"<App ID>","secret":"<Secret>","auth_code":"<auth_code>"}'
70
+ ```
71
+
72
+ The answer's `data.access_token` is the token, and `data.advertiser_ids` lists the accounts it
73
+ can manage. TikTok issues advertiser tokens as long-term tokens with no refresh step; one
74
+ stops working when the advertiser revokes the authorization, and the tools then answer
75
+ `[AUTH_REQUIRED]`. To add accounts later, authorize again and use the new token.
76
+ 4. **Install and configure:**
77
+
78
+ ```bash
79
+ agentapps install app.tiktok-ads tiktok-ads
80
+ # System secrets: set on the app id, shared by every installation
81
+ agentapps config app.tiktok-ads TIKTOK_APP_ID:"<App ID>"
82
+ agentapps config app.tiktok-ads TIKTOK_APP_SECRET:"<Secret>"
83
+ # User secret: set on the installed alias
84
+ agentapps config tiktok-ads TIKTOK_ACCESS_TOKEN:"<access_token>"
85
+ agentapps tiktok-ads tools
86
+ agentapps tiktok-ads tool list-advertisers
87
+ agentapps tiktok-ads tool get-report '{"advertiserId":"<id>","startDate":"2026-10-01","endDate":"2026-10-07","dimensions":["campaign_id","stat_time_day"]}'
88
+ ```
89
+
90
+ - `TIKTOK_ACCESS_TOKEN` (user secret, required): the advertiser access token from step 3. Every
91
+ tool needs it.
92
+ - `TIKTOK_APP_ID`, `TIKTOK_APP_SECRET` (system secrets): only `list-advertisers` and the health
93
+ check use them, because TikTok's advertiser list endpoint asks for the app credentials next to
94
+ the token. Without them the other tools still work with an advertiser id you already know (from
95
+ step 3 or TikTok Ads Manager), and the health check reports `degraded`.
96
+
97
+ ### Why not the host's OAuth flow
98
+
99
+ TikTok's authorization does not follow the standard OAuth 2.0 shape the host implements: the
100
+ authorize URL takes `app_id` instead of `client_id`, the callback carries `auth_code`, the token
101
+ exchange is a JSON body (`app_id`, `secret`, `auth_code`) instead of a form post, and the token
102
+ comes back inside TikTok's `{ code, message, data }` envelope instead of a top-level
103
+ `access_token`. Since the advertiser token is long-term, a one-time manual exchange is enough.
104
+
105
+ ## Terms of use
106
+
107
+ Using the API requires a TikTok for Business developer account and accepting the TikTok For
108
+ Business Developer Terms when registering in the
109
+ [API for Business portal](https://business-api.tiktok.com/portal), on top of the TikTok
110
+ Advertising Terms that govern the ad accounts. See TikTok's
111
+ [About API for Business](https://ads.tiktok.com/help/article/marketing-api) help article. The API
112
+ is rate limited per app and advertiser; when TikTok answers with code 40100 the tools return a
113
+ `[RATE_LIMITED]` error and the agent should wait before retrying.
114
+
115
+ ## Logos
116
+
117
+ | File | Source | Changes |
118
+ |---|---|---|
119
+ | assets/logo.png | TikTok for Developers logo pack, linked from the [design guidelines](https://developers.tiktok.com/doc/getting-started-design-guidelines) (`logo-pack.zip`), `TikTok Logo Pack/TikTok – Icons/TikTok_Icon_Black_Square.png` (1200x1200) | none (renamed) |
120
+
121
+ TODO: no official one-colour SVG found yet for `assets/logo-mono.svg`. Searched: the TikTok for
122
+ Developers logo pack above (SVGs only for the "Continue with TikTok" buttons, which contain text;
123
+ the icon itself is PNG and Adobe Illustrator only), the
124
+ [TikTok Brand Hub](https://tiktokbrandhub.com/) linked from the developer site (pages rendered
125
+ by JavaScript with no downloadable files; its favicon SVG is the note on a coloured square
126
+ badge, which leaves a solid block once the fills are removed), the TikTok for Developers site
127
+ header (a multi-colour layered "TikTok for Developers" wordmark), and the tiktok.com and
128
+ TikTok for Business home pages (no SVG logo in the served HTML).
package/agentapp.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "app.tiktok-ads",
3
3
  "name": "TikTok Ads",
4
- "version": "1.0.0",
4
+ "version": "1.0.1",
5
5
  "description": "TikTok Ads through the TikTok API for Business (Marketing API v1.3): list ad accounts, campaigns, ad groups and ads, run performance and audience reports, pause or enable delivery and change campaign or ad group budgets. Enabling delivery and budget changes affect spend and ask for approval.",
6
6
  "tagline": "Report on TikTok ad campaigns and pause, enable or re-budget them",
7
7
  "author": { "name": "Pablo López Torres", "email": "pablolopeztorres@gmail.com" },
package/dist/app.js CHANGED
@@ -21528,7 +21528,7 @@ class AppInstance {
21528
21528
  success: false,
21529
21529
  error: {
21530
21530
  code: ErrorCode.UNAUTHORIZED,
21531
- message: `Missing required user secret(s): ${missingSecrets.join(", ")}. ` + `Configure them for this installation before using ${this.config.id}.`
21531
+ message: `Missing required Installation secret(s): ${missingSecrets.join(", ")}. ` + `Configure them for this installation before using ${this.config.id}.`
21532
21532
  },
21533
21533
  duration: 0
21534
21534
  });
@@ -23892,7 +23892,7 @@ function registerTools(app) {
23892
23892
  var app = createApp({
23893
23893
  id: "app.tiktok-ads",
23894
23894
  name: "TikTok Ads",
23895
- version: "1.0.0",
23895
+ version: "1.0.1",
23896
23896
  description: "TikTok Ads through the TikTok API for Business (Marketing API v1.3): list ad accounts, campaigns, ad groups and ads, run performance and audience reports, pause or enable delivery and change campaign or ad group budgets. Enabling delivery and budget changes affect spend and ask for approval.",
23897
23897
  tagline: "Report on TikTok ad campaigns and pause, enable or re-budget them",
23898
23898
  author: { name: "Pablo López Torres", email: "pablolopeztorres@gmail.com" },
package/package.json CHANGED
@@ -1,11 +1,30 @@
1
1
  {
2
2
  "name": "@agentapps/app.tiktok-ads",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
+ "description": "Report on TikTok ad campaigns and pause, enable or re-budget them",
5
+ "license": "MIT",
6
+ "author": "Pablo López Torres <pablolopeztorres@gmail.com>",
7
+ "keywords": [
8
+ "agent-apps",
9
+ "tiktok",
10
+ "tiktok-ads",
11
+ "ads",
12
+ "advertising",
13
+ "marketing",
14
+ "campaigns",
15
+ "reports",
16
+ "ppc"
17
+ ],
4
18
  "type": "module",
5
19
  "main": "./dist/app.js",
6
20
  "exports": {
7
21
  ".": "./dist/app.js",
8
22
  "./agentapp.json": "./agentapp.json",
9
23
  "./package.json": "./package.json"
24
+ },
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "https://github.com/agentapps/agentapps.git",
28
+ "directory": "apps/tiktok-ads"
10
29
  }
11
30
  }