@funnelfox/billing 0.9.0 → 0.9.3-feat-defer-session-on-interaction.34

package/src/types.d.ts

@@ -74,10 +74,40 @@ export interface BillingCardOptions extends CheckoutCardOptions {
   emailAddress?: BillingCardEmailAddressOptions;
 }
 
+/**
+ * Apple Pay button types (https://developer.apple.com/documentation/applepayontheweb/applepaybuttontype).
+ *
+ * The legacy 7 values (Primer's union) render through Primer's CSS approach.
+ * The newer values (e.g. 'continue') cannot be rendered by WebKit via CSS, so
+ * the SDK overlays Apple's official <apple-pay-button> element on top of the
+ * Primer button and forwards clicks (see utils/apple-pay-native-button.ts,
+ * PRD-1426). Payment flow stays fully Primer-driven either way.
+ */
+export type ApplePayButtonType =
+  | NonNullable<ApplePayOptions['buttonType']>
+  | 'add-money'
+  | 'continue'
+  | 'contribute'
+  | 'order'
+  | 'pay'
+  | 'reload'
+  | 'rent'
+  | 'support'
+  | 'tip'
+  | 'top-up';
+
+export type BillingApplePayOptions = Omit<
+  ApplePayOptions,
+  'container' | 'buttonType'
+> & {
+  buttonType?: ApplePayButtonType;
+};
+
 export interface PrimerCheckoutConfig extends Pick<
   Partial<HeadlessUniversalCheckoutOptions>,
-  'paypal' | 'applePay' | 'googlePay' | 'style'
+  'paypal' | 'googlePay' | 'style'
 > {
+  applePay?: BillingApplePayOptions;
   card?: BillingCardOptions;
   cardSelectors?: CardInputSelectors;
   paymentButtonSelectors?: PaymentButtonSelectors;
@@ -93,6 +123,8 @@ export interface CheckoutConfig extends PrimerCheckoutConfig {
   enableTax?: boolean;
   onTaxChange?: (info: TaxInfo) => void;
   onTaxError?: (error: Error) => void;
+  /** See InitMethodOptions.sessionCreation. Wallet buttons only. */
+  sessionCreation?: SessionCreationMode;
 }
 
 export interface TaxInfo {
@@ -109,7 +141,11 @@ export interface PaymentButtonSelectors {
   applePay: string;
 }
 
-export interface CheckoutOptions extends Partial<HeadlessUniversalCheckoutOptions> {
+export interface CheckoutOptions extends Omit<
+  Partial<HeadlessUniversalCheckoutOptions>,
+  'applePay'
+> {
+  applePay?: BillingApplePayOptions;
   onTokenizeSuccess: OnTokenizeSuccess;
   onResumeSuccess: OnResumeSuccess;
   onAvailablePaymentMethodsLoad?: (items: PaymentMethod[]) => void;
@@ -350,12 +386,13 @@ export interface InitMethodOptions
       Partial<
         Pick<
           HeadlessUniversalCheckoutOptions,
-          'style' | 'card' | 'applePay' | 'paypal' | 'googlePay'
+          'style' | 'card' | 'paypal' | 'googlePay'
         >
       >,
       'card'
     >,
     InitMethodCallbacks {
+  applePay?: BillingApplePayOptions;
   card?: BillingCardOptions;
   orgId: string;
   baseUrl?: string;
@@ -363,7 +400,18 @@ export interface InitMethodOptions
   externalId: string;
   email?: string;
   meta?: MetadataType;
-}
+  /**
+   * When to create the client session for wallet buttons.
+   * 'onMount' (default) creates it immediately — one session per page render.
+   * 'onInteraction' renders Apple's native button first and creates the
+   * session on the visitor's first interaction, so bounced and prerendered
+   * views cost nothing. Requires a native-only Apple Pay buttonType; falls
+   * back to 'onMount' when Apple's SDK is unavailable.
+   */
+  sessionCreation?: SessionCreationMode;
+}
+
+export type SessionCreationMode = 'onMount' | 'onInteraction';
 
 export interface InitMethodCallbacks {
   onRenderSuccess?: () => void;