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

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.0-beta.6
+
+- Added `OnbornPurchaseError` with a normalized `code` (`user_cancelled`, `already_owned`, `store_unavailable`, `network_error`, `product_unavailable`, `pending`, `validation_failed`, `not_allowed`, `unknown`), plus `isUserCancelledError` and `toOnbornPurchaseError`. Apps no longer sniff raw store error shapes to tell a cancelled purchase from a real failure.
+- Added price helpers: `formatPrice`, `getPricePerPeriod` (the "only X/week" line), `parseBillingPeriod`, and `resolveBillingPeriod`. They return `undefined` rather than a guess when the period or amount is unknown.
+- The native store adapter now populates `priceAmount`, `billingPeriod`, and `introOffer` on products. iOS intro-offer eligibility is checked per subscription group; offers the customer cannot redeem are omitted.
+- `useOnbornEntitlements({ cache: true })` keeps the last known entitlements per user and replays them on cold start, exposing a `stale` flag until a fresh response lands. The server stays authoritative.
+- `useExpoIapBillingAdapter` exposes `connectionState` (`connecting`/`ready`/`unavailable`) and `retryConnection()`, so apps stop hand-rolling connection timeout state.
+- A failed native store product load no longer discards a valid offering: the paywall renders with synced catalog prices instead of showing a retry button.
+
+## 0.1.0-beta.5
+
+- Wait for the native store connection before loading localized products,
+  purchasing, or restoring. This prevents a cold-open paywall from showing an
+  unavailable state that only clears after a manual retry.
+
 ## 0.1.0-beta.4
 
 - Surface native store product-loading failures instead of silently falling

package/README.md

