action_trace 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1ffc77c240d4ab390847ceb3bcaf692655b9e10cdfb46371c4cdc3188e49313
-  data.tar.gz: 72e721d26724869b7d2cbd4afef6d0ae5b54609615d779ef974e05ebf21d5d56
+  metadata.gz: ac6e3bcd7ddba0d325500935c892b7832116e9f53035b352e757e258fb5b28d4
+  data.tar.gz: ddc86843cab5355f2c08b8134048b9d2e6bb00771112570ae037b44a59ca4e4e
 SHA512:
-  metadata.gz: 26dbcdfbe1bc91a5ebec2f55e1f3e6d8cc7a31305998a3092f6c29b2f96237c7e7707c88cdd8c87e7dc1560a453b91df3fb23b4493d8e9078ff18fdba8d9b65b
-  data.tar.gz: e2523e6faa5dc44f365db5e9ba75b99a7f772587b2815ae2592be3e621a2015ba6cd89a4cec64b16a319ebd34fb381fa4209e8448eb4b88c0def335bc27f86de
+  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/lib/action_trace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionTrace
-  VERSION = '0.2.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/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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - gimbaro
@@ -293,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