refactor: drive BackgroundShopifyGlobal emit off DataExtensionTargets

Replace the hardcoded `parts.join('.') === 'pos.app.ready.data'` check
with an `isDataTarget` flag derived from the interface the target was
declared in. Any target added to `DataExtensionTargets` now gets the
wider `BackgroundShopifyGlobal` automatically — no buildTargetDts edit
required.

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

Author: vctrchu

packages/ui-extensions-tester/src/index.ts

@@ -1,7 +1,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
-import type {AnyExtensionTarget, ApiForTarget} from './targets';
+import type {
+  AnyExtensionTarget,
+  ApiForTarget,
+  EventMapForTarget,
+} from './targets';
 import {isCheckoutTarget} from './targets';
 import {createMockTargetApi} from './mocks/target-apis';
 import {createMockNavigation, type Navigation} from './navigation';
@@ -99,12 +103,26 @@ interface BaseExtensionHarness<T extends AnyExtensionTarget> {
    * are ignored, and thrown errors are caught per-listener so one bad
    * listener doesn't block the others.
    *
+   * The `event` argument must be a real `Event` instance, matching what
+   * the host dispatches at runtime. Construct it with `new Event(type)`
+   * and attach payload fields via `Object.assign`:
+   *
    * ```ts
    * shopify.addEventListener('transactioncomplete', (event) => { ... });
-   * extension.dispatch('transactioncomplete', { transaction: {...} });
+   *
+   * const event = Object.assign(new Event('transactioncomplete'), {
+   *   transactionType: 'Sale',
+   *   orderId: 1,
+   *   grandTotal: { amount: 10, currency: 'USD' },
+   *   // ...
+   * });
+   * extension.dispatch('transactioncomplete', event);
    * ```
    */
-  dispatch(type: string, event?: unknown): void;
+  dispatch<K extends keyof EventMapForTarget<T>>(
+    type: K,
+    event: EventMapForTarget<T>[K],
+  ): void;
 }
 
 /**
@@ -217,8 +235,11 @@ class Extension<T extends AnyExtensionTarget> implements ExtensionHarness<T> {
     this.#eventListeners.get(type)?.delete(listener);
   };
 
-  dispatch(type: string, event?: unknown): void {
-    const listeners = this.#eventListeners.get(type);
+  dispatch<K extends keyof EventMapForTarget<T>>(
+    type: K,
+    event: EventMapForTarget<T>[K],
+  ): void {
+    const listeners = this.#eventListeners.get(type as string);
     if (!listeners) return;
     // Snapshot so listeners that register/unregister during dispatch
     // don't mutate the iteration.

packages/ui-extensions-tester/src/targets.ts

@@ -9,6 +9,7 @@ import type {
 import type {
   ExtensionTarget as PosExtensionTarget,
   ExtensionTargets as PointOfSaleExtensionTargets,
+  ShopifyEventMap as PosEventMap,
 } from '@shopify/ui-extensions/point-of-sale';
 import type {
   CustomerAccountExtensionTarget,
@@ -42,6 +43,16 @@ export type ApiForTarget<T extends AnyExtensionTarget> =
     ? D
     : never;
 
+/**
+ * Maps an extension target to the event map available via
+ * `shopify.addEventListener` on that surface.
+ *
+ * - POS targets: the POS `ShopifyEventMap`.
+ * - Other surfaces: no host events, so the map is empty.
+ */
+export type EventMapForTarget<T extends AnyExtensionTarget> =
+  T extends PosExtensionTarget ? PosEventMap : {};
+
 export function isCheckoutTarget(
   target: string,
 ): target is CheckoutExtensionTarget {

packages/ui-extensions-tester/src/tests/shopify-events.test.ts

@@ -1,21 +1,49 @@
+import type {
+  CashTrackingSessionStartEvent,
+  TransactionCompleteEvent,
+} from '@shopify/ui-extensions/point-of-sale';
+
 import {getExtension} from '../index';
 
 import {createTestSandbox, type TestSandbox} from './helpers';
 
+function makeTransactionCompleteEvent(): TransactionCompleteEvent {
+  return Object.assign(new Event('transactioncomplete'), {
+    transactionType: 'Sale' as const,
+    discounts: [],
+    taxTotal: {amount: 0, currency: 'USD'},
+    subtotal: {amount: 0, currency: 'USD'},
+    grandTotal: {amount: 0, currency: 'USD'},
+    paymentMethods: [],
+    balanceDue: {amount: 0, currency: 'USD'},
+    shippingLines: [],
+    taxLines: [],
+    executedAt: '2024-01-01T00:00:00Z',
+    lineItems: [],
+  });
+}
+
+function makeCashTrackingSessionStartEvent(): CashTrackingSessionStartEvent {
+  return Object.assign(new Event('cashtrackingsessionstart'), {
+    id: 1,
+    openingTime: '2024-01-01T00:00:00Z',
+  });
+}
+
 describe('shopify.addEventListener / extension.dispatch', () => {
   let sandbox: TestSandbox;
 
   beforeEach(() => {
     sandbox = createTestSandbox();
-    sandbox.placeToml();
+    sandbox.placeToml({target: 'pos.app.ready.data'});
   });
 
   afterEach(() => {
     sandbox.destroy();
   });
 
   function setUpExt() {
-    const extension = getExtension('purchase.checkout.block.render', {
+    const extension = getExtension('pos.app.ready.data', {
       configSearchDir: sandbox.tempDir,
     });
     extension.setUp();
@@ -35,11 +63,11 @@ describe('shopify.addEventListener / extension.dispatch', () => {
     const listener = jest.fn();
     shopify.addEventListener('transactioncomplete', listener);
 
-    const eventData = {transaction: {id: 1}};
-    extension.dispatch('transactioncomplete', eventData);
+    const event = makeTransactionCompleteEvent();
+    extension.dispatch('transactioncomplete', event);
 
     expect(listener).toHaveBeenCalledTimes(1);
-    expect(listener).toHaveBeenCalledWith(eventData);
+    expect(listener).toHaveBeenCalledWith(event);
   });
 
   it('fires all listeners registered for the same event', () => {
@@ -50,10 +78,11 @@ describe('shopify.addEventListener / extension.dispatch', () => {
     shopify.addEventListener('transactioncomplete', listenerA);
     shopify.addEventListener('transactioncomplete', listenerB);
 
-    extension.dispatch('transactioncomplete', 42);
+    const event = makeTransactionCompleteEvent();
+    extension.dispatch('transactioncomplete', event);
 
-    expect(listenerA).toHaveBeenCalledWith(42);
-    expect(listenerB).toHaveBeenCalledWith(42);
+    expect(listenerA).toHaveBeenCalledWith(event);
+    expect(listenerB).toHaveBeenCalledWith(event);
   });
 
   it('does not fire other events when dispatching one', () => {
@@ -64,7 +93,7 @@ describe('shopify.addEventListener / extension.dispatch', () => {
     shopify.addEventListener('transactioncomplete', target);
     shopify.addEventListener('cashtrackingsessionstart', other);
 
-    extension.dispatch('transactioncomplete', undefined);
+    extension.dispatch('transactioncomplete', makeTransactionCompleteEvent());
 
     expect(target).toHaveBeenCalledTimes(1);
     expect(other).not.toHaveBeenCalled();
@@ -77,7 +106,7 @@ describe('shopify.addEventListener / extension.dispatch', () => {
     shopify.addEventListener('transactioncomplete', listener);
     shopify.removeEventListener('transactioncomplete', listener);
 
-    extension.dispatch('transactioncomplete', undefined);
+    extension.dispatch('transactioncomplete', makeTransactionCompleteEvent());
 
     expect(listener).not.toHaveBeenCalled();
   });
@@ -89,7 +118,7 @@ describe('shopify.addEventListener / extension.dispatch', () => {
     shopify.addEventListener('transactioncomplete', listener);
     shopify.addEventListener('transactioncomplete', listener);
 
-    extension.dispatch('transactioncomplete', undefined);
+    extension.dispatch('transactioncomplete', makeTransactionCompleteEvent());
 
     expect(listener).toHaveBeenCalledTimes(1);
   });
@@ -105,7 +134,7 @@ describe('shopify.addEventListener / extension.dispatch', () => {
     shopify.addEventListener('transactioncomplete', follower);
 
     expect(() =>
-      extension.dispatch('transactioncomplete', undefined),
+      extension.dispatch('transactioncomplete', makeTransactionCompleteEvent()),
     ).not.toThrow();
     expect(throwing).toHaveBeenCalledTimes(1);
     expect(follower).toHaveBeenCalledTimes(1);
@@ -114,7 +143,10 @@ describe('shopify.addEventListener / extension.dispatch', () => {
   it('is a no-op when dispatching an event with no registered listeners', () => {
     const extension = setUpExt();
     expect(() =>
-      extension.dispatch('cashtrackingsessionstart', {}),
+      extension.dispatch(
+        'cashtrackingsessionstart',
+        makeCashTrackingSessionStartEvent(),
+      ),
     ).not.toThrow();
   });
 
@@ -126,7 +158,7 @@ describe('shopify.addEventListener / extension.dispatch', () => {
     extension.tearDown();
 
     extension.setUp();
-    extension.dispatch('transactioncomplete', undefined);
+    extension.dispatch('transactioncomplete', makeTransactionCompleteEvent());
 
     expect(leaked).not.toHaveBeenCalled();
   });

packages/ui-extensions/buildTargetDts.ts

@@ -58,10 +58,12 @@ function createInitialTargetDefinition({
   buildPath,
   name,
   surface,
+  isDataTarget,
 }: {
   buildPath: string;
   name: string;
   surface: string;
+  isDataTarget: boolean;
 }) {
   const parts = name.replaceAll("'", '').split('.');
   const fileName = `${parts.join('.')}.d.ts`;
@@ -76,7 +78,7 @@ function createInitialTargetDefinition({
   }${
     surface === 'point-of-sale'
       ? `export * from '../events';\n${
-          parts.join('.') === 'pos.app.ready.data'
+          isDataTarget
             ? `export type {BackgroundShopifyGlobal as ShopifyGlobal} from '../globals';\n`
             : ''
         }`
@@ -141,10 +143,12 @@ function getTargets(sourceFile: SourceFile) {
 // Target definitions
 function extractTargetComponents(
   sourceFile: SourceFile,
-): {name: string; components?: string[]}[] {
+): {name: string; components?: string[]; isDataTarget: boolean}[] {
   const extensionTargetArray = getTargets(sourceFile);
   return extensionTargetArray
     .map((extensionTargets) => {
+      const isDataTarget =
+        extensionTargets.getName() === 'DataExtensionTargets';
       return extensionTargets.getProperties().map((property) => {
         const componentsType = property
           .getType()
@@ -166,6 +170,7 @@ function extractTargetComponents(
         return {
           name: property.getName(),
           components,
+          isDataTarget,
         };
       });
     })
@@ -177,15 +182,20 @@ function createTargetDefinition({
   buildPath,
   project,
   surface,
-  target: {name, components},
+  target: {name, components, isDataTarget},
 }: {
   srcPaths: string[];
   buildPath: string;
   project: Project;
   surface: string;
-  target: {name: string; components?: string[]};
+  target: {name: string; components?: string[]; isDataTarget: boolean};
 }) {
-  const targetPath = createInitialTargetDefinition({name, surface, buildPath});
+  const targetPath = createInitialTargetDefinition({
+    name,
+    surface,
+    buildPath,
+    isDataTarget,
+  });
   const targetFile = project.addSourceFileAtPath(targetPath);
   const names = new Set<string>();