gscdump 0.11.2 → 0.11.4

package/dist/contracts.d.mts

@@ -32,4 +32,49 @@ interface TenantCtx {
   userId: string;
   siteId?: string;
 }
-export { ColumnDef, ColumnType, Row, TableName, TableSchema, TenantCtx };
+/**
+ * Dimensions accepted by the Google Search Console Search Analytics API.
+ *
+ * This intentionally excludes package-only logical dimensions such as
+ * `queryCanonical`; host apps must route those through an engine-backed path.
+ */
+type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'searchAppearance';
+type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+interface GscSearchAnalyticsFilter {
+  dimension: GscSearchAnalyticsDimension;
+  expression: string;
+  operator?: GscSearchAnalyticsFilterOperator;
+}
+interface GscSearchAnalyticsFilterGroup {
+  groupType?: 'and' | 'or';
+  filters: GscSearchAnalyticsFilter[];
+}
+type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+/**
+ * Canonical host-facing Search Analytics request body.
+ *
+ * Google's generated client type also has deprecated/alternate fields. The
+ * gscdump query builder emits `searchType`, so apps should forward that field
+ * unchanged rather than translating it to `type`.
+ */
+interface GscSearchAnalyticsRequest {
+  startDate: string;
+  endDate: string;
+  dimensions?: GscSearchAnalyticsDimension[];
+  dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
+  rowLimit?: number;
+  startRow?: number;
+  searchType?: GscSearchType;
+}
+interface GscSearchAnalyticsRow {
+  keys: string[];
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+interface GscSearchAnalyticsResponse {
+  rows?: GscSearchAnalyticsRow[];
+  responseAggregationType?: string;
+}
+export { ColumnDef, ColumnType, GscSearchAnalyticsDimension, GscSearchAnalyticsFilter, GscSearchAnalyticsFilterGroup, GscSearchAnalyticsFilterOperator, GscSearchAnalyticsRequest, GscSearchAnalyticsResponse, GscSearchAnalyticsRow, GscSearchType, Row, TableName, TableSchema, TenantCtx };

package/dist/index.d.mts

@@ -12,71 +12,39 @@ declare function runSequentialBatch<I, R>(items: I[], operation: (item: I, index
   concurrency?: number;
   onProgress?: (result: R, index: number, total: number) => void;
 }): Promise<R[]>;
-type ApiSite = searchconsole_v1.Schema$WmxSite;
-type ApiSitemap = searchconsole_v1.Schema$WmxSitemap;
-type ApiSitemapContent = searchconsole_v1.Schema$WmxSitemapContent;
-type SearchAnalyticsQuery = searchconsole_v1.Schema$SearchAnalyticsQueryRequest;
-type SearchAnalyticsResponse = searchconsole_v1.Schema$SearchAnalyticsQueryResponse;
-type DataRow = searchconsole_v1.Schema$ApiDataRow;
-type DimensionFilter = searchconsole_v1.Schema$ApiDimensionFilter;
-type DimensionFilterGroup = searchconsole_v1.Schema$ApiDimensionFilterGroup;
-type UrlInspectionResult = searchconsole_v1.Schema$UrlInspectionResult;
-type IndexStatusResult = searchconsole_v1.Schema$IndexStatusInspectionResult;
-type MobileUsabilityResult = searchconsole_v1.Schema$MobileUsabilityInspectionResult;
-type RichResultsResult = searchconsole_v1.Schema$RichResultsInspectionResult;
-type InspectUrlIndexResponse = searchconsole_v1.Schema$InspectUrlIndexResponse;
-type UrlNotificationMetadata = indexing_v3.Schema$UrlNotificationMetadata;
-type PublishUrlNotificationResponse = indexing_v3.Schema$PublishUrlNotificationResponse;
-type RequiredNonNullable<T> = Required<Exclude<T, null | undefined>>;
-interface Site extends Required<Omit<ApiSite, 'siteUrl'>> {
-  siteUrl: string;
-}
-interface Period {
-  start: Date | string;
-  end: Date | string;
+/**
+ * Dimensions accepted by the Google Search Console Search Analytics API.
+ *
+ * This intentionally excludes package-only logical dimensions such as
+ * `queryCanonical`; host apps must route those through an engine-backed path.
+ */
+type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'searchAppearance';
+type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+interface GscSearchAnalyticsFilter {
+  dimension: GscSearchAnalyticsDimension;
+  expression: string;
+  operator?: GscSearchAnalyticsFilterOperator;
 }
-interface ResolvedAnalyticsRange {
-  period: Period;
-  prevPeriod?: Period;
+interface GscSearchAnalyticsFilterGroup {
+  groupType?: 'and' | 'or';
+  filters: GscSearchAnalyticsFilter[];
 }
-interface SiteAnalytics {
-  analytics: {
-    period: {
-      totalClicks: number;
-      totalImpressions: number;
-    };
-    prevPeriod: {
-      totalClicks: number;
-      totalImpressions: number;
-    };
-  };
-  sitemaps: ApiSitemap[];
-  indexedUrls: string[];
-  period: {
-    url: string;
-    clicks: number;
-    clicksPercent: number;
-    prevClicks: number;
-    impressions: number;
-    impressionsPercent: number;
-    prevImpressions: number;
-  }[];
-  keywords: {
-    keyword: string;
-    position: number;
-    prevPosition: number;
-    positionPercent: number;
-    ctr: number;
-    ctrPercent: number;
-    prevCtr: number;
-    clicks: number;
-  }[];
-  graph: {
-    keys?: undefined;
-    time: string;
-    clicks: number;
-    impressions: number;
-  }[];
+type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+/**
+ * Canonical host-facing Search Analytics request body.
+ *
+ * Google's generated client type also has deprecated/alternate fields. The
+ * gscdump query builder emits `searchType`, so apps should forward that field
+ * unchanged rather than translating it to `type`.
+ */
+interface GscSearchAnalyticsRequest {
+  startDate: string;
+  endDate: string;
+  dimensions?: GscSearchAnalyticsDimension[];
+  dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
+  rowLimit?: number;
+  startRow?: number;
+  searchType?: GscSearchType;
 }
 declare const _default: {
   name: string;
@@ -170,9 +138,75 @@ 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>;
-  toBody: () => SearchAnalyticsQuery;
+  toBody: () => GscSearchAnalyticsRequest;
   getState: () => BuilderState;
 }
+type ApiSite = searchconsole_v1.Schema$WmxSite;
+type ApiSitemap = searchconsole_v1.Schema$WmxSitemap;
+type ApiSitemapContent = searchconsole_v1.Schema$WmxSitemapContent;
+type SearchAnalyticsQuery = searchconsole_v1.Schema$SearchAnalyticsQueryRequest;
+type SearchAnalyticsResponse = searchconsole_v1.Schema$SearchAnalyticsQueryResponse;
+type DataRow = searchconsole_v1.Schema$ApiDataRow;
+type DimensionFilter = searchconsole_v1.Schema$ApiDimensionFilter;
+type DimensionFilterGroup = searchconsole_v1.Schema$ApiDimensionFilterGroup;
+type UrlInspectionResult = searchconsole_v1.Schema$UrlInspectionResult;
+type IndexStatusResult = searchconsole_v1.Schema$IndexStatusInspectionResult;
+type MobileUsabilityResult = searchconsole_v1.Schema$MobileUsabilityInspectionResult;
+type RichResultsResult = searchconsole_v1.Schema$RichResultsInspectionResult;
+type InspectUrlIndexResponse = searchconsole_v1.Schema$InspectUrlIndexResponse;
+type UrlNotificationMetadata = indexing_v3.Schema$UrlNotificationMetadata;
+type PublishUrlNotificationResponse = indexing_v3.Schema$PublishUrlNotificationResponse;
+type RequiredNonNullable<T> = Required<Exclude<T, null | undefined>>;
+interface Site extends Required<Omit<ApiSite, 'siteUrl'>> {
+  siteUrl: string;
+}
+interface Period {
+  start: Date | string;
+  end: Date | string;
+}
+interface ResolvedAnalyticsRange {
+  period: Period;
+  prevPeriod?: Period;
+}
+interface SiteAnalytics {
+  analytics: {
+    period: {
+      totalClicks: number;
+      totalImpressions: number;
+    };
+    prevPeriod: {
+      totalClicks: number;
+      totalImpressions: number;
+    };
+  };
+  sitemaps: ApiSitemap[];
+  indexedUrls: string[];
+  period: {
+    url: string;
+    clicks: number;
+    clicksPercent: number;
+    prevClicks: number;
+    impressions: number;
+    impressionsPercent: number;
+    prevImpressions: number;
+  }[];
+  keywords: {
+    keyword: string;
+    position: number;
+    prevPosition: number;
+    positionPercent: number;
+    ctr: number;
+    ctrPercent: number;
+    prevCtr: number;
+    clicks: number;
+  }[];
+  graph: {
+    keys?: undefined;
+    time: string;
+    clicks: number;
+    impressions: number;
+  }[];
+}
 type VerificationMethod = 'META' | 'FILE' | 'DNS_TXT' | 'DNS_CNAME' | 'ANALYTICS' | 'TAG_MANAGER';
 type VerificationSiteType = 'SITE' | 'INET_DOMAIN' | 'ANDROID_APP';
 interface VerificationSite {
@@ -561,6 +595,112 @@ declare const INDEXING_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;
+declare const GSCDUMP_ONBOARDING_CONTRACT_VERSION: "2026-05-11";
+declare const GSCDUMP_REQUIRED_ANALYTICS_SCOPE: "https://www.googleapis.com/auth/webmasters.readonly";
+declare const GSCDUMP_OPTIONAL_INDEXING_SCOPE: "https://www.googleapis.com/auth/indexing";
+declare const accountStatuses: readonly ["disconnected", "oauth_received", "scope_missing", "refresh_missing", "db_provisioning", "ready", "reauth_required"];
+declare const accountNextActions: readonly ["connect_google", "reconnect_google", "wait_for_provisioning", "none"];
+declare const propertyStatuses: readonly ["no_local_site", "no_gsc_property", "unverified_property", "verified_candidate", "registered", "linked"];
+declare const propertyNextActions: readonly ["create_site", "verify_gsc_property", "choose_property", "register_site", "none"];
+declare const analyticsStatuses: readonly ["not_registered", "queued", "preparing", "syncing", "queryable_live", "queryable_partial", "ready", "failed"];
+declare const analyticsNextActions: readonly ["wait_for_sync", "retry_sync", "none"];
+declare const querySourceModes: readonly ["none", "live", "d1", "r2", "mixed"];
+declare const sitemapStatuses: readonly ["unknown", "discovering", "none_found", "auto_submitted", "syncing", "ready", "failed"];
+declare const sitemapNextActions: readonly ["submit_sitemap", "wait_for_sitemaps", "retry_sitemaps", "none"];
+declare const indexingStatuses: readonly ["not_requested", "missing_scope", "insufficient_permission", "waiting_for_sitemaps", "discovering", "checking", "ready", "budget_exhausted", "no_urls", "failed"];
+declare const indexingNextActions: readonly ["reconnect_google", "fix_gsc_permission", "wait_for_sitemaps", "wait_for_indexing", "retry_indexing", "none"];
+declare const lifecycleWebhookEvents: readonly ["user.lifecycle.changed", "site.lifecycle.changed", "site.analytics.ready", "site.indexing.ready", "site.auth.failed", "job.failed"];
+declare const lifecycleErrorCodes: readonly ["missing_refresh_token", "missing_analytics_scope", "missing_indexing_scope", "token_refresh_failed", "permission_lost", "insufficient_gsc_permission", "gsc_property_not_found", "gsc_property_unverified", "user_database_not_provisioned", "sync_failed", "sitemap_sync_failed", "indexing_failed"];
+type AccountStatus = typeof accountStatuses[number];
+type AccountNextAction = typeof accountNextActions[number];
+type PropertyStatus = typeof propertyStatuses[number];
+type PropertyNextAction = typeof propertyNextActions[number];
+type AnalyticsStatus = typeof analyticsStatuses[number];
+type AnalyticsNextAction = typeof analyticsNextActions[number];
+type QuerySourceMode = typeof querySourceModes[number];
+type SitemapStatus = typeof sitemapStatuses[number];
+type SitemapNextAction = typeof sitemapNextActions[number];
+type IndexingStatus = typeof indexingStatuses[number];
+type IndexingNextAction = typeof indexingNextActions[number];
+type LifecycleWebhookEvent = typeof lifecycleWebhookEvents[number];
+type LifecycleErrorCode = typeof lifecycleErrorCodes[number];
+interface LifecycleProgress {
+  completed: number;
+  failed: number;
+  total: number;
+  percent: number;
+}
+interface LifecycleError {
+  code: LifecycleErrorCode;
+  message: string;
+  retryable: boolean;
+}
+interface PartnerLifecycleAccount {
+  status: AccountStatus;
+  grantedScopes: string[];
+  missingScopes: string[];
+  nextAction: AccountNextAction;
+}
+interface PartnerLifecycleSite {
+  siteId: string;
+  externalSiteId: string | null;
+  requestedUrl: string;
+  gscPropertyUrl: string | null;
+  permissionLevel: string | null;
+  property: {
+    status: PropertyStatus;
+    nextAction: PropertyNextAction;
+  };
+  analytics: {
+    status: AnalyticsStatus;
+    progress: LifecycleProgress;
+    queryable: boolean;
+    sourceMode: QuerySourceMode;
+    syncedRange: {
+      oldest: string | null;
+      newest: string | null;
+    };
+    nextAction: AnalyticsNextAction;
+  };
+  sitemaps: {
+    status: SitemapStatus;
+    discoveredCount: number;
+    nextAction: SitemapNextAction;
+  };
+  indexing: {
+    status: IndexingStatus;
+    eligible: boolean;
+    reason: string | null;
+    progress: LifecycleProgress;
+    nextAction: IndexingNextAction;
+  };
+  latestError: LifecycleError | null;
+  lifecycleRevision: number;
+  updatedAt: string;
+}
+interface PartnerLifecycleResponse {
+  contractVersion: typeof GSCDUMP_ONBOARDING_CONTRACT_VERSION;
+  userId: string;
+  partnerId: string | null;
+  account: PartnerLifecycleAccount;
+  sites: PartnerLifecycleSite[];
+}
+interface LifecycleWebhookEnvelope<TData extends Record<string, unknown> = Record<string, unknown>> {
+  contractVersion: typeof GSCDUMP_ONBOARDING_CONTRACT_VERSION;
+  deliveryId: string;
+  event: LifecycleWebhookEvent;
+  partnerId: string;
+  userId: string;
+  siteId?: string;
+  externalUserId?: string | null;
+  externalSiteId?: string | null;
+  lifecycleRevision: number;
+  occurredAt: string;
+  data: TData;
+}
+declare function parseGrantedScopes(scopes: string | null | undefined): string[];
+declare function hasRequiredAnalyticsScope(scopes: string | string[] | null | undefined): boolean;
+declare function hasOptionalIndexingScope(scopes: string | string[] | null | undefined): boolean;
 interface DiscoverSitemapOptions {
   /** User-Agent sent on the discovery requests. */
   userAgent?: string;
@@ -586,4 +726,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 { ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BackfillProgress, CallOptions, DAYS_PER_RANGE, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, FetchSitemapUrlsOptions, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscError, GscErrorKind, GscdumpApiOptions, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingIssueType, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, MS_PER_DAY, MobileUsabilityResult, Period, PublishUrlNotificationResponse, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, UrlInspectionResult, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, addDays, addSite, batchInspectUrls, batchRequestIndexing, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingMetadata, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, inspectUrl, isPermissionDeniedError, isValidGscDate, listVerifiedSites, progressBar, requestIndexing, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, 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, GscError, GscErrorKind, GscdumpApiOptions, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingIssueType, IndexingMetadata, IndexingNextAction, IndexingNotificationType, IndexingResult, IndexingStatus, InspectUrlIndexResponse, InspectUrlResult, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, MS_PER_DAY, MobileUsabilityResult, 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, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingMetadata, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, isPermissionDeniedError, isValidGscDate, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, parseGrantedScopes, progressBar, propertyNextActions, propertyStatuses, querySourceModes, requestIndexing, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, verificationMethodsFor, verifySite };

package/dist/index.mjs

@@ -929,6 +929,127 @@ function hasIndexingScope(scopes) {
 	if (!scopes) return false;
 	return scopes.includes("googleapis.com/auth/indexing");
 }
+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";
+const accountStatuses = [
+	"disconnected",
+	"oauth_received",
+	"scope_missing",
+	"refresh_missing",
+	"db_provisioning",
+	"ready",
+	"reauth_required"
+];
+const accountNextActions = [
+	"connect_google",
+	"reconnect_google",
+	"wait_for_provisioning",
+	"none"
+];
+const propertyStatuses = [
+	"no_local_site",
+	"no_gsc_property",
+	"unverified_property",
+	"verified_candidate",
+	"registered",
+	"linked"
+];
+const propertyNextActions = [
+	"create_site",
+	"verify_gsc_property",
+	"choose_property",
+	"register_site",
+	"none"
+];
+const analyticsStatuses = [
+	"not_registered",
+	"queued",
+	"preparing",
+	"syncing",
+	"queryable_live",
+	"queryable_partial",
+	"ready",
+	"failed"
+];
+const analyticsNextActions = [
+	"wait_for_sync",
+	"retry_sync",
+	"none"
+];
+const querySourceModes = [
+	"none",
+	"live",
+	"d1",
+	"r2",
+	"mixed"
+];
+const sitemapStatuses = [
+	"unknown",
+	"discovering",
+	"none_found",
+	"auto_submitted",
+	"syncing",
+	"ready",
+	"failed"
+];
+const sitemapNextActions = [
+	"submit_sitemap",
+	"wait_for_sitemaps",
+	"retry_sitemaps",
+	"none"
+];
+const indexingStatuses = [
+	"not_requested",
+	"missing_scope",
+	"insufficient_permission",
+	"waiting_for_sitemaps",
+	"discovering",
+	"checking",
+	"ready",
+	"budget_exhausted",
+	"no_urls",
+	"failed"
+];
+const indexingNextActions = [
+	"reconnect_google",
+	"fix_gsc_permission",
+	"wait_for_sitemaps",
+	"wait_for_indexing",
+	"retry_indexing",
+	"none"
+];
+const lifecycleWebhookEvents = [
+	"user.lifecycle.changed",
+	"site.lifecycle.changed",
+	"site.analytics.ready",
+	"site.indexing.ready",
+	"site.auth.failed",
+	"job.failed"
+];
+const lifecycleErrorCodes = [
+	"missing_refresh_token",
+	"missing_analytics_scope",
+	"missing_indexing_scope",
+	"token_refresh_failed",
+	"permission_lost",
+	"insufficient_gsc_permission",
+	"gsc_property_not_found",
+	"gsc_property_unverified",
+	"user_database_not_provisioned",
+	"sync_failed",
+	"sitemap_sync_failed",
+	"indexing_failed"
+];
+function parseGrantedScopes(scopes) {
+	return (scopes ?? "").split(/\s+/).map((s) => s.trim()).filter(Boolean);
+}
+function hasRequiredAnalyticsScope(scopes) {
+	return (Array.isArray(scopes) ? scopes : parseGrantedScopes(scopes)).includes(GSCDUMP_REQUIRED_ANALYTICS_SCOPE);
+}
+function hasOptionalIndexingScope(scopes) {
+	return (Array.isArray(scopes) ? scopes : parseGrantedScopes(scopes)).includes(GSCDUMP_OPTIONAL_INDEXING_SCOPE);
+}
 const FETCH_TIMEOUT_MS = 1e4;
 const COMMON_PATHS = ["/sitemap.xml", "/sitemap_index.xml"];
 const SITEMAP_DIRECTIVE_RE = /^Sitemap:\s*(\S+)/im;
@@ -996,4 +1117,4 @@ async function fetchSitemapUrls(sitemapUrl, options = {}) {
 	await visit(sitemapUrl, 0);
 	return out;
 }
-export { DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, MS_PER_DAY, addDays, addSite, batchInspectUrls, batchRequestIndexing, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingMetadata, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, inspectUrl, isPermissionDeniedError, isValidGscDate, listVerifiedSites, progressBar, requestIndexing, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, 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, 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, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingMetadata, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, isPermissionDeniedError, isValidGscDate, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, parseGrantedScopes, progressBar, propertyNextActions, propertyStatuses, querySourceModes, requestIndexing, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, verificationMethodsFor, verifySite };

package/dist/onboarding.d.mts

@@ -0,0 +1,107 @@
+declare const GSCDUMP_ONBOARDING_CONTRACT_VERSION: "2026-05-11";
+declare const GSCDUMP_REQUIRED_ANALYTICS_SCOPE: "https://www.googleapis.com/auth/webmasters.readonly";
+declare const GSCDUMP_OPTIONAL_INDEXING_SCOPE: "https://www.googleapis.com/auth/indexing";
+declare const accountStatuses: readonly ["disconnected", "oauth_received", "scope_missing", "refresh_missing", "db_provisioning", "ready", "reauth_required"];
+declare const accountNextActions: readonly ["connect_google", "reconnect_google", "wait_for_provisioning", "none"];
+declare const propertyStatuses: readonly ["no_local_site", "no_gsc_property", "unverified_property", "verified_candidate", "registered", "linked"];
+declare const propertyNextActions: readonly ["create_site", "verify_gsc_property", "choose_property", "register_site", "none"];
+declare const analyticsStatuses: readonly ["not_registered", "queued", "preparing", "syncing", "queryable_live", "queryable_partial", "ready", "failed"];
+declare const analyticsNextActions: readonly ["wait_for_sync", "retry_sync", "none"];
+declare const querySourceModes: readonly ["none", "live", "d1", "r2", "mixed"];
+declare const sitemapStatuses: readonly ["unknown", "discovering", "none_found", "auto_submitted", "syncing", "ready", "failed"];
+declare const sitemapNextActions: readonly ["submit_sitemap", "wait_for_sitemaps", "retry_sitemaps", "none"];
+declare const indexingStatuses: readonly ["not_requested", "missing_scope", "insufficient_permission", "waiting_for_sitemaps", "discovering", "checking", "ready", "budget_exhausted", "no_urls", "failed"];
+declare const indexingNextActions: readonly ["reconnect_google", "fix_gsc_permission", "wait_for_sitemaps", "wait_for_indexing", "retry_indexing", "none"];
+declare const lifecycleWebhookEvents: readonly ["user.lifecycle.changed", "site.lifecycle.changed", "site.analytics.ready", "site.indexing.ready", "site.auth.failed", "job.failed"];
+declare const lifecycleErrorCodes: readonly ["missing_refresh_token", "missing_analytics_scope", "missing_indexing_scope", "token_refresh_failed", "permission_lost", "insufficient_gsc_permission", "gsc_property_not_found", "gsc_property_unverified", "user_database_not_provisioned", "sync_failed", "sitemap_sync_failed", "indexing_failed"];
+type AccountStatus = typeof accountStatuses[number];
+type AccountNextAction = typeof accountNextActions[number];
+type PropertyStatus = typeof propertyStatuses[number];
+type PropertyNextAction = typeof propertyNextActions[number];
+type AnalyticsStatus = typeof analyticsStatuses[number];
+type AnalyticsNextAction = typeof analyticsNextActions[number];
+type QuerySourceMode = typeof querySourceModes[number];
+type SitemapStatus = typeof sitemapStatuses[number];
+type SitemapNextAction = typeof sitemapNextActions[number];
+type IndexingStatus = typeof indexingStatuses[number];
+type IndexingNextAction = typeof indexingNextActions[number];
+type LifecycleWebhookEvent = typeof lifecycleWebhookEvents[number];
+type LifecycleErrorCode = typeof lifecycleErrorCodes[number];
+interface LifecycleProgress {
+  completed: number;
+  failed: number;
+  total: number;
+  percent: number;
+}
+interface LifecycleError {
+  code: LifecycleErrorCode;
+  message: string;
+  retryable: boolean;
+}
+interface PartnerLifecycleAccount {
+  status: AccountStatus;
+  grantedScopes: string[];
+  missingScopes: string[];
+  nextAction: AccountNextAction;
+}
+interface PartnerLifecycleSite {
+  siteId: string;
+  externalSiteId: string | null;
+  requestedUrl: string;
+  gscPropertyUrl: string | null;
+  permissionLevel: string | null;
+  property: {
+    status: PropertyStatus;
+    nextAction: PropertyNextAction;
+  };
+  analytics: {
+    status: AnalyticsStatus;
+    progress: LifecycleProgress;
+    queryable: boolean;
+    sourceMode: QuerySourceMode;
+    syncedRange: {
+      oldest: string | null;
+      newest: string | null;
+    };
+    nextAction: AnalyticsNextAction;
+  };
+  sitemaps: {
+    status: SitemapStatus;
+    discoveredCount: number;
+    nextAction: SitemapNextAction;
+  };
+  indexing: {
+    status: IndexingStatus;
+    eligible: boolean;
+    reason: string | null;
+    progress: LifecycleProgress;
+    nextAction: IndexingNextAction;
+  };
+  latestError: LifecycleError | null;
+  lifecycleRevision: number;
+  updatedAt: string;
+}
+interface PartnerLifecycleResponse {
+  contractVersion: typeof GSCDUMP_ONBOARDING_CONTRACT_VERSION;
+  userId: string;
+  partnerId: string | null;
+  account: PartnerLifecycleAccount;
+  sites: PartnerLifecycleSite[];
+}
+interface LifecycleWebhookEnvelope<TData extends Record<string, unknown> = Record<string, unknown>> {
+  contractVersion: typeof GSCDUMP_ONBOARDING_CONTRACT_VERSION;
+  deliveryId: string;
+  event: LifecycleWebhookEvent;
+  partnerId: string;
+  userId: string;
+  siteId?: string;
+  externalUserId?: string | null;
+  externalSiteId?: string | null;
+  lifecycleRevision: number;
+  occurredAt: string;
+  data: TData;
+}
+declare function parseGrantedScopes(scopes: string | null | undefined): string[];
+declare function hasRequiredAnalyticsScope(scopes: string | string[] | null | undefined): boolean;
+declare function hasOptionalIndexingScope(scopes: string | string[] | null | undefined): boolean;
+export { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, IndexingNextAction, IndexingStatus, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, PropertyNextAction, PropertyStatus, QuerySourceMode, SitemapNextAction, SitemapStatus, accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, lifecycleErrorCodes, lifecycleWebhookEvents, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses };

package/dist/onboarding.mjs

@@ -0,0 +1,122 @@
+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";
+const accountStatuses = [
+	"disconnected",
+	"oauth_received",
+	"scope_missing",
+	"refresh_missing",
+	"db_provisioning",
+	"ready",
+	"reauth_required"
+];
+const accountNextActions = [
+	"connect_google",
+	"reconnect_google",
+	"wait_for_provisioning",
+	"none"
+];
+const propertyStatuses = [
+	"no_local_site",
+	"no_gsc_property",
+	"unverified_property",
+	"verified_candidate",
+	"registered",
+	"linked"
+];
+const propertyNextActions = [
+	"create_site",
+	"verify_gsc_property",
+	"choose_property",
+	"register_site",
+	"none"
+];
+const analyticsStatuses = [
+	"not_registered",
+	"queued",
+	"preparing",
+	"syncing",
+	"queryable_live",
+	"queryable_partial",
+	"ready",
+	"failed"
+];
+const analyticsNextActions = [
+	"wait_for_sync",
+	"retry_sync",
+	"none"
+];
+const querySourceModes = [
+	"none",
+	"live",
+	"d1",
+	"r2",
+	"mixed"
+];
+const sitemapStatuses = [
+	"unknown",
+	"discovering",
+	"none_found",
+	"auto_submitted",
+	"syncing",
+	"ready",
+	"failed"
+];
+const sitemapNextActions = [
+	"submit_sitemap",
+	"wait_for_sitemaps",
+	"retry_sitemaps",
+	"none"
+];
+const indexingStatuses = [
+	"not_requested",
+	"missing_scope",
+	"insufficient_permission",
+	"waiting_for_sitemaps",
+	"discovering",
+	"checking",
+	"ready",
+	"budget_exhausted",
+	"no_urls",
+	"failed"
+];
+const indexingNextActions = [
+	"reconnect_google",
+	"fix_gsc_permission",
+	"wait_for_sitemaps",
+	"wait_for_indexing",
+	"retry_indexing",
+	"none"
+];
+const lifecycleWebhookEvents = [
+	"user.lifecycle.changed",
+	"site.lifecycle.changed",
+	"site.analytics.ready",
+	"site.indexing.ready",
+	"site.auth.failed",
+	"job.failed"
+];
+const lifecycleErrorCodes = [
+	"missing_refresh_token",
+	"missing_analytics_scope",
+	"missing_indexing_scope",
+	"token_refresh_failed",
+	"permission_lost",
+	"insufficient_gsc_permission",
+	"gsc_property_not_found",
+	"gsc_property_unverified",
+	"user_database_not_provisioned",
+	"sync_failed",
+	"sitemap_sync_failed",
+	"indexing_failed"
+];
+function parseGrantedScopes(scopes) {
+	return (scopes ?? "").split(/\s+/).map((s) => s.trim()).filter(Boolean);
+}
+function hasRequiredAnalyticsScope(scopes) {
+	return (Array.isArray(scopes) ? scopes : parseGrantedScopes(scopes)).includes(GSCDUMP_REQUIRED_ANALYTICS_SCOPE);
+}
+function hasOptionalIndexingScope(scopes) {
+	return (Array.isArray(scopes) ? scopes : parseGrantedScopes(scopes)).includes(GSCDUMP_OPTIONAL_INDEXING_SCOPE);
+}
+export { GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, lifecycleErrorCodes, lifecycleWebhookEvents, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses };

package/dist/query/index.d.mts

@@ -1,6 +1,48 @@
 import _dayjs, { Dayjs } from "dayjs";
-import { searchconsole_v1 } from "@googleapis/searchconsole/build/v1";
-type SearchAnalyticsQuery = searchconsole_v1.Schema$SearchAnalyticsQueryRequest;
+/**
+ * Canonical cross-package contracts. Type-only — zero runtime cost.
+ *
+ * Imported by @gscdump/engine, @gscdump/analysis, @gscdump/cli, @gscdump/mcp,
+ * @gscdump/cloud as the single source of truth for cross-cutting types so
+ * schema identifiers, tenant shape, and analyzer IO can't drift across
+ * packages.
+ */
+/** Logical table / dataset identifier. Canonical across query builder + storage engine. */
+type TableName = 'pages' | 'keywords' | 'countries' | 'devices' | 'page_keywords' | 'search_appearance';
+/**
+ * Dimensions accepted by the Google Search Console Search Analytics API.
+ *
+ * This intentionally excludes package-only logical dimensions such as
+ * `queryCanonical`; host apps must route those through an engine-backed path.
+ */
+type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'searchAppearance';
+type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+interface GscSearchAnalyticsFilter {
+  dimension: GscSearchAnalyticsDimension;
+  expression: string;
+  operator?: GscSearchAnalyticsFilterOperator;
+}
+interface GscSearchAnalyticsFilterGroup {
+  groupType?: 'and' | 'or';
+  filters: GscSearchAnalyticsFilter[];
+}
+type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+/**
+ * Canonical host-facing Search Analytics request body.
+ *
+ * Google's generated client type also has deprecated/alternate fields. The
+ * gscdump query builder emits `searchType`, so apps should forward that field
+ * unchanged rather than translating it to `type`.
+ */
+interface GscSearchAnalyticsRequest {
+  startDate: string;
+  endDate: string;
+  dimensions?: GscSearchAnalyticsDimension[];
+  dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
+  rowLimit?: number;
+  startRow?: number;
+  searchType?: GscSearchType;
+}
 declare const _default: {
   name: string;
   'alpha-2': string;
@@ -114,7 +156,7 @@ 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>;
-  toBody: () => SearchAnalyticsQuery;
+  toBody: () => GscSearchAnalyticsRequest;
   getState: () => BuilderState;
 }
 declare const gsc: GSCQueryBuilder<[], object>;
@@ -152,16 +194,6 @@ declare function lt<D extends Dimension>(column: Column<D>, value: DimensionValu
 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 topLevel(column: Column<'page'>): Filter<object>;
-/**
- * Canonical cross-package contracts. Type-only — zero runtime cost.
- *
- * Imported by @gscdump/engine, @gscdump/analysis, @gscdump/cli, @gscdump/mcp,
- * @gscdump/cloud as the single source of truth for cross-cutting types so
- * schema identifiers, tenant shape, and analyzer IO can't drift across
- * packages.
- */
-/** Logical table / dataset identifier. Canonical across query builder + storage engine. */
-type TableName = 'pages' | 'keywords' | 'countries' | 'devices' | 'page_keywords' | 'search_appearance';
 type LogicalDataset = TableName;
 type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
 interface PlannerCapabilities {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Google Search Console API wrapper with typed query builder, streaming pagination, and SEO analysis functions",
   "author": {
     "name": "Harlan Wilton",
@@ -76,6 +76,11 @@
       "types": "./dist/sitemap.d.mts",
       "import": "./dist/sitemap.mjs",
       "default": "./dist/sitemap.mjs"
+    },
+    "./onboarding": {
+      "types": "./dist/onboarding.d.mts",
+      "import": "./dist/onboarding.mjs",
+      "default": "./dist/onboarding.mjs"
     }
   },
   "main": "./dist/index.mjs",