@capgo/native-purchases 7.17.0 → 7.18.0

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

@@ -30,7 +30,6 @@ import com.google.common.collect.ImmutableList;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
-import java.util.Objects;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.Phaser;
 import java.util.concurrent.TimeUnit;
@@ -42,7 +41,7 @@ import org.json.JSONArray;
 @CapacitorPlugin(name = "NativePurchases")
 public class NativePurchasesPlugin extends Plugin {
 
-    private final String pluginVersion = "7.17.0";
+    private final String pluginVersion = "7.18.0";
     public static final String TAG = "NativePurchases";
     private static final Phaser semaphoreReady = new Phaser(1);
     private BillingClient billingClient;
@@ -52,10 +51,32 @@ public class NativePurchasesPlugin extends Plugin {
     @PluginMethod
     public void isBillingSupported(PluginCall call) {
         Log.d(TAG, "isBillingSupported() called");
-        JSObject ret = new JSObject();
-        ret.put("isBillingSupported", true);
-        Log.d(TAG, "isBillingSupported() returning true");
-        call.resolve(ret);
+        try {
+            // Try to initialize billing client to check if billing is actually available
+            // Pass null so initBillingClient doesn't reject the call - we'll handle the result ourselves
+            this.initBillingClient(null);
+            // If initialization succeeded, billing is supported
+            JSObject ret = new JSObject();
+            ret.put("isBillingSupported", true);
+            Log.d(TAG, "isBillingSupported() returning true - billing client initialized successfully");
+            closeBillingClient();
+            call.resolve(ret);
+        } catch (RuntimeException e) {
+            Log.e(TAG, "isBillingSupported() - billing client initialization failed: " + e.getMessage());
+            closeBillingClient();
+            // Return false instead of rejecting - this is a check method
+            JSObject ret = new JSObject();
+            ret.put("isBillingSupported", false);
+            Log.d(TAG, "isBillingSupported() returning false - billing not available");
+            call.resolve(ret);
+        } catch (Exception e) {
+            Log.e(TAG, "isBillingSupported() - unexpected error: " + e.getMessage());
+            closeBillingClient();
+            JSObject ret = new JSObject();
+            ret.put("isBillingSupported", false);
+            Log.d(TAG, "isBillingSupported() returning false - unexpected error");
+            call.resolve(ret);
+        }
     }
 
     @Override
@@ -665,44 +686,67 @@ public class NativePurchasesPlugin extends Plugin {
                         if (productType.equals("inapp")) {
                             Log.d(TAG, "Processing as in-app product");
                             product.put("identifier", productDetails.getProductId());
-                            double price =
-                                Objects.requireNonNull(productDetails.getOneTimePurchaseOfferDetails()).getPriceAmountMicros() / 1000000.0;
+                            ProductDetails.OneTimePurchaseOfferDetails oneTimeOfferDetails =
+                                productDetails.getOneTimePurchaseOfferDetails();
+                            if (oneTimeOfferDetails == null) {
+                                Log.w(TAG, "No one-time purchase offer details found for product: " + productDetails.getProductId());
+                                closeBillingClient();
+                                call.reject("No one-time purchase offer details found for product: " + productDetails.getProductId());
+                                return;
+                            }
+                            double price = oneTimeOfferDetails.getPriceAmountMicros() / 1000000.0;
                             product.put("price", price);
-                            product.put("priceString", productDetails.getOneTimePurchaseOfferDetails().getFormattedPrice());
-                            product.put("currencyCode", productDetails.getOneTimePurchaseOfferDetails().getPriceCurrencyCode());
+                            product.put("priceString", oneTimeOfferDetails.getFormattedPrice());
+                            product.put("currencyCode", oneTimeOfferDetails.getPriceCurrencyCode());
                             Log.d(TAG, "Price: " + price);
-                            Log.d(TAG, "Formatted price: " + productDetails.getOneTimePurchaseOfferDetails().getFormattedPrice());
-                            Log.d(TAG, "Currency: " + productDetails.getOneTimePurchaseOfferDetails().getPriceCurrencyCode());
+                            Log.d(TAG, "Formatted price: " + oneTimeOfferDetails.getFormattedPrice());
+                            Log.d(TAG, "Currency: " + oneTimeOfferDetails.getPriceCurrencyCode());
                         } else {
                             Log.d(TAG, "Processing as subscription product");
-                            ProductDetails.SubscriptionOfferDetails selectedOfferDetails = productDetails
-                                .getSubscriptionOfferDetails()
+                            List<ProductDetails.SubscriptionOfferDetails> offerDetailsList = productDetails.getSubscriptionOfferDetails();
+                            if (offerDetailsList == null || offerDetailsList.isEmpty()) {
+                                Log.w(TAG, "No subscription offer details found for product: " + productDetails.getProductId());
+                                closeBillingClient();
+                                call.reject("No subscription offers found for product: " + productDetails.getProductId());
+                                return;
+                            }
+
+                            ProductDetails.SubscriptionOfferDetails selectedOfferDetails = null;
+                            for (ProductDetails.SubscriptionOfferDetails offerDetails : offerDetailsList) {
+                                if (
+                                    offerDetails.getPricingPhases() != null &&
+                                    !offerDetails.getPricingPhases().getPricingPhaseList().isEmpty()
+                                ) {
+                                    selectedOfferDetails = offerDetails;
+                                    break;
+                                }
+                            }
+
+                            if (selectedOfferDetails == null) {
+                                Log.w(TAG, "No offers with pricing phases found for product: " + productDetails.getProductId());
+                                closeBillingClient();
+                                call.reject("No pricing phases found for product: " + productDetails.getProductId());
+                                return;
+                            }
+
+                            ProductDetails.PricingPhase firstPricingPhase = selectedOfferDetails
+                                .getPricingPhases()
+                                .getPricingPhaseList()
                                 .get(0);
                             product.put("planIdentifier", productDetails.getProductId());
                             product.put("identifier", selectedOfferDetails.getBasePlanId());
-                            double price =
-                                selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getPriceAmountMicros() / 1000000.0;
+                            product.put("offerToken", selectedOfferDetails.getOfferToken());
+                            product.put("offerId", selectedOfferDetails.getOfferId());
+                            double price = firstPricingPhase.getPriceAmountMicros() / 1000000.0;
                             product.put("price", price);
-                            product.put(
-                                "priceString",
-                                selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getFormattedPrice()
-                            );
-                            product.put(
-                                "currencyCode",
-                                selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getPriceCurrencyCode()
-                            );
+                            product.put("priceString", firstPricingPhase.getFormattedPrice());
+                            product.put("currencyCode", firstPricingPhase.getPriceCurrencyCode());
                             Log.d(TAG, "Plan identifier: " + productDetails.getProductId());
                             Log.d(TAG, "Base plan ID: " + selectedOfferDetails.getBasePlanId());
+                            Log.d(TAG, "Offer token: " + selectedOfferDetails.getOfferToken());
                             Log.d(TAG, "Price: " + price);
-                            Log.d(
-                                TAG,
-                                "Formatted price: " +
-                                selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getFormattedPrice()
-                            );
-                            Log.d(
-                                TAG,
-                                "Currency: " + selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getPriceCurrencyCode()
-                            );
+                            Log.d(TAG, "Formatted price: " + firstPricingPhase.getFormattedPrice());
+                            Log.d(TAG, "Currency: " + firstPricingPhase.getPriceCurrencyCode());
                         }
                         product.put("isFamilyShareable", false);
 
@@ -777,58 +821,86 @@ public class NativePurchasesPlugin extends Plugin {
                         JSONArray products = new JSONArray();
                         for (ProductDetails productDetails : productDetailsList) {
                             Log.d(TAG, "Processing product details: " + productDetails.getProductId());
-                            JSObject product = new JSObject();
-                            product.put("title", productDetails.getName());
-                            product.put("description", productDetails.getDescription());
                             Log.d(TAG, "Product title: " + productDetails.getName());
                             Log.d(TAG, "Product description: " + productDetails.getDescription());
 
                             if (productType.equals("inapp")) {
                                 Log.d(TAG, "Processing as in-app product");
+                                JSObject product = new JSObject();
+                                product.put("title", productDetails.getName());
+                                product.put("description", productDetails.getDescription());
                                 product.put("identifier", productDetails.getProductId());
-                                double price =
-                                    Objects.requireNonNull(productDetails.getOneTimePurchaseOfferDetails()).getPriceAmountMicros() /
-                                    1000000.0;
+
+                                ProductDetails.OneTimePurchaseOfferDetails oneTimeOfferDetails =
+                                    productDetails.getOneTimePurchaseOfferDetails();
+                                if (oneTimeOfferDetails == null) {
+                                    Log.w(TAG, "No one-time purchase offer details found for product: " + productDetails.getProductId());
+                                    continue;
+                                }
+
+                                double price = oneTimeOfferDetails.getPriceAmountMicros() / 1000000.0;
                                 product.put("price", price);
-                                product.put("priceString", productDetails.getOneTimePurchaseOfferDetails().getFormattedPrice());
-                                product.put("currencyCode", productDetails.getOneTimePurchaseOfferDetails().getPriceCurrencyCode());
+                                product.put("priceString", oneTimeOfferDetails.getFormattedPrice());
+                                product.put("currencyCode", oneTimeOfferDetails.getPriceCurrencyCode());
+                                product.put("isFamilyShareable", false);
                                 Log.d(TAG, "Price: " + price);
-                                Log.d(TAG, "Formatted price: " + productDetails.getOneTimePurchaseOfferDetails().getFormattedPrice());
-                                Log.d(TAG, "Currency: " + productDetails.getOneTimePurchaseOfferDetails().getPriceCurrencyCode());
+                                Log.d(TAG, "Formatted price: " + oneTimeOfferDetails.getFormattedPrice());
+                                Log.d(TAG, "Currency: " + oneTimeOfferDetails.getPriceCurrencyCode());
+                                products.put(product);
                             } else {
                                 Log.d(TAG, "Processing as subscription product");
-                                ProductDetails.SubscriptionOfferDetails selectedOfferDetails = productDetails
-                                    .getSubscriptionOfferDetails()
-                                    .get(0);
-                                product.put("planIdentifier", productDetails.getProductId());
-                                product.put("identifier", selectedOfferDetails.getBasePlanId());
-                                double price =
-                                    selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getPriceAmountMicros() / 1000000.0;
-                                product.put("price", price);
-                                product.put(
-                                    "priceString",
-                                    selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getFormattedPrice()
-                                );
-                                product.put(
-                                    "currencyCode",
-                                    selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getPriceCurrencyCode()
-                                );
-                                Log.d(TAG, "Plan identifier: " + productDetails.getProductId());
-                                Log.d(TAG, "Base plan ID: " + selectedOfferDetails.getBasePlanId());
-                                Log.d(TAG, "Price: " + price);
-                                Log.d(
-                                    TAG,
-                                    "Formatted price: " +
-                                    selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getFormattedPrice()
-                                );
-                                Log.d(
-                                    TAG,
-                                    "Currency: " +
-                                    selectedOfferDetails.getPricingPhases().getPricingPhaseList().get(0).getPriceCurrencyCode()
-                                );
+                                List<ProductDetails.SubscriptionOfferDetails> offerDetailsList =
+                                    productDetails.getSubscriptionOfferDetails();
+                                if (offerDetailsList == null || offerDetailsList.isEmpty()) {
+                                    Log.w(TAG, "No subscription offer details found for product: " + productDetails.getProductId());
+                                    continue;
+                                }
+
+                                int addedOffers = 0;
+                                for (ProductDetails.SubscriptionOfferDetails offerDetails : offerDetailsList) {
+                                    if (
+                                        offerDetails.getPricingPhases() == null ||
+                                        offerDetails.getPricingPhases().getPricingPhaseList().isEmpty()
+                                    ) {
+                                        Log.w(TAG, "No pricing phases found for offer: " + offerDetails.getBasePlanId());
+                                        continue;
+                                    }
+
+                                    JSObject product = new JSObject();
+                                    product.put("title", productDetails.getName());
+                                    product.put("description", productDetails.getDescription());
+                                    product.put("planIdentifier", productDetails.getProductId());
+                                    product.put("identifier", offerDetails.getBasePlanId());
+                                    product.put("offerToken", offerDetails.getOfferToken());
+                                    product.put("offerId", offerDetails.getOfferId());
+
+                                    ProductDetails.PricingPhase firstPricingPhase = offerDetails
+                                        .getPricingPhases()
+                                        .getPricingPhaseList()
+                                        .get(0);
+                                    double price = firstPricingPhase.getPriceAmountMicros() / 1000000.0;
+                                    product.put("price", price);
+                                    product.put("priceString", firstPricingPhase.getFormattedPrice());
+                                    product.put("currencyCode", firstPricingPhase.getPriceCurrencyCode());
+                                    product.put("isFamilyShareable", false);
+
+                                    Log.d(TAG, "Plan identifier: " + productDetails.getProductId());
+                                    Log.d(TAG, "Base plan ID: " + offerDetails.getBasePlanId());
+                                    Log.d(TAG, "Price: " + price);
+                                    Log.d(TAG, "Formatted price: " + firstPricingPhase.getFormattedPrice());
+                                    Log.d(TAG, "Currency: " + firstPricingPhase.getPriceCurrencyCode());
+
+                                    products.put(product);
+                                    addedOffers++;
+                                }
+
+                                if (addedOffers == 0) {
+                                    Log.w(
+                                        TAG,
+                                        "All subscription offers missing pricing phases for product: " + productDetails.getProductId()
+                                    );
+                                }
                             }
-                            product.put("isFamilyShareable", false);
-                            products.put(product);
                         }
                         JSObject ret = new JSObject();
                         ret.put("products", products);
@@ -1122,6 +1194,50 @@ public class NativePurchasesPlugin extends Plugin {
         }
     }
 
+    @PluginMethod
+    public void consumePurchase(PluginCall call) {
+        Log.d(TAG, "consumePurchase() called");
+        String purchaseToken = call.getString("purchaseToken");
+
+        if (purchaseToken == null || purchaseToken.isEmpty()) {
+            Log.d(TAG, "Error: purchaseToken is empty");
+            call.reject("purchaseToken is required");
+            return;
+        }
+
+        Log.d(TAG, "Consuming purchase with token: " + purchaseToken);
+        try {
+            this.initBillingClient(call);
+        } catch (RuntimeException e) {
+            Log.e(TAG, "Failed to initialize billing client: " + e.getMessage());
+            closeBillingClient();
+            return;
+        }
+
+        try {
+            ConsumeParams consumeParams = ConsumeParams.newBuilder().setPurchaseToken(purchaseToken).build();
+
+            billingClient.consumeAsync(consumeParams, (billingResult, consumedToken) -> {
+                Log.d(TAG, "onConsumeResponse() called");
+                Log.d(TAG, "Consume result: " + billingResult.getResponseCode() + " - " + billingResult.getDebugMessage());
+
+                if (billingResult.getResponseCode() == BillingClient.BillingResponseCode.OK) {
+                    Log.d(TAG, "Purchase consumed successfully");
+                    closeBillingClient();
+                    call.resolve();
+                } else {
+                    Log.d(TAG, "Purchase consumption failed");
+                    closeBillingClient();
+                    call.reject("Failed to consume purchase: " + billingResult.getDebugMessage());
+                }
+            });
+        } catch (Exception e) {
+            Log.d(TAG, "Exception during consumePurchase: " + e.getMessage());
+            closeBillingClient();
+            call.reject(e.getMessage());
+        }
+    }
+
     @PluginMethod
     public void getAppTransaction(PluginCall call) {
         Log.d(TAG, "getAppTransaction() called");

package/dist/docs.json

@@ -362,6 +362,51 @@
         "complexTypes": [],
         "slug": "acknowledgepurchase"
       },
+      {
+        "name": "consumePurchase",
+        "signature": "(options: { purchaseToken: string; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- The purchase to consume",
+            "type": "{ purchaseToken: string; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - The purchase to consume"
+          },
+          {
+            "name": "param",
+            "text": "options.purchaseToken - The purchase token from the Transaction object"
+          },
+          {
+            "name": "returns",
+            "text": "Promise that resolves when the purchase is consumed"
+          },
+          {
+            "name": "throws",
+            "text": "Error if consumption fails, token is invalid, or called on iOS/web"
+          },
+          {
+            "name": "platform",
+            "text": "android"
+          },
+          {
+            "name": "since",
+            "text": "8.2.0"
+          },
+          {
+            "name": "example",
+            "text": "```typescript\nconst transaction = await NativePurchases.purchaseProduct({\n  productIdentifier: 'coins_100',\n  isConsumable: false,\n  autoAcknowledgePurchases: false\n});\n\n// Validate with your backend first\nconst isValid = await validateWithServer(transaction.purchaseToken);\n\nif (isValid) {\n  // Grant the coins, then consume to allow re-purchase\n  await NativePurchases.consumePurchase({\n    purchaseToken: transaction.purchaseToken!\n  });\n}\n```"
+          }
+        ],
+        "docs": "Consume an in-app purchase on Android.\n\nConsuming a purchase does two things:\n1. Acknowledges the purchase (so you don't need to call acknowledgePurchase separately)\n2. Removes ownership, allowing the user to buy the same product again\n\nUse this for consumable products like virtual currency, extra lives, or credits.\n\n**Important:** In Google Play Billing Library 8.x, consumed purchases can no longer\nbe queried via getPurchases(). Once consumed, the purchase is gone.\n\nAndroid only — iOS does not have a separate consume concept.\nOn iOS and web, this method rejects with an error.",
+        "complexTypes": [],
+        "slug": "consumepurchase"
+      },
       {
         "name": "addListener",
         "signature": "(eventName: 'transactionUpdated', listenerFunc: (transaction: Transaction) => void) => Promise<PluginListenerHandle>",
@@ -619,9 +664,13 @@
             {
               "text": "android Not available (use purchaseToken instead)",
               "name": "platform"
+            },
+            {
+              "text": "```typescript\nconst transaction = await NativePurchases.purchaseProduct({ ... });\nif (transaction.receipt) {\n  // Send to your backend for validation\n  await fetch('/api/validate-receipt', {\n    method: 'POST',\n    body: JSON.stringify({ receipt: transaction.receipt })\n  });\n}\n```",
+              "name": "example"
             }
           ],
-          "docs": "Receipt data for validation (base64 encoded StoreKit receipt).\n\nSend this to your backend for server-side validation with Apple's receipt verification API.\nThe receipt remains available even after refund - server validation is required to detect refunded transactions.",
+          "docs": "Receipt data for validation (base64 encoded StoreKit receipt).\n\n**This is the full verified receipt payload from Apple StoreKit.**\nSend this to your backend for server-side validation with Apple's receipt verification API.\nThe receipt remains available even after refund - server validation is required to detect refunded transactions.\n\n**For backend validation:**\n- Use Apple's receipt verification API: https://buy.itunes.apple.com/verifyReceipt (production)\n- Or sandbox: https://sandbox.itunes.apple.com/verifyReceipt\n- This contains all transaction data needed for validation\n\n**Note:** Apple recommends migrating to App Store Server API v2 with `jwsRepresentation` for new implementations.\nThe legacy receipt verification API continues to work but may be deprecated in the future.",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -639,9 +688,13 @@
             {
               "text": "android Not available",
               "name": "platform"
+            },
+            {
+              "text": "```typescript\nconst transaction = await NativePurchases.purchaseProduct({ ... });\nif (transaction.jwsRepresentation) {\n  // Send to your backend for validation with App Store Server API v2\n  await fetch('/api/validate-jws', {\n    method: 'POST',\n    body: JSON.stringify({ jws: transaction.jwsRepresentation })\n  });\n}\n```",
+              "name": "example"
             }
           ],
