@primer-io/primer-js 0.11.0 → 0.12.0

package/dist/jsx/index.d.ts

@@ -1199,9 +1199,9 @@ export type CustomElements = {
    *
    * PayPal uses the standard button container approach:
    * - Renders to a button container div (not shadow root)
-   * - Passes buttonHeight in render options with PayPal SDK constraints (25-55px)
+   * - Passes buttonHeight in render options (sdk-core constrains to 25-55px)
    * - Uses updateOverlayForContainer for disabled state
-   * - Warns if height exceeds maximum allowed by PayPal SDK
+   * - Height is calculated from CSS (PAYMENT_METHOD_LINE_HEIGHT + padding)
    * ---
    *
    */

package/dist/primer-loader.d.ts

@@ -352,6 +352,122 @@ declare const PaymentInstrumentType$1 = {
 	ADYEN_AFFIRM: "ADYEN_AFFIRM",
 } as const;
 type PaymentInstrumentType$1 = (typeof PaymentInstrumentType$1)[keyof typeof PaymentInstrumentType$1];
+/**
+ * Google Pay shipping address parameters.
+ * @see https://developers.google.com/pay/api/web/reference/request-objects#ShippingAddressParameters
+ */
+export interface GooglePayShippingAddressParameters {
+	/**
+	 * ISO 3166-1 alpha-2 country codes where shipping is allowed.
+	 * If not specified, all shipping address countries are allowed.
+	 */
+	allowedCountryCodes?: string[];
+	/**
+	 * Set to true if a phone number is required for the shipping address.
+	 */
+	phoneNumberRequired?: boolean;
+}
+/**
+ * Google Pay button type options.
+ * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+ */
+export type GooglePayButtonType = google.payments.api.ButtonType;
+/**
+ * Google Pay button color options.
+ * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+ */
+export type GooglePayButtonColor = google.payments.api.ButtonColor;
+/**
+ * Google Pay button size mode options.
+ * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+ */
+export type GooglePayButtonSizeMode = google.payments.api.ButtonSizeMode;
+/**
+ * Google Pay button border type options.
+ * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+ */
+export type GooglePayButtonBorderType = google.payments.api.ButtonBorderType;
+/**
+ * Google Pay client-side options provided by the merchant.
+ */
+export interface GooglePayClientOptions {
+	/**
+	 * When true, requests billing address from Google Pay and updates client session.
+	 */
+	captureBillingAddress?: boolean;
+	/**
+	 * When true, requests shipping address from Google Pay and updates client session.
+	 */
+	captureShippingAddress?: boolean;
+	/**
+	 * Shipping address parameters. Only used when captureShippingAddress is true.
+	 * @see https://developers.google.com/pay/api/web/reference/request-objects#ShippingAddressParameters
+	 */
+	shippingAddressParameters?: GooglePayShippingAddressParameters;
+	/**
+	 * When true, requests email address from Google Pay and updates client session.
+	 */
+	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.
+	 */
+	requireShippingMethod?: boolean;
+	/**
+	 * When true (and environment is PRODUCTION), the Google Pay button will only be
+	 * displayed if the user already has an existing payment method that can be used.
+	 * This enables a one-tap checkout experience for returning users.
+	 *
+	 * @default false
+	 * @see https://developers.google.com/pay/api/web/reference/request-objects#IsReadyToPayRequest
+	 */
+	existingPaymentMethodRequired?: boolean;
+	/**
+	 * The type of button displayed. Each button type has a localized label.
+	 * @default 'buy'
+	 * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+	 */
+	buttonType?: GooglePayButtonType;
+	/**
+	 * The color of the button.
+	 * - 'default' or 'black': Suitable for light colored backgrounds
+	 * - 'white': Suitable for dark colored backgrounds
+	 * @default 'black'
+	 * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+	 */
+	buttonColor?: GooglePayButtonColor;
+	/**
+	 * The size mode of the button.
+	 * - 'static': Button is sized according to the translated buttonType
+	 * - 'fill': Button fills the container width (use CSS to control size)
+	 * @default 'fill'
+	 * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+	 */
+	buttonSizeMode?: GooglePayButtonSizeMode;
+	/**
+	 * The corner radius of the button in pixels.
+	 * Minimum is 0, maximum depends on button height (e.g., max 20 for 40px height).
+	 * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+	 */
+	buttonRadius?: number;
+	/**
+	 * The locale for the button text.
+	 * ISO 639-1 code (e.g., 'en', 'de', 'fr', 'ja').
+	 * If not specified, defaults to browser/OS locale.
+	 * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+	 */
+	buttonLocale?: string;
+	/**
+	 * The border type of the button.
+	 * - 'default_border': A thin border is displayed around the button (default)
+	 * - 'no_border': No border is displayed around the button
+	 * @default 'default_border'
+	 * @see https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
+	 */
+	buttonBorderType?: GooglePayButtonBorderType;
+}
 /**
  * Minimal payment summary with reduced PII exposure.
  * Used in events for public data delivery.
@@ -1080,6 +1196,8 @@ export interface AnalyticsUtils {
 	clientSessionId?: string;
 	clientSessionToken?: string;
 	sdkVersion?: string;
+	/** Timestamp (ms) when the first backend call (/configuration) started */
+	configurationFetchStartTime?: number;
 }
 export interface PrimerHeadlessCheckout {
 	createPaymentMethodManager(type: "PAYMENT_CARD", options?: PaymentMethodManagerOptions): Promise<ICardPaymentMethodManager | null>;
@@ -1402,25 +1520,38 @@ export interface PrimerCheckoutOptions {
 	/**
 	 * Configuration options for Google Pay button and payment flow.
 	 *
-	 * Controls button appearance, billing/shipping address collection,
-	 * and email requirements. The SDK manages button rendering automatically,
-	 * so the `container` property is omitted from this configuration.
+	 * When `sdkCore: true` (default), uses `GooglePayClientOptions` from SDK Core with
+	 * full express checkout support including:
+	 * - Button customization (`buttonType`, `buttonColor`, `buttonSizeMode`, `buttonRadius`, `buttonLocale`)
+	 * - Billing/shipping address capture
+	 * - Email collection
+	 * - Shipping method selection
+	 *
+	 * When `sdkCore: false`, uses legacy `GooglePayOptions` with basic button styling.
 	 *
-	 * @see GooglePayOptions - Full type definition in compatibility-types.ts
 	 * @example
 	 * ```typescript
+	 * // SDK Core mode (recommended)
+	 * googlePay: {
+	 *   buttonType: 'checkout',
+	 *   buttonColor: 'white',
+	 *   buttonSizeMode: 'fill',
+	 *   buttonRadius: 8,
+	 *   captureBillingAddress: true,
+	 *   captureShippingAddress: true,
+	 *   emailRequired: true,
+	 *   requireShippingMethod: true,
+	 * }
+	 *
+	 * // Legacy mode (sdkCore: false)
 	 * googlePay: {
 	 *   buttonType: 'buy',
 	 *   buttonColor: 'black',
 	 *   captureBillingAddress: true,
-	 *   emailRequired: true,
-	 *   shippingAddressParameters: {
-	 *     phoneNumberRequired: true
-	 *   }
 	 * }
 	 * ```
 	 */
-	googlePay?: Omit<GooglePayOptions, "container">;
+	googlePay?: GooglePayClientOptions | Omit<GooglePayOptions, "container">;
 	/**
 	 * Configuration options for PayPal button and payment flow.
 	 *
@@ -1996,8 +2127,8 @@ export interface PrepareHandler {
 export interface PaymentSuccessData {
 	/** Minimal payment summary (ID, orderId, last4, brand) - reduced PII exposure */
 	payment: PaymentSummary;
-	/** Payment method type (e.g., "PAYMENT_CARD", "PAYPAL") */
-	paymentMethodType: string;
+	/** Payment method type. May be undefined when paymentMethodData is not included in response (e.g., legacy SDK mode). */
+	paymentMethodType?: PaymentMethodType;
 	/** Unix timestamp in seconds */
 	timestamp: number;
 }
@@ -2015,8 +2146,8 @@ export interface PaymentFailureData {
 	};
 	/** Optional minimal payment summary if payment was created before failure */
 	payment?: PaymentSummary;
-	/** Payment method type (e.g., "PAYMENT_CARD", "PAYPAL") */
-	paymentMethodType: string;
+	/** Payment method type. May be undefined when payment object is not returned in the callback. */
+	paymentMethodType?: PaymentMethodType;
 	/** Unix timestamp in seconds */
 	timestamp: number;
 }
