@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/skills/storefront-best-practices/reference/connecting-to-backend.md

@@ -1,391 +0,0 @@
-# Connecting to Backend
-
-## Contents
-
-- [Overview](#overview)
-- [Detecting the Backend](#detecting-the-backend-critical)
-- [Framework Detection](#framework-detection)
-- [Environment Configuration](#environment-configuration)
-- [Backend-Specific Integration](#backend-specific-integration)
-- [Authentication Patterns](#authentication-patterns)
-- [Cart State Management](#cart-state-management)
-- [Error Handling for Ecommerce](#error-handling-for-ecommerce)
-- [Performance Patterns](#performance-patterns)
-  - [Data Fetching with TanStack Query](#data-fetching-with-tanstack-query-recommended)
-- [Checklist](#checklist)
-
-## Overview
-
-Best practices for connecting storefront to ecommerce backend APIs. Framework-agnostic patterns for authentication, cart state management, error handling, and performance optimization.
-
-**For Medusa-specific integration**, see `reference/medusa.md` for SDK setup, pricing, regions, and Medusa patterns.
-
-## Detecting the Backend (CRITICAL)
-
-**Before implementing any backend integration, identify which ecommerce backend is being used.**
-
-### Detection Strategy
-
-**1. Check for monorepo structure:**
-```bash
-# Look for backend directory
-ls -la ../backend
-ls -la ./backend
-ls -la ../../apps/backend
-```
-
-Common monorepo patterns:
-- `/apps/storefront` + `/apps/backend`
-- `/frontend` + `/backend`
-- `/packages/web` + `/packages/api`
-
-**2. Check package.json dependencies:**
-```json
-{
-  "dependencies": {
-    "@medusajs/js-sdk": "...",  // Medusa
-    // check other ecommerce frameworks...
-  }
-}
-```
-
-**3. Check environment variables:**
-```bash
-# Look in .env, .env.local, .env.example
-grep -i "api\|backend\|medusa\|shopify\|commerce" .env*
-```
-
-Common patterns:
-- `NEXT_PUBLIC_MEDUSA_BACKEND_URL` → Medusa
-- Custom `API_URL` or `BACKEND_URL` → Other backend
-
-**4. If unsure, ASK THE USER:**
-
-```markdown
-I need to connect to the ecommerce backend. Which backend are you using?
-
-Options:
-- Medusa (open-source headless commerce)
-- Custom backend
-- Other
-```
-
-### Backend Documentation and MCP Servers
-
-**ALWAYS refer to the backend's official documentation or MCP server for:**
-
-- API endpoints and data structures
-- Authentication requirements
-- SDK usage and installation
-- Environment configuration
-- Rate limits and best practices
-
-**For Medusa:**
-- Documentation: https://docs.medusajs.com
-- MCP Server: If available, use Medusa MCP server for real-time API information
-- JS SDK docs: https://docs.medusajs.com/resources/js-sdk
-- See `reference/medusa.md` for detailed integration guide
-
-**For other backends:**
-- Check the backend's documentation portal
-- Look for MCP server if available
-- Verify API endpoints and authentication methods
-- Never assume API structure without verification
-
-**Important:** Do not guess API endpoints or data formats. Always verify with documentation or ask the user to confirm the backend's API structure.
-
-## Framework Detection
-
-Identify the frontend framework to determine appropriate data fetching patterns:
-
-**Next.js:**
-- App Router: Server Components (async/await), Client Components (useEffect/TanStack Query)
-- Pages Router: getServerSideProps/getStaticProps (server), useEffect (client)
-
-**SvelteKit:**
-- Load functions for server-side data
-- Client-side: fetch in component lifecycle
-
-**TanStack Start:**
-- Server functions for server-side data
-- Client-side: fetch with React hooks
-
-**General Rule:**
-- **Server-side for initial load**: SEO, performance, security (product pages, listings)
-- **Client-side for interactions**: Cart, filters, search, user-specific data
-
-## Environment Configuration
-
-**Store API URLs and keys in environment variables:**
-
-```typescript
-// .env.local
-NEXT_PUBLIC_API_URL=https://api.example.com
-NEXT_PUBLIC_PUBLISHABLE_KEY=pk_...
-```
-
-**Framework-specific prefixes:**
-- Next.js: `NEXT_PUBLIC_` for client-side
-- SvelteKit: `PUBLIC_` for client-side
-- Vite-based (TanStack Start): `VITE_` for client-side
-
-**Security:**
-- ❌ NEVER expose secret/admin keys in client-side code
-- ✅ Publishable keys are safe for client (Medusa, Stripe)
-- ✅ Secret keys only in server-side code or environment
-
-## Backend-Specific Integration
-
-### Medusa Backend
-
-**For complete Medusa integration guide**, see `reference/medusa.md` which covers:
-- SDK installation and setup
-- Vite configuration (for TanStack Start, etc.)
-- TypeScript types from `@medusajs/types`
-- Price display (never divide by 100)
-- Common operations (products, cart, categories, customers)
-- Custom endpoints
-- Region state management
-- Error handling with SDK
-
-### Other Backends
-
-For non-Medusa backends (custom APIs, third-party platforms):
-
-**1. Consult backend's API documentation** for:
-   - Authentication requirements
-   - Available endpoints
-   - Request/response formats
-   - SDK availability (check if official SDK exists)
-
-**2. Use backend's official SDK if available** - provides type safety, error handling, and best practices
-
-**3. If no SDK, create API client wrapper:**
-   - Centralize API calls in one module
-   - Group by resource (products, cart, customers, orders)
-   - Handle authentication (include tokens/cookies)
-   - Handle errors consistently
-   - Use native fetch or axios
-
-## Authentication Patterns
-
-### Customer Authentication
-
-**Session-based (cookies):**
-- Backend manages session via cookies
-- No manual token management needed
-- Works across page refreshes
-- Common in traditional ecommerce backends
-- Call backend login endpoint, check auth state, logout methods
-
-**Token-based (JWT, OAuth):**
-- Store token in localStorage or secure cookie after login
-- Include token in Authorization header for all authenticated requests
-- Common in headless/API-first backends
-- Format: `Authorization: Bearer {token}`
-
-### Protecting Customer Routes
-
-**Check authentication before rendering customer-specific pages** (account, orders, addresses):
-
-- **Server-side**: Check auth in server functions (getServerSideProps, load functions, etc.). Redirect to login if not authenticated.
-- **Client-side**: Check auth state on mount. Redirect to login if not authenticated.
-
-Use framework-specific auth patterns for redirects.
-
-### Cart Access Pattern
-
-**Guest carts:**
-- Store cart ID in localStorage or cookie
-- Check for existing cart ID on app load
-- Create new cart if none exists
-- Allows shopping without account
-- Persists across sessions
-
-**Logged-in carts:**
-- Associate cart with customer account
-- Syncs across devices
-- **CRITICAL: Merge guest cart with customer cart on login** - Transfer guest cart items to customer's account cart, then clear guest cart ID from localStorage
-
-## Cart State Management
-
-**Critical ecommerce pattern**: Cart must be accessible throughout the app.
-
-### Global Cart State
-
-**React Context (for simple cases):**
-- Create CartContext and CartProvider
-- Store cart state and cartId (from localStorage)
-- Load cart on mount if cartId exists
-- Provide methods: addItem, removeItem, updateQuantity, clearCart
-- Update cart state after each operation
-
-**State management libraries (Zustand, Redux):**
-- Use for complex state requirements
-- Better for large applications
-- Easier to debug with DevTools
-- Same pattern: Store cart, provide actions, sync with backend
-
-**Key requirements:**
-- Cart accessible from any component
-- Real-time cart count updates
-- Optimistic UI updates (update UI immediately, sync with backend)
-
-### Cart Cleanup After Order Placement (CRITICAL)
-
-**IMPORTANT: After order is successfully placed, you MUST reset the cart state.**
-
-**Common issue:** Cart popup and global cart state still show old items after order completion. This happens when cart state isn't cleared after checkout.
-
-**Required cleanup actions:**
-
-1. **Clear cart from global state** - Reset cart state to null/empty in Context/Zustand/Redux
-2. **Clear localStorage cart ID** - Remove cart ID: `localStorage.removeItem('cart_id')`
-3. **Invalidate cart queries** - If using TanStack Query: `queryClient.invalidateQueries({ queryKey: ['cart'] })`
-4. **Update cart count to 0** - Navbar and UI should reflect empty cart
-
-**When to clear:**
-- After successful order placement (order confirmed)
-- On navigation to order confirmation page
-- Before redirecting to thank you page
-
-**Why this is critical:**
-- Prevents "phantom cart" from appearing in cart popup after order
-- Ensures clean state for next shopping session
-- Improves UX by not showing old cart items
-
-## Error Handling for Ecommerce
-
-### Ecommerce-Specific Errors
-
-**Out of stock:**
-- Catch errors when adding to cart
-- Check for "out of stock" or "inventory" in error message
-- Show user-friendly message: "Sorry, this item is now out of stock"
-- Update product availability UI to show out of stock
-
-**Price changed during checkout:**
-- Compare cart total with expected total
-- If different, show warning: "Prices have been updated. Please review your cart."
-- Highlight changed prices in cart
-
-**Payment failed:**
-- Catch errors during order completion
-- Check for specific payment errors: payment_declined, insufficient_funds, etc.
-- Show specific messages:
-  - Payment declined → "Payment declined. Please try a different payment method."
-  - Insufficient funds → "Insufficient funds. Please use a different card."
-  - Generic → "Payment failed. Please try again or contact support."
-
-**Session expired:**
-- Catch 401/Unauthorized errors
-- Clear auth state
-- Redirect to login with message: "Your session has expired. Please log in again."
-
-### User-Friendly Error Messages
-
-**Transform technical errors to clear messages:**
-- Network/fetch errors → "Unable to connect. Please check your internet connection."
-- Timeout errors → "Request timed out. Please try again."
-- Inventory errors → "This item is no longer available in the requested quantity."
-- Generic fallback → "Something went wrong. Please try again or contact support."
-
-**Pattern**: Check error message or status code, map to user-friendly message, show in UI (toast, banner, inline).
-
-## Performance Patterns
-
-### Data Fetching with TanStack Query (RECOMMENDED)
-
-**Use TanStack Query for all backend API calls** - provides automatic caching, request deduplication, loading/error states, and optimistic updates.
-
-**Installation:** `npm install @tanstack/react-query`
-
-**Setup:**
-- Create QueryClient with default options (staleTime: 5 min, retry: 1)
-- Wrap app with QueryClientProvider
-
-**Query pattern (for fetching data):**
-- Use `useQuery` with queryKey and queryFn
-- queryKey: Array with resource and identifier `['products', categoryId]`
-- queryFn: API call function
-- Returns: `data`, `isLoading`, `error`
-- Use for: Products, cart, customer data, categories
-
-**Mutation pattern (for modifying data):**
-- Use `useMutation` with mutationFn
-- mutationFn: API operation (add to cart, update, delete)
-- onSuccess: Update cache or invalidate queries
-- Returns: `mutate` function, `isPending` state
-- Use for: Add to cart, remove from cart, update quantities, place order
-
-**Benefits:**
-- Automatic caching (no manual cache management)
-- Built-in loading/error states
-- Request deduplication
-- Optimistic updates (update UI before server responds)
-- Cache invalidation strategies
-
-**Ecommerce-specific usage:**
-- Products: Long stale time (5-10 min) - products don't change often
-- Cart: Short or no stale time - prices/inventory can change
-- Categories: Long stale time - rarely change
-
-### Caching Strategy
-
-**Client-side caching:**
-- TanStack Query handles automatically with `staleTime` and `cacheTime`
-- Configure globally or per-query
-- Product data: 5-10 min stale time
-- Cart data: Fresh on every fetch
-- Categories: Long stale time
-
-**Server-side caching (framework-specific):**
-- Next.js: Use `revalidate` export or cache configuration
-- Set revalidation period (e.g., 300 seconds for product pages)
-- Static generation with ISR for product pages
-
-### Request Deduplication
-
-TanStack Query and modern frameworks handle this automatically - multiple components requesting same data result in single request.
-
-### Pagination Pattern
-
-**Offset-based:** Pass limit and offset parameters to API `limit: 24, offset: page * 24`
-
-**Cursor-based (better performance):** Pass limit and cursor (last item ID) `limit: 24, cursor: lastProductId`
-
-Check backend documentation for supported pagination type.
-
-## Checklist
-
-**Essential backend integration:**
-
-- [ ] Backend detected (Medusa, Shopify, custom, etc.)
-- [ ] Environment variables configured (API URL, keys)
-- [ ] Framework-specific data fetching patterns identified
-- [ ] **RECOMMENDED: TanStack Query installed and configured for API calls**
-- [ ] Server-side fetching for product pages (SEO)
-- [ ] Client-side fetching for cart and user interactions (use TanStack Query)
-- [ ] Authentication flow implemented (login/logout)
-- [ ] Cart ID persisted in localStorage or cookies
-- [ ] Global cart state management (context or store)
-- [ ] Cart count synced across app
-- [ ] Optimistic UI updates for cart operations
-- [ ] Error handling for out of stock scenarios
-- [ ] Error handling for payment failures
-- [ ] Session expiration handling (redirect to login)
-- [ ] User-friendly error messages (not technical)
-- [ ] Caching strategy for product data
-- [ ] Stock availability checks before checkout
-- [ ] Price change detection and warnings
-
-**For Medusa backends, also check:**
-- [ ] Medusa SDK installed (`@medusajs/js-sdk` + `@medusajs/types`)
-- [ ] SDK initialized with baseUrl and publishableKey
-- [ ] Vite SSR config added (if using TanStack Start/Vite)
-- [ ] Using official types from `@medusajs/types`
-- [ ] Not dividing prices by 100 (display as-is)
-- [ ] Region context implemented for multi-region stores
-- [ ] Region passed to cart and product queries
-
-See `reference/medusa.md` for complete Medusa integration guide.

package/skills/storefront-best-practices/reference/features/promotions.md

@@ -1,307 +0,0 @@
-# Promotions Feature
-
-## Contents
-
-- [Overview](#overview)
-- [Promotion Types and When to Use](#promotion-types-and-when-to-use)
-- [Sale Price Display](#sale-price-display)
-- [Promo Code Input](#promo-code-input)
-- [Free Shipping Threshold](#free-shipping-threshold)
-- [Promotional Banners](#promotional-banners)
-- [Countdown Timers](#countdown-timers)
-- [Mobile Considerations](#mobile-considerations)
-- [Checklist](#checklist)
-
-## Overview
-
-Promotions are temporary price reductions, discounts, or special offers designed to drive sales and incentivize purchases. Effective promotion UI clearly communicates value, creates urgency, and makes redemption easy.
-
-**Backend Integration (CRITICAL):**
-
-All promotion logic and data must come from the ecommerce backend. Do this based on backend integrated. Fetch active promotions, discount codes, and price rules from backend API. Never hardcode promotion logic in frontend.
-
-### Key Ecommerce Requirements
-
-- Clear discount communication (strikethrough pricing, percentage off)
-- Promo code input (cart/checkout)
-- Free shipping threshold progress (increase AOV)
-- Countdown timers (create urgency)
-- Automatic discount application
-- Sale badges (product discovery)
-
-### Purpose
-
-**Conversion optimization:**
-- Drive sales and increase conversion rate
-- Increase average order value (free shipping thresholds, tiered discounts)
-- Acquire new customers (first-order discounts)
-- Create urgency (limited-time offers)
-- Clear inventory (seasonal sales)
-- Reward loyalty (VIP codes, member discounts)
-
-## Promotion Types and When to Use
-
-### Sales (Price Reductions)
-
-**What it is**: Select products with reduced prices, automatically applied. No code needed.
-
-**Use when:**
-- Seasonal sales (Black Friday, holiday sales)
-- Clearance or end-of-season inventory
-- Product-specific promotions
-- You want reduced prices visible on product pages (increases click-through)
-
-**Display:**
-- Strikethrough original price (provides context for savings)
-- Sale price bold and prominent (red or brand color)
-- Sale badge on product cards ("Sale", "30% Off")
-
-**Medusa implementation:**
-Use Price Lists with special prices for products. Provides automatic strikethrough pricing in cart and on product pages.
-
-### Discount Codes
-
-**What it is**: Customer enters code to unlock discount (percentage, fixed amount, or free shipping).
-
-**Use when:**
-- Newsletter signups ("Get 10% off with WELCOME10")
-- VIP or loyalty program members (exclusive codes)
-- Targeted marketing campaigns (email, social media)
-- First-time customer incentives
-- Friends and family discounts (limited distribution)
-
-**Display:**
-- Promo code input field in cart/checkout
-- Success message: "Code applied: WELCOME10"
-- Discount shown in order summary with code name
-- Remove option (X icon or "Remove" link)
-
-**Medusa implementation:**
-Discount/promo code system with advanced logic (order-level discounts, usage limits, expiration dates).
-
-### Automatic Discounts
-
-**What it is**: Discount automatically applied when conditions met. No code entry required.
-
-**Use when:**
-- Free shipping thresholds ("Free shipping over $50")
-- Volume discounts ("Spend $100, get $20 off")
-- Buy One Get One (BOGO) offers
-- Encouraging larger cart values (increase AOV)
-
-**Display:**
-- Banner announcing the promotion
-- Progress indicator toward threshold (see Free Shipping Threshold section)
-- "Discount applied" message in cart
-- Automatic addition to order summary
-
-### Buy X, Get Y (BOGO)
-
-**What it is**: Purchase certain products to unlock free/discounted items.
-
-**Use when:**
-- Moving inventory (clear out slow-moving products)
-- Cross-selling related products ("Buy sunscreen, get beach bag 50% off")
-- Increasing units per transaction
-
-**Display:**
-- Clear promotion text on product page ("Buy 2, Get 1 Free")
-- Free/discounted item shown in cart with explanation
-- Discount line in order summary
-
-**Medusa implementation:**
-Buy X Get Y automatic discount. Free/discounted item must be added to cart to activate.
-
-## Sale Price Display
-
-### Strikethrough Pricing Pattern
-
-**Format:**
-```
-$49.99  $34.99
-(Original, strikethrough)  (Sale price, bold)
-```
-
-**Design:**
-- Original price: Strikethrough, muted gray color, smaller
-- Sale price: Bold, larger, red or accent color
-- Clear visual hierarchy (sale price dominates)
-
-**Placement:**
-- Product cards: Below image
-- Product page: Near "Add to Cart" button
-- Cart: Item price column
-
-### Percentage Off Display
-
-Show savings to emphasize value.
-
-**Options:**
-- "Save 30%" badge
-- "30% off" label
-- "$15 off" (absolute savings)
-
-**Placement:**
-- Badge on product image (top-left or top-right corner)
-- Near price (inline or below)
-- In cart summary ("Total savings: $45")
-
-### Sale Badge
-
-Bright badge on product image (red, orange, yellow) in top corner. 48-64px desktop, 40-48px mobile. Text: "Sale", "30% Off", or "Save $15".
-
-## Promo Code Input
-
-### Placement and Design
-
-**Location:**
-Cart page order summary or checkout page. Position in right sidebar (desktop) or below items (mobile).
-
-**Layout:**
-- Label: "Promo code" or "Discount code"
-- Text input (200-280px desktop, full-width mobile)
-- "Apply" button inline or stacked (mobile)
-- Auto-uppercase on submit (codes usually uppercase)
-
-**Expandable pattern (optional):**
-"Have a promo code?" link that expands to show input. Saves vertical space, reduces visual clutter.
-
-### Success and Error States
-
-**Success:**
-- Green checkmark or success message: "Code applied: WELCOME10"
-- Discount shown in order summary with code name: "Discount (WELCOME10) -$10.00"
-- Remove option: X icon or "Remove" link
-- Update cart total immediately
-
-**Error:**
-- Red error message below input: "Invalid code", "Code expired", or "Minimum purchase not met"
-- Input remains visible for retry
-- Don't clear input field (user may have typo)
-
-**Applied code display in order summary:**
-```
-Subtotal              $100.00
-Discount (WELCOME10)  -$10.00
-Shipping              $5.00
-─────────────────────
-Total                 $95.00
-```
-
-## Free Shipping Threshold
-
-**Purpose (CRITICAL)**: Increase average order value by encouraging customers to add more items to reach free shipping.
-
-### Progress Bar Pattern
-
-**Display in cart:**
-- "Add $25 more for FREE SHIPPING"
-- Horizontal progress bar showing proximity to threshold
-- Updates automatically as cart value changes
-- Green when threshold reached
-
-**Example:**
-```
-Add $25.00 more for FREE SHIPPING
-[███████░░░░░░░░] 50%
-```
-
-**When threshold met:**
-- "You've unlocked free shipping!" (success message)
-- Green checkmark or badge
-- Crossed-out shipping charge in order summary
-
-**Why it works:**
-- Visualizes proximity to goal (loss aversion)
-- Increases AOV by 15-30% on average
-- Reduces cart abandonment (free shipping is top reason to complete purchase)
-
-### Free Shipping Banner
-
-Sitewide announcement: "Free shipping on orders over $50". Display in top banner or near cart icon. Visible on all pages for awareness.
-
-## Promotional Banners
-
-### Top Banner
-
-Full-width strip at top of page (48-64px height). Bright color contrasting with navbar. Short message: "Free shipping on orders over $50" or "Sale: Up to 50% off - Shop Now".
-
-**Position:**
-- Above navbar (most common)
-- Below navbar (alternative)
-- Sticky (stays visible on scroll, optional)
-
-**CTA:**
-Link to sale page ("Shop Now", "Learn More") or whole banner clickable.
-
-### Hero Banner
-
-Large hero section on homepage with promotional message. Background image, headline ("Black Friday Sale"), subheading ("Up to 60% off sitewide"), CTA button ("Shop the Sale"), optional countdown timer.
-
-### Inline Banners
-
-Within page content (product pages, cart). Examples: Free shipping reminder on cart page, "Sale ends soon" on product page. Less prominent than hero.
-
-## Countdown Timers
-
-Use for time-sensitive promotions to create urgency and FOMO.
-
-**When to use:**
-- Flash sales (24-hour sales)
-- Limited-time offers
-- Holiday promotions
-- Never for permanent sales (fake urgency harms trust)
-
-**Display format:**
-- "Sale ends in: 2d 14h 32m 15s"
-- Or simpler: "Ends in 2 days"
-- Or: "Hurry! Only 14 hours left"
-
-**Placement:**
-Top banner, product page near price, cart page, or hero section.
-
-**Implementation:**
-Server-side time to prevent client manipulation, auto-hide when expired, update in real-time.
-
-## Mobile Considerations
-
-**Top banner:**
-Shorter text (fewer words), smaller height (40-48px), dismissible (X button).
-
-**Sale badges:**
-Slightly smaller (40-48px), still clearly visible, don't obstruct product image.
-
-**Promo code input:**
-Full-width input and button, stacked layout (input above button), large touch targets (48px height), expandable section to save space.
-
-**Countdown timer:**
-Simplified format ("Ends in 14 hours" vs full d:h:m:s), larger text for readability.
-
-## Checklist
-
-**Essential features:**
-
-- [ ] Strikethrough original price for sales
-- [ ] Sale price bold, prominent, colored
-- [ ] Sale badges on product images (40-64px)
-- [ ] Percentage off displayed ("30% Off")
-- [ ] Promo code input field in cart/checkout
-- [ ] "Apply" button next to promo input
-- [ ] Success message after applying code
-- [ ] Error message for invalid codes
-- [ ] Applied code displayed in order summary with name
-- [ ] Remove code option (X icon or "Remove" link)
-- [ ] Total savings highlighted in cart
-- [ ] Free shipping progress bar (if applicable)
-- [ ] Progress updates as cart value changes
-- [ ] Success message when threshold met
-- [ ] Countdown timer for time-limited offers (server-side)
-- [ ] Promotional banners (top banner, hero)
-- [ ] Backend integration (fetch promotions from API)
-- [ ] Mobile: Full-width promo input, stacked layout
-- [ ] Mobile: Large touch targets (48px)
-- [ ] Expandable promo section (optional, saves space)
-- [ ] ARIA labels on promo input
-- [ ] Screen reader announcements for price changes
-- [ ] Keyboard accessible (Tab, Enter)
-- [ ] High contrast text (4.5:1 minimum)