billdogeng 1.0.2.pre.beta.3

data/lib/billdogeng/client.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+require_relative "analytics"
+require_relative "flags"
+require_relative "surveys"
+require_relative "messaging"
+require_relative "llm"
+
+module BilldogEng
+  # The BilldogEng server SDK client.
+  #
+  # Engagement suite for server-side use: Analytics, Feature Flags (remote +
+  # local evaluation), Surveys (data API), Messaging dispatch, and LLM tracing.
+  #
+  # @example
+  #   bd = BilldogEng::Client.new("bd_test_xxx", local_evaluation: true)
+  #   bd.capture("user-123", "order_completed", { revenue: 49.99 })
+  #   on = bd.feature_enabled?("new_checkout", "user-123")
+  #   bd.shutdown
+  class Client
+    DEFAULTS = {
+      host: "https://api.billdog.io/v1",
+      flush_at: 20,
+      flush_interval: 10_000,
+      max_queue_size: 1000,
+      gzip: true,
+      local_evaluation: false,
+      request_timeout: 10_000,
+      max_retries: 3,
+      enable_logging: false,
+      # Person-profile processing mode — PostHog `$process_person_profile`
+      # parity. One of "always", "identified_only" (default), or "never".
+      #
+      #   "identified_only" (DEFAULT) — anonymous until you call #identify,
+      #       then identified. Matches historical behaviour; cheapest.
+      #       Attaches nothing to the wire event.
+      #   "never"  — every event stays ANONYMOUS, even after #identify. The
+      #       SDK sends $process_person_profile:false; ingest keeps customer_id
+      #       empty and never re-stitches the row to a person.
+      #   "always" — every event is IDENTIFIED, even before #identify: ingest
+      #       promotes the anonymous id to a customer. ⚠️ Billing impact —
+      #       every distinct device then counts toward billable MAU.
+      #
+      # A per-event "$process_person_profile" boolean in an event's properties
+      # overrides this mode for that single event.
+      person_profiles: "identified_only",
+      # Global toggle for `$feature_flag_called` exposure events (PostHog parity).
+      # A per-call `send_feature_flag_events:` on a flag read overrides this.
+      send_feature_flag_events: true,
+      # GeoIP resolution level applied to the /ingest-events flush via the
+      # `x-geoip-resolution-level` header. One of "full", "country_region",
+      # "country_only", "none". Unset (nil) → no header, backend default applies.
+      geoip_resolution_level: nil,
+      # Kill switch. When true the SDK is INERT: capture/identify/group_identify/alias/
+      # set_person_properties are no-ops, flag reads return nil/{}, NO background flush
+      # timer starts and NO network happens. Scoped to analytics + flags (like node);
+      # explicit surveys/messaging/llm calls are NOT gated. Default false.
+      disabled: false,
+      # TTL (ms) for cached local flag definitions — how stale a definition set may get
+      # before the next flag read refetches it. Replaces the old hardcoded 5-min TTL.
+      # Default 300000 (5 min).
+      feature_flags_polling_interval: 5 * 60 * 1000,
+      # Hook run on every event just before it is queued: `->(event) { event | nil }`.
+      # Return the (possibly mutated) event to send it, or nil to DROP it. Runs at the
+      # single enqueue choke point, so it sees capture/identify/group/alias AND the
+      # `$feature_flag_called` exposure. Default nil (no hook).
+      before_send: nil,
+    }.freeze
+
+    attr_reader :options
+    # Surveys data API.
+    attr_reader :surveys
+    # Messaging dispatch.
+    attr_reader :messaging
+    # LLM observability.
+    attr_reader :llm
+    # Direct access to the flags client (advanced: set_definitions, evaluate_locally).
+    attr_reader :feature_flags
+
+    # @param api_key [String]
+    # @param opts    [Hash] see DEFAULTS for accepted keys. May also pass
+    #   :http_adapter (an injectable `->(method,url,headers,body){[status,body]}`
+    #   used by the transport, primarily for tests).
+    def initialize(api_key, opts = {})
+      raise ArgumentError, "BilldogEng: api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      http_adapter = opts.delete(:http_adapter)
+      @options = DEFAULTS.merge(strip_nil(opts))
+
+      @transport = Transport.new(
+        host: @options[:host],
+        request_timeout: @options[:request_timeout],
+        gzip: @options[:gzip],
+        max_retries: @options[:max_retries],
+        enable_logging: @options[:enable_logging],
+        http_adapter: http_adapter,
+      )
+
+      @analytics = Analytics.new(@transport, api_key: api_key, options: @options)
+      @flags = Flags.new(
+        @transport,
+        api_key: api_key,
+        local_evaluation: @options[:local_evaluation],
+        enable_logging: @options[:enable_logging],
+        send_feature_flag_events: @options[:send_feature_flag_events],
+        disabled: @options[:disabled],
+        polling_interval_ms: @options[:feature_flags_polling_interval],
+        # Exposure events ride the normal analytics pipeline (batched, billed).
+        capture: ->(distinct_id, event, properties) { @analytics.capture(distinct_id, event, properties) },
+      )
+      @feature_flags = @flags
+      # Late-bind so capture(..., send_feature_flags: true) can inject the user's active flags without a
+      # construction-order cycle (analytics is built before flags, but flags depends on analytics.capture).
+      @analytics.set_flag_resolver(->(distinct_id, groups) { @flags.evaluate_all_local_sync(distinct_id, groups) })
+      @surveys = Surveys.new(@transport, api_key: api_key)
+      @messaging = Messaging.new(@transport)
+      @llm = Llm.new(@transport, api_key: api_key)
+    end
+
+    # ─── Analytics ────────────────────────────────────────────────────────────
+
+    # Capture an event for a user. Batched; flushed per the configured policy.
+    #
+    # @param timestamp [Integer, Time, nil] override the event timestamp — epoch ms or a native Time
+    #   (for backfills / historical import). A Time is normalized to epoch ms; nil → now.
+    # @param send_feature_flags [Boolean] attach the user's active flags to the event as
+    #   `$feature/<key>` properties (plus `$active_feature_flags`). Best-effort, LOCAL-only, sync — uses
+    #   already-cached definitions and never blocks the capture on a fetch; server-only/cold flags skipped.
+    def capture(distinct_id, event, properties = {}, groups = {}, timestamp: nil, send_feature_flags: false)
+      @analytics.capture(distinct_id, event, properties, groups,
+                         timestamp: timestamp, send_feature_flags: send_feature_flags)
+    end
+
+    # Capture an exception as a canonical `$exception` event (PostHog error-tracking parity). Parses the
+    # error's class / message / backtrace into the `$exception_list` shape. A server SDK requires the
+    # distinct_id. Disabled => no-op; a malformed/absent backtrace never raises out.
+    def capture_exception(error, distinct_id, properties = {})
+      @analytics.capture_exception(error, distinct_id, properties)
+    end
+
+    # Set person properties. Emits `$identify`. When `set_once` is supplied, ALSO persists
+    # `$set_once` properties to the profile store via #set_person_properties.
+    def identify(distinct_id, properties = {}, set_once: nil)
+      @analytics.identify(distinct_id, properties, set_once: set_once)
+    end
+
+    # Apply person-property operations to the profile store (POST `/user-properties`).
+    # Ops build in the order set -> set_once -> add -> append -> unset; empty ops => no request.
+    # Fire-and-forget (never blocks or raises out of the caller).
+    def set_person_properties(distinct_id, set: nil, set_once: nil, add: nil, append: nil, unset: nil)
+      @analytics.set_person_properties(distinct_id, set: set, set_once: set_once, add: add,
+                                                    append: append, unset: unset)
+    end
+
+    # Set group properties. Emits `$groupidentify`.
+    def group_identify(group_type, group_key, properties = {})
+      @analytics.group_identify(group_type, group_key, properties)
+    end
+
+    # Alias one distinct id to another. Emits `$create_alias`.
+    def alias(distinct_id, alias_id)
+      @analytics.alias(distinct_id, alias_id)
+    end
+
+    # Flush queued analytics events now.
+    def flush
+      @analytics.flush
+    end
+
+    # Number of events currently queued (test/observability aid).
+    def queue_length
+      @analytics.queue_length
+    end
+
+    # ─── Feature flags ──────────────────────────────────────────────────────
+
+    # `country` / `platform` / `app_version` / `sdk_version` / `experiment_variants` are the evaluation
+    # context read by the canonical audience conditions of the same name; `groups` feeds `group`
+    # membership conditions. All are resolved LOCALLY under local evaluation.
+    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)
+      @flags.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)
+    end
+
+    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)
+      @flags.feature_enabled?(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)
+    end
+
+    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)
+      @flags.get_feature_flag_payload(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)
+    end
+
+    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)
+      @flags.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)
+    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. Returns a hash of
+    # `{ "value" => <bool|variant>, "payload" => <config|nil> }` per flag.
+    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)
+      @flags.get_all_flags_and_payloads(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)
+    end
+
+    def reload_feature_flag_definitions
+      @flags.reload_feature_flag_definitions
+    end
+
+    # ─── Messaging convenience ──────────────────────────────────────────────
+
+    def dispatch_message(**params)
+      @messaging.dispatch(**params)
+    end
+
+    # ─── LLM convenience ────────────────────────────────────────────────────
+
+    def capture_trace(**params)
+      @llm.capture_trace(**params)
+    end
+
+    # ─── Lifecycle ────────────────────────────────────────────────────────────
+
+    # Flush remaining events and stop the background flush timer.
+    def shutdown
+      @analytics.shutdown
+    end
+
+    private
+
+    def strip_nil(opts)
+      opts.each_with_object({}) do |(k, v), acc|
+        acc[k] = v unless v.nil?
+      end
+    end
+  end
+end

data/lib/billdogeng/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module BilldogEng
+  # Raised when an API request ultimately fails (after retries).
+  class Error < StandardError
+    # HTTP status code, or 0 for network/timeout failures.
+    attr_reader :status
+    # Machine-readable error code from the API envelope, if any.
+    attr_reader :code
+    # Raw response body (parsed if JSON, else text), if any.
+    attr_reader :body
+
+    def initialize(message, status: 0, code: nil, body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @body = body
+    end
+  end
+end