"""
OpenAPI 3.0 Configuration for YouTube Summarizer Developer Platform
Comprehensive API documentation with examples, authentication, and SDK generation
"""

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
from typing import Dict, Any

def create_openapi_schema(app: FastAPI) -> Dict[str, Any]:
    """
    Create comprehensive OpenAPI 3.0 schema for the YouTube Summarizer API
    """
    
    if app.openapi_schema:
        return app.openapi_schema
    
    openapi_schema = get_openapi(
        title="YouTube Summarizer Developer Platform API",
        version="4.2.0",
        description="""
# YouTube Summarizer Developer Platform API

The YouTube Summarizer Developer Platform provides powerful AI-driven video content analysis and summarization capabilities. Our API enables developers to integrate advanced YouTube video processing into their applications with enterprise-grade reliability, performance, and scalability.

## Features

### 🎯 Dual Transcript Extraction
- **YouTube Captions**: Fast extraction (2-5 seconds) with automatic fallbacks
- **Whisper AI**: Premium quality transcription with 95%+ accuracy
- **Quality Comparison**: Side-by-side analysis with improvement metrics

### 🚀 Advanced Processing Options
- **Priority Processing**: Urgent, High, Normal, Low priority queues
- **Batch Operations**: Process up to 1,000 videos simultaneously
- **Real-time Updates**: WebSocket streaming and Server-Sent Events
- **Webhook Notifications**: Custom event-driven integrations

### 📊 Analytics & Monitoring
- **Usage Statistics**: Detailed API usage and performance metrics
- **Rate Limiting**: Tiered limits with automatic scaling
- **Quality Metrics**: Transcript accuracy and processing success rates

### 🔧 Developer Experience
- **Multiple SDKs**: Python, JavaScript, and TypeScript libraries
- **OpenAPI 3.0**: Complete specification with code generation
- **Comprehensive Examples**: Real-world usage patterns and best practices
- **MCP Integration**: Model Context Protocol support for AI development tools

## Authentication

All API endpoints require authentication using API keys. Include your API key in the `Authorization` header:

```
Authorization: Bearer ys_pro_abc123_def456...
```

### API Key Tiers

| Tier | Rate Limit | Batch Size | Features |
|------|------------|------------|----------|
| Free | 100/hour | 10 videos | Basic processing |
| Pro | 2,000/hour | 100 videos | Priority processing, webhooks |
| Enterprise | 10,000/hour | 1,000 videos | Custom models, SLA |

## Rate Limiting

API requests are rate-limited based on your subscription tier. Rate limit information is returned in response headers:

- `X-RateLimit-Remaining`: Requests remaining in current period
- `X-RateLimit-Reset`: UTC timestamp when rate limit resets
- `Retry-After`: Seconds to wait before retrying (when rate limited)

## Error Handling

The API uses conventional HTTP response codes and returns detailed error information:

```json
{
  "error": {
    "code": "INVALID_VIDEO_URL",
    "message": "The provided URL is not a valid YouTube video",
    "details": {
      "url": "https://example.com/invalid",
      "supported_formats": ["youtube.com/watch", "youtu.be"]
    }
  },
  "request_id": "req_abc123"
}
```

## Webhooks

Configure webhooks to receive real-time notifications about job status changes:

### Supported Events
- `job.started` - Processing begins
- `job.progress` - Progress updates (every 10%)
- `job.completed` - Processing finished successfully
- `job.failed` - Processing encountered an error
- `batch.completed` - Batch job finished

### Webhook Payload
```json
{
  "event": "job.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "job_id": "job_abc123",
    "status": "completed",
    "result_url": "/api/v2/job/job_abc123/result"
  }
}
```

## SDKs and Libraries

Official SDKs are available for popular programming languages:

### Python SDK
```python
from youtube_summarizer import YouTubeSummarizer

client = YouTubeSummarizer(api_key="ys_pro_...")
result = await client.extract_transcript(
    video_url="https://youtube.com/watch?v=example",
    source="whisper"
)
```

### JavaScript/TypeScript SDK
```javascript
import { YouTubeSummarizer } from '@youtube-summarizer/js-sdk';

const client = new YouTubeSummarizer({ apiKey: 'ys_pro_...' });
const result = await client.extractTranscript({
  videoUrl: 'https://youtube.com/watch?v=example',
  source: 'whisper'
});
```

## Model Context Protocol (MCP)

The API supports MCP for integration with AI development tools like Claude Code:

```json
{
  "mcpServers": {
    "youtube-summarizer": {
      "command": "youtube-summarizer-mcp",
      "args": ["--api-key", "ys_pro_..."]
    }
  }
}
```

## Support

- **Documentation**: [docs.youtube-summarizer.com](https://docs.youtube-summarizer.com)
- **Support**: [support@youtube-summarizer.com](mailto:support@youtube-summarizer.com)
- **Status Page**: [status.youtube-summarizer.com](https://status.youtube-summarizer.com)
- **GitHub**: [github.com/youtube-summarizer/api](https://github.com/youtube-summarizer/api)
        """,
        routes=app.routes,
    )
    
    # Add comprehensive server information
    openapi_schema["servers"] = [
        {
            "url": "https://api.youtube-summarizer.com",
            "description": "Production API server"
        },
        {
            "url": "https://staging.youtube-summarizer.com",
            "description": "Staging server for testing"
        },
        {
            "url": "http://localhost:8000",
            "description": "Local development server"
        }
    ]
    
    # Add security schemes
    openapi_schema["components"]["securitySchemes"] = {
        "ApiKeyAuth": {
            "type": "http",
            "scheme": "bearer",
            "bearerFormat": "API Key",
            "description": "API key authentication. Format: `ys_{tier}_{key_id}_{secret}`"
        },
        "WebhookAuth": {
            "type": "apiKey",
            "in": "header", 
            "name": "X-Webhook-Signature",
            "description": "HMAC-SHA256 signature of webhook payload"
        }
    }
    
    # Add global security requirement
    openapi_schema["security"] = [{"ApiKeyAuth": []}]
    
    # Add comprehensive contact and license information
    openapi_schema["info"]["contact"] = {
        "name": "YouTube Summarizer API Support",
        "url": "https://docs.youtube-summarizer.com/support",
        "email": "support@youtube-summarizer.com"
    }
    
    openapi_schema["info"]["license"] = {
        "name": "MIT License",
        "url": "https://opensource.org/licenses/MIT"
    }
    
    openapi_schema["info"]["termsOfService"] = "https://youtube-summarizer.com/terms"
    
    # Add external documentation links
    openapi_schema["externalDocs"] = {
        "description": "Complete Developer Documentation",
        "url": "https://docs.youtube-summarizer.com"
    }
    
    # Add custom extensions
    openapi_schema["x-logo"] = {
        "url": "https://youtube-summarizer.com/logo.png",
        "altText": "YouTube Summarizer Logo"
    }
    
    # Add comprehensive tags with descriptions
    if "tags" not in openapi_schema:
        openapi_schema["tags"] = []
    
    openapi_schema["tags"].extend([
        {
            "name": "Authentication",
            "description": "API key management and authentication endpoints"
        },
        {
            "name": "Transcripts",
            "description": "Video transcript extraction with dual-source support"
        },
        {
            "name": "Batch Processing",
            "description": "Multi-video batch processing operations"
        },
        {
            "name": "Jobs",
            "description": "Job status monitoring and management"
        },
        {
            "name": "Analytics",
            "description": "Usage statistics and performance metrics"
        },
        {
            "name": "Webhooks",
            "description": "Real-time event notifications"
        },
        {
            "name": "Developer Tools",
            "description": "SDK generation and development utilities"
        },
        {
            "name": "Health",
            "description": "Service health and status monitoring"
        }
    ])
    
    # Add example responses and schemas
    if "components" not in openapi_schema:
        openapi_schema["components"] = {}
    
    if "examples" not in openapi_schema["components"]:
        openapi_schema["components"]["examples"] = {}
    
    # Add comprehensive examples
    openapi_schema["components"]["examples"].update({
        "YouTubeVideoURL": {
            "summary": "Standard YouTube video URL",
            "value": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
        },
        "YouTubeShortURL": {
            "summary": "YouTube short URL",
            "value": "https://youtu.be/dQw4w9WgXcQ"
        },
        "TranscriptRequestBasic": {
            "summary": "Basic transcript extraction",
            "value": {
                "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                "transcript_source": "youtube",
                "priority": "normal"
            }
        },
        "TranscriptRequestAdvanced": {
            "summary": "Advanced transcript extraction with Whisper",
            "value": {
                "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                "transcript_source": "whisper",
                "whisper_model_size": "small",
                "priority": "high",
                "webhook_url": "https://myapp.com/webhooks/transcript",
                "include_quality_analysis": True,
                "tags": ["tutorial", "ai", "development"]
            }
        },
        "BatchProcessingRequest": {
            "summary": "Batch processing multiple videos",
            "value": {
                "video_urls": [
                    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                    "https://www.youtube.com/watch?v=oHg5SJYRHA0",
                    "https://www.youtube.com/watch?v=iik25wqIuFo"
                ],
                "batch_name": "AI Tutorial Series",
                "transcript_source": "both",
                "priority": "normal",
                "webhook_url": "https://myapp.com/webhooks/batch",
                "parallel_processing": True,
                "max_concurrent_jobs": 3
            }
        },
        "SuccessfulJobResponse": {
            "summary": "Successful job creation",
            "value": {
                "job_id": "job_abc123def456",
                "status": "queued",
                "priority": "normal",
                "created_at": "2024-01-15T10:30:00Z",
                "estimated_completion": "2024-01-15T10:32:00Z",
                "progress_percentage": 0.0,
                "current_stage": "queued",
                "webhook_url": "https://myapp.com/webhooks/transcript",
                "metadata": {
                    "user_id": "user_xyz789",
                    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                    "transcript_source": "youtube"
                }
            }
        },
        "ErrorResponse": {
            "summary": "Error response example",
            "value": {
                "error": {
                    "code": "INVALID_VIDEO_URL",
                    "message": "The provided URL is not a valid YouTube video",
                    "details": {
                        "url": "https://example.com/invalid",
                        "supported_formats": [
                            "https://www.youtube.com/watch?v={video_id}",
                            "https://youtu.be/{video_id}",
                            "https://www.youtube.com/embed/{video_id}"
                        ]
                    }
                },
                "request_id": "req_abc123def456"
            }
        }
    })
    
    # Add webhook examples
    openapi_schema["components"]["examples"].update({
        "WebhookJobStarted": {
            "summary": "Job started webhook",
            "value": {
                "event": "job.started",
                "timestamp": "2024-01-15T10:30:00Z",
                "data": {
                    "job_id": "job_abc123",
                    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                    "transcript_source": "whisper",
                    "priority": "high"
                }
            }
        },
        "WebhookJobProgress": {
            "summary": "Job progress webhook",
            "value": {
                "event": "job.progress",
                "timestamp": "2024-01-15T10:31:00Z",
                "data": {
                    "job_id": "job_abc123",
                    "status": "processing",
                    "progress": 45.0,
                    "current_stage": "extracting_transcript",
                    "estimated_completion": "2024-01-15T10:32:30Z"
                }
            }
        },
        "WebhookJobCompleted": {
            "summary": "Job completed webhook",
            "value": {
                "event": "job.completed",
                "timestamp": "2024-01-15T10:32:15Z",
                "data": {
                    "job_id": "job_abc123",
                    "status": "completed",
                    "result_url": "/api/v2/job/job_abc123/result",
                    "processing_time_seconds": 125.3,
                    "quality_score": 0.94
                }
            }
        }
    })
    
    app.openapi_schema = openapi_schema
    return app.openapi_schema

