simplici_auth 1.5.9

A Flutter package for integrating SimpliciAuth with Google OAuth in Flutter applications. Provides webview-based authentication with customizable configuration and comprehensive OAuth handling.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.6.7 - 2025-01-19

Added

• 🔧 SSO User Data Integration: Automatically sets sso_user_data attribute on webcomponent with extracted user information (email, firstName, lastName, userId)
• 🎯 Smart Data Mapping: Extracts specific fields from exchangeWebCode response and maps them to webcomponent-friendly format
• 🔄 Auto Popup Closing: Automatically closes popup browser after successful SSO authentication or on errors
• 📡 Custom Event Dispatch: Dispatches sso_data_updated custom event to notify webcomponent of new SSO data
• 👤 Graceful Manual Cancellation: Handles manual browser closing without navigating away from current page

Enhanced

• 🎛️ Webcomponent Communication: Sets both attribute and property on simplici-auth element for immediate data access
• 🚫 Non-disruptive Cancellation: User can manually close SSO popup without triggering unwanted page navigation
• 📋 Error Code Support: Includes errorCode in sso_user_data when authentication fails

Fixed

• ✅ Popup Browser Lifecycle: Proper closing of popup browser after authentication completion
• ✅ User Experience: Maintains current page state when user cancels SSO authentication manually
• ✅ Data Persistence: Ensures SSO user data is properly set on webcomponent for immediate use

1.6.6 - 2025-01-19

Added

• 🚀 Direct Dart Implementation: Implemented exchangeWebCode method directly in Dart using HTTP requests, eliminating JavaScript dependency
• 🔧 Native HTTP Calls: Replaced JavaScript window.handleHooks with native Flutter HTTP requests to https://authentication.stage.satschel.com/oauth
• 📡 Enhanced Error Handling: Added comprehensive error handling with detailed logging for HTTP responses and JSON parsing

Removed

• ❌ JavaScript Dependencies: Completely removed window.handleHooks JavaScript injection mechanism
• ❌ Static Controller Reference: Removed static webview controller reference as it's no longer needed
• ❌ Complex JavaScript Bridge: Eliminated complex JavaScript-to-Dart communication bridge

Fixed

• ✅ Reliable Code Exchange: Fixed unreliable exchangeWebCode execution by implementing it natively in Dart
• ✅ Synchronous Execution: Ensured exchangeWebCode executes reliably without JavaScript injection issues

1.6.5 - 2025-01-19

Added

• 🔍 Enhanced JavaScript Debugging: Added comprehensive logging to debug window.handleHooks execution and identify why exchangeWebCode method isn't being called
• Direct Function Fallback: Added fallback mechanism to call window.exchangeWebCode directly if window.handleHooks returns undefined
• Window Function Discovery: Added logging to list available window functions for debugging

Fixed

• 🚀 JavaScript Function Execution: Investigating and fixing issue where exchangeWebCode method exists but isn't being executed properly
• Function Call Debugging: Enhanced error tracking and parameter logging for JavaScript function calls

1.6.4 - 2025-01-19

Changed

• Updated Base URL: Updated default base URL from 9yvsbp-ip-103-217-132-118.tunnelmole.net to v8at4h-ip-103-217-132-118.tunnelmole.net
• Service Endpoint: Updated SimpliciAuth service endpoint configuration across all files including README, config, and tests
• Documentation: Updated README files to reflect the new tunnelmole endpoint

Fixed

• Service Connectivity: Ensured all references to the base URL are consistent with the new tunnelmole endpoint

1.6.3 - 2025-01-19

Fixed

• 🔥 CRITICAL FIX: JavaScript undefined handling: Fixed window.handleHooks undefined return value causing "JavaScript execution returned a result of an unsupported type" error
• Dynamic Method Name: Fixed hardcoded 'exchangeWebCode' to use dynamic $name variable for all method calls
• JSON Serialization: Added proper JSON.stringify for all JavaScript return values to ensure Flutter compatibility
• Undefined Result Handling: Added explicit handling for undefined/null results from window.handleHooks
• Enhanced Error Logging: Added detailed console logging for debugging JavaScript execution issues

Changed

• JavaScript Return Values: All JavaScript functions now return properly JSON-stringified objects
• Error Response Structure: Standardized error responses with consistent JSON structure
• Debug Output: Enhanced console logging to track JavaScript execution flow and results

1.6.2 - 2025-01-19

Changed

• Updated Base URL: Updated default base URL from u0rknz-ip-103-217-132-225.tunnelmole.net to 9yvsbp-ip-103-217-132-118.tunnelmole.net
• Service Endpoint: Updated SimpliciAuth service endpoint configuration across all files including README, config, and tests
• Documentation: Updated README files to reflect the new tunnelmole endpoint

Fixed

• Service Connectivity: Ensured all references to the base URL are consistent with the new tunnelmole endpoint

1.6.1 - 2025-01-19

Added

• Enhanced Debugging: Added console logging in JavaScript execution to capture window.handleHooks result
• Result Logging: Added console.log('🔍 handleHooks result yeah :', result) to better debug JavaScript function responses

Changed

• JavaScript Result Handling: Store window.handleHooks result in const variable before returning for better debugging visibility
• Console Output: Enhanced logging to track actual JavaScript function return values

1.6.0 - 2025-01-19

Fixed

• 🔥 CRITICAL FIX: Async JavaScript Execution: Fixed window.handleHooks JavaScript execution to properly use async/await
• JavaScript Promise Handling: Changed JavaScript IIFE to async function that awaits the Promise result from window.handleHooks
• Authentication Flow: Fixed authentication callback processing by ensuring JavaScript execution completes properly
• OAuth Integration: Resolved issue where exchangeWebCode was returning null due to improper Promise handling

Changed

• JavaScript Code: Updated _callHandleHooks method to use async function() instead of regular function()
• Promise Resolution: Now properly awaits window.handleHooks function results instead of returning unresolved Promise

1.5.9 - 2025-01-19

Changed

• Updated Base URL: Updated default base URL from verzbu-ip-103-217-132-225.tunnelmole.net to u0rknz-ip-103-217-132-225.tunnelmole.net
• Configuration Update: Updated SimpliciAuth service endpoint configuration across all files
• Documentation: Updated README files to reflect the new base URL

Fixed

• Service Endpoint: Ensured all references to the base URL are consistent across the package

1.5.8 - 2025-01-19

Fixed

• Real JavaScript Integration: exchangeWebCode now makes actual JavaScript calls to window.handleHooks instead of simulated calls
• WebView Controller Access: Added static controller reference to enable JavaScript execution from static methods
• Authentic API Calls: Exchange methods now properly call the JavaScript window.handleHooks function in the webview

Added

• JavaScript Execution: Real JavaScript evaluation in webview for window.handleHooks calls
• Dynamic Result Handling: Proper parsing of JavaScript function results
• Memory Management: Added proper cleanup of static controller references in dispose method

Changed

• _callHandleHooks Implementation: Now executes real JavaScript: window.handleHooks({ name: 'exchangeWebCode', payload: params }, 'login')
• Error Handling: Enhanced error handling for JavaScript execution failures
• Result Processing: Improved handling of JavaScript function return values

1.5.7 - 2025-01-19

Fixed

• Custom URL Scheme Handling: Fixed critical issue where custom URL scheme redirects (like com.googleusercontent.apps.xxx:/oauth/callback) were not being detected
• OAuth Redirect Detection: Updated redirect pattern matching to handle both :/oauth2redirect and :/oauth/callback formats
• WebView Navigation: Added proper handling for custom scheme redirects that prevent WebView navigation errors
• Parameter Extraction: Improved parameter extraction from custom scheme URLs vs standard HTTP URLs
• Code Capture: Fixed the core issue where authorization codes were not being captured from OAuth redirects

Added

• Enhanced Debugging: Added comprehensive logging for navigation requests and auth completion checks
• Custom Scheme Detection: Added navigation delegate to properly handle custom URL schemes
• Better URL Parsing: Added separate parsing logic for custom schemes vs HTTP/HTTPS URLs

Changed

• Navigation Handling: WebView now prevents navigation to custom schemes while still extracting parameters
• Auth Detection Logic: Improved auth completion detection for various redirect URL formats

1.5.6 - 2025-01-19

Fixed

• Provider Detection: Fixed provider extraction from event data to use 'key' field instead of 'provider' field
• Code Retrieval: Restored proper code retrieval functionality that was working in version 1.5.1
• SSO Authentication: Fixed SSO provider identification to properly capture authorization codes
• Internal Browser: Resolved issue where provider was showing as "unknown" during authentication

