@amplytools/react-native-amply-sdk 0.1.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@amplytools/react-native-amply-sdk",
+  "version": "0.1.0",
+  "description": "React Native SDK for Amply: Mobile SDK to orchestrate in-app experiences and campaigns remotely, without app releases",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amply/amply-react-native.git"
+  },
+  "homepage": "https://github.com/amply/amply-react-native",
+  "bugs": {
+    "url": "https://github.com/amply/amply-react-native/issues"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/src/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "android/",
+    "!android/.cxx/",
+    "!android/build/",
+    "!android/.gradle/",
+    "ios/",
+    "dist/",
+    "src/",
+    "plugin/",
+    "scripts/",
+    "react-native.config.js",
+    "app.plugin.js",
+    "expo-module.config.json",
+    "README.md",
+    "docs/"
+  ],
+  "scripts": {
+    "build": "expo-module build",
+    "build:plugin": "expo-module build plugin",
+    "clean": "expo-module clean",
+    "test": "expo-module test",
+    "prepare": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly"
+  },
+  "peerDependencies": {
+    "expo": ">=54.0.0",
+    "react": ">=18.2.0",
+    "react-native": ">=0.79.0"
+  },
+  "devDependencies": {
+    "@react-native/codegen": "0.81.4",
+    "@react-native/eslint-config": "^0.74.81",
+    "@react-native/typescript-config": "0.81.0",
+    "@types/jest": "^29.5.11",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.1.1",
+    "@types/react-native": "^0.73.0",
+    "eslint": "^8.56.0",
+    "expo": "^54.0.0",
+    "expo-module-scripts": "^3.5.0",
+    "jest": "^29.7.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "expo": {
+    "plugin": "./app.plugin.js"
+  }
+}

package/plugin/build/index.d.ts

@@ -0,0 +1,5 @@
+import type { ConfigPlugin } from '@expo/config-plugins';
+declare const plugin: ConfigPlugin<{
+    sdkVersion?: string;
+}>;
+export default plugin;

package/plugin/build/index.js

@@ -0,0 +1,8 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const withAmply_1 = __importDefault(require("./withAmply"));
+const plugin = (config, props) => (0, withAmply_1.default)(config, props);
+exports.default = plugin;

package/plugin/build/withAmply.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Expo Config Plugin for Amply React Native SDK
+ *
+ * The Amply React Native SDK is a TurboModule that uses react-native.config.js
+ * for autolinking in Bare React Native. For Expo apps, this plugin ensures
+ * AmplyPackage is registered in MainApplication (Android).
+ *
+ * iOS: AmplySDK is fetched automatically from CocoaPods Trunk via the podspec
+ * dependency declaration - no Podfile modifications needed.
+ *
+ * Architecture:
+ * - Bare RN: Uses react-native.config.js autolinking (fully automatic)
+ * - Expo: Uses react-native.config.js + Expo config plugin for Android registration
+ *
+ * Usage:
+ * 1. Add to app.json: "@amply/amply-react-native" in plugins array
+ * 2. Run: expo prebuild --clean
+ * 3. Run: expo start and expo run:android/ios
+ */
+import { ConfigPlugin } from '@expo/config-plugins';
+type WithAmplyPluginProps = {};
+/**
+ * Expo Config Plugin for Amply React Native SDK
+ *
+ * Registers AmplyPackage in MainApplication for Expo apps (Android).
+ * iOS uses CocoaPods Trunk for AmplySDK - no modifications needed.
+ */
+declare const withAmply: ConfigPlugin<WithAmplyPluginProps>;
+export default withAmply;

