@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/b2c/b2c-custom-api-development/references/CONTRACT.md

@@ -0,0 +1,142 @@
+# API Contract Reference (schema.yaml)
+
+## Full Schema Example
+
+```yaml
+openapi: 3.0.0
+info:
+  version: 1.0.0                      # API version (1.0.0 becomes v1 in URL)
+  title: My Custom API
+components:
+  securitySchemes:
+    ShopperToken:                     # For Shopper APIs — always site-scoped (requires siteId)
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
+          scopes:
+            c_my_scope: Description of my scope
+    AmOAuth2:                         # For Admin APIs — siteId optional (site or org context)
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
+          scopes:
+            c_my_admin_scope: Description of my admin scope
+  parameters:
+    siteId:
+      name: siteId
+      in: query
+      required: true
+      schema:
+        type: string
+        minLength: 1
+    locale:
+      name: locale
+      in: query
+      required: false
+      schema:
+        type: string
+        minLength: 1
+paths:
+  /my-endpoint:
+    get:
+      summary: Get something
+      operationId: getMyData         # Must match function name in script
+      parameters:
+        - $ref: '#/components/parameters/siteId'
+        - in: query
+          name: c_my_param           # Custom params must start with c_
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+security:
+  - ShopperToken: ['c_my_scope']     # Global security (or per-operation)
+```
+
+## Contract Requirements
+
+> Illustrative validation rules; confirm current OpenAPI contract requirements, scope naming constraints, and schema validation rules with `b2c docs read commerce-api/custom-api-components-references`.
+
+- **Version:** Defined in `info.version`, transformed to URL version (e.g., `1.0.1` becomes `v1`)
+- **Security Scheme:** Use `ShopperToken` for Shopper APIs or `AmOAuth2` for Admin APIs
+- **Custom Scopes:** Must start with `c_`, contain only alphanumeric/hyphen/period/underscore, max 25 chars
+- **Parameters:** All request parameters must be defined; custom params must have `c_` prefix
+- **System Parameters:** `siteId` and `locale` must have `type: string` and `minLength: 1`
+- **No additionalProperties:** The `additionalProperties` attribute is not allowed in request body schemas
+
+## Shopper vs Admin APIs
+
+> Illustrative operational limits and activity types; confirm current runtime quotas, max body sizes, and timeout values with `b2c docs read commerce-api/custom-apis`.
+
+| Aspect | Shopper API | Admin API |
+|--------|-------------|-----------|
+| Security Scheme | `ShopperToken` | `AmOAuth2` |
+| `siteId` Parameter | Required (always site-scoped) | Optional — see "Admin API call contexts" below |
+| Max Runtime | 10 seconds | 60 seconds |
+| Max Request Body | 5 MiB | 20 MB |
+| Activity Type | STOREFRONT | BUSINESS_MANAGER |
+
+### Admin API call contexts
+
+Unlike Shopper APIs, Admin APIs (`AmOAuth2`) can be invoked in either a storefront site context or the Business Manager / organization context. The `siteId` parameter selects which:
+
+| Context | `siteId` value | Cartridge path used to resolve `rest-apis/` |
+|---|---|---|
+| Storefront site context | A real site ID (e.g. `RefArch`) | That **site's** cartridge path |
+| Organization / Business Manager context | The literal value `Sites-Site` | The **Business Manager** cartridge path |
+| Organization / Business Manager context | `siteId` omitted | The **Business Manager** cartridge path |
+
+`Sites-Site` is not a real storefront — it's the system-defined site identifier the platform uses for BM / org-level operations. Passing `siteId=Sites-Site` is the explicit way to invoke an Admin Custom API against the BM context; omitting `siteId` resolves the same way.
+
+If you want the same Admin API to work in both contexts, declare `siteId` as an *optional* parameter (drop `required: true`). The cartridge containing your `rest-apis/` folder must be on whichever cartridge path corresponds to how the caller invokes it — the storefront site's path for storefront-`siteId` calls, and the BM cartridge path for `Sites-Site` / omitted-`siteId` calls.
+
+## Path Parameter Example
+
+```yaml
+paths:
+  /items/{itemId}:
+    get:
+      operationId: getItem
+      parameters:
+        - $ref: '#/components/parameters/siteId'
+        - in: path
+          name: itemId
+          required: true
+          schema:
+            type: string
+```
+
+## Request Body Example (POST/PUT/PATCH)
+
+```yaml
+paths:
+  /items:
+    post:
+      operationId: createItem
+      parameters:
+        - $ref: '#/components/parameters/siteId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                c_customField:
+                  type: string
+      responses:
+        '201':
+          description: Created
+```

