gscdump 1.0.2 → 1.0.3

package/dist/query/plan.d.mts

@@ -1,235 +1,3 @@
-import { TableName } from "@gscdump/contracts";
-type GscDataState = 'final' | 'all' | 'hourly_all';
-type GscAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
-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 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;
-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 Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
-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 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;
-};
-/**
- * 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[]);
-}
-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;
-}
-declare function inferDataset(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]): LogicalDataset;
-/**
- * True when every grouped + filtered dimension fits inside one stored dataset,
- * i.e. the query is answerable from stored Parquet/D1 tables without a live
- * GSC call. `inferDataset` always returns *some* dataset; this predicate is
- * how callers tell a genuine match from one that will fail at column-resolve
- * time.
- */
-declare function isDatasetResolvable(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]): boolean;
-/**
- * `BuilderState`-level convenience for {@link isDatasetResolvable}: extracts
- * the state's dimension filters (the same way `buildLogicalPlan` does) and
- * checks them against the grouped dimensions. Lets routing code (e.g. the
- * composite source) detect a cross-dimension query without rebuilding a plan.
- */
-declare function isStateResolvable(state: BuilderState): boolean;
-/**
- * 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;
+import { TableName } from "../_chunks/contracts.mjs";
+import { ComparisonFilter, LogicalComparisonPlan, LogicalDataset, LogicalDimensionFilter, LogicalFilterGroup, LogicalFilterLeaf, LogicalFilterNode, LogicalMetricFilter, LogicalQueryPlan, PlannerCapabilities, QueryError, QueryErrorKind, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, inferDataset, isDatasetResolvable, isStateResolvable } from "../_chunks/plan.mjs";
 export { ComparisonFilter, LogicalComparisonPlan, LogicalDataset, LogicalDimensionFilter, LogicalFilterGroup, LogicalFilterLeaf, LogicalFilterNode, LogicalMetricFilter, LogicalQueryPlan, PlannerCapabilities, type QueryError, type QueryErrorKind, type TableName, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, inferDataset, isDatasetResolvable, isStateResolvable };