@salesforce/b2c-dx-mcp 2.0.0 → 2.1.0

package/content/sfnext/auth.md

@@ -1,62 +0,0 @@
-# Authentication & Session Management
-
-## Architecture
-
-Split-cookie architecture with server/client contexts:
-
-- **Server middleware** (`auth.server.ts`): Manages SLAS tokens, writes cookies
-- **Client middleware** (`auth.client.ts`): Reads cookies, maintains cache
-- **React Context** (`AuthProvider`): Provides auth state to components
-
-## Cookie Design
-
-| Cookie Name | Purpose | User Type | Expiry | HttpOnly |
-|-------------|---------|-----------|--------|----------|
-| `cc-nx-g` | Guest refresh token | Guest | 30 days | No |
-| `cc-nx` | Registered refresh token | Registered | 90 days | No |
-| `cc-at` | Access token | Both | 30 min | No |
-| `usid` | User session ID | Both | Matches refresh | No |
-| `customerId` | Customer ID | Registered | Matches refresh | No |
-
-**Key Points**:
-
-- Only ONE refresh token exists (guest OR registered, never both)
-- User type derived from which refresh token exists
-- Cookies auto-namespaced with `siteId`
-- Tokens auto-refresh when expired
-
-## Usage in Loaders/Actions
-
-```typescript
-import { getAuth } from '@/middlewares/auth.server';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const auth = getAuth(context);
-
-    // Access auth properties
-    const accessToken = auth.access_token;
-    const customerId = auth.customer_id;
-    const isGuest = auth.userType === 'guest';
-    const isRegistered = auth.userType === 'registered';
-
-    return { isGuest, customerId };
-}
-```
-
-## Usage in Components
-
-```typescript
-import { useAuth } from '@/providers/auth';
-
-export function MyComponent() {
-    const auth = useAuth();
-
-    if (auth?.userType === 'guest') {
-        return <LoginPrompt />;
-    }
-
-    return <div>Welcome, customer {auth?.customer_id}</div>;
-}
-```
-
-**Reference:** See README-AUTH.md for complete authentication documentation.

package/content/sfnext/components.md

@@ -1,123 +0,0 @@
-# Component Patterns
-
-## Use the `createPage` HOC
-
-The `createPage` higher-order component standardizes page patterns with built-in Suspense and page key handling:
-
-```typescript
-import { use } from 'react';
-import { createPage } from '@/components/create-page';
-
-// Define your view component
-function ProductView({
-    product,
-    category
-}: {
-    product: Promise<Product>;
-    category?: Promise<Category>
-}) {
-    const productData = use(product);
-    const categoryData = category ? use(category) : null;
-
-    return (
-        <div>
-            <h1>{productData.name}</h1>
-            {categoryData && <p>Category: {categoryData.name}</p>}
-        </div>
-    );
-}
-
-// Create page with fallback
-const ProductPage = createPage({
-    component: ProductView,
-    fallback: <ProductSkeleton />
-});
-
-export default ProductPage;
-```
-
-**Benefits:**
-
-- Eliminates repetitive Suspense/Await boilerplate
-- Consistent loading states across pages
-- Built-in page key management for navigation transitions
-- Type-safe with full TypeScript support
-
-## shadcn/ui Components
-
-**RULES**:
-
-- ✅ Add via: `npx shadcn@latest add <component-name>`
-- ❌ DO NOT modify `src/components/ui/` directly
-- ✅ Create custom components elsewhere
-
-## Suspense Boundaries
-
-Use granular Suspense boundaries for better UX:
-
-```typescript
-// ✅ RECOMMENDED - Multiple Suspense boundaries
-export default function ProductPage({ loaderData: { product, reviews } }) {
-    return (
-        <div>
-            <Suspense fallback={<ProductHeaderSkeleton />}>
-                <Await resolve={product}>
-                    {(data) => <ProductHeader product={data} />}
-                </Await>
-            </Suspense>
-
-            <Suspense fallback={<ReviewsSkeleton />}>
-                <Await resolve={reviews}>
-                    {(data) => <ProductReviews reviews={data} />}
-                </Await>
-            </Suspense>
-        </div>
-    );
-}
-
-// ⚠️ OK - Single Suspense boundary (less granular)
-export default createPage({
-    component: ProductView,
-    fallback: <ProductPageSkeleton />
-});
-```
-
-## File Organization
-
-```
-src/components/product-tile/
-├── index.tsx              # Component
-├── index.test.tsx         # Tests
-└── stories/
-    ├── index.stories.tsx  # Storybook stories
-    └── __snapshots__/     # Storybook snapshots (optional)
-        └── product-tile-snapshot.tsx.snap
-
-# Skeleton components are separate components
-src/components/product-skeleton/
-├── index.tsx
-├── index.test.tsx
-└── stories/
-    └── index.stories.tsx
-```
-
-## Styling
-
-**Tailwind CSS 4** is the only styling approach allowed. Use utility classes directly in components.
-
-**Key rules:**
-
-- ✅ Use Tailwind utility classes
-- ✅ Use `cn()` utility for conditional classes
-- ❌ NO inline styles, NO CSS modules, NO separate CSS files
-
-**See `styling` section for:** Tailwind CSS 4, Shadcn/ui components, icons, responsive design, theme configuration, dark mode, best practices
-
-## Best Practices
-
-1. **Extract view components** - Separate data handling from presentation
-2. **Type safety** - Define proper TypeScript interfaces
-3. **Consistent fallbacks** - Reusable skeleton components
-4. **Colocate tests** - Keep tests next to components
-5. **Story coverage** - Create stories for all reusable components
-6. **Tailwind utilities only** - Use Tailwind CSS classes, avoid inline styles or CSS modules

