@oneclick.dev/cms-core-modules 0.0.70 → 0.0.72

package/src/googleAnalytics/server.ts

@@ -0,0 +1,1188 @@
+import { createRouter, defineEventHandler, createError, getQuery } from 'h3'
+
+/**
+ * Dependencies injected by the CMS when creating this handler.
+ */
+export interface ModuleHandlerDeps {
+  initFirebase: (event: any, integrationId: string) => Promise<any>
+  normalizeTimestamps: (data: any) => any
+  decrypt: (data: string) => string
+  getGoogleAccessToken: (config: { clientEmail: string; privateKey: string; projectId: string }, scopes: string[]) => Promise<string>
+}
+
+const GA_DATA_API = 'https://analyticsdata.googleapis.com/v1beta'
+const GA_SCOPES = [
+  'https://www.googleapis.com/auth/analytics.readonly',
+  'https://www.googleapis.com/auth/webmasters.readonly',
+]
+const SEARCH_CONSOLE_API = 'https://searchconsole.googleapis.com/webmasters/v3'
+
+/**
+ * Google Analytics module server handler factory.
+ *
+ * Routes (relative to `/api/v1/modules/:instanceId/`):
+ *   GET /report                → overview report with period comparison
+ *   GET /realtime              → real-time active users + pages + sources
+ *   GET /top-pages             → top pages by views
+ *   GET /top-sources           → top traffic sources
+ *   GET /devices               → device category breakdown
+ *   GET /countries             → top countries
+ *   GET /acquisition/channels  → channel grouping breakdown
+ *   GET /acquisition/campaigns → campaign performance
+ *   GET /acquisition/referrals → referral sources with landing pages
+ *   GET /content/all-pages     → all pages with deep metrics
+ *   GET /content/landing-pages → top landing (entry) pages
+ *   GET /content/exit-pages    → top exit pages
+ *   GET /audience/overview     → new vs returning, engagement rate
+ *   GET /audience/technology   → browser + OS breakdown
+ *   GET /audience/languages    → language breakdown
+ *   GET /audience/hours        → sessions by hour-of-day (peak hours)
+ */
+export function createServerHandler(deps: ModuleHandlerDeps) {
+  const { decrypt, getGoogleAccessToken } = deps
+  const router = createRouter()
+
+  /**
+   * Resolve the Google Service Account credentials + property ID from the module config.
+   */
+  async function getGAContext(event: any) {
+    const { supabase, instanceId } = event.context.module
+
+    const { data: moduleRow, error } = await supabase
+      .from('project_modules')
+      .select('config')
+      .eq('id', instanceId)
+      .single()
+
+    if (error || !moduleRow?.config) {
+      throw createError({ statusCode: 500, statusMessage: 'Failed to load module config.' })
+    }
+
+    const config = moduleRow.config as Record<string, any>
+    const propertyId = config.propertyId as string
+    const integrationId = config.serviceAccount as string
+    const siteUrl = (config.siteUrl as string) || ''
+
+    if (!integrationId) {
+      throw createError({ statusCode: 400, statusMessage: 'No Google Service Account configured for this module.' })
+    }
+    if (!propertyId) {
+      throw createError({ statusCode: 400, statusMessage: 'No GA4 Property ID configured for this module.' })
+    }
+
+    const { data: integration, error: intError } = await supabase
+      .from('integrations')
+      .select('config')
+      .eq('id', integrationId)
+      .single()
+
+    let integrationConfig = integration?.config
+    if (intError || !integrationConfig) {
+      const { data: agencyInt, error: agencyErr } = await supabase
+        .from('agency_integrations')
+        .select('config')
+        .eq('id', integrationId)
+        .single()
+
+      if (agencyErr || !agencyInt?.config) {
+        throw createError({ statusCode: 500, statusMessage: 'Failed to load Google Service Account credentials.' })
+      }
+      integrationConfig = agencyInt.config
+    }
+
+    const clientEmail = decrypt(integrationConfig.clientEmail)
+    const privateKey = decrypt(integrationConfig.privateKey)
+    const projectId = decrypt(integrationConfig.projectId)
+
+    const accessToken = await getGoogleAccessToken(
+      { clientEmail, privateKey, projectId },
+      GA_SCOPES,
+    )
+
+    return { accessToken, propertyId, siteUrl }
+  }
+
+  /**
+   * Call the GA4 Data API's runReport endpoint.
+   */
+  async function runReport(accessToken: string, propertyId: string, body: Record<string, any>) {
+    const res = await fetch(`${GA_DATA_API}/properties/${propertyId}:runReport`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}))
+      console.error('GA4 runReport failed:', err)
+      throw createError({
+        statusCode: res.status,
+        statusMessage: err?.error?.message || 'GA4 API request failed',
+      })
+    }
+
+    return res.json()
+  }
+
+  // ═══════════════════════════════════════════════════════
+  //  OVERVIEW ROUTES
+  // ═══════════════════════════════════════════════════════
+
+  // ── GET /report ──────────────────────────────────────
+  // Returns current period + previous period data for % change comparison
+  router.get(
+    '/report',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      // Calculate previous period for comparison
+      const daysMatch = startDate.match(/^(\d+)daysAgo$/)
+      const days = daysMatch ? parseInt(daysMatch[1], 10) : 30
+      const prevStartDate = `${days * 2}daysAgo`
+      const prevEndDate = `${days + 1}daysAgo`
+
+      const reportMetrics = [
+        { name: 'sessions' },
+        { name: 'totalUsers' },
+        { name: 'screenPageViews' },
+        { name: 'bounceRate' },
+        { name: 'averageSessionDuration' },
+        { name: 'newUsers' },
+        { name: 'engagementRate' },
+        { name: 'sessionsPerUser' },
+        { name: 'screenPageViewsPerSession' },
+      ]
+
+      // Try with comparison period first; fall back to current-only if it fails
+      // (e.g. property is newer than the previous period range)
+      let raw: any
+      let hasComparison = true
+      try {
+        raw = await runReport(accessToken, propertyId, {
+          dateRanges: [
+            { startDate, endDate, name: 'current' },
+            { startDate: prevStartDate, endDate: prevEndDate, name: 'previous' },
+          ],
+          dimensions: [{ name: 'date' }],
+          metrics: reportMetrics,
+          metricAggregations: ['TOTAL'],
+          orderBys: [{ dimension: { dimensionName: 'date' } }],
+        })
+      } catch {
+        hasComparison = false
+        raw = await runReport(accessToken, propertyId, {
+          dateRanges: [{ startDate, endDate }],
+          dimensions: [{ name: 'date' }],
+          metrics: reportMetrics,
+          metricAggregations: ['TOTAL'],
+          orderBys: [{ dimension: { dimensionName: 'date' } }],
+        })
+      }
+
+      return transformComparisonReport(raw, hasComparison)
+    }),
+  )
+
+  // ── GET /realtime ────────────────────────────────────
+  router.get(
+    '/realtime',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+
+      const res = await fetch(
+        `${GA_DATA_API}/properties/${propertyId}:runRealtimeReport`,
+        {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            dimensions: [{ name: 'unifiedScreenName' }],
+            metrics: [{ name: 'activeUsers' }],
+            orderBys: [{ metric: { metricName: 'activeUsers' }, desc: true }],
+            limit: 5,
+          }),
+        },
+      )
+
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({}))
+        throw createError({ statusCode: res.status, statusMessage: err?.error?.message || 'Realtime API failed' })
+      }
+
+      const data = await res.json()
+      const totalActive = (data?.rows || []).reduce(
+        (sum: number, r: any) => sum + parseInt(r.metricValues?.[0]?.value || '0', 10),
+        0,
+      )
+      const activePages = (data?.rows || []).map((r: any) => ({
+        page: r.dimensionValues?.[0]?.value || '(not set)',
+        activeUsers: parseInt(r.metricValues?.[0]?.value || '0', 10),
+      }))
+
+      return { activeUsers: totalActive, activePages }
+    }),
+  )
+
+  // ── GET /top-pages ───────────────────────────────────
+  router.get(
+    '/top-pages',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+      const limit = parseInt((query.limit as string) || '10', 10)
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'pagePath' }],
+        metrics: [
+          { name: 'screenPageViews' },
+          { name: 'totalUsers' },
+          { name: 'averageSessionDuration' },
+        ],
+        orderBys: [{ metric: { metricName: 'screenPageViews' }, desc: true }],
+        limit: limit * 2, // fetch extra to account for duplicates before aggregation
+      })
+
+      const result = transformDimensionReport(raw, 'pagePath')
+
+      // Aggregate rows with the same pagePath (GA4 can split the same
+      // page across multiple rows due to casing / trailing-slash differences)
+      const map = new Map<string, any>()
+      for (const row of result.rows) {
+        const key = (row.pagePath as string).toLowerCase().replace(/\/+$/, '')
+        const existing = map.get(key)
+        if (existing) {
+          existing.screenPageViews += row.screenPageViews || 0
+          existing.totalUsers += row.totalUsers || 0
+          // Weighted average for session duration
+          const totalViews = existing.screenPageViews
+          if (totalViews > 0) {
+            existing.averageSessionDuration =
+              ((existing.averageSessionDuration * (totalViews - (row.screenPageViews || 0)))
+               + (row.averageSessionDuration || 0) * (row.screenPageViews || 0)) / totalViews
+          }
+        } else {
+          map.set(key, { ...row })
+        }
+      }
+
+      const aggregated = [...map.values()]
+        .sort((a, b) => (b.screenPageViews || 0) - (a.screenPageViews || 0))
+        .slice(0, limit)
+
+      return { rows: aggregated, rowCount: result.rowCount }
+    }),
+  )
+
+  // ── GET /top-sources ─────────────────────────────────
+  router.get(
+    '/top-sources',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'sessionSource' }],
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+        ],
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+        limit: 10,
+      })
+
+      return transformDimensionReport(raw, 'sessionSource')
+    }),
+  )
+
+  // ── GET /devices ─────────────────────────────────────
+  router.get(
+    '/devices',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'deviceCategory' }],
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+        ],
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+      })
+
+      return transformDimensionReport(raw, 'deviceCategory')
+    }),
+  )
+
+  // ── GET /countries ───────────────────────────────────
+  router.get(
+    '/countries',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'country' }],
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+        ],
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+        limit: 10,
+      })
+
+      return transformDimensionReport(raw, 'country')
+    }),
+  )
+
+  // ═══════════════════════════════════════════════════════
+  //  ACQUISITION ROUTES
+  // ═══════════════════════════════════════════════════════
+
+  // ── GET /acquisition/channels ────────────────────────
+  router.get(
+    '/acquisition/channels',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'sessionDefaultChannelGroup' }],
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+          { name: 'newUsers' },
+          { name: 'engagementRate' },
+          { name: 'averageSessionDuration' },
+          { name: 'screenPageViewsPerSession' },
+          { name: 'conversions' },
+        ],
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+        limit: 15,
+      })
+
+      return transformDimensionReport(raw, 'sessionDefaultChannelGroup')
+    }),
+  )
+
+  // ── GET /acquisition/source-medium ───────────────────
+  router.get(
+    '/acquisition/source-medium',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'sessionSourceMedium' }],
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+          { name: 'newUsers' },
+          { name: 'bounceRate' },
+          { name: 'averageSessionDuration' },
+          { name: 'conversions' },
+        ],
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+        limit: 20,
+      })
+
+      return transformDimensionReport(raw, 'sessionSourceMedium')
+    }),
+  )
+
+  // ── GET /acquisition/referrals ───────────────────────
+  router.get(
+    '/acquisition/referrals',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'sessionSource' }],
+        dimensionFilter: {
+          filter: {
+            fieldName: 'sessionMedium',
+            stringFilter: { value: 'referral' },
+          },
+        },
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+          { name: 'engagementRate' },
+          { name: 'averageSessionDuration' },
+        ],
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+        limit: 20,
+      })
+
+      return transformDimensionReport(raw, 'sessionSource')
+    }),
+  )
+
+  // ── GET /acquisition/campaigns ───────────────────────
+  router.get(
+    '/acquisition/campaigns',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'sessionCampaignName' }],
+        dimensionFilter: {
+          notExpression: {
+            filter: {
+              fieldName: 'sessionCampaignName',
+              stringFilter: { value: '(not set)' },
+            },
+          },
+        },
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+          { name: 'conversions' },
+          { name: 'engagementRate' },
+        ],
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+        limit: 20,
+      })
+
+      return transformDimensionReport(raw, 'sessionCampaignName')
+    }),
+  )
+
+  // ═══════════════════════════════════════════════════════
+  //  CONTENT / SEO ROUTES
+  // ═══════════════════════════════════════════════════════
+
+  // ── GET /content/all-pages ───────────────────────────
+  router.get(
+    '/content/all-pages',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+      const limit = parseInt((query.limit as string) || '50', 10)
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'pagePath' }],
+        metrics: [
+          { name: 'screenPageViews' },
+          { name: 'totalUsers' },
+          { name: 'averageSessionDuration' },
+          { name: 'bounceRate' },
+          { name: 'engagementRate' },
+          { name: 'sessions' },
+          { name: 'userEngagementDuration' },
+        ],
+        orderBys: [{ metric: { metricName: 'screenPageViews' }, desc: true }],
+        limit,
+      })
+
+      return transformDimensionReport(raw, 'pagePath')
+    }),
+  )
+
+  // ── GET /content/landing-pages ───────────────────────
+  router.get(
+    '/content/landing-pages',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'landingPagePlusQueryString' }],
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+          { name: 'bounceRate' },
+          { name: 'averageSessionDuration' },
+          { name: 'screenPageViews' },
+          { name: 'engagementRate' },
+        ],
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+        limit: 30,
+      })
+
+      return transformDimensionReport(raw, 'landingPagePlusQueryString')
+    }),
+  )
+
+  // ── GET /content/exit-pages ──────────────────────────
+  router.get(
+    '/content/exit-pages',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'pagePath' }],
+        metrics: [
+          { name: 'sessions' },
+          { name: 'screenPageViews' },
+          { name: 'totalUsers' },
+          { name: 'bounceRate' },
+        ],
+        orderBys: [{ metric: { metricName: 'screenPageViews' }, desc: true }],
+        limit: 20,
+      })
+
+      // Compute approximate exit rate from bounce rate
+      const result = transformDimensionReport(raw, 'pagePath')
+      result.rows = result.rows.map((row: any) => ({
+        ...row,
+        exitRate: row.bounceRate || 0,
+      }))
+      return result
+    }),
+  )
+
+  // ── GET /content/search-terms ──────────────────────────
+  // Step 1: Try Google Search Console (real organic keywords).
+  // Step 2: Try Google Ads search queries from GA4.
+  // Step 3: Fall back to top organic-search landing pages.
+  router.get(
+    '/content/search-terms',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId, siteUrl } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      // 1) Try Google Search Console if siteUrl is configured
+      if (siteUrl) {
+        try {
+          const gscUrl = `${SEARCH_CONSOLE_API}/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`
+          console.log('[GA Module] Attempting Search Console query for site:', siteUrl)
+          const gscRes = await fetch(
+            gscUrl,
+            {
+              method: 'POST',
+              headers: {
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json',
+              },
+              body: JSON.stringify({
+                startDate: resolveDate(startDate),
+                endDate: resolveDate(endDate),
+                dimensions: ['query'],
+                rowLimit: 30,
+              }),
+            },
+          )
+
+          if (gscRes.ok) {
+            const gscData = await gscRes.json()
+            const rows = (gscData.rows || []).map((row: any) => ({
+              query: row.keys[0],
+              clicks: row.clicks,
+              impressions: row.impressions,
+              ctr: row.ctr,
+              position: row.position,
+            }))
+
+            if (rows.length > 0) {
+              console.log(`[GA Module] Search Console returned ${rows.length} keyword rows`)
+              return {
+                rows,
+                rowCount: rows.length,
+                source: 'search_console',
+              }
+            }
+            console.log('[GA Module] Search Console returned 0 rows, falling through')
+          } else {
+            const errBody = await gscRes.text().catch(() => '')
+            console.error(`[GA Module] Search Console API error (${gscRes.status}):`, errBody)
+          }
+        } catch (gscErr: any) {
+          console.error('[GA Module] Search Console request failed:', gscErr?.message || gscErr)
+        }
+      } else {
+        console.log('[GA Module] No siteUrl configured, skipping Search Console')
+      }
+
+      // 2) Try sessionGoogleAdsQuery (real search query text from Google Ads)
+      try {
+        const adsRaw = await runReport(accessToken, propertyId, {
+          dateRanges: [{ startDate, endDate }],
+          dimensions: [{ name: 'sessionGoogleAdsQuery' }],
+          metrics: [
+            { name: 'sessions' },
+            { name: 'totalUsers' },
+            { name: 'engagementRate' },
+          ],
+          dimensionFilter: {
+            andGroup: {
+              expressions: [
+                {
+                  notExpression: {
+                    filter: {
+                      fieldName: 'sessionGoogleAdsQuery',
+                      stringFilter: { value: '(not set)' },
+                    },
+                  },
+                },
+                {
+                  notExpression: {
+                    filter: {
+                      fieldName: 'sessionGoogleAdsQuery',
+                      stringFilter: { value: '(not provided)' },
+                    },
+                  },
+                },
+              ],
+            },
+          },
+          orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+          limit: 30,
+        })
+
+        const adsResult = transformDimensionReport(adsRaw, 'sessionGoogleAdsQuery')
+        if (adsResult.rows.length > 0) {
+          return { ...adsResult, source: 'google_ads' }
+        }
+      } catch {
+        // Dimension may not be available — fall through to organic landing pages
+      }
+
+      // 3) Fallback: top landing pages from organic search traffic
+      const organicRaw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'landingPagePlusQueryString' }],
+        metrics: [
+          { name: 'sessions' },
+          { name: 'totalUsers' },
+          { name: 'engagementRate' },
+        ],
+        dimensionFilter: {
+          andGroup: {
+            expressions: [
+              {
+                filter: {
+                  fieldName: 'sessionMedium',
+                  stringFilter: {
+                    matchType: 'EXACT',
+                    value: 'organic',
+                  },
+                },
+              },
+              {
+                notExpression: {
+                  filter: {
+                    fieldName: 'landingPagePlusQueryString',
+                    stringFilter: { value: '(not set)' },
+                  },
+                },
+              },
+            ],
+          },
+        },
+        orderBys: [{ metric: { metricName: 'sessions' }, desc: true }],
+        limit: 30,
+      })
+
+      const organicResult = transformDimensionReport(organicRaw, 'landingPagePlusQueryString')
+      return { ...organicResult, source: 'organic_landing_pages' }
+    }),
+  )
+
+  // ═══════════════════════════════════════════════════════
+  //  AUDIENCE ROUTES
+  // ═══════════════════════════════════════════════════════
+
+  // ── GET /audience/overview ───────────────────────────
+  router.get(
+    '/audience/overview',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'newVsReturning' }],
+        metrics: [
+          { name: 'totalUsers' },
+          { name: 'sessions' },
+          { name: 'engagementRate' },
+          { name: 'averageSessionDuration' },
+          { name: 'screenPageViewsPerSession' },
+        ],
+        metricAggregations: ['TOTAL'],
+      })
+
+      return transformDimensionReport(raw, 'newVsReturning')
+    }),
+  )
+
+  // ── GET /audience/technology ─────────────────────────
+  router.get(
+    '/audience/technology',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+      const dimension = (query.dimension as string) || 'browser'
+
+      // Allow switching between browser, operatingSystem, screenResolution
+      const allowedDimensions = ['browser', 'operatingSystem', 'screenResolution']
+      const dim = allowedDimensions.includes(dimension) ? dimension : 'browser'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: dim }],
+        metrics: [
+          { name: 'totalUsers' },
+          { name: 'sessions' },
+          { name: 'engagementRate' },
+        ],
+        orderBys: [{ metric: { metricName: 'totalUsers' }, desc: true }],
+        limit: 10,
+      })
+
+      return transformDimensionReport(raw, dim)
+    }),
+  )
+
+  // ── GET /audience/languages ──────────────────────────
+  router.get(
+    '/audience/languages',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'language' }],
+        metrics: [
+          { name: 'totalUsers' },
+          { name: 'sessions' },
+        ],
+        orderBys: [{ metric: { metricName: 'totalUsers' }, desc: true }],
+        limit: 15,
+      })
+
+      return transformDimensionReport(raw, 'language')
+    }),
+  )
+
+  // ── GET /audience/hours ──────────────────────────────
+  // Peak traffic hours heatmap data
+  router.get(
+    '/audience/hours',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'dayOfWeekName' }, { name: 'hour' }],
+        metrics: [{ name: 'sessions' }],
+        orderBys: [
+          { dimension: { dimensionName: 'dayOfWeekName' } },
+          { dimension: { dimensionName: 'hour' } },
+        ],
+        limit: 168, // 7 days × 24 hours
+      })
+
+      return transformMultiDimensionReport(raw, ['dayOfWeekName', 'hour'])
+    }),
+  )
+
+  // ── GET /audience/cities ─────────────────────────────
+  router.get(
+    '/audience/cities',
+    defineEventHandler(async (event) => {
+      const { accessToken, propertyId } = await getGAContext(event)
+      const query = getQuery(event)
+      const startDate = (query.startDate as string) || '30daysAgo'
+      const endDate = (query.endDate as string) || 'today'
+
+      const raw = await runReport(accessToken, propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'city' }, { name: 'country' }],
+        metrics: [
+          { name: 'totalUsers' },
+          { name: 'sessions' },
+        ],
+        dimensionFilter: {
+          notExpression: {
+            filter: {
+              fieldName: 'city',
+              stringFilter: { value: '(not set)' },
+            },
+          },
+        },
+        orderBys: [{ metric: { metricName: 'totalUsers' }, desc: true }],
+        limit: 20,
+      })
+
+      return transformMultiDimensionReport(raw, ['city', 'country'])
+    }),
+  )
+
+  // ═══════════════════════════════════════════════════════
+  //  SEO / SEARCH CONSOLE ROUTES
+  // ═══════════════════════════════════════════════════════
+
+  /**
+   * Helper: resolve relative GA dates like "30daysAgo" to YYYY-MM-DD for Search Console.
+   */
+  function resolveDate(d: string): string {
+    const relative = d.match(/^(\d+)daysAgo$/)
+    if (relative) {
+      const dt = new Date()
+      dt.setDate(dt.getDate() - parseInt(relative[1], 10))
+      return dt.toISOString().slice(0, 10)
+    }
+    if (d === 'today') return new Date().toISOString().slice(0, 10)
+    if (d === 'yesterday') {
+      const dt = new Date()
+      dt.setDate(dt.getDate() - 1)
+      return dt.toISOString().slice(0, 10)
+    }
+    return d
+  }
+
+  /**
+   * Call the Search Console searchAnalytics/query endpoint.
+   */
+  async function runSearchConsoleQuery(
+    accessToken: string,
+    siteUrl: string,
+    body: Record<string, any>,
+  ) {
+    const url = `${SEARCH_CONSOLE_API}/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}))
+      throw createError({
+        statusCode: res.status,
+        statusMessage: err?.error?.message || 'Search Console API request failed',
+      })
+    }
+    return res.json()
+  }
+
+  // ── GET /seo/keywords ────────────────────────────────
+  // Top search queries with clicks, impressions, CTR, position
+  router.get(
+    '/seo/keywords',
+    defineEventHandler(async (event) => {
+      const { accessToken, siteUrl } = await getGAContext(event)
+      if (!siteUrl) {
+        throw createError({ statusCode: 400, statusMessage: 'Search Console Site URL is not configured. Add it in module settings.' })
+      }
+
+      const query = getQuery(event)
+      const startDate = resolveDate((query.startDate as string) || '30daysAgo')
+      const endDate = resolveDate((query.endDate as string) || 'today')
+      const limit = Math.min(parseInt(query.limit as string) || 50, 100)
+
+      const data = await runSearchConsoleQuery(accessToken, siteUrl, {
+        startDate,
+        endDate,
+        dimensions: ['query'],
+        rowLimit: limit,
+      })
+
+      return {
+        rows: (data.rows || []).map((r: any) => ({
+          query: r.keys[0],
+          clicks: r.clicks,
+          impressions: r.impressions,
+          ctr: r.ctr,
+          position: r.position,
+        })),
+        rowCount: data.rows?.length || 0,
+      }
+    }),
+  )
+
+  // ── GET /seo/pages ───────────────────────────────────
+  // Top pages by Search Console performance
+  router.get(
+    '/seo/pages',
+    defineEventHandler(async (event) => {
+      const { accessToken, siteUrl } = await getGAContext(event)
+      if (!siteUrl) {
+        throw createError({ statusCode: 400, statusMessage: 'Search Console Site URL is not configured.' })
+      }
+
+      const query = getQuery(event)
+      const startDate = resolveDate((query.startDate as string) || '30daysAgo')
+      const endDate = resolveDate((query.endDate as string) || 'today')
+      const limit = Math.min(parseInt(query.limit as string) || 50, 100)
+
+      const data = await runSearchConsoleQuery(accessToken, siteUrl, {
+        startDate,
+        endDate,
+        dimensions: ['page'],
+        rowLimit: limit,
+      })
+
+      return {
+        rows: (data.rows || []).map((r: any) => ({
+          page: r.keys[0],
+          clicks: r.clicks,
+          impressions: r.impressions,
+          ctr: r.ctr,
+          position: r.position,
+        })),
+        rowCount: data.rows?.length || 0,
+      }
+    }),
+  )
+
+  // ── GET /seo/trends ──────────────────────────────────
+  // Daily clicks/impressions/CTR/position trend data
+  router.get(
+    '/seo/trends',
+    defineEventHandler(async (event) => {
+      const { accessToken, siteUrl } = await getGAContext(event)
+      if (!siteUrl) {
+        throw createError({ statusCode: 400, statusMessage: 'Search Console Site URL is not configured.' })
+      }
+
+      const query = getQuery(event)
+      const startDate = resolveDate((query.startDate as string) || '30daysAgo')
+      const endDate = resolveDate((query.endDate as string) || 'today')
+
+      const data = await runSearchConsoleQuery(accessToken, siteUrl, {
+        startDate,
+        endDate,
+        dimensions: ['date'],
+        rowLimit: 500,
+      })
+
+      const rows = (data.rows || [])
+        .map((r: any) => ({
+          date: r.keys[0],
+          clicks: r.clicks,
+          impressions: r.impressions,
+          ctr: r.ctr,
+          position: r.position,
+        }))
+        .sort((a: any, b: any) => a.date.localeCompare(b.date))
+
+      // Compute totals
+      const totals = rows.reduce(
+        (acc: any, r: any) => ({
+          clicks: acc.clicks + r.clicks,
+          impressions: acc.impressions + r.impressions,
+        }),
+        { clicks: 0, impressions: 0 },
+      )
+      totals.ctr = totals.impressions > 0 ? totals.clicks / totals.impressions : 0
+      totals.avgPosition =
+        rows.length > 0 ? rows.reduce((s: number, r: any) => s + r.position, 0) / rows.length : 0
+
+      return { rows, totals, rowCount: rows.length }
+    }),
+  )
+
+  // ── GET /seo/query-pages ─────────────────────────────
+  // Top queries grouped by page (for keyword-to-page mapping)
+  router.get(
+    '/seo/query-pages',
+    defineEventHandler(async (event) => {
+      const { accessToken, siteUrl } = await getGAContext(event)
+      if (!siteUrl) {
+        throw createError({ statusCode: 400, statusMessage: 'Search Console Site URL is not configured.' })
+      }
+
+      const query = getQuery(event)
+      const startDate = resolveDate((query.startDate as string) || '30daysAgo')
+      const endDate = resolveDate((query.endDate as string) || 'today')
+
+      const data = await runSearchConsoleQuery(accessToken, siteUrl, {
+        startDate,
+        endDate,
+        dimensions: ['query', 'page'],
+        rowLimit: 100,
+      })
+
+      return {
+        rows: (data.rows || []).map((r: any) => ({
+          query: r.keys[0],
+          page: r.keys[1],
+          clicks: r.clicks,
+          impressions: r.impressions,
+          ctr: r.ctr,
+          position: r.position,
+        })),
+        rowCount: data.rows?.length || 0,
+      }
+    }),
+  )
+
+  return router.handler
+}
+
+// ═══════════════════════════════════════════════════════
+//  RESPONSE TRANSFORMERS
+// ═══════════════════════════════════════════════════════
+
+/**
+ * Transform a GA4 date-dimensioned report with two date ranges into a comparison report.
+ * Returns current period rows, current totals, and previous totals for % change.
+ */
+function transformComparisonReport(raw: any, hasComparison = true) {
+  const metricHeaders = (raw.metricHeaders || []).map((h: any) => h.name)
+  const dimHeaders = (raw.dimensionHeaders || []).map((h: any) => h.name)
+  const dateIdx = dimHeaders.indexOf('date')
+
+  const allRows: any[] = []
+
+  ;(raw.rows || []).forEach((row: any) => {
+    const dateVal = dateIdx >= 0 ? row.dimensionValues[dateIdx]?.value : row.dimensionValues[0]?.value
+    if (!dateVal || dateVal.length < 8) return
+
+    const date = `${dateVal.slice(0, 4)}-${dateVal.slice(4, 6)}-${dateVal.slice(6, 8)}`
+    const entry: Record<string, any> = { date }
+    metricHeaders.forEach((metric: string, i: number) => {
+      entry[metric] = parseFloat(row.metricValues[i]?.value || '0')
+    })
+    allRows.push(entry)
+  })
+
+  // Extract totals
+  const currentTotals: Record<string, number> = {}
+  const previousTotals: Record<string, number> = {}
+
+  if (raw.totals && raw.totals.length >= 2) {
+    metricHeaders.forEach((metric: string, i: number) => {
+      currentTotals[metric] = parseFloat(raw.totals[0]?.metricValues?.[i]?.value || '0')
+      previousTotals[metric] = parseFloat(raw.totals[1]?.metricValues?.[i]?.value || '0')
+    })
+  } else if (raw.totals && raw.totals.length === 1) {
+    metricHeaders.forEach((metric: string, i: number) => {
+      currentTotals[metric] = parseFloat(raw.totals[0]?.metricValues?.[i]?.value || '0')
+    })
+  }
+
+  // Compute % change
+  const changes: Record<string, number | null> = {}
+  metricHeaders.forEach((metric: string) => {
+    const curr = currentTotals[metric] || 0
+    const prev = previousTotals[metric]
+    if (prev !== undefined && prev !== 0) {
+      changes[metric] = ((curr - prev) / prev) * 100
+    } else {
+      changes[metric] = null
+    }
+  })
+
+  // Deduplicate by date, sort chronologically
+  const byDate = new Map<string, any>()
+  for (const row of allRows) {
+    if (!byDate.has(row.date)) {
+      byDate.set(row.date, row)
+    }
+  }
+  const rows = Array.from(byDate.values()).sort((a, b) => a.date.localeCompare(b.date))
+
+  // If we had a comparison (dual date ranges), only keep the more recent half (current period)
+  const chartRows = hasComparison && raw.totals && raw.totals.length >= 2
+    ? rows.slice(-Math.ceil(rows.length / 2))
+    : rows
+
+  return {
+    rows: chartRows,
+    totals: currentTotals,
+    previousTotals,
+    changes,
+    rowCount: chartRows.length,
+  }
+}
+
+/**
+ * Transform a GA4 single-dimension report into a ranked list.
+ */
+function transformDimensionReport(raw: any, dimensionKey: string) {
+  const metricHeaders = (raw.metricHeaders || []).map((h: any) => h.name)
+
+  const rows = (raw.rows || []).map((row: any) => {
+    const entry: Record<string, any> = {
+      [dimensionKey]: row.dimensionValues[0].value,
+    }
+    metricHeaders.forEach((metric: string, i: number) => {
+      entry[metric] = parseFloat(row.metricValues[i].value)
+    })
+    return entry
+  })
+
+  return { rows, rowCount: raw.rowCount || rows.length }
+}
+
+/**
+ * Transform a GA4 multi-dimension report (e.g. pagePath + pageTitle, or dayOfWeek + hour).
+ */
+function transformMultiDimensionReport(raw: any, dimensionKeys: string[]) {
+  const metricHeaders = (raw.metricHeaders || []).map((h: any) => h.name)
+
+  const rows = (raw.rows || []).map((row: any) => {
+    const entry: Record<string, any> = {}
+    dimensionKeys.forEach((key, di) => {
+      entry[key] = row.dimensionValues[di]?.value || ''
+    })
+    metricHeaders.forEach((metric: string, i: number) => {
+      entry[metric] = parseFloat(row.metricValues[i].value)
+    })
+    return entry
+  })
+
+  return { rows, rowCount: raw.rowCount || rows.length }
+}