asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(core-flows,types): improve TSDocs of cart workflows and steps (#10962)

Browse Source 
* chore(core-flows,types): improve TSDocs of cart workflows and steps

* fix build errors

* fix build error

* fix errors
This commit is contained in:
Shahed Nasser
2025-01-16 09:44:52 +02:00
committed by GitHub
parent f5235862c0
commit 8cd58b3092
63 changed files with 1785 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
packages/core/core-flows/src/cart/steps/add-shipping-method-to-cart.ts
View File

@@ -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,

38
packages/core/core-flows/src/cart/steps/confirm-inventory.ts
View File

@@ -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,

7
packages/core/core-flows/src/cart/steps/create-carts.ts
View File

@@ -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<ICartModuleService>(Modules.CART)
const createdCarts = await service.createCarts(data)

19
packages/core/core-flows/src/cart/steps/create-line-item-adjustments.ts
View File

@@ -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,

20
packages/core/core-flows/src/cart/steps/create-line-items.ts
View File

@@ -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,

26
packages/core/core-flows/src/cart/steps/create-payment-collection.ts
View File

@@ -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<string, unknown>
}
}[]
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<IPaymentModuleService>(Modules.PAYMENT)
const created = await service.createPaymentCollections(data)

15
packages/core/core-flows/src/cart/steps/create-shipping-method-adjustments.ts
View File

@@ -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,

12
packages/core/core-flows/src/cart/steps/find-one-or-any-region.ts
View File

@@ -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<IRegionModuleService>(Modules.REGION)
const storeModule = container.resolve<IStoreModuleService>(Modules.STORE)

19
packages/core/core-flows/src/cart/steps/find-or-create-customer.ts
View File

@@ -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
}

6
packages/core/core-flows/src/cart/steps/find-sales-channel.ts
View File

@@ -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
}

23
packages/core/core-flows/src/cart/steps/get-actions-to-compute-from-promotions.ts
View File

@@ -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,

35
packages/core/core-flows/src/cart/steps/get-line-item-actions.ts
View File

@@ -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)
}
)

49
packages/core/core-flows/src/cart/steps/get-promotion-codes-to-apply.ts
View File

@@ -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
)
}
)

44
packages/core/core-flows/src/cart/steps/get-variant-price-sets.ts
View File

@@ -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<string, unknown>
}
/**
* 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
)
}
)

10
packages/core/core-flows/src/cart/steps/get-variants.ts
View File

@@ -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<ProductVariantDTO>
@@ -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,

5
packages/core/core-flows/src/cart/steps/index.ts
View File

@@ -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"

78
packages/core/core-flows/src/cart/steps/prepare-adjustments-from-promotion-actions.ts
View File

@@ -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)
}
)

6
packages/core/core-flows/src/cart/steps/remove-line-item-adjustments.ts
View File

@@ -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[]
}

6
packages/core/core-flows/src/cart/steps/remove-shipping-method-adjustments.ts
View File

@@ -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[]
}

17
packages/core/core-flows/src/cart/steps/remove-shipping-method-from-cart.ts
View File

@@ -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<string, string[]> | 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) {

41
packages/core/core-flows/src/cart/steps/reserve-inventory.ts
View File

@@ -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,

6
packages/core/core-flows/src/cart/steps/retrieve-cart.ts
View File

@@ -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<CartDTO>
}

39
packages/core/core-flows/src/cart/steps/set-tax-lines-for-items.ts
View File

@@ -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,

12
packages/core/core-flows/src/cart/steps/update-cart-promotions.ts
View File

@@ -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

13
packages/core/core-flows/src/cart/steps/update-carts.ts
View File

@@ -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<ICartModuleService>(Modules.CART)
const { selects, relations } = getSelectsAndRelationsFromObjectArray(data)

24
packages/core/core-flows/src/cart/steps/update-line-items.ts
View File

@@ -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,

15
packages/core/core-flows/src/cart/steps/update-shipping-methods.ts
View File

@@ -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([], [])
}

21
packages/core/core-flows/src/cart/steps/validate-cart-payments.ts
View File

@@ -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,

28
packages/core/core-flows/src/cart/steps/validate-cart-shipping-options.ts
View File

@@ -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,

22
packages/core/core-flows/src/cart/steps/validate-cart.ts
View File

@@ -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,

26
packages/core/core-flows/src/cart/steps/validate-line-item-prices.ts
View File

@@ -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,

78
packages/core/core-flows/src/cart/steps/validate-shipping-methods-data.ts
View File

@@ -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<string, unknown>
/**
* The `data` property of the shipping method.
*/
method_data: Record<string, unknown>
/**
* The context to validate the shipping method.
*/
context: ValidateFulfillmentDataContext
}[]
/**
* The validated data of the shipping methods.
*/
export type ValidateShippingMethodsDataOutput = void | {
[x: string]: Record<string, unknown>;
}[]
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,

31
packages/core/core-flows/src/cart/steps/validate-shipping-options-price.ts
View File

@@ -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[] = []

31
packages/core/core-flows/src/cart/steps/validate-variant-prices.ts
View File

@@ -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,

45
packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts
View File

@@ -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<string, unknown>
}[]
}
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,

29
packages/core/core-flows/src/cart/workflows/add-to-cart.ts
View File

@@ -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,

