track_relay 1.0.0

data/lib/track_relay/client_id/ahoy_visitor.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TrackRelay
+  module ClientId
+    # Resolver that returns the current Ahoy visitor token, when the
+    # host application has the [ahoy](https://github.com/ankane/ahoy)
+    # gem installed AND the controller exposes its `ahoy` helper.
+    #
+    # Default position-1 entry in {Configuration#client_id_resolvers}
+    # — between {Ga} (cookie-based) and {Session} (UUID fallback).
+    #
+    # ## Duck-typed integration
+    #
+    # This resolver does NOT `require "ahoy"`. It probes the controller
+    # via `respond_to?(:ahoy, true)` so the gem boots cleanly in apps
+    # without Ahoy. When Ahoy is absent, `#call` returns `nil` and the
+    # next resolver in the chain takes over.
+    #
+    # When Ahoy IS present, `controller.ahoy` returns an `Ahoy::Tracker`
+    # whose `#visitor_token` returns the visitor cookie value (no DB
+    # query). We use that public API only; nothing internal.
+    class AhoyVisitor
+      # @param controller [Object] any controller-like object that may
+      #   or may not include `Ahoy::Trackable`.
+      # @return [String, nil] `ahoy.visitor_token` if available, else
+      #   `nil`.
+      def call(controller:, **)
+        return nil unless controller&.respond_to?(:ahoy, true)
+
+        controller.ahoy&.visitor_token
+      end
+    end
+  end
+end

data/lib/track_relay/client_id/ga.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TrackRelay
+  module ClientId
+    # Resolver that extracts the GA4-shaped `client_id` from the host
+    # app's `_ga` cookie.
+    #
+    # Default position-0 entry in {Configuration#client_id_resolvers}.
+    # Reproduces Phase 01's `_track_relay_client_id_from_cookie` parser
+    # bit-for-bit so existing behavior is preserved when the resolver
+    # chain is enabled.
+    #
+    # ## `_ga` cookie format
+    #
+    # The `_ga` cookie ships with format
+    # `GA1.<version>.<random_int>.<unix_ts>` (four dot-separated
+    # segments). The GA4 Measurement Protocol expects the client_id to
+    # be the last two segments joined with a dot — e.g. cookie
+    # `"GA1.2.860784081.1732738496"` yields client_id
+    # `"860784081.1732738496"`.
+    #
+    # The parser always takes the last two segments (`parts[-2..]`)
+    # rather than the 3rd/4th, so it is robust against:
+    #   - Custom server-side cookie writers that prepend extra segments
+    #   - Future Google rollouts that change the prefix segment count
+    #
+    # Cookies with fewer than four segments are treated as malformed
+    # and yield `nil` (callers should fall through to the next resolver
+    # in the chain).
+    class Ga
+      # @param controller [#request] any object exposing
+      #   `controller.request.cookies["_ga"]`. Typically an
+      #   `ActionController::Base` instance from
+      #   {ControllerTracking#_resolve_client_id}.
+      # @return [String, nil] the parsed GA4 client_id, or `nil` when the
+      #   cookie is missing/empty/malformed.
+      def call(controller:, **)
+        ga_cookie = controller&.request&.cookies&.[]("_ga")
+        return nil if ga_cookie.nil? || ga_cookie.empty?
+
+        parts = ga_cookie.split(".")
+        return nil if parts.size < 4
+
+        "#{parts[-2]}.#{parts[-1]}"
+      end
+    end
+  end
+end

