@doswiftly/cli 0.1.18 → 0.1.20

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

@@ -1,241 +1,54 @@
 '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';
+import { useCallback, useEffect, useRef } from 'react';
+import { useCartStore, useCartStoreApi } from '@/stores/cart-store';
 
 // Debounce delay for quantity updates (prevents rate limiting)
 const QUANTITY_UPDATE_DEBOUNCE_MS = 500;
 
 /**
- * Hook for cart mutations — server-only, no local state manipulation.
+ * Hook for cart mutations — delegates orchestration to SDK cart store.
  *
- * All mutations go through GraphQL. React Query cache invalidation
- * (configured in hooks.ts) automatically updates all consumers via useCartSync.
+ * SDK handles: cart init, DI actions, error state, callbacks.
+ * Template handles: debounce, openCart UX.
  *
  * @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');
+ * await addToCart('variant-123', 1);
  * ```
  */
 export function useCartActions() {
-  const {
-    setCartId,
-    clearCart,
-    openCart,
-  } = useCartStore();
+  const api = useCartStoreApi();
+  const isLoading = useCartStore((s) => s.isLoading);
 
-  // GraphQL mutations
-  const createCartMutation = useCartCreate();
-  const addLinesMutation = useCartLinesAdd();
-  const updateLinesMutation = useCartLinesUpdate();
-  const removeLinesMutation = useCartLinesRemove();
-
-  // Debounce refs for quantity updates (prevents ThrottlerException on rapid clicks)
+  // Debounce refs for quantity updates
   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)
+   * Add item to cart by variant ID, delegates to SDK store.
    */
-  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]);
+  const addToCart = useCallback(async (variantId: string, quantity = 1) => {
+    await api.getState().addToCart([{ merchandiseId: variantId, quantity }]);
+    api.getState().openCart();
+  }, [api]);
 
   /**
-   * Execute the actual GraphQL update for a pending quantity change
+   * Execute the actual quantity update via SDK store.
    */
   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]);
+    await api.getState().updateQuantity([{ id: lineId, quantity }]);
+  }, [api]);
 
   /**
    * 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]);
+    await api.getState().removeFromCart([lineId]);
+  }, [api]);
 
   /**
-   * Update item quantity (debounced, takes lineId).
-   *
-   * Debounces GraphQL API calls to prevent ThrottlerException on rapid clicks.
+   * Update item quantity (debounced).
    * If quantity <= 0, removes the item instead.
    */
   const updateQuantity = useCallback((lineId: string, quantity: number) => {
@@ -244,43 +57,35 @@ export function useCartActions() {
       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);
-      }
+      updateTimeoutRef.current.delete(lineId);
+      executeQuantityUpdate(lineId, 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]);
+  // Cleanup pending debounce timeouts on unmount
+  useEffect(() => {
+    const timeouts = updateTimeoutRef.current;
+    return () => {
+      for (const timeout of timeouts.values()) {
+        clearTimeout(timeout);
+      }
+      timeouts.clear();
+    };
+  }, []);
 
   return {
     addToCart,
     updateQuantity,
     removeFromCart,
-    clearCart: clearEntireCart,
-    isLoading: createCartMutation.isPending || addLinesMutation.isPending ||
-               updateLinesMutation.isPending || removeLinesMutation.isPending,
+    clearCart: useCallback(() => api.getState().clearCart(), [api]),
+    isLoading,
   };
 }

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

