Call Jev (TypeSafe AI) from TypeScript: AI SDK experimental_evaluate vs @typesafe-ai/sdk vs fetch

There are four ways to call Jev from TypeScript: TypeSafe's own SDK, the Vercel AI SDK's experimental_evaluate, a plain HTTP request, and the Cloudflare Workers binding. They differ in runtime, key variable, field names, default retries and timeouts. This page compares them at pinned versions and lists twelve TypeScript-specific mistakes.

Official SDK

@typesafe-ai/sdk 0.6.0, npm 15 Sep 2026, 18:17 UTC; tag 66880cc; MIT

AI SDK core

ai 7.0.122, 28 Sep 2026, 21:59 UTC; Apache-2.0

First ai with experimental_evaluate

7.0.103 (16 Sep) by package contents; Vercel's guide says 7.0.105

AI SDK direct provider

@ai-sdk/typesafe-ai 3.0.10, 28 Sep 2026, 22:00 UTC

Node

SDK ≥ 20; ai and @ai-sdk/typesafe-ai ≥ 22

Which path fits your project

Comparison at pinned versions

Documented SDK source at tag v0.6.0 (retry.ts, errors.ts, client.ts); AI SDK evaluate reference, evaluation guide and TypeSafe provider page; Cloudflare model page; all checked 29 Sep 2026

Minimal Choice call per path

Each example asks one Choice question about a support message. The code follows each owner's published example and has not been run by the pool, which has no API key. Model IDs differ by route; the current IDs are in the route matrix.

1. @typesafe-ai/sdk 0.6.0 Documented, not executed SDK README and docs JavaScript page

// npm install @typesafe-ai/sdk@0.6.0        (Node >= 20, server side only)
// export TYPESAFE_API_KEY=...
import { TypeSafeClient, choice } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();          // throws at once if the key is missing
const response = await client.systemOne({
  state: "I was charged twice for my subscription this month.",
  questions: {
    category: choice("What is this ticket about?", { billing: null, technical: null, other: null }),
  },
});

console.log(response.answers.category.choice, response.answers.category.confidence);
console.log(response.model);                  // log which versioned model answered

The documented example sets no model, so the SDK default alias jev-latest applies. What jev-latest points to, and which ID to pin on each route: Jev model IDs and aliases by route.

2. AI SDK experimental_evaluate through Vercel AI Gateway Documented, not executed ai-sdk.dev evaluation guide and TypeSafe provider page

// npm i ai@7.0.122                          (Node >= 22; 7.0.105 or later per Vercel)
// export AI_GATEWAY_API_KEY=...
import { experimental_evaluate } from "ai";

const result = await experimental_evaluate({
  model: "typesafe-ai/jev",
  state: "I was charged twice for my subscription this month.",
  questions: {
    department: {
      type: "choice",
      instructions: "Which team should handle this?",
      criteria: { billing: "Payments and invoices", technical: "Bugs and integrations", other: null },
    },
  },
});

console.log(result.answers.department.choice);
console.log(result.providerMetadata?.typesafe?.confidence?.department);  // confidence is not on the answer

For TypeSafe direct instead of the gateway, install @ai-sdk/typesafe-ai, set TYPESAFE_AI_API_KEY, and pass model: typeSafeAi.evaluationModel("jev-latest") (base URL https://api.typesafe.ai/v1).

3. Raw fetch Documented, not executed request shape from the docs quickstart; the timeout line is the pool's addition

const res = await fetch("https://api.typesafe.ai/v1/systemone", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "jev-1.13.0",
    state: "I was charged twice for my subscription this month.",
    questions: {
      category: { type: "choice", instructions: "What is this ticket about?",
                  criteria: { billing: null, technical: null, other: null } },
    },
  }),
  signal: AbortSignal.timeout(10_000),        // raw fetch has no timeout unless you set one
});
if (!res.ok) throw new Error(`Jev ${res.status}: ${await res.text()}`);
const body = await res.json();
console.log(body.answers.category.choice, body.answers.category.confidence);

A retry loop for this path, tested offline against a local mock server, is the worked example on Testing without a key.

4. Cloudflare Workers binding Documented, not executed Cloudflare model page for typesafe/jev

export default {
  async fetch(request, env) {
    const response = await env.AI.run("typesafe/jev", {
      state: "I was charged twice for my subscription this month.",
      questions: {
        department: { type: "choice", instructions: "Which team should handle this?",
                      criteria: { billing: null, technical: null, other: null } },
      },
    });
    return Response.json(response);
  },
};

How long a call can take with default settings

With the official SDK's defaults and an endpoint that never answers, one call makes 3 attempts of 10 s each, with 0.5 s and 1 s waits between them. That adds up to about 31.5 s. The Claude Code plugins audited on Claude Code and MCP give a hook 10–15 s. Set a per-call timeout shorter than your caller's deadline.

TypeScript gotchas

Status codes and their meanings are on Errors and rate limits. This table lists only problems specific to the TypeScript paths.

Open issues in the official JS SDK

Open on GitHub on 29 Sep 2026. Each is the reporter's description, not rerun by the pool. Reported

• #2: a handled cancellation can crash Node 20 and 22.
• #6: noul() with no arguments, and state: null, build requests the API rejects.
• #8: timeouts above Node's timer maximum fire after about 1 ms.
• #9: a blank Retry-After header bypasses backoff.
• #12: score() accepts a null level, which returns 422.
• #13: 402 and 413 fall through to a generic APIError.
• #14: the API key can be echoed into APIConnectionError, and an empty key is sent.
• #15: Cloudflare HTML 403 when the state contains curl text.
• #17: non-finite numbers serialise as null.

Issue list: typesafe-ai/typesafe-sdk-js issues.

Projects that use these paths

Seen only: TanStack AI decide() with vercelGatewayDecider('typesafe-ai/jev') or cloudflareDecider('typesafe/jev'), described by Vercel. LangChain JS (@langchain/typesafe 0.0.2) and @effect/ai-typesafe 4.0.1 were read on 5 Oct 2026: see framework integrations. For TypeScript demo videos, see the TypeScript group on the videos page.