action_trace 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bc6e731d0e4f118c4d01db6af5ac7831064772beb3057ab66f6fdbfc0d5b4f8
-  data.tar.gz: 72c40aeedbfad2d1d6ff189ff5f5279e2783059f9b79f57c1b338acfa9602a12
+  metadata.gz: ac6e3bcd7ddba0d325500935c892b7832116e9f53035b352e757e258fb5b28d4
+  data.tar.gz: ddc86843cab5355f2c08b8134048b9d2e6bb00771112570ae037b44a59ca4e4e
 SHA512:
-  metadata.gz: 03aef93ad7fbcf10ae77298cbced45c404841dfd425b981f83568c391d4e3ef343257f0390acd37f173aa56a37d15e59b3155c2788f4934f0e48c73eec7b7528
-  data.tar.gz: ee0004fbbee480dc067768dbc2804e06e13abb94fa894e98d4b7ee45274d0ed6972bef6a4d60528c5d0aca2ed4c30ffd728b46feb5e20ac209cac91663c2ec77
+  metadata.gz: 8f4a13e9befd1d7a05e99acd17cbb3521004cdc4e2ede8e2d0fc9f49f2c176f45a7d20a7a280fc017895927c6e69513b744a479350a109359537927b6067cfc2
+  data.tar.gz: ab8913e299894c6c8868384e96a1056d859ae0368e85eb214c57e745808eddad16889f1cf7290b24f0a1afc4ae578c666994461f5ccf5008fa98cd253be1ce73

data/README.md

@@ -1,9 +1,8 @@
 # ActionTrace
 
