@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/b2c/b2c-controllers/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: b2c-controllers
+description: Create storefront controllers using SFRA or classic patterns with server.get/post, middleware chains, and res.render/json. Use this skill whenever the user needs to build a page route, handle form submissions, create AJAX endpoints, extend or override existing controllers, or add middleware to a request pipeline. Also use when debugging route registration or response rendering -- even if they just say 'new page endpoint' or 'handle a POST request'.
+---
+
+# Controllers Skill
+
+This skill guides you through creating storefront controllers for Salesforce B2C Commerce. Controllers handle HTTP requests and render responses for the storefront.
+
+## 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`
+
+## Two Controller Patterns
+
+B2C Commerce supports two controller patterns:
+
+| Pattern | When to Use | Module Style |
+|---------|-------------|--------------|
+| **SFRA** | Storefront Reference Architecture sites | `server` module with middleware |
+| **Classic** | Non-SFRA sites, simple APIs | Direct exports with `.public = true` |
+
+**SFRA is recommended** for most storefront development. Classic controllers are useful for simple endpoints or non-SFRA projects.
+
+## 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}
+```
+
+**Naming:** Controller filename becomes the URL prefix. `Home.js` handles `Home-*` requests.
+
+## SFRA Controllers (Recommended)
+
+SFRA controllers use the `server` module for routing and middleware:
+
+```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;
+    // Process subscription...
+    res.json({ success: true });
+    next();
+});
+
+module.exports = server.exports();
+```
+
+### Request Object (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 Object (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
+```
+
+### Middleware
+
+Apply middleware to routes for cross-cutting concerns:
+
+```javascript
+var server = require('server');
+var cache = require('*/cartridge/scripts/middleware/cache');
+var consentTracking = require('*/cartridge/scripts/middleware/consentTracking');
+var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
+
+// Apply caching
+server.get('Show', cache.applyDefaultCache, function (req, res, next) {
+    res.render('home/homepage');
+    next();
+});
+
+// Require HTTPS
+server.post('Login', server.middleware.https, function (req, res, next) {
+    // Handle login...
+    next();
+});
+
+// CSRF protection for forms
+server.post('Submit', csrfProtection.validateAjaxRequest, function (req, res, next) {
+    // Handle form submission...
+    next();
+});
+```
+
+### Common Middleware
+
+| Middleware | Purpose |
+|------------|---------|
+| `server.middleware.https` | Require HTTPS connection |
+| `cache.applyDefaultCache` | Apply default page caching |
+| `csrfProtection.validateAjaxRequest` | Validate CSRF token |
+| `consentTracking.consent` | Check tracking consent |
+| `userLoggedIn.validateLoggedIn` | Require authenticated user |
+
+### Route Events
+
+Execute code at specific points in the request lifecycle:
+
+```javascript
+server.post('Submit', function (req, res, next) {
+    var form = req.form;
+    res.setViewData({ email: form.email });
+    next();
+}, function (req, res, next) {
+    // Additional middleware
+    next();
+});
+
+// Execute after all middleware, before render
+this.on('route:BeforeComplete', function (req, res) {
+    var viewData = res.getViewData();
+    // Modify view data if needed
+});
+```
+
+### Extending Controllers
+
+Extend existing controllers to add or modify functionality:
+
+```javascript
+'use strict';
+
+var server = require('server');
+var page = module.superModule;  // Get parent controller
+
+server.extend(page);
+
+// Add new route
+server.get('NewRoute', function (req, res, next) {
+    res.render('newtemplate');
+    next();
+});
+
+// Override existing route
+server.replace('Show', function (req, res, next) {
+    // Custom implementation
+    res.render('custom/homepage');
+    next();
+});
+
+// Prepend to existing route
+server.prepend('Show', function (req, res, next) {
+    // Runs before original handler
+    next();
+});
+
+// Append to existing route
+server.append('Show', function (req, res, next) {
+    // Runs after original handler
+    var viewData = res.getViewData();
+    viewData.customData = 'value';
+    res.setViewData(viewData);
+    next();
+});
+
+module.exports = server.exports();
+```
+
+## Classic Controllers (Non-SFRA)
+
+For non-SFRA sites or simple endpoints, use direct exports:
+
+```javascript
+'use strict';
+
+var ISML = require('dw/template/ISML');
+
+exports.Show = function () {
+    var params = request.httpParameterMap;
+    var productId = params.pid.stringValue;
+
+    ISML.renderTemplate('product/detail', {
+        productId: productId
+    });
+};
+exports.Show.public = true;  // Required: marks function as accessible
+
+exports.GetData = function () {
+    var result = { status: 'ok', data: [] };
+
+    response.setContentType('application/json');
+    response.writer.print(JSON.stringify(result));
+};
+exports.GetData.public = true;
+```
+
+**Key difference:** Classic controllers use `exports.FunctionName.public = true` instead of the `server` module.
+
+## Module Imports
+
+Import B2C Commerce APIs using `require()`:
+
+```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');
+var Resource = require('dw/web/Resource');
+
+// Cartridge modules (use */ for cartridge path resolution)
+var collections = require('*/cartridge/scripts/util/collections');
+var productHelper = require('*/cartridge/scripts/helpers/productHelpers');
+```
+
+**Best Practice:** Only require modules when needed, not all at the top of the file.
+
+## Error Handling
+
+Wrap operations in try-catch blocks:
+
+```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();
+});
+```
+
+## Generating URLs
+
+Use URLUtils to generate locale-aware URLs:
+
+```javascript
+var URLUtils = require('dw/web/URLUtils');
+
+// Controller URL
+var productUrl = URLUtils.url('Product-Show', 'pid', 'ABC123');
+// Result: /on/demandware.store/Sites-RefArch-Site/en_US/Product-Show?pid=ABC123
+
+// HTTPS URL
+var loginUrl = URLUtils.https('Login-Show');
+
+// Static resource URL
+var imageUrl = URLUtils.staticURL('/images/logo.png');
+```
+
+## Best Practices
+
+1. **Always call `next()`** in SFRA middleware chain
+2. **Use ViewModels** to prepare data for templates
+3. **Keep controllers thin** - move business logic to scripts/helpers
+4. **Use hooks** for functionality that works for both storefront and OCAPI
+5. **Handle errors gracefully** - never expose stack traces
+6. **Use `*/cartridge/...`** for portable module paths
+
+## Detailed Reference
+
+For comprehensive patterns and examples:
+- [SFRA Patterns](references/SFRA-PATTERNS.md) - Full SFRA patterns with middleware
+- [Classic Patterns](references/CLASSIC-PATTERNS.md) - Non-SFRA controller patterns

