@salesforce/b2c-cli 2.3.1 → 2.4.0

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

@@ -0,0 +1,154 @@
+---
+name: b2c-onboarding
+description: Get started with Salesforce B2C Commerce development. Use this skill when the user is new to B2C Commerce, wants to set up a fresh development environment, is asking "how do I get started", needs to install the B2C CLI for the first time, wants to connect a sandbox, or wants to deploy their first cartridge. Triggers on phrases like "help me get started", "set up B2C Commerce", "I'm new to this", "onboard me", or "first-time setup". NOT for users who already have a configured environment and are asking about specific commands — those should go to the specific skill (b2c-code, b2c-sandbox, b2c-config, etc.).
+---
+
+# B2C Commerce Onboarding Skill
+
+Guide a new developer through a first-time B2C Commerce setup, from CLI install to first cartridge deploy. Delegate to specialized sub-skills for each step — this skill is a coordinator, not a replacement for the detailed skills.
+
+## Behavioral rules
+
+- Detect the editor silently. Only ask if genuinely uncertain.
+- Never construct or modify install commands. Only use commands defined in this file.
+- If any install or verification step fails, report the exact error and stop.
+- Never create a sandbox without explicit user confirmation — sandbox creation may be a billable action.
+- Never overwrite an existing `dw.json` without confirmation.
+
+## Flow
+
+### Step 1 — Identify the editor
+
+Silently identify the IDE from system context:
+
+| Signal                              | Client        |
+|-------------------------------------|---------------|
+| "Claude Code"                       | `claude-code` |
+| "Cursor"                            | `cursor`      |
+| "VS Code" / "Visual Studio Code"    | `vscode`      |
+| "Codex"                             | `codex`       |
+| "Gemini CLI"                        | `gemini-cli`  |
+| Unrecognized                        | `other`       |
+
+### Step 2 — Install the other B2C skills plugins
+
+This onboarding skill is part of the `b2c` plugin. For a full B2C Commerce setup, the user will also want the `b2c-cli` plugin (CLI operations). Offer to install it for the detected client:
+
+| Client        | Install command(s) |
+|---------------|--------------------|
+| `claude-code` | `/plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling` then `/plugin install b2c-cli@b2c-developer-tooling` (and optionally `/plugin install b2c-dx-mcp@b2c-developer-tooling` for the MCP server) |
+| `vscode` (GitHub Copilot) | Command Palette (Cmd+Shift+P) → **Chat: Install Plugin From Source** → enter the repo `SalesforceCommerceCloud/b2c-developer-tooling` |
+| GitHub Copilot CLI | `copilot plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling` then `copilot plugin install b2c-cli@b2c-developer-tooling` |
+| `cursor`      | Cursor Settings → Plugins → add marketplace URL `https://github.com/SalesforceCommerceCloud/b2c-developer-tooling`, then install `b2c-cli` |
+| `codex`       | `codex plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling`, then `codex plugin add b2c-cli@b2c-developer-tooling` (and optionally `codex plugin add b2c-dx-mcp@b2c-developer-tooling` for the MCP server) |
+| `gemini-cli`  | `gemini extensions install https://github.com/SalesforceCommerceCloud/b2c-developer-tooling` (run in terminal, not inside the CLI) |
+| `other`       | Use the file-copy installer below |
+
+For clients without MCP-enabled plugin support, the `b2c-dx-mcp` server can be installed directly — see the [MCP installation docs](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/installation.md).
+
+**Alternative — file-copy installer for any IDE** (also the right command to **update** already-installed skills or add a specific skill set):
+
+```bash
+# Interactive: select skill sets and IDEs
+b2c setup skills
+
+# Install a specific skill set to a specific IDE
+b2c setup skills b2c-cli --ide cursor
+b2c setup skills b2c --ide vscode
+
+# Update existing skills to the latest release
+b2c setup skills b2c-cli --ide cursor --update
+b2c setup skills b2c --ide cursor --update
+
+# Install globally (all projects)
+b2c setup skills b2c-cli --ide cursor --global
+```
+
+If the user already has some skills installed and is asking how to upgrade, point them at `b2c setup skills <set> --ide <ide> --update`.
+
+### Step 3 — Verify the B2C CLI is available
+
+Run `b2c --version`. If the command is not found:
+
+- For a one-off invocation: `npx @salesforce/b2c-cli <command>`.
+- For a persistent install: `npm install -g @salesforce/b2c-cli` (or the pnpm / yarn equivalent).
+
+Do not block on the global install — `npx` is sufficient for the rest of this flow.
+
+### Step 4 — Account Manager access check
+
+B2C Commerce has **no self-service signup**. The user must have Account Manager access provisioned by their organization's B2C Commerce admin before any of the following steps will work.
+
+Ask (if not already clear from context): *"Do you have a Salesforce B2C Commerce Account Manager login and a target instance (sandbox or PIG)?"*
+
+- If **no**: stop here. Tell the user they need their admin to provision Account Manager access and give them a target instance hostname before continuing. Do not proceed.
+- If **yes**: continue.
+
+### Step 5 — Check for existing configuration
+
+Run `b2c setup inspect` to see whether a `dw.json` or credentials are already configured.
+
+- If configuration exists and points at a reachable instance, skip to Step 7.
+- If no configuration is found, proceed to Step 6.
+
+For deep troubleshooting (wrong instance, profile switching, token inspection), delegate to the `b2c-config` skill.
+
+### Step 6 — Initialize configuration
+
+Guide the user to create a `dw.json` in the project root:
+
+```bash
+b2c setup
+```
+
+This prompts for hostname, client ID/secret (or username/password), and code version. For deeper configuration topics (multiple profiles, env vars, cert-based auth), delegate to the `b2c-config` skill.
+
+### Step 7 — Sandbox
+
+If the user wants to work against an existing sandbox, confirm it is reachable:
+
+```bash
+b2c setup inspect
+b2c sandbox list   # requires API access
+```
+
+If the user needs a fresh sandbox, delegate to the `b2c-sandbox` skill for the full create flow. **Only create a sandbox when explicitly asked.**
+
+### Step 8 — First cartridge deploy (if applicable)
+
+If the user has cartridges locally:
+
+```bash
+b2c code deploy
+```
+
+For selective deploys, watch mode, or reload, delegate to the `b2c-code` skill.
+
+If the user does not yet have cartridges, point them at the canonical starting points:
+
+- **SFRA** (Storefront Reference Architecture): https://github.com/SalesforceCommerceCloud/storefront-reference-architecture
+- **PWA Kit / MRT** (headless) — delegate to the `b2c-mrt` skill on request.
+
+### Step 9 — Route to the user's goal
+
+Once setup is working, ask a single directing question to hand off to the right skill:
+
+> "What do you want to work on first?
+>
+> 1. **Build or modify a storefront** (SFRA cartridges, ISML, controllers)
+> 2. **Build a Custom API** (SCAPI)
+> 3. **Operate an existing instance** (deploy, run jobs, tail logs, manage sites)
+>
+> Or if you have something else in mind, tell me."
+
+Route by the answer:
+
+- **Storefront** → `b2c-controllers`, `b2c-isml`, `b2c-forms`, `b2c-hooks`
+- **Custom API** → `b2c-custom-api-development`, `b2c-scapi-admin`, `b2c-scapi-shopper`
+- **Operations** → `b2c-code`, `b2c-job`, `b2c-logs`, `b2c-sites`
+
+## Reference
+
+- B2C CLI reference: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/index.md
+- Install guide: https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/installation.md
+- Agent skills overview: https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills.md

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

