ahoy_analytics 0.1.0

data/app/frontend/entrypoints/analytics-ui.tsx

@@ -0,0 +1,26 @@
+import '@vitejs/plugin-react/preamble'
+import '@/entrypoints/analytics.css'
+import { createInertiaApp } from '@inertiajs/react'
+import { createElement } from 'react'
+import type { ComponentType } from 'react'
+import { createRoot } from 'react-dom/client'
+
+type ResolvedComponent = {
+  default: ComponentType
+}
+
+createInertiaApp({
+  resolve: (name) => {
+    const pages = import.meta.glob<ResolvedComponent>('../pages/**/*.tsx')
+    const loader = pages[`../pages/${name}.tsx`]
+    if (!loader) {
+      console.error(`Missing Inertia page component: '${name}.tsx'`)
+      return Promise.reject(new Error(`Missing Inertia page component: '${name}.tsx'`))
+    }
+    return loader()
+  },
+  setup({ el, App, props }) {
+    if (!el) return
+    createRoot(el).render(createElement(App, props))
+  }
+})

data/app/frontend/entrypoints/analytics.css

@@ -0,0 +1,77 @@
+@import "../styles/shared.css";
+
+/* Admin Panel - Theme Styles */
+/* Following shadcn/ui theming convention with CSS variables */
+/* Color scheme adapted from public.css dark theme for brand consistency */
+/* Note: Tailwind CSS is imported only once in application.css */
+
+/* Admin theme - applied globally when admin.css is loaded */
+:root {
+    /* Dark theme by default for admin */
+    color-scheme: dark;
+  
+    /* Base radius - matching public for consistency */
+    --radius: 0.625rem;
+  
+    /* Core colors - matching public.css dark theme palette */
+    --background: oklch(0.18 0.015 265);              /* Same as public dark background */
+    --foreground: oklch(0.92 0.02 265);               /* Same as public dark foreground */
+  
+    /* Card colors - elevated surface for better hierarchy */
+    --card: oklch(0.24 0.01 265);                     /* Elevated from background */
+    --card-foreground: oklch(0.92 0.02 265);          /* Consistent foreground */
+  
+    /* Popover/Dropdown - more elevated for better contrast */
+    --popover: oklch(0.30 0.015 265);                 /* More elevated than card */
+    --popover-foreground: oklch(0.95 0.02 265);       /* Brighter text for contrast */
+  
+    /* Primary - golden accent from public.css */
+    --primary: oklch(0.78 0.18 84);                   /* Golden primary from public */
+    --primary-foreground: oklch(0.22 0.02 265);       /* Dark text on golden */
+  
+    /* Secondary - subtle elevated surface */
+    --secondary: oklch(0.28 0.01 265);                /* Slightly elevated */
+    --secondary-foreground: oklch(0.90 0.015 265);    /* Bright foreground */
+  
+    /* Muted - for less prominent elements */
+    --muted: oklch(0.32 0.009 265);                   /* Subtle elevation */
+    --muted-foreground: oklch(0.65 0.018 265);        /* Dimmed text */
+  
+    /* Accent (UI hover/background) — keep neutral like shadcn default */
+    --accent: oklch(0.36 0.015 265);
+    --accent-foreground: oklch(0.95 0.02 265);
+
+    /* Data accent (analytics visuals only) */
+    --data-accent: oklch(0.75 0.13 210);              /* cyan-400 vibe */
+  
+    /* Destructive - error/danger state */
+    --destructive: oklch(0.56 0.25 26);               /* Red tone from public */
+    --destructive-foreground: oklch(0.95 0.02 265);   /* Bright text */
+  
+    /* Form elements and borders */
+    --border: oklch(0.38 0.015 265);                  /* More visible border */
+    --input: oklch(0.95 0.005 265);                   /* Very light for 30% opacity in dark mode */
+    --ring: oklch(0.78 0.15 90);                      /* Golden ring focus */
+  
+    /* Chart palette (analytics) — first tone uses data accent */
+    --chart-1: var(--data-accent);
+    --chart-2: oklch(0.72 0.12 230);
+    --chart-3: oklch(0.70 0.12 200);
+    --chart-4: oklch(0.76 0.10 220);
+    --chart-5: oklch(0.68 0.10 240);
+  
+    /* Sidebar - consistent with card styling */
+    --sidebar: oklch(0.24 0.01 265);                  /* Same as card */
+    --sidebar-foreground: oklch(0.90 0.02 265);       /* Slightly dimmed */
+    --sidebar-primary: var(--primary);                /* Golden primary */
+    --sidebar-primary-foreground: var(--primary-foreground);
+    --sidebar-accent: oklch(0.32 0.015 265);          /* Hover state */
+    --sidebar-accent-foreground: oklch(0.95 0.02 265); /* Bright on hover */
+    --sidebar-border: oklch(0.32 0.01 265);           /* Subtle border */
+    --sidebar-ring: var(--ring);                      /* Same ring color */
+  }
+  
+  /* Since admin.css is only loaded for admin pages, these variables
+     become the default for everything including portaled content like
+     dropdowns. The Button component has a "golden" variant that matches
+     the public.css 3D button style systematically. */

