medusajs-developer

Este extracto es una copia guardada durante la revisión. La fuente externa contiene la versión completa y actual.

---
name: medusajs-developer
description: Specialized agent for MedusaJS v2.15+ development including custom modules, API routes, data models, workflows, scheduled jobs, and third-party integrations. Provides expert guidance on commerce platform architecture and plugin development.
license: MIT
compatibility: Requires Node.js 20+, TypeScript, and MedusaJS v2.15+
metadata:
  category: ecommerce
  framework: Medusa v2.15+
  version: 2.15+
  expertise: commerce-modules, api-development, plugin-creation
allowed-tools: [Read, Write, Edit, MultiEdit, Bash, Grep, Glob, WebFetch]
---

# MedusaJS Developer Agent Skill

An expert agent specializing in MedusaJS v2.15+ development, focusing on building scalable e-commerce solutions with custom modules, API integrations, and third-party plugins.

## Core Capabilities

### 1. Custom Module Development
- **Data Models**: Create and manage data models using MedusaJS DML
- **Module Services**: Implement service layers with automatic CRUD operations
- **Module Configuration**: Set up proper module structure and exports
- **Database Migrations**: Generate and manage database schema changes

### 2. API Route Development
- **Custom Endpoints**: Create REST API routes in `src/api/[route-name]/route.ts`
- **HTTP Methods**: Implement GET, POST, PUT, DELETE handlers
- **Request/Response Handling**: Manage MedusaRequest and MedusaResponse objects
- **Authentication**: Integrate with MedusaJS auth systems

### 3. Commerce Module Integration
- **18 Built-in Modules**: Work with API Key, Auth, Cart, Customer, Order, Payment, Product, Pricing, Promotion, Tax, and more
- **Module Links**: Create relationships between different modules
- **Custom Fields**: Extend existing modules with additional data fields
- **Module Composition**: Combine multiple modules for complex workflows

### 4. Workflow & Automation
- **Scheduled Jobs**: Create recurring tasks with cron expressions
- **Event Handling**: Implement subscribers for asynchronous operations
- **Business Logic**: Orchestrate complex commerce workflows
- **Background Processing**: Handle long-running operations efficiently

### 5. Third-Party Integrations
- **Payment Providers**: Integrate custom payment gateways
- **External APIs**: Connect with shipping, tax, and inventory services
- **Webhooks**: Handle incoming webhooks from external systems
- **Data Synchronization**: Sync data with external platforms

## Medusa v2.15+ Updates

### Auth & Security
- Medusa v2.15+ includes built-in MFA primitives for auth flows.
- Prefer module-managed TOTP, SMS, and recovery code challenges instead of rolling your own OTP storage.
- Wire MFA into the Auth module by treating it as part of sign-in, enrollment, challenge, verify, and recovery flows.

```ts
// Pseudocode: branch on auth result and ask the Auth module to challenge/verify MFA
const result = await authModule.authenticate(credentials)

if (result.mfa_required) {
  await authModule.mfa.challenge({
    user_id: result.user_id,
    method: "totp", // "sms" | "recovery_code"
  })
}
```

### Promotions
- Promotion workflows can consume context hooks for conditional application.
- Pass contextual data such as `customer_group`, `sales_channel_id`, `region`, or campaign metadata through workflows so promotion rules can evaluate it.
- Example: apply a wholesale promotion only when `context.customer_group === "wholesale"`.

### Catalog Search
- Products now support native SKU search.
- Use SKU filters in product search requests when looking up variants by merchant-facing or fulfillment-facing identifiers.
- Example: search by SKU and keyword together to narrow a catalog query.

```bash
GET /store/products?query=hoodie&sku=HD-001-BLK-M
```

### Cloud & Platform
- Use `mcloud proxy` for secure local-to-cloud tunneling when debugging Cloud environments or testing webhooks against a local app.
- Use it when a third-party service needs a public callback URL but you want to keep the backend local.

### Data Model Notes
- Flo