@@ -0,0 +1,67 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { CartActions, CartData } from '@doswiftly/storefront-sdk/react';
+import { assertNoUserErrors } from '@doswiftly/storefront-sdk';
+import { useExecute } from '@/lib/graphql/client';
+import type { CartQuery, CartCreateMutation, CartLinesAddMutation, CartLinesUpdateMutation, CartLinesRemoveMutation } from '@/generated/graphql';
+import {
+  CartDocument,
+  CartCreateDocument,
+  CartLinesAddDocument,
+  CartLinesUpdateDocument,
+  CartLinesRemoveDocument,
+} from '@/generated/graphql';
+
+interface CartMutationResult {
+  cart: { id: string; totalQuantity: number } | null;
+  userErrors: Array<{ message: string; field?: string[]; code?: string }>;
+}
+
+function extractCartData(result: CartMutationResult): CartData {
+  assertNoUserErrors(result);
+  return { id: result.cart!.id, totalQuantity: result.cart!.totalQuantity };
+}
+
+/**
+ * CartActions DI implementation using template's GraphQL operations.
+ *
+ * Maps generated GraphQL documents to the SDK CartActions interface.
+ * Used by StoresProvider to wire createCartStore with template transport.
+ */
+export function useCartDI(): CartActions {
+  const execute = useExecute();
+
+  return useMemo(
+    (): CartActions => ({
+      fetchCart: async (cartId) => {
+        const data = await execute<CartQuery>(CartDocument.toString(), { id: cartId });
+        if (!data.cart) return null;
+        return { id: data.cart.id, totalQuantity: data.cart.totalQuantity };
+      },
+
+      createCart: async () => {
+        const data = await execute<CartCreateMutation>(CartCreateDocument.toString(), { input: {} });
+        assertNoUserErrors(data.cartCreate);
+        if (!data.cartCreate.cart) throw new Error('Failed to create cart');
+        return data.cartCreate.cart.id;
+      },
+
+      addLines: async (cartId, lines) => {
+        const data = await execute<CartLinesAddMutation>(CartLinesAddDocument.toString(), { cartId, lines });
+        return extractCartData(data.cartLinesAdd);
+      },
+
+      updateLines: async (cartId, lines) => {
+        const data = await execute<CartLinesUpdateMutation>(CartLinesUpdateDocument.toString(), { cartId, lines });
+        return extractCartData(data.cartLinesUpdate);
+      },
+
+      removeLines: async (cartId, lineIds) => {
+        const data = await execute<CartLinesRemoveMutation>(CartLinesRemoveDocument.toString(), { cartId, lineIds });
+        return extractCartData(data.cartLinesRemove);
+      },
+    }),
+    [execute],
+  );
+}

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

@@ -3,6 +3,8 @@
 import { useEffect } from "react";
 import { useCart } from "@/lib/graphql/hooks";
 import { useCartStore } from "@/stores/cart-store";
