ahoy_analytics 0.1.0

data/app/controllers/ahoy_analytics/search_terms_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AhoyAnalytics
+  class SearchTermsController < AhoyAnalytics::BaseController
+    def index
+      # TODO(GSC): Real Google Search Console integration. Placeholder mirrors Plausible UX signals.
+      return render(json: { errorCode: "not_configured", isAdmin: true }, status: :unprocessable_entity) unless gsc_configured?
+      return render(json: { errorCode: "unsupported_filters" }, status: :unprocessable_entity) if unsupported_gsc_filters?(@query)
+
+      limit, page = parsed_pagination
+      search = normalized_search
+      payload = cache_for([ :search_terms, limit, page, search, params[:order_by] ]) do
+        search_terms_payload(@query, limit:, page:, search:)
+      end
+
+      range, = Ahoy::Visit.range_and_interval_for(@query[:period], nil, @query)
+      if payload[:results].blank? && (Time.zone.now - range.begin < 72.hours)
+        return render json: { errorCode: "period_too_recent" }, status: :unprocessable_entity
+      end
+
+      render json: camelize_keys(payload)
+    end
+
+    private
+      def gsc_configured?
+        configured = AhoyAnalytics.config.gsc_configured
+        configured = instance_exec(&configured) if configured.respond_to?(:call)
+        return configured unless configured.nil?
+
+        # Prefer DB flag when available, then Rails config, then ENV
+        db = AhoyAnalytics::Setting.get_bool("gsc_configured", fallback: nil)
+        return db unless db.nil?
+        v = Rails.configuration.x.analytics&.gsc_configured
+        v = ENV["ANALYTICS_GSC_CONFIGURED"] if v.nil?
+        ActiveModel::Type::Boolean.new.cast(v)
+      end
+
+      def unsupported_gsc_filters?(query)
+        filters = (query[:filters] || {}).stringify_keys
+        disallowed = %w[channel referrer utm_source utm_medium utm_campaign utm_content utm_term entry_page exit_page]
+        return true if filters.keys.any? { |k| disallowed.include?(k) }
+        adv = Array(query[:advanced_filters])
+        return true if adv.any?
+        false
+      end
+  end
+end

data/app/controllers/ahoy_analytics/sources_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module AhoyAnalytics
+  class SourcesController < AhoyAnalytics::BaseController
+    def index
+      limit, page = parsed_pagination
+      search = normalized_search
+      payload = cache_for([ :sources, @query[:mode], limit, page, search, params[:order_by] ]) do
+        sources_payload(@query, limit:, page:, search:)
+      end
+      render json: camelize_keys(payload)
+    end
+  end
+end

data/app/controllers/ahoy_analytics/top_stats_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module AhoyAnalytics
+  class TopStatsController < AhoyAnalytics::BaseController
+    def show
+      cached = cache_for(:top_stats) { top_stats_payload(@query) }
+      if cached[:top_stats]&.first&.dig(:name) == "Live visitors"
+        cached[:top_stats][0][:value] = Ahoy::Visit.live_visitors_count
+      end
+      render json: camelize_keys(cached)
+    end
+  end
+end

data/app/controllers/concerns/ahoy_analytics/set_current_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AhoyAnalytics
+  module SetCurrentRequest
+    extend ActiveSupport::Concern
+
+    included do
+      before_action do
+        AhoyAnalytics::Current.request = request
+      end
+    end
+
+    def default_url_options
+      { host: AhoyAnalytics::Current.request_host, protocol: AhoyAnalytics::Current.request_protocol }.compact_blank
+    end
+  end
+end

data/app/frontend/components/analytics/hex-highlights.tsx

