fix(types,order,medusa): Create credit lines + hooks (#11569)

what:

- api/workflows to create credit lines
- hooks to enable extending credit lines

packages/core/core-flows/src/cart/workflows/complete-cart.ts

@@ -136,6 +136,10 @@ export const completeCartWorkflow = createWorkflow(
 
       const paymentSessions = validateCartPaymentsStep({ cart })
 
+      createHook("beforePaymentAuthorization", {
+        input,
+      })
+
       const payment = authorizePaymentSessionStep({
         // We choose the first payment session, as there will only be one active payment session
         // This might change in the future.
@@ -200,17 +204,6 @@ export const completeCartWorkflow = createWorkflow(
           }
         })
 
-        const itemAdjustments = allItems
-          .map((item) => item.adjustments ?? [])
-          .flat(1)
-        const shippingAdjustments = shippingMethods
-          .map((sm) => sm.adjustments ?? [])
-          .flat(1)
-
-        const promoCodes = [...itemAdjustments, ...shippingAdjustments]
-          .map((adjustment) => adjustment.code)
-          .filter(Boolean)
-
         const creditLines = (cart.credit_lines ?? []).map(
           (creditLine: CartCreditLineDTO) => {
             return {
@@ -223,6 +216,17 @@ export const completeCartWorkflow = createWorkflow(
           }
         )
 
+        const itemAdjustments = allItems
+          .map((item) => item.adjustments ?? [])
+          .flat(1)
+        const shippingAdjustments = shippingMethods
+          .map((sm) => sm.adjustments ?? [])
+          .flat(1)
+
+        const promoCodes = [...itemAdjustments, ...shippingAdjustments]
+          .map((adjustment) => adjustment.code)
+          .filter(Boolean)
+
         return {
           region_id: cart.region?.id,
           customer_id: cart.customer?.id,
@@ -235,10 +239,10 @@ export const completeCartWorkflow = createWorkflow(
           no_notification: false,
           items: allItems,
           shipping_methods: shippingMethods,
-          credit_lines: creditLines,
           metadata: cart.metadata,
           promo_codes: promoCodes,
           transactions,
+          credit_lines: creditLines,
         }
       })
 
@@ -330,6 +334,11 @@ export const completeCartWorkflow = createWorkflow(
 
       registerUsageStep(promotionUsage)
 
+      createHook("orderCreated", {
+        order_id: createdOrder.id,
+        cart_id: cart.id,
+      })
+
       return createdOrder
     })
 

packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts

@@ -4,6 +4,7 @@ import {
   PromotionActions,
 } from "@medusajs/framework/utils"
 import {
+  createHook,
   createWorkflow,
   transform,
   when,
@@ -228,6 +229,8 @@ export const refreshCartItemsWorkflow = createWorkflow(
       },
     })
 
+    createHook("beforeRefreshingPaymentCollection", { input })
+
     refreshPaymentCollectionForCartWorkflow.runAsStep({
       input: { cart_id: input.cart_id },
     })

packages/core/core-flows/src/order/steps/confirm-order-changes.ts

@@ -29,7 +29,7 @@ export const confirmOrderChanges = createStep(
     const orderModuleService = container.resolve(Modules.ORDER)
 
     const currentChanges: Partial<OrderChangeDTO>[] = []
-    await orderModuleService.confirmOrderChange(
+    const orderChanges = await orderModuleService.confirmOrderChange(
       input.changes.map((action) => {
         const update = {
           id: action.id,
@@ -46,7 +46,7 @@ export const confirmOrderChanges = createStep(
       })
     )
 
-    return new StepResponse(null, currentChanges)
+    return new StepResponse(orderChanges, currentChanges)
   },
   async (currentChanges, { container }) => {
     if (!currentChanges?.length) {

packages/core/core-flows/src/order/workflows/create-order-credit-lines.ts

@@ -0,0 +1,170 @@
+import { CreateOrderCreditLineDTO, OrderDTO } from "@medusajs/framework/types"
+import {
+  ChangeActionType,
+  MathBN,
+  MedusaError,
+  OrderChangeStatus,
+  OrderChangeType,
+} from "@medusajs/framework/utils"
+import {
+  WorkflowData,
+  WorkflowResponse,
+  createHook,
+  createStep,
+  createWorkflow,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+import { useQueryGraphStep } from "../../common"
+import { confirmOrderChanges } from "../steps/confirm-order-changes"
+import { createOrderChangeStep } from "../steps/create-order-change"
+import { createOrderChangeActionsWorkflow } from "./create-order-change-actions"
+
+export const validateOrderCreditLinesStep = createStep(
+  "validate-order-credit-lines",
+  async function ({
+    order,
+    creditLines,
+  }: {
+    order: OrderDTO
+    creditLines: Omit<CreateOrderCreditLineDTO, "order_id">[]
+  }) {
+    const pendingDifference = MathBN.convert(order.summary?.pending_difference!)
+    const creditLinesAmount = creditLines.reduce((acc, creditLine) => {
+      return MathBN.add(acc, MathBN.convert(creditLine.amount))
+    }, MathBN.convert(0))
+
+    if (MathBN.eq(pendingDifference, 0)) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        `Can only create credit lines if the order has a positive or negative pending difference`
+      )
+    }
+
+    if (MathBN.gt(pendingDifference, 0) && MathBN.lt(creditLinesAmount, 0)) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        `Can only create positive credit lines if the order has a positive pending difference`
+      )
+    }
+
+    if (MathBN.lt(pendingDifference, 0) && MathBN.gt(creditLinesAmount, 0)) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        `Can only create negative credit lines if the order has a negative pending difference`
+      )
+    }
+
+    if (MathBN.lt(pendingDifference, 0)) {
+      if (
+        MathBN.gt(
+          creditLinesAmount.multipliedBy(-1),
+          pendingDifference.multipliedBy(-1)
+        )
+      ) {
+        throw new MedusaError(
+          MedusaError.Types.INVALID_DATA,
+          `Cannot create more negative credit lines with amount more than the pending difference`
+        )
+      }
+    }
+
+    if (MathBN.gt(pendingDifference, 0)) {
+      if (MathBN.gt(creditLinesAmount, pendingDifference)) {
+        throw new MedusaError(
+          MedusaError.Types.INVALID_DATA,
+          `Cannot create more positive credit lines with amount more than the pending difference`
+        )
+      }
+    }
+  }
+)
+
+export const createOrderCreditLinesWorkflowId = "create-order-credit-lines"
+export const createOrderCreditLinesWorkflow = createWorkflow(
+  createOrderCreditLinesWorkflowId,
+  (
+    input: WorkflowData<{
+      id: string
+      credit_lines: Omit<CreateOrderCreditLineDTO, "order_id">[]
+    }>
+  ) => {
+    const orderQuery = useQueryGraphStep({
+      entity: "orders",
+      fields: ["id", "status", "summary"],
+      filters: { id: input.id },
+      options: { throwIfKeyNotFound: true },
+    }).config({ name: "get-order" })
+
+    const order = transform(
+      { orderQuery },
+      ({ orderQuery }) => orderQuery.data[0]
+    )
+
+    validateOrderCreditLinesStep({ order, creditLines: input.credit_lines })
+
+    const orderChangeInput = transform({ input }, ({ input }) => ({
+      change_type: OrderChangeType.CREDIT_LINE,
+      order_id: input.id,
+    }))
+
+    const createdOrderChange = createOrderChangeStep(orderChangeInput)
+
+    const orderChangeActionInput = transform(
+      { order, orderChange: createdOrderChange, input },
+      ({ order, orderChange, input }) => {
+        return input.credit_lines.map((creditLine) => {
+          return {
+            order_change_id: orderChange.id,
+            order_id: order.id,
+            version: orderChange.version,
+            action: ChangeActionType.CREDIT_LINE_ADD,
+            reference: creditLine.reference!,
+            reference_id: creditLine.reference_id!,
+            amount: creditLine.amount,
+          }
+        })
+      }
+    )
+
+    createOrderChangeActionsWorkflow.runAsStep({
+      input: orderChangeActionInput,
+    })
+
+    const orderChangeQuery = useQueryGraphStep({
+      entity: "order_change",
+      fields: [
+        "id",
+        "status",
+        "change_type",
+        "actions.id",
+        "actions.order_id",
+        "actions.action",
+        "actions.details",
+        "actions.reference",
+        "actions.reference_id",
+        "actions.internal_note",
+      ],
+      filters: {
+        order_id: input.id,
+        status: [OrderChangeStatus.PENDING],
+      },
+    }).config({ name: "order-change-query" })
+
+    const orderChange = transform(
+      { orderChangeQuery },
+      ({ orderChangeQuery }) => orderChangeQuery.data[0]
+    )
+
+    const orderChanges = confirmOrderChanges({
+      changes: [orderChange],
+      orderId: order.id,
+    })
+
+    createHook("creditLinesCreated", {
+      order_id: input.id,
+      credit_lines: orderChanges.credit_lines,
+    })
+
+    return new WorkflowResponse(orderChanges.credit_lines)
+  }
+)

packages/core/core-flows/src/order/workflows/index.ts

@@ -19,10 +19,12 @@ export * from "./claim/update-claim-item"
 export * from "./claim/update-claim-shipping-method"
 export * from "./complete-orders"
 export * from "./create-fulfillment"
+export * from "./create-or-update-order-payment-collection"
+export * from "./create-order"
 export * from "./create-order-change"
 export * from "./create-order-change-actions"
+export * from "./create-order-credit-lines"
 export * from "./create-order-payment-collection"
-export * from "./create-order"
 export * from "./create-shipment"
 export * from "./decline-order-change"
 export * from "./delete-order-change"
@@ -75,12 +77,11 @@ export * from "./return/update-receive-item-return-request"
 export * from "./return/update-request-item-return"
 export * from "./return/update-return"
 export * from "./return/update-return-shipping-method"
-export * from "./update-order-change-actions"
-export * from "./update-order-changes"
-export * from "./update-tax-lines"
-export * from "./transfer/request-order-transfer"
 export * from "./transfer/accept-order-transfer"
 export * from "./transfer/cancel-order-transfer"
 export * from "./transfer/decline-order-transfer"
+export * from "./transfer/request-order-transfer"
 export * from "./update-order"
-export * from "./create-or-update-order-payment-collection"
+export * from "./update-order-change-actions"
+export * from "./update-order-changes"
+export * from "./update-tax-lines"

packages/core/js-sdk/src/admin/order.ts

@@ -1,5 +1,6 @@
 import {
   AdminOrderChangesResponse,
+  CreateOrderCreditLineDTO,
   FindParams,
   HttpTypes,
   PaginatedResponse,
@@ -499,4 +500,21 @@ export class Order {
       }
     )
   }
