@gscdump/engine-gsc-api 1.4.0 → 1.4.1

package/dist/index.d.mts

@@ -1,205 +1,5 @@
-import { GoogleSearchConsoleClient } from "gscdump";
-import { BuilderState, Column, Dimension, SearchType } from "gscdump/query";
-import { SearchType as SearchType$1 } from "@gscdump/engine";
-import { AnalysisQuerySource } from "@gscdump/engine/source";
-import { GscDataState, GscSearchAnalyticsMetadata } from "gscdump/contracts";
-declare function canProxyToGsc(state: BuilderState): boolean;
-interface CreateLiveGscSourceOptions {
-  /** GSC property URL (e.g. `sc-domain:example.com` or `https://example.com/`). */
-  siteUrl: string;
-  /**
-   * Returns a valid GSC access token. Called lazily on first query so refresh
-   * cost is paid only when the source actually runs. Host owns refresh logic.
-   */
-  getAccessToken: () => Promise<string>;
-  /** Optional host client factory (for custom timeouts, fetch, or telemetry). */
-  createClient?: (accessToken: string) => GoogleSearchConsoleClient | Promise<GoogleSearchConsoleClient>;
-  /**
-   * GSC `searchType` slice this source is scoped to (`web`, `discover`,
-   * `news`, `googleNews`, `image`, `video`). When set, the slice is injected
-   * into every outgoing builder state so the live API returns rows for that
-   * slice only. An explicit search type already present on the state wins.
-   */
-  searchType?: SearchType$1;
-}
-declare function createLiveGscSource(opts: CreateLiveGscSourceOptions): AnalysisQuerySource;
-interface GscRange {
-  start: string;
-  end: string;
-}
-interface GscTopNRow {
-  key: string;
-  clicks: number;
-  impressions: number;
-  sum_position: number;
-}
-interface FetchTopNOptions<D extends Dimension> {
-  client: GoogleSearchConsoleClient;
-  siteUrl: string;
-  dimension: Column<D>;
-  range: GscRange;
-  /**
-   * Ask the GSC API to order by clicks desc. Skip for dimensions where GSC
-   * already returns sensibly ranked rows (e.g. country).
-   */
-  orderByClicksDesc?: boolean;
-  /** Forwarded to the GSC builder. */
-  limit?: number;
-  /** Trim after the fact (e.g. country has no server-side limit). */
-  sliceTop?: number;
-  /** GSC search corpus; callers default API-boundary omissions to web. */
-  searchType?: SearchType;
-}
-declare function fetchGscTopN<D extends Dimension>(opts: FetchTopNOptions<D>): Promise<GscTopNRow[]>;
-interface GscDailyRow {
-  date: number;
-  clicks: number;
-  impressions: number;
-  sum_position: number;
-  anonymizedImpressionsPct: number;
-}
-declare function fetchGscDaily(opts: {
-  client: GoogleSearchConsoleClient;
-  siteUrl: string;
-  range: GscRange;
-  /** GSC search corpus; callers default API-boundary omissions to web. */
-  searchType?: SearchType;
-}): Promise<GscDailyRow[]>;
-interface GscApiQuerySourceOptions {
-  client: GoogleSearchConsoleClient;
-  siteUrl: string;
-}
-declare function createGscApiQuerySource(options: GscApiQuerySourceOptions): AnalysisQuerySource;
-interface GscApiRow {
-  keys: string[];
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-interface SyncSliceDomainFilter {
-  /**
-   * Domain (eTLD+1 + subdomain) to scope the slice to — matches both
-   *  `www.` and bare variants. Strip the protocol; the regex is built here.
-   */
-  domain?: string;
-}
-interface SyncSliceDimensionFilter {
-  dimension: 'page' | 'query' | 'country' | 'device' | 'searchAppearance';
-  operator?: 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
-  expression: string;
-}
-interface RunGscSyncSliceOptions {
-  client: GoogleSearchConsoleClient;
-  siteUrl: string;
-  /** One of the engine sync-fan tables. Drives the dimension list. */
-  table: 'pages' | 'queries' | 'countries' | 'dates' | 'page_queries' | 'search_appearance' | 'search_appearance_pages' | 'search_appearance_queries' | 'search_appearance_page_queries' | 'hourly_pages';
-  startDate: string;
-  endDate: string;
-  domainFilter?: SyncSliceDomainFilter | null;
-  /** Additional AND filters, e.g. `searchAppearance = AMP_BLUE_LINK`. */
-  dimensionFilters?: SyncSliceDimensionFilter[];
-  /**
-   * Override the dimension list for this slice. Defaults to
-   *  `DIMENSIONS_BY_TABLE[table]`. Hosts that need bespoke groupings (e.g.
-   *  hourly Discover variants) supply this directly.
-   */
-  dimensions?: string[];
-  /**
-   * GSC `dataState` for the query. Defaults to `'all'`. Use `'hourly_all'`
-   *  for hourly Discover slices.
-   */
-  dataState?: GscDataState;
-  /**
-   * Invoked per GSC API page with the rows fetched. Return a promise; the
-   *  loop awaits it before paging further. Throw a durable error to abort the
-   *  slice. A thrown AbortError / timeout stops the loop and returns retry
-   *  state at the current cursor so the continuation re-processes this page.
-   */
-  onBatch: (rows: GscApiRow[]) => Promise<void>;
-  initialStartRow?: number;
-  /**
-   * Max GSC API pages per call. `Infinity` for unbounded; hosts cap this
-   *  based on path (D1 vs R2) and table.
-   */
-  maxPages?: number;
-  /** GSC page size. 500 is the D1-safe default; 10k is the R2 path. */
-  rowLimit?: number;
-  /**
-   * Soft CPU budget for the loop itself. Returns `hasMore` when crossed so
-   *  the continuation resumes from `nextStartRow`.
-   */
-  cpuBudgetMs?: number;
-  searchType?: SearchType$1;
-  /** Invoked once per successful GSC API page. Hosts wire telemetry here. */
-  onPage?: (info: {
-    searchType: SearchType$1;
-    rowsThisPage: number;
-  }) => void;
-}
-interface RunGscSyncSliceResult {
-  totalRows: number;
-  hasMore: boolean;
-  nextStartRow: number;
-  /**
-   * Metadata from the LAST GSC API page seen during this slice run. When
-   *  `dataState='hourly_all'` and grouped by `hour`, this surfaces
-   *  `first_incomplete_hour` so hosts can watermark hourly progress.
-   */
-  metadata?: GscSearchAnalyticsMetadata;
-}
-type SearchAppearanceContextGrain = 'page' | 'query' | 'page_query';
-type SearchAppearanceContextTable = 'search_appearance_pages' | 'search_appearance_queries' | 'search_appearance_page_queries';
-interface RunGscSearchAppearanceContextSliceOptions {
-  client: GoogleSearchConsoleClient;
-  siteUrl: string;
-  startDate: string;
-  endDate: string;
-  domainFilter?: SyncSliceDomainFilter | null;
-  /** Use a known appearance list to skip discovery. */
-  appearances?: string[];
-  /** Context grain to fetch for every discovered appearance. Defaults to page_query. */
-  grain?: SearchAppearanceContextGrain;
-  /** Context table to fetch. Overrides `grain` when provided. */
-  table?: SearchAppearanceContextTable;
-  dataState?: GscDataState;
-  rowLimit?: number;
-  maxPages?: number;
-  cpuBudgetMs?: number;
-  searchType?: SearchType$1;
-  onTotalBatch?: (rows: GscApiRow[]) => Promise<void>;
-  onContextBatch: (batch: {
-    searchAppearance: string;
-    table: SearchAppearanceContextTable;
-    rows: GscApiRow[];
-  }) => Promise<void>;
-  onPage?: (info: {
-    searchType: SearchType$1;
-    rowsThisPage: number;
-  }) => void;
-  continuation?: SearchAppearanceContinuation;
-}
-type SearchAppearanceContinuation = {
-  phase: 'discovery';
-  appearances: string[];
-  nextStartRow: number;
-} | {
-  phase: 'context';
-  appearances: string[];
-  appearanceIndex: number;
-  nextStartRow: number;
-};
-interface RunGscSearchAppearanceContextSliceResult {
-  appearances: string[];
-  totalRows: number;
-  hasMore: boolean;
-  continuation?: SearchAppearanceContinuation;
-}
-declare function runGscSyncSlice(opts: RunGscSyncSliceOptions): Promise<RunGscSyncSliceResult>;
-/**
- * Implements GSC's required two-step search-appearance flow:
- * 1. group by `searchAppearance` alone to discover available appearances;
- * 2. for each appearance, filter by it and fetch page/query/date context.
- */
-declare function runGscSearchAppearanceContextSlice(opts: RunGscSearchAppearanceContextSliceOptions): Promise<RunGscSearchAppearanceContextSliceResult>;
+import { CreateLiveGscSourceOptions, canProxyToGsc, createLiveGscSource } from "./live.mjs";
+import { FetchTopNOptions, GscDailyRow, GscRange, GscTopNRow, fetchGscDaily, fetchGscTopN } from "./rollup-synth.mjs";
+import { GscApiQuerySourceOptions, createGscApiQuerySource } from "./source.mjs";
+import { GscApiRow, RunGscSearchAppearanceContextSliceOptions, RunGscSearchAppearanceContextSliceResult, RunGscSyncSliceOptions, RunGscSyncSliceResult, SearchAppearanceContextGrain, SearchAppearanceContextTable, SyncSliceDimensionFilter, SyncSliceDomainFilter, runGscSearchAppearanceContextSlice, runGscSyncSlice } from "./sync-slice.mjs";
 export { type CreateLiveGscSourceOptions, type FetchTopNOptions, type GscApiQuerySourceOptions, type GscApiRow, type GscDailyRow, type GscRange, type GscTopNRow, type RunGscSearchAppearanceContextSliceOptions, type RunGscSearchAppearanceContextSliceResult, type RunGscSyncSliceOptions, type RunGscSyncSliceResult, type SearchAppearanceContextGrain, type SearchAppearanceContextTable, type SyncSliceDimensionFilter, type SyncSliceDomainFilter, canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, runGscSearchAppearanceContextSlice, runGscSyncSlice };