sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/skills/sfcc-logging/references/LOG-FILES.md

@@ -0,0 +1,282 @@
+# Log Files Reference
+
+Complete reference for B2C Commerce log file types, locations, and management.
+
+## Log File Types
+
+### Custom Log Files
+
+Custom log files are generated by script logging:
+
+| Log File | Trigger | Default State |
+|----------|---------|---------------|
+| `customdebug` | `Logger.debug()` or `log.debug()` | Disabled |
+| `custominfo` | `Logger.info()` or `log.info()` | Disabled |
+| `customwarn` | `Logger.warn()` or `log.warn()` | Always enabled |
+| `customerror` | `Logger.error()` or `log.error()` | Always enabled |
+| `customfatal` | `log.fatal()` | Always enabled |
+
+### System Log Files
+
+System log files are generated by the platform:
+
+| Log File | Description |
+|----------|-------------|
+| `error` | System errors in scripts, templates, and platform |
+| `warn` | Lock status, slot warnings, servlet warnings |
+| `info` | System information from scripts and platform |
+| `debug` | Debug information (only when debug flag enabled) |
+| `fatal` | Critical system failures |
+| `api` | API problems and violations |
+| `deprecation` | Usage of deprecated APIs |
+| `jobs` | Job status information |
+| `staging` | Replication process information |
+| `quota` | Quota warnings and limits |
+| `sql` | SQL and replication issues |
+| `syslog` | API processing, staging, import/export info |
+| `sysevent` | Appserver registration, cartridge logs |
+| `analytics` | Analytics activity and errors |
+| `performance` | Internal performance data |
+| `console` | Internal console entries |
+| `migration` | Internal migration data |
+| `dbinit-sql` | SQL used during database initialization |
+
+### Custom Named Log Files
+
+Files created with `Logger.getLogger(prefix, category)`:
+
+```
+custom-<prefix>-<hostname>-appserver-<date>.log
+```
+
+Example: `custom-orderexport-blade0-1-appserver-20240115.log`
+
+## Log File Locations
+
+### WebDAV Access
+
+**Logs Directory:**
+```
+https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Logs
+```
+
+**Security Logs:**
+```
+https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Securitylogs
+```
+
+**Import/Export Logs:**
+```
+https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/log
+```
+
+### Business Manager Access
+
+1. **Administration > Site Development > Development Setup**
+2. Scroll to **WebDAV Access** section
+3. Click **Log files** link
+
+## Log Retention
+
+| Environment | Retention | Notes |
+|-------------|-----------|-------|
+| Production | 30 days | Auto-deleted after retention |
+| Staging | 30 days | Auto-deleted after retention |
+| Development | Not defined | Manual cleanup recommended |
+| Sandbox | Not defined | Manual cleanup recommended |
+
+**Security logs** are retained for 90 days.
+
+### Archive Process
+
+- After 3 days, logs move to `log_archive` directory
+- Archived logs are compressed to gzip format
+- Download logs locally for longer retention
+
+## Storage Limits
+
+### Custom Log Size Limits
+
+| Limit | Value |
+|-------|-------|
+| Per log level per day | 10 MB |
+| Per application server | Per log type |
+| Custom named log files | Same 10 MB limit |
+
+When the limit is reached:
+```
++++++++++++ Maximum log file size per day reached, logging suspended. +++++++++++
+```
+
+Logging resumes at 00:00 GMT the next day.
+
+### File Count Limits
+
+- Maximum 100,000 files per folder
+- Excess files deleted starting with oldest
+- Applies per folder, not across subfolders
+
+### Custom Log File Quota
+
+- Maximum 200 different log file prefixes per day
+- Per application server
+- Hard limit (throws exception when exceeded)
+
+## Log Entry Format
+
+### Standard Format
+
+```
+[timestamp GMT] [level] [category] message
+```
+
+Example:
+```
+[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] Order ORD123 submitted
+```
+
+### With NDC
+
+```
+[timestamp GMT] [level] [category] [ndc-context] message
+```
+
+Example:
+```
+[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] [Order:123 Payment] Processing payment
+```
+
+## Redundancy Tracking
+
+Error and Warning messages are tracked for redundancy:
+
+- Messages appearing > 10 times in 3 minutes are suppressed
+- Suppression lasts 3 minutes
+- Suppression message:
+
+```
+The following message was generated more than 10 times within the last 180 seconds.
+It will be suppressed for 180 seconds:
+<original message>
+```
+
+## Quota Log Format
+
+Quota logs show when thresholds or limits are exceeded:
+
+```
+[timestamp] [thread-info] Quota quota.name (enforced, warn threshold, limit):
+warn threshold exceeded N time(s), max actual was X, current location: details
+```
+
+Example:
+```
+[2024-01-15 13:00:22.577 GMT] [RequestHandlerServlet|14320460|Sites-MySite|Product-Show|...]
+Quota api.jsStringLength (enforced, warn 600000, limit 1000000): warn threshold exceeded 1 time(s),
+max actual was 600010, current location: request/site Sites-MySite/top pipeline Product-Show/
+interaction node/template default.CustomDisplay
+```
+
+## Security Log Format
+
+```
+[timestamp GMT][dw-sec] (User: 'username' (realm), IP: x.x.x.x [ACTION] : details)
+```
+
+Example:
+```
+[2024-01-15 02:23:19.139 GMT][dw-sec] (User: 'admin' (Sites), IP: 192.168.1.1 [LOGIN] : logged in.)
+```
+
+Actions logged:
+- LOGIN
+- LOGOUT
+- LOGIN_FAILED
+- PASSWORD_CHANGED
+- Re-login (session timeout)
+
+## Import/Export Logs
+
+Located in `/Impex/log/`:
+
+| Log Type | Description |
+|----------|-------------|
+| Catalog | Catalog import/export logs |
+| Customer | Customer batch processing logs |
+| Inventory | Inventory import logs |
+| Price Book | Price book import/validation logs |
+| Promotion | Promotion validation logs |
+| Metadata | Metadata validation logs |
+| Coupon | Coupon validation logs |
+
+Example path:
+```
+/Impex/log/Batch-Customer-20240115192425062.log
+```
+
+## Accessing Logs Programmatically
+
+### Via WebDAV Client
+
+Configure your WebDAV client with:
+- URL: `https://<instance>/on/demandware.servlet/webdav/Sites/Logs`
+- User: Business Manager username
+- Password: Business Manager password
+
+### Via MCP Tools
+
+Use the SFCC Dev MCP Server log tools:
+- `get_latest_error` - Recent error messages
+- `get_latest_debug` - Recent debug messages
+- `get_latest_info` - Recent info messages
+- `get_latest_warn` - Recent warning messages
+- `search_logs` - Search for patterns in logs
+- `summarize_logs` - Health overview of log activity
+
+## Debug Logging on Production
+
+Debug logging is **never enabled on production instances**.
+
+On non-production instances:
+- Debug logs are "in-memory" by default
+- Enables "Show Request Log" feature
+- Does not generate log files unless explicitly enabled
+
+## Best Practices
+
+### 1. Monitor Log File Sizes
+
+Check log sizes regularly to avoid hitting limits:
+- 10 MB per custom log type per day
+- Monitor during high-traffic periods
+
+### 2. Use Custom Named Logs for Integrations
+
+```javascript
+// Separate files for each integration
+var erpLog = Logger.getLogger('erp-sync', 'erp');
+var paymentLog = Logger.getLogger('payment-gateway', 'payment');
+```
+
+### 3. Clean Up Old Logs
+
+- Delete unnecessary logs promptly
+- Don't exceed 100,000 files per folder
+- Download and archive important logs locally
+
+### 4. Configure Categories in Business Manager
+
+1. Go to **Administration > Operations > Custom Log Settings**
+2. Add categories for your code areas
+3. Enable appropriate log levels per category
+4. Set up fatal email notifications
+
+### 5. Use Appropriate Log Levels
+
+| Level | Use For |
+|-------|---------|
+| debug | Development debugging only |
+| info | Notable events, job progress |
+| warn | Recoverable issues, slow operations |
+| error | Failures requiring attention |
+| fatal | Critical failures, email notification |

