@abaxx_tech/v-integration-react 1.2.0-dev.6 → 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/dist/v-integration-react.d.ts

@@ -1,33 +1,166 @@
 import { default as default_2 } from 'react';
 import { ReactNode } from 'react';
 
+/**
+ * Options for authentication request.
+ *
+ * @interface AuthOptions
+ * @property {string} alias - User's email or Abaxx ID
+ * @property {string} code_challenge - PKCE code challenge for secure authentication
+ * @property {string} request_id - Unique authentication request identifier
+ */
 export declare interface AuthOptions {
     alias: string;
     code_challenge: string;
     request_id: string;
 }
 
+/**
+ * Response from authentication request.
+ *
+ * @interface AuthResponse
+ * @property {boolean} ok - Whether the authentication request was successful
+ * @property {string} [message] - Optional message describing the result or error
+ */
 export declare interface AuthResponse {
     ok: boolean;
     message?: string;
 }
 
+/**
+ * Encodes a Uint8Array to a base64url string (URL-safe base64 encoding).
+ * Base64url uses '-' and '_' instead of '+' and '/', and removes padding '=' characters.
+ *
+ * @param {Uint8Array} buffer - The buffer to encode
+ * @returns {string} A base64url-encoded string
+ *
+ * @example
+ * ```ts
+ * const bytes = new Uint8Array([255, 254, 253]);
+ * const encoded = base64urlEncode(bytes); // Returns base64url string
+ * ```
+ */
 export declare function base64urlEncode(buffer: Uint8Array): string;
 
+/**
+ * Generates a cryptographically secure random code verifier for PKCE (Proof Key for Code Exchange).
+ *
+ * @param {number} length - The length of the code verifier in bytes (typically 64 for PKCE)
+ * @returns {Uint8Array} A Uint8Array containing random bytes for the code verifier
+ *
+ * @example
+ * ```ts
+ * const verifier = generateCodeVerifier(64);
+ * const verifierString = base64urlEncode(verifier);
+ * ```
+ */
 export declare function generateCodeVerifier(length: number): Uint8Array;
 
+/**
+ * Props for the VContextProvider component.
+ *
+ * @type {Object} Props
+ * @property {string} clientId - Client identifier for authentication
+ * @property {string} apiUrl - API URL for authentication endpoints
+ * @property {ReactNode} children - Child components to be wrapped with context
+ */
 declare type Props = {
     clientId: string;
     apiUrl: string;
     children: ReactNode;
 };
 
+/**
+ * Unsafe function to reset authentication state directly from a context object.
+ *
+ * **Warning**: This function should only be used when you have direct access to the context object.
+ * Prefer using `useVerifierReset()` hook in React components.
+ *
+ * @param {React.ContextType<typeof VContext>} ctx - The authentication context object
+ *
+ * @example
+ * ```ts
+ * // Not recommended - use useVerifierReset() hook instead
+ * const context = useContext(VContext);
+ * resetVerifierStateUnsafe(context);
+ * ```
+ */
 export declare function resetVerifierStateUnsafe(ctx: default_2.ContextType<typeof VContext>): void;
 
+/**
+ * Hook to reset all authentication state back to initial values.
+ *
+ * This hook provides access to the resetState function from the authentication context.
+ * When called, it resets all authentication-related state including:
+ * - identity, authRequestId, isAuthenticating
+ * - codeVerifier, codeChallenge, authCode
+ * - authRequestIdExpires, token, authError
+ *
+ * @returns {() => void} A function that resets all authentication state to initial values
+ *
+ * @example
+ * ```tsx
+ * import { useVerifierReset } from "@abaxx_tech/v-integration-react";
+ *
+ * const LogoutButton = () => {
+ *   const resetState = useVerifierReset();
+ *
+ *   const handleLogout = () => {
+ *     resetState(); // Resets all authentication state
+ *   };
+ *
+ *   return <button onClick={handleLogout}>Logout</button>;
+ * };
+ * ```
+ */
 export declare function useVerifierReset(): () => void;
 
+/**
+ * React context for authentication state and functions.
+ *
+ * This context provides access to all authentication-related state and functions
+ * throughout the component tree. Use `useContext(VContext)` to access the context
+ * in your components.
+ *
+ * @example
+ * ```tsx
+ * import { useContext } from 'react';
+ * import { VContext } from '@abaxx_tech/v-integration-react';
+ *
+ * const MyComponent = () => {
+ *   const { token, identity, isAuthenticating } = useContext(VContext);
+ *   // Use authentication state...
+ * };
+ * ```
+ */
 export declare const VContext: default_2.Context<VContextObj>;
 
