@stripe/stripe-react-native 0.57.3 → 0.59.0

package/src/connect/analytics/AnalyticsClient.ts

@@ -0,0 +1,75 @@
+/**
+ * Analytics HTTP client for sending events to Stripe backend
+ * Matches the Swift iOS SDK's AnalyticsClientV2 user agent format
+ */
+
+import { Platform } from 'react-native';
+import type { AnalyticsPayload } from './events';
+
+const ANALYTICS_URL = 'https://r.stripe.com/0';
+const CLIENT_ID = 'mobile_connect_sdk';
+const ORIGIN = 'stripe-connect-react-native';
+
+/**
+ * System information for analytics
+ */
+export interface SystemInfo {
+  sdkVersion: string;
+  osVersion: string;
+  deviceType: string;
+  appName: string;
+  appVersion: string;
+}
+
+/**
+ * Analytics client for sending events to Stripe backend
+ */
+export class AnalyticsClient {
+  private systemInfo: SystemInfo;
+
+  constructor(systemInfo: SystemInfo) {
+    this.systemInfo = systemInfo;
+  }
+
+  /**
+   * Send an analytics event to the Stripe backend
+   * Silently fails if network request fails - analytics should never break app functionality
+   */
+  async sendEvent(payload: AnalyticsPayload): Promise<void> {
+    try {
+      const fullPayload = {
+        ...payload,
+        client_id: CLIENT_ID,
+        origin: ORIGIN,
+        sdk_platform: Platform.OS as 'ios' | 'android',
+        sdk_version: this.systemInfo.sdkVersion,
+        os_version: this.systemInfo.osVersion,
+        device_type: this.systemInfo.deviceType,
+        app_name: this.systemInfo.appName,
+        app_version: this.systemInfo.appVersion,
+      };
+
+      await fetch(ANALYTICS_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'User-Agent': this.buildUserAgent(),
+        },
+        body: JSON.stringify(fullPayload),
+      });
+    } catch (error) {
+      // Silently fail - analytics should never break app functionality
+      if (__DEV__) {
+        console.warn('[StripeConnect] Analytics event failed:', error);
+      }
+    }
+  }
+
+  /**
+   * Build user agent string for analytics requests
+   */
+  private buildUserAgent(): string {
+    const platform = Platform.OS; // 'ios' or 'android'
+    return `Stripe/v1 ${platform}/${this.systemInfo.sdkVersion}`;
+  }
+}

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/connectTypes.ts

@@ -42,7 +42,11 @@ export type EmbeddedErrorType =
   /**
    * API errors covering any other type of problem (e.g., a temporary problem with Stripe's servers), and are extremely uncommon.
    */
-  | 'api_error';
+  | 'api_error'
+  /**
+   * Failure to render the component, typically caused by browser extensions or network issues
+   */
+  | 'render_error';
 
 export type Status =
   | 'blocked'

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>(