react-native-insider 8.1.0 → 9.0.0-nh

package/src/InsiderAppFrame.js

@@ -0,0 +1,265 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import {Platform} from 'react-native';
+
+import InsiderAppFrameNativeComponent from './specs/InsiderAppFrameNativeComponent';
+import {InsiderAppFramesError} from './InsiderAppFramesError';
+import {InsiderAppFrameStatus} from './InsiderAppFrameStatus';
+import {
+  resolveFrameStyle,
+  parseActionData,
+  normalizeStatus,
+  collapsesHeight,
+  isErrorStatus,
+  shouldWarnAboutUnsupportedReactNative,
+  APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR,
+} from './InsiderAppFrameLogic';
+
+let hasWarnedAboutUnsupportedReactNative = false;
+
+/**
+ * Whether the native component can exist in this app. Read on every render rather than cached at
+ * module scope: it is a few property reads, and a cached answer would outlive the host it was
+ * read from in tests.
+ */
+function readHostSupport() {
+  // Read from Platform: a deep import of `ReactNativeVersion` triggers React Native's
+  // deep-import deprecation warning in the consumer's logs. Optional-chained because some
+  // Platform stubs have no `constants`.
+  const reactNativeVersion = Platform.constants?.reactNativeVersion ?? null;
+
+  // Absent under the legacy architecture, where the iOS component is not compiled at all.
+  const isFabricEnabled = typeof global !== 'undefined' && global.nativeFabricUIManager != null;
+
+  return {
+    reactNativeVersion,
+    isFabricEnabled,
+    isUnsupported: shouldWarnAboutUnsupportedReactNative(
+      Platform.OS,
+      reactNativeVersion,
+      isFabricEnabled,
+    ),
+    // Narrower than isUnsupported: only the legacy architecture makes rendering throw. The
+    // version arm stays a warning, since Fabric below 0.77 fails without throwing.
+    cannotRender: Platform.OS === 'ios' && !isFabricEnabled,
+  };
+}
+
+function warnOnceIfComponentCannotRegister({
+  reactNativeVersion,
+  isFabricEnabled,
+  isUnsupported,
+  cannotRender,
+}) {
+  if (!__DEV__ || hasWarnedAboutUnsupportedReactNative || !isUnsupported) {
+    return;
+  }
+
+  hasWarnedAboutUnsupportedReactNative = true;
+  const versionLabel = reactNativeVersion
+    ? `${reactNativeVersion.major}.${reactNativeVersion.minor}.${reactNativeVersion.patch}`
+    : 'an unknown version';
+  const minimumLabel = `0.${APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR}`;
+  const isBelowMinimum =
+    reactNativeVersion?.major === 0 &&
+    reactNativeVersion.minor < APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR;
+
+  console.warn(
+    `[Insider] InsiderAppFrame requires React Native >= 0.${APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR} ` +
+      'with the New Architecture enabled on iOS. This app is on ' +
+      `${versionLabel}${isFabricEnabled ? '' : ' with the New Architecture off'}. ` +
+      (cannotRender
+        ? 'Rendering the native component would throw there, so the frame renders nothing and ' +
+          'emits no events. Enable the New Architecture' +
+          (isBelowMinimum ? ` and upgrade to React Native >= ${minimumLabel}` : '') +
+          ' to use InsiderAppFrame on iOS. '
+        : `Below 0.${APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR} the native component is not ` +
+          'guaranteed to register; if it does not, the frame shows no content and emits no ' +
+          'events. Upgrade React Native to use InsiderAppFrame on iOS. ') +
+      'The rest of the Insider SDK is unaffected.',
+  );
+}
+
+/**
+ * An empty or non-string `placementId` reaches native as no placement, which lands on the
+ * collapsing `NO_PLACEMENT` status with no error — indistinguishable from an empty placement.
+ * Warned per offending value, since two different broken placements are two different bugs.
+ */
+function warnIfPlacementIdUnusable(placementId) {
+  if (!__DEV__ || (typeof placementId === 'string' && placementId)) {
+    return;
+  }
+
+  console.warn(
+    `[Insider] InsiderAppFrame was given a placementId of ${JSON.stringify(placementId)}, which ` +
+      'is not a non-empty string. Native has no placement to resolve, so the frame collapses to ' +
+      'nothing without reporting an error. Check the value reaching the prop.',
+  );
+}
+
+let hasWarnedAboutDisabledAppFrames = false;
+
+/**
+ * App Frames is off by default in the native SDK. DISABLED has exactly one cause — the app-wide
+ * opt-in flag has not reached the SDK — and React Native developers rarely see the native log
+ * line that names it, so it is surfaced here.
+ */
+function warnOnceAboutDisabledAppFrames(placementId) {
+  if (!__DEV__ || hasWarnedAboutDisabledAppFrames) {
+    return;
+  }
+
+  hasWarnedAboutDisabledAppFrames = true;
+  console.warn(
+    `[Insider] InsiderAppFrame got status DISABLED for placement "${placementId}", so it will ` +
+      'render nothing.\n\nMost often this means the app has not opted in to App Frames, which is ' +
+      'off by default in the native SDK:\n\n' +
+      '  Android — AndroidManifest.xml, inside <application>:\n' +
+      '    <meta-data android:name="com.useinsider.insider.APP_FRAMES_ENABLED" android:value="true" />\n\n' +
+      '  iOS — Info.plist:\n' +
+      '    <key>Insider</key>\n' +
+      '    <dict><key>App Frames Enabled</key><true/></dict>\n\n' +
+      'This status has no other cause, so if the app does opt in, the flag is not reaching the ' +
+      'SDK — check for a nested plist key, a manifest-merger drop, or a misspelled meta-data ' +
+      'name. Shown once, in development only.',
+  );
+}
+
+/**
+ * Renders an inline App Frames placement.
+ *
+ * The height the native view reports is applied here because Yoga assigns an
+ * exact frame and leaves the native self-sizing paths inert. An explicit
+ * `height` in `style` still wins, matching the precedence rule both native
+ * SDKs use.
+ */
+function InsiderAppFrame(
+  {
+    placementId,
+    style,
+    onStatusChange,
+    onLoadError,
+    onHeightChange,
+    onDismissRequest,
+    onAction,
+    ...rest
+  },
+  ref,
+) {
+  // `undefined` means no height has been reported yet, so the caller's own `flex`/`aspectRatio`
+  // applies while loading instead of a forced zero height.
+  //
+  // Intentionally not reset on a `placementId` change: native keeps its own last reported height
+  // across a swap and suppresses a report equal to it, so zeroing here would leave a new placement
+  // of the same height in a zero-height box.
+  const [reportedHeight, setReportedHeight] = useState(undefined);
+
+  // Refs rather than state so `getStatus()`/`getError()` already return the new value inside the
+  // corresponding callback, as reading the native view does.
+  const statusRef = useRef(InsiderAppFrameStatus.DETACHED);
+  const errorRef = useRef(null);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      getStatus: () => statusRef.current,
+      getError: () => errorRef.current,
+    }),
+    [],
+  );
+
+  const hostSupport = readHostSupport();
+
+  useEffect(() => {
+    warnOnceIfComponentCannotRegister(hostSupport);
+    // Mount-only: the host cannot change while the app runs.
+  }, []);
+
+  useEffect(() => {
+    // Block body: a returned value would be treated by React as a cleanup function.
+    warnIfPlacementIdUnusable(placementId);
+  }, [placementId]);
+
+  const handleHeightChange = useCallback(
+    event => {
+      const {height} = event.nativeEvent;
+      setReportedHeight(height);
+      onHeightChange?.(height);
+    },
+    [onHeightChange],
+  );
+
+  const handleLoadError = useCallback(
+    event => {
+      const nextError = InsiderAppFramesError.from(event.nativeEvent);
+      errorRef.current = nextError;
+      onLoadError?.(nextError);
+    },
+    [onLoadError],
+  );
+
+  const handleAction = useCallback(
+    event => onAction?.(parseActionData(event.nativeEvent.data)),
+    [onAction],
+  );
+
+  const handleStatusChange = useCallback(
+    event => {
+      const {status: rawStatus, previousStatus} = event.nativeEvent;
+      const nextStatus = normalizeStatus(rawStatus);
+
+      statusRef.current = nextStatus;
+
+      // Native fires the error event before the status event, so an ERROR_* status must keep
+      // the error it just received; any other status clears it.
+      if (!isErrorStatus(nextStatus)) {
+        errorRef.current = null;
+      }
+
+      // Native zeroes its own size on collapse without firing a height event.
+      if (collapsesHeight(nextStatus)) {
+        setReportedHeight(0);
+      }
+
+      if (nextStatus === InsiderAppFrameStatus.DISABLED) {
+        warnOnceAboutDisabledAppFrames(placementId);
+      }
+
+      onStatusChange?.(nextStatus, normalizeStatus(previousStatus));
+    },
+    [onStatusChange, placementId],
+  );
+
+  const handleDismissRequest = useCallback(
+    () => onDismissRequest?.(),
+    [onDismissRequest],
+  );
+
+  // Rendering the native component here is not inert: under the legacy architecture React Native
+  // throws resolving its view config ("not found in the UIManager"), which unmounts the host's
+  // whole tree. After every hook, so the ref handle still answers DETACHED.
+  if (hostSupport.cannotRender) {
+    return null;
+  }
+
+  return (
+    <InsiderAppFrameNativeComponent
+      {...rest}
+      placementId={placementId}
+      style={resolveFrameStyle(style, reportedHeight)}
+      onStatusChange={handleStatusChange}
+      onLoadError={handleLoadError}
+      onHeightChange={handleHeightChange}
+      onDismissRequest={handleDismissRequest}
+      onAction={handleAction}
+    />
+  );
+}
+
+export default forwardRef(InsiderAppFrame);

