content_signals 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 511a0ac5433ad420855aad0d53f64839b1b9c05dd46f2a1cca26c86c4898c372
-  data.tar.gz: f20269439262403253d17dc0873007f5f30a7c94f3d612ad86e781137db3398c
+  metadata.gz: 7388e4fede60244368fbc17faba350e4427c9a028a7c4482b526836bc0f9f5ac
+  data.tar.gz: 14969ae023b16f9ca1a5db5922abddddf35444b860d2aa0c86211f9c6ebf695b
 SHA512:
-  metadata.gz: 890fc8d708a4fdc971e230312507801b914538ff55d9b2236e6002c9508c96872919230501fd06cc07e224fbf7208cdf6504a9158e475737f6d243f33c02c859
-  data.tar.gz: b05443d219acda5b7d3e41ee8532dea8c130c2b0b97031d91e433adf07e8b4eceeea5c3827cbb716b8d7363c8cb8aea530096cec6e148f95165c1e9bfc8049c7
+  metadata.gz: c020e32d9d0f675d11873f5933cef9b100944a9067df91956f05015eedb55b1a5ffe36a1f3337b3033093f0cabdd27547507eacdfc006d3abcbadddc7517152d
+  data.tar.gz: 02ce4de9492392cf993858d3f1d0a6b8713c915766357580bbda9c512f96df65c08e580bd8d470b6f2e23e81e83a5b86dab55156ae8f50a5ca518ca8ebf1dbe3

data/README.md

@@ -6,15 +6,21 @@ A Rails engine for tracking page views and content engagement with rich analytic
 
 ## Features
 
-- 📊 **Page view tracking** with visitor identification
-- 🌍 **Geolocation** (country, city, region) via MaxMind GeoLite2
-- 📱 **Device detection** (mobile, tablet, desktop, hybrid apps)
-- 🏢 **Multi-tenant support** (optional)
-- 🤖 **Bot filtering** (automatically excludes crawlers)
-- 🔄 **Background processing** (non-blocking with ActiveJob)
-- 📈 **Rich analytics** with time-based scopes and aggregations
-- 🎯 **Polymorphic tracking** (works with any model)
-- 📲 **Hybrid app support** (Capacitor, Cordova, React Native, Flutter)
+- **Page view tracking** with visitor identification
+- **Use cookies** to identify anonymous returning visitors
+- **Use Redis to deduplicate unique views per day** (optional)
+- **Device detection** (mobile, tablet, desktop, hybrid apps)
+- **Bot filtering** (automatically excludes crawlers)
+- **Background processing** (non-blocking with ActiveJob)
+- **Multi-tenant support** (optional)
+- **Rich analytics** with time-based scopes and aggregations
+- **Polymorphic tracking** (works with any model)
+- **Hybrid app support** (Capacitor, Cordova, React Native, Flutter)
+
+
+## Further development plans
+- **Geolocation** (country, city, region) via MaxMind GeoLite2
+
 
 ## Installation
 

data/lib/content_signals/configuration.rb

@@ -9,7 +9,9 @@ module ContentSignals
                   :redis_namespace,
                   :maxmind_db_path,
                   :track_bots,
-                  :track_admins
+                  :track_admins,
+                  :geoip_provider,  # Symbol (:maxmind, :ipinfo, :null) or a provider class
+                  :geoip_token      # API token for online providers (e.g. IPinfo)
 
     def initialize
       @multitenancy = false
@@ -20,6 +22,22 @@ module ContentSignals
       @maxmind_db_path = default_maxmind_path
       @track_bots = false
       @track_admins = false
+      @geoip_provider = :maxmind
+      @geoip_token = nil
+    end
+
+    # Returns the resolved provider class for IP geolocation.
+    # Accepts a symbol (:maxmind, :ipinfo, :null) or any class that responds to .locate(ip).
+    def resolved_geoip_provider
+      case @geoip_provider
+      when :maxmind then ContentSignals::Geoip::MaxmindProvider
+      when :ipinfo  then ContentSignals::Geoip::IpinfoProvider
+      when :null    then ContentSignals::Geoip::NullProvider
+      when Class    then @geoip_provider
+      else
+        raise ArgumentError, "Unknown geoip_provider: #{@geoip_provider.inspect}. " \
+                             "Use :maxmind, :ipinfo, :null, or a custom provider class."
+      end
     end
 
     def multitenancy?

data/lib/content_signals/geoip/base_provider.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  module Geoip
+    # Base interface for IP geolocation providers.
+    # All providers must implement `.locate(ip_address)` and return either:
+    #   - A Hash with keys: :country_code, :country_name, :city, :region, :latitude, :longitude
+    #   - nil  (when IP is local, lookup fails, or provider is disabled)
+    class BaseProvider
+      LOCAL_IP_PREFIXES = %w[127. 192.168. 10. 172. fc00: fe80:].freeze
+      LOCAL_IP_EXACT    = %w[::1 localhost].freeze
+
+      def self.locate(ip_address)
+        raise NotImplementedError, "#{name}.locate must be implemented"
+      end
+
+      def self.local_ip?(ip)
+        return true if ip.nil?
+
+        ip_str = ip.to_s
+        LOCAL_IP_EXACT.include?(ip_str) ||
+          LOCAL_IP_PREFIXES.any? { |prefix| ip_str.start_with?(prefix) }
+      end
+    end
+  end
+end

data/lib/content_signals/geoip/ipinfo_provider.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  module Geoip
+    # Online geolocation via IPinfo.io API.
+    # Requires: IPINFO_TOKEN env var (or config.geoip_token)
+    # Requires the http gem (gem "http") or net/http (built-in, used as fallback).
+    class IpinfoProvider < BaseProvider
+      API_BASE = "https://ipinfo.io"
+
+      def self.locate(ip_address)
+        return nil if ip_address.blank? || local_ip?(ip_address)
+
+        token = ContentSignals.configuration.geoip_token || ENV["IPINFO_TOKEN"]
+        return nil unless token.present?
+
+        data = fetch(ip_address, token)
+        return nil unless data && data["country"]
+
+        lat, lng = data["loc"]&.split(",")&.map(&:to_f)
+
+        {
+          country_code: data["country"],
+          country_name: country_name(data["country"]),
+          city:         data["city"],
+          region:       data["region"],
+          latitude:     lat,
+          longitude:    lng
+        }
+      rescue => e
+        Rails.logger.error "IPinfo geolocation error: #{e.message}"
+        nil
+      end
+
+      def self.fetch(ip, token)
+        uri = URI("#{API_BASE}/#{ip}/json?token=#{token}")
+        response = Net::HTTP.get_response(uri)
+        JSON.parse(response.body)
+      end
+
+      def self.country_name(code)
+        return nil unless defined?(ISO3166)
+
+        ISO3166::Country[code]&.name
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/content_signals/geoip/maxmind_provider.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  module Geoip
+    # Offline geolocation using a local MaxMind GeoLite2-City .mmdb file.
+    # Requires the maxminddb gem.
+    # Download/update the database: bundle exec rake app:stejar:geoip:update
+    class MaxmindProvider < BaseProvider
+      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.to_s)
+
+        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 "MaxMind geolocation error: #{e.message}"
+        nil
+      end
+
+      # Reset cached DB handle (useful after db file is updated)
+      def self.reset!
+        @db = nil
+      end
+    end
+  end
+end

data/lib/content_signals/geoip/null_provider.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  module Geoip
+    # No-op provider — disables geolocation entirely.
+    # Use when you don't want any IP lookup performed.
+    class NullProvider < BaseProvider
+      def self.locate(_ip_address)
+        nil
+      end
+    end
+  end
+end

