react-native-iap 15.1.0 → 15.2.1

package/plugin/build/withIAP.d.ts

@@ -34,7 +34,7 @@ type IapPluginProps = {
     /**
      * IAPKit API key for purchase verification.
      * This key will be added to AndroidManifest.xml (as meta-data) and Info.plist.
-     * Get your API key from https://iapkit.com
+     * Get your API key from https://kit.openiap.dev
      */
     iapkitApiKey?: string;
 };

package/plugin/src/withIAP.ts

@@ -363,7 +363,7 @@ type IapPluginProps = {
   /**
    * IAPKit API key for purchase verification.
    * This key will be added to AndroidManifest.xml (as meta-data) and Info.plist.
-   * Get your API key from https://iapkit.com
+   * Get your API key from https://kit.openiap.dev
    */
   iapkitApiKey?: string;
 };

package/src/hooks/useIAP.ts

@@ -25,6 +25,7 @@ import {
   showAlternativeBillingDialogAndroid,
   createAlternativeBillingTokenAndroid,
   userChoiceBillingListenerAndroid,
+  subscriptionBillingIssueListener,
   isStandardIOS,
 } from '../';
 
@@ -63,33 +64,178 @@ type UseIap = {
   availablePurchases: Purchase[];
   promotedProductIOS?: Product;
   activeSubscriptions: ActiveSubscription[];
+  /**
+   * Complete a purchase transaction. Call after server-side verification to remove it
+   * from the queue.
+   *
+   * @param args.purchase The `Purchase` to finalize.
+   * @param args.isConsumable `true` for consumables (consumes the token so the SKU can be
+   *   re-bought, e.g. coins); `false` (default) for non-consumables and subscriptions.
+   * @returns Promise that resolves once the platform finalizes the transaction.
+   * @throws When the platform finalize call fails.
+   *
+   * @example
+   * ```ts
+   * purchaseUpdatedListener(async (purchase) => {
+   *   if (await verifyOnServer(purchase)) {
+   *     await finishTransaction({ purchase, isConsumable: false });
+   *   }
+   * });
+   * ```
+   *
+   * @remarks **Critical:** Android purchases must be finalized within 3 days or Google
+   *   auto-refunds. iOS unfinished transactions replay on every app launch.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/finish-transaction}
+   */
   finishTransaction: (args: MutationFinishTransactionArgs) => Promise<void>;
+  /**
+   * List the user's unfinished purchases — non-consumables, active subscriptions, and any
+   * pending transactions not yet finished.
+   *
+   * @param options Optional `PurchaseOptions`.
+   *   - iOS: `alsoPublishToEventListenerIOS`, `onlyIncludeActiveItemsIOS`.
+   *   - Android: `includeSuspendedAndroid` (include subscriptions in a paused/grace state).
+   * @returns Promise that resolves when the request is dispatched; results land in the
+   *   hook's reactive `availablePurchases` state — read from there, don't expect a return value.
+   * @throws When the platform query fails.
+   *
+   * @example
+   * ```ts
+   * const { availablePurchases, getAvailablePurchases, finishTransaction } = useIAP();
+   *
+   * useEffect(() => {
+   *   void getAvailablePurchases();
+   * }, [getAvailablePurchases]);
+   *
+   * useEffect(() => {
+   *   for (const p of availablePurchases) {
+   *     void verifyOnServer(p).then((ok) => {
+   *       if (ok) finishTransaction({ purchase: p, isConsumable: false });
+   *     });
+   *   }
+   * }, [availablePurchases, finishTransaction]);
+   * ```
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/get-available-purchases}
+   */
   getAvailablePurchases: (options?: PurchaseOptions) => Promise<void>;
+  /**
+   * Retrieve products or subscriptions from the store by SKU.
+   *
+   * @param params `ProductRequest` — `skus` (string[]) and optional `type`
+   *   (`'in-app' | 'subs' | 'all'`, defaults to `'in-app'`).
+   * @returns Promise that resolves when the request is dispatched; results land in the
+   *   hook's reactive `products` / `subscriptions` state — read from there, don't expect a return value.
+   * @throws When the store rejects the request (empty `skus`, not connected,
+   *   network/store error). Unknown SKUs are simply omitted from the result, not thrown.
+   *
+   * @example
+   * ```ts
+   * const { products, fetchProducts } = useIAP();
+   *
+   * useEffect(() => {
+   *   void fetchProducts({
+   *     skus: ['com.app.coins_100', 'com.app.premium'],
+   *     type: 'in-app',
+   *   });
+   * }, [fetchProducts]);
+   *
+   * // Render `products` directly from hook state.
+   * ```
+   *
+   * @remarks This is a regular promise-based call. Don't confuse with `request*` APIs
+   *   (`requestPurchase`), which are event-based.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/fetch-products}
+   */
   fetchProducts: (params: {
     skus: string[];
     type?: ProductQueryType | null;
   }) => Promise<void>;
+  /**
+   * Initiate a purchase or subscription flow. The result is delivered through
+   * `purchaseUpdatedListener` — NOT the return value.
+   *
+   * @param props `RequestPurchaseProps`, discriminated by `type`:
+   *   - `type: 'in-app'` — pass `request.apple.sku` (iOS) and/or `request.google.skus` (Android).
+   *   - `type: 'subs'`  — same shape, plus `request.google.subscriptionOffers: [{ sku, offerToken }]`.
+   * @returns Promise that resolves when the request is dispatched; results land in the
+   *   hook's `onPurchaseSuccess` / `onPurchaseError` callbacks.
+   * @throws Synchronous rejection from the store (e.g. `E_NOT_PREPARED`, validation failure).
+   *
+   * @example
+   * ```ts
+   * await requestPurchase({
+   *   request: {
+   *     apple: { sku: 'com.app.premium' },
+   *     google: { skus: ['com.app.premium'] },
+   *   },
+   *   type: 'in-app',
+   * });
+   * ```
+   *
+   * @remarks Event-based. Listen for the result via {@link purchaseUpdatedListener} /
+   *   {@link purchaseErrorListener}, or use `useIAP({ onPurchaseSuccess, onPurchaseError })`.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/request-purchase}
+   */
   requestPurchase: (params: RequestPurchaseProps) => Promise<void>;
   /**
    * @deprecated Use `verifyPurchase` instead. This function will be removed in a future version.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/validate-receipt}
    */
   validateReceipt: (
     options: VerifyPurchaseProps,
   ) => Promise<VerifyPurchaseResult>;
-  /** Verify purchase with the configured providers */
+  /**
+   * Verify a purchase against your own backend (returns isValid + raw store metadata).
+   *
+   * @see {@link https://www.openiap.dev/docs/features/validation#verify-purchase}
+   */
   verifyPurchase: (
     options: VerifyPurchaseProps,
   ) => Promise<VerifyPurchaseResult>;
-  /** Verify purchase with a specific provider (e.g., IAPKit) */
+  /**
+   * Verify via a managed provider — currently only `iapkit` (IAPKit). The PurchaseVerificationProvider enum exposes no other provider literal today.
+   *
+   * @see {@link https://www.openiap.dev/docs/features/validation#verify-purchase-with-provider}
+   */
   verifyPurchaseWithProvider: (
     options: VerifyPurchaseWithProviderProps,
   ) => Promise<VerifyPurchaseWithProviderResult>;
+  /**
+   * Restore non-consumable and active subscription purchases.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/restore-purchases}
+   */
   restorePurchases: (options?: PurchaseOptions) => Promise<void>;
+  /**
+   * Read the App Store-promoted product, if any.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/ios/get-promoted-product-ios}
+   */
   getPromotedProductIOS: () => Promise<Product | null>;
+  /**
+   * Buy the currently promoted product.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/ios/request-purchase-on-promoted-product-ios}
+   */
   requestPurchaseOnPromotedProductIOS: () => Promise<boolean>;
+  /**
+   * Get details of all currently active subscriptions.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/get-active-subscriptions}
+   */
   getActiveSubscriptions: (
     subscriptionIds?: string[],
   ) => Promise<ActiveSubscription[]>;
+  /**
+   * Check whether the user has any active subscription.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/has-active-subscriptions}
+   */
   hasActiveSubscriptions: (subscriptionIds?: string[]) => Promise<boolean>;
   /**
    * Manually retry the store connection.
@@ -98,8 +244,23 @@ type UseIap = {
    */
   reconnect: () => Promise<boolean>;
   // Alternative billing (Android)
+  /**
+   * Check whether alternative billing is available for the user.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/android/check-alternative-billing-availability-android}
+   */
   checkAlternativeBillingAvailabilityAndroid?: () => Promise<boolean>;
+  /**
+   * Display Google's alternative billing information dialog.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/android/show-alternative-billing-dialog-android}
+   */
   showAlternativeBillingDialogAndroid?: () => Promise<boolean>;
+  /**
+   * Create a reporting token for an alternative billing flow.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/android/create-alternative-billing-token-android}
+   */
   createAlternativeBillingTokenAndroid?: (
     sku?: string,
   ) => Promise<string | null>;
@@ -112,6 +273,16 @@ export interface UseIapOptions {
   onError?: (error: Error) => void;
   onPromotedProductIOS?: (product: Product) => void;
   onUserChoiceBillingAndroid?: (details: UserChoiceBillingDetails) => void;
+  /**
+   * Fires when an active subscription enters a billing-issue state
+   * (StoreKit 2 Message.billingIssue on iOS 18+, Purchase.isSuspended on
+   * Play Billing 8.1+). Not invoked on Meta Horizon.
+   *
+   * Recommended: call deepLinkToSubscriptions on the returned purchase so
+   * the user can update their payment method in the platform subscription
+   * center.
+   */
+  onSubscriptionBillingIssue?: (purchase: Purchase) => void;
   /**
    * @deprecated Use enableBillingProgramAndroid instead.
    * - 'user-choice' → 'user-choice-billing'
@@ -178,6 +349,7 @@ export function useIAP(options?: UseIapOptions): UseIap {
     purchaseError?: EventSubscription;
     promotedProductIOS?: EventSubscription;
     userChoiceBillingAndroid?: EventSubscription;
+    subscriptionBillingIssue?: EventSubscription;
   }>({});
 
   // Track if component is mounted to prevent listener leaks on early unmount
@@ -463,6 +635,15 @@ export function useIAP(options?: UseIapOptions): UseIap {
           }
         });
     }
+
+    // Always attach so callers that supply `onSubscriptionBillingIssue` later
+    // (after the hook has already set up listeners) still receive events.
+    if (!subscriptionsRef.current.subscriptionBillingIssue) {
+      subscriptionsRef.current.subscriptionBillingIssue =
+        subscriptionBillingIssueListener((purchase: Purchase) => {
+          optionsRef.current?.onSubscriptionBillingIssue?.(purchase);
+        });
+    }
   }, [getActiveSubscriptionsInternal, getAvailablePurchasesInternal]);
 
   // Shared helper: clean up all listeners
@@ -471,10 +652,12 @@ export function useIAP(options?: UseIapOptions): UseIap {
     subscriptionsRef.current.purchaseError?.remove();
     subscriptionsRef.current.promotedProductIOS?.remove();
     subscriptionsRef.current.userChoiceBillingAndroid?.remove();
+    subscriptionsRef.current.subscriptionBillingIssue?.remove();
     subscriptionsRef.current.purchaseUpdate = undefined;
     subscriptionsRef.current.purchaseError = undefined;
     subscriptionsRef.current.promotedProductIOS = undefined;
     subscriptionsRef.current.userChoiceBillingAndroid = undefined;
+    subscriptionsRef.current.subscriptionBillingIssue = undefined;
   }, []);
 
   const initIapWithSubscriptions = useCallback(async (): Promise<void> => {

package/src/hooks/useWebhookEvents.ts

@@ -0,0 +1,180 @@
+import {useEffect, useRef, useState} from 'react';
+
+import {
+  connectWebhookStream,
+  type WebhookEventPayload,
+  type WebhookEventStream,
+  type WebhookListener,
+  type WebhookListenerError,
+} from '../webhook-client';
+
+export type UseWebhookEventsOptions = {
+  /**
+   * kit project API key — same value used for receipt verification.
+   * Must be non-empty to start the stream; pass `null`/`undefined` to
+   * disable the listener (e.g. before the user is logged in).
+   */
+  apiKey: string | null | undefined;
+  /**
+   * Override the kit base URL. Defaults to https://kit.openiap.dev.
+   */
+  baseUrl?: string;
+  /**
+   * Optional EventSource factory. Required on React Native because RN
+   * does not ship a global EventSource — pass an instance from
+   * `react-native-sse` (or any compatible polyfill).
+   */
+  eventSourceFactory?: (
+    url: string,
+    headers: Record<string, string>,
+  ) => WebhookEventStream;
+  /**
+   * Maximum number of events to retain in the in-memory ring buffer
+   * surfaced as `events`. Older entries are discarded. Defaults to 50.
+   * Set 0 to opt out of the buffer entirely (consume only via
+   * `onEvent`).
+   */
+  bufferSize?: number;
+  /**
+   * Called for every received event in addition to being appended to
+   * the buffer. Useful for side effects (toast, analytics, granting
+   * entitlement). Called with the latest stable callback identity.
+   */
+  onEvent?: (event: WebhookEventPayload) => void;
+  /**
+   * Called when the stream surfaces a transport / parse error.
+   * EventSource auto-reconnects regardless of this hook — this is
+   * primarily for telemetry + UI surfacing.
+   */
+  onError?: (error: WebhookListenerError) => void;
+};
+
+export type UseWebhookEventsResult = {
+  /** Most recent N events (most-recent-first). Capped at bufferSize. */
+  events: WebhookEventPayload[];
+  /** Last error reported by the underlying stream. Null when healthy. */
+  lastError: WebhookListenerError | null;
+  /**
+   * True once the first webhook event has been received from the
+   * stream. Remains false if the connection is open but idle (the
+   * underlying SSE bridge doesn't surface a "stream opened"
+   * lifecycle event we can hook into; isConnected is therefore an
+   * activity indicator, not a raw socket-state flag). Reset to
+   * false on cleanup / apiKey change.
+   */
+  isConnected: boolean;
+};
+
+// React hook wrapping the SSE webhook stream. Lifecycle:
+//   - opens on mount (once `apiKey` is non-empty),
+//   - closes on unmount,
+//   - reconnects automatically when EventSource raises a transport
+//     error (the underlying client auto-reconnects via the EventSource
+//     spec; this hook just surfaces the error and re-renders).
+//
+// Why a hook: openiap's UX guidance is that consumers consume webhook
+// events from React state (granting entitlement, refreshing the
+// subscription view) rather than via an imperative listener. The
+// hook's `events` buffer + `onEvent` callback cover both styles.
+export function useWebhookEvents({
+  apiKey,
+  baseUrl,
+  eventSourceFactory,
+  bufferSize = 50,
+  onEvent,
+  onError,
+}: UseWebhookEventsOptions): UseWebhookEventsResult {
+  const [events, setEvents] = useState<WebhookEventPayload[]>([]);
+  const [lastError, setLastError] = useState<WebhookListenerError | null>(null);
+  const [isConnected, setIsConnected] = useState(false);
+
+  // Stash callbacks in refs so reconnects don't fire on every render.
+  // The underlying SSE connection should only restart when `apiKey` /
+  // `baseUrl` change. `eventSourceFactory` is held in a ref too so
+  // anonymous-function callers don't tear down the connection every
+  // render (a common React pitfall — was previously documented as a
+  // caller-side constraint, now enforced by the hook). `bufferSize`
+  // is also a ref so adjusting the buffer cap from the host component
+  // doesn't tear down the stream and lose in-flight events.
+  const onEventRef = useRef(onEvent);
+  const onErrorRef = useRef(onError);
+  const eventSourceFactoryRef = useRef(eventSourceFactory);
+  const bufferSizeRef = useRef(bufferSize);
+  onEventRef.current = onEvent;
+  onErrorRef.current = onError;
+  eventSourceFactoryRef.current = eventSourceFactory;
+  bufferSizeRef.current = bufferSize;
+
+  // Trim the visible buffer immediately when bufferSize is lowered
+  // mid-stream. The ref-based update would otherwise only take
+  // effect on the next event.
+  useEffect(() => {
+    setEvents((prev) => (bufferSize > 0 ? prev.slice(0, bufferSize) : []));
+  }, [bufferSize]);
+
+  useEffect(() => {
+    // Fresh stream → fresh state. Resetting events + lastError on
+    // (re)connect prevents a stale payload from the previous
+    // apiKey/baseUrl from briefly leaking into the new context.
+    setEvents([]);
+    setLastError(null);
+
+    if (!apiKey) {
+      return;
+    }
+
+    let listener: WebhookListener | null = null;
+    let mounted = true;
+
+    try {
+      listener = connectWebhookStream({
+        apiKey,
+        baseUrl,
+        eventSourceFactory: eventSourceFactoryRef.current,
+        onEvent: (event) => {
+          if (!mounted) {
+            return;
+          }
+          setIsConnected(true);
+          const cap = bufferSizeRef.current;
+          if (cap > 0) {
+            setEvents((prev) => [event, ...prev].slice(0, cap));
+          }
+          onEventRef.current?.(event);
+        },
+        onError: (error) => {
+          if (!mounted) {
+            return;
+          }
+          setLastError(error);
+          onErrorRef.current?.(error);
+        },
+      });
+    } catch (error) {
+      const wrapped: WebhookListenerError = {
+        code: 'TRANSPORT_ERROR',
+        message:
+          error instanceof Error
+            ? error.message
+            : 'Failed to open webhook stream',
+        cause: error,
+      };
+      setLastError(wrapped);
+      onErrorRef.current?.(wrapped);
+    }
+
+    return () => {
+      mounted = false;
+      listener?.close();
+      setIsConnected(false);
+    };
+    // `eventSourceFactory` deliberately omitted from deps — held in a
+    // ref above so anonymous-function callers don't trigger reconnects
+    // on every render. The connection is only re-opened when apiKey or
+    // baseUrl changes; a runtime factory swap is picked up on that
+    // next reconnect via the ref.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [apiKey, baseUrl]);
+
+  return {events, lastError, isConnected};
+}