JavaScript SDK interfaces and type aliases

TL;DR Everything under export type * from "./types" in @typesafe-ai/sdk 0.6.0, plus WithResponse, EnvVar, Models, and the two exported constants ENV and LOG_LEVELS. Question types carry a const generic over their criteria, and ResultFor maps each question type to its answer type — that is the whole reason answers.x.choice is a literal union rather than string.

Type map

RetryPolicy and RequestOptions also live in src/types.ts, but are documented on JavaScript SDK error classes, RetryPolicy, RequestOptions alongside the failure modes they govern.

Primitive value types

JsonValue

type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | { [key: string]: JsonValue };

"A JSON-compatible value." Recursive; used only as the element type inside EntryType.

EntryType

type EntryType = string | { [key: string]: JsonValue } | JsonValue[] | null;

"Text, a JSON object or array, or null for state, instructions, and criteria." Note it is not JsonValue: a bare number or boolean is not an EntryType.

Description

type Description = EntryType;

"A criterion description; null leaves the label undescribed." A readability alias over EntryType, used in ChoiceCriteria.

Questions

NoulQuestion

Nested criteria members:

ChoiceQuestion<T extends ChoiceCriteria = ChoiceCriteria>

ScoreQuestion<T extends ScoreCriteria = ScoreCriteria>

ChoiceCriteria

type ChoiceCriteria = { [label: string]: Description };

"Labels mapped to descriptions, or null for undescribed labels." The published docs render the index signature as [label: string]: EntryType; since Description = EntryType, the two spellings are identical.

ScoreCriteria

type ScoreCriteria = readonly [EntryType, EntryType, ...EntryType[]];

"At least two descriptions indexed by score from zero; null leaves a score undescribed." The tuple prefix is what enforces the two-entry minimum at compile time; validateQuestions re-checks it at runtime.

Question

type Question = NoulQuestion | ScoreQuestion | ChoiceQuestion;

"A question identified by its type field." The union members use their default generic arguments, so a Question-typed value has widened criteria.

Questions

interface Questions {
  [name: string]: Question;
}

"Questions keyed by the names used to identify their answers." Must be nonempty at call time — systemOne() throws TypeSafeError "At least one question is required." for {}.

Responses

NoulResponse

ChoiceResponse<T extends ChoiceCriteria = ChoiceCriteria>

(The generated docs print probabilities as { readonly [label in string | number | symbol]: number } — that is typedoc expanding keyof T for the default generic argument, not a different type.)

ScoreResponse<T extends ScoreCriteria = ScoreCriteria>

