@doswiftly/storefront-sdk 4.0.0

package/src/react/hooks/use-auth.ts

@@ -0,0 +1,218 @@
+/**
+ * useAuth — wraps AuthClient + updates auth store.
+ *
+ * Centralizes login/logout/renew with dual-layer persistence:
+ * - httpOnly cookie (for SSR/middleware) — via onSetToken/onClearToken callbacks
+ * - Zustand store (for client-side state)
+ *
+ * Does NOT use React Query — plain async + store updates.
+ * Template can wrap in useMutation() if React Query features are needed.
+ *
+ * @example
+ * ```tsx
+ * const { login, logout, isLoading } = useAuth();
+ *
+ * const result = await login('user@example.com', 'password');
+ * if (result.success) router.push('/account');
+ * ```
+ */
+
+'use client';
+
+import { useState, useCallback } from 'react';
+import { useStorefrontClientContext } from '../providers/storefront-client-provider';
+import { useAuthStore, useAuthStoreApi } from '../stores/store-context';
+import { StorefrontError } from '../../core/errors';
+
+export interface UseAuthOptions {
+  /**
+   * Called after successful login/renewToken with the new access token.
+   * Use to set httpOnly cookie via API route.
+   */
+  onSetToken?: (token: string) => Promise<void>;
+  /**
+   * Called after logout to clear httpOnly cookie.
+   */
+  onClearToken?: () => Promise<void>;
+}
+
+export interface LoginResult {
+  success: boolean;
+  userErrors: Array<{ message: string; field?: string[] }>;
+  accessToken?: string;
+  expiresAt?: string;
+}
+
+export interface LogoutResult {
+  success: boolean;
+  userErrors: Array<{ message: string; field?: string[] }>;
+}
+
+export interface TokenRenewResult {
+  success: boolean;
+  userErrors: Array<{ message: string; field?: string[] }>;
+  accessToken?: string;
+  expiresAt?: string;
+}
+
+export function useAuth(options: UseAuthOptions = {}) {
+  const { authClient } = useStorefrontClientContext();
+  const { setAuth, clearAuth } = useAuthStore();
+  const authStore = useAuthStoreApi();
+
+  const [isLoggingIn, setIsLoggingIn] = useState(false);
+  const [isLoggingOut, setIsLoggingOut] = useState(false);
+  const [isRenewingToken, setIsRenewingToken] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const login = useCallback(async (email: string, password: string): Promise<LoginResult> => {
+    setError(null);
+    setIsLoggingIn(true);
+
+    try {
+      const result = await authClient.login(email, password);
+
+      // Set httpOnly cookie
+      if (options.onSetToken) {
+        await options.onSetToken(result.accessToken);
+      }
+
+      // Fetch customer data and set store
+      try {
+        const customer = await authClient.getCustomer(result.accessToken);
+        if (customer) {
+          setAuth(
+            {
+              id: customer.id,
+              email: customer.email,
+              firstName: customer.firstName ?? undefined,
+              lastName: customer.lastName ?? undefined,
+              phone: customer.phone ?? undefined,
+            },
+            result.accessToken,
+          );
+        } else {
+          setAuth({ id: '', email }, result.accessToken);
+        }
+      } catch {
+        // Customer fetch failed — store minimal data
+        setAuth({ id: '', email }, result.accessToken);
+      }
+
+      return {
+        success: true,
+        userErrors: [],
+        accessToken: result.accessToken,
+        expiresAt: result.expiresAt,
+      };
+    } catch (err) {
+      if (err instanceof StorefrontError && err.hasUserErrors) {
+        return {
+          success: false,
+          userErrors: err.userErrors.map((e) => ({
+            message: e.message,
+            field: e.field,
+          })),
+        };
+      }
+
+      const message = err instanceof Error ? err.message : 'Login failed';
+      setError(message);
+      return { success: false, userErrors: [{ message }] };
+    } finally {
+      setIsLoggingIn(false);
+    }
+  }, [authClient, setAuth, options]);
+
+  const logout = useCallback(async (): Promise<LogoutResult> => {
+    setError(null);
+    setIsLoggingOut(true);
+
+    try {
+      const token = authStore.getState().accessToken;
+      if (token) {
+        await authClient.logout(token);
+      }
+
+      // Clear httpOnly cookie
+      if (options.onClearToken) {
+        await options.onClearToken();
+      }
+
+      clearAuth();
+
+      return { success: true, userErrors: [] };
+    } catch (err) {
+      // Even on error, clear local state
+      clearAuth();
+      const message = err instanceof Error ? err.message : 'Logout failed';
+      setError(message);
+      return { success: false, userErrors: [{ message }] };
+    } finally {
+      setIsLoggingOut(false);
+    }
+  }, [authClient, clearAuth, options, authStore]);
+
+  const renewToken = useCallback(async (): Promise<TokenRenewResult> => {
+    setError(null);
+    setIsRenewingToken(true);
+
+    try {
+      const token = authStore.getState().accessToken;
+      if (!token) {
+        return {
+          success: false,
+          userErrors: [{ message: 'No token to renew' }],
+        };
+      }
+
+      const result = await authClient.renewToken(token);
+
+      // Update httpOnly cookie
+      if (options.onSetToken) {
+        await options.onSetToken(result.accessToken);
+      }
+
+      // Update store (keep customer data, update token)
+      const currentCustomer = authStore.getState().customer;
+      if (currentCustomer) {
+        setAuth(currentCustomer, result.accessToken);
+      }
+
+      return {
+        success: true,
+        userErrors: [],
+        accessToken: result.accessToken,
+        expiresAt: result.expiresAt,
+      };
+    } catch (err) {
+      if (err instanceof StorefrontError && err.hasUserErrors) {
+        return {
+          success: false,
+          userErrors: err.userErrors.map((e) => ({
+            message: e.message,
+            field: e.field,
+          })),
+        };
+      }
+
+      const message = err instanceof Error ? err.message : 'Token renewal failed';
+      setError(message);
+      return { success: false, userErrors: [{ message }] };
+    } finally {
+      setIsRenewingToken(false);
+    }
+  }, [authClient, setAuth, options, authStore]);
+
+  return {
+    login,
+    logout,
+    renewToken,
+
+    isLoggingIn,
+    isLoggingOut,
+    isRenewingToken,
+    isLoading: isLoggingIn || isLoggingOut || isRenewingToken,
+    error,
+  };
+}

