@salesforce/b2c-cli 2.3.1 → 2.4.0

package/content/guidance/b2c/b2c-querying-data/references/PERFORMANCE-APIS.md

@@ -0,0 +1,74 @@
+# Performance-Critical APIs
+
+Complete reference for index-friendly vs database-intensive APIs in B2C Commerce.
+
+## Product APIs
+
+### Database-Intensive (Avoid on Storefront Pages)
+
+| API | Problem | Impact |
+|-----|---------|--------|
+| `Category.getOnlineSubCategories()` | Hits database for each subcategory | Slow on deep category trees |
+| `Category.getProducts()` | Loads all products from database | Memory + time on large categories |
+| `Category.getOnlineProducts()` | Same as above, filtered | Still database-backed |
+| `Category.getProductAssignments()` | Database query per assignment | Expensive with many assignments |
+| `Category.getOnlineCategoryAssignments()` | Same, filtered by online status | Still database-backed |
+| `ProductMgr.queryAllSiteProducts()` | Full table scan of all products | Never use on storefront |
+| `Product.getPriceModel()` | Database lookup for pricing | Expensive in loops |
+| `Product.getVariants()` | Loads all variant products | Very expensive for products with many variants |
+| `Product.getVariationModel()` | Builds full variation model | Database-intensive |
+
+### Index-Friendly Replacements
+
+| API | Benefit |
+|-----|---------|
+| `ProductSearchModel.search()` | Search-index backed, fast |
+| `ProductSearchModel.setCategoryID(id)` | Replaces `Category.getProducts()` |
+| `ProductSearchModel.setOrderableProductsOnly(true)` | Replaces `Category.getOnlineProducts()` + availability check |
+| `ProductSearchModel.getRefinements()` | Index-backed refinement values |
+| `ProductSearchRefinements.getNextLevelCategoryRefinementValues(category)` | Replaces `Category.getOnlineSubCategories()` for nav |
+| `ProductSearchRefinements.getAllRefinementValues(attributeName)` | Refinement values for one attribute |
+| `ProductSearchModel.getProductSearchHits()` | Efficient result iteration |
+| `ProductSearchHit.getMinPrice()` / `getMaxPrice()` | Replaces `Product.getPriceModel()` in search |
+| `ProductSearchHit.getRepresentedProductIDs()` | Replaces `Product.getVariants()` in search |
+| `ProductSearchHit.getRepresentedVariationValues(attr)` | Replaces `Product.getVariationModel()` in search |
+
+## Order APIs
+
+| API | Type | Notes |
+|-----|------|-------|
+| `OrderMgr.searchOrders(query, sort, ...args)` | Index-backed | Preferred for storefront lookups; limited to 1000 results |
+| `OrderMgr.searchOrder(query, ...args)` | Index-backed | Single order search |
+| `OrderMgr.queryOrders(query, sort, ...args)` | Database | Use for non-indexed attributes only |
+| `OrderMgr.queryOrder(query, ...args)` | Database | Single order, database query |
+| `OrderMgr.getOrder(orderNo)` | Direct lookup | Fast; use when you have the order number |
+
+## Customer / Profile APIs
+
+| API | Type | Notes |
+|-----|------|-------|
+| `CustomerMgr.searchProfiles(query, sort, ...args)` | Index-backed | Preferred for storefront; max 1000 results |
+| `CustomerMgr.processProfiles(query, callback, ...args)` | Index-backed | Preferred for jobs; optimized memory management |
+| `CustomerMgr.queryProfiles(query, sort, ...args)` | Database | **Deprecated pattern**; use `searchProfiles` instead |
+| `SystemObjectMgr.querySystemObjects('Profile', ...)` | Database | **Deprecated for profiles**; use `CustomerMgr` methods |
+| `CustomerMgr.getCustomerByLogin(login)` | Direct lookup | Fast; use when you have the login |
+| `CustomerMgr.getCustomerByToken(token)` | Direct lookup | Fast; token-based auth flows |
+
+## Custom Object APIs
+
+| API | Type | Notes |
+|-----|------|-------|
+| `CustomObjectMgr.getCustomObject(type, key)` | Direct lookup | Fast; use when you have the key |
+| `CustomObjectMgr.queryCustomObjects(type, query, sort, ...args)` | Database | Only option for filtered queries |
+| `CustomObjectMgr.getAllCustomObjects(type)` | Database | Use with caution on large datasets |
+
+## General Query Performance Rules
+
+1. **Search index APIs** (search*) are 10-100x faster than database APIs (query*) for indexed attributes
+2. **Direct lookups** (getOrder, getCustomerByLogin, getCustomObject) are fastest when you have the key
+3. **Database queries** (query*) should only be used when:
+   - The attribute is not in the search index
+   - You need more than 1000 results (use in jobs, not storefront)
+   - You need exact database consistency (search index can be slightly behind)
+4. **Iterator management**: Always call `.close()` on query/search result iterators
+5. **Result limits**: Search APIs return at most 1000 hits; design pagination accordingly

package/content/guidance/b2c/b2c-scapi-admin/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: b2c-scapi-admin
+description: Build backend integrations that sync data between B2C Commerce and external systems like ERPs, OMS, WMS, or CRMs using SCAPI Admin APIs. Use this skill whenever the user needs to pull or push orders, products, inventory, or customer data programmatically from a backend service, set up server-to-server authentication with Account Manager client credentials and admin OAuth scopes, implement bulk inventory imports with NDJSON, or call any Commerce API from a script or pipeline (not a storefront). Also use when building nightly data exports, warehouse sync jobs, or customer data integrations — even if they just say "pull orders into our ERP" or "sync inventory from the warehouse".
+---
+
+# SCAPI Admin APIs
+
+Build backend integrations or manage Commerce data through standard Admin APIs.
+Use the `b2c-scapi-shopper` skill for storefront flows.
+
+## Tool choice
+
+When B2C MCP is available:
+- Prefer a dedicated task tool. Otherwise read `skill://mcp/b2c-mcp-scapi/SKILL.md` once
+  through resources or `skills_read`, then use `skillRead: true`.
+- `scapi_search`: bundled standard contracts, offline. Find method/path/operationId,
+  then inspect selected parameters, fields, and security scopes. Return compact projections.
+- `scapi_execute`: supported Admin JSON operations with configured Account Manager
+  auth and automatic operation/tenant scopes. Use `config_inspect` with masking;
+  do not fetch or print tokens manually for these calls.
+- `scapi_schemas_list`: live tenant schemas, including custom attributes and APIs.
+  `scapi_custom_apis_get_status`: custom registration. Custom execution and binary
+  transfers are unsupported by code mode; use an appropriate integration client.
+- `docs_search`/`docs_read`: platform semantics, limits, and auth setup. No duplicate
+  docs lookup is needed merely to repeat a discovered contract.
+
+For CLI/integration development: `b2c scapi schemas list` and
+`b2c scapi schemas get <family> <name> <version>` retrieve live contracts.
+Read [integration examples](references/CLIENT-EXAMPLES.md) only when implementing
+an external client, token flow, or bulk import. There is no CLI code-mode equivalent.
+
+## Execute deliberately
+
+- Use configured short code, tenant, and site values. Admin auth requires an
+  Account Manager client, API grants, and `SALESFORCE_COMMERCE_API:<tenant_id>`.
+  SLAS credentials do not replace Admin credentials.
+- Inspect the operation before use; examples are illustrative. For tenant-specific
+  fields use live schemas. Check official docs for version-specific semantics.
+- Distinguish creation from update; PUT may do both. Verify existence and intent,
+  then read back meaningful fields. Check earlier writes before retrying a failure.
+- Page/filter at the API and return IDs, selected fields, totals/hasMore, and errors.
+  Do not emit whole response trees or log credentials.
+- Safety is method-based: POST searches can require a targeted allow rule.
+  Confirmation-required code-mode requests stop; do not bypass them.
+
+## Conditional references
+
+- [OAuth scopes](references/OAUTH-SCOPES.md): integration grants; compare with the operation's security.
+- [Integration patterns](references/INTEGRATION-PATTERNS.md): ETL, sync, bulk import.
+- `b2c-config` skill: CLI credentials and precedence.
+- Official docs: `commerce-api/authorization-for-admin-apis`, `commerce-api/auth-z-scope-catalog`,
+  `commerce-api/timeouts-limits`, `commerce-api/throttle-rates`,
+  `commerce-api/inventory-impex-best-practices`.

package/content/guidance/b2c/b2c-scapi-admin/references/CLIENT-EXAMPLES.md

