chore(core-flows, types): improve TSDocs of tax and region related workflows (#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,

packages/core/core-flows/src/tax/steps/list-tax-rate-ids.ts

@@ -5,13 +5,26 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to retrieve the tax rate IDs.
+ */
 export type ListTaxRateIdsStepInput = {
+  /**
+   * The filters to select the tax rates.
+   */
   selector: FilterableTaxRateProps
 }
 
 export const listTaxRateIdsStepId = "list-tax-rate-ids"
 /**
  * This step retrieves the IDs of tax rates matching the specified filters.
+ * 
+ * @example
+ * const data = listTaxRateIdsStep({
+ *   selector: {
+ *     tax_region_id: "txreg_123"
+ *   }
+ * })
  */
 export const listTaxRateIdsStep = createStep(
   listTaxRateIdsStepId,

packages/core/core-flows/src/tax/steps/list-tax-rate-rule-ids.ts

@@ -5,13 +5,26 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to retrieve the tax rate rule IDs.
+ */
 export type ListTaxRateRuleIdsStepInput = {
+  /**
+   * The filters to select the tax rate rules.
+   */
   selector: FilterableTaxRateRuleProps
 }
 
 export const listTaxRateRuleIdsStepId = "list-tax-rate-rule-ids"
 /**
  * This step retrieves the IDs of tax rate rules matching the specified filters.
+ * 
+ * @example
+ * const data = listTaxRateRuleIdsStep({
+ *   selector: {
+ *     tax_rate_id: "txr_123"
+ *   }
+ * })
  */
 export const listTaxRateRuleIdsStep = createStep(
   listTaxRateRuleIdsStepId,

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

@@ -9,14 +9,33 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to update tax rates.
+ */
 export type UpdateTaxRatesStepInput = {
+  /**
+   * The filters to select the tax rates to update.
+   */
   selector: FilterableTaxRateProps
+  /**
+   * The data to update in the tax rates.
+   */
   update: UpdateTaxRateDTO
 }
 
 export const updateTaxRatesStepId = "update-tax-rates"
 /**
  * This step updates tax rates matching the specified filters.
+ * 
+ * @example
+ * const data = updateTaxRatesStep({
+ *   selector: {
+ *     id: "txr_123"
+ *   },
+ *   update: {
+ *     name: "Default Tax Rate",
+ *   }
+ * })
  */
 export const updateTaxRatesStep = createStep(
   updateTaxRatesStepId,

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

@@ -9,9 +9,22 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The tax regions to update.
+ */
+export type UpdateTaxRegionsStepInput = UpdateTaxRegionDTO[]
+
 export const updateTaxRegionsStepId = "update-tax-regions"
 /**
- * This step updates tax regions
+ * This step updates tax regions.
+ * 
+ * @example
+ * const data = updateTaxRegionsStep([
+ *   {
+ *     id: "txreg_123",
+ *     province_code: "CA",
+ *   }
+ * ])
  */
 export const updateTaxRegionsStep = createStep(
   updateTaxRegionsStepId,

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

@@ -6,19 +6,52 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { createTaxRateRulesStep } from "../steps"
 
+/**
+ * The data to create tax rules for rates.
+ */
 export type CreateTaxRateRulesWorkflowInput = {
+  /**
+   * The rules to create.
+   */
   rules: CreateTaxRateRuleDTO[]
 }
 
+/**
+ * The created tax rules for rates.
+ */
+export type CreateTaxRateRulesWorkflowOutput = TaxRateRuleDTO[]
+
 export const createTaxRateRulesWorkflowId = "create-tax-rate-rules"
 /**
- * This workflow creates one or more tax rate rules.
+ * This workflow creates one or more tax rules for rates. It's used by the
+ * [Create Tax Rules for Rates Admin API Route](https://docs.medusajs.com/api/admin#tax-rates_posttaxratesidrules).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to create tax rules for rates in your custom flows.
+ * 
+ * @example
+ * const { result } = await createTaxRateRulesWorkflow(container)
+ * .run({
+ *   input: {
+ *     rules: [
+ *       {
+ *         tax_rate_id: "txr_123",
+ *         reference: "product_type",
+ *         reference_id: "ptyp_123"
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more tax rules for rates.
  */
 export const createTaxRateRulesWorkflow = createWorkflow(
   createTaxRateRulesWorkflowId,
   (
     input: WorkflowData<CreateTaxRateRulesWorkflowInput>
-  ): WorkflowResponse<TaxRateRuleDTO[]> => {
+  ): WorkflowResponse<CreateTaxRateRulesWorkflowOutput> => {
     return new WorkflowResponse(createTaxRateRulesStep(input.rules))
   }
 )

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

@@ -6,13 +6,44 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { createTaxRatesStep } from "../steps"
 
+/**
+ * The tax rates to create.
+ */
+export type CreateTaxRatesWorkflowInput = CreateTaxRateDTO[]
+
+/**
+ * The created tax rates.
+ */
+export type CreateTaxRatesWorkflowOutput = TaxRateDTO[]
+
 export const createTaxRatesWorkflowId = "create-tax-rates"
 /**
- * This workflow creates one or more tax rates.
+ * This workflow creates one or more tax rates. It's used by the
+ * [Create Tax Rates Admin API Route](https://docs.medusajs.com/api/admin#tax-rates_posttaxrates).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to create tax rates in your custom flows.
+ * 
+ * @example
+ * const { result } = await createTaxRatesWorkflow(container)
+ * .run({
+ *   input: [
+ *     {
+ *       tax_region_id: "txreg_123",
+ *       name: "Default"
+ *     }
+ *   ]
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more tax rates.
  */
 export const createTaxRatesWorkflow = createWorkflow(
   createTaxRatesWorkflowId,
-  (input: WorkflowData<CreateTaxRateDTO[]>): WorkflowResponse<TaxRateDTO[]> => {
+  (input: WorkflowData<CreateTaxRatesWorkflowInput>): WorkflowResponse<
+    CreateTaxRatesWorkflowOutput
+  > => {
     return new WorkflowResponse(createTaxRatesStep(input))
   }
 )

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

@@ -6,15 +6,43 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { createTaxRegionsStep } from "../steps"
 
+/**
+ * The tax regions to create.
+ */
+export type CreateTaxRegionsWorkflowInput = CreateTaxRegionDTO[]
+
+/**
+ * The created tax regions.
+ */
+export type CreateTaxRegionsWorkflowOutput = TaxRegionDTO[]
+
 export const createTaxRegionsWorkflowId = "create-tax-regions"
 /**
- * This workflow creates one or more tax regions.
+ * This workflow creates one or more tax regions. It's used by the
+ * [Create Tax Region Admin API Route](https://docs.medusajs.com/api/admin#tax-regions_posttaxregions).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to create tax regions in your custom flows.
+ * 
+ * @example
+ * const { result } = await createTaxRegionsWorkflow(container)
+ * .run({
+ *   input: [
+ *     {
+ *       country_code: "us",
+ *     }
+ *   ]
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more tax regions.
  */
 export const createTaxRegionsWorkflow = createWorkflow(
   createTaxRegionsWorkflowId,
   (
-    input: WorkflowData<CreateTaxRegionDTO[]>
-  ): WorkflowResponse<TaxRegionDTO[]> => {
+    input: WorkflowData<CreateTaxRegionsWorkflowInput>
+  ): WorkflowResponse<CreateTaxRegionsWorkflowOutput> => {
     return new WorkflowResponse(createTaxRegionsStep(input))
   }
 )

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

@@ -5,11 +5,35 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { deleteTaxRateRulesStep } from "../steps"
 
-export type DeleteTaxRateRulesWorkflowInput = { ids: string[] }
+/**
+ * The data to delete tax rate rules.
+ */
+export type DeleteTaxRateRulesWorkflowInput = { 
+  /**
+   * The IDs of the tax rate rules to delete.
+   */
+  ids: string[]
+}
 
 export const deleteTaxRateRulesWorkflowId = "delete-tax-rate-rules"
 /**
- * This workflow deletes one or more tax rate rules.
+ * This workflow deletes one or more tax rate rules. It's used by the
+ * [Remove Rule of Tax Rate Admin API Route](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratesidrulesrule_id).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to delete tax rate rules in your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteTaxRateRulesWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["txrr_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more tax rate rules.
  */
 export const deleteTaxRateRulesWorkflow = createWorkflow(
   deleteTaxRateRulesWorkflowId,

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

@@ -5,11 +5,35 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { deleteTaxRatesStep } from "../steps"
 
-export type DeleteTaxRatesWorkflowInput = { ids: string[] }
+/**
+ * The data to delete tax rates.
+ */
+export type DeleteTaxRatesWorkflowInput = { 
+  /**
+   * The IDs of the tax rates to delete.
+   */
+  ids: string[]
+}
 
 export const deleteTaxRatesWorkflowId = "delete-tax-rates"
 /**
- * This workflow deletes one or more tax rates.
+ * This workflow deletes one or more tax rates. It's used by the
+ * [Delete Tax Rates Admin API Route](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratesid).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to delete tax rates in your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteTaxRatesWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["txr_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more tax rates.
  */
 export const deleteTaxRatesWorkflow = createWorkflow(
   deleteTaxRatesWorkflowId,

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

@@ -5,11 +5,35 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { deleteTaxRegionsStep } from "../steps"
 
-export type DeleteTaxRegionsWorkflowInput = { ids: string[] }
+/**
+ * The data to delete tax regions.
+ */
+export type DeleteTaxRegionsWorkflowInput = { 
+  /**
+   * The IDs of the tax regions to delete.
+   */
+  ids: string[]
+}
 
 export const deleteTaxRegionsWorkflowId = "delete-tax-regions"
 /**
- * This workflow deletes one or more tax regions.
+ * This workflow deletes one or more tax regions. It's used by the
+ * [Delete Tax Region Admin API Route](https://docs.medusajs.com/api/admin#tax-regions_deletetaxregionsid).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to delete tax regions in your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteTaxRegionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["txreg_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more tax regions.
  */
 export const deleteTaxRegionsWorkflow = createWorkflow(
   deleteTaxRegionsWorkflowId,

packages/core/core-flows/src/tax/workflows/set-tax-rate-rules.ts

@@ -11,14 +11,44 @@ import {
   listTaxRateRuleIdsStep,
 } from "../steps"
 
+/**
+ * The data to set the rules for tax rates.
+ */
 export type SetTaxRatesRulesWorkflowInput = {
+  /**
+   * The IDs of the tax rates to set their rules.
+   */
   tax_rate_ids: string[]
+  /**
+   * The rules to create for the tax rates.
+   */
   rules: Omit<CreateTaxRateRuleDTO, "tax_rate_id">[]
 }
 
 export const setTaxRateRulesWorkflowId = "set-tax-rate-rules"
 /**
  * This workflow sets the rules of tax rates.
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to set the rules of tax rates in your custom flows.
+ * 
+ * @example
+ * const { result } = await setTaxRateRulesWorkflow(container)
+ * .run({
+ *   input: {
+ *     tax_rate_ids: ["txr_123"],
+ *     rules: [
+ *       {
+ *         reference: "product_type",
+ *         reference_id: "ptyp_123"
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Set the rules of tax rates.
  */
 export const setTaxRateRulesWorkflow = createWorkflow(
   setTaxRateRulesWorkflowId,

packages/core/core-flows/src/tax/workflows/update-tax-rates.ts

@@ -20,13 +20,36 @@ import {
 } from "../steps"
 // import { setTaxRateRulesWorkflow } from "./set-tax-rate-rules"
 
+/**
+ * The data to update tax rates.
+ */
 export type UpdateTaxRatesWorkflowInput = {
+  /**
+   * The filters to select the tax rates to update.
+   */
   selector: FilterableTaxRateProps
+  /**
+   * The data to update in the tax rates.
+   */
   update: UpdateTaxRateDTO
 }
 
+/**
+ * The updated tax rates.
+ */
+export type UpdateTaxRatesWorkflowOutput = TaxRateDTO[]
+
+/**
+ * The data to retrieve the IDs of tax rate rules.
+ */
 export type MaybeListTaxRateRuleIdsStepInput = {
+  /**
+   * The IDs of the tax rates to retrieve their rules.
+   */
   tax_rate_ids: string[]
+  /**
+   * The data to update in the tax rates.
+   */
   update: UpdateTaxRateDTO
 }
 
@@ -65,6 +88,14 @@ export type MaybeListTaxRateRuleIdsStepInput = {
 const maybeListTaxRateRuleIdsStepId = "maybe-list-tax-rate-rule-ids"
 /**
  * This step lists the rules to update in a tax rate update object.
+ * 
+ * @example
+ * const data = maybeListTaxRateRuleIdsStep({
+ *   tax_rate_ids: ["txr_123"],
+ *   update: {
+ *     code: "VAT",
+ *   }
+ * })
  */
 export const maybeListTaxRateRuleIdsStep = createStep(
   maybeListTaxRateRuleIdsStepId,
@@ -88,13 +119,34 @@ export const maybeListTaxRateRuleIdsStep = createStep(
 
 export const updateTaxRatesWorkflowId = "update-tax-rates"
 /**
- * This workflow updates tax rates matching specified filters.
+ * This workflow updates tax rates matching specified filters. It's used by the
+ * [Update Tax Rates Admin API Route](https://docs.medusajs.com/api/admin#tax-rates_posttaxratesid).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to update tax rates in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateTaxRatesWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       id: ["txr_123"]
+ *     },
+ *     update: {
+ *       code: "VAT"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update tax rates.
  */
 export const updateTaxRatesWorkflow = createWorkflow(
   updateTaxRatesWorkflowId,
   (
     input: WorkflowData<UpdateTaxRatesWorkflowInput>
-  ): WorkflowResponse<TaxRateDTO[]> => {
+  ): WorkflowResponse<UpdateTaxRatesWorkflowOutput> => {
     const cleanedUpdateInput = transform(input, (data) => {
       // Transform clones data so we can safely modify it
       if (data.update.rules) {

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

@@ -6,15 +6,44 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { updateTaxRegionsStep } from "../steps/update-tax-regions"
 
+/**
+ * The tax regions to update.
+ */
+export type UpdateTaxRegionsWorkflowInput = UpdateTaxRegionDTO[]
+
+/**
+ * The updated tax regions.
+ */
+export type UpdateTaxRegionsWorkflowOutput = TaxRegionDTO[]
+
 export const updateTaxRegionsWorkflowId = "update-tax-regions"
 /**
- * This workflow updates one or more tax regions.
+ * This workflow updates one or more tax regions. It's used by the
+ * [Update Tax Regions Admin API Route](https://docs.medusajs.com/api/admin#tax-regions_posttaxregionsid).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to update tax regions in your custom flows.
+ * 
+ * @example
+ * const { result } = await updateTaxRegionsWorkflow(container)
+ * .run({
+ *   input: [
+ *     {
+ *       id: "txreg_123",
+ *       province_code: "CA",
+ *     }
+ *   ]
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more tax regions.
  */
 export const updateTaxRegionsWorkflow = createWorkflow(
   updateTaxRegionsWorkflowId,
   (
-    input: WorkflowData<UpdateTaxRegionDTO[]>
-  ): WorkflowResponse<TaxRegionDTO[]> => {
+    input: WorkflowData<UpdateTaxRegionsWorkflowInput>
+  ): WorkflowResponse<UpdateTaxRegionsWorkflowOutput> => {
     return new WorkflowResponse(updateTaxRegionsStep(input))
   }
 )

packages/core/types/src/workflow/region/create-regions.ts

@@ -1,10 +1,27 @@
 import { CreateRegionDTO, RegionDTO } from "../../region"
 
+/**
+ * The data to create regions.
+ */
 export interface CreateRegionsWorkflowInput {
+  /**
+   * The regions to create.
+   */
   regions: (CreateRegionDTO & {
+    /**
+     * The IDs of payment providers that are available in the region.
+     */
     payment_providers?: string[]
+    /**
+     * Whether prices in the region are tax inclusive.
+     * 
+     * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/pricing/tax-inclusive-pricing).
+     */
     is_tax_inclusive?: boolean
   })[]
 }
 
+/**
+ * The created regions.
+ */
 export type CreateRegionsWorkflowOutput = RegionDTO[]