google-apis-cli 0.1.0 → 0.2.0

package/dist/src/credentials.js

@@ -0,0 +1,316 @@
+// 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 { 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 { codeOf, GapiError, messageOf } from './errors.js';
+import { isRecord } from './json.js';
+const LOOPBACK_HOST = '127.0.0.1';
+const LOOPBACK_PORT = 4600; // fixed port; vmCODE forwards it for headless use
+const REDIRECT_URI = `http://${LOOPBACK_HOST}:${LOOPBACK_PORT}`; // both login flows
+const IDENTITY_SCOPES = ['openid', 'email'];
+const RELOGIN = 'run gapi auth login';
+const NO_KEY = 'API key required; pass --api-key, set GAPI_API_KEY or run gapi auth setup';
+// `||`, not `??`: an empty GAPI_CONFIG_DIR must not resolve secrets into the cwd.
+export const configDir = (env) => env.GAPI_CONFIG_DIR || join(homedir(), '.config', 'gapi');
+const API_KEY_SETTING = { flag: 'api-key', env: 'GAPI_API_KEY', key: 'api_key' };
+// `gapi auth setup` asks the OAuth client, then each entry header, then the API key.
+const CLIENT_FIELDS = [
+    { key: 'oauth_client_id', label: 'OAuth client id', required: true, secret: false },
+    { key: 'oauth_client_secret', label: 'OAuth client secret', required: true, secret: true },
+];
+const API_KEY_FIELD = {
+    key: 'api_key',
+    label: 'API key (optional, CrUX/PageSpeed)',
+    required: false,
+    secret: true,
+};
+const isCredentials = (v) => isRecord(v) && typeof v.refresh_token === 'string';
+export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(opts), warn = () => { }, stdin = process.stdin, stderr = process.stderr, }) {
+    const configFile = join(dir, 'config.json');
+    const credentialsFile = join(dir, 'credentials.json');
+    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 });
+    // 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 () => {
+        let text;
+        try {
+            text = await readFile(configFile, 'utf8');
+        }
+        catch (e) {
+            if (codeOf(e) === 'ENOENT')
+                return {};
+            throw new GapiError(2, `cannot read ${configFile}: ${messageOf(e)}`);
+        }
+        let cfg;
+        try {
+            cfg = JSON.parse(text);
+        }
+        catch {
+            throw new GapiError(2, `${configFile} is not valid JSON; fix or remove it`);
+        }
+        if (!isRecord(cfg))
+            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.
+    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);
+    };
+    const readCredentials = async () => {
+        let creds;
+        try {
+            creds = JSON.parse(await readFile(credentialsFile, 'utf8'));
+        }
+        catch {
+            // missing or unreadable reads as logged out, same as a bad shape below
+        }
+        if (!isCredentials(creds))
+            throw new GapiError(2, `not logged in; ${RELOGIN}`);
+        return creds;
+    };
+    const client = async (redirectUri) => {
+        const cfg = await readConfig();
+        const clientId = env.GAPI_OAUTH_CLIENT_ID || String(cfg.oauth_client_id ?? '');
+        const clientSecret = env.GAPI_OAUTH_CLIENT_SECRET || String(cfg.oauth_client_secret ?? '');
+        if (!clientId || !clientSecret) {
+            throw new GapiError(2, 'OAuth client not configured; run gapi auth setup');
+        }
+        return oauth({ clientId, clientSecret, redirectUri });
+    };
+    // Exchange a consent code (with its PKCE verifier) for tokens and persist them.
+    const exchange = async (c, code, codeVerifier) => {
+        const { tokens } = await c.getToken({ code, codeVerifier }).catch((e) => {
+            throw new GapiError(2, `token exchange failed: ${messageOf(e)}`);
+        });
+        await writeSecure(credentialsFile, tokens);
+        return tokens;
+    };
+    // Precedence flag → env → config file; an empty env var falls through, as in `configDir`.
+    const setting = (flags, cfg, { flag, env: name, key }) => {
+        const v = flags[flag] ?? (env[name] || cfg[key]);
+        return v == null ? undefined : String(v);
+    };
+    async function settings(flags, headerSpecs = []) {
+        const cfg = await readConfig();
+        apiKey = setting(flags, cfg, API_KEY_SETTING);
+        const headers = {};
+        for (const { name, flag, env: envName, configKey } of headerSpecs) {
+            const v = setting(flags, cfg, { flag, env: envName, key: configKey });
+            if (v !== undefined)
+                headers[name] = v;
+        }
+        const project = setting(flags, cfg, {
+            flag: 'project',
+            env: 'GOOGLE_CLOUD_PROJECT',
+            key: 'project',
+        });
+        return { project, headers };
+    }
+    const authorize = async (auth, { redact = false } = {}) => {
+        if (auth.kind === 'apiKey') {
+            // D8: a method that lists no scope needs the key; one with only never-set scopes may omit it.
+            if (apiKey === undefined) {
+                if (auth.scopes.length > 0)
+                    return {};
+                if (!redact)
+                    throw new GapiError(2, NO_KEY);
+                warn(NO_KEY);
+            }
+            return { 'X-Goog-Api-Key': redact ? '<redacted>' : String(apiKey) };
+        }
+        if (redact)
+            return { Authorization: 'Bearer <redacted>' };
+        if (!tokenClient) {
+            const c = await client();
+            c.setCredentials(await readCredentials());
+            // An event listener is not awaited: keep the write so the refresh below can await it.
+            c.on('tokens', (t) => {
+                saving = readCredentials().then((stored) => writeSecure(credentialsFile, { ...stored, ...t }));
+            });
+            tokenClient = c;
+        }
+        const { token } = await tokenClient.getAccessToken().catch((e) => {
+            const data = isRecord(e) && isRecord(e.response) ? e.response.data : undefined;
+            const reason = isRecord(data) ? data.error : undefined;
+            if (reason === 'invalid_grant')
+                throw new GapiError(2, `token expired or revoked; ${RELOGIN}`);
+            throw new GapiError(2, `token refresh failed: ${messageOf(e)}; ${RELOGIN}`);
+        });
+        const saved = saving;
+        saving = undefined;
+        await saved?.catch((e) => {
+            throw new GapiError(2, `cannot save the refreshed token: ${messageOf(e)}`);
+        });
+        if (!token)
+            throw new GapiError(2, `no access token; ${RELOGIN}`);
+        return { Authorization: `Bearer ${token}` };
+    };
+    // 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);
+        const state = randomBytes(32).toString('base64url');
+        const { codeVerifier, codeChallenge } = await c.generateCodeVerifierAsync();
+        const url = c.generateAuthUrl({
+            access_type: 'offline',
+            prompt: 'consent',
+            scope: [...consent, ...IDENTITY_SCOPES],
+            state,
+            code_challenge_method: CodeChallengeMethod.S256,
+            code_challenge: codeChallenge,
+        });
+        const redeem = (redirect) => {
+            const query = redirect.searchParams;
+            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);
+        };
+        if (manual) {
+            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());
+            if (!redirect)
+                throw new GapiError(2, 'not a URL; paste the full URL from the address bar');
+            return redeem(redirect);
+        }
+        return new Promise((resolve, reject) => {
+            const server = createServer(async (req, res) => {
+                const redirect = new URL(req.url ?? '/', REDIRECT_URI);
+                if (redirect.pathname !== '/') {
+                    res.statusCode = 404; // e.g. /favicon.ico: keep waiting for the redirect
+                    res.end();
+                    return;
+                }
+                try {
+                    const tokens = await redeem(redirect);
+                    res.end('gapi: authorized. You can close this tab.');
+                    resolve(tokens);
+                }
+                catch (e) {
+                    res.statusCode = 400;
+                    res.end(`gapi: ${messageOf(e)}`);
+                    reject(e);
+                }
+                finally {
+                    server.close();
+                }
+            });
+            server.on('error', (e) => reject(new GapiError(2, `cannot listen on ${LOOPBACK_HOST}:${LOOPBACK_PORT}: ${e.message}`)));
+            server.listen(LOOPBACK_PORT, LOOPBACK_HOST, () => {
+                const { address, port } = server.address();
+                stderr.write(`Listening on ${address}:${port}\nOpen this URL and grant access:\n${url}\n`);
+            });
+        });
+    }
+    async function status(consent) {
+        const cfg = await readConfig();
+        const creds = await readCredentials();
+        const granted = new Set((creds.scope ?? '').split(' ').filter(Boolean));
+        return {
+            account: creds.id_token ? accountFromIdToken(creds.id_token) : null,
+            hasRefreshToken: Boolean(creds.refresh_token),
+            hasApiKey: setting({}, cfg, API_KEY_SETTING) !== undefined,
+            expiryDate: creds.expiry_date ? new Date(creds.expiry_date).toISOString() : null,
+            scopes: [...granted].map(shortScope),
+            missing: consent.filter((s) => !granted.has(s)).map(shortScope),
+        };
+    }
+    // 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.
+    // 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.
+    async function logout() {
+        const token = (await readCredentials().catch(() => undefined))?.refresh_token;
+        if (token) {
+            await oauth()
+                .revokeToken(token)
+                .catch((e) => {
+                if (!isRecord(e) || e.status !== 400)
+                    throw new GapiError(1, `token revoke failed, credentials kept: ${messageOf(e)}`);
+                warn('refresh token already invalid or revoked');
+            });
+        }
+        await rm(credentialsFile, { force: true });
+    }
+    // `headers`: every entry's header specs, tagged with the entry's api.
+    async function setup(headers, prompt = ask) {
+        const cfg = await readConfig();
+        const fields = [
+            ...CLIENT_FIELDS,
+            ...headers.map((h) => ({
+                key: h.configKey,
+                label: `${h.api} ${h.configKey} (optional)`,
+                required: false,
+                secret: false,
+            })),
+            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 writeSecure(configFile, cfg);
+        return configFile;
+    }
+    return { settings, authorize, login, status, logout, setup };
+}
+// Decode a JWT payload without verifying (display only; it is our own token).
+function accountFromIdToken(idToken) {
+    try {
+        const payload = JSON.parse(Buffer.from(idToken.split('.')[1], 'base64url').toString());
+        if (!isRecord(payload))
+            return null;
+        const account = payload.email || payload.sub;
+        return typeof account === 'string' ? account : null;
+    }
+    catch {
+        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);
+    const rl = createInterface({
+        input,
+        output: secret ? new Writable({ write: (_c, _e, cb) => cb() }) : output,
+        terminal: secret ? true : terminal,
+    });
+    try {
+        return await rl.question(secret ? '' : q);
+    }
+    finally {
+        rl.close();
+        if (secret)
+            output.write('\n'); // the swallowed Enter never printed one
+    }
+}

