TypeScript SDK

The TypeScript SDK is a thin client over the check endpoint. Wrap the OpenAI client you already have and both sides of every turn are checked automatically, or call the guard yourself for anything that does not go through OpenAI.

• Wrap once, check twice. Every chat.completions.create and responses.create call is checked before the provider sees the prompt and again before the reply reaches your user
• One trace id per turn. The input check and the output check share it, so the dashboard shows a turn as one trace
• Rewrite or stop. A redacted input is rewritten before the request leaves your process; a blocked turn raises GuardBlockedError and never reaches the provider
• Fail the way you choose. The SDK fails open by default; one option makes an unreachable API block instead

Install

The package has zero runtime dependencies and ships its own types. It is ESM-only and needs Node 18 or later, which has the global fetch it relies on. openai is not a dependency: install it yourself and give the wrapper the client you already construct.

npm install @verexa/sdk

Create a key in the dashboard under Settings → API keys and set it in the environment:

1export VEREXA_API_KEY="vx_live_..."2export VEREXA_BASE_URL="https://api.verexa.dev"

VEREXA_BASE_URL is optional. Without it the SDK talks to https://api.verexa.dev. Set it to point at a local or self-hosted verdict-api.

Configure the guard

createGuard() reads the environment and returns a guard you can reuse. Options passed here win over the environment:

1import { createGuard } from "@verexa/sdk";23const guard = createGuard({4  apiKey: process.env.VEREXA_API_KEY,5  baseUrl: "https://api.verexa.dev",6  failMode: "closed",7  timeoutMs: 2000,8});

Create one guard per process and reuse it. A guard owns its circuit breaker and telemetry buffer, so a guard created per request resets both.

Wrap the OpenAI client

The wrapper installs itself into the client you pass. chat.completions.create is always wrapped, and responses.create is wrapped when the client has it, so existing call sites do not change.

1import OpenAI from "openai";2import { createGuard } from "@verexa/sdk";34const guard = createGuard();5const openai = guard.wrapOpenAI(new OpenAI());67const completion = await openai.chat.completions.create({8  model: "gpt-4o",9  messages: [{ role: "user", content: "my email is jane.doe@example.com" }],10});11console.log(completion.choices[0].message.content);

• The newest user message is checked on input. Only plain-string content is checked; array content, such as multimodal parts, is skipped. With responses.create, the check runs on the string input, or on the flattened text of a structured one
• Every choice is checked on output. Not just choices[0]; one blocked choice fails the whole call
• Redaction rewrites in place. A redacted chat message is replaced before the request is sent, and redacted choice content is replaced before the caller sees it. Structured responses.create input that needs redaction raises instead, because the flattened text cannot be reassembled
• The system prompt is forwarded (the first role: "system" message, or instructions) so output.system_prompt_leak can compare it against the reply

guard.wrapOpenAI(client) and guard.middleware() reuse the guard's client, so one circuit breaker and one telemetry buffer cover everything. The standalone wrapOpenAI(client) builds its own client from the environment.

Check text manually

When a call does not go through OpenAI, or you want the verdict in your own control flow, call the guard directly. checkInput and checkOutput take (text, options) and resolve to a verdict; they never throw, even when no answer arrives. Branch on action yourself, and use text when the action is redact.

1import { createGuard, randomTraceId } from "@verexa/sdk";23const guard = createGuard();4const traceId = randomTraceId();56const input = await guard.checkInput(userMessage, { traceId, profile: "balanced" });7if (input.action === "block") return;8const prompt = input.action === "redact" ? input.text : userMessage;910const reply = await callYourModel(prompt);1112const output = await guard.checkOutput(reply, { traceId, systemPrompt: SYSTEM_PROMPT });13if (output.action === "block") return;14send(output.action === "redact" ? output.text : reply);

Both calls accept the same options: traceId to group the turn, systemPrompt for leak detection on the reply, profile to pick the detection plan, and timeoutMs to override the client default for one call.

Stream a reply

A streamed call is checked on input before the provider is called. The output check runs once the stream ends, after every chunk has already reached you.

1import { GuardBlockedError } from "@verexa/sdk";23try {4  const stream = await openai.chat.completions.create({5    model: "gpt-4o",6    messages,7    stream: true,8  });910  for await (const chunk of stream) {11    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");12  }13} catch (err) {14  if (!(err instanceof GuardBlockedError)) throw err;15  if (err.phase === "output") retractReply(); // every chunk is already with the user16  reply("Sorry, I can't help with that.");17}

The wrapper returns an async generator rather than the provider's Stream, so consume it with for await; Stream helpers are not available on the result. Tokens pass through exactly as they arrive.

Use with the Vercel AI SDK

The @verexa/sdk/ai entry point exports a middleware for the AI SDK. It checks and redacts the prompt in transformParams, then checks the generated text, for both generateText and streamText.

1import { wrapLanguageModel } from "ai";2import { openai } from "@ai-sdk/openai";3import { guardMiddleware } from "@verexa/sdk/ai";45const model = wrapLanguageModel({6  model: openai("gpt-4o"),7  middleware: guardMiddleware(),8});

guard.middleware() reuses a configured guard's client; the standalone guardMiddleware() builds one from the environment. Streamed text is checked at the end, the same retraction signal as the OpenAI wrapper.

Read a verdict

Every check returns the same verdict shape. The action is the decision to honor:

• allow - nothing fired, the text passes through
• flag - the turn continues and the check is recorded for review
• redact - continue with the verdict's text, not the text you sent
• block - stop the turn

The same object is what checkInput and checkOutput resolve to, and what a wrapped call inspects before it rewrites or raises. Core concepts covers the actions and their fields.

Failures and telemetry

A direct check never rejects. A 500, a timeout, a DNS failure or an unparseable response resolves to a fallback verdict: degraded: true, planHash: "unavailable", and an action set by the fail mode. Only the wrappers throw, and only on a block.

1import { GuardBlockedError } from "@verexa/sdk";23try {4  const completion = await openai.chat.completions.create({ model: "gpt-4o", messages });5  send(completion.choices[0].message.content);6} catch (err) {7  if (!(err instanceof GuardBlockedError)) throw err;8  log.warn(`blocked on ${err.phase}: ${err.message}`);9  if (err.phase === "output") retractReply();10  reply("Sorry, I can't help with that.");11}

GuardBlockedError carries phase and the full response verdict. When you fail closed, an outage produces the same error as a policy block, so read response.degraded to tell them apart.

The default fail mode is open. After 5 failed checks in a row, a circuit breaker returns the fallback immediately for 30 seconds before trying again; a 4xx does not count toward it, because the service answered and the key or request is wrong. For audit traffic, raise the timeout: the tier-3 judge has an 8-second server-side budget and the default 2-second client timeout would abort the check before its verdict arrives.

Wrapped calls generate a trace id per turn and do not return it. The guard's telemetry buffer holds the most recent 500 check, error and circuit-open events, each with its trace id, so it is where to find one:

1const events = guard.telemetry.flush();23for (const event of events) {4  console.log(event.traceId, event.phase, event.action, event.degraded);5}

Handle failures covers what each failure shape means and how to respond to it.

Next steps

• Quickstart: from an API key to a guarded call
• Core concepts: actions, profiles, traces and failure modes
• Handle failures: blocked turns, degraded checks and outages
• API reference: the endpoint behind every check
• The Python and Go SDKs