behavior_analytics 0.1.0

data/lib/behavior_analytics/integrations/rails.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+begin
+  require "active_support/concern"
+rescue LoadError
+end
+
+module BehaviorAnalytics
+  module Integrations
+    module Rails
+      unless defined?(ActiveSupport::Concern)
+        raise LoadError, "Rails integration requires ActiveSupport. Please add 'activesupport' to your Gemfile."
+      end
+
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :track_behavior_analytics, if: :behavior_analytics_enabled?
+      end
+
+      class_methods do
+        def skip_behavior_tracking(options = {})
+          skip_around_action :track_behavior_analytics, options
+        end
+      end
+
+      private
+
+      def track_behavior_analytics
+        start_time = Time.current
+        yield
+      ensure
+        if should_track?
+          context = resolve_tracking_context
+          if context&.valid?
+            duration_ms = ((Time.current - start_time) * 1000).to_i
+
+            behavior_tracker.track_api_call(
+              context: context,
+              method: request.method,
+              path: request.path,
+              status_code: response.status,
+              duration_ms: duration_ms,
+              ip: request.remote_ip,
+              user_agent: request.user_agent,
+              session_id: session.id,
+              metadata: {
+                controller: controller_name,
+                action: action_name,
+                format: request.format.to_s
+              }
+            )
+          end
+        end
+      end
+
+      def behavior_tracker
+        @behavior_tracker ||= BehaviorAnalytics.create_tracker(
+          storage_adapter: BehaviorAnalytics.configuration.storage_adapter
+        )
+      end
+
+      def resolve_tracking_context
+        if BehaviorAnalytics.configuration.context_resolver
+          resolver_result = BehaviorAnalytics.configuration.context_resolver.call(request)
+          Context.new(resolver_result)
+        elsif respond_to?(:current_tenant, true) && respond_to?(:current_user, true)
+          Context.new(
+            tenant_id: current_tenant&.id,
+            user_id: current_user&.id,
+            user_type: current_user&.account_type || current_user&.user_type
+          )
+        else
+          nil
+        end
+      end
+
+      def should_track?
+        context = resolve_tracking_context
+        return false unless context&.valid?
+
+        true
+      end
+
+      def behavior_analytics_enabled?
+        BehaviorAnalytics.configuration.storage_adapter.present?
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/query.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  class Query
+    def initialize(storage_adapter)
+      @storage_adapter = storage_adapter
+      @context = nil
+      @options = {}
+    end
+
+    def for_tenant(tenant_id)
+      ensure_context
+      @context.tenant_id = tenant_id
+      self
+    end
+
+    def for_user(user_id)
+      ensure_context
+      @context.user_id = user_id
+      self
+    end
+
+    def for_user_type(user_type)
+      ensure_context
+      @context.user_type = user_type
+      self
+    end
+
+    def with_event_name(event_name)
+      @options[:event_name] = event_name
+      self
+    end
+
+    def with_event_type(event_type)
+      @options[:event_type] = event_type
+      self
+    end
+
+    def since(date)
+      @options[:since] = date
+      self
+    end
+
+    def until(date)
+      @options[:until] = date
+      self
+    end
+
+    def in_range(start_date, end_date)
+      since(start_date).until(end_date)
+    end
+
+    def limit(n)
+      @options[:limit] = n
+      self
+    end
+
+    def order_by(field, direction = :desc)
+      @options[:order_by] = { field: field, direction: direction }
+      self
+    end
+
+    def execute
+      raise Error, "Context must have tenant_id" unless @context&.valid?
+      @storage_adapter.events_for_context(@context, @options)
+    end
+
+    def count
+      raise Error, "Context must have tenant_id" unless @context&.valid?
+      @storage_adapter.event_count(@context, @options)
+    end
+
+    private
+
+    def ensure_context
+      @context ||= Context.new
+    end
+  end
+end
+

data/lib/behavior_analytics/storage/active_record_adapter.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module BehaviorAnalytics
+  module Storage
+    class ActiveRecordAdapter < Adapter
+      def initialize(model_class: nil)
+        @model_class = model_class || default_model_class
+        ensure_model_exists!
+      end
+
+      def save_events(events)
+        return if events.empty?
+
+        records = events.map do |event|
+          event_hash = event.is_a?(Hash) ? event : event.to_h
+          {
+            id: event_hash[:id] || SecureRandom.uuid,
+            tenant_id: event_hash[:tenant_id],
+            user_id: event_hash[:user_id],
+            user_type: event_hash[:user_type],
+            event_name: event_hash[:event_name],
+            event_type: event_hash[:event_type].to_s,
+            metadata: event_hash[:metadata] || {},
+            session_id: event_hash[:session_id],
+            ip: event_hash[:ip],
+            user_agent: event_hash[:user_agent],
+            duration_ms: event_hash[:duration_ms],
+            created_at: event_hash[:created_at] || (defined?(Time.current) ? Time.current : Time.now)
+          }
+        end
+
+        @model_class.insert_all(records)
+      rescue StandardError => e
+        raise Error, "Failed to save events: #{e.message}"
+      end
+
+      def events_for_context(context, options = {})
+        context.validate!
+
+        query = @model_class.where(tenant_id: context.tenant_id)
+        query = query.where(user_id: context.user_id) if context.user_id
+        query = query.where(user_type: context.user_type) if context.user_type
+
+        query = query.where("created_at >= ?", options[:since]) if options[:since]
+        query = query.where("created_at <= ?", options[:until]) if options[:until]
+        query = query.where(event_name: options[:event_name]) if options[:event_name]
+        query = query.where(event_type: options[:event_type].to_s) if options[:event_type]
+
+        query = apply_order_by(query, options[:order_by]) if options[:order_by]
+        query = query.limit(options[:limit]) if options[:limit]
+
+        query.map(&:to_h)
+      end
+
+      def delete_old_events(before_date)
+        @model_class.where("created_at < ?", before_date).delete_all
+      end
+
+      def event_count(context, options = {})
+        query = build_base_query(context, options)
+        query.count
+      end
+
+      def unique_users(context, options = {})
+        query = build_base_query(context, options)
+        query.distinct.count(:user_id)
+      end
+
+      private
+
+      def default_model_class
+        return BehaviorAnalyticsEvent if defined?(BehaviorAnalyticsEvent)
+        raise Error, "BehaviorAnalyticsEvent model not found. Please run the migration generator."
+      end
+
+      def ensure_model_exists!
+        return if @model_class
+        raise Error, "Model class must be provided or BehaviorAnalyticsEvent must be defined"
+      end
+
+      def build_base_query(context, options)
+        context.validate!
+
+        query = @model_class.where(tenant_id: context.tenant_id)
+        query = query.where(user_id: context.user_id) if context.user_id
+        query = query.where(user_type: context.user_type) if context.user_type
+
+        query = query.where("created_at >= ?", options[:since]) if options[:since]
+        query = query.where("created_at <= ?", options[:until]) if options[:until]
+        query = query.where(event_name: options[:event_name]) if options[:event_name]
+        query = query.where(event_type: options[:event_type].to_s) if options[:event_type]
+
+        query
+      end
+
+      def apply_order_by(query, order_by)
+        field = order_by[:field]
+        direction = order_by[:direction] || :desc
+
+        if @model_class.column_names.include?(field.to_s)
+          query.order("#{field} #{direction.to_s.upcase}")
+        else
+          query.order(created_at: direction)
+        end
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/storage/adapter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Storage
+    class Adapter
+      def save_events(events)
+        raise NotImplementedError, "#{self.class} must implement #save_events"
+      end
+
+      def events_for_context(context, options = {})
+        raise NotImplementedError, "#{self.class} must implement #events_for_context"
+      end
+
+      def delete_old_events(before_date)
+        raise NotImplementedError, "#{self.class} must implement #delete_old_events"
+      end
+
+      def event_count(context, options = {})
+        raise NotImplementedError, "#{self.class} must implement #event_count"
+      end
+
+      def unique_users(context, options = {})
+        raise NotImplementedError, "#{self.class} must implement #unique_users"
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/storage/in_memory_adapter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Storage
+    class InMemoryAdapter < Adapter
+      def initialize
+        @events = []
+        @mutex = Mutex.new
+      end
+
+      def save_events(events)
+        @mutex.synchronize do
+          @events.concat(events.map(&:to_h))
+        end
+      end
+
+      def events_for_context(context, options = {})
+        context.validate!
+        events = filter_by_context(@events, context)
+
+        events = filter_by_date_range(events, options[:since], options[:until]) if options[:since] || options[:until]
+        events = filter_by_event_name(events, options[:event_name]) if options[:event_name]
+        events = filter_by_event_type(events, options[:event_type]) if options[:event_type]
+
+        events = events.sort_by { |e| e[:created_at] }.reverse
+        events = events.first(options[:limit]) if options[:limit]
+
+        events
+      end
+
+      def delete_old_events(before_date)
+        @mutex.synchronize do
+          @events.reject! { |e| e[:created_at] < before_date }
+        end
+      end
+
+      def event_count(context, options = {})
+        events_for_context(context, options).count
+      end
+
+      def unique_users(context, options = {})
+        events = events_for_context(context, options)
+        events.map { |e| e[:user_id] }.compact.uniq.count
+      end
+
+      def clear
+        @mutex.synchronize do
+          @events.clear
+        end
+      end
+
+      private
+
+      def filter_by_context(events, context)
+        events.select do |event|
+          matches_tenant = event[:tenant_id] == context.tenant_id
+          matches_user = context.user_id.nil? || event[:user_id] == context.user_id || event[:user_id].nil?
+          matches_user_type = context.user_type.nil? || event[:user_type] == context.user_type || event[:user_type].nil?
+          
+          matches_tenant && matches_user && matches_user_type
+        end
+      end
+
+      def filter_by_date_range(events, since, until_date)
+        events.select do |event|
+          (since.nil? || event[:created_at] >= since) &&
+            (until_date.nil? || event[:created_at] <= until_date)
+        end
+      end
+
+      def filter_by_event_name(events, event_name)
+        events.select { |e| e[:event_name] == event_name }
+      end
+
+      def filter_by_event_type(events, event_type)
+        event_type_sym = event_type.is_a?(Symbol) ? event_type : event_type.to_sym
+        events.select { |e| e[:event_type] == event_type_sym || e[:event_type].to_sym == event_type_sym }
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/tracker.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "thread"
+
+module BehaviorAnalytics
+  class Tracker
+    attr_reader :storage_adapter, :batch_size, :flush_interval, :context_resolver
+
+    def initialize(options = {})
+      @storage_adapter = options[:storage_adapter] || BehaviorAnalytics.configuration.storage_adapter || Storage::InMemoryAdapter.new
+      @batch_size = options[:batch_size] || BehaviorAnalytics.configuration.batch_size
+      @flush_interval = options[:flush_interval] || BehaviorAnalytics.configuration.flush_interval
+      @context_resolver = options[:context_resolver] || BehaviorAnalytics.configuration.context_resolver
+
+      @buffer = []
+      @mutex = Mutex.new
+      @flush_timer = nil
+      start_flush_timer
+    end
+
+    def track(context:, event_name:, event_type: :custom, metadata: {}, **options)
+      context = normalize_context(context)
+      context.validate!
+
+      event = Event.new(
+        tenant_id: context.tenant_id,
+        user_id: context.user_id,
+        user_type: context.user_type,
+        event_name: event_name,
+        event_type: event_type,
+        metadata: metadata.merge(context.filters),
+        session_id: options[:session_id],
+        ip: options[:ip],
+        user_agent: options[:user_agent],
+        duration_ms: options[:duration_ms]
+      )
+
+      add_to_buffer(event)
+    end
+
+    def track_api_call(context:, method:, path:, status_code:, duration_ms: nil, **options)
+      track(
+        context: context,
+        event_name: "api_call",
+        event_type: :api_call,
+        metadata: {
+          method: method,
+          path: path,
+          status_code: status_code
+        }.merge(options[:metadata] || {}),
+        duration_ms: duration_ms,
+        **options
+      )
+    end
+
+    def track_feature_usage(context:, feature:, metadata: {}, **options)
+      track(
+        context: context,
+        event_name: "feature_usage",
+        event_type: :feature_usage,
+        metadata: {
+          feature: feature
+        }.merge(metadata),
+        **options
+      )
+    end
+
+    def flush
+      events_to_flush = nil
+      @mutex.synchronize do
+        return if @buffer.empty?
+        events_to_flush = @buffer.dup
+        @buffer.clear
+      end
+
+      return if events_to_flush.empty?
+
+      @storage_adapter.save_events(events_to_flush)
+      restart_flush_timer
+    end
+
+    def analytics
+      @analytics ||= Analytics::Engine.new(@storage_adapter)
+    end
+
+    def query
+      Query.new(@storage_adapter)
+    end
+
+    private
+
+    def normalize_context(context)
+      return context if context.is_a?(Context)
+      Context.new(context)
+    end
+
+    def add_to_buffer(event)
+      @mutex.synchronize do
+        @buffer << event
+        flush if @buffer.size >= @batch_size
+      end
+    end
+
+    def start_flush_timer
+      return if @flush_interval.nil? || @flush_interval <= 0
+
+      @flush_timer = Thread.new do
+        loop do
+          sleep @flush_interval
+          flush
+        end
+      end
+    end
+
+    def restart_flush_timer
+      return if @flush_interval.nil? || @flush_interval <= 0
+
+      @flush_timer&.kill
+      start_flush_timer
+    end
+  end
+end
+

data/lib/behavior_analytics/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  VERSION = "0.1.0"
+end

data/lib/behavior_analytics.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "behavior_analytics/version"
+require_relative "behavior_analytics/event"
+require_relative "behavior_analytics/context"
+require_relative "behavior_analytics/tracker"
+require_relative "behavior_analytics/query"
+require_relative "behavior_analytics/storage/adapter"
+require_relative "behavior_analytics/storage/in_memory_adapter"
+require_relative "behavior_analytics/storage/active_record_adapter"
+require_relative "behavior_analytics/analytics/engine"
+
+begin
+  require_relative "behavior_analytics/integrations/rails"
+rescue LoadError
+end
+
+module BehaviorAnalytics
+  class Error < StandardError; end
+
+  class Configuration
+    attr_accessor :storage_adapter, :batch_size, :flush_interval, :context_resolver, :scoring_weights
+
+    def initialize
+      @batch_size = 100
+      @flush_interval = 300
+      @scoring_weights = {
+        activity: 0.4,
+        unique_users: 0.3,
+        feature_diversity: 0.2,
+        time_in_trial: 0.1
+      }
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    def create_tracker(options = {})
+      Tracker.new(options)
+    end
+  end
+end

data/lib/generators/behavior_analytics/install_generator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+begin
+  require "rails/generators"
+  require "rails/generators/active_record"
+rescue LoadError
+  raise LoadError, "Rails generators require Rails. Please add 'rails' to your Gemfile."
+end
+
+module BehaviorAnalytics
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("../templates", __FILE__)
+
+      def create_migration
+        migration_template "create_behavior_events.rb",
+                           "db/migrate/create_behavior_events.rb"
+      end
+
+      def create_initializer
+        create_file "config/initializers/behavior_analytics.rb", <<~RUBY
+          BehaviorAnalytics.configure do |config|
+            config.storage_adapter = BehaviorAnalytics::Storage::ActiveRecordAdapter.new(
+              model_class: BehaviorAnalyticsEvent
+            )
+
+            config.batch_size = 100
+            config.flush_interval = 300
+
+            config.context_resolver = ->(request) {
+              {
+                tenant_id: current_tenant&.id,
+                user_id: current_user&.id,
+                user_type: current_user&.account_type
+              }
+            }
+
+            config.scoring_weights = {
+              activity: 0.4,
+              unique_users: 0.3,
+              feature_diversity: 0.2,
+              time_in_trial: 0.1
+            }
+          end
+        RUBY
+      end
+
+      def create_model
+        create_file "app/models/behavior_analytics_event.rb", <<~RUBY
+          class BehaviorAnalyticsEvent < ApplicationRecord
+            self.table_name = "behavior_events"
+
+            scope :for_tenant, ->(tenant_id) { where(tenant_id: tenant_id) }
+            scope :for_user, ->(user_id) { where(user_id: user_id) }
+            scope :for_user_type, ->(user_type) { where(user_type: user_type) }
+            scope :with_event_name, ->(name) { where(event_name: name) }
+            scope :with_event_type, ->(type) { where(event_type: type.to_s) }
+            scope :since, ->(date) { where("created_at >= ?", date) }
+            scope :until, ->(date) { where("created_at <= ?", date) }
+
+            def to_h
+              {
+                id: id,
+                tenant_id: tenant_id,
+                user_id: user_id,
+                user_type: user_type,
+                event_name: event_name,
+                event_type: event_type.to_sym,
+                metadata: metadata || {},
+                session_id: session_id,
+                ip: ip,
+                user_agent: user_agent,
+                duration_ms: duration_ms,
+                created_at: created_at
+              }
+            end
+          end
+        RUBY
+      end
+    end
+  end
+end
+

data/lib/generators/behavior_analytics/templates/create_behavior_events.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class CreateBehaviorEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :behavior_events do |t|
+      t.string :tenant_id, null: false
+      t.string :user_id
+      t.string :user_type
+      t.string :event_name, null: false
+      t.string :event_type, null: false
+      t.jsonb :metadata, default: {}
+      t.string :session_id
+      t.string :ip
+      t.string :user_agent
+      t.integer :duration_ms
+      t.datetime :created_at, null: false
+    end
+
+    add_index :behavior_events, :tenant_id
+    add_index :behavior_events, :user_id
+    add_index :behavior_events, :user_type
+    add_index :behavior_events, :event_name
+    add_index :behavior_events, :event_type
+    add_index :behavior_events, :session_id
+    add_index :behavior_events, :created_at
+    add_index :behavior_events, [:tenant_id, :created_at]
+    add_index :behavior_events, [:tenant_id, :user_id, :created_at]
+    add_index :behavior_events, [:tenant_id, :event_name, :created_at]
+  end
+end
+

data/sig/behavior_analytics.rbs

@@ -0,0 +1,4 @@
+module BehaviorAnalytics
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end