@@ -0,0 +1,165 @@
+import { useEffect, useMemo, useRef } from 'react'
+import { useThree } from '@react-three/fiber'
+import * as THREE from 'three'
+// three's BufferGeometryUtils helper for merging many hex geometries into one
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+import ConicPolygonGeometry from 'three-conic-polygon-geometry'
+import { latLngToCell, cellToBoundary, cellToLatLng } from 'h3-js'
+
+type Dot = { lat: number; lng: number; type: 'visitor'; city?: string | null }
+
+type Props = {
+  data: Dot[]
+  resolution?: number
+  margin?: number
+  // Base altitude just above land hexes (land ~0.002).
+  altitudeBase?: number
+  onHover?: (t: { x: number; y: number; label: string } | null) => void
+}
+
+// Draws real hexes (same geometry/orientation as the land layer) at the H3 cell
+// containing each dot. This guarantees exact alignment with the grid at all zooms.
+export default function HexHighlights({ data, resolution = 3, margin = 0.2, altitudeBase = 0.00205, onHover }: Props) {
+  const { scene, camera, gl } = useThree()
+  const groupRef = useRef<THREE.Group | null>(null)
+
+  const { visitorCells, cellLabels } = useMemo(() => {
+    const v = new Set<string>()
+    const labels = new Map<string, string>()
+    for (const d of data) {
+      try {
+        const cell = latLngToCell(d.lat, d.lng, resolution)
+        v.add(cell)
+        if (!labels.has(cell)) labels.set(cell, (d.city || 'Unknown') as string)
+      } catch {}
+    }
+    return { visitorCells: Array.from(v), cellLabels: labels }
+  }, [data, resolution])
+
+  useEffect(() => {
+    const group = new THREE.Group()
+    group.renderOrder = 2
+
+    const makeLayer = (
+      cells: string[],
+      color: string,
+      altitude: number,
+      renderOrder: number,
+      options?: { outline?: boolean }
+    ) => {
+      if (cells.length === 0) return
+      const geoms: THREE.BufferGeometry[] = []
+      for (const idx of cells) {
+        // Get hex boundary and center
+        const center = cellToLatLng(idx) // [lat,lng]
+        const centerLat = center[0]
+        const centerLng = center[1]
+        let boundary = cellToBoundary(idx, true) // [[lng,lat], ...]
+        // Ensure winding similar to three-globe (reverse)
+        boundary = boundary.slice().reverse()
+
+        // Apply same margin logic as three-globe to keep inner hex size consistent
+        const shrink = (elng: number, elat: number) => {
+          const lerp = (a: number, b: number, t: number) => a * (1 - t) + b * t
+          return [lerp(elng, centerLng, margin), lerp(elat, centerLat, margin)] as [number, number]
+        }
+        const shrunk = margin === 0 ? boundary : boundary.map(([lng, lat]) => shrink(lng, lat))
+
+        // Build a single ConicPolygonGeometry for this hex from radius 1 to 1+altitude
+        try {
+          const geo = new ConicPolygonGeometry([shrunk], 1, 1 + altitude, false, true, false, 4)
+          geoms.push(geo)
+        } catch {}
+      }
+      if (geoms.length > 0) {
+        const merged = BufferGeometryUtils.mergeGeometries(geoms, false) as THREE.BufferGeometry
+        const mat = new THREE.MeshLambertMaterial({ color, transparent: false, depthWrite: true })
+        const mesh = new THREE.Mesh(merged, mat)
+        mesh.renderOrder = renderOrder
+        group.add(mesh)
+
+        if (options?.outline) {
+          // Crisp 1px white outline above the fill
+          const edges = new THREE.EdgesGeometry(merged)
+          const lineMat = new THREE.LineBasicMaterial({ color: '#ffffff', transparent: true, opacity: 0.95, depthTest: false })
+          const lines = new THREE.LineSegments(edges, lineMat)
+          lines.renderOrder = renderOrder + 1
+          group.add(lines)
+        }
+      }
+    }
+
+    const visitorAlt = altitudeBase + 0.00008
+    makeLayer(visitorCells, '#2563eb', visitorAlt, 3)
+
+    scene.add(group)
+    groupRef.current = group
+
+    return () => {
+      if (groupRef.current) {
+        scene.remove(groupRef.current)
+        groupRef.current.traverse((obj) => {
+          const mesh = obj as THREE.Mesh
+          if ((mesh as any).geometry) (mesh as any).geometry.dispose?.()
+          if ((mesh as any).material) {
+            const m = (mesh as any).material as THREE.Material | THREE.Material[]
+            Array.isArray(m) ? m.forEach((mm) => mm.dispose?.()) : m.dispose?.()
+          }
+        })
+        groupRef.current = null
+      }
+    }
+  }, [scene, visitorCells, margin, altitudeBase])
+
+  // Pointer interaction: map cursor to globe point, then to H3 cell, then show label
+  useEffect(() => {
+    if (!onHover) return
+    const sphereRadius = 1
+    const handleMove = (ev: PointerEvent) => {
+      const rect = gl.domElement.getBoundingClientRect()
+      const nx = ((ev.clientX - rect.left) / rect.width) * 2 - 1
+      const ny = -((ev.clientY - rect.top) / rect.height) * 2 + 1
+
+      const ray = new THREE.Ray()
+      ray.origin.copy((camera as THREE.PerspectiveCamera).position)
+      ray.direction.set(nx, ny, 0.5).unproject(camera as THREE.PerspectiveCamera).sub(ray.origin).normalize()
+
+      // Ray-sphere intersection (center at 0, radius=1)
+      const o = ray.origin
+      const d = ray.direction
+      const b = o.dot(d)
+      const c = o.lengthSq() - sphereRadius * sphereRadius
+      const disc = b * b - c
+      if (disc < 0) { onHover(null); return }
+      const t = -b - Math.sqrt(disc)
+      if (t <= 0) { onHover(null); return }
+      const p = new THREE.Vector3().copy(d).multiplyScalar(t).add(o)
+
+      // Convert to lat/lng
+      const r = p.length()
+      const phi = Math.acos(p.y / r)
+      const theta = Math.atan2(p.z, p.x)
+      const lat = 90 - (phi * 180 / Math.PI)
+      const lng = 90 - (theta * 180 / Math.PI) - (theta < -Math.PI / 2 ? 360 : 0)
+
+      try {
+        const cell = latLngToCell(lat, lng, resolution)
+        if (cellLabels.has(cell)) {
+          const label = cellLabels.get(cell) as string
+          onHover({ x: ev.clientX - rect.left + 10, y: ev.clientY - rect.top + 12, label })
+          return
+        }
+      } catch {}
+      onHover(null)
+    }
+    const leave = () => onHover(null)
+    gl.domElement.addEventListener('pointermove', handleMove)
+    gl.domElement.addEventListener('pointerleave', leave)
+    return () => {
+      gl.domElement.removeEventListener('pointermove', handleMove)
+      gl.domElement.removeEventListener('pointerleave', leave)
+    }
+  }, [camera, gl, onHover, cellLabels, resolution])
+
+  return null
+}