data/lib/content_signals/jobs/update_geoip_database_job.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ContentSignals
+  # Downloads/refreshes the MaxMind GeoLite2-City database from the public mirror.
+  # Only runs when geoip_provider is :maxmind and maxmind_db_path is configured.
+  # Schedule via config/recurring.yml (added by `rails generate content_signals:install`).
+  class UpdateGeoipDatabaseJob < ApplicationJob
+    queue_as :default
+
+    MIRROR_URL = "https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb"
+
+    def perform
+      config = ContentSignals.configuration
+
+      unless config.geoip_provider == :maxmind
+        Rails.logger.info "[ContentSignals] UpdateGeoipDatabaseJob skipped: geoip_provider is not :maxmind"
+        return
+      end
+
+      db_path = config.maxmind_db_path
+      unless db_path.present?
+        Rails.logger.warn "[ContentSignals] UpdateGeoipDatabaseJob skipped: maxmind_db_path not configured"
+        return
+      end
+
+      download(db_path.to_s)
+    end
+
+    private
+
+    def download(db_path)
+      require "open-uri"
+      require "fileutils"
+
+      FileUtils.mkdir_p(File.dirname(db_path))
+
+      tmp_path = "#{db_path}.tmp"
+
+      Rails.logger.info "[ContentSignals] Downloading GeoLite2-City from mirror..."
+
+      URI.open(MIRROR_URL, "rb",  # rubocop:disable Security/Open
+               "User-Agent" => "Mozilla/5.0",
+               read_timeout: 120,
+               open_timeout: 15) do |remote|
+        File.binwrite(tmp_path, remote.read)
+      end
+
+      File.rename(tmp_path, db_path)
+
+      size_mb = (File.size(db_path) / 1_048_576.0).round(1)
+      Rails.logger.info "[ContentSignals] GeoLite2-City updated: #{db_path} (#{size_mb} MB)"
+
+      # Bust the cached DB handle so next lookup uses the fresh file
+      ContentSignals::Geoip::MaxmindProvider.reset!
+    rescue => e
+      File.delete(tmp_path) if tmp_path && File.exist?(tmp_path)
+      Rails.logger.error "[ContentSignals] GeoLite2 update failed: #{e.message}"
+      raise
+    end
+  end
+end

data/lib/content_signals/services/page_view_tracker.rb

@@ -44,6 +44,16 @@ module ContentSignals
       if @request.respond_to?(:cookie_jar)
         cookie_id = @request.cookie_jar.signed[:visitor_id]
         return cookie_id if cookie_id.present?
+        
+        # Generate and set new visitor cookie if none exists
+        new_visitor_id = "visitor_#{SecureRandom.uuid}"
+        @request.cookie_jar.signed[:visitor_id] = {
+          value: new_visitor_id,
+          expires: 2.years.from_now,
+          httponly: true,
+          same_site: :lax
+        }
+        return new_visitor_id
       end
 
       # 4. Fallback to IP + User Agent hash (for non-cookie scenarios)

data/lib/content_signals/services/visitor_location_service.rb

@@ -1,80 +1,16 @@
 # frozen_string_literal: true
 
 module ContentSignals
+  # Thin dispatcher: delegates IP geolocation to the configured provider.
+  # Switch providers via ContentSignals.configure { |c| c.geoip_provider = :ipinfo }
   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
+      ContentSignals.configuration.resolved_geoip_provider.locate(ip_address)
     end
 
+    # Convenience: is this a local/private IP?
     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
+      Geoip::BaseProvider.local_ip?(ip)
     end
   end
 end

data/lib/content_signals/version.rb

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

data/lib/content_signals.rb

@@ -5,17 +5,20 @@ require_relative "content_signals/configuration"
 
 # Optional dependencies - gracefully handle if not installed
 begin
-  require 'browser'
+  require "browser"
 rescue LoadError
   # Browser gem not installed - device detection will be disabled
 end
 
 begin
-  require 'maxmind/geoip2'
+  require "maxminddb"
 rescue LoadError
-  # MaxMind gem not installed - geolocation will be disabled
+  # maxminddb gem not installed - MaxmindProvider will be disabled
 end
 
+require "net/http"
+require "json"
+
 module ContentSignals
   class Error < StandardError; end
 
@@ -44,6 +47,12 @@ if defined?(ActiveRecord)
   require_relative "content_signals/models/page_view"
 end
 
+# Load geoip providers
+require_relative "content_signals/geoip/base_provider"
+require_relative "content_signals/geoip/maxmind_provider"
+require_relative "content_signals/geoip/ipinfo_provider"
+require_relative "content_signals/geoip/null_provider"
+
 # Load services
 require_relative "content_signals/services/page_view_tracker"
 require_relative "content_signals/services/visitor_location_service"