package/{docs/best-practices/ocapi_hooks.md → ai-instructions/skills/sfcc-ocapi-hooks/SKILL.md}

@@ -1,8 +1,13 @@
+---
+name: sfcc-ocapi-hooks
+description: Guide for implementing OCAPI hooks in Salesforce B2C Commerce. Use this when asked to create OCAPI hooks, extend API endpoints, validate API requests, or modify API responses.
+---
+
 # Quick Guide: Salesforce B2C Commerce OCAPI Hooks
 
 This guide provides best practices and examples for implementing OCAPI hooks in Salesforce B2C Commerce Cloud.
 
-**IMPORTANT**: Before implementing OCAPI hooks, consult the **Performance and Stability Best Practices** guide from this MCP server. Pay special attention to the OCAPI-specific performance requirements and hook development guidelines to ensure optimal performance and avoid database-intensive operations.
+**IMPORTANT**: Before implementing OCAPI hooks, consult the **Performance and Stability Best Practices** guide. Pay special attention to the OCAPI-specific performance requirements and hook development guidelines to ensure optimal performance and avoid database-intensive operations.
 
 ## 1. Core Concepts
 
@@ -47,11 +52,11 @@ This file points to your hooks configuration file.
 ```json
 {
   "name": "my-hooks-cartridge",
-  "hooks": "./cartridge/hooks.json"
+  "hooks": "./cartridge/scripts/hooks.json"
 }
 ```
 
-### `hooks.json` (e.g., `/cartridge/hooks.json`)
+### `hooks.json` (e.g., `/cartridge/scripts/hooks.json`)
 
 This file maps the official hook extension point name to your script file.
 
@@ -60,15 +65,15 @@ This file maps the official hook extension point name to your script file.
   "hooks": [
     {
       "name": "dw.ocapi.shop.customer.address.beforePATCH",
-      "script": "./customer/addressValidation.js"
+      "script": "./hooks/customer/addressValidation.js"
     },
     {
       "name": "dw.ocapi.shop.customer.modifyGETResponse",
-      "script": "./customer/enrichCustomerResponse.js"
+      "script": "./hooks/customer/enrichCustomerResponse.js"
     },
     {
       "name": "dw.ocapi.shop.order.afterPOST",
-      "script": "./order/notifyOms.js"
+      "script": "./hooks/order/notifyOms.js"
     }
   ]
 }
@@ -79,17 +84,24 @@ This file maps the official hook extension point name to your script file.
 Organize hook scripts by the resource they modify for better maintainability.
 
 ```
-/cartridge
-└──hooks.json
-└──/scripts
-   └──/hooks
-      ├──/customer
-      │  ├── addressValidation.js
-      │  └── enrichCustomerResponse.js
-      └──/order
-         └── notifyOms.js
+my_cartridge/
+├── package.json
+└── cartridge/
+  └── scripts/
+    ├── hooks.json
+    └── hooks/
+      ├── customer/
+      │   ├── addressValidation.js
+      │   └── enrichCustomerResponse.js
+      └── order/
+        └── notifyOms.js
 ```
 
+### Feature Switch (Required)
+
+OCAPI/SCAPI hook execution must be enabled in Business Manager:
+`Administration > Global Preferences > Feature Switches > Enable Salesforce Commerce Cloud API hook execution`.
+
 ## 3. Core Implementation Patterns
 
 ### Script Structure (CommonJS)
@@ -118,6 +130,29 @@ Use the Status object to control the execution flow.
 - **Success**: `return new Status(Status.OK);` or `return void` (for Shop API hooks, void is often preferred to allow other hooks in the cartridge path to run).
 - **Controlled Failure**: `return new Status(Status.ERROR, 'ERROR_CODE', 'Descriptive message.');` This halts execution, rolls back the transaction, and returns an HTTP 400 error with a fault document containing your code and message.
 
+### Passing Data Between Hooks
+
+When you need to compute data in an `after*` hook and emit it in `modify*Response`, pass it through `request.custom` for the duration of the request.
+
+```javascript
+// afterPOST
+exports.afterPOST = function (basket, doc) {
+  request.custom.externalResult = { status: 'ok' };
+  return new Status(Status.OK);
+};
+
+// modifyPOSTResponse
+exports.modifyPOSTResponse = function (basket, responseDoc, doc) {
+  responseDoc.c_externalStatus = request.custom.externalResult && request.custom.externalResult.status;
+  return new Status(Status.OK);
+};
+```
+
+### Reliability Notes
+
+- Keep hooks fast; slow hooks can cause timeouts and degrade API performance.
+- Avoid uncaught exceptions; prefer controlled errors (`Status.ERROR`) with stable error codes.
+
 ### Data Integrity (`dw.system.Transaction`)
 
 All modifications to persistent data in `before` or `after` hooks must be wrapped in a transaction.
