Seekmodo

Seekmodo developer docs

Reference for the REST shim, MCP JSON-RPC surface, and storefront connectors. Authenticate with HMAC; replay window is 5 minutes.

seekmodo-sdk

Full-featured Ruby SDK for the Seekmodo gateway. One gem ships four clients — HMAC connector, browser JWT storefront, admin-key automation, and MCP JSON-RPC — plus a dynamic tools registry for the full gateway catalog.

When to reach for this

Use Connector::Client for Rails storefront connectors and Sidekiq indexing jobs. Use Storefront::Client in a Sinatra/Rails BFF that mints browser tokens server-side. Use Admin::Client for operator scripts. For browser widgets, prefer the JavaScript SDK.

Install

gem install seekmodo-sdk

Requires Ruby >=3.1. Runtime dependencies: faraday, jwt.

Connector quick start

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)

client.search({ "q" => "red sneakers", "per_page" => 24 })
client.index(documents, action: "upsert")
client.tenant_snapshot # POST /v1/tenant.snapshot

Clients

  • Connector — HMAC transport, circuit breaker, mode FSM, pairing, browser-token mint, events batcher.
  • Storefront — JWT client: search, suggest, search_by_image, chat, recommend.*, bundle.suggest.
  • Admin — synonyms, pins, LTR, analytics via X-Seekmodo-Admin-Key (server-only).
  • MCP — JSON-RPC initialize, tools/list, tools/call with HMAC or operator bearer.
  • Tools::Registry — dynamic call("synonyms.add", …) for any catalog tool.

Wire contract tests

Run bundle exec rspec spec/contracts — same 10 gateway wire tests as the PHP and Python SDKs.

Repo: github.com/numinix/seekmodo-ruby-sdk.