@@ -52,6 +61,7 @@ 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"
+  require_relative "content_signals/jobs/update_geoip_database_job"
 end
 
 # Load concerns if ActiveSupport is available

data/lib/generators/content_signals/install_generator.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-require 'rails/generators'
-require 'rails/generators/migration'
+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__)
+      source_root File.expand_path("templates", __dir__)
 
-      desc "Creates ContentSignals migration and initializer"
+      desc "Creates ContentSignals migration, initializer, and recurring job schedule"
 
       def self.next_migration_number(path)
         next_migration_number = current_migration_number(path) + 1
@@ -19,14 +19,42 @@ module ContentSignals
 
       def copy_migration
         migration_template "create_content_signals_page_views.rb.erb",
-                          "db/migrate/create_content_signals_page_views.rb",
-                          migration_version: migration_version
+                           "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 inject_recurring_job
+        recurring_yml = "config/recurring.yml"
+
+        if File.exist?(File.join(destination_root, recurring_yml))
+          content = File.read(File.join(destination_root, recurring_yml))
+
+          if content.include?("ContentSignals::UpdateGeoipDatabaseJob")
+            say_status :skip, "recurring.yml already contains ContentSignals::UpdateGeoipDatabaseJob", :yellow
+          else
+            append_to_file recurring_yml, <<~YAML
+
+              # ContentSignals — refresh GeoLite2-City database weekly (MaxMind updates Tuesdays)
+              content_signals_update_geoip_database:
+                class: ContentSignals::UpdateGeoipDatabaseJob
+                schedule: every week at 4am
+            YAML
+            say_status :append, recurring_yml, :green
+          end
+        else
+          create_file recurring_yml, <<~YAML
+            # ContentSignals — refresh GeoLite2-City database weekly (MaxMind updates Tuesdays)
+            content_signals_update_geoip_database:
+              class: ContentSignals::UpdateGeoipDatabaseJob
+              schedule: every week at 4am
+          YAML
+        end
+      end
+
       def show_readme
         readme "README" if behavior == :invoke
       end

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

@@ -1,3 +1,5 @@
+require "content_signals"
+
 ContentSignals.configure do |config|
   # Multi-tenancy (optional)
   # Enable if your app has multiple tenants/accounts
@@ -9,9 +11,19 @@ ContentSignals.configure do |config|
   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")
+  # IP Geolocation provider
+  # :maxmind  — offline, fast, no API calls. Requires local .mmdb file (default)
+  # :ipinfo   — online, no local file needed. Requires IPINFO_TOKEN env var
+  # :null     — disables geolocation entirely
+  config.geoip_provider = :maxmind
+
+  # MaxMind GeoLite2 database path (used when geoip_provider = :maxmind)
+  # Initial download: bundle exec rake app:stejar:geoip:update  (or run the job manually)
+  # Auto-updated weekly via ContentSignals::UpdateGeoipDatabaseJob (see config/recurring.yml)
+  config.maxmind_db_path = Rails.root.join("db", "GeoLite2-City.mmdb")
+
+  # IPinfo API token (used when geoip_provider = :ipinfo)
+  # config.geoip_token = ENV["IPINFO_TOKEN"]
 
   # Tracking preferences
   config.track_bots = false    # Set to true to track bot/crawler visits

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: content_signals
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Ionuț Munteanu Alexandru
@@ -116,7 +116,12 @@ files:
 - lib/content_signals/concerns/trackable_page_views.rb
 - lib/content_signals/configuration.rb
 - lib/content_signals/engine.rb
+- lib/content_signals/geoip/base_provider.rb
+- lib/content_signals/geoip/ipinfo_provider.rb
+- lib/content_signals/geoip/maxmind_provider.rb
+- lib/content_signals/geoip/null_provider.rb
 - lib/content_signals/jobs/track_page_view_job.rb
+- lib/content_signals/jobs/update_geoip_database_job.rb
 - lib/content_signals/models/page_view.rb
 - lib/content_signals/services/device_detector_service.rb
 - lib/content_signals/services/page_view_tracker.rb