npm package: @ignitionai/sdk
Description: TypeScript SDK for IgnitionAI RAG platform
Author: IgnitionAI
Latest version: 0.1.0

# @ignitionai/sdk

TypeScript SDK for the IgnitionAI RAG platform. Zero dependencies, works everywhere: Node.js 18+, Bun, Deno, edge runtimes, and browsers.

## Installation

```bash
npm install @ignitionai/sdk
# or
bun add @ignitionai/sdk
```

## Setup

```typescript
import { IgnitionAI } from "@ignitionai/sdk";

const client = new IgnitionAI({
  apiKey: "ign_xxxxxxxxxxxx",
});
```

Or use the `IGNITION_API_KEY` environment variable:

```typescript
const client = new IgnitionAI();
```

### Configuration Options

```typescript
const client = new IgnitionAI({
  apiKey: "ign_xxxx",               // required (or IGNITION_API_KEY env)
  baseURL: "https://custom.api",    // default: https://api.ignitionai.dev
  maxRetries: 3,                    // default: 2
  timeout: 60_000,                  // default: 30_000ms
  fetch: customFetch,               // custom fetch implementation
});
```

## RAG Chat

### Non-streaming

```typescript
const response = await client.chat.send({
  collectionId: "coll_xxxx",
  query: "What is the refund policy?",
});

console.log(response.answer);
console.log(`${response.sources.length} sources used`);
```

### Streaming

```typescript
const stream = client.chat.stream({
  collectionId: "coll_xxxx",
  query: "Explain the onboarding process",
});

for await (const event of stream) {
  if (event.type === "chunk") {
    process.stdout.write(event.content);
  }
  if (event.type === "sources") {
    console.log("\nSources:", event.sources.length);
  }
}
```

#### Text-only stream

```typescript
for await (const text of stream.toTextStream()) {
  process.stdout.write(text);
}
```

#### Collect full response

```typescript
const { text, sources, metrics } = await stream.getFullResponse();
```

### Progressive Streaming

Track RAG pipeline stages in real time:

```typescript
const stream = client.chat.streamProgressive({
  collectionId: "coll_xxxx",
  query: "Compare pricing plans",
});

for await (const event of stream) {
  switch (event.type) {
    case "stage":
      console.log(`[${event.stage}] ${event.elapsed}ms`);
      break;
    case "sources":
      console.log(`Found ${event.sources.length} sources`);
      break;
    case "chunk":
      process.stdout.write(event.content);
      break;
    case "metrics":
      console.log(`\nTotal: ${event.pipelineMetrics.totalTimeMs}ms`);
      break;
  }
}
```

## Agent Chat

```typescript
const stream = client.agentChat.stream("agent_xxxx", {
  query: "How do I configure SSO?",
  // sessionId auto-generated if omitted
});

for await (const event of stream) {
  switch (event.type) {
    case "chunk":
      process.stdout.write(event.content);
      break;
    case "tool_call":
      console.log(`\n[Tool: ${event.name}]`);
      break;
    case "tool_result":
      console.log(`[Result: ${event.name}]`);
      break;
    case "sources":
      console.log(`\n${event.sources.length} sources`);
      break;
  }
}
```

## Agents

```typescript
// List
const agents = await client.agents.list();

// Get
const agent = await client.agents.get("agent_xxxx");

// Create
const agent = await client.agents.create({
  name: "Support Bot",
  collectionId: "coll_xxxx",
  model: "gpt-4o-mini",
  temperature: 30,
  enabledBuiltinTools: ["web_search", "current_date"],
});

// Generate config with AI wizard
const config = await client.agents.generate({
  description: "A customer support agent for our SaaS platform",
  language: "en",
});

// Update
await client.agents.update("agent_xxxx", { temperature: 50 });

// Delete (soft)
await client.agents.delete("agent_xxxx");

// Delete (permanent)
await client.agents.delete("agent_xxxx", true);
```

## Collections

