billdogeng 1.0.2.pre.beta.3

data/lib/billdogeng/murmur.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module BilldogEng
+  # murmurhash3 (32-bit, x86, seed-able) — ported verbatim from the canonical
+  # web reference `packages/ab-testing/src/ABTest.ts`.
+  #
+  # This is the cross-platform bucketing primitive for local feature-flag
+  # evaluation. The exact same algorithm runs on web / iOS / Android / every
+  # server SDK so that `murmurhash3("{key}.{distinctId}") % 100` produces an
+  # identical bucket everywhere — a user is deterministically in or out of a
+  # rollout regardless of which platform evaluated the flag.
+  #
+  # Implementation notes (must not change without re-pinning the vectors):
+  # - UTF-8 bytes
+  # - 32-bit multiply with truncation (`Math.imul` analogue via UINT32_MASK)
+  # - unsigned 32-bit result (`h1 >>> 0` analogue)
+  module Murmur
+    UINT32_MASK = 0xFFFFFFFF
+    C1 = 0xCC9E2D51
+    C2 = 0x1B873593
+
+    module_function
+
+    # 32-bit multiply matching JS `Math.imul` semantics: multiply, truncate to
+    # the low 32 bits. (We keep results unsigned; the algebra is identical to
+    # the signed two's-complement arithmetic in the JS/iOS/Android references.)
+    def imul(a, b)
+      (a * b) & UINT32_MASK
+    end
+
+    # Left rotate a 32-bit value.
+    def rotl32(x, r)
+      ((x << r) | (x >> (32 - r))) & UINT32_MASK
+    end
+
+    # @param key  [String]  arbitrary input (hashed as UTF-8 bytes)
+    # @param seed [Integer] hash seed (default 0)
+    # @return     [Integer] unsigned 32-bit hash
+    def murmurhash3(key, seed = 0)
+      key_bytes = key.to_s.dup.force_encoding(Encoding::UTF_8).bytes
+      h1 = seed & UINT32_MASK
+      len = key_bytes.length
+      blocks = len / 4
+
+      blocks.times do |i|
+        k1 = (key_bytes[i * 4] |
+              (key_bytes[i * 4 + 1] << 8) |
+              (key_bytes[i * 4 + 2] << 16) |
+              (key_bytes[i * 4 + 3] << 24)) & UINT32_MASK
+        k1 = imul(k1, C1)
+        k1 = rotl32(k1, 15)
+        k1 = imul(k1, C2)
+        h1 ^= k1
+        h1 = rotl32(h1, 13)
+        h1 = (imul(h1, 5) + 0xE6546B64) & UINT32_MASK
+      end
+
+      k1 = 0
+      remainder = len % 4
+      offset = blocks * 4
+      # Intentional fall-through, mirroring the C / JS switch.
+      k1 ^= key_bytes[offset + 2] << 16 if remainder >= 3
+      k1 ^= key_bytes[offset + 1] << 8  if remainder >= 2
+      if remainder >= 1
+        k1 = (k1 ^ key_bytes[offset]) & UINT32_MASK
+        k1 = imul(k1, C1)
+        k1 = rotl32(k1, 15)
+        k1 = imul(k1, C2)
+        h1 ^= k1
+      end
+
+      h1 ^= len
+      h1 ^= h1 >> 16
+      h1 = imul(h1, 0x85EBCA6B)
+      h1 ^= h1 >> 13
+      h1 = imul(h1, 0xC2B2AE35)
+      h1 ^= h1 >> 16
+      h1 & UINT32_MASK
+    end
+
+    # Deterministic 0..99 bucket for a `"{key}.{distinctId}"` style seed.
+    def bucket_of(seed)
+      murmurhash3(seed) % 100
+    end
+  end
+end

