@stripe/stripe-react-native 0.58.0 → 0.59.0

package/src/connect/analytics/ComponentAnalyticsClient.ts

@@ -0,0 +1,315 @@
+/**
+ * Component Analytics Client for tracking Connect component events
+ * Matches the Swift iOS SDK's ComponentAnalyticsClient implementation
+ */
+
+import { AnalyticsClient } from './AnalyticsClient';
+import {
+  EVENT_NAMES,
+  type AnalyticsPayload,
+  type CommonAnalyticsFields,
+  type ConnectAnalyticsEvent,
+} from './events';
+
+/**
+ * Configuration for ComponentAnalyticsClient
+ */
+export interface ComponentAnalyticsConfig {
+  publishableKey?: string;
+  platformId?: string;
+  merchantId?: string;
+  livemode?: boolean;
+  component: string;
+}
+
+/**
+ * Generates a UUID v4
+ */
+function generateUUID(): string {
+  /* eslint-disable no-bitwise */
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+  /* eslint-enable no-bitwise */
+}
+
+/**
+ * Component Analytics Client for tracking lifecycle, web view, and error events
+ */
+export class ComponentAnalyticsClient {
+  private analyticsClient: AnalyticsClient;
+  private config: ComponentAnalyticsConfig;
+  private componentInstance: string;
+  private pageViewId?: string;
+  private loadStart: number;
+  private componentFirstViewedTime?: number;
+  private loggedPageLoaded: boolean = false;
+  private loggedComponentLoaded: boolean = false;
+
+  constructor(
+    analyticsClient: AnalyticsClient,
+    config: ComponentAnalyticsConfig
+  ) {
+    this.analyticsClient = analyticsClient;
+    this.config = config;
+    this.componentInstance = generateUUID();
+    this.loadStart = Date.now();
+  }
+
+  /**
+   * Build common fields for all events
+   */
+  private buildCommonFields(): CommonAnalyticsFields {
+    return {
+      event_id: generateUUID(),
+      created: Date.now(),
+      client_id: 'mobile_connect_sdk',
+      origin: 'stripe-connect-react-native',
+      sdk_platform: 'ios' as 'ios' | 'android',
+      sdk_version: '',
+      os_version: '',
+      device_type: '',
+      app_name: '',
+      app_version: '',
+      publishable_key: this.config.publishableKey,
+      platform_id: this.config.platformId,
+      merchant_id: this.config.merchantId,
+      livemode: this.config.livemode,
+      component: this.config.component,
+      component_instance: this.componentInstance,
+    };
+  }
+
+  /**
+   * Send an analytics event
+   */
+  private async log(event: ConnectAnalyticsEvent): Promise<void> {
+    const payload: AnalyticsPayload = {
+      ...this.buildCommonFields(),
+      ...event,
+    };
+
+    await this.analyticsClient.sendEvent(payload);
+  }
+
+  /**
+   * Log component created event
+   */
+  logComponentCreated(): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_CREATED,
+    });
+  }
+
+  /**
+   * Log component viewed event (first time component becomes visible)
+   */
+  logComponentViewed(): void {
+    if (this.componentFirstViewedTime) {
+      return;
+    }
+
+    this.componentFirstViewedTime = Date.now();
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_VIEWED,
+    });
+  }
+
+  /**
+   * Log web page loaded event
+   */
+  logComponentWebPageLoaded(pageViewId?: string): void {
+    if (this.loggedPageLoaded) {
+      return;
+    }
+
+    this.loggedPageLoaded = true;
+    if (pageViewId) {
+      this.pageViewId = pageViewId;
+    }
+
+    const timeToLoad = (Date.now() - this.loadStart) / 1000;
+
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_WEB_PAGE_LOADED,
+      event_metadata: {
+        time_to_load: timeToLoad,
+      },
+      time_to_load: timeToLoad,
+    });
+  }
+
+  /**
+   * Log component loaded event (Connect JS fully initialized)
+   */
+  logComponentLoaded(): void {
+    if (this.loggedComponentLoaded) {
+      return;
+    }
+
+    this.loggedComponentLoaded = true;
+
+    const timeToLoad = (Date.now() - this.loadStart) / 1000;
+    const perceivedTimeToLoad = this.componentFirstViewedTime
+      ? (Date.now() - this.componentFirstViewedTime) / 1000
+      : undefined;
+
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_WEB_COMPONENT_LOADED,
+      event_metadata: {
+        page_view_id: this.pageViewId,
+        time_to_load: timeToLoad,
+        perceived_time_to_load: perceivedTimeToLoad,
+      },
+      page_view_id: this.pageViewId,
+      time_to_load: timeToLoad,
+      perceived_time_to_load: perceivedTimeToLoad,
+    });
+  }
+
+  /**
+   * Log page load error
+   */
+  logPageLoadError(error: Error, url?: string): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_WEB_ERROR_PAGE_LOAD,
+      event_metadata: {
+        error_message: error.message,
+        error_domain: error.name,
+        url,
+      },
+      error_message: error.message,
+      error_domain: error.name,
+      url,
+    });
+  }
+
+  /**
+   * Log unexpected navigation error
+   */
+  logUnexpectedNavigation(url?: string): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_WEB_ERROR_UNEXPECTED_NAVIGATION,
+      event_metadata: {
+        url,
+      },
+      url,
+    });
+  }
+
+  /**
+   * Log unexpected load error type
+   */
+  logUnexpectedLoadErrorType(errorType: string): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_WEB_ERROR_UNEXPECTED_LOAD_ERROR_TYPE,
+      event_metadata: {
+        error_type: errorType,
+      },
+      error_type: errorType,
+    });
+  }
+
+  /**
+   * Log unrecognized setter function warning
+   */
+  logUnrecognizedSetter(setterName: string): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_WEB_WARN_UNRECOGNIZED_SETTER,
+      event_metadata: {
+        setter_name: setterName,
+      },
+      setter_name: setterName,
+    });
+  }
+
+  /**
+   * Log message deserialization error
+   */
+  logDeserializeMessageError(messageName: string, error: Error): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_WEB_ERROR_DESERIALIZE_MESSAGE,
+      event_metadata: {
+        message_name: messageName,
+        error_message: error.message,
+      },
+      message_name: messageName,
+      error_message: error.message,
+    });
+  }
+
+  /**
+   * Log authenticated web view opened
+   */
+  logAuthenticatedWebViewOpened(id: string): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_AUTHENTICATED_WEB_OPENED,
+      event_metadata: {
+        id,
+      },
+      id,
+    });
+  }
+
+  /**
+   * Log authenticated web view canceled
+   */
+  logAuthenticatedWebViewCanceled(id: string): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_AUTHENTICATED_WEB_CANCELED,
+      event_metadata: {
+        id,
+      },
+      id,
+    });
+  }
+
+  /**
+   * Log authenticated web view redirected
+   */
+  logAuthenticatedWebViewRedirected(id: string): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_AUTHENTICATED_WEB_REDIRECTED,
+      event_metadata: {
+        id,
+      },
+      id,
+    });
+  }
+
+  /**
+   * Log authenticated web view error
+   */
+  logAuthenticatedWebViewError(id: string, error: Error): void {
+    this.log({
+      event_name: EVENT_NAMES.COMPONENT_AUTHENTICATED_WEB_ERROR,
+      event_metadata: {
+        id,
+        error_message: error.message,
+      },
+      id,
+      error_message: error.message,
+    });
+  }
+
+  /**
+   * Log client error (catch-all for mobile client errors)
+   */
+  logClientError(error: Error, file?: string, line?: number): void {
+    this.log({
+      event_name: EVENT_NAMES.CLIENT_ERROR,
+      event_metadata: {
+        error_message: error.message,
+        error_domain: error.name,
+        file,
+        line,
+      },
+      error_message: error.message,
+      error_domain: error.name,
+      file,
+      line,
+    });
+  }
+}