(Docs print probabilities as { readonly [score in number | \${number}`]: number }` — again the expansion for the default generic argument.)

Because score is an expectation, it is generally not an integer: a 0–3 rubric can return 2.41. See Score questions and Confidence vs probability.

ScoreOf<T extends ScoreCriteria>

type ScoreOf<T> = number extends T["length"] ? number : Extract<keyof T, `${number}`>;

"Score keys inferred from the rubric; a fixed-length tuple yields its indices, otherwise number." With score("…", ["a", "b", "c"] as const) you get "0" | "1" | "2"; with a readonly EntryType[] of unknown length you get number.

ScoreLegend<T extends ScoreCriteria>

type ScoreLegend<T> = { readonly [score in ScoreOf<T>]: T[score] };

"Rubric descriptions keyed by score." This is the server echoing back your rubric keyed by index, so legend["2"] is the literal description you supplied.

ResultFor<T extends Question>

type ResultFor<T> =
  T extends NoulQuestion ? NoulResponse
  : T extends ScoreQuestion<infer S> ? ScoreResponse<S>
  : T extends ChoiceQuestion<infer E> ? ChoiceResponse<E>
  : never;

"The answer type for a question, preserving its criteria keys." Order matters: NoulQuestion is tested first, then ScoreQuestion, then ChoiceQuestion; anything else resolves to never.

Usage

Snake_case, matching the wire format in HTTP API: POST /v1/systemone and GET /v1/models.

Requests and results

SystemOneRequest<Q extends Questions = Questions>

"State and named questions for systemOne. Additional properties on a request variable are forwarded, including null values."

The "additional properties are forwarded" note is a consequence of TypeScript's excess-property check applying only to object literals: pass a pre-declared variable with extra keys and the SDK spreads them into the request body. Treat that as a way to send fields the SDK does not model yet, and as a footgun otherwise.

SystemOneRequestPayload

extends SystemOneRequest (with the default Questions), overriding model:

"Request body for POST /v1/systemone, with the model resolved." You rarely construct one — systemOne() builds it as {...request, model: request.model ?? this.defaultModel} — but it is the exact JSON shape that goes on the wire.

SystemOneResult<Q extends Questions>

Note that Q has no default here, unlike SystemOneRequest<Q> — you always write SystemOneResult<typeof questions> or let inference supply it.

ModelCard

"Metadata for an available model." The three fields carry no per-field docstrings in either docs or source.

Models

"Access to the Models API resource." Reached as client.models; exported as a type only.

WithResponse<T>

Returned by APIPromise#withResponse(); exported from src/api-promise.ts, not src/types.ts.

Configuration types

TypeSafeClientConfig

"Client options. Explicit values take precedence over environment variables, then SDK defaults." Every property is optional.

Fetch

type Fetch = (input: string, init?: RequestInit) => Promise<Response>;

"HTTP fetch implementation compatible with the global fetch." Narrower than the DOM fetch: input is a string, not RequestInfo | URL.

Logger

"Log methods accepting a message and structured values; compatible with console." All four methods are required.

LogLevel

type LogLevel = "debug" | "info" | "warn" | "error" | "off";

"Log verbosity; off disables logging." Default warn.

EnvVar

type EnvVar = (typeof ENV)[keyof typeof ENV];

Resolves to "TYPESAFE_API_KEY" | "TYPESAFE_BASE_URL" | "TYPESAFE_DEFAULT_MODEL" | "TYPESAFE_LOG_LEVEL". The generated docs give it no description.

Exported variables

ENV

const ENV: {
  readonly apiKey: "TYPESAFE_API_KEY";
  readonly baseURL: "TYPESAFE_BASE_URL";
  readonly defaultModel: "TYPESAFE_DEFAULT_MODEL";
  readonly logLevel: "TYPESAFE_LOG_LEVEL";
};

"Environment variable names for client configuration. Explicit options take precedence."

LOG_LEVELS

const LOG_LEVELS: readonly LogLevel[];

"Supported log levels, from most to least verbose." Source value: ["debug", "info", "warn", "error", "off"]. The published docs give the type but not the value; the value comes from src/logging.ts.

VERSION

const VERSION: "0.6.0" = "0.6.0";

A literal type, not a widened string. See JavaScript/TypeScript SDK: install, client, choice/score/noul.

Runnable example: generics end to end

ESM, TypeScript. Nothing here is annotated except to prove the inferred types:

import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";
import type {
  ChoiceResponse,
  NoulResponse,
  Question,
  Questions,
  ResultFor,
  ScoreResponse,
  SystemOneRequest,
  SystemOneResult,
} from "@typesafe-ai/sdk";

const client = new TypeSafeClient();

const questions = {
  isBilling: noul("Is this ticket about billing?"),
  tone: 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"]),
} satisfies Questions;

const request: SystemOneRequest<typeof questions> = {
  state: { subject: "Charged twice", body: "Two $49 charges in August." },
  questions,
  model: "jev-latest",
};

const result: SystemOneResult<typeof questions> = await client.systemOne(request);

// ResultFor picks the answer type per question:
const billing: NoulResponse = result.answers.isBilling;
const tone: ChoiceResponse<{ calm: null; frustrated: null; angry: null }> = result.answers.tone;
const urgency: ScoreResponse<readonly ["can wait", "this week", "today", "right now"]> =
  result.answers.urgency;

console.log(billing.noul);                         // number, 0..1
console.log(tone.choice);                          // "calm" | "frustrated" | "angry"
console.log(tone.probabilities.angry);             // number
console.log(urgency.score, urgency.legend["3"]);   // number, "right now"
console.log(urgency.probabilities["0"]);           // number
console.log(result.model, result.usage.input_tokens, result.usage.output_tokens);

// Writing a generic helper: keep the `const` parameter to preserve literals.
async function ask<const Q extends Questions>(state: unknown, qs: Q) {
  const { answers } = await client.systemOne({ state: state as never, questions: qs });
  return answers;
}

// `ResultFor` is usable directly for a single question:
type ToneAnswer = ResultFor<(typeof questions)["tone"]>; // ChoiceResponse<{...}>

// A widened `Question` loses the literal keys — this is why you should not annotate:
const widened: Question = questions.tone;
type Widened = ResultFor<typeof widened>; // ChoiceResponse<ChoiceCriteria>, `choice` is `string`

CommonJS gets the same runtime behaviour but no type parameters at the call site unless you use // @ts-check with JSDoc:

const { choice, TypeSafeClient } = require("@typesafe-ai/sdk");
/** @type {import("@typesafe-ai/sdk").Questions} */
const questions = { tone: choice("Tone?", { calm: null, angry: null }) };

Gotchas

• Annotating kills inference. const q: Questions = {...} widens every criteria object; answers.x.choice becomes string. Use satisfies Questions or no annotation at all.
• ScoreOf degrades to number for arrays whose length TypeScript cannot see (e.g. string[]), which silently removes the literal keys from legend and probabilities.
• ChoiceResponse.choice is keyof T & string, so a criteria map built from a Record<string, null> yields string.
• EntryType excludes bare numbers and booleans. state: 42 does not type-check; wrap it (state: { value: 42 }) or stringify it.
• Usage uses snake_case while everything else in the SDK is camelCase — it mirrors the HTTP response.

Version notes

• Types described for @typesafe-ai/sdk 0.6.0 (repo commit 66880ccded6cb642dc1809620c2b108c33730214, 2026-09-15).
• ScoreCriteria became a readonly tuple in 0.6.0; in 0.5.7 score criteria were a dictionary keyed by integers. See JavaScript SDK changelog.
• Doc-vs-source: Models is published under "Interfaces" but declared export class Models in src/resources/models.ts (re-exported as export type { Models }, so only the type is public).
• Doc-vs-source (cosmetic): the docs render ChoiceCriteria's index signature as EntryType where source writes Description, and expand the mapped-type keys of ChoiceResponse.probabilities / ScoreResponse.probabilities to string | number | symbol and number | \${number}`` respectively. These are typedoc expansions of the same types.

Related

• JavaScript/TypeScript SDK: install, client, choice/score/noul — client, builders, examples
• JavaScript SDK error classes, RetryPolicy, RequestOptions — RetryPolicy, RequestOptions, error classes
• OpenAPI component schemas — the same shapes on the wire
• HTTP API: POST /v1/systemone and GET /v1/models — POST /v1/systemone, GET /v1/models
• Primitives: Choice, Score, Noul — what Choice, Score and Noul mean
• Python SDK question types (Noul, Choice, Score) — Python counterparts

Sources

• raw/docs/sdk__javascript__api.md (https://docs.typesafe.ai/sdk/javascript/api)
• raw/docs/sdk__javascript__api__interfaces__*.md (https://docs.typesafe.ai/sdk/javascript/api/interfaces/*)
• raw/docs/sdk__javascript__api__type-aliases__*.md (https://docs.typesafe.ai/sdk/javascript/api/type-aliases/*)
• raw/docs/sdk__javascript__api__variables__ENV.md, __LOG_LEVELS.md, __VERSION.md
• raw/github/typesafe-sdk-js/src/types.ts, src/env.ts, src/logging.ts, src/api-promise.ts, src/resources/models.ts (commit 66880ccded6cb642dc1809620c2b108c33730214)