feat(cart): Public-facing DTOs + (partial) module interface (#6000)

packages/cart/src/models/cart.ts

@@ -8,6 +8,7 @@ import {
   OnInit,
   OneToMany,
   OneToOne,
+  OptionalProps,
   PrimaryKey,
   Property,
 } from "@mikro-orm/core"
@@ -22,6 +23,8 @@ type OptionalCartProps =
 
 @Entity({ tableName: "cart" })
 export default class Cart {
+  [OptionalProps]?: OptionalCartProps
+
   @PrimaryKey({ columnType: "text" })
   id: string
 

packages/cart/src/models/index.ts

@@ -1,5 +1,4 @@
 export { default as Address } from "./address"
-export { default as AdjustmentLine } from "./adjustment-line"
 export { default as Cart } from "./cart"
 export { default as LineItem } from "./line-item"
 export { default as LineItemAdjustmentLine } from "./line-item-adjustment-line"
@@ -7,5 +6,3 @@ export { default as LineItemTaxLine } from "./line-item-tax-line"
 export { default as ShippingMethod } from "./shipping-method"
 export { default as ShippingMethodAdjustmentLine } from "./shipping-method-adjustment-line"
 export { default as ShippingMethodTaxLine } from "./shipping-method-tax-line"
-export { default as TaxLine } from "./tax-line"
-

packages/cart/src/models/line-item.ts

@@ -11,7 +11,7 @@ import {
   OneToMany,
   OptionalProps,
   PrimaryKey,
-  Property
+  Property,
 } from "@mikro-orm/core"
 import Cart from "./cart"
 import LineItemAdjustmentLine from "./line-item-adjustment-line"

packages/cart/src/models/shipping-method.ts

@@ -28,7 +28,7 @@ export default class ShippingMethod {
   cart: Cart
 
   @Property({ columnType: "text" })
-  title: string
+  name: string
 
   @Property({ columnType: "jsonb", nullable: true })
   description?: string | null
@@ -38,7 +38,7 @@ export default class ShippingMethod {
   amount: number
 
   @Property({ columnType: "boolean" })
-  tax_inclusive = false
+  is_tax_inclusive = false
 
   @Property({ columnType: "text", nullable: true })
   shipping_option_id?: string | null

packages/cart/src/services/cart-module.ts

@@ -1,5 +1,4 @@
 import {
-  CartTypes,
   DAL,
   InternalModuleDeclaration,
   ModuleJoinerConfig,
@@ -13,10 +12,8 @@ type InjectedDependencies = {
   baseRepository: DAL.RepositoryService
 }
 
-export default class CartModuleService<
+// TODO: implement ICartModuleService from @medusajs/types
-  TCart extends Cart = Cart
+export default class CartModuleService<TCart extends Cart = Cart> {
-> implements CartTypes.ICartModuleService
-{
   protected baseRepository_: DAL.RepositoryService
 
   constructor(

packages/core-flows/src/handlers/cart/create-cart.ts

@@ -1,4 +1,4 @@
-import { AddressDTO, CartDTO, CustomerDTO, RegionDTO } from "@medusajs/types"
+import { AddressDTO, CustomerDTO, RegionDTO, legacy__CartDTO } from "@medusajs/types"
 import { WorkflowArguments } from "@medusajs/workflows-sdk"
 
 enum Aliases {
@@ -34,7 +34,7 @@ type HandlerInputData = {
 }
 
 type HandlerOutputData = {
-  cart: CartDTO
+  cart: legacy__CartDTO
 }
 
 export async function createCart({

packages/core-flows/src/handlers/cart/retrieve-cart.ts

@@ -1,4 +1,4 @@
-import { CartDTO } from "@medusajs/types"
+import { legacy__CartDTO } from "@medusajs/types"
 import { WorkflowArguments } from "@medusajs/workflows-sdk"
 
 type HandlerInputData = {
@@ -22,7 +22,7 @@ export async function retrieveCart({
   container,
   context,
   data,
-}: WorkflowArguments<HandlerInputData>): Promise<CartDTO> {
+}: WorkflowArguments<HandlerInputData>): Promise<legacy__CartDTO> {
   const { manager } = context
 
   const cartService = container.resolve("cartService")

packages/types/src/cart/common.ts

@@ -1,4 +1,476 @@
-export type CartDTO = {
+import { BaseFilterable } from "../dal"
+import { OperatorMap } from "../dal/utils"
+
+export interface AdjustmentLineDTO {
+  /**
+   * The ID of the adjustment line
+   */
+  id: string
+  /**
+   * The code of the adjustment line
+   */
+  code: string
+  /**
+   * The amount of the adjustment line
+   */
+  amount: number
+  /**
+   * The description of the adjustment line
+   */
+  description?: string
+  /**
+   * The ID of the associated promotion
+   */
+  promotion_id?: string
+  /**
+   * The ID of the associated provider
+   */
+  provider_id?: string
+  /**
+   * When the adjustment line was created
+   */
+  created_at: Date | string
+  /**
+   * When the adjustment line was updated
+   */
+  updated_at: Date | string
+}
+
+export interface ShippingMethodAdjustmentLineDTO extends AdjustmentLineDTO {
+  /**
+   * The associated shipping method
+   */
+  shipping_method: CartShippingMethodDTO
+}
+
+export interface LineItemAdjustmentLineDTO extends AdjustmentLineDTO {
+  /**
+   * The associated line item
+   */
+  line_item: CartLineItemDTO
+}
+
+export interface TaxLineDTO {
+  /**
+   * The ID of the tax line
+   */
+  id: string
+  /**
+   * The description of the tax line
+   */
+  description?: string
+  /**
+   * The ID of the associated tax rate
+   */
+  tax_rate_id?: string
+  /**
+   * The code of the tax line
+   */
+  code: string
+  /**
+   * The rate of the tax line
+   */
+  rate: number
+  /**
+   * The ID of the associated provider
+   */
+  provider_id?: string
+  /**
+   * When the tax line was created
+   */
+  created_at: Date | string
+  /**
+   * When the tax line was updated
+   */
+  updated_at: Date | string
+}
+
+export interface ShippingMethodTaxLineDTO extends TaxLineDTO {
+  /**
+   * The associated shipping method
+   */
+  shipping_method: CartShippingMethodDTO
+}
+
+export interface LineItemTaxLineDTO extends TaxLineDTO {
+  /**
+   * The associated line item
+   */
+  line_item: CartLineItemDTO
+}
+
+export interface CartAddressDTO {
+  /**
+   * The ID of the address
+   */
+  id: string
+  /**
+   * The customer ID of the address
+   */
+  customer_id?: string
+  /**
+   * The first name of the address
+   */
+  first_name?: string
+  /**
+   * The last name of the address
+   */
+  last_name?: string
+  /**
+   * The phone number of the address
+   */
+  phone?: string
+  /**
+   * The company of the address
+   */
+  company?: string
+  /**
+   * The first address line of the address
+   */
+  address_1?: string
+  /**
+   * The second address line of the address
+   */
+  address_2?: string
+  /**
+   * The city of the address
+   */
+  city?: string
+  /**
+   * The country code of the address
+   */
+  country_code?: string
+  /**
+   * The province/state of the address
+   */
+  province?: string
+  /**
+   * The postal code of the address
+   */
+  postal_code?: string
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown> | null
+  /**
+   * When the address was created.
+   */
+  created_at: Date | string
+  /**
+   * When the address was updated.
+   */
+  updated_at: Date | string
+}
+
+export interface CartShippingMethodDTO {
+  /**
+   * The ID of the shipping method
+   */
+  id: string
+
+  /**
+   * The name of the shipping method
+   */
+  name: string
+  /**
+   * The description of the shipping method
+   */
+  description?: string
+
+  /**
+   * The price of the shipping method
+   */
+  unit_price: number
+
+  /**
+   * Whether the shipping method price is tax inclusive or not
+   */
+  is_tax_inclusive: boolean
+
+  /**
+   * The ID of the shipping option the method was created from
+   */
+  shipping_option_id?: string
+
+  /**
+   * Additional data needed for fulfillment.
+   */
+  data?: Record<string, unknown>
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown> | null
+
+  /**
+   * The associated tax lines.
+   *
+   * @expandable
+   */
+  tax_lines?: ShippingMethodTaxLineDTO[]
+  /**
+   * The associated adjustments.
+   *
+   * @expandable
+   */
+  adjustments?: ShippingMethodAdjustmentLineDTO[]
+
+  /**
+   * When the shipping method was created.
+   */
+  created_at: Date | string
+  /**
+   * When the shipping method was updated.
+   */
+  updated_at: Date | string
+
+  original_total: number
+  original_subtotal: number
+  original_tax_total: number
+
+  total: number
+  subtotal: number
+  tax_total: number
+  discount_total: number
+  discount_tax_total: number
+}
+
+export interface CartLineItemDTO {
+  /**
+   * The ID of the line item.
+   */
+  id: string
+  /**
+   * The title of the line item.
+   */
+  title: string
+  /**
+   * The subtitle of the line item.
+   */
+  subtitle?: string
+  /**
+   * The url of the line item thumbnail.
+   */
+  thumbnail?: string
+  /**
+   * The line item quantity
+   */
+  quantity: number
+  /**
+   * The product ID of the line item.
+   */
+  product_id?: string
+  /**
+   * The product title of the line item.
+   */
+  product_title?: string
+  /**
+   * The product description of the line item.
+   */
+  product_description?: string
+  /**
+   * The product subtitle of the line item.
+   */
+  product_subtitle?: string
+  /**
+   * The product type of the line item.
+   */
+  product_type?: string
+  /**
+   * The product collection of the line item.
+   */
+  product_collection?: string
+  /**
+   * The product handle of the line item.
+   */
+  product_handle?: string
+  /**
+   * The variant ID of the line item.
+   */
+  variant_id?: string
+  /**
+   * The variant sku of the line item.
+   */
+  variant_sku?: string
+  /**
+   * The variant barcode of the line item.
+   */
+  variant_barcode?: string
+  /**
+   * The variant title of the line item.
+   */
+  variant_title?: string
+  /**
+   * The variant option values of the line item.
+   */
+  variant_option_values?: Record<string, unknown>
+  /**
+   * Whether the line item requires shipping or not
+   */
+  requires_shipping: boolean
+  /**
+   * Whether the line item is discountable or not
+   */
+  is_discountable: boolean
+  /**
+   * Whether the line item price is tax inclusive or not
+   */
+  is_tax_inclusive: boolean
+  /**
+   * The original price of the item before an adjustment or a sale.
+   */
+  compare_at_unit_price?: number
+  /**
+   * The price of the item
+   */
+  unit_price: number
+  /**
+   * The associated tax lines.
+   *
+   * @expandable
+   */
+  tax_lines?: LineItemTaxLineDTO[]
+  /**
+   * The associated adjustments.
+   *
+   * @expandable
+   */
+  adjustments?: LineItemAdjustmentLineDTO[]
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown> | null
+  /**
+   * When the line item was created.
+   */
+  created_at?: Date
+  /**
+   * When the line item was updated.
+   */
+  updated_at?: Date
+
+  original_total: number
+  original_subtotal: number
+  original_tax_total: number
+
+  item_total: number
+  item_subtotal: number
+  item_tax_total: number
+
+  total: number
+  subtotal: number
+  tax_total: number
+  discount_total: number
+  discount_tax_total: number
+}
+
+export interface CartDTO {
+  /**
+   * The ID of the cart.
+   */
+  id: string
+  /**
+   * The ID of the region the cart belongs to.
+   */
+  region_id?: string
+  /**
+   * The ID of the customer on the cart.
+   */
+  customer_id?: string
+  /**
+   * The ID of the sales channel the cart belongs to.
+   */
+  sales_channel_id?: string
+  /**
+   * The email of the cart.
+   */
+  email?: string
+  /**
+   * The currency of the cart
+   */
+  currency_code: string
+  /**
+   * The associated shipping address.
+   *
+   * @expandable
+   */
+  shipping_address?: CartAddressDTO
+  /**
+   * The associated billing address.
+   *
+   * @expandable
+   */
+  billing_address?: CartAddressDTO
+  /**
+   * The associated line items.
+   *
+   * @expandable
+   */
+  items?: CartLineItemDTO[]
+  /**
+   * The associated shipping methods
+   *
+   * @expandable
+   */
+  shipping_methods?: CartShippingMethodDTO[]
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown> | null
+  /**
+   * When the cart was created.
+   */
+  created_at?: string | Date
+  /**
+   * When the cart was updated.
+   */
+  updated_at?: string | Date
+
+  original_item_total: number
+  original_item_subtotal: number
+  original_item_tax_total: number
+
+  item_total: number
+  item_subtotal: number
+  item_tax_total: number
+
+  original_total: number
+  original_subtotal: number
+  original_tax_total: number
+
+  total: number
+  subtotal: number
+  tax_total: number
+  discount_total: number
+  discount_tax_total: number
+
+  shipping_total: number
+  shipping_subtotal: number
+  shipping_tax_total: number
+
+  original_shipping_total: number
+  original_shipping_subtotal: number
+  original_shipping_tax_total: number
+}
+
+export interface FilterableCartProps
+  extends BaseFilterable<FilterableCartProps> {
+  id?: string | string[]
+
+  sales_channel_id?: string | string[] | OperatorMap<string>
+  customer_id?: string | string[] | OperatorMap<string>
+  region_id?: string | string[] | OperatorMap<string>
+
+  created_at?: OperatorMap<string>
+  updated_at?: OperatorMap<string>
+}
+
+/**
+ * TODO: Remove this in favor of new__CartDTO, when module is released 
+ * @deprecated Use CartDTO instead
+ */
+ 
+export type legacy__CartDTO = {
   id?: string
   email?: string
   billing_address_id?: string

packages/types/src/cart/index.ts

@@ -1,3 +1,4 @@
 export * from "./common"
+export * from "./mutations"
 export * from "./service"
 

packages/types/src/cart/mutations.ts

@@ -0,0 +1,133 @@
+export interface UpsertAddressDTO {
+  customer_id?: string
+  company?: string
+  first_name?: string
+  last_name?: string
+  address_1?: string
+  address_2?: string
+  city?: string
+  country_code?: string
+  province?: string
+  postal_code?: string
+  phone?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface UpdateAddressDTO extends UpsertAddressDTO {
+  id: string
+}
+
+export interface CreateAddressDTO extends UpsertAddressDTO {}
+
+export interface CreateCartDTO {
+  region_id?: string
+  customer_id?: string
+  sales_channel_id?: string
+
+  email?: string
+  currency_code: string
+
+  shipping_address?: CreateAddressDTO | UpdateAddressDTO
+  billing_address?: CreateAddressDTO | UpdateAddressDTO
+
+  metadata?: Record<string, unknown>
+}
+
+export interface UpdateCartDTO {
+  id: string
+  region_id?: string
+  customer_id?: string
+  sales_channel_id?: string
+
+  email?: string
+  currency_code?: string
+
+  billing_address?: CreateAddressDTO | UpdateAddressDTO
+  shipping_address?: CreateAddressDTO | UpdateAddressDTO
+
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateLineItemTaxLineDTO {
+  description?: string
+  tax_rate_id?: string
+  code: string
+  rate: number
+  provider_id?: string
+}
+
+export interface CreateLineItemAdjustmentDTO {
+  code: string
+  amount: number
+  description?: string
+  promotion_id?: string
+  provider_id?: string
+}
+
+export interface UpdateLineItemTaxLineDTO {
+  id: string
+  description?: string
+  tax_rate_id?: string
+  code?: string
+  rate?: number
+  provider_id?: string
+}
+
+export interface UpdateLineItemAdjustmentDTO {
+  id: string
+  code?: string
+  amount?: number
+  description?: string
+  promotion_id?: string
+  provider_id?: string
+}
+
+export interface CreateLineItemDTO {
+  title: string
+  subtitle?: string
+  thumbnail?: string
+
+  quantity: number
+
+  product_id?: string
+  product_title?: string
+  product_description?: string
+  product_subtitle?: string
+  product_type?: string
+  product_collection?: string
+  product_handle?: string
+
+  variant_id?: string
+  variant_sku?: string
+  variant_barcode?: string
+  variant_title?: string
+  variant_option_values?: Record<string, unknown>
+
+  requires_shipping?: boolean
+  is_discountable?: boolean
+  is_tax_inclusive?: boolean
+
+  compare_at_unit_price?: number
+  unit_price: number
+
+  tax_lines: CreateLineItemTaxLineDTO[]
+  adjustments: CreateLineItemAdjustmentDTO[]
+}
+
+export interface UpdateLineItemDTO
+  extends Omit<CreateLineItemDTO, "tax_lines" | "adjustments"> {
+  id: string
+
+  tax_lines: UpdateLineItemTaxLineDTO[] | CreateLineItemTaxLineDTO[]
+  adjustments: UpdateLineItemAdjustmentDTO[] | CreateLineItemAdjustmentDTO[]
+}
+
+export interface AddLineItemsDTO {
+  cart_id: string
+  items: CreateLineItemDTO[]
+}
+
+export interface UpdateLineItemsDTO {
+  cart_id: string
+  items: UpdateLineItemDTO[]
+}

packages/types/src/cart/service.ts

@@ -1,4 +1,48 @@
-import { IModuleService } from "../modules-sdk";
+import { FindConfig } from "../common"
+import { IModuleService } from "../modules-sdk"
+import { Context } from "../shared-context"
+import { CartDTO, FilterableCartProps } from "./common"
+import { AddLineItemsDTO, CreateCartDTO, UpdateCartDTO, UpdateLineItemsDTO } from "./mutations"
 
 export interface ICartModuleService extends IModuleService {
+  retrieve(
+    cartId: string,
+    config?: FindConfig<CartDTO>,
+    sharedContext?: Context
+  ): Promise<CartDTO>
+
+  list(
+    filters?: FilterableCartProps,
+    config?: FindConfig<CartDTO>,
+    sharedContext?: Context
+  ): Promise<CartDTO[]>
+
+  listAndCount(
+    filters?: FilterableCartProps,
+    config?: FindConfig<CartDTO>,
+    sharedContext?: Context
+  ): Promise<[CartDTO[], number]>
+
+  create(data: CreateCartDTO[], sharedContext?: Context): Promise<CartDTO[]>
+
+  update(data: UpdateCartDTO[], sharedContext?: Context): Promise<CartDTO[]>
+
+  delete(cartIds: string[], sharedContext?: Context): Promise<void>
+
+  addLineItems(data: AddLineItemsDTO, sharedContext?: Context): Promise<CartDTO>
+  addLineItems(
+    data: AddLineItemsDTO[],
+    sharedContext?: Context
+  ): Promise<CartDTO[]>
+
+  updateLineItems(
+    data: UpdateLineItemsDTO,
+    sharedContext?: Context
+  ): Promise<CartDTO>
+  updateLineItems(
+    data: UpdateLineItemsDTO[],
+    sharedContext?: Context
+  ): Promise<CartDTO[]>
+
+  removeLineItems(lineItemIds: string[], sharedContext?: Context): Promise<void>
 }