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

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

@@ -1,441 +0,0 @@
----
-description: How to create HTTP endpoints in Motia
-globs: steps/**/*.step.ts,steps/**/*.step.js,steps/**/*_step.py
-alwaysApply: false
----
-# API Steps Guide
-
-API Steps expose HTTP endpoints that can trigger workflows and emit events.
-
-## Creating API 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 API Step is done by two elements. Configuration and Handler.
-
-### Schema Definition
-
-- **TypeScript/JavaScript**: Motia uses Zod schemas for automatic validation of request/response 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 `ApiRouteConfig` type.
-
-**Python**: You need to define a `config` dictionary with the same properties as the TypeScript `ApiRouteConfig`.
-
-```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 interface QueryParam {
-  /**
-   * The name of the query parameter
-   */
-  name: string
-  /**
-   * The description of the query parameter
-   */
-  description: string
-}
-
-export interface ApiRouteConfig {
-  /**
-   * Should always be api
-   */
-  type: 'api'
-
-  /**
-   * A unique name for this API step, used internally and for linking handlers.
-   */
-  name: string
-
-  /**
-   * Optional human-readable description.
-   */
-  description?: string
-
-  /**
-   * The URL path for this API endpoint (e.g., '/users/:id').
-   */
-  path: string
-
-  /**
-   * The HTTP method for this route.
-   * POST, GET, PUT, DELETE, PATCH, OPTIONS, HEAD
-   */
-  method: ApiRouteMethod
-
-  /**
-   * Topics this API step can emit events to.
-   * Important note: All emits in the handler need to be listed here.
-   */
-  emits: Emit[]
-
-  /**
-   * Optional: Topics that are virtually emitted, perhaps for documentation or lineage, 
-   * but not strictly required for execution.
-   * 
-   * In Motia Workbench, they will show up as gray connections to other steps.
-   */
-  virtualEmits?: Emit[]
-
-  /**
-   * Optional: Virtually subscribed topics.
-   * 
-   * Used by API steps when we want to chain different HTTP requests
-   * that could happen sequentially
-   */
-  virtualSubscribes?: string[]
-  /**
-   * Flows are used to group multiple steps to be visible in diagrams in Workbench
-   */
-  flows?: string[]
-
-  /**
-   * List of middlewares that will be executed BEFORE the handler is called
-   */
-  middleware?: ApiMiddleware<any, any, any>[]
-
-  /**
-   * Schema for the request body. Accepts either:
-   * - Zod schema (ZodObject or ZodArray)
-   * - JSON Schema object
-   * 
-   * Note: This is not validated automatically, you need to validate it in the handler.
-   */
-  bodySchema?: StepSchemaInput
-
-  /**
-   * Schema for response bodies. Accepts either:
-   * - Zod schema (ZodObject or ZodArray)
-   * - JSON Schema object
-   * 
-   * The key (number) is the HTTP status code this endpoint can return and
-   * for each HTTP Status Code, you need to define a schema that defines the response body
-   */
-  responseSchema?: Record<number, StepSchemaInput>
-
-  /**
-   * Mostly for documentation purposes, it will show up in Endpoints section in Workbench
-   */
-  queryParams?: QueryParam[]
-
-  /**
-   * Files to include in the step bundle.
-   * Needs to be relative to the step file.
-   */
-  includeFiles?: string[]
-}
-```
-
-### Handler
-
-The handler is a function that is exported via `export const handler` that is a `ApiRouteHandler` type.
-
-#### Type Definition from Motia
-
-```typescript
-export interface ApiRequest<TBody = unknown> {
-  /**
-   * Key-value pairs of path parameters (e.g., from '/users/:id').
-   */
-  pathParams: Record<string, string>
-  /**
-   * Key-value pairs of query string parameters. Values can be string or array of strings.
-   */
-  queryParams: Record<string, string | string[]>
-  /**
-   * The parsed request body (typically an object if JSON, but can vary).
-   */
-  body: TBody
-  /**
-   * Key-value pairs of request headers. Values can be string or array of strings.
-   */
-  headers: Record<string, string | string[]>
-}
-
-export type ApiResponse<
-  TStatus extends number = number, 
-  TBody = string | Buffer | Record<string, unknown>
-> = {
-  status: TStatus
-  headers?: Record<string, string>
-  body: TBody
-}
-
-export type ApiRouteHandler<
-  /** 
-   * The type defined by config['bodySchema']
-   */
-  TRequestBody = unknown,
-  /**
-   * The type defined by config['responseSchema']
-   */
-  TResponseBody extends ApiResponse<number, unknown> = ApiResponse<number, unknown>,
-  /**
-   * The type defined by config['emits'] which is dynamic depending 
-   * on the topic handlers (Event Steps)
-   */
-  TEmitData = never,
-> = (req: ApiRequest<TRequestBody>, ctx: FlowContext<TEmitData>) => Promise<TResponseBody>
-```
-
-### Handler definition
-
-**TypeScript/JavaScript:**
-```typescript
-export const handler: Handlers['CreateResource'] = async (req, { emit, logger, state, streams }) => {
-  // Implementation
-}
-```
-
-**Python:**
-```python
-async def handler(req, context):
-    # req: dictionary containing pathParams, queryParams, body, headers
-    # context: object containing emit, logger, state, streams, trace_id
-    pass
-```
-
-### Examples
-
-#### TypeScript Example
-
-```typescript
-import { ApiRouteConfig, Handlers } from 'motia';
-import { z } from 'zod';
-
-const bodySchema = z.object({
-  title: z.string().min(1, "Title cannot be empty"),
-  description: z.string().optional(),
-  category: z.string().min(1, "Category is required"),
-  metadata: z.record(z.string(), z.any()).optional()
-})
-
-export const config: ApiRouteConfig = {
-  name: 'CreateResource',
-  type: 'api',
-  path: '/resources',
-  method: 'POST',
-  emits: ['send-email'],
-  flows: ['resource-management'],
-  bodySchema,
-  responseSchema: {
-    201: z.object({
-      id: z.string(),
-      title: z.string(),
-      category: z.string()
-    }),
-    400: z.object({ error: z.string() })
-  }
-};
-
-export const handler: Handlers['CreateResource'] = async (req, { emit, logger }) => {
-  try {
-    const { title, description, category, metadata } = bodySchema.parse(req.body);
-    
-    // Use the logger for structured logging. It's good practice to log key events or data.
-    logger.info('Attempting to create resource', { title, category });
-    
-    /**
-     * Create files to manage service calls.
-     * 
-     * Let's try to use Domain Driven Design to create files to manage service calls.
-     * Steps are the entry points, they're the Controllers on the DDD architecture.
-     */
-    const result = await service.createResource(resourceData);
-
-    /**
-     * This is how we emit events to trigger Event Steps.
-     * Only use emits if the task can take a while to complete.
-     * 
-     * Examples of long tasks 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
-     * 
-     * API Calls that are okay to fail gracefully can be done without emits.
-     */
-    await emit({
-      /**
-       * 'topic' must be one of the topics listed in config['emits'].
-       * do not emit to topics that are not defined in Steps
-       */
-      topic: 'send-email',
-      /**
-       * 'data' is the payload of the event message. 
-       * make sure the data used is compliant with the Event Step input schema
-       */
-      data: {
-        /**
-         * The data to send to the Event Step.
-         */
-        resource: result,
-        /**
-         * The user to send the email to.
-         */
-        user
-      }
-    });
-    
-    logger.info('Resource created successfully', { resourceId, title, category });
-
-    // Return a response object for the HTTP request.
-    return {
-      status: 201, // CREATED (specified in config['responseSchema'])
-      /**
-       * 'body' is the JSON response body sent back to the client.
-       */
-      body: { 
-        id: result.id,
-        title: result.title,
-        category: result.category,
-        status: 'active'
-      }
-    };
-  } catch (error) {
-    /**
-     * For one single step project, it is fine to 
-     * handle ZodErrors here, on multiple steps projects,
-     * it is highly recommended to handle them as a middleware
-     * (defined in config['middleware'])
-     */
-    if (error instanceof ZodError) {
-      logger.error('Resource creation failed', { error: error.message });
-      return {
-        status: 400,
-        body: { error: 'Validation failed' }
-      };
-    }
-
-    logger.error('Resource creation failed', { error: error.message });
-    return {
-      status: 500,
-      body: { error: 'Creation failed' }
-    };
-  }
-};
-```
-
-#### Python Example
-
-```python
-from pydantic import BaseModel, Field
-from typing import Optional, Dict, Any
-
-class ResourceData(BaseModel):
-    title: str = Field(..., min_length=1, description="Title cannot be empty")
-    description: Optional[str] = None
-    category: str = Field(..., min_length=1, description="Category is required")
-    metadata: Optional[Dict[str, Any]] = None
-
-class ResourceResponse(BaseModel):
-    id: str
-    title: str
-    category: str
-    status: str
-
-class ErrorResponse(BaseModel):
-    error: str
-
-config = {
-    "name": "CreateResource",
-    "type": "api",
-    "path": "/resources",
-    "method": "POST",
-    "emits": ["send-email"],
-    "flows": ["resource-management"],
-    "bodySchema": ResourceData.model_json_schema(),
-    "responseSchema": {
-        201: ResourceResponse.model_json_schema(),
-        400: ErrorResponse.model_json_schema()
-    }
-}
-
-async def handler(req, context):
-    try:
-        body = req.get("body", {})
-        
-        # Optional: Validate input manually using Pydantic (Motia doesn't do this automatically)
-        resource_data = ResourceData(**body)
-        
-        context.logger.info("Attempting to create resource", {
-            "title": resource_data.title, 
-            "category": resource_data.category
-        })
-        
-        # Process the resource creation
-        result = await service.create_resource({
-            "title": resource_data.title,
-            "description": resource_data.description,
-            "category": resource_data.category,
-            "metadata": resource_data.metadata
-        })
-
-        # Emit event to trigger other steps
-        await context.emit({
-            "topic": "send-email",
-            "data": {
-                "resource": result,
-                "user_id": "example-user"
-            }
-        })
-        
-        context.logger.info("Resource created successfully", {
-            "resource_id": result.get("id"),
-            "title": result.get("title"),
-            "category": result.get("category")
-        })
-
-        return {
-            "status": 201,
-            "body": {
-                "id": result.get("id"),
-                "title": result.get("title"),
-                "category": result.get("category"),
-                "status": "active"
-            }
-        }
-        
-    except ValidationError as e:
-        context.logger.error("Resource creation failed - Pydantic validation error", {"error": str(e)})
-        return {
-            "status": 400,
-            "body": {"error": "Validation failed"}
-        }
-    except Exception as e:
-        context.logger.error("Resource creation failed", {"error": str(e)})
-        return {
-            "status": 500,
-            "body": {"error": "Creation failed"}
-        }
-```

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

@@ -1,171 +0,0 @@
----
-description: Cron Steps are scheduled tasks that run based on cron expressions.
-globs: steps/**/*.step.ts,steps/**/*.step.js,steps/**/*_step.py
-alwaysApply: false
----
-# Cron Steps Guide
-
-Cron Steps enable scheduled task execution using cron expressions.
-
-They're typically used for recurring jobs like nightly reports, data synchronization, etc.
-
-Cron steps can hold logic, but they do NOT have any retry mechanisms in place, if the logic 
-is likely to fail, it's recommended to use CRON Step to emit an event to a topic that will
-ultimately trigger an Event Step that will handle the logic.
-
-## Creating Cron 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 a CRON Step is done by two elements. Configuration and Handler.
-
-### Configuration
-
-**TypeScript/JavaScript**: You need to export a config constant via `export const config` that is a `CronConfig` type.
-
-**Python**: You need to define a `config` dictionary with the same properties as the TypeScript `CronConfig`.
-
-```typescript
-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 CronConfig = {
-  /**
-   * Should always be cron
-   */
-  type: 'cron'
-
-  /**
-   * A unique name for this cron step, used internally and for linking handlers.
-   */
-  name: string
-
-  /**
-   * Optional human-readable description.
-   */
-  description?: string
-
-  /**
-   * The cron expression for scheduling.
-   */
-  cron: string
-
-  /**
-   * Optional: Topics that are virtually emitted, perhaps for documentation or lineage, but not strictly required for execution.
-   */
-  virtualEmits?: Emit[]
-
-  /**
-   * Topics this cron step can emit events to.
-   */
-  emits: Emit[]
-
-  /**
-   * 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[]
-}
-```
-
-### Handler
-
-The handler is a function that is exported via `export const handler` that is a `CronHandler` type.
-
-**TypeScript/JavaScript:**
-```typescript
-/**
- * CRON handler accepts only one argument, the FlowContext.
- * 
- * The FlowContext is based on the Handlers which can vary depending on the config['emits'].
- */
-export const handler: Handlers['CronJobEvery5Minutes'] = async ({ logger, emit, traceId, state, streams }) => {
-  logger.info('CRON Job Every 5 Minutes started')
-}
-```
-
-**Python:**
-```python
-async def handler(context):
-    # context: object containing emit, logger, state, streams, trace_id
-    context.logger.info("CRON Job Every 5 Minutes started")
-```
-
-### Examples of Cron expressions
-
-- `0 0 * * *`: Runs daily at midnight
-- `*/5 * * * *`: Runs every 5 minutes
-- `0 9 * * *`: Runs daily at 9 AM
-- `0 9 * * 1`: Runs every Monday at 9 AM
-- `0 9 * * 1-5`: Runs every Monday to Friday at 9 AM
-
-### Example uses of Cron Steps
-
-- Sending email notifications on a regular basis
-- Cleaning up old records
-- Purging old data
-- Generating reports
-- Sending out scheduled notifications
-- Collecting metrics from third-party services
-- Reconciling data from different sources
-
-## Examples
-
-### TypeScript Example
-
-```typescript
-export const config: CronConfig = {
-  name: 'CronJobEvery5Minutes', // should always be the same as Handlers['__']
-  type: 'cron',
-  cron: '*/5 * * * *',
-  emits: [], // No emits in this example
-  flows: ['example-flow']
-};
-
-export const handler: Handlers['CronJobEvery5Minutes'] = async ({ logger }) => {
-  logger.info('Cron job started')
-}
-```
-
-### Python Example
-
-```python
-config = {
-    "name": "CronJobEvery5Minutes",
-    "type": "cron",
-    "cron": "*/5 * * * *",  # Run every 5 minutes
-    "emits": [],  # No emits in this example
-    "flows": ["example-flow"]
-}
-
-async def handler(context):
-    context.logger.info("Cron job started")
-```