track_relay 1.0.0

data/lib/track_relay/subscribers/base.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/class/attribute"
+
+module TrackRelay
+  module Subscribers
+    # Base class for all track_relay subscribers.
+    #
+    # Each subscriber receives an {EventPayload} via {#handle}, which
+    # routes to one of two paths:
+    #
+    #   - **sync** — `safe_deliver(payload)` is invoked inline on the
+    #     calling thread. Used when the subclass calls {.synchronous!}
+    #     or when {Configuration#force_synchronous} is `true`.
+    #   - **async** — {DeliveryJob} is enqueued with the subscriber's
+    #     class name and the payload's serialized form. The job calls
+    #     `safe_deliver` on a fresh instance when it eventually runs.
+    #
+    # **Error contract (locked in 01-CONTEXT.md, 01-05-PLAN.md):**
+    # `safe_deliver` returns `nil` on success or the StandardError on
+    # failure — it NEVER re-raises inline. The {Dispatcher} collects
+    # those returns during fan-out and re-raises the first one
+    # afterwards, but only when {Configuration#swallow_subscriber_errors}
+    # is `false`. This guarantees that one bad subscriber never blocks
+    # peers, while still letting dev/test surface failures loudly once
+    # everyone has had their chance.
+    class Base
+      class_attribute :synchronous, default: false
+
+      # Subscriber-side event-name filters (Plan 02-01). Both default to
+      # `nil`, which means "no filter — receive every event" (Phase 1
+      # behavior). When set, they are stored as `Set<Symbol>` by the
+      # {.filter} class DSL and consulted by {#filtered?} at the top of
+      # {#handle}, BEFORE the sync/async branch.
+      #
+      # The class-level value is the default for instances of this
+      # subscriber; {TrackRelay.subscribe} (Plan 02-01) overrides per
+      # instance via the singleton-class accessors so two instances of
+      # the same subscriber can carry different filters without
+      # cross-talk.
+      class_attribute :only_events, default: nil
+      class_attribute :except_events, default: nil
+
+      # Mark this subclass as synchronous. Calls to {#handle} will run
+      # `safe_deliver` inline rather than enqueueing a {DeliveryJob}.
+      #
+      # @return [Boolean] `true`
+      def self.synchronous!
+        self.synchronous = true
+      end
+
+      # Class-level DSL for declaring an event-name filter.
+      #
+      #   class MySubscriber < TrackRelay::Subscribers::Base
+      #     filter only: %i[purchase sign_up]
+      #   end
+      #
+      # `only:` and `except:` are mutually exclusive in spirit but not
+      # enforced as such — if both are set, `only:` wins (an event must
+      # be in the allow-list AND not in the deny-list to pass). Pass
+      # `nil` to clear a previously set filter.
+      #
+      # @param only [Array<Symbol, String>, nil] allow-list; if non-nil,
+      #   only events whose name is in this set are delivered.
+      # @param except [Array<Symbol, String>, nil] deny-list; events in
+      #   this set are dropped.
+      # @return [void]
+      def self.filter(only: nil, except: nil)
+        self.only_events = coerce_event_set(only)
+        self.except_events = coerce_event_set(except)
+      end
+
+      # Coerce a filter input (Array<Symbol|String>, Set, single Symbol,
+      # or nil) into a `Set<Symbol>` or `nil`. Internal helper shared by
+      # the class-level {.filter} DSL and the per-instance override path
+      # ({Base#set_filter_overrides!}, used by {TrackRelay.subscribe}).
+      #
+      # @param value [Array, Set, Symbol, String, nil]
+      # @return [Set<Symbol>, nil]
+      def self.coerce_event_set(value)
+        return nil if value.nil?
+        Set.new(Array(value).map(&:to_sym))
+      end
+
+      # Implement in subclasses to receive an {EventPayload}.
+      #
+      # @param payload [EventPayload]
+      # @raise [NotImplementedError] when not overridden
+      # @return [void]
+      def deliver(payload)
+        raise NotImplementedError, "#{self.class.name} must implement #deliver(payload)"
+      end
+
+      # Route `payload` to the sync or async path.
+      #
+      # **Returns:** `nil` on success, the StandardError on a sync
+      # failure, or `nil` on the async path (the job runs later — its
+      # eventual failure mode is handled inside {DeliveryJob#perform}).
+      #
+      # **Filter gate (Plan 02-01):** if `only_events` / `except_events`
+      # exclude `payload.name`, return `nil` immediately — BEFORE the
+      # sync/async branch and BEFORE `safe_deliver`'s rescue boundary.
+      # A filtered event with a buggy `#deliver` therefore neither runs
+      # nor logs.
+      #
+      # @param payload [EventPayload]
+      # @return [nil, StandardError]
+      def handle(payload)
+        return nil if filtered?(payload.name.to_sym)
+
+        if self.class.synchronous || TrackRelay.config.force_synchronous
+          safe_deliver(payload)
+        else
+          DeliveryJob.perform_later(self.class.name, payload.to_h)
+          nil
+        end
+      end
+
+      # Wrap {#deliver} with the per-subscriber rescue.
+      #
+      # Returns `nil` on success or the StandardError on failure. ALWAYS
+      # logs the failure (via `Rails.logger.error`) when running under
+      # Rails. NEVER re-raises arbitrary `StandardError`s — the
+      # Dispatcher (or {DeliveryJob}) makes the loudness decision based
+      # on {Configuration#swallow_subscriber_errors}.
+      #
+      # **REQ-23 carve-out (Plan 02-04):**
+      # {TrackRelay::DeliveryRetriableError} and
+      # {TrackRelay::DeliveryDiscardableError} are RE-RAISED unconditionally
+      # — even when `swallow_subscriber_errors = true` (the production
+      # default). ActiveJob's `retry_on` / `discard_on` macros only fire
+      # on raised exceptions; without this carve-out the GA4 retry/discard
+      # policy in {DeliveryJob} would be silently broken in production
+      # because `safe_deliver` would catch the exception, return it as a
+      # value, and the job would think delivery succeeded.
+      #
+      # The carve-out is INTENTIONALLY NARROW: arbitrary `StandardError`s
+      # still flow through the existing log-and-return path — REQ-23's
+      # blanket-rescue contract is preserved for everything outside of
+      # the typed retry/discard exception classes.
+      #
+      # @param payload [EventPayload]
+      # @return [nil, StandardError]
+      def safe_deliver(payload)
+        deliver(payload)
+        nil
+      rescue TrackRelay::DeliveryRetriableError, TrackRelay::DeliveryDiscardableError
+        # Carve-out: ActiveJob retry_on/discard_on must see these.
+        # Do NOT log here — the DeliveryJob's retry path will log on
+        # eventual exhaustion, and the discard path is an intentional
+        # drop. Logging on every retry attempt would spam the log with
+        # transient blips that resolve on retry.
+        raise
+      rescue => e
+        log_failure(e)
+        e
+      end
+
+      # Set per-instance `only:` / `except:` filter overrides on this
+      # subscriber. Used by {TrackRelay.subscribe} so a single subscriber
+      # class can be registered multiple times with different filters.
+      #
+      # Each non-nil argument is coerced via {Base.coerce_event_set} and
+      # stored on the instance's singleton class so it does not bleed
+      # across instances or mutate the class-level defaults declared via
+      # {.filter}. Passing `nil` for either argument leaves that override
+      # untouched (the instance falls through to the class default).
+      #
+      # @param only [Array<Symbol, String>, Set, nil]
+      # @param except [Array<Symbol, String>, Set, nil]
+      # @return [self]
+      def set_filter_overrides!(only: nil, except: nil)
+        unless only.nil?
+          singleton_class.instance_variable_set(:@only_events_override, self.class.coerce_event_set(only))
+        end
+        unless except.nil?
+          singleton_class.instance_variable_set(:@except_events_override, self.class.coerce_event_set(except))
+        end
+        self
+      end
+
+      # Read the effective `only:` filter for this instance — the
+      # singleton override (set by {TrackRelay.subscribe}) when present,
+      # otherwise the class-level default declared via {.filter}.
+      #
+      # @return [Set<Symbol>, nil]
+      def only_events
+        if singleton_class.instance_variable_defined?(:@only_events_override)
+          singleton_class.instance_variable_get(:@only_events_override)
+        else
+          self.class.only_events
+        end
+      end
+
+      # Read the effective `except:` filter for this instance — the
+      # singleton override (set by {TrackRelay.subscribe}) when present,
+      # otherwise the class-level default declared via {.filter}.
+      #
+      # @return [Set<Symbol>, nil]
+      def except_events
+        if singleton_class.instance_variable_defined?(:@except_events_override)
+          singleton_class.instance_variable_get(:@except_events_override)
+        else
+          self.class.except_events
+        end
+      end
+
+      private
+
+      # @param event_name [Symbol] coerced from `payload.name`
+      # @return [Boolean] true ⇒ drop this event before delivery
+      def filtered?(event_name)
+        only = only_events
+        except = except_events
+        return false if only.nil? && except.nil?
+        return true if only && !only.include?(event_name)
+        return true if except&.include?(event_name)
+        false
+      end
+
+      def log_failure(e)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error(
+          "[track_relay] subscriber=#{self.class.name} failed: #{e.class}: #{e.message}\n" \
+          "#{Array(e.backtrace).first(5).join("\n")}"
+        )
+      end
+    end
+  end
+end

