npm package: @scraminator/core
Description: AI-powered Playwright automation framework that converts natural language instructions into executable Playwright code with step-by-step execution and intelligent error recovery
Author: Nawaaz Kortiwala
Latest version: 1.0.1

# @scraminator/core

> **AI-Powered Playwright Automation Framework**  
> Convert natural language instructions into executable Playwright code with step-by-step execution and intelligent error recovery.

[![npm version](https://badge.fury.io/js/%40scraminator%2Fcore.svg)](https://badge.fury.io/js/%40scraminator%2Fcore)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)](https://www.typescriptlang.org/)

## 🚀 Features

- **Natural Language Processing**: Convert plain English instructions into Playwright automation code
- **Step-by-Step Execution**: Execute workflows incrementally with real browser context
- **AI-Powered Code Generation**: Generate robust Playwright code using Claude AI
- **Intelligent Error Recovery**: Automatic retry mechanisms with AI-driven error analysis
- **Context-Aware Execution**: Capture and analyze page context for better automation
- **Final Code Delivery**: Combine all successful steps into executable Playwright code
- **Comprehensive Reporting**: Detailed execution results with timing and error analysis

## 📦 Installation

```bash
npm install @scraminator/core
```

### Prerequisites

- Node.js 18+
- Playwright installed in your project
- Anthropic API key for AI code generation

## 🎯 Quick Start

```typescript
import { EnhancedAIPlaywrightFramework } from '@scraminator/core';

// Initialize the framework
const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    headless: false,
    timeout: 30000,
  },
});

// Execute a workflow
const workflow = [
  '1. Go to https://example.com',
  '2. Click the login button',
  '3. Fill username with "testuser"',
  '4. Fill password with "testpass"',
  '5. Click submit',
];

const result = await framework.execute(workflow);

console.log('Success:', result.success);
console.log('Generated Code:', result.finalCode);
```

## 📚 API Documentation

### EnhancedAIPlaywrightFramework

The main framework class for executing AI-powered Playwright workflows.

#### Constructor

```typescript
new EnhancedAIPlaywrightFramework(config: EnhancedAIPlaywrightFrameworkConfig)
```

**Configuration Options:**

```typescript
interface EnhancedAIPlaywrightFrameworkConfig {
  aiProvider: string; // AI provider (currently 'anthropic')
  apiKey: string; // API key for the AI provider
  model: string; // AI model to use
  options?: {
    maxRetries?: number; // Max retry attempts (default: 3)
    timeout?: number; // Page timeout in ms (default: 30000)
    headless?: boolean; // Browser headless mode (default: true)
    browserType?: 'chromium' | 'firefox' | 'webkit'; // Browser type
    environment?: Record<string, any>; // Environment variables
  };
}
```

#### Methods

##### `execute(workflow, options?)`

Execute a workflow step-by-step with AI code generation.

```typescript
async execute(
  workflow: string | string[] | Instruction[],
  options?: any
): Promise<WorkflowResult>
```

**Parameters:**

- `workflow`: Workflow instructions as string, string array, or Instruction array
- `options`: Optional execution options

**Returns:**

```typescript
interface WorkflowResult {
  success: boolean; // Overall success status
  steps: StepResult[]; // Individual step results
  finalCode: string; // Combined executable code
  totalDuration: number; // Total execution time
  summary: {
    totalSteps: number; // Total steps in workflow
    successfulSteps: number; // Successfully executed steps
    failedSteps: number; // Failed steps
    recoveryAttempts: number; // Total recovery attempts
  };
}
```

### Types

#### Instruction

```typescript
interface Instruction {
  step: number; // Step number
  action: string; // Action description
  metadata?: Record<string, any>; // Optional metadata
}
```

#### StepResult

```typescript
interface StepResult {
  step: number; // Step number
  success: boolean; // Step success status
  generatedCode: string; // Generated Playwright code
  executionResult: any; // Step execution result
  error?: string; // Error message if failed
  recoveryAttempts?: number; // Number of recovery attempts
  pageContext: StepContext; // Page context at execution
  duration: number; // Step execution time
}
```

#### StepContext

```typescript
interface StepContext {
  pageUrl: string; // Current page URL
  pageTitle: string; // Page title
  pageSummary: string; // AI-generated page summary
  htmlContent: string; // Cleaned HTML content
  previousSteps: Instruction[]; // Previously executed steps
  environment: Record<string, any>; // Environment variables
  timestamp: string; // Execution timestamp
}
```

## 🔧 Usage Examples

### Basic Workflow Execution

```typescript
import { EnhancedAIPlaywrightFramework } from '@scraminator/core';

const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    headless: false,
    timeout: 30000,
  },
});

const workflow = [
  '1. Navigate to https://example.com',
  '2. Find and click the "Get Started" button',
  '3. Fill the email field with "test@example.com"',
  '4. Submit the form',
];

const result = await framework.execute(workflow);

if (result.success) {
  console.log('✅ Workflow completed successfully!');
  console.log('📊 Summary:', result.summary);
  console.log('💻 Generated Code:', result.finalCode);
} else {
  console.log('❌ Some steps failed:', result.summary.failedSteps);
}
```

### Complex Workflow with Error Handling

```typescript
const complexWorkflow = [
  '1. Go to https://ecommerce-site.com',
  '2. Search for "laptop" in the search box',
  '3. Filter results by price range $500-$1000',
  '4. Sort by customer rating',
  '5. Click on the first product',
  '6. Add item to cart',
  '7. Proceed to checkout',
  '8. Fill shipping information',
];

const result = await framework.execute(complexWorkflow);

// Analyze results
result.steps.forEach((step, index) => {
  const status = step.success ? '✅' : '❌';
  console.log(`${status} Step ${step.step}: ${step.duration}ms`);

  if (!step.success) {
    console.log(`   Error: ${step.error}`);
    console.log(`   Recovery attempts: ${step.recoveryAttempts}`);
  }
});

// Save generated code
if (result.finalCode) {
  await fs.writeFile('generated-workflow.js', result.finalCode);
  console.log('💾 Generated code saved to generated-workflow.js');
}
```

### Using Generated Code

```typescript
// Import and run the generated workflow
import generatedWorkflow from './generated-workflow.js';
import { chromium } from 'playwright';

async function runGeneratedWorkflow() {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  try {
    const results = await generatedWorkflow(page);
    console.log('Workflow executed successfully:', results);
  } finally {
    await browser.close();
  }
}

runGeneratedWorkflow();
```

## 🛠️ Advanced Configuration

### Custom Environment Variables

```typescript
const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    environment: {
      baseUrl: 'https://my-app.com',
      testMode: true,
      customTimeout: 45000,
      userAgent: 'Custom User Agent',
    },
  },
});
```

### Browser Configuration

```typescript
const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    browserType: 'firefox', // Use Firefox
    headless: false, // Show browser window
    timeout: 60000, // 60 second timeout
  },
});
```

## 🔍 Error Recovery

The framework includes intelligent error recovery mechanisms:

1. **Automatic Retry**: Failed steps are automatically retried up to 3 times
2. **AI Error Analysis**: Errors are analyzed by AI to suggest recovery strategies
3. **Context Preservation**: Page context is preserved between retry attempts
4. **Graceful Degradation**: Workflow continues even if some steps fail

### Recovery Strategies

- **Retry**: Attempt the same action with modified parameters
- **Skip**: Skip the problematic step and continue
- **Alternative Approach**: Try a different method to achieve the goal

## 📊 Monitoring and Logging

The framework provides comprehensive logging and monitoring:

```typescript
// Enable detailed logging
const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    // Logging is enabled by default
  },
});

// Execution results include detailed metrics
const result = await framework.execute(workflow);

console.log('📈 Performance Metrics:');
console.log(`   Total Duration: ${result.totalDuration}ms`);
console.log(
  `   Average Step Time: ${result.totalDuration / result.summary.totalSteps}ms`
);
console.log(
  `   Success Rate: ${((result.summary.successfulSteps / result.summary.totalSteps) * 100).toFixed(1)}%`
);
```

## 🧪 Testing

Run the test suite:

```bash
npm test
```

Run tests with UI:

```bash
npm run test:ui
```

## 📝 Development

### Building

```bash
npm run build
```

### Linting

```bash
npm run lint
npm run lint:fix
```

### Formatting

```bash
npm run format
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [Full API Documentation](./docs/API.md)
- **Examples**: [Usage Examples](./docs/EXAMPLES.md)
- **Issues**: [GitHub Issues](https://github.com/scraminator/core/issues)
- **Discussions**: [GitHub Discussions](https://github.com/scraminator/core/discussions)

## 🔗 Related Projects

- [Playwright](https://playwright.dev/) - Browser automation library
- [Anthropic Claude](https://www.anthropic.com/claude) - AI model for code generation

---

**Made with ❤️ by the Scraminator Team**