notionary 0.2.26__py3-none-any.whl → 0.2.28__py3-none-any.whl

notionary/page/properties/service.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Never
+
+from notionary.blocks.rich_text.rich_text_markdown_converter import convert_rich_text_to_markdown
+from notionary.exceptions.properties import (
+    AccessPagePropertyWithoutDataSourceError,
+    PagePropertyNotFoundError,
+    PagePropertyTypeError,
+)
+from notionary.page.properties.client import PagePropertyHttpClient
+from notionary.page.properties.models import (
+    PageCheckboxProperty,
+    PageCreatedTimeProperty,
+    PageDateProperty,
+    PageEmailProperty,
+    PageMultiSelectProperty,
+    PageNumberProperty,
+    PagePeopleProperty,
+    PagePhoneNumberProperty,
+    PageProperty,
+    PagePropertyT,
+    PageRelationProperty,
+    PageRichTextProperty,
+    PageSelectProperty,
+    PageStatusProperty,
+    PageTitleProperty,
+    PageURLProperty,
+)
+from notionary.shared.models.parent import ParentType
+
+if TYPE_CHECKING:
+    from notionary import NotionDataSource
+
+
+class PagePropertyHandler:
+    def __init__(
+        self,
+        properties: dict[str, PageProperty],
+        parent_type: ParentType,
+        page_url: str,
+        page_property_http_client: PagePropertyHttpClient,
+        parent_data_source: str,
+    ) -> None:
+        self._properties = properties
+        self._parent_type = parent_type
+        self._page_url = page_url
+        self._property_http_client = page_property_http_client
+        self._parent_data_source_id = parent_data_source
+        self._parent_data_source: NotionDataSource | None = None
+        self._data_source_loaded = False
+
+    # =========================================================================
+    # Reader Methods
+    # =========================================================================
+
+    def get_value_of_status_property(self, name: str) -> str | None:
+        status_property = self._get_typed_property_or_raise(name, PageStatusProperty)
+        return status_property.status.name if status_property.status else None
+
+    def get_value_of_select_property(self, name: str) -> str | None:
+        select_property = self._get_typed_property_or_raise(name, PageSelectProperty)
+        return select_property.select.name if select_property.select else None
+
+    async def get_value_of_title_property(self, name: str) -> str:
+        title_property = self._get_typed_property_or_raise(name, PageTitleProperty)
+        return await convert_rich_text_to_markdown(title_property.title)
+
+    def get_values_of_people_property(self, property_name: str) -> list[str]:
+        people_prop = self._get_typed_property_or_raise(property_name, PagePeopleProperty)
+        return [person.name for person in people_prop.people if person.name]
+
+    def get_value_of_created_time_property(self, name: str) -> str | None:
+        created_time_property = self._get_typed_property_or_raise(name, PageCreatedTimeProperty)
+        return created_time_property.created_time
+
+    async def get_values_of_relation_property(self, name: str) -> list[str]:
+        from notionary import NotionPage
+
+        relation_property = self._get_typed_property_or_raise(name, PageRelationProperty)
+        relation_page_ids = [rel.id for rel in relation_property.relation]
+        notion_pages = [await NotionPage.from_id(page_id) for page_id in relation_page_ids]
+        return [page.title for page in notion_pages if page]
+
+    def get_values_of_multiselect_property(self, name: str) -> list[str]:
+        multiselect_property = self._get_typed_property_or_raise(name, PageMultiSelectProperty)
+        return [option.name for option in multiselect_property.multi_select]
+
+    def get_value_of_url_property(self, name: str) -> str | None:
+        url_property = self._get_typed_property_or_raise(name, PageURLProperty)
+        return url_property.url
+
+    def get_value_of_number_property(self, name: str) -> float | None:
+        number_property = self._get_typed_property_or_raise(name, PageNumberProperty)
+        return number_property.number
+
+    def get_value_of_checkbox_property(self, name: str) -> bool:
+        checkbox_property = self._get_typed_property_or_raise(name, PageCheckboxProperty)
+        return checkbox_property.checkbox
+
+    def get_value_of_date_property(self, name: str) -> str | None:
+        date_property = self._get_typed_property_or_raise(name, PageDateProperty)
+        return date_property.date.start if date_property.date else None
+
+    async def get_value_of_rich_text_property(self, name: str) -> str:
+        rich_text_property = self._get_typed_property_or_raise(name, PageRichTextProperty)
+        return await convert_rich_text_to_markdown(rich_text_property.rich_text)
+
+    def get_value_of_email_property(self, name: str) -> str | None:
+        email_property = self._get_typed_property_or_raise(name, PageEmailProperty)
+        return email_property.email
+
+    def get_value_of_phone_number_property(self, name: str) -> str | None:
+        phone_property = self._get_typed_property_or_raise(name, PagePhoneNumberProperty)
+        return phone_property.phone_number
+
+    # =========================================================================
+    # Options Getters
+    # =========================================================================
+
+    async def get_select_options_by_property_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return data_source.get_select_options_by_property_name(property_name)
+
+    async def get_multi_select_options_by_property_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return data_source.get_multi_select_options_by_property_name(property_name)
+
+    async def get_status_options_by_property_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return data_source.get_status_options_by_property_name(property_name)
+
+    async def get_relation_options_by_property_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return await data_source.get_relation_options_by_property_name(property_name)
+
+    async def get_options_for_property_by_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return await data_source.get_options_for_property_by_name(property_name)
+
+    # =========================================================================
+    # Writer Methods
+    # =========================================================================
+
+    async def set_title_property(self, property_name: str, title: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageTitleProperty)
+        updated_page = await self._property_http_client.patch_title(property_name, title)
+        self._properties = updated_page.properties
+
+    async def set_rich_text_property(self, property_name: str, text: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageRichTextProperty)
+        updated_page = await self._property_http_client.patch_rich_text_property(property_name, text)
+        self._properties = updated_page.properties
+
+    async def set_url_property(self, property_name: str, url: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageURLProperty)
+        updated_page = await self._property_http_client.patch_url_property(property_name, url)
+        self._properties = updated_page.properties
+
+    async def set_email_property(self, property_name: str, email: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageEmailProperty)
+        updated_page = await self._property_http_client.patch_email_property(property_name, email)
+        self._properties = updated_page.properties
+
+    async def set_phone_number_property(self, property_name: str, phone_number: str) -> None:
+        self._get_typed_property_or_raise(property_name, PagePhoneNumberProperty)
+        updated_page = await self._property_http_client.patch_phone_property(property_name, phone_number)
+        self._properties = updated_page.properties
+
+    async def set_number_property(self, property_name: str, number: int | float) -> None:
+        self._get_typed_property_or_raise(property_name, PageNumberProperty)
+        updated_page = await self._property_http_client.patch_number_property(property_name, number)
+        self._properties = updated_page.properties
+
+    async def set_checkbox_property(self, property_name: str, checked: bool) -> None:
+        self._get_typed_property_or_raise(property_name, PageCheckboxProperty)
+        updated_page = await self._property_http_client.patch_checkbox_property(property_name, checked)
+        self._properties = updated_page.properties
+
+    async def set_date_property(self, property_name: str, date_value: str | dict) -> None:
+        self._get_typed_property_or_raise(property_name, PageDateProperty)
+        updated_page = await self._property_http_client.patch_date_property(property_name, date_value)
+        self._properties = updated_page.properties
+
+    async def set_select_property_by_option_name(self, property_name: str, option_name: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageSelectProperty)
+        updated_page = await self._property_http_client.patch_select_property(property_name, option_name)
+        self._properties = updated_page.properties
+
+    async def set_multi_select_property_by_option_names(self, property_name: str, option_names: list[str]) -> None:
+        self._get_typed_property_or_raise(property_name, PageMultiSelectProperty)
+        updated_page = await self._property_http_client.patch_multi_select_property(property_name, option_names)
+        self._properties = updated_page.properties
+
+    async def set_status_property_by_option_name(self, property_name: str, status: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageStatusProperty)
+        updated_page = await self._property_http_client.patch_status_property(property_name, status)
+        self._properties = updated_page.properties
+
+    async def set_relation_property_by_page_titles(self, property_name: str, page_titles: list[str]) -> None:
+        self._get_typed_property_or_raise(property_name, PageRelationProperty)
+        relation_ids = await self._convert_page_titles_to_ids(page_titles)
+        updated_page = await self._property_http_client.patch_relation_property(property_name, relation_ids)
+        self._properties = updated_page.properties
+
+    async def _ensure_data_source_loaded(self) -> None:
+        from notionary import NotionDataSource
+
+        if self._data_source_loaded:
+            return
+
+        self._parent_data_source = (
+            await NotionDataSource.from_id(self._parent_data_source_id) if self._parent_data_source_id else None
+        )
+        self._data_source_loaded = True
+
+    async def _get_parent_data_source_or_raise(self) -> NotionDataSource:
+        await self._ensure_data_source_loaded()
+
+        if not self._parent_data_source:
+            raise AccessPagePropertyWithoutDataSourceError(self._parent_type)
+        return self._parent_data_source
+
+    def _get_typed_property_or_raise(self, name: str, property_type: type[PagePropertyT]) -> PagePropertyT:
+        prop = self._properties.get(name)
+
+        if prop is None:
+            self._handle_prop_not_found(name)
+
+        if not isinstance(prop, property_type):
+            self._handle_incorrect_type(name, type(prop))
+
+        return prop
+
+    def _handle_prop_not_found(self, name: str) -> Never:
+        raise PagePropertyNotFoundError(
+            property_name=name,
+            page_url=self._page_url,
+            available_properties=list(self._properties.keys()),
+        )
+
+    def _handle_incorrect_type(self, property_name: str, actual_type: type) -> Never:
+        raise PagePropertyTypeError(
+            property_name=property_name,
+            actual_type=actual_type.__name__,
+        )
+
+    async def _convert_page_titles_to_ids(self, page_titles: list[str]) -> list[str]:
+        from notionary import NotionPage
+
+        if not page_titles:
+            return []
+
+        pages = await asyncio.gather(*[NotionPage.from_title(title=title) for title in page_titles])
+
+        return [page.id for page in pages if page]

