behavior_analytics 0.1.0 → 2.0.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/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/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
+

data/lib/behavior_analytics/hooks/webhook.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module BehaviorAnalytics
+  module Hooks
+    class Webhook
+      attr_reader :url, :secret, :filter, :retry_count, :timeout
+
+      def initialize(url:, secret: nil, filter: nil, retry_count: 3, timeout: 5)
+        @url = URI(url)
+        @secret = secret
+        @filter = filter
+        @retry_count = retry_count
+        @timeout = timeout
+        @mutex = Mutex.new
+      end
+
+      def deliver(event, context = nil)
+        return unless should_deliver?(event)
+
+        payload = build_payload(event, context)
+        signature = generate_signature(payload) if @secret
+
+        headers = {
+          "Content-Type" => "application/json",
+          "User-Agent" => "BehaviorAnalytics/2.0"
+        }
+        headers["X-Webhook-Signature"] = signature if signature
+
+        deliver_with_retry(payload, headers)
+      end
+
+      private
+
+      def should_deliver?(event)
+        return true unless @filter
+
+        case @filter
+        when Proc
+          @filter.call(event)
+        when Hash
+          @filter.all? { |key, value| matches?(event, key, value) }
+        when Symbol, String
+          event[:event_type] == @filter || event[:event_type].to_s == @filter.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 build_payload(event, context)
+        {
+          event: event.is_a?(Hash) ? event : event.to_h,
+          context: context ? (context.is_a?(Hash) ? context : context.to_h) : nil,
+          timestamp: Time.now.iso8601
+        }
+      end
+
+      def generate_signature(payload)
+        require "openssl" unless defined?(OpenSSL)
+        payload_json = JSON.generate(payload)
+        OpenSSL::HMAC.hexdigest("SHA256", @secret, payload_json)
+      end
+
+      def deliver_with_retry(payload, headers)
+        last_error = nil
+        
+        (@retry_count + 1).times do |attempt|
+          begin
+            http = Net::HTTP.new(@url.host, @url.port)
+            http.use_ssl = @url.scheme == "https"
+            http.read_timeout = @timeout
+            http.open_timeout = @timeout
+
+            request = Net::HTTP::Post.new(@url.path)
+            headers.each { |key, value| request[key] = value }
+            request.body = JSON.generate(payload)
+
+            response = http.request(request)
+
+            if response.code.to_i >= 200 && response.code.to_i < 300
+              return { success: true, response_code: response.code.to_i }
+            else
+              last_error = "HTTP #{response.code}: #{response.message}"
+            end
+          rescue StandardError => e
+            last_error = e.message
+            sleep(calculate_backoff(attempt)) if attempt < @retry_count
+          end
+        end
+
+        { success: false, error: last_error }
+      end
+
+      def calculate_backoff(attempt)
+        # Exponential backoff: 1s, 2s, 4s, etc.
+        2 ** attempt
+      end
+    end
+  end
+end
+