google-apis-cli 0.2.0 → 0.4.0

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

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

package/dist/src/apis/youtube.js

@@ -1,4 +1,19 @@
+import { items, text } from '../entities.js';
+import { isRecord } from '../json.js';
 export default {
     api: 'youtube',
     discovery: 'https://youtube.googleapis.com/$discovery/rest?version=v3',
+    // The operator's own channels; the custom URL (@handle) joins the title in the name.
+    entities: [
+        {
+            method: 'youtube.channels.list',
+            params: () => ({ part: 'snippet', mine: true }),
+            entities: (data) => items(data, 'items').flatMap((c) => {
+                const id = text(c.id);
+                const s = isRecord(c.snippet) ? c.snippet : {};
+                const name = [text(s.title), text(s.customUrl)].filter(Boolean).join(' ');
+                return id ? [{ kind: 'channel', id, name: name || undefined }] : [];
+            }),
+        },
+    ],
 };

package/dist/src/catalog.js

@@ -8,10 +8,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // Catalog: the API entries found by glob, their discovery documents behind a
 // 24 h disk cache, and the one normalized ApiModel per API (epic #30 D2, D8, D13).
+import { randomUUID } from 'node:crypto';
 import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { GapiError } from './errors.js';
+import { GapiError, reasonOf } from './errors.js';
 import { isRecord, parseOrText } from './json.js';
 const TTL_MS = 24 * 60 * 60 * 1000;
 const AUTH_PREFIX = 'https://www.googleapis.com/auth/';
@@ -42,14 +43,17 @@ export async function openCatalog({ dir, fetch, warn, apisDir = join(import.meta
     async function document(entry, refresh) {
         const file = join(cacheDir, `${entry.api}.json`);
         const mtime = await stat(file).then((s) => s.mtimeMs, () => undefined);
-        if (!refresh && mtime !== undefined && Date.now() - mtime < TTL_MS) {
+        // A future mtime (clock skew) counts as stale, so no document freezes.
+        const age = mtime === undefined ? -1 : Date.now() - Math.floor(mtime); // mtimeMs has sub-ms digits, Date.now() not: a just-written file reads as future
+        if (!refresh && age >= 0 && age < TTL_MS) {
             const doc = await cached(file);
             if (doc)
                 return doc;
         }
         const got = await download(entry.discovery).catch((e) => e instanceof Error ? e : new Error(String(e)));
         if (!(got instanceof Error)) {
-            await writeAtomic(file, got.text);
+            // The document is already here; a read-only cache dir only costs the next fetch.
+            await writeAtomic(file, got.text).catch((e) => warn(`cannot cache the ${entry.api} document: ${reasonOf(e)}`));
             return got.doc;
         }
         const stale = mtime === undefined ? undefined : await cached(file);
@@ -72,6 +76,25 @@ export async function openCatalog({ dir, fetch, warn, apisDir = join(import.meta
     }
     return { entries, load, cacheDir };
 }
+// Every entity source of an entry, children included.
+export function entitySources(entry) {
+    const sources = [...(entry.entities ?? [])];
+    for (const source of sources)
+        sources.push(...Object.values(source.children ?? {}));
+    return sources;
+}
+// `discovery:check` part: entity sources that call another entry's method, checked against
+// that entry's model. Kept out of `load`, so one API never fetches another API's document.
+export function foreignSourceProblems(entry, models) {
+    return entitySources(entry).flatMap((s) => {
+        if (s.api === undefined || s.api === entry.api)
+            return [];
+        const model = models.get(s.api);
+        if (!model)
+            return [`entities ${s.api} ${s.method}: api not loaded`];
+        return model.byId.has(s.method) ? [] : [`entities ${s.api} ${s.method}: not in the document`];
+    });
+}
 // `https://www.googleapis.com/auth/x` → `x`; any other scope URL stays as is.
 export const shortScope = (scope) => scope.startsWith(AUTH_PREFIX) ? scope.slice(AUTH_PREFIX.length) : scope;
 const isNever = (scope) => {
@@ -119,6 +142,21 @@ function toModel(doc, entry) {
     overlay('paid', entry.paid, (m, v) => {
         m.paid = v;
     });
+    // Only a POST: a `reads` id on a write would let --cache store it and Transport resend it.
+    overlay('reads', Object.fromEntries((entry.reads ?? []).map((id) => [id, true])), (m) => {
+        if (m.httpMethod === 'POST')
+            m.read = true;
+        else
+            problems.push(`reads ${m.id}: ${m.httpMethod}, not a POST`);
+    });
+    // An entity source on a method the document lacks would fail every sync of the API. A
+    // source of another entry's method is checked by `foreignSourceProblems`.
+    for (const source of entitySources(entry)) {
+        if (source.api !== undefined && source.api !== entry.api)
+            continue;
+        if (!byId.has(source.method))
+            problems.push(`entities ${source.method}: not in the document`);
+    }
     return {
         ...root,
         api: entry.api,
@@ -129,6 +167,7 @@ function toModel(doc, entry) {
         documentationLink: doc.documentationLink,
         rootUrl: doc.rootUrl ?? '',
         servicePath: doc.servicePath ?? '',
+        batchPath: doc.batchPath ?? 'batch',
         auth,
         scopes,
         byId,
@@ -190,14 +229,17 @@ async function loadEntries(dir) {
         const name = basename(f, extname(f));
         if (e.api !== name)
             throw new Error(`${file}: api '${e.api}' must equal '${name}'`);
+        if (!/^[a-z0-9-]+$/.test(e.api))
+            throw new Error(`${file}: api '${e.api}' must match [a-z0-9-]+`);
         entries[e.api] = e;
     }
     return entries;
 }
-// Temp file + rename so a reader never sees a half-written document.
-async function writeAtomic(file, text) {
+// gcloud WriteFileAtomically: a new temp file (mode 600, `wx` never reuses a looser one),
+// flushed to disk, then renamed over the target; readers see the old or the new file.
+export async function writeAtomic(file, text) {
     await mkdir(dirname(file), { recursive: true, mode: 0o700 });
-    const tmp = `${file}.${process.pid}.tmp`;
-    await writeFile(tmp, text, { mode: 0o600 });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    await writeFile(tmp, text, { mode: 0o600, flag: 'wx', flush: true });
     await rename(tmp, file);
 }

package/dist/src/credentials.js

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

package/dist/src/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

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