react-native-nitro-amplitude 0.1.0

package/src/experiment/factory.ts

@@ -0,0 +1,86 @@
+import { AnalyticsConnector } from "@amplitude/analytics-connector";
+import type { IdentityListener } from "@amplitude/analytics-connector";
+
+import { ExperimentClient } from "./experimentClient";
+import {
+  ConnectorExposureTrackingProvider,
+  ConnectorUserProvider,
+} from "./integration/connector";
+import { Defaults, ExperimentConfig } from "./types/config";
+
+const instances: Record<string, ExperimentClient> = {};
+
+/**
+ * Initializes a singleton {@link ExperimentClient} identified by the configured
+ * instance name.
+ *
+ * @param apiKey The deployment API Key
+ * @param config See {@link ExperimentConfig} for config options
+ */
+const initialize = (
+  apiKey: string,
+  config?: ExperimentConfig,
+): ExperimentClient => {
+  // Store instances by appending the instance name and api key. Allows for
+  // initializing multiple default instances for different api keys.
+  const instanceName =
+    config?.instanceName ?? Defaults.instanceName ?? "$default_instance";
+  const instanceKey = `${instanceName}.${apiKey}`;
+  if (!instances[instanceKey]) {
+    instances[instanceKey] = new ExperimentClient(apiKey, config || {});
+  }
+  return instances[instanceKey];
+};
+
+/**
+ * Initialize a singleton {@link ExperimentClient} which automatically
+ * integrates with the installed and initialized instance of the amplitude
+ * analytics SDK.
+ *
+ * You must be using amplitude-js SDK version 8.17.0+ for this integration to
+ * work.
+ *
+ * @param apiKey The deployment API Key
+ * @param config See {@link ExperimentConfig} for config options
+ */
+const initializeWithAmplitudeAnalytics = (
+  apiKey: string,
+  config?: ExperimentConfig,
+): ExperimentClient => {
+  // Store instances by appending the instance name and api key. Allows for
+  // initializing multiple default instances for different api keys.
+  const instanceName =
+    config?.instanceName ?? Defaults.instanceName ?? "$default_instance";
+  const instanceKey = `${instanceName}.${apiKey}`;
+  const connector = AnalyticsConnector.getInstance(instanceName);
+  if (!instances[instanceKey]) {
+    config = {
+      userProvider: new ConnectorUserProvider(connector.identityStore),
+      exposureTrackingProvider: new ConnectorExposureTrackingProvider(
+        connector.eventBridge,
+      ),
+      ...config,
+    };
+    instances[instanceKey] = new ExperimentClient(apiKey, config);
+    if (config.automaticFetchOnAmplitudeIdentityChange) {
+      const client = instances[instanceKey];
+      const listener: IdentityListener = () => {
+        client.fetchOnIdentityChange();
+      };
+      connector.identityStore.addIdentityListener(listener);
+      client.addStopCallback(() => {
+        connector.identityStore.removeIdentityListener(listener);
+      });
+    }
+  }
+  return instances[instanceKey];
+};
+
+/**
+ * Provides factory methods for storing singleton instances of {@link ExperimentClient}
+ * @category Core Usage
+ */
+export const Experiment = {
+  initialize,
+  initializeWithAmplitudeAnalytics,
+};

package/src/experiment/gen/version.ts

@@ -0,0 +1,2 @@
+// generated by genversion
+export const version = "1.8.13";

package/src/experiment/index.ts

@@ -0,0 +1,14 @@
+export * from "./types/config";
+export { Experiment } from "./factory";
+export { StubExperimentClient } from "./stubClient";
+export { ExperimentClient } from "./experimentClient";
+export * from "./types/client";
+export { Source } from "./types/source";
+export * from "./types/user";
+export * from "./types/variant";
+export * from "./types/exposure";
+export * from "./types/storage";
+export { LogLevel } from "./types/logger";
+export type { Logger } from "./types/logger";
+export { ConsoleLogger } from "./logger/consoleLogger";
+export { LocalStorage, MemoryStorage } from "./storage/local-storage";

package/src/experiment/integration/NativeExperimentReactNativeClient.ts

@@ -0,0 +1,25 @@
+import { NativeModules, TurboModuleRegistry } from "react-native";
+import type { TurboModule } from "react-native";
+
+export interface Spec extends TurboModule {
+  getApplicationContext(): Promise<{
+    version?: string;
+    platform?: string;
+    language?: string;
+    os?: string;
+    device_brand?: string;
+    device_manufacturer?: string;
+    device_model?: string;
+    carrier?: string;
+  }>;
+}
+
+const turboModule = TurboModuleRegistry.get<Spec>(
+  "ExperimentReactNativeClient",
+);
+const legacyModule = NativeModules.ExperimentReactNativeClient as
+  | Spec
+  | undefined
+  | null;
+
+export default turboModule ?? legacyModule;

