@gscdump/nuxt 0.22.4 → 1.5.1

package/app/composables/useGscAnalyzerBatch.ts

@@ -1,106 +0,0 @@
-// Run N analyzers in parallel against a single analyzer runner, with per-id
-// status tracking, optional concurrency cap, and stale-token discard so
-// late-completing tasks from a superseded `run()` don't overwrite fresher state.
-//
-// Caller owns: result shaping (summarize, scoring), the trigger watcher,
-// and which ids to run.
-
-import type { MaybeRefOrGetter, Ref } from '@vue/runtime-core'
-
-export type GscAnalyzerBatchStatus = 'idle' | 'pending' | 'running' | 'done' | 'error' | 'skipped'
-
-export interface GscAnalyzerBatchEntry<TResult> {
-  status: GscAnalyzerBatchStatus
-  result: TResult | null
-  error: Error | null
-}
-
-export interface GscAnalyzerBatchRunner {
-  analyze: (params: { type: string, startDate?: string, endDate?: string }) => Promise<unknown>
-}
-
-export interface UseGscAnalyzerBatchOptions {
-  /** Cap parallel analyzer runs. DuckDB-WASM is single-threaded; high parallelism just serializes behind one connection. Default 2. */
-  concurrency?: number
-  /** Drop ids before running (e.g. analyzers the current source can't serve). Returning `false` marks them `skipped`. */
-  filter?: (id: string) => boolean
-}
-
-export interface UseGscAnalyzerBatchReturn<TResult> {
-  states: Ref<Record<string, GscAnalyzerBatchEntry<TResult>>>
-  running: Ref<boolean>
-  run: () => Promise<void>
-}
-
-export function useGscAnalyzerBatch<TResult = unknown>(
-  runner: GscAnalyzerBatchRunner,
-  ids: MaybeRefOrGetter<readonly string[]>,
-  dateRange: MaybeRefOrGetter<{ start: string, end: string }>,
-  opts: UseGscAnalyzerBatchOptions = {},
-): UseGscAnalyzerBatchReturn<TResult> {
-  const states = ref<Record<string, GscAnalyzerBatchEntry<TResult>>>({}) as Ref<Record<string, GscAnalyzerBatchEntry<TResult>>>
-  const running = ref(false)
-  let token = 0
-
-  function reset(currentIds: readonly string[]): void {
-    const next: Record<string, GscAnalyzerBatchEntry<TResult>> = {}
-    for (const id of currentIds)
-      next[id] = { status: 'pending', result: null, error: null }
-    states.value = next
-  }
-
-  async function run(): Promise<void> {
-    const myToken = ++token
-    const currentIds = toValue(ids)
-    const range = toValue(dateRange)
-    running.value = true
-    reset(currentIds)
-
-    const filter = opts.filter
-    const concurrency = Math.max(1, opts.concurrency ?? 2)
-
-    const queue: string[] = []
-    for (const id of currentIds) {
-      if (filter && !filter(id))
-        states.value = { ...states.value, [id]: { status: 'skipped', result: null, error: null } }
-      else
-        queue.push(id)
-    }
-
-    async function runOne(id: string): Promise<void> {
-      if (token !== myToken)
-        return
-      states.value = { ...states.value, [id]: { status: 'running', result: null, error: null } }
-      try {
-        const result = await runner.analyze({ type: id, startDate: range.start, endDate: range.end })
-        if (token !== myToken)
-          return
-        states.value = { ...states.value, [id]: { status: 'done', result: result as TResult, error: null } }
-      }
-      catch (err) {
-        if (token !== myToken)
-          return
-        const error = err instanceof Error ? err : new Error(String(err))
-        states.value = { ...states.value, [id]: { status: 'error', result: null, error } }
-      }
-    }
-
-    const workers = Array.from({ length: concurrency }, async () => {
-      while (queue.length) {
-        if (token !== myToken)
-          return
-        const id = queue.shift()
-        if (!id)
-          break
-        await runOne(id)
-      }
-    })
-
-    await Promise.all(workers)
-
-    if (token === myToken)
-      running.value = false
-  }
-
-  return { states, running, run }
-}

package/app/composables/useGscAnalyzerDefs.ts

@@ -1,119 +0,0 @@
-// Registry of analyzer definitions. The layer owns the type shape and the
-// reader; hosts provide the array via a Nuxt plugin (`$gscAnalyzers`) or via
-// the module's `analyzers` option (which generates the plugin at build time).
-//
-// Callers:
-//   - `/analyze` page builds its tab list from `useGscAnalyzerDefs()` and
-//     renders each tab via `<GscAnalyzerPanel :def>` driven by `panel`.
-//   - `/insights` page filters via `useGscAnalyzerDefsWithCapability('insightCard')`.
-//   - `useActionPriority` filters via `useGscAnalyzerDefsWithCapability('actionPriority')`.
-//
-// Capability slots are typed; e.g. `actionPriority` only accepts the
-// `ActionSource` union from `@gscdump/analysis`, so misspelt or unknown
-// sources fail at typecheck instead of at runtime in the priority runner.
-
-import type { ActionSource } from '@gscdump/analysis'
-import type { AnalysisTool } from '@gscdump/engine/analysis-types'
-import type { Component } from '@vue/runtime-core'
-
-export type GscAnalyzerKind = 'analyzer' | 'semantic' | 'action'
-
-export type GscAnalyzerAccent = 'primary' | 'warning' | 'success' | 'error' | 'neutral'
-
-export interface GscAnalyzerInsightCard {
-  icon: string
-  accent: GscAnalyzerAccent
-  description: string
-  summarize: (res: { results: unknown[], meta: Record<string, unknown> }) => { headline: string, tagline: string }
-}
-
-export interface GscAnalyzerStatTile {
-  label: string
-  value: string | number
-  /**
-   * Optional CSS color string for the value (used by the few panels that
-   *  color-code direction, e.g. improved/worsened in change-points).
-   */
-  valueColor?: string
-}
-
-export interface GscAnalyzerPanelResult {
-  results: unknown[]
-  meta: Record<string, unknown>
-  queryMs?: number | null
-}
-
-export interface GscAnalyzerPanelSpec {
-  /**
-   * Body component. Receives `{ rows, meta, range }` as props. Lazy-import
-   *  via `defineAsyncComponent(() => import(...))` to preserve route-level
-   *  codesplitting — pages that don't render the analyzer never pay for its
-   *  chart code.
-   */
-  component: Component
-  /** Project a result to the header stat tiles. Empty array = no tiles. */
-  summarize?: (res: GscAnalyzerPanelResult) => GscAnalyzerStatTile[]
-  /** Italic footer caption explaining the underlying method. */
-  caption?: string
-  /**
-   * When true, the shell skips its loading/error/empty gating and renders
-   *  the body component immediately — the panel manages its own phase state
-   *  (pipeline panels: action priority, content gap).
-   */
-  ownsLifecycle?: boolean
-}
-
-export interface GscAnalyzerCapabilities {
-  /** Opt into the `/insights` curated grid by providing a card config. */
-  insightCard?: GscAnalyzerInsightCard
-  /** Opt into `useActionPriority`. The value is the typed `ActionSource` slug. */
-  actionPriority?: ActionSource
-  /**
-   * Opt into the unified `/analyze` panel renderer. Without this, the tab
-   *  falls back to the generic table renderer in `<GscAnalyzerPanel>`.
-   */
-  panel?: GscAnalyzerPanelSpec
-}
-
-export type GscAnalyzerCapability = keyof GscAnalyzerCapabilities
-
-export interface GscAnalyzerDefinition {
-  /** Stable analyzer id. Must match an `AnalysisTool` slug for built-in analyzers. */
-  id: AnalysisTool | (string & {})
-  label: string
-  kind: GscAnalyzerKind
-  /** Reads the per-query table; sums silently drop GSC-anonymized impressions. */
-  isQueryGrained?: boolean
-  /** Capability opt-ins. Each key gates a downstream consumer. */
-  capabilities?: GscAnalyzerCapabilities
-}
-
-export type GscAnalyzerDefinitionWithCapability<K extends GscAnalyzerCapability>
-  = GscAnalyzerDefinition & {
-    capabilities: { [P in K]: NonNullable<GscAnalyzerCapabilities[P]> }
-  }
-
-export function defineGscAnalyzer(def: GscAnalyzerDefinition): GscAnalyzerDefinition {
-  return def
-}
-
-export function useGscAnalyzerDefs(): GscAnalyzerDefinition[] {
-  return (useNuxtApp().$gscAnalyzers as GscAnalyzerDefinition[] | undefined) ?? []
-}
-
-export function useGscAnalyzerDef(id: string): GscAnalyzerDefinition | undefined {
-  return useGscAnalyzerDefs().find(a => a.id === id)
-}
-
-/**
- * Typed filter that narrows defs to those with `capability` opted in.
- * The returned defs have `capabilities[capability]` typed as non-nullable.
- */
-export function useGscAnalyzerDefsWithCapability<K extends GscAnalyzerCapability>(
-  capability: K,
-): GscAnalyzerDefinitionWithCapability<K>[] {
-  return useGscAnalyzerDefs().filter(
-    (d): d is GscAnalyzerDefinitionWithCapability<K> =>
-      d.capabilities?.[capability] != null,
-  )
-}

