google-apis-cli 0.1.0 → 0.3.0

package/dist/src/run.js

@@ -0,0 +1,374 @@
+// Process io is injected so tests drive the whole CLI in-process.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { openCatalog } from './catalog.js';
+import { configDir, openCredentials } from './credentials.js';
+import { GapiError, messageOf, reasonOf } from './errors.js';
+import { isRecord } from './json.js';
+import { parseJson, plan, resolve } from './plan.js';
+import { AUTH_USAGE, DISCOVERY_USAGE, levelText, methodHelp, rootHelp, SCHEMA_USAGE, SEARCH_USAGE, schemaFind, schemaView, searchText, } from './render.js';
+import { MAX_AGE_MS, openResponses } from './responses.js';
+import { matchQuery, search } from './search.js';
+import { send } from './transport.js';
+const GLOBAL_OPTIONS = {
+    params: { type: 'string' },
+    body: { type: 'string' },
+    'dry-run': { type: 'boolean' },
+    'page-all': { type: 'boolean' },
+    'page-limit': { type: 'string' },
+    upload: { type: 'string' },
+    'upload-content-type': { type: 'string' },
+    'upload-protocol': { type: 'string' },
+    output: { type: 'string' },
+    project: { type: 'string' },
+    'api-key': { type: 'string' },
+    cache: { type: 'string' },
+    help: { type: 'boolean' },
+};
+// D10: a helper takes the global flags that do not shape the request, plus its own options.
+const HELPER_OPTIONS = {
+    'dry-run': GLOBAL_OPTIONS['dry-run'],
+    project: GLOBAL_OPTIONS.project,
+    'api-key': GLOBAL_OPTIONS['api-key'],
+    cache: GLOBAL_OPTIONS.cache,
+    help: GLOBAL_OPTIONS.help,
+};
+const AGE_UNIT_MS = { s: 1e3, m: 60e3, h: 3600e3, d: 86400e3 };
+// `--cache <n>s|m|h|d`, from 1 s to the 7-day store limit (ADR 0001).
+function parseAge(age) {
+    const m = /^(\d+)([smhd])$/.exec(age);
+    const ms = m ? Number(m[1]) * AGE_UNIT_MS[m[2]] : 0;
+    if (ms < 1000 || ms > MAX_AGE_MS) {
+        throw new GapiError(3, `--cache: ${age} is not an age from 1s to 7d`);
+    }
+    return ms;
+}
+const isHelperName = (word) => word.startsWith('+');
+// D4: an entry header flag is accepted only on the APIs whose entry declares it.
+const headerOptions = (entry) => Object.fromEntries((entry?.headers ?? []).map((h) => [h.flag, { type: 'string' }]));
+export async function run(argv, io) {
+    try {
+        await dispatch(argv, io);
+        return 0;
+    }
+    catch (e) {
+        const err = e instanceof GapiError ? e : new GapiError(5, messageOf(e));
+        const { body } = err;
+        const shown = isRecord(body) ? (body.error ?? body) : body;
+        const detail = body ? `\n${JSON.stringify(shown, null, 2)}` : '';
+        io.stderr.write(`gapi: ${err.message}${detail}\n`);
+        return err.exit;
+    }
+}
+// Strict argv parsing; an unknown flag, a missing flag value or a repeated flag (parseArgs
+// would keep the last one) is a validation error.
+function parse(args, options) {
+    try {
+        const parsed = parseArgs({ args, options, allowPositionals: true, strict: true, tokens: true });
+        const names = parsed.tokens.flatMap((t) => (t.kind === 'option' ? [t.name] : []));
+        const twice = names.find((n, i) => names.indexOf(n) !== i);
+        if (twice !== undefined)
+            throw new GapiError(3, `--${twice} given twice`);
+        return parsed;
+    }
+    catch (e) {
+        throw e instanceof GapiError ? e : new GapiError(3, messageOf(e));
+    }
+}
+async function runAuth(sub, values, { io, creds, catalog, responses, }) {
+    // --help never starts a side effect: no server, no fetch, no file write.
+    if (values.help) {
+        io.stdout.write(`${AUTH_USAGE}\n`);
+        return;
+    }
+    if (sub === 'login') {
+        const consent = await consentScopes(catalog);
+        await responses.clear(); // a new account starts with no stored responses
+        const tokens = await creds.login({ consent, manual: values.manual === true });
+        io.stderr.write(`gapi: authorized (${tokens.refresh_token ? 'refresh token stored' : 'no refresh token'})\n`);
+        return;
+    }
+    if (sub === 'setup') {
+        // Header prompts come from the entries' `headers` overlays, in api order.
+        const headers = Object.values(catalog.entries)
+            .toSorted((a, b) => a.api.localeCompare(b.api))
+            .flatMap((e) => (e.headers ?? []).map((h) => ({ ...h, api: e.api })));
+        io.stderr.write(`gapi: saved to ${await creds.setup(headers)}\n`);
+        return;
+    }
+    if (sub === 'status') {
+        const consent = await consentScopes(catalog);
+        io.stdout.write(`${JSON.stringify(await creds.status(consent), null, 2)}\n`);
+        return;
+    }
+    if (sub === 'logout') {
+        try {
+            await creds.logout();
+        }
+        finally {
+            await responses.clear(); // also when the revoke fails: no account data stays on disk
+        }
+        io.stderr.write('gapi: credentials removed\n');
+        return;
+    }
+    throw new GapiError(3, sub === undefined ? `usage: ${AUTH_USAGE}` : `unknown auth command: ${sub}`);
+}
+// D8 consent set: every entry's per-method scope plus its entry scopes (identity is added by login).
+async function consentScopes(catalog) {
+    const models = await Promise.all(Object.keys(catalog.entries).map((api) => catalog.load(api)));
+    const scopes = new Set();
+    for (const model of models) {
+        for (const s of model.scopes)
+            scopes.add(s);
+        for (const m of model.byId.values())
+            if (m.scope)
+                scopes.add(m.scope);
+    }
+    return [...scopes];
+}
+// D9 order: a method path, else a schema name. Only a document-level method can share a
+// schema's name, since method paths of nested resources contain a dot.
+function schemaTarget(model, path) {
+    if (!model.methods.has(path) && model.schemas.has(path))
+        return { schema: path };
+    try {
+        const found = resolve(model, path.split('.'));
+        if (!found.method)
+            throw new GapiError(3, `${path} is a resource, not a method or schema`);
+        return { method: found.method };
+    }
+    catch (e) {
+        // resolve knows only the tree; a one-word path can also name a schema.
+        if (e instanceof GapiError && /^unknown /.test(e.message) && !path.includes('.')) {
+            throw new GapiError(3, `${e.message}, or a schema name`);
+        }
+        throw e;
+    }
+}
+async function dispatch(argv, io) {
+    const dir = configDir(io.env);
+    const warn = (message) => io.stderr.write(`gapi: warning: ${message}\n`);
+    const catalog = await openCatalog({ dir, fetch: io.fetch, warn, apisDir: io.apisDir });
+    const creds = openCredentials({
+        dir,
+        env: io.env,
+        warn,
+        stdin: io.stdin,
+        stderr: io.stderr,
+    });
+    const responses = openResponses(join(dir, 'responses'));
+    await responses.sweep();
+    // ADR 0001 eligibility, before any network call: the entry allows caching, the call is
+    // one request or pages, the method is a GET or a `reads` POST.
+    const cacheFor = async (call, model, values) => {
+        if (values.cache === undefined)
+            return undefined;
+        const maxAgeMs = parseAge(values.cache);
+        const { nocache } = catalog.entries[model.api];
+        if (nocache) {
+            throw new GapiError(3, `--cache: ${model.api} responses must not be cached: ${nocache.reason} (${nocache.source})`);
+        }
+        const method = model.byId.get(call.methodId);
+        const once = call.send === 'once' || call.send === 'pages';
+        if (!once || (method?.httpMethod !== 'GET' && !method?.read)) {
+            const command = method ? `${model.api} ${method.words.join(' ')}` : call.methodId;
+            throw new GapiError(3, `--cache: ${command} is not a cacheable read`);
+        }
+        return { key: responses.key(call, await creds.identity(call.auth)), maxAgeMs };
+    };
+    if (argv.length === 0 || (argv[0] === '--help' && argv.length === 1)) {
+        io.stdout.write(rootHelp(Object.keys(catalog.entries)));
+        return;
+    }
+    const [api, ...rest] = argv;
+    if (api === 'auth') {
+        const { values, positionals } = parse(rest, {
+            manual: { type: 'boolean' },
+            help: { type: 'boolean' },
+        });
+        return runAuth(positionals[0], values, { io, creds, catalog, responses });
+    }
+    if (api === 'search') {
+        // No option parse: a word like `-list` is query text (story 11).
+        if (rest.includes('--help')) {
+            io.stdout.write(`${SEARCH_USAGE}\n`);
+            return;
+        }
+        const query = rest.join(' ');
+        matchQuery(query); // a query with no token exits 3 before any document loads
+        const models = await Promise.all(Object.keys(catalog.entries).map((a) => catalog.load(a)));
+        const hits = search(models, query);
+        if (hits.length === 0)
+            io.stderr.write('gapi: no match\n');
+        io.stdout.write(searchText(hits));
+        return;
+    }
+    if (api === 'schema') {
+        const { values, positionals } = parse(rest, {
+            'resolve-refs': { type: 'boolean' },
+            find: { type: 'string' },
+            help: { type: 'boolean' },
+        });
+        if (values.help) {
+            io.stdout.write(`${SCHEMA_USAGE}\n`);
+            return;
+        }
+        if (positionals.length !== 2)
+            throw new GapiError(3, `usage: ${SCHEMA_USAGE}`);
+        const [name, path] = positionals;
+        if (values.find === '')
+            throw new GapiError(3, '--find: needs a word');
+        const model = await catalog.load(name);
+        const target = schemaTarget(model, path);
+        if (values.find !== undefined) {
+            const found = schemaFind(model, target, values.find);
+            if (found === '')
+                io.stderr.write('gapi: no match\n');
+            io.stdout.write(found);
+            return;
+        }
+        const resolveRefs = values['resolve-refs'] === true;
+        io.stdout.write(schemaView(model, target, { resolveRefs }));
+        return;
+    }
+    if (api === 'discovery') {
+        const { values, positionals } = parse(rest, { help: { type: 'boolean' } });
+        if (values.help) {
+            io.stdout.write(`${DISCOVERY_USAGE}\n`);
+            return;
+        }
+        const [sub, ...apis] = positionals;
+        if (sub === 'path') {
+            if (apis.length > 0)
+                throw new GapiError(3, `unexpected argument '${apis[0]}'`);
+            io.stdout.write(`${catalog.cacheDir}\n`);
+            return;
+        }
+        if (sub !== 'refresh')
+            throw new GapiError(3, `usage: ${DISCOVERY_USAGE}`);
+        // Validated and deduplicated before any fetch: parallel loads of one api share a temp file.
+        const names = apis.length > 0 ? [...new Set(apis)] : Object.keys(catalog.entries);
+        for (const a of names) {
+            if (!Object.hasOwn(catalog.entries, a))
+                throw new GapiError(3, `unknown api: ${a}`);
+        }
+        await Promise.all(names.map((a) => catalog.load(a, { refresh: true })));
+        for (const a of names)
+            io.stdout.write(`refreshed ${a}\n`);
+        return;
+    }
+    const [word, ...helperArgs] = rest;
+    if (word !== undefined && isHelperName(word)) {
+        if (!Object.hasOwn(catalog.entries, api))
+            throw new GapiError(3, `unknown api: ${api}`);
+        const helpers = catalog.entries[api].helpers ?? {};
+        const helper = Object.hasOwn(helpers, word) ? helpers[word] : undefined;
+        if (!helper) {
+            const valid = Object.keys(helpers).join(', ') || 'none';
+            throw new GapiError(3, `unknown helper '${word}' (valid: ${valid})`);
+        }
+        const { values, positionals } = parse(helperArgs, {
+            ...HELPER_OPTIONS,
+            ...headerOptions(catalog.entries[api]),
+            ...helper.options,
+        });
+        if (values.help) {
+            io.stdout.write(`gapi ${api} ${word} ${helper.summary}\n`);
+            return;
+        }
+        const model = await catalog.load(api);
+        const call = await helper.plan({
+            model,
+            args: positionals,
+            flags: values,
+            settings: await creds.settings(values, model.headers),
+            read: (path) => readFile(path, 'utf8').catch((e) => {
+                throw new GapiError(3, `cannot read ${path}: ${reasonOf(e)}`);
+            }),
+        });
+        const cache = await cacheFor(call, model, values);
+        return perform(call, values['dry-run'] === true, io, creds.authorize, { responses, cache });
+    }
+    const entry = Object.hasOwn(catalog.entries, api) ? catalog.entries[api] : undefined;
+    const { values, positionals } = parse(rest, { ...GLOBAL_OPTIONS, ...headerOptions(entry) });
+    const model = await catalog.load(api);
+    const target = resolve(model, positionals);
+    if (!target.method) {
+        // A listing sends nothing: a request flag here means the method word is missing.
+        const flag = Object.keys(values).find((k) => k !== 'help');
+        if (flag)
+            throw new GapiError(3, `--${flag}: ${[api, ...positionals].join(' ')} is not a method`);
+        const helpers = positionals.length === 0 ? catalog.entries[api].helpers : undefined;
+        io.stdout.write(levelText(model, positionals, target.node, helpers));
+        return;
+    }
+    if (values.help) {
+        io.stdout.write(methodHelp(model, target.method));
+        return;
+    }
+    const dryRun = values['dry-run'] === true;
+    const call = plan(model, target.method.id, {
+        params: parseJson('--params', values.params),
+        body: parseJson('--body', values.body),
+        dryRun,
+        pageAll: values['page-all'],
+        pageLimit: values['page-limit'],
+        upload: values.upload,
+        uploadContentType: values['upload-content-type'],
+        uploadProtocol: values['upload-protocol'],
+        output: values.output,
+    }, await creds.settings(values, model.headers));
+    const cache = await cacheFor(call, model, values);
+    return perform(call, dryRun, io, creds.authorize, { responses, cache });
+}
+// Prints the plan's warnings, then the redacted request (--dry-run), the stored response
+// (a --cache hit) or the live response, which a --cache miss stores after a full success.
+async function perform(call, dryRun, io, authorize, { responses, cache }) {
+    for (const w of call.warnings)
+        io.stderr.write(`gapi: warning: ${w}\n`);
+    const mtime = cache && (await responses.mtime(cache.key));
+    const fresh = cache && mtime !== undefined && Date.now() - mtime < cache.maxAgeMs;
+    const stored = fresh ? await responses.get(cache.key) : undefined;
+    if (dryRun) {
+        const headers = { ...call.headers, ...(await authorize(call.auth, { redact: true })) };
+        const request = {
+            method: call.httpMethod,
+            url: call.url,
+            headers,
+            body: call.body,
+            upload: call.send === 'upload' ? call.upload : undefined,
+            output: call.send === 'download' ? call.output : undefined,
+            parts: call.send === 'batch'
+                ? call.parts.map((p) => ({
+                    method: p.httpMethod,
+                    url: p.url,
+                    headers: p.headers,
+                    body: p.body,
+                }))
+                : undefined,
+            cache: cache && (stored === undefined ? 'miss' : 'hit'),
+        };
+        io.stdout.write(`${JSON.stringify(request, null, 2)}\n`);
+        return;
+    }
+    if (stored !== undefined && mtime !== undefined) {
+        io.stdout.write(stored);
+        io.stderr.write(`gapi: cached response from ${new Date(mtime).toISOString()}\n`);
+        return;
+    }
+    const chunks = [];
+    const out = {
+        write: (chunk) => {
+            chunks.push(chunk);
+            return io.stdout.write(chunk);
+        },
+    };
+    await send(call, { fetch: io.fetch, authorize, out, sleep: io.sleep });
+    if (!cache)
+        return;
+    // Best effort: the response is already printed, so a failed write only warns.
+    await responses.put(cache.key, chunks.join('')).catch((e) => {
+        io.stderr.write(`gapi: warning: cache write failed: ${reasonOf(e)}\n`);
+    });
+}

