seekmodo-sdk 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a3051fcfcab7839036fb801ec2c2570395dc8f77b4657b48f9ff181c011c727
+  data.tar.gz: ab157610976b2dd2232f5fd1d7a3287efca2d7d866912c9dbf13b4d8dd68e302
+SHA512:
+  metadata.gz: 1619b839b83c2118f0b56482c186b08ebe11ceb7cc0b6ed9692249b08d50ec5395a5355b5cb75649277be5c086933e312af16d9e7b4682faa8410d7802172545
+  data.tar.gz: 65dcffd819b63e19a3bd84d59e96c398eab90b5ccee08cf08e819cfd8eb31354eac974dbd569c9c97654c91d9c5cb90559b2c5842d69b6f5ae3123834494ee97

data/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ["3.1", "3.2", "3.3"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+      - name: Configure trusted publisher credentials (OIDC)
+        id: oidc
+        uses: rubygems/configure-rubygems-credentials@v1.0.0
+        continue-on-error: true
+      - name: Configure API key fallback
+        if: steps.oidc.outcome == 'failure'
+        run: |
+          mkdir -p ~/.gem
+          cat > ~/.gem/credentials <<EOF
+          ---
+          :rubygems_api_key: ${RUBYGEMS_API_KEY}
+          EOF
+          chmod 600 ~/.gem/credentials
+        env:
+          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+      - run: gem build seekmodo-sdk.gemspec
+      - run: gem push seekmodo-sdk-*.gem

data/.gitignore

@@ -0,0 +1,12 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  Exclude:
+    - "vendor/**/*"
+    - "spec/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 140
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "seekmodo-sdk.gemspec"
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/AbcSize:
+  Max: 35
+
+Metrics/ClassLength:
+  Max: 200

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.60"
+  gem "webmock", "~> 3.23"
+end

data/README.md

@@ -0,0 +1,135 @@
+# Seekmodo Ruby SDK
+
+Shared Ruby SDK for building [Seekmodo](https://seekmodo.com) storefront connectors, admin automation, and MCP agents. The gem ships four clients behind one namespace (`Seekmodo::Sdk`):
+
+| Client | Auth | Base URL | Use when |
+|--------|------|----------|----------|
+| `Connector::Client` | HMAC (`tenant_id` + `shared_secret`) | `https://mcp.seekmodo.com` | Server-side connector: index catalog, batch events, handshake, mint browser tokens |
+| `Storefront::Client` | JWT Bearer (`get_token` callback) | `https://gateway.seekmodo.com` | Storefront widgets, headless apps, anything that runs in the browser or on a token-minting server |
+| `Admin::Client` | `X-Seekmodo-Admin-Key` | `https://mcp.seekmodo.com` | Operator/admin automation: synonyms, pins, LTR, analytics |
+| `Mcp::Client` | HMAC **or** operator bearer | `https://mcp.seekmodo.com/mcp` | JSON-RPC MCP (`initialize`, `tools/list`, `tools/call`) for AI agents |
+
+**Status**: 0.5.0 · Ruby 3.1+
+
+## Install
+
+```bash
+gem install seekmodo-sdk
+```
+
+Or in Bundler:
+
+```ruby
+gem "seekmodo-sdk", "~> 0.5"
+```
+
+Runtime dependencies: `faraday`, `jwt`.
+
+## Quick starts
+
+### Connector (HMAC)
+
+```ruby
+require "seekmodo/sdk"
+
+signer = Seekmodo::Sdk::HmacSigner.new("your-tenant-id", "your-shared-secret")
+breaker = Seekmodo::Sdk::CircuitBreaker.new(Seekmodo::Sdk::Storage::Memory::BreakerStore.new)
+client = Seekmodo::Sdk::Connector::Client.new(signer, breaker: breaker)
+
+results = client.search({ "q" => "red running shoes", "per_page" => 24 })
+client.index(documents, action: "upsert") # auto-chunks at 500
+client.tenant_snapshot # POST /v1/tenant.snapshot
+```
+
+### Storefront (JWT)
+
+```ruby
+client = Seekmodo::Sdk::Storefront::Client.new(
+  tenant_id: "redline",
+  get_token: -> { connector.browser_token["token"] }
+)
+
+hits = client.search({ "q" => "spark plug" })
+recs = client.recommend.related({ "source_doc_id" => "sku-123" })
+bundles = client.bundle.suggest({ "source_doc_id" => "sku-123" })
+```
+
+### Admin
+
+```ruby
+admin = Seekmodo::Sdk::Admin::Client.new(admin_key: ENV.fetch("MCP_ADMIN_KEY"))
+
+synonyms = admin.list_synonyms("redline")
+admin.add_synonym("redline", { "synonyms" => %w[spark plug] })
+pins = admin.list_pins("redline")
+ltr = admin.ltr_status("redline")
+top = admin.analytics_top_queries("redline", window: "7d")
+zeros = admin.analytics_zero_results("redline")
+```
+
+### MCP JSON-RPC
+
+```ruby
+# HMAC (tenant connector)
+mcp = Seekmodo::Sdk::Mcp::Client.new(signer: signer)
+mcp.initialize_session({ "clientInfo" => { "name" => "my-agent" } })
+tools = mcp.tools_list
+result = mcp.tools_call("search", { "q" => "brake pads" })
+
+# Operator bearer
+mcp = Seekmodo::Sdk::Mcp::Client.new(
+  operator_token: ENV.fetch("SEEKMODO_OPERATOR_TOKEN"),
+  tenant_id: "redline"
+)
+mcp.tools_call("analytics.zero_results", { "limit" => 10 })
+```
+
+### Tools registry
+
+```ruby
+registry = Seekmodo::Sdk::Tools::Registry.new(
+  connector: connector_client,
+  admin: admin_client,
+  tenant_id: "redline"
+)
+registry.call("search", { "q" => "oil filter" })
+registry.call("synonyms.list", {})
+```
+
+## Public surface
+
+| Module / class | What it does |
+|----------------|--------------|
+| `Connector::Client` | `search`, `index`, `events`, `tenant_handshake`, `tenant_snapshot`, `browser_token`, `tools`, `health` |
+| `HmacSigner` | Builds the three `X-Seekmodo-*` headers |
+| `CircuitBreaker` | Three-state FSM (closed/open/half_open) with pluggable storage |
+| `TenantSnapshot` | Polls `tenant.snapshot` with stale-while-revalidate cache |
+| `ModeFsm` | Resolves effective connector mode |
+| `AutoPromoter` | Walks `active` tenants through shadow → enforce |
+| `Pairing` | Verifies EdDSA pairing JWTs against Seekmodo JWKS |
+| `BrowserToken` | Mints `/v1/tenants/token` browser JWTs with TTL-aware caching |
+| `EventsQueue` | Batches events into single `POST /v1/events` calls |
+| `Events::ClickBeacon` | Pure-function payload builders for beacons |
+| `Storefront::Client` | Typed `search`, `suggest`, `search_by_image`, `chat`, `event`, `recommend.*`, `bundle.suggest` |
+| `Admin::Client` | Typed admin tools + generic `call(tool, body, tenant_id:)` |
+| `Mcp::Client` | `initialize_session`, `tools_list`, `tools_call`, `ping` |
+| `Tools::Registry` | Routes normalized tool names to connector or admin |
+
+## Wire contract tests
+
+Fixtures under `spec/contracts/fixtures/` mirror the PHP SDK contract pack.
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Versioning
+
+Follows semver. Breaking wire or type changes are major bumps; new methods and optional fields are minors; bug fixes are patches.
+
+## Links
+
+- [Python SDK (reference parity)](https://github.com/numinix/seekmodo-python-sdk)
+- [PHP SDK (wire fixtures source)](https://github.com/numinix/seekmodo-php-sdk)

data/docs/tool-catalog.README.md

@@ -0,0 +1,12 @@
+# Tool catalog manifest
+
+Regenerate from the Seekmodo monorepo when gateway tools change:
+
+```bash
+cd seekmodo.com/seekmodo
+composer install -d services/mcp-gateway
+php tools/export_tool_catalog.php --out=../seekmodo-ruby-sdk/docs/tool-catalog.json
+php tools/export_tool_catalog.php --out=../seekmodo-go-sdk/docs/tool-catalog.json
+```
+
+The manifest drives SDK docs and optional codegen for `Tools::Registry` typed helpers.

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module Seekmodo
+  module Sdk
+    module Admin
+      class Error < StandardError
+        attr_reader :status, :body
+
+        def initialize(status, body)
+          @status = status
+          @body = body
+          super("gateway #{status}: #{body.to_s[0, 200]}")
+        end
+      end
+
+      class Client
+        DEFAULT_GATEWAY_URL = "https://mcp.seekmodo.com"
+
+        def initialize(admin_key:, gateway_url: DEFAULT_GATEWAY_URL, connection: nil, user_agent: "Seekmodo-Admin/1.0")
+          @admin_key = admin_key
+          @gateway_url = gateway_url.to_s.delete_suffix("/")
+          @user_agent = user_agent
+          @connection = connection || Faraday.new do |f|
+            f.adapter Faraday.default_adapter
+          end
+        end
+
+        def call(tool, body, tenant_id:)
+          path = tool.start_with?("/") ? tool : "/v1/admin/#{normalize_tool(tool)}"
+          call_rest(path, body.merge("tenant_id" => tenant_id), tenant_id: tenant_id)
+        end
+
+        def list_synonyms(tenant_id)
+          result = call("synonyms.list", {}, tenant_id: tenant_id)
+          result.fetch("synonyms", [])
+        end
+
+        def add_synonym(tenant_id, body)
+          call("synonyms.add", body, tenant_id: tenant_id)
+        end
+
+        def remove_synonym(tenant_id, id)
+          call("synonyms.remove", { "id" => id }, tenant_id: tenant_id)
+        end
+
+        def list_pins(tenant_id)
+          result = call("pins.list", {}, tenant_id: tenant_id)
+          result.fetch("pins", [])
+        end
+
+        def set_pins(tenant_id, body)
+          call("pins.set", body, tenant_id: tenant_id)
+        end
+
+        def ltr_status(tenant_id, history_limit: nil, history_offset: nil)
+          params = {}
+          if history_limit
+            params["history_limit"] = [[history_limit, 1].max, 50].min
+          end
+          if history_offset
+            params["history_offset"] = [[history_offset, 0].max, 10_000].min
+          end
+          call("ltr.status", params, tenant_id: tenant_id)
+        end
+
+        def ltr_retrain(tenant_id)
+          call("ltr.retrain", {}, tenant_id: tenant_id)
+        end
+
+        def analytics_top_queries(tenant_id, window: "7d", limit: 20)
+          result = call(
+            "analytics.top_queries",
+            { "window" => window, "limit" => limit },
+            tenant_id: tenant_id
+          )
+          result.fetch("rows", [])
+        end
+
+        def analytics_zero_results(tenant_id, window: "7d", limit: 20)
+          result = call(
+            "analytics.zero_results",
+            { "window" => window, "limit" => limit },
+            tenant_id: tenant_id
+          )
+          result.fetch("rows", [])
+        end
+
+        private
+
+        def call_rest(path, body, tenant_id:)
+          response = @connection.post(@gateway_url + path) do |req|
+            req.headers.update(
+              "Content-Type" => "application/json",
+              "X-Seekmodo-Admin-Key" => @admin_key,
+              "X-Seekmodo-Tenant" => tenant_id,
+              "User-Agent" => @user_agent
+            )
+            req.body = JSON.generate(body)
+          end
+
+          text = response.body.to_s
+          unless response.status >= 200 && response.status < 300
+            raise Error.new(response.status, text)
+          end
+
+          text.empty? ? nil : JSON.parse(text)
+        rescue JSON::ParserError => e
+          raise Error.new(response.status, "invalid JSON: #{e.message}")
+        end
+
+        def normalize_tool(tool)
+          tool.to_s.tr("_", ".")
+        end
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/auto_promoter.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "mode"
+require_relative "circuit_breaker"
+require_relative "tenant_snapshot"
+require_relative "storage/protocols"
+
+module Seekmodo
+  module Sdk
+    class AutoPromoter
+      STATE_KEY = "numinix.seekmodo.fsm_state"
+      DEFAULT_PROMOTE_AFTER_SECONDS = 3600
+      DEFAULT_DEMOTE_COOLDOWN_SECONDS = 900
+
+      def initialize(
+        snapshot,
+        breaker,
+        cache,
+        promote_after_seconds: DEFAULT_PROMOTE_AFTER_SECONDS,
+        demote_cooldown_seconds: DEFAULT_DEMOTE_COOLDOWN_SECONDS,
+        clock: nil
+      )
+        @snapshot = snapshot
+        @breaker = breaker
+        @cache = cache
+        @promote_after_seconds = promote_after_seconds
+        @demote_cooldown_seconds = demote_cooldown_seconds
+        @clock = clock || -> { Time.now.to_i }
+      end
+
+      def tick
+        config = @snapshot.get
+        configured_mode = config.fetch("mode", Mode::OFF).to_s
+        auto_promote = config.fetch("auto_promote", true)
+
+        if configured_mode != Mode::ACTIVE
+          return result(Mode::OFF, Mode::OFF, "held", "mode is not active; auto-promoter idle")
+        end
+        unless auto_promote
+          return result(Mode::OFF, Mode::OFF, "held", "auto_promote disabled")
+        end
+
+        state = load_state
+        current = state["current_state"].to_s
+        now = @clock.call
+        breaker_snapshot = @breaker.snapshot
+        breaker_open = breaker_snapshot["state"] == CircuitBreaker::STATE_OPEN
+
+        if breaker_open && current == Mode::ENFORCE
+          if now - state["last_transition_at"].to_i < @demote_cooldown_seconds
+            return result(current, current, "held", "demote cooldown active")
+          end
+          write_state(Mode::SHADOW, now)
+          return result(current, Mode::SHADOW, "demoted", "breaker open at enforce")
+        end
+
+        settled_for = now - state["last_transition_at"].to_i
+        if breaker_open
+          return result(current, current, "held", "breaker open")
+        end
+        if settled_for < @promote_after_seconds
+          return result(current, current, "held", "settled for #{settled_for}s, need #{@promote_after_seconds}s")
+        end
+
+        next_step = next_step_up(current)
+        if next_step == current
+          return result(current, current, "held", "already at enforce")
+        end
+        write_state(next_step, now)
+        result(current, next_step, "promoted", "breaker closed, settled")
+      end
+
+      def current_state
+        load_state
+      end
+
+      private
+
+      def next_step_up(current)
+        if [Mode::OFF, Mode::LEARNING].include?(current)
+          return Mode::SHADOW
+        end
+        return Mode::ENFORCE if current == Mode::SHADOW
+
+        current
+      end
+
+      def load_state
+        raw = @cache.get(STATE_KEY)
+        unless raw.is_a?(Hash)
+          now = @clock.call
+          return { "current_state" => Mode::SHADOW, "last_transition_at" => now }
+        end
+
+        current_raw = raw["current_state"].to_s
+        current = Mode.valid?(current_raw) ? current_raw : Mode::SHADOW
+        {
+          "current_state" => current,
+          "last_transition_at" => raw.fetch("last_transition_at", 0).to_i
+        }
+      end
+
+      def write_state(new_state, transitioned_at)
+        @cache.set(
+          STATE_KEY,
+          {
+            "current_state" => Mode.assert_mode(new_state),
+            "last_transition_at" => transitioned_at
+          },
+          86400
+        )
+      end
+
+      def result(from_state, to_state, action, reason)
+        {
+          "from" => from_state,
+          "to" => to_state,
+          "action" => action,
+          "reason" => reason
+        }
+      end
+    end
+  end
+end

data/lib/seekmodo/sdk/browser_token.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "connector/client"
+require_relative "exceptions/client_error"
+require_relative "storage/protocols"
+
+module Seekmodo
+  module Sdk
+    class BrowserToken
+      CACHE_KEY = "numinix.seekmodo.browser_token"
+      SAFETY_MARGIN_SECONDS = 60
+
+      def initialize(client, cache, clock: nil)
+        @client = client
+        @cache = cache
+        @clock = clock || -> { Time.now.to_i }
+      end
+
+      def token(audience = nil, force: false)
+        cache_key = "#{CACHE_KEY}:#{audience || 'default'}"
+        unless force
+          cached = @cache.get(cache_key)
+          if cached.is_a?(Hash)
+            expires_at = cached.fetch("expires_at", 0).to_i
+            if expires_at > @clock.call + SAFETY_MARGIN_SECONDS
+              return {
+                "token" => cached["token"].to_s,
+                "expires_at" => expires_at,
+                "issued_at" => cached.fetch("issued_at", @clock.call).to_i
+              }
+            end
+          end
+        end
+
+        response = @client.browser_token(audience)
+        token = response["token"].to_s
+        expires_at = response.fetch("expires_at", 0).to_i
+        issued_at = response.fetch("issued_at", @clock.call).to_i
+
+        if token.empty? || expires_at.zero?
+          raise ClientError.new(
+            "Gateway tenants.token response missing token/expires_at fields.",
+            ClientError::KIND_BAD_RESPONSE
+          )
+        end
+
+        value = {
+          "token" => token,
+          "expires_at" => expires_at,
+          "issued_at" => issued_at
+        }
+        ttl = [expires_at - @clock.call - SAFETY_MARGIN_SECONDS, 1].max
+        @cache.set(cache_key, value, ttl)
+        value
+      end
+
+      def forget(audience = nil)
+        @cache.delete("#{CACHE_KEY}:#{audience || 'default'}")
+      end
+    end
+  end
+end