@gscdump/nuxt 0.22.1 → 1.5.1

package/app/composables/useGscTableState.ts

@@ -1,119 +0,0 @@
-// Reactive table state — search, pagination, sort, filter — with optional
-// URL sync. One source of truth across a page so deep-links and
-// back/forward navigation restore exactly what the user was looking at.
-
-export interface GscSortState {
-  column: string
-  direction: 'asc' | 'desc'
-}
-
-export interface UseGscTableStateOptions<TFilter = Record<string, string>> {
-  /** Sync state into the URL query string. Default `true`. */
-  syncUrl?: boolean
-  /** Prefix for query keys (avoids collisions when multiple tables share a page). */
-  prefix?: string
-  defaultPage?: number
-  defaultPageSize?: number
-  defaultQ?: string
-  defaultSort?: GscSortState | null
-  defaultFilter?: TFilter
-}
-
-export interface UseGscTableStateReturn<TFilter = Record<string, string>> {
-  q: Ref<string>
-  page: Ref<number>
-  pageSize: Ref<number>
-  sort: Ref<GscSortState | null>
-  filter: Ref<TFilter>
-  reset: () => void
-  /** Toggle a column's sort: desc → asc → off. */
-  toggleSort: (column: string) => void
-}
-
-export function useGscTableState<TFilter extends Record<string, any> = Record<string, string>>(
-  opts: UseGscTableStateOptions<TFilter> = {},
-): UseGscTableStateReturn<TFilter> {
-  const syncUrl = opts.syncUrl ?? true
-  const prefix = opts.prefix ?? ''
-  const k = (name: string): string => (prefix ? `${prefix}_${name}` : name)
-
-  const defaultPage = opts.defaultPage ?? 1
-  const defaultPageSize = opts.defaultPageSize ?? 25
-  const defaultQ = opts.defaultQ ?? ''
-  const defaultSort = opts.defaultSort ?? null
-  const defaultFilter = (opts.defaultFilter ?? {}) as TFilter
-
-  const route = syncUrl ? useRoute() : null
-  const router = syncUrl ? useRouter() : null
-
-  function readQuery<T>(key: string, fallback: T, parse: (raw: string) => T): T {
-    if (!route)
-      return fallback
-    const raw = route.query[k(key)]
-    if (raw == null)
-      return fallback
-    return parse(Array.isArray(raw) ? (raw[0] ?? '') : String(raw))
-  }
-
-  function writeQuery(key: string, value: string | null): void {
-    if (!route || !router)
-      return
-    const query = { ...route.query }
-    const fullKey = k(key)
-    if (value == null || value === '')
-      delete query[fullKey]
-    else
-      query[fullKey] = value
-    void router.replace({ query })
-  }
-
-  const q = ref(readQuery('q', defaultQ, s => s))
-  const page = ref(readQuery('page', defaultPage, s => Number(s) || defaultPage))
-  const pageSize = ref(readQuery('pageSize', defaultPageSize, s => Number(s) || defaultPageSize))
-  const sort = ref<GscSortState | null>(readQuery('sort', defaultSort, parseSort))
-  const filter = ref(defaultFilter) as Ref<TFilter>
-
-  if (syncUrl) {
-    watch(q, v => writeQuery('q', v || null))
-    watch(page, v => writeQuery('page', v === defaultPage ? null : String(v)))
-    watch(pageSize, v => writeQuery('pageSize', v === defaultPageSize ? null : String(v)))
-    watch(sort, v => writeQuery('sort', serializeSort(v)))
-  }
-
-  // Reset page when q/filter changes (standard table UX).
-  watch([q, filter], () => {
-    page.value = defaultPage
-  }, { deep: true })
-
-  function reset(): void {
-    q.value = defaultQ
-    page.value = defaultPage
-    pageSize.value = defaultPageSize
-    sort.value = defaultSort
-    filter.value = defaultFilter
-  }
-
-  function toggleSort(column: string): void {
-    const cur = sort.value
-    if (!cur || cur.column !== column) {
-      sort.value = { column, direction: 'desc' }
-      return
-    }
-    sort.value = cur.direction === 'desc' ? { column, direction: 'asc' } : null
-  }
-
-  return { q, page, pageSize, sort, filter, reset, toggleSort }
-}
-
-function serializeSort(s: GscSortState | null): string | null {
-  return s ? `${s.column}:${s.direction}` : null
-}
-
-function parseSort(raw: string): GscSortState | null {
-  if (!raw)
-    return null
-  const [column, direction] = raw.split(':')
-  if (!column || (direction !== 'asc' && direction !== 'desc'))
-    return null
-  return { column, direction }
-}

