@gscdump/nuxt 0.21.2 → 0.22.1

package/README.md

@@ -86,31 +86,28 @@ the data — e.g. nuxtseo.com pro consuming gscdump.com. Two pieces:
    preflights can include this header, while DuckDB-WASM range reads are
    authorized by the token embedded in each URL.
 
-The `setupGscFetchAuth` helper collapses the boilerplate:
+Wire it from a `'pre'`-enforced client plugin so downstream layer plugins see
+the auth on first read. The layer's `setGscAuth` accepts a value, a `Ref`,
+or a getter — use a getter when credentials may refresh during the session:
 
 ```ts
 // plugins/00.gscdump-auth.client.ts
-export default setupGscFetchAuth({
-  credentialsEndpoint: '/api/me/gscdump-credentials',
-  // Optional: preload host-specific state. Runs inside runWithContext so
-  // composables work. Useful for useState-backed flags read by the layer's
-  // composables at construction time.
-  async onReady() {
-    const flag = useState<boolean | null>('app:browser-analyzer-enabled', () => null)
-    if (flag.value !== null)
-      return
-    const settings = await useGscFetch()<{ browserAnalyzerEnabled: boolean }>('/api/user/settings').catch(() => null)
-    flag.value = !!settings?.browserAnalyzerEnabled
+export default defineNuxtPlugin({
+  name: 'gscdump-auth',
+  enforce: 'pre',
+  async setup() {
+    const creds = ref<{ apiKey: string, browserAnalyzerEnabled?: boolean } | null>(null)
+    creds.value = await $fetch('/api/me/gscdump-credentials').catch(() => null)
+    setGscAuth(() => ({
+      apiKey: creds.value?.apiKey ?? null,
+      browserAnalyzerEnabled: !!creds.value?.browserAnalyzerEnabled,
+    }))
   },
 })
 ```
 
-The helper is `enforce: 'pre'` and dedupes via an inflight promise; Nuxt
-blocks subsequent plugins until headers land, removing the auth-header race
-where a `useGscQuery` mounts before credentials resolve.
-
-`credentialsEndpoint` returns `{ apiKey: string, ... }` by default. Override
-the field name with `tokenField` and the header name with `headerName`.
+`useGscQuery` mounts that race the credential fetch resolve once the
+`'pre'` plugin's `await` settles — Nuxt blocks subsequent plugins on it.
 
 Onboarding and lifecycle state stay outside this layer. A consumer app should
 use `@gscdump/sdk` from its host backend to register users/sites, read

package/app/composables/_useGscQueryDispatcher.ts

@@ -7,7 +7,8 @@
 
 import type { _useGscAuthInternal } from './useGscAuth'
 import type { GscQueryDecisionReason, GscQueryEngine } from './useGscQuery'
-import { useGscEngine } from './useGscEngine'
+
+const ENGINE_STATE_KEY = 'gscdump:engine'
 
 type InternalAuthState = ReturnType<typeof _useGscAuthInternal>['value']
 
