track_relay 1.0.0

data/lib/track_relay/dsl/param_builder.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "track_relay/event_definition"
+
+module TrackRelay
+  module DSL
+    # The DSL receiver for the body of `event :name do ... end`.
+    #
+    # Each type method (`integer`, `string`, `float`, `boolean`,
+    # `datetime`) records a {EventDefinition::ParamSchema} keyed by param
+    # name. `user_property` accumulates user-property declarations
+    # separately so they can be passed through to the resulting
+    # EventDefinition without polluting `params`.
+    #
+    # ParamBuilder does NOT validate or register anything itself — that
+    # is {EventBuilder}'s job. Keeping the builder side-effect-free makes
+    # it trivial to test and lets EventBuilder run validation against the
+    # complete definition (so e.g. param-count overflow is reported with
+    # the full param set).
+    class ParamBuilder
+      attr_reader :params, :user_properties
+
+      # @param event_name [Symbol] the name of the surrounding event;
+      #   stored for diagnostic context only
+      def initialize(event_name)
+        @event_name = event_name
+        @params = {}
+        @user_properties = {}
+      end
+
+      # @param name [Symbol] param name
+      # @param opts [Hash] optional ParamSchema slots (required, max, in,
+      #   format, sanitize)
+      # @return [EventDefinition::ParamSchema]
+      def integer(name, **opts)
+        record_param(name, :integer, opts)
+      end
+
+      def string(name, **opts)
+        record_param(name, :string, opts)
+      end
+
+      def float(name, **opts)
+        record_param(name, :float, opts)
+      end
+
+      def boolean(name, **opts)
+        record_param(name, :boolean, opts)
+      end
+
+      def datetime(name, **opts)
+        record_param(name, :datetime, opts)
+      end
+
+      # Declare a user property on the surrounding event. Accumulated
+      # separately from regular params so EventDefinition can keep them
+      # in `user_properties`.
+      #
+      # @param name [Symbol]
+      # @param type [Symbol] one of the type symbols (`:string`,
+      #   `:integer`, etc.)
+      def user_property(name, type)
+        @user_properties[name] = type
+      end
+
+      private
+
+      def record_param(name, type, opts)
+        schema = EventDefinition::ParamSchema.new(name: name, type: type, **opts)
+        @params[name] = schema
+      end
+    end
+  end
+end

data/lib/track_relay/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module TrackRelay
+  # Base class for every error track_relay raises.
+  #
+  # Consumers can rescue `TrackRelay::Error` to catch any failure originating
+  # from the gem (validation, catalog load-time checks, GA4 constraint
+  # violations, unknown events, etc.) without depending on individual
+  # subclasses.
+  class Error < StandardError; end
+
+  # Raised at catalog-load time when an event declares a param whose name
+  # collides with one of the reserved context keys (see {RESERVED_KEYS}).
+  class ReservedKeyError < Error; end
+
+  # Raised at catalog-load time when an event or param violates a Google
+  # Analytics 4 constraint (reserved event name, illegal characters,
+  # length, or > 25 custom params per event).
+  class Ga4ConstraintError < Error; end
+
+  # Raised at track time when an EventPayload's params do not satisfy the
+  # corresponding EventDefinition (missing required key, failed coercion,
+  # max-length overflow, inclusion-list miss, format mismatch, or undeclared
+  # extra param).
+  class ValidationError < Error; end
+
+  # Raised at catalog-load time on registry-level problems such as
+  # double-registering the same event name.
+  class CatalogError < Error; end
+
+  # Raised when callers attempt to track an event that is not present in
+  # the catalog and untyped events are disabled.
+  class UnknownEventError < Error; end
+
+  # Raised by a subscriber's `#deliver` to signal a *transient* failure
+  # that the {DeliveryJob} should retry via ActiveJob's `retry_on`.
+  # Examples: HTTP 5xx response, `Net::OpenTimeout`, `Errno::ECONNREFUSED`,
+  # `SocketError` against the GA4 Measurement Protocol endpoint.
+  #
+  # Inherits from `StandardError` (not {Error}) so the
+  # {Subscribers::Base#safe_deliver} carve-out can re-raise it without
+  # dragging in unrelated track_relay error semantics — and so consumers
+  # who rescue `TrackRelay::Error` to log validation failures do not
+  # accidentally swallow a retriable network blip.
+  class DeliveryRetriableError < StandardError; end
+
+  # Raised by a subscriber's `#deliver` to signal a *permanent* failure
+  # that the {DeliveryJob} should drop via ActiveJob's `discard_on`
+  # (HTTP 4xx, malformed credentials, etc.). Defensive: GA4 returns 2xx
+  # in practice even on bad payloads, but we map 4xx defensively in case
+  # Google ever changes that contract. Same `StandardError` rationale as
+  # {DeliveryRetriableError}.
+  class DeliveryDiscardableError < StandardError; end
+end

