feat(auth): add EntraId integration tests

- Add integration tests for token renewal and re-authentication flows
- Update credentials provider to use uniqueId as username instead of account username
- Add test utilities for loading Redis endpoint configurations
- Split TypeScript configs into separate files for samples and integration tests
- Remove `@redis/authx` package and nest it under `@`

Author: bobymicroby

packages/authx/package.json

@@ -1,4 +1,4 @@
-
+import { Disposable } from './disposable';
 /**
  * Provides credentials asynchronously.
  */

packages/authx/tsconfig.json

@@ -0,0 +1,6 @@
+/**
+ * Represents a resource that can be disposed.
+ */
+export interface Disposable {
+  dispose(): void;
+}

packages/authx/lib/credentials-provider.ts renamed to packages/client/lib/authx/credentials-provider.ts

@@ -1,4 +1,4 @@
-export { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError } from './lib/token-manager';
+export { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError } from './token-manager';
 export {
   CredentialsProvider,
   StreamingCredentialsProvider,
@@ -8,6 +8,8 @@ export {
   AsyncCredentialsProvider,
   ReAuthenticationError,
   BasicAuth
-} from './lib/credentials-provider';
-export { Token } from './lib/token';
-export { IdentityProvider, TokenResponse } from './lib/identity-provider';
+} from './credentials-provider';
+export { Token } from './token';
+export { IdentityProvider, TokenResponse } from './identity-provider';
+
+export { Disposable } from './disposable'

packages/client/lib/authx/disposable.ts

@@ -278,7 +278,7 @@ describe('TokenManager', () => {
           assert.equal(listener.errors.length, 0, 'Should not have any errors');
           assert.equal(manager.getCurrentToken().value, 'token3', 'Should have current token');
 
-          disposable?.[Symbol.dispose]();
+          disposable?.dispose();
         });
       });
     });
