sfcc-dev-mcp 1.0.15 → 1.0.19

package/dist/ai-instructions/skills/sfcc-localization/references/PROPERTIES-ENCODING.md

@@ -0,0 +1,25 @@
+# Properties Encoding & Special Characters
+
+## Escaping
+
+```properties
+message.welcome=It''s a great day!
+error.cant=You can''t do that
+message.multiline=Line one\nLine two\nLine three
+store.name=Cafe1 du Nord
+```
+
+## UTF-8
+
+Always save `.properties` files as UTF-8 to preserve non-ASCII characters.
+
+```properties
+button.close=Schließen
+message.success=Réussi!
+store.name=店舗名
+```
+
+## Tips
+
+- Avoid `encoding="off"` unless data is trusted.
+- Keep translator comments near the keys they describe.

package/dist/ai-instructions/skills/sfcc-localization/references/RESOURCE-BUNDLES.md

@@ -0,0 +1,67 @@
+# Resource Bundles
+
+Core patterns for localization in SFCC.
+
+## Directory Structure
+
+```
+/cartridge
+  /templates/resources
+    account.properties
+    checkout.properties
+    /fr/account.properties
+    /fr/checkout.properties
+    /fr_CA/account.properties
+```
+
+## Property Format (UTF-8)
+
+```properties
+# Account (default)
+account.title=My Account
+account.greeting=Welcome back
+account.logout=Sign Out
+profile.firstName=First Name
+profile.save=Save Changes
+```
+
+```properties
+# Account (fr)
+account.title=Mon compte
+account.greeting=Bon retour
+account.logout=Se déconnecter
+profile.firstName=Prénom
+profile.save=Enregistrer les modifications
+```
+
+## Using Resources in Templates
+
+```html
+<h1>${Resource.msg('account.title', 'account', null)}</h1>
+<p>${Resource.msg('account.greeting', 'account', 'Welcome')}</p>
+<p>${Resource.msgf('cart.itemCount', 'cart', null, itemCount)}</p>
+```
+
+`Resource.msg(key, bundle, default)` uses key if missing and default is null.
+
+## Parameterized Messages
+
+```properties
+greeting.personalized=Hello, {0} {1}!
+order.confirmation=Order #{0} placed on {1}
+```
+
+```html
+${Resource.msgf('greeting.personalized', 'common', null, firstName, lastName)}
+```
+
+## Fallback Chain
+
+`fr_CA` → `fr` → default bundle. Place language-wide values in the language folder, country-specific in the locale folder.
+
+## Tips
+
+- Organize bundles by page/feature (account, checkout), not by language.
+- Keep keys descriptive: `account.profile.firstName` not `label1`.
+- Avoid string concatenation; use parameters.
+- Document context in comments for translators.

package/dist/ai-instructions/skills/sfcc-localization/references/STATIC-FILES.md

@@ -0,0 +1,23 @@
+# Static Files Localization
+
+Localize static assets when they contain text (images, PDFs); CSS/JS usually stay default.
+
+## Directory Structure
+
+```
+/cartridge/static
+  /default/images/buttons/submit.png
+  /fr/images/buttons/submit.png
+  /de/images/buttons/submit.png
+  /default/css/style.css
+  /default/js/main.js
+```
+
+## Usage
+
+```html
+<img src="${URLUtils.staticURL('/images/buttons/submit.png')}" alt="Submit"/>
+<link rel="stylesheet" href="${URLUtils.staticURL('/css/style.css')}"/>
+```
+
+SFCC resolves the locale-specific asset automatically when present.

package/dist/ai-instructions/skills/sfcc-localization/references/TESTING.md

@@ -0,0 +1,21 @@
+# Testing Localization
+
+## Pseudo-Localization
+
+Use a test bundle to surface hardcoded strings:
+
+```properties
+# pseudo.properties
+button.submit=[Submit]
+account.title=[My Account]
+```
+
+## Checklist
+
+- All visible text comes from resource bundles
+- Date/time formats use locale settings
+- Currency and numbers render with locale separators
+- Images with text have locale variants if needed
+- Email templates send in the correct language
+- JavaScript strings originate from bundles
+- Fallback chain behaves as expected (e.g., fr_CA → fr → default)

package/dist/{docs/best-practices/localserviceregistry.md → ai-instructions/skills/sfcc-localserviceregistry/SKILL.md}

