@eigenpal/sdk 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -1,7 +1,64 @@
 # @eigenpal/sdk
 
-## 0.4.10
+## 0.4.12
+
+### Major Changes
+
+- c15ce88: Rename agent API calls to `/v1/agents` and scope execution helpers under their owning workflow or agent.
+
+### Patch Changes
+
+- 9905f7f: Fix the published SDKs so the README's default `baseUrl` works. 0.4.10
+  shipped paths under `/v1/...` while the actual Next.js routes live at
+  `/api/v1/...`, so every call from a freshly installed SDK either hit
+  the marketing-site HTML (200 OK silently parsed as a workflow object)
+  or 307'd to a redirect Python wouldn't follow. Now the OpenAPI spec
+  emits `/api/v1/...` and the regenerated TS + Python clients call the
+  real URLs without a `baseUrl: '.../api'` workaround.
+
+  Also trims the v1 public surface so SDK consumers no longer see internal
+  columns. The legacy app handlers spread the raw DB row, which dragged
+  `tenantId`, `isBlock`, `currentHistoryId`, `evalConfigYaml`, `createdBy`,
+  the full `currentVersion` object, `traceId`, `spanId`, `versionId`,
+  `leaseId`, `workerId`, `definitionSnapshot`, `blockSnapshots`,
+  `stepResults`, `evalScore`, `priority`, retry-chain pointers, etc. into
+  typed SDK output. The v1 endpoints now wrap the legacy response with
+  `pickPublicWorkflow` / `pickPublicWorkflowVersion` / `pickPublicExecution`
+  helpers (forwarded via `forwardItem` / `forwardList`), so the wire shape
+  matches the schema. `WorkflowSummary` is now
+  `{ id, version, createdAt, updatedAt }` — `version` is the release tag
+  string callers actually want, replacing the internal `currentHistoryId`.
+
+  Heads-up: workflow `name` is no longer surfaced as a top-level field
+  (it was previously leaked via `currentVersion.definition.name`). It's
+  authoritative inside the YAML, so fetch it via
+  `client.workflows.versions(id)[0].yamlContent` and parse, or treat the
+  workflow `id` as the canonical identifier.
+
+  Tightens response handling on both sides: the client throws
+  `EigenpalError` whenever a response carries a non-JSON Content-Type
+  (2xx or 4xx), so the next misconfigured `baseUrl` fails loudly with a
+  "point baseUrl at your EigenPal instance root" message instead of
+  silently returning string-as-object or surfacing a downstream
+  `JSONDecodeError`.
+
+  Renames the constructor: `Eigenpal` → `EigenpalClient` in both SDKs.
+  The old name was ambiguous when imported alongside `EigenpalError` etc.
+  and read awkwardly as `new Eigenpal(...)` next to the brand
+  ("Eigenpal"); `EigenpalClient` matches the convention of every
+  neighbouring class. No backwards-compat alias since 0.4.10 is fresh.
+
+  Adds `bun sdk:smoke:local [ts|py|both]` — packs the local SDK as the
+  exact tarball / wheel that ships, installs into a clean tmp workspace,
+  and runs an end-to-end smoke against `EIGENPAL_BASE_URL`. Verifies the
+  v1 paths resolve, the trimmed public shape is enforced on the wire,
+  and the HTML-host guard fires.
+
+  `defineRoute` rejects paths that don't start with `/api/` so the
+  mismatch can't reappear by accident.
+
+## Unreleased
 
 - Initial release.
 - Coverage: workflow trigger (sync + async), execution polling, cancel, workflow & version listing.
-- `Eigenpal` facade with API key auth, automatic retries on 5xx / 429 / network errors with `Retry-After` honoring, typed `EigenpalError` subclasses, and `executions.runAndWait()` for client-side polling.
+- `Eigenpal` facade with API key auth, automatic retries on 5xx / 429 / network errors with `Retry-After` honoring, typed `EigenpalError` subclasses, and `workflows.executions.runAndWait()` for client-side polling.

package/README.md

@@ -1,21 +1,32 @@
 # @eigenpal/sdk
 
