first commit

doc/socket-events.md

@@ -0,0 +1,256 @@
+# Netflix Scraper API - Socket.IO Events
+
+## Bağlantı
+
+### URL
+```
+ws://localhost:3000
+```
+
+### Transport
+- WebSocket
+- Polling (fallback)
+
+---
+
+## Client → Server Events
+
+### `job:subscribe`
+
+Bir job'ın güncellemelerine abone ol.
+
+**Payload:**
+```typescript
+jobId: string
+```
+
+**Örnek:**
+```javascript
+socket.emit('job:subscribe', '550e8400-e29b-41d4-a716-446655440000');
+```
+
+---
+
+### `job:unsubscribe`
+
+Job aboneliğini iptal et.
+
+**Payload:**
+```typescript
+jobId: string
+```
+
+**Örnek:**
+```javascript
+socket.emit('job:unsubscribe', '550e8400-e29b-41d4-a716-446655440000');
+```
+
+---
+
+## Server → Client Events
+
+### `job:progress`
+
+Job ilerleme durumu güncellendiğinde gönderilir.
+
+**Payload:**
+```typescript
+{
+  jobId: string;
+  progress: number;    // 0-100 arası
+  status: string;      // "pending" | "processing" | "completed" | "failed"
+  step: string;        // Mevcut adım açıklaması
+}
+```
+
+**Örnek:**
+```json
+{
+  "jobId": "550e8400-e29b-41d4-a716-446655440000",
+  "progress": 50,
+  "status": "processing",
+  "step": "Scraping Netflix"
+}
+```
+
+**Adımlar:**
+| Step | Progress | Açıklama |
+|------|----------|----------|
+| `created` | 0 | Job oluşturuldu |
+| `checking_cache` | 10 | Cache kontrol ediliyor |
+| `checking_database` | 30 | Database kontrol ediliyor |
+| `scraping_netflix` | 50 | Netflix'ten veri çekiliyor |
+| `saving_to_database` | 80 | Veritabanına kaydediliyor |
+| `completed` | 100 | İşlem tamamlandı |
+
+---
+
+### `job:completed`
+
+Job başarıyla tamamlandığında gönderilir.
+
+**Payload:**
+```typescript
+{
+  jobId: string;
+  data: GetInfoResponse;
+  source: "cache" | "database" | "netflix";
+}
+```
+
+**Örnek:**
+```json
+{
+  "jobId": "550e8400-e29b-41d4-a716-446655440000",
+  "data": {
+    "title": "Hayata Röveşata Çeken Adam",
+    "year": 2022,
+    "plot": "...",
+    "genres": ["18+", "Komedi"],
+    "cast": ["Tom Hanks", "Mariana Treviño", "Rachel Keller"],
+    "backdrop": "https://..."
+  },
+  "source": "netflix"
+}
+```
+
+---
+
+### `job:error`
+
+Job sırasında hata oluştuğunda gönderilir.
+
+**Payload:**
+```typescript
+{
+  jobId: string;
+  error: {
+    code: string;
+    message: string;
+  }
+}
+```
+
+**Örnek:**
+```json
+{
+  "jobId": "550e8400-e29b-41d4-a716-446655440000",
+  "error": {
+    "code": "SCRAPE_ERROR",
+    "message": "Failed to fetch Netflix page: 403"
+  }
+}
+```
+
+---
+
+## Kullanım Örneği
+
+### JavaScript (Browser)
+
+```javascript
+import { io } from 'socket.io-client';
+
+// Bağlan
+const socket = io('http://localhost:3000');
+
+// Bağlantı başarılı
+socket.on('connect', () => {
+  console.log('Connected:', socket.id);
+});
+
+// Job oluştur (API üzerinden)
+const response = await fetch('http://localhost:3000/api/getinfo/async', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-API-Key': 'your-api-key'
+  },
+  body: JSON.stringify({
+    url: 'https://www.netflix.com/tr/title/81616256'
+  })
+});
+
+const { data: { jobId } } = await response.json();
+
+// Job'a abone ol
+socket.emit('job:subscribe', jobId);
+
+// İlerleme dinle
+socket.on('job:progress', (data) => {
+  console.log(`Progress: ${data.progress}% - ${data.step}`);
+});
+
+// Tamamlanma dinle
+socket.on('job:completed', (data) => {
+  console.log('Completed:', data.data);
+  socket.emit('job:unsubscribe', jobId);
+});
+
+// Hata dinle
+socket.on('job:error', (data) => {
+  console.error('Error:', data.error);
+});
+```
+
+### React Hook
+
+```typescript
+import { useEffect, useState } from 'react';
+import { io, Socket } from 'socket.io-client';
+
+interface JobProgress {
+  jobId: string;
+  progress: number;
+  status: string;
+  step: string;
+}
+
+export function useJobProgress(jobId: string | null) {
+  const [progress, setProgress] = useState<JobProgress | null>(null);
+  const [data, setData] = useState<any>(null);
+  const [error, setError] = useState<any>(null);
+
+  useEffect(() => {
+    if (!jobId) return;
+
+    const socket = io('http://localhost:3000');
+
+    socket.emit('job:subscribe', jobId);
+
+    socket.on('job:progress', setProgress);
+    socket.on('job:completed', (result) => {
+      setData(result.data);
+      socket.emit('job:unsubscribe', jobId);
+    });
+    socket.on('job:error', (err) => {
+      setError(err.error);
+      socket.emit('job:unsubscribe', jobId);
+    });
+
+    return () => {
+      socket.emit('job:unsubscribe', jobId);
+      socket.disconnect();
+    };
+  }, [jobId]);
+
+  return { progress, data, error };
+}
+```
+
+---
+
+## CORS Yapılandırması
+
+Production'da CORS ayarlarını yapılandırın:
+
+```typescript
+// src/config/socket.ts
+io = new Server(httpServer, {
+  cors: {
+    origin: ['https://yourdomain.com', 'https://admin.yourdomain.com'],
+    methods: ['GET', 'POST'],
+    credentials: true,
+  },
+});
+```