sinaliza 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a54ea24b56cc1b698c2a65e3cbaff8b1af36c827d596aadfa78206f393df7bd
-  data.tar.gz: 86114154d0ebf6e8753fbdbb4e364edda9f5b529d681d9f8cfabf52d56de4f48
+  metadata.gz: bc89fcab6f596adbd552ed8b28da09bba68fc38afc1d784855ebe95361b077ce
+  data.tar.gz: eb6b974f6c9701a96b8aca56364e562ace77804aa939c87e5ca808a26efbe7e9
 SHA512:
-  metadata.gz: e269b6b55f5dcd9206d98f3a4e7ba366e032c1542fa794ac8313596c11aa3a29ebac6073d261e5ab16d5d310299dc8d5f79e1095d49ec8a90067341cb37e0dee
-  data.tar.gz: 65b77aeb058512973a1128c96ebaede39a82f044363d5e961203ed80f2db01b0a3d51f093d2514d8dad101865154e7d604bf57163ff6a95eb13184cb0d32f7bf
+  metadata.gz: 1d60d7c5c5d669fb061882336df233956bea2fed3517e6a9e95756f27e0e70103e3601f743e27b3e41f85c9b281b6ee26d5ca2ee6fb9482bf52a4a2c278d9f39
+  data.tar.gz: 7b40ff04f632e503bc099a8cb68c9e75dbdde24680085fa65d882cc2767e7d6426ab8ec07dfec667fa3b65e03f28314a3df0c69ebde6a0cdd4b0fb79e24c3d50

data/README.md

@@ -50,6 +50,8 @@ Both methods accept:
 | `ip_address`| IP address                           | `nil`                 |
 | `user_agent`| User agent string                    | `nil`                 |
 | `request_id`| Request ID                           | `nil`                 |
+| `context`   | Business context for grouping (any model) | `nil`            |
+| `parent`    | Parent event (for hierarchies)       | `nil`                 |
 
 ### Model concern — `Sinaliza::Trackable`
 
@@ -64,16 +66,62 @@ end
 This gives you:
 
 ```ruby
-user.events_as_actor   # events where user is the actor
-user.events_as_target  # events where user is the target
+user.events_as_actor    # events where user is the actor
+user.events_as_target   # events where user is the target
+user.events_as_context  # events where user is the context
 
 user.track_event("profile.updated", metadata: { field: "email" })
-user.track_event("post.published", target: post)
+user.track_event("post.published", target: post, context: subscription)
+user.track_event("invoice.paid", target: invoice, context: subscription, parent: signup_event)
 
 post.track_event_as_target("post.featured", actor: admin)
+
+subscription.track_event_as_context("plan.upgraded", actor: user)
+```
+
+Events are recorded with `source: "model"`. When an actor, target, or context is destroyed, associated events are preserved with nullified references (`dependent: :nullify`).
+
+### Event context
+
+The `context` parameter is a polymorphic association that lets you group events under a business object. This is useful when multiple events belong to the same logical context — such as a subscription, an order, or a project.
+
+```ruby
+subscription = user.subscriptions.current
+
+# Record events within a subscription context
+Sinaliza.record(name: "plan.upgraded", actor: user, context: subscription, metadata: { from: "basic", to: "pro" })
+Sinaliza.record(name: "payment.processed", actor: user, context: subscription)
+Sinaliza.record(name: "invoice.sent", target: user, context: subscription)
+
+# Query events by context
+subscription.events_as_context                          # all events for this subscription
+Sinaliza::Event.by_context(subscription)                # same, via scope
+Sinaliza::Event.by_context_type("Subscription")         # all events for any subscription
+```
+
+### Parent & children events
+
+Events support a parent/children hierarchy. Use this to represent causal chains or group sub-steps under a main event.
+
+```ruby
+# Create a parent event
+signup = Sinaliza.record(name: "user.signed_up", actor: user)
+
+# Create child events
+Sinaliza.record(name: "welcome_email.sent", actor: user, parent: signup)
+Sinaliza.record(name: "default_settings.created", actor: user, parent: signup)
+
+# Navigate the hierarchy
+signup.children          # child events
+signup.root?             # => true
+signup.children.first.child?   # => true
+signup.children.first.parent   # => the signup event
+
+# Query only top-level events
+Sinaliza::Event.roots
 ```
 
