sfcc-dev-mcp 1.0.19 → 1.0.21

package/docs/sfra/server.md

@@ -1,375 +0,0 @@
-# Class Server
-
-## Inheritance Hierarchy
-
-- Object
-  - sfra.models.Server
-
-## Description
-
-The SFRA Server class is the core routing solution for Salesforce Commerce Cloud's Storefront Reference Architecture (SFRA). This class provides a comprehensive middleware-based routing system that handles HTTP requests, manages route registration, and coordinates the request-response lifecycle. The Server class supports route definition with middleware chains, HTTP method shortcuts (GET/POST), route modification capabilities (prepend/append/replace), and integration with SFCC's hook system for extensibility. It serves as the foundation for all SFRA controller functionality, providing a structured approach to handling web requests with support for caching, personalization, redirects, and various rendering strategies.
-
-## Properties
-
-### routes
-
-**Type:** Object
-
-Internal registry of all registered routes, indexed by route name.
-
-## Constructor Summary
-
-### Server
-
-**Signature:** `Server()`
-
-Creates a new Server instance with an empty routes registry.
-
-## Method Summary
-
-### use
-
-**Signature:** `use(name, ...middleware) : Route`
-
-Creates a new route with middleware chain.
-
-### get
-
-**Signature:** `get(name, ...middleware) : Route`
-
-Creates a GET-specific route with automatic HTTP method validation.
-
-### post
-
-**Signature:** `post(name, ...middleware) : Route`
-
-Creates a POST-specific route with automatic HTTP method validation.
-
-### exports
-
-**Signature:** `exports() : Object`
-
-Returns an exportable object containing all registered routes.
-
-### extend
-
-**Signature:** `extend(server) : void`
-
-Extends the current server with routes from another server object.
-
-### prepend
-
-**Signature:** `prepend(name, ...middleware) : void`
-
-Adds middleware to the beginning of an existing route's chain.
-
-### append
-
-**Signature:** `append(name, ...middleware) : void`
-
-Adds middleware to the end of an existing route's chain.
-
-### replace
-
-**Signature:** `replace(name, ...middleware) : void`
-
-Replaces an existing route with a new middleware chain.
-
-### getRoute
-
-**Signature:** `getRoute(name) : Route`
-
-Retrieves a specific route by name.
-
-## Method Detail
-
-### use
-
-**Signature:** `use(name, ...middleware) : Route`
-
-**Description:** Creates a new route with the specified name and middleware chain. Automatically creates Request and Response objects from global SFCC objects and sets up route completion handling including caching, personalization, and rendering.
-
-**Parameters:**
-- `name` (String) - Unique name for the route
-- `...middleware` (Function[]) - Variable number of middleware functions to execute
-
-**Returns:**
-Route object representing the created route.
-
-**Throws:**
-- Error if name is not a string
-- Error if middleware contains non-function items
-- Error if route name already exists
-
-**Route Completion Handling:**
-- Sets cache expiration based on `res.cachePeriod` and `res.cachePeriodUnit`
-- Applies personalization with `price_promotion` vary-by header when `res.personalized` is true
-- Handles redirects with optional status codes
-- Applies rendering through the render system
-
-### get
-
-**Signature:** `get(name, ...middleware) : Route`
-
-**Description:** Convenience method for creating GET-only routes. Automatically prepends HTTP GET validation middleware to the chain.
-
-**Parameters:**
-- `name` (String) - Unique name for the route
-- `...middleware` (Function[]) - Variable number of middleware functions
-
-**Returns:**
-Route object with GET method validation.
-
-### post
-
-**Signature:** `post(name, ...middleware) : Route`
-
-**Description:** Convenience method for creating POST-only routes. Automatically prepends HTTP POST validation middleware to the chain.
-
-**Parameters:**
-- `name` (String) - Unique name for the route
-- `...middleware` (Function[]) - Variable number of middleware functions
-
-**Returns:**
-Route object with POST method validation.
-
-### exports
-
-**Signature:** `exports() : Object`
-
-**Description:** Creates an exportable object containing all registered routes with their public interfaces. Includes internal routes registry for extension capabilities.
-
-**Returns:**
-Object with route names as keys and route interfaces as values, plus `__routes` property containing internal routes.
-
-**Export Format:**
-```javascript
-{
-  "routeName": { /* route interface */ },
-  "__routes": { /* internal routes registry */ }
-}
-```
-
-### extend
-
-**Signature:** `extend(server) : void`
-
-**Description:** Extends the current server with routes from another server object created by the `exports()` method. Validates the server object structure before extension.
-
-**Parameters:**
-- `server` (Object) - Server object created by `exports()` method
-
-**Throws:**
-- Error if server object is invalid (missing `__routes`)
-- Error if server has no routes to extend
-
-### prepend
-
-**Signature:** `prepend(name, ...middleware) : void`
-
-**Description:** Adds middleware functions to the beginning of an existing route's middleware chain, allowing for route enhancement and modification.
-
-**Parameters:**
-- `name` (String) - Name of existing route to modify
-- `...middleware` (Function[]) - Middleware functions to prepend
-
-**Throws:**
-- Error if name is not a string
-- Error if middleware contains non-function items
-- Error if route does not exist
-
-### append
-
-**Signature:** `append(name, ...middleware) : void`
-
-**Description:** Adds middleware functions to the end of an existing route's middleware chain, enabling route extension and additional processing.
-
-**Parameters:**
-- `name` (String) - Name of existing route to modify
-- `...middleware` (Function[]) - Middleware functions to append
-
-**Throws:**
-- Error if name is not a string
-- Error if middleware contains non-function items
-- Error if route does not exist
-
-### replace
-
-**Signature:** `replace(name, ...middleware) : void`
-
-**Description:** Completely replaces an existing route with a new middleware chain, maintaining the same route name but changing implementation.
-
-**Parameters:**
-- `name` (String) - Name of existing route to replace
-- `...middleware` (Function[]) - New middleware functions for the route
-
-**Throws:**
-- Error if name is not a string
-- Error if middleware contains non-function items
-- Error if route does not exist
-
-### getRoute
-
-**Signature:** `getRoute(name) : Route`
-
-**Description:** Retrieves a specific route object by name for inspection or direct manipulation.
-
-**Parameters:**
-- `name` (String) - Name of the route to retrieve
-
-**Returns:**
-Route object if found, undefined otherwise.
-
-## Route Lifecycle Management
-
-### Route Creation Process
-
-1. **Parameter Validation**: Validates route name and middleware chain
-2. **Request/Response Creation**: Creates SFRA Request and Response objects from globals
-3. **Route Object Creation**: Instantiates Route with name, middleware, request, and response
-4. **Event Handler Registration**: Sets up `route:Complete` event handler
-5. **Route Registration**: Stores route in internal registry
-6. **Hook Integration**: Calls `app.server.registerRoute` hook if available
-
-### Route Completion Handling
-
-**Cache Management:**
-- Applies cache expiration when `res.cachePeriod` is set
-- Supports minutes or hours as cache period units (defaults to hours)
-- Sets HTTP expires header on the response
-
-**Personalization:**
-- Sets `price_promotion` vary-by header when `res.personalized` is true
-- Enables proper caching behavior for personalized content
-
-**Redirect Processing:**
-- Handles redirect URLs with optional status codes
-- Emits `route:Redirect` event before redirecting
-- Supports both default and custom redirect status codes
-
-**Rendering Pipeline:**
-- Applies all accumulated renderings through the render system
-- Processes ISML templates, JSON responses, XML output, and Page Designer pages
-
-## Integration Points
-
-### Global Object Integration
-
-**Request Object Creation:**
-```javascript
-var rq = new Request(
-    typeof request !== 'undefined' ? request : {},
-    typeof customer !== 'undefined' ? customer : {},
-    typeof session !== 'undefined' ? session : {}
-);
-```
-
-**Response Object Creation:**
-```javascript
-var rs = new Response(typeof response !== 'undefined' ? response : {});
-```
-
-### Hook System Integration
-
-The server integrates with SFCC's hook system through the `app.server.registerRoute` hook, allowing:
-- Custom route event handlers
-- Route-specific processing extensions
-- Integration with custom middleware systems
-
-### Middleware Architecture
-
-**Middleware Function Signature:**
-```javascript
-function middleware(req, res, next) {
-    // Middleware logic
-    next(); // Continue to next middleware
-}
-```
-
-**Middleware Chain Execution:**
-- Sequential execution of middleware functions
-- Support for asynchronous operations through next() callbacks
-- Automatic error handling and route completion
-
-## Usage Examples
-
-### Basic Route Creation
-```javascript
-server.use('HomePage', function(req, res, next) {
-    res.render('home/homepage', { title: 'Welcome' });
-    next();
-});
-```
-
-### HTTP Method-Specific Routes
-```javascript
-server.get('ProductShow', middleware.cache, function(req, res, next) {
-    // GET-only route with caching
-    next();
-});
-
-server.post('CartAdd', middleware.csrf, function(req, res, next) {
-    // POST-only route with CSRF protection
-    next();
-});
-```
-
-### Route Modification
-```javascript
-// Add authentication to existing route
-server.prepend('Account-Show', middleware.auth);
-
-// Add logging to existing route
-server.append('Checkout-Begin', middleware.logging);
-
-// Replace route implementation
-server.replace('Search-Show', newSearchMiddleware);
-```
-
-### Server Extension
-```javascript
-// Export routes from one server
-var exportedRoutes = server.exports();
-
-// Extend another server
-var newServer = new Server();
-newServer.extend(exportedRoutes);
-```
-
-## Error Handling
-
-### Parameter Validation Errors
-
-- **Invalid Route Name**: Throws error if first parameter is not a string
-- **Invalid Middleware**: Throws error if middleware chain contains non-functions
-- **Duplicate Route**: Throws error if route name already exists
-
-### Extension Errors
-
-- **Invalid Server Object**: Throws error for objects missing `__routes` property
-- **Empty Server**: Throws error when extending with server that has no routes
-
-### Route Modification Errors
-
-- **Non-Existent Route**: Throws error when trying to modify routes that don't exist
-- **Invalid Parameters**: Validates parameters before attempting modifications
-
-## Property Details
-
-### routes
-
-**Type:** Object
-
-**Description:** Internal registry storing all route definitions indexed by route name. Each entry contains a Route object with the complete middleware chain and configuration.
-
-**Structure:**
-```javascript
-{
-  "routeName": Route, // Route object instance
-  "anotherRoute": Route
-}
-```
-
-This registry enables route lookup, modification, and export functionality while maintaining the complete route configuration and state.
-
----

