footprinted 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9896445daea0ce69e019da7472258e3c87035ce60245e8941de245edda8d3865
-  data.tar.gz: 3b858b7cc413344388f9e9ccacce615e0a0c56a3e461d87cc69204e52c722b04
+  metadata.gz: e0a6166d8616c0c1204631e17bc3ecf5c09cbff6fc94a38ee892061f2679b8c2
+  data.tar.gz: '0783420c75bf7f3736b0b4fcd84484281353f07d9fb89c1773066d25cb44dab7'
 SHA512:
-  metadata.gz: 60f7ecfda0afd96cbdbc67591d1c6e5687e02bce4d30f8b5f2b3fdaad61d5493332b3d2a6c8183a0fc960d8e78dfc124af7e934cacdc77558ec5eb3f04e6c772
-  data.tar.gz: 876c40969d9a9de55dfe8298808dc162519da408f578e20d6f5b66516e9c272696f82c4f232027ec92915c23cb6277dbf1a49e95a18d6e3ee56c072bce378ef2
+  metadata.gz: ff0f0e67acc390309d8d8491f43efa63d001ae58f72768d041b88f5842a231d76a444d129067dad4daffda702a5cd9d377d08be51c87cd9c76d079fb3f937a79
+  data.tar.gz: ff2e6a3705a726900cc0c4bca87ec9c07ca635f3a1ff02f67464affce02a9f5d179fca9f33714c1b7cf5ba1f80577770362ed94a0a9f342709f17e672fedf403

data/.simplecov

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+SimpleCov.start do
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  add_filter "/test/"
+
+  track_files "{lib,app}/**/*.rb"
+
+  enable_coverage :branch
+
+  minimum_coverage line: 80, branch: 65
+
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
+
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  puts "Branch Coverage: #{SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || 'N/A'}%"
+  puts "=" * 60
+end

data/Appraisals

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.2"
+end

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.2.0] - 2026-02-08
+
+**Full rewrite.** Breaking changes from v0.1.0.
+
+- Rename `TrackableActivity` → `Footprint` (new table: `footprints`)
+- Add `event_type` column for categorizing events (replaces multiple associations per type)
+- Add JSONB `metadata` column with GIN index for arbitrary event data
+- Add `performer` polymorphic reference (who triggered the event)
+- Add `occurred_at` timestamp (defaults to `Time.current`)
+- Add extended geo fields: `region`, `continent`, `timezone`, `latitude`, `longitude` (via trackdown 0.3+)
+- Add generic `track(:event_type, ip:)` method for ad-hoc events
+- Add scopes: `by_event`, `by_country`, `recent`, `last_days`, `between`, `performed_by`
+- Add class methods: `.event_types`, `.countries`
+- Add async mode with `Footprinted::TrackJob` (ActiveJob)
+- Require trackdown ~> 0.3 for full geo field support
+- Document JSONB performance at scale, column promotion pattern, and database compatibility
+
+### Breaking changes
+
+- Table renamed from `trackable_activities` to `footprints` — run the new generator and migrate
+- Model renamed from `Footprinted::TrackableActivity` to `Footprinted::Footprint`
+- `has_trackable` now creates `track_<singular>(ip:)` methods instead of the old API
+
 ## [0.1.0] - 2024-09-25
 
 - Initial release
@@ -7,4 +30,4 @@
 - Integrated with trackdown gem for IP geolocation
 - Added customizable tracking associations
 - Created install generator for easy setup
-- Added configuration options
+- Added configuration options

data/README.md

@@ -1,178 +1,344 @@
-# 👣 `footprinted` - Track geolocated user activity in Rails
+# 👣 `footprinted` - Simple event tracking for Rails apps
 
-`footprinted` provides a simple way to track user activity with associated IP addresses and geolocation data in your Rails app.
+[![Gem Version](https://badge.fury.io/rb/footprinted.svg)](https://badge.fury.io/rb/footprinted) [![Build Status](https://github.com/rameerez/footprinted/workflows/Tests/badge.svg)](https://github.com/rameerez/footprinted/actions)
 
-It's good for tracking profile views, downloads, login attempts, or any user interaction where location matters.
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=footprinted)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=footprinted)!
 
