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

[cyhk]

Summary

This adds the custom enrichment plugin, which users can use to run their own code on properties, when they have remote config appropriately configured.

Pending backend and frontend work on the Amplitude side. Not ready for merge yet.

Checklist

• Does your PR title have the correct title format?
• Does your PR have a breaking change?:

---

Note

High Risk
Introduces dynamic execution of remote-config-provided JavaScript via new Function, which is security-sensitive and can impact event integrity/PII if misconfigured or compromised.

Overview
Adds a new browser plugin @amplitude/plugin-custom-enrichment-browser that subscribes to a remote config key and, when present, compiles and runs a user-provided script to mutate events during the enrichment phase (with error handling and teardown unsubscribe).

Exposes a new CustomEnrichmentOptions type from @amplitude/analytics-core, adds full package build/test scaffolding + docs for the new plugin, and makes a small type-only import cleanup in the page URL enrichment plugin.

^{Written by Cursor Bugbot for commit effc900. This will update automatically on new commits. Configure here.}

[Dogfalo]

Can we resolve this TODO somehow?

[cyhk]

hmm I just copied this over from autocapture-plugin.ts - felt like it made sense to preserve it given the similar logic to fetch the remote config.

[macroscopeapp]

Add browser @amplitude/plugin-custom-enrichment-browser to apply remote-configured event enrichment via packages/plugin-custom-enrichment-browser/src/custom-enrichment.ts::customEnrichmentPlugin

Introduce a browser enrichment plugin that constructs and runs a dynamic Function for event mutation, subscribes to analyticsSDK.customEnrichment remote config when available, and exposes customEnrichmentPlugin via packages/plugin-custom-enrichment-browser/src/index.ts. Add supporting types in packages/analytics-core/src/types/custom-enrichment.ts and tests in packages/plugin-custom-enrichment-browser/test/custom-enrichment.test.ts.

🖇️ Linked Issues

Implements the task AMP-139971 under the epic AMP-139965 by adding the remote config enrichment plugin for the browser.

📍Where to Start

Start with the plugin factory and lifecycle in packages/plugin-custom-enrichment-browser/src/custom-enrichment.ts.

Changes since #1339 opened

• Rewrote customEnrichmentPlugin factory in @amplitude/plugin-custom-enrichment-browser to subscribe to remote config at key configs.analyticsSDK.browserSDK.customEnrichment, validate config shape using isCustomEnrichmentConfig type guard, compile enrichment functions from body strings via createEnrichEvent helper using new Function, handle compilation errors by logging via loggerProvider?.error and falling back to identity function, return original event on execution errors, return null when enrichment returns undefined, check config.remoteConfig?.fetchRemoteConfig instead of config.fetchRemoteConfig, and remove in-memory customEnrichmentBody state [083cb13]
• Exported CustomEnrichmentOptions from @amplitude/analytics-core entry point and replaced CustomEnrichmentBody type with CustomEnrichmentOptions interface containing body: string property marked with @experimental JSDoc comment [083cb13]
• Updated test suite for customEnrichmentPlugin to assert subscription key configs.analyticsSDK.browserSDK.customEnrichment, use nested remoteConfig: { fetchRemoteConfig } config structure, verify creation-time error message 'Could not create custom enrichment function', test identity behavior for empty body, test null return for comment-only body, and validate graceful handling of missing loggerProvider and remoteConfigClient [083cb13]
• Added build tooling dependencies to @amplitude/plugin-custom-enrichment-browser package including @rollup/plugin-commonjs, @rollup/plugin-node-resolve, @rollup/plugin-typescript, rollup, rollup-plugin-execute, rollup-plugin-gzip, and rollup-plugin-terser, and updated @amplitude/analytics-core dependency to workspace:* [083cb13]
• Changed PageUrlEnrichmentOptions import in @amplitude/plugin-page-url-enrichment-browser to type-only import [083cb13]
• Updated pnpm-lock.yaml lockfile content [083cb13]
• Migrated package manager commands from yarn to pnpm in npm scripts [ca5b323]
• Implemented subscription lifecycle management in customEnrichmentPlugin by storing the subscription ID returned from remoteConfigClient.subscribe, defining an unsubscribe closure that calls remoteConfigClient.unsubscribe with the subscription ID, and invoking this closure in the teardown handler when it exists [43ea612]
• Removed type casting when accessing remoteConfig.body in customEnrichmentPlugin, using direct property access with a fallback to empty string in both the setup handler and the remote config subscription callback [43ea612]
• Added test coverage for customEnrichmentPlugin.teardown functionality including verification that remoteConfigClient.unsubscribe is called when a subscription exists, and handling of edge cases when remoteConfigClient is undefined or when the unsubscribe closure is not set [43ea612]
• Added null remote config handling to customEnrichmentPlugin.setup method in plugin-custom-enrichment-browser [effc900]

---

📊 Macroscope summarized 43ea612. 12 files reviewed, 3 issues evaluated, 3 issues filtered, 0 comments posted. View details

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}