@@ -1,39 +1,15 @@
+---
+name: sfcc-localserviceregistry
+description: Guide for creating server-to-server integrations in Salesforce B2C Commerce using LocalServiceRegistry. Use this when asked to integrate external APIs, create HTTP services, implement OAuth flows, or configure service credentials.
+---
+
 # SFCC B2C Commerce: LocalServiceRegistry Best Practices
 
 This guide provides a concise overview of best practices for creating server-to-server integrations in Salesforce B2C Commerce Cloud using the `dw.svc.LocalServiceRegistry`.
 
 ## 1. Core Architecture: Configuration and Code
 
-Integrations use a two-par5. Click **Apply** to save the new profile.
-
-### Step 3: Create the Service Definition (Tying It All Together)
-
-The Service Definition links the Credential and Profile to create the final, named service that you will call from your code.
-
-1. Navigate to **Administration > Operations > Services**.
-2. Ensure you are on the **Services** tab and click **New**.
-3. Fill in the following fields on the New Service page:
-   - **Name (ID)**: Enter the unique ID for the service. This ID must exactly match the one used in your `LocalServiceRegistry.createService()` call.
-     
-     **Best Practice**: Use a period-delimited pattern like `{cartridge}.{protocol}.{service}.{operation}` (e.g., `int_myapi.http.customer.get`). This structure automatically organizes your service logs into a helpful hierarchy.
-   
-   - **Service Type**: Select the protocol, typically HTTP for REST APIs.
-   
-   - **Mode**:
-     - **Live**: For making real calls to the external API.
-     - **Mocked**: For testing. This mode will invoke the `mockCall` or `mockFull` function in your script instead of making a network request.
-   
-   - **Credential**: Select the Service Credential you created in Step 1 from the dropdown list.
-   
-   - **Profile**: Select the Service Profile you configured in Step 2 from the dropdown list.
-   
-   - **Log Name Prefix**: (Optional but recommended) Enter a prefix (e.g., `myapi`) to create a dedicated log file for this service (`service-myapi-....log`), which simplifies debugging.
-   
-   - **Communication Log Enabled**: Check this box to log the full request and response data. This is useful for debugging but should be used with caution in production if sensitive data is being transmitted. Always implement a `filterLogMessage` callback in your script to redact sensitive information from these logs.
-
-4. Click **Apply** to save the service definition.
-
-Your service is now fully configured in the Business Manager and ready to be implemented and called from your SFRA cartridge code.rchitecture:
+Integrations use a two-part architecture:
 
 **Declarative Configuration (Business Manager)**: Defines the what, who, and how of the service call. This includes the endpoint, credentials, and operational policies like timeouts and circuit breakers.
 
@@ -65,6 +41,21 @@ The `createService` method takes a configuration object with the following core
 
 - **`mockFull(svc,...params)`**: Mocks the entire service call. No other callbacks are executed. Ideal for unit testing the consumer of the service (e.g., a controller).
 
+## 2.1 Understanding `dw.svc.Result` (What `service.call()` Returns)
+
+The Service Framework returns a `dw.svc.Result` object. Your calling code should branch on `result.ok` and also differentiate transport/config failures from HTTP/API failures.
+
+| Field | Meaning |
+|------|---------|
+| `ok` | `true` if the call succeeded and `parseResponse` did not error |
+| `status` | Typically `OK`, `ERROR`, or `SERVICE_UNAVAILABLE` |
+| `object` | Parsed value returned by `parseResponse` |
+| `error` / `errorMessage` | Error code/message (often HTTP status + message) |
+| `unavailableReason` | Why the framework refused to call (timeout, rate limit, circuit breaker, disabled, config issue) |
+| `mockResult` | Whether the response came from mock mode |
+
+**Practical rule**: treat `SERVICE_UNAVAILABLE` as a resilience signal (retry/fallback), and treat `ERROR` as a downstream/API problem (inspect HTTP status and body).
+
 ### Reusable Service Module Pattern
 
 Encapsulate all logic for an integration into a single script module. Use a singleton pattern to avoid re-creating the service definition on every call.
@@ -172,6 +163,46 @@ var myAPIService = LocalServiceRegistry.createService('int_myapi.http.customer',
     }
 });
 
