feat(core-flows,fulfillment, fulfillment-manual, types): make fulfillment typings more specific (#10677)

**What**
- attempt to add more specific type definitions around fulfillment provider APIs

---

CLOSES CMRC-814
CLOSES CMRC-816
CLOSES CMRC-817

integration-tests/http/src/utils/providers/fulfillment-manual-calculated/services/manual-fulfillment.ts

@@ -41,7 +41,10 @@ export class ManualFulfillmentService extends AbstractFulfillmentProviderService
 
   async createFulfillment() {
     // No data is being sent anywhere
-    return {}
+    return {
+      data: {},
+      labels: [],
+    }
   }
 
   async cancelFulfillment() {
@@ -49,6 +52,6 @@ export class ManualFulfillmentService extends AbstractFulfillmentProviderService
   }
 
   async createReturnFulfillment() {
-    return {}
+    return { data: {}, labels: [] }
   }
 }

packages/core/core-flows/src/cart/steps/validate-shipping-methods-data.ts

@@ -1,8 +1,7 @@
 import { Modules, promiseAll } from "@medusajs/framework/utils"
 import {
-  CartDTO,
   IFulfillmentModuleService,
-  StockLocationDTO,
+  ValidateFulfillmentDataContext,
 } from "@medusajs/types"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
@@ -11,7 +10,7 @@ export type ValidateShippingMethodsDataInput = {
   provider_id: string
   option_data: Record<string, unknown>
   method_data: Record<string, unknown>
-  context: CartDTO & { from_location: StockLocationDTO; [k: string]: unknown }
+  context: ValidateFulfillmentDataContext
 }[]
 
 export const validateAndReturnShippingMethodsDataStepId =
@@ -38,7 +37,7 @@ export const validateAndReturnShippingMethodsDataStep = createStep(
           option.provider_id,
           option.option_data,
           option.method_data,
-          option.context
+          option.context as ValidateFulfillmentDataContext
         )
 
         return {

packages/core/types/src/fulfillment/common/cart.ts

@@ -0,0 +1,29 @@
+import { CartDTO } from "../.."
+
+export type CartPropsForFulfillment = {
+  id: CartDTO["id"]
+  shipping_address: CartDTO["shipping_address"]
+  items: CartDTO["items"] & {
+    variant: {
+      id: string
+      weight: number
+      length: number
+      height: number
+      width: number
+      material: string
+      product: {
+        id: string
+      }
+    }
+    product: {
+      id: string
+      collection_id: string
+      categories: {
+        id: string
+      }[]
+      tags: {
+        id: string
+      }[]
+    }
+  }
+}

packages/core/types/src/fulfillment/common/index.ts

@@ -10,3 +10,5 @@ export * from "./fulfillment-provider"
 export * from "./fulfillment"
 export * from "./fulfillment-item"
 export * from "./fulfillment-label"
+export * from "./cart"
+export * from "./order"

packages/core/types/src/fulfillment/mutations/shipping-option.ts

@@ -1,7 +1,6 @@
 import { CreateShippingOptionTypeDTO } from "./shipping-option-type"
-import { ShippingOptionPriceType } from "../common"
+import { CartPropsForFulfillment, ShippingOptionPriceType } from "../common"
 import { CreateShippingOptionRuleDTO } from "./shipping-option-rule"
-import { CartDTO } from "../../cart"
 import { StockLocationDTO } from "../../stock-location"
 
 /**
@@ -148,13 +147,17 @@ export interface CalculateShippingOptionPriceDTO {
   /**
    * The calculation context needed for the associated fulfillment provider to calculate the price of a shipping option.
    */
-  context: CartDTO & { 
+  context: CartPropsForFulfillment & {
     /**
      * The location that the items will be shipped from.
      */
     from_location?: StockLocationDTO
-  } & Record<
+    [k: string]: unknown
-      string,
+  }
-      unknown
-    >
 }
+
+/**
+ * The calculation context needed for the associated fulfillment provider to calculate the price of a shipping option.
+ */
+export type CalculateShippingOptionPriceContext =
+  CalculateShippingOptionPriceDTO["context"]

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