data/lib/track_relay/client_id/session.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module TrackRelay
+  module ClientId
+    # Last-resort resolver that mints a session-stable UUID when no
+    # other resolver in the chain produced a client_id.
+    #
+    # Default position-2 (final) entry in
+    # {Configuration#client_id_resolvers}. Stores the generated UUID at
+    # `session[:track_relay_client_id]` so subsequent requests on the
+    # same Rails session reuse the same value — every visitor gets a
+    # consistent client_id even if they have no `_ga` cookie and no
+    # Ahoy visit record.
+    #
+    # ## Storage
+    #
+    # Uses the host app's standard session store (cookie store, Redis,
+    # ActiveRecord, etc.) — whatever `controller.session` provides.
+    # The value is a plain UUID string; no signing or encryption is
+    # required (it has no security implications).
+    #
+    # ## Sessionless contexts
+    #
+    # API-only controllers without session middleware (and any
+    # controller-less context) have `controller.session == nil`. The
+    # resolver returns `nil` in that case and the chain falls through
+    # to whatever follows — or to `nil` overall, leaving
+    # {Current.client_id} unset (the same outcome as Phase 01).
+    class Session
+      SESSION_KEY = :track_relay_client_id
+
+      # @param controller [#session] any controller-like object with a
+      #   Rails-style session hash.
+      # @return [String, nil] a stable UUID, or `nil` when no session
+      #   is available.
+      def call(controller:, **)
+        session = controller&.session
+        return nil unless session
+
+        session[SESSION_KEY] ||= SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/track_relay/configuration.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module TrackRelay
+  # Process-wide configuration for track_relay.
+  #
+  # Holds every Phase-01 knob: the subscriber list, defaults for
+  # untyped-event handling, and the test-mode synchronous override.
+  # The host application configures it via {TrackRelay.configure}; the
+  # rest of the gem reads it via {TrackRelay.config}.
+  #
+  # @example Host-app initializer
+  #   TrackRelay.configure do |c|
+  #     c.subscribe(MyAnalyticsSubscriber.new)
+  #     c.untyped_events_allowed = false
+  #     c.untyped_log_path = Rails.root.join("log/untyped_events.log")
+  #   end
+  class Configuration
+    # @!attribute [rw] swallow_subscriber_errors
+    #   Whether subscriber exceptions are caught and logged instead of
+    #   re-raised. Defaults to `true` in production, `false` elsewhere.
+    # @!attribute [rw] untyped_log_path
+    #   Optional path for logging untyped (non-catalog) events.
+    #   `nil` disables the untyped log.
+    # @!attribute [rw] untyped_events_allowed
+    #   Whether {TrackRelay.track} accepts events not in the catalog.
+    # @!attribute [rw] force_synchronous
+    #   When `true`, subscribers run inline regardless of their async
+    #   preference. Used by `test_mode!` (Plan 07) and integration tests.
+    # @!attribute [rw] raise_on_validation_error
+    #   Whether catalog/payload validation errors raise (dev/test) or
+    #   are merely logged (prod). Defaults to true in dev/test.
+    # @!attribute [rw] client_id_resolvers
+    #   Ordered chain of `#call(controller:, **)`-callables consulted
+    #   by {ControllerTracking#_resolve_client_id} to populate
+    #   {Current.client_id}. First non-nil result wins. Defaults to
+    #   `[ClientId::Ga.new, ClientId::AhoyVisitor.new,
+    #   ClientId::Session.new]` (Plan 02-02 / REQ-26).
+    # @!attribute [rw] ga4_measurement_id
+    #   GA4 Measurement Protocol `measurement_id` query parameter
+    #   (`G-XXXXXXXXXX`). Read at delivery time so credentials
+    #   lambdas / late-bound configs work. Defaults to `nil`; when
+    #   `nil` at delivery time the GA4 subscriber emits a
+    #   `Rails.logger.warn` and skips the POST without raising.
+    # @!attribute [rw] ga4_api_secret
+    #   GA4 Measurement Protocol `api_secret` query parameter, scoped
+    #   per data stream. Read at delivery time. Defaults to `nil`;
+    #   same warn-and-skip behavior as {#ga4_measurement_id} when
+    #   missing. Treat as a credential — never commit to source.
+    # @!attribute [rw] ga4_use_eu_endpoint
+    #   When `true`, the GA4 subscriber posts to
+    #   `https://region1.google-analytics.com/mp/collect` instead of
+    #   the global endpoint. Defaults to `false`.
+    attr_accessor :swallow_subscriber_errors,
+      :untyped_log_path,
+      :untyped_events_allowed,
+      :force_synchronous,
+      :raise_on_validation_error,
+      :client_id_resolvers,
+      :ga4_measurement_id,
+      :ga4_api_secret,
+      :ga4_use_eu_endpoint
+
+    # @return [Array] registered subscriber instances, in insertion order
+    attr_reader :subscribers
+
+    def initialize
+      reset!
+    end
+
+    # Restore every setting to its environment-aware default and clear
+    # the subscriber list. Used by tests and by {TrackRelay.reset_config!}.
+    #
+    # @return [void]
+    def reset!
+      @subscribers = []
+      @swallow_subscriber_errors = production_env?
+      @untyped_log_path = nil
+      @untyped_events_allowed = true
+      @force_synchronous = false
+      @raise_on_validation_error = development_or_test_env?
+      @client_id_resolvers = default_client_id_resolvers
+      @ga4_measurement_id = nil
+      @ga4_api_secret = nil
+      @ga4_use_eu_endpoint = false
+    end
+
+    # Append a subscriber to the registry.
+    #
+    # @param subscriber [#call, Object] any object conforming to the
+    #   subscriber protocol (Plan 05 defines the contract).
+    # @return [Object] the subscriber, so the call is chainable / usable
+    #   as `sub = config.subscribe(MySubscriber.new)`.
+    def subscribe(subscriber)
+      @subscribers << subscriber
+      subscriber
+    end
+
+    # Atomically replace the subscriber list and return the previous
+    # one. Plan 07's `TrackRelay.test_mode!` uses this to swap in a
+    # capturing subscriber for the duration of a test block and then
+    # restore the original list.
+    #
+    # @param list [Array, nil] new subscribers (`nil` is coerced to `[]`)
+    # @return [Array] the previous subscriber list (caller's snapshot)
+    def replace_subscribers(list)
+      previous = @subscribers
+      @subscribers = Array(list)
+      previous
+    end
+
+    private
+
+    # Build a fresh default resolver chain. Each call returns a new
+    # array with new resolver instances so a mutated chain in one test
+    # cannot leak into another (the {Session} resolver is otherwise
+    # stateless, but the array container itself must be per-config).
+    def default_client_id_resolvers
+      [
+        ClientId::Ga.new,
+        ClientId::AhoyVisitor.new,
+        ClientId::Session.new
+      ]
+    end
+
+    def production_env?
+      current_env == "production"
+    end
+
+    def development_or_test_env?
+      %w[development test].include?(current_env)
+    end
+
+    def current_env
+      if defined?(Rails) && Rails.respond_to?(:env)
+        Rails.env.to_s
+      else
+        ENV.fetch("RACK_ENV", "development")
+      end
+    end
+  end
+end

