@casoon/auditmysite/examples/README.md

Professional website analysis suite with robust accessibility testing, Core Web Vitals performance monitoring, SEO analysis, and content optimization insights. Features isolated browser contexts, retry mechanisms, and comprehensive API endpoints for profe

# 🚀 AuditMySite SDK Examples

This directory contains comprehensive examples showing how to integrate the AuditMySite SDK into various environments and use cases.

## 📁 Examples Overview

### [`basic-usage.js`](./basic-usage.js) - Getting Started
Simple examples for beginners:
- Quick audit setup
- Fluent API usage
- Event listeners
- Error handling

### [`express-integration.js`](./express-integration.js) - Web Applications
Complete Express.js web application with:
- Web interface for audit submission
- Job queue management
- Real-time progress tracking
- Report download endpoints

### [`ci-cd-integration.js`](./ci-cd-integration.js) - CI/CD Pipelines
Production-ready CI/CD integration:
- Quality gates and thresholds
- JUnit test reports
- PR summary generation
- Slack/Teams notifications
- Badge generation

## 🔧 Quick Start

### 1. Basic SDK Usage

```javascript
const { AuditSDK } = require('auditmysite');

// Simple audit
const audit = new AuditSDK();
const result = await audit.quickAudit('https://example.com/sitemap.xml', {
  maxPages: 5,
  formats: ['html', 'json']
});

console.log(`Success Rate: ${result.summary.passedPages / result.summary.testedPages * 100}%`);
```

### 2. Fluent API with Events

```javascript
const audit = new AuditSDK();

const result = await audit.audit()
  .sitemap('https://example.com/sitemap.xml')
  .maxPages(10)
  .formats(['html', 'markdown', 'csv'])
  .includePerformance()
  .on('audit:progress', (event) => {
    console.log(`Progress: ${event.data.percentage}%`);
  })
  .on('audit:page:complete', (event) => {
    const status = event.data.result.passed ? '✅' : '❌';
    console.log(`${status} ${event.data.url}`);
  })
  .run();
```

### 3. REST API Server

```javascript
const { AuditAPIServer } = require('auditmysite');

const server = new AuditAPIServer({
  port: 3000,
  maxConcurrentJobs: 5
});

await server.start();
console.log('API Server running at http://localhost:3000');
// Visit http://localhost:3000/api-docs for Swagger documentation
```

## 🌐 Integration Guides

### Node.js Application

```javascript
const { AuditSDK } = require('auditmysite');

class AccessibilityService {
  constructor() {
    this.audit = new AuditSDK({
      defaultOutputDir: './reports',
      verbose: true
    });
  }

  async auditWebsite(sitemapUrl, options = {}) {
    try {
      const result = await this.audit.quickAudit(sitemapUrl, {
        maxPages: options.maxPages || 5,
        formats: options.formats || ['json'],
        includePerformance: true
      });

      return {
        success: true,
        summary: result.summary,
        reports: result.reports
      };
    } catch (error) {
      return {
        success: false,
        error: error.message
      };
    }
  }
}

module.exports = AccessibilityService;
```

### Next.js API Route

```javascript
// pages/api/audit.js
import { AuditSDK } from 'auditmysite';

const audit = new AuditSDK({
  defaultOutputDir: './public/reports'
});

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { sitemapUrl, maxPages = 5 } = req.body;

  try {
    const result = await audit.quickAudit(sitemapUrl, {
      maxPages,
      formats: ['html', 'json']
    });

    res.json({
      success: true,
      summary: result.summary,
      reports: result.reports.map(r => ({
        ...r,
        url: `/reports/${path.basename(r.path)}`
      }))
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message
    });
  }
}
```

### GitHub Actions Workflow

```yaml
# .github/workflows/accessibility.yml
name: Accessibility Testing

on: [push, pull_request]

jobs:
  accessibility-audit:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm install auditmysite
        
      - name: Run accessibility audit
        run: node examples/ci-cd-integration.js https://your-site.com/sitemap.xml
        env:
          AUDIT_MAX_PAGES: 20
          AUDIT_FORMATS: json,html
          AUDIT_FAIL_ON_ERRORS: true
          AUDIT_SUCCESS_RATE_THRESHOLD: 85
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
          
      - name: Upload reports
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: accessibility-reports
          path: audit-reports/
          
      - name: Comment PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const summary = fs.readFileSync('audit-reports/pr-summary.md', 'utf8');
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: summary
            });
```

