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

interface AACSearchClientOptions {
	/** aac_live_… key. Required. */
	apiKey: string;
	/** Defaults to http://localhost:3000/api/v1 */
	baseUrl?: string;
	/** Retries for 429 and 5xx. Default 2. */
	maxRetries?: number;
	/** Custom fetch implementation, e.g. for tracing or a 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 from the error body
	requestId?: string; // quote this to support
}

try {
	await client.upsertDocuments("documentation", {
		documents: [{ external_id: "pricing", content: "Pro is 29 USD per month." }],
		action: "create",
	});
} catch (error) {
	if (error instanceof AACSearchError) {
		if (error.code === "QUOTA_EXCEEDED") {
			console.error(
				"Quota exhausted, retry after",
				(error.details as { resetsAt: string }).resetsAt,
			);
		} else if (error.status === 429) {
			// rate limited — back off, the SDK already retried maxRetries times
		} else {
			console.error(error.code, error.message, error.requestId);
		}
	}
	throw error;
}

const suggestions = await client.suggest("documentation", { q: "pri", limit: 5 });
const stats = await client.indexStats("documentation");
const caps = await client.capabilities();
if (!caps.features.autoEmbedding) throw new Error("semantic search unavailable on this node");

await client.upsertDocuments("documentation", {
	documents: [
		{
			external_id: "pricing",
			title: "Pricing",
			content: "Pro is 29 USD per month with 500,000 searches.",
			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: "How much does the pro plan cost?",
	per_page: 4,
});
console.log(answer.answer, answer.citations);

await client.assistantStream("documentation", { question: "And the 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} searches this period`);