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,93 @@
+# Collaborators API
+
+Base path: `/api/v1/collaborators`
+
+All endpoints require `Authorization: Bearer <jwt>`.
+
+Related: [[02 - Description Engine]], [[03 - Blocks API]], [[04 - Database Schema]]
+
+---
+
+## GET /collaborators
+
+List all collaborators for the current team.
+
+**Response:** `Collaborator[]`
+
+---
+
+## GET /collaborators/:id
+
+Get a single collaborator by ID.
+
+**Response:** `Collaborator`
+
+---
+
+## POST /collaborators
+
+Create a new collaborator. Requires `EDITOR` role.
+
+**Request body:**
+
+```json
+{
+  "name": "string",
+  "youtubeLink": "https://www.youtube.com/@handle",
+  "twitchLink": "https://www.twitch.tv/handle",
+  "instagramLink": "https://www.instagram.com/handle",
+  "tiktokLink": "https://www.tiktok.com/@handle",
+  "twitterLink": "https://x.com/handle",
+  "blueskyLink": "https://bsky.app/profile/handle",
+  "discordHandle": "username",
+  "aliases": ["string"],
+  "notes": "string"
+}
+```
+
+All platform link fields are optional. `discordHandle` stores a username string rather than a URL.
+
+---
+
+## PATCH /collaborators/:id
+
+Update a collaborator. Requires `EDITOR` role.
+
+**Request body:** Same fields as `POST /collaborators`, all optional.
+
+---
+
+## DELETE /collaborators/:id
+
+Delete a collaborator. Requires `ADMIN` role.
+
+> Before deleting, check whether the collaborator is still referenced in any `Video.collaboratorIds` JSON array. Use the `array_contains` Prisma operator to query this field.
+
+---
+
+## Collaborator tokens in descriptions
+
+When a `COLLABORATOR` or `VARIABLE` block references a collaborator, the following `{collab.*}` tokens are available:
+
+| Token | Resolves to |
+|---|---|
+| `{collab.name}` | Collaborator's display name |
+| `{collab.youtube}` | Full YouTube URL (e.g. `https://www.youtube.com/@handle`) |
+| `{collab.twitch}` | Twitch link |
+| `{collab.instagram}` | Instagram link |
+| `{collab.tiktok}` | TikTok link |
+| `{collab.twitter}` | Twitter/X link |
+| `{collab.bluesky}` | Bluesky link |
+| `{collab.discord}` | Discord handle |
+| `{collab.aliases}` | Aliases list |
+| `{collab.notes}` | Notes field |
+
+> The legacy `{collab.handle}` token is no longer supported. Any block content still using it will not resolve — update those blocks manually to `{collab.youtube}`.
+
+All tokens are registered in `shared/system-variables/system-variables.registry.ts`. See [[02 - Description Engine]] for how they are resolved.
+
+---
+
+## Collaborator tracking
+
+Collaborators are assigned to a video via `Video.collaboratorIds` — a JSON string array of collaborator IDs stored directly on the `Video` row. This is the single source for both rendering (`{collab.*}` token resolution) and filtering (the `collaboratorId` query param on `GET /videos`). There is no separate join table.