initial commit

2025-12-21 11:43:22 -06:00
parent 1f7eb01afb
commit d28de69bcb
28 changed files with 4067 additions and 108 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -0,0 +1,197 @@
+# API Documentation
+
+## Overview
+The Downlink API provides endpoints for fetching YouTube video information and downloading videos/audio in various formats.
+
+## Base URL
+- Development: `http://localhost:3000`
+- Production: `https://your-domain.com`
+
+## Endpoints
+
+### Get Video Information
+
+Retrieve metadata about a YouTube video without downloading it.
+
+**Endpoint**: `POST /api/info`
+
+**Request Body**:
+```json
+{
+  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+}
+```
+
+**Response** (Success):
+```json
+{
+  "success": true,
+  "videoInfo": {
+    "title": "Video Title",
+    "duration": 120,
+    "thumbnail": "https://i.ytimg.com/vi/.../maxresdefault.jpg",
+    "formats": [
+      {
+        "formatId": "137",
+        "ext": "mp4",
+        "resolution": "1920x1080",
+        "filesize": 50000000,
+        "formatNote": "1080p"
+      }
+    ]
+  }
+}
+```
+
+**Response** (Error):
+```json
+{
+  "success": false,
+  "error": "Invalid YouTube URL"
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `400`: Bad Request (invalid URL or missing fields)
+- `500`: Internal Server Error
+
+---
+
+### Download Video/Audio
+
+Download a YouTube video or extract audio in the specified format.
+
+**Endpoint**: `POST /api/download`
+
+**Request Body**:
+```json
+{
+  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+  "format": "mp4",
+  "formatType": "video"
+}
+```
+
+**Format Types**:
+- `"video"`: Download as video file
+- `"audio"`: Extract audio only
+
+**Video Formats**:
+- `"mp4"`: MP4 video (most compatible)
+- `"webm"`: WebM video (web-optimized)
+- `"mkv"`: MKV container (high quality)
+- `"avi"`: AVI video (legacy)
+
+**Audio Formats**:
+- `"mp3"`: MP3 audio (most compatible)
+- `"wav"`: WAV audio (uncompressed)
+- `"m4a"`: M4A audio (Apple format)
+- `"opus"`: Opus audio (modern, efficient)
+
+**Response** (Success):
+```json
+{
+  "success": true,
+  "downloadUrl": "/downloads/1234567890-abc123.mp4",
+  "filename": "Video_Title.mp4",
+  "videoInfo": {
+    "title": "Video Title",
+    "duration": 120,
+    "thumbnail": "https://...",
+    "formats": [...]
+  }
+}
+```
+
+**Response** (Error):
+```json
+{
+  "success": false,
+  "error": "Failed to download video"
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `400`: Bad Request (invalid URL, format, or missing fields)
+- `500`: Internal Server Error
+
+## Error Handling
+
+All endpoints return JSON responses with a `success` boolean field. When `success` is `false`, an `error` field contains the error message.
+
+Common error messages:
+- `"Missing required fields"`: Required request body fields are missing
+- `"Invalid YouTube URL"`: The provided URL is not a valid YouTube URL
+- `"Failed to get video info"`: Error occurred while fetching video metadata
+- `"Failed to download video"`: Error occurred during download/transcoding
+
+## Rate Limiting
+
+Currently, no rate limiting is implemented. Consider adding rate limiting for production use.
+
+## File Storage
+
+Downloaded files are stored in `/public/downloads/` and are accessible via the `downloadUrl` returned in the response. Files are named with a timestamp and random ID to avoid conflicts.
+
+**Note**: Files are not automatically cleaned up. Consider implementing a cleanup job for production.
+
+## Examples
+
+### JavaScript/TypeScript
+
+```typescript
+// Get video info
+const infoResponse = await fetch('/api/info', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+  })
+});
+const infoData = await infoResponse.json();
+
+// Download MP4 video
+const downloadResponse = await fetch('/api/download', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+    format: 'mp4',
+    formatType: 'video'
+  })
+});
+const downloadData = await downloadResponse.json();
+
+if (downloadData.success) {
+  // Download the file
+  window.location.href = downloadData.downloadUrl;
+}
+```
+
+### cURL
+
+```bash
+# Get video info
+curl -X POST http://localhost:3000/api/info \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'
+
+# Download MP3 audio
+curl -X POST http://localhost:3000/api/download \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+    "format":"mp3",
+    "formatType":"audio"
+  }'
+```
+
+## Security Considerations
+
+- URLs are validated to ensure they are YouTube URLs
+- Filenames are sanitized to prevent directory traversal
+- No user authentication is currently implemented
+- Consider adding file size limits and download quotas
+- Implement CORS policies if needed for cross-origin requests