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

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.7",
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },