TypeScript SDK: VrinClient

@vrin/sdk is the official TypeScript client. It works in Node 18+, Bun, Deno, Cloudflare Workers, and modern browsers. Written in TypeScript, shipped as both ESM and CJS, fully typed. If you’re building an agent in Python, use the Python SDK. If you’re shell-scripting, use the CLI.

Install

npm install @vrin/sdk

Also works with pnpm add, yarn add, bun add.

Authenticate

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

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

The API key starts with vrin_live_ (shared infra) or vrin_ent_ (enterprise-routed). Get one at vrin.cloud → Dashboard → API Keys. If apiKey is omitted, the client reads VRIN_API_KEY from process.env.

First query

const result = await client.query({ query: "What is ACME's Q4 revenue?" });
console.log(result.summary);
for (const source of result.sources) {
  console.log(` - ${source.title}`);
}

Constructor options

Option	Type	Default	Description
`apiKey`	`string`	`process.env.VRIN_API_KEY`	Vrin API key.
`baseUrl`	`string`	`https://api.vrin.cloud`	Override for staging or self-hosted deployments.
`timeoutMs`	`number`	`120000`	Per-request timeout. Must be ≥ the slowest query you expect.
`maxRetries`	`number`	`2`	Retry count for transient 5xx/network failures.
`fetch`	`typeof fetch`	global `fetch`	Inject a custom fetch for runtimes that don’t have one (Node < 18, some edge environments).

Usage across runtimes

Node 18+
Bun
Cloudflare Workers
Browser

import { VrinClient } from "@vrin/sdk";
const client = new VrinClient({ apiKey: process.env.VRIN_API_KEY });

import { VrinClient } from "@vrin/sdk";
const client = new VrinClient({ apiKey: Bun.env.VRIN_API_KEY });

import { VrinClient } from "@vrin/sdk";
export default {
  async fetch(req: Request, env: { VRIN_API_KEY: string }) {
    const client = new VrinClient({ apiKey: env.VRIN_API_KEY });
    const r = await client.query({ query: "..." });
    return Response.json(r);
  },
};

Never expose a raw Vrin API key in client-side JavaScript. Proxy through your own backend and call Vrin from there. The browser example below assumes a trusted internal tool context.

import { VrinClient } from "@vrin/sdk";
const client = new VrinClient({ apiKey: "vrin_live_..." });

Next steps

Querying

query, queryStream, response modes, depth.

Knowledge

insert, uploadFile, polling async jobs.

Conversations

Multi-turn sessions with startConversation + continueConversation.

Error handling

Typed exception hierarchy you can switch on.

Error handling

All errors extend VrinError. Import the specific subclasses you want to handle:

import {
  VrinClient,
  VrinError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  ServiceUnavailableError,
  TimeoutError,
  InsufficientCoverageError,
} from "@vrin/sdk";

try {
  const r = await client.query({ query: "..." });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // bad key — prompt the user to re-auth
  } else if (err instanceof RateLimitError) {
    // back off; err.retryAfterSeconds is populated if the server sent a Retry-After header
    await sleep((err.retryAfterSeconds ?? 1) * 1000);
  } else if (err instanceof InsufficientCoverageError) {
    // knowledge base has no relevant facts — ingest more or broaden the query
  } else if (err instanceof TimeoutError) {
    // request exceeded timeoutMs — retry with a longer timeout or split the query
  } else if (err instanceof VrinError) {
    console.error("Vrin error:", err.status, err.message);
  } else {
    throw err;
  }
}

VrinError exposes:

message — human-readable description
status? — HTTP status, when relevant
body? — raw server payload, for logging

Custom fetch

For runtimes without a global fetch (Node 16, some embedded envs) or when you want a middleware-style interceptor:

import { VrinClient } from "@vrin/sdk";
import { fetch as undiciFetch } from "undici";

const client = new VrinClient({
  apiKey: process.env.VRIN_API_KEY,
  fetch: undiciFetch as unknown as typeof fetch,
});

Get Started

MCP Server

CLI

Python SDK

TypeScript SDK

Concepts

Guides

TypeScript SDK: VrinClient

Install

Authenticate

First query

Constructor options

Usage across runtimes

Next steps

Querying

Knowledge

Conversations

Error handling

Error handling

Custom fetch

​Install

​Authenticate

​First query

​Constructor options

​Usage across runtimes

​Next steps

Querying

Knowledge

Conversations

Error handling

​Error handling

​Custom fetch

Install

Authenticate

First query

Constructor options

Usage across runtimes

Next steps

Error handling

Custom fetch