@doswiftly/cli 0.1.1

package/templates/storefront-nextjs-shadcn/hooks/use-auth.ts

@@ -0,0 +1,310 @@
+/**
+ * Authentication Hook
+ *
+ * Provides login, logout, and authentication state management.
+ *
+ * Security Model:
+ * 1. Login: Calls GraphQL mutation → Stores token in httpOnly cookie via API route
+ * 2. Logout: Calls GraphQL mutation → Clears httpOnly cookie via API route
+ * 3. Token validation: Happens on GraphQL backend (not client-side)
+ *
+ * Usage:
+ * - Login/Register pages: Call login() after successful mutation
+ * - Protected pages: Use AuthGuard component (checks cookie existence)
+ * - Logout button: Call logout() to clear session
+ *
+ * @see lib/auth/cookies.ts - Cookie helper functions
+ * @see lib/auth/routes.ts - Route configuration
+ * @see proxy.ts - Server-side route protection
+ *
+ * @example
+ * ```tsx
+ * function LoginForm() {
+ *   const { login, isLoading, error } = useAuth();
+ *
+ *   const handleSubmit = async (e) => {
+ *     e.preventDefault();
+ *     const result = await login(email, password);
+ *     if (result.userErrors.length === 0) {
+ *       // Success - redirected to /account
+ *     }
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ */
+
+"use client";
+
+import { useState } from "react";
+import { useRouter, useSearchParams } from "next/navigation";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { getGraphQLClient } from "@/lib/graphql/client";
+import {
+  CustomerLoginDocument,
+  CustomerLogoutDocument,
+  CustomerTokenRenewDocument,
+  type CustomerLoginMutation,
+  type CustomerLogoutMutation,
+  type CustomerTokenRenewMutation,
+} from "@/generated/graphql";
+import { setAuthToken, clearAuthToken, getAuthToken } from "@/lib/auth/cookies";
+import { redirects } from "@/lib/auth/routes";
+
+/**
+ * Login input
+ */
+export interface LoginInput {
+  email: string;
+  password: string;
+}
+
+/**
+ * Login result
+ */
+export interface LoginResult {
+  success: boolean;
+  userErrors: Array<{ message: string; field?: string[] }>;
+  accessToken?: string;
+  expiresAt?: string;
+}
+
+/**
+ * Logout result
+ */
+export interface LogoutResult {
+  success: boolean;
+  userErrors: Array<{ message: string; field?: string[] }>;
+}
+
+/**
+ * Token renew result
+ */
+export interface TokenRenewResult {
+  success: boolean;
+  userErrors: Array<{ message: string; field?: string[] }>;
+  accessToken?: string;
+  expiresAt?: string;
+}
+
+/**
+ * Authentication hook
+ */
+export function useAuth() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const queryClient = useQueryClient();
+  const client = getGraphQLClient();
+
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * Login mutation
+   */
+  const loginMutation = useMutation({
+    mutationFn: async (input: LoginInput): Promise<LoginResult> => {
+      const data = await client.request<CustomerLoginMutation>(
+        CustomerLoginDocument,
+        { input }
+      );
+
+      const { customerAccessToken, userErrors } =
+        data.customerAccessTokenCreate;
+
+      if (userErrors && userErrors.length > 0) {
+        return {
+          success: false,
+          userErrors: userErrors.map((e: any) => ({
+            message: e.message,
+            field: e.field || undefined,
+          })),
+        };
+      }
+
+      if (!customerAccessToken) {
+        return {
+          success: false,
+          userErrors: [{ message: "Failed to create access token" }],
+        };
+      }
+
+      // Store token in httpOnly cookie via API route
+      await setAuthToken(customerAccessToken.accessToken);
+
+      return {
+        success: true,
+        userErrors: [],
+        accessToken: customerAccessToken.accessToken,
+        expiresAt: customerAccessToken.expiresAt,
+      };
+    },
+    onSuccess: (result: LoginResult) => {
+      if (result.success) {
+        // Clear any cached queries that might need authentication
+        queryClient.invalidateQueries();
+
+        // Redirect to original destination or account page
+        const redirect = searchParams.get("redirect");
+        router.push(redirect || redirects.authenticated);
+      }
+    },
+    onError: (err: unknown) => {
+      setError(err instanceof Error ? err.message : "Login failed");
+    },
+  });
+
+  /**
+   * Logout mutation
+   */
+  const logoutMutation = useMutation({
+    mutationFn: async (): Promise<LogoutResult> => {
+      const token = getAuthToken();
+
+      if (!token) {
+        // No token to logout
+        return {
+          success: true,
+          userErrors: [],
+        };
+      }
+
+      const data = await client.request<CustomerLogoutMutation>(
+        CustomerLogoutDocument,
+        { customerAccessToken: token }
+      );
+
+      const { userErrors } = data.customerAccessTokenDelete;
+
+      if (userErrors && userErrors.length > 0) {
+        return {
+          success: false,
+          userErrors: userErrors.map((e: any) => ({
+            message: e.message,
+            field: e.field || undefined,
+          })),
+        };
+      }
+
+      // Clear httpOnly cookie via API route
+      await clearAuthToken();
+
+      return {
+        success: true,
+        userErrors: [],
+      };
+    },
+    onSuccess: (result: LogoutResult) => {
+      if (result.success) {
+        // Clear all cached queries
+        queryClient.clear();
+
+        // Redirect to home page
+        router.push("/");
+      }
+    },
+    onError: (err: unknown) => {
+      setError(err instanceof Error ? err.message : "Logout failed");
+    },
+  });
+
+  /**
+   * Token renew mutation
+   */
+  const renewTokenMutation = useMutation({
+    mutationFn: async (): Promise<TokenRenewResult> => {
+      const token = getAuthToken();
+
+      if (!token) {
+        return {
+          success: false,
+          userErrors: [{ message: "No token to renew" }],
+        };
+      }
+
+      const data = await client.request<CustomerTokenRenewMutation>(
+        CustomerTokenRenewDocument,
+        { customerAccessToken: token }
+      );
+
+      const { customerAccessToken, userErrors } =
+        data.customerAccessTokenRenew;
+
+      if (userErrors && userErrors.length > 0) {
+        return {
+          success: false,
+          userErrors: userErrors.map((e: any) => ({
+            message: e.message,
+            field: e.field || undefined,
+          })),
+        };
+      }
+
+      if (!customerAccessToken) {
+        return {
+          success: false,
+          userErrors: [{ message: "Failed to renew access token" }],
+        };
+      }
+
+      // Update token in httpOnly cookie via API route
+      await setAuthToken(customerAccessToken.accessToken);
+
+      return {
+        success: true,
+        userErrors: [],
+        accessToken: customerAccessToken.accessToken,
+        expiresAt: customerAccessToken.expiresAt,
+      };
+    },
+    onError: (err: unknown) => {
+      setError(err instanceof Error ? err.message : "Token renewal failed");
+    },
+  });
+
+  /**
+   * Login function
+   */
+  const login = async (email: string, password: string): Promise<LoginResult> => {
+    setError(null);
+    return loginMutation.mutateAsync({ email, password });
+  };
+
+  /**
+   * Logout function
+   */
+  const logout = async (): Promise<LogoutResult> => {
+    setError(null);
+    return logoutMutation.mutateAsync();
+  };
+
+  /**
+   * Renew token function
+   */
+  const renewToken = async (): Promise<TokenRenewResult> => {
+    setError(null);
+    return renewTokenMutation.mutateAsync();
+  };
+
+  return {
+    // Functions
+    login,
+    logout,
+    renewToken,
+
+    // State
+    isLoggingIn: loginMutation.isPending,
+    isLoggingOut: logoutMutation.isPending,
+    isRenewingToken: renewTokenMutation.isPending,
+    isLoading:
+      loginMutation.isPending ||
+      logoutMutation.isPending ||
+      renewTokenMutation.isPending,
+    error,
+
+    // Results
+    loginResult: loginMutation.data,
+    logoutResult: logoutMutation.data,
+    renewResult: renewTokenMutation.data,
+  };
+}

