botas

 90class Attachment(_CamelModel):
 91    """Bot Service attachment (images, cards, files, etc.).
 92
 93    Attributes:
 94        content_type: MIME type (e.g. ``"application/vnd.microsoft.card.adaptive"``).
 95        content_url: URL to download the attachment content.
 96        content: Inline attachment content (e.g. an Adaptive Card JSON object).
 97        name: Display name / filename.
 98        thumbnail_url: URL to a thumbnail image.
 99    """
100
101    content_type: str
102    content_url: str | None = None
103    content: Any = None
104    name: str | None = None
105    thumbnail_url: str | None = None

 96class BotApplication:
 97    """Central entry point for building a bot with the Bot Service.
 98
 99    Manages the middleware pipeline, activity handler dispatch, outbound
100    messaging via :class:`ConversationClient`, and OAuth2 token lifecycle
101    via :class:`TokenManager`.
102
103    Supports async context-manager usage for automatic resource cleanup::
104
105        async with BotApplication(options) as bot:
106            bot.on("message", my_handler)
107            ...
108
109    Attributes:
110        version: Library version string.
111        conversation_client: Client for sending outbound activities.
112        on_activity: Optional catch-all handler invoked for every activity type.
113    """
114
115    version: str = __import__("botas._version", fromlist=["__version__"]).__version__
116
117    def __init__(self, options: BotApplicationOptions = BotApplicationOptions()) -> None:
118        """Initialise the bot application.
119
120        Args:
121            options: Configuration for authentication credentials and token
122                acquisition.  Defaults to reading from environment variables.
123        """
124        self._token_manager = TokenManager(options)
125        token_provider = self._token_manager.get_bot_token
126        self.conversation_client = ConversationClient(token_provider)
127        self._middlewares: list[TurnMiddleware] = []
128        self._handlers: dict[str, ActivityHandler] = {}
129        self._invoke_handlers: dict[str, InvokeActivityHandler] = {}
130        self.on_activity: ActivityHandler | None = None
131
132    @property
133    def appid(self) -> str | None:
134        """The bot application/client ID exposed from the token manager."""
135        return self._token_manager.client_id
136
137    def on(
138        self,
139        type: str,
140        handler: ActivityHandler | None = None,
141    ) -> Any:
142        """Register a handler for an activity type.
143
144        Only one handler is stored per type; re-registering the same type
145        replaces the previous handler.
146
147        Can be used as a two-argument call or as a decorator::
148
149            bot.on('message', my_handler)
150
151            @bot.on('message')
152            async def my_handler(ctx: TurnContext):
153                await ctx.send("hello")
154
155        Args:
156            type: The activity type to handle (e.g. ``"message"``, ``"typing"``).
157            handler: Async handler function.  If omitted, returns a decorator.
158
159        Returns:
160            The ``BotApplication`` instance when called with a handler, or a
161            decorator function when called without one.
162        """
163        if handler is None:
164
165            def decorator(fn: ActivityHandler) -> ActivityHandler:
166                self._handlers[type.lower()] = fn
167                return fn
168
169            return decorator
170        self._handlers[type.lower()] = handler
171        return self
172
173    def use(self, middleware: TurnMiddleware) -> "BotApplication":
174        """Register a middleware in the turn pipeline.
175
176        Middleware executes in registration order before handler dispatch.
177        Each middleware receives ``(context, next)`` and must call ``next()``
178        to continue the pipeline, or skip it to short-circuit processing.
179
180        Args:
181            middleware: An object implementing :class:`TurnMiddleware`.
182
183        Returns:
184            The ``BotApplication`` instance for chaining.
185        """
186        self._middlewares.append(middleware)
187        return self
188
189    def on_invoke(
190        self,
191        name: str,
192        handler: InvokeActivityHandler | None = None,
193    ) -> Any:
194        """Register a handler for an invoke activity by its ``activity.name`` sub-type.
195
196        The handler must return an :class:`InvokeResponse`.  Only one handler
197        per name is supported; re-registering the same name replaces the
198        previous handler.
199
200        Can be used as a two-argument call or as a decorator::
201
202            bot.on_invoke("adaptiveCard/action", my_handler)
203
204            @bot.on_invoke("adaptiveCard/action")
205            async def my_handler(ctx): ...
206        """
207        if handler is None:
208
209            def decorator(fn: InvokeActivityHandler) -> InvokeActivityHandler:
210                self._invoke_handlers[name.lower()] = fn
211                return fn
212
213            return decorator
214        self._invoke_handlers[name.lower()] = handler
215        return self
216
217    async def process_body(self, body: str) -> InvokeResponse | None:
218        """Parse and process a raw JSON activity body.
219
220        Deserializes the JSON string into a :class:`CoreActivity`, validates
221        required fields and the ``serviceUrl``, then runs the full middleware
222        pipeline followed by handler dispatch.
223
224        For ``invoke`` activities, returns the :class:`InvokeResponse` produced
225        by the registered handler, a 200 response if no invoke handlers are
226        registered, or a 501 response if handlers exist but none match.
227        Returns ``None`` for all other activity types.
228
229        Args:
230            body: Raw JSON string representing a Bot Service activity.
231
232        Returns:
233            An :class:`InvokeResponse` for invoke activities, or ``None``.
234
235        Raises:
236            ValueError: If the JSON is malformed or required activity fields
237                are missing.
238            BotHandlerException: If the matched handler raises an exception.
239        """
240        try:
241            activity = CoreActivity.model_validate_json(body)
242        except json.JSONDecodeError as exc:
243            raise ValueError("Invalid JSON in request body") from exc
244        _assert_activity(activity)
245        _validate_service_url(activity.service_url)
246        return await self._run_pipeline(activity)
247
248    async def send_activity_async(
249        self,
250        service_url: str,
251        conversation_id: str,
252        activity: CoreActivity | dict[str, Any],
253    ) -> ResourceResponse | None:
254        """Proactively send an activity to a conversation.
255
256        Use this to push messages outside of the normal turn pipeline (e.g.
257        notifications or proactive messages).
258
259        Args:
260            service_url: The channel's service URL.
261            conversation_id: Target conversation identifier.
262            activity: The activity payload to send.
263
264        Returns:
265            A :class:`ResourceResponse` with the new activity ID, or ``None``
266            if the channel does not return one.
267        """
268        return await self.conversation_client.send_activity_async(service_url, conversation_id, activity)
269
270    async def aclose(self) -> None:
271        """Close the underlying HTTP client and release resources.
272
273        Should be called during application shutdown.  Alternatively, use the
274        bot as an async context manager to ensure automatic cleanup.
275        """
276        await self.conversation_client.aclose()
277
278    async def __aenter__(self) -> "BotApplication":
279        """Enter the async context manager."""
280        return self
281
282    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
283        """Exit the async context manager, ensuring resources are closed."""
284        await self.aclose()
285
286    async def _handle_activity_async(self, context: TurnContext) -> InvokeResponse | None:
287        if context.activity.type == "invoke":
288            return await self._dispatch_invoke_async(context)
289        handler = self.on_activity or self._handlers.get(context.activity.type.lower())
290        if handler is None:
291            return None
292        try:
293            await handler(context)
294        except Exception as exc:
295            raise BotHandlerException(
296                f'Handler for "{context.activity.type}" threw an error',
297                exc,
298                context.activity,
299            ) from exc
300        return None
301
302    async def _dispatch_invoke_async(self, context: TurnContext) -> InvokeResponse:
303        if not self._invoke_handlers:
304            return InvokeResponse(status=200, body={})
305        name = context.activity.name
306        handler = self._invoke_handlers.get(name.lower()) if name else None
307        if handler is None:
308            return InvokeResponse(status=501)
309        try:
310            return await handler(context)
311        except Exception as exc:
312            raise BotHandlerException(
313                f'Invoke handler for "{name}" threw an error',
314                exc,
315                context.activity,
316            ) from exc
317
318    async def _run_pipeline(self, activity: CoreActivity) -> InvokeResponse | None:
319        context = TurnContext(self, activity)
320        index = 0
321        invoke_response: InvokeResponse | None = None
322
323        async def next_fn() -> None:
324            nonlocal index, invoke_response
325            if index < len(self._middlewares):
326                mw = self._middlewares[index]
327                index += 1
328                await mw.on_turn(context, next_fn)
329            else:
330                invoke_response = await self._handle_activity_async(context)
331
332        await next_fn()
333        return invoke_response

16@dataclass
17class BotApplicationOptions:
18    """Configuration options for :class:`BotApplication` authentication.
19
20    All fields are optional; when ``None``, values are read from environment
21    variables (``CLIENT_ID``, ``CLIENT_SECRET``, ``TENANT_ID``,
22    ``MANAGED_IDENTITY_CLIENT_ID``).
23
24    Attributes:
25        client_id: Azure AD application (bot) ID.
26        client_secret: Azure AD client secret.
27        tenant_id: Azure AD tenant ID (defaults to ``"common"``).
28        managed_identity_client_id: Client ID for managed identity auth.
29        token_factory: Custom async callable ``(scope, tenant) -> token``
30            that bypasses MSAL entirely.
31    """
32
33    client_id: str | None = None
34    client_secret: str | None = None
35    tenant_id: str | None = None
36    managed_identity_client_id: str | None = None
37    token_factory: Callable[[str, str], Awaitable[str]] | None = None

31class BotAuthError(Exception):
32    """Raised when inbound JWT validation fails.
33
34    Inspect the message for the specific reason (expired, bad audience, etc.).
35    """
36
37    pass

68class BotHandlerException(Exception):
69    """Wraps an exception thrown inside an activity handler.
70
71    When an activity handler or invoke handler raises, the exception is
72    caught by the pipeline and re-raised as a ``BotHandlerException`` with
73    the original exception attached as ``cause`` and ``__cause__``.
74
75    Attributes:
76        name: Always ``"BotHandlerException"``.
77        cause: The original exception raised by the handler.
78        activity: The activity being processed when the error occurred.
79    """
80
81    def __init__(self, message: str, cause: BaseException, activity: CoreActivity) -> None:
82        """Initialise a BotHandlerException.
83
84        Args:
85            message: Human-readable description of the failure.
86            cause: The original exception raised by the handler.
87            activity: The activity that was being processed.
88        """
89        super().__init__(message)
90        self.name = "BotHandlerException"
91        self.cause = cause
92        self.activity = activity
93        self.__cause__ = cause

