# DomainShots.ai v3.0 - Competitive Intelligence Platform

## Overview

DomainShots.ai has evolved from a simple screenshot service into a **complete competitive intelligence platform** with AI-powered change detection, visual diffing, competitor tracking, and automated alerts.

## New Features

### 1. Visual Change Detection

Compare any two screenshots to detect and visualize changes:

```bash
POST /api/changes/compare
{
  "screenshot_before_id": 123,
  "screenshot_after_id": 124,
  "watch_list_id": 1,
  "analyze": true
}
```

**Features:**
- **Pixel-level comparison** with difference counting
- **Similarity scoring** (0-100% similarity)
- **Visual diff images** with red overlay highlighting
- **Change magnitude categorization**: minor (<5% diff), moderate (5-15%), major (>15%)

**Response:**
```json
{
  "id": 456,
  "similarity_score": 92.5,
  "pixel_difference": 45231,
  "has_changes": true,
  "change_magnitude": "moderate",
  "diff_url": "https://domainshots.ai/screenshots/diff_abc123.png",
  "before_url": "https://...",
  "after_url": "https://..."
}
```

### 2. AI-Powered Change Analysis

Fal.ai integration categorizes and explains changes:

```bash
POST /api/changes/comparisons/456/analyze
```

**AI Categories:**
- `layout` - Page structure, element positioning
- `content` - Text or media content changes
- `pricing` - Pricing table or cost changes
- `design` - Visual styling, colors, fonts
- `features` - New features or removed functionality
- `navigation` - Menu or navigation changes

**Response:**
```json
{
  "analyzed": true,
  "change_categories": ["pricing", "content"],
  "ai_summary": "Major pricing update: Enterprise plan increased 20% from $99 to $119/month. New feature highlighted in hero section.",
  "ai_confidence": 85.0
}
```

### 3. Change Detection Rules

Define rules to automatically detect and alert on specific changes:

```bash
POST /api/changes/rules
{
  "name": "Monitor competitor pricing",
  "watch_list_id": 1,
  "sensitivity": "high",
  "min_similarity_threshold": 98.0,
  "detect_pricing_changes": true,
  "detect_content_changes": false,
  "enable_alerts": true,
  "alert_channels": ["email", "webhook"]
}
```

**Sensitivity Levels:**
- `low` - Alert when similarity < 90%
- `moderate` - Alert when similarity < 95% (default)
- `high` - Alert when similarity < 98%

**Rule Types:**
- Detect layout changes
- Detect content changes
- Detect pricing changes
- Detect design changes

### 4. Competitor Tracking

Track competitors and automatically monitor their changes:

```bash
POST /api/competitors
{
  "name": "Acme Corp",
  "domain": "acme.com",
  "description": "Main competitor in SaaS space",
  "track_homepage": true,
  "track_pricing_page": true,
  "track_features_page": true,
  "custom_urls": ["https://acme.com/about"],
  "industry": "SaaS",
  "tags": ["direct-competitor", "enterprise"],
  "auto_create_watchlist": true
}
```

**Auto-creates watch lists for:**
- Homepage (`https://domain.com`)
- Pricing pages (`/pricing`, `/plans`)
- Features pages (`/features`, `/products`)
- Custom URLs

### 5. Competitive Events Timeline

Track and analyze competitor changes over time:

```bash
POST /api/competitors/events
{
  "competitor_id": 123,
  "event_type": "pricing_change",
  "title": "Acme raised pricing 20%",
  "description": "Enterprise plan increased from $99 to $119/month",
  "impact_level": "high",
  "url": "https://acme.com/pricing",
  "comparison_id": 456
}
```

**Event Types:**
- `pricing_change` - Price updates
- `feature_launch` - New features
- `design_update` - Visual redesign
- `content_update` - Content changes
- `product_launch` - New products
- `rebranding` - Brand changes

**Impact Levels:**
- `low` - Minor changes
- `medium` - Moderate significance
- `high` - Important changes
- `critical` - Major competitive threat

### 6. Automated Alerts

Get notified when changes are detected:

```bash
GET /api/alerts?acknowledged=false&limit=50
```

**Alert Channels:**
- **Email** - Send email notifications
- **Webhook** - HTTP POST to custom endpoint
- **Slack** - Slack channel integration (via webhook)

**Alert Properties:**
- Severity levels (low, medium, high, critical)
- Change categories
- Similarity scores
- Acknowledge/dismiss functionality

### 7. Webhook System

Receive real-time notifications via webhooks:

```bash
POST /api/alerts/webhooks
{
  "name": "Slack notifications",
  "url": "https://hooks.slack.com/services/xxx/yyy/zzz",
  "events": ["change_detected"],
  "secret_key": "your-hmac-secret",
  "watch_list_ids": [1, 2, 3],
  "min_severity": "high"
}
```

**Webhook Payload:**
```json
{
  "event": "change_detected",
  "alert_id": 789,
  "alert_type": "change_detected",
  "severity": "high",
  "title": "Change detected: Competitor pricing",
  "message": "Major pricing update detected...",
  "url": "https://acme.com/pricing",
  "change_categories": ["pricing"],
  "similarity_score": 92.5,
  "timestamp": "2026-01-09T02:30:00Z"
}
```

**Security:**
- HMAC-SHA256 signatures (`X-DomainShots-Signature` header)
- Delivery tracking and retry logic
- Error logging

### 8. Competitive Intelligence Dashboard

Get overview of all competitor activity:

```bash
GET /api/competitors/dashboard
```

