From 73ae136965e593f2a3f53e044b49021bb0587858 Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Mon, 1 Dec 2025 13:41:31 +0200
Subject: [PATCH] chore: improve and add TSDocs for next release (#14170)

---
 .../list-order-change-actions-by-type.ts      |  2 +
 .../compute-adjustments-for-preview.ts        | 16 ++++---
 .../workflows/on-carry-promotions-flag-set.ts | 44 ++++++++++++++++---
 .../order/workflows/update-order-change.ts    | 11 +++--
 .../modules/order/src/models/order-change.ts  |  3 ++
 .../modules/promotion/src/models/promotion.ts |  9 ++++
 6 files changed, 71 insertions(+), 14 deletions(-)

diff --git a/packages/core/core-flows/src/order/steps/list-order-change-actions-by-type.ts b/packages/core/core-flows/src/order/steps/list-order-change-actions-by-type.ts
index c58bb81c3e..90a6f6373c 100644
--- a/packages/core/core-flows/src/order/steps/list-order-change-actions-by-type.ts
+++ b/packages/core/core-flows/src/order/steps/list-order-change-actions-by-type.ts
@@ -4,6 +4,8 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 /**
  * This step lists order change actions filtered by action type.
+ * 
+ * @since v2.11.4
  */
 export const listOrderChangeActionsByTypeStep = createStep(
   "list-order-change-actions-by-type",
diff --git a/packages/core/core-flows/src/order/workflows/compute-adjustments-for-preview.ts b/packages/core/core-flows/src/order/workflows/compute-adjustments-for-preview.ts
index c8b11a77cb..9106cc8053 100644
--- a/packages/core/core-flows/src/order/workflows/compute-adjustments-for-preview.ts
+++ b/packages/core/core-flows/src/order/workflows/compute-adjustments-for-preview.ts
@@ -29,7 +29,12 @@ export type ComputeAdjustmentsForPreviewWorkflowInput = {
   /**
    * The order's details.
    */
-  order: OrderDTO & { promotions: PromotionDTO[] }
+  order: OrderDTO & { 
+    /**
+     * The promotions applied to the order.
+     */
+    promotions: PromotionDTO[]
+  }
   /**
    * The order change's details.
    */
@@ -42,13 +47,13 @@ export const computeAdjustmentsForPreviewWorkflowId =
  * This workflow computes adjustments for an order change if the carry over promotions flag is true on the order change.
  * If the flag is false, it deletes the existing adjustments replacement actions.
  *
- * It is currently used as a part of the order edit and exchange flows.
- * It's used by the [Add Items to Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditems),
- * [Add Outbound Items Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutbounditems),
- * and [Add Inbound Items Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidinbounditems).
+ * It is currently used as a part of the order edit and exchange flows. It's used by workflows
+ * like {@link orderExchangeAddNewItemWorkflow} and {@link orderEditAddNewItemWorkflow}.
  *
  * You can use this workflow within your customizations or your own custom workflows, allowing you to compute adjustments
  * in your custom flows.
+ * 
+ * @since v2.11.4
  *
  * @example
  * const { result } = await computeAdjustmentsForPreviewWorkflow(container)
@@ -62,7 +67,6 @@ export const computeAdjustmentsForPreviewWorkflowId =
  *       id: "orch_123",
  *       // other order change details...
  *     },
- *     exchange_id: "exchange_123", // optional, for exchanges
  *   }
  * })
  *
