@revenuecat/purchases-js 1.43.1 → 1.45.0

package/dist/Purchases.es.d.ts

@@ -302,7 +302,17 @@ declare type EventPropertySingleValue = string | number | boolean;
 
 declare type EventPropertyValue = null | EventPropertySingleValue | Array<EventPropertyValue>;
 
-/* Excluded from this release type: ExpressPurchaseButtonUpdater */
+/**
+ * Callback to be called when the express purchase button is ready to be updated.
+ * @experimental
+ * @public
+ */
+export declare interface ExpressPurchaseButtonUpdater {
+    /**
+     * Updates the purchase option of the express purchase button.
+     */
+    updatePurchase: (pkg: Package, purchaseOption?: PurchaseOption) => void;
+}
 
 /**
  * Flags used to enable or disable certain features in the sdk.
@@ -775,21 +785,7 @@ export declare enum PackageType {
  * Listener for paywall purchase lifecycle events.
  * @public
  */
-export declare interface PaywallListener {
-    /**
-     * Called when a purchase flow is about to start for the given package.
-     */
-    onPurchaseStarted?: (rcPackage: Package) => void;
-    /**
-     * Callback called when an error that won't close the paywall occurs.
-     * For example, a retryable error during the purchase process.
-     */
-    onPurchaseError?: (error: Error) => void;
-    /**
-     * Called when the user cancels the purchase flow.
-     */
-    onPurchaseCancelled?: () => void;
-}
+export declare type PaywallListener = PurchaseListener;
 
 /**
  * Represents the result of a purchase operation initiated from a paywall.
@@ -875,7 +871,91 @@ export declare interface PresentedOfferingContext {
     readonly placementIdentifier: string | null;
 }
 
-/* Excluded from this release type: PresentExpressPurchaseButtonParams */
+/**
+ * Parameters for the {@link Purchases.presentExpressPurchaseButton} method.
+ *
+ * @example
+ * ```ts
+ * const offerings = await purchases.getOfferings();
+ * const pkg = offerings.current?.availablePackages[0];
+ * const htmlTarget = document.getElementById("express-purchase-button");
+ * const fallbackButton = document.getElementById("checkout-button");
+ *
+ * if (pkg && htmlTarget) {
+ *   let expressButtonUpdater: ExpressPurchaseButtonUpdater | undefined;
+ *
+ *   void purchases.presentExpressPurchaseButton({
+ *     rcPackage: pkg,
+ *     htmlTarget,
+ *     onButtonReady: (updater, walletsAvailable) => {
+ *       expressButtonUpdater = updater;
+ *       htmlTarget.hidden = !walletsAvailable;
+ *
+ *       if (fallbackButton) {
+ *         fallbackButton.hidden = walletsAvailable;
+ *       }
+ *     },
+ *   });
+ *
+ *   // If the customer selects a different package later, update the button
+ *   // instead of rendering a new one.
+ *   function onSelectedPackageChanged(nextPackage: Package) {
+ *     expressButtonUpdater?.updatePurchase(nextPackage);
+ *   }
+ * }
+ * ```
+ *
+ * @experimental
+ * @public
+ */
+export declare interface PresentExpressPurchaseButtonParams {
+    /**
+     * The package you want to purchase. Obtained from {@link Purchases.getOfferings}.
+     */
+    rcPackage: Package;
+    /**
+     * The HTML element where the express purchase button should be rendered.
+     */
+    htmlTarget: HTMLElement;
+    /**
+     * The option to be used for this purchase. If not specified or null the default one will be used.
+     */
+    purchaseOption?: PurchaseOption | null;
+    /**
+     * The email of the user. If undefined, RevenueCat will ask the customer for their email.
+     */
+    customerEmail?: string;
+    /**
+     * The locale to use for the purchase flow. If not specified, English will be used
+     */
+    selectedLocale?: string;
+    /**
+     * The default locale to use if the selectedLocale is not available.
+     * Defaults to english.
+     */
+    defaultLocale?: string;
+    /**
+     * The purchase metadata to be passed to the backend.
+     * Any information provided here will be propagated to the payment gateway and
+     * to the RC transaction as metadata.
+     */
+    metadata?: PurchaseMetadata;
+    /* Excluded from this release type: labelsOverride */
+    /**
+     * Callback to be called when the express purchase button is ready to be clicked.
+     */
+    onButtonReady?: (updater: ExpressPurchaseButtonUpdater, walletsAvailable: boolean) => void;
+    /**
+     * Optional listener for purchase lifecycle events.
+     */
+    listener?: PurchaseListener;
+    /**
+     * Theme for the Stripe wallet button appearance.
+     * Matches Apple Pay button styles: 'black', 'white', or 'white-outline'
+     * Defaults to "black".
+     */
+    walletButtonTheme?: WalletButtonTheme;
+}
 
 /**
  * Parameters for the {@link Purchases.presentPaywall} method.
@@ -1193,6 +1273,26 @@ declare enum PurchaseFlowErrorCode {
     InvalidPaddleAPIKeyError = 9
 }
 
+/**
+ * Listener for purchase lifecycle events.
+ * @public
+ */
+export declare interface PurchaseListener {
+    /**
+     * Called when a purchase flow is about to start for the given package.
+     */
+    onPurchaseStarted?: (rcPackage: Package) => void;
+    /**
+     * Callback called when an error that won't close the paywall occurs.
+     * For example, a retryable error during the purchase process.
+     */
+    onPurchaseError?: (error: Error) => void;
+    /**
+     * Called when the user cancels the purchase flow.
+     */
+    onPurchaseCancelled?: () => void;
+}
+
 /**
  * Metadata that can be passed to the backend when making a purchase.
  * They will propagate to the payment gateway (i.e. Stripe) and to RevenueCat.
@@ -1433,7 +1533,14 @@ export declare class Purchases {
          * @throws {@link PurchasesError} if there is an error while performing the purchase. If the {@link PurchasesError.errorCode} is {@link ErrorCode.UserCancelledError}, the user cancelled the purchase.
              */
          purchasePackage(rcPackage: Package, customerEmail?: string, htmlTarget?: HTMLElement): Promise<PurchaseResult>;
-         /* Excluded from this release type: presentExpressPurchaseButton */
+         /**
+          * Renders an Express Purchase button for the supported wallets (Apple Pay/Google Pay).
+          * When clicked it uses the wallet UI to execute the purchase instead of
+          * the checkout flow that would be shown with `.purchase`.
+          * @param params - The parameters object to customise the purchase flow. Check {@link PresentExpressPurchaseButtonParams}
+          * @returns Promise<PurchaseResult>
+          */
+         presentExpressPurchaseButton(params: PresentExpressPurchaseButtonParams): Promise<PurchaseResult>;
          /* Excluded from this release type: getWalletButtonRender */
          /**
           * Method to perform a purchase for a given package. You can obtain the