track_relay 1.0.0

data/lib/track_relay/testing/minitest_assertions.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module TrackRelay
+  module Testing
+    # Minitest assertions for use against the active
+    # {TrackRelay::Subscribers::Test} (the one installed by
+    # {TrackRelay.test_mode!}).
+    #
+    # Designed to be mixed into `ActiveSupport::TestCase` /
+    # `Minitest::Test` either directly or via {Helpers}, which also
+    # registers per-test setup/teardown to enable test mode automatically.
+    #
+    # Used directly:
+    #
+    #   class MyTest < ActiveSupport::TestCase
+    #     include TrackRelay::Testing::MinitestAssertions
+    #
+    #     setup    { TrackRelay.test_mode! }
+    #     teardown { TrackRelay.test_mode_off! }
+    #
+    #     test "fires :foo" do
+    #       MyService.run!
+    #       assert_tracked :foo, user_id: 1
+    #     end
+    #   end
+    #
+    # Or via {Helpers}, which wires the setup/teardown for you.
+    module MinitestAssertions
+      # Return the active Test subscriber, or raise a helpful message
+      # if {TrackRelay.test_mode!} has not been called yet.
+      #
+      # @raise [RuntimeError]
+      # @return [TrackRelay::Subscribers::Test]
+      def track_relay_test
+        TrackRelay.test_subscriber ||
+          raise("Call TrackRelay.test_mode! before using assert_tracked / refute_tracked")
+      end
+
+      # Assert at least one event named `name` was captured. When
+      # `expected_params` is supplied, also assert at least one matching
+      # event has params that include every key/value pair in
+      # `expected_params` (subset semantics).
+      #
+      # @param name [Symbol]
+      # @param expected_params [Hash{Symbol => Object}]
+      # @raise [Minitest::Assertion] when the assertion fails
+      # @return [void]
+      def assert_tracked(name, **expected_params)
+        events = track_relay_test.find(name)
+        assert events.any?,
+          "Expected an event :#{name} to be tracked, but found #{track_relay_test.events.map(&:name).inspect}"
+        return if expected_params.empty?
+
+        match = events.find { |e| expected_params.all? { |k, v| e.params[k] == v } }
+        assert match,
+          "Expected :#{name} with params >= #{expected_params.inspect}, got #{events.map(&:params).inspect}"
+      end
+
+      # Assert no event named `name` was captured.
+      #
+      # @param name [Symbol]
+      # @raise [Minitest::Assertion] when an event named `name` was tracked
+      # @return [void]
+      def refute_tracked(name)
+        events = track_relay_test.find(name)
+        refute events.any?,
+          "Expected no event :#{name} to be tracked, but got #{events.map(&:params).inspect}"
+      end
+    end
+  end
+end

data/lib/track_relay/testing/rspec_matchers.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# RSpec matchers for {TrackRelay}.
+#
+# Loaded conditionally — guarded by `defined?(RSpec)` so requiring
+# `track_relay/testing` is safe even when RSpec is not on the load
+# path. Consumers who use RSpec require this file from their
+# `rails_helper.rb` (or rely on the auto-load below from
+# `track_relay/testing.rb`).
+#
+# Provided matchers:
+#
+#   - `have_tracked(name)` — passes when at least one event named
+#     `name` was captured by the active Test subscriber. Supports
+#     `.with(**params)` to require subset-matching params on at least
+#     one captured event.
+#   - `have_identified(user)` — Phase-01 placeholder that never
+#     matches; identify capture in the Test subscriber is deferred to
+#     Phase 02.
+#
+# Usage:
+#
+#   require "track_relay/testing"
+#
+#   RSpec.describe "checkout" do
+#     before { TrackRelay.test_mode! }
+#     after  { TrackRelay.test_mode_off! }
+#
+#     it "fires :purchase" do
+#       Checkout.run!
+#       expect(track_relay).to have_tracked(:purchase).with(amount_cents: 1999)
+#     end
+#   end
+#
+# The `track_relay` example-group helper (registered below) returns
+# the active Test subscriber so `expect(track_relay).to ...` reads
+# naturally. The matcher itself reads the global
+# `TrackRelay.test_subscriber`, so the receiver is mostly stylistic.
+if defined?(RSpec)
+  RSpec::Matchers.define :have_tracked do |name|
+    match do |_actual|
+      raise "Call TrackRelay.test_mode! before have_tracked" unless TrackRelay::Testing.active?
+      events = TrackRelay.test_subscriber.find(name)
+      next false if events.empty?
+      next true if @expected_params.nil?
+      events.any? { |e| @expected_params.all? { |k, v| e.params[k] == v } }
+    end
+
+    chain :with do |params|
+      @expected_params = params
+    end
+
+    failure_message do |_actual|
+      seen = TrackRelay.test_subscriber.events.map { |e| {name: e.name, params: e.params} }
+      msg = "expected an event :#{name} to be tracked"
+      msg += " with params >= #{@expected_params.inspect}" if @expected_params
+      "#{msg}, but got #{seen.inspect}"
+    end
+  end
+
+  RSpec::Matchers.define :have_identified do |_user|
+    # Phase 01 placeholder: identify capture is not yet wired into the
+    # Test subscriber. Documented as TODO for Phase 02.
+    match { |_actual| false }
+    failure_message { "have_identified is not yet implemented in Phase 01" }
+  end
+
+  if defined?(RSpec.configure)
+    RSpec.configure do |config|
+      config.include(Module.new do
+        # Returns the active Test subscriber so RSpec example groups
+        # can write `expect(track_relay).to have_tracked(...)`.
+        def track_relay
+          TrackRelay.test_subscriber || raise("Call TrackRelay.test_mode! first")
+        end
+      end)
+    end
+  end
+end