package/app/plugins/analytics.ts

@@ -1,57 +0,0 @@
-// Layer-wide DI: analytics context, query dispatcher, fetch instance, and
-// analytics client. Each value is defined as a lazy getter on the NuxtApp so
-// non-GSC routes pay zero cost and host plugins (e.g. route-gated setGscAuth)
-// can run before any of these are materialized. Hosts override by reassigning
-// the same `$xxx` key from a later plugin (Nuxt's provide uses configurable
-// defineProperty, so the last writer wins).
-
-import type { AnalyticsClient, AnalyticsFetch } from '@gscdump/sdk'
-import type { $Fetch } from 'ofetch'
-import type { GscQueryDispatcher } from '../composables/_useGscQueryDispatcher'
-import type { GscAnalyticsContext } from '../composables/useGscAnalytics'
-import { createAnalyticsClient } from '@gscdump/sdk'
-import { createDefaultGscQueryDispatcher } from '../composables/_useGscQueryDispatcher'
-import { createGscAnalyticsContext } from '../composables/useGscAnalytics'
-import { useGscAnalyticsConfig } from '../composables/useGscAnalyticsConfig'
-import { resolveGscAuthHeaders } from '../composables/useGscAuth'
-import { createGscFetch } from '../utils/gsc-fetch'
-
-export default defineNuxtPlugin((nuxtApp) => {
-  let _ctx: GscAnalyticsContext | undefined
-  let _dispatcher: GscQueryDispatcher | undefined
-  let _fetch: $Fetch | undefined
-  let _client: AnalyticsClient | undefined
-
-  function getFetch(): $Fetch {
-    if (!_fetch) {
-      const cfg = useGscAnalyticsConfig()
-      _fetch = createGscFetch(cfg.apiBase, cfg.toastErrors)
-    }
-    return _fetch
-  }
-
-  const lazy: Record<string, () => unknown> = {
-    $gscAnalytics: () => _ctx ??= createGscAnalyticsContext(),
-    $gscQueryDispatcher: () => _dispatcher ??= createDefaultGscQueryDispatcher(),
-    $gscFetch: () => getFetch(),
-    $gscAnalyticsClient: () => {
-      if (!_client) {
-        const cfg = useGscAnalyticsConfig()
-        _client = createAnalyticsClient({
-          apiBase: cfg.apiBase || '',
-          fetch: getFetch() as unknown as AnalyticsFetch,
-          headers: () => new Headers(resolveGscAuthHeaders()),
-        })
-      }
-      return _client
-    },
-  }
-
-  for (const [key, factory] of Object.entries(lazy)) {
-    Object.defineProperty(nuxtApp, key, {
-      get: factory,
-      configurable: true,
-      enumerable: true,
-    })
-  }
-})

package/app/utils/anonymization.ts

@@ -1,24 +0,0 @@
-// GSC anonymises queries on a per-day basis; summing query-grained rows
-// undercounts page impressions by this amount. Callers render a banner when
-// the trailing-28d weighted average crosses a threshold.
-//
-// Impression-weighted average matches what the user experiences when they
-// open the dashboard — daily % alone is noisy on low-traffic days.
-
-export interface DailyAnonInput {
-  impressions: number
-  anonymizedImpressionsPct: number
-}
-
-export function weightedAnonPct(days: readonly DailyAnonInput[] | null | undefined, window = 28): number | null {
-  if (!days?.length)
-    return null
-  const trailing = days.slice(-window)
-  let totalImpressions = 0
-  let weighted = 0
-  for (const d of trailing) {
-    totalImpressions += d.impressions
-    weighted += d.impressions * d.anonymizedImpressionsPct
-  }
-  return totalImpressions > 0 ? weighted / totalImpressions : null
-}

package/app/utils/country-names.ts

