JavaScript / TypeScript

The JavaScript / TypeScript SDK is @seekgist/sdk. It works in browsers, Node 20+, Deno, Bun and edge runtimes: it uses only fetch and Web Crypto. It is ESM only and fully typed. The API methods are generated from the OpenAPI file; the helpers are written by hand.

Quick start

import { SeekGist } from "@seekgist/sdk";
 
const client = new SeekGist({ apiKey: process.env.SEEKGIST_API_KEY }); // or set SEEKGIST_API_KEY
 
const res = await client.find("فستان سهرة تحت 100", { lang: "ar", per_page: 12 });
res.data.ids;      // product ids in rank order
res.data.hits;     // product cards
res.usage;         // { searches, limit, billed, period } from X-SeekGist-Usage
res.requestId;     // quote it to support

Keys: a public key (sg_pub_...) is safe in the browser. A secret key (sg_sec_...) is for your server only: the client refuses it in a browser.

Options: baseUrl (default https://api.seekgist.com), timeoutMs (10,000 per attempt), maxRetries (2), headers, fetch, and keyInQuery (sends a public key as ?key= on GET calls, so the browser skips the CORS preflight).

The suggester waits until the shopper stops typing (120 ms), cancels out-of-date calls and keeps recent answers. Suggestions are never billed.

const s = client.suggester({ lang: "auto", products: 3 });
input.addEventListener("input", async () => render(await s.input(input.value)));

Sync your catalog (server)

upsertProducts sends batches of up to 1,000 with one Idempotency-Key per batch and 5 retries. Running it again with the same keyPrefix is a safe resume. replaceAll makes it a full sync: products you did not send are removed.

const sum = await client.upsertProducts(products, { replaceAll: true, keyPrefix: `nightly-${date}` });
// sum: { batches, upserted, unchanged, deleted, errors: [{ batch, index, id, code, message }] }

Every API method

One namespace per API area, one method per endpoint: client.search, events, catalog, imports, connectors, jobs, synonyms, rules, experiments, translation, assistant, analytics, webhooks, account, billing, health, files.

await client.synonyms.create({ body: { kind: "equivalent", terms: ["sneakers", "trainers", "سنيكرز"] } });
await client.catalog.productsGet({ product_id: "42" });
const r = await client.request("search_post", { body: { q: "dress" } }); // any endpoint by its operationId

Every method takes options last: { timeoutMs, maxRetries, idempotencyKey, headers, query, signal }.

Helpers

Helper	What it does
`client.find(q, fields)`	`POST /v1/search`; returns the full answer with `usage`
`client.suggester(options)`	Debounced suggestions for a search box
`client.upsertProducts(products, options)`	Batched, safe catalog sync
`client.waitForJob(id)`	Waits for a job (reindex, import, translation) to finish
`client.pages(cursor => ...)`	`for await` over every item of a list
`verifyWebhook({ secret, headers, body })`	Checks a webhook signature and its time (5 minutes)
`parseUsage(header)`	Reads `X-SeekGist-Usage`

// Webhook receiver: pass the RAW body, not a re-encoded one.
const event = await verifyWebhook({ secret: process.env.SEEKGIST_WEBHOOK_SECRET!, headers: req.headers, body: rawBody });

Errors and retries

ApiError: the API answered with an error (status, code, requestId, fieldErrors, retryAfterS). Use code in your program.
TimeoutError, ConnectionError: no answer. WebhookVerificationError: a bad webhook.
Retries (default 2, waiting 0.5 s, 1 s, 2 s and so on, with jitter; Retry-After wins): GET calls, search, and writes with an Idempotency-Key (the SDK adds one and keeps it for every retry). Clicks, events and chat are never retried after a network error or a 5xx, so nothing is counted twice. A 429 is retried for every call.
On a store search page, use timeoutMs: 300, maxRetries: 0 and show your own search on any error. See Store fallback.

Examples

In the repository: packages/sdk-js/examples/search.mjs (search and suggest in Node), browser-suggest.html (a search box), sync-catalog.mjs (batch upsert) and webhook-receiver.mjs.