-ActionTrace is a Rails engine that consolidates user interaction tracking into a single integration point.
-It glues together [public_activity](https://github.com/chaps-io/public_activity), [ahoy_matey](https://github.com/ankane/ahoy), [paper_trail](https://github.com/paper-trail-gem/paper_trail), and [discard](https://github.com/jhawthorn/discard) so you don't have to configure each one individually.
+[![Gem Version](https://badge.fury.io/rb/action_trace.svg)](https://rubygems.org/gems/action_trace)
 
-## What it tracks
+ActionTrace is a Rails engine that consolidates user interaction tracking into a single integration point. Instead of configuring [public_activity](https://github.com/chaps-io/public_activity), [ahoy_matey](https://github.com/ankane/ahoy), [paper_trail](https://github.com/paper-trail-gem/paper_trail), and [discard](https://github.com/jhawthorn/discard) individually, ActionTrace wires them together and exposes a unified activity log with a ready-to-use UI.
 
 | Source | Description | Backed by |
 |---|---|---|
@@ -14,6 +13,8 @@ It glues together [public_activity](https://github.com/chaps-io/public_activity)
 | `session_start` | User session begun | ahoy_matey (visit) |
 | `session_end` | User logged out | ahoy_matey (event) |
 
+---
+
 ## Installation
 
 Add to your Gemfile:
@@ -30,18 +31,16 @@ rails generate action_trace:install
 rails db:migrate
 ```
 
-The installer runs the setup generators for all four gems and creates `config/initializers/action_trace.rb`.
+The installer runs the setup generators for all four underlying gems and creates `config/initializers/action_trace.rb`.
 
 ### Skipping already-installed gems
 
-If one or more of the underlying gems is already set up, pass `--skip-*` flags:
+If one or more of the underlying gems is already configured, pass `--skip-*` flags:
 
 ```bash
 rails generate action_trace:install --skip-ahoy --skip-paper-trail
 ```
 
-Available flags:
-
 | Flag | Skips |
 |---|---|
 | `--skip-ahoy` | `ahoy:install` |
@@ -64,38 +63,54 @@ GET  /action_trace/activity_logs
 POST /action_trace/activity_logs/filter
 ```
 
-The controller inherits from the host app's `ApplicationController`. Authentication and authorization are not enforced by default — copy the controller with the generator and uncomment the relevant lines for your setup (e.g. Devise's `authenticate_user!`, CanCanCan's `load_and_authorize_resource`).
+### Copy views and controller (optional)
 
-## Configuration
+ActionTrace ships minimal default views that work out of the box. Copy them into your app to customise the UI:
 
-`config/initializers/action_trace.rb` is generated automatically. Available options:
+```bash
+# Copy views only
+rails generate action_trace:views
 
-```ruby
-ActionTrace.configure do |config|
-  # Controller names to exclude from page_visit tracking (default: [])
-  config.excluded_controllers = %w[health_checks status]
+# Copy views and controller
+rails generate action_trace:views --controller
+```
 
-  # Action names to exclude from page_visit tracking (default: [])
-  config.excluded_actions = %w[ping]
+Views are placed in `app/views/action_trace/activity_logs/`. Rails will use your copies instead of the engine defaults.
 
-  # The user model class name used to resolve company filtering
-  # for PublicActivity::Activity, Ahoy::Visit and Ahoy::Event (default: 'User')
-  config.user_class = 'User'
+The `--controller` flag also copies `ActivityLogsController` to `app/controllers/action_trace/activity_logs_controller.rb`. The file includes commented-out lines for Devise and CanCanCan authentication — uncomment what applies to your setup or replace with your own auth logic.
 
-  # How long to retain activity records before purging (default: 1.year)
-  config.log_retention_period = 6.months
+> **Note:** once you copy the controller, the engine's version is no longer used. Future updates to the engine's controller will not be applied automatically — keep that in mind when upgrading.
+
+---
+
+## Usage
+
+### Models — tracking data changes
+
+Include `ActionTrace::DataTrackable` in any ActiveRecord model you want to track:
+
+```ruby
+class Document < ApplicationRecord
+  include ActionTrace::DataTrackable
 end
 ```
 
-> `user_class` must have a `company_id` column. ActionTrace uses it to filter
-> activity records through the user when filtering by company (since those
-> models store the user reference rather than a direct `company_id`).
+This records a `public_activity` event on every `create`, `update`, and `destroy`, linked to the current user (via `PublicActivity.get_controller`) and, when paper_trail is active, to the corresponding version.
 
-## Usage
+For paper_trail versioning to work, the model also needs `has_paper_trail`:
 
-### Track page visits — controller concern
+```ruby
+class Document < ApplicationRecord
+  include ActionTrace::DataTrackable
+  has_paper_trail
+end
+```
+
+For soft-delete tracking with discard, add `include Discard::Model` alongside `DataTrackable`. The `data_destroy` event is still recorded via the `before_destroy` callback.
 
-Include `ActivityTrackable` in any controller (or `ApplicationController`):
+### Controllers — tracking page visits and sessions
+
+Include `ActivityTrackable` in any controller (or `ApplicationController`) to track page visits:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -103,34 +118,32 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-This adds an `after_action :track_action` that records a `page_visit` event via Ahoy for every successful request made by a logged-in user.
+This adds an `after_action :track_action` that records a `page_visit` event via Ahoy for every successful request made by a logged-in user. It also includes `PublicActivity::StoreController`, which makes the current controller available to model callbacks so that data events can be linked to the right user.
 
-To record a session end on logout, call `track_session_end` in your sessions controller before clearing the session:
+To skip tracking on a specific controller that inherits from `ApplicationController`:
 
 ```ruby
-class SessionsController < Devise::SessionsController
-  def destroy
-    track_session_end
-    super
-  end
+class HealthChecksController < ApplicationController
+  skip_after_action :track_action
 end
 ```
 
-### Track model changes — model concern
-
-Include `ActionTrace::DataTrackable` in any ActiveRecord model:
+To record a session end on logout, call `track_session_end` before clearing the session:
 
 ```ruby
-class Document < ApplicationRecord
-  include ActionTrace::DataTrackable
+class SessionsController < Devise::SessionsController
+  def destroy
+    track_session_end
+    super
+  end
 end
 ```
 
-This records a `public_activity` event on every `create`, `update`, and `destroy`, linked to the current user (via `PublicActivity.get_controller`) and, when paper_trail is active, to the corresponding version.
+The engine's `ActivityLogsController` inherits from the host app's `ApplicationController`. Authentication and authorization are not enforced by default — copy the controller with the generator and uncomment the relevant lines for your setup (e.g. Devise's `authenticate_user!`, CanCanCan's `load_and_authorize_resource`).
 
-### Query activity logs
+### Querying activity logs directly
 
-Use `ActionTrace::FetchActivityLogs` directly to fetch and paginate unified activity:
+Use `ActionTrace::FetchActivityLogs` to fetch and paginate the unified activity log programmatically:
 
 ```ruby
 result = ActionTrace::FetchActivityLogs.call(
@@ -163,43 +176,39 @@ Each `ActionTrace::ActivityLog` exposes:
 | `trackable` | ActiveRecord object | The changed record (data events only) |
 | `trackable_type` | String | Class name of the changed record |
 
-#### Presenter helpers
-
-`ActionTrace::ActivityLog` also provides:
+Presenter helpers are also available on each log:
 
 ```ruby
-log.icon    # => 'fas fa-pencil-alt'
-log.color   # => 'text-primary'
+log.icon           # => 'fas fa-pencil-alt'
+log.color          # => 'text-primary'
 log.data_change?   # => true / false
 log.page_visit?    # => true / false
-# … (data_create?, data_destroy?, session_start?)
+# data_create?, data_destroy?, session_start?, session_end?
 ```
 
-## Customizing views and controller
-
-ActionTrace ships minimal default views for `activity_logs#index`. These work out of the box but are intentionally bare — copy them into your app to customize the UI.
+### Configuration
 
-### Copy views
+`config/initializers/action_trace.rb` is generated automatically. Available options:
 
-```bash
-rails generate action_trace:views
-```
+```ruby
+ActionTrace.configure do |config|
+  # Controller names to exclude from page_visit tracking (default: [])
+  config.excluded_controllers = %w[health_checks status]
 
-This copies the engine views to `app/views/action_trace/activity_logs/` in your application. Rails will use your copies instead of the engine defaults.
+  # Action names to exclude from page_visit tracking (default: [])
+  config.excluded_actions = %w[ping]
 
-### Copy views and controller
+  # The user model class name used to resolve company filtering (default: 'User')
+  config.user_class = 'User'
 
-```bash
-rails generate action_trace:views --controller
+  # How long to retain activity records before purging (default: 1.year)
+  config.log_retention_period = 6.months
+end
 ```
 
-Also copies `ActivityLogsController` to `app/controllers/action_trace/activity_logs_controller.rb`. The file includes commented-out lines for Devise and CanCanCan — uncomment what applies to your setup, or replace with your own auth logic.
-
-> After copying the controller, the engine's version is no longer used. Any future updates to the engine's controller will not be applied automatically — keep that in mind when upgrading.
+> `user_class` must have a `company_id` column. ActionTrace uses it to filter activity records by company (since Ahoy and PublicActivity store the user reference rather than a direct `company_id`).
 
-## Maintenance
-
-### Purge old records
+### Purging old records
 
 `ActionTrace::PurgeActivityLogJob` removes all `PublicActivity::Activity`, `Ahoy::Event`, and `Ahoy::Visit` records older than `log_retention_period` (default: 1 year). Schedule it with your preferred job scheduler:
 
@@ -208,6 +217,8 @@ Also copies `ActivityLogsController` to `app/controllers/action_trace/activity_l
 ActionTrace::PurgeActivityLogJob.perform_later
 ```
 
+---
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/interactors/action_trace/fetch_activity_logs.rb

@@ -2,7 +2,7 @@
 
 module ActionTrace
   class FetchActivityLogs
-    include Interactor::Organizer
+    include ::Interactor::Organizer
 
     organize ActionTrace::InitializeContext,
              ActionTrace::FetchDataChanges,

data/app/interactors/action_trace/fetch_data_changes.rb

@@ -2,7 +2,7 @@
 
 module ActionTrace
   class FetchDataChanges
-    include Interactor
+    include ::Interactor
     include ActivityLogFetchable
 
     def call

data/app/interactors/action_trace/fetch_page_visits.rb

@@ -2,7 +2,7 @@
 
 module ActionTrace
   class FetchPageVisits
-    include Interactor
+    include ::Interactor
     include ActivityLogFetchable
 
     def call

data/app/interactors/action_trace/fetch_session_starts.rb

@@ -2,7 +2,7 @@
 
 module ActionTrace
   class FetchSessionStarts
-    include Interactor
+    include ::Interactor
     include ActivityLogFetchable
 
     def call

data/app/interactors/action_trace/initialize_context.rb

@@ -2,7 +2,7 @@
 
 module ActionTrace
   class InitializeContext
-    include Interactor
+    include ::Interactor
 
     def call
       filters = context.filters || {}

data/app/interactors/action_trace/merge_and_format_results.rb

@@ -2,7 +2,7 @@
 
 module ActionTrace
   class MergeAndFormatResults
-    include Interactor
+    include ::Interactor
     include ActivityLogFetchable
 
     def call

data/app/models/ahoy/event.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class Ahoy::Event < ApplicationRecord
+  include Ahoy::QueryMethods
+
+  self.table_name = "ahoy_events"
+
+  belongs_to :visit, class_name: "Ahoy::Visit"
+  belongs_to :user, optional: true
+end

data/app/models/ahoy/visit.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class Ahoy::Visit < ApplicationRecord
+  self.table_name = "ahoy_visits"
+
+  has_many :events, class_name: "Ahoy::Event"
+  belongs_to :user, optional: true
+end

data/lib/action_trace/engine.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require 'public_activity'
+require 'ahoy_matey'
+require 'paper_trail'
+
 module ActionTrace
   class Engine < ::Rails::Engine
     isolate_namespace ActionTrace
@@ -29,4 +33,4 @@ module ActionTrace
       end
     end
   end
-end
+end

data/lib/action_trace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionTrace
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

data/lib/action_trace.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'interactor'
 require 'action_trace/version'
 require 'action_trace/configuration'
 require 'action_trace/engine'

data/lib/generators/action_trace/install/install_generator.rb

@@ -5,6 +5,18 @@ require 'rails/generators'
 module ActionTrace
   module Generators
     class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.source_paths
+        [File.expand_path('templates', __dir__), File.expand_path(__dir__)]
+      end
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
       desc 'Install ActionTrace and all its dependencies'
 
       class_option :skip_ahoy,            type: :boolean, default: false,

data/lib/generators/action_trace/views/views_generator.rb

@@ -22,7 +22,7 @@ module ActionTrace
         return unless options[:controller]
 
         copy_file(
-          File.expand_path('../../../../../app/controllers/action_trace/activity_logs_controller.rb', __dir__),
+          File.expand_path('../../../../app/controllers/action_trace/activity_logs_controller.rb', __dir__),
           'app/controllers/action_trace/activity_logs_controller.rb'
         )
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_trace
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - gimbaro
@@ -247,6 +247,8 @@ files:
 - app/jobs/action_trace/purge_activity_log_job.rb
 - app/models/action_trace/activity_log.rb
 - app/models/action_trace/application_record.rb
+- app/models/ahoy/event.rb
+- app/models/ahoy/visit.rb
 - app/models/concerns/action_trace/data_trackable.rb
 - app/presenters/action_trace/activity_log_presenter.rb
 - app/views/action_trace/activity_logs/_activity_log.html.erb
@@ -291,7 +293,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.8
 specification_version: 4
 summary: A Rails engine that consolidates user interaction tracking into a single
   integration