@gscdump/nuxt 0.19.0

package/app/composables/useGscTableState.ts

@@ -0,0 +1,119 @@
+// Reactive table state — search, pagination, sort, filter — with optional
+// URL sync. One source of truth across a page so deep-links and
+// back/forward navigation restore exactly what the user was looking at.
+
+export interface GscSortState {
+  column: string
+  direction: 'asc' | 'desc'
+}
+
+export interface UseGscTableStateOptions<TFilter = Record<string, string>> {
+  /** Sync state into the URL query string. Default `true`. */
+  syncUrl?: boolean
+  /** Prefix for query keys (avoids collisions when multiple tables share a page). */
+  prefix?: string
+  defaultPage?: number
+  defaultPageSize?: number
+  defaultQ?: string
+  defaultSort?: GscSortState | null
+  defaultFilter?: TFilter
+}
+
+export interface UseGscTableStateReturn<TFilter = Record<string, string>> {
+  q: Ref<string>
+  page: Ref<number>
+  pageSize: Ref<number>
+  sort: Ref<GscSortState | null>
+  filter: Ref<TFilter>
+  reset: () => void
+  /** Toggle a column's sort: desc → asc → off. */
+  toggleSort: (column: string) => void
+}
+
+export function useGscTableState<TFilter extends Record<string, any> = Record<string, string>>(
+  opts: UseGscTableStateOptions<TFilter> = {},
+): UseGscTableStateReturn<TFilter> {
+  const syncUrl = opts.syncUrl ?? true
+  const prefix = opts.prefix ?? ''
+  const k = (name: string): string => (prefix ? `${prefix}_${name}` : name)
+
+  const defaultPage = opts.defaultPage ?? 1
+  const defaultPageSize = opts.defaultPageSize ?? 25
+  const defaultQ = opts.defaultQ ?? ''
+  const defaultSort = opts.defaultSort ?? null
+  const defaultFilter = (opts.defaultFilter ?? {}) as TFilter
+
+  const route = syncUrl ? useRoute() : null
+  const router = syncUrl ? useRouter() : null
+
+  function readQuery<T>(key: string, fallback: T, parse: (raw: string) => T): T {
+    if (!route)
+      return fallback
+    const raw = route.query[k(key)]
+    if (raw == null)
+      return fallback
+    return parse(Array.isArray(raw) ? (raw[0] ?? '') : String(raw))
+  }
+
+  function writeQuery(key: string, value: string | null): void {
+    if (!route || !router)
+      return
+    const query = { ...route.query }
+    const fullKey = k(key)
+    if (value == null || value === '')
+      delete query[fullKey]
+    else
+      query[fullKey] = value
+    void router.replace({ query })
+  }
+
+  const q = ref(readQuery('q', defaultQ, s => s))
+  const page = ref(readQuery('page', defaultPage, s => Number(s) || defaultPage))
+  const pageSize = ref(readQuery('pageSize', defaultPageSize, s => Number(s) || defaultPageSize))
+  const sort = ref<GscSortState | null>(readQuery('sort', defaultSort, parseSort))
+  const filter = ref(defaultFilter) as Ref<TFilter>
+
+  if (syncUrl) {
+    watch(q, v => writeQuery('q', v || null))
+    watch(page, v => writeQuery('page', v === defaultPage ? null : String(v)))
+    watch(pageSize, v => writeQuery('pageSize', v === defaultPageSize ? null : String(v)))
+    watch(sort, v => writeQuery('sort', serializeSort(v)))
+  }
+
+  // Reset page when q/filter changes (standard table UX).
+  watch([q, filter], () => {
+    page.value = defaultPage
+  }, { deep: true })
+
+  function reset(): void {
+    q.value = defaultQ
+    page.value = defaultPage
+    pageSize.value = defaultPageSize
+    sort.value = defaultSort
+    filter.value = defaultFilter
+  }
+
+  function toggleSort(column: string): void {
+    const cur = sort.value
+    if (!cur || cur.column !== column) {
+      sort.value = { column, direction: 'desc' }
+      return
+    }
+    sort.value = cur.direction === 'desc' ? { column, direction: 'asc' } : null
+  }
+
+  return { q, page, pageSize, sort, filter, reset, toggleSort }
+}
+
+function serializeSort(s: GscSortState | null): string | null {
+  return s ? `${s.column}:${s.direction}` : null
+}
+
+function parseSort(raw: string): GscSortState | null {
+  if (!raw)
+    return null
+  const [column, direction] = raw.split(':')
+  if (!column || (direction !== 'asc' && direction !== 'desc'))
+    return null
+  return { column, direction }
+}

