feat(point-of-sale): add paymentvalidations intercept types

.changeset/pos-intercept-payment-validations.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+Add `paymentvalidations` intercept types for POS payment blocking workflows, and rename the `beforecheckout` intercept to `cartvalidations` so both interceptable workflows follow one naming scheme.

packages/ui-extensions/src/surfaces/point-of-sale/events.ts

@@ -4,6 +4,7 @@ import type {
   CashTrackingSessionCompleteEvent,
 } from './events/cash-tracking-session-events';
 import type {Cart} from './types/cart';
+import type {MoneyV2} from './types/money';
 
 /**
  * Canonical event-name constants for POS host events. Prefer these over string
@@ -24,7 +25,8 @@ export const POS_EVENT_NAMES = {
  * @private
  */
 export const POS_INTERCEPT_NAMES = {
-  BEFORE_CHECKOUT: 'beforecheckout',
+  CART_VALIDATIONS: 'cartvalidations',
+  PAYMENT_VALIDATIONS: 'paymentvalidations',
 } as const;
 
 /**
@@ -55,20 +57,59 @@ export interface ShopifyEventMap {
  * @private
  */
 export interface ShopifyInterceptMap {
-  [POS_INTERCEPT_NAMES.BEFORE_CHECKOUT]: BeforeCheckoutEvent;
+  [POS_INTERCEPT_NAMES.CART_VALIDATIONS]: CartValidationsEvent;
+  [POS_INTERCEPT_NAMES.PAYMENT_VALIDATIONS]: PaymentValidationsEvent;
 }
 
 /**
  * Dispatched when staff attempts to leave the active cart for checkout.
  *
  * @private
  */
-export interface BeforeCheckoutEvent extends Event {
-  readonly type: typeof POS_INTERCEPT_NAMES.BEFORE_CHECKOUT;
+export interface CartValidationsEvent extends Event {
+  readonly type: typeof POS_INTERCEPT_NAMES.CART_VALIDATIONS;
   /** The POS cart at the point checkout was requested. */
   readonly cart: Cart;
 }
 
+/**
+ * The kind of payment method being attempted.
+ *
+ * @private
+ */
+export type InterceptedPaymentMethodType = 'cash';
+
+/**
+ * Identifies the payment method being attempted.
+ *
+ * `type` alone identifies singleton methods (for example `cash`). `identifier`
+ * disambiguates method types a shop can have several of (for example custom
+ * payment methods) as they become interceptable.
+ *
+ * @private
+ */
+export interface InterceptedPaymentMethod {
+  readonly type: InterceptedPaymentMethodType;
+
+  /** Present when `type` alone is ambiguous. Matching is exact on the pair. */
+  readonly identifier?: string;
+}
+
+/**
+ * Dispatched when staff selects a payment method on the payments screen.
+ *
+ * @private
+ */
+export interface PaymentValidationsEvent extends Event {
+  readonly type: typeof POS_INTERCEPT_NAMES.PAYMENT_VALIDATIONS;
+
+  /** The payment method staff selected. */
+  readonly paymentMethod: InterceptedPaymentMethod;
+
+  /** The amount this tender would charge, in presentment currency. */
+  readonly amount: MoneyV2;
+}
+
 /** @private */
 export type ShopifyInterceptor<TEvent extends Event> = (
   event: TEvent,