@eigenpal/sdk 0.4.10 → 0.4.11

package/src/index.ts

@@ -1,11 +1,11 @@
 /**
- * Official TypeScript SDK for the Eigenpal API.
+ * Official TypeScript SDK for the EigenPal API.
  *
  * @example
  * ```ts
- * import { Eigenpal } from '@eigenpal/sdk';
+ * import { EigenpalClient } from '@eigenpal/sdk';
  *
- * const client = new Eigenpal({ apiKey: process.env.EIGENPAL_API_KEY! });
+ * const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY! });
  *
  * // Async — enqueue and poll later.
  * const { executionId } = await client.workflows.run('wf_abc', { input: { ... } });
@@ -16,10 +16,10 @@
  * });
  *
  * // Client-side poll (up to 5min by default).
- * const final = await client.executions.runAndWait('wf_abc', { input: { ... } });
+ * const final = await client.workflows.executions.runAndWait('wf_abc', { input: { ... } });
  * ```
  */
-export { Eigenpal, type EigenpalOptions } from './client';
+export { EigenpalClient, type EigenpalOptions } from './client';
 
 export {
   EigenpalAuthError,
@@ -33,6 +33,11 @@ export {
 } from './errors';
 
 export type { FileDescriptor, FileInput } from './lib/files';
+export type {
+  ListAgentExecutionsOptions,
+  ListAgentsOptions,
+  RunAgentOptions,
+} from './resources/agents';
 export type {
   ListVersionsOptions,
   ListWorkflowsOptions,
@@ -48,17 +53,25 @@ export type { ListExecutionsOptions, RunAndWaitOptions } from './resources/execu
 // Re-export the canonical generated types so users can type their own
 // callbacks and helpers without reaching into `./generated`.
 export type {
+  AgentExecutionResponse,
+  AgentExecutionSummary,
+  AgentSummary,
   ApiErrorEnvelope,
   ApiErrorIssue,
-  CancelExecutionResponse,
+  CancelAgentExecutionResponse,
+  CancelWorkflowExecutionResponse,
   ExecutionStatus,
-  ExecutionStatusResponse,
   ExecutionSummary,
-  ListExecutionsResponse,
+  GetAgentResponse,
+  ListAgentExecutionsResponse,
+  ListAgentsResponse,
   ListVersionsResponse,
+  ListWorkflowExecutionsResponse,
   ListWorkflowsResponse,
+  RunAgentResponse,
   RunWorkflowBody,
   RunWorkflowResponse,
+  WorkflowExecutionStatusResponse,
   WorkflowSummary,
   WorkflowVersion,
 } from './generated/types.gen';

package/src/lib/files.ts

@@ -126,3 +126,30 @@ export function buildMultipart(args: {
 
   return { formData: fd, fileCount };
 }
+
+/**
+ * Build multipart for agent runs. Agent run endpoints consume `_json` as the
+ * input object itself, unlike workflow runs where `_json` is a sidecar with
+ * `{ input, overrides, trigger }`.
+ */
+export function buildAgentMultipart(input?: Record<string, unknown>): 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;
+    }
+  }
+
+  if (Object.keys(inputScalars).length > 0) {
+    fd.append('_json', JSON.stringify(inputScalars));
+  }
+
+  return { formData: fd, fileCount };
+}

package/src/resources/agents.ts