+## 2.2 Production Safety Notes
+
+- Prefer `filterLogMessage` for any integration that may include secrets, tokens, passwords, or PII.
+- Keep `parseResponse` strict: if `client.statusCode >= 400`, throw an error so failures propagate through `result.ok === false`.
+- Use Business Manager service profiles for timeouts, rate limits, and circuit breaker behavior.
+- For comprehensive logging patterns including categories, custom log files, and log level checks, see **[sfcc-logging](../sfcc-logging/SKILL.md)**.
+
+## 2.3 HTTP Response Caching (Service Framework)
+
+For third-party APIs with stable responses (for short periods), you can enable response caching at the HTTP client level inside your service definition.
+
+### Enabling caching
+
+Enable caching inside `createRequest` (or later callbacks), after the client is initialized:
+
+```javascript
+createRequest: function (svc, operation, params) {
+    // Only access svc.client inside createRequest/parseResponse/etc.
+    // NOTE: TTL units depend on the underlying API you call; validate against your SFCC version docs.
+    svc.client.enableCaching(1000);
+
+    svc.setRequestMethod('GET');
+    // ... set URL/headers/body ...
+    return null;
+}
+```
+
+### Clearing the cache
+
+You can clear the HTTP client response cache in Business Manager:
+- **Administration → Operations → Service Maintenance**
+- Use the **Invalidate** action for **HTTP Client Response Cache**
+
+Constraints to design around:
+- Cache invalidation is typically **global** (not per-service).
+- Avoid caching error responses.
+- Cached calls can still affect service-level statistics (rate limiting/circuit breaker) depending on configuration.
+
+For broader cache strategy (page cache vs custom caches vs service caching), see **[sfcc-caching](../sfcc-caching/SKILL.md)**.
+
 // --- Public API ---
 module.exports = {
     OPERATION_GET_CUSTOMER: 'getCustomer',
@@ -181,6 +212,7 @@ module.exports = {
     }
 };
 ```
+
 ## 3. Practical Examples
 
 ### GET Request (SFRA Controller)
@@ -337,4 +369,6 @@ The Service Definition links the Credential and Profile to create the final, nam
 
    - **Credential**: Select the Service Credential you created in Step 1 from the dropdown list.
 
-4. Click **Apply** to save the service definition.Your service is now fully configured in the Business Manager and ready to be implemented and called from your SFRA cartridge code.
+4. Click **Apply** to save the service definition.
+
+Your service is now fully configured in the Business Manager and ready to be implemented and called from your SFRA cartridge code.

package/dist/ai-instructions/skills/sfcc-logging/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: sfcc-logging
+description: Guide for implementing logging in Salesforce B2C Commerce scripts
+---
+
+# Logging Skill
+
+This skill guides you through implementing logging in B2C Commerce using the Logger and Log classes.
+
+## Overview
+
+B2C Commerce provides a logging framework with:
+
+| Feature | Description |
+|---------|-------------|
+| **Log Levels** | debug, info, warn, error, fatal |
+| **Categories** | Organize logs by functional area |
+| **Custom Files** | Write to dedicated log files |
+| **NDC** | Nested Diagnostic Context for tracing |
+| **BM Configuration** | Enable/disable levels per category |
+
+## Log Levels
+
+| Level | Method | Description | Default State |
+|-------|--------|-------------|---------------|
+| `debug` | `debug()` | Detailed debugging information | Disabled (never on production) |
+| `info` | `info()` | General information | Disabled by default |
+| `warn` | `warn()` | Warning conditions | Always enabled |
+| `error` | `error()` | Error conditions | Always enabled |
+| `fatal` | `fatal()` | Critical failures | Always enabled, can send email |
+
+## Basic Logging
+
+### Using Logger (Static Methods)
+
+The `Logger` class provides static methods for quick logging:
+
+```javascript
+var Logger = require('dw/system/Logger');
+
+// Simple messages
+Logger.debug('Debug message');
+Logger.info('Info message');
+Logger.warn('Warning message');
+Logger.error('Error message');
+
+// Messages with parameters (Java MessageFormat syntax)
+Logger.info('Processing order {0} for customer {1}', orderNo, customerEmail);
+Logger.error('Failed to process {0}: {1}', productId, errorMessage);
+```
+
+### Using Log (Instance Methods)
+
+The `Log` class provides instance-based logging with categories:
+
+```javascript
+var Logger = require('dw/system/Logger');
+
+// Get logger for a category
+var log = Logger.getLogger('checkout');
+
+log.debug('Cart contents: {0}', JSON.stringify(cart));
+log.info('Checkout started for basket {0}', basketId);
+log.warn('Inventory low for product {0}', productId);
+log.error('Payment failed: {0}', errorMessage);
+log.fatal('Critical checkout failure: {0}', errorMessage);
+```
+
+## Categories
+
+Categories help organize and filter log messages:
+
+```javascript
+var Logger = require('dw/system/Logger');
+
+// Different categories for different areas
+var checkoutLog = Logger.getLogger('checkout');
+var paymentLog = Logger.getLogger('payment');
+var inventoryLog = Logger.getLogger('inventory');
+var integrationLog = Logger.getLogger('integration');
+
+// Use appropriate logger
+checkoutLog.info('Order {0} submitted', orderNo);
+paymentLog.info('Payment authorized: {0}', transactionId);
+inventoryLog.warn('Stock level below threshold for {0}', productId);
+integrationLog.error('API call failed: {0}', serviceName);
+```
+
+Categories are configured in Business Manager under **Administration > Operations > Custom Log Settings**.
+
+## Custom Named Log Files
+
+Write to dedicated log files instead of the standard custom log files:
+
+```javascript
+var Logger = require('dw/system/Logger');
+
+// Get logger with custom file prefix
+var orderExportLog = Logger.getLogger('export', 'orderexport');
+var feedLog = Logger.getLogger('feed', 'productfeed');
+
+// Messages go to custom-orderexport-*.log
+orderExportLog.info('Exporting order {0}', orderNo);
+
+// Messages go to custom-productfeed-*.log
+feedLog.info('Processing product {0}', productId);
+```
+
+### File Name Rules
+
+The `fileNamePrefix` parameter must follow these rules:
+
+| Rule | Requirement |
+|------|-------------|
+| Length | 3-25 characters |
+| Characters | a-z, A-Z, 0-9, `-`, `_` |
+| Start/End | Must start and end with alphanumeric |
+| Not allowed | Cannot start or end with `-` or `_` |
+
+### File Naming Pattern
+
+Custom log files follow this pattern:
+```
+custom-<prefix>-<hostname>-appserver-<date>.log
+```
+
+Example: `custom-orderexport-blade0-1-appserver-20240115.log`
+
+### Quota
+
+Maximum 200 different log file names per day per appserver.
+
+## Checking Log Level Status
+
+Check if a log level is enabled before expensive operations:
+
+```javascript
+var Logger = require('dw/system/Logger');
+var log = Logger.getLogger('myCategory');
+
+// Check before expensive string building
+if (log.isDebugEnabled()) {
+    log.debug('Full cart contents: {0}', JSON.stringify(cart));
+}
+
+// Check before expensive calculations
+if (log.isInfoEnabled()) {
+    var stats = calculateDetailedStats(); // expensive
+    log.info('Statistics: {0}', JSON.stringify(stats));
+}
+
+// Available checks
+log.isDebugEnabled();  // true if debug logging enabled
+log.isInfoEnabled();   // true if info logging enabled
+log.isWarnEnabled();   // true if warn logging enabled
+log.isErrorEnabled();  // true if error logging enabled
+```
+
+### Static Level Checks
+
+```javascript
+var Logger = require('dw/system/Logger');
+
+if (Logger.isDebugEnabled()) {
+    Logger.debug('Debug message');
+}
+```
+
+## Message Formatting
+
+Messages support Java MessageFormat syntax:
+
+```javascript
+var Logger = require('dw/system/Logger');
+var log = Logger.getLogger('order');
+
+// Positional parameters
+log.info('Order {0} has {1} items totaling {2}', orderNo, itemCount, total);
+
+// Same parameter multiple times
+log.info('Product {0}: {0} is out of stock', productId);
+
+// Complex objects (use JSON.stringify for objects)
+log.debug('Request: {0}', JSON.stringify(requestData));
+```
+
+## Nested Diagnostic Context (NDC)
+
+NDC helps trace related log messages across a request:
+
+```javascript
+var Logger = require('dw/system/Logger');
+var Log = require('dw/system/Log');
+
+var log = Logger.getLogger('checkout');
+var ndc = Log.getNDC();
+
+function processOrder(orderId) {
+    // Push context onto the stack
+    ndc.push('Order:' + orderId);
+
+    try {
+        log.info('Starting order processing');
+        processPayment();
+        processShipping();
+        log.info('Order processing complete');
+    } finally {
+        // Always pop context when leaving scope
+        ndc.pop();
+    }
+}
+
+function processPayment() {
+    ndc.push('Payment');
+    try {
+        log.info('Processing payment'); // NDC shows: Order:123 Payment
+    } finally {
+        ndc.pop();
+    }
+}
+```
+
+### NDC Methods
+
+| Method | Description |
+|--------|-------------|
+| `push(message)` | Add context to the stack |
+| `pop()` | Remove and return top context |
+| `peek()` | View top context without removing |
+| `remove()` | Clear entire context |
+
+## Best Practices
+
+### 1. Use Categories
+
+```javascript
+// Good: Organized by functional area
+var log = Logger.getLogger('payment.processor');
+var log = Logger.getLogger('inventory.sync');
+var log = Logger.getLogger('order.export');
+
+// Avoid: No category
+Logger.info('Something happened');
+```
+
+### 2. Check Level Before Expensive Operations
+
+```javascript
+// Good: Check before building expensive string
+if (log.isDebugEnabled()) {
+    log.debug('Full response: {0}', JSON.stringify(largeObject));
+}
+
+// Avoid: Always building expensive strings
+log.debug('Full response: {0}', JSON.stringify(largeObject));
+```
+
+### 3. Include Context in Messages
+
+```javascript
+// Good: Includes relevant context
+log.error('Payment failed for order {0}, customer {1}: {2}',
+    orderNo, customerId, errorMessage);
+
+// Avoid: Missing context
+log.error('Payment failed');
+```
+
+### 4. Use Appropriate Levels
+
+```javascript
+// debug: Detailed technical information
+log.debug('SQL query: {0}', query);
+log.debug('API request body: {0}', JSON.stringify(body));
+
+// info: Notable events
+log.info('Order {0} placed successfully', orderNo);
+log.info('Customer {0} logged in', customerId);
+
+// warn: Potential issues
+log.warn('Inventory low for product {0}: {1} remaining', productId, qty);
+log.warn('Slow API response: {0}ms', responseTime);
+
+// error: Failures that need attention
+log.error('Payment declined for order {0}: {1}', orderNo, reason);
+log.error('Failed to connect to service {0}: {1}', serviceName, error);
+
+// fatal: Critical system failures
+log.fatal('Database connection lost');
+log.fatal('Critical configuration missing: {0}', configKey);
+```
+
+### 5. Use Custom Log Files for Integration
+
+```javascript
+// Dedicated files for each integration
+var erpLog = Logger.getLogger('erp-sync', 'erp');
+var omsLog = Logger.getLogger('oms-export', 'oms');
+var crmLog = Logger.getLogger('crm-sync', 'crm');
+```
+
+### 6. Don't Log Sensitive Data
+
+```javascript
+// Good: Mask sensitive data
+log.info('Payment processed for card ending in {0}', cardNumber.slice(-4));
+
+// Avoid: Logging sensitive data
+log.info('Payment processed for card {0}', cardNumber);
+```
+
+## Business Manager Configuration
+
+Configure custom logging in **Administration > Operations > Custom Log Settings**:
+
+| Setting | Description |
+|---------|-------------|
+| **Log to File** | Enable file logging for each level |
+| **Receive Email** | Email addresses for fatal notifications |
+| **Root Category** | Default settings for all categories |
+| **Custom Categories** | Override settings per category |
+
+### Configuring Categories
+
+1. Go to **Custom Log Settings**
+2. Click **Add Category**
+3. Enter category name (e.g., `checkout`, `payment`)
+4. Set log levels to enable
+
+## Log Output Format
+
+Log entries follow this format:
+```
+[timestamp] [level] [category] message
+```
+
+Example:
+```
+[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] Order ORD123 placed successfully
+```
+
+## Detailed Reference
+
+- [Log Files](references/LOG-FILES.md) - Log file types, locations, and retention
+
+## Script API Classes
+
+| Class | Description |
+|-------|-------------|
+| `dw.system.Logger` | Static logging methods and logger factory |
+| `dw.system.Log` | Logger instance with category support |
+| `dw.system.LogNDC` | Nested Diagnostic Context for tracing |