feat(pos): add TypeScript types for pos.app.ready.data background target

Add BackgroundApi type and event definitions for the new persistent
background extension target. Part of BGX (POS Background Extensions).

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

Author: vctrchu

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

@@ -132,3 +132,9 @@ export type {
   PinPadActionType,
   PinValidationResult,
 } from './types/pin-pad';
+
+export type {BackgroundApi} from './api/background-api/background-api';
+export type {
+  BackgroundEventType,
+  BackgroundEventDataMap,
+} from './api/background-api/events';

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

@@ -0,0 +1,21 @@
+import type {SessionApi} from '../session-api/session-api';
+import type {StorageApi} from '../storage-api/storage-api';
+import type {LocaleApi} from '../locale-api/locale-api';
+import type {ConnectivityApi} from '../connectivity-api/connectivity-api';
+import type {DeviceApi} from '../device-api/device-api';
+
+/**
+ * The `BackgroundApi` provides APIs available to persistent background extensions
+ * running on the `pos.app.ready.data` target. Background extensions observe POS events
+ * via `shopify.addEventListener()` without rendering UI.
+ *
+ * This API surface includes session tokens for backend authentication, storage for
+ * cross-target communication, and read-only device/connectivity/locale information.
+ */
+export type BackgroundApi<T> = {
+  extensionPoint: T;
+} & SessionApi &
+  StorageApi &
+  LocaleApi &
+  ConnectivityApi &
+  DeviceApi;

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

@@ -0,0 +1,21 @@
+/**
+ * Event types that can be observed via `shopify.addEventListener()` in a
+ * background extension running on `pos.app.ready.data`.
+ */
+export type BackgroundEventType =
+  | 'transaction_complete'
+  | 'cart_update'
+  | 'cash_tracking_session_start'
+  | 'cash_tracking_session_complete';
+
+/**
+ * Maps each background event type to the shape of data passed to the event
+ * listener callback. Payload types use `unknown` until event schemas are
+ * finalized and will be refined in a future release.
+ */
+export interface BackgroundEventDataMap {
+  transaction_complete: {transaction: unknown};
+  cart_update: {cart: unknown};
+  cash_tracking_session_start: {session: unknown};
+  cash_tracking_session_complete: {session: unknown};
+}

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

@@ -6,7 +6,8 @@ import {
 import {TransactionCompleteData} from './event/data/TransactionCompleteData';
 import {CartUpdateEventData} from './event/data/CartUpdateEventData';
 
-import type {RenderExtension} from '../../extension';
+import type {RenderExtension, RunnableExtension} from '../../extension';
+import type {BackgroundApi} from './api/background-api/background-api';
 
 import type {
   StandardApi,
@@ -43,6 +44,21 @@ export interface EventExtensionTargets {
   ) => Promise<BaseOutput>;
 }
 
+export interface DataExtensionTargets {
+  /**
+   * A persistent background extension that starts when POS loads and runs for
+   * the session's lifetime. Use this target for observing POS events like cart
+   * updates and transaction completions without rendering UI.
+   *
+   * Register event listeners via `shopify.addEventListener()` and persist state
+   * via `shopify.storage` for companion UI targets to read.
+   */
+  'pos.app.ready.data': RunnableExtension<
+    BackgroundApi<'pos.app.ready.data'>,
+    undefined
+  >;
+}
+
 export interface RenderExtensionTargets {
   /**
    * Renders a single interactive tile component on the POS home screen's smart grid. The tile appears once during home screen initialization and remains persistent until navigation occurs. Use this target for high-frequency actions, status displays, or entry points to workflows that merchants need daily.
@@ -362,8 +378,10 @@ export interface RenderExtensionTargets {
 
 export interface ExtensionTargets
   extends RenderExtensionTargets,
-    EventExtensionTargets {}
+    EventExtensionTargets,
+    DataExtensionTargets {}
 
 export type RenderExtensionTarget = keyof RenderExtensionTargets;
 export type EventExtensionTarget = keyof EventExtensionTargets;
+export type DataExtensionTarget = keyof DataExtensionTargets;
 export type ExtensionTarget = keyof ExtensionTargets;