google-apis-cli 0.3.0 → 0.4.1

package/dist/src/run.js

@@ -4,13 +4,14 @@ 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, SEARCH_USAGE, schemaFind, schemaView, searchText, } from './render.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 { matchQuery, search } from './search.js';
-import { send } from './transport.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' },
@@ -76,7 +77,7 @@ function parse(args, options) {
         throw e instanceof GapiError ? e : new GapiError(3, messageOf(e));
     }
 }
-async function runAuth(sub, values, { io, creds, catalog, responses, }) {
+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`);
@@ -84,7 +85,8 @@ async function runAuth(sub, values, { io, creds, catalog, responses, }) {
     }
     if (sub === 'login') {
         const consent = await consentScopes(catalog);
-        await responses.clear(); // a new account starts with no stored responses
+        // 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;
@@ -99,7 +101,7 @@ async function runAuth(sub, values, { io, creds, catalog, responses, }) {
     }
     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') {
@@ -107,13 +109,155 @@ async function runAuth(sub, values, { io, creds, catalog, responses, }) {
             await creds.logout();
         }
         finally {
-            await responses.clear(); // also when the revoke fails: no account data stays on disk
+            // 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, 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) {
     const models = await Promise.all(Object.keys(catalog.entries).map((api) => catalog.load(api)));
@@ -159,6 +303,9 @@ async function dispatch(argv, io) {
     });
     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) => {
@@ -187,8 +334,10 @@ async function dispatch(argv, io) {
             manual: { type: 'boolean' },
             help: { type: 'boolean' },
         });
-        return runAuth(positionals[0], values, { io, creds, catalog, responses });
+        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')) {
@@ -204,6 +353,8 @@ async function dispatch(argv, io) {
         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' },
@@ -322,6 +473,24 @@ async function dispatch(argv, io) {
     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), 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 }) {
@@ -349,11 +518,11 @@ async function perform(call, dryRun, io, authorize, { responses, cache }) {
                 : 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) {
-        io.stdout.write(stored);
+        printJson(io, stored);
         io.stderr.write(`gapi: cached response from ${new Date(mtime).toISOString()}\n`);
         return;
     }
@@ -361,7 +530,7 @@ async function perform(call, dryRun, io, authorize, { responses, cache }) {
     const out = {
         write: (chunk) => {
             chunks.push(chunk);
-            return io.stdout.write(chunk);
+            return printJson(io, chunk);
         },
     };
     await send(call, { fetch: io.fetch, authorize, out, sleep: io.sleep });

package/dist/src/search.js

@@ -1,27 +1,81 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 // 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';
+import { isRecord } from './json.js';
+import { brief, FIELDS_USAGE, 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) {
+export function matchQuery(query, usage = SEARCH_USAGE) {
     const tokens = split(query)
         .toLowerCase()
         .match(/[\p{L}\p{N}]+/gu);
     if (!tokens)
-        throw new GapiError(3, `usage: ${SEARCH_USAGE}`);
+        throw new GapiError(3, `usage: ${usage}`);
     return tokens.map((t) => `"${t}"`).join(' OR ');
 }
 export function search(models, query) {
-    const match = matchQuery(query);
-    const db = new DatabaseSync(':memory:');
+    const env_1 = { stack: [], error: void 0, hasError: false };
     try {
+        const match = matchQuery(query);
+        const db = __addDisposableResource(env_1, new DatabaseSync(':memory:'), false);
         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');
@@ -47,7 +101,108 @@ export function search(models, query) {
             return model && method ? [{ model, method }] : [];
         });
     }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}
+export const FIELD_APIS = ['ads', 'ga4-data', 'sa360'];
+const snake = (camel) => split(camel).replaceAll(' ', '_').toLowerCase();
+// Proto field behavior marks open most Ads descriptions; the sentence after them says more.
+const FIELD_MARKS = /^(?:(?:Output only|Immutable|Required|Optional)\.\s*)+/;
+const GAQL_ROOT = /(?:Resources__(\w+)|Common__(Metrics|Segments))$/;
+const isResource = (ref) => typeof ref === 'string' && /Resources__/.test(ref);
+// Singular message fields expand to their leaves (`campaign.network_settings.target_google_search`);
+// arrays stay one field. A message that only holds other resources stays one field, as
+// `change_event.old_resource` in Google's GAQL examples.
+// shortcut: names follow the discovery shape, not Google's selectable list; selectability
+// (`selectable_with`) needs googleAdsFields.search.
+export function gaqlFields(model) {
+    const fields = [];
+    const walk = (schema, path, kind, seen) => {
+        const props = isRecord(schema.properties) ? Object.entries(schema.properties) : [];
+        for (const [key, prop] of props) {
+            if (!isRecord(prop))
+                continue;
+            const name = `${path}.${snake(key)}`;
+            const ref = typeof prop.$ref === 'string' ? prop.$ref : undefined;
+            const target = ref && !seen.includes(ref) ? model.schemas.get(ref) : undefined;
+            const inner = isRecord(target?.properties) ? Object.values(target.properties) : [];
+            if (target && ref && !inner.every((p) => isRecord(p) && isResource(p.$ref))) {
+                walk(target, name, kind, [...seen, ref]);
+            }
+            else {
+                const text = typeof prop.description === 'string' ? prop.description : '';
+                fields.push({ name, kind, description: text.replace(FIELD_MARKS, '') });
+            }
+        }
+    };
+    for (const [id, schema] of model.schemas) {
+        const m = GAQL_ROOT.exec(id);
+        if (!m)
+            continue;
+        const root = m[1] ? snake(m[1]) : m[2].toLowerCase();
+        const kind = m[1] ? 'attribute' : m[2] === 'Metrics' ? 'metric' : 'segment';
+        walk(schema, root, kind, [id]);
+    }
+    return fields;
+}
+// GA4 Metadata: dimensions and metrics; the UI name and deprecated names rank too.
+export function ga4Fields(metadata) {
+    const list = (key, kind) => {
+        const items = isRecord(metadata) && Array.isArray(metadata[key]) ? metadata[key] : [];
+        return items.filter(isRecord).flatMap((d) => {
+            if (typeof d.apiName !== 'string')
+                return [];
+            const old = Array.isArray(d.deprecatedApiNames) ? d.deprecatedApiNames : [];
+            const words = [d.uiName, ...old].filter((w) => typeof w === 'string').join(' ');
+            const description = typeof d.description === 'string' ? d.description : undefined;
+            return [{ name: d.apiName, kind, words, description }];
+        });
+    };
+    return [...list('dimensions', 'dimension'), ...list('metrics', 'metric')];
+}
+// FTS5 bm25 normalizes by the whole row's length, so names and descriptions sit in two tables:
+// a long description does not bury a short name. A description match counts a third.
+export function rankFields(fields, query) {
+    const env_2 = { stack: [], error: void 0, hasError: false };
+    try {
+        const match = matchQuery(query, FIELDS_USAGE);
+        const db = __addDisposableResource(env_2, new DatabaseSync(':memory:'), false);
+        db.exec(`create virtual table n using fts5(i unindexed, name, words, tokenize = 'porter unicode61');
+    create virtual table d using fts5(i unindexed, descr, tokenize = 'porter unicode61')`);
+        const names = db.prepare('insert into n values (?, ?, ?)');
+        const descrs = db.prepare('insert into d values (?, ?)');
+        db.exec('begin');
+        fields.forEach((f, i) => {
+            // Each name word once: a nested path repeats words (`budget…budget`).
+            names.run(i, [...new Set(split(f.name).toLowerCase().split(' '))].join(' '), split(f.words ?? ''));
+            descrs.run(i, brief(f.description));
+        });
+        db.exec('commit');
+        const ranked = db
+            .prepare(`select i, sum(s) as score from (
+         select i, bm25(n, 0, 2, 1) as s from n where n match ?
+         union all select i, bm25(d) / 3 from d where d match ?)
+       group by i order by score, i`)
+            .all(match, match)
+            .map(({ i }) => fields[Number(i)]);
+        // Fields whose last name part is exactly the query come first, in rank order.
+        const key = (text) => split(text)
+            .toLowerCase()
+            .match(/[\p{L}\p{N}]+/gu)
+            ?.join(' ');
+        const exact = (f) => key(f.name.slice(f.name.lastIndexOf('.') + 1)) === key(query);
+        return [...ranked.filter(exact), ...ranked.filter((f) => !exact(f))].slice(0, 20);
+    }
+    catch (e_2) {
+        env_2.error = e_2;
+        env_2.hasError = true;
+    }
     finally {
-        db.close();
+        __disposeResources(env_2);
     }
 }

package/dist/src/transport.js

@@ -1,4 +1,4 @@
-// Transport: sends a CallPlan and prints the response (epic #30 D13).
+// Transport: sends a CallPlan and yields or prints its responses (epic #30 D13, #200 D3).
 // `authorize` adds the credential before every request; a non-2xx exits 1, a missing scope 2.
 import { setTimeout } from 'node:timers/promises';
 import { GapiError, reasonOf } from './errors.js';
@@ -7,15 +7,23 @@ 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';
+// Prints each response as one compact JSON line; `run` picks the final form (epic #200 D2).
 export async function send(plan, deps) {
+    for await (const data of receive(plan, deps)) {
+        deps.out.write(`${JSON.stringify(data)}\n`);
+    }
+}
+// Yields each decoded response of a plan; a decode result of `undefined` is not yielded.
+// A batch yields its results before it throws a failure: the parts sent were acted on.
+export async function* receive(plan, deps) {
     const call = caller(plan, deps);
-    const print = (data) => deps.out.write(`${JSON.stringify(data, null, 2)}\n`);
+    const decode = (data, step) => (plan.decode ? plan.decode(data, step) : data);
     if (plan.send === 'upload') {
-        print(await json(await upload(plan, call, deps.sleep ?? setTimeout)));
+        yield* some(decode(await json(await upload(plan, call, deps.sleep ?? setTimeout))));
         return;
     }
     if (plan.send === 'download') {
-        print(await download(plan, call));
+        yield* some(decode(await download(plan, call)));
         return;
     }
     if (plan.send === 'batch') {
@@ -24,9 +32,8 @@ export async function send(plan, deps) {
             status,
             body: text ? parseOrText(text) : undefined,
         }));
-        // Results print before any failure: the parts already sent were acted on.
         if (results.length > 0 || !sent.error)
-            print(plan.decode ? plan.decode(results) : results);
+            yield* some(decode(results));
         if (sent.error)
             throw sent.error;
         const failed = sent.results.filter((r) => r.status < 200 || r.status > 299);
@@ -39,41 +46,41 @@ export async function send(plan, deps) {
         }
         return;
     }
-    const init = {
-        method: plan.httpMethod,
+    const fetchStep = async (step) => json(await call(step.url, {
+        method: step.httpMethod,
         headers: plan.headers,
-        body: plan.body === undefined ? undefined : JSON.stringify(plan.body),
-    };
+        body: step.body === undefined ? undefined : JSON.stringify(step.body),
+    }));
+    let step = { httpMethod: plan.httpMethod, url: plan.url, body: plan.body };
     if (plan.send === 'once') {
-        const data = await json(await call(plan.url, init));
-        print(plan.decode ? plan.decode(data) : data);
+        yield* some(decode(await fetchStep(step), step));
         return;
     }
-    // D6: one compact JSON line per page, until no nextPageToken or pageLimit pages. The next
-    // page repeats the call with only pageToken changed (AIP-158), in the query or the body.
-    const url = new URL(plan.url);
-    let pageInit = init;
-    for (let page = 1; page <= plan.pageLimit; page++) {
-        const data = await json(await call(url.href, pageInit));
-        deps.out.write(`${JSON.stringify(data)}\n`);
-        const token = isRecord(data) ? data.nextPageToken : undefined;
-        if (typeof token !== 'string' || !token)
-            return;
-        if (plan.paging === 'query') {
-            url.searchParams.set('pageToken', token);
-        }
-        else {
-            pageInit = { ...init, body: JSON.stringify({ ...plan.body, pageToken: token }) };
+    // D3: follow the rule until it stops or pageLimit responses were yielded.
+    for (let yielded = 0; step && yielded < plan.pageLimit;) {
+        const data = await fetchStep(step);
+        const decoded = decode(data, step);
+        if (decoded !== undefined) {
+            yielded++;
+            yield decoded;
         }
+        step = plan.follow(data, step);
     }
 }
+function* some(data) {
+    if (data !== undefined)
+        yield data;
+}
 // Uploads and batches never retry here; a resumable upload resumes on its own.
-function caller(plan, { fetch, authorize, sleep = setTimeout }) {
+function caller(plan, { fetch, authorize, signal, sleep = (ms) => setTimeout(ms, undefined, { signal }) }) {
     const retry = plan.retry && plan.send !== 'upload' && plan.send !== 'batch';
     return async (url, init, allowed) => {
         for (let attempt = 0;; attempt++) {
+            signal?.throwIfAborted(); // a deadline that passed during a backoff stops the retries
             const headers = { ...init.headers, ...(await authorize(plan.auth)) };
-            const res = await fetch(url, { ...init, headers }).catch((e) => {
+            const res = await fetch(url, { ...init, headers, ...(signal && { signal }) }).catch((e) => {
+                if (signal?.aborted)
+                    throw signal.reason; // a deadline is never retried
                 const cause = e instanceof Error && e.cause !== undefined ? e.cause : e;
                 return new NetworkError(1, `network: ${reasonOf(cause)}`);
             });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "google-apis-cli",
-  "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.",
+  "version": "0.4.1",
+  "description": "One discovery-driven CLI (gapi) for 49 Google marketing and data APIs: Ads, GA4, Search Console, Tag Manager, Indexing, Merchant, Business Profile, SA360, CM360, DV360, YouTube, PageSpeed, CrUX, BigQuery, Sheets, Places and more. One login, read+write.",
   "type": "module",
   "bin": {
     "gapi": "dist/bin/gapi.js"
@@ -55,13 +55,13 @@
     "url": "https://github.com/realroboto/google-apis-cli/issues"
   },
   "dependencies": {
-    "google-auth-library": "^11.3.3"
+    "google-auth-library": "^11.3.4"
   },
   "license": "MIT",
   "devDependencies": {
-    "@biomejs/biome": "^2.6.5",
+    "@biomejs/biome": "^2.6.7",
     "@types/node": "^26.6.6",
     "typescript": "^7.0.2"
   },
-  "packageManager": "pnpm@12.16.1+sha512.091d1dee7927575661b25dab3c2ae31cafc1c54d6b71ed6a6600cf0c1cb10434a447eae14015f1b23e2e6bedeed79df94a932e2164d2832280dce3fb32f656d1"
+  "packageManager": "pnpm@12.18.0+sha512.9d7882d5dc82147ecfc4e062aa34834e0ad0296710a1837a1115ae012127d36b7109e321ac1598a1dd0a65597681b1e99917e12ed0d749eae91187943363beb3"
 }