@onramper/onramper-react-native 1.0.1

package/src/OnramperClient.ts

@@ -0,0 +1,170 @@
+import { type ReactElement, createElement } from 'react';
+
+import { OnramperCheckoutButtonView } from './OnramperCheckoutButtonView';
+import { createOnramperNative } from './OnramperNative';
+import { OnramperError } from './errors';
+import type { CheckoutEvent, EventName, EventPayload } from './events';
+import type {
+  CheckoutButtonStyle,
+  CheckoutRequest,
+  OnramperConfiguration,
+  OnramperState,
+  QuoteResponse,
+  SessionCredentials,
+} from './types';
+
+export interface GetCheckoutRequirementsResult {
+  /** A native checkout button element to render. Tapping it drives login, finalize, and the payment webview internally. */
+  button: ReactElement;
+  /** The quote (rate, fees, payout) returned with the checkout intent. */
+  quote: QuoteResponse;
+}
+
+/**
+ * Typed, public entry point to the Onramper SDK. Wraps the native Nitro hybrid
+ * object: state and checkout events arrive as JSON strings over single native
+ * callbacks and are parsed here into the typed `OnramperState` / `CheckoutEvent`
+ * unions, then fanned out to any number of listeners.
+ */
+export class OnramperClient {
+  state: OnramperState = { kind: 'idle' };
+  lastError: OnramperError | null = null;
+
+  // Each client owns its own native instance (and thus its own SDK client).
+  private readonly native = createOnramperNative();
+
+  private readonly stateListeners = new Set<(state: OnramperState) => void>();
+  private readonly eventListeners = new Set<(event: CheckoutEvent) => void>();
+
+  // Resolved when the constructor-issued configure() completes. Public methods
+  // that need the native client await this first.
+  private readonly configured: Promise<void>;
+
+  constructor(config: OnramperConfiguration) {
+    // Single native state callback → update the mirror + fan out to listeners.
+    this.native.setStateListener((json) => {
+      const s = JSON.parse(json) as OnramperState;
+      this.state = s;
+      if (s.kind === 'failed') this.lastError = OnramperError.from(s.error);
+      for (const fn of this.stateListeners) fn(s);
+    });
+
+    // Single native checkout-event callback → fan out to listeners.
+    this.native.setEventListener((json) => {
+      const e = JSON.parse(json) as CheckoutEvent;
+      for (const fn of this.eventListeners) fn(e);
+    });
+
+    // The SDK calls this when its session expires; return fresh credentials.
+    // Nitro stores the async callback natively and awaits it directly — no
+    // event round-trip needed.
+    this.native.setSessionExpirationHandler(async () => {
+      const creds = await config.onSessionExpired();
+      return { sessionId: creds.sessionId, sessionToken: creds.sessionToken };
+    });
+
+    this.configured = this.native
+      .configure({
+        apiKey: config.apiKey,
+        clientId: config.clientId,
+        environment: config.environment,
+        theme: config.theme ?? 'system',
+        logLevel: config.logLevel ?? 'off',
+      })
+      .catch((e: unknown) => {
+        const err = OnramperError.from(e);
+        this.lastError = err;
+        throw err;
+      });
+    // Swallow the unhandled-rejection warning when no one awaits .configured
+    // before calling initialize(). The error still surfaces via initialize().
+    this.configured.catch(() => undefined);
+  }
+
+  async initialize(creds: SessionCredentials): Promise<void> {
+    try {
+      await this.configured;
+      await this.native.initialize(creds.sessionId, creds.sessionToken);
+    } catch (e: unknown) {
+      throw OnramperError.from(e);
+    }
+  }
+
+  async reset(): Promise<void> {
+    try {
+      await this.configured;
+      await this.native.reset();
+    } catch (e: unknown) {
+      throw OnramperError.from(e);
+    }
+  }
+
+  /**
+   * Signs the OnramperID user out by clearing stored OIDC tokens. The next
+   * checkout that requires user_info will re-trigger the login flow. Also
+   * resets in-flight checkout state. Does NOT clear the partner-scoped SDK
+   * session — re-calling `initialize` is only needed if that session expired.
+   */
+  async signOut(): Promise<void> {
+    try {
+      await this.configured;
+      await this.native.signOut();
+    } catch (e: unknown) {
+      throw OnramperError.from(e);
+    }
+  }
+
+  /**
+   * 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`).
+   */
+  async getCheckoutRequirements(
+    request: CheckoutRequest,
+    buttonStyle: CheckoutButtonStyle = {},
+  ): Promise<GetCheckoutRequirementsResult> {
+    try {
+      await this.configured;
+      const result = await this.native.getCheckoutRequirements(JSON.stringify(request), JSON.stringify(buttonStyle));
+      const quote = JSON.parse(result.quoteJson) as QuoteResponse;
+      const button = createElement(OnramperCheckoutButtonView, {
+        intentHandle: result.intentHandle,
+        style: { width: '100%', minHeight: 56 },
+      });
+      return { button, quote };
+    } catch (e: unknown) {
+      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);
+  }
+
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  addStateListener(fn: (state: OnramperState) => void): () => void {
+    this.stateListeners.add(fn);
+    return () => {
+      this.stateListeners.delete(fn);
+    };
+  }
+
+  /** Subscribe to a specific checkout event. Returns an unsubscribe function. */
+  addEventListener<K extends EventName>(name: K, fn: (e: EventPayload<K>) => void): () => void {
+    const wrapper = (e: CheckoutEvent) => {
+      if (e.type === name) fn(e as EventPayload<K>);
+    };
+    this.eventListeners.add(wrapper);
+    return () => {
+      this.eventListeners.delete(wrapper);
+    };
+  }
+
+  /** Tear down: clears JS listeners and releases the native callbacks + SDK client. */
+  destroy(): void {
+    this.stateListeners.clear();
+    this.eventListeners.clear();
+    this.native.dispose();
+  }
+}

