@economist/web-apple-pay 0.1.1-beta.0

package/README.md

@@ -0,0 +1,186 @@
+# @economist/web-apple-pay
+
+Framework-agnostic Apple Pay UI components implemented as Web Components.
+
+This package provides:
+
+- `teg-apple-pay-button`
+- `teg-apple-pay-modal`
+
+It is intentionally UI-focused. Consumer applications own backend payment orchestration, merchant validation, and secret handling.
+
+## Requirements
+
+- Node.js `20.x` or later
+- npm `10.x` or later
+
+## Installation
+
+```sh
+npm install --save @economist/web-apple-pay
+```
+
+## Quick start
+
+### 1) Configure runtime values
+
+Call `configureApplePay(...)` once during app startup, before rendering Apple Pay UI:
+
+```ts
+import { configureApplePay, defineApplePayElements } from '@economist/web-apple-pay';
+
+configureApplePay({
+  merchantId: 'merchant.com.economist.your-app',
+  debugBypassEnabled: false,
+  // required: wallet API base URL for session and checkout calls
+  walletApiBaseUrl: 'https://bff-test.economist.com',
+});
+
+defineApplePayElements();
+```
+
+### 2) Create and mount a button
+
+```ts
+import type { Offer, ApplePayButton } from '@economist/web-apple-pay';
+
+const button = document.createElement('teg-apple-pay-button') as ApplePayButton;
+button.offer = offer as Offer;
+button.country = 'US';
+button.dataset.loggedIn = 'true';
+
+container.appendChild(button);
+```
+
+When clicked, the button creates and opens `teg-apple-pay-modal` automatically.
+
+## Runtime configuration
+
+### `configureApplePay(config)`
+
+Sets package-level runtime configuration used by Apple Pay availability checks.
+Call this once during app startup.
+
+`config` shape:
+
+- `merchantId` (`string`, required): Apple Pay merchant identifier used for active-card checks.
+- `debugBypassEnabled` (`boolean`, optional): allows `?BYPASS_APPLE_PAY_CHECKS=1` query param to bypass capability checks in non-production-style debugging flows.
+- `walletApiBaseUrl` (`string`, required): base URL for wallet API requests.
+
+If `merchantId` is not configured, Apple Pay availability checks return `false` and the button hides itself.
+
+## Component behavior
+
+### `ApplePayButton`
+
+- Requires `offer` and `country` before click flow is meaningful.
+- Checks Apple Pay availability on connect; if unavailable, it hides.
+- Skips rendering for excluded variants (`bundle`, `insider_print`).
+- Forwards `data-logged-in` from button to modal (`modal.dataset.loggedIn`).
+
+#### Awaiting render completion — `whenReady()`
+
+Use `whenReady()` to await the component's render lifecycle after appending it
+to the DOM. This is the supported, stable way to know whether Apple Pay is
+available without touching lifecycle internals.
+
+```ts
+container.appendChild(btn);   // spec-compliant — browser fires connectedCallback naturally
+await btn.whenReady();        // resolves when rendering is complete
+if (btn.style.display !== 'none') {
+  // Apple Pay rendered successfully
+} else {
+  btn.remove(); // unavailable or suppressed
+}
+```
+
+> **Important:** calling `whenReady()` _before_ `appendChild` resolves
+> immediately to `undefined` — it does not wait for a future connection.
+> Always call it after appending the element.
+
+### `ApplePayModal`
+
+- Opened by `ApplePayButton` click.
+- Emits `apple-pay-confirmed` when CTA is accepted.
+- `Escape` closes the modal and prevents propagation to other global handlers.
+
+## Events
+
+### `apple-pay-confirmed`
+
+Dispatched from `ApplePayModal` as a `CustomEvent` with:
+
+- `detail.skuId` (`string`)
+- `detail.country` (`string`)
+
+Consumers should listen for this event and continue payment orchestration.
+
+## Public API
+
+- `defineApplePayElements()`: registers both custom elements.
+- `configureApplePay(config)`: sets required runtime config (merchant ID and wallet API base URL, with optional debug bypass).
+- `ApplePayButton`: button component class.
+  - `whenReady(): Promise<void>` — resolves when the current render lifecycle completes (available or hidden). Resolves immediately if called before the element is connected.
+- `ApplePayModal`: modal component class.
+- `ensureApplePayLogoSymbol()`: logo symbol injection helper.
+- `Offer`: offer contract type used by component props.
+
+## Troubleshooting
+
+### Button does not appear
+
+Check:
+
+- `configureApplePay(...)` was called before rendering (with a valid `merchantId` and `walletApiBaseUrl`)
+- device/browser supports Apple Pay checks (Safari/Apple device logic)
+- query string/feature flag gating for your page is satisfied
+- offer variant is not excluded (`bundle`, `insider_print`)
+
+### Logged-in checkbox copy looks wrong
+
+Set `button.dataset.loggedIn = 'true'` before appending the button. The button forwards this flag to the modal automatically.
+
+## Security and responsibilities
+
+Merchant setup must be handled by the consuming application:
+
+- inject merchant config at runtime
+- perform merchant validation on trusted backend services
+- keep certificates/secrets outside this package
+
+## Local development
+
+From `shared-packages`:
+
+```sh
+cd packages/web-apple-pay
+npm run build
+yalc publish --sig
+```
+
+Then in a consuming app:
+
+```sh
+yalc add @economist/web-apple-pay
+```
+
+## Storybook
+
+Run Storybook locally:
+
+```sh
+npm run storybook --workspace @economist/web-apple-pay
+```
+
+Build static Storybook output:
+
+```sh
+npm run build-storybook --workspace @economist/web-apple-pay
+```
+
+Story coverage matrix:
+
+- `ApplePayButton` docs page shows the stable default example.
+- `ApplePayButton` behavior and state variants are available as individual canvas stories in Storybook.
+- `ApplePayModal` docs page shows the stable default example.
+- `ApplePayModal` behavior and state variants are available as individual canvas stories in Storybook.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './src/index';