@eigenpal/sdk 0.0.0-placeholder

package/src/lib/files.ts

@@ -0,0 +1,128 @@
+/**
+ * File-input helpers for `client.workflows.run()`.
+ *
+ * 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.
+ */
+
+/**
+ * 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',
+ *   },
+ * });
+ * ```
+ */
+export interface FileDescriptor {
+  content: ArrayBuffer | ArrayBufferView | Blob;
+  filename: string;
+  mimeType?: string;
+}
+
+/**
+ * Any value that the SDK accepts as a "file" workflow input.
+ */
+export type FileInput = Blob | FileDescriptor;
+
+const DEFAULT_MIME = 'application/octet-stream';
+
+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;
+}
+
+export function hasFileInput(input: Record<string, unknown> | undefined): boolean {
+  if (!input) return false;
+  for (const value of Object.values(input)) {
+    if (isFileInput(value)) return true;
+  }
+  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.
+  if (typeof Blob !== 'undefined' && file instanceof Blob) {
+    const name = (file as File).name ?? 'file';
+    return { blob: file, filename: name };
+  }
+  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 });
+  }
+  return { blob, filename: desc.filename };
+}
+
+export interface MultipartParts {
+  /** FormData ready to send as the request body. */
+  formData: FormData;
+  /** Number of file fields appended (0 means no files were detected). */
+  fileCount: number;
+}
+
+/**
+ * Build a `multipart/form-data` body that matches 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.
+ */
+export function buildMultipart(args: {
+  input?: Record<string, unknown>;
+  overrides?: { steps?: Record<string, Record<string, unknown>> };
+  trigger?: 'api' | 'cli';
+}): 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 sidecar: Record<string, unknown> = {};
+  if (Object.keys(inputScalars).length > 0) sidecar.input = inputScalars;
+  if (args.overrides) sidecar.overrides = args.overrides;
+  if (args.trigger) sidecar.trigger = args.trigger;
+  if (Object.keys(sidecar).length > 0) {
+    fd.append('_json', JSON.stringify(sidecar));
+  }
+
+  return { formData: fd, fileCount };
+}

package/src/resources/executions.ts

