behavior_analytics 0.1.0 → 2.1.0

data/lib/behavior_analytics/analytics/retention.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Analytics
+    class Retention
+      def initialize(storage_adapter)
+        @storage_adapter = storage_adapter
+      end
+
+      def calculate_retention(context, options = {})
+        context.validate!
+        
+        period = options[:period] || :day
+        periods = options[:periods] || 30
+        
+        # Get all events for the context
+        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 events by user and calculate first activity
+        user_first_activity = {}
+        user_activity_by_period = {}
+        
+        all_events.each do |event|
+          user_id = event[:user_id]
+          next unless user_id
+          
+          event_time = parse_time(event[:created_at])
+          period_key = period_key_for_time(event_time, period)
+          
+          # Track first activity
+          unless user_first_activity[user_id]
+            user_first_activity[user_id] = {
+              first_period: period_key,
+              first_date: event_time
+            }
+          end
+          
+          # Track activity by period
+          user_activity_by_period[user_id] ||= Set.new
+          user_activity_by_period[user_id] << period_key
+        end
+        
+        # Calculate retention
+        retention_by_period = {}
+        
+        user_first_activity.each do |user_id, first_activity|
+          first_period = first_activity[:first_period]
+          user_periods = user_activity_by_period[user_id] || Set.new
+          
+          (0..periods).each do |offset|
+            target_period = offset_period(first_period, offset, period)
+            is_active = user_periods.include?(target_period)
+            
+            retention_by_period[offset] ||= {
+              period: offset,
+              total_users: 0,
+              active_users: 0,
+              retention_rate: 0.0
+            }
+            
+            retention_by_period[offset][:total_users] += 1
+            retention_by_period[offset][:active_users] += 1 if is_active
+          end
+        end
+        
+        # Calculate retention rates
+        retention_by_period.values.each do |data|
+          if data[:total_users] > 0
+            data[:retention_rate] = (data[:active_users].to_f / data[:total_users]) * 100
+          end
+        end
+        
+        {
+          retention_curve: retention_by_period.values.sort_by { |d| d[:period] },
+          total_cohort_size: user_first_activity.size,
+          period_type: period
+        }
+      end
+
+      def calculate_churn(context, options = {})
+        context.validate!
+        
+        period = options[:period] || :day
+        lookback_periods = options[:lookback_periods] || 7
+        
+        # Get recent events
+        since = options[:since] || (Time.now - lookback_periods.send(period))
+        until_date = options[:until] || Time.now
+        
+        all_events = @storage_adapter.events_for_context(
+          context,
+          since: since,
+          until: until_date
+        )
+        
+        # Group by user and period
+        user_periods = {}
+        
+        all_events.each do |event|
+          user_id = event[:user_id]
+          next unless user_id
+          
+          event_time = parse_time(event[:created_at])
+          period_key = period_key_for_time(event_time, period)
+          
+          user_periods[user_id] ||= Set.new
+          user_periods[user_id] << period_key
+        end
+        
+        # Calculate churn (users who were active but stopped)
+        current_period = period_key_for_time(until_date, period)
+        previous_period = offset_period(current_period, -1, period)
+        
+        active_in_previous = user_periods.select { |_, periods| periods.include?(previous_period) }.keys
+        active_in_current = user_periods.select { |_, periods| periods.include?(current_period) }.keys
+        
+        churned_users = active_in_previous - active_in_current
+        
+        {
+          churned_users: churned_users.size,
+          churned_user_ids: churned_users,
+          previous_period_active: active_in_previous.size,
+          current_period_active: active_in_current.size,
+          churn_rate: active_in_previous.empty? ? 0.0 : (churned_users.size.to_f / active_in_previous.size) * 100
+        }
+      end
+
+      private
+
+      def parse_time(time_value)
+        case time_value
+        when Time
+          time_value
+        when String
+          Time.parse(time_value)
+        else
+          Time.now
+        end
+      end
+
+      def period_key_for_time(time, period)
+        case period
+        when :day
+          time.to_date.strftime("%Y-%m-%d")
+        when :week
+          time.to_date.beginning_of_week.strftime("%Y-W%V")
+        when :month
+          time.to_date.beginning_of_month.strftime("%Y-%m")
+        when :year
+          time.to_date.beginning_of_year.strftime("%Y")
+        else
+          time.to_date.strftime("%Y-%m-%d")
+        end
+      end
+
+      def offset_period(period_key, offset, period)
+        # Parse period key and add offset
+        base_date = case period
+        when :day
+          Date.parse(period_key)
+        when :week
+          year, week = period_key.match(/(\d{4})-W(\d{2})/).captures
+          Date.commercial(year.to_i, week.to_i, 1)
+        when :month
+          Date.parse("#{period_key}-01")
+        when :year
+          Date.parse("#{period_key}-01-01")
+        else
+          Date.parse(period_key)
+        end
+        
+        offset_date = base_date + offset.send(period)
+        period_key_for_time(offset_date.to_time, period)
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/context.rb

