react-native-nitro-amplitude 0.1.0 → 0.5.0

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,14 +42,60 @@ 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;
-let activeConnectorOwnerId: number | undefined;
+const activeConnectorOwnerIds = new Map<string, number>();
+
+export function getActiveAnalyticsInstanceNames(): string[] {
+  return Array.from(activeConnectorOwnerIds.keys()).sort();
+}
 
 export class AmplitudeReactNative
   extends AmplitudeCore
@@ -58,11 +105,14 @@ 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
   config: ReactNativeConfig;
-  userProperties: { [key: string]: any } | undefined;
+  userProperties: Record<string, unknown> | undefined;
 
   init(apiKey = "", userId?: string, options?: ReactNativeOptions) {
     this.initPromise =
@@ -99,7 +149,8 @@ export class AmplitudeReactNative
       // Set up the analytics connector to integrate with the experiment SDK.
       // Send events from the experiment SDK and forward identifies to the
       // identity store.
-      const connector = getAnalyticsConnector();
+      const connectorInstanceName = this.getConnectorInstanceName();
+      const connector = getAnalyticsConnector(connectorInstanceName);
       connector.identityStore.setIdentity({
         userId: this.config.userId,
         deviceId: this.config.deviceId,
@@ -140,7 +191,7 @@ export class AmplitudeReactNative
           this.track(event.eventType, event.eventProperties).promise,
         );
       });
-      activeConnectorOwnerId = this.connectorOwnerId;
+      activeConnectorOwnerIds.set(connectorInstanceName, this.connectorOwnerId);
     } catch (error) {
       if (appStateHandlerInstalled) {
         this.appStateChangeHandler?.remove();
@@ -162,11 +213,18 @@ export class AmplitudeReactNative
     this.dispatchQ = [];
     this.isReady = false;
 
-    if (activeConnectorOwnerId === this.connectorOwnerId) {
-      const connector = getAnalyticsConnector();
+    const connectorInstanceName = this.config
+      ? this.getConnectorInstanceName()
+      : undefined;
+    if (
+      connectorInstanceName &&
+      activeConnectorOwnerIds.get(connectorInstanceName) ===
+        this.connectorOwnerId
+    ) {
+      const connector = getAnalyticsConnector(connectorInstanceName);
       connector.eventBridge.setEventReceiver(() => undefined);
       connector.identityStore.setIdentity({});
-      activeConnectorOwnerId = undefined;
+      activeConnectorOwnerIds.delete(connectorInstanceName);
     }
   }
 
@@ -178,6 +236,10 @@ export class AmplitudeReactNative
     });
   }
 
