@salesforce/b2c-cli 2.3.1 → 2.5.0

package/content/guidance/b2c/b2c-page-designer/references/META-DEFINITIONS.md

@@ -0,0 +1,340 @@
+# Page Designer Meta Definitions Reference
+
+Complete JSON schema for page types and component types.
+
+## Page Type Schema
+
+```json
+{
+    "name": "Page Type Name",
+    "description": "Description shown in editor",
+    "region_definitions": [
+        {
+            "id": "regionId",
+            "name": "Region Name",
+            "max_components": 5,
+            "component_type_exclusions": [],
+            "component_type_inclusions": []
+        }
+    ]
+}
+```
+
+### Page Type Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | Yes | Display name in editor |
+| `description` | string | No | Description shown when selecting page type |
+| `region_definitions` | array | Yes | List of content regions |
+
+### Region Definition Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | Unique identifier (alphanumeric, underscore) |
+| `name` | string | Yes | Display name in editor |
+| `max_components` | integer | No | Maximum components allowed |
+| `component_type_exclusions` | array | No | Components NOT allowed in region |
+| `component_type_inclusions` | array | No | ONLY these components allowed |
+
+## Component Type Schema
+
+```json
+{
+    "name": "Component Name",
+    "description": "Component description",
+    "group": "content",
+    "attribute_definition_groups": [
+        {
+            "id": "groupId",
+            "name": "Group Name",
+            "description": "Group description",
+            "attribute_definitions": [
+                {
+                    "id": "attributeId",
+                    "name": "Attribute Name",
+                    "description": "Help text",
+                    "type": "string",
+                    "required": false,
+                    "default_value": "default"
+                }
+            ]
+        }
+    ],
+    "region_definitions": []
+}
+```
+
+### Component Type Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | Yes | Display name |
+| `description` | string | No | Description in editor |
+| `group` | string | No | Sidebar group (content, products, etc.) |
+| `attribute_definition_groups` | array | Yes | Grouped attribute definitions |
+| `region_definitions` | array | No | Nested regions (for container components) |
+
+### Attribute Definition Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | Attribute identifier |
+| `name` | string | Yes | Display name |
+| `description` | string | No | Help text |
+| `type` | string | Yes | Attribute type |
+| `required` | boolean | No | Whether required (default false) |
+| `default_value` | varies | No | Default value |
+| `values` | array | No | Options for enum type |
+
+## Complete Page Type Example
+
+```json
+{
+    "name": "Product Landing Page",
+    "description": "Landing page for product campaigns with hero, features, and product grid",
+    "region_definitions": [
+        {
+            "id": "hero",
+            "name": "Hero Section",
+            "max_components": 1,
+            "component_type_inclusions": [
+                { "type_id": "hero-banner" },
+                { "type_id": "video-hero" }
+            ]
+        },
+        {
+            "id": "features",
+            "name": "Features Section",
+            "max_components": 4,
+            "component_type_inclusions": [
+                { "type_id": "feature-card" },
+                { "type_id": "icon-block" }
+            ]
+        },
+        {
+            "id": "products",
+            "name": "Product Grid",
+            "max_components": 1,
+            "component_type_inclusions": [
+                { "type_id": "product-grid" },
+                { "type_id": "product-carousel" }
+            ]
+        },
+        {
+            "id": "content",
+            "name": "Additional Content",
+            "component_type_exclusions": [
+                { "type_id": "hero-banner" },
+                { "type_id": "video-hero" }
+            ]
+        },
+        {
+            "id": "cta",
+            "name": "Call to Action",
+            "max_components": 1
+        }
+    ]
+}
+```
+
+## Complete Component Type Example
+
+```json
+{
+    "name": "Product Card",
+    "description": "Display a single product with image, name, price, and add to cart",
+    "group": "products",
+    "attribute_definition_groups": [
+        {
+            "id": "product",
+            "name": "Product Selection",
+            "attribute_definitions": [
+                {
+                    "id": "product",
+                    "name": "Product",
+                    "description": "Select the product to display",
+                    "type": "product",
+                    "required": true
+                }
+            ]
+        },
+        {
+            "id": "display",
+            "name": "Display Options",
+            "attribute_definitions": [
+                {
+                    "id": "showPrice",
+                    "name": "Show Price",
+                    "type": "boolean",
+                    "default_value": true
+                },
+                {
+                    "id": "showRating",
+                    "name": "Show Rating",
+                    "type": "boolean",
+                    "default_value": true
+                },
+                {
+                    "id": "showAddToCart",
+                    "name": "Show Add to Cart Button",
+                    "type": "boolean",
+                    "default_value": true
+                },
+                {
+                    "id": "imageSize",
+                    "name": "Image Size",
+                    "type": "enum",
+                    "values": ["small", "medium", "large"],
+                    "default_value": "medium"
+                }
+            ]
+        },
+        {
+            "id": "style",
+            "name": "Styling",
+            "attribute_definitions": [
+                {
+                    "id": "cardStyle",
+                    "name": "Card Style",
+                    "type": "enum",
+                    "values": ["default", "bordered", "shadow", "minimal"],
+                    "default_value": "default"
+                },
+                {
+                    "id": "backgroundColor",
+                    "name": "Background Color",
+                    "description": "CSS color value (e.g., #ffffff or white)",
+                    "type": "string"
+                }
+            ]
+        }
+    ]
+}
+```
+
+## Container Component Example
+
+Component with nested regions:
+
+```json
+{
+    "name": "Two Column Layout",
+    "description": "Container with two side-by-side columns",
+    "group": "layout",
+    "attribute_definition_groups": [
+        {
+            "id": "layout",
+            "name": "Layout Options",
+            "attribute_definitions": [
+                {
+                    "id": "leftWidth",
+                    "name": "Left Column Width",
+                    "type": "enum",
+                    "values": ["25%", "33%", "50%", "66%", "75%"],
+                    "default_value": "50%"
+                },
+                {
+                    "id": "gap",
+                    "name": "Column Gap",
+                    "type": "enum",
+                    "values": ["none", "small", "medium", "large"],
+                    "default_value": "medium"
+                }
+            ]
+        }
+    ],
+    "region_definitions": [
+        {
+            "id": "left",
+            "name": "Left Column"
+        },
+        {
+            "id": "right",
+            "name": "Right Column"
+        }
+    ]
+}
+```
+
+**Script for container:**
+
+> This follows SFRA's container-component pattern: build the region registry with
+> `PageRenderHelper.getRegionModelRegistry(component)`, pass it to the template as `regions`, and
+> call `RegionModel.render()` in ISML. The region model preserves SFRA's region and component render
+> settings before delegating to `PageMgr.renderRegion()`.
+
+```javascript
+'use strict';
+
+var Template = require('dw/util/Template');
+var HashMap = require('dw/util/HashMap');
+var PageRenderHelper = require('*/cartridge/experience/utilities/PageRenderHelper');
+
+module.exports.render = function (context) {
+    var model = new HashMap();
+    var component = context.component;
+
+    model.regions = PageRenderHelper.getRegionModelRegistry(component);
+
+    return new Template('experience/components/twocolumn').render(model).text;
+};
+```
+
+**Template for container:**
+
+```html
+<div class="two-column">
+    <div class="left-column">
+        <isprint value="${pdict.regions.left.render()}" encoding="off"/>
+    </div>
+    <div class="right-column">
+        <isprint value="${pdict.regions.right.render()}" encoding="off"/>
+    </div>
+</div>
+```
+
+## Page Script Context
+
+> Illustrative context API; confirm current PageScriptContext properties with `docs_read dw.experience.PageScriptContext` (note: renderParameters is deprecated, use getRuntimeParameters() instead).
+
+Properties available in `context` parameter:
+
+```javascript
+module.exports.render = function (context) {
+    var page = context.page;                    // dw.experience.Page
+    var renderParameters = context.renderParameters;  // DEPRECATED - use context.getRuntimeParameters()
+
+    // Page methods
+    var pageId = page.ID;
+    var pageName = page.name;
+    var isVisible = page.isVisible();
+    var region = page.getRegion('regionId');    // dw.experience.Region
+};
+```
+
+## Component Script Context
+
+> Illustrative context API; confirm current ComponentScriptContext properties with `docs_read dw.experience.ComponentScriptContext`.
+
+Properties available in `context` parameter:
+
+```javascript
+module.exports.render = function (context) {
+    var component = context.component;          // dw.experience.Component
+    var content = context.content;              // HashMap of attribute values
+    var componentRenderSettings = context.componentRenderSettings;
+
+    // Access attributes
+    var image = content.image;                  // dw.experience.image.Image
+    var product = content.product;              // dw.catalog.Product
+    var category = content.category;            // dw.catalog.Category
+    var text = content.headline;                // String
+    var enabled = content.showPrice;            // Boolean
+    var url = content.ctaUrl;                   // String (URL)
+
+    // For container components
+    var region = component.getRegion('regionId');
+};
+```

