behavior_analytics 0.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e4f126ff83e60165d7b93e152c0d3ebd20f354c0d25aad69aaa88503359ea8a
-  data.tar.gz: 1222c310f8447a36c79566f5d5aeaea504c057eecdda81f4d2b569fa62c1bc99
+  metadata.gz: 7a76aa6cdb7e21d5ac45f72e98f1e9b7bb678169eae8c75d0fdf821166986fa0
+  data.tar.gz: a80ea11cdfe8b429e4f793736fe756b583ffe3ffc7d8118e551ac68229f10b38
 SHA512:
-  metadata.gz: 3fe2f936597d8c9b5016e527aa5b3ed86fb3b82f2b7cf5ba41df66c56a5d557a05758069bbaf5051e4960e2f01ad9e41fb4c3251c1f7c7d1808691c90a3272ec
-  data.tar.gz: 3e1c42b6e12f012333a44085395f070f7f66ea40851ed73d4f994dcda2acd7013cf0db22ad908461665cc9dd04977c1412e6d6bcdf7f8c334cc4889a22b848a6
+  metadata.gz: 84183ce32e7e7ba31bad6f19ddbaa83b3f761c8546eff06b43a5824bc981b09bce7598d9da8df329be0e3cfec72831607cae3fe1cd1fa5e45292379aa5b00ac2
+  data.tar.gz: bb85ca2d9bc6ff08264eb98d0732b3d58d43401a253dbfdbb8b6fb52e68e832f01caf72699b1e71bcf6631bb6aaa450b3d9ee02bb2e95132362193ba0b42d9d8

data/README.md

@@ -100,19 +100,97 @@ end
 
 ## Usage
 
