google-apis-cli 0.1.0 → 0.2.0

package/dist/src/apis/indexing.js

@@ -1,18 +1,40 @@
-const I = ['indexing'];
+// Indexing API v3: the discovery entry plus the `+publishBatch` helper (epic #30 D7, D10).
+import { GapiError } from '../errors.js';
+import { batchPlan, plan } from '../plan.js';
+const PUBLISH = 'indexing.urlNotifications.publish';
+const LINE = /^(URL_UPDATED|URL_DELETED)\s+(\S+)$/;
+// One notification per line; blank and `#` lines are skipped. Each line becomes one batch
+// part planned like `gapi indexing urlNotifications publish`, so every Planner rule applies.
+const publishBatch = {
+    summary: '<file>  publish URL_UPDATED|URL_DELETED <url> lines, 100 per batch call',
+    options: {},
+    plan: async ({ model, args, flags, settings, read }) => {
+        if (args.length !== 1)
+            throw new GapiError(3, 'usage: gapi indexing +publishBatch <file>');
+        const [file] = args;
+        const notes = [];
+        for (const [i, raw] of (await read(file)).split(/\r?\n/).entries()) {
+            const line = raw.trim();
+            if (line === '' || line.startsWith('#'))
+                continue;
+            const match = LINE.exec(line);
+            if (!match) {
+                throw new GapiError(3, `${file}:${i + 1}: expected URL_UPDATED <url> or URL_DELETED <url>`);
+            }
+            notes.push({ url: match[2], type: match[1] });
+        }
+        if (notes.length === 0)
+            throw new GapiError(3, `${file}: no notifications`);
+        const dryRun = flags['dry-run'] === true;
+        const parts = notes.map((n) => plan(model, PUBLISH, { body: n, dryRun }, settings));
+        return {
+            ...batchPlan(model, parts),
+            decode: (results) => Array.isArray(results) ? results.map((r, i) => ({ ...notes[i], ...r })) : results,
+        };
+    },
+};
 export default {
     api: 'indexing',
-    baseUrl: 'https://indexing.googleapis.com',
-    resources: {
-        'url-notifications': {
-            // POST body: { url, type: URL_UPDATED | URL_DELETED }.
-            publish: { httpMethod: 'POST', pathTemplate: '/v3/urlNotifications:publish', scopes: I },
-            // GET ?url= ; the url is a trailing positional (query seam), not a path param.
-            'get-metadata': {
-                httpMethod: 'GET',
-                pathTemplate: '/v3/urlNotifications/metadata',
-                scopes: I,
-                query: ['url'],
-            },
-        },
-    },
+    discovery: 'https://indexing.googleapis.com/$discovery/rest?version=v3',
+    helpers: { '+publishBatch': publishBatch },
 };

package/dist/src/apis/merchant-accounts.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-accounts',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=accounts_v1',
+};

package/dist/src/apis/merchant-conversions.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-conversions',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=conversions_v1',
+};

package/dist/src/apis/merchant-datasources.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-datasources',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=datasources_v1',
+};

package/dist/src/apis/merchant-inventories.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-inventories',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=inventories_v1',
+};

package/dist/src/apis/merchant-issueresolution.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-issueresolution',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=issueresolution_v1',
+};

package/dist/src/apis/merchant-lfp.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-lfp',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=lfp_v1',
+};

package/dist/src/apis/merchant-loyaltycustomers.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-loyaltycustomers',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=loyaltycustomers_v1',
+};

package/dist/src/apis/merchant-notifications.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-notifications',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=notifications_v1',
+};

package/dist/src/apis/merchant-ordertracking.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-ordertracking',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=ordertracking_v1',
+};

package/dist/src/apis/merchant-products.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-products',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=products_v1',
+};

package/dist/src/apis/merchant-promotions.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-promotions',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=promotions_v1',
+};

package/dist/src/apis/merchant-quota.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-quota',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=quota_v1',
+};

package/dist/src/apis/merchant-reports.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-reports',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=reports_v1',
+};

package/dist/src/apis/merchant-reviews.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'merchant-reviews',
+    discovery: 'https://merchantapi.googleapis.com/$discovery/rest?version=reviews_v1alpha',
+};

package/dist/src/apis/pagespeed.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'pagespeed',
+    discovery: 'https://pagespeedonline.googleapis.com/$discovery/rest?version=v5',
+};

package/dist/src/apis/places.js

@@ -0,0 +1,15 @@
+const billed = {
+    reason: 'Free monthly caps, then billed',
+    source: 'https://developers.google.com/maps/billing-and-pricing/pricing',
+};
+export default {
+    api: 'places',
+    discovery: 'https://places.googleapis.com/$discovery/rest?version=v1',
+    paid: {
+        'places.places.autocomplete': billed,
+        'places.places.get': billed,
+        'places.places.photos.getMedia': billed,
+        'places.places.searchNearby': billed,
+        'places.places.searchText': billed,
+    },
+};

