feat(in-app-purchase-3): sync wrapper with cordova-plugin-purchase 13.18.0

Add missing v13.16-13.18 API surface (obfuscator, getStorefront, quantity
support, storefrontUpdated event, IAPTIC_JS platform) and fix pre-existing
type mismatches against upstream typings.

src/@awesome-cordova-plugins/plugins/background-fetch/index.ts

@@ -1,196 +1,18 @@
 import { Cordova, AwesomeCordovaNativePlugin, Plugin } from '@awesome-cordova-plugins/core';
 import { Injectable } from '@angular/core';
 
-/**
- * Authorization status of the Background Fetch API. Returned by `BackgroundFetch#configure` and `BackgroundFetch#status`.
- *
- * @since 7.0.0
- */
-export enum BackgroundFetchStatus {
-  /**
-   * Background fetch updates are unavailable and the user cannot enable them again.
-   * For example, this status can occur when parental controls are in effect for the current user.
-   */
-  STATUS_RESTRICTED = 0,
-  /**
-   * The user explicitly disabled background behavior for this app or for the whole system.
-   */
-  STATUS_DENIED = 1,
-  /**
-   * Background fetch is available and enabled.
-   */
-  STATUS_AVAILABLE = 2,
-}
-
-/**
- * [Android only] Network type constraint for scheduled tasks. Used with `BackgroundFetchConfig#requiredNetworkType`
- * and `BackgroundFetchTaskConfig#requiredNetworkType`.
- *
- * @since 7.0.0
- */
-export enum BackgroundFetchNetworkType {
-  /**
-   * No network constraint. The task will run regardless of network state.
-   */
-  NONE = 0,
-  /**
-   * The task requires any active network connection.
-   */
-  ANY = 1,
-  /**
-   * The task requires an unmetered (e.g. Wi-Fi) network connection.
-   */
-  UNMETERED = 2,
-  /**
-   * The task requires a non-roaming network connection.
-   */
-  NOT_ROAMING = 3,
-  /**
-   * The task requires a cellular (mobile data) network connection.
-   */
-  CELLULAR = 4,
-}
-
-/**
- * Configuration properties shared by both `BackgroundFetchConfig` and `BackgroundFetchTaskConfig`.
- *
- * Aside from `stopOnTerminate`, all properties are Android-only. iOS manages background execution
- * through its own system-controlled Background Fetch mechanism and does not support these constraints.
- */
-export interface BackgroundFetchAbstractConfig {
+export interface BackgroundFetchConfig {
   /**
    * Set true to cease background-fetch from operating after user "closes" the app. Defaults to true.
    */
   stopOnTerminate?: boolean;
-
-  /**
-   * [Android only] Set `true` to initiate background-fetch events when the device is rebooted. Defaults to `false`.
-   * NOTE: `startOnBoot` requires `stopOnTerminate: false`.
-   *
-   * @since 7.0.0
-   */
-  startOnBoot?: boolean;
-
-  /**
-   * [Android only] Set `true` to enable the Headless mechanism for handling fetch events after app termination.
-   * Defaults to `false`. NOTE: Requires `stopOnTerminate: false`.
-   *
-   * @since 7.0.0
-   */
-  enableHeadless?: boolean;
-
-  /**
-   * [Android only] By default, the plugin uses Android's `JobScheduler` when possible and falls back to
-   * `AlarmManager` for older devices. Set `true` to always use `AlarmManager` regardless of API level.
-   * Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  forceAlarmManager?: boolean;
-
-  /**
-   * [Android only] Specify the kind of network connectivity required to run this task. Defaults to
-   * `BackgroundFetchNetworkType.NONE`.
-   *
-   * @since 7.0.0
-   */
-  requiredNetworkType?: BackgroundFetchNetworkType;
-
-  /**
-   * [Android only] Set `true` to require the device's battery level to be above the "low battery" threshold
-   * before running this task. Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  requiresBatteryNotLow?: boolean;
-
-  /**
-   * [Android only] Set `true` to require the device's available storage to be above the "low storage"
-   * threshold before running this task. Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  requiresStorageNotLow?: boolean;
-
-  /**
-   * [Android only] Set `true` to require the device to be charging (or connected to permanent power, such
-   * as an Android TV device) before running this task. Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  requiresCharging?: boolean;
-
-  /**
-   * [Android only] Set `true` to require the device to be idle (not actively used) before running this task.
-   * Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  requiresDeviceIdle?: boolean;
-}
-
-export interface BackgroundFetchConfig extends BackgroundFetchAbstractConfig {
-  /**
-   * The minimum interval in **minutes** between background-fetch events. Defaults to `15` minutes. The
-   * minimum allowed value is `15` minutes.
-   *
-   * NOTE: The OS does not guarantee fetch events will fire at exactly this interval. iOS adjusts the
-   * interval based on usage patterns and system conditions. This value is a *minimum*, not a schedule.
-   *
-   * @since 7.0.0
-   */
-  minimumFetchInterval?: number;
-}
-
-/**
- * Configuration for a custom scheduled task, provided to `BackgroundFetch#scheduleTask`.
- *
- * @since 7.0.0
- */
-export interface BackgroundFetchTaskConfig extends BackgroundFetchAbstractConfig {
-  /**
-   * A unique identifier for this task. Use the same `taskId` with `BackgroundFetch#finish` to signal
-   * completion and with `BackgroundFetch#stopTask` to cancel it. Use reverse-domain notation to avoid
-   * collisions (e.g. `'com.foo.sync'`).
-   */
-  taskId: string;
-
-  /**
-   * The minimum delay in **milliseconds** before this task runs.
-   *
-   * NOTE: On iOS, the system may delay the task beyond this value depending on device conditions. On
-   * Android, `JobScheduler` treats this as a minimum delay.
-   */
-  delay: number;
-
-  /**
-   * Set `true` to schedule a repeating task. Defaults to `false` (one-shot).
-   */
-  periodic?: boolean;
-
-  /**
-   * [iOS only] Set `true` to require a network connection before running this task. On Android, use
-   * `requiredNetworkType` instead.
-   */
-  requiresNetworkConnectivity?: boolean;
 }
 
 /**
  * @name Background Fetch
  * @description
- * Cross-platform Background Fetch implementation. This plugin will execute your provided callbackFn
- * whenever a background-fetch event occurs.
- *
- * ### iOS
- * There is no way to increase the rate which a fetch-event occurs and this plugin sets the rate to the
- * most frequent possible value -- iOS determines the rate automatically based upon device usage and
- * time-of-day (ie: fetch-rate is about ~15min during prime-time hours; less frequently when the user is
- * presumed to be sleeping).
- *
- * ### Android
- * Uses `JobScheduler` (API 21+) or `AlarmManager` to schedule periodic callbacks. Additional constraints
- * (network, charging, idle) can be set via `BackgroundFetchConfig`.
- *
+ * iOS Background Fetch Implementation. See: https://developer.apple.com/reference/uikit/uiapplication#1657399
+ * iOS Background Fetch is basically an API which wakes up your app about every 15 minutes (during the user's prime-time hours) and provides your app exactly 30s of background running-time. This plugin will execute your provided callbackFn whenever a background-fetch event occurs. There is no way to increase the rate which a fetch-event occurs and this plugin sets the rate to the most frequent possible value of UIApplicationBackgroundFetchIntervalMinimum -- iOS determines the rate automatically based upon device usage and time-of-day (ie: fetch-rate is about ~15min during prime-time hours; less frequently when the user is presumed to be sleeping, at 3am for example).
  * For more detail, please see https://github.com/transistorsoft/cordova-plugin-background-fetch
  * @usage
  *
@@ -201,23 +23,17 @@ export interface BackgroundFetchTaskConfig extends BackgroundFetchAbstractConfig
  * constructor(private backgroundFetch: BackgroundFetch) {
  *
  *   const config: BackgroundFetchConfig = {
- *     minimumFetchInterval: 15,
  *     stopOnTerminate: false, // Set true to cease background-fetch from operating after user "closes" the app. Defaults to true.
  *   }
  *
- *   backgroundFetch.configure(config, (taskId: string) => {
+ *   backgroundFetch.configure(config)
+ *      .then(() => {
+ *          console.log('Background Fetch initialized');
  *
- *          console.log('Background Fetch event received', taskId);
+ *          this.backgroundFetch.finish();
  *
- *          this.backgroundFetch.finish(taskId);
- *
- *   }, (taskId: string) => {
- *          // OS has signalled that remaining background time is about to expire.
- *          console.log('Background Fetch TIMEOUT', taskId);
- *          this.backgroundFetch.finish(taskId);
- *   }).then((status) => {
- *          console.log('Background Fetch initialized', status);
- *   }).catch(e => console.log('Error initializing background fetch', e));
+ *      })
+ *      .catch(e => console.log('Error initializing background fetch', e));
  *
  *   // Start the background-fetch API. Your callbackFn provided to #configure will be executed each time a background-fetch event occurs. NOTE the #configure method automatically calls #start. You do not have to call this method after you #configure the plugin
  *   backgroundFetch.start();
@@ -231,38 +47,26 @@ export interface BackgroundFetchTaskConfig extends BackgroundFetchAbstractConfig
  * ```
  * @interfaces
  * BackgroundFetchConfig
- * BackgroundFetchTaskConfig
  */
 @Plugin({
   pluginName: 'BackgroundFetch',
   plugin: 'cordova-plugin-background-fetch',
   pluginRef: 'BackgroundFetch',
   repo: 'https://github.com/transistorsoft/cordova-plugin-background-fetch',
-  platforms: ['Android', 'iOS'],
+  platforms: ['iOS'],
 })
 @Injectable()
 export class BackgroundFetch extends AwesomeCordovaNativePlugin {
   /**
-   * Configures the plugin's fetch callbackFn.
-   *
-   * Calling `configure` automatically starts background-fetch (equivalent to calling `#start` immediately
-   * after configuration).
+   * Configures the plugin's fetch callbackFn
    *
    * @param {BackgroundFetchConfig} config Configuration for plugin
-   * @param {Function} [onEvent] Callback fired when a background-fetch event is received. The `taskId`
-   * string identifies which task fired -- pass it to `#finish` when done. Required as of plugin `7.0.0`.
-   * @param {Function} [onTimeout] Callback fired when the OS signals that remaining background time is
-   * about to expire. Call `#finish` immediately. Added in plugin `7.0.0`.
    * @returns {Promise<any>}
    */
   @Cordova({
-    otherPromise: true,
+    callbackOrder: 'reverse',
   })
-  configure(
-    config: BackgroundFetchConfig,
-    onEvent?: (taskId: string) => void,
-    onTimeout?: (taskId: string) => void
-  ): Promise<any> {
+  configure(config: BackgroundFetchConfig): Promise<any> {
     return;
   }
 
@@ -306,33 +110,4 @@ export class BackgroundFetch extends AwesomeCordovaNativePlugin {
   status(): Promise<any> {
     return;
   }
-
-  /**
-   * Schedule a custom one-shot or periodic background task in addition to the default fetch callback
-   * registered with `#configure`.
-   *
-   * Custom tasks fire the same callback registered via `#configure`'s `onEvent` argument, with their
-   * unique `taskId`. Use `#finish` with that `taskId` to signal completion.
-   *
-   * @param {BackgroundFetchTaskConfig} config Task configuration, including a unique `taskId` and a
-   * minimum `delay` in milliseconds.
-   * @returns {Promise<any>}
-   * @since 7.0.0
-   */
-  @Cordova()
-  scheduleTask(config: BackgroundFetchTaskConfig): Promise<any> {
-    return;
-  }
-
-  /**
-   * Cancel a specific task previously scheduled via `#scheduleTask`, identified by its `taskId`.
-   *
-   * @param taskId The identifier of the scheduled task to stop.
-   * @returns {Promise<any>}
-   * @since 7.0.0
-   */
-  @Cordova()
-  stopTask(taskId: string): Promise<any> {
-    return;
-  }
 }

src/@awesome-cordova-plugins/plugins/in-app-purchase-3/index.ts

@@ -14,6 +14,14 @@ export interface IAPAdapter {
 
   isSupported: boolean;
 
+  /**
+   * Returns true if the adapter can skip the native finish method for a transaction.
+   *
+   * Some platforms (e.g. Apple AppStore) require explicit acknowledgement of a purchase so it can be removed from
+   * the queue of pending transactions, regardless of whether the transaction is acknowledged or consumed already.
+   */
+  canSkipFinish?: boolean;
+
   initialize(): Promise<IAPError | undefined>;
 
   loadProducts(products: IAPProductOptions[]): Promise<(IAPProduct | IAPError)[]>;
@@ -31,7 +39,7 @@ export interface IAPAdapter {
   handleReceiptValidationResponse(receipt: IAPReceipt, response: object): Promise<void>;
 
   requestPayment(
-    payment: PaymentRequest,
+    payment: IAPPaymentRequest,
     additionalData?: IAPAdditionalData
   ): Promise<IAPError | IAPTransaction | undefined>;
 
@@ -42,6 +50,14 @@ export interface IAPAdapter {
   checkSupport(functionality: string): boolean;
 
   restorePurchases(): Promise<IAPError | undefined>;
+
+  /**
+   * Retrieve the billing country code from the platform's storefront.
+   *
+   * Returns an ISO 3166-1 alpha-2 country code (e.g., "US", "FR"),
+   * or undefined if the storefront information is not available.
+   */
+  getStorefront?(): Promise<string | undefined>;
 }
 
 export interface IAPProductOptions {
@@ -59,9 +75,26 @@ export interface IAPProductOptions {
  * @see {@link InAppPurchase3.requestPayment}
  */
 export interface IAPAdditionalData {
-  /** The application's user identifier, will be obfuscated with md5 to fill `accountId` if necessary */
+  /**
+   * The application's user identifier, will be obfuscated with md5 to fill `accountId` if necessary
+   *
+   * @deprecated Set {@link InAppPurchase3.applicationUsername} instead. The per-transaction value is
+   * ignored by upstream adapters, which always read the store-level username so receipt validation later
+   * (which doesn't have access to the original additionalData) sees the same value that was sent to the
+   * native API at purchase time.
+   */
   applicationUsername?: string;
 
+  /**
+   * Quantity of items to purchase.
+   *
+   * Only supported on platforms that report the `'orderQuantity'` capability.
+   * Platforms without support will ignore this field.
+   *
+   * @see {@link InAppPurchase3.checkSupport}
+   */
+  quantity?: number;
+
   /** GooglePlay specific additional data. See cordova-plugin-purchase documentation.*/
   googlePlay?: object;
 
@@ -127,9 +160,10 @@ export interface IAPPricingPhase {
 
   priceMicros: number;
 
-  currency: string;
+  currency?: string;
 
-  billingPeriod?: number;
+  /** ISO 8601 duration of the period (https://en.wikipedia.org/wiki/ISO_8601#Durations) */
+  billingPeriod?: string;
 
   billingCycles?: number;
 
@@ -205,6 +239,17 @@ export interface IAPTransaction {
 
   currency?: string;
 
+  /**
+   * Quantity of items purchased in a single transaction.
+   *
+   * For consumable products, this value represents the number of items purchased.
+   * For non-consumable products and subscriptions, this value is always 1.
+   *
+   * Supported on Android (Google Play) and iOS (Apple AppStore).
+   * Use `additionalData.quantity` when placing an order to purchase multiple units in a single transaction.
+   */
+  quantity?: number;
+
   products: { id: string; offerId?: string }[];
 
   /**
@@ -243,12 +288,21 @@ export interface IAPVerifiedPurchase {
 
   purchaseId?: string;
 
+  /** Identifier of the last transaction (optional) */
+  transactionId?: string;
+
   purchaseDate?: number;
 
   expiryDate?: number;
 
   isExpired?: boolean;
 
+  /** True when a purchase has been acknowledged to the platform. */
+  isAcknowledged?: boolean;
+
+  /** True when a purchase has been consumed (for consumable products). */
+  isConsumed?: boolean;
+
   renewalIntent?: string;
 
   renewalIntentChangeDate?: number;
@@ -266,6 +320,14 @@ export interface IAPVerifiedPurchase {
   priceConsentStatus?: PriceConsentStatus;
 
   lastRenewalDate?: number;
+
+  /**
+   * Quantity of items purchased in a single transaction.
+   *
+   * For consumable products, this value represents the number of items purchased.
+   * For non-consumable products and subscriptions, this value is always 1.
+   */
+  quantity?: number;
 }
 
 export interface IAPProductEvents {
@@ -321,6 +383,17 @@ export interface IAPProductEvents {
    * If no platforms have any receipts (user made no purchase), this will also get called.
    */
   receiptsVerified(cb: Callback<void>, callbackName?: string): IAPProductEvents;
+
+  /**
+   * Register a function called when a platform's storefront country code changes.
+   *
+   * Fires when a platform's cached value transitions to a different non-empty
+   * string. Does not fire for no-op refreshes, failed refreshes, or transitions
+   * to undefined (the cache preserves the last-known value).
+   *
+   * @param cb - Callback invoked with the updated {@link IAPStorefront}
+   */
+  storefrontUpdated(cb: Callback<IAPStorefront>, callbackName?: string): IAPProductEvents;
 }
 
 export interface IAPPaymentRequest {
@@ -371,6 +444,67 @@ export interface IAPPaymentRequest {
   };
 }
 
+/**
+ * Result of a call to {@link InAppPurchase3.requestPayment}.
+ *
+ * A chainable set of event registration methods, each returning the same instance.
+ *
+ * @example
+ * store.requestPayment(paymentRequest)
+ *   .cancelled(() => { // user cancelled by closing the window
+ *   })
+ *   .failed(error => { // payment request failed
+ *   })
+ *   .initiated(transaction => { // transaction initiated
+ *   })
+ *   .approved(transaction => { // transaction approved
+ *   })
+ *   .finished(transaction => { // transaction finished
+ *   });
+ */
+export interface IAPPaymentRequestPromise {
+  /** Register a function called when the payment request failed. */
+  failed(callback: Callback<IAPError>): IAPPaymentRequestPromise;
+
+  /** Register a function called when the payment request has been initiated. */
+  initiated(callback: Callback<IAPTransaction>): IAPPaymentRequestPromise;
+
+  /** Register a function called when the payment request has been approved. */
+  approved(callback: Callback<IAPTransaction>): IAPPaymentRequestPromise;
+
+  /** Register a function called when the payment request has been finished. */
+  finished(callback: Callback<IAPTransaction>): IAPPaymentRequestPromise;
+
+  /** Register a function called when the payment request was cancelled by the user. */
+  cancelled(callback: Callback<void>): IAPPaymentRequestPromise;
+}
+
+/**
+ * A storefront country code, scoped to a specific payment platform.
+ *
+ * @see {@link InAppPurchase3.getStorefront}
+ */
+export interface IAPStorefront {
+  /** The platform this storefront belongs to. */
+  platform: Platform;
+
+  /**
+   * ISO 3166-1 alpha-2 country code (e.g., "US", "FR").
+   *
+   * Undefined if the value has not been fetched yet, or if the fetch failed.
+   */
+  countryCode?: string;
+}
+
+/**
+ * Obfuscation strategy for the application username.
+ *
+ * Controls how `applicationUsername` is transformed before being sent to each platform's native API.
+ *
+ * @see {@link InAppPurchase3.obfuscator}
+ */
+export type Obfuscator = 'legacy' | 'uuid' | 'disabled' | ((applicationUsername: string, platform: Platform) => string);
+
 /**
  * Purchase platforms supported by the plugin
  */
@@ -392,6 +526,9 @@ export enum Platform {
 
   /** Test platform */
   TEST = 'test',
+
+  /** Iaptic.js */
+  IAPTIC_JS = 'iaptic-js',
 }
 
 /** Types of In-App Products */
@@ -512,11 +649,91 @@ export enum LogLevel {
   DEBUG = 4,
 }
 
+/**
+ * Error codes returned by the plugin.
+ *
+ * @see {@link IAPError.code}
+ * @see https://github.com/j3k0/cordova-plugin-purchase/blob/master/doc/api.md#error-codes
+ */
+export enum ErrorCode {
+  /** Error: Failed to intialize the in-app purchase library */
+  SETUP,
+  /** Error: Failed to load in-app products metadata */
+  LOAD,
+  /** Error: Failed to make a purchase */
+  PURCHASE,
+  /** Error: Failed to load the purchase receipt */
+  LOAD_RECEIPTS,
+  /** Error: Client is not allowed to issue the request */
+  CLIENT_INVALID,
+  /** Error: Purchase flow has been cancelled by user */
+  PAYMENT_CANCELLED,
+  /** Error: Something is suspicious about a purchase */
+  PAYMENT_INVALID,
+  /** Error: The user is not allowed to make a payment */
+  PAYMENT_NOT_ALLOWED,
+  /** Error: Unknown error */
+  UNKNOWN,
+  /** Error: Failed to refresh the purchase receipt */
+  REFRESH_RECEIPTS,
+  /** Error: The product identifier is invalid */
+  INVALID_PRODUCT_ID,
+  /** Error: Cannot finalize a transaction or acknowledge a purchase */
+  FINISH,
+  /** Error: Failed to communicate with the server */
+  COMMUNICATION,
+  /** Error: Subscriptions are not available */
+  SUBSCRIPTIONS_NOT_AVAILABLE,
+  /** Error: Purchase information is missing token */
+  MISSING_TOKEN,
+  /** Error: Verification of store data failed */
+  VERIFICATION_FAILED,
+  /** Error: Bad response from the server */
+  BAD_RESPONSE,
+  /** Error: Failed to refresh the store */
+  REFRESH,
+  /** Error: Payment has expired */
+  PAYMENT_EXPIRED,
+  /** Error: Failed to download the content */
+  DOWNLOAD,
+  /** Error: Failed to update a subscription */
+  SUBSCRIPTION_UPDATE_NOT_AVAILABLE,
+  /** Error: The requested product is not available in the store. */
+  PRODUCT_NOT_AVAILABLE,
+  /** Error: The user has not allowed access to Cloud service information */
+  CLOUD_SERVICE_PERMISSION_DENIED,
+  /** Error: The device could not connect to the network. */
+  CLOUD_SERVICE_NETWORK_CONNECTION_FAILED,
+  /** Error: The user has revoked permission to use this cloud service. */
+  CLOUD_SERVICE_REVOKED,
+  /** Error: The user has not yet acknowledged Apple's privacy policy */
+  PRIVACY_ACKNOWLEDGEMENT_REQUIRED,
+  /** Error: The app is attempting to use a property for which it does not have the required entitlement. */
+  UNAUTHORIZED_REQUEST_DATA,
+  /** Error: The offer identifier is invalid. */
+  INVALID_OFFER_IDENTIFIER,
+  /** Error: The price you specified in App Store Connect is no longer valid. */
+  INVALID_OFFER_PRICE,
+  /** Error: The signature in a payment discount is not valid. */
+  INVALID_SIGNATURE,
+  /** Error: Parameters are missing in a payment discount. */
+  MISSING_OFFER_PARAMS,
+  /** Error: The store is blocked (e.g. Google Play blocking purchases). */
+  STORE_BLOCKED,
+  /**
+   * Server code used when a subscription expired.
+   *
+   * @deprecated Validator should now return the transaction in the collection as expired.
+   */
+  VALIDATOR_SUBSCRIPTION_EXPIRED = 6778003,
+}
+
 /**
  * @hidden
  */
 export class IAPError {
   isError: true;
+  /** @see {@link ErrorCode} */
   code: number;
   message: string;
   platform: Platform | null;
@@ -874,6 +1091,8 @@ export class IAPError {
  * IAPVerifiedPurchase
  * IAPProductEvents
  * IAPPaymentRequest
+ * IAPPaymentRequestPromise
+ * IAPStorefront
  * ```
  */
 @Plugin({
@@ -914,18 +1133,38 @@ export class InAppPurchase3 extends AwesomeCordovaNativePlugin {
   @CordovaProperty()
   verbosity: number;
 
-  /** Return the identifier of the user for your application */
+  /**
+   * Return the identifier of the user for your application.
+   *
+   * This value is obfuscated according to {@link InAppPurchase3.obfuscator} before being
+   * sent to the native platform API.
+   */
   @CordovaProperty()
-  applicationUsername: string | (() => string);
+  applicationUsername: string | (() => string | undefined) | undefined;
 
   /**
    * Get the application username as a string by either calling or returning {@link InAppPurchase3.applicationUsername}
    */
   @Cordova({ sync: true })
-  getApplicationUsername(): string {
+  getApplicationUsername(): string | undefined {
     return;
   }
 
+  /**
+   * Obfuscation strategy for the application username.
+   *
+   * Controls how `applicationUsername` is transformed before being sent
+   * to each platform's native API. `'uuid'` is the recommended setting
+   * for new integrations; the default `'legacy'` exists only for
+   * backward compatibility with server-side modules that already
+   * correlate against the raw 32-hex MD5 value.
+   *
+   * @default 'legacy'
+   * @see {@link Obfuscator}
+   */
+  @CordovaProperty()
+  obfuscator: Obfuscator | undefined;
+
   /**
    * URL or implementation of the receipt validation service
    *
@@ -971,12 +1210,7 @@ export class InAppPurchase3 extends AwesomeCordovaNativePlugin {
    */
   @CordovaProperty()
   validator_privacy_policy:
-    | 'fraud'
-    | 'support'
-    | 'analytics'
-    | 'tracking'
-    | ('fraud' | 'support' | 'analytics' | 'tracking')[]
-    | undefined;
+    'fraud' | 'support' | 'analytics' | 'tracking' | ('fraud' | 'support' | 'analytics' | 'tracking')[] | undefined;
 
   /**
    * Register a product.
@@ -1003,10 +1237,10 @@ export class InAppPurchase3 extends AwesomeCordovaNativePlugin {
    * Call to initialize the in-app purchase plugin.
    *
    * @param platforms - List of payment platforms to initialize, default to Store.defaultPlatform().
-   * @returns {Promise<IAPError | undefined>}
+   * @returns {Promise<IAPError[]>}
    */
   @Cordova({ sync: true })
-  initialize(platforms: (Platform | { platform: Platform; options?: object })[]): Promise<IAPError | undefined> {
+  initialize(platforms?: (Platform | { platform: Platform; options?: object })[]): Promise<IAPError[]> {
     return;
   }
 
@@ -1170,7 +1404,7 @@ export class InAppPurchase3 extends AwesomeCordovaNativePlugin {
    * @param {IAPAdditionalData?} additionalData Additional parameters
    */
   @Cordova({ sync: false })
-  requestPayment(paymentRequest: IAPPaymentRequest, additionalData?: IAPAdditionalData): object {
+  requestPayment(paymentRequest: IAPPaymentRequest, additionalData?: IAPAdditionalData): IAPPaymentRequestPromise {
     return;
   }
 
@@ -1222,9 +1456,34 @@ export class InAppPurchase3 extends AwesomeCordovaNativePlugin {
    * @example
    * if (purchase.isBillingRetryPeriod)
    *     store.manageBilling(purchase.platform);
+   * @param {Platform?} platform
    */
   @Cordova({ sync: false })
-  manageBilling(): Promise<IAPError | undefined> {
+  manageBilling(platform?: Platform): Promise<IAPError | undefined> {
+    return;
+  }
+
+  /**
+   * Retrieve the billing country code from the platform's storefront.
+   *
+   * Returns a `IAPStorefront` object with the platform and its ISO 3166-1
+   * alpha-2 country code (e.g., "US", "FR"). The country code may be
+   * undefined if the underlying fetch has not yet completed or failed —
+   * the platform is still reported. Returns `undefined` only when no
+   * matching adapter is ready.
+   *
+   * @param platform - Optional platform. If omitted, returns the first
+   *                   cached non-empty storefront, or a `{ platform, countryCode: undefined }`
+   *                   object for the first ready adapter.
+   *
+   * @example
+   * const storefront = store.getStorefront();
+   * if (storefront?.countryCode) {
+   *     console.log(`Billing country: ${storefront.countryCode}`);
+   * }
+   */
+  @Cordova({ sync: true })
+  getStorefront(platform?: Platform): IAPStorefront | undefined {
     return;
   }