omnitrack-rb 0.1.0

data/lib/omnitrack/configuration.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  # Central configuration object. Use Omnitrack.configure { |c| ... } in an initializer.
+  class Configuration
+    VALID_MODES    = %i[auto frontend backend hybrid].freeze
+    VALID_LOG_LVLS = %i[debug info warn error none].freeze
+
+    # :auto — gem detects API-only vs full-stack at runtime
+    # :frontend — always inject JS helpers / use cookies
+    # :backend  — server-side only; no JS
+    # :hybrid   — both simultaneously
+    attr_accessor :mode
+
+    # Hash keyed by adapter symbol. Each value is a sub-hash of adapter options.
+    # Example:
+    #   { google_ads: { enabled: true, customer_id: "123" },
+    #     meta:        { enabled: true, pixel_id: "456" } }
+    attr_accessor :adapters
+
+    # Automatically capture gclid / fbclid / ttclid from incoming requests
+    attr_accessor :auto_capture
+
+    # :debug | :info | :warn | :error | :none
+    attr_accessor :log_level
+
+    # Path to dedicated log file. Defaults to Rails.root/log/omnitrack.log
+    attr_accessor :log_file
+
+    # When true, dispatch tracking calls through ActiveJob (non-blocking)
+    attr_accessor :async
+
+    # Queue name used for ActiveJob tracking jobs
+    attr_accessor :queue_name
+
+    # HTTP timeout (seconds) for outbound adapter API calls
+    attr_accessor :timeout
+
+    # Max retry attempts for failed adapter calls
+    attr_accessor :max_retries
+
+    # Retry delay base in seconds (exponential back-off: delay * 2^attempt)
+    attr_accessor :retry_delay
+
+    # Hook: called with (event_name, adapter_name, error) on adapter failure
+    attr_accessor :on_error
+
+    def initialize
+      @mode         = :auto
+      @adapters     = {}
+      @auto_capture = true
+      @log_level    = :info
+      @log_file     = nil   # resolved lazily against Rails.root
+      @async        = false
+      @queue_name   = :omnitrack
+      @timeout      = 5
+      @max_retries  = 3
+      @retry_delay  = 1
+      @on_error     = nil
+    end
+
+    def validate!
+      unless VALID_MODES.include?(@mode)
+        raise Omnitrack::ConfigurationError,
+              "Invalid mode: #{@mode.inspect}. Must be one of #{VALID_MODES}"
+      end
+
+      unless VALID_LOG_LVLS.include?(@log_level)
+        raise Omnitrack::ConfigurationError,
+              "Invalid log_level: #{@log_level.inspect}. Must be one of #{VALID_LOG_LVLS}"
+      end
+
+      true
+    end
+
+    # Returns the resolved log file path (String)
+    def resolved_log_file
+      return @log_file.to_s if @log_file
+
+      if defined?(Rails) && Rails.root
+        Rails.root.join("log", "omnitrack.log").to_s
+      else
+        "log/omnitrack.log"
+      end
+    end
+
+    # Returns the hash config for a specific adapter (or {})
+    def adapter_config(name)
+      @adapters.fetch(name.to_sym, {})
+    end
+
+    # True when the given adapter is enabled in config
+    def adapter_enabled?(name)
+      cfg = adapter_config(name)
+      cfg.fetch(:enabled, false)
+    end
+
+    # Effective Rails mode — resolves :auto at runtime
+    def effective_mode
+      return @mode unless @mode == :auto
+
+      if defined?(Rails) && Rails.application
+        Rails.application.config.api_only ? :backend : :frontend
+      else
+        :backend
+      end
+    end
+  end
+end