package/dist/src/apis/postmaster.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'postmaster',
+    discovery: 'https://gmailpostmastertools.googleapis.com/$discovery/rest?version=v2',
+};

package/dist/src/apis/sa360-legacy.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'sa360-legacy',
+    discovery: 'https://doubleclicksearch.googleapis.com/$discovery/rest?version=v2',
+};

package/dist/src/apis/sa360.js

@@ -0,0 +1,12 @@
+export default {
+    api: 'sa360',
+    discovery: 'https://searchads360.googleapis.com/$discovery/rest?version=v0',
+    headers: [
+        {
+            name: 'login-customer-id',
+            flag: 'login-customer-id',
+            env: 'SA360_LOGIN_CUSTOMER_ID',
+            configKey: 'sa360-login-customer-id',
+        },
+    ],
+};

package/dist/src/apis/sheets.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'sheets',
+    discovery: 'https://sheets.googleapis.com/$discovery/rest?version=v4',
+};

package/dist/src/apis/site-verification.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'site-verification',
+    discovery: 'https://siteverification.googleapis.com/$discovery/rest?version=v1',
+};

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

@@ -0,0 +1,14 @@
+export default {
+    api: 'web-risk',
+    discovery: 'https://webrisk.googleapis.com/$discovery/rest?version=v1',
+    paid: {
+        'webrisk.hashes.search': {
+            reason: 'Paid only',
+            source: 'https://cloud.google.com/web-risk/pricing',
+        },
+        'webrisk.projects.submissions.create': {
+            reason: 'Closed to new customers',
+            source: 'https://docs.cloud.google.com/web-risk/docs/submission-api',
+        },
+    },
+};

package/dist/src/apis/youtube-analytics.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'youtube-analytics',
+    discovery: 'https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2',
+};

package/dist/src/apis/youtube-reporting.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'youtube-reporting',
+    discovery: 'https://youtubereporting.googleapis.com/$discovery/rest?version=v1',
+};

package/dist/src/apis/youtube.js

@@ -0,0 +1,4 @@
+export default {
+    api: 'youtube',
+    discovery: 'https://youtube.googleapis.com/$discovery/rest?version=v3',
+};

package/dist/src/catalog.js

