behavior_analytics 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ab1248da55b16fed6161e2d716579fdca58301bebd9336f0a15c3ffa3b036a7
-  data.tar.gz: 60dfde4fc53044dcf04a6fda27ab6d9caf41bbe3b421e892051e17ada80fbf8c
+  metadata.gz: 7a76aa6cdb7e21d5ac45f72e98f1e9b7bb678169eae8c75d0fdf821166986fa0
+  data.tar.gz: a80ea11cdfe8b429e4f793736fe756b583ffe3ffc7d8118e551ac68229f10b38
 SHA512:
-  metadata.gz: f967ac25119baf6458fd318c8685de334686f0c0577c4ef5956aeef9bec5791e1bcaf9ea6697fdf69aa3040468aa02a3d6afad176dae33ffa0eed958d3d571c1
-  data.tar.gz: 2b230bb9364e2afcf1f8465b37a287d10a6f48a6ecc5251a152f607eafa1f045eebe5a46f3fdfa4bd3874a4b27039d7d925f5aa42399b4e8535d5a77473e3757
+  metadata.gz: 84183ce32e7e7ba31bad6f19ddbaa83b3f761c8546eff06b43a5824bc981b09bce7598d9da8df329be0e3cfec72831607cae3fe1cd1fa5e45292379aa5b00ac2
+  data.tar.gz: bb85ca2d9bc6ff08264eb98d0732b3d58d43401a253dbfdbb8b6fb52e68e832f01caf72699b1e71bcf6631bb6aaa450b3d9ee02bb2e95132362193ba0b42d9d8

data/README.md

@@ -100,19 +100,97 @@ end
 
 ## Usage
 
+### Supported Business Cases
+
+The gem is flexible and supports different business scenarios:
+
+#### 1. Multi-Tenant Systems
+Track events with tenant isolation for SaaS applications:
+
+```ruby
+context = BehaviorAnalytics::Context.new(
+  tenant_id: "org_123",
+  user_id: "user_456",
+  user_type: "premium"
+)
+```
+
+#### 2. Single-Tenant Web Apps
+Track events for regular web applications without tenant concept:
+
+```ruby
+# Option A: Set default tenant (recommended)
+BehaviorAnalytics.configure do |config|
+  config.default_tenant_id = "global"
+end
+
+context = BehaviorAnalytics::Context.new(
+  user_id: current_user.id,
+  user_type: "admin"
+)
+
+# Option B: Track without tenant_id (uses session_id or user_id as identifier)
+context = BehaviorAnalytics::Context.new(
+  user_id: current_user.id
+)
+```
+
+#### 3. API-Only Tracking
+Track API calls without user context (for monitoring, analytics, etc.):
+
+```ruby
+# Track API calls directly without user context
+tracker.track_api_call(
+  context: BehaviorAnalytics::Context.new, # Empty context - uses session_id from request
+  method: "POST",
+  path: "/api/endpoint",
+  status_code: 200,
+  duration_ms: 150
+)
+
+# Or with minimal context
+context = BehaviorAnalytics::Context.new(
+  filters: { environment: "production", service: "api" }
+)
+```
+
+#### 4. Anonymous/Public Tracking
+Track events for anonymous users or public pages:
+
+```ruby
+context = BehaviorAnalytics::Context.new(
+  filters: { page: "homepage", referrer: request.referer }
+)
+
+tracker.track(
+  context: context,
+  event_name: "page_view",
+  metadata: { path: request.path }
+)
+```
+
 ### Basic Tracking
 
 ```ruby
 # Create a tracker
 tracker = BehaviorAnalytics.create_tracker
 
-# Create a context
+# Multi-tenant example
 context = BehaviorAnalytics::Context.new(
   tenant_id: "org_123",
   user_id: "user_456",
   user_type: "trial"
 )
 
+# Single-tenant example (with default tenant)
+context = BehaviorAnalytics::Context.new(
+  user_id: "user_456",
+  user_type: "trial"
+)
+
+# API-only example (no user context)
+context = BehaviorAnalytics::Context.new
+
 # Track a custom event
 tracker.track(
   context: context,
@@ -215,6 +293,7 @@ tracker = BehaviorAnalytics.create_tracker(
 - `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
+- `default_tenant_id`: Default tenant ID for single-tenant systems (default: "default")
 
 ## Event Types
 
