onairos/POPUP_IMPLEMENTATION_README.md

The Onairos Library is a collection of functions that enable Applications to connect and communicate data with Onairos Identities via User Authorization. Integration for developers is seamless, simple and effective for all applications. LLM SDK capabiliti

# Onairos Popup Implementation & AutoFetch

## Overview

This document describes the redesigned iframe implementation that now uses a popup window approach to fix display cutoff issues and introduces automatic API fetching functionality.

## Problem Solved

**Previous Issue**: The iframe modal overlay was being cut off and not displaying properly, as shown in user feedback.

**Solution**: Replaced the modal overlay with a properly positioned popup window that:
- Opens in a separate window with optimal positioning
- Avoids being cut off by parent container constraints
- Provides better user experience with dedicated window space
- Automatically handles API calls when data is approved

## Key Features

### 1. Popup Window Implementation
- **Proper Positioning**: Centers popup on screen while ensuring it fits within screen bounds
- **Optimal Sizing**: 450x700px window size for comfortable data selection
- **Focus Management**: Automatically brings popup to focus when opened
- **Cross-browser Compatibility**: Works across different browsers and contexts

### 2. AutoFetch Functionality (Default: Enabled)
- **Automatic API Calls**: When `autoFetch` is `true` (default), API calls are made automatically after user approves data
- **Real-time Status**: Shows loading states and API response status
- **Error Handling**: Gracefully handles API failures with user-friendly messages
- **Configurable**: Can be disabled by setting `autoFetch: false`

### 3. Enhanced User Experience
- **Visual Feedback**: Loading spinners and status indicators
- **Selection Summary**: Shows count of selected data types
- **Smart Buttons**: Buttons adapt based on autoFetch setting
- **Responsive Design**: Works well on different screen sizes

## Implementation Details

### Files Modified/Created

1. **`src/iframe/dataRequestHandler.js`** - Updated popup handler with autoFetch support
2. **`src/onairosButton.jsx`** - Modified to use popup instead of modal overlay
3. **`src/components/DataRequest.js`** - Enhanced with autoFetch functionality
4. **`public/data_request_popup.html`** - New standalone popup HTML file
5. **`onairos.d.ts`** - Updated TypeScript definitions

### Key Functions

#### `openDataRequestPopup(data)`
```javascript
const popup = openDataRequestPopup({
  requestData: ['email', 'profile'],
  webpageName: 'My App',
  userData: { email: 'user@example.com' },
  autoFetch: true,
  proofMode: false
});
```

#### `listenForPopupMessages(callback, options)`
```javascript
const cleanup = listenForPopupMessages(
  handlePopupMessage,
  {
    autoFetch: true,
    onApiResponse: handleApiResponse
  }
);
```

## Usage Examples

### Basic Usage (AutoFetch Enabled)
```jsx
<OnairosButton
  requestData={['email', 'profile', 'social']}
  webpageName="My Application"
  autoFetch={true} // Default
  onComplete={(result) => {
    console.log('Data approved:', result.approved);
    console.log('API Response:', result.apiResponse);
  }}
/>
```

### Manual API Handling (AutoFetch Disabled)
```jsx
<OnairosButton
  requestData={['email', 'profile']}
  webpageName="My Application"
  autoFetch={false}
  onComplete={(result) => {
    if (result.approved) {
      // Handle approved data manually
      makeCustomApiCall(result.dataTypes);
    }
  }}
/>
```

## API Response Format

When `autoFetch` is enabled, the `onComplete` callback receives:

```javascript
{
  approved: ['email', 'profile'], // Array of approved data types
  timestamp: "2024-01-15T10:30:00.000Z",
  userEmail: "user@example.com",
  appName: "My Application",
  apiResponse: { /* API response data */ }, // Present on success
  apiError: "Error message", // Present on API failure
  apiUrl: "https://api2.onairos.uk/inferenceTest"
}
```

## Configuration Options

### OnairosButton Props
- `autoFetch` (boolean, default: `true`) - Enable automatic API calls
- `requestData` (array) - Specific data types to request
- `webpageName` (string) - Application name shown to user
- `onComplete` (function) - Callback when data request completes
- `proofMode` (boolean) - Enable proof mode for verification

### Popup Handler Options
- `autoFetch` (boolean) - Whether to make automatic API calls
- `onApiResponse` (function) - Callback for API responses

## Error Handling

The implementation includes comprehensive error handling:

1. **Popup Blocked**: Shows user-friendly message about enabling popups
2. **API Failures**: Displays error messages in the UI
3. **Network Issues**: Graceful degradation with retry logic
4. **Invalid Data**: Validation before API calls

## Testing

Use the provided test file to verify the implementation:

```bash
# Open the test file in a browser
open test-popup-implementation.html
```

The test demonstrates:
- Popup opening and positioning
- Data selection interface
- AutoFetch functionality
- API response handling
- Error scenarios

## Migration Guide

### From Modal to Popup

**Before (Modal)**:
```javascript
// Modal was embedded in page
setShowOverlay(true);
```

**After (Popup)**:
```javascript
// Popup opens in separate window
const popup = openDataRequestPopup(data);
```

### AutoFetch Integration

**Before (Manual API)**:
```javascript
onComplete={(result) => {
  if (result.approved) {
    fetch('/api/process', {
      method: 'POST',
      body: JSON.stringify(result.dataTypes)
    });
  }
}}
```

**After (AutoFetch)**:
```javascript
onComplete={(result) => {
  // API call already made automatically
  console.log('API Response:', result.apiResponse);
}}
```

## Browser Compatibility

- ✅ Chrome 80+
- ✅ Firefox 75+
- ✅ Safari 13+
- ✅ Edge 80+

## Security Considerations

1. **Cross-Origin Messaging**: Uses `postMessage` with origin validation
2. **Popup Blocking**: Graceful handling of popup blockers
3. **Data Validation**: Validates all data before API calls
4. **HTTPS Required**: API calls require secure connections

## Performance

- **Lazy Loading**: Popup HTML loaded only when needed
- **Efficient Messaging**: Minimal data transfer between windows
- **Memory Management**: Proper cleanup of event listeners
- **API Optimization**: Single API call per approval

## Troubleshooting

### Common Issues

1. **Popup Blocked**
   - Solution: Ensure popups are allowed for the domain
   - Check browser popup blocker settings

2. **API Calls Failing**
   - Verify network connectivity
   - Check API endpoint availability
   - Review CORS settings

3. **Data Not Passing**
   - Ensure popup loads completely before sending data
   - Check browser console for errors

### Debug Mode

Enable debug logging:
```javascript
localStorage.setItem('onairos-debug', 'true');
```

## Future Enhancements

- [ ] Offline support with request queuing
- [ ] Custom API endpoint configuration
- [ ] Batch API requests for multiple approvals
- [ ] Enhanced analytics and tracking
- [ ] Mobile-optimized popup sizing

## Support

For issues or questions:
1. Check the troubleshooting section
2. Review browser console for errors
3. Test with the provided test file
4. Contact support with detailed error information