package/src/OnramperNative.ts

@@ -0,0 +1,19 @@
+import { Platform } from 'react-native';
+import { NitroModules } from 'react-native-nitro-modules';
+import type { OnramperNitro } from './specs/OnramperNitro.nitro';
+
+/**
+ * Creates a fresh native Onramper Nitro hybrid object. Each `OnramperClient`
+ * owns its own instance, so its listeners and the underlying SDK client are
+ * isolated per client and torn down by `destroy()` → `dispose()`.
+ */
+export function createOnramperNative(): OnramperNitro {
+  // iOS-only in this release. Fail with a clear message rather than the opaque
+  // "hybrid object not found" Nitro would throw on platforms without a native impl.
+  if (Platform.OS !== 'ios') {
+    throw new Error(`Onramper React Native is iOS-only in this release; it is not supported on ${Platform.OS}.`);
+  }
+  return NitroModules.createHybridObject<OnramperNitro>('OnramperNitro');
+}
+
+export type { OnramperNitro };

package/src/errors.ts

@@ -0,0 +1,69 @@
+export type OnramperErrorCode =
+  // Mirrors Sources/OnramperSDK/Errors/OnramperError.swift cases
+  | 'notInitialized'
+  | 'initializationFailed'
+  | 'attestationFailed'
+  | 'invalidStateTransition'
+  | 'invalidState'
+  | 'networkError'
+  | 'decodingError'
+  | 'timeout'
+  | 'requirementNotSatisfied'
+  | 'amountOutOfRange'
+  | 'oidcFlowCancelled'
+  | 'oidcTokenExchangeFailed'
+  | 'oidcFlowFailed'
+  | 'userTokenInvalid'
+  | 'userTokenRefreshFailed'
+  | 'webviewLoadFailed'
+  | 'deepLinkFailed'
+  | 'invalidRequest'
+  | 'quoteUnavailable'
+  | 'checkoutForbidden'
+  | 'temporaryFailure'
+  | 'unrecoverable'
+  | 'configurationError'
+  | 'deviceBlocked'
+  | 'securityStorageFailed'
+  | 'securityTrustFailed'
+  // JS-only codes
+  | 'platformUnsupported'
+  | 'intentInvalidated'
+  | 'intentAlreadyConsumed'
+  | 'clientAlreadyConfigured'
+  | 'sessionExpirationHandlerFailed';
+
+export interface OnramperErrorPayload {
+  code: OnramperErrorCode;
+  message: string;
+  info?: Record<string, unknown>;
+}
+
+export class OnramperError extends Error implements OnramperErrorPayload {
+  readonly code: OnramperErrorCode;
+  readonly info?: Record<string, unknown>;
+
+  constructor(payload: OnramperErrorPayload) {
+    super(payload.message);
+    this.name = 'OnramperError';
+    this.code = payload.code;
+    this.info = payload.info;
+  }
+
+  static from(value: unknown): OnramperError {
+    if (value instanceof OnramperError) return value;
+    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> };
+      return new OnramperError({
+        code: (v.code ?? 'unrecoverable') as OnramperErrorCode,
+        message: v.message ?? 'Unknown error',
+        info: v.info,
+      });
+    }
+    return new OnramperError({ code: 'unrecoverable', message: String(value) });
+  }
+}