@@ -26,14 +27,14 @@ export interface GscFallbackEvent {
 }
 
 export interface PickEngineOpts {
-  /** Per-call override. Wins over `useGscEngine()` + `runtimeConfig.public.analytics.defaultEngine`. */
+  /** Per-call override. Wins over the `gscdump:engine` useState + `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 →
+   * resolution chain: `opts.perCall` → `gscdump:engine` useState → runtimeConfig →
    * `'auto'`. Then maps `auto` against `auth.browserAnalyzerEnabled`.
    */
   pickEngine: (auth: InternalAuthState, opts?: PickEngineOpts) => GscEngineDecision
@@ -110,7 +111,7 @@ export function createDefaultGscQueryDispatcher(
 }
 
 function resolveDefaultEngine(): GscQueryEngine {
-  const override = useGscEngine().value
+  const override = useState<GscQueryEngine | null>(ENGINE_STATE_KEY, () => null).value
   if (override)
     return override
   const cfg = useRuntimeConfig().public.analytics as { defaultEngine?: GscQueryEngine } | undefined

package/app/composables/useGscAnalytics.ts

@@ -171,14 +171,22 @@ function createContext(): GscAnalyticsContext {
   // Lazy-load: defer refreshSites until something actually reads `sites`.
   // Eager kick-off used to race host plugins that set auth via `setGscAuth`;
   // first call would 401 and the rest of the session would silently degrade.
-  // Triggering on first read defers the request to a microtask after plugin
-  // setup, so auth state is in place.
+  // Triggering on first read still needs to wait until hydration is done:
+  // `refreshSites()` flips `sitesLoading` synchronously, and doing that during
+  // the client's first render makes the sidebar disagree with SSR markup.
   let kickedOff = false
   function maybeKickOff(): void {
     if (kickedOff || !import.meta.client)
       return
     kickedOff = true
-    refreshSites()
+    const start = (): void => {
+      void refreshSites()
+    }
+    const nuxtApp = useNuxtApp()
+    if (nuxtApp.isHydrating)
+      onNuxtReady(start)
+    else
+      queueMicrotask(start)
   }
   const lazySites = computed<SiteListItem[] | null>(() => {
     maybeKickOff()

package/app/composables/useGscAnalyzerBatch.ts

@@ -16,7 +16,7 @@ export interface GscAnalyzerBatchEntry<TResult> {
 }
 
 export interface GscAnalyzerBatchRunner {
-  analyze: (params: { type: string, dateStart?: string, dateEnd?: string }) => Promise<unknown>
+  analyze: (params: { type: string, startDate?: string, endDate?: string }) => Promise<unknown>
 }
 
 export interface UseGscAnalyzerBatchOptions {
@@ -72,7 +72,7 @@ export function useGscAnalyzerBatch<TResult = unknown>(
         return
       states.value = { ...states.value, [id]: { status: 'running', result: null, error: null } }
       try {
-        const result = await runner.analyze({ type: id, dateStart: range.start, dateEnd: range.end })
+        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 } }

package/app/composables/useGscPanelContext.ts

@@ -6,11 +6,18 @@
 // `/analyze` provides these once; panels inject. Type-only — runtime values
 // are the InjectionKey Symbols themselves.
 
+import type { AnalysisParams, AnalysisResult } from '@gscdump/analysis'
 import type { InjectionKey } from '@vue/runtime-core'
-import type { GscAnalyzerInstance } from './useGscAnalyzer'
+
+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: GscAnalyzerInstance
+  runner: GscPanelRunner
   ready: Ref<boolean>
 }
 

package/app/composables/useGscParquetTable.ts

@@ -1,10 +1,9 @@
 // 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.
+// 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

package/app/composables/useGscQueryDispatcher.ts

@@ -1,122 +1,14 @@
-// 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
-}
+// 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/useGscResource.ts

@@ -1,114 +1,11 @@
-// Site-keyed async resource composable. Owns key-watch, stale-token discard,
-// status classification, refresh, and dispose for every read-only `/api/__gsc/*`
-// fetcher in the layer. Resource composables (useGscSitemaps,
-// useGscIndexingDiagnostics, …) are thin adapters that wire reactive keys to
-// `useGscAnalyticsClient().getX(...)` plus optional derived computeds.
-//
-// Stale-token (not AbortController) because `@gscdump/sdk`'s AnalyticsClient
-// doesn't accept a signal. Late-arriving promises from a superseded run are
-// dropped on `data`/`status` writes; the in-flight fetch still runs to
-// completion, which is acceptable for read-only GETs.
-
-import type { ComputedRef, Ref, WatchSource } from 'vue'
-import type { GscErrorStatus } from '../utils/gsc-error'
-import { classifyGscError } from '../utils/gsc-error'
-
-export type GscResourceStatus = 'idle' | 'pending' | 'success' | 'empty' | GscErrorStatus
-
-export interface UseGscResourceOptions<TArgs extends readonly unknown[], TData> {
-  /** Reactive args passed to the fetcher. Resource stays idle while any required key is null/undefined. */
-  keys: { [I in keyof TArgs]: MaybeRefOrGetter<TArgs[I] | null | undefined> }
-  /** Async fetcher invoked with the resolved keys. */
-  fetcher: (...args: TArgs) => Promise<TData | null>
-  /** Predicate for the `empty` status — defaults to checking `null`/`[]`/typical container fields. */
-  isEmpty?: (data: TData) => boolean
-  /** Extra reactive sources that should retrigger a fetch. */
-  watchSources?: WatchSource[]
-}
-
-export interface UseGscResourceReturn<TData> {
-  data: Ref<TData | null>
-  status: Ref<GscResourceStatus>
-  loading: ComputedRef<boolean>
-  error: Ref<Error | null>
-  refresh: () => Promise<void>
-}
-
-function defaultIsEmpty(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', 'records', 'snapshots', 'items', 'results']) {
-      const arr = rec[key]
-      if (Array.isArray(arr))
-        return arr.length === 0
-    }
-  }
-  return false
-}
-
-export function useGscResource<TArgs extends readonly unknown[], TData>(
-  opts: UseGscResourceOptions<TArgs, TData>,
-): UseGscResourceReturn<TData> {
-  const data = shallowRef<TData | null>(null)
-  const status = ref<GscResourceStatus>('idle')
-  const error = ref<Error | null>(null)
-  const loading = computed(() => status.value === 'pending')
-
-  let runToken = 0
-
-  function resolveKeys(): TArgs | null {
-    const out: unknown[] = []
-    for (const k of opts.keys) {
-      const v = toValue(k)
-      if (v == null || v === '')
-        return null
-      out.push(v)
-    }
-    return out as unknown as TArgs
-  }
-
-  async function refresh(): Promise<void> {
-    const args = resolveKeys()
-    const token = ++runToken
-    if (!args) {
-      data.value = null
-      status.value = 'idle'
-      error.value = null
-      return
-    }
-    status.value = 'pending'
-    error.value = null
-    try {
-      const out = await opts.fetcher(...args)
-      if (token !== runToken)
-        return
-      data.value = out
-      const empty = out == null || (opts.isEmpty ?? defaultIsEmpty)(out)
-      status.value = empty ? 'empty' : 'success'
-    }
-    catch (e) {
-      if (token !== runToken)
-        return
-      const classified = classifyGscError(e)
-      error.value = e instanceof Error ? e : new Error(String(e))
-      status.value = classified.status
-      data.value = null
-    }
-  }
-
-  watch(
-    [...opts.keys.map(k => () => toValue(k)), ...(opts.watchSources ?? [])],
-    refresh,
-    { immediate: true },
-  )
-
-  onScopeDispose(() => {
-    runToken++
-  })
-
-  return { data, status, loading, error, refresh }
-}
+// 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'