feat: copy posthog js processing

package.json

@@ -1,48 +1,48 @@
 {
-  "name": "useragent-plugin",
-  "version": "2.0.2",
-  "description": "Automatically attach detailed browser details to the event when $useragent property exists",
-  "main": "dist/index.js",
-  "files": [
-    "plugin.json",
-    "dist/index.js",
-    "README.md",
-    "LICENSE.md"
-  ],
-  "scripts": {
-    "test": "jest",
-    "build": "rm -rf dist && esbuild src/plugin.ts --bundle --platform=node --target=node10.4 --outfile=dist/index.js",
-    "prepublishOnly": "npm run build",
-    "format": "prettier --ignore-path .gitignore --write \"src/**/*.+(js|ts|json)\"",
-    "prepare": "husky"
-  },
-  "keywords": [
-    "posthog",
-    "plugin",
-    "browser",
-    "event ingestion",
-    "user agent"
-  ],
-  "author": "PostHog (forked from Weyert de Boer)",
-  "repository": "https://github.com/posthog/useragentplugin",
-  "license": "MIT",
-  "devDependencies": {
-    "@posthog/plugin-scaffold": "^0.12.10",
-    "@types/jest": "^27.0.3",
-    "esbuild": "^0.20.1",
-    "husky": "^9.0.11",
-    "jest": "^27.4.5",
-    "lint-staged": "^15.2.2",
-    "prettier": "^3.2.5",
-    "ts-jest": "^27.1.5",
-    "tslib": "^2.6.2"
-  },
-  "dependencies": {
-    "detect-browser": "^5.3.0"
-  },
-  "lint-staged": {
-    "src/**/*.{ts,tsx,js,json}": [
-      "format"
-    ]
-  }
+    "name": "useragent-plugin",
+    "version": "2.1.0",
+    "description": "Automatically attach detailed browser details to the event when $useragent property exists",
+    "main": "dist/index.js",
+    "files": [
+        "plugin.json",
+        "dist/index.js",
+        "README.md",
+        "LICENSE.md"
+    ],
+    "scripts": {
+        "test": "jest",
+        "build": "rm -rf dist && esbuild src/plugin.ts --bundle --platform=node --target=node10.4 --outfile=dist/index.js",
+        "prepublishOnly": "npm run build",
+        "format": "prettier --ignore-path .gitignore --write \"src/**/*.+(js|ts|json)\"",
+        "prepare": "husky"
+    },
+    "keywords": [
+        "posthog",
+        "plugin",
+        "browser",
+        "event ingestion",
+        "user agent"
+    ],
+    "author": "PostHog (forked from Weyert de Boer)",
+    "repository": "https://github.com/posthog/useragentplugin",
+    "license": "MIT",
+    "devDependencies": {
+        "@posthog/plugin-scaffold": "^0.12.10",
+        "@types/jest": "^27.0.3",
+        "esbuild": "^0.20.1",
+        "husky": "^9.0.11",
+        "jest": "^27.4.5",
+        "lint-staged": "^15.2.2",
+        "prettier": "^3.2.5",
+        "ts-jest": "^27.1.5",
+        "tslib": "^2.6.2"
+    },
+    "dependencies": {
+        "detect-browser": "^5.3.0"
+    },
+    "lint-staged": {
+        "src/**/*.{ts,tsx,js,json}": [
+            "format"
+        ]
+    }
 }

plugin.json

@@ -10,7 +10,8 @@
         {
             "key": "overrideUserAgentDetails",
             "name": "Can override existing browser related properties of event?",
-            "type": "string",
+            "type": "choice",
+            "choices": ["false", "true"],
             "hint": "If the ingested event already have $browser $browser_version properties in combination with $useragent the $browser, $browser_version properties will be re-populated with the value of $useragent",
             "default": "false",
             "required": false
@@ -31,6 +32,14 @@
             "choices": ["false", "true"],
             "default": "false",
             "required": false
+        },
+        {
+            "key": "allowV3UserAgentProcessing",
+            "type": "choice",
+            "hint": "EXPERIMENTAL: Enable v3 user agent processing, this allows us to replace posthog-js user agent processing with this user agent plugin",
+            "choices": ["false", "true"],
+            "default": "false",
+            "required": false
         }
     ]
 }

src/__tests__/index.ts

