saafe-redirection-flow 2.0.0

package/RELEASE_CHEATSHEET.md

@@ -0,0 +1,93 @@
+# 🚀 Quick Release Commands
+
+## 📋 Branch Strategy
+- **sandbox** → **stage** → **prod** (Production)
+- main branch is protected, use `prod` for production releases
+
+## ⚡ Quick Commands
+
+### 🎯 Create Release
+```bash
+# Create release on current branch
+npm run release:real
+
+# Quick production release
+npm run release:prod  # switches to prod and releases
+```
+
+### 🏗️ Build Commands
+```bash
+npm run build:production  # Production build
+npm run build:stage      # Stage build  
+npm run build:sandbox    # Sandbox build
+npm run build:all        # Build all environments
+```
+
+### 📊 Information
+```bash
+npm run version:check    # Show current version
+npm run env:check       # Show environment info
+git tag --list          # List all releases
+```
+
+## 🔄 Standard Workflow
+
+### 1. Sandbox Release
+```bash
+git checkout sandbox
+# Make changes with conventional commits
+npm run release:real
+# Creates: v1.0.0-sandbox.X
+```
+
+### 2. Stage Release  
+```bash
+git checkout stage
+git merge sandbox
+npm run release:real
+# Creates: v1.0.0-stage.X
+```
+
+### 3. Production Release
+```bash
+git checkout prod
+git merge stage  
+npm run release:real
+# Creates: v1.0.1 (production version!)
+```
+
+## 🌍 Environments
+
+| Branch | Environment | Version Format | API |
+|--------|-------------|----------------|-----|
+| prod | Production | `v1.0.1` | api.saafe.in |
+| stage | Stage | `v1.0.0-stage.1` | stage-api.saafe.in |
+| sandbox | Sandbox | `v1.0.0-sandbox.1` | sandbox-api.saafe.in |
+
+## 📝 Commit Types
+- `feat:` → Minor version bump
+- `fix:` → Patch version bump  
+- `BREAKING CHANGE:` → Major version bump
+
+## 🆘 Emergency
+- **Hotfix**: Create on `prod` branch, then merge back to `stage` and `sandbox`
+- **Debug**: Use `npm run release:dry` to test releases
+
+## 🚨 Common Issues
+
+**Release in dry-run mode:**
+```bash
+npm run release:real  # Use this instead of npm run release
+```
+
+**No version bump on prerelease:**
+- This is expected behavior
+- Main version only bumps on `prod` branch
+
+**Environment variables not loading:**
+```bash
+npm run env:check  # Verify environment detection
+npm run env:list   # Check .env files exist
+```
+
+📖 **Full Guide**: `docs/RELEASE_GUIDE.md` 

package/RELEASE_NOTES.md

