action_trace 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4bc6e731d0e4f118c4d01db6af5ac7831064772beb3057ab66f6fdbfc0d5b4f8
+  data.tar.gz: 72c40aeedbfad2d1d6ff189ff5f5279e2783059f9b79f57c1b338acfa9602a12
+SHA512:
+  metadata.gz: 03aef93ad7fbcf10ae77298cbced45c404841dfd425b981f83568c391d4e3ef343257f0390acd37f173aa56a37d15e59b3155c2788f4934f0e48c73eec7b7528
+  data.tar.gz: ee0004fbbee480dc067768dbc2804e06e13abb94fa894e98d4b7ee45274d0ed6972bef6a4d60528c5d0aca2ed4c30ffd728b46feb5e20ac209cac91663c2ec77

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright gimbaro
+
+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,213 @@
+# 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.
+
+## What it tracks
+
+| Source | Description | Backed by |
+|---|---|---|
+| `data_create` | Model created | public_activity |
+| `data_change` | Model updated | public_activity + paper_trail |
+| `data_destroy` | Model destroyed | public_activity |
+| `page_visit` | Controller action visited | ahoy_matey |
+| `session_start` | User session begun | ahoy_matey (visit) |
+| `session_end` | User logged out | ahoy_matey (event) |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "action_trace"
+```
+
+Then run:
+
+```bash
+bundle install
+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`.
+
+### Skipping already-installed gems
+
+If one or more of the underlying gems is already set up, pass `--skip-*` flags:
+
+```bash
+rails generate action_trace:install --skip-ahoy --skip-paper-trail
+```
+
+Available flags:
+
+| Flag | Skips |
+|---|---|
+| `--skip-ahoy` | `ahoy:install` |
+| `--skip-paper-trail` | `paper_trail:install` |
+| `--skip-public-activity` | `public_activity:migration` |
+| `--skip-discard` | discard initializer entry |
+
+### Mount the engine
+
+In `config/routes.rb`:
+
+```ruby
+mount ActionTrace::Engine, at: '/action_trace'
+```
+
+This exposes:
+
+```
+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`).
+
+## Configuration
+
+`config/initializers/action_trace.rb` is generated automatically. Available options:
+
+```ruby
+ActionTrace.configure do |config|
+  # Controller names to exclude from page_visit tracking (default: [])
+  config.excluded_controllers = %w[health_checks status]
+
+  # Action names to exclude from page_visit tracking (default: [])
+  config.excluded_actions = %w[ping]
+
+  # The user model class name used to resolve company filtering
+  # for PublicActivity::Activity, Ahoy::Visit and Ahoy::Event (default: 'User')
+  config.user_class = 'User'
+
+  # How long to retain activity records before purging (default: 1.year)
+  config.log_retention_period = 6.months
+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`).
+
+## Usage
+
+### Track page visits — controller concern
+
+Include `ActivityTrackable` in any controller (or `ApplicationController`):
+
+```ruby
+class ApplicationController < ActionController::Base
+  include ActivityTrackable
+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.
+
+To record a session end on logout, call `track_session_end` in your sessions controller before clearing the session:
+
+```ruby
+class SessionsController < Devise::SessionsController
+  def destroy
+    track_session_end
+    super
+  end
+end
+```
+
+### Track model changes — model concern
+
+Include `ActionTrace::DataTrackable` in any ActiveRecord model:
+
+```ruby
+class Document < ApplicationRecord
+  include ActionTrace::DataTrackable
+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.
+
+### Query activity logs
+
+Use `ActionTrace::FetchActivityLogs` directly to fetch and paginate unified activity:
+
+```ruby
+result = ActionTrace::FetchActivityLogs.call(
+  current_user: current_user,
+  filters: {
+    'source'     => 'data_change',  # optional — one of the sources listed above
+    'company_id' => 5,              # optional — overrides current_user.company_id
+    'user_id'    => 12,             # optional
+    'start_date' => '2026-01-01',   # optional — YYYY-MM-DD
+    'end_date'   => '2026-03-31'    # optional — YYYY-MM-DD
+  },
+  range: 0  # offset for pagination (increments of 50)
+)
+
+result.activity_logs  # => Array of ActionTrace::ActivityLog
+result.total_count    # => Integer
+```
+
+Each `ActionTrace::ActivityLog` exposes:
+
+| Attribute | Type | Description |
+|---|---|---|
+| `id` | String | Prefixed ID e.g. `act_42`, `visit_7`, `evt_3` |
+| `source` | String | One of the sources in the table above |
+| `occurred_at` | DateTime | When the event happened |
+| `user` | String | Display name of the user |
+| `subject` | String | Human-readable description |
+| `details` | Hash | Raw event payload |
+| `paper_trail_version` | PaperTrail::Version | Associated version (data events only) |
+| `trackable` | ActiveRecord object | The changed record (data events only) |
+| `trackable_type` | String | Class name of the changed record |
+
+#### Presenter helpers
+
+`ActionTrace::ActivityLog` also provides:
+
+```ruby
+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?)
+```
+
+## 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.
+
+### Copy views
+
+```bash
+rails generate action_trace:views
+```
+
+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.
+
+### Copy views and controller
+
+```bash
+rails generate action_trace:views --controller
+```
+
+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.
+
+## Maintenance
+
+### Purge 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:
+
+```ruby
+# e.g. with whenever or Sidekiq-cron
+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/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+require 'bundler/gem_tasks'