Changed

• Provider Resolution: Now checks both 'key' and 'provider' fields for provider identification
• Better Compatibility: Improved compatibility with different event data structures

1.5.5 - 2025-01-19

Added

• Alert Dialogs: Added visual alert dialogs for code validation status
• Code Found Alert: Shows "Code Found" alert when authorization code is successfully received
• Code Not Found Alert: Shows "Code Not Found" alert when code does not exist in authentication response
• User-Friendly Notifications: Provides immediate visual feedback to users about authentication status

Changed

• Enhanced User Experience: Users now get immediate visual feedback through alert dialogs
• Improved Error Messaging: Changed "Code is not present" to "Code does not found" for consistency
• Visual Authentication Status: Authentication results are now displayed through native alert dialogs

1.5.3 - 2025-01-19

Added

• Enhanced Code Validation: Added comprehensive code presence validation for all SSO providers
• Detailed Error Messages: Specific error messages when authorization code is missing from provider response
• Success/Error Data Structure: Standardized response format with success flags and descriptive messages

Changed

• Improved SSO Error Handling: Enhanced error reporting to clearly indicate when code is not present in authentication response
• Better Logging: More detailed logging for successful and failed authentication attempts
• Provider-Specific Messages: Error and success messages now include provider name for better debugging

1.5.2 - 2025-01-19

Added

• Universal SSO Support: Added generic SSO provider support for all providers (Google, Facebook, Microsoft, Apple, etc.)
• openSSOBrowser Handler: Added JavaScript handler to trigger SSO authentication from web components
• SSO Internal Browser: Dedicated internal browser handling for any SSO provider URL
• Auto Code/State Capture: Automatic extraction of authorization code and state from redirect URLs
• exchangeWebCode Integration: Seamless integration with exchangeWebCode method for token exchange

Changed

• Enhanced Event Handling: Improved step change event handling to detect SSO provider URLs
• Unified Authentication Flow: Streamlined authentication process for all SSO providers
• Better Error Handling: Enhanced error reporting and logging for SSO authentication flows

1.5.1 - 2025-01-19

Changed

• Configuration Updates: Applied latest changes to configuration settings
• Test Improvements: Enhanced test files with latest updates
• Package Refinements: Applied various improvements and optimizations

1.5.0 - 2025-01-19

Changed

• Major Version Update: Updated to version 1.5.0 with significant improvements
• Enhanced Features: Applied comprehensive updates and refinements
• Improved Stability: Enhanced package stability and performance

1.4.7 - 2025-01-19

Changed

• Latest Updates: Applied latest configuration changes and improvements
• Test Enhancements: Updated test files with latest changes
• Configuration Refinements: Enhanced configuration settings

1.4.6 - 2025-01-19

Changed

• Configuration Update: Updated jsPath configuration documentation for improved clarity
• Package Maintenance: Applied latest configuration updates and improvements

1.4.5 - 2025-01-19

Added

• ExchangeCodeParameter: Added parameter class for exchangeCode method with provider, access_token, code, redirect_url, instanceId, type, and responseType fields
• ExchangeWebCodePayload: Added payload class for exchangeWebCode method with state and code fields
• SimpliciAuthExchange: Added utility class with static methods for handling code exchange operations
• exchangeCode Method: Added method to handle OAuth code exchange with structured parameters
• exchangeWebCode Method: Added method to handle web-based OAuth code exchange

Changed

• API Enhancement: Extended package API to support code exchange functionality for OAuth flows

1.4.4 - 2025-01-19

Changed

• Base URL Update: Updated default base URL to tunnelmole.net endpoint for improved connectivity
• Configuration Enhancement: Enhanced configuration with updated server endpoint

1.4.3 - 2025-01-19

Changed

• Package Updates: Updated package with latest configuration and test improvements
• Version Bump: Incremented version to 1.4.3 for new release

1.4.2 - 2025-01-19

Fixed