@@ -0,0 +1,120 @@
+# Release Notes
+
+## Version 1.0.2 - Enhanced Error Handling & Parent Communication
+
+### 🚀 New Features
+
+#### Comprehensive Error Callback System
+- **Real-time Error Reporting**: Implemented comprehensive error callback system that automatically notifies parent applications of any errors
+- **Structured Error Data**: All error callbacks include detailed context including error type, status codes, stack traces, and consent flow information
+- **Global Error Boundary**: Added React Error Boundary component to catch unhandled errors and ensure parent applications are always notified
+
+#### Enhanced Parent Window Communication
+- **Detailed Success Callbacks**: Success page now sends comprehensive data including user ratings, consent handles, and redirect information
+- **Rich Rejection Callbacks**: Rejection page provides detailed feedback including specific FIP rejection reasons and user feedback
+- **Consistent Message Format**: All parent communications follow a standardized structure with type, status, and contextual data
+
+#### Improved User Experience
+- **Cancel Functionality**: Users can now deselect all selected accounts by clicking the cancel button in account selection
+- **Better Error Recovery**: Application gracefully handles errors while maintaining communication with parent applications
+
+### 📊 Error Callback Data Structure
+
+#### Comprehensive Error Information
+All error callbacks include the following structured data:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | string | Always 'error' for error callbacks |
+| `status` | string | Always 'error' for error callbacks |
+| `flowCompleted` | boolean | Indicates if the consent flow was completed |
+| `errorMessage` | string | Human-readable error description |
+| `errorType` | string | Categorized error type (api, auth, network, validation, unknown) |
+| `errorCode` | string | API error code if available |
+| `statusCode` | number | HTTP status code for API errors |
+| `timestamp` | string | ISO timestamp of when error occurred |
+| `userAgent` | string | Browser/device information |
+| `url` | string | Current page URL where error occurred |
+| `stack` | string | Error stack trace for debugging |
+| `consentHandle` | string | Consent tracking identifier |
+| `redirectUrl` | string | Intended redirect URL if available |
+
+#### Enhanced Success/Rejection Callbacks
+- **Success Callbacks**: Include user ratings, consent handles, redirect URLs, and timestamps
+- **Rejection Callbacks**: Include rejection reasons, affected FIPs, user feedback, and detailed context
+- **Consistent Format**: All callbacks follow the same structured approach for easy parsing
+
+### 🔧 Technical Improvements
+
+#### New Components & Utilities
+- **Error Callback Utility**: Created `src/utils/error-callback.ts` with comprehensive error handling functions
+- **Error Boundary Component**: Implemented `src/components/ErrorBoundary.tsx` for global error catching
+- **Enhanced State Management**: Improved account selection state management with proper cancel functionality
+
+#### Implementation Details
+- **Error Handling Integration**: Added error callbacks to consent flow, login, and account discovery pages
+- **PostMessage API**: Standardized parent window communication with structured message formats
+- **Type Safety**: Proper TypeScript interfaces for all callback data structures
+- **Non-blocking Design**: Errors don't interrupt user flow, just notify parent applications
+
+### 🔄 Migration Guide
+
+#### For Parent Applications
+Update your message event listeners to handle the new comprehensive callback data:
+
+**Error Callback Example:**
+```javascript
+window.addEventListener('message', (event) => {
+  if (event.data.type === 'error') {
+    const { errorMessage, errorType, statusCode, consentHandle } = event.data;
+    // Handle error with detailed context
+    console.error('Consent flow error:', event.data);
+  }
+});
+```
+
+**Enhanced Success/Rejection Callbacks:**
+```javascript
+window.addEventListener('message', (event) => {
+  if (event.data.type === 'AA') {
+    if (event.data.status === 'success') {
+      // New fields: userRating, consentHandle, redirectUrl, timestamp
+      const { userRating, consentHandle } = event.data;
+    } else if (event.data.status === 'rejected') {
+      // New fields: rejectionReason, rejectedByFips, userFeedback, customFeedback
+      const { rejectedByFips, userFeedback } = event.data;
+    }
+  }
+});
+```
+
+#### Breaking Changes
+- Rejected callback status changed from `'failed'` to `'rejected'` for consistency
+- All callbacks now include additional context fields (backward compatible)
+
+### 📈 Impact
+
+#### For Parent Applications
+- **Better Error Visibility**: Real-time notification of all errors with detailed context for faster debugging
+- **Enhanced Analytics**: Rich callback data enables better user journey analysis and conversion tracking
+- **Improved Support**: Detailed error information helps customer support teams resolve issues quickly
+
+#### For End Users
+- **Seamless Experience**: Error handling doesn't interrupt user flow while ensuring proper error reporting
+- **Better Functionality**: Cancel button now properly clears selections for improved usability
+- **Reliable Communication**: Consistent message format ensures parent applications receive proper notifications
+
+#### For Development Teams
+- **Comprehensive Error Handling**: Centralized error callback system reduces boilerplate code
+- **Better Debugging**: Detailed error context including stack traces and environment information
+- **Type Safety**: Proper TypeScript interfaces for all callback structures
+
+### 🐛 Bug Fixes
+- Fixed account selection cancel functionality to properly clear all selected items
+- Improved error handling consistency across all pages
+- Enhanced TypeScript type safety for callback data structures
+
+---
+
+**Full Changelog**: Compare changes since last release
+**Documentation**: Updated tracking guidelines in developer documentation 

