rails_analytics 1.0.0

data/lib/generators/rails_analytics/install/templates/initializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+RailsAnalytics.configure do |config|
+  # Método de autenticação para o dashboard.
+  # Pode ser um Symbol (ex: :authenticate_admin!) ou um callable (ex: -> { current_user&.admin? }).
+  config.auth_callback = :authenticate_admin!
+
+  # Caminho onde o engine será montado no routes.rb.
+  config.mount_path = "/analytics"
+
+  # Período padrão para as consultas do dashboard (ex: 30.days).
+  config.since_default = 30.days
+end

data/lib/rails_analytics/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsAnalytics
+  class Configuration
+    attr_accessor :auth_callback, :mount_path, :since_default
+
+    def initialize
+      @auth_callback = :authenticate_admin!
+      @mount_path = "/analytics"
+      @since_default = 30.days
+    end
+
+    def auth_callback_callable?
+      auth_callback.respond_to?(:call)
+    end
+  end
+end

data/lib/rails_analytics/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RailsAnalytics
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsAnalytics
+
+    config.generators do |g|
+      g.test_framework :minitest
+      g.helper false
+      g.assets false
+    end
+
+    initializer "rails_analytics.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.precompile += %w[rails_analytics/tracker.js rails_analytics/dashboard.css]
+      end
+    end
+
+    initializer "rails_analytics.helper" do
+      ActiveSupport.on_load(:action_view) do
+        include RailsAnalytics::ApplicationHelper
+      end
+    end
+
+    initializer "rails_analytics.rack_attack" do
+      if defined?(Rack::Attack)
+        require "rails_analytics/rack_attack"
+        RailsAnalytics::RackAttack.configure
+      end
+    end
+  end
+end

