AACsearch
SDKs

SDK Node.js

Installez et utilisez le SDK Node.js @aacsearch/client pour la recherche, la gestion des index, les synonymes, les curations, et plus encore.

SDK Node.js (@aacsearch/client)

Le paquet npm @aacsearch/client fournit deux clients :

ClientPortéePréfixe de cléCompatible navigateurCas d'utilisation
SearchClientrecherchess_search_*OuiWidgets navigateur, frontend
AdminClientCRUD completaa_admin_*NonScripts serveur, CLI, CI/CD

Règle de sécurité : n'integreze jamais les clés admin dans du code navigateur. Utilisez SearchClient pour le frontend et passez les opérations admin par votre propre backend.

Installation

Installez le paquet :

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

SearchClient (compatible navigateur)

Initialisation

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

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

Recherche de base

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-recherche

Exécutez plusieurs requêtes en un seul aller-retour :

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

AdminClient (côté serveur)

Initialisation

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

const admin = new AdminClient({
	baseUrl: "https://app.aacsearch.com",
	apiKey: "aa_admin_...",
	projectId: "org_xxx", // votre identifiant d'organisation
});

Gestion des index

// Créer un 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",
});

// Lister les index
const indexes = await admin.listIndexes();

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

CRUD de documents

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

// Upsert par lot (jusqu'à 5000)
await admin.batchUpsertDocuments("index_id", [
	{ id: "doc_2", title: "T-Shirt", price: 29.99 },
	{ id: "doc_3", title: "Cap", price: 14.99 },
]);

// Suppression par lot
await admin.batchDeleteDocuments("index_id", ["doc_2", "doc_3"]);

Gestion des clés API

// Créer une clé
const { rawKey, id } = await admin.createKey({
	indexSlug: "products",
	name: "My App Key",
	scopes: ["search"],
	allowedOrigins: ["https://myapp.com"],
	rateLimitPerMinute: 60,
});
console.log("Enregistrez cette clé — affichée une seule fois :", rawKey);

// Révoquer une clé
await admin.revokeKey(id);

Synonymes et Curations

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

Gestion des erreurs

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":
				// Patientez et réessayez
				break;
			case "quota_exceeded":
				// Contactez la facturation
				break;
			case "unauthorized":
				// La clé API est invalide
				break;
			default:
				console.error(err.message, err.details);
		}
	}
}

Codes d'erreur

CodeQuandStatut HTTP
missing_bearer_tokenEn-tête d'auth manquant401
unauthorizedFormat de jeton vide ou invalide401
forbiddenClé API invalide/expirée/révoquée403
not_foundRessource introuvable404
conflictSlug déjà utilisé409
rate_limitedLimite de débit par clé dépassée429
quota_exceededLimites du forfait mensuel dépassées402
invalid_inputErreur de validation dans le corps400
search_failedErreur AACSearch amont502
network_errorÉchec de fetch ou connexion refusée0

Référence API

Couverture complète de l'API du SDK Node.js :

CatégorieMéthodes
ProjetgetProject, createProject, getProjectById
Gestion d'indexlistIndexes, getIndex, createIndex, updateIndex, deleteIndex, getIndexStats
DocumentslistDocuments, upsertDocument, batchUpsertDocuments, deleteDocument, batchDeleteDocuments
Recherchesearch, multiSearch
Clés APIlistKeys, createKey, revokeKey
AnalyticsgetAnalytics, getUsage
SynonymeslistSynonyms, createSynonym, upsertSynonyms, deleteSynonym
CurationslistCurations, createCuration, upsertCurations, deleteCuration
Champs de trilistSortingFields, createSortingField, replaceSortingFields, deleteSortingField
FacetteslistFacets

On this page