data/lib/track_relay/controller_tracking.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "track_relay/current"
+
+module TrackRelay
+  # Controller-side tracking helper.
+  #
+  # Host applications include this concern in `ApplicationController` (or
+  # any controller) to get:
+  #
+  #   - A `before_action` that populates {Current.controller},
+  #     {Current.request}, and {Current.client_id} (the latter derived
+  #     from the `_ga` cookie if present) before any action runs. This
+  #     means {TrackRelay.track} called inside an action automatically
+  #     captures the originating controller / request in
+  #     `payload.context`.
+  #
+  #   - An instance method `track(name, **params)` that delegates to
+  #     {TrackRelay.track}. The delegate is sugar — host code can also
+  #     call `TrackRelay.track(...)` directly.
+  #
+  # The concern is NOT auto-included. Host apps include it explicitly,
+  # which keeps the gem opt-in and avoids surprising behavior in
+  # controllers that don't want tracking. The Phase 4 install generator
+  # will wire the include into ApplicationController.
+  #
+  # ## `client_id` resolver chain
+  #
+  # The before_action runs the ordered chain at
+  # {TrackRelay::Configuration#client_id_resolvers} (default
+  # `[ClientId::Ga, ClientId::AhoyVisitor, ClientId::Session]`). The
+  # FIRST resolver to return a non-nil value wins; later resolvers are
+  # not invoked. Each resolver call is wrapped in `rescue StandardError`
+  # so a single misbehaving resolver cannot block client_id resolution
+  # — the chain skips it and continues.
+  #
+  # The default first resolver ({ClientId::Ga}) reproduces Phase 1's
+  # `_ga`-cookie parser bit-for-bit, so existing behavior is preserved.
+  # Hosts can prepend custom resolvers (e.g. a request-header reader
+  # for native-app traffic) via `TrackRelay.config.client_id_resolvers.unshift(...)`.
+  module ControllerTracking
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :_track_relay_set_current
+    end
+
+    # Delegate to {TrackRelay.track}. Sugar for in-controller call sites
+    # so the host doesn't have to spell `TrackRelay.track` explicitly.
+    #
+    # @param name [Symbol]
+    # @param params [Hash]
+    # @return [void]
+    def track(name, **params)
+      TrackRelay.track(name, **params)
+    end
+
+    private
+
+    def _track_relay_set_current
+      TrackRelay::Current.controller = self
+      TrackRelay::Current.request = request
+      TrackRelay::Current.client_id = _resolve_client_id
+    end
+
+    # Run the resolver chain in order; return the first non-nil result.
+    # Each resolver's `#call` is wrapped in `rescue StandardError` so a
+    # broken resolver cannot poison the chain — it simply yields nil and
+    # the iteration continues to the next resolver.
+    #
+    # @return [String, nil]
+    def _resolve_client_id
+      TrackRelay.config.client_id_resolvers.each do |resolver|
+        result = begin
+          resolver.call(controller: self)
+        rescue => e
+          Rails.logger&.warn(
+            "[track_relay] client_id resolver #{resolver.class} raised " \
+            "#{e.class}: #{e.message} — skipping"
+          )
+          nil
+        end
+
+        return result unless result.nil?
+      end
+      nil
+    end
+  end
+end