package/app/plugins/analytics.ts

@@ -0,0 +1,57 @@
+// Layer-wide DI: analytics context, query dispatcher, fetch instance, and
+// analytics client. Each value is defined as a lazy getter on the NuxtApp so
+// non-GSC routes pay zero cost and host plugins (e.g. route-gated setGscAuth)
+// can run before any of these are materialized. Hosts override by reassigning
+// the same `$xxx` key from a later plugin (Nuxt's provide uses configurable
+// defineProperty, so the last writer wins).
+
+import type { AnalyticsClient, AnalyticsFetch } from '@gscdump/sdk'
+import type { $Fetch } from 'ofetch'
+import type { GscQueryDispatcher } from '../composables/_useGscQueryDispatcher'
+import type { GscAnalyticsContext } from '../composables/useGscAnalytics'
+import { createAnalyticsClient } from '@gscdump/sdk'
+import { createDefaultGscQueryDispatcher } from '../composables/_useGscQueryDispatcher'
+import { createGscAnalyticsContext } from '../composables/useGscAnalytics'
+import { useGscAnalyticsConfig } from '../composables/useGscAnalyticsConfig'
+import { resolveGscAuthHeaders } from '../composables/useGscAuth'
+import { createGscFetch } from '../utils/gsc-fetch'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  let _ctx: GscAnalyticsContext | undefined
+  let _dispatcher: GscQueryDispatcher | undefined
+  let _fetch: $Fetch | undefined
+  let _client: AnalyticsClient | undefined
+
+  function getFetch(): $Fetch {
+    if (!_fetch) {
+      const cfg = useGscAnalyticsConfig()
+      _fetch = createGscFetch(cfg.apiBase, cfg.toastErrors)
+    }
+    return _fetch
+  }
+
+  const lazy: Record<string, () => unknown> = {
+    $gscAnalytics: () => _ctx ??= createGscAnalyticsContext(),
+    $gscQueryDispatcher: () => _dispatcher ??= createDefaultGscQueryDispatcher(),
+    $gscFetch: () => getFetch(),
+    $gscAnalyticsClient: () => {
+      if (!_client) {
+        const cfg = useGscAnalyticsConfig()
+        _client = createAnalyticsClient({
+          apiBase: cfg.apiBase || '',
+          fetch: getFetch() as unknown as AnalyticsFetch,
+          headers: () => new Headers(resolveGscAuthHeaders()),
+        })
+      }
+      return _client
+    },
+  }
+
+  for (const [key, factory] of Object.entries(lazy)) {
+    Object.defineProperty(nuxtApp, key, {
+      get: factory,
+      configurable: true,
+      enumerable: true,
+    })
+  }
+})

package/app/utils/anonymization.ts

@@ -0,0 +1,24 @@
+// GSC anonymises queries on a per-day basis; summing query-grained rows
+// undercounts page impressions by this amount. Callers render a banner when
+// the trailing-28d weighted average crosses a threshold.
+//
+// Impression-weighted average matches what the user experiences when they
+// open the dashboard — daily % alone is noisy on low-traffic days.
+
+export interface DailyAnonInput {
+  impressions: number
+  anonymizedImpressionsPct: number
+}
+
+export function weightedAnonPct(days: readonly DailyAnonInput[] | null | undefined, window = 28): number | null {
+  if (!days?.length)
+    return null
+  const trailing = days.slice(-window)
+  let totalImpressions = 0
+  let weighted = 0
+  for (const d of trailing) {
+    totalImpressions += d.impressions
+    weighted += d.impressions * d.anonymizedImpressionsPct
+  }
+  return totalImpressions > 0 ? weighted / totalImpressions : null
+}

