motia 0.14.0-beta.165-285707 → 0.15.0-beta.165

package/dist/esm/cursor-rules/dot-files/.cursor/rules/motia/event-steps.mdc

@@ -1,234 +0,0 @@
----
-description: How to create background tasks in Motia
-globs: steps/**/*.step.ts,steps/**/*.step.js,steps/**/*_step.py
-alwaysApply: false
----
-# Event Steps Guide
-
-Event Steps are used to handle asynchronous events. These steps cannot be
-invoked by a client or user. In order to ultimately trigger an Event Step,
-you need to connect it to an API Step or a CRON Step.
-
-Examples of event steps are:
-- LLM Calls
-- Processing big files, like images, videos, audio, etc.
-- Sending emails
-
-Other applicable examples are tasks that are likely to fail, examples:
-- Webhook call to external systems
-
-## Creating Event Steps
-
-Steps need to be created in the `steps` folder, it can be in subfolders.
-
-- Steps in TS and JS should end with `.step.ts` and `.step.js` respectively.
-- Steps in Python should end with `_step.py`.
-
-## Definition
-
-Defining an Event Step is done by two elements. Configuration and Handler.
-
-### Schema Definition
-
-- **TypeScript/JavaScript**: Motia uses Zod schemas for automatic validation of input data
-- **Python**: Motia uses JSON Schema format. You can optionally use Pydantic models to generate JSON Schemas and handle manual validation in your handlers
-
-### Configuration
-
-**TypeScript/JavaScript**: You need to export a config constant via `export const config` that is a `EventConfig` type.
-
-**Python**: You need to define a `config` dictionary with the same properties as the TypeScript `EventConfig`.
-
-```typescript
-export type ZodInput = ZodObject<any> | ZodArray<any>
-export type StepSchemaInput = ZodInput | JsonSchema
-
-export type Emit = string | { 
-  /**
-   * The topic name to emit to.
-   */
-  topic: string;
-
-  /**
-   * Optional label for the emission, could be used for documentation or UI.
-   */
-  label?: string;
-
-  /**
-   * This is purely for documentation purposes, 
-   * it doesn't affect the execution of the step.
-   * 
-   * In Workbench, it will render differently based on this value.
-   */
-  conditional?: boolean;
-}
-
-export type EventConfig = {
-  /**
-   * Should always be event
-   */
-  type: 'event'
-
-  /**
-   * A unique name for this event step, used internally and for linking handlers.
-   */
-  name: string
-
-  /**
-   * Optional human-readable description.
-   */
-  description?: string
-
-  /**
-   * An array of topic names this step listens to.
-   */
-  subscribes: string[]
-
-  /**
-   * An array of topics this step can emit events to.
-   */
-  emits: Emit[]
-
-  /**
-   * Optional: Topics that are virtually emitted, perhaps for documentation or lineage, but not strictly required for execution.
-   */
-  virtualEmits?: Emit[]
-
-  /**
-   * Optional: Virtually subscribed topics for documentation/lineage purposes.
-   */
-  virtualSubscribes?: string[]
-
-  /**
-   * Schema for input data. Accepts either:
-   * - Zod schema (ZodObject or ZodArray)
-   * - JSON Schema object
-   * 
-   * This is used by Motia to create the correct types for whoever emits the event 
-   * to this step.
-   * 
-   * Avoid adding too much data to the input schema, only add the data that 
-   * is necessary for the Event Step to process. If the data is too big it's 
-   * recommended to store it in the state and fetch it from the state on the 
-   * Event Step handler.
-   */
-  input?: StepSchemaInput
-
-  /**
-   * Optional: An array of flow names this step belongs to.
-   */
-  flows?: string[]
-
-  /**
-   * Files to include in the step bundle.
-   * Needs to be relative to the step file.
-   */
-  includeFiles?: string[]
-
-  /**
-   * Optional: Infrastructure configuration for handler and queue settings.
-   */
-  infrastructure?: Partial<InfrastructureConfig>
-}
-```
-
-### Handler
-
-The handler is a function that is exported via `export const handler` that is a `EventHandler` type.
-
-### Handler definition
-
-**TypeScript/JavaScript:**
-```typescript
-/**
- * Input is inferred from the Event Step config['input']
- * Context is the FlowContext
- */
-export const handler: Handlers['SendEmail'] = async (input, { emit, logger, state, streams }) => {
-  // Implementation
-}
-```
-
-**Python:**
-```python
-async def handler(input_data, context):
-    # input_data: dictionary with the event data (matches the input schema)
-    # context: object containing emit, logger, state, streams, trace_id
-    pass
-```
-
-### Examples
-
-#### TypeScript Example
-
-```typescript
-import { EventConfig, Handlers } from 'motia';
-import { z } from 'zod';
-
-const inputSchema = z.object({
-  email: z.string(),
-  templateId: z.string(),
-  templateData: z.record(z.string(), z.any()),
-})
-
-export const config: EventConfig = {
-  name: 'SendEmail',
-  type: 'event',
-  description: 'Sends email notification to the user',
-  subscribes: ['send-email'],
-  emits: [],
-  input: inputSchema,
-  flows: ['resource-management']
-};
-
-export const handler: Handlers['SendEmail'] = async (input, { emit, logger }) => {
-  const { email, templateId, templateData } = input;
-  
-  // Process email sending logic here
-  await emailService.send({
-    to: email,
-    templateId,
-    data: templateData
-  });
-  
-  logger.info('Email sent successfully', { email, templateId });
-};
-```
-
-#### Python Example
-
-```python
-from pydantic import BaseModel
-from typing import Dict, Any
-
-class EmailData(BaseModel):
-    email: str
-    template_id: str
-    template_data: Dict[str, Any]
-
-config = {
-    "name": "SendEmail",
-    "type": "event",
-    "description": "Sends email notification to the user",
-    "subscribes": ["send-email"],
-    "emits": [],
-    "input": EmailData.model_json_schema(),
-    "flows": ["resource-management"]
-}
-
-async def handler(input_data, context):
-    # Optional: Validate input manually using Pydantic (Motia doesn't do this automatically)
-    email_data = EmailData(**input_data)
-    
-    # Process email sending logic here
-    await email_service.send({
-        "to": email_data.email,
-        "template_id": email_data.template_id,
-        "data": email_data.template_data
-    })
-    
-    context.logger.info("Email sent successfully", {
-        "email": email_data.email,
-        "template_id": email_data.template_id
-    })
-```

