@salesforce/b2c-dx-mcp 3.2.0 → 3.3.0

package/content/guidance/storefront-next/sfnext-create-vertical/references/TOKEN-SYSTEM.md

@@ -1,130 +0,0 @@
-# Token System Reference
-
-## The one rule that overrides everything else
-
-**Never use a raw hex value, RGB value, or hardcoded color in any component or CSS file.**
-Always use a semantic Tailwind utility that maps to a CSS variable. The variables are defined in
-`src/theme/tokens/` and bridged to Tailwind utilities in `src/theme/tailwind.css`.
-
-```tsx
-// ✅ correct
-<div className="bg-primary text-primary-foreground" />
-
-// ❌ wrong — breaks dark mode, breaks vertical theming, breaks Figma sync
-<div style={{ background: '#000000', color: '#ffffff' }} />
-<div className="bg-black text-white" />
-```
-
-## Token files and what they own
-
-| File | Owns |
-|------|------|
-| `src/theme/tokens/core.css` | Background, foreground, card, popover, primary, secondary, muted, accent, border, input, ring, separator, rating, charts, sidebar, focus helpers |
-| `src/theme/tokens/brand.css` | Brand palette (`--brand-black`, `--brand-white`, `--brand-gray-*`, `--brand-primary`). **This is the only file that changes per vertical.** |
-| `src/theme/tokens/header.css` | Header background/foreground, header menu surfaces, footer. Dark header = black bg / white text. |
-| `src/theme/tokens/status.css` | Destructive, warning, success, info, status-positive/warning/critical, active-bg |
-| `src/theme/tokens/swatch.css` | Swatch color, labeled, pill — variant selector UI only |
-| `src/theme/tokens/components.css` | Payment provider colors, cart-specific tokens |
-
-## Semantic token meanings — use the right one
-
-### Text colors
-| Token class | When to use |
-|-------------|-------------|
-| `text-foreground` | Default body text, headings |
-| `text-muted-foreground` | Secondary labels, helper text, placeholder, metadata |
-| `text-primary-foreground` | Text on a `bg-primary` surface (e.g. button label) |
-| `text-secondary-foreground` | Text on a `bg-secondary` surface |
-| `text-accent-foreground` | Text on a `bg-accent` surface (hover chips, tags) |
-| `text-destructive` | Error text, destructive action labels |
-| `text-card-foreground` | Text inside card surfaces |
-
-### Background colors
-| Token class | When to use |
-|-------------|-------------|
-| `bg-background` | Page/app background |
-| `bg-primary` | CTAs, filled buttons, strong actions |
-| `bg-secondary` | Secondary button fill, subtle section bg |
-| `bg-muted` | Skeleton, disabled surfaces, subtle fills |
-| `bg-accent` | Hover state, selected chip, tag bg |
-| `bg-card` | Card and tile surfaces |
-| `bg-popover` | Dropdown, tooltip, modal backgrounds |
-
-### Borders
-| Token class | When to use |
-|-------------|-------------|
-| `border-border` | Standard dividers, list separators — uses alpha so it renders correctly on ANY surface color |
-| `border-border-subtle` | Form inputs, card edges — slightly more visible |
-| `border-input` | Input field border specifically |
-| `ring-ring` | Focus ring on interactive elements |
-
-**Never use `border-black`, `border-gray-*`, or `divide-gray-*`.** Use `border-border` or `border-border-subtle`.
-
-### Header/navigation surfaces
-| Token class | When to use |
-|-------------|-------------|
-| `bg-[--header-background]` | Header band background |
-| `text-[--header-foreground]` | Header text and icons |
-| `bg-[--header-menu-background]` | Mega/dropdown menu panel |
-| `bg-[--footer-background]` | Footer background |
-
-### Status and feedback
-| Token class | When to use |
-|-------------|-------------|
-| `text-destructive` / `bg-destructive` | Delete, remove, error state |
-| `bg-warning-bg` / `text-warning-foreground` | Caution messages |
-| `text-status-positive` | In-stock, success indicator |
-| `text-status-critical` | Out of stock, error badge |
-| `bg-active-bg` / `text-active-foreground` | Active/authorized badge |
-
-## Dark mode rules
-
-**Do not write `dark:bg-black` or any dark: hardcoded color.**
-Dark mode is fully handled by `.dark` overrides in `src/theme/tokens/core.css` and other token files.
-Using semantic classes automatically gets the correct dark value.
-
-```tsx
-// ✅ correct — dark mode is automatic
-<div className="bg-card text-card-foreground" />
-
-// ❌ wrong
-<div className="bg-white dark:bg-gray-900 text-black dark:text-white" />
-```
-
-The only valid `dark:` usage is for classes that reference another semantic token:
-
-```tsx
-// ✅ valid dark: override pattern
-className="dark:bg-input/30 dark:border-input"
-```
-
-## What changes per vertical — and what does not
-
-### Changes (vertical-specific, lives in `src/theme/tokens/brand.css`)
-- Brand palette values (`--brand-black`, `--brand-primary`, `--brand-gray-*`)
-- Logo treatment (`--header-logo-filter`)
-- Brand-specific component tokens
-
-### Does NOT change (shared, lives in core/header/status/swatch/components)
-- Semantic token names and their Tailwind utility names
-- Dark mode pairing rules
-- Component variant logic (CVA)
-- Border alpha values
-- Status and feedback colors
-
-**Never override core.css, header.css, status.css, swatch.css, or components.css to create a vertical.**
-Only `brand.css` changes between verticals.
-
-## Tailwind utility bridge
-
-All token → Tailwind utility mappings are defined in `src/theme/tailwind.css`.
-If a CSS variable exists in a token file but has no Tailwind utility in `tailwind.css`, add it there
-before using it in a component. Do not use arbitrary `[--variable-name]` syntax for variables that
-should be in the bridge.
-
-```css
-/* src/theme/tailwind.css — add new token bridge entries here */
---color-my-new-token: var(--my-new-token);
-```
-
-Then use `bg-my-new-token` in components.