data/lib/track_relay/subscribers/ga4_measurement_protocol.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "track_relay/errors"
+require "track_relay/subscribers/base"
+require "track_relay/validators/ga4_constraints"
+
+module TrackRelay
+  module Subscribers
+    # GA4 Measurement Protocol server-side subscriber (REQ-08, REQ-11).
+    #
+    # POSTs each event to Google Analytics 4 via the Measurement Protocol
+    # endpoint:
+    #
+    #   POST https://www.google-analytics.com/mp/collect
+    #     ?measurement_id=G-XXXXXXXXXX
+    #     &api_secret=<secret>
+    #   Content-Type: application/json
+    #   Body: { client_id:, user_id:, timestamp_micros:, events: [{name:, params:}] }
+    #
+    # Async by default — `#deliver` runs inside a {DeliveryJob} (loadbalanced
+    # via ActiveJob). Hosts that need inline delivery (e.g. unit-test
+    # determinism, low-traffic ingestion) can call {.synchronous!} per
+    # REQ-11.
+    #
+    # ## Configuration
+    #
+    # Read from {TrackRelay::Configuration} at *delivery time* (NOT at
+    # class-body load time) so credentials lambdas / late-bound configs
+    # work:
+    #
+    #   - `config.ga4_measurement_id` — `G-XXXXXXXXXX`
+    #   - `config.ga4_api_secret`     — per-stream MP secret
+    #   - `config.ga4_use_eu_endpoint` — when `true`, post to
+    #     `https://region1.google-analytics.com/mp/collect`
+    #
+    # When `ga4_measurement_id` or `ga4_api_secret` is `nil`, `#deliver`
+    # emits a single `Rails.logger.warn` and returns without raising —
+    # gem-loaded-but-not-configured apps must not crash.
+    #
+    # ## Error contract
+    #
+    # `#deliver` raises:
+    #
+    #   - {TrackRelay::DeliveryRetriableError} on transient failures
+    #     (HTTP 5xx, `Net::OpenTimeout`, `Net::ReadTimeout`,
+    #     `Errno::ECONNREFUSED`, `SocketError`). Mapped to
+    #     `retry_on` in {DeliveryJob}.
+    #   - {TrackRelay::DeliveryDiscardableError} on permanent failures
+    #     (HTTP 4xx — defensive: GA4 returns 2xx in practice even on
+    #     malformed payloads). Mapped to `discard_on` in {DeliveryJob}.
+    #   - {TrackRelay::Ga4ConstraintError} when call-time payload
+    #     validation fails AND `config.raise_on_validation_error` is
+    #     `true` (dev/test). In production (`raise_on_validation_error
+    #     = false`) the violation is logged via `Rails.logger.warn` and
+    #     the POST is skipped.
+    #
+    # ## Why typed retriable/discardable exceptions?
+    #
+    # ActiveJob's `retry_on`/`discard_on` macros only fire on raised
+    # exceptions, not returned values. {Subscribers::Base#safe_deliver}
+    # normally rescues any `StandardError` and returns it (the REQ-23
+    # blanket-rescue contract), so a 5xx retry would never reach the
+    # job's retry policy. {Subscribers::Base} therefore carves these two
+    # exception classes out of the rescue: it re-raises them so
+    # {DeliveryJob} can map them to `retry_on`/`discard_on`. See
+    # `test/unit/subscribers/base_retry_passthrough_test.rb`.
+    class Ga4MeasurementProtocol < Base
+      # GA4 production endpoint (US/global region).
+      ENDPOINT_URL = "https://www.google-analytics.com/mp/collect"
+
+      # GA4 EU-region endpoint, selected via `config.ga4_use_eu_endpoint = true`.
+      ENDPOINT_URL_EU = "https://region1.google-analytics.com/mp/collect"
+
+      # Net::HTTP open timeout (TCP connect).
+      OPEN_TIMEOUT_SECONDS = 5
+
+      # Net::HTTP read timeout (response wait).
+      READ_TIMEOUT_SECONDS = 10
+
+      # GA4-reserved param-name prefixes. Per Scout §2 / REQ-27, params
+      # starting with these prefixes must not be sent — GA4 silently
+      # drops them.
+      RESERVED_PARAM_PREFIXES = %w[firebase_ ga_ google_].freeze
+
+      # POST `payload` to the GA4 Measurement Protocol endpoint.
+      #
+      # See class docs for the full configuration / error contract.
+      #
+      # @param payload [TrackRelay::EventPayload]
+      # @raise [TrackRelay::DeliveryRetriableError] on 5xx or network blip
+      # @raise [TrackRelay::DeliveryDiscardableError] on 4xx
+      # @raise [TrackRelay::Ga4ConstraintError] on call-time payload
+      #   violation when `raise_on_validation_error` is true
+      # @return [void]
+      def deliver(payload)
+        config = TrackRelay.config
+        measurement_id = config.ga4_measurement_id
+        api_secret = config.ga4_api_secret
+
+        if measurement_id.nil? || api_secret.nil?
+          warn_missing_credentials(measurement_id, api_secret)
+          return
+        end
+
+        return unless validate_ga4_payload!(payload)
+
+        post_to_ga4(payload, measurement_id, api_secret, config.ga4_use_eu_endpoint)
+      end
+
+      private
+
+      # Run call-time payload constraint checks (REQ-27 split). Returns
+      # `true` when delivery should proceed, `false` when a constraint
+      # was violated AND `raise_on_validation_error` is `false` (the
+      # subscriber logs and skips the POST). Raises
+      # {Ga4ConstraintError} when `raise_on_validation_error` is `true`.
+      def validate_ga4_payload!(payload)
+        if payload.params.size > Validators::Ga4Constraints::MAX_PARAMS_PER_EVENT
+          msg = "GA4 payload for #{payload.name.inspect} has #{payload.params.size} params; GA4 max is #{Validators::Ga4Constraints::MAX_PARAMS_PER_EVENT}"
+          return handle_constraint_violation(msg)
+        end
+
+        payload.params.each_key do |key|
+          as_str = key.to_s
+          next unless RESERVED_PARAM_PREFIXES.any? { |prefix| as_str.start_with?(prefix) }
+
+          msg = "Param #{key.inspect} on event #{payload.name.inspect} uses a GA4-reserved prefix (one of #{RESERVED_PARAM_PREFIXES.inspect})"
+          return false unless handle_constraint_violation(msg)
+        end
+
+        true
+      end
+
+      # Honor the {Configuration#raise_on_validation_error} gate.
+      # Returns `false` (skip the POST) when the violation is logged;
+      # raises {Ga4ConstraintError} otherwise. Mirrors the pattern in
+      # {Instrumenter#validate}.
+      def handle_constraint_violation(msg)
+        if TrackRelay.config.raise_on_validation_error
+          raise Ga4ConstraintError, msg
+        end
+
+        Rails.logger&.warn("[track_relay] #{msg}")
+        false
+      end
+
+      def post_to_ga4(payload, measurement_id, api_secret, use_eu)
+        uri = build_endpoint_uri(measurement_id, api_secret, use_eu)
+        body = build_request_body(payload)
+        response = http_post(uri, body)
+        map_response_to_exception!(response)
+      end
+
+      def build_endpoint_uri(measurement_id, api_secret, use_eu)
+        base = use_eu ? ENDPOINT_URL_EU : ENDPOINT_URL
+        uri = URI(base)
+        uri.query = URI.encode_www_form(
+          measurement_id: measurement_id,
+          api_secret: api_secret
+        )
+        uri
+      end
+
+      def build_request_body(payload)
+        body = {
+          client_id: client_id_for(payload),
+          timestamp_micros: timestamp_micros(payload),
+          events: [{
+            name: payload.name.to_s,
+            params: stringify_params(payload.params)
+          }]
+        }
+
+        user_id = payload.context[:user_id] || payload.context["user_id"]
+        body[:user_id] = user_id.to_s if user_id
+
+        JSON.generate(body)
+      end
+
+      # GA4 requires a `client_id` even when `payload.context[:client_id]`
+      # is nil (e.g. server-side events with no `_ga` cookie). Generate a
+      # deterministic-shaped fallback (`<rand>.<unix_ts>`) so the POST
+      # still goes through — the `client_id` is the cohort identifier in
+      # GA4, not a true per-user key.
+      def client_id_for(payload)
+        explicit = payload.context[:client_id] || payload.context["client_id"]
+        return explicit if explicit && !explicit.to_s.empty?
+
+        "#{SecureRandom.random_number(2_147_483_647)}.#{Time.now.to_i}"
+      end
+
+      def timestamp_micros(payload)
+        ts = payload.timestamp || Time.now
+        (ts.to_f * 1_000_000).to_i
+      end
+
+      def stringify_params(params)
+        out = {}
+        params.each { |k, v| out[k.to_s] = v }
+        out
+      end
+
+      def http_post(uri, body)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = OPEN_TIMEOUT_SECONDS
+        http.read_timeout = READ_TIMEOUT_SECONDS
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request.body = body
+
+        http.request(request)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, SocketError => e
+        raise DeliveryRetriableError, "GA4 network error: #{e.class}: #{e.message}"
+      end
+
+      # Map the response code to retry/discard semantics. GA4 returns 2xx
+      # in practice for both successful and malformed payloads (Scout §2
+      # line 211), so 4xx is defensive coverage in case Google ever
+      # changes the contract.
+      def map_response_to_exception!(response)
+        code = response.code.to_i
+        return if code.between?(200, 299)
+
+        message = "GA4 returned HTTP #{code}: #{response.body.to_s[0, 200]}"
+
+        if code.between?(500, 599)
+          raise DeliveryRetriableError, message
+        else
+          raise DeliveryDiscardableError, message
+        end
+      end
+
+      def warn_missing_credentials(measurement_id, api_secret)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+        missing = []
+        missing << "ga4_measurement_id" if measurement_id.nil?
+        missing << "ga4_api_secret" if api_secret.nil?
+        Rails.logger.warn(
+          "[track_relay] Ga4MeasurementProtocol skipping delivery — missing config: #{missing.join(", ")}"
+        )
+      end
+    end
+  end
+end

