AddSearch JavaScript Client

Common errors

• ReferenceError: AddSearchClient is not defined

  cause Attempting to use `AddSearchClient` without correctly importing or requiring it, or using the wrong import syntax for the environment (e.g., CommonJS `require` in an ESM module).
  fix Ensure you are using `import AddSearchClient from 'addsearch-js-client';` for ES Modules or `const AddSearchClient = require('addsearch-js-client');` for CommonJS environments.

• Error: Invalid Sitekey

  cause The `AddSearchClient` constructor was called with an invalid, missing, or improperly formatted 32-character public sitekey.
  fix Verify your AddSearch public sitekey is correct and provided as a string argument to the `AddSearchClient` constructor. It must be exactly 32 characters long.

• TypeError: client.search is not a function

  cause This typically occurs if `client` is not an instance of `AddSearchClient`, often due to an incorrect import or module loading issue, or attempting to call a method that does not exist on the client object.
  fix Double-check your import statement for `AddSearchClient` and ensure that `new AddSearchClient(SITEKEY)` is correctly executed before calling methods like `search`, `suggestions`, or `autocomplete`.

Warnings

• breaking The package requires Node.js version 20.0.0 or higher. Older Node.js environments will fail to run the library.
  Fix: Upgrade your Node.js runtime to version 20.0.0 or newer (e.g., using `nvm install 20` and `nvm use 20`).
• breaking Version 1.1.0 introduced changes to how POST request payloads are handled. Existing integrations making POST requests might require adjustments.
  Fix: Review the `sc-11931` change in the changelog and test your POST request implementations thoroughly after upgrading to ensure compatibility with the new handling mechanism.
• gotcha Earlier versions (before v1.0.4) had issues with error handling when cookies contained URI-incompatible characters, potentially leading to unexpected failures or malformed requests.
  Fix: Upgrade to version 1.0.4 or newer to benefit from improved cookie error handling. Ensure any custom cookie management in your application correctly encodes/decodes special characters.
• breaking A security vulnerability (CVE-2026-25639) was addressed in version 1.2.2. Older versions are susceptible.
  Fix: Immediately upgrade to version 1.2.2 or later to mitigate the vulnerability.
• breaking Another security vulnerability (CVE-2025-62718) was addressed in version 1.2.3, affecting internal tools and related components. Older versions are potentially vulnerable.
  Fix: Immediately upgrade to version 1.2.3 or later to ensure the latest security fixes are applied.

Install

• npm install addsearch-js-client npm
• yarn add addsearch-js-client yarn
• pnpm add addsearch-js-client pnpm

Imports

• AddSearchClient
  wrong:

  import { AddSearchClient } from 'addsearch-js-client';

  correct:

  import AddSearchClient from 'addsearch-js-client';

  The primary client class is exported as a default module for ESM environments. Named imports for AddSearchClient are incorrect.
• AddSearchClient (CommonJS)
  wrong:

  const { AddSearchClient } = require('addsearch-js-client');

  correct:

  const AddSearchClient = require('addsearch-js-client');

  For CommonJS environments, the client is available as a default export via require(). Destructuring is not applicable here.
• Type definitions

  import AddSearchClient, { type SearchResult, type SuggestionResult } from 'addsearch-js-client';

  TypeScript types are shipped with the package. You can import specific types like SearchResult or SuggestionResult for stronger type checking in your applications.

Quickstart

This quickstart initializes the AddSearch client, performs a basic keyword search, and demonstrates fetching search suggestions and custom field autocompletion results. It includes a placeholder for your AddSearch Sitekey and uses environment variables for secure key handling.

import AddSearchClient from 'addsearch-js-client';

// Replace 'YOUR_PUBLIC_SITEKEY' with your actual 32-character AddSearch Sitekey
const SITEKEY = process.env.ADDSEARCH_SITEKEY ?? 'YOUR PUBLIC SITEKEY';

if (SITEKEY === 'YOUR PUBLIC SITEKEY') {
  console.warn('WARNING: Replace YOUR_PUBLIC_SITEKEY with your actual AddSearch Sitekey to make this example work.');
}

// Create client with your SITEKEY
const client = new AddSearchClient(SITEKEY);

// Define a callback function to handle search results
const handleSearchResults = (res) => {
  console.log('Search Results:', res);
  if (res.hits && res.hits.length > 0) {
    console.log(`Found ${res.hits.length} results. First result title:`, res.hits[0].title);
  } else {
    console.log('No results found for the keyword.');
  }
};

// Execute a search query for 'keyword'
client.search('keyword', handleSearchResults);

// Optionally, fetch search suggestions
const handleSuggestions = (res) => {
  console.log('Search Suggestions:', res);
};
client.suggestions('auto', handleSuggestions);

// Optionally, fetch custom field autocompletion results
const handleAutocomplete = (res) => {
  console.log('Autocomplete Results:', res);
};
client.autocomplete('custom_fields.category', 'pro', handleAutocomplete);