core-framework 0.3.0__py3-none-any.whl

core_framework/api/admin/moderation/router.py

@@ -0,0 +1,205 @@
+from typing import Annotated, Any
+
+from fastapi import APIRouter, BackgroundTasks, Depends, Query, Request, status
+from firebase_admin import auth
+
+from core_framework.api.admin.moderation.schemas import (
+    AppealDecisionRequest,
+    AppealResponse,
+    ModerationActionResponse,
+    ModerationReason,
+    ReportItem,
+    ReportType,
+    RestrictionHistoryItem,
+    validate_appeal_id,
+    validate_report_id,
+)
+from core_framework.api.dependencies import RequiredUserID
+from core_framework.api.users.shared.schemas import validate_optional_user_id, validate_user_id
+from core_framework.application.moderation.appeal_service import decide_appeal, retrieve_appeals
+from core_framework.application.moderation.moderator_service import retrieve_moderation_actions_strong
+from core_framework.application.moderation.report_service import retrieve_reports
+from core_framework.application.moderation.user_service import (
+    ban_user,
+    clear_user_restriction,
+    mute_user,
+    remove_comment_report,
+    remove_post_report,
+    remove_user_report,
+    retrieve_restriction_history,
+    warn_user,
+)
+from core_framework.core.pagination import (
+    PaginationCursorType,
+    PaginationResponse,
+    TokenCursorQueryParams,
+    paginate_cursor,
+)
+from core_framework.domains.moderation import AppealDecision
+
+router = APIRouter(prefix="/moderation")
+
+
+@router.get("/moderators/{moderator_id}/actions", response_model=PaginationResponse[ModerationActionResponse])
+async def get_moderator_actions(
+    request: Request,
+    moderator_id: str,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    validated_moderator_id = validate_user_id(user_id=moderator_id)
+    actions = await retrieve_moderation_actions_strong(
+        actor_id=validated_moderator_id.root,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request,
+        actions,
+        pagination_params.limit,
+        PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/appeals", response_model=PaginationResponse[AppealResponse])
+async def get_appeals(
+    request: Request,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+    status: Annotated[AppealDecision | None, Query()] = None,
+) -> Any:
+    appeals = await retrieve_appeals(
+        status=status,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request,
+        appeals,
+        pagination_params.limit,
+        PaginationCursorType.UPDATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.patch("/appeals/{appeal_id}", response_model=AppealResponse)
+async def patch_appeal(
+    actor_id: RequiredUserID,
+    appeal_id: int,
+    decision_request: AppealDecisionRequest,
+) -> Any:
+    validated_appeal_id = validate_appeal_id(appeal_id=appeal_id)
+    return await decide_appeal(
+        actor_id=actor_id.root,
+        appeal_id=validated_appeal_id.root,
+        decision=decision_request.decision,
+        reason=decision_request.reason,
+    )
+
+
+@router.put("/users/{target_user_id}/ban", status_code=status.HTTP_204_NO_CONTENT)
+async def put_user_ban(
+    actor_id: RequiredUserID,
+    target_user_id: str,
+    moderation_reason: ModerationReason,
+    background_tasks: BackgroundTasks,
+) -> None:
+    validated_user_id = validate_user_id(user_id=target_user_id)
+    await ban_user(
+        actor_id=actor_id.root,
+        user_id=validated_user_id.root,
+        category=moderation_reason.category,
+        reason=moderation_reason.reason,
+    )
+    background_tasks.add_task(auth.revoke_refresh_tokens, validated_user_id.root)
+
+
+@router.put("/users/{target_user_id}/mute", status_code=status.HTTP_204_NO_CONTENT)
+async def put_user_mute(actor_id: RequiredUserID, target_user_id: str, moderation_reason: ModerationReason) -> None:
+    validated_user_id = validate_user_id(user_id=target_user_id)
+    await mute_user(
+        actor_id=actor_id.root,
+        user_id=validated_user_id.root,
+        category=moderation_reason.category,
+        reason=moderation_reason.reason,
+    )
+
+
+@router.put("/users/{target_user_id}/warn", status_code=status.HTTP_204_NO_CONTENT)
+async def put_user_warn(actor_id: RequiredUserID, target_user_id: str, moderation_reason: ModerationReason) -> None:
+    validated_user_id = validate_user_id(user_id=target_user_id)
+    await warn_user(
+        actor_id=actor_id.root,
+        user_id=validated_user_id.root,
+        category=moderation_reason.category,
+        reason=moderation_reason.reason,
+    )
+
+
+@router.delete("/users/{target_user_id}/restriction", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user_restriction(actor_id: RequiredUserID, target_user_id: str) -> None:
+    validated_user_id = validate_user_id(user_id=target_user_id)
+    await clear_user_restriction(actor_id=actor_id.root, user_id=validated_user_id.root)
+
+
+@router.get("/users/{target_user_id}/restriction-history", response_model=PaginationResponse[RestrictionHistoryItem])
+async def get_restriction_history(
+    request: Request,
+    target_user_id: str,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    validated_user_id = validate_user_id(user_id=target_user_id)
+    history = await retrieve_restriction_history(
+        user_id=validated_user_id.root,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request,
+        history,
+        pagination_params.limit,
+        PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/reports", response_model=PaginationResponse[ReportItem])
+async def get_reports(
+    request: Request,
+    report_type: Annotated[ReportType, Query(alias="type")],
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+    reporter_user_id: Annotated[str | None, Query()] = None,
+    target_id: Annotated[str | None, Query()] = None,
+) -> Any:
+    validated_reporter_user_id = validate_optional_user_id(user_id=reporter_user_id)
+    reports = await retrieve_reports(
+        report_type=report_type,
+        reporter_id=validated_reporter_user_id.root if validated_reporter_user_id else None,
+        target_id=target_id,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request,
+        reports,
+        pagination_params.limit,
+        PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.delete("/reports/user/{report_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user_report(report_id: int) -> None:
+    validated_report_id = validate_report_id(report_id=report_id)
+    await remove_user_report(report_id=validated_report_id.root)
+
+
+@router.delete("/reports/post/{report_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_post_report(report_id: int) -> None:
+    validated_report_id = validate_report_id(report_id=report_id)
+    await remove_post_report(report_id=validated_report_id.root)
+
+
+@router.delete("/reports/comment/{report_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_comment_report(report_id: int) -> None:
+    validated_report_id = validate_report_id(report_id=report_id)
+    await remove_comment_report(report_id=validated_report_id.root)

core_framework/api/admin/moderation/schemas.py

@@ -0,0 +1,110 @@
+from datetime import datetime
+from typing import Annotated, Any
+
+from fastapi.exceptions import RequestValidationError
+from pydantic import BaseModel, Field, RootModel, ValidationError
+
+from core_framework.api.users.shared.schemas import UserID, UserReference
+from core_framework.domains.moderation import (
+    AppealDecision,
+    HistoryAction,
+    ModerationActionType,
+    ReportCategory,
+    ReportType,
+    RestrictionCategory,
+    RestrictionType,
+)
+
+
+class ModerationReason(BaseModel):
+    category: RestrictionCategory
+    reason: Annotated[str, Field(..., min_length=3, max_length=250)]
+
+
+class RestrictionHistoryItem(BaseModel):
+    user_id: UserID
+    action: HistoryAction
+    restriction_type: RestrictionType
+    category: RestrictionCategory
+    reason: str
+    actor: UserReference | None
+    created_at: datetime
+
+
+class ModerationActionResponse(BaseModel):
+    id: int
+    actor: UserReference
+    target_user: UserReference | None
+    action_type: ModerationActionType
+    action_metadata: dict[str, Any]
+    created_at: datetime
+
+
+class AppealID(RootModel[int]):
+    root: Annotated[
+        int,
+        Field(
+            description="The ID of the appeal",
+            ge=1,
+        ),
+    ]
+
+
+class PreviewItem(BaseModel):
+    key: str
+    value: str
+
+
+class ReportItem(BaseModel):
+    type: ReportType
+    id: int
+    reporter: UserReference
+    target_id: str
+    category: ReportCategory
+    reason: str
+    created_at: datetime
+    preview: list[PreviewItem]
+
+
+class ReportID(RootModel[int]):
+    root: Annotated[
+        int,
+        Field(
+            description="The ID of the report",
+            ge=1,
+        ),
+    ]
+
+
+class AppealDecisionRequest(BaseModel):
+    decision: AppealDecision
+    reason: Annotated[str, Field(..., min_length=3, max_length=250)]
+
+
+class AppealResponse(BaseModel):
+    id: int
+    user: UserReference
+    justification: str
+    reviewer: UserReference | None
+    decision_reason: str | None
+    status: AppealDecision
+    created_at: datetime
+    updated_at: datetime
+
+
+def validate_appeal_id(*, appeal_id: int) -> AppealID:
+    try:
+        return AppealID(
+            root=appeal_id,
+        )
+    except ValidationError as e:
+        raise RequestValidationError(e.errors()) from e
+
+
+def validate_report_id(*, report_id: int) -> ReportID:
+    try:
+        return ReportID(
+            root=report_id
+        )  # Note: Workaround for Pydantic's lack of support for Root Model in Path parameters
+    except ValidationError as e:
+        raise RequestValidationError(e.errors()) from e

core_framework/api/admin/posts/router.py

@@ -0,0 +1,62 @@
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Request, status
+from ulid import ULID
+
+from core_framework.api.admin.posts.schemas import AdminPostResponse
+from core_framework.application.posts.admin_service import (
+    remove_post,
+    restore_post,
+    retrieve_all_posts,
+    retrieve_post_by_id,
+    set_post_inactive,
+)
+from core_framework.core.pagination import (
+    PaginationCursorType,
+    PaginationResponse,
+    TokenCursorQueryParams,
+    paginate_cursor,
+)
+
+router = APIRouter(
+    prefix="/posts",
+    tags=["posts - admin"],
+)
+
+
+@router.get("", response_model=PaginationResponse[AdminPostResponse])
+async def get_posts(
+    request: Request,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    posts = await retrieve_all_posts(
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request=request,
+        items=posts,
+        limit=pagination_params.limit,
+        cursor_field=PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/{post_id}", response_model=AdminPostResponse)
+async def get_post(post_id: ULID) -> Any:
+    return await retrieve_post_by_id(post_id=str(post_id))
+
+
+@router.put("/{post_id}/inactive", status_code=status.HTTP_204_NO_CONTENT)
+async def put_post_inactive(post_id: ULID) -> None:
+    await set_post_inactive(post_id=str(post_id))
+
+
+@router.delete("/{post_id}/inactive", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_post_inactive(post_id: ULID) -> None:
+    await restore_post(post_id=str(post_id))
+
+
+@router.delete("/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_post(post_id: ULID) -> None:
+    await remove_post(post_id=str(post_id))

core_framework/api/admin/posts/schemas.py

@@ -0,0 +1,29 @@
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+from ulid import ULID
+
+from core_framework.api.posts.schemas import Hashtag, PostContent
+from core_framework.api.users.shared.schemas import UserReference
+from core_framework.domains.post import PostStatus, PostVisibility
+
+
+class AdminPostStatsResponse(BaseModel):
+    like_count: Annotated[int, Field(ge=0)] = 0
+    comment_count: Annotated[int, Field(ge=0)] = 0
+    view_count: Annotated[int, Field(ge=0)] = 0
+    report_count: Annotated[int, Field(ge=0)] = 0
+
+
+class AdminPostResponse(BaseModel):
+    id: ULID
+    author: UserReference
+    content: PostContent
+    hashtags: list[Hashtag]
+    visibility: PostVisibility
+    status: PostStatus
+    edited_count: Annotated[int, Field(ge=0)] = 0
+    stats: AdminPostStatsResponse
+    edited_at: datetime | None
+    created_at: datetime

core_framework/api/admin/router.py

@@ -0,0 +1,17 @@
+from fastapi import APIRouter, Depends
+
+from core_framework.api.admin.comments.router import router as comments_router
+from core_framework.api.admin.moderation.router import router as moderation_router
+from core_framework.api.admin.posts.router import router as posts_router
+from core_framework.api.admin.users.router import router as users_router
+from core_framework.api.dependencies import check_admin_role
+
+router = APIRouter(
+    prefix="/admin",
+    dependencies=[Depends(check_admin_role)],
+)
+
+router.include_router(users_router)
+router.include_router(moderation_router)
+router.include_router(posts_router)
+router.include_router(comments_router)

core_framework/api/admin/users/router.py

@@ -0,0 +1,181 @@
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Query, Request, status
+
+from core_framework.api.admin.users.schemas import (
+    AdminProfileUpdateRequest,
+    InternalNoteDetailResponse,
+    InternalNoteRequest,
+    InternalNoteResponse,
+    RoleChangeRequest,
+    UserChangeHistoryItem,
+    UserDetailResponse,
+    UsernameChangeRequest,
+    UserSearchQueryParams,
+    UserSummaryResponse,
+    validate_note_id,
+)
+from core_framework.api.dependencies import RequiredUserID
+from core_framework.api.users.shared.schemas import validate_user_id
+from core_framework.application.users.admin_service import (
+    add_user_note,
+    change_user_profile,
+    change_user_role,
+    change_user_username,
+    remove_user,
+    remove_user_note,
+    retrieve_user_detail,
+    retrieve_user_history,
+    retrieve_user_notes,
+    retrieve_users,
+)
+from core_framework.core.pagination import (
+    PaginationCursorType,
+    PaginationResponse,
+    TokenCursorQueryParams,
+    paginate_cursor,
+)
+
+router = APIRouter(
+    prefix="/users",
+    tags=["users - admin"],
+)
+
+
+@router.get("", response_model=PaginationResponse[UserSummaryResponse])
+async def get_users(
+    request: Request,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+    search_params: Annotated[UserSearchQueryParams, Query()],
+) -> Any:
+    users = await retrieve_users(
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+        username=search_params.username,
+        role=search_params.role,
+    )
+    return paginate_cursor(
+        request,
+        users,
+        pagination_params.limit,
+        PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/{user_id}", response_model=UserDetailResponse)
+async def get_user_detail(user_id: str) -> Any:
+    validated_user_id = validate_user_id(user_id=user_id)
+    return await retrieve_user_detail(user_id=validated_user_id.root)
+
+
+@router.patch("/{user_id}/username", status_code=status.HTTP_204_NO_CONTENT)
+async def patch_user_username(
+    actor_id: RequiredUserID,
+    user_id: str,
+    request_body: UsernameChangeRequest,
+) -> None:
+    validated_user_id = validate_user_id(user_id=user_id)
+    await change_user_username(
+        actor_id=actor_id.root,
+        user_id=validated_user_id.root,
+        new_username=request_body.username.root,
+    )
+
+
+@router.patch("/{user_id}/role", status_code=status.HTTP_204_NO_CONTENT)
+async def patch_user_role(
+    actor_id: RequiredUserID,
+    user_id: str,
+    request_body: RoleChangeRequest,
+) -> None:
+    validated_user_id = validate_user_id(user_id=user_id)
+    await change_user_role(
+        actor_id=actor_id.root,
+        user_id=validated_user_id.root,
+        new_role=request_body.role,
+    )
+
+
+@router.patch("/{user_id}/profile", status_code=status.HTTP_204_NO_CONTENT)
+async def patch_user_profile(
+    actor_id: RequiredUserID,
+    user_id: str,
+    request_body: AdminProfileUpdateRequest,
+) -> None:
+    validated_user_id = validate_user_id(user_id=user_id)
+    validated_update_request = request_body.model_dump(mode="json", exclude_unset=True)
+    await change_user_profile(
+        actor_id=actor_id.root,
+        user_id=validated_user_id.root,
+        validated_update_request=validated_update_request,
+    )
+
+
+@router.get("/{user_id}/change-history", response_model=PaginationResponse[UserChangeHistoryItem])
+async def get_user_history(
+    request: Request,
+    user_id: str,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    validated_user_id = validate_user_id(user_id=user_id)
+    history = await retrieve_user_history(
+        user_id=validated_user_id.root,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request,
+        history,
+        pagination_params.limit,
+        PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.get("/{user_id}/notes", response_model=PaginationResponse[InternalNoteDetailResponse])
+async def get_user_notes(
+    request: Request,
+    user_id: str,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    validated_user_id = validate_user_id(user_id=user_id)
+    notes = await retrieve_user_notes(
+        user_id=validated_user_id.root,
+        cursor=pagination_params.cursor,
+        limit=pagination_params.limit,
+    )
+    return paginate_cursor(
+        request,
+        notes,
+        pagination_params.limit,
+        PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
+@router.post("/{user_id}/notes", response_model=InternalNoteResponse, status_code=status.HTTP_201_CREATED)
+async def post_user_note(
+    actor_id: RequiredUserID,
+    user_id: str,
+    request_body: InternalNoteRequest,
+) -> Any:
+    validated_user_id = validate_user_id(user_id=user_id)
+    return await add_user_note(
+        actor_id=actor_id.root,
+        user_id=validated_user_id.root,
+        content=request_body.content,
+    )
+
+
+@router.delete("/{user_id}/notes/{note_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user_note(actor_id: RequiredUserID, user_id: str, note_id: int) -> None:
+    validated_user_id = validate_user_id(user_id=user_id)
+    validated_note_id = validate_note_id(note_id=note_id)
+    await remove_user_note(actor_id=actor_id.root, user_id=validated_user_id.root, note_id=validated_note_id.root)
+
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(actor_id: RequiredUserID, user_id: str) -> None:
+    validated_user_id = validate_user_id(user_id=user_id)
+    await remove_user(actor_id=actor_id.root, user_id=validated_user_id.root)