package/content/guidance/storefront-next/sfnext-create-vertical/references/TROUBLESHOOTING.md

@@ -1,34 +0,0 @@
-# Troubleshooting Reference
-
-## Token not found in Tailwind utilities
-If a CSS variable exists in a token file but has no Tailwind utility in `tailwind.css`:
-- Open `src/theme/tailwind.css`.
-- Add a bridge entry: `--color-my-new-token: var(--my-new-token);`.
-- Then use `bg-my-new-token` in components — never the `bg-[--my-new-token]` arbitrary syntax.
-
-## Colors look wrong in dark mode
-- You probably hardcoded a color (`bg-white`, `text-black`, raw hex) instead of using a semantic token.
-- Replace with the semantic utility (`bg-background`, `text-foreground`, etc.). Dark mode is handled by `.dark` overrides in the token files automatically.
-
-## Vertical changes leak into other verticals
-- You edited a shared token file (`core.css`, `header.css`, `status.css`, `swatch.css`, `components.css`). Move the change into `brand.css`.
-- Or you added `if (vertical)` logic to a shared component. Replace it with a CVA variant, a slot/render-prop on the base, or an extension.
-
-## Component already exists
-If a scan finds an existing component that covers the need:
-- Add a new CVA variant instead of creating a new component.
-- Wrap in a thin composite if behaviour differs.
-- Never duplicate.
-
-## Local pages won't render without SCAPI
-- Use fixtures: create `src/config/<vertical>-fixtures.ts` and short-circuit the `_app.tsx` and `_app.product.$productId.tsx` loaders during vertical development.
-- Restore the real SCAPI calls once credentials are available.
-
-## Linter errors after changes
-Run `pnpm lint:fix` first. If errors remain, check:
-- Missing copyright header (required on every `.ts`/`.tsx` file).
-- Raw hex value or hardcoded Tailwind color — replace with a semantic token class.
-- Missing `data-slot` attribute on a component root.
-
-## Snapshot tests fail after visual changes
-Run `pnpm test-storybook:snapshot:agent -- --updateSnapshot` to update baselines after intentional visual changes.

