@typesafe-ai/sdk 0.7.0 failure path checked ; images read at @ai-sdk/typesafe-ai 3.0.24 and 3.0.26 and @typesafe-ai/sdk 0.7.0 ; title ; Workers binding as audited 29 Sep 2026; @typesafe-ai/sdk and @ai-sdk/typesafe-ai versions rechecked (@typesafe-ai/sdk unchanged; @ai-sdk/typesafe-ai 3.0.30 noted, not re-read) and (@typesafe-ai/sdk unchanged; @ai-sdk/typesafe-ai 3.0.31 and ai 7.0.159 noted, not re-read) and (@typesafe-ai/sdk unchanged; @ai-sdk/typesafe-ai 3.0.35 and ai 7.0.165 noted) · @ai-sdk/typesafe-ai 3.0.35 and ai 7.0.165 and 7.0.166 compared with the previous versions (@typesafe-ai/sdk unchanged)Jev TypeScript (TypeSafe AI): @typesafe-ai/sdk vs AI SDK vs fetch, with timeouts and missing-key errors
There are four ways to call Jev from TypeScript: TypeSafe's own SDK, the Vercel AI SDK's experimental_decide (formerly experimental_evaluate), a plain HTTP request, and the Cloudflare Workers binding. They differ in runtime, key variable, field names, default retries and timeouts. This page compares them at pinned versions and lists thirteen TypeScript-specific mistakes.
TypeScript today: @typesafe-ai/sdk is at 0.7.0 (14 Oct 2026; adds experimental image support). It throws at client creation without a key; checked at 0.7.0 (18 Oct 2026), the failure path is unchanged from 0.6.0, except that input errors now reject the returned promise. The AI SDK provider (3.0.26 on 23 Oct 2026) throws LoadAPIKeyError at the first call (read at 3.0.18); ai 7.0.128 renamed experimental_evaluate to experimental_decide. Documented 14 Oct 2026; package versions and 0.7.0 failure path 18 Oct 2026
For TypeSafe direct on Node 22 or later, use the official @typesafe-ai/sdk (0.7.0 since 14 Oct 2026, needs Node 22; 0.6.0 runs on Node 20; defaults and error classes read at 0.6.0 and checked unchanged at 0.7.0 on 18 Oct 2026). If you use Vercel AI Gateway or already use the AI SDK, use AI SDK experimental_decide (ai 7.0.128 or later; the older name experimental_evaluate still works as a deprecated alias at 7.0.140). For other runtimes or routes, use raw fetch and add your own retry and timeout. Documented package sources and docs, checked 29 Sep 2026
Version check, 18 Oct 2026; image path 23 Oct 2026; versions rechecked 9 Nov 2026
Versions rechecked 9 Nov 2026: @typesafe-ai/sdk is still 0.7.0. @ai-sdk/typesafe-ai 3.0.35 (7 Nov 2026), compared with 3.0.34 on 9 Nov 2026: it now rejects empty Choice or Score criteria and empty Score levels before sending, sends primitive JSON state as text, and returns Score legends in provider metadata; the image and error handling lines are not in that diff. ai 7.0.165 (7 Nov) and 7.0.166 (9 Nov 2026): the decide functions are unchanged from 7.0.164 (compared 9 Nov 2026); the changes are telemetry and documentation. The readings on this page stay at the versions named in them; the provider versions between 3.0.26 and 3.0.34 were not compared line by line. Documented npm registry and package tarballs, 9 Nov 2026, 11:10 UTC; R29-S18, R29-S19, R29-S20 Change, 9 Nov 2026: this recheck added; the 8 Nov and 31 Oct rechecks moved into the list of earlier version checks. No reading changed.
Checked at @ai-sdk/typesafe-ai 3.0.24 and 3.0.26 (23 Oct 2026): it still sends the images header automatically for PNG or JPEG image parts, and since 3.0.21 also for Box questions (src/typesafe-ai-decision-model.ts L245–248); other media types and image URLs are rejected before the call (L148–158). @typesafe-ai/sdk 0.7.0: the SDK does not check image format or size; it sends what you give it and the API returns 400 or 413. You add the opt-in header yourself (dist/index.mjs L226–264). Images are experimental and opt-in; TypeSafe says they are not yet ready for production. Documented npm package files read 23 Oct 2026, 05:23–05:29 UTC; the 3.0.26 src/ is identical to 3.0.24. Nothing was installed or run and no image was sent. R22-S106, R22-S116, R22-S108, R22-S100 All SDKs and integrations read: Jev with images: does your SDK or integration send them?
Checked at @typesafe-ai/sdk 0.7.0 (18 Oct 2026): the failure path is the same as 0.6.0: a missing key throws TypeSafeError in the constructor, 10,000 ms per attempt, 2 retries on 408, 429 and 5xx with 500 ms to 5 s back-off, the same error classes, and jev-latest by default. New in 0.7.0: input errors such as empty questions or missing state now reject the returned promise instead of throwing at the call, request bodies of 1 KiB or more are zstd-compressed by default on Node 22.15+ (compression: false turns this off), and the package now needs Node 22. Documented read at the published 0.7.0 and 0.6.0 packages, 18 Oct 2026, 05:18 UTC; 0.7.0 dist/index.mjs: error classes L147, L172–178; retry and back-off L52–65; timeout L909; missing key L754, L903; default model L905; promise rejection L946–961; compression L523–524, L911; package.json L31 (engine >=22, was >=20). Nothing was installed or run. R18-S227, R18-S228, R18-S229
On 18 Oct 2026, 05:17 UTC, jev-latest still pointed to jev-1.13.0 and jev-preview to jev-1.14.0; TypeSafe has said jev-latest moves to 1.14 about a week after 14 Oct, with no date published (R18-S05). Update, 24 Oct 2026: the default model of @typesafe-ai/sdk 0.7.0 is jev-latest (dist/index.mjs L905), which on TypeSafe's API pointed to jev-1.14.0 on 24 Oct 2026, 05:12 UTC (it pointed to jev-1.13.0 until at least 23 Oct 2026, 05:45 UTC). Pin jev-1.13.0 if your thresholds were tuned on 1.13. The SDK versions are unchanged (@typesafe-ai/sdk 0.7.0, @ai-sdk/typesafe-ai 3.0.26 on npm, 24 Oct 2026, 05:18 UTC), so the published file:line pins still apply (R23-S05, R23-S41). Pin jev-1.13.0 or jev-1.14.0 if you need stable answers. Images and Box are experimental and not production-ready per TypeSafe.
AI SDK: @ai-sdk/typesafe-ai 3.0.21 (16 Oct) is a patch release; the page's reading is at 3.0.20. Checked at ai 7.0.143 (18 Oct 2026): patch release; failure path not re-read. Documented npm registry, 18 Oct 2026, 05:23 UTC (R18-S57)
Examples: the @typesafe-ai/sdk example below stays pinned at 0.6.0 (Node 20) and the AI SDK example at ai 7.0.122 and @ai-sdk/typesafe-ai 3.0.10, the versions they were written for. On 0.7.0, wrap the call in try/await so input errors are caught with API errors.
Change, 31 Oct 2026: version recheck added at the top of this box (@typesafe-ai/sdk 0.7.0 unchanged; @ai-sdk/typesafe-ai 3.0.30 → 3.0.31 and ai 7.0.157 → 7.0.159 noted, patches, not re-read) and in the facts below; the 30 Oct recheck moved into the list of earlier version checks (R25-S36).
Change, 30 Oct 2026: version recheck added at the top of this box (@typesafe-ai/sdk 0.7.0 unchanged; @ai-sdk/typesafe-ai 3.0.26 → 3.0.30 and ai 7.0.152 → 7.0.157 noted, patches, not re-read) and in the facts below (R24-S35, R24-S39).
Change, 24 Oct 2026: the alias paragraph adds the 24 Oct check (on TypeSafe's API jev-latest, the SDK default, pointed to jev-1.14.0, first seen 05:12 UTC); SDK versions unchanged; ai 7.0.152 noted in the facts (not re-read) (R23-S05, R23-S41).
Change, 23 Oct 2026: image handling read at @ai-sdk/typesafe-ai 3.0.24 and 3.0.26 (header now also sent for Box questions) and at @typesafe-ai/sdk 0.7.0 (no client-side format or size check); provider version 3.0.21 → 3.0.26 in the short answer and facts. The failure-path readings are unchanged.
Change, 18 Oct 2026: the failure path of @typesafe-ai/sdk 0.7.0 was read and is unchanged from 0.6.0 (this box said "0.7.0's error path not yet re-read"); three smaller changes added (rejected promise for input errors, zstd request compression, Node 22). @ai-sdk/typesafe-ai 3.0.20 → 3.0.21 and ai 7.0.140 → 7.0.143 noted (patches; not re-read).
Earlier version checks (13, newest first)
- Versions rechecked 8 Nov 2026:
@typesafe-ai/sdkis still 0.7.0;@ai-sdk/typesafe-ai3.0.35 andai7.0.165 (7 Nov 2026) are newer than the versions this page describes; not re-read. The readings on this page stay at the versions named in them. Documented npm registry, 8 Nov 2026, 05:25 UTC; R28-S47 Change, 8 Nov 2026: this recheck added; the 31 Oct recheck below is kept as dated. No reading changed. (@ai-sdk/typesafe-ai3.0.35 andai7.0.165 were compared on 9 Nov 2026, see the recheck above.) - Versions rechecked 31 Oct 2026:
@typesafe-ai/sdkis still 0.7.0;@ai-sdk/typesafe-ai3.0.31 was released on 30 Oct 2026 (15:39 UTC; patch); this site last read the provider at 3.0.26 (image path; its failure path at 3.0.18); newer version exists, not re-read.ai7.0.159 was published on 30 Oct 2026 (22:18 UTC, after 7.0.158 at 15:38 UTC; patch; not re-read). The readings on this page stay at the versions named in them, and the examples stay at their pinned versions. The 30 Oct recheck is now in the list of earlier version checks below. Documented npm registry, 31 Oct 2026, 05:14 UTC; R25-S36 - Versions rechecked 30 Oct 2026:
@typesafe-ai/sdkis still 0.7.0;@ai-sdk/typesafe-ai3.0.30 was released on 29 Oct 2026; this site last read the provider at 3.0.26 (image path; its failure path at 3.0.18); 3.0.30 was not re-read. The provider had four patch releases after the 24 Oct check (3.0.27 on 24 Oct to 3.0.30 on 29 Oct, 17:10 UTC);ai7.0.157 was published on 29 Oct 2026 (patch; not re-read). Documented npm registry and the SDK's release feed (latest v0.7.0, 14 Oct), 30 Oct 2026, 05:20–05:21 UTC; R24-S35, R24-S39 - 16 Oct 2026, 05:25 UTC:
@typesafe-ai/sdk0.6.0 → 0.7.0 (npm, 14 Oct 2026, 21:25 UTC) and@ai-sdk/typesafe-ai3.0.18 → 3.0.20. 0.7.0 adds image and Box types; its README says "Image support is experimental", opt in with theTypeSafe-Danger-Zone-Images: trueheader viadefaultHeaders(README L42-47); default model stilljev-latest(dist/index.mjsL905). The error path was then read at 0.6.0 only. Read from the published package; nothing was installed or run. Documented (R17-S38, R17-S05, R17-S09) - 14 Oct 2026: Checked at
@typesafe-ai/sdk0.6.0 (released 15 Sep 2026; still the latest),ai7.0.140 (released 14 Oct 2026, 04:19 UTC) and@ai-sdk/typesafe-ai3.0.18 (released 12 Oct 2026, 17:47 UTC). Defaults:@typesafe-ai/sdk10 s timeout and a missing key throwsTypeSafeErrorwhen the client is created; AI SDKmaxRetries2, no timeout option on the decision call (passabortSignal), and with the TypeSafe provider a missing key throwsLoadAPIKeyErrorat the first call. Read 14 Oct 2026 from the published packages (nothing installed or run). The Cloudflare Workers binding row was not re-read (audited 29 Sep 2026). Documented R16-S207, R16-S208 (@typesafe-ai/sdk); R16-S209, R16-S215, R16-S216 (ai); R16-S210 to R16-S214 (provider); R13-S306, R13-S307, R13-S310 (0.6.0 defaults) Examples: the AI SDK example below was written forai7.0.122 and@ai-sdk/typesafe-ai3.0.10; current versions are 7.0.140 and 3.0.18.experimental_evaluateandevaluationModelstill work at those versions as deprecated aliases ofexperimental_decideanddecisionModel. Change, 14 Oct 2026:ai7.0.122 → 7.0.140 and provider 3.0.10 → 3.0.18 in the facts and comparison table; the AI SDK function is nowexperimental_decide(renamed in 7.0.128); new provider cells (base URL, missing key); new gotcha TS13 (state arrays); new page title.@typesafe-ai/sdkstays at 0.6.0. - 13 Oct 2026, 05:22 UTC:
@ai-sdk/typesafe-ai3.0.18 andai7.0.138 released 12 Oct 2026 (patches); not re-audited.@typesafe-ai/sdkis still 0.6.0. Documented (npm: @ai-sdk/typesafe-ai, npm: ai, R15-S52) - 11 Oct 2026, 05:22 UTC: No newer release of
ai(7.0.137),@ai-sdk/typesafe-ai(3.0.17) or@typesafe-ai/sdk(0.6.0) since 10 Oct.@effect/ai-typesafe4.0.3 was published on 10 Oct 2026 (patch; framework integrations audits 4.0.1); not re-audited. The@typesafe-ai/sdk0.6.0 defaults in the table below were re-read from the published package on 11 Oct: 10,000 ms per attempt,maxRetries2, no total retry budget; a missing key throwsTypeSafeErrorin the constructor. (R13-S35, R13-S306, R13-S307, R13-S310) - 10 Oct 2026, 05:18 UTC: Newer patch releases: ai 7.0.137 and @ai-sdk/typesafe-ai 3.0.17 (8–9 Oct 2026); not re-audited. (
ai7.0.137 published 9 Oct, 14:54 UTC, with 7.0.134–7.0.136 also since 8 Oct;@ai-sdk/typesafe-ai3.0.17 published 8 Oct, 21:40 UTC;@typesafe-ai/sdkstill 0.6.0; R12-S35, R12-S48.) - 8 Oct 2026, 05:14 UTC: Newer patch releases: ai 7.0.133 and @ai-sdk/typesafe-ai 3.0.16, 8 Oct 2026; not re-audited. (
ai7.0.133 published 00:30 UTC, 7.0.131 and 7.0.132 on 7 Oct;@ai-sdk/typesafe-ai3.0.16 published 00:32 UTC; were 7.0.130 and 3.0.15.)@typesafe-ai/sdkis still 0.6.0. Documented (npm: ai, npm: @ai-sdk/typesafe-ai, npm: @typesafe-ai/sdk, R11-S35) - 7 Oct 2026, 05:19 UTC: newer patch releases:
ai7.0.130 and@ai-sdk/typesafe-ai3.0.15, 7 Oct 2026 (01:47 and 01:41 UTC; 7.0.129 and 3.0.14 came out on 6 Oct, 22:23 and 22:20 UTC; were 7.0.128 and 3.0.13); not re-audited.@typesafe-ai/sdkis still 0.6.0. Documented (npm: ai, npm: @ai-sdk/typesafe-ai and npm: @typesafe-ai/sdk, R10-S35) - 6 Oct 2026, 05:15 UTC: newer patch releases:
ai7.0.128 and@ai-sdk/typesafe-ai3.0.13, 5 Oct 2026 (18:25 and 18:26 UTC; were 7.0.127 and 3.0.12); not re-audited.@typesafe-ai/sdkis still 0.6.0. Documented (npm: ai, R9-S36; npm: @ai-sdk/typesafe-ai, R9-S37; npm: @typesafe-ai/sdk, R9-S35) - 2 Oct 2026, 05:14 UTC (updated 8 Oct): Newer releases appeared after this page's audit:
ai7.0.123 to 7.0.126 (30 Sep) and now 7.0.127 (1 Oct, 19:20 UTC), and@ai-sdk/typesafe-ai3.0.11 and 3.0.12 (30 Sep, 02:20 and 17:49 UTC) (npm: ai, npm: @ai-sdk/typesafe-ai, checked 2 Oct 2026, 05:14 UTC). This page's audit usedai7.0.122 and@ai-sdk/typesafe-ai3.0.10. The new releases were not re-audited: the defaults, field names and gotchas below apply to the audited versions.@typesafe-ai/sdkis unchanged at 0.6.0 and@ai-sdk/typesafe-aiat 3.0.12 (checked 2 Oct 2026, 05:14 UTC). Documented - 29 Sep 2026, 07:14–07:16 UTC: page audited at
@typesafe-ai/sdk0.6.0,ai7.0.122 and@ai-sdk/typesafe-ai3.0.10.
- Official SDK
@typesafe-ai/sdk0.7.0, npm 14 Oct 2026, 21:25 UTC; still the latest on 18 Oct 2026 (R18-S227), on 30 Oct 2026, 05:21 UTC (R24-S35, R24-S39) and on 31 Oct 2026, 05:14 UTC (npm; R25-S36). Defaults and error classes on this page read at 0.6.0, npm 15 Sep 2026, 18:17 UTC; tag66880cc; checked unchanged at 0.7.0 on 18 Oct 2026 (R18-S229); 0.7.0 needs Node 22; MIT- Images
- Experimental, not production-ready per TypeSafe.
@typesafe-ai/sdk0.7.0: opt in with theTypeSafe-Danger-Zone-Images: trueheader viadefaultHeaders(README L42-47); it does not check image format or size (dist/index.mjsL226–264; read 23 Oct 2026, R22-S108).@ai-sdk/typesafe-ai3.0.24 and 3.0.26 send it automatically for PNG or JPEG image parts and, since 3.0.21, Box questions; other media types and image URLs are rejected before the call (read 23 Oct 2026; R22-S106, R22-S116) - AI SDK core
ai7.0.143, 16 Oct 2026, 20:10 UTC (checked 18 Oct 2026; patch, not re-read; R18-S57).ai7.0.152 was published on 23 Oct 2026; not re-read (R23-S41).ai7.0.157 was published on 29 Oct 2026, 17:10 UTC; not re-read (R24-S35).ai7.0.159 was published on 30 Oct 2026, 22:18 UTC (patch; newer version exists, not re-read; R25-S36). Last read at 7.0.140; Apache-2.0 (audited at 7.0.122)- AI SDK function name
experimental_decidesince 7.0.128;experimental_evaluateis a deprecated alias, still exported at 7.0.140- First
aiwithexperimental_evaluate - 7.0.103 (16 Sep) by package contents; Vercel's guide says 7.0.105
- AI SDK direct provider
@ai-sdk/typesafe-ai3.0.26, 22 Oct 2026, 21:19 UTC (3.0.25 earlier the same day; R22-S41); 3.0.30 was released on 29 Oct 2026, 17:10 UTC (patch; newer version exists, not re-read; R24-S35); 3.0.31 was released on 30 Oct 2026, 15:39 UTC (patch; newer version exists, not re-read; R25-S36); image path read at 3.0.24 and 3.0.26 on 23 Oct 2026 (header L245–248; R22-S106, R22-S116). At 3.0.20 (npm package files read 16 Oct 2026, 05:25 UTC): model IDs includejev-1.13.0,jev-1.14.0,jev-latest; sends the images header automatically when a request carries PNG or JPEG image parts and the long-context header whenlongContextis set (src/typesafe-ai-decision-model.tsL34-36, L119-216, L229-233; R17-S39). Key and error path read at 3.0.18 (12 Oct 2026, 17:47 UTC); audited at 3.0.10- Provider base URL
https://api.typesafe.ai/v1(envTYPESAFE_AI_BASE_URL; POST<base>/systemone)- Node
- SDK ≥ 20;
aiand@ai-sdk/typesafe-ai≥ 22
Which path fits your project
| If your project… | Use | Because |
|---|---|---|
| Runs on Node 20 or 21 | @typesafe-ai/sdk or raw fetch | ai declares Node ≥ 22 |
| Calls Jev through Vercel AI Gateway | experimental_decide (formerly experimental_evaluate) with 'typesafe-ai/jev' | The gateway string and AI_GATEWAY_API_KEY (or Vercel OIDC) are built in |
| Wants typed helpers and mapped error classes for TypeSafe direct | @typesafe-ai/sdk | choice(), score(), noul() and one error class per status |
| Runs on Cloudflare Workers | env.AI.run('typesafe/jev', …) | No package or TypeSafe key; the account binding authenticates |
| Uses another route, runtime or a gateway without an SDK | Raw fetch | Stable HTTP contract; you write retry, timeout and parsing |
| Must not stop working after a minor upgrade | Pin exact versions | The AI SDK function is experimental and "may change in patch releases" (it was renamed in 7.0.128); the SDK is 0.x |
Comparison at pinned versions
Documented SDK source at tag v0.6.0 (retry.ts, errors.ts, client.ts); AI SDK evaluate reference, evaluation guide and TypeSafe provider page; Cloudflare model page; all checked 29 Sep 2026. AI SDK column rechecked at ai 7.0.140 and @ai-sdk/typesafe-ai 3.0.18 on 14 Oct 2026 from the published packages (R16-S209 to R16-S216); Workers column not re-read.
| Field | @typesafe-ai/sdk (official) | AI SDK experimental_decide | Raw fetch | Cloudflare Workers binding |
|---|---|---|---|---|
| Install | npm install @typesafe-ai/sdk | npm i ai, plus @ai-sdk/typesafe-ai for TypeSafe direct | Nothing | env.AI binding in the wrangler config |
| Runtime | Node ≥ 20; ESM, CJS and types. Refuses to run in a browser unless dangerouslyAllowBrowser: true | Node ≥ 22 | Any runtime with fetch | Cloudflare Workers |
| Routes | TypeSafe direct; baseURL (TYPESAFE_BASE_URL) for compatible endpoints | Gateway string 'typesafe-ai/jev', or typeSafeAi.decisionModel('jev-latest') for TypeSafe direct (evaluationModel still works as an alias at 3.0.18) | Any System One endpoint | Cloudflare typesafe/jev |
| Key variable | TYPESAFE_API_KEY | Gateway: AI_GATEWAY_API_KEY. Direct provider: TYPESAFE_AI_API_KEY; a missing key throws LoadAPIKeyError at the first call, not at provider creation (fail-closed unless the caller catches it) | Your choice | Account binding |
| Answer fields | Choice choice, probabilities, confidence; Score score, legend, probabilities, confidence; Noul noul; usage.input_tokens, usage.output_tokens; model | Choice .choice; Score .score; Noul is called boolean and returns .probability; confidence at providerMetadata.typesafe.confidence[id]; usage.inputTokens; warnings; response.modelId | As the API reference | Not re-read on 29 Sep (the page shows console.log(response) only) |
| Default retries | 2 retries on 408, 429, 5xx (including 529), connection errors and timeouts; backoff 0.5 s doubling to 5 s with up to 25% jitter; honours retry-after-ms and Retry-After up to 60 s | maxRetries 2 in Core for transient failures (e.g. 429, 529), unchanged at 7.0.140; malformed answers are not retried | None | Not documented on the page read |
| Default timeout | 10 s per attempt; no total budget found in the JS source (the Python SDK has a 30 s budget) | None documented; the decide signature has no timeout at 7.0.140; pass abortSignal | None | Not documented on the page read |
| Errors | BadRequestError 400, AuthenticationError 401, PermissionDeniedError 403, NotFoundError 404, UnprocessableEntityError 422, RateLimitError 429, InternalServerError ≥ 500, APIConnectionError, APITimeoutError, APIUserAbortError. A missing key throws at construction | APICallError (provider failures incl. auth and validation), InvalidArgumentError, InvalidResponseDataError (malformed answers), Experimental_DecisionUnsupportedQuestionTypeError (the old Experimental_EvaluationUnsupportedQuestionTypeError is still exported), Experimental_DecisionRefusalError (from 7.0.130), NoSuchModelError; LoadAPIKeyError for a missing provider key | Whatever you map | Workers AI error codes (see errors page) |
| Test facility | fetch option: "Custom HTTP fetch implementation for transport configuration or tests" | Experimental_EvaluationMockModelV4 from ai/test, still exported at 7.0.140; Experimental_DecisionMockModelV4 is also exported | A local mock server | Not documented |
| Stability | 0.x; nine open issues (below) | Experimental: "may change in patch releases" | Stable HTTP contract | Route-owner page |
Two things that differ between sources
- First AI SDK version.
experimental_evaluateis absent from the type declarations ofai7.0.102 and present in 7.0.103 (published 16 Sep 2026, 18:36 UTC). Vercel's guide says "Install AI SDK 7.0.105 or later". This page uses 7.0.105 as the minimum and records the conflict. Documented package contents read, not installed; 29 Sep - Key variable name. The official SDK reads
TYPESAFE_API_KEY. The AI SDK's direct provider readsTYPESAFE_AI_API_KEY. A key set under the wrong name is a "missing key" error, not a Jev error. Documented SDK env.ts; ai-sdk.dev provider page; 29 Sep
Minimal Choice call per path
Each example asks one Choice question about a support message. The code follows each owner's published example and has not been run by the pool, which has no API key. Model IDs differ by route; the current IDs are in the route matrix.
1. @typesafe-ai/sdk 0.6.0 Documented, not executed SDK README and docs JavaScript page
// npm install @typesafe-ai/sdk@0.6.0 (Node >= 20, server side only)
// export TYPESAFE_API_KEY=...
import { TypeSafeClient, choice } from "@typesafe-ai/sdk";
const client = new TypeSafeClient(); // throws at once if the key is missing
const response = await client.systemOne({
state: "I was charged twice for my subscription this month.",
questions: {
category: choice("What is this ticket about?", { billing: null, technical: null, other: null }),
},
});
console.log(response.answers.category.choice, response.answers.category.confidence);
console.log(response.model); // log which versioned model answered
The documented example sets no model, so the SDK default alias jev-latest applies. What jev-latest points to, and which ID to pin on each route: Jev model IDs and aliases by route.
2. AI SDK experimental_evaluate (now experimental_decide) through Vercel AI Gateway Documented, not executed ai-sdk.dev evaluation guide and TypeSafe provider page. Kept at its audited pins (ai 7.0.122, @ai-sdk/typesafe-ai 3.0.10), where the old names apply; they still work at 7.0.140 as deprecated aliases. The full option shape of experimental_decide was not read, so the code is not moved to the new names.
// npm i ai@7.0.122 (Node >= 22; 7.0.105 or later per Vercel)
// export AI_GATEWAY_API_KEY=...
import { experimental_evaluate } from "ai";
const result = await experimental_evaluate({
model: "typesafe-ai/jev",
state: "I was charged twice for my subscription this month.",
questions: {
department: {
type: "choice",
instructions: "Which team should handle this?",
criteria: { billing: "Payments and invoices", technical: "Bugs and integrations", other: null },
},
},
});
console.log(result.answers.department.choice);
console.log(result.providerMetadata?.typesafe?.confidence?.department); // confidence is not on the answer
For TypeSafe direct instead of the gateway, install @ai-sdk/typesafe-ai, set TYPESAFE_AI_API_KEY, and pass model: typeSafeAi.evaluationModel("jev-latest") (base URL https://api.typesafe.ai/v1). At 3.0.18 evaluationModel is an alias of decisionModel, and a missing key throws LoadAPIKeyError at the first call.
3. Raw fetch Documented, not executed request shape from the docs quickstart; the timeout line is the pool's addition
const res = await fetch("https://api.typesafe.ai/v1/systemone", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
model: "jev-1.13.0",
state: "I was charged twice for my subscription this month.",
questions: {
category: { type: "choice", instructions: "What is this ticket about?",
criteria: { billing: null, technical: null, other: null } },
},
}),
signal: AbortSignal.timeout(10_000), // raw fetch has no timeout unless you set one
});
if (!res.ok) throw new Error(`Jev ${res.status}: ${await res.text()}`);
const body = await res.json();
console.log(body.answers.category.choice, body.answers.category.confidence);
A retry loop for this path, tested offline against a local mock server, is the worked example on Testing without a key.
4. Cloudflare Workers binding Documented, not executed Cloudflare model page for typesafe/jev
export default {
async fetch(request, env) {
const response = await env.AI.run("typesafe/jev", {
state: "I was charged twice for my subscription this month.",
questions: {
department: { type: "choice", instructions: "Which team should handle this?",
criteria: { billing: null, technical: null, other: null } },
},
});
return Response.json(response);
},
};
How long a call can take with default settings
With the official SDK's defaults and an endpoint that never answers, one call makes 3 attempts of 10 s each, with 0.5 s and 1 s waits between them. That adds up to about 31.5 s. The Claude Code plugins audited on Claude Code and MCP give a hook 10–15 s. Set a per-call timeout shorter than your caller's deadline.
One call to a hanging endpoint, 0–31.5 s
SDK defaults: 3 × 10 s attempts, 0.5 s and 1 s backoff (derived arithmetic)
Red line: a 15 s hook deadline. The caller gives up during the second attempt, while the SDK is still retrying.
Same retry pattern at 800 ms per attempt, Tested offline 3.9 s
The pool's offline test (T04) measured 3,908 ms for this case against a local mock server.
TypeScript gotchas
Status codes and their meanings are on Errors and rate limits. This table lists only problems specific to the TypeScript paths.
| # | Gotcha | What to do | Source and label |
|---|---|---|---|
| TS1 | Question type must be lowercase (choice, score, noul); capitalised types return 400 | Use the SDK helpers choice(), score(), noul() | oh-my-claudecode #4091 Reported |
| TS2 | state: null returns 422, and the JS SDK does not stop it locally | Validate state before calling | typesafe-sdk-js #6 Reported |
| TS3 | The model ID differs by route: jev-1.13.0 or jev-latest direct; typesafe-ai/jev on Vercel; typesafe/jev-1.13 on OpenRouter; typesafe/jev on Cloudflare | Keep the ID in configuration per route; check the model IDs and aliases by route | Route pages Documented 29 Sep |
| TS4 | Three key variables: TYPESAFE_API_KEY (official SDK), TYPESAFE_AI_API_KEY (AI SDK direct provider), AI_GATEWAY_API_KEY (gateway) | Set the one your path reads. The official SDK throws at construction if it is missing; the AI SDK direct provider throws LoadAPIKeyError at the first call (3.0.18, read 14 Oct 2026) | SDK env.ts L1–11; ai-sdk.dev; provider dist/index.js L156–163 (R16-S211, R16-S214) Documented |
| TS5 | The AI SDK calls a Noul boolean and returns .probability, not .noul; confidence sits in providerMetadata.typesafe.confidence | Do not port field names between paths | ai-sdk.dev Documented |
| TS6 | Double retries: the SDK and the AI SDK each retry twice by default; a wrapper that retries on top multiplies calls and cost | Set maxRetries: 0 (AI SDK) or retry: { maxRetries: 0 } in the lower layer when you retry yourself | retry.ts; ai-sdk.dev Documented |
| TS7 | Worst case with SDK defaults and a hanging endpoint is about 31.5 s (see the figure) | Pass a per-call timeout or abortSignal shorter than your caller's deadline | Derived from retry.ts; T04 shows the pattern at 800 ms |
| TS8 | Vercel's free tier returns 429 rate_limit_exceeded | Handle it separately from TypeSafe's own 429 | Vercel rate-limit docs Documented (28 Sep) |
| TS9 | The SDK throws in a browser unless dangerouslyAllowBrowser: true, and that setting would expose the key | Call Jev from a server route | client.ts L60–65, L268 Documented |
| TS10 | Cancelling a call can terminate Node 20 and 22 (open issue #2); jkudish/jev-mcp routes around it | Avoid aborting in-flight SDK calls on those Node versions, or use raw fetch | typesafe-sdk-js #2; jkudish README L757 Reported |
| TS11 | The AI SDK function "may change in patch releases": ai 7.0.128 renamed experimental_evaluate to experimental_decide. The old name is a deprecated alias at 7.0.140; per the 7.0.129 changelog it warns on use (the warning was not read in code) | Pin the exact ai version; move to experimental_decide when you upgrade | ai-sdk.dev; ai 7.0.140 changelog and dist/index.js L13126–13127 (R16-S215) Documented |
| TS12 | Probabilities are rounded to 2 decimals and may not sum to 1 | Do not assert exact sums in tests | ai-sdk.dev provider page Documented |
| TS13 | From @ai-sdk/typesafe-ai 3.0.16 (and ai 7.0.133): "Arrays passed directly as state now contain decision state parts." | "Wrap JSON arrays in an object or a json part." | Provider 3.0.18 changelog (R16-S211), read 14 Oct 2026 Documented |
Open issues in the official JS SDK
Open on GitHub on 29 Sep 2026. Each is the reporter's description, not rerun by the pool. Reported
- #2: a handled cancellation can crash Node 20 and 22.
- #6:
noul()with no arguments, andstate: null, build requests the API rejects. - #8: timeouts above Node's timer maximum fire after about 1 ms.
- #9: a blank
Retry-Afterheader bypasses backoff. - #12:
score()accepts a null level, which returns 422. - #13: 402 and 413 fall through to a generic
APIError. - #14: the API key can be echoed into
APIConnectionError, and an empty key is sent. - #15: Cloudflare HTML 403 when the state contains
curltext. - #17: non-finite numbers serialise as null.
Issue list: typesafe-ai/typesafe-sdk-js issues.
Projects that use these paths
| Project | What its code does | Label and date |
|---|---|---|
Jevmail classify.ts | Calls experimental_evaluate({ model: 'typesafe-ai/jev', …, maxRetries: 0 }), then runs its own 429 wait-and-retry-once and 5xx retry-once. This avoids stacking the AI SDK's 2 retries under its own (TS6). | Documented 28 Sep audit, not re-audited |
Vercel template jev-ai-sdk-form-router | CONFIDENCE_THRESHOLD = 0.95. The Jev call uses AbortSignal.timeout(12_000) and maxRetries: 1. If confidence is below 0.95 or missing, or Jev fails, it calls a fallback LLM (25 s, 1 retry). A missing confidence counts as a fallback, not a pass. package.json pins ai 7.0.107. The fallback model is openai/gpt-6-luna-fast in source but openai/gpt-5.6-luna-fast on the template page. | Documented at 27ea469 (22 Sep), checked 29 Sep |
MSFT-TKENDRICK/JEV-examples | The author states the examples were never executed live. Not opened by the pool. | Reported |
Seen only: TanStack AI decide() with vercelGatewayDecider('typesafe-ai/jev') or cloudflareDecider('typesafe/jev'), described by Vercel. TanStack AI's direct package, @tanstack/ai-typesafe 1.0.0, was read at commit 5651e07 on 31 Oct 2026: it raises Jev errors to your code; see framework integrations. LangChain JS (@langchain/typesafe 0.0.2) and @effect/ai-typesafe 4.0.1 were read on 5 Oct 2026: see framework integrations. For TypeScript demo videos, see the TypeScript group on the videos page.
What was not verified
- No example on this page was run. The official JS SDK was not installed, and the AI SDK was read from its published type declarations and docs.
- The AI SDK's default timeout is undocumented. The changes in
@ai-sdk/typesafe-ai3.0.9 and 3.0.10 (both 28 Sep) were not compared. - The Cloudflare binding's response shape, retries and timeout were not re-read on 29 Sep.
- The 31.5 s worst case is arithmetic from SDK defaults, not a measurement.
- On 16 Oct 2026
@typesafe-ai/sdk0.7.0 (README, default model) and@ai-sdk/typesafe-ai3.0.20 (model IDs, opt-in headers) were read as files; nothing was installed or run. No image, Box or long-context request was sent. On 18 Oct 2026 the published 0.7.0 and 0.6.0 packages were compared file by file (dist/index.mjs,package.json, README; the.cjsbuild at its constants only); nothing was installed or run. - On 23 Oct 2026
@ai-sdk/typesafe-ai3.0.24 and 3.0.26 and@typesafe-ai/sdk0.7.0 were read as package files for their image path only; nothing was installed or run and no image was sent. The failure path of the AI SDK provider was not re-read. - On 14 Oct 2026 the packages were read as files; nothing was installed or run. Not read: the full option shape of
experimental_decide, the deprecation warning text, and the Cloudflare Workers binding (audited 29 Sep 2026).