@@ -224,12 +303,74 @@ tracker = BehaviorAnalytics.create_tracker(
 
 ## Context
 
-The `Context` class encapsulates tracking context:
+The `Context` class encapsulates tracking context and is flexible to support different business cases:
 
-- `tenant_id` (required) - Multi-tenant identifier
-- `user_id` (optional) - User identifier
+- `tenant_id` (optional) - Multi-tenant identifier. Only required for multi-tenant systems
+- `user_id` (optional) - User identifier. Useful for user-based analytics
 - `user_type` (optional) - User type (e.g., "trial", "premium", "admin")
-- `filters` (optional) - Hash of custom filter criteria
+- `filters` (optional) - Hash of custom filter criteria for additional context
+
+### Context Validation
+
+A context is valid if it has **at least one identifier**:
+- `tenant_id` (for multi-tenant systems)
+- `user_id` (for user-based tracking)
+- `filters` with identifying information (for anonymous/public tracking)
+- `session_id` (automatically added for API calls)
+
+This allows the gem to support:
+- ✅ Multi-tenant SaaS applications
+- ✅ Single-tenant web applications
+- ✅ API monitoring without user context
+- ✅ Anonymous/public page tracking
+
+### Examples by Use Case
+
+**Multi-Tenant SaaS:**
+```ruby
+context = BehaviorAnalytics::Context.new(
+  tenant_id: "org_123",  # Required
+  user_id: "user_456",
+  user_type: "premium"
+)
+```
+
+**Single-Tenant Web App:**
+```ruby
+# Set default tenant (optional but recommended)
+BehaviorAnalytics.configure do |config|
+  config.default_tenant_id = "global"
+end
+
+# Track with just user_id
+context = BehaviorAnalytics::Context.new(
+  user_id: current_user.id,
+  user_type: current_user.role
+)
+```
+
+**API-Only Tracking:**
+```ruby
+# Track API calls without user context
+context = BehaviorAnalytics::Context.new  # Empty context - session_id will be used
+tracker.track_api_call(
+  context: context,
+  method: "POST",
+  path: "/api/endpoint",
+  status_code: 200
+)
+```
+
+**Anonymous/Public Tracking:**
+```ruby
+context = BehaviorAnalytics::Context.new(
+  filters: { 
+    page_type: "public",
+    referrer: request.referer 
+  }
+)
+tracker.track(context: context, event_name: "page_view")
+```
 
 ## Development
 

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/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/integrations/rails.rb

@@ -70,14 +70,26 @@ module BehaviorAnalytics
             user_id: current_user&.id,
             user_type: current_user&.account_type || current_user&.user_type
           )
+        elsif respond_to?(:current_user, true)
+          # Single-tenant system - use default tenant
+          Context.new(
+            tenant_id: BehaviorAnalytics.configuration.default_tenant_id,
+            user_id: current_user&.id,
+            user_type: current_user&.account_type || current_user&.user_type
+          )
         else
-          nil
+          # No user context - use default tenant
+          Context.new(
+            tenant_id: BehaviorAnalytics.configuration.default_tenant_id
+          )
         end
       end
 
       def should_track?
         context = resolve_tracking_context
-        return false unless context&.valid?
+        # Allow tracking even without context for API-only tracking
+        # Context validation will handle required fields
+        return false if context && !context.valid?
 
         # Check path whitelist/blacklist
         return false if path_blacklisted?
@@ -155,6 +167,9 @@ module BehaviorAnalytics
       ensure
         if should_track?
           context = resolve_tracking_context
+          # Create context if it doesn't exist (for API-only tracking)
+          context ||= Context.new(tenant_id: BehaviorAnalytics.configuration.default_tenant_id)
+          
           if context&.valid?
             duration_ms = ((Time.current - start_time) * 1000).to_i
 

data/lib/behavior_analytics/query.rb

@@ -132,7 +132,7 @@ module BehaviorAnalytics
     end
 
     def execute
-      raise Error, "Context must have tenant_id" unless @context&.valid?
+      raise Error, "Context must be valid (have at least tenant_id, user_id, or filters)" unless @context&.valid?
       
       # Merge metadata filters and other options
       final_options = @options.dup
@@ -146,7 +146,7 @@ module BehaviorAnalytics
     end
 
     def count
