@equinor/fusion-framework-module-msal 10.0.1 → 11.0.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,178 @@
 # Change Log
 
+## 11.0.0-next.0
+
+### Minor Changes
+
+- 2836e0b: Move the MSAL configuration schema into `MsalConfig.schema.ts` and add `MsalConfigExtension`, an extension point for variants of this module.
+
+  `MsalConfig` is now the schema's inferred type intersected with `MsalConfigExtension`, an empty interface a variant merges its own configuration into:
+
+  ```typescript
+  declare module "@equinor/fusion-framework-module-msal" {
+    interface MsalConfigExtension {
+      mock?: { account?: MsalMockUser };
+    }
+  }
+  ```
+
+  `BaseConfigBuilder._set` derives its target from `MsalConfig`, so before this a key the type did not know about could only be set by casting past the builder. Making the configurator generic over its configuration cannot solve that: a dot-path union over an unresolved type parameter defers, which takes every existing literal path down with it.
+
+  The schema is unchanged and still describes exactly what reaches `MsalProvider` — it strips anything merged in, so an extension carries a declaration across the builder and stops there. `MsalConfigSchema`, `TelemetryConfigSchema` and their types are re-exported from `MsalConfigurator` as before.
+
+- 2836e0b: Extract client construction from `MsalConfigurator._processConfig` into overridable seams.
+
+  `_processConfig` now only decides _whether_ a client is needed; `protected _createClient(config, init)` decides _what_ to build, and `protected _createClientConfig(config)` resolves the `MsalClientConfig` it is built from — authority derived from the tenant, cache location, telemetry-backed logging and cache lookup policy included.
+
+  Behaviour is unchanged for consumers: the client is still auto-created from `setClientConfig`, and a client supplied through `setClient` still wins, because `_createClient` is consulted only when no client was set.
+
+  This gives a supported seam for authenticating through something other than Entra ID:
+
+  ```typescript
+  class MyConfigurator extends MsalConfigurator {
+    protected override async _createClient(
+      config: MsalConfig,
+    ): Promise<IMsalClient> {
+      // same fully resolved configuration the real client is built from
+      return new MyOwnMsalClient(this._createClientConfig(config));
+    }
+  }
+  ```
+
+  Overriding it replaces only the client, leaving the builder, the schema validation and `MsalProvider` untouched.
+
+  No client is built when the module is hoisted onto a host application's provider — an app running inside a portal authenticates through the host, so a client built during configuration would be discarded, or worse, shadow the host's signed-in user. `protected _isHoisted(init)` exposes that decision to subclasses.
+
+  Also adds `getClientConfig()`, the counterpart to `setClientConfig`, so a subclass can tell "nothing was declared" apart from "declared, and here it is".
+
+  `_createClientConfig` applies its defaults to a copy of the declared configuration, not the object itself, so a caller reusing or asserting on it never sees it rewritten, and a shared constant can be used as a default without one configurator's client contaminating the next.
+
+- 2836e0b: Give `MsalMockClient` a real account cache, so its account APIs agree with each other and with MSAL.
+
+  Previously the client held a single nullable account, which made its surface inconsistent: `getAccount(filter)` ignored the filter, `getAllAccounts()` reported an account even after one had only been made active, and signing out merely blanked a field.
+
+  The client now keeps a cache keyed by `homeAccountId` alongside an active account, matching MSAL:
+
+  - `getAccount(filter)` matches on `homeAccountId`, `localAccountId`, `username` and `tenantId`.
+  - `getAllAccounts()` returns everything cached.
+  - Signing in adds the account and activates it; signing out removes it, rather than leaving a stale entry behind.
+  - `setUser` replaces the session, so declaring a second user never leaves two accounts cached.
+
+  `setActiveAccount` deliberately departs from MSAL in one respect: an account that was never issued by a sign-in is accepted and added to the cache. That makes swapping the user between tests a single line, without rebuilding the framework:
+
+  ```typescript
+  beforeEach(() => {
+    fusion.modules.auth.client.setActiveAccount(account);
+  });
+  ```
+
+- 2836e0b: Added a `./mock` entry point so applications can run against the auth module without credentials or network access.
+
+  ```ts
+  import {
+    enableMsalMock,
+    createMsalMockClient,
+  } from "@equinor/fusion-framework-module-msal/mock";
+
+  // default mock user
+  enableMsalMock(configurator);
+
+  // or a specific one
+  enableMsalMock(configurator, (builder) => {
+    builder.setAccount({ name: "Ada Lovelace" });
+  });
+  ```
+
+  Only the MSAL **client** is substituted. `MsalMockClient` resolves tokens in-process and takes the same `MsalClientConfig` as the real `MsalClient`, so `setClientConfig` means the same thing whether a test runs against Entra ID or in-process. `MsalMockConfigurator` builds it through the `_createClient` seam, and `msalMockModule` differs from the real module in its `configure` alone — `initialize` is the production one, untouched, so `MsalProvider`, schema validation and the whole start-up path run exactly as they do in production. `IMsalProvider` and `MsalConfigurator` are untouched.
+
+  The same client works with the plain module, without the mock module:
+
+  ```ts
+  enableMSAL(configurator, (builder) =>
+    builder.setClient(
+      createMsalMockClient(
+        { auth: { clientId: "my-app" } },
+        { name: "Ada Lovelace" },
+      ),
+    ),
+  );
+  ```
+
+  Tokens are structurally valid, unsigned JWTs and are identical between runs. They are not cryptographically valid and are rejected by any real service.
+
+  Exports `enableMsalMock`, `msalMockModule`, `MsalMockConfigurator`, `MsalMockClient`, `createMsalMockClient` and `createMockToken`. The entry point has no test-runner dependency.
+
+- 2836e0b: Add `setAccount` to `MsalMockConfigurator`, so a test declares the signed-in user on the builder instead of baking it into a client.
+
+  ```typescript
+  enableMsalMock(configurator, (builder) => {
+    builder.setAccount({ name: "Ada Lovelace", username: "ada@equinor.com" });
+  });
+  ```
+
+  It takes an object, `null` when nobody is signed in, or an ordinary `ConfigBuilderCallback` resolving either:
+
+  ```typescript
+  builder.setAccount(null);
+  builder.setAccount(async ({ hasModule }) => ({
+    name: hasModule("app") ? "App User" : "Portal User",
+  }));
+  ```
+
+  The callback is the builder's own type rather than a bespoke one, so it is handed the same arguments every other configuration callback receives and is resolved by the same machinery.
+
+  `null` and `{ signedOut: true }` both start without a session, and differ in what a later login resolves to: `null` forgets the identity, `signedOut` keeps it. A declared `null` is a declaration in its own right, so it overrides the default signed-in user — only an absent declaration means the test said nothing.
+
+  `setAccount` writes to `mock.account` on the configuration rather than to a field on the builder, so the user travels the ordinary builder pipeline: a callback is resolved by `_buildConfig` with the same arguments every other configuration callback receives, and the result is on the raw configuration before validation. The schema strips the key, so nothing about a test reaches `MsalProvider` — the branch exists purely to carry the declaration across the builder. `MsalMockConfig` is exported for code that reads it.
+
+  `setAccount` records configuration only — the user is signed in on the client as it is built, so it may be declared at any point before initialization and the last declaration wins. Keeping the user off `MsalClientConfig` is what lets `MsalMockClient` take the same argument the real `MsalClient` takes: a client is configured with _what it talks to_, never with _who is signed in_.
+
+  Because the user is in place before `MsalProvider.initialize()` runs, the provider's own start-up path acts on it. Pairing `{ signedOut: true }` with `setRequiresAuth(true)` therefore exercises the real automatic login, rather than a state assigned after initialization had already finished.
+
+  Because who is signed in is session state rather than client configuration, the user is applied to whichever client the module ends up authenticating through — wherever that client was built. When the module is hoisted onto a host application's provider, no client is built here, so the user is signed in on the _host's_ client instead. Without that, a declaration made in an application's test would silently do nothing precisely when the application is being tested inside a portal. The session is shared, so the host sees the same user, as it does in production; when the host does not authenticate through a mock client the declaration throws rather than failing quietly.
+
+  `setClient` replaces the client, but not the rule: a mock client supplied that way receives the declared user too.
+
+### Patch Changes
+
+- e8aae1f: Internal: publish every package on the `next` pre-release tag so the whole framework can be installed as a coherent set.
+
+  Packages without their own changes are bumped only to receive a `-next.N` version and the `next` dist-tag on npm. Install with:
+
+  ```bash
+  pnpm add @equinor/fusion-framework-react-app@next
+  ```
+
+- 2836e0b: Restructure documentation so each README is an entry point rather than a manual.
+
+  Long-form content moved into per-package `docs/` folders, matching the convention already used by `@equinor/fusion-framework-module` and `@equinor/fusion-framework-module-http`. Each README now keeps the elevator pitch, the shortest working example and a documentation table linking to the rest.
+
+  - **msal** — `docs/api-reference.md`, `docs/auth-code-flow.md`, `docs/testing.md`, `docs/version-management.md`, `docs/migration-v2-to-v4.md`, `docs/troubleshooting.md`. The README also gained the top-level heading it was missing.
+  - **service-discovery** — `docs/configuration.md`, `docs/testing.md`, `docs/session-overrides.md`, `docs/api-reference.md`.
+  - **framework** — `docs/testing-choosing-a-layer.md`, `docs/testing.md`, `docs/testing-design.md`, `docs/testing-extending.md`, `docs/testing-api.md`.
+
+  Both module READMEs now document their `/mock` entry point, which was previously undocumented, and state that spying on an individual call is the test runner's job rather than something these packages provide.
+
+- 2836e0b: Remove a stray `console.log` left in `resolveVersion`'s minor-version-mismatch warning path.
+- Updated dependencies [e8aae1f]
+- Updated dependencies [2836e0b]
+- Updated dependencies [2836e0b]
+- Updated dependencies [2836e0b]
+- Updated dependencies [2836e0b]
+- Updated dependencies [2836e0b]
+  - @equinor/fusion-framework-module@6.1.3-next.0
+  - @equinor/fusion-framework-module-telemetry@8.0.0-next.0
+
+## 10.0.2
+
+### Patch Changes
+
+- 80c3e4a: Internal: resolve `noExplicitAny`/`noConfusingVoidType` Biome warnings in `enableMSAL`'s configurator widening and the `onRedirectNavigate` callback types (v2/v4), plus safely tighten interface method return types (`login`/`acquireToken` in `IAuthClient`, `MsalProvider`) from `| void` to `| undefined`. No public API or behavior change.
+- 80c3e4a: Internal: add required fusion-lint intent comments explaining `as unknown as T` casts in the v2 proxy client and provider adapters. No behavior change.
+- 80c3e4a: Internal: resolve fusion-lint warnings across the package — added missing TSDoc (`@returns`, `@param`, `@throws`, `@template`) on public APIs, added intent comments above control-flow, `switch`, and RxJS/array chains, and split the v2-compatible `Logger` class out of `v2/types.ts` into `v2/Logger.ts` to satisfy the single-export-per-file rule. No public behavior changes; `Logger` remains available from `@equinor/fusion-framework-module-msal/v2`.
+
+  Two deferred TODOs now reference tracked issues: throwing when `MsalProvider.acquireToken` is called with empty scopes and no default scope (https://github.com/equinor/fusion-framework/issues/5113), and reconsidering the `MsalModule` proxy-provider fallback once all apps migrate to v4 (https://github.com/equinor/fusion-framework/issues/5114).
+
 ## 10.0.1
 
 ### Patch Changes

package/README.md

@@ -1,3 +1,4 @@
+# `@equinor/fusion-framework-module-msal`
 
 `@equinor/fusion-framework-module-msal` provides secure Azure AD authentication for browser applications using Microsoft's MSAL (Microsoft Authentication Library). Perfect for web applications, SPAs, and React apps that need to authenticate with Microsoft services.
 
@@ -78,92 +79,16 @@ try {
 > [!IMPORTANT]
 > The `@equinor/fusion-framework-app` enables this package by default, so applications using the app package do not need to enable this module manually.
 
-## Backend-Issued Auth Code Flow
+## Documentation
 
-Enable automatic sign-in using a backend-issued authorization code without interactive login prompts.
-
-### Overview
-
-When your backend authenticates a user and generates a short-lived SPA auth code, the MSAL module can exchange it for tokens during initialization, eliminating double-login issues and providing seamless authentication.
-
-### Usage
-
-```typescript
-import { enableMSAL } from '@equinor/fusion-framework-module-msal';
-
-enableMSAL(configurator, (builder) => {
-  builder.setClientConfig({
-    auth: {
-      clientId: 'your-client-id',
-      tenantId: 'your-tenant-id'
-    }
-  });
-
-  // Backend injects auth code as window.MSAL_AUTH_CODE during initial first page load
-  // This is the most secure approach - only available on first render, cleared after use
-  if (typeof window !== 'undefined' && window.MSAL_AUTH_CODE) {
-    builder.setAuthCode(window.MSAL_AUTH_CODE);
-    delete (window as any).MSAL_AUTH_CODE; // Clear after consuming
-  }
-
-  builder.setRequiresAuth(true);
-});
-```
-
-### How It Works
-
-1. Backend authenticates user and generates short-lived auth code
-2. Frontend passes auth code to MSAL: `builder.setAuthCode(authCode)`
-3. During `initialize()`: auth code exchanged for tokens (before `requiresAuth` check)
-4. Tokens cached by MSAL → user automatically signed in
-5. Falls back to standard MSAL flows on exchange failure
-
-### API: `setAuthCode(authCode?: string)`
-
-Sets backend-issued auth code for token exchange during initialization.
-
-Pass `undefined` to clear/reset a previously configured auth code.
-
-**Returns:** configurator instance (chainable)
-
-**Behavior:**
-- Exchange happens before `requiresAuth` check
-- On success: user auto-authenticated, no login prompt
-- On failure: falls back to standard MSAL login
-- Auth code cleared after exchange (no reuse)
-- `setAuthCode(undefined)` clears configured auth code
-- `setAuthCode('')` is treated as absent auth code
-- `setAuthCode('   ')` is trimmed and treated as absent auth code
-- No auth-code exchange is attempted when auth code is absent/cleared
-
-**Example:**
-
-```typescript
-// Best practice: Backend injects auth code on initial page load as window.MSAL_AUTH_CODE
-if (typeof window !== 'undefined' && window.MSAL_AUTH_CODE) {
-  builder.setAuthCode(window.MSAL_AUTH_CODE);
-  delete (window as any).MSAL_AUTH_CODE; // Clear after consuming to prevent reuse
-}
-
-// Clear/reset auth code when input is missing
-builder.setAuthCode(undefined);
-```
-
-### Security
-
-- ✅ Auth codes: single-use, short-lived (5-10 min)
-- ✅ MSAL validates tokens from Microsoft authority
-- ✅ Tokens stored securely, refresh tokens auto-managed
-- ⚠️ Pass codes securely: HTTPS, HTTP-only cookies, or encrypted channels
-
-### Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| Auth code not exchanged | Verify `setAuthCode()` called before init |
-| Invalid auth code error | Confirm backend `WithSpaAuthCode` enabled, code is fresh |
-| Still shows login prompt | Check auth code exchange completes before `requiresAuth` check |
-| Exchange fails | Auth code may have expired; backend should generate fresh code per load |
+| Guide | Covers |
+| --- | --- |
+| [Configuration](./docs/api-reference.md) | `enableMSAL`, builder methods, `IMsalProvider`, and type definitions |
+| [Backend-Issued Auth Code Flow](./docs/auth-code-flow.md) | Signing a user in from a backend-issued SPA auth code, without an interactive prompt |
+| [Testing](./docs/testing.md) | The `/mock` entry point: in-process authentication, deterministic tokens, and spying |
+| [Version Management](./docs/version-management.md) | Version resolution, compatibility checking, and related errors |
+| [Migration v2 to v4](./docs/migration-v2-to-v4.md) | Moving from MSAL Browser v2 to v4, including the compatibility proxy |
+| [Troubleshooting](./docs/troubleshooting.md) | Common failures and where to get help |
 
 ## Configuration
 
@@ -193,92 +118,21 @@ AZURE_TENANT_ID=your-tenant-id
 AZURE_REDIRECT_URI=https://your-app.com/callback
 ```
 
-## API Reference
-
-### `enableMSAL(configurator, configure?)`
-
-Enables the MSAL module in your Fusion Framework application.
-
-**Parameters:**
-- `configurator`: `IModulesConfigurator` - The modules configurator instance
-- `configure?`: `(builder: { setClientConfig, setRequiresAuth }) => void` - Optional configuration function
-
-**Returns:** `void`
-
-**Example:**
-```typescript
-enableMSAL(configurator, (builder) => {
-  builder.setClientConfig({ auth: { clientId: '...', tenantId: '...' } });
-  builder.setRequiresAuth(true);
-});
-```
-
-### Type Definitions
+## Testing
 
-#### `LoginOptions`
+Import from `@equinor/fusion-framework-module-msal/mock` to authenticate in-process instead of against Entra ID. The real configurator, provider and schema validation still run — only the client that would contact Entra ID is substituted.
 
 ```typescript
-type LoginOptions = {
-  request: PopupRequest | RedirectRequest;  // MSAL request object
-  behavior?: 'popup' | 'redirect';          // Auth method (default: 'redirect')
-  silent?: boolean;                         // Attempt silent auth first (default: true)
-};
-```
-
-#### `LogoutOptions`
+import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';
 
-```typescript
-type LogoutOptions = {
-  redirectUri?: string;                     // Redirect after logout
-  account?: AccountInfo;                    // Account to logout (defaults to active)
-};
+enableMsalMock(configurator);
 ```
 
-#### `AcquireTokenOptions`
+A user named `Test User` is signed in, and tokens are real JWTs minted in-process with a fixed issue time, so they are identical across runs and machines.
 
-```typescript
-type AcquireTokenOptions = {
-  request: PopupRequest | RedirectRequest;  // MSAL request with scopes
-  behavior?: 'popup' | 'redirect';          // Auth method (default: 'redirect')
-  silent?: boolean;                         // Attempt silent first (default: true if account available)
-};
-```
-
-### `IMsalProvider`
-
-The authentication provider interface available at `framework.auth`:
-
-```typescript
-interface IMsalProvider {
-  // The MSAL PublicClientApplication instance
-  readonly client: IMsalClient;
-  
-  // Current user account information
-  readonly account: AccountInfo | null;
-  
-  // Initialize the MSAL provider
-  initialize(): Promise<void>;
-  
-  // Acquire an access token for the specified scopes
-  acquireAccessToken(options: AcquireTokenOptionsLegacy): Promise<string | undefined>;
-  
-  // Acquire full authentication result
-  acquireToken(options: AcquireTokenOptionsLegacy): Promise<AcquireTokenResult>;
-  
-  // Login user interactively
-  login(options: LoginOptions): Promise<LoginResult>;
-  
-  // Logout user (returns boolean)
-  logout(options?: LogoutOptions): Promise<boolean>;
-  
-  // Handle authentication redirect (returns AuthenticationResult | null)
-  handleRedirect(): Promise<AuthenticationResult | null>;
-}
-
-// Note: defaultAccount and other deprecated v2 properties are available only
-//       when using a v2-compatible proxy via createProxyProvider()
-```
+The entry point has **no test-runner dependency**, and ships no mocking API of its own — spying on a call is your test runner's job.
 
+See [Testing](./docs/testing.md) for choosing the signed-in user, signed-out behaviour and runner guidance, or [`@equinor/fusion-framework/mock`](../../framework/docs/testing.md) to mock every framework boundary at once.
 
 ## Module Hoisting
 
@@ -287,208 +141,6 @@ The module implements a hoisting pattern where the authentication provider is cr
 > [!IMPORTANT]
 > **Configure the auth module only in the root Fusion Framework instance** - Sub-instances will automatically inherit the authentication configuration from the parent.
 
-## Migration Guide
-
-### MSAL v2 to v4 Migration
-
-This package has been upgraded from MSAL Browser v2 to v4, providing the latest security improvements and features from Microsoft.
-
-#### What Changed in v4
-
-**New MSAL Browser v4 Features:**
-- Enhanced security with improved token management
-- Better performance and memory usage
-- New authentication API structure with nested request objects
-- Improved error handling and retry mechanisms
-
-**Architecture Changes:**
-- **Module Hoisting**: The module uses module hoisting, meaning sub-module instances proxy the parent module instance
-- **Shared Authentication State**: Authentication state is shared across all module instances
-- **Async Initialization**: New `initialize()` method must be called before using the provider
-
-#### Breaking Changes
-
-1. **Auto-initialization via Framework**
-   ```typescript
-   // The provider initializes automatically when framework loads
-   const framework = await initialize(configurator);
-   const auth = framework.auth; // Already initialized
-   
-   // Manual initialization is only needed for standalone usage
-   const provider = new MsalProvider(config);
-   await provider.initialize();
-   ```
-
-2. **API Method Signature Updates**
-   - `logout()` now returns `Promise<boolean>` instead of `Promise<void>`
-   - `handleRedirect()` now returns `Promise<AuthenticationResult | null>` instead of `Promise<void>`
-   - Methods now expect nested request objects (v4 format)
-
-3. **Account Property Changes**
-   - Use `account` property (returns `AccountInfo | null`) - v4 native
-   - `defaultAccount` is deprecated and only available via v2 proxy layer
-   - Migration: Replace `defaultAccount` with `account` throughout your code
-
-#### Migration Steps
-
-1. **Update Token Acquisition** (Recommended)
-   ```typescript
-   // Before (v2 format - still works via proxy)
-   const token = await framework.auth.acquireAccessToken({ 
-     scopes: ['api.read'] 
-   });
-   
-   // After (v4 format - recommended)
-   const token = await framework.auth.acquireAccessToken({ 
-     request: { scopes: ['api.read'] } 
-   });
-   ```
-
-2. **Update Logout Handling**
-   ```typescript
-   // Before
-   await framework.auth.logout();
-   
-   // After (check return value)
-   const success = await framework.auth.logout();
-   if (success) {
-     // Handle successful logout
-   }
-   ```
-
-3. **Update Redirect Handling**
-   ```typescript
-   // Before
-   await framework.auth.handleRedirect();
-   
-   // After (handle result)
-   const result = await framework.auth.handleRedirect();
-   if (result?.account) {
-     // User authenticated successfully
-     console.log('Logged in as:', result.account.username);
-   }
-   ```
-
-4. **Update Configuration** (if needed)
-   ```typescript
-   // Ensure only the root module configures MSAL
-   enableMSAL(configurator, (builder) => {
-     builder.setClientConfig({
-       auth: {
-         clientId: 'your-client-id',
-         tenantId: 'your-tenant-id',
-         redirectUri: 'https://your-app.com/callback'
-       }
-     });
-     builder.setRequiresAuth(true);
-   });
-   ```
-
-5. **Remove Duplicate Configurations**: Remove MSAL configuration from child modules
-
-#### Backward Compatibility
-
-The module includes a **v2 proxy layer** that automatically converts v2 API calls to v4 format. This means:
-- ✅ Existing code continues to work without changes
-- ✅ Legacy format `{ scopes: [] }` is still supported
-- ✅ Deprecated v2 properties like `defaultAccount` are available via v2 proxy (with deprecation warnings)
-- ⚠️ New v4 features require using v4 format
-
-#### Benefits of Migration
-
-- **Better Security**: Latest MSAL v4 security improvements and token handling
-- **Improved Performance**: Faster token acquisition, better caching, reduced memory usage
-- **Enhanced Error Handling**: More robust error recovery and retry mechanisms
-- **Future-Proof**: Access to latest Microsoft authentication features and updates
-- **Shared State**: Improved authentication state management across app scopes via module hoisting
-- **Better Developer Experience**: Cleaner API, better TypeScript support, comprehensive documentation
-
-## Troubleshooting
-
-### Common Issues
-
-| Issue | Solution |
-|-------|----------|
-| **Authentication Loop** | Ensure redirect URIs match your application's routing |
-| **Token Acquisition Fails** | Check that required scopes are properly configured |
-| **Module Not Found** | Ensure the module is properly configured and framework is initialized |
-| **Multiple MSAL Instances** | Remove duplicate configurations from child modules |
-| **Redirect Returns Void** | For redirect flows, use `handleRedirect()` after navigation completes |
-| **Token Empty/Undefined** | Verify user is authenticated and scopes are correct |
-
-### Getting Help
-
-- 📖 [MSAL Cookbook](https://github.com/equinor/fusion-framework/tree/main/cookbooks/app-react-msal) - Complete working examples
-- 🐛 [Report Issues](https://github.com/equinor/fusion/issues) - Bug reports and feature requests
-
-## Version Management
-
-The MSAL module includes built-in version checking to ensure compatibility between different MSAL library versions.
-
-### Version Resolution
-
-```typescript
-import { resolveVersion, VersionError } from '@equinor/fusion-framework-module-msal/versioning';
-
-// Resolve and validate a version
-const result = resolveVersion('2.0.0');
-console.log(result.isLatest); // false
-console.log(result.satisfiesLatest); // true
-console.log(result.enumVersion); // MsalModuleVersion.V2
-```
-
-### Version Checking Behavior
-
-- **Major Version Incompatibility**: Throws `VersionError` if requested major version is greater than latest
-- **Minor Version Mismatch**: Logs warning but allows execution
-- **Patch Differences**: Ignored for compatibility
-- **Invalid Versions**: Throws `VersionError` with descriptive message
-
-### API Reference
-
-#### `resolveVersion(version: string | SemVer): ResolvedVersion`
-
-Resolves and validates a version string against the latest available MSAL version.
-
-**Parameters:**
-- `version` - Version string or SemVer object to resolve
-
-**Returns:** `ResolvedVersion` object containing:
-- `wantedVersion: SemVer` - The parsed requested version
-- `latestVersion: SemVer` - The latest available version
-- `isLatest: boolean` - Whether the version is exactly the latest
-- `satisfiesLatest: boolean` - Whether the major version matches latest
-- `enumVersion: MsalModuleVersion` - Corresponding enum version
-
-**Throws:** `VersionError` for invalid or incompatible versions
-
-#### `VersionError`
-
-Error class for version-related issues with the following types:
-- `InvalidVersion` - Requested version is not a valid semver
-- `InvalidLatestVersion` - Latest version parsing failed (build issue)
-- `MajorIncompatibility` - Major version is greater than latest
-- `MinorMismatch` - Minor version differs (warning only)
-- `PatchDifference` - Patch version differs (info only)
-- `IncompatibleVersion` - General incompatibility
-
-### Error Handling
-
-```typescript
-import { resolveVersion, VersionError } from '@equinor/fusion-framework-module-msal/versioning';
-
-try {
-  const result = 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);
-  }
-}
-```
-
 ## Additional Resources
 
 ### Official Documentation
@@ -507,6 +159,3 @@ try {
 - 💬 For questions: [Fusion Framework Discussions](https://github.com/equinor/fusion-framework/discussions)
 - 🐛 Report bugs: [Fusion Framework Issues](https://github.com/equinor/fusion-framework/issues)
 - 📧 Contact: Equinor Fusion Framework Team
-
-
-

package/dist/esm/MsalClient.js

@@ -84,11 +84,14 @@ export class MsalClient extends PublicClientApplication {
      * - **Redirect**: Navigates browser to Microsoft login page. Returns `void` because the browser
      *   navigates to a new page. After redirect completes, the result will be available via
      *   `handleRedirectPromise()` when the app loads on the new page.
+     *
+     * @throws {Error} If an invalid `options.behavior` value is provided.
      */
     async login(options) {
         // Attempt silent authentication first if enabled
         // This provides better UX by avoiding unnecessary popups/redirects
         if (options.silent) {
+            // Warn early when neither an account nor login hint is available for silent SSO
             if (!options.request.account && !options.request.loginHint) {
                 this.getLogger().warning('No account or login hint provided, please provide an account or login hint in the request', options.request.correlationId || FUSION_CORRELATION_ID);
             }
@@ -146,6 +149,7 @@ export class MsalClient extends PublicClientApplication {
      * ```
      */
     async logout(options) {
+        // Warn when no account was supplied since the active account will be used instead
         if (!options?.account) {
             this.getLogger().warning('No account available for logout, please provide an account in the options', FUSION_CORRELATION_ID);
         }
@@ -177,18 +181,23 @@ export class MsalClient extends PublicClientApplication {
      *
      * The default silent behavior is determined by presence of account in the request.
      * This provides optimal UX by minimizing unnecessary user interactions.
+     *
+     * @throws {Error} If no `request` is provided in `options`.
      */
     async acquireToken(options) {
         const { behavior = 'redirect', silent = !!options.request?.account, request } = options;
+        // A request is required to know which scopes/account to acquire a token for
         if (!request) {
             throw new Error('No request provided, please provide a request in the options');
         }
+        // Warn when no scopes are requested, since MSAL requires at least one scope
         if (request.scopes.length === 0) {
             this.getLogger().warning('No scopes provided, please provide scopes in the request option, see options.request for more information.', request.correlationId || FUSION_CORRELATION_ID);
         }
         // Attempt silent token acquisition first
         // This fetches from cache or uses refresh token without user interaction
         if (silent) {
+            // Only silent-acquire when an account is available to look up cached tokens for
             if (request.account) {
                 try {
                     this.getLogger().verbose('Attempting to acquire token silently', request.correlationId || FUSION_CORRELATION_ID);

package/dist/esm/MsalClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"MsalClient.js","sourceRoot":"","sources":["../../src/MsalClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MsalClient.js","sourceRoot":"","sources":["../../src/MsalClient.ts"],"names":[],"mappings":"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"}