@chemmangat/msal-next 3.0.8 → 3.1.1

package/MIGRATION_GUIDE_v3.md

@@ -0,0 +1,367 @@
+# Migration Guide: v2.x to v3.0.0
+
+This guide will help you migrate from @chemmangat/msal-next v2.x to v3.0.0.
+
+## Overview
+
+v3.0.0 is a major release with breaking changes focused on:
+- Updated minimum requirements
+- Removed deprecated APIs
+- Enhanced debugging capabilities
+- New CLI tool for easier setup
+
+## Quick Migration Checklist
+
+- [ ] Update Node.js to v18+
+- [ ] Update Next.js to v14.1+
+- [ ] Update MSAL packages to v4+
+- [ ] Update @chemmangat/msal-next to v3.0.0
+- [ ] Remove usage of deprecated APIs
+- [ ] Test your application thoroughly
+
+## Step-by-Step Migration
+
+### 1. Update Node.js
+
+v3.0.0 requires Node.js 18 or higher.
+
+```bash
+# Check your current version
+node --version
+
+# If < 18, update Node.js
+# Using nvm:
+nvm install 18
+nvm use 18
+
+# Or download from nodejs.org
+```
+
+### 2. Update Dependencies
+
+Update your `package.json`:
+
+```bash
+# Update core packages
+npm install @chemmangat/msal-next@^3.0.0
+npm install @azure/msal-browser@^4.0.0
+npm install @azure/msal-react@^3.0.0
+npm install next@^14.1.0
+
+# Or use the CLI
+npx @chemmangat/msal-next init
+```
+
+**Before** (package.json):
+```json
+{
+  "dependencies": {
+    "@chemmangat/msal-next": "^2.3.0",
+    "@azure/msal-browser": "^3.11.0",
+    "@azure/msal-react": "^2.0.0",
+    "next": "^14.0.0"
+  }
+}
+```
+
+**After** (package.json):
+```json
+{
+  "dependencies": {
+    "@chemmangat/msal-next": "^3.0.0",
+    "@azure/msal-browser": "^4.0.0",
+    "@azure/msal-react": "^3.0.0",
+    "next": "^14.1.0"
+  }
+}
+```
+
+### 3. Remove Deprecated APIs
+
+#### ServerSession.accessToken
+
+The `ServerSession.accessToken` property has been removed for security reasons.
+
+**Before** (v2.x):
+```typescript
+// ❌ This no longer works
+import { getServerSession } from '@chemmangat/msal-next/server';
+
+export default async function Page() {
+  const session = await getServerSession();
+  const token = session.accessToken; // ❌ Removed
+  
+  // Use token for API calls
+  const response = await fetch('https://graph.microsoft.com/v1.0/me', {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+}
+```
+
+**After** (v3.0.0):
+```typescript
+// ✅ Use client-side token acquisition
+'use client';
+
+import { useMsalAuth } from '@chemmangat/msal-next';
+
+export default function Page() {
+  const { acquireToken } = useMsalAuth();
+  
+  const fetchData = async () => {
+    const token = await acquireToken(['User.Read']);
+    
+    const response = await fetch('https://graph.microsoft.com/v1.0/me', {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+  };
+  
+  return <button onClick={fetchData}>Fetch Data</button>;
+}
+```
+
+**Alternative**: Use the `useGraphApi` hook:
+```typescript
+'use client';
+
+import { useGraphApi } from '@chemmangat/msal-next';
+
+export default function Page() {
+  const graph = useGraphApi();
+  
+  const fetchData = async () => {
+    const user = await graph.get('/me');
+    console.log(user);
+  };
+  
+  return <button onClick={fetchData}>Fetch Data</button>;
+}
+```
+
+### 4. Update Debug Configuration
+
+The debug logger has been enhanced with new options.
+
+**Before** (v2.x):
+```typescript
+<MsalAuthProvider
+  clientId={process.env.NEXT_PUBLIC_CLIENT_ID!}
+  enableLogging={true}
+>
+  {children}
+</MsalAuthProvider>
+```
+
+**After** (v3.0.0) - Same API, but with new capabilities:
+```typescript
+<MsalAuthProvider
+  clientId={process.env.NEXT_PUBLIC_CLIENT_ID!}
+  enableLogging={true}
+  // New: Enhanced logging is automatic
+>
+  {children}
+</MsalAuthProvider>
+
+// Access enhanced logger features
+import { getDebugLogger } from '@chemmangat/msal-next';
+
+const logger = getDebugLogger({
+  enabled: true,
+  enablePerformance: true,    // NEW
+  enableNetworkLogs: true,    // NEW
+  maxHistorySize: 100,        // NEW
+});
+
+// NEW: Performance tracking
+logger.startTiming('operation');
+// ... do work
+logger.endTiming('operation');
+
+// NEW: Export logs
+logger.downloadLogs();
+```
+
+### 5. Update TypeScript Configuration (if needed)
+
+Ensure your `tsconfig.json` is compatible:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true
+  }
+}
+```
+
+## New Features You Can Use
+
+### 1. CLI Tool
+
+Use the new CLI for easier setup:
+
+```bash
+# Initialize in existing project
+npx @chemmangat/msal-next init
+
+# Add components
+npx @chemmangat/msal-next add auth-guard
+
+# Configure Azure AD
+npx @chemmangat/msal-next configure
+```
+
+### 2. Enhanced Debug Logger
+
+```typescript
+import { getDebugLogger } from '@chemmangat/msal-next';
+
+const logger = getDebugLogger({
+  enabled: true,
+  level: 'debug',
+  enablePerformance: true,
+  enableNetworkLogs: true,
+});
+
+// Track performance
+logger.startTiming('token-acquisition');
+const token = await acquireToken(['User.Read']);
+logger.endTiming('token-acquisition');
+
+// Log network requests
+logger.logRequest('GET', '/me');
+logger.logResponse('GET', '/me', 200, userData);
+
+// Export logs for debugging
+logger.downloadLogs('debug-logs.json');
+```
+
+### 3. New Examples
+
+Check out the new examples in `src/examples/`:
+- Role-based routing
+- Multi-tenant SaaS
+- API route protection
+- Graph API integration
+
+## Common Issues and Solutions
+
+### Issue: "Module not found: @azure/msal-browser"
+
+**Solution**: Update to MSAL v4:
+```bash
+npm install @azure/msal-browser@^4.0.0 @azure/msal-react@^3.0.0
+```
+
+### Issue: "ServerSession.accessToken is undefined"
+
+**Solution**: This property was removed. Use client-side token acquisition:
+```typescript
+const { acquireToken } = useMsalAuth();
+const token = await acquireToken(['User.Read']);
+```
+
+### Issue: "Node.js version not supported"
+
+**Solution**: Update to Node.js 18+:
+```bash
+nvm install 18
+nvm use 18
+```
+
+### Issue: TypeScript errors after upgrade
+
+**Solution**: Update TypeScript and type definitions:
+```bash
+npm install -D typescript@^5.3.0
+npm install -D @types/react@^18.2.0
+```
+
+## Testing Your Migration
+
+After migrating, test these critical paths:
+
+1. **Authentication Flow**
+   ```typescript
+   // Test login
+   await loginPopup();
+   
+   // Test token acquisition
+   const token = await acquireToken(['User.Read']);
+   
+   // Test logout
+   await logoutPopup();
+   ```
+
+2. **Protected Routes**
+   - Visit protected pages
+   - Verify redirects work
+   - Check middleware behavior
+
+3. **API Calls**
+   - Test Graph API calls
+   - Verify token refresh
+   - Check error handling
+
+4. **Components**
+   - Test all auth components
+   - Verify UI renders correctly
+   - Check loading states
+
+## Rollback Plan
+
+If you encounter issues, you can rollback:
+
+```bash
+# Rollback to v2.3.0
+npm install @chemmangat/msal-next@2.3.0
+npm install @azure/msal-browser@^3.11.0
+npm install @azure/msal-react@^2.0.0
+```
+
+## Getting Help
+
+If you need assistance:
+
+1. **Documentation**: Check the [README](./README.md) and [SECURITY.md](./SECURITY.md)
+2. **Examples**: Review examples in `src/examples/`
+3. **Issues**: Open an issue on [GitHub](https://github.com/chemmangat/msal-next/issues)
+4. **Discussions**: Ask questions in [GitHub Discussions](https://github.com/chemmangat/msal-next/discussions)
+
+## Automated Migration (Coming Soon)
+
+We're working on an automated migration tool:
+
+```bash
+# Future feature
+npx @chemmangat/msal-next migrate
+```
+
+This will automatically:
+- Update dependencies
+- Remove deprecated code
+- Update configuration
+- Generate migration report
+
+## Summary
+
+v3.0.0 brings enhanced debugging, a new CLI tool, and better developer experience. While there are breaking changes, the migration path is straightforward:
+
+1. Update Node.js to 18+
+2. Update dependencies
+3. Remove `ServerSession.accessToken` usage
+4. Test thoroughly
+
+The new features make it worth the upgrade!
+
+---
+
+**Need Help?** Open an issue or discussion on GitHub.  
+**Found a Bug?** Please report it with reproduction steps.  
+**Have Feedback?** We'd love to hear from you!
+
+**Last Updated**: March 5, 2026  
+**Version**: 3.0.0

package/README.md

@@ -5,7 +5,9 @@ Production-grade MSAL authentication library for Next.js App Router with minimal
 [![npm version](https://badge.fury.io/js/@chemmangat%2Fmsal-next.svg)](https://www.npmjs.com/package/@chemmangat/msal-next)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **v3.0.0 is here!** 🎉 New CLI tool, enhanced debugging, and better DX. [See what's new](#whats-new-in-v30)
+> **📦 Current Version: 3.0.8** - Critical bug fixes for popup authentication. [See changelog](./CHANGELOG.md)
+
+> **⚠️ Important:** If you're on v3.0.6 or v3.0.7, please update immediately - those versions have a critical popup authentication bug.
 
 > **Having issues?** Check the [Troubleshooting Guide](./TROUBLESHOOTING.md) for common problems and solutions.
 
@@ -82,7 +84,7 @@ npx @chemmangat/msal-next init
 
 ### Option 2: Manual Installation
 ```bash