package/content/sfnext/config.md

@@ -1,180 +0,0 @@
-# Configuration Management
-
-## Overview
-
-All configuration is centralized in `config.server.ts` with environment variable overrides via `.env` files. The configuration system provides type-safe access to app settings with automatic parsing and validation.
-
-## Required Variables
-
-Copy `.env.default` to `.env` and set these required Commerce Cloud credentials:
-
-```bash
-PUBLIC__app__commerce__api__clientId=your-client-id
-PUBLIC__app__commerce__api__organizationId=your-org-id
-PUBLIC__app__commerce__api__siteId=your-site-id
-PUBLIC__app__commerce__api__shortCode=your-short-code
-PUBLIC__app__defaultSiteId=your-site-id
-PUBLIC__app__commerce__sites='[{"id":"your-site-id","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"}],"supportedCurrencies":["USD"]}]'
-```
-
-**Note:** The `commerce.sites` array defines your site configuration including locales, currencies, and supported options. See `.env.default` for a complete example with multiple locales and currencies.
-
-## Adding Configuration
-
-1. **Define type in `src/config/schema.ts`**:
-
-```typescript
-export type Config = {
-  app: {
-    myFeature: {
-      enabled: boolean;
-      maxItems: number;
-    };
-  };
-};
-```
-
-2. **Add defaults in `config.server.ts`**:
-
-```typescript
-export default defineConfig({
-  app: {
-    myFeature: {
-      enabled: false,
-      maxItems: 10,
-    },
-  },
-});
-```
-
-3. **Override via environment variables**:
-
-```bash
-PUBLIC__app__myFeature__enabled=true
-PUBLIC__app__myFeature__maxItems=20
-```
-
-## Usage Patterns
-
-**In React Components**:
-
-```typescript
-import { useConfig } from '@/config';
-
-export function MyComponent() {
-    const config = useConfig();
-
-    if (config.myFeature.enabled) {
-        const maxItems = config.myFeature.maxItems;
-        // Your feature code
-    }
-}
-```
-
-**In Server Loaders/Actions**:
-
-```typescript
-import { getConfig } from '@/config';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const config = getConfig(context);
-
-    if (config.myFeature.enabled) {
-        // Your loader code
-    }
-}
-```
-
-**In Client Loaders**:
-
-```typescript
-import { getConfig } from '@/config';
-
-export function clientLoader() {
-    const config = getConfig(); // No context needed - uses window.__APP_CONFIG__
-    
-    if (config.myFeature.enabled) {
-        // Your loader code
-    }
-}
-```
-
-**Note:** `getConfig()` and `useConfig()` return `AppConfig` which is the `app` section of the full `Config` type. So you access properties directly (e.g., `config.myFeature.enabled`) without the `app` prefix.
-
-## Environment Variable Rules
-
-Use the `PUBLIC__` prefix with double underscores (`__`) to set any config path:
-
-```bash
-# Environment variable         →  Config path (in Config type)  →  Access via getConfig()/useConfig()
-PUBLIC__app__commerce__sites='[...]' → config.app.commerce.sites → config.commerce.sites
-PUBLIC__app__defaultSiteId=RefArchGlobal → config.app.defaultSiteId → config.defaultSiteId
-PUBLIC__app__myFeature__enabled=true → config.app.myFeature.enabled → config.myFeature.enabled
-```
-
-**Multi-site Configuration Example:**
-
-```bash
-PUBLIC__app__commerce__sites='[
-  {
-    "id": "RefArchGlobal",
-    "defaultLocale": "en-US",
-    "defaultCurrency": "USD",
-    "supportedLocales": [
-      {"id": "en-US", "preferredCurrency": "USD"},
-      {"id": "de-DE", "preferredCurrency": "EUR"}
-    ],
-    "supportedCurrencies": ["USD", "EUR"]
-  }
-]'
-```
-
-**Accessing Site Configuration:**
-
-```typescript
-const config = getConfig(context);
-const currentSite = config.commerce.sites[0]; // Get first site
-const locale = currentSite.defaultLocale;      // "en-US"
-const currency = currentSite.defaultCurrency;  // "USD"
-```
-
-Values are automatically parsed (numbers, booleans, JSON arrays/objects).
-
-Rules:
-1. **`PUBLIC__` prefix**: Exposed to browser (client-safe values)
-2. **No prefix**: Server-only (secrets, never exposed)
-3. **`__` separator**: Navigate nested paths (`PUBLIC__app__commerce__sites`)
-4. **Case-insensitive**: All casings work (normalized to match `config.server.ts`)
-5. **Auto-parsing**: Strings, numbers, booleans, JSON arrays/objects
-6. **Validation**: Paths must exist in `config.server.ts` (prevents typos)
-7. **Depth limit**: Maximum 10 levels deep (use JSON values for deeper nesting)
-8. **Path precedence**: More specific paths override less specific ones
-9. **Protected paths**: `app__engagement` cannot be overridden via environment variables
-10. **MRT limits**: Variable names max 512 characters, total PUBLIC__ values max 32KB
-
-**Note:** Site configuration (locales, currencies) is now managed via `PUBLIC__app__commerce__sites` array instead of individual `PUBLIC__app__site__locale` variables. This enables multi-site support.
-
-**Setting nested objects with JSON:**
-
-```bash
-# Instead of multiple variables:
-PUBLIC__app__myFeature__option1=value1
-PUBLIC__app__myFeature__option2=value2
-
-# Use a single JSON value:
-PUBLIC__app__myFeature='{"option1":"value1","option2":"value2","nested":{"enabled":true}}'
-```
-
-## Security
-
-```bash
-# ✅ Safe for client (PUBLIC__ prefix)
-PUBLIC__app__commerce__api__clientId=abc123
-
-# ✅ Server-only (no prefix)
-COMMERCE_API_SLAS_SECRET=your-secret
-```
-
-Read server-only secrets directly from `process.env` - never add to config.
-
-**Reference:** See src/config/README.md for complete configuration documentation.