data/lib/omnitrack/context.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  # Captures and exposes tracking parameters from a Rack request.
+  # Works in both cookie-based (full-stack) and cookie-free (API-only) modes.
+  #
+  # Stored per-request in thread-local storage via Omnitrack::Context.current.
+  class Context
+    CLICK_ID_PARAMS = %w[gclid fbclid ttclid sclid msclkid].freeze
+    UTM_PARAMS      = %w[utm_source utm_medium utm_campaign utm_term utm_content].freeze
+
+    # Thread-local current context — set by the middleware
+    def self.current
+      Thread.current[:omnitrack_context]
+    end
+
+    def self.current=(ctx)
+      Thread.current[:omnitrack_context] = ctx
+    end
+
+    def self.clear!
+      Thread.current[:omnitrack_context] = nil
+    end
+
+    # Build a Context from a Rack::Request object
+    def self.from_request(request)
+      new(
+        ip:          extract_ip(request),
+        user_agent:  request.env["HTTP_USER_AGENT"],
+        click_ids:   extract_click_ids(request),
+        utm_params:  extract_utm_params(request),
+        cookies:     safe_cookies(request),
+        headers:     extract_tracking_headers(request)
+      )
+    end
+
+    attr_reader :ip, :user_agent, :click_ids, :utm_params, :cookies, :headers,
+                :custom_data
+
+    def initialize(ip: nil, user_agent: nil, click_ids: {}, utm_params: {},
+                   cookies: {}, headers: {}, custom_data: {})
+      @ip          = ip
+      @user_agent  = user_agent
+      @click_ids   = click_ids.transform_keys(&:to_sym)
+      @utm_params  = utm_params.transform_keys(&:to_sym)
+      @cookies     = cookies
+      @headers     = headers
+      @custom_data = custom_data || {}
+    end
+
+    # Merge extra data into the context (e.g., from a controller concern)
+    def merge!(data = {})
+      @custom_data.merge!(data.to_h)
+      self
+    end
+
+    def gclid  = click_ids[:gclid]
+    def fbclid = click_ids[:fbclid]
+    def ttclid = click_ids[:ttclid]
+
+    # Full context as a hash — passed into adapter payloads
+    def to_h
+      {
+        ip:          @ip,
+        user_agent:  @user_agent,
+        click_ids:   @click_ids,
+        utm_params:  @utm_params,
+        custom_data: @custom_data
+      }.reject { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+    end
+
+    # -------------------------------------------------------------------
+    # Private extraction helpers
+    # -------------------------------------------------------------------
+
+    def self.extract_ip(request)
+      # Respect common proxy headers
+      forwarded = request.env["HTTP_X_FORWARDED_FOR"]
+      if forwarded
+        forwarded.split(",").first.to_s.strip
+      else
+        request.ip
+      end
+    end
+    private_class_method :extract_ip
+
+    def self.extract_click_ids(request)
+      CLICK_ID_PARAMS.each_with_object({}) do |param, h|
+        value = request.params[param] ||
+                request.env["HTTP_X_#{param.upcase}"]
+        h[param] = value if value && !value.empty?
+      end
+    end
+    private_class_method :extract_click_ids
+
+    def self.extract_utm_params(request)
+      UTM_PARAMS.each_with_object({}) do |param, h|
+        value = request.params[param]
+        h[param] = value if value && !value.empty?
+      end
+    end
+    private_class_method :extract_utm_params
+
+    def self.safe_cookies(request)
+      request.cookies.to_h
+    rescue StandardError
+      {}
+    end
+    private_class_method :safe_cookies
+
+    def self.extract_tracking_headers(request)
+      {
+        referer:          request.env["HTTP_REFERER"],
+        accept_language:  request.env["HTTP_ACCEPT_LANGUAGE"]
+      }.compact
+    end
+    private_class_method :extract_tracking_headers
+  end
+end

data/lib/omnitrack/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  # Base class for all Omnitrack errors
+  class Error < StandardError; end
+
+  # Raised when the gem is misconfigured
+  class ConfigurationError < Error; end
+
+  # Raised (and caught internally) when an adapter API call fails.
+  # Carries the original exception for diagnostics.
+  class AdapterError < Error
+    attr_reader :original
+
+    def initialize(message = nil, original: nil)
+      super(message)
+      @original = original
+    end
+  end
+
+  # Raised when an event payload fails validation
+  class InvalidPayloadError < Error; end
+
+  # Raised when an adapter is referenced but not registered
+  class UnknownAdapterError < Error; end
+end

data/lib/omnitrack/helpers/view_helpers.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Omnitrack
+  module Helpers
+    # Rails view helpers for injecting tracking pixels and JS snippets.
+    # Auto-included in ActionView::Base by the Railtie when in frontend mode.
+    module ViewHelpers
+      # Emit all enabled platform JS/pixel tags as a single HTML blob.
+      # Place in your layout <head>:
+      #   <%= omnitrack_tags %>
+      def omnitrack_tags
+        return "".html_safe unless Omnitrack.frontend_mode?
+
+        tags = []
+        tags << google_analytics_tag    if Omnitrack.config.adapter_enabled?(:google_analytics)
+        tags << meta_pixel_tag          if Omnitrack.config.adapter_enabled?(:meta)
+        tags << tiktok_pixel_tag        if Omnitrack.config.adapter_enabled?(:tiktok)
+        tags << snapchat_pixel_tag      if Omnitrack.config.adapter_enabled?(:snapchat)
+
+        tags.compact.join("\n").html_safe
+      end
+
+      # Emit a single <script> block to push a custom event to all enabled platforms.
+      # Place after a key action (e.g., order confirmation page):
+      #   <%= omnitrack_event_tag("purchase", value: 99.00, currency: "USD") %>
+      def omnitrack_event_tag(event_name, **payload)
+        return "".html_safe unless Omnitrack.frontend_mode?
+
+        js = []
+        js << gtag_event(event_name, payload) if Omnitrack.config.adapter_enabled?(:google_analytics)
+        js << fbq_event(event_name, payload)  if Omnitrack.config.adapter_enabled?(:meta)
+        js << ttq_event(event_name, payload)  if Omnitrack.config.adapter_enabled?(:tiktok)
+
+        return "".html_safe if js.empty?
+
+        content_tag(:script) { js.join("\n").html_safe }
+      end
+
+      private
+
+      # ------------------------------------------------------------------
+      # Platform-specific tag builders
+      # ------------------------------------------------------------------
+
+      def google_analytics_tag
+        measurement_id = Omnitrack.config.adapter_config(:google_analytics)[:measurement_id]
+        return unless measurement_id.present?
+
+        <<~HTML
+          <!-- OmniTrack: Google Analytics 4 -->
+          <script async src="https://www.googletagmanager.com/gtag/js?id=#{measurement_id}"></script>
+          <script>
+            window.dataLayer = window.dataLayer || [];
+            function gtag(){dataLayer.push(arguments);}
+            gtag('js', new Date());
+            gtag('config', '#{measurement_id}');
+          </script>
+        HTML
+      end
+
+      def meta_pixel_tag
+        pixel_id = Omnitrack.config.adapter_config(:meta)[:pixel_id]
+        return unless pixel_id.present?
+
+        <<~HTML
+          <!-- OmniTrack: Meta Pixel -->
+          <script>
+            !function(f,b,e,v,n,t,s)
+            {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
+            n.callMethod.apply(n,arguments):n.queue.push(arguments)};
+            if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
+            n.queue=[];t=b.createElement(e);t.async=!0;
+            t.src=v;s=b.getElementsByTagName(e)[0];
+            s.parentNode.insertBefore(t,s)}(window, document,'script',
+            'https://connect.facebook.net/en_US/fbevents.js');
+            fbq('init', '#{pixel_id}');
+            fbq('track', 'PageView');
+          </script>
+          <noscript>
+            <img height="1" width="1" style="display:none"
+                 src="https://www.facebook.com/tr?id=#{pixel_id}&ev=PageView&noscript=1"/>
+          </noscript>
+        HTML
+      end
+
+      def tiktok_pixel_tag
+        pixel_id = Omnitrack.config.adapter_config(:tiktok)[:pixel_id]
+        return unless pixel_id.present?
+
+        <<~HTML
+          <!-- OmniTrack: TikTok Pixel -->
+          <script>
+            !function (w, d, t) {
+              w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];
+              ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"];
+              ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};
+              for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);
+              ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};
+              ttq.load=function(e,n){var i="https://analytics.tiktok.com/i18n/pixel/events.js";
+              ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=i,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};
+              var o=document.createElement("script");o.type="text/javascript";o.async=!0;o.src=i+"?sdkid="+e+"&lib="+t;
+              var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};
+              ttq.load('#{pixel_id}');
+              ttq.page();
+            }(window, document, 'ttq');
+          </script>
+        HTML
+      end
+
+      def snapchat_pixel_tag
+        pixel_id = Omnitrack.config.adapter_config(:snapchat)[:pixel_id]
+        return unless pixel_id.present?
+
+        <<~HTML
+          <!-- OmniTrack: Snapchat Pixel -->
+          <script type='text/javascript'>
+            (function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()
+            {a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};
+            a.queue=[];var s='script';r=t.createElement(s);r.async=!0;
+            r.src=n;var u=t.getElementsByTagName(s)[0];
+            u.parentNode.insertBefore(r,u);})(window,document,
+            'https://sc-static.net/scevent.min.js');
+            snaptr('init', '#{pixel_id}', {});
+            snaptr('track', 'PAGE_VIEW');
+          </script>
+        HTML
+      end
+
+      # ------------------------------------------------------------------
+      # JS event helpers
+      # ------------------------------------------------------------------
+
+      def gtag_event(event_name, payload)
+        "gtag('event', '#{event_name}', #{payload.to_json});"
+      end
+
+      def fbq_event(event_name, payload)
+        "fbq('track', '#{event_name}', #{payload.to_json});"
+      end
+
+      def ttq_event(event_name, payload)
+        "ttq.track('#{event_name}', #{payload.to_json});"
+      end
+    end
+  end
+end

