@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-data-fetching/SKILL.md

@@ -1,190 +1,140 @@
 ---
 name: sfnext-data-fetching
-description: Implement server-side data fetching in Storefront Next using loaders, actions, and useScapiFetcher. Use when writing loader functions, making SCAPI calls, handling form submissions, or implementing interactive data fetching. Covers synchronous loaders, streaming patterns, createApiClients, and parallel requests. NOT for client-side Zustand state — see sfnext-state-management.
+description: >-
+  Load and mutate data in a Storefront Next project: route loaders that call SCAPI through createApiClients from @/lib/api-clients.server, critical versus streamed (deferred) data, createBasketAction and BasketAction for cart actions, createActionError and ErrorCode, data() responses, useFetcher and the useScapiFetcher hook with its server allowlist, request-scoped dedupe and MRT timeouts, non-personalized SCAPI responses, shopper context, and custom API clients. Use for "fetch products in a loader", "stream data", "add a cart action", "call SCAPI from a component", "resource route", "NormalizedApiError", or "loader blocks the page". Do not use for route files or links (use `storefront-next:sfnext-routing`), when loaders re-run after actions (use `storefront-next:sfnext-revalidation`), Suspense/LCP tuning (use `storefront-next:sfnext-performance`), or defining SCAPI custom APIs (use `storefront-next:sfnext-scapi`).
 ---
 
-# Data Fetching Skill
+# Storefront Next Data Fetching
 
-This skill covers server-side data fetching patterns in Storefront Next — loaders, actions, and the useScapiFetcher hook.
+All data comes from the server. Loaders and actions run on the server with the shopper's session; the browser never calls SCAPI directly. Your project ships `docs/README-DATA.md`, `docs/README-SUSPENSE.md`, `docs/README-SCAPI-NON-PERSONALIZED-RESPONSES.md` and `docs/README-SHOPPER-CONTEXT.md`, plus the "Performance & Data Rules" in `AGENTS.md`; this skill is the quick path, those are authoritative.
 
-## Overview
+## The rules (same as AGENTS.md)
 
-Storefront Next mandates **server-only data loading**. All SCAPI requests execute on the MRT server, never in the browser. Three mechanisms exist:
+1. Fetch on the server in `loader` (reads) and `action` (writes). There is no `clientLoader` or `clientAction`.
+2. Classify every piece of data:
+   - **Critical** (needed for SEO, LCP, layout stability or the HTTP status): `await` it in the loader.
+   - **Non-critical** (below the fold, recommendations, reviews, secondary panels): start the request, do not await it, and return the unresolved promise so it streams.
+   - **Interaction-driven** (only after a click, hover or input): fetch on demand with a fetcher.
+3. Never block a loader on non-critical data.
+4. Pass the promise through `loaderData` and read it under its own `<Suspense>` with `use()` or `<Await>`. Keep the promise identity stable (compose it in the loader, never `Promise.all` or `.then` in render).
+5. Export `shouldRevalidate` on routes whose loaders depend on URL filters (see `storefront-next:sfnext-revalidation`).
 
-| Mechanism | When It Runs | Use Case |
-|-----------|-------------|----------|
-| `loader` | Route navigation | Initial page data |
-| `action` | Form submission | Mutations (add to cart, update profile) |
-| `useScapiFetcher` | User interaction | On-demand fetching (search suggestions, infinite scroll) |
+## Loader with critical and streamed data
 
