seekmodo-sdk 0.5.0

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+require_relative "../exceptions/seekmodo_error"
+require_relative "../hmac_signer"
+
+module Seekmodo
+  module Sdk
+    module Mcp
+      class Client
+        DEFAULT_GATEWAY_URL = "https://mcp.seekmodo.com"
+
+        def initialize(
+          gateway_url: DEFAULT_GATEWAY_URL,
+          signer: nil,
+          operator_token: nil,
+          tenant_id: nil,
+          connection: nil,
+          user_agent: "seekmodo-ruby-sdk/0.5.0"
+        )
+          @gateway_url = gateway_url.to_s.delete_suffix("/")
+          @signer = signer
+          @operator_token = operator_token
+          @tenant_id = tenant_id
+          @user_agent = user_agent
+          @connection = connection || Faraday.new do |f|
+            f.adapter Faraday.default_adapter
+          end
+          @request_id = 0
+
+          if @signer.nil? && @operator_token.nil?
+            raise ArgumentError, "MCP client requires signer (HMAC) or operator_token (bearer)"
+          end
+        end
+
+        def initialize_session(params = {})
+          rpc("initialize", params)
+        end
+
+        def tools_list
+          rpc("tools/list", {})
+        end
+
+        def tools_call(name, arguments = {})
+          rpc("tools/call", { "name" => name, "arguments" => arguments })
+        end
+
+        def ping
+          rpc("ping", {})
+        end
+
+        private
+
+        def rpc(method, params)
+          @request_id += 1
+          envelope = {
+            "jsonrpc" => "2.0",
+            "id" => @request_id,
+            "method" => method,
+            "params" => params
+          }
+          body = JSON.generate(envelope)
+          response = @connection.post(@gateway_url + "/mcp") do |req|
+            req.headers.update(build_headers(body))
+            req.body = body
+          end
+
+          parsed = JSON.parse(response.body)
+          unless response.status >= 200 && response.status < 300
+            raise SeekmodoError, "MCP gateway returned HTTP #{response.status}: #{response.body}"
+          end
+
+          if parsed["error"]
+            raise SeekmodoError, "MCP error #{parsed['error']}"
+          end
+
+          parsed["result"]
+        rescue JSON::ParserError => e
+          raise SeekmodoError, "MCP response was not valid JSON: #{e.message}"
+        end
+
+        def build_headers(body)
+          headers = {
+            "Content-Type" => "application/json",
+            "Accept" => "application/json",
+            "User-Agent" => @user_agent
+          }
+
+          if @operator_token
+            headers["Authorization"] = "Bearer #{@operator_token}"
+            if @tenant_id
+              headers[HmacSigner::HEADER_TENANT] = @tenant_id
+            end
+          elsif @signer
+            headers.merge!(@signer.headers(body))
+          end
+
+          headers
+        end
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/mode.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Seekmodo
+  module Sdk
+    module Mode
+      OFF = "off"
+      LEARNING = "learning"
+      SHADOW = "shadow"
+      ACTIVE = "active"
+      ENFORCE = "enforce"
+
+      ALL = [OFF, LEARNING, SHADOW, ACTIVE, ENFORCE].freeze
+
+      module_function
+
+      def values
+        ALL
+      end
+
+      def valid?(mode)
+        ALL.include?(mode)
+      end
+
+      def assert_mode(mode)
+        unless valid?(mode)
+          raise ArgumentError, "Unknown Seekmodo mode '#{mode}'; expected one of: #{ALL.join(', ')}"
+        end
+
+        mode
+      end
+
+      def serves_search?(mode)
+        [SHADOW, ACTIVE, ENFORCE].include?(mode)
+      end
+
+      def mirrors_writes?(mode)
+        mode != OFF
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/mode_fsm.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "mode"
+require_relative "circuit_breaker"
+require_relative "tenant_snapshot"
+
+module Seekmodo
+  module Sdk
+    class ModeFsm
+      def initialize(snapshot, breaker: nil, default_mode: Mode::OFF)
+        @snapshot = snapshot
+        @breaker = breaker
+        @default_mode = Mode.assert_mode(default_mode)
+      end
+
+      def effective_mode
+        if @breaker && @breaker.state == CircuitBreaker::STATE_OPEN
+          return Mode::OFF
+        end
+
+        config = @snapshot.get
+        configured = config.fetch("mode", @default_mode).to_s
+        return @default_mode unless Mode.valid?(configured)
+
+        if configured != Mode::ACTIVE
+          return configured
+        end
+
+        fsm_state = config.dig("fsm", "current_state").to_s
+        if Mode.valid?(fsm_state) && fsm_state != Mode::ACTIVE
+          return fsm_state
+        end
+
+        Mode::SHADOW
+      end
+
+      def configured_mode
+        config = @snapshot.get
+        configured = config.fetch("mode", @default_mode).to_s
+        Mode.valid?(configured) ? configured : @default_mode
+      end
+
+      def serves_search?
+        Mode.serves_search?(effective_mode)
+      end
+
+      def mirrors_writes?
+        Mode.mirrors_writes?(effective_mode)
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/pairing.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "jwt"
+require "openssl"
+require "faraday"
+
+require_relative "exceptions/seekmodo_error"
+require_relative "storage/protocols"
+
+module Seekmodo
+  module Sdk
+    class Pairing
+      DEFAULT_JWKS_URL = "https://seekmodo.com/.well-known/jwks.json"
+      KEYS_CACHE_KEY = "numinix.seekmodo.pairing.jwks"
+      KEYS_CACHE_TTL_SECONDS = 86400
+      MAX_TOKEN_AGE_SECONDS = 600
+
+      def initialize(connection, cache, jwks_url: DEFAULT_JWKS_URL, clock: nil)
+        @connection = connection
+        @cache = cache
+        @jwks_url = jwks_url
+        @clock = clock || -> { Time.now.to_i }
+      end
+
+      def verify_and_extract(jwt_token)
+        header, payload, _sig = JWT.decode(jwt_token, nil, false)
+        alg = header["alg"].to_s
+        raise SeekmodoError, "Unsupported pairing JWT alg \"#{alg}\"; expected EdDSA." unless alg == "EdDSA"
+
+        kid = header["kid"].to_s
+        raise SeekmodoError, "Pairing JWT is missing kid header." if kid.empty?
+
+        jwk = lookup_key(kid, refresh: false)
+        jwk = lookup_key(kid, refresh: true) if jwk.nil?
+        raise SeekmodoError, "No pairing JWKS key matches kid=\"#{kid}\"; rotation lag?" if jwk.nil?
+
+        public_key_raw = base64url_decode(jwk["x"].to_s)
+        raise SeekmodoError, "Pairing JWKS key has wrong byte length for Ed25519." unless public_key_raw.bytesize == 32
+
+        public_key = OpenSSL::PKey.read({
+          kty: "OKP",
+          crv: "Ed25519",
+          x: jwk["x"]
+        }.to_json)
+
+        JWT.decode(
+          jwt_token,
+          public_key,
+          true,
+          { algorithm: "EdDSA" }
+        )
+
+        now = @clock.call
+        exp = payload["exp"].to_i
+        iat = payload["iat"].to_i
+        raise SeekmodoError, "Pairing JWT has expired." if exp > 0 && exp < now
+        raise SeekmodoError, "Pairing JWT is older than the 10-minute replay window." if iat > 0 && now - iat > MAX_TOKEN_AGE_SECONDS
+
+        payload
+      rescue JWT::DecodeError => e
+        raise SeekmodoError, "Pairing JWT signature verification failed.", e.backtrace
+      end
+
+      def refresh_keys
+        fetch_keys
+      end
+
+      private
+
+      def lookup_key(kid, refresh:)
+        keys_doc = refresh ? fetch_keys : cached_keys
+        keys_doc.fetch("keys", []).find { |key| key.is_a?(Hash) && key["kid"] == kid }
+      end
+
+      def cached_keys
+        cached = @cache.get(KEYS_CACHE_KEY)
+        return cached if cached.is_a?(Hash)
+
+        fetch_keys
+      end
+
+      def fetch_keys
+        response = @connection.get(@jwks_url) do |req|
+          req.headers["Accept"] = "application/json"
+        end
+
+        raise SeekmodoError, "JWKS fetch returned HTTP #{response.status}" unless response.status == 200
+
+        body = JSON.parse(response.body)
+        unless body.is_a?(Hash) && body["keys"].is_a?(Array) && body["keys"].any?
+          raise SeekmodoError, 'JWKS response did not contain a "keys" array.'
+        end
+
+        @cache.set(KEYS_CACHE_KEY, body, KEYS_CACHE_TTL_SECONDS)
+        body
+      rescue Faraday::Error => e
+        raise SeekmodoError, "Failed to fetch Seekmodo pairing JWKS: #{e.message}"
+      rescue JSON::ParserError => e
+        raise SeekmodoError, "JWKS response was not valid JSON: #{e.message}"
+      end
+
+      def base64url_decode(segment)
+        padded = segment.tr("-_", "+/")
+        remainder = padded.length % 4
+        padded += "=" * (4 - remainder) if remainder.positive?
+        Base64.decode64(padded)
+      rescue ArgumentError => e
+        raise SeekmodoError, "Pairing JWT contains malformed base64url segment.", e.backtrace
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/signature_mismatch_tracker.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "storage/protocols"
+
+module Seekmodo
+  module Sdk
+    class SignatureMismatchTracker
+      CACHE_KEY = "numinix.seekmodo.sigmismatch_failures"
+      DEFAULT_WINDOW_SECONDS = 300
+      DEFAULT_THRESHOLD = 3
+
+      def initialize(cache, window_seconds: DEFAULT_WINDOW_SECONDS, threshold: DEFAULT_THRESHOLD, clock: nil)
+        @cache = cache
+        @window_seconds = window_seconds
+        @threshold = threshold
+        @clock = clock || -> { Time.now.to_i }
+      end
+
+      def record_failure
+        now = @clock.call
+        rows = load_and_prune(now)
+        rows << now
+        @cache.set(CACHE_KEY, rows, [@window_seconds * 2, 60].max)
+      end
+
+      def clear
+        @cache.delete(CACHE_KEY)
+      end
+
+      def tripped?
+        load_and_prune(@clock.call).length >= @threshold
+      end
+
+      def failures_in_window
+        load_and_prune(@clock.call).length
+      end
+
+      private
+
+      def load_and_prune(now)
+        cutoff = now - @window_seconds
+        stored = @cache.get(CACHE_KEY, [])
+        stored = [] unless stored.is_a?(Array)
+        pruned = stored.select { |ts| ts.is_a?(Numeric) && ts.to_i >= cutoff }.map(&:to_i)
+        if pruned.length != stored.length
+          @cache.set(CACHE_KEY, pruned, [@window_seconds * 2, 60].max)
+        end
+        pruned
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/storage/memory/stores.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "../protocols"
+
+module Seekmodo
+  module Sdk
+    module Storage
+      module Memory
+        DEFAULT_BREAKER_STATE = {
+          "state" => "closed",
+          "failures" => [],
+          "opened_at" => 0,
+          "probe_in_flight" => false
+        }.freeze
+
+        class BreakerStore
+          include Protocols::BreakerStateStore
+
+          def initialize
+            @rows = {}
+          end
+
+          def load(key)
+            state = @rows[key]
+            return DEFAULT_BREAKER_STATE.dup unless state
+
+            {
+              "state" => state["state"],
+              "failures" => state["failures"].dup,
+              "opened_at" => state["opened_at"].to_i,
+              "probe_in_flight" => state["probe_in_flight"]
+            }
+          end
+
+          def save(key, state, ttl_seconds)
+            @rows[key] = {
+              "state" => state["state"],
+              "failures" => state["failures"].dup,
+              "opened_at" => state["opened_at"].to_i,
+              "probe_in_flight" => state["probe_in_flight"]
+            }
+          end
+        end
+
+        class Cache
+          include Protocols::Cache
+
+          Entry = Struct.new(:value, :expires_at, keyword_init: true)
+
+          def initialize(clock = nil)
+            @rows = {}
+            @clock = clock || -> { Time.now.to_f }
+          end
+
+          def get(key, default = nil)
+            entry = @rows[key]
+            return default unless entry
+
+            if entry.expires_at < @clock.call
+              @rows.delete(key)
+              return default
+            end
+
+            entry.value
+          end
+
+          def set(key, value, ttl_seconds)
+            @rows[key] = Entry.new(value: value, expires_at: @clock.call + ttl_seconds)
+          end
+
+          def delete(key)
+            @rows.delete(key)
+          end
+        end
+
+        class EventQueueStore
+          include Protocols::EventQueueStore
+
+          def initialize
+            @events = []
+          end
+
+          def push(event)
+            @events << event.dup
+          end
+
+          def drain(max_events)
+            batch = @events.take(max_events)
+            @events = @events.drop(max_events)
+            batch
+          end
+
+          def count
+            @events.length
+          end
+        end
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/storage/protocols.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Seekmodo
+  module Sdk
+    module Storage
+      module Protocols
+        module Cache
+          def get(key, default = nil)
+            raise NotImplementedError
+          end
+
+          def set(key, value, ttl_seconds)
+            raise NotImplementedError
+          end
+
+          def delete(key)
+            raise NotImplementedError
+          end
+        end
+
+        module BreakerStateStore
+          def load(key)
+            raise NotImplementedError
+          end
+
+          def save(key, state, ttl_seconds)
+            raise NotImplementedError
+          end
+        end
+
+        module EventQueueStore
+          def push(event)
+            raise NotImplementedError
+          end
+
+          def drain(max_events)
+            raise NotImplementedError
+          end
+
+          def count
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+
+module Seekmodo
+  module Sdk
+    module Storefront
+      class Client
+        attr_reader :transport, :recommend, :bundle
+
+        def initialize(config)
+          @transport = Transport.new(**config)
+          @recommend = RecommendSurface.new(@transport)
+          @bundle = BundleSurface.new(@transport)
+        end
+
+        def search(args = {}, opts = {})
+          @transport.call("search", args, opts)
+        end
+
+        def suggest(args = {}, opts = {})
+          @transport.call("suggest", args, opts)
+        end
+
+        def search_by_image(args = {}, opts = {})
+          @transport.call("search.byImage", args, opts)
+        end
+
+        def chat(args = {}, opts = {})
+          @transport.call("chat", args, opts)
+        end
+
+        def event(args = {}, opts = {})
+          @transport.call("events", args, opts)
+        end
+
+        class RecommendSurface
+          def initialize(transport)
+            @transport = transport
+          end
+
+          def related(args = {}, opts = {})
+            @transport.call("recommend.related", args, opts)
+          end
+
+          def also_bought(args = {}, opts = {})
+            @transport.call("recommend.also_bought", args, opts)
+          end
+
+          def also_viewed(args = {}, opts = {})
+            @transport.call("recommend.also_viewed", args, opts)
+          end
+
+          def trending(args = {}, opts = {})
+            @transport.call("recommend.trending", args, opts)
+          end
+        end
+
+        class BundleSurface
+          def initialize(transport)
+            @transport = transport
+          end
+
+          def suggest(args = {}, opts = {})
+            @transport.call("bundle.suggest", args, opts)
+          end
+        end
+      end
+    end
+  end
+end