misoai-web 1.0.6 → 1.5.7

package/README.md

@@ -1,353 +1,9 @@
-# @midscene/web - AI-Powered Web Automation
+## Documentation
 
-[![npm version](https://badge.fury.io/js/@midscene%2Fweb.svg)](https://badge.fury.io/js/@midscene%2Fweb)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Automate UI actions, extract data, and perform assertions using AI. It offers JavaScript SDK, Chrome extension, and support for scripting in YAML.
 
-AI-powered web automation library with advanced cumulative context system for intelligent, multi-step browser interactions.
+See https://midscenejs.com/ for details.
 
-## 🚀 Features
+## License
 
-- **🧠 Cumulative Context System**: AI remembers previous actions and data across steps
-- **🗣️ Natural Language Data References**: No more `{stored.key}` syntax needed
-- **🎯 Smart Context-Aware Assertions**: Intelligent data replacement in assertions
-- **🔄 Multi-Step Workflows**: Seamless information flow between actions
-- **🛡️ Built-in CAPTCHA Solving**: Advanced AI-powered CAPTCHA detection and solving
-- **📊 Comprehensive Logging**: Full visibility into context operations and AI calls
-- **🎭 Framework Support**: Works with Puppeteer, Playwright, and more
-
-## 📦 Installation
-
-```bash
-npm install @midscene/web puppeteer
-# or
-yarn add @midscene/web puppeteer
-```
-
-## 🎯 Quick Start
-
-### Basic Usage with Cumulative Context
-
-```javascript
-import { PuppeteerAgent } from '@midscene/web';
-import puppeteer from 'puppeteer';
-
-const browser = await puppeteer.launch({ headless: false });
-const page = await browser.newPage();
-
-// Create agent with cumulative context enabled
-const agent = new PuppeteerAgent(page, {
-  enableCumulativeContext: true,  // 🔥 Enable context system
-  autoClearContext: true,         // 🧹 Start with clean context
-  testId: 'my-automation'
-});
-
-await page.goto('https://example.com');
-
-// Step 1: Store data with natural language
-await agent.aiQuery('kullanıcı adını "john_doe" olarak username şeklinde kaydet');
-
-// Step 2: Use stored data without {stored.key} syntax!
-await agent.aiAction('arama kutusuna username verisini yaz');
-
-// Step 3: Context-aware assertion
-await agent.aiAssert('arama kutusunda username değeri görünüyor');
-
-await browser.close();
-```
-
-## 🧠 Cumulative Context System
-
-### Natural Language Data Storage
-
-```javascript
-// Turkish natural language storage
-await agent.aiQuery('ürün adını "iPhone 15" olarak urun_adi şeklinde kaydet');
-await agent.aiQuery('fiyatı "999$" olarak fiyat şeklinde kaydet');
-
-// English natural language storage
-await agent.aiQuery('extract username and store as user_name');
-await agent.aiQuery('get email address, store as email');
-```
-
-### Automatic Data Usage
-
-```javascript
-// No need for {stored.key} syntax!
-await agent.aiAction('formu urun_adi ve fiyat ile doldur');
-await agent.aiAction('use user_name and email to fill the form');
-
-// Multiple data references in one action
-await agent.aiAction('sepete urun_adi ürününü fiyat fiyatıyla ekle');
-```
-
-### Context-Aware Assertions
-
-```javascript
-// Smart replacement - AI decides when to replace
-await agent.aiAssert('sepette urun_adi ürünü görünüyor'); // ✅ Will replace
-await agent.aiAssert('sayfada iPhone yazısı var');        // ❓ Context-dependent
-```
-
-## 🛡️ AI CAPTCHA Solving
-
-The `aiCaptcha` method provides intelligent CAPTCHA detection and solving capabilities with automatic execution:
-
-```javascript
-// Basic CAPTCHA solving (auto-detects complexity)
-await agent.aiCaptcha();
-
-// Advanced CAPTCHA solving with options
-await agent.aiCaptcha({
-  deepThink: true,              // Force deep analysis
-  autoDetectComplexity: true    // Auto-detect if deep thinking needed (default: true)
-});
-```
-
-### CAPTCHA Features
-
-- **🔍 Automatic Detection**: Identifies CAPTCHA type (text, image, unknown)
-- **🧠 Complexity Analysis**: Auto-detects if deep thinking is needed
-- **📝 Text CAPTCHAs**: Solves distorted text and automatically inputs solution
-- **🖼️ Image CAPTCHAs**: Handles "select all images with..." challenges with coordinate clicking
-- **🎯 Automatic Execution**: Performs all required actions (click, input, verify) automatically
-- **⚡ Smart Processing**: Uses appropriate AI model based on complexity
-- **🔄 Action Sequence**: Executes complete CAPTCHA solving workflow
-
-### CAPTCHA Response Format
-
-The AI returns a structured response with:
-
-```javascript
-{
-  captchaType: "text" | "image" | "unknown",
-  solution: "The solution text or description",
-  thought: "AI reasoning process",
-  actions: [
-    {
-      type: "click" | "input" | "verify",
-      target: "Description of target element",
-      value: "Text to input (for input actions)",
-      coordinates: [x, y] // For precise clicking
-    }
-  ]
-}
-```
-
-### CAPTCHA Example
-
-```javascript
-// Navigate to page with CAPTCHA
-await page.goto('https://example.com/login');
-
-// Fill login form
-await agent.aiInput('john@example.com', 'email field');
-await agent.aiInput('password123', 'password field');
-
-// Solve CAPTCHA automatically - AI will:
-// 1. Analyze the CAPTCHA type and complexity
-// 2. Generate solution
-// 3. Execute all required actions automatically
-const captchaResult = await agent.aiCaptcha({
-  autoDetectComplexity: true
-});
-
-console.log('CAPTCHA solved:', captchaResult.result.captchaType);
-console.log('Solution:', captchaResult.result.solution);
-console.log('Actions performed:', captchaResult.result.actions.length);
-
-// Form is now ready to submit
-await agent.aiTap('login button');
-```
-
-### Advanced CAPTCHA Scenarios
-
-```javascript
-// Complex image CAPTCHA with deep thinking
-await agent.aiCaptcha({
-  deepThink: true  // Forces detailed analysis for complex puzzles
-});
-
-// Text CAPTCHA with automatic input
-// AI will automatically:
-// - Click on input field
-// - Type the solution
-// - Click verify button
-await agent.aiCaptcha();
-
-// Using with cumulative context
-await agent.aiQuery('CAPTCHA çözümünü captcha_cozum olarak kaydet');
-await agent.aiCaptcha();
-await agent.aiAssert('CAPTCHA başarıyla çözüldü');
-```
-
-## ⚙️ Configuration Options
-
-```javascript
-const agent = new PuppeteerAgent(page, {
-  // Context System
-  enableCumulativeContext: true,    // Enable/disable context system
-  autoClearContext: false,          // Auto-clear on agent creation
-
-  // Basic Options
-  testId: 'my-test',               // Test identifier
-  cacheId: 'my-cache',             // Cache identifier
-  aiActionContext: 'context',      // AI behavior context
-
-  // Reporting
-  generateReport: true,            // Generate HTML reports
-  autoPrintReportMsg: true,        // Print report messages
-
-  // Navigation
-  forceSameTabNavigation: true,    // Force same-tab navigation
-  waitForNavigationTimeout: 30000, // Navigation timeout
-  waitForNetworkIdleTimeout: 5000  // Network idle timeout
-});
-```
-
-## 📊 Context Management
-
-### Direct Context Access
-
-```javascript
-// Get stored data
-const storedData = agent.getStoredData();
-console.log('Stored:', storedData);
-
-// Get step summary
-const summary = agent.getStepSummary();
-console.log('Steps:', summary);
-
-// Clear context manually
-agent.clearContext();
-
-// Get context store instance
-const contextStore = agent.getContextStore();
-```
-
-### Manual Data Storage
-
-```javascript
-const contextStore = agent.getContextStore();
-
-// Store data manually
-contextStore.storeData('customKey', 'customValue');
-
-// Store with aliases for natural language
-contextStore.storeDataWithAliases('productName', 'iPhone 15', ['urun', 'product']);
-
-// Get recent steps
-const recentSteps = contextStore.getRecentSteps(5);
-```
-
-## 🔍 Debug Logging
-
-Enable comprehensive logging to see context operations:
-
-```bash
-# All debug logs
-DEBUG=midscene:* node your-script.js
-
-# Context-specific logs
-DEBUG=midscene:agent node your-script.js
-
-# AI call logs
-DEBUG=midscene:ai:*,midscene:agent node your-script.js
-```
-
-### Log Examples
-
-```
-DEBUG midscene:agent Context replacement in aiAction: {
-  original: "type username in search box",
-  processed: "type john_doe in search box",
-  storedData: { "username": "john_doe" }
-}
-
-DEBUG midscene:agent Stored query result with aliases: {
-  key: "username",
-  value: "john_doe",
-  aliases: ["username", "user", "kullanici"]
-}
-```
-
-## 🎭 Multi-Step Workflow Example
-
-```javascript
-// E-commerce automation with context
-const agent = new PuppeteerAgent(page, {
-  enableCumulativeContext: true,
-  autoClearContext: true
-});
-
-await page.goto('https://shop.example.com');
-
-// Step 1: Search and store product info
-await agent.aiAction('arama kutusuna "laptop" yaz ve ara');
-await agent.aiQuery('ilk ürünün adını urun_adi olarak kaydet');
-await agent.aiQuery('ilk ürünün fiyatını urun_fiyati olarak kaydet');
-
-// Step 2: Add to cart using stored data
-await agent.aiAction('urun_adi ürününü sepete ekle');
-
-// Step 3: Verify cart contents
-await agent.aiAction('sepete git');
-await agent.aiAssert('sepette urun_adi ürünü urun_fiyati fiyatıyla görünüyor');
-
-// Step 4: Proceed to checkout
-await agent.aiAction('ödeme sayfasına git');
-await agent.aiAssert('ödeme sayfasında urun_adi ürünü listeleniyor');
-```
-
-## 🔄 Backward Compatibility
-
-The new context system is fully backward compatible:
-
-```javascript
-// Old syntax still works
-await agent.aiQuery('extract username, store as user');
-await agent.aiAction('type {stored.user} in field');
-
-// New syntax (recommended)
-await agent.aiQuery('kullanıcı adını user olarak kaydet');
-await agent.aiAction('alana user verisini yaz');
-
-// Mixed usage
-await agent.aiAction('use {stored.email} and user verisi together');
-```
-
-## 📚 API Reference
-
-### Core Methods
-
-- `aiAction(prompt)` - Perform actions with context awareness
-- `aiQuery(prompt)` - Extract data with automatic storage
-- `aiAssert(assertion)` - Context-aware assertions
-- `aiCaptcha(options)` - Intelligent CAPTCHA solving
-- `aiTap(target, options)` - Click elements
-- `aiInput(text, target, options)` - Input text
-
-### Context Methods
-
-- `getStoredData()` - Get all stored data
-- `getStepSummary()` - Get step summary
-- `clearContext()` - Clear context store
-- `getContextStore()` - Get context store instance
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
-## 🔗 Links
-
-- [Documentation](https://midscenejs.com)
-- [GitHub Repository](https://github.com/web-infra-dev/midscene)
-- [NPM Package](https://www.npmjs.com/package/@midscene/web)
-- [Examples](https://github.com/web-infra-dev/midscene/tree/main/packages/web-integration/examples)
-
----
-
-**Made with ❤️ by the Midscene Team**
+Midscene is MIT licensed.