data/lib/track_relay/testing.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "track_relay"
+require "track_relay/subscribers/test"
+
+module TrackRelay
+  # Opt-in testing entry point for {TrackRelay}.
+  #
+  # `lib/track_relay.rb` does NOT require this file — consumers add
+  # `require "track_relay/testing"` themselves in their `test_helper.rb`
+  # / `rails_helper.rb`. This keeps the auto setup/teardown helpers and
+  # the RSpec matcher hooks out of production runtime. The gem's own
+  # `test/test_helper.rb` performs that require explicitly because the
+  # gem's tests are themselves consumers of the testing surface.
+  #
+  # `test_mode!` swaps the configured subscriber list for a single
+  # {TrackRelay::Subscribers::Test} for the duration of an example so
+  # consumer tests can assert against fired events without sending them
+  # to real adapters. `test_mode_off!` restores the previously captured
+  # list.
+  #
+  # `test_mode!` is idempotent: calling twice without restoring returns
+  # the same Test instance and does NOT clobber the originally-captured
+  # subscriber list. After `test_mode_off!`, calling `test_mode!` again
+  # creates a fresh Test subscriber so per-test buffers stay isolated.
+  module Testing
+    module_function
+
+    # Replace `TrackRelay.config.subscribers` with a single
+    # {Subscribers::Test} and snapshot the previous list. Idempotent.
+    #
+    # @return [Subscribers::Test] the active test subscriber
+    def test_mode!
+      return @test_subscriber if active?
+      test_subscriber = Subscribers::Test.new
+      @previous_subscribers = TrackRelay.config.replace_subscribers([test_subscriber])
+      @test_subscriber = test_subscriber
+    end
+
+    # Restore the subscriber list captured by {.test_mode!}. No-op when
+    # not active.
+    #
+    # @return [void]
+    def test_mode_off!
+      return unless active?
+      TrackRelay.config.replace_subscribers(@previous_subscribers)
+      @previous_subscribers = nil
+      @test_subscriber = nil
+    end
+
+    # @return [Boolean] whether {.test_mode!} is currently active
+    def active?
+      !@test_subscriber.nil?
+    end
+
+    # @return [Subscribers::Test, nil] the active test subscriber, or nil
+    def test_subscriber
+      @test_subscriber
+    end
+  end
+
+  class << self
+    # Convenience delegate to {Testing.test_mode!}.
+    #
+    # @return [Subscribers::Test]
+    def test_mode!
+      Testing.test_mode!
+    end
+
+    # Convenience delegate to {Testing.test_mode_off!}.
+    #
+    # @return [void]
+    def test_mode_off!
+      Testing.test_mode_off!
+    end
+
+    # Convenience delegate to {Testing.test_subscriber}.
+    #
+    # @return [Subscribers::Test, nil]
+    def test_subscriber
+      Testing.test_subscriber
+    end
+  end
+end
+
+# Auto-load RSpec matchers when RSpec is on the load path. The
+# matcher file itself is also guarded with `if defined?(RSpec)`, so
+# consumers who require it directly outside an RSpec context are
+# still safe — the file becomes a no-op.
+require "track_relay/testing/rspec_matchers" if defined?(RSpec)