-          "docs": "StoreKit 2 JSON Web Signature (JWS) payload describing the verified transaction.\n\nSend this to your backend when using Apple's App Store Server API v2 instead of raw receipts.\nOnly available when the transaction originated from StoreKit 2 APIs (e.g. Transaction.updates).",
+          "docs": "StoreKit 2 JSON Web Signature (JWS) payload describing the verified transaction.\n\n**This is the full verified receipt in JWS format (StoreKit 2).**\nSend this to your backend when using Apple's App Store Server API v2 instead of raw receipts.\nOnly available when the transaction originated from StoreKit 2 APIs (e.g. Transaction.updates).\n\n**For backend validation:**\n- Use Apple's App Store Server API v2 to decode and verify the JWS\n- This is the modern alternative to the legacy receipt format\n- Contains signed transaction information from Apple",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -918,9 +971,13 @@
             {
               "text": "android Always present",
               "name": "platform"
+            },
+            {
+              "text": "```typescript\nconst transaction = await NativePurchases.purchaseProduct({ ... });\nif (transaction.purchaseToken) {\n  // Send to your backend for validation\n  await fetch('/api/validate-purchase', {\n    method: 'POST',\n    body: JSON.stringify({\n      purchaseToken: transaction.purchaseToken,\n      productId: transaction.productIdentifier\n    })\n  });\n}\n```",
+              "name": "example"
             }
           ],
-          "docs": "Purchase token associated with the transaction.\n\nSend this to your backend for server-side validation with Google Play Developer API.\nThis is the Android equivalent of iOS's receipt field.",
+          "docs": "Purchase token associated with the transaction.\n\n**This is the full verified purchase token from Google Play.**\nSend this to your backend for server-side validation with Google Play Developer API.\nThis is the Android equivalent of iOS's receipt field.\n\n**For backend validation:**\n- Use Google Play Developer API v3 to verify the purchase\n- API endpoint: androidpublisher.purchases.products.get() or purchases.subscriptions.get()\n- This token contains all data needed for validation with Google servers\n- Can also be used for subscription status checks and cancellation detection",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -1120,7 +1177,7 @@
         {
           "name": "identifier",
           "tags": [],
-          "docs": "Product Id.",
+          "docs": "Product Id.\n\nAndroid subscriptions note:\n- `identifier` is the base plan ID (`offerDetails.getBasePlanId()`).\n- `planIdentifier` is the subscription product ID (`productDetails.getProductId()`).\n\nIf you group/filter Android subscription results by `identifier`, you are grouping by base plan.",
           "complexTypes": [],
           "type": "string"
         },
@@ -1180,6 +1237,27 @@
           "complexTypes": [],
           "type": "string"
         },
