@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/reference/workflows/events.mdx

@@ -0,0 +1,305 @@
+---
+title: "Event-Driven Workflows | Mastra Docs"
+description: "Learn how to create event-driven workflows using afterEvent and resumeWithEvent methods in Mastra."
+---
+
+# Event-Driven Workflows
+
+Mastra provides built-in support for event-driven workflows through the `afterEvent` and `resumeWithEvent` methods. These methods allow you to create workflows that pause execution while waiting for specific events to occur, then resume with the event data when it's available.
+
+## Overview
+
+Event-driven workflows are useful for scenarios where:
+
+- You need to wait for external systems to complete processing
+- User approval or input is required at specific points
+- Asynchronous operations need to be coordinated
+- Long-running processes need to break up execution across different services
+
+## Defining Events
+
+Before using event-driven methods, you must define the events your workflow will listen for in the workflow configuration:
+
+```typescript
+import { Workflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+const workflow = new Workflow({
+  name: 'approval-workflow',
+  triggerSchema: z.object({ requestId: z.string() }),
+  events: {
+    // Define events with their validation schemas
+    approvalReceived: {
+      schema: z.object({
+        approved: z.boolean(),
+        approverName: z.string(),
+        comment: z.string().optional(),
+      }),
+    },
+    documentUploaded: {
+      schema: z.object({
+        documentId: z.string(),
+        documentType: z.enum(['invoice', 'receipt', 'contract']),
+        metadata: z.record(z.string()).optional(),
+      }),
+    },
+  },
+});
+```
+
+Each event must have a name and a schema that defines the structure of data expected when the event occurs.
+
+## afterEvent()
+
+The `afterEvent` method creates a suspension point in your workflow that automatically waits for a specific event.
+
+### Syntax
+
+```typescript
+workflow.afterEvent(eventName: string): Workflow
+```
+
+### Parameters
+
+- `eventName`: The name of the event to wait for (must be defined in the workflow's `events` configuration)
+
+### Return Value
+
+Returns the workflow instance for method chaining.
+
+### How It Works
+
+When `afterEvent` is called, Mastra:
+
+1. Creates a special step with ID `__eventName_event`
+2. Configures this step to automatically suspend workflow execution
+3. Sets up the continuation point after the event is received
+
+### Usage Example
+
+```typescript
+workflow
+  .step(initialProcessStep)
+  .afterEvent('approvalReceived')  // Workflow suspends here
+  .step(postApprovalStep)          // This runs after event is received
+  .then(finalStep)
+  .commit();
+```
+
+## resumeWithEvent()
+
+The `resumeWithEvent` method resumes a suspended workflow by providing data for a specific event.
+
+### Syntax
+
+```typescript
+run.resumeWithEvent(eventName: string, data: any): Promise<WorkflowRunResult>
+```
+
+### Parameters
+
+- `eventName`: The name of the event being triggered
+- `data`: The event data (must conform to the schema defined for this event)
+
+### Return Value
+
+Returns a Promise that resolves to the workflow execution results after resumption.
+
+### How It Works
+
+When `resumeWithEvent` is called, Mastra:
+
+1. Validates the event data against the schema defined for that event
+2. Loads the workflow snapshot
+3. Updates the context with the event data
+4. Resumes execution from the event step
+5. Continues workflow execution with the subsequent steps
+
+### Usage Example
+
+```typescript
+// Create a workflow run
+const run = workflow.createRun();
+
+// Start the workflow
+await run.start({ triggerData: { requestId: 'req-123' } });
+
+// Later, when the event occurs:
+const result = await run.resumeWithEvent('approvalReceived', {
+  approved: true,
+  approverName: 'John Doe',
+  comment: 'Looks good to me!'
+});
+
+console.log(result.results);
+```
+
+## Accessing Event Data
+
+When a workflow is resumed with event data, that data is available in the step context as `context.inputData.resumedEvent`:
+
+```typescript
+const processApprovalStep = new Step({
+  id: 'processApproval',
+  execute: async ({ context }) => {
+    // Access the event data
+    const eventData = context.inputData.resumedEvent;
+
+    return {
+      processingResult: `Processed approval from ${eventData.approverName}`,
+      wasApproved: eventData.approved,
+    };
+  },
+});
+```
+
+## Multiple Events
+
+You can create workflows that wait for multiple different events at various points:
+
+```typescript
+workflow
+  .step(createRequest)
+  .afterEvent('approvalReceived')
+  .step(processApproval)
+  .afterEvent('documentUploaded')
+  .step(processDocument)
+  .commit();
+```
+
+When resuming a workflow with multiple event suspension points, you need to provide the correct event name and data for the current suspension point.
+
+## Practical Example
+
+This example shows a complete workflow that requires both approval and document upload:
+
+```typescript
+import { Workflow, Step } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+// Define steps
+const createRequest = new Step({
+  id: 'createRequest',
+  execute: async () => ({ requestId: `req-${Date.now()}` }),
+});
+
+const processApproval = new Step({
+  id: 'processApproval',
+  execute: async ({ context }) => {
+    const approvalData = context.inputData.resumedEvent;
+    return {
+      approved: approvalData.approved,
+      approver: approvalData.approverName,
+    };
+  },
+});
+
+const processDocument = new Step({
+  id: 'processDocument',
+  execute: async ({ context }) => {
+    const documentData = context.inputData.resumedEvent;
+    return {
+      documentId: documentData.documentId,
+      processed: true,
+      type: documentData.documentType,
+    };
+  },
+});
+
+const finalizeRequest = new Step({
+  id: 'finalizeRequest',
+  execute: async ({ context }) => {
+    const requestId = context.steps.createRequest.output.requestId;
+    const approved = context.steps.processApproval.output.approved;
+    const documentId = context.steps.processDocument.output.documentId;
+
+    return {
+      finalized: true,
+      summary: `Request ${requestId} was ${approved ? 'approved' : 'rejected'} with document ${documentId}`
+    };
+  },
+});
+
+// Create workflow
+const requestWorkflow = new Workflow({
+  name: 'document-request-workflow',
+  events: {
+    approvalReceived: {
+      schema: z.object({
+        approved: z.boolean(),
+        approverName: z.string(),
+      }),
+    },
+    documentUploaded: {
+      schema: z.object({
+        documentId: z.string(),
+        documentType: z.enum(['invoice', 'receipt', 'contract']),
+      }),
+    },
+  },
+});
+
+// Build workflow
+requestWorkflow
+  .step(createRequest)
+  .afterEvent('approvalReceived')
+  .step(processApproval)
+  .afterEvent('documentUploaded')
+  .step(processDocument)
+  .then(finalizeRequest)
+  .commit();
+
+// Export workflow
+export { requestWorkflow };
+```
+
+### Running the Example Workflow
+
+```typescript
+import { requestWorkflow } from './workflows';
+import { mastra } from './mastra';
+
+async function runWorkflow() {
+  // Get the workflow
+  const workflow = mastra.getWorkflow('document-request-workflow');
+  const run = workflow.createRun();
+
+  // Start the workflow
+  const initialResult = await run.start();
+  console.log('Workflow started:', initialResult.results);
+
+  // Simulate receiving approval
+  const afterApprovalResult = await run.resumeWithEvent('approvalReceived', {
+    approved: true,
+    approverName: 'Jane Smith',
+  });
+  console.log('After approval:', afterApprovalResult.results);
+
+  // Simulate document upload
+  const finalResult = await run.resumeWithEvent('documentUploaded', {
+    documentId: 'doc-456',
+    documentType: 'invoice',
+  });
+  console.log('Final result:', finalResult.results);
+}
+
+runWorkflow().catch(console.error);
+```
+
+## Best Practices
+
+1. **Define Clear Event Schemas**: Use Zod to create precise schemas for event data validation
+2. **Use Descriptive Event Names**: Choose event names that clearly communicate their purpose
+3. **Handle Missing Events**: Ensure your workflow can handle cases where events don't occur or time out
+4. **Include Monitoring**: Use the `watch` method to monitor suspended workflows waiting for events
+5. **Consider Timeouts**: Implement timeout mechanisms for events that may never occur
+6. **Document Events**: Clearly document the events your workflow depends on for other developers
+
+## Related
+
+- [Suspend and Resume in Workflows](../../workflows/suspend-and-resume.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+- [Resume Method Reference](./resume.mdx)
+- [Watch Method Reference](./watch.mdx)
+- [After Event Reference](./afterEvent.mdx)
+- [Resume With Event Reference](./resumeWithEvent.mdx)

package/.docs/raw/reference/workflows/execute.mdx

@@ -0,0 +1,110 @@
+---
+title: "Reference: Workflow.execute() | Workflows | Mastra Docs" 
+description: "Documentation for the `.execute()` method in Mastra workflows, which runs workflow steps and returns results."
+---
+
+# Workflow.execute()
+
+Executes a workflow with the provided trigger data and returns the results. The workflow must be committed before execution.
+
+## Usage Example
+
+```typescript
+const workflow = new Workflow({
+  name: "my-workflow",
+  triggerSchema: z.object({
+    inputValue: z.number()
+  })
+});
+
+workflow.step(stepOne).then(stepTwo).commit();
+
+const result = await workflow.execute({
+  triggerData: { inputValue: 42 }
+});
+```
+
+## Parameters 
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "ExecuteOptions",
+      description: "Options for workflow execution",
+      isOptional: true,
+      properties: [
+        {
+          name: "triggerData",
+          type: "TriggerSchema",
+          description: "Input data matching the workflow's trigger schema",
+          isOptional: false
+        },
+        {
+          name: "runId", 
+          type: "string",
+          description: "Optional ID to track this execution run",
+          isOptional: true
+        }
+      ]
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "WorkflowResult",
+      type: "object",
+      description: "Results from workflow execution",
+      properties: [
+        {
+          name: "runId",
+          type: "string", 
+          description: "Unique identifier for this execution run"
+        },
+        {
+          name: "results",
+          type: "Record<string, StepResult>",
+          description: "Results from each completed step"
+        },
+        {
+          name: "status",
+          type: "WorkflowStatus",
+          description: "Final status of the workflow run"
+        }
+      ]
+    }
+  ]}
+/>
+
+## Additional Examples
+
+Execute with run ID:
+
+```typescript
+const result = await workflow.execute({
+  runId: "custom-run-id",
+  triggerData: { inputValue: 42 }
+});
+```
+
+Handle execution results:
+
+```typescript
+const { runId, results, status } = await workflow.execute({
+  triggerData: { inputValue: 42 }
+});
+
+if (status === "COMPLETED") {
+  console.log("Step results:", results);
+}
+```
+
+### Related
+
+- [Workflow.createRun()](./createRun.mdx)
+- [Workflow.commit()](./commit.mdx)
+- [Workflow.start()](./start.mdx)