data/lib/omnitrack/jobs/tracking_job.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  module Jobs
+    # ActiveJob wrapper for asynchronous event dispatch.
+    # Enqueued automatically when Omnitrack.config.async == true.
+    #
+    # The job serializes the operation + arguments to JSON so they survive
+    # the queue boundary. All arguments must be plain Ruby primitives.
+    #
+    class TrackingJob < ActiveJob::Base
+      queue_as { Omnitrack.config.queue_name }
+
+      # @param operation [String]  stringified symbol, e.g. "track_event"
+      # @param args      [Array]   JSON-serialisable positional arguments
+      def perform(operation, *args)
+        Omnitrack::Pipeline::Dispatcher.dispatch(operation.to_sym, *args)
+      rescue StandardError => e
+        Omnitrack.logger.error("tracking_job.error",
+                               operation: operation,
+                               error:     e.class.name,
+                               message:   e.message)
+        raise # Re-raise so ActiveJob retry logic still works
+      end
+    end
+  end
+end

data/lib/omnitrack/logger.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "logger"
+require "json"
+
+module Omnitrack
+  # Structured JSON logger that writes to a dedicated omnitrack.log file.
+  # All public methods are thread-safe (delegating to Ruby's stdlib Logger).
+  class Logger
+    SEVERITY_MAP = {
+      debug: ::Logger::DEBUG,
+      info:  ::Logger::INFO,
+      warn:  ::Logger::WARN,
+      error: ::Logger::ERROR,
+      none:  ::Logger::UNKNOWN
+    }.freeze
+
+    def initialize(log_file:, log_level: :info)
+      @level    = log_level.to_sym
+      @log_file = log_file
+      @backend  = build_backend(log_file)
+      apply_level!
+    end
+
+    # -------------------------------------------------------------------
+    # Public logging API
+    # -------------------------------------------------------------------
+
+    def debug(message, **context)
+      write(:debug, message, context)
+    end
+
+    def info(message, **context)
+      write(:info, message, context)
+    end
+
+    def warn(message, **context)
+      write(:warn, message, context)
+    end
+
+    def error(message, **context)
+      write(:error, message, context)
+    end
+
+    # Convenience: log an adapter request
+    def log_request(adapter:, event:, payload: {})
+      info("adapter.request",
+           adapter: adapter,
+           event:   event,
+           payload: payload)
+    end
+
+    # Convenience: log an adapter response
+    def log_response(adapter:, event:, status:, body: nil, duration_ms: nil)
+      info("adapter.response",
+           adapter:     adapter,
+           event:       event,
+           status:      status,
+           body:        body,
+           duration_ms: duration_ms)
+    end
+
+    # Convenience: log an adapter error
+    def log_error(adapter:, event:, error:, attempt: nil)
+      error("adapter.error",
+            adapter:   adapter,
+            event:     event,
+            error:     error.class.name,
+            message:   error.message,
+            attempt:   attempt,
+            backtrace: error.backtrace&.first(5))
+    end
+
+    # Re-open the log file (useful after logrotate)
+    def reopen
+      @backend.reopen(@log_file)
+    end
+
+    private
+
+    def build_backend(log_file)
+      # Ensure directory exists
+      dir = File.dirname(log_file)
+      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+
+      backend = ::Logger.new(log_file, "daily")
+      backend.formatter = method(:json_formatter)
+      backend
+    end
+
+    def apply_level!
+      @backend.level = SEVERITY_MAP.fetch(@level, ::Logger::INFO)
+    end
+
+    def write(severity, message, context)
+      return if @level == :none
+
+      @backend.public_send(severity, build_payload(message, context))
+    rescue StandardError
+      # Never let logger failures propagate into the main app
+    end
+
+    def build_payload(message, context)
+      {
+        timestamp: Time.now.utc.iso8601(3),
+        message:   message
+      }.merge(compact_context(context))
+    end
+
+    def compact_context(context)
+      context.reject { |_, v| v.nil? }
+    end
+
+    def json_formatter(_severity, _time, _progname, msg)
+      payload = msg.is_a?(Hash) ? msg : { message: msg.to_s }
+      "#{JSON.generate(payload)}\n"
+    rescue StandardError
+      "#{msg}\n"
+    end
+  end
+end

