order-management 0.0.94 → 0.0.96

package/.medusa/server/src/helpers/refund-receive-guard.js

@@ -1,17 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.refundBlockedByReturnMessage = refundBlockedByReturnMessage;
+exports.refundBlockedByExchangeMessage = refundBlockedByExchangeMessage;
+exports.refundBlockedByWalletSettleMessage = refundBlockedByWalletSettleMessage;
+exports.refundBlockedOrderUnresolvedMessage = refundBlockedOrderUnresolvedMessage;
+exports.isWalletSettleOrderTransaction = isWalletSettleOrderTransaction;
+exports.isWalletSettlePaymentRefund = isWalletSettlePaymentRefund;
+exports.orderHasWalletSettle = orderHasWalletSettle;
 exports.getUnreceivedReturnBlockingRefund = getUnreceivedReturnBlockingRefund;
+exports.shouldBlockRefundForRma = shouldBlockRefundForRma;
 exports.assertReturnReceivedForRefund = assertReturnReceivedForRefund;
 exports.canProcessRefundForReturn = canProcessRefundForReturn;
 const utils_1 = require("@medusajs/framework/utils");
 const return_exchange_guard_1 = require("./return-exchange-guard");
+const WALLET_SETTLE_REFERENCE_PREFIXES = [
+    "wallet:exchange:",
+    "wallet:return:",
+    "wallet:payment:",
+];
 /**
  * Message when a refund is attempted before the return is fully received.
  */
 function refundBlockedByReturnMessage(status) {
     return `Cannot process a refund while the return is ${status}. Receive the returned items first.`;
 }