package/docs/sfra/shipping.md

@@ -1,181 +0,0 @@
-# SFRA Shipping Model
-
-## Overview
-
-The Shipping model represents shipping information for a shipment in SFRA applications. It provides comprehensive shipping data including addresses, methods, product line items, and gift options for checkout and order processing.
-
-## Constructor
-
-```javascript
-function ShippingModel(shipment, address, customer, containerView)
-```
-
-Creates a Shipping model instance with complete shipping information.
-
-### Parameters
-
-- `shipment` (dw.order.Shipment) - The default shipment of the current basket
-- `address` (Object) - The address to use to filter the shipping method list  
-- `customer` (Object) - The current customer model
-- `containerView` (string) - The view of the product line items ('order' or 'basket')
-
-## Properties
-
-### UUID
-**Type:** string | null
-
-Unique identifier for the shipment.
-
-### productLineItems
-**Type:** ProductLineItemsModel | null
-
-Product line items model containing all products in this shipment with detailed information. Created using `ProductLineItemsModel` (note the "Model" suffix).
-
-### applicableShippingMethods
-**Type:** Array<Object>
-
-Array of shipping methods available for this shipment. Retrieved using `shippingHelpers.getApplicableShippingMethods(shipment, address)`.
-
-### selectedShippingMethod
-**Type:** ShippingMethodModel | null
-
-Currently selected shipping method for this shipment, or null if none selected.
-
-### shippingAddress
-**Type:** Object
-
-Shipping address for this shipment. Logic:
-- If shipment has address data (checked via `emptyAddress()` helper), uses `new AddressModel(shipment.shippingAddress).address`
-- Otherwise, uses the provided `address` parameter
-
-### matchingAddressId
-**Type:** string | boolean
-
-ID of matching customer address, or false if no match found in customer's address book.
-
-### isGift
-**Type:** boolean | null
-
-Indicates whether this shipment is marked as a gift.
-
-### giftMessage
-**Type:** string | null
-
-Gift message for the shipment if it's marked as a gift.
-
-## Helper Functions
-
-### getProductLineItemsModel(shipment, containerView)
-Creates a product line items model for the shipment's products.
-
-**Parameters:**
-- `shipment` (dw.order.Shipment) - Target shipment
-- `containerView` (string) - View context
-
-**Returns:** ProductLineItemsModel | null
-
-### getSelectedShippingMethod(shipment)
-Gets the selected shipping method for a shipment.
-
-**Parameters:**
-- `shipment` (dw.order.Shipment) - Target shipment
-
-**Returns:** ShippingMethodModel | null
-
-### getShipmentUUID(shipment)
-Extracts the UUID from a shipment.
-
-**Parameters:**
-- `shipment` (dw.order.Shipment) - Target shipment
-
-**Returns:** string | null
-
-### getAssociatedAddress(shipment, customer)
-Finds matching customer address for the shipping address.
-
-**Parameters:**
-- `shipment` (dw.order.Shipment) - Target shipment
-- `customer` (Object) - Customer model
-
-**Returns:** string | boolean - Matching address ID or false
-
-### emptyAddress(shipment)
-Checks if the shipment has any address information populated.
-
-**Parameters:**
-- `shipment` (dw.order.Shipment) - Target shipment
-
-**Returns:** boolean - True if ANY of the address fields ['firstName', 'lastName', 'address1', 'address2', 'phone', 'city', 'postalCode', 'stateCode'] have values
-
-## Address Handling
-
-The model provides flexible address handling:
-- **Address Population Check**: Uses `emptyAddress()` to check if shipment has address data
-- **Existing Address**: Uses `new AddressModel(shipment.shippingAddress).address` if address is populated
-- **Fallback Address**: Uses provided address parameter if shipment address is empty
-- **Address Matching**: Finds matching addresses in customer's address book using `isEquivalentAddress()`
-
-## Usage Example
-
-```javascript
-var ShippingModel = require('*/cartridge/models/shipping');
-var BasketMgr = require('dw/order/BasketMgr');
-
-var currentBasket = BasketMgr.getCurrentBasket();
-var shipment = currentBasket.defaultShipment;
-var shippingAddress = getShippingAddress(); // Your address object
-var customer = req.currentCustomer;
-
-var shipping = new ShippingModel(shipment, shippingAddress, customer, 'basket');
-
-// Access shipping information
-console.log('Shipment UUID: ' + shipping.UUID);
-console.log('Available methods: ' + shipping.applicableShippingMethods.length);
-
-if (shipping.selectedShippingMethod) {
-    console.log('Selected: ' + shipping.selectedShippingMethod.displayName);
-}
-
-// Check address matching
-if (shipping.matchingAddressId) {
-    console.log('Matches customer address: ' + shipping.matchingAddressId);
-}
-
-// Check for gift options
-if (shipping.isGift) {
-    console.log('Gift message: ' + shipping.giftMessage);
-}
-
-// Access products in shipment (if productLineItems is not null)
-if (shipping.productLineItems) {
-    shipping.productLineItems.items.forEach(function(item) {
-        console.log(item.productName + ' x ' + item.quantity);
-    });
-}
-```
-
-## Gift Functionality
-
-The model supports gift shipments:
-- **isGift** - Boolean flag for gift marking
-- **giftMessage** - Custom message for gift recipients
-- Integrates with gift wrapping and messaging features
-
-## Notes
-
-- Handles both populated and empty shipping addresses with conditional logic
-- Integrates with `shippingHelpers.getApplicableShippingMethods()` for method calculation
-- Uses `AddressModel` for address formatting when shipment address exists
-- Provides address matching using `isEquivalentAddress()` for saved customer addresses  
-- Supports gift functionality with boolean flags and message text
-- Works with both basket and order contexts via `containerView` parameter
-- Uses `ProductLineItemsModel` (with "Model" suffix) for line item information
-- All properties handle null shipments gracefully
-
-## Related Models
-
-- **AddressModel** - Used for shipping address formatting
-- **ProductLineItemsModel** - Used for shipment products
-- **ShippingMethodModel** - Used for shipping method details
-- **Cart Model** - Uses shipping models for checkout
-- **Order Model** - Uses shipping models for order information

