@gscdump/nuxt 0.22.1 → 1.5.1

package/app/composables/useGscPeriod.ts

@@ -1,243 +0,0 @@
-// 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

@@ -1,303 +0,0 @@
-// 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)
-}
-
-const DEFAULT_SEARCH_TYPE: NonNullable<AnalysisParams['searchType']> = 'web'
-
-function withDefaultSearchType(params: AnalysisParams): AnalysisParams {
-  return { ...params, searchType: params.searchType ?? DEFAULT_SEARCH_TYPE }
-}
-
-export function useGscQuery<T = AnalysisResult>(opts: UseGscQueryOptions<T>): UseGscQueryReturn<T> {
-  const querySearchType = computed(() => toValue(opts.params).searchType ?? DEFAULT_SEARCH_TYPE)
-  const queryRange = computed(() => {
-    const params = toValue(opts.params)
-    return typeof params.startDate === 'string' && typeof params.endDate === 'string'
-      ? { start: params.startDate, end: params.endDate }
-      : null
-  })
-  const analyzer = useGscAnalyzer(opts.site, querySearchType, queryRange)
-  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, withDefaultSearchType(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(withDefaultSearchType(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

@@ -1,14 +0,0 @@
-// Public re-export. The implementation lives in `_useGscQueryDispatcher.ts`;
-// the module's `imports:extend` hook strips `_use*` from host auto-imports so
-// consumers see the wrapper at `useGscQueryDispatcher` and the layer's own
-// composables import the internal file directly. Named re-exports because
-// Nuxt's auto-import scanner doesn't traverse `export *`.
-export {
-  type CreateDefaultDispatcherOpts,
-  createDefaultGscQueryDispatcher,
-  type GscEngineDecision,
-  type GscFallbackEvent,
-  type GscQueryDispatcher,
-  type PickEngineOpts,
-  useGscQueryDispatcher,
-} from './_useGscQueryDispatcher'

package/app/composables/useGscRequestIndexingInspect.ts

@@ -1,20 +0,0 @@
-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
-    })
-  }
-}

package/app/composables/useGscResource.ts

@@ -1,11 +0,0 @@
-// Public re-export. The implementation lives in `_useGscResource.ts`; the
-// module's `imports:extend` hook strips `_use*` from host auto-imports so
-// consumers see the wrapper at `useGscResource` and the layer's own
-// composables import the internal file directly. Named re-exports because
-// Nuxt's auto-import scanner doesn't traverse `export *`.
-export {
-  type GscResourceStatus,
-  useGscResource,
-  type UseGscResourceOptions,
-  type UseGscResourceReturn,
-} from './_useGscResource'