@gscdump/analysis 4.5.0 → 4.7.0

package/README.md

@@ -20,7 +20,7 @@ Node.js 22 or newer is required for Node consumers.
 | Subpath | Purpose |
 | --- | --- |
 | `@gscdump/analysis` | Pure Analyzers, browser dispatch, and shared Analyzer contracts |
-| `@gscdump/analysis/registry` | All 29 registered Analyzers, including SQL implementations |
+| `@gscdump/analysis/registry` | All 30 registered Analyzers, including SQL implementations |
 | `@gscdump/analysis/report` | Report registry, `runReport`, and formatting |
 | `@gscdump/analysis/source` | Composite and in-memory Source factories |
 | `@gscdump/analysis/errors` | Typed analysis errors and rendering helpers |
@@ -84,13 +84,13 @@ console.log(result.results)
 
 Install `@gscdump/engine`, `@gscdump/engine-gsc-api`, and `gscdump` for this example.
 
-Twelve Analyzers have row plans:
+Thirteen Analyzers have row plans:
 
 - `brand`, `cannibalization`, `clustering`, `concentration`
 - `data-detail`, `data-query`, `decay`, `movers`
-- `opportunity`, `seasonality`, `striking-distance`, `zero-click`
+- `opportunity`, `seasonality`, `striking-distance`, `trajectory`, `zero-click`
 
-All 29 Analyzers have SQL plans.
+All 30 Analyzers have SQL plans.
 SQL-only Analyzers need a Source that supports their required capabilities.
 
 | Factory | Import path | Input |

package/dist/analyzer/all.mjs

@@ -7,6 +7,7 @@ import { moversAnalyzer } from "../analyzers/movers.mjs";
 import { opportunityAnalyzer } from "../analyzers/opportunity.mjs";
 import { seasonalityAnalyzer } from "../analyzers/seasonality.mjs";
 import { strikingDistanceAnalyzer } from "../analyzers/striking-distance.mjs";
+import { trajectoryAnalyzer } from "../analyzers/trajectory.mjs";
 import { zeroClickAnalyzer } from "../analyzers/zero-click.mjs";
 import { bayesianCtrAnalyzer } from "../analyzers/bayesian-ctr.mjs";
 import { bipartitePagerankAnalyzer } from "../analyzers/bipartite-pagerank.mjs";
@@ -55,6 +56,7 @@ const ALL_ANALYZERS = [
 	stlDecomposeAnalyzer,
 	strikingDistanceAnalyzer,
 	survivalAnalyzer,
+	trajectoryAnalyzer,
 	trendsAnalyzer,
 	zeroClickAnalyzer
 ];

package/dist/analyzers/trajectory.d.mts

