dyadic 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 1.3.0 (2026-10-10)
+
+- `decisions.create(input, questions, model?)`: typed answers (a predicate's probability, a
+  choice or a score) from `POST /v1/decisions`.
+
+## 1.2.0 (2026-10-07)
+
+Security release.
+
+- The API key is only ever sent to the configured API origin. `request()` with an
+  absolute URL on another host, port or scheme, with credentials in it, or
+  protocol-relative, now raises instead of sending the key; redirects are not
+  followed. Plain `http://` base URLs are accepted only for local or
+  private-network APIs.
+- Retries no longer repeat work that may already have run. GET, HEAD, DELETE and
+  OPTIONS retry on busy or failing servers; other requests retry only when they
+  never started (no connection, or Dyadic's `rate_limit_exceeded` /
+  `concurrency_limit` refusal). `409` is no longer retried.
+- Every attempt of one call sends the same `Idempotency-Key` (choose it with
+  `{ idempotencyKey }`, or mark a call safe to replay with `{ idempotent: true }`).
+- The package documents server-side use only (a key must never ship to a browser), builds before `npm test` and `npm pack`, and has a lockfile.
+
+## 1.1.0
+
+- Runs with your own agents and functions, and connected apps (Workspace saves).

package/README.md

@@ -4,7 +4,7 @@
 npm install dyadic
 ```
 
-The official TypeScript and JavaScript SDK for the [Dyadic API](https://dyadic.app/developers/): Iris with streaming, function calling, images and typed errors. No dependencies; Node 18+, Deno, Bun and browsers.
+The official TypeScript and JavaScript SDK for the [Dyadic API](https://dyadic.app/developers/): Iris with streaming, function calling, images and typed errors. No dependencies; for server-side code on Node 18+, Deno and Bun (keep your key off the browser, see below).
 
 ```ts
 import { Dyadic } from "dyadic";
