jev typescript sdk

Install on a Server Runtime

The official package ships ESM, CommonJS and TypeScript declarations and requires Node 20 or newer. The client reads TYPESAFE_API_KEY and defaults to https://api.typesafe.ai and jev-latest. Pin the package in the lockfile and pin the Jev model once a workflow has been evaluated.

The SDK refuses browser execution unless dangerouslyAllowBrowser is explicitly enabled, because browser code exposes the API key. Treat that switch as a warning, not a deployment shortcut. Put Jev behind a server route, worker or other trusted execution boundary.

npm install @typesafe-ai/sdk

Let the Question Object Drive Answer Types

The SDK’s public types map each question key to its corresponding response type and preserve Choice criteria keys. Keep question literals narrow enough for inference. Type safety prevents reading confidence from a Noul, but it cannot prove the semantic answer is correct.

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

const questions = {
  queue: choice("Which approved team should handle this?", {
    billing: "Charges, invoices and refunds",
    technical: "Product errors and integrations",
    other: "Neither billing nor technical",
  }),
  refundRequested: noul("Does the customer explicitly request a refund?"),
  urgency: score("How urgent is this?", [
    "Routine: no deadline or blocked work",
    "Time-sensitive: deadline or degraded work",
    "Critical: essential work is blocked",
  ] as const),
} as const;

const client = new TypeSafeClient({ defaultModel: "jev-1.13.0" });
const result = await client.systemOne({
  state: { message: "Charged twice; payroll is blocked." },
  questions,
});

result.answers.queue.choice;          // "billing" | "technical" | "other"
result.answers.queue.probabilities;   // keyed by the same labels
result.answers.refundRequested.noul;  // number
result.answers.urgency.score;         // number

Timeout Is per Attempt, Not a Total Budget

Current SDK source sets a 10,000 ms timeout per attempt and two retries after the initial request. Retryable conditions include HTTP 408, 429 and 5xx responses, connection errors and timeouts. Backoff starts at 500 ms, caps at 5,000 ms, subtracts up to 25% jitter, and respects Retry-After or retry-after-ms up to 60 seconds.

Three ten-second attempts plus backoff can exceed an interactive action budget. Set client or per-call options from the workflow’s deadline; use an outer cancellation signal or deadline where necessary. Retry defaults are implementation facts from the current SDK source, not API guarantees, so date and re-check them after dependency upgrades.

Handle Typed Failures Without Swallowing Evidence

The current SDK exposes status-specific API errors plus connection, timeout and user-abort errors. Avoid logging unredacted request bodies: the source notes that known credential headers are redacted at debug level but bodies are not. Preserve the provider request ID when available.

import {
  APIError,
  APITimeoutError,
  APIUserAbortError,
  RateLimitError,
} from "@typesafe-ai/sdk";

try {
  const result = await client.systemOne(request, {
    timeout: 2_000,
    retry: { maxRetries: 1 },
    signal: abortController.signal,
  });
  return result;
} catch (error) {
  if (error instanceof APIUserAbortError) throw error;
  if (error instanceof RateLimitError) {
    // Queue, shed load or use the workflow's explicit fallback.
    console.warn(error.requestId, error.retryAfterMs);
  }
  if (error instanceof APITimeoutError) {
    // Treat as service failure, never as a low-probability answer.
  }
  if (error instanceof APIError) {
    console.error(error.status, error.requestId);
  }
  throw error;
}

Separate Transport Success from Decision Success

A 200 response with a well-typed result may still be semantically wrong. A timeout has no model probability. Store those outcomes separately and follow Jev calibration for model quality and the failure guide for transport behavior.

Use the Injectable Fetch Seam for Contract Tests

The SDK accepts a custom fetch implementation, making it possible to simulate HTTP responses, interrupted bodies and headers without intercepting global networking. Test answer parsing, request headers, retries, cancellation and failure mapping with deterministic fixtures; use separate credentialed smoke tests for the real endpoint.

Do not snapshot an exact Jev probability as a conventional unit test. Pin the model and replay labeled datasets for semantic regression, then compare distributions and decisions with tolerances and outcome metrics. The model-version guide provides the upgrade gate.