+import { useHydrated } from "@doswiftly/storefront-sdk/react";
+import type { CartLineFields } from "@/lib/graphql/fragments";
 
 /**
  * Mapped cart item for display components.
@@ -31,28 +33,30 @@ export interface CartItemData {
  */
 export function useCartSync() {
   const cartId = useCartStore((state) => state.cartId);
-  const isHydrated = useCartStore((state) => state.isHydrated);
-  const setCartId = useCartStore((state) => state.setCartId);
+  const clearCart = useCartStore((state) => state.clearCart);
+  const isHydrated = useHydrated();
 
-  const { data, isLoading, error, refetch } = useCart(cartId, {
+  const { data, isLoading, isSuccess, 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;
+  // Detect stale cart: cartId exists but server confirmed no cart (isSuccess + !cart).
+  // Using isSuccess instead of !isLoading prevents false positives when queries are
+  // cancelled by mutation optimistic updates (cancelled query → status='pending', not 'success').
+  const isStaleCart = isHydrated && Boolean(cartId) && isSuccess && !cart;
 
   // Auto-clear stale cartId
   useEffect(() => {
     if (isStaleCart) {
-      setCartId(null);
+      clearCart();
     }
-  }, [isStaleCart, setCartId]);
+  }, [isStaleCart, clearCart]);
 
   // Map GraphQL lines to display-friendly items
-  const items: CartItemData[] = (cart?.lines ?? []).map((line: any) => {
+  const items: CartItemData[] = (cart?.lines ?? []).map((line: CartLineFields) => {
     const merchandiseTitle = line.merchandise.title ?? "";
     // Hide generic variant names like "Default" or "Default Title"
     const isDefaultVariant = /^default(\s+title)?$/i.test(merchandiseTitle);
@@ -63,10 +67,10 @@ export function useCartSync() {
       lineId: line.id,
       variantId: line.merchandise.id,
       productId: line.productId || line.merchandise.id,
-      productHandle: line.productHandle,
+      productHandle: line.productHandle ?? undefined,
       productTitle,
       variantTitle,
-      productType: line.productType,
+      productType: line.productType ?? undefined,
       quantity: line.quantity,
       price: {
         amount: line.merchandise.price.amount,
@@ -88,8 +92,8 @@ export function useCartSync() {
 
   // Discount data from server
   const discountCodes: string[] = (cart?.discountCodes ?? [])
-    .filter((dc: any) => dc.applicable)
-    .map((dc: any) => dc.code);
+    .filter((dc) => dc.applicable)
+    .map((dc) => dc.code);
   const totalDiscount = subtotal - total;
 
   return {

package/templates/storefront-nextjs-shadcn/i18n/navigation.ts

@@ -0,0 +1,12 @@
+import { createNavigation } from 'next-intl/navigation';
+import { defaultLocale, localePrefix } from './routing';
+
+/**
+ * Navigation APIs for dynamic locales.
+ *
+ * No `locales` argument — any locale string accepted at runtime.
+ * Backend is SSOT for supportedLanguages.
+ * `defaultLocale` required for `as-needed` prefix mode (hides default in URL).
+ */
+export const { Link, redirect, usePathname, useRouter, getPathname } =
+  createNavigation({ defaultLocale, localePrefix });

package/templates/storefront-nextjs-shadcn/i18n/request.ts

@@ -0,0 +1,17 @@
+import { getRequestConfig } from 'next-intl/server';
+import { defaultLocale } from './routing';
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  // requestLocale is set by next-intl middleware (proxy.ts) which validates
+  // against dynamic locales from backend. If somehow invalid, fall back.
+  const locale = (await requestLocale) || defaultLocale;
+
+  let messages;
+  try {
+    messages = (await import(`../messages/${locale}.json`)).default;
+  } catch {
+    messages = (await import(`../messages/${defaultLocale}.json`)).default;
+  }
+
+  return { locale, messages };
+});

package/templates/storefront-nextjs-shadcn/i18n/routing.ts

@@ -0,0 +1,17 @@
+/**
+ * next-intl routing configuration (dynamic locales).
+ *
+ * - defaultLocale: from NEXT_PUBLIC_DEFAULT_LOCALE env var (set by CLI `doswiftly init`), fallback 'pl'.
+ * - localePrefix: 'as-needed' — default locale hidden in URL, others prefixed.
+ * - locales: NOT defined here — backend is SSOT for supportedLanguages.
+ *   - Middleware (proxy.ts) fetches supportedLanguages dynamically per-request.
+ *   - Navigation API (navigation.ts) accepts any locale string at runtime.
+ *   - Layout validates against backend's shop.supportedLanguages.
+ *
+ * No `defineRouting` — we export primitives consumed by createNavigation and createMiddleware.
+ */
+
+export const defaultLocale =
+  (process.env.NEXT_PUBLIC_DEFAULT_LOCALE as string) || 'pl';
+
+export const localePrefix = 'as-needed' as const;

package/templates/storefront-nextjs-shadcn/lib/auth/routes.ts

@@ -2,7 +2,7 @@
  * Auth Routes Configuration (SSOT)
  *
  * This file is the single source of truth for authentication routes.
- * Used by middleware.ts and can be imported by components if needed.
+ * Used by proxy.ts and can be imported by components if needed.
  *
  * IMPORTANT: Checkout is NOT protected to allow guest checkout (e-commerce best practice).
  * Users can optionally log in during checkout to use saved addresses.
@@ -16,6 +16,9 @@
  * export const guestOnlyRoutes = ['/auth/login', '/auth/register', '/auth/forgot-password'];
  */
 
+// Re-export platform constants and matching utility from SDK
+export { AUTH_COOKIE_NAME, matchesRoute } from '@doswiftly/storefront-sdk';
+
 /**
  * Routes that require authentication.
  * Unauthenticated users will be redirected to login.
@@ -30,12 +33,6 @@ export const protectedRoutes = ["/account"];
  */
 export const guestOnlyRoutes = ["/auth/login", "/auth/register"];
 
-/**
- * Cookie name for customer access token.
- * Must match the cookie name used by commerce-sdk.
- */
-export const AUTH_COOKIE_NAME = "customerAccessToken";
-
 /**
  * Default redirect paths
  */
@@ -45,13 +42,3 @@ export const redirects = {
   /** Where to redirect authenticated users trying to access guest-only routes */
   authenticated: "/account",
 } as const;
-
-/**
- * Check if a pathname matches any route in the list.
- * Supports both exact matches and prefix matches (e.g., /account matches /account/orders).
- */
-export function matchesRoute(pathname: string, routes: string[]): boolean {
-  return routes.some(
-    (route) => pathname === route || pathname.startsWith(`${route}/`)
-  );
-}