add better comments

https://coveord.atlassian.net/browse/KIT-3681

packages/samples/headless-ssr-commerce/actions/cart.ts → packages/samples/headless-ssr-commerce/actions/external-cart-api.ts

@@ -15,6 +15,15 @@ function setCartInCookies(cart: CartItem[]) {
   });
 }
 
+/**
+ * IMPORTANT: The functions exported in this module are meant to simulate a programming interface that interacts
+ * with a cart managed through an external ecommerce system.
+ *
+ * For the sake of simplicity, we substitute the "ecommerce system" with a browser cookie in this
+ * example. This is obviously an abstraction. In a real-life scenario, you would interact with an
+ * external service to retrieve and update the cart state.
+ */
+
 export async function getCart(): Promise<CartItem[]> {
   return getCartFromCookies();
 }

packages/samples/headless-ssr-commerce/app/cart/page.tsx

@@ -1,4 +1,4 @@
-import {getCart} from '@/actions/cart';
+import * as externalCartAPI from '@/actions/external-cart-api';
 import Cart from '@/components/cart';
 import SearchProvider from '@/components/providers/search-provider';
 import {searchEngineDefinition} from '@/lib/commerce-engine';
@@ -11,7 +11,7 @@ export default async function Search() {
   searchEngineDefinition.setNavigatorContextProvider(() => navigatorContext);
 
   // Fetches the cart items from an external service
-  const items = await getCart();
+  const items = await externalCartAPI.getCart();
 
   // Fetches the static state of the app with initial state (when applicable)
   const staticState = await searchEngineDefinition.fetchStaticState({

packages/samples/headless-ssr-commerce/app/layout.tsx

@@ -15,7 +15,6 @@ export default function RootLayout({children}: {children: React.ReactNode}) {
           <Link href={'/listing'}>Listing Page</Link>
           <Link href={'/cart'}>Cart Page</Link>
         </div>
-
         {children}
       </body>
     </html>

packages/samples/headless-ssr-commerce/app/listing/page.tsx

@@ -1,4 +1,4 @@
-import {getCart} from '@/actions/cart';
+import * as externalCartAPI from '@/actions/external-cart-api';
 import BreadcrumbManager from '@/components/breadcrumb-manager';
 import Cart from '@/components/cart';
 import FacetGenerator from '@/components/facets/facet-generator';
@@ -24,7 +24,7 @@ export default async function Listing() {
   listingEngineDefinition.setNavigatorContextProvider(() => navigatorContext);
 
   // Fetches the cart items from an external service
-  const items = await getCart();
+  const items = await externalCartAPI.getCart();
 
   // Fetches the static state of the app with initial state (when applicable)
   const staticState = await listingEngineDefinition.fetchStaticState({

packages/samples/headless-ssr-commerce/app/products/[productId]/page.tsx

@@ -1,4 +1,4 @@
-import {getCart} from '@/actions/cart';
+import * as externalCartAPI from '@/actions/external-cart-api';
 import ProductPage from '@/components/pages/product-page';
 import {searchEngineDefinition} from '@/lib/commerce-engine';
 import {NextJsNavigatorContext} from '@/lib/navigatorContextProvider';
@@ -15,7 +15,7 @@ export default async function ProductDescriptionPage({
   searchEngineDefinition.setNavigatorContextProvider(() => navigatorContext);
 
   // Fetches the cart items from an external service
-  const items = await getCart();
+  const items = await externalCartAPI.getCart();
 
   // Fetches the static state of the app with initial state (when applicable)
   const staticState = await searchEngineDefinition.fetchStaticState({

packages/samples/headless-ssr-commerce/app/search/page.tsx

@@ -1,4 +1,4 @@
-import {getCart} from '@/actions/cart';
+import * as externalCartAPI from '@/actions/external-cart-api';
 import BreadcrumbManager from '@/components/breadcrumb-manager';
 import FacetGenerator from '@/components/facets/facet-generator';
 import ProductList from '@/components/product-list';
@@ -18,7 +18,7 @@ export default async function Search() {
   searchEngineDefinition.setNavigatorContextProvider(() => navigatorContext);
 
   // Fetches the cart items from an external service
-  const items = await getCart();
+  const items = await externalCartAPI.getCart();
 
   // Fetches the static state of the app with initial state (when applicable)
   const staticState = await searchEngineDefinition.fetchStaticState({

packages/samples/headless-ssr-commerce/utils/cart.ts

@@ -1,40 +1,54 @@
-import {addItemToCart, clearCart, updateItemQuantity} from '@/actions/cart';
-import {Cart, CartItem, Product} from '@coveo/headless-react/ssr-commerce';
+import * as externalCartAPI from '@/actions/external-cart-api';
+import {
+  Cart as HeadlessCart,
+  CartItem as HeadlessCartItem,
+  Product as HeadlessProduct,
+} from '@coveo/headless-react/ssr-commerce';
 
-type SSRCart = Omit<Cart, 'state' | 'subscribe'>;
+type HeadlessSSRCart = Omit<HeadlessCart, 'state' | 'subscribe'>;
 
 export async function adjustQuantity(
-  cart: SSRCart,
-  item: CartItem,
+  headlessCart: HeadlessSSRCart,
+  item: HeadlessCartItem,
   delta: number
 ) {
   const updatedItem = {
     ...item,
     quantity: item.quantity + delta,
   };
 
-  cart.updateItemQuantity(updatedItem);
-  await updateItemQuantity(updatedItem);
+  headlessCart.updateItemQuantity(updatedItem);
+  // Update the item in the external service
+  await externalCartAPI.updateItemQuantity(updatedItem);
 }
 
-export async function addToCart(cart: SSRCart, product: Product) {
+export async function addToCart(
+  headlessCart: HeadlessSSRCart,
+  product: HeadlessProduct
+) {
   const item = {
     name: product.ec_name!,
     price: product.ec_price!,
     productId: product.ec_product_id!,
     quantity: 1,
   };
 
-  cart.updateItemQuantity(item);
-  await addItemToCart(item);
+  headlessCart.updateItemQuantity(item);
+  // Add the item to the external service
+  await externalCartAPI.addItemToCart(item);
 }
 
-export async function purchase(cart: SSRCart, totalPrice: number) {
-  cart.purchase({id: crypto.randomUUID(), revenue: totalPrice});
-  await clearCart();
+export async function purchase(
+  headlessCart: HeadlessSSRCart,
+  totalPrice: number
+) {
+  headlessCart.purchase({id: crypto.randomUUID(), revenue: totalPrice});
+  // Clear the cart in the external service
+  await externalCartAPI.clearCart();
 }
 
-export async function emptyCart(cart: SSRCart) {
-  cart.empty();
-  await clearCart();
+export async function emptyCart(headlessCart: HeadlessSSRCart) {
+  headlessCart.empty();
+  // Clear the cart in the external service
+  await externalCartAPI.clearCart();
 }