@promptev/client 1.1.0 → 1.2.0

package/dist/cjs/index.cjs

@@ -305,8 +305,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 +333,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 +360,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) {
@@ -536,6 +533,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

@@ -127,6 +127,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 +461,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

package/dist/esm/index.js

@@ -294,8 +294,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 +322,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 +349,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) {
@@ -524,6 +521,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.2.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

@@ -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.