package/src/connect/analytics/events.ts

@@ -0,0 +1,253 @@
+/**
+ * Analytics event types for Connect components
+ * Matches the Swift iOS SDK implementation
+ */
+
+/**
+ * Event names matching Swift SDK
+ */
+export const EVENT_NAMES = {
+  COMPONENT_CREATED: 'component.created',
+  COMPONENT_VIEWED: 'component.viewed',
+  COMPONENT_WEB_PAGE_LOADED: 'component.web.page_loaded',
+  COMPONENT_WEB_COMPONENT_LOADED: 'component.web.component_loaded',
+  COMPONENT_WEB_ERROR_PAGE_LOAD: 'component.web.error.page_load',
+  COMPONENT_WEB_ERROR_UNEXPECTED_NAVIGATION:
+    'component.web.error.unexpected_navigation',
+  COMPONENT_WEB_ERROR_UNEXPECTED_LOAD_ERROR_TYPE:
+    'component.web.error.unexpected_load_error_type',
+  COMPONENT_WEB_WARN_UNRECOGNIZED_SETTER:
+    'component.web.warn.unrecognized_setter_function',
+  COMPONENT_WEB_ERROR_DESERIALIZE_MESSAGE:
+    'component.web.error.deserialize_message',
+  COMPONENT_AUTHENTICATED_WEB_OPENED: 'component.authenticated_web.opened',
+  COMPONENT_AUTHENTICATED_WEB_CANCELED: 'component.authenticated_web.canceled',
+  COMPONENT_AUTHENTICATED_WEB_REDIRECTED:
+    'component.authenticated_web.redirected',
+  COMPONENT_AUTHENTICATED_WEB_ERROR: 'component.authenticated_web.error',
+  CLIENT_ERROR: 'client_error',
+} as const;
+
+/**
+ * Common fields included in all analytics events
+ */
+export interface CommonAnalyticsFields {
+  event_id: string;
+  created: number;
+  client_id: string;
+  origin: string;
+  sdk_platform: 'ios' | 'android';
+  sdk_version: string;
+  os_version: string;
+  device_type: string;
+  app_name: string;
+  app_version: string;
+  publishable_key?: string;
+  platform_id?: string;
+  merchant_id?: string;
+  livemode?: boolean;
+  component: string;
+  component_instance: string;
+}
+
+/**
+ * Base analytics event structure
+ */
+export interface AnalyticsEvent {
+  event_name: string;
+  event_metadata?: Record<string, any>;
+}
+
+/**
+ * Component created event
+ */
+export interface ComponentCreatedEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_CREATED;
+}
+
+/**
+ * Component viewed event (first time component becomes visible)
+ */
+export interface ComponentViewedEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_VIEWED;
+}
+
+/**
+ * Web page loaded event (HTML page finished loading)
+ */
+export interface ComponentWebPageLoadedEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_WEB_PAGE_LOADED;
+  event_metadata: {
+    time_to_load: number;
+  };
+  time_to_load: number;
+}
+
+/**
+ * Component loaded event (Connect JS fully initialized)
+ */
+export interface ComponentWebComponentLoadedEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_WEB_COMPONENT_LOADED;
+  event_metadata: {
+    page_view_id?: string;
+    time_to_load: number;
+    perceived_time_to_load?: number;
+  };
+  page_view_id?: string;
+  time_to_load: number;
+  perceived_time_to_load?: number;
+}
+
+/**
+ * Page load error event
+ */
+export interface PageLoadErrorEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_WEB_ERROR_PAGE_LOAD;
+  event_metadata: {
+    error_message: string;
+    error_domain?: string;
+    error_code?: string;
+    url?: string;
+  };
+  error_message: string;
+  error_domain?: string;
+  error_code?: string;
+  url?: string;
+}
+
+/**
+ * Unexpected navigation error event
+ */
+export interface UnexpectedNavigationEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_WEB_ERROR_UNEXPECTED_NAVIGATION;
+  event_metadata: {
+    url?: string;
+  };
+  url?: string;
+}
+
+/**
+ * Unexpected load error type event
+ */
+export interface UnexpectedLoadErrorTypeEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_WEB_ERROR_UNEXPECTED_LOAD_ERROR_TYPE;
+  event_metadata: {
+    error_type: string;
+  };
+  error_type: string;
+}
+
+/**
+ * Unrecognized setter function warning event
+ */
+export interface UnrecognizedSetterEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_WEB_WARN_UNRECOGNIZED_SETTER;
+  event_metadata: {
+    setter_name: string;
+  };
+  setter_name: string;
+}
+
+/**
+ * Message deserialization error event
+ */
+export interface DeserializeMessageErrorEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_WEB_ERROR_DESERIALIZE_MESSAGE;
+  event_metadata: {
+    message_name: string;
+    error_message: string;
+  };
+  message_name: string;
+  error_message: string;
+}
+
+/**
+ * Authenticated web view opened event
+ */
+export interface AuthenticatedWebViewOpenedEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_AUTHENTICATED_WEB_OPENED;
+  event_metadata: {
+    id: string;
+  };
+  id: string;
+}
+
+/**
+ * Authenticated web view canceled event
+ */
+export interface AuthenticatedWebViewCanceledEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_AUTHENTICATED_WEB_CANCELED;
+  event_metadata: {
+    id: string;
+  };
+  id: string;
+}
+
+/**
+ * Authenticated web view redirected event
+ */
+export interface AuthenticatedWebViewRedirectedEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_AUTHENTICATED_WEB_REDIRECTED;
+  event_metadata: {
+    id: string;
+  };
+  id: string;
+}
+
+/**
+ * Authenticated web view error event
+ */
+export interface AuthenticatedWebViewErrorEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.COMPONENT_AUTHENTICATED_WEB_ERROR;
+  event_metadata: {
+    id: string;
+    error_message: string;
+  };
+  id: string;
+  error_message: string;
+}
+
+/**
+ * Client error event (catch-all for mobile client errors)
+ */
+export interface ClientErrorEvent extends AnalyticsEvent {
+  event_name: typeof EVENT_NAMES.CLIENT_ERROR;
+  event_metadata: {
+    error_message: string;
+    error_domain?: string;
+    error_code?: string;
+    file?: string;
+    line?: number;
+  };
+  error_message: string;
+  error_domain?: string;
+  error_code?: string;
+  file?: string;
+  line?: number;
+}
+
+/**
+ * Union type of all possible analytics events
+ */
+export type ConnectAnalyticsEvent =
+  | ComponentCreatedEvent
+  | ComponentViewedEvent
+  | ComponentWebPageLoadedEvent
+  | ComponentWebComponentLoadedEvent
+  | PageLoadErrorEvent
+  | UnexpectedNavigationEvent
+  | UnexpectedLoadErrorTypeEvent
+  | UnrecognizedSetterEvent
+  | DeserializeMessageErrorEvent
+  | AuthenticatedWebViewOpenedEvent
+  | AuthenticatedWebViewCanceledEvent
+  | AuthenticatedWebViewRedirectedEvent
+  | AuthenticatedWebViewErrorEvent
+  | ClientErrorEvent;
+
+/**
+ * Full analytics payload sent to backend
+ */
+export interface AnalyticsPayload
+  extends CommonAnalyticsFields,
+    AnalyticsEvent {}

