convert_sdk 1.0.0

data/lib/convert_sdk/data_store_manager.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # The single persistence port every manager flows through.
+  #
+  # +DataStoreManager+ wraps a duck-typed *store* (anything responding to
+  # +#get(key)+ / +#set(key, value)+) and is the ONLY object that holds a raw
+  # store reference — managers (config caching in Story 2.7, sticky bucketing in
+  # 2.11, goal dedup in 4.3) never touch a store directly. This gives the SDK
+  # one place to enforce three guarantees:
+  #
+  # 1. *Validation at wiring time.* The supplied store is duck-type-checked once,
+  #    at construction. A non-conforming store is rejected with a logged error
+  #    and replaced by a {Stores::MemoryStore} — wiring NEVER raises and NEVER
+  #    accepts a broken store. (The JS SDK's +isValidDataStore+ checks only that
+  #    +get+/+set+ are functions, with no arity enforcement; this port matches
+  #    that contract exactly. Unlike JS — which leaves its data store undefined
+  #    on invalid input — this Ruby port intentionally falls back to a working
+  #    MemoryStore, because a Ruby process must never crash on SDK wiring errors.)
+  #
+  # 2. *Never-crash passthrough.* {#get} / {#set} rescue +StandardError+ from a
+  #    user-supplied store and log it; a raising store degrades to +nil+ (get) or
+  #    a no-op (set) instead of crashing the host.
+  #
+  # 3. *Atomic visitor-data merge.* {#merge_visitor_data} runs the whole
+  #    read-modify-write cycle inside a manager-level mutex, so a compound
+  #    "read current state, decide, write" operation is atomic by construction.
+  #    Goal dedup (Story 4.3) builds its check-then-mark on this guarantee.
+  #
+  # == One store, two tenants
+  #
+  # A single store instance backs both config caching and visitor data. Keys are
+  # namespaced so the two never collide: config entries use
+  # +convert_sdk.config.{sdk_key}+ ({#config_key}) and visitor entries use
+  # +{account_id}-{project_id}-{visitor_id}+ ({#visitor_key}, byte-identical to
+  # the JS +getStoreKey+ format). The two key shapes are structurally disjoint.
+  #
+  # == StoreData
+  #
+  # Visitor data is a string-keyed hash of the JS +StoreData+ shape —
+  # +{"bucketing" => {...}, "segments" => {...}, "goals" => {...}}+ (plus
+  # +"locations"+). Everything stored is string-keyed (wire-world); no symbols
+  # appear in stored structures.
+  #
+  # == Thread safety
+  #
+  # The merge cycle is guarded by +@merge_mutex+. The default {Stores::MemoryStore}
+  # adds its own internal lock, so in-process merges are atomic. For external
+  # stores (e.g. +RedisStore+, Story 2.2) the same code path runs, but
+  # cross-process merge atomicity is store-dependent and must be provided by the
+  # backing store.
+  class DataStoreManager
+    # Methods a store must respond to (JS +isValidDataStore+ contract — presence
+    # only, no arity check).
+    REQUIRED_STORE_METHODS = %i[get set].freeze
+
+    # @return [Object] the validated backing store (the supplied store, or a
+    #   {Stores::MemoryStore} fallback).
+    attr_reader :store
+
+    # @param store [Object, nil] a duck-typed store responding to +get+/+set+.
+    #   +nil+ or an invalid store falls back to a new {Stores::MemoryStore}.
+    # @param log_manager [LogManager] injected logger for validation/passthrough
+    #   diagnostics.
+    def initialize(log_manager:, store: nil)
+      @log_manager = log_manager
+      @store = resolve_store(store)
+      # Thread safety: guarded by @merge_mutex.
+      @merge_mutex = Thread::Mutex.new
+    end
+
+    # Read the value stored under +key+. A raising store is contained: the error
+    # is logged and +nil+ is returned.
+    #
+    # @param key [String]
+    # @return [Object, nil]
+    def get(key)
+      @store.get(key)
+    rescue StandardError => e
+      @log_manager.error("DataStoreManager#get: store raised (#{e.message})")
+      nil
+    end
+
+    # Store +value+ under +key+. A raising store is contained: the error is
+    # logged and the call is a no-op.
+    #
+    # @param key [String]
+    # @param value [Object]
+    # @return [void]
+    def set(key, value)
+      @store.set(key, value)
+      nil
+    rescue StandardError => e
+      @log_manager.error("DataStoreManager#set: store raised (#{e.message})")
+      nil
+    end
+
+    # Build the visitor-data store key — byte-identical to the JS
+    # +getStoreKey+ format +`${accountId}-${projectId}-${visitorId}`+. This is
+    # the SINGLE construction site for visitor keys.
+    #
+    # @param account_id [String]
+    # @param project_id [String]
+    # @param visitor_id [String]
+    # @return [String]
+    def visitor_key(account_id, project_id, visitor_id)
+      "#{account_id}-#{project_id}-#{visitor_id}"
+    end
+
+    # Build the config-cache store key. SINGLE construction site for config keys.
+    #
+    # @param sdk_key [String]
+    # @return [String]
+    def config_key(sdk_key)
+      "convert_sdk.config.#{sdk_key}"
+    end
+
+    # Atomically read-modify-write a visitor's +StoreData+.
+    #
+    # The entire cycle — read current data, yield it to the block, deep-merge
+    # the block's returned partial, write the result — runs inside
+    # +@merge_mutex+, so it is atomic by construction. The block receives the
+    # current stored data (or +{}+ for a first write) and returns a +StoreData+
+    # partial to merge in; this lets a caller inspect current state and decide
+    # what to write atomically (the substrate for Story 4.3's check-then-mark
+    # goal dedup).
+    #
+    # Merge semantics match the JS +objectDeepMerge+: nested string-keyed hashes
+    # merge recursively, arrays union (deduped, new values first), and scalars
+    # from the partial win.
+    #
+    # @param account_id [String]
+    # @param project_id [String]
+    # @param visitor_id [String]
+    # @yieldparam current [Hash] the current stored +StoreData+ (or +{}+).
+    # @yieldreturn [Hash] the +StoreData+ partial to merge in.
+    # @return [Hash] the merged, persisted +StoreData+.
+    def merge_visitor_data(account_id, project_id, visitor_id)
+      key = visitor_key(account_id, project_id, visitor_id)
+      @merge_mutex.synchronize do
+        current = get(key) || {}
+        partial = yield(current)
+        merged = deep_merge(current, partial || {})
+        set(key, merged)
+        merged
+      end
+    end
+
+    private
+
+    # Validate and resolve the backing store. Invalid → logged error + a fresh
+    # MemoryStore fallback.
+    def resolve_store(store)
+      return Stores::MemoryStore.new if store.nil?
+
+      if valid_store?(store)
+        store
+      else
+        @log_manager.error("DataStoreManager#resolve_store: rejected store " \
+                           "#{store.class} (must respond to get/set); using MemoryStore")
+        Stores::MemoryStore.new
+      end
+    end
+
+    # JS +isValidDataStore+ parity: presence of +get+ and +set+, no arity check.
+    def valid_store?(store)
+      REQUIRED_STORE_METHODS.all? { |m| store.respond_to?(m) }
+    end
+
+    # Recursive deep merge mirroring the JS +objectDeepMerge+ contract. Arrays
+    # union (new values first, deduped); nested hashes recurse; scalars from the
+    # right-hand (new) value win.
+    def deep_merge(base, incoming)
+      base.merge(incoming) do |_key, base_val, new_val|
+        if base_val.is_a?(Array) && new_val.is_a?(Array)
+          (new_val + base_val).uniq
+        elsif base_val.is_a?(Hash) && new_val.is_a?(Hash)
+          deep_merge(base_val, new_val)
+        else
+          new_val
+        end
+      end
+    end
+  end
+end

