@npaw/forge-react-native 9.6.1

package/src/ForgeVideo.ts

@@ -0,0 +1,169 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Per-(instance, identifier) video facade; mirrors the native VideoAdapter manual fire* surface and creates ad reporters.
+ */
+
+import NativeNPAWForge from './specs/NativeNPAWForge';
+import { ForgeAdReporter } from './ForgeAdReporter';
+import type { ForgeOutcome, ForgeParams } from './types';
+
+function asOutcome(value: Promise<unknown>): Promise<ForgeOutcome> {
+  return value as Promise<ForgeOutcome>;
+}
+
+export class ForgeVideo {
+  constructor(
+    readonly instanceId: string,
+    readonly identifier: string
+  ) {}
+
+  fireInit(params: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFireInit(this.instanceId, this.identifier, params));
+  }
+
+  fireStart(params: ForgeParams = {}, options: { forceInit?: boolean } = {}): Promise<ForgeOutcome> {
+    return asOutcome(
+      NativeNPAWForge.videoFireStart(this.instanceId, this.identifier, params, options.forceInit ?? false)
+    );
+  }
+
+  fireJoin(params: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFireJoin(this.instanceId, this.identifier, params));
+  }
+
+  firePause(params: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFirePause(this.instanceId, this.identifier, params));
+  }
+
+  fireResume(params: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFireResume(this.instanceId, this.identifier, params));
+  }
+
+  fireSeekBegin(params: ForgeParams = {}, options: { convertFromBuffer?: boolean } = {}): Promise<ForgeOutcome> {
+    return asOutcome(
+      NativeNPAWForge.videoFireSeekBegin(
+        this.instanceId,
+        this.identifier,
+        params,
+        options.convertFromBuffer ?? false
+      )
+    );
+  }
+
+  fireSeekEnd(params: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFireSeekEnd(this.instanceId, this.identifier, params));
+  }
+
+  fireBufferBegin(params: ForgeParams = {}, options: { convertFromSeek?: boolean } = {}): Promise<ForgeOutcome> {
+    return asOutcome(
+      NativeNPAWForge.videoFireBufferBegin(
+        this.instanceId,
+        this.identifier,
+        params,
+        options.convertFromSeek ?? false
+      )
+    );
+  }
+
+  fireBufferEnd(params: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFireBufferEnd(this.instanceId, this.identifier, params));
+  }
+
+  fireStop(params: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFireStop(this.instanceId, this.identifier, params));
+  }
+
+  fireError(errorCode?: string, errorMessage?: string, errorMetadata?: string): Promise<ForgeOutcome> {
+    return asOutcome(
+      NativeNPAWForge.videoFireError(
+        this.instanceId,
+        this.identifier,
+        errorCode ?? '',
+        errorMessage ?? '',
+        errorMetadata ?? ''
+      )
+    );
+  }
+
+  fireFatalError(errorCode?: string, errorMessage?: string, errorMetadata?: string): Promise<ForgeOutcome> {
+    return asOutcome(
+      NativeNPAWForge.videoFireFatalError(
+        this.instanceId,
+        this.identifier,
+        errorCode ?? '',
+        errorMessage ?? '',
+        errorMetadata ?? ''
+      )
+    );
+  }
+
+  fireDestroy(): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFireDestroy(this.instanceId, this.identifier));
+  }
+
+  fireEvent(
+    eventName: string,
+    dimensions: Record<string, string> = {},
+    values: Record<string, number> = {},
+    topLevelDimensions: Record<string, string> = {},
+    options: { hasEndDatetime?: boolean } = {}
+  ): Promise<ForgeOutcome> {
+    return asOutcome(
+      NativeNPAWForge.videoFireEvent(
+        this.instanceId,
+        this.identifier,
+        eventName,
+        dimensions,
+        values,
+        topLevelDimensions,
+        options.hasEndDatetime ?? false
+      )
+    );
+  }
+
+  fireEventEnd(
+    eventName: string,
+    dimensions: Record<string, string> = {},
+    values: Record<string, number> = {},
+    topLevelDimensions: Record<string, string> = {}
+  ): Promise<ForgeOutcome> {
+    return asOutcome(
+      NativeNPAWForge.videoFireEventEnd(
+        this.instanceId,
+        this.identifier,
+        eventName,
+        dimensions,
+        values,
+        topLevelDimensions
+      )
+    );
+  }
+
+  /** Manual metadata refresh (the native facade owns the snapshot semantics). */
+  fireMetadataUpdate(): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoFireMetadataUpdate(this.instanceId, this.identifier));
+  }
+
+  async createAdReporter(adapterVersion?: string): Promise<ForgeAdReporter> {
+    const reporterId = await NativeNPAWForge.createAdReporter(
+      this.instanceId,
+      this.identifier,
+      adapterVersion ?? ''
+    );
+    return new ForgeAdReporter(reporterId);
+  }
+
+  /** Destroys the kernel video view and every native resource behind it. */
+  destroy(): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.videoDestroy(this.instanceId, this.identifier));
+  }
+}

