@primer-io/primer-js 0.3.12 → 0.5.0

package/dist/primer-loader.d.ts

@@ -182,7 +182,8 @@ declare enum HeadlessManagerType {
 	NATIVE = "NATIVE",
 	REDIRECT = "REDIRECT",
 	KLARNA = "KLARNA",
-	ACH = "ACH"
+	ACH = "ACH",
+	BLIK = "BLIK"
 }
 declare enum EventTypes {
 	CHANGE = "change",
@@ -191,6 +192,7 @@ declare enum EventTypes {
 	BLUR = "blur",
 	CLICK = "click",
 	CLOSE = "close",
+	ENTER = "enter",
 	CONFIRMED_KLARNA_CATEGORY = "CONFIRMED_KLARNA_CATEGORY",
 	CONFIRMED_KLARNA_CATEGORY_ERROR = "CONFIRMED_KLARNA_CATEGORY_ERROR",
 	KLARNA_SESSION_UPDATE = "KLARNA_SESSION_UPDATE",
@@ -231,6 +233,9 @@ export interface ClientSessionAddress {
 	countryCode?: string;
 	postalCode?: string;
 }
+export type NullableAddress = {
+	[K in keyof ClientSessionAddress]?: ClientSessionAddress[K] | null;
+};
 export interface ClientSession {
 	orderId?: string;
 	currencyCode?: string;
@@ -313,7 +318,7 @@ export interface InputMetadata {
 	touched: boolean;
 	submitted: boolean;
 }
-export interface PaymentMethodConfig {
+export interface PaymentMethodConfig<T = Record<string, unknown>> {
 	id: string;
 	type: PaymentMethodType;
 	name: string;
@@ -326,9 +331,9 @@ export interface PaymentMethodConfig {
 				light: string;
 			};
 			borderWidth: {
-				colored: number;
-				dark: number;
-				light: number;
+				colored: number | string;
+				dark: number | string;
+				light: number | string;
 			};
 			cornerRadius: number;
 			iconPositionRelativeToText?: "START" | "END";
@@ -348,7 +353,7 @@ export interface PaymentMethodConfig {
 			height: number;
 		};
 	};
-	options: {
+	options: T extends Record<string, unknown> ? T : {
 		captureVaultedCardCvv?: boolean;
 		clientId?: string;
 		threeDSecureToken?: string;
@@ -632,6 +637,11 @@ export interface IAchPaymentMethodManager {
 	declineMandate(): Promise<void>;
 	getPaymentMethod(): void;
 }
+export interface IBlikPaymentMethodManager {
+	start(params: {
+		blikCode: string;
+	}): Promise<void>;
+}
 export interface HeadlessVaultManager {
 	fetchVaultedPaymentMethods(): Promise<VaultedPaymentMethod[]>;
 	deleteVaultedPaymentMethod(id: string): Promise<void>;
@@ -653,6 +663,21 @@ export interface IAssetsManager {
 		displayName?: string;
 	} | null>;
 }
+export interface CheckoutModuleConfig {
+	type: string;
+	options?: Record<string, unknown>;
+}
+export interface ClientConfiguration {
+	binDataUrl: string;
+	checkoutModules?: CheckoutModuleConfig[];
+	clientSession: ClientSession;
+	coreUrl: string;
+	env: string;
+	paymentMethods: PaymentMethodConfig[];
+	pciUrl: string;
+	primerAccountId: string;
+	settleOnAuth?: boolean;
+}
 export interface HeadlessSDKUtilities {
 	getCardNetworkAsset(network: string): {
 		cardUrl: string;
@@ -674,6 +699,7 @@ export interface HeadlessSDKUtilities {
 		goatCdnUrl: string;
 	} | undefined>;
 	getPaymentMethodConfiguration(paymentMethodType: PaymentMethodType): PaymentMethodConfig | undefined;
+	setBillingAddress(address: NullableAddress): Promise<void>;
 }
 export interface CardPaymentMethodManagerOptions {
 	onCardMetadataChange?: (metadata: {
@@ -768,6 +794,7 @@ export interface PrimerHeadlessCheckout {
 	getAssetsManager(): IAssetsManager;
 	start: () => Promise<void>;
 	refreshClientSession(): Promise<boolean>;
+	getConfiguration(): ClientConfiguration;
 	teardown?: () => void;
 }
 export interface HeadlessUniversalCheckoutOptions {
@@ -945,6 +972,27 @@ export interface KlarnaOptions {
  */
 export interface PrimerCheckoutOptions {
 	clientToken?: string;
+	/**
+	 * Sets the localization language for SDK UI text, validation messages, and country names.
+	 *
+	 * Supports standard locale codes in the format `language-COUNTRY` (e.g., `'en-US'`, `'fr-FR'`).
+	 * If an unsupported locale is provided, falls back to `'en-GB'` with a console warning.
+	 *
+	 * Supported locales: `ar`, `bg`, `ca`, `cs`, `da`, `de`, `el`, `en-GB`, `es`, `es-AR`, `es-MX`,
+	 * `et-EE`, `fi-FI`, `fr`, `he`, `hr`, `hu`, `id`, `it`, `ja`, `ko`, `lt`, `lt-LT`, `lv`, `lv-LV`,
+	 * `ms`, `nb`, `nl`, `nl_NL`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sk`, `sl`, `sr-RS`, `sv`, `th`,
+	 * `tr`, `uk-UA`, `vi`, `zh`, `zh-TW`
+	 *
+	 * @default 'en-GB'
+	 * @example
+	 * ```typescript
+	 * // French localization
+	 * { locale: 'fr-FR' }
+	 *
+	 * // Spanish (Mexico)
+	 * { locale: 'es-MX' }
+	 * ```
+	 */
 	locale?: string;
 	apiVersion?: APIVersionOption;
 	/**
@@ -952,40 +1000,239 @@ export interface PrimerCheckoutOptions {
 	 * If not provided, defaults to window.location.hostname.
 	 * This is particularly useful when the checkout is hosted on a different domain
 	 * than the merchant's registered Apple Pay domain.
+	 *
+	 * @default window.location.hostname
 	 */
 	merchantDomain?: string;
+	/**
+	 * Configuration for card payment method options.
+	 * Controls the display and validation of card form fields.
+	 */
 	card?: {
+		/**
+		 * Configuration for the cardholder name input field.
+		 */
 		cardholderName?: {
+			/**
+			 * Whether the cardholder name field is required for form validation.
+			 * When true, form submission is blocked until a valid name is entered.
+			 *
+			 * Note: When using legacy SDK (`sdkCore: false`) with `visible: false`,
+			 * this is automatically set to `false` for compatibility.
+			 *
+			 * @default false
+			 */
 			required?: boolean;
+			/**
+			 * Whether the cardholder name field is visible in the card form.
+			 * When false, the field is hidden and not included in validation.
+			 *
+			 * @default true
+			 */
 			visible?: boolean;
 		};
 	};
+	/**
+	 * Configuration options for Apple Pay button and payment flow.
+	 *
+	 * Controls button appearance, billing/shipping contact field collection,
+	 * and shipping method requirements. The SDK manages button rendering automatically,
+	 * so the `container` property is omitted from this configuration.
+	 *
+	 * @see ApplePayOptions - Full type definition in compatibility-types.ts
+	 * @example
+	 * ```typescript
+	 * applePay: {
+	 *   buttonStyle: 'black',
+	 *   buttonType: 'buy',
+	 *   billingOptions: {
+	 *     requiredBillingContactFields: ['postalAddress', 'emailAddress']
+	 *   },
+	 *   shippingOptions: {
+	 *     requiredShippingContactFields: ['postalAddress', 'name'],
+	 *     requireShippingMethod: true
+	 *   }
+	 * }
+	 * ```
+	 */
 	applePay?: Omit<ApplePayOptions, "container"> & {
+		/**
+		 * @deprecated Use `billingOptions.requiredBillingContactFields: ['postalAddress']` instead.
+		 *
+		 * Legacy option to capture billing address for Apple Pay.
+		 * This property is maintained for backward compatibility.
+		 */
 		captureBillingAddress?: boolean;
+		/**
+		 * Billing contact field configuration for Apple Pay.
+		 */
 		billingOptions?: {
+			/**
+			 * Array of billing contact fields required for checkout.
+			 *
+			 * Valid values: `'emailAddress'`, `'name'`, `'phoneNumber'`, `'postalAddress'`, `'phoneticName'`
+			 *
+			 * @example ['postalAddress', 'emailAddress']
+			 */
 			requiredBillingContactFields?: Array<"emailAddress" | "name" | "phoneNumber" | "postalAddress" | "phoneticName">;
 		};
+		/**
+		 * Shipping contact field and method configuration for Apple Pay.
+		 */
 		shippingOptions?: {
+			/**
+			 * Array of shipping contact fields required for checkout.
+			 *
+			 * Valid values: `'emailAddress'`, `'name'`, `'phoneNumber'`, `'postalAddress'`, `'phoneticName'`
+			 *
+			 * @example ['postalAddress', 'name', 'phoneNumber']
+			 */
 			requiredShippingContactFields?: Array<"emailAddress" | "name" | "phoneNumber" | "postalAddress" | "phoneticName">;
+			/**
+			 * Whether to require shipping method selection during Apple Pay checkout.
+			 *
+			 * When true, customer must select a shipping method before completing payment.
+			 *
+			 * @default false
+			 */
 			requireShippingMethod?: boolean;
 		};
 	};
+	/**
+	 * 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.
+	 *
+	 * @see GooglePayOptions - Full type definition in compatibility-types.ts
+	 * @example
+	 * ```typescript
+	 * googlePay: {
+	 *   buttonType: 'buy',
+	 *   buttonColor: 'black',
+	 *   captureBillingAddress: true,
+	 *   emailRequired: true,
+	 *   shippingAddressParameters: {
+	 *     phoneNumberRequired: true
+	 *   }
+	 * }
+	 * ```
+	 */
 	googlePay?: Omit<GooglePayOptions, "container">;
+	/**
+	 * Configuration options for PayPal button and payment flow.
+	 *
+	 * Controls button styling, size, and payment flow behavior.
+	 * The SDK manages button rendering automatically, so the `container`
+	 * property is omitted from this configuration.
+	 *
+	 * @see PayPalOptions - Full type definition in compatibility-types.ts
+	 * @example
+	 * ```typescript
+	 * paypal: {
+	 *   buttonColor: 'gold',
+	 *   buttonShape: 'pill',
+	 *   buttonLabel: 'pay',
+	 *   paymentFlow: 'PREFER_VAULT'
+	 * }
+	 * ```
+	 */
 	paypal?: Omit<PayPalOptions, "container">;
+	/**
+	 * Configuration options for Klarna payment method.
+	 *
+	 * Controls payment flow, allowed payment categories (pay now/later/over time),
+	 * and button customization for Klarna installment payments.
+	 *
+	 * @see KlarnaOptions - Full type definition in compatibility-types.ts
+	 * @example
+	 * ```typescript
+	 * klarna: {
+	 *   paymentFlow: 'DEFAULT',
+	 *   allowedPaymentCategories: ['pay_now', 'pay_later'],
+	 *   buttonOptions: {
+	 *     text: 'Pay with Klarna'
+	 *   }
+	 * }
+	 * ```
+	 */
 	klarna?: KlarnaOptions;
-	threeDsOptions?: {
-		enabled?: boolean;
-		preferred?: boolean;
-	};
+	/**
+	 * Configuration for payment method vaulting (save for later use).
+	 *
+	 * Enables customers to save payment methods for future transactions.
+	 * Vaulted methods are displayed in the checkout for quick selection.
+	 */
 	vault?: {
+		/**
+		 * Whether vaulting functionality is enabled.
+		 *
+		 * When true:
+		 * - Customers can save payment methods during checkout
+		 * - Previously saved methods are displayed for selection
+		 * - CVV re-capture may be required for vaulted cards (configurable)
+		 *
+		 * When false:
+		 * - Vaulting UI is hidden
+		 * - Only new payment methods can be used
+		 *
+		 * Note: This property is required (not optional).
+		 */
 		enabled: boolean;
+		/**
+		 * Whether to show the vault UI when no payment methods are vaulted.
+		 *
+		 * When true, displays a message encouraging customers to save a payment method.
+		 * When false, hides the vault section entirely when empty.
+		 *
+		 * @default false
+		 */
 		showEmptyState?: boolean;
 	};
+	/**
+	 * Configuration options for Stripe ACH payment method.
+	 *
+	 * Provides Stripe-specific settings for ACH bank account payments,
+	 * including mandate text and authorization requirements.
+	 *
+	 * Note: Only applicable when Stripe ACH is enabled as a payment method.
+	 */
 	stripe?: {
+		/**
+		 * Mandate data for ACH authorization and compliance.
+		 *
+		 * ACH payments require customer authorization (mandate) for bank account debits.
+		 * This configuration controls the mandate text displayed to customers.
+		 */
 		mandateData: {
+			/**
+			 * Custom mandate text for ACH authorization.
+			 *
+			 * When provided, overrides default mandate language.
+			 * Must comply with ACH authorization requirements.
+			 *
+			 * @example "I authorize [Merchant Name] to debit my bank account for the amount shown."
+			 */
 			fullMandateText?: string;
+			/**
+			 * Merchant name displayed in the mandate authorization text.
+			 *
+			 * Used in default mandate language when `fullMandateText` is not provided.
+			 * Should match the legal business name for compliance.
+			 *
+			 * @example "Acme Corporation Inc."
+			 */
 			merchantName?: string;
 		};
+		/**
+		 * Stripe publishable API key for client-side operations.
+		 *
+		 * Required for Stripe ACH functionality. Obtain from Stripe Dashboard.
+		 * Use the publishable key (starts with `pk_`), not the secret key.
+		 *
+		 * @example "pk_test_51H..."
+		 */
 		publishableKey?: string;
 	} & Record<string, unknown>;
 	/**
@@ -1023,8 +1270,76 @@ export interface PrimerCheckoutOptions {
 		 */
 		useBuiltInButton?: boolean;
 	};
+	/**
+	 * Controls which SDK engine is used for payment processing.
+	 *
+	 * - `true` or `undefined`: Uses SDK Core engine (recommended) - modern architecture with better performance
+	 * - `false`: Uses legacy SDK engine (primer-sdk-web) - maintained for backward compatibility only
+	 *
+	 * SDK Core provides:
+	 * - Improved performance and reliability
+	 * - Better error handling and validation
+	 * - Newer payment method features
+	 * - Active development and feature updates
+	 *
+	 * Legacy SDK is maintained for backward compatibility but receives only critical bug fixes.
+	 * New integrations should use SDK Core (leave this option undefined or set to true).
+	 *
+	 * @default true
+	 * @remarks Setting to false may result in different cardholder name handling for compatibility
+	 */
 	sdkCore?: boolean;
+	/**
+	 * Globally disables all payment method interactions in drop-in mode.
+	 *
+	 * When true, all payment method buttons and forms are rendered but disabled,
+	 * creating a display-only preview mode. Useful for showing checkout UI without
+	 * allowing actual transactions (e.g., design previews, demos, screenshots).
+	 *
+	 * When false or undefined, payment methods are fully interactive.
+	 *
+	 * Note: This only affects drop-in mode. Does not apply to headless implementations.
+	 *
+	 * @default false
+	 * @example
+	 * ```typescript
+	 * // Preview mode - show UI but prevent interactions
+	 * { disabledPayments: true }
+	 *
+	 * // Normal mode - fully interactive checkout
+	 * { disabledPayments: false }
+	 * ```
+	 */
 	disabledPayments?: boolean;
+	/**
+	 * Specifies which payment methods are enabled and displayed in the checkout.
+	 *
+	 * By default, only `PaymentMethodType.PAYMENT_CARD` is enabled.
+	 * Configure this to enable specific payment methods for your checkout flow.
+	 *
+	 * Available payment methods include: `PAYMENT_CARD`, `APPLE_PAY`, `GOOGLE_PAY`,
+	 * `PAYPAL`, `KLARNA`, `ADYEN_BLIK`, and many regional payment options.
+	 *
+	 * @default [PaymentMethodType.PAYMENT_CARD]
+	 * @see PaymentMethodType - Full enum of available payment method types
+	 * @example
+	 * ```typescript
+	 * // Enable card and digital wallets
+	 * enabledPaymentMethods: [
+	 *   PaymentMethodType.PAYMENT_CARD,
+	 *   PaymentMethodType.APPLE_PAY,
+	 *   PaymentMethodType.GOOGLE_PAY,
+	 *   PaymentMethodType.PAYPAL
+	 * ]
+	 *
+	 * // Enable card and BLIK (Poland)
+	 * enabledPaymentMethods: [
+	 *   PaymentMethodType.PAYMENT_CARD,
+	 *   PaymentMethodType.ADYEN_BLIK
+	 * ]
+	 * ```
+	 */
+	enabledPaymentMethods?: typeof PaymentMethodType.PAYMENT_CARD | (typeof PaymentMethodType.ADYEN_BLIK)[];
 }
 export type InitializedManager = {
 	type: typeof PaymentMethodType.STRIPE_ACH;
@@ -1041,16 +1356,42 @@ export type InitializedManager = {
 } | {
 	type: typeof PaymentMethodType.PAYPAL | typeof PaymentMethodType.GOOGLE_PAY | typeof PaymentMethodType.APPLE_PAY;
 	manager: INativePaymentMethodManager;
+} | {
+	type: typeof PaymentMethodType.ADYEN_BLIK;
+	manager: IBlikPaymentMethodManager;
 };
+/**
+ * Native payment method types (sent with managerType: 'NATIVE' from server)
+ */
+export type NativePaymentMethodTypes = typeof PaymentMethodType.PAYPAL | typeof PaymentMethodType.GOOGLE_PAY | typeof PaymentMethodType.APPLE_PAY | typeof PaymentMethodType.ADYEN_BLIK;
 export type ManagerByType<T extends PaymentMethodType> = Extract<InitializedManager, {
 	type: T;
 }>;
 export interface InitializedManagersMap extends Map<PaymentMethodType, InitializedManager> {
 	get<T extends PaymentMethodType>(key: T): ManagerByType<T> | undefined;
 }
-export type RedirectPaymentMethodTypes = Exclude<PaymentMethodType, typeof PaymentMethodType.STRIPE_ACH | typeof PaymentMethodType.PAYMENT_CARD | typeof PaymentMethodType.KLARNA | typeof PaymentMethodType.PAYPAL | typeof PaymentMethodType.GOOGLE_PAY | typeof PaymentMethodType.APPLE_PAY>;
+/**
+ * Payment methods that use the REDIRECT manager type.
+ *
+ * This type excludes payment methods with specialized manager types:
+ * - STRIPE_ACH: Uses ACH manager
+ * - PAYMENT_CARD: Uses CARD manager
+ * - KLARNA: Uses KLARNA manager
+ * - PAYPAL, GOOGLE_PAY, APPLE_PAY: Use NATIVE manager
+ * - ADYEN_BLIK: Uses BLIK manager
+ *
+ * All other payment methods use the REDIRECT manager by default.
+ */
+export type RedirectPaymentMethodTypes = Exclude<PaymentMethodType, typeof PaymentMethodType.STRIPE_ACH | typeof PaymentMethodType.PAYMENT_CARD | typeof PaymentMethodType.KLARNA | typeof PaymentMethodType.PAYPAL | typeof PaymentMethodType.GOOGLE_PAY | typeof PaymentMethodType.APPLE_PAY | typeof PaymentMethodType.ADYEN_BLIK>;
 export type DynamicPaymentMethodTypes = typeof PaymentMethodType.STRIPE_ACH;
-export type NativePaymentMethodTypes = typeof PaymentMethodType.PAYPAL | typeof PaymentMethodType.GOOGLE_PAY | typeof PaymentMethodType.APPLE_PAY;
+/**
+ * Represents a payment method that uses the REDIRECT manager.
+ *
+ * REDIRECT payment methods typically involve redirecting the user to an external
+ * page for authorization. However, some REDIRECT payment methods (like BLIK)
+ * use custom inline UI components while still being classified as REDIRECT type
+ * due to their flow characteristics (status polling, external authorization).
+ */
 export type RedirectPaymentMethod = {
 	type: RedirectPaymentMethodTypes;
 	managerType: HeadlessManagerType.REDIRECT;
@@ -1073,6 +1414,9 @@ export type InitializedPaymentMethod = {
 } | {
 	type: typeof PaymentMethodType.APPLE_PAY;
 	managerType: HeadlessManagerType.NATIVE;
+} | {
+	type: typeof PaymentMethodType.ADYEN_BLIK;
+	managerType: HeadlessManagerType.BLIK;
 } | RedirectPaymentMethod;
 export type PaymentMethodByType<T extends PaymentMethodType> = Extract<InitializedPaymentMethod, {
 	type: T;
@@ -1216,6 +1560,7 @@ declare class PrimerEventsController implements ReactiveController {
 export type AnalyticsContextType = AnalyticsUtils | null;
 export type EventsContextType = PrimerEventsController | null;
 export type HeadlessUtilsContextType = HeadlessSDKUtilities | null;
+export type ConfigurationContextType = ClientConfiguration | null;
 export type KlarnaCategoriesContextType = {
 	categories: KlarnaPaymentMethodCategory[];
 	isLoading: boolean;
@@ -1355,6 +1700,7 @@ declare class SDKContextController implements ReactiveController {
 	private vaultManagerCvvProvider;
 	private clientOptionsContext;
 	private headlessUtilsProvider;
+	private configurationProvider;
 	private klarnaCategoriesProvider;
 	private computedStylesProvider;
 	private analyticsProvider;
@@ -1381,6 +1727,8 @@ declare class SDKContextController implements ReactiveController {
 	setKlarnaCategories(value: KlarnaCategoriesContextType): void;
 	setClientOptions(value: PrimerCheckoutOptions | null): void;
 	setHeadlessUtils(value: HeadlessUtilsContextType): void;
+	setConfiguration(value: ConfigurationContextType): void;
+	getConfiguration(): ConfigurationContextType | undefined;
 	setAnalyticsUtils(value: AnalyticsContextType): void;
 	getAnalyticsUtils(): AnalyticsContextType | undefined;
 	setComputedStyles(value: CSSStyleDeclaration): void;
@@ -1987,6 +2335,61 @@ declare global {
 		"primer-input": InputComponent;
 	}
 }
+export interface SelectOption {
+	value: string;
+	label: string;
+}
+/**
+ * A native select dropdown component
+ *
+ * @element primer-select
+ *
+ * @fires change - Fired when selection changes
+ * @fires input - Fired when input value changes
+ * @fires focus - Fired when select receives focus
+ * @fires blur - Fired when select loses focus
+ */
+declare class SelectComponent extends LitElement {
+	static styles: import("lit").CSSResult[];
+	/**
+	 * The name attribute for the select element
+	 */
+	name: string;
+	/**
+	 * The id attribute for the select element
+	 */
+	id: string;
+	/**
+	 * The current value of the select
+	 */
+	value: string;
+	/**
+	 * Whether the select is disabled
+	 */
+	disabled: boolean;
+	/**
+	 * Whether the select is in an error state
+	 */
+	hasError: boolean;
+	/**
+	 * Placeholder text for the select
+	 */
+	placeholder: string;
+	/**
+	 * Array of options for the select
+	 */
+	options: SelectOption[];
+	private handleChange;
+	private handleFocus;
+	private handleBlur;
+	private renderSelectOptions;
+	render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-select": SelectComponent;
+	}
+}
 /**
  * Event detail interface for expanded-changed event
  */
@@ -2271,6 +2674,110 @@ declare global {
 		"primer-paypal": PayPalComponent;
 	}
 }
+/**
+ * BLIK Payment Component
+ *
+ * Consolidated component handling BLIK payment flow from button click through
+ * payment completion. Uses a 4-state machine for managing the user experience.
+ *
+ * @element primer-blik
+ *
+ * @property {InitializedPaymentMethod} paymentMethod - Payment method configuration
+ * @property {boolean} disabled - Disables component interaction when true
+ *
+ * @fires primer-payment-success - Dispatched on successful payment
+ * @fires primer-payment-error - Dispatched on payment error
+ *
+ * @example
+ * ```html
+ * <primer-blik .paymentMethod=${blikMethod}></primer-blik>
+ * <primer-blik disabled></primer-blik>
+ * ```
+ */
+declare class BlikComponent extends LitElement {
+	static styles: import("lit").CSSResult[];
+	paymentMethod: InitializedPaymentMethod | undefined;
+	disabled: boolean;
+	paymentManagers: InitializedManagersMap;
+	private currentState;
+	private blikCode;
+	private errorMessage;
+	private pollingDuration;
+	private pollingTimer;
+	/**
+	 * Manager loading task
+	 * Validates BLIK manager exists before allowing payment flow
+	 *
+	 * This Task provides reactive validation of manager availability:
+	 * - Automatically re-runs when paymentMethod or paymentManagers change
+	 * - Provides type-safe access to the BLIK manager
+	 * - Enables early error detection before user interaction
+	 *
+	 * Unlike native payment methods (Apple Pay, Google Pay, PayPal) which use a
+	 * two-task pattern (manager loading + button rendering), BLIK only needs the
+	 * manager loading task because it renders its own UI via Lit templates.
+	 */
+	private loadManagerTask;
+	/**
+	 * Handles button click to toggle between collapsed and expanded states
+	 */
+	private handleButtonClick;
+	/**
+	 * Handles collapsing the form back to button-only view
+	 * Resets form state when user clicks button to collapse
+	 */
+	private handleCollapse;
+	/**
+	 * Handles input changes, validates numeric input, and auto-submits on 6 digits
+	 */
+	private handleInput;
+	/**
+	 * Handles retry button click
+	 */
+	private handleRetry;
+	/**
+	 * Starts polling timer to track payment duration
+	 */
+	private startPollingTimer;
+	/**
+	 * Stops and resets polling timer
+	 */
+	private stopPollingTimer;
+	/**
+	 * Validates and submits the BLIK code
+	 */
+	private submitBlikCode;
+	/**
+	 * Renders the collapsed button state
+	 */
+	private renderCollapsed;
+	/**
+	 * Renders the expanded input state
+	 */
+	private renderExpandedInput;
+	/**
+	 * Renders the loading state
+	 */
+	private renderLoading;
+	/**
+	 * Renders the error state
+	 */
+	private renderError;
+	/**
+	 * Renders the appropriate expanded state based on current state
+	 */
+	private renderExpandedState;
+	/**
+	 * Cleanup timer on disconnect
+	 */
+	disconnectedCallback(): void;
+	render(): TemplateResult;
+}
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-blik": BlikComponent;
+	}
+}
 declare class PaymentMethodComponent extends LitElement {
 	static styles: import("lit").CSSResult[];
 	type: PaymentMethodType | undefined;
@@ -2417,6 +2924,158 @@ declare global {
 		"primer-redirect-payment": RedirectPaymentComponent;
 	}
 }
+/**
+ * BillingAddressComponent provides a form for collecting billing address information.
+ *
+ * Configuration is exclusively server-side via SDK Core's checkoutModules. Field visibility
+ * is determined by the BILLING_ADDRESS module in the client session configuration.
+ *
+ * @element primer-billing-address
+ *
+ * @fires primer-billing-address-change - Fired when form data changes
+ * @fires primer-billing-address-submit - Fired when form is submitted
+ */
+declare class BillingAddressComponent extends LitElement {
+	static styles: import("lit").CSSResult[];
+	/**
+	 * Configuration from SDK Core containing checkoutModules configuration
+	 */
+	configuration: ConfigurationContextType;
+	/**
+	 * Headless SDK utilities for API methods like setBillingAddress
+	 */
+	headlessUtils: HeadlessUtilsContextType;
+	/**
+	 * Form data state
+	 */
+	private formData;
+	/**
+	 * Validation errors state
+	 */
+	private errors;
+	/**
+	 * Tracks which fields have been touched (blurred after focus)
+	 */
+	private touchedFields;
+	/**
+	 * Tracks which fields are dirty (have had input)
+	 */
+	private dirtyFields;
+	/**
+	 * Tracks which field is currently focused
+	 */
+	private focusedField;
+	/**
+	 * Tracks whether the form has been submitted
+	 * Errors only show after submit or after field blur
+	 */
+	private submitted;
+	/**
+	 * List of countries for the select dropdown
+	 * Initialize with empty array, will be populated in connectedCallback
+	 */
+	private countryOptions;
+	/**
+	 * Initialization task that waits for context availability
+	 *
+	 * Purpose: Ensures configuration and headlessUtils contexts are ready before
+	 *          attempting field configuration extraction and country initialization
+	 *
+	 * Lifecycle:
+	 * - Task runs when this.configuration or this.headlessUtils changes
+	 * - Stays pending (returns initialState) until both contexts are available
+	 * - Completes when field config is extracted and countries initialized
+	 *
+	 * Phase 2: Infrastructure setup with stub methods
+	 * Phase 3: Will extract field configuration from checkoutModules
+	 * Phase 4: Will coordinate country initialization with Task lifecycle
+	 */
+	private _initializationTask;
+	/**
+	 * Initialize countries list
+	 */
+	connectedCallback(): void;
+	/**
+	 * Extract billing address field configuration from SDK Core checkoutModules
+	 * @param configuration - Configuration context from SDK Core
+	 * @returns Field configuration object
+	 */
+	private extractFieldConfig;
+	/**
+	 * Initialize country options with two-phase loading:
+	 * 1. Synchronously load English countries first
+	 * 2. Asynchronously load locale-specific countries
+	 *
+	 * This preserves the existing behavior where users see English countries
+	 * immediately, then see localized names if available.
+	 */
+	private initializeCountryOptions;
+	/**
+	 * Get billing address field configuration from SDK Core checkoutModules.
+	 *
+	 * This getter is used during rendering after the initialization task completes.
+	 * Configuration is determined by server-side checkoutModules configuration.
+	 * If not present, defaults to all fields disabled (form hidden).
+	 */
+	private get fieldConfig();
+	/**
+	 * Default field configuration (all fields disabled).
+	 * When no configuration is provided, the form is hidden.
+	 * This matches the legacy SDK behavior where billing address is opt-in.
+	 */
+	private get defaultFieldConfig();
+	/**
+	 * Check if the form should be visible
+	 * According to legacy SDK: form is hidden if postalCode is false
+	 */
+	private get shouldShowForm();
+	/**
+	 * Handle input change events
+	 */
+	private handleInput;
+	/**
+	 * Handle focus events
+	 */
+	private handleFocus;
+	/**
+	 * Handle blur events for validation
+	 */
+	private handleBlur;
+	/**
+	 * Validate a single field
+	 */
+	private validateField;
+	/**
+	 * Validate all enabled fields
+	 */
+	private validateForm;
+	/**
+	 * Public method to validate billing address fields
+	 * Called by the parent form (card-form) when submitting
+	 * Returns true if billing address is valid
+	 * Note: Does NOT call setBillingAddress API - that happens after card validation
+	 */
+	validateForSubmission(): Promise<boolean>;
+	/**
+	 * Public method to submit billing address to SDK Core
+	 * Called by parent form ONLY after both card and billing address validation pass
+	 *
+	 * Note: headlessUtils is guaranteed to be available when this method is called,
+	 * as the component only renders (and becomes interactive) after initialization task completes.
+	 */
+	submitToSDK(): Promise<boolean>;
+	/**
+	 * Check if field should show error
+	 * Matches card input behavior: show errors after submit OR after field is dirty AND touched
+	 */
+	private shouldShowError;
+	render(): symbol | import("lit-html").TemplateResult<1> | undefined;
+}
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-billing-address": BillingAddressComponent;
+	}
+}
 /**
  * Interface for secure htmlContent access
  */
@@ -2430,7 +3089,7 @@ export interface PortalDialogData {
 	onOpen?: () => void;
 	onContentRendered?: () => void;
 }
-export declare class PortalDialogComponent extends LitElement {
+declare class PortalDialogComponent extends LitElement {
 	static styles: import("lit").CSSResult[];
 	size: "flex" | "large";
 	showCloseButton: boolean;
@@ -2463,6 +3122,11 @@ export declare class PortalDialogComponent extends LitElement {
 	updated(changedProperties: Map<string, unknown>): void;
 	render(): import("lit-html").TemplateResult<1>;
 }
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-portal-dialog": PortalDialogComponent;
+	}
+}
 /**
  * Events emitted by the vault manager components
  */
@@ -2904,6 +3568,11 @@ declare class CardFormComponent extends LitElement {
 	 */
 	private hasAssignedContent;
 	private selectedCardNetwork;
+	/**
+	 * Form-level error message to display
+	 * @private
+	 */
+	private formErrorMessage;
 	/**
 	 * Flag to track if PAYMENT_METHOD_SELECTION event has been sent
 	 * @private
@@ -3358,7 +4027,7 @@ declare class CardFormSubmitComponent extends LitElement {
 	 */
 	get buttonText(): string;
 	set buttonText(value: string);
-	headlessInstance: HeadlessUtilsContextType;
+	headlessUtils: HeadlessUtilsContextType;
 	clientOptions: ClientOptionsContextType;
 	sdkState: SdkStateContextType;
 	cardFormContext: CardFormContext | null;
@@ -3588,6 +4257,8 @@ export declare function loadPrimer(): void;
 export {
 	AchPaymentComponent as AchPayment,
 	ApplePayComponent as ApplePay,
+	BillingAddressComponent as BillingAddress,
+	BlikComponent as Blik,
 	ButtonComponent as Button,
 	CardFormComponent as CardForm,
 	CardFormSubmitComponent as CardFormSubmit,
@@ -3610,6 +4281,7 @@ export {
 	PaymentMethodComponent as PaymentMethod,
 	PaymentMethodContainerComponent as PaymentMethodContainer,
 	PortalComponent as Portal,
+	PortalDialogComponent as PortalDialog,
 	PrimerCheckoutCompleteComponent as PrimerCheckoutComplete,
 	PrimerCheckoutErrorComponent as PrimerCheckoutFailure,
 	PrimerCheckoutStateComponent as PrimerCheckoutState,
@@ -3617,6 +4289,7 @@ export {
 	PrimerKlarnaComponent as PrimerKlarna,
 	PrimerMainComponent as PrimerMain,
 	RedirectPaymentComponent as RedirectPayment,
+	SelectComponent as Select,
 	ShowOtherPaymentsComponent as ShowOtherPayments,
 	SpinnerComponent as Spinner,
 	VaultCvvInputComponent as VaultCvvInput,