@salesforce/afv-skills 1.65.0 → 1.66.0

package/skills/commerce-temporary-processing-time-override-create/SKILL.md

@@ -1,274 +0,0 @@
----
-name: commerce-temporary-processing-time-override-create
-description: "Use this skill when users want to use this workflow when a customer wants a delivery processing time to apply only for a PERIOD (e.g. Trigger when users mention create, temporary, processing, time, override."
-metadata:
-  version: "1.0"
----
-
-# Managing Create Temporary Processing Time Override
-
-## When to Use This Skill
-
-Use this workflow when a customer wants a delivery processing time to apply only for a
-PERIOD (e.g. a holiday) rather than as a permanent default. It creates a
-ProcessingTimeSpec via the Commerce Delivery Connect API
-(POST /commerce/delivery/processing-time-specs, operation createProcessingTimeSpecDefinition,
-owned by CC OM Royal Flush), which persists a FulfmtRoutgSpec of Type='ProcessingTime'
-with a start/end date, a processing time + unit, and location/product scope, assigned to
-one or more DeliveryEstimationSetup records. This SOR is the pivot target of
-update-delivery-estimation-setup (chosen when the customer wants a temporary, not
-permanent, change).
-
-Contracts verified live against a Core org (Connect API v67.0, 2026-08-03, setup "west"):
-
-  1. AT LEAST ONE location OR product is REQUIRED at runtime even though the OAS marks
-     every field optional. An empty payload (period + time only) → HTTP 400
-     MISSING_ARGUMENT "Select at least one location or product." Always include at least
-     one locationId (or productSourceId).
-
-  2. The setup is linked by its 18-char Id (deliveryEstimationSetupIds), NOT by
-     ExternalReference — the opposite of the enable-and-push endpoint. Get the Id from
-     resolve-delivery-estimation-setup.setup_ids (the customer-chosen index, if the lookup
-     matched more than one).
-
-  3. processingTimeUnit is the same restricted set as the permanent fields:
-     Hours | Days | Weeks.
-
-  4. WIRE SHAPE: the list fields are nested wrappers, verified live:
-     locations: {locations: [{locationId}]}, products: {products: [{productSourceId,
-     type}]} (type ∈ PRODUCT | CATEGORY), deliveryEstimationSetupIds:
-     {deliveryEstimationSetupIds: [<setupId>]}. startDate/endDate are ISO-8601 date-time.
-
-  5. A successful create returns HTTP 200/201 {success:true, errors:[], id:<1fH...>}
-     (verified: 201). The list read (GET /commerce/delivery/processing-time-specs) echoes
-     it under definitions[] with processingTimeRange ("5 Days"), startDate/endDate,
-     locationOverrideCount, deliveryEstimationSetupCount.
-
-  6. NO CLEAN API UNDO. The Connect delete (deleteFulfmtRoutgSpec, keyed on
-     externalReference) returned HTTP 500 UNKNOWN_EXCEPTION for a Core-only (unsynced)
-     spec, and a direct sObject delete of FulfmtRoutgSpec is 403
-     INSUFFICIENT_ACCESS_OR_READONLY. Treat a temporary override as self-expiring at its
-     endDate; to cancel one early, set isActive=false / remove it via the Processing Time
-     Setup UI — do NOT rely on an API delete as rollback.
-
-  7. PROPAGATION TO THE CDS. A created spec exists in Core but is NOT live in the external
-     Commerce Delivery Service until it is synced. This workflow's final step
-     (sync-to-delivery-service) delegates to sync-delivery-routing-specs, ALWAYS with a
-     TARGETED single-spec sync of just this new spec (syncSingleFulfmtRoutgSpec, POST
-     /commerce/delivery/fulfillment-routing-specs/sync/{specId}) — hardcoded, never asked, and
-     never an org-wide bulk from this flow, so only this override is pushed. Verified live: a
-     created spec is absent from the CDS until synced (single-spec sync 2026-08-05 -> 201).
-
-## Workflow
-
-Create a TEMPORARY, time-boxed delivery processing-time override (holiday/seasonal), as
-opposed to the permanent field change in update-delivery-estimation-setup /
-update-location-delivery-processing-time. Flow:
-
-### Phase 1: resolve-delivery-estimation-setup → by Name → setup Id (link...
-
-resolve-delivery-estimation-setup → by Name → setup Id (link is BY ID) + LocationGroupId.
-
-### Phase 2: list-locations-in-group → present the group's locations; customer picks...
-
-list-locations-in-group → present the group's locations; customer picks which the
-     override covers (≥1 location OR product required). ALWAYS also ask whether to limit the
-     override to specific products/SKUs (or categories) vs. ALL products — omitting products
-     is not a skip, it applies to all products at the chosen locations.
-
-### Phase 3: create-temporary-override → POST /commerce/delivery/processing-time-specs with the
-
-create-temporary-override → POST /commerce/delivery/processing-time-specs with the
-     period (startDate/endDate), processingTime + unit (Hours|Days|Weeks), the location/
-     product scope (nested wrappers), and deliveryEstimationSetupIds=[setup Id]. Success =
-     200/201 {success:true, id:<1fH...>}.
-
-### Phase 4: verify-temporary-override → GET the list; confirm the new...
-
-verify-temporary-override → GET the list; confirm the new spec's period + range.
-
-### Phase 5: sync-to-delivery-service → runs AUTOMATICALLY, never asked — delegates...
-
-sync-to-delivery-service → runs AUTOMATICALLY, never asked — delegates to
-     sync-delivery-routing-specs with sync-scope HARDCODED to single (this flow only ever
-     creates one spec, so that's always the correct scope) to push the new spec live. A spec
-     exists in Core but is NOT live until synced. (A full org-wide reconcile, if genuinely
-     needed, is a separate standalone invocation of sync-delivery-routing-specs — not reachable
-     from this flow.)
-
-Live-verified on a Core org (2026-08-03, setup "west"):
-  • Empty scope → 400 MISSING_ARGUMENT ("Select at least one location or product").
-  • With one location → 201 {success:true, id:1fH...}; GET list shows processingTimeRange
-    "5 Days", the Dec 24–26 window, locationOverrideCount 1, deliveryEstimationSetupCount 1.
-  • Delete is unreliable: deleteFulfmtRoutgSpec → 500 (unsynced spec); sObject delete → 403.
-    So the override self-expires at endDate; early cancel = deactivate / Setup UI.
-
-This SOR is the PIVOT TARGET of update-delivery-estimation-setup (chosen when the customer
-wants a temporary, not permanent, change). CUSTOMER-FACING WORDING: verify-temporary-override
-reports the window + new time as an interim status (not "done" yet); only AFTER
-sync-to-delivery-service confirms should the agent say the canonical closing line verbatim —
-"Your change has been saved and synced." — followed by a short recap: the new override's own
-Name + ExternalReference (the values sent to create-temporary-override — FulfmtRoutgSpec has
-both fields; the create API doesn't echo them back, so echo what you sent) + the window + time,
-plus a best-effort link if you have spec_id:
-[<name>](<orgHost>/lightning/r/FulfmtRoutgSpec/<spec_id>/view) — the standard record-link
-form used across the corpus; link text is the Name, not the raw Id.
-RECAP LAYOUT — ONE override created: a single plain sentence with the Name link-wrapped. If
-the customer asked for the SAME override across MULTIPLE setups in this conversation (this SOR
-creates one spec per run), give ONE consolidated table at the end instead of repeated
-sentences — | Setup | Override | Reference | Window | Time | header row, one row per created
-override, same shape as the sibling per-location SORs' multi-row recap. The Setup cell is the
-chosen setup's own Name (resolve-delivery-estimation-setup.matched[<chosen index>].Name) and is
-the ONLY column that distinguishes the rows when the customer reused one override name/window
-across setups — never drop it in the multi-row form.
-Keep a single-override response
-under ~200 characters of VISIBLE text where possible (soft target — the link URL itself
-doesn't count against this, only what the customer reads). Never SPEAK a raw Id,
-sObject/field API names, HTTP codes, or the words "CDS"/
-"Commerce Delivery Service" — describe the save as one seamless action, not two systems.
-
-## Critical Constraints
-
-**Preconditions:**
-
-- Commerce Order Management with Delivery Estimation + the fulfillment-routing / CDS
-FulfmtRoutgSpec feature (Delivery Routing Engine) must be enabled, so the
-ProcessingTimeSpec Connect resource is reachable. (check: `Delivery Estimation + CDS FulfmtRoutgSpec feature enabled`)
-- A DeliveryEstimationSetup record (with a LocationGroup + LocationGroupAssignments) must
-exist to scope the override to; obtain its Id + locations via
-resolve-delivery-estimation-setup / list-locations-in-group. (check: `DeliveryEstimationSetup + locations exist`)
-
-## Verification Checklist
-
-After every write operation, confirm the effect by re-reading state:
-
-- After `resolve-delivery-estimation-setup`, `create-temporary-override`: call `verify-temporary-override`
-
-## 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` |
-| `create-temporary-override` | write | implemented | `createProcessingTimeSpecDefinition` | `resolve-delivery-estimation-setup`, `list-locations-in-group` |
-| `verify-temporary-override` | verify | implemented | `getProcessingTimeSpecDefinitions` | `resolve-delivery-estimation-setup`, `create-temporary-override` |
-| `sync-to-delivery-service` | write | — | → `cc-om-fast-and-furious/sync-delivery-routing-specs` | `verify-temporary-override` |
-
-### Dependency graph
-
-```mermaid
-graph TD
-  resolve_delivery_estimation_setup["resolve-delivery-estimation-setup (read)"]
-  list_locations_in_group["list-locations-in-group (read)"]
-  create_temporary_override["create-temporary-override (write)"]
-  verify_temporary_override["verify-temporary-override (verify)"]
-  sync_to_delivery_service["sync-to-delivery-service (write)"]
-  resolve_delivery_estimation_setup --> list_locations_in_group
-  resolve_delivery_estimation_setup --> create_temporary_override
-  list_locations_in_group --> create_temporary_override
-  resolve_delivery_estimation_setup --> verify_temporary_override
-  create_temporary_override --> verify_temporary_override
-  verify_temporary_override --> sync_to_delivery_service
-```
-
-### Read operations
-
-#### `resolve-delivery-estimation-setup`
-
-Resolve the parent DeliveryEstimationSetup by Name and capture its Id (the temporary
-spec links by Id) and LocationGroupId (to offer the group's locations). Skip if the
-caller already has the setup Id + a target location/product.
-
-**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 setup's group locations so the customer can pick which the temporary override
-applies to (at least one location OR product is required). Reads LocationGroupAssignment
-then Location details.
-
-**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`
-
-### Write operations
-
-#### `create-temporary-override`
-
-Create the temporary ProcessingTimeSpec via the Commerce Delivery Connect API. Persists a
-FulfmtRoutgSpec (Type='ProcessingTime' — set server-side) with the period, processing
-time + unit, location/product scope, and setup assignment.
-
-**Call:** `createProcessingTimeSpecDefinition`   — status: `implemented`
-
-**Inputs:**
-
-- `startDate` *(`String`)* — Override period start, ISO-8601 date-time (e.g. 2026-12-24T00:00:00.000Z).
-- `endDate` *(`String`)* — Override period end, ISO-8601 date-time. The override applies only between startDate and endDate, then self-expires. MUST be strictly after startDate.
-- `processingTime` *(`Integer`)* — Temporary processing time as a whole number (must be a positive integer).
-- `processingTimeUnit` *(`String`)* — Unit — RESTRICTED to Hours | Days | Weeks.
-- `locationIds` *(`Array`)* — Location Ids the override applies to (from list-locations-in-group). At least one
-location OR product is REQUIRED (empty scope → 400 MISSING_ARGUMENT). Each becomes a
-locations.locations[] entry {locationId}.
-  - schema: `{'type': 'array', 'items': {'type': 'string', 'pattern': '^131[a-zA-Z0-9]{12,15}$'}}`
-  - **Source:** output of `list-locations-in-group`
-- `products` *(`Array`)* — Product/category scope. Each entry {productSourceId, type} where type ∈ PRODUCT |
-CATEGORY. Supply this OR locationIds (at least one of the two is required at runtime).
-NOT NEUTRAL WHEN OMITTED: leaving products empty does NOT skip product scoping — it
-applies the override to ALL products at the selected location(s). Because that silently
-widens the blast radius, the agent MUST always ask the customer whether to limit the
-override to specific products/SKUs (or categories) before creating; only then is
-"all products" a deliberate, confirmed choice. The field stays optional so a
-location-only (all-products) override remains valid once explicitly confirmed.
-  - schema: `{'type': 'array', 'items': {'type': 'object', 'properties': {'productSourceId': {'type': 'string'}, 'type': {'type': 'string', 'pattern': '^(PRODUCT|CATEGORY)$'}}}}`
-- `deliveryEstimationSetupId` *(`String`)* — The CHOSEN setup's 18-char Id (NOT ExternalReference). Source: resolve-delivery-estimation-setup.setup_ids (the one the customer picked when the lookup matched more than one). Becomes deliveryEstimationSetupIds.deliveryEstimationSetupIds[].
-- `name` *(`String`)* — Human label for the spec (e.g. "Winter Holiday 2026"). REQUIRED — this is the primary
-identifier the closing recap uses for this record; the create API never echoes it back,
-so it must be captured up front. Ask the customer for one if they haven't given it; if
-they have no preference, propose a reasonable label from the window (e.g. "Dec 24-26
-Override") and confirm it with them rather than leaving it blank.
-- `externalReference` *(`String`)* — A stable business reference for this override — used as a recap/identification field (same
-as name) and as the key the underlying delete mechanism looks up by internally. REQUIRED. Ask
-the customer if they have a preferred reference; if not, derive a slug from the name (e.g.
-"National Day 2026" -> "national-day-2026") rather than leaving it blank. See agent_guidance.
-
-**Depends on:** `resolve-delivery-estimation-setup`, `list-locations-in-group`
-
-#### `sync-to-delivery-service`
-
-Propagate the newly-created ProcessingTimeSpec to the external Commerce Delivery
-Service. A spec created above exists in Core but is NOT live in the CDS until it is
-synced. Delegates to sync-delivery-routing-specs with sync-scope hardcoded to single —
-this flow only ever creates ONE spec, so that's always the correct scope; never asked,
-never left to a default that could silently drift to org-wide.
-
-**Delegates to:** `cc-om-fast-and-furious/sync-delivery-routing-specs`
-
-**Depends on:** `verify-temporary-override`
-
-### Verify operations
-
-#### `verify-temporary-override`
-
-Confirm the temporary override was created by reading the ProcessingTimeSpec list and finding the new spec.
-
-**Call:** `getProcessingTimeSpecDefinitions`   — status: `implemented`
-
-**Inputs:**
-
-- `deliveryEstimationSetupId` *(`String`)* — The CHOSEN setup Id, to read its ProcessingTimeSpecId back. Source: resolve-delivery-estimation-setup.setup_ids (the one the customer picked when the lookup matched more than one).
-
-**Depends on:** `resolve-delivery-estimation-setup`, `create-temporary-override`