Skip to main content

TypeScript SDK

A TypeScript client for the Alice evaluate API. One client instance serves many applications because appId is passed per request. Built for Node.js sandboxes such as Cognigy extensions and serverless functions.

Status: Generally available · Evaluates: Prompts, Responses · Vendor: Alice

Prompts, responses and images. Session and user ids in the context.

Setup​

npm install @alice-io/wonderfence-ts-sdk

Configuration: ALICE_API_KEY, appId

Example​

import { WonderFenceV2Client, AnalysisContext } from '@alice-io/wonderfence-ts-sdk';

const client = new WonderFenceV2Client({ apiKey: 'your-api-key' });
const appId = '550e8400-e29b-41d4-a716-446655440000'; // UUID from the Application Inventory page

const context: AnalysisContext = { sessionId: 'session-123', userId: 'user-456' };

const promptResult = await client.evaluatePrompt(appId, context, 'Your prompt text');
const responseResult = await client.evaluateResponse(appId, context, 'Response text');

// Release pooled HTTP sockets on shutdown
client.close();

tool calls and tool results

import { Actions, ToolContext } from '@alice-io/wonderfence-ts-sdk';

const tool: ToolContext = { toolName: 'search', toolCallId: 'call_1', mcpServer: 'github' };

const callResult = await client.evaluateToolCall(
appId,
context,
'{"query":"weather in Paris"}',
undefined,
undefined,
tool,
);
if (callResult.action === Actions.BLOCK) {
// don't run the tool
}

const toolOutput = await runSearch({ query: 'weather in Paris' });
const resultEval = await client.evaluateToolResult(
appId,
context,
toolOutput,
undefined,
undefined,
tool,
);
if (resultEval.action === Actions.BLOCK) {
throw new Error('Tool output blocked');
}
// What the agent may read: the masked text on MASK, the output as-is otherwise
const agentSees = resultEval.action === Actions.MASK ? resultEval.actionText ?? '' : toolOutput;

Good to know​

Provide either text or an image per call, not both. Retries use exponential backoff; set maxRetries: 0 in environments that allow one outbound request per execution.

The tool methods (evaluateToolCall and evaluateToolResult) need @alice-io/wonderfence-ts-sdk 3.1.0 or later, and WONDER_FENCE_AGENTIC_MESSAGE_TYPES enabled on your Alice project until tool message types are generally available. Without it the API answers 400, which the SDK throws as an ApiError without retrying. The optional ToolContext (toolName, toolCallId) names the tool and pairs a call with its result. Its mcpServer (3.2.0 or later) names the MCP server the tool belongs to, as your client knows it, and is stored with the call or result so you can audit and filter tool traffic by server. Left out, it is read from a tool named in Claude Code's mcp__<server>__<tool> form. Pass tool arguments as a string (JSON.stringify them). Tool calls and results are matched only against policies that list the Tool Call / Tool Result message types; a policy that lists only Prompt or Response does not screen them. Text is limited to 10,240 characters and an empty string is rejected, both with a 400, so truncate or chunk large tool output before evaluating it.