sfcc-dev-mcp 1.0.19 → 1.0.21

package/ai-instructions/skills/sfcc-scapi-custom-endpoints/SKILL.md

@@ -1,237 +0,0 @@
----
-name: sfcc-scapi-custom-endpoints
-description: Guide for developing SCAPI Custom APIs on Salesforce B2C Commerce. Use this when asked to create custom REST endpoints, api.json, schema.yaml, or script implementations.
----
-
-# Custom SCAPI Endpoint Development Skill
-
-This skill guides you through developing Custom APIs for Salesforce B2C Commerce under the SCAPI framework.
-
-## Quick Checklist
-
-```text
-[ ] Cartridge contains `cartridge/rest-apis/{api-name}/` with schema.yaml, script.js, api.json
-[ ] operationId in schema matches exported function name with `.public = true`
-[ ] Custom parameters and scopes use the `c_` prefix
-[ ] Contract avoids unsupported features (no additionalProperties, only local $ref)
-[ ] Shopper APIs include siteId; Admin APIs omit it
-[ ] Code version is activated to register endpoints
-```
-
-## URL Structure
-
-```
-https://{shortcode}.api.commercecloud.salesforce.com/custom/{api-name}/v{major}/organizations/{org-id}{path}?{params}
-```
-
-Version is derived from `info.version`: "1.2.0" → `/v1/`, "2.0.0" → `/v2/`
-
-## Cartridge Structure
-
-```
-my_cartridge/
-└── cartridge/
-    └── rest-apis/
-        └── my-api-name/          # Lowercase alphanumeric + hyphens only
-            ├── api.json          # Mapping file
-            ├── schema.yaml       # OAS 3.0 contract
-            └── script.js         # Implementation
-```
-
-## The Three Components
-
-### 1. API Contract (schema.yaml)
-
-```yaml
-openapi: 3.0.0
-info:
-  title: My Custom API
-  version: "1.0.0"
-paths:
-  /my-endpoint:
-    get:
-      operationId: getMyData        # Must match function name
-      parameters:
-        - name: siteId              # Required for Shopper APIs
-          in: query
-          required: true
-          schema:
-            type: string
-            minLength: 1
-        - name: c_my_param          # Custom params must have c_ prefix
-          in: query
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Success
-      security:
-        - ShopperToken: [c_my_scope]
-
-components:
-  securitySchemes:
-    ShopperToken:
-      type: oauth2
-      flows:
-        clientCredentials:
-          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{orgId}/oauth2/token
-          scopes:
-            c_my_scope: Description
-```
-
-### 2. Implementation (script.js)
-
-```javascript
-'use strict';
-
-var RESTResponseMgr = require('dw/system/RESTResponseMgr');
-
-exports.getMyData = function () {
-    // Query parameters
-    var myParam = request.getHttpParameterMap().get('c_my_param').getStringValue();
-    
-    // Path parameters (for paths like /items/{itemId})
-    var itemId = request.getSCAPIPathParameters().get('itemId');
-    
-    // Request body (POST/PUT/PATCH)
-    var body = JSON.parse(request.httpParameterMap.requestBodyAsString);
-    
-    // Success response
-    RESTResponseMgr.createSuccess({ data: myParam }).render();
-};
-exports.getMyData.public = true;  // Required!
-
-// Error response example
-exports.getMyDataWithError = function () {
-    RESTResponseMgr.createError(404, 'not-found', 
-        'Resource Not Found', 'The requested resource was not found.').render();
-};
-exports.getMyDataWithError.public = true;
-```
-
-### 3. Mapping (api.json)
-
-```json
-{
-  "endpoints": [
-    {
-      "endpoint": "getMyData",
-      "schema": "schema.yaml",
-      "implementation": "script"
-    }
-  ]
-}
-```
-
-**Important:** Implementation name has NO file extension. All files must be in the same folder.
-
-## Shopper vs Admin APIs
-
-| Aspect | Shopper API | Admin API |
-|--------|-------------|-----------|
-| Security Scheme | ShopperToken | AmOAuth2 |
-| siteId Parameter | Required | Must omit |
-| Max Runtime | 10 seconds | 60 seconds |
-| Max Request Body | 5 MiB | 20 MB |
-| Token Source | SLAS | Account Manager |
-
-## Security & Scopes
-
-Custom scopes must:
-- Start with `c_`
-- Only alphanumeric, period, hyphen, underscore
-- Max 25 characters
-
-```yaml
-security:
-  - ShopperToken: [c_read_loyalty]  # Global or per-operation
-```
-
-## Caching Responses
-
-Enable Page Caching for the site, then:
-
-```javascript
-// Cache for 60 seconds
-response.setExpires(Date.now() + 60000);
-
-// Personalized caching (price/promotion variants)
-response.setVaryBy('price_promotion');
-```
-
-TTL: minimum 1 second, maximum 86,400 seconds (24 hours).
-
-## Circuit Breaker
-
-Custom APIs have a circuit breaker that blocks requests when error rate exceeds 50%:
-
-1. Circuit opens after 50+ errors in 100 requests
-2. Requests return 503 for 60 seconds
-3. Circuit enters half-open state, testing next 10 requests
-4. If >5 fail, circuit reopens; otherwise closes
-
-**Prevention:** Write robust error handling; avoid uncaught exceptions.
-
-## Contract Constraints
-
-- **No `additionalProperties`** in request body schemas
-- **Only local `$ref`** - no remote/URL references
-- **All parameters** must be defined in contract
-- **System parameters** (`siteId`, `locale`) must have `type: string`, `minLength: 1`
-
-## Custom APIs vs Hooks
-
-- **Use Hooks** to modify existing SCAPI endpoints (e.g., add custom field to `/baskets` response)
-- **Use Custom APIs** for entirely new functionality (e.g., loyalty service, store locator)
-
-## Development Workflow
-
-1. Create cartridge with `rest-apis/{api-name}/` structure
-2. Define contract (schema.yaml) with endpoints and security
-3. Implement logic (script.js) with exported public functions
-4. Create mapping (api.json) binding endpoints to implementation
-5. Upload cartridge to B2C instance
-6. **Activate code version** to register endpoints
-7. Check registration status to verify
-8. Test with appropriate authentication
-
-## Troubleshooting
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| 400 Bad Request | Contract violation | Define all params in schema |
-| 401 Unauthorized | Invalid/missing token | Check token validity |
-| 403 Forbidden | Missing scope | Verify scope in token matches contract |
-| 404 Not Found | Endpoint not registered | Check status, verify structure |
-| 500 Internal Error | Script error | Check logs for CustomApiInvocationException |
-| 503 Service Unavailable | Circuit breaker open | Fix script errors, wait for reset |
-
-Review logs in Log Center with LCQL filter: `CustomApiRegistry`
-
-## HTTP Methods Supported
-
-GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
-
-**Note:** GET requests cannot commit transactions.
-
-## Limitations
-
-- Maximum 50 remote includes per request
-- Custom parameters must have `c_` prefix
-- Custom scope names max 25 characters
-- No `additionalProperties` in schemas
-- Only local `$ref` references
-
-## MCP Documentation Tools
-
-```javascript
-get_sfcc_class_info("dw.system.RESTResponseMgr")  // REST response manager
-search_sfcc_methods("getCustomer")                 // Customer retrieval methods
-get_sfcc_class_info("dw.svc.ServiceRegistry")     // External service integration
-```
-
-## Detailed References
-
-- [Authentication](references/AUTHENTICATION.md) - SLAS flows, client config, token management
-- [URL Mapping](references/URL-MAPPING.md) - Schema-to-URL translation, parameter access

