@gscdump/sdk 1.0.2 → 1.0.4

package/README.md

@@ -34,6 +34,12 @@ The root `createPartnerClient` export remains only for operations still in the
 compatibility inventory. Do not use it for an operation already available from
 `@gscdump/sdk/v1`.
 
+The root is also a compatibility aggregate for the pure helper modules. New
+code should use the focused subpaths, including `period`, `period-presets`,
+`site-triage`, `site-baseline`, `search-console-stage`, `indexing-issues`,
+`analytics`, `partner`, `partner-errors`, `lifecycle`, `webhook`, and
+`gsc-console-url`.
+
 For example, a typed hosted report query is:
 
 ```ts
@@ -97,7 +103,7 @@ signature, and normalize event names. gscdump.com owns webhook production and
 delivery.
 
 ```ts
-import { parseWebhookPayload } from '@gscdump/sdk'
+import { parseWebhookPayload } from '@gscdump/sdk/webhook'
 
 const envelope = await parseWebhookPayload(rawJson, {
   secret: webhookSecret,

package/dist/_chunks/errors.d.mts

@@ -0,0 +1,22 @@
+type PartnerErrorKind = 'auth' | 'rate-limit' | 'provisioning' | 'permission' | 'network' | 'validation' | 'not-found' | 'server' | 'unknown';
+interface PartnerErrorInfo {
+  kind: PartnerErrorKind;
+  statusCode?: number;
+  message: string;
+  data?: unknown;
+}
+declare class PartnerApiError extends Error {
+  readonly kind: PartnerErrorKind;
+  readonly statusCode?: number;
+  readonly data?: unknown;
+  constructor(info: PartnerErrorInfo);
+}
+declare function toPartnerError(error: unknown): PartnerApiError;
+/**
+ * Re-raise a modelled `PartnerApiError` as itself. The error variant of every
+ * `*Result` core already IS the throwable `PartnerApiError`, so the throwing
+ * wrappers preserve the exact identity/message existing call sites and tests
+ * assert (`rejects.toThrow(PartnerApiError)`, `toThrow('Invalid webhook signature')`).
+ */
+declare function partnerErrorToException(error: PartnerApiError): PartnerApiError;
+export { PartnerApiError, PartnerErrorInfo, PartnerErrorKind, partnerErrorToException, toPartnerError };

package/dist/_chunks/request.d.mts

@@ -0,0 +1,25 @@
+import { PartnerApiError } from "./errors.mjs";
+import { Result } from "gscdump/result";
+import { ZodTypeAny } from "zod";
+type HostedFetch = <T = unknown>(request: string, options?: HostedFetchOptions) => Promise<T>;
+type HostedHeaders = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+interface HostedFetchOptions {
+  method?: string;
+  headers?: HeadersInit;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  /** Opt into in-flight de-dupe for safe read-style POST requests. */
+  dedupe?: boolean;
+  [key: string]: unknown;
+}
+interface HostedClientOptions {
+  apiBase?: string;
+  fetch?: HostedFetch;
+  headers?: HostedHeaders;
+  validate?: boolean | 'request' | 'response';
+  /** Coalesce concurrent identical GET/HEAD requests within this client instance. */
+  dedupe?: boolean;
+  /** Optional shared in-flight map for de-duping across related client instances. */
+  dedupeScope?: Map<string, Promise<Result<unknown, PartnerApiError>>>;
+}
+export { HostedClientOptions, HostedFetch, HostedFetchOptions, HostedHeaders };

package/dist/_chunks/request.mjs

@@ -0,0 +1,84 @@
+import { partnerErrorToException, toPartnerError } from "../errors.mjs";
+import { err, ok, unwrapResult } from "gscdump/result";
+import { ofetch } from "ofetch";
+const TRAILING_SLASH_RE = /\/+$/;
+const LEADING_SLASH_RE = /^\/+/;
+function trimApiBase(apiBase, fallback) {
+	return (apiBase ?? fallback).replace(TRAILING_SLASH_RE, "");
+}
+function buildPath(apiBase, path) {
+	if (!apiBase) return path.startsWith("/") ? path : `/${path}`;
+	return `${apiBase}/${path.replace(LEADING_SLASH_RE, "")}`;
+}
+function mergeHeaders(base, extra) {
+	const headers = new Headers(base);
+	if (extra) for (const [key, value] of new Headers(extra).entries()) headers.set(key, value);
+	return headers;
+}
+async function resolveHeaders(options) {
+	const resolved = typeof options.headers === "function" ? await options.headers() : options.headers;
+	if (!options.apiKey) return resolved;
+	return mergeHeaders(resolved, { "x-api-key": options.apiKey });
+}
+function shouldValidate(options, phase) {
+	return options.validate === true || options.validate === phase;
+}
+function parseWith(schema, value) {
+	return schema ? schema.parse(value) : value;
+}
+function stableJson(value) {
+	if (value == null || typeof value !== "object") return JSON.stringify(value) ?? "undefined";
+	if (Array.isArray(value)) return `[${value.map((item) => item === void 0 ? "undefined" : stableJson(item)).join(",")}]`;
+	return `{${Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+function headersKey(headers) {
+	return [...headers.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => `${key}:${value}`).join("\n");
+}
+function isDedupeable(init) {
+	if ("signal" in init && init.signal) return false;
+	const method = (init.method ?? "GET").toUpperCase();
+	return method === "GET" || method === "HEAD" || init.dedupe === true;
+}
+function createHostedRequester(options, defaults) {
+	const fetchImpl = options.fetch ?? ofetch;
+	const apiBase = trimApiBase(options.apiBase, defaults.apiBase);
+	const dedupe = options.dedupe !== false;
+	const inflight = options.dedupeScope ?? /* @__PURE__ */ new Map();
+	async function requestResult(path, init = {}, responseSchema) {
+		const { dedupe: _dedupe, ...fetchInit } = init;
+		const headers = mergeHeaders(await resolveHeaders(options), init.headers);
+		const fullPath = buildPath(apiBase, path);
+		const dedupeKey = dedupe && isDedupeable(init) ? `${(init.method ?? "GET").toUpperCase()} ${fullPath}\nq=${stableJson(init.query)}\nb=${stableJson(init.body)}\nh=${headersKey(headers)}` : null;
+		if (dedupeKey) {
+			const existing = inflight.get(dedupeKey);
+			if (existing) return existing;
+		}
+		const run = (async () => {
+			try {
+				const out = await fetchImpl(fullPath, {
+					...fetchInit,
+					headers
+				});
+				return ok(shouldValidate(options, "response") ? parseWith(responseSchema, out) : out);
+			} catch (error) {
+				return err(toPartnerError(error));
+			}
+		})();
+		if (dedupeKey) {
+			inflight.set(dedupeKey, run);
+			run.finally(() => {
+				if (inflight.get(dedupeKey) === run) inflight.delete(dedupeKey);
+			});
+		}
+		return run;
+	}
+	async function request(path, init = {}, responseSchema) {
+		return unwrapResult(await requestResult(path, init, responseSchema), partnerErrorToException);
+	}
+	return {
+		request,
+		requestResult,
+		shouldValidate: (phase) => shouldValidate(options, phase)
+	};
+}
+export { createHostedRequester };

package/dist/_chunks/search-console-signals.mjs

@@ -0,0 +1,9 @@
+function formatSearchConsoleCount(value) {
+	return new Intl.NumberFormat("en").format(Math.max(0, Math.round(value)));
+}
+function countSearchConsoleIssues(issues, ...types) {
+	if (!issues?.length) return 0;
+	const wanted = new Set(types);
+	return issues.reduce((sum, issue) => sum + (wanted.has(issue.type) ? issue.count : 0), 0);
+}
+export { countSearchConsoleIssues, formatSearchConsoleCount };

package/dist/analytics-client.d.mts

@@ -0,0 +1,53 @@
+import { AnalysisSourcesOptions, SearchTypeOptions, SourceRangeOptions } from "./hosted-query.mjs";
+import { HostedClientOptions, HostedFetch, HostedFetchOptions, HostedHeaders } from "./_chunks/request.mjs";
+import { AnalysisSourcesResponse, BackfillRange, BackfillResponse, BulkFileResolutionRequest, BulkFileResolutionResponse, CountriesResponse, IndexingDiagnostics, IndexingDiagnosticsParams, IndexingInspectRateLimited, IndexingInspectRequest, IndexingInspectResponse, IndexingUrlStatus, IndexingUrlsResponse, InspectionHistoryResponse, InspectionIndex, QueryDimSourceResponse, RollupEnvelope, SearchAppearanceResponse, SiteListItem, SitemapChangesResponse, SitemapHistoryResponse, SitemapIndex, SourceInfoOptions, SourceInfoResponse, WhoamiResponse } from "@gscdump/contracts";
+type AnalyticsFetch = HostedFetch;
+type AnalyticsHeaders = HostedHeaders;
+type AnalyticsFetchOptions = HostedFetchOptions;
+interface AnalyticsClientOptions extends HostedClientOptions {
+  apiBase?: string;
+  fetch?: AnalyticsFetch;
+  headers?: AnalyticsHeaders;
+  validate?: boolean | 'request' | 'response';
+}
+/** Hosted analytics transport exposed by `@gscdump/sdk`. */
+interface AnalyticsClient {
+  whoami: () => Promise<WhoamiResponse>;
+  listSites: () => Promise<SiteListItem[]>;
+  getBulkSources: (params: BulkFileResolutionRequest) => Promise<BulkFileResolutionResponse>;
+  getSourceInfo: (siteId: string, options?: SourceInfoOptions) => Promise<SourceInfoResponse>;
+  getAnalysisSources: (siteId: string, tables?: string[] | string | AnalysisSourcesOptions, options?: SearchTypeOptions & SourceRangeOptions) => Promise<AnalysisSourcesResponse>;
+  getQueryDimSource: (siteId: string) => Promise<QueryDimSourceResponse>;
+  analyze: <T = unknown>(siteId: string, params: unknown) => Promise<T>;
+  getRollup: <T = unknown>(siteId: string, rollupId: string, params?: {
+    start?: string;
+    end?: string;
+  }) => Promise<RollupEnvelope<T>>;
+  requestBackfill: (siteId: string, range: BackfillRange) => Promise<BackfillResponse>;
+  getSitemaps: (siteId: string) => Promise<SitemapIndex>;
+  getSitemapHistory: (siteId: string, hash: string) => Promise<SitemapHistoryResponse>;
+  getSitemapChanges: (siteId: string, params?: {
+    days?: number;
+  }) => Promise<SitemapChangesResponse>;
+  getInspections: (siteId: string) => Promise<InspectionIndex>;
+  getInspectionHistory: (siteId: string, hash: string) => Promise<InspectionHistoryResponse>;
+  getIndexingUrls: (siteId: string, params?: {
+    limit?: number;
+    offset?: number;
+    status?: IndexingUrlStatus;
+    issue?: string;
+    search?: string;
+  }) => Promise<IndexingUrlsResponse>;
+  getIndexingDiagnostics: (siteId: string, params?: IndexingDiagnosticsParams) => Promise<IndexingDiagnostics>;
+  requestIndexingInspect: (siteId: string, body: IndexingInspectRequest) => Promise<IndexingInspectResponse | IndexingInspectRateLimited>;
+  getCountries: (siteId: string, range: {
+    start: string;
+    end: string;
+  }) => Promise<CountriesResponse>;
+  getSearchAppearance: (siteId: string, range: {
+    start: string;
+    end: string;
+  }) => Promise<SearchAppearanceResponse>;
+}
+declare function createAnalyticsClient(options?: AnalyticsClientOptions): AnalyticsClient;
+export { AnalyticsClient, AnalyticsClientOptions, AnalyticsFetch, AnalyticsFetchOptions, AnalyticsHeaders, createAnalyticsClient };

package/dist/analytics-client.mjs

@@ -0,0 +1,128 @@
+import { indexingDiagnosticsQuery, indexingUrlsQuery, sourceInfoQuery, tablesQuery, withDefaultSearchType } from "./hosted-query.mjs";
+import { createHostedRequester } from "./_chunks/request.mjs";
+import { analyticsEndpoints } from "@gscdump/contracts/analytics";
+function createAnalyticsClient(options = {}) {
+	const { request, shouldValidate } = createHostedRequester(options, { apiBase: "" });
+	return {
+		whoami() {
+			const endpoint = analyticsEndpoints.whoami;
+			return request(endpoint.path, { method: endpoint.method }, endpoint.response);
+		},
+		listSites() {
+			const endpoint = analyticsEndpoints.listSites;
+			return request(endpoint.path, { method: endpoint.method }, endpoint.response);
+		},
+		getBulkSources(params) {
+			const endpoint = analyticsEndpoints.getBulkSources;
+			const { siteIds, tables, ...options } = params;
+			const query = tablesQuery(tables, options);
+			if (siteIds?.length) query.siteIds = [...new Set(siteIds.filter(Boolean))].join(",");
+			return request(endpoint.path, {
+				method: endpoint.method,
+				query
+			}, endpoint.response);
+		},
+		getSourceInfo(siteId, options) {
+			const endpoint = analyticsEndpoints.getSourceInfo;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				query: sourceInfoQuery(options)
+			}, endpoint.response);
+		},
+		getAnalysisSources(siteId, tables, options) {
+			const endpoint = analyticsEndpoints.getAnalysisSources;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				query: tablesQuery(tables, options)
+			}, endpoint.response);
+		},
+		getQueryDimSource(siteId) {
+			const endpoint = analyticsEndpoints.getQueryDimSource;
+			return request(endpoint.path(siteId), { method: endpoint.method }, endpoint.response);
+		},
+		analyze(siteId, params) {
+			const endpoint = analyticsEndpoints.analyze;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				body: withDefaultSearchType(params),
+				dedupe: true
+			});
+		},
+		getRollup(siteId, rollupId, params) {
+			const endpoint = analyticsEndpoints.getRollup;
+			return request(endpoint.path(siteId, rollupId), {
+				method: endpoint.method,
+				query: params
+			}, endpoint.response);
+		},
+		requestBackfill(siteId, range) {
+			const endpoint = analyticsEndpoints.requestBackfill;
+			const body = shouldValidate("request") ? endpoint.body.parse(range) : range;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				body
+			}, endpoint.response);
+		},
+		getSitemaps(siteId) {
+			const endpoint = analyticsEndpoints.getSitemaps;
+			return request(endpoint.path(siteId), { method: endpoint.method }, endpoint.response);
+		},
+		getSitemapHistory(siteId, hash) {
+			const endpoint = analyticsEndpoints.getSitemapHistory;
+			return request(endpoint.path(siteId, hash), { method: endpoint.method }, endpoint.response);
+		},
+		getSitemapChanges(siteId, params = {}) {
+			const endpoint = analyticsEndpoints.getSitemapChanges;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				query: params
+			}, endpoint.response);
+		},
+		getInspections(siteId) {
+			const endpoint = analyticsEndpoints.getInspections;
+			return request(endpoint.path(siteId), { method: endpoint.method }, endpoint.response);
+		},
+		getInspectionHistory(siteId, hash) {
+			const endpoint = analyticsEndpoints.getInspectionHistory;
+			return request(endpoint.path(siteId, hash), { method: endpoint.method }, endpoint.response);
+		},
+		getIndexingUrls(siteId, params = {}) {
+			const endpoint = analyticsEndpoints.getIndexingUrls;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				query: indexingUrlsQuery(params)
+			}, endpoint.response);
+		},
+		getIndexingDiagnostics(siteId, params = {}) {
+			const endpoint = analyticsEndpoints.getIndexingDiagnostics;
+			const parsed = shouldValidate("request") ? endpoint.query.parse(params) : params;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				query: indexingDiagnosticsQuery(parsed)
+			}, endpoint.response);
+		},
+		requestIndexingInspect(siteId, body) {
+			const endpoint = analyticsEndpoints.requestIndexingInspect;
+			const parsed = shouldValidate("request") ? endpoint.body.parse(body) : body;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				body: parsed
+			}, endpoint.response);
+		},
+		getCountries(siteId, range) {
+			const endpoint = analyticsEndpoints.getCountries;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				query: range
+			}, endpoint.response);
+		},
+		getSearchAppearance(siteId, range) {
+			const endpoint = analyticsEndpoints.getSearchAppearance;
+			return request(endpoint.path(siteId), {
+				method: endpoint.method,
+				query: range
+			}, endpoint.response);
+		}
+	};
+}
+export { createAnalyticsClient };

package/dist/analyzer-defs.d.mts

@@ -0,0 +1,73 @@
+import { ActionSource } from "@gscdump/analysis";
+import { AnalysisTool } from "@gscdump/engine/analysis-types";
+type GscAnalyzerKind = 'analyzer' | 'semantic' | 'action';
+type GscAnalyzerAccent = 'primary' | 'warning' | 'success' | 'error' | 'neutral';
+interface GscAnalyzerInsightCard {
+  icon: string;
+  accent: GscAnalyzerAccent;
+  description: string;
+  summarize: (res: {
+    results: unknown[];
+    meta: Record<string, unknown>;
+  }) => {
+    headline: string;
+    tagline: string;
+  };
+}
+interface GscAnalyzerStatTile {
+  label: string;
+  value: string | number;
+  /** Optional CSS color for the value (e.g. improved/worsened in change-points). */
+  valueColor?: string;
+}
+interface GscAnalyzerPanelResult {
+  results: unknown[];
+  meta: Record<string, unknown>;
+  queryMs?: number | null;
+}
+interface GscAnalyzerPanelSpec<TComponent = unknown> {
+  /**
+   * Body component. Receives `{ rows, meta, range }` as props. Lazy-import
+   * to preserve route-level codesplitting.
+   *
+   * Typed `unknown` in the SDK; consumers can narrow via generic
+   * (`GscAnalyzerDefinition<VueComponent>`).
+   */
+  component: TComponent;
+  /** Project a result to the header stat tiles. Empty array = no tiles. */
+  summarize?: (res: GscAnalyzerPanelResult) => GscAnalyzerStatTile[];
+  /** Italic footer caption explaining the underlying method. */
+  caption?: string;
+  /**
+   * When true, the shell skips its loading/error/empty gating and renders
+   * the body component immediately (pipeline panels: action priority, content gap).
+   */
+  ownsLifecycle?: boolean;
+}
+interface GscAnalyzerCapabilities<TComponent = unknown> {
+  /** Opt into the `/insights` curated grid by providing a card config. */
+  insightCard?: GscAnalyzerInsightCard;
+  /** Opt into `useActionPriority`. The value is the typed `ActionSource` slug. */
+  actionPriority?: ActionSource;
+  /**
+   * Opt into the unified `/analyze` panel renderer. Without this, the tab
+   * falls back to the generic table renderer.
+   */
+  panel?: GscAnalyzerPanelSpec<TComponent>;
+}
+type GscAnalyzerCapability = keyof GscAnalyzerCapabilities;
+interface GscAnalyzerDefinition<TComponent = unknown> {
+  /** Stable analyzer id. Must match an `AnalysisTool` slug for built-in analyzers. */
+  id: AnalysisTool | (string & {});
+  label: string;
+  kind: GscAnalyzerKind;
+  /** Reads the per-query table; sums silently drop GSC-anonymized impressions. */
+  isQueryGrained?: boolean;
+  /** Capability opt-ins. Each key gates a downstream consumer. */
+  capabilities?: GscAnalyzerCapabilities<TComponent>;
+}
+type GscAnalyzerDefinitionWithCapability<K extends GscAnalyzerCapability, TComponent = unknown> = GscAnalyzerDefinition<TComponent> & {
+  capabilities: { [P in K]: NonNullable<GscAnalyzerCapabilities<TComponent>[P]>; };
+};
+declare function defineGscAnalyzer<TComponent = unknown>(def: GscAnalyzerDefinition<TComponent>): GscAnalyzerDefinition<TComponent>;
+export { GscAnalyzerAccent, GscAnalyzerCapabilities, GscAnalyzerCapability, GscAnalyzerDefinition, GscAnalyzerDefinitionWithCapability, GscAnalyzerInsightCard, GscAnalyzerKind, GscAnalyzerPanelResult, GscAnalyzerPanelSpec, GscAnalyzerStatTile, defineGscAnalyzer };

package/dist/analyzer-defs.mjs

@@ -0,0 +1,4 @@
+function defineGscAnalyzer(def) {
+	return def;
+}
+export { defineGscAnalyzer };

package/dist/anonymization.d.mts

@@ -0,0 +1,6 @@
+interface DailyAnonInput {
+  impressions: number;
+  anonymizedImpressionsPct: number;
+}
+declare function weightedAnonPct(days: readonly DailyAnonInput[] | null | undefined, window?: number): number | null;
+export { DailyAnonInput, weightedAnonPct };

package/dist/anonymization.mjs

@@ -0,0 +1,12 @@
+function weightedAnonPct(days, window = 28) {
+	if (!days?.length) return null;
+	const trailing = days.slice(-window);
+	let totalImpressions = 0;
+	let weighted = 0;
+	for (const d of trailing) {
+		totalImpressions += d.impressions;
+		weighted += d.impressions * d.anonymizedImpressionsPct;
+	}
+	return totalImpressions > 0 ? weighted / totalImpressions : null;
+}
+export { weightedAnonPct };

package/dist/archetype-compile.d.mts

@@ -0,0 +1,48 @@
+import { BuilderState } from "gscdump/query";
+import { ArchetypeQuery, GscSearchType, WireDateRange } from "@gscdump/contracts";
+/**
+ * Extract the `{ start, end }` date window from a builder-state filter in
+ * either accepted format (SDK-branded or partner wire). Returns `null` when no
+ * complete range is present.
+ */
+declare function extractWireDateRange(filter: unknown): WireDateRange | null;
+interface BuilderStateToArchetypeOptions {
+  searchType?: GscSearchType;
+  compareRange?: WireDateRange;
+}
+/**
+ * Translate a `BuilderState` into the best-fit `ArchetypeQuery`, or `null`
+ * when the shape can't be expressed (the caller keeps its legacy path — this
+ * function never throws).
+ *
+ * Supported shapes (5 of the archetypes — the others are either caller-driven
+ * builders never reached via a BuilderState, `arbitrary-sql`, or
+ * `aux-cloud-only`):
+ *  - `dimensions: ['date']`, no entity filter                → site-daily-timeseries
+ *  - `dimensions: ['date']`, one page/query/queryCanonical
+ *    equality                                                → entity-daily-timeseries
+ *  - `dimensions: ['date', X]`                               → multi-series-stacked-daily
+ *  - `dimensions: [X]` (non-date)                            → top-n-breakdown (extra
+ *    equality filters on OTHER dimensions become `facets`)
+ *  - `dimensions: ['page','query']` (either order)           → two-dimension-detail
+ *
+ * Everything else — 0 or 3+ dimensions, no date range, an OR group, a
+ * non-equality predicate the target SQL builder can't apply, a
+ * `two-dimension-detail` pair that isn't exactly {page, query} (the SQL is
+ * hardcoded to `url, query` regardless of which two dims were requested) —
+ * returns `null`.
+ */
+declare function builderStateToArchetype(siteId: string, state: BuilderState, opts?: BuilderStateToArchetypeOptions): ArchetypeQuery | null;
+/**
+ * Archetypes a hosted seam's execution wrapper can safely serve end-to-end
+ * today (rows + an ACCURATE `totalCount`/`totals`, matching the legacy
+ * `R2QueryResult` contract). `builderStateToArchetype` above can produce a
+ * `two-dimension-detail` query, but `TwoDimensionDetailQuery`/
+ * `buildTwoDimensionDetail` support neither `offset` nor `includeTotal` —
+ * there is no way to get an exact grand total or paginate past page 1 through
+ * the dispatcher yet, so seam wrappers decline it (same as a compile miss)
+ * rather than serve a wrong `totalCount`. Revisit once the contract grows
+ * those fields.
+ */
+declare function archetypeSeamSupportsQuery(query: ArchetypeQuery): boolean;
+export { BuilderStateToArchetypeOptions, archetypeSeamSupportsQuery, builderStateToArchetype, extractWireDateRange };

package/dist/archetype-compile.mjs

@@ -0,0 +1,124 @@
+import { entityDailyTimeseries, multiSeriesStackedDaily, siteDailyTimeseries, topNBreakdown, twoDimensionDetail } from "@gscdump/contracts/archetypes";
+import { extractDateRange, normalizeFilter } from "gscdump/query";
+const KNOWN_DIMENSIONS = /* @__PURE__ */ new Set([
+	"query",
+	"queryCanonical",
+	"page",
+	"country",
+	"device",
+	"searchAppearance",
+	"date",
+	"hour"
+]);
+const DATE_RANGE_OPERATORS = /* @__PURE__ */ new Set([
+	"between",
+	"gte",
+	"gt",
+	"lte",
+	"lt"
+]);
+const EQUALITY_OPERATORS = /* @__PURE__ */ new Set(["equals", "eq"]);
+const ENTITY_DIMENSIONS = [
+	"page",
+	"query",
+	"queryCanonical"
+];
+function collectEqualityMatches(filter, out) {
+	if (!filter) return true;
+	if (filter._groupType === "or") return false;
+	for (const f of filter._filters) {
+		if (f.dimension === "date") {
+			if (!DATE_RANGE_OPERATORS.has(f.operator)) return false;
+			continue;
+		}
+		if (!EQUALITY_OPERATORS.has(f.operator) || !KNOWN_DIMENSIONS.has(f.dimension)) return false;
+		const dim = f.dimension;
+		const existing = out.get(dim);
+		if (existing !== void 0 && existing !== f.expression) return false;
+		out.set(dim, f.expression);
+	}
+	for (const nested of filter._nestedGroups ?? []) if (!collectEqualityMatches(nested, out)) return false;
+	return true;
+}
+function extractWireDateRange(filter) {
+	const { startDate, endDate } = extractDateRange(filter);
+	return startDate && endDate ? {
+		start: startDate,
+		end: endDate
+	} : null;
+}
+function builderStateToArchetype(siteId, state, opts = {}) {
+	const range = extractWireDateRange(state.filter);
+	if (!range) return null;
+	const matches = /* @__PURE__ */ new Map();
+	if (!collectEqualityMatches(normalizeFilter(state.filter), matches)) return null;
+	const dims = state.dimensions ?? [];
+	if (dims.some((d) => !KNOWN_DIMENSIONS.has(d))) return null;
+	if (dims.includes("hour") || dims.includes("searchAppearance")) return null;
+	const searchType = opts.searchType;
+	const cmp = opts.compareRange;
+	const order = state.orderBy ? {
+		metric: state.orderBy.column,
+		dir: state.orderBy.dir
+	} : void 0;
+	if (dims.length === 1 && dims[0] === "date") {
+		const entityDims = ENTITY_DIMENSIONS.filter((c) => matches.has(c));
+		if (entityDims.length > 1) return null;
+		if (entityDims.length === 1) {
+			const dim = entityDims[0];
+			if (matches.size > 1) return null;
+			return entityDailyTimeseries(siteId, range, {
+				dimension: dim,
+				value: matches.get(dim)
+			}, {
+				searchType,
+				compareRange: cmp
+			});
+		}
+		if (matches.size > 0) return null;
+		return siteDailyTimeseries(siteId, range, {
+			searchType,
+			compareRange: cmp
+		});
+	}
+	if (dims.length === 2 && dims.includes("date")) {
+		if (matches.size > 0) return null;
+		return multiSeriesStackedDaily(siteId, range, dims.find((d) => d !== "date"), {
+			searchType,
+			compareRange: cmp
+		});
+	}
+	if (dims.length === 1 && dims[0] !== "date") {
+		const primary = dims[0];
+		if (matches.has(primary)) return null;
+		const facets = [...matches.entries()].map(([column, value]) => ({
+			column,
+			op: "eq",
+			value
+		}));
+		return topNBreakdown(siteId, range, primary, {
+			searchType,
+			compareRange: cmp,
+			...order ? { orderBy: order } : {},
+			limit: state.rowLimit ?? 50,
+			...state.startRow ? { offset: state.startRow } : {},
+			...facets.length ? { facets } : {}
+		});
+	}
+	if (dims.length === 2 && !dims.includes("date")) {
+		const set = new Set(dims);
+		if (!set.has("page") || !set.has("query")) return null;
+		if (matches.size > 0) return null;
+		return twoDimensionDetail(siteId, range, {
+			searchType,
+			compareRange: cmp,
+			...order ? { orderBy: order } : {},
+			...state.rowLimit ? { limit: state.rowLimit } : {}
+		});
+	}
+	return null;
+}
+function archetypeSeamSupportsQuery(query) {
+	return query.archetype !== "two-dimension-detail";
+}
+export { archetypeSeamSupportsQuery, builderStateToArchetype, extractWireDateRange };