data/app/frontend/components/analytics/hex-land-layer.tsx

@@ -0,0 +1,61 @@
+import { useEffect, useMemo, useRef } from 'react'
+import { useThree } from '@react-three/fiber'
+import ThreeGlobe from 'three-globe'
+import type { Feature, FeatureCollection, Geometry, GeoJsonProperties } from 'geojson'
+import globeData from '@/data/globe-data.json'
+
+// Import as GeoJSON FeatureCollection
+const rawFeatures = globeData as unknown as FeatureCollection<Geometry, GeoJsonProperties>
+
+export default function HexLandLayer() {
+  const { scene } = useThree()
+  const globeRef = useRef<ThreeGlobe | null>(null)
+
+  const landFeatures = useMemo(() => {
+    if (!rawFeatures?.features) return [] as Feature<Geometry, GeoJsonProperties>[]
+
+    // Features are already individual Polygons with holes removed from build script
+    return rawFeatures.features as Feature<Geometry, GeoJsonProperties>[]
+  }, [])
+
+  useEffect(() => {
+    if (!landFeatures.length) return
+
+    const globe = new ThreeGlobe({ animateIn: false })
+    globe.hexPolygonsData(landFeatures as any)
+    globe.hexPolygonResolution(3) // Medium resolution hexagons
+    globe.hexPolygonMargin(0.2) // Small margin for tight spacing
+    globe.hexPolygonUseDots(false) // Use filled hexagons, not dots
+    const SCALE = 0.01
+    globe.hexPolygonAltitude(() => 0.002) // Slight elevation
+    // In-between Tailwind sky-300 and sky-400 (~"sky-350") for softer contrast
+    globe.hexPolygonColor(() => '#5ac8fa')
+    globe.hexPolygonsTransitionDuration(0)
+    globe.showAtmosphere(false)
+    globe.scale.setScalar(SCALE)
+
+    const baseMaterial = globe.globeMaterial()
+    baseMaterial.transparent = true
+    baseMaterial.opacity = 0
+    baseMaterial.depthWrite = false
+
+    // Access and configure hexagon material for better rendering
+    const hexMaterialAccessor = (globe as unknown as { hexPolygonsMaterial?: () => any }).hexPolygonsMaterial
+    if (hexMaterialAccessor) {
+      const mat = hexMaterialAccessor.call(globe)
+      mat.transparent = false
+      mat.opacity = 1.0
+      mat.depthWrite = true
+    }
+
+    globeRef.current = globe
+    scene.add(globe)
+
+    return () => {
+      scene.remove(globe)
+      globeRef.current = null
+    }
+  }, [landFeatures, scene])
+
+  return null
+}