data/lib/track_relay/subscribers/logger.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+require "track_relay/subscribers/base"
+
+module TrackRelay
+  module Subscribers
+    # Two-output subscriber that surfaces every event in development /
+    # production logs and persists untyped (non-catalog) events to a
+    # JSONL sidecar for the linter (Plan 08) and the end-to-end test
+    # (Plan 09) to consume.
+    #
+    # **Outputs:**
+    #
+    # 1. **Always** writes a human-readable line to `Rails.logger.info`:
+    #    `[track_relay] event=<name> kind=<typed|untyped> params=[...]`
+    #
+    # 2. **Only when** {Configuration#untyped_log_path} is set AND the
+    #    payload is untyped (`payload.definition.nil?`), appends a JSONL
+    #    line to that path. The line shape is locked at:
+    #
+    #    ```json
+    #    {
+    #      "event":      "<event_name>",
+    #      "params":     ["param_a", "param_b"],
+    #      "controller": "ArticlesController",
+    #      "action":     "show",
+    #      "timestamp":  "2026-05-06T12:00:00Z"
+    #    }
+    #    ```
+    #
+    #    **Privacy contract (locked in 01-CONTEXT.md):** param VALUES are
+    #    NEVER written. Only sorted, stringified param NAMES. The
+    #    JSONL is a "what events fired" audit trail, not a payload log.
+    #
+    # The same line shape is read by `TrackRelay::Linter` (Plan 08) and
+    # asserted by the end-to-end test (Plan 09). Keep these three sites
+    # in sync if the shape ever needs to change.
+    class Logger < Base
+      synchronous!
+
+      def deliver(payload)
+        log_human(payload)
+        log_untyped_jsonl(payload) if untyped?(payload) && jsonl_path
+      end
+
+      private
+
+      def log_human(payload)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        marker = untyped?(payload) ? "untyped" : "typed"
+        Rails.logger.info(
+          "[track_relay] event=#{payload.name} kind=#{marker} params=#{payload.params.keys.sort.inspect}"
+        )
+      end
+
+      def log_untyped_jsonl(payload)
+        line = {
+          event: payload.name.to_s,
+          params: payload.params.keys.map(&:to_s).sort,
+          controller: payload.context[:controller],
+          action: payload.context[:action],
+          timestamp: payload.timestamp.iso8601
+        }
+        File.open(jsonl_path, "a") do |f|
+          f.puts(JSON.generate(line))
+        end
+      end
+
+      def untyped?(payload)
+        payload.definition.nil?
+      end
+
+      def jsonl_path
+        TrackRelay.config.untyped_log_path
+      end
+    end
+  end
+end

