sim/packages/ts-sdk

Sim Studio TypeScript SDK

The official TypeScript/JavaScript SDK for Sim Studio, allowing you to execute workflows programmatically from your applications.

Installation

npm install simstudio-ts-sdk
# or 
yarn add simstudio-ts-sdk
# or
bun add simstudio-ts-sdk

Quick Start

import { SimStudioClient } from 'simstudio-ts-sdk';

// Initialize the client
const client = new SimStudioClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://simstudio.ai' // optional, defaults to https://simstudio.ai
});

// Execute a workflow
try {
  const result = await client.executeWorkflow('workflow-id');
  console.log('Workflow executed successfully:', result);
} catch (error) {
  console.error('Workflow execution failed:', error);
}

API Reference

SimStudioClient

Constructor

new SimStudioClient(config: SimStudioConfig)

• config.apiKey (string): Your Sim Studio API key
• config.baseUrl (string, optional): Base URL for the Sim Studio API (defaults to https://simstudio.ai)

Methods

executeWorkflow(workflowId, options?)

Execute a workflow with optional input data.

const result = await client.executeWorkflow('workflow-id', {
  input: { message: 'Hello, world!' },
  timeout: 30000 // 30 seconds
});

Parameters:

• workflowId (string): The ID of the workflow to execute
• options (ExecutionOptions, optional):
  • input (any): Input data to pass to the workflow
  • timeout (number): Timeout in milliseconds (default: 30000)

Returns: Promise<WorkflowExecutionResult>

getWorkflowStatus(workflowId)

Get the status of a workflow (deployment status, etc.).

const status = await client.getWorkflowStatus('workflow-id');
console.log('Is deployed:', status.isDeployed);

Parameters:

• workflowId (string): The ID of the workflow

Returns: Promise<WorkflowStatus>

validateWorkflow(workflowId)

Validate that a workflow is ready for execution.

const isReady = await client.validateWorkflow('workflow-id');
if (isReady) {
  // Workflow is deployed and ready
}

Parameters:

• workflowId (string): The ID of the workflow

Returns: Promise<boolean>

executeWorkflowSync(workflowId, options?)

Execute a workflow and poll for completion (useful for long-running workflows).

const result = await client.executeWorkflowSync('workflow-id', {
  input: { data: 'some input' },
  timeout: 60000
});

Parameters:

• workflowId (string): The ID of the workflow to execute
• options (ExecutionOptions, optional):
  • input (any): Input data to pass to the workflow
  • timeout (number): Timeout for the initial request in milliseconds

Returns: Promise<WorkflowExecutionResult>

setApiKey(apiKey)

Update the API key.

client.setApiKey('new-api-key');

setBaseUrl(baseUrl)

Update the base URL.

client.setBaseUrl('https://my-custom-domain.com');

Types

WorkflowExecutionResult

interface WorkflowExecutionResult {
  success: boolean;
  output?: any;
  error?: string;
  logs?: any[];
  metadata?: {
    duration?: number;
    executionId?: string;
    [key: string]: any;
  };
  traceSpans?: any[];
  totalDuration?: number;
}

WorkflowStatus

interface WorkflowStatus {
  isDeployed: boolean;
  deployedAt?: string;
  isPublished: boolean;
  needsRedeployment: boolean;
}

SimStudioError

class SimStudioError extends Error {
  code?: string;
  status?: number;
}

Examples

Basic Workflow Execution

import { SimStudioClient } from 'simstudio-ts-sdk';

const client = new SimStudioClient({
  apiKey: process.env.SIMSTUDIO_API_KEY!
});

async function runWorkflow() {
  try {
    // Check if workflow is ready
    const isReady = await client.validateWorkflow('my-workflow-id');
    if (!isReady) {
      throw new Error('Workflow is not deployed or ready');
    }

    // Execute the workflow
    const result = await client.executeWorkflow('my-workflow-id', {
      input: {
        message: 'Process this data',
        userId: '12345'
      }
    });

    if (result.success) {
      console.log('Output:', result.output);
      console.log('Duration:', result.metadata?.duration);
    } else {
      console.error('Workflow failed:', result.error);
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

runWorkflow();

Error Handling

import { SimStudioClient, SimStudioError } from 'simstudio-ts-sdk';

const client = new SimStudioClient({
  apiKey: process.env.SIMSTUDIO_API_KEY!
});

async function executeWithErrorHandling() {
  try {
    const result = await client.executeWorkflow('workflow-id');
    return result;
  } catch (error) {
    if (error instanceof SimStudioError) {
      switch (error.code) {
        case 'UNAUTHORIZED':
          console.error('Invalid API key');
          break;
        case 'TIMEOUT':
          console.error('Workflow execution timed out');
          break;
        case 'USAGE_LIMIT_EXCEEDED':
          console.error('Usage limit exceeded');
          break;
        case 'INVALID_JSON':
          console.error('Invalid JSON in request body');
          break;
        default:
          console.error('Workflow error:', error.message);
      }
    } else {
      console.error('Unexpected error:', error);
    }
    throw error;
  }
}

Environment Configuration

// Using environment variables
const client = new SimStudioClient({
  apiKey: process.env.SIMSTUDIO_API_KEY!,
  baseUrl: process.env.SIMSTUDIO_BASE_URL // optional
});

Getting Your API Key

1. Log in to your Sim Studio account
2. Navigate to your workflow
3. Click on "Deploy" to deploy your workflow
4. Select or create an API key during the deployment process
5. Copy the API key to use in your application

Development

Running Tests

To run the tests locally:

1. Clone the repository and navigate to the TypeScript SDK directory:

   cd packages/ts-sdk
   

2. Install dependencies:

   bun install
   

3. Run the tests:

   bun run test
   

Building

Build the TypeScript SDK:

bun run build

This will compile TypeScript files to JavaScript and generate type declarations in the dist/ directory.

Development Mode

For development with auto-rebuild:

bun run dev

Requirements

• Node.js 18+
• TypeScript 5.0+ (for TypeScript projects)

License

Apache-2.0