-Official TypeScript SDK for the [EigenPal](https://eigenpal.com) API.
+Trigger EigenPal workflows from TypeScript.
+
+[![npm](https://img.shields.io/npm/v/@eigenpal/sdk?color=3B5BDB&labelColor=555&label=npm)](https://www.npmjs.com/package/@eigenpal/sdk)
+[![downloads](https://img.shields.io/npm/dm/@eigenpal/sdk?color=3B5BDB&labelColor=555&label=downloads)](https://www.npmjs.com/package/@eigenpal/sdk)
+[![license](https://img.shields.io/badge/license-Apache--2.0-3B5BDB?labelColor=555)](https://github.com/eigenpal/sdk-typescript/blob/main/LICENSE)
+[![docs](https://img.shields.io/badge/docs-eigenpal%2Fsdk-3B5BDB?labelColor=555)](https://github.com/eigenpal/sdk-typescript)
+
+## Install
 
 ```bash
-npm install @eigenpal/sdk
+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](./docs/configuration.md#typescript-runtime).
+
+Get an API key at **app.eigenpal.com → Settings → API Keys**.
+
+## Quick start
+
 ```ts
-import { Eigenpal } from '@eigenpal/sdk';
+import { EigenpalClient, EigenpalValidationError } from '@eigenpal/sdk';
 
-const client = new Eigenpal({
-  apiKey: process.env.EIGENPAL_API_KEY,
-});
+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.executions.runAndWait('extract-invoice', {
+const result = await client.workflows.executions.runAndWait('extract-invoice', {
   contract_document: file,
 });
 console.log(result.status, result.result);
@@ -26,7 +37,7 @@ console.log(result.status, result.result);
 Generate an API key from the dashboard under **Settings → API Keys**, then pass it explicitly:
 
 ```ts
-const client = new Eigenpal({ apiKey: process.env.EIGENPAL_API_KEY });
+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.
@@ -36,7 +47,7 @@ The `apiKey` constructor option always wins. If you omit it, the SDK falls back
 Point the SDK at your own deployment via `baseUrl`:
 
 ```ts
-const client = new Eigenpal({
+const client = new EigenpalClient({
   apiKey: process.env.EIGENPAL_API_KEY,
   baseUrl: process.env.EIGENPAL_BASE_URL ?? 'https://eigenpal.acme.internal',
 });
@@ -63,7 +74,7 @@ const result = await client.workflows.run(
 console.log(result.status, result.result);
 
 // Long-running: client-side polling, default 5min cap.
-const final = await client.executions.runAndWait('extract-invoice', {
+const final = await client.workflows.executions.runAndWait('extract-invoice', {
   contract_document: file,
 });
 ```
@@ -95,17 +106,16 @@ await client.workflows.run('extract-invoice', {
 ## Execution polling
 
 ```ts
-const status = await client.executions.get(executionId);
+const status = await client.workflows.executions.get(executionId);
 //   { executionId, status, result?, error?, createdAt, completedAt? }
 
-const list = await client.executions.list({
-  workflowId: 'extract-invoice',
-  status: 'failed',
+const list = await client.workflows.executions.list('extract-invoice', {
+  status: ['failed', 'cancelled'],
   fromDate: 'now()-7d',
   limit: 50,
 });
 
-await client.executions.cancel(executionId);
+await client.workflows.executions.cancel(executionId);
 ```
 
 ## Workflows
@@ -116,6 +126,20 @@ await client.workflows.get('extract-invoice');
 await client.workflows.versions('extract-invoice');
 ```
 
+## Agents
+
+```ts
+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`:
@@ -131,48 +155,36 @@ Every non-2xx response throws a typed subclass of `EigenpalError`:
 | timeout / abort | `EigenpalTimeoutError`    |                                                      |
 
 ```ts
-import { Eigenpal, EigenpalValidationError } from '@eigenpal/sdk';
+import { EigenpalClient, EigenpalValidationError } from '@eigenpal/sdk';
+
+const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });
 
 try {
-  await client.workflows.run('extract-invoice');
+  // 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}`);
-    }
+    for (const issue of err.issues) console.error(`${issue.field}: ${issue.message}`);
   }
   throw err;
 }
 ```
 
-## Configuration
-
-```ts
-new Eigenpal({
-  apiKey: 'eg_…', // or EIGENPAL_API_KEY
-  baseUrl: 'https://app.eigenpal.com', // or EIGENPAL_BASE_URL
-  timeoutMs: 60_000, // per-request timeout
-  maxRetries: 3, // 5xx / 429 / network
-  defaultHeaders: {
-    // merged into every request
-    'X-Trace-Id': '…',
-  },
-});
-```
-
-The SDK retries on 5xx, 429 (honoring `Retry-After`), and network errors. 4xx errors are surfaced immediately as typed exceptions and are not retried.
+For file inputs, see [docs/files.md](./docs/files.md).
 
-## TypeScript
+## Reference
 
-The full request/response types are exported:
-
-```ts
-import type {
-  WorkflowSummary,
-  ExecutionStatusResponse,
-  ListWorkflowsResponse,
-} from '@eigenpal/sdk';
-```
+| Topic                                     | What's in it                                       |
+| ----------------------------------------- | -------------------------------------------------- |
+| [Workflows](./docs/workflows.md)          | List, get, trigger runs, pin versions.             |
+| [Executions](./docs/executions.md)        | Status, polling, cancel, run-and-wait.             |
+| [File inputs](./docs/files.md)            | Multipart upload from File, Blob, Buffer, or path. |
+| [Errors](./docs/errors.md)                | Typed exceptions, retries, request ids.            |
+| [Configuration](./docs/configuration.md)  | API key, baseUrl, timeouts, headers.               |
+| [Full API reference](./docs/reference.md) | Every method, generated from the OpenAPI spec.     |
 
 ## License
 

package/package.json

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

package/src/client.ts

@@ -1,15 +1,16 @@
 import { EigenpalError, EigenpalTimeoutError, errorFromResponse } from './errors';
 import { createClient, createConfig, type Client, type Config } from './generated/client';
 import type { ApiErrorEnvelope } from './generated/types.gen';
-import { ExecutionsResource } from './resources/executions';
+import { AgentsResource } from './resources/agents';
 import { WorkflowsResource } from './resources/workflows';
+import { buildTelemetryHeaders } from './telemetry';
 
 export interface EigenpalOptions {
   /**
    * API key issued from Settings → API Keys (`eg_…`).
    *
    * Falls back to the `EIGENPAL_API_KEY` environment variable when omitted,
-   * so most users only need `new Eigenpal()`.
+   * so most users only need `new EigenpalClient()`.
    */
   apiKey?: string;
   /**
@@ -31,7 +32,6 @@ export interface EigenpalOptions {
 const DEFAULT_BASE_URL = 'https://app.eigenpal.com';
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_RETRIES = 3;
-const SDK_VERSION = '0.0.0-placeholder';
 
 /**
  * Result shape returned by hey-api operation calls. We let hey-api default
@@ -49,13 +49,13 @@ export interface OperationResult<T> {
 }
 
 /**
- * The Eigenpal SDK client.
+ * The EigenPal SDK client.
  *
  * ```ts
- * import { Eigenpal } from '@eigenpal/sdk';
+ * import { EigenpalClient } from '@eigenpal/sdk';
  *
  * // Reads EIGENPAL_API_KEY from env automatically.
- * const client = new Eigenpal();
+ * const client = new EigenpalClient();
  *
  * // Async — enqueue and poll later.
  * const { executionId } = await client.workflows.run('wf_abc', { language: 'en' });
@@ -65,15 +65,15 @@ export interface OperationResult<T> {
  *   waitForCompletion: 60,
  * });
  *
- * // Client-side polling for long-running runs (default 5min cap).
- * const final = await client.executions.runAndWait('wf_abc', { language: 'en' });
+ * // Client-side polling for long-running executions (default 5min cap).
+ * const final = await client.workflows.executions.runAndWait('wf_abc', { language: 'en' });
  * ```
  */
-export class Eigenpal {
+export class EigenpalClient {
   /** Workflow operations: `list`, `get`, `versions`, `run`. */
   public readonly workflows: WorkflowsResource;
-  /** Execution operations: `list`, `get`, `cancel`, `runAndWait`. */
-  public readonly executions: ExecutionsResource;
+  /** Agent operations: `list`, `get`, `create`, `run`, `executions`. */
+  public readonly agents: AgentsResource;
 
   /** Underlying hey-api client. Use `getRawClient()` for advanced cases. */
   private readonly client: Client;
@@ -84,7 +84,7 @@ export class Eigenpal {
     const apiKey = options.apiKey ?? readEnv('EIGENPAL_API_KEY');
     if (!apiKey) {
       throw new EigenpalError(
-        'Missing API key. Pass `new Eigenpal({ apiKey })` or set the EIGENPAL_API_KEY environment variable.',
+        'Missing API key. Pass `new EigenpalClient({ apiKey })` or set the EIGENPAL_API_KEY environment variable.',
         { status: 0 }
       );
     }
@@ -97,7 +97,10 @@ export class Eigenpal {
       baseUrl,
       headers: {
         Authorization: `Bearer ${apiKey}`,
-        'User-Agent': `eigenpal-sdk-js/${SDK_VERSION}`,
+        // SDK telemetry headers (X-Eigenpal-Sdk-*) + a richer User-Agent.
+        // User-supplied defaultHeaders override these so callers can opt out
+        // of telemetry by passing their own User-Agent / X-Eigenpal-Sdk.
+        ...buildTelemetryHeaders(),
         ...(options.defaultHeaders ?? {}),
       },
     });
@@ -112,7 +115,7 @@ export class Eigenpal {
     this.installTimeoutInterceptor();
 
     this.workflows = new WorkflowsResource(this.client, this._request.bind(this));
-    this.executions = new ExecutionsResource(this.client, this._request.bind(this));
+    this.agents = new AgentsResource(this.client, this._request.bind(this));
   }
 
   /** Expose the underlying hey-api client for advanced use (custom interceptors, etc.). */
@@ -133,12 +136,24 @@ export class Eigenpal {
       try {
         const result = await call();
         const response = result.response;
+        const status = response?.status ?? 0;
+        // Guard against misconfigured `baseUrl` pointed at an HTML host
+        // (e.g. `https://eigenpal.com` instead of `https://app.eigenpal.com`).
+        // Fires for both 2xx and non-2xx so a 4xx with HTML surfaces a typed
+        // baseUrl-pointing error instead of a misleading NotFoundError or a
+        // downstream JSON-parse crash. 0.4.10 shipped with this footgun.
+        //
+        // Don't run on retriable statuses — a 503 maintenance page from a
+        // CDN is transient and should consume retry budget, not throw on
+        // attempt zero. Only fire when we're about to surface the response
+        // as a final result or final error.
+        const willRetry = isRetriableStatus(status) && attempt < this.maxRetries;
+        if (response && !willRetry) assertJsonResponse(response);
         if (response && response.ok && result.data !== undefined) {
           return result.data;
         }
         // Non-2xx (or response missing — treat as opaque failure).
-        const status = response?.status ?? 0;
-        if (isRetriableStatus(status) && attempt < this.maxRetries) {
+        if (willRetry) {
           await sleep(retryDelay(response, attempt));
           continue;
         }
@@ -146,7 +161,7 @@ export class Eigenpal {
         const retryAfter = parseRetryAfter(response?.headers.get('retry-after') ?? null);
         throw errorFromResponse(status, envelope, retryAfter);
       } catch (err) {
-        // Re-throw mapped Eigenpal errors as-is.
+        // Re-throw mapped EigenpalError subclasses as-is.
         if (err instanceof EigenpalError) throw err;
         // Network/abort error — retry if budget allows. AbortSignal aborts
         // surface as DOMException — we treat them as terminal (don't retry).
@@ -181,6 +196,22 @@ export class Eigenpal {
   }
 }
 
+function assertJsonResponse(response: Response): void {
+  // 204 No Content has no body — accept silently.
+  if (response.status === 204) return;
+  const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+  // Match `application/json`, `application/problem+json`, etc. Empty
+  // Content-Type is tolerated since some proxies strip it on small bodies.
+  if (contentType === '' || contentType.includes('json')) return;
+  throw new EigenpalError(
+    `Expected a JSON response from the API but got Content-Type "${contentType}". ` +
+      `This usually means \`baseUrl\` points at a non-API host (e.g. the marketing site or ` +
+      `a misconfigured proxy). Set \`baseUrl\` to your EigenPal instance root, ` +
+      `e.g. "https://app.eigenpal.com".`,
+    { status: response.status }
+  );
+}
+
 function isRetriableStatus(status: number): boolean {
   return status >= 500 || status === 429;
 }

package/src/errors.ts

@@ -25,7 +25,12 @@ export class EigenpalError extends Error {
 
 export class EigenpalAuthError extends EigenpalError {
   constructor(envelope?: ApiErrorEnvelope) {
-    super('Missing or invalid API key', { status: 401, envelope });
+    super(
+      envelope?.issues?.[0]?.message ??
+        'Invalid or missing API key. Generate one at app.eigenpal.com → Settings → API Keys; ' +
+          'pass it as `new EigenpalClient({ apiKey })` or set EIGENPAL_API_KEY.',
+      { status: 401, envelope }
+    );
     this.name = 'EigenpalAuthError';
   }
 }
@@ -85,7 +90,7 @@ export class EigenpalTimeoutError extends EigenpalError {
 
 /**
  * Map an HTTP response into the appropriate typed error. Used by the
- * `Eigenpal` facade to wrap raw fetch errors before they bubble to user
+ * `EigenpalClient` facade to wrap raw fetch errors before they bubble to user
  * code.
  */
 export function errorFromResponse(

package/src/generated/index.ts

@@ -1,9 +1,17 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 export {
-  executionsCancel,
-  executionsGet,
-  executionsList,
+  agentsCreate,
+  agentsExecutionsCancel,
+  agentsExecutionsGet,
+  agentsExecutionsList,
+  agentsGet,
+  agentsList,
+  agentsRun,
+  agentsUpdate,
+  workflowsExecutionsCancel,
+  workflowsExecutionsGet,
+  workflowsExecutionsList,
   workflowsGet,
   workflowsList,
   workflowsRun,
@@ -11,35 +19,88 @@ export {
   type Options,
 } from './sdk.gen';
 export type {
+  AgentExecutionResponse,
+  AgentExecutionSummary,
+  AgentSummary,
+  AgentsCreateData,
+  AgentsCreateError,
+  AgentsCreateErrors,
+  AgentsCreateResponse,
+  AgentsCreateResponses,
+  AgentsExecutionsCancelData,
+  AgentsExecutionsCancelError,
+  AgentsExecutionsCancelErrors,
+  AgentsExecutionsCancelResponse,
+  AgentsExecutionsCancelResponses,
+  AgentsExecutionsGetData,
+  AgentsExecutionsGetError,
+  AgentsExecutionsGetErrors,
+  AgentsExecutionsGetResponse,
+  AgentsExecutionsGetResponses,
+  AgentsExecutionsListData,
+  AgentsExecutionsListError,
+  AgentsExecutionsListErrors,
+  AgentsExecutionsListResponse,
+  AgentsExecutionsListResponses,
+  AgentsGetData,
+  AgentsGetError,
+  AgentsGetErrors,
+  AgentsGetResponse,
+  AgentsGetResponses,
+  AgentsListData,
+  AgentsListError,
+  AgentsListErrors,
+  AgentsListResponse,
+  AgentsListResponses,
+  AgentsRunData,
+  AgentsRunError,
+  AgentsRunErrors,
+  AgentsRunResponse,
+  AgentsRunResponses,
+  AgentsUpdateData,
+  AgentsUpdateError,
+  AgentsUpdateErrors,
+  AgentsUpdateResponse,
+  AgentsUpdateResponses,
   ApiErrorEnvelope,
   ApiErrorIssue,
-  CancelExecutionResponse,
+  CancelAgentExecutionResponse,
+  CancelWorkflowExecutionResponse,
   ClientOptions,
+  CreateAgentBody,
+  CreateAgentResponse,
   ExecutionStatus,
-  ExecutionStatusResponse,
   ExecutionSummary,
-  ExecutionsCancelData,
-  ExecutionsCancelError,
-  ExecutionsCancelErrors,
-  ExecutionsCancelResponse,
-  ExecutionsCancelResponses,
-  ExecutionsGetData,
-  ExecutionsGetError,
-  ExecutionsGetErrors,
-  ExecutionsGetResponse,
-  ExecutionsGetResponses,
-  ExecutionsListData,
-  ExecutionsListError,
-  ExecutionsListErrors,
-  ExecutionsListResponse,
-  ExecutionsListResponses,
-  ListExecutionsResponse,
+  GetAgentResponse,
+  ListAgentExecutionsResponse,
+  ListAgentsResponse,
   ListVersionsResponse,
+  ListWorkflowExecutionsResponse,
   ListWorkflowsResponse,
+  PatchAgentBody,
+  PatchAgentResponse,
+  RunAgentBody,
+  RunAgentResponse,
   RunWorkflowBody,
   RunWorkflowResponse,
+  WorkflowExecutionStatusResponse,
   WorkflowSummary,
   WorkflowVersion,
+  WorkflowsExecutionsCancelData,
+  WorkflowsExecutionsCancelError,
+  WorkflowsExecutionsCancelErrors,
+  WorkflowsExecutionsCancelResponse,
+  WorkflowsExecutionsCancelResponses,
+  WorkflowsExecutionsGetData,
+  WorkflowsExecutionsGetError,
+  WorkflowsExecutionsGetErrors,
+  WorkflowsExecutionsGetResponse,
+  WorkflowsExecutionsGetResponses,
+  WorkflowsExecutionsListData,
+  WorkflowsExecutionsListError,
+  WorkflowsExecutionsListErrors,
+  WorkflowsExecutionsListResponse,
+  WorkflowsExecutionsListResponses,
   WorkflowsGetData,
   WorkflowsGetError,
   WorkflowsGetErrors,