@suggestapi/sdk

Official JavaScript and TypeScript SDK for SuggestAPI.

This package is designed around the current SuggestAPI docs and splits usage into two main entrypoints:

• @suggestapi/sdk/browser for browser-safe search flows
• @suggestapi/sdk/node for full server-side access, including indexing and document writes

Install

npm install @suggestapi/sdk

Quickstart

import { createSuggestApiClient } from "@suggestapi/sdk/node";

const client = createSuggestApiClient({
  apiKey: process.env.SUGGESTAPI_PUBLIC_KEY
});

const response = await client.search.autocomplete({
  index: "products",
  query: "ptfe pump",
  limit: 5,
  mode: "hybrid"
});

console.log(response.suggestions);

Browser search

import { createSuggestApiBrowserClient } from "@suggestapi/sdk/browser";

const client = createSuggestApiBrowserClient({
  apiKey: window.SUGGESTAPI_PUBLIC_KEY
});

const response = await client.search.typeahead({
  index: "products",
  query: "ptf",
  limit: 5
});

Direct browser load from CDN

If you want to use the SDK without a bundler, the package also ships a browser global bundle.

Versioned example for the current package version:

<script src="https://cdn.jsdelivr.net/npm/@suggestapi/[email protected]/dist/suggestapi.global.min.js"></script>
<script>
  const client = SuggestApi.createSuggestApiBrowserClient({
    apiKey: "your_public_key"
  });
</script>

The global name is SuggestApi.

If you prefer to always load the latest published version, you can omit the version segment:

<script src="https://cdn.jsdelivr.net/npm/@suggestapi/sdk/dist/suggestapi.global.min.js"></script>

Hybrid autocomplete with filters

The SDK automatically serializes object filters into the JSON string format expected by GET /v1/autocomplete.

import { createSuggestApiBrowserClient } from "@suggestapi/sdk/browser";

const client = createSuggestApiBrowserClient({
  apiKey: window.SUGGESTAPI_PUBLIC_KEY
});

const response = await client.search.autocomplete({
  index: "products",
  query: "diaphragm pump",
  mode: "hybrid",
  filters: {
    category: ["Pumps"],
    price: {
      gte: 100,
      lte: 1000
    }
  }
});

Recommendations

The docs currently describe the recommendation endpoint families clearly, but not every query parameter contract in detail. The SDK therefore gives you typed convenience for common fields and still lets you pass additional API params through directly.

import { createSuggestApiBrowserClient } from "@suggestapi/sdk/browser";

const client = createSuggestApiBrowserClient({
  apiKey: window.SUGGESTAPI_PUBLIC_KEY
});

const related = await client.recommendations.structural({
  index: "products",
  product_id: "sku_1001",
  limit: 6
});

const sameSeries = await client.recommendations.series({
  index: "products",
  product_id: "sku_1001",
  limit: 6
});

const compatible = await client.recommendations.application({
  index: "products",
  product_id: "sku_1001",
  filters: {
    category: ["Pumps"]
  }
});

const connected = await client.recommendations.connected({
  index: "products",
  entity_keys: ["sku_1001"],
  limit: 8
});

Personalization

import { createSuggestApiClient } from "@suggestapi/sdk/node";

const client = createSuggestApiClient({
  bearerToken: process.env.SUGGESTAPI_BEARER_TOKEN
});

await client.personalization.upsertProfile({
  user_id: "user_123",
  preferred_brands: ["LMI"]
});

await client.personalization.trackEvent({
  user_id: "user_123",
  event_type: "product_click",
  index_id: "products",
  doc_id: "sku_1001"
});

const response = await client.search.autocomplete({
  index: "products",
  query: "pump",
  user_id: "user_123",
  debug: true
});

Predict

/v1/predict is marked Beta in the docs. The SDK exposes it, but you should expect the response contract to evolve.

import { createSuggestApiBrowserClient } from "@suggestapi/sdk/browser";

const client = createSuggestApiBrowserClient({
  apiKey: window.SUGGESTAPI_PUBLIC_KEY
});

const prediction = await client.predict.run({
  index: "products",
  query: "billng setings",
  limit: 5,
  allowed_types: ["destination", "intent", "product", "category"],
  include: {
    alternatives: true,
    supporting_suggestions: true
  }
});

Index creation and document ingestion

import { createSuggestApiClient } from "@suggestapi/sdk/node";

const client = createSuggestApiClient({
  bearerToken: process.env.SUGGESTAPI_BEARER_TOKEN
});

await client.indexes.create({
  index_id: "products",
  name: "Products"
});

await client.documents.bulkUpsert("products", {
  documents: [
    {
      id: "sku_1001",
      title: "PTFE Diaphragm Pump",
      desc: "Chemical-resistant pump for demanding transfer jobs",
      manufacturer: "LMI",
      raw: {
        category: "Pumps",
        price: 499.99,
        product_url: "https://example.com/products/sku_1001"
      }
    }
  ]
});

Error handling

import { SuggestApiError, createSuggestApiBrowserClient } from "@suggestapi/sdk/browser";

const client = createSuggestApiBrowserClient({
  apiKey: window.SUGGESTAPI_PUBLIC_KEY
});

try {
  await client.search.autocomplete({
    index: "products",
    query: ""
  });
} catch (error) {
  if (error instanceof SuggestApiError) {
    console.error(error.status, error.code, error.details);
  }
}

Design notes

• Uses the native fetch API in browsers and modern Node runtimes
• Supports both x-api-key and bearer token auth
• Serializes camelCase aliases like userId, documentId, allowedTypes, and bypassCache into the API's snake_case wire format
• Keeps browser-safe and server-side entrypoints separate

Tests

Lightweight tests cover:

• query serialization
• nested camelCase to snake_case normalization
• x-api-key headers
• bearer auth headers

Run them with:

npm test

Size check

To guard the direct browser build against accidental bloat:

npm run size

The current minified global bundle is checked against a 6 KB raw-size threshold.

Release workflow

The repository includes .github/workflows/release.yml for npm publishing.

It runs on:

• manual dispatch
• GitHub releases marked as published

Before enabling it, add an NPM_TOKEN repository secret with publish access to the target package.

Examples

See examples/ for small browser, Node, and Next.js usage samples.

For direct script-tag usage, see examples/browser/cdn.html.