chore(core-flows,types): add tsdocs for create cart workflow (#10928)

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<CreateCartWorkflowInputDTO & AdditionalData>) => {
+  (input: WorkflowData<CreateCartWorkflowInput>) => {
     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,

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<string, unknown>
 
+  /**
+   * 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<string, unknown> | null
 }
 
@@ -49,33 +138,132 @@ export interface UpdateLineItemInCartWorkflowInputDTO {
   update: Partial<UpdateLineItemDTO>
 }
 
+/**
+ * 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<string, unknown>
 }
 
+/**
+ * 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<string, unknown>
 
+  /**
+   * The items to be added to the cart.
+   */
   items?: CreateCartCreateLineItemDTO[]
+
+  /**
+   * The promotional codes applied on the cart.
+   */
   promo_codes?: string[]
 }
 

packages/core/types/src/http/common/additional_data.ts

@@ -1,6 +1,8 @@
 /**
- * Represents the additional_data property accepted in HTTP
+ * Additional data, passed through the `additional_data` property accepted in HTTP
- * requests to allow arbitrary values
+ * 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<string, unknown>