google-apis-cli 0.1.0

package/dist/src/auth.js

@@ -0,0 +1,172 @@
+// The only module with real handlers: OAuth login, status, logout, and the
+// tokenProvider the executor injects. One consent grants all 13 scopes; the
+// refresh token is persisted and getAccessToken() rehydrates transparently.
+import { readFileSync, rmSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+import { OAuth2Client } from 'google-auth-library';
+import { CONFIG_PATH, CONSENT_SCOPES, CREDENTIALS_PATH, getOAuthClient, readConfigFile, SCOPES, writeSecureJson, } from './config.js';
+const LOOPBACK_PORT = 4600; // fixed port; vmCODE forwards it for headless use
+function newClient(redirectUri) {
+    const { clientId, clientSecret } = getOAuthClient();
+    if (!clientId || !clientSecret) {
+        throw new Error('OAuth client not configured. Set GAPI_OAUTH_CLIENT_ID and GAPI_OAUTH_CLIENT_SECRET.');
+    }
+    return new OAuth2Client({ clientId, clientSecret, redirectUri });
+}
+function saveCredentials(tokens) {
+    writeSecureJson(CREDENTIALS_PATH, tokens);
+}
+export function loadCredentials() {
+    return JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf8'));
+}
+const AUTH_OPTS = { access_type: 'offline', prompt: 'consent', scope: CONSENT_SCOPES };
+// Decode a JWT payload without verifying (display only; it is our own token).
+function accountFromIdToken(idToken) {
+    try {
+        const payload = JSON.parse(Buffer.from(idToken.split('.')[1], 'base64url').toString());
+        return payload.email || payload.sub || null;
+    }
+    catch {
+        return null;
+    }
+}
+// The single-consent authorization URL for a client (offline + all scopes).
+export function authUrl(client) {
+    return client.generateAuthUrl(AUTH_OPTS);
+}
+// --manual: print the consent URL, read the pasted code, exchange it.
+export async function loginManual({ prompt, } = {}) {
+    const client = newClient('urn:ietf:wg:oauth:2.0:oob');
+    const url = authUrl(client);
+    console.error(`Open this URL, grant access, then paste the code:\n${url}\n`);
+    const ask = prompt || defaultPrompt;
+    const code = (await ask('code: ')).trim();
+    const { tokens } = await client.getToken(code);
+    saveCredentials(tokens);
+    return tokens;
+}
+// Guided setup: prompt the OAuth Desktop client id/secret and the optional Ads
+// login-customer-id (MCC), then merge into ~/.config/gapi/config.json (mode
+// 600). A blank answer keeps the current stored value. `prompt` is injectable
+// for tests. The secret field is masked at the prompt and goes straight to the
+// file. config.ts reads these back with precedence env → config → embedded.
+const SETUP_FIELDS = [
+    { key: 'oauth_client_id', label: 'OAuth client id', required: true, secret: false },
+    { key: 'oauth_client_secret', label: 'OAuth client secret', required: true, secret: true },
+    {
+        key: 'login-customer-id',
+        label: 'Ads login-customer-id (optional, MCC)',
+        required: false,
+        secret: false,
+    },
+];
+export async function configureAuth({ prompt, } = {}) {
+    const ask = prompt || defaultPrompt;
+    const cfg = readConfigFile();
+    for (const { key, label, required, secret } of SETUP_FIELDS) {
+        const cur = cfg[key];
+        const hint = cur != null ? ' [keep current]' : required ? '' : ' (blank to skip)';
+        const v = (await ask(`${label}${hint}: `, { secret })).trim();
+        if (v)
+            cfg[key] = v;
+        else if (required && cur == null)
+            throw new Error(`${label} is required`);
+    }
+    writeSecureJson(CONFIG_PATH, cfg);
+    return cfg;
+}
+// `secret: true` keeps the typed value off the screen. Node has no masking
+// option, so point readline's echo at a sink and print the question ourselves.
+// `terminal: true` is what makes this safe: it puts the tty in raw mode, so the
+// driver stops echoing too and the sink is the only writer left. Streams are
+// injectable so the masking has a test.
+export async function defaultPrompt(q, { secret = false, input = process.stdin, output = process.stderr, terminal, } = {}) {
+    if (secret)
+        output.write(q);
+    const rl = createInterface({
+        input,
+        output: secret ? new Writable({ write: (_c, _e, cb) => cb() }) : output,
+        terminal: secret ? true : terminal,
+    });
+    try {
+        return await rl.question(secret ? '' : q);
+    }
+    finally {
+        rl.close();
+        if (secret)
+            output.write('\n'); // the swallowed Enter never printed one
+    }
+}
+// Loopback: run a local server on LOOPBACK_PORT, open the consent URL, capture
+// the redirect's ?code=, exchange it, shut down. `handleRedirect` is exported
+// for tests (simulate GET /?code=... without a real browser).
+export async function loginLoopback({ openUrl, } = {}) {
+    const redirectUri = `http://127.0.0.1:${LOOPBACK_PORT}`;
+    const client = newClient(redirectUri);
+    const url = authUrl(client);
+    return new Promise((resolve, reject) => {
+        const server = createServer(async (req, res) => {
+            try {
+                const tokens = await handleRedirect(client, req.url || '', redirectUri);
+                res.end('gapi: authorized. You can close this tab.');
+                server.close();
+                resolve(tokens);
+            }
+            catch (e) {
+                res.statusCode = 400;
+                res.end(`gapi: ${e instanceof Error ? e.message : String(e)}`);
+                server.close();
+                reject(e);
+            }
+        });
+        server.listen(LOOPBACK_PORT, () => {
+            console.error(`Waiting for consent at ${redirectUri}\nOpen:\n${url}`);
+            (openUrl || (() => { }))(url);
+        });
+    });
+}
+// Extract ?code=, exchange for tokens, persist. Shared by loopback + tests.
+export async function handleRedirect(client, reqUrl, base) {
+    const code = new URL(reqUrl, base).searchParams.get('code');
+    if (!code)
+        throw new Error('no code in redirect');
+    const { tokens } = await client.getToken(code);
+    saveCredentials(tokens);
+    return tokens;
+}
+// tokenProvider injected into the executor: rehydrate the refresh token and
+// let google-auth-library refresh the access token before each call.
+export function makeTokenProvider({ client: injected, } = {}) {
+    let client = injected;
+    return async () => {
+        if (!client) {
+            const c = newClient();
+            c.setCredentials(loadCredentials());
+            c.on('tokens', (t) => {
+                const cur = loadCredentials();
+                saveCredentials({ ...cur, ...t });
+            });
+            client = c;
+        }
+        const { token } = await client.getAccessToken();
+        if (!token)
+            throw new Error('no access token; run `gapi auth login`');
+        return token;
+    };
+}
+export function status() {
+    const creds = loadCredentials();
+    const granted = (creds.scope || '').split(' ').filter(Boolean);
+    const byUrl = Object.fromEntries(Object.entries(SCOPES).map(([k, v]) => [v, k]));
+    return {
+        account: creds.id_token ? accountFromIdToken(creds.id_token) : null,
+        hasRefreshToken: Boolean(creds.refresh_token),
+        expiryDate: creds.expiry_date ? new Date(creds.expiry_date).toISOString() : null,
+        scopes: granted.map((u) => byUrl[u] || u),
+    };
+}
+export function logout() {
+    rmSync(CREDENTIALS_PATH, { force: true });
+}

package/dist/src/config.js

@@ -0,0 +1,89 @@
+// Static config: OAuth client, the 13 scopes, and file paths.
+// Client id/secret follow the public-CLI pattern (gcloud/gh/firebase-tools):
+// embedded, overridable by env for the operator's own Desktop OAuth client.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// Embedded Desktop-client credentials (gcloud/gh/firebase-tools pattern),
+// overridable. Precedence: env → ~/.config/gapi/config.json (via `gapi auth
+// setup`) → embedded. Filled once the operator registers the OAuth Desktop
+// client (open item: credential not yet provisioned).
+const EMBEDDED_CLIENT_ID = '';
+const EMBEDDED_CLIENT_SECRET = '';
+// Resolved lazily (not at import) so it reads the config file after CONFIG_PATH
+// is initialized, and picks up a fresh `gapi auth setup` in the same process.
+export function getOAuthClient() {
+    const cfg = readConfigFile();
+    return {
+        clientId: process.env.GAPI_OAUTH_CLIENT_ID || String(cfg.oauth_client_id ?? '') || EMBEDDED_CLIENT_ID,
+        clientSecret: process.env.GAPI_OAUTH_CLIENT_SECRET ||
+            String(cfg.oauth_client_secret ?? '') ||
+            EMBEDDED_CLIENT_SECRET,
+    };
+}
+// Short name -> full scope URL. Manifest rows reference the short names;
+// the schema self-check asserts every row scope is a key here.
+const A = 'https://www.googleapis.com/auth/';
+export const SCOPES = {
+    adwords: `${A}adwords`,
+    'tagmanager.readonly': `${A}tagmanager.readonly`,
+    'tagmanager.edit.containers': `${A}tagmanager.edit.containers`,
+    'tagmanager.edit.containerversions': `${A}tagmanager.edit.containerversions`,
+    'tagmanager.publish': `${A}tagmanager.publish`,
+    'tagmanager.delete.containers': `${A}tagmanager.delete.containers`,
+    'tagmanager.manage.users': `${A}tagmanager.manage.users`,
+    'tagmanager.manage.accounts': `${A}tagmanager.manage.accounts`,
+    'analytics.readonly': `${A}analytics.readonly`,
+    'analytics.edit': `${A}analytics.edit`,
+    'analytics.manage.users': `${A}analytics.manage.users`,
+    webmasters: `${A}webmasters`,
+    indexing: `${A}indexing`,
+};
+export const ALL_SCOPE_URLS = Object.values(SCOPES);
+// Identity scopes (non-sensitive) so `auth status` can show the authenticated
+// account: the id_token then carries the email. Separate from the 13 API
+// scopes, which stay the coverage/self-check set.
+export const IDENTITY_SCOPES = ['openid', 'email'];
+export const CONSENT_SCOPES = [...ALL_SCOPE_URLS, ...IDENTITY_SCOPES];
+export const CONFIG_DIR = join(homedir(), '.config', 'gapi');
+export const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials.json');
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+// Read ~/.config/gapi/config.json (OAuth client id/secret, Ads login-customer-id,
+// quota project).
+export function readConfigFile() {
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+// Write JSON under CONFIG_DIR readable only by the owner (dir 700, file 600).
+// Shared by the two things we persist: the config file and the credentials.
+export function writeSecureJson(path, data) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+// Precedence flag -> env -> config file. `flags` is the parsed argv values.
+// `cfg` defaults to the config file; injectable so precedence is unit-testable
+// without writing to ~/.config.
+export function resolveSetting(flags, { flag, env, key }, cfg = readConfigFile()) {
+    return flags?.[flag] ?? (env && process.env[env]) ?? cfg?.[key];
+}
+export const QUOTA_PROJECT_ENV = 'GOOGLE_CLOUD_PROJECT';
+// Google Ads sends login-customer-id (optional, MCC callers only) as an HTTP
+// header, not an OAuth scope, resolved flag -> env -> config file (header name
+// == flag == config key). developer-token was sunset 2026-09-09 (ignored by the
+// API; access is governed by the Cloud project), so it is not sent.
+const ADS_HEADERS = [
+    { name: 'login-customer-id', env: 'GOOGLE_ADS_LOGIN_CUSTOMER_ID' },
+];
+export function resolveAdsHeaders(flags, cfg = readConfigFile()) {
+    const out = {};
+    for (const { name, env } of ADS_HEADERS) {
+        const v = resolveSetting(flags, { flag: name, env, key: name }, cfg);
+        if (v != null)
+            out[name] = String(v);
+    }
+    return out;
+}

package/dist/src/manifest.js

@@ -0,0 +1,69 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Auto-discovery of API manifests. No central registry: a glob of
+// src/apis/*.js finds every surface, so a new API slice never edits a
+// shared file. Each manifest file default-exports:
+//   { api, baseUrl, resources: { <resource>: { <verb>: row } } }
+// row = { httpMethod, pathTemplate, scopes, requiredHeaders?, decoder?, listKey?, query? }
+import { readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SCOPES } from './config.js';
+const APIS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'apis');
+export async function loadManifests(dir = APIS_DIR) {
+    // Match dev (.ts) and published (.js); skip declaration files.
+    const files = readdirSync(dir).filter((f) => (f.endsWith('.ts') || f.endsWith('.js')) && !f.endsWith('.d.ts'));
+    const manifests = {};
+    for (const f of files) {
+        const mod = await import(__rewriteRelativeImportExtension(join(dir, f)));
+        const m = mod.default;
+        manifests[m.api] = m;
+    }
+    return manifests;
+}
+// Flatten one manifest row and inject baseUrl so the executor is self-contained.
+export function findRow(manifests, api, resource, verb) {
+    const m = manifests[api];
+    const row = m?.resources?.[resource]?.[verb];
+    if (!row)
+        return null;
+    return { ...row, baseUrl: m.baseUrl };
+}
+const REQUIRED = ['httpMethod', 'pathTemplate', 'scopes'];
+// Schema self-check. Throws with all problems found. Substitutes N handler tests.
+export function checkSchema(manifests) {
+    const errors = [];
+    const known = new Set(Object.keys(SCOPES));
+    for (const [api, m] of Object.entries(manifests)) {
+        if (!m.baseUrl)
+            errors.push(`${api}: missing baseUrl`);
+        for (const [resource, verbs] of Object.entries(m.resources || {})) {
+            for (const [verb, row] of Object.entries(verbs)) {
+                const at = `${api}.${resource}.${verb}`;
+                for (const field of REQUIRED) {
+                    if (row[field] == null)
+                        errors.push(`${at}: missing ${field}`);
+                }
+                // pathTemplate placeholders must be simple {name} tokens (params supply them).
+                if (typeof row.pathTemplate === 'string') {
+                    const bad = row.pathTemplate.match(/\{[^}]*[^\w}][^}]*\}/g);
+                    if (bad)
+                        errors.push(`${at}: bad path placeholder ${bad.join(',')}`);
+                }
+                for (const s of row.scopes || []) {
+                    if (!known.has(s))
+                        errors.push(`${at}: unknown scope "${s}"`);
+                }
+            }
+        }
+    }
+    if (errors.length)
+        throw new Error(`manifest schema errors:\n${errors.join('\n')}`);
+    return true;
+}

