google-apis-cli 0.2.0 → 0.4.0

package/dist/src/render.js

@@ -1,13 +1,27 @@
-export const SCHEMA_USAGE = 'gapi schema <api> <resource>[.<sub-resource>…].<method> | <SchemaName> [--resolve-refs]';
+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…>';
+export const FIELDS_USAGE = 'gapi fields ads|sa360 <words…> | ga4-data <words…> --property <id>';
+export const FIELDS_HELP = `${FIELDS_USAGE}
+Max 20 ranked lines: <name>  <kind>  <first sentence of the description>.
+  ads, sa360  GAQL names (resource attributes, metrics., segments.) from the discovery document, no request
+  ga4-data    GA4 dimensions and metrics, custom ones included: one properties getMetadata request
+              (--property 123 or properties/123; 0 = the ones common to all properties)
+No --cache. Discovery has no GAQL compatibility (selectable_with): check it with
+googleAdsFields.search (gapi ads googleAdsFields search; sa360: searchAds360Fields search)`;
+export const ENTITIES_USAGE = 'gapi entities sync [<api>…] [--page-limit <n>] | find <words…> [--api <api>]';
 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
+${FIELDS_USAGE}
+${ENTITIES_USAGE}
 ${SCHEMA_USAGE}
 ${DISCOVERY_USAGE}
 ${AUTH_USAGE}
@@ -95,6 +109,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`.
+export 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 +162,31 @@ 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('');
+}
+// #200 D7: one line per field, the shape of search hits.
+export function fieldsText(fields) {
+    return fields
+        .map((f) => `${`${f.name}  ${f.kind}  ${brief(f.description)}`.trimEnd()}\n`)
+        .join('');
+}
+// #200 D6: tabs keep empty cells (no name, parent or domain) unambiguous for `cut`.
+export function entitiesText(hits) {
+    return hits
+        .map((h) => {
+        const date = new Date(h.synced).toISOString().slice(0, 10);
+        const cells = [h.api, h.kind, h.id, h.name, h.parent, h.domain, date];
+        return `${cells.map((c = '') => c.replace(/[\t\r\n]+/g, ' ')).join('\t')}\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 +210,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,13 +1,17 @@
 // 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 { openEntities } from './entities.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 { send } from './transport.js';
