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

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

@@ -1,401 +0,0 @@
----
-description: Real-time streaming
-globs: steps/**/*.step.ts,steps/**/*.step.js,steps/**/*_step.py,steps/**/*.stream.ts,steps/**/*.stream.js,steps/**/*_stream.py
-alwaysApply: false
----
-# Real-time Streaming
-
-Building event driven applications often requires some real-time streaming capabilities. 
-- Like integration with LLMs, they should be implemented in an asynchronous way and updates should come in real-time.
-- Chat applications, real-time collaboration, etc.
-- Long living processes like data processing, video processing, etc.
-
-Motia has a built-in real-time streaming system that allows you to easily implement real-time streaming capabilities in your application.
-
-It's called Streams.
-
-## Stream Configuration
-
-Creating a Stream means defining a data schema that will be stored and served to the clients who are subscribing.
-
-### StreamConfig Type Definition
-
-```typescript
-export type ZodInput = ZodObject<any> | ZodArray<any>
-export type StepSchemaInput = ZodInput | JsonSchema
-
-export type StreamSubscription = { groupId: string; id?: string }
-
-export interface StreamConfig {
-  /**
-   * The stream name, used on the client side to subscribe.
-   */
-  name: string
-
-  /**
-   * Schema for stream data. Accepts either:
-   * - Zod schema (ZodObject or ZodArray)
-   * - JSON Schema object
-   */
-  schema: StepSchemaInput
-
-  /**
-   * Storage configuration for the stream.
-   * Use 'default' for built-in storage or 'custom' with a factory function.
-   */
-  baseConfig: { storageType: 'default' } | { storageType: 'custom'; factory: () => MotiaStream<any> }
-
-  /**
-   * Optional: Access control callback to authorize subscriptions.
-   * Return true to allow access, false to deny.
-   */
-  canAccess?: (subscription: StreamSubscription, authContext: any) => boolean | Promise<boolean>
-}
-```
-
-### TypeScript Example
-
-```typescript
-// steps/streams/chat-messages.stream.ts
-import { StreamConfig } from 'motia'
-import { z } from 'zod'
-
-export const chatMessageSchema = z.object({
-  id: z.string(),
-  userId: z.string(),
-  message: z.string(),
-  timestamp: z.string()
-})
-
-export type ChatMessage = z.infer<typeof chatMessageSchema>
-
-export const config: StreamConfig = {
-  name: 'chatMessage',
-  schema: chatMessageSchema,
-  baseConfig: { storageType: 'default' },
-}
-```
-
-### Python Examples
-
-#### With Pydantic (Optional)
-
-```python
-# steps/streams/chat_messages_stream.py
-from pydantic import BaseModel
-
-class ChatMessage(BaseModel):
-    id: str
-    user_id: str
-    message: str
-    timestamp: str
-
-config = {
-    "name": "chatMessage",
-    "schema": ChatMessage.model_json_schema(),
-    "baseConfig": {"storageType": "default"}
-}
-```
-
-#### Without Pydantic (Pure JSON Schema)
-
-```python
-# steps/streams/chat_messages_stream.py
-
-config = {
-    "name": "chatMessage",
-    "schema": {
-        "type": "object",
-        "properties": {
-            "id": {"type": "string"},
-            "user_id": {"type": "string"},
-            "message": {"type": "string"},
-            "timestamp": {"type": "string"}
-        },
-        "required": ["id", "user_id", "message", "timestamp"]
-    },
-    "baseConfig": {"storageType": "default"}
-}
-```
-
-## Using streams
-
-Streams managers are automatically injected into the context of the steps.
-
-The interface of each stream is this
-
-```typescript
-export type BaseStreamItem<TData = unknown> = TData & { id: string }
-
-interface MotiaStream<TData> {
-  /**
-   * Retrieves a single item from the stream
-   * 
-   * @param groupId - The group id of the stream
-   * @param id - The id of the item to get
-   * @returns The item or null if it doesn't exist
-   */
-  get(groupId: string, id: string): Promise<BaseStreamItem<TData> | null>
-
-  /**
-   * Create or update a single item in the stream.
-   * 
-   * If the item doesn't exist, it will be created.
-   * If the item exists, it will be updated.
-   * 
-   * @param groupId - The group id of the stream
-   * @param id - The id of the item to set
-   * @param data - The data to set
-   * @returns The item
-   */
-  set(groupId: string, id: string, data: TData): Promise<BaseStreamItem<TData>>
-
-  /**
-   * Deletes a single item from the stream
-   * 
-   * @param groupId - The group id of the stream
-   * @param id - The id of the item to delete
-   * @returns The item or null if it doesn't exist
-   */
-  delete(groupId: string, id: string): Promise<BaseStreamItem<TData> | null>
-
-  /**
-   * Retrieves a group of items from the stream based on the group id
-   * 
-   * @param groupId - The group id of the stream
-   * @returns The items
-   */
-  getGroup(groupId: string): Promise<BaseStreamItem<TData>[]>
-
-  /**
-   * This is used mostly for ephemeral events in streams.
-   * A chat message for example has a state, which is the message content, user id, etc.
-   * 
-   * However, if you want to send an event to the subscribers like:
-   * - online status
-   * - reactions
-   * - typing indicators
-   * - etc.
-   * 
-   * @param channel - The channel to send the event to
-   * @param event - The event to send
-   */
-  send<T>(channel: StateStreamEventChannel, event: StateStreamEvent<T>): Promise<void>
-}
-```
-
-## Sending ephemeral events
-
-Streams hold state, which means when the client connects and subscribes to a GroupID and ItemID,
-they will automatically sync with the state of the stream, however, there might be cases where
-you want to send an ephemeral event to the subscribers, like:
-
-- online status
-- reactions
-- typing indicators
-- etc.
-
-This is where the `send` method comes in.
-
-```typescript
-/**
- * The channel to send the event to
- */
-type StateStreamEventChannel = {
-  /**
-   * The group id of the stream
-   */
-  groupId: string
-
-  /**
-   * The id of the item to send the event to
-   * 
-   * Optional, when not provided, the event will be sent to the entire group.
-   * Subscribers to the group will receive the event.
-   */
-  id?: string
-}
-
-export type StateStreamEvent<TData> = {
-  /**
-   * The type of the event, use as the name of the event
-   * to be handled in the subscribers.
-   */
-  type: string
-
-  /**
-   * The data of the event, the data that will be sent to the subscribers.
-   */
-  data: TData
-}
-```
-
-## Using in handlers
-
-### TypeScript Example
-
-```typescript
-import { ApiRouteConfig, Handlers } from 'motia'
-import { z } from 'zod'
-import { chatMessageSchema } from './streams/chat-messages.stream'
-
-export const config: ApiRouteConfig = {
-  name: 'CreateChatMessage',
-  type: 'api',
-  method: 'POST',
-  path: '/chat-messages',
-  bodySchema: z.object({
-    channelId: z.string(),
-    message: z.string(),
-  }),
-  emits: [],
-  responseSchema: {
-    201: chatMessageSchema
-  }
-}
-
-export const handler = async (req, { streams }) => {
-  /**
-   * Say this is an API Step that a user sends a message to a channel.
-   * 
-   * In your application logic you should have a channel ID defined somewhere
-   * so the client can send the message to the correct channel.
-   */
-  const { channelId, message } = req.body
-
-  /**
-   * Define the message ID however you want, but should be a unique identifier underneath the channel ID.
-   * 
-   * This is used to identify the message in the stream.
-   */
-  const messageId = crypto.randomUUID()
-
-  /**
-   * In your application logic you should have a user ID defined somewhere.
-   * We recommend using middlewares to identify the user on the request.
-   */
-  const userId = 'example-user-id'
-
-  /** 
-   * Creates a message in the stream 
-   */
-  const message = await streams.chatMessage.set(channelId, messageId, {
-    id: messageId,
-    userId: userId,
-    message: message,
-    timestamp: new Date().toISOString()
-  })
-
-  /**
-   * Returning the stream result directly to the client helps Workbench to
-   * render the stream object and update it in real-time in the UI.
-   */
-  return { status: 201, body: message }
-}
-```
-
-### Python Examples
-
-#### With Pydantic (Optional)
-
-```python
-import uuid
-from datetime import datetime
-from pydantic import BaseModel
-
-class ChatMessageRequest(BaseModel):
-    channel_id: str
-    message: str
-
-class ChatMessageResponse(BaseModel):
-    id: str
-    user_id: str
-    message: str
-    timestamp: str
-
-config = {
-    "name": "CreateChatMessage",
-    "type": "api",
-    "method": "POST",
-    "path": "/chat-messages",
-    "bodySchema": ChatMessageRequest.model_json_schema(),
-    "emits": [],
-    "responseSchema": {
-        201: ChatMessageResponse.model_json_schema()
-    }
-}
-
-async def handler(req, context):
-    body = req.get("body", {})
-    
-    # Optional: Validate with Pydantic
-    request_data = ChatMessageRequest(**body)
-    
-    channel_id = request_data.channel_id
-    message_text = request_data.message
-
-    message_id = str(uuid.uuid4())
-    user_id = "example-user-id"
-
-    # Creates a message in the stream
-    chat_message = await context.streams.chatMessage.set(channel_id, message_id, {
-        "id": message_id,
-        "user_id": user_id,
-        "message": message_text,
-        "timestamp": datetime.now().isoformat()
-    })
-
-    return {"status": 201, "body": chat_message}
-```
-
-#### Without Pydantic (Pure JSON Schema)
-
-```python
-import uuid
-from datetime import datetime
-
-config = {
-    "name": "CreateChatMessage",
-    "type": "api",
-    "method": "POST",
-    "path": "/chat-messages",
-    "bodySchema": {
-        "type": "object",
-        "properties": {
-            "channel_id": {"type": "string"},
-            "message": {"type": "string"}
-        },
-        "required": ["channel_id", "message"]
-    },
-    "emits": [],
-    "responseSchema": {
-        201: {
-            "type": "object",
-            "properties": {
-                "id": {"type": "string"},
-                "user_id": {"type": "string"},
-                "message": {"type": "string"},
-                "timestamp": {"type": "string"}
-            }
-        }
-    }
-}
-
-async def handler(req, context):
-    body = req.get("body", {})
-    channel_id = body.get("channel_id")
-    message_text = body.get("message")
-
-    message_id = str(uuid.uuid4())
-    user_id = "example-user-id"
-
-    # Creates a message in the stream
-    chat_message = await context.streams.chatMessage.set(channel_id, message_id, {
-        "id": message_id,
-        "user_id": user_id,
-        "message": message_text,
-        "timestamp": datetime.now().isoformat()
-    })
-
-    return {"status": 201, "body": chat_message}
-```

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