• Enhanced handleHooks Implementation: Fixed window.handleHooks returning null with improved Completer pattern
• Platform Detection: Added platform-specific handling for iOS vs Android/Web OAuth flows
• Enhanced User ID Handling: Now prioritizes SimpliciAuth backend userId from handleHooks response
• Better Error Handling: Added timeout handling, cleanup mechanisms, and improved debugging
• Parameter Debugging: Added comprehensive parameter alerts for OAuth callback debugging
• Concurrent Auth Prevention: Added flags to prevent multiple concurrent authentication attempts

Added

• onControllerCreated Callback: Added new configuration callback for webview controller access
• Enhanced Logging: Added detailed debugging logs for authentication flow
• Google-Optimized User Agent: Added specialized user agent for Google OAuth compatibility
• Platform Detection: Added iOS/Android/Web detection for optimal OAuth handling

Changed

• HandleHooks Pattern: Switched from Promise-based to Completer+Callback pattern for better reliability
• User Data Priority: Enhanced user data extraction to prioritize handleHooks response over Google API data
• Authentication Flow: Improved authentication flow with better cleanup and error recovery

1.4.1 - 2025-01-19

Added

• Added debug alert to show complete sso_user_data content for Google authentication
• Fixed syntax error in config file comment formatting

Changed

• Updated package version for official release

1.3.7 - 2025-01-16

Added

• Added debug alert to show complete sso_user_data content for Google authentication
• Fixed syntax error in config file comment formatting

1.3.6 - 2025-01-16

Fixed

• Fixed syntax error in config file comment formatting

1.3.5 - 2025-01-16

Changed

• Updated baseUrl to use development tunnel URL for testing
• Changed jsPath from "/static/js/main.js" to "/static/js/main.js"
• Updated tests to match new configuration values

1.3.4 - 2025-01-16

Fixed

• Fixed handleHooks response returning null by using Promise pattern for better async JavaScript handling
• Fixed hookResult data storage to properly pass handleHooks response data to sso_user_data for Google authentication
• Ensured handleHooks response data is correctly stored as Map object instead of JSON string

1.3.3 - 2025-01-16

Fixed

• Fixed all JavaScript console.log statements to properly stringify objects instead of showing "[object Object]"
• Fixed handleHooks response, Google config, callback functions, and component attributes logging

1.3.2 - 2025-01-16

Changed

• Improved logging consistency by stringifying hookResult in Dart logs and payload in JavaScript console logs

1.3.1 - 2025-01-16

Changed

• Stringify hookResult as JSON string instead of raw Map object for better serialization

1.1.7 - 2025-01-16

Added

• handleHooks integration: Added automatic call to window.handleHooks for Google OAuth authentication
• Hook payload support: Sends complete payload with provider, access_token, code, redirect_url, instanceId, type, and responseType
• Hook response handling: Processes handleHooks response and uses res.data for sso_user_data when available
• Enhanced user data structure: Added redirect_url field and standardized type as 'embeded' for Google OAuth

Changed

• sso_user_data source: Now uses handleHooks response data when available, falling back to standard user data
• Google OAuth type: Changed default type from 'login' to 'embeded' for Google authentication
• Data flow: Enhanced data flow to include handleHooks integration in the authentication process

Improved

• Error handling: Added comprehensive error handling for handleHooks calls
• Logging: Enhanced logging for handleHooks calls and responses
• JavaScript integration: Improved JavaScript execution for hook calls with proper async/await handling

1.1.6 - 2025-01-16

Fixed

• Duplicate callback processing: Added flag to prevent duplicate OAuth callback processing
• False error reporting: Fixed "failed to extract user data" error appearing after successful authentication
• Race condition handling: Improved handling of race conditions between popup closure and callback processing
• Authentication state tracking: Added proper tracking to prevent multiple processing of the same authentication

Changed

• Error reporting logic: Enhanced error reporting to only show errors when authentication hasn't been processed successfully
• Callback flow: Improved OAuth callback flow to reset processing flag on new authentication attempts

1.1.5 - 2025-01-16

Fixed

• WebView disposal error: Fixed "IOSInAppWebViewController was used after being disposed" error for Google OAuth
• Popup closure timing: Added delay before closing popup to allow OAuth callback processing to complete
• Error handling: Enhanced error handling for disposed webview controllers without failing authentication
• Graceful degradation: Authentication flow continues successfully even if sso_user_data UI update fails

Changed

• OAuth callback processing: Improved callback processing to handle webview disposal gracefully
• Error reporting: Changed from throwing exceptions to logging warnings for non-critical webview errors