data/app/frontend/components/analytics/metric-card.tsx

@@ -0,0 +1,138 @@
+import { Line } from 'react-chartjs-2'
+import { ArrowUpIcon, ArrowDownIcon } from 'lucide-react'
+import { Card, CardContent } from '@/components/ui/card'
+import {
+  Chart as ChartJS,
+  CategoryScale,
+  LinearScale,
+  PointElement,
+  LineElement,
+  Title,
+  Tooltip,
+  Legend,
+  Filler
+} from 'chart.js'
+
+// Register Chart.js components
+ChartJS.register(
+  CategoryScale,
+  LinearScale,
+  PointElement,
+  LineElement,
+  Title,
+  Tooltip,
+  Legend,
+  Filler
+)
+
+type SparklineSeries = number[] | { today: number[]; yesterday?: number[] }
+
+type MetricCardProps = {
+  title: string
+  value: string | number
+  change?: number
+  sparklineData?: SparklineSeries
+  variant?: 'default' | 'large'
+  showChange?: boolean
+}
+
+export function MetricCard({
+  title,
+  value,
+  change,
+  sparklineData,
+  variant = 'default',
+  showChange = true
+}: MetricCardProps) {
+  const hasChange = change !== undefined && change !== null && !isNaN(change)
+  const isPositive = hasChange && change > 0
+  const isNegative = hasChange && change < 0
+  const normalized = Array.isArray(sparklineData)
+    ? { today: sparklineData, yesterday: undefined as number[] | undefined }
+    : (sparklineData || { today: [], yesterday: undefined })
+  const showSparkline = normalized.today && normalized.today.length > 0
+  const hasMeaningfulChange = isPositive || isNegative
+
+  return (
+    <Card className="overflow-hidden rounded-xl border border-white/12 bg-[#11131b] shadow-[0_12px_26px_rgba(7,9,16,0.32)] !py-0">
+      <CardContent className="px-5 py-3">
+        <div className="flex flex-col gap-2">
+          <span className="text-sm font-semibold text-foreground/80">{title}</span>
+
+          <div className="grid grid-cols-2 items-center gap-3">
+            <div className="flex items-baseline gap-2">
+              <span className={variant === 'large' ? 'text-xl font-semibold text-foreground' : 'text-lg font-semibold text-foreground'}>
+                {value}
+              </span>
+
+              {showChange && (
+                hasMeaningfulChange ? (
+                  <div className="flex items-center gap-1 text-xs">
+                    {isPositive && <ArrowUpIcon className="size-3 text-emerald-400" />}
+                    {isNegative && <ArrowDownIcon className="size-3 text-rose-400" />}
+                    <span className={isPositive ? 'text-emerald-400' : 'text-rose-400'}>
+                      {Math.abs(change ?? 0)}%
+                    </span>
+                  </div>
+                ) : (
+                  <span className="text-xs font-medium text-muted-foreground">—</span>
+                )
+              )}
+            </div>
+
+            {showSparkline && (
+              <div className="ml-auto h-8 w-full max-w-[92px] overflow-hidden rounded-md bg-[#0d0f16]/80">
+                <Line
+                  data={{
+                    labels: Array.from({ length: Math.max(normalized.today.length, normalized.yesterday?.length || 0) }, (_, i) => i),
+                    datasets: [
+                      ...(normalized.yesterday && normalized.yesterday.length > 0
+                        ? [{
+                            data: normalized.yesterday,
+                            borderColor: 'rgba(56, 189, 248, 0.55)',
+                            backgroundColor: 'transparent',
+                            borderWidth: 1,
+                            borderDash: [3, 3] as [number, number],
+                            pointRadius: 0,
+                            pointHoverRadius: 0,
+                            tension: 0.45,
+                            fill: false
+                          }]
+                        : []),
+                      {
+                        data: normalized.today,
+                        borderColor: 'rgba(56, 189, 248, 1)',
+                        backgroundColor: 'rgba(56, 189, 248, 0.08)',
+                        borderWidth: 1.3,
+                        pointRadius: 0,
+                        pointHoverRadius: 0,
+                        tension: 0.45,
+                        fill: true
+                      }
+                    ]
+                  }}
+                  options={{
+                    responsive: true,
+                    maintainAspectRatio: false,
+                    plugins: {
+                      legend: { display: false },
+                      tooltip: { enabled: false }
+                    },
+                    scales: {
+                      x: { display: false },
+                      y: { display: false }
+                    },
+                    interaction: {
+                      mode: 'index',
+                      intersect: false
+                    }
+                  }}
+                />
+              </div>
+            )}
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  )
+}

