react-native-nitro-amplitude 0.1.0 → 0.5.0

package/src/presets.ts

@@ -0,0 +1,208 @@
+import type {
+  Event,
+  ReactNativeOptions,
+  UserSession,
+} from "@amplitude/analytics-core";
+import { getAnalyticsConnector } from "@amplitude/analytics-core";
+import { createInstance } from "./analytics/react-native-client";
+import type { AmplitudeReactNativeClient } from "./analytics/react-native-client";
+import { NetworkGuardedFetchTransport } from "./analytics/network-guarded-fetch-transport";
+import { isNative } from "./analytics/utils/platform";
+import { Experiment } from "./experiment/factory";
+import type { ExperimentClient } from "./experiment/experimentClient";
+import type { ExperimentConfig } from "./experiment/types/config";
+import type { ExperimentUser } from "./experiment/types/user";
+import { dryRunHttpClient, dryRunTransport } from "./network";
+
+function getStorageModule(): typeof import("./native/storage") {
+  if (isNative()) {
+    return require("./native/storage") as typeof import("./native/storage");
+  }
+  return require("./native/storage.web") as typeof import("./native/storage");
+}
+
+function getAnalyticsTransport() {
+  if (isNative()) {
+    const { nitroTransport } =
+      require("./analytics/nitro-transport") as typeof import("./analytics/nitro-transport");
+    return nitroTransport;
+  }
+  return new NetworkGuardedFetchTransport();
+}
+
+export type DurableAmplitudeStoragePreset = {
+  analytics: Pick<
+    ReactNativeOptions,
+    "storageProvider" | "cookieStorage" | "transportProvider"
+  >;
+  experiment: Pick<ExperimentConfig, "storage">;
+  clear: () => Promise<void>;
+};
+
+export type DurableAmplitudeStoragePresetOptions = {
+  namespace?: string;
+  dryRun?: boolean;
+};
+
+export type AmplitudeCombinedClientConfig = {
+  analyticsApiKey: string;
+  experimentDeploymentKey?: string;
+  userId?: string;
+  instanceName?: string;
+  analytics?: ReactNativeOptions;
+  experiment?: ExperimentConfig;
+  durableStorage?: boolean | DurableAmplitudeStoragePresetOptions;
+  dryRun?: boolean;
+};
+
+export type AmplitudeCombinedClient = {
+  analytics: AmplitudeReactNativeClient;
+  experiment?: ExperimentClient;
+  init: (user?: ExperimentUser) => Promise<AmplitudeCombinedClient>;
+  flush: () => Promise<void>;
+  reset: () => void;
+  getUserId: () => string | undefined;
+  getDeviceId: () => string | undefined;
+};
+
+export type AmplitudeCombinedClientConfigWithExperiment =
+  AmplitudeCombinedClientConfig & {
+    experimentDeploymentKey: string;
+  };
+
+export type AmplitudeCombinedClientWithExperiment = Omit<
+  AmplitudeCombinedClient,
+  "experiment" | "init"
+> & {
+  experiment: ExperimentClient;
+  init: (
+    user?: ExperimentUser,
+  ) => Promise<AmplitudeCombinedClientWithExperiment>;
+};
+
+export function createDurableAmplitudeStoragePreset(
+  options: DurableAmplitudeStoragePresetOptions = {},
+): DurableAmplitudeStoragePreset {
+  const namespace = options.namespace ?? "default";
+  const { NitroAnalyticsStorage, NitroExperimentStorage } = getStorageModule();
+  const analyticsEvents = new NitroAnalyticsStorage<Event[]>(
+    `${namespace}:analytics-events`,
+  );
+  const analyticsSession = new NitroAnalyticsStorage<UserSession>(
+    `${namespace}:analytics-session`,
+  );
+  const experimentVariants = new NitroExperimentStorage(
+    `${namespace}:experiment-variants`,
+  );
+  return {
+    analytics: {
+      storageProvider: analyticsEvents,
+      cookieStorage: analyticsSession,
+      transportProvider: options.dryRun
+        ? dryRunTransport
+        : getAnalyticsTransport(),
+    },
+    experiment: {
+      storage: experimentVariants,
+    },
+    clear: async () => {
+      await analyticsEvents.reset();
+      await analyticsSession.reset();
+      await experimentVariants.reset?.();
+    },
+  };
+}
+
+export function createPersistentAmplitudeConfig(
+  namespaceOrOptions?: string | DurableAmplitudeStoragePresetOptions,
+): DurableAmplitudeStoragePreset {
+  if (typeof namespaceOrOptions === "string") {
+    return createDurableAmplitudeStoragePreset({
+      namespace: namespaceOrOptions,
+    });
+  }
+  return createDurableAmplitudeStoragePreset(namespaceOrOptions);
+}
+
+export function createExperimentUser(user: ExperimentUser): ExperimentUser {
+  return {
+    ...user,
+    user_properties: user.user_properties
+      ? { ...user.user_properties }
+      : undefined,
+    groups: user.groups ? { ...user.groups } : undefined,
+    group_properties: user.group_properties
+      ? { ...user.group_properties }
+      : undefined,
+  };
+}
+
+export function createAmplitudeClient(
+  config: AmplitudeCombinedClientConfigWithExperiment,
+): AmplitudeCombinedClientWithExperiment;
+export function createAmplitudeClient(
+  config: AmplitudeCombinedClientConfig,
+): AmplitudeCombinedClient;
+export function createAmplitudeClient(config: AmplitudeCombinedClientConfig) {
+  const instanceName = config.instanceName ?? "$default_instance";
+  const dryRunEnabled =
+    config.dryRun ||
+    (typeof config.durableStorage === "object" && config.durableStorage.dryRun);
+  const storagePreset =
+    config.durableStorage === false
+      ? undefined
+      : createDurableAmplitudeStoragePreset({
+          namespace:
+            typeof config.durableStorage === "object"
+              ? config.durableStorage.namespace
+              : instanceName,
+          dryRun: dryRunEnabled,
+        });
+  const analytics = createInstance();
+  const experiment =
+    config.experimentDeploymentKey !== undefined
+      ? Experiment.initializeWithAmplitudeAnalytics(
+          config.experimentDeploymentKey,
+          {
+            ...storagePreset?.experiment,
+            ...config.experiment,
+            instanceName,
+            httpClient: dryRunEnabled
+              ? (config.experiment?.httpClient ?? dryRunHttpClient)
+              : config.experiment?.httpClient,
+          },
+        )
+      : undefined;
+  const combined = {
+    analytics,
+    experiment,
+    init: async (user?: ExperimentUser) => {
+      await analytics.init(config.analyticsApiKey, config.userId, {
+        ...storagePreset?.analytics,
+        ...config.analytics,
+        instanceName,
+        transportProvider: dryRunEnabled
+          ? (config.analytics?.transportProvider ?? dryRunTransport)
+          : (config.analytics?.transportProvider ??
+            storagePreset?.analytics.transportProvider),
+      }).promise;
+      if (experiment && user) {
+        experiment.setUser(user);
+      }
+      return combined;
+    },
+    flush: async () => analytics.flush().promise,
+    reset: () => analytics.reset(),
+    getUserId: () => analytics.getUserId(),
+    getDeviceId: () => analytics.getDeviceId(),
+  } as AmplitudeCombinedClient;
+
+  return combined;
+}
+
+export function getConnectorIdentity(instanceName = "$default_instance"): {
+  userId?: string;
+  deviceId?: string;
+} {
+  return getAnalyticsConnector(instanceName).identityStore.getIdentity();
+}