data/app/assets/stylesheets/action_trace/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/action_trace/activity_logs_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class ActivityLogsController < ApplicationController
+    # Uncomment and adapt to your authentication/authorization setup.
+    # Run `rails generate action_trace:views --controller` to copy this file into your app.
+    #
+    # before_action :authenticate_user!   # Devise
+    # load_and_authorize_resource          # CanCanCan
+
+    def index
+      @filters = session[:activity_logs_filters] || {}
+
+      result = ActionTrace::FetchActivityLogs.call(
+        filters: @filters,
+        current_user: current_user,
+        range: params[:range] || 0
+      )
+
+      if result.success?
+        @activity_logs = result.activity_logs
+        @activity_logs_count = result.total_count
+      else
+        flash.now[:error] = result.message
+        @activity_logs = []
+        @activity_logs_count = 0
+      end
+
+      return unless request.xhr?
+
+      response.headers['Cache-Control'] = 'no-store'
+      render partial: 'index'
+    end
+
+    def filter
+      session[:activity_logs_filters] = if params[:reset].present?
+                                          {}
+                                        else
+                                          params[:filters]
+                                        end
+      redirect_to activity_logs_path
+    end
+  end
+end

data/app/controllers/action_trace/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class ApplicationController < ::ApplicationController
+  end
+end

data/app/controllers/concerns/activity_trackable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ActivityTrackable
+  extend ActiveSupport::Concern
+
+  included do
+    include PublicActivity::StoreController
+
+    after_action :track_action
+  end
+
+  private
+
+  def track_action
+    return if should_skip_tracking?
+
+    properties = {
+      path: request.path,
+      method: request.method,
+      controller: controller_name,
+      action: action_name,
+      company_id: current_company_id
+    }
+
+    ahoy.track ActionTrace::ActivityLog::SOURCES[:page_visit], properties
+  end
+
+  def track_session_end
+    ahoy.track ActionTrace::ActivityLog::SOURCES[:session_end],
+               reason: 'logout',
+               ip: request.remote_ip,
+               user_agent: request.user_agent,
+               visit_id: ahoy.visit&.id
+    ahoy.reset_visit
+  end
+
+  def current_company_id
+    current_user&.company_id
+  end
+
+  def should_skip_tracking?
+    !response.successful? ||
+      ActionTrace.configuration.excluded_controllers.include?(controller_name) ||
+      ActionTrace.configuration.excluded_actions.include?(action_name) ||
+      current_user.nil?
+  end
+end

data/app/helpers/action_trace/application_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  module ApplicationHelper
+  end
+end

data/app/interactors/action_trace/fetch_activity_logs.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class FetchActivityLogs
+    include Interactor::Organizer
+
+    organize ActionTrace::InitializeContext,
+             ActionTrace::FetchDataChanges,
+             ActionTrace::FetchPageVisits,
+             ActionTrace::FetchSessionStarts,
+             ActionTrace::MergeAndFormatResults
+  end
+end

