google-apis-cli 0.2.0 → 0.3.0

package/README.md

@@ -14,10 +14,10 @@
 - 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 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 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 discovery refresh [<api>…]` refetches discovery documents now; `gapi discovery path` prints the cache dir. `gapi search --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
 
@@ -54,12 +54,14 @@ 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. |
 | **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` | `send(plan, { fetch, authorize, out, sleep })`. `authorize` adds the credential per request; GET/HEAD/PUT/DELETE and `reads` POSTs 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. `--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, 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`. |
+| **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/`. |
+| **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/` and `responses/`). `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).
 
@@ -77,7 +79,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`). 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

@@ -21,7 +21,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 = {
@@ -44,6 +47,11 @@ const gaql = {
 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',

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-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

@@ -4,7 +4,8 @@ export default {
     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'],
 };

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',

package/dist/src/apis/web-risk.js

@@ -1,6 +1,10 @@
 export default {
     api: 'web-risk',
     discovery: 'https://webrisk.googleapis.com/$discovery/rest?version=v1',
+    nocache: {
+        reason: 'Lookup results expire at the response expireTime, not a fixed age',
+        source: 'https://cloud.google.com/web-risk/docs/caching',
+    },
     paid: {
         'webrisk.hashes.search': {
             reason: 'Paid only',

package/dist/src/catalog.js

@@ -8,10 +8,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // Catalog: the API entries found by glob, their discovery documents behind a
 // 24 h disk cache, and the one normalized ApiModel per API (epic #30 D2, D8, D13).
+import { randomUUID } from 'node:crypto';
 import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { GapiError } from './errors.js';
+import { GapiError, reasonOf } from './errors.js';
 import { isRecord, parseOrText } from './json.js';
 const TTL_MS = 24 * 60 * 60 * 1000;
 const AUTH_PREFIX = 'https://www.googleapis.com/auth/';
@@ -42,14 +43,17 @@ export async function openCatalog({ dir, fetch, warn, apisDir = join(import.meta
     async function document(entry, refresh) {
         const file = join(cacheDir, `${entry.api}.json`);
         const mtime = await stat(file).then((s) => s.mtimeMs, () => undefined);
-        if (!refresh && mtime !== undefined && Date.now() - mtime < TTL_MS) {
+        // A future mtime (clock skew) counts as stale, so no document freezes.
+        const age = mtime === undefined ? -1 : Date.now() - mtime;
+        if (!refresh && age >= 0 && age < TTL_MS) {
             const doc = await cached(file);
             if (doc)
                 return doc;
         }
         const got = await download(entry.discovery).catch((e) => e instanceof Error ? e : new Error(String(e)));
         if (!(got instanceof Error)) {
-            await writeAtomic(file, got.text);
+            // The document is already here; a read-only cache dir only costs the next fetch.
+            await writeAtomic(file, got.text).catch((e) => warn(`cannot cache the ${entry.api} document: ${reasonOf(e)}`));
             return got.doc;
         }
         const stale = mtime === undefined ? undefined : await cached(file);
@@ -119,6 +123,13 @@ function toModel(doc, entry) {
     overlay('paid', entry.paid, (m, v) => {
         m.paid = v;
     });
+    // Only a POST: a `reads` id on a write would let --cache store it and Transport resend it.
+    overlay('reads', Object.fromEntries((entry.reads ?? []).map((id) => [id, true])), (m) => {
+        if (m.httpMethod === 'POST')
+            m.read = true;
+        else
+            problems.push(`reads ${m.id}: ${m.httpMethod}, not a POST`);
+    });
     return {
         ...root,
         api: entry.api,
@@ -129,6 +140,7 @@ function toModel(doc, entry) {
         documentationLink: doc.documentationLink,
         rootUrl: doc.rootUrl ?? '',
         servicePath: doc.servicePath ?? '',
+        batchPath: doc.batchPath ?? 'batch',
         auth,
         scopes,
         byId,
@@ -190,14 +202,17 @@ async function loadEntries(dir) {
         const name = basename(f, extname(f));
         if (e.api !== name)
             throw new Error(`${file}: api '${e.api}' must equal '${name}'`);
+        if (!/^[a-z0-9-]+$/.test(e.api))
+            throw new Error(`${file}: api '${e.api}' must match [a-z0-9-]+`);
         entries[e.api] = e;
     }
     return entries;
 }
-// Temp file + rename so a reader never sees a half-written document.
-async function writeAtomic(file, text) {
+// gcloud WriteFileAtomically: a new temp file (mode 600, `wx` never reuses a looser one),
+// flushed to disk, then renamed over the target; readers see the old or the new file.
+export async function writeAtomic(file, text) {
     await mkdir(dirname(file), { recursive: true, mode: 0o700 });
-    const tmp = `${file}.${process.pid}.tmp`;
-    await writeFile(tmp, text, { mode: 0o600 });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    await writeFile(tmp, text, { mode: 0o600, flag: 'wx', flush: true });
     await rename(tmp, file);
 }

package/dist/src/credentials.js

@@ -1,14 +1,14 @@
 // Credentials: the only reader and writer of config.json and credentials.json (epic #30 D8, D13).
 // Settings precedence, Bearer vs API key, token refresh + persistence, loopback/manual login.
-import { randomBytes } from 'node:crypto';
-import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { hash, randomBytes } from 'node:crypto';
+import { chmod, readFile, rm } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { Writable } from 'node:stream';
 import { CodeChallengeMethod, OAuth2Client } from 'google-auth-library';
-import { shortScope } from './catalog.js';
+import { shortScope, writeAtomic } from './catalog.js';
 import { codeOf, GapiError, messageOf } from './errors.js';
 import { isRecord } from './json.js';
 const LOOPBACK_HOST = '127.0.0.1';
@@ -62,12 +62,11 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
             throw new GapiError(2, `${configFile} is not a JSON object; fix or remove it`);
         return cfg;
     };
-    // Owner-only: dir 700, file 600. `mode` applies only on create, so a file that
-    // already exists with looser bits is narrowed too.
+    // Owner-only: file 600 by temp file + rename, so a crash or a concurrent gapi never
+    // leaves a broken file. `mkdir` mode applies only on create: narrow an existing dir too.
     const writeSecure = async (file, data) => {
-        await mkdir(dir, { recursive: true, mode: 0o700 });
-        await writeFile(file, JSON.stringify(data, null, 2), { mode: 0o600 });
-        await chmod(file, 0o600);
+        await writeAtomic(file, JSON.stringify(data, null, 2));
+        await chmod(dir, 0o700);
     };
     const readCredentials = async () => {
         let creds;
@@ -95,6 +94,9 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
         const { tokens } = await c.getToken({ code, codeVerifier }).catch((e) => {
             throw new GapiError(2, `token exchange failed: ${messageOf(e)}`);
         });
+        // Google: "refresh tokens are always returned for installed applications".
+        if (!tokens.refresh_token)
+            throw new GapiError(2, `no refresh token returned; ${RELOGIN}`);
         await writeSecure(credentialsFile, tokens);
         return tokens;
     };
@@ -137,8 +139,10 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
             const c = await client();
             c.setCredentials(await readCredentials());
             // An event listener is not awaited: keep the write so the refresh below can await it.
+            // Copy now: google-auth-library puts the old refresh token back on this object.
             c.on('tokens', (t) => {
-                saving = readCredentials().then((stored) => writeSecure(credentialsFile, { ...stored, ...t }));
+                const fresh = { ...t };
+                saving = readCredentials().then((stored) => writeSecure(credentialsFile, { ...stored, ...fresh }));
             });
             tokenClient = c;
         }
@@ -158,6 +162,14 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
             throw new GapiError(2, `no access token; ${RELOGIN}`);
         return { Authorization: `Bearer ${token}` };
     };
+    // Response cache key part (ADR 0001): one per Google account, never the token itself.
+    // No stored token → undefined; entries are stored only after an authorized success.
+    async function identity(auth) {
+        if (auth.kind === 'apiKey')
+            return 'apiKey';
+        const token = (await readCredentials().catch(() => undefined))?.refresh_token;
+        return token ? hash('sha256', token) : undefined;
+    }
     // Both flows send `state` and a PKCE S256 challenge, and redeem one redirect URL.
     async function login({ consent, manual = false, prompt = ask, }) {
         const c = await client(REDIRECT_URI);
@@ -171,17 +183,24 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
             code_challenge_method: CodeChallengeMethod.S256,
             code_challenge: codeChallenge,
         });
-        const redeem = (redirect) => {
+        // `state` first, so only Google's own redirect can end the login (CSRF).
+        const redeem = async (redirect) => {
             const query = redirect.searchParams;
+            if (query.get('state') !== state)
+                throw new GapiError(2, 'state mismatch');
             const error = query.get('error');
             if (error)
                 throw new GapiError(2, `consent failed: ${error}`);
-            if (query.get('state') !== state)
-                throw new GapiError(2, 'state mismatch');
             const code = query.get('code');
             if (!code)
                 throw new GapiError(2, 'no code in redirect');
-            return exchange(c, code, codeVerifier);
+            const tokens = await exchange(c, code, codeVerifier);
+            // Google: "Your app must verify which scopes were actually granted".
+            const granted = new Set((tokens.scope ?? '').split(' '));
+            const missing = consent.filter((s) => !granted.has(s)).map(shortScope);
+            if (missing.length > 0)
+                warn(`scopes not granted: ${missing.join(', ')}`);
+            return tokens;
         };
         if (manual) {
             stderr.write(`Open this URL and grant access:\n${url}\n` +
@@ -200,6 +219,11 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
                     res.end();
                     return;
                 }
+                if (redirect.searchParams.get('state') !== state) {
+                    res.statusCode = 400; // not Google's redirect: keep waiting for it
+                    res.end('gapi: state mismatch');
+                    return;
+                }
                 try {
                     const tokens = await redeem(redirect);
                     res.end('gapi: authorized. You can close this tab.');
@@ -235,7 +259,8 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
         };
     }
     // Revoke, then delete (the `gcloud auth revoke` pattern, #151). Revoking the refresh
-    // token ends the whole grant. Google answers 400 for a token already invalid or revoked.
+    // token ends the whole grant. Google answers 400 `invalid_token` for a token already
+    // invalid or revoked; another 400 error code is a failed request.
     // Any other failure keeps credentials.json, so the logout can be retried.
     // No stored token (missing or unreadable file) leaves nothing to revoke. The revoke
     // endpoint takes only the token, so no OAuth client id or secret is needed.
@@ -245,7 +270,8 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
             await oauth()
                 .revokeToken(token)
                 .catch((e) => {
-                if (!isRecord(e) || e.status !== 400)
+                const data = isRecord(e) && isRecord(e.response) ? e.response.data : undefined;
+                if (!isRecord(data) || data.error !== 'invalid_token')
                     throw new GapiError(1, `token revoke failed, credentials kept: ${messageOf(e)}`);
                 warn('refresh token already invalid or revoked');
             });
@@ -277,7 +303,7 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
         await writeSecure(configFile, cfg);
         return configFile;
     }
-    return { settings, authorize, login, status, logout, setup };
+    return { settings, authorize, identity, login, status, logout, setup };
 }
 // Decode a JWT payload without verifying (display only; it is our own token).
 function accountFromIdToken(idToken) {

package/dist/src/plan.js

@@ -15,6 +15,8 @@ const OWNED = new Set([
     'upload_protocol',
     '$.xgafv',
 ]);
+// gaxios httpMethodsToRetry, without OPTIONS: a resend of these changes nothing more.
+const IDEMPOTENT = new Set(['GET', 'HEAD', 'PUT', 'DELETE']);
 // The document-level parameters a caller may pass (D5).
 const SHARED = ['fields', 'quotaUser'];
 const PROTOCOLS = ['media', 'multipart', 'resumable'];
@@ -92,17 +94,18 @@ export function plan(model, target, input, settings) {
         body,
         auth: { kind: model.auth, scopes: method.scopes },
         warnings,
+        ...(IDEMPOTENT.has(method.httpMethod) || method.read ? { retry: true } : {}),
         ...mode,
     };
 }
-// The outer CallPlan of a batch call: one POST to the documented `batch` endpoint that
+// The outer CallPlan of a batch call: one POST to the document's `batchPath` endpoint that
 // carries `parts`, each planned by `plan` with its own headers (D7).
 export function batchPlan(model, parts) {
     const [first] = parts;
     return {
         methodId: first.methodId,
         httpMethod: 'POST',
-        url: `${model.rootUrl}batch`,
+        url: `${model.rootUrl}${model.batchPath}`,
         headers: {},
         auth: first.auth,
         warnings: first.warnings,
@@ -258,10 +261,25 @@ function paramValues(model, method, params) {
                 return String(v);
             throw invalid(`${name} must be a string, number or boolean`);
         });
+        // An empty list or a required '' sends nothing; a path would lose its segment.
+        if (values.length === 0)
+            throw invalid(`${name} needs at least one value`);
+        if (spec.required && values.includes(''))
+            throw invalid(`${name} needs a value`);
         for (const v of values) {
             if (spec.enum && !spec.enum.includes(v)) {
                 throw invalid(`${name} must be one of: ${spec.enum.join(', ')}`);
             }
+            const type = spec.type === 'integer' || /int64$/.test(spec.format ?? '') ? 'integer' : spec.type;
+            if (type === 'integer' && !/^-?\d+$/.test(v))
+                throw invalid(`${name} must be an integer`);
+            if (type === 'boolean' && v !== 'true' && v !== 'false') {
+                throw invalid(`${name} must be true or false`);
+            }
+            // Path patterns are checked in buildUrl, after the bare-id hint (#28).
+            if (spec.location !== 'path' && spec.pattern && !matches(spec.pattern, v)) {
+                throw invalid(`${name} must match ${spec.pattern}`);
+            }
         }
         out.set(name, { spec, values });
     }
@@ -280,9 +298,14 @@ function buildUrl(model, method, params, mode) {
         if (!param)
             throw invalid(`missing required param ${name}`);
         const value = param.values[0];
-        if (param.spec.pattern && !new RegExp(param.spec.pattern).test(value)) {
+        if (param.spec.pattern && !matches(param.spec.pattern, value)) {
             throw invalid(`${name} must match ${param.spec.pattern}`);
         }
+        // googleapis-common validateAndEncodeParams: a `.`/`..` segment would make the URL
+        // parser leave the method path; `%2e` too, since WHATWG URL reads it as a dot.
+        const dot = (reserved ? value.split('/') : [value]).find((s) => /^(?:\.|%2e){1,2}$/i.test(s));
+        if (dot !== undefined)
+            throw invalid(`${name}: '${dot}' is a dot segment; pass a real id`);
         if (reserved)
             return value.split('/').map(encodeURIComponent).join('/');
         // #28: `properties/{property}` + `properties/123` would encode to properties%2F123.
@@ -310,6 +333,16 @@ function buildUrl(model, method, params, mode) {
             : model.rootUrl;
     return `${root}${model.servicePath}${path}${qs ? `?${qs}` : ''}`;
 }
+// shortcut: a Java-only discovery pattern (e.g. `(?i)`) is skipped, not checked; translate
+// Java regex to JS if Google ever relies on one for a path.
+function matches(pattern, value) {
+    try {
+        return new RegExp(pattern).test(value);
+    }
+    catch {
+        return true;
+    }
+}
 // google/api/http.proto: {x} percent-encodes every character except [-_.~0-9a-zA-Z];
 // encodeURIComponent leaves !'()* as is.
 const encodeSegment = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);

package/dist/src/render.js

@@ -1,13 +1,17 @@
-export const SCHEMA_USAGE = 'gapi schema <api> <resource>[.<sub-resource>…].<method> | <SchemaName> [--resolve-refs]';
+// Renderers: plain text views over an ApiModel (epic #30 D4, story 8).
+import { isRecord } from './json.js';
+export const SCHEMA_USAGE = 'gapi schema <api> <resource>[.<sub-resource>…].<method> | <SchemaName> [--resolve-refs | --find <word>]';
 export const DISCOVERY_USAGE = 'gapi discovery refresh [<api>…] | path';
 export const AUTH_USAGE = 'gapi auth setup | login [--manual] | status | logout';
+export const SEARCH_USAGE = 'gapi search <words…>';
 const USAGE = `gapi <api> <resource> [<sub-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] [--project <id>] [--api-key <key>]
