BillFlow AP SDK - Execute AP workflows programmatically
npm install @oppulence/billflowap-ts-sdkThe official TypeScript/JavaScript SDK for Sim, allowing you to execute workflows programmatically from your applications.
``bash`
npm install simstudio-ts-sdkor
yarn add simstudio-ts-sdkor
bun add simstudio-ts-sdk
`typescript
import { SimStudioClient } from 'simstudio-ts-sdk';
// Initialize the client
const client = new SimStudioClient({
apiKey: 'your-api-key-here',
baseUrl: 'https://sim.ai' // optional, defaults to https://sim.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);
}
`
#### Constructor
`typescript`
new SimStudioClient(config: SimStudioConfig)
- config.apiKey (string): Your Sim API keyconfig.baseUrl
- (string, optional): Base URL for the Sim API (defaults to https://sim.ai)
#### Methods
##### executeWorkflow(workflowId, options?)
Execute a workflow with optional input data.
`typescript`
const result = await client.executeWorkflow('workflow-id', {
input: { message: 'Hello, world!' },
timeout: 30000 // 30 seconds
});
Parameters:
- workflowId (string): The ID of the workflow to executeoptions
- (ExecutionOptions, optional):input
- (any): Input data to pass to the workflow. File objects are automatically converted to base64.timeout
- (number): Timeout in milliseconds (default: 30000)
Returns: Promise
##### getWorkflowStatus(workflowId)
Get the status of a workflow (deployment status, etc.).
`typescript`
const status = await client.getWorkflowStatus('workflow-id');
console.log('Is deployed:', status.isDeployed);
Parameters:
- workflowId (string): The ID of the workflow
Returns: Promise
##### validateWorkflow(workflowId)
Validate that a workflow is ready for execution.
`typescript`
const isReady = await client.validateWorkflow('workflow-id');
if (isReady) {
// Workflow is deployed and ready
}
Parameters:
- workflowId (string): The ID of the workflow
Returns: Promise
##### executeWorkflowSync(workflowId, options?)
Execute a workflow and poll for completion (useful for long-running workflows).
`typescript`
const result = await client.executeWorkflowSync('workflow-id', {
input: { data: 'some input' },
timeout: 60000
});
Parameters:
- workflowId (string): The ID of the workflow to executeoptions
- (ExecutionOptions, optional):input
- (any): Input data to pass to the workflowtimeout
- (number): Timeout for the initial request in milliseconds
Returns: Promise
##### setApiKey(apiKey)
Update the API key.
`typescript`
client.setApiKey('new-api-key');
##### setBaseUrl(baseUrl)
Update the base URL.
`typescript`
client.setBaseUrl('https://my-custom-domain.com');
`typescript`
interface WorkflowExecutionResult {
success: boolean;
output?: any;
error?: string;
logs?: any[];
metadata?: {
duration?: number;
executionId?: string;
[key: string]: any;
};
traceSpans?: any[];
totalDuration?: number;
}
`typescript`
interface WorkflowStatus {
isDeployed: boolean;
deployedAt?: string;
needsRedeployment: boolean;
}
`typescript`
class SimStudioError extends Error {
code?: string;
status?: number;
}
`typescript
import { SimStudioClient } from 'simstudio-ts-sdk';
const client = new SimStudioClient({
apiKey: process.env.SIM_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();
`
`typescript
import { SimStudioClient, SimStudioError } from 'simstudio-ts-sdk';
const client = new SimStudioClient({
apiKey: process.env.SIM_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;
}
}
`
`typescript`
// Using environment variables
const client = new SimStudioClient({
apiKey: process.env.SIM_API_KEY!,
baseUrl: process.env.SIM_BASE_URL // optional
});
File objects are automatically detected and converted to base64 format. Include them in your input under the field name matching your workflow's API trigger input format:
The SDK converts File objects to this format:
`typescript`
{
type: 'file',
data: 'data:mime/type;base64,base64data',
name: 'filename',
mime: 'mime/type'
}
Alternatively, you can manually provide files using the URL format:
`typescript`
{
type: 'url',
data: 'https://example.com/file.pdf',
name: 'file.pdf',
mime: 'application/pdf'
}
`typescript
import { SimStudioClient } from 'simstudio-ts-sdk';
import fs from 'fs';
const client = new SimStudioClient({
apiKey: process.env.SIM_API_KEY!
});
// Node.js: Read file and create File object
const fileBuffer = fs.readFileSync('./document.pdf');
const file = new File([fileBuffer], 'document.pdf', { type: 'application/pdf' });
// Include files under the field name from your API trigger's input format
const result = await client.executeWorkflow('workflow-id', {
input: {
documents: [file], // Field name must match your API trigger's file input field
instructions: 'Process this document'
}
});
// Browser: From file input
const handleFileUpload = async (event: Event) => {
const input = event.target as HTMLInputElement;
const files = Array.from(input.files || []);
const result = await client.executeWorkflow('workflow-id', {
input: {
attachments: files, // Field name must match your API trigger's file input field
query: 'Analyze these files'
}
});
};
`
1. Log in to your Sim 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
To run the tests locally:
1. Clone the repository and navigate to the TypeScript SDK directory:
`bash`
cd packages/ts-sdk
2. Install dependencies:
`bash`
bun install
3. Run the tests:
`bash`
bun run test
Build the TypeScript SDK:
`bash`
bun run build
This will compile TypeScript files to JavaScript and generate type declarations in the dist/ directory.
For development with auto-rebuild:
`bash``
bun run dev
- Node.js 18+
- TypeScript 5.0+ (for TypeScript projects)
Apache-2.0