-## Why
+`footprinted` makes it trivial to add event tracking to any Rails model.
 
-Sometimes you need to know where your users are performing certain actions from.
-
-For example, let's say your users have profiles. Where has a particular profile been viewed from?
-
-This gem makes it trivial to track and analyze this kind of data:
+Think of a file transfer app like WeTransfer. You may want to track where every file download came from:
 
 ```ruby
-# First, add this to your User model
-has_trackable :profile_views
+# Add to your model
+has_trackable :downloads
 
-# Then, track the activity in the controller
-@user.track_profile_view(ip: request.remote_ip)
+# Track events in the controller
+@file.track_download(ip: request.remote_ip, metadata: { version: "2.1.0" })
 
-# And finally, analyze the data
-@user.profile_views.group(:country).count
-# => { 'US'=>529, 'UK'=>291, 'CA'=>78... }
+# Query the data
+@file.downloads.by_country("US").last_days(30).count
+# => 42
 ```
 
-That's it! This is all you need for `footprinted` to store the profile view along with the IP's geolocation data.
+In the example above, `footprinted` adds `footprints` to your `File` model, allowing you to easily record event data; and provides you with methods to build dashboards and analytics / business intelligence systems.
 
-> [!NOTE]
-> By adding `has_trackable :profile_views` to your model, `footprinted` automatically creates a `profile_views` association and a `track_profile_view` method to your User model.
->
-> `footprinted` does all the heavy lifting for you, so you don't need to define any models or associations. Just track and query.
+More use cases:
+- Track login attempts
+- Track profile views in a social app (think: LinkedIn)
+- Track document open events in a file-signing app (think: DocuSign)
+- Track any business-critical operation for enterprise-compliant audit logs
+- Track any interaction where knowing the *where* (IP, geolocation) or *what* (OS, app version, device ID...) matters
 
