order-management 0.0.17 → 0.0.19

package/README.md

@@ -43,6 +43,7 @@ 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
 
@@ -244,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.17",
+  "version": "0.0.19",
   "description": "A starter for Medusa plugins.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",

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

@@ -1,101 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractOrderManagementOptions = extractOrderManagementOptions;
-exports.resolveOrderManagementOptions = resolveOrderManagementOptions;
-/**
- * Extract plugin options from config module
- */
-function extractOrderManagementOptions(configModule) {
-    if (!configModule || typeof configModule !== "object") {
-        return undefined;
-    }
-    // Try from projectConfig.plugins first
-    const plugins = configModule
-        ?.projectConfig?.plugins ?? [];
-    for (const plugin of plugins) {
-        if (typeof plugin === "string") {
-            if (plugin === "order-management") {
-                return undefined;
-            }
-            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 undefined;
-            }
-            continue;
-        }
-        if (plugin?.resolve === "order-management") {
-            return plugin.options;
-        }
-    }
-    return undefined;
-}
-/**
- * Resolve plugin options with validation
- * Throws error if required options are missing
- */
-function resolveOrderManagementOptions(options) {
-    if (!options) {
-        throw new Error("order-management plugin options are required. Please configure the plugin in medusa-config.ts");
-    }
-    if (!options.storefrontUrl) {
-        throw new Error("order-management: storefrontUrl is required");
-    }
-    if (!options.jwtSecret) {
-        throw new Error("order-management: jwtSecret is required");
-    }
-    // Resolve email options
-    const emailOptions = {
-        orderConfirmTemplate: options.email?.orderConfirmTemplate ?? null,
-        otpTemplate: options.email?.otpTemplate ?? null,
-    };
-    // Resolve SMTP config
-    const smtpEnabled = options.smtp?.enabled ?? false;
-    let smtpConfig;
-    if (smtpEnabled) {
-        if (!options.smtp?.host) {
-            throw new Error("order-management: smtp.host is required when smtp.enabled is true");
-        }
-        if (!options.smtp?.port) {
-            throw new Error("order-management: smtp.port is required when smtp.enabled is true");
-        }
-        if (!options.smtp?.auth?.user) {
-            throw new Error("order-management: smtp.auth.user is required when smtp.enabled is true");
-        }
-        if (!options.smtp?.auth?.pass) {
-            throw new Error("order-management: smtp.auth.pass is required when smtp.enabled is true");
-        }
-        smtpConfig = {
-            enabled: true,
-            host: options.smtp.host,
-            port: options.smtp.port,
-            secure: options.smtp.secure ?? true,
-            auth: {
-                user: options.smtp.auth.user,
-                pass: options.smtp.auth.pass,
-            },
-            from: options.smtp.from || options.smtp.auth.user,
-        };
-    }
-    else {
-        smtpConfig = {
-            enabled: false,
-            secure: true,
-        };
-    }
-    return {
-        storefrontUrl: options.storefrontUrl,
-        jwtSecret: options.jwtSecret,
-        email: emailOptions,
-        smtp: smtpConfig,
-    };
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzb2x2ZS1vcHRpb25zLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3V0aWxzL3Jlc29sdmUtb3B0aW9ucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUtBLHNFQTZDQztBQU1ELHNFQWlFQztBQXZIRDs7R0FFRztBQUNILFNBQWdCLDZCQUE2QixDQUMzQyxZQUFzQjtJQUV0QixJQUFJLENBQUMsWUFBWSxJQUFJLE9BQU8sWUFBWSxLQUFLLFFBQVEsRUFBRSxDQUFDO1FBQ3RELE9BQU8sU0FBUyxDQUFBO0lBQ2xCLENBQUM7SUFFRCx1Q0FBdUM7SUFDdkMsTUFBTSxPQUFPLEdBQUksWUFBNEQ7UUFDM0UsRUFBRSxhQUFhLEVBQUUsT0FBTyxJQUFJLEVBQUUsQ0FBQTtJQUVoQyxLQUFLLE1BQU0sTUFBTSxJQUFJLE9BQU8sRUFBRSxDQUFDO1FBQzdCLElBQUksT0FBTyxNQUFNLEtBQUssUUFBUSxFQUFFLENBQUM7WUFDL0IsSUFBSSxNQUFNLEtBQUssa0JBQWtCLEVBQUUsQ0FBQztnQkFDbEMsT0FBTyxTQUFTLENBQUE7WUFDbEIsQ0FBQztZQUNELFNBQVE7UUFDVixDQUFDO1FBRUQsSUFBSyxNQUErQixFQUFFLE9BQU8sS0FBSyxrQkFBa0IsRUFBRSxDQUFDO1lBQ3JFLE9BQVEsTUFBcUQsQ0FBQyxPQUVqRCxDQUFBO1FBQ2YsQ0FBQztJQUNILENBQUM7SUFFRCw0Q0FBNEM7SUFDNUMsTUFBTSxhQUFhLEdBQUksWUFBd0MsRUFBRSxPQUFPLElBQUksRUFBRSxDQUFBO0lBRTlFLEtBQUssTUFBTSxNQUFNLElBQUksYUFBYSxFQUFFLENBQUM7UUFDbkMsSUFBSSxPQUFPLE1BQU0sS0FBSyxRQUFRLEVBQUUsQ0FBQztZQUMvQixJQUFJLE1BQU0sS0FBSyxrQkFBa0IsRUFBRSxDQUFDO2dCQUNsQyxPQUFPLFNBQVMsQ0FBQTtZQUNsQixDQUFDO1lBQ0QsU0FBUTtRQUNWLENBQUM7UUFFRCxJQUFLLE1BQStCLEVB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