-     [<entry header flags, e.g. ads --login-customer-id <id>>]
+     [--output <file>] [--page-all [--page-limit <n>]] [--cache <age>] [--dry-run]
+     [--project <id>] [--api-key <key>] [<entry header flags, e.g. ads --login-customer-id <id>>]
 gapi <api> [<resource>…]                  list sub-resources and methods
 gapi <api> <resource>… <method> --help    method help
-gapi <api> +<helper> … [--dry-run] [--project <id>] [--api-key <key>] [<entry header flags>]
+gapi <api> +<helper> … [--dry-run] [--cache <age>] [--project <id>] [--api-key <key>] [<entry header flags>]
+${SEARCH_USAGE}                      find methods by intent, max 20 hits
 ${SCHEMA_USAGE}
 ${DISCOVERY_USAGE}
 ${AUTH_USAGE}
@@ -95,6 +99,12 @@ const oneLine = (description = '') => description
     .trim()
     .split('\n')[0]
     .split(/(?<=\.)\s+(?=[A-Z*])/)[0];
+// The first sentence, max 100 chars: one line of search hits and of `schema --find`.
+const brief = (description) => {
+    const sentence = oneLine(description);
+    const chars = [...sentence]; // code points: a cut never splits a surrogate pair
+    return chars.length > 100 ? `${chars.slice(0, 99).join('')}…` : sentence;
+};
 // Code-point order, so the output does not depend on the machine's locale.
 const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 const byKey = (map) => [...map].sort(([a], [b]) => compare(a, b));
