Как использовать AACsearch на Node.js и TypeScript — поиск товаров в приложении, управление индексом и аналитика.

Node.js SDK для AACsearch

Используйте @aacsearch/client, чтобы добавить быстрый поиск товаров в ваше приложение Node.js или фронтенд на TypeScript/JavaScript.

Установка

Установите пакет:

npm install @aacsearch/client
# или
pnpm add @aacsearch/client

Поиск товаров (SearchClient)

Самый частый сценарий — добавить поле поиска в ваше приложение. SearchClient работает как в браузере, так и на сервере Node.js.

Инициализация

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

const client = new SearchClient({
	baseUrl: "https://app.aacsearch.com",
	apiKey: "ss_search_your_key_here",  // Из панели управления
	indexSlug: "products",  // Название индекса
});

Простой поиск

const result = await client.search({
	q: "running shoes",  // То, что ищет пользователь
	queryBy: "title,description",  // Какие поля искать
	facetBy: "category,brand",  // Получить статистику для фильтров
});

console.log(`Найдено ${result.found} товаров`);
result.hits.forEach(item => {
	console.log(`  - ${item.title} ($${item.price})`);
});

Результат содержит:

hits — массив найденных товаров
found — общее количество совпадающих товаров
facetCounts — статистика по брендам, категориям и т.д. для фильтров
page, perPage — информация для пагинации

Поиск с фильтрами и сортировкой

const result = await client.search({
	q: "shoes",
	filterBy: "price:[50..200] && availability:=in_stock",  // Только в наличии и дешевле $200
	sortBy: "price:asc",  // Отсортировать по цене (дешевле в начале)
	facetBy: "brand,category",
	page: 1,
	perPage: 20,
});

Несколько поисков в одном запросе

Если нужно выполнить несколько поисков одновременно, это может быть быстрее:

const { results } = await client.multiSearch([
	{ q: "nike shoes", per_page: 5 },
	{ q: "adidas shoes", per_page: 5 },
	{ q: "running gear", per_page: 10 },
]);

Управление индексом и товарами (AdminClient)

Для добавления и обновления товаров используйте административный клиент. Используйте только на сервере, не в браузере.

Инициализация

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

const admin = new AdminClient({
	baseUrl: "https://app.aacsearch.com",
	apiKey: "aa_admin_your_key_here",  // Административный ключ из панели
	projectId: "org_xxx",  // ID вашей организации
});

Создание индекса для товаров

// Создать индекс с полями для фильтрации и сортировки
await admin.createIndex({
	slug: "products",
	displayName: "Products",
	fields: [
		{ name: "title", type: "string" },  // Название товара
		{ name: "price", type: "float", facet: true },  // Цена (с фильтром)
		{ name: "category", type: "string", facet: true },  // Категория (с фильтром)
		{ name: "brand", type: "string", facet: true },  // Бренд
		{ name: "availability", type: "string", facet: true },  // В наличии?
	],
	defaultSortingField: "price",  // По умолчанию сортировать по цене
});

// Список ваших индексов
const indexes = await admin.listIndexes();
console.log("Индексы:", indexes.map(i => i.displayName));

Добавление товаров

// Добавить один товар
await admin.upsertDocument("index_id_here", "doc_001", {
	title: "Nike Air Max",
	price: 129.99,
	category: "Footwear",
	brand: "Nike",
	availability: "in_stock",
});

// Добавить много товаров за раз (до 5000 товаров в одном запросе)
await admin.batchUpsertDocuments("index_id_here", [
	{ id: "doc_002", title: "Adidas Ultraboost", price: 159.99, brand: "Adidas" },
	{ id: "doc_003", title: "Puma RS-X", price: 99.99, brand: "Puma" },
	{ id: "doc_004", title: "New Balance 990", price: 175.00, brand: "New Balance" },
]);

Удаление товаров

// Удалить один товар
await admin.deleteDocument("index_id_here", "doc_001");

// Удалить несколько товаров
await admin.batchDeleteDocuments("index_id_here", ["doc_002", "doc_003"]);

Синонимы и курации

Добавьте синонимы, чтобы пользователи находили товары по разным словам:

// Синонимы: "кроссовки" = "sneakers" = "training shoes"
await admin.createSynonym("index_id_here", {
	root: "sneaker",
	replacements: ["training shoe", "athletic shoe", "кроссовки"],
});

// Закрепление товара в поиске для конкретного запроса
await admin.createCuration("index_id_here", {
	query: "best running shoes",
	pinnedIds: ["doc_bestseller_001"],  // Этот товар будет в начале результатов
});

Аналитика использования

Смотрите, как часто люди ищут товары и что находят:

// Статистика за последние 30 дней
const analytics = await admin.getAnalytics({ period: "last30" });
console.log(`Всего поисков: ${analytics.totalSearches}`);
console.log(`Процент кликов: ${analytics.ctr}%`);

// Детальные данные об использовании за 7 дней
const usage = await admin.getUsage(7);
console.log(`Кол-во документов: ${usage.docCount}`);

Обработка ошибок

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

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

try {
	await client.search({ q: "shoes" });
} catch (err) {
	if (err instanceof SdkError) {
		if (err.code === "rate_limited") {
			console.log("⏳ Превышен лимит запросов, подождите...");
		} else if (err.code === "quota_exceeded") {
			console.log("💳 Превышены лимиты плана, обновите подписку");
		} else if (err.code === "unauthorized") {
			console.log("🔐 Неверный API-ключ");
		} else {
			console.error(`❌ Ошибка: ${err.message}`);
		}
	}
}

Безопасность ключей

Ключи поиска (ss_search_*) — безопасны для браузера
Административные ключи (aa_admin_*) — только на сервере Node.js
Храните ключи в переменных окружения (.env)
Отозвите скомпрометированный ключ в панели управления
Используйте разные ключи для разных приложений

Node.js SDK

On this page