react-native-nitro-amplitude 0.2.0 → 0.5.0

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";

package/src/experiment/stubClient.ts

@@ -1,4 +1,9 @@
-import { Client, FetchOptions } from "./types/client";
+import {
+  Client,
+  ExperimentFetchResult,
+  ExperimentVariantResult,
+  FetchOptions,
+} from "./types/client";
 import { Defaults } from "./types/config";
 import { ExperimentUser, ExperimentUserProvider } from "./types/user";
 import { Variant, Variants } from "./types/variant";
@@ -33,6 +38,20 @@ export class StubExperimentClient implements Client {
     return this;
   }
 
+  public async fetchWithMetadata(
+    _user?: ExperimentUser,
+    _options?: FetchOptions,
+  ): Promise<ExperimentFetchResult> {
+    return {
+      fetched: false,
+      flagKeys: [],
+      cacheHit: false,
+      durationMillis: 0,
+      source: "cache",
+      failureReason: "stub_client",
+    };
+  }
+
   public getUserProvider(): ExperimentUserProvider {
     return {
       async getUser(): Promise<ExperimentUser> {
@@ -51,11 +70,33 @@ export class StubExperimentClient implements Client {
     return Defaults.fallbackVariant ?? {};
   }
 
+  public variantWithMetadata(
+    _key: string,
+    _fallback?: string | Variant,
+  ): ExperimentVariantResult {
+    return {
+      variant: Defaults.fallbackVariant ?? {},
+      fallback: true,
+      stale: false,
+      reason: "fallback",
+    };
+  }
+
   public all(): Variants {
     return {};
   }
 
   public clear(): void {}
 
+  public clearVariants(): void {}
+
+  public hasCachedVariant(_key: string): boolean {
+    return false;
+  }
+
+  public getLastFetchTime(): number | undefined {
+    return undefined;
+  }
+
   public exposure(_key: string): void {}
 }

package/src/experiment/typed-variants.ts

@@ -0,0 +1,68 @@
+import type { Client } from "./types/client";
+import type { Variant } from "./types/variant";
+
+export function variantString(
+  client: Pick<Client, "variant">,
+  key: string,
+  fallback: string,
+): string {
+  const value = client.variant(key, fallback).value;
+  return value ?? fallback;
+}
+
+export function variantBoolean(
+  client: Pick<Client, "variant">,
+  key: string,
+  fallback: boolean,
+): boolean {
+  const value = client.variant(key, String(fallback)).value;
+  if (value === "true") {
+    return true;
+  }
+  if (value === "false") {
+    return false;
+  }
+  return fallback;
+}
+
+export function variantNumber(
+  client: Pick<Client, "variant">,
+  key: string,
+  fallback: number,
+): number {
+  const value = client.variant(key, String(fallback)).value;
+  if (value === undefined) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export function variantPayload<T>(
+  client: Pick<Client, "variant">,
+  key: string,
+  fallback: T,
+): T {
+  const payload = client.variant(key).payload;
+  return payload === undefined ? fallback : (payload as T);
+}
+
+export function variantJson<T>(
+  client: Pick<Client, "variant">,
+  key: string,
+  fallback: T,
+): T {
+  const variant = client.variant(key);
+  return parseVariantJson(variant, fallback);
+}
+
+export function parseVariantJson<T>(variant: Variant, fallback: T): T {
+  if (typeof variant.value !== "string") {
+    return fallback;
+  }
+  try {
+    return JSON.parse(variant.value) as T;
+  } catch {
+    return fallback;
+  }
+}

package/src/experiment/types/client.ts

@@ -1,5 +1,6 @@
 import { ExperimentUser, ExperimentUserProvider } from "./user";
 import { Variant, Variants } from "./variant";
+import { VariantSource } from "./source";
 
 /**
  * Interface for the main client.
@@ -9,10 +10,21 @@ export interface Client {
   start(user?: ExperimentUser): Promise<void>;
   stop(): void;
   fetch(user?: ExperimentUser, options?: FetchOptions): Promise<Client>;
+  fetchWithMetadata(
+    user?: ExperimentUser,
+    options?: FetchOptions,
+  ): Promise<ExperimentFetchResult>;
   fetchOrThrow(user?: ExperimentUser, options?: FetchOptions): Promise<Client>;
   variant(key: string, fallback?: string | Variant): Variant;
+  variantWithMetadata(
+    key: string,
+    fallback?: string | Variant,
+  ): ExperimentVariantResult;
   all(): Variants;
   clear(): void;
+  clearVariants(): void;
+  hasCachedVariant(key: string): boolean;
+  getLastFetchTime(): number | undefined;
   exposure(key: string): void;
   getUser(): ExperimentUser;
   setUser(user: ExperimentUser): void;
@@ -36,3 +48,20 @@ export type FetchOptions = {
    */
   flagKeys?: string[];
 };
+
+export type ExperimentFetchResult = {
+  fetched: boolean;
+  flagKeys: string[];
+  cacheHit: boolean;
+  durationMillis: number;
+  source: "network" | "cache";
+  failureReason?: string;
+};
+
+export type ExperimentVariantResult = {
+  variant: Variant;
+  source?: VariantSource;
+  fallback: boolean;
+  stale: boolean;
+  reason?: "missing_flag" | "fetch_failure" | "no_assignment" | "fallback";
+};

package/src/experiment/types/config.ts

@@ -1,6 +1,4 @@
-import { nitroHttpClient } from "../../native/http";
-import { NitroMemoryStorage } from "../../native/storage";
-
+import { isNative } from "../util/platform";
 import { ExposureTrackingProvider } from "./exposure";
 import { Logger, LogLevel } from "./logger";
 import { Source } from "./source";
@@ -9,6 +7,28 @@ import { HttpClient } from "./transport";
 import { ExperimentUserProvider } from "./user";
 import { Variant, Variants } from "./variant";
 
+function createDefaultHttpClient(): HttpClient {
+  if (isNative()) {
+    const { nitroHttpClient } =
+      require("../../native/http") as typeof import("../../native/http");
+    return nitroHttpClient;
+  }
+  const { nitroHttpClient } =
+    require("../../native/http.web") as typeof import("../../native/http");
+  return nitroHttpClient;
+}
+
+function createDefaultStorage(): Storage {
+  if (isNative()) {
+    const { NitroMemoryStorage } =
+      require("../../native/storage") as typeof import("../../native/storage");
+    return new NitroMemoryStorage("experiment");
+  }
+  const { NitroMemoryStorage } =
+    require("../../native/storage.web") as typeof import("../../native/storage");
+  return new NitroMemoryStorage("experiment");
+}
+
 /**
  * @category Configuration
  */
@@ -205,6 +225,10 @@ export const Defaults: ExperimentConfig = {
   automaticFetchOnAmplitudeIdentityChange: false,
   userProvider: null,
   exposureTrackingProvider: null,
-  httpClient: nitroHttpClient,
-  storage: new NitroMemoryStorage("experiment"),
+  get httpClient() {
+    return createDefaultHttpClient();
+  },
+  get storage() {
+    return createDefaultStorage();
+  },
 };

package/src/index.ts

@@ -1,6 +1,8 @@
 import analyticsClient, {
   createInstance,
 } from "./analytics/react-native-client";
+import type { AmplitudeDiagnostics } from "./diagnostics";
+import { getAmplitudeDiagnostics } from "./diagnostics";
 import { prefetchNativeContext } from "./native/context";
 
 import * as AnalyticsTypes from "./analytics/types";
@@ -27,19 +29,42 @@ export const {
   shutdown,
   track,
   extendSession,
+  flushWithResult,
+  healthCheck,
 } = analyticsClient;
 
+export function getDiagnostics(): AmplitudeDiagnostics {
+  return getAmplitudeDiagnostics(analyticsClient);
+}
+
 export { Revenue, Identify } from "@amplitude/analytics-core";
 export {
   InMemoryStorage,
   LocalStorage,
   MemoryStorage,
 } from "./analytics/storage/local-storage";
-export { NitroAnalyticsStorage, NitroMemoryStorage } from "./native/storage";
+export {
+  NitroAnalyticsStorage,
+  NitroExperimentStorage,
+  NitroMemoryStorage,
+} from "./native/storage";
 export { nitroHttpClient } from "./native/http";
 export { nitroTransport } from "./analytics/nitro-transport";
 export { prefetchNativeContext };
 export { AnalyticsTypes as Types };
+export {
+  getAmplitudeDiagnostics,
+  getLastNativeError,
+  getNativeStartupDiagnostics,
+} from "./diagnostics";
+export type {
+  AmplitudeDiagnostics,
+  NativeStartupDiagnostics,
+} from "./diagnostics";
+export * from "./errors";
+export * from "./network";
+export * from "./presets";
+export * from "./testing";
 
 export * from "./experiment/types/config";
 export { Experiment } from "./experiment/factory";
@@ -58,9 +83,10 @@ export {
   LocalStorage as ExperimentLocalStorage,
   MemoryStorage as ExperimentMemoryStorage,
 } from "./experiment/storage/local-storage";
+export * from "./experiment/typed-variants";
 
 export type { AmplitudeContext } from "./AmplitudeContext.nitro";
 export type { AmplitudeStorage } from "./AmplitudeStorage.nitro";
 export type { AmplitudeWorker } from "./AmplitudeWorker.nitro";
 
-export const VERSION = "0.2.0";
+export const VERSION = "0.5.0";

package/src/index.web.ts

@@ -1,7 +1,11 @@
 import analyticsClient, {
   createInstance,
 } from "./analytics/react-native-client";
-import { prefetchNativeContext } from "./native/context";
+import type { Transport } from "@amplitude/analytics-core";
+import { NetworkGuardedFetchTransport } from "./analytics/network-guarded-fetch-transport";
+import type { AmplitudeDiagnostics } from "./diagnostics";
+import { getAmplitudeDiagnostics } from "./diagnostics";
+import { prefetchNativeContext } from "./native/context.web";
 
 import * as AnalyticsTypes from "./analytics/types";
 
@@ -27,19 +31,42 @@ export const {
   shutdown,
   track,
   extendSession,
+  flushWithResult,
+  healthCheck,
 } = analyticsClient;
 
+export function getDiagnostics(): AmplitudeDiagnostics {
+  return getAmplitudeDiagnostics(analyticsClient);
+}
+
 export { Revenue, Identify } from "@amplitude/analytics-core";
 export {
   InMemoryStorage,
   LocalStorage,
   MemoryStorage,
 } from "./analytics/storage/local-storage";
-export { NitroAnalyticsStorage, NitroMemoryStorage } from "./native/storage";
-export { nitroHttpClient } from "./native/http";
-export { nitroTransport } from "./analytics/nitro-transport";
+export {
+  NitroAnalyticsStorage,
+  NitroExperimentStorage,
+  NitroMemoryStorage,
+} from "./native/storage.web";
+export { nitroHttpClient } from "./native/http.web";
+export const nitroTransport: Transport = new NetworkGuardedFetchTransport();
 export { prefetchNativeContext };
 export { AnalyticsTypes as Types };
+export {
+  getAmplitudeDiagnostics,
+  getLastNativeError,
+  getNativeStartupDiagnostics,
+} from "./diagnostics";
+export type {
+  AmplitudeDiagnostics,
+  NativeStartupDiagnostics,
+} from "./diagnostics";
+export * from "./errors";
+export * from "./network";
+export * from "./presets";
+export * from "./testing";
 
 export * from "./experiment/types/config";
 export { Experiment } from "./experiment/factory";
@@ -58,9 +85,10 @@ export {
   LocalStorage as ExperimentLocalStorage,
   MemoryStorage as ExperimentMemoryStorage,
 } from "./experiment/storage/local-storage";
+export * from "./experiment/typed-variants";
 
 export type { AmplitudeContext } from "./AmplitudeContext.nitro";
 export type { AmplitudeStorage } from "./AmplitudeStorage.nitro";
 export type { AmplitudeWorker } from "./AmplitudeWorker.nitro";
 
-export const VERSION = "0.2.0";
+export const VERSION = "0.5.0";

package/src/native/http.ts

@@ -1,5 +1,8 @@
 import type { HttpClient, SimpleResponse } from "../experiment/types/transport";
+import { createAmplitudeError, getAmplitudeErrorCode } from "../errors";
+import { assertNetworkEnabled } from "../network";
 import { getAmplitudeWorker } from "./hybrid";
+import type { AmplitudeWorker } from "../AmplitudeWorker.nitro";
 
 type PendingRequest = {
   resolve: (response: SimpleResponse) => void;
@@ -9,13 +12,18 @@ type PendingRequest = {
 
 const pendingRequests = new Map<string, PendingRequest>();
 let listenerInstalled = false;
+let listenerWorker: AmplitudeWorker | undefined;
+const DEFAULT_TIMEOUT_MILLIS = 10000;
+const MAX_TIMEOUT_MILLIS = 300000;
 
 function ensureListener(): void {
-  if (listenerInstalled) {
+  const worker = getAmplitudeWorker();
+  if (listenerInstalled && listenerWorker === worker) {
     return;
   }
   listenerInstalled = true;
-  getAmplitudeWorker().addOnComplete((requestId, statusCode, body, error) => {
+  listenerWorker = worker;
+  worker.addOnComplete((requestId, statusCode, body, error) => {
     const pending = pendingRequests.get(requestId);
     if (!pending) {
       return;
@@ -23,7 +31,9 @@ function ensureListener(): void {
     pendingRequests.delete(requestId);
     clearTimeout(pending.timeoutId);
     if (error) {
-      pending.reject(new Error(error));
+      pending.reject(
+        createAmplitudeError(getAmplitudeErrorCode(new Error(error)), error),
+      );
       return;
     }
     pending.resolve({
@@ -37,22 +47,36 @@ function createRequestId(): string {
   return `req_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 
+function normalizeTimeoutMillis(timeoutMillis: number): number {
+  if (!Number.isFinite(timeoutMillis) || timeoutMillis <= 0) {
+    return DEFAULT_TIMEOUT_MILLIS;
+  }
+  return Math.min(Math.ceil(timeoutMillis), MAX_TIMEOUT_MILLIS);
+}
+
 export class NitroHttpClient implements HttpClient {
   async request(
     requestUrl: string,
     method: string,
     headers: Record<string, string>,
     data: string | null,
-    timeoutMillis = 10000,
+    timeoutMillis = DEFAULT_TIMEOUT_MILLIS,
   ): Promise<SimpleResponse> {
+    assertNetworkEnabled();
     ensureListener();
     const requestId = createRequestId();
+    const normalizedTimeoutMillis = normalizeTimeoutMillis(timeoutMillis);
     return new Promise<SimpleResponse>((resolve, reject) => {
       const timeoutId = setTimeout(() => {
         pendingRequests.delete(requestId);
         getAmplitudeWorker().cancel(requestId);
-        reject(new Error(`Request timed out after ${timeoutMillis}ms`));
-      }, timeoutMillis + 250);
+        reject(
+          createAmplitudeError(
+            "timeout",
+            `Request timed out after ${normalizedTimeoutMillis}ms`,
+          ),
+        );
+      }, normalizedTimeoutMillis + 250);
 
       pendingRequests.set(requestId, { resolve, reject, timeoutId });
 
@@ -63,12 +87,18 @@ export class NitroHttpClient implements HttpClient {
           method,
           JSON.stringify(headers),
           data ?? "",
-          timeoutMillis,
+          normalizedTimeoutMillis,
         );
       } catch (error) {
         pendingRequests.delete(requestId);
         clearTimeout(timeoutId);
-        reject(error instanceof Error ? error : new Error(String(error)));
+        reject(
+          createAmplitudeError(
+            getAmplitudeErrorCode(error),
+            error instanceof Error ? error.message : String(error),
+            error,
+          ),
+        );
       }
     });
   }

package/src/native/http.web.ts

@@ -1,5 +1,6 @@
 import { FetchHttpClient } from "../experiment/transport/http";
 import type { HttpClient, SimpleResponse } from "../experiment/types/transport";
+import { assertNetworkEnabled } from "../network";
 
 export class NitroHttpClient implements HttpClient {
   request(
@@ -9,6 +10,7 @@ export class NitroHttpClient implements HttpClient {
     data: string | null,
     timeoutMillis = 10000,
   ): Promise<SimpleResponse> {
+    assertNetworkEnabled();
     return FetchHttpClient.request(
       requestUrl,
       method,

package/src/native/hybrid.web.ts

@@ -0,0 +1,21 @@
+import type { AmplitudeContext } from "../AmplitudeContext.nitro";
+import type { AmplitudeStorage } from "../AmplitudeStorage.nitro";
+import type { AmplitudeWorker } from "../AmplitudeWorker.nitro";
+
+function unavailable(): never {
+  throw new Error("Nitro Amplitude native bindings are not available on web");
+}
+
+export function getAmplitudeContext(): AmplitudeContext {
+  return unavailable();
+}
+
+export function getAmplitudeStorage(): AmplitudeStorage {
+  return unavailable();
+}
+
+export function getAmplitudeWorker(): AmplitudeWorker {
+  return unavailable();
+}
+
+export function resetHybridInstancesForTests(): void {}