@onramper/onramper-react-native 1.2.2 → 1.3.0

package/nitrogen/generated/shared/c++/views/HybridOnramperCheckoutButtonComponent.cpp

@@ -36,6 +36,16 @@ namespace margelo::nitro::onramper::views {
         throw std::runtime_error(std::string("OnramperCheckoutButton.intentHandle: ") + exc.what());
       }
     }()),
+    onContentHeightChange([&]() -> CachedProp<std::optional<std::function<void(double /* height */)>>> {
+      try {
+        const react::RawValue* rawValue = rawProps.at("onContentHeightChange", nullptr, nullptr);
+        if (rawValue == nullptr) return sourceProps.onContentHeightChange;
+        const auto& [runtime, value] = (std::pair<jsi::Runtime*, jsi::Value>)*rawValue;
+        return CachedProp<std::optional<std::function<void(double /* height */)>>>::fromRawValue(*runtime, value.asObject(*runtime).getProperty(*runtime, PropNameIDCache::get(*runtime, "f")), sourceProps.onContentHeightChange);
+      } catch (const std::exception& exc) {
+        throw std::runtime_error(std::string("OnramperCheckoutButton.onContentHeightChange: ") + exc.what());
+      }
+    }()),
     hybridRef([&]() -> CachedProp<std::optional<std::function<void(const std::shared_ptr<HybridOnramperCheckoutButtonSpec>& /* ref */)>>> {
       try {
         const react::RawValue* rawValue = rawProps.at("hybridRef", nullptr, nullptr);
@@ -50,6 +60,7 @@ namespace margelo::nitro::onramper::views {
   bool HybridOnramperCheckoutButtonProps::filterObjectKeys(const std::string& propName) {
     switch (hashString(propName)) {
       case hashString("intentHandle"): return true;
+      case hashString("onContentHeightChange"): return true;
       case hashString("hybridRef"): return true;
       default: return false;
     }

package/nitrogen/generated/shared/c++/views/HybridOnramperCheckoutButtonComponent.hpp

@@ -17,10 +17,10 @@
 #include <react/renderer/components/view/ViewProps.h>
 
 #include <string>
-#include <memory>
-#include "HybridOnramperCheckoutButtonSpec.hpp"
 #include <functional>
 #include <optional>
+#include <memory>
+#include "HybridOnramperCheckoutButtonSpec.hpp"
 
 namespace margelo::nitro::onramper::views {
 
@@ -43,6 +43,7 @@ namespace margelo::nitro::onramper::views {
 
   public:
     CachedProp<std::string> intentHandle;
+    CachedProp<std::optional<std::function<void(double /* height */)>>> onContentHeightChange;
     CachedProp<std::optional<std::function<void(const std::shared_ptr<HybridOnramperCheckoutButtonSpec>& /* ref */)>>> hybridRef;
 
   private:

package/nitrogen/generated/shared/json/OnramperCheckoutButtonConfig.json

@@ -5,6 +5,7 @@
   "directEventTypes": {},
   "validAttributes": {
     "intentHandle": true,
+    "onContentHeightChange": true,
     "hybridRef": true
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onramper/onramper-react-native",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "React Native wrapper for the Onramper iOS SDK",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
@@ -41,6 +41,7 @@
     "lint": "biome check src",
     "format": "biome format --write src",
     "test": "jest",
+    "test:native": "bash scripts/test-native.sh",
     "typecheck": "tsc --noEmit",
     "nitrogen": "nitrogen && node scripts/sync-view-config.js",
     "prepare": "bob build",
@@ -64,7 +65,7 @@
   "license": "Apache-2.0",
   "homepage": "https://github.com/onramper/onramper-react-native#readme",
   "onramperSDK": {
-    "checksum": "754184c10a736e1db3292b592ca634ddbaa61dd01540b60610df4aa73a61de9a"
+    "checksum": "7611f869eab69109b317bb2b81e23c99f9d6f108bb6425ed2aace5cc4d5ad766"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
@@ -76,12 +77,14 @@
     "@expo/config-plugins": "^10.0.0",
     "@types/jest": "^29.5.14",
     "@types/react": "~19.2.0",
+    "@types/react-test-renderer": "^19.3.0",
     "jest": "^29.7.0",
     "nitrogen": "^0.35.9",
     "react": "19.2.3",
     "react-native": "0.85.3",
     "react-native-builder-bob": "^0.43.0",
     "react-native-nitro-modules": "^0.35.9",
+    "react-test-renderer": "^19.2.3",
     "ts-jest": "^29.4.10",
     "typescript": "~5.8.3"
   },

package/src/CheckoutButton.ts

@@ -0,0 +1,28 @@
+import { createElement, useMemo, useState } from 'react';
+import { callback } from 'react-native-nitro-modules';
+
+import { OnramperCheckoutButtonView } from './OnramperCheckoutButtonView';
+
+// Height of the bare Buy button. Used until native reports the measured content
+// height so the first frame isn't collapsed.
+export const CHECKOUT_BUTTON_FALLBACK_HEIGHT = 56;
+
+export interface CheckoutButtonProps {
+  intentHandle: string;
+}
+
+/**
+ * Sizes the native checkout button to its SwiftUI content. The content grows when
+ * the SDK shows ToS text under the Buy button (which can change after mount), and
+ * Yoga can't measure a SwiftUI view — so native reports the height and it is
+ * applied here as an explicit `height`.
+ */
+export function CheckoutButton({ intentHandle }: CheckoutButtonProps) {
+  const [height, setHeight] = useState<number | null>(null);
+  const onContentHeightChange = useMemo(() => callback((h: number) => setHeight(Math.ceil(h))), []);
+  return createElement(OnramperCheckoutButtonView, {
+    intentHandle,
+    onContentHeightChange,
+    style: { width: '100%', height: height ?? CHECKOUT_BUTTON_FALLBACK_HEIGHT },
+  });
+}

package/src/OnramperClient.ts

@@ -1,6 +1,6 @@
 import { type ReactElement, createElement } from 'react';
 
-import { OnramperCheckoutButtonView } from './OnramperCheckoutButtonView';
+import { CheckoutButton } from './CheckoutButton';
 import { createOnramperNative } from './OnramperNative';
 import { OnramperError } from './errors';
 import type { CheckoutEvent, EventName, EventPayload } from './events';
@@ -8,6 +8,7 @@ import type {
   CheckoutButtonStyle,
   CheckoutRequest,
   OnramperConfiguration,
+  OnramperLogRecord,
   OnramperState,
   OnramperUserPrefill,
   QuoteResponse,
@@ -42,10 +43,24 @@ export class OnramperClient {
   // Resolved when the constructor-issued configure() completes. Public methods
   // that need the native client await this first.
   private readonly configured: Promise<void>;
+  private destroyed = false;
 
   constructor(config: OnramperConfiguration) {
+    if (config.logHandler) {
+      const handler = config.logHandler;
+      this.native.setLogListener((json) => {
+        if (this.destroyed) return;
+        try {
+          handler(JSON.parse(json) as OnramperLogRecord);
+        } catch {
+          // Diagnostics must never interrupt checkout; do not log callback data.
+          console.warn('Onramper logHandler failed.');
+        }
+      });
+    }
     // Single native state callback → update the mirror + fan out to listeners.
     this.native.setStateListener((json) => {
+      if (this.destroyed) return;
       const s = JSON.parse(json) as OnramperState;
       this.state = s;
       if (s.kind === 'failed') this.lastError = OnramperError.from(s.error);
@@ -55,6 +70,7 @@ export class OnramperClient {
     // Single native checkout-event callback → keep the transaction ID mirror
     // synchronized at finalization, then fan out to checkout listeners.
     this.native.setEventListener((json) => {
+      if (this.destroyed) return;
       const e = JSON.parse(json) as CheckoutEvent;
       if (e.type === 'checkoutFinalized') {
         this.updateCurrentTransactionId(e.response.onramperTransactionId);
@@ -63,6 +79,7 @@ export class OnramperClient {
     });
 
     this.native.setTransactionIdListener((transactionId) => {
+      if (this.destroyed) return;
       // The SDK transiently publishes nil while re-preparing after the payment
       // sheet is dismissed. The finalized transaction ID remains durable across
       // that attempt change; only explicit reset()/signOut() clear the JS mirror.
@@ -73,7 +90,9 @@ export class OnramperClient {
     // Nitro stores the async callback natively and awaits it directly — no
     // event round-trip needed.
     this.native.setSessionExpirationHandler(async () => {
+      this.assertActive();
       const creds = await config.onSessionExpired();
+      this.assertActive();
       return { sessionId: creds.sessionId, sessionToken: creds.sessionToken };
     });
 
@@ -84,10 +103,12 @@ export class OnramperClient {
         environment: config.environment,
         theme: config.theme ?? 'system',
         logLevel: config.logLevel ?? 'off',
+        isEventLoggingEnabled: config.isEventLoggingEnabled ?? false,
+        isEventConsoleLoggingEnabled: config.isEventConsoleLoggingEnabled ?? false,
       })
       .catch((e: unknown) => {
         const err = OnramperError.from(e);
-        this.lastError = err;
+        if (!this.destroyed) this.lastError = err;
         throw err;
       });
     // Swallow the unhandled-rejection warning when no one awaits .configured
@@ -95,11 +116,23 @@ export class OnramperClient {
     this.configured.catch(() => undefined);
   }
 
+  private assertActive(): void {
+    if (this.destroyed) {
+      throw new OnramperError({
+        code: 'clientDestroyed',
+        message: 'This OnramperClient has been destroyed. Create a new client before making SDK calls.',
+        userMessage: 'This checkout session has ended. Please reopen checkout.',
+      });
+    }
+  }
+
   private updateCurrentTransactionId(next: string | null): void {
+    if (this.destroyed) return;
     if (next === this.currentTransactionId) return;
 
     this.currentTransactionId = next;
     for (const fn of [...this.transactionIdListeners]) {
+      if (this.destroyed) break;
       try {
         fn(next);
       } catch (error: unknown) {
@@ -110,19 +143,27 @@ export class OnramperClient {
 
   async initialize(creds: SessionCredentials): Promise<void> {
     try {
+      this.assertActive();
       await this.configured;
+      this.assertActive();
       await this.native.initialize(creds.sessionId, creds.sessionToken);
+      this.assertActive();
     } catch (e: unknown) {
+      this.assertActive();
       throw OnramperError.from(e);
     }
   }
 
   async reset(): Promise<void> {
     try {
+      this.assertActive();
       await this.configured;
+      this.assertActive();
       await this.native.reset();
+      this.assertActive();
       this.updateCurrentTransactionId(null);
     } catch (e: unknown) {
+      this.assertActive();
       throw OnramperError.from(e);
     }
   }
@@ -135,10 +176,14 @@ export class OnramperClient {
    */
   async signOut(): Promise<void> {
     try {
+      this.assertActive();
       await this.configured;
+      this.assertActive();
       await this.native.signOut();
+      this.assertActive();
       this.updateCurrentTransactionId(null);
     } catch (e: unknown) {
+      this.assertActive();
       throw OnramperError.from(e);
     }
   }
@@ -147,6 +192,8 @@ export class OnramperClient {
    * Fetches checkout requirements + quote and returns a native checkout button
    * to render plus the quote. The button handles login / finalize / webview
    * internally; outcomes surface via the event stream (`addEventListener`).
+   * A newer preparation, reset, or sign-out invalidates older unmounted buttons
+   * and rejects obsolete in-flight preparations with `intentInvalidated`.
    *
    * Pass `prefill` to pre-populate the OnramperID sign-in and additional-info
    * screens with values you already know about the user. It is best-effort and
@@ -164,30 +211,39 @@ export class OnramperClient {
     prefill: OnramperUserPrefill = {},
   ): Promise<GetCheckoutRequirementsResult> {
     try {
+      this.assertActive();
       await this.configured;
+      this.assertActive();
       const result = await this.native.getCheckoutRequirements(
         JSON.stringify(request),
         JSON.stringify(prefill),
         JSON.stringify(buttonStyle),
       );
+      this.assertActive();
       const quote = JSON.parse(result.quoteJson) as QuoteResponse;
-      const button = createElement(OnramperCheckoutButtonView, {
-        intentHandle: result.intentHandle,
-        style: { width: '100%', minHeight: 56 },
-      });
+      const button = createElement(CheckoutButton, { intentHandle: result.intentHandle });
       return { button, quote };
     } catch (e: unknown) {
+      this.assertActive();
       throw OnramperError.from(e);
     }
   }
 
   /** Discards a prepared intent (e.g. if the user navigates away before checkout). */
-  cancelPreparedIntent(intentHandle: string): Promise<void> {
-    return this.native.cancelPreparedIntent(intentHandle);
+  async cancelPreparedIntent(intentHandle: string): Promise<void> {
+    try {
+      this.assertActive();
+      await this.native.cancelPreparedIntent(intentHandle);
+      this.assertActive();
+    } catch (e: unknown) {
+      this.assertActive();
+      throw OnramperError.from(e);
+    }
   }
 
   /** Subscribe to state changes. Returns an unsubscribe function. */
   addStateListener(fn: (state: OnramperState) => void): () => void {
+    this.assertActive();
     this.stateListeners.add(fn);
     return () => {
       this.stateListeners.delete(fn);
@@ -196,6 +252,7 @@ export class OnramperClient {
 
   /** Subscribe to the durable Onramper transaction ID. Successful reset/signOut publish null. */
   addTransactionIdListener(fn: (transactionId: string | null) => void): () => void {
+    this.assertActive();
     this.transactionIdListeners.add(fn);
     return () => {
       this.transactionIdListeners.delete(fn);
@@ -204,6 +261,7 @@ export class OnramperClient {
 
   /** Subscribe to a specific checkout event. Returns an unsubscribe function. */
   addEventListener<K extends EventName>(name: K, fn: (e: EventPayload<K>) => void): () => void {
+    this.assertActive();
     const wrapper = (e: CheckoutEvent) => {
       if (e.type === name) fn(e as EventPayload<K>);
     };
@@ -213,8 +271,10 @@ export class OnramperClient {
     };
   }
 
-  /** Tear down: clears JS listeners and releases the native callbacks + SDK client. */
+  /** Idempotent teardown. Further operations reject with `clientDestroyed`; create a new client to restart. */
   destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
     this.stateListeners.clear();
     this.eventListeners.clear();
     this.transactionIdListeners.clear();

package/src/errors.ts

@@ -8,6 +8,9 @@ export type OnramperErrorCode =
   | 'networkError'
   | 'decodingError'
   | 'timeout'
+  | 'paymentFailed'
+  | 'providerFailed'
+  | 'applePayNotConfigured'
   | 'requirementNotSatisfied'
   | 'amountOutOfRange'
   | 'oidcFlowCancelled'
@@ -26,42 +29,62 @@ export type OnramperErrorCode =
   | 'deviceBlocked'
   | 'securityStorageFailed'
   | 'securityTrustFailed'
-  // JS-only codes
+  // Wrapper lifecycle and platform codes
   | 'platformUnsupported'
   | 'intentInvalidated'
   | 'intentAlreadyConsumed'
   | 'clientAlreadyConfigured'
+  | 'clientDestroyed'
   | 'sessionExpirationHandlerFailed';
 
 export interface OnramperErrorPayload {
   code: OnramperErrorCode;
   message: string;
+  /** Customer-facing SDK copy; optional for backwards-compatible payload construction. */
+  userMessage?: string;
+  supportCode?: string;
   info?: Record<string, unknown>;
 }
 
 export class OnramperError extends Error implements OnramperErrorPayload {
   readonly code: OnramperErrorCode;
+  readonly userMessage: string;
+  readonly supportCode: string;
   readonly info?: Record<string, unknown>;
 
   constructor(payload: OnramperErrorPayload) {
     super(payload.message);
     this.name = 'OnramperError';
     this.code = payload.code;
+    this.userMessage = payload.userMessage ?? 'Something went wrong. Please try again.';
+    this.supportCode = payload.supportCode ?? payload.code;
     this.info = payload.info;
   }
 
   static from(value: unknown): OnramperError {
     if (value instanceof OnramperError) return value;
+    // Nitro transports Swift exceptions as message-only JS Errors. Our native
+    // bridge encodes SDK errors explicitly so Promise rejections retain the
+    // same fields as failed events, without consulting unrelated client state.
+    const message = value instanceof Error ? value.message : typeof value === 'string' ? value : undefined;
+    if (message?.startsWith('ONRAMPER_ERROR:')) {
+      try {
+        const payload = JSON.parse(message.slice('ONRAMPER_ERROR:'.length));
+        if (payload && typeof payload.code === 'string' && typeof payload.message === 'string') {
+          return OnramperError.from(payload);
+        }
+      } catch {
+        // A malformed/non-SDK error falls back to the ordinary error path.
+      }
+    }
     if (value && typeof value === 'object') {
-      // Structured errors (from the `.failed` state) arrive as a plain
-      // `{ code, message, info? }` object. Thrown promise rejections surface
-      // as a JS Error with just a message; we default the code in that case
-      // (the structured error is also available on `client.state` / lastError).
-      const v = value as { code?: string; message?: string; info?: Record<string, unknown> };
+      const v = value as Partial<OnramperErrorPayload>;
       return new OnramperError({
         code: (v.code ?? 'unrecoverable') as OnramperErrorCode,
         message: v.message ?? 'Unknown error',
         info: v.info,
+        userMessage: typeof v.userMessage === 'string' ? v.userMessage : undefined,
+        supportCode: typeof v.supportCode === 'string' ? v.supportCode : undefined,
       });
     }
     return new OnramperError({ code: 'unrecoverable', message: String(value) });

package/src/events.ts

@@ -16,6 +16,11 @@ export type CheckoutEvent =
   | { type: 'providerReady' }
   | { type: 'paymentAuthorized' }
   | { type: 'paymentProcessing' }
+  /** Accepted but not settled; use currentTransactionId to track the payment. */
+  | { type: 'paymentPending' }
+  | { type: 'challengeStarted' }
+  | { type: 'challengeCompleted' }
+  | { type: 'customerOnboardingRequired' }
   | { type: 'paymentCancelled' }
   | { type: 'providerError'; reason: string };
 

package/src/generated/OnramperCheckoutButtonConfig.json

@@ -5,6 +5,7 @@
   "directEventTypes": {},
   "validAttributes": {
     "intentHandle": true,
+    "onContentHeightChange": true,
     "hybridRef": true
   }
 }

package/src/index.ts

@@ -16,6 +16,9 @@ export type {
   OnramperConfiguration,
   OnramperEnvironment,
   OnramperLogLevel,
+  OnramperLogRecord,
+  ProviderJSONValue,
+  PaymentDisclosure,
   OnramperState,
   OnramperTheme,
   OnramperUserPrefill,

package/src/specs/OnramperCheckoutButton.nitro.ts

@@ -5,6 +5,12 @@ import type { HybridView, HybridViewMethods, HybridViewProps } from 'react-nativ
 // UIHostingController. iOS-only (Android is a platformUnsupported stub).
 export interface OnramperCheckoutButtonProps extends HybridViewProps {
   intentHandle: string;
+  /**
+   * Called with the hosted SwiftUI content's height (points) whenever it changes —
+   * e.g. when ToS text appears under the Buy button. React Native can't measure
+   * the SwiftUI content itself, so the JS wrapper applies this as `height`.
+   */
+  onContentHeightChange?: (height: number) => void;
 }
 
 export interface OnramperCheckoutButtonMethods extends HybridViewMethods {}

package/src/specs/OnramperNitro.nitro.ts

@@ -8,6 +8,8 @@ export interface OnramperNitroConfig {
   environment: string; // 'development' | 'production'
   theme: string; // 'system' | 'light' | 'dark'
   logLevel: string; // 'off' | 'error' | 'info' | 'debug'
+  isEventLoggingEnabled: boolean;
+  isEventConsoleLoggingEnabled: boolean;
 }
 
 // Mirrors OnramperSDK.SessionCredentials. Named with a Nitro prefix to avoid a
@@ -50,6 +52,7 @@ export interface OnramperNitro extends HybridObject<{ ios: 'swift' }> {
   cancelPreparedIntent(intentHandle: string): Promise<void>;
 
   // Single native callback per stream; the JS wrapper fans out to multiple listeners.
+  setLogListener(onLog: (recordJson: string) => void): void;
   setStateListener(onState: (stateJson: string) => void): void;
   setEventListener(onEvent: (eventJson: string) => void): void;
   // Mirrors OnramperSDK.$currentTransactionId. `undefined` represents native nil.

package/src/types.ts

@@ -5,6 +5,16 @@ import type { OnramperErrorPayload } from './errors';
 
 export type OnramperEnvironment = 'development' | 'production';
 export type OnramperLogLevel = 'off' | 'error' | 'info' | 'debug';
+/** A sanitized native SDK diagnostic. Timestamp is Unix milliseconds. */
+export interface OnramperLogRecord {
+  timestamp: number;
+  level: OnramperLogLevel;
+  category: string;
+  event: string;
+  context: Record<string, string>;
+  message: string;
+}
+
 export type OnramperTheme = 'system' | 'light' | 'dark';
 
 export type TransactionType = 'buy' | 'sell';
@@ -20,12 +30,16 @@ export interface OnramperConfiguration {
   environment: OnramperEnvironment;
   theme?: OnramperTheme;
   logLevel?: OnramperLogLevel;
+  /** Receives native records in JS; system Console output is preserved. Off unless logLevel enables it. */
+  logHandler?: (record: OnramperLogRecord) => void;
+  /** Opt-in provider-event telemetry to the BFF. Defaults to false. */
+  isEventLoggingEnabled?: boolean;
+  /** Emit provider events at info even when logLevel is lower. Defaults to false. */
+  isEventConsoleLoggingEnabled?: boolean;
   /**
    * Called by the SDK when the session token expires and needs to be re-issued.
    *
-   * May be synchronous or async — under the hood the bridge uses an event
-   * round-trip (`onSessionExpired` → `provideSessionCredentials`) so Promises
-   * are awaited normally. Throw or reject to signal that no fresh credentials
+   * May be synchronous or async; the Nitro bridge awaits the callback directly. Throw or reject to signal that no fresh credentials
    * are available; the SDK will surface `userTokenRefreshFailed`.
    */
   onSessionExpired: () => SessionCredentials | Promise<SessionCredentials>;
@@ -67,6 +81,23 @@ export interface QuoteResponse {
   networkFee: number;
   transactionFee: number;
   recommendations?: string[];
+  providerContext?: Record<string, ProviderJSONValue>;
+}
+
+/** JSON values used in provider-specific quote metadata (including booleans and limits). */
+export type ProviderJSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ProviderJSONValue[]
+  | { [key: string]: ProviderJSONValue };
+
+export interface PaymentDisclosure {
+  code: string;
+  version: string;
+  contentMarkdown: string;
+  contentHtml: string;
 }
 
 // Mirrors Swift `OnramperUserPrefill`. Values you already know about the user,
@@ -111,6 +142,7 @@ export interface HeadlessCheckoutData {
   checkoutPaymentType: CheckoutPaymentType;
   url: string;
   renderType: RenderType;
+  providerBootstrap?: { framesBaseUrl?: string };
 }
 
 export interface CheckoutFinalizeResponse {
@@ -181,6 +213,7 @@ export type OnramperState =
   | { kind: 'readyToCheckout' }
   | { kind: 'finalizing' }
   | { kind: 'rendering'; url: string; renderType: RenderType; paymentType: CheckoutPaymentType }
+  | { kind: 'paymentPending' }
   | { kind: 'completed' }
   | { kind: 'failed'; error: OnramperErrorPayload };