dyadic 1.0.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,16 +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" }));
-```
-
-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.0.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";
@@ -347,10 +347,124 @@ export interface Batch {
     expires_at: number | null;
     metadata: Record<string, string>;
 }
+/** Dyadic's built-in tools an application's run may use. */
+export type BuiltinTool = "data.web_search" | "data.web_fetch" | "image.generate" | "vision.describe_image";
+/** Your own agent, sent with the run: its name and instructions, optional
+ * behaviour overrides (tool_rules, safety, style, citations, research: text to
+ * replace the default, or false to turn it off) and model choices. */
+export interface AgentConfig {
+    id: string;
+    name: string;
+    instructions?: string;
+    behaviour?: Record<string, string | false>;
+    models?: Record<string, string>;
+    tools?: Record<string, boolean>;
+}
+export interface RunParams {
+    agent: string | AgentConfig;
+    messages: ChatMessage[];
+    builtin_tools?: BuiltinTool[];
+    functions?: Tool[];
+    end_user?: string;
+    conversation_id?: string;
+    max_tokens?: number;
+    temperature?: number;
+    think?: boolean;
+    research?: "auto" | "deep";
+    stream?: boolean;
+    /** Your own cap on what this run may spend, in USD (for example what your user has left). */
+    max_cost_usd?: number;
+    /** Ask for up to four suggested follow-up questions (`followups` on the completed run). */
+    followups?: boolean;
+}
+export interface Run {
+    object: "run";
+    type: "run.completed";
+    run_id: string;
+    status: "completed" | "requires_action";
+    agent: string;
+    output_text: string;
+    function_calls: ToolCall[];
+    messages: ChatMessage[];
+    images: {
+        url: string;
+        prompt?: string;
+        quality?: string;
+    }[];
+    sources: {
+        title?: string;
+        url: string;
+    }[];
+    tools: string[];
+    model: string;
+    models: string[];
+    usage: Usage;
+    credits: number;
+    cost_usd: number;
+    estimated: boolean;
+    model_calls: number;
+    operation_id: string;
+    seconds: number;
+    log_id?: string;
+    followups?: string[];
+}
+export interface RunEvent {
+    type: string;
+    [key: string]: unknown;
+}
+/** A function your application runs: its schema and the handler called with the parsed arguments. */
+export interface FunctionHandler {
+    description?: string;
+    parameters?: Record<string, unknown>;
+    handler: (args: any) => unknown | Promise<unknown>;
+}
+/** Connected apps: whether the person with a linked identity approved this application. */
+export interface Connection {
+    linked: boolean;
+    authorized: boolean;
+    scopes?: string[];
+    authorize_url?: string;
+    link_url?: string;
+}
+export interface SaveFile {
+    name?: string;
+    media_type?: string;
+    data: string;
+}
+export interface SaveMessage {
+    role: "user" | "assistant";
+    name?: string;
+    text: string;
+    url?: string;
+}
+export interface WorkspaceSaveParams {
+    discord_id: string | number;
+    kind: "message" | "conversation" | "image" | "file";
+    title?: string;
+    text?: string;
+    messages?: SaveMessage[];
+    as_chat?: boolean;
+    files?: SaveFile[];
+    url?: string;
+    source?: Record<string, unknown>;
+}
+export interface WorkspaceSave {
+    saved: {
+        type: "reference" | "chat" | "file";
+        id: string;
+    }[];
+    url: string;
+}
+/** `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 {
@@ -397,6 +511,8 @@ export declare class Stream<T> implements AsyncIterable<T> {
     usage: Usage | undefined;
     /** Responses streams: the final Response once response.completed arrives. */
     response: ResponseObject | undefined;
+    /** Run streams: the completed run once run.completed arrives. */
+    run: Run | undefined;
     readonly requestId: string;
     constructor(http: Response, controller: AbortController, onDone?: () => void);
     [Symbol.asyncIterator](): AsyncIterator<T>;
@@ -410,11 +526,39 @@ 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;
+    /** An agent answers a conversation: one of the account's agents by id ("iris") or your own agent inline,
+     * with Dyadic's built-in tools and your own functions. A run that calls your functions ends with status
+     * "requires_action": run `function_calls`, append `messages` and your results, and run again (or use `run`). */
+    readonly runs: {
+        create: {
+            (params: RunParams & {
+                stream: true;
+            }): Promise<Stream<RunEvent>>;
+            (params: RunParams & {
+                stream?: false;
+            }): Promise<Run>;
+        };
+        /** Run to completion, calling your functions whenever the agent asks. The result's `messages` hold
+         * everything the run added, ready to append to your conversation. */
+        run: (params: Omit<RunParams, "functions" | "stream"> & {
+            functions?: Record<string, FunctionHandler>;
+            maxRounds?: number;
+        }) => Promise<Run>;
+    };
     readonly models: {
         list: () => Promise<{
             object: "list";
@@ -529,6 +673,18 @@ export declare class Dyadic {
         retrieve: (id: string) => Promise<Batch>;
         cancel: (id: string) => Promise<Batch>;
     };
+    /** Connected apps. Show the person `authorize_url` when `authorized` is false. */
+    readonly connections: {
+        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`),
+     * whether or not they have a Dyadic account yet. */
+    readonly workspace: {
+        saves: {
+            create: ({ discord_id, ...fields }: WorkspaceSaveParams) => Promise<WorkspaceSave>;
+        };
+    };
     /** One question, one answer: the reply's text. */
     ask(prompt: string, options?: Omit<ChatCompletionParams, "messages" | "model" | "stream"> & {
         model?: Model;

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.0.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 {
@@ -90,12 +90,18 @@ export class Stream {
                     }
                     if (chunk.usage)
                         this.usage = chunk.usage;
+                    if (chunk.type === "run.completed") {
+                        this.run = chunk;
+                        yield chunk;
+                        continue;
+                    }
                     if ((chunk.type === "response.completed" || chunk.type === "response.incomplete") && chunk.response) {
                         this.response = chunk.response;
                         this.usage = chunk.response.usage ?? undefined;
                     }
                     const choice = chunk.choices?.[0];
-                    this.text += chunk.type === "response.output_text.delta" ? chunk.delta ?? "" : choice?.delta?.content ?? choice?.text ?? "";
+                    this.text += chunk.type === "response.output_text.delta" ? chunk.delta ?? "" : chunk.type === "delta" ? chunk.text ?? ""
+                        : choice?.delta?.content ?? choice?.text ?? "";
                     yield chunk;
                 }
             }
@@ -109,10 +115,72 @@ 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]);
+// 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,
+         * with Dyadic's built-in tools and your own functions. A run that calls your functions ends with status
+         * "requires_action": run `function_calls`, append `messages` and your results, and run again (or use `run`). */
+        this.runs = {
+            create: ((params) => this.request("POST", this.platformURL("/runs"), params, Boolean(params.stream), { executes: true })),
+            /** Run to completion, calling your functions whenever the agent asks. The result's `messages` hold
+             * everything the run added, ready to append to your conversation. */
+            run: async (params) => {
+                const { functions = {}, maxRounds = 8, ...rest } = params;
+                const schemas = Object.entries(functions).map(([name, f]) => ({ type: "function", function: { name, description: f.description ?? "", parameters: f.parameters ?? { type: "object", properties: {} } } }));
+                const conversation = [...rest.messages];
+                const added = [];
+                for (let round = 0; round < maxRounds; round++) {
+                    const result = await this.runs.create({ ...rest, messages: conversation, functions: schemas.length ? schemas : undefined, stream: false });
+                    if (result.status !== "requires_action")
+                        return { ...result, messages: [...added, { role: "assistant", content: result.output_text }] };
+                    const step = [...result.messages];
+                    for (const call of result.function_calls) {
+                        let args = {};
+                        try {
+                            args = JSON.parse(call.function.arguments || "{}");
+                        }
+                        catch {
+                            args = {};
+                        }
+                        const fn = functions[call.function.name];
+                        const output = fn ? await fn.handler(args) : { error: "unknown function" };
+                        step.push({ role: "tool", tool_call_id: call.id, content: typeof output === "string" ? output : JSON.stringify(output) });
+                    }
+                    conversation.push(...step);
+                    added.push(...step);
+                }
+                throw new DyadicError(`The run still wanted functions after ${maxRounds} rounds.`);
+            },
+        };
         this.models = {
             list: () => this.request("GET", "/models"),
             retrieve: (model) => this.request("GET", `/models/${model}`),
@@ -171,44 +239,96 @@ export class Dyadic {
             retrieve: (id) => this.request("GET", `/batches/${id}`),
             cancel: (id) => this.request("POST", `/batches/${id}/cancel`),
         };
-        // process.env where it exists (Node, Bun, Deno with compat); browsers pass apiKey.
+        /** Connected apps. Show the person `authorize_url` when `authorized` is false. */
+        this.connections = {
+            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`),
+         * 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). 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 = `${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) {
+                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) {
@@ -224,7 +344,8 @@ export class Dyadic {
             clearTimeout(timer);
             const data = await response.json().catch(() => ({ error: { message: `HTTP ${response.status}` } }));
             const error = data?.error ?? {};
-            if (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;
@@ -233,6 +354,8 @@ export class Dyadic {
                 requestId: response.headers.get("x-request-id") ?? "", body: data });
         }
     }
+    /** Dyadic's own endpoints sit beside the OpenAI-compatible base: .../api/openai/v1 -> .../api/v1. */
+    platformURL(path) { return this.baseURL.replace(/\/openai(\/v1)?$/, "/v1") + path; }
     /** One question, one answer: the reply's text. */
     async ask(prompt, options = {}) {
         const { model = "iris", system, ...params } = options;

package/package.json

@@ -1,15 +1,15 @@
-{
-  "name": "dyadic",
-  "version": "1.0.0",
-  "description": "The official TypeScript and JavaScript SDK for the Dyadic API (Iris, OpenAI-compatible).",
-  "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" }
+}