package/src/testing.ts

@@ -0,0 +1,177 @@
+import type { AmplitudeReturn, Result } from "@amplitude/analytics-core";
+import type { AmplitudeReactNativeClient } from "./analytics/react-native-client";
+import type { Client } from "./experiment/types/client";
+import type { Storage } from "./experiment/types/storage";
+import type { ExperimentUser } from "./experiment/types/user";
+import type { Variant, Variants } from "./experiment/types/variant";
+
+type MockFunction<Args extends unknown[], Return> = ((
+  ...args: Args
+) => Return) & {
+  calls: Args[];
+};
+
+function createMockFunction<Args extends unknown[], Return>(
+  implementation: (...args: Args) => Return,
+): MockFunction<Args, Return> {
+  const fn = ((...args: Args) => {
+    fn.calls.push(args);
+    return implementation(...args);
+  }) as MockFunction<Args, Return>;
+  fn.calls = [];
+  return fn;
+}
+
+function createReturn(eventType: string): AmplitudeReturn<Result> {
+  const result: Result = {
+    event: { event_type: eventType },
+    code: 200,
+    message: "dry_run",
+  };
+  return {
+    promise: Promise.resolve(result),
+  };
+}
+
+export type FakeExperimentStorage = Storage & {
+  values: Map<string, string>;
+};
+
+export function createFakeExperimentStorage(
+  initialValues: Record<string, string> = {},
+): FakeExperimentStorage {
+  const values = new Map(Object.entries(initialValues));
+  return {
+    values,
+    get: async (key) => values.get(key) ?? null,
+    put: async (key, value) => {
+      values.set(key, value);
+    },
+    delete: async (key) => {
+      values.delete(key);
+    },
+    reset: async () => {
+      values.clear();
+    },
+  };
+}
+
+export function createMockAmplitudeClient(): AmplitudeReactNativeClient {
+  let userId: string | undefined;
+  let deviceId = "mock-device-id";
+  let sessionId: number | undefined;
+  const client = {
+    init: createMockFunction((_: string, nextUserId?: string) => {
+      userId = nextUserId;
+      return createReturn("$init");
+    }),
+    track: createMockFunction(() => createReturn("$track")),
+    logEvent: createMockFunction(() => createReturn("$track")),
+    identify: createMockFunction(() => createReturn("$identify")),
+    groupIdentify: createMockFunction(() => createReturn("$groupidentify")),
+    setGroup: createMockFunction(() => createReturn("$groupidentify")),
+    revenue: createMockFunction(() => createReturn("revenue_amount")),
+    flush: createMockFunction(() => createReturn("$flush")),
+    flushWithResult: createMockFunction(async () => ({
+      ok: true,
+      sent: 0,
+      failed: 0,
+      dropped: 0,
+      retried: 0,
+      finishedAt: Date.now(),
+    })),
+    add: createMockFunction(() => createReturn("$add")),
+    remove: createMockFunction(() => createReturn("$remove")),
+    setUserId: createMockFunction((nextUserId: string | undefined) => {
+      userId = nextUserId;
+    }),
+    getUserId: createMockFunction(() => userId),
+    setDeviceId: createMockFunction((nextDeviceId: string) => {
+      deviceId = nextDeviceId;
+    }),
+    getDeviceId: createMockFunction(() => deviceId),
+    setSessionId: createMockFunction((nextSessionId: number) => {
+      sessionId = nextSessionId;
+    }),
+    getSessionId: createMockFunction(() => sessionId),
+    extendSession: createMockFunction(() => undefined),
+    setOptOut: createMockFunction(() => undefined),
+    reset: createMockFunction(() => {
+      userId = undefined;
+      deviceId = "mock-device-id-reset";
+    }),
+    shutdown: createMockFunction(() => undefined),
+    getDiagnostics: createMockFunction(() => ({
+      initialized: true,
+      userId,
+      deviceId,
+      sessionId,
+      queueSize: 0,
+      activeInstanceNames: ["$default_instance"],
+    })),
+    healthCheck: createMockFunction(async () => ({
+      ok: true,
+      analyticsInitialized: true,
+      nativeAvailable: true,
+      storageWritable: true,
+      errors: [],
+    })),
+  };
+  return client as unknown as AmplitudeReactNativeClient;
+}
+
+export function createMockExperimentClient(
+  initialVariants: Variants = {},
+): Client {
+  let user: ExperimentUser = {};
+  const variants = new Map<string, Variant>(Object.entries(initialVariants));
+  let client: Client;
+  client = {
+    start: createMockFunction(async (nextUser?: ExperimentUser) => {
+      user = nextUser ?? user;
+    }),
+    stop: createMockFunction(() => undefined),
+    fetch: createMockFunction(async () => client),
+    fetchWithMetadata: createMockFunction(async () => ({
+      fetched: true,
+      flagKeys: Array.from(variants.keys()),
+      cacheHit: false,
+      durationMillis: 0,
+      source: "network" as const,
+    })),
+    fetchOrThrow: createMockFunction(async () => client),
+    variant: createMockFunction((key: string, fallback?: string | Variant) => {
+      return variants.get(key) ?? normalizeFallback(fallback);
+    }),
+    variantWithMetadata: createMockFunction(
+      (key: string, fallback?: string | Variant) => ({
+        variant: variants.get(key) ?? normalizeFallback(fallback),
+        fallback: !variants.has(key),
+        stale: false,
+        reason: variants.has(key) ? undefined : "fallback",
+      }),
+    ),
+    all: createMockFunction(() => Object.fromEntries(variants)),
+    clear: createMockFunction(() => variants.clear()),
+    clearVariants: createMockFunction(() => variants.clear()),
+    hasCachedVariant: createMockFunction((key: string) => variants.has(key)),
+    getLastFetchTime: createMockFunction(() => undefined),
+    exposure: createMockFunction(() => undefined),
+    getUser: createMockFunction(() => ({ ...user })),
+    setUser: createMockFunction((nextUser: ExperimentUser) => {
+      user = { ...nextUser };
+    }),
+    getUserProvider: createMockFunction(() => ({
+      getUser: async () => ({ ...user }),
+    })),
+    setUserProvider: createMockFunction(() => client),
+  };
+  return client;
+
+  function normalizeFallback(fallback?: string | Variant): Variant {
+    if (typeof fallback === "string") {
+      return { value: fallback };
+    }
+    return fallback ?? {};
+  }
+}