+  private getConnectorInstanceName() {
+    return this.config.instanceName ?? "$default_instance";
+  }
+
   private cancelDestinationFlushes() {
     this.timeline.plugins.forEach((plugin) => {
       if (plugin.type !== "destination") {
@@ -232,7 +294,7 @@ export class AmplitudeReactNative
       return;
     }
     this.config.userId = userId;
-    setConnectorUserId(userId);
+    setConnectorUserId(userId, this.getConnectorInstanceName());
   }
 
   getDeviceId() {
@@ -245,7 +307,7 @@ export class AmplitudeReactNative
       return;
     }
     this.config.deviceId = deviceId;
-    setConnectorDeviceId(deviceId);
+    setConnectorDeviceId(deviceId, this.getConnectorInstanceName());
   }
 
   identify(identify: IIdentify, eventOptions?: EventOptions) {
@@ -267,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(),
@@ -297,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) {
@@ -507,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",
@@ -567,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";
+}

package/src/experiment/experimentClient.ts

@@ -30,7 +30,12 @@ import {
 } from "./storage/cache";
 import { MemoryStorage } from "./storage/local-storage";
 import { FetchHttpClient, WrapperClient } from "./transport/http";
-import { Client, FetchOptions } from "./types/client";
+import {
+  Client,
+  ExperimentFetchResult,
+  ExperimentVariantResult,
+  FetchOptions,
+} from "./types/client";
 import { ExperimentConfig, Defaults } from "./types/config";
 import { Exposure } from "./types/exposure";
 import { LogLevel } from "./types/logger";
@@ -119,6 +124,9 @@ export class ExperimentClient implements Client {
   private storedFetchSequenceNumber = 0;
   private readonly fetchVariantsOptions: SingleValueStoreCache<GetVariantsOptions>;
   private readonly stopCallbacks = new Set<() => void>();
+  private readonly inFlightFetches = new Map<string, Promise<Variants>>();
+  private lastFetchTime: number | undefined;
+  private lastFetchFailure: string | undefined;
 
   /**
    * Creates a new ExperimentClient instance.
@@ -341,6 +349,37 @@ export class ExperimentClient implements Client {
     return this;
   }
 
+  public async fetchWithMetadata(
+    user: ExperimentUser = this.user,
+    options?: FetchOptions,
+  ): Promise<ExperimentFetchResult> {
+    const startedAt = Date.now();
+    const fetchUser = user ?? this.user;
+    this.setUser(fetchUser);
+    try {
+      const variants = await this.fetchWithRetries(fetchUser, options);
+      const flagKeys = Object.keys(variants);
+      return {
+        fetched: true,
+        flagKeys,
+        cacheHit: false,
+        durationMillis: Date.now() - startedAt,
+        source: "network",
+      };
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.lastFetchFailure = reason;
+      return {
+        fetched: false,
+        flagKeys: options?.flagKeys ?? Object.keys(this.variants.getAll()),
+        cacheHit: Object.keys(this.variants.getAll()).length > 0,
+        durationMillis: Date.now() - startedAt,
+        source: "cache",
+        failureReason: reason,
+      };
+    }
+  }
+
   public async fetchOrThrow(
     user: ExperimentUser = this.user,
     options?: FetchOptions,
@@ -380,6 +419,45 @@ export class ExperimentClient implements Client {
     return sourceVariant.variant || {};
   }
 
+  public variantWithMetadata(
+    key: string,
+    fallback?: string | Variant,
+  ): ExperimentVariantResult {
+    if (!this.apiKey) {
+      return {
+        variant: { value: undefined },
+        fallback: true,
+        stale: false,
+        reason: "missing_flag",
+      };
+    }
+    const sourceVariant = this.variantAndSource(key, fallback);
+    if (this.config.automaticExposureTracking) {
+      this.exposureInternal(key, sourceVariant);
+    }
+    this.logger.debug(
+      `[Experiment] variant for ${key} is ${sourceVariant.variant?.value}`,
+    );
+    const variant = sourceVariant.variant || {};
+    const fallbackVariant = isFallback(sourceVariant.source);
+    const missingVariant = variant.value === undefined;
+    return {
+      variant,
+      source: sourceVariant.source,
+      fallback: fallbackVariant,
+      stale: false,
+      reason: missingVariant
+        ? this.lastFetchFailure
+          ? "fetch_failure"
+          : fallbackVariant
+            ? "fallback"
+            : "no_assignment"
+        : fallbackVariant
+          ? "fallback"
+          : undefined,
+    };
+  }
+
   /**
    * Track an exposure event for the variant associated with the flag/experiment
    * {@link key}.
@@ -431,6 +509,18 @@ export class ExperimentClient implements Client {
     void this.variants.store().catch((e) => this.logger.warn(e));
   }
 
+  public clearVariants(): void {
+    this.clear();
+  }
+
+  public hasCachedVariant(key: string): boolean {
+    return this.variants.get(key) !== undefined;
+  }
+
+  public getLastFetchTime(): number | undefined {
+    return this.lastFetchTime;
+  }
+
   /**
    * Get a copy of the internal {@link ExperimentUser} object if it is set.
    *
@@ -788,12 +878,35 @@ export class ExperimentClient implements Client {
     user: ExperimentUser,
     options?: FetchOptions,
   ): Promise<Variants> {
-    return await this.fetchInternal(
+    const key = JSON.stringify({
+      user,
+      flagKeys: options?.flagKeys ?? null,
+    });
+    const inFlightFetch = this.inFlightFetches.get(key);
+    if (inFlightFetch) {
+      return await inFlightFetch;
+    }
+    const fetch = this.fetchInternal(
       user,
       this.config.fetchTimeoutMillis,
       this.config.retryFetchOnFailure,
       options,
-    );
+    )
+      .then((variants) => {
+        this.lastFetchTime = Date.now();
+        this.lastFetchFailure = undefined;
+        return variants;
+      })
+      .catch((error: unknown) => {
+        this.lastFetchFailure =
+          error instanceof Error ? error.message : String(error);
+        throw error;
+      })
+      .finally(() => {
+        this.inFlightFetches.delete(key);
+      });
+    this.inFlightFetches.set(key, fetch);
+    return await fetch;
   }
 
   private async doFetch(

package/src/experiment/index.ts

@@ -12,3 +12,4 @@ export { LogLevel } from "./types/logger";
 export type { Logger } from "./types/logger";
 export { ConsoleLogger } from "./logger/consoleLogger";
 export { LocalStorage, MemoryStorage } from "./storage/local-storage";
+export * from "./typed-variants";