@pakt/auth-module

A comprehensive React authentication module for Pakt applications. This package provides a complete authentication solution with support for email/password authentication, Google OAuth, and two-factor authentication.

Features

• Persistent Auth State: Authentication state persists across page reloads
• Plug-and-Play Hook: Single usePaktAuth hook for all auth functionality
• Email/Password Authentication: Complete signup, login, and password reset flows
• Google OAuth Integration: Seamless Google authentication
• Two-Factor Authentication: Email-based 2FA support
• Automatic Account Fetching: Full user profile fetched automatically after login
• Customizable UI: Theme customization support
• TypeScript Support: Full type definitions included

Installation

yarn add @pakt/auth-module
# or
npm install @pakt/auth-module
# or
bun add @pakt/auth-module

Quick Start

import React, { useRef } from 'react';
import PaktAuth, { usePaktAuth, AuthRef, ConfigContextType } from '@pakt/auth-module';
import '@pakt/auth-module/dist/styles.css';

function App() {
  const authRef = useRef<AuthRef>(null);
  const { user, isAuthenticated, token, logout, getAccount } = usePaktAuth();

  const config: ConfigContextType = {
    baseUrl: "https://api-devpaktbuild.chain.site",
    verbose: true,
    googleOAuth: {
      clientId: "your-google-client-id.apps.googleusercontent.com",
    },
  };

  // Check authentication status
  if (isAuthenticated && user) {
    return (
      <div>
        <h1>Welcome, {user.firstName || user.email}!</h1>
        <p>Email: {user.email}</p>
        <button onClick={logout}>Logout</button>
      </div>
    );
  }

  // Show login/signup
  return (
    <div>
      <button onClick={() => authRef.current?.onLogin()}>Login</button>
      <button onClick={() => authRef.current?.onSignup()}>Sign Up</button>
      
      <PaktAuth
        config={config}
        ref={authRef}
        onLoginSuccess={() => {
          getAccount(); // Fetch full account details after login (optional - automatically called)
        }}
      />
    </div>
  );
}

Configuration

ConfigContextType

The main configuration object for the PaktAuth component:

interface ConfigContextType {
  baseUrl: string;        // Required: API base URL
  testnet?: boolean;      // Optional: Use testnet environment
  verbose?: boolean;      // Optional: Enable verbose logging
  
  // Theme customization
  theme?: ITheme;
  
  // Error handling
  errorHandler?: (errorMessage: string) => void;
  
  // Google OAuth configuration
  googleOAuth?: GoogleOAuthConfig;
}

Theme Configuration

Customize the appearance of the authentication components with semantic color tokens:

interface ITheme {
  // Brand Colors
  brandPrimary?: string;           // Main brand color for buttons, links, icons
  brandSecondary?: string;         // Secondary brand color for backgrounds
  
  // Text Colors
  headingText?: string;            // Color for headings and titles
  bodyText?: string;               // Color for body text and descriptions
  inverseText?: string;            // White text for dark backgrounds
  
  // Background Colors
  formBackground?: string;         // Background color for forms and cards
  modalOverlay?: string;           // Overlay color for modals and dialogs
  
  // Interactive Elements
  buttonPrimaryBackground?: string;    // Primary button background (supports gradients)
  buttonPrimaryText?: string;          // Primary button text color
  buttonPrimaryHover?: string;         // Primary button hover state
  buttonOutlineBackground?: string;    // Outline button background
  buttonOutlineText?: string;          // Outline button text color
  buttonOutlineHoverBackground?: string; // Outline button hover background
  buttonOutlineHoverText?: string;     // Outline button hover text
  
  // Form Input Colors
  inputBackground?: string;        // Input field background
  inputBorder?: string;            // Input field border
  inputFocusBorder?: string;       // Input field focus border
  inputPlaceholder?: string;       // Input placeholder text
  inputText?: string;              // Input text color
  inputLabel?: string;             // Input label text color
  
  // State Colors
  errorBackground?: string;        // Error state background
  errorText?: string;              // Error state text
  errorBorder?: string;            // Error state border
  successText?: string;            // Success state text
}

Example with gradients:

const config: ConfigContextType = {
  theme: {
    brandPrimary: "#007C5B",
    buttonPrimaryBackground: "linear-gradient(102.28deg, #008D6C 32.23%, #11FFC7 139.92%)",
    formBackground: "#FFFFFF",
    errorText: "#DC2626",
  },
  // ... other config
};

Google OAuth Configuration

interface GoogleOAuthConfig {
  clientId: string;           // Required: Your Google OAuth client ID
  clientSecret?: string;      // Optional: Client secret
  redirectUri?: string;       // Optional: Redirect URI
  scope?: string[];           // Optional: OAuth scopes
  hostedDomain?: string;      // Optional: Hosted domain restriction
}

PAKT SDK Configuration

interface PaktSDKConfig {
  baseUrl: string;    // Required: API base URL
  testnet?: boolean;  // Optional: Use testnet
  verbose?: boolean;  // Optional: Enable verbose logging
}

Component Props

PaktAuth Props

interface PaktAuthProps {
  config: ConfigContextType;                    // Required: Configuration object
  textConfig?: AuthTextConfig;                  // Optional: Custom text configuration
  onLoginSuccess?: (userData: any) => void;     // Optional: Login success callback
  onSignupSuccess?: (userData: any) => void;    // Optional: Signup success callback
}

Text Configuration

Customize the text displayed in authentication dialogs:

interface AuthTextConfig {
  loginTitle: string;        // Title for login dialogs
  loginDescription: string;  // Description for login dialogs
  signupTitle: string;       // Title for signup dialogs
  signupDescription: string; // Description for signup dialogs
}

Example:

const textConfig = {
  loginTitle: "Welcome Back",
  loginDescription: "Sign in to continue your journey",
  signupTitle: "Join Our Community",
  signupDescription: "Start building amazing things together"
};

AuthRef Methods

Access authentication methods through the ref:

interface AuthRef {
  onLogin: () => void;    // Opens the login dialog
  onSignup: () => void;   // Opens the signup dialog
}

Using the Hook

The usePaktAuth hook provides everything you need for authentication:

import { usePaktAuth } from '@pakt/auth-module';

function MyComponent() {
  const { 
    user,              // User data (null if not authenticated)
    isAuthenticated,   // Boolean: true if user is logged in
    token,             // Auth token (from cookie)
    logout,            // Logout function
    getAccount,        // Fetch full account details (optional token parameter)
    loading,           // Loading state
    error              // Error message
  } = usePaktAuth();

  // Check if user is authenticated
  if (isAuthenticated) {
    return <div>Welcome, {user?.email}</div>;
  }

  return <div>Please log in</div>;
}

Common Use Cases

Check if user is authenticated:

const { isAuthenticated } = usePaktAuth();

if (isAuthenticated) {
  // User is logged in
}

Access user data:

const { user } = usePaktAuth();

// User data includes: email, firstName, lastName, _id, etc.
console.log(user?.email);
console.log(user?.firstName);

Logout:

const { logout } = usePaktAuth();

const handleLogout = async () => {
  await logout(); // Clears auth state and cookies
};

Fetch account details:

const { getAccount } = usePaktAuth();

// Fetch full user profile from /account endpoint
// Token is automatically retrieved from cookie if not provided
await getAccount();

// Or provide token explicitly
await getAccount(authToken);

Get auth token:

const { token } = usePaktAuth();

// Token is automatically read from cookie
if (token) {
  // Use token for API calls
}

Usage Examples

Basic Implementation

import React, { useRef } from 'react';
import PaktAuth, { AuthRef, ConfigContextType } from '@pakt/auth-module';

function MyApp() {
  const authRef = useRef<AuthRef>(null);

  const config: ConfigContextType = {
    baseUrl: "https://api-devpaktbuild.chain.site",
  };

  const textConfig = {
    loginTitle: "Welcome Back",
    loginDescription: "Sign in to continue your journey",
    signupTitle: "Join Our Community",
    signupDescription: "Start building amazing things together"
  };

  return (
    <div>
      <button onClick={() => authRef.current?.onLogin()}>
        Login
      </button>
      <button onClick={() => authRef.current?.onSignup()}>
        Sign Up
      </button>
      
      <PaktAuth
        config={config}
        textConfig={textConfig}
        ref={authRef}
        onLoginSuccess={(userData) => {
          console.log("User logged in:", userData);
        }}
        onSignupSuccess={(userData) => {
          console.log("User signed up:", userData);
        }}
      />
    </div>
  );
}

With Google OAuth

import React, { useRef } from 'react';
import { PaktAuth, AuthRef, ConfigContextType } from '@pakt/auth-module';

function MyApp() {
  const authRef = useRef<AuthRef>(null);

  const config: ConfigContextType = {
    baseUrl: "https://api-devpaktbuild.chain.site",
    verbose: true,
    theme: {
      brandPrimary: "#007C5B",
      brandSecondary: "#19A966",
    },
    googleOAuth: {
      clientId: "your-google-client-id.apps.googleusercontent.com",
    },
  };

  return (
    <div>
      <PaktAuth
        config={config}
        ref={authRef}
        onLoginSuccess={(userData) => {
          // Handle successful login
          console.log("Login successful:", userData);
        }}
        onSignupSuccess={(userData) => {
          // Handle successful signup
          console.log("Signup successful:", userData);
        }}
      />
    </div>
  );
}

Custom Error Handling

import React, { useRef } from 'react';
import PaktAuth, { AuthRef, ConfigContextType } from '@pakt/auth-module';
import { toast } from 'react-hot-toast'; // Example toast library

function MyApp() {
  const authRef = useRef<AuthRef>(null);

  const config: ConfigContextType = {
    baseUrl: "https://api-devpaktbuild.chain.site",
    errorHandler: (errorMessage: string) => {
      // Custom error handling
      toast.error(errorMessage);
      
      // Or log to your error tracking service
      // Sentry.captureException(new Error(errorMessage));
    },
  };

  return (
    <PaktAuth
      config={config}
      ref={authRef}
      onLoginSuccess={(userData) => {
        toast.success("Login successful!");
        // Handle login success
      }}
      onSignupSuccess={(userData) => {
        toast.success("Account created successfully!");
        // Handle signup success
      }}
    />
  );
}

Authentication Flow

The PaktAuth component provides a complete authentication flow:

1. Login Method Selection: Users can choose between email/password or Google OAuth
2. Email/Password Login: Traditional login with email and password
3. Google OAuth: One-click login with Google account
4. Two-Factor Authentication: Email-based 2FA if enabled
5. Signup Flow: Complete registration process with email verification
6. Password Reset: Forgot password and reset functionality
7. Email Verification: Account verification with resend capability

PAKT SDK Integration

The module integrates with the PAKT SDK for backend authentication. The SDK handles:

• User registration and login
• Email verification
• Password reset
• Two-factor authentication
• Google OAuth validation
• User data management

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Please refer to the CODE_OF_CONDUCT.md and LICENSE files.

License

MIT