footprinted 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0a6166d8616c0c1204631e17bc3ecf5c09cbff6fc94a38ee892061f2679b8c2
-  data.tar.gz: '0783420c75bf7f3736b0b4fcd84484281353f07d9fb89c1773066d25cb44dab7'
+  metadata.gz: 20ea0ce295c5fe9031013e323a46e744b92de81e6e433db994dc4df485373e31
+  data.tar.gz: '09c5e324348d00dcb53b8fbe7e581e22ee45e9d194f706d48685678cc999359a'
 SHA512:
-  metadata.gz: ff0f0e67acc390309d8d8491f43efa63d001ae58f72768d041b88f5842a231d76a444d129067dad4daffda702a5cd9d377d08be51c87cd9c76d079fb3f937a79
-  data.tar.gz: ff2e6a3705a726900cc0c4bca87ec9c07ca635f3a1ff02f67464affce02a9f5d179fca9f33714c1b7cf5ba1f80577770362ed94a0a9f342709f17e672fedf403
+  metadata.gz: 69f4c70cdddadd0bcf208bcecc337ab484ae5ac6991748488e4620a5d712c69ae6b444b26ceb6c0ad10a036c4652185a938509c203348d16b5cac0a28ae9c7a4
+  data.tar.gz: 5aaa74017232c3f54cc6db64155d75d762a7f758f04a7e886474e7af9cd579173264c744447f86f0eae56b84b096cb984f462bd40105e35a1ea80e1e8283448f

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.3.0] - 2026-02-15
+
+- **Async mode now extracts geo data at enqueue time** when `request:` is passed
+  - Cloudflare headers are captured before the job is enqueued
+  - Background jobs no longer need MaxMind to get geo data
+  - Falls back to MaxMind lookup in the job if `request:` wasn't passed
+- No breaking changes — existing code works unchanged
+
+## [0.2.1] - 2026-02-09
+
+- Fix async mode: change Railtie to Engine so `TrackJob` is autoloaded
+
 ## [0.2.0] - 2026-02-08
 
 **Full rewrite.** Breaking changes from v0.1.0.

data/README.md

@@ -245,7 +245,41 @@ add_index :footprints, :device_id
 add_index :footprints, :app_version
 ```
 
-Then write to both the column and the metadata hash in your tracking code. The gem stays generic; your app adds the columns it needs.
+Your tracking calls stay the same — just pass everything in `metadata` as before. To auto-promote metadata keys into their dedicated columns, add a `before_save` callback in an initializer:
+
+```ruby
+# config/initializers/footprinted_extensions.rb
+
+# String columns that map 1:1 from metadata
+FOOTPRINT_PROMOTED_STRING_COLUMNS = %w[device_id app_version platform].freeze
+
+# Integer columns that need casting
+FOOTPRINT_PROMOTED_INTEGER_COLUMNS = %w[cpu_cores memory_gb].freeze
+
+Rails.configuration.to_prepare do
+  Footprinted::Footprint.class_eval do
+    before_save :promote_metadata_columns
+
+    private
+
+    def promote_metadata_columns
+      return if metadata.blank?
+
+      m = metadata.stringify_keys
+
+      FOOTPRINT_PROMOTED_STRING_COLUMNS.each do |key|
+        self[key] = m[key] if self[key].blank? && m[key].present?
+      end
+
+      FOOTPRINT_PROMOTED_INTEGER_COLUMNS.each do |key|
+        self[key] = m[key].to_i if self[key].blank? && m[key].present?
+      end
+    end
+  end
+end
+```
+
+This works regardless of how footprints are created — via `TrackJob` (async), direct `.create!`, or the Rails console. The gem stays generic; your app adds the columns and promotion logic it needs.
 
 > [!TIP]
 > Which metadata keys to promote depends on your use case. A licensing SaaS might promote `device_id` + `app_version`. An e-commerce app might promote `product_id` + `session_id`. A CMS might promote `page_url` + `referrer`. Keep the JSONB for everything else.
@@ -276,6 +310,21 @@ When async is enabled, `track` and `track_<event_type>` calls enqueue a `Footpri
 
 You need a working ActiveJob backend (Sidekiq, Solid Queue, etc.) for this to work.
 