@@ -5,7 +5,11 @@ module BehaviorAnalytics
     attr_accessor :tenant_id, :user_id, :user_type, :filters
 
     def initialize(attributes = {})
+      # Only use default_tenant_id if explicitly configured and no tenant_id provided
+      # This allows tracking without tenant_id for non-multi-tenant systems
       @tenant_id = attributes[:tenant_id] || attributes[:tenant]
+      @tenant_id ||= default_tenant_id if use_default_tenant?
+      
       @user_id = attributes[:user_id] || attributes[:user]
       @user_type = attributes[:user_type]
       @filters = attributes[:filters] || {}
@@ -21,11 +25,43 @@ module BehaviorAnalytics
     end
 
     def valid?
-      !tenant_id.nil? && !tenant_id.empty?
+      # Context is valid if it has at least one identifier (tenant_id, user_id, or both)
+      # This supports different business cases:
+      # - Multi-tenant: tenant_id required
+      # - Single-tenant: user_id sufficient
+      # - API-only tracking: tenant_id or user_id optional
+      has_tenant? || has_user? || has_any_identifier?
+    end
+
+    def has_tenant?
+      !tenant_id.nil? && !tenant_id.to_s.empty?
+    end
+
+    def has_user?
+      !user_id.nil? && !user_id.to_s.empty?
+    end
+
+    def has_any_identifier?
+      # Check if filters contain any identifying information
+      filters.is_a?(Hash) && !filters.empty?
     end
 
     def validate!
-      raise Error, "tenant_id is required in context" unless valid?
+      unless valid?
+        raise Error, "Context must have at least one identifier (tenant_id, user_id, or filters). " \
+                     "For single-tenant systems, set default_tenant_id in configuration or provide user_id."
+      end
+    end
+
+    private
+
+    def default_tenant_id
+      BehaviorAnalytics.configuration.default_tenant_id
+    end
+
+    def use_default_tenant?
+      # Only use default tenant if it's explicitly set (not nil)
+      default_tenant_id && !default_tenant_id.to_s.empty?
     end
   end
 end

data/lib/behavior_analytics/debug/inspector.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "set"
+
+module BehaviorAnalytics
+  module Debug
+    class Inspector
+      def initialize(tracker)
+        @tracker = tracker
+      end
+
+      def inspect_event(event_id, context)
+        context.validate!
+        
+        events = @tracker.query
+          .for_tenant(context.tenant_id)
+          .where(id: event_id)
+          .execute
+        
+        return nil if events.empty?
+        
+        event = events.first
+        {
+          event: event,
+          context: context.to_h,
+          metadata: event[:metadata] || {},
+          related_events: find_related_events(event, context)
+        }
+      end
+
+      def inspect_context(context, options = {})
+        context.validate!
+        
+        {
+          context: context.to_h,
+          event_count: @tracker.analytics.event_count(context, options),
+          unique_users: @tracker.analytics.unique_users(context, options),
+          active_days: @tracker.analytics.active_days(context, options),
+          recent_events: @tracker.query
+            .for_tenant(context.tenant_id)
+            .limit(10)
+            .execute
+        }
+      end
+
+      def inspect_buffer
+        {
+          buffer_size: @tracker.instance_variable_get(:@buffer)&.size || 0,
+          batch_size: @tracker.batch_size,
+          flush_interval: @tracker.flush_interval
+        }
+      end
+
+      private
+
+      def find_related_events(event, context)
+        related = []
+        
+        # Find events with same session
+        if event[:session_id]
+          related.concat(@tracker.query
+            .for_tenant(context.tenant_id)
+            .where(session_id: event[:session_id])
+            .limit(10)
+            .execute)
+        end
+        
+        # Find events with same correlation_id
+        if event[:correlation_id]
+          related.concat(@tracker.query
+            .for_tenant(context.tenant_id)
+            .where(correlation_id: event[:correlation_id])
+            .limit(10)
+            .execute)
+        end
+        
+        related.uniq { |e| e[:id] }
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/event.rb

