behavior_analytics 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3e4f126ff83e60165d7b93e152c0d3ebd20f354c0d25aad69aaa88503359ea8a
+  data.tar.gz: 1222c310f8447a36c79566f5d5aeaea504c057eecdda81f4d2b569fa62c1bc99
+SHA512:
+  metadata.gz: 3fe2f936597d8c9b5016e527aa5b3ed86fb3b82f2b7cf5ba41df66c56a5d557a05758069bbaf5051e4960e2f01ad9e41fb4c3251c1f7c7d1808691c90a3272ec
+  data.tar.gz: 3e1c42b6e12f012333a44085395f070f7f66ea40851ed73d4f994dcda2acd7013cf0db22ad908461665cc9dd04977c1412e6d6bcdf7f8c334cc4889a22b848a6

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+

data/.rspec_status

@@ -0,0 +1,32 @@
+example_id                                      | status | run_time        |
+----------------------------------------------- | ------ | --------------- |
+./spec/analytics/engine_spec.rb[1:1:1]          | passed | 0.00095 seconds |
+./spec/analytics/engine_spec.rb[1:2:1]          | passed | 0.0003 seconds  |
+./spec/analytics/engine_spec.rb[1:3:1]          | passed | 0.00026 seconds |
+./spec/analytics/engine_spec.rb[1:4:1]          | passed | 0.00118 seconds |
+./spec/analytics/engine_spec.rb[1:5:1]          | passed | 0.00021 seconds |
+./spec/analytics/engine_spec.rb[1:6:1]          | passed | 0.00019 seconds |
+./spec/behavior_analytics_spec.rb[1:1]          | passed | 0.0005 seconds  |
+./spec/behavior_analytics_spec.rb[1:2:1]        | passed | 0.00035 seconds |
+./spec/behavior_analytics_spec.rb[1:3:1]        | passed | 0.00009 seconds |
+./spec/context_spec.rb[1:1:1]                   | passed | 0.00005 seconds |
+./spec/context_spec.rb[1:1:2]                   | passed | 0.00004 seconds |
+./spec/context_spec.rb[1:1:3]                   | passed | 0.00004 seconds |
+./spec/context_spec.rb[1:2:1]                   | passed | 0.00005 seconds |
+./spec/context_spec.rb[1:2:2]                   | passed | 0.00005 seconds |
+./spec/context_spec.rb[1:3:1]                   | passed | 0.00106 seconds |
+./spec/event_spec.rb[1:1:1]                     | passed | 0.0001 seconds  |
+./spec/event_spec.rb[1:1:2]                     | passed | 0.00013 seconds |
+./spec/event_spec.rb[1:1:3]                     | passed | 0.00012 seconds |
+./spec/event_spec.rb[1:1:4]                     | passed | 0.00008 seconds |
+./spec/event_spec.rb[1:2:1]                     | passed | 0.00007 seconds |
+./spec/storage/in_memory_adapter_spec.rb[1:1:1] | passed | 0.00009 seconds |
+./spec/storage/in_memory_adapter_spec.rb[1:2:1] | passed | 0.00009 seconds |
+./spec/storage/in_memory_adapter_spec.rb[1:2:2] | passed | 0.00016 seconds |
+./spec/storage/in_memory_adapter_spec.rb[1:3:1] | passed | 0.00012 seconds |
+./spec/tracker_spec.rb[1:1:1]                   | passed | 0.00056 seconds |
+./spec/tracker_spec.rb[1:1:2]                   | passed | 0.00067 seconds |
+./spec/tracker_spec.rb[1:2:1]                   | passed | 0.0003 seconds  |
+./spec/tracker_spec.rb[1:3:1]                   | passed | 0.00025 seconds |
+./spec/tracker_spec.rb[1:4:1]                   | passed | 0.00024 seconds |
+./spec/tracker_spec.rb[1:5:1]                   | passed | 0.00019 seconds |

data/README.md