data/app/interactors/action_trace/fetch_data_changes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class FetchDataChanges
+    include Interactor
+    include ActivityLogFetchable
+
+    def call
+      return unless should_fetch?('data_change')
+
+      scope = base_scope(PublicActivity::Activity)
+      context.total_count += scope.count
+
+      entries = scope.includes(:owner, :trackable)
+                     .order(created_at: :desc)
+                     .offset(context.range).limit(context.per_page)
+                     .map do |activity|
+        {
+          id: "act_#{activity.id}",
+          source: source_type(activity),
+          occurred_at: activity.created_at,
+          user: activity.owner&.complete_name,
+          trackable_type: activity.trackable_type,
+          details: activity.parameters || {},
+          paper_trail_version: PaperTrail::Version.find_by(id: activity.version_id),
+          trackable: activity.trackable
+        }
+      end
+
+      context.raw_collection += entries
+    end
+
+    private
+
+    def source_type(activity)
+      if activity.key.to_s.include?('destroy')
+        ActionTrace::ActivityLog::SOURCES[:data_destroy]
+      elsif activity.key.to_s.include?('create')
+        ActionTrace::ActivityLog::SOURCES[:data_create]
+      else
+        ActionTrace::ActivityLog::SOURCES[:data_change]
+      end
+    end
+  end
+end

data/app/interactors/action_trace/fetch_page_visits.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class FetchPageVisits
+    include Interactor
+    include ActivityLogFetchable
+
+    def call
+      return unless should_fetch_any?(%w[page_visit session_end])
+
+      scope = base_scope(Ahoy::Event)
+      scope = apply_source_filter(scope)
+
+      context.total_count += scope.count
+      context.raw_collection += map_entries(scope)
+    end
+
+    private
+
+    def should_fetch_any?(sources)
+      sources.any? { |s| should_fetch?(s) }
+    end
+
+    def apply_source_filter(scope)
+      case context.source
+      when ActionTrace::ActivityLog::SOURCES[:session_end] then scope.where(name: ActionTrace::ActivityLog::SOURCES[:session_end])
+      when ActionTrace::ActivityLog::SOURCES[:page_visit] then scope.where(name: ActionTrace::ActivityLog::SOURCES[:page_visit])
+      else scope
+      end
+    end
+
+    def map_entries(scope)
+      scope.includes(:user)
+           .order(time: :desc)
+           .offset(context.range).limit(context.per_page)
+           .map { |event| format_entry(event) }
+    end
+
+    def format_entry(event)
+      props = event.properties || {}
+      {
+        id: "ahoy_#{event.id}",
+        source: event.name == 'session_end' ? 'session_end' : 'page_visit',
+        occurred_at: event.time,
+        user: event.user&.complete_name,
+        url: props['path'],
+        details: props
+      }
+    end
+  end
+end

data/app/interactors/action_trace/fetch_session_starts.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class FetchSessionStarts
+    include Interactor
+    include ActivityLogFetchable
+
+    def call
+      return unless should_fetch?('session_start')
+
+      scope = base_scope(Ahoy::Visit)
+      context.total_count += scope.count
+
+      entries = scope.includes(:user)
+                     .order(started_at: :desc)
+                     .offset(context.range).limit(context.per_page)
+                     .map do |visit|
+        {
+          id: "visit_#{visit.id}",
+          source: 'session_start',
+          occurred_at: visit.started_at,
+          user: visit.user&.complete_name,
+          subject: "#{visit.browser} on #{visit.os} (#{visit.ip})",
+          details: visit.attributes.slice('ip', 'browser', 'os', 'device_type', 'country', 'landing_page', 'user_agent')
+        }
+      end
+
+      context.raw_collection += entries
+    end
+  end
+end

data/app/interactors/action_trace/initialize_context.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class InitializeContext
+    include Interactor
+
+    def call
+      filters = context.filters || {}
+      user = context.current_user
+
+      context.company_id = filters['company_id'].presence || user.company_id
+      context.user_id = filters['user_id']
+      context.source = filters['source']
+      context.start_date = filters['start_date']
+      context.end_date = filters['end_date']
+      context.range = context.range.to_i
+      context.per_page = 50
+
+      context.raw_collection = []
+      context.total_count = 0
+    end
+  end
+end

