@onborn/billing 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0-beta.1
+
+- Added headless offering, paywall, purchase, restore, and entitlement APIs.
+- Added native-store, RevenueCat, and mock billing adapters.
+- Added shared initialization through `Onborn.init(...)` from `@onborn/analytics`.

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Onborn.
+
+All rights reserved.
+
+This package is proprietary software. It is published only for use with Onborn
+products and services. No permission is granted to copy, modify, sublicense,
+redistribute, or use this software outside an authorized Onborn integration
+unless a separate written agreement says otherwise.

package/README.md

@@ -0,0 +1,49 @@
+# @onborn/billing
+
+Headless Onborn billing for apps that own their onboarding and paywall UI.
+
+It provides offering and paywall data, native-store adapters, purchase and
+restore validation, and entitlement state without installing the Onborn UI
+renderer.
+
+```ts
+import {
+  Onborn,
+  createNativeStoresBillingAdapter,
+  useOnbornEntitlements,
+} from "@onborn/billing";
+
+Onborn.init({
+  apiKey: "onborn_test_...",
+  userId: "customer_123",
+  appVersion: "1.0.0",
+  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") };
+}
+```
+
+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.
+
+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.
+
+`@onborn/rn-sdk` re-exports this package for apps that render Onborn flows.
+
+## Documentation
+
+- [Headless billing](../../docs/rn-sdk/billing.md)
+- [Standalone analytics](../../docs/rn-sdk/analytics.md)
+- [Full React Native SDK](../../docs/rn-sdk/rn-sdk.md)

package/dist/adapters/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./mock";
+export * from "./nativeStores";
+export * from "./revenueCat";

package/dist/adapters/index.js

@@ -0,0 +1,3 @@
+export * from "./mock";
+export * from "./nativeStores";
+export * from "./revenueCat";

package/dist/adapters/mock.d.ts

@@ -0,0 +1,14 @@
+import type { OnbornBillingAdapter } from "../types";
+export type MockBillingAdapterOptions = {
+    /** Prefix for synthetic transaction IDs sent to ONBORN validate. */
+    transactionIdPrefix?: string;
+    /** Optional delay to mimic store latency in dev. */
+    purchaseDelayMs?: number;
+    restoreDelayMs?: number;
+};
+/**
+ * Dev-only billing adapter: simulates successful store purchase/restore without
+ * RevenueCat or native IAP. Pair with ONBORN `test` environment for end-to-end
+ * paywall → validate → entitlement flow.
+ */
+export declare function createMockBillingAdapter(options?: MockBillingAdapterOptions): OnbornBillingAdapter;

package/dist/adapters/mock.js

