gscdump 1.3.2 → 1.4.1

package/dist/api/batch.d.mts

@@ -0,0 +1,12 @@
+/**
+ * Batch runner with optional concurrency, inter-call delay, and progress.
+ * Used by batchRequestIndexing / batchInspectUrls. Defaults to sequential
+ * (concurrency = 1) because the underlying APIs rate-limit aggressively;
+ * callers that know their quota headroom can opt into parallelism.
+ */
+declare function runSequentialBatch<I, R>(items: I[], operation: (item: I, index: number) => Promise<R>, options?: {
+  delayMs?: number;
+  concurrency?: number;
+  onProgress?: (result: R, index: number, total: number) => void;
+}): Promise<R[]>;
+export { runSequentialBatch };

package/dist/api/batch.mjs

@@ -0,0 +1,29 @@
+async function runSequentialBatch(items, operation, options = {}) {
+	const { delayMs = 0, concurrency = 1, onProgress } = options;
+	const results = Array.from({ length: items.length });
+	let completed = 0;
+	if (concurrency <= 1) {
+		for (let i = 0; i < items.length; i++) {
+			const result = await operation(items[i], i);
+			results[i] = result;
+			onProgress?.(result, i, items.length);
+			if (i < items.length - 1 && delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+		}
+		return results;
+	}
+	const cursor = { i: 0 };
+	const worker = async () => {
+		while (true) {
+			const i = cursor.i++;
+			if (i >= items.length) return;
+			const result = await operation(items[i], i);
+			results[i] = result;
+			completed++;
+			onProgress?.(result, completed - 1, items.length);
+			if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+	return results;
+}
+export { runSequentialBatch };

package/dist/api/indexing.d.mts

@@ -0,0 +1,37 @@
+import { UrlNotification } from "../core/types.mjs";
+import { GoogleSearchConsoleClient } from "../core/client.mjs";
+type IndexingNotificationType = 'URL_UPDATED' | 'URL_DELETED';
+interface IndexingResult {
+  url: string;
+  type: IndexingNotificationType;
+  notifyTime?: string;
+}
+interface IndexingMetadata {
+  url: string;
+  latestUpdate?: UrlNotification;
+  latestRemove?: UrlNotification;
+}
+/**
+ * Request Google to index or remove a URL via the Indexing API.
+ * Note: The Indexing API officially supports only job posting and livestream content,
+ * but can be used for any URL with varying success.
+ */
+declare function requestIndexing(client: GoogleSearchConsoleClient, url: string, options?: {
+  type?: IndexingNotificationType;
+}): Promise<IndexingResult>;
+/**
+ * Get the indexing notification metadata for a URL.
+ * Returns when Google was last notified about updates/removals.
+ */
+declare function getIndexingMetadata(client: GoogleSearchConsoleClient, url: string): Promise<IndexingMetadata>;
+/**
+ * Batch request indexing for multiple URLs with rate limiting.
+ * Returns results for each URL.
+ */
+declare function batchRequestIndexing(client: GoogleSearchConsoleClient, urls: string[], options?: {
+  type?: IndexingNotificationType;
+  delayMs?: number;
+  concurrency?: number;
+  onProgress?: (result: IndexingResult, index: number, total: number) => void;
+}): Promise<IndexingResult[]>;
+export { IndexingMetadata, IndexingNotificationType, IndexingResult, batchRequestIndexing, getIndexingMetadata, requestIndexing };

package/dist/api/indexing.mjs

@@ -0,0 +1,25 @@
+import { runSequentialBatch } from "./batch.mjs";
+async function requestIndexing(client, url, options = {}) {
+	const { type = "URL_UPDATED" } = options;
+	return client.indexing.publish(url, type).then((r) => ({
+		url,
+		type,
+		notifyTime: r.urlNotificationMetadata?.latestUpdate?.notifyTime || void 0
+	}));
+}
+async function getIndexingMetadata(client, url) {
+	return client.indexing.getMetadata(url).then((r) => ({
+		url,
+		latestUpdate: r.latestUpdate || void 0,
+		latestRemove: r.latestRemove || void 0
+	}));
+}
+async function batchRequestIndexing(client, urls, options = {}) {
+	const { type = "URL_UPDATED", delayMs = 100, concurrency, onProgress } = options;
+	return runSequentialBatch(urls, (url) => requestIndexing(client, url, { type }), {
+		delayMs,
+		concurrency,
+		onProgress
+	});
+}
+export { batchRequestIndexing, getIndexingMetadata, requestIndexing };

package/dist/api/inspection.d.mts

@@ -0,0 +1,89 @@
+import { UrlInspectionResult } from "../core/types.mjs";
+import { CallOptions, GoogleSearchConsoleClient } from "../core/client.mjs";
+interface InspectUrlResult {
+  url: string;
+  inspection?: UrlInspectionResult;
+  isIndexed: boolean;
+}
+/**
+ * Inspects a URL in Google Search Console to check its indexing status.
+ */
+declare function inspectUrl(client: GoogleSearchConsoleClient, siteUrl: string, inspectionUrl: string): Promise<{
+  inspection: UrlInspectionResult | undefined;
+  isIndexed: boolean;
+}>;
+/**
+ * Batch inspect multiple URLs with rate limiting.
+ * Returns inspection results for each URL.
+ */
+declare function batchInspectUrls(client: GoogleSearchConsoleClient, siteUrl: string, urls: string[], options?: {
+  delayMs?: number;
+  concurrency?: number;
+  onProgress?: (result: InspectUrlResult, index: number, total: number) => void;
+}): Promise<InspectUrlResult[]>;
+interface ParsedIndexingResult {
+  url: string;
+  verdict: string | null;
+  coverageState: string | null;
+  indexingState: string | null;
+  robotsTxtState: string | null;
+  pageFetchState: string | null;
+  lastCrawlTime: string | null;
+  crawlingUserAgent: string | null;
+  userCanonical: string | null;
+  googleCanonical: string | null;
+  sitemaps: string | null;
+  referringUrls: string | null;
+  mobileVerdict: string | null;
+  mobileIssues: string | null;
+  richResultsVerdict: string | null;
+  richResultsItems: string | null;
+  ampVerdict: string | null;
+  ampUrl: string | null;
+  ampIndexingState: string | null;
+  ampIndexStatusVerdict: string | null;
+  ampRobotsTxtState: string | null;
+  ampPageFetchState: string | null;
+  ampLastCrawlTime: string | null;
+  ampIssues: string | null;
+  inspectionResultLink: string | null;
+}
+declare function inspectUrlFlat(client: GoogleSearchConsoleClient, siteUrl: string, inspectionUrl: string, options?: CallOptions): Promise<ParsedIndexingResult>;
+/** Maximum parallel URL Inspection requests started by the settled flat batch helper. */
+declare const MAX_FLAT_INSPECTION_BATCH_CONCURRENCY = 10;
+type InspectUrlFlatSettledResult = {
+  url: string;
+  status: 'fulfilled';
+  value: ParsedIndexingResult;
+} | {
+  url: string;
+  status: 'rejected';
+  reason: unknown;
+};
+interface BatchInspectUrlsFlatSettledOptions extends CallOptions {
+  /** Delay after each request handled by a worker. Defaults to 200ms. */
+  delayMs?: number;
+  /** Number of workers. Defaults to 1 and is capped at {@link MAX_FLAT_INSPECTION_BATCH_CONCURRENCY}. */
+  concurrency?: number;
+  onProgress?: (result: InspectUrlFlatSettledResult, index: number, total: number) => void;
+}
+/**
+ * Inspect URLs into the flat storage shape without failing the whole batch
+ * when one URL fails. Results retain input order and include each URL so
+ * callers can persist successes and classify individual failures safely.
+ */
+declare function batchInspectUrlsFlatSettled(client: GoogleSearchConsoleClient, siteUrl: string, urls: readonly string[], options?: BatchInspectUrlsFlatSettledOptions): Promise<InspectUrlFlatSettledResult[]>;
+type InspectionPriority = 'high' | 'medium' | 'low';
+declare function getNextCheckPriority(result: Pick<ParsedIndexingResult, 'verdict'>): InspectionPriority;
+/** Next-check unix seconds for a given priority. */
+declare function getNextCheckAfter(priority: InspectionPriority): number;
+declare function canUseUrlInspection(permissionLevel: string | null | undefined): boolean;
+type IndexingIneligibleReason = 'missing_indexing_scope' | 'insufficient_gsc_permission';
+interface IndexingEligibility {
+  indexingEligible: boolean;
+  indexingIneligibleReason?: IndexingIneligibleReason;
+  indexingPermissionLevel?: string | null;
+  grantedScopes?: string[];
+}
+declare function getIndexingEligibility(grantedScopes: string | null | undefined, permissionLevel: string | null | undefined): IndexingEligibility;
+export { BatchInspectUrlsFlatSettledOptions, IndexingEligibility, IndexingIneligibleReason, InspectUrlFlatSettledResult, InspectUrlResult, InspectionPriority, MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, ParsedIndexingResult, batchInspectUrls, batchInspectUrlsFlatSettled, canUseUrlInspection, getIndexingEligibility, getNextCheckAfter, getNextCheckPriority, inspectUrl, inspectUrlFlat };

package/dist/api/inspection.mjs

@@ -0,0 +1,128 @@
+import { runSequentialBatch } from "./batch.mjs";
+import { hasIndexingScope } from "../core/scopes.mjs";
+async function inspectUrl(client, siteUrl, inspectionUrl) {
+	const inspection = (await client.inspect(siteUrl, inspectionUrl)).inspectionResult;
+	return {
+		inspection,
+		isIndexed: inspection?.indexStatusResult?.verdict === "PASS"
+	};
+}
+async function batchInspectUrls(client, siteUrl, urls, options = {}) {
+	const { delayMs = 200, concurrency, onProgress } = options;
+	return runSequentialBatch(urls, async (url) => {
+		const { inspection, isIndexed } = await inspectUrl(client, siteUrl, url);
+		return {
+			url,
+			inspection,
+			isIndexed
+		};
+	}, {
+		delayMs,
+		concurrency,
+		onProgress
+	});
+}
+async function inspectUrlFlat(client, siteUrl, inspectionUrl, options) {
+	const inspection = (await client.inspect(siteUrl, inspectionUrl, options)).inspectionResult;
+	const index = inspection?.indexStatusResult;
+	const mobile = inspection?.mobileUsabilityResult;
+	const rich = inspection?.richResultsResult;
+	const amp = inspection?.ampResult;
+	return {
+		url: inspectionUrl,
+		verdict: index?.verdict ?? null,
+		coverageState: index?.coverageState ?? null,
+		indexingState: index?.indexingState ?? null,
+		robotsTxtState: index?.robotsTxtState ?? null,
+		pageFetchState: index?.pageFetchState ?? null,
+		lastCrawlTime: index?.lastCrawlTime ?? null,
+		crawlingUserAgent: index?.crawledAs ?? null,
+		userCanonical: index?.userCanonical ?? null,
+		googleCanonical: index?.googleCanonical ?? null,
+		sitemaps: index?.sitemap?.length ? JSON.stringify(index.sitemap) : null,
+		referringUrls: index?.referringUrls?.length ? JSON.stringify(index.referringUrls) : null,
+		mobileVerdict: mobile?.verdict ?? null,
+		mobileIssues: mobile?.issues?.length ? JSON.stringify(mobile.issues) : null,
+		richResultsVerdict: rich?.verdict ?? null,
+		richResultsItems: rich?.detectedItems?.length ? JSON.stringify(rich.detectedItems) : null,
+		ampVerdict: amp?.verdict ?? null,
+		ampUrl: amp?.ampUrl ?? null,
+		ampIndexingState: amp?.indexingState ?? null,
+		ampIndexStatusVerdict: amp?.ampIndexStatusVerdict ?? null,
+		ampRobotsTxtState: amp?.robotsTxtState ?? null,
+		ampPageFetchState: amp?.pageFetchState ?? null,
+		ampLastCrawlTime: amp?.lastCrawlTime ?? null,
+		ampIssues: amp?.issues?.length ? JSON.stringify(amp.issues) : null,
+		inspectionResultLink: inspection?.inspectionResultLink ?? null
+	};
+}
+const MAX_FLAT_INSPECTION_BATCH_CONCURRENCY = 10;
+async function batchInspectUrlsFlatSettled(client, siteUrl, urls, options = {}) {
+	const requestedConcurrency = Math.trunc(options.concurrency ?? 1);
+	const concurrency = Number.isFinite(requestedConcurrency) ? Math.max(1, Math.min(requestedConcurrency, 10)) : 1;
+	return runSequentialBatch([...urls], async (url) => {
+		try {
+			return {
+				url,
+				status: "fulfilled",
+				value: await inspectUrlFlat(client, siteUrl, url, { signal: options.signal })
+			};
+		} catch (reason) {
+			return {
+				url,
+				status: "rejected",
+				reason
+			};
+		}
+	}, {
+		delayMs: options.delayMs ?? 200,
+		concurrency,
+		onProgress: options.onProgress
+	});
+}
+function getNextCheckPriority(result) {
+	if (!result.verdict || result.verdict === "VERDICT_UNSPECIFIED") return "medium";
+	if (result.verdict === "FAIL" || result.verdict === "PARTIAL" || result.verdict === "NEUTRAL") return "high";
+	if (result.verdict === "PASS") return "low";
+	return "medium";
+}
+function getNextCheckAfter(priority) {
+	const now = Math.floor(Date.now() / 1e3);
+	switch (priority) {
+		case "high": return now + 7 * 86400;
+		case "medium": return now + 14 * 86400;
+		case "low": return now + 30 * 86400;
+	}
+}
+const INSPECTION_ALLOWED_PERMISSIONS = /* @__PURE__ */ new Set([
+	"siteOwner",
+	"siteFullUser",
+	"siteRestrictedUser"
+]);
+function canUseUrlInspection(permissionLevel) {
+	return !!permissionLevel && INSPECTION_ALLOWED_PERMISSIONS.has(permissionLevel);
+}
+function grantedScopeList(scopes) {
+	return scopes?.split(/\s+/).map((s) => s.trim()).filter(Boolean) ?? [];
+}
+function getIndexingEligibility(grantedScopes, permissionLevel) {
+	const scopes = grantedScopeList(grantedScopes);
+	if (!hasIndexingScope(grantedScopes)) return {
+		indexingEligible: false,
+		indexingIneligibleReason: "missing_indexing_scope",
+		indexingPermissionLevel: permissionLevel ?? null,
+		grantedScopes: scopes
+	};
+	if (!canUseUrlInspection(permissionLevel)) return {
+		indexingEligible: false,
+		indexingIneligibleReason: "insufficient_gsc_permission",
+		indexingPermissionLevel: permissionLevel ?? null,
+		grantedScopes: scopes
+	};
+	return {
+		indexingEligible: true,
+		indexingPermissionLevel: permissionLevel ?? null,
+		grantedScopes: scopes
+	};
+}
+export { MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, batchInspectUrls, batchInspectUrlsFlatSettled, canUseUrlInspection, getIndexingEligibility, getNextCheckAfter, getNextCheckPriority, inspectUrl, inspectUrlFlat };

package/dist/api/oauth.d.mts

@@ -0,0 +1,48 @@
+import { Result } from "../core/result.mjs";
+import { GscError } from "../core/errors.mjs";
+interface OAuthTokens {
+  accessToken: string;
+  /** Unix seconds. */
+  expiresAt: number;
+  /** Space-delimited scopes Google granted for this token, when returned. */
+  scope?: string;
+}
+/** Normalized response from Google's access-token introspection endpoint. */
+interface OAuthTokenInfo {
+  issuedTo?: string;
+  audience?: string;
+  authorizedParty?: string;
+  userId?: string;
+  subject?: string;
+  scope?: string;
+  /** Seconds remaining when Google inspected the token. */
+  expiresIn?: number;
+  /** Unix seconds. */
+  expiresAt?: number;
+  email?: string;
+  emailVerified?: boolean;
+  accessType?: string;
+}
+/**
+ * Exchange a refresh token for an access token. Retries transient network
+ * failures; surfaces HTTP failures (invalid_grant, etc.) immediately as
+ * `GscApiError` so callers can mark the refresh token as bad.
+ */
+declare function refreshAccessToken(refreshToken: string, clientId: string, clientSecret: string): Promise<OAuthTokens>;
+/**
+ * Exchange an authorization code (from the OAuth consent redirect) for
+ * access + refresh tokens. Same retry / surface model and `auth-expired` vs
+ * `transport` classification as {@link refreshAccessTokenResult}.
+ */
+declare function exchangeAuthCodeResult(code: string, clientId: string, clientSecret: string, redirectUri: string): Promise<Result<OAuthTokens & {
+  refreshToken?: string;
+}, GscError>>;
+/** Inspect an access token without throwing on expected OAuth failures. */
+declare function introspectAccessTokenResult(accessToken: string): Promise<Result<OAuthTokenInfo, GscError>>;
+/** Throwing convenience wrapper for {@link introspectAccessTokenResult}. */
+declare function introspectAccessToken(accessToken: string): Promise<OAuthTokenInfo>;
+/** Revoke an access or refresh token without throwing on expected OAuth failures. */
+declare function revokeOAuthTokenResult(token: string): Promise<Result<void, GscError>>;
+/** Throwing convenience wrapper for {@link revokeOAuthTokenResult}. */
+declare function revokeOAuthToken(token: string): Promise<void>;
+export { OAuthTokenInfo, OAuthTokens, exchangeAuthCodeResult, introspectAccessToken, introspectAccessTokenResult, refreshAccessToken, revokeOAuthToken, revokeOAuthTokenResult };

package/dist/api/oauth.mjs

@@ -0,0 +1,154 @@
+import { GscApiError, gscErrorToException, parseGoogleError } from "../core/errors.mjs";
+import { err, ok, unwrapResult } from "../core/result.mjs";
+const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const OAUTH_TOKEN_INFO_URL = "https://oauth2.googleapis.com/tokeninfo";
+const OAUTH_REVOKE_URL = "https://oauth2.googleapis.com/revoke";
+const OAUTH_TIMEOUT_MS = 8e3;
+const OAUTH_MAX_ATTEMPTS = 3;
+const OAUTH_BACKOFF_MS = [
+	0,
+	400,
+	1500
+];
+async function refreshAccessTokenResult(refreshToken, clientId, clientSecret) {
+	const result = await postOAuthTokenResult(new URLSearchParams({
+		client_id: clientId,
+		client_secret: clientSecret,
+		refresh_token: refreshToken,
+		grant_type: "refresh_token"
+	}), "refresh");
+	if (!result.ok) return result;
+	return ok({
+		accessToken: result.value.accessToken,
+		expiresAt: result.value.expiresAt,
+		scope: result.value.scope
+	});
+}
+async function refreshAccessToken(refreshToken, clientId, clientSecret) {
+	return unwrapResult(await refreshAccessTokenResult(refreshToken, clientId, clientSecret), oauthErrorToException);
+}
+async function exchangeAuthCodeResult(code, clientId, clientSecret, redirectUri) {
+	const result = await postOAuthTokenResult(new URLSearchParams({
+		client_id: clientId,
+		client_secret: clientSecret,
+		code,
+		redirect_uri: redirectUri,
+		grant_type: "authorization_code"
+	}), "exchange");
+	if (!result.ok) return result;
+	return result;
+}
+async function introspectAccessTokenResult(accessToken) {
+	const response = await requestOAuthResult(`${OAUTH_TOKEN_INFO_URL}?access_token=${encodeURIComponent(accessToken)}`, { method: "GET" }, "introspect");
+	if (!response.ok) return response;
+	const parsed = await readOAuthJsonResult(response.value, "introspect");
+	if (!parsed.ok) return parsed;
+	const data = parsed.value;
+	return ok({
+		issuedTo: optionalString(data.issued_to),
+		audience: optionalString(data.aud),
+		authorizedParty: optionalString(data.azp),
+		userId: optionalString(data.user_id),
+		subject: optionalString(data.sub),
+		scope: optionalString(data.scope),
+		expiresIn: optionalNumber(data.expires_in),
+		expiresAt: optionalNumber(data.exp),
+		email: optionalString(data.email),
+		emailVerified: optionalBoolean(data.email_verified),
+		accessType: optionalString(data.access_type)
+	});
+}
+async function introspectAccessToken(accessToken) {
+	return unwrapResult(await introspectAccessTokenResult(accessToken), oauthErrorToException);
+}
+async function revokeOAuthTokenResult(token) {
+	const response = await requestOAuthResult(OAUTH_REVOKE_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({ token })
+	}, "revoke");
+	return response.ok ? ok(void 0) : response;
+}
+async function revokeOAuthToken(token) {
+	return unwrapResult(await revokeOAuthTokenResult(token), oauthErrorToException);
+}
+function oauthHttpError(op, info) {
+	const message = `Failed to ${op} token: ${info.message}`;
+	const cause = new GscApiError(message, info);
+	return info.reason === "invalid_grant" || info.reason === "invalid_token" || info.code === 400 || info.code === 401 || info.code === 403 ? {
+		kind: "auth-expired",
+		message,
+		cause
+	} : {
+		kind: "transport",
+		message,
+		status: info.code,
+		cause
+	};
+}
+function oauthErrorToException(error) {
+	return error.cause instanceof Error ? error.cause : gscErrorToException(error);
+}
+async function postOAuthTokenResult(body, op) {
+	const response = await requestOAuthResult(OAUTH_TOKEN_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body
+	}, op);
+	if (!response.ok) return response;
+	const parsed = await readOAuthJsonResult(response.value, op);
+	if (!parsed.ok) return parsed;
+	const data = parsed.value;
+	return ok({
+		accessToken: data.access_token,
+		expiresAt: Math.floor(Date.now() / 1e3) + data.expires_in,
+		refreshToken: data.refresh_token,
+		scope: data.scope
+	});
+}
+async function requestOAuthResult(url, init, op) {
+	let lastError;
+	for (let attempt = 0; attempt < OAUTH_MAX_ATTEMPTS; attempt++) {
+		if (OAUTH_BACKOFF_MS[attempt]) await new Promise((r) => setTimeout(r, OAUTH_BACKOFF_MS[attempt]));
+		const res = await fetch(url, {
+			...init,
+			signal: AbortSignal.timeout(OAUTH_TIMEOUT_MS)
+		}).catch((error) => {
+			lastError = error;
+			return null;
+		});
+		if (!res) continue;
+		if (!res.ok) return err(oauthHttpError(op, parseGoogleError(await res.text(), res.status)));
+		return ok(res);
+	}
+	return err({
+		kind: "transport",
+		message: lastError instanceof Error ? lastError.message : `OAuth ${op} failed after ${OAUTH_MAX_ATTEMPTS} attempts`,
+		cause: lastError
+	});
+}
+async function readOAuthJsonResult(response, op) {
+	try {
+		return ok(await response.json());
+	} catch (cause) {
+		return err({
+			kind: "transport",
+			message: `Failed to parse ${op} token response`,
+			status: response.status,
+			cause
+		});
+	}
+}
+function optionalString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function optionalNumber(value) {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+function optionalBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (value === "true") return true;
+	if (value === "false") return false;
+}
+export { exchangeAuthCodeResult, introspectAccessToken, introspectAccessTokenResult, refreshAccessToken, revokeOAuthToken, revokeOAuthTokenResult };

package/dist/api/sites.d.mts

@@ -0,0 +1,45 @@
+import { ApiSite, ApiSitemap, Site } from "../core/types.mjs";
+import { GoogleSearchConsoleClient } from "../core/client.mjs";
+interface FetchSitesWithSitemapsOptions {
+  /** Maximum concurrent sitemap-list requests. Defaults to 4. */
+  concurrency?: number;
+}
+/**
+ * Fetches all sites the authenticated user has access to in Google Search Console.
+ */
+declare function fetchSites(client: GoogleSearchConsoleClient): Promise<ApiSite[]>;
+/**
+ * Fetches all verified sites with their sitemaps from Google Search Console.
+ */
+declare function fetchSitesWithSitemaps(client: GoogleSearchConsoleClient, options?: FetchSitesWithSitemapsOptions): Promise<(Site & {
+  sitemaps: ApiSitemap[];
+})[]>;
+/**
+ * Fetches all sitemaps for a site.
+ */
+declare function fetchSitemaps(client: GoogleSearchConsoleClient, siteUrl: string): Promise<ApiSitemap[]>;
+/**
+ * Fetches a specific sitemap.
+ */
+declare function fetchSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<ApiSitemap>;
+/**
+ * Submits a sitemap to Google Search Console.
+ */
+declare function submitSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
+/**
+ * Deletes a sitemap from Google Search Console.
+ */
+declare function deleteSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
+/**
+ * Add a property to the user's Search Console account.
+ *
+ * Note: this only registers the property in an unverified state. Ownership
+ * must be proven via the Site Verification API (see `verifySite`) before any
+ * data is accessible.
+ */
+declare function addSite(client: GoogleSearchConsoleClient, siteUrl: string): Promise<void>;
+/**
+ * Remove a property from the user's Search Console account.
+ */
+declare function deleteSite(client: GoogleSearchConsoleClient, siteUrl: string): Promise<void>;
+export { FetchSitesWithSitemapsOptions, addSite, deleteSite, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, submitSitemap };

package/dist/api/sites.mjs

@@ -0,0 +1,34 @@
+import { runSequentialBatch } from "./batch.mjs";
+async function fetchSites(client) {
+	return client.sites();
+}
+async function fetchSitesWithSitemaps(client, options = {}) {
+	const sites = (await client.sites()).filter((s) => !!s.siteUrl && s.permissionLevel !== "siteUnverifiedUser");
+	const requestedConcurrency = options.concurrency ?? 4;
+	return runSequentialBatch(sites, async (site) => {
+		const sitemaps = await client.sitemaps.list(site.siteUrl).catch(() => []);
+		return {
+			...site,
+			sitemaps
+		};
+	}, { concurrency: Number.isFinite(requestedConcurrency) ? Math.max(1, Math.floor(requestedConcurrency)) : 4 });
+}
+async function fetchSitemaps(client, siteUrl) {
+	return client.sitemaps.list(siteUrl);
+}
+async function fetchSitemap(client, siteUrl, feedpath) {
+	return client.sitemaps.get(siteUrl, feedpath);
+}
+async function submitSitemap(client, siteUrl, feedpath) {
+	return client.sitemaps.submit(siteUrl, feedpath);
+}
+async function deleteSitemap(client, siteUrl, feedpath) {
+	return client.sitemaps.delete(siteUrl, feedpath);
+}
+async function addSite(client, siteUrl) {
+	return client.sites.add(siteUrl);
+}
+async function deleteSite(client, siteUrl) {
+	return client.sites.delete(siteUrl);
+}
+export { addSite, deleteSite, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, submitSitemap };

package/dist/api/verification.d.mts

@@ -0,0 +1,43 @@
+import { GoogleSearchConsoleClient, VerificationMethod, VerificationSite, VerificationToken, VerificationWebResource } from "../core/client.mjs";
+/**
+ * Resolve a Search Console site URL (`https://example.com/` or
+ * `sc-domain:example.com`) to the Site Verification API's site shape.
+ */
+declare function siteUrlToVerificationSite(siteUrl: string): VerificationSite;
+/** Resolve a Search Console property and method to Google's verification target. */
+declare function resolveVerificationTarget(siteUrl: string, method?: VerificationMethod): {
+  site: VerificationSite;
+  method: VerificationMethod;
+};
+/**
+ * Methods valid for a given site shape. SITE properties can use META/FILE/
+ * ANALYTICS/TAG_MANAGER; INET_DOMAIN must use DNS_TXT or DNS_CNAME.
+ */
+declare function verificationMethodsFor(site: VerificationSite): VerificationMethod[];
+/**
+ * Get the verification token Google expects to find on the site or DNS.
+ */
+declare function getVerificationToken(client: GoogleSearchConsoleClient, siteUrl: string, method: VerificationMethod): Promise<VerificationToken & {
+  site: VerificationSite;
+}>;
+/**
+ * Trigger Google to validate the placed token. Caller is responsible for
+ * having placed the token (HTML tag / file / DNS record) before calling.
+ */
+declare function verifySite(client: GoogleSearchConsoleClient, siteUrl: string, method: VerificationMethod): Promise<VerificationWebResource>;
+/**
+ * List all verified WebResources for the authed user.
+ */
+declare function listVerifiedSites(client: GoogleSearchConsoleClient): Promise<VerificationWebResource[]>;
+/**
+ * Fetch a single verified WebResource by id.
+ */
+declare function getVerifiedSite(client: GoogleSearchConsoleClient, id: string): Promise<VerificationWebResource>;
+/**
+ * Drop the calling user's verified ownership of a WebResource. The placed
+ * verification token (meta tag / file / DNS record) MUST be removed first,
+ * otherwise Google may auto-re-verify and the call will fail. Other owners
+ * on the property are unaffected.
+ */
+declare function unverifySite(client: GoogleSearchConsoleClient, id: string): Promise<void>;
+export { getVerificationToken, getVerifiedSite, listVerifiedSites, resolveVerificationTarget, siteUrlToVerificationSite, unverifySite, verificationMethodsFor, verifySite };