@doswiftly/cli 0.1.1

package/templates/storefront-nextjs-shadcn/CART_INTEGRATION.md

@@ -0,0 +1,282 @@
+# Cart Integration with GraphQL
+
+This storefront template includes full GraphQL integration for cart operations. The cart system uses a hybrid approach:
+
+- **Local Store (Zustand)**: For immediate UI updates and optimistic rendering
+- **GraphQL API**: For persistence and server-side cart management
+
+## Quick Start
+
+### Using AddToCartButton
+
+The simplest way to add products to cart is using the `AddToCartButton` component:
+
+```tsx
+import { AddToCartButton } from "@/components/product/add-to-cart-button";
+
+<AddToCartButton
+  variantId={variant.id}
+  productId={product.id}
+  productHandle={product.handle}
+  productTitle={product.title}
+  variantTitle={variant.title}
+  price={variant.price}
+  image={variant.image}
+  available={variant.available}
+  quantity={1}
+/>
+```
+
+The button automatically:
+- Creates a cart if one doesn't exist
+- Adds the item to GraphQL cart
+- Updates local store for immediate UI feedback
+- Shows loading and success states
+- Displays error toasts if something fails
+
+### Using useCartActions Hook
+
+For more control, use the `useCartActions` hook directly:
+
+```tsx
+'use client';
+
+import { useCartActions } from "@/hooks/use-cart-actions";
+
+export function MyComponent() {
+  const { addToCart, updateQuantity, removeFromCart, isLoading } = useCartActions();
+  
+  const handleAdd = async () => {
+    await addToCart({
+      variantId: 'variant-123',
+      productId: 'product-456',
+      productTitle: 'T-Shirt',
+      variantTitle: 'Large / Blue',
+      price: { amount: '29.99', currencyCode: 'USD' },
+      quantity: 1
+    });
+  };
+  
+  return (
+    <button onClick={handleAdd} disabled={isLoading}>
+      Add to Cart
+    </button>
+  );
+}
+```
+
+## Cart Store
+
+The local cart store (`useCartStore`) provides immediate UI updates:
+
+```tsx
+import { useCartStore } from "@/stores/cart-store";
+
+const { items, getTotalItems, getTotalPrice, isOpen, openCart } = useCartStore();
+```
+
+**Note**: The store is automatically synced with GraphQL operations by `useCartActions`.
+
+## Cart Drawer
+
+The cart drawer shows the current cart state:
+
+```tsx
+import { CartDrawer } from "@/components/cart/cart-drawer";
+
+// In your layout or header
+<CartDrawer />
+```
+
+The drawer:
+- Opens automatically when items are added
+- Shows all cart items with images and prices
+- Allows quantity updates and item removal
+- Displays cart summary with totals
+- Provides checkout button
+
+## Cart Icon
+
+Add a cart icon to your header:
+
+```tsx
+import { CartIcon } from "@/components/cart/cart-icon";
+
+<CartIcon />
+```
+
+Shows item count badge and toggles the cart drawer.
+
+## GraphQL Operations
+
+The following GraphQL mutations are available:
+
+### Create Cart
+
+```graphql
+mutation CartCreate($input: CartCreateInput) {
+  cartCreate(input: $input) {
+    cart {
+      id
+      # ... cart fields
+    }
+    userErrors {
+      message
+      code
+    }
+  }
+}
+```
+
+### Add Lines
+
+```graphql
+mutation CartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
+  cartLinesAdd(cartId: $cartId, lines: $lines) {
+    cart {
+      id
+      # ... cart fields
+    }
+    userErrors {
+      message
+      code
+    }
+  }
+}
+```
+
+### Update Lines
+
+```graphql
+mutation CartLinesUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+  cartLinesUpdate(cartId: $cartId, lines: $lines) {
+    cart {
+      id
+      # ... cart fields
+    }
+    userErrors {
+      message
+      code
+    }
+  }
+}
+```
+
+### Remove Lines
+
+```graphql
+mutation CartLinesRemove($cartId: ID!, $lineIds: [ID!]!) {
+  cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
+    cart {
+      id
+      # ... cart fields
+    }
+    userErrors {
+      message
+      code
+    }
+  }
+}
+```
+
+## Cart Persistence
+
+- Cart ID is stored in `localStorage` as `cartId`
+- Cart data is persisted on the server via GraphQL
+- Local store items are synced with server on page load
+- Cart survives page refreshes and browser restarts
+
+## Error Handling
+
+All cart operations include error handling:
+
+- Network errors show toast notifications
+- GraphQL `userErrors` are displayed to users
+- Failed operations revert local store changes
+- Retry logic for transient failures
+
+## Currency Support
+
+Cart prices automatically use the user's selected currency:
+
+- Currency is included in GraphQL request headers
+- Prices are converted server-side
+- Exchange rates are locked for 24 hours
+- Currency changes trigger cart refetch
+
+## Testing
+
+To test cart functionality:
+
+1. Add items to cart
+2. Check browser DevTools → Application → Local Storage for `cartId`
+3. Check Network tab for GraphQL mutations
+4. Verify cart persists after page refresh
+5. Test currency switching
+
+## Troubleshooting
+
+### Cart not persisting
+
+- Check if `cartId` exists in localStorage
+- Verify GraphQL API is accessible
+- Check browser console for errors
+
+### Items not showing in cart
+
+- Ensure `CartDrawer` is included in layout
+- Check if cart store is initialized
+- Verify GraphQL mutations are successful
+
+### Currency not updating
+
+- Check if `CurrencyProvider` is in layout
+- Verify currency store is initialized
+- Check GraphQL headers include `X-Preferred-Currency`
+
+## Advanced Usage
+
+### Custom Cart Logic
+
+You can extend the cart system by:
+
+1. Adding custom fields to cart items
+2. Implementing discount code validation
+3. Adding shipping cost calculation
+4. Integrating with checkout flow
+
+### Server-Side Cart
+
+For server-side cart operations (e.g., in API routes):
+
+```typescript
+import { getClient } from "@/lib/graphql/server";
+import { CartDocument } from "@/generated/graphql";
+
+export async function GET(request: Request) {
+  const cartId = request.headers.get('x-cart-id');
+  const client = getClient();
+  
+  const { cart } = await client.request(CartDocument, { id: cartId });
+  
+  return Response.json({ cart });
+}
+```
+
+## Migration from Local-Only Cart
+
+If you have an existing local-only cart implementation:
+
+1. Replace `addItem` calls with `useCartActions().addToCart`
+2. Update `AddToCartButton` props to include all required fields
+3. Add `Toaster` to your layout for error notifications
+4. Test cart persistence across page refreshes
+
+## API Reference
+
+See the following files for detailed API documentation:
+
+- `hooks/use-cart-actions.ts` - Cart operations hook
+- `stores/cart-store.ts` - Local cart store
+- `lib/graphql/hooks.ts` - GraphQL cart hooks
+- `components/cart/` - Cart UI components

