Catalyst Index TypeScript SDK

Developer experience first client for the Catalyst Index Server. Build ingestion pipelines, kick off background jobs, and render search results with rich metadata in a few lines of code.

Highlights

• One-line setup – new CatalystIndexClient({ baseUrl, apiKey }) returns a fully typed client ready for browser or Node/Bun.
• Full endpoint coverage – projects, ingestion (sync/async/URLs/ZIP/crawl), jobs, search (single + federated), webhooks, monitors, and health.
• Rich metadata – search results include page numbers, paragraph indices, headings, and chunk hashes for deep linking.
• Type-safe errors – every call returns { ok: true, data } | { ok: false, error } with detailed error information.
• DX tooling – Built with Bun + tsup + Vitest with zero-config type generation from OpenAPI.

Quickstart

npm install @catalystlabs/catalyst-index-sdk
# or
bun install @catalystlabs/catalyst-index-sdk

import { CatalystIndexClient } from '@catalystlabs/catalyst-index-sdk';

const client = new CatalystIndexClient({
	baseUrl: process.env.RAG_ENDPOINT!,
	apiKey: process.env.RAG_API_KEY!,
});

// Create a project
const project = await client.projects.create({
	name: 'My Knowledge Base',
	description: 'Documentation and guides'
});

// Search
const results = await client.search.query(project.data.project_id, {
	query: 'refund policy',
	top_k: 10,
	rerank: true
});

if (results.ok) {
	results.data.results.forEach(result => {
		console.log(`${result.score.toFixed(3)} - ${result.text.slice(0, 100)}...`);
	});
}

Repository Layout

├── docs/                  # Developer guides & API reference
├── examples/              # Runnable usage samples (Bun scripts)
├── src/
│   ├── client.ts          # HTTP client + middleware stack
│   ├── config.ts          # runtime configuration + retry wiring
│   ├── endpoints/         # Feature-specific API modules
│   ├── helpers/           # Metadata, retry, and polling helpers
│   ├── models/            # Typed request/response contracts
│   └── index.ts           # Public exports
├── package.json
├── bun.lock
├── tsconfig.json
├── tsup.config.ts
└── vitest.config.ts

DX Principles

• Dead-simple ingestion – Helpers accept File, Blob, ArrayBuffer, or raw strings; async ingestion returns job IDs with jobs.poll convenience.
• Typed errors – Every call resolves to { ok: true, data } | { ok: false, error } with status/code/details.
• Metadata aware – Search helpers surface source_page, source_paragraph_index, headings, and chunk hashes for deep linking.
• Extensible fetch layer – Provide custom fetch, retry policy, timeouts, or headers without rewriting the client.

Scripts (via Bun)

| Command | Description | | ------------------- | ------------------------------------------------------------ | | bun run dev | Watch/rebuild the SDK during development. | | bun run build | Emit ESM + CJS bundles with declaration files. | | bun run test | Execute Vitest unit suite. | | bun run lint | Run Biome formatting/linting. | | bun run typecheck | Strict TypeScript checks (tsc --noEmit). | | bun run generate | Pull the latest OpenAPI spec into src/models/generated.ts. |

Getting Started Locally

bun install
bun run build
# optional: export RAG_OPENAPI_URL="https://your-server/openapi.json?key=..."
# bun run generate
bun run typecheck
# bun run test    # optional smoke tests

See docs/CONTRIBUTING.md for coding standards and release workflow. Additional runnable samples live in examples/ (ingestion, search, job polling).