notionary/page/schemas.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+
+from notionary.page.properties.models import DiscriminatedPageProperty
+from notionary.shared.entity.schemas import EntityResponseDto
+
+
+class NotionPageDto(EntityResponseDto):
+    archived: bool
+    properties: dict[str, DiscriminatedPageProperty]
+
+
+class PgePropertiesUpdateDto(BaseModel):
+    properties: dict[str, DiscriminatedPageProperty]

notionary/page/service.py

@@ -0,0 +1,222 @@
+from collections.abc import Callable
+from typing import Self
+
+from notionary.blocks.client import NotionBlockHttpClient
+from notionary.blocks.rich_text.rich_text_markdown_converter import convert_rich_text_to_markdown
+from notionary.comments.models import Comment
+from notionary.comments.service import CommentService
+from notionary.page.content.factory import PageContentServiceFactory
+from notionary.page.content.markdown.builder import MarkdownBuilder
+from notionary.page.content.service import PageContentService
+from notionary.page.page_http_client import NotionPageHttpClient
+from notionary.page.page_metadata_update_client import PageMetadataUpdateClient
+from notionary.page.properties.factory import PagePropertyHandlerFactory
+from notionary.page.properties.models import PageTitleProperty
+from notionary.page.properties.service import PagePropertyHandler
+from notionary.page.schemas import NotionPageDto
+from notionary.shared.entity.dto_parsers import (
+    extract_cover_image_url_from_dto,
+    extract_emoji_icon_from_dto,
+    extract_external_icon_url_from_dto,
+)
+from notionary.shared.entity.service import Entity
+from notionary.user.schemas import PartialUserDto
+from notionary.workspace.query.service import WorkspaceQueryService
+
+
+class NotionPage(Entity):
+    def __init__(
+        self,
+        id: str,
+        title: str,
+        created_time: str,
+        created_by: PartialUserDto,
+        last_edited_time: str,
+        last_edited_by: PartialUserDto,
+        url: str,
+        archived: bool,
+        in_trash: bool,
+        page_property_handler: PagePropertyHandler,
+        block_client: NotionBlockHttpClient,
+        comment_service: CommentService,
+        page_content_service: PageContentService,
+        metadata_update_client: PageMetadataUpdateClient,
+        public_url: str | None = None,
+        emoji_icon: str | None = None,
+        external_icon_url: str | None = None,
+        cover_image_url: str | None = None,
+    ) -> None:
+        super().__init__(
+            id=id,
+            created_time=created_time,
+            created_by=created_by,
+            last_edited_time=last_edited_time,
+            last_edited_by=last_edited_by,
+            in_trash=in_trash,
+            emoji_icon=emoji_icon,
+            external_icon_url=external_icon_url,
+            cover_image_url=cover_image_url,
+        )
+        self._title = title
+        self._archived = archived
+        self._url = url
+        self._public_url = public_url
+
+        self._block_client = block_client
+        self._comment_service = comment_service
+        self._page_content_service = page_content_service
+        self.properties = page_property_handler
+        self._metadata_update_client = metadata_update_client
+
+    @classmethod
+    async def from_id(
+        cls,
+        page_id: str,
+        page_property_handler_factory: PagePropertyHandlerFactory | None = None,
+    ) -> Self:
+        factory = page_property_handler_factory or PagePropertyHandlerFactory()
+        response = await cls._fetch_page_dto(page_id)
+        return await cls._create_from_dto(response, factory)
+
+    @classmethod
+    async def from_title(
+        cls,
+        page_title: str,
+        min_similarity: float = 0.6,
+        search_service: WorkspaceQueryService | None = None,
+    ) -> Self:
+        service = search_service or WorkspaceQueryService()
+        return await service.find_page(page_title, min_similarity=min_similarity)
+
+    @classmethod
+    async def _fetch_page_dto(cls, page_id: str) -> NotionPageDto:
+        async with NotionPageHttpClient(page_id=page_id) as client:
+            return await client.get_page()
+
+    @classmethod
+    async def _create_from_dto(
+        cls,
+        response: NotionPageDto,
+        page_property_handler_factory: PagePropertyHandlerFactory,
+    ) -> Self:
+        title_task = cls._extract_title_from_dto(response)
+        page_property_handler = page_property_handler_factory.create_from_page_response(response)
+
+        title = await title_task
+
+        return cls._create_with_dependencies(
+            id=response.id,
+            title=title,
+            created_time=response.created_time,
+            created_by=response.created_by,
+            last_edited_time=response.last_edited_time,
+            last_edited_by=response.last_edited_by,
+            archived=response.archived,
+            in_trash=response.in_trash,
+            url=response.url,
+            page_property_handler=page_property_handler,
+            public_url=response.public_url,
+            emoji_icon=extract_emoji_icon_from_dto(response),
+            external_icon_url=extract_external_icon_url_from_dto(response),
+            cover_image_url=extract_cover_image_url_from_dto(response),
+        )
+
+    @classmethod
+    def _create_with_dependencies(
+        cls,
+        id: str,
+        title: str,
+        created_time: str,
+        created_by: PartialUserDto,
+        last_edited_time: str,
+        last_edited_by: PartialUserDto,
+        url: str,
+        archived: bool,
+        in_trash: bool,
+        page_property_handler: PagePropertyHandler,
+        public_url: str | None = None,
+        emoji_icon: str | None = None,
+        external_icon_url: str | None = None,
+        cover_image_url: str | None = None,
+    ) -> Self:
+        block_client = NotionBlockHttpClient()
+        comment_service = CommentService()
+
+        page_content_service_factory = PageContentServiceFactory()
+        page_content_service = page_content_service_factory.create(page_id=id, block_client=block_client)
+
+        metadata_update_client = PageMetadataUpdateClient(page_id=id)
+
+        return cls(
+            id=id,
+            title=title,
+            created_time=created_time,
+            created_by=created_by,
+            last_edited_time=last_edited_time,
+            last_edited_by=last_edited_by,
+            url=url,
+            archived=archived,
+            in_trash=in_trash,
+            page_property_handler=page_property_handler,
+            block_client=block_client,
+            comment_service=comment_service,
+            page_content_service=page_content_service,
+            metadata_update_client=metadata_update_client,
+            public_url=public_url,
+            emoji_icon=emoji_icon,
+            external_icon_url=external_icon_url,
+            cover_image_url=cover_image_url,
+        )
+
+    @staticmethod
+    async def _extract_title_from_dto(response: NotionPageDto) -> str:
+        title_property = next(
+            (prop for prop in response.properties.values() if isinstance(prop, PageTitleProperty)),
+            None,
+        )
+        rich_text_title = title_property.title if title_property else []
+        return await convert_rich_text_to_markdown(rich_text_title)
+
+    @property
+    def _entity_metadata_update_client(self) -> PageMetadataUpdateClient:
+        return self._metadata_update_client
+
+    @property
+    def title(self) -> str:
+        return self._title
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    async def get_comments(self) -> list[Comment]:
+        return await self._comment_service.list_all_comments_for_page(page_id=self._id)
+
+    async def post_top_level_comment(self, comment: str) -> None:
+        await self._comment_service.create_comment_on_page(page_id=self._id, text=comment)
+
+    async def post_reply_to_discussion(self, discussion_id: str, comment: str) -> None:
+        await self._comment_service.reply_to_discussion_by_id(discussion_id=discussion_id, text=comment)
+
+    async def set_title(self, title: str) -> None:
+        await self.properties.set_title_property(title)
+        self._title = title
+
+    async def append_markdown(
+        self,
+        content: (str | Callable[[MarkdownBuilder], MarkdownBuilder]),
+    ) -> None:
+        await self._page_content_service.append_markdown(content=content)
+
+    async def replace_content(
+        self,
+        content: (str | Callable[[MarkdownBuilder], MarkdownBuilder]),
+    ) -> None:
+        await self._page_content_service.clear()
+        await self._page_content_service.append_markdown(content=content)
+
+    async def clear_page_content(self) -> None:
+        await self._page_content_service.clear()
+
+    async def get_markdown_content(self) -> str:
+        return await self._page_content_service.get_as_markdown()

