order-management 0.0.82 → 0.0.83

package/.medusa/server/src/modules/order-rma-gate/service.js

@@ -0,0 +1,202 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@medusajs/framework/utils");
+const crypto_1 = require("crypto");
+const order_rma_gate_1 = __importDefault(require("./models/order-rma-gate"));
+const constants_1 = require("./constants");
+const stale_reclaim_1 = require("./stale-reclaim");
+function isUniqueViolation(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const e = error;
+    if (e.code === "23505") {
+        return true;
+    }
+    const msg = `${e.message ?? ""} ${e.name ?? ""}`.toLowerCase();
+    return msg.includes("unique") || msg.includes("duplicate");
+}
+function newGateId() {
+    return `orgate_${(0, crypto_1.randomUUID)().replace(/-/g, "")}`;
+}
+class OrderRmaGateModuleService extends (0, utils_1.MedusaService)({
+    OrderRmaGate: order_rma_gate_1.default,
+}) {
+    constructor(container) {
+        super(container);
+        this.manager_ = container.manager;
+    }
+    get moduleKey() {
+        return constants_1.ORDER_RMA_GATE_MODULE;
+    }
+    normalize(raw) {
+        if (!raw || typeof raw !== "object" || !("id" in raw) || !("order_id" in raw)) {
+            throw new Error("Invalid order_rma_gate data");
+        }
+        const row = raw;
+        const kind = row.kind === "exchange" ? "exchange" : "return";
+        return {
+            id: row.id,
+            order_id: row.order_id,
+            kind,
+            reference_id: row.reference_id ?? null,
+            created_at: new Date(row.created_at ?? new Date()),
+            updated_at: new Date(row.updated_at ?? new Date()),
+            deleted_at: row.deleted_at ? new Date(row.deleted_at) : null,
+        };
+    }
+    getKnex() {
+        const manager = this.manager_;
+        if (typeof manager.getKnex !== "function") {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, "EntityManager.getKnex is unavailable for order_rma_gate");
+        }
+        return manager.getKnex();
+    }
+    async getActiveByOrderId(orderId) {
+        const knex = this.getKnex();
+        const row = await knex("order_rma_gate")
+            .where({ order_id: orderId })
+            .whereNull("deleted_at")
+            .first();
+        return row ? this.normalize(row) : null;
+    }
+    /**
+     * Insert a gate for the order. On unique conflict, attempt atomic stale reclaim
+     * via SELECT … FOR UPDATE in a single transaction.
+     */
+    async acquire(orderId, kind, hasActiveMedusaRma, now = new Date()) {
+        const knex = this.getKnex();
+        const id = newGateId();
+        const stamp = now;
+        try {
+            await knex("order_rma_gate").insert({
+                id,
+                order_id: orderId,
+                kind,
+                reference_id: null,
+                created_at: stamp,
+                updated_at: stamp,
+                deleted_at: null,
+            });
+            const gate = await this.getActiveByOrderId(orderId);
+            if (!gate) {
+                throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, "Gate insert succeeded but row not found");
+            }
+            return { ok: true, gate };
+        }
+        catch (error) {
+            if (!isUniqueViolation(error)) {
+                throw error;
+            }
+            return this.reclaimStaleOrConflict(orderId, kind, hasActiveMedusaRma, now);
+        }
+    }
+    /**
+     * Atomic reclaim: lock existing live gate, evaluate staleness, soft-delete + insert
+     * in the same transaction so concurrent reclaimers cannot both win.
+     */
+    async reclaimStaleOrConflict(orderId, kind, hasActiveMedusaRma, now) {
+        const knex = this.getKnex();
+        const conflictMessage = "This order already has an active return or exchange in progress. Cancel or complete the existing one before creating a new request.";
+        return knex.transaction(async (trx) => {
+            const locked = await trx("order_rma_gate")
+                .where({ order_id: orderId })
+                .whereNull("deleted_at")
+                .forUpdate()
+                .first();
+            if (!locked) {
+                // Previous holder released between unique violation and lock — insert fresh
+                const id = newGateId();
+                await trx("order_rma_gate").insert({
+                    id,
+                    order_id: orderId,
+                    kind,
+                    reference_id: null,
+                    created_at: now,
+                    updated_at: now,
+                    deleted_at: null,
+                });
+                return {
+                    ok: true,
+                    gate: this.normalize({
+                        id,
+                        order_id: orderId,
+                        kind,
+                        reference_id: null,
+                        created_at: now,
+                        updated_at: now,
+                        deleted_at: null,
+                    }),
+                };
+            }
+            const existing = this.normalize(locked);
+            const medusaActive = await hasActiveMedusaRma();
+            const decision = (0, stale_reclaim_1.evaluateStaleGateReclaim)({
+                gateCreatedAt: existing.created_at,
+                referenceId: existing.reference_id,
+                hasActiveMedusaRma: medusaActive,
+                now,
+                staleTtlMs: constants_1.STALE_GATE_TTL_MS,
+            });
+            if (decision !== "reclaim") {
+                return { ok: false, message: conflictMessage, type: "NOT_ALLOWED" };
+            }
+            await trx("order_rma_gate")
+                .where({ id: existing.id })
+                .update({
+                deleted_at: now,
+                updated_at: now,
+            });
+            const newId = newGateId();
+            await trx("order_rma_gate").insert({
+                id: newId,
+                order_id: orderId,
+                kind,
+                reference_id: null,
+                created_at: now,
+                updated_at: now,
+                deleted_at: null,
+            });
+            return {
+                ok: true,
+                gate: this.normalize({
+                    id: newId,
+                    order_id: orderId,
+                    kind,
+                    reference_id: null,
+                    created_at: now,
+                    updated_at: now,
+                    deleted_at: null,
+                }),
+            };
+        });
+    }
+    async release(orderId) {
+        const knex = this.getKnex();
+        const now = new Date();
+        await knex("order_rma_gate")
+            .where({ order_id: orderId })
+            .whereNull("deleted_at")
+            .update({
+            deleted_at: now,
+            updated_at: now,
+        });
+    }
+    async setReference(orderId, referenceId) {
+        const knex = this.getKnex();
+        const now = new Date();
+        await knex("order_rma_gate")
+            .where({ order_id: orderId })
+            .whereNull("deleted_at")
+            .update({
+            reference_id: referenceId,
+            updated_at: now,
+        });
+        return this.getActiveByOrderId(orderId);
+    }
+}
+exports.default = OrderRmaGateModuleService;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uLy4uL3NyYy9tb2R1bGVzL29yZGVyLXJtYS1nYXRlL3NlcnZpY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUFBQSxxREFBc0U7QUFFdEUsbUNBQW1DO0FBQ25DLDZFQUFrRDtBQUNsRCwyQ0FJb0I7QUFFcEIsbURBR3dCO0FBd0J4QixTQUFTLGlCQUFpQixDQUFDLEtBQWM7SUFDdkMsSUFBSSxDQUFDLEtBQUssSUFBSSxPQUFPLEtBQUssS0FBSyxRQUFRLEVBQUUsQ0FBQztRQUN4QyxPQUFPLEtBQUssQ0FBQTtJQUNkLENBQUM7SUFDRCxNQUFNLENBQUMsR0FBRyxLQUEyRCxDQUFBO0lBQ3JFLElBQUksQ0FBQyxDQUFDLElBQUksS0FBSyxPQUFPLEVBQUUsQ0FBQztRQUN2QixPQUFPLElBQUksQ0FBQTtJQUNiLENBQUM7SUFDRCxNQUFNLEdBQUcsR0FBRyxHQUFHLENBQUMsQ0FBQyxPQUFPLElBQUksRUFBRSxJQUFJLENBQUMsQ0FBQyxJQUFJLElBQUksRUFBRSxFQUFFLENBQUMsV0FBVyxFQUFFLENBQUE7SUFDOUQsT0FBTyxHQUFHLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQyxJQUFJLEdBQUcsQ0FBQyxRQUFRLENBQUMsV0FBVyxDQUFDLENBQUE7QUFDNUQsQ0FBQztBQUVELFNBQVMsU0FBUztJQUNoQixPQUFPLFVBQVUsSUFBQSxtQkFBVSxHQUFFLENBQUMsT0FBTyxDQUFDLElBQUksRUFBRSxFQUFFLENBQUMsRUFBRSxDQUFBO0FBQ25ELENBQUM7QUFFRCxNQUFxQix5QkFBMEIsU0FBUSxJQUFBLHFCQUFhLEVBQUM7SUFDbkUsWUFBWSxFQUFaLHdCQUFZO0NBQ2IsQ0FBQztJQUdBLFlBQVksU0FBK0I7UUFDekMsS0FBSyxDQUFDLFNBQVMsQ0FBQyxDQUFBO1FBQ2hCLElBQUksQ0FBQyxRQUFRLEdBQUcsU0FBUyxDQUFDLE9BQU8sQ0FBQTtJQUNu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

