@gscdump/nuxt 0.19.0

package/app/components/GscSourceDebugPanel.vue

@@ -0,0 +1,195 @@
+<script setup lang="ts">
+// Floating debug panel showing which AnalysisQuerySource the server resolved
+// for the current site. Reads `/api/__gsc/sites/:siteId/source-info`. Ships in the
+// layer so every consumer gets the same shape without reimplementing.
+//
+// Siting:
+//  - `site` prop > `siteId` prop > route param `id` (the canonical path)
+//  - Off-site routes (overview, /pricing, etc.) render a "no site context" tile.
+//
+// Visibility:
+//  - Hidden by default; click the floating ⓘ pill to open.
+//  - Preference persists in localStorage per origin (key `gsc-debug-panel`).
+
+const props = defineProps<{
+  /** Explicit site id. Falls back to route.params.id. */
+  site?: string
+  /** @deprecated Use `site`. Kept so older callers still type-check. */
+  siteId?: string
+}>()
+
+const route = useRoute()
+const resolvedSite = computed(() => props.site ?? props.siteId ?? (typeof route.params.id === 'string' ? route.params.id : null))
+
+const open = useLocalStorage('gsc-debug-panel', false)
+
+const { info, loading, error } = useGscAnalyticsSourceInfo(() => resolvedSite.value)
+
+// Off-site fallback — `/api/__gsc/whoami` exposes identity.attrs (tier,
+// plan, etc.) so the panel can still show viewer context on routes without
+// a site (overview, pricing, landing pages). Only fetched when we have no
+// site to resolve, so per-site routes pay nothing for this.
+interface WhoamiResponse {
+  userId: string
+  siteIds: string[] | null
+  identityAttrs: Record<string, unknown>
+  sourceProviderRegistered: boolean
+}
+const whoami = ref<WhoamiResponse | null>(null)
+const whoamiLoading = ref(false)
+watchEffect(() => {
+  if (!import.meta.client || resolvedSite.value || !open.value || whoami.value || whoamiLoading.value)
+    return
+  whoamiLoading.value = true
+  const request = useGscAnalyticsClient().whoami() as Promise<WhoamiResponse>
+  request
+    .then((res) => { whoami.value = res })
+    .catch(() => { /* surface via empty state, not a toast */ })
+    .finally(() => { whoamiLoading.value = false })
+})
+
+function fmtKind(kind: 'row' | 'sql'): string {
+  return kind === 'sql' ? 'SQL' : 'Rows'
+}
+</script>
+
+<template>
+  <ClientOnly>
+    <!-- Toggle affordance: always visible, bottom-right. -->
+    <button
+      type="button"
+      class="fixed z-40 bottom-3 right-3 inline-flex items-center gap-1.5 px-2.5 py-1.5 rounded-full border border-default bg-default/90 backdrop-blur text-[11px] font-mono text-muted hover:text-default shadow-sm transition-colors"
+      :title="open ? 'Hide data-source debug panel' : 'Show data-source debug panel'"
+      @click="open = !open"
+    >
+      <span class="size-1.5 rounded-full" :class="info ? (info.kind === 'sql' ? 'bg-primary' : 'bg-amber-500') : 'bg-dimmed'" />
+      src: {{ info?.name ?? (loading ? '…' : resolvedSite ? '—' : 'no site') }}
+      <UIcon :name="open ? 'i-lucide-chevron-down' : 'i-lucide-chevron-up'" class="size-3" />
+    </button>
+
+    <!-- Panel body -->
+    <div
+      v-if="open"
+      class="fixed z-40 bottom-12 right-3 w-[320px] rounded-lg border border-default bg-default/95 backdrop-blur shadow-lg text-[12px] font-mono"
+    >
+      <header class="flex items-center justify-between px-3 py-2 border-b border-default">
+        <span class="font-semibold text-default">Analytics source</span>
+        <button type="button" class="text-dimmed hover:text-default" @click="open = false">
+          <UIcon name="i-lucide-x" class="size-3.5" />
+        </button>
+      </header>
+
+      <div v-if="!resolvedSite" class="flex flex-col divide-y divide-default">
+        <div class="px-3 py-2.5 text-dimmed text-[11px] leading-snug">
+          No site context on this route. Showing identity only.
+        </div>
+        <div v-if="whoamiLoading && !whoami" class="p-3 text-dimmed">
+          Resolving…
+        </div>
+        <div v-else-if="whoami" class="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 px-3 py-2.5">
+          <span class="text-dimmed">userId</span>
+          <span class="text-default truncate" :title="whoami.userId">{{ whoami.userId }}</span>
+
+          <span class="text-dimmed">sites</span>
+          <span class="text-default">
+            {{ whoami.siteIds == null ? 'all' : `${whoami.siteIds.length} scoped` }}
+          </span>
+
+          <span class="text-dimmed">source</span>
+          <span :class="whoami.sourceProviderRegistered ? 'text-success' : 'text-error'">
+            {{ whoami.sourceProviderRegistered ? 'registered' : 'not registered' }}
+          </span>
+
+          <template v-for="(value, key) in whoami.identityAttrs" :key="key">
+            <span class="text-dimmed">{{ key }}</span>
+            <span class="text-default truncate" :title="String(value)">{{ String(value) }}</span>
+          </template>
+        </div>
+      </div>
+      <div v-else-if="loading && !info" class="p-3 text-dimmed">
+        Resolving…
+      </div>
+      <div v-else-if="error" class="p-3 text-error">
+        <div class="font-semibold mb-1">
+          Failed to resolve source
+        </div>
+        <div class="text-[11px] leading-snug">
+          {{ error.message }}
+        </div>
+      </div>
+      <div v-else-if="info" class="flex flex-col divide-y divide-default">
+        <div class="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 px-3 py-2.5">
+          <span class="text-dimmed">site</span>
+          <span class="truncate text-default" :title="resolvedSite">{{ resolvedSite }}</span>
+
+          <span class="text-dimmed">name</span>
+          <span class="text-default">{{ info.name }}</span>
+
+          <span class="text-dimmed">kind</span>
+          <span>
+            <span
+              class="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] uppercase tracking-wider font-semibold"
+              :class="info.kind === 'sql' ? 'bg-primary/10 text-primary' : 'bg-amber-500/10 text-amber-600 dark:text-amber-400'"
+            >{{ fmtKind(info.kind) }}</span>
+          </span>
+
+          <span class="text-dimmed">attach</span>
+          <span :class="info.browserAttachEligible ? 'text-success' : 'text-muted'">
+            {{ info.browserAttachEligible ? 'browser-attached' : 'server-routed' }}
+          </span>
+
+          <span class="text-dimmed">analyzers</span>
+          <span class="text-default">
+            {{ info.supportedAnalyzerIds.length }}
+            <span class="text-dimmed">runnable</span>
+          </span>
+
+          <template v-for="(value, key) in (info.identityAttrs ?? {})" :key="key">
+            <span class="text-dimmed">{{ key }}</span>
+            <span class="text-default truncate" :title="String(value)">{{ String(value) }}</span>
+          </template>
+        </div>
+
+        <div class="px-3 py-2.5">
+          <div class="text-[10px] uppercase tracking-widest text-dimmed font-semibold mb-1.5">
+            capabilities
+          </div>
+          <div class="flex flex-wrap gap-1">
+            <template v-for="(value, cap) in info.capabilities" :key="cap">
+              <span
+                v-if="value"
+                class="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] bg-elevated text-muted border border-default"
+              >
+                {{ cap }}
+              </span>
+            </template>
+            <span
+              v-if="!Object.values(info.capabilities).some(Boolean)"
+              class="text-[11px] text-dimmed"
+            >
+              none advertised
+            </span>
+          </div>
+        </div>
+
+        <details class="px-3 py-2.5">
+          <summary class="text-[10px] uppercase tracking-widest text-dimmed font-semibold cursor-pointer">
+            supported analyzer ids ({{ info.supportedAnalyzerIds.length }})
+          </summary>
+          <div class="mt-2 max-h-48 overflow-y-auto">
+            <div
+              v-for="id in info.supportedAnalyzerIds"
+              :key="id"
+              class="text-[11px] text-muted py-0.5"
+            >
+              {{ id }}
+            </div>
+            <div v-if="!info.supportedAnalyzerIds.length" class="text-[11px] text-dimmed">
+              none
+            </div>
+          </div>
+        </details>
+      </div>
+    </div>
+  </ClientOnly>
+</template>