@@ -1,56 +0,0 @@
-export const COUNTRY_NAMES: Record<string, string> = {
-  US: 'United States',
-  GB: 'United Kingdom',
-  DE: 'Germany',
-  FR: 'France',
-  CA: 'Canada',
-  AU: 'Australia',
-  IN: 'India',
-  BR: 'Brazil',
-  JP: 'Japan',
-  IT: 'Italy',
-  ES: 'Spain',
-  NL: 'Netherlands',
-  SE: 'Sweden',
-  CH: 'Switzerland',
-  MX: 'Mexico',
-  KR: 'South Korea',
-  RU: 'Russia',
-  PL: 'Poland',
-  BE: 'Belgium',
-  AT: 'Austria',
-  NO: 'Norway',
-  DK: 'Denmark',
-  FI: 'Finland',
-  PT: 'Portugal',
-  IE: 'Ireland',
-  NZ: 'New Zealand',
-  SG: 'Singapore',
-  HK: 'Hong Kong',
-  TW: 'Taiwan',
-  IL: 'Israel',
-  ZA: 'South Africa',
-  AR: 'Argentina',
-  CL: 'Chile',
-  CO: 'Colombia',
-  TH: 'Thailand',
-  PH: 'Philippines',
-  MY: 'Malaysia',
-  ID: 'Indonesia',
-  VN: 'Vietnam',
-  TR: 'Turkey',
-  CZ: 'Czech Republic',
-  RO: 'Romania',
-  HU: 'Hungary',
-  GR: 'Greece',
-  UA: 'Ukraine',
-  EG: 'Egypt',
-  NG: 'Nigeria',
-  KE: 'Kenya',
-  PK: 'Pakistan',
-  BD: 'Bangladesh',
-  AE: 'United Arab Emirates',
-  SA: 'Saudi Arabia',
-}
-
-export const countryName = (code: string): string => COUNTRY_NAMES[code] || code

package/app/utils/duckdb-wasm.ts

