@gscdump/nuxt 0.22.1 → 1.5.1

package/README.md

@@ -1,136 +1,21 @@
 # @gscdump/nuxt
 
-[![npm version](https://img.shields.io/npm/v/@gscdump/nuxt?color=yellow)](https://npmjs.com/package/@gscdump/nuxt)
-[![npm downloads](https://img.shields.io/npm/dm/@gscdump/nuxt?color=yellow)](https://npm.chart.dev/@gscdump/nuxt)
-[![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
+Minimal Nuxt integration for gscdump applications.
 
-> Nuxt layer: GSC analytics UI, Nuxt auth/runtime wiring, and DuckDB-WASM integration. It uses `@gscdump/sdk` internally for hosted analytics HTTP reads.
+It owns two stable Nuxt seams:
 
-This package assumes a site is already linked. It does not own partner
-onboarding, registration, lifecycle decisions, token exchange, or webhook
-subscription management. Use `@gscdump/sdk` from the host app for those
-flows, then pass the linked `gscdumpSiteId` into the analytics composables
-here.
+- typed `runtimeConfig.public.analytics` defaults
+- build-time analyzer registry injection as `$gscAnalyzers`
 
-Three consumption modes:
-
-| Mode | Who | What it does |
-| --- | --- | --- |
-| `origin` | gscdump.com | Reads R2 data directly (binding) + DuckDB service binding. Owns the data. |
-| `consumer` | nuxtseo.com | Proxies all reads to an origin over HTTP + an API key. No data locally. |
-| `local` | `examples/nuxt-dashboard` | Reads a `gscdump sync` dump from `GSCDUMP_DATA_DIR`. Offline dev. |
-
-## Install
-
-```bash
-pnpm add @gscdump/nuxt
-```
+Views, authentication, data fetching, server routes, and product fallback
+policy stay in the host application. Browser runtime primitives live in
+`@gscdump/engine-duckdb-wasm`; hosted API access lives in `@gscdump/sdk`.
 
 ```ts
-// nuxt.config.ts
 export default defineNuxtConfig({
-  extends: ['@gscdump/nuxt'],
-  runtimeConfig: {
-    analytics: {
-      mode: 'origin', // or 'consumer' / 'local'
-    },
-  },
-})
-```
-
-## Register an auth provider
-
-```ts
-// server/plugins/register-auth.ts
-export default defineNitroPlugin((nitro) => {
-  nitro.hooks.hook('analytics:register-auth-provider', (register) => {
-    register({
-      resolve: async (event) => {
-        const session = await getUserSession(event)
-        if (!session)
-          return null
-        return { userId: session.user.id, siteIds: session.accessibleSiteIds }
-      },
-    })
-  })
-})
-```
-
-## Data access: which endpoint?
-
-| Need | Endpoint | Client composable |
-| --- | --- | --- |
-| Pre-aggregated widgets (top pages, daily totals) | `GET /api/sites/:siteId/rollup/:id` | `useGscRollup` / `useGscRollups` / `useGscRollupFanout` |
-| Raw rows filtered by dimension/range (`where(eq(page, ...))`) | `POST /api/sites/:siteId/rows` | `useGscRowQuery({ site, state })` |
-| Analyzer result (striking-distance, CTR anomaly, …) | `POST /api/sites/:siteId/analyze` | `useGscAnalyzer(siteId).analyze(...)` |
-
-Rule of thumb: reach for `/rows` + `useGscRowQuery` for detail pages that
-need a freeform slice of the data. Only fall back to `/analyze` when the
-server runs an actual analyzer (anything in the registry); hitting it for
-plain row lookups routes through analyzer-gating logic you don't need.
-
-## Consumer mode (cross-origin)
-
-Used when the Nuxt app authenticating the viewer is not the same origin as
-the data — e.g. nuxtseo.com pro consuming gscdump.com. Two pieces:
-
-1. **Point fetch at the origin**: set `runtimeConfig.public.analytics.apiBase`
-   in `nuxt.config.ts` (or via `NUXT_PUBLIC_ANALYTICS_API_BASE`). Empty =
-   same-origin (the default origin-mode shape).
-
-2. **Hand the layer a per-viewer api key**: register a client plugin that
-   trades the viewer's host session for an api key, then call
-   `setGscFetchHeaders({ 'x-api-key': key })`. The layer's `useGscFetch`
-   attaches the header to every `/api/__gsc/*` call automatically. Browser
-   parquet reads use exact-object URLs minted by the source endpoint; runtime
-   preflights can include this header, while DuckDB-WASM range reads are
-   authorized by the token embedded in each URL.
-
-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 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,
-    }))
+  modules: ['@gscdump/nuxt'],
+  gscdumpAnalytics: {
+    analyzers: '~/gscAnalyzers',
   },
 })
 ```
-
-`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
-`GET /api/partner/users/:userId/lifecycle`, handle webhook or realtime
-invalidation, and decide when a linked site is ready to render. Once it has a
-linked site id, this layer handles query reads and analytics UI only.
-
-### CORS
-
-The origin app (`gscdump.com` or your own) must allow the consumer origin
-on `/api/__gsc/*`, `/api/r2-data/*`, and any host endpoints the helper
-calls. Allow-headers must include `x-api-key`, `Cache-Control`, and `Range`
-(DuckDB-WASM uses partial reads); expose `Content-Range`, `Accept-Ranges`,
-`Content-Length`. Preflight needs to cover `PATCH` for any settings calls.
-
-## Related
-
-- [`@gscdump/sdk`](../sdk) — framework-agnostic hosted API client used by host onboarding code and by this Nuxt layer internally.
-- [`gscdump`](../gscdump) — local package and query builder.
-- [`@gscdump/engine`](../engine) — Storage engine consumed in origin mode.
-- [`@gscdump/engine-duckdb-wasm`](../engine-duckdb-wasm) — DuckDB-WASM browser runtime used by client-side widgets.
-- [`@gscdump/analysis`](../analysis) — Analyzers powering `/analyze` endpoints.
-
-## License
-
-[MIT](../../LICENSE)

package/dist/module.d.mts

@@ -0,0 +1,22 @@
+import { GscdumpAnalyticsRuntimeConfig, GscdumpDefaultEngine, GscdumpRuntimeEnvironment, resolveGscdumpAnalyticsRuntimeConfig } from "./runtime-config.mjs";
+import { NuxtModule } from "@nuxt/schema";
+interface GscdumpNuxtModuleOptions {
+  /**
+   * Nuxt-resolvable module exporting an analyzer array as `ANALYZERS` or
+   * `default`.
+   */
+  analyzers?: string;
+}
+declare module '@nuxt/schema' {
+  interface NuxtConfig {
+    gscdumpAnalytics?: GscdumpNuxtModuleOptions;
+  }
+  interface NuxtOptions {
+    gscdumpAnalytics: GscdumpNuxtModuleOptions;
+  }
+  interface PublicRuntimeConfig {
+    analytics: GscdumpAnalyticsRuntimeConfig;
+  }
+}
+declare const gscdumpNuxtModule: NuxtModule<GscdumpNuxtModuleOptions>;
+export { type GscdumpAnalyticsRuntimeConfig, type GscdumpDefaultEngine, GscdumpNuxtModuleOptions, type GscdumpRuntimeEnvironment, gscdumpNuxtModule as default, resolveGscdumpAnalyticsRuntimeConfig };

package/dist/module.mjs

@@ -0,0 +1,30 @@
+import { resolveGscdumpAnalyticsRuntimeConfig } from "./runtime-config.mjs";
+import process from "node:process";
+import { addPluginTemplate, defineNuxtModule } from "@nuxt/kit";
+const gscdumpNuxtModule = defineNuxtModule({
+	meta: {
+		name: "@gscdump/nuxt",
+		configKey: "gscdumpAnalytics",
+		compatibility: { nuxt: ">=4.0.0" }
+	},
+	defaults: {},
+	setup(options, nuxt) {
+		nuxt.options.runtimeConfig.public.analytics = resolveGscdumpAnalyticsRuntimeConfig(nuxt.options.runtimeConfig.public.analytics, process.env);
+		if (!options.analyzers) return;
+		addPluginTemplate({
+			filename: "gscdump-analyzers.plugin.mjs",
+			getContents: () => [
+				`import { defineNuxtPlugin } from '#app'`,
+				`import * as registry from ${JSON.stringify(options.analyzers)}`,
+				`const analyzers = registry.ANALYZERS ?? registry.default`,
+				`if (!Array.isArray(analyzers))`,
+				`  throw new TypeError('gscdump analyzer registry must export an array')`,
+				`export default defineNuxtPlugin(() => ({`,
+				`  provide: { gscAnalyzers: analyzers },`,
+				`}))`,
+				``
+			].join("\n")
+		});
+	}
+});
+export { gscdumpNuxtModule as default, resolveGscdumpAnalyticsRuntimeConfig };

package/dist/runtime-config.d.mts

@@ -0,0 +1,12 @@
+type GscdumpDefaultEngine = 'auto' | 'client' | 'server';
+interface GscdumpAnalyticsRuntimeConfig {
+  apiBase: string;
+  duckdbBundleBase: string;
+  duckdbThreadBundleBase: string;
+  timezone: string;
+  toastErrors: boolean;
+  defaultEngine: GscdumpDefaultEngine;
+}
+type GscdumpRuntimeEnvironment = Readonly<Record<string, string | undefined>>;
+declare function resolveGscdumpAnalyticsRuntimeConfig(configured: Partial<GscdumpAnalyticsRuntimeConfig> | undefined, environment: GscdumpRuntimeEnvironment): GscdumpAnalyticsRuntimeConfig;
+export { GscdumpAnalyticsRuntimeConfig, GscdumpDefaultEngine, GscdumpRuntimeEnvironment, resolveGscdumpAnalyticsRuntimeConfig };

package/dist/runtime-config.mjs

@@ -0,0 +1,27 @@
+const DEFAULT_ENGINES = /* @__PURE__ */ new Set([
+	"auto",
+	"client",
+	"server"
+]);
+function defaultEngine(value) {
+	return value && DEFAULT_ENGINES.has(value) ? value : "auto";
+}
+function resolveGscdumpAnalyticsRuntimeConfig(configured, environment) {
+	const defaults = {
+		apiBase: environment.GSCDUMP_ANALYTICS_API_BASE ?? "",
+		duckdbBundleBase: environment.GSCDUMP_DUCKDB_BUNDLE_BASE ?? "",
+		duckdbThreadBundleBase: environment.GSCDUMP_DUCKDB_THREAD_BUNDLE_BASE ?? "",
+		timezone: environment.GSCDUMP_ANALYTICS_TIMEZONE ?? "",
+		toastErrors: environment.GSCDUMP_ANALYTICS_TOAST_ERRORS === "true",
+		defaultEngine: defaultEngine(environment.GSCDUMP_ANALYTICS_DEFAULT_ENGINE)
+	};
+	return {
+		apiBase: configured?.apiBase ?? defaults.apiBase,
+		duckdbBundleBase: configured?.duckdbBundleBase ?? defaults.duckdbBundleBase,
+		duckdbThreadBundleBase: configured?.duckdbThreadBundleBase ?? defaults.duckdbThreadBundleBase,
+		timezone: configured?.timezone ?? defaults.timezone,
+		toastErrors: configured?.toastErrors ?? defaults.toastErrors,
+		defaultEngine: configured?.defaultEngine ?? defaults.defaultEngine
+	};
+}
+export { resolveGscdumpAnalyticsRuntimeConfig };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@gscdump/nuxt",
   "type": "module",
-  "version": "0.22.1",
-  "description": "Nuxt layer: GSC analytics UI + DuckDB-WASM integration. Frontend-only; server primitives live in @gscdump/analysis, @gscdump/engine-sqlite, @gscdump/cloudflare, and host apps.",
+  "version": "1.5.1",
+  "description": "Minimal Nuxt integration for gscdump analytics runtime config and analyzer registries.",
   "author": {
     "name": "Harlan Wilton",
     "email": "harlan@harlanzw.com",
@@ -17,60 +17,41 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./types.ts",
-      "import": "./nuxt.config.ts",
-      "default": "./nuxt.config.ts"
+      "types": "./dist/module.d.mts",
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
     },
-    "./types": {
-      "types": "./types.ts",
-      "import": "./types.ts",
-      "default": "./types.ts"
-    },
-    "./module": {
-      "types": "./module.ts",
-      "import": "./module.ts",
-      "default": "./module.ts"
+    "./runtime-config": {
+      "types": "./dist/runtime-config.d.mts",
+      "import": "./dist/runtime-config.mjs",
+      "default": "./dist/runtime-config.mjs"
     }
   },
-  "main": "./nuxt.config.ts",
-  "types": "./types.ts",
+  "main": "./dist/module.mjs",
+  "types": "./dist/module.d.mts",
   "files": [
     "README.md",
-    "app",
-    "module.ts",
-    "nuxt.config.ts",
-    "types.ts"
+    "dist"
   ],
+  "engines": {
+    "node": ">=22"
+  },
   "peerDependencies": {
-    "nuxt": "^4.4.6",
-    "vue": "^3.5.34"
+    "nuxt": "^4.5.0"
   },
   "dependencies": {
-    "@duckdb/duckdb-wasm": "^1.32.0",
-    "@nuxt/ui": "^4.8.0",
-    "@unovis/ts": "^1.6.5",
-    "@unovis/vue": "^1.6.5",
-    "@vueuse/core": "^14.3.0",
-    "@vueuse/nuxt": "^14.3.0",
-    "defu": "^6.1.7",
-    "nuxt-use-query": "^0.1.0",
-    "ofetch": "^1.5.1",
-    "tailwindcss": "^4.3.0",
-    "@gscdump/analysis": "0.22.1",
-    "@gscdump/contracts": "0.22.1",
-    "@gscdump/engine": "0.22.1",
-    "@gscdump/engine-duckdb-wasm": "0.22.1",
-    "@gscdump/sdk": "0.22.1",
-    "gscdump": "0.22.1"
+    "@nuxt/kit": "4.5.0",
+    "@nuxt/schema": "4.5.0"
   },
   "devDependencies": {
-    "@nuxt/kit": "^4.4.6",
-    "nuxt": "^4.4.6",
-    "typescript": "^6.0.3",
-    "vue": "^3.5.34"
+    "nuxt": "^4.5.0",
+    "obuild": "^0.4.38",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "nuxt prepare",
-    "typecheck": "nuxt typecheck"
+    "build": "obuild",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
   }
 }