package/ai-instructions/skills/sfcc-scapi-custom-endpoints/references/AUTHENTICATION.md

@@ -1,214 +0,0 @@
-# SCAPI Authentication Reference
-
-Complete reference for SLAS authentication flows, client configuration, and token management.
-
-## Client Architecture: Public vs Private
-
-The most critical architectural decision is determining your client type:
-
-### Private Clients
-
-- **Capability**: Can securely store a `client_secret` on server-side
-- **Use Cases**: Backend-for-Frontend (BFF), full-stack web apps, server-to-server integrations
-- **Security Model**: Uses `client_secret` in Basic Authorization header
-- **OAuth Grant Types**: 
-  - `client_credentials` (guest users, system operations)
-  - `authorization_code` (registered user authentication)
-
-### Public Clients
-
-- **Capability**: Cannot securely store secrets (operates in untrusted environments)
-- **Use Cases**: PWA Kit storefronts, Single-Page Applications (SPAs), native mobile apps
-- **Security Model**: Uses Proof Key for Code Exchange (PKCE)
-- **OAuth Grant Types**: 
-  - `authorization_code_pkce` (all authentication scenarios)
-
-## SLAS Client Configuration
-
-Configure clients using the SLAS Admin API or UI:
-
-```javascript
-const clientConfig = {
-    "clientId": "your-client-id",
-    "name": "My Custom API Client",
-    "isPrivateClient": true,
-    "secret": "secure-client-secret", // Only for private clients
-    "channels": ["your-site-id"],
-    "scopes": [
-        "sfcc.shopper-baskets-orders.rw",
-        "sfcc.shopper-myaccount.rw", 
-        "sfcc.shopper-products",
-        "c_read_loyalty", // Custom scopes
-        "c_write_loyalty"
-    ],
-    "redirectUri": [
-        "https://your-app.com/callback"
-    ]
-};
-```
-
-## Custom Object Scopes
-
-For accessing custom objects via SCAPI:
-
-1. **Define Custom Object** in Business Manager: `Administration > Site Development > Custom Object Types`
-2. **Add Scope** to SLAS client: `sfcc.shopper-custom-objects.{object-type-id}`
-
-```yaml
-# In schema.yaml
-security:
-  - ShopperToken: [sfcc.shopper-custom-objects.StoreReview]
-```
-
-## Private Client: Guest Token Flow
-
-```bash
-# Get Guest Token
-wget --post-data="grant_type=client_credentials" \
-     --header="Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
-     --header="Content-Type: application/x-www-form-urlencoded" \
-     -O token_response.json \
-     "https://shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/org_id/oauth2/token"
-
-# Extract Token
-TOKEN=$(cat token_response.json | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
-
-# Test API Call
-wget --header="Authorization: Bearer $TOKEN" \
-     -O result.json \
-     "https://shortcode.api.commercecloud.salesforce.com/custom/my-api/v1/organizations/org_id/endpoint?siteId=MySite"
-```
-
-## Public Client: PKCE Flow
-
-```bash
-# Generate PKCE Challenge
-VERIFIER=$(openssl rand -base64 96 | tr -d '\n' | tr '/+' '_-' | tr -d '=')
-CHALLENGE=$(echo -n $VERIFIER | openssl dgst -binary -sha256 | openssl base64 -A | tr '/' '_' | tr '+' '-' | tr -d '=')
-
-# Get Authorization Code
-wget --server-response --spider \
-     "https://shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/org_id/oauth2/authorize?redirect_uri=http://localhost:3000/callback&response_type=code&hint=guest&client_id=public-client-id&code_challenge=$CHALLENGE" \
-     2>&1 | grep -i location
-
-# Exchange Code for Token (extract usid and code from Location header)
-wget --post-data="client_id=public-client-id&channel_id=site-id&code_verifier=$VERIFIER&usid=your-usid&code=your-code&grant_type=authorization_code_pkce&redirect_uri=http://localhost:3000/callback" \
-     --header="Content-Type: application/x-www-form-urlencoded" \
-     -O token_response.json \
-     "https://shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/org_id/oauth2/token"
-```
-
-## In-Script Authorization
-
-Always validate the authenticated user can access the requested data:
-
-```javascript
-exports.getLoyaltyInfo = function () {
-    var customerId = request.getHttpParameterMap().get('c_customer_id').getStringValue();
-    
-    // CRITICAL: Verify the authenticated user can access this customer's data
-    if (request.user && request.user.profile) {
-        var authenticatedCustomerId = request.user.profile.customerNo;
-        
-        // Prevent privilege escalation
-        if (authenticatedCustomerId !== customerId) {
-            RESTResponseMgr.createError(403, "insufficient-privileges", 
-                "Access Denied", "Cannot access another customer's data").render();
-            return;
-        }
-    }
-    
-    // Continue with business logic...
-};
-```
-
-## Token Validation Helper
-
-```javascript
-function validateAndExtractUser() {
-    if (!request.user) {
-        RESTResponseMgr.createError(401, "unauthorized", 
-            "Authentication Required", "Valid token required").render();
-        return null;
-    }
-    
-    // For registered users
-    if (request.user.profile && request.user.profile.customerNo) {
-        return {
-            type: 'registered',
-            customerId: request.user.profile.customerNo,
-            email: request.user.profile.email
-        };
-    }
-    
-    // For guest users
-    return {
-        type: 'guest',
-        customerId: request.user.ID
-    };
-}
-```
-
-## Accessing Customer Context
-
-Even in headless JWT-based SCAPI, you can access the authenticated customer:
-
-```javascript
-exports.getCustomerInfo = function () {
-    var session = request.getSession();
-    var customer = session.getCustomer();
-    
-    if (!customer) {
-        RESTResponseMgr.createError(401, "unauthorized", 
-            "No Customer", "No authenticated customer found").render();
-        return;
-    }
-    
-    var customerData = {
-        isRegistered: customer.isRegistered(),
-        isAuthenticated: customer.isAuthenticated()
-    };
-    
-    if (customer.isRegistered() && customer.getProfile()) {
-        var profile = customer.getProfile();
-        customerData.customerId = profile.getCustomerNo();
-        customerData.email = profile.getEmail();
-        customerData.firstName = profile.getFirstName();
-        customerData.lastName = profile.getLastName();
-    } else {
-        customerData.customerId = customer.getID();
-        customerData.isGuest = true;
-    }
-    
-    RESTResponseMgr.createSuccess(customerData).render();
-};
-
-exports.getCustomerInfo.public = true;
-```
-
-## Common Authentication Errors
-
-| Error Code | Cause | Solution |
-|------------|-------|----------|
-| 401 Unauthorized | Invalid or expired token | Refresh token or re-authenticate |
-| 403 Forbidden | Valid token, missing scope | Check client scope configuration |
-| 400 Bad Request | Invalid PKCE parameters | Verify code_verifier/code_challenge |
-| 404 Not Found | Incorrect endpoint URL | Verify API registration and URL structure |
-
-## Security Scheme Configuration
-
-For Shopper APIs:
-1. Configure custom scope in SLAS Admin UI
-2. Obtain token via Shopper Login (SLAS)
-3. Include `siteId` in requests
-
-For Admin APIs:
-1. Configure custom scope in Account Manager
-2. Obtain token via Account Manager OAuth
-3. Omit `siteId` from requests
-
-## Custom API Status Report Access
-
-To query the Custom API status report, use an Account Manager token with scope:
-- `sfcc.custom-apis` (read-only)
-- `sfcc.custom-apis.rw` (read-write)

