core-framework 0.3.0__py3-none-any.whl

core_framework/domains/post/service.py

@@ -0,0 +1,204 @@
+from collections import defaultdict
+from datetime import datetime
+from typing import Any, Final, Literal
+
+from ulid import ULID
+
+from core_framework.domains.post.enums import PostStatus, PostVisibility
+from core_framework.domains.post.exceptions import PostNotFoundException
+from core_framework.domains.post.models import Post, PostPreview, PostStats, PostWithMetadata
+from core_framework.domains.post.repository import PostRepository
+
+
+class PostService:
+    MAX_EDIT_COUNT: Final[int] = 5
+
+    def __init__(self, repository: PostRepository):
+        self.repository = repository
+
+    async def add_post(
+        self,
+        *,
+        author_id: str,
+        content: str,
+        visibility: PostVisibility,
+        hashtags: list[str],
+    ) -> None:
+        await self.repository.insert_post(
+            post_id=str(ULID()),
+            author_id=author_id,
+            content=content,
+            visibility=visibility,
+            hashtags=hashtags,
+        )
+
+    async def edit_post(
+        self,
+        *,
+        post_id: str,
+        author_id: str,
+        validated_update_request: dict[str, Any],
+    ) -> None:
+        hashtags = validated_update_request.get("hashtags")
+        post_updates = {k: v for k, v in validated_update_request.items() if k != "hashtags"}
+        await self.repository.update_post(
+            post_id=post_id,
+            author_id=author_id,
+            post_updates=post_updates,
+            hashtags=hashtags,
+            max_edit_count=self.MAX_EDIT_COUNT,
+        )
+
+    async def set_post_status_for_author(
+        self,
+        *,
+        post_id: str,
+        author_id: str,
+        status: PostStatus,
+    ) -> None:
+        await self.repository.update_post_status_by_id_and_author(
+            post_id=post_id,
+            author_id=author_id,
+            status=status,
+        )
+
+    async def add_user_restriction_lookup(self, *, user_id: str, restriction_type: Literal["muted", "banned"]) -> None:
+        await self.repository.insert_user_restriction_lookup(
+            user_id=user_id,
+            restriction_type=restriction_type,
+        )
+
+    async def remove_user_restriction_lookup(self, *, user_id: str) -> None:
+        await self.repository.delete_user_restriction_lookup(user_id=user_id)
+
+    async def add_user_block_lookup(self, *, blocker_id: str, blocked_id: str) -> None:
+        await self.repository.insert_user_block_lookup(
+            blocker_id=blocker_id,
+            blocked_id=blocked_id,
+        )
+
+    async def remove_user_block_lookup(self, *, blocker_id: str, blocked_id: str) -> None:
+        await self.repository.delete_user_block_lookup(
+            blocker_id=blocker_id,
+            blocked_id=blocked_id,
+        )
+
+    async def remove_user(self, *, user_id: str) -> None:
+        await self.repository.delete_user(user_id=user_id)
+
+    async def add_post_like(self, *, post_id: str, liker_id: str) -> None:
+        await self.repository.insert_post_like(post_id=post_id, liker_id=liker_id)
+
+    async def remove_post_like(self, *, post_id: str, liker_id: str) -> None:
+        await self.repository.delete_post_like(post_id=post_id, liker_id=liker_id)
+
+    async def retrieve_post_like_count(self, *, post_id: str) -> int:
+        return await self.repository.select_post_like_count(post_id=post_id)
+
+    async def retrieve_post_ids_liked_by_user(self, *, liker_id: str, post_ids: set[str]) -> frozenset[str]:
+        ids = await self.repository.select_post_ids_liked_by_user(liker_id=liker_id, post_ids=post_ids)
+        return frozenset(ids)
+
+    async def add_post_view(
+        self,
+        *,
+        post_id: str,
+        token: str,
+        request_context: dict[str, str],
+    ) -> None:
+        await self.repository.insert_post_view(
+            post_id=post_id,
+            token=token,
+            request_context=request_context,
+        )
+
+    async def aggregate_post_view_counts(self) -> list[str]:
+        return await self.repository.aggregate_post_view_counts()
+
+    async def update_post_stats(
+        self,
+        *,
+        post_id: str,
+        like_count: int,
+        comment_count: int,
+        report_count: int,
+    ) -> None:
+        await self.repository.update_post_stats(
+            post_id=post_id,
+            like_count=like_count,
+            comment_count=comment_count,
+            report_count=report_count,
+        )
+
+    async def retrieve_post_content_mapping(self, *, post_ids: set[str]) -> defaultdict[str, str]:
+        post_content_mapping = await self.repository.select_post_content_mapping(post_ids=post_ids)
+        return defaultdict(str, post_content_mapping)
+
+    async def retrieve_post_preview_mapping(self, *, post_ids: set[str]) -> dict[str, PostPreview]:
+        return await self.repository.select_post_preview_mapping(post_ids=post_ids)
+
+    async def retrieve_post_by_id(self, *, post_id: str, viewer_id: str | None) -> Post | None:
+        return await self.repository.select_post_by_id(post_id=post_id, viewer_id=viewer_id)
+
+    async def retrieve_post_with_metadata_by_id(self, *, post_id: str) -> PostWithMetadata:
+        return await self.repository.select_post_with_metadata_by_id(post_id=post_id)
+
+    async def set_post_status_by_id(self, *, post_id: str, status: PostStatus) -> None:
+        updated = await self.repository.update_post_status_by_id(
+            post_id=post_id,
+            status=status,
+        )
+        if not updated:
+            raise PostNotFoundException()
+
+    async def delete_post_by_id(self, *, post_id: str) -> None:
+        deleted = await self.repository.delete_post_by_id(post_id=post_id)
+        if not deleted:
+            raise PostNotFoundException()
+
+    async def retrieve_posts(self, *, viewer_id: str | None, cursor: datetime, limit: int) -> list[Post]:
+        return await self.repository.select_posts(viewer_id=viewer_id, cursor=cursor, limit=limit)
+
+    async def retrieve_posts_by_user_id(
+        self,
+        *,
+        user_id: str,
+        cursor: datetime,
+        limit: int,
+        viewer_id: str | None,
+    ) -> list[Post]:
+        return await self.repository.select_posts_by_user_id(
+            user_id=user_id,
+            cursor=cursor,
+            limit=limit,
+            viewer_id=viewer_id,
+        )
+
+    async def retrieve_posts_by_hashtag(
+        self,
+        *,
+        hashtag: str,
+        cursor: datetime,
+        limit: int,
+        viewer_id: str | None,
+    ) -> list[Post]:
+        return await self.repository.select_posts_by_hashtag(
+            hashtag=hashtag,
+            cursor=cursor,
+            limit=limit,
+            viewer_id=viewer_id,
+        )
+
+    async def retrieve_posts_unfiltered(self, *, cursor: datetime, limit: int) -> list[PostWithMetadata]:
+        return await self.repository.select_posts_unfiltered(
+            cursor=cursor,
+            limit=limit,
+        )
+
+    async def retrieve_post_stats_mapping(self, *, post_ids: set[str]) -> defaultdict[str, PostStats]:
+        post_stats_mapping = await self.repository.select_post_stats_mapping(post_ids=post_ids)
+        return defaultdict(lambda: PostStats.DEFAULT, post_stats_mapping)
+
+    async def retrieve_hashtags_mapping(self, *, post_ids: set[str]) -> defaultdict[str, list[str]]:
+        hashtags_mapping = await self.repository.select_hashtags_mapping(post_ids=post_ids)
+        return defaultdict(list, hashtags_mapping)