package/plugin/build/withAmply.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Expo Config Plugin for Amply React Native SDK
+ *
+ * The Amply React Native SDK is a TurboModule that uses react-native.config.js
+ * for autolinking in Bare React Native. For Expo apps, this plugin ensures
+ * AmplyPackage is registered in MainApplication (Android).
+ *
+ * iOS: AmplySDK is fetched automatically from CocoaPods Trunk via the podspec
+ * dependency declaration - no Podfile modifications needed.
+ *
+ * Architecture:
+ * - Bare RN: Uses react-native.config.js autolinking (fully automatic)
+ * - Expo: Uses react-native.config.js + Expo config plugin for Android registration
+ *
+ * Usage:
+ * 1. Add to app.json: "@amply/amply-react-native" in plugins array
+ * 2. Run: expo prebuild --clean
+ * 3. Run: expo start and expo run:android/ios
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("@expo/config-plugins");
+/**
+ * Modifies Android MainApplication to register AmplyPackage
+ */
+const withAmplyAndroid = (config) => {
+    return (0, config_plugins_1.withMainApplication)(config, async (cfg) => {
+        let contents = cfg.modResults.contents;
+        // Check if AmplyPackage is already imported
+        if (!contents.includes('import tools.amply.sdk.reactnative.AmplyPackage')) {
+            // Add import after the expo imports
+            contents = contents.replace(/(import expo\.modules\.ReactNativeHostWrapper)/, `import tools.amply.sdk.reactnative.AmplyPackage\n$1`);
+        }
+        // For Kotlin syntax: packages.apply { ... }
+        // We need to add the package instance inside the apply block
+        if (!contents.includes('add(AmplyPackage())')) {
+            contents = contents.replace(/(PackageList\(this\)\.packages\.apply \{[\s\S]*?)(\/\/ add.*?)\n(\s+\})/, `$1$2\n              add(AmplyPackage())\n$3`);
+        }
+        cfg.modResults.contents = contents;
+        return cfg;
+    });
+};
+/**
+ * Expo Config Plugin for Amply React Native SDK
+ *
+ * Registers AmplyPackage in MainApplication for Expo apps (Android).
+ * iOS uses CocoaPods Trunk for AmplySDK - no modifications needed.
+ */
+const withAmply = (config) => {
+    // Apply Android modifications
+    return withAmplyAndroid(config);
+};
+exports.default = withAmply;

package/plugin/src/index.ts

@@ -0,0 +1,7 @@
+import type {ConfigPlugin} from '@expo/config-plugins';
+import withAmply from './withAmply';
+
+const plugin: ConfigPlugin<{ sdkVersion?: string }> = (config, props) =>
+  withAmply(config, props);
+
+export default plugin;

package/plugin/src/withAmply.ts

@@ -0,0 +1,68 @@
+/**
+ * Expo Config Plugin for Amply React Native SDK
+ *
+ * The Amply React Native SDK is a TurboModule that uses react-native.config.js
+ * for autolinking in Bare React Native. For Expo apps, this plugin ensures
+ * AmplyPackage is registered in MainApplication (Android).
+ *
+ * iOS: AmplySDK is fetched automatically from CocoaPods Trunk via the podspec
+ * dependency declaration - no Podfile modifications needed.
+ *
+ * Architecture:
+ * - Bare RN: Uses react-native.config.js autolinking (fully automatic)
+ * - Expo: Uses react-native.config.js + Expo config plugin for Android registration
+ *
+ * Usage:
+ * 1. Add to app.json: "@amply/amply-react-native" in plugins array
+ * 2. Run: expo prebuild --clean
+ * 3. Run: expo start and expo run:android/ios
+ */
+
+import { ConfigPlugin, withMainApplication } from '@expo/config-plugins';
+
+type WithAmplyPluginProps = {
+  // Props for future use
+};
+
+/**
+ * Modifies Android MainApplication to register AmplyPackage
+ */
+const withAmplyAndroid: ConfigPlugin = (config) => {
+  return withMainApplication(config, async (cfg) => {
+    let contents = cfg.modResults.contents;
+
+    // Check if AmplyPackage is already imported
+    if (!contents.includes('import tools.amply.sdk.reactnative.AmplyPackage')) {
+      // Add import after the expo imports
+      contents = contents.replace(
+        /(import expo\.modules\.ReactNativeHostWrapper)/,
+        `import tools.amply.sdk.reactnative.AmplyPackage\n$1`
+      );
+    }
+
+    // For Kotlin syntax: packages.apply { ... }
+    // We need to add the package instance inside the apply block
+    if (!contents.includes('add(AmplyPackage())')) {
+      contents = contents.replace(
+        /(PackageList\(this\)\.packages\.apply \{[\s\S]*?)(\/\/ add.*?)\n(\s+\})/,
+        `$1$2\n              add(AmplyPackage())\n$3`
+      );
+    }
+
+    cfg.modResults.contents = contents;
+    return cfg;
+  });
+};
+
+/**
+ * Expo Config Plugin for Amply React Native SDK
+ *
+ * Registers AmplyPackage in MainApplication for Expo apps (Android).
+ * iOS uses CocoaPods Trunk for AmplySDK - no modifications needed.
+ */
+const withAmply: ConfigPlugin<WithAmplyPluginProps> = (config) => {
+  // Apply Android modifications
+  return withAmplyAndroid(config);
+};
+
+export default withAmply;

