@finsel-dgi/flow-dialog/README.md

A reusable React component library for Pasby eID authentication flows with QR code scanning and signature verification

# @pasby/flow-dialog

A reusable React component library for Pasby eID authentication flows with QR code scanning and signature verification.

## Features

- 🔐 **eID Authentication**: Support for login, identification, linking, signing, and confirmation flows
- 📱 **QR Code Integration**: Dynamic QR code generation for mobile app scanning
- ⚡ **Real-time Polling**: Automatic status updates and session management
- 🎨 **Customizable UI**: Multiple styling options and customizable components
- 📦 **TypeScript Support**: Full type definitions included
- 🚀 **Framework Agnostic**: Works with any React application

## Installation

```bash
npm install @pasby/flow-dialog
# or
yarn add @pasby/flow-dialog
# or
pnpm add @pasby/flow-dialog
```

## Quick Start

```tsx
import React from 'react';
import { FlowDialog, type FlowDialogProps } from '@pasby/flow-dialog';

function App() {
  const handleCompleted = async (response) => {
    console.log('Authentication completed:', response);
    // Handle successful authentication
  };

  const handleCanceled = () => {
    console.log('Authentication canceled');
    // Handle cancellation
  };

  const user = {
    security: {
      nin: 'user-national-id' // Optional for some flows
    }
  };

  return (
    <FlowDialog
      type="link"
      payload="Your authentication payload"
      content={{
        title: "Link Your Account",
        subtitle: "Scan the QR code to complete the linking process"
      }}
      onCompleted={handleCompleted}
      onCanceled={handleCanceled}
      user={user}
      style="dark"
    />
  );
}
```

## API Reference

### FlowDialog Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `ButtonType` | ✅ | Type of authentication flow |
| `payload` | `string` | ✅ | Authentication payload |
| `content` | `TAlert` | ✅ | Dialog content configuration |
| `onCompleted` | `(response: PingResponse) => Promise<void>` | ✅ | Success callback |
| `onCanceled` | `() => void` | ❌ | Cancellation callback |
| `user` | `User` | ❌ | User object with security info |
| `style` | `PasbyStyling` | ❌ | Visual style variant |
| `className` | `string` | ❌ | Additional CSS classes |
| `buttonText` | `string` | ❌ | Custom button text |
| `buttonProps` | `ButtonProps` | ❌ | Custom button configuration |
| `config` | `PasbyFlowConfig` | ❌ | Library configuration |

### Button Types

- `login` - User login flow
- `identify` - User identification flow  
- `link` - Account linking flow
- `sign` - Document signing flow
- `confirm` - Confirmation flow

### Styling Options

- `original` - Pasby brand colors
- `dark` - Dark theme
- `light` - Light theme

### Configuration

```tsx
const config = {
  apiBaseUrl: '/api',           // Base URL for API calls
  pollingInterval: 3000,        // Polling interval in ms
  maxRetries: 3,               // Max retry attempts
  onError: (error) => {},      // Global error handler
  onSuccess: (response) => {}  // Global success handler
};
```

## Advanced Usage

### Custom Button Component

```tsx
<FlowDialog
  type="sign"
  payload="document-to-sign"
  content={{ title: "Sign Document" }}
  onCompleted={handleCompleted}
  buttonProps={{
    children: <CustomButtonIcon />,
    color: "blue"
  }}
/>
```

### Custom Styling

```tsx
<FlowDialog
  type="link"
  payload="link-payload"
  content={{ title: "Link Account" }}
  onCompleted={handleCompleted}
  style="light"
  className="my-custom-class"
/>
```

### Error Handling

```tsx
const config = {
  onError: (error) => {
    console.error('Flow error:', error);
    // Custom error handling
  },
  maxRetries: 5
};

<FlowDialog
  config={config}
  // ... other props
/>
```

## Dependencies

This library requires the following peer dependencies:

- React >= 16.8.0
- React DOM >= 16.8.0

## Browser Support

- Chrome >= 60
- Firefox >= 60
- Safari >= 12
- Edge >= 79

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT © Pasby

## Support

For support, email support@pasby.africa or join our Discord community.