@equinor/fusion-framework-module-msal 4.0.8 → 4.1.0

package/dist/types/__tests__/versioning/resolve-version.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/static.d.ts

@@ -1,5 +1,5 @@
 export declare const ModuleName: "msal";
 export declare enum MsalModuleVersion {
     V2 = "v2",
-    Latest = "4.0.8"
+    Latest = "4.1.0"
 }

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "4.0.8";
+export declare const version = "4.1.0";

package/dist/types/versioning/VersionError.d.ts

@@ -0,0 +1,73 @@
+import { VersionMessageType } from './static';
+import type { SemVer } from 'semver';
+/**
+ * Creates a VersionError instance with a formatted message.
+ *
+ * This is a helper function that creates a VersionError with a human-readable
+ * message based on the error type and version information.
+ *
+ * @param type - The type of version error
+ * @param requestedVersion - The version that was requested
+ * @param latestVersion - The latest available version
+ * @param options - Additional error options including the error type
+ * @returns A new VersionError instance with formatted message
+ */
+declare const createVersionError: (type: VersionMessageType, requestedVersion: string | SemVer, latestVersion: string | SemVer, options?: ErrorOptions & {
+    type?: VersionMessageType;
+}) => VersionError;
+/**
+ * Error class for version-related issues in the MSAL module.
+ *
+ * This error is thrown when there are version compatibility problems,
+ * such as requesting an incompatible major version or providing an invalid version string.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   resolveVersion('3.0.0'); // Assuming latest is 2.x
+ * } catch (error) {
+ *   if (error instanceof VersionError) {
+ *     console.error('Version error:', error.message);
+ *     console.error('Requested:', error.requestedVersion);
+ *     console.error('Latest:', error.latestVersion);
+ *     console.error('Type:', error.type);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create a version error manually
+ * const error = VersionError.create(
+ *   VersionError.Type.MajorIncompatibility,
+ *   '3.0.0',
+ *   '2.1.0'
+ * );
+ * ```
+ */
+export declare class VersionError extends Error {
+    /** The version that was requested by the user */
+    readonly requestedVersion: string;
+    /** The latest available version in the system */
+    readonly latestVersion: string;
+    /** The specific type of version error that occurred */
+    readonly type?: VersionMessageType;
+    /** The error name for instanceof checks */
+    static Name: string;
+    /** Reference to the VersionMessageType enum for convenience */
+    static Type: typeof VersionMessageType;
+    /** Factory method for creating VersionError instances with formatted messages */
+    static create: typeof createVersionError;
+    /**
+     * Creates a new VersionError instance.
+     *
+     * @param message - The error message describing the version issue
+     * @param requestedVersion - The version that was requested (will be stored as string)
+     * @param latestVersion - The latest available version (will be stored as string)
+     * @param options - Additional error options including the error type
+     */
+    constructor(message: string, requestedVersion: string | SemVer, latestVersion: string | SemVer, options?: ErrorOptions & {
+        type?: VersionMessageType;
+    });
+}
+export {};

package/dist/types/versioning/create-version-message.d.ts

@@ -0,0 +1,34 @@
+import type { SemVer } from 'semver';
+import { VersionMessageType } from './static';
+/**
+ * Creates a human-readable version message based on the version message type.
+ *
+ * This function generates descriptive error messages for different version compatibility
+ * scenarios, helping developers understand version-related issues.
+ *
+ * @param type - The type of version message to create
+ * @param requestedVersion - The version that was requested by the user
+ * @param latestVersion - The latest available version in the system
+ * @returns A formatted, human-readable version message string
+ *
+ * @example
+ * ```typescript
+ * const message = createVersionMessage(
+ *   VersionMessageType.MajorIncompatibility,
+ *   '3.0.0',
+ *   '2.1.0'
+ * );
+ * // Returns: "Requested major version 3.0.0 is greater than the latest major version 2.1.0"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const message = createVersionMessage(
+ *   VersionMessageType.MinorMismatch,
+ *   '2.1.0',
+ *   '2.2.0'
+ * );
+ * // Returns: "Minor version mismatch, requested 2.1.0, latest 2.2.0"
+ * ```
+ */
+export declare const createVersionMessage: (type: VersionMessageType, requestedVersion: string | SemVer, latestVersion: string | SemVer) => string;

