Add comprehensive message lifecycle events

Author: zikaari

.changeset/orange-mayflies-sip.md

@@ -0,0 +1,6 @@
+---
+'@segment/analytics-next': patch
+'@segment/analytics-core': patch
+---
+
+Add comprehensive message lifecycle events

packages/browser/src/browser/__tests__/inspector.integration.test.ts

@@ -55,7 +55,67 @@ describe('Inspector', () => {
 
     await deliveryPromise
 
-    expect(enrichedFn).toHaveBeenCalledTimes(1)
+    expect(enrichedFn).toHaveBeenCalledTimes(2)
     expect(deliveredFn).toHaveBeenCalledTimes(1)
   })
+
+  it('emits message enrichment events with enricher information', async () => {
+    const [analytics] = await AnalyticsBrowser.load({
+      writeKey,
+    })
+
+    const enrichedFn = jest.fn()
+
+    analytics.queue.on('message_enriched', enrichedFn)
+
+    await analytics.register({
+      name: 'Test plugin',
+      version: '1.0.0',
+      type: 'before',
+      isLoaded: () => true,
+      load: () => Promise.resolve(),
+      track: (ctx) => ctx,
+    })
+
+    const ctx = await analytics.track('Test event').catch(() => {})
+
+    expect(enrichedFn).toHaveBeenLastCalledWith(
+      ctx,
+      expect.objectContaining({
+        name: 'Test plugin',
+        type: 'before',
+      })
+    )
+  })
+
+  it('emits expected events if before plugin throws error ', async () => {
+    const [analytics] = await AnalyticsBrowser.load(
+      {
+        writeKey,
+      },
+      { retryQueue: false }
+    )
+
+    const failedFn = jest.fn()
+    const deliveredFn = jest.fn()
+
+    analytics.queue.on('delivery_failure', failedFn)
+    analytics.queue.on('message_delivered', deliveredFn)
+
+    await analytics.register({
+      name: 'Faulty Plugin',
+      version: '1.0.0',
+      type: 'before',
+      isLoaded: () => true,
+      load: () => Promise.resolve(),
+      track: () => {
+        throw new Error()
+      },
+    })
+
+    await analytics.track('Faulty event')
+
+    expect(failedFn).toHaveBeenCalledTimes(1)
+    expect(deliveredFn).not.toHaveBeenCalled()
+  })
 })

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

@@ -12,8 +12,9 @@ import { isOffline } from '../connection'
 
 export type EventQueueEmitterContract<Ctx extends CoreContext> = {
   message_delivered: [ctx: Ctx]
-  message_enriched: [ctx: Ctx]
+  message_enriched: [ctx: Ctx, plugin: CorePlugin<Ctx>]
   delivery_success: [ctx: Ctx]
+  delivery_retry: [ctx: Ctx]
   delivery_failure: [ctx: Ctx, err: Ctx | Error | ContextCancelation]
   flush: [ctx: Ctx, delivered: boolean]
 }
@@ -265,6 +266,10 @@ export abstract class CoreEventQueue<
       throw new Error('Not ready')
     }
 
+    if (ctx.attempts > 1) {
+      this.emit('delivery_retry', ctx)
+    }
+
     const { before, enrichment } = this.availableExtensions(
       ctx.event.integrations ?? {}
     )
@@ -274,16 +279,18 @@ export abstract class CoreEventQueue<
       if (temp instanceof CoreContext) {
         ctx = temp
       }
+
+      this.emit('message_enriched', ctx, beforeWare)
     }
 
     for (const enrichmentWare of enrichment) {
       const temp = await attempt(ctx, enrichmentWare)
       if (temp instanceof CoreContext) {
         ctx = temp
       }
-    }
 
-    this.emit('message_enriched', ctx)
+      this.emit('message_enriched', ctx, enrichmentWare)
+    }
 
     // Enrichment and before plugins can re-arrange the deny list dynamically
     // so we need to pluck them at the end