@primer-io/primer-js 0.4.0 → 0.5.0

package/dist/jsx/index.d.ts

@@ -313,6 +313,19 @@ export type BillingAddressComponentProps = {
   "onprimer-billing-address-submit"?: (e: CustomEvent<CustomEvent>) => void;
 };
 
+export type BlikComponentProps = {
+  /** Payment method configuration */
+  paymentMethod?: InitializedPaymentMethod;
+  /** Disables component interaction when true */
+  disabled?: boolean;
+  /**  */
+  paymentManagers?: InitializedManagersMap;
+  /** Dispatched on successful payment */
+  "onprimer-payment-success"?: (e: CustomEvent<never>) => void;
+  /** Dispatched on payment error */
+  "onprimer-payment-error"?: (e: CustomEvent<never>) => void;
+};
+
 export type CardFormComponentProps = {
   /**  */
   "hide-labels"?: boolean;
@@ -926,6 +939,20 @@ export type CustomElements = {
    */
   "primer-billing-address": Partial<BillingAddressComponentProps & BaseProps & BaseEvents>;
 
+  /**
+   * 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.
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **primer-payment-success** - Dispatched on successful payment
+   * - **primer-payment-error** - Dispatched on payment error
+   */
+  "primer-blik": Partial<BlikComponentProps & BaseProps & BaseEvents>;
+
   /**
    * CardFormComponent serves as a container for card input components.
    * It handles form submission, validation, and provides context to child components.

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",
@@ -636,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>;
@@ -966,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;
 	/**
@@ -973,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>;
 	/**
@@ -1045,13 +1271,75 @@ export interface PrimerCheckoutOptions {
 		useBuiltInButton?: boolean;
 	};
 	/**
-	 * Enable SDK Core engine (recommended)
+	 * 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 Set to false to use legacy SDK engine
+	 * @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;
@@ -1068,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;
@@ -1100,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;
@@ -2357,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;
@@ -2668,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;
@@ -2701,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
  */
@@ -3832,6 +4258,7 @@ export {
 	AchPaymentComponent as AchPayment,
 	ApplePayComponent as ApplePay,
 	BillingAddressComponent as BillingAddress,
+	BlikComponent as Blik,
 	ButtonComponent as Button,
 	CardFormComponent as CardForm,
 	CardFormSubmitComponent as CardFormSubmit,
@@ -3854,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,