@@ -1,136 +0,0 @@
----
-description: Managing state across Steps
-globs: steps/**/*.step.ts,steps/**/*.step.js,steps/**/*_step.py
-alwaysApply: false
----
-
-# State Management
-
-State Management is a core concept in Motia. It's used to store data across Steps.
-They can be stored across different workflows.
-
-If we want to trigger Event Steps, we can add data to the emit call, which can be used later in the Event Step execution. But this is limited and can't store too much data, 
-that's why we need to use the State Management to store data across Steps.
-
-## Use-cases
-
-**When State Management is recommended:**
-- Pulling data from an external source, like an API, and storing it in the state, then triggering an Event Step to process the data.
-- Storing data that needs to be used later in the workflow.
-- Can be used for caching layer, like caching the result of an API call that usually can take a few seconds to complete and doesn't change very often.
-
-**When another solution can be better suited:**
-- Storing persistent user data: it's preferred to use a database like Postgres or MongoDB to store user data.
-- Storing file data like Base64 encoded images, PDFs, etc: it's preferred to use a storage solution like S3, etc.
-
-## StateManager Interface
-
-The StateManager interface is available in the context of all step handlers. The methods work identically across TypeScript/JavaScript and Python.
-
-```typescript
-type InternalStateManager = {
-  /**
-   * Retrieves a single item from the state
-   * 
-   * @param groupId - The group id of the state
-   * @param key - The key of the item to get
-   * @returns The item or null if it doesn't exist
-   */
-  get<T>(groupId: string, key: string): Promise<T | null>
-
-  /**
-   * Sets a single item in the state
-   * 
-   * @param groupId - The group id of the state
-   * @param key - The key of the item to set
-   * @param value - The value of the item to set
-   * @returns The item
-   */
-  set<T>(groupId: string, key: string, value: T): Promise<T>
-
-  /**
-   * Deletes a single item from the state
-   * 
-   * @param groupId - The group id of the state
-   * @param key - The key of the item to delete
-   * @returns The item or null if it doesn't exist
-   */
-  delete<T>(groupId: string, key: string): Promise<T | null>
-
-  /**
-   * Retrieves a group of items from the state
-   * 
-   * @param groupId - The group id of the state
-   * @returns A list with all the items in the group
-   */
-  getGroup<T>(groupId: string): Promise<T[]>
-
-  /**
-   * Clears a group of items from the state
-   * 
-   * @param groupId - The group id of the state
-   */
-  clear(groupId: string): Promise<void>
-}
-```
-
-## Usage Examples
-
-### TypeScript/JavaScript Example
-
-```typescript
-export const handler: Handlers['ProcessOrder'] = async (input, { state, logger }) => {
-  // Store an order
-  const order = {
-    id: input.orderId,
-    status: 'processing',
-    createdAt: new Date().toISOString()
-  };
-  
-  await state.set('orders', input.orderId, order);
-  
-  // Retrieve an order
-  const savedOrder = await state.get('orders', input.orderId);
-  logger.info('Order retrieved', { savedOrder });
-  
-  // Get all orders
-  const allOrders = await state.getGroup('orders');
-  logger.info('Total orders', { count: allOrders.length });
-  
-  // Update order status
-  order.status = 'completed';
-  await state.set('orders', input.orderId, order);
-  
-  // Delete an order (if needed)
-  // await state.delete('orders', input.orderId);
-};
-```
-
-### Python Example
-
-```python
-async def handler(input_data, context):
-    # Store an order
-    order = {
-        "id": input_data.get("order_id"),
-        "status": "processing",
-        "created_at": datetime.now().isoformat()
-    }
-    
-    await context.state.set("orders", input_data.get("order_id"), order)
-    
-    # Retrieve an order
-    saved_order = await context.state.get("orders", input_data.get("order_id"))
-    context.logger.info("Order retrieved", {"saved_order": saved_order})
-    
-    # Get all orders
-    all_orders = await context.state.get_group("orders")
-    context.logger.info("Total orders", {"count": len(all_orders)})
-    
-    # Update order status
-    order["status"] = "completed"
-    await context.state.set("orders", input_data.get("order_id"), order)
-    
-    # Delete an order (if needed)
-    # await context.state.delete("orders", input_data.get("order_id"))
-```

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

