feat(core): Add lifecycle hooks

packages/core/src/baseclient.ts

@@ -9,6 +9,9 @@ import type {
   Event,
   EventDropReason,
   EventHint,
+  HookCallback,
+  HookName,
+  HookStore,
   Integration,
   IntegrationClass,
   Outcome,
@@ -97,6 +100,8 @@ export abstract class BaseClient<O extends ClientOptions> implements Client<O> {
   /** Holds flushable  */
   private _outcomes: { [key: string]: number } = {};
 
+  private _hooks: HookStore = {};
+
   /**
    * Initializes this client instance.
    *
@@ -351,6 +356,30 @@ export abstract class BaseClient<O extends ClientOptions> implements Client<O> {
     }
   }
 
+  /**
+   * @inheritDoc
+   */
+  public on(hook: HookName, callback: HookCallback): void {
+    if (!this._hooks[hook]) {
+      this._hooks[hook] = [];
+    }
+
+    // @ts-ignore we cannot enforce the callback to match the hook
+    // while saving bundle size
+    this._hooks[hook].push(callback);
+  }
+
+  /**
+   * @inheritDoc
+   */
+  public emit(hook: HookName, ...args: Parameters<HookCallback>): void {
+    if (this._hooks[hook]) {
+      // @ts-ignore we cannot enforce the callback to match the hook
+      // while saving bundle size
+      this._hooks[hook].forEach((callback: HookCallback) => callback(...args));
+    }
+  }
+
   /** Updates existing session based on the provided event */
   protected _updateSessionFromEvent(session: Session, event: Event): void {
     let crashed = false;

packages/core/test/lib/base.test.ts

@@ -1,4 +1,4 @@
-import type { Event, Span } from '@sentry/types';
+import type { Event, Span, Transaction } from '@sentry/types';
 import { dsnToString, logger, SentryError, SyncPromise } from '@sentry/utils';
 
 import { Hub, makeSession, Scope } from '../../src';
@@ -1730,4 +1730,23 @@ describe('BaseClient', () => {
       expect(clearedOutcomes4.length).toEqual(0);
     });
   });
+
+  describe('hooks', () => {
+    it('should call a startTransaction hook', () => {
+      expect.assertions(1);
+
+      const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN });
+      const client = new TestClient(options);
+
+      const mockTransaction = {
+        traceId: '86f39e84263a4de99c326acab3bfe3bd',
+      } as Transaction;
+
+      client?.on('startTransaction', (transaction: Transaction) => {
+        expect(transaction).toEqual(mockTransaction);
+      });
+
+      client?.emit('startTransaction', mockTransaction);
+    });
+  });
 });

packages/types/src/client.ts

@@ -2,6 +2,7 @@ import type { EventDropReason } from './clientreport';
 import type { DataCategory } from './datacategory';
 import type { DsnComponents } from './dsn';
 import type { Event, EventHint } from './event';
+import type { EnvelopeHookCallback, EnvelopeHookName, TransactionHookCallback, TransactionHookName } from './hooks';
 import type { Integration, IntegrationClass } from './integration';
 import type { ClientOptions } from './options';
 import type { Scope } from './scope';
@@ -147,4 +148,29 @@ export interface Client<O extends ClientOptions = ClientOptions> {
    * @param event The dropped event.
    */
   recordDroppedEvent(reason: EventDropReason, dataCategory: DataCategory, event?: Event): void;
+
+  // HOOKS
+  // TODO(v8): Make the hooks non-optional.
+
+  /**
+   * Register a callback for transaction start and finish.
+   */
+  on?(hook: TransactionHookName, callback: TransactionHookCallback): void;
+
+  /**
+   * Register a callback for envelope creation and sending.
+   */
+  on?(hook: EnvelopeHookName, callback: EnvelopeHookCallback): void;
+
+  /**
+   * Fire a hook event for transaction start and finish. Expects to be given a transaction as the
+   * second argument.
+   */
+  emit?(hook: TransactionHookName, ...params: Parameters<TransactionHookCallback>): void;
+
+  /*
+   * Fire a hook event for envelope creation and sending. Expects to be given an envelope as the
+   * second argument.
+   */
+  emit?(hook: EnvelopeHookName, ...params: Parameters<EnvelopeHookCallback>): void;
 }

packages/types/src/hooks.ts

@@ -0,0 +1,19 @@
+import type { Envelope } from './envelope';
+import type { Transaction } from './transaction';
+
+export type TransactionHookName = 'startTransaction' | 'transactionFinish';
+export type TransactionHookCallback = (transaction: Transaction) => void;
+
+export type EnvelopeHookName = 'beforeEnvelope';
+export type EnvelopeHookCallback = (envelope: Envelope) => void;
+
+export type HookName = TransactionHookName | EnvelopeHookName;
+export type HookCallback = TransactionHookCallback | EnvelopeHookCallback;
+
+export type HookStoreItem<N extends HookName, C extends HookCallback> = Partial<{ [key in N]: C[] }>;
+
+export type HookStore =
+  // Hooks related to transaction start/finish
+  HookStoreItem<TransactionHookName, TransactionHookCallback> &
+    // Hooks related to envelope create and send
+    HookStoreItem<EnvelopeHookName, EnvelopeHookCallback>;

packages/types/src/index.ts

@@ -96,3 +96,4 @@ export type { WrappedFunction } from './wrappedfunction';
 export type { Instrumenter } from './instrumenter';
 
 export type { BrowserClientReplayOptions } from './browseroptions';
+export type { HookStore, HookName, HookCallback } from './hooks';