package/src/experiment/integration/connector.ts

@@ -0,0 +1,82 @@
+import { EventBridge, IdentityStore } from "@amplitude/analytics-connector";
+import { safeGlobal } from "@amplitude/experiment-core";
+
+import { Exposure, ExposureTrackingProvider } from "../types/exposure";
+import { ExperimentUser, ExperimentUserProvider } from "../types/user";
+
+type UserProperties = Record<
+  string,
+  string | number | boolean | (string | number | boolean)[]
+>;
+
+export class ConnectorUserProvider implements ExperimentUserProvider {
+  private readonly identityStore: IdentityStore;
+  constructor(identityStore: IdentityStore) {
+    this.identityStore = identityStore;
+  }
+
+  async identityReady(ms: number): Promise<void> {
+    const identity = this.identityStore.getIdentity();
+    if (!identity.userId && !identity.deviceId) {
+      return new Promise<void>((resolve, reject) => {
+        let timeoutHandle: ReturnType<typeof safeGlobal.setTimeout> | undefined;
+        const cleanup = () => {
+          if (timeoutHandle != null) {
+            safeGlobal.clearTimeout(timeoutHandle);
+            timeoutHandle = undefined;
+          }
+          this.identityStore.removeIdentityListener(listener);
+        };
+        const listener = () => {
+          cleanup();
+          resolve();
+        };
+
+        timeoutHandle = safeGlobal.setTimeout(() => {
+          cleanup();
+          reject(
+            Error(
+              "Timed out waiting for Amplitude Analytics SDK to initialize. " +
+                "You must ensure that the analytics SDK is initialized prior to calling fetch().",
+            ),
+          );
+        }, ms);
+        this.identityStore.addIdentityListener(listener);
+      });
+    }
+  }
+
+  async getUser(): Promise<ExperimentUser> {
+    return this.getUserSync();
+  }
+
+  getUserSync(): ExperimentUser {
+    const identity = this.identityStore.getIdentity();
+    let userProperties: UserProperties | undefined;
+    try {
+      userProperties = identity.userProperties as UserProperties;
+    } catch {
+      console.warn("[Experiment] failed to cast user properties");
+    }
+    return {
+      user_id: identity.userId,
+      device_id: identity.deviceId,
+      user_properties: userProperties,
+    };
+  }
+}
+
+export class ConnectorExposureTrackingProvider implements ExposureTrackingProvider {
+  private readonly eventBridge: EventBridge;
+
+  constructor(eventBridge: EventBridge) {
+    this.eventBridge = eventBridge;
+  }
+
+  track(exposure: Exposure): void {
+    this.eventBridge.logEvent({
+      eventType: "$exposure",
+      eventProperties: exposure,
+    });
+  }
+}

package/src/experiment/integration/default.ts

@@ -0,0 +1,107 @@
+import {
+  AnalyticsConnector,
+  ApplicationContext,
+} from "@amplitude/analytics-connector";
+import { Poller } from "@amplitude/experiment-core";
+
+import { ExperimentUser, ExperimentUserProvider } from "../types/user";
+import { isNative } from "../util/platform";
+
+import { getNativeApplicationContext } from "../../native/context";
+import { ConnectorUserProvider } from "./connector";
+
+export class DefaultUserProvider implements ExperimentUserProvider {
+  public baseProvider: ExperimentUserProvider | null;
+  private readonly applicationContext: ApplicationContext;
+  public cachedUser: ExperimentUser = {};
+  public cachedApplicationContext?: Record<string, string>;
+  private readonly poller: Poller = new Poller(() => this.load(), 1000);
+
+  constructor(baseProvider: ExperimentUserProvider | null = null) {
+    this.baseProvider = baseProvider;
+    this.applicationContext =
+      AnalyticsConnector.getInstance(
+        "context",
+      ).applicationContextProvider.getApplicationContext();
+  }
+
+  public start(): void {
+    void this.load();
+    if (this.shouldPollUserCache()) {
+      this.poller.start();
+    }
+  }
+
+  public stop(): void {
+    this.poller.stop();
+  }
+
+  /**
+   * The variant method is not async
+   */
+  async load(): Promise<void> {
+    try {
+      this.cachedUser = await this.getUser();
+    } catch {
+      this.cachedUser = this.cachedUser || {};
+    }
+  }
+
+  async getApplicationContext(): Promise<Record<string, string>> {
+    if (this.cachedApplicationContext) {
+      return this.cachedApplicationContext;
+    } else if (isNative()) {
+      try {
+        this.cachedApplicationContext = getNativeApplicationContext({
+          adid: true,
+          carrier: true,
+          deviceManufacturer: true,
+          deviceModel: true,
+          ipAddress: false,
+          language: true,
+          osName: true,
+          osVersion: true,
+          platform: true,
+          appSetId: true,
+          idfv: true,
+          country: true,
+        });
+      } catch {
+        this.cachedApplicationContext = {};
+      }
+      return this.cachedApplicationContext;
+    } else {
+      this.cachedApplicationContext = this.applicationContext;
+      return this.cachedApplicationContext;
+    }
+  }
+
+  getUserSync(): ExperimentUser {
+    const context = this.cachedApplicationContext ?? {};
+    let user: ExperimentUser = this.cachedUser;
+    if (this.baseProvider instanceof ConnectorUserProvider) {
+      const connectorProvider = this.baseProvider;
+      user = connectorProvider.getUserSync();
+    }
+    return {
+      ...context,
+      ...user,
+    };
+  }
+
+  async getUser(): Promise<ExperimentUser> {
+    const context = await this.getApplicationContext();
+    const baseUser = await this.baseProvider?.getUser();
+    return {
+      ...context,
+      ...(baseUser ?? {}),
+    };
+  }
+
+  private shouldPollUserCache(): boolean {
+    return (
+      !!this.baseProvider &&
+      !(this.baseProvider instanceof ConnectorUserProvider)
+    );
+  }
+}

package/src/experiment/logger/ampLogger.ts

@@ -0,0 +1,76 @@
+import { Logger, LogLevel } from "../types/logger";
+
+/**
+ * Internal logger class that wraps a Logger implementation and handles log level filtering.
+ * This class provides a centralized logging mechanism for the Experiment client.
+ * @category Logging
+ */
+export class AmpLogger implements Logger {
+  private readonly logger: Logger;
+  private readonly logLevel: LogLevel;
+
+  /**
+   * Creates a new AmpLogger instance
+   * @param logger The underlying logger implementation to use
+   * @param logLevel The minimum log level to output. Messages below this level will be ignored.
+   */
+  constructor(logger: Logger, logLevel: LogLevel = LogLevel.Error) {
+    this.logger = logger;
+    this.logLevel = logLevel;
+  }
+
+  /**
+   * Log an error message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  error(message?: any, ...optionalParams: any[]): void {
+    if (this.logLevel >= LogLevel.Error) {
+      this.logger.error(message, ...optionalParams);
+    }
+  }
+
+  /**
+   * Log a warning message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  warn(message?: any, ...optionalParams: any[]): void {
+    if (this.logLevel >= LogLevel.Warn) {
+      this.logger.warn(message, ...optionalParams);
+    }
+  }
+
+  /**
+   * Log an informational message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  info(message?: any, ...optionalParams: any[]): void {
+    if (this.logLevel >= LogLevel.Info) {
+      this.logger.info(message, ...optionalParams);
+    }
+  }
+
+  /**
+   * Log a debug message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  debug(message?: any, ...optionalParams: any[]): void {
+    if (this.logLevel >= LogLevel.Debug) {
+      this.logger.debug(message, ...optionalParams);
+    }
+  }
+
+  /**
+   * Log a verbose message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  verbose(message?: any, ...optionalParams: any[]): void {
+    if (this.logLevel >= LogLevel.Verbose) {
+      this.logger.verbose(message, ...optionalParams);
+    }
+  }
+}

package/src/experiment/logger/consoleLogger.ts

@@ -0,0 +1,54 @@
+import { Logger } from "../types/logger";
+
+/**
+ * Default console-based logger implementation.
+ * This logger uses the browser's console API to output log messages.
+ * Log level filtering is handled by the AmpLogger wrapper class.
+ * @category Logging
+ */
+export class ConsoleLogger implements Logger {
+  /**
+   * Log an error message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  error(message?: any, ...optionalParams: any[]): void {
+    console.error(message, ...optionalParams);
+  }
+
+  /**
+   * Log a warning message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  warn(message?: any, ...optionalParams: any[]): void {
+    console.warn(message, ...optionalParams);
+  }
+
+  /**
+   * Log an informational message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  info(message?: any, ...optionalParams: any[]): void {
+    console.info(message, ...optionalParams);
+  }
+
+  /**
+   * Log a debug message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  debug(message?: any, ...optionalParams: any[]): void {
+    console.debug(message, ...optionalParams);
+  }
+
+  /**
+   * Log a verbose message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  verbose(message?: any, ...optionalParams: any[]): void {
+    console.debug(message, ...optionalParams);
+  }
+}