@paydock/client-sdk 1.144.1-beta → 1.145.0-beta

package/bundles/index.cjs.d.ts

@@ -3782,6 +3782,77 @@ declare enum ERROR_OPERATION {
     SHIPPING_UPDATE = "shipping_update"
 }
 
+/**
+ * Base options shared by every wallet's static availability check
+ * (e.g. `ApplePayOpenWalletButton.checkAvailability`). Wallet-specific option
+ * interfaces extend this with their own fields.
+ */
+interface OpenWalletAvailabilityOptions {
+    /** Public key or access token used to fetch the service config when needed. */
+    public_key_or_access_token?: string;
+    /** Service ID — used with `public_key_or_access_token` to resolve the wallet configuration. */
+    service_id?: string;
+    /** Environment for the config fetch (e.g. `'sandbox'`). Defaults to the SDK default. */
+    env?: string;
+    /**
+     * When `true`, performs only the cheap, network-free synchronous check and resolves
+     * immediately — no config fetch, SDK load, or remote capability query.
+     */
+    sync?: boolean;
+}
+/**
+ * Base result shared by every wallet's static availability check. Wallet-specific
+ * result interfaces extend this with their own fields.
+ */
+interface OpenWalletAvailabilityResult {
+    /** Convenience verdict: the wallet is usable for a payment in the current context. */
+    available: boolean;
+    /** Whether the wallet is supported here at all (may be available via a fallback flow). */
+    supported: boolean;
+    /** Machine-readable reason when not available. */
+    reason?: string;
+}
+
+/**
+ * Friendly capability tokens accepted as **input** — the same values used in
+ * `ApplePayOpenWalletMeta.apple_pay_capabilities`. They declare which device
+ * credential statuses should be treated as "available".
+ */
+type ApplePayCapabilityToken = 'credentials_available' | 'credentials_status_unknown' | 'credentials_unavailable';
+/**
+ * Device-reported credential status — the **output** of
+ * `ApplePaySession.applePayCapabilities()`.
+ */
+type ApplePayCredentialStatus = 'paymentCredentialsAvailable' | 'paymentCredentialStatusUnknown' | 'paymentCredentialsUnavailable' | 'applePayUnsupported';
+/**
+ * Options for `ApplePayOpenWalletButton.checkAvailability`. Provide `merchant_id`
+ * directly to skip the network call, **or** provide `public_key_or_access_token` +
+ * `service_id` to have the SDK resolve the merchant identifier from the service config.
+ */
+interface ApplePayAvailabilityOptions extends OpenWalletAvailabilityOptions {
+    /** Apple merchant identifier. Provide this OR (`public_key_or_access_token` + `service_id`). */
+    merchant_id?: string;
+    /**
+     * Device credential statuses that count as available. Defaults to
+     * `['credentials_available', 'credentials_status_unknown']` — `credentials_status_unknown`
+     * is what third-party / cross-device (QR) browsers report, so the default keeps Apple Pay
+     * visible outside Safari.
+     */
+    apple_pay_capabilities?: ApplePayCapabilityToken[];
+}
+/** Result of `ApplePayOpenWalletButton.checkAvailability`. */
+interface ApplePayAvailabilityResult extends OpenWalletAvailabilityResult {
+    /**
+     * Whether a **native, same-device** Apple Pay session is present right now
+     * (`ApplePaySession` exists and `canMakePayments()` is `true`). Apple does not expose
+     * the transport directly, so use this to infer it: `available && has_native_session` ⇒
+     * native sheet likely; `available && !has_native_session` ⇒ cross-device / QR handoff likely.
+     */
+    has_native_session: boolean;
+    /** The raw device-reported credential status. Undefined when unsupported or not queried. */
+    payment_credential_status?: ApplePayCredentialStatus;
+}
+
 /**
  * Events emitted during the OpenWallet payment lifecycle.
  */
@@ -3933,6 +4004,30 @@ interface OnCancelEventData extends OpenWalletBaseEvent {
     event: EVENT$1.CHECKOUT_CLOSE;
 }
 