data/lib/track_relay/validators/catalog_validator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "track_relay/errors"
+require "track_relay/validators/ga4_constraints"
+
+module TrackRelay
+  module Validators
+    # Validates an {EventDefinition} at catalog-load time.
+    #
+    # Runs both GA4 constraint checks ({Ga4Constraints}) and the
+    # reserved-key collision guard. Failures raise immediately so the
+    # offending catalog file fails to load — much louder than a silent
+    # collision at track time.
+    #
+    # Two distinct error types are raised by design:
+    # - {ReservedKeyError} for params that collide with the runtime
+    #   context keys ({TrackRelay::RESERVED_KEYS}).
+    # - {Ga4ConstraintError} for any GA4 rule violation.
+    #
+    # This module is invoked by `EventBuilder#event` (DSL) before
+    # registering the definition with the catalog. It is also safe to call
+    # against externally-built definitions (e.g. tests).
+    module CatalogValidator
+      module_function
+
+      # Run all catalog-load-time checks against a definition.
+      #
+      # @param definition [TrackRelay::EventDefinition]
+      # @raise [TrackRelay::ReservedKeyError] when a param key collides
+      #   with a reserved context key
+      # @raise [TrackRelay::Ga4ConstraintError] when any GA4 rule fails
+      # @return [void]
+      def validate!(definition)
+        Ga4Constraints.validate_event_name!(definition.name)
+        Ga4Constraints.validate_param_count!(definition.params)
+
+        definition.params.each_key do |param_name|
+          if TrackRelay::RESERVED_KEYS.include?(param_name)
+            raise ReservedKeyError,
+              "Param #{param_name.inspect} on event #{definition.name.inspect} collides with a reserved context key — rename to e.g. :actor_user_id, :session_token, :tracking_client_id, or :http_request"
+          end
+
+          Ga4Constraints.validate_param_name!(param_name)
+        end
+      end
+    end
+  end
+end

data/lib/track_relay/validators/ga4_constraints.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "track_relay/errors"
+
+module TrackRelay
+  module Validators
+    # Enforces Google Analytics 4 naming + sizing constraints on catalog
+    # entries. Used by {CatalogValidator} at catalog-load time so
+    # GA4-incompatible events fail fast in development rather than silently
+    # in production where GA4 would just drop them.
+    #
+    # Rules implemented (per GA4 docs):
+    # - Event names: snake_case, start with a lowercase letter, max 40
+    #   chars, not in {TrackRelay::GA4_RESERVED_NAMES}.
+    # - Param names: same regex + max 40 chars.
+    # - Per-event param count: <= 25 custom params.
+    #
+    # All violations raise {TrackRelay::Ga4ConstraintError} with a message
+    # naming the offender so error messages stay actionable.
+    module Ga4Constraints
+      # GA4 names must start with a lowercase letter and contain only
+      # lowercase letters, digits, and underscores after that.
+      NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
+
+      # GA4 caps custom event/param name length at 40 characters.
+      MAX_NAME_LENGTH = 40
+
+      # GA4 caps custom params per event at 25.
+      MAX_PARAMS_PER_EVENT = 25
+
+      module_function
+
+      # @param name [Symbol, String] event name to validate
+      # @raise [TrackRelay::Ga4ConstraintError] when the name violates any
+      #   GA4 rule (shape, length, or reserved-name list)
+      # @return [void]
+      def validate_event_name!(name)
+        as_string = name.to_s
+
+        unless as_string.match?(NAME_PATTERN)
+          raise Ga4ConstraintError,
+            "Event name #{name.inspect} must be snake_case (matches #{NAME_PATTERN.inspect})"
+        end
+
+        if as_string.length > MAX_NAME_LENGTH
+          raise Ga4ConstraintError,
+            "Event name #{name.inspect} exceeds GA4 max length of #{MAX_NAME_LENGTH} chars (got #{as_string.length})"
+        end
+
+        if TrackRelay::GA4_RESERVED_NAMES.include?(as_string)
+          raise Ga4ConstraintError,
+            "Event name #{name.inspect} is reserved by GA4 (https://support.google.com/analytics/answer/9234069) — pick a non-reserved name"
+        end
+      end
+
+      # @param params [Hash] params hash from an EventDefinition
+      # @raise [TrackRelay::Ga4ConstraintError] when params.size > 25
+      # @return [void]
+      def validate_param_count!(params)
+        if params.size > MAX_PARAMS_PER_EVENT
+          raise Ga4ConstraintError,
+            "Event has #{params.size} custom params; GA4 caps custom params per event at #{MAX_PARAMS_PER_EVENT}"
+        end
+      end
+
+      # @param name [Symbol, String] param name to validate
+      # @raise [TrackRelay::Ga4ConstraintError] when the param name
+      #   violates GA4 shape or length rules
+      # @return [void]
+      def validate_param_name!(name)
+        as_string = name.to_s
+
+        unless as_string.match?(NAME_PATTERN)
+          raise Ga4ConstraintError,
+            "Param name #{name.inspect} must be snake_case (matches #{NAME_PATTERN.inspect})"
+        end
+
+        if as_string.length > MAX_NAME_LENGTH
+          raise Ga4ConstraintError,
+            "Param name #{name.inspect} exceeds GA4 max length of #{MAX_NAME_LENGTH} chars (got #{as_string.length})"
+        end
+      end
+    end
+  end
+end

