onairos 2.2.1 → 2.3.1

package/dist/onairos-laravel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onairos-laravel.js","mappings":"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","sources":["webpack://OnairosLaravel/webpack/universalModuleDefinition","webpack://OnairosLaravel/webpack/bootstrap","webpack://OnairosLaravel/webpack/runtime/define property getters","webpack://OnairosLaravel/webpack/runtime/hasOwnProperty shorthand","webpack://OnairosLaravel/webpack/runtime/make namespace object","webpack://OnairosLaravel/./src/laravel/blade-helpers.js"],"sourcesContent":["(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine(\"OnairosLaravel\", [], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"OnairosLaravel\"] = factory();\n\telse\n\t\troot[\"OnairosLaravel\"] = factory();\n})(this, () => {\nreturn ","// The require scope\nvar __webpack_require__ = {};\n\n","// define getter functions for harmony exports\n__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n\t\t}\n\t}\n};","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};","/**\r\n * Onairos Laravel Blade Integration Helpers\r\n * \r\n * This file provides utilities for integrating Onairos components\r\n * directly in PHP Blade templates without requiring React setup.\r\n */\r\n\r\n// Global Onairos instance for Blade templates\r\nlet onairosInstance = null;\r\n\r\n/**\r\n * Initialize Onairos for Blade template usage\r\n * @param {Object} config - Global configuration\r\n */\r\nexport function initializeOnairosForBlade(config = {}) {\r\n  const defaultConfig = {\r\n    apiKey: null,\r\n    baseUrl: 'https://api2.onairos.uk',\r\n    testMode: false,\r\n    autoDetectMobile: true,\r\n    globalStyles: true\r\n  };\r\n\r\n  window.OnairosConfig = { ...defaultConfig, ...config };\r\n  \r\n  // Inject global styles if enabled\r\n  if (window.OnairosConfig.globalStyles) {\r\n    injectOnairosStyles();\r\n  }\r\n\r\n  // Initialize mobile detection\r\n  window.OnairosUtils = {\r\n    isMobile: detectMobileDevice(),\r\n    detectMobile: detectMobileDevice\r\n  };\r\n\r\n  console.log('🔥 Onairos initialized for Laravel Blade templates');\r\n}\r\n\r\n/**\r\n * Create an Onairos button element that can be used in Blade templates\r\n * @param {string} targetElementId - ID of the element to mount to\r\n * @param {Object} options - Onairos button options\r\n */\r\nexport function createOnairosButton(targetElementId, options = {}) {\r\n  const element = document.getElementById(targetElementId);\r\n  if (!element) {\r\n    console.error(`❌ Element with ID \"${targetElementId}\" not found`);\r\n    return;\r\n  }\r\n\r\n  const defaultOptions = {\r\n    requestData: ['email', 'profile'],\r\n    webpageName: 'Laravel App',\r\n    testMode: window.OnairosConfig?.testMode || false,\r\n    autoFetch: true,\r\n    buttonType: 'pill',\r\n    textColor: 'black'\r\n  };\r\n\r\n  const config = { ...defaultOptions, ...options };\r\n\r\n  // Create button HTML\r\n  element.innerHTML = `\r\n    <div class=\"onairos-button-container\">\r\n      <button \r\n        id=\"${targetElementId}-btn\" \r\n        class=\"onairos-btn onairos-btn-${config.buttonType}\"\r\n        data-onairos-config='${JSON.stringify(config)}'\r\n      >\r\n        <span class=\"onairos-btn-text\" style=\"color: ${config.textColor}\">\r\n          Connect with Onairos\r\n        </span>\r\n        <span class=\"onairos-btn-loading\" style=\"display: none;\">\r\n          Loading...\r\n        </span>\r\n      </button>\r\n    </div>\r\n  `;\r\n\r\n  // Add event listener\r\n  const button = document.getElementById(`${targetElementId}-btn`);\r\n  button.addEventListener('click', () => handleOnairosButtonClick(config));\r\n}\r\n\r\n/**\r\n * Handle Onairos button click in Blade context\r\n * @param {Object} config - Button configuration\r\n */\r\nfunction handleOnairosButtonClick(config) {\r\n  // For Blade templates, we'll use the popup/iframe approach\r\n  if (window.OnairosUtils.isMobile) {\r\n    handleMobileFlow(config);\r\n  } else {\r\n    handleDesktopFlow(config);\r\n  }\r\n}\r\n\r\n/**\r\n * Handle mobile OAuth flow (redirect-based)\r\n * @param {Object} config - Configuration\r\n */\r\nfunction handleMobileFlow(config) {\r\n  const authUrl = buildAuthUrl(config);\r\n  window.location.href = authUrl;\r\n}\r\n\r\n/**\r\n * Handle desktop OAuth flow (popup-based)\r\n * @param {Object} config - Configuration\r\n */\r\nfunction handleDesktopFlow(config) {\r\n  const authUrl = buildAuthUrl(config);\r\n  \r\n  const popup = window.open(\r\n    authUrl,\r\n    'onairosAuth',\r\n    'width=450,height=700,scrollbars=yes,resizable=yes'\r\n  );\r\n\r\n  if (popup) {\r\n    const checkClosed = setInterval(() => {\r\n      if (popup.closed) {\r\n        clearInterval(checkClosed);\r\n        handleAuthComplete(config);\r\n      }\r\n    }, 1000);\r\n  }\r\n}\r\n\r\n/**\r\n * Build authentication URL for OAuth flow\r\n * @param {Object} config - Configuration\r\n * @returns {string} Auth URL\r\n */\r\nfunction buildAuthUrl(config) {\r\n  const baseUrl = window.OnairosConfig.baseUrl;\r\n  const params = new URLSearchParams({\r\n    webpageName: config.webpageName,\r\n    requestData: JSON.stringify(config.requestData),\r\n    testMode: config.testMode,\r\n    returnUrl: window.location.href\r\n  });\r\n  \r\n  return `${baseUrl}/auth/laravel?${params.toString()}`;\r\n}\r\n\r\n/**\r\n * Handle authentication completion\r\n * @param {Object} config - Configuration\r\n */\r\nfunction handleAuthComplete(config) {\r\n  if (config.onComplete && typeof config.onComplete === 'function') {\r\n    config.onComplete({\r\n      success: true,\r\n      timestamp: new Date().toISOString()\r\n    });\r\n  }\r\n  \r\n  // Trigger custom event for Laravel apps to listen to\r\n  const event = new CustomEvent('onairosAuthComplete', {\r\n    detail: { config, success: true }\r\n  });\r\n  window.dispatchEvent(event);\r\n}\r\n\r\n/**\r\n * Detect if device is mobile\r\n * @returns {boolean}\r\n */\r\nfunction detectMobileDevice() {\r\n  return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) ||\r\n         (window.innerWidth <= 768);\r\n}\r\n\r\n/**\r\n * Inject Onairos styles into the page\r\n */\r\nfunction injectOnairosStyles() {\r\n  if (document.getElementById('onairos-styles')) return;\r\n\r\n  const styles = `\r\n    <style id=\"onairos-styles\">\r\n      .onairos-button-container {\r\n        display: inline-block;\r\n        margin: 10px 0;\r\n      }\r\n      \r\n      .onairos-btn {\r\n        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\r\n        border: none;\r\n        border-radius: 25px;\r\n        padding: 12px 24px;\r\n        color: white;\r\n        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\r\n        font-size: 14px;\r\n        font-weight: 600;\r\n        cursor: pointer;\r\n        transition: all 0.3s ease;\r\n        box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);\r\n      }\r\n      \r\n      .onairos-btn:hover {\r\n        transform: translateY(-2px);\r\n        box-shadow: 0 6px 20px rgba(102, 126, 234, 0.6);\r\n      }\r\n      \r\n      .onairos-btn-pill {\r\n        border-radius: 25px;\r\n      }\r\n      \r\n      .onairos-btn-icon {\r\n        border-radius: 50%;\r\n        width: 45px;\r\n        height: 45px;\r\n        padding: 0;\r\n        display: flex;\r\n        align-items: center;\r\n        justify-content: center;\r\n      }\r\n      \r\n      .onairos-btn-loading {\r\n        color: #888;\r\n      }\r\n      \r\n      @media (max-width: 768px) {\r\n        .onairos-btn {\r\n          width: 100%;\r\n          padding: 15px 20px;\r\n          font-size: 16px;\r\n        }\r\n      }\r\n    </style>\r\n  `;\r\n  \r\n  document.head.insertAdjacentHTML('beforeend', styles);\r\n}\r\n\r\n/**\r\n * Laravel Blade template directive helper\r\n * Usage in Blade: @onairos(['requestData' => ['email'], 'webpageName' => 'My App'])\r\n */\r\nexport function renderOnairosDirective(options = {}) {\r\n  const elementId = `onairos-${Math.random().toString(36).substr(2, 9)}`;\r\n  \r\n  return `\r\n    <div id=\"${elementId}\"></div>\r\n    <script>\r\n      document.addEventListener('DOMContentLoaded', function() {\r\n        if (window.createOnairosButton) {\r\n          window.createOnairosButton('${elementId}', ${JSON.stringify(options)});\r\n        }\r\n      });\r\n    </script>\r\n  `;\r\n}\r\n\r\n// Expose functions globally for Blade template access\r\nif (typeof window !== 'undefined') {\r\n  window.initializeOnairosForBlade = initializeOnairosForBlade;\r\n  window.createOnairosButton = createOnairosButton;\r\n  window.renderOnairosDirective = renderOnairosDirective;\r\n} "],"names":["root","factory","exports","module","define","amd","this","__webpack_require__","definition","key","o","Object","defineProperty","enumerable","get","obj","prop","prototype","hasOwnProperty","call","Symbol","toStringTag","value","initializeOnairosForBlade","config","arguments","length","undefined","window","OnairosConfig","_objectSpread","apiKey","baseUrl","testMode","autoDetectMobile","globalStyles","document","getElementById","styles","head","insertAdjacentHTML","injectOnairosStyles","OnairosUtils","isMobile","detectMobileDevice","detectMobile","console","log","createOnairosButton","targetElementId","_window$OnairosConfig","options","element","error","concat","requestData","webpageName","autoFetch","buttonType","textColor","innerHTML","JSON","stringify","addEventListener","authUrl","buildAuthUrl","location","href","handleMobileFlow","popup","open","checkClosed","setInterval","closed","clearInterval","onComplete","success","timestamp","Date","toISOString","event","CustomEvent","detail","dispatchEvent","handleAuthComplete","handleDesktopFlow","handleOnairosButtonClick","params","URLSearchParams","returnUrl","toString","test","navigator","userAgent","innerWidth","renderOnairosDirective","elementId","Math","random","substr"],"sourceRoot":""}