package/src/InsiderAppFrameLogic.d.ts

@@ -0,0 +1,35 @@
+import type {InsiderAppFrameStatusType} from './InsiderAppFrameStatus';
+import type {StyleProp, ViewStyle} from 'react-native';
+
+export declare function flattenStyle(style: StyleProp<ViewStyle>): ViewStyle;
+export declare function hasExplicitHeight(style: StyleProp<ViewStyle>): boolean;
+/** Applies the reported height to `style` unless `style` already sets `height`. */
+export declare function resolveFrameStyle(
+  style: StyleProp<ViewStyle>,
+  reportedHeight: number | undefined,
+): StyleProp<ViewStyle>;
+/** Parses an action payload; returns `{}` for malformed input instead of throwing. */
+export declare function parseActionData(raw: string | undefined): Record<string, unknown>;
+/** Maps a status string onto `InsiderAppFrameStatus`, falling back to `UNRECOGNIZED`. */
+export declare function normalizeStatus(status: unknown): InsiderAppFrameStatusType;
+
+/** Statuses in which the frame collapses to zero height. */
+export declare const COLLAPSING_STATUSES: readonly InsiderAppFrameStatusType[];
+export declare function collapsesHeight(status: InsiderAppFrameStatusType): boolean;
+
+/** The three `ERROR_*` statuses. `UNAVAILABLE` and `DISABLED` are resting states, not errors. */
+export declare const ERROR_STATUSES: readonly InsiderAppFrameStatusType[];
+export declare function isErrorStatus(status: InsiderAppFrameStatusType): boolean;
+
+/** The in-flight loading statuses: `RESOLVING`, `DOWNLOADING` and `RENDERING`. */
+export declare const LOADING_STATUSES: readonly InsiderAppFrameStatusType[];
+export declare function isLoadingStatus(status: InsiderAppFrameStatusType): boolean;
+
+/** Minimum React Native minor version (0.x) that supports App Frames on iOS. */
+export declare const APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR: number;
+/** True when App Frames cannot render on this platform and React Native setup. */
+export declare function shouldWarnAboutUnsupportedReactNative(
+  platformOS: string,
+  version: {major: number; minor: number; patch: number} | null | undefined,
+  isFabricEnabled?: boolean,
+): boolean;

package/src/InsiderAppFrameLogic.js

@@ -0,0 +1,192 @@
+import {InsiderAppFrameStatus} from './InsiderAppFrameStatus';
+
+// Kept free of React and react-native imports so these helpers test under plain Jest.
+
+function flattenStyle(style) {
+  if (!style) {
+    return {};
+  }
+
+  if (Array.isArray(style)) {
+    return style.reduce(
+      (accumulator, entry) => Object.assign(accumulator, flattenStyle(entry)),
+      {},
+    );
+  }
+
+  // Unlike React Native's `flattenStyle`, non-objects (numeric style refs, strings) yield `{}`
+  // rather than `undefined`, so `hasExplicitHeight` can dereference the result and a string is
+  // not spread into indexed keys.
+  if (typeof style !== 'object') {
+    return {};
+  }
+
+  return Object.assign({}, style);
+}
+
+function hasExplicitHeight(style) {
+  return flattenStyle(style).height !== undefined;
+}
+
+/**
+ * Applies the native-reported height unless the caller declared one. Yoga assigns every native
+ * view an exact frame, which makes the native self-sizing paths inert.
+ *
+ * With no height reported yet (`undefined`, unlike a legitimate `0`) the style is returned
+ * untouched, so the caller's own `flex`/`aspectRatio` takes effect.
+ */
+function resolveFrameStyle(style, reportedHeight) {
+  if (reportedHeight === undefined || hasExplicitHeight(style)) {
+    return style;
+  }
+
+  return [style, {height: reportedHeight}];
+}
+
+/**
+ * Maps a bridge status string onto `InsiderAppFrameStatus`, falling back to `UNRECOGNIZED`.
+ * Android forwards native enum names verbatim, so a newer SDK can send a member this package
+ * does not know; normalising keeps the value inside the typed union.
+ */
+function normalizeStatus(status) {
+  if (Object.prototype.hasOwnProperty.call(InsiderAppFrameStatus, status)) {
+    return InsiderAppFrameStatus[status];
+  }
+
+  // The Android bridge does not log the raw value, so this is the only place it is visible.
+  if (__DEV__) {
+    console.warn(
+      `[Insider] InsiderAppFrame received an unrecognised status ${JSON.stringify(status)} and ` +
+        'mapped it to UNRECOGNIZED. This usually means the native SDK is newer than this ' +
+        'package. Everything still works; the status is simply one this version cannot name.',
+    );
+  }
+
+  return InsiderAppFrameStatus.UNRECOGNIZED;
+}
+
+/**
+ * Statuses on which the frame occupies no space. Native zeroes its own size on these without
+ * firing a height event, so the height applied from JS must be zeroed too. Matches both native
+ * implementations, which also collapse on DISABLED.
+ *
+ * DETACHED is absent so a frame scrolled off-window keeps its height and does not jump when it
+ * returns.
+ */
+const COLLAPSING_STATUSES = Object.freeze([
+  InsiderAppFrameStatus.NO_PLACEMENT,
+  InsiderAppFrameStatus.DISABLED,
+  InsiderAppFrameStatus.UNAVAILABLE,
+  InsiderAppFrameStatus.DISMISSED,
+  InsiderAppFrameStatus.ERROR_RESOLVING,
+  InsiderAppFrameStatus.ERROR_DOWNLOADING,
+  InsiderAppFrameStatus.ERROR_RENDERING,
+]);
+
+function collapsesHeight(status) {
+  return COLLAPSING_STATUSES.indexOf(status) !== -1;
+}
+
+/**
+ * The statuses that mean a step failed. `UNAVAILABLE` and `DISABLED` are resting states, not
+ * failures.
+ */
+const ERROR_STATUSES = Object.freeze([
+  InsiderAppFrameStatus.ERROR_RESOLVING,
+  InsiderAppFrameStatus.ERROR_DOWNLOADING,
+  InsiderAppFrameStatus.ERROR_RENDERING,
+]);
+
+function isErrorStatus(status) {
+  return ERROR_STATUSES.indexOf(status) !== -1;
+}
+
+/**
+ * The in-flight loading phases. A free function rather than a member of
+ * `InsiderAppFrameStatus`, which `normalizeStatus` looks up by key.
+ */
+const LOADING_STATUSES = Object.freeze([
+  InsiderAppFrameStatus.RESOLVING,
+  InsiderAppFrameStatus.DOWNLOADING,
+  InsiderAppFrameStatus.RENDERING,
+]);
+
+function isLoadingStatus(status) {
+  return LOADING_STATUSES.indexOf(status) !== -1;
+}
+
+/**
+ * The first React Native release whose codegen reads `codegenConfig.ios.componentProvider`.
+ */
+const APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR = 77;
+
+/**
+ * True when App Frames is unsupported on the running iOS host: without the New Architecture the
+ * frame renders nothing, and below 0.77 it may not register. Either way it warrants a warning.
+ *
+ * Returns false on an unreadable version rather than guessing.
+ */
+function shouldWarnAboutUnsupportedReactNative(platformOS, version, isFabricEnabled) {
+  if (platformOS !== 'ios') {
+    return false;
+  }
+
+  // The iOS component exists only under the New Architecture, whatever the React Native version.
+  // Explicitly `false` only: an undetermined value must not produce a warning.
+  if (isFabricEnabled === false) {
+    return true;
+  }
+
+  if (
+    !version ||
+    typeof version.major !== 'number' ||
+    typeof version.minor !== 'number'
+  ) {
+    return false;
+  }
+
+  if (version.major > 0) {
+    return false;
+  }
+
+  return version.minor < APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR;
+}
+
+function warnAboutUnusableActionData(raw) {
+  if (__DEV__) {
+    console.warn(
+      '[Insider] InsiderAppFrame received action data that is not a JSON object ' +
+        `(${JSON.stringify(raw)}), so onAction is given {} instead.`,
+    );
+  }
+}
+
+function parseActionData(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch (error) {
+    // Reported below with the other unusable shapes.
+  }
+
+  warnAboutUnusableActionData(raw);
+  return {};
+}
+
+export {
+  flattenStyle,
+  hasExplicitHeight,
+  resolveFrameStyle,
+  normalizeStatus,
+  collapsesHeight,
+  COLLAPSING_STATUSES,
+  isErrorStatus,
+  ERROR_STATUSES,
+  isLoadingStatus,
+  LOADING_STATUSES,
+  shouldWarnAboutUnsupportedReactNative,
+  APP_FRAMES_MIN_IOS_REACT_NATIVE_MINOR,
+  parseActionData,
+};