diff --git a/packages/core/core-flows/src/order/workflows/on-carry-promotions-flag-set.ts b/packages/core/core-flows/src/order/workflows/on-carry-promotions-flag-set.ts
index ccac690607..ca5712de51 100644
--- a/packages/core/core-flows/src/order/workflows/on-carry-promotions-flag-set.ts
+++ b/packages/core/core-flows/src/order/workflows/on-carry-promotions-flag-set.ts
@@ -34,7 +34,33 @@ export type OnCarryPromotionsFlagSetWorkflowInput = {
 }
 
 /**
- * This step validates that the order change is an exchange and validates promotion allocation.
+ * This step validates that the order change is an exchange and validates that
+ * the promotion allocation is valid for carrying over promotions.
+ *
+ * :::note
+ *
+ * You can retrieve details of the order and order change using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ *
+ * :::
+ * 
+ * @since v2.11.4
+ *
+ * @example
+ * const data = validateCarryPromotionsFlagStep({
+ *   order: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   orderChange: {
+ *     id: "orch_123",
+ *     // other order change details...
+ *   },
+ *   input: {
+ *     order_change_id: "orch_123",
+ *     carry_over_promotions: true,
+ *   }
+ * })
  */
 export const validateCarryPromotionsFlagStep = createStep(
   "validate-carry-promotions-flag",
@@ -114,9 +140,17 @@ export const validateCarryPromotionsFlagStep = createStep(
 export const onCarryPromotionsFlagSetId = "on-carry-promotions-flag-set"
 
 /**
- * This workflow sets the carry over promotions flag for an order change.
- * It validates that the order change is active and is an exchange, validates promotion allocation,
- * and either applies or removes promotion adjustments based on the flag value.
+ * This workflow toggles whether promotions are carried over to outbound items of an exchange.
+ * It validates that the order change is an exchange and that it's active. It also validates that the promotion allocation
+ * is valid for carrying over promotions. Finally, it computes adjustments for the order change
+ * and either applies or removes promotion adjustments based on whether promotions are to be carried over.
+ * 
+ * This workflow is used by other workflows, such as the {@link updateOrderChangeWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to 
+ * set the carry over promotions flag for an order change in your custom flows.
+ * 
+ * @since v2.11.4
  *
  * @example
  * const { result } = await onCarryPromotionsFlagSet(container)
@@ -129,7 +163,7 @@ export const onCarryPromotionsFlagSetId = "on-carry-promotions-flag-set"
  *
  * @summary
  *
- * Set the carry over promotions flag for an order change.
+ * Toggle carrying over promotions to outbound exchange items.
  */
 export const onCarryPromotionsFlagSet = createWorkflow(
   onCarryPromotionsFlagSetId,
diff --git a/packages/core/core-flows/src/order/workflows/update-order-change.ts b/packages/core/core-flows/src/order/workflows/update-order-change.ts
index 99b779533d..a48dd4aa5f 100644
--- a/packages/core/core-flows/src/order/workflows/update-order-change.ts
+++ b/packages/core/core-flows/src/order/workflows/update-order-change.ts
@@ -13,8 +13,13 @@ export const updateOrderChangeWorkflowId = "update-order-change-workflow"
 
 /**
  * This workflow updates an order change.
- * If the carry_over_promotions flag is provided, it calls onCarryPromotionsFlagSet
- * to handle the promotion logic. Otherwise, it updates the order change directly.
+ * If the `carry_over_promotions` flag is provided, it calls {@link onCarryPromotionsFlagSet}
+ * to handle the promotion update logic. Otherwise, it updates the order change directly.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
+ * updating an order change and conditionally handling promotion carry-over.
+ * 
+ * @since v2.11.4
  *
  * @example
  * const { result } = await updateOrderChangeWorkflow(container)
@@ -27,7 +32,7 @@ export const updateOrderChangeWorkflowId = "update-order-change-workflow"
  *
  * @summary
  *
- * Update an order change, conditionally handling promotion carry-over if specified.
+ * Update an order change.
  */
 export const updateOrderChangeWorkflow = createWorkflow(
   updateOrderChangeWorkflowId,
diff --git a/packages/modules/order/src/models/order-change.ts b/packages/modules/order/src/models/order-change.ts
index fda45c211e..64171af35c 100644
--- a/packages/modules/order/src/models/order-change.ts
+++ b/packages/modules/order/src/models/order-change.ts
@@ -27,6 +27,9 @@ const _OrderChange = model
     declined_at: model.dateTime().nullable(),
     canceled_by: model.text().nullable(),
     canceled_at: model.dateTime().nullable(),
+    /**
+     * @since v2.11.4
+     */
     carry_over_promotions: model.boolean().nullable(),
     order: model.belongsTo<() => typeof Order>(() => Order, {
       mappedBy: "changes",
diff --git a/packages/modules/promotion/src/models/promotion.ts b/packages/modules/promotion/src/models/promotion.ts
index ac1a0d80a0..5ee4d1331c 100644
--- a/packages/modules/promotion/src/models/promotion.ts
+++ b/packages/modules/promotion/src/models/promotion.ts
@@ -9,7 +9,13 @@ const Promotion = model
     code: model.text().searchable(),
     is_automatic: model.boolean().default(false),
     is_tax_inclusive: model.boolean().default(false),
+    /**
+     * @since v2.11.4
+     */
     limit: model.number().nullable(),
+    /**
+     * @since v2.11.4
+     */
     used: model.number().default(0),
     type: model.enum(PromotionUtils.PromotionType).index("IDX_promotion_type"),
     status: model
@@ -30,6 +36,9 @@ const Promotion = model
       pivotTable: "promotion_promotion_rule",
       mappedBy: "promotions",
     }),
+    /**
+     * @since v2.11.4
+     */
     metadata: model.json().nullable(),
   })
   .cascades({