@authava/react-client/README.md

React client library for seamless integration with Authava's white-label authentication service

# @authava/react-client

React client library for seamless integration with Authava's white-label authentication service.

## Installation

```bash
npm install @authava/react-client @authava/client
```

## Usage

1. Wrap your application with the AuthavaProvider:

```tsx
import { AuthavaProvider } from '@authava/react-client';

function App() {
  return (
    <AuthavaProvider config={{ domain: 'auth.yourdomain.com' }}>
      <YourApp />
    </AuthavaProvider>
  );
}
```

2. Use the useAuthava hook in your components:

```tsx
import { useAuthava } from '@authava/react-client';

function Profile() {
  const { isLoading, session, sessionState } = useAuthava();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!session) {
    return <div>Please log in</div>;
  }

  return (
    <div>
      <h1>Welcome, {session.user.email}!</h1>
      <p>Session status: {sessionState.status}</p>
    </div>
  );
}
```

## 🆕 Role and Permission Helpers

When a session is valid, you can easily check for user roles and permissions using `hasRole` and `hasPermission`. These helpers are available from the `useAuthava()` hook (in React)or manually in your own app logic by inspecting the user's `roles` and `permissions`.

### 🔑 Single Role or Permission

```ts
const { hasRole, hasPermission } = useAuthava()

if (hasRole('admin')) {
  console.log('User is an admin')
}

if (hasPermission('delete_user')) {
  console.log('User has delete access')
}
```

### 📚 Multiple Roles or Permissions

```ts
const { hasRole, hasPermission } = useAuthava()

if (hasRole(['editor', 'admin'])) {
  console.log('User has editorial or administrative rights')
}

if (hasPermission(['export_data', 'read_logs'])) {
  console.log('User can either export data or read logs')
}
```

> These helpers return `true` if **any** of the roles or permissions match (logical OR).
> If you're using React, they are available through the `useAuthava()` hook.
> In non-React environments, you'll need to define similar logic manually:

```ts
function hasRole(user, rolesToCheck) {
  const userRoles = user.roles ?? []
  const targets = Array.isArray(rolesToCheck) ? rolesToCheck : [rolesToCheck]
  return targets.some(role => userRoles.includes(role))


## Features

- 🔒 Seamless session management
- 🔄 Automatic session refresh
- 📡 Cross-tab synchronization
- ⚛️ React hooks for easy integration
- 🎯 TypeScript support
- ⚡ Next.js compatible

## API Reference

### AuthavaProvider

The `AuthavaProvider` component wraps your application and provides authentication context.

Props:
- `config`: Configuration object for Authava client
  - `domain`: Your Authava domain
  - `secure`: Use HTTPS (default: true)
  - `autoRefresh`: Enable automatic session refresh (default: true)
  - `refreshBuffer`: Minutes before expiration to refresh (default: 5)

### useAuthava Hook

The `useAuthava` hook provides access to the authentication state.

Returns:
- `isLoading`: Boolean indicating if the initial session check is in progress
- `session`: Current session object or null if not authenticated
- `sessionState`: Detailed session state including status and user info

## License

MIT