package/app/assets/css/main.css

@@ -1,2 +0,0 @@
-@import "tailwindcss";
-@import "@nuxt/ui";

package/app/components/GscAnalyzerPanel.vue

@@ -1,94 +0,0 @@
-<script setup lang="ts">
-// Unified shell for `/analyze` analyzer tabs. Drives the chrome that 11
-// per-analyzer sections used to repeat: stat tiles, body, caption. The body
-// component + tile projection + caption come from `def.capabilities.panel`;
-// the shell owns the loading/error/empty gating unless `panel.ownsLifecycle`
-// is set (pipeline panels manage their own phase state internally).
-
-import type {
-  GscAnalyzerDefinition,
-  GscAnalyzerPanelResult,
-} from '../composables/useGscAnalyzerDefs'
-
-interface Props {
-  def: GscAnalyzerDefinition
-  rows: unknown[]
-  meta: Record<string, unknown> | null
-  queryMs?: number | null
-  loading?: boolean
-  error?: string | null
-  /** Forwarded to the body component as `range`. Optional. */
-  range?: { start: string, end: string } | null
-}
-
-const props = defineProps<Props>()
-
-const panel = computed(() => props.def.capabilities?.panel)
-
-const tiles = computed(() => {
-  const p = panel.value
-  if (!p?.summarize)
-    return []
-  const result: GscAnalyzerPanelResult = {
-    results: props.rows,
-    meta: props.meta ?? {},
-    queryMs: props.queryMs ?? null,
-  }
-  return p.summarize(result)
-})
-
-const showBody = computed(() => {
-  if (!panel.value)
-    return false
-  if (panel.value.ownsLifecycle)
-    return true
-  return !props.loading && !props.error && props.rows.length > 0
-})
-
-const bodyProps = computed(() => ({
-  rows: props.rows,
-  meta: props.meta ?? {},
-  range: props.range ?? null,
-}))
-</script>
-
-<template>
-  <section v-if="panel" class="gsc-analyzer-panel">
-    <div v-if="tiles.length > 0" class="gsc-analyzer-panel__tiles">
-      <div v-for="(t, i) in tiles" :key="`${t.label}-${i}`" class="gsc-analyzer-panel__tile">
-        <span class="gsc-analyzer-panel__tile-label">{{ t.label }}</span>
-        <span class="gsc-analyzer-panel__tile-value" :style="t.valueColor ? { color: t.valueColor } : undefined">{{ t.value }}</span>
-      </div>
-    </div>
-
-    <template v-if="!panel.ownsLifecycle">
-      <div v-if="error" class="gsc-analyzer-panel__error">
-        {{ error }}
-      </div>
-      <div v-else-if="loading" class="gsc-analyzer-panel__loading">
-        Running analyzer…
-      </div>
-      <div v-else-if="rows.length === 0" class="gsc-analyzer-panel__empty">
-        No rows.
-      </div>
-    </template>
-
-    <component :is="panel.component" v-if="showBody" v-bind="bodyProps" />
-
-    <p v-if="panel.caption" class="gsc-analyzer-panel__caption">
-      <slot name="caption">{{ panel.caption }}</slot>
-    </p>
-  </section>
-</template>
-
-<style scoped>
-.gsc-analyzer-panel { background: #fff; border: 1px solid #ececef; border-top: 0; border-radius: 0 0 6px 6px; padding: 1rem 1rem 0.9rem; }
-.gsc-analyzer-panel__tiles { display: flex; gap: 1.5rem; flex-wrap: wrap; margin-bottom: 0.85rem; padding: 0 0.15rem; }
-.gsc-analyzer-panel__tile { display: flex; flex-direction: column; gap: 0.1rem; }
-.gsc-analyzer-panel__tile-label { font-size: 0.66rem; letter-spacing: 0.08em; text-transform: uppercase; color: #888; }
-.gsc-analyzer-panel__tile-value { font-size: 1.3rem; font-weight: 600; color: #1d1d1f; font-variant-numeric: tabular-nums; }
-.gsc-analyzer-panel__caption { margin: 0.8rem 0 0; font-size: 0.78rem; color: #666; font-style: italic; text-align: center; }
-.gsc-analyzer-panel__caption :deep(code) { background: #f0f0f3; padding: 0.05rem 0.3rem; border-radius: 3px; font-size: 0.74rem; color: #4c3ca0; }
-.gsc-analyzer-panel__error { padding: 1rem 1.25rem; color: #c00; background: #fff5f5; font-family: ui-monospace, monospace; font-size: 0.82rem; white-space: pre-wrap; }
-.gsc-analyzer-panel__loading, .gsc-analyzer-panel__empty { padding: 2.5rem; text-align: center; color: var(--ui-text-dimmed); font-size: 0.9rem; }
-</style>

package/app/components/GscAnonymizationBanner.vue

@@ -1,46 +0,0 @@
-<script setup lang="ts">
-// Surfaces the trailing-28d impression-weighted anonymization % from the
-// daily_totals rollup. GSC anonymises queries for low-volume or sensitive
-// terms, so query-grained breakdowns (keywords, pages-by-query) undercount
-// impressions by this amount. Hidden when data isn't ready or the gap is
-// negligible (<1%).
-
-import { useGscRollup } from '../composables/useGscRollup'
-import { weightedAnonPct } from '../utils/anonymization'
-
-interface DailyTotal {
-  impressions: number
-  anonymizedImpressionsPct: number
-}
-
-const { siteIdentifier } = defineProps<{
-  siteIdentifier: string | null | undefined
-}>()
-
-const { data: daily } = useGscRollup<DailyTotal[]>(() => siteIdentifier ?? null, 'daily_totals')
-
-const formatted = computed(() => {
-  if (!siteIdentifier)
-    return null
-  const pct = weightedAnonPct(daily.value)
-  if (pct == null)
-    return null
-  const percent = pct * 100
-  if (percent < 1)
-    return null
-  return percent.toFixed(percent < 10 ? 1 : 0)
-})
-</script>
-
-<template>
-  <div
-    v-if="formatted"
-    class="flex items-start gap-2 border border-amber-500/30 bg-amber-500/5 px-3 py-2 text-xs text-amber-200/90"
-  >
-    <UIcon name="i-ph-info" class="mt-0.5 flex-shrink-0 text-amber-400" />
-    <div>
-      <span class="font-semibold">~{{ formatted }}% of impressions are anonymised by Google.</span>
-      Query-grained breakdowns below exclude these, so the sum won't match site-level totals.
-    </div>
-  </div>
-</template>