@vrin/sdk

Official TypeScript SDK for Vrin — the retrieval-time reasoning layer for AI agents.

Works in Node 18+, Bun, Deno, Cloudflare Workers, and modern browsers.

Install

npm install @vrin/sdk
# or
pnpm add @vrin/sdk
# or
bun add @vrin/sdk

Get an API key

Sign up at vrin.cloud → Dashboard → API Keys. Store it in an environment variable:

export VRIN_API_KEY=vrin_live_...

Quickstart

import { VrinClient } from "@vrin/sdk";

const client = new VrinClient({ apiKey: process.env.VRIN_API_KEY });

// Ingest knowledge
await client.insert({
  content: "ACME Corp reported $50M revenue in Q4 2025.",
  title: "ACME Q4 2025",
});

// Query it
const result = await client.query({ query: "What is ACME's Q4 revenue?" });
console.log(result.summary);

Streaming

for await (const token of client.queryStream({ query: "Summarize ACME's year" })) {
  process.stdout.write(token);
}

For full SSE events (progress, sources, metadata):

for await (const event of client.queryEvents({ query: "..." })) {
  if (event.type === "sources") console.log("sources:", event.data);
  if (event.type === "content") process.stdout.write(String((event.data as any).delta ?? ""));
}

Upload files

import { readFile } from "node:fs/promises";

const buf = await readFile("./earnings.pdf");
const result = await client.uploadFile({
  file: buf,
  filename: "earnings.pdf",
});
console.log(result.upload_id, result.status);

Error handling

import { VrinClient, AuthenticationError, RateLimitError, InsufficientCoverageError } from "@vrin/sdk";

try {
  const r = await client.query({ query: "..." });
} catch (err) {
  if (err instanceof AuthenticationError) { /* bad key */ }
  else if (err instanceof RateLimitError) { /* back off; err.retryAfterSeconds is set if server sent it */ }
  else if (err instanceof InsufficientCoverageError) { /* knowledge base doesn't cover this */ }
  else throw err;
}

Advanced: custom base URL, timeout, fetch

const client = new VrinClient({
  apiKey: process.env.VRIN_API_KEY,
  baseUrl: "https://api.vrin.cloud",      // default
  timeoutMs: 120_000,                     // per-request timeout
  maxRetries: 2,                          // transient 5xx / network errors
  fetch: customFetch,                     // for Cloudflare Workers, Node < 18, etc.
});

See also

• Vrin docs
• Python SDK (pip install vrin)
• MCP server
• CLI

License

MIT