data/lib/track_relay/event_definition.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module TrackRelay
+  # Catalog metadata for a single event.
+  #
+  # An EventDefinition is the immutable description of an event as
+  # declared in `TrackRelay.catalog do ... end`. It holds the event name,
+  # the schema of every declared param (a Hash of {ParamSchema} keyed by
+  # param name), and any user_property declarations.
+  #
+  # EventDefinition is paired with {TrackRelay::EventPayload} at runtime:
+  # the definition is the schema, the payload is the data, and
+  # `payload.validate!` checks the data against the schema.
+  #
+  # Instances are deep-frozen at construction so the catalog cannot be
+  # mutated after load. Re-defining an event requires {Catalog#clear!}.
+  #
+  # @example
+  #   schema = TrackRelay::EventDefinition::ParamSchema.new(
+  #     name: :article_id, type: :integer, required: true
+  #   )
+  #   definition = TrackRelay::EventDefinition.new(
+  #     name: :article_viewed,
+  #     params: {article_id: schema}
+  #   )
+  #   definition.params[:article_id].type  # => :integer
+  class EventDefinition
+    # The schema of a single param within an event definition.
+    #
+    # `name` is the param's Symbol key. `type` is one of `:integer`,
+    # `:string`, `:float`, `:boolean`, `:datetime`. The remaining slots
+    # are optional validator hooks consumed by {EventPayload#validate!}:
+    #
+    # - `required` (Boolean) — when true, missing values raise
+    #   {ValidationError}.
+    # - `max` (Integer) — for strings, max length; for numbers, max
+    #   value. Overflows raise (no silent truncation).
+    # - `in` (Array) — inclusion list; values not in the list raise.
+    # - `format` (Regexp) — applied to coerced strings; mismatches raise.
+    # - `sanitize` (Callable) — applied to the raw value BEFORE coercion
+    #   and validation, so sanitization can preempt max/format checks.
+    #
+    # `Data.define` (Ruby 3.2+) gives us a frozen value object with a
+    # keyword constructor, equality by value, and zero ceremony.
+    ParamSchema = Data.define(
+      :name,
+      :type,
+      :required,
+      :max,
+      :in,
+      :format,
+      :sanitize
+    ) do
+      # Override `initialize` to default the optional slots so callers
+      # only need to pass `name:` and `type:`.
+      def initialize(name:, type:, required: false, max: nil, in: nil, format: nil, sanitize: nil)
+        super
+      end
+    end
+
+    attr_reader :name, :params, :user_properties
+
+    # @param name [Symbol] event name (e.g. `:article_viewed`)
+    # @param params [Hash{Symbol => ParamSchema}] param schemas keyed by name
+    # @param user_properties [Hash{Symbol => Symbol}] user-property names
+    #   mapped to their type (e.g. `{plan: :string}`)
+    def initialize(name:, params: {}, user_properties: {})
+      @name = name
+      @params = params.freeze
+      @user_properties = user_properties.freeze
+      freeze
+    end
+  end
+end

