sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/skills/sfcc-sfra-controllers/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: sfcc-sfra-controllers
+description: Guide for developing SFRA controllers in Salesforce B2C Commerce. Use this when asked to create controllers, extend base functionality, implement middleware chains, handle routing, or customize storefront behavior.
+---
+
+# SFRA Controllers Skill
+
+This skill guides you through creating storefront controllers for Salesforce B2C Commerce using the Storefront Reference Architecture (SFRA).
+
+## Overview
+
+Controllers are JavaScript modules that handle storefront requests. A controller URL has this structure:
+
+```
+https://{domain}/on/demandware.store/Sites-{SiteName}-Site/{locale}/{ControllerName}-{FunctionName}
+```
+
+**Example:** `https://example.com/on/demandware.store/Sites-RefArch-Site/en_US/Home-Show`
+
+## MVC Pattern
+
+SFRA uses Model-View-Controller pattern:
+
+- **Controller** (`/controllers`): Handles requests, calls models, determines view
+- **Model** (`/models`): Business logic, returns JSON objects
+- **View** (`/templates`): ISML templates, renders pdict data only
+
+**Cartridge Path**: Custom cartridges must precede `app_storefront_base` to override functionality. Never edit the base cartridge directly.
+
+## File Location
+
+Controllers reside in the cartridge's `controllers` directory:
+
+```
+/my-cartridge
+    /cartridge
+        /controllers
+            Home.js           # URL: Home-{function}
+            Product.js        # URL: Product-{function}
+            Cart.js           # URL: Cart-{function}
+```
+
+## Basic Controller Pattern
+
+```javascript
+'use strict';
+
+var server = require('server');
+
+// Handle GET request
+server.get('Show', function (req, res, next) {
+    res.render('home/homepage');
+    next();
+});
+
+// Handle POST request
+server.post('Subscribe', function (req, res, next) {
+    var email = req.form.email;
+    res.json({ success: true });
+    next();
+});
+
+module.exports = server.exports();
+```
+
+## Request & Response Objects
+
+### Request (req)
+
+```javascript
+req.querystring          // Query parameters: ?q=shoes -> req.querystring.q
+req.form                 // Form POST data: req.form.email
+req.httpMethod           // HTTP method: 'GET', 'POST', etc.
+req.httpHeaders          // Request headers
+req.currentCustomer      // Current customer object
+req.locale               // Current locale
+req.session              // Session object
+```
+
+### Response (res)
+
+```javascript
+res.render('template', model)   // Render ISML template with data
+res.json(object)                // Return JSON response
+res.redirect(url)               // Redirect to URL
+res.setViewData(data)           // Add data to view model
+res.getViewData()               // Get current view model
+res.setStatusCode(code)         // Set HTTP status code
+res.cacheExpiration(hours)      // Set cache duration
+```
+
+## Middleware Chain
+
+Each route is a series of functions with `(req, res, next)`:
+
+```javascript
+server.get('Show', 
+    middleware1,
+    middleware2,
+    function (req, res, next) {
+        // Main handler
+        next();
+    }
+);
+```
+
+**Critical**: Always call `next()` to pass control, unless terminating the request.
+
+### Common Built-in Middleware
+
+| Middleware | Purpose |
+|------------|---------|
+| `server.middleware.https` | Require HTTPS connection |
+| `server.middleware.include` | Mark as remote include only |
+| `cache.applyDefaultCache` | Apply 24-hour page caching |
+| `csrfProtection.generateToken` | Generate CSRF token |
+| `csrfProtection.validateRequest` | Validate CSRF for POST |
+| `userLoggedIn.validateLoggedIn` | Require authenticated user |
+| `consentTracking.consent` | Check tracking consent |
+
+## Controller Extension
+
+Customize without modifying base code. Always import base first:
+
+```javascript
+'use strict';
+var server = require('server');
+var page = module.superModule; // Get base controller
+server.extend(page);
+```
+
+### Extension Methods
+
+| Method | Use Case |
+|--------|----------|
+| `server.append()` | Add/modify data after base logic (most common) |
+| `server.prepend()` | Run validation before base logic |
+| `server.replace()` | Completely replace route behavior |
+
+### Append Example (Most Common)
+
+```javascript
+server.append('Show', function (req, res, next) {
+    var viewData = res.getViewData();
+    viewData.customData = 'My custom value';
+    res.setViewData(viewData);
+    next();
+});
+
+module.exports = server.exports();
+```
+
+### Replace Example (State-Changing Actions)
+
+```javascript
+// Use replace for payment, inventory updates, etc.
+server.replace('Submit', function (req, res, next) {
+    // Custom implementation
+    res.json({ success: true });
+    next();
+});
+```
+
+**Critical**: Never use `append` for state-changing routes (payments, inventory). Use `replace` to prevent duplicate transactions.
+
+## CSRF Protection
+
+```javascript
+var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
+
+// Display form - generates token automatically
+server.get('ShowForm', csrfProtection.generateToken, function (req, res, next) {
+    res.render('myForm', { pageTitle: 'Contact' });
+    // pdict.csrf.tokenName and pdict.csrf.token auto-available
+    next();
+});
+
+// Process form - validates token
+server.post('Submit', csrfProtection.validateRequest, function (req, res, next) {
+    // Token validated, safe to process
+    next();
+});
+```
+
+**Important**: Middleware automatically adds CSRF to pdict. Never manually add tokens to viewData.
+
+Template usage:
+```html
+<input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>
+```
+
+## Error Handling
+
+```javascript
+server.get('Show', function (req, res, next) {
+    try {
+        var product = ProductMgr.getProduct(req.querystring.pid);
+        
+        if (!product) {
+            res.setStatusCode(404);
+            res.render('error/notfound');
+            return next();
+        }
+        
+        res.render('product/detail', { product: product });
+    } catch (e) {
+        Logger.error('Product error: ' + e.message);
+        res.setStatusCode(500);
+        res.render('error/general');
+    }
+    next();
+});
+```
+
+## Module Imports
+
+```javascript
+// B2C Commerce APIs
+var ProductMgr = require('dw/catalog/ProductMgr');
+var Transaction = require('dw/system/Transaction');
+var Logger = require('dw/system/Logger');
+var URLUtils = require('dw/web/URLUtils');
+
+// Cartridge modules (use */ for path resolution)
+var collections = require('*/cartridge/scripts/util/collections');
+var productHelper = require('*/cartridge/scripts/helpers/productHelpers');
+```
+
+**Best Practice**: Require modules inside route functions, not at file top.
+
+## URL Generation
+
+```javascript
+var URLUtils = require('dw/web/URLUtils');
+
+// Controller URL
+var productUrl = URLUtils.url('Product-Show', 'pid', 'ABC123');
+
+// HTTPS URL
+var loginUrl = URLUtils.https('Login-Show');
+
+// Static resource URL
+var imageUrl = URLUtils.staticURL('/images/logo.png');
+```
+
+## Route Events
+
+Execute code at specific points in request lifecycle:
+
+```javascript
+server.get('Show', function (req, res, next) {
+    res.setViewData({ email: req.form.email });
+    next();
+});
+
+// Execute after all middleware, before render
+this.on('route:BeforeComplete', function (req, res) {
+    var viewData = res.getViewData();
+    // Modify view data if needed
+});
+```
+
+## JSON API Endpoints
+
+```javascript
+server.get('GetCart', function (req, res, next) {
+    var BasketMgr = require('dw/order/BasketMgr');
+    var CartModel = require('*/cartridge/models/cart');
+    
+    var basket = BasketMgr.getCurrentBasket();
+    var cart = new CartModel(basket);
+    
+    res.json(cart);
+    next();
+});
+```
+
+## Complete Controller Example
+
+```javascript
+'use strict';
+
+var server = require('server');
+var cache = require('*/cartridge/scripts/middleware/cache');
+var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
+var userLoggedIn = require('*/cartridge/scripts/middleware/userLoggedIn');
+
+// Public page with caching
+server.get('Show',
+    cache.applyDefaultCache,
+    function (req, res, next) {
+        var ProductMgr = require('dw/catalog/ProductMgr');
+        var product = ProductMgr.getProduct(req.querystring.pid);
+        
+        res.render('product/detail', { product: product });
+        next();
+    }
+);
+
+// Protected form display
+server.get('EditProfile',
+    server.middleware.https,
+    userLoggedIn.validateLoggedIn,
+    csrfProtection.generateToken,
+    function (req, res, next) {
+        res.render('account/editProfile');
+        next();
+    }
+);
+
+// Protected form submission
+server.post('SaveProfile',
+    server.middleware.https,
+    userLoggedIn.validateLoggedIn,
+    csrfProtection.validateRequest,
+    function (req, res, next) {
+        // Process form...
+        res.json({ success: true });
+        next();
+    }
+);
+
+module.exports = server.exports();
+```
+
+## Best Practices
+
+1. **Always call `next()`** in middleware chain
+2. **Use ViewModels** to prepare data for templates
+3. **Keep controllers thin** - move logic to scripts/helpers
+4. **Use hooks** for functionality that works for storefront and OCAPI
+5. **Handle errors gracefully** - never expose stack traces
+6. **Use `*/cartridge/...`** for portable module paths
+7. **Lazy load modules** - require inside functions, not at file top
+8. **Use page caching** via middleware or `res.cacheExpiration()`
+
+## Related Skills
+
+- **[sfcc-localization](../sfcc-localization/SKILL.md)** - Essential for localizing controller responses. Use `Resource.msg()` for all user-facing messages, error strings, and JSON responses. Never hardcode text in controllers.
+- **[sfcc-logging](../sfcc-logging/SKILL.md)** - Comprehensive logging patterns including categories, custom log files, and log level checks for debugging controllers.
+
+## Detailed References
+
+For comprehensive patterns and examples:
+- [Middleware Reference](references/MIDDLEWARE-REFERENCE.md) - Full middleware documentation
+- [Remote Includes](references/REMOTE-INCLUDES.md) - Remote include patterns
+- [Standard SFRA Controllers](references/STANDARD-SFRA-CONTROLLERS.md) - Complete route reference

