Initial commit: YouTube Studio Flow (backend, frontend, infrastructure, docs)

2026-08-11 12:27:44 +02:00
commit d5af006443
304 changed files with 74604 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Quota API
+
+Base path: `/api/v1/quota`
+
+All endpoints require `Authorization: Bearer <jwt>`.
+
+Related: [[02 - Videos API]], [[01 - System Overview]]
+
+---
+
+## GET /quota/history
+
+Get YouTube API quota usage history for the current team.
+
+**Query parameters:**
+
+| Param | Type | Description |
+|---|---|---|
+| `from` | ISO date | Start of the date range |
+| `to` | ISO date | End of the date range |
+| `channelId` | string | Filter by channel |
+
+**Response:**
+
+```json
+[
+  {
+    "id": "cuid",
+    "datePt": "ISO datetime",
+    "units": 50,
+    "operation": "videos.update",
+    "actionId": "uuid",
+    "actionType": "video_sync",
+    "channelId": "cuid",
+    "videoId": "cuid",
+    "video": {
+      "id": "cuid",
+      "title": "Video Title",
+      "youtubeVideoId": "abc123"
+    }
+  }
+]
+```
+
+**Field notes:**
+
+| Field | Notes |
+|---|---|
+| `datePt` | Timestamp of the quota spend, in Pacific Time (quota resets at midnight PT). |
+| `units` | Number of quota units consumed by the operation. |
+| `operation` | YouTube API method called (e.g. `videos.update`). |
+| `actionType` | Internal action that triggered the spend (e.g. `video_sync`). |
+
+---
+
+## GET /quota/today
+
+Get the total YouTube API quota consumed today (Pacific Time), plus the daily limit and remaining units.
+
+**Response:**
+
+```json
+{
+  "used": 450,
+  "limit": 10000,
+  "remaining": 9550
+}
+```
+
+---
+
+## Notes
+
+- The YouTube API quota limit is **10,000 units per day**, resetting at midnight Pacific Time.
+- A `videos.update` call (triggered by a sync job) costs **50 units**.
+- `QuotaService.canSpend()` and `.spend()` are called before every YouTube write. If the remaining quota is insufficient, the operation is rejected.
+- Quota is tracked per team and per channel.
+- See [[02 - Videos API]] — `POST /videos/:id/sync` for the sync flow that consumes quota.