gscdump 0.17.5 → 0.18.0

package/dist/contracts.d.mts

@@ -16,7 +16,14 @@ interface TenantCtx {
   userId: string;
   siteId?: string;
 }
-type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'searchAppearance';
+type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'hour' | 'searchAppearance';
+type GscDataState = 'final' | 'all' | 'hourly_all';
+interface GscSearchAnalyticsMetadata {
+  /** First date (YYYY-MM-DD, PT) still being collected. Populated when dataState=`all` and grouped by `date`. */
+  first_incomplete_date?: string;
+  /** First hour (YYYY-MM-DDThh:mm:ss±hh:mm, PT) still being collected. Populated when dataState=`hourly_all` and grouped by `hour`. */
+  first_incomplete_hour?: string;
+}
 type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
 interface GscSearchAnalyticsFilter {
   dimension: GscSearchAnalyticsDimension;
@@ -28,6 +35,8 @@ interface GscSearchAnalyticsFilterGroup {
   filters: GscSearchAnalyticsFilter[];
 }
 type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+type GscAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
+type GscResponseAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
 interface GscSearchAnalyticsRequest {
   startDate: string;
   endDate: string;
@@ -35,7 +44,10 @@ interface GscSearchAnalyticsRequest {
   dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
   rowLimit?: number;
   startRow?: number;
-  searchType?: GscSearchType;
+  /** GSC search corpus. Maps to wire field `type` (the API still accepts the deprecated `searchType` alias). */
+  type?: GscSearchType;
+  dataState?: GscDataState;
+  aggregationType?: GscAggregationType;
 }
 interface GscSearchAnalyticsRow {
   keys: string[];
@@ -46,6 +58,7 @@ interface GscSearchAnalyticsRow {
 }
 interface GscSearchAnalyticsResponse {
   rows?: GscSearchAnalyticsRow[];
-  responseAggregationType?: string;
+  responseAggregationType?: GscResponseAggregationType;
+  metadata?: GscSearchAnalyticsMetadata;
 }
-export { ColumnDef, ColumnType, GscSearchAnalyticsDimension, GscSearchAnalyticsFilter, GscSearchAnalyticsFilterGroup, GscSearchAnalyticsFilterOperator, GscSearchAnalyticsRequest, GscSearchAnalyticsResponse, GscSearchAnalyticsRow, GscSearchType, Row, TableName, TableSchema, TenantCtx };
+export { ColumnDef, ColumnType, GscAggregationType, GscDataState, GscResponseAggregationType, GscSearchAnalyticsDimension, GscSearchAnalyticsFilter, GscSearchAnalyticsFilterGroup, GscSearchAnalyticsFilterOperator, GscSearchAnalyticsMetadata, GscSearchAnalyticsRequest, GscSearchAnalyticsResponse, GscSearchAnalyticsRow, GscSearchType, Row, TableName, TableSchema, TenantCtx };

package/dist/index.d.mts

@@ -12,7 +12,14 @@ declare function runSequentialBatch<I, R>(items: I[], operation: (item: I, index
   concurrency?: number;
   onProgress?: (result: R, index: number, total: number) => void;
 }): Promise<R[]>;
-type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'searchAppearance';
+type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'hour' | 'searchAppearance';
+type GscDataState = 'final' | 'all' | 'hourly_all';
+interface GscSearchAnalyticsMetadata {
+  /** First date (YYYY-MM-DD, PT) still being collected. Populated when dataState=`all` and grouped by `date`. */
+  first_incomplete_date?: string;
+  /** First hour (YYYY-MM-DDThh:mm:ss±hh:mm, PT) still being collected. Populated when dataState=`hourly_all` and grouped by `hour`. */
+  first_incomplete_hour?: string;
+}
 type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
 interface GscSearchAnalyticsFilter {
   dimension: GscSearchAnalyticsDimension;
@@ -24,6 +31,8 @@ interface GscSearchAnalyticsFilterGroup {
   filters: GscSearchAnalyticsFilter[];
 }
 type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+type GscAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
+type GscResponseAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
 interface GscSearchAnalyticsRequest {
   startDate: string;
   endDate: string;
@@ -31,7 +40,10 @@ interface GscSearchAnalyticsRequest {
   dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
   rowLimit?: number;
   startRow?: number;
-  searchType?: GscSearchType;
+  /** GSC search corpus. Maps to wire field `type` (the API still accepts the deprecated `searchType` alias). */
+  type?: GscSearchType;
+  dataState?: GscDataState;
+  aggregationType?: GscAggregationType;
 }
 declare const _default: {
   name: string;
@@ -64,6 +76,8 @@ interface DimensionValueMap {
   device: Device;
   searchAppearance: string;
   date: string;
+  /** Hour bucket — ISO-8601 with PT offset, e.g. `2025-07-14T13:00:00-07:00`. Use with `dataState: 'hourly_all'`. */
+  hour: string;
 }
 type Dimension = keyof DimensionValueMap;
 interface QueryParamValueMap {
@@ -113,6 +127,12 @@ interface BuilderState {
   };
   rowLimit?: number;
   startRow?: number;
+  /** GSC `dataState`. `'hourly_all'` is required when grouping by `hour`. */
+  dataState?: GscDataState;
+  /** GSC `aggregationType`. `'byNewsShowcasePanel'` requires `type=discover|googleNews` with NEWS_SHOWCASE searchAppearance. */
+  aggregationType?: GscAggregationType;
+  /** GSC search corpus. Wins over any `searchType` filter when both are set. */
+  searchType?: SearchType;
 }
 type SelectableColumn = Column<Dimension> | MetricColumn<Metric>;
 type OrderableColumn = MetricColumn<Metric> | Column<'date'>;
@@ -127,6 +147,10 @@ interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
   orderBy: (col: OrderableColumn, dir: 'asc' | 'desc') => GSCQueryBuilder<D, C>;
   limit: (n: number) => GSCQueryBuilder<D, C>;
   offset: (n: number) => GSCQueryBuilder<D, C>;
+  dataState: (state: GscDataState) => GSCQueryBuilder<D, C>;
+  aggregationType: (type: GscAggregationType) => GSCQueryBuilder<D, C>;
+  /** GSC search corpus (`type` on the wire). Equivalent to filtering by `searchType`. */
+  type: (t: GscSearchType) => GSCQueryBuilder<D, C>;
   toBody: () => GscSearchAnalyticsRequest;
   getState: () => BuilderState;
 }
@@ -239,16 +263,23 @@ declare function createFetch(auth: Auth, options?: FetchOptions): $Fetch;
 interface CallOptions {
   signal?: AbortSignal;
 }
+/** Generator return value for `client.query` — exposes API response metadata plus the resolved aggregation type Google actually used (may differ from the requested `aggregationType: 'auto'`). */
+interface QueryReturn {
+  metadata?: GscSearchAnalyticsMetadata;
+  /** Aggregation type Google actually used. Useful when requesting `auto` to know if rows were aggregated `byPage` vs `byProperty`. */
+  responseAggregationType?: GscResponseAggregationType;
+}
 interface GoogleSearchConsoleClient {
   /** Query search analytics with builder, returns async generator yielding typed row batches */
-  query: <D extends Dimension[], C>(siteUrl: string, builder: GSCQueryBuilder<D, C>, opts?: CallOptions) => AsyncGenerator<GSCRow<D, C>[]>;
+  query: <D extends Dimension[], C>(siteUrl: string, builder: GSCQueryBuilder<D, C>, opts?: CallOptions) => AsyncGenerator<GSCRow<D, C>[], QueryReturn>;
   /**
    * List all sites. Also exposes write ops as `client.sites.add(siteUrl)` and
    * `client.sites.delete(siteUrl)`. Calling `client.sites()` is equivalent to
    * `client.sites.list()`.
    */
   sites: ((opts?: CallOptions) => Promise<ApiSite[]>) & {
-    list: (opts?: CallOptions) => Promise<ApiSite[]>; /** Add a property in unverified state. Caller must verify ownership separately. */
+    list: (opts?: CallOptions) => Promise<ApiSite[]>; /** Retrieve a single property (with permission level). 404 if not in the user's account. */
+    get: (siteUrl: string, opts?: CallOptions) => Promise<ApiSite>; /** Add a property in unverified state. Caller must verify ownership separately. */
     add: (siteUrl: string, opts?: CallOptions) => Promise<void>; /** Remove a property from the user's account. */
     delete: (siteUrl: string, opts?: CallOptions) => Promise<void>;
   };
@@ -266,11 +297,15 @@ interface GoogleSearchConsoleClient {
     get: (id: string, opts?: CallOptions) => Promise<VerificationWebResource>;
     delete: (id: string, opts?: CallOptions) => Promise<void>;
   };
-  /** Inspect a URL */
-  inspect: (siteUrl: string, url: string, opts?: CallOptions) => Promise<InspectUrlIndexResponse>;
+  /** Inspect a URL. `languageCode` is a BCP-47 tag for translating result strings; omit to let Google pick. */
+  inspect: (siteUrl: string, url: string, opts?: CallOptions & {
+    languageCode?: string;
+  }) => Promise<InspectUrlIndexResponse>;
   /** Sitemap operations */
   sitemaps: {
-    list: (siteUrl: string, opts?: CallOptions) => Promise<ApiSitemap[]>;
+    /** List sitemaps. Pass `sitemapIndex` to list children of a sitemap-index file. */list: (siteUrl: string, opts?: CallOptions & {
+      sitemapIndex?: string;
+    }) => Promise<ApiSitemap[]>;
     get: (siteUrl: string, feedpath: string, opts?: CallOptions) => Promise<ApiSitemap>;
     submit: (siteUrl: string, feedpath: string, opts?: CallOptions) => Promise<void>;
     delete: (siteUrl: string, feedpath: string, opts?: CallOptions) => Promise<void>;
@@ -363,6 +398,14 @@ interface ParsedIndexingResult {
   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): Promise<ParsedIndexingResult>;
@@ -406,7 +449,7 @@ declare function fetchSites(client: GoogleSearchConsoleClient): Promise<ApiSite[
  * Fetches all verified sites with their sitemaps from Google Search Console.
  */
 declare function fetchSitesWithSitemaps(client: GoogleSearchConsoleClient): Promise<(Site & {
-  sitemaps: RequiredNonNullable<ApiSitemap>[];
+  sitemaps: ApiSitemap[];
 })[]>;
 /**
  * Fetches all sitemaps for a site.
@@ -690,8 +733,8 @@ declare function findBestGscProperty<T extends GscPropertyCandidate>(targetDomai
 };
 declare function findExactGscProperty<T extends GscPropertyCandidate>(propertyUrl: string, properties: readonly T[]): T | null;
 declare function formatGscPropertyCandidates(candidates: ReadonlyArray<GscPropertyCandidate | null | undefined>): string;
-declare const INDEXING_DAILY_LIMIT = 2000;
-declare const INDEXING_EFFECTIVE_LIMIT = 1800;
+declare const URL_INSPECTION_DAILY_LIMIT = 2000;
+declare const URL_INSPECTION_EFFECTIVE_LIMIT = 1800;
 declare function hasGscReadScope(scopes: string | null | undefined): boolean;
 declare function hasGscWriteScope(scopes: string | null | undefined): boolean;
 declare function hasIndexingScope(scopes: string | null | undefined): boolean;
@@ -850,4 +893,4 @@ interface FetchSitemapUrlsOptions extends DiscoverSitemapOptions {
  * `<loc>https://...</loc>` shape but doesn't validate the schema.
  */
 declare function fetchSitemapUrls(sitemapUrl: string, options?: FetchSitemapUrlsOptions): Promise<string[]>;
-export { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BackfillProgress, CallOptions, DAYS_PER_RANGE, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, FetchSitemapUrlsOptions, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscApiError, GscApiErrorInfo, GscError, GscErrorKind, GscPropertyCandidate, GscdumpApiOptions, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingEligibility, IndexingIneligibleReason, IndexingIssueType, IndexingMetadata, IndexingNextAction, IndexingNotificationType, IndexingResult, IndexingStatus, InspectUrlIndexResponse, InspectUrlResult, InspectionPriority, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, MS_PER_DAY, MobileUsabilityResult, OAuthTokens, ParsedGscSiteUrl, ParsedIndexingResult, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, Period, PropertyNextAction, PropertyStatus, PublishUrlNotificationResponse, QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, SitemapNextAction, SitemapStatus, UrlInspectionResult, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, exchangeAuthCode, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatErrorForCli, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, grantedScopeList, groupIntoRanges, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, verificationMethodsFor, verifySite };
+export { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BackfillProgress, CallOptions, DAYS_PER_RANGE, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, FetchSitemapUrlsOptions, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscApiError, GscApiErrorInfo, GscError, GscErrorKind, GscPropertyCandidate, GscdumpApiOptions, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingEligibility, IndexingIneligibleReason, IndexingIssueType, IndexingMetadata, IndexingNextAction, IndexingNotificationType, IndexingResult, IndexingStatus, InspectUrlIndexResponse, InspectUrlResult, InspectionPriority, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, MS_PER_DAY, MobileUsabilityResult, OAuthTokens, ParsedGscSiteUrl, ParsedIndexingResult, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, Period, PropertyNextAction, PropertyStatus, PublishUrlNotificationResponse, QueryReturn, QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, SitemapNextAction, SitemapStatus, URL_INSPECTION_DAILY_LIMIT, URL_INSPECTION_EFFECTIVE_LIMIT, UrlInspectionResult, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, exchangeAuthCode, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatErrorForCli, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, grantedScopeList, groupIntoRanges, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, verificationMethodsFor, verifySite };

package/dist/index.mjs

@@ -50,17 +50,26 @@ async function batchRequestIndexing(client, urls, options = {}) {
 		onProgress
 	});
 }
+const WEBMASTERS_READ = "https://www.googleapis.com/auth/webmasters.readonly";
+const WEBMASTERS_WRITE = "https://www.googleapis.com/auth/webmasters";
+const INDEXING = "https://www.googleapis.com/auth/indexing";
+function tokenize(scopes) {
+	if (!scopes) return [];
+	return scopes.split(/\s+/).filter(Boolean);
+}
+function hasScope(scopes, scope) {
+	const tokens = tokenize(scopes);
+	const suffix = scope.replace("https://www.googleapis.com/auth/", "");
+	return tokens.includes(scope) || tokens.includes(suffix);
+}
 function hasGscReadScope(scopes) {
-	if (!scopes) return false;
-	return scopes.includes("webmasters.readonly") || scopes.includes("webmasters");
+	return hasScope(scopes, WEBMASTERS_READ) || hasScope(scopes, WEBMASTERS_WRITE);
 }
 function hasGscWriteScope(scopes) {
-	if (!scopes) return false;
-	return scopes.includes("webmasters") && !scopes.includes("webmasters.readonly");
+	return hasScope(scopes, WEBMASTERS_WRITE);
 }
 function hasIndexingScope(scopes) {
-	if (!scopes) return false;
-	return scopes.includes("googleapis.com/auth/indexing");
+	return hasScope(scopes, INDEXING);
 }
 async function inspectUrl(client, siteUrl, inspectionUrl) {
 	const inspection = (await client.inspect(siteUrl, inspectionUrl)).inspectionResult;
@@ -89,6 +98,7 @@ async function inspectUrlFlat(client, siteUrl, inspectionUrl) {
 	const index = inspection?.indexStatusResult;
 	const mobile = inspection?.mobileUsabilityResult;
 	const rich = inspection?.richResultsResult;
+	const amp = inspection?.ampResult;
 	return {
 		url: inspectionUrl,
 		verdict: index?.verdict ?? null,
@@ -106,6 +116,14 @@ async function inspectUrlFlat(client, siteUrl, inspectionUrl) {
 		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
 	};
 }
@@ -123,7 +141,11 @@ function getNextCheckAfter(priority) {
 		case "low": return now + 30 * 86400;
 	}
 }
-const INSPECTION_ALLOWED_PERMISSIONS = new Set(["siteOwner", "siteFullUser"]);
+const INSPECTION_ALLOWED_PERMISSIONS = new Set([
+	"siteOwner",
+	"siteFullUser",
+	"siteRestrictedUser"
+]);
 function canUseUrlInspection(permissionLevel) {
 	return !!permissionLevel && INSPECTION_ALLOWED_PERMISSIONS.has(permissionLevel);
 }
@@ -216,6 +238,44 @@ function extractRetryAfter(error) {
 	}
 }
 const QUOTA_MESSAGE_RE = /quota|rate\s*limit/i;
+const QUOTA_REASONS = new Set([
+	"dailyLimitExceeded",
+	"dailyLimitExceededUnreg",
+	"rateLimitExceeded",
+	"rateLimitExceededUnreg",
+	"userRateLimitExceeded",
+	"userRateLimitExceededUnreg",
+	"quotaExceeded",
+	"concurrentLimitExceeded",
+	"variableTermLimitExceeded",
+	"variableTermExpiredDailyExceeded",
+	"servingLimitExceeded",
+	"responseTooLarge",
+	"limitExceeded",
+	"batchSizeTooLarge",
+	"RATE_LIMIT_EXCEEDED",
+	"RESOURCE_EXHAUSTED"
+]);
+function extractReason(cause) {
+	const data = pickField(cause, [["data"]], (v) => true);
+	if (data) {
+		const errorInfo = pickField(data, [["error", "details"]], (v) => Array.isArray(v));
+		if (errorInfo) {
+			const reason = errorInfo.find((d) => typeof d["@type"] === "string" && d["@type"].includes("ErrorInfo"))?.reason;
+			if (typeof reason === "string") return reason;
+		}
+		const directErrors = pickField(data, [["error", "errors"]], (v) => Array.isArray(v));
+		if (directErrors) {
+			const reason = directErrors[0]?.reason;
+			if (typeof reason === "string") return reason;
+		}
+	}
+}
+function isQuotaCondition(cause, message) {
+	const reason = extractReason(cause);
+	if (reason && QUOTA_REASONS.has(reason)) return true;
+	return QUOTA_MESSAGE_RE.test(message);
+}
 function classifyError(cause) {
 	const status = extractStatus(cause);
 	const message = extractMessage(cause);
@@ -231,7 +291,7 @@ function classifyError(cause) {
 		cause
 	};
 	if (status === 403) {
-		if (QUOTA_MESSAGE_RE.test(message)) return {
+		if (isQuotaCondition(cause, message)) return {
 			kind: "rate-limited",
 			message,
 			retryAfter: extractRetryAfter(cause),
@@ -243,12 +303,12 @@ function classifyError(cause) {
 			cause
 		};
 	}
-	if (status === 404) return {
+	if (status === 404 || status === 410) return {
 		kind: "not-found",
 		message,
 		cause
 	};
-	if (status === 400 || status === 422) return {
+	if (status === 400 || status === 402 || status === 409 || status === 413 || status === 422) return {
 		kind: "validation",
 		message,
 		cause
@@ -412,7 +472,7 @@ async function fetchSites(client) {
 async function fetchSitesWithSitemaps(client) {
 	const sites = (await client.sites()).filter((s) => !!s.siteUrl && s.permissionLevel !== "siteUnverifiedUser");
 	return Promise.all(sites.map(async (site) => {
-		const sitemaps = site.permissionLevel === "siteOwner" ? await client.sitemaps.list(site.siteUrl) : [];
+		const sitemaps = await client.sitemaps.list(site.siteUrl).catch(() => []);
 		return {
 			...site,
 			sitemaps
@@ -2152,9 +2212,9 @@ function extractSpecialFilters(filter) {
 	else otherFilters.push(f);
 	if (filter._nestedGroups) for (const nested of filter._nestedGroups) {
 		const extracted = extractSpecialFilters(nested);
-		if (extracted.startDate) startDate = extracted.startDate;
-		if (extracted.endDate) endDate = extracted.endDate;
-		if (extracted.searchType) searchType = extracted.searchType;
+		if (!startDate && extracted.startDate) startDate = extracted.startDate;
+		if (!endDate && extracted.endDate) endDate = extracted.endDate;
+		if (!searchType && extracted.searchType) searchType = extracted.searchType;
 		if (extracted.dimensionFilter) cleanedNestedGroups.push(extracted.dimensionFilter);
 	}
 	const dimensionFilter = otherFilters.length > 0 || cleanedNestedGroups.length > 0 ? {
@@ -2177,11 +2237,40 @@ function resolveToBody(state) {
 		startDate,
 		endDate
 	};
-	if (searchType) body.searchType = searchType;
-	if (state.rowLimit) body.rowLimit = state.rowLimit;
-	if (state.startRow) body.startRow = state.startRow;
+	const resolvedType = state.searchType ?? searchType;
+	if (resolvedType) body.type = resolvedType;
+	if (state.rowLimit !== void 0) {
+		if (!Number.isInteger(state.rowLimit) || state.rowLimit < 1) throw new Error(`rowLimit must be a positive integer, got ${state.rowLimit}`);
+		body.rowLimit = state.rowLimit;
+	}
+	if (state.startRow !== void 0) {
+		if (!Number.isInteger(state.startRow) || state.startRow < 0) throw new Error(`startRow must be a non-negative integer, got ${state.startRow}`);
+		if (state.startRow > 0) body.startRow = state.startRow;
+	}
+	const hasHour = state.dimensions?.includes("hour");
+	if (hasHour && state.dataState !== "hourly_all") throw new Error("hour dimension requires dataState: \"hourly_all\"");
+	if (state.dataState === "hourly_all" && !hasHour) throw new Error("dataState: \"hourly_all\" requires grouping by hour dimension");
+	if (state.dataState) body.dataState = state.dataState;
 	const filterGroups = resolveFilter(dimensionFilter);
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
+	if (state.aggregationType) {
+		const groupsByPage = (body.dimensions ?? []).includes("page");
+		const apiLeafFilters = filterGroups.flatMap((g) => g.filters ?? []);
+		const filtersByPage = apiLeafFilters.some((f) => f.dimension === "page");
+		if (state.aggregationType === "byProperty") {
+			if (body.type === "discover" || body.type === "googleNews") throw new Error("aggregationType: \"byProperty\" is not supported for type \"discover\" or \"googleNews\"");
+			if (groupsByPage || filtersByPage) throw new Error("aggregationType: \"byProperty\" is not allowed when grouping or filtering by page");
+		}
+		if (state.aggregationType === "byNewsShowcasePanel") {
+			if (body.type !== "discover" && body.type !== "googleNews") throw new Error("aggregationType: \"byNewsShowcasePanel\" requires type \"discover\" or \"googleNews\"");
+			if (groupsByPage || filtersByPage) throw new Error("aggregationType: \"byNewsShowcasePanel\" is not allowed when grouping or filtering by page");
+			const saFilters = apiLeafFilters.filter((f) => f.dimension === "searchAppearance");
+			const hasNewsShowcase = saFilters.some((f) => f.operator === "equals" && f.expression === "NEWS_SHOWCASE");
+			const hasOther = saFilters.some((f) => !(f.operator === "equals" && f.expression === "NEWS_SHOWCASE"));
+			if (!hasNewsShowcase || hasOther) throw new Error("aggregationType: \"byNewsShowcasePanel\" requires a searchAppearance equals \"NEWS_SHOWCASE\" filter and no other searchAppearance filter");
+		}
+		body.aggregationType = state.aggregationType;
+	}
 	return body;
 }
 function isApiFilter(f) {
@@ -2232,6 +2321,8 @@ function gscdumpApi(options) {
 		retryDelay: 1e3,
 		retryStatusCodes: [
 			408,
+			409,
+			425,
 			429,
 			500,
 			502,
@@ -2263,10 +2354,16 @@ function gscdumpApi(options) {
 		async *query(siteId, builder, opts) {
 			const state = builder.getState();
 			const body = resolveToBody(state);
-			const rowLimit = body.rowLimit || 25e3;
+			const totalCap = body.rowLimit;
+			const pageSize = Math.min(totalCap ?? 25e3, 25e3);
 			let startRow = body.startRow || 0;
+			let yielded = 0;
+			let metadata;
 			while (true) {
 				opts?.signal?.throwIfAborted();
+				const remaining = totalCap ? totalCap - yielded : pageSize;
+				if (remaining <= 0) break;
+				const rowLimit = Math.min(pageSize, remaining);
 				const response = await fetch(`/api/sites/${encodeURIComponent(siteId)}/query`, {
 					method: "POST",
 					body: {
@@ -2276,6 +2373,7 @@ function gscdumpApi(options) {
 					},
 					signal: opts?.signal
 				});
+				if (response.metadata) metadata = response.metadata;
 				const rows = response.rows.map((row) => {
 					const result = rowWithMetricDefaults(row);
 					state.dimensions.forEach((dim) => {
@@ -2284,9 +2382,11 @@ function gscdumpApi(options) {
 					return result;
 				});
 				yield rows;
+				yielded += rows.length;
 				if (!response.meta.hasMore || rows.length < rowLimit) break;
 				startRow += rows.length;
 			}
+			return { metadata };
 		},
 		sites: (() => {
 			const list = async (opts) => {
@@ -2300,6 +2400,7 @@ function gscdumpApi(options) {
 			};
 			return Object.assign(list, {
 				list,
+				get: unsupported("get"),
 				add: unsupported("add"),
 				delete: unsupported("delete")
 			});
@@ -2352,6 +2453,15 @@ function gscdumpApi(options) {
 const GSC_API = "https://searchconsole.googleapis.com";
 const INDEXING_API = "https://indexing.googleapis.com";
 const SITE_VERIFICATION_API = "https://www.googleapis.com/siteVerification/v1";
+function encodeSiteUrl(siteUrl) {
+	if (siteUrl.startsWith("sc-domain:")) return `sc-domain:${encodeURIComponent(siteUrl.slice(10))}`;
+	return encodeURIComponent(siteUrl);
+}
+function assertValidSiteUrl(siteUrl) {
+	if (siteUrl.startsWith("sc-domain:") && siteUrl.length > 10) return;
+	if (/^https?:\/\/.+/.test(siteUrl)) return;
+	throw new Error(`Invalid siteUrl: expected "https?://…" or "sc-domain:…", got "${siteUrl}"`);
+}
 function createAuth(options) {
 	let credentials = { refresh_token: options.refreshToken };
 	return {
@@ -2393,10 +2503,21 @@ function createFetch(auth, options) {
 	return ofetch.create({
 		...options,
 		retry: 3,
-		retryDelay: 1e3,
+		retryDelay: (ctx) => {
+			const status = ctx.response?.status;
+			if (status === 429 || status === 503) {
+				const header = ctx.response?.headers.get("retry-after");
+				if (header) {
+					const secs = Number.parseInt(header, 10);
+					if (Number.isFinite(secs)) return secs * 1e3;
+					const when = Date.parse(header);
+					if (Number.isFinite(when)) return Math.max(0, when - Date.now());
+				}
+			}
+			return 1e3;
+		},
 		retryStatusCodes: [
 			408,
-			409,
 			425,
 			429,
 			500,
@@ -2439,7 +2560,7 @@ function googleSearchConsole(auth, options = {}) {
 		}
 		fetch = createFetch(authState, fetchOptions);
 	}
-	const rawQuery = (siteUrl, body, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`, {
+	const rawQuery = (siteUrl, body, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/searchAnalytics/query`, {
 		method: "POST",
 		body,
 		signal: opts?.signal
@@ -2448,25 +2569,40 @@ function googleSearchConsole(auth, options = {}) {
 		async *query(siteUrl, builder, opts) {
 			const state = builder.getState();
 			const body = resolveToBody(state);
-			const rowLimit = body.rowLimit || 25e3;
+			const totalCap = body.rowLimit;
+			const pageSize = Math.min(totalCap ?? 25e3, 25e3);
 			let startRow = body.startRow || 0;
+			let yielded = 0;
+			let metadata;
+			let responseAggregationType;
 			while (true) {
 				opts?.signal?.throwIfAborted();
-				const rows = ((await rawQuery(siteUrl, {
+				const remaining = totalCap ? totalCap - yielded : pageSize;
+				if (remaining <= 0) break;
+				const rowLimit = Math.min(pageSize, remaining);
+				const response = await rawQuery(siteUrl, {
 					...body,
 					startRow,
 					rowLimit
-				}, opts)).rows || []).map((row) => {
+				}, opts);
+				if (response.metadata) metadata = response.metadata;
+				if (response.responseAggregationType) responseAggregationType = response.responseAggregationType;
+				const rows = (response.rows || []).map((row) => {
 					const result = rowWithMetricDefaults(row);
 					state.dimensions.forEach((dim, i) => {
 						result[dim] = row.keys?.[i];
 					});
 					return result;
 				});
+				if (rows.length === 0) break;
 				yield rows;
-				if (rows.length < rowLimit) break;
+				yielded += rows.length;
 				startRow += rows.length;
 			}
+			return {
+				metadata,
+				responseAggregationType
+			};
 		},
 		sites: (() => {
 			const list = async (opts) => {
@@ -2474,11 +2610,15 @@ function googleSearchConsole(auth, options = {}) {
 			};
 			return Object.assign(list, {
 				list,
-				add: (siteUrl, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}`, {
-					method: "PUT",
-					signal: opts?.signal
-				}),
-				delete: (siteUrl, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}`, {
+				get: (siteUrl, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}`, { signal: opts?.signal }),
+				add: (siteUrl, opts) => {
+					assertValidSiteUrl(siteUrl);
+					return fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}`, {
+						method: "PUT",
+						signal: opts?.signal
+					});
+				},
+				delete: (siteUrl, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}`, {
 					method: "DELETE",
 					signal: opts?.signal
 				})
@@ -2507,7 +2647,11 @@ function googleSearchConsole(auth, options = {}) {
 		},
 		inspect: (siteUrl, url, opts) => fetch(`${GSC_API}/v1/urlInspection/index:inspect`, {
 			method: "POST",
-			body: {
+			body: opts?.languageCode ? {
+				inspectionUrl: url,
+				siteUrl,
+				languageCode: opts.languageCode
+			} : {
 				inspectionUrl: url,
 				siteUrl
 			},
@@ -2515,14 +2659,17 @@ function googleSearchConsole(auth, options = {}) {
 		}),
 		sitemaps: {
 			list: async (siteUrl, opts) => {
-				return (await fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps`, { signal: opts?.signal })).sitemap || [];
+				return (await fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/sitemaps`, {
+					signal: opts?.signal,
+					query: opts?.sitemapIndex ? { sitemapIndex: opts.sitemapIndex } : void 0
+				})).sitemap || [];
 			},
-			get: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, { signal: opts?.signal }),
-			submit: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, {
+			get: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, { signal: opts?.signal }),
+			submit: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, {
 				method: "PUT",
 				signal: opts?.signal
 			}),
-			delete: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, {
+			delete: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, {
 				method: "DELETE",
 				signal: opts?.signal
 			})
@@ -2698,8 +2845,8 @@ function findExactGscProperty(propertyUrl, properties) {
 function formatGscPropertyCandidates(candidates) {
 	return candidates.filter((c) => !!c).map((property) => `${property.siteUrl} (${property.permissionLevel})`).join(", ");
 }
-const INDEXING_DAILY_LIMIT = 2e3;
-const INDEXING_EFFECTIVE_LIMIT = 1800;
+const URL_INSPECTION_DAILY_LIMIT = 2e3;
+const URL_INSPECTION_EFFECTIVE_LIMIT = 1800;
 const GSCDUMP_ONBOARDING_CONTRACT_VERSION = "2026-05-11";
 const GSCDUMP_REQUIRED_ANALYTICS_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
 const GSCDUMP_OPTIONAL_INDEXING_SCOPE = "https://www.googleapis.com/auth/indexing";
@@ -2888,4 +3035,4 @@ async function fetchSitemapUrls(sitemapUrl, options = {}) {
 	await visit(sitemapUrl, 0);
 	return out;
 }
-export { DAYS_PER_RANGE, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, GscApiError, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, MS_PER_DAY, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, exchangeAuthCode, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatErrorForCli, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, grantedScopeList, groupIntoRanges, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, verificationMethodsFor, verifySite };
+export { DAYS_PER_RANGE, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, GscApiError, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, MS_PER_DAY, URL_INSPECTION_DAILY_LIMIT, URL_INSPECTION_EFFECTIVE_LIMIT, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, exchangeAuthCode, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatErrorForCli, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, grantedScopeList, groupIntoRanges, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, verificationMethodsFor, verifySite };

package/dist/query/index.d.mts

@@ -1,6 +1,7 @@
 import _dayjs, { Dayjs } from "dayjs";
 type TableName = 'pages' | 'keywords' | 'countries' | 'devices' | 'page_keywords' | 'search_appearance';
-type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'searchAppearance';
+type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'hour' | 'searchAppearance';
+type GscDataState = 'final' | 'all' | 'hourly_all';
 type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
 interface GscSearchAnalyticsFilter {
   dimension: GscSearchAnalyticsDimension;
@@ -12,6 +13,7 @@ interface GscSearchAnalyticsFilterGroup {
   filters: GscSearchAnalyticsFilter[];
 }
 type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+type GscAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
 interface GscSearchAnalyticsRequest {
   startDate: string;
   endDate: string;
@@ -19,7 +21,10 @@ interface GscSearchAnalyticsRequest {
   dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
   rowLimit?: number;
   startRow?: number;
-  searchType?: GscSearchType;
+  /** GSC search corpus. Maps to wire field `type` (the API still accepts the deprecated `searchType` alias). */
+  type?: GscSearchType;
+  dataState?: GscDataState;
+  aggregationType?: GscAggregationType;
 }
 declare const _default: {
   name: string;
@@ -52,6 +57,8 @@ interface DimensionValueMap {
   device: Device;
   searchAppearance: string;
   date: string;
+  /** Hour bucket — ISO-8601 with PT offset, e.g. `2025-07-14T13:00:00-07:00`. Use with `dataState: 'hourly_all'`. */
+  hour: string;
 }
 type Dimension = keyof DimensionValueMap;
 interface QueryParamValueMap {
@@ -110,6 +117,12 @@ interface BuilderState {
   };
   rowLimit?: number;
   startRow?: number;
+  /** GSC `dataState`. `'hourly_all'` is required when grouping by `hour`. */
+  dataState?: GscDataState;
+  /** GSC `aggregationType`. `'byNewsShowcasePanel'` requires `type=discover|googleNews` with NEWS_SHOWCASE searchAppearance. */
+  aggregationType?: GscAggregationType;
+  /** GSC search corpus. Wins over any `searchType` filter when both are set. */
+  searchType?: SearchType;
 }
 interface JsonInternalFilter {
   dimension: string;
@@ -136,6 +149,10 @@ interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
   orderBy: (col: OrderableColumn, dir: 'asc' | 'desc') => GSCQueryBuilder<D, C>;
   limit: (n: number) => GSCQueryBuilder<D, C>;
   offset: (n: number) => GSCQueryBuilder<D, C>;
+  dataState: (state: GscDataState) => GSCQueryBuilder<D, C>;
+  aggregationType: (type: GscAggregationType) => GSCQueryBuilder<D, C>;
+  /** GSC search corpus (`type` on the wire). Equivalent to filtering by `searchType`. */
+  type: (t: GscSearchType) => GSCQueryBuilder<D, C>;
   toBody: () => GscSearchAnalyticsRequest;
   getState: () => BuilderState;
 }
@@ -147,6 +164,7 @@ declare const device: Column<"device">;
 declare const country: Column<"country">;
 declare const searchAppearance: Column<"searchAppearance">;
 declare const date: Column<"date">;
+declare const hour: Column<"hour">;
 declare const clicks: MetricColumn<"clicks">;
 declare const impressions: MetricColumn<"impressions">;
 declare const ctr: MetricColumn<"ctr">;
@@ -164,15 +182,15 @@ declare function and<F extends Filter<any>[]>(...filters: F): Filter<MergeConstr
 declare function or<F extends Filter<any>[]>(...filters: F): Filter<object>;
 declare function not<F extends Filter<any>>(filter: F): Filter<object>;
 declare function gte<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
-declare function gte<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function gte(column: Column<'date'>, value: string): Filter<object>;
 declare function gt<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
-declare function gt<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function gt(column: Column<'date'>, value: string): Filter<object>;
 declare function lte<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
-declare function lte<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function lte(column: Column<'date'>, value: string): Filter<object>;
 declare function lt<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
-declare function lt<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function lt(column: Column<'date'>, value: string): Filter<object>;
 declare function between<M extends Metric>(column: MetricColumn<M>, start: number, end: number): Filter<object>;
-declare function between<D extends Dimension>(column: Column<D>, start: DimensionValueMap[D], end: DimensionValueMap[D]): Filter<object>;
+declare function between(column: Column<'date'>, start: string, end: string): Filter<object>;
 declare function topLevel(column: Column<'page'>): Filter<object>;
 type LogicalDataset = TableName;
 type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
@@ -258,4 +276,4 @@ declare function currentPstDate(): string;
 declare function dayjsPst(): Dayjs;
 declare function today(): string;
 declare function daysAgo(n: number): string;
-export { type BuilderState, type Column, type ComparisonFilter, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type FilterInput, type GSCQueryBuilder, type GSCResult, type GSCRow, type InternalFilter, type JsonFilter, type JsonInternalFilter, type LogicalComparisonPlan, type LogicalDataset, type LogicalDimensionFilter, type LogicalMetricFilter, type LogicalQueryPlan, type Metric, type MetricColumn, type PlannerCapabilities, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalPlan, clicks, contains, country, ctr, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, gsc, gt, gte, impressions, inArray, isJsonFilter, like, lt, lte, ne, normalizeBuilderState, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };
+export { type BuilderState, type Column, type ComparisonFilter, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type FilterInput, type GSCQueryBuilder, type GSCResult, type GSCRow, type InternalFilter, type JsonFilter, type JsonInternalFilter, type LogicalComparisonPlan, type LogicalDataset, type LogicalDimensionFilter, type LogicalMetricFilter, type LogicalQueryPlan, type Metric, type MetricColumn, type PlannerCapabilities, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalPlan, clicks, contains, country, ctr, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, gsc, gt, gte, hour, impressions, inArray, isJsonFilter, like, lt, lte, ne, normalizeBuilderState, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };

package/dist/query/index.mjs

@@ -1640,7 +1640,9 @@ function normalizeBuilderState(state) {
 		filter: normalizeFilter(s.filter),
 		orderBy: s.orderBy,
 		rowLimit: s.rowLimit,
-		startRow: s.startRow
+		startRow: s.startRow,
+		dataState: s.dataState,
+		aggregationType: s.aggregationType
 	};
 }
 function extractSpecialFilters(filter) {
@@ -1674,9 +1676,9 @@ function extractSpecialFilters(filter) {
 	else otherFilters.push(f);
 	if (filter._nestedGroups) for (const nested of filter._nestedGroups) {
 		const extracted = extractSpecialFilters(nested);
-		if (extracted.startDate) startDate = extracted.startDate;
-		if (extracted.endDate) endDate = extracted.endDate;
-		if (extracted.searchType) searchType = extracted.searchType;
+		if (!startDate && extracted.startDate) startDate = extracted.startDate;
+		if (!endDate && extracted.endDate) endDate = extracted.endDate;
+		if (!searchType && extracted.searchType) searchType = extracted.searchType;
 		if (extracted.dimensionFilter) cleanedNestedGroups.push(extracted.dimensionFilter);
 	}
 	const dimensionFilter = otherFilters.length > 0 || cleanedNestedGroups.length > 0 ? {
@@ -1714,6 +1716,7 @@ function extractSpecialOperatorFilters(input) {
 }
 function extractSearchType(state) {
 	if (!state) return void 0;
+	if (state.searchType && KNOWN_SEARCH_TYPES.has(state.searchType)) return state.searchType;
 	const filter = state.filter;
 	if (!filter || typeof filter !== "object") return void 0;
 	const raw = filter.searchType;
@@ -1728,11 +1731,40 @@ function resolveToBody(state) {
 		startDate,
 		endDate
 	};
-	if (searchType) body.searchType = searchType;
-	if (state.rowLimit) body.rowLimit = state.rowLimit;
-	if (state.startRow) body.startRow = state.startRow;
+	const resolvedType = state.searchType ?? searchType;
+	if (resolvedType) body.type = resolvedType;
+	if (state.rowLimit !== void 0) {
+		if (!Number.isInteger(state.rowLimit) || state.rowLimit < 1) throw new Error(`rowLimit must be a positive integer, got ${state.rowLimit}`);
+		body.rowLimit = state.rowLimit;
+	}
+	if (state.startRow !== void 0) {
+		if (!Number.isInteger(state.startRow) || state.startRow < 0) throw new Error(`startRow must be a non-negative integer, got ${state.startRow}`);
+		if (state.startRow > 0) body.startRow = state.startRow;
+	}
+	const hasHour = state.dimensions?.includes("hour");
+	if (hasHour && state.dataState !== "hourly_all") throw new Error("hour dimension requires dataState: \"hourly_all\"");
+	if (state.dataState === "hourly_all" && !hasHour) throw new Error("dataState: \"hourly_all\" requires grouping by hour dimension");
+	if (state.dataState) body.dataState = state.dataState;
 	const filterGroups = resolveFilter(dimensionFilter);
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
+	if (state.aggregationType) {
+		const groupsByPage = (body.dimensions ?? []).includes("page");
+		const apiLeafFilters = filterGroups.flatMap((g) => g.filters ?? []);
+		const filtersByPage = apiLeafFilters.some((f) => f.dimension === "page");
+		if (state.aggregationType === "byProperty") {
+			if (body.type === "discover" || body.type === "googleNews") throw new Error("aggregationType: \"byProperty\" is not supported for type \"discover\" or \"googleNews\"");
+			if (groupsByPage || filtersByPage) throw new Error("aggregationType: \"byProperty\" is not allowed when grouping or filtering by page");
+		}
+		if (state.aggregationType === "byNewsShowcasePanel") {
+			if (body.type !== "discover" && body.type !== "googleNews") throw new Error("aggregationType: \"byNewsShowcasePanel\" requires type \"discover\" or \"googleNews\"");
+			if (groupsByPage || filtersByPage) throw new Error("aggregationType: \"byNewsShowcasePanel\" is not allowed when grouping or filtering by page");
+			const saFilters = apiLeafFilters.filter((f) => f.dimension === "searchAppearance");
+			const hasNewsShowcase = saFilters.some((f) => f.operator === "equals" && f.expression === "NEWS_SHOWCASE");
+			const hasOther = saFilters.some((f) => !(f.operator === "equals" && f.expression === "NEWS_SHOWCASE"));
+			if (!hasNewsShowcase || hasOther) throw new Error("aggregationType: \"byNewsShowcasePanel\" requires a searchAppearance equals \"NEWS_SHOWCASE\" filter and no other searchAppearance filter");
+		}
+		body.aggregationType = state.aggregationType;
+	}
 	return body;
 }
 function isApiFilter(f) {
@@ -1817,6 +1849,24 @@ function createBuilder(state) {
 				startRow: n
 			});
 		},
+		dataState(s) {
+			return createBuilder({
+				...state,
+				dataState: s
+			});
+		},
+		aggregationType(t) {
+			return createBuilder({
+				...state,
+				aggregationType: t
+			});
+		},
+		type(t) {
+			return createBuilder({
+				...state,
+				searchType: t
+			});
+		},
 		toBody() {
 			return resolveToBody(state);
 		},
@@ -1842,6 +1892,7 @@ const device = createColumn("device");
 const country = createColumn("country");
 const searchAppearance = createColumn("searchAppearance");
 const date = createColumn("date");
+const hour = createColumn("hour");
 const clicks = createMetricColumn("clicks");
 const impressions = createMetricColumn("impressions");
 const ctr = createMetricColumn("ctr");
@@ -1869,6 +1920,7 @@ function ne(column, value) {
 	return leafFilter(column.dimension, "notEquals", String(value));
 }
 function inArray(column, values) {
+	if (values.length === 0) throw new Error(`inArray(${column.dimension}, []) requires at least one value`);
 	return {
 		_constraints: {},
 		_filters: values.map((v) => ({
@@ -1883,7 +1935,9 @@ function contains(column, pattern) {
 	return leafFilter(column.dimension, "contains", pattern);
 }
 function like(column, pattern) {
-	return leafFilter(column.dimension, "contains", pattern.replace(/%/g, ""));
+	if (!/[%_]/.test(pattern)) return leafFilter(column.dimension, "contains", pattern);
+	const regex = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/%/g, ".*").replace(/_/g, ".");
+	return leafFilter(column.dimension, "includingRegex", regex);
 }
 function regex(column, pattern) {
 	return leafFilter(column.dimension, "includingRegex", typeof pattern === "string" ? pattern : pattern.source);
@@ -1907,6 +1961,14 @@ function and(...filters) {
 	};
 }
 function or(...filters) {
+	for (const f of filters) {
+		if (f._groupType === "and" && f._filters.length > 1) throw new Error("or() cannot contain a multi-leaf AND group: GSC filter groups do not nest. Restructure as flat OR or split into multiple queries.");
+		if (f._nestedGroups && f._nestedGroups.length > 0) throw new Error("or() cannot contain nested filter groups: GSC filter groups do not nest.");
+		for (const leaf of f._filters) {
+			if (leaf.dimension === "date") throw new Error("or() cannot contain a date filter: GSC date range is a top-level AND-applied request field, not a filter. Apply the date range outside the or() group.");
+			if (leaf.dimension === "searchType") throw new Error("or() cannot contain a searchType filter: GSC search type is a top-level AND-applied request field. Use .type() outside the or() group.");
+		}
+	}
 	return {
 		_constraints: {},
 		_filters: filters.flatMap((f) => f._filters),
@@ -1914,23 +1976,30 @@ function or(...filters) {
 	};
 }
 function not(filter) {
-	return {
-		_constraints: {},
-		_filters: filter._filters.filter((f) => !DATE_OPERATORS.includes(f.operator)).map((f) => ({
+	const inverted = [];
+	for (const f of filter._filters) {
+		if (DATE_OPERATORS.includes(f.operator)) throw new Error(`not() cannot invert date operator "${f.operator}": GSC has no negated date filter.`);
+		if (!(f.operator in INVERSIONS)) throw new Error(`not() cannot invert operator "${f.operator}".`);
+		inverted.push({
 			...f,
 			operator: invertOperator(f.operator)
-		}))
+		});
+	}
+	return {
+		_constraints: {},
+		_filters: inverted
 	};
 }
+const INVERSIONS = {
+	equals: "notEquals",
+	notEquals: "equals",
+	contains: "notContains",
+	notContains: "contains",
+	includingRegex: "excludingRegex",
+	excludingRegex: "includingRegex"
+};
 function invertOperator(op) {
-	return {
-		equals: "notEquals",
-		notEquals: "equals",
-		contains: "notContains",
-		notContains: "contains",
-		includingRegex: "excludingRegex",
-		excludingRegex: "includingRegex"
-	}[op];
+	return INVERSIONS[op];
 }
 function gte(column, value) {
 	return metricOrDimFilter(column, "metricGte", "gte", String(value));
@@ -2097,4 +2166,4 @@ function today() {
 function daysAgo(n) {
 	return dayjsPst().subtract(n, "day").format("YYYY-MM-DD");
 }
-export { Countries, Devices, SearchTypes, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalPlan, clicks, contains, country, ctr, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, gsc, gt, gte, impressions, inArray, isJsonFilter, like, lt, lte, ne, normalizeBuilderState, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };
+export { Countries, Devices, SearchTypes, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalPlan, clicks, contains, country, ctr, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, gsc, gt, gte, hour, impressions, inArray, isJsonFilter, like, lt, lte, ne, normalizeBuilderState, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };

package/dist/query/plan.d.mts

@@ -1,4 +1,6 @@
 type TableName = 'pages' | 'keywords' | 'countries' | 'devices' | 'page_keywords' | 'search_appearance';
+type GscDataState = 'final' | 'all' | 'hourly_all';
+type GscAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
 declare const _default: {
   name: string;
   'alpha-2': string;
@@ -30,6 +32,8 @@ interface DimensionValueMap {
   device: Device;
   searchAppearance: string;
   date: string;
+  /** Hour bucket — ISO-8601 with PT offset, e.g. `2025-07-14T13:00:00-07:00`. Use with `dataState: 'hourly_all'`. */
+  hour: string;
 }
 type Dimension = keyof DimensionValueMap;
 interface QueryParamValueMap {
@@ -65,6 +69,12 @@ interface BuilderState {
   };
   rowLimit?: number;
   startRow?: number;
+  /** GSC `dataState`. `'hourly_all'` is required when grouping by `hour`. */
+  dataState?: GscDataState;
+  /** GSC `aggregationType`. `'byNewsShowcasePanel'` requires `type=discover|googleNews` with NEWS_SHOWCASE searchAppearance. */
+  aggregationType?: GscAggregationType;
+  /** GSC search corpus. Wins over any `searchType` filter when both are set. */
+  searchType?: SearchType;
 }
 type LogicalDataset = TableName;
 type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';

package/dist/query/plan.mjs

@@ -1627,9 +1627,9 @@ function extractSpecialFilters(filter) {
 	else otherFilters.push(f);
 	if (filter._nestedGroups) for (const nested of filter._nestedGroups) {
 		const extracted = extractSpecialFilters(nested);
-		if (extracted.startDate) startDate = extracted.startDate;
-		if (extracted.endDate) endDate = extracted.endDate;
-		if (extracted.searchType) searchType = extracted.searchType;
+		if (!startDate && extracted.startDate) startDate = extracted.startDate;
+		if (!endDate && extracted.endDate) endDate = extracted.endDate;
+		if (!searchType && extracted.searchType) searchType = extracted.searchType;
 		if (extracted.dimensionFilter) cleanedNestedGroups.push(extracted.dimensionFilter);
 	}
 	const dimensionFilter = otherFilters.length > 0 || cleanedNestedGroups.length > 0 ? {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "0.17.5",
+  "version": "0.18.0",
   "description": "Google Search Console API wrapper with typed query builder, streaming pagination, and SEO analysis functions",
   "author": {
     "name": "Harlan Wilton",
@@ -108,7 +108,7 @@
     "defu": "^6.1.7",
     "ofetch": "^1.5.1",
     "ufo": "^1.6.4",
-    "@gscdump/contracts": "0.17.5"
+    "@gscdump/contracts": "0.18.0"
   },
   "devDependencies": {
     "@googleapis/indexing": "^6.0.1",