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

[vctrchu]

What

Add TypeScript types for the pos.app.ready.data persistent background extension target.

New types

• DataTargetApi<T> — API surface for non-rendering data targets. Includes all non-UI APIs (cart, storage, session, locale, connectivity, device, product search) but excludes UI-presenting APIs (modals, toasts, scanners, pin pads).
• ShopifyEventMap — Maps event names to their typed Event subclasses (transactioncomplete, cashtrackingsessionstart, cashtrackingsessioncomplete). Sourced from ui-api-design build output.
• DataExtensionTargets — New target interface with pos.app.ready.data as a RunnableExtension<DataTargetApi, undefined>.
• DataExtensionTarget — Type alias for data target keys.

Event types (from ui-api-design)

Event type definitions are copied from the ui-api-design build output (.d.ts files), following the same pattern checkout uses for syncing types from the private repo. Events are flat Event subclasses with readonly properties:

• TransactionCompleteEvent — orderId (gid), transactionType (sale/return/exchange), customer?, grandTotal, executedAt
• CashTrackingSessionStartEvent — id (UUID), openingTime
• CashTrackingSessionCompleteEvent — id (UUID), openingTime, closingTime

WindowEventMap augmentation

POS host events are received via the standard window.addEventListener() Web API. ShopifyEventMap augments WindowEventMap so calls are fully type-safe.

shopify.extend("pos.app.ready.data", () => {
  window.addEventListener("transactioncomplete", (event) => {
    console.log(event.orderId, event.transactionType);
  });
});

Why

POS apps need a persistent background extension that starts when POS loads and runs for the session lifetime. This replaces the existing fire-and-forget .event.observe targets with a single long-lived target that receives events via window.addEventListener, aligning with web standards.

Related PRs

• ui-api-design: https://github.com/Shopify/ui-api-design/pull/1418 (TAG proposal)
• extensibility: https://app.graphite.com/github/Shopify/extensibility/pull/1064 (eventListenerPlugin + eventDispatchFactory)
• pos-mobile: https://github.com/shop/world/pull/508117, https://github.com/shop/world/pull/508119
• Deprecation of observe targets: Mark POS .observe extension targets as @deprecated #4146

[github-actions]

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

We are actively migrating UI extension reference docs to MDX in the areas/platforms/shopify-dev zone of the monorepo. This impacts docs for the following surfaces:

• Admin UI extensions
• App Home
• Checkout UI extensions
• Customer account UI extensions
• POS UI extensions

During this migration, please be aware of the following:

.doc.ts files are being deprecated. Changes to .doc.ts files in this repo will not be reflected in the new MDX-based docs. If you need to update docs for a reference that has already been migrated, make your changes directly in the areas/platforms/shopify-dev zone of the monorepo instead.

Doc comments in .ts source files (the comment blocks above types and functions) are also affected. Generating docs from these comments currently requires a newer version of the @shopify/generate-docs library that isn't yet available. Updates to doc comments may not produce the expected output until the migration is complete.

Examples that previously lived in this repo are being moved to the areas/platforms/shopify-dev zone of the monorepo and should be authored there going forward.

What should I do?

• If your PR includes changes to .doc.ts files, doc comments, or examples, please reach out to us in #devtools-proj-templated-refs so we can help ensure your updates are captured correctly.
• If your PR is limited to source code changes (non-docs), you can ignore this notice.

Thanks for your patience while we complete the migration! 🙏

[vctrchu]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(pos): add TypeScript types for pos.app.ready.data background target #4123 👈 (View in Graphite)
• 2026-04: Fix doc generation to resolve shopify-dev from World #4124
• 2026-04-rc

This stack of pull requests is managed by Graphite. Learn more about stacking.

[NathanJolly]

This PR has the target definition and DataTargetApi, but it's missing two things that should ship together:

1. addEventListener / removeEventListener — needs to be part of DataTargetApi (or the target's API surface). The generic types are defined in the TAG proposal (ui-api-design PR #1418), and the surface-specific PosEventMap with concrete event types + payloads should be defined here.

2. PosEventMap — the typed event map with transaction_complete, cash_tracking_session_start, cash_tracking_session_complete and their payload interfaces. This is what makes addEventListener type-safe for POS.

Without these, extensions targeting pos.app.ready.data have no way to type-safely listen for events.

[vctrchu]

Added both. DataTargetApi now includes addEventListener and removeEventListener using the generic types from the TAG proposal (ui-api-design #1418). Also added PosEventMap with transaction_complete, cash_tracking_session_start, and cash_tracking_session_complete — no cart_update since that's state, not an event.

[vctrchu]

/snapit

[shopify-github-actions-access]

🫰✨ Thanks @vctrchu! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

"@shopify/ui-extensions": "0.0.0-snapshot-20260330221356",
"@shopify/ui-extensions-tester": "0.0.0-snapshot-20260330221356"