package/src/InsiderAppFrameStatus.d.ts

@@ -0,0 +1,22 @@
+export declare const InsiderAppFrameStatus: {
+  readonly DETACHED: 'DETACHED';
+  readonly NO_PLACEMENT: 'NO_PLACEMENT';
+  readonly RESOLVING: 'RESOLVING';
+  readonly DOWNLOADING: 'DOWNLOADING';
+  readonly RENDERING: 'RENDERING';
+  readonly UNAVAILABLE: 'UNAVAILABLE';
+  readonly READY: 'READY';
+  readonly DISMISSED: 'DISMISSED';
+  readonly ERROR_RESOLVING: 'ERROR_RESOLVING';
+  readonly ERROR_DOWNLOADING: 'ERROR_DOWNLOADING';
+  readonly ERROR_RENDERING: 'ERROR_RENDERING';
+  /** App Frames is not enabled for the app. A terminal resting state, not an error. */
+  readonly DISABLED: 'DISABLED';
+  /** Reported when the native SDK sends a status this version does not recognize. */
+  readonly UNRECOGNIZED: 'UNRECOGNIZED';
+};
+
+export type InsiderAppFrameStatusType =
+  (typeof InsiderAppFrameStatus)[keyof typeof InsiderAppFrameStatus];
+
+export default InsiderAppFrameStatus;

