Tutorials
Jev TypeScript Tutorial
Use @typesafe-ai/sdk 0.7.0 to call Jev from TypeScript or JavaScript with inferred Choice, Score, and Noul answers.
Quick answer
Install @typesafe-ai/sdk on Node.js 22+, set TYPESAFE_API_KEY, and call TypeSafeClient.systemOne with choice(), score(), and noul() helpers. Answer types are inferred from your questions. The package ships ESM, CommonJS, and TypeScript declarations.
One SDK covers TypeScript and JavaScript. Use the typed helpers below, or start with the plain JavaScript example.
Install
npm install @typesafe-ai/sdk@0.7.0The reviewed release is 0.7.0 (2026-10-14). It requires Node.js 22+, removes request payload type exports, and adds experimental images and Box. On Node.js 22.15+, bodies of at least 1 KiB use zstd; set compression: false if your gateway does not support it. See the migration checklist.
Official requirement: Node.js 22+. The client reads TYPESAFE_API_KEY.
First call
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient();
const ticket =
"The export button crashes the settings page in Safari. Works in Chrome, but some of our customers only use Safari.";
const { answers, model, usage } = await client.systemOne({
state: { ticket },
questions: {
category: choice("What kind of ticket is `ticket`?", {
bug_report: "Something is broken or behaving wrong",
feature_request: "Asks for something that does not exist yet",
billing: "Charges, invoices, refunds",
other: null,
}),
severity: score("How severe is the issue in `ticket`?", [
"Cosmetic only",
"Feature broken with a workaround",
"Blocking, no workaround",
]),
needs_eng: noul("Does `ticket` report a product defect?"),
},
});
console.log(answers.category.choice);
console.log(answers.severity.score);
console.log(answers.needs_eng.noul);
console.log(model, usage.input_tokens);Answer types follow the helpers: answers.category.choice type-checks, answers.needs_eng.noul type-checks.
Confidence gate
Pattern from official confidence docs, adapted to the JS client:
const action = answers.category;
if (action.confidence < 0.5) {
// escalate
} else if (action.choice === "billing") {
// low-stakes path
}Those numbers are examples. Measure on your tickets.
Plain JavaScript
import { choice, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient();
const response = await client.systemOne({
state: { document: "I was charged twice. Please fix this ASAP." },
questions: {
category: choice("What is this ticket about?", {
billing: null,
technical: null,
other: null,
}),
},
});
console.log(response.answers.category.choice);Errors
The SDK documents classes such as AuthenticationError, RateLimitError, UnprocessableEntityError, APIConnectionError, and APITimeoutError. Retry 429/529; fix 401/422.
When to use this SDK
Node servers, Next.js Route Handlers, and workers. Not the browser.
When not to
If you only need to inspect JSON once, use cURL. If the service is Python, use Jev Python.
Common mistakes
- Importing
system_one(Python name) instead ofsystemOne. - Shipping the key in
NEXT_PUBLIC_*. - Forgetting
otheron a Choice. See Choice.
FAQ
Is there a separate JavaScript tutorial?
The same SDK works in both languages. This tutorial includes a plain JavaScript example.
What is the npm package?
@typesafe-ai/sdk 0.7.0, reviewed on 2026-10-20. Requires Node.js 22+. Python uses the separate typesafe-sdk package (0.7.5).
See what developers are building with Jev
Sources
- JavaScript SDKTypeSafe · accessed 2026-09-20 · documentation
- JavaScript SDK changelogTypeSafe · accessed 2026-10-20 · documentation
- Interface SystemOneRequestTypeSafe · accessed 2026-09-20 · documentation