refactor(pos): move addEventListener to window via WindowEventMap augmentation

Remove addEventListener/removeEventListener from DataTargetApi. POS events
are received via the standard window.addEventListener() Web API. PosEventMap
augments WindowEventMap for type-safe event listening.

Author: vctrchu

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

@@ -16,8 +16,6 @@ export type {ActionTargetApi} from './api/action-target-api/action-target-api';
 export type {
   DataTargetApi,
   PosEventMap,
-  AddEventListener,
-  RemoveEventListener,
 } from './api/data-target-api/data-target-api';
 
 export type {

packages/ui-extensions/src/surfaces/point-of-sale/api/data-target-api/data-target-api.ts

@@ -11,13 +11,22 @@ import type {ReturnTransactionData} from '../../event/data/ReturnTransactionData
 import type {ExchangeTransactionData} from '../../event/data/ExchangeTransactionData';
 
 /**
- * Maps POS event names to their callback payload types.
+ * Maps POS event names to their event payload types.
  *
- * Used with `addEventListener` / `removeEventListener` to provide type-safe
- * event observation. These are discrete events — for state changes like cart
- * contents, use `shopify.cart.current.subscribe()` instead.
+ * These events are dispatched on `window` and received via the standard
+ * `window.addEventListener(type, callback)` Web API. For continuous state
+ * changes like cart contents, use `shopify.cart.current.subscribe()` instead.
+ *
+ * @example
+ * ```ts
+ * shopify.extend('pos.app.ready.data', () => {
+ *   window.addEventListener('transaction_complete', (event) => {
+ *     console.log(event.transaction.orderId);
+ *   });
+ * });
+ * ```
  */
-export type PosEventMap = {
+export interface PosEventMap {
   /**
    * Fires after a sale, return, or exchange transaction completes.
    */
@@ -51,41 +60,14 @@ export type PosEventMap = {
       closingTime: string;
     };
   };
-};
-
-/**
- * Registers a listener for a POS host event. The listener is called each time
- * the event fires. This is passive and fire-and-forget — the host does not wait
- * for the listener and ignores return values.
- */
-export type AddEventListener<EventMap extends {[key: string]: unknown}> = <
-  K extends keyof EventMap,
->(
-  type: K,
-  listener: (event: EventMap[K]) => void,
-) => void;
-
-/**
- * Removes a previously registered event listener. The `type` and `listener`
- * must match those passed to `addEventListener` (same function reference).
- */
-export type RemoveEventListener<EventMap extends {[key: string]: unknown}> = <
-  K extends keyof EventMap,
->(
-  type: K,
-  listener: (event: EventMap[K]) => void,
-) => void;
+}
 
 /**
- * API surface for non-rendering data extension targets.
+ * API surface for non-rendering data extension targets. Provides access to POS APIs (cart, storage, session, etc.) without rendering UI. POS host events are received via the standard `window.addEventListener()` Web API.
  */
 export type DataTargetApi<T> = {
   extensionPoint: T;
   i18n: I18n;
-  /** Register a listener for discrete POS events. */
-  addEventListener: AddEventListener<PosEventMap>;
-  /** Remove a previously registered event listener. */
-  removeEventListener: RemoveEventListener<PosEventMap>;
 } & SessionApi &
   StorageApi &
   LocaleApi &

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

@@ -1,6 +1,9 @@
 import {Navigation} from './api/navigation-api/navigation-api';
+import type {PosEventMap} from './api/data-target-api/data-target-api';
 
 declare global {
   // @ts-expect-error - Intentionally overriding navigation type for POS context
   const navigation: Navigation;
+
+  interface WindowEventMap extends PosEventMap {}
 }