data/lib/track_relay/subscribers/test.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "track_relay/subscribers/base"
+
+module TrackRelay
+  module Subscribers
+    # In-memory capture subscriber for use in test suites.
+    #
+    # Plan 07 will wire this into `TrackRelay.test_mode!`, which swaps
+    # the configured subscriber list for a single Test instance for the
+    # duration of an example so consumer tests can assert against fired
+    # events without sending them to real adapters.
+    #
+    # Per-instance state — no class-level globals — so multiple
+    # instances do not crosstalk. {#clear!} resets the buffer; {#find}
+    # filters by event name.
+    #
+    # @example
+    #   sub = TrackRelay::Subscribers::Test.new
+    #   sub.handle(payload)
+    #   sub.events       # => [payload]
+    #   sub.find(:foo)   # => [payload] if payload.name == :foo
+    #   sub.clear!
+    class Test < Base
+      synchronous!
+
+      # @return [Array<EventPayload>] captured payloads in insertion order
+      attr_reader :events
+
+      def initialize
+        super
+        @events = []
+      end
+
+      # Append the payload to {#events}. Called inline by {Base#handle}
+      # because {.synchronous!} is set.
+      #
+      # @param payload [EventPayload]
+      # @return [Array<EventPayload>] the events buffer (after append)
+      def deliver(payload)
+        @events << payload
+      end
+
+      # Clear the captured events buffer.
+      #
+      # @return [Array] the empty buffer
+      def clear!
+        @events.clear
+      end
+
+      # Return only the captured payloads whose `name` equals `name`.
+      #
+      # @param name [Symbol]
+      # @return [Array<EventPayload>]
+      def find(name)
+        @events.select { |e| e.name == name }
+      end
+    end
+  end
+end