+### Supported Business Cases
+
+The gem is flexible and supports different business scenarios:
+
+#### 1. Multi-Tenant Systems
+Track events with tenant isolation for SaaS applications:
+
+```ruby
+context = BehaviorAnalytics::Context.new(
+  tenant_id: "org_123",
+  user_id: "user_456",
+  user_type: "premium"
+)
+```
+
+#### 2. Single-Tenant Web Apps
+Track events for regular web applications without tenant concept:
+
+```ruby
+# Option A: Set default tenant (recommended)
+BehaviorAnalytics.configure do |config|
+  config.default_tenant_id = "global"
+end
+
+context = BehaviorAnalytics::Context.new(
+  user_id: current_user.id,
+  user_type: "admin"
+)
+
+# Option B: Track without tenant_id (uses session_id or user_id as identifier)
+context = BehaviorAnalytics::Context.new(
+  user_id: current_user.id
+)
+```
+
+#### 3. API-Only Tracking
+Track API calls without user context (for monitoring, analytics, etc.):
+
+```ruby
+# Track API calls directly without user context
+tracker.track_api_call(
+  context: BehaviorAnalytics::Context.new, # Empty context - uses session_id from request
+  method: "POST",
+  path: "/api/endpoint",
+  status_code: 200,
+  duration_ms: 150
+)
+
+# Or with minimal context
+context = BehaviorAnalytics::Context.new(
+  filters: { environment: "production", service: "api" }
+)
+```
+
+#### 4. Anonymous/Public Tracking
+Track events for anonymous users or public pages:
+
+```ruby
+context = BehaviorAnalytics::Context.new(
+  filters: { page: "homepage", referrer: request.referer }
+)
+
+tracker.track(
+  context: context,
+  event_name: "page_view",
+  metadata: { path: request.path }
+)
+```
+
 ### Basic Tracking
 
 ```ruby
 # Create a tracker
 tracker = BehaviorAnalytics.create_tracker
 
-# Create a context
+# Multi-tenant example
 context = BehaviorAnalytics::Context.new(
   tenant_id: "org_123",
   user_id: "user_456",
   user_type: "trial"
 )
 
+# Single-tenant example (with default tenant)
+context = BehaviorAnalytics::Context.new(
+  user_id: "user_456",
+  user_type: "trial"
+)
+
+# API-only example (no user context)
+context = BehaviorAnalytics::Context.new
+
 # Track a custom event
 tracker.track(
   context: context,
@@ -215,6 +293,7 @@ tracker = BehaviorAnalytics.create_tracker(
 - `flush_interval`: Seconds between automatic flushes (default: 300)
 - `context_resolver`: Lambda/proc to resolve context from requests
 - `scoring_weights`: Hash of weights for engagement scoring
+- `default_tenant_id`: Default tenant ID for single-tenant systems (default: "default")
 
 ## Event Types
 
@@ -224,12 +303,74 @@ tracker = BehaviorAnalytics.create_tracker(
 
 ## Context
 
-The `Context` class encapsulates tracking context:
+The `Context` class encapsulates tracking context and is flexible to support different business cases:
 
-- `tenant_id` (required) - Multi-tenant identifier
-- `user_id` (optional) - User identifier
+- `tenant_id` (optional) - Multi-tenant identifier. Only required for multi-tenant systems
+- `user_id` (optional) - User identifier. Useful for user-based analytics
 - `user_type` (optional) - User type (e.g., "trial", "premium", "admin")
-- `filters` (optional) - Hash of custom filter criteria
+- `filters` (optional) - Hash of custom filter criteria for additional context
+
+### Context Validation
+
+A context is valid if it has **at least one identifier**:
+- `tenant_id` (for multi-tenant systems)
+- `user_id` (for user-based tracking)
+- `filters` with identifying information (for anonymous/public tracking)
+- `session_id` (automatically added for API calls)
+
+This allows the gem to support:
+- ✅ Multi-tenant SaaS applications
+- ✅ Single-tenant web applications
+- ✅ API monitoring without user context
+- ✅ Anonymous/public page tracking
+
+### Examples by Use Case
+
+**Multi-Tenant SaaS:**
+```ruby
+context = BehaviorAnalytics::Context.new(
+  tenant_id: "org_123",  # Required
+  user_id: "user_456",
+  user_type: "premium"
+)
+```
+
+**Single-Tenant Web App:**
+```ruby
+# Set default tenant (optional but recommended)
+BehaviorAnalytics.configure do |config|
+  config.default_tenant_id = "global"
+end
+
+# Track with just user_id
+context = BehaviorAnalytics::Context.new(
+  user_id: current_user.id,
+  user_type: current_user.role
+)
+```
+
+**API-Only Tracking:**
+```ruby
+# Track API calls without user context
+context = BehaviorAnalytics::Context.new  # Empty context - session_id will be used
+tracker.track_api_call(
+  context: context,
+  method: "POST",
+  path: "/api/endpoint",
+  status_code: 200
+)
+```
+
+**Anonymous/Public Tracking:**
+```ruby
+context = BehaviorAnalytics::Context.new(
+  filters: { 
+    page_type: "public",
+    referrer: request.referer 
+  }
+)
+tracker.track(context: context, event_name: "page_view")
+```
 
 ## Development
 

data/behavior_analytics.gemspec

@@ -13,6 +13,7 @@ Gem::Specification.new do |spec|
                      "computing analytics (engagement scores, time-based trends, feature usage), " \
                      "and supporting API calls, feature usage, and custom events."
   spec.homepage = "https://github.com/nerdawey/behavior_analytics"
+  spec.license = "MIT"
   spec.required_ruby_version = ">= 3.0.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
@@ -24,7 +25,8 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile]) ||
+        f.end_with?('.gem')
     end
   end
   spec.bindir = "exe"

data/db/migrate/002_enhance_behavior_events_v2.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class EnhanceBehaviorEventsV2 < ActiveRecord::Migration[7.0]
+  def change
+    # Add new columns for faster queries
+    add_column :behavior_events, :path, :string unless column_exists?(:behavior_events, :path)
+    add_column :behavior_events, :method, :string unless column_exists?(:behavior_events, :method)
+    add_column :behavior_events, :status_code, :integer unless column_exists?(:behavior_events, :status_code)
+    add_column :behavior_events, :correlation_id, :string unless column_exists?(:behavior_events, :correlation_id)
+    add_column :behavior_events, :parent_event_id, :string unless column_exists?(:behavior_events, :parent_event_id)
+    add_column :behavior_events, :tags, :string, array: true, default: [] unless column_exists?(:behavior_events, :tags)
+
+    # Add indexes for new columns
+    add_index :behavior_events, :path unless index_exists?(:behavior_events, :path)
+    add_index :behavior_events, :method unless index_exists?(:behavior_events, :method)
+    add_index :behavior_events, :status_code unless index_exists?(:behavior_events, :status_code)
+    add_index :behavior_events, :correlation_id unless index_exists?(:behavior_events, :correlation_id)
+    add_index :behavior_events, :parent_event_id unless index_exists?(:behavior_events, :parent_event_id)
+    add_index :behavior_events, :tags, using: :gin unless index_exists?(:behavior_events, :tags)
+
+    # Add composite indexes for common query patterns
+    add_index :behavior_events, [:tenant_id, :path, :created_at], 
+              name: "index_behavior_events_on_tenant_path_created" unless 
+              index_exists?(:behavior_events, [:tenant_id, :path, :created_at], 
+                           name: "index_behavior_events_on_tenant_path_created")
+    
+    add_index :behavior_events, [:tenant_id, :user_type, :created_at],
+              name: "index_behavior_events_on_tenant_user_type_created" unless
+              index_exists?(:behavior_events, [:tenant_id, :user_type, :created_at],
+                           name: "index_behavior_events_on_tenant_user_type_created")
+    
+    add_index :behavior_events, [:tenant_id, :event_type, :created_at],
+              name: "index_behavior_events_on_tenant_event_type_created" unless
+              index_exists?(:behavior_events, [:tenant_id, :event_type, :created_at],
+                           name: "index_behavior_events_on_tenant_event_type_created")
+
+    # Add GIN index on metadata JSONB for faster queries
+    if column_exists?(:behavior_events, :metadata)
+      execute <<-SQL
+        CREATE INDEX IF NOT EXISTS index_behavior_events_on_metadata_gin 
+        ON behavior_events USING gin (metadata);
+      SQL
+    end
+  end
+end
+

data/lib/behavior_analytics/analytics/cohorts.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "set"
+
+module BehaviorAnalytics
+  module Analytics
+    class Cohorts
+      def initialize(storage_adapter)
+        @storage_adapter = storage_adapter
+      end
+
+      def create_cohort(context, cohort_definition, options = {})
+        context.validate!
+        
+        date_range = options[:date_range] || (options[:since]..options[:until])
+        since = date_range.begin || options[:since]
+        until_date = date_range.end || options[:until]
+        
+        all_events = @storage_adapter.events_for_context(
+          context,
+          since: since,
+          until: until_date
+        )
+        
+        # Group users by cohort definition
+        cohort_key = cohort_definition[:key] || :created_at
+        cohort_period = cohort_definition[:period] || :month
+        
+        cohorts = {}
+        
+        all_events.each do |event|
+          cohort_date = extract_cohort_date(event, cohort_key, cohort_period)
+          cohort_id = cohort_date.strftime(cohort_format(cohort_period))
+          
+          cohorts[cohort_id] ||= {
+            cohort_id: cohort_id,
+            cohort_date: cohort_date,
+            users: Set.new,
+            events: []
+          }
+          
+          cohorts[cohort_id][:users] << event[:user_id] if event[:user_id]
+          cohorts[cohort_id][:events] << event
+        end
+        
+        cohorts.values.map do |cohort|
+          {
+            cohort_id: cohort[:cohort_id],
+            cohort_date: cohort[:cohort_date],
+            user_count: cohort[:users].size,
+            event_count: cohort[:events].size
+          }
+        end
+      end
+
+      def retention_analysis(context, cohorts, options = {})
+        context.validate!
+        
+        period = options[:period] || :day
+        periods_to_analyze = options[:periods] || 30
+        
+        retention_data = {}
+        
+        cohorts.each do |cohort|
+          cohort_id = cohort[:cohort_id] || cohort[:cohort_date]
+          cohort_date = cohort[:cohort_date] || parse_cohort_date(cohort_id)
+          
+          # Get users in this cohort
+          cohort_users = get_cohort_users(context, cohort_date, period)
+          
+          # Calculate retention for each period
+          retention_curve = []
+          
+          (0..periods_to_analyze).each do |period_offset|
+            period_date = cohort_date + period_offset.send(period)
+            
+            active_users = get_active_users(context, cohort_users, period_date, period)
+            retention_rate = cohort_users.empty? ? 0.0 : (active_users.size.to_f / cohort_users.size) * 100
+            
+            retention_curve << {
+              period: period_offset,
+              date: period_date,
+              active_users: active_users.size,
+              retention_rate: retention_rate.round(2)
+            }
+          end
+          
+          retention_data[cohort_id] = {
+            cohort_id: cohort_id,
+            cohort_date: cohort_date,
+            cohort_size: cohort_users.size,
+            retention_curve: retention_curve
+          }
+        end
+        
+        retention_data
+      end
+
+      def compare_cohorts(context, cohort_ids, options = {})
+        context.validate!
+        
+        cohorts_data = cohort_ids.map do |cohort_id|
+          retention_analysis(context, [{ cohort_id: cohort_id }], options)
+        end
+        
+        # Compare retention rates across cohorts
+        comparison = {}
+        
+        max_periods = cohorts_data.map { |c| c.values.first[:retention_curve].size }.max || 0
+        
+        (0...max_periods).each do |period|
+          period_comparison = {
+            period: period,
+            cohorts: {}
+          }
+          
+          cohorts_data.each do |cohort_data|
+            cohort_id = cohort_data.keys.first
+            retention_curve = cohort_data[cohort_id][:retention_curve]
+            
+            if retention_curve[period]
+              period_comparison[:cohorts][cohort_id] = {
+                retention_rate: retention_curve[period][:retention_rate],
+                active_users: retention_curve[period][:active_users]
+              }
+            end
+          end
+          
+          comparison[period] = period_comparison
+        end
+        
+        comparison
+      end
+
+      private
+
+      def extract_cohort_date(event, key, period)
+        date_value = event[key.to_sym] || event[key.to_s]
+        date = case date_value
+        when Time
+          date_value
+        when String
+          Time.parse(date_value)
+        else
+          Time.parse(event[:created_at].to_s)
+        end
+        
+        normalize_to_period(date, period)
+      end
+
+      def normalize_to_period(date, period)
+        case period
+        when :day
+          date.to_date
+        when :week
+          date.to_date.beginning_of_week
+        when :month
+          date.to_date.beginning_of_month
+        when :year
+          date.to_date.beginning_of_year
+        else
+          date.to_date
+        end
+      end
+
+      def cohort_format(period)
+        case period
+        when :day
+          "%Y-%m-%d"
+        when :week
+          "%Y-W%V"
+        when :month
+          "%Y-%m"
+        when :year
+          "%Y"
+        else
+          "%Y-%m-%d"
+        end
+      end
+
+      def parse_cohort_date(cohort_id)
+        # Try to parse various formats
+        Time.parse(cohort_id.to_s)
+      rescue
+        Time.now
+      end
+
+      def get_cohort_users(context, cohort_date, period)
+        # Get all users who had their first event in this cohort period
+        since = cohort_date
+        until_date = case period
+        when :day
+          since + 1.day
+        when :week
+          since + 1.week
+        when :month
+          since + 1.month
+        when :year
+          since + 1.year
+        else
+          since + 1.day
+        end
+        
+        events = @storage_adapter.events_for_context(
+          context,
+          since: since,
+          until: until_date
+        )
+        
+        # Get unique users
+        events.map { |e| e[:user_id] }.compact.uniq
+      end
+
+      def get_active_users(context, cohort_users, period_date, period)
+        # Get users who were active in this period
+        since = period_date
+        until_date = case period
+        when :day
+          since + 1.day
+        when :week
+          since + 1.week
+        when :month
+          since + 1.month
+        when :year
+          since + 1.year
+        else
+          since + 1.day
+        end
+        
+        events = @storage_adapter.events_for_context(
+          context,
+          since: since,
+          until: until_date
+        )
+        
+        active_user_ids = events.map { |e| e[:user_id] }.compact.uniq
+        cohort_users & active_user_ids
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/analytics/engine.rb

@@ -10,6 +10,9 @@ module BehaviorAnalytics
     class Engine
       def initialize(storage_adapter)
         @storage_adapter = storage_adapter
+        @funnels = nil
+        @cohorts = nil
+        @retention = nil
       end
 
       def event_count(context, options = {})
@@ -124,6 +127,18 @@ module BehaviorAnalytics
         stats.sort_by { |_feature, count| -count }.first(limit).to_h
       end
 
+      def funnels
+        @funnels ||= Funnels.new(@storage_adapter)
+      end
+
+      def cohorts
+        @cohorts ||= Cohorts.new(@storage_adapter)
+      end
+
+      def retention
+        @retention ||= Retention.new(@storage_adapter)
+      end
+
       private
 
       def normalize_context(context)

data/lib/behavior_analytics/analytics/funnels.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Analytics
+    class Funnels
+      def initialize(storage_adapter)
+        @storage_adapter = storage_adapter
+      end
+
+      def analyze_funnel(context, steps, options = {})
+        context.validate!
+        
+        date_range = options[:date_range] || (options[:since]..options[:until])
+        since = date_range.begin || options[:since]
+        until_date = date_range.end || options[:until]
+        
+        # Get all events for the context in the date range
+        all_events = @storage_adapter.events_for_context(
+          context,
+          since: since,
+          until: until_date
+        )
+        
+        # Group events by user
+        user_events = group_events_by_user(all_events)
+        
+        # Analyze each step
+        funnel_results = steps.map.with_index do |step, index|
+          step_name = step.is_a?(Hash) ? step[:name] : step.to_s
+          step_condition = step.is_a?(Hash) ? step[:condition] : ->(e) { e[:event_name] == step }
+          
+          users_at_step = user_events.select do |user_id, events|
+            events.any? { |e| evaluate_condition(e, step_condition) }
+          end
+          
+          {
+            step: step_name,
+            step_index: index,
+            users: users_at_step.keys.count,
+            events: all_events.count { |e| evaluate_condition(e, step_condition) }
+          }
+        end
+        
+        # Calculate drop-off rates
+        funnel_results.each_with_index do |step_result, index|
+          if index == 0
+            step_result[:drop_off_rate] = 0.0
+            step_result[:conversion_rate] = 100.0
+          else
+            previous_users = funnel_results[index - 1][:users]
+            current_users = step_result[:users]
+            
+            if previous_users > 0
+              step_result[:drop_off_rate] = ((previous_users - current_users).to_f / previous_users) * 100
+              step_result[:conversion_rate] = (current_users.to_f / previous_users) * 100
+            else
+              step_result[:drop_off_rate] = 100.0
+              step_result[:conversion_rate] = 0.0
+            end
+          end
+        end
+        
+        {
+          steps: funnel_results,
+          total_users: funnel_results.first[:users],
+          completed_users: funnel_results.last[:users],
+          overall_conversion_rate: calculate_overall_conversion(funnel_results)
+        }
+      end
+
+      def time_to_conversion(context, start_event, end_event, options = {})
+        context.validate!
+        
+        date_range = options[:date_range] || (options[:since]..options[:until])
+        since = date_range.begin || options[:since]
+        until_date = date_range.end || options[:until]
+        
+        all_events = @storage_adapter.events_for_context(
+          context,
+          since: since,
+          until: until_date
+        )
+        
+        user_events = group_events_by_user(all_events)
+        
+        conversion_times = []
+        
+        user_events.each do |user_id, events|
+          sorted_events = events.sort_by { |e| parse_time(e[:created_at]) }
+          
+          start_index = sorted_events.index { |e| matches_event(e, start_event) }
+          next unless start_index
+          
+          end_index = sorted_events[start_index..-1].index { |e| matches_event(e, end_event) }
+          next unless end_index
+          
+          start_time = parse_time(sorted_events[start_index][:created_at])
+          end_time = parse_time(sorted_events[start_index + end_index][:created_at])
+          
+          conversion_times << (end_time - start_time)
+        end
+        
+        return {} if conversion_times.empty?
+        
+        {
+          average_seconds: conversion_times.sum / conversion_times.size,
+          median_seconds: median(conversion_times),
+          min_seconds: conversion_times.min,
+          max_seconds: conversion_times.max,
+          count: conversion_times.size
+        }
+      end
+
+      private
+
+      def group_events_by_user(events)
+        events.group_by { |e| e[:user_id] }.reject { |k, _| k.nil? }
+      end
+
+      def evaluate_condition(event, condition)
+        case condition
+        when Proc
+          condition.call(event)
+        when String, Symbol
+          event[:event_name] == condition.to_s
+        when Hash
+          condition.all? { |key, value| event[key.to_sym] == value || event[key.to_s] == value }
+        else
+          false
+        end
+      end
+
+      def matches_event(event, event_spec)
+        case event_spec
+        when String, Symbol
+          event[:event_name] == event_spec.to_s
+        when Hash
+          event_spec.all? { |key, value| event[key.to_sym] == value || event[key.to_s] == value }
+        when Proc
+          event_spec.call(event)
+        else
+          false
+        end
+      end
+
+      def parse_time(time_value)
+        case time_value
+        when Time
+          time_value
+        when String
+          Time.parse(time_value)
+        else
+          Time.now
+        end
+      end
+
+      def median(array)
+        sorted = array.sort
+        len = sorted.length
+        (sorted[(len - 1) / 2] + sorted[len / 2]) / 2.0
+      end
+
+      def calculate_overall_conversion(funnel_results)
+        return 0.0 if funnel_results.empty?
+        
+        first_step = funnel_results.first
+        last_step = funnel_results.last
+        
+        return 0.0 if first_step[:users] == 0
+        
+        (last_step[:users].to_f / first_step[:users]) * 100
+      end
+    end
+  end
+end
+