package/app/composables/useGscAuth.ts

@@ -1,115 +0,0 @@
-// Reactive auth primitive for the @gscdump/nuxt layer.
-//
-// `useState`-backed so the value is SSR-safe and shared across the page tree.
-// Hosts call `setGscAuth(getter)` from a `'pre'`-enforced plugin so downstream
-// `useGscFetch`, `useGscQuery`, and `useGscAnalyzer` reactively re-read auth
-// on every change (no plugin race).
-//
-// `apiKey` populates `x-api-key` for cross-origin deployments.
-// `headers` is an opaque bag for hosts that need additional/alternative
-// auth schemes (e.g. `Authorization: Bearer …`, CSRF). Merged after `apiKey`.
-// `browserAnalyzerEnabled` is the user-level opt-in for DuckDB-WASM.
-//
-// `apiBase` is *not* on this state — it's a build-time runtimeConfig value
-// (`runtimeConfig.public.analytics.apiBase`). Per-user dynamic apiBase would
-// reintroduce a plugin-order race where the SDK client gets a stale prefix.
-
-import type { Ref } from '@vue/runtime-core'
-
-export interface GscAuthState {
-  apiKey: string | null
-  browserAnalyzerEnabled: boolean
-  userId?: string | null
-  /**
-   * Extra request headers to attach to every `/api/__gsc/*` call and parquet
-   * fetch. Use for non-`x-api-key` auth schemes. `apiKey` (above) is the
-   * common case — set both when needed.
-   */
-  headers?: Record<string, string>
-}
-
-interface InternalAuthState extends GscAuthState {
-  /**
-   * True once the host has called `setGscAuth` at least once. Layer
-   * consumers (e.g. `useGscQuery` engine derivation) treat unconfigured
-   * state as "no host wiring" and fall back to legacy behavior, rather
-   * than honoring the default `browserAnalyzerEnabled: false`.
-   */
-  _initialized: boolean
-}
-
-const STATE_KEY = 'gsc:auth'
-
-const DEFAULT_AUTH: InternalAuthState = {
-  apiKey: null,
-  browserAnalyzerEnabled: false,
-  userId: null,
-  headers: undefined,
-  _initialized: false,
-}
-
-function authState(): Ref<InternalAuthState> {
-  return useState<InternalAuthState>(STATE_KEY, () => ({ ...DEFAULT_AUTH }))
-}
-
-export function useGscAuth(): Readonly<Ref<GscAuthState>> {
-  return readonly(authState()) as unknown as Readonly<Ref<GscAuthState>>
-}
-
-/**
- * Layer-internal: returns the underlying state including `_initialized`.
- */
-export function _useGscAuthInternal(): Readonly<Ref<InternalAuthState>> {
-  return readonly(authState()) as Readonly<Ref<InternalAuthState>>
-}
-
-/**
- * Set the layer's auth state. Accepts a static value, a ref, or a getter.
- * Getter form is reactive — re-runs whenever its source updates.
- */
-export function setGscAuth(
-  source: GscAuthState | Ref<GscAuthState> | (() => GscAuthState),
-): void {
-  const state = authState()
-  const apply = (v: GscAuthState): void => {
-    state.value = { ...v, _initialized: true }
-  }
-  if (typeof source === 'function') {
-    watchEffect(() => apply((source as () => GscAuthState)()))
-    return
-  }
-  if (isRef(source)) {
-    watch(source, v => apply(v), { immediate: true, deep: true })
-    return
-  }
-  apply(source)
-}
-
-/**
- * Read auth state from any callsite — composable setup, fetch interceptor,
- * worker fetch callback. Resolves the ambient NuxtApp via async-local-storage
- * (server) or the global app (client) and reads the `useState` cell directly.
- * Returns the default sentinel when no NuxtApp context is available.
- */
-export function readGscAuth(): GscAuthState {
-  const nuxt = tryUseNuxtApp()
-  if (!nuxt)
-    return { ...DEFAULT_AUTH }
-  return authState().value
-}
-
-/**
- * Resolve the auth headers to attach to a request — `x-api-key` from `apiKey`
- * (if set) merged with the opaque `headers` bag. Returns `{}` when no auth
- * is wired, signalling callers to fall back to cookie credentials.
- */
-export function resolveGscAuthHeaders(auth: GscAuthState = readGscAuth()): Record<string, string> {
-  const out: Record<string, string> = {}
-  if (auth.apiKey)
-    out['x-api-key'] = auth.apiKey
-  if (auth.headers) {
-    for (const [k, v] of Object.entries(auth.headers))
-      out[k] = v
-  }
-  return out
-}

