Simplex TypeScript SDK

Official TypeScript SDK for the Simplex API.

Installation

npm install simplex-ts

Quick Start

import { SimplexClient } from 'simplex-ts';

const client = new SimplexClient({
  apiKey: 'YOUR_API_KEY_HERE'
});

// Run a workflow without variables
const result = await client.workflows.run('workflow-id');

// Run a workflow with variables
const resultWithVars = await client.workflows.run('workflow-id', {
  variables: {
    username: 'john_doe',
    product_id: '12345'
  }
});

console.log('Session ID:', result.session_id);

Configuration

const client = new SimplexClient({
  apiKey: 'YOUR_API_KEY_HERE',
  timeout: 30000,      // Optional: Request timeout in ms (default: 30000)
  maxRetries: 3,       // Optional: Number of retries (default: 3)
  retryDelay: 1000     // Optional: Delay between retries in ms (default: 1000)
});

API Methods

Workflows

Run a workflow

// Run without any options
const result = await client.workflows.run('workflow-id');

// Run with variables
const result = await client.workflows.run('workflow-id', {
  variables: { key: 'value' }
});

// Run with all options
const result = await client.workflows.run('workflow-id', {
  variables: { key: 'value' },
  metadata: 'optional-metadata',
  webhookUrl: 'https://your-webhook.com'
});

Search workflows

Search for workflows by name and/or metadata. Both parameters support partial matching.

// Search by workflow name (partial match)
const results = await client.workflows.search({
  workflowName: 'copy'
});

console.log(`Found ${results.count} workflows`);
results.workflows.forEach(workflow => {
  console.log(`- ${workflow.workflow_name} (${workflow.workflow_id})`);
  console.log(`  Metadata: ${workflow.metadata || 'None'}`);
});

// Search by metadata (partial match)
const results = await client.workflows.search({
  metadata: 'prod'
});

// Search by both name and metadata
const results = await client.workflows.search({
  workflowName: 'copy',
  metadata: 'staging'
});

// At least one parameter is required
try {
  await client.workflows.search({}); // This will throw an error
} catch (error) {
  console.error('Error: At least one search parameter required');
}

Update workflow metadata

Update the metadata string for a specific workflow.

// Update metadata for a workflow
const result = await client.workflows.updateMetadata(
  'workflow-id-here',
  'production'
);

console.log('Updated workflow:', result.workflow_id);
console.log('New metadata:', result.metadata);

// Use metadata for categorization
await client.workflows.updateMetadata('workflow-1', 'production');
await client.workflows.updateMetadata('workflow-2', 'staging');
await client.workflows.updateMetadata('workflow-3', 'development');

// Then search by category
const prodWorkflows = await client.workflows.search({
  metadata: 'prod'  // Will match 'production'
});

Create a workflow session

const session = await client.workflows.createWorkflowSession(
  'my-workflow-name',
  'https://example.com',
  {
    sessionData: { key: 'value' },
    proxies: false
  }
);

console.log('Session ID:', session.session_id);

Run an agent task

Execute a specific task using the agentic endpoint:

const result = await client.workflows.agentic(
  'Find and click the login button',
  'session-id',
  {
    maxSteps: 10,
    actionsToExclude: ['scroll', 'wait'],
    variables: { username: '[email protected]' }
  }
);

console.log('Task succeeded:', result.succeeded);
console.log('Result:', result.result);

Run a named agent

Run a pre-configured agent by name:

const result = await client.workflows.run_agent(
  'my-agent-name',
  'session-id',
  {
    key1: 'value1',
    key2: 'value2'
  }
);

console.log('Agent succeeded:', result.succeeded);
console.log('Session ID:', result.session_id);
console.log('Result:', result.result);

Session Management

Retrieve session replay video

Download the MP4 video recording of a session:

const videoBuffer = await client.retrieveSessionReplay('session-id');

// Save to file
import * as fs from 'fs';
fs.writeFileSync('session-replay.mp4', videoBuffer);

Retrieve session logs

Get the JSON logs for a completed session:

const logs = await client.retrieveSessionLogs('session-id');

console.log('Session logs:', logs);

// Save to file
import * as fs from 'fs';
fs.writeFileSync('session-logs.json', JSON.stringify(logs, null, 2));

Get session store

Retrieve metadata about files downloaded during a session:

const sessionStore = await client.getSessionStore('session-id');

console.log('Session store:', sessionStore);

Download session files

Download files that were saved during a session:

// Download all files as a zip
const zipBuffer = await client.downloadSessionFiles('session-id');
fs.writeFileSync('session-files.zip', zipBuffer);

// Download a specific file
const fileBuffer = await client.downloadSessionFiles('session-id', 'filename.pdf');
fs.writeFileSync('filename.pdf', fileBuffer);

Error Handling

The SDK provides typed error classes for different error scenarios:

import {
  SimplexClient,
  WorkflowError,
  ValidationError,
  AuthenticationError,
  RateLimitError,
  NetworkError
} from 'simplex-ts';

try {
  const result = await client.workflows.run('workflow-id');
} catch (error) {
  if (error instanceof WorkflowError) {
    console.error('Workflow failed:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

Examples

The SDK includes several example files to demonstrate different use cases:

• examples/run-workflow.ts - Basic workflow execution
• examples/create-workflow.ts - Creating workflow sessions with agentic tasks
• examples/download-file.ts - Download files from workflow sessions
• examples/session-replay-and-logs.ts - Retrieve session replays and logs
• examples/search-and-metadata.ts - Search workflows and manage metadata
• examples/webhook-express.ts - Webhook verification with Express
• examples/webhook-nextjs.ts - Webhook verification with Next.js

Run examples with:

npx tsx examples/run-workflow.ts
npx tsx examples/session-replay-and-logs.ts
npx tsx examples/download-file.ts

Development

Build the SDK

npm run build

Watch mode

npm run dev

Clean build files

npm run clean

License

MIT