sfcc-dev-mcp 1.0.15 → 1.0.19

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

@@ -0,0 +1,237 @@
+---
+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

@@ -0,0 +1,214 @@
+# 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

@@ -0,0 +1,253 @@
+# 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`
+```