onairos 1.0.13 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+## [2.0.0] - 2024-01-15
+
+### 🚀 Major Release - Simplified Integration & Enhanced UX
+
+#### ✨ New Features
+- **Popup-based Data Requests**: Completely redesigned iframe implementation using popup windows
+  - Fixes display cutoff issues seen in previous versions
+  - Better positioning and sizing (450x700px)
+  - Proper focus management and cross-browser compatibility
+
+- **AutoFetch by Default**: Automatic API calls after user approval
+  - No more manual event handling required
+  - API responses included directly in onComplete callback
+  - Configurable with `autoFetch` prop (default: true)
+
+- **Simplified OnairosButton Component**: Much cleaner integration
+  ```jsx
+  // Before v2.0 (complex)
+  <Onairos requestData={complexRequestObject} webpageName={webpageName} />
+  // + manual event listeners for API handling
+  
+  // After v2.0 (simple)
+  <OnairosButton
+    requestData={['email', 'profile']}
+    webpageName="My App"
+    onComplete={(result) => console.log(result.apiResponse)}
+  />
+  ```
+
+#### 🎨 Enhanced User Experience
+- **Real-time Status Updates**: Loading states and progress indicators
+- **Better Error Handling**: User-friendly error messages and retry logic
+- **Visual Feedback**: Selection summaries and confirmation states
+- **Smart Button Text**: Adapts based on autoFetch setting
+
+#### 🔧 Technical Improvements
+- **Robust Popup Communication**: Improved postMessage handling with retry logic
+- **Memory Management**: Proper cleanup of event listeners and popup references
+- **TypeScript Support**: Updated type definitions for new API
+- **Cross-browser Compatibility**: Tested on Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
+
+#### 📚 Documentation
+- **Comprehensive README**: Updated with simple usage examples
+- **Migration Guide**: Clear path from v1.x to v2.0
+- **Implementation Guide**: Detailed popup implementation documentation
+- **Test Files**: Example implementations for testing
+
+#### 🔄 API Changes
+- **New Response Format**: Includes apiResponse and apiError fields when autoFetch is enabled
+- **Simplified Props**: Array-based requestData instead of complex objects
+- **Backward Compatibility**: Legacy format still documented for reference
+
+#### 🐛 Bug Fixes
+- Fixed iframe cutoff issues with popup implementation
+- Improved error handling for blocked popups
+- Better handling of API failures and network issues
+- Fixed memory leaks with proper cleanup
+
+### Migration from v1.x
+
+**Installation remains the same:**
+```bash
+npm install onairos
+```
+
+**Simple migration example:**
+```jsx
+// v1.x (complex)
+const requestData = {
+  Small: { type: "Personality", descriptions: "...", reward: "..." },
+  Medium: { type: "Personality", descriptions: "...", reward: "..." },
+  Large: { type: "Personality", descriptions: "...", reward: "..." }
+};
+
+// v2.0 (simple)
+const requestData = ['email', 'profile', 'social'];
+```
+
+For detailed migration instructions, see the [README.md](./README.md#migration-from-v1x).
+
+---
+
+## [1.0.17] - Previous Release
+
+### Features
+- Initial iframe implementation
+- Manual API handling with window.sendMessage
+- Complex request object format
+- Extension-based data requests
+
+### Known Issues
+- Iframe display cutoff problems
+- Complex integration requiring manual event handling
+- Limited error handling capabilities
+
+---
+
+## Development Notes
+
+- **Breaking Changes**: v2.0.0 introduces significant API simplifications
+- **Backward Compatibility**: Legacy documentation preserved for reference
+- **Future Plans**: Enhanced mobile support, offline capabilities, custom API endpoints 

package/GITBOOK_OVERVIEW.md

@@ -0,0 +1,123 @@
+# LLM Memory SDK
+
+## Overview
+
+The Onairos LLM Memory SDK provides a unified interface for OpenAI, Anthropic Claude, and Google Gemini APIs with built-in **Retrieval-Augmented Generation (RAG)** capabilities. This enables AI models to remember and personalize interactions across sessions while maintaining user privacy.
+
+## Key Features
+
+### 🔗 **Unified API**
+- Single interface for multiple LLM providers (OpenAI, Anthropic, Google)
+- Drop-in replacement for existing OpenAI implementations
+- Seamless model switching between providers
+
+### 🧠 **Memory Enhancement** 
+- Automatic extraction and storage of meaningful user context
+- RAG-powered personalization for more relevant responses
+- Privacy-focused memory storage (insights, not raw conversations)
+
+### 🔐 **Session Management**
+- JWT-based user authentication and isolation
+- Secure session tokens with configurable expiration
+- Guest and authenticated user support
+
+### 📊 **Vector Storage**
+- Pinecone integration for semantic memory search
+- Intelligent context retrieval based on query similarity
+- Scalable memory management with user isolation
+
+## How It Works
+
+```mermaid
+graph LR
+    A[User Query] --> B[Session Validation]
+    B --> C[Memory Retrieval]
+    C --> D[Context Injection]
+    D --> E[LLM API Call]
+    E --> F[Response Generation]
+    F --> G[Memory Extraction]
+    G --> H[Vector Storage]
+    H --> I[Enhanced Response]
+```
+
+1. **Authentication**: Validate user session with JWT tokens
+2. **Memory Retrieval**: Search vector database for relevant user context
+3. **Context Enhancement**: Inject retrieved memories into the prompt
+4. **LLM Processing**: Send enhanced prompt to chosen LLM provider
+5. **Memory Storage**: Extract and store meaningful insights for future use
+
+## Quick Start
+
+### Installation
+```bash
+npm install onairos
+```
+
+### Basic Usage
+```javascript
+import { OnairosClient } from 'onairos';
+
+const onairos = new OnairosClient({
+  openaiApiKey: process.env.OPENAI_API_KEY,
+  pineconeApiKey: process.env.PINECONE_API_KEY,
+  pineconeEnvironment: process.env.PINECONE_ENVIRONMENT,
+  jwtSecret: process.env.JWT_SECRET
+});
+
+await onairos.initialize();
+
+const userId = 'user-123';
+const sessionToken = onairos.generateSessionToken(userId);
+
+const response = await onairos.completions({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'What should I learn next?' }],
+  userId,
+  sessionToken
+});
+```
+
+## Use Cases
+
+### **Personalized AI Assistants**
+- Remember user preferences and communication style
+- Provide contextually relevant recommendations
+- Maintain conversation continuity across sessions
+
+### **Educational Platforms** 
+- Track learning progress and knowledge gaps
+- Personalize curriculum based on user background
+- Remember previous explanations and adjust complexity
+
+### **Customer Support**
+- Recall customer history and preferences
+- Provide consistent experience across interactions
+- Reduce repetitive information gathering
+
+### **Content Creation**
+- Remember brand voice and style preferences
+- Maintain consistency in generated content
+- Learn from user feedback and corrections
+
+## Benefits
+
+✅ **Enhanced User Experience** - Personalized, context-aware responses  
+✅ **Privacy Protection** - Stores insights, not raw conversations  
+✅ **Easy Integration** - Drop-in replacement for existing OpenAI code  
+✅ **Multi-Provider Support** - Choose the best model for each task  
+✅ **Scalable Architecture** - Built for production environments  
+✅ **Session Security** - JWT-based authentication and user isolation  
+
+## Components
+
+- **OnairosClient** - Main SDK interface with RAG capabilities
+- **LLMWrapper** - Unified API for multiple LLM providers  
+- **MemoryManager** - Vector storage and retrieval system
+- **SessionManager** - JWT authentication and user management
+- **extractMemory** - Intelligent memory extraction utilities
+
+## Getting Started
+
+Ready to add memory to your AI applications? Check out our [complete documentation](https://docs.onairos.uk) and [API reference](https://docs.onairos.uk/api) to get started.
+
+For support, visit [support@onairos.uk](mailto:support@onairos.uk) or our [GitHub repository](https://github.com/zd819/onairos-npm). 

package/POPUP_IMPLEMENTATION_README.md

@@ -0,0 +1,252 @@
+# 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