@doswiftly/cli 0.1.19 → 0.1.20

package/templates/storefront-nextjs-shadcn/hooks/index.ts

@@ -7,5 +7,6 @@ export type { LoginResult, LogoutResult, TokenRenewResult } from "./use-auth";
 export { useAuthSync } from "./use-auth-sync";
 export { useCartSync } from "./use-cart-sync";
 export { useCartActions } from "./use-cart-actions";
+export { useCartDI } from "./use-cart-di";
 export { useFilterParams } from "./use-filter-params";
 export type { UseFilterParamsReturn, UseFilterParamsOptions } from "./use-filter-params";

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

@@ -1,261 +1,54 @@
 'use client';
 
 import { useCallback, useEffect, useRef } from 'react';
-import { useQueryClient } from '@tanstack/react-query';
 import { useCartStore, useCartStoreApi } from '@/stores/cart-store';
-import { useCartCreate, useCartLinesAdd, useCartLinesUpdate, useCartLinesRemove } from '@/lib/graphql/hooks';
-import { queryKeys } from '@/lib/graphql/query-keys';
-import { toast } from 'sonner';
-import { StorefrontError } from '@doswiftly/storefront-sdk';
 
 // 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 queryClient = useQueryClient();
-  const cartStoreApi = useCartStoreApi();
-  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 = cartStoreApi.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: unknown) {
-      console.error('Cart creation failed:', error);
-      throw error;
-    }
-  }, [cartStoreApi, 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: unknown): boolean => {
-    if (error instanceof StorefrontError) {
-      const msg = error.message.toLowerCase();
-      return msg.includes('cart not found') || msg.includes('cart does not exist');
-    }
-    if (error instanceof Error) {
-      const msg = error.message.toLowerCase();
-      return msg.includes('cart not found') || msg.includes('cart does not exist');
-    }
-    return false;
-  };
-
-  /**
-   * 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 {
-      // Cancel in-flight cart queries to prevent stale data overwriting
-      await queryClient.cancelQueries({ queryKey: queryKeys.cart.all() });
-
-      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: unknown) {
-      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);
-      const message = error instanceof Error ? error.message : 'Failed to add to cart';
-      toast.error(message);
-      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 {
-      // Cancel in-flight cart queries to prevent race conditions
-      await queryClient.cancelQueries({ queryKey: queryKeys.cart.all() });
-
-      const currentCartId = cartStoreApi.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: unknown) {
-      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);
-      const message = error instanceof Error ? error.message : 'Failed to update quantity';
-      toast.error(message);
-    }
-  }, [cartStoreApi, queryClient, 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 = cartStoreApi.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: unknown) {
-      if (isCartNotFoundError(error)) {
-        console.warn('Cart expired during remove (caught), clearing stale cartId');
-        setCartId(null);
-        return;
-      }
-
-      console.error('Remove from cart failed:', error);
-      const message = error instanceof Error ? error.message : 'Failed to remove from cart';
-      toast.error(message);
-      throw error;
-    }
-  }, [cartStoreApi, 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) => {
@@ -264,23 +57,14 @@ 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);
@@ -294,25 +78,14 @@ export function useCartActions() {
         clearTimeout(timeout);
       }
       timeouts.clear();
-      pendingUpdatesRef.current.clear();
     };
   }, []);
 
-  /**
-   * 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,
+    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

@@ -33,7 +33,7 @@ export interface CartItemData {
  */
 export function useCartSync() {
   const cartId = useCartStore((state) => state.cartId);
-  const setCartId = useCartStore((state) => state.setCartId);
+  const clearCart = useCartStore((state) => state.clearCart);
   const isHydrated = useHydrated();
 
   const { data, isLoading, isSuccess, error, refetch } = useCart(cartId, {
@@ -51,9 +51,9 @@ export function useCartSync() {
   // 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: CartLineFields) => {

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/graphql/config.ts

@@ -30,3 +30,4 @@ export const graphqlConfig = {
   apiUrl: configApiUrl,
   shopSlug: configShopSlug,
 } as const;
+

package/templates/storefront-nextjs-shadcn/lib/graphql/hooks.ts

@@ -2,7 +2,7 @@
 
 import { useQuery, useMutation, useQueryClient, type UseQueryOptions, type UseMutationOptions } from '@tanstack/react-query';
 import { useExecute } from './client';
-import { useCurrencyStore, useAuthStore } from '@doswiftly/storefront-sdk/react';
+import { useCurrencyStore, useAuthStore, useLanguageStore } from '@doswiftly/storefront-sdk/react';
 import { normalizeConnection, type NormalizedConnection } from '@doswiftly/storefront-sdk';
 import { queryKeys } from './query-keys';
 import type { TypedDocumentString } from '@/generated/graphql';
@@ -34,6 +34,7 @@ import {
   CheckoutCompleteDocument,
   CheckoutGiftCardApplyDocument,
   CheckoutGiftCardRemoveDocument,
+  CheckoutGiftCardRecipientUpdateDocument,
   CustomerDocument,
   CustomerProfileDocument,
   CustomerOrderDocument,
@@ -106,6 +107,8 @@ import type {
   CheckoutGiftCardApplyMutationVariables,
   CheckoutGiftCardRemoveMutation,
   CheckoutGiftCardRemoveMutationVariables,
+  CheckoutGiftCardRecipientUpdateMutation,
+  CheckoutGiftCardRecipientUpdateMutationVariables,
   CustomerQuery,
   CustomerQueryVariables,
   CustomerProfileQuery,
@@ -173,12 +176,14 @@ export function useGraphQLQuery<TResult, TVariables>(
 ) {
   const execute = useExecute();
   const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
   const operationName = getOperationName(document as TypedDocumentString<unknown, unknown>);
-  const queryKey = [operationName, variables, currency];
+  const queryKey = [operationName, variables, currency, language];
 
   return useQuery({
     queryKey,
     queryFn: () => execute<TResult>(document.toString(), variables as Record<string, unknown>),
+    enabled: !!language && (options?.enabled ?? true),
     ...options,
   });
 }
@@ -223,11 +228,12 @@ export function useProduct(
 ) {
   const execute = useExecute();
   const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
 
   const isId = handleOrId.startsWith('gid://');
 
   return useQuery({
-    queryKey: queryKeys.products.detail(handleOrId, currency),
+    queryKey: queryKeys.products.detail(handleOrId, currency, language),
     queryFn: () => {
       const variables: ProductQueryVariables = isId
         ? { id: handleOrId }
@@ -280,9 +286,10 @@ export function useProducts(
 ) {
   const execute = useExecute();
   const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
 
   return useQuery({
-    queryKey: queryKeys.products.list(variables as Record<string, unknown>, currency),
+    queryKey: queryKeys.products.list(variables as Record<string, unknown>, currency, language),
     queryFn: async () => {
       const { sortKey: normalizedSortKey, reverse: normalizedReverse } = normalizeSortKey(variables?.sortKey);
 
@@ -325,11 +332,12 @@ export function useCollection(
 ) {
   const execute = useExecute();
   const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
 
   const isId = handleOrId.startsWith('gid://');
 
   return useQuery({
-    queryKey: queryKeys.collections.detail(handleOrId, currency),
+    queryKey: queryKeys.collections.detail(handleOrId, currency, language),
     queryFn: () => {
       const variables: CollectionQueryVariables = isId
         ? { id: handleOrId }
@@ -360,9 +368,10 @@ export function useCollections(
 ) {
   const execute = useExecute();
   const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
 
   return useQuery({
-    queryKey: queryKeys.collections.list(variables as Record<string, unknown>, currency),
+    queryKey: queryKeys.collections.list(variables as Record<string, unknown>, currency, language),
     queryFn: async () => {
       const graphqlVariables: CollectionsQueryVariables = {
         first: variables?.first ?? 20,
@@ -431,9 +440,10 @@ export function useCategories(
 ) {
   const execute = useExecute();
   const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
 
   return useQuery({
-    queryKey: queryKeys.categories.list(currency),
+    queryKey: queryKeys.categories.list(currency, language),
     queryFn: async () => {
       const data = await execute<CategoriesQuery>(CategoriesDocument.toString());
 
@@ -478,9 +488,10 @@ export function useAvailableFilters(
 ) {
   const execute = useExecute();
   const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
 
   return useQuery({
-    queryKey: queryKeys.filters.forContext(input as Record<string, unknown>, currency),
+    queryKey: queryKeys.filters.forContext(input as Record<string, unknown>, currency, language),
     queryFn: () => {
       const variables: AvailableFiltersQueryVariables = { input: input || null };
       return execute<AvailableFiltersQuery>(AvailableFiltersDocument.toString(), variables);
@@ -879,6 +890,28 @@ export function useCheckoutGiftCardRemove(
   });
 }
 
+/**
+ * Update gift card recipient data on checkout line item
+ */
+export function useCheckoutGiftCardRecipientUpdate(
+  options?: UseMutationOptions<CheckoutGiftCardRecipientUpdateMutation, Error, CheckoutGiftCardRecipientUpdateMutationVariables>
+) {
+  const execute = useExecute();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (variables: CheckoutGiftCardRecipientUpdateMutationVariables) =>
+      execute<CheckoutGiftCardRecipientUpdateMutation>(CheckoutGiftCardRecipientUpdateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
+    },
+    ...options,
+  });
+}
+
 // ============================================================================
 // CUSTOMER HOOKS
 // ============================================================================