google-apis-cli 0.3.0 → 0.4.0

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.0",
+  "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"
 }