chore(core-flows, types): improve TSDocs of tax and region related wo…

…rkflows (medusajs#11018)

packages/core/core-flows/src/region/steps/create-regions.ts

@@ -8,6 +8,15 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createRegionsStepId = "create-regions"
 /**
  * This step creates one or more regions.
+ * 
+ * @example
+ * const data = createRegionsStep([
+ *   {
+ *     currency_code: "usd",
+ *     name: "United States",
+ *     countries: ["us"],
+ *   }
+ * ])
  */
 export const createRegionsStep = createStep(
   createRegionsStepId,

packages/core/core-flows/src/region/steps/delete-regions.ts

@@ -2,13 +2,18 @@ import { IRegionModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the regions to delete.
+ */
+export type DeleteRegionsStepInput = string[]
+
 export const deleteRegionsStepId = "delete-regions"
 /**
  * This step deletes one or more regions.
  */
 export const deleteRegionsStep = createStep(
   deleteRegionsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteRegionsStepInput, { container }) => {
     const service = container.resolve<IRegionModuleService>(Modules.REGION)
 
     await service.softDeleteRegions(ids)

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

@@ -1,3 +1,4 @@
 export * from "./create-regions"
 export * from "./delete-regions"
 export * from "./update-regions"
+export * from "./set-regions-payment-providers"

packages/core/core-flows/src/region/steps/set-regions-payment-providers.ts

@@ -13,9 +13,21 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to set the payment providers available in regions.
+ */
 export interface SetRegionsPaymentProvidersStepInput {
+  /**
+   * The regions to set the payment providers for.
+   */
   input: {
+    /**
+     * The ID of the region.
+     */
     id: string
+    /**
+     * The IDs of the payment providers that are available in the region.
+     */
     payment_providers?: string[]
   }[]
 }
@@ -91,7 +103,17 @@ async function getCurrentRegionPaymentProvidersLinks(
 export const setRegionsPaymentProvidersStepId =
   "add-region-payment-providers-step"
 /**
- * This step sets the payment providers in regions.
+ * This step sets the payment providers available in regions.
+ * 
+ * @example
+ * const data = setRegionsPaymentProvidersStep({
+ *   input: [
+ *     {
+ *       id: "reg_123",
+ *       payment_providers: ["pp_system", "pp_stripe_stripe"]
+ *     }
+ *   ]
+ * })
  */
 export const setRegionsPaymentProvidersStep = createStep(
   setRegionsPaymentProvidersStepId,

packages/core/core-flows/src/region/steps/update-regions.ts

@@ -9,14 +9,33 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to update regions.
+ */
 export type UpdateRegionsStepInput = {
+  /**
+   * The filters to select the regions to update.
+   */
   selector: FilterableRegionProps
+  /**
+   * The data to update in the regions.
+   */
   update: UpdateRegionDTO
 }
 
 export const updateRegionsStepId = "update-region"
 /**
  * This step updates regions matching the specified filters.
+ * 
+ * @example
+ * const data = updateRegionsStep({
+ *   selector: {
+ *     id: "reg_123"
+ *   },
+ *   update: {
+ *     name: "United States"
+ *   }
+ * })
  */
 export const updateRegionsStep = createStep(
   updateRegionsStepId,

packages/core/core-flows/src/region/workflows/create-regions.ts

@@ -14,7 +14,25 @@ import { setRegionsPaymentProvidersStep } from "../steps/set-regions-payment-pro
 
 export const createRegionsWorkflowId = "create-regions"
 /**
- * This workflow creates one or more regions.
+ * This workflow creates one or more regions. It's used by the
+ * [Create Region Admin API Route](https://docs.medusajs.com/api/admin#regions_postregions).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to create regions in your custom flows.
+ * 
+ * @example
+ * const { result } = await createRegionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     regions: [
+ *       {
+ *         currency_code: "usd",
+ *         name: "United States",
+ *         countries: ["us"],
+ *       }
+ *     ]
+ *   }
+ * })
  */
 export const createRegionsWorkflow = createWorkflow(
   createRegionsWorkflowId,

packages/core/core-flows/src/region/workflows/delete-regions.ts

@@ -11,7 +11,23 @@ export type DeleteRegionsWorkflowInput = { ids: string[] }
 
 export const deleteRegionsWorkflowId = "delete-regions"
 /**
- * This workflow deletes one or more regions.
+ * This workflow deletes one or more regions. It's used by the 
+ * [Delete Region Admin API Route](https://docs.medusajs.com/api/admin#regions_deleteregionsid).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to delete regions in your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteRegionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["reg_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more regions.
  */
 export const deleteRegionsWorkflow = createWorkflow(
   deleteRegionsWorkflowId,

packages/core/core-flows/src/region/workflows/update-regions.ts

@@ -15,7 +15,28 @@ import { setRegionsPaymentProvidersStep } from "../steps/set-regions-payment-pro
 
 export const updateRegionsWorkflowId = "update-regions"
 /**
- * This workflow updates regions matching the specified filters.
+ * This workflow updates regions matching the specified filters. It's used by the
+ * [Update Region Admin API Route](https://docs.medusajs.com/api/admin#regions_postregionsid).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to update regions in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateRegionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       id: "reg_123"
+ *     },
+ *     update: {
+ *       name: "United States"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update regions.
  */
 export const updateRegionsWorkflow = createWorkflow(
   updateRegionsWorkflowId,

packages/core/core-flows/src/tax/steps/create-tax-rate-rules.ts

@@ -8,6 +8,15 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createTaxRateRulesStepId = "create-tax-rate-rules"
 /**
  * This step creates one or more tax rate rules.
+ * 
+ * @example
+ * const data = createTaxRateRulesStep([
+ *   {
+ *     reference: "product_type",
+ *     reference_id: "ptyp_123",
+ *     tax_rate_id: "txr_123"
+ *   }
+ * ])
  */
 export const createTaxRateRulesStep = createStep(
   createTaxRateRulesStepId,

packages/core/core-flows/src/tax/steps/create-tax-rates.ts

@@ -5,6 +5,14 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createTaxRatesStepId = "create-tax-rates"
 /**
  * This step creates one or more tax rates.
+ * 
+ * @example
+ * const data = createTaxRatesStep([
+ *   {
+ *     name: "Default",
+ *     tax_region_id: "txreg_123",
+ *   }
+ * ])
  */
 export const createTaxRatesStep = createStep(
   createTaxRatesStepId,

packages/core/core-flows/src/tax/steps/create-tax-regions.ts

@@ -8,6 +8,13 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createTaxRegionsStepId = "create-tax-regions"
 /**
  * This step creates one or more tax regions.
+ * 
+ * @example
+ * const data = createTaxRegionsStep([
+ *   {
+ *     country_code: "us",
+ *   }
+ * ])
  */
 export const createTaxRegionsStep = createStep(
   createTaxRegionsStepId,

packages/core/core-flows/src/tax/steps/delete-tax-rate-rules.ts

@@ -2,13 +2,18 @@ import { ITaxModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the tax rate rules to delete.
+ */
+export type DeleteTaxRateRulesStepInput = string[]
+
 export const deleteTaxRateRulesStepId = "delete-tax-rate-rules"
 /**
  * This step deletes one or more tax rate rules.
  */
 export const deleteTaxRateRulesStep = createStep(
   deleteTaxRateRulesStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteTaxRateRulesStepInput, { container }) => {
     if (!ids?.length) {
       return new StepResponse(void 0, [])
     }

packages/core/core-flows/src/tax/steps/delete-tax-rates.ts

@@ -2,13 +2,18 @@ import { ITaxModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the tax rates to delete.
+ */
+export type DeleteTaxRatesStepInput = string[]
+
 export const deleteTaxRatesStepId = "delete-tax-rates"
 /**
  * This step deletes one or more tax rates.
  */
 export const deleteTaxRatesStep = createStep(
   deleteTaxRatesStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteTaxRatesStepInput, { container }) => {
     const service = container.resolve<ITaxModuleService>(Modules.TAX)
 
     await service.softDeleteTaxRates(ids)

packages/core/core-flows/src/tax/steps/delete-tax-regions.ts

@@ -2,13 +2,18 @@ import { ITaxModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the tax regions to delete.
+ */
+export type DeleteTaxRegionsStepInput = string[]
+
 export const deleteTaxRegionsStepId = "delete-tax-regions"
 /**
  * This step deletes one or more tax regions.
  */
 export const deleteTaxRegionsStep = createStep(
   deleteTaxRegionsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteTaxRegionsStepInput, { container }) => {
     const service = container.resolve<ITaxModuleService>(Modules.TAX)
 
     await service.softDeleteTaxRegions(ids)

packages/core/core-flows/src/tax/steps/get-item-tax-lines.ts

@@ -15,12 +15,35 @@ import {
 import { MedusaError, Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to retrieve tax lines for an order or cart's line items and shipping methods.
+ */
 export interface GetItemTaxLinesStepInput {
+  /**
+   * The order or cart details.
+   */
   orderOrCart: OrderWorkflowDTO | CartWorkflowDTO
+  /**
+   * The order or cart's items.
+   */
   items: OrderLineItemDTO[] | CartLineItemDTO[]
+  /**
+   * The order or cart's shipping methods.
+   */
   shipping_methods: OrderShippingMethodDTO[] | CartShippingMethodDTO[]
+  /**
+   * Whether to re-calculate taxes. Enabling this may require sending
+   * requests to third-party services, depending on the implementation of the
+   * tax provider associated with the cart or order's region.
+   */
   force_tax_calculation?: boolean
+  /**
+   * Whether the tax lines are for an order return.
+   */
   is_return?: boolean
+  /**
+   * The shipping address of the order.
+   */
   shipping_address?: OrderWorkflowDTO["shipping_address"]
 }
 
@@ -105,7 +128,34 @@ function normalizeLineItemsForShipping(
 
 export const getItemTaxLinesStepId = "get-item-tax-lines"
 /**
- * This step retrieves the tax lines for an order's line items and shipping methods.
+ * This step retrieves the tax lines for an order or cart's line items and shipping methods.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order, cart, item, shipping method, and address 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 = getItemTaxLinesStep({
+ *   orderOrCart: {
+ *     id: "order_123",
+ *     // other order details...
+ *   },
+ *   items: [
+ *     {
+ *       id: "orli_123",
+ *       // other order item details...
+ *     }
+ *   ],
+ *   shipping_methods: [
+ *     {
+ *       id: "osm_213",
+ *       // other shipping method details...
+ *     }
+ *   ],
+ * })
  */
 export const getItemTaxLinesStep = createStep(
   getItemTaxLinesStepId,