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

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,51 @@
+{
+  "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": "yarn bundle && yarn build:es5 && yarn 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": "yarn fix:eslint & yarn fix:prettier",
+    "fix:eslint": "eslint '{src,test}/**/*.ts' --fix",
+    "fix:prettier": "prettier --write \"{src,test}/**/*.ts\"",
+    "lint": "yarn lint:eslint & yarn 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": "^2.27.0",
+    "tslib": "^2.4.1"
+
+  },
+  "devDependencies": {
+
+  },
+  "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,53 @@
+import type { BrowserClient, BrowserConfig, EnrichmentPlugin, Event, ILogger } from '@amplitude/analytics-core';
+
+export const customEnrichmentPlugin = (): EnrichmentPlugin => {
+  let loggerProvider: ILogger | undefined = undefined;
+  let customEnrichmentBody: string | undefined = undefined;
+
+  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.fetchRemoteConfig) {
+        if (!config.remoteConfigClient) {
+          // TODO(xinyi): Diagnostics.recordEvent
+          config.loggerProvider.debug('Remote config client is not provided, skipping remote config fetch');
+        } else {
+          config.remoteConfigClient.subscribe('analyticsSDK.customEnrichment', 'all', (remoteConfig) => {
+            if (remoteConfig) {
+              customEnrichmentBody = remoteConfig.body as string | undefined;
+            }
+          });
+        }
+      }
+    },
+    execute: async (event: Event) => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-implied-eval
+        const enrichEvent = new Function('event', customEnrichmentBody || '') as (event: Event) => Event;
+
+        const enrichedEvent: Event = enrichEvent(event);
+
+        if (!enrichedEvent) {
+          return event;
+        }
+
+        return enrichedEvent;
+      } catch (error) {
+        loggerProvider?.error('Could not execute custom enrichment function', error);
+      }
+
+      return event;
+    },
+    teardown: async () => {
+      // No teardown required
+    },
+  };
+
+  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';