@primer-io/primer-js 0.3.7 → 0.3.8

package/dist/jsx/index.d.ts

@@ -288,6 +288,10 @@ export type CardFormComponentProps = {
   clientOptions?: ClientOptionsContextType;
   /** Headless utils for accessing server configuration */
   headlessUtils?: HeadlessUtilsContextType;
+  /** Analytics utils for sending analytics events */
+  analyticsUtils?: AnalyticsContextType;
+  /** Events controller from context for receiving forwarded events */
+  contextEventsController?: EventsContextType;
   /** Determines whether to show the cardholder name field
 Uses client configuration with fallback to default (true) */
   shouldShowCardholderName?: boolean;
@@ -347,6 +351,8 @@ export type PaymentMethodComponentProps = {
   disabled?: boolean;
   /**  */
   paymentMethods?: PaymentMethodsContextType;
+  /** Analytics utils for sending analytics events */
+  analyticsUtils?: AnalyticsContextType;
 };
 
 export type PaymentMethodContainerComponentProps = {
@@ -450,6 +456,10 @@ Falls back to localized default if not explicitly set. */
   variant?: string;
   /** Whether the button is disabled. */
   disabled?: boolean;
+  /**  */
+  analyticsUtils?: AnalyticsContextType;
+  /**  */
+  contextEventsController?: EventsContextType;
 };
 
 export type CardNetworkSelectorComponentProps = {
@@ -944,7 +954,11 @@ export type CustomElements = {
 
   /**
    * A form submit button component for card forms.
-   * Provides a consistent submit button with translation support.
+   *
+   * Provides a consistent submit button with translation support and configurable visibility.
+   * When `submitButton.useBuiltInButton` is set to `false`, the component will not render
+   * any DOM elements, allowing external buttons to handle form submission by dispatching
+   * the `primer:card-submit` event.
    * ---
    *
    */

package/dist/primer-loader.d.ts

@@ -747,6 +747,14 @@ export interface VaultData {
 	customerId: string;
 }
 type EventListener$1 = (event?: Event) => void;
+export interface AnalyticsUtils {
+	environment: string;
+	primerAccountId?: string;
+	checkoutSessionId: string;
+	clientSessionId?: string;
+	clientSessionToken?: string;
+	sdkVersion?: string;
+}
 export interface PrimerHeadlessCheckout {
 	createPaymentMethodManager(type: "PAYMENT_CARD", options?: PaymentMethodManagerOptions): Promise<ICardPaymentMethodManager | null>;
 	createPaymentMethodManager(type: "PAYPAL" | "GOOGLE_PAY" | "APPLE_PAY", options?: PaymentMethodManagerOptions): Promise<INativePaymentMethodManager | null>;
@@ -755,6 +763,7 @@ export interface PrimerHeadlessCheckout {
 	createPaymentMethodManager(type: PaymentMethodType, options?: PaymentMethodManagerOptions): Promise<IRedirectPaymentMethodManager | null>;
 	createVaultManager(): HeadlessVaultManager;
 	getSDKUtilities(): HeadlessSDKUtilities;
+	getAnalyticsUtils?: () => AnalyticsUtils;
 	configure?: (options: Omit<HeadlessUniversalCheckoutOptions, "clientSessionCachingEnabled">) => void;
 	getAssetsManager(): IAssetsManager;
 	start: () => Promise<void>;
@@ -937,6 +946,13 @@ export interface PrimerCheckoutOptions {
 	clientToken?: string;
 	locale?: string;
 	apiVersion?: APIVersionOption;
+	/**
+	 * Specifies the merchant's domain for Apple Pay domain validation.
+	 * If not provided, defaults to window.location.hostname.
+	 * This is particularly useful when the checkout is hosted on a different domain
+	 * than the merchant's registered Apple Pay domain.
+	 */
+	merchantDomain?: string;
 	card?: {
 		cardholderName?: {
 			required?: boolean;
@@ -971,8 +987,40 @@ export interface PrimerCheckoutOptions {
 		};
 		publishableKey?: string;
 	} & Record<string, unknown>;
+	/**
+	 * Configuration for the submit button behavior in Primer.js components.
+	 */
 	submitButton?: {
+		/**
+		 * Whether to show the order amount on the submit button.
+		 * When true, displays formatted amount next to button text (e.g., "Pay $12.34").
+		 * @default false
+		 */
 		amountVisible?: boolean;
+		/**
+		 * Whether to render the built-in submit button component.
+		 *
+		 * When `true` (default): The component renders the standard Primer submit button.
+		 * When `false`: No DOM elements are created, allowing external buttons to handle
+		 * form submission by dispatching the 'primer:card-submit' event.
+		 *
+		 * @example
+		 * // Hide built-in button and use external button
+		 * const options = {
+		 *   submitButton: {
+		 *     useBuiltInButton: false
+		 *   }
+		 * };
+		 *
+		 * // External button should dispatch this event to submit
+		 * const submitEvent = new CustomEvent('primer:card-submit', {
+		 *   bubbles: true,
+		 *   composed: true
+		 * });
+		 *
+		 * @default true
+		 */
+		useBuiltInButton?: boolean;
 	};
 	sdkCore?: boolean;
 	disabledPayments?: boolean;
@@ -1104,11 +1152,18 @@ export declare class PrimerJS {
 	 */
 	handlePaymentFailure(error: PrimerClientError, payment?: Payment): void;
 }
+export interface CardSubmitResult {
+	success?: boolean;
+	token?: string;
+	analyticsId?: string;
+	paymentId?: string;
+	[key: string]: unknown;
+}
 export interface CardSubmitSuccessPayload {
-	result: unknown;
+	result: CardSubmitResult;
 }
 export interface CardSubmitErrorsPayload {
-	errors: unknown;
+	errors: InputValidationError[];
 }
 export interface CardSubmitPayload {
 	source?: string;
@@ -1146,9 +1201,19 @@ declare class PrimerEventsController implements ReactiveController {
 	dispatchCheckoutInitialized(checkoutInstance: PrimerJS): void;
 	dispatchCardNetworkChange(network: CardNetworksContextType): void;
 	dispatchCardSubmit(source?: string): void;
-	dispatchFormSubmitSuccess(result: unknown): void;
-	dispatchFormSubmitErrors(errors: unknown): void;
+	dispatchFormSubmitSuccess(result: CardSubmitResult): void;
+	dispatchFormSubmitErrors(errors: InputValidationError[]): 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
+	 * that come from custom buttons or external triggers.
+	 *
+	 * @param eventDetails - The event details to forward, including source information
+	 */
+	handleExternalCardSubmit(eventDetails: CardSubmitPayload): void;
 }
+export type AnalyticsContextType = AnalyticsUtils | null;
+export type EventsContextType = PrimerEventsController | null;
 export type HeadlessUtilsContextType = HeadlessSDKUtilities | null;
 export type KlarnaCategoriesContextType = {
 	categories: KlarnaPaymentMethodCategory[];
@@ -1291,6 +1356,8 @@ declare class SDKContextController implements ReactiveController {
 	private headlessUtilsProvider;
 	private klarnaCategoriesProvider;
 	private computedStylesProvider;
+	private analyticsProvider;
+	private eventsProvider;
 	constructor(host: PrimerCheckoutType);
 	hostConnected(): void;
 	/**
@@ -1313,8 +1380,15 @@ declare class SDKContextController implements ReactiveController {
 	setKlarnaCategories(value: KlarnaCategoriesContextType): void;
 	setClientOptions(value: PrimerCheckoutOptions | null): void;
 	setHeadlessUtils(value: HeadlessUtilsContextType): void;
+	setAnalyticsUtils(value: AnalyticsContextType): void;
+	getAnalyticsUtils(): AnalyticsContextType | undefined;
 	setComputedStyles(value: CSSStyleDeclaration): void;
 	setVaultManagerCvv(value: VaultItemContextType): void;
+	/**
+	 * Updates the events context.
+	 * @param value The new events controller.
+	 */
+	setEventsController(value: EventsContextType): void;
 }
 export type SdkStateAction = {
 	type: "START_PROCESSING";
@@ -1541,6 +1615,7 @@ export declare class PrimerCheckoutComponent extends LitElement implements Prime
 	private previousLoadingState;
 	private hasAssignedContent;
 	private _loadingTimeoutId;
+	private _eventListenerController;
 	locale?: LocaleCode;
 	private onSlotChange;
 	sdkContextController: SDKContextController;
@@ -1551,10 +1626,16 @@ export declare class PrimerCheckoutComponent extends LitElement implements Prime
 	cardNetworkController: CardNetworkController;
 	achPaymentEventsController: AchPaymentEventsController;
 	constructor();
+	connectedCallback(): void;
 	attributeChangedCallback(attrName: string, oldVal: string, newVal: string): void;
 	disconnectedCallback(): void;
 	willUpdate(changedProperties: PropertyValues): void;
 	updated(): void;
+	/**
+	 * Handle external primer:card-submit events by forwarding them through the events controller
+	 * Uses AbortController signal to prevent circular event loops more safely
+	 */
+	private handleExternalCardSubmit;
 	/**
 	 * Check if the loading state has changed and update the CSS loader visibility accordingly.
 	 * This method is called after each update cycle to detect when loading is complete.
@@ -2114,6 +2195,20 @@ declare class PaymentMethodComponent extends LitElement {
 	type: PaymentMethodType | undefined;
 	disabled: boolean;
 	paymentMethods: PaymentMethodsContextType;
+	/**
+	 * Analytics utils for sending analytics events
+	 */
+	analyticsUtils: AnalyticsContextType;
+	/**
+	 * Sends PAYMENT_METHOD_SELECTION analytics event when user clicks on payment method
+	 * @private
+	 */
+	private sendPaymentMethodSelectionEvent;
+	/**
+	 * Handle interaction events on payment method component
+	 * @private
+	 */
+	private handleClick;
 	render(): typeof nothing | import("lit-html").TemplateResult<1>;
 }
 declare global {
@@ -2186,7 +2281,7 @@ declare class AchPaymentComponent extends LitElement {
 	private _handleDeclineMandate;
 	private renderForm;
 	private renderMandate;
-	render(): TemplateResult | typeof nothing | undefined;
+	render(): typeof nothing | TemplateResult | undefined;
 }
 declare global {
 	interface HTMLElementTagNameMap {
@@ -2728,6 +2823,11 @@ declare class CardFormComponent extends LitElement {
 	 */
 	private hasAssignedContent;
 	private selectedCardNetwork;
+	/**
+	 * Flag to track if PAYMENT_METHOD_SELECTION event has been sent
+	 * @private
+	 */
+	private paymentMethodSelectionSent;
 	/**
 	 * Payment managers injected from context
 	 */
@@ -2740,6 +2840,14 @@ declare class CardFormComponent extends LitElement {
 	 * Headless utils for accessing server configuration
 	 */
 	headlessUtils: HeadlessUtilsContextType;
+	/**
+	 * Analytics utils for sending analytics events
+	 */
+	analyticsUtils: AnalyticsContextType;
+	/**
+	 * Events controller from context for receiving forwarded events
+	 */
+	contextEventsController: EventsContextType;
 	/**
 	 * Context provider for card form data
 	 */
@@ -2758,6 +2866,14 @@ declare class CardFormComponent extends LitElement {
 	 * Events controller for dispatching form events
 	 */
 	private readonly eventsController;
+	/**
+	 * External event listener reference for cleanup
+	 */
+	private _contextCardSubmitListener;
+	/**
+	 * Flag to prevent circular event loop when handling events
+	 */
+	private _isHandlingContextEvent;
 	/**
 	 * Registry for input controllers to enable context-driven meta state management
 	 */
@@ -2766,6 +2882,22 @@ declare class CardFormComponent extends LitElement {
 	 * Task to set up the card form with hosted inputs
 	 */
 	private readonly setupCardFormTask;
+	/**
+	 * Sends PAYMENT_METHOD_SELECTION analytics event when user first interacts with card form
+	 * @private
+	 */
+	private sendPaymentMethodSelectionEvent;
+	/**
+	 * Checks if all required fields are filled and sends PAYMENT_DETAILS_ENTERED event
+	 * @private
+	 */
+	private checkAndSendPaymentDetailsEnteredEvent;
+	private paymentDetailsEnteredSent;
+	/**
+	 * Sends PAYMENT_DETAILS_ENTERED analytics event when all payment details are complete and valid
+	 * @private
+	 */
+	private sendPaymentDetailsEnteredEvent;
 	connectedCallback(): void;
 	disconnectedCallback(): void;
 	/**
@@ -2778,6 +2910,19 @@ declare class CardFormComponent extends LitElement {
 	 * This is a backup method to catch all possible submission events
 	 */
 	private handleDirectSubmit;
+	/**
+	 * Sets up event listeners for context-forwarded events
+	 */
+	private setupContextEventListeners;
+	/**
+	 * Cleans up context event listeners
+	 */
+	private cleanupContextEventListeners;
+	/**
+	 * Handles primer:card-submit events received from the events context
+	 * This allows the card form to respond to external submit triggers
+	 */
+	private handleContextCardSubmit;
 	/**
 	 * Determines if a button is a submit button based on its attributes
 	 */
@@ -2853,6 +2998,11 @@ declare class HostedInputController<T extends HostedInputHost> implements Reacti
 	 * Focuses the input, whether it's a hosted input or standard input
 	 */
 	focusInput(): void;
+	/**
+	 * Notifies the card form context about user interaction for analytics tracking
+	 * @private
+	 */
+	private notifyUserInteraction;
 	/**
 	 * Returns the hosted input from the card form context based on the type.
 	 * For 'cardholderName', no hosted input is provided so we return a fallback indicator.
@@ -2942,6 +3092,7 @@ export interface CardFormContext {
 	propagateValidationErrors: (errors: InputValidationError[]) => void;
 	registerInputController: (inputType: HostedInputType, controller: IHostedInputController) => void;
 	unregisterInputController: (inputType: HostedInputType) => void;
+	onUserInteraction: () => void;
 }
 /**
  * Translation configuration object
@@ -3091,7 +3242,28 @@ declare global {
 }
 /**
  * A form submit button component for card forms.
- * Provides a consistent submit button with translation support.
+ *
+ * Provides a consistent submit button with translation support and configurable visibility.
+ * When `submitButton.useBuiltInButton` is set to `false`, the component will not render
+ * any DOM elements, allowing external buttons to handle form submission by dispatching
+ * the `primer:card-submit` event.
+ *
+ * @example
+ * // Default behavior - renders the built-in submit button
+ * <primer-card-form-submit></primer-card-form-submit>
+ *
+ * @example
+ * // External button integration - hides the built-in button
+ * // Configure with submitButton.useBuiltInButton: false
+ * // External button should dispatch 'primer:card-submit' event
+ * const externalButton = document.getElementById('my-button');
+ * externalButton.addEventListener('click', () => {
+ *   const submitEvent = new CustomEvent('primer:card-submit', {
+ *     bubbles: true,
+ *     composed: true
+ *   });
+ *   document.querySelector('primer-card-form-submit').dispatchEvent(submitEvent);
+ * });
  */
 declare class CardFormSubmitComponent extends LitElement {
 	static styles: import("lit").CSSResult[];
@@ -3107,6 +3279,8 @@ declare class CardFormSubmitComponent extends LitElement {
 	clientOptions: ClientOptionsContextType;
 	sdkState: SdkStateContextType;
 	cardFormContext: CardFormContext | null;
+	analyticsUtils: AnalyticsContextType;
+	contextEventsController: EventsContextType;
 	/**
 	 * The button variant to use.
 	 * @default "primary"
@@ -3117,8 +3291,19 @@ declare class CardFormSubmitComponent extends LitElement {
 	 * @default false
 	 */
 	disabled: boolean;
+	/**
+	 * Gets the submit button configuration from client options.
+	 * Returns the configuration object or null if not set.
+	 */
+	private get submitButtonConfig();
+	/**
+	 * Determines if the built-in submit button should be rendered.
+	 * When false, no DOM elements are created allowing external button integration.
+	 * @returns true if the built-in button should be shown, false otherwise
+	 */
+	private get shouldShowBuiltInButton();
 	private handleClick;
-	render(): import("lit-html").TemplateResult<1>;
+	render(): typeof nothing | import("lit-html").TemplateResult<1>;
 }
 declare global {
 	interface HTMLElementTagNameMap {