@automattic/shopping-cart v2.0.0

Shopping Cart

This is a library for accessing the WordPress.com shopping cart.

An older version of this interface exists in calypso's lib/cart directory, but that version is deprecated.

This package provides the following API, as well as a comprehensive set of TypeScript types for the data passed through the cart. Notably, the whole cart object itself is a ResponseCart containing ResponseCartProduct objects. If adding a new product, the RequestCart and RequestCartProduct can be used instead (they have fewer required properties).

ShoppingCartProvider

A React context provider component which should be used near the top level of the render tree to grant access to the shopping cart to the components in the tree via the useShoppingCart hook or the withShoppingCart higher-order-component.

It requires three props:

• cartKey: string | number | undefined | null. Every cart is keyed by a cart key; usually this is the WordPress.com site ID (preferred, because it is always unique) or site slug. It can also be 'no-site' or 'no-user'. If undefined or null, the cart will not be loaded and the isLoading value will be true; this can be used to temporarily disable the cart.
• getCart: ( cartKey: string ) => Promise< ResponseCart >. This is an async function that will fetch the cart from the server.
• setCart: ( cartKey: string, requestCart: RequestCart ) => Promise< ResponseCart >. This is an async function that will send an updated cart to the server.
• options?: { refetchOnWindowFocus?: boolean }. Optional. Can be used to trigger getCart when the window or tab is hidden and then refocused.

useShoppingCart

This is a React hook that can be used in any child component under ShoppingCartProvider to return a ShoppingCartManager object. That object contains the following properties. Note that the action functions in this object are requests only; they do not guarantee that the request will be fulfilled by the shopping cart API.

• responseCart: ResponseCart. The full cart object itself. For this object's API, see the TypeScript type. This object should be considered read-only. To make changes to the cart, use the action functions in ShoppingCartManager like addProductsToCart.
• isLoading: boolean. True if the cart is still loading from the server. This will only be true during the initial load for a cartKey or when the cartKey is undefined|null. When updating an existing cart, isPendingUpdate will be true instead.
• isPendingUpdate: boolean. True if the cart is loading in any way, either during its initial load, when a cartKey changes, or when a modification request is pending.
• loadingError: string | null | undefined. If fetching or updating the cart causes an error, this will be a string that contains the error message.
• loadingErrorType: ShoppingCartError | undefined. If fetching or updating the cart causes an error, this will contain a string that explains what type of error.
• `couponStatus: 'fresh' | 'pending' | 'applied' | 'rejected'. A string that can be used to determine if a coupon is applied.

The following actions are also properties. Each one returns a Promise that resolves when the cart is next valid (this may be after several queued actions are complete).

• addProductsToCart: ( products: RequestCartProduct[] ) => Promise<ResponseCart>. A function that requests adding new products to the cart. May cause the cart to be replaced instead, depending on the RequestCartProducts (mostly renewals and non-renewals cannot co-exist in the cart at the same time).
• removeProductFromCart: ( uuidToRemove: string ) => Promise<ResponseCart>. A function that requests removing a product from the cart.
• applyCoupon: ( couponId: string ) => Promise<ResponseCart>. A function that requests applying a coupon to the cart (only one coupon can be applied at a time).
• removeCoupon: () => Promise<ResponseCart>. A function that requests removing a coupon to the cart.
• updateLocation: ( location: CartLocation ) => Promise<ResponseCart>. A function that can be used to change the tax location of the cart.
• replaceProductInCart: ( uuidToReplace: string, productPropertiesToChange: Partial< RequestCartProduct > ) => Promise<ResponseCart>. A function that can replace one product in the cart with another, retaining the same UUID; useful for changing product variants.
• replaceProductsInCart: ( products: RequestCartProduct[] ) => Promise<ResponseCart>. A function that replaces all the products in the cart with a new set of products. Can also be used to clear the cart.
• reloadFromServer: () => Promise<ResponseCart>. A function to throw away the current cart cache and fetch it fresh from the shopping cart API.

withShoppingCart

A React HOC (higher order component) that can be used to inject the ShoppingCartManager into another component as a prop called shoppingCartManager. For convenience, since the most common use-case for accessing this package is to get a copy of the cart, it also adds a prop called cart, which is equal to shoppingCartManager.responseCart.

createRequestCartProduct

A helper function that creates a RequestCartProduct, which can then be passed to shopping cart functions like addProductsToCart().

It takes one argument, an object which contains some or all of the properties in a RequestCartProduct, but must contain at least product_slug and product_id. The remaining properties, if not set, will be filled with the default values.

getEmptyResponseCart

A function that returns an empty but valid ResponseCart object. Useful for tests where we need to mock the shopping cart response.

getEmptyResponseCartProduct

A function that returns an empty but valid ResponseCartProduct object. Useful for tests where we need to mock the shopping cart response.

convertResponseCartToRequestCart

A function that converts a ResponseCart to a RequestCart. Usually this should be handled by the shopping cart manager but if you need to manupulate a cart object manually this may be helpful.