-Events are recorded with `source: "model"`. When an actor or target is destroyed, associated events are preserved with nullified references (`dependent: :nullify`).
+When a parent event is destroyed, its children are also destroyed (`dependent: :destroy`).
 
 ### Controller concern — `Sinaliza::Traceable`
 
@@ -112,6 +160,9 @@ The actor is resolved by calling the method defined in `Sinaliza.configuration.a
 Sinaliza::Event.by_name("user.login")
 Sinaliza::Event.by_source("controller")
 Sinaliza::Event.by_actor_type("User")
+Sinaliza::Event.by_context(subscription)            # events for a specific context record
+Sinaliza::Event.by_context_type("Subscription")     # events for any record of this type
+Sinaliza::Event.roots                                # only top-level events (no parent)
 Sinaliza::Event.since(1.week.ago)
 Sinaliza::Event.before(Date.yesterday)
 Sinaliza::Event.between(1.week.ago, 1.day.ago)
@@ -124,6 +175,7 @@ Scopes are chainable:
 
 ```ruby
 Sinaliza::Event.by_name("order.created").by_actor_type("User").since(1.day.ago)
+Sinaliza::Event.by_context(subscription).roots.reverse_chronological
 ```
 
 ## Dashboard
@@ -179,7 +231,7 @@ Schedule it with cron, Heroku Scheduler, or whatever you prefer.
 
 ## Database schema
 
-Events are stored in a single `sinaliza_events` table with polymorphic `actor` and `target` columns. The `metadata` column uses `json` type for cross-database compatibility (SQLite, PostgreSQL, MySQL).
+Events are stored in a single `sinaliza_events` table with polymorphic `actor`, `target`, and `context` columns, plus a `parent_id` foreign key for hierarchies. The `metadata` column uses `json` type for cross-database compatibility (SQLite, PostgreSQL, MySQL).
 
 ## License
 

data/app/controllers/concerns/sinaliza/traceable.rb

@@ -18,13 +18,14 @@ module Sinaliza
 
     private
 
-    def record_event(name, target: nil, parent: nil, metadata: {})
+    def record_event(name, target: nil, context: nil, parent: nil, metadata: {})
       actor = resolve_actor
 
       attributes = {
         name: name,
         actor: actor,
         target: target,
+        context: context,
         parent: parent,
         metadata: metadata,
         source: "controller"

data/app/controllers/sinaliza/events_controller.rb

@@ -11,6 +11,7 @@ module Sinaliza
       @filter_names = Event.distinct.pluck(:name).sort
       @filter_sources = Event.distinct.pluck(:source).sort
       @filter_actor_types = Event.where.not(actor_type: nil).distinct.pluck(:actor_type).sort
+      @filter_context_types = Event.where.not(context_type: nil).distinct.pluck(:context_type).sort
     end
 
     def show
@@ -24,6 +25,7 @@ module Sinaliza
       @events = @events.by_name(params[:name]) if params[:name].present?
       @events = @events.by_source(params[:source]) if params[:source].present?
       @events = @events.by_actor_type(params[:actor_type]) if params[:actor_type].present?
+      @events = @events.by_context_type(params[:context_type]) if params[:context_type].present?
       @events = @events.search(params[:q]) if params[:q].present?
       @events = @events.since(Date.parse(params[:since])) if params[:since].present?
       @events = @events.before(Date.parse(params[:before]).end_of_day) if params[:before].present?

data/app/jobs/sinaliza/record_event_job.rb

@@ -13,6 +13,10 @@ module Sinaliza
         attributes[:target] = GlobalID::Locator.locate(attributes[:target])
       end
 
+      if attributes[:context].is_a?(String)
+        attributes[:context] = GlobalID::Locator.locate(attributes[:context])
+      end
+
       Sinaliza::Event.create!(attributes)
     end
   end

data/app/models/concerns/sinaliza/trackable.rb

@@ -12,24 +12,43 @@ module Sinaliza
                class_name: "Sinaliza::Event",
                as: :target,
                dependent: :nullify
+
+      has_many :events_as_context,
+               class_name: "Sinaliza::Event",
+               as: :context,
+               dependent: :nullify
     end
 
-    def track_event(name, target: nil, parent: nil, metadata: {})
+    def track_event(name, target: nil, context: nil, parent: nil, metadata: {})
       Sinaliza.record(
         name: name,
         actor: self,
         target: target,
+        context: context,
         parent: parent,
         metadata: metadata,
         source: "model"
       )
     end
 
-    def track_event_as_target(name, actor: nil, parent: nil, metadata: {})
+    def track_event_as_target(name, actor: nil, context: nil, parent: nil, metadata: {})
       Sinaliza.record(
         name: name,
         actor: actor,
         target: self,
+        context: context,
+        parent: parent,
+        metadata: metadata,
+        source: "model"
+      )
+    end
+
+    def track_event_as_context(name, actor: nil, target: nil, parent: nil, metadata: {})
+      Sinaliza.record(
+        name: name,
+        actor: actor,
+        target: target,
+        context: self,
         parent: parent,
         metadata: metadata,
         source: "model"

data/app/models/sinaliza/event.rb

@@ -2,6 +2,7 @@ module Sinaliza
   class Event < ApplicationRecord
     belongs_to :actor, polymorphic: true, optional: true
     belongs_to :target, polymorphic: true, optional: true
+    belongs_to :context, polymorphic: true, optional: true
     belongs_to :parent, class_name: "Sinaliza::Event", optional: true
 
     has_many :children, class_name: "Sinaliza::Event", foreign_key: :parent_id, dependent: :destroy
@@ -11,6 +12,8 @@ module Sinaliza
     scope :by_name, ->(name) { where(name: name) }
     scope :by_source, ->(source) { where(source: source) }
     scope :by_actor_type, ->(type) { where(actor_type: type) }
+    scope :by_context, ->(context) { where(context_type: context.class.name, context_id: context.id) }
+    scope :by_context_type, ->(type) { where(context_type: type) }
     scope :since, ->(time) { where(created_at: time..) }
     scope :before, ->(time) { where(created_at: ..time) }
     scope :between, ->(from, to) { where(created_at: from..to) }
@@ -18,7 +21,7 @@ module Sinaliza
     scope :reverse_chronological, -> { order(created_at: :desc) }
     scope :roots, -> { where(parent_id: nil) }
     scope :search, ->(query) {
-      where("name LIKE :q OR source LIKE :q OR actor_type LIKE :q OR target_type LIKE :q", q: "%#{query}%")
+      where("name LIKE :q OR source LIKE :q OR actor_type LIKE :q OR target_type LIKE :q OR context_type LIKE :q", q: "%#{query}%")
     }
 
     def root?

data/app/views/sinaliza/events/_filters.html.erb

@@ -35,6 +35,16 @@
       </select>
     </div>
 
+    <div class="sinaliza-filters__field">
+      <label for="context_type">Context type</label>
+      <select name="context_type" id="context_type">
+        <option value="">All</option>
+        <% @filter_context_types.each do |type| %>
+          <option value="<%= type %>" <%= "selected" if params[:context_type] == type %>><%= type %></option>
+        <% end %>
+      </select>
+    </div>
+
     <div class="sinaliza-filters__field">
       <label for="since">Since</label>
       <input type="date" name="since" id="since" value="<%= params[:since] %>">

data/app/views/sinaliza/events/index.html.erb

@@ -11,6 +11,7 @@
         <th>Source</th>
         <th>Actor</th>
         <th>Target</th>
+        <th>Context</th>
         <th>Children</th>
         <th></th>
       </tr>
@@ -23,6 +24,7 @@
           <td><span class="sinaliza-badge sinaliza-badge--source"><%= event.source %></span></td>
           <td><%= event.actor ? "#{event.actor_type}##{event.actor_id}" : "-" %></td>
           <td><%= event.target ? "#{event.target_type}##{event.target_id}" : "-" %></td>
+          <td><%= event.context ? "#{event.context_type}##{event.context_id}" : "-" %></td>
           <td><%= event.children.size %></td>
           <td><%= link_to "Detail", event_path(event), class: "sinaliza-link" %></td>
         </tr>

data/app/views/sinaliza/events/show.html.erb

@@ -26,6 +26,10 @@
       <th>Target</th>
       <td><%= @event.target ? "#{@event.target_type}##{@event.target_id}" : "-" %></td>
     </tr>
+    <tr>
+      <th>Context</th>
+      <td><%= @event.context ? "#{@event.context_type}##{@event.context_id}" : "-" %></td>
+    </tr>
     <tr>
       <th>Metadata</th>
       <td><pre class="sinaliza-json"><%= JSON.pretty_generate(@event.metadata) %></pre></td>

data/db/migrate/20260220000000_add_context_to_sinaliza_events.rb

@@ -0,0 +1,5 @@
+class AddContextToSinalizaEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_reference :sinaliza_events, :context, polymorphic: true, index: true
+  end
+end

data/lib/sinaliza/version.rb

@@ -1,3 +1,3 @@
 module Sinaliza
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/lib/sinaliza.rb

@@ -12,13 +12,14 @@ module Sinaliza
       yield(configuration)
     end
 
-    def record(name:, actor: nil, target: nil, parent: nil, metadata: {}, source: nil, ip_address: nil, user_agent: nil, request_id: nil)
+    def record(name:, actor: nil, target: nil, context: nil, parent: nil, metadata: {}, source: nil, ip_address: nil, user_agent: nil, request_id: nil)
       parent_id = parent.is_a?(Sinaliza::Event) ? parent.id : parent
 
       Sinaliza::Event.create!(
         name: name,
         actor: actor,
         target: target,
+        context: context,
         parent_id: parent_id,
         metadata: metadata,
         source: source || configuration.default_source,
@@ -28,7 +29,7 @@ module Sinaliza
       )
     end
 
-    def record_later(name:, actor: nil, target: nil, parent: nil, metadata: {}, source: nil, ip_address: nil, user_agent: nil, request_id: nil)
+    def record_later(name:, actor: nil, target: nil, context: nil, parent: nil, metadata: {}, source: nil, ip_address: nil, user_agent: nil, request_id: nil)
       attributes = {
         name: name,
         metadata: metadata,
@@ -40,6 +41,7 @@ module Sinaliza
 
       attributes[:actor] = actor.to_global_id.to_s if actor
       attributes[:target] = target.to_global_id.to_s if target
+      attributes[:context] = context.to_global_id.to_s if context
       attributes[:parent_id] = parent.is_a?(Sinaliza::Event) ? parent.id : parent if parent
 
       Sinaliza::RecordEventJob.perform_later(attributes)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinaliza
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Marcelo Moraes
@@ -59,6 +59,7 @@ files:
 - config/routes.rb
 - db/migrate/20260219000000_create_sinaliza_events.rb
 - db/migrate/20260219100000_add_parent_id_to_sinaliza_events.rb
+- db/migrate/20260220000000_add_context_to_sinaliza_events.rb
 - lib/sinaliza.rb
 - lib/sinaliza/configuration.rb
 - lib/sinaliza/engine.rb