better_auth-telemetry 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f696d840e8f9fb96751e211c5ad327bf255c3460b99c7adfccab3cbb9c10a1d
+  data.tar.gz: 3b513054876f4c07d8ecfd2bca1705a94b3406226c3270815b084fa5450429fe
+SHA512:
+  metadata.gz: b17c3cebcaae59c8a9cc0d4b936ec2f793fa4004cadf6599aacdaa806b407e6fcd1631036d0039c1746f4dcb43641731a8221deb226eaf6e31fc6dfecb6b52c7
+  data.tar.gz: 437bd20b0f121eb0fa8d9f884545e2f0b1978a4c3f73c4bf6d1de9261d1f8d2cf3d410c188a03f1967f17d3c22c687315bcb97fd65300258a80b846ca42faaff

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.8.0
+
+- Initial release. Ports the upstream `@better-auth/telemetry` package
+  (vendored at `upstream/better-auth/1.6.9/packages/telemetry/`) into the
+  Ruby monorepo as the canonical `better_auth-telemetry` gem with a paired
+  `openauth-telemetry` alias.
+- Opt-in only. Telemetry is disabled by default and skipped under
+  `RACK_ENV=test` / `RAILS_ENV=test` / `APP_ENV=test` unless
+  `context[:skip_test_check]` bypasses the gate.
+- Supports both the `BETTER_AUTH_*` and `OPEN_AUTH_*` environment-variable
+  prefixes for `BETTER_AUTH_TELEMETRY`, `BETTER_AUTH_TELEMETRY_DEBUG`, and
+  `BETTER_AUTH_TELEMETRY_ENDPOINT` via `BetterAuth::Env.get`.
+- HTTP delivery uses Ruby's standard library (`Net::HTTP`) with a 5-second
+  open + read timeout. No external HTTP-client gem is required at runtime.
+- Soft-loaded by `BetterAuth::Auth#initialize`: when bundled, `auth.telemetry`
+  returns a publisher; when not bundled, it returns a noop publisher whose
+  `#publish` is a safe no-op.
+- Mirrors upstream redaction rules and camelCase wire-format keys for
+  `payload.config`. Ruby-specific deviations (single Ruby implementation,
+  `runtime.engine` extra key, `cpuSpeed` omitted, `cpuModel` always `nil`,
+  `packageManager` reflects Bundler, framework/database probe lists,
+  `appName` not emitted) are documented in the README.
+- No file under `upstream/better-auth/1.6.9/` is modified.