notionary/shared/entity/client.py

@@ -0,0 +1,29 @@
+from typing import TypeVar, override
+
+from notionary.http.client import NotionHttpClient
+from notionary.shared.entity.entity_metadata_update_client import EntityMetadataUpdateClient
+from notionary.shared.entity.schemas import EntityResponseDto, NotionEntityUpdateDto
+
+ResponseType = TypeVar("ResponseType", bound=EntityResponseDto)
+
+
+class GenericEntityMetadataUpdateClient(NotionHttpClient, EntityMetadataUpdateClient):
+    def __init__(
+        self,
+        entity_id: str,
+        path_segment: str,
+        response_dto_class: type[ResponseType],
+        timeout: int = 30,
+    ) -> None:
+        super().__init__(timeout)
+        self._entity_id = entity_id
+        self._path_segment = path_segment
+        self._response_dto_class = response_dto_class
+
+    @override
+    async def patch_metadata(self, updated_data: NotionEntityUpdateDto) -> ResponseType:
+        updated_data_dict = updated_data.model_dump(exclude_unset=True, exclude_none=True)
+        url = f"{self._path_segment}/{self._entity_id}"
+
+        response_dict = await self.patch(url, data=updated_data_dict)
+        return self._response_dto_class.model_validate(response_dict)

