capacitor-plugin-cdv-purchase 13.17.2 → 13.19.1

package/www/store.d.ts

@@ -366,6 +366,18 @@ declare namespace CdvPurchase {
             /** List of verified receipts */
             verifiedReceipts: VerifiedReceipt[];
             constructor(controller: ValidatorController, log: Logger);
+            /** Maximum number of validation attempts for a receipt when failures are temporary */
+            maxAttempts: number;
+            /** Number of failed attempts in a row, per receipt */
+            private failedAttempts;
+            /** Backoff for retrying temporary failures (created on first use, it listens to the "online" event) */
+            private retry?;
+            /**
+             * Schedule a new validation if the failure is temporary and attempts remain.
+             *
+             * @return true if a retry was scheduled
+             */
+            private scheduleRetry;
             numRequests: number;
             numResponses: number;
             incrRequestsCounter(): void;
@@ -393,6 +405,20 @@ declare namespace CdvPurchase {
             private removeExpiredCache;
             private runValidatorRequest;
         }
+        /**
+         * True if a validation error is temporary (validator or store unreachable,
+         * server error, timeout, no network) rather than a definitive answer about
+         * the receipt.
+         *
+         * Error responses from the validator come in two shapes:
+         * - HTTP 200 with `{ ok: false, status, code }` in the body (iaptic does this,
+         *   so a store outage is `status: 502, code: 6778002` in the body);
+         * - a failed HTTP request, reported by the plugin as `code: COMMUNICATION`
+         *   with the transport status: 5xx, 408 (timeout), 417 (unreadable response,
+         *   e.g. a captive portal page), 0 or negative (no network, as reported by
+         *   XMLHttpRequest or cordova-plugin-advanced-http).
+         */
+        function isTransientError(payload: Validator.Response.ErrorPayload): boolean;
     }
 }
 declare namespace CdvPurchase {
@@ -879,6 +905,141 @@ declare namespace CdvPurchase {
         function md5toUUID(str: string): string;
     }
 }
+declare namespace CdvPurchase {
+    /** Storage adapter for persisting offline entitlements. */
+    interface OfflineStorageAdapter {
+        getItem(key: string): Promise<string | null>;
+        setItem(key: string, value: string): Promise<void>;
+        removeItem(key: string): Promise<void>;
+    }
+    /** Options for {@link OfflineEntitlements}. */
+    interface OfflineEntitlementsOptions {
+        /** Storage adapter. Defaults to a `localStorage` wrapper. */
+        storage?: OfflineStorageAdapter;
+        /** Grace period in milliseconds after a subscription's expiryDate during which it's still considered owned. Defaults to 30 days. */
+        gracePeriodMs?: number;
+        /** Behavior when the grace period has elapsed and the device is still offline. `'readonly'` keeps granting access; `'deny'` revokes it. Defaults to `'readonly'`. */
+        onExpiredOffline?: 'deny' | 'readonly';
+        /** If true, detect clock rollback (persisted lastSeenTimestamp is in the future relative to now) and deny access. */
+        detectClockRollback?: boolean;
+    }
+    /** Event emitted by {@link OfflineEntitlements} when evaluating ownership offline. */
+    interface OfflineEntitlementEvent {
+        type: 'grace' | 'readonly' | 'clock_rollback' | 'entitlement_missing' | 'expired';
+        productId: string;
+        message: string;
+    }
+    /**
+     * Persist a subset of {@link VerifiedPurchase} to device storage so that
+     * `offline.isOwned()` can answer "is this product owned?" when the device
+     * is offline or has just restarted without connectivity.
+     *
+     * Phase 1 — unsigned cache. No JWT, no crypto, no server changes.
+     *
+     * @example
+     * ```typescript
+     * const offline = new CdvPurchase.OfflineEntitlements(store, {
+     *     gracePeriodMs: 30 * 24 * 60 * 60 * 1000, // 30 days
+     *     onExpiredOffline: 'readonly',
+     *     detectClockRollback: true,
+     * });
+     *
+     * await offline.ready();
+     *
+     * function isUserPremium(): boolean {
+     *     return store.owned('premium') || offline.isOwned('premium');
+     * }
+     * ```
+     *
+     * **Durability warning:** for long-offline deployments (weeks without
+     * connectivity), pass a file-based or secure-storage adapter. `localStorage`
+     * (the default) can be evicted by the WebView under storage pressure, which
+     * would silently lose the cached entitlements.
+     */
+    class OfflineEntitlements {
+        /** Storage key used in the storage adapter. */
+        private static STORAGE_KEY;
+        /** Schema version for the persisted payload. */
+        private static SCHEMA_VERSION;
+        /** Default grace period: 30 days. */
+        private static DEFAULT_GRACE_PERIOD_MS;
+        private store;
+        private storage;
+        private gracePeriodMs;
+        private onExpiredOffline;
+        private detectClockRollback;
+        /** In-memory cache of persisted entitlements, keyed by `platform:productId`. */
+        private cache;
+        /** Last seen timestamp persisted with the data, used for clock rollback detection. */
+        private lastSeenTimestamp;
+        /** True once `ready()` has resolved. */
+        private isReady;
+        /** Event callbacks. */
+        private eventCallbacks;
+        /** Last event fired per productId, to deduplicate events on repeated isOwned() calls. */
+        private lastEventPerProduct;
+        constructor(store: Store, options?: OfflineEntitlementsOptions);
+        /** Wrap the global `localStorage` as an async `OfflineStorageAdapter`. */
+        private static createLocalStorageAdapter;
+        /** Load persisted entitlements from storage into the in-memory cache. Idempotent. */
+        ready(): Promise<void>;
+        /** Reload from storage and re-evaluate. Resolves when the reload is complete. Call after reconnecting or manually. */
+        refresh(): Promise<void>;
+        /** Register a callback for {@link OfflineEntitlementEvent}s. */
+        onEvent(callback: Callback<OfflineEntitlementEvent>): void;
+        /** Remove all persisted entitlements from storage and clear the in-memory cache. For user logout. */
+        clear(): Promise<void>;
+        /**
+         * Return `true` if the product is owned, using the persisted cache when
+         * the in-memory `verifiedReceipts` don't grant ownership.
+         *
+         * Returns `false` for all products until `ready()` has resolved.
+         */
+        isOwned(productId: string): boolean;
+        /**
+         * Retrieve the persisted entitlement for a product, analogous to
+         * `store.findInVerifiedReceipts()`.
+         *
+         * Returns the {@link PersistedPurchase} (with `expiryDate`,
+         * `renewalIntent`, `lastRenewalDate`, etc.) if one has been cached,
+         * or `undefined` if no offline entitlement exists for this product.
+         *
+         * Returns `undefined` for all products until `ready()` has resolved.
+         *
+         * @example
+         * ```typescript
+         * const entitlement = offline.find('premium');
+         * if (entitlement?.expiryDate) {
+         *     const daysLeft = Math.ceil((entitlement.expiryDate - Date.now()) / 86400000);
+         *     showRenewalBanner(daysLeft);
+         * }
+         * ```
+         */
+        find(productId: string): PersistedPurchase | undefined;
+        /** Persist all `VerifiedPurchase`s in a verified receipt to storage. */
+        private onVerified;
+        /** Find the persisted purchase for a productId across all platforms. */
+        private findPersisted;
+        /** Load the persisted payload from storage into the in-memory cache. */
+        private loadFromStorage;
+        /** Serialize the in-memory cache to storage. */
+        private saveToStorage;
+        /** Fire an event to all registered callbacks, deduplicating per productId. */
+        private fireEvent;
+    }
+    /** Persisted subset of {@link VerifiedPurchase}, stored by the offline entitlements layer. */
+    interface PersistedPurchase {
+        id: string;
+        platform: Platform;
+        expiryDate?: number;
+        isExpired?: boolean;
+        renewalIntent?: string;
+        lastRenewalDate?: number;
+        purchaseDate?: number;
+        cancelationReason?: CancelationReason;
+        isBillingRetryPeriod?: boolean;
+    }
+}
 /**
  * Namespace for the cordova-plugin-purchase plugin.
  *
@@ -911,7 +1072,7 @@ declare namespace CdvPurchase {
     /**
      * Current release number of the plugin.
      */
-    const PLUGIN_VERSION = "13.17.2";
+    const PLUGIN_VERSION = "13.19.1";
     /**
      * Entry class of the plugin.
      */
@@ -2046,7 +2207,23 @@ declare namespace CdvPurchase {
         lastRenewalDate?: Date;
         /** Time when the subscription is set to expire following this transaction */
         expirationDate?: Date;
-        /** True when the transaction has been acknowledged to the platform. */
+        /**
+         * True when the transaction has been acknowledged to the platform.
+         *
+         * - Google Play: the purchase was acknowledged (or consumed).
+         * - Apple App Store (StoreKit 2, Capacitor build only): the transaction was finished. StoreKit 2 re-reports
+         *   finished non-consumables and non-renewing subscriptions as `approved` at every
+         *   app launch; check this flag in your `approved()` handler to skip delivering them again.
+         *
+         * Undefined when the platform doesn't report it (including StoreKit 1 and the Cordova
+         * `cordova-plugin-purchase-storekit2` plugin).
+         *
+         * @example
+         * store.when().approved(transaction => {
+         *   if (transaction.isAcknowledged) return transaction.finish(); // already delivered
+         *   deliver(transaction).then(() => transaction.finish());
+         * });
+         */
         isAcknowledged?: boolean;
         /** True when the transaction is still pending payment. */
         isPending?: boolean;
@@ -2880,7 +3057,7 @@ declare namespace CdvPurchase {
             /** Extended callbacks with SK2 fields (same as SK2BridgeCallbacks) */
             interface CapacitorBridgeCallbacks extends Bridge.BridgeCallbacks {
                 purchased: (transactionIdentifier: string, productId: string, originalTransactionIdentifier?: string, transactionDate?: string, discountId?: string, expirationDate?: string, jwsRepresentation?: string, quantity?: number) => void;
-                restored: (transactionIdentifier: string, productId: string, originalTransactionIdentifier?: string, transactionDate?: string, discountId?: string, expirationDate?: string, jwsRepresentation?: string, quantity?: number) => void;
+                restored: (transactionIdentifier: string, productId: string, originalTransactionIdentifier?: string, transactionDate?: string, discountId?: string, expirationDate?: string, jwsRepresentation?: string, quantity?: number, isFinished?: boolean) => void;
             }
             class CapacitorNativeBridge implements Bridge.BridgeInterface {
                 appStoreReceipt: ApplicationReceipt | null;
@@ -3144,8 +3321,14 @@ declare namespace CdvPurchase {
                 deferred: (productId: string) => void;
                 /** Called when a transaction is in "finished" state */
                 finished: (transactionIdentifier: string, productId: string) => void;
-                /** Called when a transaction is in "restored" state */
-                restored: (transactionIdentifier: string, productId: string, originalTransactionIdentifier?: string, transactionDate?: string, discountId?: string, expirationDate?: string, jwsRepresentation?: string, quantity?: number) => void;
+                /**
+                 * Called when a transaction is in "restored" state.
+                 *
+                 * `isFinished` is set by StoreKit 2 bridges when known: true when the app
+                 * already finished the transaction (e.g. a finished entitlement re-emitted
+                 * at launch), false when it is still unfinished.
+                 */
+                restored: (transactionIdentifier: string, productId: string, originalTransactionIdentifier?: string, transactionDate?: string, discountId?: string, expirationDate?: string, jwsRepresentation?: string, quantity?: number, isFinished?: boolean) => void;
                 /** Called when the application receipt is refreshed */
                 receiptsRefreshed: (receipt: ApplicationReceipt) => void;
                 /** Called when a call to "restore" failed */
@@ -6579,6 +6762,31 @@ declare namespace CdvPurchase {
     interface UnverifiedReceipt {
         receipt: Receipt;
         payload: Validator.Response.ErrorPayload;
+        /**
+         * True when validation failed for a temporary reason: the validator
+         * (or the store behind it) couldn't be reached, timed out, or answered
+         * with a server error. The receipt may well be valid.
+         *
+         * Don't revoke access on a transient failure: keep what your app (or
+         * your server) last knew, and validate again later.
+         *
+         * The plugin already retried a few times (with backoff) before firing
+         * a transient failure.
+         *
+         * False when the validator gave a definitive answer (e.g. invalid
+         * receipt, expired subscription, authentication error).
+         *
+         * Transient:
+         * - HTTP 5xx, from the transport or as `payload.status` in the response body
+         * - `CONNECTION_FAILED` (6778002) from the validator
+         * - request timeout, no network, unreadable response
+         *
+         * Definitive: everything else (HTTP 400 `INVALID_PAYLOAD`, 401/403, 410,
+         * 419 expired, ...).
+         *
+         * Set by the plugin on every `unverified` event since v13.19.0.
+         */
+        transient?: boolean;
     }
     /** Receipt data as validated by the receipt validation server */
     class VerifiedReceipt {