diff --git a/pos-background/README.md b/pos-background/README.md new file mode 100644 index 00000000..d5ea2bb0 --- /dev/null +++ b/pos-background/README.md @@ -0,0 +1,8 @@ +# POS background extension + +Scaffold for a non-visual POS background extension targeting `pos.app.ready.data`. + +The background target runs for the full POS session and observes events via +`shopify.addEventListener()`. It does not render UI. See the example handlers in +`src/background-extension.{js,ts}` for `transactioncomplete`, +`cashtrackingsessionstart`, and `cashtrackingsessioncomplete`. diff --git a/pos-background/package.json.liquid b/pos-background/package.json.liquid new file mode 100644 index 00000000..69c5bedf --- /dev/null +++ b/pos-background/package.json.liquid @@ -0,0 +1,9 @@ +{ + "name": "{{ handle }}", + "private": true, + "version": "1.0.0", + "license": "UNLICENSED", + "dependencies": { + "@shopify/ui-extensions": "2026.7.x" + } +} diff --git a/pos-background/shopify.extension.toml.liquid b/pos-background/shopify.extension.toml.liquid new file mode 100644 index 00000000..1658c75b --- /dev/null +++ b/pos-background/shopify.extension.toml.liquid @@ -0,0 +1,12 @@ +api_version = "2026-07" + +[[extensions]] +type = "ui_extension" +name = "{{ name }}" +{% if uid %}uid = "{{ uid }}"{% endif %} +handle = "{{ handle }}" +description = "A {{ flavor }} POS background extension" + +[[extensions.targeting]] +module = "./src/background-extension.{{ srcFileExtension }}" +target = "pos.app.ready.data" diff --git a/pos-background/src/background-extension.liquid b/pos-background/src/background-extension.liquid new file mode 100644 index 00000000..8a28df7e --- /dev/null +++ b/pos-background/src/background-extension.liquid @@ -0,0 +1,36 @@ +import { POS_EVENT_NAMES } from '@shopify/ui-extensions/point-of-sale'; +{% if flavor contains "typescript" %} +import type { + TransactionCompleteEvent, + CashTrackingSessionStartEvent, + CashTrackingSessionCompleteEvent, +} from '@shopify/ui-extensions/point-of-sale'; +import type { Api } from '@shopify/ui-extensions/pos.app.ready.data'; +{% endif %} + +export default ({% if flavor contains "typescript" %}api: Api{% else %}_api{% endif %}) => { + try { + shopify.addEventListener( + POS_EVENT_NAMES.TRANSACTION_COMPLETE, + (event{% if flavor contains "typescript" %}: TransactionCompleteEvent{% endif %}) => { + console.log('transaction complete', event); + }, + ); + + shopify.addEventListener( + POS_EVENT_NAMES.CASH_TRACKING_SESSION_START, + (event{% if flavor contains "typescript" %}: CashTrackingSessionStartEvent{% endif %}) => { + console.log('cash tracking session start', event); + }, + ); + + shopify.addEventListener( + POS_EVENT_NAMES.CASH_TRACKING_SESSION_COMPLETE, + (event{% if flavor contains "typescript" %}: CashTrackingSessionCompleteEvent{% endif %}) => { + console.log('cash tracking session complete', event); + }, + ); + } catch (error) { + console.error('failed to register background extension listeners', error); + } +}; diff --git a/pos-background/tsconfig.json.liquid b/pos-background/tsconfig.json.liquid new file mode 100644 index 00000000..a13080d8 --- /dev/null +++ b/pos-background/tsconfig.json.liquid @@ -0,0 +1,12 @@ +{ + "compilerOptions": { + "target": "ES2020", + "checkJs": true, + "allowJs": true, + "moduleResolution": "node", + "esModuleInterop": true, + "noEmit": true, + "skipLibCheck": true + }, + "include": ["./src", "./shopify.d.ts"] +} diff --git a/templates.json b/templates.json index 932f48ed..aa09a76d 100644 --- a/templates.json +++ b/templates.json @@ -1340,6 +1340,29 @@ ], "minimumCliVersion": "3.85.3" }, + { + "identifier": "pos_background", + "name": "POS background", + "defaultName": "pos-background", + "group": "UI extensions", + "supportLinks": [], + "url": "https://github.com/Shopify/extensions-templates", + "type": "ui_extension", + "extensionPoints": [], + "supportedFlavors": [ + { + "name": "TypeScript", + "value": "typescript", + "path": "pos-background" + }, + { + "name": "JavaScript", + "value": "vanilla-js", + "path": "pos-background" + } + ], + "minimumCliVersion": "3.85.3" + }, { "identifier": "cart_checkout_validation", "name": "Cart and checkout validation",