package/app/utils/country-names.ts

@@ -0,0 +1,56 @@
+export const COUNTRY_NAMES: Record<string, string> = {
+  US: 'United States',
+  GB: 'United Kingdom',
+  DE: 'Germany',
+  FR: 'France',
+  CA: 'Canada',
+  AU: 'Australia',
+  IN: 'India',
+  BR: 'Brazil',
+  JP: 'Japan',
+  IT: 'Italy',
+  ES: 'Spain',
+  NL: 'Netherlands',
+  SE: 'Sweden',
+  CH: 'Switzerland',
+  MX: 'Mexico',
+  KR: 'South Korea',
+  RU: 'Russia',
+  PL: 'Poland',
+  BE: 'Belgium',
+  AT: 'Austria',
+  NO: 'Norway',
+  DK: 'Denmark',
+  FI: 'Finland',
+  PT: 'Portugal',
+  IE: 'Ireland',
+  NZ: 'New Zealand',
+  SG: 'Singapore',
+  HK: 'Hong Kong',
+  TW: 'Taiwan',
+  IL: 'Israel',
+  ZA: 'South Africa',
+  AR: 'Argentina',
+  CL: 'Chile',
+  CO: 'Colombia',
+  TH: 'Thailand',
+  PH: 'Philippines',
+  MY: 'Malaysia',
+  ID: 'Indonesia',
+  VN: 'Vietnam',
+  TR: 'Turkey',
+  CZ: 'Czech Republic',
+  RO: 'Romania',
+  HU: 'Hungary',
+  GR: 'Greece',
+  UA: 'Ukraine',
+  EG: 'Egypt',
+  NG: 'Nigeria',
+  KE: 'Kenya',
+  PK: 'Pakistan',
+  BD: 'Bangladesh',
+  AE: 'United Arab Emirates',
+  SA: 'Saudi Arabia',
+}
+
+export const countryName = (code: string): string => COUNTRY_NAMES[code] || code

package/app/utils/gsc-constants.ts

@@ -0,0 +1,10 @@
+// Constants shared across GSC-shaped components. Kept as layer exports so
+// consumers import from `#imports` like everything else.
+
+/**
+ * Google Search Console data is considered "unstable" for this many days from
+ * today (PST). Rows within the window may still shift as GSC finalizes clicks/
+ * impressions; charts render those points under a dimmed / striped overlay so
+ * users don't misread last-day dips as trends.
+ */
+export const GSC_STABLE_LATENCY_DAYS = 3

package/app/utils/gsc-error.ts

@@ -0,0 +1,58 @@
+// Error classification shared by the layer's fetch wrappers and query hooks.
+// Returns a structured status the caller maps to UI (toast, banner, retry, …).
+
+export type GscErrorStatus
+  = | 'auth-missing'
+    | 'rate-limited'
+    | 'network'
+    | 'error'
+
+export interface GscClassifiedError {
+  status: GscErrorStatus
+  /** HTTP status code if the error came from a response, otherwise undefined. */
+  code?: number
+  /** Best-effort human message: server-supplied `message`, then `data.message`, then the error's own message. */
+  message?: string
+  /** Seconds the server suggested waiting (429 with `retryAfter` payload). */
+  retryAfter?: number
+}
+
+export function classifyGscError(e: unknown): GscClassifiedError {
+  const code = (e as { statusCode?: number, status?: number })?.statusCode
+    ?? (e as { status?: number })?.status
+  const message = extractMessage(e)
+
+  if (code === 401 || code === 403)
+    return { status: 'auth-missing', code, message }
+  if (code === 429) {
+    const retry = (e as { data?: { retryAfter?: number } })?.data?.retryAfter
+    return {
+      status: 'rate-limited',
+      code,
+      message,
+      retryAfter: typeof retry === 'number' ? retry : undefined,
+    }
+  }
+  // No code => didn't make it to the server (DNS, CORS, offline, abort).
+  if (code == null && !isAbort(e))
+    return { status: 'network', message }
+
+  return { status: 'error', code, message }
+}
+
+function extractMessage(e: unknown): string | undefined {
+  if (!e || typeof e !== 'object')
+    return undefined
+  const data = (e as { data?: unknown }).data
+  if (data && typeof data === 'object') {
+    const m = (data as { message?: unknown, error?: unknown }).message ?? (data as { error?: unknown }).error
+    if (typeof m === 'string')
+      return m
+  }
+  const m = (e as { message?: unknown }).message
+  return typeof m === 'string' ? m : undefined
+}
+
+function isAbort(e: unknown): boolean {
+  return (e as { name?: string })?.name === 'AbortError'
+}

