notionary 0.2.16__py3-none-any.whl → 0.2.17__py3-none-any.whl

notionary/user/models.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass
+from typing import Literal, Optional
+from pydantic import BaseModel
+
+
+class PersonUser(BaseModel):
+    """Person user details"""
+
+    email: Optional[str] = None
+
+
+class BotOwner(BaseModel):
+    """Bot owner information - simplified structure"""
+
+    type: Literal["workspace", "user"]
+    workspace: Optional[bool] = None
+
+
+class WorkspaceLimits(BaseModel):
+    """Workspace limits for bot users"""
+
+    max_file_upload_size_in_bytes: int
+
+
+class BotUser(BaseModel):
+    """Bot user details"""
+
+    owner: Optional[BotOwner] = None
+    workspace_name: Optional[str] = None
+    workspace_limits: Optional[WorkspaceLimits] = None
+
+
+class NotionUserResponse(BaseModel):
+    """
+    Represents a Notion user object as returned by the Users API.
+    Can represent both person and bot users.
+    """
+
+    object: Literal["user"]
+    id: str
+    type: Optional[Literal["person", "bot"]] = None
+    name: Optional[str] = None
+    avatar_url: Optional[str] = None
+
+    # Person-specific fields
+    person: Optional[PersonUser] = None
+
+    # Bot-specific fields
+    bot: Optional[BotUser] = None
+
+
+class NotionBotUserResponse(NotionUserResponse):
+    """
+    Specialized response for bot user (from /users/me endpoint)
+    """
+
+    # Bot users should have these fields, but they can still be None
+    type: Literal["bot"]
+    bot: Optional[BotUser] = None
+
+
+class NotionUsersListResponse(BaseModel):
+    """
+    Response model for paginated users list from /v1/users endpoint.
+    Follows Notion's standard pagination pattern.
+    """
+
+    object: Literal["list"]
+    results: list[NotionUserResponse]
+    next_cursor: Optional[str] = None
+    has_more: bool
+    type: Literal["user"]
+    user: dict = {}
+
+
+@dataclass
+class WorkspaceInfo:
+    """Dataclass to hold workspace information for bot users."""
+
+    name: Optional[str] = None
+    limits: Optional[WorkspaceLimits] = None
+    owner_type: Optional[str] = None
+    is_workspace_owned: bool = False

