chore(core-flows,types): improve tsdocs of fulfillment (#10995)

packages/core/core-flows/src/fulfillment/steps/add-shipping-options-prices.ts

@@ -8,23 +8,73 @@ import {
 import { isString, Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to create price sets for a currency code.
+ */
 export interface ShippingOptionsPriceCurrencyCode {
+  /**
+   * The currency code of the price.
+   * 
+   * @example
+   * usd
+   */
   currency_code: string
+  /**
+   * The amount of the price.
+   */
   amount: number
+  /**
+   * The rules of the price.
+   */
   rules?: PriceRule[]
 }
 
+/**
+ * The data to create price sets for a region ID.
+ */
 interface ShippingOptionsPriceRegionId {
+  /**
+   * The ID of the region that this price applies in.
+   */
   region_id: string
+  /**
+   * The amount of the price.
+   */
   amount: number
+  /**
+   * The rules of the price.
+   */
   rules?: PriceRule[]
 }
 
+/**
+ * The data to create price sets for shipping options.
+ */
 export type CreateShippingOptionsPriceSetsStepInput = {
+  /**
+   * The ID of the shipping option.
+   */
   id: string
+  /**
+   * The prices to create for the shipping option.
+   */
   prices: (ShippingOptionsPriceCurrencyCode | ShippingOptionsPriceRegionId)[]
 }[]
 
+/**
+ * The result of creating price sets for shipping options.
+ */
+export type CreateShippingOptionsPriceSetsStepOutput = {
+  /**
+   * The ID of the shipping option.
+   */
+  id: string
+  /**
+   * The ID of the price set.
+   */
+  priceSetId: string
+}[]
+
 export function buildPriceSet(
   prices: CreateShippingOptionsPriceSetsStepInput[0]["prices"],
   regionToCurrencyMap: Map<string, string>
@@ -126,7 +176,7 @@ export const createShippingOptionsPriceSetsStep = createStep(
         id: input.id,
         priceSetId: priceSets[index].id,
       }
-    })
+    }) as CreateShippingOptionsPriceSetsStepOutput
 
     return new StepResponse(
       shippingOptionPriceSetLinData,

packages/core/core-flows/src/fulfillment/steps/calculate-shipping-options-prices.ts

@@ -5,14 +5,39 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to calculate the prices for one or more shipping options.
+ */
+export type CalculateShippingOptionsPriceStepInput = CalculateShippingOptionPriceDTO[]
+
 export const calculateShippingOptionsPricesStepId =
   "calculate-shipping-options-prices"
 /**
  * This step calculates the prices for one or more shipping options.
+ * 
+ * @example
+ * const data = calculateShippingOptionsPricesStep([{
+ *   id: "so_123",
+ *   provider_id: "provider_123",
+ *   optionData: {
+ *     // custom data relevant for the fulfillment provider
+ *     carrier_code: "UPS",
+ *   },
+ *   data: {
+ *     // custom data relevant for the fulfillment provider
+ *     // specific to the cart using this shipping option
+ *   },
+ *   context: {
+ *     from_location: {
+ *       id: "sloc_123",
+ *       // other location fields
+ *     }
+ *   }
+ * }])
  */
 export const calculateShippingOptionsPricesStep = createStep(
   calculateShippingOptionsPricesStepId,
-  async (input: CalculateShippingOptionPriceDTO[], { container }) => {
+  async (input: CalculateShippingOptionsPriceStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       Modules.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/cancel-fulfillment.ts

@@ -2,13 +2,18 @@ import { IFulfillmentModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The ID of the fulfillment to cancel.
+ */
+export type CancelFulfillmentStepInput = string
+
 export const cancelFulfillmentStepId = "cancel-fulfillment"
 /**
  * This step cancels a fulfillment.
  */
 export const cancelFulfillmentStep = createStep(
   cancelFulfillmentStepId,
-  async (id: string, { container }) => {
+  async (id: CancelFulfillmentStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       Modules.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/create-fulfillment-set.ts

@@ -5,13 +5,18 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to create one or more fulfillment sets.
+ */
+export type CreateFulfillmentSetsStepInput = CreateFulfillmentSetDTO[]
+
 export const createFulfillmentSetsId = "create-fulfillment-sets"
 /**
  * This step creates one or more fulfillment sets.
  */
 export const createFulfillmentSets = createStep(
   createFulfillmentSetsId,
-  async (data: CreateFulfillmentSetDTO[], { container }) => {
+  async (data: CreateFulfillmentSetsStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       Modules.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/create-fulfillment.ts

@@ -7,7 +7,30 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 export const createFulfillmentStepId = "create-fulfillment"
 /**
- * This step creates a fulfillment
+ * This step creates a fulfillment.
+ * 
+ * @example
+ * const data = createFulfillmentStep({
+ *   location_id: "sloc_123",
+ *   provider_id: "provider_123",
+ *   delivery_address: {
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     address_1: "Test Street 1",
+ *     city: "Test City",
+ *     postal_code: "12345",
+ *     country_code: "US",
+ *     phone: "123456789",
+ *   },
+ *   items: [
+ *     {
+ *       title: "Shirt",
+ *       sku: "shirt",
+ *       quantity: 1,
+ *       barcode: "123456789",
+ *     }
+ *   ]
+ * })
  */
 export const createFulfillmentStep = createStep(
   createFulfillmentStepId,

packages/core/core-flows/src/fulfillment/steps/create-return-fulfillment.ts

@@ -8,6 +8,29 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createReturnFulfillmentStepId = "create-return-fulfillment"
 /**
  * This step creates a fulfillment for a return.
+ * 
+ * @example
+ * const data = createReturnFulfillmentStep({
+ *   location_id: "sloc_123",
+ *   provider_id: "provider_123",
+ *   delivery_address: {
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     address_1: "Test Street 1",
+ *     city: "Test City",
+ *     postal_code: "12345",
+ *     country_code: "US",
+ *     phone: "123456789",
+ *   },
+ *   items: [
+ *     {
+ *       title: "Shirt",
+ *       sku: "shirt",
+ *       quantity: 1,
+ *       barcode: "123456789",
+ *     }
+ *   ]
+ * })
  */
 export const createReturnFulfillmentStep = createStep(
   createReturnFulfillmentStepId,

packages/core/core-flows/src/fulfillment/steps/create-service-zones.ts

@@ -5,13 +5,18 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The service zones to create.
+ */
+export type CreateServiceZonesStepInput = CreateServiceZoneDTO[]
+
 export const createServiceZonesStepId = "create-service-zones"
 /**
  * This step creates one or more service zones.
  */
 export const createServiceZonesStep = createStep(
   createServiceZonesStepId,
-  async (input: CreateServiceZoneDTO[], { container }) => {
+  async (input: CreateServiceZonesStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       Modules.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/create-shipping-profiles.ts

@@ -5,13 +5,18 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The shipping profiles to create.
+ */
+export type CreateShippingProfilesStepInput = CreateShippingProfileDTO[]
+
 export const createShippingProfilesStepId = "create-shipping-profiles"
 /**
  * This step creates one or more shipping profiles.
  */
 export const createShippingProfilesStep = createStep(
   createShippingProfilesStepId,
-  async (input: CreateShippingProfileDTO[], { container }) => {
+  async (input: CreateShippingProfilesStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       Modules.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/delete-fulfillment-sets.ts

@@ -2,13 +2,18 @@ import { IFulfillmentModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the fulfillment sets to delete.
+ */
+export type DeleteFulfillmentSetsStepInput = string[]
+
 export const deleteFulfillmentSetsStepId = "delete-fulfillment-sets"
 /**
  * This step deletes one or more fulfillment sets.
  */
 export const deleteFulfillmentSetsStep = createStep(
   deleteFulfillmentSetsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteFulfillmentSetsStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       Modules.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/delete-service-zones.ts

@@ -2,13 +2,18 @@ import { IFulfillmentModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the service zones to delete.
+ */
+export type DeleteServiceZonesStepInput = string[]
+
 export const deleteServiceZonesStepId = "delete-service-zones"
 /**
  * This step deletes one or more service zones.
  */
 export const deleteServiceZonesStep = createStep(
   deleteServiceZonesStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteServiceZonesStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       Modules.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/delete-shipping-options.ts

@@ -3,13 +3,18 @@ import { IFulfillmentModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the shipping options to delete.
+ */
+export type DeleteShippingOptionsStepInput = string[]
+
 export const deleteShippingOptionsStepId = "delete-shipping-options-step"
 /**
  * This step deletes one or more shipping options.
  */
 export const deleteShippingOptionsStep = createStep(
   deleteShippingOptionsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteShippingOptionsStepInput, { container }) => {
     if (!ids?.length) {
       return
     }

packages/core/core-flows/src/fulfillment/steps/index.ts

@@ -16,3 +16,6 @@ export * from "./update-shipping-profiles"
 export * from "./upsert-shipping-options"
 export * from "./validate-shipment"
 export * from "./calculate-shipping-options-prices"
+export * from "./update-service-zones"
+export * from "./update-shipping-option-rules"
+export * from "./validate-shipping-option-prices"

packages/core/core-flows/src/fulfillment/steps/set-shipping-options-price-sets.ts

@@ -8,8 +8,17 @@ import {
   promiseAll,
 } from "@medusajs/framework/utils"
 
+/**
+ * The data to set the price sets of a shipping option.
+ */
 export type SetShippingOptionsPriceSetsStepInput = {
+  /**
+   * The ID of the shipping option.
+   */
   id: string
+  /**
+   * The IDs of the price sets of the shipping option.
+   */
   price_sets?: string[]
 }[]
 

packages/core/core-flows/src/fulfillment/steps/set-shipping-options-prices.ts

@@ -23,8 +23,17 @@ interface PriceRegionId {
   amount: number
 }
 
+/**
+ * The data to set the prices of a shipping option.
+ */
 export type SetShippingOptionsPricesStepInput = {
+  /**
+   * The ID of the shipping option.
+   */
   id: string
+  /**
+   * The prices of the shipping option.
+   */
   prices?: FulfillmentWorkflow.UpdateShippingOptionPriceRecord[]
 }[]
 
@@ -120,6 +129,19 @@ function buildPrices(
 export const setShippingOptionsPricesStepId = "set-shipping-options-prices-step"
 /**
  * This step sets the prices of one or more shipping options.
+ * 
+ * @example
+ * const data = setShippingOptionsPricesStep([
+ *   {
+ *     id: "so_123",
+ *     prices: [
+ *       {
+ *         amount: 1000,
+ *         currency_code: "usd",
+ *       }
+ *     ]
+ *   }
+ * ])
  */
 export const setShippingOptionsPricesStep = createStep(
   setShippingOptionsPricesStepId,

packages/core/core-flows/src/fulfillment/steps/update-fulfillment.ts

@@ -11,6 +11,12 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const updateFulfillmentStepId = "update-fulfillment"
 /**
  * This step updates a fulfillment.
+ * 
+ * @example
+ * const data = updateFulfillmentStep({
+ *   id: "ful_123",
+ *   delivered_at: new Date(),
+ * })
  */
 export const updateFulfillmentStep = createStep(
   updateFulfillmentStepId,

packages/core/core-flows/src/fulfillment/steps/update-service-zones.ts

@@ -11,6 +11,16 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const updateServiceZonesStepId = "update-service-zones"
 /**
  * This step updates service zones matching the specified filters.
+ * 
+ * @example
+ * const data = updateServiceZonesStep({
+ *   selector: {
+ *     id: "serzo_123"
+ *   },
+ *   update: {
+ *     name: "US",
+ *   }
+ * })
  */
 export const updateServiceZonesStep = createStep(
   updateServiceZonesStepId,

packages/core/core-flows/src/fulfillment/steps/update-shipping-option-rules.ts

@@ -9,6 +9,16 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const updateShippingOptionRulesStepId = "update-shipping-option-rules"
 /**
  * This step updates one or more shipping option rules.
+ * 
+ * @example
+ * const data = updateShippingOptionRulesStep({
+ *   data: [
+ *     {
+ *       id: "sor_123",
+ *       operator: "in"
+ *     }
+ *   ]
+ * })
  */
 export const updateShippingOptionRulesStep = createStep(
   updateShippingOptionRulesStepId,

packages/core/core-flows/src/fulfillment/steps/update-shipping-profiles.ts

@@ -9,14 +9,33 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to update a shipping profile.
+ */
 export type UpdateShippingProfilesStepInput = {
+  /**
+   * The data to update in the shipping profiles.
+   */
   update: UpdateShippingProfileDTO
+  /**
+   * The filters to select the shipping profiles to update.
+   */
   selector: FilterableShippingProfileProps
 }
 
 export const updateShippingProfilesStepId = "update-shipping-profiles"
 /**
  * This step updates shipping profiles matching the specified filters.
+ * 
+ * @example
+ * const data = updateShippingProfilesStep({
+ *   selector: {
+ *     id: "sp_123"
+ *   },
+ *   update: {
+ *     name: "Standard"
+ *   }
+ * })
  */
 export const updateShippingProfilesStep = createStep(
   updateShippingProfilesStepId,

packages/core/core-flows/src/fulfillment/steps/upsert-shipping-options.ts

@@ -11,6 +11,9 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to create or update shipping options.
+ */
 export type UpsertShippingOptionsStepInput = Omit<
   | FulfillmentWorkflow.CreateShippingOptionsWorkflowInput
   | FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput,

packages/core/core-flows/src/fulfillment/steps/validate-fulfillment-providers.ts

@@ -6,9 +6,21 @@ import {
 } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to validate fulfillment providers.
+ */
 export type FulfillmentProviderValidationWorkflowInput = {
+  /**
+   * The ID of the shipping option to validate.
+   */
   id?: string
+  /**
+   * The ID of the shipping option's service zone.
+   */
   service_zone_id?: string
+  /**
+   * The ID of the fulfillment provider to validate.
+   */
   provider_id?: string
 }
 
@@ -16,7 +28,8 @@ export const validateFulfillmentProvidersStepId =
   "validate-fulfillment-providers-step"
 /**
  * This step validates that the specified fulfillment providers are available in the
- * specified service zones.
+ * specified service zones. If the service zone or provider ID are not specified, or
+ * the provider is not available in the service zone, the step throws an error.
  */
 export const validateFulfillmentProvidersStep = createStep(
   validateFulfillmentProvidersStepId,

packages/core/core-flows/src/fulfillment/steps/validate-shipment.ts

@@ -2,13 +2,20 @@ import { IFulfillmentModuleService } from "@medusajs/framework/types"
 import { MedusaError, Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The ID of the shipment to validate.
+ */
+export type ValidateShipmentStepInput = string
+
 export const validateShipmentStepId = "validate-shipment"
 /**
  * This step validates that a shipment can be created for a fulfillment.
+ * If the shipment has already been created, the fulfillment has been canceled,
+ * or the fulfillment does not have a shipping option, the step throws an error.
  */
 export const validateShipmentStep = createStep(
   validateShipmentStepId,
-  async (id: string, { container }) => {
+  async (id: ValidateShipmentStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       Modules.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/validate-shipping-option-prices.ts

@@ -6,7 +6,10 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
-type OptionsInput = (
+/**
+ * The data to validate shipping option prices.
+ */
+export type ValidateShippingOptionPricesStepInput = (
   | FulfillmentWorkflow.CreateShippingOptionsWorkflowInput
   | FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput
 )[]
@@ -15,14 +18,32 @@ export const validateShippingOptionPricesStepId =
   "validate-shipping-option-prices"
 
 /**
- * Validate that shipping options can be crated based on provided price configuration.
+ * This step validates that shipping options can be created based on provided price configuration.
  *
  * For flat rate prices, it validates that regions exist for the shipping option prices.
  * For calculated prices, it validates with the fulfillment provider if the price can be calculated.
+ * 
+ * If not valid, the step throws an error.
+ * 
+ * @example
+ * const data = validateShippingOptionPricesStep([
+ *   {
+ *     name: "Standard Shipping",
+ *     service_zone_id: "serzo_123",
+ *     shipping_profile_id: "sp_123",
+ *     provider_id: "prov_123",
+ *     type: {
+ *       label: "Standard",
+ *       description: "Standard shipping",
+ *       code: "standard"
+ *     },
+ *     price_type: "calculated",
+ *   }
+ * ])
  */
 export const validateShippingOptionPricesStep = createStep(
   validateShippingOptionPricesStepId,
-  async (options: OptionsInput, { container }) => {
+  async (options: ValidateShippingOptionPricesStepInput, { container }) => {
     const fulfillmentModuleService = container.resolve(Modules.FULFILLMENT)
 
     const optionIds = options.map(
@@ -62,7 +83,7 @@ export const validateShippingOptionPricesStep = createStep(
 
     const flatRatePrices: FulfillmentWorkflow.UpdateShippingOptionPriceRecord[] =
       []
-    const calculatedOptions: OptionsInput = []
+    const calculatedOptions: ValidateShippingOptionPricesStepInput = []
 
     options.forEach((option) => {
       if (option.price_type === ShippingOptionPriceType.FLAT) {

packages/core/core-flows/src/fulfillment/workflows/batch-shipping-option-rules.ts

@@ -18,20 +18,66 @@ import {
 } from "../steps"
 import { updateShippingOptionRulesStep } from "../steps/update-shipping-option-rules"
 
+/**
+ * The data to manage the shipping option rules in bulk.
+ * 
+ * @property create - The shipping option rules to create.
+ * @property update - The shipping option rules to update.
+ * @property delete - The IDs of the shipping option rules to delete.
+ */
+export type BatchShippingOptionRulesInput = BatchWorkflowInput<
+  CreateShippingOptionRuleDTO,
+  UpdateShippingOptionRuleDTO
+>
+
+/**
+ * The result of managing the shipping option rules in bulk.
+ * 
+ * @property created - The shipping option rules that were created.
+ * @property updated - The shipping option rules that were updated.
+ * @property deleted - The IDs of the shipping option rules that were deleted.
+ */
+export type BatchShippingOptionRulesOutput = BatchWorkflowOutput<ShippingOptionRuleDTO>
+
 export const batchShippingOptionRulesWorkflowId = "batch-shipping-option-rules"
 /**
- * This workflow manages shipping option rules by creating, updating, or deleting them.
+ * This workflow manages shipping option rules allowing you to create, update, or delete them. It's used by the
+ * [Manage the Rules of Shipping Option Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptionsidrulesbatch).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to 
+ * manage shipping option rules within your custom flows.
+ * 
+ * @example
+ * const { result } = await batchShippingOptionRulesWorkflow(container)
+ * .run({
+ *   input: {
+ *     create: [
+ *       {
+ *         attribute: "customer_group",
+ *         value: "cusgrp_123",
+ *         operator: "eq",
+ *         shipping_option_id: "so_123"
+ *       }
+ *     ],
+ *     update: [
+ *       {
+ *         id: "sor_123",
+ *         operator: "in"
+ *       }
+ *     ],
+ *     delete: ["sor_321"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Manage shipping option rules.
  */
 export const batchShippingOptionRulesWorkflow = createWorkflow(
   batchShippingOptionRulesWorkflowId,
   (
-    input: WorkflowData<
+    input: WorkflowData<BatchShippingOptionRulesInput>
-      BatchWorkflowInput<
+  ): WorkflowResponse<BatchShippingOptionRulesOutput> => {
-        CreateShippingOptionRuleDTO,
-        UpdateShippingOptionRuleDTO
-      >
-    >
-  ): WorkflowResponse<BatchWorkflowOutput<ShippingOptionRuleDTO>> => {
     const actionInputs = transform({ input }, (data) => {
       const { create, update, delete: del } = data.input
       return {

packages/core/core-flows/src/fulfillment/workflows/calculate-shipping-options-prices.ts

@@ -12,7 +12,39 @@ import { cartFieldsForCalculateShippingOptionsPrices } from "../../cart/utils/fi
 export const calculateShippingOptionsPricesWorkflowId =
   "calculate-shipping-options-prices-workflow"
 /**
- * This workflow calculates the prices for one or more shipping options.
+ * This workflow calculates the prices for one or more shipping options in a cart. It's used by the
+ * [Calculate Shipping Option Price Store API Route](https://docs.medusajs.com/api/store#shipping-options_postshippingoptionsidcalculate).
+ * 
+ * :::note
+ * 
+ * Calculating shipping option prices may require sending requests to third-party fulfillment services.
+ * This depends on the implementation of the fulfillment provider associated with the shipping option.
+ * 
+ * :::
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * calculate the prices of shipping options within your custom flows.
+ * 
+ * @example
+ * const { result } = await calculateShippingOptionsPricesWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     shipping_options: [
+ *       {
+ *         id: "so_123",
+ *         data: {
+ *           // custom data relevant for the fulfillment provider
+ *           carrier_code: "ups",
+ *         }
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Calculate shipping option prices in a cart.
  */
 export const calculateShippingOptionsPricesWorkflow = createWorkflow(
   calculateShippingOptionsPricesWorkflowId,

packages/core/core-flows/src/fulfillment/workflows/cancel-fulfillment.ts

@@ -1,13 +1,39 @@
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { cancelFulfillmentStep } from "../steps"
 
+/**
+ * The data to cancel a fulfillment.
+ */
+export type CancelFulfillmentWorkflowInput = {
+  /**
+   * The ID of the fulfillment to cancel.
+   */
+  id: string
+}
+
 export const cancelFulfillmentWorkflowId = "cancel-fulfillment-workflow"
 /**
- * This workflow cancels a fulfillment.
+ * This workflow cancels a fulfillment. It's used by the
+ * [Cancel Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillmentsidcancel).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * cancel a fulfillment within your custom flows.
+ * 
+ * @example
+ * const { result } = await cancelFulfillmentWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "ful_123"
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel a fulfillment.
  */
 export const cancelFulfillmentWorkflow = createWorkflow(
   cancelFulfillmentWorkflowId,
-  (input: WorkflowData<{ id: string }>) => {
+  (input: WorkflowData<CancelFulfillmentWorkflowInput>) => {
     cancelFulfillmentStep(input.id)
   }
 )

packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts

@@ -14,7 +14,52 @@ import { useRemoteQueryStep } from "../../common"
 
 export const createFulfillmentWorkflowId = "create-fulfillment-workflow"
 /**
- * This workflow creates a fulfillment.
+ * This workflow creates a fulfillment, which can be used for an order, return, exchanges, and similar concepts.
+ * The workflow is used by the [Create Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillments).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * create a fulfillment within your custom flows.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order'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
+ * const { result } = await createFulfillmentWorkflow(container)
+ * .run({
+ *   input: {
+ *     location_id: "sloc_123",
+ *     provider_id: "provider_123",
+ *     delivery_address: {
+ *       first_name: "John",
+ *       last_name: "Doe",
+ *       address_1: "Test street 1",
+ *       city: "Stockholm",
+ *       country_code: "se",
+ *       postal_code: "12345",
+ *       phone: "123456789"
+ *     },
+ *     items: [
+ *       {
+ *         quantity: 1,
+ *         sku: "shirt",
+ *         title: "Shirt",
+ *         barcode: "123"
+ *       }
+ *     ],
+ *     order: {
+ *       id: "order_123"
+ *       // other order details...
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create a fulfillment.
  */
 export const createFulfillmentWorkflow = createWorkflow(
   createFulfillmentWorkflowId,

packages/core/core-flows/src/fulfillment/workflows/create-return-fulfillment.ts

@@ -15,7 +15,48 @@ import { useRemoteQueryStep } from "../../common"
 export const createReturnFulfillmentWorkflowId =
   "create-return-fulfillment-workflow"
 /**
- * This workflow creates a fulfillment for a return.
+ * This workflow creates a fulfillment for a return. It's used by other return-related workflows,
+ * such as {@link createAndCompleteReturnOrderWorkflow}.
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * create a fulfillment for a return within your custom flows.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order'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
+ * const { result } = await createReturnFulfillmentWorkflow(container)
+ * .run({
+ *   input: {
+ *     location_id: "sloc_123",
+ *     provider_id: "provider_123",
+ *     delivery_address: {
+ *       first_name: "John",
+ *       last_name: "Doe",
+ *       address_1: "Test street 1",
+ *       city: "Stockholm",
+ *       country_code: "se",
+ *       postal_code: "12345",
+ *       phone: "123456789"
+ *     },
+ *     items: [
+ *       {
+ *         quantity: 1,
+ *         sku: "shirt",
+ *         title: "Shirt",
+ *         barcode: "123"
+ *       }
+ *     ],
+ *     order: {
+ *       id: "order_123"
+ *       // other order details...
+ *     }
+ *   }
+ * })
  */
 export const createReturnFulfillmentWorkflow = createWorkflow(
   createReturnFulfillmentWorkflowId,

packages/core/core-flows/src/fulfillment/workflows/create-service-zones.ts

@@ -6,15 +6,47 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { createServiceZonesStep } from "../steps"
 
+/**
+ * The service zones to create.
+ */
+export type CreateServiceZonesWorkflowOutput = ServiceZoneDTO[]
+
 export const createServiceZonesWorkflowId = "create-service-zones-workflow"
 /**
- * This workflow creates one or more service zones.
+ * This workflow creates one or more service zones. It's used by the
+ * [Add Service Zone to Fulfillment Set Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_postfulfillmentsetsidservicezones).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * create service zones within your custom flows.
+ * 
+ * @example
+ * const { result } = await createServiceZonesWorkflow(container)
+ * .run({
+ *   input: {
+ *     data: [
+ *       {
+ *         name: "US",
+ *         fulfillment_set_id: "fuset_123",
+ *         geo_zones: [
+ *           {
+ *             type: "country",
+ *             country_code: "us",
+ *           }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more service zones.
  */
 export const createServiceZonesWorkflow = createWorkflow(
   createServiceZonesWorkflowId,
   (
     input: WorkflowData<FulfillmentWorkflow.CreateServiceZonesWorkflowInput>
-  ): WorkflowResponse<ServiceZoneDTO[]> => {
+  ): WorkflowResponse<CreateServiceZonesWorkflowOutput> => {
     return new WorkflowResponse(createServiceZonesStep(input.data))
   }
 )

packages/core/core-flows/src/fulfillment/workflows/create-shipment.ts

@@ -10,7 +10,30 @@ import { updateFulfillmentWorkflow } from "./update-fulfillment"
 
 export const createShipmentWorkflowId = "create-shipment-workflow"
 /**
- * This workflow creates shipments for a fulfillment.
+ * This workflow creates shipments for a fulfillment. It's used by the
+ * [Create Shipment Admin API Route](https://docs.medusajs.com/api/admin#fulfillments_postfulfillmentsidshipment).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * create shipments within your custom flows.
+ * 
+ * @example
+ * const { result } = await createShipmentWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "ful_123",
+ *     labels: [
+ *       {
+ *         tracking_url: "https://example.com",
+ *         tracking_number: "123",
+ *         label_url: "https://example.com"
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create a shipment for a fulfillment.
  */
 export const createShipmentWorkflow = createWorkflow(
   createShipmentWorkflowId,

packages/core/core-flows/src/fulfillment/workflows/create-shipping-options.ts

@@ -14,17 +14,85 @@ import { setShippingOptionsPriceSetsStep } from "../steps/set-shipping-options-p
 import { validateFulfillmentProvidersStep } from "../steps/validate-fulfillment-providers"
 import { validateShippingOptionPricesStep } from "../steps/validate-shipping-option-prices"
 
+/**
+ * The data to create the shipping options.
+ */
+export type CreateShippingOptionsWorkflowInput = FulfillmentWorkflow.CreateShippingOptionsWorkflowInput[]
+
 export const createShippingOptionsWorkflowId =
   "create-shipping-options-workflow"
 /**
- * This workflow creates one or more shipping options.
+ * This workflow creates one or more shipping options. It's used by the 
+ * [Create Shipping Option Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * create shipping options within your custom flows.
+ * 
+ * @example
+ * To calculate a shipping option with flat rate prices:
+ * 
+ * ```ts
+ * const { result } = await createShippingOptionsWorkflow(container)
+ * .run({
+ *   input: [
+ *     {
+ *       name: "Standard Shipping",
+ *       service_zone_id: "serzo_123",
+ *       shipping_profile_id: "sp_123",
+ *       provider_id: "prov_123",
+ *       type: {
+ *         label: "Standard",
+ *         description: "Standard shipping",
+ *         code: "standard"
+ *       },
+ *       price_type: "flat",
+ *       prices: [
+ *         {
+ *           amount: 500,
+ *           currency_code: "usd"
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * })
+ * ```
+ * 
+ * To calculate shipping option with calculated prices, set `price_type` to `calculated` and don't pass a `prices` array:
+ * 
+ * :::note
+ * 
+ * You can calculate the shipping option's price for a cart using the [calculateShippingOptionsPricesWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/calculateShippingOptionsPricesWorkflow).
+ * 
+ * :::
+ * 
+ * ```ts
+ * const { result } = await createShippingOptionsWorkflow(container)
+ * .run({
+ *   input: [
+ *     {
+ *       name: "Standard Shipping",
+ *       service_zone_id: "serzo_123",
+ *       shipping_profile_id: "sp_123",
+ *       provider_id: "prov_123",
+ *       type: {
+ *         label: "Standard",
+ *         description: "Standard shipping",
+ *         code: "standard"
+ *       },
+ *       price_type: "calculated",
+ *     }
+ *   ]
+ * })
+ * ```
+ * 
+ * @summary
+ * 
+ * Create shipping options.
  */
 export const createShippingOptionsWorkflow = createWorkflow(
   createShippingOptionsWorkflowId,
   (
-    input: WorkflowData<
+    input: WorkflowData<CreateShippingOptionsWorkflowInput>
-      FulfillmentWorkflow.CreateShippingOptionsWorkflowInput[]
-    >
   ): WorkflowResponse<FulfillmentWorkflow.CreateShippingOptionsWorkflowOutput> => {
     parallelize(
       validateFulfillmentProvidersStep(input),

packages/core/core-flows/src/fulfillment/workflows/create-shipping-profiles.ts

@@ -9,7 +9,28 @@ import { createShippingProfilesStep } from "../steps"
 export const createShippingProfilesWorkflowId =
   "create-shipping-profiles-workflow"
 /**
- * This workflow creates one or more shipping profiles.
+ * This workflow creates one or more shipping profiles. It's used by the
+ * [Create Shipping Profile Admin API Route](https://docs.medusajs.com/api/admin#shipping-profiles_postshippingprofiles).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * create shipping profiles within your custom flows.
+ * 
+ * @example
+ * const { result } = await createShippingProfilesWorkflow(container)
+ * .run({
+ *   input: {
+ *     data: [
+ *       {
+ *         name: "Standard",
+ *         type: "standard"
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more shipping profiles.
  */
 export const createShippingProfilesWorkflow = createWorkflow(
   createShippingProfilesWorkflowId,

packages/core/core-flows/src/fulfillment/workflows/delete-fulfillment-sets.ts

@@ -3,14 +3,40 @@ import { deleteFulfillmentSetsStep } from "../steps"
 import { removeRemoteLinkStep } from "../../common"
 import { Modules } from "@medusajs/framework/utils"
 
+/**
+ * The data to delete one or more fulfillment sets.
+ */
+export type DeleteFulfillmentSetsWorkflowInput = {
+  /**
+   * The IDs of the fulfillment sets to delete.
+   */
+  ids: string[]
+}
+
 export const deleteFulfillmentSetsWorkflowId =
   "delete-fulfillment-sets-workflow"
 /**
- * This workflow deletes one or more fulfillment sets.
+ * This workflow deletes one or more fulfillment sets. It's used by the
+ * [Delete Fulfillment Sets Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_deletefulfillmentsetsid).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * delete fulfillment sets within your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteFulfillmentSetsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["fulset_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more fulfillment sets.
  */
 export const deleteFulfillmentSetsWorkflow = createWorkflow(
   deleteFulfillmentSetsWorkflowId,
-  (input: WorkflowData<{ ids: string[] }>) => {
+  (input: WorkflowData<DeleteFulfillmentSetsWorkflowInput>) => {
     deleteFulfillmentSetsStep(input.ids)
 
     removeRemoteLinkStep({

packages/core/core-flows/src/fulfillment/workflows/delete-service-zones.ts

@@ -1,13 +1,39 @@
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { deleteServiceZonesStep } from "../steps"
 
+/**
+ * The data to delete one or more service zones.
+ */
+export type DeleteServiceZonesWorkflowInput = {
+  /**
+   * The IDs of the service zones to delete.
+   */
+  ids: string[]
+}
+
 export const deleteServiceZonesWorkflowId = "delete-service-zones-workflow"
 /**
- * This workflow deletes one or more service zones.
+ * This workflow deletes one or more service zones. It's used by the
+ * [Remove Service Zones from Fulfillment Set Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_deletefulfillmentsetsidservicezoneszone_id).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * delete service zones within your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteServiceZonesWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["serzo_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more service zones.
  */
 export const deleteServiceZonesWorkflow = createWorkflow(
   deleteServiceZonesWorkflowId,
-  (input: WorkflowData<{ ids: string[] }>) => {
+  (input: WorkflowData<DeleteServiceZonesWorkflowInput>) => {
     deleteServiceZonesStep(input.ids)
   }
 )

packages/core/core-flows/src/fulfillment/workflows/delete-shipping-options.ts

@@ -6,7 +6,23 @@ import { removeRemoteLinkStep } from "../../common"
 export const deleteShippingOptionsWorkflowId =
   "delete-shipping-options-workflow"
 /**
- * This workflow deletes one or more shipping options.
+ * This workflow deletes one or more shipping options. It's used by the
+ * [Delete Shipping Options Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_deleteshippingoptionsid).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * delete shipping options within your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteShippingOptionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["so_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more shipping options.
  */
 export const deleteShippingOptionsWorkflow = createWorkflow(
   deleteShippingOptionsWorkflowId,

packages/core/core-flows/src/fulfillment/workflows/mark-fulfillment-as-delivered.ts

@@ -14,7 +14,21 @@ import { updateFulfillmentWorkflow } from "./update-fulfillment"
 export const validateFulfillmentDeliverabilityStepId =
   "validate-fulfillment-deliverability"
 /**
- * This step validates that if a fulfillment can be marked delivered
+ * This step validates that a fulfillment can be marked delivered.
+ * If the fulfillment has already been canceled or delivered, the step will throw an error.
+ * 
+ * :::note
+ * 
+ * You can retrieve a fulfillment'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
+ * const data = validateFulfillmentDeliverabilityStep({
+ *   id: "ful_123",
+ *   // other fulfillment data...
+ * })
  */
 export const validateFulfillmentDeliverabilityStep = createStep(
   validateFulfillmentDeliverabilityStepId,
@@ -37,14 +51,39 @@ export const validateFulfillmentDeliverabilityStep = createStep(
   }
 )
 
+/**
+ * The data to mark a fulfillment as delivered.
+ */
+export type MarkFulfillmentAsDeliveredInput = {
+  /**
+   * The fulfillment's ID.
+   */
+  id: string
+}
+
 export const markFulfillmentAsDeliveredWorkflowId =
   "mark-fulfillment-as-delivered-workflow"
 /**
- * This workflow marks fulfillment as delivered.
+ * This workflow marks a fulfillment as delivered. It's used by the {@link markOrderFulfillmentAsDeliveredWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you 
+ * to mark a fulfillment as delivered in your custom flows.
+ * 
+ * @example
+ * const { result } = await markFulfillmentAsDeliveredWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "ful_123",
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Mark a fulfillment as delivered.
  */
 export const markFulfillmentAsDeliveredWorkflow = createWorkflow(
   markFulfillmentAsDeliveredWorkflowId,
-  ({ id }: WorkflowData<{ id: string }>) => {
+  ({ id }: WorkflowData<MarkFulfillmentAsDeliveredInput>) => {
     const fulfillment = useRemoteQueryStep({
       entry_point: "fulfillment",
       fields: ["id", "delivered_at", "canceled_at"],

packages/core/core-flows/src/fulfillment/workflows/update-fulfillment.ts

@@ -8,7 +8,24 @@ import { updateFulfillmentStep } from "../steps"
 
 export const updateFulfillmentWorkflowId = "update-fulfillment-workflow"
 /**
- * This workflow updates a fulfillment.
+ * This workflow updates a fulfillment. It's used by other workflows that update a 
+ * fulfillment, such as {@link markFulfillmentAsDeliveredWorkflow}.
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * update a fulfillment within your custom flows.
+ * 
+ * @example
+ * const { result } = await updateFulfillmentWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "ful_123",
+ *     delivered_at: new Date(),
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a fulfillment.
  */
 export const updateFulfillmentWorkflow = createWorkflow(
   updateFulfillmentWorkflowId,

packages/core/core-flows/src/fulfillment/workflows/update-service-zones.ts

@@ -6,15 +6,41 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { updateServiceZonesStep } from "../steps/update-service-zones"
 
+/**
+ * The updated service zones.
+ */
+export type UpdateServiceZonesWorkflowOutput = ServiceZoneDTO[]
+
 export const updateServiceZonesWorkflowId = "update-service-zones-workflow"
 /**
- * This workflow updates one or more service zones.
+ * This workflow updates one or more service zones. It's used by the
+ * [Update Service Zones Admin API Route](https://docs.medusajs.com/api/admin#fulfillment-sets_postfulfillmentsetsidservicezoneszone_id).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * update service zones within your custom flows.
+ * 
+ * @example
+ * const { result } = await updateServiceZonesWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       id: "serzo_123"
+ *     },
+ *     update: {
+ *       name: "Europe"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more service zones.
  */
 export const updateServiceZonesWorkflow = createWorkflow(
   updateServiceZonesWorkflowId,
   (
     input: WorkflowData<FulfillmentWorkflow.UpdateServiceZonesWorkflowInput>
-  ): WorkflowResponse<ServiceZoneDTO[]> => {
+  ): WorkflowResponse<UpdateServiceZonesWorkflowOutput> => {
     return new WorkflowResponse(updateServiceZonesStep(input))
   }
 )

packages/core/core-flows/src/fulfillment/workflows/update-shipping-options.ts

@@ -14,17 +14,39 @@ import { validateFulfillmentProvidersStep } from "../steps/validate-fulfillment-
 import { validateShippingOptionPricesStep } from "../steps/validate-shipping-option-prices"
 import { ShippingOptionPriceType } from "@medusajs/framework/utils"
 
+/**
+ * The data to update the shipping options.
+ */
+export type UpdateShippingOptionsWorkflowInput = FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput[]
+
 export const updateShippingOptionsWorkflowId =
   "update-shipping-options-workflow"
 /**
- * This workflow updates one or more shipping options.
+ * This workflow updates one or more shipping options. It's used by the
+ * [Update Shipping Options Admin API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptionsid).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * update shipping options within your custom flows.
+ * 
+ * @example
+ * const { result } = await updateShippingOptionsWorkflow(container)
+ * .run({
+ *   input: [
+ *     {
+ *       id: "so_123",
+ *       name: "Standard Shipping",
+ *     }
+ *   ]
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more shipping options.
  */
 export const updateShippingOptionsWorkflow = createWorkflow(
   updateShippingOptionsWorkflowId,
   (
-    input: WorkflowData<
+    input: WorkflowData<UpdateShippingOptionsWorkflowInput>
-      FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput[]
-    >
   ): WorkflowResponse<FulfillmentWorkflow.UpdateShippingOptionsWorkflowOutput> => {
     parallelize(
       validateFulfillmentProvidersStep(input),

packages/core/core-flows/src/fulfillment/workflows/update-shipping-profiles.ts

@@ -6,16 +6,42 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { updateShippingProfilesStep } from "../steps/update-shipping-profiles"
 
+/**
+ * The updated shipping profiles.
+ */
+export type UpdateShippingProfilesWorkflowOutput = FulfillmentWorkflow.CreateShippingProfilesWorkflowOutput
+
 export const updateShippingProfilesWorkflowId =
   "update-shipping-profiles-workflow"
 /**
- * This workflow updates one or more shipping profiles.
+ * This workflow updates one or more shipping profiles. It's used by the
+ * [Update Shipping Profiles Admin API Route](https://docs.medusajs.com/api/admin#shipping-profiles_postshippingprofilesid).
+ * 
+ * You can use this workflow within your own custom workflows, allowing you to
+ * update shipping profiles within your custom flows.
+ * 
+ * @example
+ * const { result } = await updateShippingProfilesWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       id: "sp_123",
+ *     },
+ *     update: {
+ *       name: "Standard",
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more shipping profiles.
  */
 export const updateShippingProfilesWorkflow = createWorkflow(
   updateShippingProfilesWorkflowId,
   (
     input: WorkflowData<FulfillmentWorkflow.UpdateShippingProfilesWorkflowInput>
-  ): WorkflowResponse<FulfillmentWorkflow.CreateShippingProfilesWorkflowOutput> => {
+  ): WorkflowResponse<UpdateShippingProfilesWorkflowOutput> => {
     return new WorkflowResponse(updateShippingProfilesStep(input))
   }
 )

packages/core/types/src/fulfillment/provider.ts

@@ -26,6 +26,9 @@ export type FulfillmentOption = {
   [k: string]: unknown
 }
 
+/**
+ * A calculated shipping option price.
+ */
 export type CalculatedShippingOptionPrice = {
   /**
    * The calculated price.

packages/core/types/src/fulfillment/workflows.ts

@@ -5,15 +5,33 @@ import {
   UpdateShippingOptionRuleDTO,
 } from "./mutations"
 
+/**
+ * The data to create shipping option rules.
+ */
 export type AddFulfillmentShippingOptionRulesWorkflowDTO = {
+  /**
+   * The shipping option rules to create.
+   */
   data: CreateShippingOptionRuleDTO[]
 }
 
+/**
+ * The data to delete shipping option rules.
+ */
 export type RemoveFulfillmentShippingOptionRulesWorkflowDTO = {
+  /**
+   * The IDs of the shipping option rules to delete.
+   */
   ids: string[]
 }
 
+/**
+ * The data to update shipping option rules.
+ */
 export type UpdateFulfillmentShippingOptionRulesWorkflowDTO = {
+  /**
+   * The shipping option rules to update.
+   */
   data: UpdateShippingOptionRuleDTO[]
 }
 

packages/core/types/src/pricing/common/price-rule.ts

@@ -139,8 +139,29 @@ export interface FilterablePriceRuleProps
  */
 export type PricingRuleOperatorValues = "gt" | "lt" | "eq" | "lte" | "gte"
 
+/**
+ * The rules of a price.
+ */
 export interface PriceRule {
+  /**
+   * The attribute to compare.
+   * 
+   * @example
+   * amount
+   */
   attribute: string
+  /**
+   * The operator to use in the comparison.
+   * 
+   * @example
+   * gt
+   */
   operator: PricingRuleOperatorValues
+  /**
+   * The value to compare against.
+   * 
+   * @example
+   * 100
+   */
   value: number
 }

packages/core/types/src/workflow/fulfillment/calculate-shipping-options-prices.ts

@@ -1,9 +1,33 @@
 import { CalculatedShippingOptionPrice } from "../../fulfillment"
 
+/**
+ * The data to calculate shipping option prices.
+ */
 export type CalculateShippingOptionsPricesWorkflowInput = {
+  /**
+   * The ID of the cart to calculate the shipping options for.
+   */
   cart_id: string
-  shipping_options: { id: string; data?: Record<string, unknown> }[]
+  /**
+   * The shipping options to calculate the prices for.
+   */
+  shipping_options: { 
+    /**
+     * The ID of the shipping option.
+     */
+    id: string 
+    /**
+     * Custom data that's necessary for the shipping option's fulfillment provider
+     * to calculate the price.
+     * 
+     * Learn more about this property in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property).
+     */
+    data?: Record<string, unknown>
+  }[]
 }
 
+/**
+ * The calculated shipping option prices.
+ */
 export type CalculateShippingOptionsPricesWorkflowOutput =
   CalculatedShippingOptionPrice[]

packages/core/types/src/workflow/fulfillment/create-fulfillment.ts

@@ -115,6 +115,9 @@ export type CreateFulfillmentLabelWorkflowDTO = {
 
 export type CreateFulfillmentOrderWorkflowDTO = Record<string, any>
 
+/**
+ * The details of a fulfillment to create.
+ */
 export type CreateFulfillmentWorkflowInput = {
   /**
    * The associated location's ID.

packages/core/types/src/workflow/fulfillment/create-shipping-options.ts

@@ -11,35 +11,107 @@ type CreateFlatRateShippingOptionPriceRecord =
       amount: number
     }
 
+/**
+ * The details of the shipping option to create.
+ */
 type CreateFlatShippingOptionInputBase = {
+  /**
+   * The name of the shipping option.
+   */
   name: string
+  /**
+   * The ID of the service zone the shipping option belongs to.
+   */
   service_zone_id: string
+  /**
+   * The ID of the shipping profile the shipping option belongs to.
+   */
   shipping_profile_id: string
+  /**
+   * Custom data that's necessary for the shipping option's fulfillment provider.
+   * Learn more about this property in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property).
+   */
   data?: Record<string, unknown>
+  /**
+   * The ID of the shipping option's fulfillment provider.
+   */
   provider_id: string
+  /**
+   * The type of the shipping option.
+   */
   type: {
+    /**
+     * The label of the shipping option type.
+     */
     label: string
+    /**
+     * The description of the shipping option type.
+     */
     description: string
+    /**
+     * The code of the shipping option type.
+     */
     code: string
   }
+  /**
+   * The rules that determine when the shipping option is available.
+   */
   rules?: {
+    /**
+     * The attribute to match against.
+     * @example
+     * customer_group
+     */
     attribute: string
+    /**
+     * The operator to use when matching the attribute.
+     * 
+     * @example
+     * in
+     */
     operator: RuleOperatorType
+    /**
+     * The value to match against.
+     * 
+     * @example
+     * cusgrp_123
+     */
     value: string | string[]
   }[]
 }
 
+/**
+ * The data to create a flat-rate shipping option.
+ */
 type CreateFlatRateShippingOptionInput = CreateFlatShippingOptionInputBase & {
+  /**
+   * The type of the shipping option's price.
+   */
   price_type: "flat"
+  /**
+   * The prices for the shipping option. Only required if the price type is `flat`.
+   */
   prices: CreateFlatRateShippingOptionPriceRecord[]
 }
 
+/**
+ * The data to create a calculated shipping option.
+ */
 type CreateCalculatedShippingOptionInput = CreateFlatShippingOptionInputBase & {
+  /**
+   * The type of the shipping option's price.
+   */
   price_type: "calculated"
 }
 
+/**
+ * The data to create a flat rate or calculated shipping option.
+ */
 export type CreateShippingOptionsWorkflowInput =
   | CreateFlatRateShippingOptionInput
   | CreateCalculatedShippingOptionInput
 
+/**
+ * The created shipping options.
+ */
 export type CreateShippingOptionsWorkflowOutput = ShippingOptionDTO[]

packages/core/types/src/workflow/fulfillment/delete-shipping-options.ts

@@ -1,3 +1,9 @@
+/**
+ * The data to delete shipping options.
+ */
 export interface DeleteShippingOptionsWorkflowInput {
+  /**
+   * The IDs of the shipping options to delete.
+   */
   ids: string[]
 }

packages/core/types/src/workflow/fulfillment/service-zones.ts

@@ -6,9 +6,21 @@ import {
   FilterableServiceZoneProps,
 } from "../../fulfillment"
 
+/**
+ * The details of a service zone to create.
+ */
 interface CreateServiceZone {
+  /**
+   * The name of the service zone.
+   */
   name: string
+  /**
+   * The ID of the fulfillment set the service zone belongs to.
+   */
   fulfillment_set_id: string
+  /**
+   * The geo zones of the service zone.
+   */
   geo_zones?: (
     | Omit<CreateCountryGeoZoneDTO, "service_zone_id">
     | Omit<CreateProvinceGeoZoneDTO, "service_zone_id">
@@ -17,22 +29,51 @@ interface CreateServiceZone {
   )[]
 }
 
+/**
+ * The data to create service zones.
+ */
 export interface CreateServiceZonesWorkflowInput {
+  /**
+   * The service zones to create.
+   */
   data: CreateServiceZone[]
 }
 
+/**
+ * The data to update a service zone.
+ */
 interface UpdateServiceZone {
+  /**
+   * The name of the service zone.
+   */
   name?: string | null
+  /**
+   * Add new or existing geo zones to the service zone.
+   */
   geo_zones?: (
     | Omit<CreateCountryGeoZoneDTO, "service_zone_id">
     | Omit<CreateProvinceGeoZoneDTO, "service_zone_id">
     | Omit<CreateCityGeoZoneDTO, "service_zone_id">
     | Omit<CreateZipGeoZoneDTO, "service_zone_id">
-    | { id: string }
+    | { 
+      /**
+       * The ID of the geo zone.
+       */
+      id: string
+    }
   )[]
 }
 
+/**
+ * The data to update service zones.
+ */
 export interface UpdateServiceZonesWorkflowInput {
+  /**
+   * The filters to select the service zones to update.
+   */
   selector: FilterableServiceZoneProps
+  /**
+   * The data to update in a service zone.
+   */
   update: UpdateServiceZone
 }

packages/core/types/src/workflow/fulfillment/shipping-profiles.ts

@@ -3,15 +3,33 @@ import {
   ShippingProfileDTO,
 } from "../../fulfillment"
 
+/**
+ * The details of a shipping profile to create.
+ */
 interface CreateShippingProfile {
+  /**
+   * The name of the shipping profile.
+   */
   name: string
+  /**
+   * The type of the shipping profile.
+   */
   type: string
 }
 
+/**
+ * The data to create shipping profiles.
+ */
 export interface CreateShippingProfilesWorkflowInput {
+  /**
+   * The shipping profiles to create.
+   */
   data: CreateShippingProfile[]
 }
 
+/**
+ * The created shipping profiles.
+ */
 export type CreateShippingProfilesWorkflowOutput = ShippingProfileDTO[]
 
 interface UpdateShippingProfile {
@@ -19,7 +37,16 @@ interface UpdateShippingProfile {
   type?: string
 }
 
+/**
+ * The data to update a shipping profile.
+ */
 export interface UpdateShippingProfilesWorkflowInput {
+  /**
+   * The filter to select the shipping profiles to update.
+   */
   selector: FilterableShippingProfileProps
+  /**
+   * The data to update in the shipping profile.
+   */
   update: UpdateShippingProfile
 }

packages/core/types/src/workflow/fulfillment/update-shipping-options.ts

@@ -1,54 +1,160 @@
 import { RuleOperatorType } from "../../common"
 import { PriceRule } from "../../pricing"
 
+/**
+ * The data to update a shipping option.
+ */
 type UpdateFlatShippingOptionInputBase = {
+  /**
+   * The ID of the shipping option.
+   */
   id: string
+  /**
+   * The name of the shipping option.
+   */
   name?: string
+  /**
+   * The ID of the service zone the shipping option belongs to.
+   */
   service_zone_id?: string
+  /**
+   * The ID of the shipping profile the shipping option belongs to.
+   */
   shipping_profile_id?: string
+  /**
+   * Custom data that's necessary for the shipping option's fulfillment provider.
+   * Learn more about this property in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property).
+   */
   data?: Record<string, unknown>
+  /**
+   * The ID of the shipping option's fulfillment provider.
+   */
   provider_id?: string
+  /**
+   * The type of the shipping option.
+   */
   type?: {
+    /**
+     * The label of the shipping option type.
+     */
     label: string
+    /**
+     * The description of the shipping option type.
+     */
     description: string
+    /**
+     * The code of the shipping option type.
+     */
     code: string
   }
+  /**
+   * The rules that determine when the shipping option is available.
+   */
   rules?: {
+    /**
+     * The attribute to compare.
+     * 
+     * @example
+     * customer_group
+     */
     attribute: string
+    /**
+     * The operator to compare with.
+     * 
+     * @example
+     * in
+     */
     operator: RuleOperatorType
+    /**
+     * The value to compare with.
+     * 
+     * @example
+     * cusgrp_123
+     */
     value: string | string[]
   }[]
 }
 
+/**
+ * The data to update a flat rate shipping option.
+ */
 export type UpdateShippingOptionPriceRecord =
   | {
+      /**
+       * The ID of the price record.
+       */
       id?: string
+      /**
+       * The currency code of the price.
+       * 
+       * @example
+       * usd
+       */
       currency_code?: string
+      /**
+       * The amount of the price.
+       */
       amount?: number
+      /**
+       * The rules of the price.
+       */
       rules?: PriceRule[]
     }
   | {
+    /**
+     * The ID of the price record.
+     */
       id?: string
+      /**
+       * The ID of the region that this price applies in.
+       */
       region_id?: string
+      /**
+       * The amount of the price.
+       */
       amount?: number
+      /**
+       * The rules of the price.
+       */
       rules?: PriceRule[]
     }
 
 export type UpdateCalculatedShippingOptionInput =
   UpdateFlatShippingOptionInputBase & {
+    /**
+     * The price type of the shipping option.
+     */
     price_type?: "calculated"
   }
 
+/**
+ * The data to update a flat rate shipping option.
+ */
 export type UpdateFlatRateShippingOptionInput =
   UpdateFlatShippingOptionInputBase & {
+    /**
+     * The price type of the shipping option.
+     */
     price_type?: "flat"
+    /**
+     * The prices of the shipping option.
+     */
     prices?: UpdateShippingOptionPriceRecord[]
   }
 
+/**
+ * The data to update shipping options.
+ */
 export type UpdateShippingOptionsWorkflowInput =
   | UpdateFlatRateShippingOptionInput
   | UpdateCalculatedShippingOptionInput
 
+/**
+ * The result of updating shipping options.
+ */
 export type UpdateShippingOptionsWorkflowOutput = {
+  /**
+   * The updated shipping option's ID.
+   */
   id: string
 }[]