@io-orkes/conductor-javascript 2.2.1 → 2.4.0

package/README.md

@@ -62,6 +62,22 @@ Show support for the Conductor OSS.  Please help spread the awareness by starrin
     - [Step 1: Create a MetadataClient](#step-1-create-a-metadataclient)
     - [Step 2: Define and Register a Task](#step-2-define-and-register-a-task)
     - [Step 3: Define and Register a Workflow](#step-3-define-and-register-a-workflow)
+- [Events](#events)
+  - [The EventClient](#the-eventclient)
+  - [Quick Start: Using Event Handlers](#quick-start-using-event-handlers)
+    - [Step 1: Create an EventClient](#step-1-create-an-eventclient)
+    - [Step 2: Register an Event Handler](#step-2-register-an-event-handler)
+    - [Step 3: Publish Events](#step-3-publish-events)
+    - [Step 4: Monitor Event Processing](#step-4-monitor-event-processing)
+    - [Step 5: Manage Event Handlers](#step-5-manage-event-handlers)
+- [Applications](#applications)
+  - [The ApplicationClient](#the-applicationclient)
+  - [Quick Start: Managing Applications](#quick-start-managing-applications)
+    - [Step 1: Create an ApplicationClient](#step-1-create-an-applicationclient)
+    - [Step 2: Create an Application](#step-2-create-an-application)
+    - [Step 3: Generate Access Keys](#step-3-generate-access-keys)
+    - [Step 4: Manage Application Roles](#step-4-manage-application-roles)
+    - [Step 5: Manage Applications](#step-5-manage-applications)
 - [Human Tasks](#human-tasks)
   - [The HumanExecutor and TemplateClient](#the-humanexecutor-and-templateclient)
   - [Quick Start: Creating and Managing a Human Task](#quick-start-creating-and-managing-a-human-task)
@@ -716,6 +732,248 @@ await metadataClient.registerWorkflowDef(wf);
 
 For a complete method reference, see the [MetadataClient API Reference](docs/api-reference/metadata-client.md).
 
+## Events
+
+Event handlers in Conductor allow you to automatically trigger actions (like starting workflows) when events are received. This enables event-driven workflows and integrations with external systems.
+
+### The EventClient
+
+The `EventClient` manages event handlers and event processing. For a complete method reference, see the [EventClient API Reference](docs/api-reference/event-client.md).
+
+### Quick Start: Using Event Handlers
+
+Here's how to set up event-driven workflows:
+
+#### Step 1: Create an EventClient
+
+First, create an instance of the `EventClient`:
+
+```typescript
+import { EventClient } from "@io-orkes/conductor-javascript";
+
+const eventClient = new EventClient(client);
+```
+
+#### Step 2: Register an Event Handler
+
+Create an event handler that defines what action to take when an event is received. In this example, we'll start a workflow when an order is created:
+
+```typescript
+await eventClient.addEventHandler({
+  name: "order_created_handler",
+  event: "order.created",
+  active: true,
+  description: "Starts fulfillment workflow when order is created",
+  actions: [
+    {
+      action: "start_workflow",
+      start_workflow: {
+        name: "fulfill_order",
+        version: 1,
+        input: {
+          orderId: "${event.orderId}",
+          customerId: "${event.customerId}",
+        },
+      },
+    },
+  ],
+});
+```
+
+#### Step 3: Publish Events
+
+When an event occurs, publish it to Conductor. All active handlers registered for that event will be triggered:
+
+```typescript
+await eventClient.handleIncomingEvent({
+  event: "order.created",
+  orderId: "ORDER-123",
+  customerId: "CUST-456",
+  amount: "99.99",
+  timestamp: Date.now().toString(),
+});
+```
+
+#### Step 4: Monitor Event Processing
+
+You can monitor event handlers and their execution history:
+
+```typescript
+// Get all handlers for a specific event
+const handlers = await eventClient.getEventHandlersForEvent("order.created");
+
+// Get execution history for a handler
+const executions = await eventClient.getEventExecutions("order_created_handler");
+
+// Get event messages
+const messages = await eventClient.getEventMessages("order.created");
+```
+
+#### Step 5: Manage Event Handlers
+
+Update, deactivate, or remove event handlers as needed:
+
+```typescript
+// Update a handler
+await eventClient.updateEventHandler({
+  name: "order_created_handler",
+  active: false, // Deactivate
+  // ... other fields
+});
+
+// Remove a handler
+await eventClient.removeEventHandler("order_created_handler");
+```
+
+**Event Handler Actions:**
+
+Event handlers support various actions:
+- `start_workflow` - Start a workflow execution
+- `complete_task` - Complete a specific task
+- `fail_task` - Fail a specific task
+- `terminate_workflow` - Terminate a workflow
+- `update_workflow_variables` - Update workflow variables
+
+For a complete method reference, see the [EventClient API Reference](docs/api-reference/event-client.md).
+
+## Applications
+
+Applications in Conductor are security entities that enable programmatic access to the Conductor API. Each application can have multiple access keys for authentication and can be assigned roles to control what operations it can perform.
+
+### The ApplicationClient
+
+The `ApplicationClient` manages applications, access keys, and roles. For a complete method reference, see the [ApplicationClient API Reference](docs/api-reference/application-client.md).
+
+### Quick Start: Managing Applications
+
+Here's how to create and manage applications in Conductor:
+
+#### Step 1: Create an ApplicationClient
+
+First, create an instance of the `ApplicationClient`:
+
+```typescript
+import { ApplicationClient, ApplicationRole } from "@io-orkes/conductor-javascript";
+
+const appClient = new ApplicationClient(client);
+```
+
+#### Step 2: Create an Application
+
+Create a new application to represent your service or integration:
+
+```typescript
+// Create a new application
+const app = await appClient.createApplication("payment-service");
+console.log(`Created application: ${app.id}`);
+```
+
+#### Step 3: Generate Access Keys
+
+Create access keys for the application to authenticate API requests:
+
+```typescript
+// Create an access key
+const accessKey = await appClient.createAccessKey(app.id);
+console.log(`Key ID: ${accessKey.id}`);
+console.log(`Key Secret: ${accessKey.secret}`); // Save this immediately!
+
+// The secret is only shown once - store it securely
+// Use these credentials to create authenticated clients
+const authenticatedClient = await orkesConductorClient({
+  serverUrl: "https://play.orkes.io/api",
+  keyId: accessKey.id,
+  keySecret: accessKey.secret
+});
+```
+
+#### Step 4: Manage Application Roles
+
+Grant the application permissions by adding roles:
+
+```typescript
+import { ApplicationRole } from "@io-orkes/conductor-javascript";
+
+// Add roles to the application
+await appClient.addApplicationRole(app.id, "WORKFLOW_MANAGER");
+await appClient.addApplicationRole(app.id, "WORKER");
+
+console.log("Application can now execute workflows and run workers");
+```
+
+**Available Roles:**
+
+The SDK provides an `ApplicationRole` type with the following options:
+
+- `ADMIN` - Full administrative access to all resources
+- `WORKFLOW_MANAGER` - Start and manage workflow executions
+- `WORKER` - Poll for and execute assigned tasks
+- `UNRESTRICTED_WORKER` - Can execute any task without restrictions
+- `METADATA_MANAGER` - Manage workflow and task definitions
+- `APPLICATION_MANAGER` - Manage applications and access keys
+- `APPLICATION_CREATOR` - Can create new applications
+- `USER` - Standard user access
+- `USER_READ_ONLY` - Read-only access to resources
+- `METADATA_API` - API access to metadata operations
+- `PROMPT_MANAGER` - Can manage AI prompts and templates
+
+#### Step 5: Manage Applications
+
+Manage the lifecycle of your applications:
+
+```typescript
+// List all applications
+const applications = await appClient.getAllApplications();
+console.log(`Total applications: ${applications.length}`);
+
+// Get a specific application
+const myApp = await appClient.getApplication(app.id);
+console.log(`Application name: ${myApp.name}`);
+
+// Update application name
+await appClient.updateApplication(app.id, "payment-service-v2");
+
+// Get all access keys for an application
+const keys = await appClient.getAccessKeys(app.id);
+console.log(`Application has ${keys.length} access keys`);
+
+// Toggle access key status (ACTIVE/INACTIVE)
+await appClient.toggleAccessKeyStatus(app.id, accessKey.id);
+
+// Remove a role from the application
+await appClient.removeRoleFromApplicationUser(app.id, "WORKER");
+
+// Delete an access key
+await appClient.deleteAccessKey(app.id, accessKey.id);
+
+// Delete the application
+await appClient.deleteApplication(app.id);
+```
+
+**Tagging Applications:**
+
+Organize applications with tags for better management:
+
+```typescript
+// Add tags to an application
+await appClient.addApplicationTags(app.id, [
+  { key: "environment", value: "production" },
+  { key: "team", value: "payments" },
+  { key: "cost-center", value: "engineering" }
+]);
+
+// Get application tags
+const tags = await appClient.getApplicationTags(app.id);
+
+// Delete specific tags
+await appClient.deleteApplicationTag(app.id, {
+  key: "cost-center",
+  value: "engineering"
+});
+```
+
+For a complete method reference, see the [ApplicationClient API Reference](docs/api-reference/application-client.md).
+
 ## Human Tasks
 
 Human tasks integrate human interaction into your automated workflows. They pause a workflow until a person provides input, such as an approval, a correction, or additional information.