def add_openapi_examples():
    """
    Add comprehensive examples to OpenAPI schema components
    """
    return {
        # Request Examples
        "video_urls": {
            "youtube_standard": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
            "youtube_short": "https://youtu.be/dQw4w9WgXcQ",
            "youtube_embed": "https://www.youtube.com/embed/dQw4w9WgXcQ",
            "youtube_playlist": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=PLxyz",
            "youtube_mobile": "https://m.youtube.com/watch?v=dQw4w9WgXcQ"
        },
        
        # Response Examples
        "transcript_extraction_responses": {
            "youtube_success": {
                "job_id": "job_abc123",
                "status": "completed",
                "transcript_source": "youtube",
                "processing_time": 3.2,
                "transcript": "Welcome to this amazing tutorial...",
                "metadata": {
                    "word_count": 1250,
                    "duration": 600,
                    "language": "en",
                    "quality_score": 0.87
                }
            },
            "whisper_success": {
                "job_id": "job_def456", 
                "status": "completed",
                "transcript_source": "whisper",
                "processing_time": 45.8,
                "transcript": "Welcome to this amazing tutorial...",
                "metadata": {
                    "word_count": 1280,
                    "duration": 600,
                    "language": "en",
                    "model_size": "small",
                    "confidence_score": 0.95,
                    "quality_score": 0.94
                }
            },
            "comparison_success": {
                "job_id": "job_ghi789",
                "status": "completed",
                "transcript_source": "both",
                "processing_time": 48.5,
                "youtube_transcript": "Welcome to this amazing tutorial...",
                "whisper_transcript": "Welcome to this amazing tutorial...",
                "quality_comparison": {
                    "similarity_score": 0.92,
                    "punctuation_improvement": 0.15,
                    "capitalization_improvement": 0.08,
                    "technical_terms_improved": ["API", "JavaScript", "TypeScript"],
                    "recommendation": "whisper"
                }
            }
        },
        
        # Error Examples
        "error_responses": {
            "invalid_url": {
                "error": {
                    "code": "INVALID_VIDEO_URL",
                    "message": "Invalid YouTube video URL format",
                    "details": {"url": "https://example.com/video"}
                }
            },
            "video_not_found": {
                "error": {
                    "code": "VIDEO_NOT_FOUND",
                    "message": "YouTube video not found or unavailable",
                    "details": {"video_id": "invalid123"}
                }
            },
            "rate_limit_exceeded": {
                "error": {
                    "code": "RATE_LIMIT_EXCEEDED", 
                    "message": "API rate limit exceeded",
                    "details": {
                        "limit": 1000,
                        "period": "hour",
                        "reset_time": "2024-01-15T11:00:00Z"
                    }
                }
            }
        }
    }

