@gscdump/cli 3.6.3 → 3.8.0

package/README.md

@@ -20,7 +20,7 @@ npx @gscdump/cli
 ## Quick start
 
 ```bash
-# Set up local Google OAuth
+# Connect Google for free local CLI use
 gscdump init --mode local
 gscdump auth login --mode local
 
@@ -280,16 +280,22 @@ This section covers local Google credentials. See [shared authentication](#hoste
 Credentials are saved under `~/.config/gscdump/` on XDG systems, or the platform equivalent.
 Use `gscdump auth login --mode local` to connect Google and save local mode.
 
-Local Google browser login uses a temporary listener on `127.0.0.1` with a random port.
+If you configure your own Google OAuth client, browser login uses a temporary listener on `127.0.0.1` with a random port.
 Each attempt uses state validation and PKCE S256 to bind the authorization response to that attempt.
 The listener closes after authorization, denial, or a five-minute timeout.
 
-For manual setup:
+By default, login opens gscdump.com. No Google Cloud project is required.
+The platform handles Google login and token refresh. Data queries call Google directly.
+This grants read-only Search Console access. It does not activate hosted sync, storage, or hosted MCP.
+Hosted Pro is free during beta and will require payment after launch.
+For Google write operations, configure your own OAuth client with the required scopes.
+
+For your own OAuth client:
 
 1. Create a Google Cloud project.
 2. Enable **Search Console API**, **Web Search Indexing API**, and **Site Verification API**.
 3. Create OAuth2 credentials (Desktop app).
-4. Run `gscdump init --mode local` to configure credentials and a Store directory.
+4. Set `GSC_CLIENT_ID` and `GSC_CLIENT_SECRET` for your Desktop app.
 5. Run `gscdump auth login --mode local` to save local mode.
 
 ### BYOK (Bring Your Own Key)
@@ -328,8 +334,9 @@ gscdump auth login --mode local --no-browser
 # Open the printed URL in your browser.
 ```
 
-This uses the same Desktop application OAuth client and loopback flow as browser login.
-Google's device flow does not support the required scopes.
+Default login works from a remote terminal without port forwarding. Keep the command running until you approve the browser request.
+
+With your own OAuth client, login uses the Desktop application loopback flow.
 
 If the CLI runs on another host, forward its printed loopback port before opening the URL.
 Keep the login command running on that host.

package/dist/auth-scopes.mjs