package/dist/types/versioning/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Versioning module for MSAL module compatibility checking.
+ *
+ * This module provides comprehensive version resolution and validation functionality
+ * for the MSAL module, ensuring compatibility between different MSAL library versions.
+ *
+ * @example
+ * ```typescript
+ * import { resolveVersion, VersionError } from '@equinor/fusion-framework-module-msal/versioning';
+ *
+ * try {
+ *   const result = resolveVersion('2.1.0');
+ *   console.log('Version is compatible:', result.satisfiesLatest);
+ * } catch (error) {
+ *   if (error instanceof VersionError) {
+ *     console.error('Version error:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export { resolveVersion } from './resolve-version';
+export { VersionError } from './VersionError';
+export type { ResolvedVersion } from './types';

package/dist/types/versioning/resolve-version.d.ts

@@ -0,0 +1,43 @@
+import { type SemVer } from 'semver';
+import type { ResolvedVersion } from './types';
+/**
+ * Resolves and validates a version string against the latest available MSAL version.
+ *
+ * This function performs comprehensive version checking including:
+ * - Parsing and validating the requested version
+ * - Checking major version compatibility (throws on incompatibility)
+ * - Warning on minor version mismatches (logs warning but continues)
+ * - Ignoring patch version differences for maximum compatibility
+ *
+ * @param version - The version string or SemVer object to resolve. If not provided, defaults to latest.
+ * @returns A ResolvedVersion object containing parsed versions and compatibility information
+ *
+ * @throws {VersionError} When the requested version is invalid or incompatible
+ *
+ * @example
+ * ```typescript
+ * // Resolve a specific version
+ * const result = resolveVersion('2.1.0');
+ * console.log(result.satisfiesLatest); // true if major version matches
+ *
+ * // Resolve with SemVer object
+ * const result2 = resolveVersion(new SemVer('2.0.0'));
+ *
+ * // Default to latest version
+ * const result3 = resolveVersion();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error handling
+ * try {
+ *   const result = resolveVersion('3.0.0'); // Assuming latest is 2.x
+ * } catch (error) {
+ *   if (error instanceof VersionError) {
+ *     console.error('Version error:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare function resolveVersion(version?: string | SemVer): ResolvedVersion;
+export default resolveVersion;

package/dist/types/versioning/static.d.ts

@@ -0,0 +1,8 @@
+export declare enum VersionMessageType {
+    MajorIncompatibility = "major-incompatibility",
+    MinorMismatch = "minor-mismatch",
+    PatchDifference = "patch-difference",
+    InvalidVersion = "invalid-version",
+    InvalidLatestVersion = "invalid-latest-version",
+    IncompatibleVersion = "incompatible-version"
+}

package/dist/types/versioning/types.d.ts

@@ -0,0 +1,54 @@
+import type { SemVer } from 'semver';
+import type { MsalModuleVersion } from '../static';
+/**
+ * Result of version resolution containing parsed versions and compatibility information.
+ *
+ * This type represents the outcome of resolving a version string against the latest
+ * available MSAL version, providing detailed compatibility information for consumers.
+ *
+ * @example
+ * ```typescript
+ * const result: ResolvedVersion = {
+ *   wantedVersion: new SemVer('2.1.0'),
+ *   latestVersion: new SemVer('2.2.0'),
+ *   isLatest: false,
+ *   satisfiesLatest: true,
+ *   enumVersion: MsalModuleVersion.V2
+ * };
+ * ```
+ */
+export type ResolvedVersion = {
+    /**
+     * The version that was requested and successfully parsed.
+     * This is the SemVer object representing the user's requested version.
+     */
+    wantedVersion: SemVer;
+    /**
+     * The latest available version in the system.
+     * This represents the most recent MSAL version that the module supports.
+     */
+    latestVersion: SemVer;
+    /**
+     * Whether the wanted version is exactly the latest version.
+     * True when wantedVersion.compare(latestVersion) === 0
+     */
+    isLatest: boolean;
+    /**
+     * Whether the wanted version satisfies the latest major version.
+     * True when major versions match, regardless of minor/patch differences.
+     * This is the primary compatibility check for MSAL versions.
+     */
+    satisfiesLatest: boolean;
+    /**
+     * The corresponding enum version for the wanted version.
+     * Maps the major version number to the appropriate MsalModuleVersion enum value.
+     * Used for module configuration and feature detection.
+     */
+    enumVersion: MsalModuleVersion;
+    /**
+     * Optional array of warning messages for version mismatches.
+     * Present when there are minor version differences but major versions match.
+     * Consumers can check this field to log warnings or handle version differences.
+     */
+    warnings?: string[];
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@equinor/fusion-framework-module-msal",
-  "version": "4.0.8",
-  "description": "",
+  "version": "4.1.0",
+  "description": "Microsoft Authentication Library (MSAL) integration module for Fusion Framework",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
   "exports": {
@@ -40,12 +40,13 @@
     "@types/semver": "^7.5.0",
     "semver": "^7.5.4",
     "zod": "^3.25.76",
-    "@equinor/fusion-framework-module": "^5.0.0"
+    "@equinor/fusion-framework-module": "^5.0.1"
   },
   "devDependencies": {
     "typescript": "^5.8.2"
   },
   "scripts": {
-    "build": "tsc -b"
+    "build": "tsc -b",
+    "test": "vitest run"
   }
 }

package/src/__tests__/versioning/resolve-version.test.ts

@@ -0,0 +1,255 @@
+import { describe, it, expect, vi } from 'vitest';
+import { SemVer } from 'semver';
+import { resolveVersion } from '../../versioning/resolve-version';
+import { VersionError } from '../../versioning/VersionError';
+
+// Mock the static module to avoid test failures when package version changes
+// This ensures tests remain stable regardless of package.json version bumps
+vi.mock('../../static', () => ({
+  MsalModuleVersion: {
+    V2: 'v2',
+    Latest: '4.0.9', // Fixed version for consistent testing
+  },
+}));
+
+// Import the mocked version
+import { MsalModuleVersion } from '../../static';
+
+describe('resolveVersion', () => {
+  describe('mock verification', () => {
+    it('should use mocked version for consistent testing', () => {
+      // Verify that our mock is working and we're using the fixed version
+      expect(MsalModuleVersion.Latest).toBe('4.0.9');
+      expect(MsalModuleVersion.V2).toBe('v2');
+    });
+  });
+
+  describe('successful version resolution', () => {
+    it('should resolve a valid version string', () => {
+      const result = resolveVersion('2.1.0');
+
+      expect(result).toMatchObject({
+        wantedVersion: expect.any(SemVer),
+        latestVersion: expect.any(SemVer),
+        isLatest: false,
+        satisfiesLatest: false, // 2.x is not compatible with 4.x
+        enumVersion: MsalModuleVersion.V2,
+      });
+
+      expect(result.wantedVersion.version).toBe('2.1.0');
+      expect(result.latestVersion.version).toBe('4.0.9');
+    });
+
+    it('should resolve with SemVer object', () => {
+      const semver = new SemVer('2.0.0');
+      const result = resolveVersion(semver);
+
+      expect(result.wantedVersion).toBe(semver);
+      expect(result.satisfiesLatest).toBe(false); // 2.x is not compatible with 4.x
+    });
+
+    it('should resolve latest version when no version provided', () => {
+      const result = resolveVersion();
+
+      expect(result.wantedVersion.version).toBe('4.0.9');
+      expect(result.latestVersion.version).toBe('4.0.9');
+      expect(result.isLatest).toBe(true);
+      expect(result.satisfiesLatest).toBe(true);
+    });
+
+    it('should resolve latest version when empty string provided', () => {
+      const result = resolveVersion('');
+
+      expect(result.wantedVersion.version).toBe('4.0.9');
+      expect(result.isLatest).toBe(true);
+    });
+
+    it('should handle patch version differences without warnings', () => {
+      const result = resolveVersion('4.0.8');
+
+      expect(result.satisfiesLatest).toBe(true);
+      expect(result.isLatest).toBe(false);
+      expect(result.warnings).toBeUndefined();
+    });
+
+    it('should handle minor version differences with warnings', () => {
+      const result = resolveVersion('4.1.0');
+
+      expect(result.satisfiesLatest).toBe(true);
+      expect(result.isLatest).toBe(false);
+      expect(result.warnings).toBeDefined();
+      expect(result.warnings).toHaveLength(1);
+      expect(result.warnings?.[0]).toContain('Minor version mismatch');
+    });
+
+    it('should find correct enum version for major version', () => {
+      const result = resolveVersion('2.5.0');
+
+      expect(result.enumVersion).toBe(MsalModuleVersion.V2);
+      expect(result.satisfiesLatest).toBe(false); // 2.x is not compatible with 4.x
+    });
+
+    it('should throw error when no matching major version exists in enum', () => {
+      // Version 3.0.0 should throw because there's no enum for major version 3
+      expect(() => resolveVersion('3.0.0')).toThrow(VersionError);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw VersionError for invalid version string', () => {
+      expect(() => resolveVersion('invalid-version')).toThrow(VersionError);
+    });
+
+    it('should not throw for malformed version (coerce handles it)', () => {
+      // semver.coerce('2.') returns '2.0.0', so it doesn't throw
+      expect(() => resolveVersion('2.')).not.toThrow();
+    });
+
+    it('should throw VersionError for non-semver string', () => {
+      expect(() => resolveVersion('not-a-version')).toThrow(VersionError);
+    });
+
+    it('should throw VersionError for major version incompatibility', () => {
+      expect(() => resolveVersion('5.0.0')).toThrow(VersionError);
+    });
+
+    it('should throw VersionError for very high major version', () => {
+      expect(() => resolveVersion('999.0.0')).toThrow(VersionError);
+    });
+
+    it('should include correct error type for major incompatibility', () => {
+      try {
+        resolveVersion('5.0.0');
+        expect.fail('Should have thrown VersionError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(VersionError);
+        const versionError = error as VersionError;
+        expect(versionError.type).toBe('major-incompatibility');
+        expect(versionError.requestedVersion).toBe('5.0.0');
+        expect(versionError.latestVersion).toBe('4.0.9');
+      }
+    });
+
+    it('should include correct error type for invalid version', () => {
+      try {
+        resolveVersion('invalid');
+        expect.fail('Should have thrown VersionError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(VersionError);
+        expect((error as VersionError).type).toBe('invalid-version');
+      }
+    });
+  });
+
+  describe('version comparison logic', () => {
+    it('should correctly identify latest version', () => {
+      const result = resolveVersion('4.0.9');
+      expect(result.isLatest).toBe(true);
+    });
+
+    it('should correctly identify non-latest version', () => {
+      const result = resolveVersion('4.0.8');
+      expect(result.isLatest).toBe(false);
+    });
+
+    it('should correctly identify satisfying version', () => {
+      const result = resolveVersion('4.1.0');
+      expect(result.satisfiesLatest).toBe(true);
+    });
+
+    it('should correctly identify non-satisfying version', () => {
+      expect(() => resolveVersion('5.0.0')).toThrow();
+    });
+
+    it('should throw error for major versions without enum values', () => {
+      // Version 3.0.0 should throw because there's no enum for major version 3
+      expect(() => resolveVersion('3.0.0')).toThrow(VersionError);
+    });
+  });
+
+  describe('warning behavior', () => {
+    it('should warn on minor version mismatch', () => {
+      const result = resolveVersion('4.1.0');
+
+      expect(result.warnings).toBeDefined();
+      expect(result.warnings).toHaveLength(1);
+      expect(result.warnings?.[0]).toContain('Minor version mismatch');
+    });
+
+    it('should not warn on patch version differences', () => {
+      const result = resolveVersion('4.0.8');
+
+      expect(result.warnings).toBeUndefined();
+    });
+
+    it('should not warn on exact version match', () => {
+      const result = resolveVersion('4.0.9');
+
+      expect(result.warnings).toBeUndefined();
+    });
+
+    it('should warn with correct version information', () => {
+      const result = resolveVersion('4.2.0');
+
+      expect(result.warnings).toBeDefined();
+      expect(result.warnings).toHaveLength(1);
+      expect(result.warnings?.[0]).toContain('4.2.0');
+      expect(result.warnings?.[0]).toContain('4.0.9');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle version with pre-release identifiers (coerce strips them)', () => {
+      const result = resolveVersion('4.0.9-beta.1');
+
+      expect(result.satisfiesLatest).toBe(true);
+      expect(result.wantedVersion.version).toBe('4.0.9'); // coerce strips pre-release
+    });
+
+    it('should handle version with build metadata (coerce strips them)', () => {
+      const result = resolveVersion('4.0.9+build.123');
+
+      expect(result.satisfiesLatest).toBe(true);
+      expect(result.wantedVersion.version).toBe('4.0.9'); // coerce strips build metadata
+    });
+
+    it('should handle very long version strings (coerce strips them)', () => {
+      const longVersion = '4.0.9-beta.1.alpha.2+build.123.456';
+      const result = resolveVersion(longVersion);
+
+      expect(result.satisfiesLatest).toBe(true);
+      expect(result.wantedVersion.version).toBe('4.0.9'); // coerce strips pre-release and build
+    });
+
+    it('should throw error for zero versions without enum values', () => {
+      // Version 0.0.0 should throw because there's no enum for major version 0
+      expect(() => resolveVersion('0.0.0')).toThrow(VersionError);
+    });
+  });
+
+  describe('return value structure', () => {
+    it('should return object with all required properties', () => {
+      const result = resolveVersion('2.1.0');
+
+      expect(result).toHaveProperty('wantedVersion');
+      expect(result).toHaveProperty('latestVersion');
+      expect(result).toHaveProperty('isLatest');
+      expect(result).toHaveProperty('satisfiesLatest');
+      expect(result).toHaveProperty('enumVersion');
+
+      expect(typeof result.isLatest).toBe('boolean');
+      expect(typeof result.satisfiesLatest).toBe('boolean');
+      expect(result.wantedVersion).toBeInstanceOf(SemVer);
+      expect(result.latestVersion).toBeInstanceOf(SemVer);
+      expect(typeof result.enumVersion).toBe('string');
+    });
+
+    it('should have consistent latest version across calls', () => {
+      const result1 = resolveVersion('2.0.0');
+      const result2 = resolveVersion('4.0.0');
+
+      expect(result1.latestVersion.version).toBe(result2.latestVersion.version);
+      expect(result1.latestVersion.version).toBe('4.0.9');
+    });
+  });
+});

package/src/v2/provider.ts

@@ -5,7 +5,7 @@ import { MsalModuleVersion } from '../static';
 import type { AuthClientConfig } from './configurator';
 import type { AccountInfo, AuthenticationResult } from './types';
 import type { IProxyProvider } from '../types';
-import resolveVersion from '../resolve-version';
+import { resolveVersion } from '../versioning/resolve-version';
 import { SemanticVersion } from '@equinor/fusion-framework-module';
 
 export interface IAuthProvider {

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '4.0.8';
+export const version = '4.1.0';

package/src/versioning/VersionError.ts

@@ -0,0 +1,103 @@
+import { VersionMessageType } from './static';
+import { createVersionMessage } from './create-version-message';
+import type { SemVer } from 'semver';
+
+/**
+ * Creates a VersionError instance with a formatted message.
+ *
+ * This is a helper function that creates a VersionError with a human-readable
+ * message based on the error type and version information.
+ *
+ * @param type - The type of version error
+ * @param requestedVersion - The version that was requested
+ * @param latestVersion - The latest available version
+ * @param options - Additional error options including the error type
+ * @returns A new VersionError instance with formatted message
+ */
+const createVersionError = (
+  type: VersionMessageType,
+  requestedVersion: string | SemVer,
+  latestVersion: string | SemVer,
+  options?: ErrorOptions & { type?: VersionMessageType },
+): VersionError => {
+  return new VersionError(
+    createVersionMessage(type, requestedVersion, latestVersion),
+    requestedVersion,
+    latestVersion,
+    { ...options, type },
+  );
+};
+
+/**
+ * Error class for version-related issues in the MSAL module.
+ *
+ * This error is thrown when there are version compatibility problems,
+ * such as requesting an incompatible major version or providing an invalid version string.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   resolveVersion('3.0.0'); // Assuming latest is 2.x
+ * } catch (error) {
+ *   if (error instanceof VersionError) {
+ *     console.error('Version error:', error.message);
+ *     console.error('Requested:', error.requestedVersion);
+ *     console.error('Latest:', error.latestVersion);
+ *     console.error('Type:', error.type);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create a version error manually
+ * const error = VersionError.create(
+ *   VersionError.Type.MajorIncompatibility,
+ *   '3.0.0',
+ *   '2.1.0'
+ * );
+ * ```
+ */
+export class VersionError extends Error {
+  /** The version that was requested by the user */
+  public readonly requestedVersion: string;
+
+  /** The latest available version in the system */
+  public readonly latestVersion: string;
+
+  /** The specific type of version error that occurred */
+  public readonly type?: VersionMessageType;
+
+  /** The error name for instanceof checks */
+  static Name = 'VersionError';
+
+  /** Reference to the VersionMessageType enum for convenience */
+  static Type = VersionMessageType;
+
+  /** Factory method for creating VersionError instances with formatted messages */
+  static create: typeof createVersionError = createVersionError;
+
+  /**
+   * Creates a new VersionError instance.
+   *
+   * @param message - The error message describing the version issue
+   * @param requestedVersion - The version that was requested (will be stored as string)
+   * @param latestVersion - The latest available version (will be stored as string)
+   * @param options - Additional error options including the error type
+   */
+  constructor(
+    message: string,
+    requestedVersion: string | SemVer,
+    latestVersion: string | SemVer,
+    options?: ErrorOptions & { type?: VersionMessageType },
+  ) {
+    super(message, options);
+    this.name = VersionError.Name;
+
+    // Store versions as strings
+    this.requestedVersion = String(requestedVersion);
+    this.latestVersion = String(latestVersion);
+
+    this.type = options?.type;
+  }
+}