@onborn/billing 0.1.0-beta.2 → 0.1.0-beta.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.0-beta.4
+
+- Surface native store product-loading failures instead of silently falling
+  back to backend catalog metadata without localized store prices.
+- Add the optional `@onborn/billing/expo-iap` adapter with product caching,
+  serialized purchases, StoreKit restore synchronization, transaction recovery,
+  and automatic purchase/restore transaction finishing after Onborn server
+  validation.
+
+## 0.1.0-beta.3
+
+- Fixed StoreKit 2 purchases incorrectly using the signed transaction JWS as
+  the transaction identifier.
+- Bounded purchase idempotency keys when only a signed purchase token is
+  available.
+- Added structured billing request errors with backend messages and codes.
+
 ## 0.1.0-beta.2
 
 - Removed `offeringId` from `useOnbornOffering` and

package/README.md

@@ -7,11 +7,8 @@ restore validation, and entitlement state without installing the Onborn UI
 renderer.
 
 ```ts
-import {
-  Onborn,
-  createNativeStoresBillingAdapter,
-  useOnbornEntitlements,
-} from "@onborn/billing";
+import { Onborn, useOnbornEntitlements } from "@onborn/billing";
+import { useExpoIapBillingAdapter } from "@onborn/billing/expo-iap";
 
 Onborn.init({
   apiKey: "onborn_test_...",
@@ -20,19 +17,24 @@ Onborn.init({
   platform: "ios",
 });
 
-const billingAdapter = createNativeStoresBillingAdapter({
-  purchaseProduct: async ({ storeProductId }) => {
-    // Call expo-iap, react-native-iap, or your native purchase module.
-    return { productId: storeProductId };
-  },
-});
-
 function PremiumGate() {
   const { hasEntitlement, loading } = useOnbornEntitlements();
   return { loading, premium: hasEntitlement("premium") };
 }
+
+function CustomPaywall() {
+  const { billingAdapter, connected } = useExpoIapBillingAdapter();
+  // Pass billingAdapter to useOnbornOffering or useOnbornPaywall.
+  return { billingAdapter, connected };
+}
 ```
 
+The optional `@onborn/billing/expo-iap` adapter owns the complete native-store
+lifecycle: connection callbacks, localized product loading and retries,
+serialized purchases, cancellation recovery, StoreKit restore synchronization,
+server validation hand-off, and transaction finishing. Host apps keep only
+their paywall UI and entitlement-driven navigation.
+
 The package owns the Onborn API URL. Configure credentials and user context
 once through `Onborn.init`; hooks and adapters do not accept an API key.
 
@@ -45,6 +47,10 @@ Installing `@onborn/billing` also installs its analytics and public-contract
 dependencies. You do not need `@onborn/rn-sdk` unless you render Onborn-built
 flows or paywalls.
 
+Expo apps using the official adapter must also install the optional peer
+dependency `expo-iap` and use an Expo development build. Expo Go does not
+contain this native module.
+
 `@onborn/rn-sdk` re-exports this package for apps that render Onborn flows.
 
 ## Documentation

package/dist/adapters/nativeStores.d.ts

@@ -1,6 +1,7 @@
 import type { NativeStoreRestoredPurchase } from "@onborn/sdk-contracts";
-import type { OnbornBillingAdapter, OnbornLoadProductsInput, OnbornPurchaseInput, OnbornRestoreInput } from "../types";
+import type { OnbornBillingAdapter, OnbornLoadProductsInput, OnbornPurchaseInput, OnbornPurchaseResult, OnbornRestoreInput, OnbornRestoreResult } from "../types";
 type NativeStoresPurchase = {
+    id?: string;
     productId?: string;
     storeProductId?: string;
     transactionId?: string;
@@ -38,6 +39,8 @@ export type NativeStoresBillingAdapterOptions = {
         storeProductId: string;
     }) => Promise<NativeStoresPurchase | void>;
     restorePurchases?: (input: OnbornRestoreInput) => Promise<NativeStoresRestoreOutput>;