+/**
+ * Options for `GooglePayOpenWalletButton.checkAvailability`. Extends
+ * {@link OpenWalletAvailabilityOptions}. All fields are optional — Google Pay's
+ * `isReadyToPay` check does not require a merchant identifier. Provide
+ * `public_key_or_access_token` + `service_id` to validate that the service is a Google Pay
+ * service (and resolve the merchant id), or `merchant_id` directly.
+ */
+interface GooglePayAvailabilityOptions extends OpenWalletAvailabilityOptions {
+    /**
+     * Google Pay gateway merchant identifier. Optional — `isReadyToPay` does not require it;
+     * when omitted the readiness check still runs.
+     */
+    merchant_id?: string;
+}
+/** Result of `GooglePayOpenWalletButton.checkAvailability`. */
+interface GooglePayAvailabilityResult extends OpenWalletAvailabilityResult {
+    /**
+     * Google's `isReadyToPay` `paymentMethodPresent` — whether the buyer already has a
+     * payment method usable with Google Pay. `undefined` when not reported (e.g. the
+     * synchronous check, or browsers where it is not surfaced).
+     */
+    payment_method_present?: boolean;
+}
+
 /**
  * Base metadata required to configure an OpenWallet button.
  */
@@ -4201,6 +4296,16 @@ declare abstract class OpenWalletButtons<TMeta extends OpenWalletMeta = OpenWall
     abstract readonly walletType: WalletType;
     /** @private */
     constructor(selector: string, publicKeyOrAccessToken: string, serviceId: string, meta: TMeta);
+    /**
+     * Invalidates the cached service configuration whenever an error or unavailable
+     * event fires, so the next `load()` re-fetches a fresh config. The cache is keyed
+     * on the service ID with a 1-day TTL; clearing it on failure means a config that
+     * changed server-side (and caused the failure) is not reused until the TTL expires.
+     * Registered once per button, independently of any merchant-registered handlers.
+     *
+     * @private
+     */
+    private registerCacheInvalidationOnError;
     /**
      * Creates the wallet-specific service instance for this button.
      * Each concrete subclass implements this to instantiate its specific wallet service.
@@ -5062,11 +5167,6 @@ type ApplePayButtonStyle$1 = 'black' | 'white' | 'white-outline';
 
 type ApplePayButtonType$1 = 'add-money' | 'book' | 'buy' | 'check-out' | 'continue' | 'contribute' | 'donate' | 'order' | 'pay' | 'plain' | 'reload' | 'rent' | 'set-up' | 'subscribe' | 'support' | 'tip' | 'top-up';
 
-declare global {
-    interface Window {
-        ApplePaySession: ApplePaySession;
-    }
-}
 /** Styling configuration for the Apple Pay button. */
 interface ApplePayOpenWalletMetaStyles extends OpenWalletMetaStyles {
     /** Variant displayed on the button (e.g. `'buy'`, `'donate'`, `'plain'`, `'check-out'`). */
@@ -5127,12 +5227,24 @@ interface ApplePayOpenWalletMeta extends OpenWalletMeta, Omit<ApplePayPaymentReq
     /** Visual styling for the Apple Pay button. */
     style?: ApplePayOpenWalletMetaStyles;
     /**
-     * Device capabilities allowed for the wallet button to be considered available.
-     * Used as a relaxation knob for testing — defaults to `['paymentCredentialsAvailable']` only.
+     * Device credential statuses that make the button render. Defaults to
+     * `['credentials_available', 'credentials_status_unknown']`:
+     * - `credentials_available` — the device has a confirmed Apple Pay card ready to use.
+     * - `credentials_status_unknown` — a local card can't be confirmed, but Apple Pay can
+     *   still proceed (e.g. the cross-device flow where the buyer completes payment on their
+     *   iPhone via QR, used by Chrome, Edge and Firefox).
+     * The button renders when the device's reported status is in this list. Narrow to
+     * `['credentials_available']` to require a confirmed local card.
      */
     apple_pay_capabilities?: Array<'credentials_available' | 'credentials_status_unknown' | 'credentials_unavailable'>;
 }
 
+declare global {
+    interface Window {
+        ApplePaySession: ApplePaySession;
+    }
+}
+
 /**
  * @classdesc Apple Pay wallet button that creates One-Time Tokens (OTT) via Apple Pay.
  *
@@ -5171,6 +5283,46 @@ interface ApplePayOpenWalletMeta extends OpenWalletMeta, Omit<ApplePayPaymentReq
 declare class ApplePayOpenWalletButton extends OpenWalletButtons<ApplePayOpenWalletMeta> {
     /** @private */
     readonly walletType: WalletType;
+    /**
+     * Checks Apple Pay availability **without instantiating the button** — the single,
+     * authoritative, cross-browser-aware availability entry point.
+     *
+     * Resolves the merchant identifier (either supplied directly or fetched from the
+     * service configuration), loads Apple's web SDK if needed, then queries
+     * `ApplePaySession.applePayCapabilities()`. Returns a convenience `available` verdict
+     * (computed against `apple_pay_capabilities`), the raw device-reported
+     * `payment_credential_status`, and `has_native_session` so callers can infer the transport:
+     * `available && has_native_session` ⇒ native sheet likely; `available && !has_native_session`
+     * ⇒ cross-device / QR handoff likely.
+     *
+     * Pass `{ sync: true }` for a cheap, network-free native same-device pre-check that
+     * resolves immediately (see {@link ApplePayAvailabilityOptions.sync}).
+     *
+     * @param {ApplePayAvailabilityOptions} [options] - Merchant context, allowed capabilities, and mode.
+     * @returns {Promise<ApplePayAvailabilityResult>} The availability result.
+     *
+     * @example
+     * // Lightest path — no network, when you already know the merchant identifier:
+     * const result = await ApplePayOpenWalletButton.checkAvailability({ merchant_id });
+     *
+     * @example
+     * // Resolve the merchant identifier from the service configuration:
+     * const result = await ApplePayOpenWalletButton.checkAvailability({
+     *   public_key_or_access_token,
+     *   service_id,
+     *   env: 'sandbox',
+     * });
+     * if (result.available) {
+     *   // Render the Apple Pay button (native sheet or cross-device QR, per has_native_session).
+     * } else {
+     *   console.log('Unavailable:', result.reason, result.payment_credential_status);
+     * }
+     *
+     * @example
+     * // Synchronous native-only fast check (no network / SDK load):
+     * const { has_native_session } = await ApplePayOpenWalletButton.checkAvailability({ sync: true });
+     */
+    static checkAvailability(options?: ApplePayAvailabilityOptions): Promise<ApplePayAvailabilityResult>;
     /**
      * Validates Apple Pay-specific required metadata fields.
      * Apple Pay requires `amount_label` and `store_name` to be present and strings.
@@ -5342,6 +5494,38 @@ interface GooglePayCardConfig {
 declare class GooglePayOpenWalletButton extends OpenWalletButtons<GooglePayOpenWalletMeta> {
     /** @private */
     readonly walletType: WalletType;