package/dist/src/errors.js

@@ -0,0 +1,16 @@
+export class GapiError extends Error {
+    exit;
+    body;
+    constructor(exit, message, body) {
+        super(message);
+        this.name = 'GapiError';
+        this.exit = exit;
+        this.body = body;
+    }
+}
+// A caught value's message: an Error's own text (no `Error: ` prefix), anything else as a string.
+export const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+// A Node system error's `code` (`ENOENT`, `EACCES`, …); undefined for anything else.
+export const codeOf = (e) => e instanceof Error && 'code' in e ? e.code : undefined;
+// Why a file operation failed: the system error code when there is one, else the message.
+export const reasonOf = (e) => String(codeOf(e) ?? messageOf(e));

package/dist/src/json.js

@@ -0,0 +1,11 @@
+// Guards for parsed JSON: narrow `unknown` with `isRecord` + `typeof`, never a cast.
+export const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// JSON text parsed; text that is not JSON (an HTML error page, a proxy reply) stays as is.
+export function parseOrText(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/src/plan.js

@@ -0,0 +1,315 @@
+// Planner: command words + parsed --params/--body → one validated CallPlan (epic #30 D4, D5).
+// Pure: no I/O; every rejection is a GapiError thrown before any network call.
+import { extname } from 'node:path';
+import { GapiError, messageOf } from './errors.js';
+import { isRecord } from './json.js';
+// Document-level parameters gapi sets itself (D5).
+const OWNED = new Set([
+    'alt',
+    'key',
+    'access_token',
+    'oauth_token',
+    'callback',
+    'prettyPrint',
+    'uploadType',
+    'upload_protocol',
+    '$.xgafv',
+]);
+// The document-level parameters a caller may pass (D5).
+const SHARED = ['fields', 'quotaUser'];
+const PROTOCOLS = ['media', 'multipart', 'resumable'];
+// --upload-content-type default by file extension (D7); anything else is octet-stream.
+const CONTENT_TYPES = new Map([
+    ['.png', 'image/png'],
+    ['.jpg', 'image/jpeg'],
+    ['.jpeg', 'image/jpeg'],
+    ['.gif', 'image/gif'],
+    ['.webp', 'image/webp'],
+    ['.mp4', 'video/mp4'],
+    ['.mov', 'video/quicktime'],
+    ['.webm', 'video/webm'],
+    ['.csv', 'text/csv'],
+    ['.txt', 'text/plain'],
+    ['.json', 'application/json'],
+    ['.pdf', 'application/pdf'],
+    ['.zip', 'application/zip'],
+]);
+const invalid = (message) => new GapiError(3, message);
+// Walk the resources tree by exact key; a method key must be the last word.
+export function resolve(model, words) {
+    let node = model;
+    for (const [i, word] of words.entries()) {
+        const method = node.methods.get(word);
+        if (method) {
+            if (i < words.length - 1)
+                throw invalid(`unexpected argument '${words[i + 1]}'`);
+            return { method };
+        }
+        const next = node.resources.get(word);
+        if (!next) {
+            const kind = node.methods.size === 0
+                ? 'resource'
+                : node.resources.size === 0
+                    ? 'method'
+                    : 'resource or method';
+            const valid = [...node.resources.keys(), ...node.methods.keys()].join(', ');
+            throw invalid(`unknown ${kind} '${word}' (valid: ${valid})`);
+        }
+        node = next;
+    }
+    return { node };
+}
+export function plan(model, target, input, settings) {
+    const method = typeof target === 'string' ? model.byId.get(target) : resolve(model, target).method;
+    if (!method)
+        throw invalid(`not a method: ${typeof target === 'string' ? target : target.join(' ')}`);
+    const command = `${model.api} ${method.words.join(' ')}`;
+    if (method.retired)
+        throw invalid(`retired: ${method.retired.reason} (${method.retired.source})`);
+    if (method.unavailable && !input.dryRun) {
+        throw new GapiError(2, `${command}: unavailable: scope not grantable`);
+    }
+    const warnings = method.deprecated
+        ? [
+            `${command} is deprecated${method.deprecated.source ? ` (${method.deprecated.source})` : ''}`,
+        ]
+        : [];
+    const values = paramValues(model, method, input.params ?? {});
+    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 url = buildUrl(model, method, values, mode);
+    const headers = contentHeaders(mode, body !== undefined);
+    if (model.auth === 'oauth' && settings.project)
+        headers['x-goog-user-project'] = settings.project;
+    Object.assign(headers, settings.headers);
+    return {
+        methodId: method.id,
+        httpMethod: method.httpMethod,
+        url,
+        headers,
+        body,
+        auth: { kind: model.auth, scopes: method.scopes },
+        warnings,
+        ...mode,
+    };
+}
+// The outer CallPlan of a batch call: one POST to the documented `batch` 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`,
+        headers: {},
+        auth: first.auth,
+        warnings: first.warnings,
+        send: 'batch',
+        parts,
+    };
+}
+// JSON for a body, the file type for a media upload; Transport adds the multipart boundary.
+function contentHeaders(mode, hasBody) {
+    const json = hasBody ? { 'Content-Type': 'application/json' } : {};
+    if (mode.send !== 'upload')
+        return json;
+    const { protocol, contentType } = mode.upload;
+    if (protocol === 'media')
+        return { 'Content-Type': contentType };
+    if (protocol === 'multipart')
+        return {};
+    return { ...json, 'X-Upload-Content-Type': contentType };
+}
+// D6 paging, D7 media: at most one of --page-all, --upload, --output, each only where the
+// method supports it.
+function sendMode(method, command, input) {
+    const chosen = [
+        input.pageAll && '--page-all',
+        input.upload !== undefined && '--upload',
+        input.output !== undefined && '--output',
+    ].filter((flag) => typeof flag === 'string');
+    if (chosen.length > 1)
+        throw invalid(`${chosen[0]} and ${chosen[1]} cannot be combined`);
+    if (input.pageLimit !== undefined && !input.pageAll) {
+        throw invalid('--page-limit needs --page-all');
+    }
+    if (input.upload !== undefined) {
+        const hasBody = input.body !== undefined;
+        return { send: 'upload', upload: upload(method, command, input.upload, input, hasBody) };
+    }
+    for (const [flag, value] of [
+        ['--upload-content-type', input.uploadContentType],
+        ['--upload-protocol', input.uploadProtocol],
+    ]) {
+        if (value !== undefined)
+            throw invalid(`${flag} needs --upload`);
+    }
+    if (input.output !== undefined) {
+        if (!method.download)
+            throw invalid(`--output: ${command} has no media download`);
+        return { send: 'download', output: input.output };
+    }
+    if (!input.pageAll)
+        return { send: 'once' };
+    if (!method.paging) {
+        throw invalid(`--page-all: ${command} has no pageToken parameter or request field`);
+    }
+    const limit = input.pageLimit ?? '10';
+    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).
+    const body = input.body ?? {};
+    if (!isRecord(body))
+        throw invalid('--page-all: --body must be a JSON object');
+    return { send: 'pages', pageLimit, paging: 'body', body };
+}
+// D7: protocol defaults to multipart with --body, else media; the type must fit `accept`.
+function upload(method, command, path, input, hasBody) {
+    if (!method.upload)
+        throw invalid(`--upload: ${command} takes no media upload`);
+    const protocol = input.uploadProtocol ?? (hasBody ? 'multipart' : 'media');
+    if (!isProtocol(protocol)) {
+        throw invalid(`--upload-protocol must be one of: ${PROTOCOLS.join(', ')}`);
+    }
+    if (protocol === 'resumable' && !method.upload.resumable) {
+        throw invalid(`--upload-protocol resumable: ${command} has no resumable upload`);
+    }
+    // An explicit protocol that would drop or lack the --body metadata.
+    if (protocol === 'multipart' && !hasBody) {
+        throw invalid('--upload-protocol multipart needs --body');
+    }
+    if (protocol === 'media' && hasBody)
+        throw invalid('--upload-protocol media takes no --body');
+    const contentType = input.uploadContentType ??
+        CONTENT_TYPES.get(extname(path).toLowerCase()) ??
+        'application/octet-stream';
+    const { accept } = method.upload;
+    if (accept.length > 0 && !accept.some((pattern) => accepts(pattern, contentType))) {
+        throw invalid(`--upload-content-type ${contentType}: ${command} accepts ${accept.join(', ')}`);
+    }
+    return { path, contentType, protocol };
+}
+const isProtocol = (p) => PROTOCOLS.includes(p);
+// A discovery `accept` pattern: `*/*`, `<type>/*` or an exact type; MIME types ignore case.
+function accepts(pattern, contentType) {
+    const p = pattern.toLowerCase();
+    const t = contentType.split(';')[0].trim().toLowerCase();
+    return p === '*/*' || p === t || (p.endsWith('/*') && t.startsWith(p.slice(0, -1)));
+}
+// argv JSON for --params / --body; invalid JSON and unsafe integers exit 3.
+export function parseJson(flag, text) {
+    if (text === undefined)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (e) {
+        throw invalid(`${flag} is not valid JSON: ${messageOf(e)}`);
+    }
+    const path = unsafeInteger(value, '');
+    if (path !== undefined) {
+        throw invalid(`${flag}${path && ` ${path}`}: integer exceeds 2^53; pass it as a string`);
+    }
+    return value;
+}
+// JSON.parse rounds integers past 2^53; Discovery sends int64 as a string (discovery/v1/type-format).
+function unsafeInteger(value, path) {
+    if (typeof value === 'number') {
+        return Math.abs(value) > Number.MAX_SAFE_INTEGER ? path : undefined;
+    }
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const array = Array.isArray(value);
+    for (const [key, item] of Object.entries(value)) {
+        const found = unsafeInteger(item, array ? `${path}[${key}]` : path ? `${path}.${key}` : key);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+// --params → one list of string values per known parameter (D5 value rules).
+function paramValues(model, method, params) {
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+        throw invalid('--params must be a JSON object');
+    }
+    const shared = SHARED.filter((k) => model.parameters.has(k));
+    const out = new Map();
+    for (const [name, raw] of Object.entries(params)) {
+        const spec = method.parameters.get(name) ??
+            (shared.includes(name) ? model.parameters.get(name) : undefined);
+        if (!spec) {
+            if (OWNED.has(name))
+                throw invalid(`${name} is set by gapi`);
+            const valid = [...method.parameters.keys(), ...shared].join(', ');
+            throw invalid(`unknown param ${name} (valid: ${valid})`);
+        }
+        if (Array.isArray(raw) && !spec.repeated)
+            throw invalid(`${name} takes one value, not an array`);
+        const values = (Array.isArray(raw) ? raw : [raw]).map((v) => {
+            if (typeof v === 'string')
+                return v;
+            if (typeof v === 'number' || typeof v === 'boolean')
+                return String(v);
+            throw invalid(`${name} must be a string, number or boolean`);
+        });
+        for (const v of values) {
+            if (spec.enum && !spec.enum.includes(v)) {
+                throw invalid(`${name} must be one of: ${spec.enum.join(', ')}`);
+            }
+        }
+        out.set(name, { spec, values });
+    }
+    for (const [name, spec] of method.parameters) {
+        if (spec.required && !out.has(name))
+            throw invalid(`missing required param ${name}`);
+    }
+    return out;
+}
+// rootUrl + servicePath + the discovery `path` with {x}/{+x} expanded, then the query string.
+// D7: an upload goes to rootUrl + `upload/` + …, a download adds alt=media and, on a
+// `useMediaDownloadService` method, goes to rootUrl + `download/` + … (Discovery "Using").
+function buildUrl(model, method, params, mode) {
+    const path = method.path.replace(/\{(\+?)([^}]+)\}/g, (_, reserved, name, offset) => {
+        const param = params.get(name);
+        if (!param)
+            throw invalid(`missing required param ${name}`);
+        const value = param.values[0];
+        if (param.spec.pattern && !new RegExp(param.spec.pattern).test(value)) {
+            throw invalid(`${name} must match ${param.spec.pattern}`);
+        }
+        if (reserved)
+            return value.split('/').map(encodeURIComponent).join('/');
+        // #28: `properties/{property}` + `properties/123` would encode to properties%2F123.
+        const segment = /[^/]+\/$/.exec(method.path.slice(0, offset))?.[0];
+        if (segment && value.startsWith(segment)) {
+            throw invalid(`pass the bare id: ${value.slice(segment.length)} (the path already has ${segment})`);
+        }
+        return encodeSegment(value);
+    });
+    const query = new URLSearchParams();
+    for (const [name, { spec, values }] of params) {
+        if (spec.location !== 'path')
+            for (const v of values)
+                query.append(name, v);
+    }
+    if (mode.send === 'upload')
+        query.append('uploadType', mode.upload.protocol);
+    if (mode.send === 'download')
+        query.append('alt', 'media');
+    const qs = query.toString();
+    const root = mode.send === 'upload'
+        ? `${model.rootUrl}upload/`
+        : mode.send === 'download' && method.download?.service
+            ? `${model.rootUrl}download/`
+            : model.rootUrl;
+    return `${root}${model.servicePath}${path}${qs ? `?${qs}` : ''}`;
+}
+// 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()}`);