package/app/components/GscSyncStatusCell.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+const props = defineProps<{
+  data?: {
+    status: string
+    rowsFetched: number
+    rowsInserted: number
+    error: string | null
+  }
+}>()
+
+const statusColor = computed(() => {
+  if (!props.data)
+    return 'text-muted'
+  switch (props.data.status) {
+    case 'completed': return 'text-success'
+    case 'processing': return 'text-info'
+    case 'queued': return 'text-muted'
+    case 'failed': return 'text-error'
+    default: return 'text-muted'
+  }
+})
+
+const statusIcon = computed(() => {
+  if (!props.data)
+    return '-'
+  switch (props.data.status) {
+    case 'completed': return '✓'
+    case 'processing': return '⟳'
+    case 'queued': return '○'
+    case 'failed': return '✗'
+    default: return '?'
+  }
+})
+</script>
+
+<template>
+  <span v-if="!data" class="text-muted">-</span>
+  <UTooltip v-else>
+    <span :class="statusColor" class="font-mono">
+      {{ statusIcon }}
+      <span v-if="data.status === 'completed'" class="text-muted ml-1">{{ data.rowsFetched }}</span>
+    </span>
+    <template #content>
+      <div class="text-xs space-y-1">
+        <div>Status: {{ data.status }}</div>
+        <div>Fetched: {{ data.rowsFetched?.toLocaleString() || 0 }}</div>
+        <div>Inserted: {{ data.rowsInserted?.toLocaleString() || 0 }}</div>
+        <div v-if="data.error" class="text-error">
+          Error: {{ data.error }}
+        </div>
+      </div>
+    </template>
+  </UTooltip>
+</template>