data/lib/convert_sdk/enums/bucketing_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../sentinel"
+
+module ConvertSdk
+  # Bucketing business misses, signaled as frozen singleton {Sentinel}s.
+  #
+  # Wire strings are byte-identical to the JS SDK
+  # (javascript-sdk/packages/enums/src/bucketing-error.ts). NOTE: the JS source
+  # has a typo in the constant *name* (+VARIAION_NOT_DECIDED+, missing the "T").
+  # The Ruby constant spelling is CORRECTED to {VARIATION_NOT_DECIDED}; the wire
+  # string +convert.com_variation_not_decided+ is left byte-identical to JS.
+  module BucketingError
+    # No variation could be decided for the visitor.
+    # Wire: +convert.com_variation_not_decided+ (byte-identical to JS).
+    VARIATION_NOT_DECIDED = Sentinel.new("convert.com_variation_not_decided")
+  end
+end

data/lib/convert_sdk/enums/feature_status.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Feature toggle status. Wire values byte-identical to the JS SDK
+  # (javascript-sdk/packages/enums/src/feature-status.ts).
+  module FeatureStatus
+    # The feature is on. Wire: +enabled+.
+    ENABLED = "enabled"
+
+    # The feature is off. Wire: +disabled+.
+    DISABLED = "disabled"
+  end
+end

