google-apis-cli 0.3.0 → 0.4.1

package/dist/src/credentials.js

@@ -38,7 +38,18 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
     let apiKey;
     let tokenClient;
     let saving; // the refreshed-token write the 'tokens' event starts
-    const ask = (q, opts) => defaultPrompt(q, { ...opts, input: stdin, output: stderr });
+    // Each prompting command reads stdin through one session, closed when it ends (TTY raw mode).
+    const withPrompt = async (given, fn) => {
+        if (given)
+            return fn(given);
+        const p = openPrompt({ input: stdin, output: stderr });
+        try {
+            return await fn(p.ask);
+        }
+        finally {
+            p.close();
+        }
+    };
     // Only a missing file reads as {}: anything else stops before `setup` can overwrite it.
     // The parse error is not echoed, since V8 quotes the file text (secrets) in it.
     const readConfig = async () => {
@@ -171,7 +182,7 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
         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, }) {
+    async function login({ consent, manual = false, prompt, }) {
         const c = await client(REDIRECT_URI);
         const state = randomBytes(32).toString('base64url');
         const { codeVerifier, codeChallenge } = await c.generateCodeVerifierAsync();
@@ -206,7 +217,8 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
             stderr.write(`Open this URL and grant access:\n${url}\n` +
                 `After consent the browser cannot load ${LOOPBACK_HOST}:${LOOPBACK_PORT}; ` +
                 'paste the full URL from its address bar.\n');
-            const redirect = URL.parse((await prompt('redirected URL: ')).trim());
+            const answer = await withPrompt(prompt, (ask) => ask('redirected URL: '));
+            const redirect = URL.parse(answer.trim());
             if (!redirect)
                 throw new GapiError(2, 'not a URL; paste the full URL from the address bar');
             return redeem(redirect);
@@ -279,7 +291,7 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
         await rm(credentialsFile, { force: true });
     }
     // `headers`: every entry's header specs, tagged with the entry's api.
-    async function setup(headers, prompt = ask) {
+    async function setup(headers, prompt) {
         const cfg = await readConfig();
         const fields = [
             ...CLIENT_FIELDS,
@@ -291,15 +303,17 @@ export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(o
             })),
             API_KEY_FIELD,
         ];
-        for (const { key, label, required, secret } of fields) {
-            const cur = cfg[key];
-            const hint = cur != null ? ' [keep current]' : required ? '' : ' (blank to skip)';
-            const v = (await prompt(`${label}${hint}: `, { secret })).trim();
-            if (v)
-                cfg[key] = v;
-            else if (required && cur == null)
-                throw new GapiError(3, `${label} is required`);
-        }
+        await withPrompt(prompt, async (ask) => {
+            for (const { key, label, required, secret } of fields) {
+                const cur = cfg[key];
+                const hint = cur != null ? ' [keep current]' : required ? '' : ' (blank to skip)';
+                const v = (await ask(`${label}${hint}: `, { secret })).trim();
+                if (v)
+                    cfg[key] = v;
+                else if (required && cur == null)
+                    throw new GapiError(3, `${label} is required`);
+            }
+        });
         await writeSecure(configFile, cfg);
         return configFile;
     }
@@ -318,25 +332,47 @@ function accountFromIdToken(idToken) {
         return null;
     }
 }
