seekmodo-sdk 0.5.0

data/lib/seekmodo/sdk/circuit_breaker.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "storage/protocols"
+
+module Seekmodo
+  module Sdk
+    class CircuitBreaker
+      STATE_CLOSED = "closed"
+      STATE_OPEN = "open"
+      STATE_HALFOPEN = "half_open"
+
+      def initialize(
+        store,
+        key: "numinix.seekmodo.circuit",
+        failure_threshold: 5,
+        failure_window_seconds: 60,
+        open_cooldown_seconds: 30,
+        clock: nil
+      )
+        @store = store
+        @key = key
+        @failure_threshold = failure_threshold
+        @failure_window_seconds = failure_window_seconds
+        @open_cooldown_seconds = open_cooldown_seconds
+        @clock = clock || -> { Time.now.to_i }
+      end
+
+      def allow_request?
+        state = load_state
+        now = @clock.call
+
+        if state["state"] == STATE_OPEN
+          if now - state["opened_at"].to_i >= @open_cooldown_seconds
+            state["state"] = STATE_HALFOPEN
+            state["probe_in_flight"] = true
+            save_state(state)
+            return true
+          end
+          return false
+        end
+
+        if state["state"] == STATE_HALFOPEN
+          return false if state["probe_in_flight"]
+
+          state["probe_in_flight"] = true
+          save_state(state)
+          return true
+        end
+
+        true
+      end
+
+      def record_success
+        state = load_state
+        if [STATE_HALFOPEN, STATE_OPEN].include?(state["state"])
+          save_state(
+            "state" => STATE_CLOSED,
+            "failures" => [],
+            "opened_at" => 0,
+            "probe_in_flight" => false
+          )
+          return
+        end
+
+        if state["failures"].any?
+          state["failures"] = []
+          save_state(state)
+        end
+      end
+
+      def record_failure
+        state = load_state
+        now = @clock.call
+
+        if state["state"] == STATE_HALFOPEN
+          save_state(
+            "state" => STATE_OPEN,
+            "failures" => [],
+            "opened_at" => now,
+            "probe_in_flight" => false
+          )
+          return
+        end
+
+        failures = state["failures"] + [now]
+        cutoff = now - @failure_window_seconds
+        failures = failures.select { |ts| ts >= cutoff }
+
+        if failures.length >= @failure_threshold
+          save_state(
+            "state" => STATE_OPEN,
+            "failures" => [],
+            "opened_at" => now,
+            "probe_in_flight" => false
+          )
+          return
+        end
+
+        state["failures"] = failures
+        save_state(state)
+      end
+
+      def state
+        load_state["state"]
+      end
+
+      def snapshot
+        load_state
+      end
+
+      private
+
+      def load_state
+        @store.load(@key)
+      end
+
+      def save_state(state)
+        ttl = [@open_cooldown_seconds * 2, @failure_window_seconds * 4].max
+        @store.save(@key, state, ttl)
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/connector/client.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+require_relative "../exceptions/client_error"
+require_relative "../exceptions/over_quota_error"
+require_relative "../exceptions/signature_mismatch_error"
+require_relative "../exceptions/tenant_unavailable_error"
+require_relative "../hmac_signer"
+require_relative "../circuit_breaker"
+
+module Seekmodo
+  module Sdk
+    module Connector
+      class Client
+        DEFAULT_GATEWAY_URL = "https://mcp.seekmodo.com"
+        INDEX_CHUNK_SIZE = 500
+        INDEX_HARD_CAP_PER_CALL = 1000
+        DEFAULT_REQUEST_TIMEOUT_MS = 1500
+        DEFAULT_CONNECT_TIMEOUT_MS = 250
+
+        attr_reader :signer, :gateway_url
+
+        def initialize(
+          signer,
+          gateway_url: DEFAULT_GATEWAY_URL,
+          breaker: nil,
+          user_agent: "seekmodo-ruby-sdk/0.5.0",
+          storefront_host: "",
+          connection: nil,
+          timeout_ms: DEFAULT_REQUEST_TIMEOUT_MS,
+          connect_timeout_ms: DEFAULT_CONNECT_TIMEOUT_MS
+        )
+          @signer = signer
+          @gateway_url = gateway_url.to_s.delete_suffix("/")
+          @breaker = breaker
+          @user_agent = user_agent
+          @storefront_host = storefront_host.to_s.downcase.strip
+          @owns_connection = connection.nil?
+          @connection = connection || build_connection(timeout_ms, connect_timeout_ms)
+        end
+
+        def close
+          @connection.close if @owns_connection && @connection.respond_to?(:close)
+        end
+
+        def search(params)
+          post_json("/v1/search", params)
+        end
+
+        def index(documents, action: "upsert")
+          if documents.length > INDEX_HARD_CAP_PER_CALL
+            merged = { "ok" => true, "imported" => 0, "errors" => [] }
+            documents.each_slice(INDEX_CHUNK_SIZE) do |chunk|
+              res = post_json("/v1/index", { "documents" => chunk, "action" => action })
+              merged["imported"] += res.fetch("imported", 0).to_i
+              errors = res["errors"]
+              merged["errors"] = merged["errors"] + errors if errors.is_a?(Array)
+              merged["ok"] = false unless res.fetch("ok", true)
+            end
+            return merged
+          end
+
+          post_json("/v1/index", { "documents" => documents, "action" => action })
+        end
+
+        def events(events)
+          post_json("/v1/events", { "events" => events })
+        end
+
+        def tenant_handshake
+          post_json("/v1/tenant/handshake", {})
+        end
+
+        def tenant_snapshot
+          post_json("/v1/tenant.snapshot", {})
+        end
+
+        def browser_token(audience = nil)
+          body = audience.nil? ? {} : { "audience" => audience }
+          post_json("/v1/tenants/token", body)
+        end
+
+        def tools
+          get_json("/v1/tools")
+        end
+
+        def health
+          get_json("/v1/health", signed: false)
+        end
+
+        def post_json(path, body, extra_headers = {})
+          raw = encode_body(body)
+          execute("POST", path, raw, extra_headers, signed: true)
+        end
+
+        def get_json(path, extra_headers = {}, signed: true)
+          execute("GET", path, "", extra_headers, signed: signed)
+        end
+
+        private
+
+        def build_connection(timeout_ms, connect_timeout_ms)
+          Faraday.new do |f|
+            f.options.timeout = timeout_ms / 1000.0
+            f.options.open_timeout = connect_timeout_ms / 1000.0
+            f.adapter Faraday.default_adapter
+          end
+        end
+
+        def execute(method, path, body, extra_headers, signed:)
+          if signed && !@signer.configured?
+            raise ClientError.new(
+              "Seekmodo client is missing tenant_id or shared_secret; cannot sign request.",
+              ClientError::KIND_NOT_CONFIGURED
+            )
+          end
+          if @breaker && !@breaker.allow_request?
+            raise ClientError.new(
+              "Seekmodo circuit breaker is open; refusing to call gateway.",
+              ClientError::KIND_BREAKER_OPEN
+            )
+          end
+
+          headers = {
+            "Accept" => "application/json",
+            "User-Agent" => @user_agent
+          }
+          headers["Content-Type"] = "application/json" if body && !body.empty?
+          if signed
+            headers.merge!(@signer.headers(body))
+            if !@storefront_host.empty?
+              headers[HmacSigner::HEADER_STOREFRONT_HOST] = @storefront_host
+            end
+          end
+          headers.merge!(extra_headers)
+
+          begin
+            response = @connection.run_request(
+              method.downcase.to_sym,
+              @gateway_url + path,
+              body.empty? ? nil : body,
+              headers
+            )
+          rescue Faraday::TimeoutError => e
+            on_failure
+            raise ClientError.new(
+              "Network failure calling Seekmodo gateway: #{e.message}",
+              ClientError::KIND_TIMEOUT,
+              cause: e
+            )
+          rescue Faraday::Error => e
+            on_failure
+            raise ClientError.new(
+              "Network failure calling Seekmodo gateway: #{e.message}",
+              ClientError::KIND_NETWORK,
+              cause: e
+            )
+          end
+
+          classify(response)
+        end
+
+        def classify(response)
+          status = response.status
+          body = {}
+          if response.body && !response.body.to_s.empty?
+            decoded = JSON.parse(response.body)
+            body = decoded if decoded.is_a?(Hash)
+          end
+
+          if status >= 200 && status < 300
+            on_success
+            return body
+          end
+
+          error_code = body["error"].is_a?(String) ? body["error"] : nil
+          kind = ClientError.classify_error_code(error_code)
+
+          if status >= 500
+            on_failure
+            raise ClientError.new(
+              "Gateway returned HTTP #{status}",
+              ClientError::KIND_HTTP_5XX,
+              status,
+              body: body
+            )
+          end
+
+          if kind == ClientError::KIND_TENANT_UNAVAILABLE
+            on_success
+            raise TenantUnavailableError.new(
+              "Tenant unavailable (gateway HTTP #{status}, code=#{error_code})",
+              kind,
+              status,
+              body: body
+            )
+          end
+
+          if kind == ClientError::KIND_OVER_QUOTA || status == 402
+            on_success
+            raise OverQuotaError.new(
+              "Over plan quota (gateway HTTP #{status}, code=#{error_code || 'over_quota'})",
+              ClientError::KIND_OVER_QUOTA,
+              status,
+              body: body
+            )
+          end
+
+          if kind == ClientError::KIND_SIGNATURE_MISMATCH || status == 401
+            on_failure
+            raise SignatureMismatchError.new(
+              "Gateway rejected HMAC (HTTP #{status}, code=#{error_code || 'signature_mismatch'})",
+              ClientError::KIND_SIGNATURE_MISMATCH,
+              status,
+              body: body
+            )
+          end
+
+          on_failure
+          raise ClientError.new(
+            "Gateway returned HTTP #{status}",
+            ClientError::KIND_HTTP_4XX,
+            status,
+            body: body
+          )
+        end
+
+        def on_success
+          @breaker&.record_success
+        end
+
+        def on_failure
+          @breaker&.record_failure
+        end
+
+        def encode_body(body)
+          JSON.generate(body)
+        rescue JSON::GeneratorError, TypeError => e
+          raise ClientError.new(
+            "Failed to JSON-encode request body: #{e.message}",
+            ClientError::KIND_BAD_RESPONSE,
+            cause: e
+          )
+        end
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/events/click_beacon.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Seekmodo
+  module Sdk
+    module Events
+      module ClickBeacon
+        SURFACE_SERP = "serp"
+        SURFACE_TYPEAHEAD = "typeahead"
+        SURFACE_RECOMMENDATIONS = "recommendations"
+
+        module_function
+
+        def click(query, doc_id, position, is_bot, surface: SURFACE_SERP, shopper_context: nil, extra: nil)
+          event = {
+            "type" => "click",
+            "q" => query,
+            "doc_id" => doc_id,
+            "position" => position,
+            "is_bot" => is_bot,
+            "surface" => surface,
+            "ts" => Time.now.to_i
+          }
+          event["shopper"] = shopper_context if shopper_context
+          event.merge!(extra) if extra
+          event
+        end
+
+        def impression(query, doc_ids, is_bot, surface: SURFACE_SERP, shopper_context: nil, extra: nil)
+          event = {
+            "type" => "impression",
+            "q" => query,
+            "doc_ids" => doc_ids.dup,
+            "is_bot" => is_bot,
+            "surface" => surface,
+            "ts" => Time.now.to_i
+          }
+          event["shopper"] = shopper_context if shopper_context
+          event.merge!(extra) if extra
+          event
+        end
+
+        def search(query, hits, is_bot, shopper_context: nil, extra: nil)
+          event = {
+            "type" => "search",
+            "q" => query,
+            "hits" => hits,
+            "is_bot" => is_bot,
+            "surface" => SURFACE_SERP,
+            "ts" => Time.now.to_i
+          }
+          event["shopper"] = shopper_context if shopper_context
+          event.merge!(extra) if extra
+          event
+        end
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/events/events_queue.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../connector/client"
+require_relative "../storage/protocols"
+
+module Seekmodo
+  module Sdk
+    module Events
+      class EventsQueue
+        DEFAULT_AUTO_FLUSH_THRESHOLD = 50
+        DEFAULT_MAX_PER_FLUSH = 200
+
+        def initialize(
+          client,
+          store,
+          auto_flush_threshold: DEFAULT_AUTO_FLUSH_THRESHOLD,
+          max_per_flush: DEFAULT_MAX_PER_FLUSH
+        )
+          @client = client
+          @store = store
+          @auto_flush_threshold = auto_flush_threshold
+          @max_per_flush = max_per_flush
+        end
+
+        def push(event)
+          @store.push(event)
+          flush if @store.count >= @auto_flush_threshold
+        end
+
+        def flush
+          batch = @store.drain(@max_per_flush)
+          return 0 if batch.empty?
+
+          begin
+            @client.events(batch)
+          rescue StandardError
+            batch.each { |event| @store.push(event) }
+            return 0
+          end
+
+          batch.length
+        end
+
+        def pending_count
+          @store.count
+        end
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/exceptions/breaker_open_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "seekmodo_error"
+
+module Seekmodo
+  module Sdk
+    class BreakerOpenError < SeekmodoError
+    end
+  end
+end

data/lib/seekmodo/sdk/exceptions/client_error.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "seekmodo_error"
+
+module Seekmodo
+  module Sdk
+    class ClientError < SeekmodoError
+      KIND_NOT_CONFIGURED = "not_configured"
+      KIND_BREAKER_OPEN = "breaker_open"
+      KIND_NETWORK = "network"
+      KIND_TIMEOUT = "timeout"
+      KIND_HTTP_4XX = "http_4xx"
+      KIND_HTTP_5XX = "http_5xx"
+      KIND_BAD_RESPONSE = "bad_response"
+      KIND_SIGNATURE_MISMATCH = "signature_mismatch"
+      KIND_RATE_LIMITED = "rate_limited"
+      KIND_OVER_QUOTA = "over_quota"
+      KIND_TENANT_UNAVAILABLE = "tenant_unavailable"
+
+      TENANT_UNAVAILABLE_ERROR_CODES = %w[
+        tenant_paused tenant_not_found tenant_unknown tenant_suspended tenant_disabled
+      ].freeze
+
+      attr_reader :kind, :status_code, :body
+
+      def initialize(message, kind, status_code = 0, body: nil, cause: nil)
+        super(message)
+        @kind = kind
+        @status_code = status_code
+        @body = body || {}
+        set_backtrace(cause&.backtrace) if cause
+      end
+
+      def is_transient?
+        [
+          KIND_NETWORK,
+          KIND_TIMEOUT,
+          KIND_HTTP_5XX,
+          KIND_TENANT_UNAVAILABLE
+        ].include?(kind)
+      end
+
+      def should_fallback?
+        kind != KIND_HTTP_4XX
+      end
+
+      def error_code
+        err = body["error"]
+        err.is_a?(String) ? err : nil
+      end
+
+      def self.classify_error_code(error_code)
+        return nil if error_code.nil? || error_code.empty?
+
+        if TENANT_UNAVAILABLE_ERROR_CODES.include?(error_code)
+          return KIND_TENANT_UNAVAILABLE
+        end
+        return KIND_SIGNATURE_MISMATCH if error_code == "signature_mismatch"
+        return KIND_RATE_LIMITED if error_code == "rate_limited"
+        return KIND_OVER_QUOTA if %w[over_quota feature_not_in_plan].include?(error_code)
+
+        nil
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/exceptions/over_quota_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Seekmodo
+  module Sdk
+    class OverQuotaError < ClientError
+    end
+  end
+end