data/app/frontend/layouts/analytics-layout.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react'
+
+import { cn } from '@/lib/utils'
+
+type AnalyticsLayoutProps = {
+  children: ReactNode
+  fullBleed?: boolean
+  className?: string
+}
+
+export default function AnalyticsLayout({
+  children,
+  fullBleed = false,
+  className
+}: AnalyticsLayoutProps) {
+  return (
+    <div className={cn("min-h-dvh bg-background text-foreground", fullBleed && "flex flex-col")}>
+      <main
+        className={cn(
+          fullBleed ? 'flex flex-1 flex-col min-h-dvh' : 'mx-auto w-full max-w-[1400px] px-4 py-6 lg:px-8',
+          className
+        )}
+      >
+        {children}
+      </main>
+    </div>
+  )
+}

data/app/frontend/lib/cable.ts

@@ -0,0 +1,13 @@
+import * as ActionCable from '@rails/actioncable'
+
+let consumer: ActionCable.Cable | null = null
+
+export function getConsumer() {
+  if (!consumer) {
+    const cablePath = (window as any)?.AhoyAnalytics?.cablePath || '/cable'
+    consumer = ActionCable.createConsumer(cablePath)
+  }
+  return consumer
+}
+
+export type Subscription = ActionCable.Channel

data/app/frontend/lib/geocode.ts

@@ -0,0 +1,65 @@
+export type GeocodeResult = { name: string; lat: number; lng: number }
+export type GeocodeOptions = {
+  countryCodes?: string[]
+  biasLng?: number // hemisphere bias around this longitude (degrees)
+  biasWidthDeg?: number // width of bias viewbox in degrees (default ~160)
+  limit?: number
+  placeTypes?: string[] // whitelist of Nominatim addresstype/type when category==='place'
+}
+
+// Simple OSS geocoder (OpenStreetMap Nominatim). For production, respect usage policy.
+export async function geocodeOsm(query: string, optsOrSignal?: GeocodeOptions | AbortSignal, maybeSignal?: AbortSignal): Promise<GeocodeResult[]> {
+  const opts: GeocodeOptions | undefined = optsOrSignal instanceof AbortSignal ? undefined : optsOrSignal
+  const signal: AbortSignal | undefined = (optsOrSignal instanceof AbortSignal ? optsOrSignal : maybeSignal) || undefined
+
+  const url = new URL('https://nominatim.openstreetmap.org/search')
+  url.searchParams.set('format', 'jsonv2')
+  url.searchParams.set('q', query)
+  url.searchParams.set('limit', String(opts?.limit ?? 5))
+  // Identify requests per Nominatim usage policy. In browsers we cannot set
+  // a custom User-Agent header, so provide a contact email in the query.
+  // See: https://operations.osmfoundation.org/policies/nominatim/
+  const email = (window as any)?.AhoyAnalytics?.geocodeEmail
+  if (email) url.searchParams.set('email', email)
+  if (opts?.countryCodes?.length) {
+    url.searchParams.set('countrycodes', opts.countryCodes.join(','))
+  }
+  // Bias to current hemisphere via a wide viewbox centered on current longitude
+  if (typeof opts?.biasLng === 'number') {
+    const width = Math.max(30, Math.min(180, opts.biasWidthDeg ?? 160))
+    const left = normalizeLng(opts.biasLng - width / 2)
+    const right = normalizeLng(opts.biasLng + width / 2)
+    // If the box would cross the antimeridian, skip viewbox to avoid invalid l>r
+    if (left < right) {
+      // Use almost-full latitude to cover the hemisphere; avoid +/-90 edge cases
+      url.searchParams.set('viewbox', `${left},${85},${right},${-85}`)
+      // Do not set bounded=1; viewbox here is a boost, not a hard filter
+    }
+  }
+  const res = await fetch(url.toString(), {
+    headers: { 'Accept-Language': navigator.language || 'en' },
+    method: 'GET',
+    signal
+  })
+  if (!res.ok) return []
+  const data = await res.json()
+  let rows: any[] = Array.isArray(data) ? data : []
+  // Prefer place results with common city/region/country-like types
+  const defaultPlaceTypes = opts?.placeTypes ?? [
+    'city','town','village','hamlet','suburb','locality',
+    'municipality','borough','county','state','region','province','country'
+  ]
+  const placeRows = rows.filter((d) => d && d.category === 'place' && defaultPlaceTypes.includes(d.type || d.addresstype))
+  if (placeRows.length) rows = placeRows
+  return rows.map((d: any) => ({
+    name: d.display_name as string,
+    lat: parseFloat(d.lat),
+    lng: parseFloat(d.lon)
+  }))
+}
+
+function normalizeLng(lng: number) {
+  let x = ((lng + 180) % 360 + 360) % 360 - 180
+  if (x === -180) x = 180
+  return x
+}

