@npaw/forge-react-native 9.6.1

package/src/specs/NativeNPAWForge.ts

@@ -0,0 +1,168 @@
+/**
+ * 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: TurboModule codegen spec for the NPAW Forge core React Native module - full facade surface, 1:1 with the native Kotlin/Swift NPAWForge facades. Timestamp-free by repo policy; Forge Core assigns event time.
+ */
+
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+import type { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
+
+export interface Spec extends TurboModule {
+  // ---- lifecycle ----
+  create(accountCode: string, config: UnsafeObject): Promise<string>;
+  destroy(instanceId: string): Promise<UnsafeObject>;
+  setLogLevel(instanceId: string, level: string): Promise<UnsafeObject>;
+
+  // ---- app session ----
+  startSession(instanceId: string, metadata: UnsafeObject): Promise<UnsafeObject>;
+  endSession(instanceId: string, metadata: UnsafeObject): Promise<UnsafeObject>;
+  trackSessionNavigation(instanceId: string, metadata: UnsafeObject): Promise<UnsafeObject>;
+  trackSessionEvent(instanceId: string, name: string, metadata: UnsafeObject): Promise<UnsafeObject>;
+  trackSessionEventStop(instanceId: string, name: string, metadata: UnsafeObject): Promise<UnsafeObject>;
+  trackSessionError(
+    instanceId: string,
+    errorCode: string,
+    errorMessage: string,
+    metadata: UnsafeObject
+  ): Promise<UnsafeObject>;
+
+  // ---- identity ----
+  loginSuccess(instanceId: string, userId: string, options: UnsafeObject): Promise<UnsafeObject>;
+  loginFailed(instanceId: string, options: UnsafeObject): Promise<UnsafeObject>;
+  logout(instanceId: string, options: UnsafeObject): Promise<UnsafeObject>;
+  profileCreated(instanceId: string, profileId: string, options: UnsafeObject): Promise<UnsafeObject>;
+  profileSelected(instanceId: string, profileId: string, options: UnsafeObject): Promise<UnsafeObject>;
+  profileDeleted(instanceId: string, profileId: string): Promise<UnsafeObject>;
+
+  // ---- raw / business ----
+  trackRawEvent(instanceId: string, name: string, params: UnsafeObject): Promise<UnsafeObject>;
+  /** resultCount < 0 means "not provided". */
+  trackSearch(instanceId: string, query: string, resultCount: number): Promise<UnsafeObject>;
+  trackSearchResultClick(instanceId: string, query: string, options: UnsafeObject): Promise<UnsafeObject>;
+  trackBusinessEvent(instanceId: string, name: string, attributes: UnsafeObject): Promise<UnsafeObject>;
+  trackAttribution(instanceId: string, options: UnsafeObject): Promise<UnsafeObject>;
+
+  // ---- network (manual record) ----
+  trackNetworkRequest(instanceId: string, record: UnsafeObject): Promise<UnsafeObject>;
+  /**
+   * Installs automatic network capture: Android instruments React Native's
+   * OkHttp client factory (call before the first fetch), iOS arms the
+   * URLSession swizzler. Capture-plan gating stays kernel-owned.
+   */
+  installNetworkCapture(instanceId: string, options: UnsafeObject): Promise<UnsafeObject>;
+
+  // ---- diagnostics ----
+  snapshotEvents(instanceId: string): Promise<UnsafeObject>;
+
+  // ---- video (identifier-keyed; 'default' is the native default identifier) ----
+  createVideo(instanceId: string, identifier: string, options: UnsafeObject): Promise<UnsafeObject>;
+  videoDestroy(instanceId: string, identifier: string): Promise<UnsafeObject>;
+  videoFireInit(instanceId: string, identifier: string, params: UnsafeObject): Promise<UnsafeObject>;
+  videoFireStart(
+    instanceId: string,
+    identifier: string,
+    params: UnsafeObject,
+    forceInit: boolean
+  ): Promise<UnsafeObject>;
+  videoFireJoin(instanceId: string, identifier: string, params: UnsafeObject): Promise<UnsafeObject>;
+  videoFirePause(instanceId: string, identifier: string, params: UnsafeObject): Promise<UnsafeObject>;
+  videoFireResume(instanceId: string, identifier: string, params: UnsafeObject): Promise<UnsafeObject>;
+  videoFireSeekBegin(
+    instanceId: string,
+    identifier: string,
+    params: UnsafeObject,
+    convertFromBuffer: boolean
+  ): Promise<UnsafeObject>;
+  videoFireSeekEnd(instanceId: string, identifier: string, params: UnsafeObject): Promise<UnsafeObject>;
+  videoFireBufferBegin(
+    instanceId: string,
+    identifier: string,
+    params: UnsafeObject,
+    convertFromSeek: boolean
+  ): Promise<UnsafeObject>;
+  videoFireBufferEnd(instanceId: string, identifier: string, params: UnsafeObject): Promise<UnsafeObject>;
+  videoFireStop(instanceId: string, identifier: string, params: UnsafeObject): Promise<UnsafeObject>;
+  /** Empty strings mean "not provided" for the error fields. */
+  videoFireError(
+    instanceId: string,
+    identifier: string,
+    errorCode: string,
+    errorMessage: string,
+    errorMetadata: string
+  ): Promise<UnsafeObject>;
+  videoFireFatalError(
+    instanceId: string,
+    identifier: string,
+    errorCode: string,
+    errorMessage: string,
+    errorMetadata: string
+  ): Promise<UnsafeObject>;
+  videoFireDestroy(instanceId: string, identifier: string): Promise<UnsafeObject>;
+  videoFireEvent(
+    instanceId: string,
+    identifier: string,
+    eventName: string,
+    dimensions: UnsafeObject,
+    values: UnsafeObject,
+    topLevelDimensions: UnsafeObject,
+    hasEndDatetime: boolean
+  ): Promise<UnsafeObject>;
+  videoFireEventEnd(
+    instanceId: string,
+    identifier: string,
+    eventName: string,
+    dimensions: UnsafeObject,
+    values: UnsafeObject,
+    topLevelDimensions: UnsafeObject
+  ): Promise<UnsafeObject>;
+  /** Manual metadata refresh; the params-driven variant is not exposed by the native facade. */
+  videoFireMetadataUpdate(instanceId: string, identifier: string): Promise<UnsafeObject>;
+
+  // ---- ads (numeric reporter handles) ----
+  /** Empty adapterVersion means "not provided". Resolves the reporter handle. */
+  createAdReporter(instanceId: string, identifier: string, adapterVersion: string): Promise<number>;
+  releaseAdReporter(reporterId: number): Promise<UnsafeObject>;
+  adFireManifest(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireBreakStart(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireAdInit(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireStart(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireJoin(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFirePause(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireResume(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireBufferBegin(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireBufferEnd(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  /** quartile < 0 means "not provided". */
+  adFireQuartile(reporterId: number, quartile: number): Promise<UnsafeObject>;
+  adFireClick(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireSkip(reporterId: number): Promise<UnsafeObject>;
+  adFireStop(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireError(
+    reporterId: number,
+    errorCode: string,
+    errorMessage: string,
+    errorMetadata: string
+  ): Promise<UnsafeObject>;
+  adFireFatalError(
+    reporterId: number,
+    errorCode: string,
+    errorMessage: string,
+    errorMetadata: string
+  ): Promise<UnsafeObject>;
+  adFireBreakStop(reporterId: number, params: UnsafeObject): Promise<UnsafeObject>;
+  adFireDestroy(reporterId: number): Promise<UnsafeObject>;
+
+  // ---- event feed (classic emitter contract) ----
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('NPAWForgeRN');

package/src/types.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 TypeScript types for @npaw/forge-react-native (outcomes, config, events, video options, network records).
+ */
+
+/** Wire-parity outcome codes shared by every Forge platform facade. */
+export type ForgeOutcomeCode =
+  | 'accepted'
+  | 'deferred'
+  | 'dropped'
+  | 'ignored_duplicate'
+  | 'ignored_before_session_start'
+  | 'ignored_invalid_state'
+  | 'blocked_dependency'
+  | 'unsupported_capability'
+  | 'failed_with_diagnostic';
+
+export type ForgeOutcome = {
+  code: ForgeOutcomeCode;
+  isAccepted: boolean;
+  /** Present on failed_with_diagnostic. */
+  reason?: string;
+  /** Present on failed_with_diagnostic. */
+  details?: Record<string, string>;
+};
+
+/** One kernel-recorded event from the bounded native snapshot mirror. */
+export type ForgeRecordedEvent = {
+  instanceId: string;
+  eventName: string;
+  timestampMs: number;
+  payload: Record<string, string>;
+  urgent: boolean;
+  viewKey?: string;
+};
+
+/**
+ * Instance configuration. One canonical key per concept (legacy facade
+ * aliases are intentionally not exposed); unknown keys are warn-and-ignore
+ * on the native side for forward compatibility.
+ *
+ * iOS note: deviceUuid and autoDeviceIdentityEnabled are Android-only today
+ * (the Swift Builder lacks the setters); iOS logs and ignores them.
+ */
+export type ForgeConfig = {
+  appName?: string;
+  appReleaseVersion?: string;
+  buildVariant?: string;
+  lmaEndpoint?: string;
+  analyticsUserAgent?: string;
+  logLevel?: string;
+  startSessionOnInitialize?: boolean;
+  processEventsBeforeSessionStart?: boolean;
+  preSessionEventQueueLimitEvents?: number;
+  preSessionEventQueueMaxAgeMs?: number;
+  allowLocalHttpForTesting?: boolean;
+  deviceUuid?: string;
+  autoDeviceIdentityEnabled?: boolean;
+};
+
+/**
+ * Video options DTO. Every key is forwarded through the native
+ * VideoOptions.Builder metadata pipeline, which applies the same
+ * key-normalization/alias rules as the Web binding (content.title,
+ * contentDuration, playhead, custom dimension dotted keys, ...), so option
+ * naming is web-parity by construction. Values are stringified.
+ */
+export type ForgeVideoOptions = Record<string, string | number | boolean>;
+
+/** String facts for manual fire* calls; values are stringified natively. */
+export type ForgeParams = Record<string, string | number | boolean>;
+
+export type ForgeNetworkOutcome =
+  | 'success'
+  | 'http_error'
+  | 'network_error'
+  | 'cancelled'
+  | 'timeout'
+  | 'blocked'
+  | 'unknown';
+
+/** Manual network observation, mapped onto the native NetworkRequestRecord. */
+export type ForgeNetworkRequestRecord = {
+  targetUrl: string;
+  method: string;
+  responseStatusCode: number;
+  durationMs: number;
+  outcome: ForgeNetworkOutcome;
+  responseStatusText?: string;
+  errorMessage?: string;
+  traceparent?: string;
+  dnsDurationMs?: number;
+  connectDurationMs?: number;
+  sslDurationMs?: number;
+  requestDurationMs?: number;
+  timeToFirstByteMs?: number;
+  responseDownloadDurationMs?: number;
+  redirectDurationMs?: number;
+  redirectCount?: number;
+  protocol?: string;
+  requestBytes?: number;
+  responseBytes?: number;
+};
+
+export type ForgeEventSubscription = { remove: () => void };