Add types for POS intercept ValidationAdd target values

[vctrchu]

Background

https://github.com/shop/issues-retail/issues/33533

The POS intercept API (#4520) shipped ValidationAdd.target as a bare string documented as a "JSON-path locator". The target contract we're keeping is the Functions validation target model: an enumerated token table, string-matched, never evaluated as JSON paths. Bare string can never be narrowed later without a breaking change, and it silently accepts targets no host honors.

Solution

Pin the grammar as template literal types while the intercept API is still @private, narrowed per intercepted event:

Event	Field	Target value
cartvalidations	cart	$.cart
cartvalidations	line item	$.cart.lineItems['<uuid>']
paymentvalidations	payment attempt	$.payment

• ValidationTarget union of CartValidationTarget / PaymentValidationTarget; wire format stays a plain string, and unions can widen later (never narrow).

• ValidationTargetFor<TEvent> narrows interceptor returns per event: a cartvalidations interceptor cannot return $.payment (compile error), and vice versa. InterceptResult / Operation / ValidationAdd gain a defaulted type parameter, so existing structural consumers compile unchanged.

• Devs write the line target inline — TS contextually checks template expressions against template literal types:

  target: `$.cart.lineItems['${lineItem.uuid}']`  // checked char-for-char
  target: `$.cart.lineItems[${idx}]`              // compile error

• JSDoc pins the semantics: targets are data locators (host decides rendering, falls back to the event's root scope); line item uuids must be echoed from the same event's cart snapshot, not cached across events; bundle components target their parent line; unrecognized targets degrade to root scope rather than dropping the validation; handles are namespaced per extension and may repeat across targets.

Alternatives Considered

1. Keep target?: string — ❌ can never be narrowed without a breaking change; typos and unsupported targets compile silently.
2. JSONPath filter $.cart.lineItems[?(@.uuid=='<uuid>')] — ❌ buys spec-valid JSONPath semantics the Functions token model doesn't have (its own table hardcodes deliveryGroups[0] against multi-group carts), at the cost of syntax hostile to extension developers.
3. Positional $.cart.lineItems[2] — ❌ cannot carry stable identity; .filter().map((li, i)) silently targets the wrong line.
4. Structured object / sibling uuid field — ❌ breaks the single-string target contract shared with Functions.

🎩

• Type-level only (@private API, no runtime change beyond the type declarations). yarn type-check passes.
• Verified narrowing with a scratch file: valid tokens assignable per event; cross-event tokens and positional indexes fail compilation with @ts-expect-error consumed.
• Host-side runtime sanitation of these tokens is tracked in https://github.com/shop/issues-retail/issues/33534 (extensibility repo); POS line-item rendering in https://github.com/shop/issues-retail/issues/32377.

Checklist

• I have 🎩'd these changes
• I have updated relevant documentation

[vctrchu]

CI notes: lint failure was prettier indentation in my change — fixed and pushed. The test job failure is pre-existing on 2026-10-rc (checkout testing example: api_version "2026-10" does not match @shopify/ui-extensions-tester ("2027-00")) — same failure on the branch tip before this PR (#4625's CI run). Not addressed here since this PR is point-of-sale types only.

[vctrchu]

/snapshot

[vctrchu]

/snapit

[shopify-github-actions-access]

🫰✨ Thanks @vctrchu! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

"@shopify/ui-extensions": "0.0.0-snapshot-20260818000939",
"@shopify/ui-extensions-tester": "0.0.0-snapshot-20260818000939"