package/src/connect/testUtils.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared test utilities for Connect component tests
+ */
+
+/**
+ * Mock constants returned by NativeStripeSdkModule.getConstants()
+ * Used to mock the native module in tests
+ */
+export const mockNativeConstants = {
+  API_VERSIONS: {
+    CORE: '2024-12-15',
+    ISSUING: '2024-12-15',
+  },
+  SYSTEM_INFO: {
+    sdkVersion: '1.0.0',
+    osVersion: '18.0',
+    deviceType: 'iPhone14,5',
+    appName: 'TestApp',
+    appVersion: '1.0.0',
+  },
+};
+
+/**
+ * Creates a mock for NativeStripeSdkModule with standard test constants
+ * NOTE: Prefixed with 'mock' to be allowed in jest.mock() factory functions
+ * @param additionalMethods - Optional additional methods to include in the mock
+ * @returns Mock module configuration
+ */
+export const mockCreateNativeStripeSdkMock = (
+  additionalMethods: Record<string, any> = {}
+) => ({
+  __esModule: true,
+  default: {
+    getConstants: jest.fn(() => mockNativeConstants),
+    ...additionalMethods,
+  },
+});

package/src/events.ts

@@ -64,6 +64,8 @@ type Events = {
   embeddedPaymentElementLoadingFailed: EventEmitter<UnsafeObject<any>>;
   embeddedPaymentElementUpdateComplete: EventEmitter<UnsafeObject<any>>;
   onCustomPaymentMethodConfirmHandlerCallback: EventEmitter<UnsafeObject<any>>;
+  paymentMethodMessagingElementDidUpdateHeight: EventEmitter<UnsafeObject<any>>;
+  paymentMethodMessagingElementConfigureResult: EventEmitter<UnsafeObject<any>>;
 };
 
 export function addListener<EventT extends keyof Events>(

package/src/functions.ts

@@ -31,6 +31,7 @@ import type {
   CanAddCardToWalletResult,
   FinancialConnections,
   PlatformPay,
+  CreateRadarSessionResult,
 } from './types';
 import { Platform, EventSubscription } from 'react-native';
 import type { CollectFinancialConnectionsAccountsParams } from './types/FinancialConnections';
@@ -910,6 +911,15 @@ export const openPlatformPaySetup = async (): Promise<void> => {
   }
 };
 
