@promptev/client 0.2.0 → 1.0.0

package/dist/esm/index.d.ts

@@ -1,104 +1,511 @@
+/**
+ * @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.
+ */
+/**
+ * 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.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.promptev.ai";
+/** The server's own ceiling on one message (`ApiChatBody.message`). */
+export declare const MAX_MESSAGE_CHARS = 20000;
+/** `uploads.MAX_FILES_PER_REQUEST` — files in ONE upload request. */
+export declare const MAX_FILES_PER_REQUEST = 20;
+/** `file_types.MAX_UPLOAD_BYTES` — 25 MB per file. */
+export declare const MAX_UPLOAD_BYTES: number;
+/** Files ONE orchestration run may carry — the same ceiling a chat turn has.
+ *  Server-side: `run_inputs.MAX_FILE_PARTS`. */
+export declare const MAX_FILES_PER_RUN = 5;
 export interface PromptevClientConfig {
-    projectKey: string;
+    /**
+     * Your Promptev API key — `fk_…`, minted in Settings → API keys of the
+     * project it may reach. It is sent as `Authorization: Bearer <key>`, never
+     * in a URL, and it carries the retrieval identity the agent answers under.
+     */
+    apiKey: string;
+    /** Override for self-hosted / staging. Defaults to {@link DEFAULT_BASE_URL}. */
     baseUrl?: string;
+    /** Extra HTTP headers on every request. */
     headers?: Record<string, string>;
+    /**
+     * Milliseconds to wait for the response HEADERS. A `chat()` stream is not
+     * bounded by it — once the response arrives the timer is cleared, because a
+     * turn that runs tools (or waits for an approval) legitimately outlives any
+     * request timeout.
+     */
     timeout?: number;
+    /** Retries for transient server errors (502/503/504) on non-streaming calls. */
     maxRetries?: number;
 }