package/templates/storefront-nextjs-shadcn/hooks/use-cart-actions.ts

@@ -0,0 +1,286 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+import { useCartStore } from '@/stores/cart-store';
+import { useCartCreate, useCartLinesAdd, useCartLinesUpdate, useCartLinesRemove } from '@/lib/graphql/hooks';
+import { toast } from 'sonner';
+
+// Debounce delay for quantity updates (prevents rate limiting)
+const QUANTITY_UPDATE_DEBOUNCE_MS = 500;
+
+/**
+ * Hook for cart mutations — server-only, no local state manipulation.
+ *
+ * All mutations go through GraphQL. React Query cache invalidation
+ * (configured in hooks.ts) automatically updates all consumers via useCartSync.
+ *
+ * @example
+ * ```typescript
+ * const { addToCart, updateQuantity, removeFromCart } = useCartActions();
+ *
+ * await addToCart({
+ *   variantId: 'variant-123',
+ *   productId: 'product-456',
+ *   productTitle: 'T-Shirt',
+ *   variantTitle: 'Large / Blue',
+ *   price: { amount: '29.99', currencyCode: 'USD' },
+ *   quantity: 1
+ * });
+ *
+ * // updateQuantity and removeFromCart take lineId (not variantId)
+ * updateQuantity('line-abc', 3);
+ * removeFromCart('line-abc');
+ * ```
+ */
+export function useCartActions() {
+  const {
+    setCartId,
+    clearCart,
+    openCart,
+  } = useCartStore();
+
+  // GraphQL mutations
+  const createCartMutation = useCartCreate();
+  const addLinesMutation = useCartLinesAdd();
+  const updateLinesMutation = useCartLinesUpdate();
+  const removeLinesMutation = useCartLinesRemove();
+
+  // Debounce refs for quantity updates (prevents ThrottlerException on rapid clicks)
+  const updateTimeoutRef = useRef<Map<string, NodeJS.Timeout>>(new Map());
+  const pendingUpdatesRef = useRef<Map<string, { lineId: string; quantity: number }>>(new Map());
+
+  /**
+   * Get or create cart ID.
+   * Reads cartId from store (fresh, not stale closure) or creates a new cart.
+   */
+  const getOrCreateCartId = useCallback(async (forceNew: boolean = false): Promise<string> => {
+    const currentCartId = useCartStore.getState().cartId;
+    if (currentCartId && !forceNew) {
+      return currentCartId;
+    }
+
+    try {
+      const result = await createCartMutation.mutateAsync({ input: {} });
+
+      if (result.cartCreate.cart) {
+        const newCartId = result.cartCreate.cart.id;
+        setCartId(newCartId);
+        return newCartId;
+      }
+
+      if (result.cartCreate.userErrors?.length > 0) {
+        throw new Error(result.cartCreate.userErrors[0].message);
+      }
+
+      throw new Error('Failed to create cart');
+    } catch (error: any) {
+      console.error('Cart creation failed:', error);
+      throw error;
+    }
+  }, [setCartId, createCartMutation]);
+
+  /**
+   * Check if error is a "Cart not found" error (stale/expired cart)
+   */
+  const isCartNotFoundError = (error: any): boolean => {
+    const message = error?.message || '';
+    return message.toLowerCase().includes('cart not found') ||
+           message.toLowerCase().includes('cart does not exist');
+  };
+
+  /**
+   * Add item to cart (server-only).
+   *
+   * Creates cart if needed. On "cart not found", clears cartId, creates new cart, retries once.
+   * React Query cache invalidation in hooks.ts updates all useCartSync consumers.
+   */
+  const addToCart = useCallback(async (item: {
+    variantId: string;
+    productId: string;
+    productHandle?: string;
+    productTitle: string;
+    variantTitle: string;
+    price: { amount: string; currencyCode: string };
+    image?: { url: string; altText?: string | null } | null;
+    available?: boolean;
+    quantity?: number;
+  }, _options?: { _forceNewCart?: boolean }) => {
+    const forceNewCart = _options?._forceNewCart ?? false;
+
+    try {
+      const cartId = await getOrCreateCartId(forceNewCart);
+
+      const result = await addLinesMutation.mutateAsync({
+        cartId,
+        lines: [{
+          merchandiseId: item.variantId,
+          quantity: item.quantity ?? 1,
+        }],
+      });
+
+      if (result.cartLinesAdd.userErrors?.length > 0) {
+        const errorMessage = result.cartLinesAdd.userErrors[0].message;
+
+        if (isCartNotFoundError({ message: errorMessage }) && !forceNewCart) {
+          console.warn('Cart expired, creating new cart and retrying...');
+          setCartId(null);
+          return addToCart(item, { _forceNewCart: true });
+        }
+
+        throw new Error(errorMessage);
+      }
+
+      // Open cart drawer to show the added item
+      openCart();
+      toast.success('Added to cart');
+    } catch (error: any) {
+      if (isCartNotFoundError(error) && !forceNewCart) {
+        console.warn('Cart expired (caught), creating new cart and retrying...');
+        setCartId(null);
+        return addToCart(item, { _forceNewCart: true });
+      }
+
+      console.error('Add to cart failed:', error);
+      toast.error(error.message || 'Failed to add to cart');
+      throw error;
+    }
+  }, [setCartId, openCart, getOrCreateCartId, addLinesMutation]);
+
+  /**
+   * Execute the actual GraphQL update for a pending quantity change
+   */
+  const executeQuantityUpdate = useCallback(async (lineId: string, quantity: number) => {
+    try {
+      const currentCartId = useCartStore.getState().cartId;
+      if (!currentCartId) {
+        throw new Error('No cart found');
+      }
+
+      const result = await updateLinesMutation.mutateAsync({
+        cartId: currentCartId,
+        lines: [{
+          id: lineId,
+          quantity,
+        }],
+      });
+
+      if (result.cartLinesUpdate.userErrors?.length > 0) {
+        const errorMessage = result.cartLinesUpdate.userErrors[0].message;
+
+        if (isCartNotFoundError({ message: errorMessage })) {
+          console.warn('Cart expired during update, clearing cart');
+          clearCart();
+          toast.error('Your cart has expired. Please add items again.');
+          return;
+        }
+
+        throw new Error(errorMessage);
+      }
+    } catch (error: any) {
+      if (isCartNotFoundError(error)) {
+        console.warn('Cart expired during update (caught), clearing cart');
+        clearCart();
+        toast.error('Your cart has expired. Please add items again.');
+        return;
+      }
+
+      console.error('Update quantity failed:', error);
+      toast.error(error.message || 'Failed to update quantity');
+    }
+  }, [updateLinesMutation, clearCart]);
+
+  /**
+   * Remove item from cart by line ID.
+   *
+   * Silently handles expired cart (just clears stale cartId).
+   */
+  const removeFromCart = useCallback(async (lineId: string) => {
+    try {
+      const currentCartId = useCartStore.getState().cartId;
+      if (!currentCartId) {
+        return;
+      }
+
+      const result = await removeLinesMutation.mutateAsync({
+        cartId: currentCartId,
+        lineIds: [lineId],
+      });
+
+      if (result.cartLinesRemove.userErrors?.length > 0) {
+        const errorMessage = result.cartLinesRemove.userErrors[0].message;
+
+        if (isCartNotFoundError({ message: errorMessage })) {
+          console.warn('Cart expired during remove, clearing stale cartId');
+          setCartId(null);
+          return;
+        }
+
+        throw new Error(errorMessage);
+      }
+
+      toast.success('Removed from cart');
+    } catch (error: any) {
+      if (isCartNotFoundError(error)) {
+        console.warn('Cart expired during remove (caught), clearing stale cartId');
+        setCartId(null);
+        return;
+      }
+
+      console.error('Remove from cart failed:', error);
+      toast.error(error.message || 'Failed to remove from cart');
+      throw error;
+    }
+  }, [setCartId, removeLinesMutation]);
+
+  /**
+   * Update item quantity (debounced, takes lineId).
+   *
+   * Debounces GraphQL API calls to prevent ThrottlerException on rapid clicks.
+   * If quantity <= 0, removes the item instead.
+   */
+  const updateQuantity = useCallback((lineId: string, quantity: number) => {
+    if (quantity <= 0) {
+      removeFromCart(lineId);
+      return;
+    }
+
+    // Cancel any pending update for this line
+    const existingTimeout = updateTimeoutRef.current.get(lineId);
+    if (existingTimeout) {
+      clearTimeout(existingTimeout);
+    }
+
+    // Store the pending update
+    pendingUpdatesRef.current.set(lineId, { lineId, quantity });
+
+    // Schedule debounced API call
+    const timeout = setTimeout(() => {
+      const pending = pendingUpdatesRef.current.get(lineId);
+      if (pending) {
+        pendingUpdatesRef.current.delete(lineId);
+        updateTimeoutRef.current.delete(lineId);
+        executeQuantityUpdate(pending.lineId, pending.quantity);
+      }
+    }, QUANTITY_UPDATE_DEBOUNCE_MS);
+
+    updateTimeoutRef.current.set(lineId, timeout);
+  }, [removeFromCart, executeQuantityUpdate]);
+
+  /**
+   * Clear entire cart.
+   * Clears cartId in zustand persist → useCartSync returns empty.
+   */
+  const clearEntireCart = useCallback(() => {
+    clearCart();
+    toast.success('Cart cleared');
+  }, [clearCart]);
+
+  return {
+    addToCart,
+    updateQuantity,
+    removeFromCart,
+    clearCart: clearEntireCart,
+    isLoading: createCartMutation.isPending || addLinesMutation.isPending ||
+               updateLinesMutation.isPending || removeLinesMutation.isPending,
+  };
+}

