graphplug 0.2.0__py3-none-any.whl

graphplug/_resources/mail.py

@@ -0,0 +1,196 @@
+"""Mail.
+
+The point of this module is ``send``. Graph's ``sendMail`` payload is the most awkward thing in the
+API to hand-build: recipients are objects inside objects, the body carries a content type, and an
+attachment is a base64 blob with an ``@odata.type`` discriminator. Roughly twenty lines of nested
+JSON become one call.
+"""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, AsyncIterator, Dict, Iterable, List, Optional, Sequence, Union
+
+from .._errors import GraphError
+from .._request import segment
+from .._scopes import Scopes
+from .base import GraphResource
+
+__all__ = ["Mail"]
+
+Recipients = Union[str, Sequence[str], None]
+
+
+def _recipients(value: Recipients) -> List[Dict[str, Any]]:
+    """One address or many, either way in the shape Graph expects."""
+    if not value:
+        return []
+    addresses = [value] if isinstance(value, str) else list(value)
+    return [{"emailAddress": {"address": address}} for address in addresses]
+
+
+def _attachment(path: Union[str, Path]) -> Dict[str, Any]:
+    source = Path(path)
+    if not source.is_file():
+        raise GraphError(0, "invalidRequest", f"attachment '{source}' does not exist")
+
+    content_type = mimetypes.guess_type(source.name)[0] or "application/octet-stream"
+    return {
+        "@odata.type": "#microsoft.graph.fileAttachment",
+        "name": source.name,
+        "contentType": content_type,
+        "contentBytes": base64.b64encode(source.read_bytes()).decode("ascii"),
+    }
+
+
+class Mail(GraphResource):
+    """Messages in the signed-in user's mailbox."""
+
+    path = "/me/messages"
+    scopes = Scopes.combine(Scopes.MAIL_READ_WRITE, Scopes.MAIL_SEND)
+
+    #: Graph rejects a message above roughly this size; beyond it an upload session is needed.
+    MAX_ATTACHMENT_BYTES = 3 * 1024 * 1024
+
+    # ── sending ──────────────────────────────────────────────────────────────
+
+    def compose(
+        self,
+        to: Recipients,
+        subject: str,
+        body: str = "",
+        cc: Recipients = None,
+        bcc: Recipients = None,
+        html: bool = False,
+        attachments: Optional[Iterable[Union[str, Path]]] = None,
+        reply_to: Recipients = None,
+    ) -> Dict[str, Any]:
+        """Build the message payload without sending it.
+
+        Exposed because it is useful on its own -- for drafts, for batching, and for seeing exactly
+        what would go on the wire.
+        """
+        if not to:
+            raise GraphError(0, "invalidRequest", "'to' is required")
+
+        message: Dict[str, Any] = {
+            "subject": subject,
+            "body": {"contentType": "HTML" if html else "Text", "content": body},
+            "toRecipients": _recipients(to),
+        }
+        if cc:
+            message["ccRecipients"] = _recipients(cc)
+        if bcc:
+            message["bccRecipients"] = _recipients(bcc)
+        if reply_to:
+            message["replyTo"] = _recipients(reply_to)
+
+        if attachments:
+            built = [_attachment(path) for path in attachments]
+            total = sum(len(item["contentBytes"]) for item in built)
+            if total > self.MAX_ATTACHMENT_BYTES:
+                raise GraphError(
+                    0,
+                    "invalidRequest",
+                    f"attachments total {total} bytes; Graph rejects a message this large. "
+                    "Upload to OneDrive and send a link instead.",
+                )
+            message["attachments"] = built
+
+        return message
+
+    async def send(
+        self,
+        to: Recipients,
+        subject: str,
+        body: str = "",
+        cc: Recipients = None,
+        bcc: Recipients = None,
+        html: bool = False,
+        attachments: Optional[Iterable[Union[str, Path]]] = None,
+        reply_to: Recipients = None,
+        save_to_sent: bool = True,
+    ) -> None:
+        """Send a message. Returns nothing -- Graph answers ``sendMail`` with 202 and no body."""
+        await self._collection_action("sendMail", {
+            "message": self.compose(to, subject, body, cc, bcc, html, attachments, reply_to),
+            "saveToSentItems": save_to_sent,
+        })
+
+    async def send_many(self, messages: Sequence[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Send many messages in as few round-trips as Graph allows.
+
+        Each entry is the keyword arguments ``send`` takes. Twenty go per round-trip, and the
+        batches run concurrently. Per-message failures come back in the results rather than
+        raising, so check each ``status``.
+        """
+        requests = []
+        for fields in messages:
+            fields = dict(fields)
+            save = fields.pop("save_to_sent", True)
+            requests.append({
+                "method": "POST",
+                "url": "/me/sendMail",
+                "headers": {"Content-Type": "application/json"},
+                "body": {"message": self.compose(**fields), "saveToSentItems": save},
+            })
+        return await self._client.batch(requests)
+
+    # ── replying ─────────────────────────────────────────────────────────────
+
+    async def reply(self, message_id: str, comment: str = "", reply_all: bool = False) -> None:
+        await self._action(message_id, "replyAll" if reply_all else "reply", {"comment": comment})
+
+    async def forward(self, message_id: str, to: Recipients, comment: str = "") -> None:
+        await self._action(message_id, "forward", {
+            "comment": comment,
+            "toRecipients": _recipients(to),
+        })
+
+    # ── reading ──────────────────────────────────────────────────────────────
+
+    def inbox(
+        self,
+        unread_only: bool = False,
+        since: Optional[datetime] = None,
+        search: Optional[str] = None,
+        top: int = 50,
+        select: str = "id,subject,from,receivedDateTime,isRead,hasAttachments",
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Walk the inbox newest first, narrowed however you like."""
+        options: Dict[str, Any] = {"select": select, "top": top}
+
+        # Graph refuses $orderby on a property that does not also lead $filter (InefficientFilter),
+        # so receivedDateTime comes first, and is bounded by nothing when there is no `since`.
+        filters = []
+        if since is not None:
+            moment = since if since.tzinfo else since.replace(tzinfo=timezone.utc)
+            filters.append(f"receivedDateTime ge {moment.astimezone(timezone.utc):%Y-%m-%dT%H:%M:%SZ}")
+        if unread_only:
+            if not filters:
+                filters.append("receivedDateTime ge 1900-01-01T00:00:00Z")
+            filters.append("isRead eq false")
+        if filters:
+            options["filter"] = " and ".join(filters)
+
+        if search:
+            # Graph forbids $search with $filter or $orderby, so search wins and the rest goes.
+            options = {"select": select, "top": top, "search": f'"{search}"'}
+        else:
+            options["orderby"] = "receivedDateTime desc"
+
+        return self._client.paged("/me/mailFolders/inbox/messages", **options)
+
+    async def mark_read(self, message_id: str, read: bool = True) -> Dict[str, Any]:
+        return await self.update(message_id, {"isRead": read})
+
+    async def move(self, message_id: str, folder: str) -> Dict[str, Any]:
+        """Move to a named well-known folder, or to a folder id."""
+        return await self._action(message_id, "move", {"destinationId": folder})
+
+    async def delete_many(self, message_ids: Sequence[str]) -> List[Dict[str, Any]]:
+        requests = [{"method": "DELETE", "url": f"{self.path}/{segment(i)}"} for i in message_ids]
+        return await self._client.batch(requests)

graphplug/_resources/teams.py

@@ -0,0 +1,146 @@
+"""Teams: channels, channel messages and chats.
+
+The job people actually want here is "post this into that channel", and Graph makes it a two-level
+lookup before you can: a team id, then a channel id, then a message whose text has to be wrapped in
+a body object with a content type. ``post`` is that, in one call.
+
+Chats and channels are different endpoints with the same message shape, so both are here and the
+shape is built once.
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Optional
+
+from .._errors import GraphError
+from .._scopes import Scopes
+from .base import GraphResource
+
+__all__ = ["Teams"]
+
+DEFAULT_FIELDS = "id,displayName,description"
+
+MESSAGE_FIELDS = "id,createdDateTime,from,body,importance"
+
+_IMPORTANCE = ("normal", "high", "urgent")
+
+
+def _message(text: str, html: bool, subject: Optional[str], importance: str) -> Dict[str, Any]:
+    """The chatMessage shape, which channel posts, replies and chats all share."""
+    if not text:
+        raise GraphError(0, "invalidRequest", "'message' is required")
+    if importance not in _IMPORTANCE:
+        raise GraphError(
+            0, "invalidRequest", f"'importance' must be one of {', '.join(_IMPORTANCE)}"
+        )
+
+    payload: Dict[str, Any] = {
+        "body": {"contentType": "html" if html else "text", "content": text},
+    }
+    if subject:
+        payload["subject"] = subject
+    if importance != "normal":
+        payload["importance"] = importance
+    return payload
+
+
+class Teams(GraphResource):
+    """Teams, their channels, and the messages in both.
+
+    Delegated access only in practice. Reading channel messages with *application* permissions is
+    one of Graph's protected APIs: Microsoft has to approve the app first, and until they do the
+    call returns 403 no matter what consent the tenant has granted. Posting as a user works
+    normally.
+    """
+
+    path = "/teams"
+    scopes = Scopes.combine(Scopes.TEAM_READ_BASIC, Scopes.CHANNEL_MESSAGE_SEND)
+
+    # ── finding your way ─────────────────────────────────────────────────────
+
+    def mine(self, select: str = DEFAULT_FIELDS) -> AsyncIterator[Dict[str, Any]]:
+        """Teams the signed-in person belongs to."""
+        return self._client.paged("/me/joinedTeams", select=select)
+
+    def channels(
+        self, team_id: str, select: str = DEFAULT_FIELDS
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Channels in a team."""
+        return self._client.paged(f"/teams/{team_id}/channels", select=select)
+
+    async def channel_by_name(self, team_id: str, name: str) -> Dict[str, Any]:
+        """Find a channel by its display name, so a caller need not carry channel ids around."""
+        async for channel in self.channels(team_id):
+            if channel.get("displayName", "").casefold() == name.casefold():
+                return channel
+        raise GraphError(0, "itemNotFound", f"team '{team_id}' has no channel named '{name}'")
+
+    def members(self, team_id: str) -> AsyncIterator[Dict[str, Any]]:
+        """Who is in a team."""
+        return self._client.paged(f"/teams/{team_id}/members")
+
+    # ── channel messages ─────────────────────────────────────────────────────
+
+    async def post(
+        self,
+        team_id: str,
+        channel_id: str,
+        message: str,
+        html: bool = False,
+        subject: Optional[str] = None,
+        importance: str = "normal",
+    ) -> Dict[str, Any]:
+        """Post a message to a channel. Returns the created message, including its id."""
+        return await self._client.post(
+            f"/teams/{team_id}/channels/{channel_id}/messages",
+            body=_message(message, html, subject, importance),
+        )
+
+    async def reply(
+        self,
+        team_id: str,
+        channel_id: str,
+        message_id: str,
+        message: str,
+        html: bool = False,
+    ) -> Dict[str, Any]:
+        """Reply in an existing channel thread.
+
+        Graph has no "reply to a reply": every reply attaches to the thread's root message, so
+        ``message_id`` is the id ``post`` returned.
+        """
+        return await self._client.post(
+            f"/teams/{team_id}/channels/{channel_id}/messages/{message_id}/replies",
+            body=_message(message, html, None, "normal"),
+        )
+
+    def messages(
+        self, team_id: str, channel_id: str, top: int = 50, select: str = MESSAGE_FIELDS
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Walk a channel's messages, newest first.
+
+        Replies are not included; they hang off each message's own ``replies`` collection.
+        """
+        return self._client.paged(
+            f"/teams/{team_id}/channels/{channel_id}/messages", select=select, top=top
+        )
+
+    # ── chats ────────────────────────────────────────────────────────────────
+
+    def chats(self, select: str = "id,topic,chatType,lastUpdatedDateTime") -> AsyncIterator[Dict[str, Any]]:
+        """The signed-in person's chats.
+
+        Unordered: Graph sorts chats only by ``lastMessagePreview/createdDateTime``, and refuses
+        ``$orderby`` on anything else.
+        """
+        return self._client.paged("/me/chats", select=select)
+
+    async def send_chat(self, chat_id: str, message: str, html: bool = False) -> Dict[str, Any]:
+        """Send a message into an existing chat.
+
+        Starting a *new* chat is a different call -- POST ``/chats`` with its members -- and is
+        deliberately not wrapped here until something needs it.
+        """
+        return await self._client.post(
+            f"/chats/{chat_id}/messages", body=_message(message, html, None, "normal")
+        )

graphplug/_resources/users.py

@@ -0,0 +1,121 @@
+"""People and the directory.
+
+Two things make this endpoint awkward, and both live here rather than at the call site.
+
+The first is that the signed-in person is ``/me`` while everyone else is ``/users/{id}``, so every
+directory call has a fork in it. ``_who`` closes it: pass nobody and you get yourself.
+
+The second is that Graph refuses its own most useful queries -- ``$search``, ``$count``,
+``endswith``, ``$filter`` combined with ``$orderby`` -- unless the request carries
+``ConsistencyLevel: eventual``. Without it the failure is a bare 400 that names none of this.
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Optional
+
+from .._errors import GraphError
+from .._request import segment
+from .._scopes import Scopes
+from .base import GraphResource
+
+__all__ = ["Users"]
+
+#: What Graph calls an advanced query. Cheap to send, and the queries below do not work without it.
+ADVANCED_QUERY = {"ConsistencyLevel": "eventual"}
+
+DEFAULT_FIELDS = "id,displayName,mail,userPrincipalName,jobTitle,department"
+
+
+class Users(GraphResource):
+    """People in the directory, and the signed-in person.
+
+    Works under both access models. Under application-level access ``/me`` does not exist, so the
+    methods that default to it need a user id.
+    """
+
+    path = "/users"
+    scopes = Scopes.USER_READ_ALL
+
+    @staticmethod
+    def _who(user: Optional[str]) -> str:
+        """``/me`` for the signed-in person, ``/users/{id}`` for anyone else."""
+        if user is None or user == "me":
+            return "/me"
+        return f"/users/{segment(user)}"
+
+    # ── the signed-in person ─────────────────────────────────────────────────
+
+    async def me(self, select: str = DEFAULT_FIELDS) -> Dict[str, Any]:
+        """Who am I. Delegated access only -- there is no user under app permissions."""
+        return await self._client.get("/me", select=select)
+
+    # ── finding someone ──────────────────────────────────────────────────────
+
+    def find(
+        self, query: str, top: int = 25, select: str = DEFAULT_FIELDS
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Search names and addresses for a fragment.
+
+        Graph's ``$search`` on users matches per field, so the term is applied to both the display
+        name and the mail address -- searching "smith" should find someone whether it is their
+        surname or their address.
+        """
+        if not query:
+            raise GraphError(0, "invalidRequest", "'query' is required")
+
+        term = query.replace('"', "")
+        return self._client.paged(
+            self.path,
+            headers=dict(ADVANCED_QUERY),
+            search=f'"displayName:{term}" OR "mail:{term}"',
+            select=select,
+            top=top,
+        )
+
+    async def by_email(self, address: str, select: str = DEFAULT_FIELDS) -> Dict[str, Any]:
+        """Look someone up by address.
+
+        Not the same as ``get(address)``: that resolves the *user principal name*, which is often
+        but not always the mail address. This filters on ``mail`` itself and raises if nobody
+        matches, so a wrong answer is not silently returned.
+        """
+        quoted = address.replace("'", "''")  # OData's escape; o'brien@ is a valid address
+        page = await self._client.get(
+            self.path, filter=f"mail eq '{quoted}'", select=select, top=2
+        )
+        found = (page or {}).get("value", [])
+        if not found:
+            raise GraphError(0, "itemNotFound", f"no user has the mail address '{address}'")
+        return found[0]
+
+    # ── the org chart ────────────────────────────────────────────────────────
+
+    async def manager(self, user: Optional[str] = None) -> Dict[str, Any]:
+        """Who this person reports to. Raises ``itemNotFound`` if nobody is set."""
+        return await self._client.get(f"{self._who(user)}/manager")
+
+    def reports(
+        self, user: Optional[str] = None, select: str = DEFAULT_FIELDS
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Who reports to this person, directly."""
+        return self._client.paged(f"{self._who(user)}/directReports", select=select)
+
+    def groups(
+        self, user: Optional[str] = None, select: str = "id,displayName,mail,groupTypes"
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Every group this person belongs to, directly."""
+        return self._client.paged(f"{self._who(user)}/memberOf", select=select)
+
+    # ── photo ────────────────────────────────────────────────────────────────
+
+    async def photo(
+        self, dest_path: str, user: Optional[str] = None, size: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Save a profile photo to disk.
+
+        ``size`` is one of Graph's fixed sizes such as ``"96x96"``; omit it for the original. A
+        person with no photo is a 404, which arrives as ``GraphError`` with ``itemNotFound``.
+        """
+        endpoint = f"{self._who(user)}/photo" if not size else f"{self._who(user)}/photos/{size}"
+        return await self._client.download(f"{endpoint}/$value", dest_path)

graphplug/_scopes.py

@@ -0,0 +1,56 @@
+"""Named Graph permissions.
+
+Plug and play means not having to know that sending mail needs ``Mail.Send``. Each resource
+declares the scopes it uses, so a client can be built from the resources you intend to touch and a
+missing permission produces an error that names what to grant.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Tuple
+
+__all__ = ["Scopes"]
+
+
+class Scopes:
+    """Delegated permission names, grouped by what you are trying to do."""
+
+    # Identity
+    USER_READ: Tuple[str, ...] = ("User.Read",)
+    USER_READ_ALL: Tuple[str, ...] = ("User.Read.All",)
+
+    # Mail
+    MAIL_READ: Tuple[str, ...] = ("Mail.Read",)
+    MAIL_READ_WRITE: Tuple[str, ...] = ("Mail.ReadWrite",)
+    MAIL_SEND: Tuple[str, ...] = ("Mail.Send",)
+
+    # Calendar
+    CALENDARS_READ: Tuple[str, ...] = ("Calendars.Read",)
+    CALENDARS_READ_WRITE: Tuple[str, ...] = ("Calendars.ReadWrite",)
+
+    # Files
+    FILES_READ: Tuple[str, ...] = ("Files.Read",)
+    FILES_READ_WRITE: Tuple[str, ...] = ("Files.ReadWrite",)
+    #: Other people's drives and SharePoint document libraries, not just your own.
+    FILES_READ_WRITE_ALL: Tuple[str, ...] = ("Files.ReadWrite.All",)
+
+    # Teams
+    TEAM_READ_BASIC: Tuple[str, ...] = ("Team.ReadBasic.All",)
+    CHANNEL_MESSAGE_SEND: Tuple[str, ...] = ("ChannelMessage.Send",)
+    #: Reading channel messages is a protected API: Microsoft must approve the app first.
+    CHANNEL_MESSAGE_READ: Tuple[str, ...] = ("ChannelMessage.Read.All",)
+    CHAT_READ_WRITE: Tuple[str, ...] = ("Chat.ReadWrite",)
+
+    #: Everything the built-in resources can use. Convenient for a first run; narrow it afterwards.
+    EVERYTHING: Tuple[str, ...] = (
+        "User.Read", "User.Read.All",
+        "Mail.ReadWrite", "Mail.Send",
+        "Calendars.ReadWrite",
+        "Files.ReadWrite",
+        "Team.ReadBasic.All", "ChannelMessage.Send", "Chat.ReadWrite",
+    )
+
+    @staticmethod
+    def combine(*groups: Sequence[str]) -> Tuple[str, ...]:
+        """Merge scope groups, keeping order and dropping duplicates."""
+        return tuple(dict.fromkeys(scope for group in groups for scope in group))