react-native-nitro-amplitude 0.2.0 → 0.5.0

package/lib/typescript/testing.d.ts

@@ -0,0 +1,11 @@
+import type { AmplitudeReactNativeClient } from "./analytics/react-native-client";
+import type { Client } from "./experiment/types/client";
+import type { Storage } from "./experiment/types/storage";
+import type { Variants } from "./experiment/types/variant";
+export type FakeExperimentStorage = Storage & {
+    values: Map<string, string>;
+};
+export declare function createFakeExperimentStorage(initialValues?: Record<string, string>): FakeExperimentStorage;
+export declare function createMockAmplitudeClient(): AmplitudeReactNativeClient;
+export declare function createMockExperimentClient(initialVariants?: Variants): Client;
+//# sourceMappingURL=testing.d.ts.map

package/lib/typescript/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,KAAK,EAAW,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AA8BpE,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG;IAC5C,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,CAAC;AAEF,wBAAgB,2BAA2B,CACzC,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACzC,qBAAqB,CAevB;AAED,wBAAgB,yBAAyB,IAAI,0BAA0B,CA8DtE;AAED,wBAAgB,0BAA0B,CACxC,eAAe,GAAE,QAAa,GAC7B,MAAM,CAoDR"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-amplitude",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Amplitude Analytics and Experiment SDK for React Native powered by Nitro Modules and C++ on native platforms, with web-compatible fetch and storage fallbacks.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/analytics/config.ts

@@ -11,13 +11,33 @@ import {
   CookieStorage,
   getCookieName,
   getQueryParams,
-  FetchTransport,
 } from "@amplitude/analytics-core";
+import type { Transport } from "@amplitude/analytics-core";
 
 import { LocalStorage } from "./storage/local-storage";
 import RemnantDataMigration from "./migration/remnant-data-migration";
-import { NitroAnalyticsStorage } from "../native/storage";
-import { nitroTransport } from "./nitro-transport";
+import { isNative } from "./utils/platform";
+import { NetworkGuardedFetchTransport } from "./network-guarded-fetch-transport";
+
+function createDefaultStorage() {
+  if (isNative()) {
+    const { NitroAnalyticsStorage } =
+      require("../native/storage") as typeof import("../native/storage");
+    return new NitroAnalyticsStorage<Event[]>("analytics-events");
+  }
+  const { NitroAnalyticsStorage } =
+    require("../native/storage.web") as typeof import("../native/storage");
+  return new NitroAnalyticsStorage<Event[]>("analytics-events");
+}
+
+function getDefaultTransport(): Transport {
+  if (isNative()) {
+    const { nitroTransport } =
+      require("./nitro-transport") as typeof import("./nitro-transport");
+    return nitroTransport;
+  }
+  return new NetworkGuardedFetchTransport();
+}
 
 export const getDefaultConfig = () => {
   const cookieStorage = new MemoryStorage<UserSession>();
@@ -44,10 +64,10 @@ export const getDefaultConfig = () => {
     disableCookies: true,
     domain: "",
     sessionTimeout: 5 * 60 * 1000,
-    storageProvider: new NitroAnalyticsStorage<Event[]>("analytics-events"),
+    storageProvider: createDefaultStorage(),
     trackingSessionEvents: false,
     trackingOptions,
-    transportProvider: nitroTransport,
+    transportProvider: getDefaultTransport(),
   };
 };
 
@@ -79,9 +99,10 @@ export class ReactNativeConfig extends Config implements IReactNativeConfig {
       flushIntervalMillis: 1000,
       flushMaxRetries: 5,
       flushQueueSize: 30,
-      transportProvider: defaultConfig.transportProvider,
       ...options,
       apiKey,
+      transportProvider:
+        options?.transportProvider ?? defaultConfig.transportProvider,
     });
 
     // NOTE: Define `cookieStorage` first to persist user session
