google-apis-cli 0.1.0 → 0.2.0

package/dist/src/render.js

@@ -0,0 +1,183 @@
+export const SCHEMA_USAGE = 'gapi schema <api> <resource>[.<sub-resource>…].<method> | <SchemaName> [--resolve-refs]';
+export const DISCOVERY_USAGE = 'gapi discovery refresh [<api>…] | path';
+export const AUTH_USAGE = 'gapi auth setup | login [--manual] | status | logout';
+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>]] [--dry-run] [--project <id>] [--api-key <key>]
+     [<entry header flags, e.g. ads --login-customer-id <id>>]
+gapi <api> [<resource>…]                  list sub-resources and methods
+gapi <api> <resource>… <method> --help    method help
+gapi <api> +<helper> … [--dry-run] [--project <id>] [--api-key <key>] [<entry header flags>]
+${SCHEMA_USAGE}
+${DISCOVERY_USAGE}
+${AUTH_USAGE}
+`;
+export function rootHelp(apis) {
+    return `${USAGE}\napis:\n${apis
+        .toSorted()
+        .map((api) => `  ${api}\n`)
+        .join('')}`;
+}
+const markList = (m, { reasons = false } = {}) => [
+    m.deprecated && 'deprecated',
+    m.retired && (reasons ? `retired: ${m.retired.reason}` : 'retired'),
+    m.unavailable && 'unavailable: scope not grantable',
+    m.paid && (reasons ? `paid: ${m.paid.reason}` : 'paid'),
+].filter((s) => typeof s === 'string');
+const marks = (m) => markList(m)
+    .map((s) => ` (${s})`)
+    .join('');
+export function levelText(model, words, node, helpers = {}) {
+    const lines = [`gapi ${[model.api, ...words].join(' ')}`];
+    if (Object.keys(helpers).length > 0) {
+        lines.push('', 'helpers:', ...Object.entries(helpers).map(([k, h]) => `  ${k}  ${h.summary}`));
+    }
+    if (node.resources.size > 0) {
+        lines.push('', 'resources:', ...[...node.resources.keys()].map((k) => `  ${k}`));
+    }
+    if (node.methods.size > 0) {
+        lines.push('', 'methods:', ...[...node.methods].map(([k, m]) => `  ${k}${marks(m)}`));
+    }
+    return `${lines.join('\n')}\n`;
+}
+// Many documents state "Required." only in the description, not as `required: true`.
+const requiredFact = (p) => p.required
+    ? 'required'
+    : p.description?.startsWith('Required.')
+        ? 'required (per description)'
+        : undefined;
+export function methodHelp(model, m) {
+    const lines = [`gapi ${model.api} ${m.words.join(' ')}${marks(m)}`];
+    if (m.description)
+        lines.push('', m.description);
+    lines.push('', `${m.httpMethod} ${model.rootUrl}${model.servicePath}${m.path}`, `id: ${m.id}`);
+    lines.push('', m.parameters.size > 0 ? 'params (--params):' : 'params: none');
+    for (const [name, p] of m.parameters) {
+        const facts = [
+            p.location,
+            p.type,
+            requiredFact(p),
+            p.repeated && 'repeated',
+            p.enum && `enum: ${p.enum.join('|')}`,
+            p.pattern && `pattern: ${p.pattern}`,
+        ].filter(Boolean);
+        lines.push(`  ${name}  ${facts.join(', ')}`);
+        // Descriptions carry Markdown (tables, lists): keep their lines, indented.
+        if (p.description)
+            lines.push(p.description.trim().replace(/^/gm, '      '));
+    }
+    lines.push('', `body (--body): ${m.request ?? 'none'}`, `response: ${m.response ?? 'none'}`);
+    if (m.upload) {
+        const protocols = m.upload.resumable ? 'media, multipart, resumable' : 'media, multipart';
+        const max = m.upload.maxSize ? `; max ${m.upload.maxSize}` : '';
+        lines.push(`upload: ${protocols}; accept ${m.upload.accept.join(', ') || 'any'}${max}`);
+    }
+    if (m.download)
+        lines.push('download: yes');
+    lines.push(`scopes: ${m.scopes.join(', ') || 'none'}`);
+    if (m.deprecated)
+        lines.push(`deprecated${m.deprecated.source ? `: ${m.deprecated.source}` : ''}`);
+    if (m.retired)
+        lines.push(`retired: ${m.retired.reason} (${m.retired.source})`);
+    if (m.paid)
+        lines.push(`paid: ${m.paid.reason} (${m.paid.source})`);
+    if (m.unavailable)
+        lines.push('unavailable: scope not grantable');
+    if (model.documentationLink)
+        lines.push(`docs: ${model.documentationLink}`);
+    return `${lines.join('\n')}\n`;
+}
+const GENERATED = 'Generated by `pnpm gen:skill` from the discovery document. Do not edit.';
+const AUTH_LABEL = { oauth: 'OAuth', apiKey: 'API key' };
+const cell = (text) => text.replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim();
+// A table cell holds one sentence; the full text is in `--help`.
+const oneLine = (description = '') => description
+    .trim()
+    .split('\n')[0]
+    .split(/(?<=\.)\s+(?=[A-Z*])/)[0];
+// Code-point order, so the output does not depend on the machine's locale.
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const byKey = (map) => [...map].sort(([a], [b]) => compare(a, b));
+export function indexMarkdown(models) {
+    const rows = models
+        .toSorted((a, b) => compare(a.api, b.api))
+        .map((m) => `| [\`${m.api}\`](${m.api}.md) | ${cell(m.title ?? m.name)} | ${m.version} | ${m.byId.size} | ${AUTH_LABEL[m.auth]} |`);
+    return [
+        '# gapi API reference',
+        '',
+        GENERATED,
+        '',
+        '| api | title | version | methods | auth |',
+        '|---|---|---|---|---|',
+        ...rows,
+        '',
+    ].join('\n');
+}
+export function referenceMarkdown(model) {
+    const lines = [
+        `# gapi ${model.api}: ${model.title ?? model.name} ${model.version}`,
+        '',
+        GENERATED,
+        '',
+        `Auth: ${AUTH_LABEL[model.auth]}.${model.documentationLink ? ` Docs: ${model.documentationLink}` : ''}`,
+    ];
+    // Sorted by key: Google serves the same document with its keys in varying order.
+    const visit = (node, words) => {
+        if (words.length > 0 || node.methods.size > 0) {
+            lines.push('', `## ${['gapi', model.api, ...words].join(' ')}`);
+        }
+        if (node.methods.size > 0) {
+            lines.push('', '| command | HTTP | description | required params | body | marks |', '|---|---|---|---|---|---|', ...byKey(node.methods).map(([, m]) => referenceRow(model, m)));
+        }
+        for (const [key, child] of byKey(node.resources))
+            visit(child, [...words, key]);
+    };
+    visit(model, []);
+    return `${lines.join('\n')}\n`;
+}
+function referenceRow(model, m) {
+    const required = byKey(m.parameters)
+        .filter(([, p]) => requiredFact(p))
+        .map(([name, p]) => `\`${name}\`${p.required ? '' : ' (per description)'}`);
+    const marked = markList(m, { reasons: true }).join('; ');
+    return `| \`gapi ${model.api} ${m.words.join(' ')}\` | ${m.httpMethod} | ${cell(oneLine(m.description))} | ${required.join(', ')} | ${m.request ? `\`${m.request}\`` : ''} | ${cell(marked)} |`;
+}
+// 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.
+    if ('method' in target) {
+        const m = target.method;
+        const shape = {
+            id: m.id,
+            httpMethod: m.httpMethod,
+            path: m.path,
+            description: m.description,
+            parameters: Object.fromEntries(m.parameters),
+            request: m.request,
+            response: m.response,
+            scopes: m.scopes,
+            supportsMediaUpload: m.upload !== undefined,
+            supportsMediaDownload: m.download !== undefined,
+        };
+        return `${JSON.stringify(shape, null, 2)}\n`;
+    }
+    const schema = model.schemas.get(target.schema);
+    const out = resolveRefs && schema ? expandObject(schema, model.schemas, [target.schema]) : schema;
+    return `${JSON.stringify(out, null, 2)}\n`;
+}
+function expandRefs(value, schemas, path) {
+    if (Array.isArray(value))
+        return value.map((v) => expandRefs(v, schemas, path));
+    return typeof value === 'object' && value !== null ? expandObject(value, schemas, path) : value;
+}
+// Replaces {"$ref": X, …} with schema X expanded, keeping the sibling keys.
+// A name already on the expansion path stays a {"$ref": X} with its siblings (cycle guard).
+function expandObject(obj, schemas, path) {
+    const ref = '$ref' in obj ? obj.$ref : undefined;
+    const name = typeof ref === 'string' && !path.includes(ref) ? ref : undefined;
+    const schema = name && schemas.get(name);
+    const own = Object.fromEntries(Object.entries(obj)
+        .filter(([k]) => !(schema && k === '$ref'))
+        .map(([k, v]) => [k, expandRefs(v, schemas, path)]));
+    return name && schema ? { ...expandObject(schema, schemas, [...path, name]), ...own } : own;
+}

package/dist/src/run.js

@@ -0,0 +1,263 @@
+// Process io is injected so tests drive the whole CLI in-process.
+import { readFile } from 'node:fs/promises';
+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, schemaView, } from './render.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' },
+    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'],
+    help: GLOBAL_OPTIONS.help,
+};
+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 or a missing flag value is a validation error.
+function parse(args, options) {
+    try {
+        return parseArgs({ args, options, allowPositionals: true, strict: true });
+    }
+    catch (e) {
+        throw new GapiError(3, messageOf(e));
+    }
+}
+async function runAuth(sub, values, { io, creds, catalog }) {
+    // --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);
+        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') {
+        await creds.logout();
+        io.stderr.write('gapi: credentials removed\n');
+        return;
+    }
+    throw new GapiError(3, `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 };
+    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 };
+}
+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,
+    });
+    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 });
+    }
+    if (api === 'schema') {
+        const { values, positionals } = parse(rest, {
+            'resolve-refs': { type: 'boolean' },
+            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;
+        const model = await catalog.load(name);
+        const resolveRefs = values['resolve-refs'] === true;
+        io.stdout.write(schemaView(model, schemaTarget(model, path), { 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)}`);
+            }),
+        });
+        return perform(call, values['dry-run'] === true, io, creds.authorize);
+    }
+    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) {
+        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));
+    return perform(call, dryRun, io, creds.authorize);
+}
+// Prints the plan's warnings, then the redacted request (--dry-run) or the response.
+async function perform(call, dryRun, io, authorize) {
+    for (const w of call.warnings)
+        io.stderr.write(`gapi: warning: ${w}\n`);
+    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,
+        };
+        io.stdout.write(`${JSON.stringify(request, null, 2)}\n`);
+        return;
+    }
+    await send(call, { fetch: io.fetch, authorize, out: io.stdout });
+}

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,15 @@
+// Media download (epic #30 D7): the response body streams to the --output file.
+import { createWriteStream } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+// The file is created only after a 2xx, so a Google error leaves no empty file behind.
+export async function download(plan, call) {
+    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/upload.js

@@ -0,0 +1,81 @@
+// 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';
+// 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) {
+    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);
+    // 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.
+async function resumable(plan, file, call) {
+    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();
+    let start = 0;
+    let stalls = 0;
+    for (;;) {
+        const end = Math.min(start + CHUNK, file.size);
+        const range = file.size === 0 ? 'bytes */0' : `bytes ${start}-${end - 1}/${file.size}`;
+        const headers = { 'Content-Range': range };
+        const res = await call(location, { method: 'PUT', headers, body: file.slice(start, end) }, 308);
+        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 (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;
+    }
+}