@@ -0,0 +1,440 @@
+# SCAPI Client Examples
+
+For external integration code; MCP calls use configured authentication. Verify
+contract details with schema discovery before adapting these examples.
+
+## Overview
+
+Admin APIs are designed for backend systems and integrations:
+
+- **Client**: Backend services, ETL pipelines, management tools
+- **Authentication**: Account Manager OAuth (client credentials)
+- **Response Time**: Typical < 60 seconds; see `docs_read commerce-api/timeouts-limits` for current thresholds
+- **Usage**: Moderate frequency, batch operations preferred
+
+### Base URL Structure
+
+```
+https://{shortCode}.api.commercecloud.salesforce.com/{apiFamily}/{apiName}/v1/organizations/{organizationId}/{resource}
+```
+
+Example:
+```
+https://kv7kzm78.api.commercecloud.salesforce.com/product/products/v1/organizations/f_ecom_zzte_053/products/25518823M
+```
+
+**Note:** Admin APIs typically don't require `siteId` parameter (unlike Shopper APIs).
+
+## Authentication
+
+Admin APIs use Account Manager OAuth with client credentials flow.
+
+### Get Admin Token via CLI
+
+```bash
+# Get admin token (uses clientId/clientSecret from dw.json)
+b2c auth token
+
+# Get token with specific scopes — b2c auth token accepts multiple scopes
+# (repeat --auth-scope or pass a comma-separated list). It does NOT auto-inject
+# the tenant scope, so include SALESFORCE_COMMERCE_API:<tenant_id> alongside the API scopes.
+b2c auth token \
+  --auth-scope "SALESFORCE_COMMERCE_API:zzte_053" \
+  --auth-scope sfcc.orders \
+  --auth-scope sfcc.products
+
+# Get token as JSON (includes expiration)
+b2c auth token --json
+```
+
+> **Tenant scope is required.** For any SCAPI Admin call (system APIs *and* custom Admin APIs), the token must carry both the tenant scope `SALESFORCE_COMMERCE_API:<tenant_id>` and the API-specific scopes — see [Dual Scope Requirement](#dual-scope-requirement) below. The SCAPI subcommands (`b2c scapi custom status`, `b2c scapi schemas list`) add the tenant scope automatically; `b2c auth token` and raw curl do not.
+
+See the `b2c-config` skill for configuration details.
+
+### Get Token Programmatically
+
+```bash
+curl "https://account.demandware.com/dwsso/oauth2/access_token" \
+  --request 'POST' \
+  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data "grant_type=client_credentials" \
+  --data-urlencode "scope=SALESFORCE_COMMERCE_API:${TENANT_ID} ${SCOPES}"
+```
+
+**Example:**
+
+```bash
+CLIENT_ID="your-client-id"
+CLIENT_SECRET="your-client-secret"
+TENANT_ID="zzte_053"
+SCOPES="sfcc.orders sfcc.products"
+
+TOKEN=$(curl -s "https://account.demandware.com/dwsso/oauth2/access_token" \
+  -u "$CLIENT_ID:$CLIENT_SECRET" \
+  -d "grant_type=client_credentials" \
+  --data-urlencode "scope=SALESFORCE_COMMERCE_API:$TENANT_ID $SCOPES" \
+  | jq -r '.access_token')
+```
+
+### Dual Scope Requirement
+
+Admin APIs require **two types of scopes**:
+
+1. **Tenant scope**: `SALESFORCE_COMMERCE_API:{tenant_id}` - grants access to the tenant
+2. **API-specific scopes**: `sfcc.catalogs`, `sfcc.orders.rw`, etc. - grants API access
+
+```
+scope=SALESFORCE_COMMERCE_API:zzte_053 sfcc.catalogs sfcc.products.rw
+```
+
+See [OAuth Scopes Reference](../references/OAUTH-SCOPES.md) for the complete scope list.
+
+### Account Manager Setup
+
+1. Log into Account Manager
+2. Navigate to **API Client** > **Add API Client**
+3. Configure:
+   - Display Name and Password (client secret)
+   - Assign Organizations (your B2C instances)
+   - Role: "Salesforce Commerce API"
+   - Token Endpoint Auth Method: `client_secret_post`
+   - Access Token Format: `JWT`
+   - Allowed Scopes: Add required scopes
+4. Copy the Client ID
+
+## API Families
+
+> **Note:** The examples below illustrate typical request patterns and are provided for learning purposes. For authoritative API contracts (current request/response schemas, endpoints, query parameters, headers), use `b2c scapi schemas list` and `b2c scapi schemas get <api-family> <api-name> <version>` to retrieve OpenAPI specs, or consult the official [Commerce API Reference](https://developer.salesforce.com/docs/commerce/commerce-api) via `b2c docs search` / `docs_search`.
+
+### Products API
+
+Manage product catalog data.
+
+```javascript
+// Get product
+const product = await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/${orgId}/products/${productId}`,
+    {
+        headers: { 'Authorization': `Bearer ${adminToken}` }
+    }
+).then(r => r.json());
+
+// Update product
+await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/${orgId}/products/${productId}`,
+    {
+        method: 'PATCH',
+        headers: {
+            'Authorization': `Bearer ${adminToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            name: { default: 'Updated Product Name' },
+            shortDescription: { default: 'New description' }
+        })
+    }
+);
+```
+
+**Required Scopes:**
+- Read: `sfcc.products`
+- Write: `sfcc.products.rw`
+
+### Catalogs API
+
+Manage catalog structure and assignments.
+
+```javascript
+// List catalogs
+const catalogs = await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/${orgId}/catalogs`,
+    {
+        headers: { 'Authorization': `Bearer ${adminToken}` }
+    }
+).then(r => r.json());
+
+// Get catalog details
+const catalog = await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/${orgId}/catalogs/${catalogId}`,
+    {
+        headers: { 'Authorization': `Bearer ${adminToken}` }
+    }
+).then(r => r.json());
+```
+
+**Required Scopes:**
+- Read: `sfcc.catalogs`
+- Write: `sfcc.catalogs.rw`
+
+### Orders API
+
+Retrieve and manage orders.
+
+```javascript
+// Get order by number
+const order = await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1/organizations/${orgId}/orders/${orderNo}?siteId=${siteId}`,
+    {
+        headers: { 'Authorization': `Bearer ${adminToken}` }
+    }
+).then(r => r.json());
+
+// Update order status
+await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1/organizations/${orgId}/orders/${orderNo}?siteId=${siteId}`,
+    {
+        method: 'PATCH',
+        headers: {
+            'Authorization': `Bearer ${adminToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            status: 'completed',
+            shippingStatus: 'shipped'
+        })
+    }
+);
+```
+
+**Required Scopes:**
+- Read: `sfcc.orders`
+- Write: `sfcc.orders.rw`
+
+### Inventory Availability API
+
+Manage product inventory.
+
+```javascript
+// Get inventory for a product
+const availability = await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1/organizations/${orgId}/availability-records/search`,
+    {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${adminToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            skus: ['SKU001', 'SKU002'],
+            locationIds: ['warehouse-1']
+        })
+    }
+).then(r => r.json());
+
+// Update inventory
+await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1/organizations/${orgId}/availability-records`,
+    {
+        method: 'PATCH',
+        headers: {
+            'Authorization': `Bearer ${adminToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            records: [{
+                sku: 'SKU001',
+                locationId: 'warehouse-1',
+                onHand: 100,
+                effectiveDate: new Date().toISOString()
+            }]
+        })
+    }
+);
+```
+
+**Required Scopes:**
+- Read: `sfcc.inventory.availability`
+- Write: `sfcc.inventory.availability.rw`
+
+### Inventory IMPEX API
+
+> Illustrative of the IMPEX flow; confirm file size thresholds, format requirements, and best practices with `docs_read commerce-api/inventory-impex-best-practices`.
+
+High-performance bulk inventory import. Use for 1000+ SKU updates.
+
+**Critical Requirements:**
+- Files > 100MB **MUST** be gzip compressed
+- Use newline-delimited JSON (NDJSON), not comma-separated arrays
+- Don't run imports during location graph changes
+- Use delta imports (changed data only) for best performance
+- Future quantity values must be > 0
+
+```javascript
+// Step 1: Initiate import
+const importJob = await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/${orgId}/availability-records/imports`,
+    {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${adminToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({})
+    }
+).then(r => r.json());
+
+// Step 2: Prepare newline-delimited JSON
+const ndjsonData = inventoryRecords
+    .map(r => JSON.stringify({
+        recordId: r.recordId || crypto.randomUUID(),
+        sku: r.sku,
+        locationId: r.locationId,
+        onHand: r.quantity,
+        effectiveDate: new Date().toISOString()
+    }))
+    .join('\n');
+
+// Step 3: Upload data to the uploadLink
+await fetch(importJob.uploadLink, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: ndjsonData
+});
+
+// Step 4: Monitor status
+const status = await fetch(importJob.importStatusLink, {
+    headers: { 'Authorization': `Bearer ${adminToken}` }
+}).then(r => r.json());
+```
+
+**Required Scope:** `sfcc.inventory.impex-inventory`
+
+**Note:** Inventory IMPEX logs don't appear in Log Center. Use correlation IDs and monitor import status directly.
+
+See [Integration Patterns Reference](../references/INTEGRATION-PATTERNS.md) for bulk import best practices.
+
+### Customers API
+
+Manage customer data.
+
+```javascript
+// Search customers
+const customers = await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/customer/customers/v1/organizations/${orgId}/customer-search?siteId=${siteId}`,
+    {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${adminToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            query: {
+                textQuery: { fields: ['email'], searchPhrase: 'john@example.com' }
+            }
+        })
+    }
+).then(r => r.json());
+```
+
+**Required Scopes:**
+- Read: `sfcc.shopper-customers`
+- Write: `sfcc.shopper-customers.rw`
+
+### Promotions API
+
+Manage promotions and campaigns.
+
+```javascript
+// Get promotion
+const promotion = await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1/organizations/${orgId}/promotions/${promotionId}?siteId=${siteId}`,
+    {
+        headers: { 'Authorization': `Bearer ${adminToken}` }
+    }
+).then(r => r.json());
+
+// Update promotion
+await fetch(
+    `https://${shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1/organizations/${orgId}/promotions/${promotionId}?siteId=${siteId}`,
+    {
+        method: 'PATCH',
+        headers: {
+            'Authorization': `Bearer ${adminToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            enabled: true,
+            startDate: '2024-06-01T00:00:00Z',
+            endDate: '2024-06-30T23:59:59Z'
+        })
+    }
+);
+```
+
+**Required Scopes:**
+- Read: `sfcc.promotions`
+- Write: `sfcc.promotions.rw`
+
+## Request Tracking
+
+> Illustrative of correlation ID and verbose logging mechanisms; confirm current header names and Log Center search syntax with `docs_read commerce-api/scapi-logs-request-tracking`.
+
+### Correlation IDs
+
+Include correlation IDs for tracking requests across systems:
+
+```javascript
+const correlationId = crypto.randomUUID();
+
+const response = await fetch(url, {
+    headers: {
+        'Authorization': `Bearer ${adminToken}`,
+        'correlation-id': correlationId
+    }
+});
+
+console.log(`Request ${correlationId} completed`);
+// Search Log Center: externalID:({correlationId})
+```
+
+### Verbose Logging
+
+Enable verbose logging for debugging:
+
+```javascript
+const response = await fetch(url, {
+    headers: {
+        'Authorization': `Bearer ${adminToken}`,
+        'sfdc_verbose': 'true'
+    }
+});
+```
+
+Check Log Center under `scapi.verbose` category.
+
+**Note:** Some Admin APIs (CDN Zones, Inventory, Shopper Context) don't log to Log Center.
+
+## Error Handling
+
+### Common Errors
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| 400 | Bad Request | Check request body/parameters |
+| 401 | Unauthorized | Token expired - get new token |
+| 403 | Forbidden | Missing scope or tenant access |
+| 404 | Not Found | Resource doesn't exist |
+| 429 | Rate Limited | Implement backoff |
+| 500 | Server Error | Retry with backoff |
+| 504 | Timeout | Request took > 60 seconds |
+
+### Rate Limiting
+
+Admin APIs have lower rate limits than Shopper APIs. See `docs_read commerce-api/throttle-rates` for specific rate limits per API family. For bulk operations:
+
+- Use batch endpoints when available
+- Implement exponential backoff for 429 responses
+- Consider inventory IMPEX for large data imports
+- Spread operations over time for non-urgent updates
+
+## Related Skills
+
+- `b2c-config` skill - Get admin tokens via CLI
+- `b2c-scapi-shopper` skill - Shopper-facing APIs
+- `b2c-scapi-schemas` skill - Browse OpenAPI schemas
+
+## Reference Documentation
+
+- [OAuth Scopes Reference](../references/OAUTH-SCOPES.md) - Complete admin scope reference
+- [Integration Patterns](../references/INTEGRATION-PATTERNS.md) - ETL, sync, and bulk import patterns