notionary/user/notion_bot_user.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+from typing import Optional, List
+from notionary.user.base_notion_user import BaseNotionUser
+from notionary.user.client import NotionUserClient
+from notionary.user.models import (
+    NotionBotUserResponse,
+    WorkspaceLimits,
+)
+from notionary.util import factory_only
+from notionary.util.fuzzy import find_best_match
+
+
+class NotionBotUser(BaseNotionUser):
+    """
+    Manager for Notion bot users.
+    Handles bot-specific operations and workspace information.
+    """
+
+    NO_USERS_FOUND_MSG = "No users found in workspace"
+    NO_BOT_USERS_FOUND_MSG = "No bot users found in workspace"
+
+    @factory_only("from_current_integration", "from_bot_response", "from_name")
+    def __init__(
+        self,
+        user_id: str,
+        name: Optional[str] = None,
+        avatar_url: Optional[str] = None,
+        workspace_name: Optional[str] = None,
+        workspace_limits: Optional[WorkspaceLimits] = None,
+        owner_type: Optional[str] = None,
+        token: Optional[str] = None,
+    ):
+        """Initialize bot user with bot-specific properties."""
+        super().__init__(user_id, name, avatar_url, token)
+        self._workspace_name = workspace_name
+        self._workspace_limits = workspace_limits
+        self._owner_type = owner_type
+
+    @classmethod
+    async def from_current_integration(
+        cls, token: Optional[str] = None
+    ) -> Optional[NotionBotUser]:
+        """
+        Get the current bot user (from the API token).
+
+        Args:
+            token: Optional Notion API token
+
+        Returns:
+            Optional[NotionBotUser]: Bot user instance or None if failed
+        """
+        client = NotionUserClient(token=token)
+        bot_response = await client.get_bot_user()
+
+        if bot_response is None:
+            cls.logger.error("Failed to load bot user data")
+            return None
+
+        return cls._create_from_response(bot_response, token)
+
+    @classmethod
+    async def from_name(
+        cls, name: str, token: Optional[str] = None, min_similarity: float = 0.6
+    ) -> Optional[NotionBotUser]:
+        """
+        Create a NotionBotUser by finding a bot user with fuzzy matching on the name.
+        Uses Notion's list users API and fuzzy matching to find the best result.
+        """
+        client = NotionUserClient(token=token)
+
+        try:
+            # Get all users from workspace
+            all_users_response = await client.get_all_users()
+
+            if not all_users_response:
+                cls.logger.warning(cls.NO_USERS_FOUND_MSG)
+                raise ValueError(cls.NO_USERS_FOUND_MSG)
+
+            # Filter to only bot users
+            bot_users = [
+                user for user in all_users_response if user.type == "bot" and user.name
+            ]
+
+            if not bot_users:
+                cls.logger.warning(cls.NO_BOT_USERS_FOUND_MSG)
+                raise ValueError(cls.NO_BOT_USERS_FOUND_MSG)
+
+            cls.logger.debug(
+                "Found %d bot users for fuzzy matching: %s",
+                len(bot_users),
+                [user.name for user in bot_users[:5]],  # Log first 5 names
+            )
+
+            # Use fuzzy matching to find best match
+            best_match = find_best_match(
+                query=name,
+                items=bot_users,
+                text_extractor=lambda user: user.name or "",
+                min_similarity=min_similarity,
+            )
+
+            if not best_match:
+                available_names = [user.name for user in bot_users[:5]]
+                cls.logger.warning(
+                    "No sufficiently similar bot user found for '%s' (min: %.3f). Available: %s",
+                    name,
+                    min_similarity,
+                    available_names,
+                )
+                raise ValueError(f"No sufficiently similar bot user found for '{name}'")
+
+            cls.logger.info(
+                "Found best match: '%s' with similarity %.3f for query '%s'",
+                best_match.matched_text,
+                best_match.similarity,
+                name,
+            )
+
+            # Create NotionBotUser from the matched user response
+            return cls._create_from_response(best_match.item, token)
+
+        except Exception as e:
+            cls.logger.error("Error finding bot user by name '%s': %s", name, str(e))
+            raise
+
+    @classmethod
+    def from_bot_response(
+        cls, bot_response: NotionBotUserResponse, token: Optional[str] = None
+    ) -> NotionBotUser:
+        """
+        Create a NotionBotUser from an existing bot API response.
+
+        Args:
+            bot_response: Bot user response from Notion API
+            token: Optional Notion API token
+
+        Returns:
+            NotionBotUser: Bot user instance
+        """
+        return cls._create_from_response(bot_response, token)
+
+    @property
+    def workspace_name(self) -> Optional[str]:
+        """Get the workspace name."""
+        return self._workspace_name
+
+    @property
+    def workspace_limits(self) -> Optional[WorkspaceLimits]:
+        """Get the workspace limits."""
+        return self._workspace_limits
+
+    @property
+    def owner_type(self) -> Optional[str]:
+        """Get the owner type ('workspace' or 'user')."""
+        return self._owner_type
+
+    @property
+    def user_type(self) -> str:
+        """Get the user type."""
+        return "bot"
+
+    @property
+    def is_person(self) -> bool:
+        """Check if this is a person user."""
+        return False
+
+    @property
+    def is_bot(self) -> bool:
+        """Check if this is a bot user."""
+        return True
+
+    @property
+    def is_workspace_integration(self) -> bool:
+        """Check if this is a workspace-owned integration."""
+        return self._owner_type == "workspace"
+
+    @property
+    def is_user_integration(self) -> bool:
+        """Check if this is a user-owned integration."""
+        return self._owner_type == "user"
+
+    @property
+    def max_file_upload_size(self) -> Optional[int]:
+        """The maximum file upload size in bytes."""
+        return (
+            self._workspace_limits.max_file_upload_size_in_bytes
+            if self._workspace_limits
+            else None
+        )
+
+    def __str__(self) -> str:
+        """String representation of the bot user."""
+        workspace = self._workspace_name or "Unknown Workspace"
+        return f"NotionBotUser(name='{self.get_display_name()}', workspace='{workspace}', id='{self._user_id[:8]}...')"
+
+    @classmethod
+    def _create_from_response(
+        cls, bot_response: NotionBotUserResponse, token: Optional[str]
+    ) -> NotionBotUser:
+        """Create NotionBotUser instance from API response."""
+        workspace_name = None
+        workspace_limits = None
+        owner_type = None
+
+        if bot_response.bot:
+            workspace_name = bot_response.bot.workspace_name
+            workspace_limits = bot_response.bot.workspace_limits
+            owner_type = bot_response.bot.owner.type if bot_response.bot.owner else None
+
+        instance = cls(
+            user_id=bot_response.id,
+            name=bot_response.name,
+            avatar_url=bot_response.avatar_url,
+            workspace_name=workspace_name,
+            workspace_limits=workspace_limits,
+            owner_type=owner_type,
+            token=token,
+        )
+
+        cls.logger.info(
+            "Created bot user: '%s' (ID: %s, Workspace: %s)",
+            bot_response.name or "Unknown Bot",
+            bot_response.id,
+            workspace_name or "Unknown",
+        )
+
+        return instance

