@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/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.

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

@@ -1,102 +0,0 @@
-# Loader Patterns Reference
-
-## Data Flow
-
-### Initial Page Load (SSR)
-
-```
-Browser request → MRT Server
-                  ↓
-             loader() runs on server
-                  ↓
-             SCAPI requests on MRT
-                  ↓
-             HTML response streamed → Browser
-```
-
-### Subsequent Navigation (SPA)
-
-```
-User clicks link → React Router intercepts
-                   ↓
-              Browser fetches from server
-                   ↓
-              MRT Server runs same loader()
-                   ↓
-              SCAPI requests on MRT
-                   ↓
-              JSON response → Browser
-                   ↓
-              React updates DOM
-```
-
-The loader code is identical for SSR and SPA navigation — only the response format differs (HTML vs JSON).
-
-## Decision Tree: Which Pattern to Use
-
-```
-Need data for page render?
-├── Critical for SEO / above-the-fold?
-│   └── Use awaited data (async loader with await)
-├── Non-critical / below-the-fold?
-│   └── Use deferred data (sync loader, return promises)
-└── Mix of both?
-    └── Use mixed strategy (await critical, stream rest)
-
-Need to handle mutations?
-└── Use action function
-
-Need data after page load (user interaction)?
-└── Use useScapiFetcher
-```
-
-## Pattern: Multiple API Calls with Dependencies
-
-When one API call depends on another's result:
-
-```typescript
-export async function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-
-    // First call — must resolve before dependent calls
-    const category = await clients.shopperProducts.getCategory({
-        params: { path: { id: params.categoryId } }
-    }).then(({ data }) => data);
-
-    // Dependent calls — can run in parallel with each other
-    return {
-        category,
-        products: clients.shopperSearch.productSearch({
-            params: { query: { refine: `cgid=${category.id}` } }
-        }).then(({ data }) => data),
-        refinements: clients.shopperSearch.getSearchSuggestions({
-            params: { query: { q: category.name } }
-        }).then(({ data }) => data),
-    };
-}
-```
-
-## Pattern: Conditional Data Loading
-
-```typescript
-export function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    const auth = getAuth(context);
-
-    const base = {
-        product: clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-    };
-
-    // Only fetch wishlist for registered users
-    if (auth.userType === 'registered') {
-        return {
-            ...base,
-            wishlist: clients.shopperCustomers.getWishlist({...}).then(({ data }) => data),
-        };
-    }
-
-    return base;
-}
-```

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-project-setup/references/ENV-VARIABLES.md