package/content/guidance/storefront-next/sfnext-custom-apis/SKILL.md

@@ -1,221 +0,0 @@
----
-name: sfnext-custom-apis
-description: End-to-end workflow for consuming custom SCAPI endpoints from a Storefront Next project — adding them as typed clients via `b2c sfnext scapi add custom`, discovering their schema, and calling them from loaders/actions/useScapiFetcher. Use this skill whenever the user wants to call a custom API from their Storefront Next app, gets a 404 or 401 when calling a custom endpoint from their sfnext loader, needs to add a custom API as a typed client in their storefront, asks about the full workflow from custom API cartridge to sfnext consumption, or says 'custom API in storefront next'. Also use when they ask how createApiClients exposes custom API methods or how to use useScapiFetcher with a custom endpoint. NOT for writing the custom API cartridge files (schema.yaml/script.js) from scratch — see b2c:b2c-custom-api-development. NOT for just checking registration status — see b2c-cli:b2c-scapi-custom.
----
-
-# Custom APIs in Storefront Next
-
-This skill covers the end-to-end workflow for implementing and consuming custom SCAPI endpoints from a Storefront Next project.
-
-## Overview
-
-Custom APIs let you define your own REST endpoints on B2C Commerce. In a Storefront Next project, you call these from loaders and actions just like standard SCAPI clients — with full type safety.
-
-### End-to-End Workflow
-
-```
-Create custom API    →  Deploy & register  →  Add typed client  →  Discover schema  →  Call from loader
-(cartridge)             (b2c code deploy)     (sfnext scapi add)   (scapi schemas)     (createApiClients)
-```
-
-## Step 1: Create the Custom API
-
-A custom API consists of three files in a cartridge:
-
-```
-my-cartridge/cartridge/rest-apis/my-loyalty-api/
-├── schema.yaml     # OpenAPI 3.0 schema (endpoints, params, responses)
-├── api.json        # API metadata (version, security scheme)
-└── script.js       # Implementation (controller script)
-```
-
-For full details on writing these files, see the `b2c:b2c-custom-api-development` skill.
-
-**Key choices that affect the client:**
-
-| Choice | Impact |
-|--------|--------|
-| Directory name (`my-loyalty-api`) | Becomes the API name for `scapi add` |
-| `type` in api.json (`shopper` or `admin`) | Determines auth scheme and whether `siteId` is required |
-| Paths in schema.yaml | Become the methods on the typed client |
-
-## Step 2: Deploy and Register
-
-Deploy the cartridge and verify the custom API is registered:
-
-```bash
-# deploy the cartridge
-b2c code deploy ./my-cartridge --activate
-
-# verify registration
-b2c scapi custom status
-```
-
-A successful registration shows `status: active` for your endpoints. If you see `not_registered`, debug with:
-
-```bash
-b2c scapi custom status --status not_registered --columns type,apiName,endpointPath,errorReason
-```
-
-See `b2c-cli:b2c-scapi-custom` for full diagnostics.
-
-## Step 3: Add as Typed Client
-
-Once registered, add the custom API to your Storefront Next project:
-
-```bash
-b2c sfnext scapi add custom my-loyalty-api v1
-```
-
-This generates typed client code. The client becomes available as:
-
-```typescript
-const clients = createApiClients(context);
-clients.myLoyaltyApi.getPoints({...});
-```
-
-## Step 4: Discover the API Shape
-
-Use schema browsing to understand your custom API's endpoints and response types:
-
-```bash
-# list endpoints
-b2c scapi schemas get custom my-loyalty-api v1 --list-paths
-
-# expand a specific endpoint
-b2c scapi schemas get custom my-loyalty-api v1 \
-  --expand-paths /loyalty/points/{customerId}
-```
-
-This shows you the exact parameter names and response shape to use in your loader.
-
-## Step 5: Call from Loaders and Actions
-
-### Calling from a Loader (Shopper API)
-
-```typescript
-import { createApiClients } from '@/lib/api-clients';
-
-export function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        loyaltyPoints: clients.myLoyaltyApi.getPoints({
-            params: {
-                path: { customerId: params.customerId },
-                query: { siteId: context.siteId }
-            }
-        }).then(({ data }) => data),
-    };
-}
-```
-
-### Calling from an Action (Mutation)
-
-```typescript
-import { data } from 'react-router';
-import { createApiClients } from '@/lib/api-clients';
-
-export async function action({ request, context }: ActionFunctionArgs) {
-    const formData = await request.formData();
-    const clients = createApiClients(context);
-
-    try {
-        await clients.myLoyaltyApi.redeemPoints({
-            params: {
-                path: { customerId: formData.get('customerId') as string },
-                query: { siteId: context.siteId },
-                body: { points: Number(formData.get('points')) }
-            }
-        });
-        return data({ success: true });
-    } catch (error) {
-        return data({ success: false, error: error.message }, { status: 400 });
-    }
-}
-```
-
-### Using useScapiFetcher (Interactive)
-
-For on-demand fetching triggered by user interactions:
-
-```typescript
-import { useScapiFetcher } from '@/hooks/use-scapi-fetcher';
-
-export function useLoyaltyPoints(customerId: string) {
-    const parameters = useMemo(
-        () => ({
-            params: {
-                path: { customerId },
-                query: { siteId: getSiteId() }
-            }
-        }),
-        [customerId]
-    );
-
-    const fetcher = useScapiFetcher(
-        'myLoyaltyApi',
-        'getPoints',
-        parameters
-    );
-
-    return {
-        points: fetcher.data,
-        isLoading: fetcher.state === 'loading',
-        refresh: () => fetcher.load(),
-    };
-}
-```
-
-## Step 6: Debug Issues
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Client property not available | Forgot `sfnext scapi add` | Run `b2c sfnext scapi add custom <name> <version>` |
-| 404 from custom endpoint | API not registered | Check `b2c scapi custom status`; redeploy with `--activate` |
-| 401 Unauthorized | Wrong security scheme | Shopper APIs use ShopperToken; Admin APIs use BearerToken |
-| Missing `siteId` error | Shopper custom APIs require siteId | Always include `siteId` in query params for Shopper APIs |
-| Schema returns empty | API not yet registered | Deploy and activate the cartridge first, then browse schemas |
-| Types outdated after schema change | Stale generated types | Re-run `b2c sfnext scapi add custom <name> <version> --force` |
-
-## Custom API Client Naming
-
-The API directory name maps to a camelCase property on `createApiClients()`:
-
-| Directory Name | Client Property | Example Call |
-|---------------|-----------------|-------------|
-| `my-loyalty-api` | `clients.myLoyaltyApi` | `clients.myLoyaltyApi.getPoints({...})` |
-| `order-status` | `clients.orderStatus` | `clients.orderStatus.getStatus({...})` |
-| `inventory-check` | `clients.inventoryCheck` | `clients.inventoryCheck.checkStock({...})` |
-
-## Shopper vs Admin Custom APIs
-
-| Aspect | Shopper API | Admin API |
-|--------|-------------|-----------|
-| Auth scheme | ShopperToken (SLAS) | BearerToken (Account Manager) |
-| Requires `siteId` | Yes | No |
-| Called from | Storefront loaders/actions | Admin tools, batch jobs |
-| Typical use | Customer-facing features | Back-office operations |
-
-Most Storefront Next custom APIs are **Shopper** type since they serve storefront pages.
-
-## Common Pitfalls
-
-| Pitfall | Problem | Solution |
-|---------|---------|----------|
-| Using admin auth for a shopper endpoint | 401 errors in storefront context | Set `type: "shopper"` in api.json |
-| Forgetting to redeploy after schema changes | Stale endpoints | Redeploy cartridge and re-add client with `--force` |
-| Not including `siteId` for shopper APIs | Request rejected | Always pass `siteId` in query params |
-| Calling custom API before registration completes | Intermittent 404s | Wait for `status: active` in `b2c scapi custom status` |
-
-## Related Skills
-
-- `storefront-next:sfnext-scapi-management` - Managing typed clients (add/remove/list)
-- `storefront-next:sfnext-data-fetching` - Loader/action/useScapiFetcher patterns
-- `b2c:b2c-custom-api-development` - Creating the custom API cartridge (schema + script + mapping)
-- `b2c-cli:b2c-scapi-custom` - Checking custom API registration status
-- `b2c-cli:b2c-scapi-schemas` - Schema discovery commands
-- `b2c-cli:b2c-code` - Deploying and activating code versions
-
-## Reference Documentation
-
-- [Workflow Examples](references/WORKFLOW-EXAMPLES.md) - Complete end-to-end worked examples