data/lib/rails_analytics/identity.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RailsAnalytics
+  module Identity
+    # Coarse UA bucket: "<browser_family>:<os_family>"
+    # Never stores the full user agent string.
+    def self.coarse_ua_bucket(user_agent)
+      return "Other:Other" if user_agent.nil? || user_agent.empty?
+
+      ua = user_agent.to_s
+
+      os = if ua.match?(/Windows|Win64|Win32/i)
+             "Windows"
+           elsif ua.match?(/iPhone|iPad|iOS/i)
+             "iOS"
+           elsif ua.match?(/Macintosh|Mac OS X|macOS/i)
+             "macOS"
+           elsif ua.match?(/Android/i)
+             "Android"
+           elsif ua.match?(/Linux|X11/i)
+             "Linux"
+           else
+             "Other"
+           end
+
+      browser = if ua.match?(/Edg\//i)
+                  "Edge"
+                elsif ua.match?(/OPR|Opera/i)
+                  "Opera"
+                elsif ua.match?(/Chrome/i)
+                  "Chrome"
+                elsif ua.match?(/Safari/i)
+                  "Safari"
+                elsif ua.match?(/Firefox/i)
+                  "Firefox"
+                else
+                  "Other"
+                end
+
+      "#{browser}:#{os}"
+    end
+
+    def self.key(masked_ip:, user_agent:, date:)
+      bucket = coarse_ua_bucket(user_agent)
+      salt = RailsAnalytics::DailySalt.for_date(date)
+      Digest::SHA256.hexdigest("#{masked_ip}:#{bucket}:#{salt}")
+    end
+  end
+end

data/lib/rails_analytics/ip_mask.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module RailsAnalytics
+  module IpMask
+    def self.mask(ip)
+      return nil if ip.blank?
+
+      addr = IPAddr.new(ip.to_s)
+      if addr.ipv4?
+        addr.mask(24).to_s
+      elsif addr.ipv6?
+        if addr.ipv4_mapped?
+          IPAddr.new("::ffff:#{addr.native.mask(24)}").to_s
+        else
+          addr.mask(48).to_s
+        end
+      end
+    rescue IPAddr::InvalidAddressError
+      nil
+    end
+  end
+end

data/lib/rails_analytics/rack_attack.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RailsAnalytics
+  module RackAttack
+    def self.configure
+      return unless defined?(::Rack::Attack)
+
+      masked_ip = ->(req) {
+        ip = req.env["HTTP_CF_CONNECTING_IP"] || req.ip
+        RailsAnalytics::IpMask.mask(ip) || "unknown"
+      }
+
+      # Throttle the collection endpoint: 20 req/min per masked IP.
+      # Path ends in /collect regardless of mount_path.
+      ::Rack::Attack.throttle("rails_analytics_collect_by_ip", limit: 20, period: 60.seconds) do |req|
+        if req.post? && req.path.end_with?("/collect")
+          masked_ip.call(req)
+        end
+      end
+    end
+  end
+end

data/lib/rails_analytics/stats.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module RailsAnalytics
+  module Stats
+    module_function
+
+    def visits_by_day(since: default_since)
+      base_scope(since).group("date(started_at)")
+                       .order("date(started_at)")
+                       .count
+                       .transform_keys { |k| k.is_a?(String) ? Date.parse(k) : k }
+    end
+
+    def unique_visitors_by_day(since: default_since)
+      base_scope(since).group("date(started_at)")
+                       .order("date(started_at)")
+                       .distinct
+                       .count(:anonymity_key)
+                       .transform_keys { |k| k.is_a?(String) ? Date.parse(k) : k }
+    end
+
+    def total_visits(since: default_since)
+      base_scope(since).count
+    end
+
+    def total_unique_visitors(since: default_since)
+      base_scope(since).distinct.count(:anonymity_key)
+    end
+
+    def total_events(since: default_since)
+      Event.since(since).count
+    end
+
+    def top_sources(limit: 10, since: default_since)
+      base_scope(since).where.not(referrer_domain: nil)
+                       .group(:referrer_domain)
+                       .order("count_all desc")
+                       .limit(limit)
+                       .count
+    end
+
+    def top_events(limit: 10, since: default_since)
+      Event.since(since).group(:name)
+           .order("count_all desc")
+           .limit(limit)
+           .count
+    end
+
+    def event_counts_by_name(since: default_since)
+      Event.since(since).group(:name).count
+    end
+
+    def events_by_name(name, since: default_since)
+      Event.since(since).named(name)
+           .group("date(time)")
+           .order("date(time)")
+           .count
+           .transform_keys { |k| k.is_a?(String) ? Date.parse(k) : k }
+    end
+
+    def bounce_rate(since: default_since)
+      total = base_scope(since).count
+      return 0.0 if total.zero?
+
+      visits_with_events = base_scope(since)
+                            .joins(:events)
+                            .distinct
+                            .count
+      bounced = total - visits_with_events
+      (bounced.to_f / total).round(4)
+    end
+
+    def devices(since: default_since)
+      base_scope(since).group(:device_type).count
+    end
+
+    def utm_breakdown(since: default_since)
+      base_scope(since).where.not(utm_source: nil).or(Visit.where.not(utm_campaign: nil))
+                       .group(:utm_source, :utm_campaign, :utm_medium, :utm_term, :utm_content)
+                       .count
+                       .map do |keys, count|
+        { "utm_source" => keys[0], "utm_campaign" => keys[1], "utm_medium" => keys[2],
+          "utm_term" => keys[3], "utm_content" => keys[4], "count" => count }
+      end
+    end
+
+    def visits_paginated(page: 1, per_page: 20, since: default_since)
+      base = base_scope(since)
+      total = base.count
+
+      day_rows = base.group("date(started_at)")
+                     .order("date(started_at) desc")
+                     .select(
+                       "date(started_at) as day",
+                       "count(*) as visits",
+                       "count(distinct anonymity_key) as unique_visitors"
+                     )
+                     .offset((page - 1) * per_page)
+                     .limit(per_page)
+
+      top_sources = base.where.not(referrer_domain: nil)
+                        .group("date(started_at)", :referrer_domain)
+                        .count
+
+      data = day_rows.map do |row|
+        day = row.day.to_date
+        sources = top_sources.select { |(d, _ref), _count| d.to_date == day }
+                             .max_by { |(_d, _ref), count| count }
+        {
+          date: day,
+          visits: row.visits,
+          unique_visitors: row.unique_visitors,
+          top_source: sources&.first&.last
+        }
+      end
+
+      { data: data, total: total, page: page, per_page: per_page }
+    end
+
+    def events_paginated(name: nil, page: 1, per_page: 20, since: default_since)
+      scope = Event.since(since)
+      scope = scope.named(name) if name.present?
+
+      total = scope.group("date(time)", :name).count.size
+      rows = scope.group("date(time)", :name)
+                  .order("date(time) desc")
+                  .select("date(time) as day, name, count(*) as count")
+                  .offset((page - 1) * per_page)
+                  .limit(per_page)
+
+      data = rows.map do |r|
+        { date: r.day.to_date, name: r.name, count: r.count }
+      end
+
+      { data: data, total: total, page: page, per_page: per_page }
+    end
+
+    def base_scope(since)
+      Visit.since(since)
+    end
+
+    def default_since
+      RailsAnalytics.config.since_default.ago
+    end
+  end
+end

data/lib/rails_analytics/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsAnalytics
+  VERSION = "1.0.0"
+end

data/lib/rails_analytics.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "rails_analytics/version"
+require_relative "rails_analytics/configuration"
+require_relative "rails_analytics/ip_mask"
+require_relative "rails_analytics/identity"
+require_relative "rails_analytics/stats"
+require_relative "rails_analytics/engine" if defined?(Rails::Railtie)
+
+module RailsAnalytics
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config if block_given?
+    end
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: rails_analytics
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- br4zz4
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Rails Engine with server-side tracker, aggregated dashboard, IP masking,
+  daily anonymity key rotation, UTM tracking, and 6-month retention. No third-party
+  analytics dependencies.
+email:
+- dev@br4zz4.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- app/assets/javascripts/rails_analytics/tracker.js
+- app/assets/stylesheets/rails_analytics/dashboard.css
+- app/controllers/rails_analytics/analytics_controller.rb
+- app/controllers/rails_analytics/application_controller.rb
+- app/controllers/rails_analytics/dashboards_controller.rb
+- app/helpers/rails_analytics/application_helper.rb
+- app/jobs/rails_analytics/retention_job.rb
+- app/models/rails_analytics/chart_builder.rb
+- app/models/rails_analytics/daily_salt.rb
+- app/models/rails_analytics/event.rb
+- app/models/rails_analytics/visit.rb
+- app/views/layouts/rails_analytics.html.erb
+- app/views/rails_analytics/dashboards/events.html.erb
+- app/views/rails_analytics/dashboards/overview.html.erb
+- app/views/rails_analytics/dashboards/visits.html.erb
+- config/locales/rails_analytics.en.yml
+- config/locales/rails_analytics.pt-BR.yml
+- config/routes.rb
+- db/migrate/20260906000001_create_rails_analytics_daily_salts.rb
+- db/migrate/20260906000002_create_rails_analytics_visits.rb
+- db/migrate/20260906000003_create_rails_analytics_events.rb
+- docs/dashboard-2.png
+- docs/dashboard.png
+- lib/generators/rails_analytics/install/install_generator.rb
+- lib/generators/rails_analytics/install/templates/initializer.rb
+- lib/rails_analytics.rb
+- lib/rails_analytics/configuration.rb
+- lib/rails_analytics/engine.rb
+- lib/rails_analytics/identity.rb
+- lib/rails_analytics/ip_mask.rb
+- lib/rails_analytics/rack_attack.rb
+- lib/rails_analytics/stats.rb
+- lib/rails_analytics/version.rb
+homepage: https://github.com/br4zz4/rails-analytics
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Privacy-first analytics engine for Rails — cookie-less, LGPD-compliant.
+test_files: []