Merge pull request #11 from KillrVideo/feat/explore-videos-pagination

feat: enable Explore Videos via full pagination on /videos/latest

Author: aar0np

app/services/video_service.py

@@ -542,15 +542,12 @@ async def list_latest_videos(
     page_size: int,
     db_table: Optional[AstraDBCollection] = None,
 ) -> Tuple[List[VideoSummary], int]:
-    """Return the newest *three* videos across all days for the home page row."""
-
-    # We only need a single row of 3 videos on the UI – cap the page size.
-    effective_size = min(page_size, 3)
+    """Return the newest videos across all days, sorted by submission date descending."""
 
     return await list_videos_with_query(
         {},
         page,
-        effective_size,
+        page_size,
         sort_options={"added_date": -1},
         db_table=db_table,
         source_table_name=VIDEOS_TABLE_NAME,

docs/explore-videos-frontend.md

@@ -0,0 +1,78 @@
+# Explore Videos — Frontend Integration Guide
+
+## Endpoint
+
+```
+GET /api/v1/videos/latest
+```
+
+No authentication required (public endpoint).
+
+## Query Parameters
+
+| Parameter  | Type | Default | Range  | Description          |
+|------------|------|---------|--------|----------------------|
+| `page`     | int  | 1       | >= 1   | Page number          |
+| `pageSize` | int  | 10      | 1–100  | Items per page       |
+
+## Example Request
+
+```
+GET /api/v1/videos/latest?page=1&pageSize=12
+```
+
+## Response Shape
+
+```json
+{
+  "data": [
+    {
+      "videoId": "uuid",
+      "title": "Video Title",
+      "thumbnailUrl": "https://i.ytimg.com/vi/.../hqdefault.jpg",
+      "userId": "uuid",
+      "submittedAt": "2025-12-01T14:30:00Z",
+      "content_rating": null,
+      "category": null
+    }
+  ],
+  "pagination": {
+    "currentPage": 1,
+    "pageSize": 12,
+    "totalItems": 47,
+    "totalPages": 4
+  }
+}
+```
+
+## Key Fields in Each Video
+
+| Field           | Type        | Notes                                    |
+|-----------------|-------------|------------------------------------------|
+| `videoId`       | UUID string | Use for routing to `/videos/{videoId}`   |
+| `title`         | string      | Display name                             |
+| `thumbnailUrl`  | URL or null | YouTube thumbnail; use placeholder if null |
+| `userId`        | UUID string | Uploader's user ID                       |
+| `submittedAt`   | ISO 8601    | When the video was added                 |
+| `content_rating`| string/null | Optional content rating                  |
+| `category`      | string/null | Optional category                        |
+
+## Pagination
+
+Use `pagination.totalPages` to render page controls. To fetch the next page:
+
+```
+GET /api/v1/videos/latest?page=2&pageSize=12
+```
+
+## Suggested UX
+
+- Default to `pageSize=12` (works well in 3- or 4-column grids)
+- Show video cards with thumbnail, title, and submission date
+- Link each card to the video detail page using `videoId`
+- Use `totalItems` to show "Showing X of Y videos"
+- Consider infinite scroll or "Load More" using incrementing `page` values
+
+## Sort Order
+
+Videos are sorted **newest first** (by `submittedAt` descending). There is currently no parameter to change sort order.