@@ -0,0 +1,246 @@
+# Behavior Analytics
+
+A Ruby gem for tracking user behavior events with multi-tenant support, computing analytics (engagement scores, time-based trends, feature usage), and supporting API calls, feature usage, and custom events.
+
+## Features
+
+- **Flexible Context Tracking**: Track events with multi-tenant support, user types, and custom filters
+- **Event Buffering**: Efficient batch processing with configurable buffer size and flush intervals
+- **Comprehensive Analytics**: 
+  - Event counts and aggregations
+  - Engagement scoring with customizable weights
+  - Time-based analytics (hourly, daily, weekly, monthly)
+  - Feature usage statistics
+- **Storage Adapters**: 
+  - ActiveRecord adapter for production use
+  - In-memory adapter for testing
+- **Rails Integration**: Automatic API call tracking via middleware
+- **Query Interface**: Fluent query builder for filtering events
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'behavior_analytics'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install behavior_analytics
+```
+
+## Rails Setup
+
+### 1. Run the generator
+
+```bash
+rails generate behavior_analytics:install
+```
+
+This will:
+- Create a migration for the `behavior_events` table
+- Create an initializer at `config/initializers/behavior_analytics.rb`
+- Create a model at `app/models/behavior_analytics_event.rb`
+
+### 2. Run the migration
+
+```bash
+rails db:migrate
+```
+
+### 3. Configure the initializer
+
+Edit `config/initializers/behavior_analytics.rb`:
+
+```ruby
+BehaviorAnalytics.configure do |config|
+  # Configure storage adapter (required)
+  config.storage_adapter = BehaviorAnalytics::Storage::ActiveRecordAdapter.new(
+    model_class: BehaviorAnalyticsEvent
+  )
+
+  # Configure batching
+  config.batch_size = 100
+  config.flush_interval = 300 # 5 minutes
+
+  # Configure context resolver (optional)
+  config.context_resolver = ->(request) {
+    {
+      tenant_id: current_tenant&.id,
+      user_id: current_user&.id,
+      user_type: current_user&.account_type
+    }
+  }
+
+  # Configure engagement scoring weights
+  config.scoring_weights = {
+    activity: 0.4,
+    unique_users: 0.3,
+    feature_diversity: 0.2,
+    time_in_trial: 0.1
+  }
+end
+```
+
+### 4. Include in ApplicationController
+
+```ruby
+class ApplicationController < ActionController::Base
+  include BehaviorAnalytics::Integrations::Rails
+end
+```
+
+## Usage
+
+### Basic Tracking
+
+```ruby
+# Create a tracker
+tracker = BehaviorAnalytics.create_tracker
+
+# Create a context
+context = BehaviorAnalytics::Context.new(
+  tenant_id: "org_123",
+  user_id: "user_456",
+  user_type: "trial"
+)
+
+# Track a custom event
+tracker.track(
+  context: context,
+  event_name: "project_created",
+  metadata: { project_id: 789 }
+)
+
+# Track an API call
+tracker.track_api_call(
+  context: context,
+  method: "POST",
+  path: "/api/projects",
+  status_code: 201,
+  duration_ms: 150
+)
+
+# Track feature usage
+tracker.track_feature_usage(
+  context: context,
+  feature: "advanced_search",
+  metadata: { query: "..." }
+)
+
+# Flush buffered events
+tracker.flush
+```
+
+### Analytics
+
+```ruby
+analytics = tracker.analytics
+
+# Basic counts
+event_count = analytics.event_count(context, since: 7.days.ago)
+unique_users = analytics.unique_users(context)
+active_days = analytics.active_days(context)
+
+# Engagement scoring
+score = analytics.engagement_score(context)
+# => 75.5
+
+# Time-based analytics
+timeline = analytics.activity_timeline(context, period: :daily)
+# => { 2024-01-01 => 10, 2024-01-02 => 15, ... }
+
+daily = analytics.daily_activity(context, date_range: 7.days.ago..Time.current)
+
+# Feature usage
+feature_stats = analytics.feature_usage_stats(context)
+# => { "projects" => 25, "search" => 10, ... }
+
+top_features = analytics.top_features(context, limit: 10)
+```
+
+### Query Interface
+
+```ruby
+query = tracker.query
+
+# Build complex queries
+events = query
+  .for_tenant("org_123")
+  .for_user_type("trial")
+  .with_event_type(:feature_usage)
+  .since(7.days.ago)
+  .limit(100)
+  .execute
+
+# Count events
+count = query
+  .for_tenant("org_123")
+  .with_event_name("project_created")
+  .count
+```
+
+### Custom Storage Adapter
+
+```ruby
+class MyCustomAdapter < BehaviorAnalytics::Storage::Adapter
+  def save_events(events)
+    # Your implementation
+  end
+
+  def events_for_context(context, options = {})
+    # Your implementation
+  end
+
+  # ... implement other required methods
+end
+
+tracker = BehaviorAnalytics.create_tracker(
+  storage_adapter: MyCustomAdapter.new
+)
+```
+
+## Configuration Options
+
+- `storage_adapter`: Storage adapter instance (required)
+- `batch_size`: Number of events to buffer before flushing (default: 100)
+- `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
+
+## Event Types
+
+- `:api_call` - HTTP API requests
+- `:feature_usage` - Feature usage events
+- `:custom` - Custom business events
+
+## Context
+
+The `Context` class encapsulates tracking context:
+
+- `tenant_id` (required) - Multi-tenant identifier
+- `user_id` (optional) - User identifier
+- `user_type` (optional) - User type (e.g., "trial", "premium", "admin")
+- `filters` (optional) - Hash of custom filter criteria
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nerdawey/behavior_analytics.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/behavior_analytics.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/behavior_analytics/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "behavior_analytics"
+  spec.version = BehaviorAnalytics::VERSION
+  spec.authors = ["nerdawey"]
+  spec.email = ["nerdawy@icloud.com"]
+
+  spec.summary = "Track user behavior events with flexible context filtering and comprehensive analytics"
+  spec.description = "A Ruby gem for tracking user behavior events with multi-tenant support, " \
+                     "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.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  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])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "activesupport", ">= 6.0"
+
+  # Development dependencies
+  spec.add_development_dependency "activerecord", ">= 6.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "sqlite3", "~> 1.6"
+end

