Jev JavaScript & TypeScript SDK Tutorial

Use TypeSafeClient, choice(), score(), noul(), and systemOne() in Node.js with typed answer inference.

Requirements and installation

Use Node.js 20+ and a TypeSafe API key. The SDK supports ESM, CommonJS, and TypeScript declarations. This example is an ESM script.

npm install @typesafe-ai/sdk

Set TYPESAFE_API_KEY in the environment. Keep the key in a server, Worker, or command-line process. This static manual never calls the Jev API from the browser.

Complete support-ticket example

Save as support.mjs, or download it. The helper functions construct the correct instructions and criteria shapes.

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

const client = new TypeSafeClient();
const response = await client.systemOne({
  model: "jev-1.13.0",
  state: {
  "ticket": {
    "subject": "Duplicate subscription charge",
    "message": "I was charged twice this month. Please refund the duplicate before Friday."
  },
  "customer_plan": "pro"
},
  questions: {
    department: choice("Which team should handle this ticket?", {
      billing: "Payments and refunds", technical: "Bugs and outages",
      sales: "New purchases", other: "None of these"
    }),
    urgency: score("How urgent is the request?", [
      "No deadline", "This week", "Within a day", "Immediate harm"
    ]),
    refund_requested: noul("Does the customer explicitly request a refund?")
  }
});
const answer = response.answers.department;
// Educational threshold; validate on labeled tickets before deployment.
const queue = answer.confidence >= 0.85 ? answer.choice : "manual_review";
console.log({ queue, probabilities: answer.probabilities,
  urgency: response.answers.urgency.score,
  refundRequested: response.answers.refund_requested.noul,
  model: response.model, usage: response.usage });

Run it and read results

node support.mjs

The returned answers object is keyed by the question names. With TypeScript, helpers preserve answer types: a Choice has choice, a Score has score, and a Noul has noul. A confidence property belongs to Choice and Score, not Noul.

Typed inference and multiple questions

Keep the questions object close to the call so TypeScript can infer literal category names. If you build dynamic question maps, validate the runtime result before selecting a handler. One request can include all three types while sharing state.

Error handling

Await the call inside your application’s error boundary. The SDK exposes errors such as AuthenticationError, UnprocessableEntityError, RateLimitError, and APITimeoutError. Distinguish failures that require changing the request from transient failures that can retry with a bounded budget. Never interpret an exception as a low-risk answer.

Version pinning and deployment

The example pins jev-1.13.0. Log the returned version and usage. Keep the dependency lockfile in source control. On a Worker, inject the key from an environment secret rather than bundling a .env file. Provider SDKs may use different methods and schemas; see the separate integration guides.