feat(pos): add addEventListener/removeEventListener and PosEventMap to DataTargetApi

Adds type-safe event listener support for the pos.app.ready.data background
target. PosEventMap defines three discrete events: transaction_complete,
cash_tracking_session_start, cash_tracking_session_complete.

The generic AddEventListener/RemoveEventListener types follow the TAG
proposal (ui-api-design PR #1418) and match the existing Navigation API
pattern. Cart changes are intentionally excluded — they are state, not
events, and should use shopify.cart.current.subscribe() instead.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: vctrchu

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

@@ -13,7 +13,12 @@ export type {ActionApi, ActionApiContent} from './api/action-api/action-api';
 
 export type {StandardApi} from './api/standard/standard-api';
 export type {ActionTargetApi} from './api/action-target-api/action-target-api';
-export type {DataTargetApi} from './api/data-target-api/data-target-api';
+export type {
+  DataTargetApi,
+  PosEventMap,
+  AddEventListener,
+  RemoveEventListener,
+} from './api/data-target-api/data-target-api';
 
 export type {
   CameraApi,

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

@@ -6,13 +6,86 @@ import {ProductSearchApi} from '../product-search-api/product-search-api';
 import {SessionApi} from '../session-api/session-api';
 import {StorageApi} from '../storage-api/storage-api';
 import type {I18n} from '../../../../api';
+import type {SaleTransactionData} from '../../event/data/SaleTransactionData';
+import type {ReturnTransactionData} from '../../event/data/ReturnTransactionData';
+import type {ExchangeTransactionData} from '../../event/data/ExchangeTransactionData';
+
+/**
+ * Maps POS event names to their callback 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.
+ */
+export type PosEventMap = {
+  /**
+   * Fires after a sale, return, or exchange transaction completes.
+   */
+  transaction_complete: {
+    transaction:
+      | SaleTransactionData
+      | ReturnTransactionData
+      | ExchangeTransactionData;
+  };
+  /**
+   * Fires when a cash tracking session (shift) is opened.
+   */
+  cash_tracking_session_start: {
+    cashTrackingSessionStart: {
+      /** Unique identifier for this cash tracking session. */
+      id: number;
+      /** ISO 8601 timestamp when the session was opened. */
+      openingTime: string;
+    };
+  };
+  /**
+   * Fires when a cash tracking session (shift) is closed.
+   */
+  cash_tracking_session_complete: {
+    cashTrackingSessionComplete: {
+      /** Unique identifier for this cash tracking session. */
+      id: number;
+      /** ISO 8601 timestamp when the session was opened. */
+      openingTime: string;
+      /** ISO 8601 timestamp when the session was closed. */
+      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.
  */
 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 &