package/dist/esm/cursor-rules/dot-files/.cursor/rules/motia/middlewares.mdc

@@ -1,217 +0,0 @@
----
-description: Middlewares are used to execute code before and after the handler is called
-globs: steps/**/*.step.ts,steps/**/*.step.js,steps/**/*_step.py,middlewares/**/*.middleware.ts,middlewares/**/*.middleware.js,middlewares/**/*_middleware.py
-alwaysApply: false
----
-# Middlewares Guide
-
-Middlewares are used to execute code before and after the handler is called in API Steps.
-
-The middleware is a handler that receives three arguments:
-- **Request**: this is the same request object received by API Step handlers, if modified by the middleware, it will be the same object passed to the handler and any subsequent middleware. Be careful to not cause any side effects to the request object.
-- **Context**: this is the same context object received by API Step handlers, if modified by the middleware, it will be the same object passed to the handler and any subsequent middleware. Be careful to not cause any side effects to the context object.
-- **Next**: this is a function that you need to call to invoke the next middleware in the stack. If you don't call it, the request will be halted—the handler and any subsequent middlewares will not be called.
-
-## Next function
-
-Next function is a way to either continue the execution flow or stop it. For example, in authentication middlewares, if the user is not authenticated, you can return a 401 response and not call `next()`.
-
-It can also be used to enrich data returned back to the HTTP response. Like adding a header parameter or so after calling `next()`.
-
-## Adding middlewares to a step
-
-### TypeScript/JavaScript Example
-
-```typescript
-import { ApiRouteConfig } from 'motia'
-import { coreMiddleware } from '../middlewares/core.middleware'
-
-export const config: ApiRouteConfig = {
-  type: 'api',
-  name: 'SampleRoute',
-  description: 'Sample route',
-  path: '/sample',
-  method: 'GET',
-  emits: [],
-  flows: [],
-  middleware: [coreMiddleware],
-}
-```
-
-### Python Example
-
-```python
-async def enrich_data_middleware(req, context, next_fn):
-    context.logger.info("enriching data")
-    req["enriched"] = "yes"
-    return await next_fn()
-
-config = {
-    "type": "api",
-    "name": "SampleRoute",
-    "description": "Sample route",
-    "path": "/sample",
-    "method": "GET",
-    "emits": [],
-    "flows": [],
-    "middleware": [enrich_data_middleware],
-}
-```
-
-## Middleware examples
-
-### Handling errors
-
-#### TypeScript/JavaScript
-
-```typescript
-import { ApiMiddleware } from 'motia'
-
-export const coreMiddleware: ApiMiddleware = async (req, ctx, next) => {
-  const { logger } = ctx
-
-  try {
-    /** 
-     * Calling next() will invoke the next item in the stack.
-     * 
-     * It will depend on the order of middlewares configured in the step,
-     * first one in the list is called first and so on.
-     */
-    return await next()
-  } catch (error: any) {
-    logger.error('Error while performing request', {
-      error,
-      body: req.body, // make sure you don't include sensitive data in the logs
-      stack: error.stack,
-    })
-
-    return {
-      status: 500,
-      body: { error: 'Internal Server Error' },
-    }
-  }
-}
-```
-
-#### Python
-
-```python
-async def error_handling_middleware(req, context, next_fn):
-    try:
-        # Calling next_fn() will invoke the next item in the stack.
-        # It will depend on the order of middlewares configured in the step,
-        # first one in the list is called first and so on.
-        return await next_fn()
-    except Exception as error:
-        context.logger.error('Error while performing request', {
-            'error': str(error),
-            'body': req.get('body'),  # make sure you don't include sensitive data in the logs
-        })
-        
-        return {
-            'status': 500,
-            'body': {'error': 'Internal Server Error'},
-        }
-```
-
-### Enriching response
-
-#### TypeScript/JavaScript
-
-```typescript
-export const enrichResponseMiddleware: ApiMiddleware = async (req, ctx, next) => {
-  const response = await next()
-
-  response.headers['X-Custom-Header'] = 'Custom Value'
-  
-  return response
-}
-```
-
-#### Python
-
-```python
-async def enrich_response_middleware(req, context, next_fn):
-    response = await next_fn()
-    
-    if not response.get('headers'):
-        response['headers'] = {}
-    
-    response['headers']['X-Custom-Header'] = 'Custom Value'
-    
-    return response
-```
-
-### Handling validation errors
-
-#### TypeScript/JavaScript - Handling Zod Validation errors
-
-```typescript
-import { ApiMiddleware } from 'motia'
-import { ZodError } from 'zod'
-
-export const coreMiddleware: ApiMiddleware = async (req, ctx, next) => {
-  const logger = ctx.logger
-
-  try {
-    return await next()
-  } catch (error: any) {
-    if (error instanceof ZodError) {
-      logger.error('Validation error', {
-        error,
-        stack: error.stack,
-        errors: error.errors,
-      })
-
-      return {
-        status: 400,
-        body: {
-          error: 'Invalid request body',
-          data: error.errors,
-        },
-      }
-    }
-
-    logger.error('Error while performing request', {
-      error,
-      body: req.body, // make sure you don't include sensitive data in the logs
-      stack: error.stack,
-    })
-
-    return { status: 500, body: { error: 'Internal Server Error' } }
-  }
-}
-```
-
-#### Python - Handling Pydantic Validation errors
-
-```python
-from pydantic import ValidationError
-
-async def validation_middleware(req, context, next_fn):
-    try:
-        return await next_fn()
-    except ValidationError as error:
-        context.logger.error('Validation error', {
-            'error': str(error),
-            'errors': error.errors(),
-        })
-        
-        return {
-            'status': 400,
-            'body': {
-                'error': 'Invalid request body',
-                'data': error.errors(),
-            },
-        }
-    except Exception as error:
-        context.logger.error('Error while performing request', {
-            'error': str(error),
-            'body': req.get('body'),  # make sure you don't include sensitive data in the logs
-        })
-        
-        return {
-            'status': 500,
-            'body': {'error': 'Internal Server Error'}
-        }
-```