ahoy_analytics 0.1.0

data/app/frontend/pages/admin/analytics/user-context.tsx

@@ -0,0 +1,22 @@
+import { createContext, useContext, type ReactNode } from 'react'
+import type { UserContextValue } from './types'
+
+const UserContext = createContext<UserContextValue | null>(null)
+
+export function UserProvider({
+  value,
+  children
+}: {
+  value: UserContextValue
+  children: ReactNode
+}) {
+  return <UserContext.Provider value={value}>{children}</UserContext.Provider>
+}
+
+export function useUserContext() {
+  const context = useContext(UserContext)
+  if (!context) {
+    throw new Error('useUserContext must be used within a UserProvider')
+  }
+  return context
+}

data/app/frontend/styles/shared.css

@@ -0,0 +1,156 @@
+/* Global/Shared Styles - Application-wide CSS */
+/* This file contains only shared Tailwind configuration and global utilities */
+/* Theme-specific styles are in public.css (public pages) or admin.css (admin pages) */
+
+@import "tailwindcss";
+@import "tw-animate-css";
+
+/* Shared Tailwind plugins used across the application */
+@plugin "@tailwindcss/typography";
+@plugin "@tailwindcss/forms";
+
+/* Global utility for dark mode support across all layouts */
+@custom-variant dark (&:where(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *, [data-theme="dark-pro"], [data-theme="dark-pro"] *));
+
+/* Sonner Toast Customization */
+[data-sonner-toaster] {
+  font-family: inherit;
+}
+
+[data-sonner-toast] {
+  backdrop-filter: blur(8px);
+  background: color-mix(in oklch, var(--background) 95%, transparent 5%) !important;
+  border-radius: var(--radius-md);
+  box-shadow:
+    0 0 0 1px color-mix(in oklch, var(--border) 40%, transparent 60%),
+    0 4px 12px color-mix(in oklch, oklch(0 0 0) 20%, transparent 80%),
+    0 8px 24px color-mix(in oklch, oklch(0 0 0) 10%, transparent 90%);
+  transition: all 0.2s ease;
+}
+
+[data-sonner-toast]:hover {
+  box-shadow:
+    0 0 0 1px color-mix(in oklch, var(--border) 60%, transparent 40%),
+    0 8px 20px color-mix(in oklch, oklch(0 0 0) 25%, transparent 75%),
+    0 12px 32px color-mix(in oklch, oklch(0 0 0) 15%, transparent 85%);
+  transform: translateY(-2px);
+}
+
+/* Success toasts with golden theme */
+[data-sonner-toast][data-type="success"] {
+  background: color-mix(in oklch, var(--primary) 8%, var(--background) 92%) !important;
+  border: 1px solid color-mix(in oklch, var(--primary) 30%, transparent 70%) !important;
+  color: var(--primary) !important;
+}
+
+[data-sonner-toast][data-type="success"] [data-icon] {
+  color: var(--primary);
+}
+
+/* Error toasts */
+[data-sonner-toast][data-type="error"] {
+  background: color-mix(in oklch, var(--destructive) 8%, var(--background) 92%) !important;
+  border: 1px solid color-mix(in oklch, var(--destructive) 30%, transparent 70%) !important;
+  color: var(--destructive) !important;
+}
+
+[data-sonner-toast][data-type="error"] [data-icon] {
+  color: var(--destructive);
+}
+
+/* Warning toasts */
+[data-sonner-toast][data-type="warning"] {
+  background: color-mix(in oklch, oklch(0.75 0.15 75) 8%, var(--background) 92%) !important;
+  border: 1px solid color-mix(in oklch, oklch(0.75 0.15 75) 30%, transparent 70%) !important;
+  color: oklch(0.75 0.15 75) !important;
+}
+
+/* Info toasts */
+[data-sonner-toast][data-type="info"] {
+  background: color-mix(in oklch, oklch(0.65 0.15 240) 8%, var(--background) 92%) !important;
+  border: 1px solid color-mix(in oklch, oklch(0.65 0.15 240) 30%, transparent 70%) !important;
+  color: oklch(0.65 0.15 240) !important;
+}
+
+/* Action buttons */
+[data-sonner-toast] [data-button] {
+  background: var(--primary) !important;
+  color: var(--primary-foreground) !important;
+  border-radius: calc(var(--radius-md) - 2px);
+  padding: 0.375rem 0.75rem;
+  font-weight: 500;
+  transition: all 0.15s ease;
+}
+
+[data-sonner-toast] [data-button]:hover {
+  background: color-mix(in oklch, var(--primary) 85%, oklch(0 0 0) 15%) !important;
+  transform: translateY(-1px);
+}
+
+[data-sonner-toast] [data-cancel] {
+  background: color-mix(in oklch, var(--muted) 50%, transparent 50%) !important;
+  color: var(--muted-foreground) !important;
+}
+
+/* Close button */
+[data-sonner-toast] [data-close-button] {
+  background: color-mix(in oklch, var(--foreground) 10%, transparent 90%) !important;
+  border: 1px solid color-mix(in oklch, var(--border) 40%, transparent 60%) !important;
+  transition: all 0.15s ease;
+}
+
+[data-sonner-toast] [data-close-button]:hover {
+  background: color-mix(in oklch, var(--foreground) 20%, transparent 80%) !important;
+  border-color: var(--border) !important;
+}
+
+/* Shared theme token mappings */
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+/* Global base resets - minimal and shared across all layouts */
+@layer base {
+  *, *::before, *::after { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  * { @apply border-border outline-ring/50; }
+  button:not([disabled]), [role="button"]:not([disabled]) { cursor: pointer; }
+}

data/app/helpers/ahoy_analytics/application_helper.rb

@@ -0,0 +1,96 @@
+module AhoyAnalytics
+  module ApplicationHelper
+    def ahoy_analytics_base_path
+      request&.script_name.presence || AhoyAnalytics.config.mount_path.to_s
+    end
+
+    def ahoy_analytics_head_tags(entrypoint)
+      # In dev mode with Vite, only include the client tag
+      # CSS is imported by JS files and handled by Vite automatically
+      return vite_client_tag if use_vite_dev_server?
+
+      entry = ahoy_analytics_manifest.entry(entrypoint)
+      css = Array(entry["css"])
+      return nil if css.empty?
+
+      safe_join(css.map { |path| stylesheet_link_tag(ahoy_analytics_asset_path(path), media: "all") })
+    end
+
+    def ahoy_analytics_body_tags(entrypoint)
+      return vite_javascript_tag(entrypoint) if use_vite_dev_server?
+
+      entry = ahoy_analytics_manifest.entry(entrypoint)
+      javascript_include_tag(
+        ahoy_analytics_asset_path(entry.fetch("file")),
+        type: "module",
+        defer: true,
+        crossorigin: "anonymous"
+      )
+    end
+
+    def ahoy_analytics_tracking_tag
+      config = tracking_config
+      config_json = json_escape(config.to_json)
+      safe_join([
+        javascript_tag("window.analyticsConfig = #{config_json};"),
+        ahoy_analytics_body_tags("analytics-tracker")
+      ])
+    end
+
+    def ahoy_analytics_window_config_tag
+      config_json = json_escape(ahoy_analytics_window_config.to_json)
+      javascript_tag("window.AhoyAnalytics = #{config_json};")
+    end
+
+    private
+
+      def ahoy_analytics_manifest
+        @ahoy_analytics_manifest ||= AhoyAnalytics::AssetManifest.new(
+          path: AhoyAnalytics::Engine.root.join("app/assets/ahoy_analytics/build/.vite/manifest.json")
+        )
+      end
+
+      def ahoy_analytics_asset_path(path)
+        cleaned = path.to_s.sub(/\A\//, "")
+        cleaned = cleaned.sub(/\Aassets\//, "")
+        ahoy_analytics.engine_asset_path(path: cleaned)
+      end
+
+      def tracking_config
+        ahoy_path = AhoyAnalytics.config.ahoy_path.to_s
+        ahoy_path = "/#{ahoy_path}" unless ahoy_path.start_with?("/")
+        exclude_paths = Array(AhoyAnalytics.config.tracking_exclude_paths)
+        exclude_paths << AhoyAnalytics.config.mount_path if AhoyAnalytics.config.mount_path.present?
+        exclude_paths = exclude_paths.compact.uniq
+
+        base = {
+          eventsEndpoint: "#{ahoy_path}/events",
+          visitsEndpoint: "#{ahoy_path}/visits",
+          excludePaths: exclude_paths,
+          hashBasedRouting: AhoyAnalytics.config.tracking_hash_based_routing,
+          debug: AhoyAnalytics.config.tracking_debug
+        }
+
+        include_paths = Array(AhoyAnalytics.config.tracking_include_paths).reject(&:blank?)
+        base[:includePaths] = include_paths if include_paths.any?
+
+        base.merge(AhoyAnalytics.config.tracking_options.to_h)
+      end
+
+      def ahoy_analytics_window_config
+        {
+          basePath: ahoy_analytics_base_path,
+          cablePath: AhoyAnalytics.config.cable_path,
+          geocodeEmail: AhoyAnalytics.config.geocode_email
+        }.compact
+      end
+
+      def use_vite_dev_server?
+        return false unless AhoyAnalytics.config.use_vite_dev_server
+
+        respond_to?(:vite_client_tag) &&
+          respond_to?(:vite_stylesheet_tag) &&
+          respond_to?(:vite_javascript_tag)
+      end
+  end
+end

data/app/jobs/ahoy_analytics/application_job.rb

@@ -0,0 +1,4 @@
+module AhoyAnalytics
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/ahoy_analytics/update_job.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AhoyAnalytics
+  class UpdateJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      payload = AhoyAnalytics::LiveStats.build(now: Time.zone.now)
+      ActionCable.server.broadcast(AhoyAnalytics.config.cable_stream, payload)
+    end
+  end
+end

data/app/mailers/ahoy_analytics/application_mailer.rb

@@ -0,0 +1,6 @@
+module AhoyAnalytics
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/ahoy/event/filters.rb

@@ -0,0 +1,7 @@
+module Ahoy::Event::Filters
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Event-side filter helpers to be moved here (if/when needed)
+  end
+end

data/app/models/ahoy/event.rb

@@ -0,0 +1,9 @@
+class Ahoy::Event < ApplicationRecord
+  include Ahoy::QueryMethods
+  include Ahoy::Event::Filters
+
+  self.table_name = "ahoy_events"
+
+  belongs_to :visit
+  belongs_to :user, optional: true
+end

data/app/models/ahoy/visit/cache_key.rb

@@ -0,0 +1,15 @@
+module Ahoy::Visit::CacheKey
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def analytics_data_version
+      visit_time = Ahoy::Visit.maximum(:started_at)
+      event_time = Ahoy::Event.maximum(:time)
+      if visit_time || event_time
+        [ visit_time, event_time ].compact.map { |time| time.utc.to_f }.max
+      else
+        [ Ahoy::Visit.maximum(:id), Ahoy::Event.maximum(:id) ].compact.max.to_i
+      end
+    end
+  end
+end

data/app/models/ahoy/visit/constants.rb

@@ -0,0 +1,11 @@
+module Ahoy::Visit::Constants
+  extend ActiveSupport::Concern
+
+  UNKNOWN_LABEL = "(unknown)".freeze
+  NONE_LABEL = "(none)".freeze
+  NOT_SET_LABEL = "(not set)".freeze
+  DIRECT_LABEL = "Direct / None".freeze
+
+  EVENT_PAGEVIEW = "pageview".freeze
+  EVENT_ENGAGEMENT = "engagement".freeze
+end

data/app/models/ahoy/visit/devices.rb

@@ -0,0 +1,144 @@
+module Ahoy::Visit::Devices
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def devices_payload(query, limit: nil, page: nil, search: nil, order_by: nil)
+      mode = query[:mode] || "browsers"
+      filters = query[:filters] || {}
+      range, = Ahoy::Visit.range_and_interval_for(query[:period], nil, query)
+      visits = Ahoy::Visit.scoped_visits(range, filters)
+      goal = filters["goal"].presence
+
+      if mode == "screen-sizes"
+        raw_grouped = visits.group(:screen_size).pluck(:screen_size, Arel.sql("ARRAY_AGG(id)"))
+        categorized_visit_ids = Hash.new { |h, k| h[k] = [] }
+        raw_grouped.each do |screen_size, visit_ids|
+          category = categorize_screen_size(screen_size)
+          categorized_visit_ids[category].concat(visit_ids)
+        end
+        counts = Ahoy::Visit.unique_counts_from_grouped_visit_ids(categorized_visit_ids, visits)
+        items = counts.map { |name, n| { name: name.to_s.presence || UNKNOWN_LABEL, visitors: n } }
+        if search.present?
+          items = items.select { |it| it[:name].to_s.downcase.include?(search.downcase) }
+        end
+
+        if limit && page
+          # Build counts from (possibly filtered) items
+          items_counts = items.each_with_object({}) { |it, h| h[it[:name]] = it[:visitors].to_i }
+          total = items_counts.values.sum.nonzero? || 1
+
+          metrics_map = {}
+          if order_by
+            metric, _ = order_by
+            if metric == "percentage"
+              metrics_map = items_counts.keys.index_with { |n| { percentage: (items_counts[n].to_f / total) } }
+            elsif %w[bounce_rate visit_duration].include?(metric)
+              metrics_all = Ahoy::Visit.calculate_group_metrics(categorized_visit_ids, range, filters)
+              metrics_map = items_counts.keys.index_with { |n| metrics_all[n] || {} }
+            end
+          end
+
+          sorted_names = Ahoy::Visit.order_names(counts: items_counts, metrics_map: metrics_map, order_by: order_by)
+
+          paged_names, has_more = Ahoy::Visit.paginate_names(sorted_names, limit: limit, page: page)
+          grouped_page_visit_ids = categorized_visit_ids.slice(*paged_names)
+
+          if goal.present?
+            conversions, cr = Ahoy::Visit.conversions_and_rates(grouped_page_visit_ids, visits, range, filters, goal)
+            page_items = paged_names.map { |name| { name: name, visitors: conversions[name] || 0, conversion_rate: cr[name] } }
+            { results: page_items, metrics: %i[visitors conversion_rate], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query), metric_labels: { visitors: "Conversions", conversionRate: "Conversion Rate" } } }
+          else
+            page_items = paged_names.map do |name|
+              v = items_counts[name]
+              { name: name, visitors: v, percentage: (v.to_f / total).round(3) }
+            end
+            group_metrics = Ahoy::Visit.calculate_group_metrics(grouped_page_visit_ids, range, filters)
+            page_items.each { |it| it[:bounce_rate] = group_metrics.dig(it[:name], :bounce_rate); it[:visit_duration] = group_metrics.dig(it[:name], :visit_duration) }
+            { results: page_items, metrics: %i[visitors percentage bounce_rate visit_duration], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+          end
+        else
+          total = counts.values.sum.nonzero? || 1
+          results = items.map { |it| it.merge(percentage: (it[:visitors].to_f / total).round(3)) }
+          { results: results, metrics: %i[visitors percentage], meta: { has_more: false, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+        end
+      else
+        column = mode == "operating-systems" || mode == "operating-system-versions" ? :os : :browser
+        expr = column.to_s
+        pattern = search.present? ? Ahoy::Visit.like_contains(search) : nil
+
+        if limit && page
+          rel = visits
+          rel = rel.where([ "LOWER(#{expr}) LIKE ?", pattern ]) if pattern.present?
+          grouped_visit_ids = rel.group(Arel.sql(expr)).pluck(Arel.sql("#{expr}, ARRAY_AGG(ahoy_visits.id)")).to_h
+          counts = Ahoy::Visit.unique_counts_from_grouped_visit_ids(grouped_visit_ids, visits)
+          total = counts.values.sum.nonzero? || 1
+
+          metrics_map = {}
+          if order_by
+            metric, _ = order_by
+            if metric == "percentage"
+              metrics_map = counts.keys.index_with { |n| { percentage: (counts[n].to_f / total) } }
+            elsif %w[bounce_rate visit_duration].include?(metric)
+              metrics_all = Ahoy::Visit.calculate_group_metrics(grouped_visit_ids, range, filters)
+              metrics_map = counts.keys.index_with { |n| metrics_all[n] || {} }
+            end
+          end
+          sorted_names = Ahoy::Visit.order_names(counts: counts, metrics_map: metrics_map, order_by: order_by)
+
+          paged_names, has_more = Ahoy::Visit.paginate_names(sorted_names, limit: limit, page: page)
+          page_visit_ids = grouped_visit_ids.slice(*paged_names)
+
+          if goal.present?
+            conversions, cr = Ahoy::Visit.conversions_and_rates(page_visit_ids, visits, range, filters, goal)
+            results = paged_names.map { |name| { name: name.to_s.presence || UNKNOWN_LABEL, visitors: conversions[name] || 0, conversion_rate: cr[name] } }
+            { results: results, metrics: %i[visitors conversion_rate], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query), metric_labels: { visitors: "Conversions", conversionRate: "Conversion Rate" } } }
+          else
+            results = paged_names.map do |name|
+              n = counts[name]
+              { name: name.to_s.presence || UNKNOWN_LABEL, visitors: n, percentage: (n.to_f / total).round(3) }
+            end
+            group_metrics = Ahoy::Visit.calculate_group_metrics(page_visit_ids, range, filters)
+            paged_names.each_with_index do |name, i|
+              results[i][:bounce_rate] = group_metrics.dig(name, :bounce_rate)
+              results[i][:visit_duration] = group_metrics.dig(name, :visit_duration)
+            end
+            { results: results, metrics: %i[visitors percentage bounce_rate visit_duration], meta: { has_more: has_more, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+          end
+        else
+          grouped_visit_ids = visits.group(column).pluck(column, Arel.sql("ARRAY_AGG(id)")).to_h
+          counts = Ahoy::Visit.unique_counts_from_grouped_visit_ids(grouped_visit_ids, visits)
+          total = counts.values.sum.nonzero? || 1
+          results = counts.map { |name, n| { name: name.to_s.presence || UNKNOWN_LABEL, visitors: n, percentage: (n.to_f / total).round(3) } }
+          { results: results, metrics: %i[visitors percentage], meta: { has_more: false, skip_imported_reason: Ahoy::Visit.skip_imported_reason(query) } }
+        end
+      end
+    end
+    def categorize_screen_sizes(visits_scope)
+      raw_counts = visits_scope.group(:screen_size).count
+      categorized = Hash.new(0)
+
+      raw_counts.each do |screen_size, count|
+        category = categorize_screen_size(screen_size)
+        categorized[category] += count
+      end
+
+      categorized
+    end
+
+    def categorize_screen_size(screen_size)
+      return "(not set)" if screen_size.blank?
+
+      if screen_size =~ /^(\d+)x(\d+)$/
+        width = $1.to_i
+        case width
+        when 0...768 then "Mobile"
+        when 768...1024 then "Tablet"
+        when 1024...1440 then "Laptop"
+        else "Desktop"
+        end
+      else
+        screen_size
+      end
+    end
+  end
+end

data/app/models/ahoy/visit/export.rb

@@ -0,0 +1,24 @@
+require "csv"
+
+module Ahoy::Visit::Export
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def csv_export(range, filters)
+      visits = Ahoy::Visit.scoped_visits(range, filters)
+      data = visits.group(Arel.sql("COALESCE(referring_domain, 'Direct / None')")).count
+      CSV.generate do |csv|
+        csv << %w[name visitors]
+        data.sort_by { |_, v| -v }.each do |(name, v)|
+          csv << [ csv_safe_value(name), v ]
+        end
+      end
+    end
+
+    def csv_safe_value(value)
+      str = value.to_s
+      str = "'#{str}" if str.match?(/\A[=+\-@]/)
+      str
+    end
+  end
+end