omnitrack-rb 0.1.0

data/lib/omnitrack/railtie.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  # Railtie hooks OmniTrack into Rails automatically.
+  # No user action required — simply add the gem and run the installer.
+  class Railtie < Rails::Railtie
+    # Allow Rails config namespace: config.omnitrack.mode = :backend
+    config.omnitrack = ActiveSupport::OrderedOptions.new
+
+    initializer "omnitrack.tracking_job" do
+      if defined?(ActiveJob::Base)
+        require_relative "jobs/tracking_job"
+      end
+    end
+
+    initializer "omnitrack.configure" do |app|
+      # Map any rails config keys into Omnitrack config
+      rails_cfg = app.config.omnitrack
+      if rails_cfg.any?
+        Omnitrack.configure do |c|
+          c.mode      = rails_cfg[:mode]      if rails_cfg[:mode]
+          c.log_level = rails_cfg[:log_level] if rails_cfg[:log_level]
+          c.async     = rails_cfg[:async]     if rails_cfg.key?(:async)
+        end
+      end
+    end
+
+    initializer "omnitrack.middleware" do |app|
+      app.middleware.use Omnitrack::Middleware::RequestTracker
+    end
+
+    initializer "omnitrack.view_helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include Omnitrack::Helpers::ViewHelpers
+      end
+    end
+
+    initializer "omnitrack.controller_helpers" do
+      ActiveSupport.on_load(:action_controller) do
+        include Omnitrack::Controller
+      end
+    end
+
+    initializer "omnitrack.logger_setup" do
+      Omnitrack.send(:reset_logger!)
+    end
+
+    # Expose rake tasks
+    rake_tasks do
+      load File.join(__dir__, "tasks/omnitrack.rake")
+    end
+  end
+end

data/lib/omnitrack/registry.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  # Thread-safe registry mapping adapter names (symbols) → adapter classes.
+  # Adapters are auto-registered via Base.inherited and can also be registered
+  # manually with Registry.register.
+  module Registry
+    MUTEX = Mutex.new
+    private_constant :MUTEX
+
+    @adapters = {}
+
+    class << self
+      # Register an adapter class.
+      # @param klass [Class] must inherit from Omnitrack::Adapters::Base
+      def register(klass)
+        MUTEX.synchronize do
+          @adapters[klass.adapter_name] = klass
+        end
+      end
+
+      # Look up an adapter class by name.
+      # @param name [Symbol, String]
+      # @return [Class]
+      # @raise [Omnitrack::UnknownAdapterError]
+      def lookup(name)
+        klass = MUTEX.synchronize { @adapters[name.to_sym] }
+        raise Omnitrack::UnknownAdapterError, "Unknown adapter: #{name}" unless klass
+
+        klass
+      end
+
+      # All registered adapter names
+      def registered
+        MUTEX.synchronize { @adapters.keys }
+      end
+
+      # Instantiate all *enabled* adapters based on current configuration.
+      # @return [Array<Omnitrack::Adapters::Base>]
+      def enabled_adapters
+        MUTEX.synchronize { @adapters.dup }.filter_map do |adapter_name, klass|
+          cfg = Omnitrack.config.adapter_config(adapter_name)
+          next unless cfg.fetch(:enabled, false)
+
+          klass.new(config: cfg, logger: Omnitrack.logger)
+        rescue Omnitrack::ConfigurationError => e
+          Omnitrack.logger.error("registry.init_error",
+                                 adapter: adapter_name, message: e.message)
+          nil
+        end
+      end
+
+      # Clear all registrations (useful in tests)
+      def reset!
+        MUTEX.synchronize { @adapters = {} }
+      end
+    end
+  end
+end