package/dist/src/search.js

@@ -0,0 +1,53 @@
+// 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';
+// `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) {
+    const tokens = split(query)
+        .toLowerCase()
+        .match(/[\p{L}\p{N}]+/gu);
+    if (!tokens)
+        throw new GapiError(3, `usage: ${SEARCH_USAGE}`);
+    return tokens.map((t) => `"${t}"`).join(' OR ');
+}
+export function search(models, query) {
+    const match = matchQuery(query);
+    const db = new DatabaseSync(':memory:');
+    try {
+        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');
+        for (const model of models) {
+            for (const m of model.byId.values()) {
+                const words = split([model.api, ...m.words].join(' '));
+                const extra = [
+                    split([model.title, m.request, m.response].filter(Boolean).join(' ')),
+                    m.upload && 'upload',
+                    m.download && 'download',
+                ].filter(Boolean);
+                insert.run(model.api, m.id, words, extra.join(' '), m.description ?? '');
+            }
+        }
+        db.exec('commit');
+        const byApi = new Map(models.map((model) => [model.api, model]));
+        return db
+            .prepare('select api, id from m where m match ? order by bm25(m, 0, 0, 6, 2, 1) limit 20')
+            .all(match)
+            .flatMap(({ api, id }) => {
+            const model = byApi.get(String(api));
+            const method = model?.byId.get(String(id));
+            return model && method ? [{ model, method }] : [];
+        });
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/src/transport/batch.js

@@ -0,0 +1,75 @@
+// Batch (epic #30 D7): parts go out as one multipart/mixed request per 100, sequentially.
+// Format: https://developers.google.com/search/apis/indexing-api/v3/using-api#batch
+import { randomUUID } from 'node:crypto';
+import { GapiError } from '../errors.js';
+import { parseOrText } from '../json.js';
+// Google's per-call part limit for the Indexing batch endpoint.
+const MAX_PARTS = 100;
+// A failed call stops the run but keeps the results of the calls before it: Google has
+// already acted on those parts, so the caller must still see them.
+export async function batch(plan, call) {
+    const results = [];
+    for (let start = 0; start < plan.parts.length; start += MAX_PARTS) {
+        try {
+            results.push(...(await chunk(plan, plan.parts.slice(start, start + MAX_PARTS), call)));
+        }
+        catch (error) {
+            return { results, error };
+        }
+    }
+    return { results };
+}
+async function chunk(plan, parts, call) {
+    const boundary = randomUUID();
+    const body = `${parts.map((p, i) => request(boundary, i + 1, p)).join('')}--${boundary}--`;
+    const headers = { ...plan.headers, 'Content-Type': `multipart/mixed; boundary=${boundary}` };
+    const res = await call(plan.url, { method: 'POST', headers, body });
+    // Google picks its own response boundary.
+    const responseBoundary = /boundary="?([^";]+)"?/i.exec(res.headers.get('Content-Type') ?? '')?.[1];
+    // A response gapi cannot map to its parts is Google's surprise: exit 1 with the body.
+    const text = await res.text();
+    const surprise = (message) => new GapiError(1, message, parseOrText(text));
+    if (!responseBoundary)
+        throw surprise('batch: the response has no multipart boundary');
+    const byId = responses(text, responseBoundary);
+    if (!byId)
+        throw surprise('batch: malformed response part');
+    return parts.map((_, i) => {
+        const result = byId.get(String(i + 1));
+        if (!result)
+            throw surprise(`batch: no response for part ${i + 1}`);
+        return result;
+    });
+}
+// One `application/http` part: the inner request line (path only), its headers and JSON body.
+function request(boundary, id, part) {
+    const { pathname, search } = new URL(part.url);
+    const headers = Object.entries(part.headers).map(([k, v]) => `${k}: ${v}\r\n`);
+    return (`--${boundary}\r\nContent-Type: application/http\r\nContent-Transfer-Encoding: binary\r\n` +
+        `Content-ID: <${id}>\r\n\r\n${part.httpMethod} ${pathname}${search}\r\n${headers.join('')}\r\n` +
+        `${part.body === undefined ? '' : JSON.stringify(part.body)}\r\n`);
+}
+// Response parts keyed by request Content-ID: each answers `<response-n>` with an inner
+// `HTTP/1.1 <status> …`, headers, blank line, body. Google may answer in any order.
+// A part with no Content-ID or status line makes the whole response unreadable: undefined.
+function responses(text, boundary) {
+    const byId = new Map();
+    for (const raw of text.split(`--${boundary}`).slice(1)) {
+        if (raw.startsWith('--'))
+            break;
+        const [head, response] = splitAtBlankLine(raw.replace(/^\r?\n/, ''));
+        const id = /^content-id:\s*<response-([^>]+)>\s*$/im.exec(head)?.[1];
+        const [statusHead, content] = splitAtBlankLine(response);
+        const status = Number(/^HTTP\/\S+ (\d{3})/.exec(statusHead)?.[1]);
+        if (id === undefined || !status)
+            return undefined;
+        byId.set(id, { status, text: content.trim() });
+    }
+    return byId;
+}
+function splitAtBlankLine(text) {
+    const blank = /\r?\n\r?\n/.exec(text);
+    return blank
+        ? [text.slice(0, blank.index), text.slice(blank.index + blank[0].length)]
+        : [text, ''];
+}

