chore(core-flows): [5] export types and types, add basic TSDocs (#8510)

This PR exports types and steps from the core-flows package, and adds simple TSDocs for workflows / steps. This is essential for the workflows reference. PR 5/n
medusajs · Aug 8, 2024 · f9989e1 · f9989e1
1 parent cb6796f
commit f9989e1
Show file tree

Hide file tree

Showing 28 changed files with 116 additions and 37 deletions.
diff --git a/packages/core/core-flows/src/fulfillment/steps/add-shipping-options-prices.ts b/packages/core/core-flows/src/fulfillment/steps/add-shipping-options-prices.ts
@@ -6,23 +6,23 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
-interface PriceCurrencyCode {
+export interface ShippingOptionsPriceCurrencyCode {
   currency_code: string
   amount: number
 }
 
-interface PriceRegionId {
+interface ShippingOptionsPriceRegionId {
   region_id: string
   amount: number
 }
 
-type StepInput = {
+export type CreateShippingOptionsPriceSetsStepInput = {
   id: string
-  prices: (PriceCurrencyCode | PriceRegionId)[]
+  prices: (ShippingOptionsPriceCurrencyCode | ShippingOptionsPriceRegionId)[]
 }[]
 
 function buildPriceSet(
-  prices: StepInput[0]["prices"],
+  prices: CreateShippingOptionsPriceSetsStepInput[0]["prices"],
   regionToCurrencyMap: Map<string, string>
 ): CreatePriceSetDTO {
   const shippingOptionPrices = prices.map((price) => {
@@ -47,17 +47,20 @@ function buildPriceSet(
 
 export const createShippingOptionsPriceSetsStepId =
   "add-shipping-options-prices-step"
+/**
+ * This step creates price sets for one or more shipping options.
+ */
 export const createShippingOptionsPriceSetsStep = createStep(
   createShippingOptionsPriceSetsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: CreateShippingOptionsPriceSetsStepInput, { container }) => {
     if (!data?.length) {
       return new StepResponse([], [])
     }
 
     const regionIds = data
       .map((input) => input.prices)
       .flat()
-      .filter((price): price is PriceRegionId => {
+      .filter((price): price is ShippingOptionsPriceRegionId => {
         return "region_id" in price
       })
       .map((price) => price.region_id)

diff --git a/packages/core/core-flows/src/fulfillment/steps/cancel-fulfillment.ts b/packages/core/core-flows/src/fulfillment/steps/cancel-fulfillment.ts
@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const cancelFulfillmentStepId = "cancel-fulfillment"
+/**
+ * This step cancels a fulfillment.
+ */
 export const cancelFulfillmentStep = createStep(
   cancelFulfillmentStepId,
   async (id: string, { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/create-fulfillment-set.ts b/packages/core/core-flows/src/fulfillment/steps/create-fulfillment-set.ts
@@ -6,6 +6,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createFulfillmentSetsId = "create-fulfillment-sets"
+/**
+ * This step creates one or more fulfillment sets.
+ */
 export const createFulfillmentSets = createStep(
   createFulfillmentSetsId,
   async (data: CreateFulfillmentSetDTO[], { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/create-fulfillment.ts b/packages/core/core-flows/src/fulfillment/steps/create-fulfillment.ts
@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createFulfillmentStepId = "create-fulfillment"
+/**
+ * This step creates a fulfillment
+ */
 export const createFulfillmentStep = createStep(
   createFulfillmentStepId,
   async (data: FulfillmentTypes.CreateFulfillmentDTO, { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/create-return-fulfillment.ts b/packages/core/core-flows/src/fulfillment/steps/create-return-fulfillment.ts
@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createReturnFulfillmentStepId = "create-return-fulfillment"
+/**
+ * This step creates a fulfillment for a return.
+ */
 export const createReturnFulfillmentStep = createStep(
   createReturnFulfillmentStepId,
   async (data: FulfillmentTypes.CreateFulfillmentDTO, { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/create-service-zones.ts b/packages/core/core-flows/src/fulfillment/steps/create-service-zones.ts
@@ -5,12 +5,13 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = CreateServiceZoneDTO[]
-
 export const createServiceZonesStepId = "create-service-zones"
+/**
+ * This step creates one or more service zones.
+ */
 export const createServiceZonesStep = createStep(
   createServiceZonesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: CreateServiceZoneDTO[], { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       ModuleRegistrationName.FULFILLMENT
     )

diff --git a/packages/core/core-flows/src/fulfillment/steps/create-shipping-option-rules.ts b/packages/core/core-flows/src/fulfillment/steps/create-shipping-option-rules.ts
@@ -6,6 +6,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createShippingOptionRulesStepId = "create-shipping-option-rules"
+/**
+ * This step creates one or more shipping option rules.
+ */
 export const createShippingOptionRulesStep = createStep(
   createShippingOptionRulesStepId,
   async (

diff --git a/packages/core/core-flows/src/fulfillment/steps/create-shipping-profiles.ts b/packages/core/core-flows/src/fulfillment/steps/create-shipping-profiles.ts
@@ -5,12 +5,13 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = CreateShippingProfileDTO[]
-
 export const createShippingProfilesStepId = "create-shipping-profiles"
+/**
+ * This step creates one or more shipping profiles.
+ */
 export const createShippingProfilesStep = createStep(
   createShippingProfilesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: CreateShippingProfileDTO[], { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       ModuleRegistrationName.FULFILLMENT
     )

diff --git a/packages/core/core-flows/src/fulfillment/steps/delete-fulfillment-sets.ts b/packages/core/core-flows/src/fulfillment/steps/delete-fulfillment-sets.ts
@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
 export const deleteFulfillmentSetsStepId = "delete-fulfillment-sets"
+/**
+ * This step deletes one or more fulfillment sets.
+ */
 export const deleteFulfillmentSetsStep = createStep(
   deleteFulfillmentSetsStepId,
   async (ids: string[], { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/delete-service-zones.ts b/packages/core/core-flows/src/fulfillment/steps/delete-service-zones.ts
@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const deleteServiceZonesStepId = "delete-service-zones"
+/**
+ * This step deletes one or more service zones.
+ */
 export const deleteServiceZonesStep = createStep(
   deleteServiceZonesStepId,
   async (ids: string[], { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/delete-shipping-option-rules.ts b/packages/core/core-flows/src/fulfillment/steps/delete-shipping-option-rules.ts
@@ -7,6 +7,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const deleteShippingOptionRulesStepId = "delete-shipping-option-rules"
+/**
+ * This step deletes one or more shipping option rules.
+ */
 export const deleteShippingOptionRulesStep = createStep(
   deleteShippingOptionRulesStepId,
   async (

diff --git a/packages/core/core-flows/src/fulfillment/steps/delete-shipping-options.ts b/packages/core/core-flows/src/fulfillment/steps/delete-shipping-options.ts
@@ -4,6 +4,9 @@ import { ModuleRegistrationName, Modules } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
 export const deleteShippingOptionsStepId = "delete-shipping-options-step"
+/**
+ * This step deletes one or more shipping options.
+ */
 export const deleteShippingOptionsStep = createStep(
   deleteShippingOptionsStepId,
   async (ids: string[], { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-price-sets.ts b/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-price-sets.ts
@@ -9,7 +9,7 @@ import {
   remoteQueryObjectFromString,
 } from "@medusajs/utils"
 
-type SetShippingOptionsPriceSetsStepInput = {
+export type SetShippingOptionsPriceSetsStepInput = {
   id: string
   price_sets?: string[]
 }[]
@@ -56,6 +56,9 @@ async function getCurrentShippingOptionPriceSetsLinks(
 
 export const setShippingOptionsPriceSetsStepId =
   "set-shipping-options-price-sets-step"
+/**
+ * This step sets the price sets of one or more shipping options.
+ */
 export const setShippingOptionsPriceSetsStep = createStep(
   setShippingOptionsPriceSetsStepId,
   async (data: SetShippingOptionsPriceSetsStepInput, { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-prices.ts b/packages/core/core-flows/src/fulfillment/steps/set-shipping-options-prices.ts
@@ -22,7 +22,7 @@ interface PriceRegionId {
   amount: number
 }
 
-type SetShippingOptionsPricesStepInput = {
+export type SetShippingOptionsPricesStepInput = {
   id: string
   prices?: FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput["prices"]
 }[]
@@ -89,6 +89,9 @@ function buildPrices(
 }
 
 export const setShippingOptionsPricesStepId = "set-shipping-options-prices-step"
+/**
+ * This step sets the prices of one or more shipping options.
+ */
 export const setShippingOptionsPricesStep = createStep(
   setShippingOptionsPricesStepId,
   async (data: SetShippingOptionsPricesStepInput, { container }) => {

diff --git a/packages/core/core-flows/src/fulfillment/steps/update-fulfillment.ts b/packages/core/core-flows/src/fulfillment/steps/update-fulfillment.ts
@@ -6,6 +6,9 @@ import {
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const updateFulfillmentStepId = "update-fulfillment"
+/**
+ * This step updates a fulfillment.
+ */
 export const updateFulfillmentStep = createStep(
   updateFulfillmentStepId,
   async (

diff --git a/packages/core/core-flows/src/fulfillment/steps/update-service-zones.ts b/packages/core/core-flows/src/fulfillment/steps/update-service-zones.ts
@@ -5,12 +5,13 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = FulfillmentWorkflow.UpdateServiceZonesWorkflowInput
-
 export const updateServiceZonesStepId = "update-service-zones"
+/**
+ * This step updates service zones matching the specified filters.
+ */
 export const updateServiceZonesStep = createStep(
   updateServiceZonesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: FulfillmentWorkflow.UpdateServiceZonesWorkflowInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       ModuleRegistrationName.FULFILLMENT
     )

diff --git a/packages/core/core-flows/src/fulfillment/steps/update-shipping-option-rules.ts b/packages/core/core-flows/src/fulfillment/steps/update-shipping-option-rules.ts
@@ -7,6 +7,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const updateShippingOptionRulesStepId = "update-shipping-option-rules"
+/**
+ * This step updates one or more shipping option rules.
+ */
 export const updateShippingOptionRulesStep = createStep(
   updateShippingOptionRulesStepId,
   async (

diff --git a/packages/core/core-flows/src/fulfillment/steps/update-shipping-profiles.ts b/packages/core/core-flows/src/fulfillment/steps/update-shipping-profiles.ts
@@ -9,15 +9,18 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = {
+export type UpdateShippingProfilesStepInput = {
   update: UpdateShippingProfileDTO
   selector: FilterableShippingProfileProps
 }
 
 export const updateShippingProfilesStepId = "update-shipping-profiles"
+/**
+ * This step updates shipping profiles matching the specified filters.
+ */
 export const updateShippingProfilesStep = createStep(
   updateShippingProfilesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: UpdateShippingProfilesStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       ModuleRegistrationName.FULFILLMENT
     )

diff --git a/packages/core/core-flows/src/fulfillment/steps/upsert-shipping-options.ts b/packages/core/core-flows/src/fulfillment/steps/upsert-shipping-options.ts
@@ -11,16 +11,19 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = Omit<
+export type UpsertShippingOptionsStepInput = Omit<
   | FulfillmentWorkflow.CreateShippingOptionsWorkflowInput
   | FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput,
   "prices"
 >[]
 
 export const upsertShippingOptionsStepId = "create-shipping-options-step"
+/**
+ * This step creates or updates shipping options.
+ */
 export const upsertShippingOptionsStep = createStep(
   upsertShippingOptionsStepId,
-  async (input: StepInput, { container }) => {
+  async (input: UpsertShippingOptionsStepInput, { container }) => {
     if (!input?.length) {
       return new StepResponse([], {})
     }

diff --git a/packages/core/core-flows/src/fulfillment/steps/validate-fulfillment-providers.ts b/packages/core/core-flows/src/fulfillment/steps/validate-fulfillment-providers.ts
@@ -7,17 +7,21 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type FulfillmentProviderValidationInput = {
+export type FulfillmentProviderValidationWorkflowInput = {
   id?: string
   service_zone_id?: string
   provider_id?: string
 }
 
 export const validateFulfillmentProvidersStepId =
   "validate-fulfillment-providers-step"
+/**
+ * This step validates that the specified fulfillment providers are available in the
+ * specified service zones.
+ */
 export const validateFulfillmentProvidersStep = createStep(
   validateFulfillmentProvidersStepId,
-  async (input: FulfillmentProviderValidationInput[], { container }) => {
+  async (input: FulfillmentProviderValidationWorkflowInput[], { container }) => {
     const dataToValidate: {
       service_zone_id: string
       provider_id: string

diff --git a/packages/core/core-flows/src/fulfillment/steps/validate-shipment.ts b/packages/core/core-flows/src/fulfillment/steps/validate-shipment.ts
@@ -3,6 +3,9 @@ import { MedusaError, ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
 export const validateShipmentStepId = "validate-shipment"
+/**
+ * This step validates that a shipment can be created for a fulfillment.
+ */
 export const validateShipmentStep = createStep(
   validateShipmentStepId,
   async (id: string, { container }) => {

diff --git a/packages/core/core-flows/src/inventory/workflows/bulk-create-delete-levels.ts b/packages/core/core-flows/src/inventory/workflows/bulk-create-delete-levels.ts
@@ -9,17 +9,20 @@ import {
   deleteInventoryLevelsFromItemAndLocationsStep,
 } from "../steps"
 
-interface WorkflowInput {
+export interface BulkCreateDeleteLevelsWorkflowInput {
   creates: InventoryTypes.CreateInventoryLevelInput[]
   deletes: { inventory_item_id: string; location_id: string }[]
 }
 
 export const bulkCreateDeleteLevelsWorkflowId =
   "bulk-create-delete-levels-workflow"
+/**
+ * This workflow creates and deletes inventory levels.
+ */
 export const bulkCreateDeleteLevelsWorkflow = createWorkflow(
   bulkCreateDeleteLevelsWorkflowId,
   (
-    input: WorkflowData<WorkflowInput>
+    input: WorkflowData<BulkCreateDeleteLevelsWorkflowInput>
   ): WorkflowResponse<InventoryLevelDTO[]> => {
     deleteInventoryLevelsFromItemAndLocationsStep(input.deletes)
 

diff --git a/packages/core/core-flows/src/inventory/workflows/create-inventory-items.ts b/packages/core/core-flows/src/inventory/workflows/create-inventory-items.ts
@@ -13,13 +13,13 @@ type LocationLevelWithoutInventory = Omit<
   InventoryTypes.CreateInventoryLevelInput,
   "inventory_item_id"
 >
-interface WorkflowInput {
+export interface CreateInventoryItemsWorkflowInput {
   items: (InventoryTypes.CreateInventoryItemInput & {
     location_levels?: LocationLevelWithoutInventory[]
   })[]
 }
 
-const buildLocationLevelMapAndItemData = (data: WorkflowInput) => {
+const buildLocationLevelMapAndItemData = (data: CreateInventoryItemsWorkflowInput) => {
   data.items = data.items ?? []
   const inventoryItems: InventoryTypes.CreateInventoryItemInput[] = []
   // Keep an index to location levels mapping to inject the created inventory item
@@ -66,9 +66,12 @@ const buildInventoryLevelsInput = (data: {
 }
 
 export const createInventoryItemsWorkflowId = "create-inventory-items-workflow"
+/**
+ * This workflow creates one or more inventory items.
+ */
 export const createInventoryItemsWorkflow = createWorkflow(
   createInventoryItemsWorkflowId,
-  (input: WorkflowData<WorkflowInput>) => {
+  (input: WorkflowData<CreateInventoryItemsWorkflowInput>) => {
     const { locationLevelMap, inventoryItems } = transform(
       input,
       buildLocationLevelMapAndItemData