@@ -46,7 +46,13 @@ module BehaviorAnalytics
     private
 
     def validate!
-      raise Error, "tenant_id is required" if tenant_id.nil? || tenant_id.empty?
+      # tenant_id is optional - events can be tracked without tenant for non-multi-tenant systems
+      # At least one identifier should be present (tenant_id, user_id, or session_id)
+      has_identifier = (!tenant_id.nil? && !tenant_id.to_s.empty?) ||
+                       (!user_id.nil? && !user_id.to_s.empty?) ||
+                       (!session_id.nil? && !session_id.to_s.empty?)
+      
+      raise Error, "Event must have at least one identifier (tenant_id, user_id, or session_id)" unless has_identifier
       raise Error, "event_name is required" if event_name.nil? || event_name.empty?
       raise Error, "event_type must be one of: #{EVENT_TYPES.join(', ')}" unless EVENT_TYPES.include?(event_type)
     end

data/lib/behavior_analytics/export/csv_exporter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "csv"
+require "set"
+
+module BehaviorAnalytics
+  module Export
+    class CsvExporter
+      def initialize(storage_adapter)
+        @storage_adapter = storage_adapter
+      end
+
+      def export(context, options = {})
+        context.validate!
+
+        events = @storage_adapter.events_for_context(context, options)
+        return "" if events.empty?
+
+        # Determine columns
+        columns = options[:columns] || extract_columns(events)
+        
+        CSV.generate(headers: true) do |csv|
+          csv << columns
+          
+          events.each do |event|
+            row = columns.map do |column|
+              get_value(event, column)
+            end
+            csv << row
+          end
+        end
+      end
+
+      def export_to_file(context, file_path, options = {})
+        csv_content = export(context, options)
+        File.write(file_path, csv_content)
+        file_path
+      end
+
+      def stream_export(context, options = {}, &block)
+        context.validate!
+
+        batch_size = options[:batch_size] || 1000
+        offset = 0
+        first_batch = true
+
+        loop do
+          batch_options = options.merge(limit: batch_size, offset: offset)
+          events = @storage_adapter.events_for_context(context, batch_options)
+
+          break if events.empty?
+
+          if first_batch
+            columns = options[:columns] || extract_columns(events)
+            yield CSV.generate_line(columns)
+            first_batch = false
+          end
+
+          events.each do |event|
+            columns = options[:columns] || extract_columns([event])
+            row = columns.map { |col| get_value(event, col) }
+            yield CSV.generate_line(row)
+          end
+
+          offset += batch_size
+          break if events.size < batch_size
+        end
+      end
+
+      private
+
+      def extract_columns(events)
+        return [] if events.empty?
+
+        columns = Set.new
+        events.each do |event|
+          event.keys.each { |key| columns << key.to_s }
+          if event[:metadata] && event[:metadata].is_a?(Hash)
+            event[:metadata].keys.each { |key| columns << "metadata.#{key}" }
+          end
+        end
+
+        columns.sort
+      end
+
+      def get_value(event, column)
+        if column.include?(".")
+          parts = column.split(".", 2)
+          if parts[0] == "metadata"
+            metadata = event[:metadata] || event["metadata"] || {}
+            metadata[parts[1].to_sym] || metadata[parts[1].to_s] || metadata[parts[1]] || ""
+          else
+            event[parts[0].to_sym] || event[parts[0].to_s] || ""
+          end
+        else
+          event[column.to_sym] || event[column.to_s] || ""
+        end
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/export/json_exporter.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "json"
+
+module BehaviorAnalytics
+  module Export
+    class JsonExporter
+      def initialize(storage_adapter)
+        @storage_adapter = storage_adapter
+      end
+
+      def export(context, options = {})
+        context.validate!
+
+        events = @storage_adapter.events_for_context(context, options)
+        JSON.pretty_generate(events)
+      end
+
+      def export_to_file(context, file_path, options = {})
+        json_content = export(context, options)
+        File.write(file_path, json_content)
+        file_path
+      end
+
+      def stream_export(context, options = {}, &block)
+        context.validate!
+
+        batch_size = options[:batch_size] || 1000
+        offset = 0
+        first_item = true
+
+        yield "["
+
+        loop do
+          batch_options = options.merge(limit: batch_size, offset: offset)
+          events = @storage_adapter.events_for_context(context, batch_options)
+
+          break if events.empty?
+
+          events.each_with_index do |event, index|
+            yield "," unless first_item && index == 0
+            yield JSON.generate(event)
+            first_item = false
+          end
+
+          offset += batch_size
+          break if events.size < batch_size
+        end
+
+        yield "]"
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/hooks/callback.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Hooks
+    class Callback
+      attr_reader :name, :block, :condition
+
+      def initialize(name, condition: nil, &block)
+        @name = name
+        @block = block
+        @condition = condition
+      end
+
+      def call(*args)
+        return unless should_execute?(*args)
+        @block.call(*args)
+      end
+
+      private
+
+      def should_execute?(*args)
+        return true unless @condition
+
+        case @condition
+        when Proc
+          @condition.call(*args)
+        when Hash
+          event = args[0]
+          @condition.all? { |key, value| matches?(event, key, value) }
+        when Symbol, String
+          event = args[0]
+          event[:event_type] == @condition || event[:event_type].to_s == @condition.to_s
+        else
+          true
+        end
+      end
+
+      def matches?(event, key, value)
+        event_value = event[key.to_sym] || event[key.to_s] || get_metadata_value(event, key.to_s)
+        event_value == value || event_value.to_s == value.to_s
+      end
+
+      def get_metadata_value(event, key)
+        metadata = event[:metadata] || event["metadata"] || {}
+        metadata[key.to_sym] || metadata[key.to_s] || metadata[key]
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/hooks/manager.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Hooks
+    class Manager
+      attr_reader :before_track_hooks, :after_track_hooks, :on_error_hooks
+
+      def initialize
+        @before_track_hooks = []
+        @after_track_hooks = []
+        @on_error_hooks = []
+        @mutex = Mutex.new
+      end
+
+      def before_track(condition: nil, &block)
+        @mutex.synchronize do
+          @before_track_hooks << { condition: condition, callback: block }
+        end
+        self
+      end
+
+      def after_track(condition: nil, &block)
+        @mutex.synchronize do
+          @after_track_hooks << { condition: condition, callback: block }
+        end
+        self
+      end
+
+      def on_error(condition: nil, &block)
+        @mutex.synchronize do
+          @on_error_hooks << { condition: condition, callback: block }
+        end
+        self
+      end
+
+      def execute_before_track(event, context)
+        execute_hooks(@before_track_hooks, event, context)
+      end
+
+      def execute_after_track(event, context)
+        execute_hooks(@after_track_hooks, event, context)
+      end
+
+      def execute_on_error(error, event, context)
+        execute_hooks(@on_error_hooks, error, event, context)
+      end
+
+      def clear_all
+        @mutex.synchronize do
+          @before_track_hooks.clear
+          @after_track_hooks.clear
+          @on_error_hooks.clear
+        end
+      end
+
+      private
+
+      def execute_hooks(hooks, *args)
+        hooks.each do |hook|
+          next if hook[:condition] && !evaluate_condition(hook[:condition], *args)
+          
+          begin
+            hook[:callback].call(*args)
+          rescue StandardError => e
+            handle_hook_error(e, hook)
+          end
+        end
+      end
+
+      def evaluate_condition(condition, *args)
+        case condition
+        when Proc
+          condition.call(*args)
+        when Hash
+          # For event/context matching
+          event = args[0]
+          condition.all? { |key, value| matches?(event, key, value) }
+        when Symbol, String
+          # Match event type
+          event = args[0]
+          event[:event_type] == condition || event[:event_type].to_s == condition.to_s
+        else
+          true
+        end
+      end
+
+      def matches?(event, key, value)
+        event_value = event[key.to_sym] || event[key.to_s] || get_metadata_value(event, key.to_s)
+        event_value == value || event_value.to_s == value.to_s
+      end
+
+      def get_metadata_value(event, key)
+        metadata = event[:metadata] || event["metadata"] || {}
+        metadata[key.to_sym] || metadata[key.to_s] || metadata[key]
+      end
+
+      def handle_hook_error(error, hook)
+        if defined?(Rails) && Rails.logger
+          Rails.logger.error("BehaviorAnalytics: Hook error: #{error.message}")
+        end
+        # Don't re-raise - allow other hooks to execute
+      end
+    end
+  end
+end
+