@anaralabs/sdk

Official TypeScript SDK for the Anara API. It mirrors Anara's in-product code-agent SDK — the full anara.* surface (library search, research, entities, documents, spreadsheets, notes, images, RLM map/ask) — as a typed HTTP client. Give a coding agent (Claude Code, Codex, …) the same tools the Anara agent has, over a single API key.

Zero runtime dependencies. Works in Node 18+, Deno, Bun, edge runtimes, and the browser (anywhere fetch exists).

Install

npm install @anaralabs/sdk

Authenticate

Mint an API key (Better Auth) from your signed-in browser session:

curl -X POST https://anara.com/api/better-auth/api-key/create \
  -H 'content-type: application/json' \
  -H 'cookie: <signed-in-browser-cookie>' \
  -d '{"name":"CLI","permissions":{"anara":["read","chat","write"]}}'

Keys look like anara_…. Reads need anara:read; library writes need anara:write. Keep them secret; never commit them.

Use

import { createAnaraClient } from '@anaralabs/sdk';

// `apiKey` defaults to the ANARA_API_KEY environment variable.
const anara = createAnaraClient();

// Retrieval — compose it from the raw primitives: recall, rerank, read.
const candidates = await anara.retrieval.vectorSearch({
  queries: ['wooden pallet recycling drop-off', 'where to recycle pallets'],
});
const winners = await anara.retrieval.rerank({
  query: 'wooden pallet recycling drop-off',
  candidates,
  topK: 6,
});

// Read a winner's full page when snippets aren't enough.
const page = await anara.documents.getPages(
  winners[0].documentId,
  winners[0].pageNumber != null ? [winners[0].pageNumber] : undefined,
);

// Library entities (CRUD). Writes need an `anara:write` key.
const drafts = await anara.entities.query({
  type: 'NOTE',
  nameContains: 'draft',
});
const folder = await anara.entities.create({ type: 'GROUP', name: 'Drafts' });
for (const d of drafts) await anara.entities.move(d.id, folder.id);

// Fan a cheap sub-LM over big data (RLM).
const labels = await anara.map(reviews, 'Reply POSITIVE or NEGATIVE.');

How it works

The package is a thin client: every anara.* method is one HTTP call to the Anara API (POST /api/v1/sdk with { method, args }), dispatched server-side against your authenticated workspace. anara.me() hits GET /api/v1/me. There is no Anara logic in the package itself — just typed calls over your key.

Surface

entities.query/get/create/update/move/delete · search · research · retrieval.vectorSearch/keywordSearch/rerank · documents.getPages/expandContext/readToc/readMedia/extract · store.put/get · map · ask · askMany · spreadsheets.query/applyEdits · notes.read/edit · images.create · chats.search · workspace.queryDb · me.

invoke(method, args) is the escape hatch for any method not yet wrapped.

Errors are thrown as AnaraApiError (.status, .code, .details); isAnaraApiError(e) is a type guard.

Drop-in agent guide

ANARA_AGENT_GUIDE is a ready-made system-prompt block teaching an agent when and how to call the SDK:

import { ANARA_AGENT_GUIDE } from '@anaralabs/sdk';

Configuration

createAnaraClient({
  apiKey: '…', // or ANARA_API_KEY
  baseUrl: 'https://anara.com', // override for self-hosted / preview
  fetch: customFetch, // override the fetch implementation
  headers: { 'x-trace': '…' }, // extra headers on every request
});