data/app/frontend/components/analytics/sessions-by-location.tsx

@@ -0,0 +1,62 @@
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+
+type LocationSession = {
+  country: string
+  city: string
+  region?: string
+  countryCode: string
+  visitors: number
+}
+
+export function SessionsByLocation({ sessions }: { sessions: LocationSession[] }) {
+  if (!sessions || sessions.length === 0) {
+    return (
+      <Card className="gap-0 rounded-xl border border-white/12 bg-[#11131b] shadow-[0_12px_26px_rgba(7,9,16,0.32)] py-0">
+        <CardHeader className="px-5 pt-4 pb-2">
+          <CardTitle className="text-sm font-semibold text-foreground/80">Sessions by location</CardTitle>
+        </CardHeader>
+        <CardContent className="px-5 pb-4 pt-2">
+          <div className="py-4 text-center text-xs text-muted-foreground/80">
+            No active sessions
+          </div>
+        </CardContent>
+      </Card>
+    )
+  }
+
+  const maxVisitors = Math.max(...sessions.map(s => s.visitors))
+
+  return (
+    <Card className="gap-0 rounded-xl border border-white/12 bg-[#11131b] shadow-[0_12px_26px_rgba(7,9,16,0.32)] py-0">
+      <CardHeader className="px-5 pt-4 pb-2">
+        <CardTitle className="text-sm font-semibold text-foreground/80">Sessions by location</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-2.5 px-5 pb-4 pt-2">
+        {sessions.map((session, i) => {
+          const locationParts = [
+            session.country,
+            session.region,
+            session.city
+          ].filter(Boolean)
+
+          return (
+            <div key={i} className="space-y-2">
+              <div className="flex items-center justify-between text-[12px] text-foreground/80">
+                <span className="truncate font-medium text-foreground">
+                  {locationParts.join(' - ')}
+                </span>
+                <span className="ml-2 flex-shrink-0 text-muted-foreground/80">{session.visitors}</span>
+              </div>
+              <div className="h-[6px] overflow-hidden rounded-full bg-white/10">
+                <div
+                  className="h-full rounded-full bg-cyan-400 transition-all duration-300"
+                  style={{ width: `${(session.visitors / maxVisitors) * 100}%` }}
+                />
+              </div>
+            </div>
+          )
+        })}
+      </CardContent>
+    </Card>
+  )
+}