@promptev/client 0.1.0 → 1.0.0

package/readme.md

@@ -1,6 +1,10 @@
-# Promptev JavaScript SDK
+# Promptev JavaScript client
 
-The official JavaScript/TypeScript SDK for [Promptev.ai](https://promptev.ai) — run AI prompts and agents programmatically using your project API key.
+The official JavaScript/TypeScript client for [Promptev](https://promptev.ai) — stream your AI **agents** and upload documents to their knowledge base, from anywhere that has `fetch`.
+
+> In Promptev, an **agent** is your deployed AI assistant: instructions + model + tools (Jira, Slack, GitHub, your own APIs) + the documents it can retrieve, all configured in the app. This client runs those agents. Tools execute server-side, retrieval is governed server-side, and conversation memory is built in.
+
+**Upgrading from 0.2.x? Read [Migrating from 0.2.x](#migrating-from-02x) first — 1.0 is a rewrite against a new API, and none of the 0.2 calls exist any more.**
 
 ## Installation
 
@@ -14,214 +18,244 @@ pnpm add @promptev/client
 
 Requires Node.js 18+ or any modern browser. Zero dependencies.
 
-## Platform Support
-
-Works everywhere — backend, frontend, and edge runtimes. Built entirely on [Web Platform APIs](https://wintercg.org/) (`fetch`, `ReadableStream`, `AbortController`, `TextDecoder`) with no Node.js-specific modules.
+## Quick Start
 
-| Environment | Supported | Notes |
-|---|---|---|
-| **Node.js 18+** | ✅ | ESM and CommonJS |
-| **Bun** | ✅ | Native Web API support |
-| **Deno** | ✅ | Native Web API support |
-| **React / Next.js** | ✅ | Works with any bundler |
-| **Angular** | ✅ | Full TypeScript types included |
-| **Vue / Nuxt** | ✅ | Standard ESM import |
-| **Svelte / SvelteKit** | ✅ | Standard ESM import |
-| **Vanilla JS** | ✅ | No framework required |
-| **Cloudflare Workers** | ✅ | Edge runtime compatible |
-| **Vercel Edge Functions** | ✅ | Edge runtime compatible |
+Mint an API key in Promptev under **Settings → API keys** of the project you want to reach. It looks like `fk_…`, it is shown exactly once, and it is bound to that one project.
 
-```js
-// ESM (Node 18+, React, Next.js, Vue, Angular, Svelte, etc.)
+```ts
 import { PromptevClient } from "@promptev/client";
 
-// CommonJS (legacy Node.js projects)
-const { PromptevClient } = require("@promptev/client");
+const client = new PromptevClient({ apiKey: process.env.PROMPTEV_API_KEY! });
+
+let conversationId: string | undefined;
+
+for await (const event of client.chat("support-agent", "What is the refund policy?")) {
+  switch (event.type) {
+    case "conversation":
+      conversationId = event.id;          // keep it to continue this thread
+      break;
+    case "token":
+      process.stdout.write(event.content); // the answer, one delta at a time
+      break;
+    case "approval_required":
+      console.log(`\n⏸  ${event.tool_name} is waiting for a human — ${event.reason}`);
+      break;
+    case "error":
+      throw new Error(event.message);
+  }
+}
 ```
 
-## Quick Start
-
-```ts
-import { PromptevClient } from "@promptev/client";
-
-const client = new PromptevClient({ projectKey: "pv_sk_your_key_here" });
+That is the whole conversational surface: one call that starts or continues a thread and streams everything the turn produces.
 
-// Run a prompt
-const result = await client.runPrompt("support-agent",
-  "What is the refund policy?",
-  { company: "Acme Corp" }
-);
-console.log(result);
+## Authentication
 
-// Chat with an AI agent
-const session = await client.startAgent("your-agent-id");
+The key travels in a header, never in a URL:
 
-for await (const event of client.streamAgent(session.chatbotId, {
-  sessionToken: session.sessionToken,
-  query: "Summarize our Q4 sales report",
-})) {
-  if (event.type === "done") console.log(event.output);
-}
+```
+Authorization: Bearer fk_live_xxxxxxxx
 ```
 
-## Prompts
+Three things follow from that, and they are the reason 1.0 exists:
 
-Promptev prompts are versioned, server-managed templates. `runPrompt` compiles the template with your variables — and if the prompt has a model configured in Promptev, it also executes it against the LLM and returns the AI response directly.
+- **The key never leaks into logs.** A key in a URL path ends up in access logs, proxy logs and `Referer` headers. A Bearer token does not.
+- **The key carries its own retrieval identity.** What the agent may read when *you* call it is part of the credential (`retrieves_as`), not a parameter you send. A caller cannot widen its own reach.
+- **The key is bound to one project.** An agent in a sibling project answers exactly the same `404` an unknown slug does — a key holder learns nothing about projects it was not given.
 
-### Run a prompt with variables
+Keys are minted by workspace admins, expire (at most a year), and can be revoked at any time. Keep them server-side.
+
+## `chat` — stream a turn
 
 ```ts
-const result = await client.runPrompt("support-agent",
-  "How do I reset my password?",
-  { company: "Acme Corp", tone: "professional" }
-);
+client.chat(agentSlug, message, options?): AsyncGenerator<AgentEvent>
 ```
 
-### Run a prompt without variables
+| Parameter | Type | Description |
+|---|---|---|
+| `agentSlug` | `string` | The agent's slug, from its page in Promptev. It must be **published**, and it must be in the key's project — otherwise `NotFoundError`. |
+| `message` | `string` | What to say. Required, non-empty after trimming, at most 20,000 characters. |
+| `options.conversationId` | `string?` | Continue a thread. Take it from the first `conversation` event. |
+| `options.onBehalfOf` | `object?` | Act for one of your end users — see [On behalf of your users](#on-behalf-of-your-users). |
+| `options.signal` | `AbortSignal?` | Cancel the turn. |
+
+Returns an async generator of [events](#events). It ends after `done`, or after `error`.
+
+### Multi-turn
 
 ```ts
-const result = await client.runPrompt("knowledge-base",
-  "What is the refund policy?"
-);
+let conversationId: string | undefined;
+
+async function ask(question: string) {
+  let answer = "";
+  for await (const ev of client.chat("support-agent", question, { conversationId })) {
+    if (ev.type === "conversation") conversationId = ev.id;
+    if (ev.type === "token") answer += ev.content;
+    if (ev.type === "error") throw new Error(ev.message);
+  }
+  return answer;
+}
+
+console.log(await ask("Summarize our Q4 sales report"));
+console.log(await ask("Compare that with Q3"));   // remembers the first turn
 ```
 
-### With a model configured (auto-execute)
+Passing `conversationId` is worth doing for a second reason: a tool set to **Ask once** asks for approval on the first call in a conversation and not again for the rest of it, so a continued thread interrupts you far less often.
+
+A thread belongs to the agent, to this API, **and** to the `onBehalfOf.subject` it was opened under. Keep the subject the same across a conversation's turns, and never reuse an id from the app, the portal or an embed — any mismatch answers `404`, not a fresh thread.
 
-If your prompt has a model and/or context packs attached in Promptev, `runPrompt` compiles the template, retrieves relevant context via RAG, sends it to the LLM, and returns the AI response:
+## Events
+
+Every frame the server can send, typed. Narrow on `event.type`.
+
+A frame from a **newer** server is passed through rather than thrown on, so an event added by a Promptev deploy can never break your integration — it simply matches none of your cases. If you want to log them, `import type { UnknownEvent }` and cast in your `default` branch.
+
+| Event | Fields | What it means |
+|---|---|---|
+| `conversation` | `id` | Always first. The thread id — pass it back as `conversationId`. |
+| `thinking` | `content` | One delta of the model's reasoning. Only from models that stream it. |
+| `token` | `content` | One delta of the answer. Concatenate them all to get the reply. |
+| `step` | `name`, `status`, `detail?` | A stage of the turn: reading attachments, retrieving, waiting on an emailed approval. `status` is `started` / `completed` / `failed`. |
+| `sources` | `items[]` (`name`, `document_id`) | The documents the answer is grounded in. |
+| `tool_call` | `id`, `name`, `args?` | The agent invoked a tool. |
+| `tool_result` | `id`, `name`, `ok`, `summary?` | That tool answered. `id` matches the `tool_call`. |
+| `approval_required` | `approval_id`, `tool_name`, `args?`, `reason?`, `channel?`, `expires_at?` | **The turn is paused, waiting for a human** — see below. |
+| `artifact` | `id`, `name`, `mime`, `size` | A file the agent produced this turn. Fetch it from the conversation in Promptev. |
+| `suggestions` | `questions[]` | 2–3 follow-ups the same person would plausibly ask next. |
+| `usage` | `units`, `tokens?`, `tool_calls?` | What the turn cost, just before `done`. |
+| `done` | — | The stream finished cleanly. |
+| `error` | `message` | The turn failed mid-stream. |
+
+### `approval_required` — handle this one
+
+A tool the agent wants to run can be gated on human approval. When that happens the turn **pauses and the stream stays open**: a person approves it in the Promptev app, by email, or in Slack, and the turn then continues on that same connection. You do not re-send anything. If nobody decides in time, the approval expires and the turn reports it as a failed `tool_result`.
+
+An integration that ignores this event looks *hung* to its user for as long as the approval window lasts. Show it:
 
 ```ts
-const answer = await client.runPrompt("support-agent",
-  "What is the refund policy?",
-  { company: "Acme Corp" }
-);
-console.log(answer); // "Our refund policy allows returns within 30 days..."
+for await (const ev of client.chat("ops-agent", "Refund invoice 4182")) {
+  if (ev.type === "approval_required") {
+    console.log(`Waiting on a human: ${ev.tool_name}`);
+    console.log(`  why:     ${ev.reason}`);
+    console.log(`  args:    ${JSON.stringify(ev.args)}`);
+    console.log(`  decide:  in Promptev (${ev.channel}), by ${ev.expires_at ?? "the policy deadline"}`);
+  }
+  if (ev.type === "tool_result" && ev.approval) {
+    console.log(`Approval ended: ${ev.approval}`);   // rejected / timeout / expired
+  }
+  if (ev.type === "token") process.stdout.write(ev.content);
+}
 ```
 
-### Without a model (use with your own LLM)
+`channel` is where a human can decide it — `"inline"` (the Promptev app) or `"slack"`. Approvals routed to an **approver by email** send no card at all; they show up as a `step` named `waiting for approval — <tool>`, which closes when the decision lands.
 
-If no model is configured, `runPrompt` returns the compiled template — use it with any LLM:
+## On behalf of your users
+
+If you are putting Promptev behind your own UI, tell it which of your end users a call is for:
 
 ```ts
-import OpenAI from "openai";
+for await (const ev of client.chat("support-agent", question, {
+  onBehalfOf: { subject: "ana@acme.com", groups: ["finance", "emea"] },
+})) { /* … */ }
+```
 
-const client = new PromptevClient({ projectKey: "pv_sk_..." });
-const openai = new OpenAI({ apiKey: "sk-..." });
+- `subject` is recorded as the conversation's actor, for the audit trail.
+- `groups` are **intersected** with the key's own grant. They can only ever narrow what the caller may retrieve, never widen it — so a compromised caller of yours still cannot read past what the key was given. (Because the assertion is unverified, the key's own per-user grants drop for that call; only an omitted `onBehalfOf` gets the key's full reach.)
 
-const systemPrompt = await client.runPrompt("support-agent",
-  "How do I reset my password?",
-  { company: "Acme Corp", tone: "professional" }
-);
+## `uploadDocument` — add to the knowledge base
 
-const response = await openai.chat.completions.create({
-  model: "gpt-4",
-  messages: [
-    { role: "system", content: systemPrompt },
-    { role: "user", content: "How do I reset my password?" },
-  ],
-});
-console.log(response.choices[0].message.content);
+```ts
+client.uploadDocument(files, options?): Promise<{ results: UploadResult[] }>
 ```
 
-### Stream a prompt (with tools or real-time output)
-
-When a prompt has tools attached (Jira, Slack, GitHub, etc.) or you want real-time output, use `streamPrompt`. It returns SSE events — same format as agent streaming:
+Files land in the project's **Uploads** source — the same corpus the app writes to, so what you upload is what that project's agents retrieve. The key names the project; there is nothing to address.
 
 ```ts
-for await (const event of client.streamPrompt("research-assistant",
-  "Find all P1 bugs assigned to me",
-  { project: "ACME" }
-)) {
-  if (event.type === "thoughts") console.log(`Thinking: ${event.output}`);
-  else if (event.type === "processing") console.log(`Running: ${event.output}`);
-  else if (event.type === "done") console.log(event.output);
+import { readFile } from "node:fs/promises";
+
+const { results } = await client.uploadDocument([
+  { name: "handbook.pdf", content: await readFile("handbook.pdf") },
+  { name: "policies.md", content: "# Refunds\n30 days." },
+]);
+
+for (const r of results) {
+  console.log(`${r.filename}: ${r.status}${r.error ? ` — ${r.error}` : ""} (${r.chunks} chunks)`);
 }
 ```
 
-> **When to use which:**
-> - `runPrompt()` — simple prompt execution, no tools, returns a string
-> - `streamPrompt()` — prompts with tools, RAG-heavy queries, or when you want real-time output
+In a browser, pass `File` objects straight from an `<input type="file">`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `files` | `File \| Blob \| { name, content, type? }`, or an array of them | `content` may be a `string`, `ArrayBuffer`, typed array, or `Blob`. |
+| `options.mode` | `"hybrid" \| "graph"` | How it is indexed. `"graph"` needs a graph database and an extraction model configured for the workspace. |
+| `options.signal` | `AbortSignal?` | Cancel the upload. |
+
+Limits (enforced here and again on the server): **20 files per call**, **25 MB per file**. A larger set belongs in a connector source (Google Drive, SharePoint, Dropbox, …), configured in the app. Re-uploading identical bytes updates the existing document instead of duplicating it.
+
+A per-file failure is *reported*, not thrown: every file gets a row in `results` with its own `status` and `error`. Only a whole-request failure (a bad key, no credits, a rejected file type) raises.
 
-## Agents
+> Ingestion is slow and the request does not return until every file is indexed. Raise `timeout` well above its 30-second default: `new PromptevClient({ apiKey, timeout: 300_000 })`.
 
-Promptev agents are deployed AI assistants with built-in memory, tools (Jira, Slack, GitHub, etc.), and RAG context packs. The SDK lets you start sessions and stream responses in real time.
+## `runOrchestration` — run a team of agents
 
-### Start a session
+An orchestration is a **team of agents** working one job. `chat` streams one agent's answer inline; an orchestration runs in a worker for as long as it takes, so `runOrchestration` hands back a run id straight away and `getRun` says what became of it.
 
 ```ts
-const session = await client.startAgent("your-agent-id", { visitor: "John" });
+const started = await client.runOrchestration("month-end-close", {
+  period: "2026-03",
+});
 
-console.log(session.sessionToken);  // Use this for all subsequent messages
-console.log(session.name);          // Agent display name
-console.log(session.memoryEnabled); // Whether agent retains conversation context
-```
+let run = await client.getRun(started.run_id);
+while (run.status === "running" || run.status === "revising") {
+  await new Promise((r) => setTimeout(r, 2000));
+  run = await client.getRun(started.run_id);
+}
 
-### Stream a response
+console.log(run.status); // "delivered"
+console.log(run.output);
+```
 
-The agent responds via Server-Sent Events (SSE). Each event has a `type` and `output`:
+The orchestration must be **published**, **switched on**, and in your key's project — one that is not published, or lives in a sibling project, throws the same `NotFoundError` an invented name does. One that exists and is published but is switched off says so plainly, so you can tell "turn it on" from "wrong name".
 
-| Event Type | Description |
-|---|---|
-| `thoughts` | Agent's internal reasoning |
-| `processing` | Tool execution status (e.g., "Searching Jira...") |
-| `approval_required` | Agent needs permission to run a tool |
-| `done` | Final response text |
-| `error` | Something went wrong |
+The keys in the second argument are the orchestration's **own declared inputs** — the ones its Inputs step lists. A required one you leave out is refused before anything runs, with the field named:
 
 ```ts
-for await (const event of client.streamAgent(session.chatbotId, {
-  sessionToken: session.sessionToken,
-  query: "What are the open P1 bugs in our backlog?",
-})) {
-  if (event.type === "thoughts") console.log(`Thinking: ${event.output}`);
-  else if (event.type === "processing") console.log(`Running: ${event.output}`);
-  else if (event.type === "done") console.log(`\n${event.output}`);
-  else if (event.type === "error") console.log(`Error: ${event.output}`);
+try {
+  await client.runOrchestration("month-end-close", {});
+} catch (e) {
+  if (e instanceof ValidationError) console.log(e.field); // "period"
 }
 ```
 
-### Multi-turn conversation
+### Sending files
 
-The session token maintains conversation context across messages:
+An input declared `File(s)` takes a file, keyed by that input:
 
 ```ts
-const session = await client.startAgent("your-agent-id", { visitor: "Sarah" });
-
-// First message
-for await (const event of client.streamAgent(session.chatbotId, {
-  sessionToken: session.sessionToken,
-  query: "Summarize our Q4 sales report",
-})) {
-  if (event.type === "done") console.log(event.output);
-}
-
-// Follow-up — agent remembers the previous context
-for await (const event of client.streamAgent(session.chatbotId, {
-  sessionToken: session.sessionToken,
-  query: "Compare that with Q3",
-})) {
-  if (event.type === "done") console.log(event.output);
-}
+await client.runOrchestration(
+  "contract-review",
+  { matter: "Acme renewal" },
+  { files: { contract: { name: "lease.pdf", content: bytes } } },
+);
 ```
 
-### Collect the final response only
+Up to **five files per call**, 25 MB each. Each part is named after the input it fills, which is what lets one call fill two different file inputs. Files take the same shapes `uploadDocument` does — a `File`, a `Blob`, or `{ name, content }`.
 
-```ts
-async function askAgent(client, session, query) {
-  for await (const event of client.streamAgent(session.chatbotId, {
-    sessionToken: session.sessionToken,
-    query,
-  })) {
-    if (event.type === "done") return event.output;
-    if (event.type === "error") throw new Error(event.output);
-  }
-}
+### Retrying safely
 
-const answer = await askAgent(client, session, "What's our monthly churn rate?");
+Starting a run twice runs the team twice. Pass an `idempotencyKey` and a retry returns the run you already started:
+
+```ts
+await client.runOrchestration(
+  "month-end-close",
+  { period: "2026-03" },
+  { idempotencyKey: "close-2026-03" },
+);
 ```
 
-## Error Handling
+Only your caller knows whether two calls are one event, which is why this is yours to send rather than something the client invents. Without one the start is **not** retried on a transient failure, because a retried start could fan the team out twice.
 
-The SDK raises typed errors for each failure scenario:
+## Error Handling
 
 ```ts
 import {
@@ -230,214 +264,297 @@ import {
   AuthenticationError,
   NotFoundError,
   RateLimitError,
+  InsufficientCreditsError,
   ServerError,
   NetworkError,
 } from "@promptev/client";
 
-const client = new PromptevClient({ projectKey: "pv_sk_..." });
-
 try {
-  const result = await client.runPrompt("my-prompt", "Hello", { name: "Ava" });
+  for await (const ev of client.chat("support-agent", "Hello")) {
+    if (ev.type === "token") process.stdout.write(ev.content);
+  }
 } catch (err) {
   if (err instanceof ValidationError) {
-    // 400 — missing variables, bad input
-    console.log(`Invalid request: ${err.message}`);
-  } else if (err instanceof NotFoundError) {
-    // 404 — prompt or project not found
-    console.log(`Not found: ${err.message}`);
+    console.log(`Invalid request: ${err.message} (field: ${err.field})`);
   } else if (err instanceof AuthenticationError) {
-    // 401/403 — invalid API key or agent not active
-    console.log(`Auth error: ${err.message}`);
+    console.log(`Bad or revoked API key: ${err.message}`);
+  } else if (err instanceof NotFoundError) {
+    console.log(`No such published agent in this key's project: ${err.message}`);
+  } else if (err instanceof InsufficientCreditsError) {
+    console.log(`Out of credits — top up in Billing: ${err.message}`);
   } else if (err instanceof RateLimitError) {
-    // 429 — API usage quota exceeded
-    console.log(`Rate limited: ${err.message}`);
+    console.log(`Rate limited; retry in ${err.retryAfter ?? "a moment"}s`);
   } else if (err instanceof ServerError) {
-    // 5xx — server error (after retries exhausted)
-    console.log(`Server error: ${err.message}`);
+    console.log(`Server error (after retries): ${err.message}`);
   } else if (err instanceof NetworkError) {
-    // Connection failed, timeout, DNS error
-    console.log(`Network error: ${err.message}`);
+    console.log(`Could not reach Promptev: ${err.message}`);
   }
 }
 ```
 
-All errors extend `PromptevError` and include:
-- `err.statusCode` — HTTP status code (if applicable)
-- `err.responseText` — Raw response body (for debugging)
+All errors extend `PromptevError` and carry:
+
+- `err.statusCode` — the HTTP status, when there was one
+- `err.field` — which input the server objected to, when it named one
+- `err.responseText` — the raw body, for debugging
+
+| Error | HTTP | When |
+|---|---|---|
+| `ValidationError` | 400, 422 | Empty or over-long message, bad `mode`, a rejected file type — and the same checks made client-side before a request goes out |
+| `AuthenticationError` | 401, 403 | Missing, malformed, revoked or expired key |
+| `InsufficientCreditsError` | 402 | The workspace is out of credits. Waiting does not fix it; a top-up does |
+| `NotFoundError` | 404 | Unknown agent slug, an unpublished agent, or one outside the key's project — all three answer identically on purpose |
+| `RateLimitError` | 429 | Too many requests. `err.retryAfter` is the server's own answer in seconds |
+| `ServerError` | 5xx | The server failed, after retries |
+| `NetworkError` | — | DNS, connection, abort, or the client timeout |
+| `PromptevError` | any | Base class for all of the above |
+
+**Retries.** `uploadDocument` retries 502/503/504 with exponential backoff (`maxRetries`, default 2), which is safe because a document's id is a hash of its bytes — the same upload twice is the same document. `chat` is deliberately **not** retried: re-sending a turn could run the agent, and its tools, a second time.
+
+**A failed turn may also arrive as an `error` event** rather than an exception, when the stream had already started. Handle both.
+
+## What a call costs
+
+Promptev is pay as you go and this API is metered. The rates below are the
+managed ones; a workspace running on its own database and embedding provider
+(BYO) is charged a flat **1** per operation instead, because those bills are
+already yours.
+
+| what happens | credits |
+|---|---|
+| any request to this API | **1** (`api_call`) |
+| a chat turn | **1** (`chat_turn`) |
+| each tool the agent calls | **1** |
+| retrieval | **1** per knowledge base searched |
+| retrieval in graph mode | **5** per knowledge base searched |
+| a document you upload | **1** per page, slide or MB (minimum 1) |
+
+So an ordinary `chat` costs **2** — one for the request, one for the turn — and
+more if the agent calls tools or searches knowledge. The same conversation held
+in the Promptev app costs one, because there is no request to the programmatic
+door.
+
+Two things worth knowing before they surprise you:
+
+- **A refused request is still billed.** An unknown agent slug, a rate-limited
+  call and a rejected upload each consumed the same capacity a successful one
+  would, so each costs its `api_call` credit. Only the outcome differs.
+- **A request this client rejects locally is never billed**, because it never
+  leaves your process. That is why the empty-message and upload-limit checks
+  exist here rather than being left to the server.
+
+Model tokens are not billed by Promptev at all. Model calls go to your provider
+on your own keys, and that bill is yours.
 
 ## Configuration
 
 ```ts
 const client = new PromptevClient({
-  projectKey: "pv_sk_...",              // Required — your project API key
-  baseUrl: "https://api.promptev.ai",   // Default — override for self-hosted
-  timeout: 30000,                        // Default — request timeout in ms
-  maxRetries: 2,                         // Default — retries for 502/503/504
-  headers: { "X-Custom": "value" },      // Optional — extra HTTP headers
+  apiKey: "fk_...",                        // Required
+  baseUrl: "https://api.promptev.ai",  // Default — override for self-hosted or during the cutover
+  timeout: 30000,                          // Default — ms to wait for the response
+  maxRetries: 2,                           // Default — retries for 502/503/504
+  headers: { "X-Custom": "value" },        // Optional — extra HTTP headers
 });
 ```
 
 | Parameter | Default | Description |
 |---|---|---|
-| `projectKey` | *required* | Your Promptev project API key |
-| `baseUrl` | `https://api.promptev.ai` | API base URL |
-| `timeout` | `30000` | Request timeout in milliseconds |
-| `maxRetries` | `2` | Automatic retries for transient server errors (502, 503, 504) |
+| `apiKey` | *required* | Your Promptev API key (`fk_…`) |
+| `baseUrl` | `https://api.promptev.ai` | API base URL. Self-hosted? Point it at your own host. |
+| `timeout` | `30000` | Milliseconds to wait for the **response**. A `chat()` stream is not bounded by it — a turn that runs tools, or waits on an approval, may run for minutes. |
+| `maxRetries` | `2` | Automatic retries for transient server errors (502, 503, 504) on non-streaming calls |
 | `headers` | `{}` | Additional HTTP headers |
 
-## API Reference
+## Platform Support
 
-### `PromptevClient`
+Works everywhere — backend, frontend, and edge runtimes. Built entirely on [Web Platform APIs](https://wintercg.org/) (`fetch`, `ReadableStream`, `AbortController`, `TextDecoder`, `FormData`) with no Node.js-specific modules.
 
-| Method | Description | Returns |
+| Environment | Supported | Notes |
 |---|---|---|
-| `runPrompt(promptKey, query, variables?)` | Compile and execute a prompt | `Promise<string>` |
-| `streamPrompt(promptKey, query, variables?)` | Stream prompt execution with tools | `AsyncGenerator<AgentEvent>` |
-| `startAgent(chatbotId, options?)` | Start agent session | `Promise<AgentSession>` |
-| `streamAgent(chatbotId, options)` | Stream agent response | `AsyncGenerator<AgentEvent>` |
+| **Node.js 18+** | ✅ | ESM and CommonJS |
+| **Bun** | ✅ | Native Web API support |
+| **Deno** | ✅ | Native Web API support |
+| **React / Next.js** | ✅ | Server-side — see the warning below |
+| **Angular** | ✅ | Full TypeScript types included |
+| **Vue / Nuxt** | ✅ | Standard ESM import |
+| **Svelte / SvelteKit** | ✅ | Standard ESM import |
+| **Cloudflare Workers** | ✅ | Edge runtime compatible |
+| **Vercel Edge Functions** | ✅ | Edge runtime compatible |
 
-### `AgentSession`
+```js
+// ESM (Node 18+, React, Next.js, Vue, Angular, Svelte, etc.)
+import { PromptevClient } from "@promptev/client";
 
-| Field | Type | Description |
-|---|---|---|
-| `sessionToken` | `string` | Token for subsequent stream calls |
-| `chatbotId` | `string` | Agent identifier |
-| `name` | `string` | Agent display name |
-| `memoryEnabled` | `boolean` | Whether agent retains conversation context |
-| `messages` | `array` | Previous messages (populated when resuming a session) |
+// CommonJS (legacy Node.js projects)
+const { PromptevClient } = require("@promptev/client");
+```
 
-### `AgentEvent`
+> **Do not ship your API key to a browser.** The key carries a retrieval identity: whoever holds it can read everything it was granted. Call Promptev from your own server, or put an agent in a page with Promptev's embed widget, which issues a short-lived per-visitor token instead.
 
-| Field | Type | Description |
-|---|---|---|
-| `type` | `string` | Event type: `thoughts`, `processing`, `done`, `error`, `approval_required` |
-| `output` | `string` | Event content text |
-| `raw` | `object` | Full parsed SSE event data |
+## Framework Examples
 
-### Exceptions
+### Next.js route handler — stream to your own UI
 
-| Error | HTTP Status | When |
-|---|---|---|
-| `ValidationError` | 400 | Missing required variables, bad input |
-| `AuthenticationError` | 401, 403 | Invalid API key, agent not active |
-| `NotFoundError` | 404 | Project, prompt, or agent not found |
-| `RateLimitError` | 429 | API usage quota exceeded |
-| `ServerError` | 5xx | Server error (after retries exhausted) |
-| `NetworkError` | — | Connection failed, timeout, DNS error |
-| `PromptevError` | any | Base class for all above errors |
+```ts
+// app/api/ask/route.ts
+import { PromptevClient } from "@promptev/client";
 
-## Framework Examples
+const client = new PromptevClient({ apiKey: process.env.PROMPTEV_API_KEY! });
+
+export async function POST(req: Request) {
+  const { question, conversationId, user } = await req.json();
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      const encoder = new TextEncoder();
+      try {
+        for await (const ev of client.chat("support-agent", question, {
+          conversationId,
+          onBehalfOf: { subject: user.email, groups: user.groups },
+        })) {
+          // Forward the events your UI cares about, as your own SSE stream.
+          if (ev.type === "token" || ev.type === "approval_required" || ev.type === "conversation") {
+            controller.enqueue(encoder.encode(`data: ${JSON.stringify(ev)}\n\n`));
+          }
+        }
+      } catch (err) {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: "error", message: (err as Error).message })}\n\n`));
+      } finally {
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(stream, { headers: { "Content-Type": "text/event-stream" } });
+}
+```
 
-### React
+### Express — collect the answer server-side
 
-```tsx
-import { useState } from "react";
+```js
+import express from "express";
 import { PromptevClient } from "@promptev/client";
 
-const client = new PromptevClient({ projectKey: "pv_sk_..." });
-
-export function AskAI() {
-  const [answer, setAnswer] = useState("");
-  const [loading, setLoading] = useState(false);
+const app = express();
+const client = new PromptevClient({ apiKey: process.env.PROMPTEV_API_KEY });
 
-  async function handleAsk() {
-    setLoading(true);
-    try {
-      const result = await client.runPrompt("support-agent", "What is your refund policy?");
-      setAnswer(result);
-    } finally {
-      setLoading(false);
-    }
+app.post("/api/ask", express.json(), async (req, res) => {
+  let answer = "";
+  let conversationId = req.body.conversationId;
+  let pendingApproval = null;
+
+  for await (const ev of client.chat("support-agent", req.body.question, { conversationId })) {
+    if (ev.type === "conversation") conversationId = ev.id;
+    if (ev.type === "token") answer += ev.content;
+    if (ev.type === "approval_required") pendingApproval = ev;   // tell the user!
+    if (ev.type === "error") return res.status(502).json({ error: ev.message });
   }
 
-  return (
-    <div>
-      <button onClick={handleAsk} disabled={loading}>Ask AI</button>
-      {answer && <p>{answer}</p>}
-    </div>
-  );
-}
+  res.json({ answer, conversationId, pendingApproval });
+});
+
+app.listen(3000);
 ```
 
-### React — Streaming Agent Chat
+### Upload from a browser form (through your backend)
 
-```tsx
-import { useState, useRef } from "react";
-import { PromptevClient } from "@promptev/client";
+```ts
+// Your server route, holding the key:
+const files = form.getAll("files") as File[];
+const { results } = await client.uploadDocument(files, { mode: "hybrid" });
+```
 
-const client = new PromptevClient({ projectKey: "pv_sk_..." });
+## Migrating from 0.2.x
 
-export function AgentChat() {
-  const [messages, setMessages] = useState<string[]>([]);
-  const [input, setInput] = useState("");
-  const sessionRef = useRef(null);
+**1.0 talks to a different backend.** 0.2.x targeted `POST /api/sdk/v1/agent/{project_key}/{agent_id}/…` on the previous product; Promptev's current API is `/api/v1`, which does not serve those paths at all. Every 0.2 call would 404. Upgrading is a rewrite of your call sites, not a version bump — 0.2.x still works if you have not moved yet, so migrate deliberately.
 
-  async function startChat() {
-    sessionRef.current = await client.startAgent("your-agent-id", { visitor: "user" });
-  }
+### 1. Authentication: a Bearer key, not a key in the URL
+
+```diff
+- const client = new PromptevClient({ projectKey: "pv_sk_..." });
++ const client = new PromptevClient({ apiKey: "fk_..." });
+```
 
-  async function sendMessage() {
-    if (!sessionRef.current) await startChat();
+Mint the new key in **Settings → API keys** of the project you want to reach. This is the change everything else follows from: the key is now a header, it is bound to one project, and it carries the retrieval identity the agent answers under. Your old `pv_sk_…` project key does not work against the new API.
 
-    setMessages((prev) => [...prev, `You: ${input}`]);
-    const query = input;
-    setInput("");
+### 2. Base URL
 
-    for await (const event of client.streamAgent(sessionRef.current.chatbotId, {
-      sessionToken: sessionRef.current.sessionToken,
-      query,
-    })) {
-      if (event.type === "done") {
-        setMessages((prev) => [...prev, `Agent: ${event.output}`]);
-      }
-    }
-  }
+The default is `https://api.promptev.ai`. That host is being moved onto the new backend — until it is, pass `baseUrl: "https://console.promptev.ai"` explicitly. If you had hard-coded a `baseUrl`, remove it once the move is done, unless you are self-hosted.
 
-  return (
-    <div>
-      {messages.map((msg, i) => <p key={i}>{msg}</p>)}
-      <input value={input} onChange={(e) => setInput(e.target.value)} />
-      <button onClick={sendMessage}>Send</button>
-    </div>
-  );
-}
+### 3. `startAgent` + `streamAgent` → `chat`
+
+There is no session token any more. The key is the credential, and a `conversationId` is the thread.
+
+```diff
+- const session = await client.startAgent(AGENT_ID, { visitor: "user_123" });
+- for await (const ev of client.streamAgent(session.agentId, {
+-   sessionToken: session.sessionToken,
+-   query: "What is the refund policy?",
+- })) {
+-   if (ev.type === "done") console.log(ev.output);
+- }
++ let conversationId: string | undefined;
++ let answer = "";
++ for await (const ev of client.chat("support-agent", "What is the refund policy?")) {
++   if (ev.type === "conversation") conversationId = ev.id;
++   if (ev.type === "token") answer += ev.content;      // the answer arrives in deltas
++ }
++ console.log(answer);
 ```
 
-### Node.js / Express API
+Other differences to expect:
 
-```js
-import express from "express";
-import { PromptevClient } from "@promptev/client";
+- **Agents are addressed by slug**, not by a UUID from the Deploy tab.
+- **Events changed shape.** There is no `event.output`; the answer arrives as `token` deltas that you concatenate, and `done` carries no text. See the [events table](#events). `thoughts` is now `thinking`; `processing` is now `step` / `tool_call` / `tool_result`.
+- **`visitor` is now `onBehalfOf`**, and it does more than label a session — see [On behalf of your users](#on-behalf-of-your-users).
+- **`variables` is gone.** Prompt variables were a property of the old product's templates; configure the agent's instructions in Promptev instead, or put the context in the message.
+- **`approval_required` is real now.** The old SDK had no concept of a paused turn. Handle it.
 
-const app = express();
-const client = new PromptevClient({ projectKey: "pv_sk_..." });
+### 4. `triggerAgent` → the project MCP server
 
-app.post("/api/ask", express.json(), async (req, res) => {
-  const answer = await client.runPrompt("support-agent", req.body.question);
-  res.json({ answer });
-});
+`triggerAgent` — one blocking call that ran the agent and returned JSON — has **no equivalent in this client**. The 1.0 chat endpoint only streams, and faking a blocking call by draining the stream would silently swallow `approval_required`, leaving your integration hung with no way to know why.
 
-app.listen(3000);
+Use Promptev's **project MCP server** instead, which is exactly the shape `trigger` was:
+
+```
+POST https://api.promptev.ai/api/v1/mcp
+Authorization: Bearer fk_...          ← the same key
 ```
 
-### Vanilla HTML
+It exposes `list_agents` and `call_agent`; `call_agent(agent, message)` runs an agent and returns its answer in one call. A gated tool comes back as `status: "pending_approval"` with an id — decide it in Promptev and call again. Any MCP client works, including n8n's MCP Client node, Zapier, and Claude.
 
-```html
-<script type="module">
-  import { PromptevClient } from "https://cdn.jsdelivr.net/npm/@promptev/client/dist/esm/index.js";
+If you would rather stay in this client, collect the answer yourself — and handle the pause:
 
-  const client = new PromptevClient({ projectKey: "pv_sk_..." });
+```ts
+async function ask(slug: string, message: string, conversationId?: string) {
+  let answer = "";
+  const waiting: string[] = [];
+  for await (const ev of client.chat(slug, message, { conversationId })) {
+    if (ev.type === "conversation") conversationId = ev.id;
+    if (ev.type === "token") answer += ev.content;
+    if (ev.type === "approval_required") waiting.push(ev.tool_name);
+    if (ev.type === "error") throw new Error(ev.message);
+  }
+  return { answer, conversationId, waitedOn: waiting };
+}
+```
 
-  document.getElementById("ask-btn").addEventListener("click", async () => {
-    const answer = await client.runPrompt("support-agent", "What is the refund policy?");
-    document.getElementById("output").textContent = answer;
-  });
-</script>
+### 5. What did not change
+
+The typed error hierarchy, the retry/backoff configuration (`timeout`, `maxRetries`, `headers`), and the SSE parsing all behave as they did. `InsufficientCreditsError` (402) and `err.field` are new; nothing was removed.
+
+## Building from source
+
+```bash
+npm install
+npm run build   # builds both ESM (dist/esm) and CommonJS (dist/cjs)
+npm test        # runs the offline test suite against the built output
 ```
 
 ## License
 
-This SDK is commercial software by [Promptev Inc](https://promptev.ai).
+This client is commercial software by [Promptev Inc](https://promptev.ai).
 
 - Free tier use allowed
 - Production use requires an active subscription