@eigenpal/sdk

Trigger EigenPal workflows from TypeScript.

Install

npm i @eigenpal/sdk

Requires a TypeScript-aware runtime: Bun, Deno, Node 22+ (native TS), tsx, Next.js, Vite, or any modern bundler. Plain node script.js won't work — see Configuration.

Get an API key at app.eigenpal.com → Settings → API Keys.

Quick start

import { EigenpalClient, EigenpalValidationError } from '@eigenpal/sdk';

const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });

// Pass a File / Blob / { content, filename, mimeType }. The SDK uploads
// the request as multipart/form-data, no base64 needed.
const result = await client.workflows.executions.runAndWait('extract-invoice', {
  contract_document: file,
});
console.log(result.status, result.result);

Authentication

Generate an API key from the dashboard under Settings → API Keys, then pass it explicitly:

const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });

The apiKey constructor option always wins. If you omit it, the SDK falls back to process.env.EIGENPAL_API_KEY for convenience, handy in scripts where you'd be writing exactly the line above.

Self-hosted

Point the SDK at your own deployment via baseUrl:

const client = new EigenpalClient({
  apiKey: process.env.EIGENPAL_API_KEY,
  baseUrl: process.env.EIGENPAL_BASE_URL ?? 'https://eigenpal.acme.internal',
});

baseUrl likewise wins over the EIGENPAL_BASE_URL env fallback. Defaults to https://app.eigenpal.com (the hosted cloud).

Triggering workflows

workflows.run(workflowId, input?, options?) enqueues a workflow execution.

// Async: returns immediately with { executionId }.
const { executionId } = await client.workflows.run('extract-invoice', {
  contract_document: file,
});

// Sync: server holds the connection up to 60 seconds.
const result = await client.workflows.run(
  'extract-invoice',
  { contract_document: file },
  { waitForCompletion: 60 }
);
console.log(result.status, result.result);

// Long-running: client-side polling, default 5min cap.
const final = await client.workflows.executions.runAndWait('extract-invoice', {
  contract_document: file,
});

The second argument is the workflow input map keyed by input name (as declared in the workflow). Pass undefined for inputs-less workflows. options carries version, waitForCompletion, and overrides.

File inputs

When a workflow input is a file, pass a File, Blob, or explicit { content, filename, mimeType } descriptor. The SDK auto-detects them and uploads the request as multipart/form-data (the same shape as curl -F, no base64 round-trip):

// Browser: File from <input type="file">
await client.workflows.run('extract-invoice', { contract_document: file });

// Node: Buffer from fs
import { readFile } from 'node:fs/promises';
const buffer = await readFile('contract.pdf');
await client.workflows.run('extract-invoice', {
  contract_document: {
    content: buffer,
    filename: 'contract.pdf',
    mimeType: 'application/pdf',
  },
});

Don't base64-encode files yourself. The SDK is multipart-first; base64 doubles the payload size and skips the optimised upload path.

Execution polling

const status = await client.workflows.executions.get(executionId);
//   { executionId, status, result?, error?, createdAt, completedAt? }

const list = await client.workflows.executions.list('extract-invoice', {
  status: ['failed', 'cancelled'],
  fromDate: 'now()-7d',
  limit: 50,
});

await client.workflows.executions.cancel(executionId);

Workflows

await client.workflows.list({ search: 'invoice', limit: 20 });
await client.workflows.get('extract-invoice');
await client.workflows.versions('extract-invoice');

Agents

await client.agents.list({ search: 'invoice' });
await client.agents.get('invoice-agent');

const { executionId } = await client.agents.run('invoice-agent', {
  invoice: file,
});

await client.agents.executions.get(executionId);
await client.agents.executions.cancel(executionId);

Errors

Every non-2xx response throws a typed subclass of EigenpalError:

| HTTP | Class | Notes | | --------------- | ------------------------- | ---------------------------------------------------- | | 400 | EigenpalValidationError | .issues carries the per-field problems | | 401 | EigenpalAuthError | Bad / missing API key | | 403 | EigenpalForbiddenError | API trigger disabled, scope mismatch | | 404 | EigenpalNotFoundError | Workflow / execution doesn't exist | | 429 | EigenpalRateLimitError | .retryAfter is the server-suggested wait (seconds) | | 5xx | EigenpalServerError | Auto-retried up to maxRetries | | timeout / abort | EigenpalTimeoutError | |

import { EigenpalClient, EigenpalValidationError } from '@eigenpal/sdk';

const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });

try {
  // First arg accepts the workflow slug ('extract-invoice') or id ('wf_abc123').
  const result = await client.workflows.executions.runAndWait('extract-invoice', {
    language: 'en',
  });
  console.log(result.status, result.result);
} catch (err) {
  if (err instanceof EigenpalValidationError) {
    for (const issue of err.issues) console.error(`${issue.field}: ${issue.message}`);
  }
  throw err;
}

For file inputs, see docs/files.md.

Reference

| Topic | What's in it | | ----------------------------------------- | -------------------------------------------------- | | Workflows | List, get, trigger runs, pin versions. | | Executions | Status, polling, cancel, run-and-wait. | | File inputs | Multipart upload from File, Blob, Buffer, or path. | | Errors | Typed exceptions, retries, request ids. | | Configuration | API key, baseUrl, timeouts, headers. | | Full API reference | Every method, generated from the OpenAPI spec. |

License

Apache-2.0.