core_framework/domains/user/README.md

@@ -0,0 +1,74 @@
+# User Domain
+
+## Scope
+
+Owns user identity, authorization role, user-to-user relationships, preferences, and login telemetry. Authentication is handled externally.
+
+## Owns
+
+### Identity
+
+- User identity is represented by a Firebase UID
+- Username is user-controlled and unique
+- Creation time is immutable
+
+### Authorization
+
+- Each user has exactly one role
+- Roles define administrative authority only
+- Role hierarchy is enforced by application-level authorization logic
+
+### User-to-User Relationships
+
+- Block relationships (user-controlled, personal preference)
+- Directed relationships owned by the blocking user
+
+### User Preferences
+
+- User-configurable settings owned by the user
+- Preference validation is enforced by domain logic
+
+## Does Not Own
+
+- Authentication or credentials
+- Account restriction state (muted/banned) - owned by moderation domain
+- Moderation policy, enforcement actions, or appeals
+- Notification delivery mechanisms
+
+## Invariants
+
+- user_id is immutable
+- username is globally unique
+- Each user has exactly one role
+- Role hierarchy is enforced in authorization logic
+
+## Persistence Model
+
+### Tables
+
+#### users
+
+- Core user record identified by Firebase UID
+- Stores identity, creation metadata, and authorization role
+
+#### user_blocks
+
+- Tracks user-to-user block relationships
+- Directed relationship
+
+#### user_preferences
+
+- User-configurable settings (theme, language)
+- One row per user, created on user registration
+
+#### user_login_events
+
+- Append-only record of user login telemetry (id, user_id, created_at, request_context)
+- user_id is the authenticated Firebase user (viewer_id from request_context), not from the event payload
+- request_context (JSONB) holds fields from the request: viewer_id, provider, country_code, client_type, browser_name, os_name, referrer
+- Used for audit, security, and analytics purposes
+
+#### user_deletions
+
+- Tracks scheduled account deletions
+- Stores scheduled deletion timestamp

