order-management 0.0.16 → 0.0.18

package/.medusa/server/src/workflows/swaps/create-swap-workflow.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSwapWorkflow = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const swap_1 = require("../steps/swap");
+exports.createSwapWorkflow = (0, workflows_sdk_1.createWorkflow)("create-swap", (input) => {
+    const { order_id, return_items, new_items, reason, note, customer_id } = input;
+    // Step 1: Validate order exists and belongs to customer
+    const { order } = (0, swap_1.validateOrderStep)({
+        order_id,
+        customer_id,
+    });
+    // Step 2: Validate swap items
+    const { return_items: validatedReturnItems, new_items: validatedNewItems } = (0, swap_1.validateSwapItemsStep)({
+        order,
+        return_items,
+        new_items,
+    });
+    // Step 3: Calculate price difference
+    const { difference_due } = (0, swap_1.calculateDifferenceStep)({
+        order,
+        return_items: validatedReturnItems,
+        new_items: validatedNewItems,
+    });
+    // Step 4: Create swap record
+    const { swap } = (0, swap_1.createSwapStep)({
+        order_id,
+        return_items: validatedReturnItems,
+        new_items: validatedNewItems,
+        difference_due,
+        reason,
+        note,
+    });
+    // Step 5: Send notification (optional - can be skipped if no email template)
+    // sendNotificationStep({
+    //   to: order.email || "",
+    //   subject: "Swap Request Created",
+    //   renderedContent: null, // Would need email template
+    //   templateData: {},
+    // })
+    return new workflows_sdk_1.WorkflowResponse({
+        swap,
+    });
+});
+exports.default = exports.createSwapWorkflow;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3JlYXRlLXN3YXAtd29ya2Zsb3cuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9zcmMvd29ya2Zsb3dzL3N3YXBzL2NyZWF0ZS1zd2FwLXdvcmtmbG93LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLHFFQUcwQztBQUMxQyx3Q0FLc0I7QUFPVCxRQUFBLGtCQUFrQixHQUFHLElBQUEsOEJBQWMsRUFDOUMsYUFBYSxFQUNiLENBQ0UsS0FBd0QsRUFDWixFQUFFO0lBQzlDLE1BQU0sRUFBRSxRQUFRLEVBQUUsWUFBWSxFQUFFLFNBQVMsRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFLFdBQVcsRUFBRSxHQUFHLEtBQUssQ0FBQTtJQUU5RSx3REFBd0Q7SUFDeEQsTUFBTSxFQUFFLEtBQUssRUFBRSxHQUFHLElBQUEsd0JBQWlCLEVBQUM7UUFDbEMsUUFBUTtRQUNSLFdBQVc7S0FDWixDQUFDLENBQUE7SUFFRiw4QkFBOEI7SUFDOUIsTUFBTSxFQUFFLFlBQVksRUFBRSxvQkFBb0IsRUFBRSxTQUFTLEVBQUUsaUJBQWlCLEVBQUUsR0FDeEUsSUFBQSw0QkFBcUIsRUFBQztRQUNwQixLQUFLO1FBQ0wsWUFBWTtRQUNaLFNBQVM7S0FDVixDQUFDLENBQUE7SUFFSixxQ0FBcUM7SUFDckMsTUFBTSxFQUFFLGNBQWMsRUFBRSxHQUFHLElBQUEsOEJBQXVCLEVBQUM7UUFDakQsS0FBSztRQUNMLFlBQVksRUFBRSxvQkFBb0I7UUFDbEMsU0FBUyxFQUFFLGlCQUFpQjtLQUM3QixDQUFDLENBQUE7SUFFRiw2QkFBNkI7SUFDN0IsTUFBTSxFQUFFLElBQUksRUFBRSxHQUFHLElBQUEscUJBQWMsRUFBQztRQUM5QixRQUFRO1FBQ1IsWUFBWSxFQUFFLG9CQUFvQjtRQUNsQyxTQUFTLEVBQUUsaUJBQWlCO1FBQzVCLGNBQWM7UUFDZCxNQUFNO1FBQ04sSUFBSTtLQUNMLENBQUMsQ0FBQTtJQUVGLDZFQUE2RTtJQUM3RSx5QkFBeUI7SUFDekIsMkJBQTJCO0lBQzNCLHFDQUFxQztJQUNyQyx3REFBd0Q7SUFDeEQsc0JBQXNCO0lBQ3RCLEtBQUs7SUFFTCxPQUFPLElBQUksZ0NBQWdCLENBQTJCO1FBQ3BELElBQUk7S0FDTCxDQUFDLENBQUE7QUFDSixDQUFDLENBQ0YsQ0FBQTtBQUVELGtCQUFlLDBCQUFrQixDQUFBIn0=