package/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/docs/DEPLOYMENT_WORKFLOW.md

@@ -0,0 +1,262 @@
+# 🚀 Deployment Workflow Guide
+
+## 🎯 Overview
+
+This guide explains the **conflict-free deployment workflow** for multiple environments without semantic release conflicts.
+
+## 🏗️ Branch Strategy
+
+```
+feature/branch → sandbox → stage → prod
+                    ↓       ↓       ↓
+                  Testing   QA   RELEASE
+```
+
+**Key Principle**: Only `prod` branch creates actual releases. Other branches are deployment targets.
+
+## ✅ Correct Workflow
+
+### **Step 1: Feature Development**
+
+```bash
+# Create feature branch
+git checkout -b feature/user-auth
+git add .
+git commit -m "feat: implement user authentication"
+git push origin feature/user-auth
+```
+
+### **Step 2: Deploy to Sandbox**
+
+```bash
+# Merge to sandbox (NO RELEASE)
+git checkout sandbox
+git merge feature/user-auth
+npm run build:sandbox
+# Deploy sandbox build to sandbox environment
+```
+
+### **Step 3: Deploy to Stage**
+
+```bash  
+# Merge to stage (NO RELEASE)
+git checkout stage
+git merge sandbox  # or git merge feature/user-auth
+npm run build:stage
+# Deploy stage build to stage environment
+```
+
+### **Step 4: Deploy to Production**
+
+```bash
+# Merge to prod and RELEASE
+git checkout prod
+git merge stage  # or git merge feature/user-auth
+npm run release:real  # Creates v1.0.1
+npm run build:production
+# Deploy production build to production environment
+```
+
+## 🔄 Daily Development Cycle
+
+### **Multiple Features**
+
+```bash
+# Feature A
+git checkout -b feature/dashboard
+git commit -m "feat: add user dashboard"
+git checkout sandbox
+git merge feature/dashboard
+npm run build:sandbox
+
+# Feature B  
+git checkout -b feature/notifications
+git commit -m "feat: add push notifications"
+git checkout sandbox
+git merge feature/notifications
+npm run build:sandbox
+
+# Deploy both to stage
+git checkout stage
+git merge sandbox
+npm run build:stage
+
+# Deploy both to production
+git checkout prod
+git merge stage
+npm run release:real  # Creates v1.1.0 (minor bump for 2 features)
+```
+
+### **Hotfix Process**
+
+```bash
+# Critical bug fix
+git checkout prod
+git checkout -b hotfix/security-fix
+git commit -m "fix: resolve critical security vulnerability"
+
+# Deploy directly to prod
+git checkout prod
+git merge hotfix/security-fix
+npm run release:real  # Creates v1.0.1 (patch)
+npm run build:production
+
+# Merge back to other branches
+git checkout stage
+git merge prod
+git checkout sandbox  
+git merge prod
+```
+
+## 📋 Branch Responsibilities
+
+| Branch | Purpose | Release | Build Command | Deploy To |
+|--------|---------|---------|---------------|-----------|
+| **sandbox** | Integration testing | ❌ No | `npm run build:sandbox` | Sandbox servers |
+| **stage** | QA testing | ❌ No | `npm run build:stage` | Stage servers |
+| **prod** | Production releases | ✅ Yes | `npm run build:production` | Production servers |
+
+## 🚫 What NOT to Do
+
+```bash
+# ❌ DON'T run releases on sandbox/stage
+git checkout sandbox
+npm run release:real  # This causes conflicts!
+
+git checkout stage  
+npm run release:real  # This causes conflicts!
+
+# ❌ DON'T merge in wrong direction
+git checkout sandbox
+git merge stage  # Wrong direction!
+```
+
+## ✅ Conflict Resolution
+
+If you accidentally created conflicting releases, here's how to fix:
+
+### **Reset Branch Strategy**
+
+```bash
+# 1. Create clean branches from prod
+git checkout prod
+git checkout -b sandbox-clean
+git checkout -b stage-clean
+
+# 2. Replace old branches
+git branch -D sandbox
+git branch -D stage  
+git branch -m sandbox-clean sandbox
+git branch -m stage-clean stage
+
+# 3. Push new branches
+git push -f origin sandbox
+git push -f origin stage
+```
+
+## 🎯 Version Strategy
+
+### **Current Setup (After Fix)**
+
+- **Production**: `v1.0.0`, `v1.0.1`, `v1.1.0`, `v2.0.0`
+- **Stage**: Same code as prod, no separate versions
+- **Sandbox**: Same code as stage, no separate versions
+
+### **Version Display**
+
+The `VersionDisplay` component automatically shows:
+- **Production**: `v1.0.1`
+- **Stage**: `v1.0.1 | STAGE` 
+- **Sandbox**: `v1.0.1 | SANDBOX`
+
+## 🛠️ Commands Reference
+
+### **Development Commands**
+
+```bash
+# Check current setup
+npm run version:check
+git branch -a
+git log --oneline -5
+
+# Build for environments
+npm run build:sandbox
+npm run build:stage  
+npm run build:production
+
+# Preview builds
+npm run preview:sandbox
+npm run preview:stage
+npm run preview:production
+```
+
+### **Release Commands**
+
+```bash
+# Only run on prod branch
+git checkout prod
+npm run release:real
+
+# Test release (dry run)
+npm run release:dry
+```
+
+### **Environment Commands**
+
+```bash
+# Check environment config
+npm run env:check
+npm run env:list
+
+# Check build differences
+npm run build:stage -- --debug
+npm run build:production -- --debug
+```
+
+## 📊 Benefits of This Workflow
+
+### **✅ Advantages**
+
+- ✅ **No merge conflicts** in package.json/CHANGELOG.md
+- ✅ **Clean git history** with linear releases
+- ✅ **Easier rollbacks** with single version source
+- ✅ **Clear environment separation**
+- ✅ **Simplified deployment pipeline**
+
+### **📈 Before vs After**
+
+#### **Before (Problematic)**
+```
+sandbox: v1.0.0-sandbox.1 → v1.0.0-sandbox.2 → v1.0.0-sandbox.3
+stage:   v1.0.0-stage.1   → v1.0.0-stage.2   → CONFLICTS!
+prod:    v1.0.0           → v1.0.1            → CONFLICTS!
+```
+
+#### **After (Clean)**
+```
+sandbox: code deployment only (no versions)
+stage:   code deployment only (no versions)  
+prod:    v1.0.0 → v1.0.1 → v1.1.0 → v2.0.0 (clean releases)
+```
+
+## 🎓 Training Checklist
+
+- [ ] Understand branch flow: feature → sandbox → stage → prod
+- [ ] Only release from `prod` branch
+- [ ] Use `build:environment` commands for deployment
+- [ ] Merge in correct direction (forward only)
+- [ ] Test workflow with `npm run release:dry`
+- [ ] Know how to resolve conflicts if they occur
+
+## 📞 Support
+
+If you encounter issues:
+
+1. **Check branch**: `git branch` (should be on `prod` for releases)
+2. **Check conflicts**: `git status` (resolve before releasing)
+3. **Test first**: `npm run release:dry`
+4. **Check docs**: This guide and `docs/RELEASE_GUIDE.md`
+
+---
+
+**�� Happy Deploying!**