content_signals 0.1.0 → 0.1.1

data/lib/content_signals/models/page_view.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  class PageView < ActiveRecord::Base
+    self.table_name = "content_signals_page_views"
+
+    # Associations
+    belongs_to :trackable, polymorphic: true, counter_cache: :page_views_count
+    belongs_to :tenant, optional: true if ContentSignals.configuration.multitenancy?
+    belongs_to :user, optional: true
+
+    # Validations
+    validates :trackable_type, :trackable_id, :visitor_id, :viewed_at, presence: true
+    validates :country_code, length: { maximum: 2 }, allow_nil: true
+    validates :device_type, inclusion: { in: %w[desktop mobile tablet] }, allow_nil: true
+    validates :app_platform, inclusion: { in: %w[hybrid native] }, allow_nil: true
+
+    # Default scope for tenant isolation (when multitenancy is enabled)
+    if ContentSignals.configuration.multitenancy?
+      default_scope -> { where(tenant_id: current_tenant_id) }
+
+      def self.current_tenant_id
+        return nil unless ContentSignals.configuration.multitenancy?
+
+        method_name = ContentSignals.configuration.current_tenant_method
+        return nil unless method_name
+
+        # Try to get tenant_id from Current, controller, or thread
+        if defined?(Current) && Current.respond_to?(method_name)
+          Current.send(method_name)
+        elsif Thread.current[method_name]
+          Thread.current[method_name]
+        end
+      end
+    end
+
+    # Time period scopes
+    scope :today, -> { where("viewed_at >= ?", Time.current.beginning_of_day) }
+    scope :yesterday, -> { where(viewed_at: 1.day.ago.all_day) }
+    scope :this_week, -> { where("viewed_at >= ?", Time.current.beginning_of_week) }
+    scope :last_week, -> { where(viewed_at: 1.week.ago.beginning_of_week..1.week.ago.end_of_week) }
+    scope :this_month, -> { where("viewed_at >= ?", Time.current.beginning_of_month) }
+    scope :last_month, -> { where(viewed_at: 1.month.ago.beginning_of_month..1.month.ago.end_of_month) }
+    scope :last_30_days, -> { where("viewed_at >= ?", 30.days.ago) }
+    scope :last_90_days, -> { where("viewed_at >= ?", 90.days.ago) }
+    scope :this_year, -> { where("viewed_at >= ?", Time.current.beginning_of_year) }
+
+    # Device scopes
+    scope :mobile, -> { where(device_type: "mobile") }
+    scope :desktop, -> { where(device_type: "desktop") }
+    scope :tablet, -> { where(device_type: "tablet") }
+    scope :app, -> { where(device_type: "hybrid_app") }
+    scope :web, -> { where(device_type: %w[desktop mobile tablet]) }
+
+    # Platform scopes
+    scope :from_hybrid_app, -> { where(app_platform: "hybrid") }
+    scope :from_native_app, -> { where.not(app_platform: "native") }
+    scope :from_website, -> { where(app_platform: nil) }
+
+    # Location scopes
+    scope :from_country, ->(country_code) { where(country_code: country_code.to_s.upcase) }
+    scope :from_city, ->(city) { where(city: city) }
+    scope :from_region, ->(region) { where(region: region) }
+
+    # User scopes
+    scope :authenticated, -> { where.not(user_id: nil) }
+    scope :anonymous, -> { where(user_id: nil) }
+
+    # Ordering scopes
+    scope :recent, -> { order(viewed_at: :desc) }
+    scope :oldest, -> { order(viewed_at: :asc) }
+
+    # Analytics methods
+    class << self
+      def unique_count(period = :all_time)
+        scope = period == :all_time ? self : send(period)
+        scope.distinct.count(:visitor_id)
+      end
+
+      def top_countries(limit = 10)
+        where.not(country_name: nil)
+          .group(:country_code, :country_name)
+          .order("count_id DESC")
+          .limit(limit)
+          .count(:id)
+      end
+
+      def top_cities(limit = 10)
+        where.not(city: nil)
+          .group(:city, :country_name)
+          .order("count_id DESC")
+          .limit(limit)
+          .count(:id)
+      end
+
+      def top_regions(limit = 10)
+        where.not(region: nil)
+          .group(:region, :country_name)
+          .order("count_id DESC")
+          .limit(limit)
+          .count(:id)
+      end
+
+      def device_breakdown
+        group(:device_type)
+          .order("count_id DESC")
+          .count(:id)
+      end
+
+      def browser_breakdown(limit = 10)
+        where.not(browser: nil)
+          .group(:browser)
+          .order("count_id DESC")
+          .limit(limit)
+          .count(:id)
+      end
+
+      def os_breakdown(limit = 10)
+        where.not(os: nil)
+          .group(:os)
+          .order("count_id DESC")
+          .limit(limit)
+          .count(:id)
+      end
+
+      def platform_breakdown
+        group(:app_platform)
+          .order("count_id DESC")
+          .count(:id)
+      end
+
+      def hourly_distribution
+        group("EXTRACT(HOUR FROM viewed_at)::integer")
+          .order("EXTRACT(HOUR FROM viewed_at)::integer")
+          .count(:id)
+      end
+
+      def daily_distribution(days = 30)
+        where("viewed_at >= ?", days.days.ago)
+          .group("DATE(viewed_at)")
+          .order("DATE(viewed_at)")
+          .count(:id)
+      end
+
+      def weekly_distribution(weeks = 12)
+        where("viewed_at >= ?", weeks.weeks.ago)
+          .group("strftime('%Y-%W', viewed_at)")
+          .order("strftime('%Y-%W', viewed_at)")
+          .count(:id)
+      end
+
+      def monthly_distribution(months = 12)
+        where("viewed_at >= ?", months.months.ago)
+          .group("strftime('%Y-%m', viewed_at)")
+          .order("strftime('%Y-%m', viewed_at)")
+          .count(:id)
+      end
+
+      # For map visualization - returns array of [lat, lng, count]
+      def location_heatmap
+        where.not(latitude: nil, longitude: nil)
+          .group(:latitude, :longitude)
+          .count(:id)
+          .map { |(lat, lng), count| { lat: lat.to_f, lng: lng.to_f, count: count } }
+      end
+
+      # Referrer analysis
+      def top_referrers(limit = 10)
+        where.not(referrer: nil)
+          .where.not(referrer: "")
+          .group(:referrer)
+          .order("count_id DESC")
+          .limit(limit)
+          .count(:id)
+      end
+
+      # Growth metrics
+      def growth_rate(period = :last_30_days)
+        current_period = send(period).count
+
+        previous_period_start = case period
+        when :today then 1.day.ago.beginning_of_day
+        when :this_week then 1.week.ago.beginning_of_week
+        when :this_month then 1.month.ago.beginning_of_month
+        when :last_30_days then 60.days.ago
+        else 1.day.ago
+        end
+
+        previous_period_end = case period
+        when :today then 1.day.ago.end_of_day
+        when :this_week then 1.week.ago.end_of_week
+        when :this_month then 1.month.ago.end_of_month
+        when :last_30_days then 30.days.ago
+        else Time.current
+        end
+
+        previous_period = where(viewed_at: previous_period_start..previous_period_end).count
+
+        return 0 if previous_period.zero?
+        ((current_period - previous_period).to_f / previous_period * 100).round(2)
+      end
+    end
+
+    # Instance methods
+    def web_browser?
+      app_platform.nil?
+    end
+
+    def hybrid_app?
+      app_platform.present?
+    end
+
+    def mobile_device?
+      device_type.in?(%w[mobile tablet])
+    end
+
+    def desktop_device?
+      device_type == "desktop"
+    end
+
+    def authenticated?
+      user_id.present?
+    end
+
+    def anonymous?
+      user_id.nil?
+    end
+  end
+end