@@ -1,9 +1,9 @@
-import { GSC_INDEXING_SCOPE, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, hasGoogleScope } from "gscdump/client";
-function missingRequiredScopes(scopes) {
-	return [
+import { GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, hasGoogleScope } from "gscdump/client";
+function missingRequiredScopes(scopes, provider) {
+	return (provider === "gscdump" ? [GSC_READ_SCOPE] : [
 		GSC_WRITE_SCOPE,
 		GSC_INDEXING_SCOPE,
 		GSC_SITE_VERIFICATION_SCOPE
-	].filter((scope) => !hasGoogleScope(scopes, scope));
+	]).filter((scope) => !hasGoogleScope(scopes, scope));
 }
 export { missingRequiredScopes };

package/dist/auth.mjs

@@ -2,6 +2,7 @@ import { getConfigDir, loadConfig } from "./config.mjs";
 import { pickCliEnvironmentValue, resolveCliEnvironment } from "./environment.mjs";
 import { getAppliedEnvKeys, getLoadedEnvPath } from "./env-file.mjs";
 import { displayPath, logger } from "./utils.mjs";
+import { loginWithPlatform, refreshWithPlatform } from "./hosted-auth.mjs";
 import process from "node:process";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import fs from "node:fs/promises";
@@ -11,6 +12,7 @@ import { err, ok, unwrapResult } from "gscdump/result";
 import { text } from "@clack/prompts";
 import { createAuth } from "gscdump/client";
 import { createServer } from "node:http";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { CodeChallengeMethod, JWT, OAuth2Client } from "google-auth-library";
 import open from "open";
 function authErrorToException(error) {
@@ -261,7 +263,8 @@ async function authenticate(credentials, interactive, opts = {}) {
 		}
 		return oauth2Client;
 	}
-	const existingTokens = !opts.force ? await loadTokens() : null;
+	const savedTokens = !opts.force ? await loadTokens() : null;
+	const existingTokens = savedTokens?.provider === "gscdump" ? null : savedTokens;
 	let refreshFailed = false;
 	let refreshError = null;
 	if (existingTokens) {
@@ -321,10 +324,44 @@ async function authenticate(credentials, interactive, opts = {}) {
 }
 async function getAuth(opts = {}) {
 	const { interactive = true, noBrowser = false, force = false } = opts;
-	return authenticate(await getAuthCredentials(interactive), interactive, {
+	const env = resolveCliEnvironment();
+	const config = opts.config ?? await loadConfig();
+	if (env.clientId && env.clientSecret || config.clientId && config.clientSecret) return authenticate(await getAuthCredentials(interactive), interactive, {
 		noBrowser,
 		force
 	});
+	let tokens = force ? null : await loadTokens();
+	if (tokens?.provider !== "gscdump" || !tokens.refresh_token) {
+		if (!interactive) throw new Error("Run `gscdump auth login` to connect Google.");
+		tokens = await loginWithPlatform({
+			force,
+			request: fetch,
+			now: Date.now,
+			wait: setTimeout$1,
+			authorize: async (url) => {
+				logger.info(`Open this URL to connect Google:\n${url}`);
+				if (!noBrowser) await open(url).catch((error) => logger.warn(`Browser could not open: ${error.message}. Open the URL above.`));
+			}
+		});
+		await saveTokens(tokens);
+	}
+	const refreshToken = tokens.refresh_token;
+	const client = new OAuth2Client();
+	client.refreshHandler = async () => {
+		const refreshed = await refreshWithPlatform(refreshToken);
+		await saveTokens({
+			provider: "gscdump",
+			refresh_token: refreshToken,
+			...refreshed
+		});
+		return refreshed;
+	};
+	client.setCredentials({
+		access_token: tokens.access_token,
+		expiry_date: tokens.expiry_date
+	});
+	await client.getAccessToken();
+	return client;
 }
 async function resolveAuth(opts = {}) {
 	const sa = await resolveServiceAccount({ path: opts.serviceAccount });

package/dist/commands/auth.mjs

@@ -3,7 +3,7 @@ import { clearAuthentication, getCloudAccount, parseAuthMode, parseAuthenticatio
 import { authCommandMeta } from "../command-meta.mjs";
 import { loadConfig, saveConfig } from "../config.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, noSubcommandSelected } from "../utils.mjs";
-import { authenticate, clearTokens, formatAuthProvenance, getAuth, getAuthCredentials, loadServiceAccount, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
+import { clearTokens, formatAuthProvenance, getAuth, loadServiceAccount, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
 import { missingRequiredScopes } from "../auth-scopes.mjs";
 import { clearBingCredentials, getBingClient, inspectBingCredentials } from "../bing-auth.mjs";
 import { runSmokeTest } from "./init.mjs";
@@ -64,7 +64,7 @@ async function resolveLiveAuthState() {
 	else if (tokens?.access_token) liveToken = tokens.access_token;
 	const tokenInfo = liveToken ? await fetchTokenInfo(liveToken) : null;
 	const scopes = tokenInfo?.scope ? tokenInfo.scope.split(/\s+/).filter(Boolean) : [];
-	const missing = missingRequiredScopes(scopes);
+	const missing = missingRequiredScopes(scopes, byok ? void 0 : tokens?.provider);
 	return {
 		byok,
 		tokens,
@@ -250,15 +250,11 @@ const refreshCommand = defineCommand({
 			logger.error("No saved refresh token. Run `gscdump auth login`.");
 			process.exit(1);
 		}
-		const credentials = await getAuthCredentials(false).catch((e) => {
-			logger.error(`Cannot resolve credentials: ${e.message}`);
-			process.exit(1);
-		});
 		await saveTokens({
 			...tokens,
 			expiry_date: 1
 		});
-		if ((await authenticate(credentials, false).catch((e) => {
+		if ((await getAuth({ interactive: false }).catch((e) => {
 			logger.error(`Refresh failed: ${e.message}`);
 			process.exit(1);
 		})).credentials?.access_token) logger.success("Token refreshed");

package/dist/commands/doctor.mjs

@@ -141,7 +141,7 @@ async function checkAuth(envKeys) {
 		detail: info.email
 	});
 	const scopes = info.scope ? info.scope.split(/\s+/) : [];
-	const missing = missingRequiredScopes(scopes);
+	const missing = missingRequiredScopes(scopes, byok ? void 0 : tokens?.provider);
 	if (missing.length > 0) checks.push({
 		name: "auth.scopes",
 		status: "warn",

package/dist/commands/init.mjs

@@ -2,7 +2,7 @@ import { initCommandMeta } from "../command-meta.mjs";
 import { defaultDataDir, loadConfig, saveConfig } from "../config.mjs";
 import { applyCliEnvironment } from "../environment.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
-import { authenticate, getAuthCredentials, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
+import { authenticate, getAuth, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";
@@ -117,15 +117,12 @@ const initCommand = defineCommand({
 		console.log("  \x1B[90mGoogle Search Console data extraction CLI\x1B[0m");
 		console.log();
 		const dataDir = args["no-store"] ? void 0 : await promptDataDir(config.dataDir);
-		const credentials = await getAuthCredentials(true);
 		await saveConfig({
 			...config,
-			...dataDir ? { dataDir } : {},
-			clientId: credentials.clientId,
-			clientSecret: credentials.clientSecret
+			...dataDir ? { dataDir } : {}
 		});
-		await smokeTest(await authenticate(credentials, true));
-		await maybeWriteEnvFile(credentials.clientId, credentials.clientSecret);
+		await smokeTest(await getAuth({ interactive: true }));
+		if (config.clientId && config.clientSecret) await maybeWriteEnvFile(config.clientId, config.clientSecret);
 		console.log();
 		logger.success("Setup complete! Run gscdump to get started.");
 	}

package/dist/config.mjs

@@ -27,8 +27,13 @@ const configSchema = z.strictObject({
 	]).optional(),
 	serviceAccountPath: z.string().optional()
 });
+const RETIRED_KEYS = ["mode", "cloudUrl"];
+function dropRetiredKeys(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+	return Object.fromEntries(Object.entries(value).filter(([key]) => !RETIRED_KEYS.includes(key)));
+}
 function parseConfig(value) {
-	const parsed = configSchema.safeParse(value);
+	const parsed = configSchema.safeParse(dropRetiredKeys(value));
 	if (!parsed.success) {
 		const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`);
 		throw new Error(`Invalid config at ${getConfigPath()}. ${issues.join("; ")}`);

package/dist/error-handler.mjs

@@ -75,7 +75,7 @@ var LocalStoreUnsupportedError = class extends Error {
 	tool;
 	mode;
 	constructor(tool, mode) {
-		super(`analysis "${tool}" has no implementation for the ${mode} source`);
+		super(mode === "live" ? `The live API cannot run analysis "${tool}". Run gscdump sync, then retry without --live.` : `Local data cannot run analysis "${tool}".`);
 		this.name = "LocalStoreUnsupportedError";
 		this.tool = tool;
 		this.mode = mode;

package/dist/hosted-auth.mjs

@@ -0,0 +1,55 @@
+import { z } from "zod";
+const ORIGIN = "https://gscdump.com";
+const accessSchema = z.object({
+	accessToken: z.string().min(1),
+	expiresAt: z.number().int().positive()
+});
+const pollSchema = z.discriminatedUnion("status", [z.object({ status: z.literal("pending") }), z.object({
+	status: z.literal("complete"),
+	tokens: accessSchema.extend({ refreshToken: z.string().min(1) })
+})]);
+async function requestJson(request, route, init = {}) {
+	const response = await request(`${ORIGIN}/api/cli/auth/${route}`, {
+		...init,
+		redirect: "error",
+		signal: AbortSignal.timeout(3e4)
+	});
+	if (!response.ok) {
+		if (response.status === 429 || response.status >= 500) throw new Error("Google authorization is temporarily unavailable. Try again later.");
+		throw new Error("Google authorization failed. Run `gscdump auth login --mode local --force` to reconnect.");
+	}
+	return response.json();
+}
+async function refreshWithPlatform(refreshToken, request = fetch) {
+	const result = accessSchema.parse(await requestJson(request, "refresh", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ refreshToken })
+	}));
+	return {
+		access_token: result.accessToken,
+		expiry_date: result.expiresAt
+	};
+}
+async function loginWithPlatform(deps) {
+	const init = z.object({
+		code: z.string().regex(/^[A-F0-9]{20}$/),
+		expiresIn: z.number().int().positive().max(600)
+	}).parse(await requestJson(deps.request, "init", { method: "POST" }));
+	const deadline = deps.now() + init.expiresIn * 1e3;
+	const redirect = `/app/cli/auth?code=${init.code}`;
+	const route = deps.force ? `/auth/google?reauth=1&redirect=${encodeURIComponent(redirect)}` : redirect;
+	await deps.authorize(`${ORIGIN}${route}`);
+	while (deps.now() < deadline) {
+		const result = pollSchema.parse(await requestJson(deps.request, `poll?code=${init.code}`));
+		if (result.status === "complete") return {
+			provider: "gscdump",
+			access_token: result.tokens.accessToken,
+			refresh_token: result.tokens.refreshToken,
+			expiry_date: result.tokens.expiresAt
+		};
+		await deps.wait(2e3);
+	}
+	throw new Error("Authorization expired. Run `gscdump auth login` to try again.");
+}
+export { loginWithPlatform, refreshWithPlatform };

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "3.6.3";
+var version = "3.8.0";
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "3.6.3",
+  "version": "3.8.0",
   "description": "CLI for Google Search Console and Bing with hosted or local authentication, data exports, and an MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -44,15 +44,15 @@
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "@duckdb/node-api": "1.5.5-r.4",
-    "@gscdump/analysis": "^3.6.3",
-    "@gscdump/engine": "^3.6.3",
-    "@gscdump/engine-gsc-api": "^3.6.3",
-    "@gscdump/sdk": "^3.6.3",
+    "@gscdump/analysis": "^3.8.0",
+    "@gscdump/engine": "^3.8.0",
+    "@gscdump/engine-gsc-api": "^3.8.0",
+    "@gscdump/sdk": "^3.8.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.0.2",
-    "gscdump": "^3.6.3",
+    "gscdump": "^3.8.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.2",
     "sitemapd": "^0.2.2",

package/skills/gscdump/SKILL.md

@@ -122,10 +122,13 @@ If local Google credentials are missing, use one of these paths:
 | Service account | CI with a service-account key that has Site access | `export GOOGLE_APPLICATION_CREDENTIALS=/abs/path/key.json` |
 | Interactive OAuth | A person is present | `gscdump init --mode local` |
 
-`init` needs a Google Cloud OAuth client of type Desktop app. Ask the user to
-run it; do not guess client credentials. Use `gscdump auth login --mode local --no-browser`
-when a browser cannot open.
-Run `gscdump auth login --mode local` to save local mode after configuring credentials.
+Default local login opens gscdump.com for free Google login and token refresh.
+Data queries call Google directly. No Google Cloud project or hosted activation is required.
+Use `gscdump auth login --mode local --no-browser` when a browser runs on another host.
+The default grant is read-only Search Console access.
+For Google write operations, use your own OAuth client with the required scopes.
+Set `GSC_CLIENT_ID` and `GSC_CLIENT_SECRET` to use a Desktop app OAuth client.
+Cloud mode requires hosted access. Pro is free during beta, then paid after launch.
 
 `--profile <name>` or `GSCDUMP_PROFILE` isolates the selected mode and Google, Bing, and cloud credentials.