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

notionary/user/base_notion_user.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+from abc import ABC
+from typing import Optional
+from notionary.user.client import NotionUserClient
+
+from notionary.util import LoggingMixin
+
+
+class BaseNotionUser(LoggingMixin, ABC):
+    """
+    Base class for all Notion user types with common functionality.
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        name: Optional[str] = None,
+        avatar_url: Optional[str] = None,
+        token: Optional[str] = None,
+    ):
+        """Initialize base user properties."""
+        self._user_id = user_id
+        self._name = name
+        self._avatar_url = avatar_url
+        self.client = NotionUserClient(token=token)
+
+    @property
+    def id(self) -> str:
+        """Get the user ID."""
+        return self._user_id
+
+    @property
+    def name(self) -> Optional[str]:
+        """Get the user name."""
+        return self._name
+
+    @property
+    def avatar_url(self) -> Optional[str]:
+        """Get the avatar URL."""
+        return self._avatar_url
+
+    def get_display_name(self) -> str:
+        """Get a display name for the user."""
+        return self._name or f"User {self._user_id[:8]}"
+
+    def __str__(self) -> str:
+        """String representation of the user."""
+        return f"{self.__class__.__name__}(name='{self.get_display_name()}', id='{self._user_id[:8]}...')"
+
+    def __repr__(self) -> str:
+        """Detailed string representation."""
+        return self.__str__()

notionary/user/client.py

@@ -0,0 +1,129 @@
+from typing import Optional, List
+from notionary.base_notion_client import BaseNotionClient
+from notionary.user.models import (
+    NotionBotUserResponse,
+    NotionUserResponse,
+    NotionUsersListResponse,
+)
+from notionary.util import singleton
+
+
+@singleton
+class NotionUserClient(BaseNotionClient):
+    """
+    Client for Notion user-specific operations.
+    Inherits base HTTP functionality from BaseNotionClient.
+
+    Note: The Notion API only supports individual user queries and bot user info.
+    List users endpoint is available but only returns workspace members (no guests).
+    """
+
+    async def get_user(self, user_id: str) -> Optional[NotionUserResponse]:
+        """
+        Retrieve a user by their ID.
+        """
+        response = await self.get(f"users/{user_id}")
+        if response is None:
+            self.logger.error("Failed to fetch user %s - API returned None", user_id)
+            return None
+
+        try:
+            return NotionUserResponse.model_validate(response)
+        except Exception as e:
+            self.logger.error("Failed to validate user response for %s: %s", user_id, e)
+            return None
+
+    async def get_bot_user(self) -> Optional[NotionBotUserResponse]:
+        """
+        Retrieve your token's bot user information.
+        """
+        response = await self.get("users/me")
+        if response is None:
+            self.logger.error("Failed to fetch bot user - API returned None")
+            return None
+
+        try:
+            return NotionBotUserResponse.model_validate(response)
+        except Exception as e:
+            self.logger.error("Failed to validate bot user response: %s", e)
+            return None
+
+    async def list_users(
+        self, page_size: int = 100, start_cursor: Optional[str] = None
+    ) -> Optional[NotionUsersListResponse]:
+        """
+        List all users in the workspace (paginated).
+
+        Note: Guests are not included in the response.
+        """
+        params = {"page_size": min(page_size, 100)}  # API max is 100
+        if start_cursor:
+            params["start_cursor"] = start_cursor
+
+        response = await self.get("users", params=params)
+        if response is None:
+            self.logger.error("Failed to fetch users list - API returned None")
+            return None
+
+        try:
+            return NotionUsersListResponse.model_validate(response)
+        except Exception as e:
+            self.logger.error("Failed to validate users list response: %s", e)
+            return None
+
+    async def get_all_users(self) -> List[NotionUserResponse]:
+        """
+        Get all users in the workspace by handling pagination automatically.
+        """
+        all_users = []
+        start_cursor = None
+
+        while True:
+            try:
+                response = await self.list_users(
+                    page_size=100, start_cursor=start_cursor
+                )
+
+                if not response or not response.results:
+                    break
+
+                all_users.extend(response.results)
+
+                # Check if there are more pages
+                if not response.has_more or not response.next_cursor:
+                    break
+
+                start_cursor = response.next_cursor
+
+            except Exception as e:
+                self.logger.error("Error fetching all users: %s", str(e))
+                break
+
+        self.logger.info("Retrieved %d total users from workspace", len(all_users))
+        return all_users
+
+    async def get_workspace_name(self) -> Optional[str]:
+        """
+        Get the workspace name from the bot user.
+        """
+        try:
+            bot_user = await self.get_bot_user()
+            if bot_user and bot_user.bot and bot_user.bot.workspace_name:
+                return bot_user.bot.workspace_name
+            return None
+        except Exception as e:
+            self.logger.error("Error fetching workspace name: %s", str(e))
+            return None
+
+    async def get_workspace_limits(self) -> Optional[dict]:
+        """
+        Get workspace limits from the bot user.
+        """
+        try:
+            bot_user = await self.get_bot_user()
+            if bot_user and bot_user.bot and bot_user.bot.workspace_limits:
+                return bot_user.bot.workspace_limits.model_dump()
+            return None
+        except Exception as e:
+            self.logger.error("Error fetching workspace limits: %s", str(e))
+            return None

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