From db338e4b5a039309e4dc0e7a9cb6e20c32fd8889 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 13 Jan 2025 11:23:58 +0200 Subject: [PATCH] chore(core-flows,types): add tsdocs for create cart workflow (#10928) --- .../src/cart/workflows/create-carts.ts | 37 +++- packages/core/types/src/cart/workflows.ts | 188 ++++++++++++++++++ .../types/src/http/common/additional_data.ts | 6 +- 3 files changed, 227 insertions(+), 4 deletions(-) diff --git a/packages/core/core-flows/src/cart/workflows/create-carts.ts b/packages/core/core-flows/src/cart/workflows/create-carts.ts index b1e1075499..07012a34a6 100644 --- a/packages/core/core-flows/src/cart/workflows/create-carts.ts +++ b/packages/core/core-flows/src/cart/workflows/create-carts.ts @@ -36,13 +36,42 @@ import { refreshPaymentCollectionForCartWorkflow } from "./refresh-payment-colle import { updateCartPromotionsWorkflow } from "./update-cart-promotions" import { updateTaxLinesWorkflow } from "./update-tax-lines" +/** + * The data to create the cart, along with custom data that's later passed to the cart's hooks. + */ +export type CreateCartWorkflowInput = CreateCartWorkflowInputDTO & AdditionalData + export const createCartWorkflowId = "create-cart" /** - * This workflow creates a cart. + * This workflow creates and returns a cart. You can set the cart's items, region, customer, and other details. This workflow is executed by the + * [Create Cart Store API Route](https://docs.medusajs.com/api/store#carts_postcarts). + * + * This workflow has a hook that allows you to perform custom actions on the created cart. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/cart/extend#step-4-consume-cartcreated-workflow-hook). + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around cart creation. + * + * @example + * const { result } = await createCartWorkflow(container) + * .run({ + * input: { + * region_id: "reg_123", + * items: [ + * { + * variant_id: "var_123", + * quantity: 1, + * } + * ], + * customer_id: "cus_123" + * } + * }) + * + * @summary + * + * Create a cart specifying region, items, and more. */ export const createCartWorkflow = createWorkflow( createCartWorkflowId, - (input: WorkflowData) => { + (input: WorkflowData) => { const variantIds = transform({ input }, (data) => { return (data.input.items ?? []).map((i) => i.variant_id).filter(Boolean) }) @@ -200,6 +229,10 @@ export const createCartWorkflow = createWorkflow( }) ) + /** + * This hook is executed after a cart is created. You can consume this hook to perform + * custom actions on the created cart. + */ const cartCreated = createHook("cartCreated", { cart, additional_data: input.additional_data, diff --git a/packages/core/types/src/cart/workflows.ts b/packages/core/types/src/cart/workflows.ts index 194e575fef..b64d1d448a 100644 --- a/packages/core/types/src/cart/workflows.ts +++ b/packages/core/types/src/cart/workflows.ts @@ -11,35 +11,124 @@ import { UpdateLineItemDTO, } from "./mutations" +/** + * The details of the line item to create. + */ export interface CreateCartCreateLineItemDTO { + /** + * The quantity of the line item. + */ quantity: BigNumberInput + + /** + * The ID of the variant to be added to the cart. + */ variant_id?: string + + /** + * The title of the line item. + */ title?: string + /** + * The subtitle of the line item. + */ subtitle?: string + + /** + * The thumbnail URL of the line item. + */ thumbnail?: string + /** + * The ID of the product whose variant is being added to the cart. + */ product_id?: string + + /** + * The title of the associated product. + */ product_title?: string + + /** + * The description of the associated product. + */ product_description?: string + + /** + * The subtitle of the associated product. + */ product_subtitle?: string + + /** + * The ID of the associated product's type. + */ product_type?: string + + /** + * The ID of the associated product's collection. + */ product_collection?: string + + /** + * The handle of the associated product. + */ product_handle?: string + /** + * The SKU of the associated variant. + */ variant_sku?: string + + /** + * The barcode of the associated variant. + */ variant_barcode?: string + + /** + * The title of the associated variant. + */ variant_title?: string + + /** + * The associated variant's values for the product's options. + */ variant_option_values?: Record + /** + * Whether the line item requires shipping. + */ requires_shipping?: boolean + + /** + * Whether the line item is discountable. + */ is_discountable?: boolean + + /** + * Whether the line item's price is tax inclusive. Learn more in + * [this documentation](https://docs.medusajs.com/resources/commerce-modules/pricing/tax-inclusive-pricing) + */ is_tax_inclusive?: boolean + + /** + * Whether the line item is a gift card. + */ is_giftcard?: boolean + /** + * The original price of the item before a promotion or sale. + */ compare_at_unit_price?: BigNumberInput + + /** + * The price of a single quantity of the item. + */ unit_price?: BigNumberInput + /** + * Custom key-value pairs related to the item. + */ metadata?: Record | null } @@ -49,33 +138,132 @@ export interface UpdateLineItemInCartWorkflowInputDTO { update: Partial } +/** + * The details of the address to create. + */ export interface CreateCartAddressDTO { + /** + * The first name of the customer associated with the address. + */ first_name?: string + + /** + * The last name of the customer associated with the address. + */ last_name?: string + + /** + * The address's phone number + */ phone?: string + + /** + * The address's company name. + */ company?: string + + /** + * The primary address line. + */ address_1?: string + + /** + * The secondary address line. + */ address_2?: string + + /** + * The city of the address. + */ city?: string + + /** + * The country code of the address. + * + * @example us + */ country_code?: string + + /** + * The province or state of the address. + */ province?: string + + /** + * The postal code of the address. + */ postal_code?: string + + /** + * Custom key-value pairs related to the address. + */ metadata?: Record } +/** + * The details of a cart to create. + */ export interface CreateCartWorkflowInputDTO { + /** + * The ID of the region that the cart belongs to. + */ region_id?: string + + /** + * The ID of the customer associated with the cart. + */ customer_id?: string + + /** + * The ID of the sales channel through which the cart is created. + */ sales_channel_id?: string + + /** + * The email address of the cart's customer. + */ email?: string + + /** + * The currency code of the cart. This defaults to the region's currency code. + * + * @example usd + */ currency_code?: string + + /** + * The ID of the associated shipping address. + */ shipping_address_id?: string + + /** + * The ID of the associated billing address. + */ billing_address_id?: string + + /** + * The ID of an existing shipping address, or the details of a shipping address to create. + */ shipping_address?: CreateCartAddressDTO | string + + /** + * The ID of an existing billing address, or the details of a billing address to create. + */ billing_address?: CreateCartAddressDTO | string + + /** + * Custom key-value pairs related to the cart. + */ metadata?: Record + /** + * The items to be added to the cart. + */ items?: CreateCartCreateLineItemDTO[] + + /** + * The promotional codes applied on the cart. + */ promo_codes?: string[] } diff --git a/packages/core/types/src/http/common/additional_data.ts b/packages/core/types/src/http/common/additional_data.ts index b0ae423ec8..b813d38a10 100644 --- a/packages/core/types/src/http/common/additional_data.ts +++ b/packages/core/types/src/http/common/additional_data.ts @@ -1,6 +1,8 @@ /** - * Represents the additional_data property accepted in HTTP - * requests to allow arbitrary values + * Additional data, passed through the `additional_data` property accepted in HTTP + * requests, that allows passing custom data and handle them in hooks. + * + * Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data). */ export type AdditionalData = { additional_data?: Record