@@ -24,7 +24,8 @@ function PremiumGate() {
 
 function CustomPaywall() {
   const { billingAdapter, connected } = useExpoIapBillingAdapter();
-  // Pass billingAdapter to useOnbornOffering or useOnbornPaywall.
+  // Pass billingAdapter immediately. It waits for the native connection.
+  // `connected` is only useful for optional loading or disabled UI.
   return { billingAdapter, connected };
 }
 ```
@@ -35,6 +36,10 @@ 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.
 
+Always pass the returned `billingAdapter` directly to `useOnbornOffering` or
+`useOnbornPaywall`. Do not replace it with `undefined` while `connected` is
+false; native operations already wait for the store connection internally.
+
 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.
 

package/dist/adapters/nativeStores.d.ts

@@ -1,4 +1,4 @@
-import type { NativeStoreRestoredPurchase } from "@onborn/sdk-contracts";
+import type { BillingPeriod, BillingProductOffer, NativeStoreRestoredPurchase } from "@onborn/sdk-contracts";
 import type { OnbornBillingAdapter, OnbornLoadProductsInput, OnbornPurchaseInput, OnbornPurchaseResult, OnbornRestoreInput, OnbornRestoreResult } from "../types";
 type NativeStoresPurchase = {
     id?: string;
@@ -25,6 +25,10 @@ type NativeStoresProduct = {
     currencyCode?: string;
     period?: string;
     subscriptionPeriod?: string;
+    /** Normalized renewal period, when the adapter can determine it. */
+    billingPeriod?: BillingPeriod;
+    /** Eligibility-checked introductory/promotional offer, when one applies. */
+    introOffer?: BillingProductOffer;
     raw?: unknown;
 };
 type NativeStoresRestoreOutput = NativeStoreRestoredPurchase[] | {

package/dist/adapters/nativeStores.js

@@ -71,12 +71,17 @@ function localizeProducts(products, nativeProducts) {
             title: readString(nativeProduct.title) ?? product.title,
             description: readString(nativeProduct.description) ?? product.description,
             price: readNativePrice(nativeProduct) ?? product.price,
+            // The store gives us the amount as a number; surface it as a first-class
+            // field so apps never have to dig it back out of `metadata.raw`.
+            priceAmount: readPriceAmount(nativeProduct.price) ?? product.priceAmount,
             currency: readString(nativeProduct.currencyCode) ??
                 readString(nativeProduct.currency) ??
                 product.currency,
             period: readString(nativeProduct.subscriptionPeriod) ??
                 readString(nativeProduct.period) ??
                 product.period,
+            billingPeriod: nativeProduct.billingPeriod ?? product.billingPeriod,
+            introOffer: nativeProduct.introOffer ?? product.introOffer,
             metadata: {
                 ...product.metadata,
                 nativeStoreProduct: nativeProduct.raw ?? nativeProduct,
@@ -167,3 +172,18 @@ function readPriceValue(value) {
     }
     return readString(value);
 }
+/**
+ * Stores are inconsistent about the numeric price: StoreKit hands back a
+ * number, some Play/JS bridges stringify it. Accept either, reject anything
+ * that is not a usable amount.
+ */
+function readPriceAmount(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) && value >= 0 ? value : undefined;
+    }
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value.trim());
+        return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+    }
+    return undefined;
+}

package/dist/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Normalized purchase errors.
+ *
+ * Store SDKs report failures with their own vocabulary (expo-iap's
+ * `ErrorCode`, StoreKit/Play error objects, RevenueCat codes), which pushed
+ * every host app into sniffing raw error shapes just to answer the one
+ * question every paywall asks: "did the user cancel, or did something break?".
+ * Adapters map their store's error onto `OnbornPurchaseError` so apps branch
+ * on a stable code instead of a provider's internals.
+ */
+export type OnbornPurchaseErrorCode = 
+/** The customer dismissed the store sheet. Not an error to report. */
+"user_cancelled"
+/** The customer already owns this product; restore instead of buying. */
+ | "already_owned"
+/** Store/billing service unreachable or not initialized on this device. */
+ | "store_unavailable"
+/** Transport failure talking to the store. Retrying is reasonable. */
+ | "network_error"
+/** The SKU is missing, not approved, or unavailable in this storefront. */
+ | "product_unavailable"
+/** Purchase is awaiting external action (Ask to Buy, SCA, slow payment). */
+ | "pending"
+/** The store accepted the purchase but ONBORN could not validate it. */
+ | "validation_failed"
+/** Purchase is not permitted (parental controls, restricted device). */
+ | "not_allowed"
+/** Anything the adapter could not classify. */
+ | "unknown";
+export declare class OnbornPurchaseError extends Error {
+    readonly code: OnbornPurchaseErrorCode;
+    /** The store's own code, kept for logging and support tickets. */
+    readonly storeCode?: string;
+    readonly productId?: string;
+    readonly cause?: unknown;
+    constructor(code: OnbornPurchaseErrorCode, message: string, options?: {
+        storeCode?: string;
+        productId?: string;
+        cause?: unknown;
+    });
+    /** True when the customer dismissed the purchase sheet themselves. */
+    get userCancelled(): boolean;
+}
+/**
+ * The one check every paywall needs: a cancelled purchase must stay silent,
+ * anything else deserves a message. Works on `OnbornPurchaseError` and on raw
+ * store errors, so it is safe to call on anything a `catch` block receives.
+ */
+export declare function isUserCancelledError(error: unknown): boolean;
+/** Coerce anything thrown by a store into a normalized purchase error. */
+export declare function toOnbornPurchaseError(error: unknown, options?: {
+    productId?: string;
+}): OnbornPurchaseError;

package/dist/errors.js

@@ -0,0 +1,103 @@
+/**
+ * Normalized purchase errors.
+ *
+ * Store SDKs report failures with their own vocabulary (expo-iap's
+ * `ErrorCode`, StoreKit/Play error objects, RevenueCat codes), which pushed
+ * every host app into sniffing raw error shapes just to answer the one
+ * question every paywall asks: "did the user cancel, or did something break?".
+ * Adapters map their store's error onto `OnbornPurchaseError` so apps branch
+ * on a stable code instead of a provider's internals.
+ */
+export class OnbornPurchaseError extends Error {
+    code;
+    /** The store's own code, kept for logging and support tickets. */
+    storeCode;
+    productId;
+    cause;
+    constructor(code, message, options) {
+        super(message);
+        this.name = "OnbornPurchaseError";
+        this.code = code;
+        this.storeCode = options?.storeCode;
+        this.productId = options?.productId;
+        this.cause = options?.cause;
+    }
+    /** True when the customer dismissed the purchase sheet themselves. */
+    get userCancelled() {
+        return this.code === "user_cancelled";
+    }
+}
+/**
+ * The one check every paywall needs: a cancelled purchase must stay silent,
+ * anything else deserves a message. Works on `OnbornPurchaseError` and on raw
+ * store errors, so it is safe to call on anything a `catch` block receives.
+ */
+export function isUserCancelledError(error) {
+    if (error instanceof OnbornPurchaseError) {
+        return error.userCancelled;
+    }
+    return readStoreErrorCode(error) === "user_cancelled";
+}
+/** Coerce anything thrown by a store into a normalized purchase error. */
+export function toOnbornPurchaseError(error, options) {
+    if (error instanceof OnbornPurchaseError) {
+        return error;
+    }
+    const record = error && typeof error === "object"
+        ? error
+        : {};
+    const storeCode = typeof record.code === "string" ? record.code : undefined;
+    const message = typeof record.message === "string" && record.message.trim()
+        ? record.message
+        : "The purchase could not be completed.";
+    return new OnbornPurchaseError(readStoreErrorCode(error) ?? "unknown", message, {
+        storeCode,
+        productId: options?.productId ??
+            (typeof record.productId === "string" ? record.productId : undefined),
+        cause: error,
+    });
+}
+// expo-iap `ErrorCode` values, plus the shapes StoreKit/Play surface directly.
+const STORE_ERROR_CODES = {
+    "user-cancelled": "user_cancelled",
+    "user-error": "user_cancelled",
+    "already-owned": "already_owned",
+    "duplicate-purchase": "already_owned",
+    "network-error": "network_error",
+    "remote-error": "network_error",
+    "service-timeout": "network_error",
+    "billing-unavailable": "store_unavailable",
+    "iap-not-available": "store_unavailable",
+    "init-connection": "store_unavailable",
+    "not-prepared": "store_unavailable",
+    "connection-closed": "store_unavailable",
+    "service-disconnected": "store_unavailable",
+    "service-error": "store_unavailable",
+    "activity-unavailable": "store_unavailable",
+    "item-unavailable": "product_unavailable",
+    "sku-not-found": "product_unavailable",
+    "query-product": "product_unavailable",
+    "empty-sku-list": "product_unavailable",
+    "sku-offer-mismatch": "product_unavailable",
+    pending: "pending",
+    "deferred-payment": "pending",
+    "transaction-validation-failed": "validation_failed",
+    "purchase-verification-failed": "validation_failed",
+    "receipt-failed": "validation_failed",
+    "feature-not-supported": "not_allowed",
+    "developer-error": "not_allowed",
+};
+function readStoreErrorCode(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const value = error;
+    // StoreKit surfaces cancellation as a boolean on some paths.
+    if (value.userCancelled === true) {
+        return "user_cancelled";
+    }
+    if (typeof value.code !== "string") {
+        return undefined;
+    }
+    return STORE_ERROR_CODES[value.code.toLowerCase()];
+}

package/dist/expo-iap.d.ts

@@ -3,6 +3,8 @@ import type { OnbornBillingAdapter } from "./types";
 export type ExpoIapBillingAdapterOptions = {
     /** Additional subscription SKUs that should share the adapter product cache. */
     productIds?: string[];
+    /** Maximum time an operation waits for the native store connection. */
+    connectionTimeoutMs?: number;
     purchaseTimeoutMs?: number;
     purchaseRecoveryDelayMs?: number;
     productCacheMs?: number;
@@ -10,9 +12,26 @@ export type ExpoIapBillingAdapterOptions = {
     productRetryDelayMs?: number;
     restoreSettleDelayMs?: number;
 };
+/**
+ * Lifecycle of the native store connection.
+ *
+ * `connected: false` alone cannot tell "still connecting" from "gave up",
+ * which is the difference between showing a spinner and showing a retry
+ * button — so every app ended up rebuilding this with its own timers.
+ */
+export type ExpoIapConnectionState = "connecting" | "ready" | "unavailable";
 export type ExpoIapBillingAdapter = {
+    /**
+     * Adapter that can be passed to Onborn hooks immediately. Store
+     * operations wait for the native IAP connection internally.
+     */
     billingAdapter: OnbornBillingAdapter;
+    /** Native store connection state for optional loading and disabled UI. */
     connected: boolean;
+    /** Same signal as `connected`, but distinguishes "connecting" from "gave up". */
+    connectionState: ExpoIapConnectionState;
+    /** Re-attempt a store connection after `connectionState` went unavailable. */
+    retryConnection: () => Promise<void>;
     products: ProductSubscription[];
     loadingProducts: boolean;
     productError: Error | null;
@@ -24,5 +43,7 @@ export type ExpoIapBillingAdapter = {
  *
  * Owns store connection state, serialized purchase callbacks, product caching,
  * restore synchronization, transaction recovery, and post-validation finishing.
+ * Pass `billingAdapter` to Onborn hooks unconditionally; use `connected` only
+ * when the host app wants to present store-connection UI.
  */
 export declare function useExpoIapBillingAdapter(options?: ExpoIapBillingAdapterOptions): ExpoIapBillingAdapter;

package/dist/expo-iap.js

@@ -1,8 +1,10 @@
-import { fetchProducts, getActiveSubscriptions, getAvailablePurchases, restorePurchases as synchronizeStorePurchases, useIAP, } from "expo-iap";
+import { fetchProducts, getActiveSubscriptions, getAvailablePurchases, initConnection, isEligibleForIntroOfferIOS, 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";
+import { isUserCancelledError, toOnbornPurchaseError, } from "./errors";
 const DEFAULT_PURCHASE_TIMEOUT_MS = 2 * 60 * 1000;
+const DEFAULT_CONNECTION_TIMEOUT_MS = 15_000;
 const DEFAULT_RECOVERY_DELAY_MS = 750;
 const DEFAULT_PRODUCT_CACHE_MS = 10_000;
 const DEFAULT_PRODUCT_RETRY_DELAY_MS = 500;
@@ -12,13 +14,19 @@ const DEFAULT_RESTORE_SETTLE_DELAY_MS = 300;
  *
  * Owns store connection state, serialized purchase callbacks, product caching,
  * restore synchronization, transaction recovery, and post-validation finishing.
+ * Pass `billingAdapter` to Onborn hooks unconditionally; use `connected` only
+ * when the host app wants to present store-connection UI.
  */
 export function useExpoIapBillingAdapter(options = {}) {
     const pendingPurchaseRef = useRef(null);
+    const connectedRef = useRef(false);
+    const connectionWaitersRef = useRef(new Set());
     const productCacheRef = useRef(null);
     const productRequestRef = useRef(null);
     const knownProductIdsRef = useRef(new Set(normalizeIds(options.productIds)));
     const [products, setProducts] = useState([]);
+    const [connectionState, setConnectionState] = useState("connecting");
+    const [connectionAttempt, setConnectionAttempt] = useState(0);
     const [loadingProducts, setLoadingProducts] = useState(false);
     const [productError, setProductError] = useState(null);
     const [transactionError, setTransactionError] = useState(null);
@@ -59,13 +67,75 @@ export function useExpoIapBillingAdapter(options = {}) {
             settlePendingPurchase((current) => current.reject(normalized));
         },
     });
+    useEffect(() => {
+        connectedRef.current = connected;
+        if (!connected)
+            return;
+        setConnectionState("ready");
+        for (const waiter of connectionWaitersRef.current) {
+            clearTimeout(waiter.timeout);
+            waiter.resolve();
+        }
+        connectionWaitersRef.current.clear();
+    }, [connected]);
+    // Give up on the same budget store operations use, so the UI can offer a
+    // retry instead of spinning forever.
+    useEffect(() => {
+        if (connected) {
+            return;
+        }
+        setConnectionState("connecting");
+        const timeout = setTimeout(() => setConnectionState("unavailable"), options.connectionTimeoutMs ?? DEFAULT_CONNECTION_TIMEOUT_MS);
+        return () => clearTimeout(timeout);
+    }, [connected, connectionAttempt, options.connectionTimeoutMs]);
+    const retryConnection = useCallback(async () => {
+        if (connectedRef.current) {
+            return;
+        }
+        setConnectionState("connecting");
+        // Restart the give-up timer even when initConnection resolves instantly;
+        // `connected` only flips once expo-iap's own listener fires.
+        setConnectionAttempt((attempt) => attempt + 1);
+        try {
+            await initConnection();
+        }
+        catch {
+            // Leave the state machine to the timer: a failed attempt is only
+            // "unavailable" once the budget is actually spent.
+        }
+    }, []);
+    const waitForConnection = useCallback(async () => {
+        if (connectedRef.current)
+            return;
+        await new Promise((resolve, reject) => {
+            const waiter = {
+                resolve,
+                reject,
+                timeout: setTimeout(() => {
+                    connectionWaitersRef.current.delete(waiter);
+                    reject(new Error("Native store connection timed out."));
+                }, options.connectionTimeoutMs ?? DEFAULT_CONNECTION_TIMEOUT_MS),
+            };
+            connectionWaitersRef.current.add(waiter);
+            // The connection may have completed between the first check and
+            // registering this waiter.
+            if (connectedRef.current) {
+                connectionWaitersRef.current.delete(waiter);
+                clearTimeout(waiter.timeout);
+                resolve();
+            }
+        });
+    }, [options.connectionTimeoutMs]);
     useEffect(() => () => {
         settlePendingPurchase((item) => item.reject(new Error("Purchase interrupted.")));
+        for (const waiter of connectionWaitersRef.current) {
+            clearTimeout(waiter.timeout);
+            waiter.reject(new Error("Native store connection was interrupted."));
+        }
+        connectionWaitersRef.current.clear();
     }, [settlePendingPurchase]);
     const loadProducts = useCallback(async (requestedProductIds, force = false) => {
-        if (!connected) {
-            throw new Error("Native store is not connected.");
-        }
+        await waitForConnection();
         const requestedIds = normalizeIds(requestedProductIds);
         for (const productId of requestedIds) {
             knownProductIdsRef.current.add(productId);
@@ -111,10 +181,10 @@ export function useExpoIapBillingAdapter(options = {}) {
         }
         return matches;
     }, [
-        connected,
         options.productCacheMs,
         options.productRetryCount,
         options.productRetryDelayMs,
+        waitForConnection,
     ]);
     const reloadProducts = useCallback(async (productIds = options.productIds ?? []) => {
         const normalizedIds = normalizeIds(productIds);
@@ -138,12 +208,11 @@ export function useExpoIapBillingAdapter(options = {}) {
         const nativeAdapter = createNativeStoresBillingAdapter({
             async loadProducts({ storeProductIds }) {
                 const nativeProducts = await loadProducts(storeProductIds);
-                return nativeProducts.map(normalizeStoreProduct);
+                const eligibility = await resolveIntroOfferEligibility(nativeProducts);
+                return nativeProducts.map((product) => normalizeStoreProduct(product, eligibility));
             },
             async purchaseProduct({ storeProductId }) {
-                if (!connected) {
-                    throw new Error("Native store is not connected.");
-                }
+                await waitForConnection();
                 if (pendingPurchaseRef.current) {
                     throw new Error("Another purchase is already in progress.");
                 }
@@ -177,7 +246,7 @@ export function useExpoIapBillingAdapter(options = {}) {
                                 return;
                             }
                             if (item.bufferedError) {
-                                const recovered = isUserCancelled(item.bufferedError)
+                                const recovered = isUserCancelledError(item.bufferedError)
                                     ? await recoverPurchase(storeProductId)
                                     : null;
                                 if (recovered && pendingPurchaseRef.current === item) {
@@ -197,7 +266,7 @@ export function useExpoIapBillingAdapter(options = {}) {
                                 settlePendingPurchase((current) => current.resolve(item.bufferedPurchase));
                                 return;
                             }
-                            const recovered = isUserCancelled(error)
+                            const recovered = isUserCancelledError(error)
                                 ? await recoverPurchase(storeProductId)
                                 : null;
                             if (recovered && pendingPurchaseRef.current === item) {
@@ -212,9 +281,7 @@ export function useExpoIapBillingAdapter(options = {}) {
                 return normalizeStorePurchase(purchase);
             },
             async restorePurchases({ products: configuredProducts }) {
-                if (!connected) {
-                    throw new Error("Native store is not connected.");
-                }
+                await waitForConnection();
                 const subscriptionIds = normalizeIds([
                     ...configuredProducts.map((product) => product.storeProductId),
                     ...knownProductIdsRef.current,
@@ -285,7 +352,6 @@ export function useExpoIapBillingAdapter(options = {}) {
             },
         };
     }, [
-        connected,
         finishTransaction,
         loadProducts,
         options.purchaseTimeoutMs,
@@ -293,10 +359,13 @@ export function useExpoIapBillingAdapter(options = {}) {
         recoverPurchase,
         requestPurchase,
         settlePendingPurchase,
+        waitForConnection,
     ]);
     return {
         billingAdapter,
         connected,
+        connectionState,
+        retryConnection,
         products,
         loadingProducts,
         productError,
@@ -322,7 +391,7 @@ async function fetchSubscriptionProductsWithRetry(productIds, retryCount, retryD
     }
     throw normalizeError(lastError, "Native store did not return subscription products.");
 }
-function normalizeStoreProduct(product) {
+function normalizeStoreProduct(product, offerEligibility) {
     return {
         id: product.id,
         productId: product.id,
@@ -334,9 +403,150 @@ function normalizeStoreProduct(product) {
         subscriptionPeriod: "subscriptionPeriodUnitIOS" in product
             ? product.subscriptionPeriodUnitIOS ?? undefined
             : undefined,
+        billingPeriod: readProductBillingPeriod(product),
+        introOffer: readProductIntroOffer(product, offerEligibility),
         raw: product,
     };
 }
+function readSubscriptionGroupId(product) {
+    const groupId = product
+        .subscriptionGroupIdIOS;
+    return typeof groupId === "string" && groupId.trim() ? groupId : undefined;
+}
+/**
+ * Ask the App Store which subscription groups this customer may still claim an
+ * intro offer in. Answers are resolved once per group (not per product, since
+ * a group usually holds several SKUs) and only on iOS: Play already filters
+ * offers by eligibility, so its advertised offers are usable as-is.
+ *
+ * A failed check falls back to "eligible" — the store itself is the final
+ * authority at purchase time, so a hidden offer costs a conversion while a
+ * shown one merely reverts to the standard price.
+ */
+async function resolveIntroOfferEligibility(products) {
+    if (Platform.OS !== "ios") {
+        return () => true;
+    }
+    const groupIds = new Set(products
+        .filter((product) => product
+        .subscriptionOffers?.length)
+        .map(readSubscriptionGroupId)
+        .filter((groupId) => Boolean(groupId)));
+    if (groupIds.size === 0) {
+        return () => true;
+    }
+    const results = await Promise.all(Array.from(groupIds).map(async (groupId) => {
+        try {
+            return [groupId, await isEligibleForIntroOfferIOS(groupId)];
+        }
+        catch {
+            return [groupId, true];
+        }
+    }));
+    const eligibilityByGroup = new Map(results);
+    return (product) => {
+        const groupId = readSubscriptionGroupId(product);
+        if (!groupId) {
+            return true;
+        }
+        return eligibilityByGroup.get(groupId) ?? true;
+    };
+}
+function toBillingPeriodUnit(unit) {
+    switch (unit?.toLowerCase()) {
+        case "day":
+            return "day";
+        case "week":
+            return "week";
+        case "month":
+            return "month";
+        case "year":
+            return "year";
+        default:
+            // "unknown"/"empty" are real store values; treat them as no period
+            // rather than guessing a unit and corrupting downstream price math.
+            return undefined;
+    }
+}
+function readProductBillingPeriod(product) {
+    const record = product;
+    const unit = toBillingPeriodUnit(record.subscriptionPeriodUnitIOS);
+    if (unit) {
+        const count = Number(record.subscriptionPeriodNumberIOS ?? 1);
+        return { unit, count: Number.isFinite(count) && count > 0 ? count : 1 };
+    }
+    // Android reports the renewal period on the base plan's regular offer.
+    for (const offer of record.subscriptionOffers ?? []) {
+        if (offer.type === "introductory" || offer.type === "promotional") {
+            continue;
+        }
+        const period = toBillingPeriod(offer.period);
+        if (period) {
+            return period;
+        }
+    }
+    return undefined;
+}
+function toBillingPeriod(period) {
+    const unit = toBillingPeriodUnit(period?.unit);
+    if (!unit) {
+        return undefined;
+    }
+    const count = period?.value ?? 1;
+    return { unit, count: Number.isFinite(count) && count > 0 ? count : 1 };
+}
+function toOfferPaymentMode(mode) {
+    switch (mode?.toLowerCase()) {
+        case "free-trial":
+            return "free_trial";
+        case "pay-as-you-go":
+            return "pay_as_you_go";
+        case "pay-up-front":
+            return "pay_up_front";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Resolve the introductory offer a customer can actually use.
+ *
+ * Both stores advertise offers on the product, but "advertised" is not
+ * "available to this customer": on iOS the App Store only honours an intro
+ * offer once per subscription group, so eligibility must be checked against
+ * that group. Play only returns offers the customer qualifies for, so their
+ * presence is the answer. An offer the customer cannot redeem is omitted
+ * entirely — showing its price would be a lie on the paywall.
+ */
+function readProductIntroOffer(product, offerEligibility) {
+    const offers = product
+        .subscriptionOffers ?? [];
+    const offer = offers.find((item) => item.type === "introductory") ??
+        offers.find((item) => item.type === "promotional");
+    if (!offer) {
+        return undefined;
+    }
+    const eligible = offerEligibility ? offerEligibility(product) : true;
+    if (!eligible) {
+        return undefined;
+    }
+    return {
+        ...(offer.id ? { id: offer.id } : {}),
+        type: offer.type === "promotional" ? "promotional" : "introductory",
+        ...(offer.displayPrice ? { price: offer.displayPrice } : {}),
+        ...(typeof offer.price === "number" && Number.isFinite(offer.price)
+            ? { priceAmount: offer.price }
+            : {}),
+        ...(offer.currency ? { currency: offer.currency } : {}),
+        paymentMode: toOfferPaymentMode(offer.paymentMode),
+        ...(toBillingPeriod(offer.period)
+            ? { period: toBillingPeriod(offer.period) }
+            : {}),
+        ...(typeof offer.periodCount === "number" && offer.periodCount > 0
+            ? { periodCount: offer.periodCount }
+            : {}),
+        eligible: true,
+    };
+}
 function normalizeStorePurchase(purchase) {
     return {
         productId: purchase.productId,
@@ -415,16 +625,7 @@ function isPurchase(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";
+    return toOnbornPurchaseError(error, { productId: error.productId });
 }
 function normalizeError(error, fallback) {
     return error instanceof Error ? error : new Error(fallback);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./adapters";
 export * from "./client";
+export * from "./errors";
 export * from "./runtime";
 export * from "./types";
 export * from "./useOnbornEntitlements";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./adapters";
 export * from "./client";
+export * from "./errors";
 export * from "./runtime";
 export * from "./types";
 export * from "./useOnbornEntitlements";

package/dist/useOnbornEntitlements.d.ts

@@ -1,10 +1,24 @@
 import { type CustomerEntitlementsResponse } from "@onborn/sdk-contracts";
 export type UseOnbornEntitlementsOptions = {
     autoLoad?: boolean;
+    /**
+     * Keep the last known entitlements in `analyticsStorage` and replay them on
+     * the next cold start.
+     *
+     * Without this, `data` is null until the network answers, so a paying
+     * customer sees the free experience for the first moments of every launch —
+     * and for the whole session if they are offline. Cached entitlements are
+     * marked `stale` until a fresh response arrives; they are a UX bridge, never
+     * proof of entitlement (the server stays authoritative for anything that
+     * actually matters).
+     */
+    cache?: boolean;
 };
 export type UseOnbornEntitlementsState = {
     data: CustomerEntitlementsResponse | null;
     loading: boolean;
+    /** True while `data` comes from the cache and no fresh response has landed. */
+    stale: boolean;
     error: string | null;
     reload: () => Promise<CustomerEntitlementsResponse>;
     hasEntitlement: (keyOrId: string) => boolean;

package/dist/useOnbornEntitlements.js

@@ -1,11 +1,14 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { createBillingClient } from "./client";
 import { useOnbornBillingConfig } from "./runtime";
+const ENTITLEMENTS_CACHE_PREFIX = "onborn:entitlements";
 export function useOnbornEntitlements(options = {}) {
     const runtimeOptions = useOnbornBillingConfig(options);
     const [data, setData] = useState(null);
     const [loading, setLoading] = useState(options.autoLoad !== false);
+    const [stale, setStale] = useState(false);
     const [error, setError] = useState(null);
+    const freshRef = useRef(false);
     const client = useMemo(() => createBillingClient({
         sourceId: "entitlements",
     }), [
@@ -21,12 +24,26 @@ export function useOnbornEntitlements(options = {}) {
         runtimeOptions.sdkVersion,
         runtimeOptions.userId,
     ]);
+    // Scope the cache to the user: a device that switches accounts (or upgrades
+    // from anonymous to signed-in) must never replay the previous user's
+    // entitlements.
+    const cacheKey = options.cache
+        ? `${ENTITLEMENTS_CACHE_PREFIX}:${runtimeOptions.userId ?? "anonymous"}`
+        : null;
+    const storage = options.cache ? runtimeOptions.analyticsStorage : undefined;
     const reload = useCallback(async () => {
         setLoading(true);
         setError(null);
         try {
             const response = await client.loadCustomerEntitlements();
+            freshRef.current = true;
             setData(response);
+            setStale(false);
+            if (storage && cacheKey) {
+                void storage
+                    .setItem(cacheKey, JSON.stringify(response))
+                    .catch(() => undefined);
+            }
             return response;
         }
         catch (loadError) {
@@ -37,18 +54,44 @@ export function useOnbornEntitlements(options = {}) {
         finally {
             setLoading(false);
         }
-    }, [client]);
+    }, [cacheKey, client, storage]);
+    useEffect(() => {
+        if (!storage || !cacheKey) {
+            return;
+        }
+        let cancelled = false;
+        void (async () => {
+            try {
+                const cached = await storage.getItem(cacheKey);
+                // A fresh response may have landed while storage was reading; it always
+                // wins over the cache.
+                if (cancelled || !cached || freshRef.current) {
+                    return;
+                }
+                setData(JSON.parse(cached));
+                setStale(true);
+            }
+            catch {
+                // A corrupt or unreadable cache is not worth surfacing: the network
+                // response is on its way regardless.
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [cacheKey, storage]);
     useEffect(() => {
         if (options.autoLoad === false) {
             return;
         }
-        void reload();
+        void reload().catch(() => undefined);
     }, [options.autoLoad, reload]);
     const hasEntitlement = useCallback((keyOrId) => data?.entitlements.some((item) => item.active &&
         (item.key === keyOrId || item.entitlementId === keyOrId)) ?? false, [data?.entitlements]);
     return {
         data,
         loading,
+        stale,
         error,
         reload,
         hasEntitlement,

package/dist/useOnbornOffering.js

@@ -38,10 +38,21 @@ export function useOnbornOffering(options = {}) {
         setError(null);
         try {
             const response = await client.loadOffering();
+            // Store localization is an enhancement, not a precondition. The native
+            // store connection can be cold or briefly unavailable (app resumed,
+            // StoreKit reconnecting), and treating that as fatal blanked an offering
+            // the backend had already returned — the paywall showed a retry button
+            // even though it had everything it needed to render. Fall back to the
+            // synced catalog products instead; `purchasePackage` still goes through
+            // the adapter and surfaces a real error if the store is truly
+            // unreachable.
             const products = await loadLocalizedProducts(runtimeOptions.billingAdapter, {
                 offering: response.offering,
                 products: response.products,
                 userId: runtimeOptions.userId,
+            }).catch((productsError) => {
+                console.warn("[onborn] Native store products unavailable; showing catalog prices.", productsError);
+                return response.products;
             });
             setData({ ...response, products });
             setSelectedPackageId((current) => {

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { BillingOffering, BillingPackage, BillingPlatform, BillingProduct } from "@onborn/sdk-contracts";
+import type { BillingOffering, BillingPackage, BillingPeriod, BillingPeriodUnit, BillingPlatform, BillingProduct } from "@onborn/sdk-contracts";
 import type { OnbornPackageWithProduct } from "./types";
 export declare function getPackagesWithProducts(offering: BillingOffering | undefined, products: BillingProduct[] | undefined, platform?: BillingPlatform): OnbornPackageWithProduct[];
 export declare function resolveDefaultPackageId(offering: BillingOffering | undefined): string | undefined;
@@ -6,3 +6,38 @@ export declare function findPackageWithProduct(packages: OnbornPackageWithProduc
 export declare function formatPackagePrice(product: BillingProduct | undefined, fallback?: string): string;
 export declare function getStoreProductId(billingPackage: BillingPackage, product: BillingProduct | undefined): string;
 export declare function formatBillingPeriod(period: string | undefined): string;
+/**
+ * @deprecated Use `BillingPeriod` from `@onborn/sdk-contracts`.
+ * Kept as an alias so existing imports keep compiling.
+ */
+export type ParsedBillingPeriod = BillingPeriod;
+/**
+ * Parse a store billing period into machine-readable form.
+ *
+ * Stores disagree on the wire format: Apple sends ISO-8601 durations (`P1Y`),
+ * Play sends the same or a named constant, and catalog sync may pass through
+ * whatever the store gave it. Anything unrecognized returns `undefined` rather
+ * than a guess — a wrong period silently corrupts price math.
+ */
+export declare function parseBillingPeriod(period: string | undefined): BillingPeriod | undefined;
+/** Format an amount using the store's currency, falling back to a plain number. */
+export declare function formatPrice(amount: number, currency: string | undefined, locale?: string): string;
+/**
+ * Break a subscription price down to a shorter unit — the "only 9,99 zł/week"
+ * line every annual plan shows.
+ *
+ * Returns `undefined` (never a guess) when the product has no numeric price or
+ * an unparseable period, so a missing value is visibly missing instead of
+ * quietly wrong.
+ */
+export declare function getPricePerPeriod(product: BillingProduct | undefined, unit: BillingPeriodUnit, options?: {
+    locale?: string;
+}): {
+    amount: number;
+    formatted: string;
+} | undefined;
+/**
+ * The product's renewal period, preferring the adapter-normalized
+ * `billingPeriod` and falling back to parsing the raw store string.
+ */
+export declare function resolveBillingPeriod(product: BillingProduct | undefined): BillingPeriod | undefined;

package/dist/utils.js

@@ -56,3 +56,115 @@ export function formatBillingPeriod(period) {
             return period ?? "";
     }
 }
+const PERIOD_UNIT_DAYS = {
+    day: 1,
+    week: 7,
+    month: 30.4375,
+    year: 365.25,
+};
+const NAMED_PERIODS = {
+    day: { unit: "day", count: 1 },
+    daily: { unit: "day", count: 1 },
+    one_day: { unit: "day", count: 1 },
+    week: { unit: "week", count: 1 },
+    weekly: { unit: "week", count: 1 },
+    one_week: { unit: "week", count: 1 },
+    month: { unit: "month", count: 1 },
+    monthly: { unit: "month", count: 1 },
+    one_month: { unit: "month", count: 1 },
+    two_months: { unit: "month", count: 2 },
+    three_months: { unit: "month", count: 3 },
+    six_months: { unit: "month", count: 6 },
+    year: { unit: "year", count: 1 },
+    yearly: { unit: "year", count: 1 },
+    annual: { unit: "year", count: 1 },
+    one_year: { unit: "year", count: 1 },
+};
+/**
+ * Parse a store billing period into machine-readable form.
+ *
+ * Stores disagree on the wire format: Apple sends ISO-8601 durations (`P1Y`),
+ * Play sends the same or a named constant, and catalog sync may pass through
+ * whatever the store gave it. Anything unrecognized returns `undefined` rather
+ * than a guess — a wrong period silently corrupts price math.
+ */
+export function parseBillingPeriod(period) {
+    const normalized = period?.trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    const named = NAMED_PERIODS[normalized];
+    if (named) {
+        return named;
+    }
+    // ISO-8601 duration: P1Y, P6M, P2W, P30D.
+    const iso = normalized.match(/^p(\d+)([dwmy])$/);
+    if (!iso) {
+        return undefined;
+    }
+    const count = Number(iso[1]);
+    if (!Number.isFinite(count) || count <= 0) {
+        return undefined;
+    }
+    const unit = { d: "day", w: "week", m: "month", y: "year" };
+    const key = iso[2];
+    return { unit: unit[key], count };
+}
+/** Format an amount using the store's currency, falling back to a plain number. */
+export function formatPrice(amount, currency, locale) {
+    if (!Number.isFinite(amount)) {
+        return "";
+    }
+    if (currency) {
+        try {
+            return new Intl.NumberFormat(locale, {
+                style: "currency",
+                currency,
+                maximumFractionDigits: 2,
+            }).format(amount);
+        }
+        catch {
+            // Unknown currency code or an environment without full ICU data.
+        }
+    }
+    return amount.toFixed(2);
+}
+/**
+ * Break a subscription price down to a shorter unit — the "only 9,99 zł/week"
+ * line every annual plan shows.
+ *
+ * Returns `undefined` (never a guess) when the product has no numeric price or
+ * an unparseable period, so a missing value is visibly missing instead of
+ * quietly wrong.
+ */
+export function getPricePerPeriod(product, unit, options) {
+    const amount = product?.priceAmount;
+    if (typeof amount !== "number" || !Number.isFinite(amount)) {
+        return undefined;
+    }
+    const period = resolveBillingPeriod(product);
+    if (!period) {
+        return undefined;
+    }
+    const periodUnitDays = PERIOD_UNIT_DAYS[period.unit];
+    const targetDays = PERIOD_UNIT_DAYS[unit];
+    if (!periodUnitDays || !targetDays) {
+        return undefined;
+    }
+    const periodDays = periodUnitDays * period.count;
+    if (periodDays <= 0) {
+        return undefined;
+    }
+    const perUnit = (amount / periodDays) * targetDays;
+    return {
+        amount: perUnit,
+        formatted: formatPrice(perUnit, product?.currency, options?.locale),
+    };
+}
+/**
+ * The product's renewal period, preferring the adapter-normalized
+ * `billingPeriod` and falling back to parsing the raw store string.
+ */
+export function resolveBillingPeriod(product) {
+    return product?.billingPeriod ?? parseBillingPeriod(product?.period);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onborn/billing",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Headless billing, offerings, purchases, restores, and entitlements for Onborn.",
   "license": "UNLICENSED",
   "repository": {
@@ -46,8 +46,8 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@onborn/analytics": "0.1.0-beta.2",
-    "@onborn/sdk-contracts": "0.1.0-beta.1"
+    "@onborn/analytics": "0.1.0-beta.3",
+    "@onborn/sdk-contracts": "0.1.0-beta.3"
   },
   "peerDependencies": {
     "expo-iap": ">=4.5.0",