@gscdump/cli 3.8.0 → 4.0.0

package/dist/dump-writers.mjs

@@ -0,0 +1,246 @@
+import { exportColumns, readParquetSql, sourceSelectSql, sqlString } from "./table-sources.mjs";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { DuckDBInstance } from "@duckdb/node-api";
+import { encodeRowsToParquetFlex } from "@gscdump/engine/hyparquet";
+const DUMP_FORMATS = [
+	"parquet",
+	"csv",
+	"json",
+	"ndjson",
+	"sqlite",
+	"duckdb"
+];
+function isDumpFormat(value) {
+	return DUMP_FORMATS.includes(value);
+}
+function siteDirName(siteUrl) {
+	return siteUrl.replace(/[^a-z0-9]+/gi, "_");
+}
+function createSiteDirNamer() {
+	const dirBySite = /* @__PURE__ */ new Map();
+	return (siteUrl) => {
+		const known = dirBySite.get(siteUrl);
+		if (known !== void 0) return known;
+		const base = siteDirName(siteUrl);
+		const dir = [...dirBySite.values()].includes(base) ? `${base}_${createHash("sha256").update(siteUrl).digest("hex").slice(0, 8)}` : base;
+		dirBySite.set(siteUrl, dir);
+		return dir;
+	};
+}
+function databasePath(outDir, format) {
+	return path.join(outDir, `gscdump.${format}`);
+}
+const COPY_OPTIONS = {
+	parquet: "FORMAT parquet, COMPRESSION zstd",
+	csv: "FORMAT csv, HEADER true",
+	json: "FORMAT json, ARRAY true",
+	ndjson: "FORMAT json"
+};
+const SQLITE_TYPES = {
+	VARCHAR: "TEXT",
+	DATE: "TEXT",
+	INTEGER: "INTEGER",
+	BIGINT: "INTEGER",
+	DOUBLE: "REAL"
+};
+async function openSession() {
+	const instance = await DuckDBInstance.create(":memory:");
+	const connection = await instance.connect();
+	const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "gscdump-dump-"));
+	return {
+		connection,
+		tempDir,
+		async close() {
+			connection.closeSync();
+			instance.closeSync();
+			await fs.rm(tempDir, {
+				recursive: true,
+				force: true
+			});
+		}
+	};
+}
+async function countOf(connection, sql) {
+	const reader = await connection.runAndReadAll(sql);
+	return Number(reader.getRowsJS()[0]?.[0] ?? 0);
+}
+async function presentColumns(connection, source) {
+	const reader = await connection.runAndReadAll(`DESCRIBE SELECT * FROM ${readParquetSql(source.files)}`);
+	return new Set(reader.getRowObjectsJS().map((row) => String(row.column_name)));
+}
+async function entitySelect(session, site, dataset) {
+	const file = path.join(session.tempDir, `${siteDirName(site)}-${dataset.dataset}.parquet`);
+	await fs.writeFile(file, encodeRowsToParquetFlex(dataset.rows, { columns: dataset.columns }));
+	const columns = dataset.columns.map((column) => column.name).join(", ");
+	return `SELECT ${sqlString(site)} AS site, ${columns} FROM read_parquet(${sqlString(file)})`;
+}
+function entityColumns(dataset) {
+	return [{
+		name: "site",
+		type: "VARCHAR",
+		nullable: false
+	}, ...dataset.columns];
+}
+async function openDumpSink(outDir, format) {
+	await fs.mkdir(outDir, { recursive: true });
+	if (format === "sqlite") return openSqliteSink(outDir);
+	if (format === "duckdb") return openDuckDBSink(outDir);
+	return openFileSink(outDir, format);
+}
+async function openFileSink(outDir, format) {
+	const session = await openSession();
+	const written = [];
+	const siteDir = createSiteDirNamer();
+	const copy = async (select, target) => {
+		await fs.mkdir(path.dirname(target), { recursive: true });
+		const rows = await countOf(session.connection, `COPY (${select}) TO ${sqlString(target)} (${COPY_OPTIONS[format]})`);
+		written.push(target);
+		return rows;
+	};
+	const position = format !== "parquet";
+	return {
+		async writeTable(source) {
+			const select = sourceSelectSql(source, await presentColumns(session.connection, source), {
+				position,
+				dates: "date"
+			});
+			const target = path.join(outDir, siteDir(source.site), source.searchType, `${source.table}.${format}`);
+			return {
+				dataset: source.table,
+				searchType: source.searchType,
+				path: target,
+				rows: await copy(select, target)
+			};
+		},
+		async writeEntity(site, dataset) {
+			const target = path.join(outDir, siteDir(site), `${dataset.dataset}.${format}`);
+			return {
+				dataset: dataset.dataset,
+				path: target,
+				rows: await copy(await entitySelect(session, site, dataset), target)
+			};
+		},
+		async close() {
+			await session.close();
+			return Promise.all(written.map(async (file) => ({
+				path: file,
+				bytes: (await fs.stat(file)).size
+			})));
+		}
+	};
+}
+async function openDuckDBSink(outDir) {
+	const target = databasePath(outDir, "duckdb");
+	await fs.rm(target, { force: true });
+	await fs.rm(`${target}.wal`, { force: true });
+	const session = await openSession();
+	await session.connection.run(`ATTACH ${sqlString(target)} AS out`);
+	const created = /* @__PURE__ */ new Set();
+	const insert = async (name, columns, select) => {
+		if (!created.has(name)) {
+			const ddl = columns.map((column) => `${column.name} ${column.type}${column.nullable ? "" : " NOT NULL"}`).join(", ");
+			await session.connection.run(`CREATE TABLE out.${name} (${ddl})`);
+			created.add(name);
+		}
+		return countOf(session.connection, `INSERT INTO out.${name} BY NAME ${select}`);
+	};
+	return {
+		async writeTable(source) {
+			const select = sourceSelectSql(source, await presentColumns(session.connection, source), {
+				position: false,
+				dates: "date"
+			});
+			return {
+				dataset: source.table,
+				searchType: source.searchType,
+				path: target,
+				rows: await insert(source.table, exportColumns(source.table), select)
+			};
+		},
+		async writeEntity(site, dataset) {
+			return {
+				dataset: dataset.dataset,
+				path: target,
+				rows: await insert(dataset.dataset, entityColumns(dataset), await entitySelect(session, site, dataset))
+			};
+		},
+		async close() {
+			await session.connection.run("DETACH out");
+			await session.close();
+			return [{
+				path: target,
+				bytes: (await fs.stat(target)).size
+			}];
+		}
+	};
+}
+function sqliteValue(value) {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "boolean") return value ? 1 : 0;
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "string" || typeof value === "number" || typeof value === "bigint") return value;
+	return JSON.stringify(value);
+}
+async function openSqliteSink(outDir) {
+	const target = databasePath(outDir, "sqlite");
+	await fs.rm(target, { force: true });
+	const { DatabaseSync } = await import("node:sqlite");
+	const db = new DatabaseSync(target);
+	const session = await openSession();
+	const created = /* @__PURE__ */ new Set();
+	const insert = async (name, columns, select) => {
+		if (!created.has(name)) {
+			const ddl = columns.map((column) => `"${column.name}" ${SQLITE_TYPES[column.type]}${column.nullable ? "" : " NOT NULL"}`).join(", ");
+			db.exec(`CREATE TABLE "${name}" (${ddl})`);
+			created.add(name);
+		}
+		const statement = db.prepare(`INSERT INTO "${name}" (${columns.map((column) => `"${column.name}"`).join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`);
+		const result = await session.connection.stream(`SELECT ${columns.map((column) => column.name).join(", ")} FROM (${select})`);
+		let rows = 0;
+		db.exec("BEGIN");
+		try {
+			for await (const chunk of result.yieldRowsJs()) for (const row of chunk) {
+				statement.run(...row.map(sqliteValue));
+				rows++;
+			}
+			db.exec("COMMIT");
+		} catch (error) {
+			db.exec("ROLLBACK");
+			throw error;
+		}
+		return rows;
+	};
+	return {
+		async writeTable(source) {
+			const select = sourceSelectSql(source, await presentColumns(session.connection, source), {
+				position: false,
+				dates: "iso"
+			});
+			return {
+				dataset: source.table,
+				searchType: source.searchType,
+				path: target,
+				rows: await insert(source.table, exportColumns(source.table), select)
+			};
+		},
+		async writeEntity(site, dataset) {
+			return {
+				dataset: dataset.dataset,
+				path: target,
+				rows: await insert(dataset.dataset, entityColumns(dataset), await entitySelect(session, site, dataset))
+			};
+		},
+		async close() {
+			db.close();
+			await session.close();
+			return [{
+				path: target,
+				bytes: (await fs.stat(target)).size
+			}];
+		}
+	};
+}
+export { DUMP_FORMATS, createSiteDirNamer, databasePath, isDumpFormat, openDumpSink, siteDirName };