18class CardAction(_CamelModel):
19    """A clickable action button presented to the user.
20
21    Attributes:
22        type: Action type (``"imBack"``, ``"postBack"``, ``"openUrl"``, etc.).
23        title: Button label displayed to the user.
24        value: Value sent back to the bot when the button is clicked.
25        text: Text sent to the bot (for ``imBack`` actions).
26        display_text: Text displayed in the chat when the button is clicked.
27        image: URL of an icon image for the button.
28    """
29
30    type: str = "imBack"
31    title: str | None = None
32    value: str | None = None
33    text: str | None = None
34    display_text: str | None = None
35    image: str | None = None

41class ChannelAccount(_CamelModel):
42    """Represents a user or bot account on a channel.
43
44    Used for the ``from`` and ``recipient`` fields of an activity.
45
46    Attributes:
47        id: Unique account identifier on the channel.
48        name: Display name of the account.
49        aad_object_id: Azure AD object ID (when available).
50        role: Account role (``"bot"`` or ``"user"``).
51    """
52
53    id: str
54    name: str | None = None
55    aad_object_id: str | None = None
56    role: str | None = None

46class ChannelInfo(_CamelModel):
47    """Teams channel information.
48
49    Attributes:
50        id: Unique channel identifier.
51        name: Display name of the channel.
52    """
53
54    id: str | None = None
55    name: str | None = None

