From 60dc8f69c75a7445cf304a0b19de66d2254e033c Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 13 Jan 2025 18:09:55 +0200 Subject: [PATCH] chore(core-flows,types): improve tsdocs of workflows [1] (#10940) --- .../src/cart/workflows/create-carts.ts | 13 +-- .../src/cart/workflows/update-cart.ts | 48 +++++++++- .../customer/workflows/create-addresses.ts | 53 ++++++++++- .../customer/workflows/create-customers.ts | 38 +++++++- .../customer/workflows/update-addresses.ts | 42 ++++++++- .../customer/workflows/update-customers.ts | 36 ++++++- .../workflows/cancel-order-fulfillment.ts | 34 ++++++- .../src/order/workflows/complete-orders.ts | 30 +++++- .../src/order/workflows/create-fulfillment.ts | 40 +++++++- .../src/order/workflows/create-order.ts | 49 +++++++++- .../src/order/workflows/create-shipment.ts | 41 +++++++- .../workflows/create-product-options.ts | 39 +++++++- .../workflows/create-product-variants.ts | 60 +++++++++++- .../src/product/workflows/create-products.ts | 58 +++++++++++- .../workflows/update-product-options.ts | 38 +++++++- .../workflows/update-product-variants.ts | 90 +++++++++++++++++- .../src/product/workflows/update-products.ts | 93 ++++++++++++++++++- .../promotion/workflows/create-campaigns.ts | 44 ++++++++- .../promotion/workflows/create-promotions.ts | 45 ++++++++- .../promotion/workflows/update-campaigns.ts | 39 +++++++- .../promotion/workflows/update-promotions.ts | 38 +++++++- packages/core/types/src/cart/workflows.ts | 44 +++++++++ .../types/src/http/common/additional_data.ts | 5 + .../src/workflow/order/cancel-fulfillment.ts | 12 +++ .../src/workflow/order/create-fulfillment.ts | 51 +++++++++- .../src/workflow/order/create-shipment.ts | 35 ++++++- .../types/src/workflows/products/mutations.ts | 21 +++++ 27 files changed, 1076 insertions(+), 60 deletions(-) diff --git a/packages/core/core-flows/src/cart/workflows/create-carts.ts b/packages/core/core-flows/src/cart/workflows/create-carts.ts index 07012a34a6297..3aae1f6c96ba1 100644 --- a/packages/core/core-flows/src/cart/workflows/create-carts.ts +++ b/packages/core/core-flows/src/cart/workflows/create-carts.ts @@ -37,7 +37,7 @@ import { updateCartPromotionsWorkflow } from "./update-cart-promotions" import { updateTaxLinesWorkflow } from "./update-tax-lines" /** - * The data to create the cart, along with custom data that's later passed to the cart's hooks. + * The data to create the cart, along with custom data that's passed to the workflow's hooks. */ export type CreateCartWorkflowInput = CreateCartWorkflowInputDTO & AdditionalData @@ -61,13 +61,18 @@ export const createCartWorkflowId = "create-cart" * quantity: 1, * } * ], - * customer_id: "cus_123" + * customer_id: "cus_123", + * additional_data: { + * external_id: "123" + * } * } * }) * * @summary * * Create a cart specifying region, items, and more. + * + * @property hooks.cartCreated - This hook is executed after a cart is created. You can consume this hook to perform custom actions on the created cart. */ export const createCartWorkflow = createWorkflow( createCartWorkflowId, @@ -229,10 +234,6 @@ export const createCartWorkflow = createWorkflow( }) ) - /** - * This hook is executed after a cart is created. You can consume this hook to perform - * custom actions on the created cart. - */ const cartCreated = createHook("cartCreated", { cart, additional_data: input.additional_data, diff --git a/packages/core/core-flows/src/cart/workflows/update-cart.ts b/packages/core/core-flows/src/cart/workflows/update-cart.ts index 2733ea15958f9..569692ea43838 100644 --- a/packages/core/core-flows/src/cart/workflows/update-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/update-cart.ts @@ -29,13 +29,57 @@ import { } from "../steps" import { refreshCartItemsWorkflow } from "./refresh-cart-items" +/** + * The data to update the cart, along with custom data that's passed to the workflow's hooks. + */ +export type UpdateCartWorkflowInput = UpdateCartWorkflowInputDTO & AdditionalData + export const updateCartWorkflowId = "update-cart" /** - * This workflow updates a cart. + * This workflow updates a cart and returns it. You can update the cart's region, address, and more. This workflow is executed by the + * [Update Cart Store API Route](https://docs.medusajs.com/api/store#carts_postcartsid). + * + * :::note + * + * This workflow doesn't allow updating a cart's line items. Instead, use {@link addToCartWorkflow} and {@link updateLineItemInCartWorkflow}. + * + * ::: + * + * This workflow has a hook that allows you to perform custom actions on the updated cart. For example, you can pass custom data under the `additional_data` property of the Update Cart API route, + * then update any associated details related to the cart in the workflow's hook. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating a cart. + * + * @example + * const { result } = await updateCartWorkflow(container) + * .run({ + * input: { + * id: "cart_123", + * region_id: "region_123", + * shipping_address: { + * first_name: "John", + * last_name: "Doe", + * address_1: "1234 Main St", + * city: "San Francisco", + * country_code: "US", + * postal_code: "94111", + * phone: "1234567890", + * }, + * additional_data: { + * external_id: "123" + * } + * } + * }) + * + * @summary + * + * Update a cart's details, such as region, address, and more. + * + * @property hooks.cartUpdated - This hook is executed after a cart is update. You can consume this hook to perform custom actions on the updated cart. */ export const updateCartWorkflow = createWorkflow( updateCartWorkflowId, - (input: WorkflowData) => { + (input: WorkflowData) => { const cartToUpdate = useRemoteQueryStep({ entry_point: "cart", variables: { id: input.id }, diff --git a/packages/core/core-flows/src/customer/workflows/create-addresses.ts b/packages/core/core-flows/src/customer/workflows/create-addresses.ts index 292a15cc6e031..a51e8f9b61ca6 100644 --- a/packages/core/core-flows/src/customer/workflows/create-addresses.ts +++ b/packages/core/core-flows/src/customer/workflows/create-addresses.ts @@ -3,7 +3,6 @@ import { CreateCustomerAddressDTO, } from "@medusajs/framework/types" import { - WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -16,17 +15,65 @@ import { maybeUnsetDefaultShippingAddressesStep, } from "../steps" +/** + * The data to create one or more customer addresses, along with custom data that's passed to the workflow's hooks. + */ export type CreateCustomerAddressesWorkflowInput = { + /** + * The addresses to create. + */ addresses: CreateCustomerAddressDTO[] } & AdditionalData export const createCustomerAddressesWorkflowId = "create-customer-addresses" /** - * This workflow creates one or more customer address. + * This workflow creates one or more addresses for customers. It's used by the [Add Customer Address Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomersidaddresses) + * and the [Add Customer Address Store API Route](https://docs.medusajs.com/api/store#customers_postcustomersmeaddresses). + * + * This workflow has a hook that allows you to perform custom actions on the created customer addresses. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the addresses. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating customer addresses. + * + * @example + * const { result } = await createCustomerAddressesWorkflow(container) + * .run({ + * input: { + * addresses: [ + * { + * customer_id: "cus_123", + * address_1: "456 Elm St", + * city: "Los Angeles", + * country_code: "us", + * postal_code: "90001", + * first_name: "Jane", + * last_name: "Smith", + * }, + * { + * customer_id: "cus_321", + * address_1: "789 Oak St", + * city: "New York", + * country_code: "us", + * postal_code: "10001", + * first_name: "Alice", + * last_name: "Johnson", + * } + * ], + * additional_data: { + * crm_id: "123" + * } + * } + * }) + * + * @summary + * + * Create one or more customer addresses. + * + * @property hooks.addressesCreated - This hook is executed after the addresses are created. You can consume this hook to perform custom actions on the created addresses. */ export const createCustomerAddressesWorkflow = createWorkflow( createCustomerAddressesWorkflowId, - (input: WorkflowData) => { + (input: CreateCustomerAddressesWorkflowInput) => { const unsetInput = transform(input, (data) => ({ create: data.addresses, })) diff --git a/packages/core/core-flows/src/customer/workflows/create-customers.ts b/packages/core/core-flows/src/customer/workflows/create-customers.ts index 1c32da682a546..dc2b167f3d561 100644 --- a/packages/core/core-flows/src/customer/workflows/create-customers.ts +++ b/packages/core/core-flows/src/customer/workflows/create-customers.ts @@ -1,7 +1,6 @@ import { AdditionalData, CreateCustomerDTO } from "@medusajs/framework/types" import { CustomerWorkflowEvents } from "@medusajs/framework/utils" import { - WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -10,17 +9,50 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { createCustomersStep } from "../steps" +/** + * The data to create one or more customers, along with custom data that's passed to the workflow's hooks. + */ export type CreateCustomersWorkflowInput = { + /** + * The customers to create. + */ customersData: CreateCustomerDTO[] } & AdditionalData export const createCustomersWorkflowId = "create-customers" /** - * This workflow creates one or more customers. + * This workflow creates one or more customers. It's used by the [Create Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomers). + * + * This workflow has a hook that allows you to perform custom actions on the created customer. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/customer/extend). + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating customers. + * + * @example + * const { result } = await createCustomersWorkflow(container) + * .run({ + * input: { + * customersData: [ + * { + * first_name: "John", + * last_name: "Doe", + * email: "john.doe@example.com", + * }, + * ], + * additional_data: { + * position_name: "Editor", + * } + * } + * }) + * + * @summary + * + * Create one or more customers. + * + * @property hooks.customersCreated - This hook is executed after the customers are created. You can consume this hook to perform custom actions on the created customers. */ export const createCustomersWorkflow = createWorkflow( createCustomersWorkflowId, - (input: WorkflowData) => { + (input: CreateCustomersWorkflowInput) => { const createdCustomers = createCustomersStep(input.customersData) const customersCreated = createHook("customersCreated", { customers: createdCustomers, diff --git a/packages/core/core-flows/src/customer/workflows/update-addresses.ts b/packages/core/core-flows/src/customer/workflows/update-addresses.ts index 1bee300a8a473..978fe51a2dc44 100644 --- a/packages/core/core-flows/src/customer/workflows/update-addresses.ts +++ b/packages/core/core-flows/src/customer/workflows/update-addresses.ts @@ -4,7 +4,6 @@ import { AdditionalData, } from "@medusajs/framework/types" import { - WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -17,18 +16,55 @@ import { updateCustomerAddressesStep, } from "../steps" +/** + * The data to update one or more customer addresses, along with custom data that's passed to the workflow's hooks. + */ export type UpdateCustomerAddressesWorkflowInput = { + /** + * The filters to select the addresses to update. + */ selector: FilterableCustomerAddressProps + /** + * The data to update in the addresses. + */ update: UpdateCustomerAddressDTO } & AdditionalData export const updateCustomerAddressesWorkflowId = "update-customer-addresses" /** - * This workflow updates one or more customer addresses. + * This workflow updates one or more addresses for customers. It's used by the [Update Customer Address Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomersidaddressesaddress_id) + * and the [Update Customer Address Store API Route](https://docs.medusajs.com/api/store#customers_postcustomersmeaddressesaddress_id). + * + * This workflow has a hook that allows you to perform custom actions on the updated customer addresses. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the addresses. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating customer addresses. + * + * @example + * const { result } = await updateCustomerAddressesWorkflow(container) + * .run({ + * input: { + * selector: { + * customer_id: "123" + * }, + * update: { + * first_name: "John" + * }, + * additional_data: { + * crm_id: "123" + * } + * } + * }) + * + * @summary + * + * Update one or more customer addresses. + * + * @property hooks.addressesUpdated - This hook is executed after the addresses are updated. You can consume this hook to perform custom actions on the updated addresses. */ export const updateCustomerAddressesWorkflow = createWorkflow( updateCustomerAddressesWorkflowId, - (input: WorkflowData) => { + (input: UpdateCustomerAddressesWorkflowInput) => { const unsetInput = transform(input, (data) => ({ update: data, })) diff --git a/packages/core/core-flows/src/customer/workflows/update-customers.ts b/packages/core/core-flows/src/customer/workflows/update-customers.ts index 370044b61ec23..c789cb5b8983f 100644 --- a/packages/core/core-flows/src/customer/workflows/update-customers.ts +++ b/packages/core/core-flows/src/customer/workflows/update-customers.ts @@ -14,14 +14,48 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { updateCustomersStep } from "../steps" +/** + * The data to update one or more customers, along with custom data that's passed to the workflow's hooks. + */ export type UpdateCustomersWorkflowInput = { + /** + * The filters to select the customers to update. + */ selector: FilterableCustomerProps + /** + * The data to update in the customers. + */ update: CustomerUpdatableFields } & AdditionalData export const updateCustomersWorkflowId = "update-customers" /** - * This workflow updates one or more customers. + * This workflow updates one or more customers. It's used by the [Update Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomersid) and + * the [Update Customer Store API Route](https://docs.medusajs.com/api/store#customers_postcustomersme). + * + * This workflow has a hook that allows you to perform custom actions on the updated customer. For example, you can pass under `additional_data` custom data to update + * custom data models linked to the customers. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating customers. + * + * @example + * const { result } = await updateCustomersWorkflow(container) + * .run({ + * input: { + * selector: { + * id: ["cus_123"] + * }, + * update: { + * first_name: "John" + * } + * } + * }) + * + * @summary + * + * Update one or more customers. + * + * @property hooks.customersUpdated - This hook is executed after the customers are updated. You can consume this hook to perform custom actions on the updated customers. */ export const updateCustomersWorkflow = createWorkflow( updateCustomersWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts b/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts index 30905c1f586c1..9a62d173c6f46 100644 --- a/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts +++ b/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts @@ -115,16 +115,42 @@ function prepareInventoryUpdate({ } } +/** + * The data to cancel an order's fulfillment, along with custom data that's passed to the workflow's hooks. + */ +export type CancelOrderFulfillmentWorkflowInput = OrderWorkflow.CancelOrderFulfillmentWorkflowInput & AdditionalData + export const cancelOrderFulfillmentWorkflowId = "cancel-order-fulfillment" /** - * This workflow cancels an order's fulfillment. + * This workflow cancels an order's fulfillment. It's used by the [Cancel Order's Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idcancel). + * + * This workflow has a hook that allows you to perform custom actions on the canceled fulfillment. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the fulfillment. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around canceling a fulfillment. + * + * @example + * const { result } = await cancelOrderFulfillmentWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * fulfillment_id: "ful_123", + * additional_data: { + * reason: "Customer changed their mind" + * } + * } + * }) + * + * @summary + * + * Cancel an order's fulfillment. + * + * @property hooks.orderFulfillmentCanceled - This hook is executed after the fulfillment is canceled. You can consume this hook to perform custom actions on the canceled fulfillment. */ export const cancelOrderFulfillmentWorkflow = createWorkflow( cancelOrderFulfillmentWorkflowId, ( - input: WorkflowData< - OrderWorkflow.CancelOrderFulfillmentWorkflowInput & AdditionalData - > + input: WorkflowData ) => { const order: OrderDTO & { fulfillments: FulfillmentDTO[] } = useRemoteQueryStep({ diff --git a/packages/core/core-flows/src/order/workflows/complete-orders.ts b/packages/core/core-flows/src/order/workflows/complete-orders.ts index ed835aaa92647..3285a2947cdb4 100644 --- a/packages/core/core-flows/src/order/workflows/complete-orders.ts +++ b/packages/core/core-flows/src/order/workflows/complete-orders.ts @@ -10,13 +10,41 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { completeOrdersStep } from "../steps" +/** + * The orders to complete, along with custom data that's passed to the workflow's hooks. + */ export type CompleteOrdersWorkflowInput = { + /** + * The IDs of the orders to complete. + */ orderIds: string[] } & AdditionalData export const completeOrderWorkflowId = "complete-order-workflow" /** - * This workflow completes one or more orders. + * This workflow marks one or more orders as completed. It's used by the [Complete Cart Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidcomplete). + * + * This workflow has a hook that allows you to perform custom actions on the completed orders. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the orders. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around order completion. + * + * @example + * const { result } = await completeOrderWorkflow(container) + * .run({ + * input: { + * orderIds: ["order_1", "order_2"], + * additional_data: { + * send_webhook: true, + * } + * } + * }) + * + * @summary + * + * Complete one or more orders. + * + * @property hooks.ordersCompleted - This hook is executed after the orders are completed. You can consume this hook to perform custom actions on the completed orders. */ export const completeOrderWorkflow = createWorkflow( completeOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/create-fulfillment.ts b/packages/core/core-flows/src/order/workflows/create-fulfillment.ts index 8710639ce5404..c5801024e4014 100644 --- a/packages/core/core-flows/src/order/workflows/create-fulfillment.ts +++ b/packages/core/core-flows/src/order/workflows/create-fulfillment.ts @@ -14,7 +14,6 @@ import { OrderWorkflowEvents, } from "@medusajs/framework/utils" import { - WorkflowData, WorkflowResponse, createHook, createStep, @@ -236,16 +235,47 @@ function prepareInventoryUpdate({ } } +/** + * The details of the fulfillment to create, along with custom data that's passed to the workflow's hooks. + */ +export type CreateOrderFulfillmentWorkflowInput = OrderWorkflow.CreateOrderFulfillmentWorkflowInput & AdditionalData + export const createOrderFulfillmentWorkflowId = "create-order-fulfillment" /** - * This creates a fulfillment for an order. + * This workflow creates a fulfillment for an order. It's used by the [Create Order Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidfulfillments). + * + * This workflow has a hook that allows you to perform custom actions on the created fulfillment. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the fulfillment. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating a fulfillment. + * + * @example + * const { result } = await createOrderFulfillmentWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ], + * additional_data: { + * send_oms: true + * } + * } + * }) + * + * @summary + * + * Creates a fulfillment for an order. + * + * @property hooks.fulfillmentCreated - This hook is executed after the fulfillment is created. You can consume this hook to perform custom actions on the created fulfillment. */ export const createOrderFulfillmentWorkflow = createWorkflow( createOrderFulfillmentWorkflowId, ( - input: WorkflowData< - OrderWorkflow.CreateOrderFulfillmentWorkflowInput & AdditionalData - > + input: CreateOrderFulfillmentWorkflowInput ) => { const order: OrderDTO = useRemoteQueryStep({ entry_point: "orders", diff --git a/packages/core/core-flows/src/order/workflows/create-order.ts b/packages/core/core-flows/src/order/workflows/create-order.ts index 4ccd369b275b0..31247ef820bc0 100644 --- a/packages/core/core-flows/src/order/workflows/create-order.ts +++ b/packages/core/core-flows/src/order/workflows/create-order.ts @@ -1,7 +1,6 @@ import { AdditionalData, CreateOrderDTO } from "@medusajs/framework/types" import { MedusaError, isDefined, isPresent } from "@medusajs/framework/utils" import { - WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -77,13 +76,57 @@ function getOrderInput(data) { return data_ } +export type CreateOrderWorkflowInput = CreateOrderDTO & AdditionalData + export const createOrdersWorkflowId = "create-orders" /** - * This workflow creates an order. + * This workflow creates an order. It's used by the [Create Draft Order Admin API Route](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders), but + * you can also use it to create any order. + * + * This workflow has a hook that allows you to perform custom actions on the created order. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the order. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating an order. For example, + * you can create a workflow that imports orders from an external system, then uses this workflow to create the orders in Medusa. + * + * @example + * const { result } = await createOrderWorkflow(container) + * .run({ + * input: { + * region_id: "reg_123", + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1, + * title: "Shirt", + * unit_price: 10 + * } + * ], + * sales_channel_id: "sc_123", + * status: "pending", + * shipping_address: { + * first_name: "John", + * last_name: "Doe", + * address_1: "123 Main St", + * city: "Los Angeles", + * country_code: "us", + * postal_code: "90001" + * }, + * additional_data: { + * sync_oms: true + * } + * } + * }) + * + * @summary + * + * Create an order. + * + * @property hooks.orderCreated - This hook is executed after the order is created. You can consume this hook to perform custom actions on the created order. */ export const createOrderWorkflow = createWorkflow( createOrdersWorkflowId, - (input: WorkflowData) => { + (input: CreateOrderWorkflowInput) => { const variantIds = transform({ input }, (data) => { return (data.input.items ?? []) .map((item) => item.variant_id) diff --git a/packages/core/core-flows/src/order/workflows/create-shipment.ts b/packages/core/core-flows/src/order/workflows/create-shipment.ts index a35365b884d11..c300553b5be2d 100644 --- a/packages/core/core-flows/src/order/workflows/create-shipment.ts +++ b/packages/core/core-flows/src/order/workflows/create-shipment.ts @@ -6,7 +6,6 @@ import { } from "@medusajs/framework/types" import { FulfillmentEvents, Modules } from "@medusajs/framework/utils" import { - WorkflowData, WorkflowResponse, createHook, createStep, @@ -76,16 +75,48 @@ function prepareRegisterShipmentData({ } } +/** + * The data to create a shipment for an order, along with custom data that's passed to the workflow's hooks. + */ +export type CreateOrderShipmentWorkflowInput = OrderWorkflow.CreateOrderShipmentWorkflowInput & AdditionalData + export const createOrderShipmentWorkflowId = "create-order-shipment" /** - * This workflow creates a shipment for an order. + * This workflow creates a shipment for an order. It's used by the [Create Order Shipment Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idshipments). + * + * This workflow has a hook that allows you to perform custom actions on the created shipment. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the shipment. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating a shipment. + * + * @example + * const { result } = await createOrderShipmentWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * fulfillment_id: "fulfillment_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1 + * } + * ], + * additional_data: { + * oms_id: "123" + * } + * } + * }) + * + * @summary + * + * Creates a shipment for an order. + * + * @property hooks.shipmentCreated - This hook is executed after the shipment is created. You can consume this hook to perform custom actions on the created shipment. */ export const createOrderShipmentWorkflow = createWorkflow( createOrderShipmentWorkflowId, ( - input: WorkflowData< - OrderWorkflow.CreateOrderShipmentWorkflowInput & AdditionalData - > + input: CreateOrderShipmentWorkflowInput ) => { const order: OrderDTO = useRemoteQueryStep({ entry_point: "orders", diff --git a/packages/core/core-flows/src/product/workflows/create-product-options.ts b/packages/core/core-flows/src/product/workflows/create-product-options.ts index ac7f64ddd665c..7807eea1b975c 100644 --- a/packages/core/core-flows/src/product/workflows/create-product-options.ts +++ b/packages/core/core-flows/src/product/workflows/create-product-options.ts @@ -10,13 +10,50 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { createProductOptionsStep } from "../steps" +/** + * The data to create one or more product options, along with custom data that's passed to the workflow's hooks. + */ export type CreateProductOptionsWorkflowInput = { + /** + * The product options to create. + */ product_options: ProductTypes.CreateProductOptionDTO[] } & AdditionalData export const createProductOptionsWorkflowId = "create-product-options" /** - * This workflow creates one or more product options. + * This workflow creates one or more product options. It's used by the [Create Product Option Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidoptions). + * + * This workflow has a hook that allows you to perform custom actions on the created product options. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the product options. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-option creation. + * + * @example + * const { result } = await createProductOptionsWorkflow(container) + * .run({ + * input: { + * product_options: [ + * { + * title: "Size", + * values: ["S", "M", "L", "XL"] + * }, + * { + * title: "Color", + * values: ["Red", "Blue", "Green"] + * } + * ], + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Create one or more product options. + * + * @property hooks.productOptionsCreated - This hook is executed after the product options are created. You can consume this hook to perform custom actions on the created product options. */ export const createProductOptionsWorkflow = createWorkflow( createProductOptionsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/create-product-variants.ts b/packages/core/core-flows/src/product/workflows/create-product-variants.ts index f62c7c24ebc35..1bd16ccf2db73 100644 --- a/packages/core/core-flows/src/product/workflows/create-product-variants.ts +++ b/packages/core/core-flows/src/product/workflows/create-product-variants.ts @@ -26,15 +26,36 @@ import { createProductVariantsStep } from "../steps/create-product-variants" import { createVariantPricingLinkStep } from "../steps/create-variant-pricing-link" /** + * + * The data to create one or more product variants, along with custom data that's passed to the workflow's hooks. + * * @privateRemarks * TODO: Create separate typings for the workflow input */ export type CreateProductVariantsWorkflowInput = { + /** + * The product variants to create. + */ product_variants: (ProductTypes.CreateProductVariantDTO & { + /** + * The product variant's prices. + */ prices?: PricingTypes.CreateMoneyAmountDTO[] } & { + /** + * The inventory items to associate with managed product variants. + */ inventory_items?: { + /** + * The inventory item's ID. + */ inventory_item_id: string + /** + * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, + * Medusa checks the availability of the quantity multiplied by the value set for `required_quantity`. + * When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value + * set for `required_quantity`. + */ required_quantity?: number }[] })[] @@ -179,7 +200,44 @@ const buildVariantItemCreateMap = (data: { export const createProductVariantsWorkflowId = "create-product-variants" /** - * This workflow creates one or more product variants. + * This workflow creates one or more product variants. It's used by the [Create Product Variant Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariants). + * + * This workflow has a hook that allows you to perform custom actions on the created product variants. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the product variants. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-variant creation. + * + * @example + * const { result } = await createProductVariantsWorkflow(container) + * .run({ + * input: { + * product_variants: [ + * { + * product_id: "prod_123", + * sku: "SHIRT-123", + * title: "Small Shirt", + * prices: [ + * { + * amount: 10, + * currency_code: "USD", + * }, + * ], + * options: { + * Size: "Small", + * }, + * }, + * ], + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Create one or more product variants. + * + * @property hooks.productVariantsCreated - This hook is executed after the product variants are created. You can consume this hook to perform custom actions on the created product variants. */ export const createProductVariantsWorkflow = createWorkflow( createProductVariantsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/create-products.ts b/packages/core/core-flows/src/product/workflows/create-products.ts index 84571f34d8e7c..9cecee9ebc3ca 100644 --- a/packages/core/core-flows/src/product/workflows/create-products.ts +++ b/packages/core/core-flows/src/product/workflows/create-products.ts @@ -30,7 +30,7 @@ const validateProductInputStepId = "validate-product-input" /** * This step validates a product data before creation. */ -const validateProductInputStep = createStep( +export const validateProductInputStep = createStep( validateProductInputStepId, async (data: ValidateProductInputStepInput) => { const { products } = data @@ -50,13 +50,67 @@ const validateProductInputStep = createStep( } ) +/** + * The data to create one or more products, along with custom data that's passed to the workflow's hooks. + */ export type CreateProductsWorkflowInput = { + /** + * The products to create. + */ products: CreateProductWorkflowInputDTO[] } & AdditionalData export const createProductsWorkflowId = "create-products" /** - * This workflow creates one or more products. + * This workflow creates one or more products. It's used by the [Create Product Admin API Route](https://docs.medusajs.com/api/admin#products_postproducts). + * It can also be useful to you when creating [seed scripts](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data), for example. + * + * This workflow has a hook that allows you to perform custom actions on the created products. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/product/extend). + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product creation. + * + * @example + * const { result } = await createProductsWorkflow(container) + * .run({ + * input: { + * products: [ + * { + * title: "Shirt", + * options: [ + * { + * title: "Size", + * values: ["S", "M", "L"] + * } + * ], + * variants: [ + * { + * title: "Small Shirt", + * sku: "SMALLSHIRT", + * options: { + * Size: "S" + * }, + * prices: [ + * { + * amount: 10, + * currency_code: "usd" + * } + * ], + * manage_inventory: true, + * }, + * ] + * } + * ], + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Create one or more products with options and variants. + * + * @property hooks.productCreated - This hook is executed after the products are created. You can consume this hook to perform custom actions on the created products. */ export const createProductsWorkflow = createWorkflow( createProductsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/update-product-options.ts b/packages/core/core-flows/src/product/workflows/update-product-options.ts index e93bc1198fe45..f4aec3f8f4ab1 100644 --- a/packages/core/core-flows/src/product/workflows/update-product-options.ts +++ b/packages/core/core-flows/src/product/workflows/update-product-options.ts @@ -10,14 +10,50 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { updateProductOptionsStep } from "../steps" +/** + * The data to update one or more product options, along with custom data that's passed to the workflow's hooks. + */ export type UpdateProductOptionsWorkflowInput = { + /** + * The filters to select the product options to update. + */ selector: ProductTypes.FilterableProductOptionProps + /** + * The data to update in the product options. + */ update: ProductTypes.UpdateProductOptionDTO } & AdditionalData export const updateProductOptionsWorkflowId = "update-product-options" /** - * This workflow updates product options matching the specified filters. + * This workflow updates one or more product options. It's used by the [Update Product Option Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id). + * + * This workflow has a hook that allows you to perform custom actions on the updated product options. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the product options. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-option update. + * + * @example + * const { result } = await updateProductOptionsWorkflow(container) + * .run({ + * input: { + * selector: { + * title: "Color" + * }, + * update: { + * values: ["Red", "Blue", "Green"] + * }, + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Update one or more product options. + * + * @property hooks.productOptionsUpdated - This hook is executed after the product options are updated. You can consume this hook to perform custom actions on the updated product options. */ export const updateProductOptionsWorkflow = createWorkflow( updateProductOptionsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/update-product-variants.ts b/packages/core/core-flows/src/product/workflows/update-product-variants.ts index 96818b3175cc1..cb17e0e051225 100644 --- a/packages/core/core-flows/src/product/workflows/update-product-variants.ts +++ b/packages/core/core-flows/src/product/workflows/update-product-variants.ts @@ -16,27 +16,109 @@ import { updatePriceSetsStep } from "../../pricing" import { updateProductVariantsStep } from "../steps" import { getVariantPricingLinkStep } from "../steps/get-variant-pricing-link" +/** + * The data to update one or more product variants, along with custom data that's passed to the workflow's hooks. + */ export type UpdateProductVariantsWorkflowInput = - | { + (| { + /** + * A filter to select the product variants to update. + */ selector: ProductTypes.FilterableProductVariantProps + /** + * The data to update in the product variants. + */ update: ProductTypes.UpdateProductVariantDTO & { + /** + * The product variant's prices. + */ prices?: Partial[] } } | { + /** + * The product variants to update. + */ product_variants: (ProductTypes.UpsertProductVariantDTO & { + /** + * The product variant's prices. + */ prices?: Partial[] })[] - } + }) & AdditionalData export const updateProductVariantsWorkflowId = "update-product-variants" /** - * This workflow updates one or more product variants. + * This workflow updates one or more product variants. It's used by the [Update Product Variant Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id). + * + * This workflow has a hook that allows you to perform custom actions on the updated product variants. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the product variants. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-variant update. + * + * @example + * To update product variants by their IDs: + * + * ```ts + * const { result } = await updateProductVariantsWorkflow(container) + * .run({ + * input: { + * product_variants: [ + * { + * id: "variant_123", + * prices: [ + * { + * amount: 10, + * currency_code: "usd", + * } + * ] + * }, + * { + * id: "variant_321", + * title: "Small Shirt", + * }, + * ], + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * ``` + * + * You can also update product variants by a selector: + * + * ```ts + * const { result } = await updateProductVariantsWorkflow(container) + * .run({ + * input: { + * selector: { + * product_id: "prod_123" + * }, + * update: { + * prices: [ + * { + * amount: 10, + * currency_code: "usd" + * } + * ] + * }, + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * ``` + * + * @summary + * + * Update one or more product variants. + * + * @property hooks.productVariantsUpdated - This hook is executed after the product variants are updated. You can consume this hook to perform custom actions on the updated product variants. */ export const updateProductVariantsWorkflow = createWorkflow( updateProductVariantsWorkflowId, ( - input: WorkflowData + input: WorkflowData ) => { // Passing prices to the product module will fail, we want to keep them for after the variant is updated. const updateWithoutPrices = transform({ input }, (data) => { diff --git a/packages/core/core-flows/src/product/workflows/update-products.ts b/packages/core/core-flows/src/product/workflows/update-products.ts index a9bcf84ed1439..8ed2a6ff7d5de 100644 --- a/packages/core/core-flows/src/product/workflows/update-products.ts +++ b/packages/core/core-flows/src/product/workflows/update-products.ts @@ -27,21 +27,51 @@ import { } from "../../common" import { upsertVariantPricesWorkflow } from "./upsert-variant-prices" +/** + * Update products that match a specified selector, along with custom data that's passed to the workflow's hooks. + */ export type UpdateProductsWorkflowInputSelector = { + /** + * The filters to find products to update. + */ selector: ProductTypes.FilterableProductProps + /** + * The data to update the products with. + */ update: Omit & { + /** + * The sales channels that the products are available in. + */ sales_channels?: { id: string }[] + /** + * The variants to update. + */ variants?: UpdateProductVariantWorkflowInputDTO[] } } & AdditionalData +/** + * Update one or more products, along with custom data that's passed to the workflow's hooks. + */ export type UpdateProductsWorkflowInputProducts = { + /** + * The products to update. + */ products: (Omit & { + /** + * The sales channels that the products are available in. + */ sales_channels?: { id: string }[] + /** + * The variants to update. + */ variants?: UpdateProductVariantWorkflowInputDTO[] })[] } & AdditionalData +/** + * The data to update one or more products, along with custom data that's passed to the workflow's hooks. + */ export type UpdateProductWorkflowInput = | UpdateProductsWorkflowInputSelector | UpdateProductsWorkflowInputProducts @@ -215,7 +245,68 @@ function prepareToDeleteSalesChannelLinks({ export const updateProductsWorkflowId = "update-products" /** - * This workflow updates one or more products. + * This workflow updates one or more products. It's used by the [Update Product Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsid). + * + * This workflow has a hook that allows you to perform custom actions on the updated products. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the products. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product update. + * + * @example + * To update products by their IDs: + * + * ```ts + * const { result } = await updateProductsWorkflow(container) + * .run({ + * input: { + * products: [ + * { + * id: "prod_123", + * title: "Shirts" + * }, + * { + * id: "prod_321", + * variants: [ + * { + * id: "variant_123", + * options: { + * Size: "S" + * } + * } + * ] + * } + * ], + * additional_data: { + * erp_id: "erp_123" + * } + * } + * }) + * ``` + * + * You can also update products by a selector: + * + * ```ts + * const { result } = await updateProductsWorkflow(container) + * .run({ + * input: { + * selector: { + * type_id: ["ptyp_123"] + * }, + * update: { + * description: "This is a shirt product" + * }, + * additional_data: { + * erp_id: "erp_123" + * } + * } + * }) + * ``` + * + * @summary + * + * Update one or more products with options and variants. + * + * @property hooks.productsUpdated - This hook is executed after the products are updated. You can consume this hook to perform custom actions on the updated products. */ export const updateProductsWorkflow = createWorkflow( updateProductsWorkflowId, diff --git a/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts b/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts index e1b3cdfc8f703..b9e0f262a8ead 100644 --- a/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts +++ b/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts @@ -1,23 +1,61 @@ import { AdditionalData, CreateCampaignDTO } from "@medusajs/framework/types" import { - WorkflowData, WorkflowResponse, createHook, createWorkflow, } from "@medusajs/framework/workflows-sdk" import { createCampaignsStep } from "../steps" +/** + * The data to create one or more campaigns, along with custom data that's passed to the workflow's hooks. + */ export type CreateCampaignsWorkflowInput = { + /** + * The campaigns to create. + */ campaignsData: CreateCampaignDTO[] } & AdditionalData export const createCampaignsWorkflowId = "create-campaigns" /** - * This workflow creates one or more campaigns. + * This workflow creates one or more campaigns. It's used by the [Create Campaign Admin API Route](https://docs.medusajs.com/api/admin#campaigns_postcampaigns). + * + * This workflow has a hook that allows you to perform custom actions on the created campaigns. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the campaigns. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating campaigns. + * + * @example + * const { result } = await createCampaignsWorkflow(container) + * .run({ + * input: { + * campaignsData: [ + * { + * name: "Launch Promotions", + * campaign_identifier: "GA-123456", + * starts_at: new Date("2025-01-01"), + * ends_at: new Date("2026-01-01"), + * budget: { + * type: "usage", + * limit: 100, + * } + * } + * ], + * additional_data: { + * target_audience: "new_customers" + * } + * } + * }) + * + * @summary + * + * Create one or more campaigns. + * + * @property hooks.campaignsCreated - This hook is executed after the campaigns are created. You can consume this hook to perform custom actions on the created campaigns. */ export const createCampaignsWorkflow = createWorkflow( createCampaignsWorkflowId, - (input: WorkflowData) => { + (input: CreateCampaignsWorkflowInput) => { const createdCampaigns = createCampaignsStep(input.campaignsData) const campaignsCreated = createHook("campaignsCreated", { campaigns: createdCampaigns, diff --git a/packages/core/core-flows/src/promotion/workflows/create-promotions.ts b/packages/core/core-flows/src/promotion/workflows/create-promotions.ts index 7318de07084ed..0ef246148be6f 100644 --- a/packages/core/core-flows/src/promotion/workflows/create-promotions.ts +++ b/packages/core/core-flows/src/promotion/workflows/create-promotions.ts @@ -1,23 +1,62 @@ import { AdditionalData, CreatePromotionDTO } from "@medusajs/framework/types" import { - WorkflowData, WorkflowResponse, createHook, createWorkflow, } from "@medusajs/framework/workflows-sdk" import { createPromotionsStep } from "../steps" +/** + * The data to create one or more promotions, along with custom data that's passed to the workflow's hooks. + */ export type CreatePromotionsWorkflowInput = { + /** + * The promotions to create. + */ promotionsData: CreatePromotionDTO[] } & AdditionalData export const createPromotionsWorkflowId = "create-promotions" /** - * This workflow creates one or more promotions. + * This workflow creates one or more promotions. It's used by the [Create Promotion Admin API Route](https://docs.medusajs.com/api/admin#promotions_postpromotions). + * + * This workflow has a hook that allows you to perform custom actions on the created promotion. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the promotions. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating promotions. + * + * @example + * const { result } = await createPromotionsWorkflow(container) + * .run({ + * input: { + * promotionsData: [ + * { + * code: "10OFF", + * type: "standard", + * application_method: { + * type: "percentage", + * target_type: "items", + * allocation: "across", + * value: 10, + * currency_code: "usd" + * } + * } + * ], + * additional_data: { + * external_id: "123" + * } + * } + * }) + * + * @summary + * + * Create one or more promotions. + * + * @property hooks.promotionsCreated - This hook is executed after the promotions are created. You can consume this hook to perform custom actions on the created promotions. */ export const createPromotionsWorkflow = createWorkflow( createPromotionsWorkflowId, - (input: WorkflowData) => { + (input: CreatePromotionsWorkflowInput) => { const createdPromotions = createPromotionsStep(input.promotionsData) const promotionsCreated = createHook("promotionsCreated", { promotions: createdPromotions, diff --git a/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts b/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts index 15a36f7f613d2..9848e4b7af6c1 100644 --- a/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts +++ b/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts @@ -1,23 +1,56 @@ import { AdditionalData, UpdateCampaignDTO } from "@medusajs/framework/types" import { - WorkflowData, WorkflowResponse, createHook, createWorkflow, } from "@medusajs/framework/workflows-sdk" import { updateCampaignsStep } from "../steps" +/** + * The data to update one or more campaigns, along with custom data that's passed to the workflow's hooks. + */ export type UpdateCampaignsWorkflowInput = { + /** + * The campaigns to update. + */ campaignsData: UpdateCampaignDTO[] } & AdditionalData export const updateCampaignsWorkflowId = "update-campaigns" /** - * This workflow updates one or more campaigns. + * This workflow updates one or more campaigns. It's used by the [Update Campaign Admin API Route](https://docs.medusajs.com/api/admin#campaigns_postcampaignsid). + * + * This workflow has a hook that allows you to perform custom actions on the updated campaigns. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the campaigns. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating campaigns. + * + * @example + * const { result } = await updateCampaignsWorkflow(container) + * .run({ + * input: { + * campaignsData: [ + * { + * id: "camp_123", + * name: "Launch Promotions", + * ends_at: new Date("2026-01-01"), + * } + * ], + * additional_data: { + * target_audience: "new_customers" + * } + * } + * }) + * + * @summary + * + * Update one or more campaigns. + * + * @property hooks.campaignsUpdated - This hook is executed after the campaigns are updated. You can consume this hook to perform custom actions on the updated campaigns. */ export const updateCampaignsWorkflow = createWorkflow( updateCampaignsWorkflowId, - (input: WorkflowData) => { + (input: UpdateCampaignsWorkflowInput) => { const updatedCampaigns = updateCampaignsStep(input.campaignsData) const campaignsUpdated = createHook("campaignsUpdated", { campaigns: updatedCampaigns, diff --git a/packages/core/core-flows/src/promotion/workflows/update-promotions.ts b/packages/core/core-flows/src/promotion/workflows/update-promotions.ts index 600d996e2443e..4950675330a7f 100644 --- a/packages/core/core-flows/src/promotion/workflows/update-promotions.ts +++ b/packages/core/core-flows/src/promotion/workflows/update-promotions.ts @@ -1,23 +1,55 @@ import { AdditionalData, UpdatePromotionDTO } from "@medusajs/framework/types" import { - WorkflowData, WorkflowResponse, createHook, createWorkflow, } from "@medusajs/framework/workflows-sdk" import { updatePromotionsStep } from "../steps" +/** + * The data to update one or more promotions, along with custom data that's passed to the workflow's hooks. + */ export type UpdatePromotionsWorkflowInput = { + /** + * The promotions to update. + */ promotionsData: UpdatePromotionDTO[] } & AdditionalData export const updatePromotionsWorkflowId = "update-promotions" /** - * This workflow updates one or more promotions. + * This workflow updates one or more promotions. It's used by the [Update Promotion Admin API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsid). + * + * This workflow has a hook that allows you to perform custom actions on the updated promotion. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the promotions. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating promotions. + * + * @example + * const { result } = await updatePromotionsWorkflow(container) + * .run({ + * input: { + * promotionsData: [ + * { + * id: "promo_123", + * code: "10OFF", + * } + * ], + * additional_data: { + * external_id: "123" + * } + * } + * }) + * + * @summary + * + * Update one or more promotions. + * + * @property hooks.promotionsUpdated - This hook is executed after the promotions are updated. You can consume this hook to perform custom actions on the updated promotions. */ export const updatePromotionsWorkflow = createWorkflow( updatePromotionsWorkflowId, - (input: WorkflowData) => { + (input: UpdatePromotionsWorkflowInput) => { const updatedPromotions = updatePromotionsStep(input.promotionsData) const promotionsUpdated = createHook("promotionsUpdated", { promotions: updatedPromotions, diff --git a/packages/core/types/src/cart/workflows.ts b/packages/core/types/src/cart/workflows.ts index b64d1d448a42a..7365ecbebb053 100644 --- a/packages/core/types/src/cart/workflows.ts +++ b/packages/core/types/src/cart/workflows.ts @@ -272,16 +272,60 @@ export interface AddToCartWorkflowInputDTO { items: CreateCartCreateLineItemDTO[] } +/** + * The details to update in a cart. + */ export interface UpdateCartWorkflowInputDTO { + /** + * The ID of the cart to update. + */ id: string + + /** + * An array of promotional codes applied on the cart. + */ promo_codes?: string[] + + /** + * The ID of the cart's region. + */ region_id?: string + + /** + * The ID of the cart's customer. + */ customer_id?: string | null + + /** + * The ID of the cart's sales channel. + */ sales_channel_id?: string | null + + /** + * The email address of the cart's customer. + */ email?: string | null + + /** + * The currency code for the cart. + * + * @example usd + */ currency_code?: string + + /** + * Custom key-value pairs of data related to the cart. + */ metadata?: Record | null + + /** + * The cart's shipping address. You can either update the cart's existing shipping address, or create a new one. + */ shipping_address?: CreateAddressDTO | UpdateAddressDTO | null + + /** + * The cart's billing address. You can either update the cart's existing billing address, or create a new one. + */ billing_address?: CreateAddressDTO | UpdateAddressDTO | null } diff --git a/packages/core/types/src/http/common/additional_data.ts b/packages/core/types/src/http/common/additional_data.ts index b813d38a1019c..20bec6a356277 100644 --- a/packages/core/types/src/http/common/additional_data.ts +++ b/packages/core/types/src/http/common/additional_data.ts @@ -5,5 +5,10 @@ * Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data). */ export type AdditionalData = { + /** + * Additional data that can be passed through the `additional_data` property in HTTP requests. + * + * Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data). + */ additional_data?: Record } diff --git a/packages/core/types/src/workflow/order/cancel-fulfillment.ts b/packages/core/types/src/workflow/order/cancel-fulfillment.ts index 1279a7df7ab87..25c6afec35f48 100644 --- a/packages/core/types/src/workflow/order/cancel-fulfillment.ts +++ b/packages/core/types/src/workflow/order/cancel-fulfillment.ts @@ -1,6 +1,18 @@ export interface CancelOrderFulfillmentWorkflowInput { + /** + * The ID of the order to cancel its fulfillment. + */ order_id: string + /** + * The ID of the fulfillment to cancel. + */ fulfillment_id: string + /** + * Whether to notify the customer about the cancellation. + */ no_notification?: boolean + /** + * The ID of the user that canceled the fulfillment. + */ canceled_by?: string } diff --git a/packages/core/types/src/workflow/order/create-fulfillment.ts b/packages/core/types/src/workflow/order/create-fulfillment.ts index 9fd20c1bc78f8..db479d7d26db4 100644 --- a/packages/core/types/src/workflow/order/create-fulfillment.ts +++ b/packages/core/types/src/workflow/order/create-fulfillment.ts @@ -2,19 +2,68 @@ import { OrderLineItemDTO } from "../../order" import { BigNumberInput } from "../../totals" import { CreateFulfillmentLabelWorkflowDTO } from "../fulfillment/create-fulfillment" +/** + * The details of an item in the fulfillment. + */ interface CreateOrderFulfillmentItem { + /** + * The ID of the order's item to fulfill. + */ id: string + /** + * The quantity of the item to fulfill. + */ quantity: BigNumberInput } +/** + * The details of the fulfillment to create. + */ export interface CreateOrderFulfillmentWorkflowInput { + /** + * The ID of the order to create the fulfillment for. + */ order_id: string + + /** + * The list of items in the order. If not provided, the order's items are used. + */ items_list?: OrderLineItemDTO[] - created_by?: string // The id of the authenticated user + + /** + * The ID of the user who created the fulfillment. + */ + created_by?: string + + /** + * A list of items to be fulfilled. + */ items: CreateOrderFulfillmentItem[] + + /** + * The labels to associate with the order. + */ labels?: CreateFulfillmentLabelWorkflowDTO[] + + /** + * Whether the notify the customer about the fulfillment. + */ no_notification?: boolean + + /** + * The ID of the stock location to fulfill items from. If not provided, the workflow uses the ID + * of the location associated with the shipping option used by the order's + * shipping method. + */ location_id?: string | null + + /** + * Custom k-value pairs related to the fulfillment. + */ metadata?: Record | null + + /** + * Whether the fulfillment should be shipped. + */ requires_shipping?: boolean } diff --git a/packages/core/types/src/workflow/order/create-shipment.ts b/packages/core/types/src/workflow/order/create-shipment.ts index 024e107489bfa..5d9a114e102e7 100644 --- a/packages/core/types/src/workflow/order/create-shipment.ts +++ b/packages/core/types/src/workflow/order/create-shipment.ts @@ -2,17 +2,50 @@ import { MetadataType } from "../../common" import { BigNumberInput } from "../../totals" import { CreateFulfillmentLabelWorkflowDTO } from "../fulfillment" +/** + * The details of an item in the shipment. + */ interface CreateOrderShipmentItem { + /** + * The ID of the order's item to ship. + */ id: string + /** + * The quantity of the item to ship. + */ quantity: BigNumberInput } +/** + * The details required to create a shipment for an order. + */ export interface CreateOrderShipmentWorkflowInput { + /** + * The ID of the order to create a shipment for. + */ order_id: string + /** + * The ID of the fulfillment to create a shipment for. + */ fulfillment_id: string - created_by?: string // The id of the authenticated user + /** + * The ID of the user creating the shipment. + */ + created_by?: string + /** + * The items to create a shipment for. + */ items: CreateOrderShipmentItem[] + /** + * The shipment's labels. + */ labels?: CreateFulfillmentLabelWorkflowDTO[] + /** + * Whether to notify the customer about the shipment. + */ no_notification?: boolean + /** + * Custom key-value pairs related to the shipment. + */ metadata?: MetadataType } diff --git a/packages/core/types/src/workflows/products/mutations.ts b/packages/core/types/src/workflows/products/mutations.ts index 0061422bcaf3a..80008899532e1 100644 --- a/packages/core/types/src/workflows/products/mutations.ts +++ b/packages/core/types/src/workflows/products/mutations.ts @@ -1,20 +1,41 @@ import { PricingTypes, ProductTypes } from "../../bundles" +/** + * The details of the variant to create. + */ export type CreateProductVariantWorkflowInputDTO = ProductTypes.CreateProductVariantDTO & { + /** + * The variant's prices. + */ prices?: PricingTypes.CreateMoneyAmountDTO[] } +/** + * The details of the variant to update. + */ export type UpdateProductVariantWorkflowInputDTO = ProductTypes.UpsertProductVariantDTO & { + /** + * The variant's prices. + */ prices?: PricingTypes.CreateMoneyAmountDTO[] } +/** + * The details of the product to create. + */ export type CreateProductWorkflowInputDTO = Omit< ProductTypes.CreateProductDTO, "variants" > & { + /** + * The sales channels that the product is available in. + */ sales_channels?: { id: string }[] + /** + * The product's variants. + */ variants?: CreateProductVariantWorkflowInputDTO[] }