feat(core-flows,types): export fetchShippingOptionForOrderWorkflow (#12103)

* feat(core-flows,types): export fetchShippingOptionForOrderWorkflow

* revert change

* change to tsdoc

* fix errors

---------

Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>

.changeset/yellow-dancers-breathe.md

@@ -0,0 +1,6 @@
+---
+"@medusajs/core-flows": patch
+"@medusajs/types": patch
+---
+
+feat(core-flows,types): export fetchShippingOptionForOrderWorkflow

packages/core/core-flows/src/order/index.ts

@@ -1,2 +1,3 @@
 export * from "./steps"
 export * from "./workflows"
+export * from "./utils/fetch-shipping-option"

packages/core/core-flows/src/order/utils/fetch-shipping-option.ts

@@ -48,11 +48,11 @@ const COMMON_OPTIONS_FIELDS = [
  */
 export type FetchShippingOptionForOrderWorkflowInput = {
   /**
-   * The ID of the shipping option to create the shipping method from.
+   * The ID of the shipping option to fetch.
    */
   shipping_option_id: string
   /**
-   * The custom amount to create the shipping method with.
+   * The custom amount of the shipping option.
    * If not provided, the shipping option's amount is used.
    */
   custom_amount?: BigNumberInput | null
@@ -65,7 +65,7 @@ export type FetchShippingOptionForOrderWorkflowInput = {
    */
   order_id: string
   /**
-   * The context of the order.
+   * The context of the RMA flow, which can be useful for retrieving the shipping option's price.
    */
   context: CalculatedRMAShippingContext
 }
@@ -74,15 +74,87 @@ export type FetchShippingOptionForOrderWorkflowInput = {
  * The output of the fetch shipping option for order workflow.
  */
 export type FetchShippingOptionForOrderWorkflowOutput = ShippingOptionDTO & {
+  /**
+   * The shipping option's price.
+   */
   calculated_price: {
+    /**
+     * The shipping option's price based on its type and provided context.
+     */
     calculated_amount: BigNumber
+    /**
+     * Whether the amount includes taxes.
+     */
     is_calculated_price_tax_inclusive: boolean
   }
 }
-export const createOrderEditShippingMethodWorkflowId = "fetch-shipping-option"
+export const fetchShippingOptionsForOrderWorkflowId = "fetch-shipping-option"
 /**
- * This workflows fetches a shipping option for an order (used in RMA flows).
+ * This workflow fetches a shipping option for an order. It's used in Return Merchandise Authorization (RMA) flows. It's used
+ * by other workflows, such as {@link createClaimShippingMethodWorkflow}.
  *
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around fetching
+ * shipping options for an order.
+ * 
+ * @example
+ * const { result } = await fetchShippingOptionForOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     shipping_option_id: "so_123",
+ *     currency_code: "usd",
+ *     order_id: "order_123",
+ *     context: {
+ *       return_id: "ret_123",
+ *       return_items: [
+ *         {
+ *           id: "orli_123",
+ *           quantity: 1,
+ *         }
+ *       ]
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Fetch a shipping option for an order.
+ * 
+ * @property hooks.setPricingContext - This hook is executed before the shipping option is fetched. You can consume this hook to set the pricing context for the shipping option. This is useful when you have custom pricing rules that depend on the context of the order.
+ * 
+ * For example, assuming you have the following custom pricing rule:
+ * 
+ * ```json
+ * {
+ *   "attribute": "location_id",
+ *   "operator": "eq",
+ *   "value": "sloc_123",
+ * }
+ * ```
+ * 
+ * You can consume the `setPricingContext` hook to add the `location_id` context to the prices calculation:
+ * 
+ * ```ts
+ * import { fetchShippingOptionForOrderWorkflow } from "@medusajs/medusa/core-flows";
+ * import { StepResponse } from "@medusajs/workflows-sdk";
+ * 
+ * fetchShippingOptionForOrderWorkflow.hooks.setPricingContext((
+ *   { shipping_option_id, currency_code, order_id, context, additional_data }, { container }
+ * ) => {
+ *   return new StepResponse({
+ *     location_id: "sloc_123", // Special price for in-store purchases
+ *   });
+ * });
+ * ```
+ * 
+ * The shipping option's price will now be retrieved using the context you return.
+ * 
+ * :::note
+ * 
+ * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation.
+ * 
+ * :::
+ *
+ * @privateRemarks
  * There can be 3 cases:
  * 1. The shipping option is a flat rate shipping option.
  *    In this case, pricing calculation context is not used.
@@ -92,7 +164,7 @@ export const createOrderEditShippingMethodWorkflowId = "fetch-shipping-option"
  *    In this case, we don't need to do caluclations above and just return the shipping option with the custom amount.
  */
 export const fetchShippingOptionForOrderWorkflow = createWorkflow(
-  createOrderEditShippingMethodWorkflowId,
+  fetchShippingOptionsForOrderWorkflowId,
   function (input: FetchShippingOptionForOrderWorkflowInput & AdditionalData) {
     const initialOption = useRemoteQueryStep({
       entry_point: "shipping_option",

packages/core/types/src/fulfillment/mutations/shipping-option.ts

@@ -132,9 +132,36 @@ type CalculateShippingItems = {
 }
 
 export type CalculatedRMAShippingContext =
-  | { return_id: string; return_items: CalculateShippingItems[] }
-  | { exchange_id: string; exchange_items: CalculateShippingItems[] }
-  | { claim_id: string; claim_items: CalculateShippingItems[] }
+  | {
+    /**
+     * The ID of the return.
+     */ 
+    return_id: string
+    /**
+     * The details of the return's items.
+     */
+    return_items: CalculateShippingItems[]
+  }
+  | {
+    /**
+     * The ID of the exchange.
+     */
+    exchange_id: string
+    /**
+     * The details of the exchange's items.
+     */ 
+    exchange_items: CalculateShippingItems[]
+  }
+  | {
+    /**
+     * The ID of the claim.
+     */ 
+    claim_id: string
+    /**
+     * The details of the claim's items.
+     */
+    claim_items: CalculateShippingItems[]
+  }
 
 /**
  * The data needed for the associated fulfillment provider to calculate the price of a shipping option.