@nibssplc/cams-sdk/README.md

Central Authentication Management Service (CAMS) SDK for popup-based authentication with Azure AD + custom 2FA

# @nibssplc/cams-sdk

Central Authentication Management Service (CAMS) SDK for popup-based authentication with Azure AD and custom 2FA.

## Installation

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

## Features

- 🔐 Popup-based authentication flow
- 🛡️ Built-in 2FA/MFA support
- 📦 Session management with automatic timeout
- 🔄 Retry mechanism for failed authentications
- 🎯 TypeScript support
- ✅ Input validation with Zod
- 🪵 Debug logging capabilities

## Quick Start

```typescript
import { authenticateWithCAMS, CAMSConfig } from '@nibssplc/cams-sdk';

const config: CAMSConfig = {
  camsUrl: 'https://your-cams-url.com',
  messageOrigin: 'https://your-cams-url.com',
  windowWidth: 500,
  windowHeight: 600,
  authTimeout: 300000, // 5 minutes
  debug: true
};

const appCode = 'your-app-guid';

try {
  const result = await authenticateWithCAMS(appCode, config);
  console.log('Authenticated:', result);
} catch (error) {
  console.error('Authentication failed:', error);
}
```

## Configuration

### CAMSConfig

| Property | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| `camsUrl` | string | Yes | - | CAMS authentication URL |
| `messageOrigin` | string | Yes | - | Expected message origin for security |
| `windowWidth` | number | Yes | - | Popup window width |
| `windowHeight` | number | Yes | - | Popup window height |
| `authTimeout` | number | No | 300000 | Authentication timeout (ms) |
| `idleTimeout` | number | No | 60000 | Idle timeout (ms) |
| `storageKey` | string | No | 'cams-session' | Custom storage key |
| `retryAttempts` | number | No | 0 | Auto-retry on failure |
| `debug` | boolean | No | false | Enable debug logging |

## API Reference

### authenticateWithCAMS

Main authentication function that opens a popup and handles the authentication flow.

```typescript
function authenticateWithCAMS(
  appCode: string,
  config: CAMSConfig
): Promise<AuthResult>
```

### Session Management

```typescript
import { SessionManager } from '@nibssplc/cams-sdk';

const sessionManager = new SessionManager(config);

// Check if session is valid
const isValid = sessionManager.isSessionValid();

// Get session data
const session = sessionManager.getSession();

// Clear session
sessionManager.clearSession();
```

### MFA Authentication

```typescript
import { authenticateWithMFA } from '@nibssplc/cams-sdk';

const result = await authenticateWithMFA({
  appCode: 'your-app-guid',
  MFAEndpoint: 'https://your-mfa-endpoint.com',
  accessToken: 'user-access-token'
});
```

## Error Handling

```typescript
import { CAMSError, CAMSErrorType } from '@nibssplc/cams-sdk';

try {
  await authenticateWithCAMS(appCode, config);
} catch (error) {
  if (error instanceof CAMSError) {
    switch (error.type) {
      case CAMSErrorType.POPUP_BLOCKED:
        console.error('Popup was blocked');
        break;
      case CAMSErrorType.TIMEOUT:
        console.error('Authentication timed out');
        break;
      case CAMSErrorType.USER_CANCELLED:
        console.error('User cancelled authentication');
        break;
      default:
        console.error('Authentication error:', error.message);
    }
  }
}
```

## Types

```typescript
export interface Profile {
  email: string;
  name: string;
  // ... other profile fields
}

export interface AuthResult {
  success: boolean;
  profile?: Profile;
  token?: string;
}
```

## React Integration

For React applications, use the companion package [@nibssplc/cams-sdk-react](./packages/react/README.md).

## License

MIT

## Author

NIBSS PLC, Caleb Boluwade