Getting Started with action.do: Your First Atomic Action in TypeScript

In the world of modern software, business processes are becoming increasingly complex. They are often composed of multiple services, APIs, and databases, all orchestrated into what we call a workflow. But what happens when one small part of that workflow fails? The ripple effects can be catastrophic, leading to inconsistent data, failed transactions, and frustrated users.

Enter action.do.

action.do is built on a simple yet powerful concept: the atomic action. This is a single, indivisible operation that is guaranteed to either complete successfully or fail entirely, leaving no messy, partial state behind. It's the fundamental building block for creating truly reliable automation.

This guide will walk you through the core principles of action.do and show you how to execute your very first atomic action using the TypeScript SDK.

What is an Atomic Action (and Why You Need It)?

At its core, an atomic action is a task that you can trust. Think about updating a user's profile and sending them a welcome email. In a traditional setup, if the email service fails after the database is updated, your system is left in an inconsistent state. The user's record is changed, but they never received the notification.

An atomic action wraps this entire operation into a single, transactional unit. It is:

• Reliable: It comes with built-in retry logic and error handling. If a transient network error occurs, action.do can automatically retry the task.
• Atomic: As discussed, it either succeeds completely or fails cleanly. No half-measures.
• Auditable: Every single execution is logged and tracked. You have a full, transparent audit trail to see what happened, when it happened, and what the result was.

This is a significant upgrade from a simple function call, which offers no built-in observability, retries, or audit trails. With action.do, you're not just calling code; you're executing a managed, versioned, and observable task.

Your First Action: Sending a Welcome Email

Let's get our hands dirty. We'll use the provided code example to execute a predefined action called send-welcome-email.

Step 1: Prerequisites & Setup

Before you start, make sure you have Node.js installed. Then, create a new project and install the action.do SDK.

mkdir my-automation-project
cd my-automation-project
npm init -y
npm install @do-platform/sdk

You will also need an API key from your action.do account dashboard.

Step 2: Initialize the Client

Create a new TypeScript file (e.g., index.ts) and start by importing the SDK and initializing the client with your API key.

import { DotDo } from '@do-platform/sdk';

// Replace 'YOUR_API_KEY' with your actual key from the action.do dashboard
const client = new DotDo({ apiKey: 'YOUR_API_KEY' });

Step 3: Execute the Atomic Action

Now, we'll write the function that executes our task. In this example, we assume you have already configured an action named send-welcome-email in your action.do dashboard. This action is set up to accept a userId and a template name.

import { DotDo } from '@do-platform/sdk';

const client = new DotDo({ apiKey: 'YOUR_API_KEY' });

// Execute a predefined action, 'send-welcome-email'
async function sendWelcomeEmail(userId: string) {
  console.log(`Attempting to send welcome email to user: ${userId}`);

  try {
    const result = await client.action('send-welcome-email').execute({
      userId: userId,
      template: 'new-user-template-2024',
    });

    console.log(`Action completed with status: ${result.status}`);
    console.log('Full result:', result);
    return result;
  } catch (error) {
    console.error('Failed to execute action:', error);
  }
}

// Let's run it for a new user
sendWelcomeEmail('user-abc-123');

Let's break down what's happening here:

1. client.action('send-welcome-email'): We select the specific, named action we want to run. This decouples our code from the underlying implementation of the action itself.
2. .execute({ ... }): We call execute and pass a payload containing the parameters the action needs. In this case, it's the userId of the new user and the name of the email template to use.
3. const result = await ...: The execution is an asynchronous process. The result object contains vital information about the execution, including a unique ID, the final status (completed, failed, etc.), and any output from the action.
4. console.log(...): We log the status to confirm that our agentic workflow has successfully completed its task execution.

By running this code, you have just participated in a far more robust business process than a simple function call could ever provide.

Where to Go From Here?

Executing a single action is just the beginning. The real power of action.do emerges when you use it as the foundation for all critical operations.

• Define More Actions: You can define an action for any scriptable task: making an API call, updating a database record, interacting with a smart contract, or running a shell command.
• Build Complex Workflows: While action.do is for a single atomic action, it's designed to be a building block. You can use an orchestration agent (like workflow.do) to chain multiple actions together to create sophisticated, end-to-end automated services.
• Leverage the Audit Trail: Get familiar with the action.do dashboard. Every execution of sendWelcomeEmail is logged, giving you perfect visibility and making debugging a breeze.

By adopting an action-oriented mindset, you shift from writing brittle code to building resilient, observable, and scalable business process automation.

Frequently Asked Questions (FAQs)

Q: What is an 'atomic action'?
A: An atomic action is a single, indivisible operation that either completes successfully or fails entirely, leaving no partial state. This guarantees data integrity and reliability in your workflows.

Q: How is action.do different from a simple function call?
A: action.do provides a layer of abstraction with built-in observability, retries, and audit trails. It treats actions as manageable, versioned services, making your automation more robust and transparent than a standard function.

Q: What kind of actions can I perform with action.do?
A: You can define any action that can be scripted, such as making an API call, sending an email, updating a database record, interacting with a smart contract, or running a shell command.

Q: Can actions be chained together?
A: Yes. action.do is designed as a fundamental building block. You can use an orchestration agent (like workflow.do) to chain multiple atomic actions together to create complex and powerful services.