footprinted 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2969bfdd4365c5aa27fe37a0a74d77283ad0b0053c221442496fd837fd210bfa
-  data.tar.gz: 37992d2955029ec6b2e03aa841bb5f06f5d0acf868819ffd2ac56bbc2b38b6de
+  metadata.gz: 20ea0ce295c5fe9031013e323a46e744b92de81e6e433db994dc4df485373e31
+  data.tar.gz: '09c5e324348d00dcb53b8fbe7e581e22ee45e9d194f706d48685678cc999359a'
 SHA512:
-  metadata.gz: e72627f90b0b0357ef8fffccbea1c1ae6204ccbc45144f5f992dbfdb3cc4d6716413ea173f22996412eea7f49023f6078c6841f67324b5a76ab40e18ad4d99f6
-  data.tar.gz: 88ef984e78aa8b40fd634e4beb7be934dd3187aa2d8391b1da754cd981b64a6e48766211239d20264c87948300b0abfbf0037500189d8f0332e6616142afcccb
+  metadata.gz: 69f4c70cdddadd0bcf208bcecc337ab484ae5ac6991748488e4620a5d712c69ae6b444b26ceb6c0ad10a036c4652185a938509c203348d16b5cac0a28ae9c7a4
+  data.tar.gz: 5aaa74017232c3f54cc6db64155d75d762a7f758f04a7e886474e7af9cd579173264c744447f86f0eae56b84b096cb984f462bd40105e35a1ea80e1e8283448f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

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.1)
+    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.1)
+    footprinted (0.3.0)
       rails (>= 7.0)
       trackdown (~> 0.3)
 

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.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: footprinted
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-09 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails