gscdump 1.0.1 → 1.0.3

package/dist/query/index.d.mts

@@ -1,161 +1,9 @@
-import { TableName } from "@gscdump/contracts";
-type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'hour' | 'searchAppearance';
-type GscDataState = 'final' | 'all' | 'hourly_all';
-type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
-interface GscSearchAnalyticsFilter {
-  dimension: GscSearchAnalyticsDimension;
-  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';
-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;
-}
-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;
-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;
-}
-declare const gsc: GSCQueryBuilder<[], object>;
+import { GscSearchAnalyticsRequest } from "../_chunks/contracts.mjs";
+import { Result } from "../_chunks/result.mjs";
+import { currentPstDate } from "../_chunks/dayjs.mjs";
+import { BuilderState, Column, Countries, Country, Device, Devices, Dimension, DimensionValueMap, Filter, FilterInput, GSCResult, GSCRow, InternalFilter, JsonFilter, JsonInternalFilter, MergeConstraints, Metric, MetricColumn, QueryParam, QueryParamName, QueryParamValueMap, SearchType, SearchTypes } from "../_chunks/types.mjs";
+import { GSCQueryBuilder, gsc } from "../_chunks/builder.mjs";
+import { ComparisonFilter, LogicalComparisonPlan, LogicalDataset, LogicalDimensionFilter, LogicalMetricFilter, LogicalQueryPlan, PlannerCapabilities, QueryError, QueryErrorKind, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, isQueryError, queryErrorToException, queryErrors } from "../_chunks/plan.mjs";
 declare const page: Column<"page">;
 declare const query: Column<"query">;
 declare const queryCanonical: Column<"queryCanonical">;
@@ -169,89 +17,6 @@ declare const impressions: MetricColumn<"impressions">;
 declare const ctr: MetricColumn<"ctr">;
 declare const position: MetricColumn<"position">;
 declare const searchType: QueryParam<"searchType">;
-type QueryErrorKind = 'missing-date-range' | 'invalid-row-limit' | 'invalid-start-row' | 'invalid-data-state' | 'invalid-aggregation-type' | 'invalid-builder-state' | 'invalid-filter' | 'unsupported-capability' | 'unresolvable-dataset';
-type QueryError = {
-  kind: 'missing-date-range';
-  message: string;
-} | {
-  kind: 'invalid-row-limit';
-  value: unknown;
-  message: string;
-} | {
-  kind: 'invalid-start-row';
-  value: unknown;
-  message: string;
-} | {
-  kind: 'invalid-data-state';
-  message: string;
-} | {
-  kind: 'invalid-aggregation-type';
-  message: string;
-} | {
-  kind: 'invalid-builder-state';
-  message: string;
-  cause?: unknown;
-} | {
-  kind: 'invalid-filter';
-  message: string;
-} | {
-  kind: 'unsupported-capability';
-  capability: string;
-  context: string;
-  message: string;
-} | {
-  kind: 'unresolvable-dataset';
-  dimensions: readonly Dimension[];
-  filterDims: readonly Dimension[];
-  message: string;
-};
-declare const queryErrors: {
-  readonly missingDateRange: () => QueryError;
-  readonly invalidRowLimit: (value: unknown) => QueryError;
-  readonly invalidStartRow: (value: unknown) => QueryError;
-  readonly hourDimensionRequiresHourlyState: () => QueryError;
-  readonly hourlyStateRequiresHourDimension: () => QueryError;
-  readonly byPropertyUnsupportedSearchType: () => QueryError;
-  readonly byPropertyNotAllowedWithPage: () => QueryError;
-  readonly byNewsShowcaseRequiresSearchType: () => QueryError;
-  readonly byNewsShowcaseNotAllowedWithPage: () => QueryError;
-  readonly byNewsShowcaseRequiresShowcaseFilter: () => QueryError;
-  readonly invalidBuilderState: (cause?: unknown) => QueryError;
-  readonly malformedFilterLeaf: () => QueryError;
-  readonly unsupportedCapability: (capability: string, context: string) => QueryError;
-  readonly unresolvableDataset: (dimensions: readonly Dimension[], filterDims?: readonly Dimension[]) => QueryError;
-};
-declare function isQueryError(value: unknown): value is QueryError;
-/**
- * Thrown when a query needs a planner capability (regex pushdown, comparison
- * joins, multi-dataset reads) the target engine lacks. Engines catch it to fall
- * back to the live GSC API. Carries the typed `queryError` value so a caller can
- * read the modelled failure instead of parsing the message.
- */
-declare class UnsupportedLogicalCapabilityError extends Error {
-  readonly queryError: Extract<QueryError, {
-    kind: 'unsupported-capability';
-  }>;
-  constructor(capability: string, context: string);
-}
-/**
- * Thrown when a query's grouped + filtered dimensions span more than one stored
- * dataset. Replaces the resolver's raw "unknown column" error so hosts can map
- * it to a 4xx instead of leaking an opaque 500. Carries the typed `queryError`.
- */
-declare class UnresolvableDatasetError extends Error {
-  readonly queryError: Extract<QueryError, {
-    kind: 'unresolvable-dataset';
-  }>;
-  constructor(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]);
-}
-/**
- * Re-raises a `QueryError` value as an `Error`, preserving the historical class
- * identity for the two errors engines match on by name (`UnresolvableDatasetError`,
- * `UnsupportedLogicalCapabilityError`). Pairs with `unwrapResult` so a
- * `fooResult(): Result<A, QueryError>` core can back a throwing `foo()`.
- */
-declare function queryErrorToException(error: QueryError): Error;
 declare function eq<D extends Dimension, V extends DimensionValueMap[D]>(column: Column<D>, value: V): Filter<Record<D, V>>;
 declare function eq<P extends QueryParamName, V extends QueryParamValueMap[P]>(param: QueryParam<P>, value: V): Filter<Record<P, V>>;
 declare function ne<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
