google-apis-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 google-apis-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# google-apis-cli (`gapi`)
+
+`gapi` is one CLI for Google Ads, GTM, GA4 (Admin + Data), Search Console, and Indexing.
+
+- One login. One refresh token. All scopes. Read and write.
+- One runtime dependency: `google-auth-library` (Google). Nothing third-party.
+- All network calls use native `fetch`.
+- TypeScript 7 (strict), Node 24. Node runs `.ts` directly (type-stripping) — no build step in dev. Biome for lint + format. pnpm 12 (corepack-pinned) for package management.
+- It replaces the 4 fragmented Google MCPs in vmCODE.
+
+Command shape: `gapi <api> <resource> <verb> [--json|--raw]`
+
+## Install
+
+```
+npm i -g google-apis-cli    # installs the `gapi` bin
+```
+
+Needs **Node ≥ 24** — `gapi` ships as TypeScript and runs on Node's native type-stripping, so there is no build step and no bundle.
+
+## Start here
+
+```
+gapi auth setup   # store your own OAuth Desktop client (id + secret)
+gapi auth login   # one consent, all 13 scopes
+gapi auth status  # account, refresh token, granted scopes
+```
+
+First run, or a console step fails? **[docs/SETUP.md](docs/SETUP.md)** walks the five steps and
+the traps in each. `gapi` is multi-tenant: every operator brings their own Cloud project.
+
+## OAuth App Verification
+
+`gapi` asks for sensitive scopes (`analytics.manage.users`, `tagmanager.manage.*`, `adwords`, `webmasters`).
+
+- **Testing mode** (default) works for all commands, but the refresh token expires every ~7 days — re-run `gapi auth login` when it does.
+- **Production** removes that expiry, but Google requires **OAuth App Verification** first: a privacy-policy URL, a homepage, and a reviewed consent screen. Review timeline is not guaranteed.
+
+Testing mode is enough to use the CLI; Production is the no-expiry target. Until verification passes, stay in Testing and re-auth on the ~7-day cadence.
+
+## Flow
+
+The project has 3 parts. A call moves through them in order.
+
+| Part | File | Function |
+|---|---|---|
+| **auth** | `src/auth.ts` | `gapi auth login` gets one OAuth consent. It stores the refresh token in `~/.config/gapi/credentials.json` (mode 600). `getAccessToken()` refreshes the access token. Only part with real handlers. |
+| **manifest** | `src/apis/*.ts` | Each API is data, not code: `resource → verb → { httpMethod, pathTemplate, scopes, requiredHeaders?, decoder?, listKey?, query? }`. One file per surface. A glob finds them. No central registry. Row/seam types live in `src/types.ts`. |
+| **executor seam** | `src/rest.ts` | `execute(manifestRow, params, { tokenProvider, fetch })` builds the URL, adds headers, follows pagination, applies the `decoder`, and formats `--json`/`--raw`. All network calls pass here. It is the one test seam. |
+
+`bin/gapi.ts` parses argv. The dispatch, `--help`, and URL resolution all come from the manifests.
+
+## Where to look
+
+| For | Read |
+|---|---|
+| Onboarding a Google account: consent, Ads access level, customer IDs, runtime errors | **[docs/SETUP.md](docs/SETUP.md)** |
+| What the CLI does, decisions, scopes, endpoints, risks | **[docs/SPEC.md](docs/SPEC.md)** — behavior source of truth |
+| How work is tracked (issues, blocking edges) | [docs/agents/issue-tracker.md](docs/agents/issue-tracker.md) |
+| Triage labels | [docs/agents/triage-labels.md](docs/agents/triage-labels.md) |
+| Domain vocabulary (CONTEXT.md, ADRs) | [docs/agents/domain.md](docs/agents/domain.md) |
+| Real commands and scripts | `package.json`, `gapi --help` |
+
+## Add an API or a resource
+
+- New resource = one manifest row.
+- New API = one new `src/apis/<api>.ts` file (default-export `satisfies Manifest`). The glob finds it. No shared file changes.
+- Accept rule — **coverage-oracle**: the self-check fails if the manifest does not cover 100% of the discovery-doc resources.
+- Test through the executor seam. Inject a fake `tokenProvider` and `fetch`. Use no real network.
+- Before commit: `pnpm typecheck` (tsc --noEmit) · `pnpm lint` (biome) · `pnpm test`.
+- Fix lint by fixing the code it flags — never `biome --unsafe`, never disable a rule to clear it.
+
+## Agent skills
+
+| Topic | Rule | Detail |
+|---|---|---|
+| Issue tracker | GitHub issues via `gh` | [docs/agents/issue-tracker.md](docs/agents/issue-tracker.md) |
+| Triage labels | 5 canonical labels (string == role) | [docs/agents/triage-labels.md](docs/agents/triage-labels.md) |
+| Domain docs | Single-context (`CONTEXT.md` + `docs/adr/`) | [docs/agents/domain.md](docs/agents/domain.md) |

