@primer-io/primer-js 1.4.3 → 1.5.0

package/dist/primer-loader.d.ts

@@ -440,6 +440,41 @@ export interface GooglePayClientOptions {
 	 */
 	buttonBorderType?: GooglePayButtonBorderType;
 }
+export interface ThreeDSAuthenticationData {
+	responseCode: "AUTH_SUCCESS" | "AUTH_FAILED" | "SKIPPED" | "CHALLENGE";
+	reasonCode?: string;
+	reasonText?: string;
+	protocolVersion: string;
+	challengeIssued: boolean;
+}
+export interface IPaymentMethodToken<T, U extends PaymentInstrumentType$1 = PaymentInstrumentType$1> {
+	token: string;
+	analyticsId: string;
+	tokenType: "SINGLE_USE" | "MULTI_USE";
+	paymentInstrumentData: T;
+	paymentInstrumentType: U;
+	threeDSecureAuthentication: ThreeDSAuthenticationData | null;
+	vaultData: {
+		customerId: string;
+	} | null;
+}
+export type PaymentCardToken = IPaymentMethodToken<{
+	last4Digits: string;
+	cardholderName: string;
+	network: string;
+}, typeof PaymentInstrumentType$1.CARD>;
+export interface UnmanagedPaymentToken {
+	token: string;
+	analyticsId: string;
+	tokenType: "SINGLE_USE" | "MULTI_USE";
+	paymentInstrumentType: string;
+	paymentInstrumentData: Record<string, unknown>;
+	vaultData: {
+		customerId: string;
+	} | null;
+	threeDSecureAuthentication: null;
+}
+export type PaymentMethodToken = PaymentCardToken | UnmanagedPaymentToken;
 /**
  * Minimal payment summary with reduced PII exposure.
  * Used in events for public data delivery.
@@ -564,6 +599,18 @@ export interface GenericVaultedPaymentMethodSummary extends BaseVaultedPaymentMe
  * Use the paymentInstrumentType field to narrow to specific types.
  */
 export type VaultedPaymentMethodSummary = CardVaultedPaymentMethodSummary | PayPalVaultedPaymentMethodSummary | KlarnaVaultedPaymentMethodSummary | ACHVaultedPaymentMethodSummary | GenericVaultedPaymentMethodSummary;
