trevosdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a962376d1586309cd51a06b89ebc86bf1fd6e150c04e74aede22a6565685ec40
+  data.tar.gz: 30d9cc18e9c4b11a77230525f6402a6152dc3c21cb063ede29c3a7cc76fa4609
+SHA512:
+  metadata.gz: 82076d6c8de3bf5f47a40be0b6a75581a7e9a24e4f04e7cf09c8814e60c6e68244078a83c059fefea83ee4770694bf28938d9d97eef67bb86814f6ba24f85c8e
+  data.tar.gz: 18f482f337bb9d52d6c0bed6e505d4879fd8aacb5ccf96fdd5c652389a5c23cf4006935568c77eeec7bbc5b8a1efc0e2a25429f97e039549a0b7870792a4f72d

data/README.md

@@ -0,0 +1,31 @@
+# trevosdk
+
+Trevo server SDK for Ruby — deterministic variant assignment and event tracking
+for [Trevo](https://trevosdk.com) experiments. Zero dependencies; Ruby 3.2+.
+
+```sh
+gem install trevosdk
+```
+
+```ruby
+# config/initializers/trevosdk.rb (Rails) or anywhere at boot
+Trevosdk.init(ENV.fetch("TREVO_SECRET_KEY"))
+
+variant = Trevosdk.client.get_variant("checkout-cta", user_id: current_user.id)
+if variant == "treatment"
+  # alternate experience
+end
+
+Trevosdk.client.track("checkout_started", user_id: current_user.id, properties: {plan: "pro"})
+```
+
+`get_variant` reads an immutable in-memory config snapshot — no network call — safe
+from Rails controllers, Sidekiq jobs, and scripts alike. Config refresh and event
+delivery run on background threads; events flush at process exit, or deterministically
+via `flush` / `close`.
+
+Assignment is byte-identical to every other Trevo SDK: the same user gets the same
+variant in the browser and on the backend, verified against the shared conformance
+corpus.
+
+Full docs at [docs.trevosdk.com](https://docs.trevosdk.com).

data/lib/trevosdk/batcher.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "transport"
+
+module Trevosdk
+  # Bounded background delivery mirroring the node SDK's EventBatcher semantics.
+  class EventBatcher
+    def initialize(ingestion_url:, secret_key:, max_batch_size:, flush_interval_s:, transport:, on_error:)
+      @ingestion_url = ingestion_url
+      @secret_key = secret_key
+      @batch_size = [max_batch_size, SERVER_MAX_BATCH_SIZE].min
+      @flush_interval_s = flush_interval_s
+      @transport = transport
+      @on_error = on_error
+
+      @queue = []
+      @mutex = Mutex.new
+      @send_mutex = Mutex.new
+      @wake_mutex = Mutex.new
+      @wake_cv = ConditionVariable.new
+      @wake_flag = false
+      @stopped = false
+      @dropped = 0
+      @worker = nil
+    end
+
+    def start
+      return unless @worker.nil?
+      @worker = Thread.new { run }
+      @worker.name = "trevosdk-batcher"
+    end
+
+    def enqueue(event)
+      first_drop = false
+      over_batch = false
+      @mutex.synchronize do
+        return if @stopped
+        if @queue.length >= MAX_QUEUE_SIZE
+          # Drop oldest: an outage should cost the stalest events, not the newest.
+          @queue.shift
+          @dropped += 1
+          first_drop = @dropped == 1
+        end
+        @queue.push(event)
+        over_batch = @queue.length >= @batch_size
+      end
+      if first_drop
+        @on_error.call(RuntimeError.new("Trevo event queue full at #{MAX_QUEUE_SIZE}; dropping oldest events"))
+      end
+      wake! if over_batch
+    end
+
+    # Sends everything queued; raises on delivery failure so callers get a real guarantee.
+    def flush
+      @send_mutex.synchronize { drain }
+    end
+
+    # Stops the worker and flushes once; never raises — this runs from exit hooks.
+    def shutdown
+      @mutex.synchronize { @stopped = true }
+      wake!
+      @worker&.join(@flush_interval_s + 1)
+      @worker = nil
+      begin
+        flush
+      rescue => error
+        @on_error.call(error)
+      end
+    end
+
+    private
+
+    def wake!
+      @wake_mutex.synchronize do
+        @wake_flag = true
+        @wake_cv.signal
+      end
+    end
+
+    def run
+      loop do
+        @wake_mutex.synchronize do
+          @wake_cv.wait(@wake_mutex, @flush_interval_s) unless @wake_flag
+          @wake_flag = false
+        end
+        return if @mutex.synchronize { @stopped }
+        begin
+          flush
+        rescue => error
+          @on_error.call(error)
+        end
+      end
+    end
+
+    def drain
+      pending = @mutex.synchronize do
+        drained = @queue
+        @queue = []
+        drained
+      end
+
+      pending.each_slice(@batch_size).with_index do |batch, index|
+        status = begin
+          send_batch(batch)
+        rescue
+          nil
+        end
+        next if !status.nil? && (200..299).cover?(status)
+
+        start = index * @batch_size
+        requeued =
+          if retryable?(status)
+            pending[start..]
+          else
+            # A rejected batch will be rejected identically forever; drop it, keep the rest.
+            @on_error.call(
+              RuntimeError.new(
+                "Trevo dropped #{batch.length} event(s): ingestion rejected them with status #{status.inspect}"
+              )
+            )
+            pending[(start + batch.length)..]
+          end
+        @mutex.synchronize { @queue.unshift(*requeued) }
+        raise "Trevo event delivery failed with status #{status.inspect}"
+      end
+    end
+
+    def retryable?(status)
+      return true if status.nil?
+      return true if [408, 429].include?(status)
+      status >= 500
+    end
+
+    def send_batch(events)
+      # sentAt is stamped at send, so a batch re-queued through an outage stays correctable.
+      body = JSON.generate({events: events, sentAt: Time.now.utc.iso8601(3)})
+      response = @transport.call(
+        TransportRequest.new(
+          method: "POST",
+          url: @ingestion_url,
+          headers: Trevosdk.auth_headers(@secret_key),
+          body: body
+        )
+      )
+      response.status
+    end
+  end
+end

data/lib/trevosdk/client.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+require_relative "batcher"
+require_relative "core"
+require_relative "poller"
+require_relative "transport"
+require_relative "version"
+
+module Trevosdk
+  # Server client: deterministic assignment and event tracking for any Ruby runtime.
+  #
+  # Evaluation reads an immutable config snapshot and never touches the network,
+  # so calls are safe from Rails controllers, Sidekiq jobs, and scripts alike.
+  class Client
+    EXPOSURE_EVENT = "$experiment_exposure"
+
+    def initialize(secret_key, bootstrap_config: nil, config_url: CONFIG_URL,
+      ingestion_url: INGESTION_URL, alias_url: nil,
+      poll_interval_s: DEFAULT_POLL_INTERVAL_S, flush_interval_s: DEFAULT_FLUSH_INTERVAL_S,
+      max_batch_size: DEFAULT_MAX_BATCH_SIZE, force_variants: nil,
+      transport: nil, on_error: nil)
+      raise ArgumentError, "Trevosdk::Client requires a secret_key" if secret_key.to_s.empty?
+      if !bootstrap_config.nil? && !bootstrap_config.is_a?(Array)
+        raise ArgumentError,
+          "bootstrap_config must be an array of experiment configs — pass " \
+          'response["experiments"], not the whole config response'
+      end
+
+      @secret_key = secret_key
+      @transport = transport || DEFAULT_TRANSPORT
+      @on_error = on_error || ->(error) { warn("[Trevo] #{error.message}") }
+      @alias_url = alias_url || self.class.derive_alias_url(ingestion_url)
+
+      @experiments = (bootstrap_config || []).to_h { |config| [config["experimentKey"], config] }
+      @exposures = ExposureDeduper.new(SERVER_EXPOSURE_DEDUP_MAX_KEYS)
+      @exposures_mutex = Mutex.new
+      @forced = self.class.parse_force_variants(ENV[FORCE_VARIANTS_ENV])
+        .merge((force_variants || {}).transform_keys(&:to_s))
+
+      @batcher = EventBatcher.new(
+        ingestion_url: ingestion_url,
+        secret_key: secret_key,
+        max_batch_size: [1, max_batch_size].max,
+        flush_interval_s: [MIN_FLUSH_INTERVAL_S, flush_interval_s].max,
+        transport: @transport,
+        on_error: @on_error
+      )
+      @poller = ConfigPoller.new(
+        config_url: config_url,
+        secret_key: secret_key,
+        interval_s: [MIN_POLL_INTERVAL_S, poll_interval_s].max,
+        transport: @transport,
+        on_config: ->(configs) { swap_config(configs) },
+        on_error: @on_error
+      )
+
+      @start_mutex = Mutex.new
+      @started = false
+      @closed = false
+    end
+
+    # Alias lives on the same service as events, so an ingestion override must move alias too.
+    def self.derive_alias_url(ingestion_url)
+      return ALIAS_URL if ingestion_url == INGESTION_URL
+      trimmed = ingestion_url.sub(%r{/+\z}, "")
+      return "#{trimmed.delete_suffix("/events")}/alias" if trimmed.end_with?("/events")
+      ALIAS_URL
+    end
+
+    def self.parse_force_variants(raw)
+      return {} if raw.nil? || raw.empty?
+      raw.split(",").each_with_object({}) do |pair, parsed|
+        separator = pair.index(":")
+        next if separator.nil? || separator.zero? || separator == pair.length - 1
+        key = pair[...separator].strip
+        variant = pair[(separator + 1)..].strip
+        parsed[key] = variant unless key.empty? || variant.empty?
+      end
+    end
+
+    def get_variant(experiment_key, user_id: nil, anonymous_id: nil, track_exposure: true)
+      return Core::CONTROL_VARIANT if experiment_key.to_s.empty?
+      ensure_started
+
+      config = @experiments[experiment_key]
+
+      # Overrides win, but only for a variant the experiment has, and never
+      # record an exposure — see docs/sdk/bucketing-spec.md §6.
+      override = @forced[experiment_key]
+      if override && config && config["variants"].any? { |v| v["name"] == override }
+        return override
+      end
+
+      # An empty-string user_id must fall through to the anonymous id the
+      # browser is bucketing with.
+      bucketing_id = user_id.to_s.empty? ? anonymous_id : user_id
+      return Core::CONTROL_VARIANT if bucketing_id.to_s.empty? || config.nil?
+
+      variant = Core.assign_variant(bucketing_id, config)
+
+      if track_exposure
+        now_ms = (Time.now.to_f * 1000).to_i
+        should_log = @exposures_mutex.synchronize do
+          @exposures.should_log?(bucketing_id, experiment_key, variant, now_ms)
+        end
+        if should_log
+          enqueue_event(
+            EXPOSURE_EVENT, user_id, anonymous_id,
+            {"experimentKey" => experiment_key, "variantName" => variant}, nil
+          )
+        end
+      end
+
+      variant
+    end
+
+    def track(event_name, user_id: nil, anonymous_id: nil, properties: nil, insert_id: nil)
+      enqueue_event(event_name, user_id, anonymous_id, properties, insert_id)
+    end
+
+    def alias(anonymous_id, user_id)
+      ensure_started
+      if anonymous_id.to_s.empty? || user_id.to_s.empty?
+        raise ArgumentError, "alias requires both an anonymous_id and a user_id"
+      end
+
+      response = @transport.call(
+        TransportRequest.new(
+          method: "POST",
+          url: @alias_url,
+          headers: Trevosdk.auth_headers(@secret_key),
+          body: JSON.generate({anonymousId: anonymous_id, userId: user_id})
+        )
+      )
+      if response.status == 409
+        raise "Trevo alias rejected: anonymousId \"#{anonymous_id}\" is already linked to a different user"
+      end
+      raise "Trevo alias failed with status #{response.status}" unless (200..299).cover?(response.status)
+      nil
+    end
+
+    def ready(timeout_s = nil)
+      ensure_started
+      @poller.wait_ready(timeout_s)
+    end
+
+    def flush
+      @batcher.flush
+    end
+
+    def close
+      return if @closed
+      @closed = true
+      @poller.stop
+      @batcher.shutdown
+    end
+
+    private
+
+    def swap_config(configs)
+      @experiments = configs.to_h { |config| [config["experimentKey"], config] }
+    end
+
+    def ensure_started
+      return if @started
+      @start_mutex.synchronize do
+        return if @started || @closed
+        @batcher.start
+        @poller.start
+        at_exit { close }
+        @started = true
+      end
+    end
+
+    def enqueue_event(event_name, user_id, anonymous_id, properties, insert_id)
+      built = Core.build_event(
+        event_name,
+        timestamp: Time.now.utc.iso8601(3),
+        user_id: user_id,
+        anonymous_id: anonymous_id,
+        properties: properties,
+        sdk_version: "ruby-#{VERSION}",
+        # Stamped at enqueue so a redelivered batch is stored once.
+        insert_id: insert_id || SecureRandom.uuid
+      )
+      unless built.ok
+        @on_error.call(RuntimeError.new("Trevo track(\"#{event_name}\") ignored: #{built.reason}"))
+        return
+      end
+
+      ensure_started
+      @batcher.enqueue(built.event)
+    end
+  end
+end

data/lib/trevosdk/core.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Trevosdk
+  # Pure evaluation core — no I/O, no clock reads; time is a parameter.
+  # Frozen contract: must match packages/contracts/src/corpus/vectors.json exactly.
+  module Core
+    CONTROL_VARIANT = "control"
+    BUCKET_SPACE = 10_000
+    TREVO_ID_COOKIE = "trevo_id"
+
+    MAX_EVENT_NAME_LENGTH = 500
+    EVENT_NAME_RE = /\A[A-Za-z0-9_.$-]+\z/
+    MAX_PROPERTIES_BYTES = 8_192
+
+    EXPOSURE_DEDUP_WINDOW_MS = 600_000
+    EXPOSURE_DEDUP_MAX_KEYS = 1_000
+
+    FNV_OFFSET_BASIS_32 = 0x811c9dc5
+    FNV_PRIME_32 = 0x01000193
+    MASK_32 = 0xffffffff
+
+    ParseResult = Struct.new(:success, :experiments, :error)
+    BuildEventResult = Struct.new(:ok, :event, :reason)
+
+    module_function
+
+    # FNV-1a over UTF-16 code units (not bytes) — matches the reference JS SDK.
+    # Invalid bytes hash as U+FFFD instead of raising: such strings have no JS
+    # equivalent, so deterministic assignment beats crashing the request.
+    def fnv1a32(value)
+      hash = FNV_OFFSET_BASIS_32
+      units = value.encode(Encoding::UTF_16LE, invalid: :replace, undef: :replace).unpack("v*")
+      units.each do |unit|
+        hash = ((hash ^ unit) * FNV_PRIME_32) & MASK_32
+      end
+      hash
+    end
+
+    def assign_variant(bucketing_id, config, on_warn = nil)
+      experiment_key = config["experimentKey"]
+      variants = config["variants"]
+
+      if variants.empty?
+        on_warn&.call(%([TrevoSDK] Experiment "#{experiment_key}" has no variants. Returning "control".))
+        return CONTROL_VARIANT
+      end
+
+      total = variants.sum { |variant| variant["trafficSplit"] }
+      if (total - 100).abs > 0.01
+        on_warn&.call(
+          %([TrevoSDK] Experiment "#{experiment_key}" trafficSplit sums to #{total}, ) +
+            "expected 100. Assignment may be biased."
+        )
+      end
+
+      bucket = fnv1a32("#{bucketing_id}:#{experiment_key}") % BUCKET_SPACE
+
+      cumulative = 0
+      last_variant_name = nil
+      variants.each do |variant|
+        cumulative += variant["trafficSplit"] * 100
+        return variant["name"].to_s if bucket < cumulative
+        last_variant_name = variant["name"].to_s
+      end
+
+      last_variant_name || CONTROL_VARIANT
+    end
+
+    def valid_variant?(value)
+      return false unless value.is_a?(Hash)
+      name = value["name"]
+      split = value["trafficSplit"]
+      return false unless name.is_a?(String) && !name.empty?
+      # An integral float (50.0) is accepted because JS cannot distinguish it from 50.
+      split.is_a?(Integer) || (split.is_a?(Float) && split % 1 == 0)
+    end
+
+    def valid_experiment_config?(value)
+      return false unless value.is_a?(Hash)
+      key = value["experimentKey"]
+      variants = value["variants"]
+      return false unless key.is_a?(String) && !key.empty?
+      return false unless variants.is_a?(Array) && variants.length >= 2
+      variants.all? { |variant| valid_variant?(variant) }
+    end
+
+    def parse_config_response(body)
+      return ParseResult.new(false, [], "Response is not an object") unless body.is_a?(Hash)
+      experiments = body["experiments"]
+      return ParseResult.new(false, [], "Missing experiments array") unless experiments.is_a?(Array)
+      unless experiments.all? { |experiment| valid_experiment_config?(experiment) }
+        return ParseResult.new(false, [], "Invalid experiment config in response")
+      end
+      ParseResult.new(true, experiments, nil)
+    end
+
+    def build_event(event_name, timestamp:, user_id: nil, anonymous_id: nil,
+      properties: nil, sdk_version: nil, insert_id: nil)
+      unless event_name.is_a?(String) && !event_name.strip.empty?
+        return BuildEventResult.new(false, nil, "empty-name")
+      end
+      return BuildEventResult.new(false, nil, "name-too-long") if event_name.length > MAX_EVENT_NAME_LENGTH
+      return BuildEventResult.new(false, nil, "name-charset") unless EVENT_NAME_RE.match?(event_name)
+
+      snapshot = nil
+      unless properties.nil?
+        begin
+          serialized = JSON.generate(properties)
+        rescue JSON::NestingError, JSON::GeneratorError, SystemStackError
+          return BuildEventResult.new(false, nil, "properties-unserializable")
+        end
+        return BuildEventResult.new(false, nil, "properties-too-large") if serialized.length > MAX_PROPERTIES_BYTES
+        # Round trip both validates and deep-copies, isolating the caller from later mutation.
+        snapshot = JSON.parse(serialized)
+      end
+
+      if (user_id.nil? || user_id.empty?) && (anonymous_id.nil? || anonymous_id.empty?)
+        return BuildEventResult.new(false, nil, "no-identity")
+      end
+
+      event = {"event" => event_name}
+      event["userId"] = user_id unless user_id.nil?
+      event["anonymousId"] = anonymous_id unless anonymous_id.nil?
+      event["properties"] = snapshot unless snapshot.nil?
+      event["timestamp"] = timestamp
+      event["sdkVersion"] = sdk_version unless sdk_version.nil?
+      event["insertId"] = insert_id unless insert_id.nil?
+      BuildEventResult.new(true, event, nil)
+    end
+  end
+
+  # Dedup semantics are corpus-frozen; the eviction strategy under memory pressure is not.
+  class ExposureDeduper
+    def initialize(max_keys = Core::EXPOSURE_DEDUP_MAX_KEYS)
+      @seen = {}
+      @max_keys = max_keys
+    end
+
+    def should_log?(identity, experiment_key, variant_name, now_ms)
+      if @seen.length >= @max_keys
+        @seen.delete_if { |_, ts| now_ms - ts >= Core::EXPOSURE_DEDUP_WINDOW_MS }
+        @seen.clear if @seen.length >= @max_keys
+      end
+
+      key = "#{identity}:#{experiment_key}:#{variant_name}"
+      last = @seen[key]
+      return false if !last.nil? && now_ms - last < Core::EXPOSURE_DEDUP_WINDOW_MS
+
+      @seen[key] = now_ms
+      true
+    end
+
+    def clear
+      @seen.clear
+    end
+  end
+end

data/lib/trevosdk/poller.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "core"
+require_relative "transport"
+
+module Trevosdk
+  # Fetches experiment config on an interval and hands parsed snapshots to the client.
+  class ConfigPoller
+    def initialize(config_url:, secret_key:, interval_s:, transport:, on_config:, on_error:)
+      @config_url = config_url
+      @secret_key = secret_key
+      @interval_s = interval_s
+      @transport = transport
+      @on_config = on_config
+      @on_error = on_error
+
+      @etag = nil
+      @stop_mutex = Mutex.new
+      @stop_cv = ConditionVariable.new
+      @stopped = false
+      @ready_mutex = Mutex.new
+      @ready_cv = ConditionVariable.new
+      @ready = false
+      @worker = nil
+    end
+
+    def start
+      return unless @worker.nil?
+      @worker = Thread.new { run }
+      @worker.name = "trevosdk-poller"
+    end
+
+    def wait_ready(timeout_s = nil)
+      @ready_mutex.synchronize do
+        @ready_cv.wait(@ready_mutex, timeout_s) unless @ready
+        @ready
+      end
+    end
+
+    def stop
+      @stop_mutex.synchronize do
+        @stopped = true
+        @stop_cv.signal
+      end
+      @worker&.join(1)
+      @worker = nil
+    end
+
+    private
+
+    def run
+      until @stop_mutex.synchronize { @stopped }
+        begin
+          poll
+        rescue => error
+          @on_error.call(error)
+        ensure
+          # Ready resolves after the first attempt, success or not, so callers
+          # waiting on it are never wedged by a dead config endpoint.
+          signal_ready
+        end
+        @stop_mutex.synchronize { @stop_cv.wait(@stop_mutex, @interval_s) unless @stopped }
+      end
+    end
+
+    def signal_ready
+      @ready_mutex.synchronize do
+        @ready = true
+        @ready_cv.broadcast
+      end
+    end
+
+    def poll
+      headers = Trevosdk.auth_headers(@secret_key)
+      headers["If-None-Match"] = @etag unless @etag.nil?
+      response = @transport.call(
+        TransportRequest.new(method: "GET", url: @config_url, headers: headers)
+      )
+      return if response.status == 304
+      unless (200..299).cover?(response.status)
+        raise "Trevo config fetch failed with status #{response.status}"
+      end
+
+      parsed = Core.parse_config_response(response.json)
+      raise "Trevo config response invalid: #{parsed.error}" unless parsed.success
+
+      etag = (response.headers || {}).transform_keys(&:downcase)["etag"]
+      @etag = etag unless etag.nil? || etag.empty?
+      @on_config.call(parsed.experiments)
+    end
+  end
+end

data/lib/trevosdk/transport.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Trevosdk
+  CONFIG_URL = "https://api.trevosdk.com/v1/config"
+  INGESTION_URL = "https://ingest.trevosdk.com/v1/events"
+  ALIAS_URL = "https://ingest.trevosdk.com/v1/alias"
+
+  DEFAULT_POLL_INTERVAL_S = 60.0
+  MIN_POLL_INTERVAL_S = 10.0
+  DEFAULT_FLUSH_INTERVAL_S = 5.0
+  MIN_FLUSH_INTERVAL_S = 0.5
+  DEFAULT_MAX_BATCH_SIZE = 50
+  SERVER_MAX_BATCH_SIZE = 500
+  MAX_QUEUE_SIZE = 10_000
+  REQUEST_TIMEOUT_S = 10.0
+  SERVER_EXPOSURE_DEDUP_MAX_KEYS = 100_000
+  FORCE_VARIANTS_ENV = "TREVO_FORCE_VARIANTS"
+
+  # No custom initialize: Ruby 3.2 structs accept keywords only through the default one.
+  TransportRequest = Struct.new(:method, :url, :headers, :body, :timeout_s)
+
+  TransportResponse = Struct.new(:status, :body, :headers) do
+    def json
+      JSON.parse(body.to_s)
+    end
+  end
+
+  DEFAULT_TRANSPORT = lambda do |request|
+    uri = URI.parse(request.url)
+    timeout = request.timeout_s || REQUEST_TIMEOUT_S
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == "https"
+    http.open_timeout = timeout
+    http.read_timeout = timeout
+    http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+    response = http.send_request(request.method, uri.request_uri, request.body, request.headers)
+    TransportResponse.new(
+      status: response.code.to_i,
+      body: response.body.to_s,
+      headers: response.each_header.to_h
+    )
+  end
+
+  module_function
+
+  def auth_headers(secret_key)
+    {"Content-Type" => "application/json", "Authorization" => "Bearer #{secret_key}"}
+  end
+end

data/lib/trevosdk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Trevosdk
+  VERSION = "0.1.0"
+end

data/lib/trevosdk.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "trevosdk/client"
+require_relative "trevosdk/core"
+require_relative "trevosdk/version"
+
+module Trevosdk
+  class << self
+    # Process-wide singleton for the common one-client-per-app setup
+    # (e.g. a Rails config/initializers/trevosdk.rb).
+    def init(secret_key, **options)
+      @client&.close
+      @client = Client.new(secret_key, **options)
+    end
+
+    def client
+      @client || raise("Trevosdk.init has not been called")
+    end
+
+    def close
+      @client&.close
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: trevosdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Trevo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-17 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/trevosdk.rb
+- lib/trevosdk/batcher.rb
+- lib/trevosdk/client.rb
+- lib/trevosdk/core.rb
+- lib/trevosdk/poller.rb
+- lib/trevosdk/transport.rb
+- lib/trevosdk/version.rb
+homepage: https://trevosdk.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://trevosdk.com
+  documentation_uri: https://docs.trevosdk.com
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Trevo server SDK for Ruby — deterministic variant assignment and event tracking
+test_files: []