package/.docs/raw/reference/workflows/if.mdx

@@ -0,0 +1,107 @@
+---
+title: "Reference: Workflow.if() | Conditional Branching | Mastra Docs"
+description: "Documentation for the `.if()` method in Mastra workflows, which creates conditional branches based on specified conditions."
+---
+
+# Workflow.if()
+
+> Experimental
+
+The `.if()` method creates a conditional branch in the workflow, allowing steps to execute only when a specified condition is true. This enables dynamic workflow paths based on the results of previous steps.
+
+## Usage
+
+```typescript copy showLineNumbers
+workflow
+  .step(startStep)
+  .if(async ({ context }) => {
+    const value = context.getStepResult<{ value: number }>('start')?.value;
+    return value < 10; // If true, execute the "if" branch
+  })
+  .then(ifBranchStep)
+  .else()
+  .then(elseBranchStep)
+  .commit();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "condition",
+      type: "Function | ReferenceCondition",
+      description: "A function or reference condition that determines whether to execute the 'if' branch",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Condition Types
+
+### Function Condition
+
+You can use a function that returns a boolean:
+
+```typescript
+workflow
+  .step(startStep)
+  .if(async ({ context }) => {
+    const result = context.getStepResult<{ status: string }>('start');
+    return result?.status === 'success'; // Execute "if" branch when status is "success"
+  })
+  .then(successStep)
+  .else()
+  .then(failureStep);
+```
+
+### Reference Condition
+
+You can use a reference-based condition with comparison operators:
+
+```typescript
+workflow
+  .step(startStep)
+  .if({
+    ref: { step: startStep, path: 'value' },
+    query: { $lt: 10 }, // Execute "if" branch when value is less than 10
+  })
+  .then(ifBranchStep)
+  .else()
+  .then(elseBranchStep);
+```
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining"
+    }
+  ]}
+/>
+
+## Error Handling
+
+The `if` method requires a previous step to be defined. If you try to use it without a preceding step, an error will be thrown:
+
+```typescript
+try {
+  // This will throw an error
+  workflow
+    .if(async ({ context }) => true)
+    .then(someStep)
+    .commit();
+} catch (error) {
+  console.error(error); // "Condition requires a step to be executed after"
+}
+```
+
+## Related
+
+- [else Reference](./else.mdx)
+- [then Reference](./then.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+- [Step Condition Reference](./step-condition.mdx)

package/.docs/raw/reference/workflows/resume.mdx

@@ -0,0 +1,155 @@
+---
+title: "Reference: run.resume() | Running Workflows | Mastra Docs"
+description: Documentation for the `.resume()` method in workflows, which continues execution of a suspended workflow step.
+---
+
+# run.resume()
+
+The `.resume()` method continues execution of a suspended workflow step, optionally providing new context data that can be accessed by the step on the inputData property.
+
+## Usage
+
+```typescript copy showLineNumbers
+await run.resume({
+  runId: "abc-123",
+  stepId: "stepTwo",
+  context: {
+    secondValue: 100
+  }
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "config",
+      type: "object",
+      description: "Configuration for resuming the workflow",
+      isOptional: false
+    }
+  ]}
+/>
+
+### config
+
+<PropertiesTable
+  content={[
+    {
+      name: "runId",
+      type: "string",
+      description: "Unique identifier of the workflow run to resume",
+      isOptional: false
+    },
+    {
+      name: "stepId",
+      type: "string",
+      description: "ID of the suspended step to resume",
+      isOptional: false
+    },
+    {
+      name: "context",
+      type: "Record<string, any>",
+      description: "New context data to inject into the step's inputData property",
+      isOptional: true
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "Promise<WorkflowResult>",
+      type: "object",
+      description: "Result of the resumed workflow execution"
+    }
+  ]}
+/>
+
+## Async/Await Flow
+
+When a workflow is resumed, execution continues from the point immediately after the `suspend()` call in the step's execution function. This creates a natural flow in your code:
+
+```typescript
+// Step definition with suspend point
+const reviewStep = new Step({
+  id: "review",
+  execute: async ({ context, suspend }) => {
+    // First part of execution
+    const initialAnalysis = analyzeData(context.inputData.data);
+
+    if (initialAnalysis.needsReview) {
+      // Suspend execution here
+      await suspend({ analysis: initialAnalysis });
+
+      // This code runs after resume() is called
+      // context.inputData now contains any data provided during resume
+      return {
+        reviewedData: enhanceWithFeedback(initialAnalysis, context.inputData.feedback)
+      };
+    }
+
+    return { reviewedData: initialAnalysis };
+  }
+});
+
+const { runId, resume, start } = workflow.createRun();
+
+await start({
+  inputData: {
+    data: "some data"
+  }
+});
+
+// Later, resume the workflow
+const result = await resume({
+  runId: "workflow-123",
+  stepId: "review",
+  context: {
+    // This data will be available in `context.inputData`
+    feedback: "Looks good, but improve section 3"
+  }
+});
+```
+
+### Execution Flow
+
+1. The workflow runs until it hits `await suspend()` in the `review` step
+2. The workflow state is persisted and execution pauses
+3. Later, `run.resume()` is called with new context data
+4. Execution continues from the point after `suspend()` in the `review` step
+5. The new context data (`feedback`) is available to the step on the `inputData` property
+6. The step completes and returns its result
+7. The workflow continues with subsequent steps
+
+## Error Handling
+
+The resume function may throw several types of errors:
+
+```typescript
+try {
+  await run.resume({
+    runId,
+    stepId: "stepTwo",
+    context: newData
+  });
+} catch (error) {
+  if (error.message === "No snapshot found for workflow run") {
+    // Handle missing workflow state
+  }
+  if (error.message === "Failed to parse workflow snapshot") {
+    // Handle corrupted workflow state
+  }
+}
+```
+
+## Related
+
+- [Suspend and Resume](../../workflows/suspend-and-resume.mdx)
+- [`suspend` Reference](./suspend.mdx)
+- [`watch` Reference](./watch.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+```