data/lib/seekmodo/sdk/exceptions/seekmodo_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Seekmodo
+  module Sdk
+    class SeekmodoError < StandardError
+    end
+  end
+end

data/lib/seekmodo/sdk/exceptions/signature_mismatch_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Seekmodo
+  module Sdk
+    class SignatureMismatchError < ClientError
+    end
+  end
+end

data/lib/seekmodo/sdk/exceptions/tenant_unavailable_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Seekmodo
+  module Sdk
+    class TenantUnavailableError < ClientError
+    end
+  end
+end

data/lib/seekmodo/sdk/hmac_signer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Seekmodo
+  module Sdk
+    class HmacSigner
+      HEADER_TENANT = "X-Seekmodo-Tenant"
+      HEADER_SIGNATURE = "X-Seekmodo-Signature"
+      HEADER_TIMESTAMP = "X-Seekmodo-Timestamp"
+      HEADER_SESSION = "X-Seekmodo-Session"
+      HEADER_STOREFRONT_HOST = "X-Seekmodo-Storefront-Host"
+
+      attr_reader :tenant_id
+
+      def initialize(tenant_id, shared_secret)
+        @tenant_id = tenant_id
+        @shared_secret = shared_secret
+      end
+
+      def headers(raw_body, timestamp = nil)
+        ts = (timestamp || Time.now.to_i).to_s
+        signature = OpenSSL::HMAC.hexdigest("SHA256", @shared_secret, raw_body)
+        {
+          HEADER_TENANT => @tenant_id,
+          HEADER_SIGNATURE => signature,
+          HEADER_TIMESTAMP => ts
+        }
+      end
+
+      def verify(raw_body, signature)
+        expected = OpenSSL::HMAC.hexdigest("SHA256", @shared_secret, raw_body)
+        return false if signature.nil? || signature.empty?
+
+        OpenSSL.secure_compare(expected, signature)
+      end
+
+      def configured?
+        !@tenant_id.to_s.empty? && !@shared_secret.to_s.empty?
+      end
+    end
+  end
+end