package/plugin/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "expo-module-scripts/tsconfig.plugin",
+  "compilerOptions": {
+    "outDir": "build",
+    "rootDir": "src"
+  },
+  "include": ["./src"]
+}

package/plugin/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts","./src/withamply.ts"],"version":"5.9.3"}

package/react-native.config.js

@@ -0,0 +1,34 @@
+const path = require('path');
+
+const codegenSourceDirAndroid = path.join(__dirname, 'android', 'src', 'newarch');
+const codegenSourceDirIos = path.join(__dirname, 'ios', 'Sources', 'AmplyReactNative');
+const androidProjectDir = path.join(__dirname, 'android');
+const androidJniDir = path.join(androidProjectDir, 'src', 'main', 'jni');
+
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: androidProjectDir,
+        packageImportPath: 'import tools.amply.sdk.reactnative.AmplyPackage;',
+        packageInstance: 'new AmplyPackage()',
+        cmakeListsPath: path.join(androidJniDir, 'CMakeLists.txt'),
+      },
+      ios: null,
+    },
+  },
+  commands: [],
+  assets: [],
+  codegenConfig: {
+    name: 'AmplyReactNative',
+    type: 'modules',
+    jsSrcsDir: path.join(__dirname, 'src'),
+    android: {
+      sourceDir: codegenSourceDirAndroid,
+      packageName: 'tools.amply.sdk.reactnative',
+    },
+    ios: {
+      sourceDir: codegenSourceDirIos,
+    },
+  },
+};