@@ -0,0 +1,179 @@
+import type { OperationResult } from '../client';
+import { EigenpalTimeoutError } from '../errors';
+import type { Client } from '../generated/client';
+import {
+  executionsCancel,
+  executionsGet,
+  executionsList,
+  workflowsRun,
+} from '../generated/sdk.gen';
+import type {
+  CancelExecutionResponse,
+  ExecutionStatus,
+  ExecutionStatusResponse,
+  ListExecutionsResponse,
+  RunWorkflowResponse,
+} from '../generated/types.gen';
+import { buildMultipart, hasFileInput } from '../lib/files';
+import type { WorkflowInput } from './workflows';
+
+export interface ListExecutionsOptions {
+  workflowId?: string;
+  /** Comma-separated list of execution statuses. */
+  status?: string;
+  /** ISO timestamp or relative expression like `"now()-7d"`. */
+  fromDate?: string;
+  toDate?: string;
+  exampleId?: string;
+  limit?: number;
+  offset?: number;
+  signal?: AbortSignal;
+}
+
+export interface RunAndWaitOptions {
+  /** Workflow version. Default: `"latest"`. */
+  version?: string;
+  /** Per-step output overrides for replay. */
+  overrides?: { steps?: Record<string, Record<string, unknown>> };
+  /** Polling interval in milliseconds. Default: 2_000. */
+  pollIntervalMs?: number;
+  /**
+   * Total client-side timeout in milliseconds. Default: 5 minutes. Throws
+   * `EigenpalTimeoutError` if the run hasn't reached a terminal state by then.
+   */
+  timeoutMs?: number;
+  /** AbortSignal to cancel the entire poll loop. */
+  signal?: AbortSignal;
+}
+
+const TERMINAL_STATUSES = new Set<ExecutionStatus>([
+  'completed',
+  'failed',
+  'cancelled',
+  'rejected',
+]);
+
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_RUN_AND_WAIT_TIMEOUT_MS = 5 * 60 * 1000;
+
+type Dispatch = <T>(call: () => Promise<OperationResult<T>>) => Promise<T>;
+
+/**
+ * Execution resource — read execution status, list executions, cancel
+ * in-flight runs, and the convenience `runAndWait` helper that wraps a
+ * workflow trigger + client-side poll loop. Reached via `client.executions`.
+ */
+export class ExecutionsResource {
+  constructor(
+    private readonly client: Client,
+    private readonly dispatch: Dispatch
+  ) {}
+
+  /** Get execution status. Pass `includeSteps` for the full per-step payload. */
+  async get(
+    executionId: string,
+    options: { includeSteps?: boolean; signal?: AbortSignal } = {}
+  ): Promise<ExecutionStatusResponse> {
+    return this.dispatch<ExecutionStatusResponse>(
+      () =>
+        executionsGet({
+          client: this.client,
+          path: { executionId },
+          query: options.includeSteps ? { includeSteps: 'true' } : {},
+          signal: options.signal,
+        }) as Promise<OperationResult<ExecutionStatusResponse>>
+    );
+  }
+
+  /** List executions, paginated. */
+  async list(options: ListExecutionsOptions = {}): Promise<ListExecutionsResponse> {
+    const { signal, ...query } = options;
+    return this.dispatch(() => executionsList({ client: this.client, query, signal }));
+  }
+
+  /** Cancel an execution. Idempotent. */
+  async cancel(
+    executionId: string,
+    options: { signal?: AbortSignal } = {}
+  ): Promise<CancelExecutionResponse> {
+    return this.dispatch(() =>
+      executionsCancel({
+        client: this.client,
+        path: { executionId },
+        signal: options.signal,
+      })
+    );
+  }
+
+  /**
+   * Trigger a workflow and poll for completion client-side.
+   *
+   * Unlike `workflows.run({ waitForCompletion: 60 })`, this helper polls
+   * indefinitely (up to `timeoutMs`, default 5 min) so it works for runs
+   * that exceed the server-side 60s sync window. Returns the final
+   * response with `status`/`result`/`error` populated.
+   */
+  async runAndWait(
+    workflowId: string,
+    input?: WorkflowInput,
+    options: RunAndWaitOptions = {}
+  ): Promise<RunWorkflowResponse> {
+    const pollInterval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_RUN_AND_WAIT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+
+    // 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({
+            url: '/v1/workflows/{id}/run',
+            path: { id: workflowId },
+            query: triggerQuery,
+            body: formData,
+            bodySerializer: null,
+            headers: { 'Content-Type': null },
+            signal: options.signal,
+          }) as Promise<OperationResult<RunWorkflowResponse>>;
+        })
+      : 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;
+
+    while (true) {
+      if (options.signal?.aborted) {
+        throw new EigenpalTimeoutError('runAndWait aborted');
+      }
+      if (Date.now() >= deadline) {
+        throw new EigenpalTimeoutError(
+          `runAndWait timed out after ${timeoutMs}ms (executionId=${executionId})`
+        );
+      }
+
+      const status = await this.get(executionId, { signal: options.signal });
+
+      if (status.status && TERMINAL_STATUSES.has(status.status)) {
+        return {
+          executionId,
+          status: status.status,
+          ...(status.result != null ? { result: status.result } : {}),
+          ...(status.error != null ? { error: status.error } : {}),
+        };
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+  }
+}

package/src/resources/workflows.ts