```typescript
// List
const collections = await client.collections.list();

// Create
const coll = await client.collections.create({
  name: "Product Docs",
  description: "All product documentation",
});

// Search
const results = await client.collections.search("coll_xxxx", {
  query: "authentication",
  limit: 10,
  filters: [{ field: "category", operator: "eq", value: "security" }],
});

// Browse chunks
const { chunks, total, hasMore } = await client.collections.chunks("coll_xxxx", {
  limit: 20,
  type: "text",
});

// Stats & insights
const stats = await client.collections.stats("coll_xxxx");
const insights = await client.collections.insights("coll_xxxx");

// Update / Delete
await client.collections.update("coll_xxxx", { name: "Renamed" });
await client.collections.delete("coll_xxxx");
```

## Ingestion

```typescript
// Ingest from URL
await client.ingest.url({
  collectionId: "coll_xxxx",
  url: "https://docs.example.com/guide",
});

// Ingest raw text
await client.ingest.document({
  collectionId: "coll_xxxx",
  content: "Your document content...",
  filename: "guide.txt",
});

// Upload file
await client.ingest.file({
  collectionId: "coll_xxxx",
  file: new File([buffer], "report.pdf", { type: "application/pdf" }),
});

// Crawl website
await client.ingest.crawl({
  collectionId: "coll_xxxx",
  url: "https://docs.example.com",
  maxPages: 50,
});

// Import HuggingFace dataset
await client.ingest.dataset({
  collectionId: "coll_xxxx",
  source: "huggingface",
  datasetId: "squad",
  split: "train",
  maxRows: 1000,
});
```

## MCP (Model Context Protocol)

```typescript
// List available prompts and resources
const prompts = await client.mcp.prompts("agent_xxxx");
const resources = await client.mcp.resources("agent_xxxx");

// Get a prompt
const prompt = await client.mcp.getPrompt("agent_xxxx", {
  serverName: "my-server",
  promptName: "summarize",
});

// Read a resource
const resource = await client.mcp.readResource("agent_xxxx", {
  serverName: "my-server",
  uri: "resource://data",
});

// Test server connectivity
const result = await client.mcp.testServer({
  url: "https://mcp.example.com",
  transport: "sse",
});
```

## Error Handling

All errors extend `IgnitionAIError`. HTTP errors are automatically mapped:

```typescript
import {
  IgnitionAI,
  RateLimitError,
  AuthenticationError,
  NotFoundError,
} from "@ignitionai/sdk";

try {
  await client.chat.send({ collectionId: "coll_xxxx", query: "Hello" });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (error instanceof NotFoundError) {
    console.log("Resource not found");
  }
}
```

| Error Class | Status Code |
|---|---|
| `BadRequestError` | 400 |
| `AuthenticationError` | 401 |
| `PermissionError` | 403 |
| `NotFoundError` | 404 |
| `RateLimitError` | 429 |
| `InternalServerError` | 500+ |
| `APIConnectionError` | Network failure |
| `APIConnectionTimeoutError` | Timeout |

Retries are automatic for status codes 408, 429, 500, 502, 503, 504 with exponential backoff.

## Vercel AI SDK Integration

Drop-in adapter for Next.js with `useChat()`:

### Route Handler (`app/api/chat/route.ts`)

```typescript
import { IgnitionAI } from "@ignitionai/sdk";
import { toAIStreamResponse } from "@ignitionai/sdk/adapters/vercel-ai";

const client = new IgnitionAI();

export async function POST(req: Request) {
  const { messages } = await req.json();

  const stream = client.chat.stream({
    collectionId: process.env.COLLECTION_ID!,
    query: messages.at(-1).content,
    history: messages.slice(0, -1),
  });

  return toAIStreamResponse(stream);
}
```

### Client Component

```tsx
"use client";
import { useChat } from "ai/react";

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          {m.role}: {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}
```

Works with `AgentChatStream` too:

```typescript
const stream = client.agentChat.stream(agentId, { query, sessionId });
return toAIStreamResponse(stream);
```

## Environment Variables

| Variable | Description | Required |
|---|---|---|
| `IGNITION_API_KEY` | API key (starts with `ign_`) | Yes (or pass in constructor) |
| `IGNITION_BASE_URL` | Custom API URL | No |

## Requirements

- Node.js 18+ / Bun / Deno
- Zero dependencies

## License

MIT