footprinted 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9896445daea0ce69e019da7472258e3c87035ce60245e8941de245edda8d3865
+  data.tar.gz: 3b858b7cc413344388f9e9ccacce615e0a0c56a3e461d87cc69204e52c722b04
+SHA512:
+  metadata.gz: 60f7ecfda0afd96cbdbc67591d1c6e5687e02bce4d30f8b5f2b3fdaad61d5493332b3d2a6c8183a0fc960d8e78dfc124af7e934cacdc77558ec5eb3f04e6c772
+  data.tar.gz: 876c40969d9a9de55dfe8298808dc162519da408f578e20d6f5b66516e9c272696f82c4f232027ec92915c23cb6277dbf1a49e95a18d6e3ee56c072bce378ef2

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0] - 2024-09-25
+
+- Initial release
+- Added Trackable concern for easy activity tracking
+- Integrated with trackdown gem for IP geolocation
+- Added customizable tracking associations
+- Created install generator for easy setup
+- Added configuration options

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Javi R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,182 @@
+# 👣 `footprinted` - Track geolocated user activity in Rails
+
+`footprinted` provides a simple way to track user activity with associated IP addresses and geolocation data in your Rails app.
+
+It's good for tracking profile views, downloads, login attempts, or any user interaction where location matters.
+
+## Why
+
+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:
+
+```ruby
+# First, add this to your User model
+has_trackable :profile_views
+
+# Then, track the activity in the controller
+@user.track_profile_view(ip: request.remote_ip)
+
+# And finally, analyze the data
+@user.profile_views.group(:country).count
+# => { 'US'=>529, 'UK'=>291, 'CA'=>78... }
+```
+
+That's it! This is all you need for `footprinted` to store the profile view along with the IP's geolocation data.
+
+> [!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.
+
+
+## How it works
+
+`footprinted` relies on a `trackable_activities` table, and provides a model concern to interact with it.
+
+This model concern allows you to define polymorphic associations to store activity data associated with any model.
+
+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?"
+
+`footprinted` also provides named methods that interact with the `trackable_activities` table to save and query this data.
+
+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.
+
+## Installation
+
+> [!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.
+
+After [`trackdown`](https://github.com/rameerez/trackdown) has been installed and configured, add this line to your application's Gemfile:
+
+```ruby
+gem 'footprinted'
+```
+
+And then execute:
+
+```bash
+bundle install
+rails generate footprinted:install
+rails db:migrate
+```
+
+This will create a migration file to create the polymorphic `trackable_activities` table, and migrate the database.
+
+## Usage
+
+### Basic Setup
+
+Include the `Footprinted::Model` concern and declare what you want to track:
+
+```ruby
+class User < ApplicationRecord
+  include Footprinted::Model
+  
+  # Track a single activity type
+  has_trackable :profile_views
+  
+  # Track multiple activity types
+  has_trackable :downloads
+  has_trackable :login_attempts
+end
+```
+
+### Recording Activity
+
+`footprinted` generates methods for you.
+
+For example, the `has_trackable :profile_views` association automatically provides you with a `track_profile_view` method that you can use:
+
+```ruby
+# Basic tracking with IP
+user.track_profile_view(ip: request.remote_ip)
+
+# Or track with a performer as well ("who triggered the activity?")
+user.track_profile_view(
+  ip: request.remote_ip,
+  performer: current_user
+)
+```
+
+### Querying Activity
+
+#### Basic Queries
+
+```ruby
+# Basic queries
+user.profile_views.recent
+user.profile_views.last_days(7)
+user.profile_views.between(1.week.ago, Time.current)
+
+# Location queries
+user.profile_views.by_country('US')
+user.profile_views.countries  # => ['US', 'UK', 'CA', ...]
+
+# Performer queries
+user.profile_views.performed_by(some_user)
+```
+
+### Advanced Usage
+
+Track multiple activity types:
+
+```ruby
+class Resource < ApplicationRecord
+  include Footprinted::Model
+  
+  has_trackable :downloads
+  has_trackable :previews
+end
+
+# Track activities
+product.track_download(ip: request.remote_ip)
+product.track_preview(ip: request.remote_ip)
+
+# Query activities
+product.downloads.count
+product.previews.last_days(30)
+product.downloads.between(1.week.ago, Time.current)
+```
+
+Time-based analysis:
+
+```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, ...}
+
+# Hourly distribution
+resource.downloads
+  .group("HOUR(created_at)")
+  .count
+# => {0=>10, 1=>5, 2=>8, ...}
+```
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## 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.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/TODO

@@ -0,0 +1,3 @@
+✘ Add index on users t.index ["user_id"], name: "index_trackable_activities_on_user_id" @cancelled(24-09-26 16:59)
+✔ make user:references optional in migration (activities may not have an associated user) -- or just make it more flexible, like a performer polymorphic association or something @done(24-10-30 01:35)
+✔ can they have multiple activity types per model? (user: profile_views, downloads, etc) @done(24-09-26 17:28)

data/lib/footprinted/configuration.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Footprinted
+  class Configuration
+
+    def initialize
+      # No configuration options yet
+    end
+  end
+end

data/lib/footprinted/model.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Footprinted
+  module Model
+    extend ActiveSupport::Concern
+
+    # The Footprinted::Model module provides a flexible way to track activities related to any model that includes this concern.
+    #
+    # Footprinted tracks activities through a polymorphic association: the Footprinted::TrackableActivity model.
+    #
+    # The Footprinted::Model concern sets up a :trackable_activities association using the
+    # Footprinted::TrackableActivity model.
+    #
+    # It also provides a basic method to track unnamed activities, `track_activity`,
+    # which can be used as is (not recommended) or overridden with a custom activity type:
+    #
+    # Track specific types of activities using the `has_trackable` class method.
+    # This method also dynamically defines a method to create activity records for the custom association.
+    # For example, `has_trackable :profile_views` generates the `track_profile_view` method.
+    #
+    # Example:
+    #   class YourModel < ApplicationRecord
+    #     include Trackable
+    #     has_trackable :profile_views
+    #   end
+    #
+    # The above will:
+    # - Create a `has_many :profile_views` association.
+    # - Define a method `track_profile_view` (singular) to create records in `profile_views`.
+    #
+    #
+    # Methods:
+    #
+    # - has_trackable(association_name): Sets up a custom association for tracking activities.
+    #   This method dynamically defines a tracking method based on the given association name.
+    #
+    # - track_activity(ip, user = nil): Default method provided to track activities. It logs
+    #   the IP address, and optionally, the user involved in the activity. This method can be
+    #   overridden in the model including this module for custom behavior.
+    #
+    # Note:
+    # The Footprinted::TrackableActivity model must exist and have a polymorphic association set up
+    # with the :trackable attribute for this concern to function correctly.
+
+    included do
+      has_many :trackable_activities, as: :trackable, class_name: 'Footprinted::TrackableActivity', dependent: :destroy
+    end
+
+    class_methods do
+      # Method to set custom association names
+      def has_trackable(association_name)
+        track_method_name = "track_#{association_name.to_s.singularize}"
+
+        has_many association_name, -> { where(activity_type: association_name.to_s.singularize) },
+                 as: :trackable, class_name: 'Footprinted::TrackableActivity'
+
+        # Define a custom method for tracking activities of this type
+        define_method(track_method_name) do |ip:, performer: nil|
+          send(association_name).create!(
+            ip: ip,
+            performer: performer,
+            activity_type: association_name.to_s.singularize
+          )
+        end
+      end
+    end
+
+    # Fallback method for tracking activity. This will be overridden if has_trackable is called.
+    def track_activity(ip:, user: nil, activity_type: nil)
+      trackable_activities.create(ip: ip, user: user, activity_type: activity_type)
+    end
+  end
+end

data/lib/footprinted/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Footprinted
+  class Railtie < Rails::Railtie
+    initializer "footprinted.initialize" do
+      ActiveSupport.on_load(:active_record) do
+        extend Footprinted::Model
+      end
+    end
+
+    generators do
+      require "generators/footprinted/install_generator"
+    end
+  end
+end

data/lib/footprinted/trackable_activity.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Footprinted
+  class TrackableActivity < ActiveRecord::Base
+    # Associations
+    belongs_to :trackable, polymorphic: true
+    belongs_to :performer, polymorphic: true, optional: true
+
+    # Validations
+    validates :ip, presence: true
+    validates :activity_type, presence: true
+    validates :trackable, presence: true
+
+    # Callbacks
+    before_save :set_geolocation_data
+
+    # Scopes
+    scope :by_activity, ->(type) { where(activity_type: type) }
+    scope :by_country, ->(country) { where(country: country) }
+    scope :recent, -> { order(created_at: :desc) }
+    scope :performed_by, ->(performer) { where(performer: performer) }
+    scope :between, ->(start_date, end_date) { where(created_at: start_date..end_date) }
+    scope :last_days, ->(days) { where('created_at >= ?', days.days.ago) }
+
+    # Class methods
+    def self.activity_types
+      distinct.pluck(:activity_type)
+    end
+
+    def self.countries
+      distinct.where.not(country: nil).pluck(:country)
+    end
+
+    private
+
+    def set_geolocation_data
+      return unless ip.present?
+
+      unless defined?(Trackdown)
+        raise Footprinted::Error, "The Trackdown gem is not installed. Please add `gem 'trackdown'` to your Gemfile and follow the setup instructions to configure the gem and download an IP geolocation database."
+      end
+
+      unless Trackdown.database_exists?
+        raise Footprinted::Error, "MaxMind IP geolocation database not found. Please follow the Trackdown gem setup instructions to configure the gem and download an IP geolocation database."
+      end
+
+      location = Trackdown.locate(ip.to_s)
+      self.country = location.country_code
+      self.city = location.city
+    rescue => e
+      Rails.logger.error "Failed to geolocate IP #{ip}: #{e.message}"
+      nil # Don't fail the save if geolocation fails
+    end
+  end
+end

data/lib/footprinted/version.rb

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

data/lib/footprinted.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "footprinted/version"
+require_relative "footprinted/configuration"
+require_relative "footprinted/model"
+require_relative "footprinted/trackable_activity"
+
+module Footprinted
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset
+    @configuration = Configuration.new
+  end
+end
+
+require "footprinted/railtie" if defined?(Rails)

data/lib/generators/footprinted/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+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__)
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template 'create_footprinted_trackable_activities.rb.erb', File.join(db_migrate_path, "create_footprinted_trackable_activities.rb")
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+class CreateFootprintedTrackableActivities < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :trackable_activities, id: primary_key_type do |t|
+      t.inet :ip, null: false
+      t.text :country
+      t.text :city
+      t.references :trackable, polymorphic: true, null: false, type: foreign_key_type, index: true
+      t.references :performer, polymorphic: true, type: foreign_key_type, index: true
+      t.text :activity_type, null: false
+
+      t.timestamps
+    end
+
+    add_index :trackable_activities, [:trackable_type, :trackable_id, :activity_type]
+    add_index :trackable_activities, :activity_type
+    add_index :trackable_activities, :country
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+end

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

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+Footprinted.configure do |config|
+end

data/sig/footprinted.rbs

@@ -0,0 +1,4 @@
+module Footprinted
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: footprinted
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-10-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: trackdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: Track user activity with associated IP addresses and geolocation info,
+  easily and with minimal setup. It's good for tracking profile views, downloads,
+  login attempts, or any user interaction where location matters.
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODO
+- lib/footprinted.rb
+- lib/footprinted/configuration.rb
+- lib/footprinted/model.rb
+- lib/footprinted/railtie.rb
+- lib/footprinted/trackable_activity.rb
+- lib/footprinted/version.rb
+- lib/generators/footprinted/install_generator.rb
+- lib/generators/footprinted/templates/create_footprinted_trackable_activities.rb.erb
+- lib/generators/footprinted/templates/footprinted.rb
+- sig/footprinted.rbs
+homepage: https://github.com/rameerez/footprinted
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rameerez/footprinted
+  source_code_uri: https://github.com/rameerez/footprinted
+  changelog_uri: https://github.com/rameerez/footprinted/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Track IP-geolocated user activity in your Rails app
+test_files: []