saafe-redirection-flow 2.0.0

package/docs/local-release-workflow.md

@@ -0,0 +1,234 @@
+# Local Release Workflow Guide
+
+This guide explains how to use the semantic release setup for local development and deployment without GitHub Actions.
+
+## Quick Start
+
+### 1. Check Current Status
+```bash
+# Check current version
+npm run version:check
+
+# List environment files
+npm run env:list
+
+# Check environment variables
+npm run env:check
+```
+
+### 2. Test Release (Dry Run)
+```bash
+# Test what version would be released
+npm run release:dry
+```
+
+### 3. Actual Release
+```bash
+# Create actual release
+npm run release
+```
+
+## Environment-Based Builds
+
+### Build for Specific Environments
+```bash
+# Build for production
+npm run build:production
+
+# Build for staging
+npm run build:stage
+
+# Build for sandbox
+npm run build:sandbox
+
+# Build for all environments
+npm run build:all
+```
+
+### Preview Builds
+```bash
+# Preview production build
+npm run preview:production
+
+# Preview stage build
+npm run preview:stage
+
+# Preview sandbox build
+npm run preview:sandbox
+```
+
+## Commit Convention
+
+Use conventional commits for automatic version bumping:
+
+### Patch Releases (1.0.0 → 1.0.1)
+```bash
+git commit -m "fix: resolve login issue"
+git commit -m "fix(auth): handle token expiration"
+```
+
+### Minor Releases (1.0.0 → 1.1.0)
+```bash
+git commit -m "feat: add new authentication flow"
+git commit -m "feat(dashboard): implement account selection"
+```
+
+### Major Releases (1.0.0 → 2.0.0)
+```bash
+git commit -m "feat!: redesign authentication system"
+git commit -m "feat(api)!: change response format"
+```
+
+### Other Commit Types (No Release)
+```bash
+git commit -m "docs: update readme"
+git commit -m "refactor: improve code structure"
+git commit -m "style: fix formatting"
+git commit -m "test: add unit tests"
+git commit -m "chore: update dependencies"
+```
+
+## Branch-Based Versioning
+
+### Main Branch (Production)
+- Creates stable releases: `1.0.0`, `1.1.0`, `2.0.0`
+- Used for production deployments
+
+### Stage Branch
+- Creates pre-releases: `1.0.0-stage.1`, `1.0.0-stage.2`
+- Used for staging environment testing
+
+### Sandbox Branch
+- Creates pre-releases: `1.0.0-sandbox.1`, `1.0.0-sandbox.2`
+- Used for sandbox environment testing
+
+### Develop Branch
+- Creates pre-releases: `1.0.0-dev.1`, `1.0.0-dev.2`
+- Used for development environment testing
+
+## Release Process
+
+### 1. Development Workflow
+```bash
+# Switch to appropriate branch
+git checkout sandbox
+
+# Make changes with conventional commits
+git add .
+git commit -m "feat: add new feature"
+
+# Test release
+npm run release:dry
+
+# Create release
+npm run release
+```
+
+### 2. Build and Deploy
+```bash
+# Build for the environment
+npm run build:sandbox
+
+# Deploy the dist/ folder to your hosting service
+```
+
+### 3. Promotion Workflow
+```bash
+# Promote sandbox to stage
+git checkout stage
+git merge sandbox
+npm run release
+
+# Build for stage
+npm run build:stage
+
+# Promote stage to production
+git checkout main
+git merge stage
+npm run release
+
+# Build for production
+npm run build:production
+```
+
+## What Semantic Release Does
+
+### Automatic Actions:
+1. **Analyzes commits** since last release
+2. **Determines version bump** based on commit types
+3. **Generates release notes** from commit messages
+4. **Updates package.json** version
+5. **Updates CHANGELOG.md** with new release notes
+6. **Creates git tag** for the new version
+7. **Commits changes** back to repository
+
+### Generated Files:
+- `CHANGELOG.md` - Automatically updated with release notes
+- `package.json` - Version field updated
+- `package-lock.json` - Version field updated
+
+## Environment Configuration
+
+### Environment Variables Available:
+- `VITE_API_BASE_URL` - API endpoint for current environment
+- `VITE_IMAGE_BASE_URL` - Image CDN URL
+- `VITE_APP_NAME` - Application name
+- `VITE_PUBLIC_POSTHOG_KEY` - Analytics key
+- `VITE_SESSION_TIMEOUT` - Session timeout duration
+
+### Environment Files:
+- `.env.production` - Production settings
+- `.env.stage` - Stage settings
+- `.env.sandbox` - Sandbox settings
+- `.env.development` - Development settings
+
+## Troubleshooting
+
+### No Release Created
+- Check if commits follow conventional format
+- Ensure you're on the correct branch
+- Run `npm run release:dry` to see what would happen
+
+### Build Failures
+- Check TypeScript errors: `npm run lint`
+- Verify environment variables are set
+- Ensure all dependencies are installed: `npm install`
+
+### Version Conflicts
+- Always pull latest changes before releasing
+- Use `git status` to check for uncommitted changes
+- Resolve any merge conflicts before releasing
+
+## Useful Commands
+
+```bash
+# Check what would be released
+npm run release:dry
+
+# Check current version
+npm run version:check
+
+# List all environment files
+npm run env:list
+
+# Check environment variables
+npm run env:check
+
+# Build all environments
+npm run build:all
+
+# Run development server
+npm run dev
+
+# Preview production build locally
+npm run preview:production
+```
+
+## Best Practices
+
+1. **Always test with dry run** before actual release
+2. **Use descriptive commit messages** for better release notes
+3. **Build and test** before releasing
+4. **Use branch-specific environments** for testing
+5. **Keep environment files** updated with correct settings
+6. **Review generated CHANGELOG.md** after releases 

