@primer-io/primer-js 0.8.2 → 0.10.0

package/dist/primer-loader.d.ts

@@ -190,6 +190,8 @@ declare const PaymentMethodType: {
 	readonly ATOME: "ATOME";
 	readonly DLOCAL_PIX: "DLOCAL_PIX";
 	readonly ALMA: "ALMA";
+	readonly ADYEN_CASHAPP: "ADYEN_CASHAPP";
+	readonly ADYEN_AFFIRM: "ADYEN_AFFIRM";
 };
 export type PaymentMethodType = (typeof PaymentMethodType)[keyof typeof PaymentMethodType];
 declare const PaymentMethodType$1 = {
@@ -1418,6 +1420,44 @@ export interface PrimerCheckoutOptions {
 		 * @default false
 		 */
 		showEmptyState?: boolean;
+		/**
+		 * Whether to hide vault UI components while keeping vault functionality active.
+		 *
+		 * When true:
+		 * - Vault UI components do not render
+		 * - Vault functionality remains active (onVaultedMethodsUpdate callback, APIs)
+		 * - Card form and other payment methods display normally
+		 * - Enables headless vault implementation patterns
+		 *
+		 * When false or undefined:
+		 * - Vault UI components render normally (default behavior)
+		 *
+		 * Use this for custom vault UI implementations where you want to:
+		 * - Build your own vault item display using onVaultedMethodsUpdate callback
+		 * - Create custom CVV inputs programmatically
+		 * - Start vaulted payments through PrimerJS API
+		 *
+		 * @default false
+		 * @example
+		 * ```typescript
+		 * // Headless vault mode - no vault UI
+		 * {
+		 *   vault: {
+		 *     enabled: true,
+		 *     headless: true
+		 *   }
+		 * }
+		 *
+		 * // Standard vault mode - shows vault UI
+		 * {
+		 *   vault: {
+		 *     enabled: true,
+		 *     headless: false
+		 *   }
+		 * }
+		 * ```
+		 */
+		headless?: boolean;
 	};
 	/**
 	 * Configuration options for Stripe ACH payment method.
@@ -1724,6 +1764,149 @@ export declare class InitializedVaultedPayments {
 	 */
 	size(): number;
 }
+export type ReducerCallbacks<State, _Action extends {
+	type: string;
+}> = {
+	[K in keyof State]?: State[K] extends (...args: unknown[]) => unknown ? State[K] : never;
+};
+export type TypedReducer<State, Action extends {
+	type: string;
+}, Callbacks> = (state: State, action: Action, callbacks: Callbacks) => State;
+declare abstract class ReactiveStateController<Host extends ReactiveControllerHost, State, Action extends {
+	type: string;
+}, Callbacks = ReducerCallbacks<State, Action> | null> implements ReactiveController {
+	protected host: Host;
+	protected stateHandler: (state: State) => void;
+	private _dispatcher;
+	constructor(host: Host, initialState: State, reducer: TypedReducer<State, Action, Callbacks>, initialCallbacks: Callbacks, stateHandler?: (state: State) => void);
+	get currentState(): Readonly<State>;
+	protected dispatch(action: Action): void;
+	protected setCallbacks(callbacks: Partial<Callbacks>): void;
+	hostConnected(): void;
+	hostDisconnected(): void;
+}
+declare class CompositeStateController<Host extends ReactiveControllerHost> implements ReactiveController {
+	protected host: Host;
+	private _controllers;
+	constructor(host: Host);
+	addController<State, Action extends {
+		type: string;
+	}, Callbacks = ReducerCallbacks<State, Action> | null>(controller: ReactiveStateController<Host, State, Action, Callbacks>): void;
+	hostConnected(): void;
+	hostDisconnected(): void;
+}
+/**
+ * Options for initializing the Vault Manager
+ */
+export interface VaultManagerInitOptions {
+	vaultEnabled?: boolean;
+	captureVaultedCardCvv?: boolean;
+	showEmptyState?: boolean;
+	headless?: boolean;
+}
+/**
+ * Core state interface for vault manager
+ * Contains properties related to vault functionality that don't change frequently
+ */
+export interface VaultManagerState {
+	enabled: boolean;
+	isLoading: boolean;
+	isUpdating: boolean;
+	vaultedPaymentMethods: VaultedPaymentMethod[];
+	cvvRecapture: boolean;
+	showEmptyState: boolean;
+	headless: boolean;
+	createCvvInput: ((options: CardSecurityCodeInputOptions) => Promise<CvvInput | null>) | null;
+	deleteVaultedPaymentMethod: (paymentMethodId: string) => Promise<void>;
+	startVaultedPaymentFlow: (options?: {
+		cvv?: string;
+	}) => Promise<void>;
+}
+/**
+ * CVV-specific state interface
+ * Contains properties specifically related to CVV input functionality
+ */
+export interface VaultManagerItemState {
+	formIsDirty: boolean;
+	cvvInput: CvvInput | null;
+	setCvvInput: (metadata: CvvInput | null) => void;
+	selectedVaultedPaymentMethod: VaultedPaymentMethod | null;
+	setSelectedVaultedPaymentMethod: (paymentMethod: VaultedPaymentMethod | null) => void;
+}
+declare class VaultManagerController extends CompositeStateController<PrimerCheckoutType> {
+	private coreController;
+	private itemController;
+	private _vaultManager;
+	private _options;
+	private createVaultManagerFn;
+	constructor(host: PrimerCheckoutType);
+	/**
+	 * Initialize the vault manager with a factory function and options
+	 * @param createVaultManagerFn - Bound function to create vault manager when needed
+	 * @param options - Vault configuration options
+	 */
+	initializeVaultManager(createVaultManagerFn: PrimerHeadlessCheckout["createVaultManager"] | null, options?: VaultManagerInitOptions): void;
+	get vaultManager(): HeadlessVaultManager | null;
+	set vaultManager(vaultManager: HeadlessVaultManager | null);
+	get options(): VaultManagerInitOptions | null;
+	set options(options: VaultManagerInitOptions | null);
+	get vaultManagerState(): Readonly<VaultManagerState>;
+	get vaultItemState(): Readonly<VaultManagerItemState>;
+	/**
+	 * Lifecycle method called when the host disconnects
+	 */
+	hostDisconnected(): void;
+	/**
+	 * Transform raw vault data into filtered, event-ready format.
+	 * Applies PII filtering to all vaulted payment methods.
+	 *
+	 * @param vaultedPaymentMethods - Raw vaulted payment methods from API
+	 * @returns InitializedVaultedPayments wrapper with filtered data
+	 */
+	private createVaultedPaymentsWrapper;
+	/**
+	 * Update vaulted payment methods and dispatch events/callbacks.
+	 * This method:
+	 * 1. Updates internal state via core controller
+	 * 2. Creates filtered wrapper for external APIs
+	 * 3. Dispatches event to listeners
+	 * 4. Invokes callback if defined
+	 *
+	 * @param methods - Raw vaulted payment methods from API
+	 */
+	private updatePaymentMethodsWithEvents;
+	/**
+	 * Fetch vaulted payment methods from the server
+	 */
+	fetchVaultedPaymentMethods(initialLoad?: boolean): Promise<VaultedPaymentMethod[]>;
+	createCvvInput: (options: CardSecurityCodeInputOptions) => Promise<CvvInput | null>;
+	/**
+	 * Delete a vaulted payment method by ID
+	 */
+	deleteVaultedPaymentMethod: (paymentMethodId: string) => Promise<void>;
+	/**
+	 * Set the CVV metadata - updates CVV state only
+	 * Moved to the separate CVV context
+	 */
+	setCvvInput: (metadata: CvvInput | null) => void;
+	/**
+	 * Start the vaulted payment flow
+	 * Verifies form state validity before processing
+	 */
+	startVaultedPaymentFlow: () => Promise<void>;
+	/**
+	 * Set the selected vaulted payment method - updates form state only
+	 */
+	setSelectedVaultedPaymentMethod: (paymentMethod: VaultedPaymentMethod | null) => void;
+	/**
+	 * Start vaulted payment flow by payment method ID
+	 * @param paymentMethodId - The ID of the vaulted payment method
+	 * @param options - Optional payment options including CVV token
+	 */
+	startVaultPaymentById: (paymentMethodId: string, options?: {
+		cvv?: string;
+	}) => Promise<void>;
+}
 /**
  * Payment prepare callback data.
  * Includes payment method type for validation or abort control flow.
@@ -1774,6 +1957,8 @@ export interface PaymentFailureData {
 export interface VaultedMethodsUpdateData {
 	/** Wrapper containing filtered vaulted payment methods */
 	vaultedPayments: InitializedVaultedPayments;
+	/** Indicates if CVV recapture is required for vaulted payments */
+	cvvRecapture: boolean;
 	/** Unix timestamp in seconds */
 	timestamp: number;
 }
@@ -1785,6 +1970,7 @@ export declare class PrimerJS {
 	private headlessInstance;
 	private paymentMethods;
 	private paymentManagers;
+	private vaultController;
 	/**
 	 * Called when payment flow begins.
 	 * Use for analytics tracking or UI updates (e.g., disable form).
@@ -1879,10 +2065,11 @@ export declare class PrimerJS {
 	 *
 	 * 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
+	 * @param data - Vault methods update data with filtered payment methods and cvvRecapture flag
 	 *
 	 * @example
 	 * ```typescript
@@ -1914,6 +2101,98 @@ export declare class PrimerJS {
 	 * @internal - This is only used internally by the SDK
 	 */
 	setPaymentManagers(managers: InitializedManagersMap): void;
+	/**
+	 * Internal method to set the vault controller reference.
+	 * Called during vault initialization.
+	 * @internal
+	 */
+	setVaultController(controller: VaultManagerController | null): void;
+	/**
+	 * Creates a CVV input for vaulted payment method CVV recapture.
+	 *
+	 * ⚠️ Requires vault to be initialized. Check vault availability via
+	 * the onVaultedMethodsUpdate callback before calling.
+	 *
+	 * @param options - CVV input configuration
+	 * @returns Promise resolving to CvvInput or null if vault unavailable
+	 *
+	 * @example
+	 * ```typescript
+	 * const method = vaultedPayments.get(selectedId);
+	 * const cvvInput = await primerJS.createCvvInput({
+	 *   cardNetwork: method.paymentInstrumentData.network,
+	 *   container: "#cvv-container",
+	 *   placeholder: "123"
+	 * });
+	 *
+	 * if (cvvInput.metadata.error) {
+	 *   // Handle validation error
+	 * }
+	 * ```
+	 */
+	createCvvInput(options: CardSecurityCodeInputOptions): Promise<CvvInput | null>;
+	/**
+	 * Initiates payment using a vaulted payment method.
+	 *
+	 * Enables headless vault flows where merchants build custom vault UIs.
+	 * Mirrors the legacy SDK's vaultManager.startPaymentFlow().
+	 *
+	 * @param paymentMethodId - The ID of the vaulted payment method
+	 * @param options - Optional payment options
+	 * @param options.cvv - CVV value token (required if cvvRecapture is true)
+	 * @returns Promise that resolves when payment flow starts
+	 * @throws Error if vault not initialized or payment method not found
+	 *
+	 * @example
+	 * ```typescript
+	 * // Complete headless vault flow
+	 * let vaultedMethods;
+	 * let needsCvv = false;
+	 *
+	 * primerJS.onVaultedMethodsUpdate = ({ vaultedPayments, cvvRecapture }) => {
+	 *   vaultedMethods = vaultedPayments.toArray();
+	 *   needsCvv = cvvRecapture;
+	 *
+	 *   // Build custom vault UI
+	 *   vaultedMethods.forEach(method => {
+	 *     displayVaultItem({
+	 *       id: method.id,
+	 *       last4: method.paymentInstrumentData?.last4Digits,
+	 *       network: method.paymentInstrumentData?.network
+	 *     });
+	 *   });
+	 * };
+	 *
+	 * // When user submits payment
+	 * async function handlePayment(selectedMethodId) {
+	 *   try {
+	 *     if (needsCvv) {
+	 *       const method = vaultedMethods.find(m => m.id === selectedMethodId);
+	 *       const cvvInput = await primerJS.createCvvInput({
+	 *         cardNetwork: method.paymentInstrumentData.network,
+	 *         container: "#cvv-container"
+	 *       });
+	 *
+	 *       if (cvvInput.metadata.error) {
+	 *         showError("Invalid CVV");
+	 *         return;
+	 *       }
+	 *
+	 *       await primerJS.startVaultPayment(selectedMethodId, {
+	 *         cvv: cvvInput.valueToken
+	 *       });
+	 *     } else {
+	 *       await primerJS.startVaultPayment(selectedMethodId);
+	 *     }
+	 *   } catch (error) {
+	 *     console.error("Payment failed:", error);
+	 *   }
+	 * }
+	 * ```
+	 */
+	startVaultPayment(paymentMethodId: string, options?: {
+		cvv?: string;
+	}): Promise<void>;
 	/**
 	 * Refetches a new client session from merchant backend.
 	 */
@@ -1941,7 +2220,7 @@ export declare class PrimerJS {
 	 * Internal method to handle the onVaultedMethodsUpdate callback
 	 * @internal - This is only used internally by the SDK
 	 */
-	handleVaultedMethodsUpdate(vaultedPayments: InitializedVaultedPayments): void;
+	handleVaultedMethodsUpdate(vaultedPayments: InitializedVaultedPayments, cvvRecapture: boolean): void;
 	/**
 	 * Sets the cardholder name value in the card payment form.
 	 *
@@ -2134,139 +2413,6 @@ export type KlarnaCategoriesContextType = {
 	categories: KlarnaPaymentMethodCategory[];
 	isLoading: boolean;
 };
-export type ReducerCallbacks<State, _Action extends {
-	type: string;
-}> = {
-	[K in keyof State]?: State[K] extends (...args: unknown[]) => unknown ? State[K] : never;
-};
-export type TypedReducer<State, Action extends {
-	type: string;
-}, Callbacks> = (state: State, action: Action, callbacks: Callbacks) => State;
-declare abstract class ReactiveStateController<Host extends ReactiveControllerHost, State, Action extends {
-	type: string;
-}, Callbacks = ReducerCallbacks<State, Action> | null> implements ReactiveController {
-	protected host: Host;
-	protected stateHandler: (state: State) => void;
-	private _dispatcher;
-	constructor(host: Host, initialState: State, reducer: TypedReducer<State, Action, Callbacks>, initialCallbacks: Callbacks, stateHandler?: (state: State) => void);
-	get currentState(): Readonly<State>;
-	protected dispatch(action: Action): void;
-	protected setCallbacks(callbacks: Partial<Callbacks>): void;
-	hostConnected(): void;
-	hostDisconnected(): void;
-}
-declare class CompositeStateController<Host extends ReactiveControllerHost> implements ReactiveController {
-	protected host: Host;
-	private _controllers;
-	constructor(host: Host);
-	addController<State, Action extends {
-		type: string;
-	}, Callbacks = ReducerCallbacks<State, Action> | null>(controller: ReactiveStateController<Host, State, Action, Callbacks>): void;
-	hostConnected(): void;
-	hostDisconnected(): void;
-}
-/**
- * Options for initializing the Vault Manager
- */
-export interface VaultManagerInitOptions {
-	vaultEnabled?: boolean;
-	captureVaultedCardCvv?: boolean;
-	showEmptyState?: boolean;
-}
-/**
- * Core state interface for vault manager
- * Contains properties related to vault functionality that don't change frequently
- */
-export interface VaultManagerState {
-	enabled: boolean;
-	isLoading: boolean;
-	isUpdating: boolean;
-	vaultedPaymentMethods: VaultedPaymentMethod[];
-	cvvRecapture: boolean;
-	showEmptyState: boolean;
-	createCvvInput: ((options: CardSecurityCodeInputOptions) => Promise<CvvInput | null>) | null;
-	deleteVaultedPaymentMethod: (paymentMethodId: string) => Promise<void>;
-	startVaultedPaymentFlow: (options?: {
-		cvv?: string;
-	}) => Promise<void>;
-}
-/**
- * CVV-specific state interface
- * Contains properties specifically related to CVV input functionality
- */
-export interface VaultManagerItemState {
-	formIsDirty: boolean;
-	cvvInput: CvvInput | null;
-	setCvvInput: (metadata: CvvInput | null) => void;
-	selectedVaultedPaymentMethod: VaultedPaymentMethod | null;
-	setSelectedVaultedPaymentMethod: (paymentMethod: VaultedPaymentMethod | null) => void;
-}
-declare class VaultManagerController extends CompositeStateController<PrimerCheckoutType> {
-	private coreController;
-	private itemController;
-	private _vaultManager;
-	private _options;
-	private createVaultManagerFn;
-	constructor(host: PrimerCheckoutType);
-	/**
-	 * Initialize the vault manager with a factory function and options
-	 * @param createVaultManagerFn - Bound function to create vault manager when needed
-	 * @param options - Vault configuration options
-	 */
-	initializeVaultManager(createVaultManagerFn: PrimerHeadlessCheckout["createVaultManager"] | null, options?: VaultManagerInitOptions): void;
-	get vaultManager(): HeadlessVaultManager | null;
-	set vaultManager(vaultManager: HeadlessVaultManager | null);
-	get options(): VaultManagerInitOptions | null;
-	set options(options: VaultManagerInitOptions | null);
-	get vaultManagerState(): Readonly<VaultManagerState>;
-	get vaultItemState(): Readonly<VaultManagerItemState>;
-	/**
-	 * Lifecycle method called when the host disconnects
-	 */
-	hostDisconnected(): void;
-	/**
-	 * Transform raw vault data into filtered, event-ready format.
-	 * Applies PII filtering to all vaulted payment methods.
-	 *
-	 * @param vaultedPaymentMethods - Raw vaulted payment methods from API
-	 * @returns InitializedVaultedPayments wrapper with filtered data
-	 */
-	private createVaultedPaymentsWrapper;
-	/**
-	 * Update vaulted payment methods and dispatch events/callbacks.
-	 * This method:
-	 * 1. Updates internal state via core controller
-	 * 2. Creates filtered wrapper for external APIs
-	 * 3. Dispatches event to listeners
-	 * 4. Invokes callback if defined
-	 *
-	 * @param methods - Raw vaulted payment methods from API
-	 */
-	private updatePaymentMethodsWithEvents;
-	/**
-	 * Fetch vaulted payment methods from the server
-	 */
-	fetchVaultedPaymentMethods(initialLoad?: boolean): Promise<VaultedPaymentMethod[]>;
-	createCvvInput: (options: CardSecurityCodeInputOptions) => Promise<CvvInput | null>;
-	/**
-	 * Delete a vaulted payment method by ID
-	 */
-	deleteVaultedPaymentMethod: (paymentMethodId: string) => Promise<void>;
-	/**
-	 * Set the CVV metadata - updates CVV state only
-	 * Moved to the separate CVV context
-	 */
-	setCvvInput: (metadata: CvvInput | null) => void;
-	/**
-	 * Start the vaulted payment flow
-	 * Verifies form state validity before processing
-	 */
-	startVaultedPaymentFlow: () => Promise<void>;
-	/**
-	 * Set the selected vaulted payment method - updates form state only
-	 */
-	setSelectedVaultedPaymentMethod: (paymentMethod: VaultedPaymentMethod | null) => void;
-}
 /**
  * Context for core vault manager functionality
  * Contains properties that don't change frequently and relate to vault functionality