@abaxx_tech/v-integration-react 1.2.0-dev.7 → 1.2.0-dev.8

package/README.md

@@ -257,21 +257,21 @@ Email input authentication component only. Provides a standalone email/Abaxx ID
 
 ## Error Handling
 
+The library provides comprehensive error handling through two mechanisms: React Error Boundary for component errors and `authError` in the context for authentication flow errors.
+
 ### React Error Boundary
 
 All authentication components (`VerifierAuth`, `VerifierAuthQr`, and `VerifierAuthEmail`) are automatically wrapped with an `AuthErrorBoundary` component that catches React errors during rendering or in lifecycle methods.
 
 #### Features:
 - **Automatic Error Catching**: Catches errors that occur in the component tree during rendering
-- **User-Friendly Error UI**: Displays a centered error message with a dark overlay background
-- **Error Recovery**: Provides a "Try Again" button to reset the error state and retry
+- **User-Friendly Error UI**: Displays a centered error message with a fixed overlay background
 - **Error Logging**: Automatically logs errors to the console for debugging
 
 #### Error Display:
-When an error occurs, users will see:
+When a React error occurs, users will see:
 - A centered error message: "Something went wrong"
-- A descriptive message: "An unexpected error occurred during authentication. Please try again."
-- A "Try Again" button to reset the error state
+- A descriptive message: "An unexpected error occurred. Please try again later."
 
 The error boundary uses a fixed position overlay that covers the entire viewport, ensuring the error message is always visible and centered both vertically and horizontally.
 