@@ -0,0 +1,154 @@
+import type { OperationResult } from '../client';
+import type { Client } from '../generated/client';
+import {
+  workflowsGet,
+  workflowsList,
+  workflowsRun,
+  workflowsVersionsList,
+} from '../generated/sdk.gen';
+import type {
+  ListVersionsResponse,
+  ListWorkflowsResponse,
+  RunWorkflowResponse,
+  WorkflowSummary,
+} from '../generated/types.gen';
+import { buildMultipart, hasFileInput } from '../lib/files';
+
+/**
+ * Workflow inputs keyed by name as declared in the workflow YAML.
+ *
+ * File values (`File`, `Blob`, or `{ content, filename, mimeType }`) are
+ * detected automatically and uploaded as `multipart/form-data` — same as
+ * `curl -F`. No base64 round-trip required.
+ */
+export type WorkflowInput = Record<string, unknown>;
+
+export interface RunWorkflowOptions {
+  /** Specific version id, or `"latest"` (default). */
+  version?: string;
+  /** Hold the connection up to N seconds for completion (max 60). Omit for async. */
+  waitForCompletion?: number;
+  /** Per-step output overrides for replay. */
+  overrides?: { steps?: Record<string, Record<string, unknown>> };
+  /** AbortSignal to cancel the request. */
+  signal?: AbortSignal;
+}
+
+export interface ListWorkflowsOptions {
+  /** Substring match against workflow name. */
+  search?: string;
+  /** Exact-match by workflow name (slug). */
+  name?: string;
+  kind?: 'workflow' | 'block';
+  limit?: number;
+  offset?: number;
+  signal?: AbortSignal;
+}
+
+export interface ListVersionsOptions {
+  limit?: number;
+  offset?: number;
+  signal?: AbortSignal;
+}
+
+type Dispatch = <T>(call: () => Promise<OperationResult<T>>) => Promise<T>;
+
+/**
+ * Workflow resource — list, get, run, and inspect versions of saved
+ * workflows. Reached via `client.workflows`.
+ */
+export class WorkflowsResource {
+  constructor(
+    private readonly client: Client,
+    private readonly dispatch: Dispatch
+  ) {}
+
+  /**
+   * Execute a workflow.
+   *
+   * @param workflowId — id like `wf_abc123`.
+   * @param input — workflow inputs keyed by name. Pass `undefined` for inputs-less workflows.
+   * @param options — `version`, `waitForCompletion`, `overrides`.
+   *
+   * - With no `waitForCompletion`, returns immediately with `{ executionId }`.
+   *   Poll via `client.executions.get(id)` or use `client.executions.runAndWait`.
+   * - With `waitForCompletion: 60`, the server holds the connection up to 60
+   *   seconds. The response also includes `status`, `result`, and `error`
+   *   when the run finishes within the window.
+   */
+  async run(
+    workflowId: string,
+    input?: WorkflowInput,
+    options: RunWorkflowOptions = {}
+  ): Promise<RunWorkflowResponse> {
+    const query = {
+      ...(options.version ? { version: options.version } : {}),
+      ...(options.waitForCompletion !== undefined
+        ? { wait_for_completion: options.waitForCompletion }
+        : {}),
+    };
+
+    // File-bearing input → multipart/form-data (no base64 overhead).
+    if (hasFileInput(input)) {
+      const { formData } = buildMultipart({ input, overrides: options.overrides });
+      return this.dispatch<RunWorkflowResponse>(
+        () =>
+          this.client.post({
+            url: '/v1/workflows/{id}/run',
+            path: { id: workflowId },
+            query,
+            body: formData,
+            // Skip JSON serialization; FormData passes through to fetch which
+            // sets the Content-Type header (with boundary) automatically.
+            bodySerializer: null,
+            // Explicitly null the JSON Content-Type header that the request
+            // pipeline would otherwise inherit.
+            headers: { 'Content-Type': null },
+            signal: options.signal,
+          }) as Promise<OperationResult<RunWorkflowResponse>>
+      );
+    }
+
+    return this.dispatch<RunWorkflowResponse>(() =>
+      workflowsRun({
+        client: this.client,
+        path: { id: workflowId },
+        query,
+        body: {
+          ...(input !== undefined ? { input } : {}),
+          ...(options.overrides ? { overrides: options.overrides } : {}),
+        },
+        signal: options.signal,
+      })
+    );
+  }
+
+  /** List workflows, paginated. */
+  async list(options: ListWorkflowsOptions = {}): Promise<ListWorkflowsResponse> {
+    const { signal, ...query } = options;
+    return this.dispatch(() => workflowsList({ client: this.client, query, signal }));
+  }
+
+  /** Get a single workflow by id. */
+  async get(workflowId: string, options: { signal?: AbortSignal } = {}): Promise<WorkflowSummary> {
+    return this.dispatch(() =>
+      workflowsGet({ client: this.client, path: { id: workflowId }, signal: options.signal })
+    );
+  }
+
+  /** List tagged versions for a workflow, paginated. */
+  async versions(
+    workflowId: string,
+    options: ListVersionsOptions = {}
+  ): Promise<ListVersionsResponse> {
+    const { signal, ...query } = options;
+    return this.dispatch(() =>
+      workflowsVersionsList({
+        client: this.client,
+        path: { id: workflowId },
+        query,
+        signal,
+      })
+    );
+  }
+}

package/src/runtime-config.ts

@@ -0,0 +1,15 @@
+import type { CreateClientConfig } from './generated/client.gen';
+
+/**
+ * Runtime configuration hook for the generated hey-api client.
+ *
+ * The hand-written `Eigenpal` class in `client.ts` calls
+ * `setClientConfig()` on construction with the user's `apiKey` and
+ * `baseUrl`, so the generated SDK functions automatically pick up the
+ * Authorization header. This factory returns a no-op default — values
+ * are populated when an `Eigenpal` instance is created.
+ */
+export const createClientConfig: CreateClientConfig = (config) => ({
+  ...config,
+  baseUrl: config?.baseUrl ?? 'https://app.eigenpal.com',
+});