+
+  async createCreditLine(
+    orderId: string,
+    body: Omit<CreateOrderCreditLineDTO, "order_id">,
+    query?: SelectParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminOrderResponse>(
+      `/admin/orders/${orderId}/credit-lines`,
+      {
+        method: "POST",
+        headers,
+        body,
+        query,
+      }
+    )
+  }
 }

packages/core/types/src/http/order/admin/entities.ts

@@ -1,3 +1,4 @@
+import { OrderCreditLineDTO } from "../../../order"
 import { AdminClaim } from "../../claim"
 import { AdminCustomer } from "../../customer"
 import { AdminExchange } from "../../exchange"
@@ -49,6 +50,10 @@ export interface AdminOrder extends Omit<BaseOrder, "items"> {
    * The order's shipping methods.
    */
   shipping_methods: AdminOrderShippingMethod[]
+  /**
+   * The order's credit lines.
+   */
+  credit_lines?: OrderCreditLineDTO[]
 }
 
 export interface AdminOrderChange

packages/core/types/src/order/common.ts

@@ -2982,7 +2982,12 @@ export interface OrderChangeReturn {
   /**
    * The list of shipping methods created or updated.
    */
-  shippingMethods: any[]
+  shipping_methods: any[]
+
+  /**
+   * The list of credit lines created or updated.
+   */
+  credit_lines: OrderCreditLineDTO[]
 }
 
 /**

packages/core/types/src/order/mutations.ts

@@ -1,8 +1,7 @@
-import { BigNumberInput, BigNumberValue } from "../totals"
+import { BigNumberInput } from "../totals"
 import {
   ChangeActionType,
   OrderClaimDTO,
-  OrderCreditLineDTO,
   OrderExchangeDTO,
   OrderItemDTO,
   OrderLineItemDTO,
@@ -158,6 +157,11 @@ export interface CreateOrderDTO {
    */
   billing_address?: CreateOrderAddressDTO | UpdateOrderAddressDTO
 
+  /**
+   * The credit lines of the order.
+   */
+  credit_lines?: CreateOrderCreditLineDTO[]
+
   /**
    * Whether the customer should receive notifications about
    * order updates.
@@ -174,11 +178,6 @@ export interface CreateOrderDTO {
    */
   shipping_methods?: Omit<CreateOrderShippingMethodDTO, "order_id">[]
 
-  /**
-   * The credit lines of the order.
-   */
-  credit_lines?: OrderCreditLineDTO[]
-
   /**
    * The transactions of the order.
    */
@@ -2282,7 +2281,7 @@ export interface CreateOrderCreditLineDTO {
   /**
    * The amount of the credit line.
    */
-  amount: BigNumberValue
+  amount: BigNumberInput
 
   /**
    * The reference model name that the credit line is generated from

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

@@ -2927,7 +2927,7 @@ export interface IOrderModuleService extends IModuleService {
    * @example
    * const {
    *   items,
-   *   shippingMethods
+   *   shipping_methods
    * } = await orderModuleService.applyPendingOrderActions([
    *   "123", "321"
    * ])

packages/core/utils/src/totals/__tests__/totals.ts

@@ -81,9 +81,9 @@ describe("Total calculation", function () {
       original_item_subtotal: 65,
       original_item_total: 73.5,
       original_item_tax_total: 8.5,
-      credit_lines_subtotal: 0,
-      credit_lines_tax_total: 0,
-      credit_lines_total: 0,
+      credit_line_subtotal: 0,
+      credit_line_tax_total: 0,
+      credit_line_total: 0,
     })
   })
 
@@ -152,9 +152,9 @@ describe("Total calculation", function () {
       original_item_total: 110,
       original_item_subtotal: 100,
       original_item_tax_total: 10,
-      credit_lines_subtotal: 0,
-      credit_lines_tax_total: 0,
-      credit_lines_total: 0,
+      credit_line_subtotal: 0,
+      credit_line_tax_total: 0,
+      credit_line_total: 0,
     })
   })
 
@@ -359,9 +359,9 @@ describe("Total calculation", function () {
       original_shipping_tax_total: 9.9,
       original_shipping_subtotal: 99,
       original_shipping_total: 108.9,
-      credit_lines_subtotal: 0,
-      credit_lines_tax_total: 0,
-      credit_lines_total: 0,
+      credit_line_subtotal: 0,
+      credit_line_tax_total: 0,
+      credit_line_total: 0,
     })
   })
 
@@ -447,9 +447,9 @@ describe("Total calculation", function () {
       original_item_total: 100,
       original_item_subtotal: 90.9090909090909,
       original_item_tax_total: 9.090909090909092,
-      credit_lines_subtotal: 0,
-      credit_lines_tax_total: 0,
-      credit_lines_total: 0,
+      credit_line_subtotal: 0,
+      credit_line_tax_total: 0,
+      credit_line_total: 0,
     })
 
     expect(serializedWithout).toEqual({
@@ -489,9 +489,9 @@ describe("Total calculation", function () {
       original_item_total: 110,
       original_item_subtotal: 100,
       original_item_tax_total: 10,
-      credit_lines_subtotal: 0,
-      credit_lines_tax_total: 0,
-      credit_lines_total: 0,
+      credit_line_subtotal: 0,
+      credit_line_tax_total: 0,
+      credit_line_total: 0,
     })
 
     expect(serializedMixed).toEqual({
@@ -551,9 +551,9 @@ describe("Total calculation", function () {
       original_item_total: 210,
       original_item_subtotal: 190.9090909090909,
       original_item_tax_total: 19.09090909090909,
-      credit_lines_subtotal: 0,
-      credit_lines_tax_total: 0,
-      credit_lines_total: 0,
+      credit_line_subtotal: 0,
+      credit_line_tax_total: 0,
+      credit_line_total: 0,
     })
   })
 
@@ -670,9 +670,9 @@ describe("Total calculation", function () {
       original_shipping_tax_total: 2.5,
       original_shipping_subtotal: 25,
       original_shipping_total: 27.5,
-      credit_lines_subtotal: 0,
-      credit_lines_tax_total: 0,
-      credit_lines_total: 0,
+      credit_line_subtotal: 0,
+      credit_line_tax_total: 0,
+      credit_line_total: 0,
     })
   })
 
@@ -787,9 +787,9 @@ describe("Total calculation", function () {
       return_received_total: 44,
       return_dismissed_total: 44,
       write_off_total: 44,
-      credit_lines_subtotal: 40,
-      credit_lines_tax_total: 0,
-      credit_lines_total: 40,
+      credit_line_subtotal: 40,
+      credit_line_tax_total: 0,
+      credit_line_total: 40,
     })
   })
 })

packages/core/utils/src/totals/cart/index.ts

@@ -234,9 +234,9 @@ export function decorateCartTotals(
   cart.discount_subtotal = new BigNumber(discountSubtotal)
   cart.discount_tax_total = new BigNumber(discountTaxTotal)
 
-  cart.credit_lines_total = new BigNumber(creditLinesTotal)
-  cart.credit_lines_subtotal = new BigNumber(creditLinesSubtotal)
-  cart.credit_lines_tax_total = new BigNumber(creditLinesTaxTotal)
+  cart.credit_line_total = new BigNumber(creditLinesTotal)
+  cart.credit_line_subtotal = new BigNumber(creditLinesSubtotal)
+  cart.credit_line_tax_total = new BigNumber(creditLinesTaxTotal)
 
   // cart.gift_card_total = giftCardTotal.total || 0
   // cart.gift_card_tax_total = giftCardTotal.tax_total || 0