fix(core-flows, types): export steps and types related to credit lines (medusajs#12567)

- Export steps that are used in credit-line related workflows
- Move workflow's input type to the `workflows.ts` type file
- Add and update TSDocs

Author: shahednasser

.changeset/old-dancers-retire.md

@@ -0,0 +1,6 @@
+---
+"@medusajs/core-flows": patch
+"@medusajs/types": patch
+---
+
+fix(core-flows, types): export steps and types related to credit lines

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

@@ -1,6 +1,6 @@
 import {
   CartCreditLineDTO,
-  CreateCartCreditLineDTO,
+  CreateCartCreditLinesWorkflowInput,
 } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import {
@@ -11,10 +11,27 @@ import {
 import { createEntitiesStep } from "../../common/steps/create-entities"
 
 export const createCartCreditLinesWorkflowId = "create-cart-credit-lines"
+/**
+ * This workflow creates one or more credit lines for a cart.
+ * 
+ * @example
+ * const { result } = await createCartCreditLinesWorkflow(container)
+ * .run({
+ *   input: {
+ *     cart_id: "cart_123",
+ *     amount: 10,
+ *     reference: "payment",
+ *     reference_id: "payment_123",
+ *     metadata: {
+ *       key: "value",
+ *     },
+ *   }
+ * })
+ */
 export const createCartCreditLinesWorkflow = createWorkflow(
   createCartCreditLinesWorkflowId,
   (
-    input: WorkflowData<CreateCartCreditLineDTO[]>
+    input: WorkflowData<CreateCartCreditLinesWorkflowInput>
   ): WorkflowResponse<CartCreditLineDTO[]> => {
     const creditLines = createEntitiesStep({
       moduleRegistrationName: Modules.CART,

packages/core/core-flows/src/cart/workflows/delete-cart-credit-lines.ts

@@ -7,9 +7,17 @@ import {
 import { deleteEntitiesStep } from "../../common/steps/delete-entities"
 
 export const deleteCartCreditLinesWorkflowId = "delete-cart-credit-lines"
+/**
+ * This workflow deletes one or more credit lines from a cart.
+ */
 export const deleteCartCreditLinesWorkflow = createWorkflow(
   deleteCartCreditLinesWorkflowId,
-  (input: WorkflowData<{ id: string[] }>) => {
+  (input: WorkflowData<{
+    /**
+     * The IDs of the credit lines to delete.
+     */ 
+    id: string[]
+  }>) => {
     deleteEntitiesStep({
       moduleRegistrationName: Modules.CART,
       invokeMethod: "softDeleteCreditLines",

packages/core/core-flows/src/common/index.ts

@@ -1,5 +1,7 @@
+export * from "./steps/create-entities"
 export * from "./steps/create-remote-links"
 export * from "./steps/dismiss-remote-links"
+export * from "./steps/delete-entities"
 export * from "./steps/emit-event"
 export * from "./steps/remove-remote-links"
 export * from "./steps/update-remote-links"

packages/core/core-flows/src/common/steps/create-entities.ts

@@ -1,16 +1,48 @@
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 export interface CreateEntitiesStepType {
+  /**
+   * The regitration name of the module that contains the method to be invoked.
+   */
   moduleRegistrationName: string
+  /**
+   * The method to be invoked.
+   */
   invokeMethod: string
+  /**
+   * The method to be invoked in case of compensation (when an error occurs).
+   */
   compensateMethod: string
+  /**
+   * A string to pass to the compensate method.
+   */
   entityIdentifier?: string
+  /**
+   * The data to pass to the invoke method.
+   * For example, an array of objects to create.
+   */
   data: any[]
 }
 
 export const createEntitiesStepId = "create-entities-step"
 /**
- * This step creates entities for any given module or resource
+ * This step creates one or more entities using methods in a module's service.
+ * 
+ * @example
+ * createEntitiesStep({
+ *   moduleRegistrationName: Modules.CART,
+ *   invokeMethod: "createCreditLines",
+ *   compensateMethod: "deleteCreditLines",
+ *   data: {
+ *     cart_id: "cart_123",
+ *     amount: 10,
+ *     reference: "payment",
+ *     reference_id: "payment_123",
+ *     metadata: {
+ *       key: "value",
+ *     },
+ *   },
+ * })
  */
 export const createEntitiesStep = createStep(
   createEntitiesStepId,

packages/core/core-flows/src/common/steps/delete-entities.ts

@@ -1,16 +1,41 @@
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 export interface DeleteEntitiesStepType {
+  /**
+   * The regitration name of the module that contains the method to be invoked.
+   */
   moduleRegistrationName: string
+  /**
+   * The method to be invoked.
+   */
   invokeMethod: string
+  /**
+   * The method to be invoked in case of compensation (when an error occurs).
+   */
   compensateMethod: string
+  /**
+   * A string to pass to the compensate method.
+   * For example, an ID of the entity to be deleted.
+   */
   entityIdentifier?: string
+  /**
+   * The data to pass to the invoke method.
+   * For example, an array of IDs to delete.
+   */
   data: any[]
 }
 
 export const deleteEntitiesStepId = "delete-entities-step"
 /**
- * This step deletes one or more entities.
+ * This step deletes one or more entities using methods in a module's service.
+ * 
+ * @example
+ * deleteEntitiesStep({
+ *   moduleRegistrationName: Modules.CART,
+ *   invokeMethod: "softDeleteCreditLines",
+ *   compensateMethod: "restoreCreditLines",
+ *   data: input.id,
+ * })
  */
 export const deleteEntitiesStep = createStep(
   deleteEntitiesStepId,

packages/core/types/src/cart/workflows.ts

@@ -527,3 +527,30 @@ export interface CartWorkflowDTO {
   id: string
   payment_collection: PaymentCollectionDTO
 }
+
+export type CreateCartCreditLinesWorkflowInput = {
+  /**
+   * The ID of the cart that the credit line belongs to.
+   */
+  cart_id: string
+
+  /**
+   * The amount of the credit line.
+   */
+  amount: number
+
+  /**
+   * The reference model name that the credit line is generated from
+   */
+  reference: string | null
+
+  /**
+   * The reference model id that the credit line is generated from
+   */
+  reference_id: string | null
+
+  /**
+   * The metadata of the cart detail
+   */
+  metadata: Record<string, unknown> | null
+}[]