@@ -1,4 +1,15 @@
-import { CalculateShippingOptionPriceDTO } from "./mutations"
+import { StockLocationDTO } from "../stock-location"
+import {
+  CartPropsForFulfillment,
+  FulfillmentDTO,
+  FulfillmentItemDTO,
+  FulfillmentOrderDTO,
+} from "./common"
+import {
+  CalculateShippingOptionPriceContext,
+  CalculateShippingOptionPriceDTO,
+  CreateShippingOptionDTO,
+} from "./mutations"
 
 export type FulfillmentOption = {
   /**
@@ -28,6 +39,37 @@ export type CalculatedShippingOptionPrice = {
   is_calculated_price_tax_inclusive: boolean
 }
 
+export type ValidateFulfillmentDataContext = CartPropsForFulfillment & {
+  /**
+   * Details about the location that items are being shipped from.
+   */
+  from_location: StockLocationDTO
+  [k: string]: unknown
+}
+
+export type CreateFulfillmentResult = {
+  /**
+   * Additional fulfillment data from provider
+   */
+  data: Record<string, unknown>
+  labels: {
+    /**
+     * The tracking number of the fulfillment label.
+     */
+    tracking_number: string
+
+    /**
+     * The tracking URL of the fulfillment label.
+     */
+    tracking_url: string
+
+    /**
+     * The label's URL.
+     */
+    label_url: string
+  }[]
+}
+
 export interface IFulfillmentProvider {
   /**
    *
@@ -46,7 +88,7 @@ export interface IFulfillmentProvider {
   validateFulfillmentData(
     optionData: Record<string, unknown>,
     data: Record<string, unknown>,
-    context: Record<string, unknown>
+    context: ValidateFulfillmentDataContext
   ): Promise<any>
   /**
    *
@@ -57,7 +99,7 @@ export interface IFulfillmentProvider {
    *
    * Check if the provider can calculate the fulfillment price.
    */
-  canCalculate(data: Record<string, unknown>): Promise<boolean>
+  canCalculate(data: CreateShippingOptionDTO): Promise<boolean>
   /**
    *
    * Calculate the price for the given fulfillment option.
@@ -65,18 +107,18 @@ export interface IFulfillmentProvider {
   calculatePrice(
     optionData: CalculateShippingOptionPriceDTO["optionData"],
     data: CalculateShippingOptionPriceDTO["data"],
-    context: CalculateShippingOptionPriceDTO["context"]
+    context: CalculateShippingOptionPriceContext
   ): Promise<CalculatedShippingOptionPrice>
   /**
    *
    * Create a fulfillment for the given data.
    */
   createFulfillment(
-    data: object,
+    data: Record<string, unknown>,
-    items: object[],
+    items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
-    order: object | undefined,
+    order: Partial<FulfillmentOrderDTO> | undefined,
-    fulfillment: Record<string, unknown>
+    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
-  ): Promise<Record<string, unknown>>
+  ): Promise<CreateFulfillmentResult>
   /**
    *
    * Cancel the given fulfillment.
@@ -91,7 +133,9 @@ export interface IFulfillmentProvider {
    *
    * Create a return for the given data.
    */