package/laravel.txt

@@ -0,0 +1,430 @@
+# Onairos NPM Package - Laravel Integration Context
+
+## Laravel Integration Overview
+- **Package Version**: 2.2.1+
+- **Laravel Support**: Laravel 9+ with Vite
+- **Integration Types**: Blade Templates, Vue.js, React, Mixed Approaches
+- **Build System**: Vite with custom plugins
+- **Mobile Support**: Auto-detection with responsive OAuth flows
+
+## Key Laravel-Specific Features ✅
+1. **Blade Template Integration**: Direct PHP template support without React setup
+2. **Vite Plugin System**: Custom plugins for Laravel, Vue, and React optimization
+3. **Multi-Framework Support**: Seamless Vue.js and React integration within Laravel
+4. **Mobile-First Design**: Automatic mobile detection with appropriate OAuth flows
+5. **Laravel Backend Integration**: PHP controllers and route handlers
+6. **Production Optimization**: Laravel-specific build and deployment strategies
+
+## Laravel Integration Architecture ✅
+
+### Entry Points
+- **Main Package**: `onairos` (standard React components)
+- **Laravel Blade**: `onairos/blade` (vanilla JS helpers)
+- **Vite Plugin**: `onairos/vite-plugin` (build-time optimization)
+- **Vue Component**: `onairos/src/laravel/OnairosVue.vue` (Vue 3 SFC)
+
+### Build Targets
+- **UMD Bundle**: `dist/onairos.bundle.js` (browser globals)
+- **ES Module**: `dist/onairos.esm.js` (modern imports)
+- **Laravel Specific**: `dist/onairos-laravel.js` (Blade helpers)
+
+## Integration Approaches ✅
+
+### 1. Blade Templates (PHP-Focused)
+**Use Case**: Traditional Laravel apps with minimal JavaScript
+**Technology Stack**: PHP Blade + Vanilla JS + Tailwind CSS
+
+**Implementation**:
+```javascript
+// Vite plugin handles build-time optimization
+onairosLaravelPlugin({
+  bladeSupport: true,      // Watch .blade.php files
+  injectGlobals: true,     // Auto-inject helpers
+  optimizeDeps: true,      // Optimize for Laravel
+  enableHMR: true          // Hot module replacement
+})
+```
+
+**Runtime Flow**:
+1. `initializeOnairosForBlade()` sets up global configuration
+2. `createOnairosButton()` generates DOM elements with event handlers
+3. Mobile detection switches between popup/redirect OAuth flows
+4. Custom events communicate with Laravel backend
+
+### 2. Vue.js Integration
+**Use Case**: Laravel apps using Vue.js as primary frontend
+**Technology Stack**: PHP Blade + Vue 3 + Composition API + Vite
+
+**Implementation**:
+```javascript
+// Specialized Vue plugin with auto-imports
+onairosVuePlugin({
+  autoImport: true,        // Auto-import OnairosButton in .vue files
+  optimizeDeps: true       // Optimize Vue + Onairos dependencies
+})
+```
+
+**Component Architecture**:
+- **OnairosVue.vue**: Complete Vue 3 component with Composition API
+- **Props System**: Vue-style props with validation and defaults
+- **Event System**: Vue custom events (@complete, @error, @loading)
+- **Reactive State**: Vue reactivity for loading, success, error states
+
+### 3. React Integration
+**Use Case**: Laravel apps using React as primary frontend
+**Technology Stack**: PHP Blade + React 18 + JSX + Vite
+
+**Implementation**:
+```javascript
+// React-specific optimizations
+onairosReactPlugin({
+  autoImport: true,        // Auto-import in .jsx/.tsx files
+  optimizeDeps: true       // Optimize React + Onairos bundle
+})
+```
+
+**Integration Pattern**:
+- Uses existing `OnairosButton` React component
+- Laravel Vite plugin handles React-specific builds
+- Automatic JSX transformation and optimization
+
+## Technical Implementation Details ✅
+
+### Vite Plugin System
+**Core Plugin**: `onairosLaravelPlugin()`
+- **Development**: Injects initialization scripts, enables HMR
+- **Production**: Optimizes bundles, handles asset generation
+- **File Watching**: Watches .blade.php files for changes
+- **Dependency Optimization**: Pre-bundles Onairos for faster dev server
+
+**Specialized Plugins**:
+- `onairosVuePlugin()`: Vue-specific optimizations and auto-imports
+- `onairosReactPlugin()`: React-specific optimizations and auto-imports
+
+### Mobile Detection & OAuth Flow
+```javascript
+// Automatic mobile detection
+const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) || (window.innerWidth <= 768);
+
+// OAuth flow selection
+if (isMobile) {
+  // Redirect-based flow for mobile browsers
+  window.location.href = authUrl;
+} else {
+  // Popup-based flow for desktop
+  window.open(authUrl, 'onairosAuth', 'width=450,height=700');
+}
+```
+
+### Laravel Backend Integration
+```php
+// Example Laravel controller
+class OnairosController extends Controller {
+    public function callback(Request $request) {
+        $data = $request->validate([
+            'user_hash' => 'required|string',
+            'connections' => 'required|array',
+            'data_types' => 'required|array'
+        ]);
+        
+        auth()->user()->update([
+            'onairos_hash' => $data['user_hash'],
+            'onairos_connections' => $data['connections']
+        ]);
+        
+        return response()->json(['success' => true]);
+    }
+}
+```
+
+## Differences from Standard Integration ✅
+
+### 1. Build System Integration
+**Standard**: Uses webpack UMD build for browser globals
+**Laravel**: Custom Vite plugins with Laravel-specific optimizations
+
+### 2. Component Rendering
+**Standard**: React components mounted via ReactDOM
+**Laravel Blade**: Vanilla JS functions that generate DOM elements
+**Laravel Vue**: Native Vue 3 single-file components
+**Laravel React**: React components optimized for Laravel Vite
+
+### 3. State Management
+**Standard**: React state hooks and context
+**Laravel Blade**: Global window objects and DOM manipulation
+**Laravel Vue**: Vue 3 Composition API with reactive refs
+**Laravel React**: React hooks within Laravel ecosystem
+
+### 4. OAuth Flow Handling
+**Standard**: Hardcoded popup approach
+**Laravel**: Environment-aware with automatic mobile detection
+- Desktop: Popup windows
+- Mobile: Redirect-based flow with return URL handling
+
+### 5. Styling Integration
+**Standard**: Inline styles and CSS-in-JS
+**Laravel**: 
+- Tailwind CSS integration out of the box
+- Scoped Vue styles for Vue components
+- Laravel Mix/Vite asset compilation
+- Global CSS injection for Blade templates
+
+### 6. Development Experience
+**Standard**: Create React App or manual webpack setup
+**Laravel**: 
+- Vite HMR with Blade file watching
+- Automatic dependency optimization
+- Laravel-specific error handling and debugging
+- Integration with Laravel development tools
+
+## Package Structure Changes ✅
+
+### New Files Added
+```
+src/laravel/
+├── blade-helpers.js         # Vanilla JS helpers for Blade templates
+├── vite-plugin.js          # Custom Vite plugins for Laravel
+└── OnairosVue.vue          # Vue 3 component for Laravel
+
+LARAVEL_INTEGRATION_GUIDE.md # Comprehensive integration guide
+laravel.txt                  # This context file
+```
+
+### Package.json Exports
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/onairos.esm.js",
+      "require": "./dist/onairos.bundle.js",
+      "browser": "./dist/onairos.bundle.js"
+    },
+    "./laravel": {
+      "import": "./dist/onairos.laravel.js",
+      "require": "./dist/onairos.laravel.js"
+    },
+    "./blade": "./src/laravel/blade-helpers.js",
+    "./vite-plugin": "./src/laravel/vite-plugin.js"
+  }
+}
+```
+
+### Webpack Configuration
+```javascript
+// Laravel-specific build target
+{
+  entry: {
+    'onairos-laravel': path.resolve(__dirname, 'src', 'laravel', 'blade-helpers.js')
+  },
+  output: {
+    filename: '[name].js',
+    libraryTarget: 'umd',
+    library: 'OnairosLaravel'
+  }
+}
+```
+
+## Developer Experience Improvements ✅
+
+### 1. Installation Simplicity
+```bash
+# Single package for all Laravel integration types
+npm install onairos
+
+# Optional: Framework-specific plugins
+npm install --save-dev @vitejs/plugin-vue      # For Vue
+npm install --save-dev @vitejs/plugin-react    # For React
+```
+
+### 2. Configuration Patterns
+**Blade Only**:
+```javascript
+// Minimal setup
+onairosLaravelPlugin({ bladeSupport: true })
+```
+
+**Vue Integration**:
+```javascript
+// Vue + Laravel optimization
+plugins: [laravel(), vue(), onairosVuePlugin()]
+```
+
+**React Integration**:
+```javascript
+// React + Laravel optimization  
+plugins: [laravel(), react(), onairosReactPlugin()]
+```
+
+### 3. Environment Configuration
+```env
+# Laravel .env integration
+VITE_ONAIROS_API_KEY=your_api_key
+VITE_ONAIROS_TEST_MODE=true
+VITE_ONAIROS_BASE_URL=https://api2.onairos.uk
+```
+
+### 4. Debug and Development
+```javascript
+// Enhanced debugging for Laravel
+initializeOnairosForBlade({
+  debug: true,                    // Enable console logging
+  testMode: import.meta.env.DEV,  // Auto-detect dev environment
+  autoDetectMobile: true          // Mobile detection logging
+});
+```
+
+## Production Deployment ✅
+
+### 1. Build Process
+```bash
+# Laravel standard build
+npm run build
+
+# Generates optimized bundles:
+# - dist/onairos.bundle.js (UMD)
+# - dist/onairos.esm.js (ES modules)
+# - dist/onairos-laravel.js (Laravel-specific)
+```
+
+### 2. Laravel Optimization
+```php
+// Laravel production commands
+php artisan optimize        # Route/config caching
+php artisan view:cache     # Blade template caching
+php artisan config:cache   # Environment caching
+```
+
+### 3. CDN Integration
+```env
+# Laravel asset CDN
+ASSET_URL=https://your-cdn.com
+
+# Automatic asset URL prefixing
+# https://your-cdn.com/build/assets/onairos-laravel.abc123.js
+```
+
+## Testing Strategy ✅
+
+### 1. Unit Tests
+- Laravel Blade helpers functionality
+- Vue component props and events
+- Vite plugin configuration
+- Mobile detection logic
+
+### 2. Integration Tests
+- Laravel controller callbacks
+- OAuth flow completion
+- Database integration
+- Environment variable handling
+
+### 3. End-to-End Tests
+- Full Laravel application flows
+- Mobile and desktop OAuth
+- Vue/React component integration
+- Production build verification
+
+## Known Laravel-Specific Considerations ✅
+
+### 1. CSRF Protection
+Laravel CSRF tokens are automatically handled in AJAX requests when using Laravel's default Axios configuration.
+
+### 2. Route Caching
+OAuth callback routes must be registered before route caching in production.
+
+### 3. Session Management
+Laravel sessions are used for OAuth state management alongside Onairos user hashes.
+
+### 4. Middleware Integration
+Custom Laravel middleware can be created to handle Onairos authentication states.
+
+### 5. Queue Integration
+Heavy OAuth processing can be queued using Laravel's queue system for better performance.
+
+## Migration from Standard Integration ✅
+
+### For Existing React Users
+- No changes needed to existing React components
+- Optional: Add Laravel Vite plugin for optimization
+- Optional: Use Laravel backend integration features
+
+### For New Laravel Projects
+- Choose integration approach (Blade/Vue/React)
+- Install appropriate Vite plugins
+- Follow Laravel-specific setup guide
+- Configure environment variables
+
+### For Hybrid Approaches
+- Mix Blade templates with Vue/React components
+- Use different integration methods in different parts of the app
+- Leverage Laravel's flexibility for gradual adoption
+
+## Performance Considerations ✅
+
+### 1. Bundle Size Optimization
+- Vite plugins optimize bundle splitting
+- Laravel-specific builds exclude unnecessary dependencies
+- Tree-shaking removes unused code
+
+### 2. Loading Performance
+- Lazy loading for Vue/React components
+- Preloading critical OAuth dependencies
+- Service worker integration for offline capability
+
+### 3. Mobile Performance
+- Automatic redirect vs popup optimization
+- Touch-friendly UI components
+- Reduced JavaScript payload for mobile
+
+## Troubleshooting Guide ✅
+
+### Common Issues
+
+1. **Vite Plugin Not Working**
+   - Clear Vite cache: `rm -rf node_modules/.vite`
+   - Check plugin order in vite.config.js
+   - Verify import paths
+
+2. **Blade Helpers Unavailable**
+   - Ensure `initializeOnairosForBlade()` is called
+   - Check browser console for initialization errors
+   - Verify script loading order
+
+3. **Vue Component Not Rendering**
+   - Confirm Vue 3 is properly installed
+   - Check component registration
+   - Verify Vite Vue plugin configuration
+
+4. **Mobile OAuth Issues**
+   - Test popup blockers disabled
+   - Verify redirect URLs are whitelisted
+   - Check mobile user agent detection
+
+### Debug Commands
+```javascript
+// Check initialization status
+console.log(typeof window.createOnairosButton); // Should be "function"
+console.log(typeof window.OnairosConfig);       // Should be "object"
+
+// Test mobile detection
+console.log(window.OnairosUtils.isMobile);      // Boolean
+
+// Verify Vite environment
+console.log(import.meta.env.DEV);               // Development mode
+console.log(import.meta.env.VITE_ONAIROS_*);    // Environment variables
+```
+
+## Future Laravel Enhancements 🚀
+
+### Planned Features
+1. **Artisan Commands**: CLI commands for setup and configuration
+2. **Laravel Packages**: Composer package for PHP-side integration
+3. **Blade Directives**: Custom `@onairos` Blade directive
+4. **Middleware Package**: Pre-built authentication middleware
+5. **Model Traits**: Eloquent traits for user Onairos data
+6. **Testing Helpers**: Laravel testing utilities for Onairos
+
+### Experimental Features
+1. **Server-Side Rendering**: Laravel + Inertia.js SSR support
+2. **API Resource Integration**: Laravel API resource transformers
+3. **Livewire Components**: Native Livewire component integration
+4. **Laravel Sail**: Docker development environment support 

package/llm.txt

@@ -13,6 +13,7 @@
 4. **API Integration**: Supports both test/live modes with automatic endpoint switching
 5. **PIN-based Encryption**: All models encrypted with user PIN + server key
 6. **Responsive Design**: Tailwind CSS with mobile-first approach
+7. **API Key Initialization**: Developer API key setup for authentication and environment configuration
 
 ## Mobile Browser Compatibility ✅
 **WORKS PERFECTLY**: React components, API calls, touch interactions, responsive design, state management
@@ -42,7 +43,7 @@
 - **Training Routes**: `api2.onairos.uk/mobile-training/clean` (regular) or `/enoch` (advanced)
 
 ## Data Flow
-1. **Email Authentication** → 2. **OAuth Connections** → 3. **PIN Setup** → 4. **Data Request**
+1. **API Key Initialization** → 2. **Email Authentication** → 3. **OAuth Connections** → 4. **PIN Setup** → 5. **Data Request**
 
 **Backend Format**:
 ```json
