From 8cd58b30922259d085eb4713c0eda95f11186a4e Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 16 Jan 2025 09:44:52 +0200 Subject: [PATCH] chore(core-flows,types): improve TSDocs of cart workflows and steps (#10962) * chore(core-flows,types): improve TSDocs of cart workflows and steps * fix build errors * fix build error * fix errors --- .../cart/steps/add-shipping-method-to-cart.ts | 17 ++ .../src/cart/steps/confirm-inventory.ts | 38 +++- .../core-flows/src/cart/steps/create-carts.ts | 7 +- .../steps/create-line-item-adjustments.ts | 19 +- .../src/cart/steps/create-line-items.ts | 20 ++ .../cart/steps/create-payment-collection.ts | 26 ++- .../create-shipping-method-adjustments.ts | 15 ++ .../src/cart/steps/find-one-or-any-region.ts | 12 +- .../src/cart/steps/find-or-create-customer.ts | 19 ++ .../src/cart/steps/find-sales-channel.ts | 6 + .../get-actions-to-compute-from-promotions.ts | 23 ++ .../src/cart/steps/get-line-item-actions.ts | 35 ++- .../steps/get-promotion-codes-to-apply.ts | 49 +++- .../src/cart/steps/get-variant-price-sets.ts | 44 +++- .../core-flows/src/cart/steps/get-variants.ts | 10 + .../core/core-flows/src/cart/steps/index.ts | 5 + ...pare-adjustments-from-promotion-actions.ts | 78 ++++++- .../steps/remove-line-item-adjustments.ts | 6 + .../remove-shipping-method-adjustments.ts | 6 + .../steps/remove-shipping-method-from-cart.ts | 17 +- .../src/cart/steps/reserve-inventory.ts | 41 ++++ .../src/cart/steps/retrieve-cart.ts | 6 + .../src/cart/steps/set-tax-lines-for-items.ts | 39 ++++ .../src/cart/steps/update-cart-promotions.ts | 12 + .../core-flows/src/cart/steps/update-carts.ts | 13 +- .../src/cart/steps/update-line-items.ts | 24 ++ .../src/cart/steps/update-shipping-methods.ts | 15 +- .../src/cart/steps/validate-cart-payments.ts | 21 +- .../steps/validate-cart-shipping-options.ts | 28 +++ .../src/cart/steps/validate-cart.ts | 22 +- .../cart/steps/validate-line-item-prices.ts | 26 +++ .../steps/validate-shipping-methods-data.ts | 78 +++++++ .../steps/validate-shipping-options-price.ts | 31 ++- .../src/cart/steps/validate-variant-prices.ts | 31 +++ .../workflows/add-shipping-method-to-cart.ts | 45 +++- .../src/cart/workflows/add-to-cart.ts | 29 ++- .../src/cart/workflows/complete-cart.ts | 34 ++- .../workflows/confirm-variant-inventory.ts | 118 +++++++++- .../create-payment-collection-for-cart.ts | 50 ++++- .../core-flows/src/cart/workflows/index.ts | 2 + ...-shipping-options-for-cart-with-pricing.ts | 41 +++- .../list-shipping-options-for-cart.ts | 34 ++- .../src/cart/workflows/refresh-cart-items.ts | 41 +++- .../refresh-cart-shipping-methods.ts | 29 ++- .../workflows/refresh-payment-collection.ts | 28 ++- .../cart/workflows/transfer-cart-customer.ts | 35 ++- .../cart/workflows/update-cart-promotions.ts | 34 ++- .../workflows/update-line-item-in-cart.ts | 21 +- .../src/cart/workflows/update-tax-lines.ts | 46 +++- .../customer/workflows/create-addresses.ts | 3 +- .../customer/workflows/create-customers.ts | 3 +- .../customer/workflows/update-addresses.ts | 3 +- .../src/order/workflows/create-fulfillment.ts | 3 +- .../src/order/workflows/create-order.ts | 6 +- .../src/order/workflows/create-shipment.ts | 3 +- .../promotion/workflows/create-campaigns.ts | 3 +- .../promotion/workflows/create-promotions.ts | 3 +- .../promotion/workflows/update-campaigns.ts | 3 +- .../promotion/workflows/update-promotions.ts | 3 +- packages/core/types/src/cart/workflows.ts | 115 ++++++++++ .../core/types/src/fulfillment/common/cart.ts | 60 +++++ .../core/types/src/fulfillment/provider.ts | 3 + .../core/types/src/fulfillment/workflows.ts | 211 ++++++++++++++++++ 63 files changed, 1785 insertions(+), 63 deletions(-) diff --git a/packages/core/core-flows/src/cart/steps/add-shipping-method-to-cart.ts b/packages/core/core-flows/src/cart/steps/add-shipping-method-to-cart.ts index 77964ee941..2a53c7d6c9 100644 --- a/packages/core/core-flows/src/cart/steps/add-shipping-method-to-cart.ts +++ b/packages/core/core-flows/src/cart/steps/add-shipping-method-to-cart.ts @@ -5,13 +5,30 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the shipping methods to add. + */ export interface AddShippingMethodToCartStepInput { + /** + * The shipping methods to add. + */ shipping_methods: CreateShippingMethodDTO[] } export const addShippingMethodToCartStepId = "add-shipping-method-to-cart-step" /** * This step adds shipping methods to a cart. + * + * @example + * const data = addShippingMethodToCartStep({ + * shipping_methods: [ + * { + * name: "Standard Shipping", + * cart_id: "cart_123", + * amount: 10, + * } + * ] + * }) */ export const addShippingMethodToCartStep = createStep( addShippingMethodToCartStepId, diff --git a/packages/core/core-flows/src/cart/steps/confirm-inventory.ts b/packages/core/core-flows/src/cart/steps/confirm-inventory.ts index 62e1270fd5..6115e4f674 100644 --- a/packages/core/core-flows/src/cart/steps/confirm-inventory.ts +++ b/packages/core/core-flows/src/cart/steps/confirm-inventory.ts @@ -7,19 +7,55 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the cart items to confirm their inventory availability. + */ export interface ConfirmVariantInventoryStepInput { + /** + * The items to confirm inventory for. + */ items: { + /** + * The ID of the inventory item associated with the line item's variant. + */ 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 + /** + * Whether the variant can be ordered even if it's out of stock. If a variant has this enabled, the step doesn't throw an error. + */ allow_backorder: boolean + /** + * The quantity in the cart. + */ quantity: BigNumberInput + /** + * The ID of the stock locations that the inventory quantity is available in. + */ location_ids: string[] }[] } export const confirmInventoryStepId = "confirm-inventory-step" /** - * This step confirms for one or more variants that their inventory has a required quantity. + * This step validates that items in the cart have sufficient inventory quantity. + * If an item doesn't have sufficient inventory, an error is thrown. + * + * @example + * confirmInventoryStep({ + * items: [ + * { + * inventory_item_id: "iitem_123", + * required_quantity: 1, + * allow_backorder: false, + * quantity: 1, + * location_ids: ["sloc_123"] + * } + * ] + * }) */ export const confirmInventoryStep = createStep( confirmInventoryStepId, diff --git a/packages/core/core-flows/src/cart/steps/create-carts.ts b/packages/core/core-flows/src/cart/steps/create-carts.ts index b05b37def1..c66331b010 100644 --- a/packages/core/core-flows/src/cart/steps/create-carts.ts +++ b/packages/core/core-flows/src/cart/steps/create-carts.ts @@ -2,13 +2,18 @@ import { CreateCartDTO, ICartModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the carts to create. + */ +export type CreateCartsStepInput = CreateCartDTO[] + export const createCartsStepId = "create-carts" /** * This step creates a cart. */ export const createCartsStep = createStep( createCartsStepId, - async (data: CreateCartDTO[], { container }) => { + async (data: CreateCartsStepInput, { container }) => { const service = container.resolve(Modules.CART) const createdCarts = await service.createCarts(data) diff --git a/packages/core/core-flows/src/cart/steps/create-line-item-adjustments.ts b/packages/core/core-flows/src/cart/steps/create-line-item-adjustments.ts index bc5646e507..3215a793cd 100644 --- a/packages/core/core-flows/src/cart/steps/create-line-item-adjustments.ts +++ b/packages/core/core-flows/src/cart/steps/create-line-item-adjustments.ts @@ -5,13 +5,30 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the line item adjustments to create. + */ export interface CreateLineItemAdjustmentsCartStepInput { + /** + * The line item adjustments to create. + */ lineItemAdjustmentsToCreate: CreateLineItemAdjustmentDTO[] } export const createLineItemAdjustmentsStepId = "create-line-item-adjustments" /** - * This step creates line item adjustments in a cart. + * This step creates line item adjustments in a cart, such as when a promotion is applied. + * + * @example + * createLineItemAdjustmentsStep({ + * lineItemAdjustmentsToCreate: [ + * { + * item_id: "litem_123", + * code: "10OFF", + * amount: 10, + * } + * ] + * }) */ export const createLineItemAdjustmentsStep = createStep( createLineItemAdjustmentsStepId, diff --git a/packages/core/core-flows/src/cart/steps/create-line-items.ts b/packages/core/core-flows/src/cart/steps/create-line-items.ts index be0d5efc9d..2bf7fce857 100644 --- a/packages/core/core-flows/src/cart/steps/create-line-items.ts +++ b/packages/core/core-flows/src/cart/steps/create-line-items.ts @@ -5,14 +5,34 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the line items to create. + */ export interface CreateLineItemsCartStepInput { + /** + * The ID of the cart to create line items for. + */ id: string + /** + * The line items to create. + */ items: CreateLineItemForCartDTO[] } export const createLineItemsStepId = "create-line-items-step" /** * This step creates line item in a cart. + * + * @example + * const data = createLineItemsStep({ + * "id": "cart_123", + * "items": [{ + * "title": "Shirt", + * "quantity": 1, + * "unit_price": 20, + * "cart_id": "cart_123", + * }] + * }) */ export const createLineItemsStep = createStep( createLineItemsStepId, diff --git a/packages/core/core-flows/src/cart/steps/create-payment-collection.ts b/packages/core/core-flows/src/cart/steps/create-payment-collection.ts index c19972bc29..9d7b2ecd99 100644 --- a/packages/core/core-flows/src/cart/steps/create-payment-collection.ts +++ b/packages/core/core-flows/src/cart/steps/create-payment-collection.ts @@ -5,20 +5,42 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the payment collections to create. + */ export type CreatePaymentCollectionCartStepInput = { + /** + * The ID of the region that the payment collection belongs to. + */ region_id: string + /** + * The payment collection's curency code. + */ currency_code: string + /** + * The payment collection's amount. + */ amount: BigNumberInput + /** + * Custom key-value pairs to store in the payment collection. + */ metadata?: Record -} +}[] export const createPaymentCollectionsStepId = "create-payment-collections" /** * This step creates payment collections in a cart. + * + * @example + * const data = createPaymentCollectionsStep([{ + * "region_id": "region_123", + * "currency_code": "usd", + * "amount": 40 + * }]) */ export const createPaymentCollectionsStep = createStep( createPaymentCollectionsStepId, - async (data: CreatePaymentCollectionCartStepInput[], { container }) => { + async (data: CreatePaymentCollectionCartStepInput, { container }) => { const service = container.resolve(Modules.PAYMENT) const created = await service.createPaymentCollections(data) diff --git a/packages/core/core-flows/src/cart/steps/create-shipping-method-adjustments.ts b/packages/core/core-flows/src/cart/steps/create-shipping-method-adjustments.ts index 1b11f18c00..a62d476e76 100644 --- a/packages/core/core-flows/src/cart/steps/create-shipping-method-adjustments.ts +++ b/packages/core/core-flows/src/cart/steps/create-shipping-method-adjustments.ts @@ -5,7 +5,13 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the shipping method adjustments to create. + */ export interface CreateShippingMethodAdjustmentsStepInput { + /** + * The shipping method adjustments to create. + */ shippingMethodAdjustmentsToCreate: CreateShippingMethodAdjustmentDTO[] } @@ -13,6 +19,15 @@ export const createShippingMethodAdjustmentsStepId = "create-shipping-method-adjustments" /** * This step creates shipping method adjustments for a cart. + * + * @example + * const data = createShippingMethodAdjustmentsStep({ + * "shippingMethodAdjustmentsToCreate": [{ + * "shipping_method_id": "sm_123", + * "code": "10OFF", + * "amount": 10 + * }] + * }) */ export const createShippingMethodAdjustmentsStep = createStep( createShippingMethodAdjustmentsStepId, diff --git a/packages/core/core-flows/src/cart/steps/find-one-or-any-region.ts b/packages/core/core-flows/src/cart/steps/find-one-or-any-region.ts index fd2ee158e5..41321c7b00 100644 --- a/packages/core/core-flows/src/cart/steps/find-one-or-any-region.ts +++ b/packages/core/core-flows/src/cart/steps/find-one-or-any-region.ts @@ -5,13 +5,23 @@ import { import { MedusaError, Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the region to find. + */ +export type FindOneOrAnyRegionStepInput = { + /** + * The ID of the region to find. + */ + regionId?: string +} + export const findOneOrAnyRegionStepId = "find-one-or-any-region" /** * This step retrieves a region either by the provided ID or the first region in the first store. */ export const findOneOrAnyRegionStep = createStep( findOneOrAnyRegionStepId, - async (data: { regionId?: string }, { container }) => { + async (data: FindOneOrAnyRegionStepInput, { container }) => { const service = container.resolve(Modules.REGION) const storeModule = container.resolve(Modules.STORE) diff --git a/packages/core/core-flows/src/cart/steps/find-or-create-customer.ts b/packages/core/core-flows/src/cart/steps/find-or-create-customer.ts index 3a651d9038..ff7462456f 100644 --- a/packages/core/core-flows/src/cart/steps/find-or-create-customer.ts +++ b/packages/core/core-flows/src/cart/steps/find-or-create-customer.ts @@ -2,13 +2,32 @@ import { CustomerDTO, ICustomerModuleService } from "@medusajs/framework/types" import { isDefined, Modules, validateEmail } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of the customer to find or create. + */ export interface FindOrCreateCustomerStepInput { + /** + * The ID of the customer to find. + */ customerId?: string | null + /** + * If the `customerId` isn't specified, + * find a customer with this email or create a new customer having this email. + */ email?: string | null } +/** + * The details of the customer found or created. + */ export interface FindOrCreateCustomerOutputStepOutput { + /** + * The customer found or created, if any. + */ customer?: CustomerDTO | null + /** + * The email of the customer found or created, if any. + */ email?: string | null } diff --git a/packages/core/core-flows/src/cart/steps/find-sales-channel.ts b/packages/core/core-flows/src/cart/steps/find-sales-channel.ts index 37cfde8e01..6f80d2da1f 100644 --- a/packages/core/core-flows/src/cart/steps/find-sales-channel.ts +++ b/packages/core/core-flows/src/cart/steps/find-sales-channel.ts @@ -6,7 +6,13 @@ import { import { MedusaError, Modules, isDefined } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the sales channel to find. + */ export interface FindSalesChannelStepInput { + /** + * The ID of the sales channel to find. + */ salesChannelId?: string | null } diff --git a/packages/core/core-flows/src/cart/steps/get-actions-to-compute-from-promotions.ts b/packages/core/core-flows/src/cart/steps/get-actions-to-compute-from-promotions.ts index 83e7c78c3b..f4f12164b5 100644 --- a/packages/core/core-flows/src/cart/steps/get-actions-to-compute-from-promotions.ts +++ b/packages/core/core-flows/src/cart/steps/get-actions-to-compute-from-promotions.ts @@ -2,8 +2,17 @@ import { CartDTO, IPromotionModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the cart and its applied promotions. + */ export interface GetActionsToComputeFromPromotionsStepInput { + /** + * The cart to compute the actions for. + */ cart: CartDTO + /** + * The promotion codes applied on the cart. + */ promotionCodesToApply: string[] } @@ -12,6 +21,20 @@ export const getActionsToComputeFromPromotionsStepId = /** * This step retrieves the actions to compute based on the promotions * applied on a cart. + * + * :::tip + * + * You can use the {@link retrieveCartStep} to retrieve a cart's details. + * + * ::: + * + * @example + * const data = getActionsToComputeFromPromotionsStep({ + * // retrieve the details of the cart from another workflow + * // or in another step using the Cart Module's service + * cart, + * promotionCodesToApply: ["10OFF"] + * }) */ export const getActionsToComputeFromPromotionsStep = createStep( getActionsToComputeFromPromotionsStepId, diff --git a/packages/core/core-flows/src/cart/steps/get-line-item-actions.ts b/packages/core/core-flows/src/cart/steps/get-line-item-actions.ts index a8587d793c..70afe46369 100644 --- a/packages/core/core-flows/src/cart/steps/get-line-item-actions.ts +++ b/packages/core/core-flows/src/cart/steps/get-line-item-actions.ts @@ -12,15 +12,46 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the line items to create or update. + */ export interface GetLineItemActionsStepInput { + /** + * The ID of the cart to create line items for. + */ id: string + /** + * The line items to create or update. + */ items: CreateLineItemForCartDTO[] } +export interface GetLineItemActionsStepOutput { + /** + * The line items to create. + */ + itemsToCreate: CreateLineItemForCartDTO[] + /** + * The line items to update. + */ + itemsToUpdate: UpdateLineItemWithSelectorDTO[] +} + export const getLineItemActionsStepId = "get-line-item-actions-step" /** * This step returns lists of cart line items to create or update based on the * provided input. + * + * @example + * const data = getLineItemActionsStep({ + * "id": "cart_123", + * "items": [{ + * "title": "Shirt", + * "quantity": 1, + * "unit_price": 50, + * "cart_id": "cart_123", + * }] + * }) */ export const getLineItemActionsStep = createStep( getLineItemActionsStepId, @@ -67,6 +98,8 @@ export const getLineItemActionsStep = createStep( } } - return new StepResponse({ itemsToCreate, itemsToUpdate }, null) + return new StepResponse( + { itemsToCreate, itemsToUpdate } as GetLineItemActionsStepOutput + , null) } ) diff --git a/packages/core/core-flows/src/cart/steps/get-promotion-codes-to-apply.ts b/packages/core/core-flows/src/cart/steps/get-promotion-codes-to-apply.ts index 3ea243d346..ea35110f3f 100644 --- a/packages/core/core-flows/src/cart/steps/get-promotion-codes-to-apply.ts +++ b/packages/core/core-flows/src/cart/steps/get-promotion-codes-to-apply.ts @@ -2,21 +2,66 @@ import { IPromotionModuleService } from "@medusajs/framework/types" import { Modules, PromotionActions } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the promotion codes to apply on a cart. + */ export interface GetPromotionCodesToApplyStepInput { + /** + * The cart containing items and shipping methods. + */ cart: { + /** + * The cart's items and the promotion adjustments applied to them. + */ items?: { adjustments?: { code?: string }[] }[] + /** + * The cart's shipping methods and the promotion adjustments applied to them. + */ shipping_methods?: { adjustments?: { code?: string }[] }[] } + /** + * the promotion codes to be applied to the cart. + */ promo_codes?: string[] + /** + * Whether to add, remove, or replace promotion codes. + */ action?: | PromotionActions.ADD | PromotionActions.REMOVE | PromotionActions.REPLACE } +/** + * The promotion codes to apply on the cart. + * + * @example ["PRO10", "SHIPFREE", "NEWYEAR20"] + */ +export type GetPromotionCodesToApplyStepOutput = string[] + export const getPromotionCodesToApplyId = "get-promotion-codes-to-apply" /** * This step retrieves the promotion codes to apply on a cart. + * + * @example + * const data = getPromotionCodesToApply( + * { + * cart: { + * items: [ + * { + * adjustments: [{ code: "PROMO10" }] + * } + * ], + * shipping_methods: [ + * { + * adjustments: [{ code: "SHIPFREE" }] + * } + * ] + * }, + * promo_codes: ["NEWYEAR20"], + * action: PromotionActions.ADD + * }, + * ) */ export const getPromotionCodesToApply = createStep( getPromotionCodesToApplyId, @@ -60,6 +105,8 @@ export const getPromotionCodesToApply = createStep( promo_codes.forEach((code) => promotionCodesToApply.add(code)) } - return new StepResponse(Array.from(promotionCodesToApply)) + return new StepResponse( + Array.from(promotionCodesToApply) as GetPromotionCodesToApplyStepOutput + ) } ) diff --git a/packages/core/core-flows/src/cart/steps/get-variant-price-sets.ts b/packages/core/core-flows/src/cart/steps/get-variant-price-sets.ts index d6cc8d8e38..74ef6a0c8a 100644 --- a/packages/core/core-flows/src/cart/steps/get-variant-price-sets.ts +++ b/packages/core/core-flows/src/cart/steps/get-variant-price-sets.ts @@ -1,15 +1,53 @@ -import { IPricingModuleService } from "@medusajs/framework/types" +import { CalculatedPriceSet, IPricingModuleService } from "@medusajs/framework/types" import { MedusaError, Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of the variants to get price sets for. + */ export interface GetVariantPriceSetsStepInput { + /** + * The IDs of the variants to get price sets for. + */ variantIds: string[] + /** + * The context to use when calculating the price sets. + * + * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/product/guides/price#retrieve-calculated-price-for-a-context). + */ context?: Record } +/** + * The calculated price sets of the variants. The object's keys are the variant IDs. + */ +export interface GetVariantPriceSetsStepOutput { + [k: string]: CalculatedPriceSet +} + export const getVariantPriceSetsStepId = "get-variant-price-sets" /** * This step retrieves the calculated price sets of the specified variants. + * + * @example + * To retrieve a variant's price sets: + * + * ```ts + * const data = getVariantPriceSetsStep({ + * variantIds: ["variant_123"], + * }) + * ``` + * + * To retrieve the calculated price sets of a variant: + * + * ```ts + * const data = getVariantPriceSetsStep({ + * variantIds: ["variant_123"], + * context: { + * currency_code: "usd" + * } + * }) + * ``` */ export const getVariantPriceSetsStep = createStep( getVariantPriceSetsStepId, @@ -71,6 +109,8 @@ export const getVariantPriceSetsStep = createStep( {} ) - return new StepResponse(variantToCalculatedPriceSets) + return new StepResponse( + variantToCalculatedPriceSets as GetVariantPriceSetsStepOutput + ) } ) diff --git a/packages/core/core-flows/src/cart/steps/get-variants.ts b/packages/core/core-flows/src/cart/steps/get-variants.ts index 75a19131cf..d9d8612c44 100644 --- a/packages/core/core-flows/src/cart/steps/get-variants.ts +++ b/packages/core/core-flows/src/cart/steps/get-variants.ts @@ -7,6 +7,9 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the variants to retrieve. + */ export interface GetVariantsStepInput { filter?: FilterableProductVariantProps config?: FindConfig @@ -15,6 +18,13 @@ export interface GetVariantsStepInput { export const getVariantsStepId = "get-variants" /** * This step retrieves variants matching the specified filters. + * + * @example + * const data = getVariantsStep({ + * filter: { + * id: "variant_123" + * } + * }) */ export const getVariantsStep = createStep( getVariantsStepId, diff --git a/packages/core/core-flows/src/cart/steps/index.ts b/packages/core/core-flows/src/cart/steps/index.ts index de29ab97c2..df002d717d 100644 --- a/packages/core/core-flows/src/cart/steps/index.ts +++ b/packages/core/core-flows/src/cart/steps/index.ts @@ -23,6 +23,11 @@ export * from "./set-tax-lines-for-items" export * from "./update-cart-promotions" export * from "./update-carts" export * from "./update-line-items" +export * from "./update-shipping-methods" export * from "./validate-cart-payments" export * from "./validate-cart-shipping-options" export * from "./validate-variant-prices" +export * from "./validate-cart" +export * from "./validate-line-item-prices" +export * from "./validate-shipping-methods-data" +export * from "./validate-shipping-options-price" \ No newline at end of file diff --git a/packages/core/core-flows/src/cart/steps/prepare-adjustments-from-promotion-actions.ts b/packages/core/core-flows/src/cart/steps/prepare-adjustments-from-promotion-actions.ts index 15fc94484d..72404ff6ab 100644 --- a/packages/core/core-flows/src/cart/steps/prepare-adjustments-from-promotion-actions.ts +++ b/packages/core/core-flows/src/cart/steps/prepare-adjustments-from-promotion-actions.ts @@ -10,15 +10,91 @@ import { import { ComputedActions, Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the actions computed by the Promotion Module. + */ export interface PrepareAdjustmentsFromPromotionActionsStepInput { + /** + * The actions computed by the Promotion Module. + */ actions: ComputeActions[] } +/** + * The details of the adjustments to create and remove. + */ +export interface PrepareAdjustmentsFromPromotionActionsStepOutput { + /** + * The line item adjustments to create. + */ + lineItemAdjustmentsToCreate: { + /** + * The promotion code that computed the adjustment. + */ + code: string + /** + * The amount of the adjustment. + */ + amount: number + /** + * The ID of the line item to adjust. + */ + item_id: string + /** + * The ID of the applied promotion. + */ + promotion_id?: string + }[] + /** + * The line item adjustment IDs to remove. + */ + lineItemAdjustmentIdsToRemove: string[] + /** + * The shipping method adjustments to create. + */ + shippingMethodAdjustmentsToCreate: { + /** + * The promotion code that computed the adjustment. + */ + code: string + /** + * The amount of the adjustment. + */ + amount: number + /** + * The ID of the shipping method to adjust. + */ + shipping_method_id: string + /** + * The ID of the applied promotion. + */ + promotion_id?: string + }[] + /** + * The shipping method adjustment IDs to remove. + */ + shippingMethodAdjustmentIdsToRemove: string[] + /** + * The promotion codes that were computed. + */ + computedPromotionCodes: string[] +} + export const prepareAdjustmentsFromPromotionActionsStepId = "prepare-adjustments-from-promotion-actions" /** * This step prepares the line item or shipping method adjustments using * actions computed by the Promotion Module. + * + * @example + * const data = prepareAdjustmentsFromPromotionActionsStep({ + * "actions": [{ + * "action": "addItemAdjustment", + * "item_id": "litem_123", + * "amount": 10, + * "code": "10OFF", + * }] + * }) */ export const prepareAdjustmentsFromPromotionActionsStep = createStep( prepareAdjustmentsFromPromotionActionsStepId, @@ -82,6 +158,6 @@ export const prepareAdjustmentsFromPromotionActionsStep = createStep( shippingMethodAdjustmentsToCreate, shippingMethodAdjustmentIdsToRemove, computedPromotionCodes, - }) + } as PrepareAdjustmentsFromPromotionActionsStepOutput) } ) diff --git a/packages/core/core-flows/src/cart/steps/remove-line-item-adjustments.ts b/packages/core/core-flows/src/cart/steps/remove-line-item-adjustments.ts index 6a21c9f030..cbab15bf71 100644 --- a/packages/core/core-flows/src/cart/steps/remove-line-item-adjustments.ts +++ b/packages/core/core-flows/src/cart/steps/remove-line-item-adjustments.ts @@ -2,7 +2,13 @@ import { ICartModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the line item adjustments to remove. + */ export interface RemoveLineItemAdjustmentsStepInput { + /** + * The IDs of the line item adjustments to remove. + */ lineItemAdjustmentIdsToRemove: string[] } diff --git a/packages/core/core-flows/src/cart/steps/remove-shipping-method-adjustments.ts b/packages/core/core-flows/src/cart/steps/remove-shipping-method-adjustments.ts index 0ffc9f243b..6d7cd3a74f 100644 --- a/packages/core/core-flows/src/cart/steps/remove-shipping-method-adjustments.ts +++ b/packages/core/core-flows/src/cart/steps/remove-shipping-method-adjustments.ts @@ -2,7 +2,13 @@ import { ICartModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the shipping method adjustments to remove. + */ export interface RemoveShippingMethodAdjustmentsStepInput { + /** + * The IDs of the shipping method adjustments to remove. + */ shippingMethodAdjustmentIdsToRemove: string[] } diff --git a/packages/core/core-flows/src/cart/steps/remove-shipping-method-from-cart.ts b/packages/core/core-flows/src/cart/steps/remove-shipping-method-from-cart.ts index 3706c8b02c..96180e01ff 100644 --- a/packages/core/core-flows/src/cart/steps/remove-shipping-method-from-cart.ts +++ b/packages/core/core-flows/src/cart/steps/remove-shipping-method-from-cart.ts @@ -2,10 +2,22 @@ import { ICartModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the shipping methods to remove. + */ export interface RemoveShippingMethodFromCartStepInput { + /** + * The IDs of the shipping methods to remove. + */ shipping_method_ids: string[] } +/** + * The shipping methods removed from the cart, along with IDs of related records + * that were removed. + */ +export type RemoveShippingMethodFromCartStepOutput = Record | void + export const removeShippingMethodFromCartStepId = "remove-shipping-method-to-cart-step" /** @@ -24,7 +36,10 @@ export const removeShippingMethodFromCartStep = createStep( data.shipping_method_ids ) - return new StepResponse(methods, data.shipping_method_ids) + return new StepResponse( + methods as RemoveShippingMethodFromCartStepOutput, + data.shipping_method_ids + ) }, async (ids, { container }) => { if (!ids?.length) { diff --git a/packages/core/core-flows/src/cart/steps/reserve-inventory.ts b/packages/core/core-flows/src/cart/steps/reserve-inventory.ts index b749933467..1e5c91b2be 100644 --- a/packages/core/core-flows/src/cart/steps/reserve-inventory.ts +++ b/packages/core/core-flows/src/cart/steps/reserve-inventory.ts @@ -2,13 +2,41 @@ import { MathBN, Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" import { BigNumberInput } from "@medusajs/types" + +/** + * The details of the items and their quantity to reserve. + */ export interface ReserveVariantInventoryStepInput { items: { + /** + * The ID for the line item. + */ id?: string + + /** + * The ID of the inventory item to reserve quantities from. + */ 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 + + /** + * Whether the variant can be ordered even if it's out of stock. + */ allow_backorder: boolean + + /** + * The quantity to reserve. + */ quantity: BigNumberInput + + /** + * The IDs of stock locations to reserve the item's quantity in. + */ location_ids: string[] }[] } @@ -17,6 +45,19 @@ export const reserveInventoryStepId = "reserve-inventory-step" /** * This step reserves the quantity of line items from the associated * variant's inventory. + * + * @example + * const data = reserveInventoryStep({ + * "items": [{ + * "inventory_item_id": "iitem_123", + * "required_quantity": 1, + * "allow_backorder": false, + * "quantity": 1, + * "location_ids": [ + * "sloc_123" + * ] + * }] + * }) */ export const reserveInventoryStep = createStep( reserveInventoryStepId, diff --git a/packages/core/core-flows/src/cart/steps/retrieve-cart.ts b/packages/core/core-flows/src/cart/steps/retrieve-cart.ts index 8cbe5b4f7b..4f50a17fa9 100644 --- a/packages/core/core-flows/src/cart/steps/retrieve-cart.ts +++ b/packages/core/core-flows/src/cart/steps/retrieve-cart.ts @@ -6,7 +6,13 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the cart to retrieve. + */ export interface RetrieveCartStepInput { + /** + * The ID of the cart to retrieve. + */ id: string config?: FindConfig } diff --git a/packages/core/core-flows/src/cart/steps/set-tax-lines-for-items.ts b/packages/core/core-flows/src/cart/steps/set-tax-lines-for-items.ts index b7c7c237a7..635490726a 100644 --- a/packages/core/core-flows/src/cart/steps/set-tax-lines-for-items.ts +++ b/packages/core/core-flows/src/cart/steps/set-tax-lines-for-items.ts @@ -9,15 +9,54 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the tax lines to set in a cart. + */ export interface SetTaxLinesForItemsStepInput { + /** + * The cart's details. + */ cart: CartWorkflowDTO + /** + * The tax lines to set for line items. + */ item_tax_lines: ItemTaxLineDTO[] + /** + * The tax lines to set for shipping methods. + */ shipping_tax_lines: ShippingTaxLineDTO[] } export const setTaxLinesForItemsStepId = "set-tax-lines-for-items" /** * This step sets the tax lines of shipping methods and line items in a cart. + * + * :::tip + * + * You can use the {@link retrieveCartStep} to retrieve a cart's details. + * + * ::: + * + * @example + * const data = setTaxLinesForItemsStep({ + * // retrieve the details of the cart from another workflow + * // or in another step using the Cart Module's service + * cart, + * "item_tax_lines": [{ + * "rate": 48, + * "code": "CODE123", + * "name": "Tax rate 2", + * "provider_id": "provider_1", + * "line_item_id": "litem_123" + * }], + * "shipping_tax_lines": [{ + * "rate": 49, + * "code": "CODE456", + * "name": "Tax rate 1", + * "provider_id": "provider_1", + * "shipping_line_id": "sm_123" + * }] + * }) */ export const setTaxLinesForItemsStep = createStep( setTaxLinesForItemsStepId, diff --git a/packages/core/core-flows/src/cart/steps/update-cart-promotions.ts b/packages/core/core-flows/src/cart/steps/update-cart-promotions.ts index 514cfaa43d..205c4a7201 100644 --- a/packages/core/core-flows/src/cart/steps/update-cart-promotions.ts +++ b/packages/core/core-flows/src/cart/steps/update-cart-promotions.ts @@ -6,9 +6,21 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the promotion codes to apply on a cart. + */ export interface UpdateCartPromotionStepInput { + /** + * The ID of the cart to update promotions for. + */ id: string + /** + * The promotion codes to apply on the cart. + */ promo_codes?: string[] + /** + * Whether to add, remove, or replace promotion codes. + */ action?: | PromotionActions.ADD | PromotionActions.REMOVE diff --git a/packages/core/core-flows/src/cart/steps/update-carts.ts b/packages/core/core-flows/src/cart/steps/update-carts.ts index 697ebed3e0..aa2619e0da 100644 --- a/packages/core/core-flows/src/cart/steps/update-carts.ts +++ b/packages/core/core-flows/src/cart/steps/update-carts.ts @@ -9,13 +9,24 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the carts to update. + */ +export type UpdateCartsStepInput = UpdateCartWorkflowInputDTO[] + export const updateCartsStepId = "update-carts" /** * This step updates a cart. + * + * @example + * const data = updateCartsStep([{ + * id: "cart_123", + * email: "customer@gmail.com", + * }]) */ export const updateCartsStep = createStep( updateCartsStepId, - async (data: UpdateCartWorkflowInputDTO[], { container }) => { + async (data: UpdateCartsStepInput, { container }) => { const cartModule = container.resolve(Modules.CART) const { selects, relations } = getSelectsAndRelationsFromObjectArray(data) diff --git a/packages/core/core-flows/src/cart/steps/update-line-items.ts b/packages/core/core-flows/src/cart/steps/update-line-items.ts index dcecc4e9a9..edc741b88f 100644 --- a/packages/core/core-flows/src/cart/steps/update-line-items.ts +++ b/packages/core/core-flows/src/cart/steps/update-line-items.ts @@ -8,14 +8,38 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the line items to update. + */ export interface UpdateLineItemsStepInput { + /** + * The ID of the cart that the line items belong to. + */ id: string + /** + * The line items to update. + */ items: UpdateLineItemWithSelectorDTO[] } export const updateLineItemsStepId = "update-line-items-step" /** * This step updates a cart's line items. + * + * @example + * const data = updateLineItemsStep({ + * id: "cart_123", + * items: [ + * { + * selector: { + * id: "line_item_123" + * }, + * data: { + * quantity: 2 + * } + * } + * ] + * }) */ export const updateLineItemsStep = createStep( updateLineItemsStepId, diff --git a/packages/core/core-flows/src/cart/steps/update-shipping-methods.ts b/packages/core/core-flows/src/cart/steps/update-shipping-methods.ts index b53b2f981a..f5b6245b06 100644 --- a/packages/core/core-flows/src/cart/steps/update-shipping-methods.ts +++ b/packages/core/core-flows/src/cart/steps/update-shipping-methods.ts @@ -8,13 +8,26 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the shipping methods to update. + */ +export type UpdateShippingMethodsStepInput = UpdateShippingMethodDTO[] + export const updateShippingMethodsStepId = "update-shipping-methods-step" /** * This step updates a cart's shipping methods. + * + * @example + * const data = updateOrderShippingMethodsStep([ + * { + * id: "sm_123", + * amount: 10 + * } + * ]) */ export const updateShippingMethodsStep = createStep( updateShippingMethodsStepId, - async (data: UpdateShippingMethodDTO[], { container }) => { + async (data: UpdateShippingMethodsStepInput, { container }) => { if (!data?.length) { return new StepResponse([], []) } diff --git a/packages/core/core-flows/src/cart/steps/validate-cart-payments.ts b/packages/core/core-flows/src/cart/steps/validate-cart-payments.ts index 1e3317e4fb..10687628c5 100644 --- a/packages/core/core-flows/src/cart/steps/validate-cart-payments.ts +++ b/packages/core/core-flows/src/cart/steps/validate-cart-payments.ts @@ -6,14 +6,33 @@ import { } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The cart's details. + */ export interface ValidateCartPaymentsStepInput { + /** + * The cart to validate payment sessions for. + */ cart: CartWorkflowDTO } export const validateCartPaymentsStepId = "validate-cart-payments" /** * This step validates a cart's payment sessions. Their status must - * be `pending` or `requires_more`. + * be `pending` or `requires_more`. If not valid, the step throws an error. + * + * :::tip + * + * You can use the {@link retrieveCartStep} to retrieve a cart's details. + * + * ::: + * + * @example + * const data = validateCartPaymentsStep({ + * // retrieve the details of the cart from another workflow + * // or in another step using the Cart Module's service + * cart + * }) */ export const validateCartPaymentsStep = createStep( validateCartPaymentsStepId, diff --git a/packages/core/core-flows/src/cart/steps/validate-cart-shipping-options.ts b/packages/core/core-flows/src/cart/steps/validate-cart-shipping-options.ts index 2fa65c3a66..e39e845eaa 100644 --- a/packages/core/core-flows/src/cart/steps/validate-cart-shipping-options.ts +++ b/packages/core/core-flows/src/cart/steps/validate-cart-shipping-options.ts @@ -6,12 +6,30 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the cart and its shipping options context. + */ export interface ValidateCartShippingOptionsStepInput { + /** + * The cart to validate shipping options for. + */ cart: CartDTO + /** + * The context to validate the shipping options. + */ shippingOptionsContext: { + /** + * Validate whether the shipping options are enabled in the store. + */ enabled_in_store?: "true" | "false" + /** + * Validate whether the shipping options are used for returns. + */ is_return?: "true" | "false" } + /** + * The IDs of the shipping options to validate. + */ option_ids: string[] } @@ -19,6 +37,16 @@ export const validateCartShippingOptionsStepId = "validate-cart-shipping-options" /** * This step validates shipping options to ensure they can be applied on a cart. + * If not valid, the step throws an error. + * + * @example + * const data = validateCartShippingOptionsStep({ + * // retrieve the details of the cart from another workflow + * // or in another step using the Cart Module's service + * cart, + * option_ids: ["so_123"], + * shippingOptionsContext: {} + * }) */ export const validateCartShippingOptionsStep = createStep( validateCartShippingOptionsStepId, diff --git a/packages/core/core-flows/src/cart/steps/validate-cart.ts b/packages/core/core-flows/src/cart/steps/validate-cart.ts index 3487d6dab7..3055fb8b12 100644 --- a/packages/core/core-flows/src/cart/steps/validate-cart.ts +++ b/packages/core/core-flows/src/cart/steps/validate-cart.ts @@ -2,13 +2,33 @@ import { CartDTO, CartWorkflowDTO } from "@medusajs/framework/types" import { MedusaError } from "@medusajs/framework/utils" import { createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the cart to validate. + */ export interface ValidateCartStepInput { + /** + * The cart to validate. + */ cart: CartWorkflowDTO | CartDTO } export const validateCartStepId = "validate-cart" /** - * This step validates a cart's before editing it. + * This step validates a cart to ensure it exists and is not completed. + * If not valid, the step throws an error. + * + * :::tip + * + * You can use the {@link retrieveCartStep} to retrieve a cart's details. + * + * ::: + * + * @example + * const data = validateCartStep({ + * // retrieve the details of the cart from another workflow + * // or in another step using the Cart Module's service + * cart, + * }) */ export const validateCartStep = createStep( validateCartStepId, diff --git a/packages/core/core-flows/src/cart/steps/validate-line-item-prices.ts b/packages/core/core-flows/src/cart/steps/validate-line-item-prices.ts index 9241e1d1cf..5741d58c10 100644 --- a/packages/core/core-flows/src/cart/steps/validate-line-item-prices.ts +++ b/packages/core/core-flows/src/cart/steps/validate-line-item-prices.ts @@ -1,9 +1,21 @@ import { MedusaError, isPresent } from "@medusajs/framework/utils" import { createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the line items to validate. + */ export interface ValidateLineItemPricesStepInput { + /** + * The line items to validate. + */ items: { + /** + * The price of the line item. + */ unit_price?: number | null + /** + * The title of the line item. + */ title: string }[] } @@ -11,6 +23,20 @@ export interface ValidateLineItemPricesStepInput { export const validateLineItemPricesStepId = "validate-line-item-prices" /** * This step validates the specified line item objects to ensure they have prices. + * If an item doesn't have a price, the step throws an error. + * + * @example + * const data = validateLineItemPricesStep({ + * items: [ + * { + * unit_price: 10, + * title: "Shirt" + * }, + * { + * title: "Pants" + * } + * ] + * }) */ export const validateLineItemPricesStep = createStep( validateLineItemPricesStepId, diff --git a/packages/core/core-flows/src/cart/steps/validate-shipping-methods-data.ts b/packages/core/core-flows/src/cart/steps/validate-shipping-methods-data.ts index a0040ad0da..e5d40416b5 100644 --- a/packages/core/core-flows/src/cart/steps/validate-shipping-methods-data.ts +++ b/packages/core/core-flows/src/cart/steps/validate-shipping-methods-data.ts @@ -5,18 +5,96 @@ import { } from "@medusajs/types" import { createStep, StepResponse } from "@medusajs/workflows-sdk" +/** + * The details of the shipping methods to validate. + */ export type ValidateShippingMethodsDataInput = { + /** + * The shipping method's ID. + */ id: string + /** + * The fulfillment provider ID that associated with the shipping option + * that the method was created from. + */ provider_id: string + /** + * The `data` property of the shipping option that the shipping method was + * created from. + */ option_data: Record + /** + * The `data` property of the shipping method. + */ method_data: Record + /** + * The context to validate the shipping method. + */ context: ValidateFulfillmentDataContext }[] +/** + * The validated data of the shipping methods. + */ +export type ValidateShippingMethodsDataOutput = void | { + [x: string]: Record; +}[] + export const validateAndReturnShippingMethodsDataStepId = "validate-and-return-shipping-methods-data" /** * This step validates shipping options to ensure they can be applied on a cart. + * The step either returns the validated data or void. + * + * @example + * const data = validateAndReturnShippingMethodsDataStep({ + * id: "sm_123", + * provider_id: "my_provider", + * option_data: {}, + * method_data: {}, + * context: { + * id: "cart_123", + * shipping_address: { + * id: "saddr_123", + * first_name: "Jane", + * last_name: "Smith", + * address_1: "456 Elm St", + * city: "Shelbyville", + * country_code: "us", + * postal_code: "67890", + * }, + * items: [ + * { + * variant: { + * id: "variant_123", + * weight: 1, + * length: 1, + * height: 1, + * width: 1, + * material: "wood", + * product: { + * id: "prod_123" + * } + * } + * } + * ], + * product: { + * id: "prod_123", + * collection_id: "pcol_123", + * categories: [], + * tags: [] + * }, + * from_location: { + * id: "sloc_123", + * first_name: "John", + * last_name: "Doe", + * address_1: "123 Main St", + * city: "Springfield", + * country_code: "us", + * postal_code: "12345", + * }, + * } + * }) */ export const validateAndReturnShippingMethodsDataStep = createStep( validateAndReturnShippingMethodsDataStepId, diff --git a/packages/core/core-flows/src/cart/steps/validate-shipping-options-price.ts b/packages/core/core-flows/src/cart/steps/validate-shipping-options-price.ts index 51784e93cd..6a0774beee 100644 --- a/packages/core/core-flows/src/cart/steps/validate-shipping-options-price.ts +++ b/packages/core/core-flows/src/cart/steps/validate-shipping-options-price.ts @@ -1,14 +1,41 @@ import { isDefined, MedusaError } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" -export const validateCartShippingOptionsStepId = +/** + * The details of the shipping options to validate. + */ +export type ValidateCartShippingOptionsPriceInput = { + /** + * The shipping option's details. Should have a `calculated_price.calculated_amount` + * to be considered valid. + */ + shippingOptions: any[] +} + +export const validateCartShippingOptionsPriceStepId = "validate-cart-shipping-options" /** * This step validates shipping options to ensure they have a price. + * If not valid, the step throws an error. + * + * @example + * const data = validateCartShippingOptionsPriceStep({ + * shippingOptions: [ + * { + * id: "so_123", + * }, + * { + * id: "so_321", + * calculated_price: { + * calculated_amount: 10, + * } + * } + * ] + * }) */ export const validateCartShippingOptionsPriceStep = createStep( "validate-cart-shipping-options-price", - async (data: { shippingOptions: any[] }, { container }) => { + async (data: ValidateCartShippingOptionsPriceInput, { container }) => { const { shippingOptions = [] } = data const optionsMissingPrices: string[] = [] diff --git a/packages/core/core-flows/src/cart/steps/validate-variant-prices.ts b/packages/core/core-flows/src/cart/steps/validate-variant-prices.ts index fe34300bf5..8c4a6da31e 100644 --- a/packages/core/core-flows/src/cart/steps/validate-variant-prices.ts +++ b/packages/core/core-flows/src/cart/steps/validate-variant-prices.ts @@ -2,10 +2,25 @@ import { BigNumberInput } from "@medusajs/framework/types" import { MedusaError, isPresent } from "@medusajs/framework/utils" import { createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the variants to validate. + */ export interface ValidateVariantPricesStepInput { + /** + * The variants to validate. + */ variants: { + /** + * The ID of the variant. + */ id: string + /** + * The calculated price of the variant. + */ calculated_price?: { + /** + * The calculated amount of the price. + */ calculated_amount?: BigNumberInput | null } }[] @@ -14,6 +29,22 @@ export interface ValidateVariantPricesStepInput { export const validateVariantPricesStepId = "validate-variant-prices" /** * This step validates the specified variant objects to ensure they have prices. + * If not valid, the step throws an error. + * + * @example + * const data = validateVariantPricesStep({ + * variants: [ + * { + * id: "variant_123", + * }, + * { + * id: "variant_321", + * calculated_price: { + * calculated_amount: 10, + * } + * } + * ] + * }) */ export const validateVariantPricesStep = createStep( validateVariantPricesStepId, diff --git a/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts b/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts index 275afd398a..84374ddfda 100644 --- a/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts @@ -21,17 +21,60 @@ import { cartFieldsForRefreshSteps } from "../utils/fields" import { listShippingOptionsForCartWithPricingWorkflow } from "./list-shipping-options-for-cart-with-pricing" import { refreshCartItemsWorkflow } from "./refresh-cart-items" +/** + * The data to add a shipping method to a cart. + */ export interface AddShippingMethodToCartWorkflowInput { + /** + * The ID of the cart to add the shipping method to. + */ cart_id: string + /** + * The shipping options to create the shipping methods from and add to the cart. + */ options: { + /** + * The ID of the shipping option. + */ id: string + /** + * Custom data useful for the fulfillment provider processing the shipping option or method. + * + * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property). + */ data?: Record }[] } export const addShippingMethodToCartWorkflowId = "add-shipping-method-to-cart" /** - * This workflow adds shipping methods to a cart. + * This workflow adds a shipping method to a cart. It's executed by the + * [Add Shipping Method Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidshippingmethods). + * + * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding a shipping method to the cart. + * + * @example + * const { result } = await addShippingMethodToCartWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * options: [ + * { + * id: "so_123", + * }, + * { + * id: "so_124", + * data: { + * carrier_code: "fedex", + * } + * } + * ] + * } + * }) + * + * @summary + * + * Add a shipping method to a cart. */ export const addShippingMethodToCartWorkflow = createWorkflow( addShippingMethodToCartWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/add-to-cart.ts b/packages/core/core-flows/src/cart/workflows/add-to-cart.ts index 303f0ba8b4..644a9e9f5e 100644 --- a/packages/core/core-flows/src/cart/workflows/add-to-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/add-to-cart.ts @@ -35,7 +35,34 @@ const cartFields = ["completed_at"].concat(cartFieldsForPricingContext) export const addToCartWorkflowId = "add-to-cart" /** - * This workflow adds items to a cart. + * This workflow adds a product variant to a cart as a line item. It's executed by the + * [Add Line Item Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidlineitems). + * + * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding an item to the cart. + * For example, you can use this workflow to add a line item to the cart with a custom price. + * + * @example + * const { result } = await addToCartWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1, + * }, + * { + * variant_id: "variant_456", + * quantity: 1, + * unit_price: 20 + * } + * ] + * } + * }) + * + * @summary + * + * Add a line item to a cart. */ export const addToCartWorkflow = createWorkflow( addToCartWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/complete-cart.ts b/packages/core/core-flows/src/cart/workflows/complete-cart.ts index e5469360da..c7315190dc 100644 --- a/packages/core/core-flows/src/cart/workflows/complete-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/complete-cart.ts @@ -36,7 +36,20 @@ import { prepareTaxLinesData, } from "../utils/prepare-line-item-data" +/** + * The data to complete a cart and place an order. + */ export type CompleteCartWorkflowInput = { + /** + * The ID of the cart to complete. + */ + id: string +} + +export type CompleteCartWorkflowOutput = { + /** + * The ID of the order that was created. + */ id: string } @@ -44,7 +57,24 @@ export const THREE_DAYS = 60 * 60 * 24 * 3 export const completeCartWorkflowId = "complete-cart" /** - * This workflow completes a cart. + * This workflow completes a cart and places an order for the customer. It's executed by the + * [Complete Cart Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidcomplete). + * + * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around completing a cart. + * For example, in the [Subscriptions recipe](https://docs.medusajs.com/resources/recipes/subscriptions/examples/standard#create-workflow), + * this workflow is used within another workflow that creates a subscription order. + * + * @example + * const { result } = await completeCartWorkflow(container) + * .run({ + * input: { + * id: "cart_123" + * } + * }) + * + * @summary + * + * Complete a cart and place an order. */ export const completeCartWorkflow = createWorkflow( { @@ -268,7 +298,7 @@ export const completeCartWorkflow = createWorkflow( }) const result = transform({ order, orderId }, ({ order, orderId }) => { - return { id: order?.id ?? orderId } + return { id: order?.id ?? orderId } as CompleteCartWorkflowOutput }) return new WorkflowResponse(result, { diff --git a/packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts b/packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts index 3deda838ec..55b5fb0c13 100644 --- a/packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts +++ b/packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts @@ -9,20 +9,136 @@ import { BigNumberInput } from "@medusajs/types" import { confirmInventoryStep } from "../steps" import { prepareConfirmInventoryInput } from "../utils/prepare-confirm-inventory-input" +/** + * The details of the cart items with inventory result computed for the specified input. + */ export interface ConfirmVariantInventoryWorkflowOutput { + /** + * The cart's line items with the computed inventory result. + */ items: { + /** + * The line item's ID. + */ id?: string + /** + * The ID of the inventory item used to retrieve the item's available quantity. + */ 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 + /** + * Whether the variant can be ordered even if it's out of stock. If a variant has this enabled, the workflow doesn't throw an error. + */ allow_backorder: boolean + /** + * The quantity in the cart. If you provided `itemsToUpdate` in the input, this will be the updated quantity. + */ quantity: BigNumberInput + /** + * The ID of the stock locations that the computed inventory quantity is available in. + */ location_ids: string[] }[] } export const confirmVariantInventoryWorkflowId = "confirm-item-inventory" /** - * This workflow confirms for one or more variants that their inventory has a required quantity. + * This workflow validates that product variants are in-stock at the specified sales channel, before adding them or updating their quantity in the cart. If a variant doesn't have sufficient quantity in-stock, + * the workflow throws an error. If all variants have sufficient inventory, the workflow returns the cart's items with their inventory details. + * + * This workflow is useful when confirming that a product variant has sufficient quantity to be added to or updated in the cart. It's executed + * by other cart-related workflows, such as {@link addToCartWorkflow}, to confirm that a product variant can be added to the cart at the specified quantity. + * + * :::note + * + * Learn more about the links between the product variant and sales channels and inventory items in [this documentation](https://docs.medusajs.com/resources/commerce-modules/product/links-to-other-modules). + * + * ::: + * + * You can use this workflow within your own custom workflows, allowing you to check whether a product variant has enough inventory quantity before adding them to the cart. + * + * @example + * You can retrieve a variant's required details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query): + * + * ```ts workflow={false} + * const { data: variants } = await query.graph({ + * entity: "variant", + * fields: [ + * "id", + * "manage_inventory", + * "inventory_items.inventory_item_id", + * "inventory_items.required_quantity", + * "inventory_items.inventory.requires_shipping", + * "inventory_items.inventory.location_levels.stock_locations.id", + * "inventory_items.inventory.location_levels.stock_locations.name", + * "inventory_items.inventory.location_levels.stock_locations.sales_channels.id", + * "inventory_items.inventory.location_levels.stock_locations.sales_channels.name", + * ], + * filters: { + * id: ["variant_123"] + * } + * }) + * ``` + * + * :::note + * + * In a workflow, use [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep) instead. + * + * ::: + * + * Then, pass the variant's data with the other required data to the workflow: + * + * ```ts + * const { result } = await confirmVariantInventoryWorkflow(container) + * .run({ + * input: { + * sales_channel_id: "sc_123", + * // @ts-ignore + * variants, + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1 + * } + * ] + * } + * }) + * ``` + * + * When updating an item quantity: + * + * ```ts + * const { result } = await confirmVariantInventoryWorkflow(container) + * .run({ + * input: { + * sales_channel_id: "sc_123", + * // @ts-ignore + * variants, + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1 + * } + * ], + * itemsToUpdate: [ + * { + * data: { + * variant_id: "variant_123", + * quantity: 2 + * } + * } + * ] + * } + * }) + * ``` + * + * @summary + * + * Validate that a variant is in-stock before adding to the cart. */ export const confirmVariantInventoryWorkflow = createWorkflow( confirmVariantInventoryWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts b/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts index 31788bd265..4d2962152e 100644 --- a/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts @@ -15,12 +15,40 @@ import { useRemoteQueryStep } from "../../common/steps/use-remote-query" import { createPaymentCollectionsStep } from "../steps/create-payment-collection" import { validateCartStep } from "../steps/validate-cart" +/** + * The details of the cart to validate its payment collection. + */ +export type ValidateExistingPaymentCollectionStepInput = { + /** + * The cart to validate. + */ + cart: CartDTO & { payment_collection?: any } +} + /** * This step validates that a cart doesn't have a payment collection. + * If the cart has a payment collection, the step throws an error. + * + * :::tip + * + * You can use the {@link retrieveCartStep} to retrieve a cart's details. + * + * ::: + * + * @example + * const data = validateExistingPaymentCollectionStep({ + * cart: { + * // other cart details... + * payment_collection: { + * id: "paycol_123", + * // other payment collection details. + * } + * } + * }) */ export const validateExistingPaymentCollectionStep = createStep( "validate-existing-payment-collection", - ({ cart }: { cart: CartDTO & { payment_collection?: any } }) => { + ({ cart }: ValidateExistingPaymentCollectionStepInput) => { if (cart.payment_collection) { throw new Error(`Cart ${cart.id} already has a payment collection`) } @@ -30,7 +58,25 @@ export const validateExistingPaymentCollectionStep = createStep( export const createPaymentCollectionForCartWorkflowId = "create-payment-collection-for-cart" /** - * This workflow creates a payment collection for a cart. + * This workflow creates a payment collection for a cart. It's executed by the + * [Create Payment Collection Store API Route](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollections). + * + * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around adding creating a payment collection for a cart. + * + * @example + * const { result } = await createPaymentCollectionForCartWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * metadata: { + * sandbox: true + * } + * } + * }) + * + * @summary + * + * Create payment collection for cart. */ export const createPaymentCollectionForCartWorkflow = createWorkflow( createPaymentCollectionForCartWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/index.ts b/packages/core/core-flows/src/cart/workflows/index.ts index 28d5729075..51b57a6a6a 100644 --- a/packages/core/core-flows/src/cart/workflows/index.ts +++ b/packages/core/core-flows/src/cart/workflows/index.ts @@ -7,6 +7,8 @@ export * from "./create-payment-collection-for-cart" export * from "./list-shipping-options-for-cart" export * from "./list-shipping-options-for-cart-with-pricing" export * from "./refresh-payment-collection" +export * from "./refresh-cart-items" +export * from "./refresh-cart-shipping-methods" export * from "./transfer-cart-customer" export * from "./update-cart" export * from "./update-cart-promotions" diff --git a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts index a0f05eea0f..6fe22bb779 100644 --- a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts +++ b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts @@ -6,7 +6,10 @@ import { WorkflowData, WorkflowResponse, } from "@medusajs/framework/workflows-sdk" -import { CalculateShippingOptionPriceDTO } from "@medusajs/types" +import { + CalculateShippingOptionPriceDTO, + ListShippingOptionsForCartWithPricingWorkflowInput, +} from "@medusajs/types" import { useQueryGraphStep, validatePresenceOfStep } from "../../common" import { useRemoteQueryStep } from "../../common/steps/use-remote-query" @@ -39,17 +42,39 @@ const COMMON_OPTIONS_FIELDS = [ export const listShippingOptionsForCartWithPricingWorkflowId = "list-shipping-options-for-cart-with-pricing" /** - * This workflow lists the shipping options of a cart. + * This workflow lists shipping options that can be used during checkout for a cart. It also retrieves the prices + * of these shipping options, including calculated prices that may be retrieved from third-party providers. + * + * This workflow is executed in other cart-related workflows, such as {@link addShippingMethodToCartWorkflow} to retrieve the + * price of the shipping method being added to the cart. + * + * You can use this workflow within your own custom workflows, allowing you to retrieve the shipping options of a cart and their prices + * in your custom flows. + * + * @example + * const { result } = await listShippingOptionsForCartWithPricingWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * options: [ + * { + * id: "so_123", + * data: { + * carrier_code: "fedex" + * } + * } + * ] + * } + * }) + * + * @summary + * + * List a cart's shipping options with prices. */ export const listShippingOptionsForCartWithPricingWorkflow = createWorkflow( listShippingOptionsForCartWithPricingWorkflowId, ( - input: WorkflowData<{ - cart_id: string - options?: { id: string; data?: Record }[] - is_return?: boolean - enabled_in_store?: boolean - }> + input: WorkflowData ) => { const optionIds = transform({ input }, ({ input }) => (input.options ?? []).map(({ id }) => id) diff --git a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts index dbcb3084b4..1d80b1123a 100644 --- a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts @@ -7,21 +7,41 @@ import { import { useQueryGraphStep, validatePresenceOfStep } from "../../common" import { useRemoteQueryStep } from "../../common/steps/use-remote-query" import { cartFieldsForPricingContext } from "../utils/fields" +import { ListShippingOptionsForCartWorkflowInput } from "@medusajs/types" export const listShippingOptionsForCartWorkflowId = "list-shipping-options-for-cart" /** - * This workflow lists the shipping options of a cart. + * This workflow lists the shipping options of a cart. It's executed by the + * [List Shipping Options Store API Route](https://docs.medusajs.com/api/store#shipping-options_getshippingoptions). + * + * :::note + * + * This workflow doesn't retrieve the calculated prices of the shipping options. If you need to retrieve the prices of the shipping options, + * use the {@link listShippingOptionsForCartWithPricingWorkflow} workflow. + * + * ::: + * + * You can use this workflow within your own custom workflows, allowing you to wrap custom logic around to retrieve the shipping options of a cart + * in your custom flows. + * + * @example + * const { result } = await listShippingOptionsForCartWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * option_ids: ["so_123"] + * } + * }) + * + * @summary + * + * List a cart's shipping options. */ export const listShippingOptionsForCartWorkflow = createWorkflow( listShippingOptionsForCartWorkflowId, ( - input: WorkflowData<{ - cart_id: string - option_ids?: string[] - is_return?: boolean - enabled_in_store?: boolean - }> + input: WorkflowData ) => { const cartQuery = useQueryGraphStep({ entity: "cart", diff --git a/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts b/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts index 6a6096bf0c..30b09a154d 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts +++ b/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts @@ -28,17 +28,48 @@ import { refreshPaymentCollectionForCartWorkflow } from "./refresh-payment-colle import { updateCartPromotionsWorkflow } from "./update-cart-promotions" import { updateTaxLinesWorkflow } from "./update-tax-lines" +/** + * The details of the cart to refresh. + */ +export type RefreshCartItemsWorkflowInput = { + /** + * The cart's ID. + */ + cart_id: string + /** + * The promotion codes applied on the cart. + * These promotion codes will replace previously applied codes. + */ + promo_codes?: string[] +} + export const refreshCartItemsWorkflowId = "refresh-cart-items" /** - * This workflow refreshes a cart's items + * This workflow refreshes a cart to ensure its prices, promotion codes, taxes, and other details are applied correctly. It's useful + * after making a chnge to a cart, such as after adding an item to the cart or adding a promotion code. + * + * This workflow is used by other cart-related workflows, such as the {@link addToCartWorkflow} after an item + * is added to the cart. + * + * You can use this workflow within your own custom workflows, allowing you to refresh the cart after making updates to it in your + * custom flows. + * + * @example + * const { result } = await refreshCartItemsWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * } + * }) + * + * @summary + * + * Refresh a cart's details after an update. */ export const refreshCartItemsWorkflow = createWorkflow( refreshCartItemsWorkflowId, ( - input: WorkflowData<{ - cart_id: string - promo_codes?: string[] - }> + input: WorkflowData ) => { const cart = useRemoteQueryStep({ entry_point: "cart", diff --git a/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts b/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts index 77bfaaf163..235c50f91a 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts +++ b/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts @@ -13,14 +13,39 @@ import { removeShippingMethodFromCartStep } from "../steps" import { updateShippingMethodsStep } from "../steps/update-shipping-methods" import { listShippingOptionsForCartWithPricingWorkflow } from "./list-shipping-options-for-cart-with-pricing" +/** + * The details of the cart to refresh. + */ +export type RefreshCartShippingMethodsWorkflowInput = { + /** + * The cart's ID. + */ + cart_id: string +} + export const refreshCartShippingMethodsWorkflowId = "refresh-cart-shipping-methods" /** - * This workflow refreshes a cart's shipping methods + * This workflow refreshes a cart's shipping methods, ensuring that their associated shipping options can still be used on the cart, + * and retrieve their correct pricing after a cart update. This workflow is used by the {@link refreshCartItemsWorkflow}. + * + * You can use this workflow within your own custom workflows, allowing you to refresh the cart's shipping method after making updates to the cart. + * + * @example + * const { result } = await refreshCartShippingMethodsWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * } + * }) + * + * @summary + * + * Refresh a cart's shipping methods after an update. */ export const refreshCartShippingMethodsWorkflow = createWorkflow( refreshCartShippingMethodsWorkflowId, - (input: WorkflowData<{ cart_id: string }>) => { + (input: WorkflowData) => { const cartQuery = useQueryGraphStep({ entity: "cart", filters: { id: input.cart_id }, diff --git a/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts b/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts index cdcbd28b1e..619c9224f3 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts +++ b/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts @@ -12,14 +12,40 @@ import { useRemoteQueryStep } from "../../common/steps/use-remote-query" import { updatePaymentCollectionStep } from "../../payment-collection" import { deletePaymentSessionsWorkflow } from "../../payment-collection/workflows/delete-payment-sessions" +/** + * The details of the cart to refresh. + */ export type RefreshPaymentCollectionForCartWorklowInput = { + /** + * The cart's ID. + */ cart_id: string } export const refreshPaymentCollectionForCartWorkflowId = "refresh-payment-collection-for-cart" /** - * This workflow refreshes the payment collections of a cart. + * This workflow refreshes a cart's payment collection, which is useful once the cart is created or when its details + * are updated. If the cart's total changes to the amount in its payment collection, the payment collection's payment sessions are + * deleted. It also syncs the payment collection's amount, currency code, and other details with the details in the cart. + * + * This workflow is used by other cart-related workflows, such as the {@link refreshCartItemsWorkflow} to refresh the cart's + * payment collection after an update. + * + * You can use this workflow within your own custom workflows, allowing you to refresh the cart's payment collection after making updates to it in your + * custom flows. + * + * @example + * const { result } = await refreshPaymentCollectionForCartWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * } + * }) + * + * @summary + * + * Refresh a cart's payment collection details. */ export const refreshPaymentCollectionForCartWorkflow = createWorkflow( refreshPaymentCollectionForCartWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts b/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts index 48ccabfdba..9349b7e759 100644 --- a/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts +++ b/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts @@ -10,13 +10,44 @@ import { useQueryGraphStep } from "../../common" import { updateCartsStep } from "../steps" import { refreshCartItemsWorkflow } from "./refresh-cart-items" +/** + * The cart ownership transfer details. + */ +export type TransferCartCustomerWorkflowInput = { + /** + * The cart's ID. + */ + id: string; + /** + * The ID of the customer to transfer the cart to. + */ + customer_id: string +} + export const transferCartCustomerWorkflowId = "transfer-cart-customer" /** - * This workflow transfers cart's customer. + * This workflow transfers a cart's customer ownership to another customer. It's useful if a customer logs in after + * adding the items to their cart, allowing you to transfer the cart's ownership to the logged-in customer. This workflow is used + * by the [Set Cart's Customer Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidcustomer). + * + * You can use this workflow within your own custom workflows, allowing you to set the cart's customer within your custom flows. + * + * @example + * const { result } = await transferCartCustomerWorkflow(container) + * .run({ + * input: { + * id: "cart_123", + * customer_id: "cus_123" + * } + * }) + * + * @summary + * + * Refresh a cart's payment collection details. */ export const transferCartCustomerWorkflow = createWorkflow( transferCartCustomerWorkflowId, - (input: WorkflowData<{ id: string; customer_id: string }>) => { + (input: WorkflowData) => { const cartQuery = useQueryGraphStep({ entity: "cart", filters: { id: input.id }, diff --git a/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts b/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts index 868bd91702..d5d3ec6608 100644 --- a/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts +++ b/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts @@ -20,9 +20,22 @@ import { import { updateCartPromotionsStep } from "../steps/update-cart-promotions" import { cartFieldsForRefreshSteps } from "../utils/fields" +/** + * The details of the promotion updates on a cart. + */ export type UpdateCartPromotionsWorkflowInput = { + /** + * The cart's ID. + */ cart_id: string + /** + * The promotion codes to add to the cart, remove from the cart, + * or replace all existing promotions in the cart. + */ promo_codes?: string[] + /** + * The action to perform with the specified promotion codes. + */ action?: | PromotionActions.ADD | PromotionActions.REMOVE @@ -31,7 +44,26 @@ export type UpdateCartPromotionsWorkflowInput = { export const updateCartPromotionsWorkflowId = "update-cart-promotions" /** - * This workflow updates a cart's promotions. + * This workflow updates a cart's promotions, applying or removing promotion codes from the cart. It also computes the adjustments + * that need to be applied to the cart's line items and shipping methods based on the promotions applied. This workflow is used by + * [Add Promotions Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidpromotions). + * + * You can use this workflow within your own custom workflows, allowing you to update a cart's promotions within your custom flows. + * + * @example + * const { result } = await updateCartPromotionsWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * promo_codes: ["10OFF"], + * // imported from @medusajs/framework/utils + * action: PromotionActions.ADD, + * } + * }) + * + * @summary + * + * Update a cart's applied promotions to add, replace, or remove them. */ export const updateCartPromotionsWorkflow = createWorkflow( updateCartPromotionsWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts b/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts index 287500ea3a..d5c382cbed 100644 --- a/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts @@ -24,7 +24,26 @@ const cartFields = cartFieldsForPricingContext.concat(["items.*"]) export const updateLineItemInCartWorkflowId = "update-line-item-in-cart" /** - * This workflow updates a cart's line item. + * This workflow updates a line item's details in a cart. You can update the line item's quantity, unit price, and more. This workflow is executed + * by the [Update Line Item Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidlineitemsline_id). + * + * You can use this workflow within your own custom workflows, allowing you to update a line item's details in your custom flows. + * + * @example + * const { result } = await updateLineItemInCartWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * item_id: "item_123", + * update: { + * quantity: 2 + * } + * } + * }) + * + * @summary + * + * Update a cart's line item. */ export const updateLineItemInCartWorkflow = createWorkflow( updateLineItemInCartWorkflowId, diff --git a/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts b/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts index 9aff9e6a9c..c786269a8b 100644 --- a/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts +++ b/packages/core/core-flows/src/cart/workflows/update-tax-lines.ts @@ -60,16 +60,60 @@ const cartFields = [ "shipping_address.metadata", ] +/** + * The details of the cart to update tax lines for. + */ export type UpdateTaxLinesWorkflowInput = { + /** + * The cart's ID. + */ cart_id: string + /** + * The items to update their tax lines. + * If not specified, taxes are updated for all of the cart's + * line items. + * + * @privateRemarks + * This doesn't seem to be used? + */ items?: CartLineItemDTO[] + /** + * The shipping methods to update their tax lines. + * If not specified, taxes are updated for all of the cart's + * shipping methods. + * + * @privateRemarks + * This doesn't seem to be used? + */ shipping_methods?: CartShippingMethodDTO[] + /** + * Whether to force re-calculating tax amounts, which + * may include sending requests to a third-part tax provider, depending + * on the configurations of the cart's tax region. + * + * @defaultValue false + */ force_tax_calculation?: boolean } export const updateTaxLinesWorkflowId = "update-tax-lines" /** - * This workflow updates a cart's tax lines. + * This workflow updates a cart's tax lines that are applied on line items and shipping methods. You can update the line item's quantity, unit price, and more. This workflow is executed + * by the [Calculate Taxes Store API Route](https://docs.medusajs.com/api/store#carts_postcartsidtaxes). + * + * You can use this workflow within your own custom workflows, allowing you to update a cart's tax lines in your custom flows. + * + * @example + * const { result } = await updateTaxLinesWorkflow(container) + * .run({ + * input: { + * cart_id: "cart_123", + * } + * }) + * + * @summary + * + * Update a cart's tax lines. */ export const updateTaxLinesWorkflow = createWorkflow( updateTaxLinesWorkflowId, 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 322eb1f10e..9bf06c91d0 100644 --- a/packages/core/core-flows/src/customer/workflows/create-addresses.ts +++ b/packages/core/core-flows/src/customer/workflows/create-addresses.ts @@ -3,6 +3,7 @@ import { CreateCustomerAddressDTO, } from "@medusajs/framework/types" import { + WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -73,7 +74,7 @@ export const createCustomerAddressesWorkflowId = "create-customer-addresses" */ export const createCustomerAddressesWorkflow = createWorkflow( createCustomerAddressesWorkflowId, - (input: CreateCustomerAddressesWorkflowInput) => { + (input: WorkflowData) => { 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 ac8d3448fb..2fee49e3f1 100644 --- a/packages/core/core-flows/src/customer/workflows/create-customers.ts +++ b/packages/core/core-flows/src/customer/workflows/create-customers.ts @@ -1,6 +1,7 @@ import { AdditionalData, CreateCustomerDTO } from "@medusajs/framework/types" import { CustomerWorkflowEvents } from "@medusajs/framework/utils" import { + WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -52,7 +53,7 @@ export const createCustomersWorkflowId = "create-customers" */ export const createCustomersWorkflow = createWorkflow( createCustomersWorkflowId, - (input: CreateCustomersWorkflowInput) => { + (input: WorkflowData) => { 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 c5c618092a..a7dd4e53aa 100644 --- a/packages/core/core-flows/src/customer/workflows/update-addresses.ts +++ b/packages/core/core-flows/src/customer/workflows/update-addresses.ts @@ -4,6 +4,7 @@ import { AdditionalData, } from "@medusajs/framework/types" import { + WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -64,7 +65,7 @@ export const updateCustomerAddressesWorkflowId = "update-customer-addresses" */ export const updateCustomerAddressesWorkflow = createWorkflow( updateCustomerAddressesWorkflowId, - (input: UpdateCustomerAddressesWorkflowInput) => { + (input: WorkflowData) => { const unsetInput = transform(input, (data) => ({ update: data, })) 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 4b076d46c5..d46b351ecf 100644 --- a/packages/core/core-flows/src/order/workflows/create-fulfillment.ts +++ b/packages/core/core-flows/src/order/workflows/create-fulfillment.ts @@ -14,6 +14,7 @@ import { OrderWorkflowEvents, } from "@medusajs/framework/utils" import { + WorkflowData, WorkflowResponse, createHook, createStep, @@ -309,7 +310,7 @@ export const createOrderFulfillmentWorkflowId = "create-order-fulfillment" export const createOrderFulfillmentWorkflow = createWorkflow( createOrderFulfillmentWorkflowId, ( - input: CreateOrderFulfillmentWorkflowInput + input: WorkflowData ) => { 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 745064484e..35ee351439 100644 --- a/packages/core/core-flows/src/order/workflows/create-order.ts +++ b/packages/core/core-flows/src/order/workflows/create-order.ts @@ -1,6 +1,7 @@ import { AdditionalData, CreateOrderDTO } from "@medusajs/framework/types" import { MedusaError, isDefined, isPresent } from "@medusajs/framework/utils" import { + WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -76,6 +77,9 @@ function getOrderInput(data) { return data_ } +/** + * The data to create an order, along with custom data that's passed to the workflow's hooks. + */ export type CreateOrderWorkflowInput = CreateOrderDTO & AdditionalData export const createOrdersWorkflowId = "create-orders" @@ -126,7 +130,7 @@ export const createOrdersWorkflowId = "create-orders" */ export const createOrderWorkflow = createWorkflow( createOrdersWorkflowId, - (input: CreateOrderWorkflowInput) => { + (input: WorkflowData) => { 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 9aa03fae4d..33600556f8 100644 --- a/packages/core/core-flows/src/order/workflows/create-shipment.ts +++ b/packages/core/core-flows/src/order/workflows/create-shipment.ts @@ -6,6 +6,7 @@ import { } from "@medusajs/framework/types" import { FulfillmentEvents, Modules } from "@medusajs/framework/utils" import { + WorkflowData, WorkflowResponse, createHook, createStep, @@ -154,7 +155,7 @@ export const createOrderShipmentWorkflowId = "create-order-shipment" export const createOrderShipmentWorkflow = createWorkflow( createOrderShipmentWorkflowId, ( - input: CreateOrderShipmentWorkflowInput + input: WorkflowData ) => { const order: OrderDTO = useRemoteQueryStep({ entry_point: "orders", 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 f1de5fb3b8..2d4125f733 100644 --- a/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts +++ b/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts @@ -1,5 +1,6 @@ import { AdditionalData, CreateCampaignDTO } from "@medusajs/framework/types" import { + WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -55,7 +56,7 @@ export const createCampaignsWorkflowId = "create-campaigns" */ export const createCampaignsWorkflow = createWorkflow( createCampaignsWorkflowId, - (input: CreateCampaignsWorkflowInput) => { + (input: WorkflowData) => { 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 da94ef7738..a69ede0f25 100644 --- a/packages/core/core-flows/src/promotion/workflows/create-promotions.ts +++ b/packages/core/core-flows/src/promotion/workflows/create-promotions.ts @@ -1,5 +1,6 @@ import { AdditionalData, CreatePromotionDTO } from "@medusajs/framework/types" import { + WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -56,7 +57,7 @@ export const createPromotionsWorkflowId = "create-promotions" */ export const createPromotionsWorkflow = createWorkflow( createPromotionsWorkflowId, - (input: CreatePromotionsWorkflowInput) => { + (input: WorkflowData) => { 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 f0f28fc97e..bc5d8a7fee 100644 --- a/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts +++ b/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts @@ -1,5 +1,6 @@ import { AdditionalData, UpdateCampaignDTO } from "@medusajs/framework/types" import { + WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -50,7 +51,7 @@ export const updateCampaignsWorkflowId = "update-campaigns" */ export const updateCampaignsWorkflow = createWorkflow( updateCampaignsWorkflowId, - (input: UpdateCampaignsWorkflowInput) => { + (input: WorkflowData) => { 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 107081640f..aec633c826 100644 --- a/packages/core/core-flows/src/promotion/workflows/update-promotions.ts +++ b/packages/core/core-flows/src/promotion/workflows/update-promotions.ts @@ -1,5 +1,6 @@ import { AdditionalData, UpdatePromotionDTO } from "@medusajs/framework/types" import { + WorkflowData, WorkflowResponse, createHook, createWorkflow, @@ -49,7 +50,7 @@ export const updatePromotionsWorkflowId = "update-promotions" */ export const updatePromotionsWorkflow = createWorkflow( updatePromotionsWorkflowId, - (input: UpdatePromotionsWorkflowInput) => { + (input: WorkflowData) => { 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 7365ecbebb..9e279d94a4 100644 --- a/packages/core/types/src/cart/workflows.ts +++ b/packages/core/types/src/cart/workflows.ts @@ -132,9 +132,21 @@ export interface CreateCartCreateLineItemDTO { metadata?: Record | null } +/** + * The details of the line item to update. + */ export interface UpdateLineItemInCartWorkflowInputDTO { + /** + * The ID of the cart that the line item belongs to. + */ cart_id: string + /** + * The ID of the line item to update. + */ item_id: string + /** + * The details to update in the line item. + */ update: Partial } @@ -267,8 +279,17 @@ export interface CreateCartWorkflowInputDTO { promo_codes?: string[] } +/** + * The details of adding items to the cart. + */ export interface AddToCartWorkflowInputDTO { + /** + * The ID of the cart to add items to. + */ cart_id: string + /** + * The items to add to the cart. + */ items: CreateCartCreateLineItemDTO[] } @@ -329,14 +350,36 @@ export interface UpdateCartWorkflowInputDTO { billing_address?: CreateAddressDTO | UpdateAddressDTO | null } +/** + * The details to create the payment collection. + */ export interface CreatePaymentCollectionForCartWorkflowInputDTO { + /** + * The ID of the cart to create a payment collection for. + */ cart_id: string + + /** + * Custom key-value pairs to store in the payment collection. + */ metadata?: Record } +/** + * A cart's details. + */ export interface CartWorkflowDTO extends CartDTO { + /** + * The cart's customer. + */ customer?: CustomerDTO + /** + * The cart's product to be added. + */ product?: ProductDTO + /** + * The cart's region. + */ region?: RegionDTO } @@ -361,20 +404,67 @@ export interface CompleteCartWorkflowInputDTO { id: string } +/** + * The details necessary to check whether the variant has sufficient inventory. + */ export interface ConfirmVariantInventoryWorkflowInputDTO { + /** + * The ID of the sales channel to check the inventory availability in. + */ sales_channel_id: string + /** + * The variants to confirm they have sufficient in-stock quantity. + */ variants: { + /** + * The variant's ID. + */ id: string + /** + * Whether Medusa manages the inventory of the variant. If disabled, the + * variant is always considered in stock. + */ manage_inventory: boolean + /** + * The variant's inventory items, if {@link manage_inventory} is enabled. + */ inventory_items: { + /** + * The ID of the inventory item. + */ inventory_item_id: string + /** + * The ID of the variant. + */ variant_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: BigNumberInput + /** + * The inventory details. + */ inventory: { + /** + * The inventory details at specified stock locations. + */ location_levels: { + /** + * The stock location's details. + */ stock_locations: { + /** + * The stock location's ID. + */ id: string + /** + * The associated sales channel's details. + */ sales_channels: { + /** + * The sales channel's ID. + */ id: string }[] }[] @@ -382,14 +472,39 @@ export interface ConfirmVariantInventoryWorkflowInputDTO { }[] }[] }[] + /** + * The items in the cart, or to be added. + */ items: { + /** + * The ID of the associated variant. + */ variant_id?: string | null + /** + * The quantity in the cart. + */ quantity: BigNumberInput + /** + * The ID of the line item if it's already in the cart. + */ id?: string }[] + /** + * The new quantity of the variant to be added to the cart. + * This is useful when updating a variant's quantity in the cart. + */ itemsToUpdate?: { + /** + * The item update's details. + */ data: { + /** + * The ID of the associated variant. + */ variant_id?: string + /** + * The variant's quantity. + */ quantity?: BigNumberInput } }[] diff --git a/packages/core/types/src/fulfillment/common/cart.ts b/packages/core/types/src/fulfillment/common/cart.ts index d66ce1e175..c6e7052eb1 100644 --- a/packages/core/types/src/fulfillment/common/cart.ts +++ b/packages/core/types/src/fulfillment/common/cart.ts @@ -1,27 +1,87 @@ import { CartDTO } from "../.." +/** + * A cart's details relevant for fulfillment. + */ export type CartPropsForFulfillment = { + /** + * The cart's ID. + */ id: CartDTO["id"] + /** + * The cart's shipping address. + */ shipping_address: CartDTO["shipping_address"] + /** + * The cart's items + */ items: CartDTO["items"] & { + /** + * The item's variant. + */ variant: { + /** + * The variant's ID. + */ id: string + /** + * The variant's weight. + */ weight: number + /** + * The variant's length. + */ length: number + /** + * The variant's height. + */ height: number + /** + * The variant's width. + */ width: number + /** + * The variant's material. + */ material: string + /** + * The variant's associated product. + */ product: { + /** + * The product's ID. + */ id: string } } + /** + * The item's product. + */ product: { + /** + * The product's ID. + */ id: string + /** + * The ID of the collection that the product belongs to. + */ collection_id: string + /** + * The product's categories. + */ categories: { + /** + * The category's ID. + */ id: string }[] + /** + * The product's tags. + */ tags: { + /** + * The tag's ID. + */ id: string }[] } diff --git a/packages/core/types/src/fulfillment/provider.ts b/packages/core/types/src/fulfillment/provider.ts index ee4e55f282..85095a8b6c 100644 --- a/packages/core/types/src/fulfillment/provider.ts +++ b/packages/core/types/src/fulfillment/provider.ts @@ -39,6 +39,9 @@ export type CalculatedShippingOptionPrice = { is_calculated_price_tax_inclusive: boolean } +/** + * The context for validating fulfillment data. + */ export type ValidateFulfillmentDataContext = CartPropsForFulfillment & { /** * Details about the location that items are being shipped from. diff --git a/packages/core/types/src/fulfillment/workflows.ts b/packages/core/types/src/fulfillment/workflows.ts index 33e3bbb072..455f5256b9 100644 --- a/packages/core/types/src/fulfillment/workflows.ts +++ b/packages/core/types/src/fulfillment/workflows.ts @@ -1,3 +1,5 @@ +import { CalculatedShippingOptionPrice, StockLocationAddressDTO } from ".." +import { ShippingOptionPriceType, ShippingOptionTypeDTO } from "./common" import { CreateShippingOptionRuleDTO, UpdateShippingOptionRuleDTO, @@ -14,3 +16,212 @@ export type RemoveFulfillmentShippingOptionRulesWorkflowDTO = { export type UpdateFulfillmentShippingOptionRulesWorkflowDTO = { data: UpdateShippingOptionRuleDTO[] } + +/** + * The context for retrieving the shipping options. + */ +export type ListShippingOptionsForCartWithPricingWorkflowInput = { + /** + * The cart's ID. + */ + cart_id: string + /** + * Specify the shipping options to retrieve their details and prices. + * If not provided, all applicable shipping options are retrieved. + */ + options?: { + /** + * The shipping option's ID. + */ + id: string; + /** + * Custom data relevant for the fulfillment provider that processes this shipping option. + * It can be data relevant to calculate the shipping option's price. + * + * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property). + */ + data?: Record + }[] + /** + * Whether to retrieve return shipping options. + * By default, non-return shipping options are retrieved. + * + * @defaultValue false + */ + is_return?: boolean + /** + * Whether to retrieve the shipping option's enabled in the store, which is the default. + * + * @defaultValue true + */ + enabled_in_store?: boolean +} + +/** + * The retrieved shipping options with prices. + */ +export type ListShippingOptionsForCartWithPricingWorkflowOutput = { + /** + * The shipping option's ID. + */ + id: string + + /** + * The name of the shipping option. + */ + name: string + + /** + * The shipping option's price type. + */ + price_type: ShippingOptionPriceType + + /** + * The associated service zone's ID. + */ + service_zone_id: string + + /** + * The service zone details. + */ + service_zone: { + /** + * The ID of the fulfillment set associated with the service zone. + */ + fulfillment_set_id: string + } + + /** + * The ID of the associated shipping profile. + */ + shipping_profile_id: string + + /** + * The ID of the associated fulfillment provider. It's used to calculate + * the shipping option's price, if it's price type is `calculated`, and later + * it processes shipments created from this shipping option. + */ + provider_id: string + + /** + * Custom additional data related to the shipping option, useful for the fulfillment provider + * to process the shipping option and calculate its price. + * + * Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property). + */ + data: Record + + /** + * The shipping option's type. + */ + type: Omit + + /** + * The associated fulfillment provider details. + */ + provider: { + /** + * The ID of the provider. + */ + id: string + + /** + * Whether the provider is enabled. + */ + is_enabled: boolean + } + + /** + * The shipping option rules associated with the shipping option. + */ + rules: { + /** + * The name of a property or table that the rule applies to. + * + * @example + * customer_group + */ + attribute: string + + /** + * The value of the rule. + */ + value: string + + /** + * The operator of the rule. + * + * @example + * in + */ + operator: string + }[] + + /** + * The amount for the shipping option, which can be flat rate or calculated. + */ + amount: number | undefined + + /** + * Indicates whether taxes are included in the shipping option amount. + */ + is_tax_inclusive: boolean | undefined + + /** + * The calculated price for the shipping option, if its `price_type` is `calculated`. + */ + calculated_price?: CalculatedShippingOptionPrice + + /** + * The details of the associated stock location, which is set if the shipping option's `price_type` is `calculated`. + */ + stock_location?: { + /** + * The ID of the stock location. + */ + id: string + + /** + * The name of the stock location. + */ + name: string + + /** + * The address of the stock location. + */ + address: StockLocationAddressDTO + + /** + * The ID of the fulfillment set associated with the stock location. + */ + fulfillment_set_id: string + } +}[] + +/** + * The context for retrieving the shipping options. + */ +export type ListShippingOptionsForCartWorkflowInput = { + /** + * The cart's ID. + */ + cart_id: string + /** + * Specify the shipping options to retrieve their details. + * If not specified, all applicable shipping options are retrieved. + */ + option_ids?: string[] + /** + * Whether to retrieve return shipping options. + * By default, non-return shipping options are retrieved. + * + * @defaultValue false + */ + is_return?: boolean + /** + * Whether to retrieve the shipping option's enabled in the store, which is the default. + * + * @defaultValue true + */ + enabled_in_store?: boolean +}