1.1.4 - 2025-01-16

Added

• Google OAuth iOS scheme handling: Added specific handling for Google OAuth with iOS scheme URLs
• Enhanced Google auth completion: Popup now only closes when OAuth code is received for Google authentication
• Google-specific token logging: Added dedicated logging for Google OAuth access tokens and codes
• iOS redirect URI support: Enhanced iOS scheme redirect URI handling for Google OAuth

Changed

• OAuth completion detection: Modified completion detection to specifically handle Google OAuth redirects with iOS scheme URLs
• Google OAuth flow: Improved Google OAuth flow to use iOS scheme URLs as redirect URIs
• Token exchange logging: Enhanced logging for Google OAuth token exchange with iOS scheme redirect URIs
• Callback processing: Updated callback processing to prioritize Google OAuth code handling

Fixed

• Popup closure timing: Fixed popup closure to only occur when Google OAuth code is received
• iOS scheme URL handling: Fixed iOS scheme URL handling for Google OAuth redirects

1.1.0 - 2025-01-12

1.1.3 - 2025-01-12

Fixed

• Fixed dynamic type parameter handling in user data extraction
• Resolved issue where Google OAuth flow was trying to access non-existent 'type' field from Google API response
• Enhanced type parameter extraction to properly use original OAuth params with fallback to 'login'

1.1.2 - 2025-01-12

Fixed

• Fixed OAuth callback processing to only execute when URL contains actual completion indicators (email, errorCode, userId, etc.)
• Resolved "Failed to extract user data from params" error for intermediate Microsoft OAuth URLs
• Improved auth completion detection to prevent processing of OAuth authorization URLs that don't contain user data

1.1.1 - 2025-01-12

Fixed

• Fixed boolean attributes in webcomponent HTML to properly convert to string values
• Improved compatibility with JavaScript frameworks by explicitly converting boolean values to "true"/"false" strings

Added

• Complete webcomponent props support: Added all missing properties to match the SimpliciAuth webcomponent specification:
  • page: Specify the page to display
  • lang: Language code (e.g., 'en', 'es', 'fr')
  • hideNavigation: Whether to hide navigation elements
  • microsoftRedirectUrl: Microsoft OAuth redirect URL
  • facebookRedirectUrl: Facebook OAuth redirect URL
  • appleRedirectUrl: Apple OAuth redirect URL
  • googleRedirectUrl: Google OAuth redirect URL
  • onLoaded: Callback when component is loaded
• Enhanced configuration: All webcomponent properties now available in SimpliciAuthConfig
• Comprehensive documentation: Updated README with all available properties and their descriptions

Changed

• Major version bump: Significant API expansion with all webcomponent properties now supported
• Improved webcomponent generation: Dynamic attribute generation based on configured properties

1.0.7 - 2025-01-12

Fixed

• Memory leak prevention: Added mounted checks before all setState() calls in PopupBrowser to prevent "setState() called after dispose()" errors
• Widget lifecycle management: Enhanced PopupBrowser disposal handling to prevent callbacks from executing after widget is removed from tree
• Async callback safety: Protected all WebView navigation callbacks (onPageStarted, onPageFinished, onUrlChange) from calling setState on disposed widgets

Security

• Memory safety: Prevents potential memory leaks by properly handling widget lifecycle in popup browser

1.0.6 - 2025-01-12

Fixed

• Webcomponent sso_user_data setting: Properly set sso_user_data directly on the simplici-auth webcomponent element
• Multiple data setting methods: Set sso_user_data as both attribute and property on webcomponent for maximum compatibility
• JSON stringify format: Convert all authentication parameters to proper JSON.stringify format as required
• Event dispatching: Enhanced event dispatching to trigger events both on webcomponent and globally
• Complete data inclusion: Include all authentication parameters in sso_user_data object

Added

• Webcomponent method calling: Call setSSOUserData method on webcomponent if available
• Comprehensive logging: Added detailed logging for webcomponent interaction and data setting
• Error handling: Added try-catch for JavaScript execution to prevent failures

1.0.5 - 2025-01-12

Fixed