data/app/frontend/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

data/app/frontend/pages/admin/analytics/api.ts

@@ -0,0 +1,221 @@
+import type {
+  AnalyticsQuery,
+  BehaviorsPayload,
+  DevicesPayload,
+  ListPayload,
+  MainGraphPayload,
+  MapPayload,
+  TopStatsPayload
+} from './types'
+import { analyticsPath } from './lib/base-path'
+
+// --- URL param helpers (Plausible-style f/l scheme) ---
+const NOT_URL_ENCODED_CHARACTERS = ':/'
+
+function encodeURIComponentPermissive(input: string, permittedCharacters: string): string {
+  let result = encodeURIComponent(input)
+  for (const ch of permittedCharacters) {
+    const enc = encodeURIComponent(ch)
+    if (enc !== ch) {
+      // Replace all occurrences without using replaceAll (ES2021)
+      result = result.split(enc).join(ch)
+    }
+  }
+  return result
+}
+
+function serializeFilterEntry(operator: string, key: string, value: string) {
+  // f=<operator>,<dimension>,<clause>
+  const op = encodeURIComponentPermissive(operator, NOT_URL_ENCODED_CHARACTERS)
+  const dim = encodeURIComponentPermissive(key, NOT_URL_ENCODED_CHARACTERS)
+  const clause = encodeURIComponentPermissive(value, NOT_URL_ENCODED_CHARACTERS)
+  return `f=${op},${dim},${clause}`
+}
+
+function serializeLabelEntry(key: string, label: string) {
+  const k = encodeURIComponentPermissive(key, NOT_URL_ENCODED_CHARACTERS)
+  const v = encodeURIComponentPermissive(label, NOT_URL_ENCODED_CHARACTERS)
+  return `l=${k},${v}`
+}
+
+export function buildQueryParams(query: AnalyticsQuery, extras: Record<string, unknown> = {}) {
+  const pieces: string[] = []
+  const merged: Record<string, unknown> = { ...query, ...extras }
+
+  if (merged.period) pieces.push(`period=${encodeURIComponent(String(merged.period))}`)
+  if (merged.comparison) pieces.push(`comparison=${encodeURIComponent(String(merged.comparison))}`)
+  if (merged.metric) pieces.push(`metric=${encodeURIComponent(String(merged.metric))}`)
+  if (merged.interval) pieces.push(`interval=${encodeURIComponent(String(merged.interval))}`)
+  if (merged.mode) pieces.push(`mode=${encodeURIComponent(String(merged.mode))}`)
+  if (merged.funnel) pieces.push(`funnel=${encodeURIComponent(String(merged.funnel))}`)
+  if (merged.withImported) pieces.push(`with_imported=${encodeURIComponent(String(merged.withImported))}`)
+  if ((merged as any).dialog) pieces.push(`dialog=${encodeURIComponent(String((merged as any).dialog))}`)
+  if ((merged as any).date) pieces.push(`date=${encodeURIComponent(String((merged as any).date))}`)
+  if ((merged as any).from) pieces.push(`from=${encodeURIComponent(String((merged as any).from))}`)
+  if ((merged as any).to) pieces.push(`to=${encodeURIComponent(String((merged as any).to))}`)
+  if (merged.comparison) {
+    if ((merged as any).compareFrom) pieces.push(`compare_from=${encodeURIComponent(String((merged as any).compareFrom))}`)
+    if ((merged as any).compareTo) pieces.push(`compare_to=${encodeURIComponent(String((merged as any).compareTo))}`)
+    if ((merged as any).matchDayOfWeek != null) pieces.push(`match_day_of_week=${encodeURIComponent(String((merged as any).matchDayOfWeek))}`)
+  }
+
+  const filters = (merged.filters as AnalyticsQuery['filters']) || {}
+  for (const [key, value] of Object.entries(filters)) {
+    if (value == null || value === '') continue
+    pieces.push(serializeFilterEntry('is', key, String(value)))
+  }
+
+  // Advanced filters (is_not / contains) — append as repeated f entries
+  const advanced = (merged.advancedFilters as AnalyticsQuery['advancedFilters']) || []
+  for (const entry of advanced) {
+    if (!Array.isArray(entry) || entry.length < 3) continue
+    const [op, dim, clause] = entry
+    if (!op || !dim || clause == null) continue
+    pieces.push(serializeFilterEntry(String(op), String(dim), String(clause)))
+  }
+
+  const labels = (merged.labels as AnalyticsQuery['labels']) || {}
+  const filtersObj = (merged.filters as AnalyticsQuery['filters']) || {}
+  for (const [k, v] of Object.entries(labels)) {
+    if (!v) continue
+    // Skip numeric label keys (e.g., city ID) — backend maps them to dimension labels.
+    if (/^\d+$/.test(k)) continue
+    // Only emit a label when there's a corresponding filter present.
+    const hasFilter = Object.prototype.hasOwnProperty.call(filtersObj, k)
+    if (!hasFilter) continue
+    // Avoid duplicate when label equals the filter value (e.g., city "Mumbai").
+    const filterVal = (filtersObj as any)[k]
+    if (String(filterVal) === String(v)) continue
+    pieces.push(serializeLabelEntry(k, String(v)))
+  }
+
+  // Extras (pagination/search/sort) remain standard encoding
+  for (const [k, v] of Object.entries(extras)) {
+    if (v == null) continue
+    if (k === 'order_by' && typeof v !== 'string') {
+      pieces.push(`${encodeURIComponent(k)}=${encodeURIComponent(JSON.stringify(v))}`)
+    } else {
+      pieces.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+    }
+  }
+
+  // Final dedup (idempotent URL): remove any accidental duplicates while preserving order
+  const seen = new Set<string>()
+  const deduped: string[] = []
+  for (const p of pieces) {
+    if (seen.has(p)) continue
+    seen.add(p)
+    deduped.push(p)
+  }
+  return deduped.join('&')
+}
+
+async function fetchJson<T>(path: string, query: AnalyticsQuery, extras: Record<string, unknown> = {}, signal?: AbortSignal) {
+  const qs = buildQueryParams(query, extras)
+  const response = await fetch(`${path}?${qs}`, {
+    headers: { Accept: 'application/json' },
+    signal
+  })
+  if (!response.ok) {
+    throw new Error(`Request failed with status ${response.status}`)
+  }
+  return (await response.json()) as T
+}
+
+export function fetchTopStats(query: AnalyticsQuery, signal?: AbortSignal) {
+  return fetchJson<TopStatsPayload>(analyticsPath('top_stats'), query, {}, signal)
+}
+
+export function fetchMainGraph(
+  query: AnalyticsQuery,
+  extras: { metric?: string; interval?: string } = {},
+  signal?: AbortSignal
+) {
+  return fetchJson<MainGraphPayload>(analyticsPath('main_graph'), query, extras, signal)
+}
+
+export function fetchSources(
+  query: AnalyticsQuery,
+  extras: { mode?: string } = {},
+  signal?: AbortSignal
+) {
+  return fetchJson<ListPayload>(analyticsPath('sources'), query, extras, signal)
+}
+
+export function fetchReferrers(
+  query: AnalyticsQuery,
+  extras: { source: string },
+  signal?: AbortSignal
+) {
+  return fetchJson<ListPayload>(analyticsPath('referrers'), query, extras, signal)
+}
+
+export function fetchSearchTerms(
+  query: AnalyticsQuery,
+  extras: Record<string, unknown> = {},
+  signal?: AbortSignal
+) {
+  return fetchJson<ListPayload>(analyticsPath('search_terms'), query, extras, signal)
+}
+
+export function fetchPages(
+  query: AnalyticsQuery,
+  extras: { mode?: string } = {},
+  signal?: AbortSignal
+) {
+  return fetchJson<ListPayload>(analyticsPath('pages'), query, extras, signal)
+}
+
+export function fetchLocations(
+  query: AnalyticsQuery,
+  extras: { mode?: string } = {},
+  signal?: AbortSignal
+) {
+  return fetchJson<MapPayload | ListPayload>(analyticsPath('locations'), query, extras, signal)
+}
+
+export function fetchDevices(
+  query: AnalyticsQuery,
+  extras: { mode?: string } = {},
+  signal?: AbortSignal
+) {
+  return fetchJson<DevicesPayload>(analyticsPath('devices'), query, extras, signal)
+}
+
+export function fetchBehaviors(
+  query: AnalyticsQuery,
+  extras: { mode?: string; funnel?: string } = {},
+  signal?: AbortSignal
+) {
+  return fetchJson<BehaviorsPayload>(analyticsPath('behaviors'), query, extras, signal)
+}
+
+// Generic paginated list fetcher for Details modals
+export async function fetchListPage(
+  path: string,
+  query: AnalyticsQuery,
+  extras: Record<string, unknown> = {},
+  opts: { limit?: number; page?: number; search?: string; orderBy?: unknown[][] } = {},
+  signal?: AbortSignal
+) {
+  const params: Record<string, unknown> = { ...extras }
+  if (typeof opts.limit === 'number') params.limit = String(opts.limit)
+  if (typeof opts.page === 'number') params.page = String(opts.page)
+  if (typeof opts.search === 'string') params.search = opts.search
+  // Send order_by as JSON string following Plausible's pattern: [["metric", "direction"]]
+  if (opts.orderBy && Array.isArray(opts.orderBy)) {
+    params.order_by = JSON.stringify(opts.orderBy)
+  }
+  return fetchJson<ListPayload>(path, query, params, signal)
+}
+
+export async function exportCsv(query: AnalyticsQuery) {
+  const qs = buildQueryParams(query)
+  const response = await fetch(`${analyticsPath('export')}?${qs}`, {
+    headers: { Accept: 'text/csv' }
+  })
+  if (!response.ok) {
+    throw new Error('Failed to export data')
+  }
+  return response.blob()
+}

