chore(core-flows): [9] export types and types, add basic TSDocs (#8519)

This PR exports types and steps from the core-flows package, and adds simple TSDocs for workflows / steps. This is essential for the workflows reference. PR 9/n
2024-08-08 16:41:12 +00:00
parent 6e4037edf4
commit 945b920708
25 changed files with 91 additions and 32 deletions
@@ -2,12 +2,13 @@ import { CancelOrderClaimDTO, IOrderModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CancelOrderClaimStepInput = CancelOrderClaimDTO
-
 export const cancelOrderClaimStepId = "cancel-order-claim"
+/**
+ * This step cancels a claim.
+ */
 export const cancelOrderClaimStep = createStep(
  cancelOrderClaimStepId,
-  async (data: CancelOrderClaimStepInput, { container }) => {
+  async (data: CancelOrderClaimDTO, { container }) => {
    const service = container.resolve<IOrderModuleService>(
      ModuleRegistrationName.ORDER
    )
@@ -2,11 +2,14 @@ import { IOrderModuleService, OrderChangeActionDTO } from "@medusajs/types"
 import { ChangeActionType, ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CreateOrderClaimItemsFromActionsInput = {
+export type CreateOrderClaimItemsFromActionsInput = {
  changes: OrderChangeActionDTO[]
  claimId: string
 }

+/**
+ * This step creates claim items from a change action.
+ */
 export const createOrderClaimItemsFromActionsStep = createStep(
  "create-claim-items-from-change-actions",
  async (input: CreateOrderClaimItemsFromActionsInput, { container }) => {
@@ -2,12 +2,13 @@ import { CreateOrderClaimDTO, IOrderModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CreateOrderClaimsStepInput = CreateOrderClaimDTO[]
-
 export const createOrderClaimsStepId = "create-order-claims"
+/**
+ * This step creates one or more order claims.
+ */
 export const createOrderClaimsStep = createStep(
  createOrderClaimsStepId,
-  async (data: CreateOrderClaimsStepInput, { container }) => {
+  async (data: CreateOrderClaimDTO[], { container }) => {
    const service = container.resolve<IOrderModuleService>(
      ModuleRegistrationName.ORDER
    )
@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"

 export const deleteClaimsStepId = "delete-claims"
+/**
+ * This step deletes one or more order claims.
+ */
 export const deleteClaimsStep = createStep(
  deleteClaimsStepId,
  async (data: { ids: string[] }, { container }) => {
@@ -6,6 +6,9 @@ import {
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

 export const updateOrderClaimsStepId = "update-order-claim"
+/**
+ * This step updates one or more claims.
+ */
 export const updateOrderClaimsStep = createStep(
  updateOrderClaimsStepId,
  async (data: UpdateOrderClaimDTO[], { container }) => {
@@ -2,12 +2,13 @@ import { CancelOrderExchangeDTO, IOrderModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CancelOrderExchangeStepInput = CancelOrderExchangeDTO
-
 export const cancelOrderExchangeStepId = "cancel-order-swap"
+/**
+ * This step cancels an exchange.
+ */
 export const cancelOrderExchangeStep = createStep(
  cancelOrderExchangeStepId,
-  async (data: CancelOrderExchangeStepInput, { container }) => {
+  async (data: CancelOrderExchangeDTO, { container }) => {
    const service = container.resolve<IOrderModuleService>(
      ModuleRegistrationName.ORDER
    )
@@ -6,11 +6,14 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CreateOrderExchangeItemsFromActionsInput = {
+export type CreateOrderExchangeItemsFromActionsInput = {
  changes: OrderChangeActionDTO[]
  exchangeId: string
 }

+/**
+ * This step creates exchange items from change actions.
+ */
 export const createOrderExchangeItemsFromActionsStep = createStep(
  "create-exchange-items-from-change-actions",
  async (input: CreateOrderExchangeItemsFromActionsInput, { container }) => {
@@ -2,12 +2,13 @@ import { CreateOrderExchangeDTO, IOrderModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CreateOrderExchangesStepInput = CreateOrderExchangeDTO[]
-
 export const createOrderExchangesStepId = "create-order-exchanges"
+/**
+ * This step creates one or more order exchanges.
+ */
 export const createOrderExchangesStep = createStep(
  createOrderExchangesStepId,
-  async (data: CreateOrderExchangesStepInput, { container }) => {
+  async (data: CreateOrderExchangeDTO[], { container }) => {
    const service = container.resolve<IOrderModuleService>(
      ModuleRegistrationName.ORDER
    )
@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"

 export const deleteExchangesStepId = "delete-exchanges"
+/**
+ * This step deletes one or more exchanges.
+ */
 export const deleteExchangesStep = createStep(
  deleteExchangesStepId,
  async (data: { ids: string[] }, { container }) => {
@@ -6,6 +6,9 @@ import {
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

 export const updateOrderExchangesStepId = "update-order-exchange"
+/**
+ * This step updates one or more exchanges.
+ */
 export const updateOrderExchangesStep = createStep(
  updateOrderExchangesStepId,
  async (data: UpdateOrderExchangeDTO[], { container }) => {
@@ -2,12 +2,13 @@ import { CancelOrderReturnDTO, IOrderModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CancelOrderReturnStepInput = CancelOrderReturnDTO
-
 export const cancelOrderReturnStepId = "cancel-order-return"
+/**
+ * This step cancels a return.
+ */
 export const cancelOrderReturnStep = createStep(
  cancelOrderReturnStepId,
-  async (data: CancelOrderReturnStepInput, { container }) => {
+  async (data: CancelOrderReturnDTO, { container }) => {
    const service = container.resolve<IOrderModuleService>(
      ModuleRegistrationName.ORDER
    )
@@ -2,12 +2,13 @@ import { CreateOrderReturnDTO, IOrderModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CreateCompleteReturnStepInput = CreateOrderReturnDTO
-
 export const createCompleteReturnStepId = "create-complete-return"
+/**
+ * This step creates a return.
+ */
 export const createCompleteReturnStep = createStep(
  createCompleteReturnStepId,
-  async (data: CreateCompleteReturnStepInput, { container }) => {
+  async (data: CreateOrderReturnDTO, { container }) => {
    const service = container.resolve<IOrderModuleService>(
      ModuleRegistrationName.ORDER
    )
@@ -6,11 +6,14 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CreateReturnItemsFromActionsInput = {
+export type CreateReturnItemsFromActionsInput = {
  changes: OrderChangeActionDTO[]
  returnId: string
 }

+/**
+ * This step creates return items from change actions.
+ */
 export const createReturnItemsFromActionsStep = createStep(
  "create-return-items-from-change-actions",
  async (input: CreateReturnItemsFromActionsInput, { container }) => {
@@ -2,12 +2,13 @@ import { CreateOrderReturnDTO, IOrderModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type CreateReturnsStepInput = CreateOrderReturnDTO[]
-
 export const createReturnsStepId = "create-returns"
+/**
+ * This step creates returns.
+ */
 export const createReturnsStep = createStep(
  createReturnsStepId,
-  async (data: CreateReturnsStepInput, { container }) => {
+  async (data: CreateOrderReturnDTO[], { container }) => {
    const service = container.resolve<IOrderModuleService>(
      ModuleRegistrationName.ORDER
    )
@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"

 export const deleteReturnsStepId = "delete-return"
+/**
+ * This step deletes one or more returns.
+ */
 export const deleteReturnsStep = createStep(
  deleteReturnsStepId,
  async (data: { ids: string[] }, { container }) => {
@@ -2,12 +2,13 @@ import { IOrderModuleService, ReceiveOrderReturnDTO } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-type ReceiveReturnStepInput = ReceiveOrderReturnDTO
-
 export const receiveReturnStepId = "receive-return"
+/**
+ * This step marks a return as received.
+ */
 export const receiveReturnStep = createStep(
  receiveReturnStepId,
-  async (data: ReceiveReturnStepInput, { container }) => {
+  async (data: ReceiveOrderReturnDTO, { container }) => {
    const service = container.resolve<IOrderModuleService>(
      ModuleRegistrationName.ORDER
    )
@@ -4,12 +4,15 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

-interface UpdateReturnItemBySelector {
+export interface UpdateReturnItemBySelector {
  id: string
  [key: string]: any
 }

 export const updateReturnItemsStepId = "update-return-items"
+/**
+ * This step updates return items.
+ */
 export const updateReturnItemsStep = createStep(
  updateReturnItemsStepId,
  async (data: UpdateReturnItemBySelector[], { container }) => {
@@ -6,6 +6,9 @@ import {
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"

 export const updateReturnsStepId = "update-returns"
+/**
+ * This step updates one or more returns.
+ */
 export const updateReturnsStep = createStep(
  updateReturnsStepId,
  async (data: UpdateReturnDTO[], { container }) => {
@@ -3,6 +3,9 @@ import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
 import { declineOrderChangeStep } from "../steps"

 export const declineOrderChangeWorkflowId = "decline-order-change"
+/**
+ * This workflow declines an order change.
+ */
 export const declineOrderChangeWorkflow = createWorkflow(
  declineOrderChangeWorkflowId,
  (input: WorkflowData<DeclineOrderChangeDTO>): WorkflowData<void> => {
@@ -2,6 +2,9 @@ import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
 import { deleteOrderChangeActionsStep } from "../steps"

 export const deleteOrderChangeActionsWorkflowId = "delete-order-change-actions"
+/**
+ * This workflow deletes one or more order change actions.
+ */
 export const deleteOrderChangeActionsWorkflow = createWorkflow(
  deleteOrderChangeActionsWorkflowId,
  (input: WorkflowData<{ ids: string[] }>): WorkflowData<void> => {
@@ -2,6 +2,9 @@ import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
 import { deleteOrderChangesStep } from "../steps"

 export const deleteOrderChangeWorkflowId = "delete-order-change"
+/**
+ * This workflow deletes one or more order changes.
+ */
 export const deleteOrderChangeWorkflow = createWorkflow(
  deleteOrderChangeWorkflowId,
  (input: WorkflowData<{ ids: string[] }>): WorkflowData<void> => {
@@ -13,6 +13,9 @@ import {
 } from "../utils/aggregate-status"

 export const getOrderDetailWorkflowId = "get-order-detail"
+/**
+ * This workflow retrieves an order's details.
+ */
 export const getOrderDetailWorkflow = createWorkflow(
  getOrderDetailWorkflowId,
  (
@@ -12,7 +12,7 @@ import {
  getLastPaymentStatus,
 } from "../utils/aggregate-status"

-type OrderOutput =
+export type GetOrdersListWorkflowOutput =
  | OrderDTO[]
  | {
      rows: OrderDTO[]
@@ -20,6 +20,9 @@ type OrderOutput =
    }

 export const getOrdersListWorkflowId = "get-orders-list"
+/**
+ * This workflow retrieves a list of orders.
+ */
 export const getOrdersListWorkflow = createWorkflow(
  getOrdersListWorkflowId,
  (
@@ -27,7 +30,7 @@ export const getOrdersListWorkflow = createWorkflow(
      fields: string[]
      variables?: Record<string, any>
    }>
-  ): WorkflowResponse<OrderOutput> => {
+  ): WorkflowResponse<GetOrdersListWorkflowOutput> => {
    const fields = transform(input, ({ fields }) => {
      return deduplicate([
        ...fields,
@@ -10,6 +10,9 @@ import {
 import { updateOrderChangeActionsStep } from "../steps"

 export const updateOrderChangeActionsWorkflowId = "update-order-change-actions"
+/**
+ * This workflow updates one or more order change actions.
+ */
 export const updateOrderChangeActionsWorkflow = createWorkflow(
  updateOrderChangeActionsWorkflowId,
  (
@@ -56,7 +56,7 @@ const orderFields = [
  "shipping_address.province",
 ]

-type WorkflowInput = {
+export type UpdateOrderTaxLinesWorkflowInput = {
  order_id: string
  items?: OrderLineItemDTO[]
  shipping_methods?: OrderShippingMethodDTO[]
@@ -64,9 +64,12 @@ type WorkflowInput = {
 }

 export const updateOrderTaxLinesWorkflowId = "update-order-tax-lines"
+/**
+ * This workflow updates the tax lines of items and shipping methods in an order.
+ */
 export const updateOrderTaxLinesWorkflow = createWorkflow(
  updateOrderTaxLinesWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowData<void> => {
+  (input: WorkflowData<UpdateOrderTaxLinesWorkflowInput>): WorkflowData<void> => {
    const order = useRemoteQueryStep({
      entry_point: "order",
      fields: orderFields,