@onramper/onramper-react-native 1.2.2-1 → 1.3.0

package/nitrogen/generated/ios/swift/HybridOnramperNitroSpec_cxx.swift

@@ -84,7 +84,7 @@ open class HybridOnramperNitroSpec_cxx {
     }
   }
 
-  
+
 
   /**
    * Get the memory size of the Swift class (plus size of any other allocations)
@@ -121,7 +121,7 @@ open class HybridOnramperNitroSpec_cxx {
   }
 
   // Properties
-  
+
 
   // Methods
   @inline(__always)
@@ -142,7 +142,7 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_std__shared_ptr_Promise_void___(__exceptionPtr)
     }
   }
-  
+
   @inline(__always)
   public final func initialize(sessionId: std.string, sessionToken: std.string) -> bridge.Result_std__shared_ptr_Promise_void___ {
     do {
@@ -161,7 +161,7 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_std__shared_ptr_Promise_void___(__exceptionPtr)
     }
   }
-  
+
   @inline(__always)
   public final func reset() -> bridge.Result_std__shared_ptr_Promise_void___ {
     do {
@@ -180,7 +180,7 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_std__shared_ptr_Promise_void___(__exceptionPtr)
     }
   }
-  
+
   @inline(__always)
   public final func signOut() -> bridge.Result_std__shared_ptr_Promise_void___ {
     do {
@@ -199,7 +199,7 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_std__shared_ptr_Promise_void___(__exceptionPtr)
     }
   }
-  
+
   @inline(__always)
   public final func getCheckoutRequirements(requestJson: std.string, prefillJson: std.string, styleJson: std.string) -> bridge.Result_std__shared_ptr_Promise_PreparedIntentResult___ {
     do {
@@ -218,7 +218,7 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_std__shared_ptr_Promise_PreparedIntentResult___(__exceptionPtr)
     }
   }
-  
+
   @inline(__always)
   public final func cancelPreparedIntent(intentHandle: std.string) -> bridge.Result_std__shared_ptr_Promise_void___ {
     do {
@@ -237,7 +237,23 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_std__shared_ptr_Promise_void___(__exceptionPtr)
     }
   }
-  
+
+  @inline(__always)
+  public final func setLogListener(onLog: bridge.Func_void_std__string) -> bridge.Result_void_ {
+    do {
+      try self.__implementation.setLogListener(onLog: { () -> (String) -> Void in
+        let __wrappedFunction = bridge.wrap_Func_void_std__string(onLog)
+        return { (__recordJson: String) -> Void in
+          __wrappedFunction.call(std.string(__recordJson))
+        }
+      }())
+      return bridge.create_Result_void_()
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_void_(__exceptionPtr)
+    }
+  }
+
   @inline(__always)
   public final func setStateListener(onState: bridge.Func_void_std__string) -> bridge.Result_void_ {
     do {
@@ -253,7 +269,7 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_void_(__exceptionPtr)
     }
   }
-  
+
   @inline(__always)
   public final func setEventListener(onEvent: bridge.Func_void_std__string) -> bridge.Result_void_ {
     do {
@@ -269,7 +285,7 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_void_(__exceptionPtr)
     }
   }
-  
+
   @inline(__always)
   public final func setTransactionIdListener(onTransactionId: bridge.Func_void_std__optional_std__string_) -> bridge.Result_void_ {
     do {
@@ -291,7 +307,7 @@ open class HybridOnramperNitroSpec_cxx {
       return bridge.create_Result_void_(__exceptionPtr)
     }
   }
-  
+
   @inline(__always)
   public final func setSessionExpirationHandler(handler: bridge.Func_std__shared_ptr_Promise_std__shared_ptr_Promise_NitroSessionCredentials____) -> bridge.Result_void_ {
     do {

package/nitrogen/generated/ios/swift/OnramperNitroConfig.swift

@@ -18,32 +18,42 @@ public extension OnramperNitroConfig {
   /**
    * Create a new instance of `OnramperNitroConfig`.
    */
-  init(apiKey: String, clientId: String, environment: String, theme: String, logLevel: String) {
-    self.init(std.string(apiKey), std.string(clientId), std.string(environment), std.string(theme), std.string(logLevel))
+  init(apiKey: String, clientId: String, environment: String, theme: String, logLevel: String, isEventLoggingEnabled: Bool, isEventConsoleLoggingEnabled: Bool) {
+    self.init(std.string(apiKey), std.string(clientId), std.string(environment), std.string(theme), std.string(logLevel), isEventLoggingEnabled, isEventConsoleLoggingEnabled)
   }
 
   @inline(__always)
   var apiKey: String {
     return String(self.__apiKey)
   }
-  
+
   @inline(__always)
   var clientId: String {
     return String(self.__clientId)
   }
-  
+
   @inline(__always)
   var environment: String {
     return String(self.__environment)
   }
-  
+
   @inline(__always)
   var theme: String {
     return String(self.__theme)
   }
-  
+
   @inline(__always)
   var logLevel: String {
     return String(self.__logLevel)
   }
+
+  @inline(__always)
+  var isEventLoggingEnabled: Bool {
+    return self.__isEventLoggingEnabled
+  }
+
+  @inline(__always)
+  var isEventConsoleLoggingEnabled: Bool {
+    return self.__isEventConsoleLoggingEnabled
+  }
 }

