@capgo/native-purchases 7.14.0 → 7.15.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Martin Donadieu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1571,23 +1571,35 @@ This allows users to view, modify, or cancel their subscriptions.
 acknowledgePurchase(options: { purchaseToken: string; }) => Promise<void>
 ```
 
-Manually acknowledge a purchase on Android.
+Manually acknowledge/finish a purchase transaction.
 
 This method is only needed when you set `autoAcknowledgePurchases: false` in purchaseProduct().
-Purchases MUST be acknowledged within 3 days or they will be automatically refunded by Google Play.
+
+**Platform Behavior:**
+- **Android**: Acknowledges the purchase with Google Play. Must be called within 3 days or the purchase will be refunded.
+- **iOS**: Finishes the transaction with StoreKit 2. Unfinished transactions remain in the queue and may block future purchases.
 
 **Acknowledgment Options:**
-1. **Client-side (this method)**: Call from your app after validation
-2. **Server-side (recommended for security)**: Use Google Play Developer API v3
-   - Endpoint: POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge
-   - Requires OAuth 2.0 authentication with appropriate scopes
-   - See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge
 
-When to use manual acknowledgment:
+**1. Client-side (this method)**: Call from your app after validation
+```typescript
+await NativePurchases.acknowledgePurchase({
+  purchaseToken: transaction.purchaseToken  // Android: purchaseToken, iOS: transactionId
+});
+```
+
+**2. Server-side (Android only, recommended for security)**: Use Google Play Developer API v3
+- Endpoint: `POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge`
+- Requires OAuth 2.0 authentication with appropriate scopes
+- See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge
+- For subscriptions: Use `/purchases/subscriptions/{subscriptionId}/tokens/{token}:acknowledge` instead
+- Note: iOS has no server-side finish API
+
+**When to use manual acknowledgment:**
 - Server-side validation: Verify the purchase with your backend before acknowledging
 - Entitlement delivery: Ensure user receives content/features before acknowledging
 - Multi-step workflows: Complete all steps before final acknowledgment
-- Security: Prevent client-side manipulation by handling acknowledgment server-side
+- Security: Prevent client-side manipulation by handling acknowledgment server-side (Android only)
 
 | Param         | Type                                    | Description                   |
 | ------------- | --------------------------------------- | ----------------------------- |

package/android/src/main/java/ee/forgr/nativepurchases/NativePurchasesPlugin.java

@@ -39,7 +39,7 @@ import org.json.JSONArray;
 @CapacitorPlugin(name = "NativePurchases")
 public class NativePurchasesPlugin extends Plugin {
 
-    private final String pluginVersion = "7.14.0";
+    private final String pluginVersion = "7.15.1";
     public static final String TAG = "NativePurchases";
     private static final Phaser semaphoreReady = new Phaser(1);
     private BillingClient billingClient;

package/dist/docs.json

@@ -57,7 +57,7 @@
           },
           {
             "name": "param",
-            "text": "options.autoAcknowledgePurchases - Only Android, when false the purchase will NOT be automatically acknowledged. You must manually call acknowledgePurchase() within 3 days or the purchase will be refunded. Defaults to true."
+            "text": "options.autoAcknowledgePurchases - When false, the purchase/transaction will NOT be automatically acknowledged/finished. You must manually call acknowledgePurchase() or the purchase may be refunded. Defaults to true.\n  - **Android**: Must acknowledge within 3 days or Google Play will refund\n  - **iOS**: Unfinished transactions remain in the queue and may block future purchases"
           }
         ],
         "docs": "Started purchase process for the given product.",
@@ -253,19 +253,23 @@
           },
           {
             "name": "param",
-            "text": "options.purchaseToken - The purchase token from the Transaction object (Android)"
+            "text": "options.purchaseToken - The purchase token (Android) or transaction ID as string (iOS) from the Transaction object"
           },
           {
             "name": "returns",
-            "text": "Promise that resolves when the purchase is acknowledged"
+            "text": "Promise that resolves when the purchase is acknowledged/finished"
           },
           {
             "name": "throws",
-            "text": "An error if acknowledgment fails"
+            "text": "An error if acknowledgment/finishing fails or transaction not found"
           },
           {
             "name": "platform",
-            "text": "android Only available on Android (iOS automatically finishes transactions)"
+            "text": "android Acknowledges the purchase with Google Play"
+          },
+          {
+            "name": "platform",
+            "text": "ios Finishes the transaction with StoreKit 2"
           },
           {
             "name": "since",
@@ -276,7 +280,7 @@
             "text": "```typescript\n// Client-side acknowledgment\nconst transaction = await NativePurchases.purchaseProduct({\n  productIdentifier: 'premium_feature',\n  autoAcknowledgePurchases: false\n});\n\n// Validate with your backend\nconst isValid = await fetch('/api/validate-purchase', {\n  method: 'POST',\n  body: JSON.stringify({ purchaseToken: transaction.purchaseToken })\n});\n\nif (isValid) {\n  // Option 1: Acknowledge from client\n  await NativePurchases.acknowledgePurchase({\n    purchaseToken: transaction.purchaseToken\n  });\n\n  // Option 2: Or let your backend acknowledge via Google Play API\n  // Your backend calls Google Play Developer API\n}\n```"
           }
         ],
-        "docs": "Manually acknowledge a purchase on Android.\n\nThis method is only needed when you set `autoAcknowledgePurchases: false` in purchaseProduct().\nPurchases MUST be acknowledged within 3 days or they will be automatically refunded by Google Play.\n\n**Acknowledgment Options:**\n1. **Client-side (this method)**: Call from your app after validation\n2. **Server-side (recommended for security)**: Use Google Play Developer API v3\n   - Endpoint: POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge\n   - Requires OAuth 2.0 authentication with appropriate scopes\n   - See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge\n\nWhen to use manual acknowledgment:\n- Server-side validation: Verify the purchase with your backend before acknowledging\n- Entitlement delivery: Ensure user receives content/features before acknowledging\n- Multi-step workflows: Complete all steps before final acknowledgment\n- Security: Prevent client-side manipulation by handling acknowledgment server-side",
+        "docs": "Manually acknowledge/finish a purchase transaction.\n\nThis method is only needed when you set `autoAcknowledgePurchases: false` in purchaseProduct().\n\n**Platform Behavior:**\n- **Android**: Acknowledges the purchase with Google Play. Must be called within 3 days or the purchase will be refunded.\n- **iOS**: Finishes the transaction with StoreKit 2. Unfinished transactions remain in the queue and may block future purchases.\n\n**Acknowledgment Options:**\n\n**1. Client-side (this method)**: Call from your app after validation\n```typescript\nawait NativePurchases.acknowledgePurchase({\n  purchaseToken: transaction.purchaseToken  // Android: purchaseToken, iOS: transactionId\n});\n```\n\n**2. Server-side (Android only, recommended for security)**: Use Google Play Developer API v3\n- Endpoint: `POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge`\n- Requires OAuth 2.0 authentication with appropriate scopes\n- See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge\n- For subscriptions: Use `/purchases/subscriptions/{subscriptionId}/tokens/{token}:acknowledge` instead\n- Note: iOS has no server-side finish API\n\n**When to use manual acknowledgment:**\n- Server-side validation: Verify the purchase with your backend before acknowledging\n- Entitlement delivery: Ensure user receives content/features before acknowledging\n- Multi-step workflows: Complete all steps before final acknowledgment\n- Security: Prevent client-side manipulation by handling acknowledgment server-side (Android only)",
         "complexTypes": [],
         "slug": "acknowledgepurchase"
       },

package/dist/esm/definitions.d.ts

@@ -586,7 +586,9 @@ export interface NativePurchasesPlugin {
      *                                  SECURITY: DO NOT use PII like emails in cleartext - use UUID or hashed value.
      *                                  RECOMMENDED: Use UUID v5 with deterministic generation for cross-platform compatibility.
      * @param options.isConsumable - Only Android, when true the purchase token is consumed after granting entitlement (for consumable in-app items). Defaults to false.
-     * @param options.autoAcknowledgePurchases - Only Android, when false the purchase will NOT be automatically acknowledged. You must manually call acknowledgePurchase() within 3 days or the purchase will be refunded. Defaults to true.
+     * @param options.autoAcknowledgePurchases - When false, the purchase/transaction will NOT be automatically acknowledged/finished. You must manually call acknowledgePurchase() or the purchase may be refunded. Defaults to true.
+     *                                           - **Android**: Must acknowledge within 3 days or Google Play will refund
+     *                                           - **iOS**: Unfinished transactions remain in the queue and may block future purchases
      */
     purchaseProduct(options: {
         productIdentifier: string;
@@ -674,29 +676,42 @@ export interface NativePurchasesPlugin {
      */
     manageSubscriptions(): Promise<void>;
     /**
-     * Manually acknowledge a purchase on Android.
+     * Manually acknowledge/finish a purchase transaction.
      *
      * This method is only needed when you set `autoAcknowledgePurchases: false` in purchaseProduct().
-     * Purchases MUST be acknowledged within 3 days or they will be automatically refunded by Google Play.
+     *
+     * **Platform Behavior:**
+     * - **Android**: Acknowledges the purchase with Google Play. Must be called within 3 days or the purchase will be refunded.
+     * - **iOS**: Finishes the transaction with StoreKit 2. Unfinished transactions remain in the queue and may block future purchases.
      *
      * **Acknowledgment Options:**
-     * 1. **Client-side (this method)**: Call from your app after validation
-     * 2. **Server-side (recommended for security)**: Use Google Play Developer API v3
-     *    - Endpoint: POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge
-     *    - Requires OAuth 2.0 authentication with appropriate scopes
-     *    - See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge
      *
-     * When to use manual acknowledgment:
+     * **1. Client-side (this method)**: Call from your app after validation
+     * ```typescript
+     * await NativePurchases.acknowledgePurchase({
+     *   purchaseToken: transaction.purchaseToken  // Android: purchaseToken, iOS: transactionId
+     * });
+     * ```
+     *
+     * **2. Server-side (Android only, recommended for security)**: Use Google Play Developer API v3
+     * - Endpoint: `POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge`
+     * - Requires OAuth 2.0 authentication with appropriate scopes
+     * - See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge
+     * - For subscriptions: Use `/purchases/subscriptions/{subscriptionId}/tokens/{token}:acknowledge` instead
+     * - Note: iOS has no server-side finish API
+     *
+     * **When to use manual acknowledgment:**
      * - Server-side validation: Verify the purchase with your backend before acknowledging
      * - Entitlement delivery: Ensure user receives content/features before acknowledging
      * - Multi-step workflows: Complete all steps before final acknowledgment
-     * - Security: Prevent client-side manipulation by handling acknowledgment server-side
+     * - Security: Prevent client-side manipulation by handling acknowledgment server-side (Android only)
      *
      * @param options - The purchase to acknowledge
-     * @param options.purchaseToken - The purchase token from the Transaction object (Android)
-     * @returns {Promise<void>} Promise that resolves when the purchase is acknowledged
-     * @throws An error if acknowledgment fails
-     * @platform android Only available on Android (iOS automatically finishes transactions)
+     * @param options.purchaseToken - The purchase token (Android) or transaction ID as string (iOS) from the Transaction object
+     * @returns {Promise<void>} Promise that resolves when the purchase is acknowledged/finished
+     * @throws An error if acknowledgment/finishing fails or transaction not found
+     * @platform android Acknowledges the purchase with Google Play
+     * @platform ios Finishes the transaction with StoreKit 2
      * @since 7.14.0
      *
      * @example

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAEA,MAAM,CAAN,IAAY,mBAOX;AAPD,WAAY,mBAAmB;IAC7B,qFAAoB,CAAA;IACpB,iEAAU,CAAA;IACV,uEAAa,CAAA;IACb,iEAAU,CAAA;IACV,iEAAU,CAAA;IACV,qEAAY,CAAA;AACd,CAAC,EAPW,mBAAmB,KAAnB,mBAAmB,QAO9B;AAED,MAAM,CAAN,IAAY,aAUX;AAVD,WAAY,aAAa;IACvB;;OAEG;IACH,gCAAe,CAAA;IAEf;;OAEG;IACH,8BAAa,CAAA;AACf,CAAC,EAVW,aAAa,KAAb,aAAa,QAUxB;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAyBX;AAzBD,WAAY,eAAe;IACzB;;OAEG;IACH,uEAAa,CAAA;IAEb;;OAEG;IACH,qFAAoB,CAAA;IAEpB;;OAEG;IACH,iFAAkB,CAAA;IAElB;;OAEG;IACH,mFAAmB,CAAA;IAEnB;;OAEG;IACH,+FAAyB,CAAA;AAC3B,CAAC,EAzBW,eAAe,KAAf,eAAe,QAyB1B;AACD,MAAM,CAAN,IAAY,cA2BX;AA3BD,WAAY,cAAc;IACxB,qIAAiD,CAAA;IAEjD;;;OAGG;IACH,qGAAiC,CAAA;IAEjC;;;;OAIG;IACH,iHAAuC,CAAA;IAEvC;;;OAGG;IACH,iGAA+B,CAAA;IAE/B;;;OAGG;IACH,2DAAY,CAAA;AACd,CAAC,EA3BW,cAAc,KAAd,cAAc,QA2BzB;AAED,MAAM,CAAN,IAAY,YA6CX;AA7CD,WAAY,YAAY;IACtB;;OAEG;IACH,mCAAmB,CAAA;IAEnB;;OAEG;IACH,iCAAiB,CAAA;IAEjB;;OAEG;IACH,qCAAqB,CAAA;IAErB;;OAEG;IACH,iCAAiB,CAAA;IAEjB;;OAEG;IACH,uCAAuB,CAAA;IAEvB;;OAEG;IACH,2CAA2B,CAAA;IAE3B;;OAEG;IACH,uCAAuB,CAAA;IAEvB;;OAEG;IACH,mCAAmB,CAAA;IAEnB;;OAEG;IACH,iCAAiB,CAAA;AACnB,CAAC,EA7CW,YAAY,KAAZ,YAAY,QA6CvB;AAED,MAAM,CAAN,IAAY,wBAaX;AAbD,WAAY,wBAAwB;IAClC;;OAEG;IACH,+HAAoC,CAAA;IACpC;;OAEG;IACH,qIAAmC,CAAA;IACnC;;OAEG;IACH,iIAAiC,CAAA;AACnC,CAAC,EAbW,wBAAwB,KAAxB,wBAAwB,QAanC","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\nexport enum ATTRIBUTION_NETWORK {\n  APPLE_SEARCH_ADS = 0,\n  ADJUST = 1,\n  APPSFLYER = 2,\n  BRANCH = 3,\n  TENJIN = 4,\n  FACEBOOK = 5,\n}\n\nexport enum PURCHASE_TYPE {\n  /**\n   * A type of SKU for in-app products.\n   */\n  INAPP = 'inapp',\n\n  /**\n   * A type of SKU for subscriptions.\n   */\n  SUBS = 'subs',\n}\n\n/**\n * Enum for billing features.\n * Currently, these are only relevant for Google Play Android users:\n * https://developer.android.com/reference/com/android/billingclient/api/BillingClient.FeatureType\n */\nexport enum BILLING_FEATURE {\n  /**\n   * Purchase/query for subscriptions.\n   */\n  SUBSCRIPTIONS,\n\n  /**\n   * Subscriptions update/replace.\n   */\n  SUBSCRIPTIONS_UPDATE,\n\n  /**\n   * Purchase/query for in-app items on VR.\n   */\n  IN_APP_ITEMS_ON_VR,\n\n  /**\n   * Purchase/query for subscriptions on VR.\n   */\n  SUBSCRIPTIONS_ON_VR,\n\n  /**\n   * Launch a price change confirmation flow.\n   */\n  PRICE_CHANGE_CONFIRMATION,\n}\nexport enum PRORATION_MODE {\n  UNKNOWN_SUBSCRIPTION_UPGRADE_DOWNGRADE_POLICY = 0,\n\n  /**\n   * Replacement takes effect immediately, and the remaining time will be\n   * prorated and credited to the user. This is the current default behavior.\n   */\n  IMMEDIATE_WITH_TIME_PRORATION = 1,\n\n  /**\n   * Replacement takes effect immediately, and the billing cycle remains the\n   * same. The price for the remaining period will be charged. This option is\n   * only available for subscription upgrade.\n   */\n  IMMEDIATE_AND_CHARGE_PRORATED_PRICE = 2,\n\n  /**\n   * Replacement takes effect immediately, and the new price will be charged on\n   * next recurrence time. The billing cycle stays the same.\n   */\n  IMMEDIATE_WITHOUT_PRORATION = 3,\n\n  /**\n   * Replacement takes effect when the old plan expires, and the new price will\n   * be charged at the same time.\n   */\n  DEFERRED = 4,\n}\n\nexport enum PACKAGE_TYPE {\n  /**\n   * A package that was defined with a custom identifier.\n   */\n  UNKNOWN = 'UNKNOWN',\n\n  /**\n   * A package that was defined with a custom identifier.\n   */\n  CUSTOM = 'CUSTOM',\n\n  /**\n   * A package configured with the predefined lifetime identifier.\n   */\n  LIFETIME = 'LIFETIME',\n\n  /**\n   * A package configured with the predefined annual identifier.\n   */\n  ANNUAL = 'ANNUAL',\n\n  /**\n   * A package configured with the predefined six month identifier.\n   */\n  SIX_MONTH = 'SIX_MONTH',\n\n  /**\n   * A package configured with the predefined three month identifier.\n   */\n  THREE_MONTH = 'THREE_MONTH',\n\n  /**\n   * A package configured with the predefined two month identifier.\n   */\n  TWO_MONTH = 'TWO_MONTH',\n\n  /**\n   * A package configured with the predefined monthly identifier.\n   */\n  MONTHLY = 'MONTHLY',\n\n  /**\n   * A package configured with the predefined weekly identifier.\n   */\n  WEEKLY = 'WEEKLY',\n}\n\nexport enum INTRO_ELIGIBILITY_STATUS {\n  /**\n   * doesn't have enough information to determine eligibility.\n   */\n  INTRO_ELIGIBILITY_STATUS_UNKNOWN = 0,\n  /**\n   * The user is not eligible for a free trial or intro pricing for this product.\n   */\n  INTRO_ELIGIBILITY_STATUS_INELIGIBLE,\n  /**\n   * The user is eligible for a free trial or intro pricing for this product.\n   */\n  INTRO_ELIGIBILITY_STATUS_ELIGIBLE,\n}\n\nexport interface Transaction {\n  /**\n   * Unique identifier for the transaction.\n   *\n   * @since 1.0.0\n   * @platform ios Numeric string (e.g., \"2000001043762129\")\n   * @platform android Alphanumeric string (e.g., \"GPA.1234-5678-9012-34567\")\n   */\n  readonly transactionId: string;\n  /**\n   * Receipt data for validation (base64 encoded StoreKit receipt).\n   *\n   * Send this to your backend for server-side validation with Apple's receipt verification API.\n   * The receipt remains available even after refund - server validation is required to detect refunded transactions.\n   *\n   * @since 1.0.0\n   * @platform ios Always present\n   * @platform android Not available (use purchaseToken instead)\n   */\n  readonly receipt?: string;\n  /**\n   * StoreKit 2 JSON Web Signature (JWS) payload describing the verified transaction.\n   *\n   * Send this to your backend when using Apple's App Store Server API v2 instead of raw receipts.\n   * Only available when the transaction originated from StoreKit 2 APIs (e.g. Transaction.updates).\n   *\n   * @since 7.13.2\n   * @platform ios Present for StoreKit 2 transactions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly jwsRepresentation?: string;\n  /**\n   * An optional obfuscated identifier that uniquely associates the transaction with a user account in your app.\n   *\n   * PURPOSE:\n   * - Fraud detection: Helps platforms detect irregular activity (e.g., many devices purchasing on the same account)\n   * - User linking: Links purchases to in-game characters, avatars, or in-app profiles\n   *\n   * PLATFORM DIFFERENCES:\n   * - iOS: Must be a valid UUID format (e.g., \"550e8400-e29b-41d4-a716-446655440000\")\n   *        Apple's StoreKit 2 requires UUID format for the appAccountToken parameter\n   * - Android: Can be any obfuscated string (max 64 chars), maps to Google Play's ObfuscatedAccountId\n   *           Google recommends using encryption or one-way hash\n   *\n   * SECURITY REQUIREMENTS (especially for Android):\n   * - DO NOT store Personally Identifiable Information (PII) like emails in cleartext\n   * - Use encryption or a one-way hash to generate an obfuscated identifier\n   * - Maximum length: 64 characters (both platforms)\n   * - Storing PII in cleartext will result in purchases being blocked by Google Play\n   *\n   * IMPLEMENTATION EXAMPLE:\n   * ```typescript\n   * // For iOS: Generate a deterministic UUID from user ID\n   * import { v5 as uuidv5 } from 'uuid';\n   * const NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'; // Your app's namespace UUID\n   * const appAccountToken = uuidv5(userId, NAMESPACE);\n   *\n   * // For Android: Can also use UUID or any hashed value\n   * // The same UUID approach works for both platforms\n   * ```\n   */\n  readonly appAccountToken?: string | null;\n  /**\n   * Product identifier associated with the transaction.\n   *\n   * @since 1.0.0\n   * @platform ios Always present\n   * @platform android Always present\n   */\n  readonly productIdentifier: string;\n  /**\n   * Purchase date of the transaction in ISO 8601 format.\n   *\n   * @since 1.0.0\n   * @example \"2025-10-28T06:03:19Z\"\n   * @platform ios Always present\n   * @platform android Always present\n   */\n  readonly purchaseDate: string;\n  /**\n   * Indicates whether this transaction is the result of a subscription upgrade.\n   *\n   * Useful for understanding when StoreKit generated the transaction because\n   * the customer moved from a lower tier to a higher tier plan.\n   *\n   * @since 7.13.2\n   * @platform ios Present for auto-renewable subscriptions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly isUpgraded?: boolean;\n  /**\n   * Original purchase date of the transaction in ISO 8601 format.\n   *\n   * For subscription renewals, this shows the date of the original subscription purchase,\n   * while purchaseDate shows the date of the current renewal.\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions only\n   * @platform android Not available\n   */\n  readonly originalPurchaseDate?: string;\n  /**\n   * Expiration date of the transaction in ISO 8601 format.\n   *\n   * Check this date to determine if a subscription is still valid.\n   * Compare with current date: if expirationDate > now, subscription is active.\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions only\n   * @platform android Not available (query Google Play Developer API instead)\n   */\n  readonly expirationDate?: string;\n  /**\n   * Whether the subscription is still active/valid.\n   *\n   * For iOS subscriptions, check if isActive === true to verify an active subscription.\n   * For expired or refunded iOS subscriptions, this will be false.\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions only (true if expiration date is in the future)\n   * @platform android Not available (check purchaseState === \"1\" instead)\n   */\n  readonly isActive?: boolean;\n  /**\n   * Date the transaction was revoked/refunded, in ISO 8601 format.\n   *\n   * Present when Apple revokes access due to an issue (e.g., refund or developer issue).\n   *\n   * @since 7.13.2\n   * @platform ios Present for revoked transactions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly revocationDate?: string;\n  /**\n   * Reason why Apple revoked the transaction.\n   *\n   * Possible values:\n   * - `\"developerIssue\"`: Developer-initiated refund or issue\n   * - `\"other\"`: Apple-initiated (customer refund, billing problem, etc.)\n   * - `\"unknown\"`: StoreKit didn't report a specific reason\n   *\n   * @since 7.13.2\n   * @platform ios Present for revoked transactions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly revocationReason?: 'developerIssue' | 'other' | 'unknown';\n  /**\n   * Whether the subscription will be cancelled at the end of the billing cycle.\n   *\n   * - `true`: User has cancelled but subscription remains active until expiration\n   * - `false`: Subscription will auto-renew\n   * - `null`: Status unknown or not available\n   *\n   * @since 1.0.0\n   * @default null\n   * @platform ios Present for subscriptions only (boolean or null)\n   * @platform android Always null (use Google Play Developer API for cancellation status)\n   */\n  readonly willCancel: boolean | null;\n  /**\n   * Current subscription state reported by StoreKit.\n   *\n   * Possible values:\n   * - `\"subscribed\"`: Auto-renewing and in good standing\n   * - `\"expired\"`: Lapsed with no access\n   * - `\"revoked\"`: Access removed due to refund or issue\n   * - `\"inGracePeriod\"`: Payment issue but still in grace access window\n   * - `\"inBillingRetryPeriod\"`: StoreKit retrying failed billing\n   * - `\"unknown\"`: StoreKit did not report a state\n   *\n   * @since 7.13.2\n   * @platform ios Present for auto-renewable subscriptions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly subscriptionState?:\n    | 'subscribed'\n    | 'expired'\n    | 'revoked'\n    | 'inGracePeriod'\n    | 'inBillingRetryPeriod'\n    | 'unknown';\n  /**\n   * Purchase state of the transaction (numeric string value).\n   *\n   * **Android Values:**\n   * - `\"1\"`: Purchase completed and valid (PURCHASED state)\n   * - `\"0\"`: Payment pending (PENDING state, e.g., cash payment processing)\n   * - Other numeric values: Various other states\n   *\n   * Always check `purchaseState === \"1\"` on Android to verify a valid purchase.\n   * Refunded purchases typically disappear from getPurchases() rather than showing a different state.\n   *\n   * @since 1.0.0\n   * @platform ios Not available (use isActive for subscriptions or receipt validation for IAP)\n   * @platform android Always present\n   */\n  readonly purchaseState?: string;\n  /**\n   * Order ID associated with the transaction.\n   *\n   * Use this for server-side verification on Android. This is the Google Play order ID.\n   *\n   * @since 1.0.0\n   * @example \"GPA.1234-5678-9012-34567\"\n   * @platform ios Not available\n   * @platform android Always present\n   */\n  readonly orderId?: string;\n  /**\n   * Purchase token associated with the transaction.\n   *\n   * Send this to your backend for server-side validation with Google Play Developer API.\n   * This is the Android equivalent of iOS's receipt field.\n   *\n   * @since 1.0.0\n   * @platform ios Not available (use receipt instead)\n   * @platform android Always present\n   */\n  readonly purchaseToken?: string;\n  /**\n   * Whether the purchase has been acknowledged.\n   *\n   * Purchases must be acknowledged within 3 days or they will be refunded.\n   * By default, this plugin automatically acknowledges purchases unless you set\n   * `autoAcknowledgePurchases: false` in purchaseProduct().\n   *\n   * @since 1.0.0\n   * @platform ios Not available\n   * @platform android Always present (should be true after successful purchase or manual acknowledgment)\n   */\n  readonly isAcknowledged?: boolean;\n  /**\n   * Quantity purchased.\n   *\n   * @since 1.0.0\n   * @default 1\n   * @platform ios 1 or higher (as specified in purchaseProduct call)\n   * @platform android Always 1 (Google Play doesn't support quantity > 1)\n   */\n  readonly quantity?: number;\n  /**\n   * Product type.\n   *\n   * - `\"inapp\"`: One-time in-app purchase\n   * - `\"subs\"`: Subscription\n   *\n   * @since 1.0.0\n   * @platform ios Always present\n   * @platform android Always present\n   */\n  readonly productType?: string;\n  /**\n   * Indicates how the user obtained access to the product.\n   *\n   * - `\"purchased\"`: The user purchased the product directly\n   * - `\"familyShared\"`: The user has access through Family Sharing (another family member purchased it)\n   *\n   * This property is useful for:\n   * - Detecting family sharing usage for analytics\n   * - Implementing different features/limits for family-shared vs. directly purchased products\n   * - Understanding your user acquisition channels\n   *\n   * @since 7.12.8\n   * @platform ios Always present (iOS 15.0+, StoreKit 2)\n   * @platform android Not available\n   */\n  readonly ownershipType?: 'purchased' | 'familyShared';\n  /**\n   * Indicates the server environment where the transaction was processed.\n   *\n   * - `\"Sandbox\"`: Transaction belongs to testing in the sandbox environment\n   * - `\"Production\"`: Transaction belongs to a customer in the production environment\n   * - `\"Xcode\"`: Transaction from StoreKit Testing in Xcode\n   *\n   * This property is useful for:\n   * - Debugging and identifying test vs. production purchases\n   * - Analytics and reporting (filtering out sandbox transactions)\n   * - Server-side validation (knowing which Apple endpoint to use)\n   * - Preventing test purchases from affecting production metrics\n   *\n   * @since 7.12.8\n   * @platform ios Present on iOS 16.0+ only (not available on iOS 15)\n   * @platform android Not available\n   */\n  readonly environment?: 'Sandbox' | 'Production' | 'Xcode';\n  /**\n   * Reason StoreKit generated the transaction.\n   *\n   * - `\"purchase\"`: Initial purchase that user made manually\n   * - `\"renewal\"`: Automatically generated renewal for an auto-renewable subscription\n   * - `\"unknown\"`: StoreKit did not return a reason\n   *\n   * @since 7.13.2\n   * @platform ios Present on iOS 17.0+ (StoreKit 2 transactions)\n   * @platform android Not available\n   */\n  readonly transactionReason?: 'purchase' | 'renewal' | 'unknown';\n  /**\n   * Whether the transaction is in a trial period.\n   *\n   * - `true`: Currently in free trial period\n   * - `false`: Not in trial period\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions with trial offers\n   * @platform android Present for subscriptions with trial offers\n   */\n  readonly isTrialPeriod?: boolean;\n  /**\n   * Whether the transaction is in an introductory price period.\n   *\n   * Introductory pricing is a discounted rate, different from a free trial.\n   *\n   * - `true`: Currently using introductory pricing\n   * - `false`: Not in intro period\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions with intro pricing\n   * @platform android Present for subscriptions with intro pricing\n   */\n  readonly isInIntroPricePeriod?: boolean;\n  /**\n   * Whether the transaction is in a grace period.\n   *\n   * Grace period allows users to fix payment issues while maintaining access.\n   * You typically want to continue providing access during this time.\n   *\n   * - `true`: Subscription payment failed but user still has access\n   * - `false`: Not in grace period\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions in grace period\n   * @platform android Present for subscriptions in grace period\n   */\n  readonly isInGracePeriod?: boolean;\n}\n\nexport interface TransactionVerificationFailedEvent {\n  /**\n   * Identifier of the transaction that failed verification.\n   *\n   * @since 7.13.2\n   * @platform ios Present when StoreKit reports an unverified transaction\n   * @platform android Not available\n   */\n  readonly transactionId: string;\n  /**\n   * Localized error message describing why verification failed.\n   *\n   * @since 7.13.2\n   * @platform ios Always present\n   * @platform android Not available\n   */\n  readonly error: string;\n}\n\nexport interface SubscriptionPeriod {\n  /**\n   * The Subscription Period number of unit.\n   */\n  readonly numberOfUnits: number;\n  /**\n   * The Subscription Period unit.\n   */\n  readonly unit: number;\n}\nexport interface SKProductDiscount {\n  /**\n   * The Product discount identifier.\n   */\n  readonly identifier: string;\n  /**\n   * The Product discount type.\n   */\n  readonly type: number;\n  /**\n   * The Product discount price.\n   */\n  readonly price: number;\n  /**\n   * Formatted price of the item, including its currency sign, such as €3.99.\n   */\n  readonly priceString: string;\n  /**\n   * The Product discount currency symbol.\n   */\n  readonly currencySymbol: string;\n  /**\n   * The Product discount currency code.\n   */\n  readonly currencyCode: string;\n  /**\n   * The Product discount paymentMode.\n   */\n  readonly paymentMode: number;\n  /**\n   * The Product discount number Of Periods.\n   */\n  readonly numberOfPeriods: number;\n  /**\n   * The Product discount subscription period.\n   */\n  readonly subscriptionPeriod: SubscriptionPeriod;\n}\nexport interface Product {\n  /**\n   * Product Id.\n   */\n  readonly identifier: string;\n  /**\n   * Description of the product.\n   */\n  readonly description: string;\n  /**\n   * Title of the product.\n   */\n  readonly title: string;\n  /**\n   * Price of the product in the local currency.\n   */\n  readonly price: number;\n  /**\n   * Formatted price of the item, including its currency sign, such as €3.99.\n   */\n  readonly priceString: string;\n  /**\n   * Currency code for price and original price.\n   */\n  readonly currencyCode: string;\n  /**\n   * Currency symbol for price and original price.\n   */\n  readonly currencySymbol: string;\n  /**\n   * Boolean indicating if the product is sharable with family\n   */\n  readonly isFamilyShareable: boolean;\n  /**\n   * Group identifier for the product.\n   */\n  readonly subscriptionGroupIdentifier: string;\n  /**\n   * The Product subscription group identifier.\n   */\n  readonly subscriptionPeriod: SubscriptionPeriod;\n  /**\n   * The Product introductory Price.\n   */\n  readonly introductoryPrice: SKProductDiscount | null;\n  /**\n   * The Product discounts list.\n   */\n  readonly discounts: SKProductDiscount[];\n}\n\nexport interface NativePurchasesPlugin {\n  /**\n   * Restores a user's previous  and links their appUserIDs to any user's also using those .\n   */\n  restorePurchases(): Promise<void>;\n\n  /**\n   * Started purchase process for the given product.\n   *\n   * @param options - The product to purchase\n   * @param options.productIdentifier - The product identifier of the product you want to purchase.\n   * @param options.productType - Only Android, the type of product, can be inapp or subs. Will use inapp by default.\n   * @param options.planIdentifier - Only Android, the identifier of the base plan you want to purchase from Google Play Console. REQUIRED for Android subscriptions, ignored on iOS.\n   * @param options.quantity - Only iOS, the number of items you wish to purchase. Will use 1 by default.\n   * @param options.appAccountToken - Optional identifier uniquely associated with the user's account in your app.\n   *                                  PLATFORM REQUIREMENTS:\n   *                                  - iOS: Must be a valid UUID format (StoreKit 2 requirement)\n   *                                  - Android: Can be any obfuscated string (max 64 chars), maps to ObfuscatedAccountId\n   *                                  SECURITY: DO NOT use PII like emails in cleartext - use UUID or hashed value.\n   *                                  RECOMMENDED: Use UUID v5 with deterministic generation for cross-platform compatibility.\n   * @param options.isConsumable - Only Android, when true the purchase token is consumed after granting entitlement (for consumable in-app items). Defaults to false.\n   * @param options.autoAcknowledgePurchases - Only Android, when false the purchase will NOT be automatically acknowledged. You must manually call acknowledgePurchase() within 3 days or the purchase will be refunded. Defaults to true.\n   */\n  purchaseProduct(options: {\n    productIdentifier: string;\n    planIdentifier?: string;\n    productType?: PURCHASE_TYPE;\n    quantity?: number;\n    appAccountToken?: string;\n    isConsumable?: boolean;\n    autoAcknowledgePurchases?: boolean;\n  }): Promise<Transaction>;\n\n  /**\n   * Gets the product info associated with a list of product identifiers.\n   *\n   * @param options - The product identifiers you wish to retrieve information for\n   * @param options.productIdentifiers - Array of product identifiers\n   * @param options.productType - Only Android, the type of product, can be inapp or subs. Will use inapp by default.\n   * @returns - The requested product info\n   */\n  getProducts(options: { productIdentifiers: string[]; productType?: PURCHASE_TYPE }): Promise<{ products: Product[] }>;\n\n  /**\n   * Gets the product info for a single product identifier.\n   *\n   * @param options - The product identifier you wish to retrieve information for\n   * @param options.productIdentifier - The product identifier\n   * @param options.productType - Only Android, the type of product, can be inapp or subs. Will use inapp by default.\n   * @returns - The requested product info\n   */\n  getProduct(options: { productIdentifier: string; productType?: PURCHASE_TYPE }): Promise<{ product: Product }>;\n\n  /**\n   * Check if billing is supported for the current device.\n   *\n   *\n   */\n  isBillingSupported(): Promise<{ isBillingSupported: boolean }>;\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n\n  /**\n   * Gets all the user's purchases (both in-app purchases and subscriptions).\n   * This method queries the platform's purchase history for the current user.\n   *\n   * @param options - Optional parameters for filtering purchases\n   * @param options.productType - Only Android, filter by product type (inapp or subs). If not specified, returns both types.\n   * @param options.appAccountToken - Optional filter to restrict results to purchases that used the provided account token.\n   *                                   Must be the same identifier used during purchase (UUID format for iOS, any obfuscated string for Android).\n   *                                   iOS: UUID format required. Android: Maps to ObfuscatedAccountId.\n   * @returns {Promise<{ purchases: Transaction[] }>} Promise that resolves with array of user's purchases\n   * @throws An error if the purchase query fails\n   * @since 7.2.0\n   */\n  getPurchases(options?: {\n    productType?: PURCHASE_TYPE;\n    appAccountToken?: string;\n  }): Promise<{ purchases: Transaction[] }>;\n\n  /**\n   * Opens the platform's native subscription management page.\n   * This allows users to view, modify, or cancel their subscriptions.\n   *\n   * - iOS: Opens the App Store subscription management page for the current app\n   * - Android: Opens the Google Play subscription management page\n   *\n   * @returns {Promise<void>} Promise that resolves when the management page is opened\n   * @throws An error if the subscription management page cannot be opened\n   * @since 7.10.0\n   */\n  manageSubscriptions(): Promise<void>;\n\n  /**\n   * Manually acknowledge a purchase on Android.\n   *\n   * This method is only needed when you set `autoAcknowledgePurchases: false` in purchaseProduct().\n   * Purchases MUST be acknowledged within 3 days or they will be automatically refunded by Google Play.\n   *\n   * **Acknowledgment Options:**\n   * 1. **Client-side (this method)**: Call from your app after validation\n   * 2. **Server-side (recommended for security)**: Use Google Play Developer API v3\n   *    - Endpoint: POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge\n   *    - Requires OAuth 2.0 authentication with appropriate scopes\n   *    - See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge\n   *\n   * When to use manual acknowledgment:\n   * - Server-side validation: Verify the purchase with your backend before acknowledging\n   * - Entitlement delivery: Ensure user receives content/features before acknowledging\n   * - Multi-step workflows: Complete all steps before final acknowledgment\n   * - Security: Prevent client-side manipulation by handling acknowledgment server-side\n   *\n   * @param options - The purchase to acknowledge\n   * @param options.purchaseToken - The purchase token from the Transaction object (Android)\n   * @returns {Promise<void>} Promise that resolves when the purchase is acknowledged\n   * @throws An error if acknowledgment fails\n   * @platform android Only available on Android (iOS automatically finishes transactions)\n   * @since 7.14.0\n   *\n   * @example\n   * ```typescript\n   * // Client-side acknowledgment\n   * const transaction = await NativePurchases.purchaseProduct({\n   *   productIdentifier: 'premium_feature',\n   *   autoAcknowledgePurchases: false\n   * });\n   *\n   * // Validate with your backend\n   * const isValid = await fetch('/api/validate-purchase', {\n   *   method: 'POST',\n   *   body: JSON.stringify({ purchaseToken: transaction.purchaseToken })\n   * });\n   *\n   * if (isValid) {\n   *   // Option 1: Acknowledge from client\n   *   await NativePurchases.acknowledgePurchase({\n   *     purchaseToken: transaction.purchaseToken\n   *   });\n   *\n   *   // Option 2: Or let your backend acknowledge via Google Play API\n   *   // Your backend calls Google Play Developer API\n   * }\n   * ```\n   */\n  acknowledgePurchase(options: { purchaseToken: string }): Promise<void>;\n\n  /**\n   * Listen for StoreKit transaction updates delivered by Apple's Transaction.updates.\n   * Fires on app launch if there are unfinished transactions, and for any updates afterward.\n   * iOS only.\n   */\n  addListener(\n    eventName: 'transactionUpdated',\n    listenerFunc: (transaction: Transaction) => void,\n  ): Promise<PluginListenerHandle>;\n  /**\n   * Listen for StoreKit transaction verification failures delivered by Apple's Transaction.updates.\n   * Fires when the verification result is unverified.\n   * iOS only.\n   */\n  addListener(\n    eventName: 'transactionVerificationFailed',\n    listenerFunc: (payload: TransactionVerificationFailedEvent) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /** Remove all registered listeners */\n  removeAllListeners(): Promise<void>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAEA,MAAM,CAAN,IAAY,mBAOX;AAPD,WAAY,mBAAmB;IAC7B,qFAAoB,CAAA;IACpB,iEAAU,CAAA;IACV,uEAAa,CAAA;IACb,iEAAU,CAAA;IACV,iEAAU,CAAA;IACV,qEAAY,CAAA;AACd,CAAC,EAPW,mBAAmB,KAAnB,mBAAmB,QAO9B;AAED,MAAM,CAAN,IAAY,aAUX;AAVD,WAAY,aAAa;IACvB;;OAEG;IACH,gCAAe,CAAA;IAEf;;OAEG;IACH,8BAAa,CAAA;AACf,CAAC,EAVW,aAAa,KAAb,aAAa,QAUxB;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAyBX;AAzBD,WAAY,eAAe;IACzB;;OAEG;IACH,uEAAa,CAAA;IAEb;;OAEG;IACH,qFAAoB,CAAA;IAEpB;;OAEG;IACH,iFAAkB,CAAA;IAElB;;OAEG;IACH,mFAAmB,CAAA;IAEnB;;OAEG;IACH,+FAAyB,CAAA;AAC3B,CAAC,EAzBW,eAAe,KAAf,eAAe,QAyB1B;AACD,MAAM,CAAN,IAAY,cA2BX;AA3BD,WAAY,cAAc;IACxB,qIAAiD,CAAA;IAEjD;;;OAGG;IACH,qGAAiC,CAAA;IAEjC;;;;OAIG;IACH,iHAAuC,CAAA;IAEvC;;;OAGG;IACH,iGAA+B,CAAA;IAE/B;;;OAGG;IACH,2DAAY,CAAA;AACd,CAAC,EA3BW,cAAc,KAAd,cAAc,QA2BzB;AAED,MAAM,CAAN,IAAY,YA6CX;AA7CD,WAAY,YAAY;IACtB;;OAEG;IACH,mCAAmB,CAAA;IAEnB;;OAEG;IACH,iCAAiB,CAAA;IAEjB;;OAEG;IACH,qCAAqB,CAAA;IAErB;;OAEG;IACH,iCAAiB,CAAA;IAEjB;;OAEG;IACH,uCAAuB,CAAA;IAEvB;;OAEG;IACH,2CAA2B,CAAA;IAE3B;;OAEG;IACH,uCAAuB,CAAA;IAEvB;;OAEG;IACH,mCAAmB,CAAA;IAEnB;;OAEG;IACH,iCAAiB,CAAA;AACnB,CAAC,EA7CW,YAAY,KAAZ,YAAY,QA6CvB;AAED,MAAM,CAAN,IAAY,wBAaX;AAbD,WAAY,wBAAwB;IAClC;;OAEG;IACH,+HAAoC,CAAA;IACpC;;OAEG;IACH,qIAAmC,CAAA;IACnC;;OAEG;IACH,iIAAiC,CAAA;AACnC,CAAC,EAbW,wBAAwB,KAAxB,wBAAwB,QAanC","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\nexport enum ATTRIBUTION_NETWORK {\n  APPLE_SEARCH_ADS = 0,\n  ADJUST = 1,\n  APPSFLYER = 2,\n  BRANCH = 3,\n  TENJIN = 4,\n  FACEBOOK = 5,\n}\n\nexport enum PURCHASE_TYPE {\n  /**\n   * A type of SKU for in-app products.\n   */\n  INAPP = 'inapp',\n\n  /**\n   * A type of SKU for subscriptions.\n   */\n  SUBS = 'subs',\n}\n\n/**\n * Enum for billing features.\n * Currently, these are only relevant for Google Play Android users:\n * https://developer.android.com/reference/com/android/billingclient/api/BillingClient.FeatureType\n */\nexport enum BILLING_FEATURE {\n  /**\n   * Purchase/query for subscriptions.\n   */\n  SUBSCRIPTIONS,\n\n  /**\n   * Subscriptions update/replace.\n   */\n  SUBSCRIPTIONS_UPDATE,\n\n  /**\n   * Purchase/query for in-app items on VR.\n   */\n  IN_APP_ITEMS_ON_VR,\n\n  /**\n   * Purchase/query for subscriptions on VR.\n   */\n  SUBSCRIPTIONS_ON_VR,\n\n  /**\n   * Launch a price change confirmation flow.\n   */\n  PRICE_CHANGE_CONFIRMATION,\n}\nexport enum PRORATION_MODE {\n  UNKNOWN_SUBSCRIPTION_UPGRADE_DOWNGRADE_POLICY = 0,\n\n  /**\n   * Replacement takes effect immediately, and the remaining time will be\n   * prorated and credited to the user. This is the current default behavior.\n   */\n  IMMEDIATE_WITH_TIME_PRORATION = 1,\n\n  /**\n   * Replacement takes effect immediately, and the billing cycle remains the\n   * same. The price for the remaining period will be charged. This option is\n   * only available for subscription upgrade.\n   */\n  IMMEDIATE_AND_CHARGE_PRORATED_PRICE = 2,\n\n  /**\n   * Replacement takes effect immediately, and the new price will be charged on\n   * next recurrence time. The billing cycle stays the same.\n   */\n  IMMEDIATE_WITHOUT_PRORATION = 3,\n\n  /**\n   * Replacement takes effect when the old plan expires, and the new price will\n   * be charged at the same time.\n   */\n  DEFERRED = 4,\n}\n\nexport enum PACKAGE_TYPE {\n  /**\n   * A package that was defined with a custom identifier.\n   */\n  UNKNOWN = 'UNKNOWN',\n\n  /**\n   * A package that was defined with a custom identifier.\n   */\n  CUSTOM = 'CUSTOM',\n\n  /**\n   * A package configured with the predefined lifetime identifier.\n   */\n  LIFETIME = 'LIFETIME',\n\n  /**\n   * A package configured with the predefined annual identifier.\n   */\n  ANNUAL = 'ANNUAL',\n\n  /**\n   * A package configured with the predefined six month identifier.\n   */\n  SIX_MONTH = 'SIX_MONTH',\n\n  /**\n   * A package configured with the predefined three month identifier.\n   */\n  THREE_MONTH = 'THREE_MONTH',\n\n  /**\n   * A package configured with the predefined two month identifier.\n   */\n  TWO_MONTH = 'TWO_MONTH',\n\n  /**\n   * A package configured with the predefined monthly identifier.\n   */\n  MONTHLY = 'MONTHLY',\n\n  /**\n   * A package configured with the predefined weekly identifier.\n   */\n  WEEKLY = 'WEEKLY',\n}\n\nexport enum INTRO_ELIGIBILITY_STATUS {\n  /**\n   * doesn't have enough information to determine eligibility.\n   */\n  INTRO_ELIGIBILITY_STATUS_UNKNOWN = 0,\n  /**\n   * The user is not eligible for a free trial or intro pricing for this product.\n   */\n  INTRO_ELIGIBILITY_STATUS_INELIGIBLE,\n  /**\n   * The user is eligible for a free trial or intro pricing for this product.\n   */\n  INTRO_ELIGIBILITY_STATUS_ELIGIBLE,\n}\n\nexport interface Transaction {\n  /**\n   * Unique identifier for the transaction.\n   *\n   * @since 1.0.0\n   * @platform ios Numeric string (e.g., \"2000001043762129\")\n   * @platform android Alphanumeric string (e.g., \"GPA.1234-5678-9012-34567\")\n   */\n  readonly transactionId: string;\n  /**\n   * Receipt data for validation (base64 encoded StoreKit receipt).\n   *\n   * Send this to your backend for server-side validation with Apple's receipt verification API.\n   * The receipt remains available even after refund - server validation is required to detect refunded transactions.\n   *\n   * @since 1.0.0\n   * @platform ios Always present\n   * @platform android Not available (use purchaseToken instead)\n   */\n  readonly receipt?: string;\n  /**\n   * StoreKit 2 JSON Web Signature (JWS) payload describing the verified transaction.\n   *\n   * Send this to your backend when using Apple's App Store Server API v2 instead of raw receipts.\n   * Only available when the transaction originated from StoreKit 2 APIs (e.g. Transaction.updates).\n   *\n   * @since 7.13.2\n   * @platform ios Present for StoreKit 2 transactions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly jwsRepresentation?: string;\n  /**\n   * An optional obfuscated identifier that uniquely associates the transaction with a user account in your app.\n   *\n   * PURPOSE:\n   * - Fraud detection: Helps platforms detect irregular activity (e.g., many devices purchasing on the same account)\n   * - User linking: Links purchases to in-game characters, avatars, or in-app profiles\n   *\n   * PLATFORM DIFFERENCES:\n   * - iOS: Must be a valid UUID format (e.g., \"550e8400-e29b-41d4-a716-446655440000\")\n   *        Apple's StoreKit 2 requires UUID format for the appAccountToken parameter\n   * - Android: Can be any obfuscated string (max 64 chars), maps to Google Play's ObfuscatedAccountId\n   *           Google recommends using encryption or one-way hash\n   *\n   * SECURITY REQUIREMENTS (especially for Android):\n   * - DO NOT store Personally Identifiable Information (PII) like emails in cleartext\n   * - Use encryption or a one-way hash to generate an obfuscated identifier\n   * - Maximum length: 64 characters (both platforms)\n   * - Storing PII in cleartext will result in purchases being blocked by Google Play\n   *\n   * IMPLEMENTATION EXAMPLE:\n   * ```typescript\n   * // For iOS: Generate a deterministic UUID from user ID\n   * import { v5 as uuidv5 } from 'uuid';\n   * const NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'; // Your app's namespace UUID\n   * const appAccountToken = uuidv5(userId, NAMESPACE);\n   *\n   * // For Android: Can also use UUID or any hashed value\n   * // The same UUID approach works for both platforms\n   * ```\n   */\n  readonly appAccountToken?: string | null;\n  /**\n   * Product identifier associated with the transaction.\n   *\n   * @since 1.0.0\n   * @platform ios Always present\n   * @platform android Always present\n   */\n  readonly productIdentifier: string;\n  /**\n   * Purchase date of the transaction in ISO 8601 format.\n   *\n   * @since 1.0.0\n   * @example \"2025-10-28T06:03:19Z\"\n   * @platform ios Always present\n   * @platform android Always present\n   */\n  readonly purchaseDate: string;\n  /**\n   * Indicates whether this transaction is the result of a subscription upgrade.\n   *\n   * Useful for understanding when StoreKit generated the transaction because\n   * the customer moved from a lower tier to a higher tier plan.\n   *\n   * @since 7.13.2\n   * @platform ios Present for auto-renewable subscriptions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly isUpgraded?: boolean;\n  /**\n   * Original purchase date of the transaction in ISO 8601 format.\n   *\n   * For subscription renewals, this shows the date of the original subscription purchase,\n   * while purchaseDate shows the date of the current renewal.\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions only\n   * @platform android Not available\n   */\n  readonly originalPurchaseDate?: string;\n  /**\n   * Expiration date of the transaction in ISO 8601 format.\n   *\n   * Check this date to determine if a subscription is still valid.\n   * Compare with current date: if expirationDate > now, subscription is active.\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions only\n   * @platform android Not available (query Google Play Developer API instead)\n   */\n  readonly expirationDate?: string;\n  /**\n   * Whether the subscription is still active/valid.\n   *\n   * For iOS subscriptions, check if isActive === true to verify an active subscription.\n   * For expired or refunded iOS subscriptions, this will be false.\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions only (true if expiration date is in the future)\n   * @platform android Not available (check purchaseState === \"1\" instead)\n   */\n  readonly isActive?: boolean;\n  /**\n   * Date the transaction was revoked/refunded, in ISO 8601 format.\n   *\n   * Present when Apple revokes access due to an issue (e.g., refund or developer issue).\n   *\n   * @since 7.13.2\n   * @platform ios Present for revoked transactions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly revocationDate?: string;\n  /**\n   * Reason why Apple revoked the transaction.\n   *\n   * Possible values:\n   * - `\"developerIssue\"`: Developer-initiated refund or issue\n   * - `\"other\"`: Apple-initiated (customer refund, billing problem, etc.)\n   * - `\"unknown\"`: StoreKit didn't report a specific reason\n   *\n   * @since 7.13.2\n   * @platform ios Present for revoked transactions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly revocationReason?: 'developerIssue' | 'other' | 'unknown';\n  /**\n   * Whether the subscription will be cancelled at the end of the billing cycle.\n   *\n   * - `true`: User has cancelled but subscription remains active until expiration\n   * - `false`: Subscription will auto-renew\n   * - `null`: Status unknown or not available\n   *\n   * @since 1.0.0\n   * @default null\n   * @platform ios Present for subscriptions only (boolean or null)\n   * @platform android Always null (use Google Play Developer API for cancellation status)\n   */\n  readonly willCancel: boolean | null;\n  /**\n   * Current subscription state reported by StoreKit.\n   *\n   * Possible values:\n   * - `\"subscribed\"`: Auto-renewing and in good standing\n   * - `\"expired\"`: Lapsed with no access\n   * - `\"revoked\"`: Access removed due to refund or issue\n   * - `\"inGracePeriod\"`: Payment issue but still in grace access window\n   * - `\"inBillingRetryPeriod\"`: StoreKit retrying failed billing\n   * - `\"unknown\"`: StoreKit did not report a state\n   *\n   * @since 7.13.2\n   * @platform ios Present for auto-renewable subscriptions (iOS 15+)\n   * @platform android Not available\n   */\n  readonly subscriptionState?:\n    | 'subscribed'\n    | 'expired'\n    | 'revoked'\n    | 'inGracePeriod'\n    | 'inBillingRetryPeriod'\n    | 'unknown';\n  /**\n   * Purchase state of the transaction (numeric string value).\n   *\n   * **Android Values:**\n   * - `\"1\"`: Purchase completed and valid (PURCHASED state)\n   * - `\"0\"`: Payment pending (PENDING state, e.g., cash payment processing)\n   * - Other numeric values: Various other states\n   *\n   * Always check `purchaseState === \"1\"` on Android to verify a valid purchase.\n   * Refunded purchases typically disappear from getPurchases() rather than showing a different state.\n   *\n   * @since 1.0.0\n   * @platform ios Not available (use isActive for subscriptions or receipt validation for IAP)\n   * @platform android Always present\n   */\n  readonly purchaseState?: string;\n  /**\n   * Order ID associated with the transaction.\n   *\n   * Use this for server-side verification on Android. This is the Google Play order ID.\n   *\n   * @since 1.0.0\n   * @example \"GPA.1234-5678-9012-34567\"\n   * @platform ios Not available\n   * @platform android Always present\n   */\n  readonly orderId?: string;\n  /**\n   * Purchase token associated with the transaction.\n   *\n   * Send this to your backend for server-side validation with Google Play Developer API.\n   * This is the Android equivalent of iOS's receipt field.\n   *\n   * @since 1.0.0\n   * @platform ios Not available (use receipt instead)\n   * @platform android Always present\n   */\n  readonly purchaseToken?: string;\n  /**\n   * Whether the purchase has been acknowledged.\n   *\n   * Purchases must be acknowledged within 3 days or they will be refunded.\n   * By default, this plugin automatically acknowledges purchases unless you set\n   * `autoAcknowledgePurchases: false` in purchaseProduct().\n   *\n   * @since 1.0.0\n   * @platform ios Not available\n   * @platform android Always present (should be true after successful purchase or manual acknowledgment)\n   */\n  readonly isAcknowledged?: boolean;\n  /**\n   * Quantity purchased.\n   *\n   * @since 1.0.0\n   * @default 1\n   * @platform ios 1 or higher (as specified in purchaseProduct call)\n   * @platform android Always 1 (Google Play doesn't support quantity > 1)\n   */\n  readonly quantity?: number;\n  /**\n   * Product type.\n   *\n   * - `\"inapp\"`: One-time in-app purchase\n   * - `\"subs\"`: Subscription\n   *\n   * @since 1.0.0\n   * @platform ios Always present\n   * @platform android Always present\n   */\n  readonly productType?: string;\n  /**\n   * Indicates how the user obtained access to the product.\n   *\n   * - `\"purchased\"`: The user purchased the product directly\n   * - `\"familyShared\"`: The user has access through Family Sharing (another family member purchased it)\n   *\n   * This property is useful for:\n   * - Detecting family sharing usage for analytics\n   * - Implementing different features/limits for family-shared vs. directly purchased products\n   * - Understanding your user acquisition channels\n   *\n   * @since 7.12.8\n   * @platform ios Always present (iOS 15.0+, StoreKit 2)\n   * @platform android Not available\n   */\n  readonly ownershipType?: 'purchased' | 'familyShared';\n  /**\n   * Indicates the server environment where the transaction was processed.\n   *\n   * - `\"Sandbox\"`: Transaction belongs to testing in the sandbox environment\n   * - `\"Production\"`: Transaction belongs to a customer in the production environment\n   * - `\"Xcode\"`: Transaction from StoreKit Testing in Xcode\n   *\n   * This property is useful for:\n   * - Debugging and identifying test vs. production purchases\n   * - Analytics and reporting (filtering out sandbox transactions)\n   * - Server-side validation (knowing which Apple endpoint to use)\n   * - Preventing test purchases from affecting production metrics\n   *\n   * @since 7.12.8\n   * @platform ios Present on iOS 16.0+ only (not available on iOS 15)\n   * @platform android Not available\n   */\n  readonly environment?: 'Sandbox' | 'Production' | 'Xcode';\n  /**\n   * Reason StoreKit generated the transaction.\n   *\n   * - `\"purchase\"`: Initial purchase that user made manually\n   * - `\"renewal\"`: Automatically generated renewal for an auto-renewable subscription\n   * - `\"unknown\"`: StoreKit did not return a reason\n   *\n   * @since 7.13.2\n   * @platform ios Present on iOS 17.0+ (StoreKit 2 transactions)\n   * @platform android Not available\n   */\n  readonly transactionReason?: 'purchase' | 'renewal' | 'unknown';\n  /**\n   * Whether the transaction is in a trial period.\n   *\n   * - `true`: Currently in free trial period\n   * - `false`: Not in trial period\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions with trial offers\n   * @platform android Present for subscriptions with trial offers\n   */\n  readonly isTrialPeriod?: boolean;\n  /**\n   * Whether the transaction is in an introductory price period.\n   *\n   * Introductory pricing is a discounted rate, different from a free trial.\n   *\n   * - `true`: Currently using introductory pricing\n   * - `false`: Not in intro period\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions with intro pricing\n   * @platform android Present for subscriptions with intro pricing\n   */\n  readonly isInIntroPricePeriod?: boolean;\n  /**\n   * Whether the transaction is in a grace period.\n   *\n   * Grace period allows users to fix payment issues while maintaining access.\n   * You typically want to continue providing access during this time.\n   *\n   * - `true`: Subscription payment failed but user still has access\n   * - `false`: Not in grace period\n   *\n   * @since 1.0.0\n   * @platform ios Present for subscriptions in grace period\n   * @platform android Present for subscriptions in grace period\n   */\n  readonly isInGracePeriod?: boolean;\n}\n\nexport interface TransactionVerificationFailedEvent {\n  /**\n   * Identifier of the transaction that failed verification.\n   *\n   * @since 7.13.2\n   * @platform ios Present when StoreKit reports an unverified transaction\n   * @platform android Not available\n   */\n  readonly transactionId: string;\n  /**\n   * Localized error message describing why verification failed.\n   *\n   * @since 7.13.2\n   * @platform ios Always present\n   * @platform android Not available\n   */\n  readonly error: string;\n}\n\nexport interface SubscriptionPeriod {\n  /**\n   * The Subscription Period number of unit.\n   */\n  readonly numberOfUnits: number;\n  /**\n   * The Subscription Period unit.\n   */\n  readonly unit: number;\n}\nexport interface SKProductDiscount {\n  /**\n   * The Product discount identifier.\n   */\n  readonly identifier: string;\n  /**\n   * The Product discount type.\n   */\n  readonly type: number;\n  /**\n   * The Product discount price.\n   */\n  readonly price: number;\n  /**\n   * Formatted price of the item, including its currency sign, such as €3.99.\n   */\n  readonly priceString: string;\n  /**\n   * The Product discount currency symbol.\n   */\n  readonly currencySymbol: string;\n  /**\n   * The Product discount currency code.\n   */\n  readonly currencyCode: string;\n  /**\n   * The Product discount paymentMode.\n   */\n  readonly paymentMode: number;\n  /**\n   * The Product discount number Of Periods.\n   */\n  readonly numberOfPeriods: number;\n  /**\n   * The Product discount subscription period.\n   */\n  readonly subscriptionPeriod: SubscriptionPeriod;\n}\nexport interface Product {\n  /**\n   * Product Id.\n   */\n  readonly identifier: string;\n  /**\n   * Description of the product.\n   */\n  readonly description: string;\n  /**\n   * Title of the product.\n   */\n  readonly title: string;\n  /**\n   * Price of the product in the local currency.\n   */\n  readonly price: number;\n  /**\n   * Formatted price of the item, including its currency sign, such as €3.99.\n   */\n  readonly priceString: string;\n  /**\n   * Currency code for price and original price.\n   */\n  readonly currencyCode: string;\n  /**\n   * Currency symbol for price and original price.\n   */\n  readonly currencySymbol: string;\n  /**\n   * Boolean indicating if the product is sharable with family\n   */\n  readonly isFamilyShareable: boolean;\n  /**\n   * Group identifier for the product.\n   */\n  readonly subscriptionGroupIdentifier: string;\n  /**\n   * The Product subscription group identifier.\n   */\n  readonly subscriptionPeriod: SubscriptionPeriod;\n  /**\n   * The Product introductory Price.\n   */\n  readonly introductoryPrice: SKProductDiscount | null;\n  /**\n   * The Product discounts list.\n   */\n  readonly discounts: SKProductDiscount[];\n}\n\nexport interface NativePurchasesPlugin {\n  /**\n   * Restores a user's previous  and links their appUserIDs to any user's also using those .\n   */\n  restorePurchases(): Promise<void>;\n\n  /**\n   * Started purchase process for the given product.\n   *\n   * @param options - The product to purchase\n   * @param options.productIdentifier - The product identifier of the product you want to purchase.\n   * @param options.productType - Only Android, the type of product, can be inapp or subs. Will use inapp by default.\n   * @param options.planIdentifier - Only Android, the identifier of the base plan you want to purchase from Google Play Console. REQUIRED for Android subscriptions, ignored on iOS.\n   * @param options.quantity - Only iOS, the number of items you wish to purchase. Will use 1 by default.\n   * @param options.appAccountToken - Optional identifier uniquely associated with the user's account in your app.\n   *                                  PLATFORM REQUIREMENTS:\n   *                                  - iOS: Must be a valid UUID format (StoreKit 2 requirement)\n   *                                  - Android: Can be any obfuscated string (max 64 chars), maps to ObfuscatedAccountId\n   *                                  SECURITY: DO NOT use PII like emails in cleartext - use UUID or hashed value.\n   *                                  RECOMMENDED: Use UUID v5 with deterministic generation for cross-platform compatibility.\n   * @param options.isConsumable - Only Android, when true the purchase token is consumed after granting entitlement (for consumable in-app items). Defaults to false.\n   * @param options.autoAcknowledgePurchases - When false, the purchase/transaction will NOT be automatically acknowledged/finished. You must manually call acknowledgePurchase() or the purchase may be refunded. Defaults to true.\n   *                                           - **Android**: Must acknowledge within 3 days or Google Play will refund\n   *                                           - **iOS**: Unfinished transactions remain in the queue and may block future purchases\n   */\n  purchaseProduct(options: {\n    productIdentifier: string;\n    planIdentifier?: string;\n    productType?: PURCHASE_TYPE;\n    quantity?: number;\n    appAccountToken?: string;\n    isConsumable?: boolean;\n    autoAcknowledgePurchases?: boolean;\n  }): Promise<Transaction>;\n\n  /**\n   * Gets the product info associated with a list of product identifiers.\n   *\n   * @param options - The product identifiers you wish to retrieve information for\n   * @param options.productIdentifiers - Array of product identifiers\n   * @param options.productType - Only Android, the type of product, can be inapp or subs. Will use inapp by default.\n   * @returns - The requested product info\n   */\n  getProducts(options: { productIdentifiers: string[]; productType?: PURCHASE_TYPE }): Promise<{ products: Product[] }>;\n\n  /**\n   * Gets the product info for a single product identifier.\n   *\n   * @param options - The product identifier you wish to retrieve information for\n   * @param options.productIdentifier - The product identifier\n   * @param options.productType - Only Android, the type of product, can be inapp or subs. Will use inapp by default.\n   * @returns - The requested product info\n   */\n  getProduct(options: { productIdentifier: string; productType?: PURCHASE_TYPE }): Promise<{ product: Product }>;\n\n  /**\n   * Check if billing is supported for the current device.\n   *\n   *\n   */\n  isBillingSupported(): Promise<{ isBillingSupported: boolean }>;\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n\n  /**\n   * Gets all the user's purchases (both in-app purchases and subscriptions).\n   * This method queries the platform's purchase history for the current user.\n   *\n   * @param options - Optional parameters for filtering purchases\n   * @param options.productType - Only Android, filter by product type (inapp or subs). If not specified, returns both types.\n   * @param options.appAccountToken - Optional filter to restrict results to purchases that used the provided account token.\n   *                                   Must be the same identifier used during purchase (UUID format for iOS, any obfuscated string for Android).\n   *                                   iOS: UUID format required. Android: Maps to ObfuscatedAccountId.\n   * @returns {Promise<{ purchases: Transaction[] }>} Promise that resolves with array of user's purchases\n   * @throws An error if the purchase query fails\n   * @since 7.2.0\n   */\n  getPurchases(options?: {\n    productType?: PURCHASE_TYPE;\n    appAccountToken?: string;\n  }): Promise<{ purchases: Transaction[] }>;\n\n  /**\n   * Opens the platform's native subscription management page.\n   * This allows users to view, modify, or cancel their subscriptions.\n   *\n   * - iOS: Opens the App Store subscription management page for the current app\n   * - Android: Opens the Google Play subscription management page\n   *\n   * @returns {Promise<void>} Promise that resolves when the management page is opened\n   * @throws An error if the subscription management page cannot be opened\n   * @since 7.10.0\n   */\n  manageSubscriptions(): Promise<void>;\n\n  /**\n   * Manually acknowledge/finish a purchase transaction.\n   *\n   * This method is only needed when you set `autoAcknowledgePurchases: false` in purchaseProduct().\n   *\n   * **Platform Behavior:**\n   * - **Android**: Acknowledges the purchase with Google Play. Must be called within 3 days or the purchase will be refunded.\n   * - **iOS**: Finishes the transaction with StoreKit 2. Unfinished transactions remain in the queue and may block future purchases.\n   *\n   * **Acknowledgment Options:**\n   *\n   * **1. Client-side (this method)**: Call from your app after validation\n   * ```typescript\n   * await NativePurchases.acknowledgePurchase({\n   *   purchaseToken: transaction.purchaseToken  // Android: purchaseToken, iOS: transactionId\n   * });\n   * ```\n   *\n   * **2. Server-side (Android only, recommended for security)**: Use Google Play Developer API v3\n   * - Endpoint: `POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge`\n   * - Requires OAuth 2.0 authentication with appropriate scopes\n   * - See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge\n   * - For subscriptions: Use `/purchases/subscriptions/{subscriptionId}/tokens/{token}:acknowledge` instead\n   * - Note: iOS has no server-side finish API\n   *\n   * **When to use manual acknowledgment:**\n   * - Server-side validation: Verify the purchase with your backend before acknowledging\n   * - Entitlement delivery: Ensure user receives content/features before acknowledging\n   * - Multi-step workflows: Complete all steps before final acknowledgment\n   * - Security: Prevent client-side manipulation by handling acknowledgment server-side (Android only)\n   *\n   * @param options - The purchase to acknowledge\n   * @param options.purchaseToken - The purchase token (Android) or transaction ID as string (iOS) from the Transaction object\n   * @returns {Promise<void>} Promise that resolves when the purchase is acknowledged/finished\n   * @throws An error if acknowledgment/finishing fails or transaction not found\n   * @platform android Acknowledges the purchase with Google Play\n   * @platform ios Finishes the transaction with StoreKit 2\n   * @since 7.14.0\n   *\n   * @example\n   * ```typescript\n   * // Client-side acknowledgment\n   * const transaction = await NativePurchases.purchaseProduct({\n   *   productIdentifier: 'premium_feature',\n   *   autoAcknowledgePurchases: false\n   * });\n   *\n   * // Validate with your backend\n   * const isValid = await fetch('/api/validate-purchase', {\n   *   method: 'POST',\n   *   body: JSON.stringify({ purchaseToken: transaction.purchaseToken })\n   * });\n   *\n   * if (isValid) {\n   *   // Option 1: Acknowledge from client\n   *   await NativePurchases.acknowledgePurchase({\n   *     purchaseToken: transaction.purchaseToken\n   *   });\n   *\n   *   // Option 2: Or let your backend acknowledge via Google Play API\n   *   // Your backend calls Google Play Developer API\n   * }\n   * ```\n   */\n  acknowledgePurchase(options: { purchaseToken: string }): Promise<void>;\n\n  /**\n   * Listen for StoreKit transaction updates delivered by Apple's Transaction.updates.\n   * Fires on app launch if there are unfinished transactions, and for any updates afterward.\n   * iOS only.\n   */\n  addListener(\n    eventName: 'transactionUpdated',\n    listenerFunc: (transaction: Transaction) => void,\n  ): Promise<PluginListenerHandle>;\n  /**\n   * Listen for StoreKit transaction verification failures delivered by Apple's Transaction.updates.\n   * Fires when the verification result is unverified.\n   * iOS only.\n   */\n  addListener(\n    eventName: 'transactionVerificationFailed',\n    listenerFunc: (payload: TransactionVerificationFailedEvent) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /** Remove all registered listeners */\n  removeAllListeners(): Promise<void>;\n}\n"]}

package/ios/Sources/NativePurchasesPlugin/NativePurchasesPlugin.swift

@@ -22,7 +22,7 @@ public class NativePurchasesPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "acknowledgePurchase", returnType: CAPPluginReturnPromise)
     ]
 
-    private let pluginVersion: String = "7.14.0"
+    private let pluginVersion: String = "7.15.1"
     private var transactionUpdatesTask: Task<Void, Never>?
 
     @objc func getPluginVersion(_ call: CAPPluginCall) {
@@ -99,12 +99,15 @@ public class NativePurchasesPlugin: CAPPlugin, CAPBridgedPlugin {
             let productIdentifier = call.getString("productIdentifier", "")
             let quantity = call.getInt("quantity", 1)
             let appAccountToken = call.getString("appAccountToken")
+            let autoAcknowledge = call.getBool("autoAcknowledgePurchases") ?? true
 
             if productIdentifier.isEmpty {
                 call.reject("productIdentifier is Empty, give an id")
                 return
             }
 
+            print("Auto-acknowledge enabled: \(autoAcknowledge)")
+
             Task { @MainActor in
                 do {
                     let products = try await Product.products(for: [productIdentifier])
@@ -117,7 +120,7 @@ public class NativePurchasesPlugin: CAPPlugin, CAPBridgedPlugin {
                     let result = try await product.purchase(options: purchaseOptions)
                     print("purchaseProduct result \(result)")
 
-                    await self.handlePurchaseResult(result, call: call)
+                    await self.handlePurchaseResult(result, call: call, autoFinish: autoAcknowledge)
                 } catch {
                     print(error)
                     call.reject(error.localizedDescription)
@@ -143,13 +146,23 @@ public class NativePurchasesPlugin: CAPPlugin, CAPBridgedPlugin {
 
     @available(iOS 15.0, *)
     @MainActor
-    private func handlePurchaseResult(_ result: Product.PurchaseResult, call: CAPPluginCall) async {
+    private func handlePurchaseResult(_ result: Product.PurchaseResult, call: CAPPluginCall, autoFinish: Bool) async {
         switch result {
         case let .success(verificationResult):
             switch verificationResult {
             case .verified(let transaction):
                 let response = await TransactionHelpers.buildTransactionResponse(from: transaction, jwsRepresentation: verificationResult.jwsRepresentation)
-                await transaction.finish()
+
+                if autoFinish {
+                    print("Auto-finishing transaction: \(transaction.id)")
+                    await transaction.finish()
+                } else {
+                    print("Manual finish required for transaction: \(transaction.id)")
+                    print("Transaction will remain unfinished until acknowledgePurchase() is called")
+                    // Don't finish - transaction remains in StoreKit's queue
+                    // Can be retrieved later via Transaction.all
+                }
+
                 call.resolve(response)
             case .unverified(_, let error):
                 call.reject(error.localizedDescription)
@@ -292,10 +305,58 @@ public class NativePurchasesPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     @objc func acknowledgePurchase(_ call: CAPPluginCall) {
-        print("acknowledgePurchase called on iOS - not needed, iOS automatically finishes transactions")
-        // iOS automatically finishes transactions through StoreKit 2
-        // This method is provided for API compatibility but does nothing on iOS
-        call.resolve()
+        if #available(iOS 15.0, *) {
+            print("acknowledgePurchase called on iOS")
+
+            guard let purchaseToken = call.getString("purchaseToken") else {
+                call.reject("purchaseToken is required")
+                return
+            }
+
+            // On iOS, purchaseToken is the transactionId (UInt64 as string)
+            guard let transactionId = UInt64(purchaseToken) else {
+                call.reject("Invalid purchaseToken format")
+                return
+            }
+
+            Task {
+                // Search for the transaction in StoreKit's unfinished transactions
+                // This works even after app restart because StoreKit persists them
+                var foundTransaction: Transaction?
+
+                for await verificationResult in Transaction.all {
+                    switch verificationResult {
+                    case .verified(let transaction):
+                        if transaction.id == transactionId {
+                            foundTransaction = transaction
+                            break
+                        }
+                    case .unverified:
+                        continue
+                    }
+                    if foundTransaction != nil {
+                        break
+                    }
+                }
+
+                guard let transaction = foundTransaction else {
+                    await MainActor.run {
+                        call.reject("Transaction not found or already finished. Transaction ID: \(transactionId)")
+                    }
+                    return
+                }
+
+                print("Manually finishing transaction: \(transaction.id)")
+                await transaction.finish()
+
+                await MainActor.run {
+                    print("Transaction finished successfully")
+                    call.resolve()
+                }
+            }
+        } else {
+            call.reject("Not implemented under iOS 15")
+        }
     }
 
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/native-purchases",
-  "version": "7.14.0",
+  "version": "7.15.1",
   "description": "In-app Subscriptions Made Easy",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",