@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/commerce-location-delivery-processing-time-configure/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: commerce-location-delivery-processing-time-configure
+description: "Use this skill when users want to use this workflow when an admin wants a SPECIFIC location (or several) to use a different delivery processing time than the group-wide default set on DeliveryEstimationSetup. Trigger when users mention update, location, delivery, processing, time."
+metadata:
+  version: "1.0"
+---
+
+# Managing Update Location Delivery Processing Time
+
+## When to Use This Skill
+
+Use this workflow when an admin wants a SPECIFIC location (or several) to use a
+different delivery processing time than the group-wide default set on
+DeliveryEstimationSetup. Each Location in the setup's LocationGroup carries its own
+optional DefaultProcessingTime + DefaultProcessingTimeUnit; when null, the location
+inherits the DeliveryEstimationSetup default. Resolve the setup, list its locations
+(each with its current override or "uses default"), let the admin pick one or more,
+warn if a temporary override is active (shadowing read), PATCH those Location records,
+verify, then push once (see below).
+
+PRECEDENCE (why the shadowing read exists): most-specific-active wins — a temporary
+ProcessingTimeSpec within its window, THEN a per-location override, THEN the group-wide
+setup default. Because a temporary spec outranks a per-location override, setting a
+location's processing time while an active temporary spec covers that location is a
+silent no-op within the spec's window. So when the chosen setup has a linked temporary spec
+(resolve.active_spec_ids, at the chosen index, non-null), check-active-override reads its
+window + scope and warns the admin before the PATCH — it does NOT block (setting the override is still
+valid; it simply takes effect once the temporary window passes).
+
+Contracts verified live against a Core org (2026-08-03, setup "west" group, location
+Warehouse-SFxmhlV):
+
+  1. Location.DefaultProcessingTime (int) + DefaultProcessingTimeUnit (restricted
+     picklist Hours|Days|Weeks) are UPDATEABLE and OPTIONAL (nillable). PATCH to a
+     value sets an override (HTTP 204); PATCH both to null CLEARS the override so the
+     location falls back to the setup default (verified: null round-trips).
+
+  2. PROPAGATION IS BY THE SETUP's ExternalReference, NOT the location's. The push
+     endpoint (postCommerceDeliveryEstimationConfiguration) rejects a Location's
+     ExternalReference with HTTP 403 INVALID_INPUT "A Delivery Estimation Setup
+     record doesn't exist with external reference <ref>". So after editing location
+     overrides, propagate by delegating ONE enable-and-push keyed on the parent
+     DeliveryEstimationSetup's ExternalReference — that re-pushes the whole config
+     incl. the location overrides. A location's ExternalReference is display-only.
+
+  3. Same restricted picklist as the setup: Hours | Days | Weeks; an out-of-set unit
+     → HTTP 400 INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST.
+
+  4. SHADOWING BY A TEMPORARY SPEC (precedence live-confirmed 2026-08-05). A temporary
+     ProcessingTimeSpec linked to the setup (DeliveryEstimationSetup.ProcessingTimeSpecId)
+     outranks a per-location override within its start..end window (temporary > location >
+     group-default). check-active-override surfaces this as a warning before the PATCH.
+     CONFIRMED LIVE on "west": with the location holding a 12-Day override and a 1-Hour
+     temporary spec (window Aug 5-12) linked to the setup, EstimateDeliveryDate returned a
+     ship date of cutoff + 1 HOUR (not + 12 days) — the temporary time masked the location
+     override, exactly as the warning predicts. SCOPE CAVEAT (still holds): the list endpoint
+     returns the window + counts (locationOverrideCount) but NOT the scoped location Ids, so
+     the pre-PATCH warning is window/count-based, not a precise per-location match.
+
+## Workflow
+
+Per-location delivery processing-time overrides (companion to
+update-delivery-estimation-setup, which sets the group-wide default). Flow:
+
+### Phase 1: resolve-delivery-estimation-setup → by Name → LocationGroupId + ExternalReference
+
+resolve-delivery-estimation-setup → by Name → LocationGroupId + ExternalReference
+     (+ the group default, for display) + ProcessingTimeSpecId (active_spec_ids — the
+     linked temporary override, if any) for EVERY match; the agent picks one when the
+     lookup is ambiguous and reads all fields at that same index from then on.
+
+### Phase 2: list-locations-in-group → LocationGroupAssignment (junction) → Location details
+
+list-locations-in-group → LocationGroupAssignment (junction) → Location details;
+     present each location's current override or "uses default". Admin picks one or
+     more.
+
+### Phase 3: check-active-override → SHADOWING READ (read-and-warn, never block). If
+
+check-active-override → SHADOWING READ (read-and-warn, never block). If
+     resolve.active_spec_ids at the chosen index is non-null, read the linked temporary ProcessingTimeSpec's
+     window + scope and warn that within that window its scoped locations use the
+     temporary time — so the per-location override being set won't take effect until the
+     window passes (temporary > location). Skipped internally when no spec is linked.
+
+### Phase 4: update-location-processing-time → PATCH each chosen
+
+update-location-processing-time → PATCH each chosen
+     Location.DefaultProcessingTime / DefaultProcessingTimeUnit (loop). null clears an
+     override → inherit the setup default. Restricted picklist Hours|Days|Weeks.
+
+### Phase 5: verify-location-processing-time → re-read the changed locations
+
+verify-location-processing-time → re-read the changed locations.
+
+### Phase 6: enable-and-push-delivery-estimation → ONE delegated push, keyed on the...
+
+enable-and-push-delivery-estimation → ONE delegated push, keyed on the SETUP's
+     ExternalReference (NOT a location's — that 403s), to propagate.
+
+Live-verified on a Core org (2026-08-03, setup "west", location Warehouse-SFxmhlV):
+  • PATCH Location {DefaultProcessingTime:2, DefaultProcessingTimeUnit:"Hours"} → 204;
+    read-back 2/Hours. PATCH {null,null} → 204; read-back null/null (override cleared).
+  • Push with the LOCATION's ExternalReference → HTTP 403 INVALID_INPUT (a
+    DeliveryEstimationSetup ExternalReference is required); propagation is by the
+    setup's ExternalReference only.
+  • temporary-spec-shadows-a-location-override precedence — CONFIRMED LIVE 2026-08-05: with
+    Warehouse-SFxmhlV holding a 12-Day override and a 1-Hour temporary spec (window Aug 5-12)
+    linked to "west", EstimateDeliveryDate returned ship = cutoff + 1 HOUR (not + 12 days), so
+    the temporary time masked the location override (temporary > location > group-default),
+    exactly as check-active-override warns.
+
+For the group-wide default (all locations), use update-delivery-estimation-setup
+instead.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Commerce Order Management with Delivery Estimation must be enabled (the
+DeliveryEstimationSetup + Location objects exist and the group has
+LocationGroupAssignments). (check: `Delivery Estimation enabled + LocationGroup populated`)
+- The running user must have Edit access on Location AND field-level Edit on
+Location.DefaultProcessingTime / DefaultProcessingTimeUnit. Without it the PATCH
+returns 403, or the fields are silently dropped. (check: `UserPermissions edit on Location + FLS on the two fields`)
+- A DeliveryEstimationSetup record (with a LocationGroup + LocationGroupAssignments)
+must exist. This workflow overrides locations within that group; it does not create
+records. (check: `DeliveryEstimationSetup + LocationGroupAssignments exist`)
+
+**Operational rules:**
+
+- PRECEDENCE: most-specific-active wins — a temporary ProcessingTimeSpec within its
+window, then a per-location override, then the group-wide setup default. That is why
+step 3 runs the shadowing read before the PATCH: a linked temporary spec can mask the
+new per-location override within its window (mirrors the same-named guard on the
+group-default path in update-delivery-estimation-setup).
+- CUSTOMER-FACING WORDING: once verify-location-processing-time confirms the values AND
+enable-and-push-delivery-estimation completes, say exactly: "Your change has been saved
+and synced." Follow with a compact recap: Name, ExternalReference, and the field(s)
+changed in plain language, old -> new (e.g. "default processing time: 2 Days -> 3 Days")
+— never the API field name itself (DefaultProcessingTime/Unit) — per changed
+location. If you have the Location Id, add a best-effort link:
+[<Name>](<orgHost>/lightning/r/Location/<Id>/view) — the standard record-link form used
+across the corpus; never speak the raw Id itself.
+MATCH BY Id, NOT ARRAY POSITION: verify-location-processing-time.updated_locations /
+location_names / location_external_references all come from ONE query response so they're
+aligned WITH EACH OTHER by index, but SOQL's `WHERE Id IN (...)` does NOT guarantee its
+response is ordered to match locationUpdates' input order. When building a multi-row recap,
+match each locationUpdates[] entry to its row in updated_locations by comparing Id — never
+assume row i of the recap corresponds to locationUpdates[i].
+RECAP LAYOUT — ONE location changed: a single plain sentence with the Name link-wrapped.
+MULTIPLE locations changed (the SELECT above can return several): use a compact markdown
+table instead of repeating sentences —
+  | Location | Reference | Changed |
+  |---|---|---|
+  | [<Name>](<orgHost>/lightning/r/Location/<Id>/view) | <ExternalReference> | default processing time: <old> -> <new> |
+One row per changed location. In a table, every row needs the same number of cells — if a
+Location's ExternalReference is blank/null, put "—" in that cell rather than dropping it; only
+drop the Reference column entirely if EVERY row lacks one. Keep the whole response under ~200
+characters of VISIBLE text where possible for a single-location change (the link URL doesn't count — soft target, the
+recap's completeness wins over strict truncation). Never say
+"CDS", "Commerce Delivery Service", or "delivery estimation service" to the customer —
+it's one seamless save, not two systems. Still don't surface sObject / field API names,
+raw HTTP codes, or the Connect path.
+
+## Verification Checklist
+
+After every write operation, confirm the effect by re-reading state:
+
+- After `update-location-processing-time`: call `verify-location-processing-time`
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `resolve-delivery-estimation-setup` | read | implemented | `querySoql` | — |
+| `list-locations-in-group` | read | implemented | `querySoql` | `resolve-delivery-estimation-setup` |
+| `check-active-override` | read | implemented | `getProcessingTimeSpecDefinitions` | `resolve-delivery-estimation-setup`, `list-locations-in-group` |
+| `update-location-processing-time` | write | implemented | `updateLocation` | `list-locations-in-group`, `check-active-override` |
+| `verify-location-processing-time` | verify | implemented | `querySoql` | `update-location-processing-time` |
+| `enable-and-push-delivery-estimation` | write | — | → `cc-om-fast-and-furious/enable-and-push-delivery-estimation-setup` | `verify-location-processing-time` |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  resolve_delivery_estimation_setup["resolve-delivery-estimation-setup (read)"]
+  list_locations_in_group["list-locations-in-group (read)"]
+  check_active_override["check-active-override (read)"]
+  update_location_processing_time["update-location-processing-time (write)"]
+  verify_location_processing_time["verify-location-processing-time (verify)"]
+  enable_and_push_delivery_estimation["enable-and-push-delivery-estimation (write)"]
+  resolve_delivery_estimation_setup --> list_locations_in_group
+  resolve_delivery_estimation_setup --> check_active_override
+  list_locations_in_group --> check_active_override
+  list_locations_in_group --> update_location_processing_time
+  check_active_override --> update_location_processing_time
+  update_location_processing_time --> verify_location_processing_time
+  verify_location_processing_time --> enable_and_push_delivery_estimation
+```
+
+### Read operations
+
+#### `resolve-delivery-estimation-setup`
+
+Resolve the parent DeliveryEstimationSetup by Name and capture its LocationGroupId
+(to list the group's locations), ExternalReference (needed for the propagation push
+in the final step), and ProcessingTimeSpecId (the linked temporary override, if any —
+read by check-active-override so we can warn when a temporary spec would shadow the
+location override being set). Skip if the caller already has both.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `name` *(`String`)* — The DeliveryEstimationSetup's Name OR ExternalReference (e.g. "west") — the query
+matches either field. Source: user_input.
+
+#### `list-locations-in-group`
+
+List the locations in the setup's LocationGroup with each one's current override.
+Reads LocationGroupAssignment (the group→location junction) then the Location
+details. Present each location as "override N <Unit>" or "uses default" so the
+admin can choose which to change.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `locationGroupId` *(`String`)* — LocationGroup Id (0gh...) of the CHOSEN setup. Source: resolve-delivery-estimation-setup.location_group_ids (the one the customer picked when the lookup matched more than one).
+
+**Depends on:** `resolve-delivery-estimation-setup`
+
+#### `check-active-override`
+
+SHADOWING READ. If the chosen setup has a linked temporary override
+(resolve.active_spec_ids, at the chosen index, non-null), read that ProcessingTimeSpec's
+window + scope from the Commerce Delivery list so the admin can be warned that within its
+active window the per-location override being set will not take effect for the spec's
+scoped locations (precedence: a temporary spec within its window outranks a per-location
+override). Read-and-warn: does NOT block the PATCH. Skip the API call entirely when that
+value is null (no linked spec). This is the location-path counterpart of the same-named step
+in update-delivery-estimation-setup, which guards the group-default PATCH.
+
+**Call:** `getProcessingTimeSpecDefinitions`   — status: `implemented`
+
+**Inputs:**
+
+- `activeSpecId` *(`String`)* — The CHOSEN setup's linked ProcessingTimeSpec Id (1fH...). Source:
+resolve-delivery-estimation-setup.active_spec_ids (the one the customer picked when the
+lookup matched more than one), read at that same chosen index. When null there is no
+linked temporary override — skip this step's read.
+
+**Depends on:** `resolve-delivery-estimation-setup`, `list-locations-in-group`
+
+### Write operations
+
+#### `update-location-processing-time`
+
+Apply the per-location override(s). For EACH location the admin chose, PATCH
+Location.DefaultProcessingTime / DefaultProcessingTimeUnit. Setting both to null
+CLEARS the override (the location reverts to the setup default). Loop over the
+selected locations — one PATCH per Location record.
+
+**Call:** `updateLocation`   — status: `implemented`
+
+**Inputs:**
+
+- `locationUpdates` *(`Array`)* — One entry per location being changed. Each entry: the Location Id plus the new
+DefaultProcessingTime + DefaultProcessingTimeUnit (or both null to clear the
+override → inherit the setup default). Include only locations that are actually
+changing. Source: user selection over list-locations-in-group.
+  - schema: `{'type': 'array', 'maxItems': 200, 'items': {'type': 'object', 'required': ['locationId'], 'properties': {'locationId': {'type': 'string', 'pattern': '^131[a-zA-Z0-9]{12,15}$', 'description': 'Location Id to update (from list-locations-in-group).'}, 'DefaultProcessingTime': {'type': ['integer', 'null'], 'description': 'New processing time (whole number); null clears the override.'}, 'DefaultProcessingTimeUnit': {'type': ['string', 'null'], 'pattern': '^(Hours|Days|Weeks)$', 'x-codey-enum-source': 'Location.DefaultProcessingTimeUnit', 'description': 'New unit — Hours | Days | Weeks (restricted); null clears the override.'}}}}`
+
+**Depends on:** `list-locations-in-group`, `check-active-override`
+
+**Rollback:** {'operation': 'updateLocation', 'invocation': {'kind': 'rest', 'method': 'PATCH', 'path': '/services/data/v67.0/sobjects/Location/{locationId}', 'body': {'DefaultProcessingTime': '{list-locations-in-group.locations_before[?(@.LocationId==locationId)].Location.DefaultProcessingTime}', 'DefaultProcessingTimeUnit': '{list-locations-in-group.locations_before[?(@.LocationId==locationId)].Location.DefaultProcessingTimeUnit}'}}}
+
+#### `enable-and-push-delivery-estimation`
+
+Propagate the location override(s) so the change takes effect end-to-end. Delegates to
+enable-and-push-delivery-estimation-setup — ONE push, keyed on the PARENT
+DeliveryEstimationSetup's ExternalReference (NOT any location's). That single push
+re-sends the whole configuration, including the per-location overrides just set.
+
+**Delegates to:** `cc-om-fast-and-furious/enable-and-push-delivery-estimation-setup`
+
+**Depends on:** `verify-location-processing-time`
+
+### Verify operations
+
+#### `verify-location-processing-time`
+
+Re-read the changed Location records and confirm each now holds the requested override (or null, if the override was cleared).
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `locationIds` *(`Array`)* — Ids of the changed locations (from locationUpdates[].locationId). Source:
+update-location-processing-time. The query's {locationIdsInClause} is the SOQL-safe
+rendering of THIS input — a comma-separated list of single-quoted Ids (see
+agent_guidance) — not a separate input.
+
+**Depends on:** `update-location-processing-time`

package/skills/commerce-location-graph-integrate/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: commerce-location-graph-integrate
+description: "Use this skill when users want to use this workflow to propagate a Location-graph-affecting change downstream — BOPIS pickup eligibility (enable-location-bopis), a per-location pickup time window, or a ShippingCarrierMethod / LocationShippingCarrierMethod change (update-location-shipping-carrier-method) — to the. Trigger when users mention sync, location, graph."
+metadata:
+  version: "1.0"
+---
+
+# Managing Sync Location Graph
+
+## When to Use This Skill
+
+Use this workflow to propagate a Location-graph-affecting change downstream — BOPIS pickup
+eligibility (enable-location-bopis), a per-location pickup time window, or a
+ShippingCarrierMethod / LocationShippingCarrierMethod change
+(update-location-shipping-carrier-method) — to the external Commerce Delivery Service. A
+freshly-changed field isn't reflected in a delivery/pickup estimate until this publish
+completes.
+
+triggerFullLocationGraphSync takes NO parameters — it always publishes the FULL graph (every
+location), not a scoped subset. This is a delegation target, most commonly reached via
+delegates_to from another SOR right after that SOR's own change is verified; it can also run
+standalone.
+
+WIRE CONTRACT (verified live 2026-08-07 on bopis, as part of enable-location-bopis before this
+extraction): POST /services/data/v68.0/commerce/delivery/location-graph/uploads with NO body ->
+201 {id, status:"New", type:"CdsFullLocationGraphSync", success:true} on enqueue. The SAME path's
+GET (checkFullLocationGraphSyncStatus) reports status.
+
+TERMINAL-STATE CONTRACT — WIRE GOTCHA (traced 2026-08-22 against Core source, not just a class's
+own doc-comment): the OAS's `status`/`type` PROPERTY NAMES are swapped from their actual
+semantics on the wire. The lifecycle values (New/InProgress/Completed/Error) arrive in the wire's
+`status` key even though the OAS enumerates them under the property it names `type` — confirmed
+by the live-recorded response above ({status:"New", type:"CdsFullLocationGraphSync"} — "New" is
+a lifecycle value, "CdsFullLocationGraphSync" is an operation-kind value). Terminal success =
+status "Completed"; terminal failure = status "Error" OR "ServiceException" (the shipped
+Location Management UI's own status check tests for "ServiceException", not the OAS-declared
+"Error" — the shipped code and the OAS doc disagree, so both are treated as failure here); New /
+InProgress = still running.
+ERROR CONTENT DIFFERS BY FAILURE STATUS (traced 2026-08-24): "Error" is Core's curated
+validation-failure path — its `error` field carries a real per-location message explicitly
+designed for end-user display. "ServiceException" is a DIFFERENT, generic/transport-level
+failure path (traced to the remoting call itself erroring, not a validation outcome) — every
+observed example has an EMPTY error field, and there is no evidence its content is safe to show
+customers on the rare case it isn't empty. Treat these two statuses differently when deciding
+what to relay — see the poll step's own agent_guidance.
+
+ENQUEUE IS NOT TERMINAL: the POST only enqueues; the downstream copy is not current until the
+poll below reaches "Completed". Never say "saved and synced" merely because the enqueue POST
+returned successfully.
+
+## Workflow
+
+Publish the full location graph downstream and poll to terminal success. Two steps:
+
+### Phase 1: publish-location-graph -> POST triggerFullLocationGraphSync, NO params -> enqueues...
+
+publish-location-graph -> POST triggerFullLocationGraphSync, NO params -> enqueues (status
+     "New", not yet synced).
+
+### Phase 2: poll-location-graph-sync-status -> bounded poll (every ~5s, up to...
+
+poll-location-graph-sync-status -> bounded poll (every ~5s, up to 12 attempts) of
+     checkFullLocationGraphSyncStatus until status reaches Completed (success) or
+     Error/ServiceException (failure) or the attempts are exhausted (still in progress).
+
+## Critical Constraints
+
+**Preconditions:**
+
+- The Delivery Estimation Service / location-graph feature must be enabled in the org, or the
+publish is rejected. (check: `Delivery Estimation / location-graph sync enabled`)
+
+**Operational rules:**
+
+- DELEGATED vs STANDALONE: when invoked via delegates_to from another SOR (enable-location-bopis,
+update-location-shipping-carrier-method, or any future caller), stay SILENT on completion — the
+delegating SOR owns the single closing message + recap for the entity IT changed; this SOR is
+silent plumbing to that caller. Only when invoked STANDALONE (an admin asked to publish/sync
+directly, not through another SOR) does this SOR say the closing line itself.
+- CUSTOMER-FACING WORDING (standalone only, terminal success): this SOR never writes/saves
+anything itself — it only republishes whatever is CURRENTLY in Core. Say "Your location data
+has been synced." NOT the "saved and synced" canonical line — that line implies a change was
+just saved, which is only true for a DELEGATING caller that performed a write before handing
+off here; a standalone invocation may simply be a manual re-publish with no new change at all.
+This SOR doesn't create/own any entity and takes no per-entity input
+(triggerFullLocationGraphSync is always a full, unscoped sync) — there's no single record to
+name, so that one sentence is the whole standalone reply; no recap or link is possible here. On
+terminal failure, see the poll step's own agent_guidance — use poll_error to say WHAT is wrong,
+comparing the location(s) it names against any the caller has in mind before assuming it's
+unrelated. Never say "CDS", "Commerce Delivery Service", or otherwise imply there are two
+separate systems. Don't surface sObject/field API names, the Connect path, Ids, or raw HTTP
+codes — poll_error's own message is already customer-appropriate, no further raw detail needed.
+Keep the standalone reply under ~200 characters where possible (soft target, not a hard limit).
+
+## Verification Checklist
+
+After every write operation, confirm the effect by re-reading state:
+
+- After `publish-location-graph`: call `poll-location-graph-sync-status`
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `publish-location-graph` | write | implemented | `triggerFullLocationGraphSync` | — |
+| `poll-location-graph-sync-status` | verify | implemented | `checkFullLocationGraphSyncStatus` | `publish-location-graph` |
+
+### Write operations
+
+#### `publish-location-graph`
+
+Publish the full location graph downstream. Runs with NO parameters — always a full sync, not
+a scoped one.
+
+**Call:** `triggerFullLocationGraphSync`   — status: `implemented`
+
+### Verify operations
+
+#### `poll-location-graph-sync-status`
+
+Poll the location-graph sync job (enqueued by publish-location-graph) to terminal success. The
+enqueue POST only returns status:"New" — the downstream copy is not current, and the change is
+not actually synced yet, until this poll reaches a terminal state.
+
+**Call:** `checkFullLocationGraphSyncStatus`   — status: `implemented`
+
+**Depends on:** `publish-location-graph`