@@ -142,6 +152,15 @@ function referenceRow(model, m) {
     const marked = markList(m, { reasons: true }).join('; ');
     return `| \`gapi ${model.api} ${m.words.join(' ')}\` | ${m.httpMethod} | ${cell(oneLine(m.description))} | ${required.join(', ')} | ${m.request ? `\`${m.request}\`` : ''} | ${cell(marked)} |`;
 }
+// One line per hit: command, marks, HTTP method, first sentence of the description.
+export function searchText(hits) {
+    return hits
+        .map(({ model, method: m }) => {
+        const line = `gapi ${model.api} ${m.words.join(' ')}${marks(m)}  ${m.httpMethod}  ${brief(m.description)}`;
+        return `${line.trimEnd()}\n`;
+    })
+        .join('');
+}
 // D9: a method's shape (request/response as schema names), or one document schema.
 export function schemaView(model, target, { resolveRefs }) {
     // A method shape holds schema names, never a $ref, so --resolve-refs leaves it as is.
@@ -165,6 +184,52 @@ export function schemaView(model, target, { resolveRefs }) {
     const out = resolveRefs && schema ? expandObject(schema, model.schemas, [target.schema]) : schema;
     return `${JSON.stringify(out, null, 2)}\n`;
 }
+// `--find`: one line per leaf of the expanded schema (a method: request and response) whose
+// path or printed sentence contains `word`, case-insensitive. A $ref the cycle guard left is a leaf.
+export function schemaFind(model, target, word) {
+    const roots = 'method' in target
+        ? [
+            ['request', target.method.request],
+            ['response', target.method.response],
+        ]
+        : [['', target.schema]];
+    const needle = word.toLowerCase();
+    const lines = [];
+    // An array or map item without a description takes its field's (Google puts it there).
+    const walk = (node, path, fieldDescription = '') => {
+        const own = typeof node.description === 'string' ? node.description : fieldDescription;
+        const props = isRecord(node.properties) ? Object.entries(node.properties) : [];
+        const children = [
+            ...props.map(([key, child]) => [
+                path ? `${path}.${key}` : key,
+                child,
+                '',
+            ]),
+            [`${path}[]`, node.items, own],
+            [`${path}{}`, node.additionalProperties, own],
+        ];
+        let leaf = true;
+        for (const [childPath, child, description] of children) {
+            if (!isRecord(child))
+                continue;
+            leaf = false;
+            walk(child, childPath, description);
+        }
+        const ref = typeof node.$ref === 'string' ? node.$ref : undefined;
+        const text = ref ? '' : brief(own);
+        if (!leaf || !`${path}\n${text}`.toLowerCase().includes(needle))
+            return;
+        const type = ref ? `$ref ${ref}` : `${String(node.type ?? 'any')}${node.enum ? ' enum' : ''}`;
+        lines.push(`${path}: ${type}${text ? ` — ${text}` : ''}`);
+    };
+    for (const [path, name] of roots) {
+        const schema = name ? model.schemas.get(name) : undefined;
+        const expanded = name && schema ? expandObject(schema, model.schemas, [name]) : undefined;
+        if (isRecord(expanded))
+            walk(expanded, path);
+    }
+    return lines.map((line) => `${line}\n`).join('');
+}
 function expandRefs(value, schemas, path) {
     if (Array.isArray(value))
         return value.map((v) => expandRefs(v, schemas, path));

package/dist/src/responses.js

@@ -0,0 +1,37 @@
+// Response cache (ADR 0001): one file per key under <config dir>/responses/, dir 700, files
+// 600, written by temp file + rename. Holds Google account data: login and logout clear it.
+import { hash } from 'node:crypto';
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeAtomic } from './catalog.js';
+export const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export function openResponses(dir) {
+    const file = (key) => join(dir, key);
+    // Every value that shapes the request or its output; `url` carries every query value.
+    const key = (call, identity) => hash('sha256', JSON.stringify([
+        identity,
+        call.httpMethod,
+        call.url,
+        call.headers,
+        call.body,
+        call.send,
+        call.send === 'pages' ? call.pageLimit : undefined,
+        call.decode !== undefined, // a helper's decoded output differs from the raw one
+    ]));
+    // When the entry was stored (epoch ms); undefined when there is none.
+    const mtime = (k) => stat(file(k)).then((s) => s.mtimeMs, () => undefined);
+    const get = (k) => readFile(file(k), 'utf8').catch(() => undefined);
+    const put = (k, text) => writeAtomic(file(k), text);
+    // Deletes every file (temp files too) older than the max age. Every run calls it, so
+    // account data never outlives 7 days on disk (YouTube policy, ADR 0001).
+    async function sweep() {
+        for (const name of await readdir(dir).catch(() => [])) {
+            const f = join(dir, name);
+            const s = await stat(f).catch(() => undefined);
+            if (s && Date.now() - s.mtimeMs > MAX_AGE_MS)
+                await rm(f, { force: true });
+        }
+    }
+    const clear = () => rm(dir, { recursive: true, force: true });
+    return { key, mtime, get, put, sweep, clear };
+}

package/dist/src/run.js

@@ -1,12 +1,15 @@
 // Process io is injected so tests drive the whole CLI in-process.
 import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { openCatalog } from './catalog.js';
 import { configDir, openCredentials } from './credentials.js';
 import { GapiError, messageOf, reasonOf } from './errors.js';
 import { isRecord } from './json.js';
 import { parseJson, plan, resolve } from './plan.js';
-import { AUTH_USAGE, DISCOVERY_USAGE, levelText, methodHelp, rootHelp, SCHEMA_USAGE, schemaView, } from './render.js';
+import { AUTH_USAGE, DISCOVERY_USAGE, levelText, methodHelp, rootHelp, SCHEMA_USAGE, SEARCH_USAGE, schemaFind, schemaView, searchText, } from './render.js';
+import { MAX_AGE_MS, openResponses } from './responses.js';
+import { matchQuery, search } from './search.js';
 import { send } from './transport.js';
 const GLOBAL_OPTIONS = {
     params: { type: 'string' },
@@ -20,6 +23,7 @@ const GLOBAL_OPTIONS = {
     output: { type: 'string' },
     project: { type: 'string' },
     'api-key': { type: 'string' },
+    cache: { type: 'string' },
     help: { type: 'boolean' },
 };
 // D10: a helper takes the global flags that do not shape the request, plus its own options.
@@ -27,8 +31,19 @@ const HELPER_OPTIONS = {
     'dry-run': GLOBAL_OPTIONS['dry-run'],
     project: GLOBAL_OPTIONS.project,
     'api-key': GLOBAL_OPTIONS['api-key'],
+    cache: GLOBAL_OPTIONS.cache,
     help: GLOBAL_OPTIONS.help,
 };
+const AGE_UNIT_MS = { s: 1e3, m: 60e3, h: 3600e3, d: 86400e3 };
+// `--cache <n>s|m|h|d`, from 1 s to the 7-day store limit (ADR 0001).
+function parseAge(age) {
+    const m = /^(\d+)([smhd])$/.exec(age);
+    const ms = m ? Number(m[1]) * AGE_UNIT_MS[m[2]] : 0;
+    if (ms < 1000 || ms > MAX_AGE_MS) {
+        throw new GapiError(3, `--cache: ${age} is not an age from 1s to 7d`);
+    }
+    return ms;
+}
 const isHelperName = (word) => word.startsWith('+');
 // D4: an entry header flag is accepted only on the APIs whose entry declares it.
 const headerOptions = (entry) => Object.fromEntries((entry?.headers ?? []).map((h) => [h.flag, { type: 'string' }]));
@@ -46,16 +61,22 @@ export async function run(argv, io) {
         return err.exit;
     }
 }
-// Strict argv parsing; an unknown flag or a missing flag value is a validation error.
+// Strict argv parsing; an unknown flag, a missing flag value or a repeated flag (parseArgs
+// would keep the last one) is a validation error.
 function parse(args, options) {
     try {
-        return parseArgs({ args, options, allowPositionals: true, strict: true });
+        const parsed = parseArgs({ args, options, allowPositionals: true, strict: true, tokens: true });
+        const names = parsed.tokens.flatMap((t) => (t.kind === 'option' ? [t.name] : []));
+        const twice = names.find((n, i) => names.indexOf(n) !== i);
+        if (twice !== undefined)
+            throw new GapiError(3, `--${twice} given twice`);
+        return parsed;
     }
     catch (e) {
-        throw new GapiError(3, messageOf(e));
+        throw e instanceof GapiError ? e : new GapiError(3, messageOf(e));
     }
 }
-async function runAuth(sub, values, { io, creds, catalog }) {
+async function runAuth(sub, values, { io, creds, catalog, responses, }) {
     // --help never starts a side effect: no server, no fetch, no file write.
     if (values.help) {
         io.stdout.write(`${AUTH_USAGE}\n`);
@@ -63,6 +84,7 @@ async function runAuth(sub, values, { io, creds, catalog }) {
     }
     if (sub === 'login') {
         const consent = await consentScopes(catalog);
+        await responses.clear(); // a new account starts with no stored responses
         const tokens = await creds.login({ consent, manual: values.manual === true });
         io.stderr.write(`gapi: authorized (${tokens.refresh_token ? 'refresh token stored' : 'no refresh token'})\n`);
         return;
@@ -81,11 +103,16 @@ async function runAuth(sub, values, { io, creds, catalog }) {
         return;
     }
     if (sub === 'logout') {
-        await creds.logout();
+        try {
+            await creds.logout();
+        }
+        finally {
+            await responses.clear(); // also when the revoke fails: no account data stays on disk
+        }
         io.stderr.write('gapi: credentials removed\n');
         return;
     }
-    throw new GapiError(3, `unknown auth command: ${sub}`);
+    throw new GapiError(3, sub === undefined ? `usage: ${AUTH_USAGE}` : `unknown auth command: ${sub}`);
 }
 // D8 consent set: every entry's per-method scope plus its entry scopes (identity is added by login).
 async function consentScopes(catalog) {
@@ -105,10 +132,19 @@ async function consentScopes(catalog) {
 function schemaTarget(model, path) {
     if (!model.methods.has(path) && model.schemas.has(path))
         return { schema: path };
-    const found = resolve(model, path.split('.'));
-    if (!found.method)
-        throw new GapiError(3, `${path} is a resource, not a method or schema`);
-    return { method: found.method };
+    try {
+        const found = resolve(model, path.split('.'));
+        if (!found.method)
+            throw new GapiError(3, `${path} is a resource, not a method or schema`);
+        return { method: found.method };
+    }
+    catch (e) {
+        // resolve knows only the tree; a one-word path can also name a schema.
+        if (e instanceof GapiError && /^unknown /.test(e.message) && !path.includes('.')) {
+            throw new GapiError(3, `${e.message}, or a schema name`);
+        }
+        throw e;
+    }
 }
 async function dispatch(argv, io) {
     const dir = configDir(io.env);
@@ -121,6 +157,26 @@ async function dispatch(argv, io) {
         stdin: io.stdin,
         stderr: io.stderr,
     });
+    const responses = openResponses(join(dir, 'responses'));
+    await responses.sweep();
+    // ADR 0001 eligibility, before any network call: the entry allows caching, the call is
+    // one request or pages, the method is a GET or a `reads` POST.
+    const cacheFor = async (call, model, values) => {
+        if (values.cache === undefined)
+            return undefined;
+        const maxAgeMs = parseAge(values.cache);
+        const { nocache } = catalog.entries[model.api];
+        if (nocache) {
+            throw new GapiError(3, `--cache: ${model.api} responses must not be cached: ${nocache.reason} (${nocache.source})`);
+        }
+        const method = model.byId.get(call.methodId);
+        const once = call.send === 'once' || call.send === 'pages';
+        if (!once || (method?.httpMethod !== 'GET' && !method?.read)) {
+            const command = method ? `${model.api} ${method.words.join(' ')}` : call.methodId;
+            throw new GapiError(3, `--cache: ${command} is not a cacheable read`);
+        }
+        return { key: responses.key(call, await creds.identity(call.auth)), maxAgeMs };
+    };
     if (argv.length === 0 || (argv[0] === '--help' && argv.length === 1)) {
         io.stdout.write(rootHelp(Object.keys(catalog.entries)));
         return;
@@ -131,11 +187,27 @@ async function dispatch(argv, io) {
             manual: { type: 'boolean' },
             help: { type: 'boolean' },
         });
-        return runAuth(positionals[0], values, { io, creds, catalog });
+        return runAuth(positionals[0], values, { io, creds, catalog, responses });
+    }
+    if (api === 'search') {
+        // No option parse: a word like `-list` is query text (story 11).
+        if (rest.includes('--help')) {
+            io.stdout.write(`${SEARCH_USAGE}\n`);
+            return;
+        }
+        const query = rest.join(' ');
+        matchQuery(query); // a query with no token exits 3 before any document loads
+        const models = await Promise.all(Object.keys(catalog.entries).map((a) => catalog.load(a)));
+        const hits = search(models, query);
+        if (hits.length === 0)
+            io.stderr.write('gapi: no match\n');
+        io.stdout.write(searchText(hits));
+        return;
     }
     if (api === 'schema') {
         const { values, positionals } = parse(rest, {
             'resolve-refs': { type: 'boolean' },
+            find: { type: 'string' },
             help: { type: 'boolean' },
         });
         if (values.help) {
@@ -145,9 +217,19 @@ async function dispatch(argv, io) {
         if (positionals.length !== 2)
             throw new GapiError(3, `usage: ${SCHEMA_USAGE}`);
         const [name, path] = positionals;
+        if (values.find === '')
+            throw new GapiError(3, '--find: needs a word');
         const model = await catalog.load(name);
+        const target = schemaTarget(model, path);
+        if (values.find !== undefined) {
+            const found = schemaFind(model, target, values.find);
+            if (found === '')
+                io.stderr.write('gapi: no match\n');
+            io.stdout.write(found);
+            return;
+        }
         const resolveRefs = values['resolve-refs'] === true;
-        io.stdout.write(schemaView(model, schemaTarget(model, path), { resolveRefs }));
+        io.stdout.write(schemaView(model, target, { resolveRefs }));
         return;
     }
     if (api === 'discovery') {
@@ -205,13 +287,18 @@ async function dispatch(argv, io) {
                 throw new GapiError(3, `cannot read ${path}: ${reasonOf(e)}`);
             }),
         });
-        return perform(call, values['dry-run'] === true, io, creds.authorize);
+        const cache = await cacheFor(call, model, values);
+        return perform(call, values['dry-run'] === true, io, creds.authorize, { responses, cache });
     }
     const entry = Object.hasOwn(catalog.entries, api) ? catalog.entries[api] : undefined;
     const { values, positionals } = parse(rest, { ...GLOBAL_OPTIONS, ...headerOptions(entry) });
     const model = await catalog.load(api);
     const target = resolve(model, positionals);
     if (!target.method) {
+        // A listing sends nothing: a request flag here means the method word is missing.
+        const flag = Object.keys(values).find((k) => k !== 'help');
+        if (flag)
+            throw new GapiError(3, `--${flag}: ${[api, ...positionals].join(' ')} is not a method`);
         const helpers = positionals.length === 0 ? catalog.entries[api].helpers : undefined;
         io.stdout.write(levelText(model, positionals, target.node, helpers));
         return;
@@ -232,12 +319,17 @@ async function dispatch(argv, io) {
         uploadProtocol: values['upload-protocol'],
         output: values.output,
     }, await creds.settings(values, model.headers));
-    return perform(call, dryRun, io, creds.authorize);
+    const cache = await cacheFor(call, model, values);
+    return perform(call, dryRun, io, creds.authorize, { responses, cache });
 }
-// Prints the plan's warnings, then the redacted request (--dry-run) or the response.
-async function perform(call, dryRun, io, authorize) {
+// Prints the plan's warnings, then the redacted request (--dry-run), the stored response
+// (a --cache hit) or the live response, which a --cache miss stores after a full success.
+async function perform(call, dryRun, io, authorize, { responses, cache }) {
     for (const w of call.warnings)
         io.stderr.write(`gapi: warning: ${w}\n`);
+    const mtime = cache && (await responses.mtime(cache.key));
+    const fresh = cache && mtime !== undefined && Date.now() - mtime < cache.maxAgeMs;
+    const stored = fresh ? await responses.get(cache.key) : undefined;
     if (dryRun) {
         const headers = { ...call.headers, ...(await authorize(call.auth, { redact: true })) };
         const request = {
@@ -255,9 +347,28 @@ async function perform(call, dryRun, io, authorize) {
                     body: p.body,
                 }))
                 : undefined,
+            cache: cache && (stored === undefined ? 'miss' : 'hit'),
         };
         io.stdout.write(`${JSON.stringify(request, null, 2)}\n`);
         return;
     }
-    await send(call, { fetch: io.fetch, authorize, out: io.stdout });
+    if (stored !== undefined && mtime !== undefined) {
+        io.stdout.write(stored);
+        io.stderr.write(`gapi: cached response from ${new Date(mtime).toISOString()}\n`);
+        return;
+    }
+    const chunks = [];
+    const out = {
+        write: (chunk) => {
+            chunks.push(chunk);
+            return io.stdout.write(chunk);
+        },
+    };
+    await send(call, { fetch: io.fetch, authorize, out, sleep: io.sleep });
+    if (!cache)
+        return;
+    // Best effort: the response is already printed, so a failed write only warns.
+    await responses.put(cache.key, chunks.join('')).catch((e) => {
+        io.stderr.write(`gapi: warning: cache write failed: ${reasonOf(e)}\n`);
+    });
 }

package/dist/src/search.js

@@ -0,0 +1,53 @@
+// Search: finds methods by intent across API entries with an in-memory SQLite FTS5 index (#182 §1).
+// shortcut: DatabaseSync is a documentation-only deprecated alias of Database since Node v26.11.0
+// (DEP0210); switch when @types/node types Database.
+import { DatabaseSync } from 'node:sqlite';
+import { GapiError } from './errors.js';
+import { SEARCH_USAGE } from './render.js';
+// `conversionActions` → `conversion Actions`, `URLInspection` → `URL Inspection`, `a-b_c.d` → `a b c d`.
+const split = (text) => text
+    .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, '$1 $2')
+    .replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, '$1 $2')
+    .replace(/[-_.]/g, ' ');
+// Tokens hold only letters and digits, so no FTS5 syntax reaches the match expression.
+export function matchQuery(query) {
+    const tokens = split(query)
+        .toLowerCase()
+        .match(/[\p{L}\p{N}]+/gu);
+    if (!tokens)
+        throw new GapiError(3, `usage: ${SEARCH_USAGE}`);
+    return tokens.map((t) => `"${t}"`).join(' OR ');
+}
+export function search(models, query) {
+    const match = matchQuery(query);
+    const db = new DatabaseSync(':memory:');
+    try {
+        db.exec("create virtual table m using fts5(api unindexed, id unindexed, words, extra, descr, tokenize = 'porter unicode61')");
+        const insert = db.prepare('insert into m values (?, ?, ?, ?, ?)');
+        db.exec('begin');
+        for (const model of models) {
+            for (const m of model.byId.values()) {
+                const words = split([model.api, ...m.words].join(' '));
+                const extra = [
+                    split([model.title, m.request, m.response].filter(Boolean).join(' ')),
+                    m.upload && 'upload',
+                    m.download && 'download',
+                ].filter(Boolean);
+                insert.run(model.api, m.id, words, extra.join(' '), m.description ?? '');
+            }
+        }
+        db.exec('commit');
+        const byApi = new Map(models.map((model) => [model.api, model]));
+        return db
+            .prepare('select api, id from m where m match ? order by bm25(m, 0, 0, 6, 2, 1) limit 20')
+            .all(match)
+            .flatMap(({ api, id }) => {
+            const model = byApi.get(String(api));
+            const method = model?.byId.get(String(id));
+            return model && method ? [{ model, method }] : [];
+        });
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/src/transport/download.js

@@ -1,10 +1,16 @@
 // Media download (epic #30 D7): the response body streams to the --output file.
 import { createWriteStream } from 'node:fs';
-import { rm } from 'node:fs/promises';
+import { access, constants, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import { GapiError, reasonOf } from '../errors.js';
 // The file is created only after a 2xx, so a Google error leaves no empty file behind.
 export async function download(plan, call) {
+    // A bad local path is the caller's input (exit 3), found before Google sends any byte.
+    await access(dirname(plan.output), constants.W_OK).catch((e) => {
+        throw new GapiError(3, `--output: cannot write to ${dirname(plan.output)}: ${reasonOf(e)}`);
+    });
     const res = await call(plan.url, { method: plan.httpMethod, headers: plan.headers });
     const file = createWriteStream(plan.output);
     await pipeline(res.body ?? Readable.from([]), file).catch(async (e) => {

package/dist/src/transport/retry.js

@@ -0,0 +1,21 @@
+// Retry policy shared by Transport and the resumable upload (Google client idioms, #194).
+import { GapiError } from '../errors.js';
+// The request never got an HTTP answer (DNS, reset, timeout): exit 1, like a Google error.
+export class NetworkError extends GapiError {
+}
+// Google's retry rule: 408, 429, 5xx, and a 403 for a rate limit (google-api-python-client).
+export const RETRIES = 3;
+export const retryable = (status, text = '') => status === 408 ||
+    status === 429 ||
+    status >= 500 ||
+    (status === 403 && /"reason":\s*"(user)?[rR]ateLimitExceeded"/.test(text));
+// Truncated exponential backoff with jitter: min(32 s, 1 s × 2^n + 0–1 s), Google's docs.
+export const backoff = (attempt) => Math.min(32_000, 1000 * 2 ** attempt + Math.random() * 1000);
+// Our choice, no Google client reads it: `Retry-After` (seconds or HTTP date) is a floor.
+export const retryAfter = (res) => {
+    const v = res.headers.get('Retry-After');
+    if (!v)
+        return 0;
+    const ms = /^\d+$/.test(v) ? Number(v) * 1000 : Date.parse(v) - Date.now();
+    return Number.isFinite(ms) ? Math.max(0, ms) : 0;
+};

package/dist/src/transport/upload.js

@@ -4,19 +4,20 @@ import { openAsBlob } from 'node:fs';
 import { open } from 'node:fs/promises';
 import { GapiError, reasonOf } from '../errors.js';
 import { parseOrText } from '../json.js';
+import { backoff, NetworkError, RETRIES, retryable } from './retry.js';
 // Google wants chunks in multiples of 256 KiB; 8 MiB keeps the request count low.
 const CHUNK = 8 * 1024 * 1024;
 // Consecutive 308s that move the upload no further before gapi gives up.
 const MAX_STALLS = 3;
 // Returns the final response; Transport prints it like a `once` call.
-export async function upload(plan, call) {
+export async function upload(plan, call, sleep) {
     const file = await readable(plan.upload.path);
     const { protocol, contentType } = plan.upload;
     if (protocol === 'media') {
         return call(plan.url, { method: plan.httpMethod, headers: plan.headers, body: file });
     }
     if (protocol === 'resumable')
-        return resumable(plan, file, call);
+        return resumable(plan, file, call, sleep);
     // multipart/related: the JSON metadata part, then the media part.
     const boundary = randomUUID();
     const body = new Blob([
@@ -45,7 +46,9 @@ async function readable(path) {
     return openAsBlob(path);
 }
 // Session request on the upload URL, then PUT chunks to the session URI; 308 = send more.
-async function resumable(plan, file, call) {
+// A 5xx or a network error on a chunk asks the session what it kept (`bytes */<size>`) and
+// goes on from there (google-api-python-client `next_chunk`, @google-cloud/storage).
+async function resumable(plan, file, call, sleep) {
     const session = await call(plan.url, {
         method: plan.httpMethod,
         headers: { ...plan.headers, 'X-Upload-Content-Length': String(file.size) },
@@ -58,24 +61,46 @@ async function resumable(plan, file, call) {
     }
     // undici holds the connection until a body is read or cancelled; only headers matter here.
     await session.body?.cancel();
-    let start = 0;
-    let stalls = 0;
-    for (;;) {
-        const end = Math.min(start + CHUNK, file.size);
-        const range = file.size === 0 ? 'bytes */0' : `bytes ${start}-${end - 1}/${file.size}`;
-        const headers = { 'Content-Range': range };
-        const res = await call(location, { method: 'PUT', headers, body: file.slice(start, end) }, 308);
-        if (res.status !== 308)
-            return res;
-        // `Range: bytes=0-<last>` names the bytes Google kept; no Range means it kept none.
-        const kept = /^bytes=0-(\d+)$/.exec(res.headers.get('Range') ?? '');
-        const next = kept ? Number(kept[1]) + 1 : 0;
-        stalls = next > start ? 0 : stalls + 1;
-        if (stalls === MAX_STALLS || next >= file.size) {
-            const body = parseOrText(await res.text());
-            throw new GapiError(1, `resumable upload: 308 at byte ${next} of ${file.size}, no progress`, body);
+    // A retryable answer or no answer at all is undefined: the caller asks the session again.
+    const put = (range, body) => call(location, { method: 'PUT', headers: { 'Content-Range': range }, body }, (s) => s === 308 || retryable(s)).then(async (res) => (retryable(res.status) ? void (await res.body?.cancel()) : res), (e) => {
+        if (e instanceof NetworkError)
+            return undefined;
+        throw e;
+    });
+    // Every final failure names the session, so the operator sees where the upload stopped.
+    try {
+        let start = 0;
+        let stalls = 0;
+        let failures = 0;
+        for (;;) {
+            const end = Math.min(start + CHUNK, file.size);
+            const range = file.size === 0 ? 'bytes */0' : `bytes ${start}-${end - 1}/${file.size}`;
+            let res = await put(range, file.slice(start, end));
+            while (!res) {
+                if (++failures > RETRIES)
+                    throw new GapiError(1, `resumable upload: no answer at byte ${start}`);
+                await sleep(backoff(failures - 1));
+                res = await put(`bytes */${file.size}`);
+            }
+            if (res.status !== 308)
+                return res;
+            // `Range: bytes=0-<last>` names the bytes Google kept; no Range means it kept none.
+            const kept = /^bytes=0-(\d+)$/.exec(res.headers.get('Range') ?? '');
+            const next = kept ? Number(kept[1]) + 1 : 0;
+            stalls = next > start ? 0 : stalls + 1;
+            if (next > start)
+                failures = 0;
+            if (stalls === MAX_STALLS || next >= file.size) {
+                const body = parseOrText(await res.text());
+                throw new GapiError(1, `resumable upload: 308 at byte ${next} of ${file.size}, no progress`, body);
+            }
+            await res.body?.cancel();
+            start = next;
         }
-        await res.body?.cancel();
-        start = next;
+    }
+    catch (e) {
+        if (!(e instanceof GapiError))
+            throw e;
+        throw new GapiError(e.exit, `${e.message}; session ${location}`, e.body);
     }
 }

package/dist/src/transport.js

@@ -1,15 +1,17 @@
 // Transport: sends a CallPlan and prints the response (epic #30 D13).
 // `authorize` adds the credential before every request; a non-2xx exits 1, a missing scope 2.
-import { GapiError } from './errors.js';
+import { setTimeout } from 'node:timers/promises';
+import { GapiError, reasonOf } from './errors.js';
 import { isRecord, parseOrText } from './json.js';
 import { batch } from './transport/batch.js';
 import { download } from './transport/download.js';
+import { backoff, NetworkError, RETRIES, retryAfter, retryable, } from './transport/retry.js';
 import { upload } from './transport/upload.js';
 export async function send(plan, deps) {
     const call = caller(plan, deps);
     const print = (data) => deps.out.write(`${JSON.stringify(data, null, 2)}\n`);
     if (plan.send === 'upload') {
-        print(await json(await upload(plan, call)));
+        print(await json(await upload(plan, call, deps.sleep ?? setTimeout)));
         return;
     }
     if (plan.send === 'download') {
@@ -27,9 +29,14 @@ export async function send(plan, deps) {
             print(plan.decode ? plan.decode(results) : results);
         if (sent.error)
             throw sent.error;
-        const failed = results.filter((r) => r.status < 200 || r.status > 299).length;
-        if (failed > 0)
-            throw new GapiError(1, `${failed} of ${results.length} batch parts failed`);
+        const failed = sent.results.filter((r) => r.status < 200 || r.status > 299);
+        // A part that lacks a scope gets the same exit 2 and hint as a single call.
+        const scope = failed.map((r) => failure(plan, r.status, r.text)).find((e) => e.exit === 2);
+        if (scope)
+            throw scope;
+        if (failed.length > 0) {
+            throw new GapiError(1, `${failed.length} of ${results.length} batch parts failed`);
+        }
         return;
     }
     const init = {
@@ -60,13 +67,30 @@ export async function send(plan, deps) {
         }
     }
 }
-function caller(plan, { fetch, authorize }) {
+// Uploads and batches never retry here; a resumable upload resumes on its own.
+function caller(plan, { fetch, authorize, sleep = setTimeout }) {
+    const retry = plan.retry && plan.send !== 'upload' && plan.send !== 'batch';
     return async (url, init, allowed) => {
-        const headers = { ...init.headers, ...(await authorize(plan.auth)) };
-        const res = await fetch(url, { ...init, headers });
-        if (!res.ok && res.status !== allowed)
-            throw failure(plan, res.status, await res.text());
-        return res;
+        for (let attempt = 0;; attempt++) {
+            const headers = { ...init.headers, ...(await authorize(plan.auth)) };
+            const res = await fetch(url, { ...init, headers }).catch((e) => {
+                const cause = e instanceof Error && e.cause !== undefined ? e.cause : e;
+                return new NetworkError(1, `network: ${reasonOf(cause)}`);
+            });
+            const last = !retry || attempt === RETRIES;
+            if (res instanceof NetworkError) {
+                if (last)
+                    throw res;
+                await sleep(backoff(attempt));
+                continue;
+            }
+            if (res.ok || allowed?.(res.status))
+                return res;
+            const text = await res.text();
+            if (last || !retryable(res.status, text))
+                throw failure(plan, res.status, text);
+            await sleep(Math.max(backoff(attempt), retryAfter(res)));
+        }
     };
 }
 // A 2xx body that is not JSON is Google's surprise, not gapi's: exit 1 with the body.
@@ -81,9 +105,11 @@ async function json(res) {
         throw new GapiError(1, `HTTP ${res.status}: the response body is not JSON`, text);
     }
 }
-function failure(plan, status, text) {
+export function failure(plan, status, text) {
     // A front-end error page can be HTML; keep it as text rather than fail on parse.
-    const body = parseOrText(text);
+    // A streaming method wraps the error in an array (Go googleapi errorReplyFromBody).
+    const parsed = parseOrText(text);
+    const body = Array.isArray(parsed) ? parsed[0] : parsed;
     const error = isRecord(body) && isRecord(body.error) ? body.error : {};
     // D8: the stored grant lacks this method's scope; a new consent fixes it. AIP-193: the
     // (reason, domain) pair of the ErrorInfo detail identifies the error.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "google-apis-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One discovery-driven CLI (gapi) for 47 Google marketing and data APIs: Ads, GA4, Search Console, Tag Manager, Indexing, Merchant, Business Profile, SA360, CM360, DV360, YouTube, PageSpeed, CrUX, Sheets, Places and more. One login, read+write.",
   "type": "module",
   "bin": {
     "gapi": "dist/bin/gapi.js"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=26"
   },
   "scripts": {
     "test": "node --test",
@@ -55,13 +55,13 @@
     "url": "https://github.com/realroboto/google-apis-cli/issues"
   },
   "dependencies": {
-    "google-auth-library": "^11.3.0"
+    "google-auth-library": "^11.3.3"
   },
   "license": "MIT",
   "devDependencies": {
-    "@biomejs/biome": "^2.5.15",
-    "@types/node": "^24.19.2",
+    "@biomejs/biome": "^2.6.5",
+    "@types/node": "^26.6.6",
     "typescript": "^7.0.2"
   },
-  "packageManager": "pnpm@12.11.2+sha512.25a51652a196785af5f28bda6dfe8dc582ebefa4ac1d180221ce1390231c5fb76637822ea4b6e4633ce74acdcb0a77f725af11bad38177fdeddaee818a955cb9"
+  "packageManager": "pnpm@12.16.1+sha512.091d1dee7927575661b25dab3c2ae31cafc1c54d6b71ed6a6600cf0c1cb10434a447eae14015f1b23e2e6bedeed79df94a932e2164d2832280dce3fb32f656d1"
 }