@capgo/native-purchases 7.13.5 → 7.14.0

package/dist/docs.json

@@ -17,12 +17,12 @@
       },
       {
         "name": "purchaseProduct",
-        "signature": "(options: { productIdentifier: string; planIdentifier?: string; productType?: PURCHASE_TYPE; quantity?: number; appAccountToken?: string; isConsumable?: boolean; }) => Promise<Transaction>",
+        "signature": "(options: { productIdentifier: string; planIdentifier?: string; productType?: PURCHASE_TYPE; quantity?: number; appAccountToken?: string; isConsumable?: boolean; autoAcknowledgePurchases?: boolean; }) => Promise<Transaction>",
         "parameters": [
           {
             "name": "options",
             "docs": "- The product to purchase",
-            "type": "{ productIdentifier: string; planIdentifier?: string | undefined; productType?: PURCHASE_TYPE | undefined; quantity?: number | undefined; appAccountToken?: string | undefined; isConsumable?: boolean | undefined; }"
+            "type": "{ productIdentifier: string; planIdentifier?: string | undefined; productType?: PURCHASE_TYPE | undefined; quantity?: number | undefined; appAccountToken?: string | undefined; isConsumable?: boolean | undefined; autoAcknowledgePurchases?: boolean | undefined; }"
           }
         ],
         "returns": "Promise<Transaction>",
@@ -54,6 +54,10 @@
           {
             "name": "param",
             "text": "options.isConsumable - Only Android, when true the purchase token is consumed after granting entitlement (for consumable in-app items). Defaults to false."
+          },
+          {
+            "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."
           }
         ],
         "docs": "Started purchase process for the given product.",
@@ -231,6 +235,51 @@
         "complexTypes": [],
         "slug": "managesubscriptions"
       },
+      {
+        "name": "acknowledgePurchase",
+        "signature": "(options: { purchaseToken: string; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- The purchase to acknowledge",
+            "type": "{ purchaseToken: string; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - The purchase to acknowledge"
+          },
+          {
+            "name": "param",
+            "text": "options.purchaseToken - The purchase token from the Transaction object (Android)"
+          },
+          {
+            "name": "returns",
+            "text": "Promise that resolves when the purchase is acknowledged"
+          },
+          {
+            "name": "throws",
+            "text": "An error if acknowledgment fails"
+          },
+          {
+            "name": "platform",
+            "text": "android Only available on Android (iOS automatically finishes transactions)"
+          },
+          {
+            "name": "since",
+            "text": "7.14.0"
+          },
+          {
+            "name": "example",
+            "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",
+        "complexTypes": [],
+        "slug": "acknowledgepurchase"
+      },
       {
         "name": "addListener",
         "signature": "(eventName: 'transactionUpdated', listenerFunc: (transaction: Transaction) => void) => Promise<PluginListenerHandle>",
@@ -255,6 +304,30 @@
         ],
         "slug": "addlistenertransactionupdated-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'transactionVerificationFailed', listenerFunc: (payload: TransactionVerificationFailedEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'transactionVerificationFailed'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(payload: TransactionVerificationFailedEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "Listen for StoreKit transaction verification failures delivered by Apple's Transaction.updates.\nFires when the verification result is unverified.\niOS only.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "TransactionVerificationFailedEvent"
+        ],
+        "slug": "addlistenertransactionverificationfailed-"
+      },
       {
         "name": "removeAllListeners",
         "signature": "() => Promise<void>",
@@ -316,6 +389,26 @@
           "complexTypes": [],
           "type": "string | undefined"
         },
