JavaScript/TypeScript SDK: install, client, choice/score/noul

TL;DR npm install @typesafe-ai/sdk (Node >= 20), set TYPESAFE_API_KEY, then new TypeSafeClient().systemOne({ state, questions }). Build questions with choice(instructions, {label: description}), score(instructions, [ ...ordered rubric ]), and noul(instructions?, criteria?). Answers are typed from the questions you passed; the call returns an APIPromise<SystemOneResult<Q>>, so await it for data or .withResponse() for data plus the raw Response and request ID.

Package facts

Install

npm install @typesafe-ai/sdk

Then set the API key in the environment:

export TYPESAFE_API_KEY="sk-..."   # value format not documented in raw sources

Entry points (ESM + CJS + declarations)

package.json declares dual exports. The README and docs both state: "The package includes ESM, CommonJS, and TypeScript declarations."

ESM:

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

CommonJS:

const { choice, noul, score, TypeSafeClient } = require("@typesafe-ai/sdk");

There is no deep-import subpath: everything is exported from the package root (src/index.ts is the single entry).

JSR

The repo contains a jsr.json and npm scripts push:jsr / push:jsr:dry, so the package is set up for JSR publication:

{
  "name": "@typesafe-ai/sdk",
  "version": "0.6.0",
  "license": "MIT",
  "exports": "./src/index.ts",
  "publish": {
    "include": ["src/**/*.ts", "README.md", "LICENSE", "jsr.json"],
    "exclude": ["src/**/*.test.ts"]
  }
}

Note that the JSR entry point is the TypeScript source (./src/index.ts), not dist/. Whether a JSR release actually exists on jsr.io is not confirmed by any source in raw/ — only npm releases are recorded (see JavaScript SDK changelog).

What the package exports

From src/index.ts (value exports unless marked type-only):

Models is exported as a type only, so you cannot new Models(...) from the package; you reach it through client.models. (The published API reference lists it under "Interfaces"; in source it is a class — see the version notes at the bottom.)

TypeSafeClient

new TypeSafeClient(config?: TypeSafeClientConfig): TypeSafeClient;

"Client for the TypeSafe AI API." Explicit options take precedence over environment variables, then SDK defaults. Empty or whitespace-only environment values are ignored (readEnv trims and treats blank as absent).

Throws TypeSafeError when the API key is missing, configuration is invalid, or the runtime is unsupported.

Constructor config

Full property table for TypeSafeClientConfig (all properties optional):

Construction-time failures, all TypeSafeError (messages verbatim from src/client.ts):

• Browser detected and dangerouslyAllowBrowser not set: "TypeSafeClient is running in a browser, which would expose your API key to anyone using the page. Call the API from a server instead, or pass dangerouslyAllowBrowser: true if you understand the risk."
• No key: "No API key was provided. Pass apiKey to the TypeSafeClient constructor or set the TYPESAFE_API_KEY environment variable."
• No global fetch and no fetch option: "No global fetch is available in this runtime. Pass a fetch implementation to the TypeSafeClient constructor."
• Invalid timeout: "timeout must be a positive number of milliseconds, got X."

Instance properties

