@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/commerce-fulfillment-routing-analyze/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: commerce-fulfillment-routing-analyze
+description: "Use this skill when users want to use this workflow when a customer, CSR, or admin needs to understand why an order was fulfilled from a specific location. Trigger when users mention fulfillment, routing, explanation."
+metadata:
+  version: "1.0"
+  accessCheck: "(FulfillmentOrder.OrderSummaryId) || (OrderManagement.ReadFulfillmentOrder) || (OrderManagement.orgHasOrderManagementEnabled)"
+---
+
+# Querying Fulfillment Routing Explanation
+
+## When to Use This Skill
+
+Use this workflow when a customer, CSR, or admin needs to understand why
+an order was fulfilled from a specific location. The workflow resolves
+an OrderNumber to its OrderSummary, finds all associated FulfillmentOrders,
+then calls the routing explanation API for each to surface:
+  • The winning routing criterion that determined the location
+  • Per-rule scoring and contributions to the routing decision, as a table
+  • Line-item allocation (fulfilled vs. requested vs. available elsewhere),
+    as a table
+  • Split-order context when multiple locations fulfill parts of one order
+
+Presentation is table-first and customer-centric: routing details, rule
+contributions, and line items render as markdown tables by default, not
+just on request. This is a read-only diagnostic workflow — it explains
+past routing decisions but does not modify routing or re-route orders.
+
+## Workflow
+
+fulfillment-routing-explanation is a READ-ONLY diagnostic workflow. It
+does not modify routing, re-route orders, or change fulfillment assignments.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Org must have Order Management enabled with fulfillment routing configured (check: `OrderManagement.orgHasOrderManagementEnabled`)
+- User must have access to Order Management features and fulfillment data (check: `OrderManagement.ReadFulfillmentOrder`)
+- The OrderSummary must have at least one FulfillmentOrder created. Orders
+still in cart/checkout phase or canceled before fulfillment began will
+have no FulfillmentOrders to explain. (check: `FulfillmentOrder.OrderSummaryId`)
+
+**Operational rules:**
+
+- EXECUTION PATH:
+  1. resolve-order-summary-by-number → OrderNumber → OrderSummary Id
+     (skip if caller has the Id directly)
+  2. query-fulfillment-orders → find all FulfillmentOrders for this
+     OrderSummary; detect split-order case
+  3. get-routing-explanation → call once per FulfillmentOrder to get
+     routing details
+  4. synthesize-explanation → consolidate explanations into a customer-facing
+     report: one lead sentence plus markdown tables for routing details,
+     rule contributions, and line items (single-location or split-order)
+- SPLIT-ORDER HANDLING:
+When query-fulfillment-orders returns multiple FOs, call
+get-routing-explanation for EACH one in sequence, then consolidate in
+synthesize-explanation. Label each FO by its FulfillmentOrderNumber and
+location so the customer knows which items come from where.
+- FAILURE CASES:
+- No FulfillmentOrders found: order hasn't reached fulfillment or was
+  canceled early. Surface friendly message and STOP.
+- 404 on routing-explanation: routing explanation not available (manual
+  assignment or pre-explanation era). Fall back to basic location info
+  from FulfilledFromLocation.Name.
+- Permission errors: surface to user and STOP.
+- CUSTOMER-FACING WORDING:
+- Use "location" not "Location record"
+- Use "order" not "OrderSummary"
+- Use "items" not "OrderItemSummary"
+- Translate routing criterion names to plain language (proximity, inventory,
+  cost, speed, preference)
+- No raw Ids, field names, or sObject types in customer text
+- REPORTING FORMAT (see synthesize-explanation for the full spec):
+- Table-first, not prose-first. Rule contributions and line-item
+  allocations are always rendered as markdown tables, not gated behind
+  "if the customer asks for detail."
+- One lead sentence, then tables. Don't pad tabular data with a
+  restating paragraph underneath it.
+- Split orders get an overview table across all fulfillment orders, then
+  a rule-breakdown + items table pair per fulfillment order.
+- WHEN TO USE THIS WORKFLOW:
+- "Why was my order sent from location X?"
+- "Why are my items coming from different places?"
+- "How did the system decide on this fulfillment location?"
+- "Explain the routing for order #{orderNumber}"
+- DO NOT USE for:
+- Changing fulfillment location (use re-routing workflows)
+- Canceling or modifying fulfillment orders
+- Viewing shipment tracking (use shipment status workflows)
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `resolve-order-summary-by-number` | read | implemented | `querySoql` | — |
+| `query-fulfillment-orders` | read | implemented | `querySoql` | `resolve-order-summary-by-number` |
+| `get-routing-explanation` | read | implemented | `getFulfillmentOrderRoutingExplanation` | `query-fulfillment-orders` |
+| `synthesize-explanation` | read | implemented | `conversational_synthesis` | `get-routing-explanation` |
+
+### Read operations
+
+#### `resolve-order-summary-by-number`
+
+Resolve a customer-provided OrderNumber to its OrderSummary Id.
+Customers and CSRs work with OrderNumber (the printed order number);
+the fulfillment APIs require the internal OrderSummary Id (1Os...).
+
+IMPORTANT: OrderNumber is NOT unique — a single OrderNumber can resolve
+to multiple OrderSummaries (orgs reuse it across storefronts/locales).
+When this step returns more than one row, surface candidates and ask
+which one before proceeding.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `orderNumber` *(`String`)* — Customer-facing OrderNumber (from receipt/confirmation email).
+Skip this step if caller already has the OrderSummary Id (1Os...).
+
+#### `query-fulfillment-orders`
+
+Query all FulfillmentOrders associated with the OrderSummary.
+One OrderSummary can have multiple FulfillmentOrders when the order
+is split across locations (e.g., some items from warehouse A, others
+from store B). Each FulfillmentOrder has its own routing explanation.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `orderSummaryId` *(`String`)* — OrderSummary Id from resolve-order-summary-by-number, or passed
+directly by caller.
+  - **Source:** output of `resolve-order-summary-by-number`
+
+**Depends on:** `resolve-order-summary-by-number`
+
+#### `get-routing-explanation`
+
+Call the routing explanation API for a specific FulfillmentOrder.
+Returns sections-based routing explanation with the winning criterion, per-rule
+contributions, location details, and line item information.
+
+API contract (OMS Connect API v68.0 / min version 264):
+GET /commerce/fulfillment/fulfillment-orders/{fulfillmentOrderId}/routing-explanation
+
+Returns sections-based structure:
+- success: boolean indicating API call success
+- location: string - winning location name (top-level field)
+- sections[]: array of section objects, each with:
+  - name: section identifier ("summary", "rules", "lineItems")
+  - rows[]: array of free-form Map<String,Object> with dynamic keys
+
+NOTE: rows[] fields are @ConnectHidden(from=Apex) - REST/UI-API only.
+Each row is a free-form key-value map with dynamic keys specific to the
+section type. Keys vary by routing strategy and configuration.
+
+**Call:** `getFulfillmentOrderRoutingExplanation`   — status: `implemented`
+
+**Inputs:**
+
+- `fulfillmentOrderId` *(`String`)* — FulfillmentOrder.Id from query-fulfillment-orders $.records[].Id.
+Extracted per-iteration from the loop.
+  - **Source:** output of `query-fulfillment-orders`
+- `fulfillmentOrderNumber` *(`String`)* — FulfillmentOrder.FulfillmentOrderNumber from query-fulfillment-orders
+$.records[].FulfillmentOrderNumber. Used for labeling in split-order scenarios.
+  - **Source:** output of `query-fulfillment-orders`
+
+**Depends on:** `query-fulfillment-orders`
+
+#### `synthesize-explanation`
+
+Final step: synthesize all routing explanations into a single
+customer-facing report of markdown tables. When multiple
+FulfillmentOrders exist (split order), this step consolidates their
+individual explanations into one coherent set of tables — see
+agent_guidance below for the full table spec.
+
+This is a conversational synthesis step — no API call, just presentation
+logic that threads outputs from get-routing-explanation.
+
+**Call:** `conversational_synthesis`   — status: `implemented`
+
+**Inputs:**
+
+- `fulfillment_order_count` *(`integer`)* — Total number of FulfillmentOrders (from query-fulfillment-orders)
+  - **Source:** output of `query-fulfillment-orders`
+- `routing_explanations` *(`Array`)* — Array of routing explanation outputs from get-routing-explanation,
+accumulated from the per-FO loop. Each array element is an object with:
+fulfillment_order_number, success, location, whyItWon, whyItWonTooltip
+(optional), selectionScore, selectionScoreTooltip (optional),
+unitsFilled, rules (array, each row's isOverride optional), lineItems
+(array, each row's elsewhere optional).
+  - **Source:** output of `get-routing-explanation`
+
+**Depends on:** `get-routing-explanation`

package/skills/commerce-guest-buyer-create/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: commerce-guest-buyer-create
+description: "Use this skill when users want to use this workflow when a user wants to register an existing Account as a (guest) buyer for a specific Commerce webstore — the prerequisite that lets that account shop, or be shopped-on-behalf-of, in that store. Trigger when users mention register, guest, buyer."
+metadata:
+  version: "1.0"
+  accessCheck: "(Account.exists) || (OrderManagement.orgHasRegisterGuestBuyerAPIEnabled) || (WebStore.READ)"
+---
+
+# Managing Register Guest Buyer
+
+## When to Use This Skill
+
+Use this workflow when a user wants to register an existing Account as a (guest) buyer for a specific Commerce webstore — the prerequisite that lets that account shop, or be shopped-on-behalf-of, in that store. Registration enrolls the account as a buyer for the store, adds it to the store's buyer group, and marks the account as a buyer; the confirmation should tell the user the account can now shop the store (and is in its buyer group), not just report "success".
+
+Scope boundaries (pick-signal):
+- The Account must ALREADY EXIST. This workflow does not create accounts, does not do buyer-group / entitlement setup beyond that enrollment, and does not start any shopping / cart / pricing flow — those live in separate SORs.
+- B2B stores ONLY. B2CE and B2C stores are rejected by the server (ERROR_ENABLING_BUYER). Do NOT pre-check store Type client-side — attempt the call and translate the error. (Wire-verified: B2B ok, B2CE 400.)
+- Portal users are NOT allowed (allowsPortalUsers=false on the resource).
+- Idempotent: re-registering an already-registered account returns success:true again (wire-verified) — safe to re-run.
+
+Never echo raw 0ZE / 001 Ids or the raw error envelope to a buyer — translate success and errors to friendly language and offer a next step on failure. See agent_guidance and steps[] for the path parameters, empty POST body, response handling, and precondition gates.
+
+## Workflow
+
+### Phase 1: discover-webstores -> numbered menu of store Names; user...
+
+discover-webstores  -> numbered menu of store Names; user picks one.
+                          The chosen record's Id becomes webstoreId.
+
+### Phase 2: account-input choice -> if the user gave a...
+
+account-input choice -> if the user gave a 001 Id: by-id (skip lookup).
+                          If they gave a name: by-name -> identify-account
+                          resolves Name -> accountId.
+
+### Phase 3: register-guest-buyer -> POST (empty body); read success/errors
+
+register-guest-buyer -> POST (empty body); read success/errors.
+
+- The register endpoint is POST-only and takes NO body — the two path
+  params (webstoreId 0ZE, accountId 001) are the whole contract. The
+  response is success + errors only; there is no entity payload, so
+  $.success is the confirmation. The call returns HTTP 200 for BOTH success
+  and business-rule failures — always branch on $.success, never on the
+  HTTP status alone.
+
+- What registration ACCOMPLISHES (wire-verified): it enrolls the account as
+  a buyer for the store AND adds it to that store's buyer group, and flips
+  Account.IsBuyer to true. So the success message should tell the user the
+  account can now shop the store (and is in its buyer group) — that is the
+  user-visible outcome, not just "success:true".
+
+- B2B ONLY — do NOT pre-check the store Type client-side. Registration works
+  on B2B stores; B2CE (and B2C) are rejected by the server with a clear
+  error (ERROR_ENABLING_BUYER, "not supported for B2CE store"). Let the API
+  be the authority and translate its error rather than maintaining a
+  client-side Type allow-list that could drift. WIRE-VERIFIED on q3Sdb27:
+  BrightBundle Co (B2B) succeeded; RefArch USD (B2CE) returned 400
+  success:false.
+
+- Idempotent: re-registering an already-registered account on the same store
+  returns success:true again (no error) — safe to re-run without a pre-check.
+  WIRE-VERIFIED on q3Sdb27.
+
+- Pre-validate both Id shapes at the agent layer to fail fast (0ZE / 001).
+
+- Preconditions: org gate Register Guest Buyer API enabled
+  + user check userHasRegisterGuestBuyerAPIAccess. Portal users are not
+  permitted (allowsPortalUsers=false).
+
+- The Account must ALREADY EXIST. This SOR does not create accounts and does
+  not start shopping — those are separate workflows (out of scope).
+
+- Customer-friendly wording: never echo raw 0ZE / 001 Ids, the raw error
+  envelope, or errorCode strings; translate success and errors to plain
+  language and always offer a next step on failure.
+
+- Request body detail: the register action takes an EMPTY body — the RegisterGuestBuyerInputRepresentation has no fields, so send {} / no body. (The endpoint is the Order Management Repricing API register-guest-buyer action; see the register-guest-buyer step.)
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Org must have the Order Management Register Guest Buyer Connect API
+enabled — this is the x-sfdc org-access-check on the postRegisterGuestBuyer
+endpoint. Without it, the call returns FEATURE_NOT_ENABLED.
+ (check: `Register Guest Buyer API enabled`)
+- Calling user must pass the resource's user dynamic check
+userHasRegisterGuestBuyerAPIAccess (declared on RegisterGuestBuyerResource
+via userDynamicChecks). Without it the call is rejected (403); surface a
+friendly access message, never the raw exception.
+ (check: `userHasRegisterGuestBuyerAPIAccess`)
+- The target Account (001-prefixed) must already exist. This SOR does NOT
+create accounts — if the user references an account that doesn't exist,
+resolve/confirm it first (identify-account) or stop and tell the user the
+account must be created before it can be registered as a buyer.
+ (check: `Account.exists`)
+- Caller needs READ access to WebStore (to list/select the store) and to
+Account (to resolve the account by name). Portal users are not permitted
+(the resource sets allowsPortalUsers=false).
+ (check: `WebStore.READ`)
+
+**Operational rules:**
+
+- TYPICAL FLOW
+- KEY CONTRACTS (source-verified against the Register Guest Buyer resource):
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `discover-webstores` | read | implemented | `querySoql` | — |
+| `identify-account` | read | implemented | `querySoql` | — |
+| `register-guest-buyer` | write | implemented | `postRegisterGuestBuyer` | `discover-webstores` |
+
+### Read operations
+
+#### `discover-webstores`
+
+Enumerate Commerce webstores with Id, Name, and Type. Runs FIRST; no
+choice gate (always executes). The agent presents Names to the user and
+threads the chosen record's Id into the register step as webstoreId.
+
+
+**Call:** `querySoql`   — status: `implemented`
+
+#### `identify-account`
+
+Resolve an Account by name to its 001-prefixed Id. Runs ONLY when the user
+supplied a company / account NAME rather than an Id (account-input = by-name).
+Skipped when the user already gave a 001 Id.
+
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `accountName` *(`String`)* — The company / account name (or fragment) the user gave. Matched with a
+LIKE filter; present matches for the user to pick when more than one.
+WILDCARD SAFETY: before binding, escape SOQL LIKE metacharacters in the
+user's input — backslash-escape `\`, `%`, and `_` (\\ , \%, \_) so a
+user cannot pass a bare `%`/`_` to enumerate every visible Account. A
+lone `%` or empty string must be rejected, not run as "match all".
+
+### Write operations
+
+#### `register-guest-buyer`
+
+Register the selected Account as a (guest) buyer for the selected webstore.
+POST to the Order Management Repricing API register-guest-buyer action.
+The request body is EMPTY — the whole contract is the two path params.
+Response carries success + errors only (no entity payload).
+
+
+**Call:** `postRegisterGuestBuyer`   — status: `implemented`
+
+**Inputs:**
+
+- `webstoreId` *(`String`)* — WebStore Id from discover-webstores (the store the user picked).
+Pre-validate against ^0ZE[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$ before invoking.
+
+  - **Source:** output of `discover-webstores`
+- `accountId` *(`String`)* — Account Id (001-prefixed) to register as a buyer. Sourced from
+identify-account when the user gave a name (account-input = by-name), or
+supplied directly by the user (by-id). Pre-validate against
+^001[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$ before invoking.
+
+
+**Depends on:** `discover-webstores`