-## Loader Patterns
+```tsx
+import { Suspense } from 'react';
+import { Await } from 'react-router';
+import type { Route } from './+types/_app.example';
+import { createApiClients } from '@/lib/api-clients.server';
+import { fetchProductById } from '@/lib/api/products.server';
+import { NormalizedApiError } from '@/lib/api/normalized-api-error';
 
-Loaders can be **synchronous** (returning promises for streaming) or **async** (awaiting critical data). Choose based on what the page needs:
+export async function loader({ context, params }: Route.LoaderArgs) {
+    const clients = createApiClients(context);
 
-- **Sync loader** — Returns promises directly. Enables streaming SSR: the shell renders immediately while data streams in. Best when all data can render progressively.
-- **Async loader** — Awaits critical data before rendering. Use when data is required for SEO or the page shell (e.g., category name in breadcrumbs). Non-critical data can still be returned as promises for streaming.
+    // Non-critical: start now, do not await.
+    const related = clients.shopperSearch
+        .productSearch({ params: { query: { q: 'shirt', limit: 8 } } })
+        .then(({ data }) => data.hits ?? []);
 
-```typescript
-// Sync — full streaming (all data renders progressively)
-export function loader({ params, context }: LoaderFunctionArgs): ProductPageData {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-        reviews: clients.shopperProducts.getReviews({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-    };
+    // Critical: needed for status, SEO and LCP.
+    try {
+        const product = await fetchProductById(context, params.id ?? '', { expand: ['images', 'prices'] });
+        if (!product) throw new Response('Not found', { status: 404 });
+        return { product, related };
+    } catch (e) {
+        if (e instanceof NormalizedApiError && e.status) throw new Response(e.message, { status: e.status });
+        throw e;
+    }
 }
 
-// Async — await critical data, stream the rest (mixed strategy)
-export async function loader({ params, context }: LoaderFunctionArgs): Promise<CategoryPageData> {
-    const clients = createApiClients(context);
-
-    // Await critical data needed for page shell/SEO
-    const category = await clients.shopperProducts.getCategory({
-        params: { path: { id: params.categoryId } }
-    }).then(({ data }) => data);
-
-    return {
-        category,  // Resolved immediately
-        products: clients.shopperSearch.productSearch({
-            params: { query: { q: '', refine: { cgid: params.categoryId } } }
-        }).then(({ data }) => data),  // Streamed
-    };
+export default function Example({ loaderData }: Route.ComponentProps) {
+    return (
+        <>
+            <h1>{loaderData.product.name}</h1>
+            <Suspense fallback={<div className="h-40" aria-busy="true" />}>
+                <Await resolve={loaderData.related}>{(hits) => <ul>{hits.map((h) => <li key={h.productId}>{h.productName}</li>)}</ul>}</Await>
+            </Suspense>
+        </>
+    );
 }
 ```
 
-## When to Use Each Pattern
-
-| Pattern | When | Example |
-|---------|------|---------|
-| Sync (full streaming) | All data can render progressively | Product page with reviews |
-| Async (await critical) | SEO-critical data needed for page shell | Category page (needs category name) |
-| Mixed | Some data critical, some deferrable | Category name (await) + product grid (stream) |
-
-See [Loader Patterns Reference](references/LOADER-PATTERNS.md) for more patterns and data flow diagrams.
+Real precedent: `src/routes/_app.p.$.tsx` awaits the product (404 becomes `throw new Response(..., { status: 404 })`) and streams the Page Designer page, schema and extras; `src/components/product-grid/deferred.tsx` is the streamed-grid pattern.
 
-## Action Functions
+## SCAPI clients
 
-Handle mutations (form submissions, cart updates):
+`createApiClients(context)` from `@/lib/api-clients.server` returns `AppClients`: every generated Shopper API client (`shopperProducts`, `shopperSearch`, `shopperBasketsV2`, `shopperCustomers`, `shopperOrders`, `shopperLogin`, and more) plus generated clients for your custom APIs (`@/scapi/custom-clients`). Call shape:
 
-```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 });
-    }
-}
+```ts
+const { data } = await clients.shopperBasketsV2.addItemToBasket({
+    params: { path: { basketId }, query: {} },
+    body: [{ productId, quantity: 1 }],   // body is a sibling of params; this endpoint takes an array
+});
 ```
 
-## useScapiFetcher — Interactive Data Fetching
-
-For on-demand data fetching triggered by user interactions (after page load):
+Results are `{ data }`; failures throw. Prefer the thin wrappers in `src/lib/api/*.server.ts` (`fetchProductById`, `fetchProductsByIds` which chunks to the 24-id limit, category, search, order, customer and basket helpers): they log and rethrow as `NormalizedApiError` (`@/lib/api/normalized-api-error`, with `.status` and `.cause`). Add new wrappers there rather than calling clients inline in many routes.
 
-```typescript
-import { useScapiFetcher } from '@/hooks/use-scapi-fetcher';
+The clients already wrap `fetch` with request-scoped GET/HEAD dedupe (identical calls in one request share one response; any mutation clears the cache), a hard timeout from the `MRT_REQUEST_TIMEOUT` environment variable when set, and a health observer that logs 429 and load-status headers. Do not re-implement them. More: [API-CLIENTS.md](references/API-CLIENTS.md).
 
-export function useSearchSuggestions({ q, limit, currency }) {
-    const parameters = useMemo(
-        () => ({ params: { query: { q, limit, currency } } }),
-        [q, limit, currency]
-    );
+Trim payloads: pass only the `expand`/`select` values you render. Availability is cached about 60 seconds and prices/promotions about 15 minutes, so short-TTL data is a good candidate for streaming. Shopper-agnostic responses can be cached using the policy in `src/lib/scapi/non-personalized-response-policy.server.ts` (see the shipped README-SCAPI-NON-PERSONALIZED-RESPONSES); request `personalized: 'none'` only where the response truly is the same for all shoppers, as the navigation loader in `_app.tsx` does.
 
-    const fetcher = useScapiFetcher(
-        'shopperSearch',
-        'getSearchSuggestions',
-        parameters
-    );
+## Mutations: actions
 
-    const refetch = useCallback(async () => {
-        await fetcher.load();
-    }, [fetcher]);
+Prefer an `action.*` route and a `<Form>` (navigating) or `useFetcher` (non-navigating).
 
-    return {
-        data: fetcher.data,
-        isLoading: fetcher.state === 'loading',
-        refetch,
-    };
-}
-```
+Basket mutations use the factory, which loads the basket, parses `FormData`, catches errors and wraps the result:
 
-See [SCAPI Fetcher Reference](references/SCAPI-FETCHER.md) for the complete useScapiFetcher API.
+```ts
+// src/routes/action.example-remove-item.ts
+import { data } from 'react-router';
+import { BasketAction, createBasketAction } from '@/lib/cart/basket-action.server';
+import { createActionError } from '@/lib/action-error-helpers.server';
+import { ErrorCode } from '@/lib/error-codes';
 
-## API Client Usage
+export const action = createBasketAction(
+    { method: 'POST', action: BasketAction.CartItemRemove, parse: (fd) => ({ itemId: String(fd.get('itemId') ?? '') }) },
+    async ({ input, basketId, clients }) => {
+        if (!input.itemId) {
+            return data({ success: false, error: createActionError({ code: ErrorCode.REQUIRED_FIELD, message: 'itemId is required' }) }, { status: 400 });
+        }
+        const { data: basket } = await clients.shopperBasketsV2.removeItemFromBasket({ params: { path: { basketId, itemId: input.itemId } } });
+        return basket; // factory returns { success: true, basket } and syncs the basket resource
+    }
+);
+```
 
-Always use `createApiClients(context)` in loaders and actions:
+Return the updated `Basket` for success. Return `data(payload, { status })` for validation errors (use `data()` from `react-router`, not `Response.json`). Thrown SCAPI 4xx errors pass their status through; others become 500. Available `BasketAction` values are listed in `src/lib/cart/basket-action.server.ts`. See the existing `action.cart-item-*.tsx` files. Details and non-basket actions: [ACTIONS.md](references/ACTIONS.md).
 
-```typescript
-import { createApiClients } from '@/lib/api-clients';
+## Fetching from components
 
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
+- Use `useFetcher` against your own `action.*`/`resource.*` routes (`resourceRoutes` in `@/route-paths`).
+- Use `useScapiFetcher(client, method, { params, body })` from `@/hooks/use-scapi-fetcher` for a small allowlisted set of Shopper calls without writing a route. It returns `.load()`, `.submit(payload)`, `.data`, `.errors`, `.success`. The server enforces an allowlist in `src/lib/scapi/resource-policy.ts` (for example `shopperProducts.getProduct`, `shopperBasketsV2.getBasket`, `shopperSearch.getSearchSuggestions`, and selected `shopperCustomers` address and profile mutations). Anything else needs a dedicated route. See [SCAPI-FETCHER.md](references/SCAPI-FETCHER.md).
+- Do not fetch in `useEffect` on mount what the loader could fetch (see the performance review checklist in `storefront-next:sfnext-performance`).
+- Fetchers and raw `fetch` calls that do not go through a submission do not trigger revalidation; actions do, for every active loader.
 
-    clients.shopperProducts.getProduct({...});
-    clients.shopperCustomers.getCustomer({...});
-    clients.shopperBasketsV2.getBasket({...});
-    clients.shopperSearch.productSearch({...});
-    clients.shopperOrders.getOrder({...});
-}
-```
+## Checklist
 
-## Parallel vs Sequential Requests
+1. Can the loader fetch this at request time? If yes, do it there.
+2. Is it critical? `await`; otherwise return the promise with its own Suspense and a sized skeleton.
+3. Did you request only the fields you render?
+4. Mutation errors: `createActionError` with an `ErrorCode`, return with `data(..., { status })`.
+5. New shared fetch logic goes in `src/lib/api/*.server.ts` with a test (`storefront-next:sfnext-testing`).
+6. Run `pnpm typecheck` and `pnpm test`.
 
-```typescript
-// GOOD — Parallel requests (all start simultaneously)
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}).then(({ data }) => data),
-        reviews: clients.shopperProducts.getReviews({...}).then(({ data }) => data),
-        recommendations: clients.shopperProducts.getRecommendations({...}).then(({ data }) => data),
-    };
-}
-
-// AVOID — Sequential awaits of independent requests (unnecessarily slow)
-export async function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    const product = await clients.shopperProducts.getProduct({...});  // Waits...
-    const reviews = await clients.shopperProducts.getReviews({...});  // Then waits again
-    return { product, reviews };
-}
-```
+Deeper: [LOADERS.md](references/LOADERS.md).
 
-## Common Pitfalls
+## Finding more
 
-| Pitfall | Problem | Solution |
-|---------|---------|----------|
-| Awaiting all data | Blocks page transition unnecessarily | Only await SEO-critical data; stream the rest |
-| Client loaders | Not permitted in Storefront Next | Use server `loader` or `useScapiFetcher` |
-| Sequential `await` | Slow data loading | Return promises in parallel |
-| Missing `context` in `getConfig()` | Config unavailable | Pass `context` in server loaders: `getConfig(context)` |
+Open `AGENTS.md` ("Key Documentation") and `docs/README-DATA.md` in your project. Search product docs with `b2c docs search "<term>"` or the `docs_search` MCP tool.
 
 ## Related Skills
 