71class Conversation(_CamelModel):
72    """Represents a conversation (chat, channel, or group) on a channel.
73
74    Attributes:
75        id: Unique conversation identifier on the channel.
76    """
77
78    id: str

 45class ConversationClient:
 46    """Typed client for Bot Service Conversation REST API operations.
 47
 48    All methods accept a ``service_url`` and ``conversation_id`` to target
 49    the correct channel endpoint.  Authentication is handled automatically
 50    via the injected :class:`TokenProvider`.
 51    """
 52
 53    def __init__(self, get_token: TokenProvider | None = None) -> None:
 54        """Initialise the conversation client.
 55
 56        Args:
 57            get_token: Async callable that supplies a bearer token.
 58                When ``None``, requests are unauthenticated.
 59        """
 60        self._http = BotHttpClient(get_token)
 61
 62    async def send_activity_async(
 63        self,
 64        service_url: str,
 65        conversation_id: str,
 66        activity: CoreActivity | dict[str, Any],
 67    ) -> ResourceResponse | None:
 68        """Send an activity to a conversation.
 69
 70        Args:
 71            service_url: The channel's service URL.
 72            conversation_id: Target conversation identifier.
 73            activity: Activity payload (model or dict).
 74
 75        Returns:
 76            A :class:`ResourceResponse` with the new activity ID, or ``None``.
 77        """
 78        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}/activities"
 79        data = await self._http.post(
 80            service_url,
 81            endpoint,
 82            _serialize(activity),
 83            BotRequestOptions(operation_description="send activity"),
 84        )
 85        return ResourceResponse.model_validate(data) if data else None
 86
 87    async def update_activity_async(
 88        self,
 89        service_url: str,
 90        conversation_id: str,
 91        activity_id: str,
 92        activity: CoreActivity | dict[str, Any],
 93    ) -> ResourceResponse | None:
 94        """Update an existing activity in a conversation.
 95
 96        Args:
 97            service_url: The channel's service URL.
 98            conversation_id: Conversation containing the activity.
 99            activity_id: ID of the activity to update.
100            activity: Replacement activity payload.
101
102        Returns:
103            A :class:`ResourceResponse`, or ``None``.
104        """
105        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}/activities/{_encode_id(activity_id)}"
106        data = await self._http.put(
107            service_url,
108            endpoint,
109            _serialize(activity),
110            BotRequestOptions(operation_description="update activity"),
111        )
112        return ResourceResponse.model_validate(data) if data else None
113
114    async def delete_activity_async(self, service_url: str, conversation_id: str, activity_id: str) -> None:
115        """Delete an activity from a conversation.
116
117        Args:
118            service_url: The channel's service URL.
119            conversation_id: Conversation containing the activity.
120            activity_id: ID of the activity to delete.
121        """
122        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}/activities/{_encode_id(activity_id)}"
123        await self._http.delete(
124            service_url,
125            endpoint,
126            BotRequestOptions(operation_description="delete activity"),
127        )
128
129    async def get_conversation_members_async(self, service_url: str, conversation_id: str) -> list[ChannelAccount]:
130        """Retrieve all members of a conversation.
131
132        Args:
133            service_url: The channel's service URL.
134            conversation_id: Target conversation identifier.
135
136        Returns:
137            List of :class:`ChannelAccount` objects for each member.
138        """
139        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}/members"
140        data = await self._http.get(
141            service_url,
142            endpoint,
143            options=BotRequestOptions(operation_description="get conversation members"),
144        )
145        return [ChannelAccount.model_validate(m) for m in (data or [])]
146
147    async def get_conversation_member_async(
148        self, service_url: str, conversation_id: str, member_id: str
149    ) -> ChannelAccount | None:
150        """Retrieve a single conversation member by ID.
151
152        Args:
153            service_url: The channel's service URL.
154            conversation_id: Target conversation identifier.
155            member_id: The member's account ID.
156
157        Returns:
158            A :class:`ChannelAccount`, or ``None`` if the member is not found.
159        """
160        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}/members/{_encode_id(member_id)}"
161        data = await self._http.get(
162            service_url,
163            endpoint,
164            options=BotRequestOptions(operation_description="get conversation member", return_none_on_not_found=True),
165        )
166        return ChannelAccount.model_validate(data) if data else None
167
168    async def get_conversation_paged_members_async(
169        self,
170        service_url: str,
171        conversation_id: str,
172        page_size: int | None = None,
173        continuation_token: str | None = None,
174    ) -> PagedMembersResult:
175        """Retrieve conversation members with server-side pagination.
176
177        Args:
178            service_url: The channel's service URL.
179            conversation_id: Target conversation identifier.
180            page_size: Maximum members per page (channel may enforce its own limit).
181            continuation_token: Opaque token from a previous page to fetch the next.
182
183        Returns:
184            A :class:`PagedMembersResult` containing members and an optional
185            continuation token for the next page.
186        """
187        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}/pagedmembers"
188        params = {
189            "pageSize": str(page_size) if page_size else None,
190            "continuationToken": continuation_token,
191        }
192        data = await self._http.get(
193            service_url,
194            endpoint,
195            params=params,
196            options=BotRequestOptions(operation_description="get paged members"),
197        )
198        return PagedMembersResult.model_validate(data) if data else PagedMembersResult()
199
200    async def delete_conversation_member_async(self, service_url: str, conversation_id: str, member_id: str) -> None:
201        """Remove a member from a conversation.
202
203        Args:
204            service_url: The channel's service URL.
205            conversation_id: Target conversation identifier.
206            member_id: The member's account ID.
207        """
208        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}/members/{_encode_id(member_id)}"
209        await self._http.delete(
210            service_url,
211            endpoint,
212            BotRequestOptions(operation_description="delete conversation member"),
213        )
214
215    async def create_conversation_async(
216        self, service_url: str, parameters: ConversationParameters
217    ) -> ConversationResourceResponse | None:
218        """Create a new conversation on the channel.
219
220        Args:
221            service_url: The channel's service URL.
222            parameters: Conversation creation parameters (members, topic, etc.).
223
224        Returns:
225            A :class:`ConversationResourceResponse` with the new conversation
226            ID and service URL, or ``None``.
227        """
228        data = await self._http.post(
229            service_url,
230            "/v3/conversations",
231            _serialize(parameters),
232            BotRequestOptions(operation_description="create conversation"),
233        )
234        return ConversationResourceResponse.model_validate(data) if data else None
235
236    async def get_conversations_async(
237        self, service_url: str, continuation_token: str | None = None
238    ) -> ConversationsResult:
239        """List conversations the bot has participated in.
240
241        Args:
242            service_url: The channel's service URL.
243            continuation_token: Opaque token from a previous page.
244
245        Returns:
246            A :class:`ConversationsResult` with conversations and an optional
247            continuation token.
248        """
249        params = {"continuationToken": continuation_token}
250        data = await self._http.get(
251            service_url,
252            "/v3/conversations",
253            params=params,
254            options=BotRequestOptions(operation_description="get conversations"),
255        )
256        return ConversationsResult.model_validate(data) if data else ConversationsResult()
257
258    async def send_conversation_history_async(
259        self, service_url: str, conversation_id: str, transcript: Transcript
260    ) -> ResourceResponse | None:
261        """Upload a transcript of activities to a conversation's history.
262
263        Args:
264            service_url: The channel's service URL.
265            conversation_id: Target conversation identifier.
266            transcript: A :class:`Transcript` containing activities to upload.
267
268        Returns:
269            A :class:`ResourceResponse`, or ``None``.
270        """
271        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}/activities/history"
272        data = await self._http.post(
273            service_url,
274            endpoint,
275            _serialize(transcript),
276            BotRequestOptions(operation_description="send conversation history"),
277        )
278        return ResourceResponse.model_validate(data) if data else None
279
280    async def get_conversation_account_async(self, service_url: str, conversation_id: str) -> Conversation | None:
281        """Retrieve the conversation account details.
282
283        Args:
284            service_url: The channel's service URL.
285            conversation_id: Target conversation identifier.
286
287        Returns:
288            A :class:`Conversation` object, or ``None`` if not found.
289        """
290        endpoint = f"/v3/conversations/{_encode_conversation_id(conversation_id)}"
291        data = await self._http.get(
292            service_url,
293            endpoint,
294            options=BotRequestOptions(operation_description="get conversation", return_none_on_not_found=True),
295        )
296        return Conversation.model_validate(data) if data else None
297
298    async def aclose(self) -> None:
299        """Close the underlying HTTP client and release resources."""
300        await self._http.aclose()