feat: Instrumentation

[tusharpandey13]

This change adds configurable instrumentation support to the SDK, enabling emitting events at various critical points of the SDK flows.
These events can be consumed using a callback.

Some use-cases for this feature:

• Event logging
• Debugging
• Event streaming and reactive workflows

Changes

Instrumentation infra:
These changes enable the actual instrumentation support.

• instrumentation-emitter.ts: InstrumentationEmitter class, helper methods
• instrumentation.flow.test.ts‎ & instrumentation.test.ts‎ : Tests
• types/instrumentation.ts: Type definitions
• EXAMPLES.md: Documentation

Event call sites:
These changes add call sites to existing SDK code at important points. PII data is not sent to emitter from codebase itself, removing the need for a filteration step.

• auth-client.ts: Most of the SDK flows
• client.ts: Configuration, one call site

Usage

1. Option1: Environment Variables

AUTH0_LOGGING_TARGET=console
AUTH0_LOGGING_LEVEL=info

Option 2: Custom callback

Configure a callback in Auth0ClientOptions:

export const auth0 = new Auth0Client({
  instrumentation: {
    logger: (event) => {
      // do what you want with the event here
      console.log(`[${event.level}] ${event.event}`, event.data);
    },
  },
});

Tests

Added unit and flow tests for complete integration.

In general, to fix an “invocation of non-function” issue, ensure that any value you call as a function is guaranteed to be a function at runtime, either by initializing it appropriately, guarding the call with a type check, or removing the call if it is unnecessary.

Here, resolveLogger is intended to be a function used to signal when the logger’s internal work has finished, but in this test we never assign it or await it. The test only cares that the auth flow does not wait for the slow logger; it never inspects or uses resolveLogger. Therefore the simplest, behavior-preserving fix is to stop calling resolveLogger entirely. The promise returned by slowLogger already resolves via resolve(undefined);, which is sufficient for the test’s purpose. Removing the resolveLogger!(); call ensures we no longer attempt to invoke a possibly-undefined value, while keeping the rest of the behavior (a slow, non-awaited logger) intact.

Concretely, in src/server/instrumentation.flow.test.ts, within the "EC-10: Slow async logger" describe block, update the setTimeout body so that it only calls resolve(undefined); and does not reference resolveLogger. You may optionally also remove the unused resolveLogger variable declaration, but given the instruction to minimize changes, we can leave the declaration in place even though it is unused; the key is to remove the unsafe invocation.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.60%. Comparing base (bc63577) to head (85d56f4).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2527      +/-   ##
==========================================
+ Coverage   90.15%   90.60%   +0.45%     
==========================================
  Files          51       53       +2     
  Lines        6439     6708     +269     
  Branches     1292     1333      +41     
==========================================
+ Hits         5805     6078     +273     
+ Misses        623      619       -4     
  Partials       11       11              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.