package/content/guidance/b2c/b2c-querying-data/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: b2c-querying-data
+description: Write efficient data queries in B2C Commerce for products, customers, and orders. Use this skill whenever the user needs to search products on a storefront page, look up customer profiles, query orders, paginate search results, or fix slow category pages. Also use when they ask about performance problems with data access, replacing database-intensive APIs with index-backed alternatives, or choosing between search vs query methods — even if they just say "my category page is slow" or "how do I find customers by email".
+---
+
+# Querying Data in B2C Commerce
+
+Efficient data querying is critical for storefront performance and job stability. B2C Commerce provides index-backed search APIs and database query APIs—choosing the right one for each use case avoids performance problems.
+
+## Product Search (Storefront)
+
+Use `ProductSearchModel` for all storefront product searches. It is index-backed and designed for high-traffic pages.
+
+### Basic Product Search
+
+```javascript
+var ProductSearchModel = require('dw/catalog/ProductSearchModel');
+
+var psm = new ProductSearchModel();
+psm.setCategoryID('electronics');
+psm.setOrderableProductsOnly(true); // Only in-stock products
+psm.setSearchPhrase('laptop');
+psm.search();
+
+var hits = psm.getProductSearchHits();
+while (hits.hasNext()) {
+    var hit = hits.next();
+    var productID = hit.productID;
+    var minPrice = hit.minPrice;
+    var maxPrice = hit.maxPrice;
+}
+hits.close();
+```
+
+### Paging Search Results
+
+Always page results—never load the full result set:
+
+```javascript
+var ProductSearchModel = require('dw/catalog/ProductSearchModel');
+var PagingModel = require('dw/web/PagingModel');
+
+var psm = new ProductSearchModel();
+psm.setCategoryID('mens-clothing');
+psm.setOrderableProductsOnly(true);
+psm.search();
+
+var pagingModel = new PagingModel(psm.getProductSearchHits(), psm.count);
+pagingModel.setPageSize(12);
+pagingModel.setStart(0); // page offset
+
+var pageElements = pagingModel.pageElements;
+while (pageElements.hasNext()) {
+    var hit = pageElements.next();
+    // Render product tile
+}
+```
+
+### Getting Variation Data from Search Hits
+
+Use `ProductSearchHit` methods instead of loading full product objects:
+
+```javascript
+// GOOD: Get variation info from the search hit (index-backed)
+var representedColors = hit.getRepresentedVariationValues('color');
+var representedIDs = hit.getRepresentedProductIDs();
+var minPrice = hit.getMinPrice();
+var maxPrice = hit.getMaxPrice();
+
+// BAD: Loading the full product and iterating variants (database-intensive)
+var product = hit.product;
+var variants = product.getVariants(); // Expensive!
+var priceModel = product.getPriceModel(); // Expensive!
+```
+
+### Search Refinements
+
+```javascript
+var psm = new ProductSearchModel();
+psm.setCategoryID('shoes');
+psm.addRefinementValues('color', 'blue');
+psm.addRefinementValues('size', '10');
+psm.setPriceMin(50);
+psm.setPriceMax(200);
+psm.search();
+
+// Get available refinement values for the current result set
+var refinements = psm.getRefinements();
+var colorValues = refinements.getAllRefinementValues('color');
+```
+
+### ProductSearchModel API Summary
+
+| Method | Description |
+|--------|-------------|
+| `search()` | Execute the search |
+| `setCategoryID(id)` | Filter by category |
+| `setSearchPhrase(phrase)` | Set search keywords |
+| `setOrderableProductsOnly(flag)` | Exclude out-of-stock |
+| `addRefinementValues(name, value)` | Add refinement filter |
+| `setPriceMin(price)` / `setPriceMax(price)` | Price range filter |
+| `setSortingRule(rule)` | Set sorting rule |
+| `getProductSearchHits()` | Get result iterator |
+| `getRefinements()` | Get available refinements |
+| `count` | Total result count |
+
+## Order Queries
+
+### OrderMgr.searchOrders / queryOrders
+
+Use `searchOrders` for index-backed order lookups and `queryOrders` for database queries:
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Order = require('dw/order/Order');
+
+// Index-backed search (preferred for common lookups)
+var orders = OrderMgr.searchOrders(
+    'customerEmail = {0} AND status != {1}',
+    'creationDate desc',
+    'customer@example.com',
+    Order.ORDER_STATUS_FAILED
+);
+
+while (orders.hasNext()) {
+    var order = orders.next();
+    // Process order
+}
+orders.close(); // Always close iterators
+```
+
+### Query by Date Range
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Calendar = require('dw/util/Calendar');
+var Order = require('dw/order/Order');
+
+var startDate = new Calendar();
+startDate.add(Calendar.DAY_OF_YEAR, -7);
+
+var orders = OrderMgr.searchOrders(
+    'creationDate >= {0} AND status = {1}',
+    'creationDate desc',
+    startDate.time,
+    Order.ORDER_STATUS_NEW
+);
+
+while (orders.hasNext()) {
+    var order = orders.next();
+    // Process
+}
+orders.close();
+```
+
+### searchOrders vs queryOrders
+
+| Aspect | `searchOrders` | `queryOrders` |
+|--------|---------------|---------------|
+| Backing | Search index | Database |
+| Performance | Fast for indexed fields | Slower, full table scan possible |
+| Use when | Querying indexed attributes (status, email, dates) | Querying non-indexed or custom attributes |
+| Result limit | Up to 1000 hits | No hard limit (but use paging) |
+
+**Prefer `searchOrders`** for storefront and high-traffic code paths. Use `queryOrders` only when you need to query attributes not available in the search index.
+
+## Customer / Profile Queries
+
+### CustomerMgr (Preferred)
+
+Use `searchProfiles` for index-backed searches and `processProfiles` for batch processing in jobs:
+
+```javascript
+var CustomerMgr = require('dw/customer/CustomerMgr');
+
+// Index-backed search (storefront use)
+var profiles = CustomerMgr.searchProfiles(
+    'email = {0}',
+    'lastLoginTime desc',
+    'customer@example.com'
+);
+
+while (profiles.hasNext()) {
+    var profile = profiles.next();
+    // Process profile
+}
+profiles.close();
+```
+
+### Batch Processing (Jobs)
+
+Use `processProfiles` for jobs that need to iterate over many profiles—it has optimized memory management:
+
+```javascript
+var CustomerMgr = require('dw/customer/CustomerMgr');
+
+function processProfile(profile) {
+    // Process each profile individually
+    // Memory is managed automatically
+}
+
+// Process all profiles matching the query
+CustomerMgr.processProfiles('gender = {0}', processProfile, 1);
+```
+
+**Important:** `processProfiles` replaces the older `queryProfiles` and `SystemObjectMgr.querySystemObjects` for customer data. It uses the full-text search service with better performance and memory characteristics.
+
+### Customer Query Behaviors
+
+- Wildcards (`*`, `%`, `+`) are filtered from queries and replaced by spaces
+- `LIKE` and `ILIKE` execute as full-text queries (match whole words, not substrings)
+- `LIKE` is case-insensitive
+- Combining `AND` and `OR` in the same query degrades performance
+- Range queries (e.g., `a > b`) impact performance
+- Results are limited to the first 1000 hits
+
+## System Object Queries (SystemObjectMgr)
+
+For querying system objects other than customers (e.g., SitePreferences, catalogs):
+
+```javascript
+var SystemObjectMgr = require('dw/object/SystemObjectMgr');
+
+// Query system objects
+var results = SystemObjectMgr.querySystemObjects(
+    'Profile',
+    'custom.loyaltyTier = {0}',
+    'lastLoginTime desc',
+    'Gold'
+);
+
+while (results.hasNext()) {
+    var obj = results.next();
+    // Process
+}
+results.close();
+```
+
+**Note:** For customer profiles specifically, prefer `CustomerMgr.searchProfiles` or `CustomerMgr.processProfiles` over `SystemObjectMgr.querySystemObjects`—they use the search index and perform significantly better.
+
+## Database-Intensive APIs to Avoid
+
+These APIs hit the database directly and are expensive on high-traffic pages. Replace them with index-friendly alternatives. See [Performance-Critical APIs](references/PERFORMANCE-APIS.md) for the complete list with impact details.
+
+| Avoid (Database-Intensive) | Use Instead (Index-Friendly) |
+|----------------------------|------------------------------|
+| `Category.getProducts()` / `getOnlineProducts()` | `ProductSearchModel.setCategoryID()` |
+| `ProductMgr.queryAllSiteProducts()` | `ProductSearchModel.search()` |
+| `Product.getVariants()` / `getVariationModel()` | `ProductSearchHit` methods |
+| `Product.getPriceModel()` (in loops) | `ProductSearchHit.getMinPrice()` / `getMaxPrice()` |
+| `CustomerMgr.queryProfiles()` | `CustomerMgr.searchProfiles()` or `processProfiles()` |
+
+## Related Skills
+
+- `b2c-ordering` skill — Order lifecycle, status transitions, creation flows
+- `b2c-custom-objects` skill — Custom object CRUD, OCAPI search queries
+
+## Best Practices
+
+### Do
+
+- **Always close iterators** — unclosed iterators leak resources (`results.close()`)
+- **Page results** — use `PagingModel` or limit result counts; never load unbounded result sets
+- **Put all filtering in the query** — don't post-process or filter results in custom code
+- **Use index-backed APIs** — `ProductSearchModel`, `searchOrders`, `searchProfiles` for storefront pages
+- **Use `processProfiles`** for batch customer operations in jobs (optimized memory)
+- **Limit page size** — maximum ~120 products per page for search result pages
+- **Use `setOrderableProductsOnly(true)`** — to filter unavailable products at the search level
+
+### Don't
+
+- **Don't iterate over product variants on search result pages** — use `ProductSearchHit` methods instead
+- **Don't post-process search results** — all criteria must go into the query for efficient execution
+- **Don't use `queryAllSiteProducts()`** on storefront pages — it bypasses the search index
+- **Don't combine AND + OR** in customer queries — it degrades performance
+- **Don't rely on getting more than 1000 results** — search APIs cap at 1000 hits
+- **Don't call database-intensive APIs on high-traffic pages** — category pages, search results, PDPs, and homepage
+
+### Job-Specific Guidelines
+
+- Use `processProfiles` over `queryProfiles` for large customer data sets
+- Design loop logic so memory consumption doesn't grow with result set size
+- Keep only the currently processed object in memory; don't retain references
+- Stream data to files regularly; don't build large structures in memory
+- Limit transaction size to under 1000 modified business objects
+
+## Detailed References
+
+- [Performance-Critical APIs](references/PERFORMANCE-APIS.md) — full list of index-friendly vs database-intensive APIs