data/db/migrate/001_create_behavior_events.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class CreateBehaviorEvents < ActiveRecord::Migration[7.0]
+  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/lib/behavior_analytics/analytics/engine.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "active_support/core_ext/date"
+require "active_support/core_ext/time"
+
+module BehaviorAnalytics
+  module Analytics
+    class Engine
+      def initialize(storage_adapter)
+        @storage_adapter = storage_adapter
+      end
+
+      def event_count(context, options = {})
+        normalized_context = normalize_context(context)
+        normalized_context.validate!
+        @storage_adapter.event_count(normalized_context, options)
+      end
+
+      def unique_users(context, options = {})
+        normalized_context = normalize_context(context)
+        normalized_context.validate!
+        @storage_adapter.unique_users(normalized_context, options)
+      end
+
+      def active_days(context, options = {})
+        normalized_context = normalize_context(context)
+        normalized_context.validate!
+
+        events = @storage_adapter.events_for_context(normalized_context, options)
+        return 0 if events.empty?
+
+        dates = events.map { |e| date_from_event(e) }.compact.uniq
+        dates.count
+      end
+
+      def engagement_score(context, options = {})
+        normalized_context = normalize_context(context)
+        normalized_context.validate!
+
+        weights = options[:weights] || BehaviorAnalytics.configuration.scoring_weights
+
+        total_events = event_count(normalized_context, options)
+        unique_users_count = unique_users(normalized_context, options)
+        active_days_count = active_days(normalized_context, options)
+        feature_diversity = feature_count(normalized_context, options)
+
+        events_score = [total_events / 100.0, 1.0].min
+        users_score = [unique_users_count / 10.0, 1.0].min
+        days_score = [active_days_count / 7.0, 1.0].min
+        features_score = [feature_diversity / 5.0, 1.0].min
+
+        score = (events_score * weights[:activity]) +
+                (users_score * weights[:unique_users]) +
+                (days_score * weights[:time_in_trial]) +
+                (features_score * weights[:feature_diversity])
+
+        (score * 100).round(2)
+      end
+
+      def activity_timeline(context, options = {})
+        period = options.delete(:period) || :daily
+        normalized_context = normalize_context(context)
+        normalized_context.validate!
+
+        events = @storage_adapter.events_for_context(normalized_context, options)
+        return [] if events.empty?
+
+        grouped = case period
+                  when :hourly
+                    group_by_hour(events)
+                  when :daily
+                    group_by_day(events)
+                  when :weekly
+                    group_by_week(events)
+                  when :monthly
+                    group_by_month(events)
+                  else
+                    group_by_day(events)
+                  end
+
+        grouped.map { |period_key, period_events| [period_key, period_events.count] }.to_h
+      end
+
+      def daily_activity(context, options = {})
+        normalized_context = normalize_context(context)
+        normalized_context.validate!
+
+        options = options.dup
+        if options[:date_range]
+          date_range = options.delete(:date_range)
+          options[:since] = date_range.begin
+          options[:until] = date_range.end
+        end
+
+        activity_timeline(normalized_context, options.merge(period: :daily))
+      end
+
+      def feature_usage_stats(context, options = {})
+        normalized_context = normalize_context(context)
+        normalized_context.validate!
+
+        events = @storage_adapter.events_for_context(
+          normalized_context,
+          options.merge(event_type: :feature_usage)
+        )
+
+        feature_counts = {}
+        events.each do |event|
+          feature = event[:metadata]&.dig("feature") || event[:metadata]&.dig(:feature)
+          next unless feature
+
+          feature_counts[feature] ||= 0
+          feature_counts[feature] += 1
+        end
+
+        feature_counts
+      end
+
+      def top_features(context, options = {})
+        limit = options.delete(:limit) || 10
+        stats = feature_usage_stats(context, options)
+        stats.sort_by { |_feature, count| -count }.first(limit).to_h
+      end
+
+      private
+
+      def normalize_context(context)
+        return context if context.is_a?(Context)
+        Context.new(context)
+      end
+
+      def date_from_event(event)
+        created_at = event[:created_at] || event["created_at"]
+        return nil unless created_at
+
+        if created_at.is_a?(String)
+          created_at = Time.parse(created_at)
+        elsif created_at.is_a?(Time)
+          created_at = created_at
+        end
+
+        created_at.to_date if created_at.respond_to?(:to_date)
+      rescue
+        nil
+      end
+
+      def group_by_hour(events)
+        events.group_by do |event|
+          created_at = event[:created_at] || event["created_at"]
+          next nil unless created_at
+          time = created_at.is_a?(Time) ? created_at : Time.parse(created_at.to_s)
+          time.beginning_of_hour
+        end.compact
+      end
+
+      def group_by_day(events)
+        events.group_by { |event| date_from_event(event) }.compact
+      end
+
+      def group_by_week(events)
+        events.group_by do |event|
+          date = date_from_event(event)
+          date&.beginning_of_week if date
+        end.compact
+      end
+
+      def group_by_month(events)
+        events.group_by do |event|
+          date = date_from_event(event)
+          date&.beginning_of_month if date
+        end.compact
+      end
+
+      def feature_count(context, options = {})
+        stats = feature_usage_stats(context, options)
+        stats.keys.count
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  class Context
+    attr_accessor :tenant_id, :user_id, :user_type, :filters
+
+    def initialize(attributes = {})
+      @tenant_id = attributes[:tenant_id] || attributes[:tenant]
+      @user_id = attributes[:user_id] || attributes[:user]
+      @user_type = attributes[:user_type]
+      @filters = attributes[:filters] || {}
+    end
+
+    def to_h
+      {
+        tenant_id: tenant_id,
+        user_id: user_id,
+        user_type: user_type,
+        filters: filters
+      }.compact
+    end
+
+    def valid?
+      !tenant_id.nil? && !tenant_id.empty?
+    end
+
+    def validate!
+      raise Error, "tenant_id is required in context" unless valid?
+    end
+  end
+end
+

