react-native-nitro-amplitude 0.1.0 → 0.5.0

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/transport/http.ts

@@ -66,11 +66,19 @@ const _request = (
 ): Promise<SimpleResponse> => {
   const abortController = getAbortController();
   const call = async () => {
-    const response = await getFetch()(requestUrl, {
+    const upperMethod = method.toUpperCase();
+    const init: RequestInit = {
       method: method,
       headers: headers,
-      body: data,
       signal: abortController?.signal,
+    };
+
+    if (upperMethod !== "GET" && upperMethod !== "HEAD") {
+      init.body = data;
+    }
+
+    const response = await getFetch()(requestUrl, {
+      ...init,
     });
     const simpleResponse: SimpleResponse = {
       status: response.status,

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.1.0";
+export const VERSION = "0.5.0";

package/src/index.web.ts

@@ -1,19 +1,94 @@
-const unsupported = (name: string): never => {
-  throw new Error(
-    `react-native-nitro-amplitude: ${name} is not supported on web. Use native iOS/Android builds.`,
-  );
-};
+import analyticsClient, {
+  createInstance,
+} from "./analytics/react-native-client";
+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";
 
-export const init = () => unsupported("init");
-export const track = () => unsupported("track");
-export const identify = () => unsupported("identify");
-export const createInstance = () => unsupported("createInstance");
-export const Experiment = {
-  initialize: () => unsupported("Experiment.initialize"),
-  initializeWithAmplitudeAnalytics: () =>
-    unsupported("Experiment.initializeWithAmplitudeAnalytics"),
-};
+import * as AnalyticsTypes from "./analytics/types";
+
+export { createInstance };
+export const {
+  add,
+  flush,
+  getDeviceId,
+  getSessionId,
+  getUserId,
+  groupIdentify,
+  identify,
+  init,
+  logEvent,
+  remove,
+  reset,
+  revenue,
+  setDeviceId,
+  setGroup,
+  setOptOut,
+  setSessionId,
+  setUserId,
+  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,
+  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";
+export { StubExperimentClient } from "./experiment/stubClient";
+export { ExperimentClient } from "./experiment/experimentClient";
+export * from "./experiment/types/client";
+export { Source } from "./experiment/types/source";
+export * from "./experiment/types/user";
+export * from "./experiment/types/variant";
+export * from "./experiment/types/exposure";
+export * from "./experiment/types/storage";
+export { LogLevel } from "./experiment/types/logger";
+export type { Logger } from "./experiment/types/logger";
+export { ConsoleLogger } from "./experiment/logger/consoleLogger";
+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.5.0";

package/src/native/context.web.ts

@@ -0,0 +1,38 @@
+import type { ReactNativeTrackingOptions } from "@amplitude/analytics-core";
+import type { LegacySessionData, NativeApplicationContext } from "./context";
+
+type NavigatorWithLanguage = Navigator & {
+  userLanguage?: string;
+};
+
+export function prefetchNativeContext(): void {}
+
+export function getNativeApplicationContext(
+  _options: ReactNativeTrackingOptions,
+): NativeApplicationContext {
+  const browserNavigator =
+    typeof navigator === "undefined"
+      ? undefined
+      : (navigator as NavigatorWithLanguage);
+  return {
+    platform: "Web",
+    language: browserNavigator?.language ?? browserNavigator?.userLanguage,
+  };
+}
+
+export function getLegacySessionData(_instanceName: string): LegacySessionData {
+  return {};
+}
+
+export function getLegacyEvents(
+  _instanceName: string,
+  _eventKind: string,
+): string[] {
+  return [];
+}
+
+export function removeLegacyEvent(
+  _instanceName: string,
+  _eventKind: string,
+  _eventId: number,
+): void {}

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

@@ -0,0 +1,24 @@
+import { FetchHttpClient } from "../experiment/transport/http";
+import type { HttpClient, SimpleResponse } from "../experiment/types/transport";
+import { assertNetworkEnabled } from "../network";
+
+export class NitroHttpClient implements HttpClient {
+  request(
+    requestUrl: string,
+    method: string,
+    headers: Record<string, string>,
+    data: string | null,
+    timeoutMillis = 10000,
+  ): Promise<SimpleResponse> {
+    assertNetworkEnabled();
+    return FetchHttpClient.request(
+      requestUrl,
+      method,
+      headers,
+      data ?? "",
+      timeoutMillis,
+    );
+  }
+}
+
+export const nitroHttpClient = new NitroHttpClient();

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 {}