core_framework/domains/user/__init__.py

@@ -0,0 +1,39 @@
+from core_framework.domains.user.constants import DEFAULT_USER_ID, REDACTED_AUTHOR_ID, SYSTEM_USER_ID
+from core_framework.domains.user.enums import ProfileVisibility, Theme, UserRole
+from core_framework.domains.user.exceptions import (
+    BaseUserException,
+    SelfBlockException,
+    UserCreationException,
+    UserIdConflictException,
+    UsernameConflictException,
+)
+from core_framework.domains.user.models import (
+    BlockedUser,
+    CreatedUser,
+    Preferences,
+    Profile,
+    UserChangeHistory,
+    UserIdentity,
+    UserWithProfile,
+)
+
+__all__ = [
+    "DEFAULT_USER_ID",
+    "REDACTED_AUTHOR_ID",
+    "SYSTEM_USER_ID",
+    "SelfBlockException",
+    "BaseUserException",
+    "UserIdConflictException",
+    "UsernameConflictException",
+    "UserCreationException",
+    "CreatedUser",
+    "BlockedUser",
+    "ProfileVisibility",
+    "Theme",
+    "UserRole",
+    "Preferences",
+    "Profile",
+    "UserIdentity",
+    "UserChangeHistory",
+    "UserWithProfile",
+]

core_framework/domains/user/constants.py

@@ -0,0 +1,8 @@
+from typing import Final
+
+DEFAULT_USER_ID: Final[str] = "DEFAULT_USER_ID"
+DEFAULT_USERNAME: Final[str] = "UserNotFound"
+SYSTEM_USER_ID: Final[str] = "SYSTEM"
+SYSTEM_USERNAME: Final[str] = "System"
+REDACTED_AUTHOR_ID: Final[str] = "DELETED"
+REDACTED_AUTHOR_USERNAME: Final[str] = "DeletedUser"

core_framework/domains/user/dependencies.py

@@ -0,0 +1,29 @@
+from core_framework.core.runtime import CoreRuntime, unconfigured_dependency
+from core_framework.domains.user.repository import UserRepository
+from core_framework.domains.user.service import UserService
+
+
+def build_user_repository(runtime: CoreRuntime) -> UserRepository:
+    return UserRepository(runtime.write_postgres, runtime.read_postgres, runtime.write_postgres)
+
+
+def build_user_service(runtime: CoreRuntime) -> UserService:
+    return UserService(build_user_repository(runtime))
+
+
+def configure_user_dependencies(runtime: CoreRuntime) -> None:
+    global user_repository, user_service
+    user_repository = build_user_repository(runtime)
+    user_service = build_user_service(runtime)
+
+
+user_repository = unconfigured_dependency("UserRepository")
+user_service = unconfigured_dependency("UserService")
+
+__all__ = [
+    "build_user_repository",
+    "build_user_service",
+    "configure_user_dependencies",
+    "user_repository",
+    "user_service",
+]

core_framework/domains/user/enums.py