package/app/composables/useGscConsoleUrl.ts

@@ -1,45 +0,0 @@
-// Builds `search.google.com/search-console?...` deep-links for a site +
-// optional page / query. Portable across consumers — no layer state, pure
-// URL string concat.
-
-export interface GscConsoleUrlOpts {
-  /** The GSC property — either `sc-domain:example.com` or a URL-prefix. */
-  siteLabel: string
-  /** Optional page to open Performance drilldown for. */
-  page?: string
-  /** Optional query filter. */
-  query?: string
-  /** Resource: `performance`, `url-inspection`, `sitemaps`, … */
-  resource?: 'performance' | 'url-inspection' | 'sitemaps' | 'index'
-}
-
-export function gscConsoleUrl(opts: GscConsoleUrlOpts): string {
-  const base = 'https://search.google.com/search-console'
-  const resource = opts.resource ?? 'performance'
-  const params = new URLSearchParams()
-  // Default `sc-domain:` prefix when caller passes a bare hostname.
-  const siteLabel = /^(?:https?:|sc-domain:)/.test(opts.siteLabel)
-    ? opts.siteLabel
-    : `sc-domain:${opts.siteLabel}`
-  params.set('resource_id', siteLabel)
-  if (resource === 'url-inspection') {
-    // Inspect tool expects the absolute URL under `id`, not Performance's
-    // `page=*<url>` wildcard filter.
-    if (opts.page)
-      params.set('id', opts.page)
-  }
-  else {
-    if (opts.page)
-      params.set('page', `*${opts.page}`)
-    if (opts.query)
-      params.set('query', `*${opts.query}`)
-  }
-  const path = resource === 'performance'
-    ? '/performance/search-analytics'
-    : resource === 'url-inspection'
-      ? '/inspect'
-      : resource === 'sitemaps'
-        ? '/sitemaps'
-        : '/index'
-  return `${base}${path}?${params.toString()}`
-}

package/app/composables/useGscCountries.ts