package/dist/src/transport/download.js

@@ -0,0 +1,21 @@
+// Media download (epic #30 D7): the response body streams to the --output file.
+import { createWriteStream } from 'node:fs';
+import { access, constants, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { GapiError, reasonOf } from '../errors.js';
+// The file is created only after a 2xx, so a Google error leaves no empty file behind.
+export async function download(plan, call) {
+    // A bad local path is the caller's input (exit 3), found before Google sends any byte.
+    await access(dirname(plan.output), constants.W_OK).catch((e) => {
+        throw new GapiError(3, `--output: cannot write to ${dirname(plan.output)}: ${reasonOf(e)}`);
+    });
+    const res = await call(plan.url, { method: plan.httpMethod, headers: plan.headers });
+    const file = createWriteStream(plan.output);
+    await pipeline(res.body ?? Readable.from([]), file).catch(async (e) => {
+        await rm(plan.output, { force: true }); // a cut-off stream leaves no partial file
+        throw e;
+    });
+    return { path: plan.output, bytes: file.bytesWritten };
+}

package/dist/src/transport/retry.js

@@ -0,0 +1,21 @@
+// Retry policy shared by Transport and the resumable upload (Google client idioms, #194).
+import { GapiError } from '../errors.js';
+// The request never got an HTTP answer (DNS, reset, timeout): exit 1, like a Google error.
+export class NetworkError extends GapiError {
+}
+// Google's retry rule: 408, 429, 5xx, and a 403 for a rate limit (google-api-python-client).
+export const RETRIES = 3;
+export const retryable = (status, text = '') => status === 408 ||
+    status === 429 ||
+    status >= 500 ||
+    (status === 403 && /"reason":\s*"(user)?[rR]ateLimitExceeded"/.test(text));
+// Truncated exponential backoff with jitter: min(32 s, 1 s × 2^n + 0–1 s), Google's docs.
+export const backoff = (attempt) => Math.min(32_000, 1000 * 2 ** attempt + Math.random() * 1000);
+// Our choice, no Google client reads it: `Retry-After` (seconds or HTTP date) is a floor.
+export const retryAfter = (res) => {
+    const v = res.headers.get('Retry-After');
+    if (!v)
+        return 0;
+    const ms = /^\d+$/.test(v) ? Number(v) * 1000 : Date.parse(v) - Date.now();
+    return Number.isFinite(ms) ? Math.max(0, ms) : 0;
+};

package/dist/src/transport/upload.js

@@ -0,0 +1,106 @@
+// Media upload (epic #30 D7): the file streams from disk as a Blob backed by it.
+import { randomUUID } from 'node:crypto';
+import { openAsBlob } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { GapiError, reasonOf } from '../errors.js';
+import { parseOrText } from '../json.js';
+import { backoff, NetworkError, RETRIES, retryable } from './retry.js';
+// Google wants chunks in multiples of 256 KiB; 8 MiB keeps the request count low.
+const CHUNK = 8 * 1024 * 1024;
+// Consecutive 308s that move the upload no further before gapi gives up.
+const MAX_STALLS = 3;
+// Returns the final response; Transport prints it like a `once` call.
+export async function upload(plan, call, sleep) {
+    const file = await readable(plan.upload.path);
+    const { protocol, contentType } = plan.upload;
+    if (protocol === 'media') {
+        return call(plan.url, { method: plan.httpMethod, headers: plan.headers, body: file });
+    }
+    if (protocol === 'resumable')
+        return resumable(plan, file, call, sleep);
+    // multipart/related: the JSON metadata part, then the media part.
+    const boundary = randomUUID();
+    const body = new Blob([
+        `--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n`,
+        JSON.stringify(plan.body),
+        `\r\n--${boundary}\r\nContent-Type: ${contentType}\r\n\r\n`,
+        file,
+        `\r\n--${boundary}--`,
+    ]);
+    const headers = { ...plan.headers, 'Content-Type': `multipart/related; boundary=${boundary}` };
+    return call(plan.url, { method: plan.httpMethod, headers, body });
+}
+// Checked before any request: the Blob reads lazily, so a missing, unreadable or non-regular
+// file would otherwise fail mid-upload.
+async function readable(path) {
+    const handle = await open(path, 'r').catch((e) => {
+        throw new GapiError(3, `--upload: cannot read ${path}: ${reasonOf(e)}`);
+    });
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new GapiError(3, `--upload: ${path} is not a file`);
+    }
+    finally {
+        await handle.close();
+    }
+    return openAsBlob(path);
+}
+// Session request on the upload URL, then PUT chunks to the session URI; 308 = send more.
+// A 5xx or a network error on a chunk asks the session what it kept (`bytes */<size>`) and
+// goes on from there (google-api-python-client `next_chunk`, @google-cloud/storage).
+async function resumable(plan, file, call, sleep) {
+    const session = await call(plan.url, {
+        method: plan.httpMethod,
+        headers: { ...plan.headers, 'X-Upload-Content-Length': String(file.size) },
+        body: plan.body === undefined ? undefined : JSON.stringify(plan.body),
+    });
+    const location = session.headers.get('Location');
+    if (!location) {
+        const body = parseOrText(await session.text());
+        throw new GapiError(1, 'resumable upload: the session response has no Location header', body);
+    }
+    // undici holds the connection until a body is read or cancelled; only headers matter here.
+    await session.body?.cancel();
+    // A retryable answer or no answer at all is undefined: the caller asks the session again.
+    const put = (range, body) => call(location, { method: 'PUT', headers: { 'Content-Range': range }, body }, (s) => s === 308 || retryable(s)).then(async (res) => (retryable(res.status) ? void (await res.body?.cancel()) : res), (e) => {
+        if (e instanceof NetworkError)
+            return undefined;
+        throw e;
+    });
+    // Every final failure names the session, so the operator sees where the upload stopped.
+    try {
+        let start = 0;
+        let stalls = 0;
+        let failures = 0;
+        for (;;) {
+            const end = Math.min(start + CHUNK, file.size);
+            const range = file.size === 0 ? 'bytes */0' : `bytes ${start}-${end - 1}/${file.size}`;
+            let res = await put(range, file.slice(start, end));
+            while (!res) {
+                if (++failures > RETRIES)
+                    throw new GapiError(1, `resumable upload: no answer at byte ${start}`);
+                await sleep(backoff(failures - 1));
+                res = await put(`bytes */${file.size}`);
+            }
+            if (res.status !== 308)
+                return res;
+            // `Range: bytes=0-<last>` names the bytes Google kept; no Range means it kept none.
+            const kept = /^bytes=0-(\d+)$/.exec(res.headers.get('Range') ?? '');
+            const next = kept ? Number(kept[1]) + 1 : 0;
+            stalls = next > start ? 0 : stalls + 1;
+            if (next > start)
+                failures = 0;
+            if (stalls === MAX_STALLS || next >= file.size) {
+                const body = parseOrText(await res.text());
+                throw new GapiError(1, `resumable upload: 308 at byte ${next} of ${file.size}, no progress`, body);
+            }
+            await res.body?.cancel();
+            start = next;
+        }
+    }
+    catch (e) {
+        if (!(e instanceof GapiError))
+            throw e;
+        throw new GapiError(e.exit, `${e.message}; session ${location}`, e.body);
+    }
+}