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: "preise", per_page: 5 });
console.log(result.found, result.hits[0]?.document.title);

interface AACSearchClientOptions {
	/** aac_live_… Schlüssel. Pflicht. */
	apiKey: string;
	/** Standard: http://localhost:3000/api/v1 */
	baseUrl?: string;
	/** Wiederholungen für 429 und 5xx. Standard 2. */
	maxRetries?: number;
	/** Eigene fetch-Implementierung, z. B. für Tracing oder einen Proxy. */
	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 aus dem Fehler-Body
	requestId?: string; // im Supportfall angeben
}

try {
	await client.upsertDocuments("documentation", {
		documents: [{ external_id: "pricing", content: "Pro kostet 29 USD im Monat." }],
		action: "create",
	});
} catch (error) {
	if (error instanceof AACSearchError) {
		if (error.code === "QUOTA_EXCEEDED") {
			console.error(
				"Kontingent erschöpft, weiter ab",
				(error.details as { resetsAt: string }).resetsAt,
			);
		} else if (error.status === 429) {
			// Rate-Limit — das SDK hat maxRetries bereits ausgeschöpft
		} else {
			console.error(error.code, error.message, error.requestId);
		}
	}
	throw error;
}

const suggestions = await client.suggest("documentation", { q: "pre", limit: 5 });
const stats = await client.indexStats("documentation");
const caps = await client.capabilities();
if (!caps.features.autoEmbedding)
	throw new Error("semantische Suche auf diesem Knoten nicht verfügbar");

await client.upsertDocuments("documentation", {
	documents: [
		{
			external_id: "pricing",
			title: "Preise",
			content: "Pro kostet 29 USD im Monat und enthält 500.000 Suchen.",
			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: "Was kostet der Pro-Tarif?",
	per_page: 4,
});
console.log(answer.answer, answer.citations);

await client.assistantStream("documentation", { question: "Und die Limits?" }, (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} Suchen in dieser Periode`);