@primer-io/primer-js 0.15.0 → 1.0.0

package/dist/jsx/index.d.ts

@@ -125,18 +125,6 @@ export type PrimerCheckoutStateComponentProps = {
   description?: string | undefined;
 };
 
-export type DialogComponentProps = {
-  /**  */
-  size?: "flex" | "large";
-  /**  */
-  showCloseButton?: boolean;
-
-  /**  */
-  "onprimer:dialog-open"?: (e: CustomEvent<CustomEvent>) => void;
-  /**  */
-  "onprimer:dialog-close"?: (e: CustomEvent<CustomEvent>) => void;
-};
-
 export type CollapsableComponentProps = {
   /** The header text for the collapsable */
   header?: string;
@@ -156,6 +144,18 @@ export type CollapsableComponentProps = {
   "onexpanded-changed"?: (e: CustomEvent<CustomEvent>) => void;
 };
 
+export type DialogComponentProps = {
+  /**  */
+  size?: "flex" | "large";
+  /**  */
+  showCloseButton?: boolean;
+
+  /**  */
+  "onprimer:dialog-open"?: (e: CustomEvent<CustomEvent>) => void;
+  /**  */
+  "onprimer:dialog-close"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
 export type ErrorMessageComponentProps = {
   /** The error message text to display */
   message?: string;
@@ -564,7 +564,7 @@ Falls back to localized default if not explicitly set. */
   cardFormContext?: CardFormContext | null;
 };
 
-export type InputCvvComponentProps = {
+export type InputCardNumberComponentProps = {
   /**  */
   computedStyles?: CSSStyleDeclaration | null;
   /** The input label text.
@@ -581,7 +581,7 @@ Falls back to localized default if not explicitly set. */
   cardFormContext?: CardFormContext | null;
 };
 
-export type InputCardNumberComponentProps = {
+export type InputCvvComponentProps = {
   /**  */
   computedStyles?: CSSStyleDeclaration | null;
   /** The input label text.
@@ -625,6 +625,11 @@ export type PayPalComponentProps = {
   disabled?: boolean;
 };
 
+export type PaymentMethodContentComponentProps = {
+  /** The asset configuration containing icon and display data */
+  assetConfig?: AssetConfig | null;
+};
+
 export type VaultCvvInputComponentProps = {
   /**  */
   computedStyles?: CSSStyleDeclaration | null;
@@ -637,11 +642,6 @@ Separated to minimize re-renders on frequent CVV input changes */
   vaultManagerCvvContext?: VaultItemContextType;
 };
 
-export type PaymentMethodContentComponentProps = {
-  /** The asset configuration containing icon and display data */
-  assetConfig?: AssetConfig | null;
-};
-
 export type VaultDeleteConfirmationComponentProps = {
   /** Whether a delete operation is in progress */
   isDeleting?: boolean;
@@ -779,33 +779,33 @@ export type CustomElements = {
   "primer-checkout-state": Partial<PrimerCheckoutStateComponentProps & BaseProps & BaseEvents>;
 
   /**
-   *
+   * A collapsable component that smoothly expands and collapses content.
+   * Uses CSS Grid for smooth animation and incorporates the primary button.
    * ---
    *
    *
    * ### **Events:**
-   *  - **primer:dialog-open**
-   * - **primer:dialog-close**
+   *  - **expanded-changed**
    *
    * ### **Methods:**
-   *  - **startExitAnimation(): _void_** - Public method to trigger exit animation programmatically
+   *  - **expand(): _void_** - Expand the collapsable programmatically
+   * - **collapse(): _void_** - Collapse the collapsable programmatically
    */
-  "primer-dialog": Partial<DialogComponentProps & BaseProps & BaseEvents>;
+  "primer-collapsable": Partial<CollapsableComponentProps & BaseProps & BaseEvents>;
 
   /**
-   * A collapsable component that smoothly expands and collapses content.
-   * Uses CSS Grid for smooth animation and incorporates the primary button.
+   *
    * ---
    *
    *
    * ### **Events:**
-   *  - **expanded-changed**
+   *  - **primer:dialog-open**
+   * - **primer:dialog-close**
    *
    * ### **Methods:**
-   *  - **expand(): _void_** - Expand the collapsable programmatically
-   * - **collapse(): _void_** - Collapse the collapsable programmatically
+   *  - **startExitAnimation(): _void_** - Public method to trigger exit animation programmatically
    */
-  "primer-collapsable": Partial<CollapsableComponentProps & BaseProps & BaseEvents>;
+  "primer-dialog": Partial<DialogComponentProps & BaseProps & BaseEvents>;
 
   /**
    * A reusable atomic error message component that displays error information
@@ -1148,34 +1148,34 @@ export type CustomElements = {
   "primer-input-card-holder-name": Partial<InputCardHolderNameComponentProps & BaseProps & BaseEvents>;
 
   /**
-   *
+   * Card number input component with dynamic card network detection and selection
    * ---
    *
    *
    * ### **Methods:**
    *
+   *
    * - **getError(): _string|null_** - Get the error code from the hosted input controller when the input is submitted or touched
    *
    * Can be used instead of the error returned by the `validate()` method since internally `primer-sdk-web`
    * uses the same logic to compute the error code
-   *
    */
-  "primer-input-cvv": Partial<InputCvvComponentProps & BaseProps & BaseEvents>;
+  "primer-input-card-number": Partial<InputCardNumberComponentProps & BaseProps & BaseEvents>;
 
   /**
-   * Card number input component with dynamic card network detection and selection
+   *
    * ---
    *
    *
    * ### **Methods:**
    *
-   *
    * - **getError(): _string|null_** - Get the error code from the hosted input controller when the input is submitted or touched
    *
    * Can be used instead of the error returned by the `validate()` method since internally `primer-sdk-web`
    * uses the same logic to compute the error code
+   *
    */
-  "primer-input-card-number": Partial<InputCardNumberComponentProps & BaseProps & BaseEvents>;
+  "primer-input-cvv": Partial<InputCvvComponentProps & BaseProps & BaseEvents>;
 
   /**
    * Apple Pay component with standard button container rendering.
@@ -1216,6 +1216,15 @@ export type CustomElements = {
    */
   "primer-paypal": Partial<PayPalComponentProps & BaseProps & BaseEvents>;
 
+  /**
+   * PaymentMethodContentComponent - renders payment method information with icon and details
+   * This component encapsulates the display logic and styles for payment method content
+   * so it can be reused across different containers without style conflicts
+   * ---
+   *
+   */
+  "primer-payment-method-content": Partial<PaymentMethodContentComponentProps & BaseProps & BaseEvents>;
+
   /**
    * CVV Input component for vault payment methods
    * Renders a secure iframe for CVV input when required by the selected payment method
@@ -1228,15 +1237,6 @@ export type CustomElements = {
    */
   "primer-vault-cvv-input": Partial<VaultCvvInputComponentProps & BaseProps & BaseEvents>;
 
-  /**
-   * PaymentMethodContentComponent - renders payment method information with icon and details
-   * This component encapsulates the display logic and styles for payment method content
-   * so it can be reused across different containers without style conflicts
-   * ---
-   *
-   */
-  "primer-payment-method-content": Partial<PaymentMethodContentComponentProps & BaseProps & BaseEvents>;
-
   /**
    * VaultDeleteConfirmationComponent - displays confirmation UI for deleting a payment method
    * ---

package/dist/primer-loader.d.ts

@@ -1927,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;
 }> = {
@@ -2090,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:
@@ -2186,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 */
@@ -2249,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.
-	 *
-	 * @param data - Payment method information
-	 * @param handler - Control flow handler (continue or abort)
+	 * @deprecated Use the `primer:payment-start` event instead.
 	 *
-	 * @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',
@@ -2302,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
@@ -2332,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,
@@ -2363,7 +2272,7 @@ export declare class PrimerJS {
 	 *       network: method.paymentInstrumentData?.network,
 	 *     });
 	 *   });
-	 * };
+	 * });
 	 * ```
 	 */
 	onVaultedMethodsUpdate?: (data: VaultedMethodsUpdateData) => void;
@@ -2372,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
@@ -2436,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.
 	 *
@@ -2503,7 +2400,7 @@ 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<{
@@ -2513,13 +2410,22 @@ export interface PrimerEvents {
 	"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;
 	}>;
@@ -2530,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;
 	}>;
@@ -2559,7 +2470,7 @@ 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;
@@ -2567,6 +2478,9 @@ declare class PrimerEventsController implements ReactiveController {
 	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
@@ -2577,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.
@@ -2599,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.
@@ -2688,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.
@@ -3630,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.
  *