package/content/guidance/b2c/b2c-controllers/references/CLASSIC-PATTERNS.md

@@ -0,0 +1,335 @@
+# Classic Controller Patterns
+
+Patterns for non-SFRA controllers using direct exports with `.public = true`.
+
+## When to Use Classic Controllers
+
+- Non-SFRA (pipelines-based) storefronts
+- Simple REST-like endpoints
+- Quick prototypes
+- Legacy integrations
+
+## Basic Structure
+
+```javascript
+'use strict';
+
+var ISML = require('dw/template/ISML');
+
+exports.Show = function () {
+    ISML.renderTemplate('home/homepage', {
+        pageTitle: 'Welcome'
+    });
+};
+exports.Show.public = true;  // Required for URL access
+```
+
+**Key:** Every exported function must have `.public = true` to be accessible via URL.
+
+## Request Handling
+
+```javascript
+exports.GetProduct = function () {
+    // Query parameters
+    var params = request.httpParameterMap;
+    var productId = params.pid.stringValue;
+    var quantity = params.qty.intValue || 1;
+
+    // Check if parameter exists
+    if (params.isParameterSubmitted('pid')) {
+        // Parameter was provided
+    }
+
+    // Form data (POST)
+    var email = params.email.stringValue;
+
+    // HTTP method
+    var method = request.httpMethod;  // 'GET', 'POST', etc.
+
+    // Headers
+    var contentType = request.httpHeaders.get('content-type');
+
+    ISML.renderTemplate('product/detail', {
+        productId: productId,
+        quantity: quantity
+    });
+};
+exports.GetProduct.public = true;
+```
+
+## Response Types
+
+### HTML Response (ISML)
+
+```javascript
+var ISML = require('dw/template/ISML');
+
+exports.ShowPage = function () {
+    ISML.renderTemplate('path/to/template', {
+        data: 'value'
+    });
+};
+exports.ShowPage.public = true;
+```
+
+### JSON Response
+
+```javascript
+exports.GetData = function () {
+    var result = {
+        success: true,
+        items: [],
+        count: 0
+    };
+
+    response.setContentType('application/json');
+    response.writer.print(JSON.stringify(result));
+};
+exports.GetData.public = true;
+```
+
+### XML Response
+
+```javascript
+exports.GetXML = function () {
+    var xml = '<?xml version="1.0"?><data><item>value</item></data>';
+
+    response.setContentType('application/xml');
+    response.writer.print(xml);
+};
+exports.GetXML.public = true;
+```
+
+### Redirect
+
+```javascript
+var URLUtils = require('dw/web/URLUtils');
+
+exports.Redirect = function () {
+    response.redirect(URLUtils.url('Home-Show'));
+};
+exports.Redirect.public = true;
+```
+
+### Status Codes
+
+```javascript
+exports.NotFound = function () {
+    response.setStatus(404);
+    ISML.renderTemplate('error/notfound');
+};
+exports.NotFound.public = true;
+```
+
+## Error Handling
+
+```javascript
+var Logger = require('dw/system/Logger');
+
+exports.ProcessOrder = function () {
+    try {
+        var params = request.httpParameterMap;
+        var orderId = params.orderID.stringValue;
+
+        if (!orderId) {
+            response.setStatus(400);
+            response.setContentType('application/json');
+            response.writer.print(JSON.stringify({
+                error: true,
+                message: 'Order ID required'
+            }));
+            return;
+        }
+
+        // Process order...
+
+        response.setContentType('application/json');
+        response.writer.print(JSON.stringify({ success: true }));
+
+    } catch (e) {
+        Logger.error('Order processing error: ' + e.message);
+        response.setStatus(500);
+        response.setContentType('application/json');
+        response.writer.print(JSON.stringify({
+            error: true,
+            message: 'Internal error'
+        }));
+    }
+};
+exports.ProcessOrder.public = true;
+```
+
+## Database Operations
+
+```javascript
+var Transaction = require('dw/system/Transaction');
+var ProductMgr = require('dw/catalog/ProductMgr');
+
+exports.UpdateProduct = function () {
+    var params = request.httpParameterMap;
+    var pid = params.pid.stringValue;
+    var product = ProductMgr.getProduct(pid);
+
+    if (!product) {
+        response.setStatus(404);
+        return;
+    }
+
+    Transaction.wrap(function () {
+        product.custom.lastViewed = new Date();
+    });
+
+    response.setContentType('application/json');
+    response.writer.print(JSON.stringify({ updated: true }));
+};
+exports.UpdateProduct.public = true;
+```
+
+## HTTPS Enforcement
+
+```javascript
+exports.SecurePage = function () {
+    if (!request.isHttpSecure()) {
+        var URLUtils = require('dw/web/URLUtils');
+        response.redirect(URLUtils.https('Controller-SecurePage'));
+        return;
+    }
+
+    ISML.renderTemplate('secure/page');
+};
+exports.SecurePage.public = true;
+```
+
+## Authentication Check
+
+```javascript
+var CustomerMgr = require('dw/customer/CustomerMgr');
+
+exports.AccountPage = function () {
+    var customer = session.customer;
+
+    if (!customer.authenticated) {
+        var URLUtils = require('dw/web/URLUtils');
+        response.redirect(URLUtils.url('Login-Show'));
+        return;
+    }
+
+    ISML.renderTemplate('account/dashboard', {
+        customer: customer
+    });
+};
+exports.AccountPage.public = true;
+```
+
+## Complete Example
+
+```javascript
+'use strict';
+
+var ISML = require('dw/template/ISML');
+var Transaction = require('dw/system/Transaction');
+var ProductMgr = require('dw/catalog/ProductMgr');
+var BasketMgr = require('dw/order/BasketMgr');
+var URLUtils = require('dw/web/URLUtils');
+var Logger = require('dw/system/Logger');
+
+/**
+ * Display product detail page
+ */
+exports.Show = function () {
+    var params = request.httpParameterMap;
+    var pid = params.pid.stringValue;
+
+    var product = ProductMgr.getProduct(pid);
+
+    if (!product || !product.online) {
+        response.setStatus(404);
+        ISML.renderTemplate('error/notfound');
+        return;
+    }
+
+    ISML.renderTemplate('product/detail', {
+        product: product,
+        quantity: params.qty.intValue || 1
+    });
+};
+exports.Show.public = true;
+
+/**
+ * Add product to cart (AJAX)
+ */
+exports.AddToCart = function () {
+    var params = request.httpParameterMap;
+    var pid = params.pid.stringValue;
+    var qty = params.qty.intValue || 1;
+
+    try {
+        var product = ProductMgr.getProduct(pid);
+        if (!product) {
+            sendJSON({ success: false, error: 'Product not found' }, 404);
+            return;
+        }
+
+        var basket = BasketMgr.getCurrentOrNewBasket();
+
+        Transaction.wrap(function () {
+            var pli = basket.createProductLineItem(pid, basket.defaultShipment);
+            pli.setQuantityValue(qty);
+        });
+
+        sendJSON({
+            success: true,
+            cartCount: basket.productQuantityTotal
+        });
+
+    } catch (e) {
+        Logger.error('Add to cart error: ' + e.message);
+        sendJSON({ success: false, error: 'Unable to add to cart' }, 500);
+    }
+};
+exports.AddToCart.public = true;
+
+/**
+ * Get product availability (AJAX)
+ */
+exports.GetAvailability = function () {
+    var params = request.httpParameterMap;
+    var pid = params.pid.stringValue;
+
+    var product = ProductMgr.getProduct(pid);
+    if (!product) {
+        sendJSON({ available: false }, 404);
+        return;
+    }
+
+    var availability = product.availabilityModel;
+    sendJSON({
+        available: availability.inStock,
+        quantity: availability.inventoryRecord ? availability.inventoryRecord.ATS.value : 0
+    });
+};
+exports.GetAvailability.public = true;
+
+/**
+ * Helper: Send JSON response
+ */
+function sendJSON(data, status) {
+    if (status) {
+        response.setStatus(status);
+    }
+    response.setContentType('application/json');
+    response.writer.print(JSON.stringify(data));
+}
+```
+
+## Comparison: Classic vs SFRA
+
+| Aspect | Classic | SFRA |
+|--------|---------|------|
+| Public access | `exports.fn.public = true` | Automatic via `server` |
+| Request data | `request.httpParameterMap` | `req.querystring`, `req.form` |
+| Render HTML | `ISML.renderTemplate()` | `res.render()` |
+| Return JSON | `response.writer.print()` | `res.json()` |
+| Middleware | Manual checks | Built-in middleware chain |
+| Controller extension | Not supported | `module.superModule` |
+| Route events | Not available | `this.on('route:BeforeComplete')` |