-  createReturnFulfillment(fromData: Record<string, unknown>): Promise<any>
+  createReturnFulfillment(
+    fromData: Record<string, unknown>
+  ): Promise<CreateFulfillmentResult>
   /**
    *
    * Get the documents for the given return data.

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

@@ -45,7 +45,10 @@ import {
   CreateShippingProfileDTO,
   UpsertShippingProfileDTO,
 } from "./mutations/shipping-profile"
-import { CalculatedShippingOptionPrice } from "./provider"
+import {
+  CalculatedShippingOptionPrice,
+  ValidateFulfillmentDataContext,
+} from "./provider"
 
 /**
  * The main service interface for the Fulfillment Module.
@@ -2595,7 +2598,7 @@ export interface IFulfillmentModuleService extends IModuleService {
    * @param {string} providerId - The fulfillment provider's ID.
    * @param {Record<string, unknown>} optionData - The fulfillment option data to validate.
    * @param {Record<string, unknown>} data - The fulfillment data to validate.
-   * @param {Record<string, unknown>} context - The context to validate the fulfillment option data in.
+   * @param {ValidateFulfillmentDataContext} context - The context to validate the fulfillment option data in.
    * @returns {Promise<boolean>} Whether the fulfillment option data is valid with the specified provider.
    *
    * @example
@@ -2615,7 +2618,7 @@ export interface IFulfillmentModuleService extends IModuleService {
     providerId: string,
     optionData: Record<string, unknown>,
     data: Record<string, unknown>,
-    context: Record<string, unknown>
+    context: ValidateFulfillmentDataContext
   ): Promise<Record<string, unknown>>
 
   /**

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

@@ -1,14 +1,20 @@
 import {
   CalculatedShippingOptionPrice,
   CalculateShippingOptionPriceDTO,
+  CreateFulfillmentResult,
+  CreateShippingOptionDTO,
+  FulfillmentDTO,
+  FulfillmentItemDTO,
   FulfillmentOption,
+  FulfillmentOrderDTO,
   IFulfillmentProvider,
+  ValidateFulfillmentDataContext,
 } from "@medusajs/types"
 
 /**
  * ### constructor
  *
- * The constructor allows you to access resources from the [module's container](https://docs.medusajs.com/learn/fundamentals/modules/container) 
+ * The constructor allows you to access resources from the [module's container](https://docs.medusajs.com/learn/fundamentals/modules/container)
  * using the first parameter, and the module's options using the second parameter.
  *
  * :::note
@@ -48,7 +54,7 @@ import {
  *
  *     this.logger_ = logger
  *     this.options_ = options
- * 
+ *
  *     // TODO initialize your client
  *   }
  * }
@@ -96,7 +102,7 @@ export class AbstractFulfillmentProviderService
    * This method retrieves a list of fulfillment options that this provider supports. Admin users will then choose from these options when
    * they're creating a shipping option. The chosen fulfillment option's object is then stored within the created shipping option's `data` property.
    * The `data` property is useful to store data relevant for the third-party provider to later process the fulfillment.
-   * 
+   *
    * This method is useful if your third-party provider allows you to retrieve support options, carriers, or services from an API. You can then
    * retrieve those and return then in the method, allowing the admin user to choose from the services provided by the third-party provider.
    *
@@ -112,7 +118,7 @@ export class AbstractFulfillmentProviderService
    *   async getFulfillmentOptions(): Promise<FulfillmentOption[]> {
    *     // assuming you have a client
    *     const services = await this.client.getServices()
-   * 
+   *
    *     return services.map((service) => ({
    *       id: service.service_id,
    *       name: service.name,
@@ -161,7 +167,7 @@ export class AbstractFulfillmentProviderService
   async validateFulfillmentData(
     optionData: Record<string, unknown>,
     data: Record<string, unknown>,
-    context: Record<string, unknown>
+    context: ValidateFulfillmentDataContext
   ): Promise<any> {
     throw Error("validateFulfillmentData must be overridden by the child class")
   }
@@ -190,7 +196,7 @@ export class AbstractFulfillmentProviderService
   /**
    * This method validates whether a shippin option's price can be calculated during checkout. It's executed when the admin user creates a shipping
    * option of type `calculated`. If this method returns `false`, an error is thrown as the shipping option's price can't be calculated.
-   * 
+   *
    * You can perform the checking using the third-party provider if applicable. The `data` parameter will hold the shipping option's `data` property, which
    * includes the data of a fulfillment option returned by {@link getFulfillmentOptions}.
    *
@@ -200,26 +206,26 @@ export class AbstractFulfillmentProviderService
    * @example
    * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
    *   // ...
-   *   async canCalculate(data: Record<string, unknown>): Promise<boolean> {
+   *   async canCalculate(data: CreateShippingOptionDTO): Promise<boolean> {
    *     // assuming you have a client
    *     return await this.client.hasRates(data.id)
    *   }
    * }
    */