@@ -0,0 +1,19 @@
+from enum import StrEnum
+
+
+class UserRole(StrEnum):
+    ADMIN = "admin"
+    MODERATOR = "moderator"
+    MEMBER = "member"
+
+
+class ProfileVisibility(StrEnum):
+    PUBLIC = "public"
+    PRIVATE = "private"
+    MEMBERS_ONLY = "members_only"
+
+
+class Theme(StrEnum):
+    DARK = "dark"
+    LIGHT = "light"
+    SYSTEM = "system"

core_framework/domains/user/exceptions.py

@@ -0,0 +1,31 @@
+class BaseUserException(Exception):
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)
+
+
+class UserIdConflictException(BaseUserException):
+    def __init__(self, user_id: str):
+        super().__init__(f"User ID {user_id} already exists")
+
+
+class UsernameConflictException(BaseUserException):
+    def __init__(self, username: str):
+        super().__init__(f"Username {username} already exists")
+
+
+class UserCreationException(BaseUserException):
+    def __init__(self, user_id: str):
+        super().__init__(f"Failed to create user {user_id}")
+
+
+class SelfBlockException(BaseUserException):
+    def __init__(self):
+        super().__init__("You cannot block yourself")
+
+
+class DomainUserNotFoundException(BaseUserException):
+    def __init__(self):
+        super().__init__("User not found")

core_framework/domains/user/models.py

@@ -0,0 +1,124 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import ClassVar
+
+from core_framework.domains.user.constants import (
+    DEFAULT_USER_ID,
+    DEFAULT_USERNAME,
+    REDACTED_AUTHOR_ID,
+    REDACTED_AUTHOR_USERNAME,
+    SYSTEM_USER_ID,
+    SYSTEM_USERNAME,
+)
+from core_framework.domains.user.enums import ProfileVisibility, Theme, UserRole
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CreatedUser:
+    user_id: str
+    username: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BlockedUser:
+    user_id: str
+    username: str
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Preferences:
+    theme: Theme
+    language: str
+
+    DEFAULT: ClassVar[Preferences]
+
+
+Preferences.DEFAULT = Preferences(
+    theme=Theme.LIGHT,
+    language="en",
+)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Profile:
+    display_name: str | None
+    avatar_id: str | None
+    banner_id: str | None
+    bio: str | None
+    status: str | None
+    social_links: dict[str, str]
+    profile_visibility: ProfileVisibility
+
+    DEFAULT: ClassVar[Profile]
+
+
+Profile.DEFAULT = Profile(
+    display_name=None,
+    avatar_id=None,
+    banner_id=None,
+    bio=None,
+    status=None,
+    social_links={},
+    profile_visibility=ProfileVisibility.PUBLIC,
+)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UserIdentity:
+    user_id: str
+    username: str
+    display_name: str | None
+    role: UserRole
+    avatar_id: str | None
+    created_at: datetime
+
+    DEFAULT: ClassVar[UserIdentity]
+    SYSTEM: ClassVar[UserIdentity]
+    REDACTED_AUTHOR: ClassVar[UserIdentity]
+
+
+UserIdentity.DEFAULT = UserIdentity(
+    user_id=DEFAULT_USER_ID,
+    username=DEFAULT_USERNAME,
+    display_name=None,
+    role=UserRole.MEMBER,
+    avatar_id=None,
+    created_at=datetime(1970, 1, 1),
+)
+
+UserIdentity.SYSTEM = UserIdentity(
+    user_id=SYSTEM_USER_ID,
+    username=SYSTEM_USERNAME,
+    display_name=None,
+    role=UserRole.MEMBER,
+    avatar_id=None,
+    created_at=datetime(1970, 1, 1),
+)
+
+UserIdentity.REDACTED_AUTHOR = UserIdentity(
+    user_id=REDACTED_AUTHOR_ID,
+    username=REDACTED_AUTHOR_USERNAME,
+    display_name=None,
+    role=UserRole.MEMBER,
+    avatar_id=None,
+    created_at=datetime(1970, 1, 1),
+)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UserWithProfile:
+    identity: UserIdentity
+    profile: Profile
+    deletion_scheduled_for: datetime | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UserChangeHistory:
+    user_id: str
+    actor_id: str | None
+    entity_type: str
+    field: str
+    old_value: str | None
+    new_value: str | None
+    created_at: datetime