package/scripts/codegen.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+const path = require('path');
+const fs = require('fs');
+const {
+  combineSchemasInFileList,
+} = require('@react-native/codegen/lib/cli/combine/combine-js-to-schema');
+const RNCodegen = require('@react-native/codegen/lib/generators/RNCodegen');
+
+const ROOT = path.resolve(__dirname, '..');
+const configPath = path.join(ROOT, 'codegen.config.json');
+const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+
+/**
+ * Clean up stale generated files from previous codegen runs with different libraryName.
+ * RN codegen doesn't automatically clean old files when libraryName changes.
+ */
+function cleanupStaleGeneratedFiles(outputDir, currentLibraryName) {
+  if (!fs.existsSync(outputDir)) {
+    return;
+  }
+
+  const files = fs.readdirSync(outputDir);
+  const stalePatterns = [
+    /-generated\.(cpp|h)$/,  // Files ending in -generated.cpp or -generated.h
+    /^[^/]+(\.h)$/,          // Header files
+  ];
+
+  // Only delete files that don't match current library name
+  files.forEach(file => {
+    if (file.includes(currentLibraryName)) {
+      return;  // Keep files with current library name
+    }
+
+    if (stalePatterns.some(pattern => pattern.test(file))) {
+      const filePath = path.join(outputDir, file);
+      try {
+        fs.unlinkSync(filePath);
+      } catch (err) {
+        // Silently ignore - might be a directory
+      }
+    }
+  });
+}
+
+/**
+ * Патчим android/src/newarch/jni/CMakeLists.txt после генерации.
+ * RN 0.79 в Gradle передаёт в CMake параметр:
+ *   -DREACT_NATIVE_DIR=/.../node_modules/react-native
+ *
+ * Мы из него делаем REACT_COMMON_DIR и подрубаем
+ *   ReactCommon/cmake-utils/react-native-flags.cmake
+ * Там как раз и объявлен target_compile_reactnative_options.
+ */
+function patchAndroidCMake(cmakePath) {
+  if (!fs.existsSync(cmakePath)) {
+    return;
+  }
+
+  const original = fs.readFileSync(cmakePath, 'utf-8');
+
+  // Уже патчили — выходим.
+  if (original.includes('react-native-flags.cmake')) {
+    return;
+  }
+
+  const insertSnippet = `
+# --- React Native 0.79: wire up compile flags ---
+if(NOT DEFINED REACT_NATIVE_DIR)
+  message(FATAL_ERROR "REACT_NATIVE_DIR is not defined; it must point to node_modules/react-native")
+endif()
+
+# Gradle (externalNativeBuild) passes REACT_NATIVE_DIR.
+# From it we derive ReactCommon path used by RN CMake utils.
+set(REACT_COMMON_DIR "\${REACT_NATIVE_DIR}/ReactCommon")
+
+# This provides target_compile_reactnative_options and imported targets
+# like 'reactnative', 'jsi', 'fbjni', etc.
+include(\${REACT_COMMON_DIR}/cmake-utils/react-native-flags.cmake)
+# --- end RN wiring ---
+`.trim();
+
+  const linesIn = original.split('\n');
+  const linesOut = [];
+  let inserted = false;
+
+  for (let i = 0; i < linesIn.length; i++) {
+    const line = linesIn[i];
+    linesOut.push(line);
+
+    // Вставляем наш блок сразу после set(CMAKE_VERBOSE_MAKEFILE on)
+    if (!inserted && line.match(/set\s*\(\s*CMAKE_VERBOSE_MAKEFILE\s+on\s*\)/)) {
+      linesOut.push('');
+      linesOut.push(insertSnippet);
+      linesOut.push('');
+      inserted = true;
+    }
+  }
+
+  const updated = linesOut.join('\n');
+  fs.writeFileSync(cmakePath, updated);
+}
+
+/**
+ * Patch the newarch CMakeLists.txt to add missing JSI include directories
+ * and ensure proper inclusion of React headers.
+ */
+function enhanceNewarchCMake(cmakePath) {
+  if (!fs.existsSync(cmakePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(cmakePath, 'utf-8');
+
+  // Check if we've already added the JSI includes
+  if (content.includes('REACT_JSI_DIR')) {
+    return;
+  }
+
+  // Additional imports needed for generated TurboModule code
+  const jsiEnhancement = `\n# Ensure fbjni is available as imported target
+find_package(fbjni REQUIRED CONFIG)
+
+# For OBJECT libraries, we need to explicitly add include directories since
+# target_link_libraries doesn't propagate INTERFACE_INCLUDE_DIRECTORIES for OBJECT libs
+set(REACT_JSI_DIR "\${REACT_COMMON_DIR}/jsi")
+`;
+
+  // Insert after the react-native-flags.cmake include, before file(GLOB...)
+  content = content.replace(
+    /# --- end RN wiring ---\n\n\nfile\(GLOB/,
+    '# --- end RN wiring ---' + jsiEnhancement + '\nfile(GLOB'
+  );
+
+  // For OBJECT libraries, we need to add JSI include directories explicitly
+  // Note: folly and reactnative includes will be added by the parent CMakeLists.txt
+  // after targets are created. We only need JSI here since it's a source directory.
+  const includePattern = /target_include_directories\(react_codegen_\w+ PUBLIC \. react\/renderer\/components\/\w+\)/g;
+  content = content.replace(includePattern, (match) => {
+    if (match.includes('${REACT_JSI_DIR}')) {
+      return match;  // Already has includes
+    }
+    // Add JSI include path
+    return match.replace(')', ` \${REACT_JSI_DIR})`);
+  });
+
+  // Remove target_link_libraries from OBJECT library
+  // OBJECT libraries don't need to be linked in the generated CMakeLists
+  // The parent CMakeLists will link the main library against the necessary targets
+  // and add includes for the OBJECT library separately.
+  // This avoids duplicate linking and unresolved symbols in the final link step.
+  content = content.replace(
+    /target_link_libraries\([^)]+fbjni[^)]+jsi[^)]+reactnative[^)]*\)\n/s,
+    ''
+  );
+
+  fs.writeFileSync(cmakePath, content);
+}
+
+/**
+ * Генерация для одного модуля из codegen.config.json
+ */
+function generateModule(name, moduleConfig) {
+  const jsSpecFile = path.resolve(ROOT, moduleConfig.jsSpecFile);
+  const schema = combineSchemasInFileList([jsSpecFile]);
+  const libraryName = moduleConfig.libraryName ?? name;
+
+  const androidConfig = moduleConfig.android;
+  if (androidConfig && androidConfig.sourceDir) {
+    const outputDirectory = path.resolve(ROOT, androidConfig.sourceDir);
+    const jniDir = path.join(outputDirectory, 'jni');
+
+    // Clean up stale files before generating
+    cleanupStaleGeneratedFiles(jniDir, libraryName);
+
+    RNCodegen.generate(
+      {
+        libraryName,
+        schema,
+        outputDirectory,
+        packageName: androidConfig.packageName ?? 'com.facebook.fbreact.specs',
+        assumeNonnull: true,
+      },
+      {generators: ['modulesAndroid']},
+    );
+
+    const cmakePath = path.join(outputDirectory, 'jni', 'CMakeLists.txt');
+    patchAndroidCMake(cmakePath);
+    enhanceNewarchCMake(cmakePath);  // Add JSI and React header configurations
+  }
+
+  const iosConfig = moduleConfig.ios;
+  if (iosConfig && iosConfig.sourceDir) {
+    RNCodegen.generate(
+      {
+        libraryName,
+        schema,
+        outputDirectory: path.resolve(ROOT, iosConfig.sourceDir),
+        moduleName: iosConfig.moduleName ?? libraryName,
+        assumeNonnull: true,
+      },
+      {generators: ['modulesIOS']},
+    );
+  }
+}
+
+// Обрабатываем все модули из codegen.config.json
+Object.entries(config.modules).forEach(([name, moduleConfig]) => {
+  if (moduleConfig.type !== 'NativeModule') {
+    return;
+  }
+  generateModule(name, moduleConfig);
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,92 @@
+import * as Amply from '../index';
+import {__setNativeModule} from '../nativeModule';
+
+const mockNativeModule = {
+  initialize: jest.fn(),
+  isInitialized: jest.fn(() => true),
+  track: jest.fn(),
+  getRecentEvents: jest.fn(),
+  getDataSetSnapshot: jest.fn(),
+  registerDeepLinkListener: jest.fn(),
+  addListener: jest.fn(),
+  removeListeners: jest.fn(),
+  onSystemEvent: jest.fn(),
+  onDeepLink: jest.fn(),
+};
+
+describe('Amply JS API', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+    __setNativeModule(null);
+  });
+
+  beforeEach(() => {
+    __setNativeModule(mockNativeModule as never);
+  });
+
+  it('initializes the native module', async () => {
+    await Amply.initialize({ appId: 'id', apiKeyPublic: 'public' });
+
+    expect(mockNativeModule.initialize).toHaveBeenCalledWith(
+      expect.objectContaining({ appId: 'id', apiKeyPublic: 'public' })
+    );
+  });
+
+  it('tracks events through the native layer', async () => {
+    await Amply.track({ name: 'Test Event', properties: { foo: 'bar' } });
+
+    expect(mockNativeModule.track).toHaveBeenCalledWith({
+      name: 'Test Event',
+      properties: { foo: 'bar' },
+    });
+  });
+
+  it('reads recent events', async () => {
+    const events = [{ name: 'e1' }];
+    mockNativeModule.getRecentEvents.mockResolvedValueOnce(events);
+
+    const result = await Amply.getRecentEvents(3);
+
+    expect(mockNativeModule.getRecentEvents).toHaveBeenCalledWith(3);
+    expect(result).toBe(events);
+  });
+
+  it('requests dataset snapshots', async () => {
+    const snapshot = { foo: 'bar' };
+    mockNativeModule.getDataSetSnapshot.mockResolvedValueOnce(snapshot);
+
+    const type = { kind: '@device' as const };
+    const result = await Amply.getDataSetSnapshot(type);
+
+    expect(mockNativeModule.getDataSetSnapshot).toHaveBeenCalledWith(type);
+    expect(result).toBe(snapshot);
+  });
+
+  it('subscribes to system events through the TurboModule emitter', async () => {
+    const remove = jest.fn();
+    mockNativeModule.onSystemEvent.mockReturnValueOnce({ remove });
+
+    const listener = jest.fn();
+    const unsubscribe = await Amply.addSystemEventListener(listener);
+
+    expect(mockNativeModule.onSystemEvent).toHaveBeenCalledWith(listener);
+    unsubscribe();
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('registers deep links once and subscribes via the TurboModule emitter', async () => {
+    const remove = jest.fn();
+    mockNativeModule.onDeepLink.mockReturnValue({ remove });
+
+    const listener = jest.fn();
+    const unsubscribe = await Amply.addDeepLinkListener(listener);
+    expect(mockNativeModule.registerDeepLinkListener).toHaveBeenCalledTimes(1);
+    expect(mockNativeModule.onDeepLink).toHaveBeenCalledWith(listener);
+
+    await Amply.addDeepLinkListener(() => {});
+    expect(mockNativeModule.registerDeepLinkListener).toHaveBeenCalledTimes(1);
+
+    unsubscribe();
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useAmplySystemEvents.ts

@@ -0,0 +1,75 @@
+import {useCallback, useEffect, useRef, useState} from 'react';
+import type {EventRecord} from '../nativeSpecs/NativeAmplyModule';
+import {addSystemEventListener} from '../systemEvents';
+
+export type UseAmplySystemEventsOptions = {
+  maxEntries?: number;
+  dedupe?: boolean;
+  onEvent?: (event: EventRecord) => void;
+};
+
+export type UseAmplySystemEventsResult = {
+  events: EventRecord[];
+  reset: () => void;
+};
+
+export function useAmplySystemEvents(
+  options: UseAmplySystemEventsOptions = {},
+): UseAmplySystemEventsResult {
+  const {maxEntries = 50, dedupe = true, onEvent} = options;
+  const [events, setEvents] = useState<EventRecord[]>([]);
+  const seenKeysRef = useRef<Set<string>>(new Set());
+  const handlerRef = useRef<typeof onEvent>(onEvent);
+
+  useEffect(() => {
+    handlerRef.current = onEvent;
+  }, [onEvent]);
+
+  useEffect(() => {
+    let unsubscribe: (() => void) | undefined;
+    let isMounted = true;
+
+    addSystemEventListener(event => {
+      if (!isMounted) {
+        return;
+      }
+      if (dedupe) {
+        const key = `${event.name}-${event.timestamp}`;
+        if (seenKeysRef.current.has(key)) {
+          return;
+        }
+        seenKeysRef.current.add(key);
+      }
+      handlerRef.current?.(event);
+      setEvents(prev => {
+        const next = [...prev, event];
+        if (next.length > maxEntries) {
+          next.splice(0, next.length - maxEntries);
+        }
+        return next;
+      });
+    })
+      .then(unsub => {
+        if (!isMounted) {
+          unsub();
+        } else {
+          unsubscribe = unsub;
+        }
+      })
+      .catch(error => {
+        console.warn('[Amply] system event listener error', error);
+      });
+
+    return () => {
+      isMounted = false;
+      unsubscribe?.();
+    };
+  }, [dedupe, maxEntries]);
+
+  const reset = useCallback(() => {
+    seenKeysRef.current.clear();
+    setEvents([]);
+  }, []);
+
+  return {events, reset};
+}