@agentapps/app.google.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,116 @@
1
+ # Google Ads
2
+
3
+ Lets an agent work with Google Ads accounts through the [Google Ads API](https://developers.google.com/google-ads/api/docs/start)
4
+ (REST, version **v26**, plain `fetch`, no SDK). It lists the accounts a Google user can reach,
5
+ directly or through manager (MCC) accounts, reports on account, campaign, ad group, ad,
6
+ keyword and search term performance, runs read-only GAQL queries, and makes a small set of
7
+ changes: pause or enable campaigns and ad groups, change a campaign budget, add negative
8
+ keywords. It does not create campaigns, ads or keywords, and it does not remove anything.
9
+
10
+ Limits: reports return at most 500 rows (1,000 accounts for `list-client-accounts`) and stay
11
+ under about 45,000 characters; each call gives up after 30 s. Google applies a daily operation
12
+ quota per developer token (see Setup). Money in results is in the account currency, not micros,
13
+ except in the raw rows of `run-gaql-query`.
14
+
15
+ ## Tools
16
+
17
+ | Tool | What it does | Writes? |
18
+ |---|---|---|
19
+ | `list-accessible-customers` | Accounts the connected user can reach directly; flags manager accounts | no |
20
+ | `list-client-accounts` | Client accounts under a manager account, and the `loginCustomerId` to use for them | no |
21
+ | `get-account-summary` | Account details and total metrics for a date range | no |
22
+ | `list-campaigns` | Campaigns with status, channel, bidding strategy and budget (no metrics) | no |
23
+ | `list-campaign-budgets` | Budgets with amount, period and how many campaigns share each | no |
24
+ | `get-performance-report` | Metrics per campaign, ad group, ad or keyword, optionally per day | no |
25
+ | `get-search-terms-report` | The search queries that triggered ads, with the matched keyword | no |
26
+ | `run-gaql-query` | Any read-only GAQL `SELECT`, with paging | no |
27
+ | `pause-campaign` | Pause a campaign (stops spend; reversible) | yes |
28
+ | `enable-campaign` | Enable a campaign. **Affects spend**, marked destructive | yes |
29
+ | `pause-ad-group` | Pause an ad group (reversible) | yes |
30
+ | `enable-ad-group` | Enable an ad group. **Affects spend**, marked destructive | yes |
31
+ | `update-campaign-budget` | Set a budget amount. **Affects spend**, marked destructive | yes |
32
+ | `add-negative-keywords` | Add up to 100 negative keywords to a campaign or ad group | yes |
33
+
34
+ All write tools are `sensitive` (the host asks before running them) and accept
35
+ `validateOnly: true`, which makes Google check the change without applying it. Date ranges are
36
+ a preset (`dateRange`, default `LAST_30_DAYS`) or `startDate` + `endDate` (`YYYY-MM-DD`), in
37
+ the account's time zone.
38
+
39
+ ### Manager accounts and `loginCustomerId`
40
+
41
+ Every tool that works on an account takes `customerId` (10 digits, dashes allowed) and an
42
+ optional `loginCustomerId`. When the connected Google user reaches an account only through a
43
+ manager (MCC) account, Google needs that manager's ID in the `login-customer-id` header: pass
44
+ it as `loginCustomerId`. It is a tool parameter rather than a setting because one user often
45
+ works with several managers, and a per-installation secret would have to be set (to a
46
+ placeholder) even by users without one. `list-accessible-customers` shows which accounts are
47
+ managers and `list-client-accounts` returns the `loginCustomerId` to use for each client. A
48
+ `USER_PERMISSION_DENIED` error says when it is missing.
49
+
50
+ ## Setup
51
+
52
+ The app uses Google OAuth plus a Google Ads developer token. You need:
53
+
54
+ 1. **A Google Cloud project** with the **Google Ads API** enabled
55
+ (APIs & Services > Library > Google Ads API).
56
+ 2. **An OAuth client** in that project (APIs & Services > Credentials > Create credentials >
57
+ OAuth client ID, type *Web application*), with the station callback as an authorised
58
+ redirect URI: `<station publicUrl>/auth/callback`. This gives `CLIENT_ID` and `CLIENT_SECRET`.
59
+ 3. **The OAuth consent screen** with the scopes `https://www.googleapis.com/auth/adwords` and
60
+ `https://www.googleapis.com/auth/userinfo.email`. `adwords` is a sensitive scope: while the
61
+ app is in *Testing* only the listed test users can connect and their refresh tokens expire
62
+ after 7 days; for real users Google must verify the app (Publish app, then verification).
63
+ 4. **A developer token** (`DEVELOPER_TOKEN`) from a Google Ads **manager** account: Admin >
64
+ API Center ([guide](https://developers.google.com/google-ads/api/docs/get-started/dev-token)).
65
+ A new token has *Test* access (test accounts only). Production accounts need *Explorer*
66
+ (2,880 operations a day), *Basic* (15,000 a day, after brand verification) or *Standard*
67
+ (unlimited, after a compliance review), each applied for from the API Center
68
+ ([access levels](https://developers.google.com/google-ads/api/docs/api-policy/access-levels)).
69
+ Use the token with the OAuth client of the same Google Cloud project.
70
+ 5. **The customer IDs** you will work with: the 10-digit number at the top of the Google Ads
71
+ UI (`123-456-7890`), and the manager account ID when you access clients through one.
72
+ `list-accessible-customers` finds them too.
73
+
74
+ System secrets (shared by every installation, set on the app id):
75
+
76
+ ```bash
77
+ agentapps config app.google.ads CLIENT_ID:"<oauth client id>"
78
+ agentapps config app.google.ads CLIENT_SECRET:"<oauth client secret>"
79
+ agentapps config app.google.ads REDIRECT_URI:"https://your-station.example.com/auth/callback"
80
+ agentapps config app.google.ads DEVELOPER_TOKEN:"<developer token>"
81
+ ```
82
+
83
+ `REDIRECT_URI` is only needed when `agentapps.json` has no `station.publicUrl`.
84
+
85
+ Then install an instance and connect a Google account (installation secrets belong to the alias;
86
+ `ACCESS_TOKEN`, `REFRESH_TOKEN`, `EMAIL` and `EXPIRY_DATE` are written by the OAuth flow, not
87
+ by hand):
88
+
89
+ ```bash
90
+ agentapps install app.google.ads google-ads
91
+ agentapps google-ads auth
92
+ agentapps google-ads tool list-accessible-customers
93
+ agentapps google-ads tool get-performance-report customerId:123-456-7890 dateRange:LAST_7_DAYS
94
+ agentapps google-ads tool list-client-accounts customerId:987-654-3210
95
+ ```
96
+
97
+ If you ever need to set a user secret by hand, use the alias, not the app id:
98
+ `agentapps config google-ads KEY:value`.
99
+
100
+ ## Terms of use
101
+
102
+ Use of the Google Ads API is governed by the
103
+ [Google Ads API Terms and Conditions](https://developers.google.com/google-ads/api/terms) and
104
+ the [Google Ads API policies](https://developers.google.com/google-ads/api/docs/api-policy/developer-token):
105
+ the developer token belongs to whoever applied for it, its daily operation quota applies to all
106
+ users of that token, and tools built on it must not be used to break the
107
+ [Google Ads policies](https://support.google.com/adspolicy/answer/6008942). Spend caused by
108
+ `enable-campaign`, `enable-ad-group` or `update-campaign-budget` is billed to the advertiser
109
+ account as usual.
110
+
111
+ ## Logos
112
+
113
+ | File | Source | Changes |
114
+ |---|---|---|
115
+ | assets/logo.svg | Google's official Google Ads product logo, `https://www.gstatic.com/images/branding/productlogos/ads/v5/192px.svg` (Google's product-logo CDN; the same file `ads.google.com/home/` shows as the Google Ads icon) | none |
116
+ | assets/logo-mono.svg | the same file | removed the three `fill="#..."` colour attributes; the transparent bounding `rect fill="none"` and every shape are unchanged |
package/agentapp.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "app.google.ads",
3
3
  "name": "Google Ads",
4
- "version": "1.0.0",
4
+ "version": "1.0.1",
5
5
  "description": "Google Ads API (REST, v26): list the accounts a Google user can reach (including through manager accounts), report on account, campaign, ad group, ad, keyword and search term performance, run read-only GAQL queries, pause or enable campaigns and ad groups, change campaign budgets and add negative keywords. Writes that can spend money are marked destructive.",
6
6
  "tagline": "Report on Google Ads performance and manage campaigns, budgets and negative keywords",
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
  });
@@ -24322,7 +24322,7 @@ function registerTools(app) {
24322
24322
  var app = createApp({
24323
24323
  id: "app.google.ads",
24324
24324
  name: "Google Ads",
24325
- version: "1.0.0",
24325
+ version: "1.0.1",
24326
24326
  description: "Google Ads API (REST, v26): list the accounts a Google user can reach (including through manager accounts), report on account, campaign, ad group, ad, keyword and search term performance, run read-only GAQL queries, pause or enable campaigns and ad groups, change campaign budgets and add negative keywords. Writes that can spend money are marked destructive.",
24327
24327
  tagline: "Report on Google Ads performance and manage campaigns, budgets and negative keywords",
24328
24328
  author: { name: "Pablo López Torres", email: "pablolopeztorres@gmail.com" },
package/package.json CHANGED
@@ -1,11 +1,32 @@
1
1
  {
2
2
  "name": "@agentapps/app.google.ads",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
+ "description": "Report on Google Ads performance and manage campaigns, budgets and negative keywords",
5
+ "license": "MIT",
6
+ "author": "Pablo López Torres <pablolopeztorres@gmail.com>",
7
+ "keywords": [
8
+ "agent-apps",
9
+ "google",
10
+ "google-ads",
11
+ "adwords",
12
+ "ads",
13
+ "ppc",
14
+ "sem",
15
+ "marketing",
16
+ "advertising",
17
+ "campaigns",
18
+ "gaql"
19
+ ],
4
20
  "type": "module",
5
21
  "main": "./dist/app.js",
6
22
  "exports": {
7
23
  ".": "./dist/app.js",
8
24
  "./agentapp.json": "./agentapp.json",
9
25
  "./package.json": "./package.json"
26
+ },
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "https://github.com/agentapps/agentapps.git",
30
+ "directory": "apps/google-ads"
10
31
  }
11
32
  }