@primer-io/primer-js 0.14.1 → 1.0.0

package/dist/jsx/index.d.ts

@@ -320,6 +320,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;
@@ -343,19 +356,6 @@ Uses client configuration with fallback to default (false) */
   shouldRequireCardholderName?: boolean;
 };
 
-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 DynamicPaymentComponentProps = {
   /**  */
   paymentMethod?: InitializedPaymentMethod | undefined;
@@ -961,14 +961,6 @@ export type CustomElements = {
    */
   "primer-billing-address": Partial<BillingAddressComponentProps & BaseProps & BaseEvents>;
 
-  /**
-   * CardFormComponent serves as a container for card input components.
-   * It handles form submission, validation, and provides context to child components.
-   * ---
-   *
-   */
-  "primer-card-form": Partial<CardFormComponentProps & BaseProps & BaseEvents>;
-
   /**
    * BLIK Payment Component
    *
@@ -983,6 +975,14 @@ export type CustomElements = {
    */
   "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.
+   * ---
+   *
+   */
+  "primer-card-form": Partial<CardFormComponentProps & BaseProps & BaseEvents>;
+
   /**
    *
    * ---

package/dist/primer-loader.d.ts

@@ -810,6 +810,24 @@ export interface CardNetworkChangeEvent {
 	};
 	source: "REMOTE" | "LOCAL" | "LOCAL_FALLBACK";
 }
+export interface BinDataDetails extends CardNetworkDetails {
+	issuerCountryCode?: string;
+	issuerName?: string;
+	accountFundingType?: string;
+	prepaidReloadableIndicator?: string;
+	productUsageType?: string;
+	productCode?: string;
+	productName?: string;
+	issuerCurrencyCode?: string;
+	regionalRestriction?: string;
+	accountNumberType?: string;
+}
+export interface BinDataAvailableEvent {
+	preferred?: BinDataDetails;
+	alternatives: BinDataDetails[];
+	status: "complete" | "partial";
+	firstDigits?: string;
+}
 export interface CardPaymentMethodSubmitValues {
 	cardNetwork?: string;
 }
@@ -1124,6 +1142,8 @@ export interface HeadlessSDKUtilities {
 	setBillingAddress(address: NullableAddress): Promise<void>;
 }
 export interface CardPaymentMethodManagerOptions {
+	onBinDataAvailable?: (event: BinDataAvailableEvent) => void;
+	onBinDataLoadingChange?: (loading: boolean) => void;
 	onCardMetadataChange?: (metadata: {
 		type: CardNetworkType | null;
 		possibleTypes: string[];
@@ -1907,72 +1927,6 @@ export interface AssetsConfig {
 	name: string;
 	iconUrl: string;
 }
-export declare class InitializedPayments {
-	private readonly _methods;
-	constructor(map: InitializedPaymentMethodMap);
-	get<T extends RedirectPaymentMethodTypes>(type: T): RedirectPaymentMethod | undefined;
-	get<T extends (typeof PaymentMethodType)[keyof typeof PaymentMethodType]>(type: T): PaymentMethodByType<T> | undefined;
-	toArray(): InitializedPaymentMethod[];
-	size(): number;
-}
-/**
- * Map of vaulted payment method ID to vaulted payment method summary
- */
-export type VaultedPaymentMethodsMap = Map<string, VaultedPaymentMethodSummary>;
-/**
- * Wrapper class for vaulted payment methods that provides type-safe access
- * to filtered vaulted payment method data.
- *
- * This class mirrors the structure of InitializedPayments but for vault data,
- * providing a consistent API for merchants to access vaulted payment methods
- * through events and callbacks.
- *
- * @example
- * ```typescript
- * // Access via callback
- * primerJS.onVaultedMethodsUpdate = (data) => {
- *   console.log('Vault size:', data.size());
- *
- *   // Get specific method by ID
- *   const method = data.get('pm_abc123');
- *   if (method) {
- *     console.log('Last 4:', method.paymentInstrumentData?.last4Digits);
- *   }
- *
- *   // Get all methods
- *   const allMethods = data.toArray();
- *   allMethods.forEach(method => {
- *     console.log(method.paymentMethodType);
- *   });
- * };
- * ```
- */
-export declare class InitializedVaultedPayments {
-	private readonly _methods;
-	/**
-	 * @param map - Map of vaulted payment method IDs to summaries
-	 */
-	constructor(map: VaultedPaymentMethodsMap);
-	/**
-	 * Get a vaulted payment method by its ID
-	 *
-	 * @param id - Payment method ID
-	 * @returns Vaulted payment method summary if found, undefined otherwise
-	 */
-	get(id: string): VaultedPaymentMethodSummary | undefined;
-	/**
-	 * Get all vaulted payment methods as an array
-	 *
-	 * @returns Array of all vaulted payment method summaries
-	 */
-	toArray(): VaultedPaymentMethodSummary[];
-	/**
-	 * Get the count of vaulted payment methods
-	 *
-	 * @returns Number of vaulted payment methods
-	 */
-	size(): number;
-}
 export type ReducerCallbacks<State, _Action extends {
 	type: string;
 }> = {
@@ -2070,9 +2024,9 @@ declare class VaultManagerController extends CompositeStateController<PrimerChec
 	 * Applies PII filtering to all vaulted payment methods.
 	 *
 	 * @param vaultedPaymentMethods - Raw vaulted payment methods from API
-	 * @returns InitializedVaultedPayments wrapper with filtered data
+	 * @returns Array of filtered vaulted payment method summaries
 	 */
-	private createVaultedPaymentsWrapper;
+	private createVaultedPaymentsArray;
 	/**
 	 * Update vaulted payment methods and dispatch events/callbacks.
 	 * This method:
@@ -2166,8 +2120,8 @@ export interface PaymentFailureData {
  * Includes filtered vaulted payment methods with minimal PII exposure.
  */
 export interface VaultedMethodsUpdateData {
-	/** Wrapper containing filtered vaulted payment methods */
-	vaultedPayments: InitializedVaultedPayments;
+	/** Array of filtered vaulted payment method summaries */
+	vaultedPayments: VaultedPaymentMethodSummary[];
 	/** Indicates if CVV recapture is required for vaulted payments */
 	cvvRecapture: boolean;
 	/** Unix timestamp in seconds */
@@ -2229,51 +2183,42 @@ export declare class PrimerJS {
 	 */
 	readonly vault: VaultAPI;
 	/**
-	 * Called when payment flow begins.
-	 * Use for analytics tracking or UI updates (e.g., disable form).
+	 * @deprecated Use the `primer:payment-start` event instead.
 	 *
-	 * @example
+	 * Listen to the event on the checkout element:
 	 * ```typescript
-	 * primerJS.onPaymentStart = () => {
+	 * checkout.addEventListener('primer:payment-start', (e) => {
 	 *   analytics.track('payment_started');
 	 *   disablePaymentForm();
-	 * };
+	 * });
 	 * ```
 	 */
 	onPaymentStart?: () => void;
 	/**
-	 * Called before payment creation for validation or abort control flow.
-	 * Use for last-chance validation or conditional payment creation.
+	 * @deprecated Use the `primer:payment-start` event instead.
 	 *
-	 * @param data - Payment method information
-	 * @param handler - Control flow handler (continue or abort)
-	 *
-	 * @example
+	 * Listen to the event on the checkout element:
 	 * ```typescript
-	 * primerJS.onPaymentPrepare = (data, handler) => {
-	 *   if (!validateBusinessRules(data.paymentMethodType)) {
-	 *     handler.abortPaymentCreation();
+	 * checkout.addEventListener('primer:payment-start', (e) => {
+	 *   const { paymentMethodType, abortPaymentCreation, continuePaymentCreation } = e.detail;
+	 *
+	 *   if (!validateBusinessRules(paymentMethodType)) {
+	 *     abortPaymentCreation();
 	 *     return;
 	 *   }
-	 *   handler.continuePaymentCreation();
-	 * };
+	 *   continuePaymentCreation({ idempotencyKey: 'optional-key' });
+	 * });
 	 * ```
 	 */
 	onPaymentPrepare?: (data: PaymentData, handler: PrepareHandler) => void;
 	/**
-	 * Called when payment completes successfully.
-	 * Receives minimal payment summary with reduced PII exposure.
+	 * @deprecated Use the `primer:payment-success` event instead.
 	 *
-	 * Use for:
-	 * - Order confirmation and backend sync
-	 * - Receipt generation
-	 * - Payment processing with minimal PII exposure
-	 *
-	 * @param data - Payment success data with PaymentSummary (ID, orderId, last4, brand)
-	 *
-	 * @example
+	 * Listen to the event on the checkout element:
 	 * ```typescript
-	 * primerJS.onPaymentSuccess = async ({ payment, paymentMethodType }) => {
+	 * checkout.addEventListener('primer:payment-success', (e) => {
+	 *   const { payment, paymentMethodType } = e.detail;
+	 *
 	 *   // Update backend
 	 *   await fetch(`/api/orders/${payment.orderId}/complete`, {
 	 *     method: 'POST',
@@ -2282,24 +2227,17 @@ export declare class PrimerJS {
 	 *
 	 *   // Redirect to success page
 	 *   window.location.href = `/order-success?id=${payment.orderId}`;
-	 * };
+	 * });
 	 * ```
 	 */
 	onPaymentSuccess?: (data: PaymentSuccessData) => void;
 	/**
-	 * Called when payment fails or is declined.
-	 * Receives error details and optional payment summary if created before failure.
-	 *
-	 * Use for:
-	 * - Error handling and user messaging
-	 * - Support ticket creation with diagnosticsId
-	 * - Retry logic for specific error types
+	 * @deprecated Use the `primer:payment-failure` event instead.
 	 *
-	 * @param data - Payment failure data with error details and optional PaymentSummary
-	 *
-	 * @example
+	 * Listen to the event on the checkout element:
 	 * ```typescript
-	 * primerJS.onPaymentFailure = ({ error, payment }) => {
+	 * checkout.addEventListener('primer:payment-failure', (e) => {
+	 *   const { error, payment } = e.detail;
 	 *   console.error('Payment failed:', error.code, error.message);
 	 *
 	 *   // Log to error tracking
@@ -2312,30 +2250,21 @@ export declare class PrimerJS {
 	 *
 	 *   // Show user-friendly message
 	 *   showErrorMessage(error.message);
-	 * };
+	 * });
 	 * ```
 	 */
 	onPaymentFailure?: (data: PaymentFailureData) => void;
 	/**
-	 * Called when vaulted payment methods are loaded or updated.
-	 * Receives filtered vaulted payment method data with minimal PII exposure.
-	 *
-	 * Use for:
-	 * - Building custom vault UI
-	 * - Determining if CVV recapture is required (check cvvRecapture flag)
-	 * - Analytics tracking for vault usage
-	 * - Syncing vault state with backend
-	 *
-	 * @param data - Vault methods update data with filtered payment methods and cvvRecapture flag
+	 * @deprecated Use the `primer:vault-methods-update` event instead.
 	 *
-	 * @example
+	 * Listen to the event on the checkout element:
 	 * ```typescript
-	 * primerJS.onVaultedMethodsUpdate = ({ vaultedPayments }) => {
-	 *   console.log(`Vault contains ${vaultedPayments.size()} methods`);
+	 * checkout.addEventListener('primer:vault-methods-update', (e) => {
+	 *   const { vaultedPayments } = e.detail;
+	 *   console.log(`Vault contains ${vaultedPayments.length} methods`);
 	 *
 	 *   // Display in custom UI
-	 *   const methods = vaultedPayments.toArray();
-	 *   methods.forEach(method => {
+	 *   vaultedPayments.forEach(method => {
 	 *     displayVaultedMethod({
 	 *       id: method.id,
 	 *       type: method.paymentMethodType,
@@ -2343,7 +2272,7 @@ export declare class PrimerJS {
 	 *       network: method.paymentInstrumentData?.network,
 	 *     });
 	 *   });
-	 * };
+	 * });
 	 * ```
 	 */
 	onVaultedMethodsUpdate?: (data: VaultedMethodsUpdateData) => void;
@@ -2352,7 +2281,7 @@ export declare class PrimerJS {
 	 * Set the initialized payment methods
 	 * @internal - This is only used internally by the SDK
 	 */
-	setPaymentMethods(methods: InitializedPayments): void;
+	setPaymentMethods(methods: InitializedPaymentMethod[]): void;
 	/**
 	 * Set the initialized payment managers
 	 * @internal - This is only used internally by the SDK
@@ -2416,23 +2345,11 @@ export declare class PrimerJS {
 	 * @internal - This is only used internally by the SDK
 	 */
 	handlePaymentStart(): void;
-	/**
-	 * Internal method to handle the onBeforePaymentCreate callback and transform it to onPaymentPrepare
-	 * @internal - This is only used internally by the SDK
-	 */
-	handleBeforePaymentCreate(data: {
-		paymentMethodType: PaymentMethodType;
-	}, originalHandler: {
-		continuePaymentCreation: (data?: {
-			idempotencyKey?: string;
-		}) => void;
-		abortPaymentCreation: () => void;
-	}): void;
 	/**
 	 * Internal method to handle the onVaultedMethodsUpdate callback
 	 * @internal - This is only used internally by the SDK
 	 */
-	handleVaultedMethodsUpdate(vaultedPayments: InitializedVaultedPayments, cvvRecapture: boolean): void;
+	handleVaultedMethodsUpdate(vaultedPayments: VaultedPaymentMethodSummary[], cvvRecapture: boolean): void;
 	/**
 	 * Sets the cardholder name value in the card payment form.
 	 *
@@ -2483,19 +2400,32 @@ export interface ShowOtherPaymentsToggledPayload {
 }
 export interface PrimerEvents {
 	"primer:state-change": CustomEvent<SdkStateContextType>;
-	"primer:methods-update": CustomEvent<InitializedPayments>;
+	"primer:methods-update": CustomEvent<InitializedPaymentMethod[]>;
 	"primer:ready": CustomEvent<PrimerJS>;
 	"primer:card-network-change": CustomEvent<CardNetworksContextType>;
+	"primer:bin-data-loading-change": CustomEvent<{
+		loading: boolean;
+	}>;
+	"primer:bin-data-available": CustomEvent<BinDataAvailableEvent>;
 	"primer:card-submit": CustomEvent<CardSubmitPayload>;
 	"primer:card-success": CustomEvent<CardSubmitSuccessPayload>;
 	"primer:card-error": CustomEvent<CardSubmitErrorsPayload>;
+	"primer:dialog-open": CustomEvent;
+	"primer:dialog-close": CustomEvent;
 	"primer-ach-error": CustomEvent<PrimeAchErrorPayload>;
 	"primer-ach-bank-details-collected": CustomEvent;
 	"primer-ach-mandate-confirmed": CustomEvent;
 	"primer-ach-mandate-declined": CustomEvent;
-	"primer:payment-start": CustomEvent<undefined>;
+	"primer:payment-start": CustomEvent<{
+		paymentMethodType: PaymentMethodType;
+		abortPaymentCreation: () => void;
+		continuePaymentCreation: (data?: {
+			idempotencyKey?: string;
+		}) => void;
+		timestamp: number;
+	}>;
 	"primer:payment-success": CustomEvent<{
-		paymentSummary: PaymentSummary;
+		payment: PaymentSummary;
 		paymentMethodType?: PaymentMethodType;
 		timestamp: number;
 	}>;
@@ -2506,15 +2436,20 @@ export interface PrimerEvents {
 			diagnosticsId?: string;
 			data?: Record<string, unknown>;
 		};
-		paymentSummary?: PaymentSummary;
+		payment?: PaymentSummary;
 		paymentMethodType?: PaymentMethodType;
 		timestamp: number;
 	}>;
-	"primer:vault:methods-update": CustomEvent<{
-		vaultedPayments: InitializedVaultedPayments;
+	"primer:payment-cancel": CustomEvent<{
+		paymentMethodType: PaymentMethodType | null;
+		timestamp: number;
+	}>;
+	"primer:vault-methods-update": CustomEvent<{
+		vaultedPayments: VaultedPaymentMethodSummary[];
+		cvvRecapture: boolean;
 		timestamp: number;
 	}>;
-	"primer:vault:selection-change": CustomEvent<{
+	"primer:vault-selection-change": CustomEvent<{
 		paymentMethodId: string | null;
 		timestamp: number;
 	}>;
@@ -2535,12 +2470,17 @@ declare class PrimerEventsController implements ReactiveController {
 	 */
 	dispatchEvent<K extends keyof PrimerEvents>(type: K, detail: PrimerEvents[K]["detail"]): void;
 	dispatchSdkState(sdkState: SdkStateContextType): void;
-	dispatchPaymentMethods(paymentMethods: InitializedPayments): void;
+	dispatchPaymentMethods(paymentMethods: InitializedPaymentMethod[]): void;
 	dispatchCheckoutInitialized(checkoutInstance: PrimerJS): void;
 	dispatchCardNetworkChange(network: CardNetworksContextType): void;
+	dispatchBinDataAvailable(data: BinDataAvailableEvent): void;
+	dispatchBinDataLoadingChange(loading: boolean): void;
 	dispatchCardSubmit(source?: string): void;
 	dispatchFormSubmitSuccess(result: CardSubmitResult): void;
 	dispatchFormSubmitErrors(errors: InputValidationError[]): void;
+	dispatchPaymentCancel(data: {
+		paymentMethodType: PaymentMethodType | null;
+	}): void;
 	/**
 	 * Handle external card submit events and forward them through the event system.
 	 * This method provides a centralized way to process external card submission events
@@ -2551,9 +2491,15 @@ declare class PrimerEventsController implements ReactiveController {
 	handleExternalCardSubmit(eventDetails: CardSubmitPayload): void;
 	/**
 	 * Dispatch payment start event.
-	 * Called when payment flow begins.
+	 * Called when payment flow begins, before payment creation.
+	 *
+	 * Event detail includes handlers to control the payment flow:
+	 * - abortPaymentCreation: Call to abort the payment
+	 * - continuePaymentCreation: Call to continue (optionally with idempotencyKey)
+	 *
+	 * @returns true if an event listener called a handler, false otherwise
 	 */
-	dispatchPaymentStart(): void;
+	dispatchPaymentStart(paymentMethodType: PaymentMethodType, handler: PrepareHandler): boolean;
 	/**
 	 * Dispatch payment success event with minimal payment summary.
 	 * Called when payment completes successfully.
@@ -2573,9 +2519,10 @@ declare class PrimerEventsController implements ReactiveController {
 	 * Dispatch vault methods update event.
 	 * Called when vaulted payment methods are loaded or updated.
 	 *
-	 * @param vaultedPayments - Wrapper containing filtered vaulted payment methods
+	 * @param vaultedPayments - Array of filtered vaulted payment method summaries
+	 * @param cvvRecapture - Whether CVV recapture is required for vaulted payments
 	 */
-	dispatchVaultMethodsUpdate(vaultedPayments: InitializedVaultedPayments): void;
+	dispatchVaultMethodsUpdate(vaultedPayments: VaultedPaymentMethodSummary[], cvvRecapture: boolean): void;
 	/**
 	 * Dispatch vault selection change event.
 	 * Called when a vaulted payment method is selected or deselected.
@@ -2662,7 +2609,7 @@ declare class SDKContextController implements ReactiveController {
 	 * Updates the payment methods context.
 	 * @param value The new payment methods data.
 	 */
-	setPaymentMethods(value: InitializedPayments): void;
+	setPaymentMethods(value: InitializedPaymentMethod[]): void;
 	/**
 	 * Updates the payment manager context.
 	 * @param value The new payment manager mapping.
@@ -2766,6 +2713,7 @@ declare class CardNetworkController implements ReactiveController {
 	 * @param event - The card network change event
 	 */
 	processCardNetworkChangeEvent(event: CardNetworkChangeEvent): void;
+	processBinDataAvailableEvent(event: BinDataAvailableEvent): void;
 }
 declare class StyleProcessingController implements ReactiveController {
 	host: ReactiveControllerHost & LitElement;
@@ -3603,7 +3551,7 @@ declare global {
 		"primer-klarna": PrimerKlarnaComponent;
 	}
 }
-export type PaymentMethodsContextType = InitializedPayments | null;
+export type PaymentMethodsContextType = InitializedPaymentMethod[] | null;
 /**
  * Google Pay component with shadow root rendering for full-width button support.
  *