From 480fd16ad2795fbd2fe7160cb04354e34005dd37 Mon Sep 17 00:00:00 2001 From: Grayson Adams <51373669+GraysonCAdams@users.noreply.github.com> Date: Tue, 3 Mar 2026 07:51:29 -0600 Subject: [PATCH] docs: update API, architecture, and notifications for v1.13.0 - Add POST /api/clips/[id]/refetch and DELETE /api/notifications/[id] - Update PATCH/DELETE /api/clips/[id] for host permissions - Add clipContentType to notifications response - Document new_clip in-app notifications and auto-clear behavior - Add new endpoint files to architecture directory tree --- docs/api.md | 20 +++++++++++++++++--- docs/architecture.md | 2 ++ docs/notifications.md | 13 +++++++++++-- 3 files changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/api.md b/docs/api.md index 2ddd7ac..a4b1796 100644 --- a/docs/api.md +++ b/docs/api.md @@ -100,10 +100,10 @@ Response: { id, originalUrl, videoPath, audioPath, thumbnailPath, title, artist, Request: { "title": "new caption" } Response: { "title": "new caption" } ``` -Only allowed by the uploader, and only if no one else has watched the clip. +Host-only. Only the group host can edit clip captions. ### DELETE /api/clips/[id] -Only allowed by the uploader, and only if no one else has watched the clip. +Host can delete any clip. Non-host uploaders can only delete their own clips if no one else has watched them. ### GET /api/clips/unwatched-count ``` @@ -126,6 +126,7 @@ Response: { "count": 5 } | GET | `/api/clips/[id]/reactions` | List reactions | | POST | `/api/clips/[id]/reactions` | Toggle a reaction | | POST | `/api/clips/[id]/retry` | Retry failed download | +| POST | `/api/clips/[id]/refetch` | Refetch metadata from source | ### POST /api/clips/[id]/watched ``` @@ -176,6 +177,12 @@ Retries a failed download. Only available for clips with `status: 'failed'`. Response: { "status": "downloading" } ``` +### POST /api/clips/[id]/refetch +Host-only. Refetches metadata (title, creator info) from the source URL via yt-dlp. +``` +Response: { "title": "...", "creatorName": "...", "creatorUrl": "..." } +``` + ## Group Management Host-only endpoints (unless noted). Requires `createdBy === currentUser`. @@ -305,6 +312,7 @@ Response: { "clipCount": 42, "memberCount": 8, "storageMb": 1200, "maxStorageMb" | Method | Path | Description | |--------|------|-------------| | GET | `/api/notifications` | Paginated notification feed | +| DELETE | `/api/notifications/[id]` | Delete a single notification | | POST | `/api/notifications/mark-read` | Mark notifications as read | | GET | `/api/notifications/unread-count` | Unread notification count | | GET | `/api/notifications/preferences` | Fetch notification preferences | @@ -313,7 +321,13 @@ Response: { "clipCount": 42, "memberCount": 8, "storageMb": 1200, "maxStorageMb" ### GET /api/notifications ``` Query params: ?limit=30&offset=0 -Response: { "notifications": [{ "id", "type", "clipId", "emoji", "commentPreview", "actorUsername", "actorAvatar", "clipThumbnail", "clipTitle", "read", "createdAt" }] } +Response: { "notifications": [{ "id", "type", "clipId", "emoji", "commentPreview", "actorUsername", "actorAvatar", "clipThumbnail", "clipTitle", "clipContentType", "read", "createdAt" }] } +``` + +### DELETE /api/notifications/[id] +Deletes a single notification by ID for the current user. +``` +Response: { "ok": true } ``` ### POST /api/notifications/mark-read diff --git a/docs/architecture.md b/docs/architecture.md index a88fc02..03a0fb9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -153,9 +153,11 @@ scrolly/ │ │ ├── api/ # REST API (see docs/api.md) │ │ │ ├── auth/ │ │ │ ├── clips/ +│ │ │ │ └── [id]/refetch/+server.ts # Host-only metadata refetch │ │ │ ├── gifs/ │ │ │ ├── group/ │ │ │ ├── notifications/ +│ │ │ │ └── [id]/+server.ts # Delete single notification │ │ │ ├── profile/ │ │ │ ├── push/ │ │ │ ├── videos/ diff --git a/docs/notifications.md b/docs/notifications.md index c6c5b97..669b52c 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -5,16 +5,24 @@ Scrolly has two notification systems: an **in-app activity feed** and **web push ## In-App Activity Feed The in-app activity feed shows a chronological list of notifications via the `ActivitySheet` component. Users see: +- New clips added by other group members - Reactions on their clips - Comments on their clips -New clip notifications are **push-only** — they are not stored in the `notifications` database table. Reaction and comment notifications are stored in the `notifications` table with read/unread tracking. The bottom navigation shows an unread badge count. +All notification types are stored in the `notifications` database table with read/unread tracking. The bottom navigation shows an unread badge count. Users can dismiss individual notifications via the `DELETE /api/notifications/[id]` endpoint. + +### Auto-Clear Behavior + +Certain user actions automatically delete related notifications to keep the activity feed clean: +- **Watching a clip** deletes any `new_clip` notification for that clip +- **Viewing comments** on a clip deletes `comment`, `reply`, and `mention` notifications for that clip ### API Endpoints | Method | Path | Description | |--------|------|-------------| | GET | `/api/notifications` | Paginated notification feed | +| DELETE | `/api/notifications/[id]` | Delete a single notification | | POST | `/api/notifications/mark-read` | Mark notifications as read (all or by clip/type) | | GET | `/api/notifications/unread-count` | Unread badge count | | GET | `/api/notifications/preferences` | Fetch notification preferences | @@ -28,7 +36,7 @@ Real-time push notifications via the Web Push Protocol (VAPID). | Event | Who gets notified | When sent | Preference key | |-------|-------------------|-----------|----------------| -| New clip added | All group members except poster (push only) | After download succeeds (`status: 'ready'`) | `newAdds` | +| New clip added | All group members except poster (push + in-app) | After download succeeds (`status: 'ready'`) | `newAdds` | | Reaction on a clip | Clip owner only (push + in-app) | Immediately after reaction is persisted | `reactions` | | Comment on a clip | Clip owner only (push + in-app) | Immediately after comment is persisted | `comments` | | Daily reminder | Per-user opt-in | — | `dailyReminder` (not yet scheduled) | @@ -98,6 +106,7 @@ VAPID_SUBJECT=mailto:you@example.com | Subscribe API | `src/routes/api/push/subscribe/+server.ts` | POST/DELETE push subscriptions | | Test API | `src/routes/api/push/test/+server.ts` | POST test notification to current user | | Notifications API | `src/routes/api/notifications/+server.ts` | GET notification feed | +| Delete notification API | `src/routes/api/notifications/[id]/+server.ts` | DELETE single notification | | Mark-read API | `src/routes/api/notifications/mark-read/+server.ts` | POST mark as read | | Unread-count API | `src/routes/api/notifications/unread-count/+server.ts` | GET unread badge count | | Preferences API | `src/routes/api/notifications/preferences/+server.ts` | GET/PATCH preferences |