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

Browser-safe TypeScript SDK for the Seekmodo MCP gateway. Wraps the REST + JSON-RPC surfaces with namespaced methods (search, suggest, recommend.related, bundle.suggest, chat, event), an automatic 401-retry-with-fresh-token loop, and a small structured error taxonomy.

Heads up

The SDK never sees your HMAC shared secret. It only ever holds short-lived browser tokens minted by your storefront server via POST /v1/tenants/token. Keep your HMAC secret server-side — leak it and we ask you to rotate at admin.seekmodo.com → Settings.

Install

npm install @seekmodo/sdk
# or
pnpm add @seekmodo/sdk
yarn add @seekmodo/sdk

Ships ESM + CJS dual builds with full TypeScript types. Node ≥ 18. Bundle size ≈ 4 kB minified + gzipped.

Quick start

import { SeekmodoClient } from "@seekmodo/sdk";

const client = new SeekmodoClient({
  tenantId: "your-tenant-id",
  // Server-side token-mint endpoint your storefront exposes.
  // See "Authentication" below for the connector pattern.
  getToken: async () => {
    const res = await fetch("/api/seekmodo/token");
    if (!res.ok) throw new Error("token mint failed");
    return (await res.json()).token;
  },
});

// Search.
const hits = await client.search({ q: "red running shoes" });

// Recommendations.
const recs = await client.recommend.related({ source_doc_id: "sku-123" });

// Chat — Sprint 7 PR 4. Honour res.meta.suppressed in the UI.
const res = await client.chat({
  messages: [{ role: "user", content: "Got any tents under $200?" }],
});

Authentication — the browser-token flow

Seekmodo's gateway authenticates two ways:

  • HMAC envelope — server-to-server. Carries your shared secret in the signature. Required for every write tool and every admin tool.
  • Bearer JWT — browser-to-server. 5-minute HS256 token scoped to a small read-only allowlist (search, suggest, recommend, chat, events). What the SDK uses by default.

The connector pattern:

  1. Your storefront server exposes a route — typically /api/seekmodo/token — that calls POST https://api.seekmodo.com/v1/tenants/token over HMAC. The HMAC secret never leaves the server.
  2. The gateway responds with a JSON envelope: { token, expires_at, issued_at }.
  3. The storefront either embeds the JWT in a <meta name="seekmodo:token"> tag on first render, or returns it from /api/seekmodo/token when the SDK's cached JWT expires (the SDK retries once on 401).

See the starters page for complete Hydrogen + Astro examples of this pattern.

Error taxonomy

Every error the SDK raises extends SeekmodoError so you can instanceof-match without parsing strings:

ClassHTTPWhat it means
SeekmodoAuthError401 / 403Browser token expired or rejected. The SDK auto-refreshes once before bubbling.
SeekmodoQuotaError402Over plan ceiling without prepaid credits, or feature not in plan. Storefront widgets swallow silently; admin / batch callers surface the upgrade prompt.
SeekmodoServerError5xxTransient. Storefront widgets fail open to the connector's native UI.
SeekmodoRequestError400Schema validation failure. Almost always a bug in caller code.
SeekmodoNetworkError0Transport failure (DNS, TLS, abort, offline). Fail open same as 5xx.

Versioning

The SDK follows semver. Pin to ^0.1.0 while we're pre-1.0 — minor releases add tool surfaces (e.g. new recommend.* shapes); patches don't change the wire format. We tag sdk-v* in the monorepo for every release.

Links