package/dist/error-handler.mjs

@@ -1,41 +1,41 @@
-import { formatAuthProvenance, isAuthError } from "./auth.mjs";
-import process from "node:process";
-import { isQueryError } from "gscdump/query";
+import { isUsageError } from "./command-registry.mjs";
+import { quotaStopOf } from "./quota-ledger.mjs";
 import { isAnalysisError } from "@gscdump/analysis/errors";
 import { isEngineError } from "@gscdump/engine/errors";
 import { classifyError } from "gscdump/errors";
+import { isQueryError } from "gscdump/query";
+const HOSTED_KEY_REJECTED_REASON = "gscdump.com rejected the API key";
+const HOSTED_KEY_REJECTED = `${HOSTED_KEY_REJECTED_REASON}. Run \`gscdump auth login --mode cloud --api-key KEY\` with a valid key.`;
 const QUOTA_MESSAGE_RE = /quota|rate\s*limit/i;
-function formatErrorForCli(cause) {
-	const error = classifyError(cause);
-	const lines = [`\x1B[31m${error.message}\x1B[0m`];
-	let suggestion = "";
+const ANSI_RE = /\x1B\[[0-9;]*m/g;
+function suggestionForGscError(error) {
 	switch (error.kind) {
-		case "auth-expired":
-			suggestion = "Run `gscdump auth` to re-authenticate.";
-			break;
+		case "auth-expired": return "Run `gscdump auth login` to sign in again.";
+		case "permission-denied": return "Check that this Google account is a full user or owner of the Site. Run `gscdump sites` to see your Sites.";
 		case "rate-limited": {
 			const retryIn = error.retryAfter ? `${error.retryAfter}s` : "a few minutes";
-			if (QUOTA_MESSAGE_RE.test(error.message)) suggestion = error.message.includes("Indexing API") ? "Indexing API quota exhausted (~200/day). Try again tomorrow." : `Quota or rate limit hit (Search Analytics ~25000/day). Try again in ${retryIn}.`;
-			else suggestion = `Rate limited. Slow down requests. Try again in ${retryIn}.`;
-			break;
+			if (!QUOTA_MESSAGE_RE.test(error.message)) return `Google rate limited the request. Try again in ${retryIn}.`;
+			return error.message.includes("Indexing API") ? "The Indexing API quota is used up (about 200 per day). Try again tomorrow." : `A Google quota or rate limit was reached. Try again in ${retryIn}.`;
 		}
+		case "not-found":
+		case "validation":
+		case "storage":
+		case "transport": return "";
 	}
-	if (suggestion) lines.push("", suggestion);
-	return lines.join("\n");
 }
 function extractQueryError(error) {
 	if (isQueryError(error)) return error;
-	const tagged = error.queryError;
+	const tagged = error?.queryError;
 	return isQueryError(tagged) ? tagged : null;
 }
 function extractEngineError(error) {
 	if (isEngineError(error)) return error;
-	const tagged = error.engineError;
+	const tagged = error?.engineError;
 	return isEngineError(tagged) ? tagged : null;
 }
 function extractAnalysisError(error) {
 	if (isAnalysisError(error)) return error;
-	const tagged = error.analysisError;
+	const tagged = error?.analysisError;
 	return isAnalysisError(tagged) ? tagged : null;
 }
 function suggestionForTypedError(error) {
@@ -52,7 +52,7 @@ function suggestionForTypedError(error) {
 	}
 	const analysis = extractAnalysisError(error);
 	if (analysis) switch (analysis.kind) {
-		case "missing-report-param": return `Report "${analysis.report}" needs --${analysis.param}.`;
+		case "missing-report-param": return `Report "${analysis.report}" needs ${flagForParam(analysis.param)}.`;
 		case "missing-comparison-window": return `Report "${analysis.report}" is a comparison report; pass --vs prev-period (or --vs yoy).`;
 		case "missing-brand-terms": return "Pass --brand-terms to segment branded vs non-branded queries.";
 		case "unknown-report": return `Unknown report. Available: ${analysis.available.join(", ")}.`;
@@ -81,25 +81,95 @@ var LocalStoreUnsupportedError = class extends Error {
 		this.mode = mode;
 	}
 };
-async function gscErrorHandler(error) {
-	console.error();
-	if (error instanceof LocalStoreUnsupportedError) {
-		console.error(formatErrorForCli(error));
-		if (error.mode === "local") console.error("Pass --live to run against the GSC API.");
-		console.error();
-		process.exit(1);
-	}
-	console.error(formatErrorForCli(error));
-	const typedHint = suggestionForTypedError(error);
-	if (typedHint) {
-		console.error();
-		console.error(typedHint);
+function isAuthError(err) {
+	const msg = (err instanceof Error ? err.message : String(err ?? "")).toLowerCase();
+	if (!msg) return false;
+	return /\b(?:401|unauthorized|invalid_grant|invalid_token|insufficient.*scope|invalid_client|token has been expired|token has been revoked)\b/.test(msg) || msg.includes("oauth2.googleapis.com/token");
+}
+function flagForParam(param) {
+	return {
+		prevStartDate: "--prev-start",
+		prevEndDate: "--prev-end",
+		startDate: "--start",
+		endDate: "--end"
+	}[param] ?? `--${param.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+}
+const PARAM_NAME_RE = /\b(prevStartDate|prevEndDate|brandTerms)\b/g;
+const DEFECT_ERRORS = /* @__PURE__ */ new Set([
+	"TypeError",
+	"ReferenceError",
+	"RangeError",
+	"SyntaxError",
+	"EvalError",
+	"URIError"
+]);
+function describeCliError(error) {
+	if (isUsageError(error)) return {
+		kind: "usage",
+		message: error.message
+	};
+	if (error instanceof Error && error.routeStop !== void 0) return {
+		kind: "stop",
+		message: error.message
+	};
+	if (error instanceof Error && quotaStopOf(error)) return {
+		kind: "stop",
+		message: error.message
+	};
+	if (error instanceof TypeError && error.message === "fetch failed") {
+		const cause = error.cause;
+		return {
+			kind: "expected",
+			message: `Network request failed: ${cause instanceof Error ? cause.message : "no response"}`,
+			hint: "Check your connection, then try again.",
+			showAuthSources: false
+		};
 	}
-	if (isAuthError(error)) {
-		console.error();
-		console.error(await formatAuthProvenance());
+	if (error instanceof Error && DEFECT_ERRORS.has(error.constructor.name)) return {
+		kind: "defect",
+		message: `${error.name}: ${error.message}`,
+		stack: error.stack ?? ""
+	};
+	if (error instanceof LocalStoreUnsupportedError) return {
+		kind: "expected",
+		message: error.message,
+		hint: error.mode === "local" ? "Pass --live to run against the GSC API." : "",
+		showAuthSources: false
+	};
+	const classified = classifyError(error);
+	if (classified.message === HOSTED_KEY_REJECTED) return {
+		kind: "expected",
+		message: classified.message,
+		hint: "",
+		showAuthSources: false
+	};
+	return {
+		kind: "expected",
+		message: classified.message.replace(PARAM_NAME_RE, (name) => flagForParam(name)),
+		hint: suggestionForTypedError(error) || suggestionForGscError(classified),
+		showAuthSources: classified.kind === "auth-expired" || classified.kind === "permission-denied" || isAuthError(error)
+	};
+}
+async function reportCliError(error, options) {
+	const report = describeCliError(error);
+	const red = (text) => options.color ? `\x1B[31m${text}\x1B[0m` : text;
+	const lines = [];
+	switch (report.kind) {
+		case "usage":
+			if (options.usage) lines.push(await options.usage(), "");
+			lines.push(red(report.message));
+			break;
+		case "stop":
+			lines.push(report.message);
+			break;
+		case "expected":
+			lines.push(red(`Error: ${report.message}`));
+			if (report.hint) lines.push(report.hint);
+			if (report.showAuthSources && options.authSources) lines.push("", await options.authSources());
+			break;
+		case "defect": lines.push(red(`Unexpected error. Report it at https://github.com/harlan-zw/gscdump/issues`), report.stack || report.message);
 	}
-	console.error();
-	process.exit(1);
+	const text = lines.join("\n");
+	(options.write ?? ((value) => console.error(value)))(options.color ? text : text.replace(ANSI_RE, ""));
 }
-export { LocalStoreUnsupportedError, gscErrorHandler };
+export { HOSTED_KEY_REJECTED, HOSTED_KEY_REJECTED_REASON, LocalStoreUnsupportedError, describeCliError, flagForParam, isAuthError, reportCliError };

package/dist/filters.mjs

@@ -0,0 +1,125 @@
+import { and } from "gscdump/query";
+import { toPath } from "@gscdump/engine/ingest";
+const FILTER_DIMS = [
+	"query",
+	"page",
+	"country",
+	"device",
+	"searchAppearance"
+];
+function splitOperator(raw) {
+	if (raw.startsWith("!~")) return {
+		operator: "notContains",
+		value: raw.slice(2)
+	};
+	if (raw.startsWith("!re:")) return {
+		operator: "excludingRegex",
+		value: raw.slice(4)
+	};
+	if (raw.startsWith("!")) return {
+		operator: "notEquals",
+		value: raw.slice(1)
+	};
+	if (raw.startsWith("~")) return {
+		operator: "contains",
+		value: raw.slice(1)
+	};
+	if (raw.startsWith("re:")) return {
+		operator: "includingRegex",
+		value: raw.slice(3)
+	};
+	if (raw.startsWith("contains:")) return {
+		operator: "contains",
+		value: raw.slice(9)
+	};
+	if (raw.startsWith("eq:")) return {
+		operator: "equals",
+		value: raw.slice(3)
+	};
+	return {
+		operator: "equals",
+		value: raw
+	};
+}
+function parsePageRef(value) {
+	if (!/^https?:\/\//i.test(value)) return { path: value };
+	const origin = URL.canParse(value) ? new URL(value).origin : void 0;
+	return origin ? {
+		path: toPath(value),
+		origin
+	} : { path: value };
+}
+function parseFilterArg(dim, raw) {
+	const { operator, value } = splitOperator(raw);
+	if (operator === "includingRegex" || operator === "excludingRegex") return {
+		kind: "regex",
+		dim,
+		operator,
+		pattern: value
+	};
+	if (dim === "page") return {
+		kind: "page",
+		operator,
+		page: parsePageRef(value)
+	};
+	return {
+		kind: "match",
+		dim,
+		operator,
+		value
+	};
+}
+function parseFilterArgs(args) {
+	const argName = {
+		query: "query",
+		page: "page",
+		country: "country",
+		device: "device",
+		searchAppearance: "search-appearance"
+	};
+	return FILTER_DIMS.flatMap((dim) => {
+		const raw = args[argName[dim]] ?? args[dim];
+		return raw == null || raw === "" ? [] : [parseFilterArg(dim, String(raw))];
+	});
+}
+function filterDimensions(filters) {
+	return [...new Set(filters.map((filter) => filter.kind === "page" ? "page" : filter.dim))];
+}
+function leaf(dimension, operator, expression) {
+	return {
+		_constraints: {},
+		_filters: [{
+			dimension,
+			operator,
+			expression
+		}]
+	};
+}
+function combine(leaves) {
+	if (leaves.length <= 1) return leaves[0];
+	return and(...leaves);
+}
+function localLeaf(filter) {
+	if (filter.kind === "page") return leaf("page", filter.operator, filter.page.path);
+	return filter.kind === "match" ? leaf(filter.dim, filter.operator, filter.value) : leaf(filter.dim, filter.operator, filter.pattern);
+}
+function toLocalFilter(filters) {
+	return combine(filters.map(localLeaf));
+}
+function escapeRegex(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function livePageLeaf(operator, page, siteUrl) {
+	if (page.origin) return leaf("page", operator, `${page.origin}${page.path}`);
+	if (operator === "contains" || operator === "notContains") return leaf("page", operator, page.path);
+	const path = page.path.startsWith("/") ? page.path : `/${page.path}`;
+	if (siteUrl.startsWith("sc-domain:")) return leaf("page", operator === "equals" ? "includingRegex" : "excludingRegex", `^https?://[^/]+${escapeRegex(path)}$`);
+	const url = new URL(siteUrl);
+	const propertyPath = url.pathname.replace(/\/+$/, "");
+	if (propertyPath && (path === propertyPath || path.startsWith(`${propertyPath}/`))) return leaf("page", operator, `${url.origin}${path}`);
+	return leaf("page", operator, `${siteUrl.endsWith("/") ? siteUrl.slice(0, -1) : siteUrl}${path}`);
+}
+function toLiveFilter(filters, siteUrl) {
+	return combine(filters.map((filter) => filter.kind === "page" ? livePageLeaf(filter.operator, filter.page, siteUrl) : localLeaf(filter)));
+}
+export { FILTER_DIMS, filterDimensions, parseFilterArg, parseFilterArgs, parsePageRef, toLiveFilter, toLocalFilter };

package/dist/hosted-site.mjs

@@ -0,0 +1,91 @@
+import { getCloudAccount, parseAuthentication, resolveAuthentication } from "./auth-state.mjs";
+import { loadConfig } from "./config.mjs";
+import { resolveCliEnvironment } from "./environment.mjs";
+import { logger } from "./utils.mjs";
+import process from "node:process";
+import { createGscdumpV1Client } from "@gscdump/sdk/v1";
+const HOSTED_ARGS = {
+	"site": {
+		type: "string",
+		alias: "s",
+		description: "Site URL (e.g., example.com, sc-domain:example.com, or https://example.com/)"
+	},
+	"api-root": {
+		type: "string",
+		description: "Hosted API root; defaults to saved cloud authentication or https://gscdump.com/api"
+	},
+	"api-key": {
+		type: "string",
+		description: "Hosted API key; defaults to GSCDUMP_API_KEY"
+	}
+};
+function siteKey(value) {
+	const text = value.trim();
+	if (text.startsWith("sc-domain:")) return text.slice(10).toLowerCase().replace(/\.$/, "") || void 0;
+	const url = URL.parse(/^[a-z][a-z\d+.-]*:\/\//i.test(text) ? text : `https://${text}`);
+	if (!url || !url.hostname) return void 0;
+	return `${url.hostname.toLowerCase()}${url.pathname.replace(/\/+$/, "")}`;
+}
+function matchHostedSite(sites, target) {
+	if (!target) return sites.length === 1 ? {
+		kind: "found",
+		site: sites[0]
+	} : {
+		kind: "missing",
+		target,
+		sites: [...sites]
+	};
+	const exact = sites.find((site) => site.siteId === target || site.siteUrl === target);
+	if (exact) return {
+		kind: "found",
+		site: exact
+	};
+	const key = siteKey(target);
+	const matches = key === void 0 ? [] : sites.filter((site) => siteKey(site.siteUrl) === key);
+	if (matches.length === 1) return {
+		kind: "found",
+		site: matches[0]
+	};
+	if (matches.length > 1) return {
+		kind: "ambiguous",
+		target,
+		matches
+	};
+	return {
+		kind: "missing",
+		target,
+		sites: [...sites]
+	};
+}
+function describeMatchFailure(match) {
+	if (match.kind === "ambiguous") return `Multiple hosted Sites match "${match.target}": ${match.matches.map((site) => site.siteUrl).join(", ")}. Pass the exact Site URL with --site.`;
+	if (match.sites.length === 0) return "Your hosted account has no Sites. Add a Site at https://gscdump.com.";
+	const available = `Hosted Sites: ${match.sites.map((site) => site.siteUrl).join(", ")}.`;
+	return match.target ? `No hosted Site matches "${match.target}". ${available}` : `Pass --site. ${available}`;
+}
+function fail(message) {
+	logger.error(message);
+	process.exit(1);
+}
+async function resolveHostedSite(args, command) {
+	if (args._?.length) fail(`\`gscdump ${command.name}\` does not accept a positional Site ID. Pass --site instead.`);
+	const environment = resolveCliEnvironment().values;
+	const authentication = args["api-key"] ? parseAuthentication({
+		_tag: "Cloud",
+		apiKey: args["api-key"],
+		apiRoot: String(args["api-root"] || environment.GSCDUMP_API_ROOT || "https://gscdump.com/api")
+	}) : await resolveAuthentication();
+	if (authentication._tag !== "Cloud") fail(`\`gscdump ${command.name}\` needs hosted authentication. Run \`gscdump auth login --mode cloud\` or pass --api-key. With local authentication, ${command.localAlternative}.`);
+	if (args["api-root"] && String(args["api-root"]).replace(/\/+$/, "") !== authentication.apiRoot) fail("The API root changed. Pass --api-key for the new API root.");
+	const target = args.site ? String(args.site) : (await loadConfig()).defaultSite;
+	const match = matchHostedSite((await getCloudAccount(authentication)).sites, target);
+	if (match.kind !== "found") fail(describeMatchFailure(match));
+	return {
+		client: createGscdumpV1Client({
+			apiRoot: authentication.apiRoot,
+			credential: authentication.apiKey
+		}),
+		site: match.site
+	};
+}
+export { HOSTED_ARGS, matchHostedSite, resolveHostedSite };