+Every event (footprint) in `footprinted` records the IP address, full geolocation data (country, city, region, coordinates, timezone), arbitrary JSONB metadata, and who triggered it — all resolved automatically via [`trackdown`](https://github.com/rameerez/trackdown). `footprinted` allows you to trivially build analytics dashboards and audit logs for all your app events.
 
-## How it works
+> [!NOTE]
+> By adding `has_trackable :downloads` to your model, `footprinted` automatically creates a `downloads` scoped association and a `track_download` method. No extra models or associations to define. Just track and query.
 
-`footprinted` relies on a `trackable_activities` table, and provides a model concern to interact with it.
+## Installation
 
-This model concern allows you to define polymorphic associations to store activity data associated with any model.
+Add this to your Gemfile:
 
-For each activity, `footprinted` stores:
-- IP address
-- Country
-- City
-- Activity type
-- Event timestamp
-- Optionally, an associated `performer` record, which could be a `user`, `admin`, or any other model. It answers the question: "who triggered this activity?"
+```ruby
+gem "footprinted"
+```
 
-`footprinted` also provides named methods that interact with the `trackable_activities` table to save and query this data.
+Then run:
 
-For example, `has_trackable :profile_views` will generate the `profile_views` association and the `track_profile_view` method. Similarly, `has_trackable :downloads` will generate the `downloads` association and the `track_download` method.
+```bash
+bundle install
+rails generate footprinted:install
+rails db:migrate
+```
 
-## Installation
+This creates the `footprints` table with columns for IP, geolocation fields, event type, JSONB metadata, polymorphic trackable/performer references, and all the necessary indexes.
 
 > [!IMPORTANT]
-> This gem depends on the [`trackdown`](https://github.com/rameerez/trackdown) gem for locating IPs.
->
-> **Start by following the `trackdown` README to install and configure the gem**, and make sure you have a valid installation with a working MaxMind database before continuing – otherwise we won't be able to get any geolocation data from IPs.
+> This gem depends on [`trackdown`](https://github.com/rameerez/trackdown) for IP geolocation. `trackdown` works out of the box with Cloudflare (zero config) and also supports MaxMind. See the [trackdown README](https://github.com/rameerez/trackdown) for setup instructions.
+
+## Quick Start
 
-After [`trackdown`](https://github.com/rameerez/trackdown) has been installed and configured, add this line to your application's Gemfile:
+Include the concern in any model you want to track activity on:
 
 ```ruby
-gem 'footprinted'
+class Product < ApplicationRecord
+  include Footprinted::Model
+
+  has_trackable :activations
+  has_trackable :downloads
+end
 ```
 
-And then execute:
+Track events in your controller:
 
-```bash
-bundle install
-rails generate footprinted:install
-rails db:migrate
+```ruby
+class DownloadsController < ApplicationController
+  def create
+    @product = Product.find(params[:product_id])
+    @product.track_download(ip: request.remote_ip, metadata: { version: params[:version] })
+  end
+end
 ```
 
-This will create a migration file to create the polymorphic `trackable_activities` table, and migrate the database.
+Query the data:
 
-## Usage
+```ruby
+@product.downloads.count                    # => 847
+@product.downloads.by_country("US").count   # => 529
+@product.downloads.last_days(7)             # recent downloads
+@product.downloads.countries                # => ["US", "UK", "CA", ...]
+```
 
-### Basic Setup
+## `has_trackable` DSL
 
-Include the `Footprinted::Model` concern and declare what you want to track:
+Declare one or more trackable event types on any model:
 
 ```ruby
-class User < ApplicationRecord
+class Resource < ApplicationRecord
   include Footprinted::Model
-  
-  # Track a single activity type
-  has_trackable :profile_views
-  
-  # Track multiple activity types
+
   has_trackable :downloads
-  has_trackable :login_attempts
+  has_trackable :previews
+  has_trackable :shares
 end
 ```
 
-### Recording Activity
+Each `has_trackable` call gives you:
 
-`footprinted` generates methods for you.
+- A **scoped association** (e.g., `resource.downloads`) that only returns footprints of that event type
+- A **track method** (e.g., `resource.track_download(ip:)`) that creates footprints with the correct event type
 
-For example, the `has_trackable :profile_views` association automatically provides you with a `track_profile_view` method that you can use:
+The association name is pluralized, and the track method is singularized:
 
-```ruby
-# Basic tracking with IP
-user.track_profile_view(ip: request.remote_ip)
+| Declaration | Association | Track method |
+|---|---|---|
+| `has_trackable :profile_views` | `.profile_views` | `.track_profile_view(ip:)` |
+| `has_trackable :downloads` | `.downloads` | `.track_download(ip:)` |
+| `has_trackable :login_attempts` | `.login_attempts` | `.track_login_attempt(ip:)` |
+
+### Track method parameters
 
-# Or track with a performer as well ("who triggered the activity?")
-user.track_profile_view(
-  ip: request.remote_ip,
-  performer: current_user
+```ruby
+@resource.track_download(
+  ip: request.remote_ip,          # Required: the IP address
+  request: request,               # Optional: passed to Trackdown for better geolocation
+  performer: current_user,        # Optional: who triggered this activity
+  metadata: { browser: "Chrome" },# Optional: arbitrary JSONB metadata
+  occurred_at: 2.hours.ago        # Optional: defaults to Time.current
 )
 ```
 
-### Querying Activity
+## Generic `track()` method
 
-#### Basic Queries
+For ad-hoc event types that don't need a dedicated association, use the generic `track` method:
 
 ```ruby
-# Basic queries
-user.profile_views.recent
-user.profile_views.last_days(7)
-user.profile_views.between(1.week.ago, Time.current)
+@user.track(:signup, ip: request.remote_ip)
+@user.track(:password_reset, ip: request.remote_ip, performer: admin)
+@user.track("api_call", ip: request.remote_ip, metadata: { endpoint: "/users" })
+```
 
-# Location queries
-user.profile_views.by_country('US')
-user.profile_views.countries  # => ['US', 'UK', 'CA', ...]
+It accepts the same parameters as `track_<event_type>` and works with both symbols and strings. All events tracked this way are accessible through the `footprints` association:
 
-# Performer queries
-user.profile_views.performed_by(some_user)
+```ruby
+@user.footprints.by_event("signup").count
 ```
 
-### Advanced Usage
+## Scopes
 
-Track multiple activity types:
+`footprinted` provides several useful scopes out of the box:
 
 ```ruby
-class Resource < ApplicationRecord
-  include Footprinted::Model
-  
-  has_trackable :downloads
-  has_trackable :previews
-end
+# Filter by event type
+@user.footprints.by_event("download")
+
+# Filter by country code
+@user.footprints.by_country("US")
 
-# Track activities
-product.track_download(ip: request.remote_ip)
-product.track_preview(ip: request.remote_ip)
+# Order by most recent
+@user.footprints.recent
 
-# Query activities
-product.downloads.count
-product.previews.last_days(30)
-product.downloads.between(1.week.ago, Time.current)
+# Time-based filtering
+@user.footprints.last_days(30)
+@user.footprints.between(1.week.ago, Time.current)
+
+# Filter by performer
+@user.footprints.performed_by(some_user)
 ```
 
-Time-based analysis:
+Scopes are chainable:
 
 ```ruby
-# Daily activity for the last 30 days
-resource.downloads
-  .where('created_at > ?', 30.days.ago)
-  .group("DATE(created_at)")
-  .count
-  .transform_keys { |k| k.strftime("%Y-%m-%d") }
-# => {"2024-03-26" => 5, "2024-03-25" => 3, ...}
+@user.profile_views
+  .by_country("US")
+  .last_days(7)
+  .performed_by(current_user)
+  .recent
+```
+
+### Class methods
+
+```ruby
+# Get all distinct event types
+Footprinted::Footprint.event_types
+# => ["view", "download", "login"]
+
+# Get all distinct country codes (excludes nil)
+Footprinted::Footprint.countries
+# => ["US", "UK", "CA", "DE"]
+```
+
+## JSONB metadata
+
+Every footprint can store arbitrary metadata as JSONB. This is great for device info, SDK versions, or any context you want to associate with the event:
+
+```ruby
+@product.track(:activation, ip: request.remote_ip, metadata: {
+  device_id: "A1B2C3",
+  app_version: "2.1.0",
+  platform: "macOS",
+  os_version: "15.2",
+  sdk_version: "0.4.0",
+  locale: "en_US"
+})
+```
 
-# Hourly distribution
-resource.downloads
-  .group("HOUR(created_at)")
+Query metadata using your database's JSON operators:
+
+```ruby
+# Find activations from macOS
+@product.footprints
+  .by_event("activation")
+  .where("metadata->>'platform' = ?", "macOS")
+
+# Group by app version
+@product.footprints
+  .by_event("activation")
+  .group("metadata->>'app_version'")
   .count
-# => {0=>10, 1=>5, 2=>8, ...}
+# => { "2.0.0" => 12, "2.1.0" => 45 }
+```
+
+### Performance at scale
+
+The default migration creates a [GIN index](https://www.postgresql.org/docs/current/gin-intro.html) on the `metadata` column. GIN indexes are excellent for **containment queries** (`@>`, `?`, `?|`) but do **not** speed up key extraction queries like `GROUP BY metadata->>'field'` or `COUNT(DISTINCT metadata->>'field')`.
+
+For small-to-medium tables (up to hundreds of thousands of rows), JSONB queries work just fine. At larger scale (millions of rows), if you're frequently grouping or counting distinct values on specific metadata keys, you have two options:
+
+**Option 1: Expression indexes** — add B-tree indexes on the specific JSONB keys you query most. No schema change needed:
+
+```ruby
+# In a migration in your host app
+add_index :footprints, "(metadata->>'device_id')", name: "idx_footprints_device_id"
+add_index :footprints, "(metadata->>'app_version')", name: "idx_footprints_app_version"
+```
+
+**Option 2: Promote to columns** — for your hottest query paths (e.g., `device_id` for DAU/MAU), add dedicated columns to the `footprints` table in your host app. This gives you proper B-tree indexes and fast `DISTINCT` counts:
+
+```ruby
+# In a migration in your host app
+add_column :footprints, :device_id,    :string
+add_column :footprints, :app_version,  :string
+add_column :footprints, :platform,     :string
+
+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.
+
+> [!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.
+
+### Database compatibility
+
+| Feature | PostgreSQL | MySQL 5.7+ | SQLite |
+|---|---|---|---|
+| JSONB `metadata` column | `jsonb` (native, fast) | `json` (native) | `text` (stored as string) |
+| GIN index on `metadata` | Supported | Not supported | Not supported |
+| JSON queries (`->>`, `@>`) | Full support | `JSON_EXTRACT()` syntax | `json_extract()` via extension |
+| Expression indexes | Supported | Supported (generated columns) | Not supported |
+
+PostgreSQL is the recommended database for `footprinted`. It has the best JSONB support, GIN indexes for containment queries, and expression indexes for key extraction. MySQL works but uses different JSON syntax. SQLite works for development and testing but stores metadata as text and has limited JSON query support.
+
+## Async mode with ActiveJob
+
+For high-traffic endpoints, you can enqueue footprint creation in the background:
+
+```ruby
+# config/initializers/footprinted.rb
+Footprinted.configure do |config|
+  config.async = true
+end
+```
+
+When async is enabled, `track` and `track_<event_type>` calls enqueue a `Footprinted::TrackJob` instead of writing to the database immediately. The job serializes all attributes (including metadata as a hash and occurred_at as ISO 8601) and processes them in the background.
+
+You need a working ActiveJob backend (Sidekiq, Solid Queue, etc.) for this to work.
+
+## 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:
+
+| Field | Example |
+|---|---|
+| `country_code` | `"US"` |
+| `country_name` | `"United States"` |
+| `city` | `"San Francisco"` |
+| `region` | `"California"` |
+| `continent` | `"NA"` |
+| `timezone` | `"America/Los_Angeles"` |
+| `latitude` | `37.7749` |
+| `longitude` | `-122.4194` |
+
+If geolocation fails (network error, invalid IP, etc.), the footprint is still saved — just without geolocation data. Errors are logged via `Rails.logger`.
+
+If you already know the `country_code`, you can set it directly and geolocation will be skipped:
+
+```ruby
+@user.track_profile_view(ip: "1.2.3.4", country_code: "DE")
+```
+
+## Configuration
+
+Create an initializer (the generator does this for you):
+
+```ruby
+# config/initializers/footprinted.rb
+Footprinted.configure do |config|
+  # Enqueue footprint creation via ActiveJob (default: false)
+  config.async = false
+end
+```
+
+## Generator
+
+The install generator creates two things:
+
+1. A migration for the `footprints` table with all geolocation columns, polymorphic references, JSONB metadata, indexes, and a composite index on `[trackable_type, trackable_id, event_type, occurred_at]`
+2. An initializer at `config/initializers/footprinted.rb`
+
+```bash
+rails generate footprinted:install
+rails db:migrate
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
+### Releasing a new version
+
+When bumping the version, update all three of these together:
+
+1. `lib/footprinted/version.rb` — the version constant
+2. `gemfiles/*.gemfile.lock` — run `bundle exec appraisal install` to regenerate
+3. `test/footprinted/version_test.rb` — the hardcoded version assertion
+
+CI will fail if any of these are out of sync.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/footprinted. Our code of conduct is: just be nice and make your mom proud of what you do and post online.

data/Rakefile

@@ -1,4 +1,12 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/app/jobs/footprinted/track_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Footprinted
+  class TrackJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(trackable_type, trackable_id, attributes)
+      trackable = trackable_type.constantize.find_by(id: trackable_id)
+      return unless trackable
+
+      attrs = attributes.symbolize_keys
+      attrs[:occurred_at] = Time.parse(attrs[:occurred_at]) if attrs[:occurred_at].is_a?(String)
+
+      trackable.footprints.create!(attrs)
+    end
+  end
+end

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,28 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.2.0"
+
+group :development do
+  gem "irb"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :development, :test do
+  gem "appraisal"
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "minitest-reporters", "~> 1.6"
+  gem "mocha", "~> 2.0"
+  gem "rack-test"
+  gem "sqlite3", ">= 2.1"
+  gem "ostruct"
+  gem "webmock", "~> 3.19"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"