@@ -13,6 +13,41 @@ const client = new Dyadic({ apiKey: process.env.DYADIC_API_KEY });
 console.log(await client.ask("Hello!", { model: "iris" }));
 ```
 
+## Keep your key on the server
+
+**A Dyadic API key is a long-lived secret that spends your credits. Never ship it
+to a browser**: not in a bundle, page source, local storage or a request your
+front end makes, where any visitor or extension can copy it. Use the SDK in
+server-side code (Node 18+, Deno, Bun, edge functions) and have your front end
+call your own server:
+
+```ts
+// server.ts: the key stays here
+import { Dyadic } from "dyadic";
+const client = new Dyadic({ apiKey: process.env.DYADIC_API_KEY });
+
+export async function POST(request: Request) {
+  const { question } = await request.json();
+  // Check your own user's session and limits here before spending credits.
+  return Response.json({ answer: await client.ask(String(question).slice(0, 4000), { model: "iris" }) });
+}
+```
+
+`request()` only ever sends the key to the API you configured: a relative path
+joins `baseURL`, and an absolute URL on any other host, port or scheme (or with
+credentials in it) throws `DyadicError` instead of being sent. Redirects are not
+followed. Plain `http://` is accepted only for a local or private-network API.
+
+## Retries
+
+GET, HEAD, DELETE and OPTIONS are retried on busy or failing servers. Anything
+else (a completion, an upload, a run) may already have run, and been billed,
+when it fails, so it is retried only if it provably never started: the
+connection was never made, or Dyadic refused it with `rate_limit_exceeded` or
+`concurrency_limit`. Every attempt of one call carries the same
+`Idempotency-Key`; pass `{ idempotencyKey }` to choose it, or `{ idempotent: true }`
+for a call that is safe to send twice.
+
 ## Runs: your own agent, Dyadic's tools, your functions
 
 ```ts
@@ -34,6 +69,26 @@ console.log(run.output_text);
 
 `client.runs.create({ ..., stream: true })` streams the run's events.
 
+## Decisions: typed answers, fast and cheap
+
+Ask one or more questions about some text (or text and images) and get typed answers
+back: a probability (`predicate`), one of your values (`choice`) or a rubric level
+(`score`). A fraction of a second and a fraction of a cent; billed at cost.
+
+```ts
+const decision = await client.decisions.create({
+  input: "I can't log in after resetting my password.",
+  questions: [
+    { type: "predicate", name: "urgent", instructions: "The customer is blocked from using the product." },
+    { type: "choice", name: "team", instructions: "Which team should handle this.", choices: [
+      { value: "account", description: "Sign-in and account access" },
+      { value: "billing", description: "Payments and invoices" },
+      { value: "other", description: "Anything else" },
+    ] },
+  ],
+});
+```
+
 ## Connected apps: saving into a person's Workspace
 
 With the person's approval, an application can save into their Dyadic

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "1.1.0";
+export declare const VERSION = "1.2.0";
 export declare const DEFAULT_BASE_URL = "https://dyadic.app/api/openai/v1";
 export type Model = "iris" | "iris-think" | (string & {});
 export type Role = "system" | "developer" | "user" | "assistant" | "tool";
@@ -310,6 +310,59 @@ export interface Moderation {
         category_applied_input_types: Record<string, string[]>;
     }[];
 }
+export type DecisionQuestion = {
+    type: "predicate";
+    name: string;
+    instructions: string;
+} | {
+    type: "choice";
+    name: string;
+    instructions: string;
+    choices: {
+        value: string;
+        description: string;
+    }[];
+} | {
+    type: "score";
+    name: string;
+    instructions: string;
+    levels: {
+        label: string;
+        description: string;
+    }[];
+};
+export type DecisionAnswer = {
+    type: "predicate";
+    name: string;
+    probability: number;
+} | {
+    type: "choice";
+    name: string;
+    choice: string;
+    probabilities: {
+        value: string;
+        probability: number;
+    }[];
+    confidence: number;
+} | {
+    type: "score";
+    name: string;
+    score: number;
+    probabilities: {
+        value: number;
+        label: string;
+        probability: number;
+    }[];
+    confidence: number;
+} | {
+    type: "refusal";
+    name: string;
+};
+export interface Decision {
+    id: string | null;
+    model: string;
+    answers: DecisionAnswer[];
+}
 export interface FileObject {
     id: string;
     object: "file";
@@ -455,12 +508,16 @@ export interface WorkspaceSave {
     }[];
     url: string;
 }
-/** `executes`: the request's work may already be done when it fails (a run), so it is retried only when refused before starting. */
+/** `idempotent`: the call is safe to send twice, so it is retried like a GET. `idempotencyKey`: the Idempotency-Key every
+ * attempt of this call carries (one is made for anything but GET, HEAD, DELETE and OPTIONS). `executes` is accepted for
+ * compatibility; it is now the rule for every POST. */
 export interface RequestOptions {
     form?: FormData;
     query?: Record<string, string | number | undefined>;
     raw?: boolean;
     executes?: boolean;
+    idempotent?: boolean;
+    idempotencyKey?: string;
 }
 /** Bytes from the API (speech audio, file downloads). */
 export declare class Binary {
@@ -522,10 +579,17 @@ export declare class Dyadic {
     readonly timeoutMs: number;
     readonly maxRetries: number;
     readonly appName?: string;
+    /** The one origin this client ever sends its key to. */
+    readonly origin: string;
     private fetcher;
     constructor(options?: ClientOptions);
-    /** Low-level request: JSON (or multipart `options.form`) in; JSON, text, Binary (`options.raw`) or a Stream out,
-     * with retries for busy or failing servers. */
+    /** The full URL for `path`: a relative path joins the base URL; an absolute URL is allowed only on the base URL's own
+     * origin. The key goes with every request, so it must never reach another host, a plain-http downgrade, or a URL with
+     * credentials in it. */
+    private url;
+    /** Low-level request: JSON (or multipart `options.form`) in; JSON, text, Binary (`options.raw`) or a Stream out. `path` is
+     * relative to the base URL; an absolute URL must be on its origin. GET, HEAD, DELETE and OPTIONS are retried on busy or
+     * failing servers; anything else only if it provably never started, unless `options.idempotent`. */
     request<T>(method: string, path: string, body?: unknown, stream?: boolean, options?: RequestOptions): Promise<T>;
     /** Dyadic's own endpoints sit beside the OpenAI-compatible base: .../api/openai/v1 -> .../api/v1. */
     platformURL(path: string): string;
@@ -620,6 +684,17 @@ export declare class Dyadic {
             model?: string;
         }) => Promise<Moderation>;
     };
+    /** Typed answers: each question a predicate (a probability), a choice or a score, about the input. */
+    readonly decisions: {
+        create: (params: {
+            input: string | {
+                role: "user";
+                content: unknown[];
+            }[];
+            questions: DecisionQuestion[];
+            model?: string;
+        }) => Promise<Decision>;
+    };
     readonly images: {
         generate: (params: ImageParams) => Promise<ImageResponse>;
         edit: ({ image, ...params }: Omit<ImageParams, "model"> & {
@@ -667,8 +742,8 @@ export declare class Dyadic {
         discord: (discordId: string | number) => Promise<Connection>;
     };
     /** Save into the Workspace of the person with this Discord account, once they approved this application.
-     * Not approved yet throws DyadicError with code "authorization_required" (`error.body.authorize_url`);
-     * no Dyadic account with that Discord account: "account_not_linked". */
+     * Not approved yet throws DyadicError with code "authorization_required" (`error.body.authorize_url`),
+     * whether or not they have a Dyadic account yet. */
     readonly workspace: {
         saves: {
             create: ({ discord_id, ...fields }: WorkspaceSaveParams) => Promise<WorkspaceSave>;

package/dist/index.js

@@ -1,6 +1,6 @@
 // The official TypeScript SDK for the Dyadic API: Iris
 // through the OpenAI-compatible endpoints at https://dyadic.app/api/openai/v1.
-export const VERSION = "1.1.0";
+export const VERSION = "1.2.0";
 export const DEFAULT_BASE_URL = "https://dyadic.app/api/openai/v1";
 /** Bytes from the API (speech audio, file downloads). */
 export class Binary {
@@ -115,10 +115,35 @@ export class Stream {
     async finalText() { for await (const _ of this) { /* drain */ } return this.text; }
     abort() { this.controller.abort(); }
 }
-const RETRY = new Set([408, 409, 429, 500, 502, 503, 504]);
-// A run may have executed (and been billed) by the time it fails.
-const RUN_RETRY = new Set([429]);
+// Methods that can be sent again safely: reading, or deleting the same thing twice.
+const SAFE_METHODS = new Set(["GET", "HEAD", "DELETE", "OPTIONS"]);
+const RETRY = new Set([408, 429, 500, 502, 503, 504]);
+// Anything else (a completion, an upload, a run) may already have run, and been billed, by the time it fails. It is sent
+// again only when it provably never started: no connection was made, or Dyadic refused it at the door with these codes.
+const ADMISSION_CODES = new Set(["rate_limit_exceeded", "concurrency_limit"]);
+// Network errors that mean nothing was sent (Node's codes; other runtimes report no code, so nothing is assumed).
+const NOT_SENT = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "UND_ERR_CONNECT_TIMEOUT"]);
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:/;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const sentNothing = (error) => {
+    const e = error;
+    return [e?.code, e?.cause?.code, e?.cause?.cause?.code].some((code) => code !== undefined && NOT_SENT.has(code));
+};
+const newKey = () => globalThis.crypto?.randomUUID?.()
+    ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;
+/** Loopback, a private address or a single-label name (a Docker or LAN service such as dyadic-api): where plain http
+ * can't cross the internet. */
+const privateHost = (hostname) => {
+    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    const v4 = host.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+    if (v4) {
+        const [a, b] = [Number(v4[1]), Number(v4[2])];
+        return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    }
+    if (host.includes(":"))
+        return host === "::1" || /^f[cd]/.test(host) || /^fe[89ab]/.test(host);
+    return host === "localhost" || host.endsWith(".localhost") || !host.includes(".");
+};
 export class Dyadic {
     constructor(options = {}) {
         /** An agent answers a conversation: one of the account's agents by id ("iris") or your own agent inline,
@@ -196,6 +221,10 @@ export class Dyadic {
         this.moderations = {
             create: (params) => this.request("POST", "/moderations", params),
         };
+        /** Typed answers: each question a predicate (a probability), a choice or a score, about the input. */
+        this.decisions = {
+            create: (params) => this.request("POST", "/decisions", params),
+        };
         this.images = {
             generate: (params) => this.request("POST", "/images/generations", params),
             edit: ({ image, ...params }) => this.request("POST", "/images/edits", undefined, false, { form: form(params, { image: [image, "image.png"] }) }),
@@ -219,51 +248,91 @@ export class Dyadic {
             discord: (discordId) => this.request("GET", this.platformURL(`/connections/discord/${discordId}`)),
         };
         /** Save into the Workspace of the person with this Discord account, once they approved this application.
-         * Not approved yet throws DyadicError with code "authorization_required" (`error.body.authorize_url`);
-         * no Dyadic account with that Discord account: "account_not_linked". */
+         * Not approved yet throws DyadicError with code "authorization_required" (`error.body.authorize_url`),
+         * whether or not they have a Dyadic account yet. */
         this.workspace = {
             saves: {
                 create: ({ discord_id, ...fields }) => this.request("POST", this.platformURL("/workspace/saves"), { user: { discord_id: String(discord_id) }, ...fields }, false, { executes: true }),
             },
         };
-        // process.env where it exists (Node, Bun, Deno with compat); browsers pass apiKey.
+        // process.env where it exists (Node, Bun, Deno with compat). Keep the key on a server: never ship it to a browser.
         const env = globalThis.process?.env ?? {};
         this.apiKey = options.apiKey ?? env.DYADIC_API_KEY ?? "";
         if (!this.apiKey)
             throw new DyadicError("No API key. Pass apiKey or set DYADIC_API_KEY. Create one at https://dyadic.app/workspace/?view=api.");
         this.baseURL = (options.baseURL ?? env.DYADIC_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        let base;
+        try {
+            base = new URL(this.baseURL);
+        }
+        catch {
+            throw new DyadicError(`baseURL isn't a valid URL: ${this.baseURL}`);
+        }
+        if (!(base.protocol === "https:" || (base.protocol === "http:" && privateHost(base.hostname))) || base.username || base.password) {
+            throw new DyadicError("baseURL must be an https:// URL (http:// only for a local or private-network API), without a user name or password.");
+        }
+        this.origin = base.origin;
         this.timeoutMs = options.timeoutMs ?? 600000;
         this.maxRetries = options.maxRetries ?? 2;
         this.appName = options.appName;
         this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
     }
