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/web-components

Framework-agnostic custom elements that consume the SDK. Drop them into any HTML page — no React, Vue, or build step required — and they read your tenant id + browser token from <meta> tags.

Two ways to install

  • Bundler: npm install @seekmodo/web-components then import "@seekmodo/web-components" once.
  • CDN: <script type="module" src="https://cdn.jsdelivr.net/npm/@seekmodo/web-components"></script>

Tenant + token wiring

Each component reads three <meta> tags at first render:

<meta name="seekmodo:tenant" content="your-tenant-id" />
<meta name="seekmodo:token" content="<5-min JWT minted server-side>" />
<meta name="seekmodo:gateway" content="https://api.seekmodo.com" />

<!-- Optional: SDK auto-refresh URL when the token expires mid-session -->
<meta name="seekmodo:token-refresh-url" content="/api/seekmodo/token" />

See the starters page for the full Hydrogen and Astro implementations of the token-mint side of this contract.

Components

<seekmodo-search-box>

Controlled search input. Emits seekmodo:search on submit with { query }.

Attributes

  • placeholder — Default "Search products".
  • value — Initial value. Updates preserve focus.
  • submit-label — Default "Search".

Events

  • seekmodo:search — { query: string } — fired on form submit.
  • seekmodo:input — { query: string } — fired on every keystroke.

CSS parts: inputsubmit

Meters: 0× (no gateway call until results fire).

<seekmodo-results>

Pageable results list. Calls client.search() when .setQuery(q) is invoked or a seekmodo:search event bubbles in.

Attributes

  • per-page — Default "20". Clamped to 100.
  • collection — Override the default tenant collection.

Events

  • seekmodo:results — { hits, found, page } — fires after every successful query.

CSS parts: listitempagination

Meters: 1× searches per query (Sprint 1 metering).

<seekmodo-facets>

Renders the facet tree from the last seekmodo-results response. Emits seekmodo:facet-change.

Attributes

  • max-values — Default "8" per facet group.

Events

  • seekmodo:facet-change — { filter_by, selected } — apply to your next results query (also re-emitted as a search).

CSS parts: grouplabelcheckbox

Meters: 0× — facets are returned inline with search results.

<seekmodo-typeahead>

Debounced suggestions overlay. Subscribes to seekmodo:input from a search box and calls client.suggest().

Attributes

  • debounce-ms — Default "120".
  • limit — Default "6".

Events

  • seekmodo:typeahead-pick — { query } — fires when the shopper picks a suggestion.

CSS parts: dropdownitem

Meters: 1× searches per non-debounced keystroke (Sprint 3 metering).

<seekmodo-recommendations>

Hydrates a placement strip from recommend.*. Reads the placement + anchor from attributes.

Attributes

  • placement — Required. One of "pdp-related", "pdp-also-bought", "cart-also-bought", "home-trending".
  • anchor-doc-id — Required for non-trending placements.
  • limit — Default "8".

Events

  • seekmodo:recommendations — { hits, placement } — fires after a successful fetch.

CSS parts: listitem

Meters: 1× searches per render (Sprint 4 metering).

<seekmodo-banner-slot>

Renders merchandised banners filtered by position. Hydrated by seekmodo-results responses.

Attributes

  • position — Required. e.g. "top", "sidebar", "footer".

CSS parts: banner

Meters: 0× — banners ride along the same searches call.

<seekmodo-chat>

Conversational shopper assistant. Honours meta.suppressed by rendering an upgrade affordance.

Attributes

  • intro — Opening assistant message.
  • placeholder — Composer placeholder.
  • max-turns — Default "12".
  • auto-citations — When present, render product chips.

Events

  • seekmodo:chat-turn — { message, citations, meta } — fires on every assistant turn.
  • seekmodo:chat-suppressed — { reason } — fires when meta.suppressed=true.

CSS parts: transcriptturncomposerinputsubmitupgrade

Meters: 1× searches per outer chat call + 1× searches_chat per sub-tool call (Sprint 7 metering). See /docs/chat for the worked example.

Styling

Every component scopes its styles inside a Shadow DOM root so they don't collide with your storefront CSS. Override via:

  • CSS variables on the host (or any ancestor) — e.g. seekmodo-search-box { --seekmodo-submit-bg: #111; }.
  • CSS ::part selectors for fine-grained layout — e.g. seekmodo-results::part(item) { border-radius: 0; }.
  • Named slots for content overrides — most components expose at least a default slot; seekmodo-chat additionally exposes slot="upgrade" for the suppression affordance.

Links