AACsearch
SDKs

SDK de Node.js

Instala y usa el SDK @aacsearch/client de Node.js para búsqueda, gestión de índices, sinónimos, curadurías y más.

SDK de Node.js (@aacsearch/client)

El paquete npm @aacsearch/client proporciona dos clientes:

ClienteÁmbitoPrefijo de claveSeguro para navegadorCaso de uso
SearchClientsolo búsquedass_search_*Widgets de navegador, frontend
AdminClientCRUD completoaa_admin_*NoScripts de servidor, CLI, CI/CD

Regla de seguridad: nunca incrustes claves de administrador en código de navegador. Usa SearchClient para el frontend y tramita las operaciones de administración a través de tu propio backend.

Instalación

Instala el paquete:

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

SearchClient (seguro para navegador)

Inicialización

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

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

Búsqueda básica

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

Búsqueda múltiple

Ejecuta múltiples consultas en un único viaje de ida y vuelta:

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

AdminClient (lado servidor)

Inicialización

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

const admin = new AdminClient({
	baseUrl: "https://app.aacsearch.com",
	apiKey: "aa_admin_...",
	projectId: "org_xxx", // tu ID de organización
});

Gestión de índices

// Crear índice
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",
});

// Listar índices
const indexes = await admin.listIndexes();

// Obtener estadísticas
const stats = await admin.getIndexStats(indexes[0].id);

CRUD de documentos

// Insertar o actualizar uno
await admin.upsertDocument("index_id", "doc_1", {
	title: "Running Shoes",
	price: 89.99,
	category: "Footwear",
});

// Inserción/actualización por lotes (hasta 5000)
await admin.batchUpsertDocuments("index_id", [
	{ id: "doc_2", title: "T-Shirt", price: 29.99 },
	{ id: "doc_3", title: "Cap", price: 14.99 },
]);

// Eliminación por lotes
await admin.batchDeleteDocuments("index_id", ["doc_2", "doc_3"]);

Gestión de claves API

// Crear clave
const { rawKey, id } = await admin.createKey({
	indexSlug: "products",
	name: "My App Key",
	scopes: ["search"],
	allowedOrigins: ["https://myapp.com"],
	rateLimitPerMinute: 60,
});
console.log("Guarda esta clave — se muestra una vez:", rawKey);

// Revocar clave
await admin.revokeKey(id);

Sinónimos y curadurías

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

// Curadurías
const curations = await admin.listCurations("index_id");

Analíticas

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

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

Manejo de errores

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":
				// Esperar y reintentar
				break;
			case "quota_exceeded":
				// Contactar a facturación
				break;
			case "unauthorized":
				// La clave API no es válida
				break;
			default:
				console.error(err.message, err.details);
		}
	}
}

Códigos de error

CódigoCuándo ocurreEstado HTTP
missing_bearer_tokenSin cabecera de autenticación401
unauthorizedToken vacío o con formato inválido401
forbiddenClave API inválida/expirada/revocada403
not_foundRecurso no encontrado404
conflictEl slug ya está en uso409
rate_limitedLímite de tasa por clave superado429
quota_exceededLímite mensual del plan superado402
invalid_inputError de validación en el cuerpo400
search_failedError interno de AACSearch502
network_errorFallo en la conexión o Fetch0

Referencia de la API

Cobertura completa de la API del SDK de Node.js:

CategoríaMétodos
ProyectogetProject, createProject, getProjectById
Gestión de índiceslistIndexes, getIndex, createIndex, updateIndex, deleteIndex, getIndexStats
DocumentoslistDocuments, upsertDocument, batchUpsertDocuments, deleteDocument, batchDeleteDocuments
Búsquedasearch, multiSearch
Claves APIlistKeys, createKey, revokeKey
AnalíticasgetAnalytics, getUsage
SinónimoslistSynonyms, createSynonym, upsertSynonyms, deleteSynonym
CuraduríaslistCurations, createCuration, upsertCurations, deleteCuration
Campos de ordenlistSortingFields, createSortingField, replaceSortingFields, deleteSortingField
FacetaslistFacets

On this page