chore(core-flows): update the TSDocs of new steps (#11315)

.changeset/forty-seas-begin.md

@@ -0,0 +1,5 @@
+---
+"@medusajs/core-flows": patch
+---
+
+chore(core-flows): update the TSDocs of new steps

packages/core/core-flows/src/cart/steps/validate-shipping.ts

@@ -8,12 +8,27 @@ import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
 import { MedusaError } from "../../../../utils/dist/common"
 
+/**
+ * The data to validate shipping data when cart is completed.
+ */
 export type ValidateShippingInput = {
+  /**
+   * The cart's details.
+   */
   cart: Omit<CartWorkflowDTO, "items"> & {
+    /**
+     * The cart's line items.
+     */
     items: (CartLineItemDTO & {
+      /**
+       * The item's variant.
+       */
       variant: ProductVariantDTO
     })[]
   }
+  /**
+   * The selected shipping options.
+   */
   shippingOptions: ShippingOptionDTO[]
 }
 
@@ -22,7 +37,39 @@ export const validateShippingStepId = "validate-shipping"
  * This step validates shipping data when cart is completed.
  *
  * It ensures that a shipping method is selected if there is an item in the cart that requires shipping.
- * It also ensures that product's shipping profile mathes the selected shipping options.
+ * It also ensures that product's shipping profile mathes the selected shipping options. If the
+ * conditions are not met, an error is thrown.
+ *
+ * :::note
+ *
+ * You can retrieve cart or shipping option's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ *
+ * :::
+ * 
+ * @example
+ * validateShippingStep({
+ *   cart: {
+ *     id: "cart_123",
+ *     items: [
+ *       {
+ *         id: "item_123",
+ *         variant: {
+ *           id: "variant_123",
+ *           // other item details...
+ *         },
+ *       }
+ *     ],
+ *     // other cart details...
+ *   },
+ *   shippingOptions: [
+ *     {
+ *       id: "option_123",
+ *       shipping_profile_id: "sp_123",
+ *       // other option details...
+ *     }
+ *   ]
+ * })
  */
 export const validateShippingStep = createStep(
   validateShippingStepId,

packages/core/core-flows/src/product/workflows/create-products.ts

@@ -46,7 +46,7 @@ export interface ValidateProductInputStepInput {
 const validateProductInputStepId = "validate-product-input"
 /**
  * This step validates that all provided products have options.
- * If a product is missing options, an error is thrown.
+ * If a product is missing options or a shipping profile, an error is thrown.
  *
  * @example
  * const data = validateProductInputStep({

packages/core/core-flows/src/shipping-profile/workflows/delete-shipping-profile.ts

@@ -9,11 +9,41 @@ import { deleteShippingProfilesStep } from "../steps"
 import { removeRemoteLinkStep, useQueryGraphStep } from "../../common"
 
 /**
- * This step validates that the shipping profiles to delete are not linked to any products.
+ * The data to validate the deletion of shipping profiles.
  */
-const validateStepShippingProfileDelete = createStep(
+export type ValidateStepShippingProfileDeleteInput = {
+  /**
+   * The links between products and shipping profiles.
+   */
+  links: { 
+    /**
+     * The ID of the product linked to the shipping profile.
+     */
+    product_id: string
+    /**
+     * The ID of the shipping profile to be deleted.
+     */
+    shipping_profile_id: string
+  }[]
+}
+
+/**
+ * This step validates that the shipping profiles to delete are not linked to any products.
+ * Otherwise, an error is thrown.
+ * 
+ * @example
+ * validateStepShippingProfileDelete({
+ *   links: [
+ *     {
+ *       product_id: "product_123",
+ *       shipping_profile_id: "sp_123"
+ *     }
+ *   ]
+ * })
+ */
+export const validateStepShippingProfileDelete = createStep(
   "validate-step-shipping-profile-delete",
-  (data: { links: { product_id: string; shipping_profile_id: string }[] }) => {
+  (data: ValidateStepShippingProfileDeleteInput ) => {
     const { links } = data
 
     if (links.length > 0) {