@@ -0,0 +1,121 @@
+export interface TrajectoryDay {
+  /** ISO calendar date, `YYYY-MM-DD`. */
+  date: string;
+  clicks: number;
+  impressions: number;
+}
+/**
+ * The input of `analyzeTrajectory`: which days are known, and what they held.
+ */
+export interface TrajectoryRecord {
+  /**
+   * Days that had traffic. A day between the first row and `knownThrough`
+   * with no row is known, and had no traffic.
+   */
+  days: readonly TrajectoryDay[];
+  /**
+   * `YYYY-MM-DD`. The last day whose data is known: the last synced day, or
+   * the requested end when the whole range was fetched. The latest week ends
+   * here. Days after it are unknown, so they are never read as zero. A date
+   * earlier than the last row is ignored, and an invalid one falls back to
+   * the last row with a caveat.
+   */
+  knownThrough: string;
+}
+export interface TrajectoryWindow {
+  startDate: string;
+  endDate: string;
+  clicks: number;
+  impressions: number;
+}
+/** Which metric the peak, the ratio, and the classification read. */
+export type TrajectoryBasis = {
+  _tag: 'impressions';
+  note: string;
+} | {
+  _tag: 'clicks';
+  reason: 'impressions-overcount-window' | 'impressions-clicks-disagree' | 'too-few-impressions';
+  note: string;
+};
+export type TrajectoryCaveat = {
+  _tag: 'impressions-overcount';
+  fromDate: string;
+  throughDate: string;
+  /** True when the impressions peak window sits inside the over-count period. */
+  overlapsPeak: boolean;
+  note: string;
+} | {
+  _tag: 'skipped-rows';
+  count: number;
+  note: string;
+} | {
+  _tag: 'invalid-known-through';
+  value: string;
+  note: string;
+};
+export type TrajectoryClassification = {
+  _tag: 'insufficient-data';
+  reason: 'too-few-days' | 'no-traffic';
+  days: number;
+} |
+/** Fast climb from near zero, then a drop to a small fraction of peak within about 2 weeks, staying low. */
+{
+  _tag: 'launch-honeymoon-then-cliff';
+  climbDays: number;
+  dropDays: number;
+} |
+/** The same fast drop on a site that did not start from near zero. */
+{
+  _tag: 'sudden-drop';
+  dropDays: number;
+} |
+/** Latest week is at or near the peak and clearly above 8 weeks earlier. */
+{
+  _tag: 'growing';
+} |
+/** Latest week is near the peak or moderately below it. */
+{
+  _tag: 'steady';
+} |
+/** Latest week is well below the peak with no cliff. */
+{
+  _tag: 'gradual-decline';
+};
+export interface TrajectoryResult {
+  /** First input date. Search Console history may begin at the backfill edge, not at launch. */
+  recordStartDate: string | null;
+  /** First day with any clicks or impressions. */
+  firstDataDate: string | null;
+  /** The end of the known range: `knownThrough`, or the last row when that is later. */
+  lastDataDate: string | null;
+  /** Days from the record start to the end of the known range, gaps included. */
+  days: number;
+  basis: TrajectoryBasis;
+  peak: TrajectoryWindow | null;
+  latest: TrajectoryWindow | null;
+  /**
+   * Latest 7-day total over peak 7-day total, on the basis metric. One
+   * outlier day is capped first (`OUTLIER_DAY_MULTIPLE`), so `peak` and
+   * `latest` hold raw totals and this ratio can differ from their quotient.
+   * Null when the record is too thin.
+   */
+  latestToPeakRatio: number | null;
+  /** Whole weeks from the end of the peak window to the last date. */
+  weeksSincePeak: number | null;
+  classification: TrajectoryClassification;
+  caveats: TrajectoryCaveat[];
+}
+/**
+ * Name the shape of a Site's full daily record.
+ *
+ * Pass every preserved day and the last known day. Days between the first row
+ * and `knownThrough` with no row count as zero. Days after `knownThrough` are
+ * never read. Rows with a date that is not `YYYY-MM-DD` are skipped and counted
+ * in `caveats`.
+ */
+export declare function analyzeTrajectory(record: TrajectoryRecord): TrajectoryResult;
+/**
+ * Default read when the caller gives no start date: 16 months, the span Google
+ * keeps. Hosted callers that preserve more pass `startDate` to read all of it.
+ */
+export declare const TRAJECTORY_DEFAULT_DAYS = 486;

package/dist/analyzers/trajectory.mjs