data/lib/track_relay/current.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/current_attributes"
+
+module TrackRelay
+  # Per-request / per-job ambient context for track_relay.
+  #
+  # Subclasses {ActiveSupport::CurrentAttributes} so the host application
+  # (or this gem's controller/job middleware) can stash request-scoped
+  # values that {TrackRelay.track} reads back at event time without
+  # threading them through every call site.
+  #
+  # All attributes are auto-reset between requests, jobs, and (in the
+  # test suite) between tests via
+  # `ActiveSupport::CurrentAttributes::TestHelper`, which is mixed into
+  # `ActiveSupport::TestCase` in `test/test_helper.rb`.
+  #
+  # @example Setting context in a controller before-filter
+  #   before_action do
+  #     TrackRelay::Current.user = current_user
+  #     TrackRelay::Current.request = request
+  #     TrackRelay::Current.controller = self
+  #   end
+  #
+  # @example Block-scoped override (e.g. impersonation, replay)
+  #   TrackRelay::Current.set(user: other_user) do
+  #     TrackRelay.track(:article_viewed, article_id: 42)
+  #   end
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :user, :request, :visit, :controller, :client_id
+  end
+end

data/lib/track_relay/delivery_job.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module TrackRelay
+  # ActiveJob-backed async delivery for non-synchronous subscribers.
+  #
+  # The job receives `[subscriber_class_name, payload_hash]` (because
+  # ActiveJob arguments must be GlobalID-serializable, not raw
+  # subscriber instances or {EventPayload} objects). On `perform` it
+  # reconstructs the {EventPayload} via {EventPayload.from_h} and
+  # dispatches to a fresh subscriber instance.
+  #
+  # **Async loudness mirrors the sync {Dispatcher} contract:** when
+  # `safe_deliver` returns a StandardError AND
+  # {Configuration#swallow_subscriber_errors} is `false`, the job
+  # re-raises after `safe_deliver` has already logged. This lets
+  # ActiveJob's normal error path (retry / discard / failed-job queue)
+  # surface the failure. Under the `:test` adapter this propagates
+  # synchronously through `perform_now`/`perform_later`.
+  #
+  # The job receives a serialized hash, **not** {Current} state —
+  # ActiveJob's Executor clears CurrentAttributes before `perform`, so
+  # any context the subscriber needs must already be on
+  # `payload.context` (snapshotted at track time by the Instrumenter).
+  #
+  # ## GA4 retry / discard policy (Plan 02-04)
+  #
+  # `retry_on TrackRelay::DeliveryRetriableError` covers transient GA4
+  # failures (HTTP 5xx, network timeouts, ECONNREFUSED, SocketError).
+  # The wait algorithm `:polynomially_longer` produces ~3s, ~18s, ~83s,
+  # ~258s with 15% default jitter — appropriate for GA4 since the
+  # Measurement Protocol has no strict ordering requirement, sends are
+  # idempotent enough for analytics, and GA4's 72-hour event-backdating
+  # window means late retries still arrive correctly.
+  #
+  # `discard_on TrackRelay::DeliveryDiscardableError` covers HTTP 4xx
+  # (defensive — Scout §2 confirms GA4 returns 2xx in practice even on
+  # malformed payloads, but mapping 4xx to discard is correct in case
+  # Google ever changes that contract).
+  #
+  # ### Why `DEFAULT_GA4_DELIVERY_ATTEMPTS` is a class-local constant
+  #
+  # `retry_on` runs at class-body load time, **before** any
+  # `TrackRelay.configure` block in a host's initializer has had a
+  # chance to mutate {TrackRelay.config}. Reading `TrackRelay.config.
+  # ga4_delivery_attempts` here would either crash (singleton not yet
+  # built) or capture a stale default that the host's initializer is
+  # about to overwrite. Pinning the value to a class-local constant
+  # sidesteps the load-order hazard entirely. A future minor (Phase 4)
+  # can introduce runtime configurability via `self.inherited` /
+  # `after_initialize` machinery without breaking this contract.
+  class DeliveryJob < ActiveJob::Base
+    queue_as :track_relay
+
+    # GA4 retry attempt cap (Plan 02-04). Class-local constant — see
+    # the rationale in the class docstring above. Future Phase 4 work
+    # may introduce `config.ga4_delivery_attempts` once a safe
+    # late-binding path exists; until then, `5` is the contract.
+    DEFAULT_GA4_DELIVERY_ATTEMPTS = 5
+
+    retry_on TrackRelay::DeliveryRetriableError,
+      wait: :polynomially_longer,
+      attempts: DEFAULT_GA4_DELIVERY_ATTEMPTS
+
+    discard_on TrackRelay::DeliveryDiscardableError
+
+    # @param subscriber_class_name [String] fully-qualified subscriber
+    #   class name (e.g. `"TrackRelay::Subscribers::Logger"`)
+    # @param payload_hash [Hash] result of {EventPayload#to_h}, possibly
+    #   round-tripped through JSON (string keys)
+    # @return [void]
+    def perform(subscriber_class_name, payload_hash)
+      subscriber = subscriber_class_name.constantize.new
+      payload = EventPayload.from_h(payload_hash)
+      result = subscriber.safe_deliver(payload)
+
+      # `safe_deliver` already logged via Rails.logger.error. If the
+      # host opts out of swallowing, re-raise so ActiveJob's normal
+      # error path surfaces the failure.
+      raise result if result.is_a?(StandardError) && !TrackRelay.config.swallow_subscriber_errors
+    end
+  end
+end

data/lib/track_relay/dispatcher.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module TrackRelay
+  # Single ActiveSupport::Notifications subscription that fans
+  # `track_relay.event` notifications out to every subscriber in
+  # {Configuration#subscribers}.
+  #
+  # **Error contract — collect-then-reraise (locked in 01-CONTEXT.md):**
+  #
+  # 1. Iterate every configured subscriber, calling `handle(payload)`.
+  # 2. {Subscribers::Base#handle} returns `nil` on success or the
+  #    StandardError on a sync failure (it never re-raises inline). For
+  #    non-Base subscribers that ignore the contract and raise inline,
+  #    a defensive rescue here preserves the "peers still run"
+  #    invariant — exceptions from those rogues are also collected.
+  # 3. AFTER fan-out completes, if
+  #    {Configuration#swallow_subscriber_errors} is `false` AND any
+  #    exception was collected, re-raise the **first** one. This is
+  #    the locked dev/test loudness rule: surface failures, but only
+  #    after every peer has had its chance to receive the event.
+  #
+  # **Lifecycle:** {.start!} registers a single subscription block;
+  # {.stop!} unsubscribes. Both are idempotent so the Plan 06 Railtie
+  # can call `start!` once at boot without worrying about
+  # double-subscription. {.started?} reports the current state.
+  #
+  # `lib/track_relay.rb` requires this file but does NOT call `start!`
+  # — only the Railtie does, so non-Rails environments can opt in.
+  module Dispatcher
+    NOTIFICATION = "track_relay.event"
+
+    class << self
+      # Register the AS::Notifications subscription. Idempotent: calling
+      # twice does not double-subscribe.
+      #
+      # @param notifier [#subscribe] defaults to ActiveSupport::Notifications
+      # @return [Object] the subscription handle (opaque AS object)
+      def start!(notifier = ActiveSupport::Notifications)
+        return @subscription if @subscription
+        @subscription = notifier.subscribe(NOTIFICATION) do |*, payload|
+          dispatch(payload[:event])
+        end
+      end
+
+      # Unsubscribe the AS::Notifications subscription. Idempotent — safe
+      # to call when no subscription has been registered.
+      #
+      # @param notifier [#unsubscribe] defaults to ActiveSupport::Notifications
+      # @return [void]
+      def stop!(notifier = ActiveSupport::Notifications)
+        return unless @subscription
+        notifier.unsubscribe(@subscription)
+        @subscription = nil
+      end
+
+      # @return [Boolean] whether a subscription is currently registered
+      def started?
+        !@subscription.nil?
+      end
+
+      private
+
+      def dispatch(payload)
+        errors = []
+        TrackRelay.config.subscribers.each do |subscriber|
+          # Subscribers::Base#handle returns nil on success or the
+          # StandardError on failure (it never re-raises inline). For
+          # non-Base subscribers that ignore that contract, the inline
+          # rescue below preserves the "peers still run" invariant.
+          result =
+            begin
+              subscriber.handle(payload)
+            rescue => e
+              if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+                Rails.logger.error(
+                  "[track_relay] non-Base subscriber #{subscriber.class} raised inline: #{e.class}: #{e.message}"
+                )
+              end
+              e
+            end
+          errors << result if result.is_a?(StandardError)
+        end
+
+        return if errors.empty?
+        return if TrackRelay.config.swallow_subscriber_errors
+        raise errors.first
+      end
+    end
+  end
+end