+/**
+ * Data surfaced to the merchant when a MANUAL-approval `:pay` creates an
+ * attempt awaiting approval. The merchant sends clientSessionId +
+ * paymentAttemptId to its backend (which calls /approve or /abort), then calls
+ * continueFlow() to resume the SDK.
+ */
+export interface PaymentApprovalRequiredData {
+	clientSessionId: string;
+	paymentAttemptId: string;
+	paymentMethodToken: PaymentMethodToken;
+	continueFlow: () => Promise<void>;
+}
 export type APIVersionOption = "legacy" | "2.4";
 declare enum HeadlessManagerType {
 	CARD = "CARD",
@@ -868,7 +915,7 @@ export interface IVaultedPaymentMethod<B extends BasePaymentInstrumentData = Bas
 	paymentInstrumentData: B;
 	paymentInstrumentType: I;
 	paymentMethodType: T;
-	threeDSecureAuthentication?: ThreeDSAuthenticationData | null;
+	threeDSecureAuthentication?: ThreeDSAuthenticationData$1 | null;
 	vaultData?: VaultData | null;
 	userDescription?: string;
 	isVaulted?: boolean;
@@ -1214,7 +1261,7 @@ export interface CheckoutStyle {
 	processingIndicator?: Record<string, unknown>;
 	focusCheckoutOnInit?: boolean;
 }
-export interface ThreeDSAuthenticationData {
+interface ThreeDSAuthenticationData$1 {
 	responseCode: "AUTH_SUCCESS" | "AUTH_FAILED" | "SKIPPED" | "CHALLENGE";
 	reasonCode?: string;
 	reasonText?: string;
@@ -1316,6 +1363,12 @@ export interface HeadlessUniversalCheckoutOptions {
 		};
 	} & Record<string, unknown>;
 	onAvailablePaymentMethodsLoad: (paymentMethods: PaymentMethodInfo[]) => void;
+	/**
+	 * Fires after each successful `refreshClientSession` when the available
+	 * payment methods changed as a result of the backend re-evaluating
+	 * visibility rules against the updated client session metadata.
+	 */
+	onAvailablePaymentMethodsRefresh?: (paymentMethods: PaymentMethodInfo[]) => void;
 	clientSessionCachingEnabled?: boolean;
 	apiVersion?: APIVersionOption;
 	onCheckoutComplete?: (data: {
@@ -1335,6 +1388,7 @@ export interface HeadlessUniversalCheckoutOptions {
 		abortPaymentCreation: () => void;
 	}) => void;
 	onPaymentCreationStart?: () => void;
+	onPaymentApprovalRequired?: (data: PaymentApprovalRequiredData) => void;
 	onPaymentMethodAction?: (data: "PAYMENT_METHOD_SELECTED" | "PAYMENT_METHOD_UNSELECTED", handler: {
 		payment?: Payment;
 		paymentMethodType: PaymentMethodType | null;
@@ -1346,7 +1400,7 @@ export interface HeadlessUniversalCheckoutOptions {
 	}) => boolean | Promise<boolean>;
 	onTokenizeDidNotStart?: (reason: string) => void;
 	onTokenizeStart?: () => void;
-	onTokenizeSuccess?: (data: PaymentMethodToken, handler: {
+	onTokenizeSuccess?: (data: PaymentMethodToken$1, handler: {
 		handleSuccess(): unknown;
 		handleFailure(errorMessage?: string): unknown;
 		continueWithNewClientToken(clientToken: string): unknown;
@@ -1368,13 +1422,13 @@ export interface HeadlessUniversalCheckoutOptions {
 	}) => void;
 	onResumeError?: (error: PrimerClientError) => void;
 }
-export interface PaymentMethodToken {
+interface PaymentMethodToken$1 {
 	token: string;
 	analyticsId: string;
 	tokenType: "SINGLE_USE" | "MULTI_USE";
 	paymentInstrumentData: BasePaymentInstrumentData;
 	paymentInstrumentType: PaymentInstrumentType;
-	threeDSecureAuthentication: ThreeDSAuthenticationData | null;
+	threeDSecureAuthentication: ThreeDSAuthenticationData$1 | null;
 	vaultData: VaultData | null;
 }
 export interface ApplePayOptions {
@@ -2066,6 +2120,16 @@ export type CardNetworksContextType = {
 export type SdkState = {
 	isSuccessful: boolean;
 	isProcessing: boolean;
+	/**
+	 * MANUAL approval-mode flag: a `:pay` attempt has been created and is
+	 * awaiting merchant approval (202 response). Drives the loading UI while
+	 * the merchant approves/aborts. Distinct from `isProcessing` ("a payment is
+	 * being created/processed") because the downstream locking and continueFlow
+	 * functionalities need to tell the two phases apart.
+	 * Exactly one of `isProcessing` / `isAwaitingApproval` is true at a time.
+	 * Exited by continueFlow()/safety polling.
+	 */
+	isAwaitingApproval: boolean;
 	/**
 	 * SDK/component initialization errors.
 	 * This represents errors from the Primer JS layer itself (e.g., configuration errors,
@@ -2320,6 +2384,7 @@ export declare class PrimerJS {
 	private headlessInstance;
 	private paymentMethods;
 	private vaultController;
+	private isPaymentInProgress;
 	/**
 	 * Vault namespace providing programmatic access to vaulted payment method operations.
 	 * Use for building custom vault UIs with headless flows.
@@ -2440,6 +2505,13 @@ export declare class PrimerJS {
 	 * @internal
 	 */
 	setVaultController(controller: VaultManagerController | null): void;
+	/**
+	 * Internal method to wire the payment-in-progress check.
+	 * Called during initialization so `refreshSession()` can guard against
+	 * running while a payment is in flight.
+	 * @internal
+	 */
+	setPaymentInProgressCheck(check: () => boolean): void;
 	/**
 	 * Internal implementation of createCvvInput.
 	 * @internal
@@ -2481,12 +2553,25 @@ export declare class PrimerJS {
 	}): Promise<void>;
 	/**
 	 * Refetches a new client session from merchant backend.
+	 *
+	 * No-op if a payment is currently in progress: refreshing mid-flow could
+	 * re-evaluate visibility rules and yank the in-use payment method out from
+	 * under the user. A `[PRIMER]` warning is logged (visible to integrators in
+	 * the console) so the no-op is observable during local development — e.g.
+	 * if `refreshSession()` is called from a `primer:payment-start` handler.
 	 */
 	refreshSession(): Promise<void>;
 	/**
 	 * Returns the cached list of payment methods.
 	 */
 	getPaymentMethods(): PaymentMethodInfo[];
+	/**
+	 * Internal accessor that returns the initialized payment methods (with their
+	 * managers), used by the refresh path to preserve manager identity across
+	 * client-session refreshes.
+	 * @internal
+	 */
+	getInitializedPaymentMethods(): InitializedPaymentMethod[];
 	/**
 	 * Internal method to handle the onPaymentStart callback
 	 * @internal - This is only used internally by the SDK
@@ -2585,6 +2670,9 @@ export interface PrimerEvents {
 		paymentMethodType: PaymentMethodType | null;
 		timestamp: number;
 	}>;
+	"primer:payment-approval-required": CustomEvent<PaymentApprovalRequiredData & {
+		timestamp: number;
+	}>;
 	"primer:vault-methods-update": CustomEvent<{
 		vaultedPayments: VaultedPaymentMethodSummary[];
 		cvvRecapture: boolean;
@@ -2656,6 +2744,14 @@ declare class PrimerEventsController {
 		diagnosticsId?: string;
 		data?: Record<string, unknown>;
 	}, paymentMethodType: PaymentMethodType | undefined, payment?: Payment): void;
+	/**
+	 * Dispatch payment approval required event (MANUAL approval flow).
+	 * Called when `:pay` returns 202 and the attempt awaits merchant approval.
+	 *
+	 * The detail carries clientSessionId + paymentAttemptId for the merchant's
+	 * backend to call /approve or /abort, and continueFlow() to resume the SDK.
+	 */
+	dispatchPaymentApprovalRequired(detail: PaymentApprovalRequiredData): void;
 	/**
 	 * Dispatch vault methods update event.
 	 * Called when vaulted payment methods are loaded or updated.
@@ -2830,6 +2926,14 @@ declare class HeadlessSdkController implements ReactiveController {
 	private clearLoadingTimeout;
 	private cleanupResources;
 	private _loadV2Sdk;
+	/**
+	 * MANUAL approval flow: on a `:pay` 202, sdk-core invokes this. Enter the
+	 * awaiting-approval state (so the checkout shows its loading UI while the
+	 * merchant approves/aborts), then surface the approval request to the
+	 * merchant. State is set BEFORE dispatching so listeners that synchronously
+	 * read state see `isAwaitingApproval: true`.
+	 */
+	private handlePaymentApprovalRequired;
 	initializeHeadless(): ([clientToken, options]: readonly [
 		string | null,
 		PrimerCheckoutOptions | null
@@ -2841,6 +2945,8 @@ declare class HeadlessSdkController implements ReactiveController {
 	 * @param cardNetworks - The new card networks context
 	 */
 	private updateCardNetworksState;
+	get isProcessing(): boolean;
+	private onMethodsRefreshed;
 }
 /**
  * PrimerCheckoutComponent implements the main checkout experience.