@revenuecat/purchases-capacitor-ui/dist/esm/definitions.d.ts

UI components for RevenueCat Capacitor SDK

import type { PluginListenerHandle } from '@capacitor/core';
import type { CustomerInfo, PurchasesError, PurchasesOffering, PurchasesPackage, PurchasesStoreTransaction } from '@revenuecat/purchases-typescript-internal-esm';
import { PAYWALL_RESULT } from '@revenuecat/purchases-typescript-internal-esm';
export interface RevenueCatUIPlugin {
    /**
     * Presents a paywall configured in the RevenueCat dashboard.
     * @param options The options for presenting the paywall.
     * @returns A PaywallResult indicating what happened during the paywall presentation.
     */
    presentPaywall(options?: PresentPaywallOptions): Promise<PaywallResult>;
    /**
     * Presents a paywall only if the user does not have the specified entitlement.
     * @param options The options for presenting the paywall if needed.
     * @returns A PaywallResult indicating what happened during the paywall presentation.
     */
    presentPaywallIfNeeded(options: PresentPaywallIfNeededOptions): Promise<PaywallResult>;
    /**
     * Presents the customer center where users can manage their subscriptions.
     */
    presentCustomerCenter(): Promise<void>;
    /**
     * Used for web only. Enables or disables returning mock results instead of rejecting promises with "not supported".
     * For testing purposes only.
     * @param options Options for mock web results
     */
    setMockWebResults?(options: {
        shouldMockWebResults: boolean;
    }): Promise<void>;
    /**
     * Listen for when a paywall is displayed or dismissed.
     * @param eventName The event to listen for
     * @param listener The listener to call when the event is triggered
     */
    addListener(eventName: 'paywallDisplayed' | 'paywallDismissed', listener: () => void): Promise<PluginListenerHandle>;
    /**
     * Remove all listeners for this plugin.
     */
    removeAllListeners(): Promise<void>;
}
/**
 * Object passed to onPurchaseInitiated that allows the developer to
 * control when (and whether) the purchase flow continues.
 * The developer can store this and call resume() asynchronously
 * (e.g., after an auth flow on a different screen).
 */
export interface PurchaseResumable {
    /** Call to proceed with or cancel the purchase. Defaults to true (proceed). */
    resume(shouldProceed?: boolean): void;
}
/**
 * Callbacks for observing paywall lifecycle events such as purchases,
 * restores, and errors. All callbacks are optional.
 *
 * Pass as `listener` in {@link PresentPaywallOptions} to receive events
 * while the paywall is displayed.
 */
export interface PaywallListener {
    /** Called when a purchase begins for a package. */
    onPurchaseStarted?: (args: {
        packageBeingPurchased: PurchasesPackage;
    }) => void;
    /** Called when a purchase completes successfully. */
    onPurchaseCompleted?: (args: {
        customerInfo: CustomerInfo;
        storeTransaction: PurchasesStoreTransaction;
    }) => void;
    /** Called when a purchase fails with an error. */
    onPurchaseError?: (args: {
        error: PurchasesError;
    }) => void;
    /** Called when the user cancels a purchase. */
    onPurchaseCancelled?: () => void;
    /** Called when a restore operation begins. */
    onRestoreStarted?: () => void;
    /** Called when a restore operation completes successfully. */
    onRestoreCompleted?: (args: {
        customerInfo: CustomerInfo;
    }) => void;
    /** Called when a restore operation fails with an error. */
    onRestoreError?: (args: {
        error: PurchasesError;
    }) => void;
    /**
     * Called before the payment sheet is displayed, allowing the app to gate
     * the purchase flow (e.g., require authentication first).
     *
     * The developer receives a {@link PurchaseResumable} that can be stored
     * and called asynchronously. Call `resumable.resume(true)` to proceed
     * with the purchase, or `resumable.resume(false)` to cancel it.
     *
     * If this callback is not provided, the purchase proceeds automatically.
     */
    onPurchaseInitiated?: (args: {
        packageBeingPurchased: PurchasesPackage;
        resumable: PurchaseResumable;
    }) => void;
}
/**
 * Custom purchase and restore handlers for apps that manage their own
 * purchase flow (`purchasesAreCompletedBy: MY_APP`).
 *
 * When provided in {@link PresentPaywallOptions}, the paywall delegates
 * purchase and restore operations to these handlers instead of using
 * RevenueCat's built-in purchase flow.
 */
export interface PurchaseLogic {
    /**
     * Called when the user initiates a purchase from the paywall.
     * Perform the purchase using your own payment system and return the result.
     */
    performPurchase: (args: {
        packageToPurchase: PurchasesPackage;
    }) => Promise<PurchaseLogicResult>;
    /**
     * Called when the user initiates a restore from the paywall.
     * Perform the restore using your own system and return the result.
     */
    performRestore: () => Promise<PurchaseLogicResult>;
}
/**
 * The result of a custom purchase or restore operation performed by {@link PurchaseLogic}.
 */
export type PurchaseLogicResult = {
    result: PURCHASE_LOGIC_RESULT.SUCCESS;
} | {
    result: PURCHASE_LOGIC_RESULT.CANCELLATION;
} | {
    result: PURCHASE_LOGIC_RESULT.ERROR;
    error?: PurchasesError;
};
/**
 * Possible outcomes from a custom {@link PurchaseLogic} operation.
 */
export declare enum PURCHASE_LOGIC_RESULT {
    /** The purchase or restore completed successfully. */
    SUCCESS = "SUCCESS",
    /** The user cancelled the purchase or restore. */
    CANCELLATION = "CANCELLATION",
    /** The purchase or restore failed with an error. */
    ERROR = "ERROR"
}
/** Presentation styles available for paywalls on iOS. */
export type IOSPaywallPresentationStyle = (typeof IOS_PAYWALL_PRESENTATION_STYLE)[keyof typeof IOS_PAYWALL_PRESENTATION_STYLE];
/** @see {@link IOSPaywallPresentationStyle} */
export declare const IOS_PAYWALL_PRESENTATION_STYLE: {
    /** Presents the paywall in full-screen mode. */
    readonly FULL_SCREEN: "FULL_SCREEN";
    /** Presents the paywall as a sheet. This is the default on iOS. */
    readonly SHEET: "SHEET";
};
/** Presentation styles available for paywalls on Android. */
export type AndroidPaywallPresentationStyle = (typeof ANDROID_PAYWALL_PRESENTATION_STYLE)[keyof typeof ANDROID_PAYWALL_PRESENTATION_STYLE];
/** @see {@link AndroidPaywallPresentationStyle} */
export declare const ANDROID_PAYWALL_PRESENTATION_STYLE: {
    /** Presents the paywall in full-screen mode. This is the default on Android. */
    readonly FULL_SCREEN: "FULL_SCREEN";
};
/**
 * Per-platform configuration for how a paywall is presented.
 * Use the convenience presets {@link PaywallPresentationConfiguration.FULL_SCREEN}
 * or {@link PaywallPresentationConfiguration.DEFAULT}, or provide a custom
 * configuration with per-platform styles.
 */
export interface PaywallPresentationConfiguration {
    /** Presentation style on iOS. Defaults to sheet if not specified. */
    ios?: IOSPaywallPresentationStyle;
    /** Presentation style on Android. Defaults to full-screen if not specified. */
    android?: AndroidPaywallPresentationStyle;
}
/** Convenience presets for {@link PaywallPresentationConfiguration}. */
export declare const PaywallPresentationConfiguration: {
    /** Full-screen presentation on all platforms. */
    readonly FULL_SCREEN: PaywallPresentationConfiguration;
    /** Default presentation: sheet on iOS, full-screen on Android. */
    readonly DEFAULT: PaywallPresentationConfiguration;
};
export interface PresentPaywallOptions {
    /**
     * The offering to present.
     * If not provided, the current offering will be used.
     */
    offering?: PurchasesOffering;
    /**
     * Controls how the paywall is presented on each platform.
     * Use `PaywallPresentationConfiguration.FULL_SCREEN` for full-screen on all platforms,
     * or provide a custom configuration with per-platform styles.
     * Defaults to sheet on iOS and full-screen on Android.
     */
    presentationConfiguration?: PaywallPresentationConfiguration;
    /**
     * Whether to display a close button on the paywall.
     * Only applicable for original template paywalls, ignored for V2 Paywalls.
     */
    displayCloseButton?: boolean;
    /**
     * Optional listener for paywall lifecycle events such as purchase
     * completion, restoration, and errors.
     */
    listener?: PaywallListener;
    /**
     * Optional custom purchase/restore logic for when
     * `purchasesAreCompletedBy` is set to `MY_APP`.
     */
    purchaseLogic?: PurchaseLogic;
    /**
     * Optional custom variables for paywall text substitution.
     * Variables can be referenced in paywalls using the `{{ custom.variable_name }}` syntax.
     * Keys must start with a letter and contain only alphanumeric characters and underscores.
     */
    customVariables?: Record<string, string | number | boolean>;
}
export interface PresentPaywallIfNeededOptions extends PresentPaywallOptions {
    /**
     * The identifier of the entitlement that is required.
     * The paywall will only be presented if the user doesn't have this entitlement.
     */
    requiredEntitlementIdentifier: string;
}
export { PAYWALL_RESULT as PaywallResultEnum };
export interface PaywallResult {
    /**
     * The result of the paywall presentation.
     */
    result: PAYWALL_RESULT;
}