### Docker Container

```dockerfile
FROM node:18-alpine

WORKDIR /app

# Install AuditMySite
RUN npm install auditmysite

# Copy your script
COPY audit-script.js .

# Run audit
CMD ["node", "audit-script.js"]
```

```bash
# Build and run
docker build -t my-accessibility-audit .
docker run -e SITEMAP_URL=https://example.com/sitemap.xml my-accessibility-audit
```

## 🔧 Configuration Options

### SDK Configuration

```javascript
const audit = new AuditSDK({
  timeout: 30000,              // Request timeout
  maxConcurrency: 3,           // Concurrent page tests
  defaultOutputDir: './reports', // Report output directory
  verbose: true,               // Enable verbose logging
  userAgent: 'MyBot/1.0',      // Custom user agent
  proxy: {                     // Proxy configuration
    host: 'proxy.example.com',
    port: 8080,
    auth: {
      username: 'user',
      password: 'pass'
    }
  }
});
```

### Audit Options

```javascript
const options = {
  maxPages: 20,                    // Maximum pages to test
  standard: 'WCAG2AA',             // Accessibility standard
  formats: ['html', 'json', 'csv'], // Report formats
  includePerformance: true,        // Include performance metrics
  includeSeo: false,               // Include SEO analysis
  includeSecurity: false,          // Include security checks
  viewport: {                      // Custom viewport
    width: 1920,
    height: 1080,
    isMobile: false
  },
  performanceBudget: {             // Performance thresholds
    lcp: { good: 2500, poor: 4000 },
    cls: { good: 0.1, poor: 0.25 }
  }
};
```

## 📊 Event System

The SDK provides comprehensive event tracking for real-time monitoring:

```javascript
audit.audit()
  .sitemap(url)
  .on('audit:start', (event) => {
    console.log('🚀 Audit started');
  })
  .on('audit:progress', (event) => {
    const { current, total, percentage, currentUrl } = event.data;
    console.log(`📊 ${percentage}% (${current}/${total}) - ${currentUrl}`);
  })
  .on('audit:page:start', (event) => {
    console.log(`🔍 Testing: ${event.data.url}`);
  })
  .on('audit:page:complete', (event) => {
    const { url, result, duration } = event.data;
    console.log(`✅ ${url} - ${result.errors.length} errors (${duration}ms)`);
  })
  .on('audit:page:error', (event) => {
    console.log(`❌ ${event.data.url} - ${event.data.error.message}`);
  })
  .on('report:start', (event) => {
    console.log(`📄 Generating ${event.data.format} report...`);
  })
  .on('report:complete', (event) => {
    console.log(`✅ Report generated: ${event.data.path}`);
  })
  .on('audit:complete', (event) => {
    console.log('🎉 Audit completed!');
  })
  .on('audit:error', (event) => {
    console.error('💥 Audit failed:', event.data.message);
  })
  .run();
```

## 🛡️ Error Handling

```javascript
try {
  const result = await audit.quickAudit(sitemapUrl, options);
} catch (error) {
  if (error.code === 'INVALID_SITEMAP') {
    console.error('Invalid sitemap URL provided');
  } else if (error.code === 'TIMEOUT') {
    console.error('Audit timed out - try reducing maxPages');
  } else if (error.code === 'NETWORK_ERROR') {
    console.error('Network connection failed');
  } else {
    console.error('Unexpected error:', error.message);
  }
}
```

## 📈 Performance Tips

1. **Optimize Concurrency**: Adjust `maxConcurrency` based on target server capacity
2. **Use Appropriate Limits**: Set realistic `maxPages` for your needs
3. **Choose Formats Wisely**: Only generate reports you actually need
4. **Implement Caching**: Cache sitemap parsing results for repeated audits
5. **Monitor Resources**: Track memory usage for large audits

## 🔗 Additional Resources

- [SDK API Documentation](../docs/sdk-api.md)
- [REST API Documentation](../docs/rest-api.md)
- [Configuration Reference](../docs/configuration.md)
- [Performance Guide](../docs/performance.md)
- [Troubleshooting](../docs/troubleshooting.md)

## 🤝 Contributing

Found an issue or want to contribute an example?

1. Fork the repository
2. Create a feature branch
3. Add your example with documentation
4. Submit a pull request

## 📝 License

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