@@ -0,0 +1,33 @@
+import { CacheExtension, GeoIPExtension, Meta, StorageExtension, UtilsExtension } from '@posthog/plugin-scaffold'
+import { UserAgentMetaInput } from '../plugin'
+
+export function makeMeta(options?: {
+    enable?: boolean
+    enableSegmentAnalyticsJs?: boolean
+    overrideUserAgentDetails?: boolean
+    allowV3UserAgentProcessing?: boolean
+    debugMode?: boolean
+}): Meta<UserAgentMetaInput> {
+    return {
+        cache: {} as CacheExtension,
+        storage: {} as StorageExtension,
+        global: {
+            enabledPlugin: options?.enable ?? true,
+            enableSegmentAnalyticsJs: options?.enableSegmentAnalyticsJs ?? false,
+            overrideUserAgentDetails: options?.overrideUserAgentDetails ?? true,
+            allowV3UserAgentProcessing: options?.allowV3UserAgentProcessing ?? false,
+            debugMode: options?.debugMode ?? false,
+        },
+        config: {
+            enable: options?.enable ? 'true' : 'false',
+            enableSegmentAnalyticsJs: options?.enableSegmentAnalyticsJs ? 'true' : 'false',
+            overrideUserAgentDetails: options?.overrideUserAgentDetails ? 'true' : 'false',
+            allowV3UserAgentProcessing: options?.allowV3UserAgentProcessing ? 'true' : 'false',
+        },
+        attachments: {},
+        jobs: {},
+        metrics: {},
+        geoip: {} as GeoIPExtension,
+        utils: {} as UtilsExtension,
+    }
+}

src/__tests__/plugin-validation.test.ts

@@ -0,0 +1,107 @@
+import { userAgentV3 } from '../v3'
+import { userAgentV2 } from '../v2'
+import { makeMeta } from './index'
+import { PluginEventExtra, processEvent } from '../plugin'
+
+jest.mock('../v2/index', () => ({
+    userAgentV2: jest.fn(),
+}))
+
+jest.mock('../v3/index', () => ({
+    userAgentV3: jest.fn(),
+}))
+
+describe('plugin validation', () => {
+    afterEach(() => {
+        // none of these tests should ever try to process
+        expect(userAgentV2).not.toHaveBeenCalled()
+        expect(userAgentV3).not.toHaveBeenCalled()
+    })
+
+    test('should not process event if segment_userAgent is missing', async () => {
+        const event = {
+            properties: {},
+        } as Partial<PluginEventExtra>
+        const meta = makeMeta({ enableSegmentAnalyticsJs: true })
+        const result = await processEvent(event as PluginEventExtra, meta)
+        expect(result).toBe(event)
+    })
+
+    test('should not process event if v2 mode and user agent is missing', async () => {
+        const event = {
+            properties: {},
+        } as Partial<PluginEventExtra>
+        const meta = makeMeta()
+        const result = await processEvent(event as PluginEventExtra, meta)
+        expect(result).toBe(event)
+    })
+
+    test.each(['$user-agent', '$user_agent', '$useragent'])(
+        'should not process event if v2 mode and %s is empty',
+        async key => {
+            const event = {
+                properties: {
+                    [key]: '     ',
+                },
+            } as Partial<PluginEventExtra>
+            const meta = makeMeta()
+            const result = await processEvent(event as PluginEventExtra, meta)
+            expect(result).toEqual({ properties: {} })
+        }
+    )
+
+    test('should not process event if v3 mode neither user agent not raw_user_agent is present', async () => {
+        const event = {
+            properties: {},
+        } as Partial<PluginEventExtra>
+        const meta = makeMeta({ allowV3UserAgentProcessing: true })
+        const result = await processEvent(event as PluginEventExtra, meta)
+        expect(result).toBe(event)
+    })
+
+    test('should not process event if v3 mode and user agent and raw_user_agent are empty', async () => {
+        const event = {
+            properties: {
+                $useragent: '     ',
+                $raw_user_agent: '     ',
+            },
+        } as Partial<PluginEventExtra>
+        const meta = makeMeta({ allowV3UserAgentProcessing: true })
+        const result = await processEvent(event as PluginEventExtra, meta)
+        expect(result).toEqual({
+            properties: {
+                // we never remove the raw_user_agent key
+                $raw_user_agent: '     ',
+            },
+        })
+    })
+
+    test('v2 - should not process event if has $browser and overrideUserAgentDetails is false', async () => {
+        const event = {
+            properties: {
+                $browser: 'Chrome',
+                $user_agent: 'something',
+            },
+        } as Partial<PluginEventExtra>
+        const meta = makeMeta({ allowV3UserAgentProcessing: false, overrideUserAgentDetails: false })
+        const result = await processEvent(event as PluginEventExtra, meta)
+        expect(result.properties).toEqual({
+            $browser: 'Chrome',
+        })
+    })
+
+    test('v3 - should not process event if has $browser and overrideUserAgentDetails is false', async () => {
+        const event = {
+            properties: {
+                $browser: 'Chrome',
+                $raw_user_agent: 'something',
+            },
+        } as Partial<PluginEventExtra>
+        const meta = makeMeta({ allowV3UserAgentProcessing: true, overrideUserAgentDetails: false })
+        const result = await processEvent(event as PluginEventExtra, meta)
+        expect(result.properties).toEqual({
+            $browser: 'Chrome',
+            $raw_user_agent: 'something',
+        })
+    })
+})