data/lib/billdogeng/quota_limited.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BilldogEng
+  # Client half of the `quota_limited` contract.
+  #
+  # The ingestion endpoints answer an exhausted allowance with HTTP 200 and a
+  # TOP-LEVEL `quota_limited` array naming the drained meters, rather than an
+  # error status — so a customer's app is never broken by their BillDog meter
+  # filling up (see supabase/functions/_shared/quota-limited.ts for the
+  # reasoning; PostHog's capture endpoint does the same).
+  #
+  # The cost of that choice is that a 2xx no longer proves the data was stored.
+  # Every caller that treats 2xx as success MUST consult this, or it will keep
+  # transmitting into a closed meter and report success for discarded data.
+  #
+  # Mirrors packages/core/src/quotaLimited.ts (canonical) and the Android
+  # AnalyticsUploadPolicy helpers of the same name.
+  module QuotaLimited
+    module_function
+
+    # The drained meters named by a parsed 2xx body, or [] when it is not a refusal.
+    #
+    # Deliberately tolerant: the argument is a response body the SDK does not
+    # control, so anything unexpected reads as "not limited" rather than raising
+    # inside the flush path.
+    def metrics(body)
+      return [] unless body.is_a?(Hash)
+
+      limited = body["quota_limited"] || body[:quota_limited]
+      return [] unless limited.is_a?(Array)
+
+      limited.map(&:to_s).reject(&:empty?)
+    end
+
+    # True when a parsed 2xx body reports that its payload was dropped for quota reasons.
+    def limited?(body)
+      !metrics(body).empty?
+    end
+
+    # One-line explanation for a developer's log — never for an end user, since it
+    # describes the ACCOUNT OWNER's billing state. Prefers the server's own prose and
+    # falls back to naming the meters, so the reason a client went quiet is never a
+    # bare boolean.
+    def reason(body)
+      message = body.is_a?(Hash) ? (body["message"] || body[:message]) : nil
+      return message if message.is_a?(String) && !message.empty?
+
+      names = metrics(body)
+      "allowance exhausted for: #{names.empty? ? "unknown" : names.join(", ")} — this data was not stored"
+    end
+  end
+end

data/lib/billdogeng/surveys.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module BilldogEng
+  # Surveys DATA API (no UI rendering). Wraps the `bdsurvey-*` edge functions.
+  #
+  # Lifecycle: list → fetch → start → record_partial* → submit (or abandon).
+  # The same `:idempotency_key` SHOULD be carried across start and submit so
+  # retries are safe.
+  #
+  # Answers mirror the bdsurvey-submit shape:
+  #   { question_id:, choice_id:, answer_text:, answer_number:, answer_json: }
+  #
+  # Context accepts (all optional): :respondent_id, :customer_id, :anonymous_id,
+  #   :session_id, :platform, :device_info, :duration_ms, :context,
+  #   :collector_id, :collector_type, :idempotency_key
+  class Surveys
+    def initialize(transport, api_key:)
+      @transport = transport
+      @api_key = api_key
+    end
+
+    # List active surveys eligible for the (optionally identified) user.
+    def list(distinct_id = nil, anonymous_id = nil)
+      body = { "api_key" => @api_key }
+      body["customer_id"] = distinct_id if distinct_id
+      body["anonymous_id"] = anonymous_id if anonymous_id
+      data = @transport.request(path: "/bdsurvey-list", body: body, headers: auth_header, gzip: false)
+      (data.is_a?(Hash) ? data["surveys"] : nil) || []
+    end
+
+    # Fetch the full configuration for a single survey.
+    def fetch(survey_id, distinct_id = nil, anonymous_id = nil)
+      body = { "api_key" => @api_key, "survey_id" => survey_id }
+      body["customer_id"] = distinct_id if distinct_id
+      body["anonymous_id"] = anonymous_id if anonymous_id
+      @transport.request(path: "/bdsurvey-fetch", body: body, headers: auth_header, gzip: false)
+    end
+
+    # Begin a survey response. Returns the body containing `respondent_id`.
+    def start(survey_id, context = {})
+      @transport.request(
+        path: "/bdsurvey-submit",
+        body: build_body("start", survey_id, nil, context),
+        headers: auth_header,
+        gzip: false,
+      )
+    end
+
+    # Progressively persist a partial set of answers under an in-progress respondent.
+    def record_partial(survey_id, respondent_id, answers, context = {})
+      ctx = context.merge(respondent_id: respondent_id)
+      @transport.request(
+        path: "/bdsurvey-submit",
+        body: build_body("partial", survey_id, answers, ctx),
+        headers: auth_header,
+        gzip: false,
+      )
+    end
+
+    # Submit the final answers, completing the response.
+    def submit(survey_id, answers, context = {})
+      @transport.request(
+        path: "/bdsurvey-submit",
+        body: build_body("submit", survey_id, answers, context),
+        headers: auth_header,
+        gzip: false,
+      )
+    end
+
+    # Mark an in-progress response as abandoned.
+    def abandon(survey_id, respondent_id)
+      @transport.request(
+        path: "/bdsurvey-submit",
+        body: build_body("abandon", survey_id, nil, respondent_id: respondent_id),
+        headers: auth_header,
+        gzip: false,
+      )
+    end
+
+    private
+
+    def auth_header
+      { "X-BillDog-API-Key" => @api_key }
+    end
+
+    def build_body(action, survey_id, answers, context)
+      ctx = context || {}
+      body = {
+        "action" => action,
+        "api_key" => @api_key,
+        "survey_id" => survey_id,
+      }
+      body["answers"] = normalize_answers(answers) if answers
+      body["respondent_id"]  = ctx[:respondent_id]  if ctx[:respondent_id]
+      body["customer_id"]    = ctx[:customer_id]    if ctx[:customer_id]
+      body["anonymous_id"]   = ctx[:anonymous_id]   if ctx[:anonymous_id]
+      body["session_id"]     = ctx[:session_id]     if ctx[:session_id]
+      body["platform"]       = ctx[:platform]       if ctx[:platform]
+      body["device_info"]    = ctx[:device_info]    if ctx[:device_info]
+      body["duration_ms"]    = ctx[:duration_ms]    unless ctx[:duration_ms].nil?
+      body["context"]        = ctx[:context]        if ctx[:context]
+      body["collector_id"]   = ctx[:collector_id]   if ctx[:collector_id]
+      body["collector_type"] = ctx[:collector_type] if ctx[:collector_type]
+      body["idempotency_key"] = ctx[:idempotency_key] if ctx[:idempotency_key]
+      body
+    end
+
+    # Answers may arrive symbol- or string-keyed; emit string keys on the wire.
+    def normalize_answers(answers)
+      Array(answers).map do |a|
+        next a unless a.is_a?(Hash)
+
+        a.each_with_object({}) { |(k, v), acc| acc[k.is_a?(Symbol) ? k.to_s : k] = v }
+      end
+    end
+  end
+end