data/lib/track_relay/dsl/event_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "track_relay/event_definition"
+require "track_relay/dsl/param_builder"
+require "track_relay/validators/catalog_validator"
+
+module TrackRelay
+  module DSL
+    # The DSL receiver for the body of `TrackRelay.catalog do ... end`.
+    #
+    # Provides two top-level methods:
+    # - `event(name, &block)` — defines an event. The block is
+    #   instance_exec'd against a {ParamBuilder} so type DSL methods
+    #   (integer, string, float, boolean, datetime) work without any
+    #   explicit receiver.
+    # - `user_property(name, type)` — declares a catalog-wide user
+    #   property (registered globally on {Catalog}, not attached to a
+    #   single event).
+    #
+    # `event` is the layer where validation runs. After the block
+    # populates a ParamBuilder, EventBuilder builds the
+    # {EventDefinition}, calls {Validators::CatalogValidator.validate!}
+    # to enforce GA4 + reserved-key rules, and registers the result.
+    # That way the *first* time a definition exists, it is already
+    # validated and immutable.
+    class EventBuilder
+      # Define a single event in the catalog.
+      #
+      # @param name [Symbol] event name
+      # @yield no-args block evaluated in a {ParamBuilder} context
+      # @raise [TrackRelay::Ga4ConstraintError] when the event or any
+      #   param violates GA4 rules
+      # @raise [TrackRelay::ReservedKeyError] when any param collides
+      #   with a reserved context key
+      # @raise [TrackRelay::CatalogError] when the event is already
+      #   registered
+      # @return [EventDefinition] the registered, frozen definition
+      def event(name, &block)
+        param_builder = ParamBuilder.new(name)
+        param_builder.instance_exec(&block) if block
+
+        definition = EventDefinition.new(
+          name: name,
+          params: param_builder.params,
+          user_properties: param_builder.user_properties
+        )
+
+        Validators::CatalogValidator.validate!(definition)
+        Catalog.register(definition)
+        definition
+      end
+
+      # Register a catalog-wide user property (independent of any event).
+      #
+      # @param name [Symbol]
+      # @param type [Symbol] one of `:string`, `:integer`, `:float`,
+      #   `:boolean`, `:datetime`
+      # @return [void]
+      def user_property(name, type)
+        Catalog.register_user_property(name, type)
+      end
+    end
+  end
+end