sfcc-dev-mcp 1.0.19 → 1.0.21

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

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

@@ -1,417 +0,0 @@
-# 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');
-    });
-});
-```