motia 0.7.3-beta.136 → 0.8.1-beta.138

package/dist/cjs/create/templates/generate.js

@@ -40,7 +40,7 @@ const glob_1 = require("glob");
 const generateTemplateSteps = (templateFolder) => {
     return async (rootDir, context) => {
         const templatePath = path.join(__dirname, templateFolder);
-        const files = (0, glob_1.globSync)('**/*', { absolute: false, cwd: templatePath });
+        const files = (0, glob_1.globSync)('**/*', { absolute: false, cwd: templatePath, dot: true });
         try {
             for (const fileName of files) {
                 const filePath = path.join(templatePath, fileName);
@@ -54,7 +54,7 @@ const generateTemplateSteps = (templateFolder) => {
                     (0, fs_1.mkdirSync)(targetDir, { recursive: true });
                 }
                 if ((0, fs_1.statSync)(filePath).isDirectory()) {
-                    const folderPath = path.basename(filePath);
+                    const folderPath = filePath.replace(templatePath, '');
                     (0, fs_1.mkdirSync)(path.join(rootDir, folderPath), { recursive: true });
                     continue;
                 }

package/dist/cjs/create/templates/generate.ts

@@ -8,7 +8,7 @@ export type Generator = (rootDir: string, context: CliContext) => Promise<void>
 export const generateTemplateSteps = (templateFolder: string): Generator => {
   return async (rootDir: string, context: CliContext): Promise<void> => {
     const templatePath = path.join(__dirname, templateFolder)
-    const files = globSync('**/*', { absolute: false, cwd: templatePath })
+    const files = globSync('**/*', { absolute: false, cwd: templatePath, dot: true })
 
     try {
       for (const fileName of files) {
@@ -24,7 +24,7 @@ export const generateTemplateSteps = (templateFolder: string): Generator => {
         }
 
         if (statSync(filePath).isDirectory()) {
-          const folderPath = path.basename(filePath)
+          const folderPath = filePath.replace(templatePath, '')
           mkdirSync(path.join(rootDir, folderPath), { recursive: true })
           continue
         }

package/dist/cjs/create/templates/nodejs/motia-workbench.json

@@ -2,27 +2,27 @@
   {
     "id": "basic-tutorial",
     "config": {
-      "steps/state-audit-cron.step.ts": {
+      "steps/petstore/state-audit-cron.step.ts": {
         "x": -165,
         "y": 217,
         "sourceHandlePosition": "right"
       },
-      "steps/process-food-order.step.ts": {
+      "steps/petstore/process-food-order.step.ts": {
         "x": 211,
         "y": 17,
         "sourceHandlePosition": "bottom",
         "targetHandlePosition": "left"
       },
-      "steps/api.step.ts": {
+      "steps/petstore/api.step.ts": {
         "x": -100,
         "y": 3,
         "sourceHandlePosition": "right",
         "targetHandlePosition": "left"
       },
-      "steps/notification.step.ts": {
+      "steps/petstore/notification.step.ts": {
         "x": 300,
         "y": 264
       }
     }
   }
-]
+]

package/dist/cjs/create/templates/nodejs/src/services/pet-store/create-order.ts.txt

@@ -0,0 +1,15 @@
+import { Order } from './types'
+
+export const createOrder = async (order: Omit<Order, 'id'>): Promise<Order> => {
+  const response = await fetch('https://petstore.swagger.io/v2/store/order', {
+    method: 'POST',
+    body: JSON.stringify({
+      quantity: order?.quantity ?? 1,
+      petId: 1,
+      shipDate: order?.shipDate ?? new Date().toISOString(),
+      status: order?.status ?? 'placed',
+    }),
+    headers: { 'Content-Type': 'application/json' },
+  })
+  return response.json()
+}

package/dist/cjs/create/templates/nodejs/src/services/pet-store/create-pet.ts.txt

@@ -0,0 +1,14 @@
+import { Pet } from './types'
+
+export const createPet = async (pet: Omit<Pet, 'id'>): Promise<Pet> => {
+  const response = await fetch('https://petstore.swagger.io/v2/pet', {
+    method: 'POST',
+    body: JSON.stringify({
+      name: pet?.name ?? '',
+      photoUrls: [pet?.photoUrl ?? ''],
+      status: 'available',
+    }),
+    headers: { 'Content-Type': 'application/json' },
+  })
+  return response.json()
+}

package/dist/cjs/create/templates/nodejs/src/services/pet-store/index.ts.txt

@@ -0,0 +1,9 @@
+import { createPet } from './create-pet'
+import { createOrder } from './create-order'
+
+export * from './types'
+
+export const petStoreService = {
+  createPet,
+  createOrder,
+}

package/dist/{esm/create/templates/nodejs/steps → cjs/create/templates/nodejs/steps/petstore}/api.step.ts-features.json.txt

@@ -4,7 +4,7 @@
     "title": "Step Configuration",
     "description": "All steps should have a defined configuration, this is how you define the step's behavior and how it will be triggered.",
     "lines": [
-      "6-30"
+      "5-29"
     ]
   },
   {
@@ -12,7 +12,7 @@
     "title": "API Step",
     "description": "Definition of an API endpoint",
     "lines": [
-      "12-13"
+      "11-12"
     ]
   },
   {
@@ -20,7 +20,7 @@
     "title": "Request body",
     "description": "Definition of the expected request body. Motia will automatically generate types based on this schema.",
     "lines": [
-      "14-25"
+      "13-24"
     ]
   },
   {
@@ -28,7 +28,7 @@
     "title": "Response Payload",
     "description": "Definition of the expected response payload, Motia will generate the types automatically based on this schema. This is also important to create the Open API spec later.",
     "lines": [
-      "26-28"
+      "25-27"
     ]
   },
   {
@@ -36,8 +36,8 @@
     "title": "Emits",
     "description": "We can define the events that this step will emit, this is how we can trigger other Motia Steps.",
     "lines": [
-      "29",
-      "39-46"
+      "28",
+      "38-45"
     ]
   },
   {
@@ -45,7 +45,7 @@
     "title": "Handler",
     "description": "The handler is the function that will be executed when the step is triggered. This one receives the request body and emits events.",
     "lines": [
-      "32-50"
+      "31-49"
     ]
   },
   {
@@ -53,7 +53,7 @@
     "title": "Logger",
     "description": "The logger is a utility that allows you to log messages to the console. It is available in the handler function. We encourage you to use it instead of console.log. It will automatically be tied to the trace id of the request.",
     "lines": [
-      "33"
+      "32"
     ]
   },
   {
@@ -61,7 +61,7 @@
     "title": "HTTP Response",
     "description": "The handler can return a response to the client. This is how we can return a response to the client. It must comply with the responseSchema defined in the step configuration.",
     "lines": [
-      "49"
+      "48"
     ]
   }
 ]

package/dist/{esm/create/templates/nodejs/steps → cjs/create/templates/nodejs/steps/petstore}/api.step.ts.txt

@@ -1,7 +1,6 @@
 import { ApiRouteConfig, Handlers } from 'motia'
 import { z } from 'zod'
-import { petStoreService } from '../services/pet-store'
-import { petSchema } from '../services/types'
+import { petStoreService, petSchema } from '../../src/services/pet-store'
 
 export const config: ApiRouteConfig = {
   type: 'api',

package/dist/{esm/create/templates/nodejs/steps → cjs/create/templates/nodejs/steps/petstore}/process-food-order.step.ts.txt

@@ -1,6 +1,6 @@
 import { EventConfig, Handlers } from 'motia'
 import { z } from 'zod'
-import { petStoreService } from '../services/pet-store'
+import { petStoreService } from '../../src/services/pet-store'
 
 export const config: EventConfig = {
   type: 'event',

package/dist/cjs/create/templates/nodejs/tutorial.tsx.txt

@@ -371,25 +371,35 @@ export const steps: TutorialStep[] = [
     before: [{ type: 'click', selector: workbenchXPath.closePanelButton }],
   },
   {
-    elementXpath: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial'),
+    elementXpath: workbenchXPath.endpoints.endpointsList,
     title: 'Endpoints Tool',
     description: () => (
       <p>
         This section will display all of the endpoints declared in your API Steps. It will list the HTTP method, the URL
         path, and the description declared in the Step configuration.
-        <br />
-        <br />
-        💡 Clicking on an endpoint from the list will open the endpoint overview which provides documentation on how to
-        use the endpoint and a tool to test the endpoint.
       </p>
     ),
     before: [{ type: 'click', selector: workbenchXPath.links.endpoints }],
   },
   {
-    elementXpath: workbenchXPath.sidebarContainer,
-    title: 'API Endpoint Docs',
+    elementXpath: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial'),
+    title: 'Endpoints Tool',
     description: () => (
       <p>
+        Clicking on an endpoint from the list will open the endpoint overview which provides documentation on how to use
+        the endpoint and a tool to test the endpoint.
+      </p>
+    ),
+  },
+  {
+    elementXpath: workbenchXPath.endpoints.callPanel,
+    title: 'API Endpoint Playground',
+    description: () => (
+      <p>
+        Once you click on an endpoint from the list, you will be able to test it by providing a request payload and
+        clicking on the <b>Play</b> button.
+        <br />
+        <br />
         This section will provide an overview of your API endpoint.
         <br />
         <br />
@@ -399,6 +409,25 @@ export const steps: TutorialStep[] = [
     ),
     before: [{ type: 'click', selector: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial') }],
   },
+  {
+    elementXpath: workbenchXPath.endpoints.specButton,
+    title: 'API Endpoint Specification',
+    description: () => (
+      <p>
+        Clicking on this button will open the specification of your API endpoint. Like response and request schemas.
+      </p>
+    ),
+  },
+  {
+    elementXpath: workbenchXPath.sidebarContainer,
+    title: 'API Endpoint Specification',
+    description: () => (
+      <p>
+        This is what you see when clicking on the <b>Details</b> button.
+      </p>
+    ),
+    before: [{ type: 'click', selector: workbenchXPath.endpoints.specButton }],
+  },
   {
     elementXpath: workbenchXPath.endpoints.callPanel,
     title: 'API Endpoint Test',
@@ -428,7 +457,10 @@ export const steps: TutorialStep[] = [
         </pre>
       </p>
     ),
-    before: [{ type: 'click', selector: workbenchXPath.endpoints.callTab }],
+    before: [
+      { type: 'click', selector: workbenchXPath.closePanelButton },
+      { type: 'click', selector: workbenchXPath.endpoints.bodyTab },
+    ],
   },
   {
     elementXpath: workbenchXPath.endpoints.playButton,

package/dist/cjs/create/templates/python/motia-workbench.json

@@ -2,22 +2,22 @@
   {
     "id": "basic-tutorial",
     "config": {
-      "steps/state_audit_cron_step.py": {
+      "steps/petstore/state_audit_cron_step.py": {
         "x": -38,
         "y": 683,
         "sourceHandlePosition": "right"
       },
-      "steps/process_food_order_step.py": {
+      "steps/petstore/process_food_order_step.py": {
         "x": 384,
         "y": 476,
         "targetHandlePosition": "left"
       },
-      "steps/notification_step.py": {
+      "steps/petstore/notification_step.py": {
         "x": 601,
         "y": 724,
         "targetHandlePosition": "left"
       },
-      "steps/api_step.py": {
+      "steps/petstore/api_step.py": {
         "x": 15,
         "y": 461,
         "sourceHandlePosition": "right"

package/dist/cjs/create/templates/python/steps/{api_step.py.txt → petstore/api_step.py.txt}

@@ -1,7 +1,7 @@
 from pydantic import BaseModel
 from typing import Optional
-from .services.pet_store import pet_store_service
-from .services.types import Pet
+from src.services.pet_store import pet_store_service
+from src.services.types import Pet
 
 class PetRequest(BaseModel):
     name: str

package/dist/cjs/create/templates/python/steps/{process_food_order_step.py.txt → petstore/process_food_order_step.py.txt}

@@ -1,6 +1,6 @@
 from pydantic import BaseModel
 from datetime import datetime
-from .services.pet_store import pet_store_service
+from src.services.pet_store import pet_store_service
 
 class InputSchema(BaseModel):
     id: str

package/dist/cjs/create/templates/python/tutorial.tsx.txt

@@ -360,7 +360,7 @@ export const steps: TutorialStep[] = [
     title: 'Endpoints',
     description: () => (
       <p>
-        Now that we've looked at Motia's Step types, let's trigger the API Step from the <b>endpoints</b> section in
+        Now that we've looked at Motia primitives, let's trigger the API Step from the <b>endpoints</b> section in
         Workbench.
         <br />
         <br />
@@ -371,25 +371,35 @@ export const steps: TutorialStep[] = [
     before: [{ type: 'click', selector: workbenchXPath.closePanelButton }],
   },
   {
-    elementXpath: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial'),
+    elementXpath: workbenchXPath.endpoints.endpointsList,
     title: 'Endpoints Tool',
     description: () => (
       <p>
         This section will display all of the endpoints declared in your API Steps. It will list the HTTP method, the URL
         path, and the description declared in the Step configuration.
-        <br />
-        <br />
-        💡 Clicking on an endpoint from the list will open the endpoint overview which provides documentation on how to
-        use the endpoint and a tool to test the endpoint.
       </p>
     ),
     before: [{ type: 'click', selector: workbenchXPath.links.endpoints }],
   },
   {
-    elementXpath: workbenchXPath.sidebarContainer,
-    title: 'API Endpoint Docs',
+    elementXpath: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial'),
+    title: 'Endpoints Tool',
     description: () => (
       <p>
+        Clicking on an endpoint from the list will open the endpoint overview which provides documentation on how to use
+        the endpoint and a tool to test the endpoint.
+      </p>
+    ),
+  },
+  {
+    elementXpath: workbenchXPath.endpoints.callPanel,
+    title: 'API Endpoint Playground',
+    description: () => (
+      <p>
+        Once you click on an endpoint from the list, you will be able to test it by providing a request payload and
+        clicking on the <b>Play</b> button.
+        <br />
+        <br />
         This section will provide an overview of your API endpoint.
         <br />
         <br />
@@ -399,6 +409,25 @@ export const steps: TutorialStep[] = [
     ),
     before: [{ type: 'click', selector: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial') }],
   },
+  {
+    elementXpath: workbenchXPath.endpoints.specButton,
+    title: 'API Endpoint Specification',
+    description: () => (
+      <p>
+        Clicking on this button will open the specification of your API endpoint. Like response and request schemas.
+      </p>
+    ),
+  },
+  {
+    elementXpath: workbenchXPath.sidebarContainer,
+    title: 'API Endpoint Specification',
+    description: () => (
+      <p>
+        This is what you see when clicking on the <b>Details</b> button.
+      </p>
+    ),
+    before: [{ type: 'click', selector: workbenchXPath.endpoints.specButton }],
+  },
   {
     elementXpath: workbenchXPath.endpoints.callPanel,
     title: 'API Endpoint Test',
@@ -428,7 +457,10 @@ export const steps: TutorialStep[] = [
         </pre>
       </p>
     ),
-    before: [{ type: 'click', selector: workbenchXPath.endpoints.callTab }],
+    before: [
+      { type: 'click', selector: workbenchXPath.closePanelButton },
+      { type: 'click', selector: workbenchXPath.endpoints.bodyTab },
+    ],
   },
   {
     elementXpath: workbenchXPath.endpoints.playButton,

package/dist/cjs/cursor-rules/dot-files/.cursor/architecture/architecture.mdc

@@ -0,0 +1,96 @@
+---
+description: How to structure your Motia project
+globs:
+alwaysApply: true
+---
+
+# Architecture Guide
+
+## Overview
+
+This guide covers the architecture of a Motia project.
+
+## File Structure
+
+All step files should be underneath the `steps/` folder.
+
+Underneath the `steps/` folder, create subfolders for Flows. Flows are used to group steps together.
+
+## Step Naming Conventions
+
+### Typescript
+
+- Use kebab-case for filenames: `resource-processing.step.ts`
+- Include `.step` before language extension
+
+### Python
+
+- Use snake_case for filenames: `data_processor_step.py`
+- Include `_step` before language extension
+
+### Global
+
+- Match handler names to config names
+- Use descriptive, action-oriented names
+
+## Code Style Guidelines
+
+- **JavaScript**: Use modern ES6+ features, async/await, proper error handling
+- **TypeScript**: Make sure you use the correct Handlers type that is auto generated on the `types.d.ts` file.
+
+## Defining Middlewares
+
+Middleware is a powerful feature in Motia to help adding common validation, error
+handling and other common logic to your steps.
+
+- Make sure to add all the middlewares in a single folder, called `middlewares/`.
+- Create a comprehensive file name for the middleware, like `auth.middleware.ts`.
+- Follow SOLID principles with separation of concerns in middlewares, create a middleware for each responsibility.
+- Use core middleware to handle ZodError gracefully (see [Error Handling Guide](./error-handling.mdc))
+- Rate limiting and CORS are not needed to be handled in middleware since they're an infrastructure concern.
+
+## Domain Driven Design
+
+Make sure you follow Domain Driven Design principles in your project.
+
+- Create `/src/services` folder to store your services, this is where it holds business logic.
+- Create `/src/repositories` folder to store your repositories, this is where it holds data access logic.
+- Create `/src/utils` folder to store your utility functions.
+- Models and DTOs are not quite necessary, we can rely on zod to create the models and DTOs from the steps.
+- Controller layer is the Steps, it should have mostly logic around validation and calling services.
+- Avoid having Service methods with just a call to the Repository, it should have some logic around it, if it doesn't have, then Steps can have access to repositories directly.
+
+### Services
+
+Defining services can be done in the following way:
+
+- Create a folder underneath `/src/services/` folder, like `/src/services/auth/`.
+- Create a file inside the folder called `index.ts`.
+- Inside `index.ts`, export a constant with the name of the service, with the methods as properties.
+- Methods should be defined as separate files, use export named functions.
+- Use the service in the Steps.
+
+#### Example
+
+```typescript
+/**
+ * Business logic for authentication defined in a separate file in the same folder.
+ */
+import { login } from './login'
+
+/**
+ * Constant with the name of the service, with the methods as properties.
+ */
+export const authService = {
+  login
+}
+```
+
+## Logging and observability
+
+- Make sure to use the Logger from Motia (from context object) to log messages.
+- Make sure to have visibility of what is going on in a request
+- Before throwing errors, make sure to log the issue, identify if issue is a validation blocker, then log with `logger.warn`, if it's something that is not supposed to happen, then log with `logger.error`.
+- Make sure to add context to the logs to help identify any potential issues.
+
+

package/dist/cjs/cursor-rules/dot-files/.cursor/architecture/error-handling.mdc

@@ -0,0 +1,122 @@
+---
+description: How to handle errors in a Motia project
+globs:
+alwaysApply: true
+---
+
+# Error Handling Guide
+
+Errors happen, but we need to handle them gracefully. Make sure you create a custom error class for your project, underneath `/src/errors/` folder.
+
+## Good practices
+
+- Use Custom error to return errors to the client.
+- Anything that is not the error class, should be logged with `logger.error`. And root cause should be omitted to the client.
+
+## Create a custom Error class
+
+Name: `/src/errors/base.error.ts`
+
+```typescript
+export class BaseError extends Error {
+  public readonly status: number
+  public readonly code: string
+  public readonly metadata: Record<string, any>
+
+  constructor(
+    message: string,
+    status: number = 500,
+    code: string = 'INTERNAL_SERVER_ERROR',
+    metadata: Record<string, any> = {}
+  ) {
+    super(message)
+    this.name = this.constructor.name
+    this.status = status
+    this.code = code
+    this.metadata = metadata
+
+    // Maintains proper stack trace for where our error was thrown
+    Error.captureStackTrace(this, this.constructor)
+  }
+
+  toJSON() {
+    return {
+      error: {
+        name: this.name,
+        message: this.message,
+        code: this.code,
+        status: this.status,
+        ...(Object.keys(this.metadata).length > 0 && { metadata: this.metadata }),
+      },
+    }
+  }
+}
+```
+
+Then create sub class for specific errors that are commonly thrown in your project.
+
+Name: `/src/errors/not-found.error.ts`
+
+```typescript
+import { BaseError } from './base.error'
+
+export class NotFoundError extends BaseError {
+  constructor(message: string = 'Not Found', metadata: Record<string, any> = {}) {
+    super(message, 404, 'NOT_FOUND', metadata)
+  }
+}
+```
+
+## Core Middleware
+
+Make sure you create a core middleware that will be added to ALL API Steps.
+
+File: `/src/middlewares/core.middleware.ts`
+
+```typescript
+import { ApiMiddleware } from 'motia'
+import { ZodError } from 'zod'
+import { BaseError } from '../errors/base.error'
+
+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,
+        },
+      }
+    } else if (error instanceof BaseError) {
+      logger.error('BaseError', {
+        status: error.status,
+        code: error.code,
+        metadata: error.metadata,
+        name: error.name,
+        message: error.message,
+      })
+
+      return { status: error.status, body: error.toJSON() }
+    }
+
+    logger.error('Error while performing request', {
+      error,
+      body: req.body,
+      stack: error.stack,
+    })
+
+    return { status: 500, body: { error: 'Internal Server Error' } }
+  }
+}
+```

package/dist/cjs/cursor-rules/dot-files/.cursor/index.mdc

@@ -0,0 +1,34 @@
+---
+description: Rules for the project
+globs:
+alwaysApply: true
+---
+
+## Real time events
+
+Make sure to use [real time events guide](./rules/motia/realtime-streaming.mdc) to create a new real time event.
+
+## State/Cache management
+
+Make sure to use [state management guide](./rules/motia/state-management.mdc) to create a new state management.
+
+## Creating HTTP Endpoints
+
+Make sure to use [API steps guide](./rules/motia/api-steps.mdc) to create new HTTP endpoints.
+
+## Background Tasks
+
+Make sure to use [event steps guide](./rules/motia/event-steps.mdc) to create new background tasks.
+
+## Scheduled Tasks
+
+Make sure to use [cron steps guide](./rules/motia/cron-steps.mdc) to create new scheduled tasks.
+
+## Virtual Steps & Flow Visualization
+
+Make sure to use [virtual steps guide](./rules/motia/virtual-steps.mdc) when connecting nodes virtually and creating smooth flows in Workbench.
+
+## Authentication
+
+If ever need to add authentication, make sure to use middleware to authenticate the request.
+Make sure to use [middlewares](./rules/motia/middlewares.mdc) to validate the requests.