+    finalizePurchase?: (result: OnbornPurchaseResult) => Promise<void>;
+    finalizeRestore?: (result: OnbornRestoreResult) => Promise<void>;
     refetchCustomerEntitlements?: (input: {
         userId?: string;
     }) => Promise<unknown>;

package/dist/adapters/nativeStores.js

@@ -49,6 +49,8 @@ export function createNativeStoresBillingAdapter(options) {
                 raw: normalized.raw,
             };
         },
+        finalizePurchase: options.finalizePurchase,
+        finalizeRestore: options.finalizeRestore,
         async refetchCustomerEntitlements(input) {
             const result = await options.refetchCustomerEntitlements?.(input);
             return {
@@ -143,6 +145,7 @@ function normalizeNativeRestoredPurchase(value) {
         store,
         storeProductId,
         transactionId: readString(record.transactionId) ??
+            readString(record.id) ??
             readString(record.originalTransactionIdentifierIOS),
         purchaseToken: readString(record.purchaseToken),
         raw: record.raw ?? value,
@@ -150,7 +153,7 @@ function normalizeNativeRestoredPurchase(value) {
 }
 function readTransactionId(purchase) {
     return (purchase?.transactionId ??
-        purchase?.purchaseToken ??
+        purchase?.id ??
         purchase?.originalTransactionIdentifierIOS);
 }
 function readString(value) {

package/dist/client.d.ts

@@ -2,6 +2,11 @@ import { type CustomerEntitlementsResponse, type GetOfferingResponse, type GetPa
 export type BillingClientOptions = {
     sourceId?: string;
 };
+export declare class OnbornBillingRequestError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
 export declare class BillingClient {
     private readonly options;
     private readonly config;

package/dist/client.js

@@ -2,6 +2,16 @@ import { Onborn, } from "@onborn/analytics";
 import { resolveOnbornBillingConfig } from "./runtime";
 import { CustomerEntitlementsResponseSchema, GetOfferingResponseSchema, GetPaywallResponseSchema, PurchaseValidationResponseSchema, } from "@onborn/sdk-contracts";
 const ONBORN_API_BASE_URL = "https://api.testing.onborn.app";
+export class OnbornBillingRequestError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "OnbornBillingRequestError";
+    }
+}
 export class BillingClient {
     options;
     config;
@@ -113,7 +123,8 @@ export class BillingClient {
             body: JSON.stringify(payload),
         });
         if (!response.ok) {
-            throw new Error(`Purchase request failed (${response.status})`);
+            const failure = await readBillingFailure(response);
+            throw new OnbornBillingRequestError(failure.message ?? `Purchase request failed (${response.status})`, response.status, failure.code);
         }
         const parsed = PurchaseValidationResponseSchema.safeParse(await response.json());
         if (!parsed.success) {
@@ -135,6 +146,22 @@ export class BillingClient {
         });
     }
 }
+async function readBillingFailure(response) {
+    try {
+        const payload = (await response.json());
+        return {
+            message: typeof payload.error === "string"
+                ? payload.error
+                : typeof payload.message === "string"
+                    ? payload.message
+                    : undefined,
+            code: typeof payload.code === "string" ? payload.code : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
 export function createBillingClient(options = {}) {
     return new BillingClient(options);
 }

package/dist/expo-iap.d.ts

@@ -0,0 +1,28 @@
+import { type ProductSubscription } from "expo-iap";
+import type { OnbornBillingAdapter } from "./types";
+export type ExpoIapBillingAdapterOptions = {
+    /** Additional subscription SKUs that should share the adapter product cache. */
+    productIds?: string[];
+    purchaseTimeoutMs?: number;
+    purchaseRecoveryDelayMs?: number;
+    productCacheMs?: number;
+    productRetryCount?: number;
+    productRetryDelayMs?: number;
+    restoreSettleDelayMs?: number;
+};
+export type ExpoIapBillingAdapter = {
+    billingAdapter: OnbornBillingAdapter;
+    connected: boolean;
+    products: ProductSubscription[];
+    loadingProducts: boolean;
+    productError: Error | null;
+    transactionError: Error | null;
+    reloadProducts: (productIds?: string[]) => Promise<ProductSubscription[]>;
+};
+/**
+ * Official Expo IAP bridge for Onborn billing.
+ *
+ * Owns store connection state, serialized purchase callbacks, product caching,
+ * restore synchronization, transaction recovery, and post-validation finishing.
+ */
+export declare function useExpoIapBillingAdapter(options?: ExpoIapBillingAdapterOptions): ExpoIapBillingAdapter;

package/dist/expo-iap.js

@@ -0,0 +1,437 @@
+import { fetchProducts, getActiveSubscriptions, getAvailablePurchases, restorePurchases as synchronizeStorePurchases, useIAP, } from "expo-iap";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Platform } from "react-native";
+import { createNativeStoresBillingAdapter } from "./adapters/nativeStores";
+const DEFAULT_PURCHASE_TIMEOUT_MS = 2 * 60 * 1000;
+const DEFAULT_RECOVERY_DELAY_MS = 750;
+const DEFAULT_PRODUCT_CACHE_MS = 10_000;
+const DEFAULT_PRODUCT_RETRY_DELAY_MS = 500;
+const DEFAULT_RESTORE_SETTLE_DELAY_MS = 300;
+/**
+ * Official Expo IAP bridge for Onborn billing.
+ *
+ * Owns store connection state, serialized purchase callbacks, product caching,
+ * restore synchronization, transaction recovery, and post-validation finishing.
+ */
+export function useExpoIapBillingAdapter(options = {}) {
+    const pendingPurchaseRef = useRef(null);
+    const productCacheRef = useRef(null);
+    const productRequestRef = useRef(null);
+    const knownProductIdsRef = useRef(new Set(normalizeIds(options.productIds)));
+    const [products, setProducts] = useState([]);
+    const [loadingProducts, setLoadingProducts] = useState(false);
+    const [productError, setProductError] = useState(null);
+    const [transactionError, setTransactionError] = useState(null);
+    useEffect(() => {
+        for (const productId of normalizeIds(options.productIds)) {
+            knownProductIdsRef.current.add(productId);
+        }
+    }, [options.productIds]);
+    const settlePendingPurchase = useCallback((callback) => {
+        const item = pendingPurchaseRef.current;
+        if (!item)
+            return;
+        clearTimeout(item.timeout);
+        pendingPurchaseRef.current = null;
+        callback(item);
+    }, []);
+    const { connected, requestPurchase, finishTransaction } = useIAP({
+        onPurchaseSuccess: (purchase) => {
+            const item = pendingPurchaseRef.current;
+            if (!item || item.productId !== purchase.productId)
+                return;
+            if (item.dispatching) {
+                item.bufferedPurchase = purchase;
+                return;
+            }
+            settlePendingPurchase((current) => current.resolve(purchase));
+        },
+        onPurchaseError: (error) => {
+            const item = pendingPurchaseRef.current;
+            if (!item || (error.productId && error.productId !== item.productId)) {
+                return;
+            }
+            const normalized = normalizePurchaseError(error);
+            if (item.dispatching) {
+                item.bufferedError = normalized;
+                return;
+            }
+            settlePendingPurchase((current) => current.reject(normalized));
+        },
+    });
+    useEffect(() => () => {
+        settlePendingPurchase((item) => item.reject(new Error("Purchase interrupted.")));
+    }, [settlePendingPurchase]);
+    const loadProducts = useCallback(async (requestedProductIds, force = false) => {
+        if (!connected) {
+            throw new Error("Native store is not connected.");
+        }
+        const requestedIds = normalizeIds(requestedProductIds);
+        for (const productId of requestedIds) {
+            knownProductIdsRef.current.add(productId);
+        }
+        if (requestedIds.length === 0)
+            return [];
+        const cached = productCacheRef.current;
+        if (!force &&
+            cached &&
+            Date.now() - cached.fetchedAt <
+                (options.productCacheMs ?? DEFAULT_PRODUCT_CACHE_MS) &&
+            requestedIds.every((id) => cached.products.some((product) => product.id === id))) {
+            return cached.products.filter((product) => requestedIds.includes(product.id));
+        }
+        if (!productRequestRef.current) {
+            setLoadingProducts(true);
+            setProductError(null);
+            const allProductIds = Array.from(knownProductIdsRef.current);
+            productRequestRef.current = fetchSubscriptionProductsWithRetry(allProductIds, options.productRetryCount ?? 1, options.productRetryDelayMs ?? DEFAULT_PRODUCT_RETRY_DELAY_MS)
+                .then((loadedProducts) => {
+                productCacheRef.current = {
+                    products: loadedProducts,
+                    fetchedAt: Date.now(),
+                };
+                setProducts(loadedProducts);
+                return loadedProducts;
+            })
+                .catch((error) => {
+                const normalized = normalizeError(error, "Native store did not return subscription products.");
+                setProductError(normalized);
+                throw normalized;
+            })
+                .finally(() => {
+                productRequestRef.current = null;
+                setLoadingProducts(false);
+            });
+        }
+        const loadedProducts = await productRequestRef.current;
+        const matches = loadedProducts.filter((product) => requestedIds.includes(product.id));
+        const missingIds = requestedIds.filter((id) => !matches.some((product) => product.id === id));
+        if (missingIds.length > 0) {
+            throw new Error(`Native store did not return requested products: ${missingIds.join(", ")}.`);
+        }
+        return matches;
+    }, [
+        connected,
+        options.productCacheMs,
+        options.productRetryCount,
+        options.productRetryDelayMs,
+    ]);
+    const reloadProducts = useCallback(async (productIds = options.productIds ?? []) => {
+        const normalizedIds = normalizeIds(productIds);
+        return normalizedIds.length > 0
+            ? loadProducts(normalizedIds, true)
+            : [];
+    }, [loadProducts, options.productIds]);
+    const recoverPurchase = useCallback(async (productId) => {
+        await wait(options.purchaseRecoveryDelayMs ?? DEFAULT_RECOVERY_DELAY_MS);
+        try {
+            const availablePurchases = await getAvailablePurchases({
+                onlyIncludeActiveItemsIOS: true,
+            });
+            return findPurchase(availablePurchases, productId);
+        }
+        catch {
+            return null;
+        }
+    }, [options.purchaseRecoveryDelayMs]);
+    const billingAdapter = useMemo(() => {
+        const nativeAdapter = createNativeStoresBillingAdapter({
+            async loadProducts({ storeProductIds }) {
+                const nativeProducts = await loadProducts(storeProductIds);
+                return nativeProducts.map(normalizeStoreProduct);
+            },
+            async purchaseProduct({ storeProductId }) {
+                if (!connected) {
+                    throw new Error("Native store is not connected.");
+                }
+                if (pendingPurchaseRef.current) {
+                    throw new Error("Another purchase is already in progress.");
+                }
+                knownProductIdsRef.current.add(storeProductId);
+                const purchase = await new Promise((resolve, reject) => {
+                    const timeout = setTimeout(() => {
+                        settlePendingPurchase((item) => item.reject(new Error("Purchase timed out.")));
+                    }, options.purchaseTimeoutMs ?? DEFAULT_PURCHASE_TIMEOUT_MS);
+                    pendingPurchaseRef.current = {
+                        productId: storeProductId,
+                        resolve,
+                        reject,
+                        timeout,
+                        dispatching: true,
+                    };
+                    void (async () => {
+                        try {
+                            const result = await requestPurchase({
+                                request: Platform.OS === "android"
+                                    ? { google: { skus: [storeProductId] } }
+                                    : { apple: { sku: storeProductId } },
+                                type: "subs",
+                            });
+                            const item = pendingPurchaseRef.current;
+                            if (!item || item.productId !== storeProductId)
+                                return;
+                            item.dispatching = false;
+                            const successfulPurchase = findPurchase(result, storeProductId) ?? item.bufferedPurchase;
+                            if (successfulPurchase) {
+                                settlePendingPurchase((current) => current.resolve(successfulPurchase));
+                                return;
+                            }
+                            if (item.bufferedError) {
+                                const recovered = isUserCancelled(item.bufferedError)
+                                    ? await recoverPurchase(storeProductId)
+                                    : null;
+                                if (recovered && pendingPurchaseRef.current === item) {
+                                    settlePendingPurchase((current) => current.resolve(recovered));
+                                }
+                                else if (pendingPurchaseRef.current === item) {
+                                    settlePendingPurchase((current) => current.reject(item.bufferedError));
+                                }
+                            }
+                        }
+                        catch (error) {
+                            const item = pendingPurchaseRef.current;
+                            if (!item || item.productId !== storeProductId)
+                                return;
+                            item.dispatching = false;
+                            if (item.bufferedPurchase) {
+                                settlePendingPurchase((current) => current.resolve(item.bufferedPurchase));
+                                return;
+                            }
+                            const recovered = isUserCancelled(error)
+                                ? await recoverPurchase(storeProductId)
+                                : null;
+                            if (recovered && pendingPurchaseRef.current === item) {
+                                settlePendingPurchase((current) => current.resolve(recovered));
+                            }
+                            else if (pendingPurchaseRef.current === item) {
+                                settlePendingPurchase((current) => current.reject(normalizeError(error, "Unable to start purchase.")));
+                            }
+                        }
+                    })();
+                });
+                return normalizeStorePurchase(purchase);
+            },
+            async restorePurchases({ products: configuredProducts }) {
+                if (!connected) {
+                    throw new Error("Native store is not connected.");
+                }
+                const subscriptionIds = normalizeIds([
+                    ...configuredProducts.map((product) => product.storeProductId),
+                    ...knownProductIdsRef.current,
+                ]);
+                await synchronizeStorePurchases();
+                await wait(options.restoreSettleDelayMs ?? DEFAULT_RESTORE_SETTLE_DELAY_MS);
+                const [availableResult, activeResult] = await Promise.allSettled([
+                    getAvailablePurchases({ onlyIncludeActiveItemsIOS: true }),
+                    getActiveSubscriptions(subscriptionIds),
+                ]);
+                if (availableResult.status === "rejected" &&
+                    activeResult.status === "rejected") {
+                    throw availableResult.reason;
+                }
+                const restoredPurchases = [
+                    ...(availableResult.status === "fulfilled"
+                        ? availableResult.value.map(normalizeRestoredPurchase)
+                        : []),
+                    ...(activeResult.status === "fulfilled"
+                        ? activeResult.value
+                            .filter((subscription) => subscription.isActive)
+                            .map((subscription) => ({
+                            store: Platform.OS === "android"
+                                ? "google_play"
+                                : "app_store",
+                            storeProductId: subscription.productId,
+                            transactionId: subscription.transactionId,
+                            purchaseToken: subscription.purchaseToken ?? undefined,
+                            raw: subscription,
+                        }))
+                        : []),
+                ];
+                return {
+                    purchases: deduplicateRestoredPurchases(restoredPurchases),
+                    raw: {
+                        availablePurchases: availableResult.status === "fulfilled"
+                            ? availableResult.value
+                            : [],
+                        activeSubscriptions: activeResult.status === "fulfilled" ? activeResult.value : [],
+                    },
+                };
+            },
+        });
+        return {
+            ...nativeAdapter,
+            async finalizePurchase(result) {
+                const purchase = findPurchase(result.raw, result.productId);
+                if (!purchase)
+                    return;
+                setTransactionError(null);
+                try {
+                    await finishTransaction({ purchase, isConsumable: false });
+                }
+                catch (error) {
+                    setTransactionError(normalizeError(error, "Unable to finish native transaction."));
+                }
+            },
+            async finalizeRestore(result) {
+                const purchases = findPurchases(result.raw);
+                if (purchases.length === 0)
+                    return;
+                setTransactionError(null);
+                const outcomes = await Promise.allSettled(purchases.map((purchase) => finishTransaction({ purchase, isConsumable: false })));
+                const failed = outcomes.find((outcome) => outcome.status === "rejected");
+                if (failed) {
+                    setTransactionError(normalizeError(failed.reason, "Unable to finish restored native transaction."));
+                }
+            },
+        };
+    }, [
+        connected,
+        finishTransaction,
+        loadProducts,
+        options.purchaseTimeoutMs,
+        options.restoreSettleDelayMs,
+        recoverPurchase,
+        requestPurchase,
+        settlePendingPurchase,
+    ]);
+    return {
+        billingAdapter,
+        connected,
+        products,
+        loadingProducts,
+        productError,
+        transactionError,
+        reloadProducts,
+    };
+}
+async function fetchSubscriptionProductsWithRetry(productIds, retryCount, retryDelayMs) {
+    let lastError;
+    for (let attempt = 0; attempt <= Math.max(0, retryCount); attempt += 1) {
+        if (attempt > 0)
+            await wait(retryDelayMs);
+        try {
+            const result = await fetchProducts({ skus: productIds, type: "subs" });
+            const products = (result ?? []).filter((product) => product.type === "subs");
+            if (products.length > 0)
+                return products;
+            lastError = new Error("Native store returned an empty product catalog.");
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw normalizeError(lastError, "Native store did not return subscription products.");
+}
+function normalizeStoreProduct(product) {
+    return {
+        id: product.id,
+        productId: product.id,
+        title: product.title,
+        description: product.description,
+        displayPrice: product.displayPrice,
+        currency: product.currency,
+        price: product.price ?? undefined,
+        subscriptionPeriod: "subscriptionPeriodUnitIOS" in product
+            ? product.subscriptionPeriodUnitIOS ?? undefined
+            : undefined,
+        raw: product,
+    };
+}
+function normalizeStorePurchase(purchase) {
+    return {
+        productId: purchase.productId,
+        transactionId: purchase.transactionId ?? purchase.id,
+        purchaseToken: purchase.purchaseToken ?? undefined,
+        originalTransactionIdentifierIOS: "originalTransactionIdentifierIOS" in purchase
+            ? purchase.originalTransactionIdentifierIOS ?? undefined
+            : undefined,
+        raw: purchase,
+    };
+}
+function normalizeRestoredPurchase(purchase) {
+    return {
+        store: purchase.store === "google"
+            ? "google_play"
+            : "app_store",
+        storeProductId: purchase.productId,
+        transactionId: ("originalTransactionIdentifierIOS" in purchase
+            ? purchase.originalTransactionIdentifierIOS
+            : undefined) ??
+            purchase.transactionId ??
+            purchase.id,
+        purchaseToken: purchase.purchaseToken ?? undefined,
+        raw: purchase,
+    };
+}
+function deduplicateRestoredPurchases(purchases) {
+    return Array.from(new Map(purchases.map((purchase) => [
+        `${purchase.storeProductId}:${purchase.transactionId ?? purchase.purchaseToken ?? ""}`,
+        purchase,
+    ])).values());
+}
+function findPurchase(value, productId) {
+    const candidates = Array.isArray(value) ? value : [value];
+    for (const candidate of candidates) {
+        if (isPurchase(candidate) &&
+            (!productId || candidate.productId === productId)) {
+            return candidate;
+        }
+        if (candidate && typeof candidate === "object" && "raw" in candidate) {
+            const nested = findPurchase(candidate.raw, productId);
+            if (nested)
+                return nested;
+        }
+    }
+    return null;
+}
+function findPurchases(value) {
+    const found = new Map();
+    collectPurchases(value, found, new Set());
+    return Array.from(found.values());
+}
+function collectPurchases(value, found, visited) {
+    if (!value || typeof value !== "object")
+        return;
+    if (visited.has(value))
+        return;
+    visited.add(value);
+    if (isPurchase(value)) {
+        found.set(`${value.productId}:${value.transactionId ?? value.id}`, value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectPurchases(item, found, visited);
+        return;
+    }
+    for (const nested of Object.values(value)) {
+        collectPurchases(nested, found, visited);
+    }
+}
+function isPurchase(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        "productId" in value &&
+        "transactionDate" in value);
+}
+function normalizePurchaseError(error) {
+    const normalized = new Error(error.message);
+    normalized.code = error.code;
+    normalized.userCancelled = isUserCancelled(error);
+    return normalized;
+}
+function isUserCancelled(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const value = error;
+    return value.userCancelled === true || value.code === "user-cancelled";
+}
+function normalizeError(error, fallback) {
+    return error instanceof Error ? error : new Error(fallback);
+}
+function normalizeIds(values) {
+    return Array.from(new Set((values ?? []).filter((value) => typeof value === "string" && value.trim().length > 0)));
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/types.d.ts

@@ -50,7 +50,14 @@ export type OnbornRestoreResult = {
 export type OnbornBillingAdapter = {
     loadProducts?: (input: OnbornLoadProductsInput) => Promise<BillingProduct[]>;
     purchasePackage: (input: OnbornPurchaseInput) => Promise<OnbornPurchaseResult>;
+    /**
+     * Completes a native transaction after Onborn validates it. Implementations
+     * should be idempotent because unfinished store transactions may be replayed.
+     */
+    finalizePurchase?: (result: OnbornPurchaseResult) => Promise<void>;
     restorePurchases?: (input: OnbornRestoreInput) => Promise<OnbornRestoreResult>;
+    /** Completes restored native transactions after Onborn reconciles them. */
+    finalizeRestore?: (result: OnbornRestoreResult) => Promise<void>;
     refetchCustomerEntitlements?: (input: {
         userId?: string;
     }) => Promise<OnbornRestoreResult>;

package/dist/useOnbornOffering.js

@@ -94,6 +94,7 @@ export function useOnbornOffering(options = {}) {
                     result: adapterResult,
                 })
                 : adapterResult;
+            await finalizePurchase(runtimeOptions.billingAdapter, result);
             runtimeOptions.onPurchaseCompleted?.(result);
             notifyEntitlementsChanged(result.entitlements, runtimeOptions.onEntitlementsChanged);
             return result;
@@ -123,6 +124,7 @@ export function useOnbornOffering(options = {}) {
                 offering: data?.offering,
                 result: adapterResult,
             });
+            await finalizeRestore(runtimeOptions.billingAdapter, result);
             runtimeOptions.onRestoreCompleted?.(result);
             notifyEntitlementsChanged(result.entitlements, runtimeOptions.onEntitlementsChanged);
             return result;
@@ -177,12 +179,7 @@ async function loadLocalizedProducts(billingAdapter, input) {
     if (!billingAdapter?.loadProducts) {
         return input.products;
     }
-    try {
-        return await billingAdapter.loadProducts(input);
-    }
-    catch {
-        return input.products;
-    }
+    return billingAdapter.loadProducts(input);
 }
 function notifyEntitlementsChanged(entitlements, callback) {
     if (!entitlements) {
@@ -190,3 +187,13 @@ function notifyEntitlementsChanged(entitlements, callback) {
     }
     callback?.(entitlements);
 }
+async function finalizePurchase(adapter, result) {
+    if (!result.success || result.status !== "validated")
+        return;
+    await adapter.finalizePurchase?.(result);
+}
+async function finalizeRestore(adapter, result) {
+    if (!result.success || result.status !== "validated")
+        return;
+    await adapter.finalizeRestore?.(result);
+}

package/dist/useOnbornPaywall.js

@@ -150,6 +150,7 @@ export function useOnbornPaywall(options) {
                     result: adapterResult,
                 })
                 : adapterResult;
+            await finalizePurchase(runtimeOptions.billingAdapter, result);
             runtimeOptions.onPurchaseCompleted?.(result);
             notifyEntitlementsChanged(result.entitlements, runtimeOptions.onEntitlementsChanged);
             if (result.success && result.status === "validated") {
@@ -231,6 +232,7 @@ export function useOnbornPaywall(options) {
                 offering: data?.offering,
                 result: adapterResult,
             });
+            await finalizeRestore(runtimeOptions.billingAdapter, result);
             runtimeOptions.onRestoreCompleted?.(result);
             notifyEntitlementsChanged(result.entitlements, runtimeOptions.onEntitlementsChanged);
             if (restorePaywall) {
@@ -330,12 +332,7 @@ async function loadLocalizedProducts(billingAdapter, input) {
     if (!billingAdapter?.loadProducts) {
         return input.products;
     }
-    try {
-        return await billingAdapter.loadProducts(input);
-    }
-    catch {
-        return input.products;
-    }
+    return billingAdapter.loadProducts(input);
 }
 function notifyEntitlementsChanged(entitlements, callback) {
     if (!entitlements) {
@@ -343,3 +340,13 @@ function notifyEntitlementsChanged(entitlements, callback) {
     }
     callback?.(entitlements);
 }
+async function finalizePurchase(adapter, result) {
+    if (!result.success || result.status !== "validated")
+        return;
+    await adapter.finalizePurchase?.(result);
+}
+async function finalizeRestore(adapter, result) {
+    if (!result.success || result.status !== "validated")
+        return;
+    await adapter.finalizeRestore?.(result);
+}

package/dist/validation.js

@@ -44,7 +44,7 @@ export async function validateBillingRestore(input) {
 }
 function createPurchaseIdempotencyKey(input) {
     const stablePart = input.result.transactionId ??
-        input.result.purchaseToken ??
+        fingerprintIdempotencyValue(input.result.purchaseToken) ??
         input.result.productId ??
         input.item.product?.storeProductId ??
         input.item.package.id;
@@ -55,6 +55,18 @@ function createPurchaseIdempotencyKey(input) {
         stablePart,
     ].join(":");
 }
+function fingerprintIdempotencyValue(value) {
+    if (!value)
+        return undefined;
+    let first = 0x811c9dc5;
+    let second = 0x9e3779b9;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        first = Math.imul(first ^ code, 0x01000193);
+        second = Math.imul(second ^ code, 0x85ebca6b);
+    }
+    return `${(first >>> 0).toString(36)}${(second >>> 0).toString(36)}`;
+}
 function createRestoreIdempotencyKey(input) {
     return ["restore", input.offering?.id ?? "unknown", String(Date.now())].join(":");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onborn/billing",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Headless billing, offerings, purchases, restores, and entitlements for Onborn.",
   "license": "UNLICENSED",
   "repository": {
@@ -22,6 +22,11 @@
       "react-native": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./expo-iap": {
+      "react-native": "./dist/expo-iap.js",
+      "types": "./dist/expo-iap.d.ts",
+      "default": "./dist/expo-iap.js"
     }
   },
   "files": [
@@ -45,15 +50,22 @@
     "@onborn/sdk-contracts": "0.1.0-beta.1"
   },
   "peerDependencies": {
+    "expo-iap": ">=4.5.0",
     "react": ">=18.0.0",
     "react-native": ">=0.76.0"
   },
+  "peerDependenciesMeta": {
+    "expo-iap": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@repo/eslint-config": "*",
     "@repo/typescript-config": "*",
     "@types/node": "^22.15.3",
     "@types/react": "~19.2.4",
     "eslint": "^9.39.1",
+    "expo-iap": "4.5.0",
     "react": "19.2.3",
     "react-native": "0.86.0",
     "typescript": "5.9.2"