@gscdump/nuxt 0.19.0

package/app/composables/useGscPeriod.ts

@@ -0,0 +1,243 @@
+// Period + comparison primitives. Pure utilities (date math, growth calc)
+// plus the reactive `useGscPeriod()` composable that wires them into refs.
+//
+// Supports rolling presets (7d/28d/3m/6m/12m), calendar presets (this-week,
+// this-month, last-month, this-quarter, this-year), and custom ranges
+// (`custom:start:end` or `custom:start:end:prevStart:prevEnd`).
+//
+// Timezone via `runtimeConfig.public.analytics.timezone` (IANA name) or
+// the `timezone` option. Default: UTC.
+
+import { GSC_STABLE_LATENCY_DAYS } from '../utils/gsc-constants'
+
+export type RollingPeriod = '7d' | '28d' | '3m' | '6m' | '12m'
+export type CalendarPeriod = 'this-week' | 'this-month' | 'last-month' | 'this-quarter' | 'this-year'
+export type CustomPeriod = `custom:${string}:${string}` | `custom:${string}:${string}:${string}:${string}`
+export type Period = RollingPeriod | CalendarPeriod | CustomPeriod
+export type CompareMode = 'previous' | 'year' | 'none'
+
+export interface PeriodPreset {
+  value: RollingPeriod | CalendarPeriod
+  label: string
+  shortLabel: string
+  days: number
+}
+
+export const PERIOD_PRESETS = [
+  { value: '7d', label: 'Last 7 days', shortLabel: '7d', days: 7 },
+  { value: '28d', label: 'Last 28 days', shortLabel: '28d', days: 28 },
+  { value: '3m', label: 'Last 3 months', shortLabel: '3m', days: 90 },
+  { value: '6m', label: 'Last 6 months', shortLabel: '6m', days: 180 },
+  { value: '12m', label: 'Last 12 months', shortLabel: '12m', days: 365 },
+  { value: 'this-week', label: 'This week', shortLabel: 'WTD', days: 7 },
+  { value: 'this-month', label: 'This month', shortLabel: 'MTD', days: 31 },
+  { value: 'last-month', label: 'Last month', shortLabel: 'LM', days: 31 },
+  { value: 'this-quarter', label: 'This quarter', shortLabel: 'QTD', days: 92 },
+  { value: 'this-year', label: 'This year', shortLabel: 'YTD', days: 365 },
+] as const satisfies readonly PeriodPreset[]
+
+export const COMPARE_OPTIONS: readonly { value: CompareMode, label: string }[] = [
+  { value: 'previous', label: 'Previous period' },
+  { value: 'year', label: 'Year over year' },
+  { value: 'none', label: 'No comparison' },
+]
+
+export interface DateRange {
+  start: string
+  end: string
+  days: number
+  prevStart: string
+  prevEnd: string
+  yearStart: string
+  yearEnd: string
+}
+
+export function isCustomPeriod(p: Period | string): p is CustomPeriod {
+  return typeof p === 'string' && p.startsWith('custom:')
+}
+
+export function parseCustomPeriod(p: Period | string): { start: string, end: string, prevStart?: string, prevEnd?: string } | null {
+  if (!isCustomPeriod(p))
+    return null
+  const [, start, end, prevStart, prevEnd] = p.split(':')
+  if (!start || !end)
+    return null
+  return prevStart && prevEnd ? { start, end, prevStart, prevEnd } : { start, end }
+}
+
+export interface PeriodOptions {
+  /** Subtract GSC's stable-data latency from `end`. Default `true`. */
+  stableData?: boolean
+  /** IANA timezone (e.g. 'America/Los_Angeles'). Default UTC. */
+  timezone?: string
+}
+
+export function periodToDateRange(period: Period | string, opts: PeriodOptions = {}): DateRange {
+  const stableData = opts.stableData ?? true
+  const custom = parseCustomPeriod(period)
+  if (custom) {
+    const range = buildRange(parseIso(custom.start), parseIso(custom.end))
+    if (custom.prevStart && custom.prevEnd) {
+      return {
+        ...range,
+        prevStart: custom.prevStart,
+        prevEnd: custom.prevEnd,
+        yearStart: custom.prevStart,
+        yearEnd: custom.prevEnd,
+      }
+    }
+    return range
+  }
+
+  const today = todayInTz(opts.timezone)
+  const end = stableData ? addDays(today, -GSC_STABLE_LATENCY_DAYS) : addDays(today, -1)
+
+  switch (period) {
+    case '7d': return buildRange(addDays(end, -6), end)
+    case '28d': return buildRange(addDays(end, -27), end)
+    case '3m': return buildRange(addDays(end, -89), end)
+    case '6m': return buildRange(addDays(end, -179), end)
+    case '12m': return buildRange(addDays(end, -364), end)
+    case 'this-week': return buildRange(startOfWeek(end), end)
+    case 'this-month': return buildRange(startOfMonth(end), end)
+    case 'last-month': {
+      const prev = addDays(startOfMonth(end), -1)
+      return buildRange(startOfMonth(prev), endOfMonth(prev))
+    }
+    case 'this-quarter': return buildRange(startOfQuarter(end), end)
+    case 'this-year': return buildRange(startOfYear(end), end)
+    default: return buildRange(addDays(end, -27), end)
+  }
+}
+
+export function periodToDays(period: Period | string, opts?: PeriodOptions): number {
+  return periodToDateRange(period, opts).days
+}
+
+export function compareRange(range: DateRange, mode: CompareMode): { start: string, end: string } | null {
+  if (mode === 'none')
+    return null
+  if (mode === 'year')
+    return { start: range.yearStart, end: range.yearEnd }
+  return { start: range.prevStart, end: range.prevEnd }
+}
+
+export function getPeriodLabel(period: Period | string): string {
+  if (isCustomPeriod(period)) {
+    const c = parseCustomPeriod(period)
+    return c ? `${c.start} → ${c.end}` : 'Custom'
+  }
+  return PERIOD_PRESETS.find(p => p.value === period)?.label ?? String(period)
+}
+
+/**
+ * Relative growth as a fraction (0.12 = +12%). `null` if prev is zero or
+ * either side missing — caller renders "—" rather than divide-by-zero.
+ */
+export function computeGrowth(current: number, previous: number | null | undefined): number | null {
+  if (previous == null || previous === 0)
+    return null
+  return (current - previous) / previous
+}
+
+export interface UseGscPeriodOptions {
+  defaultPeriod?: Period
+  defaultCompareMode?: CompareMode
+  defaultStableData?: boolean
+  /** Override `runtimeConfig.public.analytics.timezone`. */
+  timezone?: string
+}
+
+export interface UseGscPeriodReturn {
+  period: Ref<Period>
+  compareMode: Ref<CompareMode>
+  stableData: Ref<boolean>
+  range: ComputedRef<DateRange>
+  comparison: ComputedRef<{ start: string, end: string } | null>
+  label: ComputedRef<string>
+  presets: typeof PERIOD_PRESETS
+  compareOptions: typeof COMPARE_OPTIONS
+}
+
+export function useGscPeriod(opts: UseGscPeriodOptions = {}): UseGscPeriodReturn {
+  const period = useState<Period>('gsc:period', () => opts.defaultPeriod ?? '28d')
+  const compareMode = useState<CompareMode>('gsc:compareMode', () => opts.defaultCompareMode ?? 'previous')
+  const stableData = useState<boolean>('gsc:stableData', () => opts.defaultStableData ?? true)
+
+  const cfg = useRuntimeConfig().public.analytics as { timezone?: string } | undefined
+  const timezone = opts.timezone ?? cfg?.timezone ?? undefined
+
+  const range = computed(() => periodToDateRange(period.value, { stableData: stableData.value, timezone }))
+  const comparison = computed(() => compareRange(range.value, compareMode.value))
+  const label = computed(() => getPeriodLabel(period.value))
+
+  return {
+    period,
+    compareMode,
+    stableData,
+    range,
+    comparison,
+    label,
+    presets: PERIOD_PRESETS,
+    compareOptions: COMPARE_OPTIONS,
+  }
+}
+
+function todayInTz(tz?: string): Date {
+  if (!tz) {
+    const now = new Date()
+    return new Date(`${now.toISOString().slice(0, 10)}T00:00:00Z`)
+  }
+  const fmt = new Intl.DateTimeFormat('en-CA', { timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit' })
+  return new Date(`${fmt.format(new Date())}T00:00:00Z`)
+}
+
+function parseIso(s: string): Date {
+  return new Date(`${s}T00:00:00Z`)
+}
+
+function addDays(d: Date, n: number): Date {
+  const out = new Date(d)
+  out.setUTCDate(out.getUTCDate() + n)
+  return out
+}
+
+function iso(d: Date): string {
+  return d.toISOString().slice(0, 10)
+}
+
+function startOfWeek(d: Date): Date {
+  const day = d.getUTCDay()
+  return addDays(d, day === 0 ? -6 : 1 - day)
+}
+
+function startOfMonth(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1))
+}
+
+function endOfMonth(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0))
+}
+
+function startOfQuarter(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), Math.floor(d.getUTCMonth() / 3) * 3, 1))
+}
+
+function startOfYear(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), 0, 1))
+}
+
+function buildRange(start: Date, end: Date): DateRange {
+  const days = Math.round((end.getTime() - start.getTime()) / 86400000) + 1
+  const prevEnd = addDays(start, -1)
+  const prevStart = addDays(prevEnd, -(days - 1))
+  return {
+    start: iso(start),
+    end: iso(end),
+    days,
+    prevStart: iso(prevStart),
+    prevEnd: iso(prevEnd),
+    yearStart: iso(addDays(start, -365)),
+    yearEnd: iso(addDays(end, -365)),
+  }
+}

