gscdump 1.0.1 → 1.0.3

package/dist/_chunks/result.d.mts

@@ -0,0 +1,20 @@
+interface Ok<A> {
+  readonly ok: true;
+  readonly value: A;
+}
+interface Err<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+type Result<A, E> = Ok<A> | Err<E>;
+declare function ok<A>(value: A): Ok<A>;
+declare function err<E>(error: E): Err<E>;
+declare function isOk<A, E>(result: Result<A, E>): result is Ok<A>;
+declare function isErr<A, E>(result: Result<A, E>): result is Err<E>;
+/**
+ * Collapses a `Result` back into the throwing world: returns the value or throws
+ * via `toError`. Used by the throwing wrappers that sit over the `Result` core so
+ * existing call sites keep their `await`/`throw` ergonomics.
+ */
+declare function unwrapResult<A, E>(result: Result<A, E>, toError: (error: E) => unknown): A;
+export { Err, Ok, Result, err, isErr, isOk, ok, unwrapResult };

package/dist/_chunks/types.d.mts

@@ -0,0 +1,112 @@
+import { GscAggregationType, GscDataState } from "./contracts.mjs";
+declare const _default: {
+  name: string;
+  'alpha-2': string;
+  'alpha-3': string;
+  'country-code': string;
+}[];
+declare const Devices: {
+  readonly MOBILE: "MOBILE";
+  readonly DESKTOP: "DESKTOP";
+  readonly TABLET: "TABLET";
+};
+type Device = typeof Devices[keyof typeof Devices];
+declare const SearchTypes: {
+  readonly WEB: "web";
+  readonly IMAGE: "image";
+  readonly VIDEO: "video";
+  readonly NEWS: "news";
+  readonly DISCOVER: "discover";
+  readonly GOOGLE_NEWS: "googleNews";
+};
+type SearchType = typeof SearchTypes[keyof typeof SearchTypes];
+declare const Countries: { [K in (typeof _default)[number]["alpha-3"]]: Lowercase<K>; };
+type Country = typeof Countries[keyof typeof Countries];
+interface DimensionValueMap {
+  query: string;
+  queryCanonical: string;
+  page: string;
+  country: Country;
+  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 {
+  searchType: SearchType;
+}
+type QueryParamName = keyof QueryParamValueMap;
+interface Column<D extends Dimension> {
+  readonly __columnBrand: 'gscdump.Column';
+  readonly dimension: D;
+}
+interface QueryParam<P extends QueryParamName> {
+  readonly __queryParamBrand: 'gscdump.QueryParam';
+  readonly param: P;
+}
+type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+type DateOperator = 'gte' | 'gt' | 'lte' | 'lt' | 'between';
+type MetricOperator = 'metricGte' | 'metricGt' | 'metricLte' | 'metricLt' | 'metricBetween';
+type SpecialOperator = 'topLevel';
+interface InternalFilter {
+  dimension: Dimension | QueryParamName | Metric;
+  operator: FilterOperator | DateOperator | MetricOperator | SpecialOperator;
+  expression: string;
+  expression2?: string;
+}
+interface Filter<C = object> {
+  readonly __filterBrand: 'gscdump.Filter';
+  readonly _constraints: C;
+  readonly _filters: InternalFilter[];
+  readonly _nestedGroups?: Filter<any>[];
+  readonly _groupType?: 'and' | 'or';
+}
+type MergeConstraints<F extends Filter<any>[]> = UnionToIntersection<F[number]['_constraints']>;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+interface GSCResult<D extends Dimension[], C> {
+  rows: Array<GSCRow<D, C>>;
+}
+type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ? C[K] : DimensionValueMap[K]; } & {
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+};
+type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
+interface MetricColumn<M extends Metric> {
+  readonly __metricColumnBrand: 'gscdump.MetricColumn';
+  readonly metric: M;
+}
+interface BuilderState {
+  dimensions: Dimension[];
+  metrics?: Metric[];
+  filter?: Filter<any>;
+  prefilter?: Filter<any>;
+  orderBy?: {
+    column: Metric | 'date';
+    dir: 'asc' | 'desc';
+  };
+  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;
+  operator: string;
+  expression: string;
+  expression2?: string;
+}
+interface JsonFilter {
+  _filters: JsonInternalFilter[];
+  _nestedGroups?: JsonFilter[];
+  _groupType?: 'and' | 'or';
+}
+type FilterInput = Filter<any> | JsonFilter;
+export { BuilderState, Column, Countries, Country, Device, Devices, Dimension, DimensionValueMap, Filter, FilterInput, FilterOperator, GSCResult, GSCRow, InternalFilter, JsonFilter, JsonInternalFilter, MergeConstraints, Metric, MetricColumn, MetricOperator, QueryParam, QueryParamName, QueryParamValueMap, SearchType, SearchTypes };

