@gscdump/sdk 1.0.1 → 1.0.3

package/dist/gsc-constants.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Google Search Console data is considered "unstable" for this many days from
+ * today (PST). Rows within the window may still shift as GSC finalizes clicks/
+ * impressions; charts render those points under a dimmed / striped overlay so
+ * users don't misread last-day dips as trends.
+ *
+ * This is the client DISPLAY-latency band, NOT the server lake-membership
+ * boundary. gscdump's `DEFAULT_STABILITY_CUTOFF_DAYS` (= 4) decides which days
+ * live in the Iceberg lake vs the recent overlay; this constant (= 3) only dims
+ * the UI. The display band is intentionally one day SMALLER so that, even at
+ * maximum UTC-vs-PST clock skew, the freshest UI-requested day is lake-resident
+ * (R2-SQL-complete) rather than overlay-only. The two are distinct concepts; do
+ * not unify them to a single value (gscdump plan
+ * `2026-06-24-overlay-canonical-merge-unification.md` W6).
+ */
+declare const GSC_STABLE_LATENCY_DAYS = 3;
+export { GSC_STABLE_LATENCY_DAYS };

package/dist/gsc-constants.mjs

@@ -0,0 +1,2 @@
+const GSC_STABLE_LATENCY_DAYS = 3;
+export { GSC_STABLE_LATENCY_DAYS };

package/dist/gsc-error.d.mts

@@ -0,0 +1,12 @@
+type GscErrorStatus = 'auth-missing' | 'rate-limited' | 'network' | 'error';
+interface GscClassifiedError {
+  status: GscErrorStatus;
+  /** HTTP status code if the error came from a response, otherwise undefined. */
+  code?: number;
+  /** Best-effort human message: server-supplied `message`, then `data.message`, then the error's own message. */
+  message?: string;
+  /** Seconds the server suggested waiting (429/503 retry payloads). */
+  retryAfter?: number;
+}
+declare function classifyGscError(e: unknown): GscClassifiedError;
+export { GscClassifiedError, GscErrorStatus, classifyGscError };

package/dist/gsc-error.mjs

@@ -0,0 +1,42 @@
+function classifyGscError(e) {
+	const code = e?.statusCode ?? e?.status;
+	const message = extractMessage(e);
+	if (code === 401 || code === 403) return {
+		status: "auth-missing",
+		code,
+		message
+	};
+	if (code === 429 || code === 503) {
+		const data = e?.data;
+		const retry = data?.retryAfter ?? data?.retryAfterSeconds;
+		return {
+			status: code === 429 ? "rate-limited" : "network",
+			code,
+			message,
+			retryAfter: typeof retry === "number" ? retry : void 0
+		};
+	}
+	if (code == null && !isAbort(e)) return {
+		status: "network",
+		message
+	};
+	return {
+		status: "error",
+		code,
+		message
+	};
+}
+function extractMessage(e) {
+	if (!e || typeof e !== "object") return void 0;
+	const data = e.data;
+	if (data && typeof data === "object") {
+		const m = data.message ?? data.error;
+		if (typeof m === "string") return m;
+	}
+	const m = e.message;
+	return typeof m === "string" ? m : void 0;
+}
+function isAbort(e) {
+	return e?.name === "AbortError";
+}
+export { classifyGscError };

package/dist/gsc-period-presets.d.mts

@@ -0,0 +1,31 @@
+import { CompareMode, Period } from "./period.mjs";
+type GscColumn = 'clicks' | 'impressions' | 'ctr' | 'position';
+interface GscColumnOption {
+  key: GscColumn;
+  label: string;
+  icon: string;
+  color: string;
+}
+interface PeriodPreset {
+  value: Period;
+  label: string;
+  shortLabel: string;
+  group: 'rolling' | 'calendar';
+}
+declare const PERIOD_PRESETS: PeriodPreset[];
+declare const COMPARE_OPTIONS: {
+  value: CompareMode;
+  label: string;
+  description: string;
+}[];
+declare const GSC_PERIOD_OPTIONS: {
+  label: string;
+  value: Period;
+  longLabel: string;
+}[];
+declare const GSC_PERIOD_OPTIONS_LONG: {
+  label: string;
+  value: Period;
+}[];
+declare const GSC_COLUMN_OPTIONS: GscColumnOption[];
+export { COMPARE_OPTIONS, GSC_COLUMN_OPTIONS, GSC_PERIOD_OPTIONS, GSC_PERIOD_OPTIONS_LONG, GscColumn, GscColumnOption, PERIOD_PRESETS, PeriodPreset };

package/dist/gsc-period-presets.mjs