@@ -1,76 +0,0 @@
----
-description: Overriding the UI of Steps in Motia
-globs: steps/**/*.step.tsx,steps/**/*.step.jsx,steps/**/*_step.tsx,steps/**/*_step.jsx
-alwaysApply: true
----
-
-# UI Steps Guide for Motia
-
-UI Steps provide a powerful way to create custom, visually appealing representations of your workflow steps in the Workbench flow visualization tool.
-
-With UI Steps, you can enhance the user experience by designing intuitive, context-aware visual components that clearly communicate your flow's sequencing and events.
-
-## Overview
-
-To create a custom UI for a step, create a .tsx or .jsx file next to your step file with the same base name:
-
-```
-steps/ 
-└── myStep/ 
-  ├── myStep.step.ts      # Step definition
-  └── myStep.step.tsx     # Visual override
-```
-
-## Basic Usage
-
-Let's override an EventNode but keeping the same look. Like the image below. We're going to add an image on the side and show the description.
-
-```typescript
-// myStep.step.tsx
- 
-import { EventNode, EventNodeProps } from 'motia/workbench'
-import React from 'react'
- 
-export const Node: React.FC<EventNodeProps> = (props) => {
-  return (
-    <EventNode {...props}>
-      <div className="flex flex-row items-start gap-2">
-        <div className="text-sm text-gray-400 font-mono">{props.data.description}</div>
-        <img
-          style={{ width: '64px', height: '64px' }}
-          src="https://www.motia.dev/icon.png"
-        />
-      </div>
-    </EventNode>
-  )
-}
-```
-
-## Components
-
-Motia Workbench provides out of the box components that you can use to create custom UI steps, which apply to different types of steps.
-
-### Available Components
-
-| Component | Props Type | Description |
-|-----------|------------|-------------|
-| EventNode | EventNodeProps | Base component for Event Steps, with built-in styling and connection points |
-| ApiNode | ApiNodeProps | Component for API Steps, includes request/response visualization capabilities |
-| CronNode | CronNodeProps | Base component for Cron Steps, displays timing information |
-| NoopNode | NoopNodeProps | Base component for NoopNodes with a different color to comply workbench legend |
-
-
-## Styling guidelines
-
-- Use Tailwind's utility classes only:	Stick to Tailwind CSS utilities for consistent styling
-- Avoid arbitrary values: Use predefined scales from the design system
-- Keep components responsive: Ensure UI elements adapt well to different screen sizes
-- Follow Motia's design system: Maintain consistency with Motia's established design patterns
-
-## Best practices
-
-- Use base components: Use EventNode and ApiNode when possible
-- Keep it simple: Maintain simple and clear visualizations
-- Optimize performance: Minimize state and computations
-- Documentation: Document custom components and patterns
-- Style sharing: Share common styles through utility classes