package/src/NPAWForge.ts

@@ -0,0 +1,177 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Main @npaw/forge-react-native facade class - sessions, identity, raw/business events, network records, diagnostics, video handles, kernel event feed.
+ */
+
+import NativeNPAWForge from './specs/NativeNPAWForge';
+import { ForgeVideo } from './ForgeVideo';
+import { subscribeInstanceEvents } from './events';
+import type {
+  ForgeConfig,
+  ForgeEventSubscription,
+  ForgeNetworkRequestRecord,
+  ForgeOutcome,
+  ForgeParams,
+  ForgeRecordedEvent,
+  ForgeVideoOptions,
+} from './types';
+
+export const DEFAULT_VIDEO_IDENTIFIER = 'default';
+
+function asOutcome(value: Promise<unknown>): Promise<ForgeOutcome> {
+  return value as Promise<ForgeOutcome>;
+}
+
+export class NPAWForge {
+  private constructor(readonly instanceId: string) {}
+
+  /** Builds a Forge instance; resolves once the native runtime is live. */
+  static async create(accountCode: string, config: ForgeConfig = {}): Promise<NPAWForge> {
+    const instanceId = await NativeNPAWForge.create(accountCode, config);
+    return new NPAWForge(instanceId);
+  }
+
+  // ---- lifecycle ----
+
+  destroy(): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.destroy(this.instanceId));
+  }
+
+  setLogLevel(level: string): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.setLogLevel(this.instanceId, level));
+  }
+
+  // ---- app session ----
+
+  startSession(metadata: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.startSession(this.instanceId, metadata));
+  }
+
+  endSession(metadata: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.endSession(this.instanceId, metadata));
+  }
+
+  trackSessionNavigation(metadata: ForgeParams): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackSessionNavigation(this.instanceId, metadata));
+  }
+
+  trackSessionEvent(name: string, metadata: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackSessionEvent(this.instanceId, name, metadata));
+  }
+
+  trackSessionEventStop(name: string, metadata: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackSessionEventStop(this.instanceId, name, metadata));
+  }
+
+  trackSessionError(errorCode: string, errorMessage: string, metadata: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackSessionError(this.instanceId, errorCode, errorMessage, metadata));
+  }
+
+  // ---- identity ----
+
+  loginSuccess(userId: string, options: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.loginSuccess(this.instanceId, userId, options));
+  }
+
+  loginFailed(options: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.loginFailed(this.instanceId, options));
+  }
+
+  logout(options: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.logout(this.instanceId, options));
+  }
+
+  profileCreated(profileId: string, options: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.profileCreated(this.instanceId, profileId, options));
+  }
+
+  profileSelected(profileId: string, options: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.profileSelected(this.instanceId, profileId, options));
+  }
+
+  profileDeleted(profileId: string): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.profileDeleted(this.instanceId, profileId));
+  }
+
+  // ---- raw / business ----
+
+  trackRawEvent(name: string, params: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackRawEvent(this.instanceId, name, params));
+  }
+
+  trackSearch(query: string, resultCount?: number): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackSearch(this.instanceId, query, resultCount ?? -1));
+  }
+
+  trackSearchResultClick(query: string, options: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackSearchResultClick(this.instanceId, query, options));
+  }
+
+  trackBusinessEvent(name: string, attributes: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackBusinessEvent(this.instanceId, name, attributes));
+  }
+
+  trackAttribution(options: ForgeParams = {}): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackAttribution(this.instanceId, options));
+  }
+
+  // ---- network ----
+
+  trackNetworkRequest(record: ForgeNetworkRequestRecord): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.trackNetworkRequest(this.instanceId, record));
+  }
+
+  /**
+   * Installs automatic network capture (Android: RN OkHttp factory
+   * instrumentation, call before the app's first fetch; iOS: URLSession
+   * swizzling). The kernel capture plan still gates what propagates.
+   */
+  installNetworkCapture(): Promise<ForgeOutcome> {
+    return asOutcome(NativeNPAWForge.installNetworkCapture(this.instanceId, {}));
+  }
+
+  // ---- diagnostics / events ----
+
+  async snapshotEvents(): Promise<ForgeRecordedEvent[]> {
+    const result = (await NativeNPAWForge.snapshotEvents(this.instanceId)) as {
+      items: ForgeRecordedEvent[];
+    };
+    return result.items;
+  }
+
+  /** Live feed of every event the kernel records for this instance. */
+  onEvent(callback: (event: ForgeRecordedEvent) => void): ForgeEventSubscription {
+    return subscribeInstanceEvents(this.instanceId, callback);
+  }
+
+  // ---- video ----
+
+  /**
+   * Creates (or reuses, per native same-identifier replacement semantics) a
+   * video handle. Options flow through the native VideoOptions metadata
+   * pipeline (web-parity key naming).
+   */
+  async createVideo(
+    options: ForgeVideoOptions = {},
+    identifier: string = DEFAULT_VIDEO_IDENTIFIER
+  ): Promise<ForgeVideo> {
+    await NativeNPAWForge.createVideo(this.instanceId, identifier, options);
+    return new ForgeVideo(this.instanceId, identifier);
+  }
+
+  /** Returns a handle to an existing video without creating it natively. */
+  video(identifier: string = DEFAULT_VIDEO_IDENTIFIER): ForgeVideo {
+    return new ForgeVideo(this.instanceId, identifier);
+  }
+}
+
+export default NPAWForge;