package/dist/bin/gapi.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// argv -> dispatch. The command tree, --help, and URL resolution all derive
+// from the auto-discovered manifests (single source). Two branches step outside
+// generic dispatch: `auth` (real handlers) and the `ads gaql` sugar (story 31,
+// query positional + --customer/--stream). Ads adds the optional
+// login-customer-id HTTP header (resolveAdsHeaders) on `ads` calls only.
+import { parseArgs } from 'node:util';
+import { gaqlBody } from '../src/apis/ads.js';
+import { configureAuth, loginLoopback, loginManual, logout, makeTokenProvider, status, } from '../src/auth.js';
+import { QUOTA_PROJECT_ENV, resolveAdsHeaders, resolveSetting } from '../src/config.js';
+import { checkSchema, findRow, loadManifests } from '../src/manifest.js';
+import { execute, pathParams } from '../src/rest.js';
+const GLOBAL_OPTIONS = {
+    json: { type: 'boolean' },
+    raw: { type: 'boolean' },
+    help: { type: 'boolean' },
+    limit: { type: 'string' },
+    body: { type: 'string' },
+    project: { type: 'string' },
+    // Ads (see `ads gaql` sugar + resolveAdsHeaders): login-customer-id header,
+    // target account, and search/searchStream toggle.
+    'login-customer-id': { type: 'string' },
+    customer: { type: 'string' },
+    stream: { type: 'boolean' },
+};
+function printTree(manifests) {
+    console.log('gapi <api> <resource> <verb> [--json|--raw]\n');
+    console.log('auth  setup | login [--manual] | status | logout\n');
+    for (const [api, m] of Object.entries(manifests).sort()) {
+        console.log(api);
+        for (const [resource, verbs] of Object.entries(m.resources).sort()) {
+            console.log(`  ${resource}  ${Object.keys(verbs).sort().join(' | ')}`);
+        }
+    }
+}
+async function runAuth(sub, values) {
+    if (sub === 'login') {
+        const tokens = values.manual ? await loginManual() : await loginLoopback();
+        console.error('gapi: authorized (' +
+            (tokens.refresh_token ? 'refresh token stored' : 'no refresh token') +
+            ')');
+        return;
+    }
+    if (sub === 'setup') {
+        await configureAuth();
+        return console.error('gapi: saved to ~/.config/gapi/config.json');
+    }
+    if (sub === 'status')
+        return console.log(JSON.stringify(status(), null, 2));
+    if (sub === 'logout') {
+        logout();
+        return console.error('gapi: credentials removed');
+    }
+    throw new Error(`unknown auth command: ${sub}`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const manifests = await loadManifests();
+    checkSchema(manifests);
+    if (argv.length === 0 || (argv[0] === '--help' && argv.length === 1)) {
+        printTree(manifests);
+        return;
+    }
+    const [api, ...rest] = argv;
+    if (api === 'auth') {
+        const { values, positionals } = parseArgs({
+            args: rest,
+            options: { manual: { type: 'boolean' }, help: { type: 'boolean' } },
+            allowPositionals: true,
+        });
+        return runAuth(positionals[0], values);
+    }
+    if (!manifests[api])
+        throw new Error(`unknown api: ${api} (try \`gapi --help\`)`);
+    const { values, positionals } = parseArgs({
+        args: rest,
+        options: GLOBAL_OPTIONS,
+        allowPositionals: true,
+    });
+    const [resource, verb] = positionals;
+    if (values.help || !resource || !verb) {
+        printTree({ [api]: manifests[api] });
+        return;
+    }
+    // `ads gaql` is the one sugar beyond generic dispatch (story 31): the query is
+    // a positional, --stream picks searchStream, --customer fills the path param.
+    const isGaql = api === 'ads' && resource === 'gaql';
+    const row = isGaql
+        ? findRow(manifests, api, 'gaql', values.stream ? 'searchStream' : 'search')
+        : findRow(manifests, api, resource, verb);
+    if (!row)
+        throw new Error(`unknown command: ${api} ${resource} ${verb}`);
+    const params = {};
+    if (isGaql) {
+        if (!values.customer)
+            throw new Error('ads gaql requires --customer <id>');
+        params.customer = values.customer;
+        params.body = gaqlBody(verb); // `verb` is the GAQL query string here
+    }
+    else {
+        // params = positional path args after verb, then row.query params as further
+        // positionals, plus body/limit from flags.
+        const pp = pathParams(row.pathTemplate);
+        pp.forEach((name, i) => {
+            if (positionals[2 + i] != null)
+                params[name] = positionals[2 + i];
+        });
+        (row.query ?? []).forEach((name, i) => {
+            const v = positionals[2 + pp.length + i];
+            if (v != null)
+                params[name] = v;
+        });
+    }
+    if (values.limit != null)
+        params.limit = values.limit;
+    if (values.body != null)
+        params.body = JSON.parse(values.body);
+    const quotaProject = resolveSetting(values, {
+        flag: 'project',
+        env: QUOTA_PROJECT_ENV,
+        key: 'project',
+    });
+    // Only Ads calls carry the optional login-customer-id header, so other APIs
+    // never send an Ads-specific header.
+    const extraHeaders = api === 'ads' ? resolveAdsHeaders(values) : undefined;
+    const { json, raw } = await execute(row, params, {
+        tokenProvider: makeTokenProvider(),
+        fetch,
+        quotaProject,
+        extraHeaders,
+    });
+    console.log(JSON.stringify(values.raw ? raw : json, null, 2));
+}
+main().catch((e) => {
+    const detail = e.body ? `\n${JSON.stringify(e.body.error ?? e.body, null, 2)}` : '';
+    console.error(`gapi: ${e.message}${detail}`);
+    process.exit(1);
+});

package/dist/src/apis/ads.js

@@ -0,0 +1,54 @@
+const ADS = ['adwords'];
+const C = '/v25/customers/{customer}';
+// Build the search-request body from a bare GAQL string (story 31). Trivial by
+// design — kept a named pure function so bin/gapi.ts's `gapi ads gaql "<q>"`
+// sugar has one tested seam.
+export const gaqlBody = (query) => ({ query });
+// searchStream → JSON array of {results, ...} chunks; concat into one list.
+const streamConcat = (data) => Array.isArray(data) ? data.flatMap((c) => c?.results ?? []) : data;
+// Every :mutate service is the same shape: POST customers/{}/{collection}:mutate
+// with a {operations:[...]} body. Only the collection segment varies.
+const mutate = (collection) => ({
+    mutate: {
+        httpMethod: 'POST',
+        pathTemplate: `${C}/${collection}:mutate`,
+        scopes: ADS,
+    },
+});
+export default {
+    api: 'ads',
+    baseUrl: 'https://googleads.googleapis.com',
+    resources: {
+        customers: {
+            // Empty body; returns { resourceNames: ["customers/123", ...] }. Ignores
+            // login-customer-id (direct-access accounts only).
+            'list-accessible': {
+                httpMethod: 'GET',
+                pathTemplate: '/v25/customers:listAccessibleCustomers',
+                scopes: ADS,
+            },
+        },
+        gaql: {
+            // Body-paged: {query, pageToken}. Raw {results, nextPageToken} out.
+            search: {
+                httpMethod: 'POST',
+                pathTemplate: `${C}/googleAds:search`,
+                scopes: ADS,
+            },
+            // Streams the whole result set in one response (array of chunks).
+            searchStream: {
+                httpMethod: 'POST',
+                pathTemplate: `${C}/googleAds:searchStream`,
+                scopes: ADS,
+                decoder: streamConcat,
+            },
+        },
+        // Core write surface (:mutate). Body: {operations:[{create|update|remove}]}.
+        campaigns: mutate('campaigns'),
+        'campaign-budgets': mutate('campaignBudgets'),
+        'campaign-criteria': mutate('campaignCriteria'),
+        'ad-groups': mutate('adGroups'),
+        'ad-group-ads': mutate('adGroupAds'),
+        'ad-group-criteria': mutate('adGroupCriteria'),
+    },
+};

package/dist/src/apis/ga4-admin-v1alpha.js

@@ -0,0 +1,280 @@
+const RO = ['analytics.readonly'];
+const RW = ['analytics.edit'];
+const USERS = ['analytics.manage.users'];
+export default {
+    api: 'ga4-admin-alpha',
+    baseUrl: 'https://analyticsadmin.googleapis.com',
+    resources: {
+        // --- access bindings (users/permissions), gated by analytics.manage.users ---
+        'access-bindings': {
+            list: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings',
+                scopes: USERS,
+                listKey: 'accessBindings',
+            },
+            get: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings/{accessBinding}',
+                scopes: USERS,
+            },
+            // The names to fetch are a trailing positional → ?names= (query seam).
+            'batch-get': {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings:batchGet',
+                scopes: USERS,
+                query: ['names'],
+            },
+            create: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings',
+                scopes: USERS,
+            },
+            patch: {
+                httpMethod: 'PATCH',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings/{accessBinding}',
+                scopes: USERS,
+            },
+            delete: {
+                httpMethod: 'DELETE',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings/{accessBinding}',
+                scopes: USERS,
+            },
+            'batch-create': {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings:batchCreate',
+                scopes: USERS,
+            },
+            'batch-update': {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings:batchUpdate',
+                scopes: USERS,
+            },
+            'batch-delete': {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/accessBindings:batchDelete',
+                scopes: USERS,
+            },
+        },
+        'account-access-bindings': {
+            list: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings',
+                scopes: USERS,
+                listKey: 'accessBindings',
+            },
+            get: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings/{accessBinding}',
+                scopes: USERS,
+            },
+            // The names to fetch are a trailing positional → ?names= (query seam).
+            'batch-get': {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings:batchGet',
+                scopes: USERS,
+                query: ['names'],
+            },
+            create: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings',
+                scopes: USERS,
+            },
+            patch: {
+                httpMethod: 'PATCH',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings/{accessBinding}',
+                scopes: USERS,
+            },
+            delete: {
+                httpMethod: 'DELETE',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings/{accessBinding}',
+                scopes: USERS,
+            },
+            'batch-create': {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings:batchCreate',
+                scopes: USERS,
+            },
+            'batch-update': {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings:batchUpdate',
+                scopes: USERS,
+            },
+            'batch-delete': {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/accounts/{account}/accessBindings:batchDelete',
+                scopes: USERS,
+            },
+        },
+        // --- audiences (no delete: archived via :archive) ---
+        audiences: {
+            list: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/audiences',
+                scopes: RO,
+                listKey: 'audiences',
+            },
+            get: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/audiences/{audience}',
+                scopes: RO,
+            },
+            create: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/audiences',
+                scopes: RW,
+            },
+            patch: {
+                httpMethod: 'PATCH',
+                pathTemplate: '/v1alpha/properties/{property}/audiences/{audience}',
+                scopes: RW,
+            },
+            archive: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/audiences/{audience}:archive',
+                scopes: RW,
+            },
+        },
+        'calculated-metrics': {
+            list: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/calculatedMetrics',
+                scopes: RO,
+                listKey: 'calculatedMetrics',
+            },
+            get: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/calculatedMetrics/{calculatedMetric}',
+                scopes: RO,
+            },
+            create: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/calculatedMetrics',
+                scopes: RW,
+            },
+            patch: {
+                httpMethod: 'PATCH',
+                pathTemplate: '/v1alpha/properties/{property}/calculatedMetrics/{calculatedMetric}',
+                scopes: RW,
+            },
+            delete: {
+                httpMethod: 'DELETE',
+                pathTemplate: '/v1alpha/properties/{property}/calculatedMetrics/{calculatedMetric}',
+                scopes: RW,
+            },
+        },
+        'channel-groups': {
+            list: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/channelGroups',
+                scopes: RO,
+                listKey: 'channelGroups',
+            },
+            get: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/channelGroups/{channelGroup}',
+                scopes: RO,
+            },
+            create: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/channelGroups',
+                scopes: RW,
+            },
+            patch: {
+                httpMethod: 'PATCH',
+                pathTemplate: '/v1alpha/properties/{property}/channelGroups/{channelGroup}',
+                scopes: RW,
+            },
+            delete: {
+                httpMethod: 'DELETE',
+                pathTemplate: '/v1alpha/properties/{property}/channelGroups/{channelGroup}',
+                scopes: RW,
+            },
+        },
+        // --- subproperties & rollups ---
+        'rollup-properties': {
+            create: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties:createRollupProperty',
+                scopes: RW,
+            },
+        },
+        subproperties: {
+            provision: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties:provisionSubproperty',
+                scopes: RW,
+            },
+        },
+        'rollup-property-source-links': {
+            list: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/rollupPropertySourceLinks',
+                scopes: RO,
+                listKey: 'rollupPropertySourceLinks',
+            },
+            get: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/rollupPropertySourceLinks/{rollupPropertySourceLink}',
+                scopes: RO,
+            },
+            create: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/rollupPropertySourceLinks',
+                scopes: RW,
+            },
+            delete: {
+                httpMethod: 'DELETE',
+                pathTemplate: '/v1alpha/properties/{property}/rollupPropertySourceLinks/{rollupPropertySourceLink}',
+                scopes: RW,
+            },
+        },
+        'subproperty-event-filters': {
+            list: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/subpropertyEventFilters',
+                scopes: RO,
+                listKey: 'subpropertyEventFilters',
+            },
+            get: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/subpropertyEventFilters/{subpropertyEventFilter}',
+                scopes: RO,
+            },
+            create: {
+                httpMethod: 'POST',
+                pathTemplate: '/v1alpha/properties/{property}/subpropertyEventFilters',
+                scopes: RW,
+            },
+            patch: {
+                httpMethod: 'PATCH',
+                pathTemplate: '/v1alpha/properties/{property}/subpropertyEventFilters/{subpropertyEventFilter}',
+                scopes: RW,
+            },
+            delete: {
+                httpMethod: 'DELETE',
+                pathTemplate: '/v1alpha/properties/{property}/subpropertyEventFilters/{subpropertyEventFilter}',
+                scopes: RW,
+            },
+        },
+        // subproperty sync configs are auto-created → list/get/patch only.
+        'subproperty-sync-configs': {
+            list: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/subpropertySyncConfigs',
+                scopes: RO,
+                listKey: 'subpropertySyncConfigs',
+            },
+            get: {
+                httpMethod: 'GET',
+                pathTemplate: '/v1alpha/properties/{property}/subpropertySyncConfigs/{subpropertySyncConfig}',
+                scopes: RO,
+            },
+            patch: {
+                httpMethod: 'PATCH',
+                pathTemplate: '/v1alpha/properties/{property}/subpropertySyncConfigs/{subpropertySyncConfig}',
+                scopes: RW,
+            },
+        },
+    },
+};