+    /**
+     * Checks Google Pay availability **without instantiating the button** — the static
+     * availability entry point.
+     *
+     * Loads the Google Pay JS SDK if needed, then runs `PaymentsClient.isReadyToPay()` using
+     * the **default** card configuration (a button instance with a custom `card_config` may
+     * produce a different result). All options are optional — unlike Apple Pay, Google Pay's
+     * readiness check does not require a merchant identifier; supplying `service_id` +
+     * `public_key_or_access_token` additionally validates that the service is a Google Pay service.
+     *
+     * Pass `{ sync: true }` for a cheap, network-free check that only reports whether the
+     * Google Pay JS API is already present (see {@link GooglePayAvailabilityOptions.sync}).
+     *
+     * @param {GooglePayAvailabilityOptions} [options] - Optional merchant context and mode.
+     * @returns {Promise<GooglePayAvailabilityResult>} The availability result.
+     *
+     * @example
+     * // Simplest form — no merchant context needed:
+     * const result = await GooglePayOpenWalletButton.checkAvailability();
+     * if (result.available) {
+     *   // Render the Google Pay button.
+     * }
+     *
+     * @example
+     * // Validate the service is a Google Pay service while checking:
+     * const result = await GooglePayOpenWalletButton.checkAvailability({
+     *   public_key_or_access_token,
+     *   service_id,
+     *   env: 'sandbox',
+     * });
+     */
+    static checkAvailability(options?: GooglePayAvailabilityOptions): Promise<GooglePayAvailabilityResult>;
     /**
      * Validates Google Pay-specific required metadata fields.
      * Google Pay has no additional required fields beyond the base (amount, currency, country).
@@ -7256,4 +7440,4 @@ declare global {
 }
 
 export { AfterpayCheckoutButton, AfterpayOnSiteMessaging, Api, ApplePayOpenWalletButton, ApplePayWalletButtonExpress, CANVAS_3DS_EVENT, CHECKOUT_BUTTON_EVENT, EVENT$2 as CHECKOUT_EVENT, Canvas3ds, Canvas3dsTokenFormat, Checkout, CheckoutActionCode, ClickToPay, Configuration, ContactShippingEditingMode, ELEMENT, ERROR_OPERATION, EVENT$3 as EVENT, Builder$1 as ExternalCheckoutBuilder, Checker as ExternalCheckoutChecker, FORM_FIELD, FRAUD_PREVENTION_EVENTS, FraudPreventionService, GooglePayOpenWalletButton, HtmlMultiWidget, HtmlPaymentSourceWidget, HtmlWidget, InstructionDebugger, MultiWidget, OpenWalletButtons, PAYMENT_EXPIRED, PAYMENT_FAILURE, PAYMENT_SUCCESSFUL, PAYMENT_TYPE, PURPOSE, PayPalDataCollector, PayPalSavePaymentSourceWidget, Builder as PaymentSourceBuilder, PaymentSourceWidget, PaypalCheckoutButton, PaypalWalletButtonExpress, STYLABLE_ELEMENT, STYLABLE_ELEMENT_STATE, STYLE, SUPPORTED_CARD_TYPES, TEXT, TOKEN_TYPE, TRIGGER, TYPE, VAULT_DISPLAY_STYLE, VaultDisplayWidget, EVENT as WALLET_BUTTONS_EXPRESS_EVENT, WALLET_TYPES, WalletButtons, ZipmoneyCheckoutButton };
-export type { ApplePayButtonStyle, ApplePayButtonType, ApplePayOpenWalletMeta, ApplePayWalletMeta, AppleShippingType, BaseWalletMeta, Billing, Canvas3dsAuthPayload, Canvas3dsChargeAuthEventPayload, Canvas3dsErrorEventPayload, Canvas3dsErrorPayload, Canvas3dsEventMap, Canvas3dsEventName, CheckoutIntentTokenPayload, CheckoutPaymentExpiredPayload, CheckoutPaymentFailurePayload, CheckoutPaymentSuccessPayload, CheckoutResponse, CreateOTTData, CreateOTTRequest, CreateOTTResponse, CreateSessionRequest, CreateSessionResponse, EventTypes, FraudPreventionEvent, FraudPreventionEventType, FraudPreventionProvider, GooglePayCardConfig, GooglePayOpenWalletMeta, GooglePayOpenWalletMetaStyles, HandleResponseInterface, IApplePayShippingOption, ICheckout, IClickToPayMeta, IDetails, IElementStyleInput, IEventAfterLoadData, IEventCheckoutFinishData, IEventData$1 as IEventData, IEventError, IEventFinishData, IEventMetaData, IEventSizeData, IFormValidation, IOpenWalletProvider, IPayPalMeta, IStyles$1 as IStyles, ITexts, ITokenStandalone3DS, IWalletMeta, IWalletOnClickEvent, IWalletPaymentSuccessfulEvent, IWalletUnavailableEvent, IWalletUpdateData, IWalletUpdateEvent, OTTResponse, OnCancelEventData, OnClickEventData$1 as OnClickEventData, OnCreateOTTErrorEventData, OnCreateOTTErrorPayload, OnCreateOTTSuccessPayload, OnCreateOTTSuccessfulEventData, OnErrorEventData$1 as OnErrorEventData, OnErrorPayload, OnLoadedEventData, OnUnavailableDetails, OnUnavailableEventData$1 as OnUnavailableEventData, OnUnavailablePayload, OpenWalletBaseEvent, OpenWalletDataEvent, OpenWalletEventType, OpenWalletMeta, PaypalWalletMeta, ProcessAuthenticationResponse, Shipping, VaultDisplayStyle, OnClickEventData as WalletExpressOnClickEventData, OnCloseEventData as WalletExpressOnCloseEventData, OnErrorEventData as WalletExpressOnErrorEventData, OnPaymentErrorEventData as WalletExpressOnPaymentErrorEventData, OnPaymentInReviewEventData as WalletExpressOnPaymentInReviewEventData, OnPaymentSuccessfulEventData as WalletExpressOnPaymentSuccessfulEventData, OnShippingAddressChangeEventData as WalletExpressOnShippingAddressChangeEventData, OnShippingAddressChangeEventResponse as WalletExpressOnShippingAddressChangeEventResponse, OnShippingOptionChangeEventData as WalletExpressOnShippingOptionChangeEventData, OnShippingOptionChangeEventResponse as WalletExpressOnShippingOptionChangeEventResponse, OnUnavailableEventData as WalletExpressOnUnavailableEventData, WalletType, WidgetEventMap, WidgetEventName };
+export type { ApplePayAvailabilityOptions, ApplePayAvailabilityResult, ApplePayButtonStyle, ApplePayButtonType, ApplePayCapabilityToken, ApplePayCredentialStatus, ApplePayOpenWalletMeta, ApplePayWalletMeta, AppleShippingType, BaseWalletMeta, Billing, Canvas3dsAuthPayload, Canvas3dsChargeAuthEventPayload, Canvas3dsErrorEventPayload, Canvas3dsErrorPayload, Canvas3dsEventMap, Canvas3dsEventName, CheckoutIntentTokenPayload, CheckoutPaymentExpiredPayload, CheckoutPaymentFailurePayload, CheckoutPaymentSuccessPayload, CheckoutResponse, CreateOTTData, CreateOTTRequest, CreateOTTResponse, CreateSessionRequest, CreateSessionResponse, EventTypes, FraudPreventionEvent, FraudPreventionEventType, FraudPreventionProvider, GooglePayAvailabilityOptions, GooglePayAvailabilityResult, GooglePayCardConfig, GooglePayOpenWalletMeta, GooglePayOpenWalletMetaStyles, HandleResponseInterface, IApplePayShippingOption, ICheckout, IClickToPayMeta, IDetails, IElementStyleInput, IEventAfterLoadData, IEventCheckoutFinishData, IEventData$1 as IEventData, IEventError, IEventFinishData, IEventMetaData, IEventSizeData, IFormValidation, IOpenWalletProvider, IPayPalMeta, IStyles$1 as IStyles, ITexts, ITokenStandalone3DS, IWalletMeta, IWalletOnClickEvent, IWalletPaymentSuccessfulEvent, IWalletUnavailableEvent, IWalletUpdateData, IWalletUpdateEvent, OTTResponse, OnCancelEventData, OnClickEventData$1 as OnClickEventData, OnCreateOTTErrorEventData, OnCreateOTTErrorPayload, OnCreateOTTSuccessPayload, OnCreateOTTSuccessfulEventData, OnErrorEventData$1 as OnErrorEventData, OnErrorPayload, OnLoadedEventData, OnUnavailableDetails, OnUnavailableEventData$1 as OnUnavailableEventData, OnUnavailablePayload, OpenWalletAvailabilityOptions, OpenWalletAvailabilityResult, OpenWalletBaseEvent, OpenWalletDataEvent, OpenWalletEventType, OpenWalletMeta, PaypalWalletMeta, ProcessAuthenticationResponse, Shipping, VaultDisplayStyle, OnClickEventData as WalletExpressOnClickEventData, OnCloseEventData as WalletExpressOnCloseEventData, OnErrorEventData as WalletExpressOnErrorEventData, OnPaymentErrorEventData as WalletExpressOnPaymentErrorEventData, OnPaymentInReviewEventData as WalletExpressOnPaymentInReviewEventData, OnPaymentSuccessfulEventData as WalletExpressOnPaymentSuccessfulEventData, OnShippingAddressChangeEventData as WalletExpressOnShippingAddressChangeEventData, OnShippingAddressChangeEventResponse as WalletExpressOnShippingAddressChangeEventResponse, OnShippingOptionChangeEventData as WalletExpressOnShippingOptionChangeEventData, OnShippingOptionChangeEventResponse as WalletExpressOnShippingOptionChangeEventResponse, OnUnavailableEventData as WalletExpressOnUnavailableEventData, WalletType, WidgetEventMap, WidgetEventName };