@entitlehub/react-native 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,18 +1,56 @@
 # Changelog
 
-## 0.1.6 — 2026-07-21
+## 0.1.8 (2026-09-19)
+
+### Fixed
+- **Black screen on launch: "Requiring unknown module expo-iap".** The SDK loaded `expo-iap` with
+  `require()`. Metro decides what to bundle by reading literal `require("…")` / `import("…")` calls,
+  and the ESM build rewrote that call into esbuild's `__require` shim, which Metro cannot see. So
+  `expo-iap` was never put in the bundle, the first call threw, and React Native tore the UI down
+  with it, before the store sheet ever opened. It is now loaded with `import("expo-iap")`, which
+  survives the build as a literal. Verified by bundling a real Expo app: with 0.1.7 the store
+  library is absent from the bundle, with 0.1.8 it is there.
+- The module now loads while `configureEntitleHub()` runs, so a missing or broken `expo-iap` raises
+  a clear error there instead of being swallowed by the store-connection catch, and handles CJS
+  interop (module namespace or `.default`).
+
+### Changed
+- `configureEntitleHub({ iap })` is no longer a workaround for the bug above, just the way to pin an
+  exact module instance or use another OpenIAP-compatible library.
+
+## 0.1.7 (2026-07-22)
+
+### Fixed
+- **A completed purchase could still be reported as failed.** After a timeout, `purchaseProduct()`
+  checked for confirmation exactly once. Store notifications are asynchronous, so that single
+  reading races the grant and sometimes loses, observed live: the entitlement was written seconds
+  after the check ran, and the user saw a purchase-failed error for a purchase that worked. It now
+  polls the store and the server with backoff (`reconcileMs`, default 30s) before giving up.
+- **The timeout counted the user's own time.** The timer was armed when `purchaseProduct()` was
+  called: before the store's password / Face ID sheet appears, so a user who paused mid-purchase
+  tripped it. It now starts once the request is actually in flight, with a separate generous
+  backstop (`sheetTimeoutMs`, default 10m) so a stuck bridge still can't hang forever.
+
+### Changed
+- **Rejections are now typed `PurchaseError`s: branch on `.code`, not the message.**
+  `purchase-cancelled`, `purchase-failed`, and the new `purchase-pending`. **`purchase-pending` is
+  not a failure**: the store took the money but hasn't confirmed yet. Show "still confirming", the
+  entitlement lands on its own and `addCustomerInfoUpdateListener` fires when it does. `.pending`
+  and `.customerInfo` are on the error. The old untyped `"purchase-timeout"` message is gone.
+
+## 0.1.6 (2026-07-21)
 
 ### Added
 - Reports `react-native/<version>` to EntitleHub on each call, so the dashboard can tell you when
-  your SDK is behind a release with fixes in it — rather than you finding out by hitting the bug.
+  your SDK is behind a release with fixes in it, rather than you finding out by hitting the bug.
   Version only; no device or user data.
 
-## 0.1.5 — 2026-07-21
+## 0.1.5 (2026-07-21)
 
 ### Fixed
 - **`purchaseProduct()` could hang forever after a successful purchase.** It waited only on
   `purchaseUpdatedListener`; on the react-native-iap 15+ / Nitro bridge that callback never fires,
-  so the promise never settled — the paywall stayed open and features stayed locked even though the
+  so the promise never settled: the paywall stayed open and features stayed locked even though the
   user had been charged and EntitleHub had already granted the entitlement server-side.
   `requestPurchase`'s resolved value was being discarded entirely; it is now honoured, so bridges
   that resolve instead of emitting an event work.
@@ -20,14 +58,14 @@
 ### Added
 - Reconciliation safety net: if no result arrives within `timeoutMs` (default 120s),
   `purchaseProduct()` re-reads `getAvailablePurchases()` and, failing that, re-checks entitlements
-  from the server — resolving successfully if the entitlement appeared while the client was waiting.
+  from the server: resolving successfully if the entitlement appeared while the client was waiting.
   Only rejects (`"purchase-timeout"`) when nothing was actually granted.
 - `purchaseProduct(id, { timeoutMs })` to tune that window.
 
