mbuzz 0.6.2

data/lib/mbuzz/configuration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class ConfigurationError < StandardError; end
+
+  class Configuration
+    attr_accessor :api_key, :api_url, :enabled, :debug, :timeout, :batch_size, :flush_interval, :logger,
+      :skip_paths, :skip_extensions
+
+    # Default paths to skip - health checks, assets, etc.
+    DEFAULT_SKIP_PATHS = %w[
+      /up
+      /health
+      /healthz
+      /ping
+      /cable
+      /assets
+      /packs
+      /rails/active_storage
+      /api
+    ].freeze
+
+    # Default extensions to skip - static assets
+    DEFAULT_SKIP_EXTENSIONS = %w[
+      .js .css .map .png .jpg .jpeg .gif .ico .svg .woff .woff2 .ttf .eot .webp
+    ].freeze
+
+    def initialize
+      @api_url = "https://mbuzz.co/api/v1"
+      @enabled = true
+      @debug = false
+      @timeout = 5
+      @batch_size = 50
+      @flush_interval = 30
+      @skip_paths = []
+      @skip_extensions = []
+    end
+
+    def validate!
+      raise ConfigurationError, "api_key is required" if api_key.nil? || api_key.empty?
+    end
+
+    def all_skip_paths
+      DEFAULT_SKIP_PATHS + Array(skip_paths)
+    end
+
+    def all_skip_extensions
+      DEFAULT_SKIP_EXTENSIONS + Array(skip_extensions)
+    end
+  end
+end

data/lib/mbuzz/controller_helpers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  module ControllerHelpers
+    def mbuzz_track(event_type, properties: {})
+      Client.track(
+        user_id: mbuzz_user_id,
+        visitor_id: mbuzz_visitor_id,
+        event_type: event_type,
+        properties: properties
+      )
+    end
+
+    def mbuzz_identify(traits: {})
+      Client.identify(
+        user_id: mbuzz_user_id,
+        visitor_id: mbuzz_visitor_id,
+        traits: traits
+      )
+    end
+
+    def mbuzz_user_id
+      request.env[ENV_USER_ID_KEY]
+    end
+
+    def mbuzz_visitor_id
+      request.env[ENV_VISITOR_ID_KEY]
+    end
+
+    def mbuzz_session_id
+      request.env[ENV_SESSION_ID_KEY]
+    end
+  end
+end

data/lib/mbuzz/middleware/tracking.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module Mbuzz
+  module Middleware
+    class Tracking
+      attr_reader :app, :request
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return app.call(env) if skip_request?(env)
+
+        reset_request_state!
+        @request = Rack::Request.new(env)
+
+        env[ENV_VISITOR_ID_KEY] = visitor_id
+        env[ENV_USER_ID_KEY] = user_id
+        env[ENV_SESSION_ID_KEY] = session_id
+
+        RequestContext.with_context(request: request) do
+          create_session_if_new
+
+          status, headers, body = app.call(env)
+          set_visitor_cookie(headers)
+          set_session_cookie(headers)
+          [status, headers, body]
+        end
+      end
+
+      # Path filtering - skip health checks, static assets, etc.
+
+      def skip_request?(env)
+        path = env["PATH_INFO"].to_s.downcase
+
+        skip_by_path?(path) || skip_by_extension?(path)
+      end
+
+      def skip_by_path?(path)
+        Mbuzz.config.all_skip_paths.any? { |skip| path.start_with?(skip) }
+      end
+
+      def skip_by_extension?(path)
+        Mbuzz.config.all_skip_extensions.any? { |ext| path.end_with?(ext) }
+      end
+
+      private
+
+      def reset_request_state!
+        @request = nil
+        @visitor_id = nil
+        @session_id = nil
+        @user_id = nil
+      end
+
+      def visitor_id
+        @visitor_id ||= visitor_id_from_cookie || Visitor::Identifier.generate
+      end
+
+      def visitor_id_from_cookie
+        request.cookies[VISITOR_COOKIE_NAME]
+      end
+
+      def user_id
+        @user_id ||= user_id_from_session
+      end
+
+      def user_id_from_session
+        request.session[SESSION_USER_ID_KEY] if request.session
+      end
+
+      def set_visitor_cookie(headers)
+        Rack::Utils.set_cookie_header!(headers, VISITOR_COOKIE_NAME, visitor_cookie_options)
+      end
+
+      def visitor_cookie_options
+        base_cookie_options.merge(
+          value: visitor_id,
+          max_age: VISITOR_COOKIE_MAX_AGE
+        )
+      end
+
+      # Session ID management
+
+      def session_id
+        @session_id ||= session_id_from_cookie || generate_session_id
+      end
+
+      def session_id_from_cookie
+        request.cookies[SESSION_COOKIE_NAME]
+      end
+
+      def generate_session_id
+        SecureRandom.hex(32)
+      end
+
+      def new_session?
+        session_id_from_cookie.nil?
+      end
+
+      # Session creation
+
+      def create_session_if_new
+        return unless new_session?
+
+        create_session_async
+      end
+
+      def create_session_async
+        Thread.new { create_session }
+      end
+
+      def create_session
+        Client.session(
+          visitor_id: visitor_id,
+          session_id: session_id,
+          url: request.url,
+          referrer: request.referer
+        )
+      rescue => e
+        log_session_error(e)
+      end
+
+      def log_session_error(error)
+        Mbuzz.config.logger&.error("Session creation failed: #{error.message}")
+      end
+
+      # Session cookie
+
+      def set_session_cookie(headers)
+        Rack::Utils.set_cookie_header!(headers, SESSION_COOKIE_NAME, session_cookie_options)
+      end
+
+      def session_cookie_options
+        base_cookie_options.merge(
+          value: session_id,
+          max_age: SESSION_COOKIE_MAX_AGE
+        )
+      end
+
+      # Shared cookie options
+
+      def base_cookie_options
+        options = {
+          path: VISITOR_COOKIE_PATH,
+          httponly: true,
+          same_site: VISITOR_COOKIE_SAME_SITE
+        }
+        options[:secure] = true if request.ssl?
+        options
+      end
+    end
+  end
+end