+/**
+ * Creates a [Radar session](https://docs.stripe.com/radar/radar-session).
+ * @returns A promise that resolves to a Radar session id, or an error.
+ */
+export const createRadarSession =
+  async (): Promise<CreateRadarSessionResult> => {
+    return await NativeStripeSdk.createRadarSession();
+  };
+
 export const setFinancialConnectionsForceNativeFlow = async (
   enabled: boolean
 ): Promise<void> => {

package/src/hooks/useStripe.tsx

@@ -27,6 +27,7 @@ import type {
   FinancialConnections,
   PlatformPay,
   PlatformPayError,
+  CreateRadarSessionResult,
 } from '../types';
 import { useCallback } from 'react';
 import {
@@ -59,6 +60,7 @@ import {
   createPlatformPayToken,
   updatePlatformPaySheet,
   openPlatformPaySetup,
+  createRadarSession,
 } from '../functions';
 import type { CollectBankAccountTokenParams } from '../types/PaymentMethod';
 import type { CollectFinancialConnectionsAccountsParams } from '../types/FinancialConnections';
@@ -320,6 +322,11 @@ export function useStripe() {
     return openPlatformPaySetup();
   }, []);
 
+  const _createRadarSession =
+    useCallback(async (): Promise<CreateRadarSessionResult> => {
+      return createRadarSession();
+    }, []);
+
   return {
     retrievePaymentIntent: _retrievePaymentIntent,
     retrieveSetupIntent: _retrieveSetupIntent,
@@ -355,5 +362,6 @@ export function useStripe() {
     createPlatformPayToken: _createPlatformPayToken,
     updatePlatformPaySheet: _updatePlatformPaySheet,
     openPlatformPaySetup: _openPlatformPaySetup,
+    createRadarSession: _createRadarSession,
   };
 }

package/src/specs/NativePaymentMethodMessagingElement.ts

@@ -0,0 +1,25 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import type { DirectEventHandler } from 'react-native/Libraries/Types/CodegenTypes';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+import {
+  PaymentMethodMessagingElementAppearance,
+  PaymentMethodMessagingElementConfiguration,
+  PaymentMethodMessagingElementState,
+} from '../types/components/PaymentMethodMessagingElementComponent';
+import { UnsafeMixed } from './utils';
+
+interface StateChangeEvent {
+  result: UnsafeMixed<PaymentMethodMessagingElementState>;
+}
+
+export interface NativeProps extends ViewProps {
+  appearance?: UnsafeMixed<PaymentMethodMessagingElementAppearance>;
+  configuration: UnsafeMixed<PaymentMethodMessagingElementConfiguration>;
+  onStateChange: DirectEventHandler<StateChangeEvent>;
+}
+
+type ComponentType = HostComponent<NativeProps>;
+
+export default codegenNativeComponent<NativeProps>(
+  'PaymentMethodMessagingElementView'
+) as ComponentType;