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
2025-01-07 08:08:45 +00:00
parent 333ed538f5
commit 16b0672f8a
12 changed files with 1358 additions and 68 deletions
@@ -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 {
@@ -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
+      }[]
+    }
+  }
+}
@@ -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"
@@ -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"]
@@ -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,
-    items: object[],
-    order: object | undefined,
-    fulfillment: Record<string, unknown>
-  ): Promise<Record<string, unknown>>
+    data: Record<string, unknown>,
+    items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
+    order: Partial<FulfillmentOrderDTO> | undefined,
+    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
+  ): 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.
@@ -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>>

  /**
@@ -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 
-   * parameters holds the `data` property of the shipping method's shipping option, which has fulfillment 
+   *
+   * 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
   * 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,
-    items: object[],
-    order: object | undefined,
-    fulfillment: Record<string, unknown>
-  ): Promise<any> {
+    data: Record<string, unknown>,
+    items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
+    order: Partial<FulfillmentOrderDTO> | undefined,
+    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
+  ): 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")
  }