+### Geolocation in async mode
+
+When you pass `request:` in async mode, geolocation data is extracted **immediately** (before enqueueing) using Cloudflare headers via [`trackdown`](https://github.com/rameerez/trackdown). This means:
+
+- **No MaxMind database needed** in your background workers if you use Cloudflare
+- Geo data is captured at request time, not in the job
+- If `request:` is not passed, the job falls back to MaxMind lookup
+
+```ruby
+# In your controller — pass request: for Cloudflare geo extraction
+@product.track(:purchase, ip: request.remote_ip, request: request)
+```
+
+This is the recommended pattern for async mode behind Cloudflare.
+
 ## Geolocation via Trackdown
 
 `footprinted` automatically resolves geolocation data from IP addresses using the [`trackdown`](https://github.com/rameerez/trackdown) gem. For every footprint, the following fields are populated:

data/app/jobs/footprinted/track_job.rb

@@ -11,6 +11,13 @@ module Footprinted
       attrs = attributes.symbolize_keys
       attrs[:occurred_at] = Time.parse(attrs[:occurred_at]) if attrs[:occurred_at].is_a?(String)
 
+      # Log geo data status for debugging
+      if attrs[:country_code].present?
+        Rails.logger.debug { "[Footprinted] TrackJob received pre-extracted geo: #{attrs[:country_code]}/#{attrs[:city]}" }
+      else
+        Rails.logger.debug { "[Footprinted] TrackJob has no pre-extracted geo, will attempt lookup for #{attrs[:ip]}" }
+      end
+
       trackable.footprints.create!(attrs)
     end
   end

data/gemfiles/rails_7.2.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    footprinted (0.2.0)
+    footprinted (0.3.0)
       rails (>= 7.0)
       trackdown (~> 0.3)
 

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    footprinted (0.2.0)
+    footprinted (0.3.0)
       rails (>= 7.0)
       trackdown (~> 0.3)
 

data/lib/footprinted/{railtie.rb → engine.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Footprinted
-  class Railtie < Rails::Railtie
+  class Engine < Rails::Engine
     initializer "footprinted.initialize" do
       ActiveSupport.on_load(:active_record) do
         extend Footprinted::Model

data/lib/footprinted/model.rb

@@ -28,6 +28,7 @@ module Footprinted
           }
 
           if Footprinted.configuration.async
+            Footprinted::Model.enrich_with_geo_data!(attrs, ip, request)
             Footprinted::TrackJob.perform_later(
               self.class.name, id,
               attrs.merge(occurred_at: attrs[:occurred_at].iso8601)
@@ -52,6 +53,7 @@ module Footprinted
       }
 
       if Footprinted.configuration.async
+        Footprinted::Model.enrich_with_geo_data!(attrs, ip, request)
         Footprinted::TrackJob.perform_later(
           self.class.name, id,
           attrs.merge(occurred_at: attrs[:occurred_at].iso8601)
@@ -63,5 +65,27 @@ module Footprinted
         record
       end
     end
+
+    # Extract geo data from request (Cloudflare headers) before enqueueing
+    # This allows async jobs to have geo data without needing MaxMind
+    def self.enrich_with_geo_data!(attrs, ip, request)
+      return unless request && defined?(Trackdown)
+
+      location = Trackdown.locate(ip.to_s, request: request)
+      attrs.merge!(
+        country_code: location.country_code,
+        country_name: location.country_name,
+        city: location.city,
+        region: location.region,
+        continent: location.continent,
+        timezone: location.timezone,
+        latitude: location.latitude,
+        longitude: location.longitude
+      )
+
+      if location.country_code.present?
+        Rails.logger.debug { "[Footprinted] Extracted geo at enqueue: #{location.country_code}/#{location.city} for #{ip}" }
+      end
+    end
   end
 end

data/lib/footprinted/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Footprinted
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/footprinted.rb

@@ -25,4 +25,4 @@ module Footprinted
   end
 end
 
-require "footprinted/railtie" if defined?(Rails)
+require "footprinted/engine" if defined?(Rails)

data/lib/generators/footprinted/install_generator.rb

@@ -1,25 +1,46 @@
 # frozen_string_literal: true
 
-require 'rails/generators/base'
-require 'rails/generators/active_record'
+require "rails/generators/base"
+require "rails/generators/active_record"
 
 module Footprinted
   module Generators
     class InstallGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
 
-      source_root File.expand_path('templates', __dir__)
+      source_root File.expand_path("templates", __dir__)
 
-      def self.next_migration_number(dir)
-        ActiveRecord::Generators::Base.next_migration_number(dir)
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
       end
 
       def create_migration_file
-        migration_template 'create_footprinted_footprints.rb.erb', File.join(db_migrate_path, "create_footprinted_footprints.rb")
+        migration_template "create_footprinted_footprints.rb.erb",
+                           File.join(db_migrate_path, "create_footprinted_footprints.rb")
       end
 
       def create_initializer
-        template 'footprinted.rb', 'config/initializers/footprinted.rb'
+        template "footprinted.rb", "config/initializers/footprinted.rb"
+      end
+
+      def display_post_install_message
+        say "\n🎉 The `footprinted` gem has been successfully installed!", :green
+        say "\nTo complete the setup:"
+        say "  1. Run `rails db:migrate` to create the footprints table."
+        say "     ⚠️  You must run migrations before starting your app!", :yellow
+        say "\n  2. Add `include Footprinted::Model` to any model you want to track:"
+        say "       class Product < ApplicationRecord"
+        say "         include Footprinted::Model"
+        say "       end"
+        say "\n  3. Create footprints from your controllers or services:"
+        say "       product.footprints.create!("
+        say "         ip: request.remote_ip,"
+        say "         event_type: 'page_view',"
+        say "         occurred_at: Time.current"
+        say "       )"
+        say "\nSee the footprinted README for detailed usage and examples.", :cyan
+        say "Happy tracking! 👣\n", :green
       end
 
       private
@@ -27,7 +48,6 @@ module Footprinted
       def migration_version
         "[#{ActiveRecord::VERSION::STRING.to_f}]"
       end
-
     end
   end
 end

data/lib/generators/footprinted/templates/create_footprinted_footprints.rb.erb

@@ -1,4 +1,4 @@
-class CreateFootprintedFootprints < ActiveRecord::Migration<%%= migration_version %>
+class CreateFootprintedFootprints < ActiveRecord::Migration<%= migration_version %>
   def change
     primary_key_type, foreign_key_type = primary_and_foreign_key_types
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: footprinted
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-08 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -64,9 +64,9 @@ files:
 - gemfiles/rails_8.1.gemfile.lock
 - lib/footprinted.rb
 - lib/footprinted/configuration.rb
+- lib/footprinted/engine.rb
 - lib/footprinted/footprint.rb
 - lib/footprinted/model.rb
-- lib/footprinted/railtie.rb
 - lib/footprinted/version.rb
 - lib/generators/footprinted/install_generator.rb
 - lib/generators/footprinted/templates/create_footprinted_footprints.rb.erb