JavaScript / TypeScript SDK

Installation

Requires Node.js 20 or newer:

npm install @typesafe-ai/sdk

Set the environment variable, then create a client:

export TYPESAFE_API_KEY="sk-..."

Basic usage

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

const client = new TypeSafeClient();
const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice);

Type inference

This is the most valuable part of the TS SDK: answer types are inferred from the questions you pass.

questions: {
  category: choice("What is this ticket about?", {
    billing: null,
    technical: null,
    other: null,
  }),
}

Because the criteria keys are billing / technical / other, the type of response.answers.category.choice is the union of those three literals. A typo like "bililng" is a compile error rather than a runtime undefined.

Likewise, a question built with score(...) yields an answer carrying score, legend, probabilities, and confidence; one built with noul(...) carries only noul.

The upshot: you never hand-write answer types, and you never treat the API response as any.

Response shape

response.answers.category.choice;        // the selected option
response.answers.category.probabilities; // per-option probabilities
response.answers.category.confidence;    // confidence

All question types are indexed by question name under response.answers; the fields available depend on the question’s type.

Package layout

The SDK ships ESM, CommonJS, and TypeScript declaration files, so it works directly across build setups.

For every option and default, see the SDK’s client and types.

Related

• Quick start
• Primitives — how the three question types are constructed
• Speculative fan-out — asking several questions at once