**Response:**
```json
{
  "stats": {
    "total_competitors": 5,
    "active_competitors": 4,
    "industries_tracked": 2
  },
  "recent_events": [
    {
      "id": 123,
      "event_type": "pricing_change",
      "title": "Acme raised pricing 20%",
      "impact_level": "high",
      "competitor_name": "Acme Corp",
      "created_at": "2026-01-08T..."
    }
  ],
  "high_impact_events_30d": 3
}
```

## Use Cases

### 1. Competitive Pricing Monitoring

Track competitor pricing pages and get alerts when prices change:

```bash
# Add competitor
POST /api/competitors
{
  "name": "Competitor A",
  "domain": "competitor-a.com",
  "track_pricing_page": true
}

# Create detection rule
POST /api/changes/rules
{
  "name": "Pricing alerts",
  "watch_list_id": 1,
  "detect_pricing_changes": true,
  "sensitivity": "high"
}

# Set up Slack webhook
POST /api/alerts/webhooks
{
  "name": "Slack #pricing-intel",
  "url": "https://hooks.slack.com/...",
  "min_severity": "medium"
}
```

### 2. Product Feature Tracking

Monitor when competitors launch new features:

```bash
# Track features page
POST /api/competitors
{
  "name": "Competitor B",
  "domain": "competitor-b.com",
  "track_features_page": true,
  "custom_urls": ["https://competitor-b.com/roadmap"]
}

# Create detection rule
POST /api/changes/rules
{
  "name": "Feature launches",
  "detect_content_changes": true,
  "detect_features": true,
  "enable_alerts": true
}
```

### 3. Design & Branding Updates

Track visual changes to competitor websites:

```bash
POST /api/changes/rules
{
  "name": "Design monitoring",
  "detect_design_changes": true,
  "detect_layout_changes": true,
  "sensitivity": "moderate"
}
```

## Premium Tiers

### Professional ($29.99/month)
- ✅ Visual change detection
- ✅ Basic alerts (email)
- ✅ Monitor up to 10 competitors
- ✅ 500 screenshots/month
- ✅ 10 API tokens
- ✅ 10,000 API requests/month

### Enterprise ($99.99/month)
- ✅ AI-powered change categorization
- ✅ Webhook alerts & Slack integration
- ✅ Unlimited competitor monitoring
- ✅ Competitive intelligence dashboard
- ✅ Unlimited screenshots
- ✅ Unlimited API tokens
- ✅ Unlimited API requests
- ✅ Priority support

## Database Schema

### New Tables (9)

1. **screenshot_comparisons** - Visual diffs and AI analysis
2. **change_detection_rules** - User-defined detection rules
3. **change_alerts** - Generated alerts
4. **webhook_endpoints** - Webhook configurations
5. **webhook_deliveries** - Delivery tracking
6. **competitors** - Competitor tracking
7. **competitive_events** - Event timeline

## API Reference

### Change Detection

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/changes/compare` | POST | Compare two screenshots |
| `/api/changes/comparisons` | GET | List comparisons |
| `/api/changes/comparisons/:id` | GET | Get comparison details |
| `/api/changes/comparisons/:id/analyze` | POST | Analyze with AI |
| `/api/changes/stats` | GET | Get comparison stats |
| `/api/changes/rules` | GET/POST | Manage detection rules |
| `/api/changes/rules/:id` | PUT/DELETE | Update/delete rule |

### Competitors

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/competitors` | GET/POST | List/add competitors |
| `/api/competitors/:id` | GET/PUT/DELETE | Manage competitor |
| `/api/competitors/:id/watchlist` | POST | Create watch list |
| `/api/competitors/events` | GET/POST | Manage events |
| `/api/competitors/dashboard` | GET | Get dashboard |

### Alerts

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/alerts` | GET | List alerts |
| `/api/alerts/:id/acknowledge` | POST | Acknowledge alert |
| `/api/alerts/:id/dismiss` | POST | Dismiss alert |
| `/api/alerts/webhooks` | GET/POST | Manage webhooks |
| `/api/alerts/webhooks/:id` | PUT/DELETE | Update/delete webhook |

## Migration

Run the new migration to add change detection tables:

```bash
psql -h HOST -U USER -d DATABASE -f server/migrations/004_change_detection.sql
```

## Example Workflow

```bash
# 1. Add competitor
curl -X POST https://api.domainshots.ai/api/competitors \
  -H "Authorization: Bearer dsh_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Competitor X",
    "domain": "competitor-x.com",
    "track_pricing_page": true,
    "auto_create_watchlist": true
  }'

# 2. Create detection rule
curl -X POST https://api.domainshots.ai/api/changes/rules \
  -H "Authorization: Bearer dsh_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pricing monitor",
    "watch_list_id": 1,
    "detect_pricing_changes": true,
    "sensitivity": "high",
    "enable_alerts": true
  }'

# 3. Set up webhook
curl -X POST https://api.domainshots.ai/api/alerts/webhooks \
  -H "Authorization: Bearer dsh_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack alerts",
    "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
    "events": ["change_detected"]
  }'

# 4. Get alerts
curl https://api.domainshots.ai/api/alerts?acknowledged=false \
  -H "Authorization: Bearer dsh_YOUR_TOKEN"

# 5. View dashboard
curl https://api.domainshots.ai/api/competitors/dashboard \
  -H "Authorization: Bearer dsh_YOUR_TOKEN"
```

## What's Next?

Coming soon:
- Slack app integration (native)
- Discord bot
- Zapier/Make.com integrations
- Email digest reports
- Trend analysis charts
- Competitive benchmarking
- Market intelligence reports
- Chrome extension for quick checks

---

**DomainShots.ai v3.0** - From simple screenshots to complete competitive intelligence platform.

🔗 [GitHub](https://github.com/straticus1/domainshots.ai) | 📚 [Docs](https://docs.domainshots.ai) | 🌐 [Website](https://domainshots.ai)