-export interface AgentSession {
-    sessionToken: string;
-    agentId: string;
+/**
+ * Assert, on this one call, WHICH end user your backend is acting for.
+ *
+ * The key's grant is a ceiling and this only ever narrows within it: the
+ * groups you assert are intersected with the key's `grp:` grants, and the
+ * key's `user:` grants drop entirely the moment an assertion is present. A
+ * compromised caller therefore cannot read beyond what the key was granted.
+ * `subject` is recorded as the conversation's actor for the audit trail; it is
+ * not verified by the server, so it never widens anything.
+ */
+export interface OnBehalfOf {
+    /** Who you are acting for — an email or a stable user id (1–320 chars). */
+    subject: string;
+    /** The end user's groups, as your system knows them. Omit for the key's full grant. */
+    groups?: string[];
+}
+export interface ChatOptions {
+    /**
+     * Continue an existing thread. Read it off the first `conversation` event
+     * and pass it back on the next turn. Omit to start a new conversation.
+     *
+     * Worth passing: with a tool's "Ask once" approval mode the agent asks on
+     * the FIRST call in a conversation and not again for the rest of it, so a
+     * continued thread sees far fewer `approval_required` events.
+     *
+     * A thread belongs to the agent, to this API surface, AND to the
+     * `onBehalfOf.subject` it was opened under — so keep the subject the same
+     * across the turns of one conversation, and never pass an id from the app,
+     * the portal or an embed. Any mismatch answers 404, not a new thread.
+     */
+    conversationId?: string;
+    /** Act for one of your end users — see {@link OnBehalfOf}. */
+    onBehalfOf?: OnBehalfOf;
+    /** Abort the turn from your own signal (in addition to the client timeout). */
+    signal?: AbortSignal;
+}
+export interface UploadOptions {
+    /**
+     * How the document is indexed. `"hybrid"` (the default) or `"graph"`.
+     * `"graph"` needs a graph database and an extraction model configured for
+     * the workspace, or the server answers 422.
+     */
+    mode?: "hybrid" | "graph";
+    /** Abort the upload from your own signal. */
+    signal?: AbortSignal;
+}
+/**
+ * A file to upload. Either a web `File`/`Blob`, or a plain object naming its
+ * bytes — which is what you want in Node, where `File` is awkward:
+ *
+ * ```ts
+ * await client.uploadDocument({ name: "handbook.pdf", content: await readFile(path) });
+ * ```
+ */
+export type UploadInput = Blob | {
+    /** The filename the corpus stores it under — the extension picks the parser. */
+    name: string;
+    content: Blob | ArrayBuffer | ArrayBufferView | string;
+    /** Optional MIME type; the server decides from the name either way. */
+    type?: string;
+};
+/** One file's outcome — a batch reports every file, failures included. */
+export interface UploadResult {
+    filename: string;
+    /** What the engine made of it — `"indexed"`, `"failed"`, … */
+    status: string;
+    /** The corpus id, or `null` when the file did not land. */
+    document_id: string | null;
+    chunks: number;
+    units: number;
+    /** Why this file failed, or `null`. */
+    error: string | null;
+}
+export interface UploadResponse {
+    results: UploadResult[];
+}
+/** First frame of every stream: the id that continues this thread. */
+export interface ConversationEvent {
+    type: "conversation";
+    /** Pass as `conversationId` on the next `chat()` call. */
+    id: string;
+}
+/**
+ * One delta of the model's REASONING — not the answer. Never concatenate it
+ * into the reply; render it separately, or ignore it.
+ *
+ * Emitted only by models that actually stream thinking (Anthropic with a
+ * thinking budget, Gemini, the OpenAI Responses API) — many turns carry none.
+ */
+export interface ThinkingEvent {
+    type: "thinking";
+    content: string;
+}
+/**
+ * ONE delta of the answer. Concatenating every `token.content` in order gives
+ * the agent's complete reply.
+ */
+export interface TokenEvent {
+    type: "token";
+    content: string;
+}
+/** A stage of the turn — reading attachments, retrieving, waiting on an emailed approval. */
+export interface StepEvent {
+    type: "step";
     name: string;
-    memoryEnabled: boolean;
-    messages: Record<string, any>[];
+    status: "started" | "completed" | "failed";
+    detail?: string;
+    /** Set on the "waiting for approval — <tool>" step an EMAIL approval opens. */
+    tool_name?: string;
+    channel?: string;
+}
+/** Where the answer is grounded — one entry per retrieved document. */
+export interface SourcesEvent {
+    type: "sources";
+    items: {
+        name: string;
+        document_id: string;
+    }[];
+}
+/** The agent decided to run a tool. `id` correlates with its `tool_result`. */
+export interface ToolCallEvent {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args?: Record<string, unknown>;
+}
+/** That tool answered. `ok: false` is a failure the agent will go on to explain. */
+export interface ToolResultEvent {
+    type: "tool_result";
+    id: string;
+    name: string;
+    ok: boolean;
+    /** A one-line summary of the result — never the full payload. */
+    summary?: string;
+    /** How an approval ended, when the tool was gated: rejected / timeout / expired. */
+    approval?: string;
+}
+/**
+ * THE TURN IS PAUSED, WAITING FOR A HUMAN.
+ *
+ * A tool the agent wants to run is gated on approval. The stream stays OPEN: a
+ * person approves it in the Promptev app, by email, or in Slack, and the turn
+ * then continues on this same connection — you never re-send the message. If
+ * nobody decides in time the approval expires and the turn reports it as a
+ * failed `tool_result` (`approval: "expired"`).
+ *
+ * Handle this event. An integration that ignores it looks hung to its user for
+ * as long as the approval window lasts, which is the single most common
+ * support ticket this API generates. At minimum, tell your user what is being
+ * asked and who has to decide it.
+ *
+ * NOT every gated tool sends this event. `channel` is only ever `"inline"` or
+ * `"slack"` — somewhere a human is already looking. A tool whose approval is
+ * routed to an APPROVER BY EMAIL sends no card at all: it streams a
+ * {@link StepEvent} named `waiting for approval — <tool>` instead, which
+ * closes when the decision lands. Code that waits only for
+ * `approval_required` would wait forever on those.
+ *
+ * Passing `conversationId` on follow-up turns materially reduces how often you
+ * see it: a tool set to "Ask once" asks on the first call in a conversation and
+ * not again for the rest of it.
+ */
+export interface ApprovalRequiredEvent {
+    type: "approval_required";
+    /** The pending approval's id — the same one the approver decides in Promptev. */
+    approval_id: string;
+    /** The tool waiting to run. */
+    tool_name: string;
+    /** The arguments it would run with — show these to whoever has to decide. */
+    args?: Record<string, unknown>;
+    /** Why approval is being asked for, in the operator's own words. */
+    reason?: string;
+    /**
+     * Where a human can decide it — `"inline"` (in the Promptev app) or
+     * `"slack"`. Never `"email"`: see this event's note above.
+     */
+    channel?: "inline" | "slack";
+    /** ISO-8601 deadline, after which the approval expires and the tool fails. */
+    expires_at?: string;
+}
+/**
+ * A file the agent produced this turn (`generate_file`). This surface carries
+ * no download link — open the conversation in Promptev to fetch the file, or
+ * have the agent put what you need in its answer.
+ */
+export interface ArtifactEvent {
+    type: "artifact";
+    id: string;
+    kind: string;
+    name: string;
+    mime: string;
+    size: number;
+    exports?: unknown[];
+    /** Only on surfaces that mint signed links; absent on `/api/v1`. */
+    url?: string;
+}
+/** 2–3 follow-ups the same person would plausibly ask next. Only when the agent has suggestions on. */
+export interface SuggestionsEvent {
+    type: "suggestions";
+    questions: string[];
 }
-export interface TriggerResult {
-    response: string;
-    sessionId: string;
+/** What the turn cost, emitted just before `done`. */
+export interface UsageEvent {
+    type: "usage";
+    /** Credit units: one for the turn plus one per executed tool call. */
+    units: number;
+    /** Provider token counts, when the provider reported them. */
+    tokens?: Record<string, unknown>;
+    tool_calls?: number;
 }
-export interface AgentEvent {
+/** The stream finished cleanly. Nothing follows it. */
+export interface DoneEvent {
+    type: "done";
+}
+/** The turn failed mid-stream. Nothing follows it. */
+export interface ErrorEvent {
+    type: "error";
+    message: string;
+}
+/**
+ * A frame from a NEWER server than this client knows about.
+ *
+ * Unknown types are yielded, never thrown on: a server that adds an event must
+ * not break an integration that had nothing to do with the deploy. Such a
+ * frame arrives typed as {@link AgentEvent} — its `type` simply matches none of
+ * the cases you handle. Cast it if you want its fields:
+ *
+ * ```ts
+ * default: console.log("new event:", (ev as UnknownEvent).type);
+ * ```
+ */
+export interface UnknownEvent {
     type: string;
-    output: string;
-    raw: Record<string, any>;
+    [key: string]: unknown;
 }
+/**
+ * Every frame `chat()` can yield. Narrow on `type`.
+ *
+ * The union names what today's server emits, so narrowing gives you real field
+ * types. A frame from a newer server still reaches you at runtime — see
+ * {@link UnknownEvent}.
+ */
+export type AgentEvent = ConversationEvent | ThinkingEvent | TokenEvent | StepEvent | SourcesEvent | ToolCallEvent | ToolResultEvent | ApprovalRequiredEvent | ArtifactEvent | SuggestionsEvent | UsageEvent | DoneEvent | ErrorEvent;
+/** The named event types — the vocabulary, for switch tables and filters. */
+export type AgentEventType = "conversation" | "thinking" | "token" | "step" | "sources" | "tool_call" | "tool_result" | "approval_required" | "artifact" | "suggestions" | "usage" | "done" | "error";
 export declare class PromptevError extends Error {
     statusCode?: number;
     responseText?: string;
-    constructor(message: string, statusCode?: number, responseText?: string);
+    /** Which request field the server objected to, when it named one. */
+    field?: string;
+    constructor(message: string, statusCode?: number, responseText?: string, field?: string);
 }
+/** 400/422 — the request itself was wrong. `field` says which part. */
 export declare class ValidationError extends PromptevError {
-    constructor(message: string, statusCode?: number, responseText?: string);
+    name: string;
 }
+/** 401/403 — the key is missing, malformed, revoked or expired. */
 export declare class AuthenticationError extends PromptevError {
-    constructor(message: string, statusCode?: number, responseText?: string);
+    name: string;
 }
+/**
+ * 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.
+ */
 export declare class NotFoundError extends PromptevError {
-    constructor(message: string, statusCode?: number, responseText?: string);
+    name: string;
 }
+/** 429 — too many requests. `retryAfter` is the server's own answer, in seconds. */
 export declare class RateLimitError extends PromptevError {
-    constructor(message: string, statusCode?: number, responseText?: string);
+    name: string;
+    /** Seconds to wait, from the `Retry-After` header, when the server sent one. */
+    retryAfter?: number;
+    constructor(message: string, statusCode?: number, responseText?: string, field?: string, retryAfter?: number);
+}
+/**
+ * 402 — the workspace is out of credits. Not a rate limit: waiting does not
+ * fix it, a top-up does.
+ */
+export declare class InsufficientCreditsError extends PromptevError {
+    name: string;
 }
+/** 5xx — the server failed, after the client's retries were exhausted. */
 export declare class ServerError extends PromptevError {
-    constructor(message: string, statusCode?: number, responseText?: string);
+    name: string;
 }
+/** The request never got an answer: DNS, connection, abort, or the client timeout. */
 export declare class NetworkError extends PromptevError {
-    constructor(message: string, statusCode?: number, responseText?: string);
+    name: string;
+}
+/** What an orchestration takes: its own declared input keys. Values are plain
+ *  scalars or flat lists of them — the shape the server bounds (50 keys, 64-char
+ *  names, lists of 100, 64 KB). Files do NOT go in here; they are their own
+ *  parts, keyed by the input they fill. */
+export type RunInputs = Record<string, unknown>;
+export interface RunOptions {
+    /** Files for inputs declared `File(s)`, keyed by the input's key — the part
+     *  is NAMED after the input it fills, which is what lets one call fill two
+     *  different file inputs. */
+    files?: Record<string, UploadInput | UploadInput[]>;
+    /** Send one and a retry returns the run you already started instead of
+     *  running the team twice. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export interface StartedRun {
+    /** Pass this to {@link PromptevClient.getRun}. */
+    run_id: string;
+    status: "accepted";
+}
+export interface RunStatus {
+    run_id: string;
+    /** The orchestration's slug. */
+    orchestration: string;
+    /** `running` · `awaiting_review` · `revising` · `delivered` · `failed`. */
+    status: string;
+    created_at: string | null;
+    /** Present only once there IS one — a half-written answer read mid-run is
+     *  worse than none, because a caller would act on a draft. */
+    output?: string;
+    error?: string;
 }
 export declare class PromptevClient {
-    private projectKey;
+    private apiKey;
     private baseUrl;
     private headers;
     private timeout;
     private maxRetries;
     constructor(config: PromptevClientConfig);
+    /**
+     * 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.
+     */
     private static raiseForStatus;
+    private authHeaders;
     private fetchWithRetry;
+    /**
+     * 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.
+     */
+    private fetchOnce;
     private parseSSE;
     /**
-     * Trigger an agent in a single blocking call — the primary way to use the SDK.
+     * 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.
+     *
+     * @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);
+     * }
+     * ```
+     */
+    chat(agentSlug: string, message: string, options?: ChatOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * 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.
      *
-     * Creates (or resumes) a session AND runs the agent, returning the final
-     * response as JSON. Any tools the agent has attached run server-side.
+     * 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.
      *
-     * @param agentId - Your agent's id (from the Deploy tab).
-     * @param message - The user message to send to the agent.
-     * @param opts.sessionId - Pass the `sessionId` from a previous call to keep
-     *   conversation memory. Omit it for a fresh, stateless run.
-     * @param opts.variables - Object filling the agent's `{{...}}` prompt variables.
-     * @returns `{ response, sessionId }` — pass `sessionId` back on the next call
-     *   to continue the same conversation.
+     * 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
-     * const { response, sessionId } = await client.triggerAgent(
-     *   "your-agent-id",
-     *   "What is the refund policy?",
-     *   { variables: { company: "Acme Corp" } }
+     * ```ts
+     * import { readFile } from "node:fs/promises";
+     *
+     * const { results } = await client.uploadDocument(
+     *   { name: "handbook.pdf", content: await readFile("handbook.pdf") },
+     *   { mode: "hybrid" }
      * );
-     * // Follow-up keeps memory:
-     * await client.triggerAgent("your-agent-id", "And for digital goods?", { sessionId });
+     * for (const r of results) console.log(r.filename, r.status, r.error ?? "");
+     * ```
      */
-    triggerAgent(agentId: string, message: string, opts?: {
-        sessionId?: string;
-        variables?: Record<string, any>;
-        visitor?: string;
-    }): Promise<TriggerResult>;
+    uploadDocument(files: UploadInput | UploadInput[], options?: UploadOptions): Promise<UploadResponse>;
     /**
-     * Start a new agent chat session (streaming flow).
+     * 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.
      *
-     * @param agentId - Your agent's id (from the Deploy tab).
+     * ```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 } } },
+     * );
+     * ```
      */
-    startAgent(agentId: string, options?: {
-        visitor?: string;
-        platform?: string;
-    }): Promise<AgentSession>;
+    runOrchestration(slug: string, inputs?: RunInputs, options?: RunOptions): Promise<StartedRun>;
     /**
-     * Stream an agent response as SSE events.
+     * What became of a run — poll this after {@link runOrchestration}.
      *
-     * @param agentId - Your agent's id (from the Deploy tab).
+     * ```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);
+     * ```
      */
-    streamAgent(agentId: string, options: {
-        sessionToken: string;
-        query: string;
-    }): AsyncGenerator<AgentEvent>;
+    getRun(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RunStatus>;
 }
 export default PromptevClient;