@@ -1,46 +0,0 @@
-// Fetches per-country search performance for a site over a date window.
-// Server dispatches tier-aware: free → GSC API live, pro → engine parquet.
-// The page sees a uniform row shape regardless of which backend served it.
-
-import type { CountriesResponse, CountryRow, GscApiRange } from '@gscdump/contracts'
-import type { ComputedRef, Ref } from '@vue/runtime-core'
-import type { GscResourceStatus } from './_useGscResource'
-import { gscQueries } from '../queries/gsc'
-import { useGscResource } from './_useGscResource'
-
-export interface UseGscCountriesReturn {
-  response: Readonly<Ref<CountriesResponse | null>>
-  rows: ComputedRef<CountryRow[]>
-  range: ComputedRef<GscApiRange | null>
-  source: ComputedRef<CountriesResponse['source'] | null>
-  loading: ComputedRef<boolean>
-  status: Readonly<Ref<GscResourceStatus>>
-  error: Readonly<Ref<Error | null>>
-  refresh: () => Promise<void>
-}
-
-export function useGscCountries(
-  siteId: MaybeRefOrGetter<string | null | undefined>,
-  range: MaybeRefOrGetter<{ start: string, end: string } | null | undefined>,
-): UseGscCountriesReturn {
-  const { data, status, loading, error, refresh } = useGscResource<[string, string, string], CountriesResponse>({
-    keys: [
-      siteId,
-      () => toValue(range)?.start,
-      () => toValue(range)?.end,
-    ] as const,
-    operation: (id, start, end) => gscQueries.countries(id, { start, end }),
-    isEmpty: r => r.rows.length === 0,
-  })
-
-  return {
-    response: data as Readonly<Ref<CountriesResponse | null>>,
-    rows: computed(() => data.value?.rows ?? []),
-    range: computed(() => data.value?.range ?? null),
-    source: computed(() => data.value?.source ?? null),
-    loading,
-    status,
-    error,
-    refresh,
-  }
-}

package/app/composables/useGscCurrentSite.ts

@@ -1,36 +0,0 @@
-import type { ComputedRef, InjectionKey } from 'vue'
-
-export interface GscCurrentSiteContext {
-  siteId: ComputedRef<string>
-  site: ReturnType<typeof useGscSite>
-}
-
-export const gscCurrentSiteKey: InjectionKey<GscCurrentSiteContext> = Symbol('gsc-current-site')
-
-function createGscCurrentSiteContext(siteId: MaybeRefOrGetter<string | null | undefined>): GscCurrentSiteContext {
-  const resolvedSiteId = computed(() => String(toValue(siteId) ?? ''))
-  return { siteId: resolvedSiteId, site: useGscSite(resolvedSiteId) }
-}
-
-/**
- * Provide the current-site context for a dashboard subtree. Hosts with a route
- * shape other than `/sites/[id]/*` should call this from their layout/page.
- */
-export function provideGscCurrentSite(siteId: MaybeRefOrGetter<string | null | undefined>): GscCurrentSiteContext {
-  const ctx = createGscCurrentSiteContext(siteId)
-  provide(gscCurrentSiteKey, ctx)
-  return ctx
-}
-
-/**
- * Read the current-site context. Falls back to the historical `/sites/[id]/*`
- * route convention for existing hosts that have not added a provider yet.
- */
-export function useGscCurrentSite(): GscCurrentSiteContext {
-  const provided = inject(gscCurrentSiteKey, null)
-  if (provided)
-    return provided
-
-  const route = useRoute()
-  return createGscCurrentSiteContext(() => route.params.id as string | undefined)
-}

package/app/composables/useGscInspectionHistory.ts

@@ -1,42 +0,0 @@
-// Fetches the inspection timeline for a single URL (by hash) from the
-// site's history shards. Oldest → newest. 404 / empty history is a normal
-// state on the first dashboard visit before a second snapshot runs.
-
-import type { InspectionHistoryRecord, InspectionHistoryResponse } from '@gscdump/contracts'
-import type { ComputedRef, Ref } from '@vue/runtime-core'
-import type { GscResourceStatus } from './_useGscResource'
-import { gscQueries } from '../queries/gsc'
-import { useGscResource } from './_useGscResource'
-
-export interface UseGscInspectionHistoryReturn {
-  response: Readonly<Ref<InspectionHistoryResponse | null>>
-  records: ComputedRef<InspectionHistoryRecord[]>
-  url: ComputedRef<string | null>
-  loading: ComputedRef<boolean>
-  status: Readonly<Ref<GscResourceStatus>>
-  error: Readonly<Ref<Error | null>>
-  refresh: () => Promise<void>
-}
-
-export function useGscInspectionHistory(
-  siteId: MaybeRefOrGetter<string | null | undefined>,
-  urlHash: MaybeRefOrGetter<string | null | undefined>,
-): UseGscInspectionHistoryReturn {
-  const { data, status, loading, error, refresh } = useGscResource<[string, string], InspectionHistoryResponse>({
-    keys: [siteId, urlHash] as const,
-    operation: (id, hash) => gscQueries.inspectionHistory(id, hash),
-  })
-
-  const records = computed(() => data.value?.records ?? [])
-  const url = computed(() => data.value?.url ?? null)
-
-  return {
-    response: data as Readonly<Ref<InspectionHistoryResponse | null>>,
-    records,
-    url,
-    loading,
-    status,
-    error,
-    refresh,
-  }
-}

