@shopkit/cart 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,730 @@
+import * as zustand from 'zustand';
+
+/**
+ * @shopkit/cart - Cart Module Types
+ *
+ * Single source of truth for all cart-related types and interfaces.
+ * This module is designed to be merchant-agnostic and package-ready.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Represents an item in the shopping cart.
+ *
+ * @example
+ * ```typescript
+ * const item: CartItem = {
+ *   id: "gid://shopify/CartLine/123",
+ *   productId: "gid://shopify/Product/456",
+ *   variantId: "gid://shopify/ProductVariant/789",
+ *   title: "Premium T-Shirt",
+ *   quantity: 2,
+ *   price: { amount: 29.99, currencyCode: "USD" },
+ *   image: "https://example.com/image.jpg"
+ * };
+ * ```
+ */
+interface CartItem {
+    /** Unique identifier for the cart line item */
+    id: string;
+    /** Product identifier */
+    productId: string;
+    /** Optional variant identifier */
+    variantId?: string;
+    /** Product title */
+    title: string;
+    /** Current price of the item */
+    price: {
+        amount: number;
+        currencyCode: string;
+    };
+    /** Original price before discounts (for showing savings) */
+    compareAtPrice?: {
+        amount: number;
+        currencyCode: string;
+    };
+    /** Quantity of this item in cart */
+    quantity: number;
+    /** Product image URL */
+    image?: string;
+    /** Product vendor/brand */
+    vendor?: string;
+}
+/**
+ * Request payload for adding/updating cart items.
+ * Used when communicating with the cart service.
+ */
+interface CartItemRequest {
+    /** Product identifier */
+    productId: string;
+    /** Variant identifier */
+    variantId: string;
+    /** Quantity to add/set */
+    quantity: number;
+}
+/**
+ * Response from cart API operations.
+ * Contains the full cart state after an operation.
+ */
+interface CartResponse {
+    /** Cart identifier */
+    id: string;
+    /** Items currently in the cart */
+    items: CartItem[];
+    /** Subtotal before discounts */
+    subtotal?: {
+        amount: number;
+        currencyCode: string;
+    };
+    /** Total amount after discounts */
+    totalAmount?: {
+        amount: number;
+        currencyCode: string;
+    };
+    /** URL to proceed to checkout */
+    checkoutUrl?: string;
+    /** Timestamp when cart was created */
+    createdAt?: string;
+    /** Timestamp when cart was last updated */
+    updatedAt?: string;
+    [key: string]: any;
+}
+/**
+ * Interface for cart service implementations.
+ * Implement this interface to create custom cart backends.
+ *
+ * @example
+ * ```typescript
+ * class MyCartService implements ICartService {
+ *   async createCart(merchantName: string): Promise<CartResponse> {
+ *     // Your implementation
+ *   }
+ *   async getCart(cartId: string): Promise<CartResponse> {
+ *     // Your implementation
+ *   }
+ *   // ... other methods
+ * }
+ * ```
+ */
+interface ICartService {
+    /**
+     * Create a new cart for the given merchant.
+     * @param merchantName - Unique identifier for the merchant
+     * @returns The newly created cart
+     */
+    createCart(merchantName: string): Promise<CartResponse>;
+    /**
+     * Retrieve an existing cart by ID.
+     * @param cartId - The cart identifier
+     * @returns The cart data
+     */
+    getCart(cartId: string): Promise<CartResponse>;
+    /**
+     * Add items to the cart.
+     * @param cartId - The cart identifier
+     * @param items - Array of items to add
+     */
+    addToCart(cartId: string, items: CartItemRequest[]): Promise<void>;
+    /**
+     * Remove items from the cart.
+     * @param cartId - The cart identifier
+     * @param itemIds - Array of cart line item IDs to remove
+     */
+    removeFromCart(cartId: string, itemIds: string[]): Promise<void>;
+    /**
+     * Update item quantities in the cart.
+     * @param cartId - The cart identifier
+     * @param items - Array of items with updated quantities
+     */
+    updateCart(cartId: string, items: CartItemRequest[]): Promise<void>;
+}
+/**
+ * Interface for cart storage implementations.
+ * Implement this interface to customize how cart IDs are persisted.
+ *
+ * @example
+ * ```typescript
+ * class CookieCartStorage implements ICartStorage {
+ *   getCartId(): string | null {
+ *     return getCookie('cart-id');
+ *   }
+ *   setCartId(cartId: string): void {
+ *     setCookie('cart-id', cartId);
+ *   }
+ *   // ... other methods
+ * }
+ * ```
+ */
+interface ICartStorage {
+    /**
+     * Get the stored cart ID.
+     * @returns The cart ID or null if not found
+     */
+    getCartId(): string | null;
+    /**
+     * Store the cart ID.
+     * @param cartId - The cart ID to store
+     */
+    setCartId(cartId: string): void;
+    /**
+     * Remove the stored cart ID.
+     */
+    removeCartId(): void;
+    /**
+     * Clear all cart-related storage.
+     */
+    clear(): void;
+}
+/**
+ * Configuration options for the cart module.
+ * Pass to `configureCart()` at app initialization.
+ *
+ * @example
+ * ```typescript
+ * const config: CartConfig = {
+ *   merchantName: "my-store",
+ *   cartService: new DefaultCartService("/api/cart"),
+ *   cartStorage: new DefaultCartStorage("my-store"),
+ *   defaultCurrencyCode: "USD",
+ *   onCartEvent: (event) => console.log("Cart event:", event),
+ * };
+ * configureCart(config);
+ * ```
+ */
+interface CartConfig {
+    /** Unique identifier for the merchant/store */
+    merchantName: string;
+    /** Service instance for cart API operations */
+    cartService: ICartService;
+    /** Storage instance for cart persistence */
+    cartStorage: ICartStorage;
+    /** Default currency code for price formatting (default: "USD") */
+    defaultCurrencyCode?: string;
+    /** Optional callback for cart events (analytics, logging, etc.) */
+    onCartEvent?: (event: CartEvent) => void;
+}
+/**
+ * Events emitted by the cart store.
+ * Subscribe via the `onCartEvent` callback in CartConfig.
+ */
+type CartEvent = {
+    type: "CART_INITIALIZED";
+    cartId: string;
+} | {
+    type: "ADD_TO_CART";
+    item: CartItem;
+} | {
+    type: "REMOVE_FROM_CART";
+    item: CartItem;
+} | {
+    type: "UPDATE_QUANTITY";
+    item: CartItem;
+    previousQuantity: number;
+} | {
+    type: "CLEAR_CART";
+    itemCount: number;
+} | {
+    type: "CART_OPENED";
+} | {
+    type: "CART_CLOSED";
+} | {
+    type: "CART_ERROR";
+    action: string;
+    error: string;
+};
+/**
+ * The state shape of the cart store.
+ * Access via `useCartStore()` hook.
+ */
+interface CartState {
+    /** Items currently in the cart */
+    items: CartItem[];
+    /** Whether the cart drawer/modal is open */
+    isOpen: boolean;
+    /** Whether a cart operation is in progress */
+    isLoading: boolean;
+    /** Current error message, if any */
+    error: string | null;
+    /** Current cart identifier */
+    cartId: string | null;
+    /** URL to proceed to checkout */
+    checkoutUrl?: string;
+    /** Server-calculated total amount */
+    totalAmount?: {
+        amount: number;
+        currencyCode: string;
+    };
+    /** Whether the cart has been initialized */
+    isInitialized: boolean;
+}
+/**
+ * Actions available on the cart store.
+ */
+interface CartActions {
+    /**
+     * Initialize the cart. Restores from storage or creates new.
+     * @param merchantName - Optional merchant name override
+     */
+    initializeCart: (merchantName?: string) => Promise<void>;
+    /**
+     * Add a single item to the cart.
+     * @param item - The cart item to add
+     */
+    addItem: (item: CartItem) => Promise<void>;
+    /**
+     * Add multiple items to the cart.
+     * @param items - Array of items to add
+     */
+    addItems: (items: CartItemRequest[]) => Promise<void>;
+    /**
+     * Remove an item from the cart.
+     * @param lineId - Cart line item ID
+     * @param variantId - Optional variant ID for identification
+     */
+    removeItem: (lineId: string, variantId?: string) => Promise<void>;
+    /**
+     * Update the quantity of an item.
+     * @param lineId - Cart line item ID
+     * @param quantity - New quantity
+     * @param variantId - Optional variant ID for identification
+     */
+    updateItemQuantity: (lineId: string, quantity: number, variantId?: string) => Promise<void>;
+    /**
+     * Clear all items from the cart.
+     */
+    clearCart: () => Promise<void>;
+    /**
+     * Open the cart drawer/modal.
+     */
+    openCart: () => Promise<void>;
+    /**
+     * Close the cart drawer/modal.
+     */
+    closeCart: () => void;
+    /**
+     * Toggle the cart drawer/modal open/closed.
+     */
+    toggleCart: () => Promise<void>;
+}
+
+/**
+ * Configure the cart module with required services.
+ * Must be called before using the cart store.
+ */
+declare function configureCart(config: CartConfig): void;
+/**
+ * Get the current cart configuration.
+ * Throws if cart is not configured.
+ */
+declare function getCartConfig(): CartConfig;
+/**
+ * Check if cart is configured.
+ */
+declare function isCartConfigured(): boolean;
+declare const useCartStore: zustand.UseBoundStore<zustand.StoreApi<CartState & CartActions>>;
+
+/**
+ * Hook to get the number of unique items in the cart.
+ *
+ * @returns The count of unique items (not total quantity)
+ *
+ * @example
+ * ```tsx
+ * function CartBadge() {
+ *   const count = useCartCount();
+ *   return <span>{count} items</span>;
+ * }
+ * ```
+ */
+declare const useCartCount: () => number;
+/**
+ * Hook to get the total quantity of all items in the cart.
+ * This sums up quantities across all items.
+ *
+ * @returns The sum of all item quantities
+ *
+ * @example
+ * ```tsx
+ * function CartIcon() {
+ *   const totalQty = useCartTotalQuantity();
+ *   return <Badge count={totalQty}><ShoppingCart /></Badge>;
+ * }
+ * ```
+ */
+declare const useCartTotalQuantity: () => number;
+/**
+ * Hook to get all cart items.
+ *
+ * @returns Array of cart items
+ *
+ * @example
+ * ```tsx
+ * function CartItemsList() {
+ *   const items = useCartItems();
+ *   return (
+ *     <ul>
+ *       {items.map(item => (
+ *         <li key={item.id}>{item.title} x {item.quantity}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare const useCartItems: () => CartItem[];
+/**
+ * Hook to get the cart toggle function.
+ * Call the returned function to toggle cart open/closed.
+ *
+ * @returns Function to toggle cart visibility
+ *
+ * @example
+ * ```tsx
+ * function CartButton() {
+ *   const toggleCart = useCartToggle();
+ *   return <button onClick={toggleCart}>Toggle Cart</button>;
+ * }
+ * ```
+ */
+declare const useCartToggle: () => () => Promise<void>;
+/**
+ * Hook to get cart status information.
+ *
+ * @returns Object with isOpen, isLoading, error, cartId, and isInitialized
+ *
+ * @example
+ * ```tsx
+ * function CartStatus() {
+ *   const { isOpen, isLoading, error } = useCartStatus();
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <Error message={error} />;
+ *   return <div>Cart is {isOpen ? 'open' : 'closed'}</div>;
+ * }
+ * ```
+ */
+declare const useCartStatus: () => {
+    isOpen: boolean;
+    isLoading: boolean;
+    error: string | null;
+    cartId: string | null;
+    isInitialized: boolean;
+};
+/**
+ * Hook to calculate cart total from items (client-side calculation).
+ * This is a quick calculation that doesn't account for server-side discounts.
+ *
+ * @returns The calculated total price
+ *
+ * @example
+ * ```tsx
+ * function CartSubtotal() {
+ *   const total = useCartTotal();
+ *   return <span>Subtotal: ${total.toFixed(2)}</span>;
+ * }
+ * ```
+ */
+declare const useCartTotal: () => number;
+/**
+ * Hook to get the server-calculated total amount.
+ * This includes any discounts applied server-side.
+ *
+ * @returns The total amount object with amount and currencyCode, or undefined
+ *
+ * @example
+ * ```tsx
+ * function CartTotal() {
+ *   const totalAmount = useCartTotalAmount();
+ *   if (!totalAmount) return null;
+ *   return <span>Total: {formatPrice(totalAmount.amount, totalAmount.currencyCode)}</span>;
+ * }
+ * ```
+ */
+declare const useCartTotalAmount: () => {
+    amount: number;
+    currencyCode: string;
+} | undefined;
+/**
+ * Hook to check if a product/variant is in the cart.
+ *
+ * @param productId - The product ID to check
+ * @param variantId - Optional variant ID for more specific check
+ * @returns True if the product (and optionally variant) is in the cart
+ *
+ * @example
+ * ```tsx
+ * function ProductCard({ product }) {
+ *   const inCart = useIsInCart(product.id);
+ *   return (
+ *     <button disabled={inCart}>
+ *       {inCart ? 'In Cart' : 'Add to Cart'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const useIsInCart: (productId: string, variantId?: string) => boolean;
+/**
+ * Hook to get a specific cart item by product/variant ID.
+ *
+ * @param productId - The product ID to find
+ * @param variantId - Optional variant ID for more specific search
+ * @returns The cart item if found, undefined otherwise
+ *
+ * @example
+ * ```tsx
+ * function ProductQuantity({ productId }) {
+ *   const item = useCartItem(productId);
+ *   return item ? <span>Qty: {item.quantity}</span> : null;
+ * }
+ * ```
+ */
+declare const useCartItem: (productId: string, variantId?: string) => CartItem | undefined;
+/**
+ * Hook to get the checkout URL.
+ *
+ * @returns The checkout URL or undefined
+ *
+ * @example
+ * ```tsx
+ * function CheckoutButton() {
+ *   const checkoutUrl = useCheckoutUrl();
+ *   return checkoutUrl ? (
+ *     <a href={checkoutUrl}>Proceed to Checkout</a>
+ *   ) : null;
+ * }
+ * ```
+ */
+declare const useCheckoutUrl: () => string | undefined;
+
+interface UseAddToCartOptions {
+    onSuccess?: (item: CartItem) => void;
+    onError?: (error: Error) => void;
+    defaultCurrencyCode?: string;
+}
+/**
+ * Hook for adding products to the cart with loading state management.
+ */
+declare function useAddToCart(options?: UseAddToCartOptions): {
+    addToCart: (product: any, variantId?: string, customQuantity?: number) => Promise<void>;
+    loadingStates: Record<string, boolean>;
+    isLoading: (productId: string) => boolean;
+};
+
+/**
+ * Default cart service implementation using fetch API.
+ * Makes HTTP requests to cart API endpoints.
+ */
+declare class DefaultCartService implements ICartService {
+    private baseUrl;
+    constructor(baseUrl?: string);
+    private makeRequest;
+    private handleResponse;
+    createCart(merchantName: string): Promise<CartResponse>;
+    getCart(cartId: string): Promise<CartResponse>;
+    addToCart(cartId: string, items: CartItemRequest[]): Promise<void>;
+    removeFromCart(cartId: string, itemIds: string[]): Promise<void>;
+    updateCart(cartId: string, items: CartItemRequest[]): Promise<void>;
+}
+
+/**
+ * Default cart storage implementation using localStorage.
+ * Provides namespaced storage for multi-tenant support.
+ */
+declare class DefaultCartStorage implements ICartStorage {
+    private merchantName;
+    constructor(merchantName?: string);
+    private getStorageKey;
+    private get;
+    private set;
+    private remove;
+    getCartId(): string | null;
+    setCartId(cartId: string): void;
+    removeCartId(): void;
+    clear(): void;
+}
+
+/**
+ * Data-Layer Cart Service
+ *
+ * Adapter that bridges the cart package with @shopkit/data-layer.
+ * This allows cart operations to use the unified data-layer client
+ * instead of making direct HTTP calls.
+ *
+ * @module services/data-layer-cart-service
+ */
+
+/**
+ * Data-layer response interface (matches @shopkit/data-layer IResponse)
+ */
+interface DataLayerResponse<T = any> {
+    success: boolean;
+    message: string;
+    data: T | null;
+    error?: any;
+    meta?: any;
+}
+/**
+ * Data-layer client interface (cart methods only)
+ * This interface matches the cart-related methods from @shopkit/data-layer ICommerceClient
+ */
+interface IDataLayerClient {
+    getCart(params: {
+        id: string;
+    }, options?: any): Promise<DataLayerResponse>;
+    createCart(options?: any): Promise<DataLayerResponse>;
+    addToCart(params: {
+        id: string;
+        items: any[];
+    }, options?: any): Promise<DataLayerResponse>;
+    removeFromCart(params: {
+        id: string;
+        itemIds: string[];
+    }, options?: any): Promise<DataLayerResponse>;
+    updateCart(params: {
+        id: string;
+        items: any[];
+    }, options?: any): Promise<DataLayerResponse>;
+}
+/**
+ * Cart service that uses @shopkit/data-layer for cart operations.
+ *
+ * This adapter bridges the cart package with the data-layer, allowing
+ * all cart operations to go through the unified commerce abstraction.
+ *
+ * @example
+ * ```typescript
+ * import { DataLayerCartService } from "@shopkit/cart";
+ * import { createCommerceClient } from "@shopkit/data-layer";
+ *
+ * const dataLayerClient = createCommerceClient({
+ *   type: "shopify",
+ *   config: { domain: "...", storefrontAccessToken: "..." }
+ * });
+ *
+ * const cartService = new DataLayerCartService(dataLayerClient);
+ *
+ * configureCart({
+ *   merchantName: "my-store",
+ *   cartService,
+ *   cartStorage: new DefaultCartStorage("my-store"),
+ * });
+ * ```
+ */
+declare class DataLayerCartService implements ICartService {
+    private client;
+    constructor(dataLayerClient: IDataLayerClient);
+    /**
+     * Unwrap a data-layer response to get the raw data
+     * @throws Error if the response indicates failure
+     */
+    private unwrapResponse;
+    /**
+     * Create a new cart
+     */
+    createCart(merchantName: string): Promise<CartResponse>;
+    /**
+     * Get an existing cart by ID
+     */
+    getCart(cartId: string): Promise<CartResponse>;
+    /**
+     * Add items to cart
+     */
+    addToCart(cartId: string, items: CartItemRequest[]): Promise<void>;
+    /**
+     * Remove items from cart
+     */
+    removeFromCart(cartId: string, itemIds: string[]): Promise<void>;
+    /**
+     * Update cart items
+     */
+    updateCart(cartId: string, items: CartItemRequest[]): Promise<void>;
+}
+/**
+ * Type guard to check if a client is a data-layer client
+ */
+declare function isDataLayerClient(client: any): client is IDataLayerClient;
+
+/**
+ * Maps a product object to a CartItem.
+ * Handles variant selection, price normalization, and currency fallback.
+ */
+declare function mapProductToCartItem(product: any, variantId?: string, quantity?: number, defaultCurrencyCode?: string): CartItem;
+
+/**
+ * Format a price amount for display using Intl.NumberFormat.
+ *
+ * @param amount - The numeric price amount
+ * @param currencyCode - ISO 4217 currency code (default: "USD")
+ * @param locale - BCP 47 locale string (default: browser locale)
+ * @returns Formatted price string
+ *
+ * @example
+ * ```typescript
+ * formatPrice(29.99, "USD");        // "$29.99"
+ * formatPrice(29.99, "EUR", "de-DE"); // "29,99 €"
+ * formatPrice(1999, "INR", "en-IN");  // "₹1,999.00"
+ * ```
+ */
+declare function formatPrice(amount: number, currencyCode?: string, locale?: string): string;
+/**
+ * Calculate the total price of cart items.
+ * Multiplies each item's price by its quantity and sums the results.
+ *
+ * @param items - Array of items with price and quantity
+ * @returns The total price
+ *
+ * @example
+ * ```typescript
+ * const items = [
+ *   { price: { amount: 10 }, quantity: 2 },
+ *   { price: { amount: 25 }, quantity: 1 },
+ * ];
+ * calculateCartTotal(items); // 45
+ * ```
+ */
+declare function calculateCartTotal(items: Array<{
+    price: number | {
+        amount: number;
+    };
+    quantity: number;
+}>): number;
+/**
+ * Calculate total savings from compareAtPrice vs price.
+ * Useful for displaying "You save X" on cart/checkout.
+ *
+ * @param items - Array of items with price, compareAtPrice, and quantity
+ * @returns The total savings amount
+ *
+ * @example
+ * ```typescript
+ * const items = [
+ *   { price: { amount: 20 }, compareAtPrice: { amount: 30 }, quantity: 2 },
+ * ];
+ * calculateSavings(items); // 20 (saved $10 x 2 items)
+ * ```
+ */
+declare function calculateSavings(items: Array<{
+    price: number | {
+        amount: number;
+    };
+    compareAtPrice?: number | {
+        amount: number;
+    };
+    quantity: number;
+}>): number;
+
+interface CartInitializerProps {
+    merchantName: string;
+}
+/**
+ * Cart initializer component.
+ *
+ * IMPORTANT: `configureCart()` must be called before this component mounts.
+ * Apps should either:
+ *   1. Call `configureCart()` at module scope in a client entry point, or
+ *   2. Create a wrapper component that calls `configureCart()` in a useEffect
+ *      before rendering `<CartInitializer>`.
+ */
+declare function CartInitializer({ merchantName }: CartInitializerProps): null;
+
+export { type CartActions, type CartConfig, type CartEvent, CartInitializer, type CartItem, type CartItemRequest, type CartResponse, type CartState, DataLayerCartService, DefaultCartService, DefaultCartStorage, type ICartService, type ICartStorage, type IDataLayerClient, type UseAddToCartOptions, calculateCartTotal, calculateSavings, configureCart, formatPrice, getCartConfig, isCartConfigured, isDataLayerClient, mapProductToCartItem, useAddToCart, useCartCount, useCartItem, useCartItems, useCartStatus, useCartStore, useCartToggle, useCartTotal, useCartTotalAmount, useCartTotalQuantity, useCheckoutUrl, useIsInCart };