@@ -233,7 +268,7 @@ exports.afterPOST = function (order) {
 ### Error Handling & Resilience
 
 - **DO** wrap all hook logic in `try/catch` blocks.
-- **DO** use `dw.system.Logger` with custom categories and include the `request.requestID` for easy tracing.
+- **DO** use `dw.system.Logger` with custom categories and include the `request.requestID` for easy tracing. See **[sfcc-logging](../sfcc-logging/SKILL.md)** for complete logging patterns.
 - **BE AWARE** of the Hook Circuit Breaker. If a hook fails more than 50% of the time in its last 100 executions, it will be disabled for 60 seconds, returning HTTP 503.
 
 ### Testing

package/ai-instructions/skills/sfcc-ocapi-scapi-slas/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: sfcc-ocapi-scapi-slas
+description: Decision guide for OCAPI vs SCAPI, and practical SLAS token lifecycle guidance (guest tokens, refresh rotation, public vs private clients, and hybrid SFRA/headless auth). Use this when planning integrations or debugging auth/rate-limit issues.
+---
+
+# OCAPI vs SCAPI vs SLAS (Decision & Operations Skill)
+
+This skill is for architecture decisions and recurring operational pitfalls:
+- When to choose OCAPI vs SCAPI
+- What SLAS rate limiting implies (429 + Retry-After)
+- How to manage SLAS tokens correctly
+- Hybrid auth implications in SFRA + headless setups
+
+## Quick Checklist
+
+```text
+[ ] Identify the consumer: storefront server, backend system, or headless client
+[ ] For shopper APIs, prefer SCAPI + SLAS when the endpoint exists
+[ ] For admin APIs, use SCAPI Admin + Account Manager (AM), not SLAS
+[ ] Expect 429 + Retry-After from SLAS; implement backoff + caching
+[ ] Cache SLAS tokens within the correct scope (don't request a token per API call)
+[ ] Refresh tokens rotate for public clients; private clients may be reusable
+[ ] Avoid refresh-token race conditions (single-flight refresh per shopper)
+[ ] Choose OAuth client type correctly: public vs private
+[ ] Include channel_id in guest token requests when required
+```
+
+## OCAPI vs SCAPI: Official distinctions
+
+- Shopper APIs use SLAS tokens. SLAS JWTs can be accepted by OCAPI endpoints when the SLAS client is allowed.
+- Admin APIs use Account Manager (AM) tokens, not shopper SLAS tokens.
+- Do not mix shopper SLAS clients with admin API access; request only the scopes required by the API family.
+
+## SLAS: Token Lifecycle (The Most Common Failure)
+
+### Token lifetimes are explicit
+Access tokens are documented at roughly 30 minutes, while refresh token validity varies by shopper type and environment. Plan caching and refresh logic around these constraints, and confirm the current values for your org.
+
+### Token caching is (practically) required
+If you request a new guest/login token repeatedly, you'll burn SLAS limits and create intermittent auth failures.
+
+Cache tokens at the right scope:
+- **Browser/PWA**: per shopper session/device (never share tokens across shoppers)
+- **BFF/server**: per shopper session, or per server session key you control
+
+In other words: cache aggressively, but never "globally" in a way that can mix identities.
+
+Also cache stable endpoints (JWT/JWKS/config) where possible and honor `Retry-After` when SLAS returns 429.
+
+### Refresh token rotation
+Refresh token rotation applies to public clients, while private clients may receive reusable refresh tokens:
+- Public clients: exchanging a refresh token returns a **new** refresh token.
+- You must persist and use the **new** refresh token for subsequent refreshes.
+- Reusing the old refresh token typically fails (for example `400 Invalid Refresh Token`).
+
+If a new refresh token is returned, always store it atomically before the next request.
+
+Operational pitfall: parallel refreshes can invalidate each other. Ensure only one refresh happens at a time per shopper (single-flight / mutex) and that the stored refresh token is updated atomically.
+
+### Public vs private clients
+- **Public client**: secrets cannot be protected (browser SPA, mobile app)
+- **Private client**: secret can be stored server-side (BFF)
+
+Choose correctly; it affects your security posture and which OAuth flows you should use.
+Practical default:
+- Public clients: authorization code + PKCE (no client secret in the client)
+- Private clients: server-side flows (client secret stays on the server)
+
+### Grant type pitfalls (guest vs registered)
+- Public guest shoppers: use `authorization_code_pkce` (not `client_credentials`).
+- Private guest shoppers: use `client_credentials`.
+- Registered shoppers: use `authorization_code_pkce` (public) or `authorization_code` / `authorization_code_pkce` (private).
+
+### Service protection (409)
+SLAS may return 409 responses when the same endpoint is called repeatedly with the same USID in a short time. This usually indicates token churn or retry storms. Reduce token issuance and serialize refresh requests.
+
+### Troubleshooting quick map
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| 429 Too Many Requests + `Retry-After` | SLAS rate limit hit | Honor `Retry-After`, reuse tokens, and reduce token requests |
+| 400 `invalid_request` on guest token | Missing `channel_id` requirement | Include `channel_id` on guest token requests |
+| 400 `invalid_grant` or `Invalid Refresh Token` | Reused refresh token or wrong client type | Store the newly returned refresh token and validate client type/flow |
+| 409 Conflict | Service protection due to repeated calls with same USID | Throttle calls and serialize refreshes |
+| 401 Unauthorized | Access token expired or wrong audience/client | Refresh or re-auth with the correct client and scopes |
+
+## Hybrid SFRA + Headless
+
+Older approach: cartridge-based bridging (e.g. `plugin_slas`) can introduce:
+- multiple remote calls during login/registration/session refresh
+- increased risk of hitting per-request API call budgets/quotas in storefront flows
+- operational overhead (patching + regression)
+
+Newer approach: platform-native hybrid authentication (B2C Commerce 25.3+) reduces that integration tax, but requires the `sfcc.session_bridge` scope and keeping the `dwsid` and SLAS JWT in sync. Review required headers/cookies for your architecture before rollout.
+
+## References
+- Salesforce: SLAS guide
+  - https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.html
+- Salesforce: Authorization for Shopper APIs
+  - https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.html
+- Salesforce: Commerce API authorization (Account Manager)
+  - https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html
+- Salesforce: Hybrid Auth (Commerce API)
+  - https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-authentication.html
+- Salesforce: Hybrid Auth overview
+  - https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.html
+- Salesforce: Commerce API release notes (channel_id enforcement)
+  - https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#03182025