package/src/events.ts

@@ -0,0 +1,23 @@
+import type { OnramperErrorPayload } from './errors';
+import type { CheckoutFinalizeResponse, CheckoutRequirement, OnramperState, RenderType } from './types';
+
+export type CheckoutEvent =
+  | { type: 'stateChanged'; state: OnramperState }
+  | { type: 'checkoutStarted'; intentId: string }
+  | { type: 'loginRequired'; requirements: CheckoutRequirement[] }
+  | { type: 'readyToCheckout' }
+  | { type: 'requirementSatisfied'; requirementType: string }
+  | { type: 'checkoutFinalized'; response: CheckoutFinalizeResponse }
+  | { type: 'renderingStarted'; url: string; renderType: RenderType }
+  | { type: 'completed'; checkoutId: string }
+  | { type: 'failed'; error: OnramperErrorPayload }
+  | { type: 'cancelled' }
+  // Provider-lifecycle events from third-party checkout webviews.
+  | { type: 'providerReady' }
+  | { type: 'paymentAuthorized' }
+  | { type: 'paymentProcessing' }
+  | { type: 'paymentCancelled' }
+  | { type: 'providerError'; reason: string };
+
+export type EventName = CheckoutEvent['type'];
+export type EventPayload<K extends EventName> = Extract<CheckoutEvent, { type: K }>;

package/src/generated/OnramperCheckoutButtonConfig.json