package/app/utils/gsc-fetch.ts

@@ -0,0 +1,94 @@
+// Configured $fetch instance for the layer's `/api/__gsc/*` calls.
+//
+// When `runtimeConfig.public.analytics.apiBase` is set, requests are routed
+// to that origin (e.g. `https://gscdump.com`). Empty = same-origin, the
+// default for self-hosted deployments (gscdump.com itself).
+//
+// Auth: resolved via `useGscAuth` (host calls `setGscAuth` from a `'pre'`
+// plugin). `apiKey` populates `x-api-key`; `headers` carries any additional
+// auth headers. When no auth is wired, the layer falls back to cookies for
+// same-site / cookie-credentials deployments.
+//
+// Built once per NuxtApp by the layer plugin and provided as `$gscFetch`.
+// `useGscFetch()` is a thin reader; hosts override by providing their own
+// `$gscFetch` from a later plugin.
+
+import type { $Fetch } from 'ofetch'
+import { readGscAuth, resolveGscAuthHeaders } from '../composables/useGscAuth'
+import { classifyGscError } from './gsc-error'
+
+const TOAST_DEDUP_MS = 5000
+
+interface ToastDedup {
+  recent: Map<string, number>
+}
+
+function shouldEmitToast(dedup: ToastDedup, key: string): boolean {
+  const now = Date.now()
+  const last = dedup.recent.get(key) ?? 0
+  if (now - last < TOAST_DEDUP_MS)
+    return false
+  dedup.recent.set(key, now)
+  if (dedup.recent.size > 32) {
+    const oldest = [...dedup.recent.entries()].sort((a, b) => a[1] - b[1])[0]
+    if (oldest)
+      dedup.recent.delete(oldest[0])
+  }
+  return true
+}
+
+function defaultToastTitle(status: string): string {
+  switch (status) {
+    case 'auth-missing': return 'Sign in required'
+    case 'rate-limited': return 'Rate limit exceeded'
+    case 'network': return 'Network error'
+    default: return 'Request failed'
+  }
+}
+
+export function createGscFetch(cfgApiBase: string, toastErrors: boolean): $Fetch {
+  const dedup: ToastDedup = { recent: new Map() }
+  return $fetch.create({
+    onRequest: ({ options }) => {
+      const auth = readGscAuth()
+      const apiBase = cfgApiBase ?? ''
+      const authHeaders = resolveGscAuthHeaders(auth)
+
+      const merged = new Headers(options.headers as HeadersInit | undefined)
+      for (const [k, v] of Object.entries(authHeaders))
+        merged.set(k, v)
+      options.headers = merged
+
+      if (apiBase && typeof options.baseURL !== 'string')
+        options.baseURL = apiBase
+
+      const hasAuth = Object.keys(authHeaders).length > 0
+      if (hasAuth) {
+        if (!options.credentials)
+          options.credentials = 'omit'
+      }
+      else if (apiBase && !options.credentials) {
+        // No explicit auth — fall back to cookies for cross-origin sessions.
+        options.credentials = 'include'
+      }
+    },
+    onResponseError: (ctx) => {
+      if (!toastErrors || !import.meta.client)
+        return
+      const c = classifyGscError(ctx.error ?? ctx.response)
+      const key = `${c.status}:${c.code ?? '-'}:${c.message ?? ''}`
+      if (!shouldEmitToast(dedup, key))
+        return
+      const toast = useToast()
+      toast.add({
+        title: defaultToastTitle(c.status),
+        description: c.message,
+        color: c.status === 'rate-limited' ? 'warning' : 'error',
+      })
+    },
+  }) as unknown as $Fetch
+}
+
+export function useGscFetch(): $Fetch {
+  return useNuxtApp().$gscFetch as $Fetch
+}