-- `storefront-next:sfnext-scapi-management` - Adding/removing SCAPI clients and discovering API shapes
-- `storefront-next:sfnext-custom-apis` - Calling custom API endpoints from loaders/actions
-- `storefront-next:sfnext-routing` - Route file conventions and module exports
-- `storefront-next:sfnext-components` - Rendering loader data with createPage and Suspense
-- `storefront-next:sfnext-state-management` - Client-side Zustand stores (NOT data fetching)
-- `storefront-next:sfnext-authentication` - Auth context in loaders
-
-## Reference Documentation
-
-- [Loader Patterns Reference](references/LOADER-PATTERNS.md) - Data flow diagrams and advanced patterns
-- [SCAPI Fetcher Reference](references/SCAPI-FETCHER.md) - Complete useScapiFetcher API and examples
+- `storefront-next:sfnext-routing` - route files and links
+- `storefront-next:sfnext-revalidation` - avoid wasted loader re-runs after actions
+- `storefront-next:sfnext-performance` - Suspense placement, LCP, review checklist
+- `storefront-next:sfnext-state-management` - basket provider and client state
+- `storefront-next:sfnext-scapi` - SCAPI access and custom APIs
+- `storefront-next:sfnext-authentication` - sessions behind loaders
+- `b2c-cli:b2c-scapi-custom` - inspect custom API endpoints
+- `b2c:b2c-custom-api-development` - build a custom API

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-data-fetching/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "Add a loader on my Storefront Next page that awaits the product and streams recommendations so the page doesn't block", "should_trigger": true},
+  {"query": "How do I write a createBasketAction handler that returns a validation error?", "should_trigger": true},
+  {"query": "My product grid re-fetches every time I add an item to the cart; how do I stop loaders re-running after actions?", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-data-fetching/references/ACTIONS.md

@@ -0,0 +1,53 @@
+# Actions and errors
+
+## Where to put a mutation
+
+Create `src/routes/action.<name>.ts(x)` exporting only `action`. Add an entry to `resourceRoutes` in `src/route-paths.ts`. The `/action/**` paths are excluded from the site prefix. Use `<Form method="post" action={resourceRoutes.x}>` when the user should navigate or when a native form must work without JavaScript; use `useFetcher` for in-place changes (add to cart, quantity changes, toggles).
+
+## Basket actions: `createBasketAction`
+
+`import { BasketAction, createBasketAction } from '@/lib/cart/basket-action.server'`
+
+```ts
+createBasketAction(
+    { method: 'POST' | 'PATCH', action: BasketAction.X, parse: (fd: FormData) => input },
+    async ({ input, basketId, basket, context, clients, logger }) => Basket | ReturnType<typeof data>
+)
+```
+
+- The factory enforces the HTTP method, ensures a basket exists, parses form data, runs the handler and converts the result.
+- Returning a `Basket` yields `{ success: true, basket }` (status 200) and updates the basket resource through `updateBasketResource` so the provider picks it up.
+- Returning `data({ success: false, error }, { status })` sends validation errors.
+- Throwing yields `{ success: false, error }`; a SCAPI 4xx keeps its status, anything else is 500.
+- Enum values: CartItemRemove, CartItemUpdate, CartItemAdd, CartSetAdd, CartBundleAdd, CartBundleUpdate, PromoCodeAdd, PromoCodeRemove, BonusProductAdd, SwatchOrder. Add new ones in the same file when a new kind of basket mutation needs its own name.
+- Request bodies for some calls are arrays (`addItemToBasket` takes `[payload]`).
+
+Read `action.cart-item-add.tsx`, `action.cart-item-update.tsx` and `action.cart-item-remove.tsx` for complete examples.
+
+## Other actions
+
+For non-basket work (customer, wishlist, consent, checkout), write a plain `action({ request, context })`: read `await request.formData()`, call `createApiClients(context)` or a `src/lib/api/*.server.ts` wrapper, and return `data(...)`. Check authentication with `getAuth(context)` where needed (`NOT_AUTHENTICATED`).
+
+## Error shape
+
+```ts
+import { createActionError } from '@/lib/action-error-helpers.server';
+import { ErrorCode } from '@/lib/error-codes';
+
+createActionError({ code: ErrorCode.INVALID_INPUT, message: 'Invalid quantity' });
+createActionError({ error: caughtError });            // normalizes SCAPI/unknown errors
+```
+
+`ErrorCode` members: NOT_FOUND, NOT_AUTHENTICATED, NOT_AUTHORIZED, INVALID_INPUT, REQUIRED_FIELD, CONFLICT, EXPIRED, OPERATION_FAILED, OUT_OF_STOCK, RATE_LIMITED, METHOD_NOT_ALLOWED, UNKNOWN, SCAPI_UNSUPPORTED, CONFIGURATION_ERROR.
+
+Response types live in `@/routes/types/action-responses` (`ActionResponse<T>`, `BasketActionResponse`). Return status codes with `data(payload, { status })` from `react-router`.
+
+## Client side
+
+- `useItemFetcher({ itemId, componentName })` (`@/hooks/use-item-fetcher`) gives per-line-item fetcher keys so a row shows its own pending state.
+- Optimistic UI: read `fetcher.formData`, `useNavigation`, or `useOptimistic`.
+- Side effects after a fetcher finishes: `useFetcherEffect` (`@/hooks/use-fetcher-effect`) or `useScapiFetcherEffect` (`@/hooks/use-scapi-fetcher-effect`) instead of hand-written `useEffect` chains.
+
+## After an action
+
+React Router revalidates every active loader by default. Decide which should re-run and declare it with `shouldRevalidate` or tags: `storefront-next:sfnext-revalidation`.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-data-fetching/references/API-CLIENTS.md

@@ -0,0 +1,34 @@
+# API clients
+
+`createApiClients(context)` (`@/lib/api-clients.server`) builds, per request, the typed clients used in loaders and actions. Cost is low; call it in each function that needs it.
+
+## What you get
+
+`AppClients` (type in `@/scapi/custom-clients`) is the generated Shopper API clients merged with clients generated for your custom APIs. Authentication (shopper access token), `siteId`, locale and currency come from the request context. The `@/scapi` barrel exports schema and operation types, for example `ShopperProducts.schemas['Product']` and `ApiError`.
+
+## Fetch layers
+
+Each client uses `dedupe(timeout(healthObserver(originBoundFetch)))`:
+
+| Layer | Behavior |
+|---|---|
+| dedupe | within one request, identical GET/HEAD calls share one promise; any non-GET call clears the whole registry |
+| timeout | aborts calls after `MRT_REQUEST_TIMEOUT` ms when that variable is set (no-op otherwise) |
+| health observer | logs 429 and SCAPI load-status signals |
+
+Consequences: it is safe for several components' loaders to request the same product; do not add your own in-memory cache keyed by request; after a write in the same request, re-reads are real calls.
+
+## Errors
+
+Clients throw. In `src/lib/api/*.server.ts`, catch and `throw new NormalizedApiError(error)`; route code checks `e.status`. Map 404 to a `Response` with status 404; let unexpected errors reach the route `ErrorBoundary`.
+
+## Custom APIs
+
+Generated custom-API clients appear on `AppClients` (for example a notification client). To add one: define the API with `storefront-next:sfnext-scapi` guidance, generate the client as described there, and call it as `clients.<name>.<operation>({ params, body })`.
+
+## Request shaping checklist
+
+- `expand`/`select` only what the UI renders.
+- `fetchProductsByIds` chunks at 24 ids; do not loop single `getProduct` calls.
+- Start independent calls before awaiting (parallel), but keep non-critical calls un-awaited.
+- Pass `personalized: 'none'` only for shopper-independent data, following `docs/README-SCAPI-NON-PERSONALIZED-RESPONSES.md`.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-data-fetching/references/LOADERS.md

@@ -0,0 +1,73 @@
+# Loader patterns
+
+See also `docs/README-DATA.md`, `docs/README-SUSPENSE.md` and the "Performance & Data Rules" in `AGENTS.md` in your project.
+
+## Critical versus streamed
+
+| Data | Treatment |
+|---|---|
+| Entity that decides status (product, category, order) | `await`; map SCAPI 404 to `throw new Response(msg, { status: 404 })` |
+| Data visible in the first viewport, SEO tags, JSON-LD source | `await` |
+| Page Designer page for the LCP region | `await` the page and render `<Region critical>` (see `storefront-next:sfnext-page-designer`) |
+| Below the fold, recommendations, reviews, secondary panels | return the promise |
+| Short-TTL data (availability about 60 s) that is not the LCP | prefer streaming |
+| Needs a user gesture | fetcher, not loader |
+
+Start every independent request before the first `await` so they run in parallel:
+
+```ts
+const clients = createApiClients(context);
+const extrasPromise = loadExtras(context, id);          // started, not awaited
+const product = await fetchProductById(context, id);    // critical
+return { product, extras: extrasPromise };
+```
+
+## Stable promises
+
+Compose dependent work inside the loader (`extrasPromise.then(...)` there, never in render). A new promise object per render restarts Suspense and flashes the fallback. Do not wrap promises in `useMemo`. If a component must derive one, pin it with `useState(() => ...)` or re-pin via `useRef` keyed on the inputs. Full rules in `docs/README-SUSPENSE.md`.
+
+A streamed promise that can reject needs an error path: use `<Await errorElement={...}>` or make the loader promise resolve to a fallback value (`.catch(() => [])`) when degraded output is acceptable, and log inside the loader.
+
+## Consuming a promise
+
+```tsx
+<Suspense fallback={<RecommendationsSkeleton />}>
+    <Await resolve={loaderData.recommendations} errorElement={null}>
+        {(items) => <Recommendations items={items} />}
+    </Await>
+</Suspense>
+```
+
+- One `<Suspense>` per independent async operation; siblings may resolve independently.
+- The skeleton must reserve the final height (no `fallback={null}` above the fold).
+- A component that reads a promise with `use()` must have a `<Suspense>` ancestor, otherwise it blocks the first byte.
+- For product listings reuse `DeferredProductGrid` (`@/components/product-grid/deferred`).
+
+## Shared layout data
+
+Layout loaders (for example `_app.tsx` navigation) stream their data and child routes read it with `useRouteLoaderData('routes/_app')`. Put data that many routes need in the lowest common layout, not in each page.
+
+## Request context
+
+Loaders receive `context` (`Route.LoaderArgs`). Useful accessors:
+
+| Need | Import |
+|---|---|
+| Logger | `getLogger` from `@/lib/logger.server` |
+| Site, locale, currency | `siteContext` from `@salesforce/storefront-next-runtime/site-context` via `context.get(siteContext)` |
+| Config | `getConfig` from `@salesforce/storefront-next-runtime/config` |
+| Session | `getAuth` from `@/middlewares/auth.server` |
+| Basket | `getBasket`, `getBasketSnapshot`, `ensureBasketId` from `@/middlewares/basket.server` |
+
+Middleware order is defined in `src/root.tsx` (`export const middleware`); add new request-wide state there with `createContext`/middleware instead of re-deriving it in each loader.
+
+## Shopper context and personalization
+
+Shopper context (customer segments, source codes, custom qualifiers) is applied by `shopper-context` middleware and read in components with `useShopperContext`. Read `docs/README-SHOPPER-CONTEXT.md` before changing it. Personalized endpoints must not be cached as shared responses.
+
+## Pitfalls
+
+- `Promise.all([...])` over critical and non-critical together re-blocks the loader; await only the critical set.
+- Mutating `loaderData` on the client is unsupported; derive in the loader.
+- Do not add `clientLoader`.
+- Shaping or normalizing data in render (lookup maps, chained passes) belongs in the loader.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-data-fetching/references/SCAPI-FETCHER.md

@@ -1,93 +1,39 @@
-# SCAPI Fetcher Reference
+# `useScapiFetcher`
 
-## How useScapiFetcher Works
+`import { useScapiFetcher } from '@/hooks/use-scapi-fetcher'`
 
-```
-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
-```
-
-Even though `useScapiFetcher` is called from the browser, the actual SCAPI requests happen **on the server** through the resource route, keeping credentials secure.
-
-## API
+A typed wrapper over React Router's `useFetcher` that calls a Shopper client method through a single resource route (`src/routes/resource.api.client.$resource.ts`). The request is encoded (base64url of `[client, method, options]`) into `/resource/api/client/:resource`, executed on the server, and the SCAPI `data` is returned unwrapped.
 
-```typescript
-const fetcher = useScapiFetcher(
-    clientName,    // SCAPI client: 'shopperSearch', 'shopperProducts', etc.
-    methodName,    // Method: 'getSearchSuggestions', 'productSearch', etc.
-    parameters     // SCAPI parameters object
-);
+```tsx
+const product = useScapiFetcher('shopperProducts', 'getProduct', {
+    params: { path: { id: variantId }, query: { expand: ['availability', 'prices'] } },
+});
 
-// Properties
-fetcher.data       // Response data (undefined until loaded)
-fetcher.state      // 'idle' | 'loading' | 'submitting'
-fetcher.load()     // Trigger a GET request
-fetcher.submit()   // Trigger a POST request
+useEffect(() => {
+    if (variantId && product.state === 'idle' && !product.data && !product.errors) void product.load();
+}, [variantId, product]);  // keep deps stable; see checklist
 ```
 
-## loader vs useScapiFetcher
+Returned object: `.load()` (GET), `.submit(payload, opts)` (mutation), `.data`, `.errors`, `.success`, plus the fetcher fields such as `.state`.
 
-| Scenario | Use |
-|----------|-----|
-| Load product data on page visit | `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` |
+Real users: `src/providers/basket.tsx` (`shopperBasketsV2.getBasket`) and `src/components/cart-item-modal/*` (`shopperProducts.getProduct`).
 
-## Timeline Comparison
+## Server allowlist (`src/lib/scapi/resource-policy.ts`)
 
-```
-loader (Server):
-  [navigate] → [server fetch] → [stream to client]
-  Data available: Streamed during render via Suspense
+- Loaders: `shopperBasketsV2.getBasket`, `shopperProducts.getProduct`, `shopperProducts.getProducts`, `shopperSearch.getSearchSuggestions`.
+- Actions: `shopperCustomers.createCustomerAddress`, `updateCustomerAddress`, `removeCustomerAddress`, `updateCustomer`, `updateCustomerPassword`.
 
-useScapiFetcher:
-  [render] → [user action] → [fetch] → [re-render]
-  Data available: AFTER user action, component re-renders
-```
+Everything else is rejected. `organizationId`, `siteId` and `locale` are set by the server, and request bodies and headers are sanitized. The older "helpers" overload is unsupported.
 
-## Complete Example: Search Suggestions
+Need something else (recommendations, category products, your own custom API)? Create a `resource.*` route with a `loader`. Pattern: same-origin check, input validation, `Cache-Control: no-store` for personalized output (`resource.recommendations.ts`, `resource.category-products.ts`). To allow another client call, change `resource-policy.ts` deliberately and add a test; do not widen it casually.
 
-```typescript
-import { useScapiFetcher } from '@/hooks/use-scapi-fetcher';
-import { useMemo, useCallback } from 'react';
+## Related hooks
 
-export function useSearchSuggestions({ q, limit, currency }) {
-    const parameters = useMemo(
-        () => ({
-            params: {
-                query: { q, limit, currency }
-            }
-        }),
-        [q, limit, currency]
-    );
+- `useScapiFetcherEffect(fetcher, { onSuccess, onError })` runs callbacks once per completed request.
+- `useScapiFetchClient` (`@/hooks/use-scapi-fetch`) is a lower-level, non-fetcher variant for one-off calls.
 
-    const fetcher = useScapiFetcher(
-        'shopperSearch',
-        'getSearchSuggestions',
-        parameters
-    );
+## When not to use it
 
-    const refetch = useCallback(async () => {
-        await fetcher.load();
-    }, [fetcher]);
+If the data is knowable at request time, fetch it in the loader. Mounting a component that fires `useScapiFetcher().load()` in an effect for data the route could have streamed adds a waterfall; see the performance review checklist in `storefront-next:sfnext-performance`.
 
-    return {
-        data: fetcher.data,
-        isLoading: fetcher.state === 'loading',
-        refetch
-    };
-}
-```
+Calls made through `useScapiFetcher().load()` are fetcher loads, not submissions, so they do not revalidate other loaders. `.submit()` is a submission and does.