package/src/capture.ts

@@ -0,0 +1,192 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: RN-side capture helpers - JS error/unhandled-rejection observer (native crashes stay native) and screen-view tracking with Web-parity payload keys, plus a react-navigation onStateChange helper.
+ */
+
+import type { NPAWForge } from './NPAWForge';
+import type { ForgeEventSubscription } from './types';
+
+type GlobalErrorHandler = (error: unknown, isFatal?: boolean) => void;
+
+type ErrorUtilsLike = {
+  getGlobalHandler: () => GlobalErrorHandler;
+  setGlobalHandler: (handler: GlobalErrorHandler) => void;
+};
+
+type RejectionTrackingModule = {
+  enable: (options: {
+    allRejections: boolean;
+    onUnhandled: (id: number, rejection: unknown) => void;
+    onHandled?: (id: number) => void;
+  }) => void;
+  disable: () => void;
+};
+
+export type ErrorCaptureOptions = {
+  /** Also observe unhandled promise rejections. Default true. */
+  trackUnhandledRejections?: boolean;
+};
+
+const STACK_LIMIT_CHARS = 8 * 1024; // kernel caps at 8 KiB; pre-trim the JS copy
+
+function describeError(error: unknown): { code: string; message: string; stack?: string } {
+  if (error instanceof Error) {
+    return {
+      code: error.name || 'Error',
+      message: error.message || String(error),
+      stack: error.stack ? error.stack.slice(0, STACK_LIMIT_CHARS) : undefined,
+    };
+  }
+  return { code: 'Error', message: String(error) };
+}
+
+/**
+ * W1: JS error visibility. Native crashes are already captured by the native
+ * SDKs; JS exceptions and unhandled rejections are invisible natively, so
+ * this observer forwards them through the typed session-error path. The
+ * previous global handler keeps running (RedBox/LogBox in dev, crash
+ * semantics in release are unchanged).
+ */
+export function installErrorCapture(
+  forge: NPAWForge,
+  options: ErrorCaptureOptions = {}
+): ForgeEventSubscription {
+  const globalObject = globalThis as {
+    ErrorUtils?: ErrorUtilsLike;
+    HermesInternal?: unknown;
+  };
+  const errorUtils = globalObject.ErrorUtils;
+  let removed = false;
+  let previousHandler: GlobalErrorHandler | undefined;
+
+  if (errorUtils) {
+    previousHandler = errorUtils.getGlobalHandler();
+    errorUtils.setGlobalHandler((error, isFatal) => {
+      if (!removed) {
+        const described = describeError(error);
+        void forge
+          .trackSessionError(described.code, described.message, {
+            source: 'react_native_capture',
+            fatal: isFatal ? 'true' : 'false',
+            ...(described.stack ? { stack: described.stack } : {}),
+          })
+          .catch(() => {});
+      }
+      previousHandler?.(error, isFatal);
+    });
+  }
+
+  let rejectionTrackingEnabled = false;
+  if (options.trackUnhandledRejections !== false) {
+    try {
+      // The promise polyfill RN installs ships rejection tracking here.
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const tracking: RejectionTrackingModule = require('promise/setimmediate/rejection-tracking');
+      tracking.enable({
+        allRejections: true,
+        onUnhandled: (_id, rejection) => {
+          if (removed) {
+            return;
+          }
+          const described = describeError(rejection);
+          void forge
+            .trackSessionError('UnhandledPromiseRejection', described.message, {
+              source: 'react_native_capture',
+              fatal: 'false',
+              ...(described.stack ? { stack: described.stack } : {}),
+            })
+            .catch(() => {});
+        },
+      });
+      rejectionTrackingEnabled = true;
+    } catch {
+      rejectionTrackingEnabled = false;
+    }
+  }
+
+  return {
+    remove: () => {
+      removed = true;
+      if (errorUtils && previousHandler) {
+        errorUtils.setGlobalHandler(previousHandler);
+      }
+      // Rejection tracking stays enabled (it delegates to the default
+      // logger); the removed flag stops Forge forwarding.
+      void rejectionTrackingEnabled;
+    },
+  };
+}
+
+export type ScreenViewOptions = {
+  /** Parameterized route shape, e.g. '/movie/:id'. Defaults to the name. */
+  routeTemplate?: string;
+};
+
+const lastScreenByInstance = new Map<string, { route: string; page: string }>();
+
+/**
+ * W2: manual screen views. Mirrors the Web navigation capture pair: a typed
+ * trackSessionNavigation plus the raw_screen_view raw event with the same
+ * payload keys (route/page/previousRoute/previousPage/routeTemplate/
+ * launchSource), so RN screens land in the same dashboards.
+ */
+export async function trackScreenView(
+  forge: NPAWForge,
+  screenName: string,
+  options: ScreenViewOptions = {}
+): Promise<void> {
+  const route = screenName.startsWith('/') ? screenName : `/${screenName}`;
+  const previous = lastScreenByInstance.get(forge.instanceId);
+  const launchSource = previous ? 'normal' : 'launch';
+  lastScreenByInstance.set(forge.instanceId, { route, page: screenName });
+
+  await forge.trackSessionNavigation({
+    route,
+    page: screenName,
+    source: 'react_native_capture',
+  });
+  await forge.trackRawEvent('raw_screen_view', {
+    route,
+    page: screenName,
+    ...(previous ? { previousRoute: previous.route, previousPage: previous.page } : {}),
+    routeTemplate: options.routeTemplate ?? route,
+    launchSource,
+  });
+}
+
+type NavigationStateLike = {
+  routes?: Array<{ name?: string }>;
+  index?: number;
+};
+
+/**
+ * react-navigation glue: pass the returned function to
+ * NavigationContainer's onStateChange (and call it once with the initial
+ * state from onReady).
+ */
+export function createNavigationObserver(
+  forge: NPAWForge
+): (state: NavigationStateLike | undefined) => void {
+  let lastName: string | undefined;
+  return state => {
+    const route =
+      state && Array.isArray(state.routes) && typeof state.index === 'number'
+        ? state.routes[state.index]
+        : undefined;
+    const name = route?.name;
+    if (!name || name === lastName) {
+      return;
+    }
+    lastName = name;
+    void trackScreenView(forge, name).catch(() => {});
+  };
+}

