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,125 @@
+# Templates API
+
+Base path: `/api/v1/templates`
+
+All endpoints require `Authorization: Bearer <jwt>`.
+
+Related: [[02 - Description Engine]], [[03 - Blocks API]], [[02 - Videos API]]
+
+---
+
+## GET /templates
+
+List all active templates for the current team.
+
+**Response:** `Template[]`
+
+---
+
+## GET /templates/:id
+
+Get a single template by ID.
+
+**Response:** `Template`
+
+---
+
+## POST /templates
+
+Create a new template. Requires `EDITOR` role.
+
+**Request body:**
+
+```json
+{
+  "name": "string",
+  "description": "string",
+  "defaultBlocks": ["blockId", "freetext:uuid"],
+  "defaultOverrides": {},
+  "rules": {
+    "requiredLinks": ["https://..."]
+  },
+  "variables": {},
+  "videoFields": {
+    "privacyStatus": "PUBLIC",
+    "tags": ["tag1"]
+  }
+}
+```
+
+**Field notes:**
+
+| Field | Notes |
+|---|---|
+| `description` | Optional human-readable description of the template's purpose. |
+| `defaultBlocks` | Ordered list of block IDs. May include `freetext:uuid` entries for inline free-text entries. |
+| `defaultOverrides` | Per-block overrides in the same shape as `VideoConfig.blockOverrides`. Stores free-text content keyed by `freetext:*` ID. |
+| `rules` | Optional lint/validation rules applied when the template is in use, e.g. required links. |
+| `variables` | Default variable values to seed into `VideoConfig.variableValues` when the template is applied. |
+| `videoFields` | Video metadata fields to apply when the template is applied to a video (e.g. `privacyStatus`, `tags`). |
+
+---
+
+## PATCH /templates/:id
+
+Update a template. Requires `EDITOR` role.
+
+**Request body:** Same fields as `POST /templates`, all optional.
+
+---
+
+## DELETE /templates/:id
+
+Delete a template. Requires `ADMIN` role.
+
+---
+
+## POST /templates/:id/preview
+
+Render a preview of the template's description for a given variable context. Does not require a video — useful for inspecting template output before applying.
+
+**Request body:**
+
+```json
+{
+  "variableValues": {
+    "custom_var": "value"
+  }
+}
+```
+
+**Response:**
+
+```json
+{ "rendered": "string" }
+```
+
+---
+
+## Version history
+
+`TemplateVersion` rows are written to the database on every `PATCH /templates/:id` call, storing a snapshot of the template content before the update. When a template is deleted, its version rows are also deleted.
+
+There is **no `GET /templates/:id/versions` endpoint**. The version history is stored but unreachable via the API. Template version history is not exposed to the frontend. See the backlog.
+
+---
+
+## POST /templates/:templateId/apply/:videoId
+
+Apply a template to a specific video. Requires `EDITOR` role.
+
+When applied:
+- `template.defaultBlocks` is written to `VideoConfig.blockOrder`
+- `template.defaultOverrides` is written to `VideoConfig.blockOverrides`
+- If `applyVideoFields` is `true`, video metadata fields from `template.videoFields` are applied to the video row
+
+**Request body:**
+
+```json
+{
+  "applyVideoFields": true,
+  "applyDescriptionConfig": true
+}
+```
+
+**Response:** Updated `VideoDetail`