package/app/components/GscTopRollupCard.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+// Reads a `top_*_28d` rollup directly from R2 and renders the top 10 rows.
+// Zero DuckDB round-trip — the rollup pre-aggregated clicks over the
+// trailing 28 days when sync last completed. Hidden when the rollup isn't
+// built yet (dashboard still shows the live tables as the canonical view).
+
+import { useGscRollup } from '../composables/useGscRollup'
+
+interface TopPageRow { url: string, clicks: number, impressions: number, sum_position: number }
+interface TopKeywordRow { query: string, clicks: number, impressions: number, sum_position: number }
+type TopRow = TopPageRow | TopKeywordRow
+
+const { siteIdentifier, rollupId, title, labelKey, hrefBase } = defineProps<{
+  siteIdentifier: string | null | undefined
+  rollupId: 'top_pages_28d' | 'top_keywords_28d'
+  title: string
+  // Field on each row to render as the label (e.g. 'url' or 'query')
+  labelKey: 'url' | 'query'
+  // Optional: if set, label becomes a link to `${hrefBase}${encodeURIComponent(label)}`
+  hrefBase?: string
+}>()
+
+const { envelope, loading } = useGscRollup<TopRow[]>(() => siteIdentifier ?? null, () => rollupId)
+
+const top10 = computed(() => (envelope.value?.payload ?? []).slice(0, 10))
+const hasClicks = computed(() => top10.value.some((r: TopRow) => r.clicks > 0))
+
+const builtAtRelative = computed(() => {
+  const builtAt = envelope.value?.builtAt
+  if (!builtAt)
+    return null
+  const ageMs = Date.now() - builtAt
+  const hours = Math.floor(ageMs / 3600_000)
+  if (hours < 1)
+    return 'just now'
+  if (hours < 24)
+    return `${hours}h ago`
+  return `${Math.floor(hours / 24)}d ago`
+})
+</script>
+
+<template>
+  <UCard v-if="loading || top10.length">
+    <template #header>
+      <div class="flex items-center justify-between gap-4">
+        <div>
+          <h3 class="font-semibold">
+            {{ title }}
+          </h3>
+          <p class="text-xs text-muted mt-0.5">
+            Last 28 days<span v-if="builtAtRelative"> · built {{ builtAtRelative }}</span>
+          </p>
+        </div>
+        <span class="text-[10px] font-mono uppercase text-cyan-400 border border-cyan-500/40 bg-cyan-500/5 px-1.5 py-0.5">
+          rollup
+        </span>
+      </div>
+    </template>
+
+    <div v-if="loading && !top10.length" class="space-y-2">
+      <USkeleton v-for="i in 5" :key="i" class="h-6" />
+    </div>
+    <div v-else-if="!hasClicks" class="text-sm text-muted py-4 text-center">
+      No clicks in the last 28 days.
+    </div>
+    <div v-else class="space-y-1">
+      <div
+        v-for="(row, i) in top10"
+        :key="String((row as any)[labelKey])"
+        class="flex items-center justify-between gap-3 py-1 text-sm border-b border-default/40 last:border-0"
+      >
+        <div class="flex items-center gap-2 min-w-0">
+          <span class="text-xs text-muted tabular-nums w-5 text-right">{{ i + 1 }}</span>
+          <component
+            :is="hrefBase ? 'NuxtLink' : 'span'"
+            :to="hrefBase ? `${hrefBase}${encodeURIComponent(String((row as any)[labelKey]))}` : undefined"
+            class="truncate"
+            :class="hrefBase ? 'text-primary hover:underline' : ''"
+          >
+            {{ (row as any)[labelKey] }}
+          </component>
+        </div>
+        <div class="flex items-center gap-3 text-xs shrink-0 tabular-nums text-muted">
+          <span class="text-neutral-200">{{ row.clicks.toLocaleString() }}</span>
+          <span>{{ row.impressions.toLocaleString() }} impr</span>
+        </div>
+      </div>
+    </div>
+  </UCard>
+</template>