-      raise Error, "Context must have tenant_id" unless @context&.valid?
+      raise Error, "Context must be valid (have at least tenant_id, user_id, or filters)" unless @context&.valid?
       
       final_options = @options.dup
       final_options[:metadata_filters] = @metadata_filters unless @metadata_filters.empty?

data/lib/behavior_analytics/storage/active_record_adapter.rb

@@ -41,6 +41,9 @@ module BehaviorAnalytics
 
         query = build_base_query(context, options)
         
+        # If no tenant_id, query all events (for non-multi-tenant systems)
+        # This allows tracking without tenant isolation
+        
         # Apply metadata filters
         if options[:metadata_filters]
           options[:metadata_filters].each do |key, value|
@@ -140,6 +143,7 @@ module BehaviorAnalytics
       end
 
       def event_count(context, options = {})
+        context.validate!
         query = build_base_query(context, options)
         
         # Apply metadata filters
@@ -211,8 +215,17 @@ module BehaviorAnalytics
       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
+        # Support different business cases:
+        # - Multi-tenant: filter by tenant_id
+        # - Single-tenant: filter by user_id (tenant_id may be nil)
+        # - API-only: no filters required
+        query = @model_class.all
+        
+        if context.has_tenant?
+          query = query.where(tenant_id: context.tenant_id)
+        end
+        
+        query = query.where(user_id: context.user_id) if context.has_user?
         query = query.where(user_type: context.user_type) if context.user_type
 
         query = query.where("created_at >= ?", options[:since]) if options[:since]

data/lib/behavior_analytics/storage/elasticsearch_adapter.rb

@@ -125,11 +125,21 @@ module BehaviorAnalytics
       end
 
       def build_query(context, options)
-        must_clauses = [
-          { term: { tenant_id: context.tenant_id } }
-        ]
+        must_clauses = []
+        
+        # Support different business cases:
+        # - Multi-tenant: filter by tenant_id
+        # - Single-tenant: filter by user_id (tenant_id may be nil)
+        # - API-only: no strict filters required
+        
+        if context.has_tenant?
+          must_clauses << { term: { tenant_id: context.tenant_id } }
+        end
+        
+        if context.has_user?
+          must_clauses << { term: { user_id: context.user_id } }
+        end
         
-        must_clauses << { term: { user_id: context.user_id } } if context.user_id
         must_clauses << { term: { user_type: context.user_type } } if context.user_type
         must_clauses << { term: { event_name: options[:event_name] } } if options[:event_name]
         must_clauses << { term: { event_type: options[:event_type].to_s } } if options[:event_type]

data/lib/behavior_analytics/storage/in_memory_adapter.rb

@@ -143,9 +143,26 @@ module BehaviorAnalytics
 
       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?
+          # Support different business cases:
+          # - Multi-tenant: must match tenant_id
+          # - Single-tenant: match user_id (tenant_id may be nil)
+          # - API-only: no strict matching required
+          
+          matches_tenant = if context.has_tenant?
+            event[:tenant_id] == context.tenant_id
+          else
+            true # No tenant filter if context doesn't have tenant
+          end
+          
+          matches_user = if context.has_user?
+            event[:user_id] == context.user_id
+          else
+            true # No user filter if context doesn't have user
+          end
+          
+          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

data/lib/behavior_analytics/storage/kafka_adapter.rb

@@ -36,7 +36,15 @@ module BehaviorAnalytics
         
         # Kafka is primarily for streaming, so we need a consumer
         # This is a simplified version - in production you'd use a proper consumer group
-        consumer = @kafka.consumer(group_id: "behavior_analytics_#{context.tenant_id}")
+        group_id = if context.has_tenant?
+          "behavior_analytics_#{context.tenant_id}"
+        elsif context.has_user?
+          "behavior_analytics_user_#{context.user_id}"
+        else
+          "behavior_analytics_global"
+        end
+        
+        consumer = @kafka.consumer(group_id: group_id)
         consumer.subscribe(@topic)
         
         events = []
@@ -88,8 +96,15 @@ module BehaviorAnalytics
       end
 
       def matches_context?(event, context, options)
-        return false unless event[:tenant_id] == context.tenant_id
-        return false if context.user_id && event[:user_id] != context.user_id
+        # Support different business cases
+        if context.has_tenant?
+          return false unless event[:tenant_id] == context.tenant_id
+        end
+        
+        if context.has_user?
+          return false unless event[:user_id] == context.user_id
+        end
+        
         return false if context.user_type && event[:user_type] != context.user_type
         return false if options[:event_name] && event[:event_name] != options[:event_name]
         return false if options[:event_type] && event[:event_type] != options[:event_type]

