sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/skills/sfcc-sfra-models/references/MODEL-STRUCTURE.md

@@ -0,0 +1,234 @@
+# SFRA Model Project Structure Reference
+
+Complete reference for the default SFRA model directory structure in `app_storefront_base`.
+
+## Directory Organization
+
+```
+cartridge/models/
+├── account.js                    # Customer account model
+├── address.js                    # Address transformation model
+├── billing.js                    # Billing information model
+├── cart.js                       # Shopping cart model with totals
+├── categories.js                 # Category navigation model
+├── content.js                    # Content asset model
+├── locale.js                     # Locale and currency model
+├── order.js                      # Order model for order history
+├── payment.js                    # Payment instrument model
+├── productLineItems.js           # Collection of product line items
+├── shipping.js                   # Shipping address and methods
+├── store.js                      # Individual store model
+├── stores.js                     # Store locator collection model
+├── totals.js                     # Order/cart totals calculation model
+├── price/                        # Price-related models
+│   ├── default.js                # Standard price model
+│   ├── range.js                  # Price range model (min-max)
+│   └── tiered.js                 # Tiered pricing model
+├── product/                      # Product-related models
+│   ├── bonusProduct.js           # Bonus/promotional product model
+│   ├── fullProduct.js            # Complete product details model
+│   ├── productAttributes.js      # Product attributes model
+│   ├── productBundle.js          # Product bundle model
+│   ├── productImages.js          # Product images model
+│   ├── productSet.js             # Product set model
+│   ├── productTile.js            # Product tile/listing model
+│   └── decorators/               # Product decorator functions
+│       ├── index.js              # Decorator registry
+│       ├── attributes.js         # Product attributes decorator
+│       ├── availability.js       # Stock availability decorator
+│       ├── base.js               # Core product information
+│       ├── bonusUnitPrice.js     # Bonus pricing decorator
+│       ├── bundleReadyToOrder.js # Bundle ordering readiness
+│       ├── bundledProducts.js    # Bundle component products
+│       ├── currentUrl.js         # Product URL decorator
+│       ├── description.js        # Product description decorator
+│       ├── images.js             # Product images decorator
+│       ├── online.js             # Online availability decorator
+│       ├── options.js            # Product options decorator
+│       ├── pageMetaData.js       # SEO metadata decorator
+│       ├── price.js              # Price calculation decorator
+│       ├── promotions.js         # Promotional pricing decorator
+│       ├── quantity.js           # Quantity handling decorator
+│       ├── quantitySelector.js   # Quantity selector decorator
+│       ├── ratings.js            # Product ratings decorator
+│       ├── raw.js                # Raw API object decorator
+│       ├── readyToOrder.js       # Order readiness decorator
+│       ├── searchPrice.js        # Search result pricing
+│       ├── searchVariationAttributes.js # Search variation handling
+│       ├── setIndividualProducts.js # Product set individuals
+│       ├── setProductsCollection.js # Product set collection
+│       ├── setReadyToOrder.js    # Set ordering readiness
+│       ├── sizeChart.js          # Size chart decorator
+│       ├── template.js           # Template selection decorator
+│       └── variationAttributes.js # Variation attributes decorator
+├── productLineItem/              # Product line item models
+│   ├── bonusOrderLineItem.js     # Bonus order line item
+│   ├── bonusProductLineItem.js   # Bonus product line item
+│   ├── bundleLineItem.js         # Bundle line item model
+│   ├── bundleOrderLineItem.js    # Bundle order line item
+│   ├── orderLineItem.js          # Order line item model
+│   ├── productLineItem.js        # Cart line item model
+│   └── decorators/               # Line item decorators
+│       ├── index.js              # Decorator registry
+│       ├── appliedPromotions.js  # Applied promotion decorator
+│       ├── bonusProductLineItem.js # Bonus product decorator
+│       ├── bonusProductLineItemUUID.js # Bonus UUID decorator
+│       ├── bonusUnitPrice.js     # Bonus pricing decorator
+│       ├── bundledProductLineItems.js # Bundle items decorator
+│       ├── discountBonusLineItems.js # Discount bonus decorator
+│       ├── gift.js               # Gift message decorator
+│       ├── options.js            # Line item options decorator
+│       ├── orderable.js          # Orderability decorator
+│       ├── preOrderUUID.js       # Pre-order UUID decorator
+│       ├── priceTotal.js         # Price total decorator
+│       ├── quantity.js           # Quantity decorator
+│       ├── quantityOptions.js    # Quantity options decorator
+│       ├── renderedPromotions.js # Rendered promotions decorator
+│       ├── shipment.js           # Shipment decorator
+│       └── uuid.js               # UUID decorator
+├── search/                       # Search-related models
+│   ├── contentSearch.js          # Content search results model
+│   ├── productSearch.js          # Product search results model
+│   ├── productSortOptions.js     # Sort options model
+│   ├── attributeRefinementValue/ # Search refinement models
+│   └── suggestions/              # Search suggestion models
+└── shipping/                     # Shipping-related models
+    └── shippingMethod.js         # Shipping method model
+```
+
+## Key Model Categories
+
+### 1. Core Commerce Models
+
+| Model | Purpose |
+|-------|---------|
+| `cart.js` | Central shopping cart with totals, line items, promotions |
+| `order.js` | Order model for history and confirmation pages |
+| `account.js` | Customer account information and preferences |
+| `payment.js` | Payment instruments and billing information |
+| `totals.js` | Cart/order total calculations |
+
+### 2. Product Models
+
+| Model | Purpose |
+|-------|---------|
+| `product/fullProduct.js` | Complete product details for PDP |
+| `product/productTile.js` | Lightweight product info for listings |
+| `product/productBundle.js` | Bundle product handling |
+| `product/productSet.js` | Product set handling |
+| `product/decorators/` | Modular product enhancement functions |
+
+### 3. Line Item Models
+
+| Model | Purpose |
+|-------|---------|
+| `productLineItem/productLineItem.js` | Cart line items |
+| `productLineItem/orderLineItem.js` | Order line items |
+| `productLineItem/bundleLineItem.js` | Bundle line items |
+| `productLineItem/decorators/` | Line item enhancement functions |
+
+### 4. Pricing Models
+
+| Model | Purpose |
+|-------|---------|
+| `price/default.js` | Standard pricing model |
+| `price/range.js` | Price range for variable pricing |
+| `price/tiered.js` | Volume-based pricing tiers |
+
+### 5. Location & Shipping Models
+
+| Model | Purpose |
+|-------|---------|
+| `store.js` & `stores.js` | Store locator functionality |
+| `shipping.js` | Shipping address and method selection |
+| `shipping/shippingMethod.js` | Individual shipping method |
+| `address.js` | Address transformation and validation |
+
+### 6. Search Models
+
+| Model | Purpose |
+|-------|---------|
+| `search/productSearch.js` | Search results and refinements |
+| `search/contentSearch.js` | Content search functionality |
+| `search/productSortOptions.js` | Sorting options for search |
+
+## Model Inheritance Patterns
+
+### Decorator Pattern (Product Models)
+
+```javascript
+// product/decorators/index.js - Central decorator registry
+module.exports = {
+    base: require('*/cartridge/models/product/decorators/base'),
+    price: require('*/cartridge/models/product/decorators/price'),
+    images: require('*/cartridge/models/product/decorators/images'),
+    availability: require('*/cartridge/models/product/decorators/availability'),
+    // ... other decorators
+};
+
+// Usage in fullProduct.js
+var decorators = require('*/cartridge/models/product/decorators/index');
+
+function fullProduct(product, apiProduct, options) {
+    decorators.base(product, apiProduct, options.productType);
+    decorators.price(product, apiProduct, options.promotions);
+    decorators.images(product, apiProduct, options);
+    return product;
+}
+```
+
+### Composition Pattern (Complex Models)
+
+```javascript
+// cart.js - Composes multiple sub-models
+var TotalsModel = require('*/cartridge/models/totals');
+var ProductLineItemsModel = require('*/cartridge/models/productLineItems');
+
+function Cart(basket) {
+    this.totals = new TotalsModel(basket);
+    this.items = new ProductLineItemsModel(basket.productLineItems);
+    this.shipments = createShipmentModels(basket.shipments);
+}
+```
+
+### Factory Pattern (Conditional Models)
+
+```javascript
+// Different models based on product type
+function createProductModel(apiProduct, type) {
+    switch (type) {
+        case 'full': 
+            return require('*/cartridge/models/product/fullProduct');
+        case 'tile': 
+            return require('*/cartridge/models/product/productTile');
+        case 'bundle': 
+            return require('*/cartridge/models/product/productBundle');
+        default:
+            return require('*/cartridge/models/product/fullProduct');
+    }
+}
+```
+
+## Best Practices for Structure
+
+1. **Follow the Directory Convention** - Maintain the same directory structure in custom cartridges
+2. **Use Decorator Registries** - Create `index.js` files to register and export decorators
+3. **Separate Concerns** - Keep pricing, images, and availability in separate decorators
+4. **Maintain Model Hierarchy** - Extend base models rather than replacing entirely
+5. **Consistent Naming** - Follow SFRA naming conventions for predictable imports
+
+## Custom Cartridge Model Structure
+
+When creating custom models, mirror the base structure:
+
+```
+app_custom/cartridge/models/
+├── account.js              # Extends base account model
+├── product/
+│   ├── fullProduct.js      # Extends base full product
+│   └── decorators/
+│       ├── index.js        # Re-exports base + custom decorators
+│       └── customAttr.js   # New custom decorator
+└── custom/
+    └── myCustomModel.js    # Brand new model
+```