package/.medusa/server/src/modules/order-rma-gate/stale-reclaim.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateStaleGateReclaim = evaluateStaleGateReclaim;
+function evaluateStaleGateReclaim(input) {
+    if (input.hasActiveMedusaRma) {
+        return "conflict";
+    }
+    const ageMs = input.now.getTime() - input.gateCreatedAt.getTime();
+    if (input.referenceId == null || input.referenceId === "") {
+        if (ageMs >= input.staleTtlMs) {
+            return "reclaim";
+        }
+        return "conflict";
+    }
+    // reference_id set but Medusa reports no active RMA → orphan / terminal entity
+    return "reclaim";
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RhbGUtcmVjbGFpbS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uLy4uL3NyYy9tb2R1bGVzL29yZGVyLXJtYS1nYXRlL3N0YWxlLXJlY2xhaW0udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFhQSw0REFrQkM7QUFsQkQsU0FBZ0Isd0JBQXdCLENBQ3RDLEtBQW9DO0lBRXBDLElBQUksS0FBSyxDQUFDLGtCQUFrQixFQUFFLENBQUM7UUFDN0IsT0FBTyxVQUFVLENBQUE7SUFDbkIsQ0FBQztJQUVELE1BQU0sS0FBSyxHQUFHLEtBQUssQ0FBQyxHQUFHLENBQUMsT0FBTyxFQUFFLEdBQUcsS0FBSyxDQUFDLGFBQWEsQ0FBQyxPQUFPLEVBQUUsQ0FBQTtJQUVqRSxJQUFJLEtBQUssQ0FBQyxXQUFXLElBQUksSUFBSSxJQUFJLEtBQUssQ0FBQyxXQUFXLEtBQUssRUFBRSxFQUFFLENBQUM7UUFDMUQsSUFBSSxLQUFLLElBQUksS0FBSyxDQUFDLFVBQVUsRUFBRSxDQUFDO1lBQzlCLE9BQU8sU0FBUyxDQUFBO1FBQ2xCLENBQUM7UUFDRCxPQUFPLFVBQVUsQ0FBQTtJQUNuQixDQUFDO0lBRUQsK0VBQStFO0lBQy9FLE9BQU8sU0FBUyxDQUFBO0FBQ2xCLENBQUMifQ==

package/.medusa/server/src/modules/order-rma-gate/types.js

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

package/.medusa/server/src/subscribers/order-return-received.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.default = orderReturnReceivedHandler;
+const utils_1 = require("@medusajs/framework/utils");
+const return_exchange_guard_1 = require("../helpers/return-exchange-guard");
+/**
+ * Unlock the order RMA gate when a return is actually received.
+ *
+ * Note: older Medusa `createAndCompleteReturnOrderWorkflow` may emit
+ * `order.return_received` even when `receive_now` is false. We only release
+ * when the return entity status is `received`.
+ */
+async function orderReturnReceivedHandler({ event, container, }) {
+    const data = event.data ?? {};
+    const returnId = data.return_id ?? data.id;
+    try {
+        const orderModule = container.resolve(utils_1.Modules.ORDER);
+        let orderId = data.order_id;
+        let status;
+        if (returnId) {
+            const ret = await orderModule.retrieveReturn(returnId).catch(() => null);
+            if (!ret) {
+                return;
+            }
+            orderId = orderId ?? ret.order_id;
+            status = ret.status;
+        }
+        if (!orderId) {
+            return;
+        }
+        // Only unlock on true received status (not spurious REQUESTED-time emits)
+        if (status !== "received") {
+            return;
+        }
+        await (0, return_exchange_guard_1.releaseOrderRmaGate)(orderId, container);
+    }
+    catch (error) {
+        console.error(`[order.return_received] Failed to release RMA gate:`, error);
+    }
+}
+exports.config = {
+    event: "order.return_received",
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib3JkZXItcmV0dXJuLXJlY2VpdmVkLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3N1YnNjcmliZXJzL29yZGVyLXJldHVybi1yZWNlaXZlZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFrQkEsNkNBcUNDO0FBdERELHFEQUFtRDtBQUVuRCw0RUFBc0U7QUFRdEU7Ozs7OztHQU1HO0FBQ1ksS0FBSyxVQUFVLDBCQUEwQixDQUFDLEVBQ3ZELEtBQUssRUFDTCxTQUFTLEdBQytCO0lBQ3hDLE1BQU0sSUFBSSxHQUFHLEtBQUssQ0FBQyxJQUFJLElBQUksRUFBRSxDQUFBO0lBQzdCLE1BQU0sUUFBUSxHQUFHLElBQUksQ0FBQyxTQUFTLElBQUksSUFBSSxDQUFDLEVBQUUsQ0FBQTtJQUUxQyxJQUFJLENBQUM7UUFDSCxNQUFNLFdBQVcsR0FBRyxTQUFTLENBQUMsT0FBTyxDQUFzQixlQUFPLENBQUMsS0FBSyxDQUFDLENBQUE7UUFDekUsSUFBSSxPQUFPLEdBQUcsSUFBSSxDQUFDLFFBQVEsQ0FBQTtRQUMzQixJQUFJLE1BQTBCLENBQUE7UUFFOUIsSUFBSSxRQUFRLEVBQUUsQ0FBQztZQUNiLE1BQU0sR0FBRyxHQUFHLE1BQU0sV0FBVyxDQUFDLGNBQWMsQ0FBQyxRQUFRLENBQUMsQ0FBQyxLQUFLLENBQUMsR0FBRyxFQUFFLENBQUMsSUFBSSxDQUFDLENBQUE7WUFDeEUsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDO2dCQUNULE9BQU07WUFDUixDQUFDO1lBQ0QsT0FBTyxHQUFHLE9BQU8sSUFBSSxHQUFHLENBQUMsUUFBUSxDQUFBO1lBQ2pDLE1BQU0sR0FBRyxHQUFHLENBQUMsTUFBTSxDQUFBO1FBQ3JCLENBQUM7UUFFRCxJQUFJLENBQUMsT0FBTyxFQUFFLENBQUM7WUFDYixPQUFNO1FBQ1IsQ0FBQztRQUVELDBFQUEwRTtRQUMxRSxJQUFJLE1BQU0sS0FBSyxVQUFVLEVBQUUsQ0FBQztZQUMxQixPQUFNO1FBQ1IsQ0FBQztRQUVELE1BQU0sSUFBQSwyQ0FBbUIsRUFBQyxPQUFPLEVBQUUsU0FBUyxDQUFDLENBQUE7SUFDL0MsQ0FBQztJQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7UUFDZixPQUFPLENBQUMsS0FBSyxDQUNYLHFEQUFxRCxFQUNyRCxLQUFLLENBQ04sQ0FBQTtJQUNILENBQUM7QUFDSCxDQUFDO0FBRVksUUFBQSxNQUFNLEdBQXFCO0lBQ3RDLEtBQUssRUFBRSx1QkFBdUI7Q0FDL0IsQ0FBQSJ9

package/README.md

@@ -321,6 +321,7 @@ This plugin is compatible with Medusa v2 (e.g. `@medusajs/framework` and `@medus
 - **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 / Exchange Delivery Window**: Configurable per-type windows (`returnValidInDays`, `exchangeValidInDays`) that block return or exchange requests submitted after N days from the fulfillment's `delivered_at` timestamp. Defaults to 7 days each if not configured. The window is checked only when the order has been marked as delivered; undelivered orders are unaffected.
+- **Return / Exchange mutual exclusion**: Order-level lock via `order_rma_gate` — an active return blocks creating an exchange (and a second return), and vice versa. Same helper on store and guest create routes. Gate uses a partial unique index on `order_id` and atomic stale reclaim (`SELECT … FOR UPDATE`). Unlock on cancel/reject or when return status is actually `received`.
 - **Return Orders Admin Panel**: Admin UI and API for return orders (list, filter, search, detail, reject); returns are stored in the Medusa ORDER module and created via `createAndCompleteReturnOrderWorkflow`
 - **Exchanges Admin Panel**: Admin UI and API for exchanges (list, detail, reject, cancel); exchanges are ORDER module order changes (type `exchange`) created by customers via Medusa core workflows (`beginExchangeOrderWorkflow`, etc.)
 - **Medusa workflows**: Customer returns use `createAndCompleteReturnOrderWorkflow`; customer exchanges use `beginExchangeOrderWorkflow`, `orderExchangeRequestItemReturnWorkflow`, `orderExchangeAddNewItemWorkflow`, `confirmExchangeRequestWorkflow`, and `cancelBeginOrderExchangeWorkflow`. Admin actions use `confirmReturnReceiveWorkflow`, `cancelReturnWorkflow`, and `cancelBeginOrderExchangeWorkflow`.
@@ -334,8 +335,8 @@ This plugin is compatible with Medusa v2 (e.g. `@medusajs/framework` and `@medus
 | **Store (authenticated)** | `/store/orders/cancel|reorder/:id`, `/store/returns`, `/store/swaps`, `/store/payment-details`, `/store/refund-payment-mapping/:return_id`, `/store/orders/:order_id/refund-payment-mappings` |
 | **Store (guest)** | `/store/otp/request|verify`, `/store/guest-orders`, `/store/guest-orders/:id/returns|cancel|reorder|swaps` |
 | **Admin** | `/admin/returns`, `/admin/swaps`, `/admin/refund-payment-mapping/:return_id`, `/admin/refund-payment-mapping/:return_id/mark-refunded`, `/admin/orders/:order_id/refund-context` |
-| **Modules** | `payment_detail`, `refund_payment_mapping`; returns/exchanges use Medusa ORDER module |
-| **Subscribers** | Order confirmation email, status notifications, return/swap event sync |
+| **Modules** | `payment_detail`, `refund_payment_mapping`, `order_rma_gate`; returns/exchanges use Medusa ORDER module |
+| **Subscribers** | Order confirmation email, status notifications, return/swap event sync, `order.return_received` RMA gate release |
 
 ### Important APIs (quick reference)
 
@@ -632,7 +633,9 @@ Status updates are tracked in the return's metadata with timestamps and admin us
 
 ### One active return or exchange per item (Medusa v2)
 
-Medusa v2 does **not** allow multiple active return/exchange requests for the same order item at the same time. Once an item is part of a return or a swap (exchange), that quantity is reserved until the request is completed or canceled. Duplicate requests for the same quantity will fail validation (prevents double refunds / double fulfillment).
+**Active standalone return** = `status ∈ {open, requested, partially_received}` and no `exchange_id`.
+
+Medusa v2 does **not** allow multiple active return/exchange requests for the **same order item** at the same time. Once an item is part of a return or a swap (exchange), that quantity is reserved until the request is completed or canceled. This plugin also enforces **order-level** mutual exclusion via `order_rma_gate` (see Eligibility and Validation).
 
 **To allow a new request**, the first one must be closed or canceled:
 
@@ -1449,7 +1452,13 @@ Returns are validated for:
 - **Default Payment Method**: Customer must have a default payment method before creating a return
 - **Delivery Window**: Return is blocked if more than `returnValidInDays` days have passed since `fulfillment.delivered_at`. If the fulfillment has no `delivered_at` the check is skipped. Configure in plugin options (default: 7 days)
 - **Exchange Window**: Exchange is blocked if more than `exchangeValidInDays` days have passed since `fulfillment.delivered_at` (default: 7 days)
-- **Duplicate Prevention**: Cannot create a new return or exchange while one is already pending or requested for the same order
+- **Mutual exclusion (order-level)**: While any **active** return or exchange exists on the order, neither a second return nor a cross-type request may be created (intentional: one open RMA per order). Active return statuses are `open` | `requested` | `partially_received` (not `received` / `canceled`). Exchange-linked returns do not count as standalone refund returns. Enforced by:
+  - Medusa entity allowlists (`assertNoActiveConflictingRma`)
+  - `order_rma_gate` row with `UNIQUE (order_id) WHERE deleted_at IS NULL` (race-safe create)
+  - Atomic stale reclaim with `SELECT … FOR UPDATE` when a gate is abandoned (default TTL `STALE_GATE_TTL_MS` = 15 minutes; tune if crash-recovery timing requires it)
+  - Release on store/guest/admin cancel+reject, and on `order.return_received` only when return `status === "received"`
+  - Create workflow failure releases the gate (compensation)
+  - **Retry UX (v1):** a client retry of a successful create may get `400 NOT_ALLOWED` while the gate is held — check the order for an existing return/exchange before escalating support tickets
 
 ### Helper Functions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "order-management",
-  "version": "0.0.82",
+  "version": "0.0.83",
   "description": "A starter for Medusa plugins.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",
@@ -30,6 +30,8 @@
   "scripts": {
     "build": "medusa plugin:build",
     "dev": "medusa plugin:develop",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "medusa plugin:build"
   },
   "devDependencies": {
@@ -46,7 +48,7 @@
     "@types/react": "^18.3.2",
     "@types/react-dom": "^18.2.25",
     "jsonwebtoken": "^9.0.3",
-    "medusa-plugin-dynamic-config": "^0.0.36",
+    "medusa-plugin-dynamic-config": "0.0.36",
     "prop-types": "^15.8.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",