data/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2024 - present
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,202 @@
+# better_auth-telemetry
+
+Opt-in telemetry package for Better Auth Ruby. Ports the upstream
+`@better-auth/telemetry` package (vendored at
+`upstream/better-auth/1.6.9/packages/telemetry/`) using only Ruby's standard
+library.
+
+Telemetry is **disabled by default**. The package never sends data unless an
+operator explicitly opts in, and it is automatically skipped when the host
+process is running under `RACK_ENV=test`, `RAILS_ENV=test`, or `APP_ENV=test`.
+It is not configured through `plugins: [...]`; it is an optional gem that core
+soft-loads when available.
+
+## Installation
+
+Add the gem:
+
+```ruby
+gem "better_auth-telemetry"
+```
+
+When the gem is bundled, `BetterAuth::Auth#initialize` automatically wires
+`auth.telemetry` to a publisher. When the gem is **not** bundled, `auth.telemetry`
+is still safe to call: it returns a noop publisher whose `#publish` is a no-op.
+Core's behavior is unchanged either way.
+
+Require `better_auth/telemetry` only when using the telemetry API directly:
+
+```ruby
+require "better_auth/telemetry"
+```
+
+## Opting in
+
+Two equivalent ways to opt in. Either is sufficient on its own.
+
+### Via options
+
+```ruby
+auth = BetterAuth.auth(
+  secret: ENV.fetch("BETTER_AUTH_SECRET"),
+  database: :postgres,
+  telemetry: { enabled: true }
+)
+```
+
+An explicit `telemetry: { enabled: false }` always wins over the env var:
+setting `options[:telemetry][:enabled] = false` disables telemetry even when
+`BETTER_AUTH_TELEMETRY=1` is set.
+
+### Via environment variables
+
+The package reads every variable through `BetterAuth::Env.get`, which honors
+both the `BETTER_AUTH_*` and `OPEN_AUTH_*` prefixes. The `OPEN_AUTH_*` form
+takes precedence over the `BETTER_AUTH_*` form when both are set.
+
+| Purpose      | `BETTER_AUTH_*` form           | `OPEN_AUTH_*` form           |
+|--------------|--------------------------------|------------------------------|
+| Opt in       | `BETTER_AUTH_TELEMETRY`        | `OPEN_AUTH_TELEMETRY`        |
+| Debug mode   | `BETTER_AUTH_TELEMETRY_DEBUG`  | `OPEN_AUTH_TELEMETRY_DEBUG`  |
+| Endpoint URL | `BETTER_AUTH_TELEMETRY_ENDPOINT` | `OPEN_AUTH_TELEMETRY_ENDPOINT` |
+
+A value is treated as truthy when it is non-empty, not equal to `"0"`, and not
+equal to (case-insensitive) `"false"`. Unset and empty are both treated as
+absent. No other telemetry environment variables are recognized.
+
+```bash
+export BETTER_AUTH_TELEMETRY=1
+export BETTER_AUTH_TELEMETRY_ENDPOINT=https://telemetry.example.com/ingest
+```
+
+## Test environment skip
+
+When `RACK_ENV`, `RAILS_ENV`, or `APP_ENV` equals `"test"`, telemetry is skipped
+even if it is otherwise opted in. Bypass this skip by setting
+`context[:skip_test_check] = true`. `skip_test_check` only bypasses the test
+gate; it does not opt telemetry in on its own.
+
+```ruby
+BetterAuth::Telemetry.create(
+  options,
+  { skip_test_check: true } # opt-in still required via options or env
+)
+```
+
+## Debug mode
+
+When debug mode is on (`options[:telemetry][:debug] = true` or
+`BETTER_AUTH_TELEMETRY_DEBUG` set to a truthy value), every event is logged via
+the configured logger using `logger.info(JSON.pretty_generate(event))` and
+**no HTTP request is made**. This is the recommended mode for inspecting what
+the package would send before pointing it at a real endpoint.
+
+```ruby
+auth = BetterAuth.auth(
+  secret: ENV.fetch("BETTER_AUTH_SECRET"),
+  database: :postgres,
+  telemetry: { enabled: true, debug: true }
+)
+```
+
+When neither debug mode nor `custom_track` is configured and an endpoint is
+set, the publisher starts a short-lived background thread that POSTs JSON
+events to the endpoint via `Net::HTTP` with a 5-second open + read timeout.
+HTTP telemetry is fire-and-forget, so constructing `BetterAuth.auth` is not
+blocked by a slow or unavailable endpoint. Any `StandardError` raised during
+HTTP delivery is rescued and logged at error level rather than propagated.
+
+## The `custom_track` injection seam
+
+`context[:custom_track]` is a callable (typically a `Proc` or lambda) that
+receives every event in lieu of HTTP delivery. It is the testing seam used by
+the gem's own test suite, and it is also useful in production to forward
+events to an in-process queue, an audit log, or a custom collector.
+
+```ruby
+recorder = []
+custom_track = ->(event) { recorder << event }
+
+publisher = BetterAuth::Telemetry.create(
+  { secret: "x", database: :memory, telemetry: { enabled: true } },
+  { custom_track: custom_track, skip_test_check: true }
+)
+
+publisher.publish(type: "ping", payload: { hello: "world" })
+
+# recorder now contains the init event plus { type: "ping", payload: { hello: "world" }, anonymousId: "..." }
+```
+
+If `custom_track` raises, the exception is rescued, logged at error level, and
+swallowed; `#publish` always returns `nil`. The `anonymousId` on every event
+emitted by a single publisher is the same string, derived from
+`BetterAuth::Telemetry.project_id(base_url)`.
+
+The package accepts both snake_case and camelCase keys on the context for
+parity with callers mirroring upstream type definitions: `:custom_track` and
+`:customTrack` are equivalent, as are `:skip_test_check` and `:skipTestCheck`.
+
+## Differences from upstream
+
+The upstream `@better-auth/telemetry` package targets multiple JavaScript
+runtimes (Node, Bun, Deno, edge) and ships two build entrypoints. This Ruby
+port collapses both upstream variants into a single server-side Ruby
+implementation and adapts every detector to idiomatic Ruby. The wire format
+preserves upstream camelCase keys and redaction rules so existing telemetry
+consumers can ingest events from Ruby projects without schema branching.
+
+The intentional Ruby-specific deviations are:
+
+- **Single Ruby implementation.** No Node, Bun, Deno, or edge runtime
+  branches. Detectors do not probe for `npm_config_user_agent`, do not walk
+  `node_modules`, and do not classify against JavaScript-only runtimes.
+- **`runtime.engine` extra key.** The runtime payload includes an `:engine`
+  key (`"ruby"`, `"jruby"`, `"truffleruby"`) sourced from `RUBY_ENGINE` so
+  consumers can distinguish Ruby implementations. Upstream emits only `name`
+  and `version`.
+- **`cpuSpeed` omitted.** Upstream's `systemInfo.cpuSpeed` field is not
+  emitted at all on the Ruby side. There is no portable Ruby standard-library
+  API for CPU speed, and emitting `nil` would invite consumers to assume the
+  field can ever be populated.
+- **`cpuModel` always `nil`.** The `systemInfo.cpuModel` key is present in the
+  payload (so the schema matches upstream) but is always `nil`. Ruby has no
+  portable standard-library API for the CPU model string.
+- **`packageManager` reflects Bundler, not npm.** When Bundler is loadable
+  and a Gemfile is locatable, `payload.packageManager` is
+  `{ name: "bundler", version: Bundler::VERSION }`. Otherwise the field is
+  `nil`. Upstream's `npm_config_user_agent` parsing has no Ruby analogue.
+- **Framework probe list is Ruby-specific.** The framework detector inspects
+  `Gem.loaded_specs` for `rails`, `sinatra`, `hanami`, `hanami-router`,
+  `roda`, `grape`, `rack` (in that order). Node-only frameworks (`next`,
+  `nuxt`, `astro`, `sveltekit`, `solid-start`, `tanstack-start`, `hono`,
+  `express`, `elysia`, `expo`) are intentionally not probed.
+- **Database probe list is Ruby-specific.** The database detector falls back
+  to `Gem.loaded_specs` for `sequel`, `pg`, `mysql2`, `sqlite3`,
+  `activerecord`, `mongoid`, `mongo`, `rom-sql` (in that order) when no
+  context override or `BetterAuth::Adapters::*` adapter class match is found.
+- **Standard library only HTTP.** HTTP delivery uses `Net::HTTP` with a
+  5-second open + read timeout inside a short-lived background thread. No
+  external HTTP-client gem is required at runtime, and HTTP delivery does not
+  block `BetterAuth.auth` construction.
+- **Explicit false is a strong opt-out.** `telemetry: { enabled: false }`
+  disables telemetry even when `BETTER_AUTH_TELEMETRY` or `OPEN_AUTH_TELEMETRY`
+  is truthy. This is intentionally stricter than upstream so application
+  configuration can override process-wide env vars.
+- **snake_case canonical context keys, with camelCase synonyms accepted.**
+  The Ruby-canonical context keys are `:custom_track`, `:database`,
+  `:adapter`, `:skip_test_check`. The package also accepts the camelCase
+  variants (`:customTrack`, `:skipTestCheck`) for parity with callers
+  mirroring upstream type definitions.
+- **`appName` is not emitted.** The `app_name` value is used internally by
+  `BetterAuth::Telemetry.project_id` to derive the `anonymousId` but is
+  intentionally not emitted as a payload field, since it can be
+  user-identifying.
+- **Public `BetterAuth::Telemetry.reset_project_id!` testing helper.** A
+  module-level helper is exposed for resetting the memoized
+  `anonymous_id` between tests. It has no effect on production behavior and
+  exists solely so test suites can assert deterministic project_id derivation
+  across opt-in / opt-out cycles.
+
+## License
+
+MIT

data/lib/better_auth/plugins/telemetry.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Soft-load probe shim for `better_auth-telemetry`.
+#
+# The core package soft-loads `require "better_auth/telemetry"` when building
+# `auth.telemetry`. This shim keeps the plugin-style path loadable for callers
+# that still require it directly, then delegates to the canonical public entry
+# point.
+#
+# Implements Requirements 16.1 and 16.2.
+require "better_auth/telemetry"

data/lib/better_auth/telemetry/create.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "env"
+require_relative "http_client"
+require_relative "noop_publisher"
+require_relative "options"
+require_relative "project_id"
+require_relative "publisher"
+
+require_relative "detectors/auth_config"
+require_relative "detectors/database"
+require_relative "detectors/environment"
+require_relative "detectors/framework"
+require_relative "detectors/project_info"
+require_relative "detectors/runtime"
+require_relative "detectors/system_info"
+
+module BetterAuth
+  module Telemetry
+    # Process-environment variables that mark the host as running inside a
+    # test suite. Mirrors {BetterAuth::Configuration#test_environment?}
+    # without taking a hard dependency on a `Configuration` instance — the
+    # `create` entry point also accepts raw hashes and `nil`.
+    TEST_ENV_VARS = %w[RACK_ENV RAILS_ENV APP_ENV].freeze
+
+    # Public entry point used by `BetterAuth::Auth#initialize` (and by
+    # tests that exercise the publisher in isolation) to build a
+    # publisher tailored to the host's opt-in state.
+    #
+    # ## Pipeline
+    #
+    # 1. Normalize the heterogeneous `options` and `context` arguments
+    #    into {NormalizedOptions} / {NormalizedContext} value objects so
+    #    the rest of the pipeline does not have to repeatedly do
+    #    snake/camelCase key lookups.
+    # 2. Resolve `endpoint = Env.get("BETTER_AUTH_TELEMETRY_ENDPOINT")`,
+    #    honoring the `OPEN_AUTH_*` alias prefix.
+    # 3. **Short-circuit**: when both the endpoint and `custom_track`
+    #    are absent there is no delivery channel and the publisher
+    #    cannot do useful work, so we hand back a {NoopPublisher} and
+    #    bypass the rest of the pipeline (Requirement 5.1).
+    # 4. **Decision table** (Property 3 / Requirements 4.1–4.7):
+    #    compute `enabled` from `(options_enabled, env_truthy,
+    #    in_test_env, skip_test_check)` using
+    #
+    #        opt_in       = options_enabled == true || (options_enabled.nil? && env_truthy)
+    #        overridden   = options_enabled == false   # explicit false beats env truthy
+    #        in_test_gate = in_test_env && !skip_test_check
+    #        enabled      = opt_in && !overridden && !in_test_gate
+    #
+    # 5. When enabled, build the delivery `track` lambda via
+    #    {.build_track}: `custom_track` wins, then debug-mode logging,
+    #    then HTTP delivery (Requirements 5.2–5.4, 5.7, 5.9). Each
+    #    branch is wrapped in a `rescue StandardError` that routes the
+    #    failure through the configured logger (Requirements 21.1,
+    #    21.2) so a misbehaving sink never propagates out of the track
+    #    callable.
+    # 6. **Compose and emit the init event** (Requirement 6): resolve a
+    #    stable {.project_id} for the host (scoped to the
+    #    {CurrentOptions.with_app_name} block so the `from_app_name`
+    #    rule sees the configured `app_name`), invoke each detector
+    #    inside {.safely} so a single misbehaving probe degrades to
+    #    `nil` instead of aborting the init event, build the
+    #    upstream-shaped `{type: "init", anonymousId:, payload: {...}}`
+    #    event with camelCase keys, and fire it through the track
+    #    lambda exactly once. Errors raised by the dispatch itself
+    #    surface through the rescue inside the track lambda.
+    # 7. Return a fully-initialized {Publisher} that closes over the
+    #    same `track` / `anonymous_id` / `enabled` state so subsequent
+    #    `#publish` calls reuse the already-resolved id (Requirement
+    #    6.10).
+    #
+    # The method itself never raises: detectors are wrapped in
+    # {.safely}, the track lambda swallows transport failures, and the
+    # decision-layer logic is plain hash lookups and env reads.
+    #
+    # @param options [BetterAuth::Configuration, Hash, nil] the host's
+    #   options. `nil` is equivalent to `{}`. When a `Hash`, both
+    #   snake_case and camelCase keys are accepted.
+    # @param context [Hash, nil] optional caller-supplied context with
+    #   `custom_track` / `database` / `adapter` / `skip_test_check`
+    #   keys (snake_case or camelCase).
+    # @return [NoopPublisher, Publisher] a noop publisher when telemetry
+    #   has no delivery channel or is disabled, otherwise a fully-formed
+    #   {Publisher}.
+    def self.create(options, context = nil)
+      norm_opts = NormalizedOptions.from(options)
+      norm_ctx = NormalizedContext.from(context)
+      logger = norm_opts.logger
+
+      endpoint = Env.get("BETTER_AUTH_TELEMETRY_ENDPOINT")
+
+      # No delivery channel -> short-circuit to noop, regardless of opt-in.
+      return NoopPublisher.new if endpoint_absent?(endpoint) && norm_ctx.custom_track.nil?
+
+      enabled = compute_enabled(
+        options_enabled: norm_opts.telemetry_enabled,
+        env_truthy: Env.truthy?(Env.get("BETTER_AUTH_TELEMETRY")),
+        in_test_env: in_test_env?,
+        skip_test_check: norm_ctx.skip_test_check ? true : false
+      )
+
+      return NoopPublisher.new unless enabled
+
+      track = build_track(
+        custom_track: norm_ctx.custom_track,
+        debug: debug_mode?(norm_opts),
+        endpoint: endpoint,
+        logger: logger
+      )
+
+      # Resolve the anonymous id under a `with_app_name` scope so the
+      # `from_app_name` rule in `ProjectId.resolve_project_name` reads
+      # the configured `app_name` even when the underlying
+      # `BetterAuth::Telemetry.project_id` cache is cold. Once cached
+      # the value is reused for the lifetime of the process; the scope
+      # only matters on the very first call.
+      anonymous_id = CurrentOptions.with_app_name(norm_opts.app_name) do
+        BetterAuth::Telemetry.project_id(norm_opts.base_url)
+      end
+
+      init_event = compose_init_event(
+        options: options,
+        norm_ctx: norm_ctx,
+        anonymous_id: anonymous_id
+      )
+
+      track.call(init_event)
+
+      Publisher.new(
+        enabled: true,
+        anonymous_id: anonymous_id,
+        track: track,
+        base_url: norm_opts.base_url,
+        logger: logger
+      )
+    end
+
+    # Apply the Property 3 decision table.
+    #
+    # @api private
+    # @param options_enabled [Boolean, nil]
+    # @param env_truthy [Boolean]
+    # @param in_test_env [Boolean]
+    # @param skip_test_check [Boolean]
+    # @return [Boolean]
+    def self.compute_enabled(options_enabled:, env_truthy:, in_test_env:, skip_test_check:)
+      opt_in = options_enabled == true || (options_enabled.nil? && env_truthy)
+      overridden = options_enabled == false
+      in_test_gate = in_test_env && !skip_test_check
+
+      opt_in && !overridden && !in_test_gate
+    end
+
+    # @api private
+    def self.endpoint_absent?(endpoint)
+      endpoint.nil? || (endpoint.respond_to?(:empty?) && endpoint.empty?)
+    end
+
+    # @api private
+    def self.in_test_env?
+      TEST_ENV_VARS.any? { |k| ENV[k] == "test" }
+    end
+
+    # Decide whether debug mode is active. The option-layer flag wins
+    # when explicitly `true`; otherwise we defer to the env classifier
+    # via {Env.truthy?} on `BETTER_AUTH_TELEMETRY_DEBUG` (which honors
+    # the `OPEN_AUTH_*` alias prefix as well). Mirrors Requirement 5.4.
+    #
+    # @api private
+    # @param norm_opts [NormalizedOptions]
+    # @return [Boolean]
+    def self.debug_mode?(norm_opts)
+      norm_opts.telemetry_debug == true || Env.truthy?(Env.get("BETTER_AUTH_TELEMETRY_DEBUG"))
+    end
+
+    # Build the delivery `track` lambda. Three branches, in priority
+    # order (Requirements 5.2 → 5.4):
+    #
+    # 1. `custom_track` present — invoke `custom_track.call(event)`.
+    #    Primary testing seam and the only branch that runs without
+    #    requiring `BETTER_AUTH_TELEMETRY_ENDPOINT` to be set.
+    # 2. Debug mode active — log the JSON-pretty event via
+    #    `logger.info(...)` and skip HTTP entirely (Requirement 5.9).
+    # 3. Default — fire-and-forget JSON `POST` through a short-lived
+    #    background thread calling {HttpClient.post_json}, which
+    #    already swallows transport errors.
+    #
+    # Every branch wraps its dispatch in a `rescue StandardError` that
+    # routes the failure through `logger.error(...)`, so callable /
+    # logger-encoding / HTTP failures never propagate out of the track
+    # lambda. The lambda always returns `nil`.
+    #
+    # @api private
+    # @param custom_track [#call, nil]
+    # @param debug [Boolean]
+    # @param endpoint [String, nil]
+    # @param logger [LoggerAdapter]
+    # @return [Proc] a one-arg lambda accepting a normalized event hash.
+    def self.build_track(custom_track:, debug:, endpoint:, logger:)
+      if custom_track
+        lambda do |event|
+          custom_track.call(event)
+          nil
+        rescue => e
+          logger.error("[better-auth.telemetry] custom_track failed: #{e.class}: #{e.message}")
+          nil
+        end
+      elsif debug
+        lambda do |event|
+          logger.info(JSON.pretty_generate(event))
+          nil
+        rescue => e
+          logger.error("[better-auth.telemetry] debug log failed: #{e.class}: #{e.message}")
+          nil
+        end
+      else
+        lambda do |event|
+          Thread.new do
+            HttpClient.post_json(endpoint, event, logger: logger)
+          rescue => e
+            logger.error("[better-auth.telemetry] http dispatch failed: #{e.class}: #{e.message}")
+          end
+          nil
+        rescue => e
+          logger.error("[better-auth.telemetry] http dispatch failed: #{e.class}: #{e.message}")
+          nil
+        end
+      end
+    end
+
+    # Compose the init event hash emitted at create time.
+    #
+    # Each detector is invoked through {.safely} so a single failing
+    # probe degrades that field to `nil` rather than aborting the
+    # whole event composition (Requirement 6.4 / 9.11). The output
+    # matches the upstream wire shape: top-level `type`,
+    # `anonymousId`, and a `payload` hash with the seven camelCase
+    # keys `config`, `runtime`, `database`, `framework`,
+    # `environment`, `systemInfo`, `packageManager`
+    # (Requirements 6.1, 6.3).
+    #
+    # `AuthConfig.call` and `Database.call` are passed the original
+    # `options` argument (not the {NormalizedOptions} wrapper) because
+    # both detectors transparently accept either a
+    # {BetterAuth::Configuration} or a raw hash; the normalized view
+    # is only consumed by the decision/track-building layer.
+    #
+    # @api private
+    # @param options [BetterAuth::Configuration, Hash, nil]
+    # @param norm_ctx [NormalizedContext]
+    # @param anonymous_id [String]
+    # @return [Hash{Symbol => Object}]
+    def self.compose_init_event(options:, norm_ctx:, anonymous_id:)
+      payload = {
+        config: safely { Detectors::AuthConfig.call(options, norm_ctx) },
+        runtime: safely { Detectors::Runtime.call },
+        database: safely { Detectors::Database.call(options, norm_ctx) },
+        framework: safely { Detectors::Framework.call },
+        environment: safely { Detectors::Environment.call },
+        systemInfo: safely { Detectors::SystemInfo.call },
+        packageManager: safely { Detectors::ProjectInfo.call }
+      }
+
+      {
+        type: "init",
+        anonymousId: anonymous_id,
+        payload: payload
+      }
+    end
+
+    # Run `block` and rescue any `StandardError` to `nil`. Used to
+    # bound each detector invocation in {.compose_init_event} so a
+    # raising probe degrades only that field rather than aborting the
+    # whole init event.
+    #
+    # Non-`StandardError` exceptions (`Interrupt`, `SystemExit`,
+    # `SignalException`, `NoMemoryError`) are intentionally allowed to
+    # propagate.
+    #
+    # @api private
+    # @yield the probe to run.
+    # @return [Object, nil] whatever the block returns, or `nil` if
+    #   the block raised a `StandardError`.
+    def self.safely
+      yield
+    rescue
+      nil
+    end
+  end
+end