@@ -1,82 +0,0 @@
-# Environment Variables Reference
-
-## Naming Convention
-
-Environment variables use the `PUBLIC__` prefix with double underscore (`__`) separators to map to configuration paths:
-
-```bash
-# Pattern: PUBLIC__app__{path}__{to}__{property}=value
-PUBLIC__app__commerce__api__clientId=abc123
-# Maps to: config.app.commerce.api.clientId
-# Accessed as: getConfig(context).commerce.api.clientId
-```
-
-## Rules
-
-1. **`PUBLIC__` prefix** — Exposed to browser (client-safe values only)
-2. **No prefix** — Server-only secrets (never sent to client)
-3. **`__` separator** — Navigates nested config paths
-4. **Case-insensitive** — All casings work (normalized to match `config.server.ts`)
-5. **Auto-parsing** — Strings, numbers, booleans, JSON arrays/objects parsed automatically
-6. **Validation** — Paths must exist in `config.server.ts` (prevents typos)
-7. **Depth limit** — Maximum 10 levels deep (use JSON 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
-
-## Required Variables
-
-| Variable | Description |
-|----------|-------------|
-| `PUBLIC__app__commerce__api__clientId` | SLAS client ID |
-| `PUBLIC__app__commerce__api__organizationId` | Commerce Cloud organization ID |
-| `PUBLIC__app__commerce__api__siteId` | Default site ID |
-| `PUBLIC__app__commerce__api__shortCode` | API short code |
-| `PUBLIC__app__defaultSiteId` | Default site ID for routing |
-| `PUBLIC__app__commerce__sites` | JSON array of site configurations |
-
-## Server-Only Variables
-
-```bash
-# Server-only secrets (no PUBLIC__ prefix)
-COMMERCE_API_SLAS_SECRET=your-slas-secret
-```
-
-Access server-only secrets via `process.env` directly — never add them to the config system.
-
-## Multi-Site Configuration
-
-The `commerce.sites` array defines site configurations:
-
-```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"]
-  }
-]'
-```
-
-## Setting Complex Values
-
-```bash
-# Individual variables
-PUBLIC__app__myFeature__option1=value1
-PUBLIC__app__myFeature__option2=value2
-
-# Or as a single JSON value
-PUBLIC__app__myFeature='{"option1":"value1","option2":"value2"}'
-```
-
-## Security Guidelines
-
-| Prefix | Visibility | Use For |
-|--------|-----------|---------|
-| `PUBLIC__` | Browser + Server | Client IDs, site IDs, feature flags |
-| (none) | Server only | API secrets, private keys, credentials |

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

@@ -1,203 +0,0 @@
----
-name: sfnext-scapi-management
-description: Add, remove, and list typed SCAPI clients in a Storefront Next project using `b2c sfnext scapi` commands, and browse API schemas to discover endpoints before writing loaders. Use this skill whenever the user says 'sfnext scapi', 'add an API to my storefront next project', 'what SCAPI clients does my sfnext project have', 'remove an API client', 'list available APIs for sfnext', 'browse schema before writing a loader', or asks how to integrate a specific SCAPI (shopper-baskets, shopper-search, etc.) into their Storefront Next project as a typed client. Also use when they want to check what parameters an endpoint accepts before coding. NOT for making actual SCAPI calls from loaders — see sfnext-data-fetching. NOT for standalone schema browsing outside a Storefront Next project — see b2c-cli:b2c-scapi-schemas.
----
-
-# SCAPI Client Management Skill
-
-This skill covers managing which typed SCAPI clients are available in a Storefront Next project and how to discover their shapes before writing data-fetching code.
-
-## Overview
-
-Storefront Next projects use typed SCAPI clients generated from OpenAPI schemas. Two complementary command sets work together:
-
-| Command Set | Purpose | When to Use |
-|-------------|---------|-------------|
-| `b2c sfnext scapi` | Manage which clients exist in your project | Adding/removing APIs, checking what's configured |
-| `b2c scapi schemas` | Browse API shapes (endpoints, fields, types) | Before writing a loader — discover what's available |
-
-## Managing Project Clients
-
-### List Available APIs
-
-See what SCAPI APIs can be added to your project:
-
-```bash
-# show all APIs available to add
-b2c sfnext scapi available
-
-# filter by API family
-b2c sfnext scapi available --api-family product
-
-# JSON output for scripting
-b2c sfnext scapi available --json
-```
-
-### Add a Client
-
-Add a typed SCAPI client to your project. This generates type-safe client code accessible via `createApiClients(context)`:
-
-```bash
-# add the shopper-products API
-b2c sfnext scapi add product shopper-products v1
-
-# add a custom API
-b2c sfnext scapi add custom my-loyalty-api v1
-
-# force re-add (overwrite existing)
-b2c sfnext scapi add product shopper-products v1 --force
-```
-
-After adding, the client becomes available in your loaders:
-
-```typescript
-import { createApiClients } from '@/lib/api-clients';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-    };
-}
-```
-
-### List Current Project Clients
-
-See which SCAPI clients are currently configured in your project:
-
-```bash
-# list all configured clients
-b2c sfnext scapi list
-
-# JSON output
-b2c sfnext scapi list --json
-```
-
-### Remove a Client
-
-Remove an unused client to reduce bundle size:
-
-```bash
-# remove a client
-b2c sfnext scapi remove product shopper-products
-```
-
-## Discovering API Shapes
-
-Before writing a loader or action, use `b2c scapi schemas` to explore what endpoints and fields an API offers.
-
-### The Schema-First Workflow
-
-```
-1. b2c scapi schemas list              → Find the API family/name/version
-2. b2c scapi schemas get ... --list-paths   → See available endpoints
-3. b2c scapi schemas get ... --expand-paths → See request params + response shape
-4. Write your loader using the discovered types
-```
-
-### Step 1: Find the API
-
-```bash
-# list all available schemas
-b2c scapi schemas list
-
-# filter to product APIs
-b2c scapi schemas list --api-family product
-```
-
-### Step 2: See Available Endpoints
-
-```bash
-# list all paths in shopper-products
-b2c scapi schemas get product shopper-products v1 --list-paths
-```
-
-Output shows endpoints like `/products/{productId}`, `/products`, etc.
-
-### Step 3: Expand Endpoint Details
-
-```bash
-# see the full shape of a specific endpoint
-b2c scapi schemas get product shopper-products v1 --expand-paths /products/{productId}
-
-# see the response schema type
-b2c scapi schemas get product shopper-products v1 --expand-schemas Product
-
-# combine: endpoint + its response type
-b2c scapi schemas get product shopper-products v1 \
-  --expand-paths /products/{productId} \
-  --expand-schemas Product,ProductResult
-```
-
-### Step 4: Write Your Loader
-
-Now that you know the endpoint path and parameter structure, write your loader:
-
-```typescript
-export function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-    };
-}
-```
-
-## Example: Adding and Using a New API
-
-Complete walkthrough — adding shopper-search and writing a search loader:
-
-```bash
-# 1. Check what's available
-b2c sfnext scapi available --api-family search
-
-# 2. Add the client
-b2c sfnext scapi add search shopper-search v1
-
-# 3. Discover endpoints
-b2c scapi schemas get search shopper-search v1 --list-paths
-
-# 4. Inspect the productSearch endpoint
-b2c scapi schemas get search shopper-search v1 \
-  --expand-paths /product-search \
-  --expand-schemas ProductSearchResult
-```
-
-Then write the loader:
-
-```typescript
-export function loader({ request, context }: LoaderFunctionArgs) {
-    const url = new URL(request.url);
-    const q = url.searchParams.get('q') ?? '';
-    const clients = createApiClients(context);
-
-    return {
-        results: clients.shopperSearch.productSearch({
-            params: { query: { q, limit: 25 } }
-        }).then(({ data }) => data),
-    };
-}
-```
-
-## Common Pitfalls
-
-| Pitfall | Problem | Solution |
-|---------|---------|----------|
-| Writing a loader without checking the schema | Wrong parameter names or missing required fields | Run `--expand-paths` first to see exact param structure |
-| Adding an API but client not appearing | Missing `pnpm install` after add | Run `pnpm install` to regenerate types |
-| Trying to browse custom API schemas before registration | Schema returns empty/404 | Deploy and register the custom API first (see `sfnext-custom-apis`) |
-| Using wrong API version | Types don't match runtime behavior | Use `scapi available` to verify the current version |
-
-## Related Skills
-
-- `storefront-next:sfnext-data-fetching` - Using the clients in loaders, actions, and useScapiFetcher
-- `storefront-next:sfnext-custom-apis` - End-to-end custom API implementation and consumption
-- `b2c-cli:b2c-scapi-schemas` - Full reference for schema browsing commands and flags
-- `storefront-next:sfnext-project-setup` - Project creation and initial structure
-
-## Reference Documentation
-
-- [CLI Commands Reference](references/CLI-COMMANDS.md) - Detailed command reference for `b2c sfnext scapi`

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

@@ -1,12 +0,0 @@
-[
-  {"query": "I just scaffolded a new storefront next project and I need to add the shopper-search API so I can build a search results page. What's the command to add it and how do I verify it's available in my createApiClients factory?", "should_trigger": true},
-  {"query": "How do I run b2c sfnext scapi available to see which APIs I can add to my storefront next project? I want to know what's available before setting up my data fetching.", "should_trigger": true},
-  {"query": "I need to integrate the shopper-baskets-v2 API into my storefront next checkout flow. Can you walk me through the b2c sfnext scapi add command and then checking the schema?", "should_trigger": true},
-  {"query": "I ran b2c sfnext scapi list and see APIs I no longer use in my storefront next project. How do I remove them with scapi remove to reduce my bundle size?",  "should_trigger": true},
-  {"query": "I'm setting up a new storefront next project and want to add the shopper-customers API as a typed client. What does b2c sfnext scapi add do exactly and where does the generated client code end up?", "should_trigger": true},
-  {"query": "I have the shopper-products client already added. Now I need to write a loader function that calls getProduct and returns the data. How do I use createApiClients in a route loader?", "should_trigger": false},
-  {"query": "My storefront next build is failing because of TypeScript errors in my route components. How do I run the typecheck and fix the issues?", "should_trigger": false},
-  {"query": "I want to look at all the SCAPI schemas available across Commerce Cloud without any specific project context. Just need to browse the full API catalog.", "should_trigger": false},
-  {"query": "I need to write the server-side script.js implementation for a custom API endpoint that returns loyalty points from a custom object.", "should_trigger": false},
-  {"query": "How do I set up the initial environment variables and dw.json for a brand new storefront next project before running pnpm dev?", "should_trigger": false}
-]