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

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