@@ -1,166 +0,0 @@
-// Shared browser-DuckDB-WASM helpers used by per-site analyzers and the
-// home-page multi-site fanout. Both consumers boot the same WASM bundle and
-// run the same in-memory parquet attach path; OPFS attach lives in the caller
-// because the two lifecycle models (refcounted long-lived vs ephemeral
-// per-run) need different handle ownership.
-
-import type { AsyncDuckDB, AsyncDuckDBConnection } from '@duckdb/duckdb-wasm'
-import type { DuckDBWasmBootResult, OpfsAttachedHandle } from '@gscdump/engine-duckdb-wasm'
-
-/**
- * Boot DuckDB-WASM using the layer's configured bundle base. The dynamic
- * `import('@gscdump/engine-duckdb-wasm')` keeps the WASM bundle out of the
- * SSR build; callers should also gate the call behind `import.meta.client`.
- *
- * The `filesystem` config disables HEAD-request preflight and forces full
- * HTTP reads — Cloudflare Workers strips `Content-Length` on streamed
- * responses, which makes DuckDB's default range-request path 404.
- */
-export async function bootGscDuckDBWasm(bundleBase?: string): Promise<DuckDBWasmBootResult> {
-  const { bootDuckDBWasm } = await import('@gscdump/engine-duckdb-wasm')
-  return bootDuckDBWasm({
-    ...(bundleBase
-      ? {
-          bundles: {
-            mvp: { mainModule: `${bundleBase}/duckdb-mvp.wasm`, mainWorker: `${bundleBase}/duckdb-browser-mvp.worker.js` },
-            eh: { mainModule: `${bundleBase}/duckdb-eh.wasm`, mainWorker: `${bundleBase}/duckdb-browser-eh.worker.js` },
-          },
-        }
-      : {}),
-    config: { filesystem: { reliableHeadRequests: false, allowFullHTTPReads: true } },
-  })
-}
-
-/**
- * Process-wide shared boot. The ~800ms WASM boot is the dominant cost on the
- * warm path (OPFS cache-hit means downloads are skipped); paying it once per
- * session instead of per refresh turns date-range changes / search-type
- * swaps into near-instant updates.
- *
- * Callers that want their own throwaway instance can keep using
- * {@link bootGscDuckDBWasm}; those that want session-wide reuse — the home
- * page fanout and the per-site analyzer — go through this.
- *
- * Browser-only. The `bundleBase` is captured from the first call; subsequent
- * calls reuse the promise and ignore the argument (it's a deployment-wide
- * constant in practice).
- */
-let sharedBootPromise: Promise<DuckDBWasmBootResult> | null = null
-let sharedBootColdMs: number | undefined
-export function sharedGscDuckDBWasm(bundleBase?: string): Promise<DuckDBWasmBootResult> {
-  if (!sharedBootPromise) {
-    if (typeof performance !== 'undefined')
-      performance.mark('gsc:duckdb:boot:start')
-    const start = typeof performance !== 'undefined' ? performance.now() : 0
-    sharedBootPromise = bootGscDuckDBWasm(bundleBase).then((b) => {
-      if (typeof performance !== 'undefined') {
-        sharedBootColdMs = performance.now() - start
-        performance.mark('gsc:duckdb:boot:end')
-      }
-      return b
-    })
-  }
-  else if (typeof performance !== 'undefined') {
-    performance.mark('gsc:duckdb:boot:reuse')
-  }
-  return sharedBootPromise
-}
-
-/** Diagnostics: ms paid for the one-time cold boot, or undefined if not yet booted. */
-export function sharedGscDuckDBWasmColdMs(): number | undefined {
-  return sharedBootColdMs
-}
-
-/**
- * Fetch every URL into a `Uint8Array` in parallel. `onFileFetched` ticks
- * once per successful download. Separate from `registerParquetView` so
- * callers can run fetches outside any connection mutex.
- */
-export async function fetchParquetBuffers(
-  urls: readonly string[],
-  onFileFetched?: () => void,
-): Promise<Uint8Array[]> {
-  return Promise.all(urls.map(async (url) => {
-    const r = await fetch(url, { credentials: 'omit' })
-    if (!r.ok)
-      throw new Error(`GET ${url} failed: ${r.status}`)
-    const buf = new Uint8Array(await r.arrayBuffer())
-    onFileFetched?.()
-    return buf
-  }))
-}
-
-/**
- * Register pre-fetched parquet buffers as virtual files, then build a single
- * view that unions them. `CAST(date AS DATE)` canonicalises the legacy-VARCHAR
- * / new-DATE encodings. File-name uniqueness is the caller's job; pass a
- * `viewName` that already encodes any site/table salt so concurrent attaches
- * across sites don't collide on the DuckDB virtual filesystem. Call under the
- * DuckDB-WASM single-connection mutex.
- */
-export async function registerParquetView(opts: {
-  db: AsyncDuckDB
-  conn: AsyncDuckDBConnection
-  viewName: string
-  buffers: readonly Uint8Array[]
-}): Promise<void> {
-  const { db, conn, viewName, buffers } = opts
-  const fileNames = buffers.map((_, i) => `${viewName}_${i}.parquet`)
-  for (let i = 0; i < buffers.length; i++)
-    await db.registerFileBuffer(fileNames[i]!, buffers[i]!)
-  const fileList = fileNames.map(n => `'${n.replace(/'/g, '\'\'')}'`).join(',')
-  await conn.query(`CREATE OR REPLACE VIEW ${viewName} AS SELECT * REPLACE (CAST(date AS DATE) AS date) FROM read_parquet([${fileList}], union_by_name = true)`)
-}
-
-/**
- * Attach a parquet file set into DuckDB-WASM, preferring the OPFS-backed
- * path (cache-hit skips download) and falling back to in-memory buffers when
- * OPFS is opted out, unavailable, or quota-exhausted.
- *
- * Returns the OPFS handle when the OPFS path succeeded — caller must keep
- * the handle alive and `detach()` on cleanup. Returns `null` when the
- * fallback path was used; nothing to detach. `onFileProgress` ticks once per
- * downloaded file in either path so the caller can drive a progress UI.
- *
- * `withDb` wraps the DDL/file-register calls when the caller serialises
- * against other DuckDB activity (e.g. a shared connection); pass `undefined`
- * when the caller already owns a private connection.
- */
-export async function attachParquetWithFallback(args: {
-  db: AsyncDuckDB
-  conn: AsyncDuckDBConnection
-  viewName: string
-  files: readonly { url: string, bytes: number, contentHash: string }[]
-  version: string
-  useOpfsCache: boolean
-  fetchConcurrency?: number
-  onFileProgress?: () => void
-  withDb?: <T>(fn: () => Promise<T>) => Promise<T>
-}): Promise<OpfsAttachedHandle | null> {
-  const { db, conn, viewName, files, version, useOpfsCache, onFileProgress } = args
-  const lock = args.withDb ?? (<T>(fn: () => Promise<T>) => fn())
-  const fetchConcurrency = args.fetchConcurrency ?? Math.min(files.length, 4)
-
-  if (useOpfsCache) {
-    const { attachOpfsParquetTables } = await import('@gscdump/engine-duckdb-wasm')
-    const handle = await lock(() => attachOpfsParquetTables({
-      db,
-      conn,
-      tables: [{
-        table: viewName,
-        files: files.map(f => ({ url: f.url, bytes: f.bytes, contentHash: f.contentHash })),
-      }],
-      version,
-      fetchConcurrency,
-      onFileProgress,
-    }))
-    if (!handle.degradedTables.includes(viewName))
-      return handle
-    // OPFS quota / failure — fall through to buffer path. Caller's progress
-    // counter restarts; both paths report one tick per fetched file.
-  }
-
-  const buffers = await fetchParquetBuffers(files.map(f => f.url), onFileProgress)
-  await lock(() => registerParquetView({ db, conn, viewName, buffers }))
-  return null
-}

