npm package: @solidactions/sdk
Description: SolidActions SDK - Durable workflow execution framework
Latest version: 0.4.1

# SolidActions SDK

[![npm version](https://img.shields.io/npm/v/@solidactions/sdk.svg)](https://www.npmjs.com/package/@solidactions/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Lightweight durable workflows for TypeScript.

## What is SolidActions?

SolidActions provides lightweight durable workflows built on top of an HTTP API backend.
Instead of managing your own workflow orchestrator or task queue system, you can use SolidActions to add durable workflows and queues to your program in just a few lines of code.

This SDK uses HTTP API calls to communicate with a SolidActions backend server (such as Laravel) that implements the workflow persistence API.

## Features

- **💾 Durable Workflows** - Checkpoint workflow state to automatically resume from failures
- **📒 Durable Queues** - Run tasks in the background with guaranteed completion
- **📅 Durable Scheduling** - Schedule workflows with cron syntax or durable sleep
- **📫 Durable Notifications** - Pause workflows until signals/notifications arrive
- **⚙️ Workflow Management** - Query, cancel, resume, or restart workflows programmatically

## Installation

```bash
npm install @solidactions/sdk
```

## Quick Start

```typescript
import { SolidActions } from '@solidactions/sdk';

// Register workflow steps
async function stepOne() {
  SolidActions.logger.info('Step one completed!');
}

async function stepTwo() {
  SolidActions.logger.info('Step two completed!');
}

// Register the workflow
async function workflowFunction() {
  await SolidActions.runStep(stepOne);
  await SolidActions.runStep(stepTwo);
}
const workflow = SolidActions.registerWorkflow(workflowFunction);
```

## Configuration

Configure via environment variables:

```bash
SOLIDACTIONS_API_URL=https://your-backend.com/api
SOLIDACTIONS_API_KEY=your-api-key
```

Or in code:

```typescript
import { SolidActions } from '@solidactions/sdk';

SolidActions.setConfig({
  name: 'my-app',
  api: {
    url: process.env.SOLIDACTIONS_API_URL!,
    key: process.env.SOLIDACTIONS_API_KEY!,
  },
});

await SolidActions.launch();
```

Or use a config file (`solidactions-config.yaml`):

```yaml
name: my-app
api:
  url: https://your-api-backend.com
  key: ${SOLIDACTIONS_API_KEY}
```

## Durable Workflows

Workflows checkpoint their state so they can resume from the last completed step after any failure:

```typescript
async function paymentWorkflow(orderId: string) {
  // Step 1: Reserve inventory
  await SolidActions.runStep(() => reserveInventory(orderId));

  // Step 2: Process payment (if this fails, we resume from step 2)
  await SolidActions.runStep(() => processPayment(orderId));

  // Step 3: Ship order
  await SolidActions.runStep(() => shipOrder(orderId));
}
const workflow = SolidActions.registerWorkflow(paymentWorkflow);
```

## Durable Queues

Run tasks in the background with guaranteed completion:

```typescript
import { SolidActions, WorkflowQueue } from '@solidactions/sdk';

const queue = new WorkflowQueue('background_tasks');

async function processTask(task: Task) {
  // Process the task...
}
const taskWorkflow = SolidActions.registerWorkflow(processTask);

// Enqueue work
await SolidActions.startWorkflow(taskWorkflow, { queueName: queue.name })(task);
```

## Durable Sleep

Sleep for any duration (even days) - workflows resume exactly when the sleep ends:

```typescript
async function reminderWorkflow(email: string) {
  await SolidActions.runStep(() => sendConfirmationEmail(email));
  await SolidActions.sleep(86400000); // Sleep 24 hours
  await SolidActions.runStep(() => sendReminderEmail(email));
}
```

## Signals and Events

Wait for external signals or emit events:

```typescript
async function approvalWorkflow(requestId: string) {
  // Wait for approval signal (with timeout)
  const approved = await SolidActions.recv<boolean>('approval', 3600);

  if (approved) {
    await SolidActions.runStep(() => processApproval(requestId));
  }
}
```

## Client API

Use the client to manage workflows programmatically:

```typescript
import { SolidActionsClient } from '@solidactions/sdk';

const client = SolidActionsClient.create();

// List workflows
const workflows = await client.listWorkflows({
  status: 'ERROR',
  startTime: '2025-04-22T03:00:00Z',
});

// Cancel or resume workflows
await client.cancelWorkflow(workflowId);
await client.resumeWorkflow(workflowId);
```

## Deploying Workflows

Use the [`@solidactions/cli`](https://www.npmjs.com/package/@solidactions/cli) to deploy your workflows:

```bash
npm install -g @solidactions/cli

# Authenticate
solidactions init <api-key>

# Deploy your project
solidactions deploy <project-name> <path>
```

The CLI handles project creation, source upload, Docker builds, environment variables, and scheduling. See the [CLI repo](https://github.com/SolidActions/solidactions-cli) for full documentation.

## Documentation

See [`docs/sdk-reference.md`](docs/sdk-reference.md) for comprehensive SDK documentation including:

- Lifecycle: `SolidActions.run()`, `setConfig()`/`launch()`/`shutdown()`, `getInput()`
- Workflows: registration, determinism rules, IDs and idempotency, timeouts, child workflows
- Steps: `runStep()`, configurable retries, parallel execution with `Promise.allSettled()`
- Durable primitives: `sleep()`, `now()`, `randomUUID()`
- Communication: `send()`/`recv()` messaging, `setEvent()`/`getEvent()` events, streaming, `respond()`
- Workflow handles and management: `listWorkflows()`, `cancelWorkflow()`, `forkWorkflow()`
- SolidActionsClient: standalone HTTP client for external workflow queries
- Configuration, custom serialization, testing, and error classes
- Recovery and versioning