data/lib/track_relay/testing/helpers.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "track_relay/testing"
+require "track_relay/testing/minitest_assertions"
+
+module TrackRelay
+  module Testing
+    # Minitest mix-in that combines {MinitestAssertions} with auto
+    # setup/teardown for {TrackRelay.test_mode!}.
+    #
+    # Including this module into `ActiveSupport::TestCase` /
+    # `Minitest::Test`:
+    #   1. mixes in `assert_tracked` / `refute_tracked` /
+    #      `track_relay_test`;
+    #   2. registers `setup` / `teardown` blocks that auto-enable
+    #      `TrackRelay.test_mode!` per test, so each example gets a fresh
+    #      Test subscriber.
+    #
+    #   class MyTest < ActiveSupport::TestCase
+    #     include TrackRelay::Testing::Helpers
+    #
+    #     test "fires :foo" do
+    #       MyService.run!
+    #       assert_tracked :foo, user_id: 1
+    #     end
+    #   end
+    #
+    # The `setup` / `teardown` blocks only register when the including
+    # class supports them (i.e. when included into a Minitest test
+    # class). Including the module elsewhere is a no-op for the hooks;
+    # `MinitestAssertions` is still mixed in so consumers can wire
+    # `test_mode!` themselves.
+    module Helpers
+      def self.included(base)
+        base.include(MinitestAssertions)
+
+        if base.respond_to?(:setup) && base.respond_to?(:teardown)
+          base.setup { TrackRelay.test_mode! }
+          base.teardown { TrackRelay.test_mode_off! }
+        end
+      end
+    end
+  end
+end