+        {
+          "name": "planIdentifier",
+          "tags": [],
+          "docs": "Android subscriptions only: Google Play product identifier tied to the offer/base plan set.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "offerToken",
+          "tags": [],
+          "docs": "Android subscriptions only: offer token required when purchasing specific offers.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "offerId",
+          "tags": [],
+          "docs": "Android subscriptions only: offer identifier (null/undefined for base offers).",
+          "complexTypes": [],
+          "type": "string | null | undefined"
+        },
         {
           "name": "subscriptionPeriod",
           "tags": [],

package/dist/esm/definitions.d.ts

@@ -132,23 +132,60 @@ export interface Transaction {
     /**
      * Receipt data for validation (base64 encoded StoreKit receipt).
      *
+     * **This is the full verified receipt payload from Apple StoreKit.**
      * Send this to your backend for server-side validation with Apple's receipt verification API.
      * The receipt remains available even after refund - server validation is required to detect refunded transactions.
      *
+     * **For backend validation:**
+     * - Use Apple's receipt verification API: https://buy.itunes.apple.com/verifyReceipt (production)
+     * - Or sandbox: https://sandbox.itunes.apple.com/verifyReceipt
+     * - This contains all transaction data needed for validation
+     *
+     * **Note:** Apple recommends migrating to App Store Server API v2 with `jwsRepresentation` for new implementations.
+     * The legacy receipt verification API continues to work but may be deprecated in the future.
+     *
      * @since 1.0.0
      * @platform ios Always present
      * @platform android Not available (use purchaseToken instead)
+     * @example
+     * ```typescript
+     * const transaction = await NativePurchases.purchaseProduct({ ... });
+     * if (transaction.receipt) {
+     *   // Send to your backend for validation
+     *   await fetch('/api/validate-receipt', {
+     *     method: 'POST',
+     *     body: JSON.stringify({ receipt: transaction.receipt })
+     *   });
+     * }
+     * ```
      */
     readonly receipt?: string;
     /**
      * StoreKit 2 JSON Web Signature (JWS) payload describing the verified transaction.
      *
+     * **This is the full verified receipt in JWS format (StoreKit 2).**
      * Send this to your backend when using Apple's App Store Server API v2 instead of raw receipts.
      * Only available when the transaction originated from StoreKit 2 APIs (e.g. Transaction.updates).
      *
+     * **For backend validation:**
+     * - Use Apple's App Store Server API v2 to decode and verify the JWS
+     * - This is the modern alternative to the legacy receipt format
+     * - Contains signed transaction information from Apple
+     *
      * @since 7.13.2
      * @platform ios Present for StoreKit 2 transactions (iOS 15+)
      * @platform android Not available
+     * @example
+     * ```typescript
+     * const transaction = await NativePurchases.purchaseProduct({ ... });
+     * if (transaction.jwsRepresentation) {
+     *   // Send to your backend for validation with App Store Server API v2
+     *   await fetch('/api/validate-jws', {
+     *     method: 'POST',
+     *     body: JSON.stringify({ jws: transaction.jwsRepresentation })
+     *   });
+     * }
+     * ```
      */
     readonly jwsRepresentation?: string;
     /**
@@ -325,12 +362,33 @@ export interface Transaction {
     /**
      * Purchase token associated with the transaction.
      *
+     * **This is the full verified purchase token from Google Play.**
      * Send this to your backend for server-side validation with Google Play Developer API.
      * This is the Android equivalent of iOS's receipt field.
      *
+     * **For backend validation:**
+     * - Use Google Play Developer API v3 to verify the purchase
+     * - API endpoint: androidpublisher.purchases.products.get() or purchases.subscriptions.get()
+     * - This token contains all data needed for validation with Google servers
+     * - Can also be used for subscription status checks and cancellation detection
+     *
      * @since 1.0.0
      * @platform ios Not available (use receipt instead)
      * @platform android Always present
+     * @example
+     * ```typescript
+     * const transaction = await NativePurchases.purchaseProduct({ ... });
+     * if (transaction.purchaseToken) {
+     *   // Send to your backend for validation
+     *   await fetch('/api/validate-purchase', {
+     *     method: 'POST',
+     *     body: JSON.stringify({
+     *       purchaseToken: transaction.purchaseToken,
+     *       productId: transaction.productIdentifier
+     *     })
+     *   });
+     * }
+     * ```
      */
     readonly purchaseToken?: string;
     /**
@@ -589,6 +647,12 @@ export interface SKProductDiscount {
 export interface Product {
     /**
      * Product Id.
+     *
+     * Android subscriptions note:
+     * - `identifier` is the base plan ID (`offerDetails.getBasePlanId()`).
+     * - `planIdentifier` is the subscription product ID (`productDetails.getProductId()`).
+     *
+     * If you group/filter Android subscription results by `identifier`, you are grouping by base plan.
      */
     readonly identifier: string;
     /**
@@ -623,6 +687,18 @@ export interface Product {
      * Group identifier for the product.
      */
     readonly subscriptionGroupIdentifier: string;
+    /**
+     * Android subscriptions only: Google Play product identifier tied to the offer/base plan set.
+     */
+    readonly planIdentifier?: string;
+    /**
+     * Android subscriptions only: offer token required when purchasing specific offers.
+     */
+    readonly offerToken?: string;
+    /**
+     * Android subscriptions only: offer identifier (null/undefined for base offers).
+     */
+    readonly offerId?: string | null;
     /**
      * The Product subscription group identifier.
      */
@@ -893,6 +969,50 @@ export interface NativePurchasesPlugin {
     acknowledgePurchase(options: {
         purchaseToken: string;
     }): Promise<void>;
+    /**
+     * Consume an in-app purchase on Android.
+     *
+     * Consuming a purchase does two things:
+     * 1. Acknowledges the purchase (so you don't need to call acknowledgePurchase separately)
+     * 2. Removes ownership, allowing the user to buy the same product again
+     *
+     * Use this for consumable products like virtual currency, extra lives, or credits.
+     *
+     * **Important:** In Google Play Billing Library 8.x, consumed purchases can no longer
+     * be queried via getPurchases(). Once consumed, the purchase is gone.
+     *
+     * Android only — iOS does not have a separate consume concept.
+     * On iOS and web, this method rejects with an error.
+     *
+     * @param options - The purchase to consume
+     * @param options.purchaseToken - The purchase token from the Transaction object
+     * @returns {Promise<void>} Promise that resolves when the purchase is consumed
+     * @throws Error if consumption fails, token is invalid, or called on iOS/web
+     * @platform android
+     * @since 8.2.0
+     *
+     * @example
+     * ```typescript
+     * const transaction = await NativePurchases.purchaseProduct({
+     *   productIdentifier: 'coins_100',
+     *   isConsumable: false,
+     *   autoAcknowledgePurchases: false
+     * });
+     *
+     * // Validate with your backend first
+     * const isValid = await validateWithServer(transaction.purchaseToken);
+     *
+     * if (isValid) {
+     *   // Grant the coins, then consume to allow re-purchase
+     *   await NativePurchases.consumePurchase({
+     *     purchaseToken: transaction.purchaseToken!
+     *   });
+     * }
+     * ```
+     */
+    consumePurchase(options: {
+        purchaseToken: string;
+    }): Promise<void>;
     /**
      * Listen for StoreKit transaction updates delivered by Apple's Transaction.updates.
      * Fires on app launch if there are unfinished transactions, and for any updates afterward.