@eigenpal/sdk 0.6.16 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @eigenpal/sdk
 
+## 0.7.0
+
+### Minor Changes
+
+- 963fd6c: Unify run detail on `GET /api/v1/runs/{id}`: return the canonical Run object directly (no `{ run: ... }` envelope) and merge expanded fields in-place via documented `expand` tokens. Remove the session-only `expand=internal` dashboard escape hatch; SDKs and CLI now use explicit expand lists.
+
+### Patch Changes
+
+- 12c00d8: Docs: clearer wording in the file-input and TypeScript-runtime sections. No API or behavior changes.
+
+## 0.6.17
+
+### Patch Changes
+
+- 716c3cf: Update the hosted default API base URL and API-key guidance from `app.eigenpal.com` to `studio.eigenpal.com`.
+
 ## 0.6.15
 
 ### Minor Changes

package/README.md

@@ -15,7 +15,7 @@ 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**.
+Get an API key at **studio.eigenpal.com → Settings → API Keys**.
 
 ## Quick start
 
@@ -29,7 +29,7 @@ const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });
 const result = await client.workflows.executions.runAndWait('extract-invoice', {
   contract_document: file,
 });
-console.log(result.status, result.output);
+console.log(result.finished, result.output);
 ```
 
 ## Authentication
@@ -53,15 +53,15 @@ const client = new EigenpalClient({
 });
 ```
 
-`baseUrl` likewise wins over the `EIGENPAL_BASE_URL` env fallback. Defaults to `https://app.eigenpal.com` (the hosted cloud).
+`baseUrl` likewise wins over the `EIGENPAL_BASE_URL` env fallback. Defaults to `https://studio.eigenpal.com` (the hosted cloud).
 
 ## Starting runs
 
 `client.run(target, input?, options?)` starts a workflow or agent run. Targets can be strings such as `workflows.extract-invoice` / `agents.invoice-agent` or structured objects like `{ type: 'workflow', slug: 'extract-invoice' }`.
 
 ```ts
-// Async: returns immediately with { runId }.
-const { runId } = await client.run('workflows.extract-invoice', {
+// Async: returns immediately with { id }.
+const { id: runId } = await client.run('workflows.extract-invoice', {
   contract_document: file,
 });
 
@@ -71,7 +71,7 @@ const result = await client.run(
   { contract_document: file },
   { waitForCompletion: 60 }
 );
-console.log(result.status, result.output);
+console.log(result.finished, result.output);
 
 // Long-running: client-side polling, default 5min cap.
 const final = await client.workflows.executions.runAndWait('extract-invoice', {
@@ -112,11 +112,18 @@ const runs = await client.runs.list({
   status: 'failed,cancelled',
 });
 
-const run = await client.runs.get(runId, { include: 'detail' });
-await client.runs.cancel(runId);
-
-const status = await client.runs.get(runId);
-//   { run: { id, status, output?, error?, createdAt, completedAt? } }
+const run = await client.runs.get(runId);
+//   { id, type, finished, output, files, error, timing, ... }
+
+// Add heavier optional sections with `expand`.
+const withUsage = await client.runs.get(runId, { expand: ['usage', 'execution'] });
+console.log(
+  withUsage.output,
+  withUsage.files,
+  withUsage.error,
+  withUsage.usage,
+  withUsage.execution
+);
 
 const list = await client.runs.list({
   type: 'workflow',
@@ -146,7 +153,7 @@ await client.workflows.versions('extract-invoice');
 await client.agents.list({ search: 'invoice' });
 await client.agents.get('invoice-agent');
 
-const { runId: agentRunId } = await client.run('agents.invoice-agent', {
+const { id: agentRunId } = await client.run('agents.invoice-agent', {
   invoice: file,
 });
 
@@ -181,7 +188,7 @@ try {
   const result = await client.workflows.executions.runAndWait('extract-invoice', {
     language: 'en',
   });
-  console.log(result.status, result.output);
+  console.log(result.finished, result.output);
 } catch (err) {
   if (err instanceof EigenpalValidationError) {
     for (const issue of err.issues) console.error(`${issue.field}: ${issue.message}`);

package/package.json

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

package/src/client.ts

@@ -1,7 +1,9 @@
 import { EigenpalError, EigenpalTimeoutError, errorFromResponse } from './errors';
 import { createClient, createConfig, type Client, type Config } from './generated/client';
-import { runStartWithTarget } from './generated/sdk.gen';
-import type { ApiErrorEnvelope } from './generated/types.gen';
+import type {
+  ApiErrorEnvelope,
+  RunStartResponse as GeneratedRunStartResponse,
+} from './generated/types.gen';
 import { buildRunJsonBody, buildRunMultipart, hasFileInput } from './lib/files';
 import { AgentsResource } from './resources/agents';
 import { AutomationsResource } from './resources/automations';
@@ -21,7 +23,7 @@ export interface EigenpalOptions {
   /**
    * Override the API base URL.
    *
-   * Defaults to `EIGENPAL_BASE_URL` if set, otherwise `https://app.eigenpal.com`.
+   * Defaults to `EIGENPAL_BASE_URL` if set, otherwise `https://studio.eigenpal.com`.
    */
   baseUrl?: string;
   /** Per-request timeout in milliseconds. Defaults to 60_000. */