data/app/frontend/pages/admin/analytics/hooks/use-debounce.ts

@@ -0,0 +1,36 @@
+import { useCallback, useEffect, useRef } from 'react'
+
+const DEBOUNCE_DELAY = 300
+
+/**
+ * Debounce hook following Plausible's pattern.
+ * Delays function execution until after the specified delay has passed
+ * since the last time it was invoked.
+ */
+export function useDebounce<T extends (...args: any[]) => any>(
+  fn: T,
+  delay = DEBOUNCE_DELAY
+): T {
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current)
+      }
+    }
+  }, [])
+
+  return useCallback(
+    ((...args: Parameters<T>) => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current)
+      }
+
+      timerRef.current = setTimeout(() => {
+        fn(...args)
+      }, delay)
+    }) as T,
+    [fn, delay]
+  )
+}

data/app/frontend/pages/admin/analytics/last-load-context.tsx

@@ -0,0 +1,29 @@
+import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from 'react'
+
+export type LastLoadContextValue = {
+  lastLoadedAt: number
+  touch: () => void
+}
+
+const LastLoadContext = createContext<LastLoadContextValue | null>(null)
+
+export function LastLoadProvider({ children }: { children: ReactNode }) {
+  const [lastLoadedAt, setLastLoadedAt] = useState(() => Date.now())
+
+  const touch = useCallback(() => setLastLoadedAt(Date.now()), [])
+
+  const value = useMemo<LastLoadContextValue>(
+    () => ({ lastLoadedAt, touch }),
+    [lastLoadedAt, touch]
+  )
+
+  return <LastLoadContext.Provider value={value}>{children}</LastLoadContext.Provider>
+}
+
+export function useLastLoadContext() {
+  const context = useContext(LastLoadContext)
+  if (!context) {
+    throw new Error('useLastLoadContext must be used within a LastLoadProvider')
+  }
+  return context
+}

data/app/frontend/pages/admin/analytics/lib/base-path.ts

@@ -0,0 +1,28 @@
+type AnalyticsWindowConfig = {
+  basePath?: string
+  cablePath?: string
+}
+
+declare global {
+  interface Window {
+    AhoyAnalytics?: AnalyticsWindowConfig
+  }
+}
+
+export function analyticsBasePath() {
+  if (typeof window === 'undefined') return '/admin/analytics'
+  const base = window.AhoyAnalytics?.basePath || '/admin/analytics'
+  return base.replace(/\/+$/, '')
+}
+
+export function analyticsPath(path: string = '') {
+  const base = analyticsBasePath()
+  if (!path) return base
+  const trimmed = path.replace(/^\/+/, '')
+  return `${base}/${trimmed}`
+}
+
+export function analyticsCablePath() {
+  if (typeof window === 'undefined') return '/cable'
+  return window.AhoyAnalytics?.cablePath || '/cable'
+}