package/app/utils/gsc-filters.ts

@@ -0,0 +1,32 @@
+// Re-exports the typed query operators from `gscdump/query` so layer
+// consumers can compose filters without an extra import line. Auto-imported
+// like the layer's other utils.
+//
+// Usage:
+//   const filter = and(
+//     between(date, range.start, range.end),
+//     eq(country, 'usa'),
+//   )
+//
+// Replaces nuxtseo's wire-format `dateFilter` / `andFilter` helpers — both
+// formats coerce to the same shape server-side, so the typed primitives
+// are strictly better.
+
+export {
+  and,
+  between,
+  contains,
+  eq,
+  gt,
+  gte,
+  inArray,
+  like,
+  lt,
+  lte,
+  ne,
+  not,
+  notRegex,
+  or,
+  regex,
+  topLevel,
+} from 'gscdump/query'

package/app/utils/gsc-rows.ts

@@ -0,0 +1,72 @@
+// Shape-canonicalising helpers for GSC row payloads.
+//
+// Free-tier rows (GSC API) ship `position`; engine rows ship `sum_position`.
+// Both formats coerce to the same denominator: `sum_position = position * impressions`,
+// so downstream `weightedPosition / impressions` math works without branching.
+//
+// Lifted from the per-page detail pages where the coalesce + totals reducer
+// was duplicated. The `+1` in `position` is GSC's 1-indexed convention
+// (position 1 == top result), applied once after weighting.
+
+export interface RawDailyRow {
+  date: string
+  clicks: number
+  impressions: number
+  sum_position?: number
+  position?: number
+}
+
+export interface CanonicalDailyRow {
+  date: string
+  clicks: number
+  impressions: number
+  sum_position: number
+}
+
+export interface GscRowTotals {
+  clicks: number
+  impressions: number
+  ctr: number
+  position: number
+}
+
+export interface GscDailySummary {
+  daily: CanonicalDailyRow[]
+  totals: GscRowTotals
+  chartData: Array<{ date: string, clicks: number, impressions: number }>
+}
+
+/** Fill `sum_position` from `position * impressions` when the row only carries `position`. */
+export function coerceRowMetrics<
+  T extends { impressions: number, sum_position?: number, position?: number },
+>(row: T): T & { sum_position: number } {
+  return {
+    ...row,
+    sum_position: row.sum_position ?? (row.position ?? 0) * row.impressions,
+  }
+}
+
+/** Sort daily rows by date asc, coerce `sum_position`, reduce totals, derive chartData. */
+export function summarizeDailyRows(raw: readonly RawDailyRow[]): GscDailySummary {
+  const daily: CanonicalDailyRow[] = raw
+    .map(coerceRowMetrics)
+    .map(r => ({ date: r.date, clicks: r.clicks, impressions: r.impressions, sum_position: r.sum_position }))
+    .sort((a, b) => a.date.localeCompare(b.date))
+
+  let clicks = 0
+  let impressions = 0
+  let weightedPosition = 0
+  for (const d of daily) {
+    clicks += d.clicks
+    impressions += d.impressions
+    weightedPosition += d.sum_position
+  }
+  const totals: GscRowTotals = {
+    clicks,
+    impressions,
+    ctr: impressions > 0 ? clicks / impressions : 0,
+    position: impressions > 0 ? weightedPosition / impressions + 1 : 0,
+  }
+  const chartData = daily.map(d => ({ date: d.date, clicks: d.clicks, impressions: d.impressions }))
+  return { daily, totals, chartData }
+}