data/lib/behavior_analytics/storage/redis_adapter.rb

@@ -98,8 +98,13 @@ module BehaviorAnalytics
         user_id = event_hash[:user_id]
         event_type = event_hash[:event_type]
         
-        @redis.sadd("#{@key_prefix}:tenant:#{tenant_id}", event_hash[:id])
+        # Index by tenant if present (multi-tenant)
+        @redis.sadd("#{@key_prefix}:tenant:#{tenant_id}", event_hash[:id]) if tenant_id
+        
+        # Index by user if present (single-tenant or multi-tenant)
         @redis.sadd("#{@key_prefix}:user:#{user_id}", event_hash[:id]) if user_id
+        
+        # Index by event type
         @redis.sadd("#{@key_prefix}:type:#{event_type}", event_hash[:id]) if event_type
       end
 
@@ -114,17 +119,38 @@ module BehaviorAnalytics
       end
 
       def find_event_ids(context, options)
-        # Start with tenant index
-        ids = @redis.smembers("#{@key_prefix}:tenant:#{context.tenant_id}").to_a
+        # Support different business cases:
+        # - Multi-tenant: use tenant index
+        # - Single-tenant: use user index
+        # - API-only: use event type or all events
+        
+        if context.has_tenant?
+          # Start with tenant index
+          ids = @redis.smembers("#{@key_prefix}:tenant:#{context.tenant_id}").to_a
+        elsif context.has_user?
+          # Use user index for single-tenant systems
+          ids = @redis.smembers("#{@key_prefix}:user:#{context.user_id}").to_a
+        else
+          # API-only or anonymous tracking - start with all or event type
+          if options[:event_type]
+            ids = @redis.smembers("#{@key_prefix}:type:#{options[:event_type]}").to_a
+          else
+            # Get all event IDs (scan all keys - less efficient but supports API-only tracking)
+            ids = []
+            @redis.scan_each(match: "#{@key_prefix}:event:*") do |key|
+              ids << key.split(":").last
+            end
+          end
+        end
         
-        # Intersect with user index if specified
-        if context.user_id
+        # Intersect with user index if specified (in addition to tenant)
+        if context.has_tenant? && context.has_user?
           user_ids = @redis.smembers("#{@key_prefix}:user:#{context.user_id}").to_a
           ids = ids & user_ids
         end
         
         # Intersect with event type if specified
-        if options[:event_type]
+        if options[:event_type] && context.has_tenant?
           type_ids = @redis.smembers("#{@key_prefix}:type:#{options[:event_type]}").to_a
           ids = ids & type_ids
         end
@@ -136,6 +162,16 @@ module BehaviorAnalytics
         events.select do |event|
           matches = true
           
+          # Tenant matching (if context has tenant)
+          if context.has_tenant?
+            matches &&= event[:tenant_id] == context.tenant_id
+          end
+          
+          # User matching (if context has user)
+          if context.has_user?
+            matches &&= event[:user_id] == context.user_id
+          end
+          
           matches &&= event[:user_type] == context.user_type if context.user_type
           matches &&= event[:event_name] == options[:event_name] if options[:event_name]
           

data/lib/behavior_analytics/version.rb

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

data/lib/behavior_analytics.rb

@@ -95,7 +95,7 @@ module BehaviorAnalytics
                   :hooks_manager, :raise_on_hook_error, :sampling_strategy, :rate_limiter,
                   :schema_validator, :schema_registry, :tracking_whitelist, :tracking_blacklist,
                   :skip_bots, :controller_action_filters, :slow_query_threshold, :track_middleware_requests,
-                  :metrics, :tracer, :debug_mode, :logger
+                  :metrics, :tracer, :debug_mode, :logger, :default_tenant_id
 
     def initialize
       @batch_size = 100
@@ -123,6 +123,7 @@ module BehaviorAnalytics
       @tracer = nil
       @debug_mode = @environment == "development"
       @logger = nil
+      @default_tenant_id = "default" # Default tenant for single-tenant systems
     end
 
     def debug(message, context: nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: behavior_analytics
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - nerdawey