package/.medusa/server/src/workflows/swaps/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9zcmMvd29ya2Zsb3dzL3N3YXBzL3R5cGVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/.medusa/server/src/workflows/swaps/update-swap-status-workflow.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateSwapStatusWorkflow = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const swap_1 = require("../steps/swap");
+exports.updateSwapStatusWorkflow = (0, workflows_sdk_1.createWorkflow)("update-swap-status", (input) => {
+    const { swap_id, status, metadata } = input;
+    // Step 1: Retrieve swap to validate it exists
+    (0, swap_1.retrieveSwapStep)({
+        swap_id,
+    });
+    // Step 2: Update status (validation happens in updateSwapStatusStep)
+    const { swap } = (0, swap_1.updateSwapStatusStep)({
+        swap_id,
+        status,
+        metadata,
+    });
+    return new workflows_sdk_1.WorkflowResponse({
+        swap,
+    });
+});
+exports.default = exports.updateSwapStatusWorkflow;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXBkYXRlLXN3YXAtc3RhdHVzLXdvcmtmbG93LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vLi4vc3JjL3dvcmtmbG93cy9zd2Fwcy91cGRhdGUtc3dhcC1zdGF0dXMtd29ya2Zsb3cudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEscUVBRzBDO0FBQzFDLHdDQUdzQjtBQU1ULFFBQUEsd0JBQXdCLEdBQUcsSUFBQSw4QkFBYyxFQUNwRCxvQkFBb0IsRUFDcEIsQ0FDRSxLQUFvQyxFQUNjLEVBQUU7SUFDcEQsTUFBTSxFQUFFLE9BQU8sRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLEdBQUcsS0FBSyxDQUFBO0lBRTNDLDhDQUE4QztJQUM5QyxJQUFBLHVCQUFnQixFQUFDO1FBQ2YsT0FBTztLQUNSLENBQUMsQ0FBQTtJQUVGLHFFQUFxRTtJQUNyRSxNQUFNLEVBQUUsSUFBSSxFQUFFLEdBQUcsSUFBQSwyQkFBb0IsRUFBQztRQUNwQyxPQUFPO1FBQ1AsTUFBTTtRQUNOLFFBQVE7S0FDVCxDQUFDLENBQUE7SUFFRixPQUFPLElBQUksZ0NBQWdCLENBQWlDO1FBQzFELElBQUk7S0FDTCxDQUFDLENBQUE7QUFDSixDQUFDLENBQ0YsQ0FBQTtBQUVELGtCQUFlLGdDQUF3QixDQUFBIn0=

package/README.md

@@ -43,22 +43,43 @@ This starter is compatible with versions >= 2.4.0 of `@medusajs/medusa`.
 - **Order Confirmation Emails**: Automatically sends email notifications when orders are placed (with "Claim Order" support for registered users)
 - **Return Orders Admin Panel**: Complete return orders management section in the Medusa Admin Panel with list view, filtering, search, detail pages, and status management
 - **Guest Returns & Invoices**: Secure endpoints for guest users to initiate returns and download invoices
+- **Customer-Initiated Swaps**: Complete swap/exchange functionality allowing customers to request item swaps directly from the storefront with full status lifecycle management
 
 ## Configuration
 
 The plugin can be configured in your `medusa-config.js` file:
 
 ```js
+import { defineConfig } from "@medusajs/framework/utils"
+
 module.exports = defineConfig({
   // ...
   plugins: [
     {
       resolve: "order-management",
       options: {
+        // Required options
+        storefrontUrl: process.env.STOREFRONT_URL || "http://localhost:8000",
+        jwtSecret: process.env.JWT_SECRET || "medusa-secret-guest-access",
+        
+        // Email template options
         email: {
           orderConfirmTemplate: "src/templates/emails/order-confirmation.html", // Path to HTML template file
           otpTemplate: "src/templates/emails/otp-verification.html", // Path to HTML template file (required)
         },
+        
+        // Optional SMTP configuration (for email delivery)
+        smtp: {
+          enabled: process.env.FORCE_SMTP_REDELIVER === "true",
+          host: process.env.SMTP_HOST,
+          port: process.env.SMTP_PORT ? Number(process.env.SMTP_PORT) : undefined,
+          secure: process.env.SMTP_SECURE === "true",
+          auth: {
+            user: process.env.SMTP_AUTH_USER,
+            pass: process.env.SMTP_AUTH_PASS,
+          },
+          from: process.env.SMTP_FROM || process.env.SMTP_AUTH_USER,
+        },
       },
     },
   ],
@@ -67,15 +88,29 @@ module.exports = defineConfig({
 
 ### Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `email.orderConfirmTemplate` | `string \| null` | `null` | Path to HTML template file for order confirmation emails (relative to project root or absolute path) |
-| `email.otpTemplate` | `string \| null` | `null` | Path to HTML template file for OTP verification emails (relative to project root or absolute path). **Required** for guest OTP functionality. |
+**Required Options:**
+- `storefrontUrl` - Your storefront URL (required)
+- `jwtSecret` - JWT secret for guest order tokens (required)
+
+**Email Template Options:**
+- `email.orderConfirmTemplate` - Path to HTML template file for order confirmation emails (optional)
+- `email.otpTemplate` - Path to HTML template file for OTP verification emails (required for guest OTP functionality)
+
+**Optional SMTP Options:**
+- `smtp.enabled` - Enable SMTP email delivery (default: `false`)
+- `smtp.host` - SMTP server host (required if enabled)
+- `smtp.port` - SMTP server port (required if enabled)
+- `smtp.secure` - Use secure connection (default: `true`)
+- `smtp.auth.user` - SMTP username (required if enabled)
+- `smtp.auth.pass` - SMTP password (required if enabled)
+- `smtp.from` - From email address (optional, defaults to `smtp.auth.user`)
 
 **Notes**: 
+- `storefrontUrl` and `jwtSecret` are required. All other options are optional.
 - Order confirmation emails are only sent if a template path is provided. If no template is configured, emails will not be sent.
-- OTP template is **mandatory**. The guest OTP request API will return an error if `email.otpTemplate` is not configured.
+- OTP template is **mandatory** for guest OTP functionality. The guest OTP request API will return an error if `email.otpTemplate` is not configured.
 - OTP templates should include `{{otp}}` placeholder for the verification code.
+- SMTP configuration is optional. If not enabled, emails will use Medusa's default email provider.
 
 ## Return Orders Admin Panel
 
@@ -210,6 +245,213 @@ The following variables are available in order confirmation email templates:
 | `{{is_registered}}` | Whether the customer email has a registered account | `true` |
 | `{{claim_link}}` | Link for registered users to claim their guest order | `http://.../claim?order_id=...` |
 
