gscdump 0.11.3 → 0.11.5

package/dist/contracts.d.mts

@@ -1,80 +1,2 @@
-/**
- * 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';
-/** Untyped row shape crossing storage/query boundaries. */
-type Row = Record<string, unknown>;
-type ColumnType = 'DATE' | 'VARCHAR' | 'INTEGER' | 'BIGINT' | 'DOUBLE';
-interface ColumnDef {
-  name: string;
-  type: ColumnType;
-  nullable: boolean;
-}
-interface TableSchema {
-  name: TableName;
-  columns: ColumnDef[];
-  sortKey: string[];
-  /**
-   * Monotonically increasing version. Tagged onto every manifest entry written
-   * for this table; bump when columns are added/removed/retyped so readers can
-   * detect stale on-disk data.
-   */
-  version: number;
-}
-/** Tenant identity for multi-user / multi-site storage. */
-interface TenantCtx {
-  userId: string;
-  siteId?: 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 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 };
+import { ColumnDef, ColumnType, GscSearchAnalyticsDimension, GscSearchAnalyticsFilter, GscSearchAnalyticsFilterGroup, GscSearchAnalyticsFilterOperator, GscSearchAnalyticsRequest, GscSearchAnalyticsResponse, GscSearchAnalyticsRow, GscSearchType, Row, TableName, TableSchema, TenantCtx } from "@gscdump/contracts";
+export { type ColumnDef, type ColumnType, type GscSearchAnalyticsDimension, type GscSearchAnalyticsFilter, type GscSearchAnalyticsFilterGroup, type GscSearchAnalyticsFilterOperator, type GscSearchAnalyticsRequest, type GscSearchAnalyticsResponse, type GscSearchAnalyticsRow, type GscSearchType, type Row, type TableName, type TableSchema, type TenantCtx };

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { $Fetch, FetchOptions } from "ofetch";
 import { indexing_v3 } from "@googleapis/indexing/build/v3";
+import { GscSearchAnalyticsRequest } from "@gscdump/contracts";
 import { searchconsole_v1 } from "@googleapis/searchconsole/build/v1";
 /**
  * Batch runner with optional concurrency, inter-call delay, and progress.
@@ -12,40 +13,6 @@ declare function runSequentialBatch<I, R>(items: I[], operation: (item: I, index
   concurrency?: number;
   onProgress?: (result: R, index: number, total: number) => void;
 }): Promise<R[]>;
-/**
- * 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;
@@ -595,6 +562,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;
@@ -620,4 +693,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,48 +1,5 @@
 import _dayjs, { Dayjs } from "dayjs";
-/**
- * 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;
-}
+import { GscSearchAnalyticsRequest, TableName } from "@gscdump/contracts";
 declare const _default: {
   name: string;
   'alpha-2': string;

package/dist/query/plan.d.mts

@@ -1,13 +1,4 @@
-/**
- * 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';
+import { TableName } from "@gscdump/contracts";
 declare const _default: {
   name: string;
   'alpha-2': string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "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",
@@ -102,7 +107,8 @@
     "dayjs": "^1.11.20",
     "defu": "^6.1.7",
     "ofetch": "^1.5.1",
-    "ufo": "^1.6.4"
+    "ufo": "^1.6.4",
+    "@gscdump/contracts": "0.11.5"
   },
   "devDependencies": {
     "@googleapis/indexing": "^6.0.1",