feat(pos): add TypeScript types for pos.app.ready.data background target by vctrchu · Pull Request #4123 · Shopify/ui-extensions

vctrchu · 2026-03-17T23:20:00Z

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 non-UI APIs (cart, storage, session, locale, connectivity, device, product search); excludes UI-presenting APIs.
ShopifyEventMap — Maps event names to their typed Event subclasses (transactioncomplete, cashtrackingsessionstart, cashtrackingsessioncomplete).
DataExtensionTargets — New target interface with pos.app.ready.data as a RunnableExtension<DataTargetApi, undefined>.
DataExtensionTarget — Type alias for data target keys.
ShopifyGlobal — POS shopify global type, augmented with addEventListener / removeEventListener keyed on ShopifyEventMap. Follows the same declare global pattern Checkout uses.

Event types

TransactionCompleteEvent — Discriminated union of three module-local variant interfaces (SaleCompleteEvent | ReturnCompleteEvent | ExchangeCompleteEvent), each extending BaseTransactionCompleteEvent. All fields are readonly. Narrow on event.transactionType ('Sale' | 'Return' | 'Exchange') to access per-type fields (lineItems, refundId, lineItemsAdded, etc.). Shared fields (orderId, grandTotal, customer, paymentMethods, …) are available without narrowing. The three variants are internal scaffolding — only TransactionCompleteEvent is part of the public surface.
BaseTransactionCompleteEvent — Internal shared base extending Event. Contains the 12 fields common to Sale/Return/Exchange (orderId, customer, grandTotal, taxTotal, paymentMethods, shippingLines, etc.).
CashTrackingSessionStartEvent — Event subclass with id: number and openingTime: string (ISO 8601).
CashTrackingSessionCompleteEvent — Adds closingTime: string.

Folder structure

Event types live at the surface-level point-of-sale/events/ (sibling to api/ and globals.ts), not nested inside api/data-target-api/. Host events are dispatched on the global shopify object and consumable by any target, so they aren't scoped to a specific API. The layout mirrors the existing api.ts + api/ pattern:

point-of-sale/
├── api.ts     + api/       (APIs)
├── events.ts  + events/    (host events)
└── globals.ts

`shopify` global augmentation

POS host events are received via shopify.addEventListener() on the global shopify object, consistent with TAG proposal Shopify/ui-api-design#1418.

shopify.addEventListener('transactioncomplete', (event) => {
  if (event.transactionType === 'Sale') {
    console.log(event.lineItems, event.grandTotal);
  }
});

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 shopify.addEventListener, aligning with the shape TAG approved in Shopify/ui-api-design#1418.

Related PRs

ui-api-design (TAG proposal): Shopify/ui-api-design#1418
extensibility host (eventListenerPlugin + eventDispatchFactory): Shopify/extensibility#1064
pos-mobile wiring: shop/world#508117, shop/world#508119
Observe target deprecation: Mark POS .observe extension targets as @deprecated #4146

Status

Draft until TAG approves Shopify/ui-api-design#1418. Types will publish with the 2026-07 quarterly release train.

github-actions · 2026-03-17T23:20:07Z

🚨🚨🚨 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:

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 · 2026-03-17T23:29:59Z

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:

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.
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 · 2026-03-18T21:14:55Z

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 · 2026-03-30T22:13:04Z

/snapit

shopify-github-actions-access · 2026-03-30T22:14:39Z

🫰✨ 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"

Introduces the new `pos.app.ready.data` data extension target (non-rendering, session-long background extension) along with its typed event surface: - `DataExtensionTargets` / `DataExtensionTarget` / `DataTargetApi<T>` - `ShopifyGlobal` with `addEventListener` / `removeEventListener` - `ShopifyEventMap` mapping 3 event names to Event subclasses: - transactioncomplete (TransactionCompleteEvent — Sale | Return | Exchange) - cashtrackingsessionstart (CashTrackingSessionStartEvent) - cashtrackingsessioncomplete (CashTrackingSessionCompleteEvent) - Mock factory for pos.app.ready.data in ui-extensions-tester Events live at the surface level (point-of-sale/events/ with events.ts barrel) since they are dispatched on the global `shopify` object and consumable by any target, not scoped to data-target extensions.

@deprecated

Mirrors #4299 for the new pos.app.ready.data target: - Intersect DataTargetApi<T> with ExtensionApi<T> so data extensions can read shopify.extension.apiVersion and shopify.extension.target. - Mark extensionPoint as @deprecated in favor of extension.target, matching the StandardApi change. - Populate extension: { apiVersion, target } in createDataTargetMock.

vctrchu · 2026-04-20T22:51:01Z

/snapit

shopify-github-actions-access · 2026-04-20T22:52:40Z

🫰✨ 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-20260420225138",
"@shopify/ui-extensions-tester": "0.0.0-snapshot-20260420225138"

js-goupil

Couple of tiny things that we should address before merging so we don't break the navigation listener

js-goupil · 2026-04-21T19:21:03Z