package/content/sfnext/data-fetching.md

@@ -1,323 +0,0 @@
-# Data Fetching Patterns
-
-## Loader Functions
-
-**IMPORTANT**: This project **mandates server-only data loading**. Every UI route must only export a `loader` function.
-
-### Critical Rule: Synchronous Loaders for Streaming
-
-**IMPORTANT**: Loaders should be **synchronous functions that return objects containing promises**, NOT async functions. This enables non-blocking page transitions and streaming SSR.
-
-```typescript
-// ✅ CORRECT - Synchronous loader returning promises
-export function loader({ context }: LoaderFunctionArgs): ProductPageData {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),  // Promise - streams
-        reviews: clients.shopperProducts.getReviews({...}),  // Promise - streams
-    };
-}
-
-// ❌ AVOID - Async loader blocks page transitions
-export async function loader({ context }: LoaderFunctionArgs): Promise<ProductPageData> {
-    const product = await clients.shopperProducts.getProduct({...}); // Blocks!
-    return { product };
-}
-```
-
-**Why this matters:**
-- Async loaders with `await` **block the entire page transition** until all data resolves
-- Synchronous loaders returning promises allow React to **stream data progressively**
-- Each promise resolves independently, enabling granular Suspense boundaries
-- Users see content as it becomes available, not all at once
-
-**Behavior**:
-- Initial load: Runs on server (SSR)
-- Navigation: Runs on server (XHR/fetch to server)
-- SCAPI requests always on MRT
-
-## Data Loading Strategies
-
-### Pattern 1: Awaited Data (Blocking)
-
-```typescript
-// ⚠️ BLOCKS rendering until all data is ready
-export async function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: await clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data)
-    };
-}
-```
-
-**Use when:** Critical data must be available before rendering (SEO, above-the-fold content)
-
-### Pattern 2: Deferred Data (Streaming)
-
-```typescript
-// ✅ RECOMMENDED - Streams data progressively
-export function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        // Return promises directly - they'll stream to client
-        product: clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-
-        reviews: clients.shopperProducts.getReviews({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data)
-    };
-}
-```
-
-**Use when:** Non-critical data can load after initial render
-
-### Pattern 3: Mixed Strategy
-
-```typescript
-// ✅ BEST OF BOTH - Critical data awaited, rest streamed
-export async function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-
-    // Await critical data
-    const product = await clients.shopperProducts.getProduct({
-        params: { path: { id: params.productId } }
-    }).then(({ data }) => data);
-
-    return {
-        product, // Resolved
-        reviews: clients.shopperProducts.getReviews({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data), // Streamed
-        recommendations: clients.shopperProducts.getRecommendations({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data) // Streamed
-    };
-}
-```
-
-## Action Functions
-
-Handle mutations (form submissions, cart updates):
-
-```typescript
-import {data, redirect} from 'react-router';
-
-export async function action({request, context}: ActionFunctionArgs) {
-  const formData = await request.formData();
-  const productId = formData.get('productId') as string;
-
-  const clients = createApiClients(context);
-
-  try {
-    await clients.shopperBasketsV2.addItemToBasket({
-      params: {
-        path: {basketId},
-        body: {productId, quantity: 1},
-      },
-    });
-
-    return data({success: true});
-  } catch (error) {
-    return data({success: false, error: error.message}, {status: 400});
-  }
-}
-```
-
-## Interactive Data Fetching: useScapiFetcher
-
-For on-demand, user-triggered data fetching (after page load), use the `useScapiFetcher` hook instead of loaders.
-
-### `loader` vs `useScapiFetcher`
-
-| Aspect | `loader` | `useScapiFetcher` |
-|--------|----------|-------------------|
-| **When it runs** | Route navigation (page load) | On-demand (user interaction) |
-| **Triggered by** | URL change | Component code (useEffect, button click) |
-| **Data availability** | Before/during component render (streamed) | After component mounts |
-| **Execution context** | Server (MRT) | Triggers server route |
-| **Use case** | Initial page data | Dynamic, interactive fetching |
-
-### How `useScapiFetcher` Works
-
-```text
-Component calls useScapiFetcher()
-        ↓
-Hook builds URL: /resource/api/client/{encoded-params}
-        ↓
-fetcher.load() or fetcher.submit()
-        ↓
-resource.api.client.$resource.ts loader/action runs ON SERVER
-        ↓
-createApiClients(context) makes SCAPI call (server-side)
-        ↓
-JSON response returned to component
-```
-
-**Important:** Even though you call `useScapiFetcher` from the browser, the actual SCAPI requests still happen **on the server** through the resource route, keeping credentials secure.
-
-### Example: Search Suggestions
-
-```typescript
-import { useScapiFetcher } from '@/hooks/use-scapi-fetcher';
-import { useMemo, useCallback } from 'react';
-
-export function useSearchSuggestions({ q, limit, currency }) {
-    // Prepare SCAPI parameters
-    const parameters = useMemo(
-        () => ({
-            params: {
-                query: { q, limit, currency }
-            }
-        }),
-        [q, limit, currency]
-    );
-
-    // Hook automatically routes to server
-    const fetcher = useScapiFetcher(
-        'shopperSearch',           // SCAPI client
-        'getSearchSuggestions',    // Method name
-        parameters                 // Parameters
-    );
-
-    const refetch = useCallback(async () => {
-        await fetcher.load();  // Triggers server request
-    }, [fetcher]);
-
-    return {
-        data: fetcher.data,
-        isLoading: fetcher.state === 'loading',
-        refetch
-    };
-}
-```
-
-### When to Use Each Approach
-
-| Scenario | Use |
-|----------|-----|
-| Load product data when visiting `/product/123` | `loader` |
-| Load checkout data | `loader` |
-| Search suggestions as user types | `useScapiFetcher` |
-| Update customer profile in modal | `useScapiFetcher` |
-| Load recommendations after page loads | `useScapiFetcher` |
-| Fetch bonus products when modal opens | `useScapiFetcher` |
-| Infinite scroll / Load more | `useScapiFetcher` |
-
-### Timeline Comparison
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                     loader (Server)                             │
-├─────────────────────────────────────────────────────────────────┤
-│  User clicks link → Server loader() → Stream data → Page render │
-│                                                                 │
-│  Timeline:  [navigate] → [server fetch] → [stream to client]    │
-│                                                                 │
-│  Data available: Streamed during render via Suspense            │
-└─────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────┐
-│                     useScapiFetcher                             │
-├─────────────────────────────────────────────────────────────────┤
-│  Page loads → Component mounts → User types → fetcher.load()    │
-│                                                                 │
-│  Timeline:  [render] → [user action] → [fetch] → [re-render]    │
-│                                                                 │
-│  Data available: AFTER user action, component re-renders        │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## API Client Usage
-
-Always use `createApiClients(context)`:
-
-```typescript
-import { createApiClients } from '@/lib/api-clients';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-
-    // All SCAPI clients with full type safety:
-    clients.shopperProducts.getProduct({...});
-    clients.shopperCustomers.getCustomer({...});
-    clients.shopperBasketsV2.getBasket({...});
-    clients.shopperSearch.productSearch({...});
-    clients.shopperOrders.getOrder({...});
-}
-```
-
-## Parallel vs Sequential
-
-```typescript
-// ✅ GOOD - Parallel requests
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-
-    return {
-        product: clients.shopperProducts.getProduct({...}),
-        reviews: clients.shopperProducts.getReviews({...}),
-        recommendations: clients.shopperProducts.getRecommendations({...})
-    };
-    // All three requests start simultaneously
-}
-
-// ❌ BAD - Sequential requests
-export async function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-
-    const product = await clients.shopperProducts.getProduct({...});
-    const reviews = await clients.shopperProducts.getReviews({...});
-    const recommendations = await clients.shopperProducts.getRecommendations({...});
-
-    return { product, reviews, recommendations };
-    // Each request waits for the previous to complete
-}
-```
-
-## Understanding Data Flow
-
-### Initial Page Load (SSR)
-
-```text
-Browser → MRT Server
-         ↓
-    loader() runs on server
-         ↓
-    SCAPI requests on MRT
-         ↓
-    HTML response → Browser
-```
-
-**Key characteristics:**
-- The `loader()` runs on the server
-- SCAPI requests happen server-side (direct in production, proxied in dev)
-- Full HTML is returned to browser
-- Client hydrates the HTML
-
-### Subsequent Navigation (SPA)
-
-All routes use server `loader` for both SSR and SPA navigation:
-
-```text
-User clicks link → React Router intercepts
-         ↓
-    Browser makes fetch() to server
-         ↓
-    MRT Server receives request
-         ↓
-    Same loader() runs on server
-         ↓
-    SCAPI requests on MRT
-         ↓
-    JSON response → Browser
-         ↓
-    React updates DOM
-```
-
-**Key Point:** The loader function code is identical for both SSR and SPA navigation. The only difference is the response format (HTML vs JSON). This is why SCAPI credentials stay secure and MRT orchestration works consistently.
-
-**Reference:** See README-DATA.md for complete data fetching documentation.