data/lib/content_signals/services/device_detector_service.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  class DeviceDetectorService
+    def self.detect(user_agent, app_platform: nil)
+      return nil if user_agent.blank?
+      return nil unless defined?(Browser)
+
+      browser = Browser.new(user_agent)
+
+      {
+        device_type: detect_device_type(browser, app_platform),
+        browser: browser.name,
+        os: browser.platform.name
+      }
+    rescue => e
+      Rails.logger.error "Device detection error: #{e.message}"
+      {
+        device_type: app_platform.present? ? 'hybrid_app' : 'desktop',
+        browser: 'Unknown',
+        os: 'Unknown'
+      }
+    end
+
+    def self.detect_device_type(browser, app_platform)
+      # If it's from a mobile app, always mark as hybrid_app
+      return 'hybrid_app' if app_platform.present?
+
+      return 'mobile' if browser.device.mobile?
+      return 'tablet' if browser.device.tablet?
+
+      'desktop'
+    end
+
+    def self.webview?(user_agent)
+      return false if user_agent.blank?
+
+      ua = user_agent.to_s.downcase
+      ua.match?(/wv|webview|; wv\)/)
+    end
+  end
+end

data/lib/content_signals/services/page_view_tracker.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  class PageViewTracker
+    def self.track(trackable:, request:, user: nil)
+      new(trackable, request, user).track
+    end
+
+    def initialize(trackable, request, user)
+      @trackable = trackable
+      @user = user
+      @request = request
+      @visitor_id = identify_visitor
+    end
+
+    def track
+      # Track unique view if first time today (optional, requires Redis)
+      track_unique_view if unique_today?
+
+      # Gather all tracking data
+      tracking_data = compile_tracking_data
+
+      # Store detailed view record asynchronously
+      # Note: counter_cache on PageView model will automatically increment page_views_count
+      ContentSignals::TrackPageViewJob.perform_later(
+        @trackable.class.name,
+        @trackable.id,
+        @user&.id,
+        tracking_data
+      )
+    end
+
+    private
+
+    def identify_visitor
+      # 1. Authenticated user (most reliable)
+      return "user_#{@user.id}" if @user
+
+      # 2. Device ID from mobile app (persistent across app sessions)
+      device_id = @request.headers['X-Device-ID'] || @request.params[:device_id]
+      return "device_#{device_id}" if device_id.present?
+
+      # 3. Browser cookie (set by controller concern, read here)
+      if @request.respond_to?(:cookie_jar)
+        cookie_id = @request.cookie_jar.signed[:visitor_id]
+        return cookie_id if cookie_id.present?
+      end
+
+      # 4. Fallback to IP + User Agent hash (for non-cookie scenarios)
+      "anon_#{Digest::SHA256.hexdigest("#{@request.ip}:#{@request.user_agent}")[0..15]}"
+    end
+
+    def unique_today?
+      return true unless redis_enabled?
+
+      key = unique_view_key
+      !Rails.cache.exist?(key)
+    end
+
+    def track_unique_view
+      return unless redis_enabled?
+
+      key = unique_view_key
+      Rails.cache.write(key, true, expires_in: 24.hours)
+
+      # Also increment daily unique counter
+      daily_key = "page_unique_views:#{@trackable.class.name}:#{@trackable.id}:#{Date.current}"
+      Rails.cache.increment(daily_key, 1)
+    rescue => e
+      Rails.logger.error "Failed to track unique view: #{e.message}"
+    end
+
+    def unique_view_key
+      tenant_part = current_tenant_id ? "tenant_#{current_tenant_id}:" : ""
+      "page_view:#{tenant_part}#{@trackable.class.name}:#{@trackable.id}:visitor_#{@visitor_id}:#{Date.current}"
+    end
+
+    def compile_tracking_data
+      location_data = ContentSignals::VisitorLocationService.locate(@request.ip) || {}
+      app_context = detect_app_context
+      device_data = ContentSignals::DeviceDetectorService.detect(
+        @request.user_agent,
+        app_platform: app_context[:app_platform]
+      ) || {}
+
+      {
+        tenant_id: current_tenant_id,
+        visitor_id: @visitor_id,
+        ip_address: @request.ip,
+        user_agent: @request.user_agent,
+        referrer: @request.referrer,
+        locale: detect_locale,
+        viewed_at: Time.current,
+        app_platform: app_context[:app_platform],
+        app_version: app_context[:app_version],
+        device_id: app_context[:device_id]
+      }.merge(location_data).merge(device_data)
+    end
+
+    def detect_app_context
+      {
+        app_platform: @request.headers['X-App-Platform'] || detect_platform_from_ua,
+        app_version: @request.headers['X-App-Version'],
+        device_id: @request.headers['X-Device-ID'] || @request.params[:device_id]
+      }
+    end
+
+    def detect_platform_from_ua
+      ua = @request.user_agent.to_s.downcase
+      return 'capacitor' if ua.include?('capacitor')
+      return 'cordova' if ua.include?('cordova')
+      return 'react_native' if ua.include?('react-native')
+      return 'flutter' if ua.include?('flutter')
+      return 'webview' if ua.match?(/wv|webview/)
+      nil
+    end
+
+    def detect_locale
+      accept_language = @request.headers['Accept-Language']
+      return I18n.locale.to_s unless accept_language
+
+      accept_language.split(',').first&.strip || I18n.locale.to_s
+    end
+
+    def current_tenant_id
+      return nil unless ContentSignals.configuration.multitenancy?
+
+      method_name = ContentSignals.configuration.current_tenant_method
+      return nil unless method_name
+
+      # Try to get tenant_id from controller instance
+      controller = @request.env['action_controller.instance']
+      return nil unless controller
+
+      controller.send(method_name) if controller.respond_to?(method_name, true)
+    rescue => e
+      Rails.logger.error "Failed to get tenant_id: #{e.message}"
+      nil
+    end
+
+    def redis_enabled?
+      ContentSignals.configuration.redis_enabled? && Rails.cache.respond_to?(:redis)
+    rescue
+      false
+    end
+  end
+end

