@salesforce/b2c-cli 2.3.1 → 2.5.0

package/content/guidance/b2c/b2c-custom-objects/references/OCAPI-SEARCH.md

@@ -0,0 +1,298 @@
+# OCAPI Custom Object Search Reference
+
+Full reference for searching custom objects via OCAPI Data API.
+
+## Search Endpoint
+
+```http
+POST /s/-/dw/data/v{version}/custom_objects_search/{object_type}
+Authorization: Bearer {token}
+Content-Type: application/json
+```
+
+## Request Structure
+
+```json
+{
+    "query": { },
+    "select": "(**)",
+    "expand": [],
+    "sorts": [{ "field": "creation_date", "sort_order": "desc" }],
+    "start": 0,
+    "count": 25
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `query` | Yes | Search query object |
+| `select` | No | Fields to return (`(**)` for all) |
+| `expand` | No | Related objects to expand |
+| `sorts` | No | Sort order array |
+| `start` | No | Pagination offset (default: 0) |
+| `count` | No | Results per page (default: 25, max: 200) |
+
+## Query Types
+
+### Term Query (Exact Match)
+
+```json
+{
+    "query": {
+        "term_query": {
+            "fields": ["c_status"],
+            "operator": "is",
+            "values": ["active"]
+        }
+    }
+}
+```
+
+`fields` is a required array, and `operator` is required. `values`, when used, is an array;
+omit it for `is_null` and `is_not_null`. Supported operators:
+- `is`: Exact match
+- `one_of`: Match any value in array
+- `is_null`: Check for null
+- `is_not_null`: Check for non-null
+- `less`, `greater`: Comparisons
+- `not_in`: Exclude values
+- `neq`: Not equal
+
+```json
+{
+    "term_query": {
+        "fields": ["c_priority"],
+        "operator": "greater",
+        "values": [5]
+    }
+}
+```
+
+```json
+{
+    "term_query": {
+        "fields": ["c_status"],
+        "operator": "one_of",
+        "values": ["active", "pending"]
+    }
+}
+```
+
+### Text Query (Full-Text Search)
+
+```json
+{
+    "query": {
+        "text_query": {
+            "fields": ["c_name", "c_description"],
+            "search_phrase": "test product"
+        }
+    }
+}
+```
+
+### Range Filter
+
+There is no `range_query`. Ranges are expressed as a `range_filter` inside a `filtered_query`:
+
+```json
+{
+    "query": {
+        "filtered_query": {
+            "query": { "match_all_query": {} },
+            "filter": {
+                "range_filter": {
+                    "field": "c_count",
+                    "from": 1,
+                    "to": 100,
+                    "from_inclusive": true,
+                    "to_inclusive": false
+                }
+            }
+        }
+    }
+}
+```
+
+### Boolean Query
+
+Combine multiple queries:
+
+```json
+{
+    "query": {
+        "bool_query": {
+            "must": [
+                { "term_query": { "fields": ["c_isActive"], "operator": "is", "values": [true] } },
+                { "term_query": { "fields": ["c_type"], "operator": "is", "values": ["premium"] } }
+            ],
+            "should": [
+                { "term_query": { "fields": ["c_priority"], "operator": "greater", "values": [5] } }
+            ],
+            "must_not": [
+                { "term_query": { "fields": ["c_status"], "operator": "is", "values": ["deleted"] } }
+            ]
+        }
+    }
+}
+```
+
+| Clause | Description |
+|--------|-------------|
+| `must` | All conditions must match (AND) |
+| `should` | At least one should match (OR) |
+| `must_not` | None of these should match (NOT) |
+
+### Match All Query
+
+```json
+{
+    "query": {
+        "match_all_query": {}
+    }
+}
+```
+
+### Filtered Query
+
+Combine query with filter (filter doesn't affect scoring):
+
+```json
+{
+    "query": {
+        "filtered_query": {
+            "query": {
+                "text_query": {
+                    "fields": ["c_name"],
+                    "search_phrase": "test"
+                }
+            },
+            "filter": {
+                "term_filter": {
+                    "field": "c_isActive",
+                    "operator": "is",
+                    "values": [true]
+                }
+            }
+        }
+    }
+}
+```
+
+### Nested Query
+
+Query nested objects:
+
+```json
+{
+    "query": {
+        "nested_query": {
+            "path": "c_addresses",
+            "query": {
+                "term_query": {
+                    "fields": ["c_addresses.city"],
+                    "operator": "is",
+                    "values": ["Boston"]
+                }
+            }
+        }
+    }
+}
+```
+
+## Sorting
+
+```json
+{
+    "sorts": [
+        { "field": "creation_date", "sort_order": "desc" },
+        { "field": "c_priority", "sort_order": "asc" }
+    ]
+}
+```
+
+| Sort Order | Description |
+|------------|-------------|
+| `asc` | Ascending (A-Z, 0-9, oldest first) |
+| `desc` | Descending (Z-A, 9-0, newest first) |
+
+## Field Selection
+
+```json
+{
+    "select": "(c_name, c_status, creation_date)"
+}
+```
+
+- `(**)` - All fields (default)
+- `(field1, field2)` - Specific fields only
+
+## Response Structure
+
+This example assumes `MyType` defines a string key attribute named `customObjectId`.
+
+```json
+{
+    "count": 1,
+    "hits": [
+        {
+            "key_property": "customObjectId",
+            "key_value_string": "key1",
+            "object_type": "MyType",
+            "c_name": "Test Object",
+            "c_status": "active"
+        }
+    ],
+    "query": { "match_all_query": {} },
+    "select": "(**)",
+    "start": 0,
+    "total": 1
+}
+```
+
+## Pagination Example
+
+```bash
+# First page
+curl -X POST ".../custom_objects_search/MyType" \
+  -d '{"query":{"match_all_query":{}},"start":0,"count":25}'
+
+# Second page
+curl -X POST ".../custom_objects_search/MyType" \
+  -d '{"query":{"match_all_query":{}},"start":25,"count":25}'
+```
+
+## Complex Query Example
+
+Find active premium configs modified in the last 7 days:
+
+```json
+{
+    "query": {
+        "bool_query": {
+            "must": [
+                { "term_query": { "fields": ["c_isActive"], "operator": "is", "values": [true] } },
+                { "term_query": { "fields": ["c_tier"], "operator": "is", "values": ["premium"] } },
+                {
+                    "term_query": {
+                        "fields": ["last_modified"],
+                        "operator": "greater",
+                        "values": ["2024-01-08T00:00:00.000Z"]
+                    }
+                }
+            ]
+        }
+    },
+    "sorts": [{ "field": "last_modified", "sort_order": "desc" }],
+    "count": 50
+}
+```
+
+## Error Handling
+
+| Status | Description |
+|--------|-------------|
+| 400 | Invalid query syntax |
+| 401 | Missing or invalid token |
+| 403 | Insufficient permissions |
+| 404 | Custom object type not found |

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

@@ -0,0 +1,242 @@
+---
+name: b2c-forms
+description: Build forms with validation in B2C Commerce using SFRA patterns. Use this skill whenever the user needs to create a storefront form (checkout, registration, profile edit, address, contact), define form fields in XML, handle form submission in a controller, add field validation rules, or render forms in ISML templates. Also use when they mention form XML definitions, server.forms.getForm, form groups/actions/lists, or CSRF protection on form posts — even if they just say "I need a registration form" or "add validation to checkout".
+---
+
+# Forms Skill
+
+This skill guides you through creating forms with validation in Salesforce B2C Commerce using the SFRA patterns.
+
+## Overview
+
+B2C Commerce forms consist of three parts:
+
+1. **Form Definition** - XML file defining fields, validation, and actions
+2. **Controller Logic** - Server-side form handling and processing
+3. **Template** - ISML template rendering the HTML form
+
+## File Location
+
+Forms are defined in the cartridge's `forms` directory:
+
+```
+/my-cartridge
+    /cartridge
+        /forms
+            /default              # Default locale
+                profile.xml
+                contact.xml
+            /de_DE               # German-specific (optional)
+                address.xml
+```
+
+## Form Definition (XML)
+
+### Basic Structure
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
+    <field formid="email" label="form.email.label" type="string"
+           mandatory="true" max-length="50"
+           regexp="^[\w.%+-]+@[\w.-]+\.\w{2,6}$"
+           parse-error="form.email.invalid"/>
+
+    <field formid="password" label="form.password.label" type="string"
+           mandatory="true" min-length="8" max-length="255"
+           missing-error="form.password.required"/>
+
+    <field formid="rememberMe" label="form.remember.label" type="boolean"/>
+
+    <action formid="submit" valid-form="true"/>
+    <action formid="cancel" valid-form="false"/>
+</form>
+```
+
+### Field Types
+
+| Type | Description | HTML Input |
+|------|-------------|------------|
+| `string` | Text input | `<input type="text">` |
+| `integer` | Whole number | `<input type="number">` |
+| `number` | Decimal number | `<input type="number">` |
+| `boolean` | Checkbox | `<input type="checkbox">` |
+| `date` | Date value | `<input type="date">` |
+
+### Key Field Attributes
+
+| Attribute | Purpose | Example |
+|-----------|---------|---------|
+| `formid` | Field identifier (required) | `formid="email"` |
+| `label` | Resource key for label | `label="form.email.label"` |
+| `type` | Data type (required) | `type="string"` |
+| `mandatory` | Required field | `mandatory="true"` |
+| `max-length` | Max string length | `max-length="100"` |
+| `min-length` | Min string length | `min-length="8"` |
+| `regexp` | Validation pattern | `regexp="^\d{5}$"` |
+
+### Validation Error Messages
+
+| Attribute | When Triggered |
+|-----------|----------------|
+| `missing-error` | Mandatory field is empty |
+| `parse-error` | Value doesn't match regexp or type |
+| `range-error` | Value outside min/max range |
+| `value-error` | General validation failure |
+
+See [Form XML Reference](references/FORM-XML.md) for complete field attributes, groups, lists, and validation patterns.
+
+## Controller Logic (SFRA)
+
+### Rendering a Form
+
+```javascript
+'use strict';
+
+var server = require('server');
+var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
+
+server.get('Show',
+    csrfProtection.generateToken,
+    function (req, res, next) {
+        var form = server.forms.getForm('profile');
+        form.clear();  // Reset previous values
+
+        res.render('account/profile', {
+            profileForm: form
+        });
+        next();
+    }
+);
+
+module.exports = server.exports();
+```
+
+### Processing Form Submission
+
+```javascript
+server.post('Submit',
+    server.middleware.https,
+    csrfProtection.validateAjaxRequest,
+    function (req, res, next) {
+        var form = server.forms.getForm('profile');
+
+        if (!form.valid) {
+            res.json({
+                success: false,
+                fields: getFormErrors(form)
+            });
+            return next();
+        }
+
+        // Access form values
+        var email = form.email.value;
+        var firstName = form.firstName.value;
+
+        // Process and save data
+        this.on('route:BeforeComplete', function () {
+            var Transaction = require('dw/system/Transaction');
+            Transaction.wrap(function () {
+                customer.profile.email = email;
+                customer.profile.firstName = firstName;
+            });
+        });
+
+        res.json({ success: true });
+        next();
+    }
+);
+
+function getFormErrors(form) {
+    var errors = {};
+    Object.keys(form).forEach(function (key) {
+        if (form[key] && form[key].error) {
+            errors[key] = form[key].error;
+        }
+    });
+    return errors;
+}
+```
+
+### Prepopulating Forms
+
+```javascript
+server.get('Edit', function (req, res, next) {
+    var form = server.forms.getForm('profile');
+    form.clear();
+
+    var profile = req.currentCustomer.profile;
+    form.firstName.value = profile.firstName;
+    form.lastName.value = profile.lastName;
+    form.email.value = profile.email;
+
+    res.render('account/editProfile', { profileForm: form });
+    next();
+});
+```
+
+## Template (ISML)
+
+### Basic Form Template
+
+```html
+<form action="${pdict.actionUrl}" method="POST" name="profile-form"
+      class="form-horizontal" data-action="${URLUtils.url('Profile-Submit')}">
+
+    <!-- CSRF Token -->
+    <input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>
+
+    <div class="form-group ${pdict.profileForm.email.mandatory ? 'required' : ''}">
+        <label for="email" class="form-control-label">
+            ${Resource.msg('form.email.label', 'forms', null)}
+        </label>
+        <input type="email"
+               id="email"
+               name="email"
+               class="form-control ${pdict.profileForm.email.error ? 'is-invalid' : ''}"
+               value="${pdict.profileForm.email.value || ''}"
+               <isif condition="${pdict.profileForm.email.mandatory}">required</isif>
+               maxlength="${pdict.profileForm.email.maxLength || 50}"/>
+        <isif condition="${pdict.profileForm.email.error}">
+            <div class="invalid-feedback">${pdict.profileForm.email.error}</div>
+        </isif>
+    </div>
+
+    <button type="submit" class="btn btn-primary">
+        ${Resource.msg('button.submit', 'forms', null)}
+    </button>
+</form>
+```
+
+## Localization
+
+Form labels and errors use resource bundles:
+
+**forms.properties:**
+```properties
+form.email.label=Email Address
+form.email.required=Email is required
+form.email.invalid=Please enter a valid email address
+form.password.label=Password
+button.submit=Submit
+```
+
+**forms_de_DE.properties:**
+```properties
+form.email.label=E-Mail-Adresse
+form.email.required=E-Mail ist erforderlich
+```
+
+## Best Practices
+
+1. **Always use CSRF protection** for form submissions
+2. **Clear forms** before displaying to reset state
+3. **Use resource keys** for labels and errors (localization)
+4. **Validate server-side** even with client-side validation
+5. **Use `route:BeforeComplete`** for database operations
+6. **Return JSON** for AJAX form submissions
+
+## Detailed Reference
+
+For comprehensive form patterns:
+- [Form XML Reference](references/FORM-XML.md) - Complete XML schema, validation patterns, and examples