-// `secret: true` keeps the typed value off the screen. Node has no masking
-// option, so point readline's echo at a sink and print the question ourselves.
-// `terminal: true` is what makes this safe: it puts the tty in raw mode, so the
-// driver stops echoing too and the sink is the only writer left. Streams are
-// injected (Credentials passes the ones `run` got), so the masking has a test.
-export async function defaultPrompt(q, { secret = false, input, output, terminal, }) {
-    if (secret)
-        output.write(q);
+// `secret: true` keeps the typed value off the screen. Node has no masking option.
+// So readline echoes through a gate that drops writes during a secret.
+// TTY raw mode stops the driver echo; a pipe echoes nothing.
+export function openPrompt({ input, output, terminal, }) {
+    let muted = false; // a secret: drop the terminal echo of what the user types
     const rl = createInterface({
         input,
-        output: secret ? new Writable({ write: (_c, _e, cb) => cb() }) : output,
-        terminal: secret ? true : terminal,
+        output: new Writable({
+            write: (c, _e, cb) => {
+                if (!muted)
+                    output.write(c);
+                cb();
+            },
+        }),
+        terminal: terminal ?? ('isTTY' in input && input.isTTY === true),
     });
-    try {
-        return await rl.question(secret ? '' : q);
-    }
-    finally {
-        rl.close();
-        if (secret)
-            output.write('\n'); // the swallowed Enter never printed one
-    }
+    // One reader per session, made before any await: a pipe sends all answers in one chunk (#233).
+    const lines = rl[Symbol.asyncIterator]();
+    let ended = false; // input closed: buffered lines remain, but `rl.prompt` throws
+    rl.on('close', () => {
+        ended = true;
+    });
+    const ask = async (q, { secret = false } = {}) => {
+        muted = secret;
+        if (secret || ended)
+            output.write(q);
+        else {
+            rl.setPrompt(q); // terminal mode redraws the prompt on line edits
+            rl.prompt();
+        }
+        try {
+            const { value, done } = await lines.next();
+            if (done)
+                throw new GapiError(3, `input ended before an answer to: ${q.trim()}`);
+            return value;
+        }
+        finally {
+            muted = false;
+            if (secret)
+                output.write('\n'); // the swallowed Enter (TTY) or the pipe never printed one
+        }
+    };
+    return { ask, close: () => rl.close() };
 }

package/dist/src/entities.js

@@ -0,0 +1,180 @@
+// Entities (#200 D6, ADR 0002): the offline index of the operator's own accounts, properties
+// and sites in <config dir>/entities.db, mode 600. Rows hold the Credentials identity and live
+// at most 7 days; login and logout delete the file. Nothing here ever picks an ID for a call.
+// shortcut: DatabaseSync is a deprecated alias of Database since Node v26.11.0 (DEP0210), switch
+// when @types/node types Database.
+import { existsSync } from 'node:fs';
+import { mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { GapiError } from './errors.js';
+import { isRecord } from './json.js';
+import { MAX_AGE_MS } from './responses.js';
+const VERSION = 1; // PRAGMA user_version; another value drops the file, sync rebuilds it
+const NOT_A_DATABASE = 26; // SQLITE_NOTADB: the file is dropped like another version
+const BUSY_MS = 5000; // another gapi process may hold the write lock
+const SCHEMA = `create virtual table if not exists entity using fts5(
+  api unindexed, kind unindexed, id, name, parent, domain, identity unindexed, synced unindexed,
+  tokenize = 'trigram')`;
+// Domain key: URL host, lower case (IDN as punycode), no leading `www.`.
+// shortcut: no public-suffix parsing, so `shop.acme.com` does not link to `acme.com`; upgrade
+// when a source needs subdomain linking.
+export function domainOf(uri) {
+    if (typeof uri !== 'string' || uri === '')
+        return undefined;
+    const bare = uri.replace(/^sc-domain:/, '');
+    const url = URL.parse(/^[a-z][a-z\d+.-]*:\/\//i.test(bare) ? bare : `https://${bare}`);
+    return url?.hostname.replace(/^www\./, '') || undefined;
+}
+// The record items of `data[key]`, for a source's `entities` mapping.
+export const items = (data, key) => isRecord(data) && Array.isArray(data[key]) ? data[key].filter(isRecord) : [];
+export const text = (v) => typeof v === 'string' && v ? v : undefined;
+// Schema version; undefined for a file that is not a database. Any other error (a lock) throws,
+// so a busy index is never dropped.
+function versionOf(db) {
+    try {
+        return Number(db.prepare('pragma user_version').get()?.user_version);
+    }
+    catch (e) {
+        if (e instanceof Error && 'errcode' in e && e.errcode === NOT_A_DATABASE)
+            return undefined;
+        throw e;
+    }
+}
+export function openEntities(file) {
+    const clear = async () => {
+        await Promise.all(['', '-journal'].map((s) => rm(`${file}${s}`, { force: true })));
+    };
+    // Created mode 600 before SQLite opens it (SQLite gives its journal the same mode). `fresh`:
+    // the file is empty, so it is new (or a racing process has not written it yet).
+    const create = async () => {
+        await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+        await writeFile(file, '', { mode: 0o600, flag: 'a' });
+        const fresh = (await stat(file)).size === 0;
+        return { db: new DatabaseSync(file, { timeout: BUSY_MS }), fresh };
+    };
+    // A new file gets the schema in place. A file of another schema version, or not a database
+    // at all, is dropped and rebuilt empty.
+    async function open() {
+        let { db, fresh } = await create();
+        try {
+            if (!fresh && versionOf(db) === VERSION)
+                return db;
+            if (!fresh) {
+                db.close();
+                await clear();
+                ({ db } = await create());
+            }
+            db.exec(SCHEMA);
+            db.exec(`pragma user_version = ${VERSION}`);
+            return db;
+        }
+        catch (e) {
+            if (db.isOpen)
+                db.close();
+            throw e;
+        }
+    }
+    async function use(fn) {
+        const db = await open();
+        try {
+            return fn(db);
+        }
+        finally {
+            db.close();
+        }
+    }
+    // Every run: rows older than the response cache max age go (ADR 0001 terms, ADR 0002).
+    async function sweep() {
+        if (!existsSync(file))
+            return;
+        await use((db) => db.prepare('delete from entity where synced < ?').run(Date.now() - MAX_AGE_MS));
+    }
+    // Reads every source of one API, then replaces that API's rows in one transaction; a
+    // failed call throws before the write, so the old rows stay. Rows of one kind and ID merge
+    // (later defined fields win), so a child can add a domain or name. Returns the row count.
+    async function sync(api, sources, identity, request) {
+        const merged = new Map();
+        const walk = async (source, parent) => {
+            const found = [];
+            const call = {
+                api: source.api,
+                method: source.method,
+                params: source.params?.(parent) ?? {},
+                body: source.body?.(parent),
+                headers: source.headers?.(parent),
+            };
+            for await (const page of request(call))
+                found.push(...source.entities(page, parent));
+            for (const e of found) {
+                const key = `${e.kind}\0${e.id}`;
+                const was = merged.get(key);
+                merged.set(key, {
+                    ...e,
+                    name: e.name ?? was?.name,
+                    parent: e.parent ?? was?.parent,
+                    domain: e.domain ?? was?.domain,
+                });
+            }
+            for (const e of found) {
+                const { children } = source;
+                const child = children && Object.hasOwn(children, e.kind) ? children[e.kind] : undefined;
+                if (child)
+                    await walk(child, e);
+            }
+        };
+        for (const source of sources)
+            await walk(source);
+        const rows = [...merged.values()];
+        const now = Date.now();
+        return use((db) => {
+            db.exec('begin');
+            try {
+                db.prepare('delete from entity where api = ? and identity = ?').run(api, identity);
+                const insert = db.prepare('insert into entity values (?, ?, ?, ?, ?, ?, ?, ?)');
+                for (const r of rows) {
+                    insert.run(api, r.kind, r.id, r.name ?? '', r.parent ?? '', r.domain ?? '', identity, now);
+                }
+                db.exec('commit');
+            }
+            catch (e) {
+                db.exec('rollback');
+                throw e;
+            }
+            return rows.length;
+        });
+    }
+    // Trigram match of each whitespace-separated term (any substring of 3+ characters), joined
+    // by OR, best 20 by bm25. Each term is one quoted FTS5 string, so no FTS5 syntax reaches the
+    // match. `empty`: the identity has no row (for `api`) at all.
+    async function find(query, { api, identity }) {
+        const terms = query.split(/\s+/).filter(Boolean);
+        const short = terms.find((t) => [...t].length < 3);
+        if (terms.length === 0 || short !== undefined) {
+            throw new GapiError(3, `find: each term needs 3 or more characters${short ? `: '${short}'` : ''}`);
+        }
+        if (identity === undefined || !existsSync(file))
+            return { hits: [], empty: true };
+        const match = terms.map((t) => `"${t.replaceAll('"', '""')}"`).join(' OR ');
+        return use((db) => {
+            const scope = 'identity = ? and (? is null or api = ?)';
+            const count = db.prepare(`select count(*) as n from entity where ${scope}`);
+            const empty = count.get(identity, api ?? null, api ?? null)?.n === 0;
+            const hits = db
+                .prepare(`select api, kind, id, name, parent, domain, synced from entity
+           where entity match ? and ${scope} order by rank limit 20`)
+                .all(match, identity, api ?? null, api ?? null)
+                .map((r) => ({
+                api: String(r.api),
+                kind: String(r.kind),
+                id: String(r.id),
+                name: text(r.name),
+                parent: text(r.parent),
+                domain: text(r.domain),
+                synced: Number(r.synced),
+            }));
+            return { hits, empty };
+        });
+    }
+    return { sync, find, sweep, clear };
+}

package/dist/src/plan.js

@@ -80,7 +80,7 @@ export function plan(model, target, input, settings) {
     if (input.body !== undefined && !method.request)
         throw invalid(`--body: ${command} takes no request body`);
     const mode = sendMode(method, command, input);
-    const body = mode.send === 'pages' && mode.paging === 'body' ? mode.body : input.body;
+    const body = mode.send === 'pages' && method.paging === 'body' ? pagingBody(input) : input.body;
     const url = buildUrl(model, method, values, mode);
     const headers = contentHeaders(mode, body !== undefined);
     if (model.auth === 'oauth' && settings.project)
@@ -163,13 +163,27 @@ function sendMode(method, command, input) {
     if (!/^[1-9]\d*$/.test(limit))
         throw invalid('--page-limit must be a positive integer');
     const pageLimit = Number(limit);
-    if (method.paging === 'query')
-        return { send: 'pages', pageLimit, paging: 'query' };
-    // Body paging: every page sends this object, from page 2 on with pageToken set (D6).
+    return { send: 'pages', pageLimit, follow: nextPage(method.paging) };
+}
+// Body paging: every page sends this object, from page 2 on with pageToken set (D6).
+function pagingBody(input) {
     const body = input.body ?? {};
     if (!isRecord(body))
         throw invalid('--page-all: --body must be a JSON object');
-    return { send: 'pages', pageLimit, paging: 'body', body };
+    return body;
+}
+// AIP-158 follow rule: repeat the request with only pageToken changed, until no nextPageToken.
+function nextPage(paging) {
+    return (data, last) => {
+        const token = isRecord(data) ? data.nextPageToken : undefined;
+        if (typeof token !== 'string' || !token)
+            return undefined;
+        if (paging === 'body')
+            return { ...last, body: { ...(isRecord(last.body) && last.body), pageToken: token } };
+        const url = new URL(last.url);
+        url.searchParams.set('pageToken', token);
+        return { ...last, url: url.href };
+    };
 }
 // D7: protocol defaults to multipart with --body, else media; the type must fit `accept`.
 function upload(method, command, path, input, hasBody) {

package/dist/src/render.js

@@ -1,9 +1,17 @@
-// 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…>';
+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>]] [--cache <age>] [--dry-run]
@@ -12,6 +20,8 @@ gapi <api> [<resource>…]                  list sub-resources and methods
 gapi <api> <resource>… <method> --help    method help
 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}
@@ -100,7 +110,7 @@ const oneLine = (description = '') => description
     .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) => {
+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;
@@ -161,6 +171,22 @@ export function searchText(hits) {
     })
         .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.