package/dist/src/rest.js

@@ -0,0 +1,90 @@
+import { RestError } from './types.js';
+const RESERVED = new Set(['json', 'raw', 'limit', 'body']);
+// The {name} placeholders a pathTemplate declares. Shared with the dispatcher
+// so path params are extracted in exactly one place.
+export function pathParams(pathTemplate) {
+    return [...pathTemplate.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+}
+// Fill {placeholders} in the path from params; return the used keys too.
+export function resolvePath(pathTemplate, params) {
+    const used = new Set();
+    const path = pathTemplate.replace(/\{(\w+)\}/g, (_, name) => {
+        if (params[name] == null)
+            throw new Error(`missing path param: ${name}`);
+        used.add(name);
+        return encodeURIComponent(String(params[name]));
+    });
+    return { path, used };
+}
+function buildUrl(baseUrl, pathTemplate, params) {
+    const { path, used } = resolvePath(pathTemplate, params);
+    const url = new URL(baseUrl + path);
+    // Leftover non-reserved params become query string, for every method: writes
+    // carry query params too (e.g. PATCH `updateMask`, list `pageSize`). The body
+    // is separate — RESERVED excludes it.
+    for (const [k, v] of Object.entries(params)) {
+        if (used.has(k) || RESERVED.has(k) || v == null)
+            continue;
+        url.searchParams.set(k, String(v));
+    }
+    return url;
+}
+// Merge a page's list array into acc under listKey. Returns the merged list.
+function mergeList(acc, page, listKey) {
+    const items = page?.[listKey];
+    if (Array.isArray(items))
+        return acc.concat(items);
+    return acc;
+}
+export async function execute(row, params, opts) {
+    const { tokenProvider, fetch: fetchImpl, quotaProject, extraHeaders = {} } = opts;
+    const method = row.httpMethod;
+    const headers = { Authorization: `Bearer ${await tokenProvider()}` };
+    if (quotaProject)
+        headers['x-goog-user-project'] = quotaProject;
+    for (const name of row.requiredHeaders || []) {
+        if (extraHeaders[name] == null)
+            throw new Error(`missing required header: ${name}`);
+    }
+    Object.assign(headers, extraHeaders);
+    const hasBody = method !== 'GET' && params.body != null;
+    if (hasBody)
+        headers['Content-Type'] = 'application/json';
+    const limit = params.limit != null ? Number(params.limit) : undefined;
+    let url = buildUrl(row.baseUrl, row.pathTemplate, params);
+    let last;
+    let merged = [];
+    let paged = false;
+    while (true) {
+        const res = await fetchImpl(url.toString(), {
+            method,
+            headers,
+            body: hasBody ? JSON.stringify(params.body) : undefined,
+        });
+        const text = await res.text();
+        const data = text ? JSON.parse(text) : {};
+        if (!res.ok) {
+            throw new RestError(data?.error?.message || `HTTP ${res.status}`, res.status, data);
+        }
+        last = data;
+        if (row.listKey) {
+            merged = mergeList(merged, data, row.listKey);
+            paged = true;
+            if (limit != null && merged.length >= limit) {
+                merged = merged.slice(0, limit);
+                break;
+            }
+            const next = data.nextPageToken;
+            if (!next)
+                break;
+            url = buildUrl(row.baseUrl, row.pathTemplate, { ...params, pageToken: next });
+            continue; // yagni: sequential paging; parallel prefetch if a surface ever needs it
+        }
+        break;
+    }
+    const raw = last;
+    let payload = paged ? { [row.listKey]: merged } : last;
+    if (row.decoder)
+        payload = row.decoder(paged ? merged : last, raw);
+    return { json: payload, raw };
+}

package/dist/src/types.js

@@ -0,0 +1,13 @@
+// Shared types for the two seams: the declarative manifest row and the
+// executor's injected dependencies. Kept in one file so an API slice only
+// imports types, never redefines the contract.
+// Carries the Google REST error status + body up to the CLI's catch.
+export class RestError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "google-apis-cli",
+  "version": "0.1.0",
+  "description": "One CLI (gapi) for Google Ads, GTM, GA4 (Admin+Data), Search Console, and Indexing. One login, all scopes, read+write.",
+  "type": "module",
+  "bin": {
+    "gapi": "dist/bin/gapi.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome check --write",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
+  },
+  "files": [
+    "dist/"
+  ],
+  "keywords": [
+    "google",
+    "google-ads",
+    "gtm",
+    "tag-manager",
+    "ga4",
+    "analytics",
+    "search-console",
+    "indexing",
+    "cli"
+  ],
+  "homepage": "https://github.com/realroboto/google-apis-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realroboto/google-apis-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/realroboto/google-apis-cli/issues"
+  },
+  "dependencies": {
+    "google-auth-library": "^11.0.2"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.13",
+    "@types/node": "^24.13.4",
+    "typescript": "^7.0.2"
+  },
+  "packageManager": "pnpm@12.3.4+sha512.961aa41fb077da3a04a441d9f8e15ebc0c96da8ef710b2eb67bf9ee7cb0610eabd48f1fd85f51cffe73846785fa0f87c56a3a872a1d893f8446741b5cce45457"
+}