AACsearch
SDKs

Node.js SDK

Installieren und verwenden Sie das @aacsearch/client Node.js SDK für Suche, Index-Verwaltung, Synonyme, Kuratierungen und mehr.

Node.js SDK (@aacsearch/client)

Das npm-Paket @aacsearch/client stellt zwei Clients bereit:

ClientBereichSchlüssel-PräfixBundle-sicherAnwendungsfall
SearchClientNur Suchess_search_*JaBrowser-Widgets, Frontend
AdminClientVollzugriffaa_admin_*NeinServerseitige Skripte, CLI, CI/CD

Sicherheitsregel: Admin-Schlüssel niemals in Browser-Code einbetten. Verwenden Sie SearchClient für das Frontend und leiten Sie Admin-Operationen über Ihr eigenes Backend weiter.

Installation

Installieren Sie das Paket:

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

SearchClient (browsersicher)

Initialisierung

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

const client = new SearchClient({
	baseUrl: "https://app.aacsearch.com",
	apiKey: "ss_search_...",
	indexSlug: "products",
});

Einfache Suche

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: [...] }

Multi-Suche

Führen Sie mehrere Abfragen in einem einzigen Round-Trip aus:

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

AdminClient (serverseitig)

Initialisierung

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

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

Index-Verwaltung

// Index erstellen
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",
});

// Indizes auflisten
const indexes = await admin.listIndexes();

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

Dokumenten-CRUD

// Einzelnes Dokument einfügen/aktualisieren
await admin.upsertDocument("index_id", "doc_1", {
	title: "Running Shoes",
	price: 89.99,
	category: "Footwear",
});

// Batch einfügen/aktualisieren (bis zu 5000)
await admin.batchUpsertDocuments("index_id", [
	{ id: "doc_2", title: "T-Shirt", price: 29.99 },
	{ id: "doc_3", title: "Cap", price: 14.99 },
]);

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

API-Schlüssel-Verwaltung

// Schlüssel erstellen
const { rawKey, id } = await admin.createKey({
	indexSlug: "products",
	name: "My App Key",
	scopes: ["search"],
	allowedOrigins: ["https://myapp.com"],
	rateLimitPerMinute: 60,
});
console.log("Schlüssel speichern — wird nur einmal angezeigt:", rawKey);

// Schlüssel widerrufen
await admin.revokeKey(id);

Synonyme & Kuratierungen

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

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

Analysen

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

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

Fehlerbehandlung

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":
				// Zurücksetzen und erneut versuchen
				break;
			case "quota_exceeded":
				// Abrechnung kontaktieren
				break;
			case "unauthorized":
				// API-Schlüssel ist ungültig
				break;
			default:
				console.error(err.message, err.details);
		}
	}
}

Fehlercodes

CodeWannHTTP-Status
missing_bearer_tokenKein Auth-Header401
unauthorizedLeeres oder ungültiges Token-Format401
forbiddenUngültiger/abgelaufener/widerrufener403
not_foundRessource nicht gefunden404
conflictSlug bereits vergeben409
rate_limitedPro-Schlüssel-Ratenlimit überschritten429
quota_exceededMonatsplan-Limit überschritten402
invalid_inputValidierungsfehler im Anfragetext400
search_failedUpstream-Suchmaschinenfehler502
network_errorFetch fehlgeschlagen oder Verbindung0

API-Referenz

Vollständige API-Abdeckung des Node.js SDK:

KategorieMethoden
ProjektgetProject, createProject, getProjectById
Index-VerwaltunglistIndexes, getIndex, createIndex, updateIndex, deleteIndex, getIndexStats
DokumentelistDocuments, upsertDocument, batchUpsertDocuments, deleteDocument, batchDeleteDocuments
Suchesearch, multiSearch
API-SchlüssellistKeys, createKey, revokeKey
AnalysengetAnalytics, getUsage
SynonymelistSynonyms, createSynonym, upsertSynonyms, deleteSynonym
KuratierungenlistCurations, createCuration, upsertCurations, deleteCuration
SortierfelderlistSortingFields, createSortingField, replaceSortingFields, deleteSortingField
FacettenlistFacets

On this page