@nibssplc/cams-sdk-react/README.md

React hooks and components for NIBSS CAMS SDK

# @nibssplc/cams-sdk-react

React hooks and components for NIBSS CAMS SDK with support for both regular CAMS authentication and Azure AD MSAL integration.

## Installation

```bash
npm install @nibssplc/cams-sdk-react
```

For MSAL mode, also install:
```bash
npm install @azure/msal-browser @azure/msal-react
```

### Importing Styles

The SDK includes bundled Tailwind CSS. Import it in your app entry point:

```tsx
import '@nibssplc/cams-sdk-react/dist/styles.css';
```

For Next.js, add to `app/layout.tsx` or `pages/_app.tsx`:
```tsx
import '@nibssplc/cams-sdk-react/dist/styles.css';
```

## Features

- ⚛️ React hooks for authentication
- 🔄 Unified provider supporting both REGULAR and MSAL modes
- 🎨 Pre-built UI components (login page, MFA gate)
- 🛡️ Protected route component
- 🎯 TypeScript support
- 🪝 Context-based state management
- 📱 Next.js compatible

## Quick Start

### MSAL Mode (Azure AD + MFA)

```tsx
import { UnifiedCAMSProvider, useCAMSContext } from '@nibssplc/cams-sdk-react';

const msalConfig = {
  auth: {
    clientId: 'your-client-id',
    authority: 'https://login.microsoftonline.com/your-tenant-id',
    redirectUri: window.location.origin
  }
};

function App() {
  return (
    <UnifiedCAMSProvider
      mode="MSAL"
      appCode="your-app-guid"
      msalConfig={msalConfig}
      MFAEndpoint="https://your-mfa-endpoint.com"
    >
      <YourApp />
    </UnifiedCAMSProvider>
  );
}

function YourApp() {
  const { login, logout, isAuthenticated, userProfile } = useCAMSContext();

  return (
    <div>
      {isAuthenticated ? (
        <>
          <p>Welcome, {userProfile?.name}</p>
          <button onClick={logout}>Logout</button>
        </>
      ) : (
        <button onClick={login}>Login</button>
      )}
    </div>
  );
}
```

### REGULAR Mode (Popup Authentication)

```tsx
import { UnifiedCAMSProvider, useCAMSContext } from '@nibssplc/cams-sdk-react';

function App() {
  return (
    <UnifiedCAMSProvider
      mode="REGULAR"
      appCode="your-app-guid"
      camsUrl="https://your-cams-url.com"
      messageOrigin="https://your-cams-url.com"
      windowWidth={500}
      windowHeight={600}
    >
      <YourApp />
    </UnifiedCAMSProvider>
  );
}
```

## Components

### UnifiedCAMSProvider

Main provider component supporting both authentication modes.

**Props (MSAL Mode):**
```tsx
interface MSALProviderProps {
  mode: "MSAL";
  appCode: string;
  msalConfig: Configuration;
  msalInstance?: PublicClientApplication;
  MFAEndpoint: string;
  children: React.ReactNode;
}
```

**Props (REGULAR Mode):**
```tsx
interface RegularProviderProps {
  mode: "REGULAR";
  appCode: string;
  camsUrl: string;
  messageOrigin: string;
  windowWidth: number;
  windowHeight: number;
  authTimeout?: number;
  debug?: boolean;
  children: React.ReactNode;
}
```

### DefaultLoginPage

Pre-built login page with Microsoft and AD authentication options.

```tsx
import { DefaultLoginPage } from '@nibssplc/cams-sdk-react';

function App() {
  return (
    <UnifiedCAMSProvider mode="MSAL" {...config}>
      <DefaultLoginPage />
    </UnifiedCAMSProvider>
  );
}
```

### MFAGate

Component that enforces MFA completion before rendering children.

```tsx
import { MFAGate } from '@nibssplc/cams-sdk-react';

function ProtectedContent() {
  return (
    <MFAGate>
      <YourProtectedContent />
    </MFAGate>
  );
}
```

### ProtectedRoute

Route wrapper that requires authentication.

```tsx
import { ProtectedRoute } from '@nibssplc/cams-sdk-react';

function App() {
  return (
    <ProtectedRoute>
      <YourProtectedPage />
    </ProtectedRoute>
  );
}
```

## Hooks

### useCAMSContext

Access authentication state and methods.

```tsx
import { useCAMSContext } from '@nibssplc/cams-sdk-react';

function MyComponent() {
  const {
    isAuthenticated,
    isLoading,
    userProfile,
    login,
    logout,
    error,
    authMode
  } = useCAMSContext();

  return (
    <div>
      {isAuthenticated && <p>Hello, {userProfile?.name}</p>}
    </div>
  );
}
```

**Return Values:**

| Property | Type | Description |
|----------|------|-------------|
| `isAuthenticated` | boolean | Authentication status |
| `isLoading` | boolean | Loading state |
| `userProfile` | Profile \| null | User profile data |
| `login` | function | Trigger login flow |
| `logout` | function | Logout user |
| `error` | Error \| null | Authentication error |
| `authMode` | 'REGULAR' \| 'MSAL' | Current auth mode |
| `requiresMFA` | boolean | MFA required (MSAL only) |

### useCAMSAuth

Hook for REGULAR mode authentication.

```tsx
import { useCAMSAuth } from '@nibssplc/cams-sdk-react';

const auth = useCAMSAuth({
  appCode: 'your-app-guid',
  camsUrl: 'https://your-cams-url.com',
  messageOrigin: 'https://your-cams-url.com',
  windowWidth: 500,
  windowHeight: 600
});
```

### useCAMSMSALAuth

Hook for MSAL mode authentication.

```tsx
import { useCAMSMSALAuth } from '@nibssplc/cams-sdk-react';

const auth = useCAMSMSALAuth({
  appCode: 'your-app-guid',
  MFAEndpoint: 'https://your-mfa-endpoint.com'
});
```

## Next.js Integration

```tsx
// app/providers.tsx
'use client';

import { UnifiedCAMSProvider } from '@nibssplc/cams-sdk-react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <UnifiedCAMSProvider mode="MSAL" {...config}>
      {children}
    </UnifiedCAMSProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

## Styling

The SDK bundles all required Tailwind CSS, so you don't need to configure Tailwind in your project. Simply import the styles:

```tsx
import '@nibssplc/cams-sdk-react/dist/styles.css';
```

If your project already uses Tailwind, the SDK styles will work alongside your existing configuration.

## Examples

See the [examples](../../examples) directory for complete implementations:
- `integrated-mfa-example.tsx` - MSAL mode with MFA
- `popup-auth-example.tsx` - Regular popup authentication

## License

MIT

## Author

NIBSS PLC, Caleb Boluwade