@@ -274,87 +39,6 @@ declare function lt(column: Column<'date'>, value: string): Filter<object>;
 declare function between<M extends Metric>(column: MetricColumn<M>, start: number, end: number): Filter<object>;
 declare function between(column: Column<'date'>, start: string, end: string): Filter<object>;
 declare function topLevel(column: Column<'page'>): Filter<object>;
-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>;
-type LogicalDataset = TableName;
-type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
-interface PlannerCapabilities {
-  regex?: boolean;
-  multiDataset?: boolean;
-  comparisonJoin?: boolean;
-  windowTotals?: boolean;
-}
-interface LogicalDimensionFilter {
-  dimension: Dimension;
-  operator: FilterOperator;
-  expression: string;
-  expression2?: string;
-}
-interface LogicalMetricFilter {
-  metric: Metric;
-  operator: MetricOperator;
-  expression: number;
-  expression2?: number;
-}
-interface LogicalFilterLeaf {
-  kind: 'leaf';
-  filter: LogicalDimensionFilter;
-}
-interface LogicalFilterGroup {
-  kind: 'group';
-  groupType: 'and' | 'or';
-  children: LogicalFilterNode[];
-}
-type LogicalFilterNode = LogicalFilterLeaf | LogicalFilterGroup;
-interface LogicalQueryPlan {
-  dataset: LogicalDataset;
-  dimensions: Dimension[];
-  groupByDimensions: Dimension[];
-  hasDate: boolean;
-  metrics: Metric[];
-  dateRange: {
-    startDate: string;
-    endDate: string;
-  };
-  dimensionFilters: LogicalDimensionFilter[];
-  dimensionFilterTree?: LogicalFilterNode;
-  metricFilters: LogicalMetricFilter[];
-  prefilters: LogicalMetricFilter[];
-  specialFilters: {
-    topLevel: boolean;
-  };
-  queryParams: Partial<Record<QueryParamName, string>>;
-  orderBy?: BuilderState['orderBy'];
-  rowLimit?: number;
-  startRow?: number;
-}
-interface LogicalComparisonPlan {
-  current: LogicalQueryPlan;
-  previous: LogicalQueryPlan;
-  comparisonFilter?: ComparisonFilter;
-}
-/**
- * Errors-as-values core: builds the logical plan or returns a typed `QueryError`
- * for every modelled failure (missing date range, a regex filter on an engine
- * without regex pushdown, a cross-dimension query with no stored home).
- * `buildLogicalPlan` is the throwing wrapper for call sites that prefer exceptions.
- */
-declare function buildLogicalPlanResult(state: BuilderState, capabilities?: PlannerCapabilities): Result<LogicalQueryPlan, QueryError>;
-declare function buildLogicalPlan(state: BuilderState, capabilities?: PlannerCapabilities): LogicalQueryPlan;
-/**
- * Errors-as-values core for the comparison plan: returns a typed `QueryError`
- * when the engine lacks the comparison-join or multi-dataset capability the
- * paired queries need, or when either side fails to plan.
- */
-declare function buildLogicalComparisonPlanResult(current: BuilderState, previous: BuilderState, capabilities?: PlannerCapabilities, comparisonFilter?: ComparisonFilter): Result<LogicalComparisonPlan, QueryError>;
-declare function buildLogicalComparisonPlan(current: BuilderState, previous: BuilderState, capabilities?: PlannerCapabilities, comparisonFilter?: ComparisonFilter): LogicalComparisonPlan;
 declare function normalizeFilter(input?: FilterInput): Filter<any> | undefined;
 /**
  * Errors-as-values core for {@link normalizeBuilderState}: returns an
@@ -389,7 +73,6 @@ declare function extractSearchType(state: BuilderState | undefined | null): Sear
  */
 declare function resolveToBodyResult(state: BuilderState): Result<GscSearchAnalyticsRequest, QueryError>;
 declare function resolveToBody(state: BuilderState): GscSearchAnalyticsRequest;
-declare function currentPstDate(): string;
 declare function today(): string;
 declare function daysAgo(n: number): string;
 export { type BuilderState, type Column, type ComparisonFilter, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type FilterInput, type GSCQueryBuilder, type GSCResult, type GSCRow, type InternalFilter, type JsonFilter, type JsonInternalFilter, type LogicalComparisonPlan, type LogicalDataset, type LogicalDimensionFilter, type LogicalMetricFilter, type LogicalQueryPlan, type Metric, type MetricColumn, type PlannerCapabilities, QueryError, QueryErrorKind, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, clicks, contains, country, ctr, currentPstDate, date, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, gsc, gt, gte, hour, impressions, inArray, isQueryError, like, lt, lte, ne, normalizeBuilderState, normalizeBuilderStateResult, normalizeFilter, not, notRegex, or, page, position, query, queryCanonical, queryErrorToException, queryErrors, regex, resolveToBody, resolveToBodyResult, searchAppearance, searchType, today, topLevel };