@@ -0,0 +1,168 @@
+import type { OperationResult } from '../client';
+import type { Client } from '../generated/client';
+import {
+  agentsCreate,
+  agentsExecutionsCancel,
+  agentsExecutionsGet,
+  agentsExecutionsList,
+  agentsGet,
+  agentsList,
+  agentsRun,
+  agentsUpdate,
+} from '../generated/sdk.gen';
+import type {
+  AgentExecutionResponse,
+  CreateAgentBody,
+  CreateAgentResponse,
+  GetAgentResponse,
+  ListAgentExecutionsResponse,
+  ListAgentsResponse,
+  PatchAgentBody,
+  PatchAgentResponse,
+  RunAgentResponse,
+} from '../generated/types.gen';
+import { buildAgentMultipart, hasFileInput } from '../lib/files';
+import type { WorkflowInput } from './workflows';
+
+type Dispatch = <T>(call: () => Promise<OperationResult<T>>) => Promise<T>;
+
+export interface ListAgentsOptions {
+  search?: string;
+  limit?: number;
+  offset?: number;
+  signal?: AbortSignal;
+}
+
+export interface RunAgentOptions {
+  waitForCompletion?: number;
+  signal?: AbortSignal;
+}
+
+export interface ListAgentExecutionsOptions {
+  status?: string;
+  batchId?: string;
+  limit?: number;
+  offset?: number;
+  signal?: AbortSignal;
+}
+
+export class AgentExecutionsResource {
+  constructor(
+    private readonly client: Client,
+    private readonly dispatch: Dispatch
+  ) {}
+
+  async list(
+    agentId: string,
+    options: ListAgentExecutionsOptions = {}
+  ): Promise<ListAgentExecutionsResponse> {
+    const { signal, ...query } = options;
+    return this.dispatch(() =>
+      agentsExecutionsList({ client: this.client, path: { agentId }, query, signal })
+    );
+  }
+
+  async get(
+    executionId: string,
+    options: { include?: string; signal?: AbortSignal } = {}
+  ): Promise<AgentExecutionResponse> {
+    const { signal, include } = options;
+    return this.dispatch(() =>
+      agentsExecutionsGet({
+        client: this.client,
+        path: { executionId },
+        query: include ? { include } : {},
+        signal,
+      })
+    );
+  }
+
+  async cancel(
+    executionId: string,
+    options: { signal?: AbortSignal } = {}
+  ): Promise<AgentExecutionResponse> {
+    return this.dispatch(() =>
+      agentsExecutionsCancel({
+        client: this.client,
+        path: { executionId },
+        signal: options.signal,
+      })
+    );
+  }
+}
+
+export class AgentsResource {
+  public readonly executions: AgentExecutionsResource;
+
+  constructor(
+    private readonly client: Client,
+    private readonly dispatch: Dispatch
+  ) {
+    this.executions = new AgentExecutionsResource(client, dispatch);
+  }
+
+  async list(options: ListAgentsOptions = {}): Promise<ListAgentsResponse> {
+    const { signal, ...query } = options;
+    return this.dispatch(() => agentsList({ client: this.client, query, signal }));
+  }
+
+  async get(agentId: string, options: { signal?: AbortSignal } = {}): Promise<GetAgentResponse> {
+    return this.dispatch(() =>
+      agentsGet({ client: this.client, path: { agentId }, signal: options.signal })
+    );
+  }
+
+  async create(
+    body: CreateAgentBody,
+    options: { signal?: AbortSignal } = {}
+  ): Promise<CreateAgentResponse> {
+    return this.dispatch(() => agentsCreate({ client: this.client, body, signal: options.signal }));
+  }
+
+  async update(
+    agentId: string,
+    body: PatchAgentBody,
+    options: { signal?: AbortSignal } = {}
+  ): Promise<PatchAgentResponse> {
+    return this.dispatch(() =>
+      agentsUpdate({ client: this.client, path: { agentId }, body, signal: options.signal })
+    );
+  }
+
+  async run(
+    agentId: string,
+    input?: WorkflowInput,
+    options: RunAgentOptions = {}
+  ): Promise<RunAgentResponse> {
+    const query =
+      options.waitForCompletion !== undefined
+        ? { wait_for_completion: options.waitForCompletion }
+        : {};
+
+    if (hasFileInput(input)) {
+      const { formData } = buildAgentMultipart(input);
+      return this.dispatch<RunAgentResponse>(
+        () =>
+          this.client.post({
+            url: '/api/v1/agents/{agentId}/run',
+            path: { agentId },
+            query,
+            body: formData,
+            bodySerializer: null,
+            headers: { 'Content-Type': null },
+            signal: options.signal,
+          }) as Promise<OperationResult<RunAgentResponse>>
+      );
+    }
+
+    return this.dispatch(() =>
+      agentsRun({
+        client: this.client,
+        path: { agentId },
+        query,
+        body: { ...(input !== undefined ? { input } : {}) },
+        signal: options.signal,
+      })
+    );
+  }
+}