package/docs/routes.md

@@ -0,0 +1,118 @@
+# SAAFE Routes Documentation
+
+This document provides information about the routes and pages available in the SAAFE Redirection Flow application.
+
+## Route Structure
+
+The application uses React Router v7 for route management. The main route structure is defined in `App.tsx`.
+
+## Available Routes
+
+### Public Routes
+
+| Route | Component | Description |
+|-------|-----------|-------------|
+| `/` | Redirect to `/login` | Redirects to the login page |
+| `/login` | `Login` | Initial entry point for user authentication |
+
+### Protected Routes
+
+These routes require authentication via the `AuthGuard` component:
+
+| Route | Component | Description |
+|-------|-----------|-------------|
+| `/link-accounts` | Redirect to `/link-accounts/banks` | Default redirect for account linking |
+| `/link-accounts/discovery` | `Discover` | Account discovery page |
+| `/link-accounts/proceed` | `Discover` | Proceed with discovered accounts |
+| `/link-accounts/link` | `Discover` | Link selected accounts |
+| `/link-accounts/discover-account` | `Discover` | Discover specific account details |
+| `/link-accounts/old-user` | `OldUser` | Page for returning users with existing linked accounts |
+| `/link-accounts/:category` | `Discover` | Category-specific financial institution listing |
+| `/review` | `ReviewConsent` | Review and confirm data sharing consent |
+| `/success` | `Success` | Successful account linking confirmation |
+| `/rejected` | `Rejected` | Consent rejection confirmation |
+
+## Page Components
+
+### Login Page
+
+**Path:** `/login`  
+**Component:** `Login.tsx`
+
+The initial entry point for users. This page:
+- Decodes and validates URL parameters
+- Authenticates the user with their financial institution
+- Supports OTP verification if enabled
+- Adapts UI based on the specified platform
+- Handles theme preferences
+
+### Discover Page
+
+**Path:** `/link-accounts/discovery` (and related paths)  
+**Component:** `Discover.tsx`
+
+Multi-purpose page that handles various aspects of account discovery:
+- Lists available financial institutions by category
+- Discovers accounts associated with a user
+- Allows selection of accounts to link
+- Shows detailed account information
+
+### ReviewConsent Page
+
+**Path:** `/review`  
+**Component:** `ReviewConsent.tsx`
+
+Page for reviewing and providing consent for data sharing:
+- Displays detailed information about what data will be shared
+- Shows the third-party requestor details
+- Explains the purpose of data sharing
+- Provides clear accept/reject options
+
+### Success Page
+
+**Path:** `/success`  
+**Component:** `Success.tsx`
+
+Confirmation page shown after successful account linking:
+- Displays success message and next steps
+- Provides options to return to the originating application
+- Shows linked account details (if configured)
+
+### Rejected Page
+
+**Path:** `/rejected`  
+**Component:** `Rejected.tsx`
+
+Confirmation page shown after rejecting consent:
+- Confirms the user's rejection of data sharing
+- Explains implications of rejection
+- Provides options to return to the originating application
+
+### Old User Page
+
+**Path:** `/link-accounts/old-user`  
+**Component:** `OldUser.tsx`
+
+Special page for returning users with previously linked accounts:
+- Shows existing linked accounts
+- Provides options to add more accounts
+- Allows unlinking of existing accounts
+
+## Navigation Flow
+
+The typical user journey follows this flow:
+
+1. User arrives at `/login` with required URL parameters
+2. After successful authentication, user is directed to `/link-accounts/discovery`
+3. User selects accounts to link and proceeds to `/review`
+4. User reviews consent details and either:
+   - Accepts, leading to `/success`
+   - Rejects, leading to `/rejected`
+
+## Route Protection
+
+All routes except `/login` are protected by the `AuthGuard` component, which:
+- Verifies that the user is authenticated
+- Redirects unauthenticated users to the login page
+- Maintains session state across page navigation
+- Handles session timeouts 