package/app/utils/position.ts

@@ -0,0 +1,7 @@
+// Rollup-row position helper. `sum_position` is GSC's average-position sum
+// across impressions; dividing back out (+1 because GSC is 1-indexed) gives
+// the impression-weighted average position. Returns 0 when there were no
+// impressions so the column renders blank rather than NaN.
+export function positionFor(r: { impressions: number, sum_position: number }): number {
+  return r.impressions > 0 ? r.sum_position / r.impressions + 1 : 0
+}

package/app/utils/setup-gsc-fetch-auth.ts

@@ -0,0 +1,62 @@
+// Plugin factory for consumer-mode auth wiring.
+//
+// In consumer mode, the host app authenticates the viewer against its own
+// origin and exchanges that for a gscdump.com api key. `setupGscFetchAuth`
+// collapses the boilerplate of "fetch credentials, call setGscAuth, dedupe
+// via inflight promise, enforce: 'pre'" into a single call. The returned
+// value is a plugin definition; consumers re-export it from a client plugin
+// file (`plugins/00.gscdump-auth.client.ts`).
+//
+// `enforce: 'pre'` + the returned promise make Nuxt block subsequent plugins
+// until headers land, which avoids the auth-header race where a query mounts
+// before credentials resolve.
+
+import { setGscAuth } from '../composables/useGscAuth'
+
+interface SetupGscFetchAuthOptions<TCreds extends Record<string, any> = { apiKey: string }> {
+  /** Host endpoint returning credentials. Called once per page load. */
+  credentialsEndpoint: string
+  /** Field on the response holding the api key. Default: `apiKey`. */
+  tokenField?: keyof TCreds & string
+  /** Header name to send to gscdump.com. Default: `x-api-key`. Set this only when the host uses a custom header name; the layer maps `apiKey` → `x-api-key` by default. */
+  headerName?: string
+  /**
+   * Optional hook fired after auth is set. Use for host-specific state
+   * preloading (e.g. user settings flags). Runs inside `nuxtApp.runWithContext`.
+   */
+  onReady?: (ctx: { credentials: TCreds }) => void | Promise<void>
+}
+
+export function setupGscFetchAuth<TCreds extends Record<string, any> = { apiKey: string }>(
+  options: SetupGscFetchAuthOptions<TCreds>,
+): ReturnType<typeof defineNuxtPlugin> {
+  const { credentialsEndpoint, tokenField = 'apiKey' as keyof TCreds & string, headerName = 'x-api-key', onReady } = options
+  let inflight: Promise<void> | null = null
+
+  return defineNuxtPlugin({
+    name: 'gscdump-analytics-auth',
+    enforce: 'pre',
+    async setup(nuxtApp) {
+      if (inflight)
+        return inflight
+      inflight = (async () => {
+        const credentials = await $fetch<TCreds>(credentialsEndpoint).catch(() => null)
+        const apiKey = credentials?.[tokenField] as string | undefined
+        if (!apiKey)
+          return
+        // Default header name = `x-api-key` is already handled by the layer
+        // when `apiKey` is set on auth state. A custom `headerName` is routed
+        // through the opaque `headers` bag.
+        setGscAuth({
+          apiKey: headerName === 'x-api-key' ? apiKey : null,
+          browserAnalyzerEnabled: false,
+          headers: headerName === 'x-api-key' ? undefined : { [headerName]: apiKey },
+        })
+        if (onReady) {
+          await nuxtApp.runWithContext(() => onReady({ credentials: credentials! }))
+        }
+      })()
+      return inflight
+    },
+  })
+}

package/module.ts

