Utlwa API

A React library that provides authentication, API integration, and common UI components for Utlwa applications.

Installation

npm install utlwa-api

Key Components

UtlwaProvider

The UtlwaProvider is a required wrapper component that provides authentication context to all child components. Any component that uses hooks from this library (useAuthSession, useGet, usePost, etc.) must be wrapped in this provider.

This component serves several purposes:

1. Authentication Management:

   • Wraps the application with AuthProvider for handling authentication state
   • Uses a preconfigured login page URL (https://utlwa.app/#/account/login)
   • Sets up the authentication context for API requests

2. Layout Structure:

   • Automatically includes a PageFooter component at the bottom of the application
   • Ensures consistent layout across all pages

3. Context Provider:

   • Makes authentication context available to all child components
   • Enables the use of authentication-related hooks throughout the app

Props:

• children: React components that will have access to the authentication context (Required)

Basic Usage

Here's a minimal example of how to set up your application with Utlwa:

import { UtlwaProvider } from 'utlwa-api';

function App() {
  return (
    <UtlwaProvider>
      <YourApp />
    </UtlwaProvider>
  );
}

⚠️ IMPORTANT: Do not use any hooks from this library (useAuthSession, useGet, usePost, etc.) in components that are not wrapped by UtlwaProvider. Doing so will result in runtime exceptions as these hooks depend on the authentication context provided by UtlwaProvider.

Available Hooks

The library provides several hooks for authentication and API interactions:

• useAuthSession: Check authentication status
• useGet: Make GET requests
• usePost: Make POST requests
• usePatch: Make PATCH requests
• useDelete: Make DELETE requests

Components

MainActionBar

A navigation bar component that includes:

• User profile display
• Authentication status
• Logout functionality

PageFooter

A consistent footer component that is automatically included when using UtlwaProvider.

ProfileImage

A component for displaying user avatars with fallback to initials.

Example Implementation

The example app demonstrates proper setup and usage:

import { UtlwaProvider } from '../utlwa/components/UtlwaProvider';
import { AppContent } from './components/AppContent';

function App() {
  return (
    <UtlwaProvider>
      <AppContent />
    </UtlwaProvider>
  );
}

This setup ensures:

• All child components have access to authentication features
• The application has a consistent layout structure
• Authentication redirects are properly configured

Authentication Flow

The UtlwaProvider internally configures:

1. A login page URL (https://utlwa.app/#/account/login)
2. Authentication context for API requests
3. Automatic token management and refresh functionality

When authentication is required:

1. Users are redirected to the preconfigured login page
2. After successful login, they are redirected back to your application
3. The library handles token management and refresh automatically

Authentication Handling

The library provides a simple way to handle authentication states in your components. Here's how to implement authentication handling:

import { LoginButton } from 'utlwa-api';
import { useAuthSession } from 'utlwa-api';

const YourComponent = () => {
    // Check if user needs to login
    const { shouldLogin } = useAuthSession();

    // Show login button if authentication is required
    if (shouldLogin) {
        return (<LoginButton />);
    }

    // Render your authenticated content
    return (
        <div>
            Your protected content here
        </div>
    );
};

Key Authentication Components and Hooks

1. useAuthSession:

   • A hook that provides authentication state
   • Returns { shouldLogin } to indicate if authentication is required
   • Must be used within a component wrapped by UtlwaProvider

2. LoginButton:

   • A pre-styled button component that handles the login process
   • Automatically redirects to the configured login page
   • Handles the authentication flow and token management
   • Can be customized with your own component:

     <LoginButton Component={({ onClick }) => (
       <button onClick={onClick}>Custom Login</button>
     )} />

Authentication Flow Example

Here's a complete example showing how authentication works in a real component:

import { LoginButton } from 'utlwa-api';
import { useAuthSession } from 'utlwa-api';
import { MainActionBar } from 'utlwa-api';

export const AppContent = () => {
    const { shouldLogin } = useAuthSession();

    if (shouldLogin) {
        return (<LoginButton />)
    }

    return (
        <>
            <MainActionBar>Your App Name</MainActionBar>
            <div className="app-container">
                <h1>Protected Content</h1>
                <div className="content-container">
                    Your authenticated content here
                </div>
            </div>
        </>
    );
};

This pattern ensures that:

• Protected content is only shown to authenticated users
• Users are automatically prompted to login when needed
• The authentication state is properly managed
• Token refresh and management is handled automatically

Development

To run the example application:

npm install
npm run dev

License

[Add your license information here]