@@ -287,7 +287,330 @@ const LoginPage = () => {
 };
 ```
 
-**Note**: The error boundary only catches errors in React components. For network errors or API errors, use the `authError` property from `VContext` to handle them in your application logic.
+**Note**: The error boundary only catches errors in React components. For network errors, API errors, or authentication flow errors, use the `authError` property from `VContext` to handle them in your application logic.
+
+### Authentication Error States (`authError`)
+
+The `authError` property in `VContext` contains error messages for authentication flow failures. All error states are documented below with their causes, recovery strategies, and handling examples.
+
+#### Error Categories
+
+##### 1. Input Validation Errors
+
+These errors occur when user input is invalid or missing.
+
+| Error Message | Cause | When It Occurs |
+|--------------|-------|----------------|
+| `"Invalid login. Email or Abaxx ID is required."` | Empty alias field | User attempts to authenticate without entering email/Abaxx ID |
+| `"Invalid login. Please use your existing Email or Abaxx ID."` | Invalid or non-existent alias | Server responds with "Unable to request auth." |
+
+**Recovery Strategy:**
+- Clear the error message
+- Allow user to re-enter their email/Abaxx ID
+- Provide helpful validation feedback before submission
+- No need to reset the entire authentication state
+
+**Example:**
+```tsx
+import { useContext, useEffect } from 'react';
+import { VContext } from "@abaxx_tech/v-integration-react";
+
+const LoginForm = () => {
+  const { authError, setAuthError } = useContext(VContext);
+  
+  useEffect(() => {
+    if (authError?.includes("Invalid login")) {
+      // Clear error when user starts typing
+      const timer = setTimeout(() => setAuthError(null), 5000);
+      return () => clearTimeout(timer);
+    }
+  }, [authError, setAuthError]);
+  
+  return (
+    <div>
+      {authError && (
+        <div className="error-message">
+          {authError}
+          <button onClick={() => setAuthError(null)}>Dismiss</button>
+        </div>
+      )}
+      {/* Your login form */}
+    </div>
+  );
+};
+```
+
+##### 2. Authentication Request Errors
+
+These errors occur when the authentication request to the server fails.
+
+| Error Message | Cause | When It Occurs |
+|--------------|-------|----------------|
+| `"Auth request failed: ${message}"` | Server rejected the request | HTTP response is not OK or `data.ok === false` |
+| `"Auth request failed: ${error}"` | Network or fetch exception | Exception thrown during fetch request |
+| `"Something went wrong. Please try again later."` | Unexpected error | Generic catch-all error in authentication flow |
+
+**Recovery Strategy:**
+- For network errors: Retry the request after a short delay
+- For server errors: Check API configuration and server status
+- Provide a "Retry" button to allow manual retry
+- Consider resetting authentication state if multiple retries fail
+
+**Example:**
+```tsx
+import { useContext, useState } from 'react';
+import { VContext, useVerifierReset } from "@abaxx_tech/v-integration-react";
+
+const ErrorHandler = () => {
+  const { authError, setAuthError } = useContext(VContext);
+  const resetState = useVerifierReset();
+  const [retryCount, setRetryCount] = useState(0);
+  
+  const handleRetry = () => {
+    setAuthError(null);
+    setRetryCount(prev => prev + 1);
+    // Trigger re-authentication
+    window.location.reload(); // Or use your retry logic
+  };
+  
+  const handleReset = () => {
+    resetState();
+    setRetryCount(0);
+  };
+  
+  if (!authError) return null;
+  
+  const isNetworkError = authError.includes("Auth request failed");
+  const isGenericError = authError.includes("Something went wrong");
+  
+  return (
+    <div className="error-container">
+      <div className="error-message">{authError}</div>
+      {isNetworkError && retryCount < 3 && (
+        <button onClick={handleRetry}>
+          Retry ({retryCount}/3)
+        </button>
+      )}
+      <button onClick={handleReset}>
+        Start Over
+      </button>
+    </div>
+  );
+};
+```
+
+##### 3. SSE Connection Errors
+
+These errors occur when the Server-Sent Events (SSE) connection fails or is interrupted.
+
+| Error Message | Cause | When It Occurs |
+|--------------|-------|----------------|
+| `"Connection lost. Reconnecting... (attempt X/3)"` | SSE connection interrupted | Connection lost during authentication flow (automatic retry in progress) |
+| `"Unable to establish connection. Please check your network and try again."` | Maximum retries exceeded | SSE connection failed after 3 retry attempts |
+| `"Connection setup failed: ${error}"` | SSE initialization failure | Failed to create EventSource connection |
+
+**Recovery Strategy:**
+- For reconnection errors: Wait for automatic retry (library handles this)
+- For connection failures: Check network connectivity and API URL configuration
+- Provide user feedback about connection status
+- Allow manual retry by resetting state and restarting authentication
+- Consider implementing exponential backoff for manual retries
+
+**Example:**
+```tsx
+import { useContext, useEffect } from 'react';
+import { VContext, useVerifierReset } from "@abaxx_tech/v-integration-react";
+
+const ConnectionStatus = () => {
+  const { authError, setAuthError } = useContext(VContext);
+  const resetState = useVerifierReset();
+  
+  useEffect(() => {
+    if (authError?.includes("Connection lost")) {
+      // Connection is being retried automatically
+      // Just show status, no action needed
+      return;
+    }
+    
+    if (authError?.includes("Unable to establish connection")) {
+      // Maximum retries exceeded
+      // User should manually retry
+    }
+  }, [authError]);
+  
+  const handleManualRetry = () => {
+    resetState();
+    setAuthError(null);
+    // State reset will trigger new SSE connection
+  };
+  
+  if (!authError) return null;
+  
+  const isReconnecting = authError.includes("Reconnecting");
+  const isConnectionFailed = authError.includes("Unable to establish");
+  
+  return (
+    <div className="connection-status">
+      {isReconnecting && (
+        <div className="reconnecting">
+          <Spinner />
+          <span>{authError}</span>
+        </div>
+      )}
+      {isConnectionFailed && (
+        <div className="connection-failed">
+          <p>{authError}</p>
+          <button onClick={handleManualRetry}>
+            Try Again
+          </button>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+##### 4. Token Exchange Errors
+
+These errors occur when exchanging the authorization code for an access token fails.
+
+| Error Message | Cause | When It Occurs |
+|--------------|-------|----------------|
+| `"Failed to obtain auth token: ${error}"` | Token exchange failed | Server rejected token exchange request or network error occurred |
+
+**Recovery Strategy:**
+- This is a critical error - authentication cannot complete
+- Reset authentication state to start fresh
+- Check server logs and API configuration
+- Verify PKCE code verifier is correctly generated
+- Consider logging this error for debugging
+
+**Example:**
+```tsx
+import { useContext, useEffect } from 'react';
+import { VContext, useVerifierReset } from "@abaxx_tech/v-integration-react";
+
+const TokenErrorHandler = () => {
+  const { authError, setAuthError } = useContext(VContext);
+  const resetState = useVerifierReset();
+  
+  useEffect(() => {
+    if (authError?.includes("Failed to obtain auth token")) {
+      // Log critical error for debugging
+      console.error("Token exchange failed:", authError);
+      
+      // Optionally send to error tracking service
+      // errorTrackingService.log(authError);
+    }
+  }, [authError]);
+  
+  const handleRecovery = () => {
+    resetState();
+    setAuthError(null);
+    // User will need to restart authentication flow
+  };
+  
+  if (!authError?.includes("Failed to obtain auth token")) {
+    return null;
+  }
+  
+  return (
+    <div className="critical-error">
+      <h3>Authentication Failed</h3>
+      <p>{authError}</p>
+      <p>Please try logging in again.</p>
+      <button onClick={handleRecovery}>
+        Start Over
+      </button>
+    </div>
+  );
+};
+```
+
+### Complete Error Handling Example
+
+Here's a comprehensive example showing how to handle all error types in a consumer application:
+
+```tsx
+import { useContext, useEffect, useState } from 'react';
+import { VContext, useVerifierReset } from "@abaxx_tech/v-integration-react";
+
+const AuthErrorHandler = () => {
+  const { authError, setAuthError, isAuthenticating, token } = useContext(VContext);
+  const resetState = useVerifierReset();
+  const [errorType, setErrorType] = useState<'validation' | 'network' | 'connection' | 'token' | null>(null);
+  
+  // Categorize error type
+  useEffect(() => {
+    if (!authError) {
+      setErrorType(null);
+      return;
+    }
+    
+    if (authError.includes("Invalid login")) {
+      setErrorType('validation');
+    } else if (authError.includes("Auth request failed") || authError.includes("Something went wrong")) {
+      setErrorType('network');
+    } else if (authError.includes("Connection") || authError.includes("Reconnecting")) {
+      setErrorType('connection');
+    } else if (authError.includes("Failed to obtain auth token")) {
+      setErrorType('token');
+    }
+  }, [authError]);
+  
+  // Auto-dismiss validation errors after user interaction
+  useEffect(() => {
+    if (errorType === 'validation') {
+      const timer = setTimeout(() => setAuthError(null), 5000);
+      return () => clearTimeout(timer);
+    }
+  }, [errorType, setAuthError]);
+  
+  const handleRetry = () => {
+    setAuthError(null);
+    // Trigger retry logic based on error type
+    if (errorType === 'connection' || errorType === 'token') {
+      resetState();
+    }
+  };
+  
+  const handleDismiss = () => {
+    setAuthError(null);
+  };
+  
+  if (!authError || !errorType) return null;
+  
+  return (
+    <div className={`error-banner error-${errorType}`}>
+      <div className="error-content">
+        <span className="error-icon">⚠️</span>
+        <span className="error-message">{authError}</span>
+      </div>
+      <div className="error-actions">
+        {errorType === 'validation' && (
+          <button onClick={handleDismiss}>Dismiss</button>
+        )}
+        {(errorType === 'network' || errorType === 'connection') && (
+          <button onClick={handleRetry}>Retry</button>
+        )}
+        {errorType === 'token' && (
+          <button onClick={() => resetState()}>Start Over</button>
+        )}
+      </div>
+    </div>
+  );
+};
+
+// Usage in your app
+const App = () => {
+  return (
+    <VerifierProvider apiUrl={API_URL} clientId={CLIENT_ID}>
+      <AuthErrorHandler />
+      <VerifierAuth title="My App" />
+    </VerifierProvider>
+  );
+};
+```
 
 ## Context API
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abaxx_tech/v-integration-react",
-  "version": "1.2.0-dev.7",
+  "version": "1.2.0-dev.8",
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },