fix: address review comments on user activity endpoint (closes #17)

- Use validation_alias instead of alias in UserActivityResponse so OpenAPI
  spec emits camelCase field names (userId, activityType, activityId,
  activityTimestamp) while model_validate() from snake_case DB objects still works
- Change route path from {user_id_path:uuid} to {user_id_path} with UUID
  type annotation so invalid UUIDs produce 422 instead of 404
- Replace activity_type query param type str with Literal["view","comment","rate"]
  for enum validation and OpenAPI documentation
- Replace max(1, math.ceil(...)) totalPages formula with integer division
  so empty result sets return totalPages=0 consistently
- Fix test_get_user_activity_with_type_filter to assert item["activityType"]
  directly instead of hedging with .get() fallback
- Regenerate docs/killrvideo_openapi.yaml to reflect all model/route changes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: pmcfadin

app/api/v1/endpoints/user_activity.py

@@ -0,0 +1,51 @@
+"""API endpoint for querying user activity timelines."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, Optional
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+
+from app.api.v1.dependencies import PaginationParams
+from app.models.common import PaginatedResponse, Pagination
+from app.models.user_activity import UserActivityResponse
+from app.services import user_activity_service
+
+router = APIRouter(tags=["User Activity"])
+
+
+@router.get(
+    "/users/{user_id_path}/activity",
+    response_model=PaginatedResponse[UserActivityResponse],
+    summary="Get user activity timeline",
+)
+async def get_user_activity(
+    user_id_path: UUID,
+    pagination: Annotated[PaginationParams, Depends()],
+    activity_type: Optional[Literal["view", "comment", "rate"]] = Query(
+        None, description="Filter by activity type (view, comment, rate)"
+    ),
+):
+    """Return a paginated timeline of a user's activity over the last 30 days."""
+
+    activities, total = await user_activity_service.list_user_activity(
+        userid=user_id_path,
+        page=pagination.page,
+        page_size=pagination.pageSize,
+        activity_type=activity_type,
+    )
+
+    total_pages = (total + pagination.pageSize - 1) // pagination.pageSize
+
+    response_items = [UserActivityResponse.model_validate(a) for a in activities]
+
+    return PaginatedResponse[UserActivityResponse](
+        data=response_items,
+        pagination=Pagination(
+            currentPage=pagination.page,
+            pageSize=pagination.pageSize,
+            totalItems=total,
+            totalPages=total_pages,
+        ),
+    )

docs/killrvideo_openapi.yaml

@@ -1271,6 +1271,70 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/HTTPValidationError'
+  /api/v1/users/{user_id_path}/activity:
+    get:
+      tags:
+      - User Activity
+      summary: Get user activity timeline
+      description: Return a paginated timeline of a user's activity over the last
+        30 days.
+      operationId: get_user_activity_api_v1_users__user_id_path__activity_get
+      parameters:
+      - name: user_id_path
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+          title: User Id Path
+      - name: activity_type
+        in: query
+        required: false
+        schema:
+          anyOf:
+          - enum:
+            - view
+            - comment
+            - rate
+            type: string
+          - type: 'null'
+          description: Filter by activity type (view, comment, rate)
+          title: Activity Type
+        description: Filter by activity type (view, comment, rate)
+      - name: page
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          description: Page number
+          default: 1
+          title: Page
+        description: Page number
+      - name: pageSize
+        in: query
+        required: false
+        schema:
+          type: integer
+          maximum: 100
+          minimum: 1
+          description: Items per page
+          default: 10
+          title: Pagesize
+        description: Items per page
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaginatedResponse_UserActivityResponse_'
+        '422':
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
   /:
     get:
       summary: Health check
@@ -1579,6 +1643,20 @@ components:
       - data
       - pagination
       title: PaginatedResponse[FlagResponse]
+    PaginatedResponse_UserActivityResponse_:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/UserActivityResponse'
+          type: array
+          title: Data
+        pagination:
+          $ref: '#/components/schemas/Pagination'
+      type: object
+      required:
+      - data
+      - pagination
+      title: PaginatedResponse[UserActivityResponse]
     PaginatedResponse_VideoSummary_:
       properties:
         data:
@@ -1743,6 +1821,31 @@ components:
       - email
       - userId
       title: User
+    UserActivityResponse:
+      properties:
+        userId:
+          type: string
+          format: uuid
+          title: Userid
+        activityType:
+          type: string
+          title: Activitytype
+        activityId:
+          type: string
+          format: uuid
+          title: Activityid
+        activityTimestamp:
+          type: string
+          format: date-time
+          title: Activitytimestamp
+      type: object
+      required:
+      - userId
+      - activityType
+      - activityId
+      - activityTimestamp
+      title: UserActivityResponse
+      description: API response representation for a single user activity item.
     UserCreateRequest:
       properties:
         firstName:
@@ -1873,7 +1976,7 @@ components:
         description:
           anyOf:
           - type: string
-            maxLength: 1000
+            maxLength: 2000
           - type: 'null'
           title: Description
         tags:
@@ -2127,7 +2230,7 @@ components:
         description:
           anyOf:
           - type: string
-            maxLength: 1000
+            maxLength: 2000
           - type: 'null'
           title: Description
         tags: