dyadic 1.0.0

package/README.md

@@ -0,0 +1,16 @@
+# 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/

package/dist/index.d.ts

@@ -0,0 +1,540 @@
+export declare const VERSION = "1.0.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";
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+} | {
+    type: "file";
+    file: {
+        file_id?: string;
+        filename?: string;
+        file_data?: string;
+    };
+} | {
+    type: "input_audio";
+    input_audio: {
+        data: string;
+        format: "wav" | "mp3";
+    };
+};
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ChatMessage {
+    role: Role;
+    content: string | ContentPart[] | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+export interface Tool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        strict?: boolean;
+    };
+}
+export interface GenerationParams {
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    min_p?: number;
+    top_a?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    repetition_penalty?: number;
+    seed?: number;
+    logit_bias?: Record<string, number>;
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    stop?: string | string[];
+    reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    logprobs?: boolean;
+    top_logprobs?: number;
+    user?: string;
+    stream_options?: {
+        include_usage?: boolean;
+    };
+}
+export interface ChatCompletionParams extends GenerationParams {
+    model: Model;
+    messages: ChatMessage[];
+    tools?: Tool[];
+    tool_choice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    parallel_tool_calls?: boolean;
+    response_format?: {
+        type: "text" | "json_object" | "json_schema";
+        json_schema?: Record<string, unknown>;
+    };
+    stream?: boolean;
+}
+export interface CompletionParams extends GenerationParams {
+    model: Model;
+    prompt: string;
+    stream?: boolean;
+}
+export interface BillingInfo {
+    credits?: number;
+    credits_final?: boolean;
+    request_id?: string;
+    log_id?: string;
+}
+export interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    dyadic?: BillingInfo;
+}
+export interface ChatCompletion {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: {
+        index: number;
+        finish_reason: string;
+        logprobs: unknown;
+        message: {
+            role: "assistant";
+            content: string | null;
+            reasoning_content?: string;
+            tool_calls?: ToolCall[];
+        };
+    }[];
+    usage: Usage;
+    dyadic?: BillingInfo;
+}
+export interface ChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    usage?: Usage;
+    choices: {
+        index: number;
+        finish_reason: string | null;
+        logprobs?: unknown;
+        delta: {
+            role?: string;
+            content?: string;
+            reasoning_content?: string;
+            tool_calls?: {
+                index: number;
+                id?: string;
+                type?: "function";
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }[];
+        };
+    }[];
+}
+export interface TextCompletion {
+    id: string;
+    object: "text_completion";
+    created: number;
+    model: string;
+    choices: {
+        text: string;
+        index: number;
+        finish_reason: string | null;
+    }[];
+    usage?: Usage;
+    dyadic?: BillingInfo;
+}
+export interface ModelInfo {
+    id: string;
+    object: "model";
+    created: number;
+    owned_by: string;
+    name?: string;
+    description?: string;
+}
+export interface ImageParams {
+    prompt: string;
+    model?: Model;
+    size?: string;
+    quality?: "standard" | "hd" | "high" | "max";
+    n?: 1;
+}
+export interface ImageResponse {
+    created: number;
+    data: {
+        b64_json?: string;
+        url?: string;
+        revised_prompt?: string;
+    }[];
+}
+export interface ResponseParams {
+    model: Model;
+    input: string | Record<string, unknown>[];
+    instructions?: string;
+    previous_response_id?: string;
+    store?: boolean;
+    tools?: Record<string, unknown>[];
+    tool_choice?: unknown;
+    parallel_tool_calls?: boolean;
+    text?: {
+        format?: Record<string, unknown>;
+    };
+    reasoning?: {
+        effort?: "minimal" | "low" | "medium" | "high";
+        summary?: string;
+    };
+    max_output_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    top_logprobs?: number;
+    metadata?: Record<string, string>;
+    user?: string;
+    safety_identifier?: string;
+    stream?: boolean;
+}
+export interface ResponseObject {
+    id: string;
+    object: "response";
+    created_at: number;
+    status: "completed" | "incomplete" | "failed" | "in_progress";
+    model: string;
+    output: {
+        type: string;
+        id?: string;
+        role?: string;
+        content?: {
+            type: string;
+            text?: string;
+        }[];
+        call_id?: string;
+        name?: string;
+        arguments?: string;
+    }[];
+    output_text?: string;
+    previous_response_id: string | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+    } | null;
+    metadata: Record<string, string>;
+}
+export interface ResponseEvent {
+    type: string;
+    sequence_number: number;
+    delta?: string;
+    response?: ResponseObject;
+    [key: string]: unknown;
+}
+export interface EmbeddingParams {
+    model: "text-embedding-3-small" | "text-embedding-3-large" | "text-embedding-ada-002" | (string & {});
+    input: string | string[];
+    dimensions?: number;
+    encoding_format?: "float" | "base64";
+    user?: string;
+}
+export interface EmbeddingList {
+    object: "list";
+    model: string;
+    data: {
+        object: "embedding";
+        index: number;
+        embedding: number[] | string;
+    }[];
+    usage: {
+        prompt_tokens: number;
+        total_tokens: number;
+    };
+}
+export interface SpeechParams {
+    model: "tts-1" | "tts-1-hd" | "gpt-4o-mini-tts" | (string & {});
+    voice: string;
+    input: string;
+    response_format?: "mp3" | "wav" | "pcm";
+    speed?: number;
+    instructions?: string;
+}
+/** A file to upload: a Blob or File, bytes, or { name, data, type }. In Node, `await fs.openAsBlob(path)` reads one from disk. */
+export type Uploadable = Blob | Uint8Array | ArrayBuffer | {
+    name: string;
+    data: Blob | Uint8Array | ArrayBuffer | string;
+    type?: string;
+};
+export interface TranscriptionParams {
+    file: Uploadable;
+    model: "whisper-1" | "gpt-4o-transcribe" | "gpt-4o-mini-transcribe" | (string & {});
+    language?: string;
+    prompt?: string;
+    response_format?: "json" | "text" | "srt" | "verbose_json" | "vtt";
+    temperature?: number;
+    timestamp_granularities?: ("word" | "segment")[];
+}
+export interface Transcription {
+    text: string;
+    language?: string;
+    duration?: number;
+    segments?: unknown[];
+    words?: unknown[];
+    usage?: Record<string, unknown>;
+}
+export interface Moderation {
+    id: string;
+    model: string;
+    results: {
+        flagged: boolean;
+        categories: Record<string, boolean>;
+        category_scores: Record<string, number>;
+        category_applied_input_types: Record<string, string[]>;
+    }[];
+}
+export interface FileObject {
+    id: string;
+    object: "file";
+    bytes: number;
+    created_at: number;
+    filename: string;
+    purpose: string;
+    status: string;
+    expires_at: number | null;
+}
+export interface Page<T> {
+    object: "list";
+    data: T[];
+    first_id: string | null;
+    last_id: string | null;
+    has_more: boolean;
+}
+export interface Batch {
+    id: string;
+    object: "batch";
+    endpoint: string;
+    status: "validating" | "failed" | "in_progress" | "finalizing" | "completed" | "expired" | "cancelling" | "cancelled";
+    input_file_id: string;
+    output_file_id: string | null;
+    error_file_id: string | null;
+    errors: unknown;
+    completion_window: string;
+    request_counts: {
+        total: number;
+        completed: number;
+        failed: number;
+    };
+    created_at: number;
+    completed_at: number | null;
+    expires_at: number | null;
+    metadata: Record<string, string>;
+}
+export interface RequestOptions {
+    form?: FormData;
+    query?: Record<string, string | number | undefined>;
+    raw?: boolean;
+}
+/** Bytes from the API (speech audio, file downloads). */
+export declare class Binary {
+    readonly data: ArrayBuffer;
+    readonly contentType: string;
+    readonly requestId: string;
+    constructor(data: ArrayBuffer, contentType: string, requestId?: string);
+    bytes(): Uint8Array;
+    text(): string;
+    blob(): Blob;
+    get size(): number;
+}
+export interface ClientOptions {
+    apiKey?: string;
+    baseURL?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    appName?: string;
+    fetch?: typeof fetch;
+}
+/** An error from the API, in OpenAI's shape (status 0 for a network failure). */
+export declare class DyadicError extends Error {
+    status: number;
+    type: string;
+    code: string | null;
+    param: string | null;
+    requestId: string;
+    body: unknown;
+    constructor(message: string, init?: {
+        status?: number;
+        type?: string;
+        code?: string | null;
+        param?: string | null;
+        requestId?: string;
+        body?: unknown;
+    });
+}
+/** A streamed completion: `for await (const chunk of stream)`. `text` and `usage` fill in as it goes. */
+export declare class Stream<T> implements AsyncIterable<T> {
+    private http;
+    readonly controller: AbortController;
+    private onDone;
+    text: string;
+    usage: Usage | undefined;
+    /** Responses streams: the final Response once response.completed arrives. */
+    response: ResponseObject | undefined;
+    readonly requestId: string;
+    constructor(http: Response, controller: AbortController, onDone?: () => void);
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /** Read to the end and return the whole text. */
+    finalText(): Promise<string>;
+    abort(): void;
+}
+export declare class Dyadic {
+    readonly apiKey: string;
+    readonly baseURL: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly appName?: 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. */
+    request<T>(method: string, path: string, body?: unknown, stream?: boolean, options?: RequestOptions): Promise<T>;
+    readonly models: {
+        list: () => Promise<{
+            object: "list";
+            data: ModelInfo[];
+        }>;
+        retrieve: (model: Model) => Promise<ModelInfo>;
+    };
+    readonly chat: {
+        completions: {
+            create: {
+                (params: ChatCompletionParams & {
+                    stream: true;
+                }): Promise<Stream<ChatCompletionChunk>>;
+                (params: ChatCompletionParams & {
+                    stream?: false;
+                }): Promise<ChatCompletion>;
+                (params: ChatCompletionParams): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
+            };
+        };
+    };
+    readonly completions: {
+        create: {
+            (params: CompletionParams & {
+                stream: true;
+            }): Promise<Stream<TextCompletion>>;
+            (params: CompletionParams & {
+                stream?: false;
+            }): Promise<TextCompletion>;
+        };
+    };
+    readonly responses: {
+        create: {
+            (params: ResponseParams & {
+                stream: true;
+            }): Promise<Stream<ResponseEvent>>;
+            (params: ResponseParams & {
+                stream?: false;
+            }): Promise<ResponseObject>;
+        };
+        retrieve: (id: string) => Promise<ResponseObject>;
+        delete: (id: string) => Promise<{
+            id: string;
+            object: "response.deleted";
+            deleted: boolean;
+        }>;
+        inputItems: (id: string, query?: {
+            limit?: number;
+            after?: string;
+            order?: "asc" | "desc";
+        }) => Promise<Page<Record<string, unknown>>>;
+        cancel: (id: string) => Promise<ResponseObject>;
+    };
+    readonly embeddings: {
+        create: (params: EmbeddingParams) => Promise<EmbeddingList>;
+    };
+    readonly audio: {
+        speech: {
+            create: (params: SpeechParams) => Promise<Binary>;
+        };
+        transcriptions: {
+            create: ({ file, ...params }: TranscriptionParams) => Promise<string | Transcription>;
+        };
+        translations: {
+            create: ({ file, ...params }: Omit<TranscriptionParams, "language" | "timestamp_granularities">) => Promise<string | Transcription>;
+        };
+    };
+    readonly moderations: {
+        create: (params: {
+            input: string | string[] | ContentPart[];
+            model?: string;
+        }) => Promise<Moderation>;
+    };
+    readonly images: {
+        generate: (params: ImageParams) => Promise<ImageResponse>;
+        edit: ({ image, ...params }: Omit<ImageParams, "model"> & {
+            image: Uploadable;
+        }) => Promise<ImageResponse>;
+        createVariation: ({ image, ...params }: Omit<ImageParams, "prompt" | "model"> & {
+            image: Uploadable;
+        }) => Promise<ImageResponse>;
+    };
+    readonly files: {
+        create: (params: {
+            file: Uploadable;
+            purpose: "batch" | "user_data" | "assistants" | "vision" | (string & {});
+        }) => Promise<FileObject>;
+        list: (query?: {
+            purpose?: string;
+            limit?: number;
+            after?: string;
+            order?: "asc" | "desc";
+        }) => Promise<Page<FileObject>>;
+        retrieve: (id: string) => Promise<FileObject>;
+        delete: (id: string) => Promise<{
+            id: string;
+            object: "file";
+            deleted: boolean;
+        }>;
+        content: (id: string) => Promise<Binary>;
+    };
+    readonly batches: {
+        create: (params: {
+            input_file_id: string;
+            endpoint: string;
+            completion_window?: "24h";
+            metadata?: Record<string, string>;
+        }) => Promise<Batch>;
+        list: (query?: {
+            limit?: number;
+            after?: string;
+        }) => Promise<Page<Batch>>;
+        retrieve: (id: string) => Promise<Batch>;
+        cancel: (id: string) => Promise<Batch>;
+    };
+    /** One question, one answer: the reply's text. */
+    ask(prompt: string, options?: Omit<ChatCompletionParams, "messages" | "model" | "stream"> & {
+        model?: Model;
+        system?: string;
+    }): Promise<string>;
+    /** The API's OpenAPI description. */
+    openapi(): Promise<Record<string, unknown>>;
+}
+export default Dyadic;

