arcade-slack 0.4.6__py3-none-any.whl → 0.5.0__py3-none-any.whl

arcade_slack/constants.py

@@ -1,13 +1,18 @@
 import os
 
-from arcade_slack.custom_types import PositiveInt
+from arcade_slack.custom_types import PositiveNonZeroInt
 
 MAX_PAGINATION_SIZE_LIMIT = 200
 
-MAX_PAGINATION_TIMEOUT_SECONDS = PositiveInt(
+MAX_PAGINATION_TIMEOUT_SECONDS = PositiveNonZeroInt(
     os.environ.get(
         "MAX_PAGINATION_TIMEOUT_SECONDS",
         os.environ.get("MAX_SLACK_PAGINATION_TIMEOUT_SECONDS", 30),
     ),
     name="MAX_PAGINATION_TIMEOUT_SECONDS or MAX_SLACK_PAGINATION_TIMEOUT_SECONDS",
 )
+
+MAX_CONCURRENT_REQUESTS = PositiveNonZeroInt(
+    os.environ.get("SLACK_MAX_CONCURRENT_REQUESTS", 3),
+    name="SLACK_MAX_CONCURRENT_REQUESTS",
+)

arcade_slack/conversation_retrieval.py

@@ -0,0 +1,74 @@
+import json
+from typing import cast
+
+from arcade_tdk.errors import RetryableToolError, ToolExecutionError
+from slack_sdk.errors import SlackApiError
+from slack_sdk.web.async_client import AsyncWebClient
+
+from arcade_slack.models import (
+    ConversationType,
+    FindChannelByNameSentinel,
+)
+from arcade_slack.utils import (
+    async_paginate,
+    extract_conversation_metadata,
+)
+
+
+async def get_conversation_by_id(
+    auth_token: str,
+    conversation_id: str,
+) -> dict:
+    """Get metadata of a conversation in Slack by the conversation_id."""
+    try:
+        slack_client = AsyncWebClient(token=auth_token)
+        response = await slack_client.conversations_info(
+            channel=conversation_id,
+            include_locale=True,
+            include_num_members=True,
+        )
+        return dict(**extract_conversation_metadata(response["channel"]))
+
+    except SlackApiError as e:
+        slack_error = cast(str, e.response.get("error", ""))
+        if "not_found" in slack_error.lower():
+            message = f"Conversation with ID '{conversation_id}' not found."
+            raise ToolExecutionError(message=message, developer_message=message)
+        raise
+
+
+async def get_channel_by_name(
+    auth_token: str,
+    channel_name: str,
+) -> dict:
+    channel_name_casefolded = channel_name.lstrip("#").casefold()
+
+    slack_client = AsyncWebClient(token=auth_token)
+
+    results, _ = await async_paginate(
+        func=slack_client.conversations_list,
+        response_key="channels",
+        types=",".join([
+            ConversationType.PUBLIC_CHANNEL.value,
+            ConversationType.PRIVATE_CHANNEL.value,
+        ]),
+        exclude_archived=True,
+        sentinel=FindChannelByNameSentinel(channel_name_casefolded),
+    )
+
+    available_channels = []
+
+    for channel in results:
+        if channel["name"].casefold() == channel_name_casefolded:
+            return dict(**extract_conversation_metadata(channel))
+        else:
+            available_channels.append({"id": channel["id"], "name": channel["name"]})
+
+    error_message = f"Channel with name '{channel_name}' not found."
+
+    raise RetryableToolError(
+        message=error_message,
+        developer_message=error_message,
+        additional_prompt_content=f"Available channels: {json.dumps(available_channels)}",
+        retry_after_ms=500,
+    )

arcade_slack/custom_types.py

@@ -1,11 +1,11 @@
 from typing import NewType
 
 
-class PositiveInt(int):
-    def __new__(cls, value: str | int, name: str = "value") -> "PositiveInt":
+class PositiveNonZeroInt(int):
+    def __new__(cls, value: str | int, name: str = "value") -> "PositiveNonZeroInt":
         def validate(val: int) -> int:
-            if val <= 0:
-                raise ValueError(f"{name} must be positive, got {val}")
+            if val < 1:
+                raise ValueError(f"{name} must be a positive non-zero integer, got {val}")
             return val
 
         try:

arcade_slack/exceptions.py

@@ -8,23 +8,3 @@ class PaginationTimeoutError(SlackToolkitError):
     def __init__(self, timeout_seconds: int):
         self.timeout_seconds = timeout_seconds
         super().__init__(f"The pagination process timed out after {timeout_seconds} seconds.")
-
-
-class ItemNotFoundError(SlackToolkitError):
-    """Raised when an item is not found."""
-
-
-class UsernameNotFoundError(SlackToolkitError):
-    """Raised when a user is not found by the username searched"""
-
-    def __init__(self, usernames_found: list[str], username_not_found: str) -> None:
-        self.usernames_found = usernames_found
-        self.username_not_found = username_not_found
-
-
-class ConversationNotFoundError(SlackToolkitError):
-    """Raised when a conversation is not found"""
-
-
-class DirectMessageConversationNotFoundError(ConversationNotFoundError):
-    """Raised when a direct message conversation searched is not found"""

arcade_slack/message_retrieval.py

@@ -0,0 +1,76 @@
+from datetime import datetime, timezone
+from typing import Any
+
+from arcade_tdk.errors import ToolExecutionError
+from slack_sdk.web.async_client import AsyncWebClient
+
+from arcade_slack.utils import (
+    async_paginate,
+    convert_datetime_to_unix_timestamp,
+    convert_relative_datetime_to_unix_timestamp,
+    enrich_message_datetime,
+)
+
+
+async def retrieve_messages_in_conversation(
+    conversation_id: str,
+    auth_token: str | None = None,
+    oldest_relative: str | None = None,
+    latest_relative: str | None = None,
+    oldest_datetime: str | None = None,
+    latest_datetime: str | None = None,
+    limit: int | None = None,
+    next_cursor: str | None = None,
+) -> dict:
+    error_message = None
+    if oldest_datetime and oldest_relative:
+        error_message = "Cannot specify both 'oldest_datetime' and 'oldest_relative'."
+
+    if latest_datetime and latest_relative:
+        error_message = "Cannot specify both 'latest_datetime' and 'latest_relative'."
+
+    if error_message:
+        raise ToolExecutionError(error_message, developer_message=error_message)
+
+    current_unix_timestamp = int(datetime.now(timezone.utc).timestamp())
+
+    if latest_relative:
+        latest_timestamp = convert_relative_datetime_to_unix_timestamp(
+            latest_relative, current_unix_timestamp
+        )
+    elif latest_datetime:
+        latest_timestamp = convert_datetime_to_unix_timestamp(latest_datetime)
+    else:
+        latest_timestamp = None
+
+    if oldest_relative:
+        oldest_timestamp = convert_relative_datetime_to_unix_timestamp(
+            oldest_relative, current_unix_timestamp
+        )
+    elif oldest_datetime:
+        oldest_timestamp = convert_datetime_to_unix_timestamp(oldest_datetime)
+    else:
+        oldest_timestamp = None
+
+    datetime_args: dict[str, Any] = {}
+    if oldest_timestamp:
+        datetime_args["oldest"] = oldest_timestamp
+    if latest_timestamp:
+        datetime_args["latest"] = latest_timestamp
+
+    slackClient = AsyncWebClient(token=auth_token)
+
+    response, next_cursor = await async_paginate(
+        slackClient.conversations_history,
+        "messages",
+        limit=limit,
+        next_cursor=next_cursor,
+        channel=conversation_id,
+        include_all_metadata=True,
+        inclusive=True,  # Include messages at the start and end of the time range
+        **datetime_args,
+    )
+
+    messages = [enrich_message_datetime(message) for message in response]
+
+    return {"messages": messages, "next_cursor": next_cursor}

arcade_slack/models.py

@@ -1,5 +1,12 @@
+import asyncio
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
 from enum import Enum
-from typing import Literal, TypedDict
+from typing import Any, Literal, TypedDict
+
+from arcade_tdk.errors import ToolExecutionError
+from slack_sdk.errors import SlackApiError
 
 from arcade_slack.custom_types import (
     SlackOffsetSecondsFromUTC,
@@ -24,6 +31,16 @@ class ConversationType(str, Enum):
     MULTI_PERSON_DIRECT_MESSAGE = "multi_person_direct_message"
     DIRECT_MESSAGE = "direct_message"
 
+    def to_slack_name_str(self) -> str:
+        mapping = {
+            ConversationType.PUBLIC_CHANNEL: ConversationTypeSlackName.PUBLIC_CHANNEL.value,
+            ConversationType.PRIVATE_CHANNEL: ConversationTypeSlackName.PRIVATE_CHANNEL.value,
+            ConversationType.MULTI_PERSON_DIRECT_MESSAGE: ConversationTypeSlackName.MPIM.value,
+            ConversationType.DIRECT_MESSAGE: ConversationTypeSlackName.IM.value,
+        }
+
+        return mapping[self]
+
 
 """
 About Slack dictionaries: Slack does not guarantee the presence of all fields for a given
@@ -204,3 +221,150 @@ class SlackConversationsToolResponse(TypedDict, total=True):
 
     conversations: list[ConversationMetadata]
     next_cursor: SlackPaginationNextCursor | None
+
+
+class PaginationSentinel(ABC):
+    """Base class for pagination sentinel classes."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        self.kwargs = kwargs
+
+    @abstractmethod
+    def __call__(self, last_result: Any) -> bool:
+        """Determine if the pagination should stop."""
+        raise NotImplementedError
+
+
+class FindUserByUsernameSentinel(PaginationSentinel):
+    """Sentinel class for finding a user by username."""
+
+    def __call__(self, last_result: Any) -> bool:
+        for user in last_result:
+            if not isinstance(user.get("name"), str):
+                continue
+            if user.get("name").casefold() == self.kwargs["username"].casefold():
+                return True
+        return False
+
+
+class FindMultipleUsersByUsernameSentinel(PaginationSentinel):
+    """Sentinel class for finding multiple users by username."""
+
+    def __init__(self, usernames: list[str]) -> None:
+        if not usernames:
+            raise ValueError("usernames must be a non-empty list of strings")
+        super().__init__(usernames=usernames)
+        self.usernames_pending = {username.casefold() for username in usernames}
+
+    def _flag_username_found(self, username: str) -> None:
+        with suppress(KeyError):
+            self.usernames_pending.remove(username.casefold())
+
+    def _all_usernames_found(self) -> bool:
+        return not self.usernames_pending
+
+    def __call__(self, last_result: Any) -> bool:
+        if not self.usernames_pending:
+            return True
+        for user in last_result:
+            username = user.get("name")
+            if not isinstance(username, str):
+                continue
+            if username.casefold() in self.usernames_pending:
+                self._flag_username_found(username)
+                if self._all_usernames_found():
+                    return True
+        return False
+
+
+class FindMultipleUsersByIdSentinel(PaginationSentinel):
+    """Sentinel class for finding multiple users by ID."""
+
+    def __init__(self, user_ids: list[str]) -> None:
+        if not user_ids:
+            raise ValueError("user_ids must be a non-empty list of strings")
+        super().__init__(user_ids=user_ids)
+        self.user_ids_pending = set(user_ids)
+
+    def _flag_user_id_found(self, user_id: str) -> None:
+        with suppress(KeyError):
+            self.user_ids_pending.remove(user_id.casefold())
+
+    def _all_user_ids_found(self) -> bool:
+        return not self.user_ids_pending
+
+    def __call__(self, last_result: Any) -> bool:
+        if not self.user_ids_pending:
+            return True
+        for user in last_result:
+            user_id = user.get("id")
+            if user_id in self.user_ids_pending:
+                self._flag_user_id_found(user_id)
+                if self._all_user_ids_found():
+                    return True
+        return False
+
+
+class FindChannelByNameSentinel(PaginationSentinel):
+    """Sentinel class for finding a channel by name."""
+
+    def __init__(self, channel_name: str) -> None:
+        super().__init__(channel_name=channel_name)
+        self.channel_name_casefold = channel_name.casefold()
+
+    def __call__(self, last_result: Any) -> bool:
+        for channel in last_result:
+            channel_name = channel.get("name")
+            if not isinstance(channel_name, str):
+                continue
+            if channel_name.casefold() == self.channel_name_casefold:
+                return True
+        return False
+
+
+class AbstractConcurrencySafeCoroutineCaller(ABC):
+    """Abstract base class for concurrency-safe coroutine callers."""
+
+    def __init__(self, func: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> None:
+        self.func = func
+        self.args = args
+        self.kwargs = kwargs
+
+    @abstractmethod
+    async def __call__(self, semaphore: asyncio.Semaphore) -> Any:
+        """Call a coroutine with a semaphore."""
+        raise NotImplementedError
+
+
+class ConcurrencySafeCoroutineCaller(AbstractConcurrencySafeCoroutineCaller):
+    """Calls a coroutine with an asyncio semaphore."""
+
+    async def __call__(self, semaphore: asyncio.Semaphore) -> Any:
+        async with semaphore:
+            return await self.func(*self.args, **self.kwargs)
+
+
+class GetUserByEmailCaller(AbstractConcurrencySafeCoroutineCaller):
+    """Call Slack's lookupByEmail method with an asyncio semaphore while handling API errors."""
+
+    def __init__(
+        self,
+        func: Callable[..., Awaitable[Any]],
+        email: str,
+    ) -> None:
+        super().__init__(func)
+        self.email = email
+
+    async def __call__(self, semaphore: asyncio.Semaphore) -> dict[str, Any]:
+        async with semaphore:
+            try:
+                user = await self.func(email=self.email)
+                return {"user": user["user"], "email": self.email}
+            except SlackApiError as e:
+                if e.response.get("error") in ["user_not_found", "users_not_found"]:
+                    return {"user": None, "email": self.email}
+                else:
+                    raise ToolExecutionError(
+                        message="Error getting user by email",
+                        developer_message=f"Error getting user by email: {e.response.get('error')}",
+                    )