package/ai-instructions/skills/sfcc-scapi-custom-endpoints/references/URL-MAPPING.md

@@ -1,253 +0,0 @@
-# SCAPI URL Structure & Endpoint Mapping Reference
-
-Complete reference for understanding how OpenAPI schemas translate to SCAPI endpoint URLs.
-
-## URL Structure
-
-All custom SCAPI endpoints follow this standardized pattern:
-
-```
-https://{shortcode}.api.commercecloud.salesforce.com/custom/{api-name}/v{major-version}/organizations/{organization-id}{path}?{query-parameters}
-```
-
-**Components:**
-- `{shortcode}`: Your SFCC instance shortcode (e.g., `zzrf-001`)
-- `{api-name}`: Directory name under `cartridge/rest-apis/`
-- `v{major-version}`: From `info.version` in schema.yaml (e.g., "1.0.0" → "v1")
-- `{organization-id}`: Your SFCC organization ID (typically `f_ecom_*`)
-- `{path}`: Path defined in your OpenAPI schema
-- `{query-parameters}`: Query string parameters from schema
-
-## Version Management
-
-| Schema Version | URL Version |
-|----------------|-------------|
-| "1.0.0" | v1 |
-| "1.2.5" | v1 |
-| "2.0.0" | v2 |
-| "2.1.3" | v2 |
-| "3.0.0-beta" | v3 |
-
-**Best Practice**: Use semantic versioning; introduce breaking changes only in new major versions.
-
-## Schema-to-URL Examples
-
-### Simple Query Parameters
-
-**Schema:**
-```yaml
-# rest-apis/product-info/schema.yaml
-openapi: 3.0.0
-info:
-  title: Product Information API
-  version: "1.0.0"
-paths:
-  /products/{sku}:
-    get:
-      operationId: getProductInfo
-      parameters:
-        - name: siteId
-          in: query
-          required: true
-          schema:
-            type: string
-            minLength: 1
-        - name: sku
-          in: path
-          required: true
-          schema:
-            type: string
-```
-
-**Resulting URL:**
-```
-https://zzrf-001.api.commercecloud.salesforce.com/custom/product-info/v1/organizations/f_ecom_zzrf_001/products/682875540326M?siteId=RefArchGlobal
-```
-
-### Custom Query Parameters
-
-**Schema:**
-```yaml
-# rest-apis/pricing-api/schema.yaml
-openapi: 3.0.0
-info:
-  title: Pricing API
-  version: "1.2.0"  # → v1 URL
-paths:
-  /product-pricing/{productId}:
-    get:
-      operationId: getProductPricing
-      parameters:
-        - name: siteId
-          in: query
-          required: true
-          schema:
-            type: string
-            minLength: 1
-        - name: productId
-          in: path
-          required: true
-          schema:
-            type: string
-        - name: c_quantity
-          in: query
-          required: false
-          schema:
-            type: number
-            minimum: 1
-            default: 1
-        - name: c_include_promotions
-          in: query
-          required: false
-          schema:
-            type: boolean
-            default: false
-```
-
-**Resulting URL:**
-```
-https://shortcode.api.commercecloud.salesforce.com/custom/pricing-api/v1/organizations/org_id/product-pricing/ABC123?siteId=MySite&c_quantity=2&c_include_promotions=true
-```
-
-### Nested Resource Paths
-
-**Schema:**
-```yaml
-# rest-apis/customer-management/schema.yaml
-openapi: 3.0.0
-info:
-  title: Customer Management API
-  version: "2.0.0"  # → v2 URL
-paths:
-  /customers/{customerId}/orders/{orderId}/tracking:
-    get:
-      operationId: getOrderTracking
-      parameters:
-        - name: siteId
-          in: query
-          required: true
-          schema:
-            type: string
-        - name: customerId
-          in: path
-          required: true
-          schema:
-            type: string
-        - name: orderId
-          in: path
-          required: true
-          schema:
-            type: string
-```
-
-**Resulting URL:**
-```
-https://shortcode.api.commercecloud.salesforce.com/custom/customer-management/v2/organizations/org_id/customers/12345/orders/ORD-001234/tracking?siteId=SiteGenesis
-```
-
-## Parameter Access in Scripts
-
-### Path Parameters
-
-Use `request.getSCAPIPathParameters()` for `in: path` parameters:
-
-```javascript
-var productId = request.getSCAPIPathParameters().get('productId');
-var customerId = request.getSCAPIPathParameters().get('customerId');
-var orderId = request.getSCAPIPathParameters().get('orderId');
-```
-
-### Query Parameters
-
-Use `request.getHttpParameterMap()` for `in: query` parameters:
-
-```javascript
-var siteId = request.getHttpParameterMap().get('siteId').getStringValue();
-var quantity = request.getHttpParameterMap().get('c_quantity').getIntValue() || 1;
-var includePromos = request.getHttpParameterMap().get('c_include_promotions').getBooleanValue();
-```
-
-### Request Body (POST/PUT/PATCH)
-
-```javascript
-var requestBody = JSON.parse(request.httpParameterMap.requestBodyAsString);
-```
-
-## Complete Script Example
-
-```javascript
-'use strict';
-
-var RESTResponseMgr = require('dw/system/RESTResponseMgr');
-
-exports.getProductPricing = function () {
-    // Path parameters
-    var productId = request.getSCAPIPathParameters().get('productId');
-    
-    // Query parameters
-    var siteId = request.getHttpParameterMap().get('siteId').getStringValue();
-    var quantity = request.getHttpParameterMap().get('c_quantity').getIntValue() || 1;
-    var includePromos = request.getHttpParameterMap().get('c_include_promotions').getBooleanValue();
-    
-    // Validation
-    if (!productId) {
-        RESTResponseMgr.createError(400, "missing-product-id", 
-            "Missing Product ID", "Product ID is required").render();
-        return;
-    }
-    
-    // Business logic...
-    var pricingData = {
-        productId: productId,
-        basePrice: 29.99,
-        salePrice: 24.99,
-        quantity: quantity
-    };
-    
-    RESTResponseMgr.createSuccess(pricingData).render();
-};
-
-exports.getProductPricing.public = true;
-```
-
-## Testing URLs
-
-```bash
-curl -X GET \
-  'https://shortcode.api.commercecloud.salesforce.com/custom/pricing-api/v1/organizations/org_id/product-pricing/ABC123?siteId=MySite&c_quantity=2' \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json'
-```
-
-## Common Issues
-
-| Issue | Symptom | Solution |
-|-------|---------|----------|
-| 404 Not Found | Endpoint not accessible | Check cartridge registration, API directory name, schema syntax |
-| Version mismatch | Wrong version in URL | Verify `info.version` in schema.yaml |
-| Parameter not found | Script can't access params | Ensure names match schema, use correct access method |
-| Invalid path structure | URL doesn't match | Verify path definition in schema |
-
-## Client Documentation Template
-
-```markdown
-## Get Product Pricing
-
-Retrieves pricing information for a product.
-
-### Endpoint
-`GET /custom/pricing-api/v1/organizations/{organizationId}/product-pricing/{productId}`
-
-### Full URL
-```
-https://shortcode.api.commercecloud.salesforce.com/custom/pricing-api/v1/organizations/f_ecom_org/product-pricing/ABC123?siteId=RefArchGlobal&c_quantity=2
-```
-
-### Parameters
-- `productId` (path, required): Product SKU or ID
-- `siteId` (query, required): Site identifier
-- `c_quantity` (query, optional): Quantity for tiered pricing (default: 1)
-
-### Authentication
-Requires SLAS Shopper Token with scope: `c_read_pricing`
-```