package/docs/sdk-integration.md

@@ -0,0 +1,325 @@
+# SAAFE SDK Integration Guide
+
+This document provides detailed information on how to integrate the SAAFE Redirection Flow into your applications via the SDK.
+
+## Overview
+
+The SAAFE Redirection Flow is designed to be embedded within mobile and web applications using a WebView (iOS, Android) or iframe (Web) approach. This allows your users to securely link their financial accounts without leaving your application.
+
+## Integration Methods
+
+### Mobile SDK Integration
+
+#### iOS (Swift) WebView Integration
+
+```swift
+import UIKit
+import WebKit
+
+class SAFERedirectionViewController: UIViewController, WKNavigationDelegate {
+    
+    private var webView: WKWebView!
+    private let financialInstitutionId: String
+    private let encryptedRequest: String
+    private let requestDate: String
+    
+    init(financialInstitutionId: String, encryptedRequest: String, requestDate: String) {
+        self.financialInstitutionId = financialInstitutionId
+        self.encryptedRequest = encryptedRequest
+        self.requestDate = requestDate
+        super.init(nibName: nil, bundle: nil)
+    }
+    
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        
+        setupWebView()
+        loadSAAFERedirection()
+    }
+    
+    private func setupWebView() {
+        let configuration = WKWebViewConfiguration()
+        webView = WKWebView(frame: view.bounds, configuration: configuration)
+        webView.navigationDelegate = self
+        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        view.addSubview(webView)
+    }
+    
+    private func loadSAAFERedirection() {
+        let baseUrl = "https://saafe-app.com/login"
+        var urlComponents = URLComponents(string: baseUrl)!
+        
+        urlComponents.queryItems = [
+            URLQueryItem(name: "fi", value: financialInstitutionId),
+            URLQueryItem(name: "ecreq", value: encryptedRequest),
+            URLQueryItem(name: "reqdate", value: requestDate),
+            URLQueryItem(name: "platform", value: "ios"),
+            URLQueryItem(name: "theme", value: "system")
+        ]
+        
+        if let url = urlComponents.url {
+            let request = URLRequest(url: url)
+            webView.load(request)
+        }
+    }
+    
+    // MARK: - WKNavigationDelegate
+    
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        // Handle successful page load
+    }
+    
+    func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
+        // Intercept navigation if needed
+        
+        // Example: Detect success/rejection callbacks
+        if let url = navigationAction.request.url?.absoluteString {
+            if url.contains("/success") {
+                // Handle success scenario
+                self.dismiss(animated: true, completion: nil)
+                decisionHandler(.cancel)
+                return
+            } else if url.contains("/rejected") {
+                // Handle rejection scenario
+                self.dismiss(animated: true, completion: nil)
+                decisionHandler(.cancel)
+                return
+            }
+        }
+        
+        decisionHandler(.allow)
+    }
+}
+```
+
+#### Android (Kotlin) WebView Integration
+
+```kotlin
+import android.os.Bundle
+import android.webkit.WebView
+import android.webkit.WebViewClient
+import androidx.appcompat.app.AppCompatActivity
+import java.net.URLEncoder
+
+class SAFERedirectionActivity : AppCompatActivity() {
+    
+    private lateinit var webView: WebView
+    
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        
+        // Get parameters from intent
+        val financialInstitutionId = intent.getStringExtra("fi") ?: ""
+        val encryptedRequest = intent.getStringExtra("ecreq") ?: ""
+        val requestDate = intent.getStringExtra("reqdate") ?: ""
+        
+        // Set up WebView
+        webView = WebView(this)
+        webView.settings.javaScriptEnabled = true
+        webView.settings.domStorageEnabled = true
+        
+        webView.webViewClient = object : WebViewClient() {
+            override fun shouldOverrideUrlLoading(view: WebView?, url: String?): Boolean {
+                // Detect success/rejection URLs
+                url?.let {
+                    when {
+                        it.contains("/success") -> {
+                            // Handle success
+                            finish()
+                            return true
+                        }
+                        it.contains("/rejected") -> {
+                            // Handle rejection
+                            finish()
+                            return true
+                        }
+                    }
+                }
+                return false
+            }
+        }
+        
+        setContentView(webView)
+        
+        // Load SAAFE Redirection Flow
+        val baseUrl = "https://saafe-app.com/login"
+        val urlParams = "?fi=$financialInstitutionId&ecreq=$encryptedRequest&reqdate=$requestDate&platform=android&theme=system"
+        webView.loadUrl(baseUrl + urlParams)
+    }
+    
+    override fun onBackPressed() {
+        if (webView.canGoBack()) {
+            webView.goBack()
+        } else {
+            // Show confirmation dialog before exiting
+            // This is important as closing mid-flow can cause issues
+            // Implementation of confirmation dialog omitted for brevity
+        }
+    }
+}
+```
+
+### Web Integration
+
+#### React Application Integration
+
+```tsx
+import React, { useEffect, useRef } from 'react';
+
+interface SAFERedirectionProps {
+  financialInstitutionId: string;
+  encryptedRequest: string;
+  requestDate: string;
+  onSuccess?: () => void;
+  onRejection?: () => void;
+  theme?: 'light' | 'dark' | 'system';
+}
+
+const SAFERedirection: React.FC<SAFERedirectionProps> = ({
+  financialInstitutionId,
+  encryptedRequest,
+  requestDate,
+  onSuccess,
+  onRejection,
+  theme = 'system'
+}) => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  
+  useEffect(() => {
+    const handleMessage = (event: MessageEvent) => {
+      // Verify origin for security
+      if (event.origin !== 'https://saafe-app.com') return;
+      
+      // Process messages from the iframe
+      if (event.data.type === 'saafe:success') {
+        onSuccess?.();
+      } else if (event.data.type === 'saafe:rejection') {
+        onRejection?.();
+      }
+    };
+    
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, [onSuccess, onRejection]);
+  
+  const safeUrl = `https://saafe-app.com/login?fi=${encodeURIComponent(financialInstitutionId)}&ecreq=${encodeURIComponent(encryptedRequest)}&reqdate=${encodeURIComponent(requestDate)}&platform=web&theme=${theme}`;
+  
+  return (
+    <iframe
+      ref={iframeRef}
+      src={safeUrl}
+      style={{ width: '100%', height: '600px', border: 'none' }}
+      title="SAAFE Account Linking"
+      allow="camera; microphone"
+    />
+  );
+};
+
+export default SAFERedirection;
+```
+
+## URL Parameters Reference
+
+| Parameter | Description | Valid Values | Required |
+|-----------|-------------|-------------|----------|
+| fi | Financial Institution ID | String | Yes |
+| ecreq | Encrypted Request | String | Yes |
+| reqdate | Request Date | String | Yes |
+| profile | User Profile | String | No |
+| platform | Client Platform | ios, android, react-native, flutter, web | No |
+| theme | Application Theme | light, dark, system | No |
+
+### Detailed Parameter Information
+
+#### Financial Institution ID (fi)
+
+Unique identifier for the financial institution being accessed. This is provided by the SAAFE platform.
+
+#### Encrypted Request (ecreq)
+
+A JWT-encoded request payload that contains:
+- User identification information
+- Request scope (what data is being requested)
+- Expiration time
+- Signature
+
+The encryption ensures that request parameters cannot be tampered with.
+
+#### Request Date (reqdate)
+
+ISO8601 formatted date-time string that indicates when the request was initiated. Used for security validation.
+
+#### Platform (platform)
+
+Identifies the client platform for optimized display and behavior:
+- **ios**: iOS-specific optimizations (status bar handling, iOS-style UI)
+- **android**: Android optimizations
+- **react-native**: React Native WebView optimizations
+- **flutter**: Flutter WebView optimizations
+- **web**: Standard web experience
+
+#### Theme (theme)
+
+Controls the visual theme:
+- **light**: Forces light theme
+- **dark**: Forces dark theme
+- **system**: Uses device theme preference (default)
+
+## Security Considerations
+
+### Cross-Origin Restrictions
+
+When embedding the SAAFE Redirection Flow in a web application via an iframe, be aware of potential cross-origin restrictions. The application handles document displays to avoid cross-origin issues.
+
+### Navigation Flow Protection
+
+The SAAFE Redirection Flow includes navigation protection to warn users before exiting a flow in progress. This helps prevent accidental cancellations.
+
+### Secure Communication
+
+For mobile WebViews, use the provided URL interception patterns to securely communicate the flow outcome back to your application.
+
+## Callback Handling
+
+### Success Callback
+
+When an account linking flow completes successfully, the application navigates to the `/success` route. For iframe integrations, a message is posted to the parent window. For WebViews, you can intercept this URL to handle success in your native application.
+
+### Rejection Callback
+
+If the user rejects the consent, the application navigates to the `/rejected` route. Similar to the success case, messages are posted for iframes and the URL can be intercepted in WebViews.
+
+## Styling and Customization
+
+### Custom Styling
+
+You can provide custom styling parameters via the URL:
+- Primary button color
+- Background colors
+- Font styles
+
+These are applied via CSS variables at runtime.
+
+## Testing
+
+To test your integration, you can use the following test credentials:
+
+- Financial Institution ID: `test_fi`
+- Encrypted Request: `test_encrypted_request`
+- Request Date: Current timestamp
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Blank Screen**: Ensure all required URL parameters are provided and correctly encoded.
+2. **Navigation Issues**: If the flow doesn't complete, check your URL interception logic in WebViews.
+3. **Cross-Origin Errors**: For web iframe integration, ensure your domain is whitelisted.
+
+### Support
+
+For further assistance, contact the SAAFE support team at support@saafe-platform.com.