AACsearch
SDKs

Node.js SDK

Install and use the @aacsearch/client Node.js SDK for search, index management, synonyms, curations, and more.

Node.js SDK (@aacsearch/client)

The @aacsearch/client npm package provides two clients:

ClientScopeKey PrefixBundle-safeUse Case
SearchClientsearch-onlyss_search_*YesBrowser widgets, frontend
AdminClientfull CRUDaa_admin_*NoServer-side scripts, CLI, CI/CD

Security rule: never embed admin keys in browser code. Use SearchClient for frontend and proxy admin operations through your own backend.

Installation

Install the package:

npm install @aacsearch/client
# or
pnpm add @aacsearch/client

SearchClient (browser-safe)

Initialization

import { SearchClient } from "@aacsearch/client";

const client = new SearchClient({
	baseUrl: "https://app.aacsearch.com",
	apiKey: "ss_search_...",
	indexSlug: "products",
});
const result = await client.search({
	q: "running shoes",
	queryBy: "title,description",
	facetBy: "category,brand",
});

console.log(result.hits, result.found);
// { hits: [...], found: 42, page: 1, perPage: 10, facetCounts: [...] }

Execute multiple queries in a single round-trip:

const { results } = await client.multiSearch([
	{ q: "nike", queryBy: "title" },
	{ q: "adidas", queryBy: "title", filterBy: "in_stock:=true" },
]);

AdminClient (server-side)

Initialization

import { AdminClient } from "@aacsearch/client";

const admin = new AdminClient({
	baseUrl: "https://app.aacsearch.com",
	apiKey: "aa_admin_...",
	projectId: "org_xxx", // your organization ID
});

Index Management

// Create index
await admin.createIndex({
	slug: "products",
	displayName: "Products",
	fields: [
		{ name: "title", type: "string" },
		{ name: "price", type: "float", facet: true },
		{ name: "category", type: "string", facet: true },
	],
	defaultSortingField: "price",
});

// List indexes
const indexes = await admin.listIndexes();

// Get stats
const stats = await admin.getIndexStats(indexes[0].id);

Document CRUD

// Upsert single
await admin.upsertDocument("index_id", "doc_1", {
	title: "Running Shoes",
	price: 89.99,
	category: "Footwear",
});

// Batch upsert (up to 5000)
await admin.batchUpsertDocuments("index_id", [
	{ id: "doc_2", title: "T-Shirt", price: 29.99 },
	{ id: "doc_3", title: "Cap", price: 14.99 },
]);

// Batch delete
await admin.batchDeleteDocuments("index_id", ["doc_2", "doc_3"]);

API Key Management

// Create key
const { rawKey, id } = await admin.createKey({
	indexSlug: "products",
	name: "My App Key",
	scopes: ["search"],
	allowedOrigins: ["https://myapp.com"],
	rateLimitPerMinute: 60,
});
console.log("Save this key — shown once:", rawKey);

// Revoke key
await admin.revokeKey(id);

Synonyms & Curations

// Synonyms
await admin.createSynonym("index_id", {
	root: "shoe",
	replacements: ["sneaker", "trainer"],
});

// Curations
const curations = await admin.listCurations("index_id");

Analytics

const analytics = await admin.getAnalytics({ period: "last30" });
console.log(analytics.totalSearches, analytics.ctr);

const usage = await admin.getUsage(7);
console.log(usage.rows);

Error Handling

import { SdkError, SearchClient } from "@aacsearch/client";

const client = new SearchClient({ baseUrl, apiKey, indexSlug: "test" });

try {
	await client.search({ q: "test" });
} catch (err) {
	if (err instanceof SdkError) {
		switch (err.code) {
			case "rate_limited":
				// Back off and retry
				break;
			case "quota_exceeded":
				// Contact billing
				break;
			case "unauthorized":
				// API key is invalid
				break;
			default:
				console.error(err.message, err.details);
		}
	}
}

Error Codes

CodeWhenHTTP Status
missing_bearer_tokenNo auth header401
unauthorizedEmpty or invalid token format401
forbiddenInvalid/expired/revoked API key403
not_foundResource not found404
conflictSlug already used409
rate_limitedPer-key rate limit exceeded429
quota_exceededMonthly plan limits exceeded402
invalid_inputValidation error in request body400
search_failedUpstream search engine error502
network_errorFetch failed or connection refused0

API Reference

Full API coverage of the Node.js SDK:

CategoryMethods
ProjectgetProject, createProject, getProjectById
Index ManagementlistIndexes, getIndex, createIndex, updateIndex, deleteIndex, getIndexStats
DocumentslistDocuments, upsertDocument, batchUpsertDocuments, deleteDocument, batchDeleteDocuments
Searchsearch, multiSearch
API KeyslistKeys, createKey, revokeKey
AnalyticsgetAnalytics, getUsage
SynonymslistSynonyms, createSynonym, upsertSynonyms, deleteSynonym
CurationslistCurations, createCuration, upsertCurations, deleteCuration
Sorting FieldslistSortingFields, createSortingField, replaceSortingFields, deleteSortingField
FacetslistFacets

On this page