seekmodo-sdk 0.5.0

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

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module Seekmodo
+  module Sdk
+    module Storefront
+      class Transport
+        DEFAULT_BASE_URL = "https://gateway.seekmodo.com"
+        DEFAULT_TIMEOUT_MS = 8000
+
+        def initialize(
+          tenant_id:,
+          get_token:,
+          base_url: DEFAULT_BASE_URL,
+          connection: nil,
+          timeout_ms: DEFAULT_TIMEOUT_MS,
+          signal: nil,
+          on_error: nil,
+          get_region: nil,
+          user_agent: "seekmodo-ruby-sdk/0.5.0"
+        )
+          raise ArgumentError, "Seekmodo SDK: tenant_id is required" if tenant_id.to_s.empty?
+          raise ArgumentError, "Seekmodo SDK: get_token callback is required" unless get_token.respond_to?(:call)
+
+          @tenant_id = tenant_id
+          @get_token = get_token
+          @base_url = base_url.to_s.delete_suffix("/")
+          @timeout_ms = timeout_ms
+          @signal = signal
+          @on_error = on_error
+          @get_region = get_region
+          @user_agent = user_agent
+          @cached_token = nil
+          @owns_connection = connection.nil?
+          @connection = connection || Faraday.new do |f|
+            f.options.timeout = timeout_ms / 1000.0
+            f.adapter Faraday.default_adapter
+          end
+        end
+
+        def clear_token_cache
+          @cached_token = nil
+        end
+
+        def call(tool, args = {}, opts = {})
+          begin
+            call_once(tool, args, opts, false)
+          rescue AuthError => e
+            clear_token_cache
+            begin
+              call_once(tool, args, opts, true)
+            rescue StandardError => retry_err
+              @on_error&.call(retry_err, tool: tool)
+              raise retry_err
+            end
+          rescue StandardError => e
+            @on_error&.call(e, tool: tool)
+            raise e
+          end
+        end
+
+        private
+
+        def call_once(tool, args, opts, is_retry)
+          token = resolve_token(is_retry)
+          url = "#{@base_url}/v1/#{Faraday::Utils.escape(tool)}"
+          headers = {
+            "Content-Type" => "application/json",
+            "Authorization" => "Bearer #{token}",
+            "X-Seekmodo-Tenant" => @tenant_id,
+            "X-Seekmodo-SDK" => @user_agent,
+            "User-Agent" => @user_agent
+          }
+
+          if @get_region
+            begin
+              slug = @get_region.call
+              headers["Seekmodo-Region"] = slug if slug.is_a?(String) && !slug.empty?
+            rescue StandardError
+              # ignore misconfigured region hook
+            end
+          end
+
+          timeout_ms = opts[:timeout_ms] || @timeout_ms
+          response = @connection.post(url) do |req|
+            req.headers.update(headers)
+            req.body = JSON.generate(args)
+            req.options.timeout = timeout_ms / 1000.0
+          end
+
+          body = response.body.to_s.empty? ? nil : safe_json(response.body)
+
+          if [401, 403].include?(response.status)
+            raise AuthError.new(response.status, body, tool)
+          end
+          if response.status == 402
+            raise QuotaError.new(body, tool)
+          end
+          if response.status >= 500
+            raise ServerError.new(response.status, body, tool)
+          end
+          unless response.status >= 200 && response.status < 300
+            raise RequestError.new(response.status, body, tool)
+          end
+
+          body
+        rescue Faraday::Error => e
+          raise NetworkError.new(e, tool)
+        end
+
+        def resolve_token(force_refresh)
+          now_ms = (Time.now.to_f * 1000).to_i
+          if !force_refresh && @cached_token && @cached_token[:expires_at] - 10_000 > now_ms
+            return @cached_token[:token]
+          end
+
+          result = @get_token.call
+          if result.is_a?(String)
+            @cached_token = { token: result, expires_at: now_ms + 60_000 }
+            return result
+          end
+
+          if result.is_a?(Hash) && result["token"].is_a?(String) && result["expires_at"].is_a?(Numeric)
+            @cached_token = { token: result["token"], expires_at: result["expires_at"].to_i }
+            return result["token"]
+          end
+
+          raise ArgumentError, "Seekmodo SDK: get_token must return a string or { token, expires_at }"
+        end
+
+        def safe_json(text)
+          JSON.parse(text)
+        rescue JSON::ParserError
+          text
+        end
+
+        class Error < StandardError
+          attr_reader :tool
+
+          def initialize(tool)
+            @tool = tool
+            super()
+          end
+        end
+
+        class AuthError < Error
+          attr_reader :status, :body
+
+          def initialize(status, body, tool)
+            @status = status
+            @body = body
+            super(tool)
+          end
+        end
+
+        class QuotaError < Error
+          attr_reader :body
+
+          def initialize(body, tool)
+            @body = body
+            super(tool)
+          end
+        end
+
+        class ServerError < Error
+          attr_reader :status, :body
+
+          def initialize(status, body, tool)
+            @status = status
+            @body = body
+            super(tool)
+          end
+        end
+
+        class RequestError < Error
+          attr_reader :status, :body
+
+          def initialize(status, body, tool)
+            @status = status
+            @body = body
+            super(tool)
+          end
+        end
+
+        class NetworkError < Error
+          attr_reader :cause
+
+          def initialize(cause, tool)
+            @cause = cause
+            super(tool)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/tenant_snapshot.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "connector/client"
+require_relative "storage/protocols"
+
+module Seekmodo
+  module Sdk
+    class TenantSnapshot
+      DEFAULT_TTL_SECONDS = 300
+      DEFAULT_STALE_TTL_SECONDS = 60
+      CACHE_KEY = "numinix.seekmodo.tenant_snapshot"
+      CACHE_KEY_FETCHED_AT = "numinix.seekmodo.tenant_snapshot.fetched_at"
+
+      def initialize(
+        client,
+        cache,
+        ttl_seconds: DEFAULT_TTL_SECONDS,
+        stale_after_seconds: DEFAULT_STALE_TTL_SECONDS,
+        clock: nil
+      )
+        @client = client
+        @cache = cache
+        @ttl_seconds = ttl_seconds
+        @stale_after_seconds = [stale_after_seconds, ttl_seconds].min
+        @clock = clock || -> { Time.now.to_i }
+      end
+
+      def get
+        cached = @cache.get(CACHE_KEY)
+        fetched_at = @cache.get(CACHE_KEY_FETCHED_AT, 0).to_i
+
+        if cached.is_a?(Hash) && fetched_at > 0
+          age = @clock.call - fetched_at
+          if age < @stale_after_seconds
+            return cached
+          end
+
+          begin
+            return refresh
+          rescue StandardError
+            return cached
+          end
+        end
+
+        begin
+          refresh
+        rescue StandardError
+          {}
+        end
+      end
+
+      def refresh
+        snapshot = @client.tenant_snapshot
+        @cache.set(CACHE_KEY, snapshot, @ttl_seconds)
+        @cache.set(CACHE_KEY_FETCHED_AT, @clock.call, @ttl_seconds)
+        snapshot
+      end
+
+      def forget
+        @cache.delete(CACHE_KEY)
+        @cache.delete(CACHE_KEY_FETCHED_AT)
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/tools/registry.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Seekmodo
+  module Sdk
+    module Tools
+      class Registry
+        ADMIN_PREFIXES = %w[
+          synonyms. pins. ltr. analytics. tenant. merchandising. experiments.
+          catalog. queries. segments. banners. deboosts. esp. regions.
+          recommendations. bundles. image_search. bot_check. schema.
+        ].freeze
+
+        ADMIN_TOOLS = %w[
+          synonyms.list synonyms.add synonyms.remove
+          pins.list pins.set pins.remove
+          ltr.status ltr.retrain ltr.toggle ltr.config.set
+          analytics.top_queries analytics.zero_results
+          tenant.snapshot tenant.config tenant.config.set
+        ].freeze
+
+        def initialize(connector: nil, admin: nil, tenant_id: nil)
+          @connector = connector
+          @admin = admin
+          @tenant_id = tenant_id
+        end
+
+        def call(tool, args = {}, tenant_id: @tenant_id)
+          normalized = normalize_tool(tool)
+          if admin_tool?(normalized)
+            unless @admin
+              raise ArgumentError, "Admin client required for tool #{normalized}"
+            end
+            unless tenant_id
+              raise ArgumentError, "tenant_id required for admin tool #{normalized}"
+            end
+            return @admin.call(normalized, args, tenant_id: tenant_id)
+          end
+
+          unless @connector
+            raise ArgumentError, "Connector client required for tool #{normalized}"
+          end
+
+          route_connector(normalized, args)
+        end
+
+        private
+
+        def normalize_tool(tool)
+          tool.to_s.tr("_", ".")
+        end
+
+        def admin_tool?(tool)
+          return true if ADMIN_TOOLS.include?(tool)
+          return true if tool.start_with?("admin.")
+
+          ADMIN_PREFIXES.any? { |prefix| tool.start_with?(prefix) }
+        end
+
+        def route_connector(tool, args)
+          case tool
+          when "search"
+            @connector.search(args)
+          when "index"
+            documents = args["documents"] || args[:documents] || []
+            action = args["action"] || args[:action] || "upsert"
+            @connector.index(documents, action: action)
+          when "events"
+            events = args["events"] || args[:events] || []
+            @connector.events(events)
+          when "tenant.handshake"
+            @connector.tenant_handshake
+          when "tenant.snapshot"
+            @connector.tenant_snapshot
+          when "tenants/token"
+            audience = args["audience"] || args[:audience]
+            @connector.browser_token(audience)
+          when "tools"
+            @connector.tools
+          when "health"
+            @connector.health
+          else
+            @connector.post_json("/v1/#{tool}", args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Seekmodo
+  module Sdk
+    VERSION = "0.5.0"
+  end
+end

data/lib/seekmodo/sdk.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "sdk/version"
+require_relative "sdk/exceptions/seekmodo_error"
+require_relative "sdk/exceptions/client_error"
+require_relative "sdk/exceptions/tenant_unavailable_error"
+require_relative "sdk/exceptions/over_quota_error"
+require_relative "sdk/exceptions/signature_mismatch_error"
+require_relative "sdk/exceptions/breaker_open_error"
+require_relative "sdk/hmac_signer"
+require_relative "sdk/mode"
+require_relative "sdk/circuit_breaker"
+require_relative "sdk/connector/client"
+require_relative "sdk/tenant_snapshot"
+require_relative "sdk/mode_fsm"
+require_relative "sdk/auto_promoter"
+require_relative "sdk/pairing"
+require_relative "sdk/browser_token"
+require_relative "sdk/signature_mismatch_tracker"
+require_relative "sdk/storage/protocols"
+require_relative "sdk/storage/memory/stores"
+require_relative "sdk/events/click_beacon"
+require_relative "sdk/events/events_queue"
+require_relative "sdk/storefront/transport"
+require_relative "sdk/storefront/client"
+require_relative "sdk/admin/client"
+require_relative "sdk/mcp/client"
+require_relative "sdk/tools/registry"
+
+module Seekmodo
+  module Sdk
+  end
+end

data/lib/seekmodo-sdk.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "seekmodo/sdk"

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: seekmodo-sdk
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Seekmodo
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: Ruby SDK for the Seekmodo MCP gateway with HMAC connector transport,
+  JWT storefront client, admin tools, and JSON-RPC MCP support.
+email:
+- support@seekmodo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- README.md
+- docs/tool-catalog.README.md
+- lib/seekmodo-sdk.rb
+- lib/seekmodo/sdk.rb
+- lib/seekmodo/sdk/admin/client.rb
+- lib/seekmodo/sdk/auto_promoter.rb
+- lib/seekmodo/sdk/browser_token.rb
+- lib/seekmodo/sdk/circuit_breaker.rb
+- lib/seekmodo/sdk/connector/client.rb
+- lib/seekmodo/sdk/events/click_beacon.rb
+- lib/seekmodo/sdk/events/events_queue.rb
+- lib/seekmodo/sdk/exceptions/breaker_open_error.rb
+- lib/seekmodo/sdk/exceptions/client_error.rb
+- lib/seekmodo/sdk/exceptions/over_quota_error.rb
+- lib/seekmodo/sdk/exceptions/seekmodo_error.rb
+- lib/seekmodo/sdk/exceptions/signature_mismatch_error.rb
+- lib/seekmodo/sdk/exceptions/tenant_unavailable_error.rb
+- lib/seekmodo/sdk/hmac_signer.rb
+- lib/seekmodo/sdk/mcp/client.rb
+- lib/seekmodo/sdk/mode.rb
+- lib/seekmodo/sdk/mode_fsm.rb
+- lib/seekmodo/sdk/pairing.rb
+- lib/seekmodo/sdk/signature_mismatch_tracker.rb
+- lib/seekmodo/sdk/storage/memory/stores.rb
+- lib/seekmodo/sdk/storage/protocols.rb
+- lib/seekmodo/sdk/storefront/client.rb
+- lib/seekmodo/sdk/storefront/transport.rb
+- lib/seekmodo/sdk/tenant_snapshot.rb
+- lib/seekmodo/sdk/tools/registry.rb
+- lib/seekmodo/sdk/version.rb
+homepage: https://seekmodo.com/docs/sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://seekmodo.com/docs/sdk
+  source_code_uri: https://github.com/numinix/seekmodo-ruby-sdk
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Seekmodo Ruby SDK — connector, storefront, admin, and MCP clients
+test_files: []