@@ -57,7 +58,27 @@
 }
 ```
 
+## API Key Setup ✅
+**CRITICAL**: Must initialize API key before using any Onairos components
+
+```javascript
+import { initializeApiKey } from '@onairos/react-native';
+
+// Initialize with developer key
+await initializeApiKey({
+  apiKey: 'dev_your_32_char_key_here',
+  environment: 'production', // or 'development'
+  enableLogging: true
+});
+```
+
+**Configuration Options**:
+- `apiKey`: Your 32-character developer key (format: `dev_your_32_char_key_here`)
+- `environment`: `'production'` or `'development'` mode
+- `enableLogging`: Boolean for debug logging
+
 ## Key Components
+- **initializeApiKey**: API key setup function (must be called first)
 - **OnairosButton**: Main entry point with props (testMode, autoFetch, requestData)
 - **UniversalOnboarding**: OAuth connector management with mobile detection
 - **DataRequest**: Data type selection with visual checkmarks
@@ -81,8 +102,25 @@
 ✅ Enhanced OAuth URL parsing for all 9 platforms
 ✅ Added mobile browser compatibility documentation
 ✅ Fixed OAuth popup blocking on mobile devices
+✅ Added API key initialization system for developer authentication
+✅ Implemented environment-specific configuration (production/development)
+✅ Added comprehensive logging system for debugging
+✅ Fixed TypeScript declaration file resolution issue in package.json exports
 
 ## Usage Pattern
+**Step 1: Initialize API Key (Required)**
+```javascript
+import { initializeApiKey } from '@onairos/react-native';
+
+// Must be called before using any components
+await initializeApiKey({
+  apiKey: 'dev_your_32_char_key_here',
+  environment: 'production',
+  enableLogging: true
+});
+```
+
+**Step 2: Use Onairos Components**
 ```javascript
 import { OnairosButton } from 'onairos';
 