data/lib/mbuzz/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class Railtie < Rails::Railtie
+    initializer "mbuzz.configure_rails" do |app|
+      app.middleware.use Mbuzz::Middleware::Tracking
+
+      ActiveSupport.on_load(:action_controller) do
+        include Mbuzz::ControllerHelpers
+      end
+    end
+  end
+end

data/lib/mbuzz/request_context.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class RequestContext
+    def self.with_context(request:)
+      Thread.current[:mbuzz_request] = request
+      yield
+    ensure
+      Thread.current[:mbuzz_request] = nil
+    end
+
+    def self.current
+      return nil unless Thread.current[:mbuzz_request]
+
+      new(Thread.current[:mbuzz_request])
+    end
+
+    attr_reader :request
+
+    def initialize(request)
+      @request = request
+    end
+
+    def url
+      @request.url
+    end
+
+    def referrer
+      @request.referrer
+    end
+
+    def user_agent
+      @request.user_agent
+    end
+
+    def enriched_properties(custom = {})
+      { url: url, referrer: referrer }.compact.merge(custom)
+    end
+  end
+end

data/lib/mbuzz/version.rb

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

data/lib/mbuzz/visitor/identifier.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Mbuzz
+  module Visitor
+    class Identifier
+      def self.generate
+        SecureRandom.hex(32)
+      end
+    end
+  end
+end

data/lib/mbuzz.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "mbuzz/version"
+require_relative "mbuzz/configuration"
+require_relative "mbuzz/visitor/identifier"
+require_relative "mbuzz/request_context"
+require_relative "mbuzz/api"
+require_relative "mbuzz/client"
+require_relative "mbuzz/middleware/tracking"
+require_relative "mbuzz/controller_helpers"
+
+require_relative "mbuzz/railtie" if defined?(Rails::Railtie)
+
+module Mbuzz
+  class Error < StandardError; end
+
+  EVENTS_PATH = "/events"
+  IDENTIFY_PATH = "/identify"
+  CONVERSIONS_PATH = "/conversions"
+  SESSIONS_PATH = "/sessions"
+
+  VISITOR_COOKIE_NAME = "_mbuzz_vid"
+  VISITOR_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 2 # 2 years
+  VISITOR_COOKIE_PATH = "/"
+  VISITOR_COOKIE_SAME_SITE = "Lax"
+
+  SESSION_COOKIE_NAME = "_mbuzz_sid"
+  SESSION_COOKIE_MAX_AGE = 30 * 60 # 30 minutes
+
+  SESSION_USER_ID_KEY = "user_id"
+  ENV_USER_ID_KEY = "mbuzz.user_id"
+  ENV_VISITOR_ID_KEY = "mbuzz.visitor_id"
+  ENV_SESSION_ID_KEY = "mbuzz.session_id"
+
+  # ============================================================================
+  # Configuration
+  # ============================================================================
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # New simplified configuration method (v0.5.0)
+  # @param api_key [String] Your mbuzz API key
+  # @param api_url [String, nil] Override API URL (defaults to https://mbuzz.co/api/v1)
+  # @param session_timeout [Integer, nil] Session timeout in seconds
+  # @param debug [Boolean, nil] Enable debug logging
+  # @param skip_paths [Array<String>, nil] Additional paths to skip tracking (e.g., ["/admin", "/internal"])
+  # @param skip_extensions [Array<String>, nil] Additional extensions to skip (e.g., [".pdf"])
+  def self.init(api_key:, api_url: nil, session_timeout: nil, debug: nil, skip_paths: nil, skip_extensions: nil)
+    config.api_key = api_key
+    config.api_url = api_url if api_url
+    config.session_timeout = session_timeout if session_timeout
+    config.debug = debug unless debug.nil?
+    config.skip_paths = skip_paths if skip_paths
+    config.skip_extensions = skip_extensions if skip_extensions
+    config
+  end
+
+  # @deprecated Use {.init} instead
+  def self.configure
+    warn "[DEPRECATION] Mbuzz.configure is deprecated. Use Mbuzz.init(api_key: ...) instead."
+    yield(config)
+  end
+
+  # ============================================================================
+  # Context Accessors
+  # ============================================================================
+
+  def self.visitor_id
+    RequestContext.current&.request&.env&.dig(ENV_VISITOR_ID_KEY) || fallback_visitor_id
+  end
+
+  def self.fallback_visitor_id
+    @fallback_visitor_id ||= Visitor::Identifier.generate
+  end
+  private_class_method :fallback_visitor_id
+
+  def self.user_id
+    RequestContext.current&.request&.env&.dig(ENV_USER_ID_KEY)
+  end
+
+  def self.session_id
+    RequestContext.current&.request&.env&.dig(ENV_SESSION_ID_KEY)
+  end
+
+  # ============================================================================
+  # 4-Call Model API
+  # ============================================================================
+
+  # Track an event (journey step)
+  #
+  # @param event_type [String] The name of the event
+  # @param properties [Hash] Custom event properties (url, referrer auto-added)
+  # @return [Hash, false] Result hash on success, false on failure
+  #
+  # @example
+  #   Mbuzz.event("add_to_cart", product_id: "SKU-123", price: 49.99)
+  #
+  def self.event(event_type, **properties)
+    Client.track(
+      visitor_id: visitor_id,
+      session_id: session_id,
+      user_id: user_id,
+      event_type: event_type,
+      properties: enriched_properties(properties)
+    )
+  end
+
+  # @deprecated Use {.event} instead
+  def self.track(event_type, properties: {})
+    warn "[DEPRECATION] Mbuzz.track is deprecated. Use Mbuzz.event(event_type, **properties) instead."
+    event(event_type, **properties)
+  end
+
+  # Track a conversion (revenue-generating outcome)
+  #
+  # @param conversion_type [String] The type of conversion
+  # @param revenue [Numeric, nil] Revenue amount
+  # @param user_id [String, nil] User ID for acquisition-linked conversions
+  # @param is_acquisition [Boolean] Mark this as the acquisition conversion for this user
+  # @param inherit_acquisition [Boolean] Inherit attribution from user's acquisition conversion
+  # @param properties [Hash] Custom properties
+  # @return [Hash, false] Result hash on success, false on failure
+  #
+  # @example Basic conversion
+  #   Mbuzz.conversion("purchase", revenue: 99.99, order_id: "ORD-123")
+  #
+  # @example Acquisition conversion (marks signup as THE acquisition moment)
+  #   Mbuzz.conversion("signup", user_id: "user_123", is_acquisition: true)
+  #
+  # @example Recurring revenue (inherits attribution from acquisition)
+  #   Mbuzz.conversion("payment", user_id: "user_123", revenue: 49.00, inherit_acquisition: true)
+  #
+  def self.conversion(conversion_type, revenue: nil, user_id: nil, is_acquisition: false, inherit_acquisition: false, **properties)
+    Client.conversion(
+      visitor_id: visitor_id,
+      user_id: user_id,
+      conversion_type: conversion_type,
+      revenue: revenue,
+      is_acquisition: is_acquisition,
+      inherit_acquisition: inherit_acquisition,
+      properties: enriched_properties(properties)
+    )
+  end
+
+  # Identify a user and optionally link to current visitor
+  #
+  # @param user_id [String, Numeric] Your application's user identifier
+  # @param traits [Hash] User attributes (email, name, plan, etc.)
+  # @param visitor_id [String, nil] Explicit visitor ID (auto-captured from cookie if nil)
+  # @return [Hash, false] Result hash with identity_id and visitor_linked, or false on failure
+  #
+  # @example Basic identification
+  #   Mbuzz.identify("user_123", traits: { email: "jane@example.com" })
+  #
+  # @example With explicit visitor_id
+  #   Mbuzz.identify("user_123", visitor_id: "abc123...", traits: { email: "jane@example.com" })
+  #
+  def self.identify(user_id, traits: {}, visitor_id: nil)
+    Client.identify(
+      user_id: user_id,
+      visitor_id: visitor_id || self.visitor_id,
+      traits: traits
+    )
+  end
+
+  # ============================================================================
+  # Private Helpers
+  # ============================================================================
+
+  def self.enriched_properties(custom_properties)
+    return custom_properties unless RequestContext.current
+
+    RequestContext.current.enriched_properties(custom_properties)
+  end
+  private_class_method :enriched_properties
+end