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

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

@@ -41,14 +41,17 @@ export class ManualFulfillmentService extends AbstractFulfillmentProviderService
 
   async createFulfillment() {
     // No data is being sent anywhere
-    return {}
+    return {
+      data: {},
+      labels: [],
+    }
   }
 
   async cancelFulfillment() {
     return {}
   }
 
   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,4 @@ export * from "./fulfillment-provider"
 export * from "./fulfillment"
 export * from "./fulfillment-item"
 export * from "./fulfillment-label"
+export * from "./cart"

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<
-      string,
-      unknown
-    >
+    [k: 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 { OrderDTO } from "../order"
+import { StockLocationDTO } from "../stock-location"
+import {
+  CartPropsForFulfillment,
+  FulfillmentDTO,
+  FulfillmentItemDTO,
+} 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,37 +88,39 @@ export interface IFulfillmentProvider {
   validateFulfillmentData(
     optionData: Record<string, unknown>,
     data: Record<string, unknown>,
-    context: Record<string, unknown>
+    context: ValidateFulfillmentDataContext
   ): Promise<any>
   /**
    *
    * Validate the given option.
+   *
+   * TODO: seems not to be used, called from `fulfillmentModuleService.validateFulfillmentOption`?
    */
   validateOption(data: Record<string, unknown>): Promise<boolean>
   /**
    *
    * 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.
    */
   calculatePrice(
     optionData: CalculateShippingOptionPriceDTO["optionData"],
     data: CalculateShippingOptionPriceDTO["data"],
-    context: CalculateShippingOptionPriceDTO["context"]
+    context: CalculateShippingOptionPriceContext
   ): Promise<CalculatedShippingOptionPrice>
   /**
    *
    * Create a fulfillment for the given data.
    */
   createFulfillment(
-    data: object,
-    items: object[],
-    order: object | undefined,
-    fulfillment: Record<string, unknown>
-  ): Promise<Record<string, unknown>>
+    data: Record<string, unknown>,
+    items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
+    order: Partial<OrderDTO> | undefined,
+    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
+  ): Promise<CreateFulfillmentResult>
   /**
    *
    * Cancel the given fulfillment.
@@ -91,7 +135,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>>
 
   /**