TypeScript SDK
Install the @foilengine/sdk package for Node.js, web, Deno, or Bun projects.
Installation
npm install @foilengine/sdkQuick Start
import { FoilEngineClient } from '@foilengine/sdk';
const client = new FoilEngineClient({ apiKey: 'pk_live_...' });
// Discover your personas
const personas = await client.personas.list();
console.log(personas[0].name); // "Grumpy Barista"
// Initialize a session
const session = await client.chat.initSession(personas[0].id, {
userSessionId: 'player-001',
playerName: 'Alex',
playerGender: 'non-binary',
});
console.log(session.message); // NPC's greeting
// Send a message
const response = await client.chat.sendMessage(personas[0].id, {
message: 'What do you recommend?',
userSessionId: 'player-001',
});
console.log(response.message); // NPC's reply
console.log(response.current_state); // State machine state
console.log(response.score); // Session scoreConfiguration
const client = new FoilEngineClient({
apiKey: 'pk_live_...', // required
baseUrl: 'http://localhost:8000', // default: https://api.foilengine.io
timeout: 30000, // default: 30000ms
maxRetries: 3, // default: 3
});Available Methods
Personas
| Method | Returns | Description |
|---|---|---|
client.personas.list() | Promise<Persona[]> | List all published personas |
Machines
| Method | Returns | Description |
|---|---|---|
client.machines.list(personaId, userSessionId) | Promise<MachineInfo[]> | List available machines for a player |
Chat
| Method | Returns | Description |
|---|---|---|
client.chat.initSession(personaId, options) | Promise<SessionInit> | Start a new conversation |
client.chat.sendMessage(personaId, options) | Promise<ChatResponse> | Send a message, get NPC reply |
client.chat.getSession(personaId, userSessionId) | Promise<SessionStatus> | Check if a session exists |
client.chat.getHistory(personaId, userSessionId) | Promise<ChatHistory> | Get full message history |
client.chat.reset(personaId, userSessionId) | Promise<ResetResult> | Delete a session |
Error Handling
import {
FoilEngineClient,
NotFoundError,
AuthenticationError,
RateLimitError,
} from '@foilengine/sdk';
const client = new FoilEngineClient({ apiKey: 'pk_live_...' });
try {
const session = await client.chat.getSession(personaId, 'player-001');
} catch (e) {
if (e instanceof NotFoundError) {
// No existing session — initialize one
const session = await client.chat.initSession(personaId, { ... });
} else if (e instanceof RateLimitError) {
console.log(`Retry after ${e.retryAfter}s`);
} else if (e instanceof AuthenticationError) {
console.error('Invalid API key');
}
}| Error Class | Status | When |
|---|---|---|
BadRequestError | 400 | Invalid UUID, missing fields |
AuthenticationError | 401 | Missing or invalid API key |
ForbiddenError | 403 | Not owner or persona unpublished |
NotFoundError | 404 | Resource not found |
RateLimitError | 429 | Rate limit exceeded |
ServerError | 500 | Internal server error |
💡Tip
The SDK automatically retries on 429 and 5xx errors with exponential backoff (up to 3 retries). Uses native fetch with zero dependencies.
TypeScript Types
All request and response types are fully typed and exported:
import type {
Persona,
MachineInfo,
SessionInit,
ChatResponse,
ChatHistory,
SessionStatus,
UnlockedMachine,
InitSessionOptions,
SendMessageOptions,
} from '@foilengine/sdk';