Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AddSearchClient
✓ import AddSearchClient from 'addsearch-js-client';
✗ 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)
✓ const AddSearchClient = require('addsearch-js-client');
✗ 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.
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);
Debug
Known issues
breakingThe package requires Node.js version 20.0.0 or higher. Older Node.js environments will fail to run the library.fixUpgrade your Node.js runtime to version 20.0.0 or newer (e.g., using `nvm install 20` and `nvm use 20`).
affects: <1.0.0 (Implicitly, as it appeared in the metadata recently), >=1.0.0
breakingVersion 1.1.0 introduced changes to how POST request payloads are handled. Existing integrations making POST requests might require adjustments.fixReview the `sc-11931` change in the changelog and test your POST request implementations thoroughly after upgrading to ensure compatibility with the new handling mechanism.
affects: >=1.1.0
gotchaEarlier versions (before v1.0.4) had issues with error handling when cookies contained URI-incompatible characters, potentially leading to unexpected failures or malformed requests.fixUpgrade 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.
affects: <1.0.4
breakingA security vulnerability (CVE-2026-25639) was addressed in version 1.2.2. Older versions are susceptible.fixImmediately upgrade to version 1.2.2 or later to mitigate the vulnerability.
affects: <1.2.2
breakingAnother security vulnerability (CVE-2025-62718) was addressed in version 1.2.3, affecting internal tools and related components. Older versions are potentially vulnerable.fixImmediately upgrade to version 1.2.3 or later to ensure the latest security fixes are applied.
affects: <1.2.3
Errors
Common errors & fixes
ReferenceError: AddSearchClient is not defined
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).
fixEnsure 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
The `AddSearchClient` constructor was called with an invalid, missing, or improperly formatted 32-character public sitekey.
fixVerify 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
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.
fixDouble-check your import statement for `AddSearchClient` and ensure that `new AddSearchClient(SITEKEY)` is correctly executed before calling methods like `search`, `suggestions`, or `autocomplete`.
Audit
Dependencies
axiosrequiredUsed for making HTTP requests to the AddSearch API.
form-datarequiredLikely used for handling POST request payloads, especially in Node.js environments.