@primer-io/primer-js 0.9.0 → 0.11.0

package/dist/jsx/index.d.ts

@@ -66,8 +66,6 @@ export type PrimerCheckoutComponentProps = {
   /**  */
   "client-token"?: string;
   /**  */
-  options?: PrimerCheckoutOptions;
-  /**  */
   "loader-disabled"?: boolean;
   /** Whether the component has completed initialization and loading
 This is used to control the CSS-only loader visibility */
@@ -77,6 +75,8 @@ This is used to control the CSS-only loader visibility */
   /**  */
   primerJS?: PrimerJS | undefined;
   /**  */
+  options?: PrimerCheckoutOptions;
+  /**  */
   defaultSlot?: HTMLSlotElement;
   /**  */
   locale?: LocaleCode | undefined;
@@ -657,6 +657,8 @@ export type VaultDeleteConfirmationComponentProps = {
   vaultManager?: VaultManagerContextType;
 };
 
+export type VaultEmptyStateComponentProps = {};
+
 export type VaultErrorMessageComponentProps = {
   /** The error message to display */
   errorMessage?: string;
@@ -674,8 +676,6 @@ export type VaultErrorMessageComponentProps = {
   ) => void;
 };
 
-export type VaultEmptyStateComponentProps = {};
-
 export type VaultManagerHeaderComponentProps = {
   /** Whether we're in edit mode */
   isEditMode?: boolean;
@@ -1236,18 +1236,18 @@ export type CustomElements = {
   "primer-vault-delete-confirmation": Partial<VaultDeleteConfirmationComponentProps & BaseProps & BaseEvents>;
 
   /**
-   * VaultErrorMessageComponent - displays error messages with improved visuals
+   * VaultEmptyStateComponent - displays when no payment methods are available
    * ---
    *
    */
-  "primer-vault-error-message": Partial<VaultErrorMessageComponentProps & BaseProps & BaseEvents>;
+  "primer-vault-empty-state": Partial<VaultEmptyStateComponentProps & BaseProps & BaseEvents>;
 
   /**
-   * VaultEmptyStateComponent - displays when no payment methods are available
+   * VaultErrorMessageComponent - displays error messages with improved visuals
    * ---
    *
    */
-  "primer-vault-empty-state": Partial<VaultEmptyStateComponentProps & BaseProps & BaseEvents>;
+  "primer-vault-error-message": Partial<VaultErrorMessageComponentProps & BaseProps & BaseEvents>;
 
   /**
    * VaultManagerHeaderComponent - displays the header for the vault manager

package/dist/primer-loader.d.ts

@@ -376,36 +376,106 @@ export interface PaymentSummary {
 	};
 }
 /**
- * Minimal vaulted payment method summary with reduced PII exposure.
- * Used for vault events and callbacks to expose vaulted payment methods safely.
+ * Base interface for common vaulted payment method fields.
+ * All payment-method-specific interfaces extend this base.
  */
-export interface VaultedPaymentMethodSummary {
+export interface BaseVaultedPaymentMethodSummary {
 	/** Payment instrument ID */
 	id: string;
 	/** Analytics tracking ID */
 	analyticsId: string;
 	/** Payment method type (e.g., "PAYMENT_CARD", "PAYPAL") */
 	paymentMethodType: PaymentMethodType$1;
-	/** Payment instrument type (e.g., "CARD", "PAYPAL_BILLING_AGREEMENT") */
-	paymentInstrumentType: PaymentInstrumentType$1;
-	/** Payment instrument data with whitelisted safe fields only */
+	/** Optional user-provided description for the payment method */
+	userDescription?: string;
+}
+/**
+ * Vaulted payment card summary with card-specific fields.
+ */
+export interface CardVaultedPaymentMethodSummary extends BaseVaultedPaymentMethodSummary {
+	/** Discriminant for card payment instruments */
+	paymentInstrumentType: "PAYMENT_CARD";
+	/** Card-specific payment instrument data */
 	paymentInstrumentData?: {
-		/** Last 4 digits of card (cards only) */
+		/** Last 4 digits of card */
 		last4Digits?: string;
-		/** Card network (e.g., "VISA", "MASTERCARD") - cards only */
+		/** Card network (e.g., "VISA", "MASTERCARD") */
 		network?: string;
-		/** Last 4 digits of account number (ACH only) */
+		/** Cardholder name */
+		cardholderName?: string;
+		/** Expiration month (1-12) */
+		expirationMonth?: string;
+		/** Expiration year (e.g., "2025") */
+		expirationYear?: string;
+	};
+}
+/**
+ * Vaulted PayPal billing agreement summary with PayPal-specific fields.
+ */
+export interface PayPalVaultedPaymentMethodSummary extends BaseVaultedPaymentMethodSummary {
+	/** Discriminant for PayPal billing agreement instruments */
+	paymentInstrumentType: "PAYPAL_BILLING_AGREEMENT";
+	/** PayPal-specific payment instrument data */
+	paymentInstrumentData?: {
+		/** External PayPal payer ID */
+		externalPayerId?: string;
+		/** PayPal account email */
+		email?: string;
+		/** First name */
+		firstName?: string;
+		/** Last name */
+		lastName?: string;
+	};
+}
+/**
+ * Vaulted Klarna customer token summary with Klarna-specific fields.
+ */
+export interface KlarnaVaultedPaymentMethodSummary extends BaseVaultedPaymentMethodSummary {
+	/** Discriminant for Klarna customer token instruments */
+	paymentInstrumentType: "KLARNA_CUSTOMER_TOKEN";
+	/** Klarna-specific payment instrument data */
+	paymentInstrumentData?: {
+		/** Klarna account email */
+		email?: string;
+		/** First name */
+		firstName?: string;
+		/** Last name */
+		lastName?: string;
+		/** Phone number */
+		phoneNumber?: string;
+	};
+}
+/**
+ * Vaulted ACH (Automated Clearing House) summary with ACH-specific fields.
+ */
+export interface ACHVaultedPaymentMethodSummary extends BaseVaultedPaymentMethodSummary {
+	/** Discriminant for ACH instruments */
+	paymentInstrumentType: "AUTOMATED_CLEARING_HOUSE";
+	/** ACH-specific payment instrument data */
+	paymentInstrumentData?: {
+		/** Last 4 digits of account number */
 		accountNumberLastFourDigits?: string;
-		/** Bank name (ACH only) */
+		/** Bank name */
 		bankName?: string;
-		/** Account type (ACH only) */
+		/** Account type (e.g., "CHECKING", "SAVINGS") */
 		accountType?: string;
-		/** Email for wallet payment methods */
-		email?: string;
 	};
-	/** Optional user-provided description for the payment method */
-	userDescription?: string;
 }
+/**
+ * Generic vaulted payment method summary for payment instruments
+ * not explicitly modeled with their own interface.
+ */
+export interface GenericVaultedPaymentMethodSummary extends BaseVaultedPaymentMethodSummary {
+	/** Discriminant for all other payment instrument types */
+	paymentInstrumentType: Exclude<PaymentInstrumentType$1, "PAYMENT_CARD" | "PAYPAL_BILLING_AGREEMENT" | "KLARNA_CUSTOMER_TOKEN" | "AUTOMATED_CLEARING_HOUSE">;
+	/** Generic payment instrument data for unknown/other payment methods */
+	paymentInstrumentData?: Record<string, unknown>;
+}
+/**
+ * Discriminated union of all vaulted payment method summaries.
+ * Use the paymentInstrumentType field to narrow to specific types.
+ */
+export type VaultedPaymentMethodSummary = CardVaultedPaymentMethodSummary | PayPalVaultedPaymentMethodSummary | KlarnaVaultedPaymentMethodSummary | ACHVaultedPaymentMethodSummary | GenericVaultedPaymentMethodSummary;
 export type APIVersionOption = "legacy" | "2.4";
 declare enum HeadlessManagerType {
 	CARD = "CARD",
@@ -1962,6 +2032,38 @@ export interface VaultedMethodsUpdateData {
 	/** Unix timestamp in seconds */
 	timestamp: number;
 }
+/**
+ * VaultAPI provides programmatic access to vaulted payment method operations.
+ * Enables merchants to build custom vault UIs and manage vaulted payment methods.
+ */
+export interface VaultAPI {
+	/**
+	 * Creates a CVV input for vaulted payment method CVV recapture.
+	 *
+	 * @param options - CVV input configuration options
+	 * @returns Promise resolving to CvvInput instance, or null if vault unavailable
+	 */
+	createCvvInput(options: CardSecurityCodeInputOptions): Promise<CvvInput | null>;
+	/**
+	 * Starts payment using a vaulted payment method.
+	 *
+	 * @param paymentMethodId - The unique identifier of the vaulted payment method
+	 * @param options - Optional payment configuration
+	 * @returns Promise that resolves when payment flow initiates
+	 * @throws Error if vault not initialized or payment method not found
+	 */
+	startPayment(paymentMethodId: string, options?: {
+		cvv?: string;
+	}): Promise<void>;
+	/**
+	 * Deletes a vaulted payment method from the vault.
+	 *
+	 * @param paymentMethodId - The unique identifier of the payment method to delete
+	 * @returns Promise that resolves when deletion completes
+	 * @throws Error if vault not initialized
+	 */
+	delete(paymentMethodId: string): Promise<void>;
+}
 /**
  * PrimerJS is a wrapper class that provides a stable API for interfacing with the Primer SDK
  * while hiding direct access to the legacy headless instance.
@@ -1971,6 +2073,20 @@ export declare class PrimerJS {
 	private paymentMethods;
 	private paymentManagers;
 	private vaultController;
+	/**
+	 * Vault namespace providing programmatic access to vaulted payment method operations.
+	 * Use for building custom vault UIs with headless flows.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Start payment with vaulted method
+	 * await primerJS.vault.startPayment(methodId);
+	 *
+	 * // Delete a vaulted method
+	 * await primerJS.vault.delete(methodId);
+	 * ```
+	 */
+	readonly vault: VaultAPI;
 	/**
 	 * Called when payment flow begins.
 	 * Use for analytics tracking or UI updates (e.g., disable form).
@@ -2107,88 +2223,41 @@ export declare class PrimerJS {
 	 * @internal
 	 */
 	setVaultController(controller: VaultManagerController | null): void;
+	/**
+	 * Internal implementation of createCvvInput.
+	 * @internal
+	 */
+	private createCvvInputInternal;
+	/**
+	 * Internal implementation of startVaultPayment.
+	 * @internal
+	 */
+	private startVaultPaymentInternal;
+	/**
+	 * Deletes a vaulted payment method.
+	 * @internal
+	 */
+	private deleteVaultPaymentMethod;
 	/**
 	 * Creates a CVV input for vaulted payment method CVV recapture.
 	 *
-	 * ⚠️ Requires vault to be initialized. Check vault availability via
-	 * the onVaultedMethodsUpdate callback before calling.
+	 * @deprecated Use primerJS.vault.createCvvInput() instead.
+	 * This method will be removed in a future major version.
 	 *
 	 * @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().
+	 * @deprecated Use primerJS.vault.startPayment() instead.
+	 * This method will be removed in a future major version.
 	 *
 	 * @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;