Advocaat

What it does

Advocaat, from Pooya Parsa (known for the UnJS and Nitro projects), is a small TypeScript client for Jev built around tagged templates. Questions read almost like the code that uses them:

import { ask } from "advocaat";

const { kind, security, severity } = await ask(issue, {
  kind: ask.choice`What kind of issue is this?`({ bug: "Something is broken", other: null }),
  security: ask.if`Does this issue describe a security vulnerability?`,
  severity: ask.score`How severe is this issue?`(["Cosmetic", "Workaround exists", "Blocks production"]),
});

ask.if returns a boolean, ask.switch returns just the chosen label, ask.chance returns the probability, and ask.score adds a ratio from 0 to 1. Answers are typed from your questions, so kind.choice is "bug" | "other". Objects you interpolate into a question are moved into the request’s state and referred to by path. It also works with Vercel AI Gateway, where it calculates confidence locally because the gateway doesn’t return it.

A bundled agent skill teaches coding agents to design questions and use the library.

Setup

npx nypm i advocaat
export TYPESAFE_API_KEY="your-api-key"

It has no runtime dependencies. Options (key, base URL, model, custom fetch, abort signal, headers) can be passed per call, and a bare ask reads the key from the environment.

Using it

We installed 0.0.6 from npm in a fresh project and ran the README’s examples against the real API, recording every request with a custom fetch.

• The quick start works as written. Three question types came back in one request, with a label, a boolean, and a ratio between 0 and 1.
• The README’s request example is exact. For the duplicate-check example with two interpolated objects, the body we captured matched the README’s “How data is sent” JSON word for word.
• The shorthands behave. ask.switch returned a bare label, and a plain question object with Noul criteria returned a chance.
• Errors are clear and not retried. An invalid key raised an APIError with TypeSafe’s 401 message after a single attempt, as the README says.
• The repository’s checks pass. Lint, type checking, and all 26 tests passed at the latest commit, with coverage around 96%. A tree-shaking improvement on main isn’t in a release yet.

We didn’t test the Vercel AI Gateway path, including its locally computed confidence.

Permissions and data

• It sends only what you give it. The state you pass and your questions go to TypeSafe, or to Vercel AI Gateway if you choose it. There’s nothing else: no telemetry and no other network calls.
• Keep untrusted text in the state. The README suggests putting short text straight into a question, as in ask.if`Is "${message}" spam?` . That puts the text in the instructions, not the state. We confirmed it: the request’s state was empty and the whole message, including an “ignore previous instructions” line we planted, was part of the question. For user-supplied or scraped text, wrap it as ${{ message }} so it goes into the state and stays data rather than becoming part of the question.
• Key selection is automatic. Without an explicit key, it uses TYPESAFE_API_KEY, then AI_GATEWAY_API_KEY, then VERCEL_OIDC_TOKEN. On Vercel deployments without a TypeSafe key, requests go through the gateway.

Maintenance

Twenty-nine commits and releases up to 0.0.6 between September 16 and 18, with CI, automated formatting, dependency updates, and a changelog. It’s MIT licensed, with no open issues. The version number is honest: this is an early API.

Verdict

Advocaat makes calling Jev from TypeScript unusually pleasant. Questions read like conditions, answers come back typed, and the library is small enough to read in one sitting. Everything we tried matched its documentation. Keep untrusted text in the state rather than the question, add your own retries, and expect changes before 1.0. For TypeSafe’s official client, see the JavaScript SDK.

See how it compares with other tools in Best Jev tools, tested hands-on.

Review updated Sep 19, 2026. Numbers quoted from the project are its author's own; we don't publish our own measurements of Jev.