@@ -0,0 +1,88 @@
+/**
+ * Dev-only billing adapter: simulates successful store purchase/restore without
+ * RevenueCat or native IAP. Pair with ONBORN `test` environment for end-to-end
+ * paywall → validate → entitlement flow.
+ */
+export function createMockBillingAdapter(options = {}) {
+    const transactionIdPrefix = options.transactionIdPrefix ?? "mock";
+    return {
+        async purchasePackage(input) {
+            await delay(options.purchaseDelayMs);
+            const storeProductId = input.product?.storeProductId ?? input.package.productId;
+            if (!storeProductId) {
+                throw new Error(`Missing storeProductId for ONBORN package '${input.package.id}'.`);
+            }
+            const transactionId = `${transactionIdPrefix}-${Date.now()}-${input.package.id}`;
+            return {
+                success: true,
+                packageId: input.package.id,
+                productId: storeProductId,
+                transactionId,
+                receipt: JSON.stringify({
+                    mock: true,
+                    userId: input.userId,
+                    offeringId: input.offering.id,
+                    packageId: input.package.id,
+                    storeProductId,
+                    transactionId,
+                }),
+                raw: {
+                    mock: true,
+                    mode: "purchase",
+                },
+            };
+        },
+        async restorePurchases(input) {
+            await delay(options.restoreDelayMs);
+            const activeProductIds = input.products
+                .map((product) => product.storeProductId)
+                .filter((id) => Boolean(id?.trim()));
+            const purchases = input.products
+                .filter((product) => (product.store === "app_store" ||
+                product.store === "google_play") &&
+                Boolean(product.storeProductId?.trim()))
+                .map((product) => {
+                const storeProductId = product.storeProductId ?? product.id;
+                return {
+                    store: product.store,
+                    storeProductId,
+                    transactionId: `${transactionIdPrefix}-restore-${Date.now()}-${product.id}`,
+                    raw: {
+                        mock: true,
+                        mode: "restore_purchase",
+                        productId: product.id,
+                    },
+                };
+            });
+            return {
+                success: true,
+                activeProductIds,
+                entitlementIds: [],
+                purchases,
+                raw: {
+                    mock: true,
+                    mode: "restore",
+                    userId: input.userId,
+                },
+            };
+        },
+        async refetchCustomerEntitlements(input) {
+            return {
+                success: true,
+                raw: {
+                    mock: true,
+                    mode: "refetch",
+                    userId: input.userId,
+                },
+            };
+        },
+    };
+}
+function delay(ms) {
+    if (!ms || ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/adapters/nativeStores.d.ts

@@ -0,0 +1,46 @@
+import type { NativeStoreRestoredPurchase } from "@onborn/sdk-contracts";
+import type { OnbornBillingAdapter, OnbornLoadProductsInput, OnbornPurchaseInput, OnbornRestoreInput } from "../types";
+type NativeStoresPurchase = {
+    productId?: string;
+    storeProductId?: string;
+    transactionId?: string;
+    purchaseToken?: string;
+    originalTransactionIdentifierIOS?: string;
+    raw?: unknown;
+};
+type NativeStoresProduct = {
+    productId?: string;
+    storeProductId?: string;
+    id?: string;
+    title?: string;
+    description?: string;
+    price?: string | number;
+    priceString?: string;
+    localizedPrice?: string;
+    localizedPriceString?: string;
+    displayPrice?: string;
+    formattedPrice?: string;
+    currency?: string;
+    currencyCode?: string;
+    period?: string;
+    subscriptionPeriod?: string;
+    raw?: unknown;
+};
+type NativeStoresRestoreOutput = NativeStoreRestoredPurchase[] | {
+    purchases?: NativeStoreRestoredPurchase[];
+    raw?: unknown;
+} | unknown[] | void;
+export type NativeStoresBillingAdapterOptions = {
+    loadProducts?: (input: OnbornLoadProductsInput & {
+        storeProductIds: string[];
+    }) => Promise<NativeStoresProduct[] | void>;
+    purchaseProduct: (input: OnbornPurchaseInput & {
+        storeProductId: string;
+    }) => Promise<NativeStoresPurchase | void>;
+    restorePurchases?: (input: OnbornRestoreInput) => Promise<NativeStoresRestoreOutput>;
+    refetchCustomerEntitlements?: (input: {
+        userId?: string;
+    }) => Promise<unknown>;
+};
+export declare function createNativeStoresBillingAdapter(options: NativeStoresBillingAdapterOptions): OnbornBillingAdapter;
+export {};

package/dist/adapters/nativeStores.js

@@ -0,0 +1,166 @@
+export function createNativeStoresBillingAdapter(options) {
+    return {
+        async loadProducts(input) {
+            if (!options.loadProducts) {
+                return input.products;
+            }
+            const storeProductIds = input.products
+                .map((product) => product.storeProductId)
+                .filter((id) => Boolean(id?.trim()));
+            if (storeProductIds.length === 0) {
+                return input.products;
+            }
+            const nativeProducts = (await options.loadProducts({
+                ...input,
+                storeProductIds: Array.from(new Set(storeProductIds)),
+            })) ?? [];
+            if (nativeProducts.length === 0) {
+                return input.products;
+            }
+            return localizeProducts(input.products, nativeProducts);
+        },
+        async purchasePackage(input) {
+            const storeProductId = input.product?.storeProductId;
+            if (!storeProductId) {
+                throw new Error(`Missing storeProductId for ONBORN package '${input.package.id}'.`);
+            }
+            const purchase = await options.purchaseProduct({
+                ...input,
+                storeProductId,
+            });
+            return {
+                success: true,
+                packageId: input.package.id,
+                productId: storeProductId,
+                transactionId: readTransactionId(purchase),
+                purchaseToken: purchase?.purchaseToken,
+                raw: purchase,
+            };
+        },
+        async restorePurchases(input) {
+            if (!options.restorePurchases) {
+                throw new Error("Missing native store restorePurchases implementation.");
+            }
+            const result = await options.restorePurchases(input);
+            const normalized = normalizeNativeRestoreOutput(result);
+            return {
+                success: true,
+                purchases: normalized.purchases,
+                raw: normalized.raw,
+            };
+        },
+        async refetchCustomerEntitlements(input) {
+            const result = await options.refetchCustomerEntitlements?.(input);
+            return {
+                success: true,
+                raw: result,
+            };
+        },
+    };
+}
+function localizeProducts(products, nativeProducts) {
+    return products.map((product) => {
+        const nativeProduct = findNativeProduct(product, nativeProducts);
+        if (!nativeProduct) {
+            return product;
+        }
+        return {
+            ...product,
+            title: readString(nativeProduct.title) ?? product.title,
+            description: readString(nativeProduct.description) ?? product.description,
+            price: readNativePrice(nativeProduct) ?? product.price,
+            currency: readString(nativeProduct.currencyCode) ??
+                readString(nativeProduct.currency) ??
+                product.currency,
+            period: readString(nativeProduct.subscriptionPeriod) ??
+                readString(nativeProduct.period) ??
+                product.period,
+            metadata: {
+                ...product.metadata,
+                nativeStoreProduct: nativeProduct.raw ?? nativeProduct,
+            },
+        };
+    });
+}
+function findNativeProduct(product, nativeProducts) {
+    return nativeProducts.find((nativeProduct) => {
+        const identifiers = [
+            nativeProduct.storeProductId,
+            nativeProduct.productId,
+            nativeProduct.id,
+        ].filter(Boolean);
+        return (identifiers.includes(product.storeProductId) ||
+            identifiers.includes(product.id));
+    });
+}
+function readNativePrice(product) {
+    return (readString(product.priceString) ??
+        readString(product.localizedPriceString) ??
+        readString(product.localizedPrice) ??
+        readString(product.displayPrice) ??
+        readString(product.formattedPrice) ??
+        readPriceValue(product.price));
+}
+function normalizeNativeRestoreOutput(output) {
+    if (Array.isArray(output)) {
+        return {
+            purchases: output
+                .map(normalizeNativeRestoredPurchase)
+                .filter((item) => Boolean(item)),
+            raw: output,
+        };
+    }
+    if (output && typeof output === "object") {
+        const result = output;
+        const purchases = Array.isArray(result.purchases)
+            ? result.purchases
+                .map(normalizeNativeRestoredPurchase)
+                .filter((item) => Boolean(item))
+            : [];
+        return {
+            purchases,
+            raw: result.raw ?? output,
+        };
+    }
+    return {
+        purchases: [],
+        raw: output,
+    };
+}
+function normalizeNativeRestoredPurchase(value) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const record = value;
+    const store = record.store;
+    const storeProductId = readString(record.storeProductId) ??
+        readString(record.productId) ??
+        readString(record.productIds);
+    if ((store !== "app_store" && store !== "google_play") || !storeProductId) {
+        return null;
+    }
+    return {
+        store,
+        storeProductId,
+        transactionId: readString(record.transactionId) ??
+            readString(record.originalTransactionIdentifierIOS),
+        purchaseToken: readString(record.purchaseToken),
+        raw: record.raw ?? value,
+    };
+}
+function readTransactionId(purchase) {
+    return (purchase?.transactionId ??
+        purchase?.purchaseToken ??
+        purchase?.originalTransactionIdentifierIOS);
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : undefined;
+}
+function readPriceValue(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(value);
+    }
+    return readString(value);
+}