data/lib/track_relay/version.rb

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

data/lib/track_relay.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "track_relay/version"
+require "track_relay/errors"
+require "track_relay/event_definition"
+require "track_relay/validators/ga4_constraints"
+require "track_relay/validators/catalog_validator"
+require "track_relay/catalog"
+require "track_relay/dsl/param_builder"
+require "track_relay/dsl/event_builder"
+require "track_relay/current"
+require "track_relay/client_id/ga"
+require "track_relay/client_id/ahoy_visitor"
+require "track_relay/client_id/session"
+require "track_relay/configuration"
+require "track_relay/instrumenter"
+require "track_relay/subscribers/base"
+require "track_relay/subscribers/test"
+require "track_relay/subscribers/logger"
+require "track_relay/subscribers/ga4_measurement_protocol"
+require "track_relay/subscribers/ahoy"
+require "track_relay/delivery_job"
+require "track_relay/dispatcher"
+require "track_relay/controller_tracking"
+require "track_relay/job_tracking"
+require "track_relay/linter"
+
+# The Railtie is the only Rails-coupled file pulled in at load time.
+# Load it conditionally so the gem still works in non-Rails contexts
+# (plain `require "track_relay"` from a script). Everything above this
+# line depends on activesupport but not the full Rails stack.
+require "track_relay/railtie" if defined?(Rails::Railtie)
+
+module TrackRelay
+  # Param keys that cannot appear in a catalog event because they collide
+  # with the runtime context that track_relay injects automatically
+  # (TrackRelay::Current + reserved-key extraction in `track`).
+  #
+  # If a catalog event declares any of these as params, the catalog
+  # validator raises {ReservedKeyError} at load time so the conflict
+  # surfaces during boot rather than at track time.
+  RESERVED_KEYS = %i[user visitor_token client_id request].freeze
+
+  # Event names Google Analytics 4 reserves for its own use. Custom events
+  # in the catalog must not use any of these names — GA4 silently drops
+  # them on ingestion. Source:
+  # https://support.google.com/analytics/answer/9234069
+  #
+  # Kept here as a frozen Array of Strings so {GA4_RESERVED_NAMES.include?}
+  # works against both String and Symbol input via to_s coercion in the
+  # validator.
+  GA4_RESERVED_NAMES = %w[
+    ad_click
+    ad_exposure
+    ad_query
+    ad_reward
+    adunit_exposure
+    app_clear_data
+    app_exception
+    app_install
+    app_remove
+    app_store_refund
+    app_store_subscription_cancel
+    app_store_subscription_convert
+    app_store_subscription_renew
+    app_update
+    click
+    error
+    file_download
+    first_open
+    first_visit
+    form_start
+    form_submit
+    in_app_purchase
+    notification_dismiss
+    notification_foreground
+    notification_open
+    notification_receive
+    os_update
+    page_view
+    screen_view
+    scroll
+    session_start
+    session_start_with_rollout
+    session_resume_with_rollout
+    user_engagement
+    video_complete
+    video_progress
+    video_start
+    view_search_results
+  ].freeze
+
+  class << self
+    # Process-wide {Configuration} singleton. Lazily instantiated on
+    # first access. Reset between tests via {reset_config!}.
+    #
+    # @return [Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yield the {Configuration} singleton for host-app setup, then
+    # return it so callers can chain.
+    #
+    #   TrackRelay.configure do |c|
+    #     c.subscribe(MySubscriber.new)
+    #     c.untyped_events_allowed = false
+    #   end
+    #
+    # @yieldparam config [Configuration]
+    # @return [Configuration]
+    def configure
+      yield(config)
+      config
+    end
+
+    # Replace the singleton with a fresh {Configuration}. Used by the
+    # test suite's teardown hook so per-test mutations do not leak.
+    #
+    # @return [Configuration] the new (default) configuration
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+
+  # Track an event — typed (catalog-defined) or untyped.
+  #
+  # Reserved keys (`:user`, `:request`, `:client_id`, `:visitor_token`)
+  # are partitioned out of `params` BEFORE catalog lookup so they never
+  # appear in `payload.params`. `:user`/`:request`/`:client_id` are
+  # bound on {Current} for the duration of the call;
+  # `:visitor_token` is merged directly into `payload.context`.
+  #
+  # See {Instrumenter.track} for full semantics.
+  #
+  # @param name [Symbol]
+  # @param params [Hash]
+  # @return [void]
+  def self.track(name, **params)
+    Instrumenter.track(name, **params)
+  end
+
+  # Identify a user — Phase 01 thin pass-through.
+  #
+  # See {Instrumenter.identify}.
+  #
+  # @param user [Object]
+  # @param user_properties [Hash]
+  # @return [void]
+  def self.identify(user, **user_properties)
+    Instrumenter.identify(user, **user_properties)
+  end
+
+  # Register a subscriber with optional per-instance event-name filters.
+  #
+  #   TrackRelay.subscribe(MySubscriber)
+  #   TrackRelay.subscribe(MySubscriber, only: %i[purchase sign_up])
+  #   TrackRelay.subscribe(MySubscriber, except: %i[page_view])
+  #   TrackRelay.subscribe(MySubscriber.new, only: %i[purchase])
+  #
+  # Accepts either a subscriber class (instantiated via `.new`) or a
+  # pre-built instance. When `only:` or `except:` is non-nil, the value
+  # is coerced to `Set<Symbol>` and stored as a SINGLETON-CLASS override
+  # on the registered instance. Other instances of the same class — and
+  # the class-level defaults declared via `filter only:` / `filter
+  # except:` — are NOT mutated.
+  #
+  # The instance is appended to {Configuration#subscribers} via
+  # {Configuration#subscribe} and returned, so callers can hold a
+  # reference (e.g. for tests).
+  #
+  # @param subscriber_or_class [Class, Subscribers::Base]
+  # @param only [Array<Symbol, String>, nil] allow-list override
+  # @param except [Array<Symbol, String>, nil] deny-list override
+  # @return [Subscribers::Base] the registered subscriber instance
+  def self.subscribe(subscriber_or_class, only: nil, except: nil)
+    instance = subscriber_or_class.is_a?(Class) ? subscriber_or_class.new : subscriber_or_class
+    instance.set_filter_overrides!(only: only, except: except)
+    config.subscribe(instance)
+    instance
+  end
+
+  # Top-level entry point for the catalog DSL.
+  #
+  # Evaluates `block` against a {DSL::EventBuilder} so callers can use
+  # `event :name do ... end` and `user_property :name, :type` directly:
+  #
+  #   TrackRelay.catalog do
+  #     event :article_viewed do
+  #       integer :article_id, required: true
+  #     end
+  #
+  #     user_property :plan, :string
+  #   end
+  #
+  # Each `event` declaration validates against GA4 + reserved-key rules
+  # and registers the resulting {EventDefinition} in {Catalog} before
+  # returning. Failures raise {Ga4ConstraintError},
+  # {ReservedKeyError}, or {CatalogError} depending on the violation.
+  def self.catalog(&block)
+    DSL::EventBuilder.new.instance_exec(&block)
+  end
+end