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
The plugin evaluates remotely provided JavaScript (new Function) to modify events, which is security- and stability-sensitive if misconfigured or abused. Runtime failures are handled, but the execution surface area is broad and tied to remote configuration.

Overview
Adds an experimental @amplitude/plugin-custom-enrichment-browser package that subscribes to a Remote Config key (configs.analyticsSDK.browserSDK.customEnrichment) and uses the returned body script to build an event enrichment function via new Function, applied to every event during execute() (with teardown unsubscribing).

Exposes a new CustomEnrichmentOptions type from @amplitude/analytics-core, and includes comprehensive Jest coverage for success/error/empty-config paths; also makes small doc/import cleanups in the page URL enrichment plugin.

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

[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]
• Consolidated conditional logic in customEnrichmentPlugin remote config subscription callback to clear the enrichment function when remote config is null or fails isCustomEnrichmentConfig validation [6fd8e65]
• Added test cases validating customEnrichmentPlugin behavior when remote config body is null or transitions from valid to null [6fd8e65]
• Added remote config fetching configuration to test setup [7d650e8]

---

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

[daniel-graham-amplitude]

Looks good! I can't find any issues.

[Dogfalo]

no changes necessarily, but have some unanswered questions about the behavior of the plugin

[Mercy811]

Thanks @cyhk, LGTM!

[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.}