@promptev/client 1.1.0 → 1.3.0

package/dist/cjs/index.cjs

@@ -12,7 +12,7 @@
  *   - `uploadDocument()`  — put files into the key's project corpus.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.PromptevClient = exports.NetworkError = exports.ServerError = exports.InsufficientCreditsError = exports.RateLimitError = exports.NotFoundError = exports.AuthenticationError = exports.ValidationError = exports.PromptevError = exports.KNOWLEDGE_ACTIONS = 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
@@ -39,6 +39,13 @@ 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;
+/** The knowledge base's actions, as the project MCP's `search_knowledge_base`
+ *  offers them. Informational: the server decides, so an action added there
+ *  works here without a new SDK. */
+exports.KNOWLEDGE_ACTIONS = [
+    "discover", "search", "get_doc", "list", "query_meta", "compute", "get_chunks",
+    "get_docs", "map_reduce", "traverse", "find_related", "get_neighbors", "community_summary",
+];
 // ── Errors ──────────────────────────────────────────────
 class PromptevError extends Error {
     constructor(message, statusCode, responseText, field) {
@@ -305,8 +312,8 @@ class PromptevClient {
      * @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.
+     * @param message What to say. Non-empty after trimming unless
+     *   `options.files` are sent, at most {@link MAX_MESSAGE_CHARS} characters.
      *
      * @example Stream the answer
      * ```ts
@@ -333,10 +340,11 @@ class PromptevClient {
             throw new ValidationError("Name the agent to talk to.", undefined, undefined, "agentSlug");
         }
         const text = String(message ?? "").trim();
-        if (!text) {
+        const files = options?.files ?? [];
+        if (!text && files.length === 0) {
             // 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");
+            throw new ValidationError("Say something to the agent, or attach a file.", 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");
@@ -359,11 +367,7 @@ class PromptevClient {
         // POST could run the agent, and its tools, a second time.
         const resp = await this.fetchOnce(url, {
             method: "POST",
-            headers: this.authHeaders({
-                "Content-Type": "application/json",
-                Accept: "text/event-stream",
-            }),
-            body: JSON.stringify(payload),
+            ...chatBody(payload, files, (extra) => this.authHeaders(extra)),
             signal: options?.signal,
         });
         if (resp.status >= 400) {
@@ -462,6 +466,43 @@ class PromptevClient {
      * );
      * ```
      */
+    /**
+     * Read the key's project knowledge base through the Context Engine: the
+     * same tool, with the same actions, as `search_knowledge_base` on the
+     * project's MCP server (`POST /api/v1/knowledge`).
+     *
+     * ```ts
+     * const overview = await client.searchKnowledgeBase("discover");
+     * const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
+     * for (const hit of found.hits) console.log(hit.document_name, hit.chunk_text);
+     * const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });
+     * ```
+     *
+     * `fields` are that action's fields (`query`, `top_k`, `document_id`,
+     * `source_ids`, `mode`, `limit`, `cursor`, ...); undefined and null ones
+     * are not sent. Returns the knowledge base's answer as an object.
+     */
+    async searchKnowledgeBase(action, fields = {}, options) {
+        if (typeof action !== "string" || !action.trim()) {
+            throw new ValidationError('Name the action, e.g. "search".', undefined, undefined, "action");
+        }
+        const body = { action: action.trim() };
+        for (const [key, value] of Object.entries(fields ?? {})) {
+            if (value !== undefined && value !== null)
+                body[key] = value;
+        }
+        const headers = this.authHeaders();
+        headers["Content-Type"] = "application/json";
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/api/v1/knowledge`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: options?.signal,
+        });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text, resp.headers);
+        return text ? JSON.parse(text) : {};
+    }
     async runOrchestration(slug, inputs = {}, options) {
         if (!slug || !slug.trim()) {
             throw new ValidationError("Name the orchestration to run.", undefined, undefined, "slug");
@@ -536,6 +577,33 @@ class PromptevClient {
     }
 }
 exports.PromptevClient = PromptevClient;
+/**
+ * The body of a chat call: JSON when there are no files; MULTIPART when there
+ * are, the JSON in a `payload` part and each file in a `files` part. Count and
+ * size are judged here, before the wire.
+ */
+function chatBody(payload, files, headers) {
+    if (files.length === 0) {
+        return {
+            headers: headers({ "Content-Type": "application/json", Accept: "text/event-stream" }),
+            body: JSON.stringify(payload),
+        };
+    }
+    if (files.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");
+    }
+    const form = new FormData();
+    form.append("payload", JSON.stringify(payload));
+    for (const file of files) {
+        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, "files");
+        }
+        form.append("files", blob, name);
+    }
+    // NO Content-Type — fetch sets the multipart boundary itself.
+    return { headers: headers({ Accept: "text/event-stream" }), body: form };
+}
 /** One upload input, as a named Blob — the only shape `FormData` accepts. */
 function toBlob(file) {
     if (typeof Blob !== "undefined" && file instanceof Blob) {

package/dist/esm/index.d.ts

@@ -35,6 +35,11 @@ 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;
+/** The knowledge base's actions, as the project MCP's `search_knowledge_base`
+ *  offers them. Informational: the server decides, so an action added there
+ *  works here without a new SDK. */
+export declare const KNOWLEDGE_ACTIONS: readonly ["discover", "search", "get_doc", "list", "query_meta", "compute", "get_chunks", "get_docs", "map_reduce", "traverse", "find_related", "get_neighbors", "community_summary"];
+export type KnowledgeAction = (typeof KNOWLEDGE_ACTIONS)[number];
 export interface PromptevClientConfig {
     /**
      * Your Promptev API key — `fk_…`, minted in Settings → API keys of the
@@ -127,6 +132,16 @@ export interface ChatOptions {
      * keyed by tool id (shown on the tool's page) — see {@link ToolInput}.
      */
     toolInputs?: Record<string, ToolInput>;
+    /**
+     * Files for the agent to read on this turn, sent in the same call: at most
+     * {@link MAX_FILES_PER_RUN}, each at most 25 MB. Accepted only when the
+     * agent's "Chat attachments" is on (409 otherwise), and only the types the
+     * promptev chat takes (415 otherwise). An image is shown to a model that can
+     * see, and read into text for one that cannot. A document is read before
+     * the answer starts, so a long scan makes a slower first event. With files,
+     * `message` may be empty.
+     */
+    files?: UploadInput[];
     /** Abort the turn from your own signal (in addition to the client timeout). */
     signal?: AbortSignal;
 }
@@ -451,8 +466,8 @@ export declare class PromptevClient {
      * @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.
+     * @param message What to say. Non-empty after trimming unless
+     *   `options.files` are sent, at most {@link MAX_MESSAGE_CHARS} characters.
      *
      * @example Stream the answer
      * ```ts
@@ -529,6 +544,25 @@ export declare class PromptevClient {
      * );
      * ```
      */
+    /**
+     * Read the key's project knowledge base through the Context Engine: the
+     * same tool, with the same actions, as `search_knowledge_base` on the
+     * project's MCP server (`POST /api/v1/knowledge`).
+     *
+     * ```ts
+     * const overview = await client.searchKnowledgeBase("discover");
+     * const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
+     * for (const hit of found.hits) console.log(hit.document_name, hit.chunk_text);
+     * const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });
+     * ```
+     *
+     * `fields` are that action's fields (`query`, `top_k`, `document_id`,
+     * `source_ids`, `mode`, `limit`, `cursor`, ...); undefined and null ones
+     * are not sent. Returns the knowledge base's answer as an object.
+     */
+    searchKnowledgeBase(action: KnowledgeAction | (string & {}), fields?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<Record<string, any>>;
     runOrchestration(slug: string, inputs?: RunInputs, options?: RunOptions): Promise<StartedRun>;
     /**
      * What became of a run — poll this after {@link runOrchestration}.

package/dist/esm/index.js

@@ -36,6 +36,13 @@ export const 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`. */
 export const MAX_FILES_PER_RUN = 5;
+/** The knowledge base's actions, as the project MCP's `search_knowledge_base`
+ *  offers them. Informational: the server decides, so an action added there
+ *  works here without a new SDK. */
+export const KNOWLEDGE_ACTIONS = [
+    "discover", "search", "get_doc", "list", "query_meta", "compute", "get_chunks",
+    "get_docs", "map_reduce", "traverse", "find_related", "get_neighbors", "community_summary",
+];
 // ── Errors ──────────────────────────────────────────────
 export class PromptevError extends Error {
     constructor(message, statusCode, responseText, field) {
@@ -294,8 +301,8 @@ export class PromptevClient {
      * @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.
+     * @param message What to say. Non-empty after trimming unless
+     *   `options.files` are sent, at most {@link MAX_MESSAGE_CHARS} characters.
      *
      * @example Stream the answer
      * ```ts
@@ -322,10 +329,11 @@ export class PromptevClient {
             throw new ValidationError("Name the agent to talk to.", undefined, undefined, "agentSlug");
         }
         const text = String(message ?? "").trim();
-        if (!text) {
+        const files = options?.files ?? [];
+        if (!text && files.length === 0) {
             // 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");
+            throw new ValidationError("Say something to the agent, or attach a file.", undefined, undefined, "message");
         }
         if (text.length > MAX_MESSAGE_CHARS) {
             throw new ValidationError(`A message can be at most ${MAX_MESSAGE_CHARS} characters.`, undefined, undefined, "message");
@@ -348,11 +356,7 @@ export class PromptevClient {
         // POST could run the agent, and its tools, a second time.
         const resp = await this.fetchOnce(url, {
             method: "POST",
-            headers: this.authHeaders({
-                "Content-Type": "application/json",
-                Accept: "text/event-stream",
-            }),
-            body: JSON.stringify(payload),
+            ...chatBody(payload, files, (extra) => this.authHeaders(extra)),
             signal: options?.signal,
         });
         if (resp.status >= 400) {
@@ -451,6 +455,43 @@ export class PromptevClient {
      * );
      * ```
      */
+    /**
+     * Read the key's project knowledge base through the Context Engine: the
+     * same tool, with the same actions, as `search_knowledge_base` on the
+     * project's MCP server (`POST /api/v1/knowledge`).
+     *
+     * ```ts
+     * const overview = await client.searchKnowledgeBase("discover");
+     * const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
+     * for (const hit of found.hits) console.log(hit.document_name, hit.chunk_text);
+     * const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });
+     * ```
+     *
+     * `fields` are that action's fields (`query`, `top_k`, `document_id`,
+     * `source_ids`, `mode`, `limit`, `cursor`, ...); undefined and null ones
+     * are not sent. Returns the knowledge base's answer as an object.
+     */
+    async searchKnowledgeBase(action, fields = {}, options) {
+        if (typeof action !== "string" || !action.trim()) {
+            throw new ValidationError('Name the action, e.g. "search".', undefined, undefined, "action");
+        }
+        const body = { action: action.trim() };
+        for (const [key, value] of Object.entries(fields ?? {})) {
+            if (value !== undefined && value !== null)
+                body[key] = value;
+        }
+        const headers = this.authHeaders();
+        headers["Content-Type"] = "application/json";
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/api/v1/knowledge`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: options?.signal,
+        });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text, resp.headers);
+        return text ? JSON.parse(text) : {};
+    }
     async runOrchestration(slug, inputs = {}, options) {
         if (!slug || !slug.trim()) {
             throw new ValidationError("Name the orchestration to run.", undefined, undefined, "slug");
@@ -524,6 +565,33 @@ export class PromptevClient {
         return JSON.parse(text);
     }
 }
+/**
+ * The body of a chat call: JSON when there are no files; MULTIPART when there
+ * are, the JSON in a `payload` part and each file in a `files` part. Count and
+ * size are judged here, before the wire.
+ */
+function chatBody(payload, files, headers) {
+    if (files.length === 0) {
+        return {
+            headers: headers({ "Content-Type": "application/json", Accept: "text/event-stream" }),
+            body: JSON.stringify(payload),
+        };
+    }
+    if (files.length > MAX_FILES_PER_RUN) {
+        throw new ValidationError(`At most ${MAX_FILES_PER_RUN} files can be sent with one call.`, undefined, undefined, "files");
+    }
+    const form = new FormData();
+    form.append("payload", JSON.stringify(payload));
+    for (const file of files) {
+        const [name, blob] = toBlob(file);
+        if (blob.size > MAX_UPLOAD_BYTES) {
+            throw new ValidationError(`${name}: larger than ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB — add bigger files to the agent's knowledge instead.`, undefined, undefined, "files");
+        }
+        form.append("files", blob, name);
+    }
+    // NO Content-Type — fetch sets the multipart boundary itself.
+    return { headers: headers({ Accept: "text/event-stream" }), body: form };
+}
 /** One upload input, as a named Blob — the only shape `FormData` accepts. */
 function toBlob(file) {
     if (typeof Blob !== "undefined" && file instanceof Blob) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptev/client",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "JavaScript/TypeScript client for Promptev — stream your AI agents and upload documents with a workspace API key",
   "type": "module",
   "main": "./dist/cjs/index.cjs",

package/readme.md

@@ -1,6 +1,6 @@
 # Promptev JavaScript client
 
-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`.
+The official JavaScript/TypeScript client for [Promptev](https://promptev.ai) — stream your AI **agents**, put documents into the Context Engine and search it, 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.
 
@@ -105,6 +105,28 @@ Passing `conversationId` is worth doing for a second reason: a tool set to **Ask
 
 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.
 
+## Sending files with a message
+
+Pass `files` and the agent reads them on that turn, in the same call. This is the paperclip of the promptev chat: the agent takes files only when **Chat attachments** is switched on in its builder, and only the types that chat takes.
+
+```ts
+import { readFile } from "node:fs/promises";
+
+for await (const ev of client.chat("support-agent", "What is the total on this receipt?", {
+  files: [{ name: "receipt.png", content: await readFile("receipt.png") }],   // or a File / Blob
+})) {
+  if (ev.type === "token") process.stdout.write(ev.content);
+}
+```
+
+Up to **five files per call**, 25 MB each. An image is shown to a model that can see, and read into text for one that cannot. A document is read before the answer starts, so a long scan makes a slower first event. A call may carry files and an empty message.
+
+| Status | When |
+|---|---|
+| 409 | The agent's Chat attachments is off |
+| 415 | A file type the agent cannot take |
+| 413 | The workspace is out of storage |
+
 ## Changing the model or a tool's values for one call
 
 Both options are optional. Leave them out and the agent runs exactly as it was published. Nothing a call sends is stored: the next call runs the published agent again.
@@ -252,6 +274,25 @@ A per-file failure is *reported*, not thrown: every file gets a row in `results`
 
 > 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 })`.
 
+## `searchKnowledgeBase` — search the knowledge base
+
+```ts
+client.searchKnowledgeBase(action, fields?, options?): Promise<Record<string, any>>
+```
+
+Reads your key's project knowledge base through the Context Engine. It is the same tool, with the same actions, as `search_knowledge_base` on the project's MCP server. Start with `discover` to see what is there, then `search` for passages or `get_doc` for one document:
+
+```ts
+const overview = await client.searchKnowledgeBase("discover");
+
+const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
+for (const hit of found.hits) console.log(hit.document_name, hit.score, hit.chunk_text);
+
+const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });
+```
+
+The actions are exported as `KNOWLEDGE_ACTIONS`: `discover`, `search`, `get_doc`, `list`, `query_meta`, `compute`, `get_chunks`, `get_docs`, `map_reduce`, `traverse`, `find_related`, `get_neighbors` and `community_summary`. `fields` are that action's fields (`query`, `top_k`, `document_id`, `source_ids`, `mode`, `limit`, `cursor`, ...). The key reads only its own project.
+
 ## `runOrchestration` — run a team of agents
 
 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.
@@ -372,9 +413,7 @@ All errors extend `PromptevError` and carry:
 ## 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.
+same for every workspace, including one on its own database or models.
 
 | what happens | credits |
 |---|---|
@@ -384,6 +423,7 @@ already yours.
 | 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) |
+| `searchKnowledgeBase` | the same as on the MCP server: **1** per call, **+1** for a search (**+5** when the graph is searched); no `api_call` charge |
 
 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