notionary/shared/entity/dto_parsers.py

@@ -0,0 +1,53 @@
+from typing import cast
+
+from notionary.blocks.rich_text.rich_text_markdown_converter import RichTextToMarkdownConverter
+from notionary.shared.entity.schemas import Describable, EntityResponseDto, Titled
+from notionary.shared.models.cover import CoverType
+from notionary.shared.models.icon import IconType
+from notionary.shared.models.parent import DatabaseParent, DataSourceParent, ParentType
+
+
+def extract_emoji_icon_from_dto(entity_dto: EntityResponseDto) -> str | None:
+    if not entity_dto.icon or entity_dto.icon.type != IconType.EMOJI:
+        return None
+    return entity_dto.icon.emoji
+
+
+def extract_external_icon_url_from_dto(entity_dto: EntityResponseDto) -> str | None:
+    if not entity_dto.icon or entity_dto.icon.type != IconType.EXTERNAL:
+        return None
+    return entity_dto.icon.external.url if entity_dto.icon.external else None
+
+
+def extract_cover_image_url_from_dto(entity_dto: EntityResponseDto) -> str | None:
+    if not entity_dto.cover or entity_dto.cover.type != CoverType.EXTERNAL:
+        return None
+    return entity_dto.cover.external.url if entity_dto.cover.external else None
+
+
+def extract_database_id(entity_dto: EntityResponseDto) -> str | None:
+    if entity_dto.parent.type == ParentType.DATA_SOURCE_ID:
+        data_source_parent = cast(DataSourceParent, entity_dto.parent)
+        return data_source_parent.database_id if data_source_parent else None
+
+    if entity_dto.parent.type == ParentType.DATABASE_ID:
+        database_parent = cast(DatabaseParent, entity_dto.parent)
+        return database_parent.database_id if database_parent else None
+
+    return None
+
+
+async def extract_title(
+    entity: Titled,
+    rich_text_converter: RichTextToMarkdownConverter,
+) -> str:
+    return await rich_text_converter.to_markdown(entity.title)
+
+
+async def extract_description(
+    entity: Describable,
+    rich_text_converter: RichTextToMarkdownConverter,
+) -> str | None:
+    if not entity.description:
+        return None
+    return await rich_text_converter.to_markdown(entity.description)