data/lib/track_relay/event_payload.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "time"
+require "track_relay/errors"
+
+module TrackRelay
+  # Runtime data for a single event in flight.
+  #
+  # An EventPayload pairs a {EventDefinition} (the schema) with the raw
+  # values supplied at the call site (`TrackRelay.track(:foo, ...)`),
+  # plus the request-derived context (user, visitor_token, client_id,
+  # etc.) and a timestamp. It is the value passed through the
+  # `track_relay.event` ActiveSupport::Notifications instrumentation.
+  #
+  # Two constructors:
+  # - `EventPayload.new(definition:, params:, ...)` — typed payload;
+  #   {validate!} coerces and enforces the definition's schema.
+  # - `EventPayload.untyped(name:, params:, ...)` — untyped payload (no
+  #   matching definition); {validate!} is a no-op so consumers can
+  #   still ship the raw event for the untyped-events linter (see
+  #   Plan 04).
+  #
+  # `validate!` is destructive: it replaces `@params` with the coerced
+  # hash so subscribers see post-coercion values. Errors raise
+  # {ValidationError} naming the offending key.
+  class EventPayload
+    # Sentinel values that the strict boolean coercion accepts. Anything
+    # else raises {ValidationError}.
+    BOOLEAN_TRUE_VALUES = [true, "true", 1].freeze
+    BOOLEAN_FALSE_VALUES = [false, "false", 0].freeze
+
+    attr_reader :definition, :params, :context, :timestamp
+
+    # @param definition [EventDefinition] schema for typed events
+    # @param params [Hash{Symbol => Object}] raw param values
+    # @param context [Hash] request-derived metadata (user, visitor,
+    #   request, etc.)
+    # @param timestamp [Time] event timestamp; defaults to now
+    def initialize(definition:, params:, context: {}, timestamp: Time.now)
+      @definition = definition
+      @params = params
+      @context = context
+      @timestamp = timestamp
+      @untyped_name = nil
+    end
+
+    # Build an untyped payload — no definition, no schema enforcement.
+    # Used when a host application calls `TrackRelay.track(:unknown, ...)`
+    # while `untyped_events_allowed = true`.
+    #
+    # @param name [Symbol] event name (stored separately because there
+    #   is no definition to read it from)
+    # @param params [Hash]
+    # @param context [Hash]
+    # @param timestamp [Time]
+    # @return [EventPayload]
+    def self.untyped(name:, params:, context: {}, timestamp: Time.now)
+      payload = new(definition: nil, params: params, context: context, timestamp: timestamp)
+      payload.instance_variable_set(:@untyped_name, name)
+      payload
+    end
+
+    # Reconstruct an EventPayload from a serialized {to_h} form. Used
+    # by Plan 05's {DeliveryJob} to rehydrate a payload after ActiveJob
+    # has serialized arguments through the queue adapter.
+    #
+    # The reconstructed payload is always untyped (`definition: nil`):
+    # validation happened at track time on the calling thread, so the
+    # async delivery path doesn't need the schema. ActiveJob's argument
+    # serialization round-trips Symbols as Strings under the standard
+    # adapter, so `String#to_sym` is applied defensively to the name.
+    #
+    # @param hash [Hash] result of {to_h} (Symbol- or String-keyed)
+    # @return [EventPayload]
+    def self.from_h(hash)
+      payload = allocate
+      payload.instance_variable_set(:@definition, nil)
+      payload.instance_variable_set(:@params, hash[:params] || hash["params"] || {})
+      payload.instance_variable_set(:@context, hash[:context] || hash["context"] || {})
+      payload.instance_variable_set(
+        :@timestamp,
+        Time.iso8601(hash[:timestamp] || hash["timestamp"])
+      )
+      payload.instance_variable_set(
+        :@untyped_name,
+        (hash[:name] || hash["name"]).to_sym
+      )
+      payload
+    end
+
+    # @return [Symbol] event name (from definition or untyped store)
+    def name
+      @definition ? @definition.name : @untyped_name
+    end
+
+    # @return [Boolean] whether this payload was built without a
+    #   matching catalog definition
+    def untyped?
+      @definition.nil?
+    end
+
+    # Coerce and validate `@params` against `@definition.params`.
+    # Mutates `@params` to the coerced hash.
+    #
+    # For each schema entry the order of operations is:
+    # 1. Apply `sanitize` callable if present (raw -> sanitized).
+    # 2. Check `required` against post-sanitize value.
+    # 3. Coerce to `type`.
+    # 4. Apply `max` (length for strings, value for numbers).
+    # 5. Apply `in` inclusion list.
+    # 6. Apply `format` regex (strings only).
+    #
+    # After per-key processing, any incoming param not declared in the
+    # schema raises {ValidationError}.
+    #
+    # No-op for untyped payloads.
+    #
+    # @raise [ValidationError]
+    # @return [Hash{Symbol => Object}] coerced params
+    def validate!
+      return @params if untyped?
+
+      coerced = {}
+
+      @definition.params.each do |key, schema|
+        raw_value = @params[key]
+        raw_value = schema.sanitize.call(raw_value) if schema.sanitize&.respond_to?(:call) && @params.key?(key)
+
+        if raw_value.nil?
+          if schema.required
+            raise ValidationError, "Param #{key.inspect} is required but was not provided"
+          end
+          next
+        end
+
+        coerced_value = coerce(key, schema.type, raw_value)
+        check_max!(key, schema.max, coerced_value) if schema.max
+        check_in!(key, schema.in, coerced_value) if schema.in
+        check_format!(key, schema.format, coerced_value) if schema.format
+
+        coerced[key] = coerced_value
+      end
+
+      extras = @params.keys - @definition.params.keys
+      unless extras.empty?
+        raise ValidationError,
+          "Unexpected param(s) #{extras.map(&:inspect).join(", ")} not declared on event #{@definition.name.inspect}"
+      end
+
+      @params = coerced
+    end
+
+    # Serialize to a Hash suitable for ActiveJob arguments / JSON
+    # encoding. Used by the DeliveryJob in Plan 05.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        name: name,
+        params: @params,
+        context: @context,
+        timestamp: @timestamp.respond_to?(:iso8601) ? @timestamp.iso8601 : @timestamp.to_s
+      }
+    end
+
+    private
+
+    def coerce(key, type, value)
+      case type
+      when :integer then coerce_integer(key, value)
+      when :string then coerce_string(value)
+      when :float then coerce_float(key, value)
+      when :boolean then coerce_boolean(key, value)
+      when :datetime then coerce_datetime(key, value)
+      else
+        raise ValidationError, "Param #{key.inspect} has unsupported type #{type.inspect}"
+      end
+    end
+
+    def coerce_integer(key, value)
+      Integer(value)
+    rescue ArgumentError, TypeError
+      raise ValidationError, "Param #{key.inspect} cannot be coerced to Integer (got #{value.inspect})"
+    end
+
+    def coerce_string(value)
+      String(value)
+    end
+
+    def coerce_float(key, value)
+      Float(value)
+    rescue ArgumentError, TypeError
+      raise ValidationError, "Param #{key.inspect} cannot be coerced to Float (got #{value.inspect})"
+    end
+
+    def coerce_boolean(key, value)
+      return true if BOOLEAN_TRUE_VALUES.include?(value)
+      return false if BOOLEAN_FALSE_VALUES.include?(value)
+
+      raise ValidationError,
+        "Param #{key.inspect} cannot be coerced to Boolean — accepted values are true/false/'true'/'false'/1/0 (got #{value.inspect})"
+    end
+
+    def coerce_datetime(key, value)
+      case value
+      when Time, DateTime
+        value
+      when String
+        begin
+          Time.iso8601(value)
+        rescue ArgumentError
+          raise ValidationError, "Param #{key.inspect} is not a valid ISO8601 datetime (got #{value.inspect})"
+        end
+      else
+        raise ValidationError,
+          "Param #{key.inspect} cannot be coerced to datetime — expected Time, DateTime, or ISO8601 String (got #{value.class})"
+      end
+    end
+
+    def check_max!(key, max, value)
+      length_or_value = value.is_a?(String) ? value.length : value
+
+      if length_or_value > max
+        unit = value.is_a?(String) ? "length" : "value"
+        raise ValidationError,
+          "Param #{key.inspect} #{unit} #{length_or_value} exceeds max #{max}"
+      end
+    end
+
+    def check_in!(key, allowed, value)
+      unless allowed.include?(value)
+        raise ValidationError,
+          "Param #{key.inspect} value #{value.inspect} is not in inclusion list #{allowed.inspect}"
+      end
+    end
+
+    def check_format!(key, format, value)
+      unless value.is_a?(String) && value.match?(format)
+        raise ValidationError,
+          "Param #{key.inspect} value #{value.inspect} does not match format #{format.inspect}"
+      end
+    end
+  end
+end

data/lib/track_relay/instrumenter.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require "track_relay/catalog"
+require "track_relay/current"
+require "track_relay/errors"
+require "track_relay/event_payload"
+
+module TrackRelay
+  # Central orchestrator for {TrackRelay.track} and {TrackRelay.identify}.
+  #
+  # `track` is the integration point of:
+  #
+  #   - {RESERVED_KEYS} extraction (split-routed: some keys land on
+  #     {Current}, `:visitor_token` lands directly in `payload.context`)
+  #   - {Catalog} lookup (typed vs untyped path)
+  #   - {EventPayload} construction + {EventPayload#validate!}
+  #   - context snapshot (read at `track` time so async delivery in
+  #     Plan 05 has the data after `Current` is reset)
+  #   - `ActiveSupport::Notifications.instrument("track_relay.event", ...)`
+  #
+  # All four steps happen on the calling thread before any subscriber
+  # runs, so reserved-key partitioning and validation are deterministic
+  # from the host application's perspective.
+  #
+  # Reserved-key split rationale (per Plan 01-04 must_have):
+  #
+  #   - `:user`, `:request`, `:client_id` are {Current} attributes —
+  #     bound via `Current.set(...) { ... }` for the duration of the
+  #     instrumentation block.
+  #   - `:visitor_token` is intentionally NOT a {Current} attribute.
+  #     {Current} carries `:visit` (an Ahoy-style record), not a raw
+  #     opaque token. The token is merged directly into
+  #     `payload.context[:visitor_token]` so subscribers (and the
+  #     downstream DeliveryJob in Plan 05) can read it without
+  #     touching {Current}.
+  #
+  # `identify` is a thin pass-through in Phase 01: it instruments
+  # `track_relay.identify` with `{user:, properties:}` and performs
+  # no catalog validation against `user_property` declarations.
+  # Adapter-specific user-property handling is deferred to Phase 02.
+  module Instrumenter
+    # AS::Notifications event name for typed/untyped event tracking.
+    NOTIFICATION = "track_relay.event"
+
+    # AS::Notifications event name for identify calls.
+    IDENTIFY_NOTIFICATION = "track_relay.identify"
+
+    # Reserved keys that must be partitioned onto {Current} (block-scoped
+    # via `Current.set`). See {DIRECT_CONTEXT_KEYS} for keys that bypass
+    # {Current} and land directly on `payload.context`.
+    CURRENT_ATTR_KEYS = %i[user request client_id].freeze
+
+    # Reserved keys that bypass {Current} entirely and are merged
+    # directly into `payload.context` at build time.
+    DIRECT_CONTEXT_KEYS = %i[visitor_token].freeze
+
+    module_function
+
+    # Track a typed (catalog-defined) or untyped event.
+    #
+    # Reserved keys are extracted from `params` BEFORE catalog lookup so
+    # they never appear in `payload.params`. Validation gating respects
+    # {Configuration#raise_on_validation_error} (`true` re-raises, `false`
+    # logs and swallows without instrumenting).
+    #
+    # @param name [Symbol] event name; looked up in {Catalog}
+    # @param params [Hash{Symbol => Object}] event params + reserved keys
+    # @return [void]
+    # @raise [UnknownEventError] when the event is not in the catalog
+    #   AND {Configuration#untyped_events_allowed} is false
+    # @raise [ValidationError] when a typed event fails validation AND
+    #   {Configuration#raise_on_validation_error} is true
+    def track(name, **params)
+      current_attrs, direct_context, event_params = partition_reserved(params)
+      with_current_attrs(current_attrs) do
+        definition = Catalog.lookup(name)
+        payload = build_payload(
+          name: name,
+          definition: definition,
+          params: event_params,
+          extra_context: direct_context
+        )
+        return unless validate(payload)
+        ActiveSupport::Notifications.instrument(NOTIFICATION, event: payload)
+      end
+    end
+
+    # Identify a user — Phase 01 pass-through.
+    #
+    # Instruments `track_relay.identify` with `{user:, properties:}`.
+    # No catalog validation happens here; adapter-specific user_property
+    # validation is deferred to Phase 02 where each subscriber decides
+    # how to handle properties (GA4 user_properties, Ahoy User update,
+    # etc.).
+    #
+    # TODO(phase-02): wire `Catalog.user_properties` validation here so
+    # consumers can declare user_property schemas and have them enforced
+    # at identify time.
+    #
+    # @param user [Object] user-like object (or id) to identify
+    # @param user_properties [Hash] arbitrary properties to attach
+    # @return [void]
+    def identify(user, **user_properties)
+      ActiveSupport::Notifications.instrument(
+        IDENTIFY_NOTIFICATION,
+        user: user,
+        properties: user_properties
+      )
+    end
+
+    # Bind `current_attrs` on {Current} for the duration of `block`.
+    #
+    # When the hash is empty, `Current.set(**{})` would raise
+    # `ArgumentError: wrong number of arguments (given 0, expected 1)`
+    # under ActiveSupport 8.x. Skipping the wrapper in that case
+    # preserves the no-reserved-keys path (most calls).
+    #
+    # @param current_attrs [Hash]
+    # @yield with `Current` bound
+    # @return [Object] the block's return value
+    def with_current_attrs(current_attrs, &block)
+      if current_attrs.empty?
+        block.call
+      else
+        Current.set(**current_attrs, &block)
+      end
+    end
+
+    # Split params into three buckets:
+    #
+    #   - `current_attrs` — keys that {Current.set} accepts
+    #     (`:user`, `:request`, `:client_id`)
+    #   - `direct_context` — keys that bypass {Current} and land
+    #     directly on `payload.context` (`:visitor_token`)
+    #   - `event_params` — everything else (validated against catalog)
+    #
+    # @param params [Hash]
+    # @return [Array(Hash, Hash, Hash)] three-tuple of partitioned hashes
+    def partition_reserved(params)
+      current_attrs = {}
+      direct_context = {}
+      event_params = {}
+
+      params.each do |key, value|
+        if CURRENT_ATTR_KEYS.include?(key)
+          current_attrs[key] = value
+        elsif DIRECT_CONTEXT_KEYS.include?(key)
+          direct_context[key] = value
+        else
+          event_params[key] = value
+        end
+      end
+
+      [current_attrs, direct_context, event_params]
+    end
+
+    # Build either a typed or untyped {EventPayload}, merging
+    # `extra_context` (e.g. `:visitor_token`) into the snapshot of
+    # {Current} taken at instrument time.
+    #
+    # Untyped path is gated by
+    # {Configuration#untyped_events_allowed} — when disallowed,
+    # {UnknownEventError} is raised.
+    #
+    # @param name [Symbol]
+    # @param definition [EventDefinition, nil]
+    # @param params [Hash]
+    # @param extra_context [Hash] reserved keys that go straight to
+    #   context (currently just `:visitor_token`)
+    # @return [EventPayload]
+    # @raise [UnknownEventError]
+    def build_payload(name:, definition:, params:, extra_context: {})
+      context = current_context.merge(extra_context)
+
+      if definition
+        EventPayload.new(definition: definition, params: params, context: context)
+      elsif TrackRelay.config.untyped_events_allowed
+        EventPayload.untyped(name: name, params: params, context: context)
+      else
+        raise UnknownEventError,
+          "Unknown event #{name.inspect}; declare it in your catalog or set config.untyped_events_allowed = true"
+      end
+    end
+
+    # Snapshot {Current} at instrument time. Plan 05's DeliveryJob
+    # depends on this contract: by the time the job runs, the Rails
+    # Executor has already cleared {Current}, so async subscribers
+    # must read from `payload.context`, not from `Current` directly.
+    #
+    # Keys snapshot:
+    #
+    #   - `:user`        — Current.user (any object)
+    #   - `:controller`  — Current.controller&.class&.name (String)
+    #   - `:action`      — Current.controller&.action_name (String)
+    #   - `:client_id`   — Current.client_id (String)
+    #   - `:visit`       — Current.visit (Ahoy-style record or nil)
+    #   - `:request_id`  — Current.request&.request_id (String)
+    #
+    # `:controller` and `:action` are required by Plan 05's Logger
+    # JSONL shape.
+    #
+    # @return [Hash]
+    def current_context
+      controller = Current.controller
+      action = controller.respond_to?(:action_name) ? controller.action_name : nil
+
+      {
+        user: Current.user,
+        controller: controller&.class&.name,
+        action: action,
+        client_id: Current.client_id,
+        visit: Current.visit,
+        request_id: Current.request&.request_id
+      }
+    end
+
+    # Run {EventPayload#validate!} and apply the
+    # {Configuration#raise_on_validation_error} gate.
+    #
+    # Returns truthy when the caller should proceed to instrument and
+    # `nil` when validation failed and was swallowed (no instrument).
+    #
+    # @param payload [EventPayload]
+    # @return [Object, nil] truthy on success, `nil` on swallowed failure
+    # @raise [ValidationError] when validation fails AND
+    #   {Configuration#raise_on_validation_error} is true
+    def validate(payload)
+      payload.validate!
+      payload
+    rescue ValidationError => e
+      raise if TrackRelay.config.raise_on_validation_error
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error("[track_relay] validation failed for #{payload.name.inspect}: #{e.message}")
+      end
+
+      nil
+    end
+  end
+end