package/app/utils/gsc-constants.ts

@@ -1,10 +0,0 @@
-// Constants shared across GSC-shaped components. Kept as layer exports so
-// consumers import from `#imports` like everything else.
-
-/**
- * Google Search Console data is considered "unstable" for this many days from
- * today (PST). Rows within the window may still shift as GSC finalizes clicks/
- * impressions; charts render those points under a dimmed / striped overlay so
- * users don't misread last-day dips as trends.
- */
-export const GSC_STABLE_LATENCY_DAYS = 3

package/app/utils/gsc-error.ts

@@ -1,58 +0,0 @@
-// Error classification shared by the layer's fetch wrappers and query hooks.
-// Returns a structured status the caller maps to UI (toast, banner, retry, …).
-
-export type GscErrorStatus
-  = | 'auth-missing'
-    | 'rate-limited'
-    | 'network'
-    | 'error'
-
-export interface GscClassifiedError {
-  status: GscErrorStatus
-  /** HTTP status code if the error came from a response, otherwise undefined. */
-  code?: number
-  /** Best-effort human message: server-supplied `message`, then `data.message`, then the error's own message. */
-  message?: string
-  /** Seconds the server suggested waiting (429 with `retryAfter` payload). */
-  retryAfter?: number
-}
-
-export function classifyGscError(e: unknown): GscClassifiedError {
-  const code = (e as { statusCode?: number, status?: number })?.statusCode
-    ?? (e as { status?: number })?.status
-  const message = extractMessage(e)
-
-  if (code === 401 || code === 403)
-    return { status: 'auth-missing', code, message }
-  if (code === 429) {
-    const retry = (e as { data?: { retryAfter?: number } })?.data?.retryAfter
-    return {
-      status: 'rate-limited',
-      code,
-      message,
-      retryAfter: typeof retry === 'number' ? retry : undefined,
-    }
-  }
-  // No code => didn't make it to the server (DNS, CORS, offline, abort).
-  if (code == null && !isAbort(e))
-    return { status: 'network', message }
-
-  return { status: 'error', code, message }
-}
-
-function extractMessage(e: unknown): string | undefined {
-  if (!e || typeof e !== 'object')
-    return undefined
-  const data = (e as { data?: unknown }).data
-  if (data && typeof data === 'object') {
-    const m = (data as { message?: unknown, error?: unknown }).message ?? (data as { error?: unknown }).error
-    if (typeof m === 'string')
-      return m
-  }
-  const m = (e as { message?: unknown }).message
-  return typeof m === 'string' ? m : undefined
-}
-
-function isAbort(e: unknown): boolean {
-  return (e as { name?: string })?.name === 'AbortError'
-}

package/app/utils/gsc-fetch.ts