@@ -0,0 +1,356 @@
+import { datesQueryState } from "../analyzer/adapt-rows.mjs";
+import { rowNumber, rowString } from "../analyzer/row-values.mjs";
+import { fetchBudgetOf } from "@gscdump/engine/analysis-types";
+import { defineAnalyzer } from "@gscdump/engine/analyzer";
+import { defaultEndDate } from "@gscdump/engine/period";
+import { enumeratePartitions } from "@gscdump/engine/planner";
+import { MS_PER_DAY, toIsoDate } from "gscdump/dates";
+const IMPRESSIONS_OVERCOUNT_FROM = "2025-05-13";
+const IMPRESSIONS_OVERCOUNT_THROUGH = "2026-04-27";
+const METRIC_DISAGREEMENT = .25;
+const CLIFF_FRACTION = .15;
+const STAYS_LOW_FRACTION = .25;
+const LAUNCH_START_FRACTION = .25;
+const NEAR_PEAK_RATIO = .9;
+const DECLINE_RATIO = .7;
+const GROWTH_PRIOR_FRACTION = .8;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function parseDay(date) {
+	if (!ISO_DATE.test(date)) return null;
+	const ms = Date.parse(`${date}T00:00:00Z`);
+	return Number.isFinite(ms) ? ms : null;
+}
+function dateAt(startMs, index) {
+	return toIsoDate(new Date(startMs + index * MS_PER_DAY));
+}
+function fillSeries(days, endMs) {
+	const byMs = /* @__PURE__ */ new Map();
+	let skipped = 0;
+	for (const day of days) {
+		const ms = parseDay(day.date);
+		if (ms === null) {
+			skipped++;
+			continue;
+		}
+		const held = byMs.get(ms) ?? {
+			clicks: 0,
+			impressions: 0
+		};
+		held.clicks += Number.isFinite(day.clicks) ? day.clicks : 0;
+		held.impressions += Number.isFinite(day.impressions) ? day.impressions : 0;
+		byMs.set(ms, held);
+	}
+	if (!byMs.size) return null;
+	const keys = [...byMs.keys()];
+	const first = Math.min(...keys);
+	const last = Math.max(...keys, endMs ?? Number.NEGATIVE_INFINITY);
+	const length = Math.round((last - first) / MS_PER_DAY) + 1;
+	const clicks = Array.from({ length }).fill(0);
+	const impressions = Array.from({ length }).fill(0);
+	for (const [ms, value] of byMs) {
+		const index = Math.round((ms - first) / MS_PER_DAY);
+		clicks[index] = value.clicks;
+		impressions[index] = value.impressions;
+	}
+	return {
+		startDate: toIsoDate(new Date(first)),
+		clicks,
+		impressions,
+		skipped
+	};
+}
+function rollingSums(series) {
+	const out = Array.from({ length: series.length }).fill(NaN);
+	let sum = 0;
+	for (let i = 0; i < series.length; i++) {
+		sum += series[i];
+		if (i >= 7) sum -= series[i - 7];
+		if (i >= 6) out[i] = sum;
+	}
+	return out;
+}
+function median(values) {
+	values.sort((a, b) => a - b);
+	const mid = values.length >> 1;
+	return values.length % 2 ? values[mid] : (values[mid - 1] + values[mid]) / 2;
+}
+function capOutlierDays(series) {
+	return series.map((value, i) => {
+		const around = series.slice(Math.max(0, i - 7), i + 7 + 1);
+		return Math.min(value, Math.max(3 * median(around), 3));
+	});
+}
+function peakIndex(rolling) {
+	let best = -1;
+	for (let i = 6; i < rolling.length; i++) if (best === -1 || rolling[i] >= rolling[best]) best = i;
+	return best;
+}
+function ratioOf(rolling) {
+	const peak = rolling[peakIndex(rolling)];
+	const latest = rolling[rolling.length - 1];
+	return peak && peak > 0 && latest !== void 0 ? latest / peak : null;
+}
+function windowAt(filled, startMs, endIndex, rc, ri) {
+	return {
+		startDate: dateAt(startMs, endIndex - 6),
+		endDate: dateAt(startMs, endIndex),
+		clicks: rc[endIndex],
+		impressions: ri[endIndex]
+	};
+}
+function overlapsOvercount(startDate, endDate) {
+	return startDate <= "2026-04-27" && endDate >= "2025-05-13";
+}
+function emptyBasis(classification) {
+	return {
+		_tag: "impressions",
+		note: `Impressions are the default basis. No basis carries a read. ${classification._tag === "insufficient-data" && classification.reason === "no-traffic" ? `The peak week holds under 20 clicks and under 200 impressions.` : `The record is under 28 days.`}`
+	};
+}
+function emptyResult(filled, classification, caveats) {
+	const startMs = filled ? parseDay(filled.startDate) : 0;
+	const days = filled?.clicks.length ?? 0;
+	const firstTraffic = filled ? filled.clicks.findIndex((c, i) => c > 0 || filled.impressions[i] > 0) : -1;
+	return {
+		recordStartDate: filled?.startDate ?? null,
+		firstDataDate: firstTraffic >= 0 ? dateAt(startMs, firstTraffic) : null,
+		lastDataDate: filled ? dateAt(startMs, days - 1) : null,
+		days,
+		basis: emptyBasis(classification),
+		peak: null,
+		latest: null,
+		latestToPeakRatio: null,
+		weeksSincePeak: null,
+		classification,
+		caveats
+	};
+}
+function chooseBasis(rc, ri, startMs) {
+	const peakC = rc[peakIndex(rc)];
+	const peakIdxI = peakIndex(ri);
+	const peakI = ri[peakIdxI];
+	const enoughClicks = peakC >= 20;
+	const enoughImpressions = peakI >= 200;
+	const overlapsPeak = overlapsOvercount(dateAt(startMs, peakIdxI - 6), dateAt(startMs, peakIdxI));
+	if (!enoughClicks && !enoughImpressions) return null;
+	if (!enoughClicks) return {
+		basis: {
+			_tag: "impressions",
+			note: "Too few clicks to read. Impressions carry this read."
+		},
+		overlapsPeak
+	};
+	if (!enoughImpressions) return {
+		basis: {
+			_tag: "clicks",
+			reason: "too-few-impressions",
+			note: "Too few impressions to read. Clicks carry this read."
+		},
+		overlapsPeak
+	};
+	if (overlapsPeak) return {
+		basis: {
+			_tag: "clicks",
+			reason: "impressions-overcount-window",
+			note: `Clicks carry this read. Search Console over-counted impressions through ${IMPRESSIONS_OVERCOUNT_THROUGH}, and the impressions peak sits in that period.`
+		},
+		overlapsPeak
+	};
+	const ratioC = ratioOf(rc);
+	const ratioI = ratioOf(ri);
+	if (ratioC !== null && ratioI !== null && Math.abs(ratioC - ratioI) > .25) return {
+		basis: {
+			_tag: "clicks",
+			reason: "impressions-clicks-disagree",
+			note: "Clicks carry this read. Clicks and impressions disagree about how far the site fell from its peak."
+		},
+		overlapsPeak
+	};
+	return {
+		basis: {
+			_tag: "impressions",
+			note: "Impressions and clicks agree. Impressions carry this read."
+		},
+		overlapsPeak
+	};
+}
+function classify(rolling, peakIdx, firstTrafficIdx) {
+	const peak = rolling[peakIdx];
+	const lastIdx = rolling.length - 1;
+	const latest = rolling[lastIdx];
+	const ratio = latest / peak;
+	let dropIdx = -1;
+	for (let j = peakIdx + 1; j <= lastIdx; j++) if (rolling[j] <= .15 * peak) {
+		dropIdx = j;
+		break;
+	}
+	let cliffStartIdx = peakIdx;
+	for (let j = dropIdx - 1; j > peakIdx; j--) if (rolling[j] >= .7 * peak) {
+		cliffStartIdx = j;
+		break;
+	}
+	if (dropIdx !== -1 && dropIdx - cliffStartIdx <= 21) {
+		let staysLow = true;
+		for (let k = dropIdx; k <= lastIdx; k++) if (rolling[k] > .25 * peak) {
+			staysLow = false;
+			break;
+		}
+		if (staysLow) {
+			const dropDays = dropIdx - cliffStartIdx;
+			const climbDays = peakIdx - firstTrafficIdx;
+			const firstWeekIdx = firstTrafficIdx + 7 - 1;
+			const startsNearZero = firstWeekIdx < peakIdx && rolling[firstWeekIdx] <= .25 * peak;
+			return climbDays <= 56 && startsNearZero ? {
+				_tag: "launch-honeymoon-then-cliff",
+				climbDays,
+				dropDays
+			} : {
+				_tag: "sudden-drop",
+				dropDays
+			};
+		}
+	}
+	if (ratio <= .7) return { _tag: "gradual-decline" };
+	if (ratio >= .9) {
+		const priorIdx = lastIdx - 56;
+		if (priorIdx >= 6 && rolling[priorIdx] <= .8 * latest) return { _tag: "growing" };
+	}
+	return { _tag: "steady" };
+}
+function analyzeTrajectory(record) {
+	const { days } = record;
+	const knownMs = parseDay(record.knownThrough);
+	const filled = fillSeries(days, knownMs);
+	const caveats = [];
+	if (knownMs === null) caveats.push({
+		_tag: "invalid-known-through",
+		value: record.knownThrough,
+		note: `"${record.knownThrough}" is not a YYYY-MM-DD date. The latest week ends at the last row.`
+	});
+	const skippedCount = filled ? filled.skipped : days.length;
+	if (skippedCount > 0) caveats.push({
+		_tag: "skipped-rows",
+		count: skippedCount,
+		note: `${skippedCount} rows had no valid YYYY-MM-DD date and were skipped.`
+	});
+	if (!filled) return emptyResult(null, {
+		_tag: "insufficient-data",
+		reason: "too-few-days",
+		days: 0
+	}, caveats);
+	const length = filled.clicks.length;
+	if (length < 28) return emptyResult(filled, {
+		_tag: "insufficient-data",
+		reason: "too-few-days",
+		days: length
+	}, caveats);
+	const startMs = parseDay(filled.startDate);
+	const rc = rollingSums(filled.clicks);
+	const ri = rollingSums(filled.impressions);
+	const cc = rollingSums(capOutlierDays(filled.clicks));
+	const ci = rollingSums(capOutlierDays(filled.impressions));
+	const chosen = chooseBasis(cc, ci, startMs);
+	if (!chosen) return emptyResult(filled, {
+		_tag: "insufficient-data",
+		reason: "no-traffic",
+		days: length
+	}, caveats);
+	const lastDate = dateAt(startMs, length - 1);
+	if (overlapsOvercount(filled.startDate, lastDate)) caveats.push({
+		_tag: "impressions-overcount",
+		fromDate: IMPRESSIONS_OVERCOUNT_FROM,
+		throughDate: IMPRESSIONS_OVERCOUNT_THROUGH,
+		overlapsPeak: chosen.overlapsPeak,
+		note: `Search Console over-counted impressions from ${IMPRESSIONS_OVERCOUNT_FROM} through ${IMPRESSIONS_OVERCOUNT_THROUGH}. Clicks were not affected.`
+	});
+	const rolling = chosen.basis._tag === "clicks" ? cc : ci;
+	const peakIdx = peakIndex(rolling);
+	const firstTrafficIdx = filled.clicks.findIndex((c, i) => c > 0 || filled.impressions[i] > 0);
+	const lastIdx = length - 1;
+	return {
+		recordStartDate: filled.startDate,
+		firstDataDate: dateAt(startMs, firstTrafficIdx),
+		lastDataDate: lastDate,
+		days: length,
+		basis: chosen.basis,
+		peak: windowAt(filled, startMs, peakIdx, rc, ri),
+		latest: windowAt(filled, startMs, lastIdx, rc, ri),
+		latestToPeakRatio: rolling[lastIdx] / rolling[peakIdx],
+		weeksSincePeak: Math.floor((lastIdx - peakIdx) / 7),
+		classification: classify(rolling, peakIdx, firstTrafficIdx),
+		caveats
+	};
+}
+const TRAJECTORY_DEFAULT_DAYS = 486;
+function trajectoryWindow(params) {
+	const endDate = params.endDate || defaultEndDate();
+	return {
+		startDate: params.startDate || toIsoDate(/* @__PURE__ */ new Date(Date.parse(endDate) - 485 * MS_PER_DAY)),
+		endDate
+	};
+}
+const trajectoryAnalyzer = defineAnalyzer({
+	id: "trajectory",
+	buildSql(params) {
+		const { startDate, endDate } = trajectoryWindow(params);
+		return {
+			sql: `
+    SELECT
+      strftime(CAST(date AS DATE), '%Y-%m-%d') AS date,
+      CAST(SUM(clicks) AS DOUBLE) AS clicks,
+      CAST(SUM(impressions) AS DOUBLE) AS impressions
+    FROM read_parquet({{FILES}}, union_by_name = true)
+    WHERE date >= ? AND date <= ?
+    GROUP BY 1
+    ORDER BY 1
+  `,
+			params: [startDate, endDate],
+			current: {
+				table: "dates",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows, params) {
+		const arr = Array.isArray(rows) ? rows : [];
+		const { startDate, endDate } = trajectoryWindow(params);
+		return {
+			results: [analyzeTrajectory({
+				days: arr.map((r) => ({
+					date: rowString(r.date),
+					clicks: rowNumber(r.clicks),
+					impressions: rowNumber(r.impressions)
+				})),
+				knownThrough: endDate
+			})],
+			meta: {
+				total: 1,
+				startDate,
+				endDate
+			}
+		};
+	},
+	buildRows(params) {
+		return { dates: datesQueryState(trajectoryWindow(params), fetchBudgetOf(params)) };
+	},
+	reduceRows(rows, params) {
+		const dates = Array.isArray(rows) ? rows : [];
+		const { startDate, endDate } = trajectoryWindow(params);
+		return {
+			results: [analyzeTrajectory({
+				days: dates.map((r) => ({
+					date: r.date,
+					clicks: r.clicks,
+					impressions: r.impressions
+				})),
+				knownThrough: endDate
+			})],
+			meta: {
+				total: 1,
+				startDate,
+				endDate
+			}
+		};
+	}
+});
+export { CLIFF_FRACTION, DECLINE_RATIO, GROWTH_PRIOR_FRACTION, IMPRESSIONS_OVERCOUNT_FROM, IMPRESSIONS_OVERCOUNT_THROUGH, LAUNCH_START_FRACTION, METRIC_DISAGREEMENT, NEAR_PEAK_RATIO, STAYS_LOW_FRACTION, TRAJECTORY_DEFAULT_DAYS, analyzeTrajectory, trajectoryAnalyzer };

package/dist/index.d.mts

@@ -8,6 +8,7 @@ import { MOVERS_SORT_METRICS, MoverData, MoversInput, MoversOptions, MoversResul
 import { OpportunityFactors, OpportunityOptions, OpportunityResult, OpportunitySortMetric, OpportunityWeights, analyzeOpportunity } from "./analyzers/opportunity.mjs";
 import { MonthlyData, SeasonalityMetric, SeasonalityOptions, SeasonalityResult, analyzeSeasonality } from "./analyzers/seasonality.mjs";
 import { StrikingDistanceInputRow, StrikingDistanceOptions, StrikingDistanceResult, analyzeStrikingDistance } from "./analyzers/striking-distance.mjs";
+import { TRAJECTORY_DEFAULT_DAYS, TrajectoryBasis, TrajectoryCaveat, TrajectoryClassification, TrajectoryDay, TrajectoryRecord, TrajectoryResult, TrajectoryWindow, analyzeTrajectory } from "./analyzers/trajectory.mjs";
 import { ZeroClickOptions, ZeroClickResult, analyzeZeroClick } from "./analyzers/zero-click.mjs";
 import { AnalyzerRunner, BrowserAnalyzeOptions, analyzeInBrowser } from "./browser.mjs";
 import { INTENT_CLASSIFIER_VERSION, IntentClassification, SEARCH_INTENT_CODE, SearchIntent, classifyQueryIntent, encodeIntent } from "./query/intent.mjs";
@@ -18,4 +19,4 @@ import { Analyzer, AnalyzerCapabilityError, AnalyzerRegistry, AnalyzerRegistryIn
 import { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, padTimeseries, periodOf, resolveWindow } from "@gscdump/engine/period";
 import { AnalysisQuerySource, AnalysisSourceKind, ENGINE_QUERY_CAPABILITIES, EngineQuerySourceOptions, ExecuteSqlOptions, FileSet, QueryRow, SourceCapabilities, createEngineQuerySource, queryRows, runAnalyzerWithEngine } from "@gscdump/engine/source";
 import { DefineReportOptions, DefinedReport, ReportContext, ReportFinding, ReportPlanStep, ReportResult, ReportSection } from "@gscdump/engine/report";
-export { type AnalysisParams, type AnalysisPeriod, type AnalysisQuerySource, type AnalysisResult, type AnalysisSourceKind, type AnalysisTool, type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerRunner, type AnalyzerVariants, type BaseMetrics, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSegmentationRow, type BrandSummary, type BrowserAnalyzeOptions, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonMode, type ComparisonPeriod, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type CurrentSitemapScope, type DateRow, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DefineAnalyzerOptions, type DefineReportOptions, type DefinedAnalyzer, type DefinedReport, ENGINE_QUERY_CAPABILITIES, type EngineQuerySourceOptions, type ExecuteSqlOptions, type FileSet, INTENT_CLASSIFIER_VERSION, type IntentClassification, type KeywordCluster, MOVERS_SORT_METRICS, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, NORMALIZER_VERSION, type OpportunityFactors, type OpportunityOptions, type OpportunityResult, type OpportunitySortMetric, type OpportunityWeights, type PadTimeseriesOptions, type PageRow, type Plan, type QueriesRow, type QueryPageRow, type QueryRow, type ReduceContext, type ReduceCtx, type Reducer, type ReportContext, type ReportFinding, type ReportPlanStep, type ReportResult, type ReportSection, type RequiredCapability, type ResolveWindowOptions, type ResolvedWindow, type RowQueriesPlan, SEARCH_INTENT_CODE, SITEMAP_SYNC_COLLAPSE_POLICY, SITEMAP_TRUST_COLLAPSE_POLICY, type SearchIntent, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SitemapCollapsePolicy, type SitemapCollapseState, type SitemapDelta, type SitemapHealthDiff, type SitemapHealthInput, type SitemapHealthRow, type SitemapHealthTotals, type SortOrder, type SourceCapabilities, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type StrikingDistanceInputRow, type StrikingDistanceOptions, type StrikingDistanceResult, type TypedRowQuery, type WindowPreset, type ZeroClickOptions, type ZeroClickResult, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, classifyQueryIntent, classifySitemapCollapse, compareCurrentSitemapScope, comparisonOf, createAnalyzerRegistry, createEngineQuerySource, createSorter, defineAnalyzer, diffSitemapHealth, encodeIntent, normalizeQuery, num, padTimeseries, periodOf, queryRows, resolveWindow, runAnalyzerFromSource, runAnalyzerWithEngine, sitemapHistoryHasCollapse };
+export { type AnalysisParams, type AnalysisPeriod, type AnalysisQuerySource, type AnalysisResult, type AnalysisSourceKind, type AnalysisTool, type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerRunner, type AnalyzerVariants, type BaseMetrics, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSegmentationRow, type BrandSummary, type BrowserAnalyzeOptions, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonMode, type ComparisonPeriod, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type CurrentSitemapScope, type DateRow, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DefineAnalyzerOptions, type DefineReportOptions, type DefinedAnalyzer, type DefinedReport, ENGINE_QUERY_CAPABILITIES, type EngineQuerySourceOptions, type ExecuteSqlOptions, type FileSet, INTENT_CLASSIFIER_VERSION, type IntentClassification, type KeywordCluster, MOVERS_SORT_METRICS, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, NORMALIZER_VERSION, type OpportunityFactors, type OpportunityOptions, type OpportunityResult, type OpportunitySortMetric, type OpportunityWeights, type PadTimeseriesOptions, type PageRow, type Plan, type QueriesRow, type QueryPageRow, type QueryRow, type ReduceContext, type ReduceCtx, type Reducer, type ReportContext, type ReportFinding, type ReportPlanStep, type ReportResult, type ReportSection, type RequiredCapability, type ResolveWindowOptions, type ResolvedWindow, type RowQueriesPlan, SEARCH_INTENT_CODE, SITEMAP_SYNC_COLLAPSE_POLICY, SITEMAP_TRUST_COLLAPSE_POLICY, type SearchIntent, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SitemapCollapsePolicy, type SitemapCollapseState, type SitemapDelta, type SitemapHealthDiff, type SitemapHealthInput, type SitemapHealthRow, type SitemapHealthTotals, type SortOrder, type SourceCapabilities, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type StrikingDistanceInputRow, type StrikingDistanceOptions, type StrikingDistanceResult, TRAJECTORY_DEFAULT_DAYS, type TrajectoryBasis, type TrajectoryCaveat, type TrajectoryClassification, type TrajectoryDay, type TrajectoryRecord, type TrajectoryResult, type TrajectoryWindow, type TypedRowQuery, type WindowPreset, type ZeroClickOptions, type ZeroClickResult, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeTrajectory, analyzeZeroClick, classifyQueryIntent, classifySitemapCollapse, compareCurrentSitemapScope, comparisonOf, createAnalyzerRegistry, createEngineQuerySource, createSorter, defineAnalyzer, diffSitemapHealth, encodeIntent, normalizeQuery, num, padTimeseries, periodOf, queryRows, resolveWindow, runAnalyzerFromSource, runAnalyzerWithEngine, sitemapHistoryHasCollapse };

package/dist/index.mjs

@@ -8,6 +8,7 @@ import { MOVERS_SORT_METRICS, analyzeMovers } from "./analyzers/movers.mjs";
 import { analyzeOpportunity } from "./analyzers/opportunity.mjs";
 import { analyzeSeasonality } from "./analyzers/seasonality.mjs";
 import { analyzeStrikingDistance } from "./analyzers/striking-distance.mjs";
+import { TRAJECTORY_DEFAULT_DAYS, analyzeTrajectory } from "./analyzers/trajectory.mjs";
 import { analyzeZeroClick } from "./analyzers/zero-click.mjs";
 import { analyzeInBrowser } from "./browser.mjs";
 import { INTENT_CLASSIFIER_VERSION, SEARCH_INTENT_CODE, classifyQueryIntent, encodeIntent } from "./query/intent.mjs";
@@ -17,4 +18,4 @@ import { num } from "@gscdump/engine/analysis-types";
 import { AnalyzerCapabilityError, createAnalyzerRegistry, defineAnalyzer, runAnalyzerFromSource } from "@gscdump/engine/analyzer";
 import { comparisonOf, padTimeseries, periodOf, resolveWindow } from "@gscdump/engine/period";
 import { ENGINE_QUERY_CAPABILITIES, createEngineQuerySource, queryRows, runAnalyzerWithEngine } from "@gscdump/engine/source";
-export { AnalyzerCapabilityError, ENGINE_QUERY_CAPABILITIES, INTENT_CLASSIFIER_VERSION, MOVERS_SORT_METRICS, NORMALIZER_VERSION, SEARCH_INTENT_CODE, SITEMAP_SYNC_COLLAPSE_POLICY, SITEMAP_TRUST_COLLAPSE_POLICY, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, classifyQueryIntent, classifySitemapCollapse, compareCurrentSitemapScope, comparisonOf, createAnalyzerRegistry, createEngineQuerySource, createSorter, defineAnalyzer, diffSitemapHealth, encodeIntent, normalizeQuery, num, padTimeseries, periodOf, queryRows, resolveWindow, runAnalyzerFromSource, runAnalyzerWithEngine, sitemapHistoryHasCollapse };
+export { AnalyzerCapabilityError, ENGINE_QUERY_CAPABILITIES, INTENT_CLASSIFIER_VERSION, MOVERS_SORT_METRICS, NORMALIZER_VERSION, SEARCH_INTENT_CODE, SITEMAP_SYNC_COLLAPSE_POLICY, SITEMAP_TRUST_COLLAPSE_POLICY, TRAJECTORY_DEFAULT_DAYS, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeTrajectory, analyzeZeroClick, classifyQueryIntent, classifySitemapCollapse, compareCurrentSitemapScope, comparisonOf, createAnalyzerRegistry, createEngineQuerySource, createSorter, defineAnalyzer, diffSitemapHealth, encodeIntent, normalizeQuery, num, padTimeseries, periodOf, queryRows, resolveWindow, runAnalyzerFromSource, runAnalyzerWithEngine, sitemapHistoryHasCollapse };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/analysis",
   "type": "module",
-  "version": "4.5.0",
+  "version": "4.7.0",
   "description": "GSC analyzers — striking-distance, opportunity, movers, decay, brand, clustering, concentration, seasonality. Pure row-based + DuckDB-native.",
   "author": {
     "name": "Harlan Wilton",
@@ -61,9 +61,9 @@
     "node": ">=22.13.0"
   },
   "dependencies": {
-    "@gscdump/engine": "^4.5.0",
-    "@gscdump/engine-gsc-api": "^4.5.0",
-    "gscdump": "^4.5.0",
+    "@gscdump/engine": "^4.7.0",
+    "@gscdump/engine-gsc-api": "^4.7.0",
+    "gscdump": "^4.7.0",
     "pluralize": "^8.0.0"
   },
   "devDependencies": {