package/templates/storefront-nextjs-shadcn/hooks/use-cart-sync.ts

@@ -0,0 +1,110 @@
+"use client";
+
+import { useEffect } from "react";
+import { useCart } from "@/lib/graphql/hooks";
+import { useCartStore } from "@/stores/cart-store";
+
+/**
+ * Mapped cart item for display components.
+ * Server is the single source of truth — no client-side items[].
+ */
+export interface CartItemData {
+  lineId: string;
+  variantId: string;
+  productId: string;
+  productHandle?: string;
+  productTitle: string;
+  variantTitle: string;
+  productType?: string;
+  quantity: number;
+  price: { amount: string; currencyCode: string };
+  image?: { url: string; altText?: string | null } | null;
+  available: boolean;
+}
+
+/**
+ * Primary data source for cart display.
+ *
+ * Reads cart from GraphQL (server as source of truth).
+ * Maps GraphQL lines to display-friendly CartItemData.
+ * Detects and auto-clears stale cart IDs.
+ */
+export function useCartSync() {
+  const cartId = useCartStore((state) => state.cartId);
+  const isHydrated = useCartStore((state) => state.isHydrated);
+  const setCartId = useCartStore((state) => state.setCartId);
+
+  const { data, isLoading, error, refetch } = useCart(cartId, {
+    enabled: isHydrated && Boolean(cartId),
+    retry: false,
+  });
+
+  const cart = data?.cart;
+
+  // Detect stale cart: cartId exists but server returns nothing
+  const isStaleCart = isHydrated && Boolean(cartId) && !isLoading && !cart;
+
+  // Auto-clear stale cartId
+  useEffect(() => {
+    if (isStaleCart) {
+      setCartId(null);
+    }
+  }, [isStaleCart, setCartId]);
+
+  // Map GraphQL lines to display-friendly items
+  const items: CartItemData[] = (cart?.lines ?? []).map((line: any) => {
+    const merchandiseTitle = line.merchandise.title ?? "";
+    // Hide generic variant names like "Default" or "Default Title"
+    const isDefaultVariant = /^default(\s+title)?$/i.test(merchandiseTitle);
+    const productTitle = line.productTitle || merchandiseTitle;
+    const variantTitle = isDefaultVariant ? "" : merchandiseTitle;
+
+    return {
+      lineId: line.id,
+      variantId: line.merchandise.id,
+      productId: line.productId || line.merchandise.id,
+      productHandle: line.productHandle,
+      productTitle,
+      variantTitle,
+      productType: line.productType,
+      quantity: line.quantity,
+      price: {
+        amount: line.merchandise.price.amount,
+        currencyCode: line.merchandise.price.currencyCode,
+      },
+      image: line.merchandise.image || null,
+      available: line.merchandise.available,
+    };
+  });
+
+  const totalQuantity = cart?.totalQuantity ?? 0;
+  const subtotal = cart?.cost?.subtotalAmount
+    ? parseFloat(cart.cost.subtotalAmount.amount)
+    : 0;
+  const total = cart?.cost?.totalAmount
+    ? parseFloat(cart.cost.totalAmount.amount)
+    : subtotal;
+  const currency = cart?.cost?.subtotalAmount?.currencyCode ?? "PLN";
+
+  // Discount data from server
+  const discountCodes: string[] = (cart?.discountCodes ?? [])
+    .filter((dc: any) => dc.applicable)
+    .map((dc: any) => dc.code);
+  const totalDiscount = subtotal - total;
+
+  return {
+    cart,
+    cartId,
+    items,
+    totalQuantity,
+    subtotal,
+    total,
+    currency,
+    discountCodes,
+    totalDiscount,
+    isLoading: !isHydrated || isLoading,
+    isStaleCart,
+    error,
+    refetch,
+  };
+}