package/docs/sfra/store.md

@@ -1,145 +0,0 @@
-# SFRA Store Model
-
-## Overview
-
-The Store model represents a physical store location in SFRA applications. It provides store information including location details, contact information, and store hours for store locator functionality and in-store pickup features.
-
-## Constructor
-
-```javascript
-function store(storeObject)
-```
-
-Creates a Store model instance from a store object.
-
-### Parameters
-
-- `storeObject` (dw.catalog.Store) - A Store object from the SFCC API
-
-## Properties
-
-### ID
-**Type:** string
-
-Unique identifier for the store.
-
-### name
-**Type:** string
-
-Display name of the store.
-
-### address1
-**Type:** string
-
-Primary address line of the store location.
-
-### address2
-**Type:** string
-
-Secondary address line (suite, building, etc.).
-
-### city
-**Type:** string
-
-City where the store is located.
-
-### postalCode
-**Type:** string
-
-Postal/ZIP code for the store location.
-
-### latitude
-**Type:** number
-
-Latitude coordinate for the store location (used for mapping and distance calculations).
-
-### longitude
-**Type:** number
-
-Longitude coordinate for the store location (used for mapping and distance calculations).
-
-### phone
-**Type:** string (optional)
-
-Store phone number for customer contact.
-
-### stateCode
-**Type:** string (optional)
-
-State or province code for the store location.
-
-### countryCode
-**Type:** string (optional)
-
-Country code for the store location (extracted from countryCode.value).
-
-### storeHours
-**Type:** string (optional)
-
-Store hours information as markup/HTML content for display.
-
-## Usage Example
-
-```javascript
-var store = require('*/cartridge/models/store');
-var StoreMgr = require('dw/catalog/StoreMgr');
-
-// Get a specific store
-var storeObject = StoreMgr.getStore('store-001');
-var storeModel = new store(storeObject);
-
-// Access store properties
-console.log(storeModel.name);          // "Downtown Location"
-console.log(storeModel.address1);      // "123 Main St"
-console.log(storeModel.city);          // "New York"
-console.log(storeModel.phone);         // "555-123-4567"
-
-// Use coordinates for mapping
-if (storeModel.latitude && storeModel.longitude) {
-    console.log('Location: ' + storeModel.latitude + ', ' + storeModel.longitude);
-}
-
-// Display store hours
-if (storeModel.storeHours) {
-    console.log(storeModel.storeHours); // HTML markup for hours display
-}
-```
-
-## Coordinate System
-
-The model provides geographic coordinates for:
-- **Mapping Integration** - Display stores on maps
-- **Distance Calculations** - Find nearest stores
-- **Location Services** - GPS-based store finding
-
-## Conditional Properties
-
-Several properties are only included if they exist in the source store object:
-- **phone** - Only included if store has a phone number
-- **stateCode** - Only included for locations with state/province
-- **countryCode** - Only included if country is specified
-- **storeHours** - Only included if store hours are configured
-
-## Store Hours Format
-
-Store hours are provided as markup/HTML content, allowing for:
-- Rich formatting of hours display
-- Multiple day ranges and special hours
-- Holiday hours and exceptions
-- Custom styling and presentation
-
-## Notes
-
-- Handles missing store data gracefully
-- Provides essential location information for store locators
-- Includes geographic coordinates for mapping functionality
-- Supports international stores with flexible address formats
-- Store hours support rich HTML formatting
-- Null-safe property access for optional fields
-
-## Related Models
-
-- **Stores Model** - Collection of store models
-- **Product Models** - May include store availability
-- **Cart Models** - May include store pickup options
-- **Address Models** - Similar address structure