package/app/composables/useGscInspections.ts

@@ -1,52 +0,0 @@
-// Fetches the URL-inspection entity index for a site, with PASS/NEUTRAL/FAIL
-// counts derived from the records. Split from the previous `useEntity(kind)`
-// discriminated API so each entity stays its own typed hook.
-
-import type { InspectionHistoryRecord, InspectionIndex } from '@gscdump/contracts'
-import type { ComputedRef, Ref } from '@vue/runtime-core'
-import type { GscResourceStatus } from './_useGscResource'
-import { gscQueries } from '../queries/gsc'
-import { useGscResource } from './_useGscResource'
-
-export interface UseGscInspectionsReturn {
-  index: Readonly<Ref<InspectionIndex | null>>
-  records: ComputedRef<InspectionHistoryRecord[]>
-  statusCounts: ComputedRef<{ PASS: number, NEUTRAL: number, FAIL: number, unknown: number }>
-  loading: ComputedRef<boolean>
-  status: Readonly<Ref<GscResourceStatus>>
-  error: Readonly<Ref<Error | null>>
-  refresh: () => Promise<void>
-}
-
-export function useGscInspections(siteId: MaybeRefOrGetter<string | null | undefined>): UseGscInspectionsReturn {
-  const { data, status, loading, error, refresh } = useGscResource<[string], InspectionIndex>({
-    keys: [siteId] as const,
-    operation: (id: string) => gscQueries.inspections(id),
-  })
-
-  const records = computed<InspectionHistoryRecord[]>(() =>
-    data.value ? Object.values(data.value.records) : [],
-  )
-
-  const statusCounts = computed(() => {
-    const counts = { PASS: 0, NEUTRAL: 0, FAIL: 0, unknown: 0 }
-    for (const r of records.value) {
-      const key = r.indexStatus as keyof typeof counts | undefined
-      if (key && key in counts)
-        counts[key]++
-      else
-        counts.unknown++
-    }
-    return counts
-  })
-
-  return {
-    index: data as Readonly<Ref<InspectionIndex | null>>,
-    records,
-    statusCounts,
-    loading,
-    status,
-    error,
-    refresh,
-  }
-}

package/app/composables/useGscPanelContext.ts

@@ -1,31 +0,0 @@
-// Provide/inject seam for analyzer panels. Pipeline panels (those declared
-// with `panel.ownsLifecycle: true`) need access to the analyzer runner +
-// long-running composable instances so they can fire `analyze`/`query` and
-// keep their phase state alive across tab switches.
-//
-// `/analyze` provides these once; panels inject. Type-only — runtime values
-// are the InjectionKey Symbols themselves.
-
-import type { AnalysisParams, AnalysisResult } from '@gscdump/engine/analysis-types'
-import type { InjectionKey } from '@vue/runtime-core'
-
-export interface GscPanelRunner {
-  /** Positional-form SQL runner — `{ rows, queryMs }`. */
-  query: (sql: string, params?: readonly unknown[]) => Promise<{ rows: Record<string, unknown>[], queryMs: number }>
-  /** Registry-driven analyzer dispatch over the same per-site DuckDB-WASM runtime. */
-  analyze: (params: AnalysisParams, opts?: { signal?: AbortSignal }) => Promise<AnalysisResult & { queryMs: number }>
-}
-
-export interface GscPanelRunnerContext {
-  runner: GscPanelRunner
-  ready: Ref<boolean>
-}
-
-export const gscPanelRunnerKey: InjectionKey<GscPanelRunnerContext> = Symbol('gscPanelRunnerKey')
-
-export function useGscPanelRunner(): GscPanelRunnerContext {
-  const ctx = inject(gscPanelRunnerKey, null)
-  if (!ctx)
-    throw new Error('useGscPanelRunner() called outside <GscAnalyzerPanel> context')
-  return ctx
-}