@@ -328,7 +328,7 @@ describe('TokenManager', () => {
         assert.equal(listener.receivedTokens.length, 1, 'Should not receive new token after failure');
         assert.equal(listener.errors.length, 1, 'Should receive error');
         assert.equal(listener.errors[0].message, 'Fatal error', 'Should have correct error message');
-        assert.equal(listener.errors[0].isFatal, true, 'Should be a fatal error');
+        assert.equal(listener.errors[0].isRetryable, false, 'Should be a fatal error');
 
         // verify that the token manager is stopped and no more requests are made after the error and expected refresh time
         await delay(80);
@@ -338,7 +338,7 @@ describe('TokenManager', () => {
         assert.equal(listener.errors.length, 1, 'Should not receive more errors after error');
         assert.equal(manager.isRunning(), false, 'Should stop token manager after error');
 
-        disposable?.[Symbol.dispose]();
+        disposable?.dispose();
       });
 
       it('should handle retries with exponential backoff', async () => {
@@ -352,7 +352,7 @@ describe('TokenManager', () => {
             initialDelayMs: 100,
             maxDelayMs: 1000,
             backoffMultiplier: 2,
-            shouldRetry: (error: unknown) => error instanceof Error && error.message === 'Temporary failure'
+            isRetryable: (error: unknown) => error instanceof Error && error.message === 'Temporary failure'
           }
         };
 
@@ -389,7 +389,7 @@ describe('TokenManager', () => {
         // Should have first error but not stop due to retry config
         assert.equal(listener.errors.length, 1, 'Should have first error');
         assert.ok(listener.errors[0].message.includes('attempt 1'), 'Error should indicate first attempt');
-        assert.equal(listener.errors[0].isFatal, false, 'Should not be a fatal error');
+        assert.equal(listener.errors[0].isRetryable, true, 'Should not be a fatal error');
         assert.equal(manager.isRunning(), true, 'Should continue running during retries');
 
         // Advance past first retry (delay: 100ms due to backoff)
@@ -401,7 +401,7 @@ describe('TokenManager', () => {
 
         assert.equal(listener.errors.length, 2, 'Should have second error');
         assert.ok(listener.errors[1].message.includes('attempt 2'), 'Error should indicate second attempt');
-        assert.equal(listener.errors[0].isFatal, false, 'Should not be a fatal error');
+        assert.equal(listener.errors[0].isRetryable, true, 'Should not be a fatal error');
         assert.equal(manager.isRunning(), true, 'Should continue running during retries');
 
         // Advance past second retry (delay: 200ms due to backoff)
@@ -420,7 +420,7 @@ describe('TokenManager', () => {
         assert.equal(manager.isRunning(), true, 'Should continue running after recovery');
         assert.equal(identityProvider.getRequestCount(), 4, 'Should have made exactly 4 requests');
 
-        disposable?.[Symbol.dispose]();
+        disposable?.dispose();
       });
 
       it('should stop after max retries exceeded', async () => {
@@ -435,7 +435,7 @@ describe('TokenManager', () => {
             maxDelayMs: 1000,
             backoffMultiplier: 2,
             jitterPercentage: 0,
-            shouldRetry: (error: unknown) => error instanceof Error && error.message === 'Temporary failure'
+            isRetryable: (error: unknown) => error instanceof Error && error.message === 'Temporary failure'
           }
         };
 
@@ -470,7 +470,7 @@ describe('TokenManager', () => {
         // First error
         assert.equal(listener.errors.length, 1, 'Should have first error');
         assert.equal(manager.isRunning(), true, 'Should continue running after first error');
-        assert.equal(listener.errors[0].isFatal, false, 'Should not be a fatal error');
+        assert.equal(listener.errors[0].isRetryable, true, 'Should not be a fatal error');
 
         // Advance past first retry
         await delay(100);
@@ -483,7 +483,7 @@ describe('TokenManager', () => {
         // Second error
         assert.equal(listener.errors.length, 2, 'Should have second error');
         assert.equal(manager.isRunning(), true, 'Should continue running after second error');
-        assert.equal(listener.errors[1].isFatal, false, 'Should not be a fatal error');
+        assert.equal(listener.errors[1].isRetryable, true, 'Should not be a fatal error');
 
         // Advance past second retry
         await delay(200);
@@ -495,11 +495,11 @@ describe('TokenManager', () => {
 
         // Should stop after max retries
         assert.equal(listener.errors.length, 3, 'Should have final error');
-        assert.equal(listener.errors[2].isFatal, true, 'Should not be a fatal error');
+        assert.equal(listener.errors[2].isRetryable, false, 'Should be a fatal error');
         assert.equal(manager.isRunning(), false, 'Should stop after max retries exceeded');
         assert.equal(identityProvider.getRequestCount(), 4, 'Should have made exactly 4 requests');
 
-        disposable?.[Symbol.dispose]();
+        disposable?.dispose();
 
       });
     });

packages/authx/lib/identity-provider.ts renamed to packages/client/lib/authx/identity-provider.ts

@@ -1,22 +1,75 @@
 import { IdentityProvider, TokenResponse } from './identity-provider';
 import { Token } from './token';
+import {Disposable} from './disposable';
 
 /**
  * The configuration for retrying token refreshes.
  */
 export interface RetryPolicy {
-  // The maximum number of attempts to retry token refreshes.
+  /**
+   * The maximum number of attempts to retry token refreshes.
+   */
   maxAttempts: number;
-  // The initial delay in milliseconds before the first retry.
+
+  /**
+   * The initial delay in milliseconds before the first retry.
+   */
   initialDelayMs: number;
-  // The maximum delay in milliseconds between retries (the calculated delay will be capped at this value).
+
+  /**
+   * The maximum delay in milliseconds between retries.
+   * The calculated delay will be capped at this value.
+   */
   maxDelayMs: number;
-  // The multiplier for exponential backoff between retries. e.g. 2 will double the delay each time.
+
+  /**
+   * The multiplier for exponential backoff between retries.
+   * @example
+   * A value of 2 will double the delay each time:
+   * - 1st retry: initialDelayMs
+   * - 2nd retry: initialDelayMs * 2
+   * - 3rd retry: initialDelayMs * 4
+   */
   backoffMultiplier: number;
-  // The percentage of jitter to apply to the delay. e.g. 0.1 will add or subtract up to 10% of the delay.
+
+  /**
+   * The percentage of jitter to apply to the delay.
+   * @example
+   * A value of 0.1 will add or subtract up to 10% of the delay.
+   */
   jitterPercentage?: number;
-  // A custom function to determine if a retry should be attempted based on the error and attempt number.
-  shouldRetry?: (error: unknown, attempt: number) => boolean;
+
+  /**
+   * Function to classify errors from the identity provider as retryable or non-retryable.
+   * Used to determine if a token refresh failure should be retried based on the type of error.
+   *
+   * The default behavior is to retry all types of errors if no function is provided.
+   *
+   * Common use cases:
+   * - Network errors that may be transient (should retry)
+   * - Invalid credentials (should not retry)
+   * - Rate limiting responses (should retry)
+   *
+   * @param error - The error from the identity provider3
+   * @param attempt - Current retry attempt (0-based)
+   * @returns `true` if the error is considered transient and the operation should be retried
+   *
+   * @example
+   * ```typescript
+   * const retryPolicy: RetryPolicy = {
+   *   maxAttempts: 3,
+   *   initialDelayMs: 1000,
+   *   maxDelayMs: 5000,
+   *   backoffMultiplier: 2,
+   *   isRetryable: (error) => {
+   *     // Retry on network errors or rate limiting
+   *     return error instanceof NetworkError ||
+   *            error instanceof RateLimitError;
+   *   }
+   * };
+   * ```
+   */
+  isRetryable?: (error: unknown, attempt: number) => boolean;
 }
 
 /**
@@ -36,14 +89,13 @@ export interface TokenManagerConfig {
 }
 
 /**
- * IDPError is an error that occurs while calling the underlying IdentityProvider.
+ * IDPError indicates a failure from the identity provider.
  *
- * It can be transient and if retry policy is configured, the token manager will attempt to obtain a token again.
- * This means that receiving non-fatal error is not a stream termination event.
- * The stream will be terminated only if the error is fatal.
+ * The `isRetryable` flag is determined by the RetryPolicy's error classification function - if an error is
+ * classified as retryable, it will be marked as transient and the token manager will attempt to recover.
  */
 export class IDPError extends Error {
-  constructor(public readonly message: string, public readonly isFatal: boolean) {
+  constructor(public readonly message: string, public readonly isRetryable: boolean) {
     super(message);
     this.name = 'IDPError';
   }
@@ -105,7 +157,6 @@ export class TokenManager<T> {
    */
   public start(listener: TokenStreamListener<T>, initialDelayMs: number = 0): Disposable {
     if (this.listener) {
-      console.log('TokenManager is already running, stopping the previous instance');
       this.stop();
     }
 
@@ -115,7 +166,7 @@ export class TokenManager<T> {
     this.scheduleNextRefresh(initialDelayMs);
 
     return {
-      [Symbol.dispose]: () => this.stop()
+      dispose: () => this.stop()
     };
   }
 
@@ -142,14 +193,14 @@ export class TokenManager<T> {
   private shouldRetry(error: unknown): boolean {
     if (!this.config.retry) return false;
 
-    const { maxAttempts, shouldRetry } = this.config.retry;
+    const { maxAttempts, isRetryable } = this.config.retry;
 
     if (this.retryAttempt >= maxAttempts) {
       return false;
     }
 
-    if (shouldRetry) {
-      return shouldRetry(error, this.retryAttempt);
+    if (isRetryable) {
+      return isRetryable(error, this.retryAttempt);
     }
 
     return false;
@@ -172,10 +223,10 @@ export class TokenManager<T> {
       if (this.shouldRetry(error)) {
         this.retryAttempt++;
         const retryDelay = this.calculateRetryDelay();
-        this.notifyError(`Token refresh failed (attempt ${this.retryAttempt}), retrying in ${retryDelay}ms: ${error}`, false)
+        this.notifyError(`Token refresh failed (attempt ${this.retryAttempt}), retrying in ${retryDelay}ms: ${error}`, true)
         this.scheduleNextRefresh(retryDelay);
       } else {
-        this.notifyError(error, true);
+        this.notifyError(error, false);
         this.stop();
       }
     }
@@ -255,13 +306,13 @@ export class TokenManager<T> {
     return this.currentToken;
   }
 
-  private notifyError = (error: unknown, isFatal: boolean): void => {
+  private notifyError(error: unknown, isRetryable: boolean): void {
     const errorMessage = error instanceof Error ? error.message : String(error);
 
     if (!this.listener) {
       throw new Error(`TokenManager is not running but received an error: ${errorMessage}`);
     }
 
-    this.listener.onError(new IDPError(errorMessage, isFatal));
+    this.listener.onError(new IDPError(errorMessage, isRetryable));
   }
 }