dyadic 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 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

@@ -1,59 +1,94 @@
-# dyadic
-
-```sh
-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.
-
-```ts
-import { Dyadic } from "dyadic";
-
-const client = new Dyadic({ apiKey: process.env.DYADIC_API_KEY });
-console.log(await client.ask("Hello!", { model: "iris" }));
-```
-
-## Runs: your own agent, Dyadic's tools, your functions
-
-```ts
-const run = await client.runs.run({
-  agent: { id: "helpdesk", name: "Helpdesk", instructions: "You answer customers of a small shop." },
-  messages: [{ role: "user", content: "Where is order 1042?" }],
-  builtin_tools: ["data.web_search"],
-  functions: {
-    lookup_order: {
-      description: "Look up an order by id.",
-      parameters: { type: "object", properties: { order_id: { type: "string" } }, required: ["order_id"] },
-      handler: async ({ order_id }) => ({ order_id, status: "shipped" }),
-    },
-  },
-  end_user: "customer-17",
-});
-console.log(run.output_text);
-```
-
-`client.runs.create({ ..., stream: true })` streams the run's events.
-
-## Connected apps: saving into a person's Workspace
-
-With the person's approval, an application can save into their Dyadic
-Workspace, naming them by the Discord account linked to their Dyadic account.
-
-```ts
-const status = await client.connections.discord(discordId);
-if (!status.authorized) console.log("Allow this app:", status.authorize_url); // show the person this link
-
-try {
-  const saved = await client.workspace.saves.create({ discord_id: discordId, kind: "message", title: "From #general",
-    text: "Worth keeping", url: "https://discord.com/channels/1/2/3" });
-  console.log(saved.url);
-} catch (error) {
-  if (error instanceof DyadicError && error.code === "authorization_required") console.log("Allow this app:", error.body.authorize_url);
-}
-```
-
-`kind` is `message`, `conversation` (with `messages`, saved as a chat the
-person can continue unless `as_chat: false`), `image` or `file` (with `files`:
-base64, up to 10 of 8 MB).
-
-Full guide: https://dyadic.app/developers/
+# dyadic
+
+```sh
+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; for server-side code on Node 18+, Deno and Bun (keep your key off the browser, see below).
+
+```ts
+import { Dyadic } from "dyadic";
+
+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
+const run = await client.runs.run({
+  agent: { id: "helpdesk", name: "Helpdesk", instructions: "You answer customers of a small shop." },
+  messages: [{ role: "user", content: "Where is order 1042?" }],
+  builtin_tools: ["data.web_search"],
+  functions: {
+    lookup_order: {
+      description: "Look up an order by id.",
+      parameters: { type: "object", properties: { order_id: { type: "string" } }, required: ["order_id"] },
+      handler: async ({ order_id }) => ({ order_id, status: "shipped" }),
+    },
+  },
+  end_user: "customer-17",
+});
+console.log(run.output_text);
+```
+
+`client.runs.create({ ..., stream: true })` streams the run's events.
+
+## Connected apps: saving into a person's Workspace
+
+With the person's approval, an application can save into their Dyadic
+Workspace, naming them by the Discord account linked to their Dyadic account.
+
+```ts
+const status = await client.connections.discord(discordId);
+if (!status.authorized) console.log("Allow this app:", status.authorize_url); // show the person this link
+
+try {
+  const saved = await client.workspace.saves.create({ discord_id: discordId, kind: "message", title: "From #general",
+    text: "Worth keeping", url: "https://discord.com/channels/1/2/3" });
+  console.log(saved.url);
+} catch (error) {
+  if (error instanceof DyadicError && error.code === "authorization_required") console.log("Allow this app:", error.body.authorize_url);
+}
+```
+
+`kind` is `message`, `conversation` (with `messages`, saved as a chat the
+person can continue unless `as_chat: false`), `image` or `file` (with `files`:
+base64, up to 10 of 8 MB).
+
+Full guide: https://dyadic.app/developers/

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";
@@ -455,12 +455,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 +526,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;
@@ -667,8 +678,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,
@@ -219,51 +244,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 +344,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",
-  "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"],
-  "engines": { "node": ">=18" },
-  "license": "MIT",
-  "homepage": "https://dyadic.app/developers/",
-  "scripts": { "build": "tsc", "test": "node --test test/client.test.js" },
-  "devDependencies": { "typescript": "5.6.3" }
-}
+{
+  "name": "dyadic",
+  "version": "1.2.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", "CHANGELOG.md"],
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "homepage": "https://dyadic.app/developers/",
+  "scripts": { "build": "tsc", "pretest": "tsc", "test": "node --test test/client.test.js test/transport.test.js", "prepack": "tsc" },
+  "devDependencies": { "typescript": "5.6.3" }
+}