package/content/guidance/storefront-next/sfnext-custom-apis/references/WORKFLOW-EXAMPLES.md

@@ -1,294 +0,0 @@
-# Workflow Examples
-
-Complete end-to-end examples showing the full lifecycle from custom API creation through calling from a Storefront Next storefront.
-
-## Example 1: Shopper Custom API — Loyalty Points
-
-A customer-facing API that retrieves and redeems loyalty points.
-
-### Cartridge Structure
-
-```
-loyalty-cartridge/cartridge/rest-apis/loyalty-points/
-├── schema.yaml
-├── api.json
-└── script.js
-```
-
-### schema.yaml
-
-```yaml
-openapi: "3.0.0"
-info:
-  title: Loyalty Points API
-  version: "v1"
-paths:
-  /points/{customerId}:
-    get:
-      operationId: getPoints
-      parameters:
-        - name: customerId
-          in: path
-          required: true
-          schema:
-            type: string
-        - name: siteId
-          in: query
-          required: true
-          schema:
-            type: string
-      responses:
-        "200":
-          description: Customer loyalty points
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/LoyaltyBalance"
-  /points/{customerId}/redeem:
-    post:
-      operationId: redeemPoints
-      parameters:
-        - name: customerId
-          in: path
-          required: true
-          schema:
-            type: string
-        - name: siteId
-          in: query
-          required: true
-          schema:
-            type: string
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/RedeemRequest"
-      responses:
-        "200":
-          description: Redemption result
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/RedeemResult"
-components:
-  schemas:
-    LoyaltyBalance:
-      type: object
-      properties:
-        customerId:
-          type: string
-        points:
-          type: integer
-        tier:
-          type: string
-          enum: [bronze, silver, gold, platinum]
-        lastUpdated:
-          type: string
-          format: date-time
-    RedeemRequest:
-      type: object
-      required: [points]
-      properties:
-        points:
-          type: integer
-          minimum: 1
-    RedeemResult:
-      type: object
-      properties:
-        success:
-          type: boolean
-        remainingPoints:
-          type: integer
-        transactionId:
-          type: string
-```
-
-### api.json
-
-```json
-{
-  "type": "shopper",
-  "version": "v1"
-}
-```
-
-### Deploy and Register
-
-```bash
-# deploy the cartridge
-b2c code deploy ./loyalty-cartridge --activate
-
-# verify registration
-b2c scapi custom status --api-name loyalty-points
-```
-
-### Add to Storefront Next Project
-
-```bash
-b2c sfnext scapi add custom loyalty-points v1
-```
-
-### Discover and Use
-
-```bash
-# check endpoints
-b2c scapi schemas get custom loyalty-points v1 --list-paths
-
-# inspect response shape
-b2c scapi schemas get custom loyalty-points v1 \
-  --expand-paths /points/{customerId} \
-  --expand-schemas LoyaltyBalance
-```
-
-### Storefront Code
-
-```typescript
-// src/routes/_app.account.loyalty.tsx
-import { createApiClients } from '@/lib/api-clients';
-import { createPage } from '@/lib/create-page';
-
-interface LoyaltyPageData {
-    balance: Promise<LoyaltyBalance>;
-}
-
-export function loader({ context }: LoaderFunctionArgs): LoyaltyPageData {
-    const clients = createApiClients(context);
-    const customerId = context.session.customerId;
-
-    return {
-        balance: clients.loyaltyPoints.getPoints({
-            params: {
-                path: { customerId },
-                query: { siteId: context.siteId }
-            }
-        }).then(({ data }) => data),
-    };
-}
-
-export default createPage<LoyaltyPageData>(({ data }) => (
-    <div className="space-y-4">
-        <h1 className="text-2xl font-bold">Loyalty Points</h1>
-        <Suspense fallback={<Skeleton className="h-24" />}>
-            <Await resolve={data.balance}>
-                {(balance) => (
-                    <div className="rounded-lg border p-6">
-                        <p className="text-4xl font-bold">{balance.points}</p>
-                        <p className="text-muted-foreground">
-                            {balance.tier} tier
-                        </p>
-                    </div>
-                )}
-            </Await>
-        </Suspense>
-    </div>
-));
-```
-
----
-
-## Example 2: Admin Custom API — Inventory Check
-
-An admin API for back-office inventory operations. Admin APIs use BearerToken auth and do not require `siteId`.
-
-### Key Differences from Shopper APIs
-
-| Aspect | This Example | Example 1 (Shopper) |
-|--------|-------------|---------------------|
-| api.json `type` | `"admin"` | `"shopper"` |
-| Auth | BearerToken (Account Manager) | ShopperToken (SLAS) |
-| `siteId` param | Not required | Required |
-| Typical caller | Admin tools, cron jobs | Storefront loaders |
-
-### api.json
-
-```json
-{
-  "type": "admin",
-  "version": "v1"
-}
-```
-
-### Usage in Storefront Context
-
-Admin APIs are typically NOT called from storefront loaders (since storefronts use shopper auth). If you need admin-level data in a storefront, consider:
-
-1. Using a shopper API that exposes the same data with appropriate access controls
-2. Pre-computing results and storing them in a custom object accessible via shopper APIs
-
----
-
-## Example 3: useScapiFetcher with Custom API
-
-Interactive pattern for fetching custom API data after page load (e.g., showing loyalty points in a modal that opens on click).
-
-```typescript
-// src/hooks/use-loyalty-points.ts
-import { useScapiFetcher } from '@/hooks/use-scapi-fetcher';
-import { useMemo, useCallback } from 'react';
-
-export function useLoyaltyPoints(customerId: string | undefined) {
-    const parameters = useMemo(
-        () => customerId ? {
-            params: {
-                path: { customerId },
-                query: { siteId: getSiteId() }
-            }
-        } : null,
-        [customerId]
-    );
-
-    const fetcher = useScapiFetcher(
-        'loyaltyPoints',
-        'getPoints',
-        parameters
-    );
-
-    const refresh = useCallback(async () => {
-        if (parameters) {
-            await fetcher.load();
-        }
-    }, [fetcher, parameters]);
-
-    return {
-        points: fetcher.data?.points ?? 0,
-        tier: fetcher.data?.tier ?? 'bronze',
-        isLoading: fetcher.state === 'loading',
-        refresh,
-    };
-}
-```
-
-```typescript
-// src/components/loyalty-badge.tsx
-import { useLoyaltyPoints } from '@/hooks/use-loyalty-points';
-
-export function LoyaltyBadge({ customerId }: { customerId: string }) {
-    const { points, tier, isLoading, refresh } = useLoyaltyPoints(customerId);
-
-    useEffect(() => {
-        refresh();
-    }, [refresh]);
-
-    if (isLoading) return <Skeleton className="h-6 w-16" />;
-
-    return (
-        <Badge variant={tier === 'platinum' ? 'default' : 'secondary'}>
-            {points} pts
-        </Badge>
-    );
-}
-```
-
-### How It Works
-
-```
-LoyaltyBadge renders
-  → useLoyaltyPoints calls useScapiFetcher('loyaltyPoints', 'getPoints', params)
-  → fetcher.load() sends GET to /resource/api/client/{encoded-params}
-  → Resource route runs ON SERVER
-  → createApiClients(context).loyaltyPoints.getPoints({...}) calls SCAPI
-  → JSON response returned to component
-```
-
-The custom API call happens server-side even though it's triggered from a client component.