behavior_analytics 0.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e4f126ff83e60165d7b93e152c0d3ebd20f354c0d25aad69aaa88503359ea8a
-  data.tar.gz: 1222c310f8447a36c79566f5d5aeaea504c057eecdda81f4d2b569fa62c1bc99
+  metadata.gz: 8ab1248da55b16fed6161e2d716579fdca58301bebd9336f0a15c3ffa3b036a7
+  data.tar.gz: 60dfde4fc53044dcf04a6fda27ab6d9caf41bbe3b421e892051e17ada80fbf8c
 SHA512:
-  metadata.gz: 3fe2f936597d8c9b5016e527aa5b3ed86fb3b82f2b7cf5ba41df66c56a5d557a05758069bbaf5051e4960e2f01ad9e41fb4c3251c1f7c7d1808691c90a3272ec
-  data.tar.gz: 3e1c42b6e12f012333a44085395f070f7f66ea40851ed73d4f994dcda2acd7013cf0db22ad908461665cc9dd04977c1412e6d6bcdf7f8c334cc4889a22b848a6
+  metadata.gz: f967ac25119baf6458fd318c8685de334686f0c0577c4ef5956aeef9bec5791e1bcaf9ea6697fdf69aa3040468aa02a3d6afad176dae33ffa0eed958d3d571c1
+  data.tar.gz: 2b230bb9364e2afcf1f8465b37a287d10a6f48a6ecc5251a152f607eafa1f045eebe5a46f3fdfa4bd3874a4b27039d7d925f5aa42399b4e8535d5a77473e3757

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
+