chore(core-flows,types): improve tsdocs of pricing-related workflows (#11000)

* chore(core-flows,types): improve tsdocs of pricing-related workflows

* fix build error

packages/core/core-flows/src/price-list/steps/create-price-list-prices.ts

@@ -11,6 +11,23 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createPriceListPricesStepId = "create-price-list-prices"
 /**
  * This step creates prices for a price list.
+ * 
+ * @example
+ * const data = createPriceListPricesStep({
+ *   data: [{
+ *     id: "plist_123",
+ *     prices: [
+ *       {
+ *         currency_code: "USD",
+ *         amount: 1000,
+ *         variant_id: "variant_123",
+ *       }
+ *     ]
+ *   }],
+ *   variant_price_map: {
+ *     "variant_123": "pset_123"
+ *   }
+ * })
  */
 export const createPriceListPricesStep = createStep(
   createPriceListPricesStepId,

packages/core/core-flows/src/price-list/steps/create-price-lists.ts

@@ -9,6 +9,24 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createPriceListsStepId = "create-price-lists"
 /**
  * This step creates a price list.
+ * 
+ * @example
+ * const data = createPriceListsStep({
+ *   data: [{
+ *     title: "Test Price List",
+ *     description: "Test Price List",
+ *     prices: [
+ *       {
+ *         currency_code: "USD",
+ *         amount: 1000,
+ *         variant_id: "variant_123",
+ *       }
+ *     ]
+ *   }],
+ *   variant_price_map: {
+ *     "variant_123": "pset_123"
+ *   }
+ * })
  */
 export const createPriceListsStep = createStep(
   createPriceListsStepId,

packages/core/core-flows/src/price-list/steps/delete-price-lists.ts

@@ -2,13 +2,18 @@ import { IPricingModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of price lists to delete.
+ */
+export type DeletePriceListsStepInput = string[]
+
 export const deletePriceListsStepId = "delete-price-lists"
 /**
  * This step deletes one or more price lists.
  */
 export const deletePriceListsStep = createStep(
   deletePriceListsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeletePriceListsStepInput, { container }) => {
     const pricingModule = container.resolve<IPricingModuleService>(
       Modules.PRICING
     )

packages/core/core-flows/src/price-list/steps/get-existing-price-lists-price-ids.ts

@@ -2,6 +2,21 @@ import { IPricingModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to retrieve the prices of price lists.
+ */
+export type GetExistingPriceListsPriceIdsStepInput = {
+  /**
+   * The IDs of the price lists to retrieve the prices for.
+   */
+  price_list_ids: string[]
+}
+
+/**
+ * An object whose keys are price list IDs and values are arrays of its price IDs.
+ */
+export type GetExistingPriceListsPriceIdsStepOutput = Record<string, string[]>
+
 export const getExistingPriceListsPriceIdsStepId =
   "get-existing-price-lists-prices"
 /**
@@ -9,9 +24,10 @@ export const getExistingPriceListsPriceIdsStepId =
  */
 export const getExistingPriceListsPriceIdsStep = createStep(
   getExistingPriceListsPriceIdsStepId,
-  async (data: { price_list_ids: string[] }, { container }) => {
+  async (data: GetExistingPriceListsPriceIdsStepInput, { container }) => {
     const { price_list_ids: priceListIds = [] } = data
-    const priceListPriceIdsMap: Record<string, string[]> = {}
+    const priceListPriceIdsMap: 
+      GetExistingPriceListsPriceIdsStepOutput = {}
     const pricingModule = container.resolve<IPricingModuleService>(
       Modules.PRICING
     )

packages/core/core-flows/src/price-list/steps/remove-price-list-prices.ts

@@ -2,13 +2,18 @@ import { IPricingModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of price lists to remove their prices.
+ */
+export type RemovePriceListPricesStepInput = string[]
+
 export const removePriceListPricesStepId = "remove-price-list-prices"
 /**
  * This step removes prices from a price list.
  */
 export const removePriceListPricesStep = createStep(
   removePriceListPricesStepId,
-  async (ids: string[], { container }) => {
+  async (ids: RemovePriceListPricesStepInput, { container }) => {
     if (!ids.length) {
       return new StepResponse([], [])
     }

packages/core/core-flows/src/price-list/steps/update-price-list-prices.ts

@@ -15,6 +15,24 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 export const updatePriceListPricesStepId = "update-price-list-prices"
 /**
  * This step updates a price list's prices.
+ * 
+ * @example
+ * const data = updatePriceListPricesStep({
+ *   data: [{
+ *    id: "plist_123",
+ *     prices: [
+ *       {
+ *         id: "price_123",
+ *         currency_code: "USD",
+ *         amount: 1000,
+ *         variant_id: "variant_123",
+ *       }
+ *     ]
+ *   }],
+ *   variant_price_map: {
+ *     "variant_123": "pset_123"
+ *   }
+ * })
  */
 export const updatePriceListPricesStep = createStep(
   updatePriceListPricesStepId,

packages/core/core-flows/src/price-list/steps/update-price-lists.ts

@@ -11,13 +11,26 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The price lists to update.
+ */
+export type UpdatePriceListsStepInput = UpdatePriceListWorkflowInputDTO[]
+
 export const updatePriceListsStepId = "update-price-lists"
 /**
  * This step updates one or more price lists.
+ * 
+ * @example
+ * const data = updatePriceListsStep([
+ *   {
+ *     id: "plist_123",
+ *     title: "Test Price List",
+ *   }
+ * ])
  */
 export const updatePriceListsStep = createStep(
   updatePriceListsStepId,
-  async (data: UpdatePriceListDTO[], { container }) => {
+  async (data: UpdatePriceListsStepInput, { container }) => {
     const pricingModule = container.resolve<IPricingModuleService>(
       Modules.PRICING
     )

packages/core/core-flows/src/price-list/steps/validate-price-lists.ts

@@ -10,13 +10,19 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of price lists to validate that they exist.
+ */
+export type ValidatePriceListsStepInput = Pick<UpdatePriceListDTO, "id">[]
+
 export const validatePriceListsStepId = "validate-price-lists"
 /**
  * This step validates that the specified price lists exist.
+ * If not valid, the step throws an error.
  */
 export const validatePriceListsStep = createStep(
   validatePriceListsStepId,
-  async (data: Pick<UpdatePriceListDTO, "id">[], { container }) => {
+  async (data: ValidatePriceListsStepInput, { container }) => {
     const pricingModule = container.resolve<IPricingModuleService>(
       Modules.PRICING
     )

packages/core/core-flows/src/price-list/steps/validate-variant-price-links.ts

@@ -4,18 +4,41 @@ import {
 } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to validate that the specified variants have prices.
+ */
+export type ValidateVariantPriceLinksStepInput = {
+  /**
+   * The prices to validate that their specified variants have prices.
+   */
+  prices?: {
+    /**
+     * The variant ID.
+     */
+    variant_id: string
+  }[]
+}[]
+
 export const validateVariantPriceLinksStepId = "validate-variant-price-links"
 /**
  * This step validates that the specified variants have prices.
+ * If not valid, the step throws an error.
+ * 
+ * @example
+ * const data = validateVariantPriceLinksStep([
+ *   {
+ *     prices: [
+ *       {
+ *         variant_id: "variant_123",
+ *       }
+ *     ]
+ *   }
+ * ])
  */
 export const validateVariantPriceLinksStep = createStep(
   validateVariantPriceLinksStepId,
   async (
-    data: {
-      prices?: {
-        variant_id: string
-      }[]
-    }[],
+    data: ValidateVariantPriceLinksStepInput,
     { container }
   ) => {
     const remoteQuery = container.resolve(

packages/core/core-flows/src/price-list/workflows/batch-price-list-prices.ts

@@ -13,16 +13,58 @@ import { createPriceListPricesWorkflow } from "./create-price-list-prices"
 import { removePriceListPricesWorkflow } from "./remove-price-list-prices"
 import { updatePriceListPricesWorkflow } from "./update-price-list-prices"
 
+/**
+ * The data to manage a price list's prices.
+ */
+export type BatchPriceListPricesWorkflowInput = {
+  /**
+   * The data to manage the prices of a price list.
+   */
+  data: BatchPriceListPricesWorkflowDTO
+}
+
 export const batchPriceListPricesWorkflowId = "batch-price-list-prices"
 /**
- * This workflow manages price lists' prices by creating, updating, or removing them.
+ * This workflow manages a price list's prices by creating, updating, or removing them. It's used by the
+ * [Manage Prices in Price List Admin API Route](https://docs.medusajs.com/api/admin#price-lists_postpricelistsidpricesbatch).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to 
+ * manage price lists' prices in your custom flows.
+ * 
+ * @example
+ * const { result } = await batchPriceListPricesWorkflow(container)
+ * .run({
+ *   input: {
+ *     data: {
+ *       id: "plist_123",
+ *       create: [
+ *         {
+ *           amount: 10,
+ *           currency_code: "usd",
+ *           variant_id: "variant_123"
+ *         }
+ *       ],
+ *       update: [
+ *         {
+ *           id: "price_123",
+ *           amount: 10,
+ *           currency_code: "usd",
+ *           variant_id: "variant_123"
+ *         }
+ *       ],
+ *       delete: ["price_321"]
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Manage a price list's prices.
  */
 export const batchPriceListPricesWorkflow = createWorkflow(
   batchPriceListPricesWorkflowId,
   (
-    input: WorkflowData<{
-      data: BatchPriceListPricesWorkflowDTO
-    }>
+    input: WorkflowData<BatchPriceListPricesWorkflowInput>
   ): WorkflowResponse<BatchPriceListPricesWorkflowResult> => {
     const createInput = transform({ input: input.data }, (data) => [
       { id: data.input.id, prices: data.input.create },

packages/core/core-flows/src/price-list/workflows/create-price-list-prices.ts

@@ -12,17 +12,55 @@ import { createPriceListPricesStep } from "../steps/create-price-list-prices"
 import { validatePriceListsStep } from "../steps/validate-price-lists"
 import { validateVariantPriceLinksStep } from "../steps/validate-variant-price-links"
 
+/**
+ * The data to create prices for price lists.
+ */
+export type CreatePriceListPricesWorkflowInput = {
+  /**
+   * The prices to create.
+   */
+  data: CreatePriceListPricesWorkflowDTO[]
+}
+
+/**
+ * The created prices.
+ */
+export type CreatePriceListPricesWorkflowOutput = PricingTypes.PriceDTO[]
+
 export const createPriceListPricesWorkflowId = "create-price-list-prices"
 /**
- * This workflow creates prices in price lists.
+ * This workflow creates prices in price lists. It's used by other workflows, such as 
+ * {@link batchPriceListPricesWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * create prices in price lists in your custom flows.
+ * 
+ * @example
+ * const { result } = await createPriceListPricesWorkflow(container)
+ * .run({
+ *   input: {
+ *     data: [{
+ *       id: "plist_123",
+ *       prices: [
+ *         {
+ *           amount: 10,
+ *           currency_code: "usd",
+ *           variant_id: "variant_123"
+ *         }
+ *       ],
+ *     }]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create prices in price lists.
  */
 export const createPriceListPricesWorkflow = createWorkflow(
   createPriceListPricesWorkflowId,
   (
-    input: WorkflowData<{
-      data: CreatePriceListPricesWorkflowDTO[]
-    }>
-  ): WorkflowResponse<PricingTypes.PriceDTO[]> => {
+    input: WorkflowData<CreatePriceListPricesWorkflowInput>
+  ): WorkflowResponse<CreatePriceListPricesWorkflowOutput> => {
     const [_, variantPriceMap] = parallelize(
       validatePriceListsStep(input.data),
       validateVariantPriceLinksStep(input.data)

packages/core/core-flows/src/price-list/workflows/create-price-lists.ts

@@ -9,13 +9,45 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { createPriceListsStep, validateVariantPriceLinksStep } from "../steps"
 
+/**
+ * The data to create price lists.
+ */
 export type CreatePriceListsWorkflowInput = {
+  /**
+   * The price lists to create.
+   */
   price_lists_data: CreatePriceListWorkflowInputDTO[]
 }
 
+/**
+ * The created price lists.
+ */
+export type CreatePriceListsWorkflowOutput = PriceListDTO[]
+
 export const createPriceListsWorkflowId = "create-price-lists"
 /**
- * This workflow creates one or more price lists.
+ * This workflow creates one or more price lists. It's used by the
+ * [Create Price List Admin API Route](https://docs.medusajs.com/api/admin#price-lists_postpricelists).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * create price lists in your custom flows.
+ * 
+ * @example
+ * const { result } = await createPriceListsWorkflow(container)
+ * .run({
+ *   input: {
+ *     price_lists_data: [
+ *       {
+ *         title: "Price List 1",
+ *         description: "Price List 1 Description",
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more price lists.
  */
 export const createPriceListsWorkflow = createWorkflow(
   createPriceListsWorkflowId,

packages/core/core-flows/src/price-list/workflows/delete-price-lists.ts

@@ -1,13 +1,35 @@
 import { createWorkflow, WorkflowData } from "@medusajs/framework/workflows-sdk"
 import { deletePriceListsStep } from "../steps"
 
+/**
+ * The data to delete price lists.
+ */
+export type DeletePriceListsWorkflowInput = {
+  /**
+   * The IDs of the price lists to delete.
+   */
+  ids: string[]
+}
+
 export const deletePriceListsWorkflowId = "delete-price-lists"
 /**
- * This workflow deletes one or more price lists.
+ * This workflow deletes one or more price lists. It's used by the
+ * [Delete Price List Admin API Route](https://docs.medusajs.com/api/admin#price-lists_deletepricelistsid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * delete price lists in your custom flows.
+ * 
+ * @example
+ * const { result } = await deletePriceListsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["plist_123"]
+ *   }
+ * })
  */
 export const deletePriceListsWorkflow = createWorkflow(
   deletePriceListsWorkflowId,
-  (input: WorkflowData<{ ids: string[] }>): WorkflowData<void> => {
+  (input: WorkflowData<DeletePriceListsWorkflowInput>): WorkflowData<void> => {
     return deletePriceListsStep(input.ids)
   }
 )

packages/core/core-flows/src/price-list/workflows/remove-price-list-prices.ts

@@ -5,13 +5,39 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { removePriceListPricesStep } from "../steps/remove-price-list-prices"
 
+/**
+ * The data to remove prices from price lists.
+ */
+export type RemovePriceListPricesWorkflowInput = {
+  /**
+   * The IDs of the price lists to remove their prices.
+   */
+  ids: string[]
+}
+
 export const removePriceListPricesWorkflowId = "remove-price-list-prices"
 /**
- * This workflow removes price lists' prices.
+ * This workflow removes price lists' prices. It's used by other workflows, such
+ * as {@link batchPriceListPricesWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * remove prices in price lists in your custom flows.
+ * 
+ * @example
+ * const { result } = await removePriceListPricesWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["plist_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Remove prices in price lists.
  */
 export const removePriceListPricesWorkflow = createWorkflow(
   removePriceListPricesWorkflowId,
-  (input: WorkflowData<{ ids: string[] }>): WorkflowResponse<string[]> => {
+  (input: WorkflowData<RemovePriceListPricesWorkflowInput>): WorkflowResponse<string[]> => {
     return new WorkflowResponse(removePriceListPricesStep(input.ids))
   }
 )

packages/core/core-flows/src/price-list/workflows/update-price-list-prices.ts

@@ -12,16 +12,52 @@ import { updatePriceListPricesStep } from "../steps/update-price-list-prices"
 import { validatePriceListsStep } from "../steps/validate-price-lists"
 import { validateVariantPriceLinksStep } from "../steps/validate-variant-price-links"
 
+/**
+ * The data to update the prices of price lists.
+ */
+export type UpdatePriceListPricesWorkflowInput = {
+  /**
+   * The price lists to update their prices.
+   */
+  data: UpdatePriceListPricesWorkflowDTO[]
+}
+
 export const updatePriceListPricesWorkflowId = "update-price-list-prices"
 /**
- * This workflow update price lists' prices.
+ * This workflow update price lists' prices. It's used by other workflows, such
+ * as {@link batchPriceListPricesWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * update prices in price lists in your custom flows.
+ * 
+ * @example
+ * const { result } = await updatePriceListPricesWorkflow(container)
+ * .run({
+ *   input: {
+ *     data: [
+ *       {
+ *         id: "price_123",
+ *         prices: [
+ *           {
+ *             id: "price_123",
+ *             amount: 10,
+ *             currency_code: "usd",
+ *             variant_id: "variant_123"
+ *           }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update price lists' prices.
  */
 export const updatePriceListPricesWorkflow = createWorkflow(
   updatePriceListPricesWorkflowId,
   (
-    input: WorkflowData<{
-      data: UpdatePriceListPricesWorkflowDTO[]
-    }>
+    input: WorkflowData<UpdatePriceListPricesWorkflowInput>
   ): WorkflowResponse<PricingTypes.PriceDTO[]> => {
     const [_, variantPriceMap] = parallelize(
       validatePriceListsStep(input.data),

packages/core/core-flows/src/price-list/workflows/update-price-lists.ts

@@ -2,9 +2,40 @@ import { UpdatePriceListWorkflowInputDTO } from "@medusajs/framework/types"
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { updatePriceListsStep, validatePriceListsStep } from "../steps"
 
+/**
+ * The data to update price lists.
+ */
+export type UpdatePriceListsWorkflowInput = {
+  /**
+   * The price lists to update.
+   */
+  price_lists_data: UpdatePriceListWorkflowInputDTO[]
+}
+
 export const updatePriceListsWorkflowId = "update-price-lists"
 /**
- * This workflow updates one or more price lists.
+ * This workflow updates one or more price lists. It's used by the
+ * [Update Price List Admin API Route](https://docs.medusajs.com/api/admin#price-lists_postpricelistsid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * update price lists in your custom flows.
+ * 
+ * @example
+ * const { result } = await updatePriceListsWorkflow(container)
+ * .run({
+ *   input: {
+ *     price_lists_data: [
+ *       {
+ *         id: "plist_123",
+ *         title: "Test Price List",
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more price lists.
  */
 export const updatePriceListsWorkflow = createWorkflow(
   updatePriceListsWorkflowId,

packages/core/core-flows/src/pricing/steps/create-price-preferences.ts

@@ -5,14 +5,26 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The price preferences to create.
+ */
+export type CreatePricePreferencesStepInput = PricingWorkflow.CreatePricePreferencesWorkflowInput[]
+
 export const createPricePreferencesStepId = "create-price-preferences"
 /**
  * This step creates one or more price preferences.
+ * 
+ * @example
+ * const data = createPricePreferencesStep([{
+ *   attribute: "region_id",
+ *   value: "reg_123",
+ *   is_tax_inclusive: true
+ * }])
  */
 export const createPricePreferencesStep = createStep(
   createPricePreferencesStepId,
   async (
-    data: PricingWorkflow.CreatePricePreferencesWorkflowInput[],
+    data: CreatePricePreferencesStepInput,
     { container }
   ) => {
     const pricingModule = container.resolve<IPricingModuleService>(

packages/core/core-flows/src/pricing/steps/create-price-sets.ts

@@ -5,13 +5,28 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The price sets to create.
+ */
+export type CreatePriceSetWorkflowInput = CreatePriceSetDTO[]
+
 export const createPriceSetsStepId = "create-price-sets"
 /**
  * This step creates one or more price sets.
+ * 
+ * @example
+ * const data = createPriceSetsStep([{
+ *   prices: [
+ *     {
+ *       amount: 10,
+ *       currency_code: "usd",
+ *     }
+ *   ]
+ * }])
  */
 export const createPriceSetsStep = createStep(
   createPriceSetsStepId,
-  async (data: CreatePriceSetDTO[], { container }) => {
+  async (data: CreatePriceSetWorkflowInput, { container }) => {
     const pricingModule = container.resolve<IPricingModuleService>(
       Modules.PRICING
     )

packages/core/core-flows/src/pricing/steps/delete-price-preferences.ts

@@ -2,13 +2,18 @@ import { IPricingModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of price preferences to delete.
+ */
+export type DeletePricePreferencesStepInput = string[]
+
 export const deletePricePreferencesStepId = "delete-price-preferences"
 /**
  * This step deletes one or more price preferences.
  */
 export const deletePricePreferencesStep = createStep(
   deletePricePreferencesStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeletePricePreferencesStepInput, { container }) => {
     const service = container.resolve<IPricingModuleService>(Modules.PRICING)
 
     await service.softDeletePricePreferences(ids)

packages/core/core-flows/src/pricing/steps/update-price-preferences-as-array.ts

@@ -9,13 +9,25 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The price preferences to update.
+ */
 export type UpdatePricePreferencesAsArrayStepInput =
   PricingWorkflow.UpdatePricePreferencesWorkflowInput["update"][]
 
 export const updatePricePreferencesAsArrayStepId =
   "update-price-preferences-as-array"
 /**
- * This step updates price preferences.
+ * This step creates or updates price preferences.
+ * 
+ * @example
+ * const data = updatePricePreferencesAsArrayStep([
+ *   {
+ *     attribute: "region_id",
+ *     value: "reg_123",
+ *     is_tax_inclusive: true
+ *   }
+ * ])
  */
 export const updatePricePreferencesAsArrayStep = createStep(
   updatePricePreferencesAsArrayStepId,

packages/core/core-flows/src/pricing/steps/update-price-preferences.ts

@@ -11,6 +11,16 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const updatePricePreferencesStepId = "update-price-preferences"
 /**
  * This step updates price preferences matching the specified filters.
+ * 
+ * @example
+ * const data = updatePricePreferencesStep({
+ *   selector: {
+ *     id: ["pp_123"]
+ *   },
+ *   update: {
+ *     is_tax_inclusive: true
+ *   }
+ * })
  */
 export const updatePricePreferencesStep = createStep(
   updatePricePreferencesStepId,

packages/core/core-flows/src/pricing/steps/update-price-sets.ts

@@ -6,18 +6,46 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to update price sets. You can either update price sets with a selector
+ * or by providing IDs in the price set objects to update.
+ */
 export type UpdatePriceSetsStepInput =
   | {
+    /**
+     * The filters to select which price sets to update.
+     */
       selector?: PricingTypes.FilterablePriceSetProps
+      /**
+       * The data to update the price sets with.
+       */
       update?: PricingTypes.UpdatePriceSetDTO
     }
   | {
+    /**
+     * The price sets to update.
+     */
       price_sets: PricingTypes.UpsertPriceSetDTO[]
     }
 
 export const updatePriceSetsStepId = "update-price-sets"
 /**
  * This step updates price sets.
+ * 
+ * @example
+ * const data = updatePriceSetsStep({
+ *   selector: {
+ *     id: ["pset_123"]
+ *   },
+ *   update: {
+ *     prices: [
+ *       {
+ *         amount: 10,
+ *         currency_code: "usd",
+ *       }
+ *     ]
+ *   }
+ * })
  */
 export const updatePriceSetsStep = createStep(
   updatePriceSetsStepId,

packages/core/core-flows/src/pricing/workflows/create-price-preferences.ts

@@ -6,14 +6,39 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { createPricePreferencesStep } from "../steps"
 
+/**
+ * The price preferences to create.
+ */
+export type CreatePricePreferencesWorkflowInput = PricingWorkflow.CreatePricePreferencesWorkflowInput[]
+
 export const createPricePreferencesWorkflowId = "create-price-preferences"
 /**
- * This workflow creates one or more price preferences.
+ * This workflow creates one or more price preferences. It's used by the
+ * [Create Price Preferences Admin API Route](https://docs.medusajs.com/api/admin#price-preferences_postpricepreferences).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to 
+ * create price preferences in your custom flows.
+ * 
+ * @example
+ * const { result } = await createPricePreferencesWorkflow(container)
+ * .run({
+ *   input: [
+ *     {
+ *       attribute: "region_id",
+ *       value: "reg_123",
+ *       is_tax_inclusive: true
+ *     }
+ *   ]
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more price preferences.
  */
 export const createPricePreferencesWorkflow = createWorkflow(
   createPricePreferencesWorkflowId,
   (
-    input: WorkflowData<PricingWorkflow.CreatePricePreferencesWorkflowInput[]>
+    input: WorkflowData<CreatePricePreferencesWorkflowInput>
   ) => {
     return new WorkflowResponse(createPricePreferencesStep(input))
   }

packages/core/core-flows/src/pricing/workflows/delete-price-preferences.ts

@@ -1,13 +1,32 @@
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { deletePricePreferencesStep } from "../steps"
 
+/**
+ * The IDs of price preferences to delete.
+ */
+export type DeletePricePreferencesWorkflowInput = string[]
+
 export const deletePricePreferencesWorkflowId = "delete-price-preferences"
 /**
- * This workflow deletes one or more price preferences.
+ * This workflow deletes one or more price preferences. It's used by the
+ * [Delete Price Preferences Admin API Route](https://docs.medusajs.com/api/admin#price-preferences_deletepricepreferencesid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * delete price preferences in your custom flows.
+ * 
+ * @example
+ * const { result } = await deletePricePreferencesWorkflow(container)
+ * .run({
+ *   input: ["pp_123"]
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more price preferences.
  */
 export const deletePricePreferencesWorkflow = createWorkflow(
   deletePricePreferencesWorkflowId,
-  (input: WorkflowData<string[]>) => {
+  (input: WorkflowData<DeletePricePreferencesWorkflowInput>) => {
     return deletePricePreferencesStep(input)
   }
 )

packages/core/core-flows/src/pricing/workflows/update-price-preferences.ts

@@ -8,7 +8,28 @@ import { updatePricePreferencesStep } from "../steps"
 
 export const updatePricePreferencesWorkflowId = "update-price-preferences"
 /**
- * This workflow updates one or more price preferences.
+ * This workflow updates one or more price preferences. It's used by the
+ * [Update Price Preference Admin API Route](https://docs.medusajs.com/api/admin#price-preferences_postpricepreferencesid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * update price preferences in your custom flows.
+ * 
+ * @example
+ * const { result } = await updatePricePreferencesWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       id: ["pp_123"]
+ *     },
+ *     update: {
+ *       is_tax_inclusive: true
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more price preferences.
  */
 export const updatePricePreferencesWorkflow = createWorkflow(
   updatePricePreferencesWorkflowId,

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

@@ -1,79 +1,273 @@
 import { PricingTypes } from "../bundles"
 import { PriceListStatus } from "./common"
 
+/**
+ * The data to create a price list's price.
+ */
 export interface CreatePriceListPriceWorkflowDTO {
+  /**
+   * The amount for the price.
+   */
   amount: number
+
+  /**
+   * The currency code for the price.
+   * 
+   * @example
+   * usd
+   */
   currency_code: string
+
+  /**
+   * The ID of the variant that this price applies to.
+   */
   variant_id: string
+
+  /**
+   * The maximum quantity of the variant allowed in the cart for this price to be applied.
+   */
   max_quantity?: number | null
+
+  /**
+   * The minimum quantity of the variant required in the cart for this price to be applied.
+   */
   min_quantity?: number | null
+
+  /**
+   * Additional rules for the price list.
+   */
   rules?: Record<string, string>
 }
 
+/**
+ * The data to update a price list's price.
+ */
 export interface UpdatePriceListPriceWorkflowDTO {
+  /**
+   * The ID of the price.
+   */
   id: string
+
+  /**
+   * The ID of the product variant that this price belongs to.
+   */
   variant_id: string
+
+  /**
+   * The amount of the price.
+   */
   amount?: number
+
+  /**
+   * The currency code of the price.
+   * 
+   * @example
+   * usd
+   */
   currency_code?: string
+
+  /**
+   * The maximum quantity of the variant allowed in the cart for this price to be applied.
+   */
   max_quantity?: number | null
+
+  /**
+   * The minimum quantity of the variant required in the cart for this price to be applied.
+   */
   min_quantity?: number | null
+
+  /**
+   * Additional rules for the price.
+   */
   rules?: Record<string, string>
 }
 
+/**
+ * The data to create a price list.
+ */
 export interface CreatePriceListWorkflowInputDTO {
+  /**
+   * The title of the price list.
+   */
   title: string
+
+  /**
+   * The description of the price list.
+   */
   description: string
+
+  /**
+   * The start date and time of the price list.
+   */
   starts_at?: string | null
+
+  /**
+   * The end date and time of the price list.
+   */
   ends_at?: string | null
+
+  /**
+   * The status of the price list.
+   */
   status?: PriceListStatus
+
+  /**
+   * The rules associated with the price list.
+   */
   rules?: Record<string, string[]>
+
+  /**
+   * The prices associated with the price list.
+   */
   prices?: CreatePriceListPriceWorkflowDTO[]
 }
 
+/**
+ * The data to update in a price list.
+ */
 export interface UpdatePriceListWorkflowInputDTO {
+  /**
+   * The ID of the price list to update.
+   */
   id: string
+
+  /**
+   * The title of the price list.
+   */
   title?: string
+
+  /**
+   * The description of the price list.
+   */
   description?: string | null
+
+  /**
+   * The start date of the price list.
+   */
   starts_at?: string | null
+
+  /**
+   * The end date of the price list.
+   */
   ends_at?: string | null
+
+  /**
+   * The status of the price list.
+   */
   status?: PriceListStatus
+
+  /**
+   * The rules associated with the price list.
+   */
   rules?: Record<string, string[]>
 }
 
+/**
+ * The data to update the prices of a price list.
+ */
 export interface UpdatePriceListPricesWorkflowDTO {
+  /**
+   * The ID of the price list.
+   */
   id: string
+  /**
+   * The prices to update.
+   */
   prices: UpdatePriceListPriceWorkflowDTO[]
 }
 
+/**
+ * The data to manage the prices of a price list.
+ */
 export interface BatchPriceListPricesWorkflowDTO {
+  /**
+   * The ID of the price list.
+   */
   id: string
+  /**
+   * The prices to create.
+   */
   create: CreatePriceListPriceWorkflowDTO[]
+  /**
+   * The prices to update.
+   */
   update: UpdatePriceListPriceWorkflowDTO[]
+  /**
+   * The IDs of prices to delete.
+   */
   delete: string[]
 }
 
+/**
+ * The result of managing a price list's prices.
+ */
 export interface BatchPriceListPricesWorkflowResult {
+  /**
+   * The prices that were created.
+   */
   created: PricingTypes.PriceDTO[]
+  /**
+   * The prices that were updated.
+   */
   updated: PricingTypes.PriceDTO[]
+  /**
+   * The IDs of the prices that were deleted.
+   */
   deleted: string[]
 }
 
+/**
+ * The data to create prices for a price list.
+ */
 export interface CreatePriceListPricesWorkflowDTO {
+  /**
+   * The ID of the price list.
+   */
   id: string
+  /**
+   * The prices to create in the price list.
+   */
   prices: CreatePriceListPriceWorkflowDTO[]
 }
 
+/**
+ * The data to update the prices of a price list.
+ */
 export interface UpdatePriceListPriceWorkflowStepDTO {
+  /**
+   * The price list and its prices to update.
+   */
   data?: UpdatePriceListPricesWorkflowDTO[]
+  /**
+   * An object whose keys are variant IDs and values are price set IDs.
+   */
   variant_price_map: Record<string, string>
 }
 
+/**
+ * The data to create price lists.
+ */
 export interface CreatePriceListsWorkflowStepDTO {
+  /**
+   * The price lists to create.
+   */
   data: CreatePriceListWorkflowInputDTO[]
+  /**
+   * An object whose keys are variant IDs and values are price set IDs.
+   */
   variant_price_map: Record<string, string>
 }
 
+/**
+ * The data to create prices for price lists.
+ */
 export interface CreatePriceListPricesWorkflowStepDTO {
+  /**
+   * The prices to create.
+   */
   data: (Pick<CreatePriceListWorkflowInputDTO, "prices"> & { id: string })[]
+  /**
+   * An object whose keys are variant IDs and values are price set IDs.
+   */
   variant_price_map: Record<string, string>
 }

packages/core/types/src/workflow/pricing/index.ts

@@ -1,8 +1,22 @@
 import { FilterablePricePreferenceProps } from "../../pricing"
 
+/**
+ * The data of a price preference to create.
+ */
 export interface CreatePricePreferencesWorkflowInput {
+  /**
+   * The attribute of the price preference. For example, `region_id` or `currency_code`.
+   */
   attribute?: string
+  /**
+   * The value of the price preference. For example, `reg_123` or `usd`.
+   */
   value?: string
+  /**
+   * Whether prices matching this preference are tax inclusive.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/pricing/tax-inclusive-pricing).
+   */
   is_tax_inclusive?: boolean
 }