package/app/composables/_useGscBackfill.ts

@@ -0,0 +1,111 @@
+// Detects `meta.backfillRequired` from tool/analysis responses, kicks off an
+// on-demand backfill request, polls sync-progress, and invokes a refetch once
+// the requested range is synced.
+
+import { useGscFetch } from '../utils/gsc-fetch'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+
+interface BackfillRange {
+  startDate: string
+  endDate: string
+}
+
+interface SyncProgressResponse {
+  sites?: Array<{
+    id: string
+    oldestDateSynced?: string | null
+    newestDateSynced?: string | null
+    syncStatus?: string
+    backfill?: { percent?: number }
+  }>
+}
+
+export interface GscBackfillState {
+  pending: Ref<boolean>
+  range: Ref<BackfillRange | null>
+  percent: Ref<number>
+  error: Ref<string | null>
+}
+
+const POLL_INTERVAL_MS = 4000
+const POLL_MAX_MS = 15 * 60 * 1000
+
+export function useGscBackfill(): GscBackfillState & {
+  request: (siteId: string, req: BackfillRange, refetch: () => Promise<unknown> | unknown) => Promise<void>
+  maybeTrigger: (meta: unknown, siteId: string, refetch: () => Promise<unknown> | unknown) => boolean
+  reset: () => void
+} {
+  const pending = ref(false)
+  const range = ref<BackfillRange | null>(null)
+  const percent = ref(0)
+  const error = ref<string | null>(null)
+  // Track ranges we've already attempted in this session so a failed/timed-out
+  // backfill doesn't retrigger on every refetch.
+  const attemptedKeys = new Set<string>()
+
+  function rangeKey(siteId: string, r: BackfillRange): string {
+    return `${siteId}:${r.startDate}:${r.endDate}`
+  }
+
+  async function isRangeCovered(siteId: string, req: BackfillRange): Promise<boolean> {
+    const progress = await useGscFetch()<SyncProgressResponse>('/api/sync-progress').catch(() => null)
+    const site = progress?.sites?.find(s => s.id === siteId)
+    if (!site?.oldestDateSynced || !site?.newestDateSynced)
+      return false
+    percent.value = site.backfill?.percent ?? percent.value
+    return req.startDate >= site.oldestDateSynced && req.endDate <= site.newestDateSynced
+  }
+
+  async function request(siteId: string, req: BackfillRange, refetch: () => Promise<unknown> | unknown): Promise<void> {
+    pending.value = true
+    range.value = req
+    percent.value = 0
+    error.value = null
+    attemptedKeys.add(rangeKey(siteId, req))
+
+    await useGscAnalyticsClient().requestBackfill(siteId, req).catch((err) => {
+      error.value = (err as { data?: { message?: string }, message?: string })?.data?.message
+        || (err as Error)?.message
+        || 'Failed to queue backfill'
+    })
+
+    if (error.value) {
+      pending.value = false
+      return
+    }
+
+    const started = Date.now()
+    let covered = false
+    while (Date.now() - started < POLL_MAX_MS) {
+      await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS))
+      covered = await isRangeCovered(siteId, req)
+      if (covered)
+        break
+    }
+
+    if (!covered)
+      error.value = 'Backfill did not complete within the expected window. Try again later.'
+
+    if (covered)
+      await refetch()
+    pending.value = false
+    range.value = null
+  }
+
+  function maybeTrigger(meta: unknown, siteId: string, refetch: () => Promise<unknown> | unknown): boolean {
+    const backfillRequired = (meta as { backfillRequired?: BackfillRange })?.backfillRequired
+    if (!backfillRequired || pending.value)
+      return false
+    if (attemptedKeys.has(rangeKey(siteId, backfillRequired)))
+      return false
+    request(siteId, backfillRequired, refetch)
+    return true
+  }
+
+  function reset(): void {
+    attemptedKeys.clear()
+    error.value = null
+  }
+
+  return { pending, range, percent, error, request, maybeTrigger, reset }
+}

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/_useGscResource.ts

@@ -0,0 +1,114 @@
+// 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/runtime-core'
+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 }
+}