@entitlehub/react-native 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 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.
+  Version only; no device or user data.
+
 ## 0.1.5 — 2026-07-21
 
 ### Fixed

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  PurchaseError: () => PurchaseError,
   addCustomerInfoUpdateListener: () => addCustomerInfoUpdateListener,
   configureEntitleHub: () => configureEntitleHub,
   getCustomerInfo: () => getCustomerInfo,
@@ -42,6 +43,7 @@ function iap() {
   }
   return _iap;
 }
+var RN_SDK_VERSION = "0.1.7";
 var client;
 function eh() {
   if (!client) throw new Error("Call configureEntitleHub({ apiKey, appUserId }) before using EntitleHub.");
@@ -49,7 +51,12 @@ function eh() {
 }
 async function configureEntitleHub(opts) {
   if (opts.iap) _iap = opts.iap;
-  client = new import_sdk.EntitleHub({ apiKey: opts.apiKey, appUserId: opts.appUserId, baseUrl: opts.baseUrl });
+  client = new import_sdk.EntitleHub({
+    apiKey: opts.apiKey,
+    appUserId: opts.appUserId,
+    baseUrl: opts.baseUrl,
+    client: `react-native/${RN_SDK_VERSION}`
+  });
   try {
     await iap().initConnection();
   } catch {
@@ -71,11 +78,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;
@@ -130,26 +151,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 \u2014 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);
@@ -157,17 +195,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() {
@@ -198,6 +240,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

@@ -31,6 +31,23 @@ 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.
@@ -44,17 +61,25 @@ declare function getProducts(productIds: string[], type?: "in-app" | "subs" | "a
  *     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

@@ -31,6 +31,23 @@ 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.
@@ -44,17 +61,25 @@ declare function getProducts(productIds: string[], type?: "in-app" | "subs" | "a
  *     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

@@ -17,6 +17,7 @@ function iap() {
   }
   return _iap;
 }
+var RN_SDK_VERSION = "0.1.7";
 var client;
 function eh() {
   if (!client) throw new Error("Call configureEntitleHub({ apiKey, appUserId }) before using EntitleHub.");
@@ -24,7 +25,12 @@ function eh() {
 }
 async function configureEntitleHub(opts) {
   if (opts.iap) _iap = opts.iap;
-  client = new EntitleHub({ apiKey: opts.apiKey, appUserId: opts.appUserId, baseUrl: opts.baseUrl });
+  client = new EntitleHub({
+    apiKey: opts.apiKey,
+    appUserId: opts.appUserId,
+    baseUrl: opts.baseUrl,
+    client: `react-native/${RN_SDK_VERSION}`
+  });
   try {
     await iap().initConnection();
   } catch {
@@ -46,11 +52,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;
@@ -105,26 +125,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 \u2014 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);
@@ -132,17 +169,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() {
@@ -172,6 +213,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,6 +1,6 @@
 {
   "name": "@entitlehub/react-native",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",