@@ -100,14 +138,47 @@ import { OnairosButton } from 'onairos';
 ```
 
 ## Critical Success Factors
-1. **Cross-Platform**: Same React code works in desktop browsers, mobile browsers, and React Native
-2. **OAuth Reliability**: Auto-detects environment and uses appropriate OAuth flow
-3. **API Consistency**: All endpoints use `api2.onairos.uk` with proper authentication
-4. **Mobile UX**: Touch-friendly UI with proper viewport handling
-5. **Error Handling**: Comprehensive error states and user guidance
+1. **API Key Setup**: Must call `initializeApiKey()` before using any components
+2. **Cross-Platform**: Same React code works in desktop browsers, mobile browsers, and React Native
+3. **OAuth Reliability**: Auto-detects environment and uses appropriate OAuth flow
+4. **API Consistency**: All endpoints use `api2.onairos.uk` with proper authentication
+5. **Mobile UX**: Touch-friendly UI with proper viewport handling
+6. **Error Handling**: Comprehensive error states and user guidance
+
+## TypeScript Support ✅
+**Full TypeScript Support**: Complete type definitions provided in `onairos.d.ts`
+
+**Usage with TypeScript**:
+```typescript
+import { OnairosButton } from 'onairos';
+import type { OnairosProps } from 'onairos';
+
+// Component usage with full type safety
+const MyComponent: React.FC = () => {
+  return (
+    <OnairosButton
+      requestData={{
+        basic: { type: "basic", reward: "10 tokens" },
+        personality: { type: "personality", reward: "25 tokens" }, 
+        preferences: { type: "preferences", reward: "15 tokens" }
+      }}
+      webpageName="MyApp"
+      testMode={false}
+      autoFetch={true}
+      onComplete={(result) => console.log(result)}
+    />
+  );
+};
+```
+
+**Common TypeScript Issues & Solutions**:
+- **"Could not find declaration file"**: Fixed in v2.1.5 by adding `types` field to package.json exports
+- **Import errors**: Always import from `'onairos'` (not specific paths)
+- **Type inference**: All components have full TypeScript support with IntelliSense
 
 ## Build & Development
 - **Build**: `npm run build` (creates dist/ folder)
 - **Test Files**: Multiple test HTML files for different scenarios
 - **Entry Points**: `src/index.js` (main), `src/onairos.native.jsx` (React Native)
-- **Responsive**: Tailwind CSS with `sm:`, `md:`, `lg:` breakpoints throughout 
+- **Responsive**: Tailwind CSS with `sm:`, `md:`, `lg:` breakpoints throughout
+- **TypeScript**: Full type definitions with proper package.json exports configuration 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onairos",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "dependencies": {
     "@react-oauth/google": "^0.12.1",
     "@telegram-apps/sdk-react": "^2.0.25",
@@ -24,6 +24,10 @@
     "copy-assets": "echo 'Assets copied by webpack'",
     "dev": "webpack --mode development --watch",
     "test": "react-scripts test",
+    "test:laravel": "vitest run --config tests/laravel/vitest.config.js",
+    "test:laravel:watch": "vitest --config tests/laravel/vitest.config.js",
+    "test:laravel:ui": "vitest --ui --config tests/laravel/vitest.config.js",
+    "test:all": "npm run test && npm run test:laravel",
     "eject": "react-scripts eject"
   },
   "eslintConfig": {
@@ -60,6 +64,8 @@
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-typescript": "^12.1.2",
+    "@vitejs/plugin-vue": "^5.0.4",
+    "@vue/test-utils": "^2.4.4",
     "assert": "^2.1.0",
     "babel-loader": "^9.2.1",
     "browserify-zlib": "^0.2.0",
@@ -68,6 +74,7 @@
     "file-loader": "^6.2.0",
     "html-webpack-plugin": "^5.6.3",
     "https-browserify": "^1.0.0",
+    "jsdom": "^24.0.0",
     "lucide-react": "^0.503.0",
     "os-browserify": "^0.3.0",
     "path-browserify": "^1.0.1",
@@ -78,7 +85,9 @@
     "tailwindcss": "^3.3.5",
     "terser-webpack-plugin": "^5.3.10",
     "url": "^0.11.4",
+    "vitest": "^1.2.0",
     "vm-browserify": "^1.1.2",
+    "vue": "^3.4.15",
     "webpack": "^5.89.0",
     "webpack-bundle-analyzer": "^4.10.1",
     "webpack-cli": "^5.1.4"
@@ -96,6 +105,22 @@
   "types": "onairos.d.ts",
   "browser": "dist/onairos.bundle.js",
   "react-native": "dist/onairos.native.js",
+  "laravel": "dist/onairos.laravel.js",
+  "exports": {
+    ".": {
+      "types": "./onairos.d.ts",
+      "import": "./dist/onairos.esm.js",
+      "require": "./dist/onairos.bundle.js",
+      "browser": "./dist/onairos.bundle.js"
+    },
+    "./laravel": {
+      "types": "./onairos.d.ts",
+      "import": "./dist/onairos.laravel.js",
+      "require": "./dist/onairos.laravel.js"
+    },
+    "./blade": "./src/laravel/blade-helpers.js",
+    "./vite-plugin": "./src/laravel/vite-plugin.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zd819/onairos-npm"
@@ -105,7 +130,13 @@
     "Identity",
     "Authentication",
     "Data-Sharing",
-    "Privacy"
+    "Privacy",
+    "Laravel",
+    "Vite",
+    "Blade",
+    "Vue",
+    "React",
+    "PHP"
   ],
   "author": "Zion Darko",
   "license": "Apache-2.0",