package/src/react/hooks/use-cart-manager.ts

@@ -0,0 +1,236 @@
+/**
+ * useCartManager — wraps CartClient with cart ID persistence + loading states.
+ *
+ * Auto-creates cart on first add. CartId persisted in cookie (SSR/edge visible).
+ * Does NOT use React Query — plain async + useState.
+ * Template wraps in useMutation() if React Query features are needed.
+ *
+ * @example
+ * ```tsx
+ * const { addItem, updateQuantity, removeItem, isLoading } = useCartManager();
+ *
+ * await addItem([{ merchandiseId: 'variant-123', quantity: 1 }]);
+ * ```
+ */
+
+'use client';
+
+import { useState, useCallback } from 'react';
+import { useStorefrontClientContext } from '../providers/storefront-client-provider';
+import type { Cart, CartLineInput, CartLineUpdateInput, CartCreateInput, CartBuyerIdentityInput } from '../../core/cart/types';
+import { StorefrontError } from '../../core/errors';
+
+// ---------------------------------------------------------------------------
+// Cart ID persistence (cookie — SSR/edge visible)
+// ---------------------------------------------------------------------------
+
+function getCartIdFromCookie(): string | null {
+  if (typeof document === 'undefined') return null;
+  const match = document.cookie.match(/(?:^|;\s*)cart-id=([^;]*)/);
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+function setCartIdCookie(cartId: string): void {
+  if (typeof document === 'undefined') return;
+  const maxAge = 30 * 24 * 60 * 60; // 30 days
+  document.cookie = `cart-id=${encodeURIComponent(cartId)};max-age=${maxAge};path=/;samesite=lax`;
+}
+
+function clearCartIdCookie(): void {
+  if (typeof document === 'undefined') return;
+  document.cookie = 'cart-id=;max-age=0;path=/';
+}
+
+export function useCartManager() {
+  const { cartClient } = useStorefrontClientContext();
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * Get existing cart ID from cookie or create a new cart.
+   */
+  const getOrCreateCartId = useCallback(async (forceNew = false): Promise<string> => {
+    if (!forceNew) {
+      const existing = getCartIdFromCookie();
+      if (existing) return existing;
+    }
+
+    const cart = await cartClient.create();
+    setCartIdCookie(cart.id);
+    return cart.id;
+  }, [cartClient]);
+
+  /**
+   * Check if error indicates cart not found (expired).
+   */
+  const isCartExpired = (err: unknown): boolean => {
+    if (err instanceof StorefrontError) {
+      return err.message.toLowerCase().includes('cart not found') ||
+             err.message.toLowerCase().includes('cart does not exist');
+    }
+    return false;
+  };
+
+  /**
+   * Fetch current cart. Returns null if no cart exists.
+   */
+  const getCart = useCallback(async (): Promise<Cart | null> => {
+    const cartId = getCartIdFromCookie();
+    if (!cartId) return null;
+
+    try {
+      return await cartClient.get(cartId);
+    } catch (err) {
+      if (isCartExpired(err)) {
+        clearCartIdCookie();
+        return null;
+      }
+      throw err;
+    }
+  }, [cartClient]);
+
+  /**
+   * Add items to cart. Creates cart if needed.
+   * On expired cart, clears cookie, creates new cart, retries once.
+   */
+  const addItem = useCallback(async (
+    lines: CartLineInput[],
+    options?: { forceNewCart?: boolean },
+  ): Promise<Cart> => {
+    setError(null);
+    setIsLoading(true);
+
+    try {
+      const cartId = await getOrCreateCartId(options?.forceNewCart);
+      const cart = await cartClient.addItems(cartId, lines);
+      return cart;
+    } catch (err) {
+      if (isCartExpired(err) && !options?.forceNewCart) {
+        clearCartIdCookie();
+        return addItem(lines, { forceNewCart: true });
+      }
+
+      const message = err instanceof Error ? err.message : 'Failed to add to cart';
+      setError(message);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [cartClient, getOrCreateCartId]);
+
+  /**
+   * Update line items (quantity, attributes).
+   */
+  const updateItem = useCallback(async (
+    lines: CartLineUpdateInput[],
+  ): Promise<Cart> => {
+    setError(null);
+    setIsLoading(true);
+
+    try {
+      const cartId = getCartIdFromCookie();
+      if (!cartId) throw new Error('No cart found');
+      return await cartClient.updateItems(cartId, lines);
+    } catch (err) {
+      if (isCartExpired(err)) {
+        clearCartIdCookie();
+      }
+      const message = err instanceof Error ? err.message : 'Failed to update cart';
+      setError(message);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [cartClient]);
+
+  /**
+   * Remove items by line IDs.
+   */
+  const removeItem = useCallback(async (lineIds: string[]): Promise<Cart> => {
+    setError(null);
+    setIsLoading(true);
+
+    try {
+      const cartId = getCartIdFromCookie();
+      if (!cartId) throw new Error('No cart found');
+      return await cartClient.removeItems(cartId, lineIds);
+    } catch (err) {
+      if (isCartExpired(err)) {
+        clearCartIdCookie();
+      }
+      const message = err instanceof Error ? err.message : 'Failed to remove from cart';
+      setError(message);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [cartClient]);
+
+  /**
+   * Update discount codes (replaces all existing).
+   */
+  const updateDiscountCodes = useCallback(async (codes: string[]): Promise<Cart> => {
+    setError(null);
+    setIsLoading(true);
+
+    try {
+      const cartId = getCartIdFromCookie();
+      if (!cartId) throw new Error('No cart found');
+      return await cartClient.updateDiscountCodes(cartId, codes);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to update discount codes';
+      setError(message);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [cartClient]);
+
+  /**
+   * Update cart note.
+   */
+  const updateNote = useCallback(async (note: string): Promise<Cart> => {
+    setError(null);
+    setIsLoading(true);
+
+    try {
+      const cartId = getCartIdFromCookie();
+      if (!cartId) throw new Error('No cart found');
+      return await cartClient.updateNote(cartId, note);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to update note';
+      setError(message);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [cartClient]);
+
+  /**
+   * Clear cart — removes cookie.
+   */
+  const clearCart = useCallback(() => {
+    clearCartIdCookie();
+  }, []);
+
+  /**
+   * Get current cart ID from cookie (if exists).
+   */
+  const getCartId = useCallback((): string | null => {
+    return getCartIdFromCookie();
+  }, []);
+
+  return {
+    getCart,
+    addItem,
+    updateItem,
+    removeItem,
+    updateDiscountCodes,
+    updateNote,
+    clearCart,
+    getCartId,
+
+    isLoading,
+    error,
+  };
+}

package/src/react/hooks/use-currency.ts

@@ -0,0 +1,23 @@
+/**
+ * useCurrency — convenience hook for currency state.
+ */
+
+'use client';
+
+import { useCurrencyStore } from '../stores/store-context';
+
+export function useCurrency() {
+  const currency = useCurrencyStore((s) => s.currency);
+  const baseCurrency = useCurrencyStore((s) => s.baseCurrency);
+  const supportedCurrencies = useCurrencyStore((s) => s.supportedCurrencies);
+  const setCurrency = useCurrencyStore((s) => s.setCurrency);
+  const isLoaded = useCurrencyStore((s) => s.isLoaded);
+
+  return {
+    currency,
+    baseCurrency,
+    supportedCurrencies,
+    setCurrency,
+    isLoaded,
+  };
+}

package/src/react/hooks/use-debounced-value.ts

@@ -0,0 +1,30 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+
+/**
+ * Debounce a value.
+ *
+ * @param value - Value to debounce
+ * @param delay - Delay in ms (default: 300)
+ * @returns Debounced value
+ *
+ * @example
+ * ```tsx
+ * const [query, setQuery] = useState("");
+ * const debouncedQuery = useDebouncedValue(query, 300);
+ * ```
+ */
+export function useDebouncedValue<T>(value: T, delay = 300): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/react/hooks/use-hydrated.ts

@@ -0,0 +1,20 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+const emptySubscribe = () => () => {};
+
+/**
+ * Returns false during SSR and first client render,
+ * then true after hydration completes.
+ *
+ * Use this to guard any content that depends on browser-only state
+ * (localStorage, cookies, window) to prevent hydration mismatches.
+ */
+export function useHydrated() {
+  return useSyncExternalStore(
+    emptySubscribe,
+    () => true, // Client: true
+    () => false, // Server: false
+  );
+}

package/src/react/hooks/use-storefront-client.ts

@@ -0,0 +1,12 @@
+/**
+ * useStorefrontClient — access StorefrontClient from context.
+ */
+
+'use client';
+
+import { useStorefrontClientContext } from '../providers/storefront-client-provider';
+import type { StorefrontClient } from '../../core/client/types';
+
+export function useStorefrontClient(): StorefrontClient {
+  return useStorefrontClientContext().client;
+}

package/src/react/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @doswiftly/storefront-sdk/react — React adapter
+ *
+ * Provides React providers, Zustand stores, and hooks
+ * that wrap the framework-agnostic core.
+ *
+ * Peer dependencies: react ^18 || ^19, zustand ^5
+ *
+ * @example
+ * ```tsx
+ * import { StorefrontProvider, useAuth, useCartManager, useCurrency } from '@doswiftly/storefront-sdk/react';
+ * ```
+ */
+
+// Providers
+export { StorefrontProvider, type StorefrontProviderProps } from './providers/storefront-provider';
+export { StorefrontClientProvider, type StorefrontClientProviderProps } from './providers/storefront-client-provider';
+export { CurrencyProvider, type CurrencyProviderProps } from './providers/currency-provider';
+
+// Hooks
+export { useAuth, type UseAuthOptions, type LoginResult, type LogoutResult, type TokenRenewResult } from './hooks/use-auth';
+export { useCartManager } from './hooks/use-cart-manager';
+export { useStorefrontClient } from './hooks/use-storefront-client';
+export { useCurrency } from './hooks/use-currency';
+
+// Store hooks (Context-based)
+export { useAuthStore, useAuthStoreApi, useAuthHydrated } from './stores/store-context';
+export { useCurrencyStore, useCurrencyStoreApi } from './stores/store-context';
+
+// Store types
+export type { AuthStore, CustomerInfo } from './stores/auth.store';
+export type { CurrencyStore, ShopCurrencyData } from './stores/currency.store';
+
+// Selectors
+export { selectCurrency, selectBaseCurrency, selectSupportedCurrencies, selectIsLoaded } from './stores/currency.store';
+
+// Cookie utilities
+export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync } from './cookies';
+
+// Generic hooks
+export { useHydrated } from './hooks/use-hydrated';
+export { useDebouncedValue } from './hooks/use-debounced-value';
+
+// Store context helper
+export { createStoreContext } from './helpers/create-store-context';

package/src/react/providers/currency-provider.tsx

@@ -0,0 +1,30 @@
+/**
+ * CurrencyProvider — initializes currency store from Shop data.
+ *
+ * Thin wrapper that calls useCurrencyStore.initialize() on mount
+ * with the shop's currency configuration from the server.
+ */
+
+'use client';
+
+import React, { useEffect } from 'react';
+import { useCurrencyStore } from '../stores/store-context';
+import type { ShopCurrencyData } from '../stores/currency.store';
+
+export interface CurrencyProviderProps {
+  children: React.ReactNode;
+  shopData: ShopCurrencyData;
+}
+
+export function CurrencyProvider({ children, shopData }: CurrencyProviderProps) {
+  const initialize = useCurrencyStore((s) => s.initialize);
+  const isLoaded = useCurrencyStore((s) => s.isLoaded);
+
+  useEffect(() => {
+    if (!isLoaded) {
+      initialize(shopData);
+    }
+  }, [initialize, isLoaded, shopData]);
+
+  return <>{children}</>;
+}