📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
Migrate SEO analytics to v2 API
Blue Mouse3be9b6654d4d
diff --git a/backend/apps/cloud/src/analytics/analytics.controller.ts b/backend/apps/cloud/src/analytics/analytics.controller.tsindex 76f237689..ea22a6824 100644--- a/backend/apps/cloud/src/analytics/analytics.controller.ts+++ b/backend/apps/cloud/src/analytics/analytics.controller.ts@@ -50,7 +50,7 @@ import { DEFAULT_TIMEZONE } from '../user/entities/user.entity'import { AuthenticationGuard } from '../auth/guards/authentication.guard'import { PageviewsDto } from './dto/pageviews.dto'import { EventsDto } from './dto/events.dto'-import { GetDataDto, ChartRenderMode, TimeBucketType } from './dto/getData.dto'+import { GetDataDto, ChartRenderMode } from './dto/getData.dto'import { GetCustomEventMetadata } from './dto/get-custom-event-meta.dto'import { GetPagePropertyMetaDto } from './dto/get-page-property-meta.dto'import { GetJourneysDto } from './dto/get-journeys.dto'@@ -109,7 +109,7 @@ import { LiveVisitorsDto } from './dto/live-visitors.dto'import { GetHeartbeatStatsDto } from './dto/get-heartbeat-stats'import { GetKeywordsDto } from './dto/get-keywords.dto'import { GetBotStatsDto } from './dto/get-bot-stats.dto'-import { GSCService } from '../project/gsc.service'+import { GSC_ALL_TIME_DAYS, GSCService } from '../project/gsc.service'import { GetProfileIdDto, GetSessionIdDto } from './dto/get-id.dto'import { ExperimentService } from '../experiment/experiment.service'import {@@ -129,9 +129,6 @@ const BOT_RESPONSE = { message: 'Bot traffic detected, request is ignored' }const ONLINE_VISITORS_WINDOW_MINUTES = 5 // minutes-// Maximum range for "all time" GSC queries (~16 months, GSC's data retention)-const GSC_ALL_TIME_DAYS = 480-// Performance object validator: none of the values cannot be bigger than 1000 * 60 * 5 (5 minutes) and are >= 0const MAX_PERFORMANCE_VALUE = 1000 * 60 * 5const isPerformanceValid = (perf: any) => {@@ -1196,139 +1193,6 @@ export class AnalyticsController {return { keywords }}- @Get('gsc-dashboard')- @Auth(true, true)- async getGSCDashboard(- @Query() data: GetKeywordsDto,- @CurrentUserId() uid: string,- @Headers() headers: { 'x-password'?: string },- ) {- const {- pid,- period,- from,- to,- timezone = DEFAULT_TIMEZONE,- timeBucket,- filters,- } = data-- await this.analyticsService.checkProjectAccess(- pid,- uid,- headers['x-password'],- )-- await this.analyticsService.checkBillingAccess(pid)-- const defaultTimeBucket = ['1h', 'today', 'yesterday', '1d'].includes(- period,- )- ? TimeBucketType.HOUR- : TimeBucketType.DAY- const finalTimeBucket = (timeBucket || defaultTimeBucket) as TimeBucketType- let groupTimeBucket: TimeBucketType | null = finalTimeBucket- if (period === 'all' || period === 'custom') {- groupTimeBucket = null- }-- this.logger.log(- `pid: ${pid}, period: ${period}, timeBucket: ${finalTimeBucket}, filters: ${filters}`,- 'GET /analytics/gsc-dashboard',- )-- const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined-- const safeTimezone = this.analyticsService.getSafeTimezone(timezone)- const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(- from,- to,- groupTimeBucket,- period,- safeTimezone,- diff,- )-- return this.gscService.getDashboard(- pid,- groupFrom,- groupTo,- finalTimeBucket,- filters,- )- }-- @Get('gsc-details')- @Auth(true, true)- async getGSCDetails(- @Query() data: GetKeywordsDto,- @CurrentUserId() uid: string,- @Headers() headers: { 'x-password'?: string },- ) {- const {- pid,- period,- from,- to,- timezone = DEFAULT_TIMEZONE,- page,- query,- } = data-- this.logger.log(- `pid: ${pid}, period: ${period}, page: ${page}, query: ${query}`,- 'GET /analytics/gsc-details',- )-- await this.analyticsService.checkProjectAccess(- pid,- uid,- headers['x-password'],- )-- await this.analyticsService.checkBillingAccess(pid)-- const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined-- const safeTimezone = this.analyticsService.getSafeTimezone(timezone)- const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(- from,- to,- null,- period,- safeTimezone,- diff,- )-- if (page) {- const keywords = await this.gscService.getKeywords(- pid,- groupFrom,- groupTo,- 50,- 0,- undefined,- page,- )- return { type: 'queries', data: keywords }- }-- if (query) {- const pages = await this.gscService.getTopPages(- pid,- groupFrom,- groupTo,- 50,- 0,- undefined,- query,- )- return { type: 'pages', data: pages }- }-- return { type: 'none', data: [] }- }-@Get('birdseye')@Auth(true, true)// returns overall short statistics per projectdiff --git a/backend/apps/cloud/src/analytics/analytics.module.ts b/backend/apps/cloud/src/analytics/analytics.module.tsindex ae5fb10ae..f0f0a817b 100644--- a/backend/apps/cloud/src/analytics/analytics.module.ts+++ b/backend/apps/cloud/src/analytics/analytics.module.ts@@ -22,6 +22,7 @@ import {} from './session-replay-export.service'import { SessionReplayExportProcessor } from './session-replay-export.processor'import { AnalyticsV2Service } from './v2/analytics-v2.service'+import { SeoV2Service } from './v2/seo-v2.service'import { TrafficV2Controller } from './v2/controllers/traffic-v2.controller'import { PerformanceV2Controller } from './v2/controllers/performance-v2.controller'import { CaptchaV2Controller } from './v2/controllers/captcha-v2.controller'@@ -29,6 +30,7 @@ import { ErrorsV2Controller } from './v2/controllers/errors-v2.controller'import { SessionsV2Controller } from './v2/controllers/sessions-v2.controller'import { ProfilesV2Controller } from './v2/controllers/profiles-v2.controller'import { ProjectV2Controller } from './v2/controllers/project-v2.controller'+import { SeoV2Controller } from './v2/controllers/seo-v2.controller'@Module({imports: [@@ -43,6 +45,7 @@ import { ProjectV2Controller } from './v2/controllers/project-v2.controller'providers: [AnalyticsService,AnalyticsV2Service,+ SeoV2Service,BotDetectionService,SaltService,SessionReplayS3Service,@@ -62,6 +65,7 @@ import { ProjectV2Controller } from './v2/controllers/project-v2.controller'SessionsV2Controller,ProfilesV2Controller,ProjectV2Controller,+ SeoV2Controller,],})export class AnalyticsModule {}diff --git a/backend/apps/cloud/src/analytics/protection/public-project-cache.interceptor.ts b/backend/apps/cloud/src/analytics/protection/public-project-cache.interceptor.tsindex a108983b4..f82b44cf0 100644--- a/backend/apps/cloud/src/analytics/protection/public-project-cache.interceptor.ts+++ b/backend/apps/cloud/src/analytics/protection/public-project-cache.interceptor.ts@@ -33,8 +33,6 @@ const CACHEABLE_ROUTES = new Set(['funnel-sessions','custom-events','keywords',- 'gsc-dashboard',- 'gsc-details',])/**diff --git a/backend/apps/cloud/src/analytics/v2/__tests__/seo.mapper.spec.ts b/backend/apps/cloud/src/analytics/v2/__tests__/seo.mapper.spec.tsnew file mode 100644index 000000000..d90e11b99--- /dev/null+++ b/backend/apps/cloud/src/analytics/v2/__tests__/seo.mapper.spec.ts@@ -0,0 +1,210 @@+import { TimeBucketType } from '../../dto/getData.dto'+import {+ bucketSeoDateSeries,+ gscCountryToAlpha2,+ mapSeoBreakdownRows,+ mapSeoSummary,+ mapSeoTimeseries,+ SeoDateSeriesEntry,+} from '../mappers/seo.mapper'++const day = (+ date: string,+ clicks: number,+ impressions: number,+ position: number,+): SeoDateSeriesEntry => ({+ date,+ clicks,+ impressions,+ position,+ ctr: impressions > 0 ? (clicks / impressions) * 100 : 0,+})++describe('gscCountryToAlpha2', () => {+ it('converts Search Console alpha-3 to the alpha-2 the rest of v2 uses', () => {+ expect(gscCountryToAlpha2('usa')).toBe('US')+ expect(gscCountryToAlpha2('deu')).toBe('DE')+ expect(gscCountryToAlpha2('ukr')).toBe('UA')+ })++ it('passes through anything it cannot map rather than dropping the row', () => {+ expect(gscCountryToAlpha2('zzz')).toBe('ZZZ')+ expect(gscCountryToAlpha2('')).toBe('')+ })+})++describe('mapSeoBreakdownRows', () => {+ it("reads getKeywords' `count` as clicks", () => {+ expect(+ mapSeoBreakdownRows(+ 'query',+ [+ {+ name: 'swetrix',+ count: 12,+ impressions: 400,+ ctr: 3,+ position: 4.2,+ },+ ],+ ['clicks', 'impressions', 'ctr', 'position'],+ ),+ ).toEqual([+ { value: 'swetrix', clicks: 12, impressions: 400, ctr: 3, position: 4.2 },+ ])+ })++ it('reads the label field each per-dimension getter returns', () => {+ expect(+ mapSeoBreakdownRows('page', [{ page: '/blog', clicks: 5 }], ['clicks']),+ ).toEqual([{ value: '/blog', clicks: 5 }])++ expect(+ mapSeoBreakdownRows(+ 'device',+ [{ device: 'mobile', clicks: 3 }],+ ['clicks'],+ ),+ ).toEqual([{ value: 'mobile', clicks: 3 }])+ })++ it('normalises country rows to alpha-2', () => {+ expect(+ mapSeoBreakdownRows(+ 'country',+ [{ country: 'usa', clicks: 9 }],+ ['clicks'],+ ),+ ).toEqual([{ value: 'US', clicks: 9 }])+ })++ it('only emits the requested metrics', () => {+ expect(+ mapSeoBreakdownRows(+ 'query',+ [{ name: 'a', count: 1, impressions: 2, ctr: 50, position: 1 }],+ ['clicks'],+ ),+ ).toEqual([{ value: 'a', clicks: 1 }])+ })++ it('defaults missing values to zero rather than emitting NaN', () => {+ expect(+ mapSeoBreakdownRows('query', [{ name: 'a' }], ['clicks', 'position']),+ ).toEqual([{ value: 'a', clicks: 0, position: 0 }])+ })+})++describe('mapSeoSummary', () => {+ it('reports the absolute change between periods, matching the other v2 summaries', () => {+ expect(+ mapSeoSummary(+ { clicks: 120, impressions: 3000, ctr: 4, position: 8.1 },+ { clicks: 100, impressions: 2500, ctr: 4.5, position: 9.4 },+ ),+ ).toEqual({+ current: { clicks: 120, impressions: 3000, ctr: 4, position: 8.1 },+ previous: { clicks: 100, impressions: 2500, ctr: 4.5, position: 9.4 },+ change: { clicks: 20, impressions: 500, ctr: -0.5, position: -1.3 },+ })+ })++ it('treats a missing previous period as zeroes', () => {+ const summary = mapSeoSummary(+ { clicks: 10, impressions: 100, ctr: 10, position: 2 },+ null,+ )++ expect(summary.previous).toEqual({+ clicks: 0,+ impressions: 0,+ ctr: 0,+ position: 0,+ })+ expect(summary.change.clicks).toBe(10)+ })+})++describe('bucketSeoDateSeries', () => {+ const series = [+ day('2026-01-05', 10, 100, 10),+ day('2026-01-20', 30, 300, 2),+ day('2026-02-10', 5, 50, 4),+ ]++ it('leaves the native hour and day granularity untouched', () => {+ expect(bucketSeoDateSeries(series, TimeBucketType.DAY)).toBe(series)+ expect(bucketSeoDateSeries(series, TimeBucketType.HOUR)).toBe(series)+ })++ it('sums clicks and impressions into month buckets', () => {+ const [january, february] = bucketSeoDateSeries(+ series,+ TimeBucketType.MONTH,+ )++ expect(january.date).toBe('2026-01-01')+ expect(january.clicks).toBe(40)+ expect(january.impressions).toBe(400)+ expect(february.date).toBe('2026-02-01')+ expect(february.clicks).toBe(5)+ })++ it('recomputes ctr from the bucket totals rather than averaging it', () => {+ const [january] = bucketSeoDateSeries(series, TimeBucketType.MONTH)+ // 40 clicks / 400 impressions, not the mean of the two daily CTRs.+ expect(january.ctr).toBe(10)+ })++ it('averages position weighted by impressions', () => {+ const [january] = bucketSeoDateSeries(series, TimeBucketType.MONTH)+ // (10*100 + 2*300) / 400 = 4, whereas a plain mean would give 6.+ expect(january.position).toBe(4)+ })++ it('rolls a whole year up into one bucket', () => {+ const yearly = bucketSeoDateSeries(series, TimeBucketType.YEAR)++ expect(yearly).toHaveLength(1)+ expect(yearly[0].date).toBe('2026-01-01')+ expect(yearly[0].clicks).toBe(45)+ })++ it('reports zeroed rates for a bucket with no impressions', () => {+ const [bucket] = bucketSeoDateSeries(+ [day('2026-01-05', 0, 0, 0)],+ TimeBucketType.MONTH,+ )++ expect(bucket.ctr).toBe(0)+ expect(bucket.position).toBe(0)+ })+})++describe('mapSeoTimeseries', () => {+ it('emits ISO timestamps in the requested timezone', () => {+ const [row] = mapSeoTimeseries(+ [day('2026-01-05', 10, 100, 3)],+ ['clicks'],+ 'Europe/Kyiv',+ )++ expect(row.timestamp).toBe('2026-01-05T00:00:00+02:00')+ expect(row.clicks).toBe(10)+ })++ it('only emits the requested metrics', () => {+ const [row] = mapSeoTimeseries(+ [day('2026-01-05', 10, 100, 3)],+ ['clicks', 'position'],+ 'UTC',+ )++ expect(Object.keys(row).sort()).toEqual(['clicks', 'position', 'timestamp'])+ })++ it('drops rows Search Console returned without a date', () => {+ expect(mapSeoTimeseries([day('', 1, 1, 1)], ['clicks'], 'UTC')).toEqual([])+ })+})diff --git a/backend/apps/cloud/src/analytics/v2/__tests__/seo.registry.spec.ts b/backend/apps/cloud/src/analytics/v2/__tests__/seo.registry.spec.tsnew file mode 100644index 000000000..145d9407b--- /dev/null+++ b/backend/apps/cloud/src/analytics/v2/__tests__/seo.registry.spec.ts@@ -0,0 +1,134 @@+import { UnprocessableEntityException } from '@nestjs/common'++import { V2Filter } from '../query/filters.translator'+import {+ getDefaultSeoMetrics,+ getSeoBreakdownDimension,+ getSeoMetric,+ listSeoDimensions,+ parseSeoMetricsParam,+ toGscFiltersJson,+ validateSeoFilters,+ V2_SEO_DIMENSIONS,+} from '../registry/seo'++const filter = (overrides: Partial<V2Filter> = {}): V2Filter =>+ ({+ dimension: 'country',+ operator: 'is',+ value: 'US',+ ...overrides,+ }) as V2Filter++describe('seo dimension lookups', () => {+ it('resolves every declared dimension to its Search Console name', () => {+ expect(getSeoBreakdownDimension('query').gsc).toBe('query')+ expect(getSeoBreakdownDimension('page').gsc).toBe('page')+ expect(getSeoBreakdownDimension('country').gsc).toBe('country')+ expect(getSeoBreakdownDimension('device').gsc).toBe('device')+ })++ it('rejects unknown dimensions with 422', () => {+ expect(() => getSeoBreakdownDimension('nope')).toThrow(+ UnprocessableEntityException,+ )+ // Valid for traffic, but Search Console reports nothing like it.+ expect(() => getSeoBreakdownDimension('browser')).toThrow(+ UnprocessableEntityException,+ )+ })++ it('has unique api names', () => {+ const names = listSeoDimensions().map((dimension) => dimension.api)+ expect(new Set(names).size).toBe(names.length)+ })++ it('only maps onto dimensions Search Console actually serves', () => {+ for (const dimension of V2_SEO_DIMENSIONS) {+ expect(['query', 'page', 'country', 'device']).toContain(dimension.gsc)+ }+ })+})++describe('seo metric lookups', () => {+ it('resolves metrics and rejects unknown ones', () => {+ expect(getSeoMetric('clicks').api).toBe('clicks')+ expect(() => getSeoMetric('visitors')).toThrow(UnprocessableEntityException)+ })++ it('returns all four metrics by default', () => {+ expect(getDefaultSeoMetrics().map((metric) => metric.api)).toEqual([+ 'clicks',+ 'impressions',+ 'ctr',+ 'position',+ ])+ })++ it('parses and dedupes the metrics CSV param', () => {+ expect(+ parseSeoMetricsParam('clicks, impressions,clicks').map(+ (metric) => metric.api,+ ),+ ).toEqual(['clicks', 'impressions'])++ expect(parseSeoMetricsParam(undefined).map((metric) => metric.api)).toEqual(+ ['clicks', 'impressions', 'ctr', 'position'],+ )++ expect(() => parseSeoMetricsParam('bogus')).toThrow(+ UnprocessableEntityException,+ )+ })+})++describe('validateSeoFilters', () => {+ it('accepts scalar filters on known dimensions', () => {+ const filters = [filter(), filter({ dimension: 'query', value: 'swetrix' })]+ expect(validateSeoFilters(filters)).toBe(filters)+ })++ it('rejects filters on dimensions Search Console cannot filter by', () => {+ expect(() =>+ validateSeoFilters([filter({ dimension: 'browser' })]),+ ).toThrow(UnprocessableEntityException)+ })++ it('rejects array values, which have no dimensionFilterGroups equivalent', () => {+ expect(() => validateSeoFilters([filter({ value: ['US', 'DE'] })])).toThrow(+ UnprocessableEntityException,+ )+ })++ it('rejects null values, since Search Console reports no unset values', () => {+ expect(() => validateSeoFilters([filter({ value: null })])).toThrow(+ UnprocessableEntityException,+ )+ })+})++describe('toGscFiltersJson', () => {+ it('renames query -> keywords, the key GSCService.parseFilters expects', () => {+ const json = toGscFiltersJson([+ filter({ dimension: 'query', value: 'swetrix' }),+ ])++ expect(JSON.parse(json)).toEqual([+ { dimension: 'keywords', operator: 'is', value: 'swetrix' },+ ])+ })++ it('leaves dimensions that already share a name alone', () => {+ const json = toGscFiltersJson([+ filter({ dimension: 'page', operator: 'contains', value: '/blog' }),+ ])++ expect(JSON.parse(json)).toEqual([+ { dimension: 'page', operator: 'contains', value: '/blog' },+ ])+ })++ it('returns undefined for no filters so no filter group is sent', () => {+ expect(toGscFiltersJson([])).toBeUndefined()+ })+})diff --git a/backend/apps/cloud/src/analytics/v2/controllers/project-v2.controller.ts b/backend/apps/cloud/src/analytics/v2/controllers/project-v2.controller.tsindex 48df6c494..bb3a81ff2 100644--- a/backend/apps/cloud/src/analytics/v2/controllers/project-v2.controller.ts+++ b/backend/apps/cloud/src/analytics/v2/controllers/project-v2.controller.ts@@ -33,6 +33,7 @@ import {V2FunnelSessionsQueryDto,} from '../dto/project.dto'import { V2ProjectParamsDto } from '../dto/v2-base.dto'+import { SeoV2Service } from '../seo-v2.service'@ApiTags('Analytics v2')@ApiBearerAuth()@@ -44,6 +45,7 @@ import { V2ProjectParamsDto } from '../dto/v2-base.dto'export class ProjectV2Controller {constructor(private readonly analyticsV2Service: AnalyticsV2Service,+ private readonly seoV2Service: SeoV2Service,private readonly logger: AppLoggerService,) {}@@ -144,6 +146,12 @@ export class ProjectV2Controller {headers['x-password'],)+ // SEO is served by the Search Console API rather than ClickHouse, so it+ // keeps its own registry outside the sqlExpr-based one.+ if (query.type === 'seo') {+ return this.seoV2Service.getDimensions()+ }+return this.analyticsV2Service.getDimensions(query.type || 'traffic')}diff --git a/backend/apps/cloud/src/analytics/v2/controllers/seo-v2.controller.ts b/backend/apps/cloud/src/analytics/v2/controllers/seo-v2.controller.tsnew file mode 100644index 000000000..85ee82f0c--- /dev/null+++ b/backend/apps/cloud/src/analytics/v2/controllers/seo-v2.controller.ts@@ -0,0 +1,202 @@+import {+ Controller,+ Get,+ Headers,+ Param,+ Query,+ UseGuards,+ UseInterceptors,+ UsePipes,+ ValidationPipe,+} from '@nestjs/common'+import {+ ApiBearerAuth,+ ApiOperation,+ ApiSecurity,+ ApiTags,+} from '@nestjs/swagger'++import { Auth } from '../../../auth/decorators'+import { CurrentUserId } from '../../../auth/decorators/current-user-id.decorator'+import { OptionalJwtAccessTokenGuard } from '../../../auth/guards'+import { AuthenticationGuard } from '../../../auth/guards/authentication.guard'+import { AppLoggerService } from '../../../logger/logger.service'+import { AnalyticsReadGuard } from '../../protection/analytics-read.guard'+import { CacheableAnalytics } from '../../protection/cacheable-analytics.decorator'+import { PublicProjectCacheInterceptor } from '../../protection/public-project-cache.interceptor'+import { AnalyticsV2Service } from '../analytics-v2.service'+import {+ V2SeoBreakdownDto,+ V2SeoRangeDto,+ V2SeoSummaryDto,+ V2SeoTimeseriesDto,+} from '../dto/seo.dto'+import { V2ProjectParamsDto } from '../dto/v2-base.dto'+import { SeoV2Service } from '../seo-v2.service'++@ApiTags('Analytics v2')+@ApiBearerAuth()+@ApiSecurity('apiKey')+@UseGuards(OptionalJwtAccessTokenGuard, AuthenticationGuard, AnalyticsReadGuard)+@UseInterceptors(PublicProjectCacheInterceptor)+@UsePipes(new ValidationPipe({ transform: true }))+@Controller('v2/projects/:pid/seo')+export class SeoV2Controller {+ constructor(+ private readonly seoV2Service: SeoV2Service,+ private readonly analyticsV2Service: AnalyticsV2Service,+ private readonly logger: AppLoggerService,+ ) {}++ @Get('status')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'Search Console connection status',+ description:+ 'Whether Google Search Console is connected for this project and which property is linked. The other seo endpoints return 409 until both are true.',+ })+ async getStatus(+ @Param() { pid }: V2ProjectParamsDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/status')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getStatus(pid)+ }++ @Get('summary')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'SEO summary',+ description:+ 'Clicks, impressions, CTR and average position for the selected period, the previous period of the same length, and the change between them.',+ })+ async getSummary(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoSummaryDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/summary')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getSummary(pid, query)+ }++ @Get('timeseries')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'SEO timeseries',+ description:+ 'Selected SEO metrics grouped by time bucket, as rows of objects with ISO-8601 timestamps.',+ })+ async getTimeseries(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoTimeseriesDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/timeseries')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getTimeseries(pid, query)+ }++ @Get('breakdown')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'SEO breakdown',+ description:+ 'SEO metrics grouped by a single dimension (query, page, country, device), paginated. Rows are always ordered by clicks descending.',+ })+ async getBreakdown(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoBreakdownDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(+ `pid: ${pid}, dimension: ${query.dimension}`,+ 'GET /v2/projects/:pid/seo/breakdown',+ )++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getBreakdown(pid, query)+ }++ @Get('branded-traffic')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'Branded vs non-branded traffic',+ description:+ "Clicks split by whether the search query contained one of the project's brand keywords. Skipped for ranges wider than 31 days.",+ })+ async getBrandedTraffic(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoRangeDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/branded-traffic')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getBrandedTraffic(pid, query)+ }++ @Get('positions')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'Search position analytics',+ description:+ 'Impressions bucketed by search position, and the daily count of ranking queries per position bucket. Skipped for ranges wider than 31 days.',+ })+ async getPositions(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoRangeDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/positions')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getPositions(pid, query)+ }+}diff --git a/backend/apps/cloud/src/analytics/v2/dto/project.dto.ts b/backend/apps/cloud/src/analytics/v2/dto/project.dto.tsindex 44dddc3a9..e3cbc8dc5 100644--- a/backend/apps/cloud/src/analytics/v2/dto/project.dto.ts+++ b/backend/apps/cloud/src/analytics/v2/dto/project.dto.ts@@ -77,15 +77,15 @@ export class V2FunnelSessionsQueryDto extends V2FunnelQueryDto {export class V2DimensionsQueryDto {@ApiProperty({required: false,- enum: ['traffic', 'performance', 'captcha', 'errors'],+ enum: ['traffic', 'performance', 'captcha', 'errors', 'seo'],default: 'traffic',description: 'Data type to list dimensions and metrics for',})@IsOptional()- @IsIn(['traffic', 'performance', 'captcha', 'errors'], {+ @IsIn(['traffic', 'performance', 'captcha', 'errors', 'seo'], {message: 'The provided type is incorrect',})- type?: 'traffic' | 'performance' | 'captcha' | 'errors'+ type?: 'traffic' | 'performance' | 'captcha' | 'errors' | 'seo'}export class V2DimensionValuesParamsDto extends V2ProjectParamsDto {diff --git a/backend/apps/cloud/src/analytics/v2/dto/seo.dto.ts b/backend/apps/cloud/src/analytics/v2/dto/seo.dto.tsnew file mode 100644index 000000000..f8153b33a--- /dev/null+++ b/backend/apps/cloud/src/analytics/v2/dto/seo.dto.ts@@ -0,0 +1,115 @@+import { ApiProperty } from '@nestjs/swagger'+import { Type } from 'class-transformer'+import {+ IsIn,+ IsInt,+ IsNotEmpty,+ IsOptional,+ IsString,+ Max,+ Min,+} from 'class-validator'++import { TimeBucketType } from '../../dto/getData.dto'+import { SEO_SORT } from '../registry/seo'+import { V2BaseQueryDto } from './v2-base.dto'++const V2_SEO_MAX_BREAKDOWN_LIMIT = 100++/**+ * Search Console reports nothing below hourly granularity, so `minute` is+ * excluded from the buckets a caller may ask for.+ */+export const V2_SEO_TIME_BUCKETS = [+ TimeBucketType.HOUR,+ TimeBucketType.DAY,+ TimeBucketType.MONTH,+ TimeBucketType.YEAR,+] as const++export type V2SeoTimeBucket = (typeof V2_SEO_TIME_BUCKETS)[number]++export class V2SeoSummaryDto extends V2BaseQueryDto {}++export class V2SeoRangeDto extends V2BaseQueryDto {}++export class V2SeoTimeseriesDto extends V2BaseQueryDto {+ @ApiProperty({+ required: false,+ enum: V2_SEO_TIME_BUCKETS,+ description:+ "Time bucket for grouping. One of: hour, day, month, year. Defaults to 'day', or 'hour' for intraday periods.",+ })+ @IsOptional()+ @IsIn(V2_SEO_TIME_BUCKETS as readonly string[], {+ message: `The provided timeBucket is incorrect. Search Console supports: ${V2_SEO_TIME_BUCKETS.join(', ')}`,+ })+ timeBucket?: V2SeoTimeBucket++ @ApiProperty({+ required: false,+ description:+ 'Comma-separated metric names to return. Defaults to clicks, impressions, ctr and position.',+ example: 'clicks,impressions',+ })+ @IsOptional()+ @IsString()+ metrics?: string+}++export class V2SeoBreakdownDto extends V2BaseQueryDto {+ @ApiProperty({+ description:+ 'Dimension to break down by. One of: query, page, country, device',+ example: 'query',+ })+ @IsNotEmpty()+ @IsString()+ dimension: string++ @ApiProperty({+ required: false,+ description:+ 'Comma-separated metric names to compute per dimension value. Defaults to clicks, impressions, ctr and position.',+ example: 'clicks,impressions',+ })+ @IsOptional()+ @IsString()+ metrics?: string++ @ApiProperty({+ required: false,+ default: 30,+ maximum: V2_SEO_MAX_BREAKDOWN_LIMIT,+ description: 'Number of rows to return',+ })+ @IsOptional()+ @Type(() => Number)+ @IsInt()+ @Min(1)+ @Max(V2_SEO_MAX_BREAKDOWN_LIMIT)+ limit?: number++ @ApiProperty({+ required: false,+ default: 0,+ description: 'Number of rows to skip (pagination)',+ })+ @IsOptional()+ @Type(() => Number)+ @IsInt()+ @Min(0)+ offset?: number++ @ApiProperty({+ required: false,+ enum: [SEO_SORT],+ default: SEO_SORT,+ description: `Search Console orders rows by clicks descending and offers no sort control, so '${SEO_SORT}' is the only accepted value.`,+ })+ @IsOptional()+ @IsIn([SEO_SORT], {+ message: `Search Console always orders rows by clicks descending; omit 'sort' or pass '${SEO_SORT}'`,+ })+ sort?: string+}diff --git a/backend/apps/cloud/src/analytics/v2/mappers/seo.mapper.ts b/backend/apps/cloud/src/analytics/v2/mappers/seo.mapper.tsnew file mode 100644index 000000000..efd1ab46c--- /dev/null+++ b/backend/apps/cloud/src/analytics/v2/mappers/seo.mapper.ts@@ -0,0 +1,221 @@+import countries from 'i18n-iso-countries'+import dayjs from 'dayjs'++import { TimeBucketType } from '../../dto/getData.dto'+import { V2SeoGscDimension } from '../registry/seo'+import { toIsoTimestamp, TimeseriesRow } from './timeseries.mapper'++export interface SeoMetricValues {+ clicks: number+ impressions: number+ ctr: number+ position: number+}++export type SeoDateSeriesEntry = { date: string } & SeoMetricValues++export interface SeoSummaryData {+ current: SeoMetricValues+ previous: SeoMetricValues+ change: SeoMetricValues+}++const round = (value: unknown, precision: number): number => {+ const number = Number(value)++ if (!Number.isFinite(number)) {+ return 0+ }++ const factor = 10 ** precision++ return Math.round(number * factor) / factor+}++const toInteger = (value: unknown): number => Math.round(Number(value) || 0)++/**+ * Search Console reports countries as lowercase ISO 3166-1 alpha-3, while the+ * rest of the v2 surface (and the `cc` column behind the traffic `country`+ * dimension) uses uppercase alpha-2. Normalise so a `country` value means the+ * same thing whichever data type produced it.+ */+export const gscCountryToAlpha2 = (country: string): string => {+ const alpha2 = countries.alpha3ToAlpha2(String(country || '').toUpperCase())++ return alpha2 || String(country || '').toUpperCase()+}++const EMPTY_METRICS: SeoMetricValues = {+ clicks: 0,+ impressions: 0,+ ctr: 0,+ position: 0,+}++const mapSeoMetricValues = (+ values: Partial<SeoMetricValues> | null | undefined,+): SeoMetricValues => ({+ clicks: toInteger(values?.clicks),+ impressions: toInteger(values?.impressions),+ ctr: round(values?.ctr, 2),+ position: round(values?.position, 2),+})++export const mapSeoSummary = (+ current: Partial<SeoMetricValues> | null | undefined,+ previous: Partial<SeoMetricValues> | null | undefined,+): SeoSummaryData => {+ const mappedCurrent = mapSeoMetricValues(current)+ const mappedPrevious = previous ? mapSeoMetricValues(previous) : EMPTY_METRICS++ return {+ current: mappedCurrent,+ previous: mappedPrevious,+ change: {+ clicks: mappedCurrent.clicks - mappedPrevious.clicks,+ impressions: mappedCurrent.impressions - mappedPrevious.impressions,+ ctr: round(mappedCurrent.ctr - mappedPrevious.ctr, 2),+ position: round(mappedCurrent.position - mappedPrevious.position, 2),+ },+ }+}++/**+ * A raw row as returned by one of the GSCService per-dimension getters. They+ * disagree on the label field, and getKeywords calls its click count `count`.+ */+export interface GscBreakdownRow extends Partial<SeoMetricValues> {+ name?: string+ page?: string+ country?: string+ device?: string+ count?: number+}++const readRowValue = (+ dimension: V2SeoGscDimension,+ row: GscBreakdownRow,+): string => {+ if (dimension === 'query') return row.name ?? ''+ if (dimension === 'page') return row.page ?? ''+ if (dimension === 'country') return gscCountryToAlpha2(row.country ?? '')++ return row.device ?? ''+}++export const mapSeoBreakdownRows = (+ dimension: V2SeoGscDimension,+ rows: GscBreakdownRow[],+ metrics: string[],+): Record<string, unknown>[] =>+ rows.map((row) => {+ const values = mapSeoMetricValues({+ clicks: row.clicks ?? row.count,+ impressions: row.impressions,+ ctr: row.ctr,+ position: row.position,+ })++ const mapped: Record<string, unknown> = {+ value: readRowValue(dimension, row),+ }++ for (const metric of metrics) {+ mapped[metric] = values[metric as keyof SeoMetricValues]+ }++ return mapped+ })++const startOfBucket = (date: string, bucket: TimeBucketType): string => {+ const parsed = dayjs(date)++ if (bucket === TimeBucketType.MONTH) {+ return parsed.startOf('month').format('YYYY-MM-DD')+ }++ if (bucket === TimeBucketType.YEAR) {+ return parsed.startOf('year').format('YYYY-MM-DD')+ }++ return date+}++/**+ * Search Console only serves hourly and daily rows, so wider buckets are rolled+ * up here. Clicks and impressions sum; ctr is recomputed from the totals and+ * position is averaged weighted by impressions, since neither is additive.+ */+export const bucketSeoDateSeries = (+ series: SeoDateSeriesEntry[],+ bucket: TimeBucketType,+): SeoDateSeriesEntry[] => {+ if (bucket !== TimeBucketType.MONTH && bucket !== TimeBucketType.YEAR) {+ return series+ }++ const buckets = new Map<+ string,+ { clicks: number; impressions: number; weightedPosition: number }+ >()+ const orderedKeys: string[] = []++ for (const entry of series) {+ if (!entry.date) continue++ const key = startOfBucket(entry.date, bucket)+ const existing = buckets.get(key)++ if (existing) {+ existing.clicks += entry.clicks+ existing.impressions += entry.impressions+ existing.weightedPosition += entry.position * entry.impressions+ } else {+ orderedKeys.push(key)+ buckets.set(key, {+ clicks: entry.clicks,+ impressions: entry.impressions,+ weightedPosition: entry.position * entry.impressions,+ })+ }+ }++ return orderedKeys.map((key) => {+ const entry = buckets.get(key)++ return {+ date: key,+ clicks: Math.round(entry.clicks),+ impressions: Math.round(entry.impressions),+ ctr:+ entry.impressions > 0+ ? round((entry.clicks / entry.impressions) * 100, 2)+ : 0,+ position:+ entry.impressions > 0+ ? round(entry.weightedPosition / entry.impressions, 2)+ : 0,+ }+ })+}++export const mapSeoTimeseries = (+ series: SeoDateSeriesEntry[],+ metrics: string[],+ timezone: string,+): TimeseriesRow[] =>+ series+ .filter((entry) => Boolean(entry.date))+ .map((entry) => {+ const values = mapSeoMetricValues(entry)+ const row: TimeseriesRow = {+ timestamp: toIsoTimestamp(entry.date, timezone),+ }++ for (const metric of metrics) {+ row[metric] = values[metric as keyof SeoMetricValues]+ }++ return row+ })diff --git a/backend/apps/cloud/src/analytics/v2/registry/seo.ts b/backend/apps/cloud/src/analytics/v2/registry/seo.tsnew file mode 100644index 000000000..7128783ee--- /dev/null+++ b/backend/apps/cloud/src/analytics/v2/registry/seo.ts@@ -0,0 +1,193 @@+import { UnprocessableEntityException } from '@nestjs/common'++import { V2Filter } from '../query/filters.translator'++/**+ * SEO data is served by the Google Search Console API rather than ClickHouse,+ * so it cannot join the column/sqlExpr registry in ./dimensions and ./metrics.+ * These definitions mirror that registry's shape and lookup semantics to keep+ * /v2/projects/:pid/seo/* consistent with the rest of the v2 surface.+ */++export type V2SeoGscDimension = 'query' | 'page' | 'country' | 'device'++export interface V2SeoDimensionDef {+ api: string+ gsc: V2SeoGscDimension+ description: string+}++export interface V2SeoMetricDef {+ api: string+ isDefault?: boolean+ format: 'integer' | 'percent' | 'position'+ description: string+}++export const V2_SEO_DIMENSIONS: V2SeoDimensionDef[] = [+ {+ api: 'query',+ gsc: 'query',+ description: 'Search query the site was surfaced for',+ },+ {+ api: 'page',+ gsc: 'page',+ description: 'Landing page URL that appeared in search results',+ },+ {+ api: 'country',+ gsc: 'country',+ description: 'Country the search was made from (ISO 3166-1 alpha-2 code)',+ },+ {+ api: 'device',+ gsc: 'device',+ description: 'Device category the search was made on',+ },+]++const V2_SEO_METRICS: V2SeoMetricDef[] = [+ {+ api: 'clicks',+ isDefault: true,+ format: 'integer',+ description: 'Clicks through to the site from search results',+ },+ {+ api: 'impressions',+ isDefault: true,+ format: 'integer',+ description: 'Times a link to the site appeared in search results',+ },+ {+ api: 'ctr',+ isDefault: true,+ format: 'percent',+ description: 'Click-through rate, as a percentage of impressions',+ },+ {+ api: 'position',+ isDefault: true,+ format: 'position',+ description: 'Average position in search results',+ },+]++export const listSeoDimensions = (): V2SeoDimensionDef[] => V2_SEO_DIMENSIONS++export const listSeoMetrics = (): V2SeoMetricDef[] => V2_SEO_METRICS++const findSeoDimension = (api: string): V2SeoDimensionDef | undefined =>+ V2_SEO_DIMENSIONS.find((dimension) => dimension.api === api)++export const getSeoBreakdownDimension = (api: string): V2SeoDimensionDef => {+ const dimension = findSeoDimension(api)++ if (!dimension) {+ throw new UnprocessableEntityException(+ `Unknown seo dimension '${api}'. Supported dimensions: ${V2_SEO_DIMENSIONS.map(+ (d) => d.api,+ ).join(', ')}`,+ )+ }++ return dimension+}++export const getSeoMetric = (api: string): V2SeoMetricDef => {+ const metric = V2_SEO_METRICS.find((m) => m.api === api)++ if (!metric) {+ throw new UnprocessableEntityException(+ `Unknown seo metric '${api}'. Supported metrics: ${V2_SEO_METRICS.map(+ (m) => m.api,+ ).join(', ')}`,+ )+ }++ return metric+}++export const getDefaultSeoMetrics = (): V2SeoMetricDef[] =>+ V2_SEO_METRICS.filter((metric) => metric.isDefault)++export const parseSeoMetricsParam = (+ metrics: string | undefined,+): V2SeoMetricDef[] => {+ if (!metrics) {+ return getDefaultSeoMetrics()+ }++ const names = [+ ...new Set(+ metrics+ .split(',')+ .map((name) => name.trim())+ .filter(Boolean),+ ),+ ]++ if (names.length === 0) {+ return getDefaultSeoMetrics()+ }++ return names.map((name) => getSeoMetric(name))+}++/**+ * Search Console orders rows by clicks descending and exposes no sort control,+ * so this is the only ordering the seo breakdown can honour. It is accepted+ * (rather than rejected outright) so callers can be explicit about it.+ */+export const SEO_SORT = 'clicks:desc'++/**+ * GSCService.parseFilters keys filters by their v1 URL names, where the keyword+ * dimension is 'keywords'. v2 calls it 'query', after Search Console's own+ * naming, so translate on the way down — the same v2 -> v1 hop the ClickHouse+ * data types make through toV1FiltersJson.+ */+export const toGscFiltersJson = (filters: V2Filter[]): string | undefined => {+ if (filters.length === 0) {+ return undefined+ }++ return JSON.stringify(+ filters.map((filter) => ({+ ...filter,+ dimension: filter.dimension === 'query' ? 'keywords' : filter.dimension,+ })),+ )+}++/**+ * Search Console expresses filters as dimensionFilterGroups of scalar+ * comparisons, so the array / null values the rest of v2 accepts have no+ * equivalent here. Reject them rather than silently dropping the filter.+ */+export const validateSeoFilters = (filters: V2Filter[]): V2Filter[] => {+ for (const filter of filters) {+ if (!findSeoDimension(filter.dimension)) {+ throw new UnprocessableEntityException(+ `Unknown seo filter dimension '${filter.dimension}'. Supported dimensions: ${V2_SEO_DIMENSIONS.map(+ (d) => d.api,+ ).join(', ')}`,+ )+ }++ if (Array.isArray(filter.value)) {+ throw new UnprocessableEntityException(+ `The seo filter on '${filter.dimension}' cannot take an array of values; Search Console only supports a single value per filter`,+ )+ }++ if (filter.value === null) {+ throw new UnprocessableEntityException(+ `The seo filter on '${filter.dimension}' cannot take a null value; Search Console does not report unset dimension values`,+ )+ }+ }++ return filters+}diff --git a/backend/apps/cloud/src/analytics/v2/seo-v2.service.ts b/backend/apps/cloud/src/analytics/v2/seo-v2.service.tsnew file mode 100644index 000000000..a8261e0a3--- /dev/null+++ b/backend/apps/cloud/src/analytics/v2/seo-v2.service.ts@@ -0,0 +1,512 @@+import {+ BadRequestException,+ ConflictException,+ Injectable,+ UnprocessableEntityException,+} from '@nestjs/common'+import dayjs from 'dayjs'+import utc from 'dayjs/plugin/utc'++import {+ BrandedTrafficAnalytics,+ GSC_ALL_TIME_DAYS,+ GSCContext,+ GSCService,+ MAX_BRANDED_TRAFFIC_RANGE_DAYS,+ MAX_FILTER_EXPRESSION_LENGTH,+ MAX_FILTERS,+ MAX_POSITION_ANALYTICS_RANGE_DAYS,+ OPTIONAL_ANALYTICS_TIMEOUT_MS,+ PositionAnalytics,+} from '../../project/gsc.service'+import { AnalyticsService } from '../analytics.service'+import { TimeBucketType } from '../dto/getData.dto'+import {+ V2SeoBreakdownDto,+ V2SeoRangeDto,+ V2SeoSummaryDto,+ V2SeoTimeseriesDto,+ V2_SEO_TIME_BUCKETS,+} from './dto/seo.dto'+import { V2_DEFAULT_PERIOD, V2BaseQueryDto } from './dto/v2-base.dto'+import { envelope, V2Envelope } from './mappers/envelope'+import {+ bucketSeoDateSeries,+ mapSeoBreakdownRows,+ mapSeoSummary,+ mapSeoTimeseries,+ SeoDateSeriesEntry,+ SeoSummaryData,+} from './mappers/seo.mapper'+import { toIsoTimestamp, TimeseriesRow } from './mappers/timeseries.mapper'+import { parseV2Filters, V2Filter } from './query/filters.translator'+import {+ getSeoBreakdownDimension,+ listSeoDimensions,+ listSeoMetrics,+ parseSeoMetricsParam,+ SEO_SORT,+ toGscFiltersJson,+ validateSeoFilters,+} from './registry/seo'++dayjs.extend(utc)++const DEFAULT_SEO_BREAKDOWN_LIMIT = 30++const INTRADAY_PERIODS = ['1h', 'today', 'yesterday', '1d']++interface SeoTimeframe {+ period: string | null+ timeBucket: TimeBucketType+ safeTimezone: string+ groupFrom: string+ groupTo: string+ rangeDays: number+}++const SKIPPED = Symbol('skipped')++/**+ * Runs an expensive Search Console rollup under a deadline. A timeout aborts+ * the in-flight paging and reports the panel as skipped; a genuine upstream+ * failure still propagates, so a broken panel reads as broken rather than as+ * "too much data".+ */+const resolveOptional = async <T>(+ load: (signal: AbortSignal) => Promise<T>,+): Promise<T | typeof SKIPPED> => {+ const controller = new AbortController()+ let timeout: ReturnType<typeof setTimeout> | undefined++ const loading = load(controller.signal)++ // Aborting rejects `loading` after the race has already settled on SKIPPED;+ // this keeps that late rejection from surfacing as an unhandled rejection+ // without stopping Promise.race from seeing a real, pre-deadline failure.+ loading.catch(() => {})++ try {+ return await Promise.race([+ loading,+ new Promise<typeof SKIPPED>((resolve) => {+ timeout = setTimeout(() => {+ controller.abort()+ resolve(SKIPPED)+ }, OPTIONAL_ANALYTICS_TIMEOUT_MS)+ }),+ ])+ } finally {+ if (timeout) {+ clearTimeout(timeout)+ }+ }+}++@Injectable()+export class SeoV2Service {+ constructor(+ private readonly gscService: GSCService,+ private readonly analyticsService: AnalyticsService,+ ) {}++ /**+ * Search Console has to be connected and a property linked before any of the+ * data endpoints can answer. Both are project configuration rather than a bad+ * request, hence 409 rather than 400.+ *+ * Call this only after the request itself has been validated: a malformed+ * filter is a 422 whether or not the project happens to be connected, and+ * answering 409 first would send callers debugging their query down the+ * wrong path.+ */+ private async requireContext(pid: string): Promise<GSCContext> {+ const { connected, property } =+ await this.gscService.getConnectionState(pid)++ if (!connected) {+ throw new ConflictException(+ 'Google Search Console is not connected for this project',+ )+ }++ if (!property) {+ throw new ConflictException(+ 'No Google Search Console property is linked to this project',+ )+ }++ return this.gscService.getGSCContext(pid)+ }++ private prepareFilters(filters: string | undefined): {+ appliedFilters: V2Filter[]+ gscFilters: string | undefined+ } {+ const appliedFilters = validateSeoFilters(parseV2Filters(filters))++ if (appliedFilters.length > MAX_FILTERS) {+ throw new UnprocessableEntityException(+ `Too many filters; at most ${MAX_FILTERS} may be applied at once`,+ )+ }++ for (const filter of appliedFilters) {+ if (String(filter.value).length > MAX_FILTER_EXPRESSION_LENGTH) {+ throw new UnprocessableEntityException(+ `The seo filter on '${filter.dimension}' has a value longer than ${MAX_FILTER_EXPRESSION_LENGTH} characters`,+ )+ }+ }++ // GSCService.parseFilters already understands the v2 filter shape, so the+ // validated filters are handed straight back to it, mirroring how the+ // ClickHouse data types translate v2 -> v1 JSON -> getFiltersQuery.+ return { appliedFilters, gscFilters: toGscFiltersJson(appliedFilters) }+ }++ private resolveTimeframe(+ dto: V2BaseQueryDto,+ requestedBucket?: TimeBucketType,+ ): SeoTimeframe {+ const { from, to, timezone } = dto+ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)++ if (Boolean(from) !== Boolean(to)) {+ throw new BadRequestException(+ "The 'from' and 'to' parameters must be provided together",+ )+ }++ const hasCustomRange = Boolean(from && to)+ const period = hasCustomRange+ ? null+ : dto.period && dto.period !== 'custom'+ ? dto.period+ : V2_DEFAULT_PERIOD++ const timeBucket =+ requestedBucket ??+ (period && INTRADAY_PERIODS.includes(period)+ ? TimeBucketType.HOUR+ : TimeBucketType.DAY)++ // getGroupFromTo validates the bucket against the range, which neither an+ // open-ended 'all' nor a caller-chosen custom range can satisfy.+ const groupTimeBucket =+ hasCustomRange || period === 'all' ? null : timeBucket+ const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined++ const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(+ hasCustomRange ? from : undefined,+ hasCustomRange ? to : undefined,+ groupTimeBucket,+ period ?? undefined,+ safeTimezone,+ diff,+ )++ const rangeDays =+ Math.abs(+ dayjs(groupTo)+ .startOf('day')+ .diff(dayjs(groupFrom).startOf('day'), 'day'),+ ) + 1++ return { period, timeBucket, safeTimezone, groupFrom, groupTo, rangeDays }+ }++ private baseMeta(+ pid: string,+ timeframe: SeoTimeframe,+ appliedFilters: V2Filter[],+ ): Record<string, unknown> {+ return {+ pid,+ period: timeframe.period,+ from: toIsoTimestamp(timeframe.groupFrom, timeframe.safeTimezone),+ to: toIsoTimestamp(timeframe.groupTo, timeframe.safeTimezone),+ timezone: timeframe.safeTimezone,+ appliedFilters,+ }+ }++ async getStatus(+ pid: string,+ ): Promise<V2Envelope<{ connected: boolean; property: string | null }>> {+ const state = await this.gscService.getConnectionState(pid)++ return envelope(state, { pid })+ }++ /**+ * Mirrors AnalyticsV2Service.getDimensions so `?type=seo` answers in the same+ * shape as every other data type on the discovery endpoint.+ */+ getDimensions(): V2Envelope<{+ dimensions: Record<string, unknown>[]+ metrics: Record<string, unknown>[]+ }> {+ const dimensions = listSeoDimensions().map((dimension) => ({+ name: dimension.api,+ description: dimension.description,+ filterOnly: false,+ extraFields: [] as string[],+ }))++ const metrics = listSeoMetrics().map((metric) => ({+ name: metric.api,+ description: metric.description,+ format: metric.format,+ default: Boolean(metric.isDefault),+ }))++ return envelope({ dimensions, metrics }, { type: 'seo' })+ }++ async getSummary(+ pid: string,+ dto: V2SeoSummaryDto,+ ): Promise<V2Envelope<SeoSummaryData>> {+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const timeframe = this.resolveTimeframe(dto)+ const ctx = await this.requireContext(pid)+ const { groupFrom, groupTo } = timeframe++ const fromDate = dayjs(groupFrom)+ const durationMs = dayjs(groupTo).diff(fromDate)+ const previousTo = fromDate+ .subtract(1, 'millisecond')+ .format('YYYY-MM-DD HH:mm:ss')+ const previousFrom = fromDate+ .subtract(durationMs, 'millisecond')+ .format('YYYY-MM-DD HH:mm:ss')++ const [current, previous] = await Promise.all([+ this.gscService.getSummary(pid, groupFrom, groupTo, gscFilters, ctx),+ this.gscService+ .getSummary(pid, previousFrom, previousTo, gscFilters, ctx)+ .catch(() => null),+ ])++ return envelope(mapSeoSummary(current, previous), {+ ...this.baseMeta(pid, timeframe, appliedFilters),+ metrics: listSeoMetrics().map((metric) => metric.api),+ })+ }++ async getTimeseries(+ pid: string,+ dto: V2SeoTimeseriesDto,+ ): Promise<V2Envelope<TimeseriesRow[]>> {+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const metrics = parseSeoMetricsParam(dto.metrics).map(+ (metric) => metric.api,+ )+ const timeframe = this.resolveTimeframe(+ dto,+ dto.timeBucket as TimeBucketType | undefined,+ )+ const ctx = await this.requireContext(pid)++ // Search Console only serves hourly and daily rows; wider buckets are+ // rolled up from the daily series rather than requested upstream.+ const series = (await this.gscService.getDateSeries(+ pid,+ timeframe.groupFrom,+ timeframe.groupTo,+ timeframe.timeBucket === TimeBucketType.HOUR ? 'hour' : 'day',+ gscFilters,+ ctx,+ )) as SeoDateSeriesEntry[]++ const bucketed = bucketSeoDateSeries(series, timeframe.timeBucket)++ return envelope(+ mapSeoTimeseries(bucketed, metrics, timeframe.safeTimezone),+ {+ ...this.baseMeta(pid, timeframe, appliedFilters),+ metrics,+ timeBucket: timeframe.timeBucket,+ allowedTimeBuckets: [...V2_SEO_TIME_BUCKETS],+ },+ )+ }++ async getBreakdown(+ pid: string,+ dto: V2SeoBreakdownDto,+ ): Promise<V2Envelope<Record<string, unknown>[]>> {+ const dimension = getSeoBreakdownDimension(dto.dimension)+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const metrics = parseSeoMetricsParam(dto.metrics).map(+ (metric) => metric.api,+ )+ const timeframe = this.resolveTimeframe(dto)+ const limit = dto.limit ?? DEFAULT_SEO_BREAKDOWN_LIMIT+ const offset = dto.offset ?? 0+ const ctx = await this.requireContext(pid)+ const { groupFrom, groupTo } = timeframe++ const rows = await this.fetchBreakdownRows(+ dimension.gsc,+ pid,+ groupFrom,+ groupTo,+ limit,+ offset,+ gscFilters,+ ctx,+ )++ return envelope(mapSeoBreakdownRows(dimension.gsc, rows, metrics), {+ ...this.baseMeta(pid, timeframe, appliedFilters),+ dimension: dimension.api,+ metrics,+ limit,+ offset,+ sort: SEO_SORT,+ })+ }++ private fetchBreakdownRows(+ dimension: 'query' | 'page' | 'country' | 'device',+ pid: string,+ from: string,+ to: string,+ limit: number,+ offset: number,+ filters: string | undefined,+ ctx: GSCContext,+ ) {+ if (dimension === 'query') {+ return this.gscService.getKeywords(+ pid,+ from,+ to,+ limit,+ offset,+ filters,+ undefined,+ ctx,+ )+ }++ if (dimension === 'page') {+ return this.gscService.getTopPages(+ pid,+ from,+ to,+ limit,+ offset,+ filters,+ undefined,+ ctx,+ )+ }++ if (dimension === 'country') {+ return this.gscService.getTopCountries(+ pid,+ from,+ to,+ limit,+ offset,+ filters,+ ctx,+ )+ }++ return this.gscService.getTopDevices(+ pid,+ from,+ to,+ limit,+ offset,+ filters,+ ctx,+ )+ }++ async getBrandedTraffic(+ pid: string,+ dto: V2SeoRangeDto,+ ): Promise<V2Envelope<BrandedTrafficAnalytics | null>> {+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const timeframe = this.resolveTimeframe(dto)+ const ctx = await this.requireContext(pid)+ const meta = this.baseMeta(pid, timeframe, appliedFilters)++ if (timeframe.rangeDays > MAX_BRANDED_TRAFFIC_RANGE_DAYS) {+ return envelope(null, {+ ...meta,+ skipped: true,+ skippedReason: 'range_too_large',+ maxRangeDays: MAX_BRANDED_TRAFFIC_RANGE_DAYS,+ })+ }++ const result = await resolveOptional((signal) =>+ this.gscService.getBrandedTraffic(+ pid,+ timeframe.groupFrom,+ timeframe.groupTo,+ gscFilters,+ ctx,+ signal,+ ),+ )++ if (result === SKIPPED) {+ return envelope(null, {+ ...meta,+ skipped: true,+ skippedReason: 'timeout',+ timeoutMs: OPTIONAL_ANALYTICS_TIMEOUT_MS,+ })+ }++ return envelope(result, { ...meta, skipped: false })+ }++ async getPositions(+ pid: string,+ dto: V2SeoRangeDto,+ ): Promise<V2Envelope<PositionAnalytics | null>> {+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const timeframe = this.resolveTimeframe(dto)+ const ctx = await this.requireContext(pid)+ const meta = this.baseMeta(pid, timeframe, appliedFilters)++ if (timeframe.rangeDays > MAX_POSITION_ANALYTICS_RANGE_DAYS) {+ return envelope(null, {+ ...meta,+ skipped: true,+ skippedReason: 'range_too_large',+ maxRangeDays: MAX_POSITION_ANALYTICS_RANGE_DAYS,+ })+ }++ const result = await resolveOptional((signal) =>+ this.gscService.getPositionAnalytics(+ pid,+ timeframe.groupFrom,+ timeframe.groupTo,+ gscFilters,+ ctx,+ signal,+ ),+ )++ if (result === SKIPPED) {+ return envelope(null, {+ ...meta,+ skipped: true,+ skippedReason: 'timeout',+ timeoutMs: OPTIONAL_ANALYTICS_TIMEOUT_MS,+ })+ }++ return envelope(result, { ...meta, skipped: false })+ }+}diff --git a/backend/apps/cloud/src/project/gsc.service.ts b/backend/apps/cloud/src/project/gsc.service.tsindex 41eff7995..851c2996b 100644--- a/backend/apps/cloud/src/project/gsc.service.ts+++ b/backend/apps/cloud/src/project/gsc.service.ts@@ -39,11 +39,17 @@ const ENCRYPTION_KEY = deriveKey('gsc-token')const MAX_ROW_LIMIT = 25000const MAX_BRANDED_PAGES = 10-const MAX_FILTER_EXPRESSION_LENGTH = 500-const MAX_FILTERS = 20-const MAX_BRANDED_TRAFFIC_RANGE_DAYS = 31-const MAX_POSITION_ANALYTICS_RANGE_DAYS = 31-const OPTIONAL_ANALYTICS_TIMEOUT_MS = 12000+export const MAX_FILTER_EXPRESSION_LENGTH = 500+export const MAX_FILTERS = 20+export const MAX_BRANDED_TRAFFIC_RANGE_DAYS = 31+export const MAX_POSITION_ANALYTICS_RANGE_DAYS = 31+export const OPTIONAL_ANALYTICS_TIMEOUT_MS = 12000++/**+ * Search Console keeps roughly 16 months of history, so an 'all' period is+ * resolved against a fixed window rather than the project's first event.+ */+export const GSC_ALL_TIME_DAYS = 480const IMPRESSION_POSITION_BUCKETS = [{ key: 'pos1To3', label: '1-3' },@@ -67,13 +73,8 @@ type OrganicPositionSeriesEntry = { date: string } & Record<OrganicPositionBucketKey,number>-type BrandedTrafficAnalytics = { branded: number; nonBranded: number }-type SkippedBrandedAnalytics = {- skipped: true- branded: null- nonBranded: null-}-type PositionAnalytics = {+export type BrandedTrafficAnalytics = { branded: number; nonBranded: number }+export type PositionAnalytics = {impressionsByPosition: {key: ImpressionPositionBucketKeylabel: string@@ -82,23 +83,6 @@ type PositionAnalytics = {}[]organicPositions: OrganicPositionSeriesEntry[]}-type SkippedPositionAnalytics = {- skipped: true- impressionsByPosition: null- organicPositions: null-}--const SKIPPED_BRANDED_ANALYTICS: SkippedBrandedAnalytics = {- skipped: true,- branded: null,- nonBranded: null,-}--const SKIPPED_POSITION_ANALYTICS: SkippedPositionAnalytics = {- skipped: true,- impressionsByPosition: null,- organicPositions: null,-}const initialImpressionPositionBuckets = (): Record<ImpressionPositionBucketKey,@@ -140,32 +124,6 @@ const getOrganicPositionBucketKey = (return 'pos51Plus'}-const resolveOptionalAnalytics = async <T>(- load: (signal: AbortSignal) => Promise<T>,- fallback: T,-): Promise<T> => {- const controller = new AbortController()- let timeout: ReturnType<typeof setTimeout> | undefined-- try {- return await Promise.race([- load(controller.signal),- new Promise<T>((resolve) => {- timeout = setTimeout(() => {- controller.abort()- resolve(fallback)- }, OPTIONAL_ANALYTICS_TIMEOUT_MS)- }),- ])- } catch {- return fallback- } finally {- if (timeout) {- clearTimeout(timeout)- }- }-}-type GSCRow = {keys: string[]clicks?: number@@ -174,7 +132,7 @@ type GSCRow = {position?: number}-type GSCContext = {+export type GSCContext = {sc: ReturnType<typeof searchconsole>siteUrl: string}@@ -398,6 +356,23 @@ export class GSCService {return { connected, email: project?.gscAccountEmail || null }}+ /**+ * Whether the project can currently be queried: an account must be connected+ * and one of its properties linked. Unlike getStatus this needs no account+ * email, so it is safe to expose to anyone with project read access.+ */+ async getConnectionState(+ pid: string,+ ): Promise<{ connected: boolean; property: string | null }> {+ const tokens = await this.getStoredTokens(pid)+ const connected = !_isEmpty(tokens?.refresh_token || tokens?.access_token)++ return {+ connected,+ property: connected ? tokens.property_uri || null : null,+ }+ }+private async getAuthedClientForPid(pid: string) {const tokens = await this.getStoredTokens(pid)if (_isEmpty(tokens)) {@@ -426,7 +401,7 @@ export class GSCService {return oauth2Client}- private async getGSCContext(pid: string): Promise<GSCContext> {+ async getGSCContext(pid: string): Promise<GSCContext> {const tokens = await this.getStoredTokens(pid)if (_isEmpty(tokens) || _isEmpty(tokens.property_uri)) {throw new BadRequestException(@@ -1185,97 +1160,4 @@ export class GSCService {)}}-- async getDashboard(- pid: string,- from: string,- to: string,- timeBucket?: string,- filtersStr?: string,- ) {- const connected = await this.isConnected(pid)- if (!connected) {- return { notConnected: true }- }-- const tokens = await this.getStoredTokens(pid)- if (_isEmpty(tokens.property_uri)) {- return { notConnected: true, noProperty: true }- }-- let ctx: GSCContext- try {- ctx = await this.getGSCContext(pid)- } catch {- return { notConnected: true }- }-- const fromDate = dayjs(from)- const toDate = dayjs(to)- const durationMs = toDate.diff(fromDate)- const rangeDays =- Math.abs(toDate.startOf('day').diff(fromDate.startOf('day'), 'day')) + 1- const shouldLoadBrandedTraffic = rangeDays <= MAX_BRANDED_TRAFFIC_RANGE_DAYS- const shouldLoadPositionAnalytics =- rangeDays <= MAX_POSITION_ANALYTICS_RANGE_DAYS- const prevTo = fromDate- .subtract(1, 'millisecond')- .format('YYYY-MM-DD HH:mm:ss')- const prevFrom = fromDate- .subtract(durationMs, 'millisecond')- .format('YYYY-MM-DD HH:mm:ss')-- const [- summary,- previousSummary,- dateSeries,- topPages,- topQueries,- topCountries,- topDevices,- brandedTraffic,- positionAnalytics,- ] = await Promise.all([- this.getSummary(pid, from, to, filtersStr, ctx),- this.getSummary(pid, prevFrom, prevTo, filtersStr, ctx).catch(() => null),- this.getDateSeries(pid, from, to, timeBucket, filtersStr, ctx),- this.getTopPages(pid, from, to, 50, 0, filtersStr, undefined, ctx),- this.getKeywords(pid, from, to, 50, 0, filtersStr, undefined, ctx),- this.getTopCountries(pid, from, to, 50, 0, filtersStr, ctx),- this.getTopDevices(pid, from, to, 50, 0, filtersStr, ctx),- shouldLoadBrandedTraffic- ? resolveOptionalAnalytics<- BrandedTrafficAnalytics | SkippedBrandedAnalytics- >(- (signal) =>- this.getBrandedTraffic(pid, from, to, filtersStr, ctx, signal),- SKIPPED_BRANDED_ANALYTICS,- )- : Promise.resolve(SKIPPED_BRANDED_ANALYTICS),- shouldLoadPositionAnalytics- ? resolveOptionalAnalytics<- PositionAnalytics | SkippedPositionAnalytics- >(- (signal) =>- this.getPositionAnalytics(pid, from, to, filtersStr, ctx, signal),- SKIPPED_POSITION_ANALYTICS,- )- : Promise.resolve(SKIPPED_POSITION_ANALYTICS),- ])-- return {- notConnected: false,- summary,- previousSummary,- dateSeries,- topPages,- topQueries,- topCountries,- topDevices,- brandedTraffic,- positionAnalyticsSkipped: 'skipped' in positionAnalytics,- impressionsByPosition: positionAnalytics.impressionsByPosition,- organicPositions: positionAnalytics.organicPositions,- }- }}diff --git a/backend/apps/community/src/analytics/analytics.controller.ts b/backend/apps/community/src/analytics/analytics.controller.tsindex 9c1f8a5e9..61bc50b40 100644--- a/backend/apps/community/src/analytics/analytics.controller.ts+++ b/backend/apps/community/src/analytics/analytics.controller.ts@@ -42,7 +42,7 @@ import { DEFAULT_TIMEZONE } from '../user/entities/user.entity'import { AuthenticationGuard } from '../auth/guards/authentication.guard'import { PageviewsDto } from './dto/pageviews.dto'import { EventsDto } from './dto/events.dto'-import { GetDataDto, ChartRenderMode, TimeBucketType } from './dto/getData.dto'+import { GetDataDto, ChartRenderMode } from './dto/getData.dto'import { GetFiltersDto } from './dto/get-filters.dto'import { DataDeletionDto } from './dto/data-deletion.dto'import { GetVersionFiltersDto } from './dto/get-version-filters.dto'@@ -79,7 +79,7 @@ import { GetHeartbeatStatsDto } from './dto/get-heartbeat-stats'import { LiveVisitorsDto } from './dto/live-visitors.dto'import { NoscriptDto } from './dto/noscript.dto'import { GetKeywordsDto } from './dto/get-keywords.dto'-import { GSCService } from '../project/gsc.service'+import { GSC_ALL_TIME_DAYS, GSCService } from '../project/gsc.service'import { ExperimentService } from '../experiment/experiment.service'import { getExperimentVariant } from '../feature-flag/evaluation'@@ -94,9 +94,6 @@ const BOT_RESPONSE = { message: 'Bot traffic detected, request is ignored' }const ONLINE_VISITORS_WINDOW_MINUTES = 5 // minutes-// Maximum range for "all time" GSC queries (~16 months, GSC's data retention)-const GSC_ALL_TIME_DAYS = 480-// Performance object validator: none of the values cannot be bigger than 1000 * 60 * 5 (5 minutes) and are >= 0const MAX_PERFORMANCE_VALUE = 1000 * 60 * 5const isPerformanceValid = (perf: any) => {@@ -2864,133 +2861,4 @@ export class AnalyticsController {const keywords = await this.gscService.getKeywords(pid, groupFrom, groupTo)return { keywords }}-- @Get('gsc-dashboard')- @Auth(true, true)- async getGSCDashboard(- @Query() data: GetKeywordsDto,- @CurrentUserId() uid: string,- @Headers() headers: { 'x-password'?: string },- ) {- const {- pid,- period,- from,- to,- timezone = DEFAULT_TIMEZONE,- timeBucket,- filters,- } = data-- await this.analyticsService.checkProjectAccess(- pid,- uid,- headers['x-password'],- )-- const defaultTimeBucket = ['1h', 'today', 'yesterday', '1d'].includes(- period,- )- ? TimeBucketType.HOUR- : TimeBucketType.DAY- const finalTimeBucket = (timeBucket || defaultTimeBucket) as TimeBucketType- let groupTimeBucket: TimeBucketType | null = finalTimeBucket- if (period === 'all' || period === 'custom') {- groupTimeBucket = null- }-- this.logger.log(- `pid: ${pid}, period: ${period}, timeBucket: ${finalTimeBucket}, filters: ${filters}`,- 'GET /analytics/gsc-dashboard',- )-- const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined-- const safeTimezone = this.analyticsService.getSafeTimezone(timezone)- const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(- from,- to,- groupTimeBucket,- period,- safeTimezone,- diff,- )-- return this.gscService.getDashboard(- pid,- groupFrom,- groupTo,- finalTimeBucket,- filters,- )- }-- @Get('gsc-details')- @Auth(true, true)- async getGSCDetails(- @Query() data: GetKeywordsDto,- @CurrentUserId() uid: string,- @Headers() headers: { 'x-password'?: string },- ) {- const {- pid,- period,- from,- to,- timezone = DEFAULT_TIMEZONE,- page,- query,- } = data-- this.logger.log(- `pid: ${pid}, period: ${period}, page: ${page}, query: ${query}`,- 'GET /analytics/gsc-details',- )-- await this.analyticsService.checkProjectAccess(- pid,- uid,- headers['x-password'],- )-- const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined-- const safeTimezone = this.analyticsService.getSafeTimezone(timezone)- const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(- from,- to,- null,- period,- safeTimezone,- diff,- )-- if (page) {- const keywords = await this.gscService.getKeywords(- pid,- groupFrom,- groupTo,- 50,- 0,- undefined,- page,- )- return { type: 'queries', data: keywords }- }-- if (query) {- const pages = await this.gscService.getTopPages(- pid,- groupFrom,- groupTo,- 50,- 0,- undefined,- query,- )- return { type: 'pages', data: pages }- }-- return { type: 'none', data: [] }- }}diff --git a/backend/apps/community/src/analytics/analytics.module.ts b/backend/apps/community/src/analytics/analytics.module.tsindex da9d6ce47..413e1b5df 100644--- a/backend/apps/community/src/analytics/analytics.module.ts+++ b/backend/apps/community/src/analytics/analytics.module.ts@@ -11,6 +11,7 @@ import { AppLoggerModule } from '../logger/logger.module'import { ProjectModule } from '../project/project.module'import { ExperimentModule } from '../experiment/experiment.module'import { AnalyticsV2Service } from './v2/analytics-v2.service'+import { SeoV2Service } from './v2/seo-v2.service'import { TrafficV2Controller } from './v2/controllers/traffic-v2.controller'import { PerformanceV2Controller } from './v2/controllers/performance-v2.controller'import { CaptchaV2Controller } from './v2/controllers/captcha-v2.controller'@@ -18,12 +19,14 @@ import { ErrorsV2Controller } from './v2/controllers/errors-v2.controller'import { SessionsV2Controller } from './v2/controllers/sessions-v2.controller'import { ProfilesV2Controller } from './v2/controllers/profiles-v2.controller'import { ProjectV2Controller } from './v2/controllers/project-v2.controller'+import { SeoV2Controller } from './v2/controllers/seo-v2.controller'@Module({imports: [AppLoggerModule, ProjectModule, forwardRef(() => ExperimentModule)],providers: [AnalyticsService,AnalyticsV2Service,+ SeoV2Service,BotDetectionService,SaltService,HeartbeatGateway,@@ -40,6 +43,7 @@ import { ProjectV2Controller } from './v2/controllers/project-v2.controller'SessionsV2Controller,ProfilesV2Controller,ProjectV2Controller,+ SeoV2Controller,],})export class AnalyticsModule {}diff --git a/backend/apps/community/src/analytics/protection/public-project-cache.interceptor.ts b/backend/apps/community/src/analytics/protection/public-project-cache.interceptor.tsindex 57ee4c8cf..431b281e7 100644--- a/backend/apps/community/src/analytics/protection/public-project-cache.interceptor.ts+++ b/backend/apps/community/src/analytics/protection/public-project-cache.interceptor.ts@@ -33,8 +33,6 @@ const CACHEABLE_ROUTES = new Set(['funnel-sessions','custom-events','keywords',- 'gsc-dashboard',- 'gsc-details',])@Injectable()diff --git a/backend/apps/community/src/analytics/v2/__tests__/seo.mapper.spec.ts b/backend/apps/community/src/analytics/v2/__tests__/seo.mapper.spec.tsnew file mode 100644index 000000000..d90e11b99--- /dev/null+++ b/backend/apps/community/src/analytics/v2/__tests__/seo.mapper.spec.ts@@ -0,0 +1,210 @@+import { TimeBucketType } from '../../dto/getData.dto'+import {+ bucketSeoDateSeries,+ gscCountryToAlpha2,+ mapSeoBreakdownRows,+ mapSeoSummary,+ mapSeoTimeseries,+ SeoDateSeriesEntry,+} from '../mappers/seo.mapper'++const day = (+ date: string,+ clicks: number,+ impressions: number,+ position: number,+): SeoDateSeriesEntry => ({+ date,+ clicks,+ impressions,+ position,+ ctr: impressions > 0 ? (clicks / impressions) * 100 : 0,+})++describe('gscCountryToAlpha2', () => {+ it('converts Search Console alpha-3 to the alpha-2 the rest of v2 uses', () => {+ expect(gscCountryToAlpha2('usa')).toBe('US')+ expect(gscCountryToAlpha2('deu')).toBe('DE')+ expect(gscCountryToAlpha2('ukr')).toBe('UA')+ })++ it('passes through anything it cannot map rather than dropping the row', () => {+ expect(gscCountryToAlpha2('zzz')).toBe('ZZZ')+ expect(gscCountryToAlpha2('')).toBe('')+ })+})++describe('mapSeoBreakdownRows', () => {+ it("reads getKeywords' `count` as clicks", () => {+ expect(+ mapSeoBreakdownRows(+ 'query',+ [+ {+ name: 'swetrix',+ count: 12,+ impressions: 400,+ ctr: 3,+ position: 4.2,+ },+ ],+ ['clicks', 'impressions', 'ctr', 'position'],+ ),+ ).toEqual([+ { value: 'swetrix', clicks: 12, impressions: 400, ctr: 3, position: 4.2 },+ ])+ })++ it('reads the label field each per-dimension getter returns', () => {+ expect(+ mapSeoBreakdownRows('page', [{ page: '/blog', clicks: 5 }], ['clicks']),+ ).toEqual([{ value: '/blog', clicks: 5 }])++ expect(+ mapSeoBreakdownRows(+ 'device',+ [{ device: 'mobile', clicks: 3 }],+ ['clicks'],+ ),+ ).toEqual([{ value: 'mobile', clicks: 3 }])+ })++ it('normalises country rows to alpha-2', () => {+ expect(+ mapSeoBreakdownRows(+ 'country',+ [{ country: 'usa', clicks: 9 }],+ ['clicks'],+ ),+ ).toEqual([{ value: 'US', clicks: 9 }])+ })++ it('only emits the requested metrics', () => {+ expect(+ mapSeoBreakdownRows(+ 'query',+ [{ name: 'a', count: 1, impressions: 2, ctr: 50, position: 1 }],+ ['clicks'],+ ),+ ).toEqual([{ value: 'a', clicks: 1 }])+ })++ it('defaults missing values to zero rather than emitting NaN', () => {+ expect(+ mapSeoBreakdownRows('query', [{ name: 'a' }], ['clicks', 'position']),+ ).toEqual([{ value: 'a', clicks: 0, position: 0 }])+ })+})++describe('mapSeoSummary', () => {+ it('reports the absolute change between periods, matching the other v2 summaries', () => {+ expect(+ mapSeoSummary(+ { clicks: 120, impressions: 3000, ctr: 4, position: 8.1 },+ { clicks: 100, impressions: 2500, ctr: 4.5, position: 9.4 },+ ),+ ).toEqual({+ current: { clicks: 120, impressions: 3000, ctr: 4, position: 8.1 },+ previous: { clicks: 100, impressions: 2500, ctr: 4.5, position: 9.4 },+ change: { clicks: 20, impressions: 500, ctr: -0.5, position: -1.3 },+ })+ })++ it('treats a missing previous period as zeroes', () => {+ const summary = mapSeoSummary(+ { clicks: 10, impressions: 100, ctr: 10, position: 2 },+ null,+ )++ expect(summary.previous).toEqual({+ clicks: 0,+ impressions: 0,+ ctr: 0,+ position: 0,+ })+ expect(summary.change.clicks).toBe(10)+ })+})++describe('bucketSeoDateSeries', () => {+ const series = [+ day('2026-01-05', 10, 100, 10),+ day('2026-01-20', 30, 300, 2),+ day('2026-02-10', 5, 50, 4),+ ]++ it('leaves the native hour and day granularity untouched', () => {+ expect(bucketSeoDateSeries(series, TimeBucketType.DAY)).toBe(series)+ expect(bucketSeoDateSeries(series, TimeBucketType.HOUR)).toBe(series)+ })++ it('sums clicks and impressions into month buckets', () => {+ const [january, february] = bucketSeoDateSeries(+ series,+ TimeBucketType.MONTH,+ )++ expect(january.date).toBe('2026-01-01')+ expect(january.clicks).toBe(40)+ expect(january.impressions).toBe(400)+ expect(february.date).toBe('2026-02-01')+ expect(february.clicks).toBe(5)+ })++ it('recomputes ctr from the bucket totals rather than averaging it', () => {+ const [january] = bucketSeoDateSeries(series, TimeBucketType.MONTH)+ // 40 clicks / 400 impressions, not the mean of the two daily CTRs.+ expect(january.ctr).toBe(10)+ })++ it('averages position weighted by impressions', () => {+ const [january] = bucketSeoDateSeries(series, TimeBucketType.MONTH)+ // (10*100 + 2*300) / 400 = 4, whereas a plain mean would give 6.+ expect(january.position).toBe(4)+ })++ it('rolls a whole year up into one bucket', () => {+ const yearly = bucketSeoDateSeries(series, TimeBucketType.YEAR)++ expect(yearly).toHaveLength(1)+ expect(yearly[0].date).toBe('2026-01-01')+ expect(yearly[0].clicks).toBe(45)+ })++ it('reports zeroed rates for a bucket with no impressions', () => {+ const [bucket] = bucketSeoDateSeries(+ [day('2026-01-05', 0, 0, 0)],+ TimeBucketType.MONTH,+ )++ expect(bucket.ctr).toBe(0)+ expect(bucket.position).toBe(0)+ })+})++describe('mapSeoTimeseries', () => {+ it('emits ISO timestamps in the requested timezone', () => {+ const [row] = mapSeoTimeseries(+ [day('2026-01-05', 10, 100, 3)],+ ['clicks'],+ 'Europe/Kyiv',+ )++ expect(row.timestamp).toBe('2026-01-05T00:00:00+02:00')+ expect(row.clicks).toBe(10)+ })++ it('only emits the requested metrics', () => {+ const [row] = mapSeoTimeseries(+ [day('2026-01-05', 10, 100, 3)],+ ['clicks', 'position'],+ 'UTC',+ )++ expect(Object.keys(row).sort()).toEqual(['clicks', 'position', 'timestamp'])+ })++ it('drops rows Search Console returned without a date', () => {+ expect(mapSeoTimeseries([day('', 1, 1, 1)], ['clicks'], 'UTC')).toEqual([])+ })+})diff --git a/backend/apps/community/src/analytics/v2/__tests__/seo.registry.spec.ts b/backend/apps/community/src/analytics/v2/__tests__/seo.registry.spec.tsnew file mode 100644index 000000000..145d9407b--- /dev/null+++ b/backend/apps/community/src/analytics/v2/__tests__/seo.registry.spec.ts@@ -0,0 +1,134 @@+import { UnprocessableEntityException } from '@nestjs/common'++import { V2Filter } from '../query/filters.translator'+import {+ getDefaultSeoMetrics,+ getSeoBreakdownDimension,+ getSeoMetric,+ listSeoDimensions,+ parseSeoMetricsParam,+ toGscFiltersJson,+ validateSeoFilters,+ V2_SEO_DIMENSIONS,+} from '../registry/seo'++const filter = (overrides: Partial<V2Filter> = {}): V2Filter =>+ ({+ dimension: 'country',+ operator: 'is',+ value: 'US',+ ...overrides,+ }) as V2Filter++describe('seo dimension lookups', () => {+ it('resolves every declared dimension to its Search Console name', () => {+ expect(getSeoBreakdownDimension('query').gsc).toBe('query')+ expect(getSeoBreakdownDimension('page').gsc).toBe('page')+ expect(getSeoBreakdownDimension('country').gsc).toBe('country')+ expect(getSeoBreakdownDimension('device').gsc).toBe('device')+ })++ it('rejects unknown dimensions with 422', () => {+ expect(() => getSeoBreakdownDimension('nope')).toThrow(+ UnprocessableEntityException,+ )+ // Valid for traffic, but Search Console reports nothing like it.+ expect(() => getSeoBreakdownDimension('browser')).toThrow(+ UnprocessableEntityException,+ )+ })++ it('has unique api names', () => {+ const names = listSeoDimensions().map((dimension) => dimension.api)+ expect(new Set(names).size).toBe(names.length)+ })++ it('only maps onto dimensions Search Console actually serves', () => {+ for (const dimension of V2_SEO_DIMENSIONS) {+ expect(['query', 'page', 'country', 'device']).toContain(dimension.gsc)+ }+ })+})++describe('seo metric lookups', () => {+ it('resolves metrics and rejects unknown ones', () => {+ expect(getSeoMetric('clicks').api).toBe('clicks')+ expect(() => getSeoMetric('visitors')).toThrow(UnprocessableEntityException)+ })++ it('returns all four metrics by default', () => {+ expect(getDefaultSeoMetrics().map((metric) => metric.api)).toEqual([+ 'clicks',+ 'impressions',+ 'ctr',+ 'position',+ ])+ })++ it('parses and dedupes the metrics CSV param', () => {+ expect(+ parseSeoMetricsParam('clicks, impressions,clicks').map(+ (metric) => metric.api,+ ),+ ).toEqual(['clicks', 'impressions'])++ expect(parseSeoMetricsParam(undefined).map((metric) => metric.api)).toEqual(+ ['clicks', 'impressions', 'ctr', 'position'],+ )++ expect(() => parseSeoMetricsParam('bogus')).toThrow(+ UnprocessableEntityException,+ )+ })+})++describe('validateSeoFilters', () => {+ it('accepts scalar filters on known dimensions', () => {+ const filters = [filter(), filter({ dimension: 'query', value: 'swetrix' })]+ expect(validateSeoFilters(filters)).toBe(filters)+ })++ it('rejects filters on dimensions Search Console cannot filter by', () => {+ expect(() =>+ validateSeoFilters([filter({ dimension: 'browser' })]),+ ).toThrow(UnprocessableEntityException)+ })++ it('rejects array values, which have no dimensionFilterGroups equivalent', () => {+ expect(() => validateSeoFilters([filter({ value: ['US', 'DE'] })])).toThrow(+ UnprocessableEntityException,+ )+ })++ it('rejects null values, since Search Console reports no unset values', () => {+ expect(() => validateSeoFilters([filter({ value: null })])).toThrow(+ UnprocessableEntityException,+ )+ })+})++describe('toGscFiltersJson', () => {+ it('renames query -> keywords, the key GSCService.parseFilters expects', () => {+ const json = toGscFiltersJson([+ filter({ dimension: 'query', value: 'swetrix' }),+ ])++ expect(JSON.parse(json)).toEqual([+ { dimension: 'keywords', operator: 'is', value: 'swetrix' },+ ])+ })++ it('leaves dimensions that already share a name alone', () => {+ const json = toGscFiltersJson([+ filter({ dimension: 'page', operator: 'contains', value: '/blog' }),+ ])++ expect(JSON.parse(json)).toEqual([+ { dimension: 'page', operator: 'contains', value: '/blog' },+ ])+ })++ it('returns undefined for no filters so no filter group is sent', () => {+ expect(toGscFiltersJson([])).toBeUndefined()+ })+})diff --git a/backend/apps/community/src/analytics/v2/controllers/project-v2.controller.ts b/backend/apps/community/src/analytics/v2/controllers/project-v2.controller.tsindex 48df6c494..bb3a81ff2 100644--- a/backend/apps/community/src/analytics/v2/controllers/project-v2.controller.ts+++ b/backend/apps/community/src/analytics/v2/controllers/project-v2.controller.ts@@ -33,6 +33,7 @@ import {V2FunnelSessionsQueryDto,} from '../dto/project.dto'import { V2ProjectParamsDto } from '../dto/v2-base.dto'+import { SeoV2Service } from '../seo-v2.service'@ApiTags('Analytics v2')@ApiBearerAuth()@@ -44,6 +45,7 @@ import { V2ProjectParamsDto } from '../dto/v2-base.dto'export class ProjectV2Controller {constructor(private readonly analyticsV2Service: AnalyticsV2Service,+ private readonly seoV2Service: SeoV2Service,private readonly logger: AppLoggerService,) {}@@ -144,6 +146,12 @@ export class ProjectV2Controller {headers['x-password'],)+ // SEO is served by the Search Console API rather than ClickHouse, so it+ // keeps its own registry outside the sqlExpr-based one.+ if (query.type === 'seo') {+ return this.seoV2Service.getDimensions()+ }+return this.analyticsV2Service.getDimensions(query.type || 'traffic')}diff --git a/backend/apps/community/src/analytics/v2/controllers/seo-v2.controller.ts b/backend/apps/community/src/analytics/v2/controllers/seo-v2.controller.tsnew file mode 100644index 000000000..85ee82f0c--- /dev/null+++ b/backend/apps/community/src/analytics/v2/controllers/seo-v2.controller.ts@@ -0,0 +1,202 @@+import {+ Controller,+ Get,+ Headers,+ Param,+ Query,+ UseGuards,+ UseInterceptors,+ UsePipes,+ ValidationPipe,+} from '@nestjs/common'+import {+ ApiBearerAuth,+ ApiOperation,+ ApiSecurity,+ ApiTags,+} from '@nestjs/swagger'++import { Auth } from '../../../auth/decorators'+import { CurrentUserId } from '../../../auth/decorators/current-user-id.decorator'+import { OptionalJwtAccessTokenGuard } from '../../../auth/guards'+import { AuthenticationGuard } from '../../../auth/guards/authentication.guard'+import { AppLoggerService } from '../../../logger/logger.service'+import { AnalyticsReadGuard } from '../../protection/analytics-read.guard'+import { CacheableAnalytics } from '../../protection/cacheable-analytics.decorator'+import { PublicProjectCacheInterceptor } from '../../protection/public-project-cache.interceptor'+import { AnalyticsV2Service } from '../analytics-v2.service'+import {+ V2SeoBreakdownDto,+ V2SeoRangeDto,+ V2SeoSummaryDto,+ V2SeoTimeseriesDto,+} from '../dto/seo.dto'+import { V2ProjectParamsDto } from '../dto/v2-base.dto'+import { SeoV2Service } from '../seo-v2.service'++@ApiTags('Analytics v2')+@ApiBearerAuth()+@ApiSecurity('apiKey')+@UseGuards(OptionalJwtAccessTokenGuard, AuthenticationGuard, AnalyticsReadGuard)+@UseInterceptors(PublicProjectCacheInterceptor)+@UsePipes(new ValidationPipe({ transform: true }))+@Controller('v2/projects/:pid/seo')+export class SeoV2Controller {+ constructor(+ private readonly seoV2Service: SeoV2Service,+ private readonly analyticsV2Service: AnalyticsV2Service,+ private readonly logger: AppLoggerService,+ ) {}++ @Get('status')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'Search Console connection status',+ description:+ 'Whether Google Search Console is connected for this project and which property is linked. The other seo endpoints return 409 until both are true.',+ })+ async getStatus(+ @Param() { pid }: V2ProjectParamsDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/status')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getStatus(pid)+ }++ @Get('summary')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'SEO summary',+ description:+ 'Clicks, impressions, CTR and average position for the selected period, the previous period of the same length, and the change between them.',+ })+ async getSummary(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoSummaryDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/summary')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getSummary(pid, query)+ }++ @Get('timeseries')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'SEO timeseries',+ description:+ 'Selected SEO metrics grouped by time bucket, as rows of objects with ISO-8601 timestamps.',+ })+ async getTimeseries(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoTimeseriesDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/timeseries')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getTimeseries(pid, query)+ }++ @Get('breakdown')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'SEO breakdown',+ description:+ 'SEO metrics grouped by a single dimension (query, page, country, device), paginated. Rows are always ordered by clicks descending.',+ })+ async getBreakdown(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoBreakdownDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(+ `pid: ${pid}, dimension: ${query.dimension}`,+ 'GET /v2/projects/:pid/seo/breakdown',+ )++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getBreakdown(pid, query)+ }++ @Get('branded-traffic')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'Branded vs non-branded traffic',+ description:+ "Clicks split by whether the search query contained one of the project's brand keywords. Skipped for ranges wider than 31 days.",+ })+ async getBrandedTraffic(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoRangeDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/branded-traffic')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getBrandedTraffic(pid, query)+ }++ @Get('positions')+ @Auth(true, true)+ @CacheableAnalytics()+ @ApiOperation({+ summary: 'Search position analytics',+ description:+ 'Impressions bucketed by search position, and the daily count of ranking queries per position bucket. Skipped for ranges wider than 31 days.',+ })+ async getPositions(+ @Param() { pid }: V2ProjectParamsDto,+ @Query() query: V2SeoRangeDto,+ @CurrentUserId() uid: string,+ @Headers() headers: { 'x-password'?: string },+ ) {+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/positions')++ await this.analyticsV2Service.assertReadAccess(+ pid,+ uid,+ headers['x-password'],+ )++ return this.seoV2Service.getPositions(pid, query)+ }+}diff --git a/backend/apps/community/src/analytics/v2/dto/project.dto.ts b/backend/apps/community/src/analytics/v2/dto/project.dto.tsindex 44dddc3a9..e3cbc8dc5 100644--- a/backend/apps/community/src/analytics/v2/dto/project.dto.ts+++ b/backend/apps/community/src/analytics/v2/dto/project.dto.ts@@ -77,15 +77,15 @@ export class V2FunnelSessionsQueryDto extends V2FunnelQueryDto {export class V2DimensionsQueryDto {@ApiProperty({required: false,- enum: ['traffic', 'performance', 'captcha', 'errors'],+ enum: ['traffic', 'performance', 'captcha', 'errors', 'seo'],default: 'traffic',description: 'Data type to list dimensions and metrics for',})@IsOptional()- @IsIn(['traffic', 'performance', 'captcha', 'errors'], {+ @IsIn(['traffic', 'performance', 'captcha', 'errors', 'seo'], {message: 'The provided type is incorrect',})- type?: 'traffic' | 'performance' | 'captcha' | 'errors'+ type?: 'traffic' | 'performance' | 'captcha' | 'errors' | 'seo'}export class V2DimensionValuesParamsDto extends V2ProjectParamsDto {diff --git a/backend/apps/community/src/analytics/v2/dto/seo.dto.ts b/backend/apps/community/src/analytics/v2/dto/seo.dto.tsnew file mode 100644index 000000000..f8153b33a--- /dev/null+++ b/backend/apps/community/src/analytics/v2/dto/seo.dto.ts@@ -0,0 +1,115 @@+import { ApiProperty } from '@nestjs/swagger'+import { Type } from 'class-transformer'+import {+ IsIn,+ IsInt,+ IsNotEmpty,+ IsOptional,+ IsString,+ Max,+ Min,+} from 'class-validator'++import { TimeBucketType } from '../../dto/getData.dto'+import { SEO_SORT } from '../registry/seo'+import { V2BaseQueryDto } from './v2-base.dto'++const V2_SEO_MAX_BREAKDOWN_LIMIT = 100++/**+ * Search Console reports nothing below hourly granularity, so `minute` is+ * excluded from the buckets a caller may ask for.+ */+export const V2_SEO_TIME_BUCKETS = [+ TimeBucketType.HOUR,+ TimeBucketType.DAY,+ TimeBucketType.MONTH,+ TimeBucketType.YEAR,+] as const++export type V2SeoTimeBucket = (typeof V2_SEO_TIME_BUCKETS)[number]++export class V2SeoSummaryDto extends V2BaseQueryDto {}++export class V2SeoRangeDto extends V2BaseQueryDto {}++export class V2SeoTimeseriesDto extends V2BaseQueryDto {+ @ApiProperty({+ required: false,+ enum: V2_SEO_TIME_BUCKETS,+ description:+ "Time bucket for grouping. One of: hour, day, month, year. Defaults to 'day', or 'hour' for intraday periods.",+ })+ @IsOptional()+ @IsIn(V2_SEO_TIME_BUCKETS as readonly string[], {+ message: `The provided timeBucket is incorrect. Search Console supports: ${V2_SEO_TIME_BUCKETS.join(', ')}`,+ })+ timeBucket?: V2SeoTimeBucket++ @ApiProperty({+ required: false,+ description:+ 'Comma-separated metric names to return. Defaults to clicks, impressions, ctr and position.',+ example: 'clicks,impressions',+ })+ @IsOptional()+ @IsString()+ metrics?: string+}++export class V2SeoBreakdownDto extends V2BaseQueryDto {+ @ApiProperty({+ description:+ 'Dimension to break down by. One of: query, page, country, device',+ example: 'query',+ })+ @IsNotEmpty()+ @IsString()+ dimension: string++ @ApiProperty({+ required: false,+ description:+ 'Comma-separated metric names to compute per dimension value. Defaults to clicks, impressions, ctr and position.',+ example: 'clicks,impressions',+ })+ @IsOptional()+ @IsString()+ metrics?: string++ @ApiProperty({+ required: false,+ default: 30,+ maximum: V2_SEO_MAX_BREAKDOWN_LIMIT,+ description: 'Number of rows to return',+ })+ @IsOptional()+ @Type(() => Number)+ @IsInt()+ @Min(1)+ @Max(V2_SEO_MAX_BREAKDOWN_LIMIT)+ limit?: number++ @ApiProperty({+ required: false,+ default: 0,+ description: 'Number of rows to skip (pagination)',+ })+ @IsOptional()+ @Type(() => Number)+ @IsInt()+ @Min(0)+ offset?: number++ @ApiProperty({+ required: false,+ enum: [SEO_SORT],+ default: SEO_SORT,+ description: `Search Console orders rows by clicks descending and offers no sort control, so '${SEO_SORT}' is the only accepted value.`,+ })+ @IsOptional()+ @IsIn([SEO_SORT], {+ message: `Search Console always orders rows by clicks descending; omit 'sort' or pass '${SEO_SORT}'`,+ })+ sort?: string+}diff --git a/backend/apps/community/src/analytics/v2/mappers/seo.mapper.ts b/backend/apps/community/src/analytics/v2/mappers/seo.mapper.tsnew file mode 100644index 000000000..efd1ab46c--- /dev/null+++ b/backend/apps/community/src/analytics/v2/mappers/seo.mapper.ts@@ -0,0 +1,221 @@+import countries from 'i18n-iso-countries'+import dayjs from 'dayjs'++import { TimeBucketType } from '../../dto/getData.dto'+import { V2SeoGscDimension } from '../registry/seo'+import { toIsoTimestamp, TimeseriesRow } from './timeseries.mapper'++export interface SeoMetricValues {+ clicks: number+ impressions: number+ ctr: number+ position: number+}++export type SeoDateSeriesEntry = { date: string } & SeoMetricValues++export interface SeoSummaryData {+ current: SeoMetricValues+ previous: SeoMetricValues+ change: SeoMetricValues+}++const round = (value: unknown, precision: number): number => {+ const number = Number(value)++ if (!Number.isFinite(number)) {+ return 0+ }++ const factor = 10 ** precision++ return Math.round(number * factor) / factor+}++const toInteger = (value: unknown): number => Math.round(Number(value) || 0)++/**+ * Search Console reports countries as lowercase ISO 3166-1 alpha-3, while the+ * rest of the v2 surface (and the `cc` column behind the traffic `country`+ * dimension) uses uppercase alpha-2. Normalise so a `country` value means the+ * same thing whichever data type produced it.+ */+export const gscCountryToAlpha2 = (country: string): string => {+ const alpha2 = countries.alpha3ToAlpha2(String(country || '').toUpperCase())++ return alpha2 || String(country || '').toUpperCase()+}++const EMPTY_METRICS: SeoMetricValues = {+ clicks: 0,+ impressions: 0,+ ctr: 0,+ position: 0,+}++const mapSeoMetricValues = (+ values: Partial<SeoMetricValues> | null | undefined,+): SeoMetricValues => ({+ clicks: toInteger(values?.clicks),+ impressions: toInteger(values?.impressions),+ ctr: round(values?.ctr, 2),+ position: round(values?.position, 2),+})++export const mapSeoSummary = (+ current: Partial<SeoMetricValues> | null | undefined,+ previous: Partial<SeoMetricValues> | null | undefined,+): SeoSummaryData => {+ const mappedCurrent = mapSeoMetricValues(current)+ const mappedPrevious = previous ? mapSeoMetricValues(previous) : EMPTY_METRICS++ return {+ current: mappedCurrent,+ previous: mappedPrevious,+ change: {+ clicks: mappedCurrent.clicks - mappedPrevious.clicks,+ impressions: mappedCurrent.impressions - mappedPrevious.impressions,+ ctr: round(mappedCurrent.ctr - mappedPrevious.ctr, 2),+ position: round(mappedCurrent.position - mappedPrevious.position, 2),+ },+ }+}++/**+ * A raw row as returned by one of the GSCService per-dimension getters. They+ * disagree on the label field, and getKeywords calls its click count `count`.+ */+export interface GscBreakdownRow extends Partial<SeoMetricValues> {+ name?: string+ page?: string+ country?: string+ device?: string+ count?: number+}++const readRowValue = (+ dimension: V2SeoGscDimension,+ row: GscBreakdownRow,+): string => {+ if (dimension === 'query') return row.name ?? ''+ if (dimension === 'page') return row.page ?? ''+ if (dimension === 'country') return gscCountryToAlpha2(row.country ?? '')++ return row.device ?? ''+}++export const mapSeoBreakdownRows = (+ dimension: V2SeoGscDimension,+ rows: GscBreakdownRow[],+ metrics: string[],+): Record<string, unknown>[] =>+ rows.map((row) => {+ const values = mapSeoMetricValues({+ clicks: row.clicks ?? row.count,+ impressions: row.impressions,+ ctr: row.ctr,+ position: row.position,+ })++ const mapped: Record<string, unknown> = {+ value: readRowValue(dimension, row),+ }++ for (const metric of metrics) {+ mapped[metric] = values[metric as keyof SeoMetricValues]+ }++ return mapped+ })++const startOfBucket = (date: string, bucket: TimeBucketType): string => {+ const parsed = dayjs(date)++ if (bucket === TimeBucketType.MONTH) {+ return parsed.startOf('month').format('YYYY-MM-DD')+ }++ if (bucket === TimeBucketType.YEAR) {+ return parsed.startOf('year').format('YYYY-MM-DD')+ }++ return date+}++/**+ * Search Console only serves hourly and daily rows, so wider buckets are rolled+ * up here. Clicks and impressions sum; ctr is recomputed from the totals and+ * position is averaged weighted by impressions, since neither is additive.+ */+export const bucketSeoDateSeries = (+ series: SeoDateSeriesEntry[],+ bucket: TimeBucketType,+): SeoDateSeriesEntry[] => {+ if (bucket !== TimeBucketType.MONTH && bucket !== TimeBucketType.YEAR) {+ return series+ }++ const buckets = new Map<+ string,+ { clicks: number; impressions: number; weightedPosition: number }+ >()+ const orderedKeys: string[] = []++ for (const entry of series) {+ if (!entry.date) continue++ const key = startOfBucket(entry.date, bucket)+ const existing = buckets.get(key)++ if (existing) {+ existing.clicks += entry.clicks+ existing.impressions += entry.impressions+ existing.weightedPosition += entry.position * entry.impressions+ } else {+ orderedKeys.push(key)+ buckets.set(key, {+ clicks: entry.clicks,+ impressions: entry.impressions,+ weightedPosition: entry.position * entry.impressions,+ })+ }+ }++ return orderedKeys.map((key) => {+ const entry = buckets.get(key)++ return {+ date: key,+ clicks: Math.round(entry.clicks),+ impressions: Math.round(entry.impressions),+ ctr:+ entry.impressions > 0+ ? round((entry.clicks / entry.impressions) * 100, 2)+ : 0,+ position:+ entry.impressions > 0+ ? round(entry.weightedPosition / entry.impressions, 2)+ : 0,+ }+ })+}++export const mapSeoTimeseries = (+ series: SeoDateSeriesEntry[],+ metrics: string[],+ timezone: string,+): TimeseriesRow[] =>+ series+ .filter((entry) => Boolean(entry.date))+ .map((entry) => {+ const values = mapSeoMetricValues(entry)+ const row: TimeseriesRow = {+ timestamp: toIsoTimestamp(entry.date, timezone),+ }++ for (const metric of metrics) {+ row[metric] = values[metric as keyof SeoMetricValues]+ }++ return row+ })diff --git a/backend/apps/community/src/analytics/v2/registry/seo.ts b/backend/apps/community/src/analytics/v2/registry/seo.tsnew file mode 100644index 000000000..7128783ee--- /dev/null+++ b/backend/apps/community/src/analytics/v2/registry/seo.ts@@ -0,0 +1,193 @@+import { UnprocessableEntityException } from '@nestjs/common'++import { V2Filter } from '../query/filters.translator'++/**+ * SEO data is served by the Google Search Console API rather than ClickHouse,+ * so it cannot join the column/sqlExpr registry in ./dimensions and ./metrics.+ * These definitions mirror that registry's shape and lookup semantics to keep+ * /v2/projects/:pid/seo/* consistent with the rest of the v2 surface.+ */++export type V2SeoGscDimension = 'query' | 'page' | 'country' | 'device'++export interface V2SeoDimensionDef {+ api: string+ gsc: V2SeoGscDimension+ description: string+}++export interface V2SeoMetricDef {+ api: string+ isDefault?: boolean+ format: 'integer' | 'percent' | 'position'+ description: string+}++export const V2_SEO_DIMENSIONS: V2SeoDimensionDef[] = [+ {+ api: 'query',+ gsc: 'query',+ description: 'Search query the site was surfaced for',+ },+ {+ api: 'page',+ gsc: 'page',+ description: 'Landing page URL that appeared in search results',+ },+ {+ api: 'country',+ gsc: 'country',+ description: 'Country the search was made from (ISO 3166-1 alpha-2 code)',+ },+ {+ api: 'device',+ gsc: 'device',+ description: 'Device category the search was made on',+ },+]++const V2_SEO_METRICS: V2SeoMetricDef[] = [+ {+ api: 'clicks',+ isDefault: true,+ format: 'integer',+ description: 'Clicks through to the site from search results',+ },+ {+ api: 'impressions',+ isDefault: true,+ format: 'integer',+ description: 'Times a link to the site appeared in search results',+ },+ {+ api: 'ctr',+ isDefault: true,+ format: 'percent',+ description: 'Click-through rate, as a percentage of impressions',+ },+ {+ api: 'position',+ isDefault: true,+ format: 'position',+ description: 'Average position in search results',+ },+]++export const listSeoDimensions = (): V2SeoDimensionDef[] => V2_SEO_DIMENSIONS++export const listSeoMetrics = (): V2SeoMetricDef[] => V2_SEO_METRICS++const findSeoDimension = (api: string): V2SeoDimensionDef | undefined =>+ V2_SEO_DIMENSIONS.find((dimension) => dimension.api === api)++export const getSeoBreakdownDimension = (api: string): V2SeoDimensionDef => {+ const dimension = findSeoDimension(api)++ if (!dimension) {+ throw new UnprocessableEntityException(+ `Unknown seo dimension '${api}'. Supported dimensions: ${V2_SEO_DIMENSIONS.map(+ (d) => d.api,+ ).join(', ')}`,+ )+ }++ return dimension+}++export const getSeoMetric = (api: string): V2SeoMetricDef => {+ const metric = V2_SEO_METRICS.find((m) => m.api === api)++ if (!metric) {+ throw new UnprocessableEntityException(+ `Unknown seo metric '${api}'. Supported metrics: ${V2_SEO_METRICS.map(+ (m) => m.api,+ ).join(', ')}`,+ )+ }++ return metric+}++export const getDefaultSeoMetrics = (): V2SeoMetricDef[] =>+ V2_SEO_METRICS.filter((metric) => metric.isDefault)++export const parseSeoMetricsParam = (+ metrics: string | undefined,+): V2SeoMetricDef[] => {+ if (!metrics) {+ return getDefaultSeoMetrics()+ }++ const names = [+ ...new Set(+ metrics+ .split(',')+ .map((name) => name.trim())+ .filter(Boolean),+ ),+ ]++ if (names.length === 0) {+ return getDefaultSeoMetrics()+ }++ return names.map((name) => getSeoMetric(name))+}++/**+ * Search Console orders rows by clicks descending and exposes no sort control,+ * so this is the only ordering the seo breakdown can honour. It is accepted+ * (rather than rejected outright) so callers can be explicit about it.+ */+export const SEO_SORT = 'clicks:desc'++/**+ * GSCService.parseFilters keys filters by their v1 URL names, where the keyword+ * dimension is 'keywords'. v2 calls it 'query', after Search Console's own+ * naming, so translate on the way down — the same v2 -> v1 hop the ClickHouse+ * data types make through toV1FiltersJson.+ */+export const toGscFiltersJson = (filters: V2Filter[]): string | undefined => {+ if (filters.length === 0) {+ return undefined+ }++ return JSON.stringify(+ filters.map((filter) => ({+ ...filter,+ dimension: filter.dimension === 'query' ? 'keywords' : filter.dimension,+ })),+ )+}++/**+ * Search Console expresses filters as dimensionFilterGroups of scalar+ * comparisons, so the array / null values the rest of v2 accepts have no+ * equivalent here. Reject them rather than silently dropping the filter.+ */+export const validateSeoFilters = (filters: V2Filter[]): V2Filter[] => {+ for (const filter of filters) {+ if (!findSeoDimension(filter.dimension)) {+ throw new UnprocessableEntityException(+ `Unknown seo filter dimension '${filter.dimension}'. Supported dimensions: ${V2_SEO_DIMENSIONS.map(+ (d) => d.api,+ ).join(', ')}`,+ )+ }++ if (Array.isArray(filter.value)) {+ throw new UnprocessableEntityException(+ `The seo filter on '${filter.dimension}' cannot take an array of values; Search Console only supports a single value per filter`,+ )+ }++ if (filter.value === null) {+ throw new UnprocessableEntityException(+ `The seo filter on '${filter.dimension}' cannot take a null value; Search Console does not report unset dimension values`,+ )+ }+ }++ return filters+}diff --git a/backend/apps/community/src/analytics/v2/seo-v2.service.ts b/backend/apps/community/src/analytics/v2/seo-v2.service.tsnew file mode 100644index 000000000..a8261e0a3--- /dev/null+++ b/backend/apps/community/src/analytics/v2/seo-v2.service.ts@@ -0,0 +1,512 @@+import {+ BadRequestException,+ ConflictException,+ Injectable,+ UnprocessableEntityException,+} from '@nestjs/common'+import dayjs from 'dayjs'+import utc from 'dayjs/plugin/utc'++import {+ BrandedTrafficAnalytics,+ GSC_ALL_TIME_DAYS,+ GSCContext,+ GSCService,+ MAX_BRANDED_TRAFFIC_RANGE_DAYS,+ MAX_FILTER_EXPRESSION_LENGTH,+ MAX_FILTERS,+ MAX_POSITION_ANALYTICS_RANGE_DAYS,+ OPTIONAL_ANALYTICS_TIMEOUT_MS,+ PositionAnalytics,+} from '../../project/gsc.service'+import { AnalyticsService } from '../analytics.service'+import { TimeBucketType } from '../dto/getData.dto'+import {+ V2SeoBreakdownDto,+ V2SeoRangeDto,+ V2SeoSummaryDto,+ V2SeoTimeseriesDto,+ V2_SEO_TIME_BUCKETS,+} from './dto/seo.dto'+import { V2_DEFAULT_PERIOD, V2BaseQueryDto } from './dto/v2-base.dto'+import { envelope, V2Envelope } from './mappers/envelope'+import {+ bucketSeoDateSeries,+ mapSeoBreakdownRows,+ mapSeoSummary,+ mapSeoTimeseries,+ SeoDateSeriesEntry,+ SeoSummaryData,+} from './mappers/seo.mapper'+import { toIsoTimestamp, TimeseriesRow } from './mappers/timeseries.mapper'+import { parseV2Filters, V2Filter } from './query/filters.translator'+import {+ getSeoBreakdownDimension,+ listSeoDimensions,+ listSeoMetrics,+ parseSeoMetricsParam,+ SEO_SORT,+ toGscFiltersJson,+ validateSeoFilters,+} from './registry/seo'++dayjs.extend(utc)++const DEFAULT_SEO_BREAKDOWN_LIMIT = 30++const INTRADAY_PERIODS = ['1h', 'today', 'yesterday', '1d']++interface SeoTimeframe {+ period: string | null+ timeBucket: TimeBucketType+ safeTimezone: string+ groupFrom: string+ groupTo: string+ rangeDays: number+}++const SKIPPED = Symbol('skipped')++/**+ * Runs an expensive Search Console rollup under a deadline. A timeout aborts+ * the in-flight paging and reports the panel as skipped; a genuine upstream+ * failure still propagates, so a broken panel reads as broken rather than as+ * "too much data".+ */+const resolveOptional = async <T>(+ load: (signal: AbortSignal) => Promise<T>,+): Promise<T | typeof SKIPPED> => {+ const controller = new AbortController()+ let timeout: ReturnType<typeof setTimeout> | undefined++ const loading = load(controller.signal)++ // Aborting rejects `loading` after the race has already settled on SKIPPED;+ // this keeps that late rejection from surfacing as an unhandled rejection+ // without stopping Promise.race from seeing a real, pre-deadline failure.+ loading.catch(() => {})++ try {+ return await Promise.race([+ loading,+ new Promise<typeof SKIPPED>((resolve) => {+ timeout = setTimeout(() => {+ controller.abort()+ resolve(SKIPPED)+ }, OPTIONAL_ANALYTICS_TIMEOUT_MS)+ }),+ ])+ } finally {+ if (timeout) {+ clearTimeout(timeout)+ }+ }+}++@Injectable()+export class SeoV2Service {+ constructor(+ private readonly gscService: GSCService,+ private readonly analyticsService: AnalyticsService,+ ) {}++ /**+ * Search Console has to be connected and a property linked before any of the+ * data endpoints can answer. Both are project configuration rather than a bad+ * request, hence 409 rather than 400.+ *+ * Call this only after the request itself has been validated: a malformed+ * filter is a 422 whether or not the project happens to be connected, and+ * answering 409 first would send callers debugging their query down the+ * wrong path.+ */+ private async requireContext(pid: string): Promise<GSCContext> {+ const { connected, property } =+ await this.gscService.getConnectionState(pid)++ if (!connected) {+ throw new ConflictException(+ 'Google Search Console is not connected for this project',+ )+ }++ if (!property) {+ throw new ConflictException(+ 'No Google Search Console property is linked to this project',+ )+ }++ return this.gscService.getGSCContext(pid)+ }++ private prepareFilters(filters: string | undefined): {+ appliedFilters: V2Filter[]+ gscFilters: string | undefined+ } {+ const appliedFilters = validateSeoFilters(parseV2Filters(filters))++ if (appliedFilters.length > MAX_FILTERS) {+ throw new UnprocessableEntityException(+ `Too many filters; at most ${MAX_FILTERS} may be applied at once`,+ )+ }++ for (const filter of appliedFilters) {+ if (String(filter.value).length > MAX_FILTER_EXPRESSION_LENGTH) {+ throw new UnprocessableEntityException(+ `The seo filter on '${filter.dimension}' has a value longer than ${MAX_FILTER_EXPRESSION_LENGTH} characters`,+ )+ }+ }++ // GSCService.parseFilters already understands the v2 filter shape, so the+ // validated filters are handed straight back to it, mirroring how the+ // ClickHouse data types translate v2 -> v1 JSON -> getFiltersQuery.+ return { appliedFilters, gscFilters: toGscFiltersJson(appliedFilters) }+ }++ private resolveTimeframe(+ dto: V2BaseQueryDto,+ requestedBucket?: TimeBucketType,+ ): SeoTimeframe {+ const { from, to, timezone } = dto+ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)++ if (Boolean(from) !== Boolean(to)) {+ throw new BadRequestException(+ "The 'from' and 'to' parameters must be provided together",+ )+ }++ const hasCustomRange = Boolean(from && to)+ const period = hasCustomRange+ ? null+ : dto.period && dto.period !== 'custom'+ ? dto.period+ : V2_DEFAULT_PERIOD++ const timeBucket =+ requestedBucket ??+ (period && INTRADAY_PERIODS.includes(period)+ ? TimeBucketType.HOUR+ : TimeBucketType.DAY)++ // getGroupFromTo validates the bucket against the range, which neither an+ // open-ended 'all' nor a caller-chosen custom range can satisfy.+ const groupTimeBucket =+ hasCustomRange || period === 'all' ? null : timeBucket+ const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined++ const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(+ hasCustomRange ? from : undefined,+ hasCustomRange ? to : undefined,+ groupTimeBucket,+ period ?? undefined,+ safeTimezone,+ diff,+ )++ const rangeDays =+ Math.abs(+ dayjs(groupTo)+ .startOf('day')+ .diff(dayjs(groupFrom).startOf('day'), 'day'),+ ) + 1++ return { period, timeBucket, safeTimezone, groupFrom, groupTo, rangeDays }+ }++ private baseMeta(+ pid: string,+ timeframe: SeoTimeframe,+ appliedFilters: V2Filter[],+ ): Record<string, unknown> {+ return {+ pid,+ period: timeframe.period,+ from: toIsoTimestamp(timeframe.groupFrom, timeframe.safeTimezone),+ to: toIsoTimestamp(timeframe.groupTo, timeframe.safeTimezone),+ timezone: timeframe.safeTimezone,+ appliedFilters,+ }+ }++ async getStatus(+ pid: string,+ ): Promise<V2Envelope<{ connected: boolean; property: string | null }>> {+ const state = await this.gscService.getConnectionState(pid)++ return envelope(state, { pid })+ }++ /**+ * Mirrors AnalyticsV2Service.getDimensions so `?type=seo` answers in the same+ * shape as every other data type on the discovery endpoint.+ */+ getDimensions(): V2Envelope<{+ dimensions: Record<string, unknown>[]+ metrics: Record<string, unknown>[]+ }> {+ const dimensions = listSeoDimensions().map((dimension) => ({+ name: dimension.api,+ description: dimension.description,+ filterOnly: false,+ extraFields: [] as string[],+ }))++ const metrics = listSeoMetrics().map((metric) => ({+ name: metric.api,+ description: metric.description,+ format: metric.format,+ default: Boolean(metric.isDefault),+ }))++ return envelope({ dimensions, metrics }, { type: 'seo' })+ }++ async getSummary(+ pid: string,+ dto: V2SeoSummaryDto,+ ): Promise<V2Envelope<SeoSummaryData>> {+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const timeframe = this.resolveTimeframe(dto)+ const ctx = await this.requireContext(pid)+ const { groupFrom, groupTo } = timeframe++ const fromDate = dayjs(groupFrom)+ const durationMs = dayjs(groupTo).diff(fromDate)+ const previousTo = fromDate+ .subtract(1, 'millisecond')+ .format('YYYY-MM-DD HH:mm:ss')+ const previousFrom = fromDate+ .subtract(durationMs, 'millisecond')+ .format('YYYY-MM-DD HH:mm:ss')++ const [current, previous] = await Promise.all([+ this.gscService.getSummary(pid, groupFrom, groupTo, gscFilters, ctx),+ this.gscService+ .getSummary(pid, previousFrom, previousTo, gscFilters, ctx)+ .catch(() => null),+ ])++ return envelope(mapSeoSummary(current, previous), {+ ...this.baseMeta(pid, timeframe, appliedFilters),+ metrics: listSeoMetrics().map((metric) => metric.api),+ })+ }++ async getTimeseries(+ pid: string,+ dto: V2SeoTimeseriesDto,+ ): Promise<V2Envelope<TimeseriesRow[]>> {+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const metrics = parseSeoMetricsParam(dto.metrics).map(+ (metric) => metric.api,+ )+ const timeframe = this.resolveTimeframe(+ dto,+ dto.timeBucket as TimeBucketType | undefined,+ )+ const ctx = await this.requireContext(pid)++ // Search Console only serves hourly and daily rows; wider buckets are+ // rolled up from the daily series rather than requested upstream.+ const series = (await this.gscService.getDateSeries(+ pid,+ timeframe.groupFrom,+ timeframe.groupTo,+ timeframe.timeBucket === TimeBucketType.HOUR ? 'hour' : 'day',+ gscFilters,+ ctx,+ )) as SeoDateSeriesEntry[]++ const bucketed = bucketSeoDateSeries(series, timeframe.timeBucket)++ return envelope(+ mapSeoTimeseries(bucketed, metrics, timeframe.safeTimezone),+ {+ ...this.baseMeta(pid, timeframe, appliedFilters),+ metrics,+ timeBucket: timeframe.timeBucket,+ allowedTimeBuckets: [...V2_SEO_TIME_BUCKETS],+ },+ )+ }++ async getBreakdown(+ pid: string,+ dto: V2SeoBreakdownDto,+ ): Promise<V2Envelope<Record<string, unknown>[]>> {+ const dimension = getSeoBreakdownDimension(dto.dimension)+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const metrics = parseSeoMetricsParam(dto.metrics).map(+ (metric) => metric.api,+ )+ const timeframe = this.resolveTimeframe(dto)+ const limit = dto.limit ?? DEFAULT_SEO_BREAKDOWN_LIMIT+ const offset = dto.offset ?? 0+ const ctx = await this.requireContext(pid)+ const { groupFrom, groupTo } = timeframe++ const rows = await this.fetchBreakdownRows(+ dimension.gsc,+ pid,+ groupFrom,+ groupTo,+ limit,+ offset,+ gscFilters,+ ctx,+ )++ return envelope(mapSeoBreakdownRows(dimension.gsc, rows, metrics), {+ ...this.baseMeta(pid, timeframe, appliedFilters),+ dimension: dimension.api,+ metrics,+ limit,+ offset,+ sort: SEO_SORT,+ })+ }++ private fetchBreakdownRows(+ dimension: 'query' | 'page' | 'country' | 'device',+ pid: string,+ from: string,+ to: string,+ limit: number,+ offset: number,+ filters: string | undefined,+ ctx: GSCContext,+ ) {+ if (dimension === 'query') {+ return this.gscService.getKeywords(+ pid,+ from,+ to,+ limit,+ offset,+ filters,+ undefined,+ ctx,+ )+ }++ if (dimension === 'page') {+ return this.gscService.getTopPages(+ pid,+ from,+ to,+ limit,+ offset,+ filters,+ undefined,+ ctx,+ )+ }++ if (dimension === 'country') {+ return this.gscService.getTopCountries(+ pid,+ from,+ to,+ limit,+ offset,+ filters,+ ctx,+ )+ }++ return this.gscService.getTopDevices(+ pid,+ from,+ to,+ limit,+ offset,+ filters,+ ctx,+ )+ }++ async getBrandedTraffic(+ pid: string,+ dto: V2SeoRangeDto,+ ): Promise<V2Envelope<BrandedTrafficAnalytics | null>> {+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const timeframe = this.resolveTimeframe(dto)+ const ctx = await this.requireContext(pid)+ const meta = this.baseMeta(pid, timeframe, appliedFilters)++ if (timeframe.rangeDays > MAX_BRANDED_TRAFFIC_RANGE_DAYS) {+ return envelope(null, {+ ...meta,+ skipped: true,+ skippedReason: 'range_too_large',+ maxRangeDays: MAX_BRANDED_TRAFFIC_RANGE_DAYS,+ })+ }++ const result = await resolveOptional((signal) =>+ this.gscService.getBrandedTraffic(+ pid,+ timeframe.groupFrom,+ timeframe.groupTo,+ gscFilters,+ ctx,+ signal,+ ),+ )++ if (result === SKIPPED) {+ return envelope(null, {+ ...meta,+ skipped: true,+ skippedReason: 'timeout',+ timeoutMs: OPTIONAL_ANALYTICS_TIMEOUT_MS,+ })+ }++ return envelope(result, { ...meta, skipped: false })+ }++ async getPositions(+ pid: string,+ dto: V2SeoRangeDto,+ ): Promise<V2Envelope<PositionAnalytics | null>> {+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)+ const timeframe = this.resolveTimeframe(dto)+ const ctx = await this.requireContext(pid)+ const meta = this.baseMeta(pid, timeframe, appliedFilters)++ if (timeframe.rangeDays > MAX_POSITION_ANALYTICS_RANGE_DAYS) {+ return envelope(null, {+ ...meta,+ skipped: true,+ skippedReason: 'range_too_large',+ maxRangeDays: MAX_POSITION_ANALYTICS_RANGE_DAYS,+ })+ }++ const result = await resolveOptional((signal) =>+ this.gscService.getPositionAnalytics(+ pid,+ timeframe.groupFrom,+ timeframe.groupTo,+ gscFilters,+ ctx,+ signal,+ ),+ )++ if (result === SKIPPED) {+ return envelope(null, {+ ...meta,+ skipped: true,+ skippedReason: 'timeout',+ timeoutMs: OPTIONAL_ANALYTICS_TIMEOUT_MS,+ })+ }++ return envelope(result, { ...meta, skipped: false })+ }+}diff --git a/backend/apps/community/src/project/gsc.service.ts b/backend/apps/community/src/project/gsc.service.tsindex b2a751f52..dc4350e23 100644--- a/backend/apps/community/src/project/gsc.service.ts+++ b/backend/apps/community/src/project/gsc.service.ts@@ -39,11 +39,17 @@ const ENCRYPTION_KEY = deriveKey('gsc-token')const MAX_ROW_LIMIT = 25000const MAX_BRANDED_PAGES = 10-const MAX_FILTER_EXPRESSION_LENGTH = 500-const MAX_FILTERS = 20-const MAX_BRANDED_TRAFFIC_RANGE_DAYS = 31-const MAX_POSITION_ANALYTICS_RANGE_DAYS = 31-const OPTIONAL_ANALYTICS_TIMEOUT_MS = 12000+export const MAX_FILTER_EXPRESSION_LENGTH = 500+export const MAX_FILTERS = 20+export const MAX_BRANDED_TRAFFIC_RANGE_DAYS = 31+export const MAX_POSITION_ANALYTICS_RANGE_DAYS = 31+export const OPTIONAL_ANALYTICS_TIMEOUT_MS = 12000++/**+ * Search Console keeps roughly 16 months of history, so an 'all' period is+ * resolved against a fixed window rather than the project's first event.+ */+export const GSC_ALL_TIME_DAYS = 480const IMPRESSION_POSITION_BUCKETS = [{ key: 'pos1To3', label: '1-3' },@@ -67,13 +73,8 @@ type OrganicPositionSeriesEntry = { date: string } & Record<OrganicPositionBucketKey,number>-type BrandedTrafficAnalytics = { branded: number; nonBranded: number }-type SkippedBrandedAnalytics = {- skipped: true- branded: null- nonBranded: null-}-type PositionAnalytics = {+export type BrandedTrafficAnalytics = { branded: number; nonBranded: number }+export type PositionAnalytics = {impressionsByPosition: {key: ImpressionPositionBucketKeylabel: string@@ -82,23 +83,6 @@ type PositionAnalytics = {}[]organicPositions: OrganicPositionSeriesEntry[]}-type SkippedPositionAnalytics = {- skipped: true- impressionsByPosition: null- organicPositions: null-}--const SKIPPED_BRANDED_ANALYTICS: SkippedBrandedAnalytics = {- skipped: true,- branded: null,- nonBranded: null,-}--const SKIPPED_POSITION_ANALYTICS: SkippedPositionAnalytics = {- skipped: true,- impressionsByPosition: null,- organicPositions: null,-}const initialImpressionPositionBuckets = (): Record<ImpressionPositionBucketKey,@@ -140,32 +124,6 @@ const getOrganicPositionBucketKey = (return 'pos51Plus'}-const resolveOptionalAnalytics = async <T>(- load: (signal: AbortSignal) => Promise<T>,- fallback: T,-): Promise<T> => {- const controller = new AbortController()- let timeout: ReturnType<typeof setTimeout> | undefined-- try {- return await Promise.race([- load(controller.signal),- new Promise<T>((resolve) => {- timeout = setTimeout(() => {- controller.abort()- resolve(fallback)- }, OPTIONAL_ANALYTICS_TIMEOUT_MS)- }),- ])- } catch {- return fallback- } finally {- if (timeout) {- clearTimeout(timeout)- }- }-}-type GSCRow = {keys: string[]clicks?: number@@ -174,7 +132,7 @@ type GSCRow = {position?: number}-type GSCContext = {+export type GSCContext = {sc: ReturnType<typeof searchconsole>siteUrl: string}@@ -428,6 +386,28 @@ export class GSCService {return !_isEmpty(tokens?.refresh_token || tokens?.access_token)}+ /**+ * Whether the project can currently be queried: Search Console has to be+ * configured on this instance, an account connected and a property linked.+ * Unlike getStatus this needs no account email, so it is safe to expose to+ * anyone with project read access.+ */+ async getConnectionState(+ pid: string,+ ): Promise<{ connected: boolean; property: string | null }> {+ if (!this.isAvailable()) {+ return { connected: false, property: null }+ }++ const tokens = await this.getStoredTokens(pid)+ const connected = !_isEmpty(tokens?.refresh_token || tokens?.access_token)++ return {+ connected,+ property: connected ? tokens.property_uri || null : null,+ }+ }+async getStatus(pid: string): Promise<{connected: booleanemail: string | null@@ -482,7 +462,7 @@ export class GSCService {return oauth2Client}- private async getGSCContext(pid: string): Promise<GSCContext> {+ async getGSCContext(pid: string): Promise<GSCContext> {const tokens = await this.getStoredTokens(pid)if (_isEmpty(tokens) || _isEmpty(tokens.property_uri)) {throw new BadRequestException(@@ -1245,101 +1225,4 @@ export class GSCService {)}}-- async getDashboard(- pid: string,- from: string,- to: string,- timeBucket?: string,- filtersStr?: string,- ) {- if (!this.isAvailable()) {- return { notConnected: true }- }-- const connected = await this.isConnected(pid)- if (!connected) {- return { notConnected: true }- }-- const tokens = await this.getStoredTokens(pid)- if (_isEmpty(tokens.property_uri)) {- return { notConnected: true, noProperty: true }- }-- let ctx: GSCContext- try {- ctx = await this.getGSCContext(pid)- } catch {- return { notConnected: true }- }-- const fromDate = dayjs(from)- const toDate = dayjs(to)- const durationMs = toDate.diff(fromDate)- const rangeDays =- Math.abs(toDate.startOf('day').diff(fromDate.startOf('day'), 'day')) + 1- const shouldLoadBrandedTraffic = rangeDays <= MAX_BRANDED_TRAFFIC_RANGE_DAYS- const shouldLoadPositionAnalytics =- rangeDays <= MAX_POSITION_ANALYTICS_RANGE_DAYS- const prevTo = fromDate- .subtract(1, 'millisecond')- .format('YYYY-MM-DD HH:mm:ss')- const prevFrom = fromDate- .subtract(durationMs, 'millisecond')- .format('YYYY-MM-DD HH:mm:ss')-- const [- summary,- previousSummary,- dateSeries,- topPages,- topQueries,- topCountries,- topDevices,- brandedTraffic,- positionAnalytics,- ] = await Promise.all([- this.getSummary(pid, from, to, filtersStr, ctx),- this.getSummary(pid, prevFrom, prevTo, filtersStr, ctx).catch(() => null),- this.getDateSeries(pid, from, to, timeBucket, filtersStr, ctx),- this.getTopPages(pid, from, to, 50, 0, filtersStr, undefined, ctx),- this.getKeywords(pid, from, to, 50, 0, filtersStr, undefined, ctx),- this.getTopCountries(pid, from, to, 50, 0, filtersStr, ctx),- this.getTopDevices(pid, from, to, 50, 0, filtersStr, ctx),- shouldLoadBrandedTraffic- ? resolveOptionalAnalytics<- BrandedTrafficAnalytics | SkippedBrandedAnalytics- >(- (signal) =>- this.getBrandedTraffic(pid, from, to, filtersStr, ctx, signal),- SKIPPED_BRANDED_ANALYTICS,- )- : Promise.resolve(SKIPPED_BRANDED_ANALYTICS),- shouldLoadPositionAnalytics- ? resolveOptionalAnalytics<- PositionAnalytics | SkippedPositionAnalytics- >(- (signal) =>- this.getPositionAnalytics(pid, from, to, filtersStr, ctx, signal),- SKIPPED_POSITION_ANALYTICS,- )- : Promise.resolve(SKIPPED_POSITION_ANALYTICS),- ])-- return {- notConnected: false,- summary,- previousSummary,- dateSeries,- topPages,- topQueries,- topCountries,- topDevices,- brandedTraffic,- positionAnalyticsSkipped: 'skipped' in positionAnalytics,- impressionsByPosition: positionAnalytics.impressionsByPosition,- organicPositions: positionAnalytics.organicPositions,- }- }}diff --git a/docs/content/docs/api/stats-v2.mdx b/docs/content/docs/api/stats-v2.mdxindex a321df12b..de46bf774 100644--- a/docs/content/docs/api/stats-v2.mdx+++ b/docs/content/docs/api/stats-v2.mdx@@ -63,6 +63,7 @@ Every endpoint returns the same envelope:| performance | `load_time`, `ttfb`, `dns`, `tls`, `connection`, `response`, `render`, `dom_load` — all in seconds, aggregated by `measure` || errors | `occurrences`, `affected_users` || captcha | `events` (breakdown), `generated`, `passed`, `failed`, `validation_failed`, `replayed` (timeseries/summary) |+| seo | `clicks`, `impressions`, `ctr` (percentage), `position` (average search position) — all four returned by default |### Dimensions@@ -91,6 +92,7 @@ Dimensions use human-readable names (mapped internally onto the v1 short codes):| `page_property` | `tag:key:<key>` | filter-only, takes a `key` || `error_name` / `error_message` / `error_filename` | — | errors, filter-only || `captcha_event` / `captcha_difficulty` / `captcha_reason` / `solve_time` | — | captcha only |+| `query` | `keywords` | seo only — the search query |Which dimensions apply to which data type is discoverable via [`GET /v2/projects/:pid/dimensions`](#get-v2projectspiddimensions).@@ -116,6 +118,8 @@ Unknown dimensions or operators are rejected with a `422` and a message listingBreakdown and list endpoints accept `limit` (default 30) and `offset`. Breakdown responses include `meta.total` — the total number of dimension values — for pagination. Breakdowns also accept `sort=field:direction` where `field` is `value` or any selected metric and `direction` is `asc` or `desc` (default: first selected metric, descending).+The `seo` data type is the exception on both counts: Google Search Console reports no row total and offers no sort control, so `/seo/breakdown` omits `meta.total` and always orders by clicks descending. Page through it until you get fewer rows than you asked for.+### Measure (performance)Performance endpoints accept `measure`: `median` (default), `average`, `p75`, `p95`. The special `quantiles` measure is only meaningful on `/performance/timeseries`, where it returns `p50`/`p75`/`p95` of the total load time.@@ -323,6 +327,203 @@ Captcha counters per time bucket. Metrics: `generated`, `passed`, `failed`, `valCaptcha events grouped by `country`, `browser`, `os`, `device` (passed captchas only), or `captcha_event`, `captcha_difficulty`, `captcha_reason`, `solve_time`.+## SEO endpoints++SEO data comes from [Google Search Console](/integrations/google-search-console) rather than from your Swetrix events, so these endpoints behave a little differently from the rest of v2. The differences are all forced by the upstream API and are called out below.++Search Console must be connected to the project and one of its properties linked. Until both are true, every `seo` endpoint except `/seo/status` returns `409 Conflict`:++```json title="Response (409)"+{+ "statusCode": 409,+ "message": "Google Search Console is not connected for this project"+}+```++Two further caveats worth knowing before you build against these:++- **Data lags.** Search Console is typically 2–3 days behind, so recent days may be empty or incomplete.+- **Retention is ~16 months.** `period=all` resolves to the last 480 days rather than your project's full history.++### GET /v2/projects/:pid/seo/status++Whether the project can serve SEO data at all. Poll this before the others to tell "not connected" apart from "no data".++```bash+curl 'https://api.swetrix.com/v2/projects/YOUR_PROJECT_ID/seo/status' \+ -H "X-Api-Key: ${SWETRIX_API_KEY}"+```++```json title="Response"+{+ "data": { "connected": true, "property": "sc-domain:example.com" },+ "meta": { "pid": "YOUR_PROJECT_ID" }+}+```++`connected` reports whether a Google account is linked; `property` is the Search Console property being queried, and is `null` when an account is connected but no property has been picked yet. Both must be set for the data endpoints to answer.++### GET /v2/projects/:pid/seo/summary++Clicks, impressions, CTR and average position for the selected period, the previous period of the same length, and the change between them.++```bash+curl 'https://api.swetrix.com/v2/projects/YOUR_PROJECT_ID/seo/summary?period=7d' \+ -H "X-Api-Key: ${SWETRIX_API_KEY}"+```++```json title="Response"+{+ "data": {+ "current": { "clicks": 412, "impressions": 18320, "ctr": 2.25, "position": 12.4 },+ "previous": { "clicks": 388, "impressions": 17010, "ctr": 2.28, "position": 13.1 },+ "change": { "clicks": 24, "impressions": 1310, "ctr": -0.03, "position": -0.7 }+ },+ "meta": {+ "pid": "YOUR_PROJECT_ID",+ "metrics": ["clicks", "impressions", "ctr", "position"],+ "period": "7d",+ "timezone": "Etc/GMT",+ "appliedFilters": []+ }+}+```++`change` is the absolute difference, as everywhere else in v2. Note that a _falling_ `position` is an improvement.++### GET /v2/projects/:pid/seo/timeseries++SEO metrics grouped by time bucket, as rows with ISO 8601 timestamps.++Parameters: `period`/`from`+`to`, `timezone`, `timeBucket`, `metrics`, `filters`.++Search Console reports nothing below hourly granularity, so `timeBucket` here accepts only `hour`, `day` (default), `month` and `year` — `minute` is rejected with a `422`. Hourly and daily rows come straight from Search Console; `month` and `year` are rolled up by Swetrix, summing clicks and impressions, recomputing CTR from those totals, and averaging position weighted by impressions (none of the three are additive).++```bash+curl 'https://api.swetrix.com/v2/projects/YOUR_PROJECT_ID/seo/timeseries?period=7d&metrics=clicks,impressions&timezone=Europe/Kyiv' \+ -H "X-Api-Key: ${SWETRIX_API_KEY}"+```++```json title="Response"+{+ "data": [+ { "timestamp": "2026-07-01T00:00:00+03:00", "clicks": 61, "impressions": 2604 },+ { "timestamp": "2026-07-02T00:00:00+03:00", "clicks": 58, "impressions": 2511 }+ ],+ "meta": {+ "pid": "YOUR_PROJECT_ID",+ "metrics": ["clicks", "impressions"],+ "timeBucket": "day",+ "allowedTimeBuckets": ["hour", "day", "month", "year"],+ "period": "7d",+ "timezone": "Europe/Kyiv",+ "appliedFilters": []+ }+}+```++### GET /v2/projects/:pid/seo/breakdown++SEO metrics grouped by **one dimension** — `query`, `page`, `country` or `device`.++Parameters: `dimension` (required), `metrics` (default: all four), `limit` (max 100), `offset`, plus the usual time range and `filters`.++```bash+curl 'https://api.swetrix.com/v2/projects/YOUR_PROJECT_ID/seo/breakdown?dimension=query&period=4w&limit=2' \+ -H "X-Api-Key: ${SWETRIX_API_KEY}"+```++```json title="Response"+{+ "data": [+ { "value": "swetrix", "clicks": 184, "impressions": 2103, "ctr": 8.75, "position": 1.4 },+ {+ "value": "google analytics alternative",+ "clicks": 96,+ "impressions": 8801,+ "ctr": 1.09,+ "position": 9.2+ }+ ],+ "meta": {+ "pid": "YOUR_PROJECT_ID",+ "dimension": "query",+ "metrics": ["clicks", "impressions", "ctr", "position"],+ "limit": 2,+ "offset": 0,+ "sort": "clicks:desc",+ "period": "4w",+ "timezone": "Etc/GMT",+ "appliedFilters": []+ }+}+```++Notes:++- **No `meta.total` and no `sort`.** Search Console neither counts matching rows nor lets you order them, so rows always come back by clicks descending. `sort` is accepted only as `clicks:desc`, so you can be explicit; anything else is a `422` rather than a silently ignored parameter. Page with `limit`/`offset` until a page comes back short.+- **`country` is alpha-2.** Search Console reports alpha-3 (`usa`); Swetrix normalises to the alpha-2 (`US`) that `country` means everywhere else in v2.+- Combine `dimension` with a filter to drill in — the queries a given page ranks for are `?dimension=query&filters=[{"dimension":"page","operator":"is","value":"https://example.com/blog"}]`, and the pages ranking for a query are the mirror image.++### GET /v2/projects/:pid/seo/branded-traffic++Clicks split by whether the search query contained one of the project's brand keywords (configured in project settings; Swetrix falls back to the project name and domain).++```json title="Response (data)"+{ "branded": 260, "nonBranded": 152 }+```++Returns `data: null` with `meta.skipped: true` when the rollup was not run — see [skipped rollups](#skipped-rollups).++### GET /v2/projects/:pid/seo/positions++Impressions bucketed by search position, plus the daily count of ranking queries per position bucket.++```json title="Response (data, truncated)"+{+ "impressionsByPosition": [+ { "key": "pos1To3", "label": "1-3", "impressions": 4120, "percentage": 22.5 },+ { "key": "pos4To10", "label": "4-10", "impressions": 7330, "percentage": 40 }+ ],+ "organicPositions": [+ {+ "date": "2026-07-01",+ "pos1To3": 12,+ "pos4To10": 40,+ "pos11To20": 61,+ "pos21To50": 88,+ "pos51Plus": 24+ }+ ]+}+```++`impressionsByPosition` buckets are `pos1To3`, `pos4To10`, `pos11To20`, `pos21Plus`; `organicPositions` splits the tail further into `pos21To50` and `pos51Plus`. Returns `data: null` with `meta.skipped: true` when the rollup was not run.++### Skipped rollups++`/seo/branded-traffic` and `/seo/positions` have to page through every query in the range, which is slow and expensive against Search Console's quota. Rather than let them hang, Swetrix skips them and says so in `meta`:++```json title="Response"+{+ "data": null,+ "meta": {+ "pid": "YOUR_PROJECT_ID",+ "skipped": true,+ "skippedReason": "range_too_large",+ "maxRangeDays": 31,+ "period": "3M",+ "timezone": "Etc/GMT",+ "appliedFilters": []+ }+}+```++- `skippedReason: "range_too_large"` — the range exceeds `meta.maxRangeDays` (31). Narrow the range.+- `skippedReason: "timeout"` — Search Console did not answer within `meta.timeoutMs`. Retry, or narrow the range.++On a successful run `meta.skipped` is `false` and `data` is populated. A skip is not an error — an actual upstream failure still returns a `5xx`.+## Error endpoints### GET /v2/projects/:pid/errors@@ -430,7 +631,7 @@ Paginated sessions that reached a funnel `step` (1-indexed). `dropoff=true` retu### GET /v2/projects/:pid/dimensions-Machine-readable list of the dimensions and metrics available for a data type (`?type=traffic|performance|captcha|errors`) — build dashboard UIs against this instead of hardcoding.+Machine-readable list of the dimensions and metrics available for a data type (`?type=traffic|performance|captcha|errors|seo`) — build dashboard UIs against this instead of hardcoding.```json title="Response (data, truncated)"{@@ -478,6 +679,7 @@ Distinct recorded values for a dimension — for filter autocompletion (`?type=t| `GET /v1/log/funnel` / `/log/funnel-sessions` | `/funnel` / `/funnel/sessions` || `GET /v1/log/live-visitors` + `/log/hb` | `/live-visitors` (merged) || `GET /v1/log/filters` / `/log/errors-filters` / `/log/filters/versions` | `/dimensions/:dimension/values` |+| `GET /v1/log/keywords` | `/seo/breakdown?dimension=query` |Key differences:@@ -487,4 +689,6 @@ Key differences:4. **Everything is wrapped** in `{ data, meta }` and breakdowns/lists are paginated server-side.5. `take`/`skip` are now `limit`/`offset`.-Still v1-only: GSC/keywords endpoints, bot statistics, session replays, `generalStats`, multi-project `birdseye` (`pids` array), and all data ingestion endpoints.+`GET /v1/log/keywords` still works, but it only ever returned the top queries. The `seo` endpoints cover the whole Search Console integration, so prefer them for new code.++Still v1-only: bot statistics, session replays, `generalStats`, multi-project `birdseye` (`pids` array), and all data ingestion endpoints.diff --git a/web/app/api/api.server.ts b/web/app/api/api.server.tsindex a973224ff..e9a0dd13a 100644--- a/web/app/api/api.server.ts+++ b/web/app/api/api.server.ts@@ -1881,196 +1881,6 @@ export async function getGSCKeywordsServer()}-interface GSCDateSeriesEntry {- date: string- clicks: number- impressions: number- ctr: number- position: number-}--interface GSCTopPageEntry {- page: string- clicks: number- impressions: number- ctr: number- position: number-}--interface GSCTopQueryEntry {- name: string- count: number- impressions: number- position: number- ctr: number-}--interface GSCTopCountryEntry {- country: string- clicks: number- impressions: number- ctr: number- position: number-}--interface GSCTopDeviceEntry {- device: string- clicks: number- impressions: number- ctr: number- position: number-}--type GSCImpressionPositionBucketKey =- | 'pos1To3'- | 'pos4To10'- | 'pos11To20'- | 'pos21Plus'--type GSCOrganicPositionBucketKey =- | 'pos1To3'- | 'pos4To10'- | 'pos11To20'- | 'pos21To50'- | 'pos51Plus'--interface GSCImpressionsByPositionEntry {- key: GSCImpressionPositionBucketKey- label: string- impressions: number- percentage: number-}--type GSCOrganicPositionEntry = { date: string } & Record<- GSCOrganicPositionBucketKey,- number->--interface GSCBrandedTraffic {- branded: number- nonBranded: number- skipped?: false-}--interface GSCSkippedBrandedTraffic {- skipped: true- branded: null- nonBranded: null-}--export interface GSCDashboardResponse {- notConnected?: boolean- noProperty?: boolean- summary?: {- clicks: number- impressions: number- ctr: number- position: number- }- previousSummary?: {- clicks: number- impressions: number- ctr: number- position: number- } | null- dateSeries?: GSCDateSeriesEntry[]- topPages?: GSCTopPageEntry[]- topQueries?: GSCTopQueryEntry[]- topCountries?: GSCTopCountryEntry[]- topDevices?: GSCTopDeviceEntry[]- brandedTraffic?: GSCBrandedTraffic | GSCSkippedBrandedTraffic- positionAnalyticsSkipped?: boolean- impressionsByPosition?: GSCImpressionsByPositionEntry[] | null- organicPositions?: GSCOrganicPositionEntry[] | null-}--export async function getGSCDashboardServer(- request: Request,- pid: string,- params: {- period?: string- from?: string- to?: string- timezone?: string- password?: string- timeBucket?: string- filters?: V2Filter[]- } = {},-): Promise<ServerFetchResult<GSCDashboardResponse>> {- const queryParams = new URLSearchParams()- queryParams.append('pid', pid)- queryParams.append('period', params.period || '7d')- if (params.from) queryParams.append('from', params.from)- if (params.to) queryParams.append('to', params.to)- if (params.timezone) queryParams.append('timezone', params.timezone)- if (params.timeBucket) queryParams.append('timeBucket', params.timeBucket)- if (params.filters)- queryParams.append('filters', serializeFiltersForUrl(params.filters))-- const headers: Record<string, string> = {}- if (params.password) {- headers['x-password'] = params.password- }-- return serverFetch<GSCDashboardResponse>(- request,- `log/gsc-dashboard?${queryParams.toString()}`,- {- headers,- timeoutMs: 60000,- },- )-}--export interface GSCDetailsResponse {- type: 'queries' | 'pages' | 'none'- data: Array<{- name?: string- page?: string- count?: number- clicks?: number- impressions: number- ctr: number- position: number- }>-}--export async function getGSCDetailsServer(- request: Request,- pid: string,- params: {- period?: string- from?: string- to?: string- timezone?: string- password?: string- page?: string- query?: string- } = {},-): Promise<ServerFetchResult<GSCDetailsResponse>> {- const queryParams = new URLSearchParams()- queryParams.append('pid', pid)- queryParams.append('period', params.period || '7d')- if (params.from) queryParams.append('from', params.from)- if (params.to) queryParams.append('to', params.to)- if (params.timezone) queryParams.append('timezone', params.timezone)- if (params.page) queryParams.append('page', params.page)- if (params.query) queryParams.append('query', params.query)-- const headers: Record<string, string> = {}- if (params.password) {- headers['x-password'] = params.password- }-- return serverFetch<GSCDetailsResponse>(- request,- `log/gsc-details?${queryParams.toString()}`,- {- headers,- },- )-}-// ============================================================================// MARK: Revenue API// ============================================================================diff --git a/web/app/api/v2/endpoints.ts b/web/app/api/v2/endpoints.tsindex 4360fc84f..d78521323 100644--- a/web/app/api/v2/endpoints.ts+++ b/web/app/api/v2/endpoints.ts@@ -10,6 +10,10 @@ import {MetricSums,PagePropertyRow,PerformanceSummaryData,+ SeoBrandedTrafficData,+ SeoPositionsData,+ SeoStatusData,+ SeoSummaryData,TimeseriesRow,TrafficSummaryData,V2CommonParams,@@ -24,7 +28,9 @@ type SummaryData<T extends V2DataType> = T extends 'traffic'? PerformanceSummaryData: T extends 'captcha'? CaptchaSummaryData- : Record<string, unknown>+ : T extends 'seo'+ ? SeoSummaryData+ : Record<string, unknown>export const getSummary = <T extends V2DataType>(pid: string,@@ -70,6 +76,33 @@ export const getBreakdown = (signal,)+export const getSeoStatus = (pid: string, signal?: AbortSignal) =>+ fetchV2<SeoStatusData>(`projects/${pid}/seo/status`, {}, signal)++// Both of the below return `data: null` with `meta.skipped` when the range is+// too wide or Search Console did not answer within the deadline.+export const getSeoBrandedTraffic = (+ pid: string,+ params: Common,+ signal?: AbortSignal,+) =>+ fetchV2<SeoBrandedTrafficData | null>(+ `projects/${pid}/seo/branded-traffic`,+ params,+ signal,+ )++export const getSeoPositions = (+ pid: string,+ params: Common,+ signal?: AbortSignal,+) =>+ fetchV2<SeoPositionsData | null>(+ `projects/${pid}/seo/positions`,+ params,+ signal,+ )+export const getCustomEvents = (pid: string,params: Common & { limit?: number; offset?: number },diff --git a/web/app/api/v2/types.ts b/web/app/api/v2/types.tsindex a0c9921ce..f39aad2ef 100644--- a/web/app/api/v2/types.ts+++ b/web/app/api/v2/types.ts@@ -1,4 +1,9 @@-export type V2DataType = 'traffic' | 'performance' | 'errors' | 'captcha'+export type V2DataType =+ | 'traffic'+ | 'performance'+ | 'errors'+ | 'captcha'+ | 'seo'export type V2FilterOperator = 'is' | 'is_not' | 'contains' | 'contains_not'@@ -94,6 +99,59 @@ export interface CaptchaSummaryData {previous: CaptchaSummaryStats | null}+interface SeoMetricValues {+ clicks: number+ impressions: number+ ctr: number+ position: number+}++export interface SeoSummaryData {+ current: SeoMetricValues+ previous: SeoMetricValues+ change: SeoMetricValues+}++export interface SeoStatusData {+ connected: boolean+ property: string | null+}++export interface SeoBrandedTrafficData {+ branded: number+ nonBranded: number+}++type SeoImpressionPositionBucketKey =+ | 'pos1To3'+ | 'pos4To10'+ | 'pos11To20'+ | 'pos21Plus'++type SeoOrganicPositionBucketKey =+ | 'pos1To3'+ | 'pos4To10'+ | 'pos11To20'+ | 'pos21To50'+ | 'pos51Plus'++interface SeoImpressionsByPositionEntry {+ key: SeoImpressionPositionBucketKey+ label: string+ impressions: number+ percentage: number+}++type SeoOrganicPositionEntry = { date: string } & Record<+ SeoOrganicPositionBucketKey,+ number+>++export interface SeoPositionsData {+ impressionsByPosition: SeoImpressionsByPositionEntry[]+ organicPositions: SeoOrganicPositionEntry[]+}+export interface CustomEventRow {event: stringcount: numberdiff --git a/web/app/hooks/useAnalyticsProxy.ts b/web/app/hooks/useAnalyticsProxy.tsindex d0686d195..dd0b01f25 100644--- a/web/app/hooks/useAnalyticsProxy.ts+++ b/web/app/hooks/useAnalyticsProxy.ts@@ -1,4 +1,4 @@-import { useCallback, useRef, useState } from 'react'+import { useCallback, useState } from 'react'import type {SessionReplaysResponse,@@ -18,7 +18,6 @@ import type {BotProtectionStats,BotProtectionPeriod,JourneysResponse,- GSCDashboardResponse,RevenueStatus,RevenueDataResponse,OverallObject,@@ -658,59 +657,6 @@ export function useJourneysProxy() {return { fetchJourneys, data, error, isLoading }}-export function useGSCDashboardProxy() {- const [data, setData] = useState<GSCDashboardResponse | null>(null)- const [error, setError] = useState<string | null>(null)- const [isLoading, setIsLoading] = useState(false)- const requestIdRef = useRef(0)-- const fetchDashboard = useCallback(- async (projectId: string, params: ClientAnalyticsParams = {}) => {- const requestId = requestIdRef.current + 1- requestIdRef.current = requestId- setIsLoading(true)- setError(null)-- try {- const result = await postAnalytics<GSCDashboardResponse>({- action: 'getGSCDashboard',- projectId,- params,- })-- if (requestId !== requestIdRef.current) {- return result.data- }-- if (result.data) {- setData(result.data)- }- setError(result.error)- return result.data- } catch (err) {- if (requestId === requestIdRef.current) {- setError(err instanceof Error ? err.message : 'Unknown error')- }- return null- } finally {- if (requestId === requestIdRef.current) {- setIsLoading(false)- }- }- },- [],- )-- const resetData = useCallback(() => {- requestIdRef.current += 1- setData(null)- setError(null)- setIsLoading(false)- }, [])-- return { fetchDashboard, data, error, isLoading, resetData }-}-export function useRevenueProxy() {const [statusData, setStatusData] = useState<RevenueStatus | null>(null)const [revenueData, setRevenueData] = useState<RevenueDataResponse | null>(diff --git a/web/app/hooks/v2/useV2Queries.ts b/web/app/hooks/v2/useV2Queries.tsindex c54f09d6e..fe3113a8f 100644--- a/web/app/hooks/v2/useV2Queries.ts+++ b/web/app/hooks/v2/useV2Queries.ts@@ -98,6 +98,9 @@ interface TimeseriesOpts {mode?: 'periodical' | 'cumulative'measure?: stringenabled?: boolean+ // Overrides the bucket from the URL, for tabs whose data source supports a+ // narrower set of buckets than the project view offers.+ timeBucket?: string}export const useTimeseriesQuery = (@@ -108,7 +111,7 @@ export const useTimeseriesQuery = (const { timeBucket } = useViewProjectContext()const params = {...common,- timeBucket: timeBucket || undefined,+ timeBucket: opts.timeBucket || timeBucket || undefined,metrics: opts.metrics,mode: opts.mode,measure: opts.measure,@@ -132,7 +135,7 @@ export const useCompareTimeseriesQuery = (const params = compare? {...compareOverride(common, compare),- timeBucket: timeBucket || undefined,+ timeBucket: opts.timeBucket || timeBucket || undefined,metrics: opts.metrics,mode: opts.mode,measure: opts.measure,@@ -213,8 +216,15 @@ export const useBreakdownDetailsQuery = (),initialPageParam: 0,getNextPageParam: (lastPage, pages) => {- const total = lastPage.meta.total ?? 0const loaded = pages.reduce((acc, page) => acc + page.data.length, 0)+ const total = lastPage.meta.total++ // Search Console reports no row count, so fall back to treating a full+ // page as a hint that another one may follow.+ if (total === undefined || total === null) {+ return lastPage.data.length === DETAILS_PAGE_SIZE ? loaded : undefined+ }+return loaded < total ? loaded : undefined},placeholderData: keepPreviousData,@@ -222,6 +232,43 @@ export const useBreakdownDetailsQuery = (})}+export const useSeoStatusQuery = () => {+ const { id: pid } = useCurrentProject()++ return useQuery({+ queryKey: ['v2', pid, 'seo', 'status'],+ queryFn: ({ signal }) => v2.getSeoStatus(pid, signal),+ placeholderData: keepPreviousData,+ })+}++export const useSeoBrandedTrafficQuery = (opts: { enabled?: boolean } = {}) => {+ const { pid, common } = useV2CommonParams('seo')++ return useQuery({+ queryKey: ['v2', pid, 'seo', 'branded-traffic', common],+ queryFn: ({ signal }) => v2.getSeoBrandedTraffic(pid, common, signal),+ placeholderData: keepPreviousData,+ enabled: opts.enabled,+ })+}++/**+ * Impressions-by-position and organic positions come out of a single Search+ * Console rollup, so both panels share one query rather than paying for it+ * twice.+ */+export const useSeoPositionsQuery = (opts: { enabled?: boolean } = {}) => {+ const { pid, common } = useV2CommonParams('seo')++ return useQuery({+ queryKey: ['v2', pid, 'seo', 'positions', common],+ queryFn: ({ signal }) => v2.getSeoPositions(pid, common, signal),+ placeholderData: keepPreviousData,+ enabled: opts.enabled,+ })+}+export const useCustomEventsQuery = (opts: { limit?: number; enabled?: boolean } = {},) => {diff --git a/web/app/lib/v2Dimensions.ts b/web/app/lib/v2Dimensions.tsindex d9a1a5d25..797759589 100644--- a/web/app/lib/v2Dimensions.ts+++ b/web/app/lib/v2Dimensions.ts@@ -26,6 +26,9 @@ export const V1_TO_V2_DIMENSION: Record<string, string> = {entryPage: 'entry_page',exitPage: 'exit_page',ev: 'event',+ // The SEO tab's keyword filter predates v2, which names the dimension after+ // Search Console's own 'query'.+ keywords: 'query',}export const KEYED_DIMENSIONS = ['event_metadata', 'page_property'] as const@@ -115,11 +118,14 @@ const CAPTCHA_DIMENSIONS = ['solve_time',]+const SEO_DIMENSIONS = ['query', 'page', 'country', 'device']+export const VALID_DIMENSIONS_BY_TYPE: Record<V2DataType, string[]> = {traffic: TRAFFIC_DIMENSIONS,performance: PERFORMANCE_DIMENSIONS,errors: ERROR_DIMENSIONS,captcha: CAPTCHA_DIMENSIONS,+ seo: SEO_DIMENSIONS,}export const ALL_VALID_DIMENSIONS = Array.from(@@ -128,5 +134,6 @@ export const ALL_VALID_DIMENSIONS = Array.from(...PERFORMANCE_DIMENSIONS,...ERROR_DIMENSIONS,...CAPTCHA_DIMENSIONS,+ ...SEO_DIMENSIONS,]),)diff --git a/web/app/pages/Project/View/Panels.tsx b/web/app/pages/Project/View/Panels.tsxindex 8c73d5199..cf236fbdd 100644--- a/web/app/pages/Project/View/Panels.tsx+++ b/web/app/pages/Project/View/Panels.tsx@@ -1785,7 +1785,7 @@ const FilterWrapper = ({ children, as, to, ...props }: FilterWrapperProps) => {return <div {...props}>{children}</div>}-interface PanelProps {+export interface PanelProps {name: stringdata: Entry[]rowMapper?: (row: any) => React.ReactNodediff --git a/web/app/pages/Project/View/ViewProject.helpers.tsx b/web/app/pages/Project/View/ViewProject.helpers.tsxindex 3dfa83064..8303bea75 100644--- a/web/app/pages/Project/View/ViewProject.helpers.tsx+++ b/web/app/pages/Project/View/ViewProject.helpers.tsx@@ -2346,7 +2346,7 @@ const typeNameMapping = (t: typeof i18next.t) => ({region: t('project.mapping.rg'),city: t('project.mapping.ct'),page: t('project.mapping.pg'),- keywords: t('project.seo.topQueries'),+ query: t('project.seo.query'),entry_page: t('project.entryPages'),exit_page: t('project.exitPages'),locale: t('project.mapping.lc'),diff --git a/web/app/pages/Project/View/ViewProject.tsx b/web/app/pages/Project/View/ViewProject.tsxindex b7ebf609b..451d2c791 100644--- a/web/app/pages/Project/View/ViewProject.tsx+++ b/web/app/pages/Project/View/ViewProject.tsx@@ -197,7 +197,6 @@ interface RefreshTriggersContextType {featureFlagsRefreshTrigger: numberjourneysRefreshTrigger: numberreplaysRefreshTrigger: number- seoRefreshTrigger: number}const defaultViewProjectContext: ViewProjectContextType = {@@ -260,7 +259,6 @@ const defaultRefreshTriggersContext: RefreshTriggersContextType = {featureFlagsRefreshTrigger: 0,journeysRefreshTrigger: 0,replaysRefreshTrigger: 0,- seoRefreshTrigger: 0,}const ViewProjectContext = createContext<ViewProjectContextType>(@@ -346,7 +344,6 @@ const ViewProjectContent = () => {useState(0)const [journeysRefreshTrigger, setJourneysRefreshTrigger] = useState(0)const [replaysRefreshTrigger, setReplaysRefreshTrigger] = useState(0)- const [seoRefreshTrigger, setSeoRefreshTrigger] = useState(0)const customMetrics = useMemo<ProjectViewCustomEvent[]>(() => {const raw = searchParams.get('metrics')if (!raw) return []@@ -893,6 +890,7 @@ const ViewProjectContent = () => {PROJECT_TABS.funnels,PROJECT_TABS.profiles,PROJECT_TABS.captcha,+ PROJECT_TABS.seo,]),[],)@@ -932,12 +930,6 @@ const ViewProjectContent = () => {setReplaysRefreshTrigger((prev) => prev + 1)return}-- if (activeTab === PROJECT_TABS.seo) {- await queryClient.invalidateQueries({ queryKey: ['v2', id] })- setSeoRefreshTrigger((prev) => prev + 1)- return- }},[authLoading, dataLoading, activeTab, queryClient, id, V2_TABS],)@@ -1276,7 +1268,6 @@ const ViewProjectContent = () => {featureFlagsRefreshTrigger,journeysRefreshTrigger,replaysRefreshTrigger,- seoRefreshTrigger,}),[goalsRefreshTrigger,@@ -1284,7 +1275,6 @@ const ViewProjectContent = () => {featureFlagsRefreshTrigger,journeysRefreshTrigger,replaysRefreshTrigger,- seoRefreshTrigger,],)diff --git a/web/app/pages/Project/View/v2/BreakdownPanel.tsx b/web/app/pages/Project/View/v2/BreakdownPanel.tsxindex 4b94cdbc1..d4f1f2069 100644--- a/web/app/pages/Project/View/v2/BreakdownPanel.tsx+++ b/web/app/pages/Project/View/v2/BreakdownPanel.tsx@@ -12,7 +12,7 @@ import Button from '~/ui/Button'import { Text } from '~/ui/Text'import { getItem, setItem } from '~/utils/localstorage'-import { Panel, PanelContainer } from '../Panels'+import { Panel, PanelContainer, type PanelProps } from '../Panels'import { groupVersionRows, mapBreakdownRows } from './adapters'export interface BreakdownSubTab {@@ -33,6 +33,7 @@ interface BreakdownPanelProps {primaryMetric?: stringmetrics?: string[]measure?: string+ sort?: stringrowMapper?: (entry: Entry, subTabId: string) => React.ReactNodevalueMapper?: (value: number, subTabId: string) => numbertransformEntries?: (entries: Entry[], subTabId: string) => Entry[]@@ -50,6 +51,11 @@ interface BreakdownPanelProps {valuesHeaderName?: stringhighlightColour?: 'blue' | 'red' | 'orange'onActiveSubTabChange?: (subTabId: string) => void+ detailsExtraColumns?: PanelProps['detailsExtraColumns']+ rowTooltipRenderer?: PanelProps['rowTooltipRenderer']+ rowTooltipFollowCursor?: boolean+ hidePercentageInDetails?: boolean+ disableRowClick?: boolean}const subTabStorageKey = (dataType: string, panelId: string) =>@@ -64,6 +70,7 @@ export const BreakdownPanel = ({primaryMetric = 'visitors',metrics,measure,+ sort,rowMapper,valueMapper,transformEntries,@@ -73,6 +80,11 @@ export const BreakdownPanel = ({valuesHeaderName,highlightColour,onActiveSubTabChange,+ detailsExtraColumns,+ rowTooltipRenderer,+ rowTooltipFollowCursor,+ hidePercentageInDetails,+ disableRowClick,}: BreakdownPanelProps) => {const { t } = useTranslation('common')const { getFilterLink: getFilterLinkContext } = useViewProjectContext()@@ -99,11 +111,13 @@ export const BreakdownPanel = ({const isSentinel = !activeSubTab.dimension+ const resolvedSort = sort ?? `${primaryMetric}:desc`+const query = useBreakdownDetailsQuery(dataType, {dimension: activeSubTab.dimension || '',metrics,measure,- sort: `${primaryMetric}:desc`,+ sort: resolvedSort,enabled: hasBeenInView && !isSentinel,})@@ -111,7 +125,7 @@ export const BreakdownPanel = ({dimension: activeSubTab.versionsDimension || '',metrics,measure,- sort: `${primaryMetric}:desc`,+ sort: resolvedSort,enabled: hasBeenInView && Boolean(activeSubTab.versionsDimension),})@@ -119,9 +133,10 @@ export const BreakdownPanel = ({const mapped = mapBreakdownRows(query.data?.pages.flatMap((page) => page.data),primaryMetric,+ metrics,)return transformEntries ? transformEntries(mapped, activeSubTabId) : mapped- }, [query.data, primaryMetric, transformEntries, activeSubTabId])+ }, [query.data, primaryMetric, metrics, transformEntries, activeSubTabId])const versionData = useMemo(() => {if (!activeSubTab.versionsDimension || !versionsQuery.data) {@@ -224,6 +239,11 @@ export const BreakdownPanel = ({}valuesHeaderName={valuesHeaderName}highlightColour={highlightColour}+ detailsExtraColumns={detailsExtraColumns}+ rowTooltipRenderer={rowTooltipRenderer}+ rowTooltipFollowCursor={rowTooltipFollowCursor}+ hidePercentageInDetails={hidePercentageInDetails}+ disableRowClick={disableRowClick}dataLoading={query.isFetching && !query.isFetchingNextPage}isRefetching={query.isFetching && !query.isLoading && !query.isFetchingNextPagediff --git a/web/app/pages/Project/View/v2/adapters.ts b/web/app/pages/Project/View/v2/adapters.tsindex a75701b0b..a3a890b1e 100644--- a/web/app/pages/Project/View/v2/adapters.ts+++ b/web/app/pages/Project/View/v2/adapters.ts@@ -11,6 +11,9 @@ import { OverallObject } from '~/lib/models/Project'export const mapBreakdownRows = (rows: BreakdownRow[] | undefined,primaryMetric = 'visitors',+ // Metrics beyond the primary one are copied onto the entry so panels can show+ // them in extra columns or row tooltips (the SEO panels lean on this).+ extraMetrics?: string[],): Entry[] => {if (!rows) return []@@ -19,6 +22,11 @@ export const mapBreakdownRows = (count: Number(row[primaryMetric] ?? 0),...(typeof row.country === 'string' ? { cc: row.country } : {}),...(typeof row.region_code === 'string' ? { rgc: row.region_code } : {}),+ ...Object.fromEntries(+ (extraMetrics ?? [])+ .filter((metric) => metric !== primaryMetric)+ .map((metric) => [metric, Number(row[metric] ?? 0)]),+ ),}))}diff --git a/web/app/pages/Project/tabs/SEO/SEOView.tsx b/web/app/pages/Project/tabs/SEO/SEOView.tsxindex 856fa3387..a5a38ac27 100644--- a/web/app/pages/Project/tabs/SEO/SEOView.tsx+++ b/web/app/pages/Project/tabs/SEO/SEOView.tsx@@ -1,5 +1,5 @@import {- ArrowClockwiseIcon,+ ArrowsClockwiseIcon,EyeIcon,InfoIcon,LinkIcon,@@ -14,55 +14,63 @@ import {import dayjs from 'dayjs'import _isEmpty from 'lodash/isEmpty'import _round from 'lodash/round'-import React, { useEffect, useCallback, useMemo, useRef, useState } from 'react'+import React, { useCallback, useEffect, useMemo, useState } from 'react'import { Trans, useTranslation } from 'react-i18next'import { Link } from '~/ui/Link'import { useSearchParams } from 'react-router'-import { useGSCDashboardProxy } from '~/hooks/useAnalyticsProxy'-import { useBreakdownQuery } from '~/hooks/v2/useV2Queries'-import { mapBreakdownRows } from '~/pages/Project/View/v2/adapters'import { useAnnotations } from '~/hooks/useAnnotations'+import { useInViewOnce } from '~/hooks/useInViewOnce'+import {+ useBreakdownQuery,+ useCompareSummaryQuery,+ useCompareTimeseriesQuery,+ useSeoBrandedTrafficQuery,+ useSeoPositionsQuery,+ useSeoStatusQuery,+ useSummaryQuery,+ useTimeseriesQuery,+} from '~/hooks/v2/useV2Queries'import { DOCS_URL } from '~/lib/constants'import type { TimeBucket } from '~/lib/constants'import type { Entry } from '~/lib/models/Entry'-import BillboardChart from '~/ui/BillboardChart'import AnnotationModal from '~/modals/AnnotationModal'import { ChartContextMenu } from '~/pages/Project/View/components/ChartContextMenu'import DashboardHeader from '~/pages/Project/View/components/DashboardHeader'-import { MainChart } from '~/pages/Project/View/components/MainChart'import Filters from '~/pages/Project/View/components/Filters'+import { MainChart } from '~/pages/Project/View/components/MainChart'import ProjectViewHeaderActions from '~/pages/Project/View/components/ProjectViewHeaderActions'import TabErrorBoundary from '~/pages/Project/View/components/TabErrorBoundary'+import CCRow from '~/pages/Project/View/components/CCRow'import {- Panel,PanelContainer,PanelEmptyState,PanelLoadingState,} from '~/pages/Project/View/Panels'import {- useViewProjectContext,- useRefreshTriggers,-} from '~/pages/Project/View/ViewProject'+ BreakdownPanel,+ type BreakdownSubTab,+} from '~/pages/Project/View/v2/BreakdownPanel'+import { mapBreakdownRows } from '~/pages/Project/View/v2/adapters'+import { useViewProjectContext } from '~/pages/Project/View/ViewProject'import {noRegionPeriods,panelIconMapping,getDeviceRowMapper,} from '~/pages/Project/View/ViewProject.helpers'import { MetricCard } from '~/pages/Project/tabs/Traffic/MetricCards'-import { CompactNumberFlow, PercentFlow } from '~/ui/NumberFlow'import RefRow from '~/pages/Project/tabs/Traffic/RefRow'-import CCRow from '~/pages/Project/View/components/CCRow'import { useCurrentProject } from '~/providers/CurrentProjectProvider'import { useTheme } from '~/providers/ThemeProvider'+import BillboardChart from '~/ui/BillboardChart'+import Button from '~/ui/Button'import Checkbox from '~/ui/Checkbox'import Dropdown from '~/ui/Dropdown'import Loader from '~/ui/Loader'-import LoadingBar from '~/ui/LoadingBar'+import { CompactNumberFlow, PercentFlow } from '~/ui/NumberFlow'import { Text } from '~/ui/Text'import Tooltip from '~/ui/Tooltip'import { nFormatter } from '~/utils/generic'-import countries from '~/utils/isoCountries'import { getSearchEngineReferrals, getAIReferrals } from '~/utils/referrers'import routes from '~/utils/routes'@@ -70,8 +78,8 @@ import CompactReferralPanel from './CompactReferralPanel'import {SEO_METRICS,type SEOMetricKey,- aggregateDateSeries,hasOrganicPositionData,+ seoTimeseriesToDateSeries,} from './seo-utils'import type { QuadrantData } from './seo-chart-options'import {@@ -89,7 +97,16 @@ interface SEOViewProps {const SEO_DOCS_URL = `${DOCS_URL}/analytics-dashboard/seo`-const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {+// Every metric the seo endpoints expose. Panels ask for all four so impressions,+// CTR and position are available for the extra columns and row tooltips.+const SEO_BREAKDOWN_METRICS = ['clicks', 'impressions', 'ctr', 'position']++// Search Console orders rows by clicks descending and offers no sort control.+const SEO_SORT = 'clicks:desc'++const QUADRANT_QUERY_LIMIT = 50++const SEOViewInner = ({ tnMapping }: SEOViewProps) => {const {t,i18n: { language },@@ -98,7 +115,6 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {const { id, allowedToManage } = useCurrentProject()const {period,- timezone,timeFormat,timeBucket,periodPairs,@@ -106,15 +122,6 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {getFilterLink,isActiveCompare,} = useViewProjectContext()- const { seoRefreshTrigger } = useRefreshTriggers()- const { fetchDashboard, data, error, isLoading } = useGSCDashboardProxy()- const {- fetchDashboard: fetchCompareDashboard,- data: compareData,- error: compareError,- isLoading: isCompareLoading,- resetData: resetCompareData,- } = useGSCDashboardProxy()const [searchParams, setSearchParams] = useSearchParams()const {annotations,@@ -196,6 +203,70 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {urlTimeBucket,])+ const statusQuery = useSeoStatusQuery()+ const status = statusQuery.data?.data+ const isConnected = Boolean(status?.connected && status?.property)++ // The expensive rollups and the quadrant only fetch once scrolled to, so an+ // SEO page load costs Search Console nothing it does not display. The panels+ // below gate their spinner on isPending rather than isLoading: a query that+ // is disabled (not yet scrolled to) or paused (offline) is pending but not+ // fetching, and isLoading would call that "no data" instead of "not yet".+ const { ref: brandedRef, hasBeenInView: brandedInView } = useInViewOnce()+ const { ref: positionsRef, hasBeenInView: positionsInView } = useInViewOnce()+ const { ref: quadrantRef, hasBeenInView: quadrantInView } = useInViewOnce()++ const summaryQuery = useSummaryQuery('seo', { enabled: isConnected })+ const compareSummaryQuery = useCompareSummaryQuery('seo', {+ enabled: isConnected,+ })+ const timeseriesQuery = useTimeseriesQuery('seo', {+ timeBucket: seoTimeBucket,+ enabled: isConnected,+ })+ const compareTimeseriesQuery = useCompareTimeseriesQuery('seo', {+ timeBucket: seoTimeBucket,+ enabled: isConnected,+ })+ const brandedQuery = useSeoBrandedTrafficQuery({+ enabled: isConnected && brandedInView,+ })+ const positionsQuery = useSeoPositionsQuery({+ enabled: isConnected && positionsInView,+ })+ const quadrantQuery = useBreakdownQuery('seo', {+ dimension: 'query',+ metrics: SEO_BREAKDOWN_METRICS,+ limit: QUADRANT_QUERY_LIMIT,+ sort: SEO_SORT,+ enabled: isConnected && quadrantInView,+ })++ const referrerQuery = useBreakdownQuery('traffic', {+ dimension: 'referrer',+ limit: 100,+ sort: 'visitors:desc',+ })++ const refEntries: Entry[] = useMemo(+ () => mapBreakdownRows(referrerQuery.data?.data),+ [referrerQuery.data],+ )++ const searchEngineEntries = useMemo(+ () => getSearchEngineReferrals(refEntries),+ [refEntries],+ )+ const aiReferralEntries = useMemo(+ () => getAIReferrals(refEntries),+ [refEntries],+ )++ const refRowMapper = useCallback(+ ({ name: entryName }: any) => <RefRow rowName={entryName} />,+ [],+ )+const metricItems = useMemo(() => [{@@ -229,144 +300,28 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {}))}, [])- const referrerQuery = useBreakdownQuery('traffic', {- dimension: 'referrer',- limit: 100,- sort: 'visitors:desc',- })-- const refEntries: Entry[] = useMemo(- () => mapBreakdownRows(referrerQuery.data?.data),- [referrerQuery.data],- )-- const searchEngineEntries = useMemo(- () => getSearchEngineReferrals(refEntries),- [refEntries],- )- const aiReferralEntries = useMemo(- () => getAIReferrals(refEntries),- [refEntries],- )+ const summary = summaryQuery.data?.data.current+ const comparisonSummary = isActiveCompare+ ? compareSummaryQuery.data?.data.current+ : summaryQuery.data?.data.previous- const refRowMapper = useCallback(- ({ name: entryName }: any) => <RefRow rowName={entryName} />,- [],+ const series = useMemo(+ () => seoTimeseriesToDateSeries(timeseriesQuery.data?.data, seoTimeBucket),+ [timeseriesQuery.data, seoTimeBucket],)- const noopFilterLink = useCallback(() => '#', [])- const gscLoading = isLoading || isCompareLoading- const gscError = error || compareError-- // No cached response to fall back on — panels show spinners rather than- // claiming they have no data.- const isSEOLoading = gscLoading && !data-- const [isManualRefreshing, setIsManualRefreshing] = useState(false)-- const prevTrigger = useRef(seoRefreshTrigger)-- const from = searchParams.get('from') || undefined- const to = searchParams.get('to') || undefined- const compareEnabled = searchParams.get('compare') === 'true'- const compareFrom = searchParams.get('compareFrom') || undefined- const compareTo = searchParams.get('compareTo') || undefined-- const loadData = useCallback(async () => {- const params = {- period,- from,- to,- timezone,- timeBucket: seoTimeBucket,- filters,- }-- const currentPromise = fetchDashboard(projectId, params)-- if (isActiveCompare && compareEnabled && compareFrom && compareTo) {- resetCompareData()- await Promise.all([- currentPromise,- fetchCompareDashboard(projectId, {- ...params,- period: 'custom',- from: compareFrom,- to: compareTo,- }),- ])- return- }-- resetCompareData()- await currentPromise- }, [- fetchDashboard,- fetchCompareDashboard,- resetCompareData,- projectId,- period,- from,- to,- compareEnabled,- compareFrom,- compareTo,- timezone,- seoTimeBucket,- filters,- isActiveCompare,- ])-- useEffect(() => {- loadData()- }, [loadData])-- useEffect(() => {- if (seoRefreshTrigger !== prevTrigger.current) {- prevTrigger.current = seoRefreshTrigger- loadData()- }- }, [seoRefreshTrigger, loadData])-- const handleManualRefresh = useCallback(async () => {- if (isManualRefreshing) return- setIsManualRefreshing(true)- try {- await loadData()- } finally {- setIsManualRefreshing(false)- }- }, [isManualRefreshing, loadData])-- const manualRefreshButton = useMemo(- () => (- <button- type='button'- title={t('project.refreshStats')}- onClick={handleManualRefresh}- className='relative rounded-md border border-transparent p-2 transition-all ring-inset hover:border-gray-300 hover:bg-white focus:z-10 focus:ring-1 focus:ring-slate-900 focus:outline-hidden hover:dark:border-slate-700/80 dark:hover:bg-slate-900 dark:focus:ring-slate-300'- >- <ArrowClockwiseIcon- className={`h-5 w-5 text-gray-700 dark:text-gray-50 ${isManualRefreshing ? 'animate-spin' : ''}`}- />- </button>- ),- [t, handleManualRefresh, isManualRefreshing],- )-- const aggregatedSeries = useMemo(- () => aggregateDateSeries(data?.dateSeries || [], seoTimeBucket),- [data?.dateSeries, seoTimeBucket],- )-- const aggregatedCompareSeries = useMemo(- () => aggregateDateSeries(compareData?.dateSeries || [], seoTimeBucket),- [compareData?.dateSeries, seoTimeBucket],+ const compareSeries = useMemo(+ () =>+ seoTimeseriesToDateSeries(+ compareTimeseriesQuery.data?.data,+ seoTimeBucket,+ ),+ [compareTimeseriesQuery.data, seoTimeBucket],)const chartXAxisData = useMemo(- () => aggregatedSeries.map((entry) => entry.date),- [aggregatedSeries],+ () => series.map((entry) => entry.date),+ [series],)const filteredAnnotations = useMemo(() => {@@ -386,82 +341,13 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {})}, [annotations, chartXAxisData])- const topPagesAsEntries: Entry[] = useMemo(- () =>- (data?.topPages || []).map(- (p) =>- ({- name: p.page,- count: p.clicks,- impressions: p.impressions,- ctr: p.ctr,- position: p.position,- }) as Entry & { impressions: number; ctr: number; position: number },- ),- [data?.topPages],- )-- const topQueriesAsEntries: (Entry & {- impressions: number- ctr: number- position: number- })[] = useMemo(- () =>- (data?.topQueries || []).map(- (q) =>- ({- name: q.name,- count: q.count,- impressions: q.impressions,- ctr: q.ctr,- position: q.position,- }) as Entry & { impressions: number; ctr: number; position: number },- ),- [data?.topQueries],- )-- const topCountriesAsEntries: Entry[] = useMemo(- () =>- (data?.topCountries || []).map((c) => {- const alpha2 =- countries.alpha3ToAlpha2(c.country.toUpperCase())?.toLowerCase() ||- c.country- return {- name: alpha2,- count: c.clicks,- impressions: c.impressions,- ctr: c.ctr,- position: c.position,- } as Entry & { impressions: number; ctr: number; position: number }- }),- [data?.topCountries],- )+ const isBrandedTrafficSkipped = brandedQuery.data?.meta.skipped === true- const topDevicesAsEntries: Entry[] = useMemo(- () =>- (data?.topDevices || []).map(- (d) =>- ({- name: d.device,- count: d.clicks,- impressions: d.impressions,- ctr: d.ctr,- position: d.position,- }) as Entry & { impressions: number; ctr: number; position: number },- ),- [data?.topDevices],+ const brandedTraffic = useMemo(+ () => brandedQuery.data?.data ?? { branded: 0, nonBranded: 0 },+ [brandedQuery.data],)- const isBrandedTrafficSkipped = data?.brandedTraffic?.skipped === true-- const brandedTraffic = useMemo(() => {- if (!data?.brandedTraffic || data.brandedTraffic.skipped) {- return { branded: 0, nonBranded: 0 }- }-- return data.brandedTraffic- }, [data?.brandedTraffic])-const donutChartOptions = useMemo(() =>buildDonutChartOptions(@@ -473,21 +359,18 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {[brandedTraffic, t, theme],)+ const isPositionAnalyticsSkipped = positionsQuery.data?.meta.skipped === true+const impressionsByPosition = useMemo(- () => data?.impressionsByPosition || [],- [data?.impressionsByPosition],+ () => positionsQuery.data?.data?.impressionsByPosition ?? [],+ [positionsQuery.data],)const organicPositions = useMemo(- () => data?.organicPositions || [],- [data?.organicPositions],+ () => positionsQuery.data?.data?.organicPositions ?? [],+ [positionsQuery.data],)- const isPositionAnalyticsSkipped =- data?.positionAnalyticsSkipped === true ||- data?.impressionsByPosition === null ||- data?.organicPositions === null-const hasImpressionsByPositionData = useMemo(() => impressionsByPosition.some((bucket) => bucket.impressions > 0),[impressionsByPosition],@@ -514,59 +397,63 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {[language],)- const deviceRowMapper = useMemo(- () => getDeviceRowMapper('dv', theme, t),+ const deviceRowMapper = useCallback(+ (entry: Entry) => {+ const mapper = getDeviceRowMapper('dv', theme, t) as+ | ((entry: Entry) => React.ReactNode)+ | undefined+ return mapper ? mapper(entry) : entry.name+ },[theme, t],)const anyMetricActive = Object.values(activeMetrics).some(Boolean)const quadrantData: QuadrantData | null = useMemo(() => {- if (!topQueriesAsEntries.length) return null- const positions = topQueriesAsEntries.map((q) => q.position)- const ctrs = topQueriesAsEntries.map((q) => q.ctr)- const impressions = topQueriesAsEntries.map((q) => q.impressions)- const names = topQueriesAsEntries.map((q) => q.name ?? '')+ const entries = mapBreakdownRows(+ quadrantQuery.data?.data,+ 'clicks',+ SEO_BREAKDOWN_METRICS,+ ) as (Entry & { impressions: number; ctr: number; position: number })[]++ if (!entries.length) return null++ const positions = entries.map((q) => q.position)+ const ctrs = entries.map((q) => q.ctr)+ const impressions = entries.map((q) => q.impressions)+ const names = entries.map((q) => q.name ?? '')const maxImp = Math.max(...impressions) || 1const minImp = Math.min(...impressions) || 0return { positions, ctrs, impressions, names, maxImp, minImp }- }, [topQueriesAsEntries])+ }, [quadrantQuery.data])const quadrantChartOptions = useMemo(() => {if (!quadrantData) return {}- const avgCtr = data?.summary?.ctr ?? 5- const avgPos = data?.summary?.position ?? 10+ const avgCtr = summary?.ctr ?? 5+ const avgPos = summary?.position ?? 10return buildQuadrantChartOptions(quadrantData, avgCtr, avgPos, theme, t)- }, [quadrantData, data?.summary, theme, t])-- const comparisonSummary =- isActiveCompare && compareEnabled- ? compareData?.summary- : data?.previousSummary+ }, [quadrantData, summary, theme, t])const chartOptions = useMemo(() =>buildMainChartOptions(- aggregatedSeries,+ series,activeMetrics,seoTimeBucket,t,!noRegionPeriods.includes(period),filteredAnnotations,- isActiveCompare && compareEnabled && aggregatedCompareSeries.length- ? aggregatedCompareSeries- : undefined,+ isActiveCompare && compareSeries.length ? compareSeries : undefined,),[- aggregatedSeries,+ series,activeMetrics,seoTimeBucket,t,isActiveCompare,- compareEnabled,- aggregatedCompareSeries,+ compareSeries,period,filteredAnnotations,],@@ -706,46 +593,75 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {[t],)- if (gscError && !data) {+ const pagesSubTabs = useMemo<BreakdownSubTab[]>(+ () => [{ id: 'page', label: t('project.seo.page'), dimension: 'page' }],+ [t],+ )++ const queriesSubTabs = useMemo<BreakdownSubTab[]>(+ () => [{ id: 'query', label: t('project.seo.query'), dimension: 'query' }],+ [t],+ )++ const countriesSubTabs = useMemo<BreakdownSubTab[]>(+ () => [+ { id: 'country', label: t('project.mapping.cc'), dimension: 'country' },+ ],+ [t],+ )++ const devicesSubTabs = useMemo<BreakdownSubTab[]>(+ () => [+ { id: 'device', label: t('project.mapping.dv'), dimension: 'device' },+ ],+ [t],+ )++ const header = (+ <DashboardHeader+ showSearchButton={false}+ rightContent={<ProjectViewHeaderActions tnMapping={tnMapping} />}+ timeBucketSelectorItems={seoPeriodPairs}+ />+ )++ if (statusQuery.isLoading) {return (<>- <DashboardHeader- showSearchButton={false}- showRefreshButton={false}- rightContent={- <ProjectViewHeaderActions- tnMapping={tnMapping}- extraActions={manualRefreshButton}- />- }- timeBucketSelectorItems={seoPeriodPairs}- />+ {header}+ <div className='flex min-h-[400px] items-center justify-center'>+ <Loader />+ </div>+ </>+ )+ }++ if (statusQuery.isError) {+ return (+ <>+ {header}<div className='mx-auto flex min-h-[400px] max-w-xl flex-col items-center justify-center px-4 text-center'><Text as='h3' size='lg' weight='medium'>{t('apiNotifications.somethingWentWrong')}</Text>- <Text as='p' size='sm' colour='secondary' className='mt-2'>- {gscError}- </Text>+ <Button+ className='mt-3 gap-1.5'+ onClick={() => statusQuery.refetch()}+ variant='secondary'+ size='sm'+ >+ <ArrowsClockwiseIcon className='size-4' />+ {t('project.refreshStats')}+ </Button></div></>)}- if (data?.notConnected) {+ if (!isConnected) {return (<>- <DashboardHeader- showSearchButton={false}- showRefreshButton={false}- rightContent={- <ProjectViewHeaderActions- tnMapping={tnMapping}- extraActions={manualRefreshButton}- />- }- timeBucketSelectorItems={seoPeriodPairs}- />+ {header}<div className='mx-auto w-full max-w-2xl py-16 text-center'><div className='mx-auto mb-6 flex size-14 items-center justify-center rounded-xl bg-gray-100 dark:bg-slate-900'><PlugIcon@@ -778,7 +694,7 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {}}/></Text>- {data?.noProperty ? (+ {status?.connected && !status?.property ? (<Textas='p'size='sm'@@ -799,23 +715,15 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {)}+ const isHeroLoading = summaryQuery.isPending || timeseriesQuery.isPending+ const isHeroError = summaryQuery.isError || timeseriesQuery.isError+return (<>- <DashboardHeader- showSearchButton={false}- showRefreshButton={false}- rightContent={- <ProjectViewHeaderActions- tnMapping={tnMapping}- extraActions={manualRefreshButton}- />- }- timeBucketSelectorItems={seoPeriodPairs}- />+ {header}{filters.length > 0 ? (<Filters className='mb-3' tnMapping={tnMapping} />) : null}- {gscLoading && data ? <LoadingBar /> : null}<div className='relative overflow-hidden rounded-lg border border-gray-200 bg-white p-4 dark:border-slate-800/60 dark:bg-slate-900/25'><div className='mb-3 flex w-full items-center justify-end gap-1 lg:absolute lg:top-2 lg:right-2 lg:mb-0 lg:w-auto lg:justify-normal'>@@ -856,10 +764,10 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {<div className='mb-5 flex flex-wrap justify-center gap-5 lg:justify-start'><MetricCardlabel={t('project.seo.clicks')}- value={data?.summary?.clicks ?? 0}+ value={summary?.clicks ?? 0}change={comparisonSummary- ? (data?.summary?.clicks ?? 0) - comparisonSummary.clicks+ ? (summary?.clicks ?? 0) - comparisonSummary.clicks: undefined}goodChangeDirection='down'@@ -873,11 +781,10 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {/><MetricCardlabel={t('project.seo.impressions')}- value={data?.summary?.impressions ?? 0}+ value={summary?.impressions ?? 0}change={comparisonSummary- ? (data?.summary?.impressions ?? 0) -- comparisonSummary.impressions+ ? (summary?.impressions ?? 0) - comparisonSummary.impressions: undefined}goodChangeDirection='down'@@ -891,10 +798,10 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {/><MetricCardlabel={t('project.seo.avgCTR')}- value={_round(data?.summary?.ctr ?? 0, 2)}+ value={_round(summary?.ctr ?? 0, 2)}change={comparisonSummary- ? _round((data?.summary?.ctr ?? 0) - comparisonSummary.ctr, 2)+ ? _round((summary?.ctr ?? 0) - comparisonSummary.ctr, 2): undefined}type='percent'@@ -909,11 +816,11 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {/><MetricCardlabel={t('project.seo.avgPosition')}- value={_round(data?.summary?.position ?? 0, 1)}+ value={_round(summary?.position ?? 0, 1)}change={comparisonSummary? _round(- (data?.summary?.position ?? 0) - comparisonSummary.position,+ (summary?.position ?? 0) - comparisonSummary.position,1,): undefined@@ -928,12 +835,29 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {}/></div>- {isSEOLoading ? (+ {isHeroError ? (+ <div className='flex h-80 flex-col items-center justify-center text-center'>+ <Text as='p' size='sm' colour='secondary'>+ {t('apiNotifications.somethingWentWrong')}+ </Text>+ <Button+ className='mt-3 gap-1.5'+ onClick={() => {+ summaryQuery.refetch()+ timeseriesQuery.refetch()+ }}+ variant='secondary'+ size='sm'+ >+ <ArrowsClockwiseIcon className='size-4' />+ {t('project.refreshStats')}+ </Button>+ </div>+ ) : isHeroLoading ? (<div className='flex h-80 items-center justify-center'><Loader className='pt-0!' /></div>- ) : null}- {anyMetricActive && !_isEmpty(aggregatedSeries) ? (+ ) : anyMetricActive && !_isEmpty(series) ? (<divonContextMenu={(event) =>handleChartContextMenu(event, chartXAxisData)@@ -945,8 +869,8 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {options={chartOptions}className='h-80 [&_svg]:overflow-visible!'deps={[- aggregatedSeries,- aggregatedCompareSeries,+ series,+ compareSeries,activeMetrics,seoTimeBucket,timeFormat,@@ -964,24 +888,31 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {data={searchEngineEntries}icon={panelIconMapping.referrer}rowMapper={refRowMapper}- isLoading={isSEOLoading}+ isLoading={referrerQuery.isLoading}/><CompactReferralPaneltitle={t('project.seo.aiReferrals')}data={aiReferralEntries}icon={<RobotIcon className='h-5 w-5' />}rowMapper={refRowMapper}- isLoading={isSEOLoading}+ isLoading={referrerQuery.isLoading}/>- <div className='overflow-hidden rounded-lg border border-gray-200 bg-white px-4 py-3 dark:border-slate-800/60 dark:bg-slate-900/25'>+ <div+ ref={brandedRef}+ className='overflow-hidden rounded-lg border border-gray-200 bg-white px-4 py-3 dark:border-slate-800/60 dark:bg-slate-900/25'+ ><div className='mb-1 flex items-center gap-1 text-gray-900 dark:text-gray-50'><MagnifyingGlassIcon className='size-5' /><Text size='sm' weight='semibold'>{t('project.seo.brandedTraffic')}</Text></div>- {isSEOLoading ? (+ {brandedQuery.isPending ? (<PanelLoadingState />+ ) : brandedQuery.isError ? (+ <PanelEmptyState+ message={t('apiNotifications.somethingWentWrong')}+ />) : isBrandedTrafficSkipped ? (<PanelEmptyState message={t('project.seo.analyticsSkipped')} />) : brandedTraffic.branded + brandedTraffic.nonBranded > 0 ? (@@ -996,15 +927,23 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {</div></div>- <div className='mt-3 grid grid-cols-1 gap-3 xl:grid-cols-[minmax(0,0.9fr)_minmax(0,1.35fr)]'>+ <div+ ref={positionsRef}+ className='mt-3 grid grid-cols-1 gap-3 xl:grid-cols-[minmax(0,0.9fr)_minmax(0,1.35fr)]'+ ><PanelContainername={t('project.seo.impressionsByPosition')}icon={<ChartBarIcon className='size-5' />}type='impressionsByPosition'contentClassName='relative flex min-h-[21rem] flex-col overflow-hidden'- isLoading={isSEOLoading}+ isLoading={positionsQuery.isPending}+ isRefetching={positionsQuery.isFetching && !positionsQuery.isPending}>- {isPositionAnalyticsSkipped ? (+ {positionsQuery.isError ? (+ <PanelEmptyState+ message={t('apiNotifications.somethingWentWrong')}+ />+ ) : isPositionAnalyticsSkipped ? (<PanelEmptyState message={t('project.seo.analyticsSkipped')} />) : hasImpressionsByPositionData ? (<BillboardChart@@ -1022,9 +961,14 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {icon={<TrendUpIcon className='size-5' />}type='organicPositions'contentClassName='relative flex min-h-[21rem] flex-col overflow-hidden'- isLoading={isSEOLoading}+ isLoading={positionsQuery.isPending}+ isRefetching={positionsQuery.isFetching && !positionsQuery.isPending}>- {isPositionAnalyticsSkipped ? (+ {positionsQuery.isError ? (+ <PanelEmptyState+ message={t('apiNotifications.somethingWentWrong')}+ />+ ) : isPositionAnalyticsSkipped ? (<PanelEmptyState message={t('project.seo.analyticsSkipped')} />) : hasOrganicPositions ? (<BillboardChart@@ -1039,41 +983,41 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {</div><div className='mt-3 grid grid-cols-1 gap-3 sm:grid-cols-2'>- <Panel+ <BreakdownPanel+ dataType='seo'+ panelId='pages'name={t('project.seo.topPages')}- data={topPagesAsEntries}icon={panelIconMapping.page}- id='pg'- activeTabId='pg'- disableRowClick={false}+ subTabs={pagesSubTabs}+ primaryMetric='clicks'+ metrics={SEO_BREAKDOWN_METRICS}+ sort={SEO_SORT}getFilterLink={getFilterLink}valuesHeaderName={t('project.seo.clicks')}detailsExtraColumns={detailsExtraColumns}hidePercentageInDetails- dataLoading={gscLoading}- isLoading={isSEOLoading}rowTooltipRenderer={seoGscRowTooltip}rowTooltipFollowCursor/>- <Panel+ <BreakdownPanel+ dataType='seo'+ panelId='queries'name={t('project.seo.topQueries')}- data={topQueriesAsEntries}icon={<MagnifyingGlassIcon className='h-5 w-5' />}- id='keywords'- activeTabId='keywords'- disableRowClick={false}+ subTabs={queriesSubTabs}+ primaryMetric='clicks'+ metrics={SEO_BREAKDOWN_METRICS}+ sort={SEO_SORT}getFilterLink={getFilterLink}valuesHeaderName={t('project.seo.clicks')}detailsExtraColumns={detailsExtraColumns}hidePercentageInDetails- dataLoading={gscLoading}- isLoading={isSEOLoading}rowTooltipRenderer={seoGscRowTooltip}rowTooltipFollowCursor/></div>- <div className='mt-3'>+ <div className='mt-3' ref={quadrantRef}><PanelContainername={t('project.seo.quadrant')}icon={<TargetIcon className='size-5' />}@@ -1097,10 +1041,14 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {}contentClassName=''>- {isSEOLoading ? (+ {quadrantQuery.isPending ? (<div className='flex h-[400px] items-center justify-center'><Loader className='pt-0!' /></div>+ ) : quadrantQuery.isError ? (+ <PanelEmptyState+ message={t('apiNotifications.somethingWentWrong')}+ />) : quadrantData ? (<BillboardChartoptions={quadrantChartOptions}@@ -1114,36 +1062,36 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {</div><div className='mt-3 grid grid-cols-1 gap-3 sm:grid-cols-2'>- <Panel+ <BreakdownPanel+ dataType='seo'+ panelId='location'name={t('project.location')}- data={topCountriesAsEntries}icon={<MapPinIcon className='h-5 w-5' />}- id='country'- activeTabId='cc'- disableRowClick- getFilterLink={noopFilterLink}+ subTabs={countriesSubTabs}+ primaryMetric='clicks'+ metrics={SEO_BREAKDOWN_METRICS}+ sort={SEO_SORT}+ getFilterLink={getFilterLink}rowMapper={countryRowMapper}valuesHeaderName={t('project.seo.clicks')}detailsExtraColumns={detailsExtraColumns}hidePercentageInDetails- dataLoading={gscLoading}- isLoading={isSEOLoading}/>- <Panel+ <BreakdownPanel+ dataType='seo'+ panelId='devices'name={t('project.devices')}- data={topDevicesAsEntries}icon={panelIconMapping.device}- id='device'- activeTabId='dv'- disableRowClick- getFilterLink={noopFilterLink}+ subTabs={devicesSubTabs}+ primaryMetric='clicks'+ metrics={SEO_BREAKDOWN_METRICS}+ sort={SEO_SORT}+ getFilterLink={getFilterLink}rowMapper={deviceRowMapper}- capitalize+ capitalize={['device']}valuesHeaderName={t('project.seo.clicks')}detailsExtraColumns={detailsExtraColumns}hidePercentageInDetails- dataLoading={gscLoading}- isLoading={isSEOLoading}/></div>@@ -1190,8 +1138,7 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {const SEOView = ({ projectId, tnMapping }: SEOViewProps) => {const [searchParams] = useSearchParams()- const { seoRefreshTrigger } = useRefreshTriggers()- const resetKey = `seo:${projectId}:${searchParams.toString()}:${seoRefreshTrigger}`+ const resetKey = `seo:${projectId}:${searchParams.toString()}`return (<TabErrorBoundary titleKey='dashboard.failedToLoadSeo' resetKey={resetKey}>diff --git a/web/app/pages/Project/tabs/SEO/seo-utils.ts b/web/app/pages/Project/tabs/SEO/seo-utils.tsindex 987e47625..a86422d9c 100644--- a/web/app/pages/Project/tabs/SEO/seo-utils.ts+++ b/web/app/pages/Project/tabs/SEO/seo-utils.ts@@ -1,9 +1,4 @@-import dayjs from 'dayjs'-import isoWeek from 'dayjs/plugin/isoWeek'-import quarterOfYear from 'dayjs/plugin/quarterOfYear'--dayjs.extend(isoWeek)-dayjs.extend(quarterOfYear)+import { TimeseriesRow } from '~/api/v2/types'export const SEO_METRICS = {clicks: 'clicks',@@ -54,75 +49,25 @@ export interface DateSeriesEntry {position: number}-const getBucketKey = (date: string, bucket: string): string => {- const d = dayjs(date)- switch (bucket) {- case 'hour':- case 'day':- return date- case 'week':- return d.startOf('isoWeek').format('YYYY-MM-DD')- case 'month':- return d.startOf('month').format('YYYY-MM-DD')- case 'quarter':- return d.startOf('quarter').format('YYYY-MM-DD')- case 'year':- return d.startOf('year').format('YYYY-MM-DD')- default:- return date- }-}--export const aggregateDateSeries = (- series: DateSeriesEntry[],- bucket: string,-): DateSeriesEntry[] => {- if (!series.length || bucket === 'day' || bucket === 'hour') return series-- const buckets = new Map<- string,- {- clicks: number- impressions: number- weightedPosition: number- }- >()- const orderedKeys: string[] = []-- for (const entry of series) {- const key = getBucketKey(entry.date, bucket)- const existing = buckets.get(key)- if (existing) {- existing.clicks += entry.clicks- existing.impressions += entry.impressions- existing.weightedPosition += entry.position * entry.impressions- } else {- orderedKeys.push(key)- buckets.set(key, {- clicks: entry.clicks,- impressions: entry.impressions,- weightedPosition: entry.position * entry.impressions,- })- }- }-- return orderedKeys.map((key) => {- const b = buckets.get(key)!- return {- date: key,- clicks: b.clicks,- impressions: b.impressions,- ctr:- b.impressions > 0- ? Number(((b.clicks / b.impressions) * 100).toFixed(2))- : 0,- position:- b.impressions > 0- ? Number((b.weightedPosition / b.impressions).toFixed(1))- : 0,- }- })-}+/**+ * The v2 SEO timeseries is already bucketed server-side; this only reshapes its+ * ISO timestamps into the plain date strings the chart builders plot on the x+ * axis.+ */+export const seoTimeseriesToDateSeries = (+ rows: TimeseriesRow[] | undefined,+ timeBucket: string,+): DateSeriesEntry[] =>+ (rows ?? []).map((row) => ({+ date:+ timeBucket === 'hour'+ ? row.timestamp.slice(0, 19).replace('T', ' ')+ : row.timestamp.slice(0, 10),+ clicks: Number(row.clicks ?? 0),+ impressions: Number(row.impressions ?? 0),+ ctr: Number(row.ctr ?? 0),+ position: Number(row.position ?? 0),+ }))export const hasOrganicPositionData = (series: OrganicPositionEntry[],diff --git a/web/app/routes/api.analytics.ts b/web/app/routes/api.analytics.tsindex 42ae49933..c050a20f1 100644--- a/web/app/routes/api.analytics.ts+++ b/web/app/routes/api.analytics.ts@@ -26,8 +26,6 @@ import {getJourneysServer,getJourneySessionsServer,getGSCKeywordsServer,- getGSCDashboardServer,- getGSCDetailsServer,getRevenueStatusServer,getRevenueDataServer,getOverallStatsServer,@@ -52,8 +50,6 @@ import {type JourneysResponse,type JourneySessionsResponse,type GSCKeywordsResponse,- type GSCDashboardResponse,- type GSCDetailsResponse,type RevenueStatus,type RevenueDataResponse,type OverallObject,@@ -99,8 +95,6 @@ interface ProxyRequest {| 'getJourneys'| 'getJourneySessions'| 'getGSCKeywords'- | 'getGSCDashboard'- | 'getGSCDetails'| 'getRevenueStatus'| 'getRevenueData'| 'getOverallStats'@@ -627,46 +621,6 @@ export async function action({ request }: ActionFunctionArgs) {})}- case 'getGSCDashboard': {- const result = await getGSCDashboardServer(request, projectId, {- period: params.period,- from: formatDateForBackend(params.from),- to: formatDateForBackend(params.to),- timezone: params.timezone,- password: password || undefined,- timeBucket: params.timeBucket,- filters: params.filters,- })- return data<ProxyResponse<GSCDashboardResponse>>({- data: result.data,- error: result.error- ? Array.isArray(result.error)- ? result.error.join(', ')- : result.error- : null,- })- }-- case 'getGSCDetails': {- const result = await getGSCDetailsServer(request, projectId, {- period: params.period,- from: formatDateForBackend(params.from),- to: formatDateForBackend(params.to),- timezone: params.timezone,- password: password || undefined,- page: params.page,- query: params.query,- })- return data<ProxyResponse<GSCDetailsResponse>>({- data: result.data,- error: result.error- ? Array.isArray(result.error)- ? result.error.join(', ')- : result.error- : null,- })- }-case 'getRevenueStatus': {const result = await getRevenueStatusServer(request, projectId)return data<ProxyResponse<RevenueStatus>>({diff --git a/web/app/utils/analyticsUrl.ts b/web/app/utils/analyticsUrl.tsindex 04a231819..600bb6dc4 100644--- a/web/app/utils/analyticsUrl.ts+++ b/web/app/utils/analyticsUrl.ts@@ -60,10 +60,6 @@ export const parseFilterKey = (rawKey: string): ParsedFilterKey | null => {return { dimension: key, operator }}- if (key === 'keywords') {- return { dimension: key, operator }- }-return null}