Connect Jev with JavaScript and TypeScript

1. Install the official SDK

Requirements: Node.js 20 or newer, npm and a TypeSafe account with API access. Use a local or server process. Never put the key in a browser bundle. The official SDK README supports JavaScript and TypeScript, with ESM, CommonJS and inferred answer types.

Windows · PowerShell

npm.cmd install --save-exact @typesafe-ai/sdk@0.6.0
$env:TYPESAFE_API_KEY = "<your-key>"

macOS / Linux

npm install --save-exact @typesafe-ai/sdk@0.6.0
export TYPESAFE_API_KEY="<your-key>"

Run installation in your project folder. Enter your real key privately in the terminal or use your secret manager. Get API access through the TypeSafe console. Version 0.6.0 was checked against the published npm package on 2026-10-05.

2. Make one structured request

Save the download in your project folder. The .mjs extension runs as an ES module without changing package.json. This example asks for a format, not generated text. The named question format produces response.answers.format. Its criteria are a finite set.

Windows, macOS and Linux

node connect-jev-js.mjs

import { choice, TypeSafeClient } from '@typesafe-ai/sdk';
import { pathToFileURL } from 'node:url';

export async function decide(client, document) {
  const result = await client.systemOne({
    state: { document },
    questions: { format: choice('Which export format is requested?', {
      csv: 'A spreadsheet or comma-separated table',
      json: 'Structured JSON data',
      other: 'Neither format, or insufficient information',
    }) },
  });
  const answer = result.answers?.format;
  if (!answer || !['csv', 'json', 'other'].includes(answer.choice)
      || !Number.isFinite(answer.confidence) || answer.confidence < 0 || answer.confidence > 1) {
    throw new Error('Invalid decision response');
  }
  return { model: result.model, choice: answer.choice, confidence: answer.confidence,
    probabilities: answer.probabilities,
    route: answer.confidence >= 0.8 && answer.choice !== 'other' ? answer.choice : 'review' };
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  if (!process.env.TYPESAFE_API_KEY) {
    console.error('Set TYPESAFE_API_KEY in this local or server process.');
    process.exitCode = 1;
  } else {
    try {
      const client = new TypeSafeClient({ timeout: 15000, retry: { maxRetries: 0 }, logLevel: 'off' });
      console.log(JSON.stringify(await decide(client, 'Export my table as CSV.'), null, 2));
    } catch {
      console.error('Decision failed. Check credentials, connectivity and account status privately.');
      process.exitCode = 1;
    }
  }
}

3. Keep TypeScript inference

In an existing server-side TypeScript project, use the same imports and call. The SDK infers the allowed labels directly from the criteria object; no hand-written response cast is needed. Your project’s existing TypeScript build compiles this fragment.

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient();
const result = await client.systemOne({
  state: { document: "Export as CSV" },
  questions: { format: choice("Requested format?", { csv: null, json: null, other: null }) },
});
const format: "csv" | "json" | "other" = result.answers.format.choice;

4. Handle the response and errors

The script checks the label and confidence before applying an illustrative confidence >= 0.8 policy. A confident other still goes to review. It prints model, choice, confidence and probabilities. The jev-latest alias can change, so retain the returned model in evaluations. Network errors produce a generic error message and a nonzero exit status without logging request bodies or credentials.

Offline fixture example: {"choice":"csv","confidence":0.9,"route":"csv"}. This is an illustration, not a live inference result.

Contract references: client and configuration, request and response types, native API. The installed SDK 0.6.0 was exercised offline through its custom fetch transport. Live API test: Not checked. No model request was sent for this guide.

Troubleshooting

ERR_MODULE_NOT_FOUND

Install the pinned SDK in the same project folder as the downloaded .mjs file.

Missing key or authentication failure

Set TYPESAFE_API_KEY in the process that launches Node. Check your account privately; do not print the key.

Timeout, rate limit or network failure

The example uses a 15-second timeout and disables retries. Keep API failure distinct from a valid decision. Add bounded retries only with an explicit request budget.

A valid label is wrong

Review the state and criteria with labelled task examples. Confidence is not a measured accuracy rate.

Next: put the next agent step behind an application policy →

Projects to explore

These are catalog records with their own sources and evidence labels.

• @typesafe-ai/sdk (TypeScript) official

  The official TypeScript/JavaScript client, shipping ESM, CJS and type declarations for Node 20+; same ticket-classification quickstart as the Python SDK.

• typesafe-sdk (Python) official

  The official Python client (`uv add typesafe-sdk`) with sync and async variants; the quickstart classifies support tickets into billing, technical or other.

• Agent Squad: typed Jev routing source-backed

  Agent Squad includes JevClassifier implementations in TypeScript and Python. A typed Choice question selects among configured agents using the request and conversation context.