notionary/shared/entity/entity_metadata_update_client.py

@@ -0,0 +1,41 @@
+from abc import ABC, abstractmethod
+
+from notionary.shared.entity.schemas import EntityResponseDto, NotionEntityUpdateDto
+from notionary.shared.models.cover import NotionCover
+from notionary.shared.models.icon import EmojiIcon, ExternalIcon
+
+
+class EntityMetadataUpdateClient(ABC):
+    @abstractmethod
+    async def patch_metadata(self, updated_data: NotionEntityUpdateDto) -> EntityResponseDto: ...
+
+    async def patch_emoji_icon(self, emoji: str) -> EntityResponseDto:
+        icon = EmojiIcon(emoji=emoji)
+        update_dto = NotionEntityUpdateDto(icon=icon)
+        return await self.patch_metadata(update_dto)
+
+    async def patch_external_icon(self, icon_url: str) -> EntityResponseDto:
+        icon = ExternalIcon.from_url(icon_url)
+        update_dto = NotionEntityUpdateDto(icon=icon)
+        return await self.patch_metadata(update_dto)
+
+    async def remove_icon(self) -> None:
+        update_dto = NotionEntityUpdateDto(icon=None)
+        return await self.patch_metadata(update_dto)
+
+    async def patch_external_cover(self, cover_url: str) -> EntityResponseDto:
+        cover = NotionCover.from_url(cover_url)
+        update_dto = NotionEntityUpdateDto(cover=cover)
+        return await self.patch_metadata(update_dto)
+
+    async def remove_cover(self) -> None:
+        update_dto = NotionEntityUpdateDto(cover=None)
+        return await self.patch_metadata(update_dto)
+
+    async def move_to_trash(self) -> EntityResponseDto:
+        update_dto = NotionEntityUpdateDto(in_trash=True)
+        return await self.patch_metadata(update_dto)
+
+    async def restore_from_trash(self) -> EntityResponseDto:
+        update_dto = NotionEntityUpdateDto(in_trash=False)
+        return await self.patch_metadata(update_dto)