package/src/resources/executions.ts

@@ -2,25 +2,24 @@ import type { OperationResult } from '../client';
 import { EigenpalTimeoutError } from '../errors';
 import type { Client } from '../generated/client';
 import {
-  executionsCancel,
-  executionsGet,
-  executionsList,
+  workflowsExecutionsCancel,
+  workflowsExecutionsGet,
+  workflowsExecutionsList,
   workflowsRun,
 } from '../generated/sdk.gen';
 import type {
-  CancelExecutionResponse,
+  CancelWorkflowExecutionResponse,
   ExecutionStatus,
-  ExecutionStatusResponse,
-  ListExecutionsResponse,
+  ListWorkflowExecutionsResponse,
   RunWorkflowResponse,
+  WorkflowExecutionStatusResponse,
 } 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;
+  /** Execution status, or an array of statuses. */
+  status?: string | string[];
   /** ISO timestamp or relative expression like `"now()-7d"`. */
   fromDate?: string;
   toDate?: string;
@@ -59,11 +58,11 @@ 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`.
+ * Workflow execution resource — read execution status, list executions, cancel
+ * in-flight executions, and the convenience `runAndWait` helper that wraps a
+ * workflow trigger + client-side poll loop. Reached via `client.workflows.executions`.
  */
-export class ExecutionsResource {
+export class WorkflowExecutionsResource {
   constructor(
     private readonly client: Client,
     private readonly dispatch: Dispatch
@@ -73,31 +72,44 @@ export class ExecutionsResource {
   async get(
     executionId: string,
     options: { includeSteps?: boolean; signal?: AbortSignal } = {}
-  ): Promise<ExecutionStatusResponse> {
-    return this.dispatch<ExecutionStatusResponse>(
+  ): Promise<WorkflowExecutionStatusResponse> {
+    return this.dispatch<WorkflowExecutionStatusResponse>(
       () =>
-        executionsGet({
+        workflowsExecutionsGet({
           client: this.client,
           path: { executionId },
           query: options.includeSteps ? { includeSteps: 'true' } : {},
           signal: options.signal,
-        }) as Promise<OperationResult<ExecutionStatusResponse>>
+        }) as Promise<OperationResult<WorkflowExecutionStatusResponse>>
     );
   }
 
   /** List executions, paginated. */
-  async list(options: ListExecutionsOptions = {}): Promise<ListExecutionsResponse> {
-    const { signal, ...query } = options;
-    return this.dispatch(() => executionsList({ client: this.client, query, signal }));
+  async list(
+    workflowId: string,
+    options: ListExecutionsOptions = {}
+  ): Promise<ListWorkflowExecutionsResponse> {
+    const { signal, status, ...rest } = options;
+    // Wire format takes comma-separated lists; idiomatic JS callers can
+    // pass a string[] and we serialize.
+    const query = {
+      ...rest,
+      ...(status !== undefined
+        ? { status: Array.isArray(status) ? status.join(',') : status }
+        : {}),
+    };
+    return this.dispatch(() =>
+      workflowsExecutionsList({ client: this.client, path: { id: workflowId }, query, signal })
+    );
   }
 
   /** Cancel an execution. Idempotent. */
   async cancel(
     executionId: string,
     options: { signal?: AbortSignal } = {}
-  ): Promise<CancelExecutionResponse> {
+  ): Promise<CancelWorkflowExecutionResponse> {
     return this.dispatch(() =>
-      executionsCancel({
+      workflowsExecutionsCancel({
         client: this.client,
         path: { executionId },
         signal: options.signal,
@@ -128,7 +140,7 @@ export class ExecutionsResource {
       ? await this.dispatch<RunWorkflowResponse>(() => {
           const { formData } = buildMultipart({ input, overrides: options.overrides });
           return this.client.post({
-            url: '/v1/workflows/{id}/run',
+            url: '/api/v1/workflows/{id}/run',
             path: { id: workflowId },
             query: triggerQuery,
             body: formData,

package/src/resources/workflows.ts

@@ -13,6 +13,7 @@ import type {
   WorkflowSummary,
 } from '../generated/types.gen';
 import { buildMultipart, hasFileInput } from '../lib/files';
+import { WorkflowExecutionsResource } from './executions';
 
 /**
  * Workflow inputs keyed by name as declared in the workflow YAML.
@@ -58,10 +59,14 @@ type Dispatch = <T>(call: () => Promise<OperationResult<T>>) => Promise<T>;
  * workflows. Reached via `client.workflows`.
  */
 export class WorkflowsResource {
+  public readonly executions: WorkflowExecutionsResource;
+
   constructor(
     private readonly client: Client,
     private readonly dispatch: Dispatch
-  ) {}
+  ) {
+    this.executions = new WorkflowExecutionsResource(client, dispatch);
+  }
 
   /**
    * Execute a workflow.
@@ -71,7 +76,8 @@ export class WorkflowsResource {
    * @param options — `version`, `waitForCompletion`, `overrides`.
    *
    * - With no `waitForCompletion`, returns immediately with `{ executionId }`.
-   *   Poll via `client.executions.get(id)` or use `client.executions.runAndWait`.
+   *   Poll via `client.workflows.executions.get(id)` or use
+   *   `client.workflows.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.
@@ -94,7 +100,7 @@ export class WorkflowsResource {
       return this.dispatch<RunWorkflowResponse>(
         () =>
           this.client.post({
-            url: '/v1/workflows/{id}/run',
+            url: '/api/v1/workflows/{id}/run',
             path: { id: workflowId },
             query,
             body: formData,

package/src/runtime-config.ts

@@ -3,11 +3,11 @@ 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
+ * The hand-written `EigenpalClient` 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.
+ * are populated when an `EigenpalClient` instance is created.
  */
 export const createClientConfig: CreateClientConfig = (config) => ({
   ...config,

package/src/telemetry.ts

@@ -0,0 +1,54 @@
+/**
+ * SDK telemetry headers attached to every outbound request.
+ *
+ * The server reads these to track adoption — which language, which
+ * version, which runtime are calling? Lets us answer "should we still
+ * support Node 20?" or "is the 0.4 series still in use?" from log
+ * aggregation alone, without having to ship a separate phone-home.
+ *
+ * Header convention follows the Stainless / Anthropic SDK pattern:
+ *   X-Eigenpal-Sdk          — language tag ("typescript")
+ *   X-Eigenpal-Sdk-Version  — package version (rewritten at publish)
+ *   X-Eigenpal-Sdk-Runtime  — "bun-1.3.11" / "node-22.0.0" / "deno-X" / "browser"
+ *   X-Eigenpal-Sdk-Os       — "darwin-arm64" / "linux-x64" / "browser"
+ *
+ * `User-Agent` carries the same info in a single human-readable string
+ * for log lines and proxies that don't surface custom headers.
+ */
+
+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.4.11';
+
+function detectRuntime(): string {
+  const g = globalThis as unknown as {
+    Bun?: { version: string };
+    Deno?: { version?: { deno?: string } };
+  };
+  if (g.Bun?.version) return `bun-${g.Bun.version}`;
+  if (g.Deno?.version?.deno) return `deno-${g.Deno.version.deno}`;
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    return `node-${process.versions.node}`;
+  }
+  return 'browser';
+}
+
+function detectOs(): string {
+  if (typeof process !== 'undefined' && process.platform) {
+    return `${process.platform}-${process.arch}`;
+  }
+  return 'browser';
+}
+
+export function buildTelemetryHeaders(): Record<string, string> {
+  const runtime = detectRuntime();
+  const os = detectOs();
+  return {
+    'X-Eigenpal-Sdk': SDK_LANGUAGE,
+    'X-Eigenpal-Sdk-Version': SDK_VERSION,
+    'X-Eigenpal-Sdk-Runtime': runtime,
+    'X-Eigenpal-Sdk-Os': os,
+    'User-Agent': `eigenpal-sdk-typescript/${SDK_VERSION} (${runtime}; ${os})`,
+  };
+}