-npm install @chemmangat/msal-next@3.0.0 @azure/msal-browser@^4.0.0 @azure/msal-react@^3.0.0
+npm install @chemmangat/msal-next@latest @azure/msal-browser@^4.0.0 @azure/msal-react@^3.0.0
 ```
 
 ## Quick Start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemmangat/msal-next",
-  "version": "3.0.8",
+  "version": "3.1.1",
   "description": "Production-grade MSAL authentication package for Next.js App Router with minimal boilerplate",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -20,10 +20,10 @@
   "files": [
     "dist",
     "README.md",
-    "SECURITY.md",
-    "TROUBLESHOOTING.md",
     "CHANGELOG.md",
-    "RELEASE_NOTES_v3.0.8.md"
+    "MIGRATION_GUIDE_v3.md",
+    "SECURITY.md",
+    "TROUBLESHOOTING.md"
   ],
   "scripts": {
     "build": "tsup",

package/RELEASE_NOTES_v3.0.8.md

@@ -1,70 +0,0 @@
-# Release Notes - v3.0.8 (Critical Bug Fix)
-
-## 🚨 Critical Update Required
-
-If you're using v3.0.6 or v3.0.7, please update immediately. These versions have a critical bug that breaks popup authentication.
-
-## What Happened?
-
-In v3.0.6, we attempted to fix a popup redirect issue by skipping `handleRedirectPromise()` in popup windows. This was incorrect and broke the authentication flow for popup-based logins.
-
-## The Fix
-
-v3.0.8 properly handles the popup flow by:
-1. Calling `handleRedirectPromise()` in ALL windows (main and popup)
-2. Only cleaning the URL in the main window
-3. Allowing the popup to close naturally after MSAL processes the redirect
-
-## Update Instructions
-
-```bash
-npm install @chemmangat/msal-next@3.0.8
-```
-
-No code changes required. Your existing implementation will work correctly.
-
-## Verified Scenarios
-
-### ✅ Working
-- Popup login flow
-- Redirect login flow
-- User cancellation
-- Page refresh during auth
-- Multiple tabs
-- Token acquisition
-- Logout flows
-- SSR/hydration
-
-### ✅ Fixed Issues
-- Popup not closing after authentication
-- URL showing auth code after login
-- Button staying disabled after popup closes
-- Redirect happening in popup window
-
-## For Users on v2.x
-
-If you're still on v2.x, you can safely upgrade to v3.0.8. All v2.x functionality is preserved with additional improvements.
-
-## Support
-
-If you encounter any issues:
-1. Check the [Troubleshooting Guide](./TROUBLESHOOTING.md)
-2. Review [Test Scenarios](./TEST_SCENARIOS.md)
-3. Open an issue on GitHub with:
-   - Your version number
-   - Browser and OS
-   - Steps to reproduce
-   - Console errors
-
-## Apology
-
-We sincerely apologize for the disruption caused by v3.0.6 and v3.0.7. We've implemented additional testing procedures to prevent similar issues in the future.
-
-## Next Steps
-
-1. Update to v3.0.8
-2. Test your authentication flows
-3. Report any issues immediately
-4. Consider implementing the test scenarios in your own testing
-
-Thank you for your patience and continued use of @chemmangat/msal-next.