package/nitrogen/generated/shared/c++/HybridOnramperNitroSpec.cpp

@@ -20,6 +20,7 @@ namespace margelo::nitro::onramper {
       prototype.registerHybridMethod("signOut", &HybridOnramperNitroSpec::signOut);
       prototype.registerHybridMethod("getCheckoutRequirements", &HybridOnramperNitroSpec::getCheckoutRequirements);
       prototype.registerHybridMethod("cancelPreparedIntent", &HybridOnramperNitroSpec::cancelPreparedIntent);
+      prototype.registerHybridMethod("setLogListener", &HybridOnramperNitroSpec::setLogListener);
       prototype.registerHybridMethod("setStateListener", &HybridOnramperNitroSpec::setStateListener);
       prototype.registerHybridMethod("setEventListener", &HybridOnramperNitroSpec::setEventListener);
       prototype.registerHybridMethod("setTransactionIdListener", &HybridOnramperNitroSpec::setTransactionIdListener);

package/nitrogen/generated/shared/c++/HybridOnramperNitroSpec.hpp

@@ -65,6 +65,7 @@ namespace margelo::nitro::onramper {
       virtual std::shared_ptr<Promise<void>> signOut() = 0;
       virtual std::shared_ptr<Promise<PreparedIntentResult>> getCheckoutRequirements(const std::string& requestJson, const std::string& prefillJson, const std::string& styleJson) = 0;
       virtual std::shared_ptr<Promise<void>> cancelPreparedIntent(const std::string& intentHandle) = 0;
+      virtual void setLogListener(const std::function<void(const std::string& /* recordJson */)>& onLog) = 0;
       virtual void setStateListener(const std::function<void(const std::string& /* stateJson */)>& onState) = 0;
       virtual void setEventListener(const std::function<void(const std::string& /* eventJson */)>& onEvent) = 0;
       virtual void setTransactionIdListener(const std::function<void(const std::optional<std::string>& /* transactionId */)>& onTransactionId) = 0;

package/nitrogen/generated/shared/c++/OnramperNitroConfig.hpp

@@ -44,10 +44,12 @@ namespace margelo::nitro::onramper {
     std::string environment     SWIFT_PRIVATE;
     std::string theme     SWIFT_PRIVATE;
     std::string logLevel     SWIFT_PRIVATE;
+    bool isEventLoggingEnabled     SWIFT_PRIVATE;
+    bool isEventConsoleLoggingEnabled     SWIFT_PRIVATE;
 
   public:
     OnramperNitroConfig() = default;
-    explicit OnramperNitroConfig(std::string apiKey, std::string clientId, std::string environment, std::string theme, std::string logLevel): apiKey(apiKey), clientId(clientId), environment(environment), theme(theme), logLevel(logLevel) {}
+    explicit OnramperNitroConfig(std::string apiKey, std::string clientId, std::string environment, std::string theme, std::string logLevel, bool isEventLoggingEnabled, bool isEventConsoleLoggingEnabled): apiKey(apiKey), clientId(clientId), environment(environment), theme(theme), logLevel(logLevel), isEventLoggingEnabled(isEventLoggingEnabled), isEventConsoleLoggingEnabled(isEventConsoleLoggingEnabled) {}
 
   public:
     friend bool operator==(const OnramperNitroConfig& lhs, const OnramperNitroConfig& rhs) = default;
@@ -67,7 +69,9 @@ namespace margelo::nitro {
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "clientId"))),
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "environment"))),
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "theme"))),
-        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "logLevel")))
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "logLevel"))),
+        JSIConverter<bool>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isEventLoggingEnabled"))),
+        JSIConverter<bool>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isEventConsoleLoggingEnabled")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::onramper::OnramperNitroConfig& arg) {
@@ -77,6 +81,8 @@ namespace margelo::nitro {
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "environment"), JSIConverter<std::string>::toJSI(runtime, arg.environment));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "theme"), JSIConverter<std::string>::toJSI(runtime, arg.theme));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "logLevel"), JSIConverter<std::string>::toJSI(runtime, arg.logLevel));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "isEventLoggingEnabled"), JSIConverter<bool>::toJSI(runtime, arg.isEventLoggingEnabled));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "isEventConsoleLoggingEnabled"), JSIConverter<bool>::toJSI(runtime, arg.isEventConsoleLoggingEnabled));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -92,6 +98,8 @@ namespace margelo::nitro {
       if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "environment")))) return false;
       if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "theme")))) return false;
       if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "logLevel")))) return false;
+      if (!JSIConverter<bool>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isEventLoggingEnabled")))) return false;
+      if (!JSIConverter<bool>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isEventConsoleLoggingEnabled")))) return false;
       return true;
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onramper/onramper-react-native",
-  "version": "1.2.2-1",
+  "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",

package/src/OnramperClient.ts

@@ -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,27 +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(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);
@@ -193,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);
@@ -201,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>);
     };
@@ -210,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/index.ts

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

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 };