@@ -0,0 +1,81 @@
+// Nuxt module for @gscdump/nuxt.
+//
+// Responsibilities:
+//  - Merge the layer's public runtime-config defaults (apiBase, duckdbBundleBase)
+//    with env-var fallbacks. The layer is a portable client; hosts pick where
+//    `/api/__gsc/*` calls go via `GSCDUMP_ANALYTICS_API_BASE`.
+//  - Generate the `$gscAnalyzers` plugin from `options.analyzers` so hosts
+//    only declare their analyzer registry path in `nuxt.config.ts` — no
+//    plugin boilerplate.
+//
+// Auth-provider wiring is NOT a Nuxt module hook; the host wires its own
+// Nitro server handlers using primitives from @gscdump/cloudflare,
+// @gscdump/engine-sqlite, and @gscdump/analysis. Using a build-time hook
+// here would fire before the host's plugin has a chance to register.
+
+import type { GscAnalyticsRuntimeConfig } from './types'
+import process from 'node:process'
+import { addPluginTemplate, defineNuxtModule } from '@nuxt/kit'
+import { defu } from 'defu'
+
+export interface ModuleOptions {
+  /**
+   * Path to a TS/JS file exporting `ANALYZERS` (a `GscAnalyzerDefinition[]`).
+   * Accepts Nuxt aliases (`~/gscAnalyzers`) or absolute paths. When set, the
+   * module generates a plugin that provides `$gscAnalyzers` so hosts do not
+   * need to hand-roll their own plugin file.
+   */
+  analyzers?: string
+}
+
+declare module 'nuxt/schema' {
+  interface NuxtConfig { gscdumpAnalytics?: ModuleOptions }
+  interface NuxtOptions { gscdumpAnalytics: ModuleOptions }
+}
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: '@gscdump/nuxt',
+    configKey: 'gscdumpAnalytics',
+    compatibility: { nuxt: '>=4.0.0' },
+  },
+  setup(options, nuxt) {
+    const defaults: GscAnalyticsRuntimeConfig = {
+      apiBase: process.env.GSCDUMP_ANALYTICS_API_BASE ?? '',
+      duckdbBundleBase: process.env.GSCDUMP_DUCKDB_BUNDLE_BASE ?? '',
+      timezone: process.env.GSCDUMP_ANALYTICS_TIMEZONE ?? '',
+      toastErrors: process.env.GSCDUMP_ANALYTICS_TOAST_ERRORS === 'true',
+      defaultEngine: (process.env.GSCDUMP_ANALYTICS_DEFAULT_ENGINE as GscAnalyticsRuntimeConfig['defaultEngine'] | undefined) ?? 'auto',
+    }
+    nuxt.options.runtimeConfig.public.analytics = defu(
+      nuxt.options.runtimeConfig.public.analytics as Partial<GscAnalyticsRuntimeConfig> | undefined,
+      defaults,
+    )
+
+    if (options.analyzers) {
+      // Generated plugin imports the host's analyzer file and provides
+      // `$gscAnalyzers`. Runs after the layer's `analytics.ts` plugin (which
+      // doesn't provide `$gscAnalyzers`), so consumers see this array.
+      addPluginTemplate({
+        filename: 'gscdump-analyzers.plugin.mjs',
+        getContents: () => [
+          `import { defineNuxtPlugin } from '#app'`,
+          `import { ANALYZERS } from ${JSON.stringify(options.analyzers)}`,
+          `export default defineNuxtPlugin(() => ({ provide: { gscAnalyzers: ANALYZERS } }))`,
+          ``,
+        ].join('\n'),
+      })
+    }
+
+    // Strip underscore-prefixed composables from the consumer auto-import surface.
+    // `app/composables/_useFoo.ts` stays usable inside the layer via explicit
+    // relative imports, but never appears as a global auto-import in host apps.
+    nuxt.hook('imports:extend', (imports) => {
+      for (let i = imports.length - 1; i >= 0; i--) {
+        const from = imports[i]?.from ?? ''
+        if (/\/_use[A-Z]/.test(from))
+          imports.splice(i, 1)
+      }
+    })
+  },
+})