package/templates/storefront-nextjs-shadcn/CLAUDE.md

@@ -0,0 +1,96 @@
+# Storefront Template - Development Guide
+
+Ten plik jest synchronizowany do `storefronts/test-shop/` przez `pnpm sync:storefront:watch`.
+
+## Architektura
+
+```
+app/                    # Next.js 15 App Router
+├── layout.tsx          # Root layout z providers
+├── page.tsx            # Homepage
+├── products/           # Strony produktow
+├── collections/        # Strony kolekcji
+├── cart/               # Koszyk
+├── checkout/           # Checkout
+├── account/            # Panel klienta
+└── auth/               # Login/Register
+
+components/
+├── product/            # ProductCard, ProductGrid, AddToCartButton
+├── cart/               # CartDrawer, CartItem, CartSummary
+├── auth/               # LoginForm, RegisterForm
+├── layout/             # Header, Footer, Navigation
+├── ui/                 # shadcn/ui components
+└── providers/          # QueryProvider, CurrencyProvider, ThemeProvider
+
+lib/
+├── graphql/
+│   ├── server.ts       # SSR helpers z React cache()
+│   ├── client.ts       # Client-side GraphQL client
+│   └── hooks.ts        # React Query hooks
+└── currency/           # Currency management
+
+stores/                 # Zustand stores
+├── cart-store.ts       # Koszyk (persist localStorage)
+├── currency-store.ts   # Waluta (persist cookies)
+└── auth-store.ts       # Autentykacja
+
+generated/
+└── graphql.ts          # Auto-generowane typy
+```
+
+## Data Fetching
+
+### Server Components (lib/graphql/server.ts):
+```typescript
+import { fetchProducts, fetchProduct } from '@/lib/graphql/server';
+
+// W async Server Component
+const { products, pageInfo } = await fetchProducts({ first: 20 });
+const { product } = await fetchProduct(handle);
+```
+
+### Client Components (lib/graphql/hooks.ts):
+```typescript
+'use client';
+import { useProducts, useCart, useCartLinesAdd } from '@/lib/graphql/hooks';
+
+const { data, isLoading } = useProducts({ first: 20 });
+const addLines = useCartLinesAdd();
+```
+
+## Zustand Stores
+
+### Cart Store:
+```typescript
+import { useCartStore } from '@/stores/cart-store';
+
+const { items, addItem, removeItem, getTotalItems, getTotalPrice } = useCartStore();
+```
+
+### Currency Store:
+```typescript
+import { useCurrencyStore } from '@/stores/currency-store';
+
+const { currency, setCurrency, supportedCurrencies } = useCurrencyStore();
+```
+
+## Konwencje
+
+1. **Client vs Server**: Dodaj `"use client"` tylko gdy potrzebne (hooks, interaktywnosc)
+2. **Typy**: Zawsze definiuj interfejsy dla props
+3. **Styling**: Uzywaj `cn()` dla laczenia klas Tailwind
+4. **Obrazki**: next/image z alt i priority dla LCP
+5. **Formularze**: Zod dla walidacji
+
+## GraphQL Operations
+
+Operacje sa zdefiniowane w:
+```
+packages/backend/src/commerce/storefront-graphql/operations/
+├── queries.graphql
+├── mutations.graphql
+└── fragments.graphql
+```
+
+Aby poznac dostepne operacje, przeczytaj te pliki.

package/templates/storefront-nextjs-shadcn/GRAPHQL_DOCUMENT_NAMES.md

@@ -0,0 +1,190 @@
+# GraphQL Document Names Reference
+
+## ⚠️ WAŻNE: Konwencja nazewnictwa
+
+**WSZYSTKIE** GraphQL dokumenty w `generated/graphql.ts` mają suffix `Document`!
+
+```typescript
+// ✅ POPRAWNIE
+import { CustomerCreateDocument } from "@/generated/graphql";
+client.request(CustomerCreateDocument, { input });
+
+// ❌ BŁĄD - nie istnieje!
+import { CustomerCreate } from "@/generated/graphql";
+```
+
+---
+
+## 📋 Kompletna lista dostępnych dokumentów
+
+### 🔍 Queries (Zapytania)
+
+#### Collections & Categories
+- ✅ `GetFeaturedCollectionsDocument` - Featured collections
+- ✅ `GetCollectionWithProductsDocument` - Collection z produktami
+- ✅ `GetAllCollectionsDocument` - Wszystkie collections
+- ✅ `CollectionDocument` - Pojedyncza collection
+- ✅ `CollectionsDocument` - Lista collections
+- ✅ `CategoryDocument` - Pojedyncza kategoria
+- ✅ `CategoriesDocument` - Lista kategorii
+
+#### Products
+- ✅ `GetFeaturedProductsDocument` - Featured produkty
+- ✅ `GetProductWithReviewsDocument` - Produkt z recenzjami
+- ✅ `SearchProductsWithFiltersDocument` - Wyszukiwanie z filtrami
+- ✅ `ProductDocument` - Pojedynczy produkt
+- ✅ `ProductsDocument` - Lista produktów
+- ✅ `ProductSearchDocument` - Wyszukiwanie produktów
+
+#### Cart
+- ✅ `CartDocument` - Koszyk
+
+#### Shop
+- ✅ `ShopDocument` - Informacje o sklepie
+
+---
+
+### ✏️ Mutations (Mutacje)
+
+#### Customer Authentication
+- ✅ `CustomerCreateDocument` - Rejestracja nowego klienta
+- ✅ `CustomerLoginDocument` - Logowanie
+- ✅ `CustomerLogoutDocument` - Wylogowanie
+- ✅ `CustomerTokenRenewDocument` - Odnowienie tokenu
+
+#### Customer Profile
+- ✅ `CustomerUpdateDocument` - Aktualizacja profilu
+
+#### Customer Addresses
+- ✅ `CustomerAddressCreateDocument` - Dodanie adresu
+- ✅ `CustomerAddressUpdateDocument` - Edycja adresu
+- ✅ `CustomerAddressDeleteDocument` - Usunięcie adresu
+- ✅ `CustomerDefaultAddressUpdateDocument` - Ustawienie domyślnego adresu
+
+#### Customer Password
+- ✅ `CustomerPasswordRecoverDocument` - Odzyskiwanie hasła (wysyłka emaila)
+- ✅ `CustomerPasswordResetDocument` - Reset hasła (z tokenem)
+
+#### Cart Operations
+- ✅ `CartCreateDocument` - Utworzenie koszyka
+- ✅ `CartLinesAddDocument` - Dodanie produktów do koszyka
+- ✅ `CartLinesUpdateDocument` - Aktualizacja ilości w koszyku
+- ✅ `CartLinesRemoveDocument` - Usunięcie produktów z koszyka
+- ✅ `CartDiscountCodesUpdateDocument` - Dodanie kodu rabatowego
+- ✅ `CartBuyerIdentityUpdateDocument` - Aktualizacja danych kupującego
+- ✅ `CartNoteUpdateDocument` - Dodanie notatki do zamówienia
+
+---
+
+## 🎯 Przykłady użycia
+
+### Client-side (React Query)
+
+```typescript
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { getGraphQLClient } from "@/lib/graphql/client";
+import { 
+  CustomerCreateDocument,
+  CustomerLoginDocument,
+  CartCreateDocument 
+} from "@/generated/graphql";
+
+const client = getGraphQLClient();
+
+// Mutation
+const registerMutation = useMutation({
+  mutationFn: async (input) => {
+    return client.request(CustomerCreateDocument, { input });
+  },
+});
+
+// Query
+const { data } = useQuery({
+  queryKey: ["cart", cartId],
+  queryFn: () => client.request(CartDocument, { id: cartId }),
+});
+```
+
+### Server-side (Next.js Server Components)
+
+```typescript
+import { getClient } from "@/lib/graphql/server";
+import { ProductDocument, CollectionsDocument } from "@/generated/graphql";
+
+export async function getProduct(handle: string) {
+  const client = await getClient();
+  return client.request(ProductDocument, { handle });
+}
+
+export async function getCollections() {
+  const client = await getClient();
+  return client.request(CollectionsDocument, { first: 10 });
+}
+```
+
+---
+
+## 🔧 Najczęstsze błędy
+
+### ❌ Błąd 1: Brak suffixu "Document"
+```typescript
+// BŁĄD
+import { CustomerCreate } from "@/generated/graphql";
+
+// POPRAWNIE
+import { CustomerCreateDocument } from "@/generated/graphql";
+```
+
+### ❌ Błąd 2: Niepoprawna nazwa dokumentu
+```typescript
+// BŁĄD
+import { CustomerRecoverDocument } from "@/generated/graphql";
+
+// POPRAWNIE
+import { CustomerPasswordRecoverDocument } from "@/generated/graphql";
+```
+
+### ❌ Błąd 3: Używanie nieistniejących dokumentów
+```typescript
+// BŁĄD - CheckoutCreate nie istnieje w Storefront API
+import { CheckoutCreateDocument } from "@/generated/graphql";
+
+// POPRAWNIE - Używaj Cart API
+import { CartCreateDocument } from "@/generated/graphql";
+```
+
+---
+
+## 📝 Notatki
+
+1. **Shopify Storefront API** nie ma:
+   - ❌ `CheckoutCreateDocument` - **NIE ISTNIEJE!** Używaj `CartCreateDocument` + `cart.checkoutUrl`
+   - ❌ Bezpośredniego API dla zamówień - używaj Customer API
+   - ❌ `CheckoutDocument` - używaj `CartDocument` który zawiera `checkoutUrl`
+
+2. **Categories vs Collections**:
+   - `CategoriesDocument` - custom kategorie (jeśli zaimplementowane)
+   - `CollectionsDocument` - natywne Shopify collections (zalecane)
+
+3. **Password Recovery**:
+   - `CustomerPasswordRecoverDocument` - wysyła email z linkiem
+   - `CustomerPasswordResetDocument` - resetuje hasło z tokenem z emaila
+
+4. **Cart vs Checkout**:
+   - Shopify Storefront API v2024+ używa Cart API zamiast Checkout API
+   - `CartDocument` zawiera `checkoutUrl` do przekierowania na checkout
+
+---
+
+## 🔄 Aktualizacja dokumentów
+
+Jeśli dodajesz nowe GraphQL queries/mutations:
+
+1. Dodaj je do `graphql/` folder
+2. Uruchom codegen: `npm run graphql:codegen`
+3. Sprawdź wygenerowane nazwy w `generated/graphql.ts`
+4. Zaktualizuj tę dokumentację
+
+---
+
+**Ostatnia aktualizacja:** 2024-12-10