> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> The conare package: the whole API in a few methods.

```bash theme={null}
npm install conare
```

No dependencies. Works on Node 18+, Bun, Deno and edge runtimes.

```ts theme={null}
import { Conare } from "conare";

const conare = new Conare();              // CONARE_API_KEY from the environment
const docs = conare.namespace("docs");

await docs.add({ id: "refunds", text: "Refunds are available for 30 days.", metadata: { team: "support" } });
const results = await docs.query("how do refunds work?", { topK: 5, filter: { team: "support" } });
```

## Client

```ts theme={null}
new Conare({
  apiKey: "sk-conare-...",                // default: CONARE_API_KEY
  baseURL: "https://api.conare.ai",       // default: CONARE_BASE_URL, then this
  timeout: 60_000,                        // per request, in ms
  maxRetries: 2,                          // on 429, 5xx and network errors
});
```

Every method also takes `signal` (an `AbortSignal`) and `timeout` in its options.

## Reference

| Method | Returns |
| - | - |
| `conare.namespace(name)` | A `Namespace` handle. Nothing is sent. |
| `conare.namespaces()` | `[{ name, documents }]` |
| `ns.add(doc \| docs[])` | The ids. Many documents are sent 100 at a time. |
| `ns.query(text, { topK, filter, rerank })` | `[{ id, text, score, metadata }]` |
| `ns.get(id)` | `{ id, text, metadata, updatedAt }` or `null` |
| `ns.list({ limit })` | An async iterator over `{ id, metadata, updatedAt }`. Fetches pages as you go. |
| `ns.delete(id)` | |
| `ns.drop()` | Deletes the namespace and its documents. |
| `conare.embed(texts, { type })` | `number[][]` |
| `conare.rerank(query, documents, { topK })` | `[{ index, score, document }]` |
| `conare.sources.connect({ type, namespace, name, redirectUrl })` | `{ source, connectUrl }` |
| `conare.sources.list()` | `Source[]` |
| `conare.sources.get(id)` | `Source` |
| `conare.sources.sync(id)` | `Source` |
| `conare.sources.delete(id, { deleteDocuments })` | |
| `conare.sources.types()` | `[{ type, name, logoUrl }]` |

Names are camelCase in TypeScript and snake\_case on the wire. Timestamps are `Date` objects.

## Errors

Every failure is a `ConareError`:

```ts theme={null}
import { ConareError } from "conare";

try {
  await docs.add({ text: "" });
} catch (err) {
  if (err instanceof ConareError) {
    console.log(err.status, err.code, err.message, err.requestId);
  }
}
```

`status` is 0 when no response arrived (`code` is `timeout` or `connection_error`). Rate limits
(429), server errors (5xx) and network errors are retried twice with backoff, and `Retry-After`
is honoured.