google-apis-cli 0.2.0 → 0.4.0

package/README.md

@@ -1,23 +1,23 @@
 # google-apis-cli (`gapi`)
 
-`gapi` is one CLI for 47 Google API entries, built from Google's discovery documents at runtime:
+`gapi` is one CLI for 49 Google API entries, built from Google's discovery documents at runtime:
 
 - Google Ads v26, GA4 Admin (v1beta, v1alpha), GA4 Data (v1beta, v1alpha), Search Console, Tag Manager, Indexing
 - Merchant API (13 v1 sub-APIs + Reviews v1alpha), Business Profile (7 v1 APIs + v4)
 - Search Ads 360 (Reporting v0, legacy v2), Campaign Manager 360 v5, Display & Video 360 v4, Bid Manager v2
 - YouTube Data v3, YouTube Analytics v2, YouTube Reporting v1
 - PageSpeed Insights v5, CrUX v1 (API key)
-- BigQuery Data Transfer v1, Data Manager v1, Gmail Postmaster Tools v2, Site Verification v1, Sheets v4, Places (New) v1, Web Risk v1
+- BigQuery v2, BigQuery Data Transfer v1, Data Manager v1, Gmail Postmaster Tools v2, Site Verification v1, Sheets v4, Places (New) v1, Web Risk v1, Cloud Quotas v1
 
 `gapi --help` lists the entry names; [skills/gapi/reference/index.md](skills/gapi/reference/index.md) gives title, version, method count and auth per entry.
 
 - One login. One refresh token. Every scope the entries use (computed from the documents). 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 (pinned via `packageManager`) for package management.
+- TypeScript 7 (strict), Node 26. Node runs `.ts` directly (type-stripping) — no build step in dev. Biome for lint + format. pnpm 12 (pinned via `packageManager`) for package management.
 - It replaces the 4 fragmented Google MCPs in vmCODE.
 
-Command shape: `gapi <api> <resource>… <method> [--params '<json>'] [--body '<json>'] [--upload <file> [--upload-content-type <type>] [--upload-protocol media|multipart|resumable]] [--output <file>] [--page-all [--page-limit <n>]] [--dry-run]`. `gapi <api> [<resource>…]` lists a level (the api level also lists helpers); `… <method> --help` shows method help. `gapi <api> +<helper> … [--dry-run] [--project <id>] [--api-key <key>] [<entry header flag>]` runs a hand command, e.g. `gapi ads +gaql "<query>" --customer <id> [--stream]`, `gapi indexing +publishBatch <file>`. `gapi schema <api> <resource>[.<sub>…].<method> | <SchemaName> [--resolve-refs]` prints a method shape or a schema as JSON. `gapi discovery refresh [<api>…]` refetches discovery documents now; `gapi discovery path` prints the cache dir. `gapi schema --help`, `gapi discovery --help` and `gapi auth [<sub>] --help` print that command's usage and run nothing.
+Command shape: `gapi <api> <resource>… <method> [--params '<json>'] [--body '<json>'] [--upload <file> [--upload-content-type <type>] [--upload-protocol media|multipart|resumable]] [--output <file>] [--page-all [--page-limit <n>]] [--cache <age>] [--dry-run]`. `gapi <api> [<resource>…]` lists a level (the api level also lists helpers); `… <method> --help` shows method help. `gapi <api> +<helper> … [--dry-run] [--cache <age>] [--project <id>] [--api-key <key>] [<entry header flag>]` runs a hand command, e.g. `gapi ads +gaql "<query>" --customer <id> [--stream]`, `gapi indexing +publishBatch <file>`, `gapi bigquery +query "<sql>" --project <id> [--max-bytes <n>] [--estimate]`. `gapi search <words…>` lists at most 20 methods across all API entries that match the words (command, marks, HTTP method, first sentence of the description). `gapi fields ads|sa360 <words…>` lists at most 20 GAQL field names from the discovery document (no request); `gapi fields ga4-data <words…> --property <id>` ranks GA4 dimensions and metrics from one `getMetadata` request; `--cache` exits 3. `gapi schema <api> <resource>[.<sub>…].<method> | <SchemaName> [--resolve-refs]` prints a method shape or a schema as JSON; `--find <word>` prints instead only the field paths of the expanded schema (a method: `request.…` and `response.…`) whose path or printed description (first sentence, max 100 chars) contains the word. `gapi entities sync [<api>…] [--page-limit <n>]` stores the operator's own accounts, properties and sites (entity source overlays) in a local index; `gapi entities find <words…> [--api <api>]` prints at most 20 matching entities offline, one tab-separated line each (API, kind, ID, name, parent, domain, sync date). `gapi discovery refresh [<api>…]` refetches discovery documents now; `gapi discovery path` prints the cache dir. `gapi search --help`, `gapi fields --help`, `gapi schema --help`, `gapi discovery --help` and `gapi auth [<sub>] --help` print that command's usage and run nothing.
 
 ## Install
 