@@ -233,7 +254,8 @@ export const useReactNativeConfig = async (
   let lastEventId = previousCookies?.lastEventId;
 
   const storageProvider =
-    options?.storageProvider ?? (await createEventsStorage(options));
+    options?.storageProvider ??
+    (await createEventsStorage(options, defaultConfig));
 
   if (options?.migrateLegacyData !== false) {
     const legacySessionData = await new RemnantDataMigration(
@@ -263,7 +285,8 @@ export const useReactNativeConfig = async (
       ...defaultConfig.trackingOptions,
       ...options?.trackingOptions,
     },
-    transportProvider: options?.transportProvider ?? new FetchTransport(),
+    transportProvider:
+      options?.transportProvider ?? defaultConfig.transportProvider,
     userId,
   });
 
@@ -319,6 +342,7 @@ const createFlexibleStorage = async <T>(
 
 export const createEventsStorage = async (
   overrides?: ReactNativeOptions,
+  baseConfig = getDefaultConfig(),
 ): Promise<Storage<Event[]> | undefined> => {
   const hasStorageProviderProperty =
     overrides &&
@@ -331,6 +355,7 @@ export const createEventsStorage = async (
   if (!hasStorageProviderProperty || overrides.storageProvider) {
     for (const storage of [
       overrides?.storageProvider,
+      hasStorageProviderProperty ? undefined : baseConfig.storageProvider,
       new LocalStorage<Event[]>(),
     ]) {
       if (storage && (await storage.isEnabled())) {

package/src/analytics/index.ts

@@ -25,6 +25,9 @@ export const {
   shutdown,
   track,
   extendSession,
+  flushWithResult,
+  getDiagnostics,
+  healthCheck,
 } = client;
 
 export { Revenue, Identify } from "@amplitude/analytics-core";

package/src/analytics/network-guarded-fetch-transport.ts

@@ -0,0 +1,10 @@
+import { FetchTransport } from "@amplitude/analytics-core";
+import type { Payload, Response } from "@amplitude/analytics-core";
+import { assertNetworkEnabled } from "../network";
+
+export class NetworkGuardedFetchTransport extends FetchTransport {
+  async send(serverUrl: string, payload: Payload): Promise<Response | null> {
+    assertNetworkEnabled();
+    return await super.send(serverUrl, payload);
+  }
+}

package/src/analytics/nitro-transport.ts

@@ -1,6 +1,7 @@
 import { BaseTransport } from "@amplitude/analytics-core";
 import type { Payload, Response, Transport } from "@amplitude/analytics-core";
 import { nitroHttpClient } from "../native/http";
+import { assertNetworkEnabled } from "../network";
 
 export class NitroTransport extends BaseTransport implements Transport {
   private readonly customHeaders: Record<string, string>;
@@ -11,6 +12,7 @@ export class NitroTransport extends BaseTransport implements Transport {
   }
 
   async send(serverUrl: string, payload: Payload): Promise<Response | null> {
+    assertNetworkEnabled();
     const response = await nitroHttpClient.request(
       serverUrl,
       "POST",

package/src/analytics/plugins/context.ts

@@ -60,6 +60,8 @@ export class Context implements BeforePlugin {
   config: ReactNativeConfig;
   uaResult: UAParser.IResult;
   library = `amplitude-nitro-ts/${VERSION}`;
+  private nativeContext: NativeContext | undefined;
+  private nativeContextLoaded = false;
 
   constructor() {
     let agent: string | undefined;
@@ -77,8 +79,15 @@ export class Context implements BeforePlugin {
   }
 
   private getNativeContext(): NativeContext | undefined {
+    if (this.nativeContextLoaded) {
+      return this.nativeContext;
+    }
+    this.nativeContextLoaded = true;
     try {
-      return getNativeApplicationContext(this.config.trackingOptions);
+      this.nativeContext = getNativeApplicationContext(
+        this.config.trackingOptions,
+      );
+      return this.nativeContext;
     } catch (error) {
       this.config.loggerProvider?.error(
         `Failed to load native application context: ${String(error)}`,

package/src/analytics/react-native-client.ts

@@ -27,6 +27,7 @@ import {
   SpecialEventType,
   AnalyticsClient,
 } from "@amplitude/analytics-core";
+import { healthCheck } from "../diagnostics";
 import { CampaignTracker } from "./campaign/campaign-tracker";
 import { Context } from "./plugins/context";
 import { useReactNativeConfig, createCookieStorage } from "./config";
@@ -41,15 +42,61 @@ type ScheduledDestination = {
   flushId?: ReturnType<typeof setTimeout> | null;
   queue?: unknown[];
   resetSchedule?: () => void;
+  fulfillRequest?: (list: unknown[], code: number, message: string) => unknown;
+};
+
+type FlushOutcome = {
+  code: number;
+  count: number;
+  message: string;
 };
 
 export type AmplitudeReactNativeClient = ReactNativeClient & {
   shutdown: () => void;
+  flushWithResult: () => Promise<AmplitudeFlushResult>;
+  getDiagnostics: () => AmplitudeAnalyticsDiagnostics;
+  healthCheck: () => Promise<AmplitudeHealthCheckResult>;
+};
+
+export type AmplitudeFlushResult = {
+  ok: boolean;
+  sent: number;
+  failed: number;
+  dropped: number;
+  retried: number;
+  reason?: string;
+  result?: Result;
+  finishedAt: number;
+};
+
+export type AmplitudeAnalyticsDiagnostics = {
+  initialized: boolean;
+  instanceName?: string;
+  userId?: string;
+  deviceId?: string;
+  sessionId?: number;
+  queueSize: number;
+  lastFlushTime?: number;
+  lastFlushDurationMillis?: number;
+  lastFlushError?: string;
+  activeInstanceNames: string[];
+};
+
+export type AmplitudeHealthCheckResult = {
+  ok: boolean;
+  analyticsInitialized: boolean;
+  nativeAvailable: boolean;
+  storageWritable: boolean;
+  errors: string[];
 };
 
 let nextConnectorOwnerId = 0;
 const activeConnectorOwnerIds = new Map<string, number>();
 
+export function getActiveAnalyticsInstanceNames(): string[] {
+  return Array.from(activeConnectorOwnerIds.keys()).sort();
+}
+
 export class AmplitudeReactNative
   extends AmplitudeCore
   implements ReactNativeClient, AnalyticsClient
@@ -58,6 +105,9 @@ export class AmplitudeReactNative
   private appStateChangeHandler: NativeEventSubscription | undefined;
   private initPromise: Promise<void> | undefined;
   private readonly connectorOwnerId = ++nextConnectorOwnerId;
+  private lastFlushTime: number | undefined;
+  private lastFlushDurationMillis: number | undefined;
+  private lastFlushError: string | undefined;
   explicitSessionId: number | undefined;
 
   // @ts-ignore
@@ -279,6 +329,95 @@ export class AmplitudeReactNative
     return this.config?.sessionId;
   }
 
+  async flushWithResult(): Promise<AmplitudeFlushResult> {
+    const queueSize = this.getQueueSize();
+    const collector = this.collectFlushOutcomes();
+    const startedAt = Date.now();
+    try {
+      await this.flush().promise;
+      const outcomes = collector.finish();
+      this.lastFlushTime = Date.now();
+      this.lastFlushDurationMillis = this.lastFlushTime - startedAt;
+      const remainingQueueSize = this.getQueueSize();
+      const failedOutcomes = outcomes.filter(
+        (outcome) => !this.isSuccessStatusCode(outcome.code),
+      );
+      const dropped = failedOutcomes.reduce(
+        (total, outcome) => total + outcome.count,
+        0,
+      );
+      if (remainingQueueSize > 0) {
+        this.lastFlushError = `Flush completed with ${remainingQueueSize} queued event(s) remaining`;
+        return {
+          ok: false,
+          sent: this.countSuccessfulOutcomes(outcomes),
+          failed: remainingQueueSize,
+          dropped,
+          retried: remainingQueueSize,
+          reason: this.lastFlushError,
+          finishedAt: this.lastFlushTime,
+        };
+      }
+      if (dropped > 0) {
+        this.lastFlushError =
+          failedOutcomes[0]?.message ??
+          `Flush dropped ${dropped} event(s) without retry`;
+        return {
+          ok: false,
+          sent: this.countSuccessfulOutcomes(outcomes),
+          failed: dropped,
+          dropped,
+          retried: 0,
+          reason: this.lastFlushError,
+          finishedAt: this.lastFlushTime,
+        };
+      }
+      this.lastFlushError = undefined;
+      return {
+        ok: true,
+        sent: this.countSuccessfulOutcomes(outcomes) || queueSize,
+        failed: 0,
+        dropped: 0,
+        retried: 0,
+        finishedAt: this.lastFlushTime,
+      };
+    } catch (error) {
+      collector.finish();
+      this.lastFlushTime = Date.now();
+      this.lastFlushDurationMillis = this.lastFlushTime - startedAt;
+      this.lastFlushError =
+        error instanceof Error ? error.message : String(error);
+      return {
+        ok: false,
+        sent: 0,
+        failed: queueSize,
+        dropped: 0,
+        retried: 0,
+        reason: this.lastFlushError,
+        finishedAt: this.lastFlushTime,
+      };
+    }
+  }
+
+  getDiagnostics(): AmplitudeAnalyticsDiagnostics {
+    return {
+      initialized: Boolean(this.config && this.isReady),
+      instanceName: this.config?.instanceName,
+      userId: this.getUserId(),
+      deviceId: this.getDeviceId(),
+      sessionId: this.getSessionId(),
+      queueSize: this.getQueueSize(),
+      lastFlushTime: this.lastFlushTime,
+      lastFlushDurationMillis: this.lastFlushDurationMillis,
+      lastFlushError: this.lastFlushError,
+      activeInstanceNames: getActiveAnalyticsInstanceNames(),
+    };
+  }
+
+  async healthCheck(): Promise<AmplitudeHealthCheckResult> {
+    return healthCheck(this);
+  }
+
   getIdentity() {
     return {
       userId: this.getUserId(),
@@ -309,6 +448,66 @@ export class AmplitudeReactNative
     this.config.lastEventTime = this.currentTimeMillis();
   }
 
+  private getQueueSize(): number {
+    let queueSize =
+      this.q.length + this.dispatchQ.length + this.timeline.queue.length;
+    this.timeline.plugins.forEach((plugin) => {
+      if (plugin.type !== "destination") {
+        return;
+      }
+      const destination = plugin as ScheduledDestination;
+      queueSize += destination.queue?.length ?? 0;
+    });
+    return queueSize;
+  }
+
+  private collectFlushOutcomes(): { finish: () => FlushOutcome[] } {
+    const outcomes: FlushOutcome[] = [];
+    const restorers: (() => void)[] = [];
+
+    this.timeline.plugins.forEach((plugin) => {
+      if (plugin.type !== "destination") {
+        return;
+      }
+
+      const destination = plugin as ScheduledDestination;
+      if (!destination.fulfillRequest) {
+        return;
+      }
+
+      const original = destination.fulfillRequest;
+      destination.fulfillRequest = (list, code, message) => {
+        outcomes.push({ code, count: list.length, message });
+        return original.call(destination, list, code, message);
+      };
+      restorers.push(() => {
+        destination.fulfillRequest = original;
+      });
+    });
+
+    return {
+      finish: () => {
+        while (restorers.length > 0) {
+          restorers.pop()?.();
+        }
+        return outcomes;
+      },
+    };
+  }
+
+  private countSuccessfulOutcomes(outcomes: FlushOutcome[]): number {
+    return outcomes.reduce((total, outcome) => {
+      if (!this.isSuccessStatusCode(outcome.code)) {
+        return total;
+      }
+      return total + outcome.count;
+    }, 0);
+  }
+
+  private isSuccessStatusCode(code: number): boolean {
+    return code >= 200 && code < 300;
+  }
+
   private setSessionIdInternal(sessionId: number, eventTime: number) {
     const previousSessionId = this.config.sessionId;
     if (previousSessionId === sessionId) {
@@ -519,6 +718,12 @@ export const createInstance = (): AmplitudeReactNativeClient => {
       getClientLogConfig(client),
       getClientStates(client, ["config.apiKey", "timeline.queue.length"]),
     ),
+    flushWithResult: debugWrapper(
+      client.flushWithResult.bind(client),
+      "flushWithResult",
+      getClientLogConfig(client),
+      getClientStates(client, ["config.apiKey", "timeline.queue.length"]),
+    ),
     getUserId: debugWrapper(
       client.getUserId.bind(client),
       "getUserId",
@@ -579,6 +784,18 @@ export const createInstance = (): AmplitudeReactNativeClient => {
       getClientLogConfig(client),
       getClientStates(client, ["config", "timeline.plugins"]),
     ),
+    getDiagnostics: debugWrapper(
+      client.getDiagnostics.bind(client),
+      "getDiagnostics",
+      getClientLogConfig(client),
+      getClientStates(client, ["config", "timeline.plugins"]),
+    ),
+    healthCheck: debugWrapper(
+      client.healthCheck.bind(client),
+      "healthCheck",
+      getClientLogConfig(client),
+      getClientStates(client, ["config", "timeline.plugins"]),
+    ),
   };
 };
 

package/src/diagnostics.ts

@@ -0,0 +1,119 @@
+import type {
+  AmplitudeAnalyticsDiagnostics,
+  AmplitudeHealthCheckResult,
+  AmplitudeReactNativeClient,
+} from "./analytics/react-native-client";
+import { isNative } from "./analytics/utils/platform";
+import { getAmplitudeErrorCode } from "./errors";
+import { getNetworkEnabled } from "./network";
+
+type HybridModule = typeof import("./native/hybrid");
+
+export type NativeStartupDiagnostics = {
+  nitroModulesAvailable: boolean;
+  contextAvailable: boolean;
+  storageAvailable: boolean;
+  workerAvailable: boolean;
+  nativeAvailable: boolean;
+  lastError?: {
+    code: string;
+    message: string;
+  };
+};
+
+export type AmplitudeDiagnostics = AmplitudeAnalyticsDiagnostics & {
+  native: NativeStartupDiagnostics;
+  networkEnabled: boolean;
+};
+
+let lastNativeError: NativeStartupDiagnostics["lastError"];
+
+function getHybridModule(): HybridModule {
+  if (isNative()) {
+    return require("./native/hybrid") as HybridModule;
+  }
+  return require("./native/hybrid.web") as HybridModule;
+}
+
+export function getLastNativeError(): NativeStartupDiagnostics["lastError"] {
+  return lastNativeError;
+}
+
+export function getNativeStartupDiagnostics(): NativeStartupDiagnostics {
+  const result: NativeStartupDiagnostics = {
+    nitroModulesAvailable: true,
+    contextAvailable: false,
+    storageAvailable: false,
+    workerAvailable: false,
+    nativeAvailable: false,
+    lastError: lastNativeError,
+  };
+
+  try {
+    const { getAmplitudeContext, getAmplitudeStorage, getAmplitudeWorker } =
+      getHybridModule();
+    getAmplitudeContext();
+    result.contextAvailable = true;
+    getAmplitudeStorage();
+    result.storageAvailable = true;
+    getAmplitudeWorker();
+    result.workerAvailable = true;
+    result.nativeAvailable = true;
+    lastNativeError = undefined;
+    result.lastError = undefined;
+  } catch (error) {
+    lastNativeError = {
+      code: getAmplitudeErrorCode(error),
+      message: error instanceof Error ? error.message : String(error),
+    };
+    result.nitroModulesAvailable = false;
+    result.lastError = lastNativeError;
+  }
+
+  return result;
+}
+
+export function getAmplitudeDiagnostics(
+  analytics: AmplitudeReactNativeClient,
+): AmplitudeDiagnostics {
+  return {
+    ...analytics.getDiagnostics(),
+    native: getNativeStartupDiagnostics(),
+    networkEnabled: getNetworkEnabled(),
+  };
+}
+
+export async function healthCheck(
+  analytics?: AmplitudeReactNativeClient,
+): Promise<AmplitudeHealthCheckResult> {
+  const errors: string[] = [];
+  const native = getNativeStartupDiagnostics();
+  let storageWritable = false;
+
+  try {
+    const { getAmplitudeStorage } = getHybridModule();
+    const storage = getAmplitudeStorage();
+    const key = `health::${Date.now()}`;
+    storage.set(key, "ok", false);
+    storageWritable = storage.get(key, false) === "ok";
+    storage.remove(key, false);
+  } catch (error) {
+    errors.push(error instanceof Error ? error.message : String(error));
+  }
+
+  if (!native.nativeAvailable && native.lastError) {
+    errors.push(native.lastError.message);
+  }
+
+  const analyticsInitialized = analytics
+    ? analytics.getDiagnostics().initialized
+    : false;
+
+  return {
+    ok: native.nativeAvailable && storageWritable,
+    analyticsInitialized,
+    nativeAvailable: native.nativeAvailable,
+    storageWritable,
+    errors,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,60 @@
+export type AmplitudeErrorCode =
+  | "not_initialized"
+  | "network_error"
+  | "storage_error"
+  | "invalid_api_key"
+  | "invalid_deployment_key"
+  | "experiment_fetch_failed"
+  | "native_unavailable"
+  | "serialization_error"
+  | "event_too_large"
+  | "timeout"
+  | "unknown";
+
+export class AmplitudeError extends Error {
+  readonly code: AmplitudeErrorCode;
+  readonly cause?: unknown;
+
+  constructor(code: AmplitudeErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.name = "AmplitudeError";
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+export function createAmplitudeError(
+  code: AmplitudeErrorCode,
+  message: string,
+  cause?: unknown,
+): AmplitudeError {
+  return new AmplitudeError(code, message, cause);
+}
+
+export function getAmplitudeErrorCode(error: unknown): AmplitudeErrorCode {
+  if (error instanceof AmplitudeError) {
+    return error.code;
+  }
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    if (message.includes("deployment key")) {
+      return "invalid_deployment_key";
+    }
+    if (message.includes("api key")) {
+      return "invalid_api_key";
+    }
+    if (message.includes("timeout")) {
+      return "timeout";
+    }
+    if (message.includes("network") || message.includes("fetch")) {
+      return "network_error";
+    }
+    if (message.includes("storage")) {
+      return "storage_error";
+    }
+    if (message.includes("nitro") || message.includes("native")) {
+      return "native_unavailable";
+    }
+  }
+  return "unknown";
+}