All are readonly. The API key is stored in a private field (#apiKey) and is not a public property.

systemOne()

systemOne<const Q extends Questions>(
  request: SystemOneRequest<Q>,
  options?: RequestOptions,
): APIPromise<SystemOneResult<Q>>;

"Answer named questions about text or structured state."

request fields: state: EntryType (required), questions: Q (required, nonempty), model?: string (override; omitted values inherit defaultModel). Additional properties on a request variable are forwarded, including null values.

Wire behaviour: the SDK validates questions locally, then POSTs {...request, model: request.model ?? client.defaultModel} (a SystemOneRequestPayload) to POST /v1/systemone. See HTTP API: POST /v1/systemone and GET /v1/models.

Throws:

Upstream example:

const { answers } = await client.systemOne({
  state: "I was charged twice. Please help.",
  questions: { billing: noul("Is this about billing?") },
});
console.log(answers.billing.noul);

Headers the client sends

Built in fetchWithRetries. User-supplied headers are merged first so they cannot clobber auth or the JSON content type; header matching is case-insensitive, last value wins.

The response request ID is read from x-typesafe-request-id.

Question builders

All three are plain functions that return a literal object; nothing is sent when you call them.

choice()

function choice<const T extends ChoiceCriteria>(
  instructions: EntryType,
  criteria: T,
): ChoiceQuestion<T>;

Throws TypeSafeError "Choice criteria must be a map of labels to descriptions, not a list." if you pass an array.

score()

function score<const T extends ScoreCriteria>(
  instructions: EntryType,
  criteria: T,
): ScoreQuestion<T>;

Throws TypeSafeError "Score criteria must be a list of descriptions indexed by score from zero, not a map." if you pass an object. In v0.6.0 the rubric is an ordered sequence, not an int-keyed map — see JavaScript SDK changelog.

noul()

function noul(
  instructions?: EntryType,
  criteria?: { true?: EntryType; false?: EntryType } | null,
): NoulQuestion;

Validation of the whole question set

systemOne() calls validateQuestions before sending. It throws TypeSafeError for:

• an empty object: "At least one question is required."
• a score question whose criteria is not an array: Score question "<name>" has criteria that are not a list; score criteria must be a list of descriptions indexed by score from zero.
• a score question with fewer than two criteria: Score question "<name>" has N criteria; at least two scores are required.

choice and noul questions are not otherwise validated client-side.

SystemOneRequest / SystemOneResult in practice

SystemOneResult<Q> is { model: string; answers: { [K in keyof Q]: ResultFor<Q[K]> }; usage: Usage }. The mapping ResultFor is what makes answers typed by question:

usage is { input_tokens: number; output_tokens: number } — snake_case, matching the wire format.

TypeScript generics usage — the const type parameter is what preserves literal label and tuple types, so you get narrowed keys without any manual annotation:

import { choice, score, TypeSafeClient } from "@typesafe-ai/sdk";
import type { ChoiceResponse, ScoreResponse, SystemOneResult } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();

const questions = {
  tone: choice("What is the customer's tone?", { calm: null, angry: null }),
  urgency: score("How urgent is this?", ["can wait", "today", "right now"]),
} as const;

const result: SystemOneResult<typeof questions> = await client.systemOne({
  state: "My account is locked and I have a demo in ten minutes.",
  questions,
});

// `tone.choice` is "calm" | "angry", not string:
const tone: ChoiceResponse<{ calm: null; angry: null }> = result.answers.tone;
if (tone.choice === "angry") console.log("escalate");

// `urgency.probabilities` is keyed "0" | "1" | "2":
const urgency: ScoreResponse<readonly ["can wait", "today", "right now"]> = result.answers.urgency;
console.log(urgency.probabilities["2"], urgency.legend["2"]);

Writing questions inline in the systemOne({ questions: { ... } }) call gives the same inference, because systemOne itself declares <const Q extends Questions>.

APIPromise

systemOne() and models.list() return APIPromise<T>, a Promise<T> subclass. "Non-2xx responses reject with an APIError, including through asResponse()." The body is parsed lazily and at most once; then/catch/finally are overridden to go through that single parse.

Constructor (public but intended for internal use): new APIPromise<T>(responsePromise: Promise<Response>, parseResponse: (response: Response) => Promise<T>).

const { data, response, requestId } = await client
  .systemOne({ state: "…", questions: { ok: noul("Is this fine?") } })
  .withResponse();

console.log(requestId, response.status, response.headers.get("x-typesafe-request-id"));
console.log(data.answers.ok.noul);

models resource

client.models.list(options?: RequestOptions): APIPromise<ModelCard[]>

"List the models available to the account." Calls GET /v1/models and unwraps the { models: [...] } envelope; a response of any other shape raises TypeSafeError "Unexpected response shape from GET /v1/models; expected { models: [...] }."

ModelCard: { readonly name: string; readonly description: string; readonly release_date: string }. Catalogue and pricing live in Models, aliases, pricing, rate limits, context.

const models = await client.models.list();
console.log(models.map((m) => `${m.name} (${m.release_date})`).join("\n"));

Logging

What gets logged: info emits per-attempt summaries (#3 POST /v1/systemone <- 200 in 412ms (request req_…), timeouts, aborts, retry waits). debug additionally logs outgoing URL + headers + body and the parsed response body. Redaction covers authorization, proxy-authorization, x-api-key (masked to Bearer ***abcd, keeping the scheme and the last four characters of secrets longer than eight) and cookie / set-cookie (***). Request and response bodies are not redacted — do not use debug on production traffic containing personal data.

An invalid level from either the option or TYPESAFE_LOG_LEVEL throws TypeSafeError: Invalid log level "X" from <source>. Expected one of: debug, info, warn, error, off.

const client = new TypeSafeClient({
  logLevel: "debug",
  logger: {
    debug: (m, ...a) => myLogger.trace({ a }, m),
    info: (m, ...a) => myLogger.info({ a }, m),
    warn: (m, ...a) => myLogger.warn({ a }, m),
    error: (m, ...a) => myLogger.error({ a }, m),
  },
});

Environment variables and VERSION

ENV maps config keys to env var names (see TYPESAFE_* environment variables across SDKs):

VERSION is the string literal type "0.6.0", kept in sync with package.json and checked by npm run check:version.

End-to-end example

examples/demo.ts verbatim from the repo (run with npm run demo, which invokes tsx examples/demo.ts; needs TYPESAFE_API_KEY). The only change you need outside the repo is importing from "@typesafe-ai/sdk" instead of "../src":

// Run with `npm run demo`. Needs TYPESAFE_API_KEY in the environment.
import { APIError, choice, noul, score, TypeSafeClient } from "../src";

const client = new TypeSafeClient({ logLevel: "info" });

const models = await client.models.list();
console.log("Available models:", models.map((m) => m.name).join(", "));

const ticket = {
  subject: "Charged twice this month",
  body: "Hi, I see two charges of $49 on my card for August. I only have one account. Please fix this ASAP, I'm pretty frustrated.",
};

try {
  const { answers, usage } = await client.systemOne({
    state: ticket,
    questions: {
      isBilling: noul("Is this ticket about billing?"),
      sentiment: choice("What is the customer's tone?", {
        calm: null,
        frustrated: null,
        angry: null,
      }),
      urgency: score("How urgent is this ticket?", ["can wait", "this week", "today", "right now"]),
      refundRisk: score("How likely is the customer to demand a refund?", [
        "unlikely",
        "possible",
        "likely",
      ]),
    },
  });

  // Every answer is typed by the question that produced it.
  const { isBilling, sentiment, urgency, refundRisk } = answers;
  console.log("billing?    ", isBilling.noul.toFixed(2));
  console.log(
    "tone        ",
    sentiment.choice,
    `(${sentiment.probabilities[sentiment.choice].toFixed(2)})`,
  );
  console.log("urgency     ", urgency.score.toFixed(2), "on a 0-3 scale:", urgency.legend);
  console.log(
    "refund risk ",
    refundRisk.score.toFixed(2),
    `(${refundRisk.confidence.toFixed(2)} confidence)`,
  );
  console.log("tokens      ", usage.input_tokens, "in /", usage.output_tokens, "out");
} catch (err) {
  if (err instanceof APIError) {
    console.error(`API error ${err.status} (request ${err.requestId ?? "unknown"}):`, err.body);
  } else {
    throw err;
  }
}

The file uses top-level await, so it must run as ESM. The CommonJS equivalent wraps the body in an async IIFE:

const { APIError, choice, noul, score, TypeSafeClient } = require("@typesafe-ai/sdk");

(async () => {
  const client = new TypeSafeClient({ logLevel: "info" });
  try {
    const { answers, usage } = await client.systemOne({
      state: { subject: "Charged twice this month", body: "Two $49 charges in August." },
      questions: {
        isBilling: noul("Is this ticket about billing?"),
        sentiment: choice("What is the customer's tone?", {
          calm: null,
          frustrated: null,
          angry: null,
        }),
        urgency: score("How urgent is this ticket?", ["can wait", "this week", "today", "right now"]),
      },
    });
    console.log(answers.isBilling.noul, answers.sentiment.choice, answers.urgency.score);
    console.log(usage.input_tokens, usage.output_tokens);
  } catch (err) {
    if (err instanceof APIError) {
      console.error(`API error ${err.status} (request ${err.requestId ?? "unknown"}):`, err.body);
    } else {
      throw err;
    }
  }
})();

Gotchas

• Browser use is refused by default. isBrowser() checks for window.document and navigator; if present and dangerouslyAllowBrowser is not true, the constructor throws. Call the API from a server.
• timeout is per attempt, not per call. With maxRetries: 2 and timeout: 10000, worst-case wall time is roughly three attempts plus backoff.
• The body is fully buffered before the promise resolves, under the same timeout, so asResponse() hands you a response whose body is already readable — but don't consume both asResponse() and the parsed value on the same APIPromise.
• score criteria must be a list in 0.6.0; an int-keyed object throws TypeSafeError at build time (score()) or at validation time (systemOne()).
• Response parsing is lenient: bodies are JSON.parsed even when content-type is missing, falling back to the raw text, and an empty body parses to undefined.
• defaultHeaders cannot override auth: Authorization, Accept, User-Agent, X-TypeSafe-SDK, X-TypeSafe-Runtime, and Content-Type are merged last and win.

Version notes

• This page describes @typesafe-ai/sdk 0.6.0 (repo commit 66880ccded6cb642dc1809620c2b108c33730214, 2026-09-15).
• Doc-vs-source discrepancy: the published API reference lists Models under Interfaces (# Interface: Models), but src/resources/models.ts declares export class Models with a constructor taking an internal Transport. Because src/index.ts re-exports it with export type { Models }, only the type is importable — the docs' classification is accurate from a consumer's point of view, but the source is a class.
• The docs' ChoiceCriteria index signature renders as [label: string]: EntryType; source writes [label: string]: Description, and Description = EntryType, so they are the same type.

Related

• JavaScript SDK interfaces and type aliases — every interface and type alias in detail
• JavaScript SDK error classes, RetryPolicy, RequestOptions — error classes, RetryPolicy, RequestOptions
• JavaScript SDK changelog — release history
• HTTP API: POST /v1/systemone and GET /v1/models — the wire contract behind systemOne() and models.list()
• TYPESAFE_* environment variables across SDKs — TYPESAFE_* across SDKs
• Python SDK: install, clients, system_one() — the Python equivalent
• Primitives: Choice, Score, Noul — Choice, Score, Noul
• Quickstart: first call in HTTP, Python, JS — first call in HTTP, Python, JS

Sources

• raw/docs/sdk__javascript.md (https://docs.typesafe.ai/sdk/javascript)
• raw/docs/sdk__javascript__api.md (https://docs.typesafe.ai/sdk/javascript/api)
• raw/docs/sdk__javascript__api__classes__TypeSafeClient.md (https://docs.typesafe.ai/sdk/javascript/api/classes/TypeSafeClient)
• raw/docs/sdk__javascript__api__classes__APIPromise.md (https://docs.typesafe.ai/sdk/javascript/api/classes/APIPromise)
• raw/docs/sdk__javascript__api__functions__choice.md, __score.md, __noul.md
• raw/docs/sdk__javascript__api__interfaces__Models.md, __Logger.md
• raw/docs/sdk__javascript__api__variables__VERSION.md, __LOG_LEVELS.md, __ENV.md
• raw/github/typesafe-sdk-js (https://github.com/typesafe-ai/typesafe-sdk-js, commit 66880ccded6cb642dc1809620c2b108c33730214): README.md, package.json, jsr.json, examples/demo.ts, src/index.ts, src/client.ts, src/questions.ts, src/api-promise.ts, src/logging.ts, src/env.ts, src/runtime.ts, src/version.ts, src/resources/models.ts