@promptev/client 0.1.0 → 1.0.0

package/dist/cjs/index.cjs

@@ -1,55 +1,115 @@
 "use strict";
-// ── Types ───────────────────────────────────────────────
+/**
+ * @promptev/client — the official JavaScript/TypeScript client for Promptev.
+ *
+ * 1.0 talks to Promptev's `/api/v1` surface, authenticated with a workspace
+ * API key (`fk_…`) sent as a Bearer token. The key is bound to ONE project and
+ * carries its own retrieval identity, so what a caller may read is part of the
+ * credential rather than a parameter on the call.
+ *
+ * Two methods:
+ *   - `chat()`            — stream a turn from an agent (SSE).
+ *   - `uploadDocument()`  — put files into the key's project corpus.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PromptevClient = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.NotFoundError = exports.AuthenticationError = exports.ValidationError = exports.PromptevError = void 0;
+exports.PromptevClient = exports.NetworkError = exports.ServerError = exports.InsufficientCreditsError = exports.RateLimitError = exports.NotFoundError = exports.AuthenticationError = exports.ValidationError = exports.PromptevError = exports.MAX_FILES_PER_RUN = exports.MAX_UPLOAD_BYTES = exports.MAX_FILES_PER_REQUEST = exports.MAX_MESSAGE_CHARS = exports.DEFAULT_BASE_URL = void 0;
+// ── Configuration ───────────────────────────────────────
+/**
+ * The default host. NOT `api.promptev.ai` — that host still serves the
+ * previous product and would answer 404 for every `/api/v1` path here.
+ * FLIP THIS the day `api.promptev.ai` is repointed at the console backend.
+ */
+/**
+ * Where the client talks by default.
+ *
+ * `api.promptev.ai` is the API's permanent home. At the time 1.0 was written
+ * that host still served the PREVIOUS product, and it is being repointed at
+ * the new backend — so this default is correct for where things are going and
+ * must not ship to npm before the DNS moves. Point `baseUrl` at
+ * `https://console.promptev.ai` in the meantime, or at your own host if you
+ * run Promptev yourself.
+ */
+exports.DEFAULT_BASE_URL = "https://api.promptev.ai";
+/** The server's own ceiling on one message (`ApiChatBody.message`). */
+exports.MAX_MESSAGE_CHARS = 20000;
+/** `uploads.MAX_FILES_PER_REQUEST` — files in ONE upload request. */
+exports.MAX_FILES_PER_REQUEST = 20;
+/** `file_types.MAX_UPLOAD_BYTES` — 25 MB per file. */
+exports.MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+/** Files ONE orchestration run may carry — the same ceiling a chat turn has.
+ *  Server-side: `run_inputs.MAX_FILE_PARTS`. */
+exports.MAX_FILES_PER_RUN = 5;
 // ── Errors ──────────────────────────────────────────────
 class PromptevError extends Error {
-    constructor(message, statusCode, responseText) {
+    constructor(message, statusCode, responseText, field) {
         super(message);
         this.name = "PromptevError";
         this.statusCode = statusCode;
         this.responseText = responseText;
+        this.field = field;
     }
 }
 exports.PromptevError = PromptevError;
+/** 400/422 — the request itself was wrong. `field` says which part. */
 class ValidationError extends PromptevError {
-    constructor(message, statusCode, responseText) {
-        super(message, statusCode, responseText);
+    constructor() {
+        super(...arguments);
         this.name = "ValidationError";
     }
 }
 exports.ValidationError = ValidationError;
+/** 401/403 — the key is missing, malformed, revoked or expired. */
 class AuthenticationError extends PromptevError {
-    constructor(message, statusCode, responseText) {
-        super(message, statusCode, responseText);
+    constructor() {
+        super(...arguments);
         this.name = "AuthenticationError";
     }
 }
 exports.AuthenticationError = AuthenticationError;
+/**
+ * 404 — no such agent, OR an agent your key cannot reach, OR one that has
+ * never been published. All three answer identically on purpose: a key holder
+ * learns nothing about projects it was not given.
+ */
 class NotFoundError extends PromptevError {
-    constructor(message, statusCode, responseText) {
-        super(message, statusCode, responseText);
+    constructor() {
+        super(...arguments);
         this.name = "NotFoundError";
     }
 }
 exports.NotFoundError = NotFoundError;
+/** 429 — too many requests. `retryAfter` is the server's own answer, in seconds. */
 class RateLimitError extends PromptevError {
-    constructor(message, statusCode, responseText) {
-        super(message, statusCode, responseText);
+    constructor(message, statusCode, responseText, field, retryAfter) {
+        super(message, statusCode, responseText, field);
         this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
     }
 }
 exports.RateLimitError = RateLimitError;
+/**
+ * 402 — the workspace is out of credits. Not a rate limit: waiting does not
+ * fix it, a top-up does.
+ */
+class InsufficientCreditsError extends PromptevError {
+    constructor() {
+        super(...arguments);
+        this.name = "InsufficientCreditsError";
+    }
+}
+exports.InsufficientCreditsError = InsufficientCreditsError;
+/** 5xx — the server failed, after the client's retries were exhausted. */
 class ServerError extends PromptevError {
-    constructor(message, statusCode, responseText) {
-        super(message, statusCode, responseText);
+    constructor() {
+        super(...arguments);
         this.name = "ServerError";
     }
 }
 exports.ServerError = ServerError;
+/** The request never got an answer: DNS, connection, abort, or the client timeout. */
 class NetworkError extends PromptevError {
-    constructor(message, statusCode, responseText) {
-        super(message, statusCode, responseText);
+    constructor() {
+        super(...arguments);
         this.name = "NetworkError";
     }
 }
@@ -60,67 +120,84 @@ const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_BACKOFF = 500; // ms
 class PromptevClient {
     constructor(config) {
-        this.projectKey = config.projectKey;
-        this.baseUrl = (config.baseUrl ?? "https://api.promptev.ai").replace(/\/+$/, "");
-        this.headers = {
-            "Content-Type": "application/json",
-            ...(config.headers ?? {}),
-        };
+        if (!config || !config.apiKey || !String(config.apiKey).trim()) {
+            throw new ValidationError("Pass your Promptev API key: new PromptevClient({ apiKey: 'fk_…' }).", undefined, undefined, "apiKey");
+        }
+        this.apiKey = String(config.apiKey).trim();
+        this.baseUrl = (config.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.headers = { ...(config.headers ?? {}) };
         this.timeout = config.timeout ?? 30000;
         this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
     }
     // ── Error handling ──────────────────────────────────
-    static raiseForStatus(status, text) {
+    /**
+     * Every refusal on `/api/v1` is `{"error": {"message", "field"?}}`. The
+     * older `{"detail": …}` shape is still read as a fallback, so a proxy or an
+     * un-migrated route can never produce an empty message.
+     */
+    static raiseForStatus(status, text, headers) {
         if (status < 400)
             return;
-        let detail;
+        let detail = text || "Unknown error";
+        let field;
         try {
             const body = JSON.parse(text);
-            detail =
-                typeof body.detail === "string" ? body.detail : text || "Unknown error";
+            const err = body?.error;
+            if (err && typeof err === "object") {
+                if (typeof err.message === "string")
+                    detail = err.message;
+                if (typeof err.field === "string")
+                    field = err.field;
+            }
+            else if (typeof body?.detail === "string") {
+                detail = body.detail;
+            }
         }
         catch {
-            detail = text || "Unknown error";
+            /* not JSON — the raw body is the best message there is */
         }
-        if (status === 400)
-            throw new ValidationError(detail, status, text);
-        if (status === 401)
-            throw new AuthenticationError(detail, status, text);
-        if (status === 403)
-            throw new AuthenticationError(detail, status, text);
+        if (status === 400 || status === 422)
+            throw new ValidationError(detail, status, text, field);
+        if (status === 401 || status === 403)
+            throw new AuthenticationError(detail, status, text, field);
+        if (status === 402)
+            throw new InsufficientCreditsError(detail, status, text, field);
         if (status === 404)
-            throw new NotFoundError(detail, status, text);
-        if (status === 429)
-            throw new RateLimitError(detail, status, text);
+            throw new NotFoundError(detail, status, text, field);
+        if (status === 429) {
+            const raw = headers?.get("retry-after");
+            const seconds = raw != null && raw !== "" ? Number(raw) : NaN;
+            throw new RateLimitError(detail, status, text, field, Number.isFinite(seconds) ? seconds : undefined);
+        }
         if (status >= 500)
-            throw new ServerError(detail, status, text);
-        throw new PromptevError(detail, status, text);
+            throw new ServerError(detail, status, text, field);
+        throw new PromptevError(detail, status, text, field);
+    }
+    authHeaders(extra) {
+        // Authorization goes on AFTER the caller's headers: a stray `Authorization`
+        // in `config.headers` must not be able to displace the key silently.
+        return {
+            ...this.headers,
+            Authorization: `Bearer ${this.apiKey}`,
+            ...(extra ?? {}),
+        };
     }
     // ── Retry helper ────────────────────────────────────
     async fetchWithRetry(url, init) {
         let lastError = null;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
             try {
-                const controller = new AbortController();
-                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-                const resp = await fetch(url, {
-                    ...init,
-                    signal: controller.signal,
-                });
-                clearTimeout(timeoutId);
+                const resp = await this.fetchOnce(url, init);
                 if (!RETRYABLE_STATUS.has(resp.status) || attempt === this.maxRetries) {
                     return resp;
                 }
                 lastError = new ServerError(`Server error (${resp.status})`, resp.status);
             }
             catch (err) {
-                if (err.name === "AbortError") {
-                    lastError = new NetworkError("Request timed out");
-                }
-                else {
-                    lastError = new NetworkError(`Network error: ${err.message}`);
-                }
-                if (attempt === this.maxRetries)
+                lastError = err;
+                // A caller who aborted wants the call to STOP, not to be tried again.
+                const caller = init.signal;
+                if (caller?.aborted || attempt === this.maxRetries)
                     throw lastError;
             }
             const delay = DEFAULT_BACKOFF * Math.pow(2, attempt);
@@ -128,8 +205,50 @@ class PromptevClient {
         }
         throw lastError;
     }
+    /**
+     * One `fetch`, with the client timeout applied to the RESPONSE only.
+     *
+     * The timer is cleared the moment the response resolves, which is what lets
+     * a `chat()` stream run for minutes — a tool call, or a human deciding an
+     * approval, is not a stalled request.
+     */
+    async fetchOnce(url, init) {
+        const controller = new AbortController();
+        const caller = init.signal;
+        const onAbort = () => controller.abort();
+        if (caller) {
+            if (caller.aborted)
+                controller.abort();
+            else
+                caller.addEventListener("abort", onAbort, { once: true });
+        }
+        let timedOut = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, this.timeout);
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            if (err?.name === "AbortError") {
+                if (timedOut)
+                    throw new NetworkError("Request timed out");
+                throw new NetworkError("Request was aborted");
+            }
+            throw new NetworkError(`Network error: ${err?.message ?? err}`);
+        }
+        finally {
+            clearTimeout(timeoutId);
+            if (caller)
+                caller.removeEventListener("abort", onAbort);
+        }
+    }
     // ── SSE parser ──────────────────────────────────────
     async *parseSSE(response) {
+        if (!response.body) {
+            throw new NetworkError("The server sent no response body to stream.");
+        }
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
         let buffer = "";
@@ -141,154 +260,302 @@ class PromptevClient {
                 buffer += decoder.decode(value, { stream: true });
                 const lines = buffer.split("\n");
                 buffer = lines.pop() || "";
-                for (const line of lines) {
+                for (const raw of lines) {
+                    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
                     if (!line.startsWith("data: "))
                         continue;
+                    let data;
                     try {
-                        const data = JSON.parse(line.slice(6));
-                        const event = {
-                            type: data.type || "unknown",
-                            output: data.output || "",
-                            raw: data,
-                        };
-                        yield event;
-                        if (event.type === "done" || event.type === "error")
-                            return;
+                        data = JSON.parse(line.slice(6));
                     }
                     catch {
-                        continue;
+                        continue; // a frame we cannot parse is never a reason to stop
                     }
+                    if (!data || typeof data !== "object" || typeof data.type !== "string")
+                        continue;
+                    const event = data;
+                    yield event;
+                    if (event.type === "done" || event.type === "error")
+                        return;
                 }
             }
         }
         finally {
+            // Cancel, not just release: a caller who breaks out of the loop early
+            // (or stops at `done`) would otherwise leave the connection open until
+            // the socket is collected.
+            try {
+                await reader.cancel();
+            }
+            catch {
+                /* already closed */
+            }
             reader.releaseLock();
         }
     }
-    // ── Prompt API ──────────────────────────────────────
+    // ── Agent API ───────────────────────────────────────
     /**
-     * Compile and execute a prompt.
+     * Send a message to one of your project's agents and stream the answer.
+     *
+     * This is the whole conversational surface: it starts a thread or continues
+     * one, streams every event the turn produces, and ends with `done` (or
+     * `error`). There is no separate "start" call and no session token — the API
+     * key IS the credential, and `conversationId` is the thread.
+     *
+     * @param agentSlug The agent's slug, as shown on its page in Promptev. Only
+     *   PUBLISHED agents in the key's own project can be reached; anything else
+     *   answers 404 ({@link NotFoundError}).
+     * @param message What to say. Required, non-empty after trimming, at most
+     *   {@link MAX_MESSAGE_CHARS} characters.
      *
-     * If the prompt has a model configured, it compiles the template,
-     * sends it to the LLM, and returns the AI response. If no model
-     * is configured, it returns the compiled template string.
+     * @example Stream the answer
+     * ```ts
+     * let conversationId: string | undefined;
+     * for await (const ev of client.chat("support-agent", "What is the refund policy?")) {
+     *   switch (ev.type) {
+     *     case "conversation": conversationId = ev.id; break;
+     *     case "token": process.stdout.write(ev.content); break;
+     *     case "approval_required":
+     *       console.log(`\n${ev.tool_name} needs approval — ${ev.reason ?? "policy"}`);
+     *       break;
+     *     case "error": throw new Error(ev.message);
+     *   }
+     * }
+     * // Continue the thread — and see far fewer approval prompts:
+     * for await (const ev of client.chat("support-agent", "And for digital goods?", { conversationId })) {
+     *   if (ev.type === "token") process.stdout.write(ev.content);
+     * }
+     * ```
      */
-    async runPrompt(promptKey, query, variables) {
-        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}`;
-        const merged = { query, ...(variables ?? {}) };
-        const resp = await this.fetchWithRetry(url, {
+    async *chat(agentSlug, message, options) {
+        const slug = String(agentSlug ?? "").trim();
+        if (!slug) {
+            throw new ValidationError("Name the agent to talk to.", undefined, undefined, "agentSlug");
+        }
+        const text = String(message ?? "").trim();
+        if (!text) {
+            // The server answers 422 for this; refusing here saves the round trip
+            // AND the api_call the workspace would still have been metered for.
+            throw new ValidationError("Say something to the agent.", undefined, undefined, "message");
+        }
+        if (text.length > exports.MAX_MESSAGE_CHARS) {
+            throw new ValidationError(`A message can be at most ${exports.MAX_MESSAGE_CHARS} characters.`, undefined, undefined, "message");
+        }
+        const payload = { message: text };
+        if (options?.conversationId != null)
+            payload.conversation_id = options.conversationId;
+        if (options?.onBehalfOf != null) {
+            const obo = { subject: options.onBehalfOf.subject };
+            if (options.onBehalfOf.groups != null)
+                obo.groups = options.onBehalfOf.groups;
+            payload.on_behalf_of = obo;
+        }
+        const url = `${this.baseUrl}/api/v1/agents/${encodeURIComponent(slug)}/chat`;
+        // Deliberately NOT fetchWithRetry: a turn is not idempotent — a retried
+        // POST could run the agent, and its tools, a second time.
+        const resp = await this.fetchOnce(url, {
             method: "POST",
-            headers: this.headers,
-            body: JSON.stringify({ variables: merged }),
+            headers: this.authHeaders({
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+            }),
+            body: JSON.stringify(payload),
+            signal: options?.signal,
         });
-        const text = await resp.text();
-        PromptevClient.raiseForStatus(resp.status, text);
-        const data = JSON.parse(text);
-        if (typeof data.prompt !== "string") {
-            throw new PromptevError("Unexpected response: missing 'prompt' field");
+        if (resp.status >= 400) {
+            const body = await resp.text();
+            PromptevClient.raiseForStatus(resp.status, body, resp.headers);
         }
-        return data.prompt;
+        yield* this.parseSSE(resp);
     }
     /**
-     * Compile and execute a prompt with streaming.
+     * Put one or more documents into the project's corpus — the same "Uploads"
+     * source the app writes to, so what you upload here is what the agents in
+     * that project retrieve.
+     *
+     * The key names the project, so nothing about the destination is in the
+     * request: a key cannot upload into a project it does not reach.
+     *
+     * Limits, checked here and again on the server: at most
+     * {@link MAX_FILES_PER_REQUEST} files per call, at most
+     * {@link MAX_UPLOAD_BYTES} (25 MB) per file — a larger set belongs in a
+     * connector source. Ingestion is content-addressed: re-uploading identical
+     * bytes updates the existing document instead of duplicating it.
      *
-     * Use this when the prompt has tools attached or you want real-time
-     * output. Returns the same event types as agent streaming.
+     * Ingestion is slow, and the request does not return until every file is
+     * indexed — raise `timeout` well above its 30 s default for real documents.
+     *
+     * @example
+     * ```ts
+     * import { readFile } from "node:fs/promises";
+     *
+     * const { results } = await client.uploadDocument(
+     *   { name: "handbook.pdf", content: await readFile("handbook.pdf") },
+     *   { mode: "hybrid" }
+     * );
+     * for (const r of results) console.log(r.filename, r.status, r.error ?? "");
+     * ```
      */
-    async *streamPrompt(promptKey, query, variables) {
-        const url = `${this.baseUrl}/api/sdk/v1/prompt/client/${this.projectKey}/${promptKey}?stream=true`;
-        const merged = { query, ...(variables ?? {}) };
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-        let resp;
-        try {
-            resp = await fetch(url, {
-                method: "POST",
-                headers: this.headers,
-                body: JSON.stringify({ variables: merged }),
-                signal: controller.signal,
-            });
+    async uploadDocument(files, options) {
+        const list = Array.isArray(files) ? files : [files];
+        if (list.length === 0) {
+            throw new ValidationError("Attach at least one file.", undefined, undefined, "files");
         }
-        catch (err) {
-            clearTimeout(timeoutId);
-            if (err.name === "AbortError")
-                throw new NetworkError("Request timed out");
-            throw new NetworkError(`Network error: ${err.message}`);
+        if (list.length > exports.MAX_FILES_PER_REQUEST) {
+            throw new ValidationError(`Upload at most ${exports.MAX_FILES_PER_REQUEST} files at a time — sync a larger set through a connector source.`, undefined, undefined, "files");
         }
-        clearTimeout(timeoutId);
-        if (resp.status >= 400) {
-            const text = await resp.text();
-            PromptevClient.raiseForStatus(resp.status, text);
+        if (options?.mode != null && !["hybrid", "graph"].includes(options.mode)) {
+            throw new ValidationError("Mode must be 'hybrid' or 'graph'.", undefined, undefined, "mode");
         }
-        const contentType = resp.headers.get("content-type") || "";
-        // Non-streaming fallback: prompt has no model, backend returns JSON
-        if (!contentType.includes("text/event-stream")) {
-            const data = await resp.json();
-            yield {
-                type: "done",
-                output: data.prompt || "",
-                raw: data,
-            };
-            return;
+        const form = new FormData();
+        for (const file of list) {
+            const [name, blob] = toBlob(file);
+            if (blob.size > exports.MAX_UPLOAD_BYTES) {
+                throw new ValidationError(`${name}: larger than ${exports.MAX_UPLOAD_BYTES / (1024 * 1024)} MB — sync bigger files through a connector source.`, undefined, undefined, "files");
+            }
+            form.append("files", blob, name);
         }
-        yield* this.parseSSE(resp);
-    }
-    // ── Agent API ───────────────────────────────────────
-    /**
-     * Start a new agent chat session.
-     */
-    async startAgent(chatbotId, options) {
-        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/start`;
-        const payload = {};
-        if (options?.visitor != null)
-            payload.visitor = options.visitor;
-        if (options?.platform && options.platform !== "sdk")
-            payload.platform = options.platform;
+        if (options?.mode != null)
+            form.append("mode", options.mode);
+        const url = `${this.baseUrl}/api/v1/documents`;
+        // Retried on 502/503/504, unlike chat: the same bytes ingest to the same
+        // document (its id is a hash of the content), so a retry cannot duplicate one.
         const resp = await this.fetchWithRetry(url, {
             method: "POST",
-            headers: this.headers,
-            body: JSON.stringify(payload),
+            // NO Content-Type — fetch sets the multipart boundary itself.
+            headers: this.authHeaders(),
+            body: form,
+            signal: options?.signal,
         });
-        const text = await resp.text();
-        PromptevClient.raiseForStatus(resp.status, text);
-        const data = JSON.parse(text);
-        return {
-            sessionToken: data.session_token,
-            chatbotId: data.chatbot_id,
-            name: data.name,
-            memoryEnabled: data.memory_enabled ?? false,
-            messages: data.messages ?? [],
-        };
+        const body = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, body, resp.headers);
+        const data = JSON.parse(body);
+        return { results: Array.isArray(data?.results) ? data.results : [] };
     }
     /**
-     * Stream an agent response as SSE events.
+     * Start a run of a published orchestration. Answers as soon as the run is
+     * recorded — **not** when it finishes.
+     *
+     * An orchestration is a team of agents; it runs in a worker for as long as it
+     * takes, so this returns a `run_id` and {@link getRun} tells you what became
+     * of it. That is the difference from {@link chat}, which streams one agent's
+     * answer inline.
+     *
+     * ```ts
+     * const { run_id } = await client.runOrchestration("month-end-close", {
+     *   period: "2026-03",
+     *   entity: "Acme GmbH",
+     * });
+     * ```
+     *
+     * With files — the part is named after the input it fills:
+     *
+     * ```ts
+     * const { run_id } = await client.runOrchestration(
+     *   "contract-review",
+     *   { matter: "Acme renewal" },
+     *   { files: { contract: { name: "lease.pdf", content: bytes } } },
+     * );
+     * ```
      */
-    async *streamAgent(chatbotId, options) {
-        const url = `${this.baseUrl}/api/sdk/v1/agent/${this.projectKey}/${chatbotId}/stream?session_token=${encodeURIComponent(options.sessionToken)}`;
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-        let resp;
-        try {
-            resp = await fetch(url, {
-                method: "POST",
-                headers: this.headers,
-                body: JSON.stringify({ query: options.query }),
-                signal: controller.signal,
-            });
+    async runOrchestration(slug, inputs = {}, options) {
+        if (!slug || !slug.trim()) {
+            throw new ValidationError("Name the orchestration to run.", undefined, undefined, "slug");
         }
-        catch (err) {
-            clearTimeout(timeoutId);
-            if (err.name === "AbortError")
-                throw new NetworkError("Request timed out");
-            throw new NetworkError(`Network error: ${err.message}`);
+        const fileEntries = Object.entries(options?.files ?? {}).flatMap(([key, value]) => (Array.isArray(value) ? value : [value]).map((file) => [key, file]));
+        if (fileEntries.length > exports.MAX_FILES_PER_RUN) {
+            throw new ValidationError(`At most ${exports.MAX_FILES_PER_RUN} files can be sent with one call.`, undefined, undefined, "files");
         }
-        clearTimeout(timeoutId);
-        if (resp.status >= 400) {
-            const text = await resp.text();
-            PromptevClient.raiseForStatus(resp.status, text);
+        const headers = this.authHeaders();
+        if (options?.idempotencyKey) {
+            headers["Idempotency-Key"] = options.idempotencyKey;
         }
-        yield* this.parseSSE(resp);
+        let body;
+        if (fileEntries.length > 0) {
+            // MULTIPART when there are files, JSON when there are not — the two
+            // shapes the server accepts, and the JSON rides in a `payload` part so
+            // the input keys survive untouched.
+            const form = new FormData();
+            form.append("payload", JSON.stringify(inputs ?? {}));
+            for (const [key, file] of fileEntries) {
+                const [name, blob] = toBlob(file);
+                if (blob.size > exports.MAX_UPLOAD_BYTES) {
+                    throw new ValidationError(`${name}: larger than ${exports.MAX_UPLOAD_BYTES / (1024 * 1024)} MB — add bigger files to the agent's knowledge instead.`, undefined, undefined, key);
+                }
+                form.append(key, blob, name);
+            }
+            body = form;
+            // NO Content-Type — fetch sets the multipart boundary itself.
+        }
+        else {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(inputs ?? {});
+        }
+        const url = `${this.baseUrl}/api/v1/orchestrations/${encodeURIComponent(slug)}/run`;
+        // NOT retried without an idempotency key: a retried start could fan the
+        // team out twice, and only the caller can say whether two calls are one
+        // event. With a key the server collapses them, so retrying is safe.
+        const resp = options?.idempotencyKey
+            ? await this.fetchWithRetry(url, { method: "POST", headers, body, signal: options?.signal })
+            : await fetch(url, { method: "POST", headers, body, signal: options?.signal });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text, resp.headers);
+        const data = JSON.parse(text);
+        return { run_id: String(data?.run_id ?? ""), status: "accepted" };
+    }
+    /**
+     * What became of a run — poll this after {@link runOrchestration}.
+     *
+     * ```ts
+     * let run = await client.getRun(run_id);
+     * while (run.status === "running" || run.status === "revising") {
+     *   await new Promise((r) => setTimeout(r, 2000));
+     *   run = await client.getRun(run_id);
+     * }
+     * console.log(run.output);
+     * ```
+     */
+    async getRun(runId, options) {
+        if (!runId || !runId.trim()) {
+            throw new ValidationError("Name the run to read.", undefined, undefined, "runId");
+        }
+        const url = `${this.baseUrl}/api/v1/runs/${encodeURIComponent(runId)}`;
+        // A read is safe to retry.
+        const resp = await this.fetchWithRetry(url, {
+            method: "GET",
+            headers: this.authHeaders(),
+            signal: options?.signal,
+        });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text, resp.headers);
+        return JSON.parse(text);
     }
 }
 exports.PromptevClient = PromptevClient;
+/** One upload input, as a named Blob — the only shape `FormData` accepts. */
+function toBlob(file) {
+    if (typeof Blob !== "undefined" && file instanceof Blob) {
+        // A `File` is a Blob that already has a name; a bare Blob needs one.
+        const name = file.name;
+        return [typeof name === "string" && name ? name : "upload", file];
+    }
+    const named = file;
+    if (!named || typeof named.name !== "string" || !named.name.trim()) {
+        throw new ValidationError("Give each uploaded file a name — the extension is what picks the parser.", undefined, undefined, "files");
+    }
+    const content = named.content;
+    if (content == null) {
+        throw new ValidationError(`${named.name}: no content to upload.`, undefined, undefined, "files");
+    }
+    if (typeof Blob !== "undefined" && content instanceof Blob) {
+        return [named.name, content];
+    }
+    const part = ArrayBuffer.isView(content)
+        ? content.buffer.slice(content.byteOffset, content.byteOffset + content.byteLength)
+        : content;
+    return [
+        named.name,
+        new Blob([part], named.type ? { type: named.type } : undefined),
+    ];
+}
 exports.default = PromptevClient;