@primer-io/primer-js 1.7.0 → 1.8.0

package/dist/jsx/index.d.ts

@@ -71,8 +71,6 @@ export type PrimerCheckoutComponentProps = {
 This is used to control the CSS-only loader visibility */
   "js-initialized"?: boolean;
   /**  */
-  jsInitialized?: boolean;
-  /**  */
   primerJS?: PrimerJS | undefined;
   /**  */
   options?: PrimerCheckoutOptions;

package/dist/primer-loader.d.ts

@@ -1,7 +1,6 @@
 import { ContextProvider } from '@lit/context';
 import { Task, initialState } from '@lit/task';
-import { PayPalButtonStyle } from '@paypal/paypal-js';
-import { FUNDING_SOURCE } from '@paypal/paypal-js/types/components/funding-eligibility';
+import { FUNDING_SOURCE, PayPalButtonStyle } from '@paypal/paypal-js';
 import { CSSResult, LitElement, PropertyValues, ReactiveController, ReactiveControllerHost, SVGTemplateResult, TemplateResult, nothing } from 'lit';
 
 declare global {
@@ -268,7 +267,9 @@ export interface GooglePayClientOptions {
 	 */
 	captureBillingAddress?: boolean;
 	/**
-	 * When true, requests shipping address from Google Pay and updates client session.
+	 * When true, requests shipping address from Google Pay and updates client
+	 * session. Register `onShippingAddressChange` to supply shipping options
+	 * for display in the sheet.
 	 */
 	captureShippingAddress?: boolean;
 	/**
@@ -281,10 +282,9 @@ export interface GooglePayClientOptions {
 	 */
 	emailRequired?: boolean;
 	/**
-	 * When true, enables shipping method selection in the Google Pay payment sheet.
-	 * Shipping methods are read from the SHIPPING checkout module in the client configuration.
-	 * When the user selects a shipping option, the SDK will call selectShippingMethod()
-	 * on the client session API to update the order on the backend.
+	 * When true, enables shipping method selection in the Google Pay payment
+	 * sheet. Register `onShippingAddressChange` to supply the option list and
+	 * `onShippingOptionChange` to commit the shopper's selection.
 	 */
 	requireShippingMethod?: boolean;
 	/**
@@ -371,29 +371,15 @@ export interface BillingAddressCheckoutModule {
 	type: "BILLING_ADDRESS";
 	options: BillingAddressModuleOptions;
 }
-/**
- * Shipping method for express checkout flows (Google Pay, Apple Pay).
- */
-export interface ShippingMethod {
-	/** Unique identifier for the shipping method */
-	id: string;
-	/** Display name for the shipping method */
-	name: string;
-	/** Description (e.g., "5-7 business days") */
-	description: string;
-	/** Shipping cost in minor units */
-	amount: number;
-	/** Type of shipping method */
-	type?: "shipping" | "pickup";
-}
 /**
  * Shipping checkout module options
  */
 export interface ShippingModuleOptions {
-	/** Available shipping methods */
-	shippingMethods: ShippingMethod[];
+	/** Available shipping methods (legacy `shippingMethodsUrl` path only) */
+	shippingMethods: ShippingOption[];
 	/** Currently selected shipping method ID */
 	selectedShippingMethod?: string;
+	callbackMode?: boolean;
 }
 /**
  * Shipping checkout module
@@ -407,6 +393,20 @@ export interface ShippingCheckoutModule {
  * Supports billing address and shipping modules
  */
 export type CheckoutModuleConfig = BillingAddressCheckoutModule | ShippingCheckoutModule;
+/**
+ * A shipping option offered to the shopper inside an Express Checkout
+ * (Apple Pay / Google Pay) payment sheet — either the legacy
+ * `shippingMethodsUrl`-resolved list (read from `ShippingCheckoutModule`),
+ * or merchant-supplied via the newer event-driven flow: returned via the
+ * `setShippingOptions` handler on `onShippingAddressChange`, and passed back
+ * via `onShippingOptionChange` once the shopper selects one.
+ */
+export interface ShippingOption {
+	amount: number;
+	id: string;
+	name: string;
+	description: string;
+}
 export type ApprovalMode = "AUTO" | "MANUAL";
 export interface ClientSession {
 	clientSessionId: string;
@@ -722,6 +722,51 @@ export interface PayPalOptionsWithPaypalJsTypes {
 	enableFunding?: FUNDING_SOURCE[];
 	integrationDate?: string;
 	debug?: boolean;
+	/**
+	 * PayPal App Switch configuration.
+	 *
+	 * When enabled, tapping the PayPal button attempts to open the PayPal app
+	 * (falling back to the web flow when unavailable), and the buyer is
+	 * returned to complete checkout. The SDK uses your `returnUrl` as the PayPal
+	 * order/billing-agreement return and cancel URLs, and resumes the pending
+	 * session on return.
+	 */
+	appSwitch?: {
+		/**
+		 * Whether App Switch is enabled.
+		 * @default false
+		 */
+		enabled?: boolean;
+		/**
+		 * The full URL PayPal returns and cancels to after the app switch.
+		 * **Required when App Switch is enabled**, and PayPal requires it to be the
+		 * same URL the SDK was initialized on. The SDK appends `?clientToken=…` so
+		 * that page can resume the pending session.
+		 */
+		returnUrl?: string;
+		/**
+		 * Host-app bridge for checkout embedded in a native app's webview, where
+		 * PayPal's in-browser App Switch cannot return. The SDK hands the approval
+		 * deep link to the host app, which opens it and calls `resumeAppSwitch()`
+		 * on the native return.
+		 */
+		hostApp?: {
+			/** Return the host native app's return deep link, OS, and OS version. */
+			getContext: () => Promise<{
+				appUrl: string;
+				osType: "IOS" | "ANDROID" | "OTHER";
+				/** Host OS version, e.g. "14". */
+				osVersion?: string;
+			}>;
+			/**
+			 * Open the PayPal approval deep link. The native return appends
+			 * `/success` or `/cancel` to the return URL and carries the `token`
+			 * (order id) on both — route by path: `resumeAppSwitch(token)` on
+			 * success, `cancelAppSwitch()` on cancel.
+			 */
+			openApprovalUrl: (approvalUrl: string) => void | Promise<void>;
+		};
+	};
 }
 export interface LegacyApplePayOptions {
 	/**
@@ -769,6 +814,11 @@ export interface ApplePayClientOptions {
 		 * @see https://developer.apple.com/documentation/applepayontheweb/applepaypaymentrequest/requiredshippingcontactfields
 		 */
 		requiredShippingContactFields?: ("postalAddress" | "name" | "phoneticName" | "phone" | "email")[];
+		/**
+		 * When true, enables shipping method selection in the Apple Pay sheet.
+		 * Register `onShippingAddressChange` to supply the option list and
+		 * `onShippingOptionChange` to commit the shopper's selection.
+		 */
 		requireShippingMethod?: boolean;
 	};
 }
@@ -1145,8 +1195,11 @@ export interface BlikPaymentMethod {
 	 */
 	start(): Promise<void>;
 }
+/**
+ * A payment method rendered as a branded button by an external SDK.
+ */
 export interface NativePaymentMethod {
-	type: typeof PaymentMethodType.APPLE_PAY | typeof PaymentMethodType.GOOGLE_PAY | typeof PaymentMethodType.PAYPAL;
+	type: typeof PaymentMethodType.APPLE_PAY | typeof PaymentMethodType.GOOGLE_PAY;
 	managerType: HeadlessManagerType.NATIVE;
 	/**
 	 * Initialize the payment method (e.g. load the external SDK)
@@ -1158,6 +1211,22 @@ export interface NativePaymentMethod {
 	render(container: HTMLElement, buttonOptions?: PaymentRenderButtonOptions): Promise<void>;
 	setDisabled(disabled: boolean): Promise<void>;
 }
+/**
+ * PayPal renders like the other native methods, plus the host-app App Switch
+ * entry points. Both warn and do nothing unless `paypal.appSwitch.hostApp` is
+ * configured.
+ */
+export interface PayPalPaymentMethod {
+	type: typeof PaymentMethodType.PAYPAL;
+	managerType: HeadlessManagerType.NATIVE;
+	start(): Promise<void>;
+	render(container: HTMLElement, buttonOptions?: PaymentRenderButtonOptions): Promise<void>;
+	setDisabled(disabled: boolean): Promise<void>;
+	/** Finishes the payment after the buyer returns, with the `orderId` the host app captured. */
+	resumeAppSwitch(orderId: string): Promise<void>;
+	/** Propagates a user cancellation when the buyer returns without approving. */
+	cancelAppSwitch(): Promise<void>;
+}
 /**
  * Payment method types that have a surface of their own. Everything else is
  * driven generically — by a redirect, or by the backend.
@@ -1459,12 +1528,67 @@ export interface CreateHeadlessOptions {
 	 * is resolved. Not fired for a fresh checkout (no attempt in flight).
 	 */
 	onCheckoutResume?: () => void;
+	/**
+	 * Express Checkout (Apple Pay / Google Pay): invoked when the shopper
+	 * changes/enters their shipping address inside the native payment sheet.
+	 * The merchant computes shipping options for that address and calls
+	 * `setShippingOptions` with the result; the SDK displays them in the
+	 * sheet. Display-only — the SDK does not persist the list.
+	 *
+	 * Required for `captureShippingAddress`/`requireShippingMethod` (Google
+	 * Pay) or `shippingOptions.requireShippingMethod` (Apple Pay) to show any
+	 * shipping options. If not registered, no options are shown and a warning
+	 * is logged.
+	 *
+	 * Must call `setShippingOptions` within 20 seconds or the payment attempt
+	 * fails with a `REQUEST_TIMEOUT` error. If integrating via
+	 * `addEventListener('primer:shipping-address-change', ...)` instead of
+	 * this callback, call `event.preventDefault()` synchronously to signal you
+	 * will respond asynchronously — otherwise the SDK assumes nothing is
+	 * listening, logs a warning, and your later response is ignored.
+	 *
+	 * Not invoked at all if a legacy `shippingMethodsUrl`-configured `SHIPPING`
+	 * checkout module is present on the client session — that legacy,
+	 * server-resolved flow takes priority silently (a warning is logged, but
+	 * this callback is simply never called). The two are mutually exclusive;
+	 * remove the `shippingMethodsUrl` configuration to use this callback.
+	 */
+	onShippingAddressChange?: (data: {
+		paymentMethodType: PaymentMethodType;
+		shippingAddress: NullableAddress;
+	}, handler: {
+		setShippingOptions: (options: ShippingOption[]) => void;
+	}) => void;
+	/**
+	 * Express Checkout (Apple Pay / Google Pay): invoked when the shopper
+	 * selects one of the shipping options supplied via
+	 * `onShippingAddressChange`. The merchant's backend should PATCH the
+	 * client session with the authoritative shipping amount (+ tax) before
+	 * calling `continue()` to acknowledge. Payment authorization is gated on
+	 * this ack.
+	 *
+	 * Must call `continue()` within 20 seconds or the payment attempt fails
+	 * with a `REQUEST_TIMEOUT` error. If integrating via
+	 * `addEventListener('primer:shipping-option-change', ...)` instead of
+	 * this callback, call `event.preventDefault()` synchronously to signal you
+	 * will respond asynchronously — otherwise the SDK assumes nothing is
+	 * listening, logs a warning, and your later response is ignored.
+	 *
+	 * Not invoked at all if a legacy `shippingMethodsUrl`-configured `SHIPPING`
+	 * checkout module is present — see `onShippingAddressChange`.
+	 */
+	onShippingOptionChange?: (data: {
+		paymentMethodType: PaymentMethodType;
+		selectedShippingOption: ShippingOption;
+	}, handler: {
+		continue: () => void;
+	}) => void;
 	onBinDataAvailable?: (event: BinDataAvailableEvent) => void;
 	onBinDataLoadingChange?: (loading: boolean) => void;
 	onCardNetworksChange?: (event: CardNetworkChangeEvent) => void;
 	onCardNetworksLoading?: () => void;
 }
-export type InitializedPaymentMethod = CardPaymentMethod | KlarnaPaymentMethod | AdyenKlarnaPaymentMethod | QRCodePaymentMethod | BlikPaymentMethod | MbwayPaymentMethod | RedirectPaymentMethod | BackendDrivenPaymentMethod | NativePaymentMethod;
+export type InitializedPaymentMethod = CardPaymentMethod | KlarnaPaymentMethod | AdyenKlarnaPaymentMethod | QRCodePaymentMethod | BlikPaymentMethod | MbwayPaymentMethod | RedirectPaymentMethod | BackendDrivenPaymentMethod | NativePaymentMethod | PayPalPaymentMethod;
 export interface CardSecurityCodeInputOptions {
 	ariaLabel?: string;
 	container: string | Element | HTMLElement;
@@ -1485,7 +1609,7 @@ export interface InputMetadata {
 	touched: boolean;
 	submitted: boolean;
 }
-export interface PrimerCheckoutOptions extends Omit<CreateHeadlessOptions, "dialogProvider"> {
+export interface PrimerCheckoutOptions extends Omit<CreateHeadlessOptions, "dialogProvider" | "onShippingAddressChange" | "onShippingOptionChange"> {
 	giftCard?: {
 		logoSrc: string;
 		background: string;
@@ -1680,11 +1804,17 @@ export type SdkState = {
 	 */
 	isProcessing: boolean;
 	/**
-	 * SDK/component initialization errors.
-	 * This represents errors from the Primer JS layer itself (e.g., configuration errors,
-	 * component initialization failures), not payment processing errors.
-	 */
-	primerJsError: Error | null;
+	 * SDK initialization errors — never payment-processing failures (those go
+	 * to `paymentFailure`). The error thrown during initialization is kept
+	 * as-is; common codes:
+	 * - `INVALID_CLIENT_TOKEN`: the client token is malformed, expired, or was
+	 *   rejected — generate a new one
+	 * - `INITIALIZATION_ERROR`: any other initialization failure (e.g. the
+	 *   configuration failed to load)
+	 * `origin` says who should act on it ('network' marks retryable failures);
+	 * the underlying cause is nested in `error`.
+	 */
+	primerJsError: SdkError | null;
 	isLoading: boolean;
 	/**
 	 * Payment processing failure information.
@@ -2115,13 +2245,6 @@ export declare class PrimerJS {
 	 * Returns the cached list of payment methods.
 	 */
 	getPaymentMethods(): InitializedPaymentMethod[];
-	/**
-	 * Internal accessor that returns the initialized payment methods (with their
-	 * managers), used by the refresh path to preserve manager identity across
-	 * client-session refreshes.
-	 * @internal
-	 */
-	getInitializedPaymentMethods(): InitializedPaymentMethod[];
 	/**
 	 * Internal method to handle the onPaymentStart callback
 	 * @internal - This is only used internally by the SDK
@@ -2150,6 +2273,29 @@ export declare class PrimerJS {
 	 * ```
 	 */
 	setCardholderName(cardholderName: string): void;
+	/**
+	 * PayPal host-app App Switch: finishes the payment after the buyer returns
+	 * from the PayPal app, with the `orderId` the host app read from the return
+	 * deep link's `token` param. The outcome arrives through the usual
+	 * onCheckoutComplete/onCheckoutFail callbacks.
+	 *
+	 * Does not need the PayPal button to have rendered.
+	 *
+	 * @example
+	 * ```typescript
+	 * const checkout = document.querySelector('primer-checkout');
+	 * await checkout.primerJS?.resumeAppSwitch(orderIdFromDeepLink);
+	 * ```
+	 */
+	resumeAppSwitch(orderId: string): Promise<void>;
+	/** PayPal host-app App Switch: cancels when the buyer returns without approving. */
+	cancelAppSwitch(): Promise<void>;
+	/**
+	 * Warns rather than throwing when PayPal is absent: the host app calls these
+	 * on a deep-link return, where whether PayPal is in the session is not its
+	 * business.
+	 */
+	private findPayPalMethod;
 }
 export interface CardSubmitResult {
 	success?: boolean;
@@ -2223,6 +2369,18 @@ export interface PrimerEvents {
 	"primer:payment-approval-required": CustomEvent<PaymentApprovalRequiredData & {
 		timestamp: number;
 	}>;
+	"primer:shipping-address-change": CustomEvent<{
+		paymentMethodType: PaymentMethodType;
+		shippingAddress: NullableAddress;
+		setShippingOptions: (options: ShippingOption[]) => void;
+		timestamp: number;
+	}>;
+	"primer:shipping-option-change": CustomEvent<{
+		paymentMethodType: PaymentMethodType;
+		selectedShippingOption: ShippingOption;
+		continue: () => void;
+		timestamp: number;
+	}>;
 	"primer:vault-methods-update": CustomEvent<{
 		vaultedPayments: VaultedPaymentMethodSummary[];
 		cvvRecapture: boolean;
@@ -2302,6 +2460,26 @@ declare class PrimerEventsController {
 	 * backend to call /approve or /abort, and continueFlow() to resume the SDK.
 	 */
 	dispatchPaymentApprovalRequired(detail: PaymentApprovalRequiredData): void;
+	/**
+	 * @returns true if a listener called `preventDefault()` or
+	 * `setShippingOptions` synchronously; false if nothing is listening, so
+	 * the caller can resolve on its own rather than waiting out its timeout.
+	 */
+	dispatchShippingAddressChange(detail: {
+		paymentMethodType: PaymentMethodType;
+		shippingAddress: NullableAddress;
+		setShippingOptions: (options: ShippingOption[]) => void;
+	}): boolean;
+	/**
+	 * @returns true if a listener called `preventDefault()` or `continue()`
+	 * synchronously; false if nothing is listening, so the caller can resolve
+	 * on its own rather than waiting out its timeout.
+	 */
+	dispatchShippingOptionChange(detail: {
+		paymentMethodType: PaymentMethodType;
+		selectedShippingOption: ShippingOption;
+		continue: () => void;
+	}): boolean;
 	/**
 	 * Dispatch vault methods update event.
 	 * Called when vaulted payment methods are loaded or updated.
@@ -2460,8 +2638,6 @@ declare class HeadlessSdkController implements ReactiveController {
 	host: PrimerCheckoutType;
 	private currentSdkInstance;
 	private primerJS;
-	private loadingTimeout;
-	private isDisconnected;
 	/**
 	 * Session-bound telemetry of the current SDK instance. Held here (in
 	 * addition to the Lit context) so teardown paths can still emit
@@ -2472,8 +2648,6 @@ declare class HeadlessSdkController implements ReactiveController {
 	get primerJSInstance(): PrimerJS | null;
 	hostConnected(): void;
 	hostDisconnected(): void;
-	private setupLoadingTimeout;
-	private clearLoadingTimeout;
 	private cleanupResources;
 	/**
 	 * Datadog error reporting that works across the whole lifecycle: uses the
@@ -2489,6 +2663,19 @@ declare class HeadlessSdkController implements ReactiveController {
 	 * synchronously read state see `isProcessing: true`.
 	 */
 	private handlePaymentApprovalRequired;
+	/**
+	 * Bridges sdk-core's shipping-address-change callback to the
+	 * primer:shipping-address-change DOM event, auto-resolving with no
+	 * options so sdk-core's promise doesn't time out if nothing responds.
+	 */
+	private handleShippingAddressChange;
+	/**
+	 * Express Checkout (Apple Pay / Google Pay): sdk-core invokes this when the
+	 * shopper selects one of the shipping options previously supplied via
+	 * onShippingAddressChange. Same bridge/auto-resolve shape as
+	 * handleShippingAddressChange above.
+	 */
+	private handleShippingOptionChange;
 	initializeHeadless(): ([clientToken, options]: readonly [
 		string | null,
 		PrimerCheckoutOptions | null
@@ -2512,8 +2699,6 @@ declare class HeadlessSdkController implements ReactiveController {
  * 2. Setting the CSS custom property --primer-loader-disabled: 1
  */
 export declare class PrimerCheckoutComponent extends LitElement implements PrimerCheckoutType {
-	set jsInitialized(value: boolean);
-	get jsInitialized(): boolean;
 	get primerJS(): PrimerJS | undefined;
 	static styles: CSSResult[];
 	customStyles: string;
@@ -2525,11 +2710,9 @@ export declare class PrimerCheckoutComponent extends LitElement implements Prime
 	 * This is used to control the CSS-only loader visibility
 	 * @private
 	 */
-	private _jsInitialized;
+	private jsInitialized;
 	defaultSlot: HTMLSlotElement;
-	private previousLoadingState;
 	private hasAssignedContent;
-	private _loadingTimeoutId;
 	private _eventListenerController;
 	private _classObserver;
 	locale: LocaleCode;
@@ -2541,7 +2724,7 @@ export declare class PrimerCheckoutComponent extends LitElement implements Prime
 	headlessSdkController: HeadlessSdkController;
 	constructor();
 	connectedCallback(): void;
-	attributeChangedCallback(attrName: string, oldVal: string, newVal: string): void;
+	attributeChangedCallback(attrName: "custom-styles" | (string & {}), oldVal: string, newVal: string): void;
 	disconnectedCallback(): void;
 	willUpdate(changedProperties: PropertyValues): void;
 	updated(): void;
@@ -2560,11 +2743,6 @@ export declare class PrimerCheckoutComponent extends LitElement implements Prime
 	 * Uses AbortController signal to prevent circular event loops more safely
 	 */
 	private handleExternalShowOtherPaymentsToggle;
-	/**
-	 * Check if the loading state has changed and update the CSS loader visibility accordingly.
-	 * This method is called after each update cycle to detect when loading is complete.
-	 */
-	private checkLoadingStateChange;
 	render(): TemplateResult;
 	addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: PrimerCheckoutComponent, ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
 	addEventListener<K extends keyof ShadowRootEventMap>(type: K, listener: (this: PrimerCheckoutComponent, ev: ShadowRootEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;