data/lib/content_signals/services/visitor_location_service.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  class VisitorLocationService
+    def self.locate(ip_address)
+      return nil if ip_address.blank? || local_ip?(ip_address)
+
+      db_path = ContentSignals.configuration.maxmind_db_path
+      return nil unless db_path && File.exist?(db_path)
+
+      # Initialize database connection (cached in production)
+      db = @db ||= MaxMindDB.new(db_path.to_s)
+      result = db.lookup(ip_address)
+
+      return nil unless result&.found?
+
+      {
+        country_code: result.country.iso_code,
+        country_name: result.country.name,
+        city: result.city.name,
+        region: result.subdivisions.most_specific&.name,
+        latitude: result.location.latitude,
+        longitude: result.location.longitude
+      }
+    rescue MaxMindDB::Error => e
+      Rails.logger.error "MaxMind lookup error: #{e.message}"
+      nil
+    rescue => e
+      Rails.logger.error "Geolocation error: #{e.message}"
+      nil
+    end
+
+    def self.local_ip?(ip)
+      return true if ip.nil?
+
+      ip_str = ip.to_s
+      ip_str.start_with?('127.', '192.168.', '10.', '172.', 'fc00:', 'fe80:') ||
+      ip_str == '::1' ||
+      ip_str == 'localhost'
+    end
+
+    # Fallback to API if database not available (optional)
+    def self.locate_via_api(ip_address)
+      return nil if ip_address.blank? || local_ip?(ip_address)
+      return nil unless defined?(HTTP)
+
+      token = ENV['IPINFO_TOKEN']
+      return nil unless token
+
+      # Using IPinfo.io as fallback
+      response = HTTP.get("https://ipinfo.io/#{ip_address}/json", params: { token: token })
+      data = JSON.parse(response.body)
+
+      return nil unless data['country']
+
+      lat, lng = data['loc']&.split(',')&.map(&:to_f)
+
+      {
+        country_code: data['country'],
+        country_name: country_name_from_code(data['country']),
+        city: data['city'],
+        region: data['region'],
+        latitude: lat,
+        longitude: lng
+      }
+    rescue => e
+      Rails.logger.error "API geolocation error: #{e.message}"
+      nil
+    end
+
+    def self.country_name_from_code(code)
+      return nil unless defined?(ISO3166)
+
+      country = ISO3166::Country[code]
+      country&.name
+    rescue
+      nil
+    end
+  end
+end