-    /** Low-level request: JSON (or multipart `options.form`) in; JSON, text, Binary (`options.raw`) or a Stream out,
-     * with retries for busy or failing servers. */
+    /** The full URL for `path`: a relative path joins the base URL; an absolute URL is allowed only on the base URL's own
+     * origin. The key goes with every request, so it must never reach another host, a plain-http downgrade, or a URL with
+     * credentials in it. */
+    url(path) {
+        if (path.startsWith("//") || path.startsWith("\\\\"))
+            throw new DyadicError("Protocol-relative URLs aren't allowed; pass a path like /models.");
+        const candidate = SCHEME.test(path) ? path : this.baseURL + (path.startsWith("/") ? path : `/${path}`);
+        let target;
+        try {
+            target = new URL(candidate);
+        }
+        catch {
+            throw new DyadicError(`Not a valid URL: ${path}`);
+        }
+        if (target.username || target.password || target.origin !== this.origin) {
+            throw new DyadicError(`Refusing to send the API key to ${target.protocol}//${target.host}: this client only calls ${this.origin}.`);
+        }
+        return target.toString();
+    }
+    /** Low-level request: JSON (or multipart `options.form`) in; JSON, text, Binary (`options.raw`) or a Stream out. `path` is
+     * relative to the base URL; an absolute URL must be on its origin. GET, HEAD, DELETE and OPTIONS are retried on busy or
+     * failing servers; anything else only if it provably never started, unless `options.idempotent`. */
     async request(method, path, body, stream = false, options = {}) {
         const headers = { Authorization: `Bearer ${this.apiKey}`, Accept: stream ? "text/event-stream" : options.raw ? "*/*" : "application/json" };
         if (body !== undefined && !options.form)
             headers["Content-Type"] = "application/json";
         const query = Object.entries(options.query ?? {}).filter(([, v]) => v !== undefined).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
-        const url = `${path.startsWith("http") ? path : this.baseURL + path}${query ? `?${query}` : ""}`;
+        const target = this.url(path);
+        const url = `${target}${query ? `${target.includes("?") ? "&" : "?"}${query}` : ""}`;
         const payload = options.form ?? (body === undefined ? undefined : JSON.stringify(body));
         if (this.appName)
             headers["X-Title"] = this.appName;
+        const replayable = Boolean(options.idempotent) || SAFE_METHODS.has(method.toUpperCase());
+        if (!replayable || options.idempotencyKey)
+            headers["Idempotency-Key"] = options.idempotencyKey ?? newKey();
         for (let attempt = 0;; attempt++) {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), this.timeoutMs);
             timer?.unref?.();
             let response;
             try {
-                response = await this.fetcher(url, { method, headers, body: payload, signal: controller.signal });
+                // Never follow a redirect: it would carry the key wherever it points.
+                response = await this.fetcher(url, { method, headers, body: payload, signal: controller.signal, redirect: "manual" });
             }
             catch (error) {
                 clearTimeout(timer);
-                if (attempt < this.maxRetries && !options.executes) {
+                if (attempt < this.maxRetries && (replayable || sentNothing(error))) {
                     await sleep(500 * 2 ** attempt);
                     continue;
                 }
                 throw new DyadicError(`Could not reach the Dyadic API: ${error.message}`);
             }
+            if (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
+                clearTimeout(timer);
+                throw new DyadicError(`The API answered with a redirect (HTTP ${response.status}); not following it with your key.`, { status: response.status });
+            }
             if (!stream)
                 clearTimeout(timer);
             if (response.ok) {
@@ -279,7 +348,8 @@ export class Dyadic {
             clearTimeout(timer);
             const data = await response.json().catch(() => ({ error: { message: `HTTP ${response.status}` } }));
             const error = data?.error ?? {};
-            if ((options.executes ? RUN_RETRY : RETRY).has(response.status) && attempt < this.maxRetries && error.type !== "insufficient_quota") {
+            const retry = replayable ? RETRY.has(response.status) : response.status === 429 && ADMISSION_CODES.has(error.code);
+            if (retry && attempt < this.maxRetries && error.type !== "insufficient_quota") {
                 const after = Number(response.headers.get("retry-after"));
                 await sleep(Number.isFinite(after) && after > 0 ? Math.min(after, 30) * 1000 : 500 * 2 ** attempt);
                 continue;

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "dyadic",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "The official TypeScript and JavaScript SDK for the Dyadic API: runs with your own agents and functions, plus the OpenAI-compatible API.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist", "README.md"],
+  "files": ["dist", "README.md", "CHANGELOG.md"],
   "engines": { "node": ">=18" },
   "license": "MIT",
   "homepage": "https://dyadic.app/developers/",
-  "scripts": { "build": "tsc", "test": "node --test test/client.test.js" },
+  "scripts": { "build": "tsc", "pretest": "tsc", "test": "node --test test/client.test.js test/transport.test.js", "prepack": "tsc" },
   "devDependencies": { "typescript": "5.6.3" }
 }