Official TypeScript / JavaScript SDK Guide

What It Solves & Overview

The official JavaScript/TypeScript client library (@typesafe-ai/sdk) provides strongly-typed interfaces for interacting with TypeSafe AI System One decision models. It exposes mathematical evaluation primitives including Choice, Score, and Noul without requiring prompt engineering or JSON string scraping.

Suitability & Fit

When to Use

Building Node.js backend microservices, Next.js API routes, or edge workers that require fast decision classification.
Integrating deterministic intent routing or feature flagging directly into existing TypeScript codebases.
Enforcing end-to-end compile-time type safety across candidate decision enums.

When NOT to Use

Generating open-ended prose, multi-paragraph essays, or creative chat conversational responses.
Working in pure Python environments (use typesafe-sdk on PyPI instead).

Installation & Setup

npm install @typesafe-ai/sdk
# Optional dependency for offline schema validation example:
npm install zod

Offline Contract Verification Example

Verification Notice: The code snippet below demonstrates local structural validation of inputs and choice schemas without requiring live network credentials. Real-world API execution requires active connectivity and API credentials.

import { z } from 'zod';

// Local contract verification stub (illustrative schema without network)
const IntentSchema = z.enum(['billing_inquiry', 'tech_support', 'account_closure']);
type IntentChoice = z.infer<typeof IntentSchema>;

interface RoutingState {
  userId: string;
  message: string;
}

function verifyLocalContract(state: RoutingState, candidates: readonly string[]) {
  if (!state.userId) throw new Error('Missing userId');
  return { valid: true, primitive: 'Choice', candidates };
}

console.log('TS SDK contract verified offline:', verifyLocalContract({ userId: 'u1', message: 'help' }, IntentSchema.options));

Prerequisites & Operational Boundaries

Prerequisites

Node.js 18.0.0 or higher.
A valid TYPESAFE_API_KEY from console.typesafe.ai (required for live cloud API execution).

Known Limitations

Requires active network connection to TypeSafe AI API endpoints for live scoring.
Does not perform offline model inference; local execution is restricted to type validation.

Official Source Provenance

This guide is compiled and fact-checked against official upstream assets: