@rotateprotocol/sdk 1.0.0

package/src/hooks.ts

@@ -0,0 +1,518 @@
+/**
+ * Rotate React Hooks — Store, Cart & Marketplace
+ *
+ * Drop-in React hooks for building storefronts and marketplaces.
+ * Think of these as a ready-made React integration for Solana payments.
+ *
+ * @example
+ * ```tsx
+ * function ProductPage() {
+ *   const { products, getByCategory } = useProducts(store);
+ *   const { cart, addItem, totals, checkout } = useCart(store);
+ *
+ *   return (
+ *     <div>
+ *       {getByCategory('shirts').map(p => (
+ *         <button key={p.id} onClick={() => addItem(p.id)}>
+ *           {p.name} — ${p.price}
+ *         </button>
+ *       ))}
+ *       <p>Cart: {totals.totalQuantity} items, ${totals.total}</p>
+ *       <button onClick={() => checkout()}>Pay Now</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { useState, useCallback, useMemo, useEffect, useRef } from 'react';
+import {
+  RotateStore,
+  RotateCart,
+  Product,
+  LineItem,
+  CartTotals,
+  CheckoutResult,
+  Currency,
+} from './store';
+import {
+  RotateMarketplace,
+  MarketplaceCart,
+  MarketplaceProduct,
+  MarketplaceLineItem,
+  MarketplaceCartTotals,
+  MarketplaceCheckoutResult,
+  Vendor,
+} from './marketplace';
+
+// ==================== useProducts ====================
+
+export interface UseProductsReturn {
+  /** All active products */
+  products: Product[];
+  /** All categories */
+  categories: string[];
+  /** Get product by ID */
+  getProduct: (id: string) => Product | undefined;
+  /** Get products by category */
+  getByCategory: (category: string) => Product[];
+  /** Search products */
+  search: (query: string) => Product[];
+  /** Paginated product listing */
+  paginate: (page: number, perPage: number) => { products: Product[]; totalPages: number; total: number };
+  /** Check stock */
+  isInStock: (productId: string, qty?: number) => boolean;
+  /** Total product count */
+  count: number;
+}
+
+/**
+ * Hook for browsing products in a RotateStore.
+ */
+export function useProducts(store: RotateStore): UseProductsReturn {
+  // Force re-render on catalog changes
+  const [version, setVersion] = useState(0);
+  const refresh = useCallback(() => setVersion((v) => v + 1), []);
+
+  const products = useMemo(
+    () => store.getProducts({ active: true }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [store, version]
+  );
+
+  const categories = useMemo(
+    () => store.getCategories(),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [store, version]
+  );
+
+  const getProduct = useCallback((id: string) => store.getProduct(id), [store]);
+
+  const getByCategory = useCallback(
+    (category: string) => store.getProducts({ category, active: true }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [store, version]
+  );
+
+  const search = useCallback(
+    (query: string) => store.getProducts({ search: query, active: true }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [store, version]
+  );
+
+  const paginate = useCallback(
+    (page: number, perPage: number) => {
+      const all = store.getProducts({ active: true });
+      const total = all.length;
+      const totalPages = Math.ceil(total / perPage);
+      const offset = (page - 1) * perPage;
+      return {
+        products: all.slice(offset, offset + perPage),
+        totalPages,
+        total,
+      };
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [store, version]
+  );
+
+  const isInStock = useCallback(
+    (productId: string, qty: number = 1) => store.isInStock(productId, qty),
+    [store]
+  );
+
+  return {
+    products,
+    categories,
+    getProduct,
+    getByCategory,
+    search,
+    paginate,
+    isInStock,
+    count: products.length,
+  };
+}
+
+// ==================== useCart ====================
+
+export interface UseCartReturn {
+  /** The underlying cart instance */
+  cart: RotateCart;
+  /** Current line items */
+  items: LineItem[];
+  /** Calculated totals */
+  totals: CartTotals;
+  /** Is the cart empty */
+  isEmpty: boolean;
+  /** Add item to cart */
+  addItem: (productId: string, quantity?: number) => void;
+  /** Set exact quantity */
+  setQuantity: (productId: string, quantity: number) => void;
+  /** Remove item */
+  removeItem: (productId: string) => void;
+  /** Clear entire cart */
+  clear: () => void;
+  /** Apply discount code */
+  applyDiscount: (code: string) => boolean;
+  /** Remove discount */
+  removeDiscount: (code: string) => boolean;
+  /** Set metadata */
+  setMetadata: (key: string, value: string) => void;
+  /** Checkout and create on-chain payment link */
+  checkout: (options?: {
+    currency?: Currency;
+    expiresIn?: number;
+    allowTips?: boolean;
+    orderRef?: string;
+  }) => Promise<CheckoutResult>;
+  /** Whether checkout is in progress */
+  checkingOut: boolean;
+  /** Last checkout result */
+  lastCheckout: CheckoutResult | null;
+  /** Error from last operation */
+  error: string | null;
+}
+
+/**
+ * Hook for managing a shopping cart backed by a RotateStore.
+ */
+export function useCart(store: RotateStore): UseCartReturn {
+  const cartRef = useRef<RotateCart>(store.createCart());
+  const [version, setVersion] = useState(0);
+  const [checkingOut, setCheckingOut] = useState(false);
+  const [lastCheckout, setLastCheckout] = useState<CheckoutResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const bump = useCallback(() => setVersion((v) => v + 1), []);
+
+  const items = useMemo(() => cartRef.current.getItems(), [version]);
+  const totals = useMemo(() => cartRef.current.getTotals(), [version]);
+  const isEmpty = useMemo(() => cartRef.current.isEmpty, [version]);
+
+  const addItem = useCallback(
+    (productId: string, quantity: number = 1) => {
+      try {
+        cartRef.current.addItem(productId, quantity);
+        setError(null);
+      } catch (e: any) {
+        setError(e.message);
+      }
+      bump();
+    },
+    [bump]
+  );
+
+  const setQuantity = useCallback(
+    (productId: string, quantity: number) => {
+      try {
+        cartRef.current.setItemQuantity(productId, quantity);
+        setError(null);
+      } catch (e: any) {
+        setError(e.message);
+      }
+      bump();
+    },
+    [bump]
+  );
+
+  const removeItem = useCallback(
+    (productId: string) => {
+      cartRef.current.removeItem(productId);
+      bump();
+    },
+    [bump]
+  );
+
+  const clear = useCallback(() => {
+    cartRef.current.clear();
+    setLastCheckout(null);
+    setError(null);
+    bump();
+  }, [bump]);
+
+  const applyDiscount = useCallback(
+    (code: string) => {
+      const ok = cartRef.current.applyDiscount(code);
+      bump();
+      return ok;
+    },
+    [bump]
+  );
+
+  const removeDiscount = useCallback(
+    (code: string) => {
+      const ok = cartRef.current.removeDiscount(code);
+      bump();
+      return ok;
+    },
+    [bump]
+  );
+
+  const setMetadata = useCallback(
+    (key: string, value: string) => {
+      cartRef.current.setMetadata(key, value);
+    },
+    []
+  );
+
+  const checkout = useCallback(
+    async (options?: {
+      currency?: Currency;
+      expiresIn?: number;
+      allowTips?: boolean;
+      orderRef?: string;
+    }) => {
+      setCheckingOut(true);
+      setError(null);
+      try {
+        const result = await cartRef.current.checkout(options);
+        setLastCheckout(result);
+        // Create a fresh cart after successful checkout
+        cartRef.current = store.createCart();
+        bump();
+        return result;
+      } catch (e: any) {
+        setError(e.message);
+        throw e;
+      } finally {
+        setCheckingOut(false);
+      }
+    },
+    [store, bump]
+  );
+
+  return {
+    cart: cartRef.current,
+    items,
+    totals,
+    isEmpty,
+    addItem,
+    setQuantity,
+    removeItem,
+    clear,
+    applyDiscount,
+    removeDiscount,
+    setMetadata,
+    checkout,
+    checkingOut,
+    lastCheckout,
+    error,
+  };
+}
+
+// ==================== useMarketplace ====================
+
+export interface UseMarketplaceReturn {
+  /** All vendors */
+  vendors: Vendor[];
+  /** All marketplace products */
+  products: MarketplaceProduct[];
+  /** Categories */
+  categories: string[];
+  /** Get products by vendor */
+  getVendorProducts: (vendorId: string) => MarketplaceProduct[];
+  /** Search products across all vendors */
+  search: (query: string) => MarketplaceProduct[];
+  /** Check stock */
+  isInStock: (productId: string, qty?: number) => boolean;
+  /** Get a specific vendor */
+  getVendor: (id: string) => Vendor | undefined;
+}
+
+/**
+ * Hook for browsing a marketplace catalog.
+ */
+export function useMarketplace(marketplace: RotateMarketplace): UseMarketplaceReturn {
+  const [version, setVersion] = useState(0);
+
+  const vendors = useMemo(
+    () => marketplace.getVendors({ active: true }),
+    [marketplace, version]
+  );
+
+  const products = useMemo(
+    () => marketplace.getProducts({ active: true }),
+    [marketplace, version]
+  );
+
+  const categories = useMemo(
+    () => marketplace.getCategories(),
+    [marketplace, version]
+  );
+
+  const getVendorProducts = useCallback(
+    (vendorId: string) => marketplace.getVendorProducts(vendorId),
+    [marketplace, version]
+  );
+
+  const search = useCallback(
+    (query: string) => marketplace.getProducts({ search: query, active: true }),
+    [marketplace, version]
+  );
+
+  const isInStock = useCallback(
+    (productId: string, qty: number = 1) => marketplace.isInStock(productId, qty),
+    [marketplace]
+  );
+
+  const getVendor = useCallback(
+    (id: string) => marketplace.getVendor(id),
+    [marketplace]
+  );
+
+  return {
+    vendors,
+    products,
+    categories,
+    getVendorProducts,
+    search,
+    isInStock,
+    getVendor,
+  };
+}
+
+// ==================== useMarketplaceCart ====================
+
+export interface UseMarketplaceCartReturn {
+  /** The underlying marketplace cart */
+  cart: MarketplaceCart;
+  /** Current line items with vendor info */
+  items: MarketplaceLineItem[];
+  /** Per-vendor + combined totals */
+  totals: MarketplaceCartTotals;
+  /** Is empty */
+  isEmpty: boolean;
+  /** Number of unique vendors in cart */
+  vendorCount: number;
+  /** Add item */
+  addItem: (productId: string, quantity?: number) => void;
+  /** Set quantity */
+  setQuantity: (productId: string, quantity: number) => void;
+  /** Remove item */
+  removeItem: (productId: string) => void;
+  /** Clear */
+  clear: () => void;
+  /** Checkout — creates one payment link per vendor */
+  checkout: (options?: {
+    currency?: Currency;
+    expiresIn?: number;
+    allowTips?: boolean;
+    orderRef?: string;
+  }) => Promise<MarketplaceCheckoutResult>;
+  /** Whether checkout is in progress */
+  checkingOut: boolean;
+  /** Last checkout result */
+  lastCheckout: MarketplaceCheckoutResult | null;
+  /** Error */
+  error: string | null;
+}
+
+/**
+ * Hook for managing a multi-vendor marketplace cart.
+ */
+export function useMarketplaceCart(marketplace: RotateMarketplace): UseMarketplaceCartReturn {
+  const cartRef = useRef<MarketplaceCart>(marketplace.createCart());
+  const [version, setVersion] = useState(0);
+  const [checkingOut, setCheckingOut] = useState(false);
+  const [lastCheckout, setLastCheckout] = useState<MarketplaceCheckoutResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const bump = useCallback(() => setVersion((v) => v + 1), []);
+
+  const items = useMemo(() => cartRef.current.getItems(), [version]);
+  const totals = useMemo(() => cartRef.current.getTotals(), [version]);
+  const isEmpty = useMemo(() => cartRef.current.isEmpty, [version]);
+
+  const addItem = useCallback(
+    (productId: string, quantity: number = 1) => {
+      try {
+        cartRef.current.addItem(productId, quantity);
+        setError(null);
+      } catch (e: any) {
+        setError(e.message);
+      }
+      bump();
+    },
+    [bump]
+  );
+
+  const setQuantity = useCallback(
+    (productId: string, quantity: number) => {
+      try {
+        cartRef.current.setItemQuantity(productId, quantity);
+        setError(null);
+      } catch (e: any) {
+        setError(e.message);
+      }
+      bump();
+    },
+    [bump]
+  );
+
+  const removeItem = useCallback(
+    (productId: string) => {
+      cartRef.current.removeItem(productId);
+      bump();
+    },
+    [bump]
+  );
+
+  const clear = useCallback(() => {
+    cartRef.current.clear();
+    setLastCheckout(null);
+    setError(null);
+    bump();
+  }, [bump]);
+
+  const checkout = useCallback(
+    async (options?: {
+      currency?: Currency;
+      expiresIn?: number;
+      allowTips?: boolean;
+      orderRef?: string;
+    }) => {
+      setCheckingOut(true);
+      setError(null);
+      try {
+        const result = await cartRef.current.checkout(options);
+        setLastCheckout(result);
+        cartRef.current = marketplace.createCart();
+        bump();
+        return result;
+      } catch (e: any) {
+        setError(e.message);
+        throw e;
+      } finally {
+        setCheckingOut(false);
+      }
+    },
+    [marketplace, bump]
+  );
+
+  return {
+    cart: cartRef.current,
+    items,
+    totals,
+    isEmpty,
+    vendorCount: totals.vendorCount,
+    addItem,
+    setQuantity,
+    removeItem,
+    clear,
+    checkout,
+    checkingOut,
+    lastCheckout,
+    error,
+  };
+}
+
+// ==================== EXPORTS ====================
+
+export {
+  RotateStore,
+  RotateCart,
+  RotateMarketplace,
+  MarketplaceCart,
+};