Simplify interfacing with Inspector

.changeset/purple-bobcats-wave.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-next': patch
+---
+
+Simplify interfacing with Inspector

packages/browser/package.json

@@ -41,7 +41,7 @@
   "size-limit": [
     {
       "path": "dist/umd/index.js",
-      "limit": "25.8 KB"
+      "limit": "25.7 KB"
     }
   ],
   "dependencies": {
@@ -58,7 +58,7 @@
     "unfetch": "^4.1.0"
   },
   "devDependencies": {
-    "@segment/inspector-core": "^1.0.0",
+    "@segment/inspector-webext": "^1.1.0",
     "@size-limit/preset-big-lib": "^7.0.8",
     "@types/flat": "^5.0.1",
     "@types/fs-extra": "^9.0.2",

packages/browser/src/core/analytics/index.ts

@@ -115,13 +115,6 @@ export class Analytics extends Emitter {
     this.integrations = options?.integrations ?? {}
     this.options = options ?? {}
 
-    inspectorHost.start({
-      user: {
-        id: this.user().id() || null,
-        traits: this.user().traits(),
-      },
-    })
-
     autoBind(this)
   }
 
@@ -329,12 +322,7 @@ export class Analytics extends Emitter {
   ): Promise<DispatchedEvent> {
     const ctx = new Context(event)
 
-    inspectorHost.trace({
-      stage: 'triggered',
-      id: ctx.id,
-      event: event as any,
-      timestamp: new Date().toISOString(),
-    })
+    inspectorHost.triggered?.(ctx as any)
 
     if (isOffline() && !this.options.retryQueue) {
       return ctx

packages/browser/src/core/inspector/__tests__/index.test.ts

@@ -4,35 +4,26 @@ let analytics: Analytics
 
 describe('Inspector interface', () => {
   beforeEach(() => {
-    window.__SEGMENT_INSPECTOR__ = {
-      start: jest.fn(),
-      trace: jest.fn(),
-    }
+    Object.assign((window.__SEGMENT_INSPECTOR__ ??= {}), {
+      triggered: jest.fn(),
+      enriched: jest.fn(),
+      delivered: jest.fn(),
+    })
 
     analytics = new Analytics({
       writeKey: 'abc',
     })
   })
 
-  it('accepts and starts up an inspector client trying to connect', () => {
-    expect(window.__SEGMENT_INSPECTOR__?.start).toHaveBeenCalledTimes(1)
-  })
-
   it('notifies the connected inspector client about each event API call and delivery', async () => {
-    expect(window.__SEGMENT_INSPECTOR__?.trace).not.toHaveBeenCalled()
-
-    const timestampMatcher = expect.stringMatching(
-      /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/
-    )
     const deliveryPromise = analytics.track('Test event').catch(() => {})
 
-    // expect 2 calls, triggered report, followed enriched report
-    expect(window.__SEGMENT_INSPECTOR__?.trace).toHaveBeenCalledTimes(2)
+    expect(window.__SEGMENT_INSPECTOR__?.triggered).toHaveBeenCalledTimes(1)
+    expect(window.__SEGMENT_INSPECTOR__?.enriched).toHaveBeenCalledTimes(1)
 
-    expect(window.__SEGMENT_INSPECTOR__?.trace).toHaveBeenCalledWith(
+    expect(window.__SEGMENT_INSPECTOR__?.triggered).toHaveBeenCalledWith(
       expect.objectContaining({
-        stage: 'triggered',
-        timestamp: timestampMatcher,
+        id: expect.any(String),
         event: expect.objectContaining({
           event: 'Test event',
           type: 'track',
@@ -42,18 +33,6 @@ describe('Inspector interface', () => {
 
     await deliveryPromise
 
-    // triggered -> enriched -> delivered
-    expect(window.__SEGMENT_INSPECTOR__?.trace).toHaveBeenCalledTimes(3)
-
-    expect(window.__SEGMENT_INSPECTOR__?.trace).toHaveBeenCalledWith(
-      expect.objectContaining({
-        stage: 'delivered',
-        timestamp: timestampMatcher,
-        event: expect.objectContaining({
-          event: 'Test event',
-          type: 'track',
-        }),
-      })
-    )
+    expect(window.__SEGMENT_INSPECTOR__?.delivered).toHaveBeenCalledTimes(1)
   })
 })

packages/browser/src/core/inspector/index.ts

@@ -1,15 +1,17 @@
-import type { Inspector } from '@segment/inspector-core'
+import type { InspectBroker } from '@segment/inspector-webext'
 import { getGlobal } from '../../lib/get-global'
 
 declare global {
   interface Window {
-    __SEGMENT_INSPECTOR__?: Inspector
+    __SEGMENT_INSPECTOR__: Partial<InspectBroker>
   }
 }
 
 const env = getGlobal()
 
-export const inspectorHost: Inspector = {
-  start: (...args) => (env as any)?.['__SEGMENT_INSPECTOR__']?.start(...args),
-  trace: (...args) => (env as any)?.['__SEGMENT_INSPECTOR__']?.trace(...args),
-}
+// The code below assumes the inspector extension will use Object.assign
+// to add the inspect interface on to this object reference (unless the
+// extension code ran first and has already set up the variable)
+export const inspectorHost: Partial<InspectBroker> = ((env as any)[
+  '__SEGMENT_INSPECTOR__'
+] ??= {})

packages/browser/src/core/queue/event-queue.ts

@@ -266,12 +266,7 @@ export class EventQueue extends Emitter {
       }
     }
 
-    inspectorHost.trace({
-      stage: 'enriched',
-      id: ctx.id,
-      event: ctx.event as any,
-      timestamp: new Date().toISOString(),
-    })
+    inspectorHost.enriched?.(ctx as any)
 
     // Enrichment and before plugins can re-arrange the deny list dynamically
     // so we need to pluck them at the end
@@ -290,14 +285,8 @@ export class EventQueue extends Emitter {
 
     ctx.stats.increment('message_delivered')
 
-    inspectorHost.trace({
-      stage: 'delivered',
-      id: ctx.id,
-      event: ctx.event as any,
-      timestamp: new Date().toISOString(),
-      // FIXME: Resolve browsers destinations that the event was sent to
-      destinations: ['segment.io'],
-    })
+    // FIXME: Resolve browsers destinations that the event was sent to
+    inspectorHost.delivered?.(ctx as any, ['segment.io'])
 
     const afterCalls = after.map((after) => attempt(ctx, after))
     await Promise.all(afterCalls)

yarn.lock

@@ -1500,7 +1500,7 @@ __metadata:
     "@segment/analytics-core": 1.0.0
     "@segment/analytics.js-video-plugins": ^0.2.1
     "@segment/facade": ^3.4.9
-    "@segment/inspector-core": ^1.0.0
+    "@segment/inspector-webext": ^1.1.0
     "@segment/tsub": ^0.1.12
     "@size-limit/preset-big-lib": ^7.0.8
     "@types/flat": ^5.0.1
@@ -1580,10 +1580,19 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@segment/inspector-core@npm:^1.0.0":
-  version: 1.0.0
-  resolution: "@segment/inspector-core@npm:1.0.0"
-  checksum: 4c04303301f54cab9fe8d0502fe0a755ad21206b8917ebbfb5edb8be5888cd7ed4dc948cf34e52b957863de44f9152551d78571ba12c00106f573fdb2136f4ef
+"@segment/inspector-core@npm:^1.1.0":
+  version: 1.1.0
+  resolution: "@segment/inspector-core@npm:1.1.0"
+  checksum: 447733b76b9ab645c6ec1d765d907d92def3e8c1e20ded6c06df3406d98d7f63baac1fecd552ebd4afdf8f8bd53c51fb9266c48fe3f18a2f560af46633729a7c
+  languageName: node
+  linkType: hard
+
+"@segment/inspector-webext@npm:^1.1.0":
+  version: 1.1.0
+  resolution: "@segment/inspector-webext@npm:1.1.0"
+  dependencies:
+    "@segment/inspector-core": ^1.1.0
+  checksum: 65aacfdb535c10d0954150bb74e54c1cd139ccae8f21d110399bd5e1b6ccee562cdd3d3966228de8d2e3433d169f727d1b31f6a6d59b010e3b8dbb3f1f27d8d3
   languageName: node
   linkType: hard