@@ -34,7 +36,7 @@ export interface EigenpalOptions {
   defaultHeaders?: Record<string, string>;
 }
 
-const DEFAULT_BASE_URL = 'https://app.eigenpal.com';
+const DEFAULT_BASE_URL = 'https://studio.eigenpal.com';
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_RETRIES = 3;
 
@@ -64,28 +66,27 @@ export type RunTarget =
 
 export type RunInput = Record<string, unknown>;
 
-export interface RunOptions {
-  input?: RunInput;
+/** Third argument to `client.run()` — transport knobs, not workflow/agent input. */
+export interface RunCallOptions {
   waitForCompletion?: number;
   overrides?: { steps?: Record<string, Record<string, unknown>> };
   signal?: AbortSignal;
 }
 
-export type RunCallOptions = Omit<RunOptions, 'input'>;
-
 export interface RerunOptions {
   version?: 'latest' | 'original' | string;
   waitForCompletion?: number;
   signal?: AbortSignal;
 }
 
-export type RunStartResponse = Record<string, unknown> & {
-  runId: string;
-  type: 'workflow' | 'agent';
-  status?: string;
-  output?: unknown;
-  error?: string | null;
-};
+/**
+ * Run-start response — async bodies are `{ id, type, finished: false }` (201);
+ * wait-expired bodies use the same shape (202); sync terminal completion matches
+ * `client.runs.get(id)` (200).
+ * Aliases the generated OpenAPI type so the handwritten and generated surfaces
+ * can never diverge.
+ */
+export type RunStartResponse = GeneratedRunStartResponse;
 
 /**
  * The EigenPal SDK client.
@@ -97,15 +98,14 @@ export type RunStartResponse = Record<string, unknown> & {
  * const client = new EigenpalClient();
  *
  * // Async — enqueue and poll later.
- * const { runId } = await client.run('workflows.extract-invoice', {
- *   input: { language: 'en' },
- * });
+ * const { id } = await client.run('workflows.extract-invoice', { language: 'en' });
  *
  * // Sync (server holds the connection up to 60s).
- * const result = await client.run('workflows.extract-invoice', {
- *   input: { language: 'en' },
- *   waitForCompletion: 60,
- * });
+ * const result = await client.run(
+ *   'workflows.extract-invoice',
+ *   { language: 'en' },
+ *   { waitForCompletion: 60 }
+ * );
  *
  * // Client-side polling for long-running executions (default 5min cap).
  * const final = await client.workflows.executions.runAndWait('wf_abc', { language: 'en' });
@@ -177,77 +177,65 @@ export class EigenpalClient {
   async run(
     target: RunTarget,
     input?: RunInput,
-    options?: RunCallOptions
-  ): Promise<RunStartResponse>;
-  async run(target: RunTarget, options?: RunOptions): Promise<RunStartResponse>;
-  async run(request: { target: RunTarget } & RunOptions): Promise<RunStartResponse>;
-  async run(
-    targetOrRequest: RunTarget | ({ target: RunTarget } & RunOptions),
-    inputOrOptions: RunInput | RunOptions = {},
     options: RunCallOptions = {}
   ): Promise<RunStartResponse> {
-    const targetPassedDirectly =
-      typeof targetOrRequest === 'string' ||
-      (targetOrRequest &&
-        typeof targetOrRequest === 'object' &&
-        'type' in targetOrRequest &&
-        !('target' in targetOrRequest));
-    const request = targetPassedDirectly
-      ? { target: targetOrRequest, ...normalizeRunArgs(inputOrOptions, options) }
-      : (targetOrRequest as { target: RunTarget } & RunOptions);
-    const { pathTarget, version } = pathTargetFromRunTarget(request.target);
+    assertRunTarget(target);
+    assertInputNotOptionsBag(input);
+
+    const { pathTarget, version } = pathTargetFromRunTarget(target);
     const query = runQuery({
-      waitForCompletion: request.waitForCompletion,
+      waitForCompletion: options.waitForCompletion,
       version,
     });
 
-    if (hasFileInput(request.input)) {
+    if (hasFileInput(input)) {
       const { formData } = await buildRunMultipart({
-        input: request.input,
-        overrides: request.overrides,
+        target: pathTarget,
+        input,
+        overrides: options.overrides,
       });
       return this._request<RunStartResponse>(
         () =>
           this.client.post({
-            url: `/api/v1/run/${encodeURIComponent(pathTarget)}`,
+            url: '/api/v1/runs',
             query,
             body: formData,
             bodySerializer: null,
             headers: { 'Content-Type': null },
-            signal: request.signal,
+            signal: options.signal,
           }) as Promise<OperationResult<RunStartResponse>>
       );
     }
 
-    const body = buildRunJsonBody(request.input, request.overrides);
+    const body = buildRunJsonBody(pathTarget, input, options.overrides);
     return this._request<RunStartResponse>(
       () =>
-        runStartWithTarget({
-          client: this.client,
-          path: { target: pathTarget },
+        this.client.post({
+          url: '/api/v1/runs',
           query,
           body,
-          signal: request.signal,
+          signal: options.signal,
         }) as Promise<OperationResult<RunStartResponse>>
     );
   }
 
-  async rerun(runId: string, options: RerunOptions = {}): Promise<Record<string, unknown>> {
-    return this._request<Record<string, unknown>>(
+  async rerun(runId: string, options: RerunOptions = {}): Promise<RunStartResponse> {
+    const query: { version?: string; wait_for_completion?: number } = {};
+    if (options.version && options.version !== 'latest') {
+      query.version = options.version;
+    }
+    if (options.waitForCompletion !== undefined) {
+      query.wait_for_completion = options.waitForCompletion;
+    }
+
+    return this._request<RunStartResponse>(
       () =>
         this.client.post({
           url: '/api/v1/runs/{id}/rerun',
           path: { id: runId },
-          query:
-            options.waitForCompletion !== undefined
-              ? { wait_for_completion: options.waitForCompletion }
-              : undefined,
-          body:
-            options.version && options.version !== 'latest'
-              ? { sourceRef: options.version }
-              : undefined,
+          query: Object.keys(query).length > 0 ? query : undefined,
           signal: options.signal,
-        }) as Promise<OperationResult<Record<string, unknown>>>
+        }) as Promise<OperationResult<RunStartResponse>>
     );
   }
 
@@ -266,7 +254,7 @@ export class EigenpalClient {
         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`).
+        // (e.g. `https://eigenpal.com` instead of `https://studio.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.
@@ -338,14 +326,26 @@ function pathTargetFromRunTarget(target: RunTarget): { pathTarget: string; versi
   if (!idOrSlug) {
     throw new EigenpalError('Run target objects require `slug` or `id`.', { status: 0 });
   }
-  const root = target.type === 'agent' ? 'agents' : 'workflows';
-  const name = idOrSlug.includes('.') ? idOrSlug : `${root}.${idOrSlug.split('/').join('.')}`;
+  const name =
+    target.type === 'agent'
+      ? agentPathTarget(idOrSlug)
+      : `workflows.${idOrSlug.split('/').join('.')}`;
   return {
     pathTarget: name,
     version: target.version && target.version !== 'latest' ? target.version : undefined,
   };
 }
 
+function agentPathTarget(idOrSlug: string): string {
+  if (!idOrSlug.includes('.')) return `agents.${idOrSlug.split('/').join('.')}`;
+  if (!idOrSlug.startsWith('agents.')) {
+    throw new EigenpalError(`Agent target must be rooted at "agents.", got "${idOrSlug}".`, {
+      status: 0,
+    });
+  }
+  return idOrSlug;
+}
+
 function runQuery(options: {
   waitForCompletion?: number;
   version?: string;
@@ -368,29 +368,29 @@ function assertJsonResponse(response: Response): void {
     `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".`,
+      `e.g. "https://studio.eigenpal.com".`,
     { status: response.status }
   );
 }
 
-function normalizeRunArgs(
-  inputOrOptions: RunInput | RunOptions,
-  options: RunCallOptions
-): RunOptions {
-  if (Object.keys(options).length > 0) {
-    return { ...options, input: inputOrOptions as RunInput };
-  }
-  if (looksLikeRunOptions(inputOrOptions)) {
-    return inputOrOptions;
+function assertRunTarget(target: RunTarget): void {
+  if (typeof target === 'object' && target !== null && 'target' in target) {
+    throw new EigenpalError(
+      'Pass the run target as the first argument to client.run(target, input?, options?). ' +
+        'Do not wrap it in { target }.',
+      { status: 0 }
+    );
   }
-  return { input: inputOrOptions as RunInput };
 }
 
-function looksLikeRunOptions(value: unknown): value is RunOptions {
-  if (!value || typeof value !== 'object') return false;
-  return (
-    'input' in value || 'waitForCompletion' in value || 'overrides' in value || 'signal' in value
-  );
+function assertInputNotOptionsBag(input: RunInput | undefined): void {
+  if (!input || typeof input !== 'object') return;
+  if ('waitForCompletion' in input || 'overrides' in input || 'signal' in input) {
+    throw new EigenpalError(
+      'Pass workflow/agent input as the second argument and { waitForCompletion, overrides, signal } as the third.',
+      { status: 0 }
+    );
+  }
 }
 
 function isRetriableStatus(status: number): boolean {

package/src/errors.ts

@@ -27,7 +27,7 @@ export class EigenpalAuthError extends EigenpalError {
   constructor(envelope?: ApiErrorEnvelope) {
     super(
       envelope?.issues?.[0]?.message ??
-        'Invalid or missing API key. Generate one at app.eigenpal.com → Settings → API Keys; ' +
+        'Invalid or missing API key. Generate one at studio.eigenpal.com → Settings → API Keys; ' +
           'pass it as `new EigenpalClient({ apiKey })` or set EIGENPAL_API_KEY.',
       { status: 401, envelope }
     );

package/src/generated/client/client.gen.ts

@@ -37,7 +37,7 @@ export const createClient = (config: Config = {}): Client => {
     ThrowOnError extends boolean = boolean,
     Url extends string = string,
   >(
-    options: RequestOptions<TData, TResponseStyle, ThrowOnError, Url>
+    options: RequestOptions<TData, TResponseStyle, ThrowOnError, Url>,
   ) => {
     const opts = {
       ..._config,

package/src/generated/client/index.ts

@@ -1,12 +1,12 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 export type { Auth } from '../core/auth.gen';
+export type { QuerySerializerOptions } from '../core/bodySerializer.gen';
 export {
   formDataBodySerializer,
   jsonBodySerializer,
   urlSearchParamsBodySerializer,
 } from '../core/bodySerializer.gen';
-export type { QuerySerializerOptions } from '../core/bodySerializer.gen';
 export { buildClientParams } from '../core/params.gen';
 export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen';
 export { createClient } from './client.gen';

package/src/generated/client/types.gen.ts

@@ -1,7 +1,10 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 import type { Auth } from '../core/auth.gen';
-import type { ServerSentEventsOptions, ServerSentEventsResult } from '../core/serverSentEvents.gen';
+import type {
+  ServerSentEventsOptions,
+  ServerSentEventsResult,
+} from '../core/serverSentEvents.gen';
 import type { Client as CoreClient, Config as CoreConfig } from '../core/types.gen';
 import type { Middleware } from './utils.gen';
 
@@ -143,7 +146,7 @@ type MethodFn = <
   ThrowOnError extends boolean = false,
   TResponseStyle extends ResponseStyle = 'fields',
 >(
-  options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>
+  options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>,
 ) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
 
 type SseFn = <
@@ -152,7 +155,7 @@ type SseFn = <
   ThrowOnError extends boolean = false,
   TResponseStyle extends ResponseStyle = 'fields',
 >(
-  options: Omit<RequestOptions<never, TResponseStyle, ThrowOnError>, 'method'>
+  options: Omit<RequestOptions<never, TResponseStyle, ThrowOnError>, 'method'>,
 ) => Promise<ServerSentEventsResult<TData, TError>>;
 
 type RequestFn = <
@@ -162,7 +165,7 @@ type RequestFn = <
   TResponseStyle extends ResponseStyle = 'fields',
 >(
   options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'> &
-    Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, 'method'>
+    Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, 'method'>,
 ) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
 
 type BuildUrlFn = <
@@ -173,7 +176,7 @@ type BuildUrlFn = <
     url: string;
   },
 >(
-  options: TData & Options<TData>
+  options: TData & Options<TData>,
 ) => string;
 
 export type Client = CoreClient<RequestFn, Config, MethodFn, BuildUrlFn, SseFn> & {
@@ -189,7 +192,7 @@ export type Client = CoreClient<RequestFn, Config, MethodFn, BuildUrlFn, SseFn>
  * to ensure your client always has the correct values.
  */
 export type CreateClientConfig<T extends ClientOptions = ClientOptions> = (
-  override?: Config<ClientOptions & T>
+  override?: Config<ClientOptions & T>,
 ) => Config<Required<ClientOptions> & T>;
 
 export interface TDataShape {

package/src/generated/client/utils.gen.ts

@@ -103,7 +103,7 @@ const checkForExistence = (
   options: Pick<RequestOptions, 'auth' | 'query'> & {
     headers: Headers;
   },
-  name?: string
+  name?: string,
 ): boolean => {
   if (!name) {
     return false;
@@ -208,7 +208,7 @@ export const mergeHeaders = (
         // content value in OpenAPI specification is 'application/json'
         mergedHeaders.set(
           key,
-          typeof value === 'object' ? JSON.stringify(value) : (value as string)
+          typeof value === 'object' ? JSON.stringify(value) : (value as string),
         );
       }
     }
@@ -222,7 +222,7 @@ type ErrInterceptor<Err, Res, Req, Options> = (
   response: Res | undefined,
   /** request may be undefined, because error may be from building the request object itself */
   request: Req | undefined,
-  options: Options
+  options: Options,
 ) => Err | Promise<Err>;
 
 type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
@@ -230,7 +230,7 @@ type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Pr
 type ResInterceptor<Res, Req, Options> = (
   response: Res,
   request: Req,
-  options: Options
+  options: Options,
 ) => Res | Promise<Res>;
 
 class Interceptors<Interceptor> {
@@ -308,7 +308,7 @@ const defaultHeaders = {
 };
 
 export const createConfig = <T extends ClientOptions = ClientOptions>(
-  override: Config<Omit<ClientOptions, keyof T> & T> = {}
+  override: Config<Omit<ClientOptions, keyof T> & T> = {},
 ): Config<Omit<ClientOptions, keyof T> & T> => ({
   ...jsonBodySerializer,
   headers: defaultHeaders,

package/src/generated/client.gen.ts

@@ -13,10 +13,6 @@ import type { ClientOptions as ClientOptions2 } from './types.gen';
  * `setConfig()`. This is useful for example if you're using Next.js
  * to ensure your client always has the correct values.
  */
-export type CreateClientConfig<T extends ClientOptions = ClientOptions2> = (
-  override?: Config<ClientOptions & T>
-) => Config<Required<ClientOptions> & T>;
+export type CreateClientConfig<T extends ClientOptions = ClientOptions2> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
 
-export const client = createClient(
-  createClientConfig(createConfig<ClientOptions2>({ baseUrl: 'https://app.eigenpal.com' }))
-);
+export const client = createClient(createClientConfig(createConfig<ClientOptions2>({ baseUrl: 'https://studio.eigenpal.com' })));

package/src/generated/core/auth.gen.ts

@@ -21,7 +21,7 @@ export interface Auth {
 
 export const getAuthToken = async (
   auth: Auth,
-  callback: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken
+  callback: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken,
 ): Promise<string | undefined> => {
   const token = typeof callback === 'function' ? await callback(auth) : callback;
 

package/src/generated/core/pathSerializer.gen.ts

@@ -117,7 +117,7 @@ export const serializePrimitiveParam = ({
 
   if (typeof value === 'object') {
     throw new Error(
-      'Deeply-nested arrays/objects aren’t supported. Provide your own `querySerializer()` to handle these.'
+      'Deeply-nested arrays/objects aren’t supported. Provide your own `querySerializer()` to handle these.',
     );
   }
 
@@ -164,7 +164,7 @@ export const serializeObjectParam = ({
         allowReserved,
         name: style === 'deepObject' ? `${name}[${key}]` : key,
         value: v as string,
-      })
+      }),
     )
     .join(separator);
   return style === 'label' || style === 'matrix' ? separator + joinedValues : joinedValues;

package/src/generated/core/utils.gen.ts

@@ -57,7 +57,7 @@ export const defaultPathSerializer = ({ path, url: _url }: PathSerializer) => {
             style,
             value: value as Record<string, unknown>,
             valueOnly: true,
-          })
+          }),
         );
         continue;
       }
@@ -68,13 +68,13 @@ export const defaultPathSerializer = ({ path, url: _url }: PathSerializer) => {
           `;${serializePrimitiveParam({
             name,
             value: value as string,
-          })}`
+          })}`,
         );
         continue;
       }
 
       const replaceValue = encodeURIComponent(
-        style === 'label' ? `.${value as string}` : (value as string)
+        style === 'label' ? `.${value as string}` : (value as string),
       );
       url = url.replace(match, replaceValue);
     }