@salesforce/afv-skills 1.65.0 → 1.65.1

package/skills/commerce-delivery-routing-specs-integrate/SKILL.md

@@ -1,174 +0,0 @@
----
-name: commerce-delivery-routing-specs-integrate
-description: "Use this skill when users want to use this workflow to propagate FulfmtRoutgSpec changes — most commonly a ProcessingTimeSpec temporary override just created by create-temporary-processing-time-override — to the external Commerce Delivery Service (CDS). Also use when you created/changed one spec and want only it to go live. Trigger when users mention sync, delivery, routing, specs."
-metadata:
-  version: "1.0"
-  accessCheck: "CommerceDelivery.orgHasDeliveryRoutingEngineFeatureEnabled"
----
-
-# Managing Sync Delivery Routing Specs
-
-## When to Use This Skill
-
-Use this workflow to propagate FulfmtRoutgSpec changes — most commonly a ProcessingTimeSpec
-temporary override just created by create-temporary-processing-time-override — to the external
-Commerce Delivery Service (CDS). A spec created/edited in Core is NOT live in the CDS until it
-is synced. Two modes, chosen via the sync-scope choice_point:
-
-  1. SINGLE (targeted): syncSingleFulfmtRoutgSpec — POST
-     /commerce/delivery/fulfillment-routing-specs/sync/{specId} — pushes just ONE spec, by its
-     1fH... Id. Use when you created/changed one spec and want only it to go live. Smaller blast
-     radius. Verified live on bopis (2026-08-05): 201 {success:true, errors:[]}.
-  2. ALL (org-wide bulk): syncAllFulfmtRoutgSpecs — POST
-     /commerce/delivery/fulfillment-routing-specs/sync (no body) — loads and pushes EVERY
-     FulfmtRoutgSpec in the org. Full reconcile; also re-pushes any other pending specs.
-     Verified live on bopis (2026-08-04): 201.
-
-Both are owned by CC OM Not Hotdog and gated by "Delivery Routing Engine enabled". NOTE: the
-single-spec endpoint is live in Core but currently MISSING from the generated OAS/corpus (a
-generation-staleness gap — the raw Core source spec lists it), so it's authored here against the
-verified live Core contract (minVersion 262 = API v62+, path {specId}, no request body, 201).
-
-## Workflow
-
-Propagate FulfmtRoutgSpec changes to the external Commerce Delivery Service. TWO modes via the
-sync-scope choice_point:
-  - single -> sync-single-fulfillment-routing-spec: POST
-    /commerce/delivery/fulfillment-routing-specs/sync/{specId} (spec Id in path, no body) —
-    pushes ONLY that spec. Verified live 2026-08-05 (201). Requires a 1fH... spec Id.
-  - all -> sync-all-fulfillment-routing-specs: POST
-    /commerce/delivery/fulfillment-routing-specs/sync (no body, or an optional
-    fulfmtRoutgSpecSyncInput.type filter — ProcessingTime | Markdown) — bulk sync of every spec,
-    or every spec of one type. Verified live 2026-08-04 (201, unscoped).
-
-Prefer SINGLE right after creating/editing one spec (e.g. a holiday ProcessingTimeSpec):
-pass that spec's id. Use ALL for a full reconcile, or when no single id is in hand (single
-requires the spec Id); when the caller knows the spec's Type, pass it on the ALL branch too
-(type=ProcessingTime / type=Markdown) so an org-wide reconcile can't be failed by a malformed,
-unrelated spec of the other type sharing the same bulk batch.
-
-This is the propagation step a ProcessingTimeSpec needs to go live — a created spec exists in
-Core but isn't fully in effect until synced. It's the delegation target of
-create-temporary-processing-time-override — a deterministic caller (see the EXCEPTION above):
-it only ever creates ONE spec per run, so it hardcodes sync-scope: single and passes the new
-spec id, without asking. Can also run standalone after any FulfmtRoutgSpec create/edit.
-
-## Critical Constraints
-
-**Preconditions:**
-
-- The Delivery Routing Engine feature must be enabled in the org (Connect org-access-check
-"Delivery Routing Engine enabled"), or the sync is rejected. (check: `Delivery Routing Engine enabled`)
-
-**Operational rules:**
-
-- ASK which scope the customer wants (default single — smaller blast radius) — this MUST be an
-explicit customer choice, never a silently-guessed default, even when this SOR is reached via
-delegates_to: a delegating SOR must surface the question, not guess on the customer's behalf.
-- EXCEPTION — deterministic callers may hardcode instead of asking: the "always ask" rule exists
-to stop an AMBIGUOUS scope being silently guessed wrong (that was the actual 2026-08-17
-incident — an agent defaulted to a scope it wasn't sure about). It does NOT apply when the
-calling SOR's own flow makes the correct scope a certainty rather than a guess. The bar for
-this is a STRUCTURAL invariant in the caller's OWN steps, provable by reading them — not a
-feeling that a scope is "probably" right. e.g. create-temporary-processing-time-override only
-ever creates exactly ONE spec per run (its create step has no fan-out, no loop, no batch input),
-so "single" is the only correct answer there; asking would just be friction over a question with
-one possible answer, not a real choice. That caller hardcodes sync-scope: single unconditionally.
-A future caller claiming this exception must be able to point to the equivalent structural
-guarantee in its own flow (e.g. "this step processes exactly one record because X"), not just
-assert confidence — when a caller's own scope IS genuinely ambiguous (it doesn't know in
-advance whether the customer wants one spec or a full reconcile), it must still ask.
-- CORPUS NOTE: the single-spec sync is live in Core but missing from the generated OAS (staleness
-gap; the raw Core source spec lists it) — authored against the verified live contract.
-- DELEGATED vs STANDALONE: when invoked via delegates_to from another SOR, stay silent on
-completion — the delegating SOR owns the single closing message to the customer. Only when
-invoked STANDALONE (directly, not via delegation) should this SOR itself say the canonical
-closing line below.
-- CUSTOMER-FACING WORDING (standalone only): this SOR never writes/saves anything itself — it
-only pushes whatever already exists in Core (same reasoning as the sibling sync-location-graph)
-— NOT the "saved and synced" canonical line, which implies a write just happened here; that
-write, if any, belongs to whichever caller created/edited the spec before reaching this SOR.
-Say which spec(s) were synced, not just "synced" generically:
-  - SINGLE: "Your routing spec has been synced." — this SOR only ever receives the raw specId
-    (1fH...) as input — no Name or ExternalReference. Never speak that raw Id in prose. Instead
-    give a best-effort link with NEUTRAL anchor text (you don't have a friendly name to use):
-    [view routing spec](<orgHost>/lightning/r/FulfmtRoutgSpec/<specId>/view) — keep the `]` and
-    `(` on the same line with no space/break between them, or the Markdown link renders broken.
-    If the caller (a delegating SOR) already named the spec by its own Name/ExternalReference in
-    ITS recap, this branch is DELEGATED, not standalone, so you're silent anyway (see above) —
-    this wording only fires when an admin invoked sync-delivery-routing-specs directly with a
-    bare Id and no other SOR is speaking for them.
-  - ALL: no single entity to name or link. If a type filter (ProcessingTime/Markdown) was
-    sent, say "Your <type> routing specs have been synced." (e.g. "Your processing-time
-    routing specs have been synced.") — NOT the unqualified "all routing specs," which
-    overclaims scope when only one type was actually touched. Only say "Your routing specs
-    have been synced." (unqualified) when NO type filter was sent — a genuinely unscoped,
-    every-type sync.
-RECAP LAYOUT — MULTIPLE syncs standalone in one conversation (e.g. "sync spec A and spec B" —
-two sync-scope: single calls with different spec Ids — or "sync all processing-time specs,
-then all markdown specs" — two sync-scope: all calls with different type filters): give ONE
-consolidated table instead of repeating the sentence form per sync —
-  | Spec / Scope | Outcome |
-  |---|---|
-  | [view routing spec](<orgHost>/lightning/r/FulfmtRoutgSpec/<specId>/view) | synced |
-  | all processing-time specs | synced |
-One row per sync performed in this conversation. For a SINGLE-mode row, reuse the same
-best-effort NEUTRAL-anchor-text link as above (still no friendly name to show — the anchor
-text is identical across rows, only the link target differs). For an ALL-mode row, name the
-type filter if one was sent (e.g. "all processing-time specs"), or "all routing specs" if
-unscoped. Use whichever outcome word applies (synced / could not be synced — see the SINGLE/ALL
-guidance above for what failure looks like). Say the canonical opening line once, before the
-table, if every row synced — e.g. "Your routing specs have been synced." Omit it only when a
-row could not be synced, since that's the one outcome it would misstate; in that case name the
-failed rows separately from the succeeded ones.
-Keep it under ~200 characters of VISIBLE text where possible (soft target — the link URL
-doesn't count). Never say "CDS",
-"Commerce Delivery Service", or "delivery service" as something distinct from the setup change
-— describe it as one seamless save. Don't surface the Connect path, sObject names, or
-raw HTTP codes.
-
-## Operations Reference
-
-Operations grouped by purpose. Use these as the building blocks for the workflows above.
-
-### Summary
-
-| Operation | Purpose | Status | Call | Depends on |
-|-----------|---------|--------|------|------------|
-| `sync-single-fulfillment-routing-spec` | write | implemented | `syncSingleFulfmtRoutgSpec` | — |
-| `sync-all-fulfillment-routing-specs` | write | implemented | `syncAllFulfmtRoutgSpecs` | — |
-
-### Write operations
-
-#### `sync-single-fulfillment-routing-spec`
-
-Targeted sync — push a SINGLE FulfmtRoutgSpec (e.g. the ProcessingTimeSpec just created) to
-the Commerce Delivery Service by its Id, so only that spec goes live in the CDS.
-
-**Call:** `syncSingleFulfmtRoutgSpec`   — status: `implemented`
-
-**Inputs:**
-
-- `specId` *(`String`)* — The FulfmtRoutgSpec / ProcessingTimeSpec Id to sync (1fH...). Provided by the caller at
-invocation: a delegating SOR passes it (e.g. create-temporary-processing-time-override's
-create-temporary-override.spec_id), or a standalone admin supplies it directly (e.g.
-DeliveryEstimationSetup.ProcessingTimeSpecId).
-
-#### `sync-all-fulfillment-routing-specs`
-
-Org-wide bulk sync — load every FulfmtRoutgSpec for the org (optionally scoped to one Type)
-and push the bulk payload to the Commerce Delivery Service, making all Core-side spec changes
-live at once.
-
-**Call:** `syncAllFulfmtRoutgSpecs`   — status: `implemented`
-
-**Inputs:**
-
-- `type` *(`String`)* — Optional FulfmtRoutgSpec.Type to scope the bulk sync to (ProcessingTime | Markdown). Omit
-to sync every FulfmtRoutgSpec regardless of type — verified server-side
-(CDSFulfmtRoutgSpecSyncRequestMapper): no body, or a blank type, is explicitly
-backward-compatible and syncs all types. SET THIS whenever the caller only cares about one
-type (e.g. delegated from a ProcessingTime-only flow): the bulk endpoint loads + PUTs every
-matching spec in ONE call, so one malformed/incompatible spec of the OTHER type elsewhere in
-the org can fail the entire batch even though the spec you care about is fine. An
-unrecognized value 400s (INVALID_INPUT).

package/skills/commerce-estimate-bopis-query/SKILL.md

@@ -1,279 +0,0 @@
----
-name: commerce-estimate-bopis-query
-description: "Use this skill when users want to use this workflow when someone wants a real-time BUY-ONLINE-PICKUP-IN-STORE (BOPIS) estimate — \"which stores can I pick this up from?\", \"when can I collect these items in store?\", \"find pickup locations near <address>\". Trigger when users mention estimate, bopis."
-metadata:
-  version: "1.0"
----
-
-# Querying Estimate Bopis
-
-## When to Use This Skill
-
-Use this workflow when someone wants a real-time BUY-ONLINE-PICKUP-IN-STORE (BOPIS) estimate — "which
-stores can I pick this up from?", "when can I collect these items in store?", "find pickup locations
-near <address>". It does NOT change any configuration; it is a read-only estimate over the current
-DeliveryEstimationSetup and its pickup-eligible locations. To turn a location's pickup eligibility
-ON, use the sibling enable-location-bopis skill instead.
-
-It guides the caller through building the request one piece at a time — do not ask for raw JSON:
-pick the DeliveryEstimationSetup, then EITHER name the specific store(s) to check (each must be
-BOPIS/pickup-eligible — this skill verifies that first) OR ask the service to find nearby
-pickup-eligible stores within a radius of an address, choose products + quantities, collect the
-address — then calls EstimateBopis (at API v68.0) and reads back, per store, the earliest pickup
-time, order cutoff, distance, and available inventory.
-
-TWO WAYS TO CHOOSE STORES (the location-selection choice_point): (1) SPECIFIC — the customer names
-the store(s); each named store must be pickup-eligible (the skill checks and, if one isn't, says so
-and offers enable-location-bopis); an address is optional. (2) NEARBY — the customer gives an
-address + a radius and the service returns the closest pickup-eligible stores; here the address,
-radius, and a max-store count are all required.
-
-TWO WAYS TO IDENTIFY THE SETUP (the setup-selection choice_point): (1) FILTER — the default when a
-person runs this skill directly; an optional Name/ExternalReference substring narrows the setup
-list, and the customer picks one. (2) PIN — used when another skill (e.g. enable-location-bopis) has
-already resolved and chosen the setup for you; it hands off the exact record Id and no further
-customer-facing selection happens on this path.
-
-ADMIN/CUSTOMER-FACING WORDING: answer in plain language — e.g. "2 units of SKU-1042 can be picked
-up at Downtown Store (2.8 mi away) from Aug 8, 6:20 PM Pacific; order by Aug 8, 9:59 AM
-Pacific." ALWAYS NAME THE ZONE: the response's times carry an explicit "Z" and are UTC, so quoting
-the raw clock face can be off by a full calendar day (see the estimate step's TIMES ARRIVE AS UTC
-guidance). Multi-store answers go in complete table(s), not a sentence per store — see that step's
-RECAP LAYOUT. Don't surface the Connect path, sObject/field API names, external-reference strings, or raw
-HTTP codes.
-
-## Workflow
-
-Guided real-time BUY-ONLINE-PICKUP-IN-STORE (BOPIS) estimate. Read-only: builds an EstimateBopis
-request with the customer, one piece at a time, and returns each store's pickup estimate. Changes
-nothing. To turn a location's pickup eligibility ON, use enable-location-bopis (this skill only
-reads it).
-
-Flow:
-
-### Phase 1: resolve-delivery-estimation-setup (FILTER) or resolve-setup-by-id (PIN) -> exactly one...
-
-resolve-delivery-estimation-setup (FILTER) or resolve-setup-by-id (PIN) -> exactly one runs, per
-     the setup-selection choice; either way it captures the setup's Id and Name for the recap,
-     ExternalReference (the URL PATH segment), and LocationGroupId. FILTER lists setups for the customer
-     to pick from; PIN resolves the one exact Id a delegating skill already chose — no customer-facing
-     selection on that path.
-
-### Phase 2: list-bopis-eligible-locations -> show the group's stores + pickup...
-
-list-bopis-eligible-locations -> show the group's stores + pickup eligibility. SPECIFIC mode:
-     verify each named store is pickup-eligible (match on ExternalReference); NEARBY mode:
-     informational. If none are eligible, suggest enable-location-bopis and STOP.
-
-### Phase 3: list-products -> present SKU'd products; customer picks products...
-
-list-products -> present SKU'd products; customer picks products + a positive whole-number
-     quantity each.
-
-### Phase 4: estimate-bopis -> build the body per the location-selection...
-
-estimate-bopis -> build the body per the location-selection choice and POST; read back the
-     per-store pickup estimate.
-
-## Critical Constraints
-
-**Preconditions:**
-
-- The Delivery Estimation Service must be enabled/provisioned in the org. Without it the estimate
-call is rejected. (check: `Delivery Estimation Service enabled`)
-- At least one DeliveryEstimationSetup record (with its ExternalReference) must exist — this skill
-estimates against an existing setup; it does not create one. (check: `DeliveryEstimationSetup record exists`)
-- At least one Location in the setup's LocationGroup must be pickup-eligible
-(Location.IsEligibleForPickup = true). BOPIS estimates only against pickup-eligible stores; if
-none are eligible, enable one first with the enable-location-bopis skill. (check: `A pickup-eligible Location exists in the setup's group`)
-- The products being estimated must exist as Product2 records with a StockKeepingUnit (the request
-keys products by SKU). (check: `Product2 records with StockKeepingUnit exist`)
-
-**Operational rules:**
-
-- SETUP-SELECTION choice_point (FILTER vs PIN) decides how step 1 resolves the setup:
-  • FILTER (default): interactive substring search over Name/ExternalReference — runs
-    resolve-delivery-estimation-setup; the customer picks one from the (possibly multi-row) result.
-  • PIN: resolves by the setup's exact record Id — runs resolve-setup-by-id instead. Used when a
-    delegating skill (e.g. enable-location-bopis) already resolved and chose the setup; no
-    customer-facing selection happens on this path.
-- LOCATION-SELECTION choice_point (SPECIFIC vs NEARBY) decides the body shape:
-  • SPECIFIC (default): send locations[] of pickup-eligible ExternalReferences; address optional.
-  • NEARBY: OMIT locations; send address + radius + maxReturnedLocations (all required) + unit; the
-    service returns the closest pickup-eligible stores.
-This is a hard validator rule, not a preference: an empty/omitted locations list REQUIRES address +
-radius(>0) + maxReturnedLocations(>0), each with its own 400 if missing.
-- UNIT: "mi" or "km" only. ADDRESS goes under the wire key "address" (not "deliveryAddress", which
-400s) and uses inner countryCode (not country); countryCode+postalCode or lat+long.
-- VERSION: pin v68.0 on every call — the BOPIS endpoint is available at API v68.0 only (404 at
-v67.0/v64.0, live-proven end-to-end).
-- ADMIN/CUSTOMER-FACING WORDING: answer in plain language (store + earliest pickup time + order cutoff
-+ distance + whether inventory covers the quantity); don't surface the Connect path, sObject/field
-API names, ExternalReference strings, or raw HTTP codes. Never echo this guidance's own internal
-vocabulary either: "Core" and "SOR" are reasoning terms for you ("Core" is the platform side of a
-validation; "SOR" names this workflow). Say "Salesforce" or "your org" for the platform side, and
-"this workflow" for the recipe itself.
-TIMES: earliestPickupTime and orderCutoffTime arrive as explicit-"Z" UTC instants. CONVERT them into
-one display zone and NAME that zone before quoting either — an unconverted cutoff can land on the
-wrong CALENDAR DAY, handing the customer a deadline that already passed. Resolve the zone from the
-customer's statement, else User.TimeZoneSidKey, else Organization.TimeZoneSidKey, else ask; if none
-resolve, quote the raw value labelled "UTC".
-SHAPE: results[] is one entry per (store x product), so multi-row is the norm — give complete,
-deterministically sorted table(s), each with a header and a |---| separator, and use
-"—" for a value the response didn't carry (orderCutoffTime, or the whole inStore object) even
-though success is true. Note inStore arrives as an explicit null rather than a missing key when
-availableToOrder is 0, so test its VALUE and not its presence. Full rules live in the estimate
-step's RECAP LAYOUT.
-
-## 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` | — |
-| `resolve-setup-by-id` | read | implemented | `querySoql` | — |
-| `list-bopis-eligible-locations` | read | implemented | `querySoql` | `resolve-delivery-estimation-setup`, `resolve-setup-by-id` |
-| `list-products` | read | implemented | `querySoql` | `resolve-delivery-estimation-setup`, `resolve-setup-by-id` |
-| `estimate-bopis` | read | implemented | `EstimateBopis` | `resolve-delivery-estimation-setup`, `resolve-setup-by-id`, `list-bopis-eligible-locations`, `list-products` |
-
-### Dependency graph
-
-```mermaid
-graph TD
-  resolve_delivery_estimation_setup["resolve-delivery-estimation-setup (read)"]
-  resolve_setup_by_id["resolve-setup-by-id (read)"]
-  list_bopis_eligible_locations["list-bopis-eligible-locations (read)"]
-  list_products["list-products (read)"]
-  estimate_bopis["estimate-bopis (read)"]
-  resolve_delivery_estimation_setup --> list_bopis_eligible_locations
-  resolve_setup_by_id --> list_bopis_eligible_locations
-  resolve_delivery_estimation_setup --> list_products
-  resolve_setup_by_id --> list_products
-  resolve_delivery_estimation_setup --> estimate_bopis
-  resolve_setup_by_id --> estimate_bopis
-  list_bopis_eligible_locations --> estimate_bopis
-  list_products --> estimate_bopis
-```
-
-### Read operations
-
-#### `resolve-delivery-estimation-setup`
-
-List / resolve the DeliveryEstimationSetup and capture its ExternalReference (the URL path
-segment for the estimate call) and its LocationGroupId (used next to list the group's
-pickup-eligible stores). Optionally filter by a Name/ExternalReference substring.
-
-**Call:** `querySoql`   — status: `implemented`
-
-**Inputs:**
-
-- `nameFilter` *(`String`)* — OPTIONAL Name or ExternalReference filter (e.g. "west"). When provided the query matches either
-field with a LIKE; when omitted, all setups are listed. Source: user_input.
-
-#### `resolve-setup-by-id`
-
-Resolve the ONE DeliveryEstimationSetup whose exact record Id was handed in (the delegated / pinned
-path). Captures the SAME fields as the substring resolve step — Id and Name for recap, plus
-ExternalReference (the estimate URL path segment) and LocationGroupId (the group to list) — so
-every downstream step binds identically regardless of which resolve branch ran.
-
-**Call:** `querySoql`   — status: `implemented`
-
-**Inputs:**
-
-- `setupId` *(`String`)* — The exact DeliveryEstimationSetup record Id (2A0...) to resolve. Source: a delegating skill that
-already resolved AND chose the setup (e.g. enable-location-bopis.resolve-delivery-estimation-setup.setup_ids[chosen]).
-An Id is exact + unique, so this pins the exact setup with no re-search and no Name/ExternalReference
-collision.
-
-#### `list-bopis-eligible-locations`
-
-List the stores in the resolved setup's LocationGroup together with each one's pickup eligibility
-(Location.IsEligibleForPickup), so the caller can (in SPECIFIC mode) confirm the store(s) they
-name are pickup-eligible, or (in NEARBY mode) see which stores are eligible for context. The BOPIS
-request keys locations by Location.ExternalReference, so this step surfaces exactly those
-references.
-
-**Call:** `querySoql`   — status: `implemented`
-
-**Inputs:**
-
-- `locationGroupId` *(`String`)* — LocationGroup Id (0gh...) of the chosen setup. Source: whichever resolve branch ran — resolve-delivery-estimation-setup.location_group_ids[chosen] (filter) or resolve-setup-by-id.location_group_ids[0] (pin).
-
-**Depends on:** `resolve-delivery-estimation-setup`, `resolve-setup-by-id`
-
-#### `list-products`
-
-List Product2 records that have a StockKeepingUnit so the customer can choose which products to
-estimate and enter a quantity for each. Products are keyed by SKU in the request. Optionally filter
-by a Name/SKU substring.
-
-**Call:** `querySoql`   — status: `implemented`
-
-**Inputs:**
-
-- `productFilter` *(`String`)* — OPTIONAL Name or StockKeepingUnit filter. When provided the query matches either with a LIKE;
-when omitted, active products with a SKU are listed. Source: user_input.
-
-**Depends on:** `resolve-delivery-estimation-setup`, `resolve-setup-by-id`
-
-#### `estimate-bopis`
-
-Call EstimateBopis with the assembled request — the resolved setup ExternalReference in the URL
-path, EITHER the chosen pickup-eligible store references (SPECIFIC mode) OR a radius + max store
-count (NEARBY mode), the chosen products + quantities, and the address — and read back, per store,
-the earliest pickup time, order cutoff, distance, and inventory. Read-only: computes an estimate,
-changes nothing.
-
-**Call:** `EstimateBopis`   — status: `implemented`
-
-**Inputs:**
-
-- `externalReference` *(`String`)* — The chosen DeliveryEstimationSetup's ExternalReference — the URL PATH segment (NOT a body field,
-NOT the 2A0 Id). Source: whichever resolve branch ran —
-resolve-delivery-estimation-setup.setup_external_references[chosen] (filter) or
-resolve-setup-by-id.setup_external_references[0] (pin).
-- `locations` *(`Array`)* — SPECIFIC mode only: the pickup-eligible store(s) to estimate, each entry a Location
-ExternalReference (NOT a Name — a Name is rejected 400 "Location reference '<x>' not found in
-delivery estimation setup"). Every entry MUST be one of
-list-bopis-eligible-locations.eligible_location_external_references. OMIT this field entirely in
-NEARBY mode (see the location-selection choice_point): an empty/absent locations list switches
-the service into radius discovery, which then REQUIRES address + radius + maxReturnedLocations.
-Source: customer selection over list-bopis-eligible-locations.
-  - schema: `{'type': 'array', 'minItems': 1, 'maxItems': 100, 'items': {'type': 'string', 'pattern': '^[^\\x00-\\x1F\\x7F]{1,255}$', 'description': "A pickup-eligible Location's ExternalReference (from list-bopis-eligible-locations)."}}`
-- `products` *(`Array`)* — The products to estimate, each a (SKU, quantity) pair. Source: customer selection over
-list-products. quantity must be a positive whole number.
-  - schema: `{'type': 'array', 'minItems': 1, 'maxItems': 2000, 'items': {'type': 'object', 'required': ['stockKeepingUnit', 'quantity'], 'properties': {'stockKeepingUnit': {'type': 'string', 'minLength': 1, 'description': 'Product StockKeepingUnit (non-blank; Core 400s INVALID_API_INPUT on a blank SKU).'}, 'quantity': {'type': 'integer', 'minimum': 1, 'maximum': 2147483647, 'description': 'Positive whole-number quantity in [1, 2147483647] (fractional values are rejected).'}}}}`
-- `address` *(`Object`)* — The destination/search address. The WIRE KEY IS "address" — NOT "deliveryAddress", which the
-endpoint rejects with 400 JSON_PARSER_ERROR 'Unrecognized field "deliveryAddress"' in both
-modes (measured on 2026-08-25). NOTE the inner field name is countryCode (NOT country
-as in the delivery-date estimate) — the outer key differs from delivery-date too, so do not
-pattern-match either name off that sibling. REQUIRED in NEARBY mode (locations omitted) — 400
-"Address is required when locations list is empty" otherwise; OPTIONAL in SPECIFIC mode.
-Provide countryCode+postalCode and/or latitude+longitude (both forms live-proven 201;
-lat/long alone is accepted and drives the distance). Sending BOTH is also accepted (201),
-and when both are present THE COORDINATES WIN: they do not supplement the postal code, they
-replace it as the distance origin. Measured on 2026-08-26 — postalCode 94105 (San
-Francisco) sent together with Miami coordinates returned distances byte-identical to
-Miami-coordinates-alone at all 5 stores over 5 calls each, and identical to the 94105 control
-at none of them. Source: customer input.
-  - schema: `{'type': 'object', 'properties': {'countryCode': {'type': ['string', 'null'], 'description': 'ISO 3166-1 alpha-2 country code (e.g. "US"). Pair with postalCode.'}, 'postalCode': {'type': ['string', 'null'], 'description': 'Postal code. Pair with countryCode.'}, 'latitude': {'type': ['number', 'null'], 'minimum': -90, 'maximum': 90, 'description': 'Optional latitude in [-90,90]; latitude+longitude alone is an accepted address form and drives the distance. TAKES PRECEDENCE over countryCode+postalCode when both are supplied — send it only if you want the coordinates, not the postal code, to be the distance origin.'}, 'longitude': {'type': ['number', 'null'], 'minimum': -180, 'maximum': 180, 'description': 'Optional longitude in [-180,180]; pair with latitude. Same precedence over countryCode+postalCode as latitude.'}}}`
-- `unit` *(`String`)* — Distance unit for the radius and the returned distance. EXACTLY "mi" or "km" (any other value ->
-400 "Unit must be either 'mi' or 'km'"). Defaults to mi when omitted. Source: user_input.
-- `radius` *(`Number`)* — NEARBY mode only: the search radius (in `unit`) within which to find pickup-eligible stores.
-REQUIRED and > 0 when locations is omitted (400 "Radius must be greater than 0 when locations
-list is empty" otherwise). Ignored/omit in SPECIFIC mode. Source: user_input.
-  - schema: `{'type': 'number', 'exclusiveMinimum': 0}`
-- `maxReturnedLocations` *(`Integer`)* — NEARBY mode only: the maximum number of nearby pickup-eligible stores to return. REQUIRED and > 0
-when locations is omitted (400 "Max returned locations must be greater than 0 when locations list
-is empty" otherwise). Ignored/omit in SPECIFIC mode. Source: user_input.
-  - schema: `{'type': 'integer', 'minimum': 1, 'maximum': 1000}`
-- `orderDate` *(`String`)* — OPTIONAL simulated "now" for the estimate — an ISO-8601 UTC timestamp passed through to the
-delivery service so pickup times / order cutoffs are computed relative to it instead of the
-actual current time (useful for "if I ordered at <time>, when could I pick up?"). Omit to use the
-real current time. Source: user_input.
-
-**Depends on:** `resolve-delivery-estimation-setup`, `resolve-setup-by-id`, `list-bopis-eligible-locations`, `list-products`