@eigenpal/sdk 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -1,11 +1,15 @@
 # @eigenpal/sdk
 
-## 0.5.4
+## 0.5.6
 
 ### Major Changes
 
 - c15ce88: Rename agent API calls to `/v1/agents` and scope execution helpers under their owning workflow or agent.
 
+### Minor Changes
+
+- d1d3260: `client.workflows.run` (and agent runs) now accept a Node readable stream (`fs.createReadStream('contract.pdf')`) as a file input, inferring the upload filename from the stream's path. Adds a `toFile(content, filename, mimeType?)` helper for attaching a filename to raw bytes (`Buffer`, `ArrayBuffer`, or `Blob`). Streams are drained to bytes before the request is sent, so a retried request can replay the body.
+
 ### Patch Changes
 
 - 5909b21: Add execution-scoped agent feedback filters and expected artifact management to the API, CLI, and SDKs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigenpal/sdk",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Official TypeScript SDK for the EigenPal API",
   "type": "module",
   "main": "./src/index.ts",

package/src/index.ts

@@ -32,7 +32,8 @@ export {
   EigenpalValidationError,
 } from './errors';
 
-export type { FileDescriptor, FileInput } from './lib/files';
+export { toFile } from './lib/files';
+export type { FileDescriptor, FileInput, NodeReadableStream } from './lib/files';
 export type {
   ListAgentExecutionsOptions,
   ListAgentsOptions,

package/src/lib/files.ts

@@ -1,25 +1,49 @@
 /**
- * File-input helpers for `client.workflows.run()`.
+ * File-input helpers for `client.workflows.run()` (and agent runs).
  *
- * Pass a `File`, `Blob`, or explicit `{ content, filename, mimeType }` triple
- * as a workflow input value. The SDK auto-detects file values and uploads
- * them as `multipart/form-data` — matching `curl -F`. No base64 needed.
+ * A workflow input value is treated as a file when it is one of:
+ *   - a Node readable stream — `fs.createReadStream('contract.pdf')`
+ *   - a `File` or `Blob`
+ *   - a `{ content, filename, mimeType? }` descriptor — build one with `toFile()`
+ *
+ * File values are auto-detected and uploaded as `multipart/form-data`
+ * (matching `curl -F`) — no base64 round-trip.
  */
 
+const DEFAULT_MIME = 'application/octet-stream';
+
+/** Common file extensions → MIME type, for upload filename inference. */
+const MIME_BY_EXT: Record<string, string> = {
+  pdf: 'application/pdf',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  txt: 'text/plain',
+  csv: 'text/csv',
+  json: 'application/json',
+  xml: 'application/xml',
+  html: 'text/html',
+  md: 'text/markdown',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+
+/** Guess a MIME type from a filename extension; falls back to octet-stream. */
+function guessMimeType(filename: string): string {
+  const ext = filename.includes('.') ? filename.split('.').pop()!.toLowerCase() : '';
+  return MIME_BY_EXT[ext] ?? DEFAULT_MIME;
+}
+
 /**
- * Explicit file descriptor — raw bytes plus metadata. Use when you have a
- * `Buffer` / `Uint8Array` / `ArrayBuffer` and want to set the filename /
- * mime type yourself (a bare `Blob` has no filename).
- *
- * ```ts
- * await client.workflows.run('extract-invoice', {
- *   contract_document: {
- *     content: buffer,
- *     filename: 'contract.pdf',
- *     mimeType: 'application/pdf',
- *   },
- * });
- * ```
+ * Explicit file descriptor — raw bytes plus metadata. Build one with
+ * `toFile()` when you have a `Buffer` / `Uint8Array` / `ArrayBuffer` / `Blob`
+ * in memory rather than a path or a stream.
  */
 export interface FileDescriptor {
   content: ArrayBuffer | ArrayBufferView | Blob;
@@ -28,27 +52,63 @@ export interface FileDescriptor {
 }
 
 /**
- * Any value that the SDK accepts as a "file" workflow input.
+ * A Node readable stream — typically `fs.createReadStream('contract.pdf')`.
+ * The SDK drains it and infers the upload filename from `path`.
  */
-export type FileInput = Blob | FileDescriptor;
+export interface NodeReadableStream extends AsyncIterable<unknown> {
+  /** Source path; used to infer the upload filename. */
+  readonly path?: string;
+}
 
-const DEFAULT_MIME = 'application/octet-stream';
+/** Any value the SDK accepts as a "file" workflow input. */
+export type FileInput = Blob | FileDescriptor | NodeReadableStream;
+
+/**
+ * Attach a filename (and optional MIME type) to raw bytes. The escape hatch
+ * for when you have a `Buffer` / `ArrayBuffer` / `Blob` in memory rather than
+ * a file path or stream.
+ *
+ * ```ts
+ * await client.workflows.run('extract-invoice', {
+ *   contract_document: toFile(buffer, 'contract.pdf'),
+ * });
+ * ```
+ */
+export function toFile(
+  content: ArrayBuffer | ArrayBufferView | Blob,
+  filename: string,
+  mimeType?: string
+): FileDescriptor {
+  return { content, filename, mimeType: mimeType ?? guessMimeType(filename) };
+}
+
+/** Detect a Node readable stream (`fs.createReadStream`, etc.). */
+function isReadStream(value: unknown): value is NodeReadableStream {
+  if (value === null || typeof value !== 'object') return false;
+  const v = value as Record<PropertyKey, unknown>;
+  return (
+    typeof v[Symbol.asyncIterator] === 'function' &&
+    (typeof v.pipe === 'function' || typeof v.read === 'function')
+  );
+}
+
+/** Detect an explicit `{ content, filename }` descriptor. */
+function isFileDescriptor(value: unknown): value is FileDescriptor {
+  if (value === null || typeof value !== 'object') return false;
+  const v = value as { content?: unknown; filename?: unknown };
+  return (
+    typeof v.filename === 'string' &&
+    v.content != null &&
+    (v.content instanceof ArrayBuffer ||
+      ArrayBuffer.isView(v.content) ||
+      (typeof Blob !== 'undefined' && v.content instanceof Blob))
+  );
+}
 
 export function isFileInput(value: unknown): value is FileInput {
   if (typeof Blob !== 'undefined' && value instanceof Blob) return true;
-  if (value !== null && typeof value === 'object') {
-    const v = value as { content?: unknown; filename?: unknown };
-    if (
-      typeof v.filename === 'string' &&
-      v.content != null &&
-      (v.content instanceof ArrayBuffer ||
-        ArrayBuffer.isView(v.content) ||
-        (typeof Blob !== 'undefined' && v.content instanceof Blob))
-    ) {
-      return true;
-    }
-  }
-  return false;
+  if (isReadStream(value)) return true;
+  return isFileDescriptor(value);
 }
 
 export function hasFileInput(input: Record<string, unknown> | undefined): boolean {
@@ -59,23 +119,45 @@ export function hasFileInput(input: Record<string, unknown> | undefined): boolea
   return false;
 }
 
-/** Convert a `FileInput` to `{ blob, filename }` for `FormData.append`. */
-function toBlobAndFilename(file: FileInput): { blob: Blob; filename: string } {
-  // File extends Blob, so the Blob branch covers it.
+/** Last path segment of a (possibly nested) file path. */
+function basename(path: string): string {
+  const segments = path.split(/[\\/]/);
+  return segments[segments.length - 1] || 'file';
+}
+
+/**
+ * Resolve a `FileInput` to a `{ blob, filename }` pair for `FormData.append`.
+ *
+ * Streams are drained to bytes *here* — eagerly, before the request is sent —
+ * so the body can be replayed if the SDK retries the request. (A consumed
+ * stream cannot be re-read; a Blob can.)
+ */
+async function resolveFileBlob(file: FileInput): Promise<{ blob: Blob; filename: string }> {
+  // `File` extends `Blob`, so this branch covers both.
   if (typeof Blob !== 'undefined' && file instanceof Blob) {
-    const name = (file as File).name ?? 'file';
-    return { blob: file, filename: name };
+    return { blob: file, filename: (file as File).name || 'file' };
+  }
+
+  // Node readable stream — drain it into a Blob now.
+  if (isReadStream(file)) {
+    const filename = typeof file.path === 'string' ? basename(file.path) : 'file';
+    const parts: BlobPart[] = [];
+    for await (const chunk of file) {
+      parts.push(chunk as BlobPart);
+    }
+    return { blob: new Blob(parts, { type: guessMimeType(filename) }), filename };
   }
+
+  // Explicit descriptor.
   const desc = file as FileDescriptor;
-  const content = desc.content;
   const type = desc.mimeType ?? DEFAULT_MIME;
-  let blob: Blob;
-  if (content instanceof Blob) {
-    blob = type && content.type !== type ? content.slice(0, content.size, type) : content;
-  } else {
-    // ArrayBuffer or ArrayBufferView — wrap in a Blob.
-    blob = new Blob([content as BlobPart], { type });
+  if (!(desc.content instanceof Blob)) {
+    // ArrayBuffer / ArrayBufferView — wrap the bytes in a typed Blob.
+    return { blob: new Blob([desc.content as BlobPart], { type }), filename: desc.filename };
   }
+  // Already a Blob — reuse it, re-slicing only to apply a different MIME type.
+  const blob =
+    desc.content.type === type ? desc.content : desc.content.slice(0, desc.content.size, type);
   return { blob, filename: desc.filename };
 }
 
@@ -86,38 +168,46 @@ export interface MultipartParts {
   fileCount: number;
 }
 
+/** Drain `input` into a FormData, appending each detected file as a field. */
+async function appendFiles(
+  fd: FormData,
+  input: Record<string, unknown> | undefined
+): Promise<{ scalars: Record<string, unknown>; fileCount: number }> {
+  const scalars: Record<string, unknown> = {};
+  let fileCount = 0;
+  for (const [key, value] of Object.entries(input ?? {})) {
+    if (isFileInput(value)) {
+      const { blob, filename } = await resolveFileBlob(value);
+      fd.append(key, blob, filename);
+      fileCount += 1;
+    } else {
+      scalars[key] = value;
+    }
+  }
+  return { scalars, fileCount };
+}
+
 /**
- * Build a `multipart/form-data` body that matches what
- * `processMultipartRunBody` on the server expects:
+ * Build a `multipart/form-data` body matching what `processMultipartRunBody`
+ * on the server expects:
  *
  *   - Each file in `input` becomes a top-level form field (key = input name).
  *   - Non-file inputs + overrides + trigger go in a `_json` text field.
  *
- * Only top-level file values are extracted. Files nested inside arrays /
- * objects keep their position in the JSON sidecar — the server doesn't
- * support nested file uploads via multipart.
+ * Async because stream inputs are drained to bytes here. Only top-level file
+ * values are extracted — files nested inside arrays / objects keep their
+ * position in the JSON sidecar (the server has no nested-upload path).
  */
-export function buildMultipart(args: {
+export async function buildMultipart(args: {
   input?: Record<string, unknown>;
   overrides?: { steps?: Record<string, Record<string, unknown>> };
   trigger?: 'api' | 'cli';
-}): MultipartParts {
+}): Promise<MultipartParts> {
   const fd = new FormData();
-  const inputScalars: Record<string, unknown> = {};
-  let fileCount = 0;
-
-  for (const [key, value] of Object.entries(args.input ?? {})) {
-    if (isFileInput(value)) {
-      const { blob, filename } = toBlobAndFilename(value);
-      fd.append(key, blob, filename);
-      fileCount += 1;
-    } else {
-      inputScalars[key] = value;
-    }
-  }
+  const { scalars, fileCount } = await appendFiles(fd, args.input);
 
   const sidecar: Record<string, unknown> = {};
-  if (Object.keys(inputScalars).length > 0) sidecar.input = inputScalars;
+  if (Object.keys(scalars).length > 0) sidecar.input = scalars;
   if (args.overrides) sidecar.overrides = args.overrides;
   if (args.trigger) sidecar.trigger = args.trigger;
   if (Object.keys(sidecar).length > 0) {
@@ -132,23 +222,14 @@ export function buildMultipart(args: {
  * input object itself, unlike workflow runs where `_json` is a sidecar with
  * `{ input, overrides, trigger }`.
  */
-export function buildAgentMultipart(input?: Record<string, unknown>): MultipartParts {
+export async function buildAgentMultipart(
+  input?: Record<string, unknown>
+): Promise<MultipartParts> {
   const fd = new FormData();
-  const inputScalars: Record<string, unknown> = {};
-  let fileCount = 0;
-
-  for (const [key, value] of Object.entries(input ?? {})) {
-    if (isFileInput(value)) {
-      const { blob, filename } = toBlobAndFilename(value);
-      fd.append(key, blob, filename);
-      fileCount += 1;
-    } else {
-      inputScalars[key] = value;
-    }
-  }
+  const { scalars, fileCount } = await appendFiles(fd, input);
 
-  if (Object.keys(inputScalars).length > 0) {
-    fd.append('_json', JSON.stringify(inputScalars));
+  if (Object.keys(scalars).length > 0) {
+    fd.append('_json', JSON.stringify(scalars));
   }
 
   return { formData: fd, fileCount };

package/src/resources/agents.ts

@@ -409,7 +409,7 @@ export class AgentsResource {
         : {};
 
     if (hasFileInput(input)) {
-      const { formData } = buildAgentMultipart(input);
+      const { formData } = await buildAgentMultipart(input);
       return this.dispatch<RunAgentResponse>(
         () =>
           this.client.post({

package/src/resources/executions.ts

@@ -136,10 +136,14 @@ export class WorkflowExecutionsResource {
 
     // Trigger async — we don't ask the server to wait, since we're polling.
     const triggerQuery = options.version ? { version: options.version } : {};
-    const runResult = hasFileInput(input)
-      ? await this.dispatch<RunWorkflowResponse>(() => {
-          const { formData } = buildMultipart({ input, overrides: options.overrides });
-          return this.client.post({
+    let runResult: RunWorkflowResponse;
+    if (hasFileInput(input)) {
+      // Build the multipart body once, up front — `dispatch` may retry the
+      // POST, and a drained stream cannot be replayed.
+      const { formData } = await buildMultipart({ input, overrides: options.overrides });
+      runResult = await this.dispatch<RunWorkflowResponse>(
+        () =>
+          this.client.post({
             url: '/api/v1/workflows/{id}/run',
             path: { id: workflowId },
             query: triggerQuery,
@@ -147,20 +151,22 @@ export class WorkflowExecutionsResource {
             bodySerializer: null,
             headers: { 'Content-Type': null },
             signal: options.signal,
-          }) as Promise<OperationResult<RunWorkflowResponse>>;
+          }) as Promise<OperationResult<RunWorkflowResponse>>
+      );
+    } else {
+      runResult = await this.dispatch<RunWorkflowResponse>(() =>
+        workflowsRun({
+          client: this.client,
+          path: { id: workflowId },
+          query: triggerQuery,
+          body: {
+            ...(input !== undefined ? { input } : {}),
+            ...(options.overrides ? { overrides: options.overrides } : {}),
+          },
+          signal: options.signal,
         })
-      : await this.dispatch<RunWorkflowResponse>(() =>
-          workflowsRun({
-            client: this.client,
-            path: { id: workflowId },
-            query: triggerQuery,
-            body: {
-              ...(input !== undefined ? { input } : {}),
-              ...(options.overrides ? { overrides: options.overrides } : {}),
-            },
-            signal: options.signal,
-          })
-        );
+      );
+    }
 
     const { executionId } = runResult;
 

package/src/resources/workflows.ts

@@ -96,7 +96,7 @@ export class WorkflowsResource {
 
     // File-bearing input → multipart/form-data (no base64 overhead).
     if (hasFileInput(input)) {
-      const { formData } = buildMultipart({ input, overrides: options.overrides });
+      const { formData } = await buildMultipart({ input, overrides: options.overrides });
       return this.dispatch<RunWorkflowResponse>(
         () =>
           this.client.post({

package/src/telemetry.ts

@@ -19,7 +19,7 @@
 export const SDK_LANGUAGE = 'typescript';
 // Rewritten at publish time by scripts/render-sdk-versions.sh.
 // Keep this string literal exactly stable — sed matches on it.
-export const SDK_VERSION = '0.5.4';
+export const SDK_VERSION = '0.5.6';
 
 function detectRuntime(): string {
   const g = globalThis as unknown as {