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

package/README.md

@@ -8,7 +8,7 @@
 - **Token Management**: Provides authentication token through React Context.
 - **Real-time Authentication**: Server-Sent Events (SSE) for real-time authentication status updates.
 - **PKCE Flow**: Implements OAuth 2.0 PKCE (Proof Key for Code Exchange) for secure authentication.
-- **Error Handling**: Comprehensive error handling and user feedback.
+- **Error Handling**: Comprehensive error handling and user feedback with React Error Boundary for graceful error recovery.
 - **Customizable Styling**: Full control over colors, sizes, and text with support for both Tailwind classes and hex colors.
 - **Background Authentication Service**: Automatic token management and authentication flow handling.
 - **State Reset**: Built-in functionality to reset authentication state back to initial values.
@@ -201,6 +201,7 @@ Complete authentication UI with QR code and email input. This component provides
 - Real-time authentication status updates
 - Loading states and error handling
 - Responsive design with grid layout
+- Automatic error boundary protection for React errors
 
 ### `VerifierAuthQr`
 QR code authentication component only. Displays a QR code that users can scan with the Verifier+ app for authentication.
@@ -252,6 +253,41 @@ Email input authentication component only. Provides a standalone email/Abaxx ID
 - 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 for React errors
+
+## Error Handling
+
+### 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
+- **Error Logging**: Automatically logs errors to the console for debugging
+
+#### Error Display:
+When an 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
+
+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.
+
+#### Example:
+```tsx
+// Error boundary is automatically included - no additional setup needed
+import { VerifierAuth } from "@abaxx_tech/v-integration-react";
+
+const LoginPage = () => {
+  // If any error occurs in VerifierAuth or its children,
+  // the error boundary will catch it and display the error UI
+  return <VerifierAuth title="Abaxx Drive" />;
+};
+```
+
+**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.
 
 ## Context API
 

package/dist/v-integration-react.css