@@ -25,7 +25,7 @@ Command shape: `gapi <api> <resource>… <method> [--params '<json>'] [--body '<
 npm i -g google-apis-cli    # installs the `gapi` bin
 ```
 
-Needs **Node ≥ 24**. The package ships `dist/` (plain `tsc` output, built at publish, no bundle); in the repo, Node runs the `.ts` sources directly.
+Needs **Node ≥ 26**. The package ships `dist/` (plain `tsc` output, built at publish, no bundle); in the repo, Node runs the `.ts` sources directly.
 
 ## Start here
 
@@ -36,7 +36,7 @@ gapi auth status  # account, refresh token, API key, granted and missing scopes
 ```
 
 First run, or a console step fails? **[docs/SETUP.md](docs/SETUP.md)** walks the steps (services,
-API key, Business Profile access, consent, Merchant registration) and the traps in each. `gapi` is multi-tenant: every operator brings their own Cloud project.
+API key, Business Profile access, consent, Merchant registration, client access) and the traps in each. `gapi` is multi-tenant: every operator brings their own Cloud project.
 
 ## OAuth App Verification
 
@@ -54,22 +54,26 @@ A call moves through these parts in order.
 
 | Part | File | Function |
 |---|---|---|
-| **run** | `src/run.ts` | `run(argv, io)`: strict argv parse, routing (`--help`, `auth`, `schema`, `discovery`, `<api> …`), `GapiError` → exit code. `bin/gapi.ts` passes process io. |
+| **run** | `src/run.ts` | `run(argv, io)`: strict argv parse, routing (`--help`, `auth`, `search`, `schema`, `discovery`, `<api> …`), `GapiError` → exit code. `bin/gapi.ts` passes process io. One JSON writer for responses, `--dry-run` and `auth status`: compact lines off a terminal, 2-space indent when `io.stdout.isTTY` (#200 D2). |
 | **Catalog** | `src/catalog.ts` | API entries (`src/apis/*.ts`, glob, no registry) → `ApiModel`. Discovery entries: document cached 24 h. |
 | **Planner** | `src/plan.ts` | `plan(model, words \| methodId, input, settings)` → `CallPlan`. Pure. Every `--params`/`--body` rule; validation fails exit 3 before network. |
-| **Transport** | `src/transport.ts` | `send(plan, { fetch, authorize, out })`. `authorize` adds the credential per request; non-2xx → exit 1; 403 `ACCESS_TOKEN_SCOPE_INSUFFICIENT` → exit 2. `--page-all` follows `nextPageToken`, sending `pageToken` in the query or in the request body (methods whose request schema has `pageToken`): one JSON line per page, max `--page-limit` (default 10). `--upload` streams a file to `rootUrl` + `upload/` (media, multipart, or resumable in 8 MiB chunks); `--output` writes the `alt=media` body to a file, from `rootUrl` + `download/` when the method sets `useMediaDownloadService`. `--dry-run` prints the plan instead. |
-| **Renderers** | `src/render.ts` | Root help, level listing, method help, `schemaView` (`$ref` expansion, cycle guard), and the skill reference Markdown that `pnpm gen:skill` writes to `skills/gapi/reference/` (generated; do not edit by hand). |
-| **Credentials** | `src/credentials.ts` | Only reader and writer of `config.json` and `credentials.json` (mode 600) in the config dir (`GAPI_CONFIG_DIR` or `~/.config/gapi`). `settings`: `--project`, `--api-key` and entry header flags, each flag → env → config. `authorize`: OAuth Bearer (refreshed token saved) or `X-Goog-Api-Key`. `login`, `status` (with `missing`), `logout` (revoke, then delete), `setup`. |
+| **Transport** | `src/transport.ts` + `src/transport/{upload,download,batch}.ts` | `receive(plan, { fetch, authorize, sleep, signal? })`: async iterator of decoded responses (#200 D3); `decode(data, step)` reshapes each (`step` = the request that got it), `undefined` yields nothing. `send(plan, { …, out })` writes one compact JSON line per response by iterating it. `signal` (`AbortSignal`) sets a deadline; an abort is never retried. `authorize` adds the credential per request; GET/HEAD/PUT/DELETE, `reads` POSTs and helper plans marked `retry` (`+query`: idempotent `requestId`) retry 408/429/5xx and network errors (max 3, backoff with jitter); non-2xx or network failure → exit 1; 403 `ACCESS_TOKEN_SCOPE_INSUFFICIENT` (also in an array body or a batch part) → exit 2. A `pages` plan follows its follow rule; the Planner's `--page-all` rule (AIP-158) follows `nextPageToken`, sending `pageToken` in the query or in the request body (methods whose request schema has `pageToken`): one JSON line per page, max `--page-limit` (default 10) yielded pages. `--upload` streams a file to `rootUrl` + `upload/` (media, multipart, or resumable in 8 MiB chunks, resumed from the session's `Range` after a 5xx or network error); `--output` writes the `alt=media` body to a file, from `rootUrl` + `download/` when the method sets `useMediaDownloadService`. `+publishBatch` sends `multipart/mixed` to the document's `batchPath`. `--dry-run` prints the plan instead. |
+| **Search** | `src/search.ts` | `search(models, query)`: SQLite FTS5 index (`node:sqlite`) built in memory per call from every loaded ApiModel, nothing on disk. Words split at camelCase, `-`, `_`, `.`; query tokens are letters and digits only, double-quoted, joined with `OR`; best 20 by `bm25`. `rankFields(fields, query)` (#200 D7): same split and match over `gaqlFields(model)` (resource, metrics, segments schemas → snake_case GAQL names) or `ga4Fields(metadata)`; names and first description sentences in two FTS5 tables, since bm25 normalizes by row length; a field whose last name part equals the query comes first. |
+| **Renderers** | `src/render.ts` | Root help, level listing, method help, search hits, `schemaView` (`$ref` expansion, cycle guard), `schemaFind` (`--find` field paths), and the skill reference Markdown that `pnpm gen:skill` writes to `skills/gapi/reference/` (generated; do not edit by hand). |
+| **Response cache** | `src/responses.ts` | `--cache <age>` (1s–7d, opt-in per call, [ADR 0001](docs/adr/0001-response-cache.md)): `run` checks eligibility before any network call (no `nocache` entry, single call or pages, `GET` or a `reads` POST), then answers a hit from `responses/` in the config dir (dir 700, files 600) with no fetch, or stores a miss after a successful send. Key holds `identity(auth)` from Credentials (refresh-token hash), so accounts never share entries. `auth login` and `auth logout` delete `responses/`. |
+| **Entities** | `src/entities.ts` | `gapi entities sync` / `find` ([ADR 0002](docs/adr/0002-entities-store.md)): only reader and writer of `entities.db` in the config dir (mode 600; another schema version is dropped). `sync` runs each entry's `entities` sources through `receive` (`--page-limit` pages per list), then replaces that API's rows in one transaction; a failed API keeps its rows, exit 1. `find`: trigram FTS5, bm25, best 20; a term under 3 characters exits 3. Rows hold `identity(auth)`; every run deletes rows older than 7 days; `auth login` and `auth logout` delete the file. |
+| **Credentials** | `src/credentials.ts` | Only reader and writer of `config.json` and `credentials.json` (mode 600) in the config dir (`GAPI_CONFIG_DIR` or `~/.config/gapi`; it also holds the discovery `cache/`, `responses/` and `entities.db`). `settings`: `--project`, `--api-key` and entry header flags, each flag → env → config. `authorize`: OAuth Bearer (refreshed token saved) or `X-Goog-Api-Key`. `login`, `status` (with `missing`), `logout` (revoke, then delete), `setup`. |
 
-CLI tests call `run` in-process (`test/run.test.ts`, `test/helpers/io.ts`). Terms: [GLOSSARY.md](GLOSSARY.md).
+CLI tests call `run` in-process (`test/run.test.ts`, `test/helpers/io.ts`). `test/skill.test.ts` runs every `gapi … --dry-run` line of SKILL.md and recipes.md against the shipped entries; a new example method needs its entry in the pruned docs of `test/fixtures/skill/`. Terms: [GLOSSARY.md](GLOSSARY.md).
 
 ## Where to look
 
 | For | Read |
 |---|---|
-| Onboarding a Google account: services to enable, Ads access level, Business Profile access, API key, consent, Merchant registration, customer IDs, runtime errors | **[docs/SETUP.md](docs/SETUP.md)** |
-| Using the CLI as an agent: grammar, `--params`, `schema`, `--dry-run`, paging, media, helpers, exit codes, marks | [skills/gapi/SKILL.md](skills/gapi/SKILL.md) + generated [reference](skills/gapi/reference/index.md) |
+| Onboarding a Google account: services to enable, Ads access level, Business Profile access, API key, consent, Merchant registration, client access, customer IDs, runtime errors | **[docs/SETUP.md](docs/SETUP.md)** |
+| Using the CLI as an agent: grammar, `--params`, `schema`, `--dry-run`, paging, media, helpers, exit codes, marks | [skills/gapi/SKILL.md](skills/gapi/SKILL.md) + [recipes](skills/gapi/recipes.md) + generated [reference](skills/gapi/reference/index.md) |
 | What the CLI does, decisions, scopes, endpoints, risks | **[docs/SPEC.md](docs/SPEC.md)** — behavior source of truth |
+| Releasing a version (tag push → npm via trusted publishing; changes in [CHANGELOG.md](CHANGELOG.md)) | [docs/runbook.md](docs/runbook.md) item 4 |
 | 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 (GLOSSARY.md, ADRs) | [docs/agents/domain.md](docs/agents/domain.md) |
@@ -77,7 +81,8 @@ CLI tests call `run` in-process (`test/run.test.ts`, `test/helpers/io.ts`). Term
 
 ## Add an API or a resource
 
-- New API = one new `src/apis/<api>.ts` file that default-exports an API entry (`satisfies ApiEntry`): the discovery URL plus overlays (`retired`, `deprecated`, `paid`, `headers`, `helpers`). The discovery document gives every resource and method. The glob finds the file; `api` must equal the file name, or the Catalog fails to load. No shared file changes.
+- New API = one new `src/apis/<api>.ts` file that default-exports an API entry (`satisfies ApiEntry`): the discovery URL plus overlays (`retired`, `deprecated`, `paid`, `reads`, `nocache`, `headers`, `helpers`, `entities`). The discovery document gives every resource and method. The glob finds the file; `api` must equal the file name, or the Catalog fails to load. No shared file changes.
+- Check the API's caching terms; set `nocache` (`{ reason, source }`) when they forbid or bound caching ([ADR 0001](docs/adr/0001-response-cache.md)). Else list POST methods that only read (reports, searches) by id in `reads`, so `--cache` accepts them.
 - Accept rule — `pnpm discovery:check` exits 0. It fails when an overlay names a method id that is not in the document. CI runs it weekly and on manual dispatch (`.github/workflows/discovery.yml`); `prepublishOnly` runs it before every publish.
 - Test through `run(argv, io)`: fixture entries via `io.apisDir`, cache seeded in a temp `GAPI_CONFIG_DIR`, fake `fetch` (`test/helpers/fetch.ts`). `--dry-run` shows the request. Use no real network.
 - Before commit: `pnpm typecheck` (tsc --noEmit) · `pnpm lint` (biome) · `pnpm test`.

package/dist/bin/gapi.js

@@ -1,7 +1,14 @@
 #!/usr/bin/env node
 import { run } from '../src/run.js';
 const { argv, env, stdin, stdout, stderr } = process;
-// Ignore stream errors (EPIPE on `gapi … | head`), as console.log did before run(argv, io).
-for (const s of [stdout, stderr])
-    s.on('error', () => { });
+// stdout EPIPE (`gapi … | head`): the reader is gone, so stop, which also stops --page-all
+// fetches. Any other stream error (ENOSPC, EBADF) lost output: exit 5, never a silent 0.
+for (const s of [stdout, stderr]) {
+    s.on('error', (e) => {
+        if (e.code !== 'EPIPE')
+            process.exit(5);
+        if (s === stdout)
+            process.exit(0);
+    });
+}
 process.exitCode = await run(argv.slice(2), { env, fetch, stdin, stdout, stderr });

package/dist/src/apis/ads.js

@@ -6,6 +6,7 @@
 //
 // `:search` keeps its raw {results, nextPageToken}; `ads customers googleAds search
 // --page-all` pages it through the request body (epic #30 D6); `--stream` is the all-rows path.
+import { items, text } from '../entities.js';
 import { GapiError } from '../errors.js';
 import { isRecord } from '../json.js';
 import { plan } from '../plan.js';
@@ -21,7 +22,10 @@ const streamConcat = (data) => {
         const message = isRecord(failed.error) ? failed.error.message : undefined;
         throw new GapiError(1, typeof message === 'string' ? message : 'searchStream: a chunk holds an error', failed);
     }
-    return data.flatMap((c) => (isRecord(c) && Array.isArray(c.results) ? c.results : []));
+    const results = data.flatMap((c) => (isRecord(c) && Array.isArray(c.results) ? c.results : []));
+    // SUMMARY_ROW_SETTING puts the totals in the last chunk's summaryRow; keep them.
+    const summaryRow = data.findLast((c) => isRecord(c) && c.summaryRow !== undefined)?.summaryRow;
+    return summaryRow === undefined ? results : { results, summaryRow };
 };
 // D10: one GAQL query; `--stream` returns every row, without it the first page as returned.
 const gaql = {
@@ -41,9 +45,34 @@ const gaql = {
         return stream ? { ...call, decode: streamConcat } : call;
     },
 };
+// Per accessible customer: itself (level 0, gives its name) and its direct clients, queried
+// as that customer (`login-customer-id`). A client's parent is its manager.
+// shortcut: `level <= 1` skips clients of a sub-manager the login cannot access directly;
+// upgrade to the whole tree when an operator needs them.
+const customerClients = {
+    method: 'googleads.customers.googleAds.search',
+    params: (parent) => ({ customerId: parent?.id }),
+    body: () => ({
+        query: 'SELECT customer_client.id, customer_client.descriptive_name, customer_client.level FROM customer_client WHERE customer_client.level <= 1',
+    }),
+    headers: (parent) => ({ 'login-customer-id': parent?.id ?? '' }),
+    entities: (data, parent) => items(data, 'results').flatMap((r) => {
+        const c = isRecord(r.customerClient) ? r.customerClient : {};
+        const id = text(c.id);
+        if (!id)
+            return [];
+        const name = text(c.descriptiveName);
+        return [{ kind: 'customer', id, name, parent: id === parent?.id ? undefined : parent?.id }];
+    }),
+};
 export default {
     api: 'ads',
     discovery: 'https://googleads.googleapis.com/$discovery/rest?version=v26',
+    reads: [
+        'googleads.customers.googleAds.search',
+        'googleads.customers.googleAds.searchStream',
+        'googleads.googleAdsFields.search',
+    ],
     headers: [
         {
             name: 'login-customer-id',
@@ -53,4 +82,17 @@ export default {
         },
     ],
     helpers: { '+gaql': gaql },
+    // Customer IDs as calls take them: 10 digits, no `customers/` prefix.
+    entities: [
+        {
+            method: 'googleads.customers.listAccessibleCustomers',
+            entities: (data) => isRecord(data) && Array.isArray(data.resourceNames)
+                ? data.resourceNames.flatMap((n) => {
+                    const id = typeof n === 'string' ? n.replace(/^customers\//, '') : '';
+                    return id ? [{ kind: 'customer', id }] : [];
+                })
+                : [],
+            children: { customer: customerClients },
+        },
+    ],
 };

package/dist/src/apis/bigquery.js

@@ -0,0 +1,191 @@
+// BigQuery API v2 (#200 D4) and the read-only `+query` helper (D5).
+// No `reads`: jobs.query also runs DML/DDL, so a cache hit could skip a write (ADR 0001).
+// No `nocache`: the operator owns the warehouse data.
+import { randomUUID } from 'node:crypto';
+import { items, text } from '../entities.js';
+import { GapiError } from '../errors.js';
+import { isRecord } from '../json.js';
+import { plan } from '../plan.js';
+const QUERY_ARGS = '"<sql>" [--max-bytes <n>] [--estimate] [--page-limit <n>]';
+const BUDGET = String(10 * 2 ** 30); // 10 GiB: one third of the 32 GiB daily quota (D11)
+const WAIT_MS = 60_000; // per call; the server default is 10 s
+const positive = (flag, value) => {
+    if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value)) {
+        throw new GapiError(3, `${flag} must be a positive integer`);
+    }
+    return value;
+};
+// D5 row decode: `f`/`v` cells → plain JSON. Integer and decimal types stay strings, as sent:
+// a JSON number loses integers above 2^53.
+function cell(field, v) {
+    if (v === null || v === undefined)
+        return null;
+    if (field.mode === 'REPEATED' && Array.isArray(v)) {
+        const item = { ...field, mode: undefined };
+        return v.map((c) => cell(item, isRecord(c) ? c.v : c));
+    }
+    if ((field.type === 'RECORD' || field.type === 'STRUCT') && isRecord(v)) {
+        return record(field.fields ?? [], v);
+    }
+    if (typeof v !== 'string')
+        return v;
+    if (field.type === 'FLOAT' || field.type === 'FLOAT64') {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : v; // NaN and Infinity have no JSON number: kept as sent
+    }
+    if (field.type === 'BOOLEAN' || field.type === 'BOOL')
+        return v === 'true';
+    if (field.type === 'TIMESTAMP' && /^-?\d+$/.test(v))
+        return timestamp(BigInt(v));
+    return v;
+}
+function record(fields, row) {
+    const cells = Array.isArray(row.f) ? row.f : [];
+    return Object.fromEntries(fields.map((f, i) => [f.name, cell(f, isRecord(cells[i]) ? cells[i].v : null)]));
+}
+// `useInt64Timestamp`: microseconds since the epoch → ISO 8601 with 6 fraction digits.
+function timestamp(us) {
+    const floor = us < 0n && us % 1000n !== 0n ? 1n : 0n;
+    const ms = us / 1000n - floor;
+    const rest = us - ms * 1000n;
+    return new Date(Number(ms)).toISOString().replace('Z', `${String(rest).padStart(3, '0')}Z`);
+}
+// One printed line per result page; a running job (`jobComplete: false`) prints nothing.
+function page(data) {
+    if (!isRecord(data) || data.jobComplete === false)
+        return undefined;
+    const fields = isRecord(data.schema) && Array.isArray(data.schema.fields) ? data.schema.fields : [];
+    const rows = Array.isArray(data.rows)
+        ? data.rows.map((r) => record(fields, isRecord(r) ? r : {}))
+        : [];
+    const { totalRows, totalBytesProcessed, cacheHit } = data;
+    return { rows, totalRows, totalBytesProcessed, cacheHit };
+}
+const isDryRun = (body) => isRecord(body) && body.dryRun === true;
+// D5 follow rule: dry run → the same body as a real query (same requestId); a running job →
+// getQueryResults; a pageToken → the next page. Else stop: without a job, every row came inline.
+function follow(model, settings) {
+    const results = (job, pageToken) => plan(model, 'bigquery.jobs.getQueryResults', {
+        params: {
+            projectId: job.projectId,
+            jobId: job.jobId,
+            ...(typeof job.location === 'string' && { location: job.location }),
+            timeoutMs: WAIT_MS,
+            'formatOptions.useInt64Timestamp': true,
+            ...(typeof pageToken === 'string' && pageToken && { pageToken }),
+        },
+    }, settings).url;
+    return (data, last) => {
+        if (isDryRun(last.body)) {
+            const { dryRun: _, ...query } = last.body;
+            return { ...last, body: query };
+        }
+        if (!isRecord(data))
+            return undefined;
+        const token = typeof data.pageToken === 'string' && data.pageToken ? data.pageToken : undefined;
+        if (data.jobComplete !== false && !token)
+            return undefined;
+        const job = data.jobReference;
+        if (!isRecord(job) || typeof job.jobId !== 'string') {
+            throw new GapiError(1, 'BigQuery returned more results but no job reference', data);
+        }
+        return { httpMethod: 'GET', url: results(job, data.jobComplete === false ? undefined : token) };
+    };
+}
+// D5: one read-only statement. Step 1, a free dry run, checks the statement type and the
+// estimate; step 2 runs the query only when both pass, with the budget as maximumBytesBilled.
+const query = {
+    summary: `${QUERY_ARGS}  run one read-only SQL query under a byte budget (default 10 GiB)`,
+    options: {
+        'max-bytes': { type: 'string' },
+        estimate: { type: 'boolean' },
+        'page-limit': { type: 'string' },
+    },
+    plan: async ({ model, args, flags, settings }) => {
+        if (args.length !== 1)
+            throw new GapiError(3, `usage: gapi bigquery +query ${QUERY_ARGS}`);
+        if (!settings.project) {
+            throw new GapiError(3, '+query needs a job project: --project <id>, GOOGLE_CLOUD_PROJECT, or project in the config');
+        }
+        const maxBytes = positive('--max-bytes', flags['max-bytes'] ?? BUDGET);
+        const pageLimit = Number(positive('--page-limit', flags['page-limit'] ?? '10'));
+        const body = {
+            query: args[0],
+            useLegacySql: false,
+            maximumBytesBilled: maxBytes,
+            jobCreationMode: 'JOB_CREATION_OPTIONAL',
+            timeoutMs: WAIT_MS,
+            jobTimeoutMs: '600000', // BigQuery cancels the job server-side: bounds the poll loop
+            formatOptions: { useInt64Timestamp: true },
+            requestId: randomUUID(), // idempotent resend: the plan may retry (D5)
+            dryRun: true,
+        };
+        const call = plan(model, 'bigquery.jobs.query', { params: { projectId: settings.project }, body, dryRun: flags['dry-run'] === true }, settings);
+        const estimate = flags.estimate === true;
+        const decode = (data, step) => {
+            if (!isDryRun(step?.body))
+                return page(data);
+            const { statementType, totalBytesProcessed: bytes } = isRecord(data) ? data : {};
+            if (estimate)
+                return { statementType, totalBytesProcessed: bytes };
+            if (statementType !== 'SELECT') {
+                throw new GapiError(3, `+query runs only SELECT; this statement is ${statementType}; send it with gapi bigquery jobs insert`);
+            }
+            if (typeof bytes !== 'string' || !/^\d+$/.test(bytes)) {
+                throw new GapiError(1, 'the dry run returned no byte estimate', data);
+            }
+            if (BigInt(bytes) > BigInt(maxBytes)) {
+                throw new GapiError(1, `estimate ${bytes} bytes is over the budget of ${maxBytes} bytes; narrow the dates or columns, or raise --max-bytes`);
+            }
+            return undefined;
+        };
+        if (estimate)
+            return { ...call, send: 'once', decode, retry: true };
+        return {
+            ...call,
+            send: 'pages',
+            pageLimit,
+            follow: follow(model, settings),
+            decode,
+            retry: true,
+        };
+    },
+};
+export default {
+    api: 'bigquery',
+    discovery: 'https://bigquery.googleapis.com/$discovery/rest?version=v2',
+    helpers: { '+query': query },
+    // Dataset ID `project.dataset`, as SQL names it. A GA4 export dataset `analytics_<id>` gets
+    // GA4 property `properties/<id>` as parent, so a find on the property returns it.
+    entities: [
+        {
+            method: 'bigquery.projects.list',
+            entities: (data) => items(data, 'projects').flatMap((p) => {
+                const id = isRecord(p.projectReference) ? text(p.projectReference.projectId) : undefined;
+                return id ? [{ kind: 'project', id, name: text(p.friendlyName) }] : [];
+            }),
+            children: {
+                project: {
+                    method: 'bigquery.datasets.list',
+                    params: (parent) => ({ projectId: parent?.id }),
+                    entities: (data, parent) => items(data, 'datasets').flatMap((d) => {
+                        const ref = isRecord(d.datasetReference) ? d.datasetReference : {};
+                        const project = text(ref.projectId);
+                        const dataset = text(ref.datasetId);
+                        if (!project || !dataset)
+                            return [];
+                        const ga4 = /^analytics_(\d+)$/.exec(dataset)?.[1];
+                        return [
+                            {
+                                kind: 'dataset',
+                                id: `${project}.${dataset}`,
+                                name: text(d.friendlyName),
+                                parent: ga4 ? `properties/${ga4}` : parent?.id,
+                            },
+                        ];
+                    }),
+                },
+            },
+        },
+    ],
+};

package/dist/src/apis/business-information.js

@@ -1,5 +1,37 @@
+import { domainOf, items, text } from '../entities.js';
 export default {
     api: 'business-information',
     discovery: 'https://mybusinessbusinessinformation.googleapis.com/$discovery/rest?version=v1',
     scopes: ['business.manage'],
+    // This API lists locations but not accounts; Account Management lists the accounts.
+    entities: [
+        {
+            api: 'business-account-management',
+            method: 'mybusinessaccountmanagement.accounts.list',
+            entities: (data) => items(data, 'accounts').flatMap((a) => {
+                const id = text(a.name);
+                return id ? [{ kind: 'account', id, name: text(a.accountName) }] : [];
+            }),
+            children: {
+                account: {
+                    method: 'mybusinessbusinessinformation.accounts.locations.list',
+                    params: (parent) => ({ parent: parent?.id, readMask: 'name,title,websiteUri' }),
+                    entities: (data, parent) => items(data, 'locations').flatMap((l) => {
+                        const id = text(l.name);
+                        return id
+                            ? [
+                                {
+                                    kind: 'location',
+                                    id,
+                                    name: text(l.title),
+                                    parent: parent?.id,
+                                    domain: domainOf(l.websiteUri),
+                                },
+                            ]
+                            : [];
+                    }),
+                },
+            },
+        },
+    ],
 };

package/dist/src/apis/cloudquotas.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'cloudquotas',
+    discovery: 'https://cloudquotas.googleapis.com/$discovery/rest?version=v1',
+};

package/dist/src/apis/crux.js

@@ -1,4 +1,8 @@
 export default {
     api: 'crux',
     discovery: 'https://chromeuxreport.googleapis.com/$discovery/rest?version=v1',
+    nocache: {
+        reason: 'Google-owned content; Google APIs Terms §5 bound caching to the cache header',
+        source: 'https://developers.google.com/terms',
+    },
 };

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

@@ -1,4 +1,51 @@
+import { domainOf, items, text } from '../entities.js';
+import { isRecord } from '../json.js';
+// Per property: its data streams; a web stream's default URI gives the domain.
+const dataStreams = {
+    method: 'analyticsadmin.properties.dataStreams.list',
+    params: (parent) => ({ parent: parent?.id }),
+    entities: (data, parent) => items(data, 'dataStreams').flatMap((s) => {
+        const id = text(s.name);
+        const uri = isRecord(s.webStreamData) ? s.webStreamData.defaultUri : undefined;
+        return id
+            ? [
+                {
+                    kind: 'stream',
+                    id,
+                    name: text(s.displayName),
+                    parent: parent?.id,
+                    domain: domainOf(uri),
+                },
+            ]
+            : [];
+    }),
+};
 export default {
     api: 'ga4-admin',
     discovery: 'https://analyticsadmin.googleapis.com/$discovery/rest?version=v1beta',
+    // Account summaries list every account and its properties in one list.
+    entities: [
+        {
+            method: 'analyticsadmin.accountSummaries.list',
+            entities: (data) => items(data, 'accountSummaries').flatMap((a) => {
+                const id = text(a.account);
+                const account = id ? [{ kind: 'account', id, name: text(a.displayName) }] : [];
+                const properties = items(a, 'propertySummaries').flatMap((p) => {
+                    const property = text(p.property);
+                    return property
+                        ? [
+                            {
+                                kind: 'property',
+                                id: property,
+                                name: text(p.displayName),
+                                parent: text(p.parent),
+                            },
+                        ]
+                        : [];
+                });
+                return [...account, ...properties];
+            }),
+            children: { property: dataStreams },
+        },
+    ],
 };

package/dist/src/apis/ga4-data-alpha.js

@@ -1,4 +1,5 @@
 export default {
     api: 'ga4-data-alpha',
     discovery: 'https://analyticsdata.googleapis.com/$discovery/rest?version=v1alpha',
+    reads: ['analyticsdata.properties.runReport', 'analyticsdata.properties.runFunnelReport'],
 };

package/dist/src/apis/ga4-data.js

@@ -1,4 +1,12 @@
 export default {
     api: 'ga4-data',
     discovery: 'https://analyticsdata.googleapis.com/$discovery/rest?version=v1beta',
+    reads: [
+        'analyticsdata.properties.runReport',
+        'analyticsdata.properties.runPivotReport',
+        'analyticsdata.properties.batchRunReports',
+        'analyticsdata.properties.batchRunPivotReports',
+        'analyticsdata.properties.runRealtimeReport',
+        'analyticsdata.properties.checkCompatibility',
+    ],
 };

package/dist/src/apis/gsc.js

@@ -1,10 +1,21 @@
+import { domainOf, items } from '../entities.js';
 export default {
     api: 'gsc',
     discovery: 'https://searchconsole.googleapis.com/$discovery/rest?version=v1',
     retired: {
         'searchconsole.urlTestingTools.mobileFriendlyTest.run': {
             reason: 'Retired by Google in December 2023',
-            source: 'https://developers.google.com/search/blog/2017/01/introducing-mobile-friendly-test-api',
+            source: 'https://developers.google.com/search/blog/2023/04/page-experience-in-search',
         },
     },
+    reads: ['webmasters.searchanalytics.query', 'searchconsole.urlInspection.index.inspect'],
+    // A site's ID is its siteUrl: `sc-domain:acme.com` or a URL prefix; both give the domain.
+    entities: [
+        {
+            method: 'webmasters.sites.list',
+            entities: (data) => items(data, 'siteEntry').flatMap(({ siteUrl }) => typeof siteUrl === 'string'
+                ? [{ kind: 'site', id: siteUrl, domain: domainOf(siteUrl) }]
+                : []),
+        },
+    ],
 };

package/dist/src/apis/gtm.js

@@ -1,4 +1,39 @@
+import { domainOf, items, text } from '../entities.js';
 export default {
     api: 'gtm',
     discovery: 'https://tagmanager.googleapis.com/$discovery/rest?version=v2',
+    // IDs are paths (`accounts/1/containers/2`). The container name carries its public ID
+    // (GTM-…). shortcut: all domain keys of a container share one space-separated domain cell;
+    // upgrade to one row per domain when a find must tell them apart.
+    entities: [
+        {
+            method: 'tagmanager.accounts.list',
+            entities: (data) => items(data, 'account').flatMap((a) => {
+                const id = text(a.path);
+                return id ? [{ kind: 'account', id, name: text(a.name) }] : [];
+            }),
+            children: {
+                account: {
+                    method: 'tagmanager.accounts.containers.list',
+                    params: (parent) => ({ parent: parent?.id }),
+                    entities: (data, parent) => items(data, 'container').flatMap((c) => {
+                        const id = text(c.path);
+                        if (!id)
+                            return [];
+                        const names = [text(c.name), text(c.publicId)].filter(Boolean);
+                        const domains = Array.isArray(c.domainName) ? c.domainName.map(domainOf) : [];
+                        return [
+                            {
+                                kind: 'container',
+                                id,
+                                name: names.join(' ') || undefined,
+                                parent: parent?.id,
+                                domain: [...new Set(domains.filter(Boolean))].join(' ') || undefined,
+                            },
+                        ];
+                    }),
+                },
+            },
+        },
+    ],
 };

package/dist/src/apis/merchant-accounts.js

@@ -1,4 +1,17 @@
+import { domainOf, items, text } from '../entities.js';
 export default {
     api: 'merchant-accounts',
     discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=accounts_v1',
+    // `homePageUri` (output only) gives the domain without one homepage call per account.
+    entities: [
+        {
+            method: 'merchantapi.accounts.list',
+            entities: (data) => items(data, 'accounts').flatMap((a) => {
+                const id = text(a.name);
+                return id
+                    ? [{ kind: 'account', id, name: text(a.accountName), domain: domainOf(a.homePageUri) }]
+                    : [];
+            }),
+        },
+    ],
 };

package/dist/src/apis/merchant-reports.js

@@ -1,4 +1,5 @@
 export default {
     api: 'merchant-reports',
     discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=reports_v1',
+    reads: ['merchantapi.accounts.reports.search'],
 };

package/dist/src/apis/pagespeed.js

@@ -1,4 +1,8 @@
 export default {
     api: 'pagespeed',
     discovery: 'https://pagespeedonline.googleapis.com/$discovery/rest?version=v5',
+    nocache: {
+        reason: 'Google-owned content; Google APIs Terms §5 bound caching to the cache header',
+        source: 'https://developers.google.com/terms',
+    },
 };

package/dist/src/apis/places.js

@@ -5,6 +5,10 @@ const billed = {
 export default {
     api: 'places',
     discovery: 'https://places.googleapis.com/$discovery/rest?version=v1',
+    nocache: {
+        reason: 'Places terms forbid caching API content (place_id excepted)',
+        source: 'https://developers.google.com/maps/documentation/places/web-service/policies',
+    },
     paid: {
         'places.places.autocomplete': billed,
         'places.places.get': billed,

package/dist/src/apis/sa360.js

@@ -1,6 +1,7 @@
 export default {
     api: 'sa360',
     discovery: 'https://searchads360.googleapis.com/$discovery/rest?version=v0',
+    reads: ['searchads360.customers.searchAds360.search', 'searchads360.searchAds360Fields.search'],
     headers: [
         {
             name: 'login-customer-id',