feat(plugin-custom-enrichment): add custom enrichment plugin

packages/analytics-core/src/index.ts

@@ -99,6 +99,7 @@ export { NetworkTrackingOptions, NetworkCaptureRule } from './types/network-trac
 export { SAFE_HEADERS, FORBIDDEN_HEADERS } from './types/constants';
 
 export { PageUrlEnrichmentOptions } from './types/page-url-enrichment';
+export { CustomEnrichmentOptions } from './types/custom-enrichment';
 
 // Campaign
 export { Campaign, UTMParameters, ReferrerParameters, ClickIdParameters, ICampaignParser } from './types/campaign';

packages/analytics-core/src/types/custom-enrichment.ts

@@ -0,0 +1,7 @@
+/**
+ * @experimental this feature is experimental and may not be stable
+ */
+
+export interface CustomEnrichmentOptions {
+  body: string;
+}

packages/plugin-custom-enrichment-browser/CHANGELOG.md

@@ -0,0 +1 @@
+# Change Log

packages/plugin-custom-enrichment-browser/README.md

@@ -0,0 +1,63 @@
+<p align="center">
+  <a href="https://amplitude.com" target="_blank" align="center">
+    <img src="https://static.amplitude.com/lightning/46c85bfd91905de8047f1ee65c7c93d6fa9ee6ea/static/media/amplitude-logo-with-text.4fb9e463.svg" width="280">
+  </a>
+  <br />
+</p>
+
+# @amplitude/plugin-custom-enrichment-browser
+
+Official Browser SDK plugin for custom enrichment
+
+## Installation
+
+This package is published on NPM registry and is available to be installed using npm and yarn.
+
+```sh
+# npm
+npm install @amplitude/plugin-custom-enrichment-browser
+
+# yarn
+yarn add @amplitude/plugin-custom-enrichment-browser
+```
+
+## Usage
+
+This plugin works on top of Amplitude Browser SDK and allows the user to execute custom functionality on their events. To use this plugin, you need to install `@amplitude/analytics-browser` version `v2.0.0` or later.
+
+### 1. Import Amplitude packages
+
+* `@amplitude/plugin-custom-enrichment-browser`
+
+```typescript
+import { customEnrichmentPlugin } from '@amplitude/plugin-custom-enrichment-browser';
+```
+
+### 2. Instantiate custom enrichment plugin
+```typescript
+const customEnrichmentPlugin = customEnrichmentPlugin();
+```
+
+#### Options
+
+
+### 3. Install plugin to Amplitude SDK
+
+```typescript
+amplitude.add(customEnrichmentPlugin);
+```
+
+### 4. Initialize Amplitude SDK
+
+```typescript
+amplitude.init('API_KEY');
+```
+
+## Result
+This plugin executes a user-defined script, defined within Amplitude Remote Configuration Settings.
+
+#### Event type
+* No event type added
+
+#### Event properties
+* Defined by user

packages/plugin-custom-enrichment-browser/jest.config.js

@@ -0,0 +1,10 @@
+const baseConfig = require('../../jest.config.js');
+const package = require('./package');
+
+module.exports = {
+  ...baseConfig,
+  displayName: package.name,
+  rootDir: '.',
+  testEnvironment: 'jsdom',
+  coveragePathIgnorePatterns: ['index.ts'],
+};

packages/plugin-custom-enrichment-browser/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@amplitude/plugin-custom-enrichment-browser",
+  "private": true,
+  "version": "0.0.1",
+  "description": "",
+  "author": "Amplitude Inc",
+  "homepage": "https://github.com/amplitude/Amplitude-TypeScript",
+  "license": "MIT",
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.js",
+  "types": "lib/esm/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amplitude/Amplitude-TypeScript.git"
+  },
+  "scripts": {
+    "build": "pnpm bundle && pnpm build:es5 && pnpm build:esm",
+    "bundle": "rollup --config rollup.config.js",
+    "build:es5": "tsc -p ./tsconfig.es5.json",
+    "build:esm": "tsc -p ./tsconfig.esm.json",
+    "watch": "tsc -p ./tsconfig.esm.json --watch",
+    "clean": "rimraf node_modules lib coverage",
+    "fix": "pnpm fix:eslint & pnpm fix:prettier",
+    "fix:eslint": "eslint '{src,test}/**/*.ts' --fix",
+    "fix:prettier": "prettier --write \"{src,test}/**/*.ts\"",
+    "lint": "pnpm lint:eslint & pnpm lint:prettier",
+    "lint:eslint": "eslint '{src,test}/**/*.ts'",
+    "lint:prettier": "prettier --check \"{src,test}/**/*.ts\"",
+    "test": "jest",
+    "typecheck": "tsc -p ./tsconfig.json"
+  },
+  "bugs": {
+    "url": "https://github.com/amplitude/Amplitude-TypeScript/issues"
+  },
+  "dependencies": {
+    "@amplitude/analytics-core": "workspace:*",
+    "tslib": "^2.4.1"
+
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^23.0.4",
+    "@rollup/plugin-node-resolve": "^15.0.1",
+    "@rollup/plugin-typescript": "^10.0.1",
+    "rollup": "^2.79.1",
+    "rollup-plugin-execute": "^1.1.1",
+    "rollup-plugin-gzip": "^3.1.0",
+    "rollup-plugin-terser": "^7.0.2"
+  },
+  "files": [
+    "lib"
+  ]
+}