@@ -2353,7 +2484,7 @@ export interface PrimerEvents {
 	"primer:payment-start": CustomEvent<undefined>;
 	"primer:payment-success": CustomEvent<{
 		paymentSummary: PaymentSummary;
-		paymentMethodType: string;
+		paymentMethodType?: PaymentMethodType;
 		timestamp: number;
 	}>;
 	"primer:payment-failure": CustomEvent<{
@@ -2364,7 +2495,7 @@ export interface PrimerEvents {
 			data?: Record<string, unknown>;
 		};
 		paymentSummary?: PaymentSummary;
-		paymentMethodType: string;
+		paymentMethodType?: PaymentMethodType;
 		timestamp: number;
 	}>;
 	"primer:vault:methods-update": CustomEvent<{
@@ -2415,7 +2546,7 @@ declare class PrimerEventsController implements ReactiveController {
 	 * Dispatch payment success event with minimal payment summary.
 	 * Called when payment completes successfully.
 	 */
-	dispatchPaymentSuccess(payment: Payment, paymentMethodType: string): void;
+	dispatchPaymentSuccess(payment: Payment, paymentMethodType: PaymentMethodType | undefined): void;
 	/**
 	 * Dispatch payment failure event.
 	 * Called when payment fails or is declined.
@@ -2425,7 +2556,7 @@ declare class PrimerEventsController implements ReactiveController {
 		message: string;
 		diagnosticsId?: string;
 		data?: Record<string, unknown>;
-	}, paymentMethodType: string, payment?: Payment): void;
+	}, paymentMethodType: PaymentMethodType | undefined, payment?: Payment): void;
 	/**
 	 * Dispatch vault methods update event.
 	 * Called when vaulted payment methods are loaded or updated.
@@ -3519,9 +3650,9 @@ declare global {
  *
  * PayPal uses the standard button container approach:
  * - Renders to a button container div (not shadow root)
- * - Passes buttonHeight in render options with PayPal SDK constraints (25-55px)
+ * - Passes buttonHeight in render options (sdk-core constrains to 25-55px)
  * - Uses updateOverlayForContainer for disabled state
- * - Warns if height exceeds maximum allowed by PayPal SDK
+ * - Height is calculated from CSS (PAYMENT_METHOD_LINE_HEIGHT + padding)
  */
 declare class PayPalComponent extends LitElement {
 	static styles: import("lit").CSSResult[];