Seekmodo

Seekmodo developer docs

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

Headless storefront starters

Two reference repos that wire Seekmodo into a fresh headless storefront in under 30 minutes. Both consume @seekmodo/sdk + @seekmodo/web-components from public npm and demonstrate the same four surfaces — search, facets, recommendations, and chat — so you can pick the stack you already use.

What the starters are not

They're intentionally minimal — no design system, no auth, no checkout flow. The goal is to show the connector pattern (server-side HMAC → 5-minute JWT → browser SDK / web-components) clearly, then delete the placeholder UI as you graft Seekmodo onto your real storefront.

seekmodo-hydrogen-starter

Shopify Hydrogen (Remix + Vite + React + Oxygen workers)

Live preview ↗Request the source ↗

Routes

  • / — Search box + facets + results + chat.
  • /products/:handle — PDP with the recommendations strip.
  • /api/seekmodo/token — Server-only token mint endpoint.

What it shows

  • Server-side browser-token mint in app/root.tsx loader — JWT embedded in <meta> on every full render.
  • SDK auto-refresh route at /api/seekmodo/token uses the same HMAC envelope server-side.
  • PDP recommendations strip via <seekmodo-recommendations placement="pdp-related">.
  • <seekmodo-chat> with a slot="upgrade" override showing the storefront-branded affordance.
Preview iframe

seekmodo-astro-starter

Astro 5 + Node SSR adapter

Live preview ↗Request the source ↗

Routes

  • / — Search box + facets + results + chat.
  • /products/[handle] — PDP with the recommendations strip.
  • /api/seekmodo/token — Server-only token mint endpoint.

What it shows

  • Server-side browser-token mint in src/layouts/Base.astro.
  • Astro server endpoint at src/pages/api/seekmodo/token.ts for SDK auto-refresh.
  • Tiny inline <script> bridges search-box submit events to the results element — no useEffect needed.
  • Demonstrates output: "server" — static mode would bake a stale JWT into the build artifact.
Preview iframe

Quick-start checklist

Same shape for both starters once you have the source package:

  1. Unpack the starter you requested from support into a fresh directory.
  2. npm install
  3. Copy .env.example to .env and fill in SEEKMODO_TENANT_ID + SEEKMODO_HMAC_SECRET (from admin.seekmodo.com → Settings).
  4. npm run dev — search, recs, and chat are live.
  5. Replace the placeholder PDP loader with your real catalog (Storefront API, headless CMS, whatever you use).
  6. Style via CSS variables / ::part selectors — see Web Components → Styling.

Versioning + drift safety

Each starter pins ^0.1.0 of both packages and ships a CI workflow that installs the latest published SDK on every push, so a breaking change on our side fails the starter's build before it fails yours. New SDK releases are announced on the changelog stream linked from the SDK reference.

Building your own starter

Both starters above start as the same scaffold pattern: server-side HMAC envelope minting a 5-minute browser JWT, SDK or web-components consuming the JWT in the browser, and a token-refresh route on the server. If you're wiring a stack we don't cover (Next.js commerce, SvelteKit, Nuxt, Eleventy) and want a hand, drop us a note — we'll publish your stack alongside Hydrogen and Astro.

Links