AddSearch JavaScript Client

1.2.3 verified Tue Apr 21 auth: no javascript

The `addsearch-js-client` package provides a JavaScript client library for interacting with the AddSearch Search API and Indexing API. It allows developers to easily integrate search functionalities like keyword search, search suggestions, and custom field autocompletion into their web applications or Node.js environments. The current stable version is 1.2.3. The package appears to have a regular release cadence, with multiple minor and patch updates released within recent months, often addressing dependency updates, security vulnerabilities, and new features like AI answers streaming. Key differentiators include its focus on a comprehensive search-as-a-service platform, offering features like fuzzy matching, configurable search operators, and specific indexing capabilities alongside standard search. It supports both browser and Node.js environments and ships with TypeScript types, ensuring type safety for TypeScript projects. The library aims to simplify the integration of complex search features into various JavaScript applications.

Common errors

error 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 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.

error 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

yarn add addsearch-js-client

pnpm add addsearch-js-client

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);