+        {
+          "name": "jwsRepresentation",
+          "tags": [
+            {
+              "text": "7.13.2",
+              "name": "since"
+            },
+            {
+              "text": "ios Present for StoreKit 2 transactions (iOS 15+)",
+              "name": "platform"
+            },
+            {
+              "text": "android Not available",
+              "name": "platform"
+            }
+          ],
+          "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).",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
         {
           "name": "appAccountToken",
           "tags": [],
@@ -367,6 +460,26 @@
           "complexTypes": [],
           "type": "string"
         },
+        {
+          "name": "isUpgraded",
+          "tags": [
+            {
+              "text": "7.13.2",
+              "name": "since"
+            },
+            {
+              "text": "ios Present for auto-renewable subscriptions (iOS 15+)",
+              "name": "platform"
+            },
+            {
+              "text": "android Not available",
+              "name": "platform"
+            }
+          ],
+          "docs": "Indicates whether this transaction is the result of a subscription upgrade.\n\nUseful for understanding when StoreKit generated the transaction because\nthe customer moved from a lower tier to a higher tier plan.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
         {
           "name": "originalPurchaseDate",
           "tags": [
@@ -427,6 +540,46 @@
           "complexTypes": [],
           "type": "boolean | undefined"
         },
+        {
+          "name": "revocationDate",
+          "tags": [
+            {
+              "text": "7.13.2",
+              "name": "since"
+            },
+            {
+              "text": "ios Present for revoked transactions (iOS 15+)",
+              "name": "platform"
+            },
+            {
+              "text": "android Not available",
+              "name": "platform"
+            }
+          ],
+          "docs": "Date the transaction was revoked/refunded, in ISO 8601 format.\n\nPresent when Apple revokes access due to an issue (e.g., refund or developer issue).",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "revocationReason",
+          "tags": [
+            {
+              "text": "7.13.2",
+              "name": "since"
+            },
+            {
+              "text": "ios Present for revoked transactions (iOS 15+)",
+              "name": "platform"
+            },
+            {
+              "text": "android Not available",
+              "name": "platform"
+            }
+          ],
+          "docs": "Reason why Apple revoked the transaction.\n\nPossible 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",
+          "complexTypes": [],
+          "type": "'developerIssue' | 'other' | 'unknown' | undefined"
+        },
         {
           "name": "willCancel",
           "tags": [
@@ -451,6 +604,26 @@
           "complexTypes": [],
           "type": "boolean | null"
         },
+        {
+          "name": "subscriptionState",
+          "tags": [
+            {
+              "text": "7.13.2",
+              "name": "since"
+            },
+            {
+              "text": "ios Present for auto-renewable subscriptions (iOS 15+)",
+              "name": "platform"
+            },
+            {
+              "text": "android Not available",
+              "name": "platform"
+            }
+          ],
+          "docs": "Current subscription state reported by StoreKit.\n\nPossible 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",
+          "complexTypes": [],
+          "type": "'unknown' | 'subscribed' | 'expired' | 'revoked' | 'inGracePeriod' | 'inBillingRetryPeriod' | undefined"
+        },
         {
           "name": "purchaseState",
           "tags": [
@@ -527,11 +700,11 @@
               "name": "platform"
             },
             {
-              "text": "android Always present (should be true after successful purchase)",
+              "text": "android Always present (should be true after successful purchase or manual acknowledgment)",
               "name": "platform"
             }
           ],
-          "docs": "Whether the purchase has been acknowledged.\n\nPurchases must be acknowledged within 3 days or they will be refunded.\nThis plugin automatically acknowledges purchases.",
+          "docs": "Whether the purchase has been acknowledged.\n\nPurchases must be acknowledged within 3 days or they will be refunded.\nBy default, this plugin automatically acknowledges purchases unless you set\n`autoAcknowledgePurchases: false` in purchaseProduct().",
           "complexTypes": [],
           "type": "boolean | undefined"
         },
@@ -619,6 +792,26 @@
           "complexTypes": [],
           "type": "'Sandbox' | 'Production' | 'Xcode' | undefined"
         },
+        {
+          "name": "transactionReason",
+          "tags": [
+            {
+              "text": "7.13.2",
+              "name": "since"
+            },
+            {
+              "text": "ios Present on iOS 17.0+ (StoreKit 2 transactions)",
+              "name": "platform"
+            },
+            {
+              "text": "android Not available",
+              "name": "platform"
+            }
+          ],
+          "docs": "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",
+          "complexTypes": [],
+          "type": "'unknown' | 'purchase' | 'renewal' | undefined"
+        },
         {
           "name": "isTrialPeriod",
           "tags": [
@@ -892,6 +1085,55 @@
           "type": "() => Promise<void>"
         }
       ]
+    },
+    {
+      "name": "TransactionVerificationFailedEvent",
+      "slug": "transactionverificationfailedevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "transactionId",
+          "tags": [
+            {
+              "text": "7.13.2",
+              "name": "since"
+            },
+            {
+              "text": "ios Present when StoreKit reports an unverified transaction",
+              "name": "platform"
+            },
+            {
+              "text": "android Not available",
+              "name": "platform"
+            }
+          ],
+          "docs": "Identifier of the transaction that failed verification.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "error",
+          "tags": [
+            {
+              "text": "7.13.2",
+              "name": "since"
+            },
+            {
+              "text": "ios Always present",
+              "name": "platform"
+            },
+            {
+              "text": "android Not available",
+              "name": "platform"
+            }
+          ],
+          "docs": "Localized error message describing why verification failed.",
+          "complexTypes": [],
+          "type": "string"
+        }
+      ]
     }
   ],
   "enums": [

package/dist/esm/definitions.d.ts

@@ -140,6 +140,17 @@ export interface Transaction {
      * @platform android Not available (use purchaseToken instead)
      */
     readonly receipt?: string;
+    /**
+     * StoreKit 2 JSON Web Signature (JWS) payload describing the verified transaction.
+     *
+     * 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).
+     *
+     * @since 7.13.2
+     * @platform ios Present for StoreKit 2 transactions (iOS 15+)
+     * @platform android Not available
+     */
+    readonly jwsRepresentation?: string;
     /**
      * An optional obfuscated identifier that uniquely associates the transaction with a user account in your app.
      *
@@ -188,6 +199,17 @@ export interface Transaction {
      * @platform android Always present
      */
     readonly purchaseDate: string;
+    /**
+     * Indicates whether this transaction is the result of a subscription upgrade.
+     *
+     * Useful for understanding when StoreKit generated the transaction because
+     * the customer moved from a lower tier to a higher tier plan.
+     *
+     * @since 7.13.2
+     * @platform ios Present for auto-renewable subscriptions (iOS 15+)
+     * @platform android Not available
+     */
+    readonly isUpgraded?: boolean;
     /**
      * Original purchase date of the transaction in ISO 8601 format.
      *
@@ -221,6 +243,29 @@ export interface Transaction {
      * @platform android Not available (check purchaseState === "1" instead)
      */
     readonly isActive?: boolean;
+    /**
+     * Date the transaction was revoked/refunded, in ISO 8601 format.
+     *
+     * Present when Apple revokes access due to an issue (e.g., refund or developer issue).
+     *
+     * @since 7.13.2
+     * @platform ios Present for revoked transactions (iOS 15+)
+     * @platform android Not available
+     */
+    readonly revocationDate?: string;
+    /**
+     * Reason why Apple revoked the transaction.
+     *
+     * Possible values:
+     * - `"developerIssue"`: Developer-initiated refund or issue
+     * - `"other"`: Apple-initiated (customer refund, billing problem, etc.)
+     * - `"unknown"`: StoreKit didn't report a specific reason
+     *
+     * @since 7.13.2
+     * @platform ios Present for revoked transactions (iOS 15+)
+     * @platform android Not available
+     */
+    readonly revocationReason?: 'developerIssue' | 'other' | 'unknown';
     /**
      * Whether the subscription will be cancelled at the end of the billing cycle.
      *
@@ -234,6 +279,22 @@ export interface Transaction {
      * @platform android Always null (use Google Play Developer API for cancellation status)
      */
     readonly willCancel: boolean | null;
+    /**
+     * Current subscription state reported by StoreKit.
+     *
+     * Possible values:
+     * - `"subscribed"`: Auto-renewing and in good standing
+     * - `"expired"`: Lapsed with no access
+     * - `"revoked"`: Access removed due to refund or issue
+     * - `"inGracePeriod"`: Payment issue but still in grace access window
+     * - `"inBillingRetryPeriod"`: StoreKit retrying failed billing
+     * - `"unknown"`: StoreKit did not report a state
+     *
+     * @since 7.13.2
+     * @platform ios Present for auto-renewable subscriptions (iOS 15+)
+     * @platform android Not available
+     */
+    readonly subscriptionState?: 'subscribed' | 'expired' | 'revoked' | 'inGracePeriod' | 'inBillingRetryPeriod' | 'unknown';
     /**
      * Purchase state of the transaction (numeric string value).
      *
@@ -276,11 +337,12 @@ export interface Transaction {
      * Whether the purchase has been acknowledged.
      *
      * Purchases must be acknowledged within 3 days or they will be refunded.
-     * This plugin automatically acknowledges purchases.
+     * By default, this plugin automatically acknowledges purchases unless you set
+     * `autoAcknowledgePurchases: false` in purchaseProduct().
      *
      * @since 1.0.0
      * @platform ios Not available
-     * @platform android Always present (should be true after successful purchase)
+     * @platform android Always present (should be true after successful purchase or manual acknowledgment)
      */
     readonly isAcknowledged?: boolean;
     /**
@@ -337,6 +399,18 @@ export interface Transaction {
      * @platform android Not available
      */
     readonly environment?: 'Sandbox' | 'Production' | 'Xcode';
+    /**
+     * Reason StoreKit generated the transaction.
+     *
+     * - `"purchase"`: Initial purchase that user made manually
+     * - `"renewal"`: Automatically generated renewal for an auto-renewable subscription
+     * - `"unknown"`: StoreKit did not return a reason
+     *
+     * @since 7.13.2
+     * @platform ios Present on iOS 17.0+ (StoreKit 2 transactions)
+     * @platform android Not available
+     */
+    readonly transactionReason?: 'purchase' | 'renewal' | 'unknown';
     /**
      * Whether the transaction is in a trial period.
      *
@@ -376,6 +450,24 @@ export interface Transaction {
      */
     readonly isInGracePeriod?: boolean;
 }
+export interface TransactionVerificationFailedEvent {
+    /**
+     * Identifier of the transaction that failed verification.
+     *
+     * @since 7.13.2
+     * @platform ios Present when StoreKit reports an unverified transaction
+     * @platform android Not available
+     */
+    readonly transactionId: string;
+    /**
+     * Localized error message describing why verification failed.
+     *
+     * @since 7.13.2
+     * @platform ios Always present
+     * @platform android Not available
+     */
+    readonly error: string;
+}
 export interface SubscriptionPeriod {
     /**
      * The Subscription Period number of unit.
@@ -494,6 +586,7 @@ 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.
      */
     purchaseProduct(options: {
         productIdentifier: string;
@@ -502,6 +595,7 @@ export interface NativePurchasesPlugin {
         quantity?: number;
         appAccountToken?: string;
         isConsumable?: boolean;
+        autoAcknowledgePurchases?: boolean;
     }): Promise<Transaction>;
     /**
      * Gets the product info associated with a list of product identifiers.
@@ -579,12 +673,72 @@ export interface NativePurchasesPlugin {
      * @since 7.10.0
      */
     manageSubscriptions(): Promise<void>;
+    /**
+     * Manually acknowledge a purchase on Android.
+     *
+     * 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.
+     *
+     * **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:
+     * - 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
+     *
+     * @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)
+     * @since 7.14.0
+     *
+     * @example
+     * ```typescript
+     * // Client-side acknowledgment
+     * const transaction = await NativePurchases.purchaseProduct({
+     *   productIdentifier: 'premium_feature',
+     *   autoAcknowledgePurchases: false
+     * });
+     *
+     * // Validate with your backend
+     * const isValid = await fetch('/api/validate-purchase', {
+     *   method: 'POST',
+     *   body: JSON.stringify({ purchaseToken: transaction.purchaseToken })
+     * });
+     *
+     * if (isValid) {
+     *   // Option 1: Acknowledge from client
+     *   await NativePurchases.acknowledgePurchase({
+     *     purchaseToken: transaction.purchaseToken
+     *   });
+     *
+     *   // Option 2: Or let your backend acknowledge via Google Play API
+     *   // Your backend calls Google Play Developer API
+     * }
+     * ```
+     */
+    acknowledgePurchase(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.
      * iOS only.
      */
     addListener(eventName: 'transactionUpdated', listenerFunc: (transaction: Transaction) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for StoreKit transaction verification failures delivered by Apple's Transaction.updates.
+     * Fires when the verification result is unverified.
+     * iOS only.
+     */
+    addListener(eventName: 'transactionVerificationFailed', listenerFunc: (payload: TransactionVerificationFailedEvent) => void): Promise<PluginListenerHandle>;
     /** Remove all registered listeners */
     removeAllListeners(): Promise<void>;
 }