data/lib/omnitrack/result.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Omnitrack
+  # Immutable value object returned by every adapter call.
+  # Provides a consistent interface regardless of platform.
+  class Result
+    attr_reader :status, :adapter, :data, :error, :metadata
+
+    def initialize(status:, adapter: nil, data: nil, error: nil, metadata: {})
+      @status   = status.to_sym   # :success | :failure | :skipped
+      @adapter  = adapter
+      @data     = data
+      @error    = error
+      @metadata = metadata || {}
+      freeze
+    end
+
+    # -------------------------------------------------------------------
+    # Factory methods
+    # -------------------------------------------------------------------
+
+    def self.success(adapter: nil, data: nil, metadata: {})
+      new(status: :success, adapter: adapter, data: data, metadata: metadata)
+    end
+
+    def self.failure(error: nil, adapter: nil, metadata: {})
+      new(status: :failure, adapter: adapter, error: error, metadata: metadata)
+    end
+
+    def self.skipped(reason: nil, adapter: nil)
+      new(status: :skipped, adapter: adapter,
+          metadata: { reason: reason })
+    end
+
+    # -------------------------------------------------------------------
+    # Predicate helpers
+    # -------------------------------------------------------------------
+
+    def success?
+      @status == :success
+    end
+
+    def failure?
+      @status == :failure
+    end
+
+    def skipped?
+      @status == :skipped
+    end
+
+    # -------------------------------------------------------------------
+    # Serialisation
+    # -------------------------------------------------------------------
+
+    def to_h
+      {
+        status:   @status,
+        adapter:  @adapter,
+        data:     @data,
+        error:    @error&.message,
+        metadata: @metadata
+      }
+    end
+
+    def to_json(*args)
+      require "json"
+      JSON.generate(to_h, *args)
+    end
+
+    def inspect
+      "#<Omnitrack::Result status=#{@status} adapter=#{@adapter} " \
+        "error=#{@error&.message.inspect}>"
+    end
+  end
+
+  # Aggregated result for pipeline dispatches (one result per adapter)
+  class MultiResult
+    include Enumerable
+
+    attr_reader :results
+
+    def initialize(results = [])
+      @results = results.freeze
+    end
+
+    def each(&block)
+      @results.each(&block)
+    end
+
+    def success?
+      @results.all?(&:success?)
+    end
+
+    def any_failure?
+      @results.any?(&:failure?)
+    end
+
+    def failures
+      @results.select(&:failure?)
+    end
+
+    def successes
+      @results.select(&:success?)
+    end
+
+    def to_h
+      {
+        success:  success?,
+        results:  @results.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/omnitrack/tasks/omnitrack.rake

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+namespace :omnitrack do
+  desc "Show OmniTrack configuration and registered adapters"
+  task status: :environment do
+    puts "\n=== OmniTrack v#{Omnitrack::VERSION} ===\n"
+    puts "Mode:       #{Omnitrack.config.effective_mode}"
+    puts "Log file:   #{Omnitrack.config.resolved_log_file}"
+    puts "Log level:  #{Omnitrack.config.log_level}"
+    puts "Async:      #{Omnitrack.config.async}"
+    puts "Queue:      #{Omnitrack.config.queue_name}"
+    puts "\nRegistered adapters:"
+    Omnitrack::Registry.registered.each do |adapter_name|
+      enabled = Omnitrack.config.adapter_enabled?(adapter_name)
+      status  = enabled ? "✓ enabled" : "✗ disabled"
+      puts "  #{adapter_name.to_s.ljust(20)} #{status}"
+    end
+    puts ""
+  end
+
+  desc "Send a test event through all enabled adapters"
+  task :test_event, [:event_name] => :environment do |_, args|
+    event = args[:event_name] || "test_event"
+    puts "Sending test event '#{event}' through all enabled adapters..."
+    result = Omnitrack.track(event, value: 1.0, currency: "USD", test: true)
+    result.each do |r|
+      icon = r.success? ? "✓" : (r.skipped? ? "–" : "✗")
+      puts "  #{icon} #{r.adapter}: #{r.status}"
+      puts "    error: #{r.error&.message}" if r.failure?
+    end
+    puts ""
+  end
+
+  desc "Rotate OmniTrack log file"
+  task rotate_log: :environment do
+    Omnitrack.logger.reopen
+    puts "OmniTrack log rotated: #{Omnitrack.config.resolved_log_file}"
+  end
+end

data/lib/omnitrack/version.rb

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

data/lib/omnitrack.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/inflections"
+require "fileutils"
+require "securerandom"
+
+require_relative "omnitrack/version"
+require_relative "omnitrack/errors"
+require_relative "omnitrack/result"
+require_relative "omnitrack/configuration"
+require_relative "omnitrack/logger"
+require_relative "omnitrack/context"
+require_relative "omnitrack/registry"
+require_relative "omnitrack/pipeline/dispatcher"
+require_relative "omnitrack/adapters/base"
+require_relative "omnitrack/adapters/google_ads"
+require_relative "omnitrack/adapters/google_analytics"
+require_relative "omnitrack/adapters/meta"
+require_relative "omnitrack/adapters/tiktok"
+require_relative "omnitrack/adapters/snapchat"
+require_relative "omnitrack/middleware/request_tracker"
+require_relative "omnitrack/helpers/view_helpers"
+require_relative "omnitrack/concerns/controller"
+
+# Lazy-load Rails integrations only when Rails is present
+if defined?(Rails)
+  require_relative "omnitrack/railtie"
+  require_relative "generators/omnitrack/install/install_generator"
+end
+
+# ==============================================================================
+# Omnitrack
+# ==============================================================================
+# Top-level module providing the primary public API.
+#
+# Usage:
+#   Omnitrack.configure { |c| c.adapters = { ... } }
+#   Omnitrack.track("purchase", value: 99.00, currency: "USD")
+#   Omnitrack.track_conversion(value: 99.00, order_id: "ORD-001")
+#   Omnitrack.identify(email: "user@example.com")
+#
+module Omnitrack
+  class << self
+    # -------------------------------------------------------------------
+    # Configuration
+    # -------------------------------------------------------------------
+
+    # Access the global configuration object.
+    # @return [Omnitrack::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Configure OmniTrack via block.
+    #
+    #   Omnitrack.configure do |c|
+    #     c.mode    = :hybrid
+    #     c.adapters = { meta: { enabled: true, pixel_id: "..." } }
+    #   end
+    #
+    def configure
+      yield config
+      config.validate!
+      reset_logger!
+      self
+    end
+
+    # Reset configuration and logger (useful in tests)
+    def reset!
+      @config = nil
+      @logger = nil
+      Omnitrack::Registry.reset!
+      # Re-bind built-in adapters without reloading (avoids duplicate constant/method warnings)
+      [
+        Omnitrack::Adapters::GoogleAds,
+        Omnitrack::Adapters::GoogleAnalytics,
+        Omnitrack::Adapters::Meta,
+        Omnitrack::Adapters::TikTok,
+        Omnitrack::Adapters::Snapchat
+      ].each { |adapter_class| Omnitrack::Registry.register(adapter_class) }
+    end
+
+    # -------------------------------------------------------------------
+    # Logger
+    # -------------------------------------------------------------------
+
+    # @return [Omnitrack::Logger]
+    def logger
+      @logger ||= build_logger
+    end
+
+    # -------------------------------------------------------------------
+    # Public tracking API
+    # -------------------------------------------------------------------
+
+    # Track a named event across all enabled adapters.
+    #
+    # @param event_name [String, Symbol]
+    # @param payload    [Hash]
+    # @return [Omnitrack::MultiResult]
+    def track(event_name, payload = {})
+      dispatch(:track_event, event_name.to_s, payload.to_h)
+    end
+
+    # Track a conversion across all enabled adapters.
+    #
+    # @param data [Hash]
+    # @return [Omnitrack::MultiResult]
+    def track_conversion(data = {})
+      dispatch(:track_conversion, data.to_h)
+    end
+
+    # Identify a user across all enabled adapters.
+    #
+    # @param user_data [Hash]  keys: :email, :phone, :external_id, :first_name, :last_name, etc.
+    # @return [Omnitrack::MultiResult]
+    def identify(user_data = {})
+      dispatch(:identify_user, user_data.to_h)
+    end
+
+    # -------------------------------------------------------------------
+    # Mode helpers
+    # -------------------------------------------------------------------
+
+    def frontend_mode?
+      %i[frontend hybrid].include?(config.effective_mode)
+    end
+
+    def backend_mode?
+      %i[backend hybrid].include?(config.effective_mode)
+    end
+
+    private
+
+    def dispatch(operation, *args)
+      if config.async && defined?(Omnitrack::Jobs::TrackingJob)
+        Omnitrack::Jobs::TrackingJob.perform_later(operation.to_s, *args)
+        return Omnitrack::MultiResult.new([
+          Omnitrack::Result.success(metadata: { queued: true, operation: operation })
+        ])
+      end
+
+      Omnitrack::Pipeline::Dispatcher.dispatch(operation, *args)
+    rescue StandardError => e
+      # Top-level safety net — never raise into the host application
+      logger.error("omnitrack.dispatch_error",
+                   operation: operation, error: e.class.name, message: e.message)
+      Omnitrack::MultiResult.new([
+        Omnitrack::Result.failure(error: e)
+      ])
+    end
+
+    def build_logger
+      Omnitrack::Logger.new(
+        log_file:  config.resolved_log_file,
+        log_level: config.log_level
+      )
+    end
+
+    def reset_logger!
+      @logger = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,207 @@
+--- !ruby/object:Gem::Specification
+name: omnitrack-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Your Name
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: |
+  OmniTrack is a production-grade tracking and conversion gem for Ruby on Rails.
+  It supports multiple ad/analytics platforms (Google Ads, GA4, Meta, TikTok, Snapchat)
+  via a clean adapter pattern, works in both full-stack and API-only Rails apps,
+  and provides structured logging, background job support, and an extensible pipeline.
+email:
+- you@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.example"
+- AI_GEM_SETUP.md
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- USAGE.md
+- lib/generators/omnitrack/install/install_generator.rb
+- lib/generators/omnitrack/install/templates/README
+- lib/generators/omnitrack/install/templates/env.example
+- lib/generators/omnitrack/install/templates/initializer.rb
+- lib/omnitrack.rb
+- lib/omnitrack/adapters/base.rb
+- lib/omnitrack/adapters/google_ads.rb
+- lib/omnitrack/adapters/google_analytics.rb
+- lib/omnitrack/adapters/meta.rb
+- lib/omnitrack/adapters/snapchat.rb
+- lib/omnitrack/adapters/tiktok.rb
+- lib/omnitrack/concerns/controller.rb
+- lib/omnitrack/configuration.rb
+- lib/omnitrack/context.rb
+- lib/omnitrack/errors.rb
+- lib/omnitrack/helpers/view_helpers.rb
+- lib/omnitrack/jobs/tracking_job.rb
+- lib/omnitrack/logger.rb
+- lib/omnitrack/middleware/request_tracker.rb
+- lib/omnitrack/pipeline/dispatcher.rb
+- lib/omnitrack/railtie.rb
+- lib/omnitrack/registry.rb
+- lib/omnitrack/result.rb
+- lib/omnitrack/tasks/omnitrack.rake
+- lib/omnitrack/version.rb
+homepage: https://github.com/yourorg/omnitrack-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yourorg/omnitrack-rb
+  source_code_uri: https://github.com/yourorg/omnitrack-rb
+  changelog_uri: https://github.com/yourorg/omnitrack-rb/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Flexible, modular tracking and conversion system for Rails
+test_files: []