@@ -0,0 +1,10 @@
+{
+  "uiViewClassName": "OnramperCheckoutButton",
+  "supportsRawText": false,
+  "bubblingEventTypes": {},
+  "directEventTypes": {},
+  "validAttributes": {
+    "intentHandle": true,
+    "hybridRef": true
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// Public API re-exports.
+
+export { OnramperClient } from './OnramperClient';
+export type { GetCheckoutRequirementsResult } from './OnramperClient';
+export { OnramperCheckoutButtonView } from './OnramperCheckoutButtonView';
+export type { OnramperCheckoutButtonViewProps } from './OnramperCheckoutButtonView';
+export { OnramperError } from './errors';
+export type { OnramperErrorCode, OnramperErrorPayload } from './errors';
+export type {
+  CheckoutButtonStyle,
+  CheckoutFinalizeResponse,
+  CheckoutRequest,
+  CheckoutPaymentType,
+  CheckoutRequirement,
+  HeadlessCheckoutData,
+  OnramperConfiguration,
+  OnramperEnvironment,
+  OnramperLogLevel,
+  OnramperState,
+  OnramperTheme,
+  QuoteError,
+  QuoteResponse,
+  RenderType,
+  SessionCredentials,
+  ToSItem,
+  TransactionType,
+  UserInfoField,
+  WalletInfo,
+} from './types';
+export type { CheckoutEvent, EventName, EventPayload } from './events';

package/src/specs/OnramperCheckoutButton.nitro.ts

@@ -0,0 +1,16 @@
+import type { HybridView, HybridViewMethods, HybridViewProps } from 'react-native-nitro-modules';
+
+// The native checkout button. Renders the SwiftUI OnramperCheckoutButton that
+// getCheckoutRequirements() stashed under `intentHandle`, hosted via
+// UIHostingController. iOS-only (Android is a platformUnsupported stub).
+export interface OnramperCheckoutButtonProps extends HybridViewProps {
+  intentHandle: string;
+}
+
+export interface OnramperCheckoutButtonMethods extends HybridViewMethods {}
+
+export type OnramperCheckoutButton = HybridView<
+  OnramperCheckoutButtonProps,
+  OnramperCheckoutButtonMethods,
+  { ios: 'swift' }
+>;

package/src/specs/OnramperNitro.nitro.ts

@@ -0,0 +1,60 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+
+// Plain config passed to configure(). String unions are validated on the Swift
+// side against the SDK's Environment/Theme/LogLevel enums.
+export interface OnramperNitroConfig {
+  apiKey: string;
+  clientId: string;
+  environment: string; // 'development' | 'production'
+  theme: string; // 'system' | 'light' | 'dark'
+  logLevel: string; // 'off' | 'error' | 'info' | 'debug'
+}
+
+// Mirrors OnramperSDK.SessionCredentials. Named with a Nitro prefix to avoid a
+// Swift type clash with the SDK's own `SessionCredentials`.
+export interface NitroSessionCredentials {
+  sessionId: string;
+  sessionToken: string;
+}
+
+// Result of getCheckoutRequirements: a handle the OnramperCheckoutButton view
+// renders by, plus the quote (JSON-encoded QuoteResponse, parsed in JS).
+export interface PreparedIntentResult {
+  intentHandle: string;
+  quoteJson: string;
+}
+
+/**
+ * Native bridge to OnramperSDK's `OnramperClient`. The public, typed JS API
+ * (`OnramperClient`) wraps this.
+ *
+ * State and checkout events are delivered as JSON strings (the SDK's
+ * `OnramperState`/`CheckoutEvent` are non-Codable Swift enums; the Swift side
+ * hand-maps each case to a dict and JSON-encodes it). The JS wrapper parses
+ * them back into the fully-typed `OnramperState`/`CheckoutEvent` unions.
+ */
+export interface OnramperNitro extends HybridObject<{ ios: 'swift' }> {
+  configure(config: OnramperNitroConfig): Promise<void>;
+  initialize(sessionId: string, sessionToken: string): Promise<void>;
+  reset(): Promise<void>;
+  signOut(): Promise<void>;
+
+  // Fetches checkout requirements + quote, stores the SDK's SwiftUI checkout
+  // button under a handle, and returns the handle + JSON-encoded quote. The
+  // OnramperCheckoutButton Nitro view renders the stored button by handle.
+  // `requestJson` is a JSON CheckoutRequest; `styleJson` a JSON CheckoutButtonStyle.
+  getCheckoutRequirements(requestJson: string, styleJson: string): Promise<PreparedIntentResult>;
+  cancelPreparedIntent(intentHandle: string): Promise<void>;
+
+  // Single native callback per stream; the JS wrapper fans out to multiple listeners.
+  setStateListener(onState: (stateJson: string) => void): void;
+  setEventListener(onEvent: (eventJson: string) => void): void;
+
+  // The SDK's sessionExpirationHandler, as a stored async callback that returns
+  // fresh credentials. Replaces the Expo-era onSessionExpired/provide/fail dance.
+  setSessionExpirationHandler(handler: () => Promise<NitroSessionCredentials>): void;
+
+  // NOTE: every HybridObject has a built-in `dispose()`; we override it natively
+  // (in HybridOnramperNitro.swift) to release stored callbacks + the SDK client.
+  // It must NOT be declared here — nitrogen rejects re-declaring dispose().
+}

package/src/types.ts

@@ -0,0 +1,133 @@
+// Mirrors Swift Codable structs in OnramperSDK. Source of truth is the Swift SDK
+// at the bundled version. Do not add fields that don't exist there.
+
+import type { OnramperErrorPayload } from './errors';
+
+export type OnramperEnvironment = 'development' | 'production';
+export type OnramperLogLevel = 'off' | 'error' | 'info' | 'debug';
+export type OnramperTheme = 'system' | 'light' | 'dark';
+
+export type TransactionType = 'buy' | 'sell';
+
+export interface SessionCredentials {
+  sessionId: string;
+  sessionToken: string;
+}
+
+export interface OnramperConfiguration {
+  apiKey: string;
+  clientId: string;
+  environment: OnramperEnvironment;
+  theme?: OnramperTheme;
+  logLevel?: OnramperLogLevel;
+  /**
+   * 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
+   * are available; the SDK will surface `userTokenRefreshFailed`.
+   */
+  onSessionExpired: () => SessionCredentials | Promise<SessionCredentials>;
+}
+
+export interface WalletInfo {
+  network: string;
+  address: string;
+  memo?: string;
+}
+
+// Flattened from the Swift nesting (CheckoutIntentRequest → OnramperTransactionData).
+// The bridge re-nests before handing to the SDK. ISO codes (`source`, `destination`,
+// `country`, `subdivision`) are lowercased by the SDK; pass either case.
+export interface CheckoutRequest {
+  source: string;
+  destination?: string;
+  amount: number;
+  type: TransactionType;
+  country?: string;
+  subdivision?: string;
+  paymentMethod: string;
+  wallet: WalletInfo;
+  onlyOnramps?: string[];
+}
+
+// Mirrors Swift QuoteResponse exactly — all fields optional because the BFF
+// can return a partial quote with `errors` populated when the onramp can't
+// honor the request. Integrators must handle nulls.
+export interface QuoteResponse {
+  quoteId?: string;
+  ramp?: string;
+  rate?: number;
+  networkFee?: number;
+  transactionFee?: number;
+  payout?: number;
+  paymentMethod?: string;
+  recommendations?: string[];
+  errors?: QuoteError[];
+}
+
+export interface QuoteError {
+  type: string;
+  message: string;
+}
+
+export interface CheckoutButtonStyle {
+  backgroundColor?: string; // hex #RRGGBB or #RRGGBBAA
+  foregroundColor?: string;
+  borderRadius?: number;
+}
+
+// Mirrors Swift `RenderType` raw values from Models/SharedTypes.swift.
+export type RenderType = 'webview' | 'deeplink';
+// Mirrors Swift `CheckoutPaymentType` raw values from Models/SharedTypes.swift.
+export type CheckoutPaymentType = 'applepay' | 'revolutpay';
+
+// Mirrors Swift `CheckoutFinalizeResponse` / `HeadlessCheckoutData`
+// (Sources/OnramperSDK/Models/CheckoutFinalizeResponse.swift).
+export interface HeadlessCheckoutData {
+  checkoutPaymentType: CheckoutPaymentType;
+  url: string;
+  renderType: RenderType;
+}
+
+export interface CheckoutFinalizeResponse {
+  headlessCheckoutId: string;
+  headlessCheckoutData: HeadlessCheckoutData;
+}
+
+// Checkout requirements surfaced by the BFF and bridged through JSON.
+// Shape mirrors Sources/OnramperSDK/Models/CheckoutIntentResponse.swift.
+export type CheckoutRequirement =
+  | { type: 'tos'; providerId: string; items: ToSItem[] }
+  | { type: 'amount_limit'; providerId: string; minAmountLimit?: number; maxAmountLimit?: number }
+  | { type: 'user_info'; providerId: string; fields: UserInfoField[] };
+
+export interface ToSItem {
+  type: 'tos' | 'privacy_policy' | 'user_agreement';
+  required: boolean;
+  satisfied: boolean;
+  url?: string;
+  content?: string;
+}
+
+export interface UserInfoField {
+  type: string; // backend can extend; safer to leave open
+  required: boolean;
+  // other fields omitted for v1 — extend later if needed
+}
+
+export type OnramperState =
+  | { kind: 'idle' }
+  | { kind: 'initializing' }
+  | { kind: 'ready' }
+  | { kind: 'checkoutPreparing' }
+  | { kind: 'requireLogin'; requirements: CheckoutRequirement[] }
+  | { kind: 'authenticating' }
+  | { kind: 'readyToCheckout' }
+  | { kind: 'finalizing' }
+  | { kind: 'rendering'; url: string; renderType: RenderType; paymentType: CheckoutPaymentType }
+  | { kind: 'completed' }
+  | { kind: 'failed'; error: OnramperErrorPayload };
+
+export type { OnramperErrorPayload };