@@ -1 +1 @@
-.v-auth-container *,.v-auth-container *:before,.v-auth-container *:after{box-sizing:border-box;border-width:0;border-style:solid;border-color:#e5e7eb}.v-auth-container{font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,Noto Sans,sans-serif;line-height:1.5}.v-grid{display:grid}.v-grid-cols-1{grid-template-columns:repeat(1,minmax(0,1fr))}.v-grid-responsive{grid-template-columns:1fr}@media (min-width: 768px){.v-grid-responsive{grid-template-columns:1fr 1fr}}.v-h-screen{height:100vh}.v-bg-white{background-color:#fff}.v-bg-left{display:none}@media (min-width: 768px){.v-bg-left{display:block}}.v-flex{display:flex}.v-flex-col{flex-direction:column}.v-items-center{align-items:center}.v-justify-center{justify-content:center}.v-gap-2{gap:.5rem}.v-relative{position:relative}.v-absolute{position:absolute}.v-hidden{display:none}@media (min-width: 768px){.v-hidden.md\:v-block{display:block}}.v-inset-0{top:0;right:0;bottom:0;left:0}.v-h-full{height:100%}.v-w-full{width:100%}.v-w-20{width:5rem}.v-h-20{height:5rem}.v-h-10{height:2.5rem}.v-h-4{height:1rem}.v-h-130{height:130px}.v-h-16{height:4rem}.v-w-4{width:1rem}.v-min-w-300{min-width:300px}.v-w-130{width:130px}.v-w-16{width:4rem}.v-p-3{padding:.75rem}.v-p-4{padding:1rem}.v-p-6{padding:1.5rem}.v-px-2{padding-left:.5rem;padding-right:.5rem}.v-px-4{padding-left:1rem;padding-right:1rem}.v-mb-3{margin-bottom:.75rem}.v-mb-4{margin-bottom:1rem}.v-mb-5{margin-bottom:1.25rem}.v-mb-6{margin-bottom:1.5rem}.v-mb-8{margin-bottom:2rem}.v-my-4{margin-top:1rem;margin-bottom:1rem}.v-text-center{text-align:center}.v-text-sm{font-size:.875rem;line-height:1.25rem}.v-text-base{font-size:1rem;line-height:1.5rem}.v-text-xl{font-size:1.25rem;line-height:1.75rem}.v-text-2xl{font-size:1.5rem;line-height:2rem}.v-font-medium{font-weight:500}.v-font-semibold{font-weight:600}.v-tracking-wide{letter-spacing:.025em}.v-text-black{color:#000}.v-text-white{color:#fff}.v-text-gray-400{color:#9ca3af}.v-text-gray-800{color:#1f2937}.v-text-green-700{color:#15803d}.v-text-green-800{color:#166534}.v-bg-green-100{background-color:#dcfce7}.v-bg-slate-100{background-color:#f1f5f9}.v-text-slate-800{color:#1e293b}.v-bg-transparent{background-color:transparent}.v-bg-red{background-color:#cf0000}.v-text-gray-600{color:#6b7280}.v-border{border-width:1px}.v-border-gray-400{border-color:#9ca3af}.v-rounded{border-radius:.25rem}.v-rounded-lg{border-radius:.5rem}.v-input{-webkit-appearance:none;-moz-appearance:none;appearance:none;border-radius:.25rem;border:1px solid #9ca3af;background-color:transparent;padding:.5rem;text-align:center;color:#6b7280}.v-input:focus{outline:2px solid transparent;outline-offset:2px;border-color:#3b82f6}.v-input:disabled{opacity:.5;cursor:not-allowed}.v-button{display:inline-flex;align-items:center;justify-content:center;gap:.5rem;border-radius:.25rem;padding:.5rem 1rem;font-weight:600;transition:all .2s;cursor:pointer;border:none;background-color:#cf0000;color:#fff}.v-button:hover{background-color:#b91c1c}.v-button:disabled{opacity:.5;cursor:not-allowed}.v-animate-spin{animation:spin 1s linear infinite}@keyframes spin{0%{transform:rotate(0)}to{transform:rotate(360deg)}}.v-fade-in{animation:fadeIn .3s ease-in-out}@keyframes fadeIn{0%{opacity:0;transform:translateY(10px)}to{opacity:1;transform:translateY(0)}}.v-bg-cover{background-size:cover}.v-bg-no-repeat{background-repeat:no-repeat}.v-object-contain{object-fit:contain}.v-mix-blend-multiply{mix-blend-mode:multiply}.v-blur-sm{filter:blur(4px)}.v-fixed{position:fixed}.v-top-4{top:1rem}.v-right-4{right:1rem}
+.v-auth-container *,.v-auth-container *:before,.v-auth-container *:after{box-sizing:border-box;border-width:0;border-style:solid;border-color:#e5e7eb}.v-auth-container{font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,Noto Sans,sans-serif;line-height:1.5}.v-grid{display:grid}.v-grid-cols-1{grid-template-columns:repeat(1,minmax(0,1fr))}.v-grid-responsive{grid-template-columns:1fr}@media (min-width: 768px){.v-grid-responsive{grid-template-columns:1fr 1fr}}.v-h-screen{height:100vh}.v-min-h-screen{min-height:100vh}.v-bg-white{background-color:#fff}.v-bg-left{display:none}@media (min-width: 768px){.v-bg-left{display:block}}.v-flex{display:flex}.v-flex-col{flex-direction:column}.v-items-center{align-items:center}.v-justify-center{justify-content:center}.v-gap-2{gap:.5rem}.v-relative{position:relative}.v-absolute{position:absolute}.v-hidden{display:none}@media (min-width: 768px){.v-hidden.md\:v-block{display:block}}.v-inset-0{top:0;right:0;bottom:0;left:0}.v-h-full{height:100%}.v-w-full{width:100%}.v-w-20{width:5rem}.v-h-20{height:5rem}.v-h-10{height:2.5rem}.v-h-4{height:1rem}.v-h-130{height:130px}.v-h-16{height:4rem}.v-w-4{width:1rem}.v-min-w-300{min-width:300px}.v-w-130{width:130px}.v-w-16{width:4rem}.v-p-3{padding:.75rem}.v-p-4{padding:1rem}.v-p-6{padding:1.5rem}.v-px-2{padding-left:.5rem;padding-right:.5rem}.v-px-4{padding-left:1rem;padding-right:1rem}.v-mb-3{margin-bottom:.75rem}.v-mb-4{margin-bottom:1rem}.v-mb-5{margin-bottom:1.25rem}.v-mb-6{margin-bottom:1.5rem}.v-mb-8{margin-bottom:2rem}.v-my-4{margin-top:1rem;margin-bottom:1rem}.v-text-center{text-align:center}.v-text-sm{font-size:.875rem;line-height:1.25rem}.v-text-base{font-size:1rem;line-height:1.5rem}.v-text-xl{font-size:1.25rem;line-height:1.75rem}.v-text-2xl{font-size:1.5rem;line-height:2rem}.v-font-medium{font-weight:500}.v-font-semibold{font-weight:600}.v-tracking-wide{letter-spacing:.025em}.v-text-black{color:#000}.v-text-white{color:#fff}.v-text-gray-400{color:#9ca3af}.v-text-gray-800{color:#1f2937}.v-text-green-700{color:#15803d}.v-text-green-800{color:#166534}.v-bg-green-100{background-color:#dcfce7}.v-bg-slate-100{background-color:#f1f5f9}.v-text-slate-800{color:#1e293b}.v-bg-transparent{background-color:transparent}.v-bg-red{background-color:#cf0000}.v-text-gray-600{color:#6b7280}.v-border{border-width:1px}.v-border-gray-400{border-color:#9ca3af}.v-rounded{border-radius:.25rem}.v-rounded-lg{border-radius:.5rem}.v-input{-webkit-appearance:none;-moz-appearance:none;appearance:none;border-radius:.25rem;border:1px solid #9ca3af;background-color:transparent;padding:.5rem;text-align:center;color:#6b7280}.v-input:focus{outline:2px solid transparent;outline-offset:2px;border-color:#3b82f6}.v-input:disabled{opacity:.5;cursor:not-allowed}.v-button{display:inline-flex;align-items:center;justify-content:center;gap:.5rem;border-radius:.25rem;padding:.5rem 1rem;font-weight:600;transition:all .2s;cursor:pointer;border:none;background-color:#cf0000;color:#fff}.v-button:hover{background-color:#b91c1c}.v-button:disabled{opacity:.5;cursor:not-allowed}.v-animate-spin{animation:spin 1s linear infinite}@keyframes spin{0%{transform:rotate(0)}to{transform:rotate(360deg)}}.v-fade-in{animation:fadeIn .3s ease-in-out}@keyframes fadeIn{0%{opacity:0;transform:translateY(10px)}to{opacity:1;transform:translateY(0)}}.v-bg-cover{background-size:cover}.v-bg-no-repeat{background-repeat:no-repeat}.v-object-contain{object-fit:contain}.v-mix-blend-multiply{mix-blend-mode:multiply}.v-blur-sm{filter:blur(4px)}.v-fixed{position:fixed}.v-top-4{top:1rem}.v-right-4{right:1rem}

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;