better_auth-telemetry 0.8.0

data/lib/better_auth/telemetry/options.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require_relative "logger_adapter"
+
+module BetterAuth
+  module Telemetry
+    # Value objects that normalize the heterogeneous shapes the
+    # `BetterAuth::Telemetry.create(options, context)` entry point accepts
+    # into the small, well-typed surface the rest of the pipeline depends
+    # on.
+    #
+    # Two normalizers ship together:
+    #
+    # - {NormalizedOptions} wraps the host-supplied `options`. The argument
+    #   may be a {BetterAuth::Configuration}, a raw `Hash`, or `nil`.
+    # - {NormalizedContext} wraps the optional `context` hash that callers
+    #   use to override telemetry-side detection (`custom_track`,
+    #   `database`, `adapter`, `skip_test_check`).
+    #
+    # Both accept either snake_case (`:custom_track`, `:skip_test_check`,
+    # `:database`, `:adapter`) or camelCase (`:customTrack`,
+    # `:skipTestCheck`) keys, in either symbol or string form, so callers
+    # mirroring the upstream TypeScript API do not have to translate keys
+    # by hand.
+    #
+    # Neither value object raises on missing or `nil` input. Missing keys
+    # surface as `nil` readers (or `false` for the boolean-defaulting
+    # `skip_test_check`).
+    module Options
+    end
+
+    # Normalized view of the host `options` argument supplied to
+    # {BetterAuth::Telemetry.create}.
+    #
+    # `NormalizedOptions.from(options)` accepts:
+    #
+    # - a {BetterAuth::Configuration} instance (production path: the value
+    #   `BetterAuth::Auth#initialize` passes in),
+    # - a `Hash` with snake_case or camelCase keys (mirrors the upstream
+    #   `BetterAuthOptions` shape and the common test seam),
+    # - or `nil` (every reader returns `nil` / a default-fallback logger).
+    #
+    # ## Telemetry opt-in precedence
+    #
+    # `telemetry_enabled` and `telemetry_debug` use the upstream
+    # `nil`/`true`/`false` precedence semantics:
+    #
+    # - `nil` means "not configured at the option layer" (the env layer
+    #   may still opt the process in via `BETTER_AUTH_TELEMETRY`).
+    # - `true` is an explicit opt-in (subject to the test-environment skip
+    #   unless `skip_test_check` overrides it).
+    # - `false` is an explicit opt-out that overrides every env opt-in.
+    #
+    # The readers resolve `telemetry[:enabled]` and `telemetry[:debug]`
+    # from either a {BetterAuth::Configuration} or a raw Hash.
+    #
+    # ## Logger
+    #
+    # The {#logger} reader always returns a usable {LoggerAdapter}.
+    # When the host supplies no logger we fall back to
+    # `BetterAuth::Logger.create` via {LoggerAdapter.from} so callers
+    # never have to nil-check.
+    class NormalizedOptions
+      # @return [BetterAuth::Configuration, nil] the raw configuration
+      #   instance when the host passed one, otherwise `nil`. Useful for
+      #   detectors that want to read additional fields without going
+      #   through this value object.
+      attr_reader :configuration
+
+      # @return [String, nil] the resolved `app_name` from the
+      #   configuration or hash, or `nil` when not configured.
+      attr_reader :app_name
+
+      # @return [String, nil] the resolved `base_url` from the
+      #   configuration or hash, or `nil` when not configured.
+      attr_reader :base_url
+
+      # @return [Boolean, nil] explicit option-layer opt-in / opt-out for
+      #   telemetry. `nil` defers to env. See class docs for precedence.
+      attr_reader :telemetry_enabled
+
+      # @return [Boolean, nil] explicit option-layer toggle for debug
+      #   mode. `nil` defers to `BETTER_AUTH_TELEMETRY_DEBUG`.
+      attr_reader :telemetry_debug
+
+      # @return [LoggerAdapter] always-usable logger adapter. Falls back
+      #   to the default {BetterAuth::Logger} when no logger was supplied.
+      attr_reader :logger
+
+      # Build a {NormalizedOptions} from a {BetterAuth::Configuration},
+      # a `Hash`, or `nil`.
+      #
+      # @param options [BetterAuth::Configuration, Hash, nil]
+      # @return [NormalizedOptions]
+      def self.from(options)
+        if options.is_a?(::BetterAuth::Configuration)
+          from_configuration(options)
+        elsif options.is_a?(Hash)
+          from_hash(options)
+        else
+          new(
+            configuration: nil,
+            app_name: nil,
+            base_url: nil,
+            telemetry_enabled: nil,
+            telemetry_debug: nil,
+            raw_logger: nil
+          )
+        end
+      end
+
+      # @api private
+      def self.from_configuration(configuration)
+        telemetry =
+          if configuration.respond_to?(:telemetry) && configuration.telemetry.is_a?(Hash)
+            configuration.telemetry
+          else
+            {}
+          end
+        new(
+          configuration: configuration,
+          app_name: configuration.app_name,
+          base_url: configuration.base_url,
+          telemetry_enabled: Options.fetch_key(telemetry, :enabled, :enabled),
+          telemetry_debug: Options.fetch_key(telemetry, :debug, :debug),
+          raw_logger: configuration.logger
+        )
+      end
+
+      # @api private
+      def self.from_hash(hash)
+        telemetry = Options.fetch_key(hash, :telemetry, :telemetry)
+        telemetry = telemetry.is_a?(Hash) ? telemetry : {}
+
+        new(
+          configuration: nil,
+          app_name: Options.fetch_key(hash, :app_name, :appName),
+          base_url: Options.fetch_key(hash, :base_url, :baseURL),
+          telemetry_enabled: Options.fetch_key(telemetry, :enabled, :enabled),
+          telemetry_debug: Options.fetch_key(telemetry, :debug, :debug),
+          raw_logger: Options.fetch_key(hash, :logger, :logger)
+        )
+      end
+
+      # @api private
+      def initialize(configuration:, app_name:, base_url:, telemetry_enabled:, telemetry_debug:, raw_logger:)
+        @configuration = configuration
+        @app_name = app_name
+        @base_url = base_url
+        @telemetry_enabled = telemetry_enabled
+        @telemetry_debug = telemetry_debug
+        @logger = LoggerAdapter.from(raw_logger)
+      end
+    end
+
+    # Normalized view of the optional `context` argument supplied to
+    # {BetterAuth::Telemetry.create}.
+    #
+    # `NormalizedContext.from(context)` accepts:
+    #
+    # - a `Hash` with snake_case or camelCase keys (`:custom_track` /
+    #   `:customTrack`, `:skip_test_check` / `:skipTestCheck`,
+    #   `:database`, `:adapter`),
+    # - or `nil` (every reader returns its default).
+    #
+    # Defaults:
+    #
+    # - {#custom_track} — `nil` when missing.
+    # - {#database} — `nil` when missing.
+    # - {#adapter} — `nil` when missing.
+    # - {#skip_test_check} — `false` when missing or `nil`. Any other
+    #   value is preserved as-is so the decision layer can apply its own
+    #   truthiness check.
+    class NormalizedContext
+      # @return [#call, nil] caller-supplied tracker. When present, every
+      #   event is delivered to `custom_track.call(event)` instead of via
+      #   HTTP. The primary testing seam.
+      attr_reader :custom_track
+
+      # @return [String, nil] override for the database name reported in
+      #   the init event. Bypasses the {Detectors::Database} chain when
+      #   present.
+      attr_reader :database
+
+      # @return [String, nil] adapter class name, populated by
+      #   `BetterAuth::Auth#initialize`. Pass-through into the auth-config
+      #   payload's `adapter` key.
+      attr_reader :adapter
+
+      # @return [Boolean] whether to bypass the
+      #   `RACK_ENV/RAILS_ENV/APP_ENV == "test"` skip. Does NOT
+      #   force-enable telemetry on its own; the opt-in from
+      #   {NormalizedOptions} or env still has to be in place.
+      attr_reader :skip_test_check
+
+      # Build a {NormalizedContext} from a `Hash` or `nil`.
+      #
+      # @param context [Hash, nil]
+      # @return [NormalizedContext]
+      def self.from(context)
+        hash = context.is_a?(Hash) ? context : {}
+        skip = Options.fetch_key(hash, :skip_test_check, :skipTestCheck)
+        new(
+          custom_track: Options.fetch_key(hash, :custom_track, :customTrack),
+          database: Options.fetch_key(hash, :database, :database),
+          adapter: Options.fetch_key(hash, :adapter, :adapter),
+          skip_test_check: skip.nil? ? false : skip
+        )
+      end
+
+      # @api private
+      def initialize(custom_track:, database:, adapter:, skip_test_check:)
+        @custom_track = custom_track
+        @database = database
+        @adapter = adapter
+        @skip_test_check = skip_test_check
+      end
+    end
+
+    module Options
+      # Look up a key in a hash, accepting symbol and string forms of both
+      # the snake_case and camelCase variants. Returns `nil` when nothing
+      # matches; an explicit `nil` value also returns `nil`.
+      #
+      # @param hash [Hash]
+      # @param snake [Symbol] snake_case key (canonical Ruby form).
+      # @param camel [Symbol] camelCase key (upstream form).
+      # @return [Object, nil]
+      def self.fetch_key(hash, snake, camel)
+        return nil unless hash.is_a?(Hash)
+
+        keys = [snake, camel, snake.to_s, camel.to_s].uniq
+        keys.each do |key|
+          return hash[key] if hash.key?(key)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/project_id.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+require "securerandom"
+
+require_relative "version"
+
+module BetterAuth
+  module Telemetry
+    # Thread-local registry that lets {ProjectId.resolve_project_name}
+    # discover the host's `app_name` without changing the public method
+    # signature `BetterAuth::Telemetry.project_id(base_url)` (Requirement
+    # 14.1).
+    #
+    # `BetterAuth::Telemetry.create` sets `app_name` for the duration of
+    # an init flow via {.with_app_name}; outside of that scope the reader
+    # returns `nil` and the project-name resolver falls through to the
+    # next rule in the chain (Bundler.locked_gems → Bundler.root).
+    #
+    # The store is per-thread so concurrent `create` calls in different
+    # threads don't clobber each other.
+    module CurrentOptions
+      KEY = :better_auth_telemetry_current_options_app_name
+
+      module_function
+
+      # @return [String, nil] the app name set by the most recent
+      #   {.with_app_name} block on the current thread, or `nil`.
+      def app_name
+        Thread.current[KEY]
+      end
+
+      # @param value [String, nil]
+      # @return [String, nil] the value just stored.
+      def app_name=(value)
+        Thread.current[KEY] = value
+      end
+
+      # Run `block` with `app_name` set to `value`, restoring the prior
+      # value (typically `nil`) on the way out — even when the block
+      # raises.
+      #
+      # @param value [String, nil]
+      # @yield with the thread-local app name temporarily set.
+      # @return [Object] whatever the block returns.
+      def with_app_name(value)
+        prior = Thread.current[KEY]
+        Thread.current[KEY] = value
+        yield
+      ensure
+        Thread.current[KEY] = prior
+      end
+    end
+
+    # Project-name resolver used by {BetterAuth::Telemetry.project_id}.
+    #
+    # The chain (Requirement 14.7) is:
+    #
+    # 1. {CurrentOptions.app_name} — when set and not the default
+    #    `"Better Auth"`.
+    # 2. The first entry of `Bundler.locked_gems.specs` — the
+    #    Gemfile.lock-pinned name of the current project.
+    # 3. `File.basename(Bundler.root)` — the directory name of the
+    #    Gemfile root, used when the lockfile yields nothing useful.
+    #
+    # Every fallback is wrapped in `rescue StandardError; nil` so that a
+    # missing Bundler load, an unreadable lockfile, or any unrelated
+    # error in one rule degrades to the next rule rather than escaping
+    # to the caller (Requirement 14.8).
+    module ProjectId
+      # Upstream sentinel: the `Better Auth` literal is treated as "not
+      # configured" so the chain falls through to the Bundler signals.
+      DEFAULT_APP_NAME = "Better Auth"
+
+      module_function
+
+      # @return [String, nil] the resolved project name, or `nil` when
+      #   no rule produced a non-empty string.
+      def resolve_project_name
+        from_app_name || from_locked_gems || from_bundler_root
+      rescue
+        nil
+      end
+
+      # Read the host's `app_name` from {CurrentOptions}. Treats the
+      # literal `"Better Auth"` (the upstream default) as "not
+      # configured" so it never wins over the Bundler-derived rules.
+      #
+      # @return [String, nil]
+      def from_app_name
+        name = CurrentOptions.app_name
+        return nil if name.nil?
+        return nil unless name.is_a?(String)
+        return nil if name.empty?
+        return nil if name == DEFAULT_APP_NAME
+
+        name
+      rescue
+        nil
+      end
+
+      # First gemspec in `Bundler.locked_gems.specs`. Mirrors the
+      # upstream `package.json#name` lookup. Returns `nil` when Bundler
+      # is not loaded, no lockfile is locatable, or the spec list is
+      # empty.
+      #
+      # @return [String, nil]
+      def from_locked_gems
+        return nil unless defined?(::Bundler)
+
+        locked = ::Bundler.locked_gems
+        return nil if locked.nil?
+
+        spec = locked.specs&.first
+        return nil if spec.nil?
+
+        name = spec.name
+        return nil if name.nil? || name.empty?
+
+        name
+      rescue
+        nil
+      end
+
+      # Directory name of `Bundler.root`. The closest Ruby analog to
+      # upstream's "directory containing package.json" fallback.
+      #
+      # @return [String, nil]
+      def from_bundler_root
+        return nil unless defined?(::Bundler)
+
+        root = ::Bundler.root
+        return nil if root.nil?
+
+        name = File.basename(root.to_s)
+        return nil if name.nil? || name.empty?
+
+        name
+      rescue
+        nil
+      end
+    end
+
+    @project_id_cache = nil
+    @project_id_mutex = Mutex.new
+
+    # Resolve a stable, anonymous project id for telemetry.
+    #
+    # The id is derived once per process and memoized; subsequent calls
+    # — regardless of the `base_url` they pass — return the cached
+    # value (Requirement 14.6). This mirrors the upstream
+    # `projectIdCached` module-scope variable.
+    #
+    # ## Derivation chain (Requirements 14.2 – 14.5)
+    #
+    # 1. Project name resolvable AND `base_url` non-empty:
+    #    `Base64(SHA-256(base_url + name))`.
+    # 2. Project name resolvable AND `base_url` nil/empty:
+    #    `Base64(SHA-256(name))`.
+    # 3. No project name AND `base_url` non-empty:
+    #    `Base64(SHA-256(base_url))`.
+    # 4. Otherwise: a random 32-character `[a-zA-Z0-9]` id from
+    #    `SecureRandom`, matching upstream `generateId(32)`.
+    #
+    # The Bundler/lockfile probes inside {ProjectId.resolve_project_name}
+    # never raise out of this method (Requirement 14.8); a failed probe
+    # collapses to "no project name" and the chain continues at rule 3
+    # or rule 4.
+    #
+    # @param base_url [String, nil] the host's configured base URL.
+    # @return [String] the memoized anonymous project id.
+    def self.project_id(base_url)
+      cached = @project_id_cache
+      return cached if cached
+
+      @project_id_mutex.synchronize do
+        cached = @project_id_cache
+        return cached if cached
+
+        @project_id_cache = derive_project_id(base_url)
+      end
+    end
+
+    # Test-only hook that clears the memoized project id cache.
+    #
+    # Wired here in task 3.6 to clear the `@project_id_cache` ivar that
+    # backs {.project_id}. Tests use this between cases that exercise
+    # different derivation rules (e.g. with vs. without a project name)
+    # so each call goes through the full chain again.
+    #
+    # @return [nil]
+    def self.reset_project_id!
+      @project_id_mutex.synchronize do
+        @project_id_cache = nil
+      end
+      nil
+    end
+
+    # @api private
+    def self.derive_project_id(base_url)
+      url = base_url.is_a?(String) ? base_url : nil
+      url = nil if url && url.empty?
+
+      name = ProjectId.resolve_project_name
+      name = nil if name.is_a?(String) && name.empty?
+
+      if name && url
+        hash_to_base64(url + name)
+      elsif name
+        hash_to_base64(name)
+      elsif url
+        hash_to_base64(url)
+      else
+        random_id_32
+      end
+    end
+
+    # @api private
+    def self.hash_to_base64(input)
+      Base64.strict_encode64(Digest::SHA256.digest(input.to_s))
+    end
+
+    # @api private
+    PROJECT_ID_ALPHABET = (
+      ("a".."z").to_a + ("A".."Z").to_a + ("0".."9").to_a
+    ).freeze
+
+    # @api private
+    def self.random_id_32
+      Array.new(32) { PROJECT_ID_ALPHABET[SecureRandom.random_number(PROJECT_ID_ALPHABET.length)] }.join
+    end
+  end
+end

data/lib/better_auth/telemetry/publisher.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "project_id"
+
+module BetterAuth
+  module Telemetry
+    # Publisher returned from {BetterAuth::Telemetry.create} when telemetry is
+    # opted-in. The publisher is delivery-agnostic: it does not know whether
+    # the configured `track` callable forwards events over HTTP, hands them to
+    # a host-supplied `custom_track`, or routes them through the debug logger.
+    # All of that branching is built into the `track` lambda once at
+    # `create`-time, and the `Publisher` simply normalizes each event and
+    # forwards it through (Requirements 5.6, 5.7, 6.10, 15.1, 15.2).
+    #
+    # ## Responsibilities
+    #
+    # 1. Short-circuit to `nil` when `enabled` is `false`, so a disabled
+    #    publisher is a noop. `#enabled?` reports the flag verbatim.
+    # 2. Lazily resolve `anonymous_id` on the first `#publish` call by
+    #    delegating to {BetterAuth::Telemetry.project_id} when the publisher
+    #    was constructed without one. The result is cached on the instance,
+    #    so subsequent `#publish` calls reuse the same `anonymousId`.
+    # 3. Normalize each event hash to symbol keys with the upstream wire
+    #    shape (`type`, `payload`, `anonymousId`). Both `:type`/`:payload`
+    #    and `"type"`/`"payload"` input keys are accepted; missing
+    #    `:payload` falls back to `{}`.
+    # 4. Forward the normalized event through `track.call(event)` and
+    #    rescue any `StandardError` raised by the callable, routing the
+    #    failure through `logger.error(...)` and returning `nil`. Errors in
+    #    HTTP delivery, custom_track callbacks, or JSON encoding therefore
+    #    never escape `#publish`.
+    #
+    # The publisher is intentionally stateless beyond the cached
+    # `anonymous_id`: there is no internal queue and no batching. It calls
+    # the supplied `track` lambda synchronously; the HTTP track implementation
+    # may then hand the actual POST to a short-lived background thread.
+    #
+    # @example wiring with a `RecordingTrack` (test seam)
+    #   recorder = BetterAuth::Telemetry::Test::RecordingTrack.new
+    #   publisher = BetterAuth::Telemetry::Publisher.new(
+    #     enabled: true,
+    #     anonymous_id: nil,
+    #     track: recorder,
+    #     base_url: "https://example.com",
+    #     logger: BetterAuth::Telemetry::LoggerAdapter.from(nil)
+    #   )
+    #   publisher.publish(type: "ping", payload: {})
+    #   recorder.last # => { type: :ping, payload: {}, anonymousId: "..." }
+    class Publisher
+      # @param enabled [Boolean] whether the publisher should forward events.
+      #   When `false`, every `#publish` call is a noop returning `nil`.
+      # @param anonymous_id [String, nil] the resolved anonymous project id,
+      #   or `nil` to defer resolution to the first `#publish` call.
+      # @param track [#call] callable that receives the normalized event
+      #   hash. Built once by `BetterAuth::Telemetry.create` and closes over
+      #   the chosen delivery mode (custom_track, debug, or http).
+      # @param base_url [String, nil] the host's base URL, forwarded to
+      #   {BetterAuth::Telemetry.project_id} when lazy-resolving
+      #   `anonymous_id`.
+      # @param logger [#error] log adapter used to surface delivery
+      #   failures (`StandardError`) raised by `track`.
+      def initialize(enabled:, anonymous_id:, track:, base_url:, logger:)
+        @enabled = enabled
+        @anonymous_id = anonymous_id
+        @track = track
+        @base_url = base_url
+        @logger = logger
+      end
+
+      # Forward an event through the configured `track` callable.
+      #
+      # Returns `nil` when the publisher is disabled. Otherwise normalizes
+      # the input event to `{type:, payload:, anonymousId:}` (symbol keys),
+      # lazy-resolves `anonymous_id` on first use, and dispatches via
+      # `track.call(event_to_emit)`. Any `StandardError` raised by `track`
+      # is rescued and logged at error level; the call still returns `nil`.
+      #
+      # The `event` argument may carry either symbol (`:type`, `:payload`)
+      # or string (`"type"`, `"payload"`) keys; missing `:payload` defaults
+      # to `{}`. Output keys are always symbols, matching the upstream wire
+      # format.
+      #
+      # @param event [Hash] the event to publish; accepts symbol or string
+      #   `:type`/`:payload` keys.
+      # @return [nil]
+      def publish(event)
+        return nil unless @enabled
+
+        @anonymous_id ||= BetterAuth::Telemetry.project_id(@base_url)
+
+        event_to_emit = {
+          type: event[:type] || event["type"],
+          payload: event[:payload] || event["payload"] || {},
+          anonymousId: @anonymous_id
+        }
+
+        @track.call(event_to_emit)
+        nil
+      rescue => e
+        @logger.error("[better-auth.telemetry] publish failed: #{e.class}: #{e.message}")
+        nil
+      end
+
+      # @return [Boolean] whether this publisher is opted-in. `false` means
+      #   `#publish` is a noop.
+      def enabled?
+        @enabled
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Telemetry
+    VERSION = "0.8.0"
+  end
+end