package/ai-instructions/skills/sfcc-sfra-controllers/references/MIDDLEWARE-REFERENCE.md

@@ -0,0 +1,257 @@
+# SFRA Middleware Reference
+
+Comprehensive reference for built-in SFRA middlewares and custom middleware patterns.
+
+## Cache Middlewares (`cache.js`)
+
+These middlewares set appropriate cache headers for different types of content.
+
+### `applyDefaultCache`
+Sets standard 24-hour cache for general content.
+```javascript
+var cache = require('*/cartridge/scripts/middleware/cache');
+
+server.get('Show', cache.applyDefaultCache, function (req, res, next) {
+    // Your controller logic here
+    // Page will be cached for 24 hours
+    next();
+});
+```
+
+### `applyPromotionSensitiveCache`
+Sets 24-hour cache with personalization flag for promotion-sensitive pages.
+```javascript
+server.get('ProductList', cache.applyPromotionSensitiveCache, function (req, res, next) {
+    // Page cached for 24 hours but marked as personalized
+    // Useful for pages that show different content based on promotions
+    next();
+});
+```
+
+### `applyShortPromotionSensitiveCache`
+Sets 1-hour cache with personalization for highly dynamic promotional content.
+```javascript
+server.get('FlashSale', cache.applyShortPromotionSensitiveCache, function (req, res, next) {
+    // Short cache for time-sensitive promotional content
+    next();
+});
+```
+
+### `applyInventorySensitiveCache`
+Sets 30-minute cache for inventory-dependent pages.
+```javascript
+server.get('ProductAvailability', cache.applyInventorySensitiveCache, function (req, res, next) {
+    // Short cache for pages that depend on inventory levels
+    next();
+});
+```
+
+## CSRF Protection (`csrf.js`)
+
+Critical security middlewares for preventing Cross-Site Request Forgery attacks.
+
+### `generateToken`
+Generates and adds CSRF token to view data. Required for forms that will be submitted via POST.
+```javascript
+var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
+
+server.get('ShowForm', csrfProtection.generateToken, function (req, res, next) {
+    res.render('myForm', {
+        // csrf token automatically available in pdict.csrf
+    });
+    next();
+});
+```
+
+### `validateRequest`
+Validates CSRF token for standard form submissions. Logs out user and redirects on failure.
+```javascript
+server.post('SubmitForm', csrfProtection.validateRequest, function (req, res, next) {
+    // Process form submission - token has been validated
+    next();
+});
+```
+
+### `validateAjaxRequest`
+Validates CSRF token for AJAX requests. Redirects to AJAX-specific error page on failure.
+```javascript
+server.post('AjaxSubmit', csrfProtection.validateAjaxRequest, function (req, res, next) {
+    // Process AJAX form submission
+    res.json({ success: true });
+    next();
+});
+```
+
+### CSRF Middleware Automation
+
+**IMPORTANT**: The middleware automatically adds CSRF to pdict. Never manually add CSRF tokens.
+
+```javascript
+// ❌ WRONG - Don't do this!
+server.get('ShowForm', csrfProtection.generateToken, function(req, res, next) {
+    res.render('myForm', {
+        csrf: res.getViewData().csrf,    // ❌ Redundant
+    });
+});
+
+// ✅ CORRECT - Middleware handles it
+server.get('ShowForm', csrfProtection.generateToken, function(req, res, next) {
+    res.render('myForm', {
+        pageTitle: 'My Form'
+        // pdict.csrf.tokenName and pdict.csrf.token are automatically available
+    });
+    next();
+});
+```
+
+## User Authentication (`userLoggedIn.js`)
+
+Middlewares for protecting routes that require authentication.
+
+### `validateLoggedIn`
+Ensures user is logged in, redirects to login page if not. Preserves query parameters.
+```javascript
+var userLoggedIn = require('*/cartridge/scripts/middleware/userLoggedIn');
+
+server.get('AccountDashboard', userLoggedIn.validateLoggedIn, function (req, res, next) {
+    // User is guaranteed to be logged in here
+    next();
+});
+```
+
+### `validateLoggedInAjax`
+AJAX-friendly version that returns JSON response instead of redirecting.
+```javascript
+server.post('UpdateProfile', userLoggedIn.validateLoggedInAjax, function (req, res, next) {
+    var viewData = res.getViewData();
+    if (viewData.loggedin) {
+        res.json({ success: true });
+    } else {
+        res.json({ 
+            success: false, 
+            redirectUrl: viewData.redirectUrl 
+        });
+    }
+    next();
+});
+```
+
+## Consent Tracking (`consentTracking.js`)
+
+Handles privacy consent management and tracking permissions.
+
+### `consent`
+Manages tracking consent state and generates CSRF tokens when needed.
+```javascript
+var consentTracking = require('*/cartridge/scripts/middleware/consentTracking');
+
+server.get('Home', consentTracking.consent, function (req, res, next) {
+    // Consent status available in pdict.tracking_consent
+    // Can be: true (consented), false (declined), null (not set)
+    next();
+});
+```
+
+## Page Metadata (`pageMetaData.js`)
+
+Processes and computes page metadata for SEO.
+
+### `computedPageMetaData`
+Consolidates page metadata from various sources into a single object.
+```javascript
+var pageMetaData = require('*/cartridge/scripts/middleware/pageMetaData');
+
+server.get('ProductDetail', pageMetaData.computedPageMetaData, function (req, res, next) {
+    // Computed metadata available in pdict.CurrentPageMetaData
+    next();
+});
+```
+
+## Middleware Chaining Examples
+
+### Complete Product Detail Page
+```javascript
+var server = require('server');
+var cache = require('*/cartridge/scripts/middleware/cache');
+var consentTracking = require('*/cartridge/scripts/middleware/consentTracking');
+var pageMetaData = require('*/cartridge/scripts/middleware/pageMetaData');
+
+server.get('Show', 
+    cache.applyPromotionSensitiveCache,
+    consentTracking.consent,
+    pageMetaData.computedPageMetaData,
+    function (req, res, next) {
+        var pid = req.querystring.pid;
+        // Product logic here...
+        next();
+    }
+);
+```
+
+### Secure Form Submission
+```javascript
+var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
+var userLoggedIn = require('*/cartridge/scripts/middleware/userLoggedIn');
+
+// Show form
+server.get('ShowContactForm', 
+    userLoggedIn.validateLoggedIn,
+    csrfProtection.generateToken,
+    function (req, res, next) {
+        res.render('contactForm');
+        next();
+    }
+);
+
+// Process form
+server.post('SubmitContactForm',
+    userLoggedIn.validateLoggedIn,
+    csrfProtection.validateRequest,
+    function (req, res, next) {
+        // User authenticated and CSRF validated
+        next();
+    }
+);
+```
+
+## Custom Middleware Best Practices
+
+When creating custom middleware:
+
+1. **Follow the Pattern**: Always accept `(req, res, next)` parameters
+2. **Call next()**: Always call `next()` unless terminating the request
+3. **Handle Errors**: Use try-catch and pass errors to `next(error)`
+4. **Set View Data**: Use `res.setViewData()` to pass data to templates
+5. **Check Existing Data**: Use `res.getViewData()` to avoid overwriting existing data
+
+```javascript
+// Custom middleware example
+function customMiddleware(req, res, next) {
+    try {
+        var viewData = res.getViewData() || {};
+        viewData.customProperty = 'customValue';
+        res.setViewData(viewData);
+        next();
+    } catch (error) {
+        next(error);
+    }
+}
+```
+
+## Common Middleware Table
+
+| Middleware | Purpose |
+|------------|---------|
+| `server.middleware.https` | Require HTTPS connection |
+| `server.middleware.include` | Mark route as remote include only |
+| `cache.applyDefaultCache` | Apply default page caching (24h) |
+| `cache.applyPromotionSensitiveCache` | Promotion-aware caching (24h) |
+| `cache.applyShortPromotionSensitiveCache` | Short promotion cache (1h) |
+| `cache.applyInventorySensitiveCache` | Inventory-aware caching (30m) |
+| `csrfProtection.generateToken` | Generate CSRF token for forms |
+| `csrfProtection.validateRequest` | Validate CSRF for POST |
+| `csrfProtection.validateAjaxRequest` | Validate CSRF for AJAX |
+| `consentTracking.consent` | Check tracking consent |
+| `userLoggedIn.validateLoggedIn` | Require authenticated user |
+| `userLoggedIn.validateLoggedInAjax` | Require auth (AJAX response) |
+| `pageMetaData.computedPageMetaData` | Compute SEO metadata |