data/app/interactors/action_trace/merge_and_format_results.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class MergeAndFormatResults
+    include Interactor
+    include ActivityLogFetchable
+
+    def call
+      sorted_results = context.raw_collection
+                              .sort_by { |item| item[:occurred_at] }
+                              .reverse
+                              .first(context.per_page)
+
+      context.activity_logs = sorted_results.map { |attrs| ActionTrace::ActivityLog.new(attrs) }
+
+      total = context.total_count
+      context.activity_logs.define_singleton_method(:total_count) { total }
+    end
+  end
+end

data/app/interactors/concerns/activity_log_fetchable.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ActivityLogFetchable
+  extend ActiveSupport::Concern
+
+  def should_fetch?(source_type)
+    return true if context.source.blank?
+
+    if %w[data_change data_destroy].include?(source_type)
+      return context.source == ActionTrace::ActivityLog::SOURCES[:data_change] ||
+             context.source == ActionTrace::ActivityLog::SOURCES[:data_destroy] ||
+             context.source == ActionTrace::ActivityLog::SOURCES[:data_create]
+    end
+
+    context.source == source_type
+  end
+
+  def base_scope(model_class)
+    scope = model_class.all
+    scope = apply_activity_type_filter(scope) if model_class == PublicActivity::Activity
+    if context.company_id.present?
+      scope = if model_class.respond_to?(:filter_by_company)
+                model_class.filter_by_company(scope, context.company_id)
+              else
+                scope.where(company_id: context.company_id)
+              end
+    end
+
+    user_column = model_class == PublicActivity::Activity ? :owner_id : :user_id
+    scope = scope.where(user_column => context.user_id) if context.user_id.present?
+
+    apply_date_filters(scope, model_class)
+  end
+
+  private
+
+  def apply_activity_type_filter(scope)
+    return scope if context.source.blank?
+
+    case context.source
+    when ActionTrace::ActivityLog::SOURCES[:data_destroy]
+      scope.where('activities.`key` LIKE ?', '%.destroy')
+    when ActionTrace::ActivityLog::SOURCES[:data_change]
+      scope.where('activities.`key` LIKE ?', '%.update')
+    when ActionTrace::ActivityLog::SOURCES[:data_create]
+      scope.where('activities.`key` LIKE ?', '%.create')
+    else
+      scope
+    end
+  end
+
+  def apply_date_filters(scope, model_class)
+    date_column = date_column_for(model_class)
+    table = model_class.table_name
+
+    scope = apply_start_date_filter(scope, table, date_column)
+    apply_end_date_filter(scope, table, date_column)
+  rescue ArgumentError
+    scope
+  end
+
+  def date_column_for(model_class)
+    case model_class.to_s
+    when 'Ahoy::Event' then :time
+    when 'Ahoy::Visit' then :started_at
+    else :created_at
+    end
+  end
+
+  def apply_start_date_filter(scope, table, column)
+    return scope if context.start_date.blank?
+
+    scope.where(table => { column => Date.parse(context.start_date).beginning_of_day.. })
+  end
+
+  def apply_end_date_filter(scope, table, column)
+    return scope if context.end_date.blank?
+
+    scope.where(table => { column => ..Date.parse(context.end_date).end_of_day })
+  end
+end

data/app/jobs/action_trace/application_job.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/action_trace/purge_activity_log_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActionTrace
+  class PurgeActivityLogJob < ApplicationJob
+    queue_as :maintenance
+
+    def perform
+      threshold = ActionTrace.configuration.log_retention_period.ago
+
+      act_count = PublicActivity::Activity.where(created_at: ...threshold).delete_all
+      evt_count = Ahoy::Event.where(time: ...threshold).delete_all
+      vst_count = Ahoy::Visit.where(started_at: ...threshold).delete_all
+
+      Rails.logger.info "Activity log: Removed #{act_count} PublicActivities, #{evt_count} AhoyEvents, #{vst_count} AhoyVisits."
+    end
+  end
+end