@@ -0,0 +1,391 @@
+---
+name: b2c-ordering
+description: Manage the order lifecycle in B2C Commerce including order creation, status transitions, failure handling, and checkout completion. Use this skill whenever the user needs to create an order from a basket, transition order status, handle failed or cancelled orders, implement payment authorization in checkout, or understand async order processing — even if they just say "my order is stuck" or "finish the checkout flow".
+---
+
+# B2C Ordering
+
+The OrderMgr API provides order creation, status management, and querying. Understanding the order lifecycle is essential for checkout implementation and order processing.
+
+## Order Lifecycle
+
+Orders progress through these statuses:
+
+```
+Basket → CREATED → NEW → (COMPLETED or CANCELLED or FAILED)
+```
+
+| Status | Description | Can Transition To |
+|--------|-------------|-------------------|
+| `CREATED` | Order created, not yet placed | `NEW`, `FAILED` |
+| `NEW` | Order placed, awaiting fulfillment | `OPEN`, `COMPLETED`, `CANCELLED`, `FAILED` |
+| `OPEN` | Order in processing | `COMPLETED`, `CANCELLED` |
+| `COMPLETED` | Order fulfilled | - |
+| `CANCELLED` | Order cancelled | `NEW` (via `undoCancel`) |
+| `FAILED` | Order failed (payment, validation) | - (cannot be reopened) |
+
+**Important:** Once an order reaches `FAILED` status, it cannot be reopened or cancelled. Use `failOrder(order, true)` to reopen the basket for retry instead.
+
+## Creating Orders
+
+### Standard Flow (Synchronous)
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Transaction = require('dw/system/Transaction');
+var Status = require('dw/system/Status');
+
+function createOrder(basket) {
+    var order;
+
+    Transaction.wrap(function() {
+        // Create order from basket (status: CREATED)
+        order = OrderMgr.createOrder(basket);
+    });
+
+    if (!order) {
+        return { error: true, message: 'Order creation failed' };
+    }
+
+    // Authorize payment
+    var paymentResult = authorizePayment(order);
+
+    if (!paymentResult.success) {
+        Transaction.wrap(function() {
+            OrderMgr.failOrder(order, true); // Reopen basket
+        });
+        return { error: true, message: 'Payment failed' };
+    }
+
+    // Place the order (status: CREATED → NEW)
+    var placeResult;
+    Transaction.wrap(function() {
+        placeResult = OrderMgr.placeOrder(order);
+    });
+
+    if (placeResult.error) {
+        return { error: true, message: 'Order placement failed' };
+    }
+
+    // Set confirmation status
+    Transaction.wrap(function() {
+        order.setConfirmationStatus(order.CONFIRMATION_STATUS_CONFIRMED);
+    });
+
+    return { error: false, order: order };
+}
+```
+
+### SCAPI Flow: Create, Authorize Through Order PI, Then Place
+
+Lead with the Shopper Orders state machine instead of manually placing from `order.afterPOST`:
+
+```text
+POST /checkout/shopper-orders/v1/organizations/{orgId}/orders
+  -> commits order in CREATED
+
+PATCH /checkout/shopper-orders/v1/organizations/{orgId}/orders/{orderNo}/payment-instruments/{piId}
+  -> invokes dw.order.payment.authorizeCreditCard or dw.order.payment.authorize
+  -> passes successfullyAuthorized to order.payment_instrument.afterPATCH
+  -> default afterPATCH places when authorized coverage reaches the order total
+
+NEW     -> success
+CREATED -> not fully placed; authorize remaining PIs, fail safely, or reconcile
+```
+
+Return `undefined` from a successful custom order-PI `afterPATCH` implementation so the platform's
+default coverage-based placement behavior runs. A non-null `Status` ends execution and suppresses
+that implementation.
+
+On a deterministic payment failure, use the Shopper Orders fail action with `reopenBasket=true`.
+On an indeterminate gateway result, retain the `CREATED` order for reconciliation rather than
+risking a duplicate authorization.
+
+Use `dw.ocapi.shop.order.afterPOST` as the alternative when checkout deliberately needs a single
+server-side phase that creates, authorizes, and performs the Commerce-side place-or-fail transition,
+or when the processor cannot participate in order-PI authorization. That hook runs inside order
+creation's transaction: do not add a nested `Transaction.wrap`, and understand that `Status.ERROR`
+rolls back the Commerce order but not an external gateway side effect. See
+"Alternative: Authorize and Place in `order.afterPOST`" in the `b2c-hooks` skill.
+
+## OrderMgr API Reference
+
+### Order Creation
+
+| Method | Description |
+|--------|-------------|
+| `createOrder(basket)` | Create order with auto-generated number |
+| `createOrder(basket, orderNo)` | Create order with specific number |
+| `createOrderNo()` | Generate next order number |
+| `createOrderSequenceNo()` | Get next sequence number (for custom formatting) |
+
+### Order Status
+
+| Method | Description |
+|--------|-------------|
+| `placeOrder(order)` | Place order (CREATED → NEW) |
+| `failOrder(order, reopenBasket)` | Fail order (set to FAILED status) |
+| `cancelOrder(order)` | Cancel order (set to CANCELLED status) |
+| `undoCancelOrder(order)` | Revert cancelled order to NEW |
+
+**Note:** There is no `undoFailOrder()` method. Failed orders cannot be reopened. Use `failOrder(order, true)` to reopen the basket for retry.
+
+### Order Queries
+
+| Method | Description |
+|--------|-------------|
+| `getOrder(orderNo)` | Get order by number |
+| `searchOrder(query, ...args)` | Search for single order |
+| `searchOrders(query, sortString, ...args)` | Search for multiple orders |
+| `queryOrder(query, ...args)` | Query single order |
+| `queryOrders(query, sortString, ...args)` | Query multiple orders |
+
+## Querying Orders
+
+### Get Order by Number
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+
+var order = OrderMgr.getOrder('00001234');
+
+if (order) {
+    var status = order.status.value;
+    var total = order.totalGrossPrice;
+}
+```
+
+### Search Orders
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+
+// Search by customer email
+var orders = OrderMgr.searchOrders(
+    'customerEmail = {0} AND status != {1}',
+    'creationDate desc',
+    'customer@example.com',
+    dw.order.Order.ORDER_STATUS_FAILED
+);
+
+while (orders.hasNext()) {
+    var order = orders.next();
+    // Process order
+}
+orders.close();
+```
+
+### Query by Date Range
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Calendar = require('dw/util/Calendar');
+
+var startDate = new Calendar();
+startDate.add(Calendar.DAY_OF_YEAR, -7);
+
+var orders = OrderMgr.searchOrders(
+    'creationDate >= {0} AND status = {1}',
+    'creationDate desc',
+    startDate.time,
+    dw.order.Order.ORDER_STATUS_NEW
+);
+
+while (orders.hasNext()) {
+    var order = orders.next();
+    // Process order
+}
+orders.close();
+```
+
+## Order Status Management
+
+### Cancel Order
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Transaction = require('dw/system/Transaction');
+var Order = require('dw/order/Order');
+
+function cancelOrder(orderNo) {
+    var order = OrderMgr.getOrder(orderNo);
+
+    if (!order) {
+        return { error: true, message: 'Order not found' };
+    }
+
+    // Can only cancel NEW or OPEN orders
+    if (order.status.value !== Order.ORDER_STATUS_NEW &&
+        order.status.value !== Order.ORDER_STATUS_OPEN) {
+        return { error: true, message: 'Order cannot be cancelled' };
+    }
+
+    Transaction.wrap(function() {
+        OrderMgr.cancelOrder(order);
+    });
+
+    return { error: false };
+}
+```
+
+### Fail Order
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Transaction = require('dw/system/Transaction');
+
+function failOrder(order, reopenBasket) {
+    // reopenBasket: true = customer can retry checkout
+    //               false = basket is lost
+
+    Transaction.wrap(function() {
+        OrderMgr.failOrder(order, reopenBasket);
+    });
+}
+```
+
+### Handling Failed Orders
+
+**Failed orders cannot be reopened.** Instead, use `failOrder(order, true)` to reopen the basket:
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Transaction = require('dw/system/Transaction');
+
+// When payment fails, fail the order and reopen basket
+function handlePaymentFailure(order) {
+    Transaction.wrap(function() {
+        // reopenBasket=true allows customer to retry checkout
+        OrderMgr.failOrder(order, true);
+    });
+
+    // Basket is now available again for the customer
+    return { error: true, message: 'Payment failed. Please try again.' };
+}
+```
+
+### SCAPI: Fail Order and Reopen Basket
+
+For SCAPI integrations, use the Shopper Orders fail action after a deterministic payment failure:
+
+```http
+POST /checkout/shopper-orders/v1/organizations/{orgId}/orders/{orderNo}/actions/fail?siteId={siteId}&reopenBasket=true
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+    "reasonCode": "payment_auth_failure"
+}
+```
+
+The current payment-oriented reason codes are `payment_auth_failure`, `payment_confirm_failure`, and
+`payment_capture_failure`. The endpoint returns `409` when the order is no longer in a state that can
+be failed. Confirm the current Shopper Orders schema before generating version-specific code.
+
+### Undo Cancelled Order
+
+Cancelled orders can be reopened using `undoCancelOrder()`:
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Transaction = require('dw/system/Transaction');
+var Order = require('dw/order/Order');
+
+function reopenCancelledOrder(orderNo) {
+    var order = OrderMgr.getOrder(orderNo);
+
+    if (order.status.value !== Order.ORDER_STATUS_CANCELLED) {
+        return { error: true, message: 'Order is not cancelled' };
+    }
+
+    Transaction.wrap(function() {
+        // Revert to NEW status
+        OrderMgr.undoCancelOrder(order);
+    });
+
+    return { error: false, order: order };
+}
+```
+
+## Order Properties
+
+| Property | Description |
+|----------|-------------|
+| `orderNo` | Order number |
+| `status` | Current order status |
+| `confirmationStatus` | Confirmation status |
+| `exportStatus` | Export status for OMS |
+| `paymentStatus` | Payment status |
+| `shippingStatus` | Shipping status |
+| `customerEmail` | Customer email |
+| `customerName` | Customer name |
+| `totalGrossPrice` | Order total (with tax) |
+| `totalNetPrice` | Order total (without tax) |
+| `totalTax` | Total tax amount |
+| `creationDate` | Order creation date |
+| `productLineItems` | Line items in order |
+| `shipments` | Order shipments |
+| `paymentInstruments` | Payment instruments |
+
+## Custom Order Numbers
+
+Use the `dw.order.createOrderNo` hook for custom order number generation:
+
+```javascript
+// hooks.json
+{
+    "hooks": [
+        {
+            "name": "dw.order.createOrderNo",
+            "script": "./hooks/orderNo.js"
+        }
+    ]
+}
+```
+
+```javascript
+// hooks/orderNo.js
+var OrderMgr = require('dw/order/OrderMgr');
+var Site = require('dw/system/Site');
+
+exports.createOrderNo = function() {
+    var seqNo = OrderMgr.createOrderSequenceNo();
+    var prefix = Site.current.ID.toUpperCase();
+    var year = new Date().getFullYear();
+
+    return prefix + '-' + year + '-' + seqNo;
+};
+```
+
+## Best Practices
+
+### Do
+
+- Wrap Script API order mutations in a transaction only when the caller does not already provide one
+- Check order status before transitions
+- Close order iterators when done
+- Use `failOrder(order, true)` to let customers retry
+- Implement idempotent order creation (use specific order numbers)
+- Set appropriate export/confirmation status
+
+### Don't
+
+- Place orders before successful payment authorization
+- Cancel orders without refund processing
+- Leave orders in CREATED status indefinitely
+- Forget to handle concurrent order modifications
+- Skip status validation before transitions
+
+## Error Handling
+
+| Scenario | Solution |
+|----------|----------|
+| Basket is empty | Validate basket before `createOrder()` |
+| Invalid basket | Check for missing shipping/billing addresses |
+| Payment failed | Use `failOrder(order, true)` to reopen basket |
+| Order number exists | Use auto-generated numbers or validate uniqueness |
+| Status transition invalid | Check current status before calling status methods |
+
+## Related Skills
+
+- `b2c-hooks` skill - Order hooks (calculate, payment, createOrderNo)