+  /**
+   * The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` when order creation is pending.
+   */
+  readonly orderId?: number;


Should this be Order { id: number } like customer?

js-goupil · 2026-04-21T19:23:45Z

+   * their return values are ignored, and their errors are caught without
+   * affecting the host or other listeners.
+   */
+  addEventListener<K extends keyof ShopifyEventMap>(


This might override the addEventListener that we create in navigation-api.ts. If anything, we should move 'currententrychange key into the ShopifyEventMap in events.ts

vctrchu self-assigned this Mar 17, 2026

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch from 1ac2792 to 405dc2b Compare March 17, 2026 23:23

vctrchu changed the base branch from 2026-04-rc to vchu/fix-doc-gen-world-path March 17, 2026 23:23

vctrchu mentioned this pull request Mar 17, 2026

2026-04: Fix doc generation to resolve shopify-dev from World #4124

Draft

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch from 6528efa to 2d36a20 Compare March 18, 2026 18:44

NathanJolly reviewed Mar 18, 2026

View reviewed changes

vctrchu changed the title ~~Add TypeScript types for pos.app.ready.data background target~~ feat(pos): add BGX types — pos.app.ready.data target + storage.keys subscribable Mar 27, 2026

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch from 8ce7778 to 06eeda4 Compare March 27, 2026 23:15

vctrchu changed the title ~~feat(pos): add BGX types — pos.app.ready.data target + storage.keys subscribable~~ feat(pos): add TypeScript types for pos.app.ready.data background target Mar 27, 2026

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch 2 times, most recently from e2c600a to e63759e Compare March 30, 2026 21:36

vctrchu marked this pull request as ready for review March 30, 2026 21:39

vctrchu changed the base branch from vchu/fix-doc-gen-world-path to 2026-04-rc March 30, 2026 21:56

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch 3 times, most recently from c9e53ce to 83610ef Compare March 30, 2026 22:07

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch from 83610ef to 3b55663 Compare March 30, 2026 22:14

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch 3 times, most recently from 93c4e1d to 6edab18 Compare March 31, 2026 01:07

vctrchu mentioned this pull request Mar 31, 2026

Mark POS .observe extension targets as @deprecated #4146

Draft

2 tasks

vctrchu requested review from a team and NathanJolly March 31, 2026 01:14

vctrchu marked this pull request as draft March 31, 2026 23:26

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch from 6edab18 to 5d0a28d Compare April 1, 2026 20:10

vctrchu changed the base branch from 2026-04-rc to 2026-07-rc April 18, 2026 00:59

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch from 5d0a28d to 7ab45d5 Compare April 18, 2026 02:09

vctrchu removed the request for review from NathanJolly April 18, 2026 02:10

vctrchu added the #gsd:49396 POS App: Persistent background extension capability label Apr 18, 2026

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch 4 times, most recently from 58916be to b72ad92 Compare April 19, 2026 05:23

vctrchu added 2 commits April 20, 2026 11:56

vctrchu force-pushed the vchu/bgx-types-pos-app-ready-data branch from b72ad92 to 5e4a3ba Compare April 20, 2026 18:59

vctrchu marked this pull request as ready for review April 20, 2026 22:43

js-goupil reviewed Apr 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat(pos): add TypeScript types for pos.app.ready.data background target#4123
vctrchu wants to merge 2 commits into2026-07-rcfrom
vchu/bgx-types-pos-app-ready-data

vctrchu commented Mar 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 17, 2026

Uh oh!

vctrchu commented Mar 17, 2026 •

edited

Loading

Uh oh!

NathanJolly left a comment

Uh oh!

vctrchu commented Mar 18, 2026

Uh oh!

vctrchu commented Mar 30, 2026

Uh oh!

shopify-github-actions-access Bot commented Mar 30, 2026

Uh oh!

vctrchu commented Apr 20, 2026

Uh oh!

shopify-github-actions-access Bot commented Apr 20, 2026

Uh oh!

js-goupil left a comment

Uh oh!

js-goupil Apr 21, 2026

Uh oh!

js-goupil Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

vctrchu commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

New types

Event types

Folder structure

shopify global augmentation

Why

Related PRs

Status

Uh oh!

github-actions Bot commented Mar 17, 2026

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

What should I do?

Uh oh!

vctrchu commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NathanJolly left a comment

Choose a reason for hiding this comment

Uh oh!

vctrchu commented Mar 18, 2026

Uh oh!

vctrchu commented Mar 30, 2026

Uh oh!

shopify-github-actions-access Bot commented Mar 30, 2026

Uh oh!

vctrchu commented Apr 20, 2026

Uh oh!

shopify-github-actions-access Bot commented Apr 20, 2026

Uh oh!

js-goupil left a comment

Choose a reason for hiding this comment

Uh oh!

js-goupil Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

js-goupil Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vctrchu commented Mar 17, 2026 •

edited

Loading

`shopify` global augmentation

vctrchu commented Mar 17, 2026 •

edited

Loading