[!WARNING] This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.

@86d-app/cart

Shopping cart module for guest and authenticated customers. Supports adding, updating, and removing items with configurable expiration and per-cart item limits.

Installation

npm install @86d-app/cart

Usage

import cart from "@86d-app/cart";

const module = cart({
  guestCartExpiration: 604800000, // 7 days in ms
  maxItemsPerCart: 100,
});

Configuration

| Option | Type | Default | Description | |---|---|---|---| | guestCartExpiration | number | 604800000 | Guest cart TTL in milliseconds (7 days) | | maxItemsPerCart | number | 100 | Maximum number of distinct items per cart |

Store Endpoints

| Method | Path | Description | |---|---|---| | POST | /cart | Add an item to the cart | | GET | /cart/get | Get the current cart with items and totals | | PATCH | /cart/items/:id/update | Update quantity of a cart item | | DELETE | /cart/items/:id/remove | Remove a single item from the cart | | POST | /cart/clear | Remove all items from the cart |

All store endpoints return a consistent shape:

{
  cart: Cart;
  items: CartItem[];
  itemCount: number;
  subtotal: number;
}

Admin Endpoints

| Method | Path | Description | |---|---|---| | GET | /admin/carts | List all carts (paginated) | | GET | /admin/carts/:id | Get a cart with its items | | DELETE | /admin/carts/:id/delete | Delete a cart |

Controller API

The CartController interface is exported for use in inter-module contracts (e.g. checkout referencing the cart).

interface CartController {
  /** Get an existing cart or create one for the given customer/guest */
  getOrCreateCart(params: {
    customerId?: string;
    guestId?: string;
  }): Promise<Cart>;

  /** Retrieve all items in a cart */
  getCartItems(cartId: string): Promise<CartItem[]>;

  /** Calculate the total price of all items in a cart */
  getCartTotal(cartId: string): Promise<number>;

  /** Check whether a product exists in any active cart */
  isProductInActiveCart(productId: string): Promise<boolean>;

  /** Add a product (or variant) to a cart */
  addItem(params: {
    cartId: string;
    productId: string;
    variantId?: string;
    quantity: number;
    price: number;
  }): Promise<CartItem>;

  /** Change the quantity of an existing cart item */
  updateItem(itemId: string, quantity: number): Promise<CartItem>;

  /** Remove a single item from a cart */
  removeItem(itemId: string): Promise<void>;

  /** Remove all items from a cart */
  clearCart(cartId: string): Promise<void>;
}

Types

interface Cart {
  id: string;
  customerId?: string;
  guestId?: string;
  status: "active" | "abandoned" | "converted";
  expiresAt: Date;
  metadata?: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

interface CartItem {
  id: string;
  cartId: string;
  productId: string;
  variantId?: string;
  quantity: number;
  /** Price snapshot at time of adding to cart (in cents) */
  price: number;
  metadata?: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

Notes

• Cart item IDs are deterministic: ${cartId}_${productId}[_${variantId}]. Adding the same product twice updates its quantity.
• Guest carts use a guestId; authenticated carts use a customerId. Both can coexist.
• The storage adapter is swappable — replace the default in-memory adapter with any persistence layer.