@@ -0,0 +1,203 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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 { 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 { isRecord, parseOrText } from './json.js';
+const TTL_MS = 24 * 60 * 60 * 1000;
+const AUTH_PREFIX = 'https://www.googleapis.com/auth/';
+// Scopes gapi never requests (D8); `drive.*` is matched by prefix.
+const NEVER = new Set(['drive', 'openid', 'email', 'profile', 'display-video-user-management']);
+// Discovery reference: `kind` is "The fixed string discovery#restDescription."
+const isRestDescription = (v) => isRecord(v) && v.kind === 'discovery#restDescription';
+export async function openCatalog({ dir, fetch, warn, apisDir = join(import.meta.dirname, 'apis'), }) {
+    const entries = await loadEntries(apisDir);
+    const cacheDir = join(dir, 'cache');
+    const models = new Map();
+    // A non-2xx answer or a body that is not a discovery document is a failed fetch, never cached.
+    async function download(url) {
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const text = await res.text();
+        const doc = JSON.parse(text);
+        if (!isRestDescription(doc))
+            throw new Error('response is not a discovery#restDescription');
+        return { text, doc };
+    }
+    // A cache file that is unreadable, not JSON or not a discovery document reads as absent.
+    const cached = async (file) => {
+        const doc = await readFile(file, 'utf8').then(parseOrText, () => undefined);
+        return isRestDescription(doc) ? doc : undefined;
+    };
+    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) {
+            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);
+            return got.doc;
+        }
+        const stale = mtime === undefined ? undefined : await cached(file);
+        if (!stale) {
+            throw new GapiError(4, `discovery fetch failed for ${entry.api}: ${got.message}; retry: gapi discovery refresh ${entry.api}`);
+        }
+        warn(`discovery fetch failed for ${entry.api}: ${got.message}; using cached copy`);
+        return stale;
+    }
+    async function load(api, { refresh = false } = {}) {
+        const memo = models.get(api);
+        if (memo && !refresh)
+            return memo;
+        const entry = Object.hasOwn(entries, api) ? entries[api] : undefined;
+        if (!entry)
+            throw new GapiError(3, `unknown api: ${api}`);
+        const model = toModel(await document(entry, refresh), entry);
+        models.set(api, model);
+        return model;
+    }
+    return { entries, load, cacheDir };
+}
+// `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) => {
+    const short = shortScope(scope);
+    return NEVER.has(short) || short.startsWith('drive.');
+};
+function toModel(doc, entry) {
+    const scopes = (entry.scopes ?? []).map((s) => AUTH_PREFIX + s);
+    const byId = new Map();
+    const build = (node, words) => ({
+        methods: new Map(Object.entries(node.methods ?? {}).map(([key, m]) => {
+            const method = toMethod(m, [...words, key], scopes, doc.schemas ?? {});
+            byId.set(method.id, method);
+            return [key, method];
+        })),
+        resources: new Map(Object.entries(node.resources ?? {}).map(([key, r]) => [key, build(r, [...words, key])])),
+    });
+    const root = build(doc, []);
+    // Auth kind first (D8): no grantable scope anywhere and no entry scopes → API key.
+    const listed = [
+        ...Object.keys(doc.auth?.oauth2?.scopes ?? {}),
+        ...[...byId.values()].flatMap((m) => m.scopes),
+    ];
+    const auth = scopes.length === 0 && listed.every(isNever) ? 'apiKey' : 'oauth';
+    if (auth === 'oauth') {
+        for (const m of byId.values())
+            m.unavailable = m.scopes.length > 0 && m.scopes.every(isNever);
+    }
+    const problems = [];
+    const overlay = (kind, values, apply) => {
+        for (const [id, value] of Object.entries(values ?? {})) {
+            const m = byId.get(id);
+            if (m)
+                apply(m, value);
+            else
+                problems.push(`${kind} ${id}: not in the document`);
+        }
+    };
+    overlay('retired', entry.retired, (m, v) => {
+        m.retired = v;
+    });
+    overlay('deprecated', entry.deprecated, (m, v) => {
+        m.deprecated = v;
+    });
+    overlay('paid', entry.paid, (m, v) => {
+        m.paid = v;
+    });
+    return {
+        ...root,
+        api: entry.api,
+        name: doc.name ?? entry.api,
+        version: doc.version ?? '',
+        title: doc.title,
+        description: doc.description,
+        documentationLink: doc.documentationLink,
+        rootUrl: doc.rootUrl ?? '',
+        servicePath: doc.servicePath ?? '',
+        auth,
+        scopes,
+        byId,
+        parameters: new Map(Object.entries(doc.parameters ?? {})),
+        schemas: new Map(Object.entries(doc.schemas ?? {})),
+        headers: entry.headers,
+        problems,
+    };
+}
+// A method whose document lists no scopes takes the entry scopes (D8: `business-*`).
+function toMethod(m, words, entryScopes, schemas) {
+    const scopes = m.scopes?.length ? m.scopes : entryScopes;
+    const parameters = new Map(Object.entries(m.parameters ?? {}));
+    const schemaHas = (ref, field) => {
+        const properties = ref && Object.hasOwn(schemas, ref.$ref) ? schemas[ref.$ref].properties : {};
+        return isRecord(properties) && Object.hasOwn(properties, field);
+    };
+    return {
+        id: m.id,
+        words,
+        httpMethod: m.httpMethod,
+        path: m.path,
+        description: m.description,
+        parameters,
+        parameterOrder: m.parameterOrder ?? [],
+        request: m.request?.$ref,
+        response: m.response?.$ref,
+        scopes,
+        scope: scopes.find((s) => !isNever(s)),
+        unavailable: false,
+        deprecated: m.deprecated ? {} : undefined,
+        upload: m.supportsMediaUpload
+            ? {
+                accept: m.mediaUpload?.accept ?? [],
+                maxSize: m.mediaUpload?.maxSize,
+                resumable: m.mediaUpload?.protocols?.resumable !== undefined,
+            }
+            : undefined,
+        download: m.supportsMediaDownload ? { service: m.useMediaDownloadService === true } : undefined,
+        // D6: a `pageToken` query parameter, else a request field answered by `nextPageToken`.
+        paging: parameters.get('pageToken')?.location === 'query'
+            ? 'query'
+            : schemaHas(m.request, 'pageToken') && schemaHas(m.response, 'nextPageToken')
+                ? 'body'
+                : undefined,
+    };
+}
+// The two fields every API entry sets; `satisfies ApiEntry` in the file checks the rest.
+const isApiEntry = (v) => isRecord(v) && typeof v.api === 'string' && typeof v.discovery === 'string';
+// Dev (.ts) and published (.js) entries, keyed by `api`; D1 ties `api` to the file name.
+async function loadEntries(dir) {
+    const files = (await readdir(dir)).filter((f) => (f.endsWith('.ts') || f.endsWith('.js')) && !f.endsWith('.d.ts'));
+    const entries = {};
+    for (const f of files) {
+        const file = join(dir, f);
+        const e = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href))).default;
+        if (!isApiEntry(e))
+            throw new Error(`${file}: default export is not an API entry`);
+        const name = basename(f, extname(f));
+        if (e.api !== name)
+            throw new Error(`${file}: api '${e.api}' must equal '${name}'`);
+        entries[e.api] = e;
+    }
+    return entries;
+}
+// Temp file + rename so a reader never sees a half-written document.
+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 });
+    await rename(tmp, file);
+}