SDK

Четыре SDK генерируются из того же OpenAPI-документа, что и этот справочник, поэтому для каждой операции, параметра и ошибки, описанных здесь, в каждом из них есть метод с тем же именем (operationId в camelCase, snake_case или PascalCase — в зависимости от соглашений языка).

Создание клиента

import { AACSearchClient } from "aacsearch";
const client = new AACSearchClient({ baseUrl: "https://api.aacsearch.com/v1", apiKey: process.env.NOVA_API_KEY! });

Поиск

const page = await client.documents.searchCollection({
  collectionName: "products",
  searchParameters: { q: "cordless drill", query_by: "name,brand", filter_by: "in_stock:true", per_page: 20 },
});

Помимо полей поискового движка, результаты содержат расширения платформы: redirect и suggestions из поисковых правил, query_rewrite, если запрос без результатов был исправлен, и found.

Потоковый ответ ассистента

Потоковая операция использует Server-Sent Events; каждый SDK предоставляет её в виде итератора объектов ChatChunk (sources, delta…, usage, done).

const stream = await client.assistants.streamChatCompletion({ assistantId, body: { messages: [{ role: "user", content: q }] } });
for await (const chunk of stream) if (chunk.type === "delta") process.stdout.write(chunk.delta ?? "");

Чтобы сохранить контекст диалога, передайте conversation_id из фрагмента done в следующем ходе; GET …/conversations/{id} возвращает историю.

События, рекомендации, голос, изображения

await client.events.ingestEvents({ events: [{ type: "purchase", collection: "products", session_id, doc_ids: ["42"], value: 12990, currency: "RUB" }] });
const similar = await client.recommendations.getRecommendations({ collectionName: "products", model_id: "similar", object_id: "42" });
const text = await client.voice.createTranscription({ file: clip, language: "ru" });
const byPhoto = await client.media.searchByImage({ collectionName: "products", image_base64, vector_field: "image_embedding" });

Ошибки, повторные попытки, тайм-ауты

Ответы с кодом, отличным от 2xx, выбрасывают типизированную ошибку для каждого статуса — BadRequestError, UnauthorizedError, PaymentRequiredError (в кошельке недостаточно средств для AI-операции), ForbiddenError (область доступа ключа), NotFoundError, ConflictError, TooManyRequestsError (квота или лимит на сессию), — и каждая содержит статус и JSON-тело ответа. Запросы повторяются с экспоненциальной задержкой при 408, 429 и 5xx с учётом Retry-After; каждый метод принимает параметры запроса, позволяющие изменить maxRetries и тайм-аут (по умолчанию 60 с). Отключите повторные попытки для ходов ассистента, за которые вы не хотите платить дважды.

В браузере

Используйте поисковый ключ (см. ключи и области доступа) и передавайте X-NOVA-SESSION-ID посетителя. Для готовой страницы поиска, автодополнения, чата поддержки и блоков рекомендаций используйте пакет aacsearch-ui, построенный поверх этого SDK.

Повторная генерация

SDK генерируются Fern и хранятся в репозитории; в fern/README.md описан конвейер (pnpm generate, fern generate, pnpm sdk:patch) и те немногие вещи, которые генераторы не могут выразить.