package/dist/adapters/revenueCat.d.ts

@@ -0,0 +1,90 @@
+import type { BillingRuntimeConfig } from "@onborn/sdk-contracts";
+import type { OnbornBillingAdapter, OnbornPurchaseInput } from "../types";
+type RevenueCatCustomerInfo = {
+    originalAppUserId?: string;
+    originalAppUserID?: string;
+    entitlements?: {
+        active?: Record<string, unknown>;
+    };
+    activeSubscriptions?: string[];
+    allPurchasedProductIdentifiers?: string[];
+    nonSubscriptionTransactions?: Array<{
+        productIdentifier?: string;
+        productId?: string;
+    }>;
+};
+type RevenueCatStoreProduct = {
+    identifier?: string;
+    productIdentifier?: string;
+    title?: string;
+    description?: string;
+    price?: number | string;
+    priceString?: string;
+    localizedPriceString?: string;
+    currencyCode?: string;
+    currency?: string;
+    subscriptionPeriod?: string;
+    period?: string;
+    trialPeriod?: string;
+    trialDuration?: string;
+    trial_duration?: string;
+    freeTrialPeriod?: string;
+    introPrice?: {
+        period?: string;
+        subscriptionPeriod?: string;
+    } | null;
+    introductoryPrice?: {
+        period?: string;
+        subscriptionPeriod?: string;
+    } | null;
+};
+type RevenueCatPackage = {
+    identifier?: string;
+    packageType?: string;
+    product?: RevenueCatStoreProduct;
+};
+type RevenueCatOffering = {
+    identifier?: string;
+    availablePackages?: RevenueCatPackage[];
+};
+type RevenueCatOfferings = {
+    current?: RevenueCatOffering | null;
+    all?: Record<string, RevenueCatOffering | undefined>;
+};
+export type RevenueCatPurchasesModule = {
+    configure?: (options: {
+        apiKey: string;
+        appUserID?: string;
+    }) => void | Promise<void>;
+    getOfferings: () => Promise<RevenueCatOfferings>;
+    purchasePackage: (pkg: RevenueCatPackage) => Promise<{
+        customerInfo?: RevenueCatCustomerInfo;
+        productIdentifier?: string;
+    }>;
+    restorePurchases: () => Promise<RevenueCatCustomerInfo>;
+    getCustomerInfo?: () => Promise<RevenueCatCustomerInfo>;
+    logIn?: (appUserId: string) => Promise<{
+        customerInfo?: RevenueCatCustomerInfo;
+        created?: boolean;
+    }>;
+};
+export type RevenueCatBillingAdapterOptions = {
+    purchases: RevenueCatPurchasesModule;
+    /**
+     * Calls RevenueCat `logIn(userId)` before purchase/restore/refetch when the
+     * method exists. Keep this on unless the host app configures RevenueCat with
+     * the same appUserID before creating the adapter.
+     */
+    identifyUser?: boolean;
+    resolvePackage?: (input: OnbornPurchaseInput, offerings: RevenueCatOfferings) => RevenueCatPackage | Promise<RevenueCatPackage>;
+};
+export declare function createRevenueCatBillingAdapter(options: RevenueCatBillingAdapterOptions): OnbornBillingAdapter;
+export type ConfigureRevenueCatPurchasesOptions = {
+    purchases: RevenueCatPurchasesModule;
+    billing?: BillingRuntimeConfig;
+    platform?: "ios" | "android";
+    userId?: string;
+};
+export declare function configureRevenueCatPurchases(options: ConfigureRevenueCatPurchasesOptions): Promise<void>;
+export declare function resolveRevenueCatSdkKey(options: Pick<ConfigureRevenueCatPurchasesOptions, "billing" | "platform">): string | undefined;
+export {};

