Jev JavaScript SDK: Install, Examples and Errors

The official JavaScript and TypeScript client is @typesafe-ai/sdk. It ships ESM, CommonJS and TypeScript declarations, and talks to TypeSafe’s own API. We ran the examples below with version 0.6.0 on Node.js 24 on September 19, 2026. (On Vercel’s AI Gateway you would use the AI SDK’s experimental_evaluate instead; see Jev on Vercel.)

Install

npm install @typesafe-ai/sdk

It requires Node.js 20 or newer. The package reads TYPESAFE_API_KEY from the environment.

Ask questions

triage.mjs

import { TypeSafeClient, noul, choice, score } from '@typesafe-ai/sdk';

const client = new TypeSafeClient({ defaultModel: 'jev-1.13.0' });

const response = await client.systemOne({
  state: 'I was charged twice for my annual plan this morning. Please refund one of the charges today.',
  questions: {
    wantsRefund: noul('Is the customer asking for money back?'),
    queue: choice('Which team should handle this message?', {
      billing: 'Charges, invoices, refunds',
      technical: 'Bugs, outages, integrations',
      sales: 'New plans, upgrades, quotes',
    }),
    urgency: score('How urgent is this message?', [
      'Can wait a week',
      'Should be handled this week',
      'Needs a reply today',
    ]),
  },
});

console.log(response.answers.wantsRefund.noul);    // 0.99
console.log(response.answers.queue.choice);        // "billing"
console.log(response.answers.queue.confidence);    // 1
console.log(response.answers.urgency.score);       // 2
console.log(response.usage);                       // { input_tokens: 418, output_tokens: 72 }

This took 539 ms in our run. The helpers take the instructions first, then the criteria: an object of option descriptions for choice (use null when the name is self-explanatory) and an ordered array of levels for score.

In TypeScript, the answer types are inferred from the questions, so response.answers.queue.choice is typed as "billing" | "technical" | "sales", and a typo in a question ID is a compile error.

Client options

Option	Default	Notes
apiKey	TYPESAFE_API_KEY	Without any key, the client throws TypeSafeError before sending
defaultModel	TYPESAFE_DEFAULT_MODEL, then jev-latest	Use jev-1.13.0 to pin the version
baseURL	https://api.typesafe.ai
timeout	10,000 ms per attempt	There is no total budget across retries
retry	2 retries, 500 ms backoff doubling to 5,000 ms, 25% jitter	Retries 408, 429 and 500 to 599, timeouts and connection errors; honors Retry-After
logLevel	warn	debug logs bodies; credential headers are redacted
dangerouslyAllowBrowser	false	Leave it off: a key in browser code can be copied by anyone

List the model names your account can use:

const models = await client.models.list();
console.log(models.map((m) => m.name)); // ["jev-latest", "jev-preview"]

Errors

import { TypeSafeClient, noul, AuthenticationError, BadRequestError, RateLimitError } from '@typesafe-ai/sdk';

try {
  await client.systemOne({ state: 'hi', questions: { q: noul('Is this a greeting?') } });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401: fix the key, do not retry
  } else if (err instanceof BadRequestError) {
    // 400: unknown model, unknown question type or max_tokens_exceeded
  } else if (err instanceof RateLimitError) {
    // 429 that survived the built-in retries: slow down
  } else {
    throw err;
  }
}

With an invalid key we got an AuthenticationError with status 401 and the message “Cannot authenticate with the server. Please check your API key and try again.” Other classes include PermissionDeniedError (403), UnprocessableEntityError (422), InternalServerError (5xx, including 529), APITimeoutError and APIConnectionError. See Jev API errors for what each one means.

Version notes

Version 0.6.0 (September 15, 2026) changed Score criteria from an object keyed by numbers to an ordered array. Code written for 0.5.7 that passes { 0: "...", 1: "..." } needs updating. See the Jev changelog.

Where to run it

Run Jev calls on your server, in a serverless function or in a Worker, never in the browser with a real key. For latency-sensitive paths, create the client once at startup and reuse it; put all questions about one input into a single systemOne call.

See also: Your first Jev call, Jev API reference.