package/content/guidance/b2c/b2c-custom-api-development/references/IMPLEMENTATION.md

@@ -0,0 +1,153 @@
+# Implementation Reference (script.js)
+
+## Complete Implementation Example
+
+> Illustrative Script API integration; confirm current Custom API request handling, path parameter access, and response patterns with `b2c docs read commerce-api/custom-api-components-references` and Script API docs for `dw.system.Request`.
+
+```javascript
+var RESTResponseMgr = require('dw/system/RESTResponseMgr');
+
+exports.getMyData = function() {
+    // Get query parameters
+    var myParam = request.getHttpParameterMap().get('c_my_param').getStringValue();
+
+    // Get path parameters (for paths like /items/{itemId})
+    var itemId = request.getSCAPIPathParameters().get('itemId');
+
+    // Get request body (for POST/PUT/PATCH)
+    var requestBody = JSON.parse(request.httpParameterMap.requestBodyAsString);
+
+    // Business logic here...
+    var result = {
+        data: 'my data',
+        param: myParam
+    };
+
+    // Return success response
+    RESTResponseMgr.createSuccess(result).render();
+};
+exports.getMyData.public = true;  // Required: mark function as public
+
+// Error response example
+exports.getMyDataWithError = function() {
+    RESTResponseMgr
+        .createError(404, 'not-found', 'Resource Not Found', 'The requested resource was not found.')
+        .render();
+};
+exports.getMyDataWithError.public = true;
+```
+
+## Best Practices
+
+- Always return JSON format responses
+- Use RFC 9457 error format with at least the `type` field
+- Mark all exported functions with `.public = true`
+- Handle errors gracefully to avoid circuit breaker activation
+- GET requests cannot commit transactions
+
+## Caching Responses
+
+Enable Page Caching for the site, then use:
+
+```javascript
+// Cache for 60 seconds
+response.setExpires(Date.now() + 60000);
+
+// Personalized caching
+response.setVaryBy('price_promotion');
+```
+
+## Remote Includes
+
+Include responses from other SCAPI endpoints:
+
+```javascript
+var include = dw.system.RESTResponseMgr.createScapiRemoteInclude(
+    'custom', 'other-api', 'v1', 'endpointPath',
+    dw.web.URLParameter('siteId', 'MySite')
+);
+
+var response = {
+    data: 'my data',
+    included: [include]
+};
+RESTResponseMgr.createSuccess(response).render();
+```
+
+## External Service Calls
+
+When calling external services via `LocalServiceRegistry.createService()`, configure the service in Business Manager or import via site archive:
+
+```javascript
+var LocalServiceRegistry = require('dw/svc/LocalServiceRegistry');
+
+var service = LocalServiceRegistry.createService('my.external.api', {
+    createRequest: function(svc, args) {
+        svc.setRequestMethod('GET');
+        svc.addHeader('Authorization', 'Bearer ' + args.token);
+        return null;
+    },
+    parseResponse: function(svc, client) {
+        return JSON.parse(client.text);
+    }
+});
+
+var result = service.call({ token: 'my-token' });
+```
+
+See `b2c:b2c-webservices` skill for service configuration and services.xml format.
+
+## services.xml Example
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<services xmlns="http://www.demandware.com/xml/impex/services/2014-09-26">
+
+    <service-credential service-credential-id="my.external.api">
+        <url>https://api.example.com/v1</url>
+    </service-credential>
+
+    <service-profile service-profile-id="my.external.api.profile">
+        <timeout-millis>5000</timeout-millis>
+        <rate-limit-enabled>false</rate-limit-enabled>
+        <cb-enabled>true</cb-enabled>
+        <cb-calls>5</cb-calls>
+        <cb-millis>10000</cb-millis>
+    </service-profile>
+
+    <service service-id="my.external.api">
+        <service-type>HTTP</service-type>
+        <enabled>true</enabled>
+        <log-prefix>MYAPI</log-prefix>
+        <comm-log-enabled>true</comm-log-enabled>
+        <profile-id>my.external.api.profile</profile-id>
+        <credential-id>my.external.api</credential-id>
+    </service>
+
+</services>
+```
+
+Import with: `b2c job import ./my-services-folder`
+
+## HTTP Methods Supported
+
+- GET (no transaction commits)
+- POST
+- PUT
+- PATCH
+- DELETE
+- HEAD
+- OPTIONS
+
+## Circuit Breaker Protection
+
+> Illustrative thresholds; confirm current circuit breaker behavior, error rate calculations, and timeout values with `b2c docs read commerce-api/custom-api-circuit-breaker`.
+
+Custom APIs have a circuit breaker that blocks requests when error rate exceeds 50%:
+
+1. Circuit opens after 50+ errors in 100 requests
+2. Requests return 503 for 60 seconds
+3. Circuit enters half-open state, testing next 10 requests
+4. If >5 fail, circuit reopens; otherwise closes
+
+**Prevention:** Write robust code with error handling and avoid long-running remote calls.

package/content/guidance/b2c/b2c-custom-api-development/references/TESTING.md

@@ -0,0 +1,118 @@
+# Testing Custom APIs
+
+## Prerequisites for Testing
+
+Before testing a Shopper API with custom scopes, ensure you have a SLAS client configured with those scopes:
+
+```bash
+# Create a test client with your custom scope (replace c_my_scope with your scope)
+b2c slas client create \
+  --tenant-id zzpq_013 \
+  --channels RefArch \
+  --default-scopes \
+  --scopes "c_my_scope" \
+  --redirect-uri http://localhost:3000/callback \
+  --json
+
+# Save the client_id and client_secret from the output
+```
+
+**Warning:** Use `--scopes` (plural) for client scopes, NOT `--scope` (singular).
+
+See `b2c-cli:b2c-slas` skill for more options.
+
+## Get a Shopper Token (Private Client)
+
+> Illustrative SLAS token endpoint and grant flow; confirm current SLAS endpoint URLs, grant types, and parameter requirements with `b2c docs read commerce-api/custom-api-authentication`.
+
+Using a private SLAS client with client credentials grant:
+
+```bash
+# Set your credentials
+SHORTCODE="your-short-code" # see b2c-cli:b2c-config skill to find this value
+ORG="f_ecom_xxxx_xxx"
+SLAS_CLIENT_ID="your-client-id"
+SLAS_CLIENT_SECRET="your-client-secret"
+SITE="RefArch" # b2c-cli:b2c-sites skill to find site IDs
+
+# Get access token
+TOKEN=$(curl -s "https://$SHORTCODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/token" \
+    -u "$SLAS_CLIENT_ID:$SLAS_CLIENT_SECRET" \
+    -d "grant_type=client_credentials&channel_id=$SITE" | jq -r '.access_token')
+
+echo $TOKEN
+```
+
+## Call Your Custom API
+
+```bash
+# Call the Custom API endpoint
+curl -s "https://$SHORTCODE.api.commercecloud.salesforce.com/custom/my-api/v1/organizations/$ORG/my-endpoint?siteId=$SITE" \
+    -H "Authorization: Bearer $TOKEN" | jq
+```
+
+## Testing Admin APIs
+
+> Illustrative Account Manager OAuth scope requirements; confirm current Admin API authorization model, tenant scope format, and scope combination rules with `b2c docs read commerce-api/custom-api-authentication`.
+
+For Admin APIs (`AmOAuth2`), obtain a token from Account Manager with the **two required scope types**:
+
+1. The **tenant scope** `SALESFORCE_COMMERCE_API:<tenant_id>` (grants access to the tenant), and
+2. Your **custom Admin scope(s)** `c_my_admin_scope` (as declared in `schema.yaml`).
+
+> **Important:** Unlike the SCAPI subcommands (`b2c scapi custom status`, `b2c scapi schemas list`), which inject the `SALESFORCE_COMMERCE_API:<tenant_id>` scope for you, a raw token request (`b2c auth token` or curl) sends **only** the scopes you pass. Omitting the tenant scope yields a token that 403s against the Admin API.
+
+### Get an Admin Token via the CLI (recommended)
+
+`b2c auth token` accepts multiple scopes — repeat `--auth-scope` or pass a comma-separated list. List the tenant scope **and** your custom scope(s):
+
+```bash
+TENANT_ID="zzpq_013"
+
+# Repeatable flag form
+TOKEN=$(b2c auth token \
+    --auth-scope "SALESFORCE_COMMERCE_API:$TENANT_ID" \
+    --auth-scope c_my_admin_scope)
+
+# Comma-separated form (equivalent)
+TOKEN=$(b2c auth token --auth-scope "SALESFORCE_COMMERCE_API:$TENANT_ID,c_my_admin_scope")
+
+# Call Admin API (no siteId for org context)
+curl -s "https://$SHORTCODE.api.commercecloud.salesforce.com/custom/my-admin-api/v1/organizations/$ORG/my-endpoint" \
+    -H "Authorization: Bearer $TOKEN" | jq
+```
+
+### Get an Admin Token via curl
+
+```bash
+AM_CLIENT_ID="your-am-client-id"
+AM_CLIENT_SECRET="your-am-client-secret"
+TENANT_ID="zzpq_013"
+
+# The scope MUST include the tenant scope plus your custom Admin scope(s)
+TOKEN=$(curl -s "https://account.demandware.com/dwsso/oauth2/access_token" \
+    -u "$AM_CLIENT_ID:$AM_CLIENT_SECRET" \
+    -d "grant_type=client_credentials" \
+    --data-urlencode "scope=SALESFORCE_COMMERCE_API:$TENANT_ID c_my_admin_scope" | jq -r '.access_token')
+
+# Call Admin API (no siteId)
+curl -s "https://$SHORTCODE.api.commercecloud.salesforce.com/custom/my-admin-api/v1/organizations/$ORG/my-endpoint" \
+    -H "Authorization: Bearer $TOKEN" | jq
+```
+
+## Testing Tips
+
+- Use `b2c slas client list` to find existing SLAS clients
+- Use `b2c slas client create --default-scopes --scopes "c_my_scope"` to create a test client
+- Check logs with `b2c logs get` if requests fail
+- Verify endpoint registration with `b2c scapi custom status --tenant-id <tenant>`
+
+## Common Test Failures
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| 400 Bad Request | Missing or invalid parameter | Check schema.yaml parameter definitions |
+| 401 Unauthorized | Invalid/expired token | Get a fresh token |
+| 403 Forbidden | Missing scope | Verify scope in token matches contract. For Admin APIs, confirm the token includes **both** `SALESFORCE_COMMERCE_API:<tenant_id>` and your custom scope(s) |
+| 404 Not Found | Endpoint not registered | Run `b2c scapi custom status` |
+| 500 Internal Error | Script error | Check `b2c logs get --level ERROR` |

package/content/guidance/b2c/b2c-custom-caches/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: b2c-custom-caches
+description: Implement custom caching with CacheMgr, caches.json definitions, and cache region configuration. Use this skill whenever the user needs to cache expensive computations or API responses server-side, define cache regions with TTL and size limits, invalidate cache entries, or debug disappearing cache data. Also use when optimizing script performance with application-level caching -- even if they just say 'cache this data' or 'my cached values keep disappearing'.
+---
+
+# B2C Custom Caches
+
+Custom caches improve code performance by storing data that is expensive to calculate, takes a long time to retrieve, or is accessed frequently. Caches are defined in JSON files within cartridges and accessed via the Script API.
+
+## When to Use Custom Caches
+
+| Use Case | Example |
+|----------|---------|
+| Expensive calculations | Check if any variation product is on sale for base product display |
+| External system responses | Cache in-store availability or prices from external APIs |
+| Configuration settings | Store configuration data from JSON files or external sources |
+| Frequently accessed data | Product attributes, category data, site preferences |
+
+## Limitations
+
+| Constraint | Value |
+|------------|-------|
+| Total memory per app server | ~20 MB for all custom caches |
+| Max caches per code version | 100 |
+| Max entry size | 128 KB |
+| Supported value types | Primitives, arrays, plain objects, `null` (not `undefined`) |
+| Cross-server sync | None (caches are per-application-server) |
+
+## Defining a Custom Cache
+
+### File Structure
+
+```
+my_cartridge/
+├── package.json       # References caches.json
+└── caches.json        # Cache definitions
+```
+
+### package.json
+
+Add a `caches` entry pointing to the cache definition file:
+
+```json
+{
+  "name": "my_cartridge",
+  "caches": "./caches.json"
+}
+```
+
+### caches.json
+
+Define caches with unique IDs and optional expiration:
+
+```json
+{
+  "caches": [
+    {
+      "id": "ProductAttributeCache"
+    },
+    {
+      "id": "ExternalPriceCache",
+      "expireAfterSeconds": 300
+    },
+    {
+      "id": "SiteConfigCache",
+      "expireAfterSeconds": 60
+    }
+  ]
+}
+```
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `id` | Yes | Unique ID across all cartridges in code version |
+| `expireAfterSeconds` | No | Maximum seconds an entry is retained |
+
+## Using Custom Caches
+
+### Script API Classes
+
+| Class | Description |
+|-------|-------------|
+| `dw.system.CacheMgr` | Entry point for accessing defined caches |
+| `dw.system.Cache` | Cache instance for storing and retrieving entries |
+
+### Basic Usage
+
+```javascript
+var CacheMgr = require('dw/system/CacheMgr');
+
+// Get a defined cache
+var cache = CacheMgr.getCache('ProductAttributeCache');
+
+// Get value (returns undefined if not found)
+var value = cache.get('myKey');
+
+// Store value directly
+cache.put('myKey', { data: 'value' });
+
+// Remove entry
+cache.invalidate('myKey');
+```
+
+### Recommended Pattern: get with Loader
+
+Use `get(key, loader)` to automatically populate the cache on miss:
+
+```javascript
+var CacheMgr = require('dw/system/CacheMgr');
+var Site = require('dw/system/Site');
+
+var cache = CacheMgr.getCache('SiteConfigCache');
+
+// Loader function called only on cache miss
+var config = cache.get(Site.current.ID + '_config', function() {
+    // Expensive operation - only runs if not cached
+    return loadConfigurationFromFile(Site.current);
+});
+```
+
+### Scoped Cache Keys
+
+Include scope identifiers in keys to separate entries by context:
+
+```javascript
+var CacheMgr = require('dw/system/CacheMgr');
+var Site = require('dw/system/Site');
+
+var cache = CacheMgr.getCache('ProductCache');
+
+// Site-scoped key
+var siteKey = Site.current.ID + '_' + productID;
+var productData = cache.get(siteKey, loadProductData);
+
+// Catalog-scoped key
+var catalogKey = 'catalog_' + catalogID + '_' + productID;
+var catalogData = cache.get(catalogKey, loadCatalogData);
+
+// Locale-scoped key
+var localeKey = request.locale + '_' + contentID;
+var content = cache.get(localeKey, loadLocalizedContent);
+```
+
+## Cache Methods
+
+| Method | Description |
+|--------|-------------|
+| `get(key)` | Returns cached value or `undefined` |
+| `get(key, loader)` | Returns cached value or calls loader, stores result |
+| `put(key, value)` | Stores value directly (overwrites existing) |
+| `invalidate(key)` | Removes entry for key |
+
+## Best Practices
+
+### Do
+
+- Use `get(key, loader)` pattern for automatic population
+- Include scope (site, catalog, locale) in cache keys
+- Set appropriate `expireAfterSeconds` for time-sensitive data
+- Handle cache misses gracefully (data may be evicted anytime)
+- Use descriptive cache IDs
+
+### Don't
+
+- Include personal user data in cache keys (keys may appear in logs)
+- Store Script API objects (only primitives and plain objects)
+- Rely on cache entries existing (no persistence guarantee)
+- Expect cross-server cache synchronization
+- Store `undefined` values (use `null` instead)
+
+## Cache Invalidation
+
+Caches are automatically cleared when:
+- Any file in the active code version changes
+- A new code version is activated
+- Data replication completes
+- Code replication completes
+
+Manual invalidation only affects the current application server:
+
+```javascript
+var cache = CacheMgr.getCache('MyCache');
+
+// Invalidate single entry (current app server only)
+cache.invalidate('myKey');
+
+// Storing undefined has same effect as invalidate
+cache.put('myKey', undefined);
+```
+
+## Common Patterns
+
+### Caching External API Responses
+
+```javascript
+var CacheMgr = require('dw/system/CacheMgr');
+var LocalServiceRegistry = require('dw/svc/LocalServiceRegistry');
+
+var priceCache = CacheMgr.getCache('ExternalPriceCache');
+
+function getExternalPrice(productID) {
+    return priceCache.get('price_' + productID, function() {
+        var service = LocalServiceRegistry.createService('PriceService', {
+            createRequest: function(svc, args) {
+                svc.setRequestMethod('GET');
+                svc.addParam('productId', args.productID);
+                return null;
+            },
+            parseResponse: function(svc, response) {
+                return JSON.parse(response.text);
+            }
+        });
+
+        var result = service.call({ productID: productID });
+        return result.ok ? result.object : null;
+    });
+}
+```
+
+### Caching Expensive Calculations
+
+```javascript
+var CacheMgr = require('dw/system/CacheMgr');
+
+var saleCache = CacheMgr.getCache('ProductSaleCache');
+
+function isProductOnSale(masterProduct) {
+    return saleCache.get('sale_' + masterProduct.ID, function() {
+        var variants = masterProduct.variants.iterator();
+        while (variants.hasNext()) {
+            var variant = variants.next();
+            if (isInPromotion(variant)) {
+                return true;
+            }
+        }
+        return false;
+    });
+}
+```
+
+### Configuration Cache with Site Scope
+
+```javascript
+var CacheMgr = require('dw/system/CacheMgr');
+var Site = require('dw/system/Site');
+var File = require('dw/io/File');
+var FileReader = require('dw/io/FileReader');
+
+var configCache = CacheMgr.getCache('SiteConfigCache');
+
+function getSiteConfig() {
+    var siteID = Site.current.ID;
+
+    return configCache.get(siteID + '_config', function() {
+        var configFile = new File(File.IMPEX + '/src/config/' + siteID + '.json');
+        if (!configFile.exists()) {
+            return null;
+        }
+
+        var reader = new FileReader(configFile);
+        var content = reader.getString();
+        reader.close();
+
+        return JSON.parse(content);
+    });
+}
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Cache not found exception | Cache ID not defined in any caches.json | Add cache definition to caches.json |
+| Duplicate cache ID error | Same ID used in multiple cartridges | Use unique IDs across all cartridges |
+| Entry not stored | Value exceeds 128 KB limit | Reduce data size or cache subsets |
+| Entry not stored | Value contains Script API objects | Use only primitives and plain objects |
+| Unexpected cache misses | Different app server or cache cleared | Always handle misses gracefully |
+
+Check the custom error log and custom warn log for cache-related messages.