• sso_user_data format: Simplified sso_user_data to match original working format with just essential fields (provider, email, firstName, lastName, userId, instanceId, type, responseType)
• Data setting method: Fixed webview data setting to use correct format and trigger proper webcomponent events
• Browser popup closure: Ensured popup browser closes properly after authentication completion
• Event notification: Added proper event dispatching (sso-auth-complete) to notify webcomponent of successful authentication

Changed

• Simplified data structure: Removed complex nested data structures in favor of simple, flat sso_user_data format
• Enhanced event handling: Added multiple event triggers (handleSSOComplete, onAuthenticationComplete, CustomEvent) to ensure webcomponent receives authentication data

1.0.4 - 2025-01-12

Enhanced

• sso_user_data setting: Enhanced and guaranteed sso_user_data setting for ALL authentication providers (Google, Facebook, Apple, etc.)
• Comprehensive logging: Added detailed step-by-step logging for authentication flow and sso_user_data setting process
• Data verification: Added JavaScript-side verification to ensure sso_user_data is properly accessible in webview
• Error handling: Improved error handling with explicit error throwing for sso_user_data setting failures
• Multi-provider support: Ensured consistent sso_user_data format across all OAuth providers

Added

• Provider-specific logging: Each authentication step now logs the provider type for better debugging
• Data accessibility verification: JavaScript verification that sso_user_data is properly set and accessible
• Enhanced completion handlers: Added support for multiple completion callback types (handleAuthCompletion, onSSOComplete)

1.0.3 - 2025-01-12

Fixed

• Direct user data handling: Added support for providers that return user data directly in URL parameters (like Facebook)
• Universal OAuth callback: Enhanced OAuth callback handling to process both token-based flows (Google) and direct data flows (Facebook, etc.)
• Parameter extraction: Improved URL parameter extraction with proper URL decoding for names and special characters
• Auth completion detection: Enhanced popup browser to detect more auth completion URL patterns
• sso_user_data completeness: Ensure all available user information from params is included in sso_user_data

Changed

• OAuth flow flexibility: Support for multiple OAuth response types (code exchange vs direct user data)
• Enhanced parameter parsing: Better handling of URL-encoded parameters and special characters
• Improved debugging: Consistent debug logging across all browser components

1.0.2 - 2025-01-12

Fixed

• Browser UI: Changed from full-screen InternalBrowser to popup-style dialog browser (PopupBrowser) for better user experience
• User data extraction: Added comprehensive user data extraction including firstName, lastName, email, and userId
• sso_user_data: Implemented proper sso_user_data setting in webview with JSON stringified format
• OAuth token exchange: Added complete OAuth flow with token exchange and user info retrieval from Google API
• Auto-close functionality: Browser now automatically closes after successful authentication

Changed

• Authentication flow: Complete OAuth 2.0 flow with proper token exchange and user data retrieval
• Browser style: Popup dialog style instead of full-screen with AppBar for better UX
• Data handling: Comprehensive user data structure with all required fields

1.0.1 - 2025-01-12

Fixed

• onStepChanged URL handling: Restored functionality to automatically open URLs in internal browser when triggered by step change events
• Event data parsing: Improved parsing of step change event data to properly extract URLs and other parameters
• Internal browser integration: Fixed integration with internal browser for OAuth flows
• Google OAuth configuration: Enhanced extraction and handling of Google OAuth configuration from instance details

Changed

• WebView implementation: Updated to use webcomponent HTML generation instead of direct URL loading for better event handling
• Event handlers: Added proper JavaScript handlers for step changes and auth completion events
• Debug logging: Improved debug logging for better troubleshooting of authentication flows

1.0.0 - 2025-01-12

Added

• Initial release of SimpliciAuth Flutter package
• SimpliciAuthWebView: Main widget for displaying authentication interface
• SimpliciAuthConfig: Configuration class with comprehensive customization options
• Cross-platform support: Works on iOS, Android, Web, macOS, Linux, and Windows
• OAuth integration: Complete OAuth 2.0 flow with Google
• Callback support: Multiple callback functions for different authentication events
• Debug mode: Optional debug logging for development
• Custom styling: Support for custom CSS and user agents
• Example app: Complete example demonstrating package usage

Features

• Configurable instance ID, environment, and platform settings
• Support for combined input and auto navigation options
• Token exchange and user data retrieval
• Error handling and success callbacks
• Internal browser for OAuth flows
• Comprehensive documentation and README