main

2026-02-10 12:27:14 +03:00
parent 80f53511d8
commit fc88faddb9
141 changed files with 35961 additions and 101 deletions
--- a/docs/API_CONTRACTS.md
+++ b/docs/API_CONTRACTS.md
@@ -0,0 +1,337 @@
+# Content Hunter - API Contracts
+
+## Overview
+Complete API reference for all Content Hunter backend endpoints. All endpoints are RESTful and return JSON.
+
+## Base URL
+```
+Production: https://api.contenthunter.app/v1
+Development: http://localhost:3000/v1
+```
+
+## Authentication
+All protected endpoints require Bearer token:
+```
+Authorization: Bearer <access_token>
+```
+
+---
+
+## 1. Authentication (`/auth`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/auth/register` | Register new user | ❌ |
+| POST | `/auth/login` | Login with email/password | ❌ |
+| POST | `/auth/google` | Google OAuth login | ❌ |
+| POST | `/auth/refresh` | Refresh access token | ⚠️ |
+| POST | `/auth/logout` | Logout user | ✅ |
+| POST | `/auth/forgot-password` | Request password reset | ❌ |
+| POST | `/auth/reset-password` | Reset password with token | ❌ |
+
+### Request/Response Examples
+
+```typescript
+// POST /auth/register
+Request: { email: string; password: string; name: string; }
+Response: { user: User; accessToken: string; refreshToken: string; }
+
+// POST /auth/login
+Request: { email: string; password: string; }
+Response: { user: User; accessToken: string; refreshToken: string; }
+```
+
+---
+
+## 2. Users (`/users`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/users/me` | Get current user | ✅ |
+| PUT | `/users/me` | Update profile | ✅ |
+| PUT | `/users/me/preferences` | Update preferences | ✅ |
+| GET | `/users/me/credits` | Get credit balance | ✅ |
+| DELETE | `/users/me` | Delete account | ✅ |
+
+---
+
+## 3. Workspaces (`/workspaces`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/workspaces` | List user workspaces | ✅ |
+| POST | `/workspaces` | Create workspace | ✅ |
+| GET | `/workspaces/:id` | Get workspace | ✅ |
+| PUT | `/workspaces/:id` | Update workspace | ✅ |
+| DELETE | `/workspaces/:id` | Delete workspace | ✅ |
+| POST | `/workspaces/:id/members` | Add member | ✅ |
+| DELETE | `/workspaces/:id/members/:userId` | Remove member | ✅ |
+
+---
+
+## 4. Content (`/content`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/content` | List content | ✅ |
+| POST | `/content` | Create content | ✅ |
+| GET | `/content/:id` | Get content | ✅ |
+| PUT | `/content/:id` | Update content | ✅ |
+| DELETE | `/content/:id` | Delete content | ✅ |
+| POST | `/content/:id/variations` | Generate variations | ✅ |
+| POST | `/content/:id/repurpose` | Repurpose content | ✅ |
+
+---
+
+## 5. Content Generation (`/content-generation`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/content-generation/generate` | Generate content | ✅ |
+| POST | `/content-generation/hooks` | Generate hooks | ✅ |
+| POST | `/content-generation/threads` | Generate thread | ✅ |
+| POST | `/content-generation/captions` | Generate captions | ✅ |
+| POST | `/content-generation/scripts` | Generate video script | ✅ |
+| GET | `/content-generation/styles` | Get writing styles | ✅ |
+| POST | `/content-generation/styles` | Create custom style | ✅ |
+
+### Content Generation Request
+```typescript
+{
+  type: 'post' | 'thread' | 'carousel' | 'video_script' | 'newsletter';
+  platform: 'x' | 'instagram' | 'linkedin' | 'tiktok' | 'youtube';
+  topic: string;
+  style?: string;
+  language?: ContentLanguage;
+  niche?: string;
+  variations?: number; // 1-3
+}
+```
+
+---
+
+## 6. Trends (`/trends`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/trends` | Get aggregated trends | ✅ |
+| GET | `/trends/google` | Google Trends | ✅ |
+| GET | `/trends/twitter` | Twitter/X trends | ✅ |
+| GET | `/trends/reddit` | Reddit trends | ✅ |
+| GET | `/trends/news` | News trends | ✅ |
+| POST | `/trends/youtube/transcript` | Extract YouTube transcript | ✅ |
+| POST | `/trends/scrape` | Scrape web page | ✅ |
+| POST | `/trends/scan` | Manual trend scan | ✅ |
+
+---
+
+## 7. Source Accounts (`/source-accounts`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/source-accounts` | List source accounts | ✅ |
+| POST | `/source-accounts` | Add source account | ✅ |
+| GET | `/source-accounts/:id` | Get source account | ✅ |
+| DELETE | `/source-accounts/:id` | Remove source | ✅ |
+| GET | `/source-accounts/:id/posts` | Get source posts | ✅ |
+| POST | `/source-accounts/:id/analyze` | Analyze viral post | ✅ |
+
+---
+
+## 8. Neuro Marketing (`/neuro-marketing`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/neuro-marketing/triggers` | Get psychology triggers | ✅ |
+| GET | `/neuro-marketing/hooks` | Get emotional hooks | ✅ |
+| GET | `/neuro-marketing/patterns` | Get engagement patterns | ✅ |
+| POST | `/neuro-marketing/analyze` | Analyze content psychology | ✅ |
+| POST | `/neuro-marketing/optimize` | Optimize for engagement | ✅ |
+
+---
+
+## 9. SEO (`/seo`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/seo/keywords` | Search keywords | ✅ |
+| POST | `/seo/analyze` | Analyze content SEO | ✅ |
+| POST | `/seo/optimize` | Optimize for SEO | ✅ |
+| GET | `/seo/suggestions` | Get keyword suggestions | ✅ |
+
+---
+
+## 10. Visual Generation (`/visual-generation`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/visual-generation/image` | Generate image | ✅ |
+| POST | `/visual-generation/video` | Generate video (Veo) | ✅ |
+| GET | `/visual-generation/templates` | Get templates | ✅ |
+| POST | `/visual-generation/templates` | Create template | ✅ |
+| PUT | `/visual-generation/templates/:id` | Update template | ✅ |
+
+---
+
+## 11. Video & Thumbnails (`/video-thumbnail`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/video-thumbnail/script` | Generate video script | ✅ |
+| POST | `/video-thumbnail/thumbnail` | Generate thumbnail | ✅ |
+| POST | `/video-thumbnail/title` | Optimize video title | ✅ |
+| GET | `/video-thumbnail/patterns` | Get thumbnail patterns | ✅ |
+
+---
+
+## 12. Social Integration (`/social`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/social/accounts` | List connected accounts | ✅ |
+| POST | `/social/connect/:platform` | Connect platform | ✅ |
+| DELETE | `/social/disconnect/:platform` | Disconnect platform | ✅ |
+| POST | `/social/publish` | Publish content | ✅ |
+| GET | `/social/status/:postId` | Get publish status | ✅ |
+
+---
+
+## 13. Scheduling (`/scheduling`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/scheduling/calendar` | Get calendar view | ✅ |
+| POST | `/scheduling/calendar/event` | Create event | ✅ |
+| PUT | `/scheduling/calendar/event/:id` | Update event | ✅ |
+| DELETE | `/scheduling/calendar/event/:id` | Delete event | ✅ |
+| GET | `/scheduling/workflows` | Get workflow templates | ✅ |
+| POST | `/scheduling/workflows` | Create workflow | ✅ |
+| GET | `/scheduling/timing/:platform` | Get optimal times | ✅ |
+| GET | `/scheduling/queue` | Get post queue | ✅ |
+| POST | `/scheduling/queue` | Add to queue | ✅ |
+| GET | `/scheduling/automation` | Get automation rules | ✅ |
+| POST | `/scheduling/automation` | Create automation | ✅ |
+
+---
+
+## 14. Analytics (`/analytics`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/analytics/engagement` | Record engagement | ✅ |
+| GET | `/analytics/dashboard/overview` | Dashboard overview | ✅ |
+| GET | `/analytics/dashboard/heatmap` | Engagement heatmap | ✅ |
+| GET | `/analytics/gold-posts` | Get gold posts | ✅ |
+| POST | `/analytics/ab-tests` | Create A/B test | ✅ |
+| GET | `/analytics/ab-tests/:id` | Get test results | ✅ |
+| GET | `/analytics/growth-formulas` | Get growth formulas | ✅ |
+| POST | `/analytics/growth-formulas` | Create formula | ✅ |
+| GET | `/analytics/webhooks` | List webhooks | ✅ |
+| POST | `/analytics/webhooks` | Create webhook | ✅ |
+
+---
+
+## 15. Subscriptions (`/subscriptions`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/subscriptions/plans` | Get available plans | ❌ |
+| GET | `/subscriptions/current` | Get current subscription | ✅ |
+| POST | `/subscriptions/checkout` | Create checkout session | ✅ |
+| POST | `/subscriptions/cancel` | Cancel subscription | ✅ |
+| POST | `/subscriptions/webhook` | Stripe webhook | ❌ |
+
+---
+
+## 16. Credits (`/credits`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/credits/balance` | Get balance | ✅ |
+| GET | `/credits/history` | Get usage history | ✅ |
+| POST | `/credits/purchase` | Purchase credits | ✅ |
+| GET | `/credits/packages` | Get credit packages | ❌ |
+
+---
+
+## 17. Languages (`/languages`)
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| GET | `/languages` | List supported languages | ❌ |
+| GET | `/languages/:code` | Get language details | ❌ |
+| GET | `/languages/:code/guide` | Get cultural guide | ❌ |
+
+---
+
+## Error Response Format
+
+All errors follow this structure:
+```typescript
+{
+  statusCode: number;
+  message: string;
+  error: string;
+  timestamp: string;
+  path: string;
+}
+```
+
+### Common Status Codes
+| Code | Description |
+|------|-------------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 429 | Rate Limited |
+| 500 | Server Error |
+
+---
+
+## Rate Limits
+
+| Plan | Requests/min | Requests/day |
+|------|-------------|--------------|
+| Free | 10 | 100 |
+| Starter | 30 | 1,000 |
+| Pro | 60 | 5,000 |
+| Ultimate | 100 | 20,000 |
+| Enterprise | Unlimited | Unlimited |
+
+---
+
+## Pagination
+
+List endpoints support pagination:
+```
+GET /content?page=1&limit=20&sort=createdAt&order=desc
+```
+
+Response includes:
+```typescript
+{
+  data: T[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+  }
+}
+```
+
+---
+
+## WebSocket Events
+
+Connect to: `wss://api.contenthunter.app/ws`
+
+| Event | Direction | Description |
+|-------|-----------|-------------|
+| `content.generated` | Server→Client | Content generation complete |
+| `publish.status` | Server→Client | Publish status update |
+| `trend.alert` | Server→Client | New trend detected |
+| `gold.detected` | Server→Client | Gold post detected |