@biltme/iap

Thin Expo / React Native client wrapper for the bilt-billing backend.

@biltme/iap gives a React app a single provider + two hooks that handle the full in-app purchase lifecycle on iOS:

• Bootstrap the user with the backend (gets an appAccountToken).
• Fetch App Store product metadata through expo-iap.
• Drive native purchases and forward receipts to POST /v1/iap/purchases/ingest.
• Expose a backend-authoritative entitlements map to the UI.
• Restore purchases via expo-iap + POST /v1/iap/restore.
• Open the native Manage Subscriptions sheet.
• Transparently retry ingest calls that failed due to network / transient errors, persisted across app restarts.

Only iOS is wired up today. The provider is safe to mount on Android — it will bootstrap entitlements and skip the store calls.

Contents

• Installation
• Quick start
• Configuration (BiltIapConfig)
• BiltIapProvider
• Hooks
  • useBiltIAP()
  • useEntitlement(code)
• Entitlements
• Products
• Error handling (BiltIapError)
• Offline retry queue
• Lifecycle behavior
• Backend endpoints used
• Metro / workspace resolution
• Testapp reference

Installation

This package is published as a workspace package inside the bilt-billing repo. Consumers install it by path (or through the workspace) and own the native peer dependencies themselves.

Peer dependencies (must live in the host app's node_modules):

• react >= 18
• react-native >= 0.72
• expo-iap >= 3
• @react-native-async-storage/async-storage >= 2

They are peers because both the host app and @biltme/iap must see the exact same copy. Duplicating react or react-native produces runtime errors like Invalid hook call or Cannot read property 'useRef' of null.

expo-iap requires a custom dev build. Expo Go cannot load it.

Quick start

import React from 'react';
import {BiltIapProvider, useBiltIAP, useEntitlement} from '@biltme/iap';
import type {BiltIapConfig} from '@biltme/iap';

const config: BiltIapConfig = {
  tenantAppId: '11111111-1111-1111-1111-111111111111',
  getAccessToken: async () => auth.getToken(),
  productIds: ['com.example.pro.monthly'],
  onError: (err) =>
    console.warn('[BiltIAP]', {
      code: err.code,
      message: err.message,
      retryable: err.retryable,
      requestId: err.requestId,
      cause: err.cause,
    }),
};

export default function App() {
  return (
    <BiltIapProvider config={config}>
      <PaywallScreen />
    </BiltIapProvider>
  );
}

function PaywallScreen() {
  const {initialized, products, purchaseProduct, restorePurchases} = useBiltIAP();
  const pro = useEntitlement('pro');

  if (!initialized) return null;
  if (pro.active) return <ProFeatures />;

  return (
    <>
      {products.map((p) => (
        <Button
          key={p.productId}
          title={`Buy ${p.title} — ${p.displayPrice}`}
          onPress={() => purchaseProduct(p.productId)}
        />
      ))}
      <Button title="Restore Purchases" onPress={() => restorePurchases()} />
    </>
  );
}

A complete, runnable example (UI, synthetic purchases, StoreKit, restore, notifications) lives in testapp/App.tsx and testapp/src/BillingScreen.tsx.

Configuration (BiltIapConfig)

getAccessToken is read on every backend call. If your app rotates sessions or refreshes tokens in the background, return the latest access token from this callback.

If you need to point at a local or staging billing backend, override it explicitly:

const config: BiltIapConfig = {
  backendUrl: 'http://127.0.0.1:8099',
  tenantAppId: '11111111-1111-1111-1111-111111111111',
  getAccessToken: async () => auth.getToken(),
  productIds: ['com.example.pro.monthly'],
};

BiltIapProvider

<BiltIapProvider config={config}>{children}</BiltIapProvider>

On mount the provider:

1. Calls GET /v1/iap/bootstrap to obtain appAccountToken and the initial entitlements map for the user represented by the bearer token.
2. On iOS, calls ExpoIap.initConnection() and ExpoIap.fetchProducts({skus: productIds, type: 'all'}) so both subscriptions and one-time SKUs load.
3. Loads the persisted retry queue from AsyncStorage and flushes it.
4. Subscribes to ExpoIap.purchaseUpdatedListener and ExpoIap.purchaseErrorListener.
5. Subscribes to AppState "change". On foreground it re-fetches entitlements and flushes the retry queue.

On unmount it removes listeners, clears any pending flush timer, and calls ExpoIap.endConnection() on iOS.

Hooks

useBiltIAP()

Returns BiltIapState & BiltIapApi. Must be called inside a BiltIapProvider — otherwise it throws useBiltIAP must be used inside <BiltIapProvider>.

State:

API methods:

useEntitlement(code)

Convenience hook for simple gate UIs.

const pro = useEntitlement('pro');

if (pro.loading) return <Spinner />;
if (pro.active) return <ProFeatures />;
return <Paywall />;

Returns:

Entitlements

type EntitlementStatus =
  | 'active'
  | 'grace_period'
  | 'billing_retry'
  | 'expired'
  | 'revoked'
  | 'refunded'
  | 'purchased';

type BiltEntitlement = {
  active: boolean;
  status: EntitlementStatus;
  platform: 'IOS' | 'Android';
  productId?: string;
  currentPlanId?: string;
  expirationDate?: number;   // epoch ms
  isAutoRenewing?: boolean;
  gracePeriod?: boolean;
  billingRetry?: boolean;
  updatedAt?: number;        // epoch ms
};

type EntitlementMap = Record<string, BiltEntitlement>;

Entitlements are always authored by the backend. The client never derives entitlement state from a local purchase — it only forwards receipts and re-reads the map.

Products

type StoreProduct = {
  productId: string;
  title: string;
  description: string;
  displayPrice: string;      // localized, e.g. "$4.99"
  price: number;             // numeric price in `currency`
  currency: string;
  type: 'subscription' | 'one-time';
};

type is inferred from expo-iap's typeIOS: auto-renewable-subscription and non-renewing-subscription are treated as 'subscription', everything else as 'one-time'. purchaseProduct uses this to pick between type: 'subs' and type: 'in-app' when calling ExpoIap.requestPurchase.

Error handling (BiltIapError)

Every error surfaced by the provider is an instance of BiltIapError.

class BiltIapError extends Error {
  readonly code: BiltIapErrorCode;
  readonly retryable: boolean;
  readonly requestId?: string;
}

Codes:

Only refreshEntitlements swallows its own errors (into lastError / onError). purchaseProduct and restorePurchases both swallow to onError and also rethrow so callers can surface per-action UI.

Offline retry queue

Ingest calls (POST /v1/iap/purchases/ingest) are critical — they turn a real StoreKit receipt into an entitlement. If one fails with a retryable: true error, the payload is enqueued in RetryQueue and persisted to AsyncStorage under the key @biltme/iap:retry-queue.

Retry behavior:

• Exponential backoff: min(2s * 2^attempts, 5min) with 50–100% jitter.
• Up to 8 attempts per payload. After that the item is dropped (dead letter) rather than poisoning the queue.
• Flushed on: enqueue, app foreground, and when flushRetryQueue() is called explicitly.
• Non-retryable errors (invalid-request, ownership-mismatch, etc.) drop the item immediately instead of retrying.

The queue count is exposed through pendingRetries so the UI can show a banner like:

{pendingRetries > 0 && (
  <Text>{pendingRetries} pending retries in queue</Text>
)}

Lifecycle behavior

• purchase-updated listener: ingests the receipt, then calls ExpoIap.finishTransaction({purchase}) only if the backend returns finishTransaction: true. Pending (ask-to-buy) purchases are ignored until they resolve — the user does not get access yet.
• purchase-error listener: user-cancelled is silently dropped; all other codes surface via onError.
• Foreground refresh: when AppState flips to "active" and the provider has initialized, it re-fetches entitlements and flushes the retry queue. This is how server-side lifecycle events (renew, expire, refund) reach the client without an explicit pull.
• Restore: calls ExpoIap.restorePurchases() first (so the native receipt refresh happens), then ExpoIap.getAvailablePurchases with onlyIncludeActiveItemsIOS: true, re-ingests each unique transaction, then hits /v1/iap/restore to let the backend reconcile.

Backend endpoints used

All requests are JSON and carry these headers:

• Content-Type: application/json
• X-Bilt-Tenant-App-Id: <config.tenantAppId>
• Authorization: Bearer <await config.getAccessToken()>

The backend uses the bearer token to authenticate the caller and derive the stable appUserId. tenantAppId is tenant routing only.

Responses follow the shape { ok: true, data: T } on success and { ok: false, error: { code, message, retryable?, requestId? } } on failure. The client reads retryable from the body when present and falls back to "HTTP 5xx => retryable" otherwise.

Metro / workspace resolution

When consuming @biltme/iap from a local workspace path inside an Expo app, Metro must resolve react, react-native, and the native peers from the host app's node_modules, not from packages/iap/node_modules. Otherwise you will see:

• Invalid hook call
• Cannot read property 'useRef' of null

See testapp/metro.config.js for a working config.

Testapp reference

The testapp workspace exercises every public API of this package:

• testapp/App.tsx — how to mount BiltIapProvider and wire onError.
• testapp/src/BillingScreen.tsx — full usage of useBiltIAP, useEntitlement, purchaseProduct, restorePurchases, refreshEntitlements, openManageSubscriptions, and pendingRetries.
• testapp/README.md — four end-to-end scenarios (smoke test, synthetic purchases, local StoreKit, ASC sandbox on device).