@@ -0,0 +1,115 @@
+const PERIOD_PRESETS = [
+	{
+		value: "7d",
+		label: "Last 7 days",
+		shortLabel: "7d",
+		group: "rolling"
+	},
+	{
+		value: "28d",
+		label: "Last 28 days",
+		shortLabel: "28d",
+		group: "rolling"
+	},
+	{
+		value: "3m",
+		label: "Last 3 months",
+		shortLabel: "3m",
+		group: "rolling"
+	},
+	{
+		value: "6m",
+		label: "Last 6 months",
+		shortLabel: "6m",
+		group: "rolling"
+	},
+	{
+		value: "12m",
+		label: "Last 12 months",
+		shortLabel: "12m",
+		group: "rolling"
+	},
+	{
+		value: "this-week",
+		label: "This week",
+		shortLabel: "Week",
+		group: "calendar"
+	},
+	{
+		value: "this-month",
+		label: "This month",
+		shortLabel: "Month",
+		group: "calendar"
+	},
+	{
+		value: "last-month",
+		label: "Last month",
+		shortLabel: "Last mo",
+		group: "calendar"
+	},
+	{
+		value: "this-quarter",
+		label: "This quarter",
+		shortLabel: "Qtr",
+		group: "calendar"
+	},
+	{
+		value: "this-year",
+		label: "This year",
+		shortLabel: "Year",
+		group: "calendar"
+	}
+];
+const COMPARE_OPTIONS = [
+	{
+		value: "previous",
+		label: "Previous period",
+		description: "Compare to the period immediately before"
+	},
+	{
+		value: "year",
+		label: "Year over year",
+		description: "Compare to the same period last year"
+	},
+	{
+		value: "none",
+		label: "No comparison",
+		description: "Disable comparison"
+	}
+];
+const GSC_PERIOD_OPTIONS = PERIOD_PRESETS.filter((p) => p.group === "rolling").map((p) => ({
+	label: p.shortLabel,
+	value: p.value,
+	longLabel: p.label
+}));
+const GSC_PERIOD_OPTIONS_LONG = GSC_PERIOD_OPTIONS.map((o) => ({
+	label: o.longLabel,
+	value: o.value
+}));
+const GSC_COLUMN_OPTIONS = [
+	{
+		key: "clicks",
+		label: "Clicks",
+		icon: "i-lucide-mouse-pointer-click",
+		color: "blue"
+	},
+	{
+		key: "impressions",
+		label: "Views",
+		icon: "i-lucide-eye",
+		color: "purple"
+	},
+	{
+		key: "ctr",
+		label: "CTR",
+		icon: "i-lucide-percent",
+		color: "green"
+	},
+	{
+		key: "position",
+		label: "Pos",
+		icon: "i-lucide-hash",
+		color: "orange"
+	}
+];
+export { COMPARE_OPTIONS, GSC_COLUMN_OPTIONS, GSC_PERIOD_OPTIONS, GSC_PERIOD_OPTIONS_LONG, PERIOD_PRESETS };

package/dist/gsc-rows.d.mts

