TypeScript SDK

import { AACSearchClient, AACSearchError } from "@repo/sdk";

const client = new AACSearchClient({
	apiKey: process.env.AAC_KEY!,
	baseUrl: "https://search.example.com/api/v1",
});

const result = await client.search("documentation", { q: "тарифы", per_page: 5 });
console.log(result.found, result.hits[0]?.document.title);

interface AACSearchClientOptions {
	/** Ключ aac_live_… Обязателен. */
	apiKey: string;
	/** По умолчанию http://localhost:3000/api/v1 */
	baseUrl?: string;
	/** Повторы для 429 и 5xx. По умолчанию 2. */
	maxRetries?: number;
	/** Своя реализация fetch — для трассировки или прокси. */
	fetch?: typeof fetch;
}

new AACSearchClient({ apiKey: "" });
// AACSearchError: apiKey is required (status 401, code MISSING_API_KEY)

class AACSearchError extends Error {
	name: "AACSearchError";
	status: number; // 401, 403, 422, 429, 502…
	code: string; // UNAUTHORIZED, QUOTA_EXCEEDED, VALIDATION_ERROR…
	details?: unknown; // details из тела ошибки
	requestId?: string; // указывайте в обращении в поддержку
}

try {
	await client.upsertDocuments("documentation", {
		documents: [{ external_id: "pricing", content: "Pro стоит 29 USD в месяц." }],
		action: "create",
	});
} catch (error) {
	if (error instanceof AACSearchError) {
		if (error.code === "QUOTA_EXCEEDED") {
			console.error("Квота исчерпана, ждать до", (error.details as { resetsAt: string }).resetsAt);
		} else if (error.status === 429) {
			// сработал лимит запросов — SDK уже исчерпал maxRetries
		} else {
			console.error(error.code, error.message, error.requestId);
		}
	}
	throw error;
}

const suggestions = await client.suggest("documentation", { q: "тар", limit: 5 });
const stats = await client.indexStats("documentation");
const caps = await client.capabilities();
if (!caps.features.autoEmbedding) throw new Error("семантический поиск недоступен на этом узле");

await client.upsertDocuments("documentation", {
	documents: [
		{
			external_id: "pricing",
			title: "Тарифы",
			content: "Pro стоит 29 USD в месяц и включает 500 000 поисков.",
			tags: ["billing"],
		},
	],
	action: "upsert",
});

const doc = await client.getDocument("documentation", "pricing");
await client.deleteDocument("documentation", "pricing");
await client.deleteDocuments("documentation", { filter_by: "source_type:=connector" });

const answer = await client.answer("documentation", {
	question: "Сколько стоит тариф pro?",
	per_page: 4,
});
console.log(answer.answer, answer.citations);

await client.assistantStream("documentation", { question: "А какие лимиты?" }, (event) => {
	if (event.type === "delta")
		process.stdout.write(String((event.payload as { text?: string }).text ?? ""));
});

const { overview } = await client.analyticsOverview({ days: 7 });
console.log(overview.totals.searches, overview.totals.zeroResultRate);

const { usage } = await client.usage();
console.log(`${usage.searches.used}/${usage.searches.limit} поисков за период`);