package/app/composables/useGscQuery.ts

@@ -0,0 +1,290 @@
+// Unified analytics query hook. Dispatches browser DuckDB-WASM vs server
+// fallback, abort-safe, with typed status enum and opt-in backfill-on-demand.
+//
+// `site` is a parameter (not global state) so multi-site pages can issue
+// independent queries. `serverFallback` is optional — the default POSTs
+// AnalysisParams to `/api/__gsc/sites/[siteId]/analyze`. Override if your server
+// uses a different contract.
+
+import type { AnalysisParams, AnalysisResult } from '@gscdump/analysis'
+import type { ComputedRef, Ref, WatchSource } from '@vue/runtime-core'
+import { classifyGscError } from '../utils/gsc-error'
+import { useGscBackfill } from './_useGscBackfill'
+import { useGscQueryDispatcher } from './_useGscQueryDispatcher'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+import { useGscAnalyzer } from './useGscAnalyzer'
+import { _useGscAuthInternal } from './useGscAuth'
+
+export type GscQueryEngine = 'auto' | 'browser' | 'server'
+
+export type GscQueryStatus
+  = | 'idle'
+    | 'pending'
+    | 'success'
+    | 'empty'
+    | 'error'
+    | 'auth-missing'
+    | 'rate-limited'
+    | 'network'
+
+/**
+ * Why a given query ended up on `browser` or `server`. Surfaced for
+ * dev tooling so 0% R2 utilisation can be diagnosed without guessing
+ * (e.g. opt-in off vs. site not eligible vs. attach failure).
+ */
+export type GscQueryDecisionReason
+  = | 'idle'
+    | 'ssr'
+    | 'disabled'
+    | 'forced:server'
+    | 'forced:browser'
+    | 'optin:off'
+    | 'auto:browser'
+    | 'auto:fallback'
+
+export interface GscQueryDecision {
+  mode: 'browser' | 'server' | null
+  reason: GscQueryDecisionReason
+  /** Free-text detail for `auto:fallback` (the underlying error message). */
+  detail?: string
+}
+
+export interface GscQueryMeta {
+  raw: Record<string, unknown> | null
+  backfillRequired?: { startDate: string, endDate: string }
+  retryAfter?: number
+}
+
+export type GscBackfillRunner = ReturnType<typeof useGscBackfill>
+
+export interface UseGscQueryOptions<T> {
+  /** Site id (reactive). Required — queries don't dispatch without a site. */
+  site: MaybeRefOrGetter<string | null | undefined>
+  /** Reactive analysis params (discriminated union by `.type`). */
+  params: MaybeRefOrGetter<AnalysisParams>
+  /**
+   * Transform raw `AnalysisResult` from the browser path into the consumer type.
+   * Omit to pass through as-is (return type becomes `AnalysisResult`).
+   */
+  reshape?: (raw: AnalysisResult) => T
+  /**
+   * Server fallback override. Defaults to POSTing the params to
+   * `/api/__gsc/sites/[siteId]/analyze` and returning the response body.
+   */
+  serverFallback?: (siteId: string, params: AnalysisParams) => Promise<T>
+  /**
+   * Force a specific engine. Default `'auto'`. Accepts a getter so callers
+   * can swing engine reactively (e.g. flip to `'server'` when the requested
+   * range overlaps a known coverage gap). Re-read on every `runQuery` and
+   * also included in the watcher graph so changes trigger a refetch.
+   */
+  engine?: MaybeRefOrGetter<GscQueryEngine>
+  /** Extra reactive sources that should trigger refetch. */
+  watchSources?: WatchSource[]
+  /** Extract meta from the consumer payload. Defaults to `(out as any).meta`. */
+  extractMeta?: (out: T) => Record<string, unknown> | null | undefined
+  /**
+   * Backfill handling. `false` (default) = off. `true` = spin up a dedicated
+   * `useGscBackfill()`. Pass an existing runner to share across queries.
+   */
+  backfill?: boolean | GscBackfillRunner
+  /** Gate the query — when `false` it stays idle. */
+  enabled?: MaybeRefOrGetter<boolean>
+}
+
+export interface UseGscQueryReturn<T> {
+  data: Ref<T | null>
+  status: Ref<GscQueryStatus>
+  pending: ComputedRef<boolean>
+  error: Ref<Error | null>
+  engine: Ref<'browser' | 'server' | null>
+  elapsedMs: Ref<number | null>
+  fallbackReason: Ref<string | null>
+  /** Why this query ran where it ran. Updated on every dispatch. */
+  lastDecision: Ref<GscQueryDecision>
+  meta: Ref<GscQueryMeta>
+  backfill: GscBackfillRunner | null
+  refresh: () => Promise<void>
+}
+
+function classifyError(e: unknown): { status: GscQueryStatus, retryAfter?: number } {
+  const c = classifyGscError(e)
+  return { status: c.status as GscQueryStatus, retryAfter: c.retryAfter }
+}
+
+function isEmpty(v: unknown): boolean {
+  if (v == null)
+    return true
+  if (Array.isArray(v))
+    return v.length === 0
+  if (typeof v === 'object') {
+    const rec = v as Record<string, unknown>
+    for (const key of ['rows', 'results', 'daily', 'items']) {
+      const arr = rec[key]
+      if (Array.isArray(arr))
+        return arr.length === 0
+    }
+  }
+  return false
+}
+
+async function defaultServerFallback<T>(siteId: string, params: AnalysisParams): Promise<T> {
+  return await useGscAnalyticsClient().analyze<T>(siteId, params)
+}
+
+export function useGscQuery<T = AnalysisResult>(opts: UseGscQueryOptions<T>): UseGscQueryReturn<T> {
+  const analyzer = useGscAnalyzer(opts.site)
+  const dispatcher = useGscQueryDispatcher()
+
+  const data = shallowRef<T | null>(null)
+  const status = ref<GscQueryStatus>('idle')
+  const error = ref<Error | null>(null)
+  const engine = ref<'browser' | 'server' | null>(null)
+  const elapsedMs = ref<number | null>(null)
+  const fallbackReason = ref<string | null>(null)
+  const lastDecision = ref<GscQueryDecision>({ mode: null, reason: 'idle' })
+  const meta = ref<GscQueryMeta>({ raw: null })
+  const pending = computed(() => status.value === 'pending')
+
+  function extractMeta(out: T): Record<string, unknown> | null {
+    if (opts.extractMeta) {
+      const m = opts.extractMeta(out)
+      return m ?? null
+    }
+    const m = (out as unknown as { meta?: Record<string, unknown> })?.meta
+    return m ?? null
+  }
+
+  function captureMeta(out: T): void {
+    const raw = extractMeta(out)
+    const backfillRequired = (raw as { backfillRequired?: { startDate: string, endDate: string } } | null)?.backfillRequired
+    meta.value = backfillRequired ? { raw, backfillRequired } : { raw }
+  }
+
+  async function runServer(siteId: string): Promise<void> {
+    const t0 = performance.now()
+    const fn = opts.serverFallback ?? defaultServerFallback
+    const out = await fn(siteId, toValue(opts.params)) as T
+    data.value = out
+    engine.value = 'server'
+    elapsedMs.value = performance.now() - t0
+    captureMeta(out)
+  }
+
+  async function runBrowser(signal: AbortSignal): Promise<void> {
+    const out = await analyzer.analyze(toValue(opts.params), { signal })
+    signal.throwIfAborted()
+    const shaped = opts.reshape ? opts.reshape(out) : (out as unknown as T)
+    data.value = shaped
+    engine.value = 'browser'
+    elapsedMs.value = (out as unknown as { queryMs?: number }).queryMs ?? null
+    captureMeta(shaped)
+  }
+
+  let activeController: AbortController | null = null
+
+  async function runQuery(): Promise<void> {
+    if (!import.meta.client) {
+      status.value = 'idle'
+      lastDecision.value = { mode: null, reason: 'ssr' }
+      return
+    }
+    if (opts.enabled && !toValue(opts.enabled)) {
+      status.value = 'idle'
+      data.value = null
+      engine.value = null
+      elapsedMs.value = null
+      lastDecision.value = { mode: null, reason: 'disabled' }
+      return
+    }
+    const siteId = toValue(opts.site)
+    if (!siteId) {
+      status.value = 'idle'
+      lastDecision.value = { mode: null, reason: 'idle' }
+      return
+    }
+    activeController?.abort()
+    const controller = new AbortController()
+    activeController = controller
+    status.value = 'pending'
+    error.value = null
+    fallbackReason.value = null
+
+    const decision = dispatcher.pickEngine(_useGscAuthInternal().value, { perCall: toValue(opts.engine) })
+    lastDecision.value = decision
+
+    try {
+      if (decision.mode === 'server') {
+        await runServer(siteId)
+      }
+      else {
+        // Browser-mode: when the caller asked for `auto` we fall back to server
+        // on failure; explicit `browser` propagates the error.
+        await runBrowser(controller.signal).catch(async (e) => {
+          if (e?.name === 'AbortError')
+            throw e
+          if (decision.requested !== 'auto')
+            throw e
+          fallbackReason.value = e instanceof Error ? e.message : String(e)
+          console.warn('[useGscQuery] browser failed, falling back to server:', fallbackReason.value)
+          dispatcher.reportFallback({
+            reason: fallbackReason.value,
+            at: Date.now(),
+            url: typeof location !== 'undefined' ? location.pathname : '',
+          })
+          lastDecision.value = { mode: 'server', reason: 'auto:fallback', detail: fallbackReason.value }
+          await runServer(siteId)
+        })
+      }
+      if (!controller.signal.aborted)
+        status.value = isEmpty(data.value) ? 'empty' : 'success'
+    }
+    catch (e) {
+      if ((e as { name?: string })?.name === 'AbortError')
+        return
+      error.value = e instanceof Error ? e : new Error(String(e))
+      const classified = classifyError(e)
+      status.value = classified.status
+      if (classified.retryAfter != null)
+        meta.value = { ...meta.value, retryAfter: classified.retryAfter }
+    }
+    finally {
+      if (activeController === controller)
+        activeController = null
+    }
+  }
+
+  if (import.meta.client) {
+    onScopeDispose(() => {
+      activeController?.abort()
+      activeController = null
+    })
+  }
+
+  const sources: WatchSource[] = [
+    () => toValue(opts.site),
+    () => toValue(opts.params),
+    ...(opts.watchSources ?? []),
+  ]
+  if (opts.enabled)
+    sources.push(() => toValue(opts.enabled))
+  if (opts.engine !== undefined)
+    sources.push(() => toValue(opts.engine))
+  watch(sources, runQuery, { deep: true, immediate: true })
+
+  let backfill: GscBackfillRunner | null = null
+  const b = opts.backfill ?? false
+  if (b !== false) {
+    backfill = b === true ? useGscBackfill() : b
+    watch(() => meta.value.backfillRequired, (req: { startDate: string, endDate: string } | undefined) => {
+      if (!req)
+        return
+      const siteId = toValue(opts.site)
+      if (!siteId)
+        return
+      backfill!.maybeTrigger({ backfillRequired: req }, siteId, runQuery)
+    }, { immediate: true })
+  }
+
+  return { data, status, pending, error, engine, elapsedMs, fallbackReason, lastDecision, meta, backfill, refresh: runQuery }
+}