notionary/user/notion_user.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from typing import Optional, List
+from notionary.user.base_notion_user import BaseNotionUser
+from notionary.user.client import NotionUserClient
+from notionary.user.models import (
+    NotionUserResponse,
+)
+from notionary.util import factory_only
+from notionary.util.fuzzy import find_best_matches
+
+
+class NotionUser(BaseNotionUser):
+    """
+    Manager for Notion person users.
+    Handles person-specific operations and information.
+    """
+
+    NO_USERS_FOUND_MSG = "No users found in workspace"
+    NO_PERSON_USERS_FOUND_MSG = "No person users found in workspace"
+
+    @factory_only("from_user_id", "from_user_response", "from_name")
+    def __init__(
+        self,
+        user_id: str,
+        name: Optional[str] = None,
+        avatar_url: Optional[str] = None,
+        email: Optional[str] = None,
+        token: Optional[str] = None,
+    ):
+        """Initialize person user with person-specific properties."""
+        super().__init__(user_id, name, avatar_url, token)
+        self._email = email
+
+    @classmethod
+    async def from_user_id(
+        cls, user_id: str, token: Optional[str] = None
+    ) -> Optional[NotionUser]:
+        """
+        Create a NotionUser from a user ID.
+        """
+        client = NotionUserClient(token=token)
+        user_response = await client.get_user(user_id)
+
+        if user_response is None:
+            cls.logger.error("Failed to load user data for ID: %s", user_id)
+            return None
+
+        # Ensure this is actually a person user
+        if user_response.type != "person":
+            cls.logger.error(
+                "User %s is not a person user (type: %s)", user_id, user_response.type
+            )
+            return None
+
+        return cls._create_from_response(user_response, token)
+
+    @classmethod
+    async def from_name(
+        cls, name: str, token: Optional[str] = None, min_similarity: float = 0.6
+    ) -> Optional[NotionUser]:
+        """
+        Create a NotionUser by finding a person user with fuzzy matching on the name.
+        """
+        from notionary.util import find_best_match
+
+        client = NotionUserClient(token=token)
+
+        try:
+            # Get all users from workspace
+            all_users_response = await client.get_all_users()
+
+            if not all_users_response:
+                cls.logger.warning(cls.NO_USERS_FOUND_MSG)
+                raise ValueError(cls.NO_USERS_FOUND_MSG)
+
+            person_users = [
+                user
+                for user in all_users_response
+                if user.type == "person" and user.name
+            ]
+
+            if not person_users:
+                cls.logger.warning(cls.NO_PERSON_USERS_FOUND_MSG)
+                raise ValueError(cls.NO_PERSON_USERS_FOUND_MSG)
+
+            cls.logger.debug(
+                "Found %d person users for fuzzy matching: %s",
+                len(person_users),
+                [user.name for user in person_users[:5]],
+            )
+
+            # Use fuzzy matching to find best match
+            best_match = find_best_match(
+                query=name,
+                items=person_users,
+                text_extractor=lambda user: user.name or "",
+                min_similarity=min_similarity,
+            )
+
+            if not best_match:
+                available_names = [user.name for user in person_users[:5]]
+                cls.logger.warning(
+                    "No sufficiently similar person user found for '%s' (min: %.3f). Available: %s",
+                    name,
+                    min_similarity,
+                    available_names,
+                )
+                raise ValueError(
+                    f"No sufficiently similar person user found for '{name}'"
+                )
+
+            cls.logger.info(
+                "Found best match: '%s' with similarity %.3f for query '%s'",
+                best_match.matched_text,
+                best_match.similarity,
+                name,
+            )
+
+            # Create NotionUser from the matched user response
+            return cls._create_from_response(best_match.item, token)
+
+        except Exception as e:
+            cls.logger.error("Error finding user by name '%s': %s", name, str(e))
+            raise
+
+    @classmethod
+    def from_user_response(
+        cls, user_response: NotionUserResponse, token: Optional[str] = None
+    ) -> NotionUser:
+        """
+        Create a NotionUser from an existing API response.
+        """
+        if user_response.type != "person":
+            raise ValueError(f"Cannot create NotionUser from {user_response.type} user")
+
+        return cls._create_from_response(user_response, token)
+
+    @classmethod
+    async def search_users_by_name(
+        cls,
+        name: str,
+        token: Optional[str] = None,
+        min_similarity: float = 0.3,
+        limit: Optional[int] = 5,
+    ) -> List[NotionUser]:
+        """
+        Search for multiple person users by name using fuzzy matching.
+
+        Args:
+            name: The name to search for
+            token: Optional Notion API token
+            min_similarity: Minimum similarity threshold (0.0 to 1.0), default 0.3
+            limit: Maximum number of results to return, default 5
+
+        Returns:
+            List[NotionUser]: List of matching users sorted by similarity (best first)
+        """
+        client = NotionUserClient(token=token)
+
+        try:
+            # Get all users from workspace
+            all_users_response = await client.get_all_users()
+
+            if not all_users_response:
+                cls.logger.warning(cls.NO_USERS_FOUND_MSG)
+                return []
+
+            # Filter to only person users (not bots)
+            person_users = [
+                user
+                for user in all_users_response
+                if user.type == "person" and user.name
+            ]
+
+            if not person_users:
+                cls.logger.warning(cls.NO_PERSON_USERS_FOUND_MSG)
+                return []
+
+            # Use fuzzy matching to find all matches
+            matches = find_best_matches(
+                query=name,
+                items=person_users,
+                text_extractor=lambda user: user.name or "",
+                min_similarity=min_similarity,
+                limit=limit,
+            )
+
+            cls.logger.info(
+                "Found %d matching users for query '%s'", len(matches), name
+            )
+
+            # Convert to NotionUser instances
+            result_users = []
+            for match in matches:
+                try:
+                    user = cls._create_from_response(match.item, token)
+                    result_users.append(user)
+                except Exception as e:
+                    cls.logger.warning(
+                        "Failed to create user from match '%s': %s",
+                        match.matched_text,
+                        str(e),
+                    )
+                    continue
+
+            return result_users
+
+        except Exception as e:
+            cls.logger.error("Error searching users by name '%s': %s", name, str(e))
+            return []
+
+    @property
+    def email(self) -> Optional[str]:
+        """
+        Get the user email (requires proper integration capabilities).
+        """
+        return self._email
+
+    @property
+    def user_type(self) -> str:
+        """Get the user type."""
+        return "person"
+
+    @property
+    def is_person(self) -> bool:
+        """Check if this is a person user."""
+        return True
+
+    @property
+    def is_bot(self) -> bool:
+        """Check if this is a bot user."""
+        return False
+
+    @classmethod
+    def _create_from_response(
+        cls, user_response: NotionUserResponse, token: Optional[str]
+    ) -> NotionUser:
+        """Create NotionUser instance from API response."""
+        email = user_response.person.email if user_response.person else None
+
+        instance = cls(
+            user_id=user_response.id,
+            name=user_response.name,
+            avatar_url=user_response.avatar_url,
+            email=email,
+            token=token,
+        )
+
+        cls.logger.info(
+            "Created person user: '%s' (ID: %s)",
+            user_response.name or "Unknown",
+            user_response.id,
+        )
+
+        return instance