data/lib/better_auth/telemetry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Public entry point for the `better_auth-telemetry` gem.
+#
+# Requiring this file pulls in every internal component the telemetry
+# pipeline depends on so callers only need a single
+# `require "better_auth/telemetry"` to access the full public surface:
+#
+# - {BetterAuth::Telemetry.create} — build a publisher tailored to the
+#   host's opt-in state.
+# - {BetterAuth::Telemetry.project_id} /
+#   {BetterAuth::Telemetry.reset_project_id!} — anonymous project id
+#   resolution and the test-only cache reset hook.
+# - {BetterAuth::Telemetry::Publisher} /
+#   {BetterAuth::Telemetry::NoopPublisher} — the two publisher shapes
+#   `create` returns.
+# - {BetterAuth::Telemetry::Detectors} — the seven detector modules
+#   (`Runtime`, `Environment`, `SystemInfo`, `Database`, `Framework`,
+#   `ProjectInfo`, `AuthConfig`).
+# - Supporting value objects and helpers
+#   ({BetterAuth::Telemetry::NormalizedOptions},
+#   {BetterAuth::Telemetry::NormalizedContext},
+#   {BetterAuth::Telemetry::CurrentOptions},
+#   {BetterAuth::Telemetry::Env},
+#   {BetterAuth::Telemetry::HttpClient},
+#   {BetterAuth::Telemetry::LoggerAdapter}).
+#
+# The standard-library requires below are listed once at the entry
+# point so individual internal files can rely on them being loaded.
+# Every internal file additionally requires what it directly depends
+# on, so any single file is independently loadable.
+
+require "better_auth"
+
+require "base64"
+require "digest"
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+require_relative "telemetry/version"
+require_relative "telemetry/noop_publisher"
+require_relative "telemetry/logger_adapter"
+require_relative "telemetry/options"
+require_relative "telemetry/env"
+require_relative "telemetry/http_client"
+require_relative "telemetry/project_id"
+require_relative "telemetry/publisher"
+require_relative "telemetry/create"
+
+require_relative "telemetry/detectors/runtime"
+require_relative "telemetry/detectors/environment"
+require_relative "telemetry/detectors/system_info"
+require_relative "telemetry/detectors/database"
+require_relative "telemetry/detectors/framework"
+require_relative "telemetry/detectors/project_info"
+require_relative "telemetry/detectors/auth_config"
+
+module BetterAuth
+  # Top-level namespace for the `better_auth-telemetry` gem.
+  #
+  # See `BetterAuth::Telemetry.create` for the entry point used by
+  # `BetterAuth::Auth#initialize` and by tests that exercise the
+  # publisher in isolation.
+  module Telemetry
+  end
+end