Synthetic Query Monitoring

1// Synthetic Query Monitoring Implementation
2 
3interface SyntheticQuerySet {
4  id: string;
5  name: string;
6  purpose: 'core-brand' | 'competitive' | 'product' | 'topic-specific';
7  createdDate: Date;
8  queries: SyntheticQuery[];
9  platforms: string[];
10  testingSchedule: 'daily' | 'weekly' | 'biweekly';
11  status: 'active' | 'transitioning' | 'retired';
12}
13 
14interface SyntheticQuery {
15  id: string;
16  query: string;
17  category: string;
18  weight: number; // Importance weight for index calculation
19}
20 
21interface SyntheticTestResult {
22  querySetId: string;
23  testDate: Date;
24  platform: string;
25  results: QueryResult[];
26  visibilityIndex: number;
27  competitorIndices?: Record<string, number>;
28}
29 
30interface QueryResult {
31  queryId: string;
32  brandAppeared: boolean;
33  position: 'featured' | 'recommended' | 'listed' | 'mentioned' | 'absent';
34  competitorsAppeared: string[];
35}
36 
37interface VisibilityTrend {
38  querySetId: string;
39  platform: string;
40  dataPoints: TrendDataPoint[];
41  weekOverWeekChange: number;
42  rollingAverage12Week: number;
43  yearOverYearChange?: number;
44  stabilityScore: number;
45}
46 
47interface TrendDataPoint {
48  date: Date;
49  visibilityIndex: number;
50  sampleSize: number;
51}
52 
53// Execute synthetic query monitoring
54async function executeSyntheticMonitoring(
55  querySet: SyntheticQuerySet,
56  brand: string,
57  brandVariations: string[],
58  competitors: string[]
59): Promise<SyntheticTestResult[]> {
60  const results: SyntheticTestResult[] = [];
61  
62  for (const platform of querySet.platforms) {
63    const queryResults: QueryResult[] = [];
64    
65    for (const query of querySet.queries) {
66      const response = await queryPlatform(platform, query.query);
67      const brandDetected = detectBrand(response, brand, brandVariations);
68      const position = brandDetected 
69        ? determinePosition(response, brand) 
70        : 'absent';
71      const competitorsDetected = detectCompetitors(response, competitors);
72      
73      queryResults.push({
74        queryId: query.id,
75        brandAppeared: brandDetected,
76        position,
77        competitorsAppeared: competitorsDetected
78      });
79    }
80    
81    // Calculate visibility index
82    const visibilityIndex = calculateVisibilityIndex(querySet, queryResults);
83    
84    // Calculate competitor indices
85    const competitorIndices: Record<string, number> = {};
86    competitors.forEach(competitor => {
87      competitorIndices[competitor] = calculateCompetitorIndex(
88        querySet, 
89        queryResults, 
90        competitor
91      );
92    });
93    
94    results.push({
95      querySetId: querySet.id,
96      testDate: new Date(),
97      platform,
98      results: queryResults,
99      visibilityIndex,
100      competitorIndices
101    });
102  }
103  
104  return results;
105}
106 
107// Calculate weighted visibility index
108function calculateVisibilityIndex(
109  querySet: SyntheticQuerySet,
110  results: QueryResult[]
111): number {
112  let weightedSum = 0;
113  let totalWeight = 0;
114  
115  querySet.queries.forEach(query => {
116    const result = results.find(r => r.queryId === query.id);
117    if (result) {
118      // Score based on position
119      const positionScore = getPositionScore(result.position);
120      weightedSum += positionScore * query.weight;
121      totalWeight += query.weight;
122    }
123  });
124  
125  return totalWeight > 0 ? (weightedSum / totalWeight) * 100 : 0;
126}
127 
128function getPositionScore(position: string): number {
129  const scores: Record<string, number> = {
130    'featured': 1.0,
131    'recommended': 0.85,
132    'listed': 0.6,
133    'mentioned': 0.4,
134    'absent': 0
135  };
136  return scores[position] || 0;
137}
138 
139// Analyze visibility trends
140function analyzeVisibilityTrend(
141  historicalResults: SyntheticTestResult[],
142  querySetId: string,
143  platform: string
144): VisibilityTrend {
145  const relevantResults = historicalResults
146    .filter(r => r.querySetId === querySetId && r.platform === platform)
147    .sort((a, b) => a.testDate.getTime() - b.testDate.getTime());
148  
149  const dataPoints: TrendDataPoint[] = relevantResults.map(r => ({
150    date: r.testDate,
151    visibilityIndex: r.visibilityIndex,
152    sampleSize: r.results.length
153  }));
154  
155  // Calculate week-over-week change
156  const weekOverWeekChange = dataPoints.length >= 2
157    ? dataPoints[dataPoints.length - 1].visibilityIndex - 
158      dataPoints[dataPoints.length - 2].visibilityIndex
159    : 0;
160  
161  // Calculate 12-week rolling average
162  const last12Weeks = dataPoints.slice(-12);
163  const rollingAverage12Week = last12Weeks.length > 0
164    ? last12Weeks.reduce((sum, dp) => sum + dp.visibilityIndex, 0) / last12Weeks.length
165    : 0;
166  
167  // Calculate year-over-year if data exists
168  let yearOverYearChange: number | undefined;
169  if (dataPoints.length >= 52) {
170    const currentIndex = dataPoints[dataPoints.length - 1].visibilityIndex;
171    const yearAgoIndex = dataPoints[dataPoints.length - 52].visibilityIndex;
172    yearOverYearChange = currentIndex - yearAgoIndex;
173  }
174  
175  // Calculate stability score (inverse of variance)
176  const stabilityScore = calculateStabilityScore(dataPoints);
177  
178  return {
179    querySetId,
180    platform,
181    dataPoints,
182    weekOverWeekChange,
183    rollingAverage12Week,
184    yearOverYearChange,
185    stabilityScore
186  };
187}
188 
189function calculateStabilityScore(dataPoints: TrendDataPoint[]): number {
190  if (dataPoints.length < 4) return 100; // Not enough data
191  
192  const recent = dataPoints.slice(-12);
193  const values = recent.map(dp => dp.visibilityIndex);
194  const mean = values.reduce((a, b) => a + b, 0) / values.length;
195  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / values.length;
196  const stdDev = Math.sqrt(variance);
197  
198  // Convert to 0-100 score where 100 is perfectly stable
199  // Assume stdDev of 10+ is "very unstable"
200  return Math.max(0, 100 - (stdDev * 10));
201}
202 
203// Generate trend alerts
204function generateTrendAlerts(
205  trend: VisibilityTrend,
206  thresholds: { weeklyChange: number; stability: number }
207): string[] {
208  const alerts: string[] = [];
209  
210  if (Math.abs(trend.weekOverWeekChange) > thresholds.weeklyChange) {
211    const direction = trend.weekOverWeekChange > 0 ? 'increased' : 'decreased';
212    alerts.push(
213      `Synthetic visibility ${direction} by ${Math.abs(trend.weekOverWeekChange).toFixed(1)} points this week`
214    );
215  }
216  
217  if (trend.stabilityScore < thresholds.stability) {
218    alerts.push(
219      `Visibility stability score (${trend.stabilityScore.toFixed(0)}) below threshold - high variance detected`
220    );
221  }
222  
223  if (trend.yearOverYearChange !== undefined && trend.yearOverYearChange < -5) {
224    alerts.push(
225      `Year-over-year visibility declined by ${Math.abs(trend.yearOverYearChange).toFixed(1)} points`
226    );
227  }
228  
229  return alerts;
230}
231 
232// Manage query set lifecycle
233function manageQuerySetTransition(
234  oldSet: SyntheticQuerySet,
235  newSet: SyntheticQuerySet,
236  overlapWeeks: number = 12
237): TransitionPlan {
238  const transitionStart = new Date();
239  const transitionEnd = new Date(transitionStart.getTime() + overlapWeeks * 7 * 24 * 60 * 60 * 1000);
240  
241  return {
242    oldSetId: oldSet.id,
243    newSetId: newSet.id,
244    transitionStart,
245    transitionEnd,
246    overlapWeeks,
247    actions: [
248      { date: transitionStart, action: 'Begin parallel testing of both sets' },
249      { date: transitionEnd, action: 'Retire old set, new set becomes primary' },
250    ],
251    correlationAnalysisRequired: true
252  };
253}