notionary/shared/entity/schemas.py

@@ -0,0 +1,45 @@
+from enum import StrEnum
+from typing import Protocol
+
+from pydantic import BaseModel
+
+from notionary.blocks.rich_text.models import RichText
+from notionary.shared.models.cover import NotionCover
+from notionary.shared.models.icon import Icon
+from notionary.shared.models.parent import Parent
+from notionary.user.schemas import PartialUserDto
+
+
+class EntityWorkspaceQueryObjectType(StrEnum):
+    PAGE = "page"
+    DATA_SOURCE = "data_source"
+    DATABASE = "database"
+
+
+class EntityResponseDto(BaseModel):
+    object: EntityWorkspaceQueryObjectType
+    id: str
+    created_time: str
+    created_by: PartialUserDto
+    last_edited_time: str
+    last_edited_by: PartialUserDto
+    cover: NotionCover | None = None
+    icon: Icon | None = None
+    parent: Parent
+    in_trash: bool
+    url: str
+    public_url: str | None = None
+
+
+class NotionEntityUpdateDto(BaseModel):
+    icon: Icon | None = None
+    cover: NotionCover | None = None
+    in_trash: bool | None = None
+
+
+class Titled(Protocol):
+    title: list[RichText]
+
+
+class Describable(Protocol):
+    description: list[RichText] | None