data/lib/content_signals/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ContentSignals
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/content_signals.rb

@@ -1,8 +1,60 @@
 # frozen_string_literal: true
 
 require_relative "content_signals/version"
+require_relative "content_signals/configuration"
+
+# Optional dependencies - gracefully handle if not installed
+begin
+  require 'browser'
+rescue LoadError
+  # Browser gem not installed - device detection will be disabled
+end
+
+begin
+  require 'maxmind/geoip2'
+rescue LoadError
+  # MaxMind gem not installed - geolocation will be disabled
+end
 
 module ContentSignals
   class Error < StandardError; end
-  # Your code goes here...
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+# Load Rails engine if Rails is available
+require_relative "content_signals/engine" if defined?(Rails::Engine)
+
+# Always load models when ActiveRecord is available
+if defined?(ActiveRecord)
+  require_relative "content_signals/models/page_view"
+end
+
+# Load services
+require_relative "content_signals/services/page_view_tracker"
+require_relative "content_signals/services/visitor_location_service"
+require_relative "content_signals/services/device_detector_service"
+
+# Load jobs if ActiveJob is available
+if defined?(ActiveJob)
+  require_relative "content_signals/jobs/track_page_view_job"
+end
+
+# Load concerns if ActiveSupport is available
+if defined?(ActiveSupport::Concern)
+  require_relative "content_signals/concerns/trackable_page_views"
 end