@@ -0,0 +1,54 @@
+interface RawDailyRow {
+  date: string;
+  clicks: number;
+  impressions: number;
+  sum_position?: number;
+  position?: number;
+}
+interface CanonicalDailyRow {
+  date: string;
+  clicks: number;
+  impressions: number;
+  sum_position: number;
+}
+interface GscRowTotals {
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+interface GscDailySummary {
+  daily: CanonicalDailyRow[];
+  totals: GscRowTotals;
+  chartData: Array<{
+    date: string;
+    clicks: number;
+    impressions: number;
+  }>;
+}
+/**
+ * Fill `sum_position` from `(position - 1) * impressions` when the row only
+ * carries `position`. GSC positions are 1-based and 0/absent is a no-data
+ * sentinel — the old `Math.max(1, …)` clamp synthesized rank #1 (sum 0 with
+ * full impression weight) for such rows instead of contributing nothing.
+ */
+declare function coerceRowMetrics<T extends {
+  impressions: number;
+  sum_position?: number;
+  position?: number;
+}>(row: T): T & {
+  sum_position: number;
+};
+/** Sort daily rows by date asc, coerce `sum_position`, reduce totals, derive chartData. */
+declare function summarizeDailyRows(raw: readonly RawDailyRow[]): GscDailySummary;
+/**
+ * Rollup-row position helper. `sum_position` is GSC's average-position sum
+ * across impressions; dividing back out (+1 because GSC is 1-indexed) gives
+ * the impression-weighted average position. Returns 0 when there were no
+ * impressions so the column renders blank rather than NaN.
+ */
+declare function positionFor(r: {
+  impressions: number;
+  sum_position: number;
+}): number;
+export { CanonicalDailyRow, GscDailySummary, GscRowTotals, RawDailyRow, coerceRowMetrics, positionFor, summarizeDailyRows };

package/dist/gsc-rows.mjs

@@ -0,0 +1,48 @@
+function coerceRowMetrics(row) {
+	const position = row.position ?? 0;
+	return {
+		...row,
+		sum_position: row.sum_position ?? (position > 0 ? (position - 1) * row.impressions : 0)
+	};
+}
+function summarizeDailyRows(raw) {
+	const daily = [];
+	for (let index = 0; index < raw.length; index++) {
+		const row = raw[index];
+		const position = row.position ?? 0;
+		const sumPosition = row.sum_position ?? (position > 0 ? (position - 1) * row.impressions : 0);
+		daily.push({
+			date: row.date,
+			clicks: row.clicks,
+			impressions: row.impressions,
+			sum_position: sumPosition
+		});
+	}
+	daily.sort((a, b) => a.date.localeCompare(b.date));
+	let clicks = 0;
+	let impressions = 0;
+	let weightedPosition = 0;
+	for (const row of daily) {
+		clicks += row.clicks;
+		impressions += row.impressions;
+		weightedPosition += row.sum_position;
+	}
+	return {
+		daily,
+		totals: {
+			clicks,
+			impressions,
+			ctr: impressions > 0 ? clicks / impressions : 0,
+			position: impressions > 0 ? weightedPosition / impressions + 1 : 0
+		},
+		chartData: daily.map((d) => ({
+			date: d.date,
+			clicks: d.clicks,
+			impressions: d.impressions
+		}))
+	};
+}
+function positionFor(r) {
+	return r.impressions > 0 ? r.sum_position / r.impressions + 1 : 0;
+}
+export { coerceRowMetrics, positionFor, summarizeDailyRows };

package/dist/hosted-query.d.mts

@@ -0,0 +1,31 @@
+import { BuilderStateWire, DataDetailOptions, DataQueryOptions, GscdumpPageTrendParams, GscdumpQueryTrendParams, IndexingDiagnosticsParams, IndexingUrlsParams, SourceInfoOptions } from "@gscdump/contracts";
+type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+interface SearchTypeOptions {
+  searchType?: GscSearchType;
+}
+interface SourceRangeOptions {
+  start?: string;
+  end?: string;
+  startDate?: string;
+  endDate?: string;
+}
+interface AnalysisSourcesOptions extends SearchTypeOptions, SourceRangeOptions {
+  tables?: string[] | string;
+  maxBytes?: number;
+  maxRows?: number;
+  maxFiles?: number;
+}
+declare const DEFAULT_SEARCH_TYPE: GscSearchType;
+declare function withDefaultSearchType<T extends object>(value: T, searchType?: GscSearchType): T & SearchTypeOptions & Record<string, unknown>;
+declare function withDefaultSearchType<T>(value: T, searchType?: GscSearchType): T;
+declare function searchTypeQuery(searchType?: GscSearchType): Record<string, string>;
+declare function dateRangeOptionsQuery(options: SourceRangeOptions | undefined): Record<string, string>;
+declare function sourceInfoQuery(options: SourceInfoOptions | undefined): Record<string, string>;
+declare function tablesQuery(tablesOrOptions: string[] | string | AnalysisSourcesOptions | undefined, options?: AnalysisSourcesOptions): Record<string, string>;
+declare function dataQuery(state: BuilderStateWire, options?: DataQueryOptions): Record<string, string>;
+declare function dataDetailQuery(state: BuilderStateWire, options?: DataDetailOptions): Record<string, string>;
+declare function indexingUrlsQuery(params?: IndexingUrlsParams): Record<string, string | number>;
+declare function indexingDiagnosticsQuery(params?: IndexingDiagnosticsParams): Record<string, string | number>;
+declare function queryTrendQuery(params: GscdumpQueryTrendParams): Record<string, string>;
+declare function pageTrendQuery(params: GscdumpPageTrendParams): Record<string, string>;
+export { AnalysisSourcesOptions, DEFAULT_SEARCH_TYPE, GscSearchType, SearchTypeOptions, SourceRangeOptions, dataDetailQuery, dataQuery, dateRangeOptionsQuery, indexingDiagnosticsQuery, indexingUrlsQuery, pageTrendQuery, queryTrendQuery, searchTypeQuery, sourceInfoQuery, tablesQuery, withDefaultSearchType };

package/dist/hosted-query.mjs

@@ -0,0 +1,105 @@
+const DEFAULT_SEARCH_TYPE = "web";
+function isAnalysisSourcesOptions(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function withDefaultSearchType(value, searchType) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+	const scoped = value;
+	return {
+		...scoped,
+		searchType: searchType ?? scoped.searchType ?? "web"
+	};
+}
+function searchTypeQuery(searchType) {
+	return { searchType: searchType ?? "web" };
+}
+function stableJson(value) {
+	if (value == null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map((item) => item === void 0 ? "null" : 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 dateRangeOptionsQuery(options) {
+	const query = {};
+	const start = options?.start ?? options?.startDate;
+	const end = options?.end ?? options?.endDate;
+	if (start) query.start = start;
+	if (end) query.end = end;
+	return query;
+}
+function sourceInfoQuery(options) {
+	return {
+		...searchTypeQuery(options?.searchType),
+		...dateRangeOptionsQuery(options)
+	};
+}
+function tablesQuery(tablesOrOptions, options) {
+	const tables = isAnalysisSourcesOptions(tablesOrOptions) ? tablesOrOptions.tables : tablesOrOptions;
+	const source = isAnalysisSourcesOptions(tablesOrOptions) ? tablesOrOptions : options;
+	const query = {
+		...searchTypeQuery(source?.searchType),
+		...dateRangeOptionsQuery(source)
+	};
+	if (tables) query.tables = Array.isArray(tables) ? [...new Set(tables.filter(Boolean))].sort().join(",") : [...new Set(tables.split(",").map((t) => t.trim()).filter(Boolean))].sort().join(",");
+	if (source?.maxBytes != null) query.maxBytes = String(Math.max(1, Math.floor(source.maxBytes)));
+	if (source?.maxRows != null) query.maxRows = String(Math.max(1, Math.floor(source.maxRows)));
+	if (source?.maxFiles != null) query.maxFiles = String(Math.max(1, Math.floor(source.maxFiles)));
+	return query;
+}
+function dataQuery(state, options) {
+	const opts = options;
+	const scoped = withDefaultSearchType(state, opts?.searchType);
+	const query = {
+		q: stableJson(scoped),
+		searchType: scoped.searchType ?? "web"
+	};
+	if (opts?.comparison) query.qc = stableJson(withDefaultSearchType(opts.comparison, scoped.searchType));
+	if (opts?.filter) query.filter = opts.filter;
+	return query;
+}
+function dataDetailQuery(state, options) {
+	const opts = options;
+	const scoped = withDefaultSearchType(state, opts?.searchType);
+	const query = {
+		q: stableJson(scoped),
+		searchType: scoped.searchType ?? "web"
+	};
+	if (opts?.comparison) query.qc = stableJson(withDefaultSearchType(opts.comparison, scoped.searchType));
+	return query;
+}
+function indexingUrlsQuery(params = {}) {
+	const query = {};
+	if (params.limit != null) query.limit = params.limit;
+	if (params.offset != null) query.offset = params.offset;
+	if (params.status) query.status = params.status;
+	if (params.issue) query.issue = params.issue;
+	if (params.search) query.search = params.search;
+	if (params.count === 0 || params.count === false) query.count = 0;
+	return query;
+}
+function indexingDiagnosticsQuery(params = {}) {
+	const query = {};
+	if (params.sampleIssues) query.sampleIssues = Array.isArray(params.sampleIssues) ? [...new Set(params.sampleIssues.map((item) => String(item).trim()).filter(Boolean))].sort().join(",") : params.sampleIssues;
+	if (params.sampleLimit != null) query.sampleLimit = params.sampleLimit;
+	return query;
+}
+function queryTrendQuery(params) {
+	const query = {
+		startDate: params.startDate,
+		endDate: params.endDate,
+		searchType: params.searchType ?? "web"
+	};
+	if (params.prevStartDate) query.prevStartDate = params.prevStartDate;
+	if (params.prevEndDate) query.prevEndDate = params.prevEndDate;
+	return query;
+}
+function pageTrendQuery(params) {
+	const query = {
+		startDate: params.startDate,
+		endDate: params.endDate,
+		searchType: params.searchType ?? "web"
+	};
+	if (params.prevStartDate) query.prevStartDate = params.prevStartDate;
+	if (params.prevEndDate) query.prevEndDate = params.prevEndDate;
+	return query;
+}
+export { DEFAULT_SEARCH_TYPE, dataDetailQuery, dataQuery, dateRangeOptionsQuery, indexingDiagnosticsQuery, indexingUrlsQuery, pageTrendQuery, queryTrendQuery, searchTypeQuery, sourceInfoQuery, tablesQuery, withDefaultSearchType };