order-management 0.0.49 → 0.0.50

package/README.md

@@ -8,7 +8,7 @@
   </a>
 </p>
 <h1 align="center">
-  Medusa Plugin Starter
+  Order Management Plugin
 </h1>
 
 <h4 align="center">
@@ -17,7 +17,7 @@
 </h4>
 
 <p align="center">
-  Building blocks for digital commerce
+  Order lifecycle, guest portal, returns, swaps, and status-based notifications for Medusa
 </p>
 <p align="center">
   <a href="https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md">
@@ -34,17 +34,29 @@
 
 ## Compatibility
 
-This starter is compatible with versions >= 2.4.0 of `@medusajs/medusa`. 
+This plugin is compatible with Medusa v2 (e.g. `@medusajs/framework` and `@medusajs/medusa` 2.11.x). Check `package.json` peer dependencies for the exact version range. 
 
 ## Features
 
-- **Order Management**: Cancel and reorder functionality for orders
-- **Guest Order Portal**: Complete look-up system for guest users (OTP-based) with full order management capabilities
-- **Guest Order Actions**: Secure endpoints for guest users to view orders, initiate returns, cancel orders, reorder, and download invoices
-- **Order Confirmation Emails**: Automatically sends email notifications when orders are placed (with "Claim Order" support for registered users)
-- **Status-Based Notifications**: Configure automatic email and SMS notifications for any order status change (order placed, shipped, delivered, etc.)
-- **Return Orders Admin Panel**: Complete return orders management section in the Medusa Admin Panel with list view, filtering, search, detail pages, and status management
-- **Customer-Initiated Swaps**: Complete swap/exchange functionality allowing customers to request item swaps directly from the storefront with full status lifecycle management
+- **Order Management**: Cancel and reorder for both authenticated customers and guest orders
+- **Authenticated Customer APIs**: Store endpoints for logged-in customers to cancel orders (`/store/orders/cancel/:order_id`), reorder (`/store/orders/reorder/:order_id`), and manage returns and swaps (`/store/returns`, `/store/swaps`)
+- **Guest Order Portal**: OTP-based look-up for guest users with full order management (view orders, initiate returns, cancel, reorder, manage swaps)
+- **Guest Order Actions**: Secure JWT-protected endpoints for guest users to view orders, initiate returns, cancel orders, reorder, and manage swaps (all under `/store/guest-orders/:id/...`)
+- **Order Confirmation Emails**: Optional email notifications when orders are placed (with "Claim Order" support for registered users)
+- **Status-Based Notifications**: Configurable email, SMS, and push notifications for order status changes (pending, shipped, delivered, canceled, etc.)
+- **Return Orders Admin Panel**: Admin UI and API for return orders (list, filter, search, detail, approve, reject, mark received, process refund)
+- **Customer-Initiated Returns**: Store and guest APIs to create returns; admin workflow to approve, receive, and process refunds with Medusa return linking
+- **Customer-Initiated Swaps**: Store and guest APIs to create swap requests; admin creates Medusa exchange via `create-exchange` with full status lifecycle
+
+### Plugin structure (high level)
+
+| Area | What the plugin provides |
+|------|---------------------------|
+| **Store (authenticated)** | `/store/orders/cancel|reorder/:id`, `/store/returns`, `/store/swaps` |
+| **Store (guest)** | `/store/otp/request|verify`, `/store/guest-orders`, `/store/guest-orders/:id/returns|swaps|cancel|reorder` |
+| **Admin** | `/admin/returns` (list, get, approve, reject, mark-received, process-refund, status), `/admin/swaps` (list, get, create-exchange, reject, health) |
+| **Modules** | Custom `return` and `swap` modules with workflows and Medusa linking |
+| **Subscribers** | Order confirmation email, status notifications, return/swap event sync |
 
 ## Configuration
 
@@ -185,11 +197,17 @@ Once the plugin is installed and configured, you can access the Return Orders se
 
 ### API Endpoints
 
-The plugin provides the following admin API endpoints for return orders management:
+The plugin provides admin API endpoints for return orders:
 
-- `GET /admin/returns` - List all return orders with filtering, search, and pagination
-- `GET /admin/returns/:id` - Get detailed information for a specific return order
-- `POST /admin/returns/:id/status` - Update the status of a return order
+- `GET /admin/returns` - List all return orders (filtering, search, pagination)
+- `GET /admin/returns/:id` - Get detailed information for a specific return
+- `POST /admin/returns/:id/approve` - Approve and create Medusa return
+- `POST /admin/returns/:id/reject` - Reject the return
+- `POST /admin/returns/:id/mark-received` - Mark return items as received
+- `POST /admin/returns/:id/process-refund` - Process refund
+- `POST /admin/returns/:id/status` - Update status manually (if needed)
+
+Full request/response details are in the **Standalone Return Flow** section below.
 
 ### Return Statuses
 
@@ -230,12 +248,26 @@ The plugin provides the following store API endpoints for the Guest Order Portal
 - `GET /store/guest-orders/:id` - Get full details for a specific guest order (includes items, shipping status, etc.).
 
 #### Guest Order Actions