+## Customer-Initiated Swaps
+
+The plugin includes a complete swap/exchange feature that allows customers to request item swaps directly from the storefront. This extends Medusa v2's native OrderExchange functionality with customer-facing APIs and admin management tools.
+
+### Features
+
+- **Customer-Initiated Swaps**: Customers can request swaps for their orders directly from the storefront
+- **Complete Status Lifecycle**: Full status tracking from `requested` → `approved` → `return_started` → `return_shipped` → `return_received` → `new_items_shipped` → `completed`
+- **Admin Management**: Complete admin panel for viewing, approving, rejecting, and managing swaps
+- **Price Difference Calculation**: Automatic calculation of price differences between returned and new items
+- **Status History**: Complete audit trail of all status changes
+
+### Swap Status Flow
+
+```
+requested → approved → return_started → return_shipped → return_received → new_items_shipped → completed
+         ↘ rejected
+         ↘ cancelled (from any status except completed)
+```
+
+### Storefront API Endpoints
+
+#### Create Swap Request
+
+```bash
+POST /store/swaps
+Authorization: Bearer <customer_token>
+Content-Type: application/json
+
+{
+  "order_id": "order_123",
+  "return_items": [
+    {
+      "id": "item_123",
+      "quantity": 1,
+      "reason": "Wrong size"
+    }
+  ],
+  "new_items": [
+    {
+      "variant_id": "variant_456",
+      "quantity": 1
+    }
+  ],
+  "reason": "Size exchange",
+  "note": "Please send size M instead"
+}
+```
+
+#### List Customer Swaps
+
+```bash
+GET /store/swaps
+Authorization: Bearer <customer_token>
+```
+
+#### Get Swap Details
+
+```bash
+GET /store/swaps/{swap_id}
+Authorization: Bearer <customer_token>
+```
+
+#### List Swaps for Order
+
+```bash
+GET /store/orders/{order_id}/swaps
+Authorization: Bearer <customer_token>
+```
+
+#### Create Swap for Order
+
+```bash
+POST /store/orders/{order_id}/swaps
+Authorization: Bearer <customer_token>
+Content-Type: application/json
+
+{
+  "return_items": [
+    {
+      "id": "item_123",
+      "quantity": 1
+    }
+  ],
+  "new_items": [
+    {
+      "variant_id": "variant_456",
+      "quantity": 1
+    }
+  ],
+  "reason": "Size exchange"
+}
+```
+
+#### Cancel Swap
+
+```bash
+POST /store/swaps/{swap_id}/cancel
+Authorization: Bearer <customer_token>
+```
+
+### Admin API Endpoints
+
+#### List All Swaps
+
+```bash
+GET /admin/swaps?status=requested&order_id=order_123&limit=50&offset=0
+```
+
+#### Get Swap Details
+
+```bash
+GET /admin/swaps/{swap_id}
+```
+
+#### Approve Swap
+
+```bash
+POST /admin/swaps/{swap_id}/approve
+```
+
+#### Reject Swap
+
+```bash
+POST /admin/swaps/{swap_id}/reject
+Content-Type: application/json
+
+{
+  "reason": "Item out of stock"
+}
+```
+
+#### Update Swap Status
+
+```bash
+POST /admin/swaps/{swap_id}/status
+Content-Type: application/json
+
+{
+  "status": "return_started",
+  "metadata": {
+    "return_label_id": "label_123"
+  }
+}
+```
+
+### Admin UI
+
+The plugin includes a complete admin UI for managing swaps:
+
+- **Swaps List Page**: View all swaps with filtering by status, search by order ID, and pagination
+- **Swap Detail Page**: View complete swap information including:
+  - Swap details (ID, status, dates, price difference)
+  - Original order information
+  - Return items list
+  - New items list
+  - Status history timeline
+  - Action buttons (approve/reject/update status)
+
+Access the Swaps section from the Admin Panel sidebar.
+
+### Storefront Helpers
+
+The plugin provides helper methods for easy integration:
+
+```typescript
+import { createSwapRequest, getSwaps, getSwap, cancelSwap } from "order-management/helpers"
+
+// Create a swap request
+const swap = await createSwapRequest({
+  orderId: "order_123",
+  returnItems: [
+    { id: "item_123", quantity: 1, reason: "Wrong size" }
+  ],
+  newItems: [
+    { variant_id: "variant_456", quantity: 1 }
+  ],
+  reason: "Size exchange",
+  note: "Please send size M"
+}, container)
+
+// Get swaps for an order
+const swaps = await getSwaps("order_123", container)
+
+// Get a specific swap
+const swapDetails = await getSwap("swap_123", container)
+
+// Cancel a swap
+const cancelledSwap = await cancelSwap("swap_123", container)
+```
+
+### Status Transitions
+
+The swap status flow enforces valid transitions:
+
+- **requested** → `approved`, `rejected`, `cancelled`
+- **approved** → `return_started`, `cancelled`
+- **return_started** → `return_shipped`, `cancelled`
+- **return_shipped** → `return_received`, `cancelled`
+- **return_received** → `new_items_shipped`, `cancelled`
+- **new_items_shipped** → `completed`, `cancelled`
+- **rejected** → (terminal state)
+- **completed** → (terminal state)
+- **cancelled** → (terminal state)
+
+Invalid status transitions will be rejected with a descriptive error message.
+
 ## Getting Started
 
 Visit the [Quickstart Guide](https://docs.medusajs.com/learn/installation) to set up a server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "order-management",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "A starter for Medusa plugins.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",

package/.medusa/server/src/utils/resolve-options.js

@@ -1,57 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveOrderManagementOptions = resolveOrderManagementOptions;
-exports.extractOrderManagementOptions = extractOrderManagementOptions;
-const DEFAULT_OPTIONS = {
-    email: {
-        orderConfirmTemplate: null,
-        otpTemplate: null,
-    },
-};
-/**
- * Resolve and normalize plugin options with defaults
- */
-function resolveOrderManagementOptions(options) {
-    if (!options) {
-        return DEFAULT_OPTIONS;
-    }
-    return {
-        email: {
-            orderConfirmTemplate: options.email?.orderConfirmTemplate ?? DEFAULT_OPTIONS.email.orderConfirmTemplate,
-            otpTemplate: options.email?.otpTemplate ?? DEFAULT_OPTIONS.email.otpTemplate,
-        },
-    };
-}
-/**
- * Extract plugin options from config module
- */
-function extractOrderManagementOptions(configModule) {
-    // Try from projectConfig.plugins first
-    const plugins = configModule?.projectConfig?.plugins ?? [];
-    for (const plugin of plugins) {
-        if (typeof plugin === "string") {
-            if (plugin === "order-management") {
-                return {};
-            }
-            continue;
-        }
-        if (plugin?.resolve === "order-management") {
-            return plugin.options;
-        }
-    }
-    // Try from direct config.plugins (fallback)
-    const directPlugins = configModule?.plugins ?? [];
-    for (const plugin of directPlugins) {
-        if (typeof plugin === "string") {
-            if (plugin === "order-management") {
-                return {};
-            }
-            continue;
-        }
-        if (plugin?.resolve === "order-management") {
-            return plugin.options;
-        }
-    }
-    return undefined;
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzb2x2ZS1vcHRpb25zLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3V0aWxzL3Jlc29sdmUtb3B0aW9ucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQW1CQSxzRUFhQztBQUtELHNFQW9DQztBQWhFRCxNQUFNLGVBQWUsR0FBbUM7SUFDdEQsS0FBSyxFQUFFO1FBQ0wsb0JBQW9CLEVBQUUsSUFBSTtRQUMxQixXQUFXLEVBQUUsSUFBSTtLQUNsQjtDQUNGLENBQUE7QUFFRDs7R0FFRztBQUNILFNBQWdCLDZCQUE2QixDQUMzQyxPQUE2QztJQUU3QyxJQUFJLENBQUMsT0FBTyxFQUFFLENBQUM7UUFDYixPQUFPLGVBQWUsQ0FBQTtJQUN4QixDQUFDO0lBRUQsT0FBTztRQUNMLEtBQUssRUFBRTtZQUNMLG9CQUFvQixFQUFFLE9BQU8sQ0FBQyxLQUFLLEVBQUUsb0JBQW9CLElBQUksZUFBZSxDQUFDLEtBQUssQ0FBQyxvQkFBb0I7WUFDdkcsV0FBVyxFQUFFLE9BQU8sQ0FBQyxLQUFLLEVBQUUsV0FBVyxJQUFJLGVBQWUsQ0FBQyxLQUFLLENBQUMsV0FBVztTQUM3RTtLQUNGLENBQUE7QUFDSCxDQUFDO0FBRUQ7O0dBRUc7QUFDSCxTQUFnQiw2QkFBNkIsQ0FDM0MsWUFBa0I7SUFFbEIsdUNBQXVDO0lBQ3ZDLE1BQU0sT0FBTyxHQUFHLFlBQVksRUFBRSxhQUFhLEVBQUUsT0FBTyxJQUFJLEVBQUUsQ0FBQTtJQUUxRCxLQUFLLE1BQU0sTUFBTSxJQUFJLE9BQU8sRUFBRSxDQUFDO1FBQzdCLElBQUksT0FBTyxNQUFNLEtBQUssUUFBUSxFQUFFLENBQUM7WUFDL0IsSUFBSSxNQUFNLEtBQUssa0JBQWtCLEVBQUUsQ0FBQztnQkFDbEMsT0FBTyxFQUFFLENBQUE7WUFDWCxDQUFDO1lBQ0QsU0FBUTtRQUNWLENBQUM7UUFFRCxJQUFJLE1BQU0sRUFBRSxPQUFPLEtBQUssa0JBQWtCLEVBQUUsQ0FBQztZQUMzQyxPQUFPLE1BQU0sQ0FBQyxPQUF1QyxDQUFBO1FBQ3ZELENBQUM7SUFDSCxDQUFDO0lBRUQsNENBQTRDO0lBQzVDLE1BQU0sYUFBYSxHQUFJLFlBQW9CLEVBQUUsT0FBTyxJQUFJLEVBQUUsQ0FBQTtJQUUxRCxLQUFLLE1BQU0sTUFBTSxJQUFJLGFBQWEsRUFBRSxDQUFDO1FBQ25DLElBQUksT0FBTyxNQUFNLEtBQUssUUFBUSxFQUFFLENBQUM7WUFDL0IsSUFBSSxNQUFNLEtBQUssa0JBQWtCLEVBQUUsQ0FBQztnQkFDbEMsT0FBTyxFQUFFLENBQUE7WUFDWCxDQUFDO1lBQ0QsU0FBUTtRQUNWLENBQUM7UUFFRCxJQUFJLE1BQU0sRUFBRSxPQUFPLEtBQUssa0JBQWtCLEVBQUUsQ0FBQztZQUMzQyxPQUFPLE1BQU0sQ0FBQyxPQUF1QyxDQUFBO1FBQ3ZELENBQUM7SUFDSCxDQUFDO0lBRUQsT0FBTyxTQUFTLENBQUE7QUFDbEIsQ0FBQyJ9