@devjonaed/typesafe-ai 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `ask(state, questions)` — answers named questions in one call and returns them unwrapped: a
+  probability for a Noul, the selected label for a Choice, the expected score for a Score.
+- Shorthand specs: a string is a yes/no question, an array of labels is a choice. `choice()`,
+  `score()` and `noul()` are re-exported for questions that need descriptions.
+- `$` carries the full SDK result — answers, probabilities, confidence, usage, model and request ID.
+- `configure()` and `client()` for the client, which is otherwise built from `TYPESAFE_API_KEY` on
+  first use.
+- Bad input fails before the request: non-object question maps, unusable question values, choices
+  with fewer than two distinct string labels, a blank model override, a blank API key, and `$` as a
+  question name.
+- Bad responses fail loudly: a missing answer, or an answer whose type does not match the question
+  asked, throws instead of yielding `undefined` or a plausible-looking wrong value.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Md Jonaed Hasan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,353 @@
+# @devjonaed/typesafe-ai
+
+[![CI](https://github.com/jonaed1230/typesafe-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/jonaed1230/typesafe-ai/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@devjonaed/typesafe-ai)](https://www.npmjs.com/package/@devjonaed/typesafe-ai)
+
+> **Unofficial.** A community wrapper around TypeSafe AI's official SDK, not built or endorsed by
+> TypeSafe. Bugs here belong in
+> [this repo's issues](https://github.com/jonaed1230/typesafe-ai/issues), not TypeSafe's. For the
+> official client, use [`@typesafe-ai/sdk`](https://www.npmjs.com/package/@typesafe-ai/sdk) directly.
+
+A thin wrapper around [`@typesafe-ai/sdk`](https://www.npmjs.com/package/@typesafe-ai/sdk). Ask typed
+questions about some state, get the answers back already unwrapped.
+
+```ts
+// the SDK
+const client = new TypeSafeClient();
+const r = await client.systemOne({
+  state,
+  questions: {
+    category: choice("...", { billing: null, technical: null, other: null }),
+    urgent: noul("Is the customer angry?"),
+  },
+});
+r.answers.category.choice;
+r.answers.urgent.noul;
+
+// this package
+const a = await ask(state, {
+  category: ["billing", "technical", "other"],
+  urgent: "Is the customer angry?",
+});
+a.category;
+a.urgent;
+```
+
+No client to construct, shorthand for the common questions, and answers that are values rather than
+envelopes. Everything the SDK returns is still on `a.$`, and `client()` hands you the SDK itself.
+
+```sh
+npm install @devjonaed/typesafe-ai
+```
+
+Set `TYPESAFE_API_KEY` in your environment. That is the whole setup — there is no client to construct.
+
+```ts
+import { ask } from "@devjonaed/typesafe-ai";
+
+const a = await ask("I was charged twice. Please fix this ASAP.", {
+  category: ["billing", "technical", "other"],
+  urgent: "Is the customer angry?",
+});
+
+a.category; // "billing"  — typed as "billing" | "technical" | "other"
+a.urgent; // 0.81       — probability from 0 to 1
+```
+
+## Writing questions
+
+| You write | You get | Underneath |
+| --- | --- | --- |
+| `"Is the customer angry?"` | a probability from 0 to 1 | a Noul question |
+| `["billing", "technical"]` | the selected label, as a narrow union | a Choice question |
+| `choice(instructions, criteria)` | the selected label | a Choice question with descriptions |
+| `score(instructions, criteria)` | the expected score | a Score question |
+| `noul(instructions, criteria)` | a probability from 0 to 1 | a Noul question with descriptions |
+
+All three helpers take optional descriptions, including `noul`:
+
+```ts
+noul("Is the customer angry?", { true: "Furious or threatening to leave.", false: "Calm." });
+```
+
+`choice`, `score` and `noul` are re-exported from the SDK, so one import covers everything:
+
+```ts
+import { ask, choice, score } from "@devjonaed/typesafe-ai";
+
+const a = await ask(ticket, {
+  team: choice("Who should handle this?", {
+    billing: "Charges, refunds, invoices.",
+    platform: "Outages, errors, latency.",
+  }),
+  severity: score("How badly is the customer blocked?", [
+    "Not blocked.",
+    "Inconvenienced.",
+    "Cannot work.",
+  ]),
+});
+
+a.team; // "billing" | "platform"
+a.severity; // 0.83 — the expected score, from 0 to 2 here
+```
+
+Every question is answered in one API call, in parallel, and extra questions do not slow the call
+down. That makes it cheap to ask everything a branch might need up front and let your code decide
+what matters:
+
+```ts
+const a = await ask(ticket, {
+  category: ["billing", "technical", "other"],
+  refundRequested: "Is the customer asking for money back?",
+  angry: "Is the customer angry?",
+  mentionsLegal: "Does the customer mention lawyers or legal action?",
+});
+
+if (a.mentionsLegal > 0.8) return escalate(ticket);
+if (a.category === "billing" && a.refundRequested > 0.6) return refundQueue(ticket);
+```
+
+Keep each question narrow. One question per decision beats one question that tries to decide
+everything — see [Patterns](https://docs.typesafe.ai/patterns) for the shapes that work.
+
+An array is the shortest form, but it sends no instructions — the labels alone have to carry the
+question. Reach for `choice()` as soon as a label needs explaining. It needs at least two distinct
+labels; anything less is rejected before the request goes out.
+
+A score is answered on `0` to `levels - 1`, and the answer may fall between levels. The rubric comes
+back on `$`, so you never have to keep the level list in sync by hand:
+
+```ts
+a.severity; // 0.83
+a.$.answers.severity.legend; // { 0: "Not blocked.", 1: "Inconvenienced.", 2: "Cannot work." }
+a.$.answers.severity.probabilities; // { 0: 0.17, 1: 0.82, 2: 0.01 }
+a.$.answers.severity.confidence; // 0.73
+```
+
+### Structured instructions
+
+Instructions and criteria are not limited to strings — any JSON object or array works, which keeps a
+long rubric readable:
+
+```ts
+const a = await ask(ticket, {
+  team: choice(
+    { question: "Who handles this?", rules: ["route by topic", "prefer specialists"] },
+    { billing: { owns: ["charges", "refunds"] }, platform: { owns: ["outages"] }, other: null },
+  ),
+});
+```
+
+`null` as a description leaves that label undescribed, which is exactly what the array shorthand
+sends for every label.
+
+## Confidence, probabilities and usage
+
+Unwrapped answers cover the common case. The full SDK result is always on `$`, typed per question:
+
+```ts
+a.$.answers.category.confidence; // 1
+a.$.answers.category.probabilities; // { billing: 1, technical: 0, other: 0 }
+a.$.usage; // { input_tokens: 415, output_tokens: 96 }
+a.$.requestId; // "req_01a0ca7f5a747639aaac05b46c7dc7db"
+a.$.model; // "jev-1.13.0"
+```
+
+Gate on confidence when a wrong answer is expensive:
+
+```ts
+const { category, $ } = await ask(ticket, { category: ["billing", "technical", "other"] });
+if ($.answers.category.confidence < 0.7) return escalateToHuman(ticket);
+```
+
+**A Noul answer has no confidence and no probabilities.** Its probability *is* the answer, so the
+full shape is just `{ type: "noul", noul: 0.91 }`. Only Choice and Score report confidence — for a
+yes/no question, read how far `a.urgent` sits from `0.5`.
+
+Because `$` is reserved, `ask` throws a `TypeSafeError` if you name a question `$`.
+
+## State
+
+State can be text, or any JSON object or array:
+
+```ts
+await ask(
+  { ticket: { body, customer: { plan: "enterprise", tenureMonths: 14 } } },
+  { churnRisk: "Is this customer likely to cancel?" },
+);
+```
+
+State is required. The SDK's types also accept `null`, but the API rejects it with
+`UnprocessableEntityError: 422 state: Field required`, so pass something.
+
+## Options
+
+Per-call options are the SDK's, plus `model`:
+
+```ts
+await ask(state, questions, {
+  model: "jev-preview",
+  timeout: 5000,
+  signal: controller.signal,
+  retry: { maxRetries: 4 },
+  headers: { "x-request-source": "support-inbox" },
+});
+```
+
+The client is created from the environment on first use. To configure it yourself, call `configure`
+once at startup:
+
+```ts
+import { configure } from "@devjonaed/typesafe-ai";
+
+configure({ apiKey: process.env.MY_KEY, defaultModel: "jev-preview", timeout: 30_000 });
+```
+
+`configure` takes the SDK's `TypeSafeClientConfig` and returns the client. `client()` returns the
+current one, so the full SDK surface — `client().models.list()`, `client().systemOne(...)` — stays
+reachable when you need it.
+
+## Configuration
+
+Explicit options beat environment variables, which beat the defaults:
+
+| Variable | `configure` option | Default |
+| --- | --- | --- |
+| `TYPESAFE_API_KEY` | `apiKey` | required |
+| `TYPESAFE_BASE_URL` | `baseURL` | `https://api.typesafe.ai` |
+| `TYPESAFE_DEFAULT_MODEL` | `defaultModel` | `jev-latest` |
+| `TYPESAFE_LOG_LEVEL` | `logLevel` | `warn` |
+
+Other defaults: `timeout` 10000 ms per attempt, `retry.maxRetries` 2. Available models today are
+`jev-latest` and `jev-preview` — `client().models.list()` is the current answer.
+
+Set `logLevel: "info"` for request summaries, or `"debug"` to log headers and bodies. Credential
+headers are redacted; **bodies are not**, so keep `debug` away from production if your state
+contains personal data.
+
+The client refuses to run in a browser, because that would ship your API key to every visitor. Call
+it from your server. `dangerouslyAllowBrowser: true` overrides that, and the name is the warning.
+
+Three more `configure` options are worth knowing:
+
+```ts
+configure({
+  logger: myPinoLikeLogger, // anything with debug/info/warn/error; defaults to console
+  defaultHeaders: { "x-app": "support-inbox" }, // sent on every request
+  fetch: myFetch, // swap the transport — this is the seam the test suite uses
+});
+```
+
+## Request IDs
+
+Every call's request ID is on `$`, ready to quote to support:
+
+```ts
+const a = await ask(ticket, { category: ["billing", "technical", "other"] });
+a.$.requestId; // "req_01a0ca7f5a747639aaac05b46c7dc7db"
+```
+
+It is `undefined` when the server sends no `x-typesafe-request-id` header. Failures carry it too —
+every `APIError` has a `requestId`. For the raw `Response` itself, use the SDK promise underneath:
+`client().systemOne(...).withResponse()`, which also offers `asResponse()` and `map()`.
+
+## Types
+
+`ask` infers everything from the spec you pass, so you rarely need these, but they are exported for
+signatures of your own:
+
+```ts
+import type { Answer, Answers, Meta, Spec, SpecMap, QuestionOf } from "@devjonaed/typesafe-ai";
+
+type Routing = SpecMap & { category: readonly ["billing", "technical"] };
+type Category = Answer<readonly ["billing", "technical"]>; // "billing" | "technical"
+type Result = Answers<Routing>; // { category: ... } & { $: Meta<Routing> }
+```
+
+`EntryType`, `Question` and `SystemOneResult` are re-exported from the SDK for the same reason.
+
+## Errors
+
+Errors come from the SDK unchanged: `AuthenticationError` (401), `BadRequestError` (400),
+`PermissionDeniedError` (403), `UnprocessableEntityError` (422), `RateLimitError` (429, with
+`retryAfterMs`), `InternalServerError` (5xx), `APIConnectionError`, `APITimeoutError` and
+`APIUserAbortError` — all extending `TypeSafeError`. Import them from `@typesafe-ai/sdk`.
+
+Failed requests are retried twice by default, with backoff on 408, 429 and 5xx. Override per call
+with `retry`, or for every call through `configure`.
+
+Bad input is caught before any request goes out, always as `TypeSafeError`:
+
+```
+Questions must be an object keyed by answer name; got an array.
+"$" is reserved for the full result; rename that question.
+Question "category" must be a string, an array of at least two labels, or a question from choice(), score() or noul(); got number.
+Choice question "category" has 1 label; at least two are required.
+Choice question "category" repeats a label; every label must be distinct.
+Choice question "category" has a non-string label (1); labels must be strings.
+The model override is blank. Pass a model name, or omit `model`.
+The API key is blank. Pass a real key, or omit `apiKey` to read TYPESAFE_API_KEY from the environment.
+At least one question is required.                                    (from the SDK)
+Score question "severity" has 1 criteria; at least two scores are required.  (from the SDK)
+```
+
+A rejected `configure` leaves any previous client untouched. Every failure in this package is a
+`TypeSafeError`, so one check covers input mistakes, API errors and transport errors alike:
+
+```ts
+import { APIError, TypeSafeError } from "@typesafe-ai/sdk";
+
+try {
+  const a = await ask(ticket, { category: ["billing", "technical", "other"] });
+} catch (e) {
+  if (e instanceof APIError) console.error(e.status, e.requestId);
+  else if (e instanceof TypeSafeError) console.error("bad request shape:", e.message);
+  else throw e;
+}
+```
+
+A bad *response* is an error too, rather than a value that looks plausible:
+
+```
+The API returned no answer for question "category". Request ID: req_01a0ca7f5a747639aaac05b46c7dc7db.
+The API answered question "category" with a "noul" answer, but a "choice" question was asked.
+```
+
+The second one matters: without it, asking a Choice and receiving a Noul would hand you `0.5` where
+you expected a label. If a future model adds a question type this version does not know, you get
+that error instead of `undefined`.
+
+
+## Tests
+
+```sh
+npm test                      # build, then 34 offline tests
+TYPESAFE_API_KEY=... npm test # adds 8 tests against the real API
+npm run check:docs            # type-checks every snippet in this file
+```
+
+CI runs all of it on Node 20, 22 and 24 for every push and pull request. The live tests skip
+themselves when no key is present, so forks get a meaningful green run without secrets.
+
+The offline tests stub `fetch`, so they assert the exact request body that goes out — including that
+the array shorthand produces a byte-identical body to hand-written SDK questions. The live tests are
+skipped without a key.
+
+## Learn more
+
+This README documents the wrapper. For the model itself — when to reach for Choice over Score, how
+to decompose a judgment into atomic questions, and how confidence is calibrated — see the TypeSafe
+docs:
+
+- [Primitives](https://docs.typesafe.ai/primitives) — Choice, Score and Noul in depth
+- [Confidence](https://docs.typesafe.ai/confidence) — what it measures and how to gate on it
+- [Patterns](https://docs.typesafe.ai/patterns) — fan-out, confidence routing, composite scoring
+- [How to build with TypeSafe](https://docs.typesafe.ai/concepts/how-to-build-with-system-one)
+
+## Requirements
+
+Node 20 or newer. ESM only — there is no CommonJS build.
+
+## License
+
+MIT. Copyright (c) 2026 Md Jonaed Hasan. See [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { TypeSafeClient, type ChoiceQuestion, type EntryType, type NoulQuestion, type Question, type Questions, type RequestOptions, type ScoreQuestion, type SystemOneResult, type TypeSafeClientConfig } from "@typesafe-ai/sdk";
+export { choice, noul, score } from "@typesafe-ai/sdk";
+export type { EntryType, Question, SystemOneResult } from "@typesafe-ai/sdk";
+/** A question written the short way, or a full SDK question object. */
+export type Spec = string | readonly string[] | Question;
+/** Questions keyed by the name their answer is returned under. */
+export type SpecMap = Record<string, Spec>;
+/** The unwrapped answer for one spec: a probability, a label, or a score. */
+export type Answer<S> = S extends string ? number : S extends readonly (infer L)[] ? L extends string ? L : never : S extends ChoiceQuestion<infer C> ? keyof C & string : S extends ScoreQuestion<infer _> ? number : S extends NoulQuestion ? number : never;
+/** The SDK question a spec expands to, so `$` keeps its precise answer types. */
+export type QuestionOf<S> = S extends string ? NoulQuestion : S extends readonly (infer L)[] ? [L] extends [string] ? ChoiceQuestion<{
+    [Label in L]: null;
+}> : never : S extends Question ? S : never;
+/** The full SDK result, plus the request ID for the call that produced it. */
+export type Meta<S extends SpecMap> = SystemOneResult<{
+    [K in keyof S]: QuestionOf<S[K]>;
+} & Questions> & {
+    /** Request ID from `x-typesafe-request-id`, or `undefined` when absent. Quote it to support. */
+    readonly requestId: string | undefined;
+};
+/** Unwrapped answers by name, plus `$` holding the full SDK result. */
+export type Answers<S extends SpecMap> = {
+    [K in keyof S]: Answer<S[K]>;
+} & {
+    $: Meta<S>;
+};
+/**
+ * Replace the client `ask` uses. Call once at startup, or not at all.
+ *
+ * @throws {TypeSafeError} `apiKey` is present but blank. The SDK would accept it and fail
+ * later with a 401; failing here points at the unset variable that actually caused it.
+ */
+export declare const configure: (config?: TypeSafeClientConfig) => TypeSafeClient;
+/** The client `ask` uses, created from the environment on first use. */
+export declare const client: () => TypeSafeClient;
+/**
+ * Ask named questions about some state and get the answers back unwrapped.
+ *
+ * A string is a yes/no question and answers with a probability from 0 to 1.
+ * An array of labels is a choice and answers with the selected label.
+ * `choice()`, `score()` and `noul()` cover the cases that need descriptions.
+ *
+ * @example
+ * const a = await ask("I was charged twice. Fix this ASAP.", {
+ *   category: ["billing", "technical", "other"],
+ *   urgent: "Is the customer angry?",
+ * });
+ * a.category; // "billing"
+ * a.urgent; // 0.93
+ * a.$.answers.category.confidence; // 0.88
+ * a.$.requestId; // "req_01a0ca7f5a747639aaac05b46c7dc7db"
+ */
+export declare function ask<const S extends SpecMap>(state: EntryType, spec: S, options?: RequestOptions & {
+    model?: string;
+}): Promise<Answers<S>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EAId,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE7E,uEAAuE;AACvE,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,QAAQ,CAAC;AAEzD,kEAAkE;AAClE,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE3C,6EAA6E;AAC7E,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GACpC,MAAM,GACN,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAC5B,CAAC,SAAS,MAAM,GACd,CAAC,GACD,KAAK,GACP,CAAC,SAAS,cAAc,CAAC,MAAM,CAAC,CAAC,GAC/B,MAAM,CAAC,GAAG,MAAM,GAChB,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAC9B,MAAM,GACN,CAAC,SAAS,YAAY,GACpB,MAAM,GACN,KAAK,CAAC;AAElB,iFAAiF;AACjF,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GACxC,YAAY,GACZ,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAC5B,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAClB,cAAc,CAAC;KAAG,KAAK,IAAI,CAAC,GAAG,IAAI;CAAE,CAAC,GACtC,KAAK,GACP,CAAC,SAAS,QAAQ,GAChB,CAAC,GACD,KAAK,CAAC;AAEd,8EAA8E;AAC9E,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,OAAO,IAAI,eAAe,CACnD;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,SAAS,CACjD,GAAG;IACF,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,OAAO,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG;IAC1E,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;CACZ,CAAC;AAuEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,SAAQ,oBAAyB,KAAG,cAM7D,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,MAAM,QAAO,cAAmD,CAAC;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,OAAO,EAC/C,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,cAAc,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAiCrB"}

package/dist/index.js

@@ -0,0 +1,102 @@
+import { TypeSafeClient, TypeSafeError, choice, noul, } from "@typesafe-ai/sdk";
+export { choice, noul, score } from "@typesafe-ai/sdk";
+/** The question types this version understands. */
+const TYPES = new Set(["noul", "choice", "score"]);
+const toQuestion = (name, spec) => {
+    if (typeof spec === "string")
+        return noul(spec);
+    if (Array.isArray(spec)) {
+        const bad = spec.find((label) => typeof label !== "string");
+        if (bad !== undefined)
+            throw new TypeSafeError(`Choice question "${name}" has a non-string label (${JSON.stringify(bad)}); labels must be strings.`);
+        // Mirror the SDK's own rule for score rubrics: a question nobody can answer is a
+        // mistake worth catching here, not a 422 from the server.
+        const labels = new Set(spec);
+        if (labels.size !== spec.length)
+            throw new TypeSafeError(`Choice question "${name}" repeats a label; every label must be distinct.`);
+        if (labels.size < 2)
+            throw new TypeSafeError(`Choice question "${name}" has ${labels.size} label${labels.size === 1 ? "" : "s"}; at least two are required.`);
+        return choice(null, Object.fromEntries([...labels].map((label) => [label, null])));
+    }
+    // Anything else has to be a question object, or the request would be silently malformed
+    // and the API would answer a question nobody asked.
+    if (spec === null || typeof spec !== "object" || !TYPES.has(spec.type))
+        throw new TypeSafeError(`Question "${name}" must be a string, an array of at least two labels, or a question from choice(), score() or noul(); got ${describe(spec)}.`);
+    return spec;
+};
+const describe = (value) => value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
+/**
+ * Pull the one value a caller wants out of an answer.
+ *
+ * The answer has to match the question that was asked. A mismatch means the API and this
+ * package disagree about the request, and returning the wrong field would look like a
+ * plausible answer rather than a bug.
+ */
+const unwrap = (name, asked, answer) => {
+    if (answer === null || typeof answer !== "object")
+        throw new TypeSafeError(`The API answered question "${name}" with ${describe(answer)} instead of an answer.`);
+    if (answer.type !== asked.type)
+        throw new TypeSafeError(`The API answered question "${name}" with a ${JSON.stringify(answer.type)} answer, but a ${JSON.stringify(asked.type)} question was asked.`);
+    switch (answer.type) {
+        case "noul":
+            return answer.noul;
+        case "choice":
+            return answer.choice;
+        case "score":
+            return answer.score;
+    }
+};
+let shared;
+/**
+ * Replace the client `ask` uses. Call once at startup, or not at all.
+ *
+ * @throws {TypeSafeError} `apiKey` is present but blank. The SDK would accept it and fail
+ * later with a 401; failing here points at the unset variable that actually caused it.
+ */
+export const configure = (config = {}) => {
+    if (config.apiKey !== undefined && config.apiKey.trim() === "")
+        throw new TypeSafeError("The API key is blank. Pass a real key, or omit `apiKey` to read TYPESAFE_API_KEY from the environment.");
+    return (shared = new TypeSafeClient(config));
+};
+/** The client `ask` uses, created from the environment on first use. */
+export const client = () => (shared ??= new TypeSafeClient());
+/**
+ * Ask named questions about some state and get the answers back unwrapped.
+ *
+ * A string is a yes/no question and answers with a probability from 0 to 1.
+ * An array of labels is a choice and answers with the selected label.
+ * `choice()`, `score()` and `noul()` cover the cases that need descriptions.
+ *
+ * @example
+ * const a = await ask("I was charged twice. Fix this ASAP.", {
+ *   category: ["billing", "technical", "other"],
+ *   urgent: "Is the customer angry?",
+ * });
+ * a.category; // "billing"
+ * a.urgent; // 0.93
+ * a.$.answers.category.confidence; // 0.88
+ * a.$.requestId; // "req_01a0ca7f5a747639aaac05b46c7dc7db"
+ */
+export async function ask(state, spec, options = {}) {
+    if (spec === null || typeof spec !== "object" || Array.isArray(spec))
+        throw new TypeSafeError(`Questions must be an object keyed by answer name; got ${describe(spec)}.`);
+    if ("$" in spec)
+        throw new TypeSafeError('"$" is reserved for the full result; rename that question.');
+    const { model, ...request } = options;
+    if (model !== undefined && model.trim() === "")
+        throw new TypeSafeError("The model override is blank. Pass a model name, or omit `model`.");
+    const questions = Object.fromEntries(Object.entries(spec).map(([name, value]) => [name, toQuestion(name, value)]));
+    const { data, requestId } = await client()
+        .systemOne({ state, questions, model }, request)
+        .withResponse();
+    // Object.fromEntries defines own properties, so a question named "__proto__" lands as
+    // data rather than silently reassigning the prototype.
+    const answers = Object.fromEntries(Object.keys(spec).map((name) => {
+        const answer = data.answers[name];
+        if (answer === undefined)
+            throw new TypeSafeError(`The API returned no answer for question "${name}". Request ID: ${requestId ?? "unknown"}.`);
+        return [name, unwrap(name, questions[name], answer)];
+    }));
+    return { ...answers, $: { ...data, requestId } };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@devjonaed/typesafe-ai",
+  "version": "0.1.0",
+  "description": "Unofficial two-line wrapper around the TypeSafe AI SDK: ask typed questions, get unwrapped answers.",
+  "keywords": [
+    "typesafe",
+    "jev",
+    "system-one",
+    "llm",
+    "classification",
+    "typescript",
+    "unofficial"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Md Jonaed Hasan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonaed1230/typesafe-ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jonaed1230/typesafe-ai/issues"
+  },
+  "homepage": "https://github.com/jonaed1230/typesafe-ai#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test",
+    "check:docs": "node scripts/check-readme.mjs",
+    "prepublishOnly": "npm test && npm run check:docs"
+  },
+  "dependencies": {
+    "@typesafe-ai/sdk": "^0.6.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,206 @@
+import {
+  TypeSafeClient,
+  TypeSafeError,
+  choice,
+  noul,
+  type ChoiceQuestion,
+  type EntryType,
+  type NoulQuestion,
+  type Question,
+  type Questions,
+  type ResultFor,
+  type RequestOptions,
+  type ScoreQuestion,
+  type SystemOneResult,
+  type TypeSafeClientConfig,
+} from "@typesafe-ai/sdk";
+
+export { choice, noul, score } from "@typesafe-ai/sdk";
+export type { EntryType, Question, SystemOneResult } from "@typesafe-ai/sdk";
+
+/** A question written the short way, or a full SDK question object. */
+export type Spec = string | readonly string[] | Question;
+
+/** Questions keyed by the name their answer is returned under. */
+export type SpecMap = Record<string, Spec>;
+
+/** The unwrapped answer for one spec: a probability, a label, or a score. */
+export type Answer<S> = S extends string
+  ? number
+  : S extends readonly (infer L)[]
+    ? L extends string
+      ? L
+      : never
+    : S extends ChoiceQuestion<infer C>
+      ? keyof C & string
+      : S extends ScoreQuestion<infer _>
+        ? number
+        : S extends NoulQuestion
+          ? number
+          : never;
+
+/** The SDK question a spec expands to, so `$` keeps its precise answer types. */
+export type QuestionOf<S> = S extends string
+  ? NoulQuestion
+  : S extends readonly (infer L)[]
+    ? [L] extends [string]
+      ? ChoiceQuestion<{ [Label in L]: null }>
+      : never
+    : S extends Question
+      ? S
+      : never;
+
+/** The full SDK result, plus the request ID for the call that produced it. */
+export type Meta<S extends SpecMap> = SystemOneResult<
+  { [K in keyof S]: QuestionOf<S[K]> } & Questions
+> & {
+  /** Request ID from `x-typesafe-request-id`, or `undefined` when absent. Quote it to support. */
+  readonly requestId: string | undefined;
+};
+
+/** Unwrapped answers by name, plus `$` holding the full SDK result. */
+export type Answers<S extends SpecMap> = { [K in keyof S]: Answer<S[K]> } & {
+  $: Meta<S>;
+};
+
+/** The question types this version understands. */
+const TYPES = new Set(["noul", "choice", "score"]);
+
+const toQuestion = (name: string, spec: Spec): Question => {
+  if (typeof spec === "string") return noul(spec);
+
+  if (Array.isArray(spec)) {
+    const bad = spec.find((label) => typeof label !== "string");
+    if (bad !== undefined)
+      throw new TypeSafeError(
+        `Choice question "${name}" has a non-string label (${JSON.stringify(bad)}); labels must be strings.`,
+      );
+
+    // Mirror the SDK's own rule for score rubrics: a question nobody can answer is a
+    // mistake worth catching here, not a 422 from the server.
+    const labels = new Set<string>(spec);
+    if (labels.size !== spec.length)
+      throw new TypeSafeError(
+        `Choice question "${name}" repeats a label; every label must be distinct.`,
+      );
+    if (labels.size < 2)
+      throw new TypeSafeError(
+        `Choice question "${name}" has ${labels.size} label${labels.size === 1 ? "" : "s"}; at least two are required.`,
+      );
+
+    return choice(null, Object.fromEntries([...labels].map((label) => [label, null])));
+  }
+
+  // Anything else has to be a question object, or the request would be silently malformed
+  // and the API would answer a question nobody asked.
+  if (spec === null || typeof spec !== "object" || !TYPES.has((spec as Question).type))
+    throw new TypeSafeError(
+      `Question "${name}" must be a string, an array of at least two labels, or a question from choice(), score() or noul(); got ${describe(spec)}.`,
+    );
+  return spec as Question;
+};
+
+const describe = (value: unknown): string =>
+  value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
+
+/**
+ * Pull the one value a caller wants out of an answer.
+ *
+ * The answer has to match the question that was asked. A mismatch means the API and this
+ * package disagree about the request, and returning the wrong field would look like a
+ * plausible answer rather than a bug.
+ */
+const unwrap = (name: string, asked: Question, answer: ResultFor<Question> | undefined) => {
+  if (answer === null || typeof answer !== "object")
+    throw new TypeSafeError(
+      `The API answered question "${name}" with ${describe(answer)} instead of an answer.`,
+    );
+  if (answer.type !== asked.type)
+    throw new TypeSafeError(
+      `The API answered question "${name}" with a ${JSON.stringify(answer.type)} answer, but a ${JSON.stringify(asked.type)} question was asked.`,
+    );
+
+  switch (answer.type) {
+    case "noul":
+      return answer.noul;
+    case "choice":
+      return answer.choice;
+    case "score":
+      return answer.score;
+  }
+};
+
+let shared: TypeSafeClient | undefined;
+
+/**
+ * Replace the client `ask` uses. Call once at startup, or not at all.
+ *
+ * @throws {TypeSafeError} `apiKey` is present but blank. The SDK would accept it and fail
+ * later with a 401; failing here points at the unset variable that actually caused it.
+ */
+export const configure = (config: TypeSafeClientConfig = {}): TypeSafeClient => {
+  if (config.apiKey !== undefined && config.apiKey.trim() === "")
+    throw new TypeSafeError(
+      "The API key is blank. Pass a real key, or omit `apiKey` to read TYPESAFE_API_KEY from the environment.",
+    );
+  return (shared = new TypeSafeClient(config));
+};
+
+/** The client `ask` uses, created from the environment on first use. */
+export const client = (): TypeSafeClient => (shared ??= new TypeSafeClient());
+
+/**
+ * Ask named questions about some state and get the answers back unwrapped.
+ *
+ * A string is a yes/no question and answers with a probability from 0 to 1.
+ * An array of labels is a choice and answers with the selected label.
+ * `choice()`, `score()` and `noul()` cover the cases that need descriptions.
+ *
+ * @example
+ * const a = await ask("I was charged twice. Fix this ASAP.", {
+ *   category: ["billing", "technical", "other"],
+ *   urgent: "Is the customer angry?",
+ * });
+ * a.category; // "billing"
+ * a.urgent; // 0.93
+ * a.$.answers.category.confidence; // 0.88
+ * a.$.requestId; // "req_01a0ca7f5a747639aaac05b46c7dc7db"
+ */
+export async function ask<const S extends SpecMap>(
+  state: EntryType,
+  spec: S,
+  options: RequestOptions & { model?: string } = {},
+): Promise<Answers<S>> {
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec))
+    throw new TypeSafeError(
+      `Questions must be an object keyed by answer name; got ${describe(spec)}.`,
+    );
+  if ("$" in spec)
+    throw new TypeSafeError(
+      '"$" is reserved for the full result; rename that question.',
+    );
+
+  const { model, ...request } = options;
+  if (model !== undefined && model.trim() === "")
+    throw new TypeSafeError("The model override is blank. Pass a model name, or omit `model`.");
+  const questions = Object.fromEntries(
+    Object.entries(spec).map(([name, value]) => [name, toQuestion(name, value)]),
+  ) as Questions;
+  const { data, requestId } = await client()
+    .systemOne({ state, questions, model }, request)
+    .withResponse();
+
+  // Object.fromEntries defines own properties, so a question named "__proto__" lands as
+  // data rather than silently reassigning the prototype.
+  const answers = Object.fromEntries(
+    Object.keys(spec).map((name) => {
+      const answer = data.answers[name];
+      if (answer === undefined)
+        throw new TypeSafeError(
+          `The API returned no answer for question "${name}". Request ID: ${requestId ?? "unknown"}.`,
+        );
+      return [name, unwrap(name, questions[name]!, answer)];
+    }),
+  );
+  return { ...answers, $: { ...data, requestId } } as Answers<S>;
+}