Contd SDK for TypeScript/Node.js

Resumable workflows with exactly-once execution semantics.

Installation

npm install @contd/sdk

Quick Start

import { ContdClient, workflow, step, WorkflowConfig, StepConfig, RetryPolicy } from '@contd/sdk';

// Remote client usage
const client = new ContdClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.contd.ai'
});

// Start a workflow
const workflowId = await client.startWorkflow({
  workflowName: 'process-order',
  input: { orderId: '12345' }
});

// Check status
const status = await client.getStatus(workflowId);
console.log(status.status); // 'running', 'completed', etc.

// Resume interrupted workflow
await client.resume(workflowId);

// Time travel to savepoint
const newWorkflowId = await client.timeTravel(workflowId, 'savepoint-id');

Defining Workflows

import { workflow, step, ExecutionContext } from '@contd/sdk';

// Define a step with retry policy
@step({
  retry: {
    maxAttempts: 3,
    backoffBase: 2,
    backoffMax: 60,
    backoffJitter: 0.5
  },
  timeout: 30000
})
async function chargePayment(orderId: string): Promise<{ paymentId: string }> {
  const result = await paymentGateway.charge(orderId);
  return { paymentId: result.id };
}

// Define a workflow
@workflow({ tags: { team: 'platform' } })
async function processOrder(orderId: string) {
  await validateOrder(orderId);
  await chargePayment(orderId);
  await shipOrder(orderId);
}

Testing

import { ContdTestCase, WorkflowTestBuilder } from '@contd/sdk';

// Using test case
const testCase = new ContdTestCase();
testCase.setUp();

await testCase.runWorkflow(processOrder, {
  args: ['order-123'],
  interruptAtStep: 2
});
testCase.assertInterrupted(2);

await testCase.resumeWorkflow();
testCase.assertCompleted();

testCase.tearDown();

// Using fluent builder
await new WorkflowTestBuilder(processOrder)
  .withInput('order-123')
  .interruptAt(2)
  .run()
  .assertInterrupted()
  .resume()
  .assertCompleted();

Error Handling

import {
  ContdError,
  WorkflowLocked,
  StepTimeout,
  TooManyAttempts
} from '@contd/sdk';

try {
  await client.startWorkflow({ ... });
} catch (error) {
  if (error instanceof WorkflowLocked) {
    console.log('Workflow is locked by:', error.details.currentOwner);
  } else if (error instanceof StepTimeout) {
    console.log('Step timed out:', error.stepName);
  }
}

Features

• Resumable workflows with exactly-once execution
• Automatic retry with exponential backoff
• Step-level timeouts
• Rich savepoints with epistemic metadata
• Idempotent step execution
• Comprehensive error hierarchy
• Testing utilities with mock engine