package/dist/adapters/revenueCat.js

@@ -0,0 +1,208 @@
+import { Platform } from "react-native";
+export function createRevenueCatBillingAdapter(options) {
+    return {
+        async loadProducts(input) {
+            await identifyRevenueCatUser(options, input.userId);
+            const offerings = await options.purchases.getOfferings();
+            return localizeProductsFromRevenueCat(input, offerings);
+        },
+        async purchasePackage(input) {
+            await identifyRevenueCatUser(options, input.userId);
+            const offerings = await options.purchases.getOfferings();
+            const revenueCatPackage = options.resolvePackage
+                ? await options.resolvePackage(input, offerings)
+                : resolveRevenueCatPackage(input, offerings);
+            const result = await options.purchases.purchasePackage(revenueCatPackage);
+            return {
+                success: true,
+                packageId: input.package.id,
+                productId: result.productIdentifier ??
+                    input.product?.storeProductId ??
+                    input.package.productId,
+                entitlementIds: readActiveEntitlementIds(result.customerInfo),
+                activeProductIds: readActiveProductIds(result.customerInfo),
+                raw: result,
+            };
+        },
+        async restorePurchases(input) {
+            await identifyRevenueCatUser(options, input.userId);
+            const customerInfo = await options.purchases.restorePurchases();
+            return {
+                success: true,
+                entitlementIds: readActiveEntitlementIds(customerInfo),
+                activeProductIds: readActiveProductIds(customerInfo),
+                raw: {
+                    customerInfo,
+                    productIds: input.products.map((product) => product.storeProductId),
+                },
+            };
+        },
+        async refetchCustomerEntitlements(input) {
+            await identifyRevenueCatUser(options, input.userId);
+            if (!options.purchases.getCustomerInfo) {
+                throw new Error("Missing RevenueCat getCustomerInfo implementation.");
+            }
+            const customerInfo = await options.purchases.getCustomerInfo();
+            return {
+                success: true,
+                entitlementIds: readActiveEntitlementIds(customerInfo),
+                activeProductIds: readActiveProductIds(customerInfo),
+                raw: { customerInfo },
+            };
+        },
+    };
+}
+export async function configureRevenueCatPurchases(options) {
+    if (!options.purchases.configure) {
+        throw new Error("Missing RevenueCat configure implementation.");
+    }
+    const apiKey = resolveRevenueCatSdkKey(options);
+    if (!apiKey) {
+        throw new Error("Missing RevenueCat public SDK key for current platform.");
+    }
+    await options.purchases.configure({
+        apiKey,
+        ...(options.userId
+            ? {
+                appUserID: options.userId,
+            }
+            : {}),
+    });
+}
+export function resolveRevenueCatSdkKey(options) {
+    if (options.billing?.provider !== "revenuecat") {
+        return undefined;
+    }
+    const platform = options.platform ?? resolveRuntimePlatform();
+    return platform === "android"
+        ? options.billing.revenueCat?.androidSdkKey
+        : options.billing.revenueCat?.iosSdkKey;
+}
+async function identifyRevenueCatUser(options, userId) {
+    if (options.identifyUser === false || !userId || !options.purchases.logIn) {
+        return;
+    }
+    await options.purchases.logIn(userId);
+}
+function resolveRuntimePlatform() {
+    return Platform.OS === "android" ? "android" : "ios";
+}
+function resolveRevenueCatPackage(input, offerings) {
+    const match = findRevenueCatPackage(input, offerings);
+    if (!match) {
+        throw new Error(`RevenueCat package not found for ONBORN package '${input.package.id}'.`);
+    }
+    return match;
+}
+function findRevenueCatPackage(input, offerings) {
+    const candidates = listRevenueCatPackages(input, offerings);
+    const productId = input.product?.storeProductId;
+    return candidates.find((candidate) => {
+        const identifiers = [
+            candidate.identifier,
+            candidate.packageType,
+            candidate.product?.identifier,
+            candidate.product?.productIdentifier,
+        ].filter(Boolean);
+        return (identifiers.includes(input.package.id) ||
+            identifiers.includes(input.package.productId) ||
+            (productId ? identifiers.includes(productId) : false));
+    });
+}
+function listRevenueCatPackages(input, offerings) {
+    const offeringKeys = [
+        input.offering.providerOfferingId,
+        input.offering.key,
+        input.offering.id,
+    ].filter((key) => Boolean(key));
+    const preferredOfferings = offeringKeys
+        .map((key) => offerings.all?.[key])
+        .filter((offering) => Boolean(offering));
+    const allOfferings = Object.values(offerings.all ?? {}).filter((offering) => Boolean(offering));
+    return [...preferredOfferings, offerings.current, ...allOfferings]
+        .filter((offering) => Boolean(offering))
+        .flatMap((offering) => offering.availablePackages ?? []);
+}
+function localizeProductsFromRevenueCat(input, offerings) {
+    if (!input.offering) {
+        return input.products;
+    }
+    const offering = input.offering;
+    return input.products.map((product) => {
+        const billingPackage = offering.packages.find((item) => packageReferencesProduct(item, product));
+        if (!billingPackage) {
+            return product;
+        }
+        const revenueCatPackage = findRevenueCatPackage({
+            paywall: input.paywall,
+            offering,
+            package: billingPackage,
+            product,
+            userId: input.userId,
+        }, offerings);
+        const revenueCatProduct = revenueCatPackage?.product;
+        if (!revenueCatProduct) {
+            return product;
+        }
+        return {
+            ...product,
+            title: revenueCatProduct.title ?? product.title,
+            description: revenueCatProduct.description ?? product.description,
+            price: readRevenueCatPrice(revenueCatProduct) ?? product.price,
+            currency: revenueCatProduct.currencyCode ??
+                revenueCatProduct.currency ??
+                product.currency,
+            period: revenueCatProduct.subscriptionPeriod ??
+                revenueCatProduct.period ??
+                product.period,
+            trialPeriod: readRevenueCatTrialPeriod(revenueCatProduct) ?? product.trialPeriod,
+        };
+    });
+}
+function packageReferencesProduct(billingPackage, product) {
+    const referencedIds = [
+        billingPackage.productId,
+        billingPackage.productIdsByStore?.app_store,
+        billingPackage.productIdsByStore?.google_play,
+        billingPackage.productIdsByStore?.revenuecat_custom,
+    ].filter((value) => Boolean(value));
+    return (referencedIds.includes(product.id) ||
+        referencedIds.includes(product.storeProductId));
+}
+function readRevenueCatPrice(product) {
+    if (product.priceString) {
+        return product.priceString;
+    }
+    if (product.localizedPriceString) {
+        return product.localizedPriceString;
+    }
+    if (typeof product.price === "string") {
+        return product.price;
+    }
+    return undefined;
+}
+function readRevenueCatTrialPeriod(product) {
+    return (product.trialPeriod ??
+        product.trialDuration ??
+        product.trial_duration ??
+        product.freeTrialPeriod ??
+        product.introPrice?.period ??
+        product.introPrice?.subscriptionPeriod ??
+        product.introductoryPrice?.period ??
+        product.introductoryPrice?.subscriptionPeriod);
+}
+function readActiveEntitlementIds(customerInfo) {
+    return Object.keys(customerInfo?.entitlements?.active ?? {});
+}
+function readActiveProductIds(customerInfo) {
+    return uniqueCompact([
+        ...(customerInfo?.activeSubscriptions ?? []),
+        ...(customerInfo?.allPurchasedProductIdentifiers ?? []),
+        ...(customerInfo?.nonSubscriptionTransactions ?? []).flatMap((transaction) => [transaction.productIdentifier, transaction.productId]),
+    ]);
+}
+function uniqueCompact(values) {
+    return [
+        ...new Set(values.filter((value) => Boolean(value))),
+    ];
+}