@@ -1,94 +0,0 @@
-// Configured $fetch instance for the layer's `/api/__gsc/*` calls.
-//
-// When `runtimeConfig.public.analytics.apiBase` is set, requests are routed
-// to that origin (e.g. `https://gscdump.com`). Empty = same-origin, the
-// default for self-hosted deployments (gscdump.com itself).
-//
-// Auth: resolved via `useGscAuth` (host calls `setGscAuth` from a `'pre'`
-// plugin). `apiKey` populates `x-api-key`; `headers` carries any additional
-// auth headers. When no auth is wired, the layer falls back to cookies for
-// same-site / cookie-credentials deployments.
-//
-// Built once per NuxtApp by the layer plugin and provided as `$gscFetch`.
-// `useGscFetch()` is a thin reader; hosts override by providing their own
-// `$gscFetch` from a later plugin.
-
-import type { $Fetch } from 'ofetch'
-import { readGscAuth, resolveGscAuthHeaders } from '../composables/useGscAuth'
-import { classifyGscError } from './gsc-error'
-
-const TOAST_DEDUP_MS = 5000
-
-interface ToastDedup {
-  recent: Map<string, number>
-}
-
-function shouldEmitToast(dedup: ToastDedup, key: string): boolean {
-  const now = Date.now()
-  const last = dedup.recent.get(key) ?? 0
-  if (now - last < TOAST_DEDUP_MS)
-    return false
-  dedup.recent.set(key, now)
-  if (dedup.recent.size > 32) {
-    const oldest = [...dedup.recent.entries()].sort((a, b) => a[1] - b[1])[0]
-    if (oldest)
-      dedup.recent.delete(oldest[0])
-  }
-  return true
-}
-
-function defaultToastTitle(status: string): string {
-  switch (status) {
-    case 'auth-missing': return 'Sign in required'
-    case 'rate-limited': return 'Rate limit exceeded'
-    case 'network': return 'Network error'
-    default: return 'Request failed'
-  }
-}
-
-export function createGscFetch(cfgApiBase: string, toastErrors: boolean): $Fetch {
-  const dedup: ToastDedup = { recent: new Map() }
-  return $fetch.create({
-    onRequest: ({ options }) => {
-      const auth = readGscAuth()
-      const apiBase = cfgApiBase ?? ''
-      const authHeaders = resolveGscAuthHeaders(auth)
-
-      const merged = new Headers(options.headers as HeadersInit | undefined)
-      for (const [k, v] of Object.entries(authHeaders))
-        merged.set(k, v)
-      options.headers = merged
-
-      if (apiBase && typeof options.baseURL !== 'string')
-        options.baseURL = apiBase
-
-      const hasAuth = Object.keys(authHeaders).length > 0
-      if (hasAuth) {
-        if (!options.credentials)
-          options.credentials = 'omit'
-      }
-      else if (apiBase && !options.credentials) {
-        // No explicit auth — fall back to cookies for cross-origin sessions.
-        options.credentials = 'include'
-      }
-    },
-    onResponseError: (ctx) => {
-      if (!toastErrors || !import.meta.client)
-        return
-      const c = classifyGscError(ctx.error ?? ctx.response)
-      const key = `${c.status}:${c.code ?? '-'}:${c.message ?? ''}`
-      if (!shouldEmitToast(dedup, key))
-        return
-      const toast = useToast()
-      toast.add({
-        title: defaultToastTitle(c.status),
-        description: c.message,
-        color: c.status === 'rate-limited' ? 'warning' : 'error',
-      })
-    },
-  }) as unknown as $Fetch
-}
-
-export function useGscFetch(): $Fetch {
-  return useNuxtApp().$gscFetch as $Fetch
-}

package/app/utils/gsc-filters.ts

@@ -1,32 +0,0 @@
-// Re-exports the typed query operators from `gscdump/query` so layer
-// consumers can compose filters without an extra import line. Auto-imported
-// like the layer's other utils.
-//
-// Usage:
-//   const filter = and(
-//     between(date, range.start, range.end),
-//     eq(country, 'usa'),
-//   )
-//
-// Replaces nuxtseo's wire-format `dateFilter` / `andFilter` helpers — both
-// formats coerce to the same shape server-side, so the typed primitives
-// are strictly better.
-
-export {
-  and,
-  between,
-  contains,
-  eq,
-  gt,
-  gte,
-  inArray,
-  like,
-  lt,
-  lte,
-  ne,
-  not,
-  notRegex,
-  or,
-  regex,
-  topLevel,
-} from 'gscdump/query'