-  async canCalculate(data: Record<string, unknown>): Promise<boolean> {
+  async canCalculate(data: CreateShippingOptionDTO): Promise<boolean> {
     throw Error("canCalculate must be overridden by the child class")
   }
 
   /**
    * This method calculates the price of a shipping method when it's created or its cart is refreshed.
-   * 
+   *
-   * In this method, you can send a request to your third-party provider to retrieve the prices. The first 
+   * In this method, you can send a request to your third-party provider to retrieve the prices. The first
-   * parameters holds the `data` property of the shipping method's shipping option, which has fulfillment 
+   * parameters holds the `data` property of the shipping method's shipping option, which has fulfillment
    * object data returned by {@link getFulfillmentOptions}.
-   * 
+   *
    * The second parameter holds the `data` property of the shipping method, which has data returned by {@link validateFulfillmentData}.
    * It can also hold custom data passed from the frontend during checkout.
-   * 
+   *
    * So, using both of these data, assuming you're storing in them data related to the third-party service,
    * you can retrieve the calculated price of the shipping method.
    *
@@ -281,7 +287,7 @@ export class AbstractFulfillmentProviderService
    *     items: any,
    *     order: any,
    *     fulfillment: any
-   *   ): Promise<any> {
+   *   ): Promise<CreateFulfillmentResult> {
    *     // assuming the client creates a fulfillment
    *     // in the third-party service
    *     const externalData = await this.client.create(
@@ -299,11 +305,11 @@ export class AbstractFulfillmentProviderService
    * }
    */
   async createFulfillment(
-    data: object,
+    data: Record<string, unknown>,
-    items: object[],
+    items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
-    order: object | undefined,
+    order: Partial<FulfillmentOrderDTO> | undefined,
-    fulfillment: Record<string, unknown>
+    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
-  ): Promise<any> {
+  ): Promise<CreateFulfillmentResult> {
     throw Error("createFulfillment must be overridden by the child class")
   }
 
@@ -362,12 +368,12 @@ export class AbstractFulfillmentProviderService
    * purchasing a label for the return fulfillment.
    *
    * @param fulfillment - The fulfillment's details.
-   * @returns An object whose `data` property is stored in the fulfillment's `data` property.
+   * @returns An object containing `data` which is stored in the fulfillment's `data` property and `labels` array which is used to create FulfillmentLabels.
    *
    * @example
    * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
    *   // ...
-   *   async createReturnFulfillment(fulfillment: Record<string, unknown>): Promise<any> {
+   *   async createReturnFulfillment(fulfillment: Record<string, unknown>): Promise<CreateFulfillmentResult> {
    *     // assuming the client creates a fulfillment for a return
    *     // in the third-party service
    *     const externalData = await this.client.createReturn(
@@ -385,7 +391,7 @@ export class AbstractFulfillmentProviderService
    */
   async createReturnFulfillment(
     fulfillment: Record<string, unknown>
-  ): Promise<any> {
+  ): Promise<CreateFulfillmentResult> {
     throw Error("createReturn must be overridden by the child class")
   }
 

packages/modules/fulfillment/src/services/fulfillment-module-service.ts

@@ -17,6 +17,7 @@ import {
   SoftDeleteReturn,
   UpdateFulfillmentSetDTO,
   UpdateServiceZoneDTO,
+  ValidateFulfillmentDataContext,
 } from "@medusajs/framework/types"
 import {
   arrayDifference,
@@ -650,7 +651,7 @@ export default class FulfillmentModuleService
           fulfillmentData || {},
           items.map((i) => i),
           order,
-          fulfillmentRest
+          fulfillmentRest as unknown as Partial<FulfillmentDTO>
         )
       await this.fulfillmentService_.update(
         {
@@ -710,11 +711,22 @@ export default class FulfillmentModuleService
       sharedContext
     )
 
+    const shippingOption = await this.shippingOptionService_.retrieve(
+      fulfillment.shipping_option_id!,
+      {
+        select: ["id", "name", "data", "metadata"],
+      },
+      sharedContext
+    )
+
     try {
       const providerResult =
         await this.fulfillmentProviderService_.createReturn(
           fulfillment.provider_id!, // TODO: should we add a runtime check on provider_id being provided?,
-          fulfillment as Record<any, any>
+          {
+            ...fulfillment,
+            shipping_option: shippingOption,
+          } as Record<any, any>
         )
       await this.fulfillmentService_.update(
         {
@@ -2002,7 +2014,7 @@ export default class FulfillmentModuleService
     providerId: string,
     optionData: Record<string, unknown>,
     data: Record<string, unknown>,
-    context: Record<string, unknown>
+    context: ValidateFulfillmentDataContext
   ): Promise<Record<string, unknown>> {
     return await this.fulfillmentProviderService_.validateFulfillmentData(
       providerId,
@@ -2012,6 +2024,7 @@ export default class FulfillmentModuleService
     )
   }
 
+  // TODO: seems not to be used, what is the purpose of this method?
   async validateFulfillmentOption(
     providerId: string,
     data: Record<string, unknown>
@@ -2058,10 +2071,7 @@ export default class FulfillmentModuleService
     }
 
     const promises = shippingOptionsData.map((option) =>
-      this.fulfillmentProviderService_.canCalculate(
+      this.fulfillmentProviderService_.canCalculate(option.provider_id, option)
-        option.provider_id,
-        option as unknown as Record<string, unknown>
-      )
     )
 
     return await promiseAll(promises)

packages/modules/fulfillment/src/services/fulfillment-provider.ts

@@ -1,11 +1,17 @@
 import {
   CalculateShippingOptionPriceDTO,
   Constructor,
+  CreateFulfillmentResult,
+  CreateShippingOptionDTO,
   DAL,
+  FulfillmentDTO,
+  FulfillmentItemDTO,
   FulfillmentOption,
+  FulfillmentOrderDTO,
   FulfillmentTypes,
   IFulfillmentProvider,
   Logger,
+  ValidateFulfillmentDataContext,
 } from "@medusajs/framework/types"
 import {
   MedusaError,
@@ -91,7 +97,7 @@ export default class FulfillmentProviderService extends ModulesSdkUtils.MedusaIn
     providerId: string,
     optionData: Record<string, unknown>,
     data: Record<string, unknown>,
-    context: Record<string, unknown>
+    context: ValidateFulfillmentDataContext
   ) {
     const provider = this.retrieveProviderRegistration(providerId)
     return await provider.validateFulfillmentData(optionData, data, context)
@@ -102,7 +108,7 @@ export default class FulfillmentProviderService extends ModulesSdkUtils.MedusaIn
     return await provider.validateOption(data)
   }
 
-  async canCalculate(providerId: string, data: Record<string, unknown>) {
+  async canCalculate(providerId: string, data: CreateShippingOptionDTO) {
     const provider = this.retrieveProviderRegistration(providerId)
     return await provider.canCalculate(data)
   }
@@ -119,11 +125,11 @@ export default class FulfillmentProviderService extends ModulesSdkUtils.MedusaIn
 
   async createFulfillment(
     providerId: string,
-    data: object,
+    data: Record<string, unknown>,
-    items: object[],
+    items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
-    order: object | undefined,
+    order: Partial<FulfillmentOrderDTO> | undefined,
-    fulfillment: Record<string, unknown>
+    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
-  ): Promise<Record<string, unknown>> {
+  ): Promise<CreateFulfillmentResult> {
     const provider = this.retrieveProviderRegistration(providerId)
     return await provider.createFulfillment(data, items, order, fulfillment)
   }

packages/modules/providers/fulfillment-manual/src/services/manual-fulfillment.ts

@@ -1,7 +1,10 @@
 import { AbstractFulfillmentProviderService } from "@medusajs/framework/utils"
 import {
   CalculatedShippingOptionPrice,
+  CalculateShippingOptionPriceContext,
+  CreateFulfillmentResult,
   FulfillmentOption,
+  ValidateFulfillmentDataContext,
 } from "@medusajs/types"
 
 // TODO rework type and DTO's
@@ -28,7 +31,7 @@ export class ManualFulfillmentService extends AbstractFulfillmentProviderService
   async validateFulfillmentData(
     optionData: Record<string, unknown>,
     data: Record<string, unknown>,
-    context: Record<string, unknown>
+    context: ValidateFulfillmentDataContext
   ): Promise<any> {
     return data
   }
@@ -36,7 +39,7 @@ export class ManualFulfillmentService extends AbstractFulfillmentProviderService
   async calculatePrice(
     optionData: Record<string, unknown>,
     data: Record<string, unknown>,
-    context: Record<string, unknown>
+    context: CalculateShippingOptionPriceContext
   ): Promise<CalculatedShippingOptionPrice> {
     throw new Error("Manual fulfillment does not support price calculation")
   }
@@ -49,16 +52,22 @@ export class ManualFulfillmentService extends AbstractFulfillmentProviderService
     return true
   }
 
-  async createFulfillment(): Promise<Record<string, any>> {
+  async createFulfillment(): Promise<CreateFulfillmentResult> {
     // No data is being sent anywhere
-    return {}
+    return {
+      data: {},
+      labels: [],
+    }
   }
 
   async cancelFulfillment(): Promise<any> {
     return {}
   }
 
-  async createReturnFulfillment(): Promise<any> {
+  async createReturnFulfillment(): Promise<CreateFulfillmentResult> {
-    return {}
+    return {
+      data: {},
+      labels: [],
+    }
   }
 }