-## 0.1.2 — 2026-07-18
+## 0.1.2 (2026-07-18)
 
 ### Added
-- `configureEntitleHub({ iap })` — inject the OpenIAP-compatible store module (pinned expo-iap
+- `configureEntitleHub({ iap })`: inject the OpenIAP-compatible store module (pinned expo-iap
   version, or react-native-iap) instead of the hard-coded `expo-iap`. Decouples this SDK from a
   single store-library version so you can work around a native issue without changing the SDK.
 
@@ -36,17 +74,17 @@
   thread) are a store-library-version concern; how to pin a version, inject a module, or fall back
   to the fully-decoupled `@entitlehub/sdk` + your own billing library.
 
-## 0.1.1 — 2026-07-18
+## 0.1.1 (2026-07-18)
 
 ### Fixed
-- **`purchaseProduct` crashed** — 0.1.0 was written against expo-iap's old flat `requestPurchase`
+- **`purchaseProduct` crashed**: 0.1.0 was written against expo-iap's old flat `requestPurchase`
   API and read the purchase from the return value. `expo-iap@4.x` is **event-based** with a
   discriminated request. Now: `requestPurchase({ request: { apple: { sku }, google: { skus } },
   type })` with the result bridged from `purchaseUpdatedListener` / `purchaseErrorListener`.
 - Android subscriptions now pass the required `offerToken` (fetched from the product).
 - `getProducts` uses expo-iap's `fetchProducts` (the old `getProducts` no longer exists).
 
-## 0.1.0 — 2026-07-18
+## 0.1.0 (2026-07-18)
 
 Initial release.
 

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@entitlehub/react-native)](https://www.npmjs.com/package/@entitlehub/react-native)
 [![license MIT](https://img.shields.io/npm/l/@entitlehub/react-native)](./LICENSE)
 
-EntitleHub for **React Native & Expo** — one call to purchase and unlock entitlements. It opens the
+EntitleHub for **React Native & Expo**: one call to purchase and unlock entitlements. It opens the
 native store sheet (via [`expo-iap`](https://github.com/hyochan/expo-iap)), validates the receipt
 with EntitleHub server-side, and hands you the updated entitlements. The RevenueCat developer
 experience, on EntitleHub.
@@ -26,7 +26,7 @@ await configureEntitleHub({ apiKey: "pk_live_…", appUserId: user.id });
 // gate a feature:
 if (await isEntitled("pro")) unlockPro();
 
-// buy — opens the native sheet, validates, returns entitlements:
+// buy: opens the native sheet, validates, returns entitlements:
 const info = await purchaseProduct("app_pro_monthly", { isSubscription: true });
 if (info.isActive("pro")) unlockPro();
 
@@ -45,7 +45,7 @@ const restored = await restorePurchases();
 | `addCustomerInfoUpdateListener(fn)` | React to entitlement changes. |
 
 Only your **publishable** key (`pk_`) ships in the app. EntitleHub validates the Apple/Google
-receipt server-side, so a forged one is rejected — no secret key on the device.
+receipt server-side, so a forged one is rejected, no secret key on the device.
 
 ## How it works
 
@@ -60,22 +60,25 @@ Full guide: **[entitlehub.com/docs/purchases](https://entitlehub.com/docs/purcha
 ## Choosing / pinning the store library
 
 The on-device purchase runs through **expo-iap** (OpenIAP). That native layer is the store
-library's responsibility, not EntitleHub's — and a given version can have platform-specific native
+library's responsibility, not EntitleHub's, and a given version can have platform-specific native
 bugs. If you hit a **native IAP crash** (e.g. an `EXC_BAD_ACCESS` in the store module), it's the
 store library, not this SDK or your app code, and no JS change can catch a native exception thrown
 off the JS thread.
 
 Two levers, both without changing this SDK:
 
-- **Pin a working version:** `npm install expo-iap@<version>` — this package uses whatever `expo-iap`
+- **Pin a working version:** `npm install expo-iap@<version>`, this package uses whatever `expo-iap`
   is installed (peer dependency).
-- **Supply your own module:** pass any OpenIAP-compatible library to `configureEntitleHub`:
+- **Supply your own module:** pass any OpenIAP-compatible library to `configureEntitleHub`. You do
+  not need this to use `expo-iap`, which is loaded for you; it is for pinning an exact instance or
+  using a different library:
   ```ts
-  await configureEntitleHub({ apiKey, appUserId, iap: require("expo-iap") }); // or react-native-iap
+  import * as iap from "expo-iap"; // or react-native-iap
+  await configureEntitleHub({ apiKey, appUserId, iap });
   ```
 
 Fully decoupled fallback: skip this package and use **[`@entitlehub/sdk`](https://www.npmjs.com/package/@entitlehub/sdk)**
-directly — open the purchase with *any* billing library you've verified on your target OS, then call
+directly: open the purchase with *any* billing library you've verified on your target OS, then call
 `eh.reportPurchase({ signedTransaction | purchaseToken })`. See
 [Purchases → manual](https://entitlehub.com/docs/purchases).
 

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,11 +17,20 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  PurchaseError: () => PurchaseError,
   addCustomerInfoUpdateListener: () => addCustomerInfoUpdateListener,
   configureEntitleHub: () => configureEntitleHub,
   getCustomerInfo: () => getCustomerInfo,
@@ -33,16 +44,25 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_sdk = require("@entitlehub/sdk");
 var _iap;
-function iap() {
+async function loadIap() {
   if (_iap) return _iap;
+  let mod;
   try {
-    _iap = require("expo-iap");
+    mod = await import("expo-iap");
   } catch {
     throw new Error("@entitlehub/react-native needs 'expo-iap'. Install it with:  npx expo install expo-iap");
   }
+  _iap = typeof mod?.initConnection === "function" ? mod : mod?.default ?? mod;
+  if (typeof _iap?.initConnection !== "function") {
+    throw new Error("@entitlehub/react-native: the 'expo-iap' module did not load correctly (no initConnection). Check that expo-iap is installed and its version supports the OpenIAP API.");
+  }
+  return _iap;
+}
+function iap() {
+  if (!_iap) throw new Error("Call configureEntitleHub({ apiKey, appUserId }) before using EntitleHub purchases.");
   return _iap;
 }
-var RN_SDK_VERSION = "0.1.6";
+var RN_SDK_VERSION = "0.1.8";
 var client;
 function eh() {
   if (!client) throw new Error("Call configureEntitleHub({ apiKey, appUserId }) before using EntitleHub.");
@@ -50,6 +70,7 @@ function eh() {
 }
 async function configureEntitleHub(opts) {
   if (opts.iap) _iap = opts.iap;
+  else await loadIap();
   client = new import_sdk.EntitleHub({
     apiKey: opts.apiKey,
     appUserId: opts.appUserId,
@@ -77,11 +98,25 @@ async function getProducts(productIds, type = "all") {
   return iap().fetchProducts({ skus: productIds, type });
 }
 var DEFAULT_PURCHASE_TIMEOUT_MS = 12e4;
+var DEFAULT_SHEET_TIMEOUT_MS = 6e5;
+var DEFAULT_RECONCILE_MS = 3e4;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var PurchaseError = class extends Error {
+  constructor(code, message, customerInfo) {
+    super(message);
+    this.name = "PurchaseError";
+    this.code = code;
+    this.pending = code === "purchase-pending";
+    this.customerInfo = customerInfo;
+  }
+};
 async function purchaseProduct(productId, opts = {}) {
   const I = iap();
   const isSub = Boolean(opts.isSubscription);
   const isConsumable = Boolean(opts.isConsumable) && !isSub;
   const timeoutMs = opts.timeoutMs ?? DEFAULT_PURCHASE_TIMEOUT_MS;
+  const sheetTimeoutMs = opts.sheetTimeoutMs ?? DEFAULT_SHEET_TIMEOUT_MS;
+  const reconcileMs = opts.reconcileMs ?? DEFAULT_RECONCILE_MS;
   let entitlementsBefore = [];
   try {
     entitlementsBefore = (await eh().getCustomerInfo()).activeEntitlementIds;
@@ -136,26 +171,43 @@ async function purchaseProduct(productId, opts = {}) {
     };
     const isPurchase = (p) => Boolean(p) && Boolean(p.purchaseToken || p.jwsRepresentation || p.jwsRepresentationIos || p.purchaseTokenAndroid || p.transactionId || p.transactionReceipt || p.id);
     const reconcile = async () => {
-      if (settled) return;
-      try {
-        const owned = await I.getAvailablePurchases() || [];
-        const match = owned.find((p) => (p?.productId ?? p?.id ?? p?.sku) === productId);
-        if (match) return settleWithPurchase(match);
-      } catch {
-      }
-      try {
-        const info = await eh().getCustomerInfo({ fetchPolicy: "network-only" });
-        const grew = info.activeEntitlementIds.some((id) => !entitlementsBefore.includes(id));
-        if (grew) {
-          if (settled) return;
-          settled = true;
-          cleanup();
-          resolve(info);
-          return;
+      const deadline = Date.now() + reconcileMs;
+      let wait = 2e3;
+      let lastInfo;
+      while (!settled) {
+        try {
+          const owned = await I.getAvailablePurchases() || [];
+          const match = owned.find((p) => (p?.productId ?? p?.id ?? p?.sku) === productId);
+          if (match) return settleWithPurchase(match);
+        } catch {
         }
-      } catch {
+        try {
+          lastInfo = await eh().getCustomerInfo({ fetchPolicy: "network-only" });
+          if (lastInfo.activeEntitlementIds.some((id) => !entitlementsBefore.includes(id))) {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            resolve(lastInfo);
+            return;
+          }
+        } catch {
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) break;
+        await sleep(Math.min(wait, remaining));
+        wait = Math.min(wait * 1.5, 8e3);
       }
-      fail(new Error("purchase-timeout"));
+      fail(new PurchaseError(
+        "purchase-pending",
+        "The store hasn't confirmed this purchase yet. It may still complete, show a pending state, not a failure.",
+        lastInfo
+      ));
+    };
+    const armTimer = (ms) => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        void reconcile();
+      }, ms);
     };
     const updSub = I.purchaseUpdatedListener((purchase) => {
       void settleWithPurchase(purchase);
@@ -163,17 +215,21 @@ async function purchaseProduct(productId, opts = {}) {
     const errSub = I.purchaseErrorListener((error) => {
       const code = error?.code;
       const cancelled = code === "E_USER_CANCELLED" || code === "user-cancelled" || /cancel/i.test(String(error?.message));
-      fail(new Error(cancelled ? "purchase-cancelled" : error?.message || "purchase-failed"));
+      fail(cancelled ? new PurchaseError("purchase-cancelled", "The user cancelled the purchase.") : new PurchaseError("purchase-failed", error?.message || "The purchase failed."));
     });
     Promise.resolve(
       I.requestPurchase({ request, type: isSub ? "subs" : "in-app" })
     ).then((res) => {
       const p = Array.isArray(res) ? res.find(isPurchase) : res;
-      if (isPurchase(p)) void settleWithPurchase(p);
-    }).catch((e) => fail(e));
-    timer = setTimeout(() => {
-      void reconcile();
-    }, timeoutMs);
+      if (isPurchase(p)) {
+        void settleWithPurchase(p);
+        return;
+      }
+      armTimer(timeoutMs);
+    }).catch((e) => fail(
+      e instanceof PurchaseError ? e : new PurchaseError("purchase-failed", e?.message || "The purchase failed.")
+    ));
+    armTimer(sheetTimeoutMs);
   });
 }
 async function restorePurchases() {
@@ -204,6 +260,7 @@ async function reportToEntitleHub(purchase, productId, isSubscription) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PurchaseError,
   addCustomerInfoUpdateListener,
   configureEntitleHub,
   getCustomerInfo,

package/dist/index.d.cts

@@ -13,9 +13,8 @@ interface ConfigureOptions {
      * `fetchProducts`, `requestPurchase`, `purchaseUpdatedListener`, `purchaseErrorListener`,
      * `finishTransaction`, `getAvailablePurchases`). Defaults to `expo-iap`.
      *
-     * Pass your own if you need a specific version or a different OpenIAP-compatible library, e.g.
-     * `iap: require("expo-iap")` with a pinned version, or `react-native-iap`. Useful to work around
-     * a native issue in a particular store-library version without changing this SDK.
+     * Optional. Pass your own only to pin a specific version or to use a different OpenIAP-compatible
+     * library (e.g. `react-native-iap`); expo-iap is loaded for you otherwise.
      */
     iap?: unknown;
 }
@@ -31,30 +30,55 @@ declare function isEntitled(entitlementId: string): Promise<boolean>;
 declare function getOfferings(): Promise<Offerings>;
 /** Live store products (prices, localized titles) from the native store (expo-iap `fetchProducts`). */
 declare function getProducts(productIds: string[], type?: "in-app" | "subs" | "all"): Promise<any[]>;
+/** Why a purchase didn't complete. Check `code`, never match on the message. */
+type PurchaseErrorCode = "purchase-cancelled" | "purchase-pending" | "purchase-failed";
+/**
+ * A purchase that didn't return entitlements.
+ *
+ * `code === "purchase-pending"` is NOT a failure: the store took the money but confirmation hasn't
+ * reached us yet (store notifications are asynchronous). Show "still confirming", not an error,
+ * the entitlement will arrive on its own, and `addCustomerInfoUpdateListener` will fire when it does.
+ */
+declare class PurchaseError extends Error {
+    readonly code: PurchaseErrorCode;
+    /** True when the purchase probably succeeded and is just unconfirmed. */
+    readonly pending: boolean;
+    /** Last known entitlements, if we managed to read them. */
+    readonly customerInfo?: CustomerInfo;
+    constructor(code: PurchaseErrorCode, message: string, customerInfo?: CustomerInfo);
+}
 /**
  * Buy a product in one call: open the native purchase sheet, validate the receipt with EntitleHub,
  * and return the updated entitlements. Purchase + entitlement sync, the RevenueCat way.
  *
  * Store bridges disagree about how the result comes back, so we accept it from any source and never
  * hang waiting for one of them:
- *  1. `purchaseUpdatedListener` — expo-iap's event-based flow.
- *  2. `requestPurchase`'s resolved value — react-native-iap 15+ / Nitro resolves with the purchase
+ *  1. `purchaseUpdatedListener`: expo-iap's event-based flow.
+ *  2. `requestPurchase`'s resolved value: react-native-iap 15+ / Nitro resolves with the purchase
  *     and may never emit the event.
- *  3. Reconciliation after `timeoutMs` — re-read `getAvailablePurchases()`, and failing that check
+ *  3. Reconciliation after `timeoutMs`: re-read `getAvailablePurchases()`, and failing that check
  *     whether the entitlement appeared server-side anyway (EntitleHub's store-notification webhook
  *     grants it independently of the client).
  *
- * Rejects with "purchase-cancelled" if the user backs out, "purchase-timeout" if nothing arrived
- * and nothing was granted.
+ * Rejects with a `PurchaseError`; branch on `.code`, never the message:
+ *   - `purchase-cancelled`: the user backed out.
+ *   - `purchase-pending`  : the store took the money but hasn't confirmed. NOT a failure; show a
+ *                            pending state. `.pending` is true and the entitlement will land on its own.
+ *   - `purchase-failed`   : a real failure.
  */
 declare function purchaseProduct(productId: string, opts?: {
     isSubscription?: boolean;
     isConsumable?: boolean;
+    /** Wait for the store's result once the request is in flight (default 120s). */
     timeoutMs?: number;
+    /** Absolute backstop from the call, covering time spent in the store's own sheet (default 10m). */
+    sheetTimeoutMs?: number;
+    /** How long to poll for confirmation before reporting pending (default 30s). */
+    reconcileMs?: number;
 }): Promise<CustomerInfo>;
 /** Restore the user's purchases: re-validate each with EntitleHub, then return entitlements. */
 declare function restorePurchases(): Promise<CustomerInfo>;
 /** Subscribe to entitlement changes (e.g. after a purchase). Returns an unsubscribe function. */
 declare function addCustomerInfoUpdateListener(fn: (info: CustomerInfo) => void): () => void;
 
-export { type ConfigureOptions, addCustomerInfoUpdateListener, configureEntitleHub, getCustomerInfo, getOfferings, getProducts, isEntitled, logIn, purchaseProduct, restorePurchases };
+export { type ConfigureOptions, PurchaseError, type PurchaseErrorCode, addCustomerInfoUpdateListener, configureEntitleHub, getCustomerInfo, getOfferings, getProducts, isEntitled, logIn, purchaseProduct, restorePurchases };

package/dist/index.d.ts

@@ -13,9 +13,8 @@ interface ConfigureOptions {
      * `fetchProducts`, `requestPurchase`, `purchaseUpdatedListener`, `purchaseErrorListener`,
      * `finishTransaction`, `getAvailablePurchases`). Defaults to `expo-iap`.
      *
-     * Pass your own if you need a specific version or a different OpenIAP-compatible library, e.g.
-     * `iap: require("expo-iap")` with a pinned version, or `react-native-iap`. Useful to work around
-     * a native issue in a particular store-library version without changing this SDK.
+     * Optional. Pass your own only to pin a specific version or to use a different OpenIAP-compatible
+     * library (e.g. `react-native-iap`); expo-iap is loaded for you otherwise.
      */
     iap?: unknown;
 }
@@ -31,30 +30,55 @@ declare function isEntitled(entitlementId: string): Promise<boolean>;
 declare function getOfferings(): Promise<Offerings>;
 /** Live store products (prices, localized titles) from the native store (expo-iap `fetchProducts`). */
 declare function getProducts(productIds: string[], type?: "in-app" | "subs" | "all"): Promise<any[]>;
+/** Why a purchase didn't complete. Check `code`, never match on the message. */
+type PurchaseErrorCode = "purchase-cancelled" | "purchase-pending" | "purchase-failed";
+/**
+ * A purchase that didn't return entitlements.
+ *
+ * `code === "purchase-pending"` is NOT a failure: the store took the money but confirmation hasn't
+ * reached us yet (store notifications are asynchronous). Show "still confirming", not an error,
+ * the entitlement will arrive on its own, and `addCustomerInfoUpdateListener` will fire when it does.
+ */
+declare class PurchaseError extends Error {
+    readonly code: PurchaseErrorCode;
+    /** True when the purchase probably succeeded and is just unconfirmed. */
+    readonly pending: boolean;
+    /** Last known entitlements, if we managed to read them. */
+    readonly customerInfo?: CustomerInfo;
+    constructor(code: PurchaseErrorCode, message: string, customerInfo?: CustomerInfo);
+}
 /**
  * Buy a product in one call: open the native purchase sheet, validate the receipt with EntitleHub,
  * and return the updated entitlements. Purchase + entitlement sync, the RevenueCat way.
  *
  * Store bridges disagree about how the result comes back, so we accept it from any source and never
  * hang waiting for one of them:
- *  1. `purchaseUpdatedListener` — expo-iap's event-based flow.
- *  2. `requestPurchase`'s resolved value — react-native-iap 15+ / Nitro resolves with the purchase
+ *  1. `purchaseUpdatedListener`: expo-iap's event-based flow.
+ *  2. `requestPurchase`'s resolved value: react-native-iap 15+ / Nitro resolves with the purchase
  *     and may never emit the event.
- *  3. Reconciliation after `timeoutMs` — re-read `getAvailablePurchases()`, and failing that check
+ *  3. Reconciliation after `timeoutMs`: re-read `getAvailablePurchases()`, and failing that check
  *     whether the entitlement appeared server-side anyway (EntitleHub's store-notification webhook
  *     grants it independently of the client).
  *
- * Rejects with "purchase-cancelled" if the user backs out, "purchase-timeout" if nothing arrived
- * and nothing was granted.
+ * Rejects with a `PurchaseError`; branch on `.code`, never the message:
+ *   - `purchase-cancelled`: the user backed out.
+ *   - `purchase-pending`  : the store took the money but hasn't confirmed. NOT a failure; show a
+ *                            pending state. `.pending` is true and the entitlement will land on its own.
+ *   - `purchase-failed`   : a real failure.
  */
 declare function purchaseProduct(productId: string, opts?: {
     isSubscription?: boolean;
     isConsumable?: boolean;
+    /** Wait for the store's result once the request is in flight (default 120s). */
     timeoutMs?: number;
+    /** Absolute backstop from the call, covering time spent in the store's own sheet (default 10m). */
+    sheetTimeoutMs?: number;
+    /** How long to poll for confirmation before reporting pending (default 30s). */
+    reconcileMs?: number;
 }): Promise<CustomerInfo>;
 /** Restore the user's purchases: re-validate each with EntitleHub, then return entitlements. */
 declare function restorePurchases(): Promise<CustomerInfo>;
 /** Subscribe to entitlement changes (e.g. after a purchase). Returns an unsubscribe function. */
 declare function addCustomerInfoUpdateListener(fn: (info: CustomerInfo) => void): () => void;
 
-export { type ConfigureOptions, addCustomerInfoUpdateListener, configureEntitleHub, getCustomerInfo, getOfferings, getProducts, isEntitled, logIn, purchaseProduct, restorePurchases };
+export { type ConfigureOptions, PurchaseError, type PurchaseErrorCode, addCustomerInfoUpdateListener, configureEntitleHub, getCustomerInfo, getOfferings, getProducts, isEntitled, logIn, purchaseProduct, restorePurchases };

package/dist/index.js

@@ -1,23 +1,25 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/index.ts
 import { EntitleHub } from "@entitlehub/sdk";
 var _iap;
-function iap() {
+async function loadIap() {
   if (_iap) return _iap;
+  let mod;
   try {
-    _iap = __require("expo-iap");
+    mod = await import("expo-iap");
   } catch {
     throw new Error("@entitlehub/react-native needs 'expo-iap'. Install it with:  npx expo install expo-iap");
   }
+  _iap = typeof mod?.initConnection === "function" ? mod : mod?.default ?? mod;
+  if (typeof _iap?.initConnection !== "function") {
+    throw new Error("@entitlehub/react-native: the 'expo-iap' module did not load correctly (no initConnection). Check that expo-iap is installed and its version supports the OpenIAP API.");
+  }
+  return _iap;
+}
+function iap() {
+  if (!_iap) throw new Error("Call configureEntitleHub({ apiKey, appUserId }) before using EntitleHub purchases.");
   return _iap;
 }
-var RN_SDK_VERSION = "0.1.6";
+var RN_SDK_VERSION = "0.1.8";
 var client;
 function eh() {
   if (!client) throw new Error("Call configureEntitleHub({ apiKey, appUserId }) before using EntitleHub.");
@@ -25,6 +27,7 @@ function eh() {
 }
 async function configureEntitleHub(opts) {
   if (opts.iap) _iap = opts.iap;
+  else await loadIap();
   client = new EntitleHub({
     apiKey: opts.apiKey,
     appUserId: opts.appUserId,
@@ -52,11 +55,25 @@ async function getProducts(productIds, type = "all") {
   return iap().fetchProducts({ skus: productIds, type });
 }
 var DEFAULT_PURCHASE_TIMEOUT_MS = 12e4;
+var DEFAULT_SHEET_TIMEOUT_MS = 6e5;
+var DEFAULT_RECONCILE_MS = 3e4;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var PurchaseError = class extends Error {
+  constructor(code, message, customerInfo) {
+    super(message);
+    this.name = "PurchaseError";
+    this.code = code;
+    this.pending = code === "purchase-pending";
+    this.customerInfo = customerInfo;
+  }
+};
 async function purchaseProduct(productId, opts = {}) {
   const I = iap();
   const isSub = Boolean(opts.isSubscription);
   const isConsumable = Boolean(opts.isConsumable) && !isSub;
   const timeoutMs = opts.timeoutMs ?? DEFAULT_PURCHASE_TIMEOUT_MS;
+  const sheetTimeoutMs = opts.sheetTimeoutMs ?? DEFAULT_SHEET_TIMEOUT_MS;
+  const reconcileMs = opts.reconcileMs ?? DEFAULT_RECONCILE_MS;
   let entitlementsBefore = [];
   try {
     entitlementsBefore = (await eh().getCustomerInfo()).activeEntitlementIds;
@@ -111,26 +128,43 @@ async function purchaseProduct(productId, opts = {}) {
     };
     const isPurchase = (p) => Boolean(p) && Boolean(p.purchaseToken || p.jwsRepresentation || p.jwsRepresentationIos || p.purchaseTokenAndroid || p.transactionId || p.transactionReceipt || p.id);
     const reconcile = async () => {
-      if (settled) return;
-      try {
-        const owned = await I.getAvailablePurchases() || [];
-        const match = owned.find((p) => (p?.productId ?? p?.id ?? p?.sku) === productId);
-        if (match) return settleWithPurchase(match);
-      } catch {
-      }
-      try {
-        const info = await eh().getCustomerInfo({ fetchPolicy: "network-only" });
-        const grew = info.activeEntitlementIds.some((id) => !entitlementsBefore.includes(id));
-        if (grew) {
-          if (settled) return;
-          settled = true;
-          cleanup();
-          resolve(info);
-          return;
+      const deadline = Date.now() + reconcileMs;
+      let wait = 2e3;
+      let lastInfo;
+      while (!settled) {
+        try {
+          const owned = await I.getAvailablePurchases() || [];
+          const match = owned.find((p) => (p?.productId ?? p?.id ?? p?.sku) === productId);
+          if (match) return settleWithPurchase(match);
+        } catch {
         }
-      } catch {
+        try {
+          lastInfo = await eh().getCustomerInfo({ fetchPolicy: "network-only" });
+          if (lastInfo.activeEntitlementIds.some((id) => !entitlementsBefore.includes(id))) {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            resolve(lastInfo);
+            return;
+          }
+        } catch {
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) break;
+        await sleep(Math.min(wait, remaining));
+        wait = Math.min(wait * 1.5, 8e3);
       }
-      fail(new Error("purchase-timeout"));
+      fail(new PurchaseError(
+        "purchase-pending",
+        "The store hasn't confirmed this purchase yet. It may still complete, show a pending state, not a failure.",
+        lastInfo
+      ));
+    };
+    const armTimer = (ms) => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        void reconcile();
+      }, ms);
     };
     const updSub = I.purchaseUpdatedListener((purchase) => {
       void settleWithPurchase(purchase);
@@ -138,17 +172,21 @@ async function purchaseProduct(productId, opts = {}) {
     const errSub = I.purchaseErrorListener((error) => {
       const code = error?.code;
       const cancelled = code === "E_USER_CANCELLED" || code === "user-cancelled" || /cancel/i.test(String(error?.message));
-      fail(new Error(cancelled ? "purchase-cancelled" : error?.message || "purchase-failed"));
+      fail(cancelled ? new PurchaseError("purchase-cancelled", "The user cancelled the purchase.") : new PurchaseError("purchase-failed", error?.message || "The purchase failed."));
     });
     Promise.resolve(
       I.requestPurchase({ request, type: isSub ? "subs" : "in-app" })
     ).then((res) => {
       const p = Array.isArray(res) ? res.find(isPurchase) : res;
-      if (isPurchase(p)) void settleWithPurchase(p);
-    }).catch((e) => fail(e));
-    timer = setTimeout(() => {
-      void reconcile();
-    }, timeoutMs);
+      if (isPurchase(p)) {
+        void settleWithPurchase(p);
+        return;
+      }
+      armTimer(timeoutMs);
+    }).catch((e) => fail(
+      e instanceof PurchaseError ? e : new PurchaseError("purchase-failed", e?.message || "The purchase failed.")
+    ));
+    armTimer(sheetTimeoutMs);
   });
 }
 async function restorePurchases() {
@@ -178,6 +216,7 @@ async function reportToEntitleHub(purchase, productId, isSubscription) {
   throw new Error("Could not read a receipt from the purchase (no iOS JWS or Android purchase token).");
 }
 export {
+  PurchaseError,
   addCustomerInfoUpdateListener,
   configureEntitleHub,
   getCustomerInfo,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@entitlehub/react-native",
-  "version": "0.1.6",
-  "description": "EntitleHub for React Native & Expo — one call to purchase and unlock entitlements. Wraps expo-iap for the native store sheet and validates receipts via EntitleHub.",
+  "version": "0.1.8",
+  "description": "EntitleHub for React Native & Expo, one call to purchase and unlock entitlements. Wraps expo-iap for the native store sheet and validates receipts via EntitleHub.",
   "keywords": [
     "entitlehub",
     "react-native",