data/lib/billdogeng/targeting.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "set"
+require "date"
+
+module BilldogEng
+  # targeting.rb — the canonical audience-rule evaluator, ported from the backend.
+  #
+  # This is a port of `evaluateTargetingRulePure` + `compare` in
+  # `supabase/functions/_shared/edge-serving/pure.ts`. It is pinned to
+  # tests/fixtures/flag-targeting.json, which is GENERATED FROM that backend evaluator. It is never
+  # checked against another SDK — nine hand-ports of the murmur hash once all agreed with each other and
+  # all disagreed with the server, for months, precisely because each SDK's tests were written against a
+  # sibling SDK.
+  #
+  # WHY THIS EXISTS. The SDK previously received a flat `{attribute, operator, value}` array, which could
+  # express none of: an OR combinator, a date window, a paused rule, group membership, or most of the
+  # operator set. Every flag using one of those was deferred to the server even though the SDK held
+  # everything needed to answer it. That flat shape was also a SECOND condition DSL, duplicated across
+  # nine SDKs. It is gone: the SDK now receives the rule verbatim in the one canonical DSL and resolves
+  # it here.
+  #
+  # THE COLD CONTRACT. Some condition types (`segment`, `cohort`, `survey_answer`,
+  # `event_fired_in_window`, `group_property`) are answerable only by querying the database. We cannot
+  # resolve them and we must not guess: a failed lookup silently reading as "no match" is how targeting
+  # breaks quietly. Those conditions return COLD, which propagates to `Verdict#cold`, and the caller falls
+  # back to the server. In practice the backend already marks such flags `requires_server_evaluation` so
+  # they never reach this code — the COLD path here is the belt to that braces, and it fails SAFE.
+  module Targeting
+    # DB-backed condition types. Not resolvable in-process. Mirrors COLD_CONDITION_TYPES in pure.ts.
+    #
+    # Group PROPERTIES read the `groups` table. Group MEMBERSHIP ("group") does not — it comes from the
+    # caller-supplied groups map — so it stays purely evaluable.
+    COLD_CONDITION_TYPES = Set.new(
+      %w[segment cohort survey_answer event_fired_in_window group_property],
+    ).freeze
+
+    # Internal sentinel for a condition that only the database can answer.
+    COLD = :__billdog_cold__
+
+    # The result of evaluating a rule.
+    #
+    # `cold` is NOT `matched == false`: "we cannot decide here" and "this user is not in the audience"
+    # are different answers, and collapsing the former into the latter is how targeting breaks quietly.
+    # A cold verdict means the caller MUST re-resolve against the server.
+    Verdict = Struct.new(:matched, :cold) do
+      def matched?
+        matched ? true : false
+      end
+
+      def cold?
+        cold ? true : false
+      end
+
+      # Destructuring aid: `matched, cold = verdict.to_a`
+      def to_a
+        [matched, cold]
+      end
+    end
+
+    module_function
+
+    # Operator comparison — byte-for-byte port of `compare()` in pure.ts.
+    # This is the SDK's ONE operator matcher; nothing else may re-implement it.
+    def compare(operator, actual, expected)
+      actual_string = to_comparable(actual)
+
+      return !actual_string.nil? && !actual_string.empty? if operator == "exists"
+      return actual_string.nil? || actual_string.empty? if operator == "not_exists"
+      return false if actual_string.nil?
+
+      case operator
+      when "is", "equals"
+        actual_string == js_string(expected)
+      when "is_not", "not_equals"
+        actual_string != js_string(expected)
+      when "any_of"
+        expected.is_a?(Array) && expected.map { |e| js_string(e) }.include?(actual_string)
+      when "not_any_of"
+        expected.is_a?(Array) && !expected.map { |e| js_string(e) }.include?(actual_string)
+      when "contains"
+        actual_string.include?(js_string(expected))
+      when "not_contains"
+        !actual_string.include?(js_string(expected))
+      when "greater_than", "gt"
+        compare_date_or_number(actual, expected) { |a, b| a > b }
+      when "less_than", "lt"
+        compare_date_or_number(actual, expected) { |a, b| a < b }
+      when "greater_than_or_equal", "gte"
+        compare_date_or_number(actual, expected) { |a, b| a >= b }
+      when "less_than_or_equal", "lte"
+        compare_date_or_number(actual, expected) { |a, b| a <= b }
+      else
+        false
+      end
+    end
+
+    # Evaluate an audience rule against a context.
+    #
+    # @param rule [Hash] the canonical rule: status / enabled / start_date / end_date / segment_ids /
+    #   conditions {logic, rules}. String- or symbol-keyed.
+    # @param ctx [Hash] country / platform / app_version / sdk_version / custom_attributes / groups /
+    #   experiment_variants. String- or symbol-keyed.
+    # @return [Verdict] `matched` when fully determined from context; `cold` when a DB-backed condition is
+    #   load-bearing and the caller MUST re-resolve via the server. Note an OR rule already satisfied by a
+    #   context condition is decided WITHOUT the server, even if it also contains a DB-backed condition.
+    def evaluate_targeting_rule(rule, ctx)
+      rule = {} unless rule.is_a?(Hash)
+      status = dig_key(rule, "status")
+      enabled = dig_key(rule, "enabled")
+      return Verdict.new(false, false) if enabled == false || status == "paused" || status == "archived"
+
+      now = Time.now
+      start_date = dig_key(rule, "start_date")
+      end_date = dig_key(rule, "end_date")
+      return Verdict.new(false, false) if start_date && parse_boundary(start_date, now) > now
+      return Verdict.new(false, false) if end_date && parse_boundary(end_date, now) < now
+
+      # Legacy `segment_ids` — fail CLOSED. These are a DB-backed allow-list we cannot read, and treating
+      # them as absent would hand the flag to everyone.
+      segment_ids = dig_key(rule, "segment_ids")
+      return Verdict.new(false, false) if segment_ids.is_a?(Array) && !segment_ids.empty?
+
+      conditions = dig_key(rule, "conditions")
+      conditions = {} unless conditions.is_a?(Hash)
+      rules = dig_key(conditions, "rules")
+      rules = [] unless rules.is_a?(Array)
+      logic = dig_key(conditions, "logic") == "OR" ? "OR" : "AND"
+      return Verdict.new(true, false) if rules.empty?
+
+      saw_cold = false
+      pure_results = []
+      rules.each do |condition|
+        r = evaluate_condition(condition, ctx)
+        if r == COLD
+          saw_cold = true
+        else
+          pure_results << r
+        end
+      end
+
+      if logic == "OR"
+        return Verdict.new(true, false) if pure_results.any? { |r| r }
+
+        return saw_cold ? Verdict.new(false, true) : Verdict.new(false, false)
+      end
+
+      # AND
+      return Verdict.new(false, false) if pure_results.any? { |r| r == false }
+
+      saw_cold ? Verdict.new(false, true) : Verdict.new(true, false)
+    end
+
+    # ─── Internals ────────────────────────────────────────────────────────────
+
+    # @return [true, false, COLD]
+    def evaluate_condition(condition, ctx)
+      return false unless condition.is_a?(Hash)
+
+      type = dig_key(condition, "type")
+      operator = dig_key(condition, "operator")
+      value = dig_key(condition, "value")
+
+      return COLD if COLD_CONDITION_TYPES.include?(type)
+
+      case type
+      when "group"
+        # Group MEMBERSHIP is resolvable from the caller-supplied groups map alone.
+        group_type = dig_key(condition, "group_type") || dig_key(condition, "field")
+        return false unless group_type
+
+        compare(operator, dig_key(dig_key(ctx, "groups"), group_type), value)
+      when "experiment_variant"
+        experiment_id = dig_key(condition, "field") || dig_key(condition, "attribute_key")
+        variants = dig_key(ctx, "experiment_variants")
+        return false if experiment_id.nil? || variants.nil?
+
+        compare(operator, dig_key(variants, experiment_id), value)
+      when "attribute", "custom_attribute"
+        key = dig_key(condition, "field") || dig_key(condition, "attribute_key")
+        return false unless key
+
+        compare(operator, dig_key(dig_key(ctx, "custom_attributes"), key), value)
+      when "country", "platform", "app_version", "sdk_version"
+        compare(operator, dig_key(ctx, type), value)
+      when "subscription_status"
+        compare(operator, dig_key(dig_key(ctx, "custom_attributes"), "subscription_status"), value)
+      when "entitlement"
+        compare(operator, dig_key(dig_key(ctx, "custom_attributes"), "entitlement_id"), value)
+      else
+        # Derived/unknown types yield false, matching the backend.
+        false
+      end
+    end
+
+    # Hash lookup tolerant of string OR symbol keys — definitions may arrive either way (the wire is JSON;
+    # a Ruby caller injecting definitions by hand naturally writes symbols).
+    def dig_key(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      return hash[key] if hash.key?(key)
+
+      if key.is_a?(String)
+        sym = key.to_sym
+        return hash[sym] if hash.key?(sym)
+      elsif key.is_a?(Symbol)
+        str = key.to_s
+        return hash[str] if hash.key?(str)
+      end
+      nil
+    end
+
+    # String(value) with nil for nil/undefined — mirrors pure.ts `toComparable`.
+    def to_comparable(value)
+      value.nil? ? nil : js_string(value)
+    end
+
+    # JS `String(x)` semantics for the shapes that reach us from JSON.
+    def js_string(value)
+      return "null" if value.nil?
+      return value.join(",") if value.is_a?(Array)
+
+      value.to_s
+    end
+
+    # ISO date-or-number comparison (mirrors the pure.ts gt/lt/gte/lte branches):
+    # if BOTH parse as dates, compare epoch ms; else compare numbers.
+    def compare_date_or_number(actual, expected)
+      act_date = try_parse_date(actual)
+      exp_date = try_parse_date(expected)
+      if act_date && exp_date
+        yield(act_date, exp_date)
+      else
+        # The backend does Number(STRING(actual)) — it stringifies FIRST. That is not a detail: it makes
+        # Number(String(true)) == Number("true") == NaN, so a boolean attribute never satisfies an
+        # ordering rule. Converting the RAW value instead gives true -> 1.0, which quietly puts every
+        # boolean-valued user on the WRONG side of the threshold. `expected` stays raw, because JS applies
+        # Number() to it directly (Number(true) IS 1).
+        yield(to_number(js_string(actual)), to_number(expected))
+      end
+    end
+
+    # Date detection = a string matching ^\d{4}-\d{2}-\d{2} AND a valid parse, so a plain number like "10"
+    # is never mistaken for a date. Returns epoch ms, or nil. Mirrors pure.ts `tryParseDate`.
+    def try_parse_date(value)
+      return (value.to_time.to_f * 1000).to_i if value.is_a?(DateTime) || value.is_a?(Date)
+      return (value.to_f * 1000).to_i if value.is_a?(Time)
+      return nil unless value.is_a?(String) && value =~ /\A\d{4}-\d{2}-\d{2}/
+
+      begin
+        (DateTime.parse(value).to_time.to_f * 1000).to_i
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+
+    # JS `Number(x)` semantics: an empty/blank string is 0, anything unparseable is NaN (and every
+    # comparison against NaN is false, in Ruby exactly as in JS).
+    def to_number(value)
+      return 1.0 if value == true
+      return 0.0 if value == false
+      return 0.0 if value.is_a?(String) && value.strip.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      Float::NAN
+    end
+
+    # A rule's start/end boundary. Anything unparseable is treated as absent (never blocks the rule),
+    # matching `new Date(x)` producing an Invalid Date, whose comparisons are all false.
+    def parse_boundary(value, now)
+      ms = try_parse_date(value)
+      return now if ms.nil? # unparseable → neither in the future nor in the past
+
+      Time.at(ms / 1000.0)
+    end
+  end
+end