+- `GET /store/guest-orders/:id` - Get full details for a specific guest order (requires guest JWT).
 - `POST /store/guest-orders/:id/returns` - Initiate a return request for a guest order.
 - `POST /store/guest-orders/:id/cancel` - Cancel a guest order.
 - `POST /store/guest-orders/:id/reorder` - Reorder a guest order (creates a new cart with the same items).
-- `GET /store/guest-orders/:id/invoice` - Download a PDF invoice for the guest order.
+- `GET /store/guest-orders/:id/swaps` - List swaps for the guest order.
+- `POST /store/guest-orders/:id/swaps` - Create a swap request for the guest order.
+- `POST /store/guest-orders/:id/swaps/:swap_id/cancel` - Cancel a swap for the guest order.
+
+**Note**: All guest order endpoints require the guest JWT in the `Authorization: Bearer <token>` header or cookie.
+
+## Authenticated Customer Order APIs
+
+Logged-in customers (storefront with customer auth) can use these endpoints without the guest portal:
 
-**Note**: All `GET` and `POST` requests to guest order endpoints require the JWT token in the `Authorization: Bearer <token>` header.
+- `POST /store/orders/cancel/:order_id` - Cancel an order (customer must own the order).
+- `POST /store/orders/reorder/:order_id` - Reorder (creates a new cart with the same items).
+- `GET /store/returns`, `POST /store/returns`, `GET /store/returns/:id`, `POST /store/returns/:id/cancel` - List and create returns (filtered by customer).
+- `GET /store/swaps`, `POST /store/swaps`, `GET /store/swaps/:id`, `POST /store/swaps/:id/cancel` - List and create swaps (filtered by customer).
+
+All require `Authorization: Bearer <customer_token>`.
 
 ## Email Templates
 
@@ -651,17 +683,9 @@ requested → approved → return_started → return_shipped → return_received
          ↘ cancelled (from any status except completed)
 ```
 
-### Storefront Implementation Guide
-
-For detailed implementation instructions on integrating exchange functionality into your storefront, see the [Storefront Exchange Implementation Guide](./docs/STOREFRONT_EXCHANGE_IMPLEMENTATION.md). This guide includes:
+### Storefront API Endpoints (Authenticated Customers)
 
-- Complete API documentation with request/response examples
-- React/TypeScript implementation examples
-- Error handling best practices
-- Status flow diagrams
-- Integration checklist
-
-### Storefront API Endpoints
+All store swap endpoints require customer authentication (`Authorization: Bearer <customer_token>`).
 
 #### Create Swap Request
 
@@ -693,10 +717,12 @@ Content-Type: application/json
 #### List Customer Swaps
 
 ```bash
-GET /store/swaps
+GET /store/swaps?order_id=order_123&limit=100&offset=0
 Authorization: Bearer <customer_token>
 ```
 
+Optional query: `order_id` to filter by order; `limit` and `offset` for pagination.
+
 #### Get Swap Details
 
 ```bash
@@ -704,37 +730,6 @@ 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
@@ -756,10 +751,12 @@ GET /admin/swaps?status=requested&order_id=order_123&limit=50&offset=0
 GET /admin/swaps/{swap_id}
 ```
 
-#### Approve Swap
+#### Create Exchange (Approve and create Medusa exchange)
+
+Admin "approval" is done by creating the Medusa exchange from the swap. This endpoint creates the exchange (and return) in Medusa and links it to the plugin swap.
 
 ```bash
-POST /admin/swaps/{swap_id}/approve
+POST /admin/swaps/{swap_id}/create-exchange
 ```
 
 #### Reject Swap
@@ -773,43 +770,23 @@ Content-Type: application/json
 }
 ```
 
-#### 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:
+The plugin includes an 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)
+- **Swap Detail Page**: View swap information including swap details, order, return items, new items, and status history. Actions: **Create Exchange** (creates the Medusa exchange and links it to the swap) and **Reject**
 
-Access the Swaps section from the Admin Panel sidebar.
+Access the Swaps section from the Admin Panel sidebar. A health check endpoint is available at `GET /admin/swaps/health` for monitoring.
 
 ### Storefront Helpers
 
-The plugin provides helper methods for easy integration:
+The plugin exports helpers for use in custom workflows or server-side code (e.g. within the Medusa backend). Import from the built plugin:
 
 ```typescript
 import { createSwapRequest, getSwaps, getSwap, cancelSwap } from "order-management/helpers"
 
-// Create a swap request
+// Create a swap request (order_id in payload)
 const swap = await createSwapRequest({
   orderId: "order_123",
   returnItems: [
@@ -822,7 +799,7 @@ const swap = await createSwapRequest({
   note: "Please send size M"
 }, container)
 
-// Get swaps for an order
+// Get swaps (optionally filtered by order)
 const swaps = await getSwaps("order_123", container)
 
 // Get a specific swap
@@ -832,6 +809,8 @@ const swapDetails = await getSwap("swap_123", container)
 const cancelledSwap = await cancelSwap("swap_123", container)
 ```
 
+Return helpers are available from `order-management/helpers/returns` (see Standalone Return Flow section).
+
 ### Status Transitions
 
 The swap status flow enforces valid transitions:

package/package.json

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