package/src/events.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Kernel event feed wiring - single NativeEventEmitter channel shared by every Forge instance, filtered per instance id.
+ */
+
+import { NativeEventEmitter, NativeModules } from 'react-native';
+import NativeNPAWForge from './specs/NativeNPAWForge';
+import type { ForgeEventSubscription, ForgeRecordedEvent } from './types';
+
+export const FORGE_EVENT_CHANNEL = 'NPAWForgeEvent';
+
+const emitter = new NativeEventEmitter(
+  // The spec module implements addListener/removeListeners; iOS needs the
+  // module object itself for the classic emitter contract.
+  NativeModules.NPAWForgeRN ?? (NativeNPAWForge as never)
+);
+
+export function subscribeInstanceEvents(
+  instanceId: string,
+  callback: (event: ForgeRecordedEvent) => void
+): ForgeEventSubscription {
+  const subscription = emitter.addListener(
+    FORGE_EVENT_CHANNEL,
+    (event: ForgeRecordedEvent) => {
+      if (event.instanceId === instanceId) {
+        callback(event);
+      }
+    }
+  );
+  return { remove: () => subscription.remove() };
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Public exports for @npaw/forge-react-native.
+ */
+
+export { NPAWForge, DEFAULT_VIDEO_IDENTIFIER } from './NPAWForge';
+export { ForgeVideo } from './ForgeVideo';
+export { ForgeAdReporter } from './ForgeAdReporter';
+export { FORGE_EVENT_CHANNEL } from './events';
+export {
+  installErrorCapture,
+  trackScreenView,
+  createNavigationObserver,
+} from './capture';
+export type { ErrorCaptureOptions, ScreenViewOptions } from './capture';
+export type {
+  ForgeConfig,
+  ForgeEventSubscription,
+  ForgeNetworkOutcome,
+  ForgeNetworkRequestRecord,
+  ForgeOutcome,
+  ForgeOutcomeCode,
+  ForgeParams,
+  ForgeRecordedEvent,
+  ForgeVideoOptions,
+} from './types';
+
+export { NPAWForge as default } from './NPAWForge';