package/dist/contracts.d.mts

@@ -1,47 +1,2 @@
-import { ColumnDef, ColumnType, Row, TableName, TableSchema, TenantCtx } from "@gscdump/contracts";
-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;
-  expression: string;
-  operator?: GscSearchAnalyticsFilterOperator;
-}
-interface GscSearchAnalyticsFilterGroup {
-  groupType?: 'and' | 'or';
-  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;
-  dimensions?: GscSearchAnalyticsDimension[];
-  dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
-  rowLimit?: number;
-  startRow?: number;
-  /** 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[];
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-interface GscSearchAnalyticsResponse {
-  rows?: GscSearchAnalyticsRow[];
-  responseAggregationType?: GscResponseAggregationType;
-  metadata?: GscSearchAnalyticsMetadata;
-}
+import { ColumnDef, ColumnType, GscAggregationType, GscDataState, GscResponseAggregationType, GscSearchAnalyticsDimension, GscSearchAnalyticsFilter, GscSearchAnalyticsFilterGroup, GscSearchAnalyticsFilterOperator, GscSearchAnalyticsMetadata, GscSearchAnalyticsRequest, GscSearchAnalyticsResponse, GscSearchAnalyticsRow, GscSearchType, Row, TableName, TableSchema, TenantCtx } from "./_chunks/contracts.mjs";
 export { type ColumnDef, type ColumnType, GscAggregationType, GscDataState, GscResponseAggregationType, GscSearchAnalyticsDimension, GscSearchAnalyticsFilter, GscSearchAnalyticsFilterGroup, GscSearchAnalyticsFilterOperator, GscSearchAnalyticsMetadata, GscSearchAnalyticsRequest, GscSearchAnalyticsResponse, GscSearchAnalyticsRow, GscSearchType, type Row, type TableName, type TableSchema, type TenantCtx };

package/dist/core/result.d.mts

@@ -1,20 +1,2 @@
-interface Ok<A> {
-  readonly ok: true;
-  readonly value: A;
-}
-interface Err<E> {
-  readonly ok: false;
-  readonly error: E;
-}
-type Result<A, E> = Ok<A> | Err<E>;
-declare function ok<A>(value: A): Ok<A>;
-declare function err<E>(error: E): Err<E>;
-declare function isOk<A, E>(result: Result<A, E>): result is Ok<A>;
-declare function isErr<A, E>(result: Result<A, E>): result is Err<E>;
-/**
- * Collapses a `Result` back into the throwing world: returns the value or throws
- * via `toError`. Used by the throwing wrappers that sit over the `Result` core so
- * existing call sites keep their `await`/`throw` ergonomics.
- */
-declare function unwrapResult<A, E>(result: Result<A, E>, toError: (error: E) => unknown): A;
+import { Err, Ok, Result, err, isErr, isOk, ok, unwrapResult } from "../_chunks/result.mjs";
 export { Err, Ok, Result, err, isErr, isOk, ok, unwrapResult };

package/dist/dates.d.mts

@@ -1,63 +1,3 @@
-/** Milliseconds in a UTC day. Use for date arithmetic without DST surprises. */
-declare const MS_PER_DAY = 86400000;
-/** Format a Date as YYYY-MM-DD (UTC). */
-declare function toIsoDate(d: Date): string;
-/** Most recent date GSC has fully finalized data for (no further updates). */
-declare const GSC_FINALIZED_LAG_DAYS = 3;
-/** Most recent date GSC will return data for, may still be updating. */
-declare const GSC_FRESHEST_LAG_DAYS = 1;
-/** Approximate historical retention window for Search Analytics. */
-declare const GSC_RETENTION_MONTHS = 16;
-/** Today's date (YYYY-MM-DD) in PST. */
-declare function getPstDate(): string;
-/** YYYY-MM-DD for `now() - n` days, UTC. */
-declare function daysAgo(n: number): string;
-/** Most recent finalized date (3 days ago PST). */
-declare function getLatestGscDate(): string;
-/** Freshest date GSC will return (yesterday PST, may still update). */
-declare function getFreshestGscDate(): string;
-/**
- * Dates that are still pending (1-3 days ago PST). These need to be re-synced
- * each day until they finalize.
- */
-declare function getPendingDates(): string[];
-/** All dates between two YYYY-MM-DD strings (inclusive, oldest first). */
-declare function getDateRange(startDate: string, endDate: string): string[];
-/** Default span used when chunking long backfills into batches. */
-declare const DAYS_PER_RANGE = 30;
-/**
- * Like {@link getDateRange} but skips dates outside GSC's queryable window
- * (older than retention or newer than the freshest date).
- */
-declare function generateGscDateRange(startDate: string, endDate: string): string[];
-/**
- * Group a sorted list of dates into contiguous runs, splitting on either a
- * gap or after `daysPerRange` dates accumulate. Useful for bucketing
- * backfill work into bounded jobs.
- */
-declare function groupIntoRanges(dates: string[], daysPerRange?: number): Array<{
-  startDate: string;
-  endDate: string;
-}>;
-/** Inclusive day count between two YYYY-MM-DD strings. */
-declare function countDays(startDate: string, endDate: string): number;
-/** Oldest date GSC retains (~16 months ago). */
-declare function getOldestGscDate(): string;
-/** Add `n` UTC days to a YYYY-MM-DD string (n may be negative). */
-declare function addDays(dateStr: string, n: number): string;
-declare function getNextDate(dateStr: string): string;
-interface BackfillProgress {
-  progress: number;
-  daysAvailable: number;
-  daysSynced: number;
-  oldestGscDate: string;
-  isComplete: boolean;
-}
-/**
- * Backfill progress (0-1) given the oldest + newest dates synced.
- * Returns null when no sync data exists.
- */
-declare function getBackfillProgress(oldestDateSynced: string | null, newestDateSynced: string | null): BackfillProgress | null;
-declare function currentPstDate(): string;
-declare function daysAgoPst(n: number): string;
+import { DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_RETENTION_MONTHS, MS_PER_DAY, addDays, countDays, daysAgo, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPstDate, groupIntoRanges, toIsoDate } from "./_chunks/gsc-dates.mjs";
+import { currentPstDate, daysAgoPst } from "./_chunks/dayjs.mjs";
 export { DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_RETENTION_MONTHS, MS_PER_DAY, addDays, countDays, currentPstDate, daysAgoPst, daysAgo as daysAgoUtc, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPstDate, groupIntoRanges, toIsoDate };

package/dist/dates.mjs

@@ -1,118 +1,3 @@
-import { format, subDays } from "date-fns";
-const MS_PER_DAY = 864e5;
-function toIsoDate(d) {
-	return d.toISOString().slice(0, 10);
-}
-const GSC_FINALIZED_LAG_DAYS = 3;
-const GSC_FRESHEST_LAG_DAYS = 1;
-const GSC_RETENTION_MONTHS = 16;
-function getPstDate() {
-	return (/* @__PURE__ */ new Date()).toLocaleDateString("en-CA", { timeZone: "America/Los_Angeles" });
-}
-function getPstDateDaysAgo(daysAgo) {
-	const pstNow = new Date((/* @__PURE__ */ new Date()).toLocaleString("en-US", { timeZone: "America/Los_Angeles" }));
-	pstNow.setDate(pstNow.getDate() - daysAgo);
-	return toIsoDate(pstNow);
-}
-function daysAgo(n) {
-	return toIsoDate(/* @__PURE__ */ new Date(Date.now() - n * MS_PER_DAY));
-}
-function getLatestGscDate() {
-	return getPstDateDaysAgo(3);
-}
-function getFreshestGscDate() {
-	return getPstDateDaysAgo(1);
-}
-function getPendingDates() {
-	const dates = [];
-	for (let daysAgo = 1; daysAgo <= 3; daysAgo++) dates.push(getPstDateDaysAgo(daysAgo));
-	return dates;
-}
-function getDateRange(startDate, endDate) {
-	const dates = [];
-	const endMs = Date.parse(`${endDate}T00:00:00Z`);
-	for (let cursor = Date.parse(`${startDate}T00:00:00Z`); cursor <= endMs; cursor += MS_PER_DAY) dates.push(toIsoDate(new Date(cursor)));
-	return dates;
-}
-const DAYS_PER_RANGE = 30;
-function generateGscDateRange(startDate, endDate) {
-	const start = startDate < getOldestGscDate() ? getOldestGscDate() : startDate;
-	const end = endDate > getFreshestGscDate() ? getFreshestGscDate() : endDate;
-	return start <= end ? getDateRange(start, end) : [];
-}
-function groupIntoRanges(dates, daysPerRange = 30) {
-	if (dates.length === 0) return [];
-	const sorted = [...dates].sort();
-	const ranges = [];
-	let rangeStart = sorted[0];
-	let rangePrev = sorted[0];
-	for (let i = 1; i < sorted.length; i++) {
-		const current = sorted[i];
-		const expected = getNextDate(rangePrev);
-		const daysInRange = countDays(rangeStart, rangePrev);
-		if (current !== expected || daysInRange >= daysPerRange) {
-			ranges.push({
-				startDate: rangeStart,
-				endDate: rangePrev
-			});
-			rangeStart = current;
-		}
-		rangePrev = current;
-	}
-	ranges.push({
-		startDate: rangeStart,
-		endDate: rangePrev
-	});
-	return ranges;
-}
-function countDays(startDate, endDate) {
-	return Math.round((Date.parse(`${endDate}T00:00:00Z`) - Date.parse(`${startDate}T00:00:00Z`)) / MS_PER_DAY) + 1;
-}
-function getOldestGscDate() {
-	const date = /* @__PURE__ */ new Date();
-	date.setMonth(date.getMonth() - 16);
-	return toIsoDate(date);
-}
-function addDays(dateStr, n) {
-	return toIsoDate(new Date(Date.parse(`${dateStr}T00:00:00Z`) + n * MS_PER_DAY));
-}
-function getNextDate(dateStr) {
-	return addDays(dateStr, 1);
-}
-function getBackfillProgress(oldestDateSynced, newestDateSynced) {
-	if (!oldestDateSynced || !newestDateSynced) return null;
-	const oldestGsc = getOldestGscDate();
-	const totalDays = countDays(oldestGsc, getLatestGscDate());
-	const syncedDays = countDays(oldestDateSynced, newestDateSynced);
-	return {
-		progress: Math.round(Math.min(1, syncedDays / totalDays) * 100) / 100,
-		daysAvailable: totalDays,
-		daysSynced: syncedDays,
-		oldestGscDate: oldestGsc,
-		isComplete: oldestDateSynced <= oldestGsc
-	};
-}
-const PST_FORMATTER = new Intl.DateTimeFormat("en-CA", {
-	timeZone: "America/Los_Angeles",
-	year: "numeric",
-	month: "2-digit",
-	day: "2-digit"
-});
-function pstDateParts(d = /* @__PURE__ */ new Date()) {
-	const parts = PST_FORMATTER.formatToParts(d);
-	const get = (t) => Number(parts.find((p) => p.type === t).value);
-	return {
-		year: get("year"),
-		month: get("month"),
-		day: get("day")
-	};
-}
-function currentPstDate() {
-	const { year, month, day } = pstDateParts();
-	return `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
-}
-function daysAgoPst(n) {
-	const { year, month, day } = pstDateParts();
-	return format(subDays(new Date(year, month - 1, day, 12), n), "yyyy-MM-dd");
-}
+import { DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_RETENTION_MONTHS, MS_PER_DAY, addDays, countDays, daysAgo, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPstDate, groupIntoRanges, toIsoDate } from "./_chunks/gsc-dates.mjs";
+import { currentPstDate, daysAgoPst } from "./_chunks/dayjs.mjs";
 export { DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_RETENTION_MONTHS, MS_PER_DAY, addDays, countDays, currentPstDate, daysAgoPst, daysAgo as daysAgoUtc, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPstDate, groupIntoRanges, toIsoDate };

package/dist/index.d.mts

@@ -1,3 +1,10 @@
+import { GscResponseAggregationType, GscSearchAnalyticsMetadata } from "./_chunks/contracts.mjs";
+import { Err, Ok, Result, err, isErr, isOk, ok, unwrapResult } from "./_chunks/result.mjs";
+import { BackfillProgress, DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_RETENTION_MONTHS, MS_PER_DAY, addDays, countDays, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, groupIntoRanges, isValidGscDate, toIsoDate } from "./_chunks/gsc-dates.mjs";
+import { Dimension, GSCRow } from "./_chunks/types.mjs";
+import { GSCQueryBuilder } from "./_chunks/builder.mjs";
+import { normalizeUrl } from "./normalize.mjs";
+import { decodeSiteId, encodeSiteId, normalizeSiteUrl } from "./tenant.mjs";
 import { $Fetch, FetchOptions } from "ofetch";
 import { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_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, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses } from "@gscdump/contracts/partner";
 /**
@@ -11,148 +18,6 @@ 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' | '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;
-  expression: string;
-  operator?: GscSearchAnalyticsFilterOperator;
-}
-interface GscSearchAnalyticsFilterGroup {
-  groupType?: 'and' | 'or';
-  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;
-  dimensions?: GscSearchAnalyticsDimension[];
-  dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
-  rowLimit?: number;
-  startRow?: number;
-  /** 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;
-  'alpha-2': string;
-  'alpha-3': string;
-  'country-code': string;
-}[];
-declare const Devices: {
-  readonly MOBILE: "MOBILE";
-  readonly DESKTOP: "DESKTOP";
-  readonly TABLET: "TABLET";
-};
-type Device = typeof Devices[keyof typeof Devices];
-declare const SearchTypes: {
-  readonly WEB: "web";
-  readonly IMAGE: "image";
-  readonly VIDEO: "video";
-  readonly NEWS: "news";
-  readonly DISCOVER: "discover";
-  readonly GOOGLE_NEWS: "googleNews";
-};
-type SearchType = typeof SearchTypes[keyof typeof SearchTypes];
-declare const Countries: { [K in (typeof _default)[number]["alpha-3"]]: Lowercase<K>; };
-type Country = typeof Countries[keyof typeof Countries];
-interface DimensionValueMap {
-  query: string;
-  queryCanonical: string;
-  page: string;
-  country: Country;
-  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 {
-  searchType: SearchType;
-}
-type QueryParamName = keyof QueryParamValueMap;
-interface Column<D extends Dimension> {
-  readonly __columnBrand: 'gscdump.Column';
-  readonly dimension: D;
-}
-type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
-type DateOperator = 'gte' | 'gt' | 'lte' | 'lt' | 'between';
-type MetricOperator = 'metricGte' | 'metricGt' | 'metricLte' | 'metricLt' | 'metricBetween';
-type SpecialOperator = 'topLevel';
-interface InternalFilter {
-  dimension: Dimension | QueryParamName | Metric;
-  operator: FilterOperator | DateOperator | MetricOperator | SpecialOperator;
-  expression: string;
-  expression2?: string;
-}
-interface Filter<C = object> {
-  readonly __filterBrand: 'gscdump.Filter';
-  readonly _constraints: C;
-  readonly _filters: InternalFilter[];
-  readonly _nestedGroups?: Filter<any>[];
-  readonly _groupType?: 'and' | 'or';
-}
-type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ? C[K] : DimensionValueMap[K]; } & {
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-};
-type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
-interface MetricColumn<M extends Metric> {
-  readonly __metricColumnBrand: 'gscdump.MetricColumn';
-  readonly metric: M;
-}
-interface BuilderState {
-  dimensions: Dimension[];
-  metrics?: Metric[];
-  filter?: Filter<any>;
-  prefilter?: Filter<any>;
-  orderBy?: {
-    column: Metric | 'date';
-    dir: 'asc' | 'desc';
-  };
-  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'>;
-type ExtractDimensions<T extends SelectableColumn[]> = { [K in keyof T]: T[K] extends Column<infer D> ? D : never; }[number] extends (infer U) ? Exclude<U, never>[] : never;
-interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
-  select: {
-    <T extends Dimension[]>(...dims: T): GSCQueryBuilder<T, C>;
-    <T extends SelectableColumn[]>(...cols: T): GSCQueryBuilder<ExtractDimensions<T> & Dimension[], C>;
-  };
-  where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
-  prefilter: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C>;
-  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;
-}
 /** Search Console property returned by the Sites resource. */
 interface ApiSite {
   permissionLevel?: string | null;
@@ -654,25 +519,6 @@ declare function rethrowAsGscApiError(prefix: string): (err: unknown) => never;
  * needs the permission verdict.
  */
 declare function isPermissionDeniedError(err: unknown): boolean;
-interface Ok<A> {
-  readonly ok: true;
-  readonly value: A;
-}
-interface Err<E> {
-  readonly ok: false;
-  readonly error: E;
-}
-type Result<A, E> = Ok<A> | Err<E>;
-declare function ok<A>(value: A): Ok<A>;
-declare function err<E>(error: E): Err<E>;
-declare function isOk<A, E>(result: Result<A, E>): result is Ok<A>;
-declare function isErr<A, E>(result: Result<A, E>): result is Err<E>;
-/**
- * Collapses a `Result` back into the throwing world: returns the value or throws
- * via `toError`. Used by the throwing wrappers that sit over the `Result` core so
- * existing call sites keep their `await`/`throw` ergonomics.
- */
-declare function unwrapResult<A, E>(result: Result<A, E>, toError: (error: E) => unknown): A;
 interface OAuthTokens {
   accessToken: string;
   /** Unix seconds. */
@@ -801,67 +647,6 @@ declare function getVerifiedSite(client: GoogleSearchConsoleClient, id: string):
  * on the property are unaffected.
  */
 declare function unverifySite(client: GoogleSearchConsoleClient, id: string): Promise<void>;
-/** Milliseconds in a UTC day. Use for date arithmetic without DST surprises. */
-declare const MS_PER_DAY = 86400000;
-/** Format a Date as YYYY-MM-DD (UTC). */
-declare function toIsoDate(d: Date): string;
-/** Most recent date GSC has fully finalized data for (no further updates). */
-declare const GSC_FINALIZED_LAG_DAYS = 3;
-/** Most recent date GSC will return data for, may still be updating. */
-declare const GSC_FRESHEST_LAG_DAYS = 1;
-/** Approximate historical retention window for Search Analytics. */
-declare const GSC_RETENTION_MONTHS = 16;
-/** Today's date (YYYY-MM-DD) in PST. */
-declare function getPstDate(): string;
-/** Most recent finalized date (3 days ago PST). */
-declare function getLatestGscDate(): string;
-/** Freshest date GSC will return (yesterday PST, may still update). */
-declare function getFreshestGscDate(): string;
-/**
- * Dates that are still pending (1-3 days ago PST). These need to be re-synced
- * each day until they finalize.
- */
-declare function getPendingDates(): string[];
-/** All dates between two YYYY-MM-DD strings (inclusive, oldest first). */
-declare function getDateRange(startDate: string, endDate: string): string[];
-/** Default span used when chunking long backfills into batches. */
-declare const DAYS_PER_RANGE = 30;
-/**
- * Like {@link getDateRange} but skips dates outside GSC's queryable window
- * (older than retention or newer than the freshest date).
- */
-declare function generateGscDateRange(startDate: string, endDate: string): string[];
-/**
- * Group a sorted list of dates into contiguous runs, splitting on either a
- * gap or after `daysPerRange` dates accumulate. Useful for bucketing
- * backfill work into bounded jobs.
- */
-declare function groupIntoRanges(dates: string[], daysPerRange?: number): Array<{
-  startDate: string;
-  endDate: string;
-}>;
-/** Inclusive day count between two YYYY-MM-DD strings. */
-declare function countDays(startDate: string, endDate: string): number;
-/** Oldest date GSC retains (~16 months ago). */
-declare function getOldestGscDate(): string;
-/** Add `n` UTC days to a YYYY-MM-DD string (n may be negative). */
-declare function addDays(dateStr: string, n: number): string;
-declare function getPreviousDate(dateStr: string): string;
-declare function getNextDate(dateStr: string): string;
-/** True if `dateStr` falls within GSC's queryable window. */
-declare function isValidGscDate(dateStr: string): boolean;
-interface BackfillProgress {
-  progress: number;
-  daysAvailable: number;
-  daysSynced: number;
-  oldestGscDate: string;
-  isComplete: boolean;
-}
-/**
- * Backfill progress (0-1) given the oldest + newest dates synced.
- * Returns null when no sync data exists.
- */
-declare function getBackfillProgress(oldestDateSynced: string | null, newestDateSynced: string | null): BackfillProgress | null;
 declare const INDEXING_ISSUE_FILTERS: {
   readonly canonical_mismatch: "user_canonical IS NOT NULL AND google_canonical IS NOT NULL AND user_canonical != google_canonical";
   readonly stale_crawl: "last_crawl_time < datetime('now', '-30 days')";
@@ -996,7 +781,6 @@ declare function normalizeGscSiteUrl(siteUrl: string): string;
  * Returns lowercase hostname stripped of protocol, or null if unparseable.
  */
 declare function normalizeRegistrationTarget(inputUrl: string): string | null;
-declare function normalizeUrl(input: string): string;
 interface DiscoverSitemapOptions {
   /** User-Agent sent on the discovery requests. */
   userAgent?: string;
@@ -1022,23 +806,6 @@ interface FetchSitemapUrlsOptions extends DiscoverSitemapOptions {
  * `<loc>https://...</loc>` shape but doesn't validate the schema.
  */
 declare function fetchSitemapUrls(sitemapUrl: string, options?: FetchSitemapUrlsOptions): Promise<string[]>;
-declare function encodeSiteId(siteUrl: string): string;
-/**
- * Best-effort inverse of `encodeSiteId` for the common prefixes. Lossy
- * (`encodeSiteId` collapses non-word chars to `_` and strips trailing
- * underscores), but round-trips domain properties + https origins cleanly —
- * the only two shapes GSC hands out in practice.
- *
- * Returns the input unchanged when neither prefix is recognised, so callers
- * can pass through canonical site URLs without branching.
- */
-declare function decodeSiteId(encoded: string): string;
-/**
- * Normalize a siteUrl to the form Google APIs expect: domain properties get
- * the `sc-domain:` prefix added if missing, URL properties pass through.
- * Idempotent — safe to call on already-prefixed values.
- */
-declare function normalizeSiteUrl(siteUrl: string): string;
 /**
  * Equivalence key for matching two URLs that point at the same resource
  * across protocol (http/https), www. prefix, trailing slash, and casing.