+import { AUTH_USAGE, DISCOVERY_USAGE, ENTITIES_USAGE, entitiesText, FIELDS_HELP, FIELDS_USAGE, fieldsText, levelText, methodHelp, rootHelp, SCHEMA_USAGE, SEARCH_USAGE, schemaFind, schemaView, searchText, } from './render.js';
+import { MAX_AGE_MS, openResponses } from './responses.js';
+import { FIELD_APIS, ga4Fields, gaqlFields, matchQuery, rankFields, search, } from './search.js';
+import { receive, send } from './transport.js';
 const GLOBAL_OPTIONS = {
     params: { type: 'string' },
     body: { type: 'string' },
@@ -20,6 +24,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 +32,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 +62,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, entities, }) {
     // --help never starts a side effect: no server, no fetch, no file write.
     if (values.help) {
         io.stdout.write(`${AUTH_USAGE}\n`);
@@ -63,6 +85,8 @@ async function runAuth(sub, values, { io, creds, catalog }) {
     }
     if (sub === 'login') {
         const consent = await consentScopes(catalog);
+        // A new account starts with no stored responses and no entities.
+        await Promise.all([responses.clear(), entities.clear()]);
         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;
@@ -77,15 +101,162 @@ async function runAuth(sub, values, { io, creds, catalog }) {
     }
     if (sub === 'status') {
         const consent = await consentScopes(catalog);
-        io.stdout.write(`${JSON.stringify(await creds.status(consent), null, 2)}\n`);
+        printJson(io, `${JSON.stringify(await creds.status(consent))}\n`);
         return;
     }
     if (sub === 'logout') {
-        await creds.logout();
+        try {
+            await creds.logout();
+        }
+        finally {
+            // Also when the revoke fails: no account data stays on disk.
+            await Promise.all([responses.clear(), entities.clear()]);
+        }
         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}`);
+}
+// #200 D6: `sync` stores each API's entity sources; `find` searches them offline.
+async function runEntities(args, { io, creds, catalog, entities }) {
+    const parsed = parse(args, {
+        help: { type: 'boolean' },
+        api: { type: 'string' },
+        'page-limit': { type: 'string' },
+    });
+    const { values } = parsed;
+    const [sub, ...positionals] = parsed.positionals;
+    if (values.help) {
+        io.stdout.write(`${ENTITIES_USAGE}\n`);
+        return;
+    }
+    if (sub !== 'find' && sub !== 'sync')
+        throw new GapiError(3, `usage: ${ENTITIES_USAGE}`);
+    const other = sub === 'find' ? 'page-limit' : 'api';
+    if (values[other] !== undefined)
+        throw new GapiError(3, `--${other}: not an option of ${sub}`);
+    const identity = await creds.identity({ kind: 'oauth', scopes: [] });
+    const sourcesOf = (api) => {
+        if (!Object.hasOwn(catalog.entries, api))
+            throw new GapiError(3, `unknown api: ${api}`);
+        const sources = catalog.entries[api].entities ?? [];
+        if (sources.length === 0)
+            throw new GapiError(3, `${api} has no entity sources`);
+        return sources;
+    };
+    if (sub === 'find') {
+        const api = typeof values.api === 'string' ? values.api : undefined;
+        if (api !== undefined)
+            sourcesOf(api);
+        const { hits, empty } = await entities.find(positionals.join(' '), { api, identity });
+        if (empty)
+            io.stderr.write('gapi: entities index is empty or older than 7 days; run gapi entities sync\n');
+        if (hits.length === 0)
+            io.stderr.write('gapi: no match\n');
+        io.stdout.write(entitiesText(hits));
+        return;
+    }
+    const limit = typeof values['page-limit'] === 'string' ? values['page-limit'] : '10';
+    if (!/^[1-9]\d*$/.test(limit))
+        throw new GapiError(3, '--page-limit must be a positive integer');
+    const apis = positionals.length > 0
+        ? [...new Set(positionals)]
+        : Object.keys(catalog.entries)
+            .filter((a) => catalog.entries[a].entities?.length)
+            .toSorted();
+    const sources = apis.map((a) => ({ api: a, sources: sourcesOf(a) }));
+    if (identity === undefined)
+        throw new GapiError(2, 'no refresh token; run gapi auth login');
+    // Cost first: one call per top-level source, then one per parent entity of a child source.
+    const children = new Set();
+    const each = (api, list) => {
+        for (const s of list) {
+            for (const [kind, child] of Object.entries(s.children ?? {})) {
+                children.add(`${api} ${kind}`);
+                each(api, [child]);
+            }
+        }
+    };
+    for (const s of sources)
+        each(s.api, s.sources);
+    const top = sources.reduce((n, s) => n + s.sources.length, 0);
+    const then = [...children].map((c) => `, then 1 per ${c}`).join('');
+    io.stderr.write(`gapi: entities sync: ${top} list calls${then}; max ${limit} pages per list\n`);
+    let failed = 0;
+    for (const { api, sources: list } of sources) {
+        try {
+            // A source may call another entry's method (`api`); its settings and headers apply.
+            const request = async function* ({ api: owner = api, method, params, body, headers, }) {
+                const model = await catalog.load(owner);
+                const settings = await creds.settings({}, model.headers);
+                const paged = model.byId.get(method)?.paging !== undefined;
+                const call = plan(model, method, { params, body, pageAll: paged, pageLimit: paged ? limit : undefined }, { ...settings, headers: { ...settings.headers, ...headers } });
+                for (const w of call.warnings)
+                    io.stderr.write(`gapi: warning: ${w}\n`);
+                yield* receive(call, { fetch: io.fetch, authorize: creds.authorize, sleep: io.sleep });
+            };
+            const n = await entities.sync(api, list, identity, request);
+            io.stdout.write(`${api}: ${n} entities\n`);
+        }
+        catch (e) {
+            failed++;
+            io.stdout.write(`${api}: failed, old rows kept: ${messageOf(e)}\n`);
+        }
+    }
+    if (failed > 0)
+        throw new GapiError(1, `${failed} of ${sources.length} entity sources failed`);
+}
+// #200 D7: GAQL names offline from the discovery document, GA4 names from one getMetadata call.
+async function runFields(args, { io, creds, catalog }) {
+    const { values, positionals } = parse(args, {
+        property: { type: 'string' },
+        cache: { type: 'string' },
+        help: { type: 'boolean' },
+    });
+    if (values.help) {
+        io.stdout.write(`${FIELDS_HELP}\n`);
+        return;
+    }
+    // ADR 0001 keys a cache entry by the request, so two queries would share one entry.
+    if (values.cache !== undefined)
+        throw new GapiError(3, '--cache: fields is not cacheable');
+    const [name, ...words] = positionals;
+    if (name === undefined)
+        throw new GapiError(3, `usage: ${FIELDS_USAGE}`);
+    if (!FIELD_APIS.includes(name)) {
+        throw new GapiError(3, `fields: ${name} has no field source; supported: ${FIELD_APIS.join(', ')}`);
+    }
+    const query = words.join(' ');
+    matchQuery(query, FIELDS_USAGE); // no word → exit 3 before any document loads
+    const { property } = values;
+    if (name !== 'ga4-data' && property !== undefined) {
+        throw new GapiError(3, `--property: not an option of fields ${name}`);
+    }
+    if (name === 'ga4-data' && property === undefined) {
+        throw new GapiError(3, '--property is required');
+    }
+    const id = property?.replace(/^properties\//, '');
+    if (id !== undefined && !/^\d+$/.test(id)) {
+        throw new GapiError(3, `--property: ${property} is not a GA4 property id`);
+    }
+    const model = await catalog.load(name);
+    let fields = [];
+    if (id === undefined) {
+        fields = gaqlFields(model);
+    }
+    else {
+        const settings = await creds.settings({}, model.headers);
+        const call = plan(model, 'analyticsdata.properties.getMetadata', { params: { name: `properties/${id}/metadata` } }, settings);
+        for (const w of call.warnings)
+            io.stderr.write(`gapi: warning: ${w}\n`);
+        const opts = { fetch: io.fetch, authorize: creds.authorize, sleep: io.sleep };
+        for await (const data of receive(call, opts))
+            fields = ga4Fields(data);
+    }
+    const hits = rankFields(fields, query);
+    if (hits.length === 0)
+        io.stderr.write('gapi: no match\n');
+    io.stdout.write(fieldsText(hits));
 }
 // D8 consent set: every entry's per-method scope plus its entry scopes (identity is added by login).
 async function consentScopes(catalog) {
@@ -105,10 +276,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 +301,29 @@ async function dispatch(argv, io) {
         stdin: io.stdin,
         stderr: io.stderr,
     });
+    const responses = openResponses(join(dir, 'responses'));
+    await responses.sweep();
+    const entities = openEntities(join(dir, 'entities.db'));
+    // shortcut: a lock or disk error skips this run's sweep with a warning, the next run retries.
+    await entities.sweep().catch((e) => warn(`entities sweep skipped: ${messageOf(e)}`));
+    // 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 +334,31 @@ 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, entities });
+    }
+    if (api === 'entities')
+        return runEntities(rest, { io, creds, catalog, entities });
+    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 === 'fields')
+        return runFields(rest, { io, creds, catalog });
     if (api === 'schema') {
         const { values, positionals } = parse(rest, {
             'resolve-refs': { type: 'boolean' },
+            find: { type: 'string' },
             help: { type: 'boolean' },
         });
         if (values.help) {
@@ -145,9 +368,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 +438,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 +470,35 @@ 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 });
+}
+// The one JSON writer (epic #200 D2): compact lines stay as they are off a terminal (agents), each
+// line gets a 2-space indent on a terminal (operators).
+function printJson(io, lines) {
+    if (!io.stdout.isTTY)
+        return io.stdout.write(lines);
+    let text;
+    try {
+        const values = lines
+            .split('\n')
+            .filter(Boolean)
+            .map((l) => JSON.parse(l));
+        text = values.map((v) => `${JSON.stringify(v, null, 2)}\n`).join('');
+    }
+    catch {
+        text = lines; // a cache entry stored before #205 is already indented
+    }
+    return io.stdout.write(text);
 }
-// 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 +516,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`);
+        printJson(io, `${JSON.stringify(request)}\n`);
+        return;
+    }
+    if (stored !== undefined && mtime !== undefined) {
+        printJson(io, stored);
+        io.stderr.write(`gapi: cached response from ${new Date(mtime).toISOString()}\n`);
         return;
     }
-    await send(call, { fetch: io.fetch, authorize, out: io.stdout });
+    const chunks = [];
+    const out = {
+        write: (chunk) => {
+            chunks.push(chunk);
+            return printJson(io, 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`);
+    });
 }