@gscdump/cli 3.4.4 → 3.6.0

package/README.md

@@ -4,7 +4,10 @@
 [![npm downloads](https://img.shields.io/npm/dm/@gscdump/cli?color=yellow)](https://npm.chart.dev/@gscdump/cli)
 [![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
 
-> CLI for Google Search Console — sync to a local DuckDB/Parquet store, run typed queries, execute 29 SEO analyzers, and serve an MCP endpoint for AI assistants.
+Query Google Search Console and Bing with hosted or local authentication.
+Sync Google rows to a local Parquet Store, and run SEO Analyzers or Reports.
+The package also provides the MCP server.
+Use Node.js 22.13 or later in the 22 release line, or Node.js 24 or later.
 
 ## Install
 
@@ -17,20 +20,21 @@ npx @gscdump/cli
 ## Quick start
 
 ```bash
-# First-run setup — OAuth with Google
-gscdump init
+# Set up local Google OAuth
+gscdump init --mode local
+gscdump auth login --mode local
 
 # List sites
 gscdump sites
 
-# Sync the last 28 days to a local Parquet store
-gscdump sync --site https://example.com
+# Sync 90 days to the Store
+gscdump sync --site sc-domain:example.com --days 90 --tables pages,queries,page_queries,countries,dates
 
-# Query the store
-gscdump query --site https://example.com --dimensions page,query --limit 50
+# Query the Store
+gscdump query --site sc-domain:example.com --dimensions page,query --limit 50
 
-# Run an analyzer
-gscdump analyze striking-distance --site https://example.com
+# Run an Analyzer
+gscdump analyze striking-distance --site sc-domain:example.com
 
 # Start the MCP server
 gscdump mcp
@@ -40,27 +44,124 @@ gscdump mcp
 
 | Command | Description |
 |---|---|
-| `init` | Full setup (OAuth + dataDir; offers to write a `.env` for portability) |
+| `init` | Full setup (OAuth + dataDir; offers to write a `.env` for later use) |
 | `auth` | Manage authentication (`status`, `login`, `logout`, `refresh`) |
+| `bing` | Connect Bing, list sites, dump datasets, inspect URLs, and check hosted verification |
 | `config` | Manage CLI configuration (`show`, `set`, `unset`, `path`, `validate`) |
 | `doctor` | Health checks: auth, scopes, dataDir writability, API reachability |
 | `sites [--owner-only] [--with-sitemaps]` | List available GSC sites |
-| `sites add <url>` / `sites delete <url> [--yes]` | Register / remove a property in Search Console (add registers in unverified state) |
+| `sites add <url>` / `sites delete <url> [--yes]` | Register or remove a Site in Search Console (add registers in unverified state) |
 | `sites verify-token <url> [--method]` / `sites verify <url> [--method]` | Get a verification token, then trigger ownership verification (META/FILE/DNS_TXT/DNS_CNAME/ANALYTICS/TAG_MANAGER) |
-| `sitemaps` | GSC CRUD, explicit live probes, and hosted canonical reads (`current`, `history`, `membership`, `lastmod`, `export`) |
-| `inspect <url>` / `inspect batch [--concurrency]` | URL inspection (single URL or batch from file/stdin); renders index status, rich results, and AMP |
-| `indexing` | Notify Google about URL changes (`submit`, `remove`, `status`, `batch [--concurrency] [--yes]`); supports `--retries` |
-| `sync` | Sync GSC data to the local Parquet store; `--retry-failed`, `--dry-run` |
-| `query` | Run a search analytics query (local store by default; `--live` hits GSC API). Filters: `--query`, `--page`, `--country`, `--device`, `--search-appearance`, `--type`, `--data-state`, `--aggregation-type`. `--explain` previews the request body; `--output -` writes to stdout. |
-| `dump` | Export from the store to a directory (`--format parquet\|json\|ndjson\|csv`, `--tables`, `--all-sites`) |
-| `analyze <tool>` | Run an SEO analyzer against the store (`--live` for row-based against fresh API) |
+| `sitemaps` | List, submit, or delete Google sitemaps; probe live URLs; read hosted snapshots (`current`, `history`, `membership`, `lastmod`, `export`) |
+| `inspect <url>` / `inspect batch [--concurrency]` | URL inspection (single URL or batch from file/stdin); renders Indexing Evidence, rich results, and AMP |
+| `indexing` | Notify Google about URL changes (`submit`, `remove`, `status`, `batch`, `batch-status`, `quota`); supports `--retries` |
+| `sync` | Sync GSC data to the local Parquet Store; `--retry-failed`, `--dry-run` |
+| `query` | Run a search analytics query (Store by default; `--live` hits GSC API). Filters: `--query`, `--page`, `--country`, `--device`, `--search-appearance`, `--type`, `--data-state`, `--aggregation-type`. `--explain` previews the request body; `--output -` writes to stdout. |
+| `dump` | Export from the Store to a directory (`--format parquet\|json\|ndjson\|csv`, `--tables`, `--all-sites`) |
+| `analyze <tool>` | Run an SEO Analyzer against the Store (`--live` for row-based against fresh API) |
 | `entities` | Snapshot URL inspections and indexing metadata into the local entity store |
 | `store stats` | Show row/byte counts per table and on-disk footprint |
-| `store compact` | Roll daily partitions older than N days into monthly files (`--dry-run`) |
+| `store compact` | Compact older data into weekly, monthly, and quarterly tiers (`--dry-run`) |
 | `store gc` | Delete orphaned objects past the grace window (`--dry-run`) |
 | `store export` | Export the live store to a single `.duckdb` file |
+| `store rm-site` / `store reset` | Delete one Site's data or reset the Store; inspect `--help` before use |
 | `store rollups rebuild` | Rebuild post-sync rollup tables |
+| `report <id>` / `report list` | Run or list Reports; `--explain` previews a plan |
+| `profile` | Create, select, list, or delete credential profiles |
 | `mcp` | Start the MCP server for AI assistants |
+| `skill install [--agent claude\|codex] [--target <dir>]` | Copy the packaged `gscdump` agent skill (SKILL.md) into an agent skill directory |
+| `papercut --command <cmd> --comment <text> --agent <name> [--intent bug\|improvement] --yes` | Report a CLI problem to gscdump.com; anonymous, ten per hour per network address |
+
+## Hosted and local authentication
+
+One authentication mode applies to both Google and Bing.
+Credentials and the saved mode belong to the current `--profile` or `--config-dir`.
+
+```bash
+# Use a user API key from https://gscdump.com/app/settings
+export GSCDUMP_API_KEY=gsd_user_...
+gscdump auth login --mode cloud
+gscdump auth status --json
+
+# Google uses the connection on gscdump.com
+gscdump sites --json
+gscdump query --live --site sc-domain:example.com --dimensions page
+
+# Connect Bing through gscdump.com, then read its data
+gscdump bing sites --json
+gscdump bing login --site s_SITE_ID
+gscdump bing status --site s_SITE_ID --json
+gscdump bing dump --site s_SITE_ID --out ./bing-export --format csv
+
+# Use local credentials for one command
+gscdump bing sites --mode local --json
+
+# Save local mode after successful Google login
+gscdump auth login --mode local
+```
+
+`--mode cloud|local` overrides the mode for one invocation.
+`GSCDUMP_AUTH_MODE` provides the same override.
+A successful login saves the mode for later commands.
+If no mode is saved, `GSCDUMP_API_KEY` selects hosted authentication.
+With neither source, the CLI defaults to local authentication.
+When a saved mode exists, it remains selected unless an explicit override applies.
+`GSCDUMP_API_ROOT` defaults to `https://gscdump.com/api`.
+If you change a saved API root, supply the API key explicitly.
+
+| Operation | Hosted authentication | Local authentication |
+| --- | --- | --- |
+| Google queries, sync, sites, sitemaps, URL inspection | Uses the Google connection through gscdump.com | Calls Google with local credentials |
+| Google Indexing API and Site Verification API | Requires local mode | Supported with the required Google scopes |
+| Bing datasets | Reads synced datasets through the public API | Reads data currently returned by Bing |
+| Bing connection and CNAME verification | Uses `bing login`, `bing status`, and `bing verify` | Verify sites in Bing Webmaster Tools |
+| Hosted sitemap membership and history | Supported | Requires hosted authentication |
+| Store queries and exports | Reads the local Store | Reads the local Store |
+
+Hosted Bing access follows the API's plan and preview access rules.
+`auth logout` removes the saved mode and saved Google and Bing credentials.
+Environment credentials remain active until you unset them.
+
+## Bing
+
+For local Bing access, generate an API key in Bing Webmaster Tools under Settings, API Access.
+See [Microsoft's authentication guide](https://learn.microsoft.com/en-us/bingwebmaster/getting-access).
+
+```bash
+export BING_API_KEY=...
+gscdump bing login --mode local
+gscdump bing sites --json
+gscdump bing dump --site https://example.com/ --format json --out ./bing-export
+gscdump bing dump --all-sites --format ndjson
+gscdump bing inspect https://example.com/page --site https://example.com/ --json
+```
+
+`BING_ACCESS_TOKEN` also accepts an existing Bing OAuth access token.
+Local API keys and OAuth credentials are saved separately from Google credentials.
+`bing logout --mode local` removes only saved Bing credentials.
+
+For local browser OAuth, register a Bing OAuth client with this exact redirect URI:
+`http://127.0.0.1:53683/oauth/bing`.
+
+```bash
+export BING_CLIENT_ID=...
+export BING_CLIENT_SECRET=...
+gscdump bing login --mode local --oauth
+```
+
+Use `--redirect-uri` or `BING_REDIRECT_URI` for another registered loopback URI.
+`--no-browser` prints the authorization URL. Saved OAuth credentials refresh automatically.
+
+`bing dump` exports `traffic`, `pages`, `keywords`, and `crawl` by default.
+Use `--datasets traffic,pages` to select datasets.
+Local mode also supports `--datasets crawl-issues`.
+Files use JSON, NDJSON, or CSV, with one directory per Bing site and a `metadata.json` file.
+
+In hosted mode, exports default to the last 366 days.
+Use `--start YYYY-MM-DD --end YYYY-MM-DD` for a range up to 366 days.
+The CLI follows every returned page and rejects unavailable datasets or a snapshot that changes during export.
+In local mode, date options filter the rows Bing returns. They cannot recover older history.
+Bing Indexing Evidence preserves uncertainty and does not imply an indexed verdict.
 
 ### Filter expressions
 
@@ -81,45 +182,68 @@ gscdump query --live --site sc-domain:example.com \
   --page '~/blog/' --query '~brand' --dimensions page,query
 ```
 
+`--limit` and `--format` override saved `defaultLimit` and `defaultFormat` values.
+Without saved values, queries use 1000 rows and JSON.
+Limits must be positive integers. Formats must be `json` or `csv`.
+
+`--start` and `--end` work independently. An omitted date keeps its default.
+Non-interactive queries default to 31 days ago through three days ago, using UTC dates.
+Dates must use `YYYY-MM-DD`, and `--start` cannot follow `--end`.
+
+```bash
+# Export query rows with a CSV header.
+gscdump query --live --site sc-domain:example.com \
+  --dimensions page,query --format csv --output rows.csv
+```
+
 ### Global flags
 
 - `--no-color` / `NO_COLOR` env: strip ANSI from stdout (stderr keeps colour for interactive use).
 - `--config-dir <path>` / `GSCDUMP_CONFIG_DIR`: override `~/.config/gscdump`.
-- `--profile <name>` / `GSCDUMP_PROFILE`: scope tokens + config to a profile under `~/.config/gscdump/profiles/<name>` (juggle multiple GSC accounts).
-- Most commands accept `--quiet` and `--json` for scripted use; `logger` writes to stderr so `--json` output is safe to pipe.
+- `--profile <name>` / `GSCDUMP_PROFILE`: separate tokens and config to a profile under `~/.config/gscdump/profiles/<name>` (separate Google credentials).
+- Most commands accept `--quiet` and `--json` for scripts. The `query` command uses `--format json` instead.
 
-## Analyzers
+Use `query --profile` for query timings. Use `--profile <name>` to select a credential profile.
+Numeric flags reject fractions, negative counts, and text suffixes.
+Saved config rejects invalid values and unknown keys. If parsing fails, fix the reported file.
 
-`gscdump analyze <tool>` dispatches to `@gscdump/analysis`. 21 tools available:
-
-**Core SEO:** `striking-distance`, `opportunity`, `movers`, `decay`, `zero-click`, `brand`, `cannibalization`
+## Analyzers
 
-**Statistical:** `ctr-anomaly`, `position-volatility`, `bayesian-ctr`, `stl-decompose`, `change-point`, `survival`
+`gscdump analyze <tool>` runs one of 29 Analyzers from `@gscdump/analysis`.
+See the [full list](../../README.md#analyzers) and [Source support](../analysis/README.md#sources).
 
-**Structural:** `long-tail`, `intent-atlas`, `query-migration`, `clustering`, `concentration`, `seasonality`, `trends`, `bipartite-pagerank`
+Each Analyzer accepts `--site`, `--start`, `--end`, `--limit`, and output flags.
+`movers` and `decay` also accept `--prev-start` and `--prev-end`.
+Use `gscdump analyze <tool> --help` for additional options.
 
-Each analyzer accepts `--site`, date range flags, and tool-specific options (see `gscdump analyze <tool> --help`). Pass `--live` to bypass the local store and run against fresh GSC API results.
+The CLI requires local data unless you pass `--live`.
+Pass `--live` to use Google explicitly.
+SQL-only Analyzers require local data.
 
 ## Sync
 
 ```bash
-# Default: sync the last 7 days, skipping dates already marked done
-gscdump sync --site https://example.com
+# Default: three days ending three days ago; skip completed dates
+gscdump sync --site sc-domain:example.com --tables pages,queries,page_queries,countries,dates
 
-# Backfill the full 450-day history
-gscdump sync --site https://example.com --full
+# Backfill from 450 days ago to three days ago
+gscdump sync --site sc-domain:example.com --full --tables pages,queries,page_queries,countries,dates
 
 # Custom range
-gscdump sync --site https://example.com --start 2024-01-01 --end 2024-01-31
+gscdump sync --site sc-domain:example.com --start 2026-08-01 --end 2026-08-31 \
+  --tables pages,queries,page_queries,countries,dates
 
-# Check status — watermarks + pending/inflight/done/failed counts
-gscdump sync --site https://example.com --status
+# Check sync state and watermarks
+gscdump sync --site sc-domain:example.com --status
 
-# Parallel table fetches
-gscdump sync --site https://example.com --concurrency 4
+# Limit concurrent day requests per table
+gscdump sync --site sc-domain:example.com --concurrency 4 \
+  --tables pages,queries,page_queries,countries,dates
 ```
 
-Sync is idempotent. Cross-process locking protects concurrent `sync`/`compact`/`gc` runs. Pagination walks past GSC's 25k-row-per-request cap automatically.
+Sync skips completed dates; `--force` refreshes them.
+Cross-process locks coordinate `sync`, `compact`, and `gc`.
+Pagination follows Google's 25,000-row pages, subject to [Google's data limits](https://developers.google.com/webmaster-tools/v1/how-tos/all-your-data).
 
 ## MCP server
 
@@ -136,7 +260,7 @@ Add to your Claude / VS Code config:
   "mcpServers": {
     "gscdump": {
       "command": "npx",
-      "args": ["@gscdump/cli", "mcp"]
+      "args": ["-y", "@gscdump/cli", "mcp"]
     }
   }
 }
@@ -145,20 +269,28 @@ Add to your Claude / VS Code config:
 Then ask questions like:
 
 - "What pages lost traffic this week?"
-- "Find keywords in striking distance (position 4-20)."
+- "Find queries in striking distance (positions 4 to 20)."
 - "Which queries have cannibalization issues?"
 - "Compare this month vs last month for /blog/ pages."
 
 ## Auth
 
-`gscdump init` walks you through full setup (OAuth + data dir). Credentials are stored locally under `~/.config/gscdump/` (XDG) or equivalent. Use `gscdump auth login` if you only want to refresh OAuth tokens without touching config.
+This section covers local Google credentials. See [shared authentication](#hosted-and-local-authentication) for cloud mode and [Bing](#bing) for Bing credentials.
+`gscdump init --mode local` configures Google OAuth and a Store directory.
+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.
+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:
 
 1. Create a Google Cloud project.
-2. Enable **Search Console API** and **Web Search Indexing API**.
+2. Enable **Search Console API**, **Web Search Indexing API**, and **Site Verification API**.
 3. Create OAuth2 credentials (Desktop app).
-4. Run `gscdump init` (or `gscdump auth login`).
+4. Run `gscdump init --mode local` to configure credentials and a Store directory.
+5. Run `gscdump auth login --mode local` to save local mode.
 
 ### BYOK (Bring Your Own Key)
 
@@ -168,39 +300,70 @@ Skip `init` entirely by setting env vars. Either path works (`GSC_*` preferred,
 # Option A: raw bearer token (e.g., from gcloud or another OAuth flow)
 export GSC_ACCESS_TOKEN=ya29...
 
-# Option B: refresh-token flow (no google-auth-library dep used)
+# Option B: refresh-token flow (OAuth refresh credentials)
 export GSC_CLIENT_ID=...
 export GSC_CLIENT_SECRET=...
 export GSC_REFRESH_TOKEN=...
 ```
 
-When BYOK is detected, `gscdump auth status` reports `byok` as the source and `gscdump auth login` is a no-op.
+`gscdump auth status` shows which credential source is active.
+`auth login --mode local` skips OAuth when it finds BYOK credentials and saves local mode.
 
 ### Service account
 
-For CI / headless usage, point `gscdump` at a service-account JSON key. The service account must be granted access to each property in Search Console (Settings → Users and permissions).
+For CI / headless usage, point `gscdump` at a service-account JSON key. Grant the service account access to each Site in Search Console under Settings → Users and permissions.
 
 ```bash
-gscdump auth login --service-account ./gsc-sa.json   # smoke-test the key
-export GOOGLE_APPLICATION_CREDENTIALS=$(realpath ./gsc-sa.json)
+gscdump auth login --mode local --service-account ./gsc-sa.json   # smoke-test the key
+export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/gsc-sa.json
 gscdump sites
 ```
 
 ### Headless OAuth
 
-When the loopback flow can't open a browser (servers, containers, WSL2 without forwarding), use the device-code flow:
+If you want to open the authorization URL yourself, disable automatic browser opening:
+
+```bash
+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.
+
+If the CLI runs on another host, forward its printed loopback port before opening the URL.
+Keep the login command running on that host.
+For example, if the CLI prints port `45678`, run this command on your browser host:
 
 ```bash
-gscdump auth login --no-browser
-# → opens a verification URL on any device; type the displayed user code
+ssh -N -L 45678:127.0.0.1:45678 user@host
 ```
 
+Replace `user@host` with the CLI host.
+Keep the forwarding command running until login completes.
+Then open the printed authorization URL in your browser.
+For containers or WSL, forward the same port to the environment running the CLI.
+If you cannot forward loopback traffic, use a refresh token or service account.
+
+See Google's [native application OAuth guide](https://developers.google.com/identity/protocols/oauth2/native-app)
+and [device flow scope limits](https://developers.google.com/identity/protocols/oauth2/limited-input-device#allowedscopes).
+
+Indexing notifications apply only to eligible job or livestream pages.
+See [URL inspection and indexing](../../docs/guides/url-indexing.md).
+
 ## Related
 
-- [`gscdump`](../gscdump) — Core library: GSC API client + query builder + analytics pipeline.
-- [`@gscdump/engine`](../engine) — Storage engine the CLI syncs into.
-- [`@gscdump/analysis`](../analysis) — SEO analyzers (row-based + DuckDB-native).
+- [`gscdump`](../gscdump) : Google and Bing clients with a typed query builder.
+- [`@gscdump/engine`](../engine) : Storage engine the CLI syncs into.
+- [`@gscdump/analysis`](../analysis) : SEO Analyzers (row-based + DuckDB-native).
 
 ## License
 
 [MIT](../../LICENSE)
+
+## CLI charts
+
+Human output shares chart styles and metric units across Analyzers, Reports, and Store stats.
+Use `gscdump query --format table` for query charts.
+JSON and CSV keep their existing payloads and defaults.
+See [CLI charts](../../docs/guides/cli-charts.md) for examples and data limits.

package/bin/gscdump.mjs

@@ -1,3 +1,8 @@
 #!/usr/bin/env node
 
-import('../dist/cli.mjs').then(({ runCli }) => runCli())
+import process from 'node:process'
+
+import ('../dist/cli.mjs').then(({ runCli }) => runCli()).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+})

package/dist/analysis-local.mjs

@@ -3,8 +3,8 @@ import { createLocalStore } from "./local-store.mjs";
 import { createCommandContext } from "./context.mjs";
 import { LocalStoreUnsupportedError } from "./error-handler.mjs";
 import process from "node:process";
-import { join } from "node:path";
 import { readdir } from "node:fs/promises";
+import { join } from "node:path";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
 import { createGscApiQuerySource } from "@gscdump/engine-gsc-api";
 import { AnalyzerCapabilityError, runAnalyzerFromSource } from "@gscdump/engine/analyzer";

package/dist/auth-state.mjs

@@ -0,0 +1,112 @@
+import { useCliRuntime } from "./runtime.mjs";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+const apiRootSchema = z.url().transform((value) => value.replace(/\/+$/, "")).refine((value) => {
+	const url = new URL(value);
+	return !url.username && !url.password && !url.search && !url.hash && (url.protocol === "https:" || url.protocol === "http:" && [
+		"localhost",
+		"127.0.0.1",
+		"[::1]"
+	].includes(url.hostname));
+}, "Use HTTPS, or HTTP on loopback, for the API root");
+const stateSchema = z.discriminatedUnion("_tag", [z.object({ _tag: z.literal("Local") }), z.object({
+	_tag: z.literal("Cloud"),
+	apiRoot: apiRootSchema,
+	apiKey: z.string().trim().regex(/^gsd_user_\S+$/)
+})]);
+function parseAuthMode(value) {
+	if (value === void 0 || value === "") return void 0;
+	if (value === "cloud" || value === "local") return value;
+	throw new Error("Authentication mode must be cloud or local.");
+}
+function parseAuthentication(value) {
+	const parsed = stateSchema.safeParse(value);
+	if (!parsed.success) throw new Error("Invalid authentication. Use a gscdump user API key and a trusted API root.");
+	return parsed.data;
+}
+async function saveAuthentication(state) {
+	const parsed = parseAuthentication(state);
+	const configDir = useCliRuntime().configDir;
+	await fs.mkdir(configDir, {
+		recursive: true,
+		mode: 448
+	});
+	const target = path.join(configDir, "authentication.json");
+	const temporary = `${target}.${randomUUID()}.tmp`;
+	try {
+		await fs.writeFile(temporary, JSON.stringify(parsed, null, 2), {
+			mode: 384,
+			flag: "wx"
+		});
+		await fs.rename(temporary, target);
+	} finally {
+		await fs.rm(temporary, { force: true });
+	}
+}
+async function clearAuthentication() {
+	await fs.rm(path.join(useCliRuntime().configDir, "authentication.json"), { force: true });
+}
+async function resolveAuthentication() {
+	const runtime = useCliRuntime();
+	const env = runtime.environment;
+	const mode = runtime.authModeOverride ?? parseAuthMode(env.GSCDUMP_AUTH_MODE);
+	if (mode === "local") return { _tag: "Local" };
+	const body = await fs.readFile(path.join(runtime.configDir, "authentication.json"), "utf8").catch((error) => {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	});
+	const saved = body === null ? null : stateSchema.safeParse(JSON.parse(body));
+	if (saved && !saved.success) throw new Error("Saved authentication is invalid. Run `gscdump auth login --mode cloud` or `--mode local`.");
+	const state = saved?.success ? saved.data : null;
+	if (mode !== "cloud" && state?._tag === "Local") return state;
+	if (env.GSCDUMP_API_KEY) {
+		const parsed = stateSchema.safeParse({
+			_tag: "Cloud",
+			apiKey: env.GSCDUMP_API_KEY,
+			apiRoot: env.GSCDUMP_API_ROOT ?? (state?._tag === "Cloud" ? state.apiRoot : "https://gscdump.com/api")
+		});
+		if (!parsed.success) throw new Error("Invalid hosted authentication. Set GSCDUMP_API_KEY to a gscdump user API key.");
+		return parsed.data;
+	}
+	if (state?._tag === "Cloud") {
+		if (env.GSCDUMP_API_ROOT && env.GSCDUMP_API_ROOT.replace(/\/+$/, "") !== state.apiRoot) throw new Error("The API root changed. Supply GSCDUMP_API_KEY explicitly for the new API root.");
+		return state;
+	}
+	if (mode === "cloud") throw new Error("Hosted credentials are missing. Run `gscdump auth login --mode cloud`.");
+	return { _tag: "Local" };
+}
+const accountSchema = z.object({
+	user: z.object({
+		publicId: z.string(),
+		email: z.string()
+	}),
+	sites: z.array(z.object({
+		siteId: z.string(),
+		siteUrl: z.string()
+	}).passthrough())
+});
+async function cloudRequest(state, route, options = {}) {
+	const response = await fetch(`${state.apiRoot}${route}`, {
+		...options,
+		headers: {
+			"Content-Type": "application/json",
+			"x-api-key": state.apiKey
+		},
+		signal: options.signal ?? AbortSignal.timeout(3e4),
+		redirect: "error"
+	});
+	if (!response.ok) throw Object.assign(/* @__PURE__ */ new Error(`Hosted request failed (${response.status}) for ${route.split("?")[0]}. Check \`gscdump auth status\`.`), {
+		statusCode: response.status,
+		retryAfter: response.headers.get("retry-after"),
+		response
+	});
+	return response.status === 204 ? void 0 : response.json();
+}
+async function getCloudAccount(state) {
+	const result = accountSchema.safeParse(await cloudRequest(state, "/cli/me"));
+	if (!result.success) throw new Error("The hosted API returned invalid account data.");
+	return result.data;
+}
+export { clearAuthentication, cloudRequest, getCloudAccount, parseAuthMode, parseAuthentication, resolveAuthentication, saveAuthentication };