package/app/composables/useGscQueryDispatcher.ts

@@ -0,0 +1,122 @@
+// Per-query dispatch policy + fallback telemetry behind one swappable seam.
+//
+// `useGscQuery` owns *intent* (the caller's `engine: 'auto' | 'browser' | 'server'`);
+// the dispatcher owns *policy* (how `auto` resolves against current auth, what
+// to do with auto-fallback events). Default impl is no-op telemetry — hosts
+// that want fallback beacons override the provide with a configured factory.
+
+import type { _useGscAuthInternal } from './useGscAuth'
+import type { GscQueryDecisionReason, GscQueryEngine } from './useGscQuery'
+import { useGscEngine } from './useGscEngine'
+
+type InternalAuthState = ReturnType<typeof _useGscAuthInternal>['value']
+
+export interface GscEngineDecision {
+  mode: 'browser' | 'server'
+  reason: GscQueryDecisionReason
+  /** The resolved intent before the auth/optin mapping — useful for callers that branch on "did the user ask for auto?". */
+  requested: GscQueryEngine
+  detail?: string
+}
+
+export interface GscFallbackEvent {
+  reason: string
+  at: number
+  url: string
+}
+
+export interface PickEngineOpts {
+  /** Per-call override. Wins over `useGscEngine()` + `runtimeConfig.public.analytics.defaultEngine`. */
+  perCall?: GscQueryEngine
+}
+
+export interface GscQueryDispatcher {
+  /**
+   * Resolve the active engine into a concrete mode + reason. Consults the
+   * resolution chain: `opts.perCall` → `useGscEngine()` → runtimeConfig →
+   * `'auto'`. Then maps `auto` against `auth.browserAnalyzerEnabled`.
+   */
+  pickEngine: (auth: InternalAuthState, opts?: PickEngineOpts) => GscEngineDecision
+  /** Called once per auto-fallback. Default impl is a no-op. */
+  reportFallback: (event: GscFallbackEvent) => void
+}
+
+export interface CreateDefaultDispatcherOpts {
+  /** When set, fallbacks beacon to this URL with batched payloads. */
+  telemetryEndpoint?: string
+}
+
+const FLUSH_DELAY_MS = 5000
+
+function createReporter(endpoint: string): (event: GscFallbackEvent) => void {
+  const buffer: GscFallbackEvent[] = []
+  let flushScheduled = false
+
+  function flush(): void {
+    flushScheduled = false
+    if (buffer.length === 0)
+      return
+    const events = buffer.splice(0)
+    const body = JSON.stringify({ events })
+    if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+      navigator.sendBeacon(endpoint, new Blob([body], { type: 'application/json' }))
+      return
+    }
+    fetch(endpoint, { method: 'POST', body, headers: { 'content-type': 'application/json' } }).catch(() => {})
+  }
+
+  function scheduleFlush(): void {
+    if (flushScheduled || typeof window === 'undefined')
+      return
+    flushScheduled = true
+    setTimeout(flush, FLUSH_DELAY_MS)
+    if (typeof document !== 'undefined') {
+      const handler = (): void => {
+        if (document.visibilityState === 'hidden')
+          flush()
+      }
+      document.addEventListener('visibilitychange', handler, { once: true })
+    }
+  }
+
+  return (event: GscFallbackEvent): void => {
+    buffer.push(event)
+    scheduleFlush()
+  }
+}
+
+export function createDefaultGscQueryDispatcher(
+  opts: CreateDefaultDispatcherOpts = {},
+): GscQueryDispatcher {
+  const reportFallback = opts.telemetryEndpoint
+    ? createReporter(opts.telemetryEndpoint)
+    : (): void => {}
+
+  return {
+    pickEngine(auth, opts = {}): GscEngineDecision {
+      const requested = opts.perCall ?? resolveDefaultEngine()
+      if (requested === 'server')
+        return { mode: 'server', reason: 'forced:server', requested }
+      if (requested === 'browser')
+        return { mode: 'browser', reason: 'forced:browser', requested }
+      // 'auto': when the host has wired setGscAuth, derive from the per-user
+      // browserAnalyzerEnabled flag. When unwired, preserve legacy 'auto' = browser.
+      if (auth._initialized && !auth.browserAnalyzerEnabled)
+        return { mode: 'server', reason: 'optin:off', requested }
+      return { mode: 'browser', reason: 'auto:browser', requested }
+    },
+    reportFallback,
+  }
+}
+
+function resolveDefaultEngine(): GscQueryEngine {
+  const override = useGscEngine().value
+  if (override)
+    return override
+  const cfg = useRuntimeConfig().public.analytics as { defaultEngine?: GscQueryEngine } | undefined
+  return cfg?.defaultEngine ?? 'auto'
+}
+
+export function useGscQueryDispatcher(): GscQueryDispatcher {
+  return useNuxtApp().$gscQueryDispatcher
+}

package/app/composables/useGscRequestIndexingInspect.ts

@@ -0,0 +1,20 @@
+import type { IndexingInspectRateLimited, IndexingInspectResponse } from '@gscdump/contracts'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+
+export function useGscRequestIndexingInspect(): (
+  siteId: string,
+  urls: string[],
+) => Promise<IndexingInspectResponse | IndexingInspectRateLimited> {
+  const client = useGscAnalyticsClient()
+  return async (siteId, urls) => {
+    return client.requestIndexingInspect(siteId, { urls }).catch((err: unknown) => {
+      const status = (err as { status?: number, statusCode?: number, response?: { status?: number } })?.status
+        ?? (err as { statusCode?: number })?.statusCode
+        ?? (err as { response?: { status?: number } })?.response?.status
+      const data = (err as { data?: unknown })?.data as IndexingInspectRateLimited | undefined
+      if (status === 429 && data && data.error === 'rate_limited')
+        return data
+      throw err
+    })
+  }
+}