@agentapps/app.meta-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,164 @@
1
+ # Meta Ads
2
+
3
+ Lets an agent report on and manage Meta (Facebook and Instagram) advertising through the
4
+ [Meta Marketing API](https://developers.facebook.com/docs/marketing-api), Graph API **v26.0**.
5
+ It lists ad accounts, campaigns, ad sets, ads and creatives, runs performance reports
6
+ (Ads Insights) at any level with date ranges, daily series and breakdowns, pauses and
7
+ activates delivery, changes budgets, and creates campaigns and ad sets. New campaigns and ad
8
+ sets are always created **paused**. Creating ads (images, video, Page posts) is not
9
+ supported: finish ads in Ads Manager.
10
+
11
+ Every write asks for approval by default. The tools that can make you spend money
12
+ (`activate-ad-object`, `update-budget`) are marked destructive and say so in their
13
+ descriptions.
14
+
15
+ ## Tools
16
+
17
+ | Tool | What it does | Writes? |
18
+ |---|---|---|
19
+ | `list-ad-accounts` | Ad accounts the token can use: id, name, status, currency, time zone, amount spent | no |
20
+ | `list-campaigns` | Campaigns of an account: objective, status, effective status, budgets, bid strategy | no |
21
+ | `list-ad-sets` | Ad sets of a campaign or account: budgets, optimisation goal, billing, schedule, targeting on request | no |
22
+ | `list-ads` | Ads of an ad set, campaign or account, with their creative and delivery issues | no |
23
+ | `list-creatives` | Ad creatives of an account: title, body, thumbnail, call to action | no |
24
+ | `get-insights` | Performance report for an account, campaign, ad set or ad: spend, impressions, reach, clicks, CTR, CPC, CPM or any Insights field; level, date preset or range, daily/weekly/monthly series, breakdowns, sort | no |
25
+ | `pause-ad-object` | Pause a campaign, ad set or ad (stops spend; reversible) | yes |
26
+ | `activate-ad-object` | Activate a campaign, ad set or ad. **Starts spending money** (destructive) | yes |
27
+ | `update-budget` | Change the daily or lifetime budget of a campaign or ad set. **Affects spend** (destructive) | yes |
28
+ | `create-campaign` | Create a campaign, always PAUSED, with or without a campaign budget | yes |
29
+ | `create-ad-set` | Create an ad set in a campaign, always PAUSED, with targeting and budget | yes |
30
+
31
+ Before any status or budget change the app reads the object with a field only that kind of
32
+ object has, so a write meant for an ad never lands on an ad set. Budgets are integers in the
33
+ account currency's minor units (cents: `5000` = 50.00); Insights `spend` is in major units.
34
+
35
+ ## Setup
36
+
37
+ The app needs one user secret, `META_ACCESS_TOKEN`, and no system secrets.
38
+
39
+ ```bash
40
+ agentapps install app.meta-ads meta-ads
41
+ agentapps config meta-ads META_ACCESS_TOKEN:"<token>"
42
+ agentapps meta-ads tools
43
+ agentapps meta-ads tool list-ad-accounts
44
+ agentapps meta-ads tool get-insights id:act_1234567890 level:campaign datePreset:last_7d
45
+ ```
46
+
47
+ Installation secrets are per installation: set them on the alias (`meta-ads` above), not on
48
+ `app.meta-ads`. (`agentapps config app.meta-ads KEY:value` sets system secrets shared by every
49
+ installation; this app declares none.)
50
+
51
+ Campaign, ad set and ad ids have up to 18 digits, more than a JavaScript number holds. The
52
+ CLI turns `id:120210000000000001` into a rounded number, which the app rejects. Pass such
53
+ calls as one JSON object instead, which keeps strings:
54
+
55
+ ```bash
56
+ agentapps meta-ads tool pause-ad-object '{"level":"campaign","id":"120210000000000001"}'
57
+ ```
58
+
59
+ ### Getting `META_ACCESS_TOKEN` (recommended: a System User token)
60
+
61
+ A System User token belongs to your business, not to a person, and does not expire. It can
62
+ reach exactly the ad accounts you assign to the System User.
63
+
64
+ 1. **Business portfolio.** You need a Meta business portfolio
65
+ ([business.facebook.com](https://business.facebook.com)) that owns, or has partner access
66
+ to, the ad accounts. You need admin rights in it.
67
+ 2. **Meta app.** At [developers.facebook.com/apps](https://developers.facebook.com/apps),
68
+ create a Business app, add the Marketing API (the ads management use case) and connect the
69
+ app to the business portfolio. No App Review is needed to manage your own business's ad
70
+ accounts: standard access to `ads_read` and `ads_management` is enough. Leave **Require App Secret** off in the app's advanced settings:
71
+ this app does not send `appsecret_proof`.
72
+ 3. **System User.** In [Business Settings](https://business.facebook.com/settings) → Users →
73
+ **System Users**, click **Add** and create a System User (role Employee is enough; Admin
74
+ also works). Then, on that System User, click **Add assets**: under **Ad accounts**, pick
75
+ each ad account and allow managing campaigns (needed by the write tools) or only viewing
76
+ performance (reporting only); under **Apps**, pick your app.
77
+ 4. **Token.** On the same System User, click **Generate new token**, select your app, and
78
+ permission:
79
+ - `ads_read`: every read tool and reports,
80
+ - `ads_management`: pause, activate, budgets, create,
81
+ - `business_management`: lists ad accounts the business reaches through other portfolios.
82
+
83
+ System User tokens do not expire by default (if an expiry choice is shown, pick
84
+ **Never**). Copy it right away: Meta shows it only once. A reporting-only installation can
85
+ use a token with just `ads_read` (writes then fail with `[FORBIDDEN]`). Meta's guides:
86
+ [System Users](https://developers.facebook.com/docs/marketing-api/system-users),
87
+ [Generate an access token](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens#generate-token).
88
+ 5. Store it: `agentapps config <alias> META_ACCESS_TOKEN:"<token>"`. In this repo,
89
+ `META_ACCESS_TOKEN=... node packages/create/dist/cli.js health apps/meta-ads` runs the
90
+ health check, which calls `/me` and names the token's owner.
91
+
92
+ Account ids: `list-ad-accounts` returns them as `act_<digits>`; every tool also accepts the
93
+ bare digits.
94
+
95
+ **Access tier and limits.** New apps get the Marketing API's **Limited access** tier: heavily
96
+ rate-limited per ad account and meant for development, with 1 System User. For everyday use,
97
+ request **Full access** with **+Upgrade** on the Marketing API Access Tier feature in the App
98
+ Dashboard once the app qualifies (500 Marketing API calls in the past 15 days, at the time of
99
+ writing); see [Authorization](https://developers.facebook.com/docs/marketing-api/get-started/authorization)
100
+ and [Rate limiting](https://developers.facebook.com/docs/marketing-api/overview/rate-limiting).
101
+ Throttling comes back as `[RATE_LIMITED]`: wait a few minutes. Ad set budgets can change about
102
+ 4 times per hour.
103
+
104
+ ### Alternative: a personal long-lived token
105
+
106
+ A user access token from the [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
107
+ (with the same three permissions), exchanged for a long-lived one, also works, but it expires
108
+ after about 60 days and reaches only the ad accounts that person can use. When it expires,
109
+ calls fail with `[AUTH_REQUIRED]` and you set a new one with the same `agentapps config` line.
110
+
111
+ ### Why not OAuth (Facebook Login) in the app
112
+
113
+ The host's generic OAuth flow (authorize URL + code exchange, refresh with a refresh token)
114
+ does not fit Meta today:
115
+
116
+ - Business apps log in with **Facebook Login for Business**, which takes a `config_id` (a
117
+ login configuration created per Meta app) instead of `scope`, plus
118
+ `override_default_response_type=true` for System User tokens. The host builds the authorize
119
+ URL from the manifest's static `authorizeUrl` and `scopes` and the `CLIENT_ID` system secret;
120
+ it has no way to add a per-deployment `config_id`, and the schema requires a non-empty
121
+ `scopes` list that Meta says not to send.
122
+ - With a user-token configuration, Meta returns a short-lived token (hours) and **no refresh
123
+ token**, so the host's refresh never runs. The app would have to exchange it for a 60-day
124
+ token (`fb_exchange_token`, needs the app secret) and a person would still reconnect every
125
+ 60 days.
126
+ - Using `ads_read` / `ads_management` on ad accounts of other businesses requires Meta App
127
+ Review (advanced access) and business verification.
128
+
129
+ A System User token pasted once avoids all of this. An OAuth variant would need: `auth.type:
130
+ "oauth2"` with a `facebook` provider (authorize
131
+ `https://www.facebook.com/v26.0/dialog/oauth`, token
132
+ `https://graph.facebook.com/v26.0/oauth/access_token`), only `ACCESS_TOKEN` as user secret,
133
+ system secrets `CLIENT_ID`, `CLIENT_SECRET` and a `CONFIG_ID` set once with
134
+ `agentapps config app.meta-ads CLIENT_ID:<app id>` (and so on), and a host change that adds
135
+ `config_id` and `override_default_response_type` to the authorize URL.
136
+
137
+ Meta also hosts an official Ads MCP server (`https://mcp.facebook.com/ads`). This app differs
138
+ from it by asking for approval before each write, marking spend-affecting tools destructive,
139
+ keeping a small set of bounded tools, and storing one token per installation.
140
+
141
+ ## Terms of use
142
+
143
+ Use of the Marketing API is governed by the
144
+ [Meta Platform Terms](https://developers.facebook.com/terms) and the
145
+ [Developer Policies](https://developers.facebook.com/devpolicy/) (including the Marketing API
146
+ section). Ads you create or activate must follow
147
+ [Meta's Advertising Standards](https://transparency.meta.com/policies/ad-standards/), and ads
148
+ about employment, housing, credit, social issues, elections or politics, gambling or financial
149
+ products must declare their special ad category. Graph API versions are supported for about
150
+ two years; this app pins v26.0 (released July 2026).
151
+
152
+ ## Logos
153
+
154
+ TODO: no logo shipped yet; `assets/logo.svg` and `assets/logo-mono.svg` are placeholders.
155
+ Searched: the [Meta brand resource center](https://www.meta.com/brand/resources/meta/company-brand/)
156
+ has the official Meta company lockup (four colour variants, including mono), but the download
157
+ sits behind accepting Meta's brand terms, and the page says "All usage of the Meta logo
158
+ requires approval" through Meta's Brand Review process, which a person at the company has to
159
+ request. The meta.com site icon (`static.xx.fbcdn.net`, gradient symbol) is under the same
160
+ terms, and the guidelines say the Meta logo must not stand for Facebook. Icon collections
161
+ (Bootstrap Icons, logo aggregators) are not official sources. Next step: a person accepts the
162
+ terms (or gets Brand Review approval), downloads the lockup zip from the brand page, and adds
163
+ the primary symbol as `assets/logo.svg` and the mono symbol, with fills removed, as
164
+ `assets/logo-mono.svg`.
package/agentapp.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "app.meta-ads",
3
3
  "name": "Meta Ads",
4
- "version": "1.0.0",
4
+ "version": "1.0.1",
5
5
  "description": "Meta (Facebook and Instagram) ads through the Marketing API: list ad accounts, campaigns, ad sets, ads and creatives, run performance reports with breakdowns, pause or activate delivery, change budgets, and create campaigns and ad sets (always paused)",
6
6
  "tagline": "Report on Meta ad performance and manage campaigns, ad sets, ads and budgets",
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
  });
@@ -24360,7 +24360,7 @@ function registerTools(app) {
24360
24360
  var app = createApp({
24361
24361
  id: "app.meta-ads",
24362
24362
  name: "Meta Ads",
24363
- version: "1.0.0",
24363
+ version: "1.0.1",
24364
24364
  description: "Meta (Facebook and Instagram) ads through the Marketing API: list ad accounts, campaigns, ad sets, ads and creatives, run performance reports with breakdowns, pause or activate delivery, change budgets, and create campaigns and ad sets (always paused)",
24365
24365
  tagline: "Report on Meta ad performance and manage campaigns, ad sets, ads and budgets",
24366
24366
  author: { name: "Pablo López Torres", email: "pablolopeztorres@gmail.com" },
package/package.json CHANGED
@@ -1,11 +1,31 @@
1
1
  {
2
2
  "name": "@agentapps/app.meta-ads",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
+ "description": "Report on Meta ad performance and manage campaigns, ad sets, ads and budgets",
5
+ "license": "MIT",
6
+ "author": "Pablo López Torres <pablolopeztorres@gmail.com>",
7
+ "keywords": [
8
+ "agent-apps",
9
+ "meta",
10
+ "facebook",
11
+ "instagram",
12
+ "ads",
13
+ "advertising",
14
+ "marketing",
15
+ "campaigns",
16
+ "insights",
17
+ "ppc"
18
+ ],
4
19
  "type": "module",
5
20
  "main": "./dist/app.js",
6
21
  "exports": {
7
22
  ".": "./dist/app.js",
8
23
  "./agentapp.json": "./agentapp.json",
9
24
  "./package.json": "./package.json"
25
+ },
26
+ "repository": {
27
+ "type": "git",
28
+ "url": "https://github.com/agentapps/agentapps.git",
29
+ "directory": "apps/meta-ads"
10
30
  }
11
31
  }