34
packages/core/core-flows/src/cart/workflows/complete-cart.ts
View File

@@ -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, {

118
packages/core/core-flows/src/cart/workflows/confirm-variant-inventory.ts
View File

@@ -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,

50
packages/core/core-flows/src/cart/workflows/create-payment-collection-for-cart.ts
View File

@@ -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,

2
packages/core/core-flows/src/cart/workflows/index.ts
View File

@@ -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"

41
packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts
View File

@@ -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<string, unknown> }[]
is_return?: boolean
enabled_in_store?: boolean
}>
input: WorkflowData<ListShippingOptionsForCartWithPricingWorkflowInput>
) => {
const optionIds = transform({ input }, ({ input }) =>
(input.options ?? []).map(({ id }) => id)

34
packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts
View File

@@ -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<ListShippingOptionsForCartWorkflowInput>
) => {
const cartQuery = useQueryGraphStep({
entity: "cart",

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

@@ -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<RefreshCartItemsWorkflowInput>
) => {
const cart = useRemoteQueryStep({
entry_point: "cart",

29
packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts
View File

@@ -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<RefreshCartShippingMethodsWorkflowInput>) => {
const cartQuery = useQueryGraphStep({
entity: "cart",
filters: { id: input.cart_id },

28
packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts
View File

@@ -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,

35
packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts
View File

@@ -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<TransferCartCustomerWorkflowInput>) => {
const cartQuery = useQueryGraphStep({
entity: "cart",
filters: { id: input.id },

34
packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts
View File

@@ -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,

21
packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts
View File

@@ -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,

46
packages/core/core-flows/src/cart/workflows/update-tax-lines.ts
View File

@@ -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,

3
packages/core/core-flows/src/customer/workflows/create-addresses.ts
View File

@@ -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<CreateCustomerAddressesWorkflowInput>) => {
const unsetInput = transform(input, (data) => ({
create: data.addresses,
}))

3
packages/core/core-flows/src/customer/workflows/create-customers.ts
View File

@@ -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<CreateCustomersWorkflowInput>) => {
const createdCustomers = createCustomersStep(input.customersData)
const customersCreated = createHook("customersCreated", {
customers: createdCustomers,

3
packages/core/core-flows/src/customer/workflows/update-addresses.ts
View File

@@ -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<UpdateCustomerAddressesWorkflowInput>) => {
const unsetInput = transform(input, (data) => ({
update: data,
}))

3
packages/core/core-flows/src/order/workflows/create-fulfillment.ts
View File

@@ -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<CreateOrderFulfillmentWorkflowInput>
) => {
const order: OrderDTO = useRemoteQueryStep({
entry_point: "orders",

6
packages/core/core-flows/src/order/workflows/create-order.ts
View File

@@ -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<CreateOrderWorkflowInput>) => {
const variantIds = transform({ input }, (data) => {
return (data.input.items ?? [])
.map((item) => item.variant_id)

3
packages/core/core-flows/src/order/workflows/create-shipment.ts
View File

@@ -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<CreateOrderShipmentWorkflowInput>
) => {
const order: OrderDTO = useRemoteQueryStep({
entry_point: "orders",

3
packages/core/core-flows/src/promotion/workflows/create-campaigns.ts
View File

@@ -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<CreateCampaignsWorkflowInput>) => {
const createdCampaigns = createCampaignsStep(input.campaignsData)
const campaignsCreated = createHook("campaignsCreated", {
campaigns: createdCampaigns,

3
packages/core/core-flows/src/promotion/workflows/create-promotions.ts
View File

@@ -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<CreatePromotionsWorkflowInput>) => {
const createdPromotions = createPromotionsStep(input.promotionsData)
const promotionsCreated = createHook("promotionsCreated", {
promotions: createdPromotions,

3
packages/core/core-flows/src/promotion/workflows/update-campaigns.ts
View File

@@ -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<UpdateCampaignsWorkflowInput>) => {
const updatedCampaigns = updateCampaignsStep(input.campaignsData)
const campaignsUpdated = createHook("campaignsUpdated", {
campaigns: updatedCampaigns,

3
packages/core/core-flows/src/promotion/workflows/update-promotions.ts
View File

@@ -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<UpdatePromotionsWorkflowInput>) => {
const updatedPromotions = updatePromotionsStep(input.promotionsData)
const promotionsUpdated = createHook("promotionsUpdated", {
promotions: updatedPromotions,

115
packages/core/types/src/cart/workflows.ts
View File

@@ -132,9 +132,21 @@ export interface CreateCartCreateLineItemDTO {
metadata?: Record<string, unknown> | 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<UpdateLineItemDTO>
}
@@ -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<string, unknown>
}
/**
* 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
}
}[]

60
packages/core/types/src/fulfillment/common/cart.ts
View File

@@ -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
}[]
}

3
packages/core/types/src/fulfillment/provider.ts
View File

@@ -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.

211
packages/core/types/src/fulfillment/workflows.ts
View File

@@ -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<string, unknown>
}[]
/**
* 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<string, unknown>
/**
* The shipping option's type.
*/
type: Omit<ShippingOptionTypeDTO, "shipping_option_id" | "shipping_option" | "created_at" | "updated_at" | "deleted_at">
/**
* 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
}