data/lib/omnitrack/middleware/request_tracker.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module Omnitrack
+  module Middleware
+    # Rack middleware that:
+    #  1. Builds an Omnitrack::Context from the incoming request
+    #  2. Makes it available thread-locally as Omnitrack::Context.current
+    #  3. Clears it after the response (prevents cross-request data leakage)
+    #
+    # Auto-inserted by the Railtie; can also be added manually:
+    #   config.middleware.use Omnitrack::Middleware::RequestTracker
+    #
+    class RequestTracker
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+
+        if Omnitrack.config.auto_capture
+          ctx = Omnitrack::Context.from_request(request)
+          Omnitrack::Context.current = ctx
+
+          Omnitrack.logger.debug("middleware.request",
+                                 method:     request.request_method,
+                                 path:       request.path,
+                                 click_ids:  ctx.click_ids,
+                                 utm_params: ctx.utm_params)
+        end
+
+        @app.call(env)
+      ensure
+        Omnitrack::Context.clear!
+      end
+    end
+  end
+end

data/lib/omnitrack/pipeline/dispatcher.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  module Pipeline
+    # Central event dispatcher.
+    # Instantiates all enabled adapters, runs the requested operation on each,
+    # and returns an Omnitrack::MultiResult.
+    #
+    # Usage (called by Omnitrack module methods):
+    #   Omnitrack::Pipeline::Dispatcher.dispatch(:track_event, "purchase", payload)
+    #
+    class Dispatcher
+      class << self
+        # @param operation [Symbol]  one of :track_event, :track_conversion, :identify_user
+        # @param args      [Array]   forwarded to the adapter method
+        # @return [Omnitrack::MultiResult]
+        def dispatch(operation, *args)
+          adapters = Omnitrack::Registry.enabled_adapters
+
+          if adapters.empty?
+            Omnitrack.logger.warn("dispatcher.no_adapters",
+                                  operation: operation)
+            return Omnitrack::MultiResult.new([
+              Omnitrack::Result.skipped(reason: "no enabled adapters")
+            ])
+          end
+
+          results = adapters.map do |adapter|
+            dispatch_to(adapter, operation, args)
+          end
+
+          Omnitrack::MultiResult.new(results)
+        end
+
+        private
+
+        def dispatch_to(adapter, operation, args)
+          unless adapter.respond_to?(operation)
+            return Omnitrack::Result.skipped(
+              reason: "#{adapter.name} does not implement #{operation}",
+              adapter: adapter.name
+            )
+          end
+
+          adapter.public_send(operation, *args)
+        rescue StandardError => e
+          # Adapter-level isolation — one adapter blowing up must not affect others
+          Omnitrack.logger.log_error(adapter: adapter.name,
+                                     event:   operation.to_s,
+                                     error:   e)
+          Omnitrack::Result.failure(error: e, adapter: adapter.name)
+        end
+      end
+    end
+  end
+end