data/lib/generators/content_signals/install_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module ContentSignals
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc "Creates ContentSignals migration and initializer"
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migration
+        migration_template "create_content_signals_page_views.rb.erb",
+                          "db/migrate/create_content_signals_page_views.rb",
+                          migration_version: migration_version
+      end
+
+      def copy_initializer
+        template "content_signals.rb.erb", "config/initializers/content_signals.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/content_signals/templates/README

@@ -0,0 +1,36 @@
+===============================================================================
+
+  ContentSignals has been installed!
+
+  Next steps:
+
+  1. Run migrations:
+     rails db:migrate
+
+  2. Add page_views_count counter to your trackable models:
+     rails generate migration AddPageViewsCountToYourModel page_views_count:integer
+
+     Then edit the migration to add default value and index:
+
+     add_column :your_models, :page_views_count, :integer, default: 0, null: false
+     add_index :your_models, :page_views_count
+
+  3. Include tracking in your controllers:
+
+     class YourController < ApplicationController
+       include ContentSignals::TrackablePageViews
+
+       def show
+         @record = YourModel.find(params[:id])
+         # Page views are tracked automatically!
+       end
+     end
+
+  4. (Optional) Configure geolocation:
+     - Download MaxMind GeoLite2 database: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
+     - Place in db/GeoLite2-City.mmdb
+     - Update config/initializers/content_signals.rb
+
+  For more information, see: https://github.com/yourusername/content_signals
+
+===============================================================================

data/lib/generators/content_signals/templates/content_signals.rb.erb

@@ -0,0 +1,19 @@
+ContentSignals.configure do |config|
+  # Multi-tenancy (optional)
+  # Enable if your app has multiple tenants/accounts
+  config.multitenancy = false
+  config.current_tenant_method = :current_tenant_id
+
+  # Redis (optional, for unique visitor tracking)
+  # Requires Redis gem and connection
+  config.redis_enabled = true
+  config.redis_namespace = "content_signals"
+
+  # MaxMind GeoLite2 database path (optional, for geolocation)
+  # Download from: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
+  # config.maxmind_db_path = Rails.root.join("db", "GeoLite2-City.mmdb")
+
+  # Tracking preferences
+  config.track_bots = false    # Set to true to track bot/crawler visits
+  config.track_admins = false  # Set to true to track admin user visits
+end