package/dist/index.js

@@ -0,0 +1,246 @@
+// 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 DEFAULT_BASE_URL = "https://dyadic.app/api/openai/v1";
+/** Bytes from the API (speech audio, file downloads). */
+export class Binary {
+    constructor(data, contentType, requestId = "") {
+        this.data = data;
+        this.contentType = contentType;
+        this.requestId = requestId;
+    }
+    bytes() { return new Uint8Array(this.data); }
+    text() { return new TextDecoder().decode(this.data); }
+    blob() { return new Blob([this.data], { type: this.contentType }); }
+    get size() { return this.data.byteLength; }
+}
+function toBlob(file, fallback) {
+    if (typeof Blob !== "undefined" && file instanceof Blob)
+        return [file, file.name || fallback];
+    if (file instanceof Uint8Array || file instanceof ArrayBuffer)
+        return [new Blob([file]), fallback];
+    const named = file;
+    const data = named.data instanceof Blob ? named.data : new Blob([named.data], named.type ? { type: named.type } : {});
+    return [data, named.name || fallback];
+}
+function form(fields, files) {
+    const out = new FormData();
+    for (const [name, [file, fallback]] of Object.entries(files)) {
+        const [blob, filename] = toBlob(file, fallback);
+        out.append(name, blob, filename);
+    }
+    for (const [name, value] of Object.entries(fields)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value))
+            for (const item of value)
+                out.append(name.endsWith("[]") ? name : `${name}[]`, String(item));
+        else
+            out.append(name, String(value));
+    }
+    return out;
+}
+/** An error from the API, in OpenAI's shape (status 0 for a network failure). */
+export class DyadicError extends Error {
+    constructor(message, init = {}) {
+        super(message);
+        this.name = "DyadicError";
+        this.status = init.status ?? 0;
+        this.type = init.type ?? "";
+        this.code = init.code ?? null;
+        this.param = init.param ?? null;
+        this.requestId = init.requestId ?? "";
+        this.body = init.body;
+    }
+}
+/** A streamed completion: `for await (const chunk of stream)`. `text` and `usage` fill in as it goes. */
+export class Stream {
+    constructor(http, controller, onDone = () => { }) {
+        this.http = http;
+        this.controller = controller;
+        this.onDone = onDone;
+        this.text = "";
+        this.requestId = http.headers.get("x-request-id") ?? "";
+    }
+    async *[Symbol.asyncIterator]() {
+        const reader = this.http.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    return;
+                buffer += decoder.decode(value, { stream: true });
+                let index;
+                while ((index = buffer.indexOf("\n\n")) >= 0) {
+                    const frame = buffer.slice(0, index);
+                    buffer = buffer.slice(index + 2);
+                    const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).join("");
+                    if (!data)
+                        continue;
+                    if (data === "[DONE]")
+                        return;
+                    const chunk = JSON.parse(data);
+                    if (chunk.error)
+                        throw new DyadicError(chunk.error.message, { status: 200, type: chunk.error.type, code: chunk.error.code, body: chunk });
+                    if (chunk.type === "response.failed") {
+                        const failure = chunk.response?.error ?? { message: "The response failed." };
+                        throw new DyadicError(failure.message, { status: 200, code: failure.code ?? null, body: chunk });
+                    }
+                    if (chunk.usage)
+                        this.usage = chunk.usage;
+                    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 ?? "";
+                    yield chunk;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+            this.onDone();
+        }
+    }
+    /** Read to the end and return the whole text. */
+    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]);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class Dyadic {
+    constructor(options = {}) {
+        this.models = {
+            list: () => this.request("GET", "/models"),
+            retrieve: (model) => this.request("GET", `/models/${model}`),
+        };
+        this.chat = {
+            completions: {
+                create: ((params) => {
+                    const body = params.stream ? { stream_options: { include_usage: true }, ...params } : params;
+                    return this.request("POST", "/chat/completions", body, Boolean(params.stream));
+                }),
+            },
+        };
+        this.completions = {
+            create: ((params) => {
+                const body = params.stream ? { stream_options: { include_usage: true }, ...params } : params;
+                return this.request("POST", "/completions", body, Boolean(params.stream));
+            }),
+        };
+        this.responses = {
+            create: ((params) => this.request("POST", "/responses", params, Boolean(params.stream))),
+            retrieve: (id) => this.request("GET", `/responses/${id}`),
+            delete: (id) => this.request("DELETE", `/responses/${id}`),
+            inputItems: (id, query = {}) => this.request("GET", `/responses/${id}/input_items`, undefined, false, { query }),
+            cancel: (id) => this.request("POST", `/responses/${id}/cancel`),
+        };
+        this.embeddings = {
+            create: (params) => this.request("POST", "/embeddings", params),
+        };
+        this.audio = {
+            speech: { create: (params) => this.request("POST", "/audio/speech", params, false, { raw: true }) },
+            transcriptions: {
+                create: ({ file, ...params }) => this.request("POST", "/audio/transcriptions", undefined, false, { form: form(params, { file: [file, "audio"] }) }),
+            },
+            translations: {
+                create: ({ file, ...params }) => this.request("POST", "/audio/translations", undefined, false, { form: form(params, { file: [file, "audio"] }) }),
+            },
+        };
+        this.moderations = {
+            create: (params) => this.request("POST", "/moderations", 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"] }) }),
+            createVariation: ({ image, ...params }) => this.request("POST", "/images/variations", undefined, false, { form: form(params, { image: [image, "image.png"] }) }),
+        };
+        this.files = {
+            create: (params) => this.request("POST", "/files", undefined, false, { form: form({ purpose: params.purpose }, { file: [params.file, "file"] }) }),
+            list: (query = {}) => this.request("GET", "/files", undefined, false, { query }),
+            retrieve: (id) => this.request("GET", `/files/${id}`),
+            delete: (id) => this.request("DELETE", `/files/${id}`),
+            content: (id) => this.request("GET", `/files/${id}/content`, undefined, false, { raw: true }),
+        };
+        this.batches = {
+            create: (params) => this.request("POST", "/batches", { completion_window: "24h", ...params }),
+            list: (query = {}) => this.request("GET", "/batches", undefined, false, { query }),
+            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.
+        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(/\/+$/, "");
+        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. */
+    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 payload = options.form ?? (body === undefined ? undefined : JSON.stringify(body));
+        if (this.appName)
+            headers["X-Title"] = this.appName;
+        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 });
+            }
+            catch (error) {
+                clearTimeout(timer);
+                if (attempt < this.maxRetries) {
+                    await sleep(500 * 2 ** attempt);
+                    continue;
+                }
+                throw new DyadicError(`Could not reach the Dyadic API: ${error.message}`);
+            }
+            if (!stream)
+                clearTimeout(timer);
+            if (response.ok) {
+                if (stream)
+                    return new Stream(response, controller, () => clearTimeout(timer));
+                const kind = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+                if (!options.raw && (kind === "application/json" || kind.endsWith("+json")))
+                    return await response.json();
+                if (!options.raw && kind.startsWith("text/"))
+                    return await response.text();
+                return new Binary(await response.arrayBuffer(), kind, response.headers.get("x-request-id") ?? "");
+            }
+            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 after = Number(response.headers.get("retry-after"));
+                await sleep(Number.isFinite(after) && after > 0 ? Math.min(after, 30) * 1000 : 500 * 2 ** attempt);
+                continue;
+            }
+            throw new DyadicError(error.message ?? `HTTP ${response.status}`, { status: response.status, type: error.type, code: error.code, param: error.param,
+                requestId: response.headers.get("x-request-id") ?? "", body: data });
+        }
+    }
+    /** One question, one answer: the reply's text. */
+    async ask(prompt, options = {}) {
+        const { model = "iris", system, ...params } = options;
+        const messages = [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: prompt }];
+        const reply = await this.chat.completions.create({ ...params, model, messages, stream: false });
+        return reply.choices[0]?.message.content ?? "";
+    }
+    /** The API's OpenAPI description. */
+    openapi() { return this.request("GET", "/openapi.json"); }
+}
+export default Dyadic;

package/package.json

@@ -0,0 +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" }
+}