+function refundBlockedByExchangeMessage() {
+    return "Cannot process a refund while an exchange is in progress. Receive the returned items first.";
+}
+function refundBlockedByWalletSettleMessage() {
+    return "Cannot process a payment refund; this order was already settled to the customer wallet.";
+}
+function refundBlockedOrderUnresolvedMessage() {
+    return "Cannot process a refund: unable to resolve the order for this payment. Verify the payment is linked to an order.";
+}
+function isWalletSettleOrderTransaction(tx) {
+    if ((tx.reference ?? "").trim() !== "refund") {
+        return false;
+    }
+    const refId = (tx.reference_id ?? "").trim();
+    return WALLET_SETTLE_REFERENCE_PREFIXES.some((prefix) => refId.startsWith(prefix));
+}
+function isWalletSettlePaymentRefund(refund) {
+    if (refund.created_by === "wallet_settle") {
+        return true;
+    }
+    if (refund.metadata?.wallet_settle === true) {
+        return true;
+    }
+    const note = refund.note ?? "";
+    return note.startsWith("wallet_settle:");
+}
+function orderHasWalletSettle(input) {
+    if ((input.orderTransactions ?? []).some(isWalletSettleOrderTransaction)) {
+        return true;
+    }
+    if ((input.paymentRefunds ?? []).some(isWalletSettlePaymentRefund)) {
+        return true;
+    }
+    return false;
+}
 /**
  * First unreceived return that must block a refund (`open` | `requested` | `partially_received`).
  * Exchange-linked returns are included — refunds are blocked until items are received.
@@ -24,6 +71,60 @@ function getUnreceivedReturnBlockingRefund(returns) {
     }
     return null;
 }
+/**
+ * Whether admin payment refund should be blocked for open RMA or prior wallet settle.
+ */
+function shouldBlockRefundForRma(input) {
+    if (orderHasWalletSettle({
+        orderTransactions: input.orderTransactions,
+        paymentRefunds: input.paymentRefunds,
+    })) {
+        return {
+            blocked: true,
+            reason: "wallet_settle",
+            message: refundBlockedByWalletSettleMessage(),
+        };
+    }
+    const blockingReturn = getUnreceivedReturnBlockingRefund(input.returns);
+    if (blockingReturn) {
+        return {
+            blocked: true,
+            reason: "return",
+            message: refundBlockedByReturnMessage(blockingReturn.status ?? "requested"),
+            returnId: blockingReturn.id,
+            status: blockingReturn.status ?? undefined,
+        };
+    }
+    for (const exchange of input.exchanges) {
+        let linked = exchange.return ?? null;
+        if (!linked && exchange.return_id) {
+            linked =
+                input.returns.find((r) => r.id === exchange.return_id) ?? null;
+        }
+        const linkedForGuard = linked
+            ? {
+                id: linked.id,
+                status: linked.status ?? undefined,
+                exchange_id: linked.exchange_id,
+            }
+            : null;
+        if ((0, return_exchange_guard_1.isActiveExchange)({
+            id: exchange.id,
+            canceled_at: exchange.canceled_at,
+            return_id: exchange.return_id,
+            return: linkedForGuard,
+        }, linkedForGuard)) {
+            return {
+                blocked: true,
+                reason: "exchange",
+                message: refundBlockedByExchangeMessage(),
+                exchangeId: exchange.id,
+                status: linked?.status ?? undefined,
+            };
+        }
+    }
+    return { blocked: false };
+}
 /**
  * Throw NOT_ALLOWED when this return is still unreceived.
  * No return / already received / canceled → allow.
@@ -45,4 +146,4 @@ function canProcessRefundForReturn(input) {
         Boolean(input.has_mapping) &&
         !input.is_refunded);
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVmdW5kLXJlY2VpdmUtZ3VhcmQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvaGVscGVycy9yZWZ1bmQtcmVjZWl2ZS1ndWFyZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQVdBLG9FQUVDO0FBTUQsOEVBU0M7QUFNRCxzRUFhQztBQUtELDhEQVVDO0FBOURELHFEQUF1RDtBQUN2RCxtRUFBOEQ7QUFPOUQ7O0dBRUc7QUFDSCxTQUFnQiw0QkFBNEIsQ0FBQyxNQUFjO0lBQ3pELE9BQU8sK0NBQStDLE1BQU0scUNBQXFDLENBQUE7QUFDbkcsQ0FBQztBQUVEOzs7R0FHRztBQUNILFNBQWdCLGlDQUFpQyxDQUMvQyxPQUErQjtJQUUvQixLQUFLLE1BQU0sR0FBRyxJQUFJLE9BQU8sRUFBRSxDQUFDO1FBQzFCLElBQUksSUFBQSw0Q0FBb0IsRUFBQyxHQUFHLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQztZQUNyQyxPQUFPLEdBQUcsQ0FBQTtRQUNaLENBQUM7SUFDSCxDQUFDO0lBQ0QsT0FBTyxJQUFJLENBQUE7QUFDYixDQUFDO0FBRUQ7OztHQUdHO0FBQ0gsU0FBZ0IsNkJBQTZCLENBQzNDLEdBQTRDO0lBRTVDLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQztRQUNULE9BQU07SUFDUixDQUFDO0lBQ0QsSUFBSSxDQUFDLElBQUEsNENBQW9CLEVBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxFQUFFLENBQUM7UUFDdEMsT0FBTTtJQUNSLENBQUM7SUFDRCxNQUFNLElBQUksbUJBQVcsQ0FDbkIsbUJBQVcsQ0FBQyxLQUFLLENBQUMsV0FBVyxFQUM3Qiw0QkFBNEIsQ0FBQyxHQUFHLENBQUMsTUFBTSxJQUFJLFdBQVcsQ0FBQyxDQUN4RCxDQUFBO0FBQ0gsQ0FBQztBQUVEOztHQUVHO0FBQ0gsU0FBZ0IseUJBQXlCLENBQUMsS0FJekM7SUFDQyxPQUFPLENBQ0wsS0FBSyxDQUFDLE1BQU0sS0FBSyxVQUFVO1FBQzNCLE9BQU8sQ0FBQyxLQUFLLENBQUMsV0FBVyxDQUFDO1FBQzFCLENBQUMsS0FBSyxDQUFDLFdBQVcsQ0FDbkIsQ0FBQTtBQUNILENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVmdW5kLXJlY2VpdmUtZ3VhcmQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvaGVscGVycy9yZWZ1bmQtcmVjZWl2ZS1ndWFyZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQWtEQSxvRUFFQztBQUVELHdFQUVDO0FBRUQsZ0ZBRUM7QUFFRCxrRkFFQztBQUVELHdFQVVDO0FBRUQsa0VBV0M7QUFFRCxvREFXQztBQU1ELDhFQVNDO0FBS0QsMERBbUVDO0FBTUQsc0VBYUM7QUFLRCw4REFVQztBQS9ORCxxREFBdUQ7QUFDdkQsbUVBR2dDO0FBcUNoQyxNQUFNLGdDQUFnQyxHQUFHO0lBQ3ZDLGtCQUFrQjtJQUNsQixnQkFBZ0I7SUFDaEIsaUJBQWlCO0NBQ1QsQ0FBQTtBQUVWOztHQUVHO0FBQ0gsU0FBZ0IsNEJBQTRCLENBQUMsTUFBYztJQUN6RCxPQUFPLCtDQUErQyxNQUFNLHFDQUFxQyxDQUFBO0FBQ25HLENBQUM7QUFFRCxTQUFnQiw4QkFBOEI7SUFDNUMsT0FBTyw2RkFBNkYsQ0FBQTtBQUN0RyxDQUFDO0FBRUQsU0FBZ0Isa0NBQWtDO0lBQ2hELE9BQU8seUZBQXlGLENBQUE7QUFDbEcsQ0FBQztBQUVELFNBQWdCLG1DQUFtQztJQUNqRCxPQUFPLGtIQUFrSCxDQUFBO0FBQzNILENBQUM7QUFFRCxTQUFnQiw4QkFBOEIsQ0FDNUMsRUFBa0M7SUFFbEMsSUFBSSxDQUFDLEVBQUUsQ0FBQyxTQUFTLElBQUksRUFBRSxDQUFDLENBQUMsSUFBSSxFQUFFLEtBQUssUUFBUSxFQUFFLENBQUM7UUFDN0MsT0FBTyxLQUFLLENBQUE7SUFDZCxDQUFDO0lBQ0QsTUFBTSxLQUFLLEdBQUcsQ0FBQyxFQUFFLENBQUMsWUFBWSxJQUFJLEVBQUUsQ0FBQyxDQUFDLElBQUksRUFBRSxDQUFBO0lBQzVDLE9BQU8sZ0NBQWdDLENBQUMsSUFBSSxDQUFDLENBQUMsTUFBTSxFQUFFLEVBQUUsQ0FDdEQsS0FBSyxDQUFDLFVB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

package/README.md

@@ -245,7 +245,6 @@ curl "http://localhost:9000/admin/orders/order_123/refund-context" \
 | Swaps routes | `/swaps`, `/swaps/:id` | Exchange listing/detail pages | Search, filters, reject/cancel exchange; uses `/admin/swaps*`. |
 | Payments routes | `/payments`, `/payments/:id` | Transaction list + detail pages | Filter transactions and inspect gateway payload. |
 | Refunds routes | `/refunds`, `/refunds/:id` | Refund list + detail pages | Filter by status/provider/date/amount; view computed refund context. |
-| `order-refund-context-widget` | `order.details.after` | Refund context panel | Order checkout payment method (including guest orders), refund calculation (product amount, return charge, processed final refund), edit refund mode/details/images, upload images, mark refunded. |
 | `order-gift-items-widget` | `order.details.side.after` | Gift item widget | Reads gift metadata and downloads generated gift card image. |
 
 ## Models & Entities
@@ -271,6 +270,7 @@ curl "http://localhost:9000/admin/orders/order_123/refund-context" \
 | OTP request fails with template/config message | Missing `email.otpTemplate` or unresolved plugin options | Configure plugin options in `medusa-config.ts`; verify template path exists. |
 | Guest JWT endpoints return unauthorized | Invalid/expired token or `jwtSecret` mismatch | Re-run OTP verify and ensure same `jwtSecret` is used in runtime config. |
 | Store cancel returns generic `An error occurred` | Workflow failure was wrapped and not unwrapped by the cancel route | Upgrade this plugin. Nested Medusa/workflow errors are now unwrapped into a real `message`. Check payment refund/void logs if cancel still fails. |
+| Backend fails to start: `Package subpath './zod' is not defined` in `@medusajs/framework` | Validators imported `@medusajs/framework/zod`, which older framework builds do not export | Upgrade to `order-management` ≥ `0.0.95` (validators import `zod` directly). |
 | Cancel blocked by open fulfillments on a “not fulfilled” order | Core cancel requires all fulfillments to have `canceled_at` | Upgrade this plugin. Unshipped open fulfillments are canceled automatically before core cancel. |
 | Return/exchange blocked with `RETURN_WINDOW_EXPIRED` | Delivery date outside configured window | Increase `returnValidInDays`/`exchangeValidInDays` or update storefront UX for expiry handling. |
 | Refund mapping routes fail | `refund-payment-mapping` module not registered/migrated | Register module and run migrations. |
@@ -591,7 +591,7 @@ The plugin includes a `refund_payment_mapping` module: one row per return linkin
   - `PUT /admin/refund-payment-mapping/:return_id` — update admin-only fields. Body: `{ refund_mode?: "offline" | "online" | null, images?: string[], details?: string | null }` (partial; only provided keys are updated).
   - `POST /admin/refund-payment-mapping/:return_id/mark-refunded` — set `is_refunded = true` (idempotent). Requires Medusa return status `received`; otherwise `400 NOT_ALLOWED`. Already-refunded mappings still succeed without re-checking receive status.
 - **Receive-before-refund guard**: Middleware on Medusa core `POST /admin/payments/:id/refund` rejects the request with `400 NOT_ALLOWED` when the order has any return in `open`, `requested`, or `partially_received` (including exchange-linked returns). Message: `Cannot process a refund while the return is {status}. Receive the returned items first.` Orders with no return, or only `received` / `canceled` returns, are not blocked.
-- **Order detail integration**: `GET /admin/orders/:order_id/refund-context` — aggregated read returning `return_id`, `return_status`, `can_process_refund` (`true` only when status is `received` and the mapping exists and is not already refunded), `order_payment` (checkout `provider_id`, human-readable `label`, `is_cod` — used for guest orders that have no saved `payment_detail`), `refund_mapping` (id, payment_id, is_refunded, refund_mode, images, details), `payment_detail` (id, type, detail_json, is_default) resolved from the customer's specified or default payment detail, and `refund` (product_amount, return_charge, expected_net_amount, final_refund_amount, currency_code, is_processed, breakdown_matches, destination_label). `final_refund_amount` is the processed payment refund (or COD/offline `return.refund_amount` after mark-refunded), not `product_amount - return_charge`. Returns null blocks when no return or mapping exists. An admin widget at `order.details.after` shows **Order payment method** (the provider used at checkout, including guest orders), **Refund calculation**, refund payment method, **Refund mode** (Offline/Online), **Details**, **Images** (with upload via Medusa `POST /admin/uploads`), and **Mark refunded** only when `can_process_refund` is true. While the return is unreceived the widget tells admins to receive items first and not refund from Payments. Only admin can change refund_mode, images, and details.
+- **Order detail integration**: `GET /admin/orders/:order_id/refund-context` — aggregated read returning `return_id`, `return_status`, `can_process_refund` (`true` only when status is `received` and the mapping exists and is not already refunded), `order_payment` (checkout `provider_id`, human-readable `label`, `is_cod` — used for guest orders that have no saved `payment_detail`), `refund_mapping` (id, payment_id, is_refunded, refund_mode, images, details), `payment_detail` (id, type, detail_json, is_default) resolved from the customer's specified or default payment detail, and `refund` (product_amount, return_charge, expected_net_amount, final_refund_amount, currency_code, is_processed, breakdown_matches, destination_label). `final_refund_amount` is the processed payment refund (or COD/offline `return.refund_amount` after mark-refunded), not `product_amount - return_charge`. Returns null blocks when no return or mapping exists. Used by admin refund/return detail pages; refund_mode, images, and details are admin-only via the mapping APIs above.
 - **Store return payload**: `GET /store/returns` and `GET /store/returns/:id` attach the same `refund` object so the storefront can render the breakdown. `GET /store/orders/:order_id/refund-payment-mappings` includes `refund` per mapping.
 - **Registration**: Add the module in `medusa-config.js` (e.g. `orderManagement.modules["refund-payment-mapping"]`) and run migrations.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "order-management",
-  "version": "0.0.94",
+  "version": "0.0.96",
   "description": "A starter for Medusa plugins.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",
@@ -56,7 +56,8 @@
     "typescript": "^5.9.3",
     "vite": "^8.3.0",
     "vitest": "^5.0.1",
-    "yalc": "^1.0.0-pre.53"
+    "yalc": "^1.0.0-pre.53",
+    "zod": "4.2.0"
   },
   "peerDependencies": {
     "@medusajs/admin-sdk": "2.11.2",
@@ -66,7 +67,8 @@
     "@medusajs/medusa": "2.11.2",
     "@medusajs/test-utils": "2.11.2",
     "@medusajs/ui": "4.0.25",
-    "medusa-plugin-dynamic-config": ">=0.0.36"
+    "medusa-plugin-dynamic-config": ">=0.0.36",
+    "zod": ">=3.0.0"
   },
   "engines": {
     "node": ">=20"