def create_postman_collection(base_url: str = "https://api.youtube-summarizer.com") -> Dict[str, Any]:
    """
    Generate Postman collection for API testing
    """
    return {
        "info": {
            "name": "YouTube Summarizer API",
            "description": "Complete API collection for YouTube Summarizer Developer Platform",
            "version": "4.2.0",
            "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
        },
        "auth": {
            "type": "bearer",
            "bearer": [
                {
                    "key": "token",
                    "value": "{{api_key}}",
                    "type": "string"
                }
            ]
        },
        "variable": [
            {
                "key": "base_url",
                "value": base_url,
                "type": "string"
            },
            {
                "key": "api_key",
                "value": "ys_pro_your_key_here",
                "type": "string"
            }
        ],
        "item": [
            {
                "name": "Health Check",
                "request": {
                    "method": "GET",
                    "header": [],
                    "url": {
                        "raw": "{{base_url}}/api/v2/health",
                        "host": ["{{base_url}}"],
                        "path": ["api", "v2", "health"]
                    }
                }
            },
            {
                "name": "Extract Transcript - YouTube",
                "request": {
                    "method": "POST",
                    "header": [
                        {
                            "key": "Content-Type",
                            "value": "application/json"
                        }
                    ],
                    "body": {
                        "mode": "raw",
                        "raw": json.dumps({
                            "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                            "transcript_source": "youtube",
                            "priority": "normal"
                        }, indent=2)
                    },
                    "url": {
                        "raw": "{{base_url}}/api/v2/transcript/extract",
                        "host": ["{{base_url}}"],
                        "path": ["api", "v2", "transcript", "extract"]
                    }
                }
            },
            {
                "name": "Extract Transcript - Whisper AI",
                "request": {
                    "method": "POST",
                    "header": [
                        {
                            "key": "Content-Type",
                            "value": "application/json"
                        }
                    ],
                    "body": {
                        "mode": "raw",
                        "raw": json.dumps({
                            "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                            "transcript_source": "whisper",
                            "whisper_model_size": "small",
                            "priority": "high",
                            "include_quality_analysis": True
                        }, indent=2)
                    },
                    "url": {
                        "raw": "{{base_url}}/api/v2/transcript/extract",
                        "host": ["{{base_url}}"],
                        "path": ["api", "v2", "transcript", "extract"]
                    }
                }
            },
            {
                "name": "Batch Processing",
                "request": {
                    "method": "POST",
                    "header": [
                        {
                            "key": "Content-Type",
                            "value": "application/json"
                        }
                    ],
                    "body": {
                        "mode": "raw",
                        "raw": json.dumps({
                            "video_urls": [
                                "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                                "https://www.youtube.com/watch?v=oHg5SJYRHA0"
                            ],
                            "batch_name": "Test Batch",
                            "transcript_source": "youtube",
                            "parallel_processing": True
                        }, indent=2)
                    },
                    "url": {
                        "raw": "{{base_url}}/api/v2/batch/process",
                        "host": ["{{base_url}}"],
                        "path": ["api", "v2", "batch", "process"]
                    }
                }
            },
            {
                "name": "Get Job Status",
                "request": {
                    "method": "GET",
                    "header": [],
                    "url": {
                        "raw": "{{base_url}}/api/v2/job/{{job_id}}",
                        "host": ["{{base_url}}"],
                        "path": ["api", "v2", "job", "{{job_id}}"]
                    }
                }
            },
            {
                "name": "Usage Statistics",
                "request": {
                    "method": "GET", 
                    "header": [],
                    "url": {
                        "raw": "{{base_url}}/api/v2/usage/stats",
                        "host": ["{{base_url}}"],
                        "path": ["api", "v2", "usage", "stats"]
                    }
                }
            }
        ]
    }