data/lib/behavior_analytics/event.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module BehaviorAnalytics
+  class Event
+    EVENT_TYPES = %i[api_call feature_usage custom].freeze
+
+    attr_accessor :id, :tenant_id, :user_id, :user_type, :event_name, :event_type,
+                  :metadata, :session_id, :ip, :user_agent, :duration_ms, :created_at
+
+    def initialize(attributes = {})
+      @id = attributes[:id] || SecureRandom.uuid
+      @tenant_id = attributes[:tenant_id]
+      @user_id = attributes[:user_id]
+      @user_type = attributes[:user_type]
+      @event_name = attributes[:event_name]
+      @event_type = attributes[:event_type] || :custom
+      @metadata = attributes[:metadata] || {}
+      @session_id = attributes[:session_id]
+      @ip = attributes[:ip]
+      @user_agent = attributes[:user_agent]
+      @duration_ms = attributes[:duration_ms]
+      @created_at = attributes[:created_at] || Time.now
+
+      validate!
+    end
+
+    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,
+        metadata: metadata,
+        session_id: session_id,
+        ip: ip,
+        user_agent: user_agent,
+        duration_ms: duration_ms,
+        created_at: created_at
+      }
+    end
+
+    private
+
+    def validate!
+      raise Error, "tenant_id is required" if tenant_id.nil? || tenant_id.empty?
+      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
+  end
+end
+