package/src/InsiderAppFrameStatus.js

@@ -0,0 +1,35 @@
+/**
+ * The content-lifecycle phase an InsiderAppFrame is in, mirroring the native
+ * `InsiderAppFramesViewStatus` enum. Observe transitions via `onStatusChange`.
+ *
+ * Only `DISABLED` is terminal. `UNAVAILABLE` (no campaign targets the placement)
+ * and `DISABLED` are not errors; only the `ERROR_*` values are. App Frames fail
+ * silently by design, so prefer collapsing the slot over surfacing any of these
+ * to the end user.
+ *
+ * @readonly
+ * @enum {string}
+ */
+const InsiderAppFrameStatus = Object.freeze({
+  DETACHED: 'DETACHED',
+  NO_PLACEMENT: 'NO_PLACEMENT',
+  RESOLVING: 'RESOLVING',
+  DOWNLOADING: 'DOWNLOADING',
+  RENDERING: 'RENDERING',
+  UNAVAILABLE: 'UNAVAILABLE',
+  READY: 'READY',
+  DISMISSED: 'DISMISSED',
+  ERROR_RESOLVING: 'ERROR_RESOLVING',
+  ERROR_DOWNLOADING: 'ERROR_DOWNLOADING',
+  ERROR_RENDERING: 'ERROR_RENDERING',
+
+  // Its only cause is that the app has not opted in to App Frames (Android's
+  // APP_FRAMES_ENABLED meta-data / iOS's `App Frames Enabled` Info.plist key).
+  DISABLED: 'DISABLED',
+
+  // JS-only: a status reported by a native SDK newer than this package.
+  UNRECOGNIZED: 'UNRECOGNIZED',
+});
+
+export { InsiderAppFrameStatus };
+export default InsiderAppFrameStatus;

package/src/InsiderAppFramesError.d.ts