packages/plugin-custom-enrichment-browser/rollup.config.js

@@ -0,0 +1,3 @@
+import { umd } from '../../scripts/build/rollup.config';
+
+export default [umd];

packages/plugin-custom-enrichment-browser/src/custom-enrichment.ts

@@ -0,0 +1,91 @@
+import type {
+  BrowserClient,
+  BrowserConfig,
+  CustomEnrichmentOptions,
+  EnrichmentPlugin,
+  Event,
+  ILogger,
+  RemoteConfig,
+} from '@amplitude/analytics-core';
+
+export const customEnrichmentPlugin = (): EnrichmentPlugin => {
+  let loggerProvider: ILogger | undefined;
+  let unsubscribe: (() => void) | undefined;
+
+  let enrichEvent: ((event: Event) => Event) | undefined;
+
+  function isCustomEnrichmentConfig(config: RemoteConfig): config is CustomEnrichmentOptions {
+    // 1. Check if it's an object and not null
+    if (typeof config !== 'object' || config === null) {
+      return false;
+    }
+
+    // 2. Validate specific properties exist and are the correct type
+    return 'body' in config && typeof config.body === 'string';
+  }
+
+  function createEnrichEvent(body: string): (event: Event) => Event {
+    if (body) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-implied-eval
+        return new Function('event', body) as (event: Event) => Event;
+      } catch (error) {
+        loggerProvider?.error('Could not create custom enrichment function', error);
+      }
+    }
+
+    // if there was no content, return a function that returns the event unchanged
+    return (event: Event) => event;
+  }
+
+  const plugin: EnrichmentPlugin = {
+    name: '@amplitude/plugin-custom-enrichment-browser',
+    type: 'enrichment',
+
+    setup: async (config: BrowserConfig, _: BrowserClient) => {
+      loggerProvider = config.loggerProvider;
+      loggerProvider?.log('Installing @amplitude/plugin-custom-enrichment-browser');
+
+      // Fetch remote config for custom enrichment in a non-blocking manner
+      if (config.remoteConfig?.fetchRemoteConfig) {
+        if (!config.remoteConfigClient) {
+          // TODO(xinyi): Diagnostics.recordEvent
+          loggerProvider?.debug('Remote config client is not provided, skipping remote config fetch');
+        } else {
+          const subscriptionId = config.remoteConfigClient.subscribe(
+            'configs.analyticsSDK.browserSDK.customEnrichment',
+            'all',
+            (remoteConfig: RemoteConfig | null) => {
+              if (remoteConfig && isCustomEnrichmentConfig(remoteConfig)) {
+                enrichEvent = createEnrichEvent(remoteConfig.body || '');
+              } else {
+                // if there is no valid body, clear enrich event
+                enrichEvent = createEnrichEvent('');
+              }
+            },
+          );
+          unsubscribe = () => config.remoteConfigClient?.unsubscribe(subscriptionId);
+        }
+      }
+    },
+    execute: async (event: Event) => {
+      if (enrichEvent) {
+        try {
+          return enrichEvent(event) ?? null;
+        } catch (error) {
+          loggerProvider?.error('Could not execute custom enrichment function', error);
+          return event;
+        }
+      }
+
+      return event;
+    },
+    teardown: async () => {
+      if (unsubscribe) {
+        unsubscribe();
+      }
+    },
+  };
+
+  return plugin;
+};

packages/plugin-custom-enrichment-browser/src/index.ts

@@ -0,0 +1,2 @@
+export { customEnrichmentPlugin } from './custom-enrichment';
+export { customEnrichmentPlugin as plugin } from './custom-enrichment';