@vizzly-testing/cli 0.20.1 → 0.21.1

package/docs/internal/SDK-API.md

@@ -0,0 +1,1018 @@
+# Vizzly SDK API Documentation
+
+This document describes the public API endpoints available for Vizzly SDKs and CLI tools.
+
+## Base URL
+
+All SDK endpoints are prefixed with `/api/sdk/`
+
+## Authentication
+
+All SDK endpoints require:
+
+- **API Token**: Passed via `Authorization: Bearer <token>` header
+- **User-Agent**: Must contain "Vizzly" in the header value (e.g., `Vizzly-CLI/1.0.0`)
+
+## Build Management
+
+### Create Build
+
+Creates a new build for screenshot uploads and comparisons. Supports both standalone builds and parallel execution for sharded test runs.
+
+**Endpoint:** `POST /api/sdk/builds`
+
+**Request Body:**
+
+```json
+{
+  "build": {
+    "name": "CLI Build 2024-01-15T10:30:00Z",
+    "branch": "feature/new-ui",
+    "commit_sha": "abc123def456",
+    "commit_message": "Add new user dashboard",
+    "common_ancestor_sha": "def456ghi789",
+    "environment": "test",
+    "github_pull_request_number": 123,
+
+    // Parallel execution fields (optional)
+    "parallel_id": "workflow-12345-attempt-1"
+  }
+}
+```
+
+**Parallel Execution Field:**
+
+- `parallel_id` (optional): Unique identifier for parallel test execution (e.g., GitHub workflow run ID)
+
+When `parallel_id` is provided:
+
+- **First shard**: Creates a new build with the parallel_id
+- **Subsequent shards**: Find and reuse the existing build with the same parallel_id
+- **All shards**: Upload screenshots to the same build (leveraging existing build reopening logic)
+
+**Response (201):**
+
+```json
+{
+  "id": "build-uuid",
+  "name": "CLI Build 2024-01-15T10:30:00Z",
+  "branch": "feature/new-ui",
+  "environment": "test",
+  "status": "created",
+  "url": "https://app.vizzly.co/org-slug/project-slug/builds/build-uuid",
+  "organizationSlug": "my-org",
+  "projectSlug": "my-project",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### Get Build Details
+
+Retrieves build information with optional related data.
+
+**Endpoint:** `GET /api/sdk/builds/:buildId`
+
+**Query Parameters:**
+
+- `include` (optional): `"screenshots"`, `"comparisons"`, or `"review-summary"` to include related data
+
+**Response (200):**
+
+```json
+{
+  "build": {
+    "id": "build-uuid",
+    "name": "CLI Build 2024-01-15T10:30:00Z",
+    "branch": "feature/new-ui",
+    "status": "completed",
+    "screenshot_count": 25,
+    "comparison_count": 20,
+    "created_at": "2024-01-15T10:30:00Z",
+    "screenshots": [
+      // Only included if include=screenshots
+      {
+        "id": "screenshot-uuid",
+        "name": "homepage-desktop-chrome",
+        "build_id": "build-uuid",
+        "browser": "chrome",
+        "viewport_width": 1920,
+        "viewport_height": 1080,
+        "url": "https://example.com/page",
+        "sha256": "abc123def456...",
+        "status": "completed",
+        "original_url": "https://storage.example.com/screenshot.png",
+        "file_size_bytes": 245760,
+        "width": 1920,
+        "height": 1080,
+        "created_at": "2024-01-15T10:30:00Z"
+      }
+    ],
+    "comparisons": [], // Only included if include=comparisons
+    "review_summary": {
+      // Only included if include=review-summary
+      "build_id": "build-uuid",
+      "review_status": "in_progress",
+      "assignments": [
+        {
+          "id": "assignment-uuid",
+          "user_id": "user-uuid",
+          "user_name": "Jane Smith",
+          "status": "pending",
+          "assigned_at": "2024-01-15T10:00:00Z"
+        }
+      ],
+      "statistics": {
+        "total_assignments": 1,
+        "pending": 1,
+        "completed": 0
+      }
+    }
+  }
+}
+```
+
+### List Builds
+
+Retrieves a paginated list of builds with optional filtering.
+
+**Endpoint:** `GET /api/sdk/builds`
+
+**Query Parameters:**
+
+- `limit` (optional, default: 20): Maximum number of builds to return
+- `offset` (optional, default: 0): Number of builds to skip
+- `branch` (optional): Filter by branch name
+- `environment` (optional): Filter by environment
+- `status` (optional): Filter by build status
+
+**Response (200):**
+
+```json
+{
+  "builds": [
+    {
+      "id": "build-uuid",
+      "name": "CLI Build 2024-01-15T10:30:00Z",
+      "branch": "main",
+      "environment": "test",
+      "status": "completed",
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 150,
+    "limit": 20,
+    "offset": 0,
+    "hasMore": true
+  }
+}
+```
+
+### Update Build Status
+
+Updates the status of a build (typically called by CLI when test suite completes).
+
+**Endpoint:** `PUT /api/sdk/builds/:buildId/status`
+
+**Request Body:**
+
+```json
+{
+  "status": "completed",
+  "executionTimeMs": 45000
+}
+```
+
+**Valid Status Values:**
+
+- `"pending"` → Maps to "created" (build ready for screenshots)
+- `"running"` → Maps to "processing" (build is processing screenshots)
+- `"completed"` → Maps to "completed" (all screenshots processed successfully)
+- `"failed"` → Maps to "failed" (build failed or was terminated)
+
+**Important: Parallel Build Behavior**
+
+For builds with a `parallel_id`, the `"completed"` status is **not allowed** via this endpoint. Instead, you'll receive:
+
+**Response for Parallel Build Completion Attempt (200):**
+
+```json
+{
+  "build_id": "build-uuid",
+  "status": "processing",
+  "message": "Build with parallel_id cannot be finalized via status endpoint. Use POST /api/sdk/parallel/:parallelId/finalize to complete all parallel shards.",
+  "parallel_id": "workflow-12345-attempt-1",
+  "awaiting_finalize_all": true
+}
+```
+
+**Response for Regular Builds (200):**
+
+```json
+{
+  "message": "Build status updated successfully",
+  "build": {
+    "id": "build-uuid",
+    "status": "completed",
+    "execution_time_ms": 45000
+  }
+}
+```
+
+## Screenshot Management
+
+### Upload Screenshot (Real-time)
+
+Uploads a single screenshot to an existing build (used during test execution).
+
+**Endpoint:** `POST /api/sdk/builds/:buildId/screenshots`
+
+**Request Body:**
+
+```json
+{
+  "name": "homepage-desktop-chrome",
+  "image_data": "base64-encoded-image-data",
+  "properties": {
+    "browser": "chrome",
+    "browserVersion": "91.0.4472.124",
+    "device": "desktop",
+    "viewport": {
+      "width": 1920,
+      "height": 1080
+    },
+    "url": "https://example.com/homepage",
+    "selector": ".main-content"
+  }
+}
+```
+
+**Response (201):**
+
+```json
+{
+  "id": "screenshot-uuid",
+  "name": "homepage-desktop-chrome",
+  "build_id": "build-uuid",
+  "status": "pending",
+  "sha256": "abc123...",
+  "isDuplicate": false,
+  "build_screenshot_count": 5,
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### Check Existing Screenshots (Signature-Based Deduplication)
+
+Checks if screenshots with given SHA256 hashes already exist using intelligent signature-based deduplication. Supports both legacy SHA-only format and new signature-based format.
+
+**Endpoint:** `POST /api/sdk/check-shas`
+
+#### Legacy Format (SHA-only)
+
+**Request Body:**
+
+```json
+{
+  "buildId": "build-uuid",
+  "shas": ["abc123def456...", "def456ghi789..."]
+}
+```
+
+**Response (200):**
+
+```json
+{
+  "existing": ["abc123def456..."],
+  "missing": ["def456ghi789..."],
+  "summary": {
+    "total_checked": 2,
+    "existing_count": 1,
+    "missing_count": 1,
+    "screenshots_created": 1,
+    "format_used": "legacy-sha-only"
+  },
+  "screenshots": [
+    {
+      "id": "screenshot-uuid",
+      "name": "auto-generated-name",
+      "sha256": "abc123def456...",
+      "fromExisting": true,
+      "alreadyExisted": false
+    }
+  ]
+}
+```
+
+#### New Format (Signature-Based - Recommended)
+
+**Request Body:**
+
+```json
+{
+  "buildId": "build-uuid",
+  "screenshots": [
+    {
+      "sha256": "abc123def456...",
+      "name": "homepage-login-form",
+      "browser": "chrome",
+      "viewport_width": 1920,
+      "viewport_height": 1080,
+      "url": "https://example.com/login",
+      "selector": ".login-form"
+    },
+    {
+      "sha256": "def456ghi789...",
+      "name": "dashboard-mobile",
+      "browser": "chrome",
+      "viewport_width": 375,
+      "viewport_height": 667
+    }
+  ]
+}
+```
+
+**Response (200):**
+
+```json
+{
+  "existing": [],
+  "missing": ["abc123def456...", "def456ghi789..."],
+  "summary": {
+    "total_checked": 2,
+    "existing_count": 0,
+    "missing_count": 2,
+    "screenshots_created": 0,
+    "format_used": "signature-based"
+  },
+  "results": [
+    {
+      "sha256": "abc123def456...",
+      "exists": true,
+      "reusable": false,
+      "reason": "Different signature (homepage-desktop|1920|chrome vs homepage-login-form|1920|chrome)"
+    },
+    {
+      "sha256": "def456ghi789...",
+      "exists": false,
+      "reusable": false,
+      "reason": "SHA not found"
+    }
+  ],
+  "screenshots": []
+}
+```
+
+#### Signature-Based Logic
+
+The new format uses screenshot **signature** for intelligent deduplication:
+
+- **Signature**: `name + viewport_width + browser` (excludes height as it's variable)
+- **Same SHA + Same Signature**: Screenshot is reusable, returns as "existing"
+- **Same SHA + Different Signature**: Screenshot not reusable, returns as "missing" to force new upload
+- **Different SHA**: New screenshot, returns as "missing"
+
+This ensures screenshots with new names but identical image data create separate records with correct names.
+
+### Batch Upload Screenshots
+
+Uploads multiple screenshot files and/or references existing screenshots by SHA256.
+
+**Endpoint:** `POST /api/sdk/upload`
+
+**Content-Type:** `multipart/form-data`
+
+**Form Fields:**
+
+- `screenshots` (files): Array of screenshot image files
+- `build_id` (optional): ID of existing build to upload to
+- `build_name` (optional): Name for new build if creating one
+- `branch` (optional): Git branch name
+- `commit_sha` (optional): Git commit SHA
+- `commit_message` (optional): Git commit message
+- `common_ancestor_sha` (optional): Common ancestor commit SHA
+- `environment` (optional, default: "test"): Environment name
+- `existing_shas` (optional): JSON array of SHA256 hashes for existing screenshots
+- `config` (optional): JSON configuration object
+- `threshold` (optional): Comparison threshold
+- `parallel_id` (optional): Unique identifier for parallel test execution
+
+**Response (201):**
+
+```json
+{
+  "message": "Screenshots uploaded successfully and queued for processing",
+  "build": {
+    "id": "build-uuid",
+    "name": "CLI Build",
+    "status": "processing"
+  },
+  "screenshots": [],
+  "count": 10,
+  "processing_time_ms": 1250,
+  "efficiency": {
+    "total_processed": 10,
+    "files_uploaded": 7,
+    "existing_shas_requested": 3,
+    "existing_reused": 3,
+    "existing_skipped": 0
+  }
+}
+```
+
+## Comparison Management
+
+### Get Comparison Details
+
+Retrieves detailed information about a specific comparison, including diff images and commit context for debugging.
+
+**Endpoint:** `GET /api/sdk/comparisons/:comparisonId`
+
+**Response (200):**
+
+```json
+{
+  "comparison": {
+    "id": "comparison-uuid",
+    "build_id": "build-uuid",
+    "build_name": "CLI Build",
+    "build_branch": "feature/new-ui",
+    "build_commit_sha": "abc123def456",
+    "build_commit_message": "✨ Add new dashboard",
+    "build_common_ancestor_sha": "def456ghi789",
+    "name": "homepage-desktop-chrome",
+    "status": "completed",
+    "diff_percentage": 2.5,
+    "threshold": 0.1,
+    "has_diff": true,
+    "approval_status": "pending",
+    "current_screenshot_url": "https://storage.example.com/current.png",
+    "baseline_screenshot_url": "https://storage.example.com/baseline.png",
+    "diff_url": "https://storage.example.com/diff.png",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+## Build Collaboration
+
+### Create Build Comment
+
+Creates a comment on a build for team collaboration and feedback.
+
+**Endpoint:** `POST /api/sdk/builds/:buildId/comments`
+
+**Request Body:**
+
+```json
+{
+  "content": "All visual diffs look good, approving this build for deployment.",
+  "type": "general"
+}
+```
+
+**Comment Types:**
+
+- `"general"`: General comment or discussion
+- `"approval"`: Comment indicating approval
+- `"rejection"`: Comment indicating rejection with concerns
+
+**Response (201):**
+
+```json
+{
+  "comment": {
+    "id": "comment-uuid",
+    "build_id": "build-uuid",
+    "user_id": "user-uuid",
+    "author_name": "John Doe",
+    "content": "All visual diffs look good, approving this build for deployment.",
+    "type": "general",
+    "created_at": "2024-01-15T10:30:00Z",
+    "updated_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### List Build Comments
+
+Retrieves all comments for a build, including nested replies.
+
+**Endpoint:** `GET /api/sdk/builds/:buildId/comments`
+
+**Response (200):**
+
+```json
+{
+  "comments": [
+    {
+      "id": "comment-uuid",
+      "build_id": "build-uuid",
+      "user_id": "user-uuid",
+      "author_name": "John Doe",
+      "content": "All visual diffs look good, approving this build for deployment.",
+      "type": "general",
+      "created_at": "2024-01-15T10:30:00Z",
+      "updated_at": "2024-01-15T10:30:00Z",
+      "replies": []
+    }
+  ]
+}
+```
+
+**Note:** For MCP/Claude Code integration, the `profile_photo_url` and `email` fields are filtered out to reduce token usage.
+
+## Comparison Approvals
+
+### Update Comparison Approval Status
+
+Updates the approval status of a comparison.
+
+**Endpoint:** `PUT /api/sdk/comparisons/:comparisonId/approval`
+
+**Request Body:**
+
+```json
+{
+  "approval_status": "approved",
+  "comment": "Visual changes look intentional, layout improvements are good."
+}
+```
+
+**Valid Approval Status Values:**
+
+- `"pending"`: No decision made yet (default)
+- `"approved"`: Comparison approved, changes are intentional
+- `"rejected"`: Comparison rejected, changes need investigation
+- `"auto_approved"`: Automatically approved (identical screenshots)
+
+**Response (200):**
+
+```json
+{
+  "message": "Comparison approval status updated successfully",
+  "comparison": {
+    "id": "comparison-uuid",
+    "approval_status": "approved",
+    "approval_comment": "Visual changes look intentional, layout improvements are good.",
+    "approved_by": "user-uuid",
+    "approved_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### Approve Comparison
+
+Convenient endpoint to approve a comparison with optional comment.
+
+**Endpoint:** `POST /api/sdk/comparisons/:comparisonId/approve`
+
+**Request Body:**
+
+```json
+{
+  "comment": "Homepage redesign looks excellent, ready for production."
+}
+```
+
+**Response (200):**
+
+```json
+{
+  "message": "Comparison approved successfully",
+  "comparison": {
+    "id": "comparison-uuid",
+    "approval_status": "approved",
+    "approval_comment": "Homepage redesign looks excellent, ready for production.",
+    "approved_by": "user-uuid",
+    "approved_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### Reject Comparison
+
+Convenient endpoint to reject a comparison with required reason.
+
+**Endpoint:** `POST /api/sdk/comparisons/:comparisonId/reject`
+
+**Request Body:**
+
+```json
+{
+  "reason": "Button alignment is off by 2px, needs to be fixed before deployment."
+}
+```
+
+**Response (200):**
+
+```json
+{
+  "message": "Comparison rejected successfully",
+  "comparison": {
+    "id": "comparison-uuid",
+    "approval_status": "rejected",
+    "approval_comment": "Button alignment is off by 2px, needs to be fixed before deployment.",
+    "approved_by": "user-uuid",
+    "approved_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+## Review Management
+
+### Get Build Review Summary
+
+Retrieves review status, assignments, and statistics for a build.
+
+**Endpoint:** `GET /api/sdk/builds/:buildId/review-summary`
+
+**Response (200):**
+
+```json
+{
+  "build_id": "build-uuid",
+  "review_status": "in_progress",
+  "assignments": [
+    {
+      "id": "assignment-uuid",
+      "user_id": "user-uuid",
+      "user_name": "Jane Smith",
+      "status": "pending",
+      "assigned_at": "2024-01-15T10:00:00Z",
+      "due_date": null
+    },
+    {
+      "id": "assignment-uuid-2",
+      "user_id": "user-uuid-2",
+      "user_name": "John Doe",
+      "status": "completed",
+      "assigned_at": "2024-01-15T10:00:00Z",
+      "completed_at": "2024-01-15T10:30:00Z",
+      "due_date": null
+    }
+  ],
+  "statistics": {
+    "total_assignments": 2,
+    "pending": 1,
+    "completed": 1,
+    "approved": 0,
+    "rejected": 0
+  }
+}
+```
+
+**Review Status Values:**
+
+- `"pending"`: No reviewers assigned yet
+- `"in_progress"`: Reviewers assigned, waiting for completion
+- `"completed"`: All reviewers have completed their review
+- `"approved"`: Build approved by all reviewers
+- `"rejected"`: Build rejected by one or more reviewers
+
+## Token Management
+
+### Get Token Context
+
+Retrieves information about the current API token and associated organization/project.
+
+**Endpoint:** `GET /api/sdk/token/context`
+
+**Response (200):**
+
+```json
+{
+  "token": {
+    "id": "token-uuid",
+    "name": "CI/CD Token",
+    "prefix": "vzy_"
+  },
+  "organization": {
+    "id": "org-uuid",
+    "name": "My Company",
+    "slug": "my-company"
+  },
+  "project": {
+    "id": "project-uuid",
+    "name": "My App",
+    "slug": "my-app"
+  }
+}
+```
+
+## Error Responses
+
+All endpoints may return these common error responses:
+
+### 400 Bad Request
+
+```json
+{
+  "error": "Validation error message"
+}
+```
+
+### 400 Bad Request (Missing User-Agent)
+
+```json
+{
+  "error": "User-Agent header required"
+}
+```
+
+```json
+{
+  "error": "Invalid User-Agent for SDK request"
+}
+```
+
+### 401 Unauthorized
+
+```json
+{
+  "error": "Invalid or missing API token"
+}
+```
+
+### 404 Not Found
+
+```json
+{
+  "error": "Resource not found"
+}
+```
+
+### 413 Payload Too Large (Storage Quota Exceeded)
+
+```json
+{
+  "error": "Storage quota exceeded",
+  "details": {
+    "currentUsage": "2.5GB",
+    "limit": "5.0GB",
+    "estimatedUpload": "3.0GB",
+    "planName": "Pro"
+  }
+}
+```
+
+### 500 Internal Server Error
+
+```json
+{
+  "error": "Internal server error message"
+}
+```
+
+## Rate Limits
+
+Currently, there are no enforced rate limits on SDK endpoints, but reasonable usage is expected.
+
+## Usage Examples
+
+### Complete Workflow Example
+
+1. **Create a build:**
+
+   ```bash
+   curl -X POST /api/sdk/builds \
+     -H "Authorization: Bearer your-api-token" \
+     -H "User-Agent: Vizzly-CLI/1.0.0" \
+     -H "Content-Type: application/json" \
+     -d '{"build": {"name": "Test Build", "branch": "main"}}'
+   ```
+
+2. **Upload screenshots:**
+
+   ```bash
+   curl -X POST /api/sdk/builds/build-uuid/screenshots \
+     -H "Authorization: Bearer your-api-token" \
+     -H "User-Agent: Vizzly-CLI/1.0.0" \
+     -H "Content-Type: application/json" \
+     -d '{"name": "homepage", "image_data": "base64..."}'
+   ```
+
+3. **Complete the build:**
+   ```bash
+   curl -X PUT /api/sdk/builds/build-uuid/status \
+     -H "Authorization: Bearer your-api-token" \
+     -H "User-Agent: Vizzly-CLI/1.0.0" \
+     -H "Content-Type: application/json" \
+     -d '{"status": "completed"}'
+   ```
+
+## Parallel Build Support
+
+Vizzly supports parallel test execution where multiple test runners (shards) contribute screenshots to a single shared build. This is particularly useful for CI/CD workflows with parallel jobs.
+
+### How Parallel Builds Work
+
+1. **Single Build**: All shards share one build using a common `parallel_id`
+2. **First Shard Creates**: The first shard to call the API creates the build
+3. **Subsequent Shards Reuse**: Other shards find and reuse the existing build
+4. **Automatic Reopening**: Existing build reopening logic handles concurrent uploads
+5. **Shard Completion**: Individual shards can update status to `"failed"` but NOT `"completed"`
+6. **Manual Finalization**: ONLY the finalize endpoint can complete parallel builds
+
+### New Endpoints for Parallel Builds
+
+#### Finalize Parallel Build
+
+Marks a parallel build as completed after all shards finish.
+
+**Endpoint:** `POST /api/sdk/parallel/:parallelId/finalize`
+
+**Response (200):**
+
+```json
+{
+  "message": "Parallel build finalized successfully",
+  "build": {
+    "id": "build-uuid",
+    "status": "completed",
+    "parallel_id": "workflow-12345-attempt-1"
+  }
+}
+```
+
+### Usage Example (GitHub Actions)
+
+```yaml
+jobs:
+  e2e-tests:
+    strategy:
+      matrix:
+        shard: [1/4, 2/4, 3/4, 4/4]
+    steps:
+      - name: Run tests with Vizzly
+        run: |
+          npx vizzly run "npm test -- --shard=${{ matrix.shard }}" \
+            --parallel-id="${{ github.run_id }}-${{ github.run_attempt }}"
+
+  finalize-e2e:
+    needs: e2e-tests
+    runs-on: ubuntu-latest
+    if: always() && needs.e2e-tests.result == 'success'
+    steps:
+      - name: Finalize parallel build
+        run: |
+          curl -X POST "https://api.vizzly.co/api/sdk/parallel/${{ github.run_id }}-${{ github.run_attempt }}/finalize" \
+            -H "Authorization: Bearer ${{ secrets.VIZZLY_TOKEN }}" \
+            -H "User-Agent: GitHub-Actions/1.0"
+```
+
+### Best Practices
+
+- Use GitHub workflow run ID + attempt number for `parallel_id` to ensure uniqueness
+- Always call the finalize endpoint after all shards complete
+- The finalize job should depend on all shard jobs completing successfully
+
+## Hotspot Analysis (TDD Mode)
+
+Hotspot endpoints provide historical data about regions that frequently change across builds (timestamps, dynamic IDs, ads, etc.). This data helps the CLI's TDD mode intelligently filter out known dynamic content.
+
+### Get Screenshot Hotspots
+
+Retrieves hotspot analysis for a specific screenshot name.
+
+**Endpoint:** `GET /api/sdk/screenshots/:screenshotName/hotspots`
+
+**Query Parameters:**
+
+- `windowSize` (optional, default: 20, max: 50): Number of historical builds to analyze
+
+**Response (200):**
+
+```json
+{
+  "screenshot_name": "homepage-desktop-chrome",
+  "hotspot_analysis": {
+    "regions": [
+      {
+        "y1": 100,
+        "y2": 150,
+        "height": 50,
+        "frequency": 0.85,
+        "lineCount": 50
+      }
+    ],
+    "total_builds_analyzed": 15,
+    "confidence": "high",
+    "confidence_score": 85,
+    "confidence_factors": {
+      "build_count": 15,
+      "data_source": "approved",
+      "frequency_consistency": 0.9
+    },
+    "data_source": "approved",
+    "frequency_threshold": 0.7
+  }
+}
+```
+
+**Confidence Values:**
+
+- `"high"`: Strong historical data, reliable hotspot detection
+- `"medium"`: Moderate data, reasonably reliable
+- `"low"`: Limited data, use with caution
+- `"insufficient_data"`: Not enough historical builds to determine hotspots
+
+**Data Source Values:**
+
+- `"approved"`: Hotspots derived from approved builds only (highest quality)
+- `"mixed"`: Includes both approved and unapproved builds
+- `"none"`: No historical data available
+
+### Batch Get Screenshot Hotspots
+
+Retrieves hotspot analysis for multiple screenshots in a single request. More efficient for TDD baseline downloads.
+
+**Endpoint:** `POST /api/sdk/screenshots/hotspots`
+
+**Request Body:**
+
+```json
+{
+  "screenshot_names": [
+    "homepage-desktop-chrome",
+    "dashboard-mobile-safari",
+    "settings-tablet-firefox"
+  ],
+  "windowSize": 20
+}
+```
+
+**Constraints:**
+
+- Maximum 100 screenshot names per request
+- Screenshot names must be valid (no path traversal, max 255 characters)
+
+**Response (200):**
+
+```json
+{
+  "hotspots": {
+    "homepage-desktop-chrome": {
+      "regions": [
+        {
+          "y1": 100,
+          "y2": 150,
+          "height": 50,
+          "frequency": 0.85,
+          "lineCount": 50
+        }
+      ],
+      "total_builds_analyzed": 15,
+      "confidence": "high",
+      "confidence_score": 85,
+      "data_source": "approved"
+    },
+    "dashboard-mobile-safari": {
+      "regions": [],
+      "total_builds_analyzed": 8,
+      "confidence": "medium",
+      "confidence_score": 60,
+      "data_source": "mixed"
+    }
+  },
+  "summary": {
+    "requested": 3,
+    "returned": 2
+  }
+}
+```
+
+**Notes:**
+
+- Only screenshots with `total_builds_analyzed > 0` are included in the response
+- Screenshots without historical data are omitted from the `hotspots` object
+- The `summary` shows how many screenshots were requested vs returned
+
+### Usage Example (CLI TDD Mode)
+
+```bash
+# Fetch hotspots for baseline download
+curl -X POST /api/sdk/screenshots/hotspots \
+  -H "Authorization: Bearer your-api-token" \
+  -H "User-Agent: Vizzly-CLI/1.0.0" \
+  -H "Content-Type: application/json" \
+  -d '{"screenshot_names": ["homepage", "dashboard", "settings"]}'
+```
+
+The CLI uses this data to:
+
+1. Identify regions that historically change frequently
+2. Apply intelligent filtering during local comparisons
+3. Reduce false positives from dynamic content like timestamps or ads
+
+## Implementation Notes
+
+- All image data should be base64 encoded when sent via JSON
+- File uploads use standard multipart/form-data encoding
+- SHA256 hashes are used for deduplication and efficient uploads
+- Build processing happens asynchronously after screenshot upload
+- Screenshots are automatically processed for comparisons when uploaded
+- Builds can be reopened if new screenshots arrive (useful for parallel test execution)
+- Storage quota is checked before accepting uploads
+- **Parallel builds**: Multiple shards share a single build using `parallel_id` for efficient parallel testing
+- **Build finalization**: Use the finalize endpoint to complete parallel builds after all shards finish