@@ -0,0 +1,25 @@
+export declare const InsiderAppFramesErrorCode: {
+  readonly UNKNOWN: 'UNKNOWN';
+  readonly RESOLUTION_FAILED: 'RESOLUTION_FAILED';
+  readonly RESPONSE_MALFORMED: 'RESPONSE_MALFORMED';
+  readonly DOWNLOADING_FAILED: 'DOWNLOADING_FAILED';
+  readonly PLACEMENT_UNTRUSTED: 'PLACEMENT_UNTRUSTED';
+  readonly CONTENT_DISPLAY_FAILED: 'CONTENT_DISPLAY_FAILED';
+  readonly RENDERING_FAILED: 'RENDERING_FAILED';
+};
+
+export type InsiderAppFramesErrorCodeType =
+  (typeof InsiderAppFramesErrorCode)[keyof typeof InsiderAppFramesErrorCode];
+
+/** The `dismissCode` value when the content supplied none. */
+export declare const NO_DISMISS_CODE: -1;
+
+export declare class InsiderAppFramesError extends Error {
+  readonly code: InsiderAppFramesErrorCodeType;
+  /** The code the content dismissed with, or `NO_DISMISS_CODE`. */
+  readonly dismissCode: number;
+  /** The underlying platform error's message, or `null`. `message` always describes `code`. */
+  readonly cause: string | null;
+  constructor(code: string, message: string, dismissCode?: number, cause?: string | null);
+  static from(error: unknown): InsiderAppFramesError;
+}

package/src/InsiderAppFramesError.js

@@ -0,0 +1,77 @@
+const InsiderAppFramesErrorCode = Object.freeze({
+  UNKNOWN: 'UNKNOWN',
+  RESOLUTION_FAILED: 'RESOLUTION_FAILED',
+  RESPONSE_MALFORMED: 'RESPONSE_MALFORMED',
+  DOWNLOADING_FAILED: 'DOWNLOADING_FAILED',
+  PLACEMENT_UNTRUSTED: 'PLACEMENT_UNTRUSTED',
+  CONTENT_DISPLAY_FAILED: 'CONTENT_DISPLAY_FAILED',
+  RENDERING_FAILED: 'RENDERING_FAILED',
+});
+
+const NO_DISMISS_CODE = -1;
+
+class InsiderAppFramesError extends Error {
+  #code;
+  #dismissCode;
+  #cause;
+
+  constructor(code, message, dismissCode, cause) {
+    super(message);
+
+    this.name = 'InsiderAppFramesError';
+    const isKnownCode = Object.prototype.hasOwnProperty.call(InsiderAppFramesErrorCode, code);
+    this.#code = isKnownCode ? InsiderAppFramesErrorCode[code] : InsiderAppFramesErrorCode.UNKNOWN;
+
+    // The Android bridge does not log the raw code, so this is the only place it is visible.
+    if (__DEV__ && !isKnownCode && code !== undefined && code !== null) {
+      console.warn(
+        `[Insider] InsiderAppFramesError received an unrecognised code ${JSON.stringify(code)} ` +
+          'and mapped it to UNKNOWN. This usually means the native SDK is newer than this package.',
+      );
+    }
+    this.#dismissCode = typeof dismissCode === 'number' ? dismissCode : NO_DISMISS_CODE;
+    // Codegen event fields are non-nullable, so an absent cause arrives as an empty string.
+    this.#cause = typeof cause === 'string' && cause ? cause : null;
+  }
+
+  get code() {
+    return this.#code;
+  }
+
+  get dismissCode() {
+    return this.#dismissCode;
+  }
+
+  /**
+   * The originating platform error's message (Android `getCause()`, iOS
+   * `NSUnderlyingErrorKey`), or null when there is none.
+   */
+  get cause() {
+    return this.#cause;
+  }
+
+  static from(error) {
+    if (error instanceof InsiderAppFramesError) {
+      return error;
+    }
+
+    if (typeof error === 'string') {
+      return new InsiderAppFramesError(InsiderAppFramesErrorCode.UNKNOWN, error);
+    }
+
+    if (error && typeof error === 'object') {
+      const message =
+        typeof error.message === 'string' && error.message
+          ? error.message
+          : 'An unknown App Frames error occurred.';
+      return new InsiderAppFramesError(error.code, message, error.dismissCode, error.cause);
+    }
+
+    return new InsiderAppFramesError(
+      InsiderAppFramesErrorCode.UNKNOWN,
+      'An unknown App Frames error occurred.',
+    );
+  }
+}
+
+export {InsiderAppFramesError, InsiderAppFramesErrorCode, NO_DISMISS_CODE};

package/src/InsiderEvent.js

@@ -5,6 +5,7 @@ import { shouldNotProceed, generateJSONErrorString, checkParameters, showParamet
 const Insider = NativeModules.RNInsider;
 
 export default class RNInsiderEvent {
+  // Stryker disable next-line StringLiteral: the constructor always overwrites name
   name = '';
   parameters = [];