package/ai-instructions/skills/sfcc-sfra-models/references/TESTING-SECURITY.md

@@ -0,0 +1,417 @@
+# SFRA Model Testing & Security Reference
+
+Complete reference for testing, performance optimization, and security considerations for SFRA models.
+
+## Unit Testing Models
+
+```javascript
+'use strict';
+
+var assert = require('chai').assert;
+var AccountModel = require('../../../cartridges/app_custom/cartridge/models/account');
+
+describe('Account Model', function() {
+    var mockCustomer;
+    var mockProfile;
+    var mockAddressBook;
+    
+    beforeEach(function() {
+        mockProfile = {
+            firstName: 'John',
+            lastName: 'Doe', 
+            email: 'john.doe@example.com',
+            custom: {
+                loyaltyNumber: 'LP123456',
+                loyaltyTier: 'Gold',
+                loyaltyPoints: 1500
+            }
+        };
+        
+        mockCustomer = {
+            authenticated: true,
+            profile: mockProfile
+        };
+        
+        mockAddressBook = {
+            addresses: []
+        };
+    });
+    
+    describe('Constructor', function() {
+        it('should create account with loyalty program data', function() {
+            var account = new AccountModel(mockCustomer, mockAddressBook, {});
+            
+            assert.isNotNull(account.loyaltyProgram);
+            assert.equal(account.loyaltyProgram.number, 'LP123456');
+            assert.equal(account.loyaltyProgram.tier, 'Gold');
+            assert.equal(account.loyaltyProgram.points, 1500);
+        });
+        
+        it('should handle customer without loyalty program', function() {
+            delete mockCustomer.profile.custom;
+            var account = new AccountModel(mockCustomer, mockAddressBook, {});
+            
+            assert.isNull(account.loyaltyProgram);
+        });
+    });
+});
+```
+
+## Testing Decorators
+
+```javascript
+'use strict';
+
+var assert = require('chai').assert;
+var socialMedia = require('../../../cartridge/models/product/decorators/socialMedia');
+
+describe('Social Media Decorator', function() {
+    var mockProduct;
+    var mockApiProduct;
+    
+    beforeEach(function() {
+        mockProduct = {};
+        mockApiProduct = {
+            ID: 'test-product',
+            name: 'Test Product',
+            shortDescription: { markup: 'Test description' },
+            brand: 'TestBrand',
+            primaryCategory: { displayName: 'Test Category' },
+            getImages: function() {
+                return [{ getURL: function() { return 'http://example.com/image.jpg'; }}];
+            }
+        };
+    });
+    
+    it('should add social sharing data to product', function() {
+        socialMedia(mockProduct, mockApiProduct);
+        
+        assert.isDefined(mockProduct.social);
+        assert.isDefined(mockProduct.social.facebook);
+        assert.isDefined(mockProduct.social.twitter);
+        assert.isDefined(mockProduct.social.pinterest);
+    });
+    
+    it('should not return a new object', function() {
+        var result = socialMedia(mockProduct, mockApiProduct);
+        
+        assert.isUndefined(result); // Decorators should not return
+        assert.isDefined(mockProduct.social); // Should mutate original
+    });
+});
+```
+
+## Performance Best Practices
+
+### Minimize API Calls
+
+```javascript
+// ❌ Bad: Multiple API calls in loop
+function getBadProductData(productIds) {
+    var products = [];
+    for (var i = 0; i < productIds.length; i++) {
+        var product = ProductMgr.getProduct(productIds[i]); // API call per product!
+        products.push(transformProduct(product));
+    }
+    return products;
+}
+
+// ✅ Good: Single API call with batch processing
+function getGoodProductData(productIds) {
+    var ProductSearchModel = require('dw/catalog/ProductSearchModel');
+    var searchModel = new ProductSearchModel();
+    searchModel.setProductIDs(productIds);
+    searchModel.search();
+    
+    var products = [];
+    var productHits = searchModel.getProductSearchHits();
+    
+    while (productHits.hasNext()) {
+        var productHit = productHits.next();
+        products.push(transformProduct(productHit.product));
+    }
+    
+    return products;
+}
+```
+
+### Efficient Data Transformation
+
+```javascript
+'use strict';
+
+var collections = require('*/cartridge/scripts/util/collections');
+
+/**
+ * Transform collection efficiently using collections.map
+ */
+function transformProductLineItems(lineItems) {
+    return collections.map(lineItems, function(lineItem) {
+        return {
+            productID: lineItem.productID,
+            productName: lineItem.productName,
+            price: lineItem.price.value,
+            quantity: lineItem.quantity.value
+        };
+    });
+}
+
+/**
+ * Filter and transform in single pass
+ */
+function getAvailableProducts(products) {
+    return collections.map(
+        collections.select(products, function(product) {
+            return product.online && product.availabilityModel.available;
+        }),
+        function(product) {
+            return transformProductTile(product);
+        }
+    );
+}
+```
+
+### Caching Strategies
+
+```javascript
+'use strict';
+
+var CacheMgr = require('dw/system/CacheMgr');
+
+// Use appropriate cache for the data type
+var shortTermCache = CacheMgr.getCache('ShortTerm');     // Minutes
+var mediumTermCache = CacheMgr.getCache('MediumTerm');   // Hours
+var longTermCache = CacheMgr.getCache('LongTerm');       // Days
+
+// Cache expensive computations
+function getCachedRecommendations(productId, maxItems) {
+    var cacheKey = 'recs_' + productId + '_' + maxItems;
+    var cached = mediumTermCache.get(cacheKey);
+    
+    if (cached) {
+        return cached;
+    }
+    
+    var recommendations = computeRecommendations(productId, maxItems);
+    mediumTermCache.put(cacheKey, recommendations, 3600); // 1 hour
+    
+    return recommendations;
+}
+```
+
+## Security Considerations
+
+### Data Sanitization
+
+```javascript
+'use strict';
+
+var StringUtils = require('dw/util/StringUtils');
+
+/**
+ * Sanitize user-generated content in models
+ */
+function sanitizeCustomerData(customer) {
+    return {
+        firstName: StringUtils.encodeString(
+            customer.profile.firstName, 
+            StringUtils.ENCODE_TYPE_HTML
+        ),
+        lastName: StringUtils.encodeString(
+            customer.profile.lastName, 
+            StringUtils.ENCODE_TYPE_HTML
+        ),
+        email: customer.profile.email // Email validation handled elsewhere
+    };
+}
+
+/**
+ * Remove sensitive data from model output
+ */
+function sanitizePaymentInstrument(paymentInstrument) {
+    return {
+        UUID: paymentInstrument.UUID,
+        maskedCreditCardNumber: paymentInstrument.maskedCreditCardNumber,
+        creditCardType: paymentInstrument.creditCardType,
+        // NEVER expose: creditCardNumber, securityCode
+        expirationMonth: paymentInstrument.expirationMonth,
+        expirationYear: paymentInstrument.expirationYear
+    };
+}
+```
+
+### Access Control in Models
+
+```javascript
+'use strict';
+
+/**
+ * Customer Model with Privacy Controls
+ */
+function Customer(apiCustomer, viewingCustomer) {
+    // Public information always available
+    this.customerNumber = apiCustomer.customerNo;
+    
+    // Private information only for authenticated customer
+    if (viewingCustomer && viewingCustomer.UUID === apiCustomer.UUID) {
+        this.profile = getCustomerProfile(apiCustomer);
+        this.addresses = getCustomerAddresses(apiCustomer);
+        this.orders = getCustomerOrders(apiCustomer);
+    }
+    
+    // Admin-only information
+    if (viewingCustomer && hasAdminPermission(viewingCustomer)) {
+        this.internalNotes = apiCustomer.custom.internalNotes;
+        this.riskScore = apiCustomer.custom.riskScore;
+    }
+}
+
+function hasAdminPermission(customer) {
+    // Check customer group membership
+    return customer.customerGroups.some(function(group) {
+        return group.ID === 'Administrators';
+    });
+}
+```
+
+### Preventing Data Leaks
+
+```javascript
+// ❌ Bad: Returning entire API object
+function getProductData(product) {
+    return {
+        product: product // Exposes all API methods and properties!
+    };
+}
+
+// ✅ Good: Whitelist specific properties
+function getProductData(product) {
+    return {
+        id: product.ID,
+        name: product.name,
+        price: product.priceModel.price.value,
+        available: product.availabilityModel.available
+        // Only expose what's needed
+    };
+}
+```
+
+## JSDoc Documentation Standards
+
+```javascript
+'use strict';
+
+/**
+ * Enhanced Product Model
+ * 
+ * @namespace ProductModel
+ * @description Provides a comprehensive JSON representation of SFCC Product objects
+ */
+
+/**
+ * Create enhanced product model
+ * 
+ * @memberof ProductModel
+ * @param {dw.catalog.Product} apiProduct - SFCC Product API object
+ * @param {Object} options - Configuration options
+ * @param {dw.catalog.ProductVariationModel} options.variationModel - Variation model
+ * @param {number} options.quantity - Selected quantity  
+ * @param {dw.util.Collection<dw.campaign.Promotion>} options.promotions - Active promotions
+ * 
+ * @returns {Object} Enhanced product model with following structure:
+ * @returns {string} returns.id - Product ID
+ * @returns {string} returns.productName - Localized product name
+ * @returns {string} returns.productType - Type: 'master', 'variant', 'simple', 'bundle', 'set'
+ * @returns {Object} returns.price - Price information
+ * @returns {Array<Object>} returns.images - Product images
+ * @returns {Object} returns.availability - Availability information
+ * 
+ * @throws {Error} Throws error if apiProduct is null or undefined
+ * 
+ * @since 1.0.0
+ * @version 2.1.0 - Added sustainability attributes
+ */
+function createEnhancedProduct(apiProduct, options) {
+    if (!apiProduct) {
+        throw new Error('apiProduct is required');
+    }
+    // Implementation
+}
+
+module.exports = createEnhancedProduct;
+```
+
+## Controller Integration Pattern
+
+```javascript
+'use strict';
+
+var server = require('server');
+var BasketMgr = require('dw/order/BasketMgr');
+var CartModel = require('*/cartridge/models/cart');
+var AccountModel = require('*/cartridge/models/account');
+
+server.post('AddToCart', function (req, res, next) {
+    var currentBasket = BasketMgr.getCurrentBasket();
+    var customer = req.currentCustomer;
+    
+    // Perform cart operations
+    var result = addProductToCart(req.form.pid, req.form.quantity);
+    
+    if (result.success) {
+        // Create models for response
+        var cartModel = new CartModel(currentBasket);
+        
+        // Add customer-specific data if authenticated
+        if (customer.authenticated) {
+            var accountModel = new AccountModel(customer.raw);
+            cartModel.customer = accountModel;
+        }
+        
+        // Return JSON response with models
+        res.json({
+            success: true,
+            cart: cartModel,
+            message: Resource.msg('cart.add.success', 'cart', null)
+        });
+    } else {
+        res.json({
+            success: false,
+            error: result.error
+        });
+    }
+    
+    next();
+});
+
+module.exports = server.exports();
+```
+
+## Test Coverage Guidelines
+
+| Model Type | Required Tests |
+|------------|----------------|
+| Simple Data Models | Constructor, null handling, property mapping |
+| Decorator Models | Mutation (not cloning), property addition, edge cases |
+| Factory Models | Each variant, default case, invalid type handling |
+| Composite Models | Sub-model creation, null components, integration |
+| Cached Models | Cache hit, cache miss, expiration, key generation |
+
+## Performance Testing
+
+```javascript
+describe('Model Performance', function() {
+    it('should create product model in under 50ms', function() {
+        var start = Date.now();
+        
+        for (var i = 0; i < 100; i++) {
+            new ProductModel(mockApiProduct, mockOptions);
+        }
+        
+        var elapsed = Date.now() - start;
+        var avgTime = elapsed / 100;
+        
+        assert.isBelow(avgTime, 50, 'Average model creation should be under 50ms');
+    });
+});
+```

package/{dist/docs/best-practices/sfra_scss.md → ai-instructions/skills/sfcc-sfra-scss/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: sfcc-sfra-scss
+description: Best practices for styling and theming SFRA storefronts using SCSS. Use when asked to create style overrides, theming, responsive layouts, or CSS customizations in SFCC.
+---
+
 ## SFRA SCSS Best Practices (AI-Agent Optimized)
 
 Purpose: Provide a concise, implementation‑ready reference for styling and theming Salesforce B2C Commerce SFRA storefronts using SCSS. Optimized for automated reasoning, safe overrides, upgrade resilience, and performant output.