data/lib/convert_sdk/enums/goal_data_key.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Recognized keys for conversion goal data (consumed by conversion tracking,
+  # Story 4.3). Wire strings byte-identical to the JS SDK
+  # (javascript-sdk/packages/enums/src/goal-data-key.ts).
+  module GoalDataKey
+    # Revenue amount. Wire: +amount+.
+    AMOUNT = "amount"
+    # Number of products. Wire: +productsCount+.
+    PRODUCTS_COUNT = "productsCount"
+    # Transaction identifier. Wire: +transactionId+.
+    TRANSACTION_ID = "transactionId"
+    # Custom dimension 1. Wire: +customDimension1+.
+    CUSTOM_DIMENSION_1 = "customDimension1"
+    # Custom dimension 2. Wire: +customDimension2+.
+    CUSTOM_DIMENSION_2 = "customDimension2"
+    # Custom dimension 3. Wire: +customDimension3+.
+    CUSTOM_DIMENSION_3 = "customDimension3"
+    # Custom dimension 4. Wire: +customDimension4+.
+    CUSTOM_DIMENSION_4 = "customDimension4"
+    # Custom dimension 5. Wire: +customDimension5+.
+    CUSTOM_DIMENSION_5 = "customDimension5"
+
+    # All recognized goal-data keys, in declaration order. Frozen array for
+    # validation use (Story 4.3).
+    ALL = [
+      AMOUNT, PRODUCTS_COUNT, TRANSACTION_ID,
+      CUSTOM_DIMENSION_1, CUSTOM_DIMENSION_2, CUSTOM_DIMENSION_3,
+      CUSTOM_DIMENSION_4, CUSTOM_DIMENSION_5
+    ].freeze
+
+    # The two-worlds mapping (Story 4.3): the PUBLIC Ruby +track_conversion+
+    # +goal_data:+ surface accepts snake_case symbol keys; this is the SINGLE
+    # place the snake_case input is translated to the camelCase WIRE identifier.
+    # The conversion build site (DataManager#convert) consults this map to
+    # validate caller keys and emit the wire-correct +[{key, value}]+ pairs;
+    # any key absent here is unknown and rejected. Frozen so it cannot drift.
+    RUBY_KEY_MAP = {
+      amount: AMOUNT,
+      products_count: PRODUCTS_COUNT,
+      transaction_id: TRANSACTION_ID,
+      custom_dimension_1: CUSTOM_DIMENSION_1,
+      custom_dimension_2: CUSTOM_DIMENSION_2,
+      custom_dimension_3: CUSTOM_DIMENSION_3,
+      custom_dimension_4: CUSTOM_DIMENSION_4,
+      custom_dimension_5: CUSTOM_DIMENSION_5
+    }.freeze
+
+    # Translate a single caller-supplied +goal_data+ key (symbol or string,
+    # snake_case OR the camelCase wire form) to its wire identifier, or +nil+
+    # when the key is not one of the eight platform keys (caller rejects it).
+    # Accepting the wire form too keeps the surface forgiving for integrators
+    # who already know the platform identifiers.
+    #
+    # @param key [Symbol, String] the caller key.
+    # @return [String, nil] the wire identifier, or nil when unrecognized.
+    def self.wire_key_for(key)
+      RUBY_KEY_MAP[key.to_sym] || (ALL.include?(key.to_s) ? key.to_s : nil)
+    end
+  end
+end

data/lib/convert_sdk/enums/log_level.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Logging verbosity levels, ordered least-to-most severe. Integer values are
+  # JS-parity, verified against javascript-sdk/packages/enums/src/log-level.ts.
+  # Consumed by LogManager (Story 1.4): a message logs when its level is >= the
+  # configured threshold; +SILENT+ suppresses everything.
+  module LogLevel
+    # Finest-grained tracing.
+    TRACE = 0
+    # Debug diagnostics.
+    DEBUG = 1
+    # Informational messages.
+    INFO = 2
+    # Warnings.
+    WARN = 3
+    # Errors.
+    ERROR = 4
+    # Suppress all logging.
+    SILENT = 5
+  end
+end

data/lib/convert_sdk/enums/rule_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../sentinel"
+
+module ConvertSdk
+  # Rule-evaluation business misses, signaled as frozen singleton {Sentinel}s.
+  #
+  # Returned by audience/rule evaluation when a decision cannot be made. Wire
+  # strings are byte-identical to the JS SDK
+  # (javascript-sdk/packages/enums/src/rule-error.ts) and appear on the wire.
+  module RuleError
+    # No data was found to evaluate the rule. Wire: +convert.com_no_data_found+.
+    NO_DATA_FOUND = Sentinel.new("convert.com_no_data_found")
+
+    # More data is required before a decision can be made.
+    # Wire: +convert.com_need_more_data+.
+    NEED_MORE_DATA = Sentinel.new("convert.com_need_more_data")
+  end
+end

data/lib/convert_sdk/enums/system_events.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # SDK system event names, fired by EventManager across Epics 2-4. Wire strings
+  # are byte-identical to the JS SDK
+  # (javascript-sdk/packages/enums/src/system-events.ts).
+  module SystemEvents
+    # SDK is ready. Wire: +ready+.
+    READY = "ready"
+    # Remote config was updated. Wire: +config.updated+.
+    CONFIG_UPDATED = "config.updated"
+    # A bucketing decision was made. Wire: +bucketing+.
+    BUCKETING = "bucketing"
+    # A conversion was tracked. Wire: +conversion+.
+    CONVERSION = "conversion"
+    # The API request queue was released. Wire: +api.queue.released+.
+    API_QUEUE_RELEASED = "api.queue.released"
+    # Visitor segments were computed. Wire: +segments+.
+    SEGMENTS = "segments"
+    # A location was activated. Wire: +location.activated+.
+    LOCATION_ACTIVATED = "location.activated"
+    # A location was deactivated. Wire: +location.deactivated+.
+    LOCATION_DEACTIVATED = "location.deactivated"
+    # Audiences were evaluated. Wire: +audiences+.
+    AUDIENCES = "audiences"
+    # The datastore queue was released. Wire: +datastore.queue.released+.
+    DATASTORE_QUEUE_RELEASED = "datastore.queue.released"
+  end
+end

data/lib/convert_sdk/event_manager.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Synchronous, thread-safe pub/sub engine for SDK lifecycle events.
+  #
+  # +EventManager+ is the single emission point for the SDK's lifecycle signals.
+  # Consumers subscribe with {#on} using the cross-SDK-consistent event names
+  # ({SystemEvents}); the SDK's internal stages fire those events with {#fire}
+  # as wiring lands in later stories (Client +ready+ in 2.5, +config.updated+
+  # per refresh in 2.7, +bucketing+ in 2.11/4.1, +conversion+ in 4.3,
+  # +api.queue.released+ in 4.2). This story delivers the engine only.
+  #
+  # == Event names are a wire-parity surface (FR57)
+  #
+  # Event names are byte-identical to the JS SDK's +SystemEvents+ strings. A
+  # {SystemEvents} constant *is* its wire string (e.g.
+  # +SystemEvents::READY == "ready"+), so +on(SystemEvents::READY)+ and
+  # +on("ready")+ register under the SAME string key. Names are normalized to
+  # their string form (+#to_s+) before they touch the registry.
+  #
+  # == Synchronous firing
+  #
+  # Events fire synchronously, in registration order, at each lifecycle stage —
+  # no event thread, no queue. A slow listener slows the SDK (documented, JS
+  # parity). The firing path never raises into its caller: a listener that
+  # raises is caught and logged, and the remaining listeners still run.
+  #
+  # == Deferred replay for late subscribers
+  #
+  # Some events (READY, CONVERSION in JS) fire with <tt>deferred: true</tt>. The
+  # first deferred emission of an event records its +{payload, err}+ so a
+  # listener that subscribes *after* the event already happened is replayed the
+  # stored value the moment it registers. This lets late subscribers observe a
+  # one-shot lifecycle signal they would otherwise have missed.
+  #
+  # == Thread safety
+  #
+  # The listener registry and the deferred store are both guarded by
+  # +@listeners_mutex+. Registration mutates the registry inside the lock.
+  # Firing takes a +dup+ snapshot of the listener list inside the lock, then
+  # iterates that snapshot OUTSIDE the lock — so a listener body (which runs
+  # unlocked) may itself call {#on} to register a new listener without
+  # deadlocking. The newly added listener is not invoked by the in-flight fire
+  # (it was not in the snapshot); it participates in subsequent fires.
+  class EventManager
+    # @param log_manager [LogManager] sink for contained listener failures and
+    #   unknown-event debug traces.
+    def initialize(log_manager:)
+      @log_manager = log_manager
+      # event name (String) => Array<Proc> of listeners, registration-ordered.
+      @listeners = {}
+      # event name (String) => { payload:, err: } recorded by the first
+      # deferred fire, replayed to late subscribers.
+      @deferred = {}
+      # Thread safety: guarded by @listeners_mutex (both @listeners and @deferred).
+      @listeners_mutex = Thread::Mutex.new
+    end
+
+    # Subscribe to an event. Public API.
+    #
+    # Accepts a {SystemEvents} constant (which IS its string value) or any
+    # matching string; the name is normalized to its string form so both
+    # spellings register under one key. If the event was previously fired with
+    # <tt>deferred: true</tt>, the listener is invoked immediately with the
+    # stored payload/err (deferred replay).
+    #
+    # @param event [String] a {SystemEvents} value or matching string.
+    # @yieldparam payload [Object, nil] the emitted payload.
+    # @yieldparam err [Object, nil] the emitted error, or +nil+ on normal
+    #   emission. Single-parameter blocks work — extra args are ignored.
+    # @return [self]
+    def on(event, &listener)
+      return self if listener.nil?
+
+      key = event.to_s
+      deferred = @listeners_mutex.synchronize do
+        (@listeners[key] ||= []) << listener
+        @deferred[key]
+      end
+      # Replay outside the lock so the listener body may itself call #on.
+      invoke(key, listener, deferred[:payload], deferred[:err]) if deferred
+      self
+    end
+
+    # Emit an event to all currently registered listeners. Internal API.
+    #
+    # @api private
+    # @param event [String] a {SystemEvents} value or matching string.
+    # @param payload [Object, nil] delivered as the listener's first argument.
+    # @param err [Object, nil] delivered as the listener's second argument
+    #   (+nil+ on normal emission).
+    # @param deferred [Boolean] when true, the first such emission of this event
+    #   is recorded for replay to late subscribers (see class docs).
+    # @return [void]
+    def fire(event, payload = nil, err = nil, deferred: false)
+      key = event.to_s
+      snapshot = @listeners_mutex.synchronize do
+        @deferred[key] ||= { payload: payload, err: err } if deferred
+        @listeners[key]&.dup
+      end
+
+      if snapshot.nil? || snapshot.empty?
+        @log_manager.debug("EventManager#fire: no listeners for '#{key}'")
+        return
+      end
+
+      # Iterate the snapshot OUTSIDE the lock — listener bodies run unlocked and
+      # may re-register without deadlock.
+      snapshot.each { |listener| invoke(key, listener, payload, err) }
+    end
+
+    private
+
+    # Invoke one listener with exception containment. A raising listener is
+    # caught (StandardError only — never Exception) and logged at error level;
+    # it is never re-raised, so siblings still fire and the host never crashes.
+    def invoke(event, listener, payload, err)
+      listener.call(payload, err)
+    rescue StandardError => e
+      @log_manager.error(
+        "EventManager#fire: listener for '#{event}' raised #{e.class}: #{e.message}"
+      )
+    end
+  end
+end

data/lib/convert_sdk/experience_manager.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Variation-selection support — the thin per-experience / across-experiences
+  # entry surface over the {DataManager} decision flow.
+  #
+  # This mirrors the JS +experience-manager.ts+ division of labor EXACTLY: the
+  # ExperienceManager owns variation SELECTION (the public-ish +select_variation+
+  # / +select_variations+ seams that {Context} drives), while the ORDERED decision
+  # FLOW — entity -> archived -> environment -> stored-bucketing -> locations ->
+  # audiences -> custom segments -> traffic allocation -> variation — lives in
+  # {DataManager#get_bucketing} (JS +data-manager.ts:227-720+). A reordered step
+  # is a parity bug; the order is owned in ONE place (DataManager) and exercised,
+  # not duplicated here.
+  #
+  # == +select_variation+ (one experience by key)
+  #
+  # Delegates straight to {DataManager#get_bucketing}, returning a frozen
+  # {BucketedVariation} on a hit or a {Sentinel} ({RuleError}/{BucketingError}) on
+  # a miss — JS +selectVariation+ (+experience-manager.ts:110-116+).
+  #
+  # == +select_variations+ (all experiences)
+  #
+  # Maps {DataManager#get_bucketing} over EVERY configured experience and FILTERS
+  # OUT every non-decision: +nil+, {RuleError}, and {BucketingError} sentinels.
+  # This is the JS +selectVariations+ contract (+experience-manager.ts:159-168+):
+  # the across-all-experiences call returns ONLY the variations a visitor was
+  # actually bucketed into; misses never appear in the list (FR16 return shape).
+  #
+  # @api private
+  class ExperienceManager
+    # @param data_manager [DataManager] the decision-flow owner (holds the config
+    #   snapshot, the bucketing/rule collaborators, and the visitor store seam).
+    # @param log_manager [LogManager, nil] optional debug logger.
+    def initialize(data_manager:, log_manager: nil)
+      @data_manager = data_manager
+      @log_manager = log_manager
+    end
+
+    # Decide one experience for a visitor by experience key.
+    #
+    # @param visitor_id [String] the visitor identifier.
+    # @param experience_key [String] the experience +key+ to decide.
+    # @param attributes [Hash] bucketing attributes — +:visitor_properties+
+    #   (audiences), +:location_properties+ (locations/site_area), +:environment+,
+    #   +:update_visitor_properties+.
+    # @return [BucketedVariation, Sentinel] a frozen variation, or a
+    #   {RuleError}/{BucketingError} sentinel on a miss.
+    def select_variation(visitor_id, experience_key, attributes = {})
+      @data_manager.get_bucketing(visitor_id, experience_key, attributes)
+    end
+
+    # Decide ALL configured experiences for a visitor, returning only the
+    # successful bucketed variations (misses filtered — JS parity).
+    #
+    # @param visitor_id [String] the visitor identifier.
+    # @param attributes [Hash] bucketing attributes (see {#select_variation}).
+    # @return [Array<BucketedVariation>] the frozen variations the visitor was
+    #   bucketed into (sentinels and nils excluded).
+    def select_variations(visitor_id, attributes = {})
+      @data_manager.experiences.filter_map do |experience|
+        next unless experience.is_a?(Hash)
+
+        result = @data_manager.get_bucketing(visitor_id, experience["key"], attributes)
+        result if result.is_a?(BucketedVariation)
+      end
+    end
+  end
+end