@gscdump/nuxt 0.19.0

package/app/composables/useGscAuth.ts

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

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

@@ -0,0 +1,47 @@
+// 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 { useGscResource } from './_useGscResource'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+
+export interface UseGscCountriesReturn {
+  response: Readonly<Ref<CountriesResponse | null>>
+  rows: ComputedRef<CountryRow[]>
+  range: ComputedRef<GscApiRange | null>
+  source: ComputedRef<CountriesResponse['source'] | null>
+  loading: ComputedRef<boolean>
+  status: Ref<GscResourceStatus>
+  error: 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({
+    keys: [
+      siteId,
+      () => toValue(range)?.start,
+      () => toValue(range)?.end,
+    ] as const,
+    fetcher: (id: string, start: string, end: string) =>
+      useGscAnalyticsClient().getCountries(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

@@ -0,0 +1,15 @@
+// Dashboard route convention `/sites/[id]/*` ↔ analytics layer's
+// `useGscSite(siteId)`. Pages collapse to:
+//   const { siteId, site } = useGscCurrentSite()
+// The analytics layer is otherwise route-agnostic — this composable is the
+// one place the `id` param name is hard-coded. Hosts using a different param
+// name should provide their own equivalent.
+
+export function useGscCurrentSite(): {
+  siteId: ComputedRef<string>
+  site: ReturnType<typeof useGscSite>
+} {
+  const route = useRoute()
+  const siteId = computed(() => String(route.params.id))
+  return { siteId, site: useGscSite(siteId) }
+}

package/app/composables/useGscEngine.ts

@@ -0,0 +1,16 @@
+// App-wide engine override for `useGscQuery`. SSR-safe via `useState`.
+//
+// Resolution priority lives in `useGscQueryDispatcher.pickEngine`:
+//   per-call `opts.engine` → `useGscEngine().value` → `runtimeConfig.public.
+//   analytics.defaultEngine` → `'auto'`.
+//
+// Set the value once on the consumer side (e.g. from your auth plugin's
+// `onReady` hook reading a per-user feature flag) and every query inherits.
+
+import type { GscQueryEngine } from './useGscQuery'
+
+const STATE_KEY = 'gscdump:engine'
+
+export function useGscEngine(): Ref<GscQueryEngine | null> {
+  return useState<GscQueryEngine | null>(STATE_KEY, () => null)
+}

package/app/composables/useGscInspectionHistory.ts

@@ -0,0 +1,42 @@
+// 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 { useGscResource } from './_useGscResource'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+
+export interface UseGscInspectionHistoryReturn {
+  response: Readonly<Ref<InspectionHistoryResponse | null>>
+  records: ComputedRef<InspectionHistoryRecord[]>
+  url: ComputedRef<string | null>
+  loading: ComputedRef<boolean>
+  status: Ref<GscResourceStatus>
+  error: 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({
+    keys: [siteId, urlHash] as const,
+    fetcher: (id: string, hash: string) => useGscAnalyticsClient().getInspectionHistory(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

@@ -0,0 +1,52 @@
+// 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 { useGscResource } from './_useGscResource'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+
+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: Ref<GscResourceStatus>
+  error: Ref<Error | null>
+  refresh: () => Promise<void>
+}
+
+export function useGscInspections(siteId: MaybeRefOrGetter<string | null | undefined>): UseGscInspectionsReturn {
+  const { data, status, loading, error, refresh } = useGscResource({
+    keys: [siteId] as const,
+    fetcher: (id: string) => useGscAnalyticsClient().getInspections(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

@@ -0,0 +1,24 @@
+// 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 { InjectionKey } from '@vue/runtime-core'
+import type { GscAnalyzerInstance } from './useGscAnalyzer'
+
+export interface GscPanelRunnerContext {
+  runner: GscAnalyzerInstance
+  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
+}

package/app/composables/useGscParquetTable.ts

@@ -0,0 +1,199 @@
+// Parquet-attached DuckDB table view: fuzzy-search + sortable metrics +
+// pagination over a single attached parquet (`main.<table>`), date-filtered.
+//
+// Sibling of `useGscRollupTable` — the rollup variant fetches a precomputed
+// JSON payload; this variant fires SQL against a parquet view in the
+// browser-attached DuckDB-WASM runtime. Two callers today (analyze.vue's
+// `pages` and `keywords` raw tabs); third+ callers are mechanical.
+//
+// Caller passes the `query` fn from `useGscAnalyzer(siteId)`; the composable
+// owns the SQL builder, the debounce, the watcher, and the count+page
+// Promise.all. It does NOT own `period`/`sort`/`page`/`q` — those are passed
+// in so callers can deep-link and share state (the `/analyze` page wires one
+// `useGscTableState` across raw + analyzer tabs).
+
+import type { MaybeRefOrGetter, Ref } from '@vue/runtime-core'
+import type { GscSortState } from './useGscTableState'
+
+interface QueryResult { rows: Record<string, unknown>[], queryMs: number }
+
+export interface UseGscParquetTableOptions {
+  /** Attached view name in `main.<table>` (e.g. `pages`, `keywords`). */
+  table: MaybeRefOrGetter<string>
+  /** Dimension column rows group by + fuzzy-search against. */
+  dim: MaybeRefOrGetter<string>
+  /** `useGscAnalyzer(siteId).query`. */
+  query: (sql: string, params?: unknown[]) => Promise<QueryResult>
+  /** Date window applied as `date BETWEEN ? AND ?`. */
+  dateRange: MaybeRefOrGetter<{ start: string, end: string }>
+  /**
+   * External table state — search, sort, page, pageSize. Usually a shared
+   *  `useGscTableState()` so URL deep-links survive tab switches.
+   */
+  q: Ref<string>
+  sort: Ref<GscSortState | null>
+  page: Ref<number>
+  pageSize: Ref<number>
+  /** Gate firing the query until the underlying runtime is ready. */
+  ready: MaybeRefOrGetter<boolean>
+  /** Re-fire whenever any of these change. (Period state, stableData flag, …) */
+  triggers?: MaybeRefOrGetter<unknown>[]
+  /** Search debounce. Default 200ms. */
+  debounceMs?: number
+}
+
+export interface UseGscParquetTableReturn {
+  rows: Ref<Record<string, unknown>[]>
+  totalRows: Ref<number | null>
+  totalPages: Ref<number | null>
+  queryMs: Ref<number | null>
+  loading: Ref<boolean>
+  error: Ref<string | null>
+}
+
+const SQL_SORT_COLS = new Set(['clicks', 'impressions', 'ctr', 'avg_position'])
+const WHITESPACE_RE = /\s+/
+
+function tokenize(s: string): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const t of s.trim().split(WHITESPACE_RE).filter(Boolean)) {
+    const lower = t.toLowerCase()
+    if (!seen.has(lower)) {
+      seen.add(lower)
+      out.push(lower)
+    }
+  }
+  return out
+}
+
+interface SearchClauses { where: string, rank: string, params: unknown[] }
+
+function buildSearchClauses(dim: string, tokens: string[]): SearchClauses {
+  if (tokens.length === 0)
+    return { where: '', rank: '', params: [] }
+  const patterns = tokens.map(t => `%${t}%`)
+  const ors = tokens.map(() => `${dim} ILIKE ?`).join(' OR ')
+  const cases = tokens.map(() => `(CASE WHEN ${dim} ILIKE ? THEN 1 ELSE 0 END)`).join(' + ')
+  return {
+    where: `WHERE (${ors})`,
+    rank: `${cases} DESC,`,
+    params: [...patterns, ...patterns],
+  }
+}
+
+function withDateFilter(
+  searchWhere: string,
+  searchParams: unknown[],
+  start: string,
+  end: string,
+): { where: string, params: unknown[] } {
+  const dateClause = 'date BETWEEN ? AND ?'
+  const where = searchWhere ? `${searchWhere} AND ${dateClause}` : `WHERE ${dateClause}`
+  return { where, params: [...searchParams, start, end] }
+}
+
+function sortKey(dim: string, sort: GscSortState | null): string {
+  const col = sort?.column ?? 'clicks'
+  if (SQL_SORT_COLS.has(col))
+    return col
+  if (col === dim)
+    return dim
+  return 'clicks'
+}
+
+export function useGscParquetTable(opts: UseGscParquetTableOptions): UseGscParquetTableReturn {
+  const rows = ref<Record<string, unknown>[]>([])
+  const totalRows = ref<number | null>(null)
+  const queryMs = ref<number | null>(null)
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+
+  const searchDebounced = ref('')
+  let handle: ReturnType<typeof setTimeout> | null = null
+  watch(opts.q, (v: string) => {
+    if (handle)
+      clearTimeout(handle)
+    handle = setTimeout(() => {
+      searchDebounced.value = v
+    }, opts.debounceMs ?? 200)
+  })
+
+  async function run(): Promise<void> {
+    if (!toValue(opts.ready))
+      return
+    const table = toValue(opts.table)
+    const dim = toValue(opts.dim)
+    const { start, end } = toValue(opts.dateRange)
+    const tokens = tokenize(searchDebounced.value)
+    const { where: searchWhere, rank, params: searchParams } = buildSearchClauses(dim, tokens)
+    const dir = (opts.sort.value?.direction ?? 'desc').toUpperCase()
+    const limit = opts.pageSize.value
+    const offset = (opts.page.value - 1) * limit
+
+    const wherePart = withDateFilter(searchWhere, searchParams.slice(0, tokens.length), start, end)
+    const rankParams = searchParams.slice(tokens.length)
+
+    const pageSql = `
+      SELECT ${dim},
+             SUM(clicks)::BIGINT AS clicks,
+             SUM(impressions)::BIGINT AS impressions,
+             CASE WHEN SUM(impressions) > 0
+                  THEN ROUND(SUM(clicks) * 1.0 / SUM(impressions), 4)
+                  ELSE 0 END AS ctr,
+             CASE WHEN SUM(impressions) > 0
+                  THEN ROUND(SUM(sum_position) / SUM(impressions) + 1, 2)
+                  ELSE 0 END AS avg_position
+      FROM main.${table}
+      ${wherePart.where}
+      GROUP BY ${dim}
+      ORDER BY ${rank} ${sortKey(dim, opts.sort.value)} ${dir}
+      LIMIT ${limit} OFFSET ${offset}
+    `
+    const countSql = `SELECT COUNT(DISTINCT ${dim})::BIGINT AS n FROM main.${table} ${wherePart.where}`
+
+    loading.value = true
+    error.value = null
+    rows.value = []
+    queryMs.value = null
+    try {
+      const [pageRes, countRes] = await Promise.all([
+        opts.query(pageSql, [...wherePart.params, ...rankParams]),
+        opts.query(countSql, wherePart.params),
+      ])
+      rows.value = pageRes.rows
+      queryMs.value = pageRes.queryMs
+      const n = countRes.rows[0]?.n
+      totalRows.value = typeof n === 'bigint' ? Number(n) : typeof n === 'number' ? n : null
+    }
+    catch (err) {
+      error.value = err instanceof Error ? err.message : String(err)
+    }
+    finally {
+      loading.value = false
+    }
+  }
+
+  const triggerSources = [
+    () => toValue(opts.ready),
+    () => toValue(opts.table),
+    () => toValue(opts.dim),
+    () => toValue(opts.dateRange),
+    opts.sort,
+    opts.page,
+    opts.pageSize,
+    searchDebounced,
+    ...(opts.triggers ?? []).map(t => () => toValue(t as MaybeRefOrGetter<unknown>)),
+  ]
+  watch(triggerSources, () => {
+    void run()
+  })
+
+  const totalPages = computed(() => {
+    if (totalRows.value == null)
+      return null
+    return Math.max(1, Math.ceil(totalRows.value / opts.pageSize.value))
+  })
+
+  return { rows, totalRows, totalPages, queryMs, loading, error }
+}