def generate_sdk_templates() -> Dict[str, str]:
    """
    Generate SDK templates for different programming languages
    """
    return {
        "python": '''
"""
YouTube Summarizer Python SDK
Auto-generated from OpenAPI specification
"""

import httpx
import asyncio
from typing import Dict, Any, Optional, List
from dataclasses import dataclass
from enum import Enum

class TranscriptSource(str, Enum):
    YOUTUBE = "youtube"
    WHISPER = "whisper"
    BOTH = "both"

@dataclass
class TranscriptRequest:
    video_url: str
    transcript_source: TranscriptSource = TranscriptSource.YOUTUBE
    priority: str = "normal"
    webhook_url: Optional[str] = None

class YouTubeSummarizer:
    def __init__(self, api_key: str, base_url: str = "https://api.youtube-summarizer.com"):
        self.api_key = api_key
        self.base_url = base_url
        self.client = httpx.AsyncClient(
            headers={"Authorization": f"Bearer {api_key}"}
        )
    
    async def extract_transcript(self, request: TranscriptRequest) -> Dict[str, Any]:
        """Extract transcript from YouTube video"""
        response = await self.client.post(
            f"{self.base_url}/api/v2/transcript/extract",
            json=request.__dict__
        )
        response.raise_for_status()
        return response.json()
    
    async def get_job_status(self, job_id: str) -> Dict[str, Any]:
        """Get job status by ID"""
        response = await self.client.get(
            f"{self.base_url}/api/v2/job/{job_id}"
        )
        response.raise_for_status()
        return response.json()
    
    async def close(self):
        """Close the HTTP client"""
        await self.client.aclose()
        ''',
        
        "javascript": '''
/**
 * YouTube Summarizer JavaScript SDK
 * Auto-generated from OpenAPI specification
 */

class YouTubeSummarizer {
    constructor({ apiKey, baseUrl = 'https://api.youtube-summarizer.com' }) {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
    }

    async _request(method, path, data = null) {
        const url = `${this.baseUrl}${path}`;
        const options = {
            method,
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json',
            },
        };

        if (data) {
            options.body = JSON.stringify(data);
        }

        const response = await fetch(url, options);
        
        if (!response.ok) {
            throw new Error(`API request failed: ${response.status} ${response.statusText}`);
        }

        return response.json();
    }

    /**
     * Extract transcript from YouTube video
     * @param {Object} request - Transcript extraction request
     * @returns {Promise<Object>} Job response
     */
    async extractTranscript(request) {
        return this._request('POST', '/api/v2/transcript/extract', request);
    }

    /**
     * Get job status by ID
     * @param {string} jobId - Job ID
     * @returns {Promise<Object>} Job status
     */
    async getJobStatus(jobId) {
        return this._request('GET', `/api/v2/job/${jobId}`);
    }

    /**
     * Process multiple videos in batch
     * @param {Object} request - Batch processing request
     * @returns {Promise<Object>} Batch job response
     */
    async batchProcess(request) {
        return this._request('POST', '/api/v2/batch/process', request);
    }
}

// Export for different module systems
if (typeof module !== 'undefined' && module.exports) {
    module.exports = YouTubeSummarizer;
} else if (typeof window !== 'undefined') {
    window.YouTubeSummarizer = YouTubeSummarizer;
}
        '''
    }