+/**
+ * Authentication context object providing access to all authentication-related state and functions.
+ *
+ * @typedef {Object} VContextObj@typedef {Object} VContextObj
+ * @property {string} apiUrl - API base URL for authentication endpoints
+ * @property {string} clientId - Client identifier for authentication
+ * @property {string} authRequestId - Current authentication request ID
+ * @property {React.Dispatch<React.SetStateAction<string>>} setAuthRequestId - Function to set the authentication request ID
+ * @property {string} identity - User identity after successful authentication
+ * @property {React.Dispatch<React.SetStateAction<string>>} setIdentity - Function to set the user identity
+ * @property {boolean} isAuthenticating - Whether authentication is currently in progress
+ * @property {React.Dispatch<React.SetStateAction<boolean>>} setIsAuthenticating - Function to set authentication status
+ * @property {string} codeVerifier - PKCE code verifier for secure authentication
+ * @property {React.Dispatch<React.SetStateAction<string>>} setCodeVerifier - Function to set the code verifier
+ * @property {string} codeChallenge - PKCE code challenge for secure authentication
+ * @property {React.Dispatch<React.SetStateAction<string>>} setCodeChallenge - Function to set the code challenge
+ * @property {string} authCode - Authorization code from successful authentication
+ * @property {React.Dispatch<React.SetStateAction<string>>} setAuthCode - Function to set the authorization code
+ * @property {Date} authRequestIdExpires - Expiration time for the authentication request
+ * @property {React.Dispatch<React.SetStateAction<Date>>} setAuthRequestIdExpires - Function to set the request expiration time
+ * @property {string | null} token - Authentication token, null if not authenticated
+ * @property {React.Dispatch<React.SetStateAction<string | null>>} setToken - Function to set the authentication token
+ * @property {string | null} authError - Authentication error message, null if no error
+ * @property {React.Dispatch<React.SetStateAction<string | null>>} setAuthError - Function to set authentication error
+ * @property {() => void} resetState - Resets all mutable state back to initial values
+ */
 export declare type VContextObj = {
     apiUrl: string;
     clientId: string;
@@ -52,12 +185,103 @@ export declare type VContextObj = {
     resetState: () => void;
 };
 
-export declare const VContextProvider: default_2.FC<Props>;
+/* Excluded from this release type: VContextProvider */
 
+/**
+ * Complete authentication UI component with QR code and email input.
+ *
+ * This component provides a full-screen authentication experience with:
+ * - Background image and branding
+ * - QR code generation with Abaxx branding
+ * - Email/Abaxx ID input field
+ * - Real-time authentication status updates
+ * - Loading states and error handling
+ * - Responsive design with grid layout
+ * - Automatic error boundary protection
+ *
+ * @param {VerifierAuthProps} props - The component props
+ * @param {string} props.title - Title displayed in the login UI (e.g., "Abaxx Drive")
+ * @param {string} [props.containerClass] - Additional CSS classes for the container
+ * @returns {JSX.Element} The complete authentication UI component
+ *
+ * @example
+ * ```tsx
+ * import { VerifierAuth } from "@abaxx_tech/v-integration-react";
+ * import "v-integration-react/index.css";
+ *
+ * const LoginPage = () => {
+ *   return <VerifierAuth title="Abaxx Drive" />;
+ * };
+ * ```
+ */
 export declare const VerifierAuth: default_2.FC<VerifierAuthProps>;
 
+/**
+ * Email input authentication component only.
+ *
+ * Provides a standalone email/Abaxx ID input field with authentication functionality.
+ * Features include:
+ * - Email/Abaxx ID input validation
+ * - Loading states with spinner animation
+ * - Real-time authentication status updates
+ * - Customizable styling with support for both Tailwind classes and hex colors
+ * - Error handling with user feedback
+ * - Success state with checkmark icon
+ * - Automatic error boundary protection
+ *
+ * @param {VerifierAuthEmailProps} props - The component props
+ * @param {string} [props.inputPlaceholder="Enter Email or Abaxx ID"] - Placeholder text for the input field
+ * @param {string} [props.buttonText="Sign In"] - Text displayed on the button
+ * @param {string} [props.inputHeight="v-h-10"] - Height class for the input field
+ * @param {string} [props.inputWidth="v-w-full"] - Width class for the input field
+ * @param {string} [props.inputTextColor="v-text-gray-600"] - Text color for the input field
+ * @param {string} [props.inputBorderColor="v-border-gray-400"] - Border color for the input field
+ * @param {string} [props.inputBackgroundColor="v-bg-transparent"] - Background color for the input field
+ * @param {string} [props.buttonHeight="v-h-10"] - Height class for the button
+ * @param {string} [props.buttonWidth="v-w-full"] - Width class for the button
+ * @param {string} [props.buttonBackgroundColor="v-bg-red"] - Background color for the button
+ * @param {string} [props.buttonTextColor="v-text-white"] - Text color for the button
+ * @param {string} [props.containerClass=""] - Additional CSS classes for the container
+ * @param {string} [props.checkmarkColor="#c40808"] - Color of the checkmark icon
+ * @returns {JSX.Element} The email authentication component
+ *
+ * @example
+ * ```tsx
+ * import { VerifierAuthEmail } from "@abaxx_tech/v-integration-react";
+ * import "v-integration-react/index.css";
+ *
+ * const EmailLoginAuth = () => {
+ *   return (
+ *     <VerifierAuthEmail
+ *       inputPlaceholder="Enter your email"
+ *       buttonText="Sign In"
+ *       buttonBackgroundColor="#0b981"
+ *       checkmarkColor="#0b981"
+ *     />
+ *   );
+ * };
+ * ```
+ */
 export declare const VerifierAuthEmail: default_2.FC<VerifierAuthEmailProps>;
 
+/**
+ * Props for the VerifierAuthEmail component.
+ *
+ * @interface VerifierAuthEmailProps
+ * @property {string} [inputPlaceholder="Enter Email or Abaxx ID"] - Placeholder text for the input field
+ * @property {string} [buttonText="Sign In"] - Text displayed on the button
+ * @property {string} [inputHeight="v-h-10"] - Height class for the input field
+ * @property {string} [inputWidth="v-w-full"] - Width class for the input field
+ * @property {string} [inputTextColor="v-text-gray-600"] - Text color for the input field (Tailwind class or hex color)
+ * @property {string} [inputBorderColor="v-border-gray-400"] - Border color for the input field (Tailwind class or hex color)
+ * @property {string} [inputBackgroundColor="v-bg-transparent"] - Background color for the input field (Tailwind class or hex color)
+ * @property {string} [buttonHeight="v-h-10"] - Height class for the button
+ * @property {string} [buttonWidth="v-w-full"] - Width class for the button
+ * @property {string} [buttonBackgroundColor="v-bg-red"] - Background color for the button (Tailwind class or hex color)
+ * @property {string} [buttonTextColor="v-text-white"] - Text color for the button (Tailwind class or hex color)
+ * @property {string} [containerClass=""] - Additional CSS classes for the container
+ * @property {string} [checkmarkColor="#c40808"] - Color of the checkmark icon (hex color)
+ */
 export declare interface VerifierAuthEmailProps {
     inputPlaceholder?: string;
     buttonText?: string;
@@ -74,13 +298,75 @@ export declare interface VerifierAuthEmailProps {
     checkmarkColor?: string;
 }
 
+/**
+ * Props for the VerifierAuth component.
+ *
+ * @interface VerifierAuthProps
+ * @property {string} title - Title displayed in the login UI
+ * @property {string} [containerClass] - Additional CSS classes for the container
+ */
 export declare interface VerifierAuthProps {
     title: string;
     containerClass?: string;
 }
 
+/**
+ * QR code authentication component only.
+ *
+ * Displays a QR code that users can scan with the Verifier+ app for authentication.
+ * Features include:
+ * - Dynamic QR code generation with authentication parameters
+ * - Loading spinner while QR code is being generated
+ * - Optional status display with success/pending states
+ * - Customizable styling and branding
+ * - Automatic QR code updates when authentication parameters change
+ * - Automatic error boundary protection
+ *
+ * @param {VerifierAuthQrProps} props - The component props
+ * @param {number} [props.size=130] - QR code size in pixels
+ * @param {string} [props.qrColor="#e60100"] - QR code foreground color
+ * @param {string} [props.logoImage] - Logo URL to display in QR center
+ * @param {number} [props.logoWidth=40] - Logo width in pixels
+ * @param {number} [props.logoHeight=20] - Logo height in pixels
+ * @param {number} [props.quietZone=0] - Quiet zone around QR code
+ * @param {string} [props.containerClass=""] - Additional CSS classes for container
+ * @param {boolean} [props.showStatus=true] - Whether to show authentication status
+ * @param {string} [props.checkmarkColor="#c40808"] - Color of the checkmark icon
+ * @returns {JSX.Element} The QR code authentication component
+ *
+ * @example
+ * ```tsx
+ * import { VerifierAuthQr } from "@abaxx_tech/v-integration-react";
+ * import "v-integration-react/index.css";
+ *
+ * const QRLoginAuth = () => {
+ *   return (
+ *     <VerifierAuthQr
+ *       size={150}
+ *       qrColor="#e60100"
+ *       checkmarkColor="#0b981"
+ *       showStatus={true}
+ *     />
+ *   );
+ * };
+ * ```
+ */
 export declare const VerifierAuthQr: default_2.FC<VerifierAuthQrProps>;
 
+/**
+ * Props for the VerifierAuthQr component.
+ *
+ * @interface VerifierAuthQrProps
+ * @property {number} [size=130] - QR code size in pixels
+ * @property {string} [qrColor="#e60100"] - QR code foreground color (hex color)
+ * @property {string} [logoImage="https://content.abaxx.com/assets/static/qr-logo.png"] - Logo URL to display in QR center
+ * @property {number} [logoWidth=40] - Logo width in pixels
+ * @property {number} [logoHeight=20] - Logo height in pixels
+ * @property {number} [quietZone=0] - Quiet zone around QR code
+ * @property {string} [containerClass=""] - Additional CSS classes for container
+ * @property {boolean} [showStatus=true] - Whether to show authentication status (success/pending)
+ * @property {string} [checkmarkColor="#c40808"] - Color of the checkmark icon (hex color)
+ */
 export declare interface VerifierAuthQrProps {
     size?: number;
     qrColor?: string;
@@ -93,8 +379,47 @@ export declare interface VerifierAuthQrProps {
     checkmarkColor?: string;
 }
 
+/**
+ * Main provider component that wraps your application and manages authentication context.
+ *
+ * This component automatically handles:
+ * - PKCE code verifier and challenge generation
+ * - Server-Sent Events (SSE) connection for real-time authentication updates
+ * - Authentication state and token lifecycle management
+ * - Background authentication service
+ *
+ * @param {VerifierProviderProps} props - The provider props
+ * @param {string} props.apiUrl - API URL for authentication endpoints
+ * @param {string} props.clientId - Client identifier for authentication
+ * @param {ReactNode} props.children - Child components to be wrapped
+ * @returns {JSX.Element} The provider component with authentication context
+ *
+ * @example
+ * ```tsx
+ * import { VerifierProvider } from "@abaxx_tech/v-integration-react";
+ *
+ * const App = () => {
+ *   return (
+ *     <VerifierProvider
+ *       apiUrl="https://api.example.com"
+ *       clientId="your-client-id"
+ *     >
+ *       <YourApp />
+ *     </VerifierProvider>
+ *   );
+ * };
+ * ```
+ */
 export declare const VerifierProvider: default_2.FC<VerifierProviderProps>;
 
+/**
+ * Props for the VerifierProvider component.
+ *
+ * @interface VerifierProviderProps
+ * @property {string} clientId - Client identifier for authentication
+ * @property {string} apiUrl - API URL for authentication endpoints
+ * @property {ReactNode} children - Child components to be wrapped with authentication context
+ */
 export declare interface VerifierProviderProps {
     clientId: string;
     apiUrl: string;

package/dist/v-integration-react.js

@@ -1978,12 +1978,26 @@ class gt extends Fr {
       error: null
     };
   }
+  /**
+   * Static method called when an error is thrown in a child component.
+   * Updates the state to indicate an error has occurred.
+   * 
+   * @param {Error} error - The error that was thrown
+   * @returns {State} The new state with error information
+   */
   static getDerivedStateFromError(Q) {
     return {
       hasError: !0,
       error: Q
     };
   }
+  /**
+   * Called after an error has been thrown by a descendant component.
+   * Logs the error for debugging purposes.
+   * 
+   * @param {Error} error - The error that was thrown
+   * @param {ErrorInfo} errorInfo - Additional error information
+   */
   componentDidCatch(Q, ee) {
     console.error("Authentication component error:", Q, ee);
   }

package/package.json

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