billdogeng 1.0.2.pre.beta.3

data/lib/billdogeng/flags.rb

@@ -0,0 +1,518 @@
+# frozen_string_literal: true
+
+require_relative "murmur"
+require_relative "targeting"
+
+module BilldogEng
+  # Feature-flag client supporting both remote and local (server-side) evaluation.
+  #
+  # Local evaluation (`local_evaluation: true`) fetches flag DEFINITIONS once,
+  # caches them with a 5-minute TTL, and evaluates each flag deterministically on
+  # this process — the correct home for flag evaluation in a server SDK and the
+  # cross-platform-identical algorithm shared with web / iOS / Android.
+  #
+  # Remote evaluation falls back to `POST /experiment-config`, which returns a
+  # pre-evaluated `feature_flags` map for the given user.
+  class Flags
+    FLAG_DEFINITIONS_TTL_MS = 5 * 60 * 1000 # 5 minutes
+
+    # Returned by #evaluate_locally when a DB-backed condition is load-bearing: the flag is neither on nor
+    # off from here, and the caller must ask the server. A sentinel — NOT `false` — because "we don't know"
+    # and "not in the audience" are different answers, and conflating them is how targeting breaks quietly.
+    COLD_VERDICT = :__billdog_requires_server_evaluation__
+
+    # Upper bound on the (distinct_id, flag, value) dedupe cache. A server SDK sees many users, so the
+    # cache is per-triple, not per-flag; when it fills, the OLDEST entry is evicted (insertion-ordered
+    # Hash) so exposures for churned users are eventually re-emitted rather than the SDK leaking memory
+    # unboundedly.
+    MAX_REPORTED_FLAG_CALLS = 50_000
+
+    # @param send_feature_flag_events [Boolean] global toggle for `$feature_flag_called` exposure events.
+    # @param disabled [Boolean] when true all flag reads are inert (return nil/{}), no network.
+    # @param polling_interval_ms [Integer] TTL (ms) for cached local flag definitions. Default 5 min.
+    # @param capture [#call] emit an analytics event, wired to the Analytics client's #capture:
+    #   `->(distinct_id, event, properties) { ... }`. Optional (nil disables emission entirely).
+    def initialize(transport, api_key:, local_evaluation:, enable_logging:,
+                   send_feature_flag_events: true, disabled: false,
+                   polling_interval_ms: FLAG_DEFINITIONS_TTL_MS, capture: nil)
+      @transport = transport
+      @api_key = api_key
+      @local_evaluation = local_evaluation
+      @enable_logging = enable_logging
+      @send_feature_flag_events = send_feature_flag_events
+      @disabled = disabled
+      @polling_interval_ms = polling_interval_ms
+      @capture = capture
+
+      @definitions = {}            # key => definition hash
+      @definitions_fetched_at = 0  # epoch ms
+      @mutex = Mutex.new
+      @fetch_mutex = Mutex.new     # single-flight guard for definition fetches
+      @fetch_cond = ConditionVariable.new
+      @fetch_in_progress = false
+
+      # Dedupe set for `$feature_flag_called`, keyed "distinct_id:key:value". A Hash is used as an
+      # insertion-ordered set so #shift evicts the OLDEST entry (FIFO) when the cap is reached. Guarded by
+      # its own mutex because Ruby analytics runs on background threads.
+      @reported_flag_calls = {}
+      @report_mutex = Mutex.new
+    end
+
+    # True when a flag's conditions need the database, so it cannot be evaluated in-process.
+    def server_only?(key)
+      def_ = @definitions[key]
+      !def_.nil? && def_["requires_server_evaluation"] == true
+    end
+
+    # Get a flag's value for a user.
+    #
+    # @param groups [Hash] group memberships, e.g. `{ "organisation" => "acme" }`. Feeds the audience
+    #   engine's `group` conditions, evaluated LOCALLY — the map is caller-supplied, so no DB is needed.
+    # @param person_properties [Hash] person attributes, read by `attribute` / `entitlement` /
+    #   `subscription_status` conditions.
+    # @param country [String] evaluation context, read by `country` / `platform` / `app_version` /
+    # @param platform [String] `sdk_version` conditions. Each falls back to a same-named person property.
+    # @param app_version [String]
+    # @param sdk_version [String]
+    # @param experiment_variants [Hash] experiment assignments, read by `experiment_variant` conditions.
+    # @return [true, false, String, nil] boolean, variant key, or nil if unknown.
+    def get_feature_flag(key, distinct_id, groups: nil, person_properties: nil, country: nil,
+                         platform: nil, app_version: nil, sdk_version: nil, experiment_variants: nil,
+                         send_feature_flag_events: nil, only_evaluate_locally: false)
+      return nil if @disabled
+
+      opts = build_opts(groups, person_properties, country, platform, app_version, sdk_version,
+                        experiment_variants, send_feature_flag_events, only_evaluate_locally)
+      if @local_evaluation
+        ensure_definitions
+        return nil unless @definitions.key?(key)
+
+        # A flag whose release conditions need the DATABASE (segment / cohort / survey_answer /
+        # event_fired_in_window / group_property) is emitted with requires_server_evaluation. Evaluating
+        # it here would ignore the conditions entirely and turn a TARGETED flag ON for users who do not
+        # match it.
+        unless server_only?(key)
+          verdict = eval_local(key, distinct_id, opts)
+          unless verdict == COLD_VERDICT
+            report_feature_flag_called(key, distinct_id, verdict, opts)
+            return verdict
+          end
+          # Defensive: the server said this flag was locally evaluable but a DB-backed condition turned
+          # out to be load-bearing. Ask the server rather than guess.
+        end
+      end
+
+      # only_evaluate_locally: caller forbids a server round-trip — return nil rather than ask.
+      return nil if only_evaluate_locally
+
+      map = fetch_remote(distinct_id, opts[:person_properties], opts[:groups])
+      return nil unless map.key?(key)
+
+      report_feature_flag_called(key, distinct_id, map[key], opts)
+      map[key]
+    end
+
+    # Boolean view of #get_feature_flag (a variant string counts as ON).
+    def feature_enabled?(key, distinct_id, groups: nil, person_properties: nil, country: nil,
+                         platform: nil, app_version: nil, sdk_version: nil, experiment_variants: nil,
+                         send_feature_flag_events: nil, only_evaluate_locally: false)
+      v = get_feature_flag(key, distinct_id, groups: groups, person_properties: person_properties,
+                                             country: country, platform: platform,
+                                             app_version: app_version, sdk_version: sdk_version,
+                                             experiment_variants: experiment_variants,
+                                             send_feature_flag_events: send_feature_flag_events,
+                                             only_evaluate_locally: only_evaluate_locally)
+      return false if v.nil?
+
+      v != false
+    end
+
+    # Get a flag's payload (variant config). Only meaningful under local eval.
+    # Returns the matched variant's payload, else the flag-level payload, else nil.
+    def get_feature_flag_payload(key, distinct_id, groups: nil, person_properties: nil, country: nil,
+                                 platform: nil, app_version: nil, sdk_version: nil,
+                                 experiment_variants: nil, send_feature_flag_events: nil,
+                                 only_evaluate_locally: false)
+      return nil if @disabled
+
+      opts = build_opts(groups, person_properties, country, platform, app_version, sdk_version,
+                        experiment_variants, send_feature_flag_events, only_evaluate_locally)
+      ensure_definitions
+      def_ = @definitions[key]
+      return nil unless def_
+
+      verdict = if server_only?(key)
+                  # Server-only conditions: resolve remotely rather than ignoring them. only_evaluate_locally
+                  # forbids the round-trip — cannot resolve, so return nil.
+                  return nil if only_evaluate_locally
+
+                  fetch_remote(distinct_id, opts[:person_properties], opts[:groups])[key]
+                else
+                  local = eval_local(key, distinct_id, opts)
+                  if local == COLD_VERDICT
+                    return nil if only_evaluate_locally
+
+                    fetch_remote(distinct_id, opts[:person_properties], opts[:groups])[key]
+                  else
+                    local
+                  end
+                end
+      # Node coerces a missing remote verdict to `false` (`?? false`), so the definition-known flag still
+      # emits an exposure of `false` rather than silently skipping — mirror that before reporting.
+      verdict = false if verdict.nil?
+      report_feature_flag_called(key, distinct_id, verdict, opts)
+      return nil if verdict == false
+
+      if verdict.is_a?(String) && def_["variants"]
+        variant = Array(def_["variants"]).find { |v| v["key"] == verdict }
+        return variant["payload"] if variant && variant.key?("payload") && !variant["payload"].nil?
+      end
+      def_["payload"]
+    end
+
+    # Evaluate every known flag for a user.
+    def get_all_flags(distinct_id, groups: nil, person_properties: nil, country: nil, platform: nil,
+                      app_version: nil, sdk_version: nil, experiment_variants: nil,
+                      only_evaluate_locally: false)
+      return {} if @disabled
+
+      opts = build_opts(groups, person_properties, country, platform, app_version, sdk_version,
+                        experiment_variants, nil, only_evaluate_locally)
+      unless @local_evaluation
+        # only_evaluate_locally with no local definitions to evaluate from → nothing to return.
+        return {} if only_evaluate_locally
+
+        return fetch_remote(distinct_id, opts[:person_properties], opts[:groups])
+      end
+
+      ensure_definitions
+
+      # Evaluate locally FIRST, so we learn which flags actually need the server — including any that go
+      # COLD at runtime — and can then fetch them all in ONE request rather than one per flag.
+      local = {}
+      need_server = []
+      @definitions.each_key do |key|
+        if server_only?(key)
+          need_server << key
+          next
+        end
+
+        verdict = eval_local(key, distinct_id, opts)
+        if verdict == COLD_VERDICT
+          need_server << key
+        else
+          local[key] = verdict
+        end
+      end
+
+      # only_evaluate_locally: skip the server round-trip; flags that needed it resolve to false.
+      remote = if need_server.empty? || only_evaluate_locally
+                 {}
+               else
+                 fetch_remote(distinct_id, opts[:person_properties], opts[:groups])
+               end
+
+      out = {}
+      @definitions.each_key do |key|
+        out[key] = local.key?(key) ? local[key] : remote.fetch(key, false)
+      end
+      out
+    end
+
+    # Evaluate every known flag AND its payload for a user. Payloads resolve in LOCAL mode (from the
+    # cached definitions); in remote mode payloads are unavailable, so payload is nil. The value side
+    # matches #get_all_flags. Returns `{ key => { "value" => v, "payload" => p } }`. Disabled → {}.
+    def get_all_flags_and_payloads(distinct_id, groups: nil, person_properties: nil, country: nil,
+                                   platform: nil, app_version: nil, sdk_version: nil,
+                                   experiment_variants: nil, only_evaluate_locally: false)
+      return {} if @disabled
+
+      values = get_all_flags(distinct_id, groups: groups, person_properties: person_properties,
+                                          country: country, platform: platform,
+                                          app_version: app_version, sdk_version: sdk_version,
+                                          experiment_variants: experiment_variants,
+                                          only_evaluate_locally: only_evaluate_locally)
+      out = {}
+      values.each do |key, value|
+        out[key] = { "value" => value, "payload" => payload_for(key, value) }
+      end
+      out
+    end
+
+    # Synchronous, LOCAL-ONLY evaluation of every cached flag — used by capture(..., send_feature_flags:)
+    # to attach `$feature/<key>` properties without blocking on a fetch. Server-only and COLD flags are
+    # skipped (they cannot be resolved here). Returns only flags whose verdict is determined locally.
+    def evaluate_all_local_sync(distinct_id, groups = nil)
+      return {} if @disabled
+
+      opts = build_opts(groups, nil, nil, nil, nil, nil, nil)
+      out = {}
+      @definitions.each_key do |key|
+        next if server_only?(key)
+
+        verdict = eval_local(key, distinct_id, opts)
+        out[key] = verdict unless verdict == COLD_VERDICT
+      end
+      out
+    end
+
+    # Force a reload of the cached flag definitions (local mode).
+    def reload_feature_flag_definitions
+      fetch_definitions
+      nil
+    end
+
+    # Inject flag definitions directly, bypassing the network. Primarily for
+    # tests and for hosts that distribute definitions through their own channel.
+    # Accepts an array of definition hashes (string- or symbol-keyed).
+    def set_definitions(defs)
+      normalized = Array(defs).map { |d| normalize_definition(d) }
+      @mutex.synchronize do
+        @definitions = normalized.each_with_object({}) { |d, acc| acc[d["key"]] = d }
+        @definitions_fetched_at = now_ms
+      end
+      nil
+    end
+
+    # Deterministic local flag evaluation (spec §D):
+    #  1. Missing/inactive → false.
+    #  2. The flag's release conditions (`targeting_rule`) must match, else false. Resolved by the
+    #     canonical audience evaluator in BilldogEng::Targeting — AND/OR, date windows, rule status, the
+    #     full operator set and group membership all resolve here, with no server round-trip.
+    #  3. bucket = murmurhash3("flag:{key}:{distinct_id}") % 100; ON iff bucket < rollout.
+    #  4. Multivariate: walk variants by cumulative rollout against an INDEPENDENT hash,
+    #     murmurhash3("flag-variant:{key}:{distinct_id}") % 100 — NOT the rollout bucket.
+    #
+    # @return [false, true, String, COLD_VERDICT] false (off), true (on), the chosen variant key, or
+    #   COLD_VERDICT when a DB-backed condition turned out to be load-bearing and only the server can
+    #   decide. NEVER collapse COLD_VERDICT into false.
+    def evaluate_locally(key, distinct_id, person_properties = nil, groups: nil, country: nil,
+                         platform: nil, app_version: nil, sdk_version: nil, experiment_variants: nil)
+      opts = build_opts(groups, person_properties, country, platform, app_version, sdk_version,
+                        experiment_variants)
+      eval_local(key, distinct_id, opts)
+    end
+
+    private
+
+    def build_opts(groups, person_properties, country, platform, app_version, sdk_version,
+                   experiment_variants, send_feature_flag_events = nil, only_evaluate_locally = false)
+      {
+        groups: groups,
+        person_properties: person_properties,
+        country: country,
+        platform: platform,
+        app_version: app_version,
+        sdk_version: sdk_version,
+        experiment_variants: experiment_variants,
+        send_feature_flag_events: send_feature_flag_events,
+        only_evaluate_locally: only_evaluate_locally,
+      }
+    end
+
+    # The payload a resolved verdict maps to, from cached definitions (variant payload → flag payload →
+    # nil). A false verdict has no payload.
+    def payload_for(key, value)
+      return nil if value == false
+
+      def_ = @definitions[key]
+      return nil unless def_
+
+      if value.is_a?(String) && def_["variants"]
+        variant = Array(def_["variants"]).find { |v| v["key"] == value }
+        return variant["payload"] if variant && variant.key?("payload") && !variant["payload"].nil?
+      end
+      def_["payload"]
+    end
+
+    # Emit the `$feature_flag_called` exposure event (PostHog parity) — the record that lets analytics and
+    # experiments attribute outcomes to the flag a user was exposed to. Deduped per (distinct_id, key,
+    # value) so a hot flag read in a request loop bills at most one exposure per user per value.
+    # Fire-and-forget: the value is handed to the analytics #capture (which queues), never awaited, so a
+    # flag read is never slowed or failed by telemetry. `nil` verdicts (unknown flag) are NOT reported —
+    # there was no exposure. Gated by a per-call `send_feature_flag_events` override (wins when present),
+    # else the global toggle.
+    def report_feature_flag_called(key, distinct_id, response, opts)
+      enabled = opts[:send_feature_flag_events]
+      enabled = @send_feature_flag_events if enabled.nil?
+      return if enabled == false
+      return if @capture.nil?
+
+      dedupe_key = "#{distinct_id}:#{key}:#{response}"
+      @report_mutex.synchronize do
+        return if @reported_flag_calls.key?(dedupe_key)
+
+        # Evict the OLDEST (insertion-ordered) entry to bound memory.
+        @reported_flag_calls.shift if @reported_flag_calls.size >= MAX_REPORTED_FLAG_CALLS
+        @reported_flag_calls[dedupe_key] = true
+      end
+
+      @capture.call(distinct_id, "$feature_flag_called", {
+                      "$feature_flag" => key,
+                      "$feature_flag_response" => response,
+                    })
+    end
+
+    def eval_local(key, distinct_id, opts)
+      def_ = @definitions[key]
+      return false if def_.nil? || !def_["active"]
+
+      rule = def_["targeting_rule"]
+      if rule
+        verdict = Targeting.evaluate_targeting_rule(rule, audience_context(opts))
+        # A DB-backed condition is load-bearing. We cannot resolve it and MUST NOT guess — treating it as
+        # "no match" would silently withhold the flag, and treating it as a match would silently hand a
+        # targeted feature to everyone. Tell the caller to ask the server.
+        return COLD_VERDICT if verdict.cold?
+        return false unless verdict.matched?
+      end
+
+      # CANONICAL bucketing — must match the backend byte-for-byte. Conformance vectors:
+      # tests/fixtures/flag-bucketing.json (generated FROM the backend).
+      bucket = Murmur.murmurhash3("flag:#{key}:#{distinct_id}") % 100
+      return false if bucket >= def_["rollout_percentage"]
+
+      variants = def_["variants"]
+      if variants && !variants.empty?
+        # INDEPENDENT hash — reusing the rollout bucket starves later variants: at 10% rollout split 50/50
+        # every enabled user has bucket < 10, which is < 50, so variant B was NEVER assigned.
+        variant_bucket = Murmur.murmurhash3("flag-variant:#{key}:#{distinct_id}") % 100
+        cumulative = 0
+        variants.each do |variant|
+          cumulative += variant["rollout_percentage"]
+          return variant["key"] if variant_bucket < cumulative
+        end
+        return true # weights sum < 100 → on, no specific variant
+      end
+
+      true
+    end
+
+    # Build the audience context the canonical evaluator reads, from the SDK's flag-eval options.
+    def audience_context(opts)
+      props = opts[:person_properties] || {}
+      {
+        # Explicit context wins; otherwise fall back to a same-named person property, since most callers
+        # already carry country/platform in their property bag.
+        "country" => opts[:country] || Targeting.dig_key(props, "country"),
+        "platform" => opts[:platform] || Targeting.dig_key(props, "platform"),
+        "app_version" => opts[:app_version] || Targeting.dig_key(props, "app_version"),
+        "sdk_version" => opts[:sdk_version] || Targeting.dig_key(props, "sdk_version"),
+        "custom_attributes" => props,
+        "groups" => opts[:groups],
+        "experiment_variants" => opts[:experiment_variants],
+      }
+    end
+
+    def log(*args)
+      warn("[BilldogEng:flags] #{args.join(" ")}") if @enable_logging
+    end
+
+    def ensure_definitions
+      return if definitions_fresh?
+
+      # Single-flight: when the TTL expires under concurrent load, only ONE thread
+      # fetches; the rest wait for it rather than each firing a duplicate
+      # /feature-flag-definitions request (node dedups via a shared loadPromise). The
+      # HTTP call runs OUTSIDE @fetch_mutex so a slow fetch never blocks the waiters'
+      # bookkeeping and there is no lock-ordering hazard with @mutex.
+      do_fetch = false
+      @fetch_mutex.synchronize do
+        if @fetch_in_progress
+          @fetch_cond.wait(@fetch_mutex) while @fetch_in_progress
+          return # the in-flight fetch populated (or refreshed) the cache
+        end
+        return if definitions_fresh? # a fetch may have completed between the checks
+
+        @fetch_in_progress = true
+        do_fetch = true
+      end
+      return unless do_fetch
+
+      begin
+        fetch_definitions
+      ensure
+        @fetch_mutex.synchronize do
+          @fetch_in_progress = false
+          @fetch_cond.broadcast
+        end
+      end
+    end
+
+    def definitions_fresh?
+      @mutex.synchronize do
+        !@definitions.empty? && (now_ms - @definitions_fetched_at) < @polling_interval_ms
+      end
+    end
+
+    def fetch_definitions
+      data = @transport.request(
+        path: "/feature-flag-definitions",
+        body: { "api_key" => @api_key },
+        headers: { "X-BillDog-API-Key" => @api_key },
+        gzip: false,
+      )
+      flags = (data.is_a?(Hash) ? data["flags"] : nil) || []
+      normalized = flags.map { |d| normalize_definition(d) }
+      @mutex.synchronize do
+        @definitions = normalized.each_with_object({}) { |d, acc| acc[d["key"]] = d }
+        @definitions_fetched_at = now_ms
+      end
+      log("loaded #{@definitions.size} flag definitions")
+    rescue BilldogEng::Error => e
+      # Graceful: keep any existing cache; surface in logs only.
+      log("failed to load flag definitions: #{e.message}")
+    end
+
+    def fetch_remote(distinct_id, attributes, groups = nil)
+      data = @transport.request(
+        path: "/experiment-config",
+        body: {
+          "api_key" => @api_key,
+          "user_id" => distinct_id,
+          "attributes" => attributes || {},
+          # GROUP TARGETING: this param existed on the flag API and was silently DROPPED (the server had
+          # nowhere to put it). It now feeds the audience engine's group / group_property conditions.
+          "groups" => groups || {},
+        },
+        headers: { "X-BillDog-API-Key" => @api_key },
+        gzip: false,
+      )
+      (data.is_a?(Hash) ? data["feature_flags"] : nil) || {}
+    end
+
+    # Normalize a definition hash to string keys (variants too). The canonical `targeting_rule` is nested
+    # (conditions → rules → condition hashes), so it is stringified DEEPLY: a shallow pass would leave
+    # symbol keys inside the rule where the evaluator looks for strings.
+    def normalize_definition(def_)
+      d = stringify(def_)
+      d["variants"] = Array(d["variants"]).map { |v| stringify(v) } if d.key?("variants")
+      d["targeting_rule"] = deep_stringify(d["targeting_rule"]) if d.key?("targeting_rule")
+      d
+    end
+
+    def stringify(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) { |(k, v), acc| acc[k.is_a?(Symbol) ? k.to_s : k] = v }
+    end
+
+    # Recursively string-key every nested hash, preserving arrays and scalar values verbatim.
+    def deep_stringify(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), acc|
+          acc[k.is_a?(Symbol) ? k.to_s : k] = deep_stringify(v)
+        end
+      when Array
+        obj.map { |v| deep_stringify(v) }
+      else
+        obj
+      end
+    end
+
+    def now_ms
+      (Time.now.to_f * 1000).to_i
+    end
+  end
+end

data/lib/billdogeng/llm.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "time"
+
+module BilldogEng
+  # LLM observability — capture a model invocation as a trace span.
+  #
+  # Wraps `POST /llm/trace`. The wire payload is camelCase (matching the edge
+  # function's Zod schema) and authenticates with `X-BillDog-API-Key`.
+  class Llm
+    def initialize(transport, api_key:)
+      @transport = transport
+      @api_key = api_key
+    end
+
+    # Record a single LLM trace span.
+    #
+    # @param trace_id         [String] (required)
+    # @param span_id          [String] (required)
+    # @param model            [String] (required)
+    # @param input_text       [String] (required)
+    # @param output_text      [String] (required)
+    # @param parent_span_id   [String, nil]
+    # @param prompt_tokens    [Integer]
+    # @param completion_tokens[Integer]
+    # @param duration_ms      [Integer]
+    # @param cost_usd         [Numeric]
+    # @param properties       [Hash]
+    # @param metadata         [Hash]
+    # @param timestamp        [String, nil] ISO-8601; defaults to now.
+    def capture_trace(trace_id:, span_id:, model:, input_text:, output_text:,
+                      parent_span_id: nil, prompt_tokens: 0, completion_tokens: 0,
+                      duration_ms: 0, cost_usd: 0, properties: {}, metadata: {}, timestamp: nil)
+      body = {
+        "api_key" => @api_key,
+        "traceId" => trace_id,
+        "spanId" => span_id,
+        "parentSpanId" => parent_span_id || "",
+        "model" => model,
+        "inputText" => input_text,
+        "outputText" => output_text,
+        "promptTokens" => prompt_tokens || 0,
+        "completionTokens" => completion_tokens || 0,
+        "durationMs" => duration_ms || 0,
+        "costUsd" => cost_usd || 0,
+        "properties" => properties || {},
+        "metadata" => metadata || {},
+        "timestamp" => timestamp || Time.now.utc.iso8601(3),
+      }
+
+      @transport.request(
+        path: "/llm/trace",
+        body: body,
+        headers: { "X-BillDog-API-Key" => @api_key },
+        gzip: false,
+      )
+    end
+  end
+end

data/lib/billdogeng/messaging.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BilldogEng
+  # Messaging dispatch (BillDog advantage over PostHog) — server-side delivery
+  # across push / email / sms / in-app / live-activity.
+  #
+  # Note: `messaging-dispatch` authenticates with a Supabase session **Bearer
+  # JWT** + project membership, not the `X-BillDog-API-Key` key used by the other
+  # modules. Pass the JWT as `:access_token` per call.
+  class Messaging
+    def initialize(transport)
+      @transport = transport
+    end
+
+    # Dispatch a message.
+    #
+    # @param project_id   [String] project UUID (required)
+    # @param channel      [String, Symbol] push|email|sms|in-app|live-activity
+    # @param content      [Hash]   message content
+    # @param access_token [String] Bearer JWT (required)
+    # @param targeting    [Hash, nil] { type:, conditions:, segmentIds:, tags:, subscriberIds: }
+    # @param scheduling   [Hash, nil] { deliveryType:, scheduledAt:, windowStart:, windowEnd: }
+    # @param template_id  [String, nil]
+    # @return [Hash] e.g. { "sent" => N, "failed" => M }
+    def dispatch(project_id:, channel:, content:, access_token:, targeting: nil, scheduling: nil, template_id: nil)
+      body = {
+        "action" => "send",
+        "project_id" => project_id,
+        "channel" => channel.to_s,
+        "content" => content,
+      }
+      body["targeting"] = targeting if targeting
+      body["scheduling"] = scheduling if scheduling
+      body["template_id"] = template_id if template_id
+
+      @transport.request(
+        path: "/messaging-dispatch",
+        body: body,
+        headers: { "Authorization" => "Bearer #{access_token}" },
+        gzip: false,
+      )
+    end
+  end
+end